<title>Preprocessor Directives</title>

  <para>
   Several preprocessor directives are available that modify how
   the <command>ecpg</command> preprocessor parses and processes a
   file.
  </para>

  <sect2 id="ecpg-include">
   <title>Including Files</title>

   <para>
    To include an external file into your embedded SQL program, use:
<programlisting>
EXEC SQL INCLUDE <replaceable>filename</replaceable>;
EXEC SQL INCLUDE &lt;<replaceable>filename</replaceable>&gt;;
EXEC SQL INCLUDE "<replaceable>filename</replaceable>";
</programlisting>
    The embedded SQL preprocessor will look for a file named
    <literal><replaceable>filename</replaceable>.h</literal>,
    preprocess it, and include it in the resulting C output.  Thus,
    embedded SQL statements in the included file are handled correctly.
   </para>

   <para>
    The <command>ecpg</command> preprocessor will search a file at
    several directories in following order:

    <itemizedlist>
     <listitem><simpara>current directory</simpara></listitem>
     <listitem><simpara><filename>/usr/local/include</filename></simpara></listitem>
     <listitem><simpara>PostgreSQL include directory, defined at build time (e.g., <filename>/usr/local/pgsql/include</filename>)</simpara></listitem>
     <listitem><simpara><filename>/usr/include</filename></simpara></listitem>
    </itemizedlist>

    But when <literal>EXEC SQL INCLUDE
    "<replaceable>filename</replaceable>"</literal> is used, only the
    current directory is searched.
   </para>

   <para>
    In each directory, the preprocessor will first look for the file
    name as given, and if not found will append <literal>.h</literal>
    to the file name and try again (unless the specified file name
    already has that suffix).
   </para>

   <para>
    Note that <command>EXEC SQL INCLUDE</command> is <emphasis>not</emphasis> the same as:
<programlisting>
#include &lt;<replaceable>filename</replaceable>.h&gt;
</programlisting>
    because this file would not be subject to SQL command preprocessing.
    Naturally, you can continue to use the C
    <literal>#include</literal> directive to include other header
    files.
   </para>

   <note>
    <para>
     The include file name is case-sensitive, even though the rest of
     the <literal>EXEC SQL INCLUDE</literal> command follows the normal
     SQL case-sensitivity rules.
    </para>
   </note>
  </sect2>

  <sect2 id="ecpg-define">
   <title>The define and undef Directives</title>
   <para>
    Similar to the directive <literal>#define</literal> that is known from C,
    embedded SQL has a similar concept:
<programlisting>
EXEC SQL DEFINE <replaceable>name</replaceable>;
EXEC SQL DEFINE <replaceable>name</replaceable> <replaceable>value</replaceable>;
</programlisting>
    So you can define a name:
<programlisting>
EXEC SQL DEFINE HAVE_FEATURE;
</programlisting>
    And you can also define constants:
<programlisting>
EXEC SQL DEFINE MYNUMBER 12;
EXEC SQL DEFINE MYSTRING 'abc';
</programlisting>
    Use <literal>undef</literal> to remove a previous definition:
<programlisting>
EXEC SQL UNDEF MYNUMBER;
</programlisting>
   </para>

   <para>
    Of course you can continue to use the C versions <literal>#define</literal>
    and <literal>#undef</literal> in your embedded SQL program. The difference
    is where your defined values get evaluated. If you use <literal>EXEC SQL
    DEFINE</literal> then the <command>ecpg</command> preprocessor evaluates the defines and substitutes
    the values. For example if you write:
<programlisting>
EXEC SQL DEFINE MYNUMBER 12;
...
EXEC SQL UPDATE Tbl SET col = MYNUMBER;
</programlisting>
    then <command>ecpg</command> will already do the substitution and your C compiler will never
    see any name or identifier <literal>MYNUMBER</literal>. Note that you cannot use
    <literal>#define</literal> for a constant that you are going to use in an
    embedded SQL query because in this case the embedded SQL precompiler is not
    able to