INFORMIX-ESQL/C Programmer's Manual Programming with INFORMIX-ESQL/C

You can use the following capabilities of the ESQL/C preprocessor when you write ESQL/C code:

• The include directive expands ESQL/C include files within your program.
• The define and undef directives create compile-time definitions.
• The ifdef, ifndef, else, elif, and endif directives specify conditional compilation.

As with embedded SQL statements, you can use either of two formats for ESQL/C preprocessor directives:

• The EXEC SQL keywords:
EXEC SQL preprocessor_directive;
• The dollar sign ($) notation:
$preprocessor_directive;

Important: The EXEC SQL keywords conform to ANSI standards.

In either of these formats, replace preprocessor_directive with one of the valid preprocessor directives that the following sections describe. You must terminate these directives with a semicolon (;).

The ESQL/C preprocessor works in two stages. In stage 1, it acts as a preprocessor for the ESQL/C code. In stage 2, it converts all of the embedded SQL code to C code.

In stage 1, the ESQL/C preprocessor incorporates other files in the source file by processing all include directives ($include and EXEC SQL include statements). Also in stage 1, ESQL/C creates or removes compile-time definitions by processing all define ($define and EXEC SQL define) and undef ($undef and EXEC SQL undef) directives.

The remainder of this section describes each of the ESQL/C preprocessor directives in more detail.

The include directive allows you to specify a file to include within your ESQL/C program. The ESQL/C preprocessor places the contents of the specified file into the ESQL/C source file. Stage 1 of the ESQL/C preprocessor reads the contents of filename into the current file at the position of the include directive.

You can use the include preprocessor directive in either of the following two formats:

• EXEC SQL include filename;
• $include filename;

Replace filename with the name of the file you want to include in your program. You can specify filename with or without quotation marks. If you use a full pathname, however, you must enclose the pathname in quotation marks.

The following example shows how to use full pathnames in a Windows environment.

EXEC SQL include decimal.h;



EXEC SQL include "C:\apps\finances\credits.h";



Tip: If you specify the full pathname, you must recompile the program if the location of the file changes. Better programming practice specifies search locations with the esql -I option and specifies only the filename with the include directive.

If you omit the quotes around the filename, ESQL/C changes the filename to lowercase characters. If you omit the pathname, the ESQL/C preprocessor checks the preprocessor search path for the file. For more information on this search path, see Naming the Location of Include Files.

You can use include for the following types of files:

• An ESQL/C header file

You do not have to use the .h file extension for an ESQL/C header file; the compiler assumes that your program refers to a file with a .h extension. The following examples show valid statements to include ESQL/C header files:

EXEC SQL include varchar.h;
$include sqlda;
EXEC SQL include sqlstype;

For a complete list of ESQL/C header files, see Using ESQL/C Header Files.

• Other user-defined files

You must specify the exact name of the file that you wish to include. The compiler does not assume the .h extension when you include a header file that is not an ESQL/C header file.

The following examples show valid statements to include the files constant_defs and typedefs.h in a UNIX environment:

EXEC SQL include constant_defs;
EXEC SQL include "constant_defs";
$include typedefs.h;
EXEC SQL include "typedefs.h";

You must use the ESQL/C include directive if the file you specify contains embedded SQL statements, or other ESQL/C statements.

Use the standard C #include directive to include system header files. The #include of C includes a file after ESQL/C preprocessing.

The ESQL/C preprocessor allows you to create simple variables that are available only to the ESQL/C preprocessor. Informix calls these variables definitions. The ESQL/C preprocessor manages these definitions with two directives:

The ESQL/C preprocessor rather than the C preprocessor (which processes #define and #undef) processes these directives. The ESQL/C preprocessor creates (define) or removes (undef) these definitions in stage 1 of preprocessing.

The ESQL/C define directive can create definitions with the following formats:

• The format for Boolean symbols is
define symbolname;

The following examples show the two ways to define a Boolean symbol that is called TRANS:

EXEC SQL define TRANS;
$define TRANS;

• The format for integer constants is
define symbolname value;

The following examples show both formats for two integer constants, MAXROWS (with a value of 25), and USETRANSACTIONS (with a value of 1):

EXEC SQL define MAXROWS 25;
$define MAXROWS 25;

EXEC SQL define USETRANSACTIONS 1;
$define USETRANSACTIONS 1;

Important: Unlike the C #define statement, the define directive does not support string constants or macros of statements that receive values at runtime.

You can override define and undef statements in the source program with the esql command line options, -ED and -EU. For more information about these options, see Defining and Undefining Definitions While Preprocessing.

The ESQL/C preprocessor supports the following directives for conditional compilation:

In the following example, the BEGIN WORK statement only compiles if you previously defined the name USETRANSACTIONS with a define directive:

EXEC SQL ifdef  USETRANSACTIONS;

EXEC SQL begin  work;

EXEC SQL endif;

The following example illustrates the use of the elif statement. This sample code will print "USETRANSACTIONS defined".
EXEC SQL define USETRANSACTIONS;
	

	EXEC SQL ifndef USETRANSACTIONS;

		printf("USETRANSACTIONS not defined");

	EXEC SQL elif USETRANSACTIONS;

		printf("USETRANSACTIONS defined");

	EXEC SQL endif;

The ESQL/C preprocessor does not support a general if directive; it supports only the ifdef and ifndef statements that test whether a name was defined with define.

The ESQL/C preprocessor processes conditional compilation definitions in stage 1 of the preprocessing.