CQL++ Installation

Introduction

Installation of CQL++ requires the following basic steps:

Creating the destination directories
Unpacking the distribution files into the destination directories
Modifying the makefiles (if target system is not directly supported, or if directory names need to be changed)
Compiling
For client/server versions, adding the appropriate entries to the hosts and services files
Running the bigt test program to verify basic operation

In these instructions, we are assuming that you have copied the contents of the distribution media onto your local system. Thus, the instructions for installation are the same whether you receive DOS format diskettes, tar format diskettes, or tar format tape.

Files are distributed in compressed archives. Files are extracted from these archives using the program xarc. Source files are provided to compile the xarc program. An executable version, xarc.exe, is provided for Microsoft (intel) environments.

Environments which are directly supported include a batch (.bat or .cmd) or shell script file for installation. The issues described below will be automatically taken care of by the batch or shell script file. The following more detailed instructions are supplied for environments which are not directly supported. If you are installing for one of the directly supported environments, go directly to the installation instructions for that environment:

Installing for Environments Not Directly Supported

The distribution files include a makefile for compiling xarc. For System V UNIX environments, simple enter make. For BSD UNIX environments, enter make OPTION='-D__BSD__'

xarc is run in one of two ways, either
xarc ArchiveName

or
xarc ArchiveName -r

Here, ArchiveName represents one of the actual archive names (described below).

The source files are stored in the archives in UNIX format, with line feeds but without carriage returns. When run with the -r switch, xarc inserts carriage returns into the extracted files. Thus, -r should be used in DOS, OS/2, VMS, and in other environments which require carriage returns.

Directories

