Generating an Executable Program
Once you have written your EQUEL program, it must be preprocessed to convert the EQUEL statements into BASIC code. These sections describe the use of the EQUEL preprocessor. Additionally, it describes how to compile and link the resulting code to obtain an executable file.
The EQUEL Preprocessor Command
The BASIC preprocessor is invoked by the following command line:
eqb {flags} {filename}
where flags are
-d
Adds debugging information to the runtime database error messages generated by EQUEL. The source file name, line number, and the erroneous statement itself are printed along with the error message.
-f[filename]
Writes preprocessor output to the named file. If the -f flag is specified without a filename, the output is sent to standard output, one screen at a time. If the -f flag is omitted, output is given the basename of the input file, suffixed ".bas".
-iN
Sets the default size of integers to N bytes. N must be 1, 2, or 4. The default setting is 4.
-l
Writes preprocessor error messages to the preprocessor's listing file, as well as to the terminal. The listing file includes preprocessor error messages and your source text in a file named filename.lis, where filename is the name of the input file.
-lo
Similar to -l, but the generated BASIC code also appears in the listing file
-n. ext
Specifies the extension used for filenames in ## include and ## include inline statements in the source code. If -n is omitted, include filenames in the source code must be given the extension ".qb".
-o
Directs the preprocessor not to generate output files for include files.
This does not affect the translated include statements in the main program. The preprocessor will generate a default extension for the translated include file statements unless you use the -o.ext flag.
-o.ext
Specifies the extension given by the preprocessor to both the translated include statements in the main program and the generated output files. If this flag is not provided, the default extension is ".bas".
If you use this flag in combination with the -o flag, then the preprocessor generates the specified extension for the translated include statements, but does not generate new output files for the include statements.
-rN
Sets default size of reals to N bytes. N must be 4 or 8. The default setting is 4.
-s
Reads input from standard input and generates BASIC code to standard output. This is useful for testing statements you are not familiar with. If the -l option is specified with this flag, the listing file is called "stdin.lis." To terminate the interactive session, type Ctrl Z.
-w
Prints warning messages
-?
Shows what command line options are available for eqb
The EQUEL/BASIC preprocessor assumes that input files are named with the extension ".qb". This default can be overridden by specifying the file extension of the input file(s) on the command line. The output of the preprocessor is a file of generated BASIC statements with the same name and the extension ".bas".
If you enter the command without specifying any flags or a filename, INGRES displays a flags list for the command.
The following table presents the options available with eqb.
Eqb Command Examples
The following are examples of eqb commands.
eqb file1
Preprocesses "file1.qb" to "file1.bas"
eqb -l file2.xb
Preprocesses "file2.xb" to "file2.bas" and creates listing "file2.lis"
eqb -s
Accepts input from standard input and writes generated code to standard output
eqb -ffile3.out file3
Preprocesses "file3.qb" to "file3.out"
eqb
Displays a list of flags available for this command.
The BASIC Compiler
As mentioned above, the preprocessor generates BASIC code. You should use the VMS basic command to compile this code. Most of the basic command line options can be used. You should not use the g_float or h_float qualifiers if floating-point values in the program are interacting with INGRES floating-point objects. If you use the byte or word compiler qualifiers, you must run the EQUEL preprocessor with the -i1 or -i2 flag. Similarly, use of the BASIC double qualifier requires that you have preprocessed your EQUEL file using the -r8 flag. Note, too, that many of the statements that the EQUEL preprocessor generates are BASIC language extensions provided by VAX/VMS. Consequently, you should not attempt to compile with the ansi_standard qualifier.
The following example preprocesses and compiles the file "test1." Note that both the EQUEL preprocessor and the BASIC compiler assume the default extensions.
$ eqb test1
$ basic/list test1
Note: Check the Readme file for any operating system specific information on compiling and linking EQUEL/BASIC programs.
Linking an EQUEL Program
EQUEL programs require procedures from several VMS shared libraries in order to run properly. Once you have preprocessed and compiled an EQUEL program, you can link it. Assuming the object file for your program is called "dbentry," use the following link command:
$ link dbentry.obj,-
ii_system:[ingres.files]equel.opt/opt
It is recommended that you do not explicitly link in the libraries referenced in the EQUEL.OPT file. The members of these libraries change with different releases of INGRES. Consequently, you may be required to change your link command files in order to link your EQUEL programs.
Assembling and Linking Precompiled Forms
The technique of declaring a precompiled form to the FRS is discussed in the QUEL Reference Guide. To use such a form in your program, you must also follow the steps described here.
In VIFRED, you can select a menu item to compile a form. When you do this, VIFRED creates a file in your directory describing the form in the VAX-11 MACRO language. VIFRED lets you select the name for the file. Once you have created the MACRO file this way, you can assemble it into linkable object code with the VMS command:
macro filename
The output of this command is a file with the extension ".obj". You then link this object file with your program (in this case named "formentry") by listing it in the link command, as in the following example:
$ link formentry,-
empform.obj,-
ii_system:[ingres.files]equel.opt/opt
Linking an EQUEL Program without Shared Libraries
While the use of shared libraries in linking EQUEL programs is recommended for optimal performance and ease-of-maintenance, non-shared versions of the libraries have been included in case you require them. Non-shared libraries required by EQUEL are listed in the esql.noshare options file. The options file must be included in your link command after all user modules. Libraries must be specified in the order given in the options file.
The following example demonstrates the link command of an EQUEL program called "dbentry" that has been preprocessed and compiled:
$ link dbentry,-
ii_system:[ingres.files]equel.noshare/opt