33.16. Internals

This section explains howECPG works internally. This information can occasionally be useful to help users understand how to useECPG.

The first four lines written byecpg 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 anEXEC SQL statement, it intervenes and changes it. The command starts withEXEC SQL and ends with;. Everything in between is treated as anSQL 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 aEXEC SQL DECLARE section.

The most important function in the library isECPGdo, which takes care of executing most commands. It takes a variable number of arguments. This can easily add up to 50 or so arguments, and we hope this will not be a problem on any platform.

The arguments are:

For every variable that is part of theSQL command, the function gets ten arguments:

1. The type as a special symbol.

2. A pointer to the value or a pointer to the pointer.

3. The size of the variable if it is achar orvarchar.

4. The number of elements in the array (for array fetches).

5. The offset to the next element in the array (for array fetches).

6. The type of the indicator variable as a special symbol.

7. A pointer to the indicator variable.

8. 0

9. The number of elements in the indicator array (for array fetches).

10. The offset to the next element in the indicator array (for array fetches).

Note that not all SQL commands are treated in this way. For instance, an open cursor statement like:

EXEC SQL OPENcursor;

is not copied to the output. Instead, the cursor'sDECLARE command is used at the position of theOPEN command because it indeed opens the cursor.

Here is a complete example describing the output of the preprocessor of a filefoo.pgc (details might change with each particular version of the preprocessor):

EXEC SQL BEGIN DECLARE SECTION;int index;int result;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 */#include <ecpgtype.h>;#include <ecpglib.h>;/* exec sql begin declare section */#line 1 "foo.pgc" int index; int result;/* exec sql end declare section */...ECPGdo(__LINE__, NULL, "SELECT res FROM mytable WHERE index = ?     ",        ECPGt_int,&(index),1L,1L,sizeof(int),        ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,        ECPGt_int,&(result),1L,1L,sizeof(int),        ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);#line 147 "foo.pgc"

(The indentation here is added for readability and not something the preprocessor does.)