Create a directory for the CQL++ source files (for example, cql81. In this directory, create the following subdirectories:

app: C++ source files for test programs.
data: Data directory for test database.
doc: Documentation directory for HTML files.
include: Header files used by several subsystems.
common: C++ source files used by several subsystems.
isam: C++ source files for the ISAM subsystem.
isam.client (isamclie for FAT file systems): C++ source files for the ISAM client side library (client/server version only).
isam.server (isamserv for FAT file systems): C++ source files for the ISAM server (client/server version only).
odbc: Directory for building ODBC driver (Windows environments only).
pp: C++ source files for the SQL preprocessor.
sql: C++ source files for the SQL subsystem.
sql.server (sqlserve for FAT file systems): C++ source files for the SQL server process (client/server version only).
script: SQL script files.

Archives

Most of the archives have the same names as the directories. In some cases, we've changed the names to keep all the archive names within the limits of a filename on a DOS disk. The names are the archives are:

app: source files for app directory
app.bc: app files specific to Borland C
app.lin: app files specific to LINUX
app.nt: app files specific to Windows NT with Visual C++
app.os2: app files specific to OS/2
app.sgi: app files specific to Silicon Graphics
app.sun: app files specific to Sun
common: source files for common directory
common.bc: common files specific to Borland C
common.lin: common files specific to LINUX
common.nt: common files specific to Windows NT/Visual C++
common.os2: common files specific to OS/2
common.sgi: common files specific to Silicon Graphics
common.sun: common files specific to Sun
doc: HTML files for CQL++ manual
include: header files for include directory
include.bc: include files specific to Borland C
include.lin: include files specific to LINUX
include.nt: include files specific to Windows NT and Visual C++
include.os2: include files specific to OS/2
include.sgi: include files specific to Silicon Graphics
include.sun: include files specific to sun
isam: source files for isam directory
isam.bc: isam files specific to Borland C
isam.lin: isam files specific to LINUX
isam.nt: isam files specific to Windows NT/Visual C++
isam.os2: isam files specific to OS/2
isam.sgi: isam files specific to Silicon Graphics
isam.sun: isam files specific to Sun
isamclie: source files for isam.client directory
isamclie.bc: isam.client files specific to Borland C
isamclie.lin: isam.client files specific to LINUX
isamclie.nt: isam.client files specific to Windows NT/Visual C++
isamclie.os2: isam.client files specific to OS/2
isamclie.sgi: isam.client files specific to Silicon Graphics
isamclie.sun: isam.client files specific to Sun
isamserv: source files for isam.server directory
isamserv.bc: isam.server files specific to Borland C
isamserv.lin: isam.server files specific to LINUX
isamserv.nt: isam.server files specific to Windows NT/Visual C++
isamserv.os2: isam.server files specific to OS/2
isamserv.sgi: isam.server files specific to Silicon Graphics
isamserv.sun: isam.server files specific to Sun
odbc: ODBC files
odbc16: ODBC files for making 16 bit driver
pp: preprocessor related files
scripts: SQL script files for creating test tables
sql: source files for SQL directory
sql.bc: sql files specific to Borland C
sql.lin: sql files specific to LINUX
sql.nt: sql files specific to Windows NT/Visual C++
sql.os2: sql files specific to OS/2
sql.sgi: sql files specific to Silicon Graphics
sql.sun: sql files specific to Sun
sqlserve: sql server source files
sqlserve.bc: sql server files specific to Borland C
sqlserve.lin: sql server files specific to LINUX
sqlserve.nt: sql server files specific to Windows NT/Visual C++
sqlserve.os2: sql server files specific to OS/2
sqlserve.sgi: sql server files specific to Silicon Graphics
sqlserve.sun: sql server files specific to Sun

The general procedure is to extract into an archive the files for that archive, followed by the environment specific files for that archive. For new environments, the best procedure is to select the closest supported environment and make whatever modifications are necessary.

For example, to install for LINUX:

Extract the include archive into the include directory.
Extract the linux specific include files from archive include.lin into the include directory.
Extract the common archive into the common directory.
Extract the linux specific common files from archive common.lin into the common directory.
Extract the .html files from archive doc into the doc directory.
Extract the isam archive into the isam directory.
Extract the linux specific isam files from archive isam.lin into the isam directory.
Extract the isamclie archive into the isam.client directory.
Extract the linux specific isam.client files from archive isamclie.lin into the isam.client directory.
Extract the sql archive into the sql directory.
Extract the linux specific sql files from archive sql.lin into the sql directory.
Extract the sqlserve archive into the sql.server directory.
Extract the linux specific sql server files from archive sqlserve.lin into the sql.server directory.

Note that there are some source files which aren't referenced in the makefiles. These are .y and .l files; input to GNU Bison and Flex, respectively. Bison (GNU's version of YACC) and Flex (GNU's version of lex) are code generators which produce .c source files. There are two sets; one set for the SQL server parser, and one set for the SQL preprocessor parser. You do not need to use these files to compile the system, as the generated .c files are already in the directory. The files are included in case you wish to modify the source files to change the behavior of one of the parsers. The generated .c files have to be compiled as c++ files.

Some compilers have difficulty treating files with a .c extension as c++ files; if this is the case, it may be necessary to rename the files to .cxx or .C. For supported compilers, .cxx or .C files are included where necessary.

Some make utilities have built in rules for translating .y and .l files. If this occurs, the make utility may attempt to run yacc and/or lex, and may generate files which overwrite files supplied by us in the sql or pp directories. If this occurs, erase (or move) the .y and .l files. (You can always recover the original files from the archives on the master media.)

Modifying Makefiles

If the environment is directly supported, there is a makefile supplied for each directory. For environments which are not directly supported, there are template makefiles for use as models. These makefiles use the compilation commands for the GNU compiler g++. Generally, all you need to do is to change the command g++ to the appropriate command for your system.

Some directories have two makefiles, one for client/server operation and one for single user operation. Directories which are only used in client/server operation have only one makefile. If there are two makefiles, they have the names makefile.su (for single user) and makefile.cs for client/server. If there is only one template makefile, it is named makefile.in. Copy the appropriate makefile to makefile. For example, if you are compiling for client/server and are compiling the isam directory, copy makefile.cs to makefile. Make the necessary changes to makefile.

The makefile templates are designed for use with the GNU make utility. If you use another make utility, there are some features in the template makefiles which may be new to you. Also, there are some macros whose meaning may not be obvious. This list describes them.

The newer, and more correct, form of dependency rule is used. For example:
%.o: %.cxx
$(CC) $<
Some make utilities do not understand this, requiring instead the old form of a dependency rule:
.c.o:
$(CC) $<
There is a directive, vpath, used in GNU makefiles to specify the location of source files which may not be in the current directory. For example, in the template makefile for the isam.server (or isamserv) directory, the following directive appears:
vpath %.cxx ../isam.client:../isam:../common
This tells the make utility that .cxx files which are not in the current directory should be searched for in directories ../isam.client, ../isam, and ../common (in that order). Note that the directory names are separated by colons, UNIX style, and not by semicolons, brain dead operating system style.
For environments where the GNU make utility is not available, or if for some reason you do not wish to use it, you may need to add specific dependency lines in the makefile for each source file that is not in the current directory. For example,
cqobject.o: ../isam.client/cqobject.cxx
There is another directive, .PHONY, which may be unfamiliar. It provides a list of targets which are not actually things to be made. For example,
.PHONY=all
Most make utilities tolerate phony targets without special handling, so if your make utility doesn't understand .PHONY, you can usually remove it.
The template makefiles also use the UNIX ar command to build libraries, followed by the ranlib utility. Some UNIX systems do not require the use of ranlib, although they will typically just give you a message that it is unnecessary (without aborting the make). On non-UNIX systems, the library program will have a different name and the format for making a library in the makefile vill vary. Samples can be found in the OS/2, Windows NT, and Borland C makefiles.
The makefiles which include link statements have a variable, OSLIBRARIES. The setting of this variable in the template may or may not be appropriate for your system. The setting is usually /usr/lib/libm.sa which is appropriate for some, but not all, UNIX systems. The suffix .sa means shared library. If your system does not support shared libraries, you will need to use /usr/lib/libm.a.
This library reference is needed for systems where floating point functions are not automatically linked in by the linker. If you get undefined externals for floating point functions (typically sqrt), then a reference to the systems math library is required.
We generally use the maximum warning level with whichever compiler we are working with. Any warning specifications in the template makefiles may be removed. You should not get any warning messages when compiling CQL++; if you do, call us.

Compilation

For single user operation, compile the directories in the following sequence:

common
isam
sql
app

For client/server operation, compile the directories in the following sequence:

common
isam
isam.client
isam.server
sql
app
sql.server

After completion of compilation, executable file cqinterp or cqinterp.exe is available in the sql directory. This is the SQL command line interpreter. Test program bigt or bigt.exe is available in the app directory.

For client/server operation, ISAM server executable cqserver or cqserver.exe is available in the isam.server directory. SQL server daemon cqdaemon or cqdaemon.exe is available in the sql.server directory. Executable cqsqlsrv or cqsqlsrv.exe is available in the sql.server directory, to be started automatically by cqdaemon each time an ODBC or SQL server connection occurs.

Creating the Test Database

Test program bigt expects the existence of a test database. An SQL script is provided to create the test database. This script is called newstuff. To create the test database:

Change to the data directory. Delete all files in this directory.
Run cqinterp
Execute the script using the command @'../scripts/newstuff'

Running the Test Program

With data as the current directory, run test program bigt. bigt displays a message as it completes each test. If an error is detected, bigt prints an error message and aborts. If all tests complete correctly, the final message is test 67 passed. This verifies basic CQL++ functionality. The user can view files bigt1.cxx, bigt2.cxx, bigt3.cxx, bigt4.cxx, bigt5.cxx, and bigt6.cxx to see the functionality verified by bigt and to see many examples of the use of the CQL++ API.

Client/Server Setup

There are three directories related to client/server opration. Note that we use shorter directory names in Windows and OS/2. If you are using the NTFS in Windows NT, or the HPFS in OS/2, you can use the longer names.

The client/server directories are (short names in parentheses):

isam.client (isamclie): Includes files used on the client side during ISAM server operation. Some of these files are also used on the server side.
isam.server (isamserv): Includes files used exclusively on the server side to make the ISAM server executable cqserver (cqservew for windows) and cqstop.
sql.server (sqlserve): Includes files to make the server side SQL executable cqsqlsrv

and the daemon executable cqdaemon

The Client/Server Operation section describes the uses of these executables. This section also describes the additions to the hosts and services TCP/IP files required to run the ISAM and SQL server processes.

ODBC Compilation Issues

There is a define in cqsqlsrv.h, __DUMB_DOWN_TO_MICROSOFT_ACCESS__, which also appears in ODBC driver file cqsqlsys.h. This turns off some correct ODBC behavior which Microsoft Access does not understand. Hopefully, we'll be able to remove these when Microsoft fixes Access. Note that updates may exist after this was written, so you may wish to test your version of access with the #define removed.

If you compile the ODBC driver as a 16 bit DLL with the Microsoft compiler, you must use the -Gt0 flag. This makes all external data far data.

ODBC INI Variables

The initial settings of the ODBC INI variables are created by the ODBC installation program. The use of each variable is explained here.

The ODBC entries may be in the ODBC.INI file (for Windows 3.11) or in the registry (for Windows NT). The ODBC setup routine called by the ODBC driver manager is used to modify the values. When the ODBC setup routine is used, the actual location of the INI values is transparent to the user.

The following variables are defined for the ODBC driver:

Service: This is the name of the service, which translates to a number that allows the ODBC client to connect to the server. The name is initially set to CQL. On the server side, the name is set by the compile time define __CQL_SQL_SERVER_SERVICE_NAME__ in cqoption.h in the include directory. The services file on each side must specify the same port number for this service. More information about the services file is in the Client/Server Operation section.
User1: You can specify as many User variables as you like. They are used to set up the dialog box used by SQLDriverConnect. The driver looks for User1, User2, User3, etc. When a UserN is not found, the driver stops looking for user names, so there can be no gap in the user numbers. That is, you can have User1, User2, and User3, but you cannot have User1, User2, and User4 (User4 would be ignored). The User variables are ignored if you use SQLConnect instead of SQLDriverConnect.
Driver: This is the physical location of the DLL, called CQLODBC.DLL. In Windows NT, all ODBC drivers must be 32 bit drivers and the INI variable is Driver. In Windows 3.x, the INI variable needs to be Driver32 for a 32 bit driver and Driver for a 16 bit driver. In the 16 bit environment, both the 16 and 32 bit drivers can be included in the same INI file.

There are other entries in the INI file, although they should rarely be changed. For Windows NT, a line is added to the ODBC DATA SOURCES section. For Windows 3.x, a line is added to the ODBC DATA SOURCES and/or to the ODBC 32 BIT DATA SOURCES section.

Microsoft uses what it calls "thunking" layers which allow 16 bit apps to use 32 bit drivers and v.v. (Note: Windows NT can only "thunk" in one direction. That is, 16 bit apps can use 32 bit drivers, but 32 bit apps cannot use 16 bit drivers.) In Windows 3.x, it is important to put the driver in the correction section (ODBC DATA SOURCES or ODBC 32 BIT DATA SOURCES) and to use the correct INI variable name (Driver or Driver32). This will prevent the ODBC driver manager from inappropriately using a "thunking" layer.

Installation with Microsoft VC++

Windows NT installation uses the batch file install.bat. To install, perform the following steps:

Create a root directory for CQL, for example, cql81.
Under the root directory, create a subdirectory called dist.
Copy all files from the distribution disks into the dist directory.
Run the batch program as follows: install nt

Proceed to compilation.

Installation with Borland C++

Borland C++ installation uses the batch file install.bat. To install, perform the following steps:

Create a root directory for CQL, for example, cql81.
Under the root directory, create a subdirectory called dist.
Copy all files from the distribution disks into the dist directory.
Run the batch program as follows: install bc

Proceed to compilation.

Installation for OS/2

OS/2 installation uses the batch file install.cmd. To install, perform the following steps:

Create a root directory for CQL, for example, cql81.
Under the root directory, create a subdirectory called dist.
Copy all files from the distribution disks into the dist directory.
Run the batch program as follows: install

Proceed to compilation.

Installation for SUN

Sun installation uses a shell script install.sun. Note that this is a Bourne shell script, not a c-shell script. It can be run under the Bourne shell, the Korn shell, or the GNU bash shell. To install, perform the following steps:

Create a root directory for CQL, for example, cql81.
Under the root directory, create a subdirectory called dist.
Copy all files from the distribution disks into the dist directory.
Make the installation script executable using chmod as follows: chmod +x install.sun
Run the batch program as follows: install.sun

Proceed to compilation.

Installation for Silicon Graphics

Silicon Graphics installation uses a shell script install.sgi. Note that this is a Bourne shell script, not a c-shell script. It can be run under the Bourne shell, the Korn shell, or the GNU bash shell. To install, perform the following steps:

Create a root directory for CQL, for example, cql81.
Under the root directory, create a subdirectory called dist.
Copy all files from the distribution disks into the dist directory.
Make the installation script executable using chmod as follows: chmod +x install.sgi
Run the batch program as follows: install.sgi

Proceed to compilation.

Installation for LINUX

Linux installation uses a shell script install.lin. To install, perform the following steps:

Create a root directory for CQL, for example, cql81.
Under the root directory, create a subdirectory called dist.
Copy all files from the distribution disks into the dist directory.
Make the installation script executable using chmod as follows: chmod +x install.lin
Run the batch program as follows: install.lin

Proceed to compilation.