INFORMIX-ESQL/C Programmer's Manual Compiling Programs

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. For more information, see Compiling an INFORMIX-ESQL/C Program.

Before you use esql, make sure that:

• the filename of the ESQL/C source file has the .ec extension. You can also use the .ecp extension if you want the C preprocessor to run before the ESQL/C preprocessor.
• you set the environment variable INFORMIXDIR correctly and that the PATH environment variable includes the path to the bin directory of the INFORMIXDIR directory ($INFORMIXDIR/bin on the UNIX operating system and %INFORMIXDIR%\bin in Windows environments).

For a complete description of INFORMIXDIR, see the Informix Guide to SQL: Reference or the Informix Client Products Installation Guide for your operating system.

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:

• Preprocessing options determine how esql translates the embedded SQL statements.
• Compilation options affect the compilation phase, when the C compiler translates the C source to object code.
• Linking options affect the linking phase, when the C compiler links the object code to produce an executable file.

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.

-ansi	checks for Informix extensions to ANSI-standard SQL syntax.
-EDname	defines a user-supplied name flag to the preprocessor that the undef, ifdef, and ifndef directives can use. For more information, see Defining and Undefining Definitions While Preprocessing.
-EUname	undefines a specified preprocessor name flag. For more information, see Defining and Undefining Definitions While Preprocessing.
-g	numbers every line (used by a debugger).
-G	suppresses line numbers (used by a debugger; same as -nln).
-icheck	generates the code to check if a null value is returned to a host variable that does not have an associated indicator variable. Generates an error if such a case exists.
-Ipathname	expands the search range for ESQL/C and C include files. The ESQL/C preprocessor only processes ESQL/C include files (those with the include directive). The esql command passes this option to the C compiler for processing of C include files (those with the #include preprocessor statement).
-local	specifies that the static cursor names and static statement ids that you declare in a file are local to that file. If you do not use the -local option, cursor names and statement IDs, by default, are global entities.
-log logfile	sends the error and warning messages to the specified file instead of to standard output.
-nln	suppresses line numbers (used by a debugger; same as -G).
-nowarn	suppresses warning messages from the preprocessor (has no effect on error messages).
-xopen	generates warning messages for SQL statements that use Informix extensions to the X/Open standard. It also indicates that dynamic SQL statements use the X/Open set of codes for data types (when using GET DESCRIPTOR and SET DESCRIPTOR statements or an sqlda structure).

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.

-EDMACNAME=62 

EXEC SQL define MACNAME 62; 

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.

Use the -V option to obtain the Informix version number and serial number for your ESQL/C product, as the following example shows:

esql -V

Most preprocessor options that precede a filename affect the file. Suppose you issue the following command:

esql -G demo1.ec -ansi demo2.ec

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 names the executable file for all of the source files that follow it on the command line. For example, the executable file inpt is created from both of the source files, custinpt.ec and ordinpt.ec, on the following command line.

esql -o inpt custinpt.ec ordinpt.ec

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:

esql -e demo1.ec

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:

esql -e -ansi -G demo1.ec

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.

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:

• You can set the DBANSIWARN environment variable.

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.

• You can specify the -ansi option at compile time whenever you want to check for ANSI compatibility.

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:

esql -ansi demo1.ec

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.

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:

• Use the -EDname syntax to define a Boolean symbol, as follows:
esql -EDENABLE_CODE define_ex.ec
• Use the -EDname=value syntax to define an integer constant, as follows:
esql -EDMAXLENGTH=10 demo1.ec

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:

-EUname

The -EU option has a global effect over the whole file, regardless of other define directives for name.

Important: Do not put a space between ED or EU and the symbol 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 2-2 shows a code fragment that uses conditional compilation (the ifdef and ifndef directives).

/* define_ex.ec */

#include <stdio.h>

EXEC SQL include sqlca;

EXEC SQL define ENABLE_CODE;



main()

{


EXEC SQL ifdef ENABLE_CODE;

printf("First block enabled");

EXEC SQL endif ENABLE_CODE;


EXEC SQL ifndef ENABLE_CODE;

EXEC SQL define ENABLE_CODE;

EXEC SQL endif ENABLE_CODE;


EXEC SQL ifdef ENABLE_CODE;

printf("Second block enabled");

EXEC SQL endif ENABLE_CODE;

}

For the code fragment shown in Figure 2-2, the following esql command line does not generate code because the command line undefines the ENABLE_CODE definition for the entire source file:

esql -EUENABLE_CODE define_ex.ec

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:

esql -icheck demo1.ec

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.

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:

• The ESQL/C preprocessor (esql) processes only ESQL/C include files.

You specify these include files with the include preprocessor directive $include or EXEC SQL include.

• The C preprocessor (cc) processes only the C include files.

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:

esql -Idirectory esqlcprogram.ec

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:

esql -I/usr/johnd/incls demo1.ec

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:

esql -IC:dorrie\incl -IC:\johnd\incls demo1.ec

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.

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:

• Use the -g option if you want to include line numbers for every line (C and embedded SQL).
• Use the -G or -nln options if you do not want any line numbers.

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 128 characters, you receive a warning message.

Tip: Informix provides the -local option primarily for backward compatibility with applications that were created in previous versions of ESQL/C. Do not use this option when you compile new applications. Do not mix files compiled with and without the -local flag. If you mix them, you might receive unpredictable results.

If you use the -local option, you must recompile the source files every time you rename them.

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:

esql -log err.out -o demorun demo1.ec

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 error output, which is stderr on UNIX, for example.

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.

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:

• It checks for Informix extensions to X/Open-standard syntax.

If you include Informix extensions to X/Open-standard syntax in your code, the preprocessor generates warning messages.

• It uses the X/Open set of codes for SQL data types.

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.

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:
• Incorporates ESQL/C header files into the source file when it processes all include directives ($include and EXEC SQL include statements)
• Creates or removes compile-time definitions when it processes all define ($define and EXEC SQL define) and undef ($undef and EXEC SQL undef) directives
• Processes any conditional compilation directives (ifdef, ifndef, else, elif, endif) and translates embedded SQL statements to ESQL/C function calls and special data structures
2. The C preprocessor takes the following actions:
• Incorporates C header files into the source file when it processes all C include directives (#include)
• Creates or removes compile-time definitions when it processes all C language define (#define) and undef (#undef) directives
• Processes C conditional compilation directives (#ifdef, #ifndef, #else, #elif, #endif)
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 in 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.

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. You can do this in any of the following ways:

• Pass the -cp or the onlycp option to the esql command.

Both force the C preprocessor to run first, but in the case of the -cponly option, the compilation stops after the C preprocessor is run, and the result is put in a source.icp file.

• Create the ESQL/C source file with a .ecp extension.

This triggers the -cp option by default.

• Set the CPFIRST environment variables to TRUE (uppercase only) as explained in the following section.

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.

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.

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 longer 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.

For details on the phases of SQL keyword protection and unprotection, see SQL Keyword Protection.

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 2-3, the same C header file is used by both ESQL/C and C source files.

/*header file i.h*/

#define LEN 15

typedef struct customer_t{

	int    c_no;
	char   fname[LEN];

	char   lname[LEN];

	} CUST_REC;


/*cust.ec*/

#include <stdio.h>



EXEC SQL BEGIN DECLARE SECTION;

#include "i.h"

EXEC SQL END DECLARE SECTION;



int main()

{



EXEC SQL BEGIN DECLARE SECTION;

	CUST_REC cust;

EXEC SQL END DECLARE SECTION;


}





/*name.c*/

#include "i.h"

int main ()

{...

	CUST_REC cust;


}

In the example in Figure 2-4, the ESQL/C source file contains a host variable based on a type defined in the time.h system-header file.

/*time.ec*/



#include <time.h>



main ()

{...

EXEC SQL BEGIN DECLARE SECTION;

	time_t time_hostvar;

EXEC SQL END DECLARE SECTION;


}

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 2-5 on page 2-32, which leads to error -33051: Syntax error on identifier or symbol `name_hostvar with the example in Figure 2-3 on page 2-30 which does not. The only difference is that in the example in Figure 2-3, 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.

/*header file i.h*/

#define LEN 15

typedef struct customer_t{

	int    c_no;

	char   fname[LEN];

	char   lname[LEN];

	} CUST_REC;


/*cust.ec*/

#include "i.h"



int main()

{



EXEC SQL BEGIN DECLARE SECTION;

	CUST_REC cust;


}


...Leads to error -33051...

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.

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 2-6.

/*header file i.h*/

#ifndef ESBDS /*define empty macros, if included by a C\ 

	source*/

#define ESBDS

#define ESEDS

#endif


ESEDS

statement that you do not want ESQL/C preprocessor to see

ESBDS





/*name.ec*/

#define ESBDS "EXEC SQL BEGIN DECLARE SECTION;"

#define ESEDS "EXEC SQL END DECLARE SECTION"

main ()

{...

EXEC SQL BEGIN DECLARE SECTION;

	#include "i.h"

EXEC SQL END DECLARE SECTION;


}

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:

EXEC SQL insert into orders (shipcharge) values (NULL);

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:

EXEC SQL SQLKEYWORD_insert SQLKEYWORD_into orders (order_num) 

SQLKEYWORD_values (SQLKEYWORD_NULL);

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.

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:

EXEC SQL BEGIN DECLARE SECTION;

$BEGIN DECLARE SECTION;



EXEC SQL connect to `database9';

$connect to `database9';



EXEC SQL select fname into :hostvar1 from table1;

$  select fname into :hostvar1 from table1;

However, the $ symbol can also occur at the beginning of typedef definitions such as in the following example:

$int *ip = NULL;

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, 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 dollar sign ($) symbol.

The following additional preprocessing options are available to you if you use ESQL/C in a Windows environment.

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:

esql -lw:75 demo.ec

If you omit the -lw option, the preprocessor does not perform line wrapping.

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:

• Use the -nowarn option to suppress warning messages. This option has no effect on error messages.
• Use the -mserr option to display error and warning messages in Microsoft Error Message format. Some text editors understand this format and can use it to go to the line in the ESQL/C source file that caused the error or warning.

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:

esql -ts:4 demo.ec