| <!-- |
| $PostgreSQL: pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.31 2006/09/16 00:30:18 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> |
| |
| <indexterm zone="app-ecpg"> |
| <primary>ecpg</primary> |
| </indexterm> |
| |
| <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 |
| preferably 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 <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> may |
| be <literal>INFORMIX</literal> or |
| <literal>INFORMIX_SE</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</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 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 <command>ecpg</command> should write all |
| its output to the given <replaceable>filename</replaceable>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-r <replaceable>option</replaceable></option></term> |
| <listitem> |
| <para> |
| Selects a run-time behavior. Currently, |
| <replaceable>option</replaceable> can only be |
| <literal>no_indicator</literal>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-t</option></term> |
| <listitem> |
| <para> |
| Turn on autocommit of transactions. In this mode, each SQL command is |
| automatically committed unless it is inside an explicit |
| transaction block. In the default mode, commands 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 |
| linker options <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> |
| |
| </refentry> |