The first four lines written by ecpg to the
output are fixed lines. Two are comments and two are include
lines necessary to interface to the library. Then the
preprocessor reads through the file and writes output. Normally
it just echoes everything to the output.
When it sees an EXEC SQL statement, it
intervenes and changes it. The command starts with exec
sql and ends with ;. Everything in
between is treated as an SQL statement and
parsed for variable substitution.
Variable substitution occurs when a symbol starts with a colon
(:). The variable with that name is looked up
among the variables that were previously declared within a
EXEC SQL DECLARE section. Depending on whether the
variable is being use for input or output, a pointer to the
variable is output to allow access by the function.
For every variable that is part of the SQL
query, the function gets other arguments:
The type as a special symbol.
A pointer to the value or a pointer to the pointer.
The size of the variable if it is a char or varchar.
The number of elements in the array (for array fetches).
The offset to the next element in the array (for array fetches).
The type of the indicator variable as a special symbol.
A pointer to the value of the indicator variable or a pointer
to the pointer of the indicator variable.
Number of elements in the indicator array (for array fetches).
The offset to the next element in the indicator array (for
Note that not all SQL commands are treated in this way. For
instance, an open cursor statement like
EXEC SQL OPEN cursor;
is not copied to the output. Instead, the cursor's
DECLARE command is used because it opens the cursor as
Here is a complete example describing the output of the
preprocessor of a file foo.pgc (details may
change with each particular version of the preprocessor):
EXEC SQL BEGIN DECLARE SECTION;
EXEC SQL END DECLARE SECTION;
EXEC SQL SELECT res INTO :result FROM mytable WHERE index = :index;
is translated into:
/* Processed by ecpg (2.6.0) */
/* These two include files are added by the preprocessor */
/* exec sql begin declare section */
#line 1 "foo.pgc"
/* exec sql end declare section */
ECPGdo(__LINE__, NULL, "SELECT res FROM mytable WHERE index = ? ",
ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
#line 147 "foo.pgc"
(The indentation in this manual is added for readability and not
something the preprocessor does.)