begriffs open source - ai-pg/blob - full-docs/txt/ecpg-preproc.txt

   1
   2 34.9. Preprocessor Directives #
   3
   4    34.9.1. Including Files
   5    34.9.2. The define and undef Directives
   6    34.9.3. ifdef, ifndef, elif, else, and endif Directives
   7
   8    Several preprocessor directives are available that modify how the ecpg
   9    preprocessor parses and processes a file.
  10
  11 34.9.1. Including Files #
  12
  13    To include an external file into your embedded SQL program, use:
  14 EXEC SQL INCLUDE filename;
  15 EXEC SQL INCLUDE <filename>;
  16 EXEC SQL INCLUDE "filename";
  17
  18    The embedded SQL preprocessor will look for a file named filename.h,
  19    preprocess it, and include it in the resulting C output. Thus, embedded
  20    SQL statements in the included file are handled correctly.
  21
  22    The ecpg preprocessor will search a file at several directories in
  23    following order:
  24      * current directory
  25      * /usr/local/include
  26      * PostgreSQL include directory, defined at build time (e.g.,
  27        /usr/local/pgsql/include)
  28      * /usr/include
  29
  30    But when EXEC SQL INCLUDE "filename" is used, only the current
  31    directory is searched.
  32
  33    In each directory, the preprocessor will first look for the file name
  34    as given, and if not found will append .h to the file name and try
  35    again (unless the specified file name already has that suffix).
  36
  37    Note that EXEC SQL INCLUDE is not the same as:
  38 #include <filename.h>
  39
  40    because this file would not be subject to SQL command preprocessing.
  41    Naturally, you can continue to use the C #include directive to include
  42    other header files.
  43
  44 Note
  45
  46    The include file name is case-sensitive, even though the rest of the
  47    EXEC SQL INCLUDE command follows the normal SQL case-sensitivity rules.
  48
  49 34.9.2. The define and undef Directives #
  50
  51    Similar to the directive #define that is known from C, embedded SQL has
  52    a similar concept:
  53 EXEC SQL DEFINE name;
  54 EXEC SQL DEFINE name value;
  55
  56    So you can define a name:
  57 EXEC SQL DEFINE HAVE_FEATURE;
  58
  59    And you can also define constants:
  60 EXEC SQL DEFINE MYNUMBER 12;
  61 EXEC SQL DEFINE MYSTRING 'abc';
  62
  63    Use undef to remove a previous definition:
  64 EXEC SQL UNDEF MYNUMBER;
  65
  66    Of course you can continue to use the C versions #define and #undef in
  67    your embedded SQL program. The difference is where your defined values
  68    get evaluated. If you use EXEC SQL DEFINE then the ecpg preprocessor
  69    evaluates the defines and substitutes the values. For example if you
  70    write:
  71 EXEC SQL DEFINE MYNUMBER 12;
  72 ...
  73 EXEC SQL UPDATE Tbl SET col = MYNUMBER;
  74
  75    then ecpg will already do the substitution and your C compiler will
  76    never see any name or identifier MYNUMBER. Note that you cannot use
  77    #define for a constant that you are going to use in an embedded SQL
  78    query because in this case the embedded SQL precompiler is not able to
  79    see this declaration.
  80
  81    If multiple input files are named on the ecpg preprocessor's command
  82    line, the effects of EXEC SQL DEFINE and EXEC SQL UNDEF do not carry
  83    across files: each file starts with only the symbols defined by -D
  84    switches on the command line.
  85
  86 34.9.3. ifdef, ifndef, elif, else, and endif Directives #
  87
  88    You can use the following directives to compile code sections
  89    conditionally:
  90
  91    EXEC SQL ifdef name; #
  92           Checks a name and processes subsequent lines if name has been
  93           defined via EXEC SQL define name.
  94
  95    EXEC SQL ifndef name; #
  96           Checks a name and processes subsequent lines if name has not
  97           been defined via EXEC SQL define name.
  98
  99    EXEC SQL elif name; #
 100           Begins an optional alternative section after an EXEC SQL ifdef
 101           name or EXEC SQL ifndef name directive. Any number of elif
 102           sections can appear. Lines following an elif will be processed
 103           if name has been defined and no previous section of the same
 104           ifdef/ifndef...endif construct has been processed.
 105
 106    EXEC SQL else; #
 107           Begins an optional, final alternative section after an EXEC SQL
 108           ifdef name or EXEC SQL ifndef name directive. Subsequent lines
 109           will be processed if no previous section of the same
 110           ifdef/ifndef...endif construct has been processed.
 111
 112    EXEC SQL endif; #
 113           Ends an ifdef/ifndef...endif construct. Subsequent lines are
 114           processed normally.
 115
 116    ifdef/ifndef...endif constructs can be nested, up to 127 levels deep.
 117
 118    This example will compile exactly one of the three SET TIMEZONE
 119    commands:
 120 EXEC SQL ifdef TZVAR;
 121 EXEC SQL SET TIMEZONE TO TZVAR;
 122 EXEC SQL elif TZNAME;
 123 EXEC SQL SET TIMEZONE TO TZNAME;
 124 EXEC SQL else;
 125 EXEC SQL SET TIMEZONE TO 'GMT';
 126 EXEC SQL endif;