Command Line Operations
The following sections describe how to turn an embedded ESQL/BASIC source program into an executable program. These sections include commands that preprocess, compile, and link a program.
esqlb Command -- Invoke Embedded SQL Preprocessor for BASIC
The BASIC preprocessor is invoked by the following command line:
esqlb {flags} {filename}
where flags are
Flag | Description |
|---|---|
-d | Adds debugging information to the runtime database error messages generated by Embedded SQL. The source file name, line number, and statement in error will be displayed with the error message. |
-f[filename] | Writes preprocessor output to the named file. If no filename is specified, the output is sent to standard output, one screen at a time. |
-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 | Like -l, but the generated BASIC code also appears in the listing file. |
-o | Directs the preprocessor not to generate output files for include files. This flag 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. |
-? | Shows which command line options are available for esqlb. |
-rN | Sets the 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 unfamiliar statements. If you specify the -l option with this flag, the listing file is called "stdin.lis". To terminate the interactive session, type Ctrl Z. |
-sqlcode | Indicates the file declares ANSI SQL code. The ANSI-92 specification describes SQLCODE as a "deprecated feature" and recommends using the SQLSTATE variable. |
-[no]sqlcode | Tells the preprocessor not to assume a declared SQLCODE is for ANSI status information. |
-w | Prints warning messages. |
-wopen | This flag is identical to -wsql=open. However, -wopen is supported only for backwards capability. See -wsql=open for more information. |
-wsql=entry_ SQL92|open | Prints warning messages that indicate all non-entry SQL92 compliant syntax. Use open only with OpenSQL syntax. -wsql = open generates a warning if the preprocessor encounters an Embedded SQL statement that does not conform to OpenSQL syntax. (OpenSQL syntax is described in the OpenSQL Reference Guide.) This flag is useful if you intend to port an application across different Ingres Gateways. The warnings do not affect the generated code and the output file may be compiled. This flag does not validate the statement syntax for any SQL Gateway whose syntax is more restrictive than that of OpenSQL. |
The Embedded SQL BASIC preprocessor assumes that input files are named with the extension ".sb". 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 in tab format with the same name and the extension ".bas".
If you enter the command without specifying any flags or a filename, Ingres displays a list of flags available for the command.
esqlb Command Options
The following table presents the command options available with esqlb:
Command | Comment |
|---|---|
esqlb file1 | Preprocesses "file1.sb" to "file1.bas" |
esqlb file2.xb | Preprocesses "file2.xb" to "file2.bas" |
esqlb -l file3 | Preprocesses "file3.sb" to "file3.bas" and creates listing "file3.lis" |
esqlb -s | Accepts input from standard input |
esqlb -ffile4.out file4 | Preprocesses "file4.sb" to "file4.out" |
esqlb | Displays a list of flags available for this command |
The BASIC Compiler
As previously mentioned, 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 Embedded SQL preprocessor with the -i1 or -i2 flag. Similarly, use of the BASIC double qualifier requires that you have preprocessed your Embedded SQL file using the -r8 flag. Note, too, that many of the statements that the Embedded SQL 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 Embedded SQL preprocessor and the BASIC compiler assume the default extensions.
$ esqlb test1
$ basic/list test1
$ basic/list test1
VMS:
As of Ingres II 2.0/0011 (axm.vms/00) Ingres uses member alignment and IEEE floating-point formats. Embedded programs must be compiled with member alignment turned on. In addition, embedded programs accessing floating-point data (including the MONEY data type) must be compiled to recognize IEEE floating-point formats.
The VMS default qualifier /g_float is not a standard and should not be used.
On Alpha systems, hardware support for D_float is only partial, the default has changed to G_float, and support for IEEE (IEEE 754-1985 standard for floating point arithmetic) has been added. Because of this, and because IEEE is available on other platforms and is recognized as an industry standard, Ingres for OpenVMS Alpha uses the IEEE format.
All programs and libraries should be compiled using the IEEE qualifier. Do not mix programs or libraries compiled with different qualifiers.
For example:
esqlb prog.sb
basic /float=ieee prog
basic /float=ieee prog
Failure to use the /float=ieee qualifier or the use of non-IEEE float numbers will result in unpredictable results when non-IEEE floats are used as keys or in restrictions.
Note: Check your Release Notes for any operating system specific information on compiling and linking ESQL/BASIC programs.
How Embedded SQL Programs are Linked
Embedded SQL programs require procedures from several VMS shared libraries in order to run properly. Once you have preprocessed and compiled an Embedded SQL 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]esql.opt/opt
ii_system:[Ingres.files]esql.opt/opt
Link Precompiled Forms
The technique of declaring a precompiled form to the FRS is discussed in the SQL Reference Guide and in BASIC Variables and Data Types. To use such a form in your program, you must also follow the steps described here.
To link a precompiled form
1. In VIFRED, select a menu item to compile a form. VIFRED then creates a file in your directory describing the form in the VAX-11 MACRO language. Select a name for the file.
2. Once you have created the MACRO file, assemble it into linkable object code with the following VMS command:
macro filename
3. The output of this command is a file with the extension ".obj". Link this object file with your program by listing it in the link command, as in the following example:
$ link formentry,-
empform.obj,-
ii_system:[Ingres.files]esql.opt/opt
empform.obj,-
ii_system:[Ingres.files]esql.opt/opt
How Embedded SQL Programs are Linked without Shared Libraries
While the use of shared libraries in linking Embedded SQL 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 Embedded SQL 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 for an Embedded SQL program called "dbentry" that has been preprocessed and compiled:
$ link dbentry,-
ii_system:[Ingres.files]esql.noshare/opt
ii_system:[Ingres.files]esql.noshare/opt
User-written Embedded SQL Routines in Shareable Images
When you plan to place your code in a shareable image, note the following about the psect attributes of your global or external variables.
• As a default, some compilers mark global variables as shared (SHR: every user who runs a program linked to the shareable image sees the same variable) and others mark them as not shared (NOSHR: every user who runs a program linked to the shareable image gets their own private copy of the variable).
• Some compilers support modifiers you can place in your source code variable declaration statements to explicitly state which attributes to assign a variable.
• The attributes that a compiler assigns to a variable can be overridden at link time with the psect_attr link option. This option overrides attributes of all variables in the psect. For further details, consult your compiler reference manual.
Last modified date: 04/03/2024