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