<!--
doc/src/sgml/ref/ecpg-ref.sgml
PostgreSQL documentation
-->

<refentry id="app-ecpg">
 <indexterm zone="app-ecpg">
  <primary>ecpg</primary>
 </indexterm>

 <refmeta>
  <refentrytitle><application>ecpg</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname><application>ecpg</application></refname>
  <refpurpose>embedded SQL C preprocessor</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>ecpg</command>
   <arg choice="opt" rep="repeat"><replaceable>option</replaceable></arg>
   <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>


 <refsect1 id="app-ecpg-description">
  <title>Description</title>

  <para>
   <command>ecpg</command> is the embedded SQL preprocessor for C
   programs.  It converts C programs with embedded SQL statements to
   normal C code by replacing the SQL invocations with special
   function calls.  The output files can then be processed with any C
   compiler tool chain.
  </para>

  <para>
   <command>ecpg</command> will convert each input file given on the
   command line to the corresponding C output file.  If an input file
   name does not have any extension, <filename>.pgc</filename> is
   assumed.  The file's extension will be replaced
   by <filename>.c</filename> to construct the output file name.
   But the output file name can be overridden using the
   <option>-o</option> option.
  </para>

  <para>
   If an input file name is just <literal>-</literal>,
   <command>ecpg</command> reads the program from standard input
   (and writes to standard output, unless that is overridden
   with <option>-o</option>).
  </para>

  <para>
   This reference page does not describe the embedded SQL language.
   See <xref linkend="ecpg"/> for more information on that topic.
  </para>
 </refsect1>


 <refsect1>
  <title>Options</title>

  <para>
   <command>ecpg</command> accepts the following command-line
   arguments:

   <variablelist>
    <varlistentry>
     <term><option>-c</option></term>
     <listitem>
      <para>
       Automatically generate certain C code from SQL code.  Currently, this
       works for <literal>EXEC SQL TYPE</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-C <replaceable>mode</replaceable></option></term>
     <listitem>
      <para>
       Set a compatibility mode.  <replaceable>mode</replaceable> can
       be <literal>INFORMIX</literal>,
       <literal>INFORMIX_SE</literal>, or <literal>ORACLE</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-D <replaceable>symbol</replaceable>[=<replaceable>value</replaceable>]</option></term>
     <listitem>
      <para>
       Define a preprocessor symbol, equivalently to the <command>EXEC SQL
       DEFINE</command> directive.  If no <replaceable>value</replaceable> is
       specified, the symbol is defined with the value <literal>1</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-h</option></term>
     <listitem>
      <para>
       Process header files.  When this option is specified, the output file
       extension becomes <literal>.h</literal> not <literal>.c</literal>,
       and the default input file extension is <literal>.pgh</literal>
       not <literal>.pgc</literal>.  Also, the <option>-c</option> option is
       forced on.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-i</option></term>
     <listitem>
      <para>
       Parse system include files as well.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-I <replaceable class="parameter">directory</replaceable></option></term>
     <listitem>
      <para>
       Specify an additional include path, used to find files included
       via <literal>EXEC SQL INCLUDE</literal>.  Defaults