1<!--
2doc/src/sgml/ref/ecpg-ref.sgml
3PostgreSQL documentation
4-->
5
6<refentry id="APP-ECPG">
7 <indexterm zone="app-ecpg">
8  <primary>ecpg</primary>
9 </indexterm>
10
11 <refmeta>
12  <refentrytitle><application>ecpg</application></refentrytitle>
13  <manvolnum>1</manvolnum>
14  <refmiscinfo>Application</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18  <refname><application>ecpg</application></refname>
19  <refpurpose>embedded SQL C preprocessor</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23  <cmdsynopsis>
24   <command>ecpg</command>
25   <arg choice="opt" rep="repeat"><replaceable>option</replaceable></arg>
26   <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
27  </cmdsynopsis>
28 </refsynopsisdiv>
29
30
31 <refsect1 id="APP-ECPG-description">
32  <title>Description</title>
33
34  <para>
35   <command>ecpg</command> is the embedded SQL preprocessor for C
36   programs.  It converts C programs with embedded SQL statements to
37   normal C code by replacing the SQL invocations with special
38   function calls.  The output files can then be processed with any C
39   compiler tool chain.
40  </para>
41
42  <para>
43   <command>ecpg</command> will convert each input file given on the
44   command line to the corresponding C output file.  If an input file
45   name does not have any extension, <filename>.pgc</filename> is
46   assumed.  The file's extension will be replaced
47   by <filename>.c</filename> to construct the output file name.
48   But the output file name can be overridden using the
49   <option>-o</option> option.
50  </para>
51
52  <para>
53   If an input file name is just <literal>-</literal>,
54   <command>ecpg</command> reads the program from standard input
55   (and writes to standard output, unless that is overridden
56   with <option>-o</option>).
57  </para>
58
59  <para>
60   This reference page does not describe the embedded SQL language.
61   See <xref linkend="ecpg"> for more information on that topic.
62  </para>
63 </refsect1>
64
65
66 <refsect1>
67  <title>Options</title>
68
69  <para>
70   <command>ecpg</command> accepts the following command-line
71   arguments:
72
73   <variablelist>
74    <varlistentry>
75     <term><option>-c</option></term>
76     <listitem>
77      <para>
78       Automatically generate certain C code from SQL code.  Currently, this
79       works for <literal>EXEC SQL TYPE</literal>.
80      </para>
81     </listitem>
82    </varlistentry>
83
84    <varlistentry>
85     <term><option>-C <replaceable>mode</replaceable></option></term>
86     <listitem>
87      <para>
88       Set a compatibility mode.  <replaceable>mode</replaceable> can
89       be <literal>INFORMIX</literal> or
90       <literal>INFORMIX_SE</literal>.
91      </para>
92     </listitem>
93    </varlistentry>
94
95    <varlistentry>
96     <term><option>-D <replaceable>symbol</replaceable></option></term>
97     <listitem>
98      <para>
99       Define a C preprocessor symbol.
100      </para>
101     </listitem>
102    </varlistentry>
103
104    <varlistentry>
105     <term><option>-h</option></term>
106     <listitem>
107      <para>
108       Process header files.  When this option is specified, the output file
109       extension becomes <literal>.h</literal> not <literal>.c</literal>,
110       and the default input file extension is <literal>.pgh</literal>
111       not <literal>.pgc</literal>.  Also, the <option>-c</option> option is
112       forced on.
113      </para>
114     </listitem>
115    </varlistentry>
116
117    <varlistentry>
118     <term><option>-i</option></term>
119     <listitem>
120      <para>
121       Parse system include files as well.
122      </para>
123     </listitem>
124    </varlistentry>
125
126    <varlistentry>
127     <term><option>-I <replaceable class="parameter">directory</replaceable></option></term>
128     <listitem>
129      <para>
130       Specify an additional include path, used to find files included
131       via <literal>EXEC SQL INCLUDE</literal>.  Defaults are
132       <filename>.</filename> (current directory),
133       <filename>/usr/local/include</filename>, the
134       <productname>PostgreSQL</productname> include directory which
135       is defined at compile time (default:
136       <filename>/usr/local/pgsql/include</filename>), and
137       <filename>/usr/include</filename>, in that order.
138      </para>
139     </listitem>
140    </varlistentry>
141
142    <varlistentry>
143     <term><option>-o <replaceable>filename</replaceable></option></term>
144     <listitem>
145      <para>
146       Specifies that <command>ecpg</command> should write all
147       its output to the given <replaceable>filename</replaceable>.
148       Write <literal>-o -</literal> to send all output to standard output.
149      </para>
150     </listitem>
151    </varlistentry>
152
153    <varlistentry>
154     <term><option>-r <replaceable>option</replaceable></option></term>
155     <listitem>
156      <para>
157       Selects run-time behavior.  <replaceable>Option</replaceable> can be
158       one of the following:
159       <variablelist>
160        <varlistentry>
161         <term><option>no_indicator</option></term>
162         <listitem>
163         <para>
164         Do not use indicators but instead use special values to represent
165         null values. Historically there have been databases using this approach.
166         </para>
167         </listitem>
168        </varlistentry>
169        <varlistentry>
170         <term><option>prepare</option></term>
171         <listitem>
172         <para>
173         Prepare all statements before using them. Libecpg will keep a cache of
174         prepared statements and reuse a statement if it gets executed again. If the
175         cache runs full, libecpg will free the least used statement.
176         </para>
177         </listitem>
178        </varlistentry>
179        <varlistentry>
180         <term><option>questionmarks</option></term>
181         <listitem>
182         <para>
183         Allow question mark as placeholder for compatibility reasons.
184         This used to be the default long ago.
185         </para>
186         </listitem>
187        </varlistentry>
188       </variablelist></para>
189     </listitem>
190    </varlistentry>
191
192    <varlistentry>
193     <term><option>-t</option></term>
194     <listitem>
195      <para>
196       Turn on autocommit of transactions. In this mode, each SQL command is
197       automatically committed unless it is inside an explicit
198       transaction block. In the default mode, commands are committed
199       only when <command>EXEC SQL COMMIT</command> is issued.
200      </para>
201     </listitem>
202    </varlistentry>
203
204    <varlistentry>
205     <term><option>-v</option></term>
206     <listitem>
207      <para>
208       Print additional information including the version and the
209       "include" path.
210      </para>
211     </listitem>
212    </varlistentry>
213
214    <varlistentry>
215     <term><option>--version</option></term>
216     <listitem>
217      <para>
218       Print the <application>ecpg</application> version and exit.
219      </para>
220     </listitem>
221    </varlistentry>
222
223    <varlistentry>
224     <term><option>-?</option></term>
225     <term><option>--help</option></term>
226     <listitem>
227      <para>
228       Show help about <application>ecpg</application> command line
229       arguments, and exit.
230      </para>
231     </listitem>
232    </varlistentry>
233
234   </variablelist>
235  </para>
236 </refsect1>
237
238
239 <refsect1>
240  <title>Notes</title>
241
242  <para>
243   When compiling the preprocessed C code files, the compiler needs to
244   be able to find the <application>ECPG</> header files in the
245   <productname>PostgreSQL</> include directory.  Therefore, you might
246   have to use the <option>-I</> option when invoking the compiler
247   (e.g., <literal>-I/usr/local/pgsql/include</literal>).
248  </para>
249
250  <para>
251   Programs using C code with embedded SQL have to be linked against
252   the <filename>libecpg</filename> library, for example using the
253   linker options <literal>-L/usr/local/pgsql/lib -lecpg</literal>.
254  </para>
255
256  <para>
257   The value of either of these directories that is appropriate for
258   the installation can be found out using <xref
259   linkend="app-pgconfig">.
260  </para>
261 </refsect1>
262
263
264 <refsect1>
265  <title>Examples</title>
266
267  <para>
268   If you have an embedded SQL C source file named
269   <filename>prog1.pgc</filename>, you can create an executable
270   program using the following sequence of commands:
271<programlisting>
272ecpg prog1.pgc
273cc -I/usr/local/pgsql/include -c prog1.c
274cc -o prog1 prog1.o -L/usr/local/pgsql/lib -lecpg
275</programlisting></para>
276 </refsect1>
277
278</refentry>
279