Debian Codegraph @

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

raw
1 <!--
2 doc/src/sgml/ref/ecpg-ref.sgml
3 PostgreSQL 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>,
90 <literal>INFORMIX_SE</literal>, or <literal>ORACLE</literal>.
91 </para>
92 </listitem>
93 </varlistentry>
94
95 <varlistentry>
96 <term><option>-D <replaceable>symbol</replaceable>[=<replaceable>value</replaceable>]</option></term>
97 <listitem>
98 <para>
99 Define a preprocessor symbol, equivalently to the <command>EXEC SQL
100 DEFINE</command> directive. If no <replaceable>value</replaceable> is
101 specified, the symbol is defined with the value <literal>1</literal>.
102 </para>
103 </listitem>
104 </varlistentry>
105
106 <varlistentry>
107 <term><option>-h</option></term>
108 <listitem>
109 <para>
110 Process header files. When this option is specified, the output file
111 extension becomes <literal>.h</literal> not <literal>.c</literal>,
112 and the default input file extension is <literal>.pgh</literal>
113 not <literal>.pgc</literal>. Also, the <option>-c</option> option is
114 forced on.
115 </para>
116 </listitem>
117 </varlistentry>
118
119 <varlistentry>
120 <term><option>-i</option></term>
121 <listitem>
122 <para>
123 Parse system include files as well.
124 </para>
125 </listitem>
126 </varlistentry>
127
128 <varlistentry>
129 <term><option>-I <replaceable class="parameter">directory</replaceable></option></term>
130 <listitem>
131 <para>
132 Specify an additional include path, used to find files included
133 via <literal>EXEC SQL INCLUDE</literal>. Defaults are
134 <filename>.</filename> (current directory),
135 <filename>/usr/local/include</filename>, the
136 <productname>PostgreSQL</productname> include directory which
137 is defined at compile time (default:
138 <filename>/usr/local/pgsql/include</filename>), and
139 <filename>/usr/include</filename>, in that order.
140 </para>
141 </listitem>
142 </varlistentry>
143
144 <varlistentry>
145 <term><option>-o <replaceable>filename</replaceable></option></term>
146 <listitem>
147 <para>
148 Specifies that <command>ecpg</command> should write all
149 its output to the given <replaceable>filename</replaceable>.
150 Write <literal>-o -</literal> to send all output to standard output.
151 </para>
152 </listitem>
153 </varlistentry>
154
155 <varlistentry>
156 <term><option>-r <replaceable>option</replaceable></option></term>
157 <listitem>
158 <para>
159 Selects run-time behavior. <replaceable>Option</replaceable> can be
160 one of the following:
161 <variablelist>
162 <varlistentry>
163 <term><option>no_indicator</option></term>
164 <listitem>
165 <para>
166 Do not use indicators but instead use special values to represent
167 null values. Historically there have been databases using this approach.
168 </para>
169 </listitem>
170 </varlistentry>
171 <varlistentry>
172 <term><option>prepare</option></term>
173 <listitem>
174 <para>
175 Prepare all statements before using them. Libecpg will keep a cache of
176 prepared statements and reuse a statement if it gets executed again. If the
177 cache runs full, libecpg will free the least used statement.
178 </para>
179 </listitem>
180 </varlistentry>
181 <varlistentry>
182 <term><option>questionmarks</option></term>
183 <listitem>
184 <para>
185 Allow question mark as placeholder for compatibility reasons.
186 This used to be the default long ago.
187 </para>
188 </listitem>
189 </varlistentry>
190 </variablelist></para>
191 </listitem>
192 </varlistentry>
193
194 <varlistentry>
195 <term><option>-t</option></term>
196 <listitem>
197 <para>
198 Turn on autocommit of transactions. In this mode, each SQL command is
199 automatically committed unless it is inside an explicit
200 transaction block. In the default mode, commands are committed
201 only when <command>EXEC SQL COMMIT</command> is issued.
202 </para>
203 </listitem>
204 </varlistentry>
205
206 <varlistentry>
207 <term><option>-v</option></term>
208 <listitem>
209 <para>
210 Print additional information including the version and the
211 "include" path.
212 </para>
213 </listitem>
214 </varlistentry>
215
216 <varlistentry>
217 <term><option>--version</option></term>
218 <listitem>
219 <para>
220 Print the <application>ecpg</application> version and exit.
221 </para>
222 </listitem>
223 </varlistentry>
224
225 <varlistentry>
226 <term><option>-?</option></term>
227 <term><option>--help</option></term>
228 <listitem>
229 <para>
230 Show help about <application>ecpg</application> command line
231 arguments, and exit.
232 </para>
233 </listitem>
234 </varlistentry>
235
236 </variablelist>
237 </para>
238 </refsect1>
239
240
241 <refsect1>
242 <title>Notes</title>
243
244 <para>
245 When compiling the preprocessed C code files, the compiler needs to
246 be able to find the <application>ECPG</application> header files in the
247 <productname>PostgreSQL</productname> include directory. Therefore, you might
248 have to use the <option>-I</option> option when invoking the compiler
249 (e.g., <literal>-I/usr/local/pgsql/include</literal>).
250 </para>
251
252 <para>
253 Programs using C code with embedded SQL have to be linked against
254 the <filename>libecpg</filename> library, for example using the
255 linker options <literal>-L/usr/local/pgsql/lib -lecpg</literal>.
256 </para>
257
258 <para>
259 The value of either of these directories that is appropriate for
260 the installation can be found out using <xref
261 linkend="app-pgconfig"/>.
262 </para>
263 </refsect1>
264
265
266 <refsect1>
267 <title>Examples</title>
268
269 <para>
270 If you have an embedded SQL C source file named
271 <filename>prog1.pgc</filename>, you can create an executable
272 program using the following sequence of commands:
273 <programlisting>
274 ecpg prog1.pgc
275 cc -I/usr/local/pgsql/include -c prog1.c
276 cc -o prog1 prog1.o -L/usr/local/pgsql/lib -lecpg
277 </programlisting></para>
278 </refsect1>
279
280 </refentry>