Using the esql Command
To create an executable C program from an ESQL/C source file, use the esql command. The Informix installation script installs the esql command as part of the ESQL/C product. This section describes what the esql command can do and how you use it.
The esql command performs the following steps:
1. Converts the embedded SQL statements to C language code.
2. Compiles the file that results with the C compiler to create an object file.
3. Spawns the resource compiler and links any resource files (.res) that you specify on the esql command line. 
4. Links the object file with the ESQL/C libraries and your own libraries.
You can use the esql command to perform all these steps. Alternatively, you can use the esql command to perform step 1, then compile and link the files with your C compiler directly. For more information about step 1, see "Compiling an ESQL/C Program".
Requirements for Using esql
Before you use esql, make sure that:
Syntax of the esql Command
The following sections describe the syntax available for the esql command. This section organizes the command-line options by the processing phase that they affect:
The esql Command for UNIX
The following diagram gives the esql command options for the UNIX operating system. For more information on the -cp, -np, -nup, and -cponly options, see "Running the C Preprocessor Before the ESQL/C Preprocessor".
|
|
The esql Command for Windows Environments
The following diagram shows the general syntax of the ESQL/C command processor, esql. For more information on the -cp, -np, -nup, and onlycp options, see "Running the C Preprocessor Before the ESQL/C Preprocessor".
|
|
Options That Affect Preprocessing
An ESQL/C program must be preprocessed before a C compiler can compile it. The ESQL/C preprocessor converts the embedded SQL statements to C language code.
You can use all the preprocessor options that the following sections describe for preprocessing only or for preprocessing, compiling, and linking.
Checking the Version Number
Use the -V option to obtain the Informix version number and serial number for your ESQL/C product, as shown in the following example:
Associating Options with Files
Most processor options that precede a filename affect the file. Suppose you issue the following command:
The -G option affects the demo1.ec file, and both the -ansi and the -G options affect the demo2.ec file.
An exception is the -o option, which affects only the next item, as "Naming the Executable File in Windows Environments" describes.
Preprocessing Without Compiling or Linking
By default, the esql command causes the ESQL/C program to be preprocessed, compiled, and linked. The output of the esql command is an executable file. You can specify the -e option to suppress the compilation and linking of your ESQL/C program. With this option, esql only causes preprocessing of the code. The output of this command is a C source file (.c extension).
For example, to preprocess the program that resides in the file demo1.ec, you use the following command:
The preceding command would generate a C source file that is called demo1.c. The following esql command preprocesses demo1.ec, checks for Informix extensions to ANSI-standard syntax, and does not use line numbers:
Generating Thread-Safe Code
You can use the -thread option to instruct the preprocessor to generate thread-safe code.
You must use the THREADLIB environment variable with this option to specify which thread package to use when you compile your application.
For Windows environments, the Informix general libraries (libgen, libos, libgls, libafs, and libsql) are shared thread-safe DLLs. Therefore, the esql command links the shared thread-safe DLLs automatically. You do not set the THREADLIB environment variable when you compile multithreaded applications in a Windows environment.
Checking for ANSI-Standard SQL Syntax
When you compile an ESQL/C program, you can instruct the preprocessor to check for Informix extensions to ANSI-standard SQL syntax in one of two ways:
After you set the DBANSIWARN environment variable, every time you compile or run an ESQL/C program, ESQL/C checks for ANSI compatibility. For information on how to set DBANSIWARN, see the Informix Guide to SQL: Reference. For details about how to check for runtime warnings, see Chapter 10 of this manual. For details on how to set environment variables, see the Informix Client Products Installation Guide for your operating system.
The -ansi option does not cause ESQL/C to check for ANSI compatibility at runtime.
With the -ansi option, the ESQL/C preprocessor generates a warning message when it encounters an Informix extension to ANSI SQL syntax. The following esql command preprocesses, compiles, and links the demo1.ec program and verifies that it does not contain any Informix extensions to the ANSI-standard syntax:
If you compile a program with both the -ansi and -xopen options, the ESQL/C preprocessor generates warning messages for Informix extensions to both ANSI and X/Open SQL syntax.
Defining and Undefining Definitions While Preprocessing
You can use the -ED and -EU options to create or remove definitions during ESQL/C preprocessing.
To create a global definition, use one of the following forms of the -ED option:
The -EDname is equivalent to the define preprocessor directive ($define or EXEC SQL define) with name at the top of your ESQL/C program.
To remove or undefine a definition globally for the entire source file, use the following syntax for the -EU option:
The -EU option has a global effect over the whole file, regardless of other define directives for name.
As with the define and undef statements, the ESQL/C preprocessor processes the -ED and -EU options in stage 1 of preprocessing (before it preprocesses the code in your source file). For more information on preprocessor definitions, see "The define and undef Directives".
Figure 1-20 shows a code fragment that uses conditional compilation (the ifdef and ifndef directives).
For the code fragment shown in Figure 1-20, the following esql command line does not generate code because the command line undefines the ENABLE_CODE definition for the entire source file:
Checking for Missing Indicator Variables
If you include the -icheck option, the ESQL/C preprocessor generates code in your program that returns a runtime error if an SQL statement returns a null value to a host variable that does not have an associated indicator variable. For example, the following command tells the preprocessor to insert code that checks for null values into the demo1.ec program:
If you do not use the -icheck option, ESQL/C does not generate an error if the database server passes a null value to a host variable without an indicator variable. For more information on indicator variables, see "Using Indicator Variables".
Naming the Location of Include Files
The -I preprocessor option allows you to name a directory where the preprocessor searches for ESQL/C and C include files. This option is valid for both the ESQL/C and the C preprocessors as follows:
You specify these include files with the include preprocessor directive $include or EXEC SQL include.
You specify these files with the #include preprocessor statement. Because the C preprocessing begins after the ESQL/C compilation completes, the C include files are processed after the ESQL/C include files.
The preprocessor passes the -I option to the C compiler for processing of C include files (those that a #include preprocessor statement specifies). The syntax for the -I option is as follows:
The directory can reside on a mounted remote file system if the standard C library functions fopen(), fread(), and fclose() can access them.
The following esql command names the UNIX directory /usr/johnd/incls as a directory to search for ESQL/C and C include files within the demo1 program:
Each -I option lists a single directory. To list several directories, you must list multiple -I options on the command line.
To search in both the C:\dorrie\incl and C:\johnd\incls directories in a Windows environment, you would need to issue the following command:
When the preprocessor reaches an include directive, it looks through a search path for the file to include. It searches directories in this sequence:
1. The current directory
2. The directories that -I preprocessor options specify (in the order in which you specify them on the command line)
3. The directory $INFORMIXDIR/incl/esql on a UNIX operating system and the %INFORMIXDIR%\incl\esql in a Windows environment (where $INFORMIXDIR and %INFORMIXDIR% represent the contents of the environment variable of that name)
4. The directory /usr/include
For more information on ESQL/C include files, see "The include Directive".
Numbering Lines
By default, the ESQL/C preprocessor gives line numbers to the embedded SQL lines in your program. You can change this default numbering with two command-line options:
Setting the Scope of Cursor Names and Statement IDs
By default, ESQL/C defines cursor names and statement IDs as global entities. If you use the -local option, static cursor names and static statement IDs that you declare in a file are local to that file. To create the local name, ESQL/C adds a unique tag (two to nine characters long) to the cursor names and statement IDs in an ESQL/C program. If the combined length of the cursor name (or statement ID) and the unique tag exceeds 18 characters, you receive a warning message.
If you use the -local option, you must recompile the source files every time you rename them.
Redirecting Errors and Warnings
By default, esql directs error and warning messages it generates to standard output. If you want the errors and warnings to be put into a file, use the -log option with the filename. For example, the following esql command compiles the program demo1.ec and sends the errors to the err.out file:
This option only affects the error warnings that the ESQL/C preprocessor generates. The warnings from the compile and link stages still go to the standard output.
Suppressing Warnings
By default, the preprocessor generates warning messages when it processes an ESQL/C file. To suppress these warning messages, use the -nowarn option. This option has no effect on error messages.
Using X/Open Standards
The -xopen option tells the ESQL/C preprocessor that your program uses X/Open standards. When you specify this option, the preprocessor performs the following two tasks:
If you include Informix extensions to X/Open-standard syntax in your code, the preprocessor generates warning messages.
ESQL/C uses these codes in a dynamic management structure (a system-descriptor area or an sqlda structure) to indicate column data types. Informix defines these codes in the sqlxtype.h header file.
If you use X/Open SQL in an ESQL/C program, you must recompile any other source files in the same application with the -xopen option.
If you compile a program with both the -xopen and -ansi options, the ESQL/C preprocessor generates warning messages for Informix extensions to both X/Open and ANSI SQL syntax.
Running the C Preprocessor Before the ESQL/C Preprocessor
The compilation of an ESQL/C source file can follow either the default order, where the ESQL/C preprocessor runs first on the source file, or it can allow the C preprocessor to run on the source file before the ESQL/C preprocessor.
The default sequence of compilation for an ESQL/C source file is as follows:
1. The ESQL/C preprocessor performs the following steps to create a .c file from the ESQL/C source file:
2. The C preprocessor takes the following actions:
3. The C compiler, assembler, and linker work in the usual way, as they do for a C source file, translating the C code file into an executable program.
This default order of compilation is restrictive because you cannot use #defines or typedefs defined within C system header files or custom C header files to define ESQL/C host variables and constants, nor can you use them for conditional compilation of ESQL/C code. With the default order of compilation, C header files do not get included into the ESQL/C source code until after the ESQL/C preprocessor has run, making these definitions unavailable to the ESQL/C preprocessor.
Options for Running the C Preprocessor First
You can make the C preprocessor run on an ESQL/C source file first, thus expanding any C-dependent typedefs or #defines inside the ESQL/C source file before the ESQL/C preprocessor is run on that source file. This can be done any of the following ways:
CPFIRST Environment Variable
The CPFIRST environment variable specifies whether the C preprocessor should run before the ESQL/C preprocessor on all ESQL/C source files. Set the environment variable to TRUE (uppercase only) to run the C preprocessor on all ESQL/C source files, irrespective of whether the -cp option is passed to the esql command, and irrespective of whether the source file has the .ec or the .ecp extension.
The following diagram shows how to set the CPFIRST environment variable in a UNIX C-shell environment.
The following diagram shows how to set the CPFIRST environment variable in a Windows command-line environment.
The Order of Compilation When the C Preprocessor Runs First
When a user chooses to run the C preprocessor on an ESQL/C source file before the ESQL/C preprocessor, the file undergoes the following order of compilation. For details on the phases of SQL keyword protection and unprotection, see "SQL Keyword Protection".
1. The eprotect utility runs on the source file to protect all SQL keywords against interpretation by the C preprocessor
2. The C preprocessor runs on the source file
3. The eprotect utility runs on the output of the C preprocessor with the -u mode to remove SQL keyword protection
4. The ESQL/C preprocessor runs on the output of the C preprocessor, which no long has any SQL keyword protection
5. The output of the ESQL/C preprocessor undergoes compilation and linking by the C compiler and linker to produce an executable file.
Defining Host Variables Based on C #defines and typedefs
When the C preprocessor runs on a source file, it expands the contents of all C header files where they are included within the source file. This expansion makes it possible to use host variables in ESQL/C source files based on types and #define and typedef statements in C header files. The examples given here indicate some of the advantages of sharing header files. In the example in Figure 1-21, the same C header file is used by both ESQL/C and C source files.
In the example in Figure 1-22, the ESQL/C source file contains a host variable based on a type defined in the time.h system-header file.
A C header file can be included anywhere inside an ESQL/C source file. However, to define host variables in ESQL/C files based on #defines and typedefs defined in C header files, you must include the C header file within the EXEC SQL declare section. Contrast the example in Figure 1-23, which leads to error -33051: Syntax error on identifier or symbol `name_hostvar with the example in Figure 1-21 which does not. The only difference is that in the example in Figure 1-21, the C header file with the #define and the typedef that is used in the EXEC SQL declare section is included within that declare section.
Allowing All Valid C Declaration Syntax Inside the EXEC SQL Declare Section
When the ESQL/C preprocessor runs on a file, it expands all the contents of header files inside the ESQL/C source file where the header file was included in the source file. Therefore, one consequence of including C header files inside the EXEC SQL declare section is that all types of C declaration syntax are included in the EXEC SQL declare section after the pass through the C preprocessor. You can now include all valid C declaration syntax in the EXEC SQL declare section in the EXEC SQL declare section. However, you can only declare host variables based on certain types described in "Host-Variable Data Types".
Excluding Statements Inside C Header Files
If the ESQL/C preprocessor has problems with certain statements in C header files, you can exclude specific lines from the preprocessing that the ESQL/C preprocessor performs as shown in the example in Figure 1-24.
SQL Keyword Protection
If the code in the ESQL/C files is passed unprotected to the C preprocessor before it is passed to the ESQL/C preprocessor, certain SQL keywords might be analyzed by the C preprocessor, which causes unintended results. In the following example, the SQL keyword NULL is replaced by the C preprocessor with the value zero, which creates a valid SQL statement, but one which inserts a value into the orders table other than the value that the programmer intended:
When a user gives the option to run the C preprocessor before the ESQL/C preprocessor, the utility eprotect runs before the C preprocessor runs on the ESQL/C source file. The eprotect utility prepends any SQL keyword that occurs in an SQL statement with the prefix SQLKEYWORD_. This prefix is affixed on all SQL keywords inside SQL statements that begin with the EXEC SQL directive and end with a semicolon. When the ESQL/C source file that contains the select statement mentioned earlier is passed to the C preprocessor, the SELECT statement has the following form:
After the C preprocessor runs on an ESQL/C source file, the esql command runs the eprotect utility with the -u mode, which removes all the SQLKEYWORD_ prefixes before it runs the ESQL/C preprocessor on the output of the C preprocessor.
SQL Keyword Protection and the $ Symbol
All SQL statements within ESQL/C source files can either begin with the EXEC SQL key words or with the $ prefix. All of the following pairs of statements are equivalent:
However, the $ symbol can also occur at the beginning of typedef definitions such as in the following example:
In cases such as the preceding typedef example, program logic might require that the C preprocessor substitute the value zero in the place of the keyword NULL. Not allowing the C preprocessor to make value substitutions in such cases would lead to errors. Therefore the eprotect utility does not prepend the SQLKEYWORD_ prefix on SQL keywords that appear in SQL statements that begin with the dollar sign ($) symbol.
Important: If you want to run the C preprocessor on your ESQL/C source file before the ESQL/C preprocessor does, and if you do not want the C preprocessor to substitute values for the SQL keywords in SQL statements that occur in your source file, you must begin each SQL statement with the keywords EXEC SQL, and not with the $ symbol.
Preprocessor Options Specific to Windows Environments
The following additional preprocessing options are available to you if you use ESQL/C in a Windows environment.
Line Wrapping
The ESQL/C preprocessor translates one embedded SQL statement as one C line. Long lines can cause problems for some debuggers and editors. You can use the -lw option to tell the preprocessor to wrap output lines at a specific column position. For example, the following esql command tells the preprocessor to wrap lines at column 75:
If you omit the -lw option, the preprocessor does not perform line wrapping.
Changing Error and Warning Displays
By default, the ESQL/C preprocessor generates error and warning messages when it processes an ESQL/C file. It displays these errors and warnings in the console window. You can change the display of error and warning messages with the following command-line options:
Setting Tab Stops
By default, the ESQL/C preprocessor formats the C source file with tab stops at every eighth column position. You can use the -ts option to set different tab stops. For example, the following esql command tells the preprocessor to set tab stops every four characters:
|
