Command Line Operations
The following sections describe how to turn an embedded SQL/Ada source program into an executable program. The commands that preprocess, compile, and link a program are also described.
esqla Command – Invoke Embedded SQL Preprocessor for Ada
The Embedded SQL/Ada preprocessor is invoked by the following command line:
esqla {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 are displayed with the error message. |
-f[filename] | Writes preprocessor output to the named file. If you do not specify a filename, the output is sent to standard output, one screen at a time. |
-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 | Acts like the -l flag, but the listing file also includes the generated Ada code. |
-? | Shows what command line options are available for Embedded SQL/Ada. |
-s | Reads input from standard input and generates Ada 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 an integer variable named SQLCODE to receive status information from SQL statements. That declaration need not be in an exec sql begin/end declare section. This feature is provided for ISO Entry SQL92 conformity. However, the ISO Entry SQL92 specification describes SQLCODE as a "deprecated feature" and recommends using the SQLSTATE variable. |
-nosqlcode | Tells the preprocessor not to assume the existence of a status variable named SQLCODE. The flag -nosqlcode is the default. |
-w | Prints warning messages. |
-wopen | This flag is identical to -wsql=open. However, -wopen is supported only for backwards capability. Refer to -wsql=open below for more information. |
-wsql=entry_ SQL92 | Causes the preprocessor to flag any usage of syntax or features that do not conform to the ISO Entry SQL92 entry level standard. (This is also known as the "FIPS flagger" option.) |
-wsql=open | 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. (For OpenSQL syntax, see the OpenSQL Reference Guide.) This flag is useful if you intend to port an application across different Enterprise Access products. 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 Enterprise Access product whose syntax is more restrictive than that of OpenSQL. |
The Embedded SQL/Ada preprocessor assumes that input files are named with the extension ".sa". You can override this default by specifying the file extension of the input file(s) on the command line. The output of the preprocessor is a file of generated Ada statements with the same name and the extension ".ada".
If you enter the command without specifying any flags or a filename, a list of flags available for the command is displayed.
esqla Command Options
The following table presents the command options available with esqla.
Command | Comment |
|---|---|
esqla file1 | Preprocesses "file1.sa" to "file1.ada" |
esqla file2.xa | Preprocesses "file2.xa" to "file2.ada" |
esqla -l file3 | Preprocesses "file3.sa" to "file3.ada" and creates the listing "file3.lis" |
esqla -s | Accepts input from standard input |
esqla -ffile4.out file4 | Preprocesses "file4.sa" to "file4.out" |
esqla | Displays a list of flags available for this command. |
The ACS Environment and the Ada Compiler
The preprocessor generates Ada code. You can then use the VMS ada command to compile this code into your Ada program library.
The following sections describe the Ada program library and Embedded SQL programs.
How to Enter Embedded SQL Package Specifications
Once you have set up an Ada program library, you must add four Embedded SQL units to your library. The units are package specifications that describe to the Ada compiler all the calls that the preprocessor generates. The source for these units is in the files:
ii_system:[ingres.files]eqdef.ada
ii_system:[ingres.files]eqsqlca.ada
ii_system:[ingres.files]eqsqlda.ada
ii_system:[ingres.files]eqsqlca.ada
ii_system:[ingres.files]eqsqlda.ada
Once you have defined your current program library using the acs set library command, you should enter the three units into your program library by issuing the following commands:
copy ii_system:[ingres.files]eqdef.ada, eqsqlca.ada,-
eqsqlda.ada []
ada eqdef.ada,eqsqlca.ada,eqsqlda.ada
delete eqdef.ada.,eqsqlca.ada.,eqsqlda.ada
eqsqlda.ada []
ada eqdef.ada,eqsqlca.ada,eqsqlda.ada
delete eqdef.ada.,eqsqlca.ada.,eqsqlda.ada
You do not have to take the last step if you intend to compile the closure of a particular program from the source files at a later date. However, you should not modify an Embedded SQL definition file if it is left in your directory.
You need only enter the four Embedded SQL units once into your program library. Of course, if a new release of Embedded SQL/Ada includes modifications to the files "eqdef.ada," "esqlca.ada," or "eqsqlda.ada," you should copy and recompile the files.
If you display the new unit information, you will find the four unit names "ESQL," "ESQLDA," "EQUEL," and "EQUEL_FORMS" in the library. For example, by issuing:
acs dir esql*,equel*
the three unit names will be displayed.
How to Define Long Floating-point Storage
The storage representation format of long floating-point variables must be d_float because the Ingres runtime system uses that format for floating-point conversions. If your Embedded SQL program has long_float variables that interact with the Embedded SQL runtime system, you must make sure they are stored in the d_float format. The default Ada format is g_float. A convenient way to control the format of all long float variables is to issue the acs set pragma program command. For example, by issuing the following command, you redefine the program library characteristics for long_float from the default to d_float:
acs set pragma/long_float=d_float
A second remedy to this particular problem is to issue the statement:
pragma long_float(d_float)
in the source file of each compilation unit that uses floating-point variables. You can also explicitly declare the Embedded SQL variables with type d_float, as defined in package SYSTEM.
The following example is a typical command file that sets up a new Ada program library with the Embedded SQL package specifications and the d_float numerical format. The name of the new program library is passed in as a parameter:
acs create library [.'p1']
acs set library [.'p1']
acs set pragma/long_float=d_float
copy ii_system:[ingres.files]eqdef.ada,eqsqlca.ada, -
eqsqlda.ada []
ada eqdef.ada,eqsqlca.ada,eqsqlda.ada
delete eqdef.ada.,eqsqlca.ada.,eqsqlda.ada
exit
acs set library [.'p1']
acs set pragma/long_float=d_float
copy ii_system:[ingres.files]eqdef.ada,eqsqlca.ada, -
eqsqlda.ada []
ada eqdef.ada,eqsqlca.ada,eqsqlda.ada
delete eqdef.ada.,eqsqlca.ada.,eqsqlda.ada
exit
The Ada Compiler
After you enter the Embedded SQL packages into the Ada program library, you can compile the Ada file generated by the preprocessor.
The following example preprocesses and compiles the file "test1." Note that both the Embedded SQL/Ada preprocessor and the Ada compiler assume the default extensions.
esqla test1
ada/list test1
ada/list test1
Note: Refer to the Readme file for any operating system specific information on compiling and linking ESQL/Ada programs.
VMS:
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:
esqla prog.sa
ada /float=ieee prog
ada /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.
How Embedded SQL Programs are Linked
Embedded SQL/Ada programs require procedures from several VMS shared libraries in order to run. After you preprocess and compile an Embedded SQL/Ada program, you can link it. For example, if your program unit is called "dbentry," you can use the following link command:
acs link dbentry –
ii_system:[ingres.files]esql.opt/opt
ii_system:[ingres.files]esql.opt/opt
Note that the Embedded SQL runtime library is not written in Ada, and therefore is specified as a foreign object file.
Link Precompiled Forms
The technique of declaring a precompiled form to the Forms Runtime System is discussed in the SQL Reference Guide. To use such a form in your program, you must also follow the steps described here.
To link a precomiled 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 MACRO language.
2. Once you have created the file, assemble it into linkable object code with the 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 specifying it in the link command as in the following example for the program unit "formentry," which includes two compiled forms:
acs link formentry –
empform.obj, deptform.obj, -
ii_system:[ingres.files]esql.opt/opt
empform.obj, deptform.obj, -
ii_system:[ingres.files]esql.opt/opt
How to Link Embedded SQL Programs without Shared Libraries
While the use of shared libraries in Embedded SQL programs is recommended for optimal performance and ease of maintenance, non-shared versions of the Embedded SQL runtime 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 local modules. Libraries must be specified in the order given in the options file.
The following example demonstrates the link command of the Embedded SQL program unit "dbentry," which has been preprocessed and compiled:
acs link dbentry –
ii_system:[ingres.files]esql.noshare/opt
ii_system:[ingres.files]esql.noshare/opt
Last modified date: 04/03/2024