postgres/doc/src/sgml/ref/ecpg-ref.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.24 2003/01/19 00:13:29 momjian Exp $
PostgreSQL documentation
-->

<refentry id="APP-ECPG">
 <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.  Input files
   preferrably have the extension <filename>.pgc</filename>, in which
   case the extension will be replaced by <filename>.c</filename> to
   determine the output file name.  If the extension of the input file
   is not <filename>.pgc</filename>, then the output file name is
   computed by appending <literal>.c</literal> to the full file name.
   The output file name can also be overridden using the
   <option>-o</option> option.
  </para>

  <para>
   This reference page does not describe the embedded SQL language.
   See the &cite-programmer; 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 C code from SQL code.  Currently, this
       works for <literal>EXEC SQL TYPE</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-D <replaceable>symbol</replaceable></option></term>
     <listitem>
      <para>
       Define a C preprocessor symbol.
      </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 are
       <filename>.</filename> (current directory),
       <filename>/usr/local/include</filename>, the
       <productname>PostgreSQL</productname> include directory which
       is defined at compile time (default:
       <filename>/usr/local/pgsql/include</filename>), and
       <filename>/usr/include</filename>, in that order.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-o <replaceable>filename</replaceable></option></term>
     <listitem>
      <para>
       Specifies that <application>ecpg</application> should write all
       its output to the given <replaceable>filename</replaceable>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-t</option></term>
     <listitem>
      <para>
       Turn on autocommit of transactions. In this mode, each query is
       automatically committed unless it is inside an explicit
       transaction block. In the default mode, queries are committed
       only when <command>EXEC SQL COMMIT</command> is issued.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term><option>-v</option></term>
     <listitem>
      <para>
       Print additional information including the version and the
       include path.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>---help</option></term>
     <listitem>
      <para>
       Show a brief summary of the command usage, then exit.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>--version</option></term>
     <listitem>
      <para>
       Output version information, then exit.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>


 <refsect1>
  <title>Notes</title>

  <para>
   When compiling the preprocessed C code files, the compiler needs to
   be able to find the <application>ECPG</> header files in the
   <productname>PostgreSQL</> include directory.  Therefore, one might
   have to use the <option>-I</> option when invoking the compiler
   (e.g., <literal>-I/usr/local/pgsql/include</literal>).
  </para>

  <para>
   Programs using C code with embedded SQL have to be linked against
   the <filename>libecpg</filename> library, for example using the
   flags <literal>-L/usr/local/pgsql/lib -lecpg</literal>.
  </para>

  <para>
   The value of either of these directories that is appropriate for
   the installation can be found out using <xref
   linkend="app-pgconfig">.
  </para>
 </refsect1>


 <refsect1>
  <title>Examples</title>

  <para>
   If you have an embedded SQL C source file named
   <filename>prog1.pgc</filename>, you can create an executable
   program using the following sequence of commands:
<programlisting>
ecpg prog1.pgc
cc -I/usr/local/pgsql/include -c prog1.c
cc -o prog1 prog1.o -L/usr/local/pgsql/lib -lecpg
</programlisting>
  </para>
 </refsect1>


 <refsect1>
  <title>See Also</title>

  <para>
   &cite-programmer; for a more detailed description of the embedded
   SQL interface
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->