C-preprocessor directives v17

The ECPGPlus C-preprocessor enforces two behaviors that depend on the mode in which you invoke ECPGPlus:

• PROC mode
• Non-PROC mode

Compiling in PROC mode

In PROC mode, ECPGPlus allows you to:

• Declare host variables outside of an EXEC SQL BEGIN/END DECLARE SECTION.
• Use any C variable as a host variable as long as its data type is compatible with ECPG.

When you invoke ECPGPlus in PROC mode (by including the -C PROC keywords), the ECPG compiler honors the following C-preprocessor directives:

#include
#if expression
#ifdef symbolName
#ifndef symbolName
#else
#elif expression
#endif
#define symbolName expansion
#define symbolName([macro arguments]) expansion
#undef symbolName
#defined(symbolName)

Preprocessor directives are used to affect or direct the code that's received by the compiler. For example, consider the following code sample:

#if HAVE_LONG_LONG == 1
#define BALANCE_TYPE long long
#else
#define BALANCE_TYPE double
#endif
...
BALANCE_TYPE customerBalance;

Suppose you invoke ECPGPlus with the following command-line arguments:

ecpg –C PROC –DHAVE_LONG_LONG=1

ECPGPlus copies the entire fragment, without change, to the output file. It sends only the following tokens to the ECPG parser:

long long customerBalance;

On the other hand, suppose you invoke ECPGPlus with the following command-line arguments:

ecpg –C PROC –DHAVE_LONG_LONG=0

The ECPG parser receives the following tokens:

double customerBalance;

If your code uses preprocessor directives to filter the code that's sent to the compiler, the complete code is retained in the original code, while the ECPG parser sees only the processed token stream.

You can also use compatible syntax when executing the following preprocessor directives with an EXEC directive:

EXEC ORACLE DEFINE
EXEC ORACLE UNDEF
EXEC ORACLE INCLUDE
EXEC ORACLE IFDEF
EXEC ORACLE IFNDEF
EXEC ORACLE ELIF
EXEC ORACLE ELSE
EXEC ORACLE ENDIF
EXEC ORACLE OPTION

For example, suppose your code includes the following:

EXEC ORACLE IFDEF HAVE_LONG_LONG;
#define BALANCE_TYPE long long
EXEC ORACLE ENDIF;
BALANCE_TYPE customerBalance;

You invoke ECPGPlus with the following command-line arguments:

ecpg –C PROC DEFINE=HAVE_LONG_LONG=1

ECPGPlus sends the following tokens to the output file and the ECPG parser:

long long customerBalance;

Using the SELECT_ERROR precompiler option

When using ECPGPlus in compatible mode, you can use the SELECT_ERROR precompiler option to tell your program how to handle result sets that contain more rows than the host variable can accommodate. The syntax is:

SELECT_ERROR={YES|NO}

The default value is YES. A SELECT statement returns an error message if the result set exceeds the capacity of the host variable. Specify NO to suppress error messages when a SELECT statement returns more rows than a host variable can accommodate.

Use SELECT_ERROR with the EXEC ORACLE OPTION directive.

Compiling in non-PROC mode

If you don't include the -C PROC command-line option:

• C preprocessor directives are copied to the output file without change.
• You must declare the type and name of each C variable that you intend to use as a host variable in an EXEC SQL BEGIN/END DECLARE section.

When invoked in non-PROC mode, ECPG implements the behavior described in the PostgreSQL core documentation.