head	1.34;
access;
symbols
	REL9_0_0:1.34
	REL9_1_ALPHA1:1.34
	REL9_0_RC1:1.34
	REL9_0_BETA4:1.34
	REL9_0_STABLE:1.34.0.6
	REL9_0_BETA3:1.34
	REL9_0_BETA2:1.34
	REL7_4_29:1.29
	REL8_0_25:1.30
	REL8_1_21:1.30
	REL8_2_17:1.31
	REL8_3_11:1.32
	REL8_4_4:1.32
	REL9_0_BETA1:1.34
	REL9_0_ALPHA5_BRANCH:1.34.0.4
	REL9_0_ALPHA5:1.34
	REL7_4_28:1.29
	REL8_0_24:1.30
	REL8_1_20:1.30
	REL8_2_16:1.31
	REL8_3_10:1.32
	REL8_4_3:1.32
	REL9_0_ALPHA4:1.34
	REL9_0_ALPHA4_BRANCH:1.34.0.2
	REL8_5_ALPHA3:1.32
	REL8_5_ALPHA3_BRANCH:1.32.0.10
	REL7_4_27:1.29
	REL8_0_23:1.30
	REL8_1_19:1.30
	REL8_2_15:1.31
	REL8_3_9:1.32
	REL8_4_2:1.32
	REL8_5_ALPHA2:1.32
	REL8_5_ALPHA2_BRANCH:1.32.0.8
	REL7_4_26:1.29
	REL8_0_22:1.30
	REL8_1_18:1.30
	REL8_2_14:1.31
	REL8_3_8:1.32
	REL8_4_1:1.32
	REL8_5_ALPHA1:1.32
	REL8_5_ALPHA1_BRANCH:1.32.0.6
	REL8_4_STABLE:1.32.0.4
	REL8_4_0:1.32
	REL8_4_RC2:1.32
	REL8_4_RC1:1.32
	REL8_4_BETA2:1.32
	REL8_4_BETA1:1.32
	REL7_4_25:1.29
	REL8_0_21:1.30
	REL8_1_17:1.30
	REL8_2_13:1.31
	REL8_3_7:1.32
	REL7_4_24:1.29
	REL8_0_20:1.30
	REL8_1_16:1.30
	REL8_2_12:1.31
	REL8_3_6:1.32
	REL7_4_23:1.29
	REL8_0_19:1.30
	REL8_1_15:1.30
	REL8_2_11:1.31
	REL8_3_5:1.32
	REL7_4_22:1.29
	REL8_0_18:1.30
	REL8_1_14:1.30
	REL8_2_10:1.31
	REL8_3_4:1.32
	REL7_4_21:1.29
	REL8_0_17:1.30
	REL8_1_13:1.30
	REL8_2_9:1.31
	REL8_3_3:1.32
	REL7_4_20:1.29
	REL8_0_16:1.30
	REL8_1_12:1.30
	REL8_2_8:1.31
	REL8_3_2:1.32
	REL8_2_7:1.31
	REL8_3_1:1.32
	REL8_3_STABLE:1.32.0.2
	REL8_3_0:1.32
	REL8_3_RC2:1.32
	REL7_3_21:1.22
	REL7_4_19:1.29
	REL8_0_15:1.30
	REL8_1_11:1.30
	REL8_2_6:1.31
	REL8_3_RC1:1.32
	REL8_3_BETA4:1.32
	REL8_3_BETA3:1.32
	REL8_3_BETA2:1.32
	REL8_3_BETA1:1.32
	REL7_3_20:1.22
	REL7_4_18:1.29
	REL8_0_14:1.30
	REL8_1_10:1.30
	REL8_2_5:1.31
	REL7_3_19:1.22
	REL7_4_17:1.29
	REL8_0_13:1.30
	REL8_1_9:1.30
	REL8_2_4:1.31
	REL8_0_12:1.30
	REL8_1_8:1.30
	REL8_2_3:1.31
	REL7_3_18:1.22
	REL7_4_16:1.29
	REL8_0_11:1.30
	REL8_1_7:1.30
	REL8_2_2:1.31
	REL8_0_10:1.30
	REL8_1_6:1.30
	REL8_2_1:1.31
	REL7_4_15:1.29
	REL7_3_17:1.22
	REL8_2_STABLE:1.31.0.2
	REL8_2_0:1.31
	REL8_2_RC1:1.31
	REL8_2_BETA3:1.31
	REL8_2_BETA2:1.31
	REL8_1_5:1.30
	REL8_0_9:1.30
	REL7_4_14:1.29
	REL7_3_16:1.22
	REL8_2_BETA1:1.31
	REL7_3_15:1.22
	REL7_4_13:1.29
	REL8_0_8:1.30
	REL8_1_4:1.30
	REL7_3_14:1.22
	REL7_4_12:1.29
	REL8_0_7:1.30
	REL8_1_3:1.30
	REL7_3_13:1.22
	REL7_4_11:1.29
	REL8_0_6:1.30
	REL8_1_2:1.30
	REL7_3_12:1.22
	REL7_4_10:1.29
	REL8_0_5:1.30
	REL8_1_1:1.30
	REL8_1_STABLE:1.30.0.6
	REL8_1_0:1.30
	REL8_1_0RC1:1.30
	REL8_1_0BETA4:1.30
	REL8_1_0BETA3:1.30
	REL7_3_11:1.22
	REL7_4_9:1.29
	REL8_0_4:1.30
	REL8_1_0BETA2:1.30
	REL8_1_0BETA1:1.30
	REL7_2_8:1.18
	REL7_3_10:1.22
	REL7_4_8:1.29
	REL8_0_3:1.30
	REL8_0_2:1.30
	REL7_2_7:1.18
	REL7_3_9:1.22
	REL7_4_7:1.29
	REL8_0_1:1.30
	REL8_0_STABLE:1.30.0.4
	REL8_0_0:1.30.0.2
	REL8_0_0RC5:1.30
	REL8_0_0RC4:1.30
	REL8_0_0RC3:1.30
	REL8_0_0RC2:1.30
	REL8_0_0RC1:1.30
	REL8_0_0BETA5:1.30
	REL8_0_0BETA4:1.30
	REL7_4_6:1.29
	REL7_3_8:1.22
	REL7_2_6:1.18
	REL8_0_0BETA3:1.30
	REL8_0_0BETA2:1.30
	REL7_2_5:1.18
	REL7_4_5:1.29
	REL7_3_7:1.22
	REL7_4_4:1.29
	REL8_0_0BETA1:1.30
	REL7_4_3:1.29
	REL7_4_2:1.29
	REL7_3_6:1.22
	REL7_4_1:1.29
	REL7_3_5:1.22
	REL7_4:1.29
	REL7_4_RC2:1.29
	REL7_4_STABLE:1.29.0.2
	REL7_4_RC1:1.29
	REL7_4_BETA5:1.28
	REL7_4_BETA4:1.28
	REL7_4_BETA3:1.27
	REL7_4_BETA2:1.26
	WIN32_DEV:1.26.0.2
	REL7_4_BETA1:1.26
	REL7_3_4:1.22
	REL7_3_2:1.22
	REL7_2_4:1.18
	REL7_3_STABLE:1.22.0.2
	REL7_2_3:1.18
	REL7_2_STABLE:1.18.0.2
	REL7_2:1.18
	REL7_2_RC2:1.18
	REL7_2_RC1:1.18
	REL7_2_BETA5:1.16
	REL7_2_BETA4:1.14
	REL7_2_BETA3:1.12
	REL7_2_BETA2:1.11
	REL7_2_BETA1:1.11
	REL7_1_2:1.7
	REL7_1_STABLE:1.7.0.2
	REL7_1_BETA:1.5
	REL7_1_BETA3:1.6
	REL7_1_BETA2:1.6
	REL7_1:1.7
	REL7_0_PATCHES:1.2.0.2
	REL7_0:1.2;
locks; strict;
comment	@# @;


1.34
date	2010.02.19.14.36.45;	author momjian;	state Exp;
branches;
next	1.33;

1.33
date	2010.02.19.03.50.03;	author momjian;	state Exp;
branches;
next	1.32;

1.32
date	2007.01.31.23.26.03;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2006.09.16.00.30.18;	author momjian;	state Exp;
branches;
next	1.30;

1.30
date	2003.11.29.19.51.38;	author pgsql;	state Exp;
branches;
next	1.29;

1.29
date	2003.11.02.12.55.24;	author petere;	state Exp;
branches;
next	1.28;

1.28
date	2003.09.20.20.12.05;	author tgl;	state Exp;
branches;
next	1.27;

1.27
date	2003.08.31.17.32.23;	author petere;	state Exp;
branches;
next	1.26;

1.26
date	2003.03.25.16.15.39;	author petere;	state Exp;
branches
	1.26.2.1;
next	1.25;

1.25
date	2003.03.24.14.32.51;	author petere;	state Exp;
branches;
next	1.24;

1.24
date	2003.01.19.00.13.29;	author momjian;	state Exp;
branches;
next	1.23;

1.23
date	2002.11.15.03.11.18;	author momjian;	state Exp;
branches;
next	1.22;

1.22
date	2002.10.24.17.48.54;	author petere;	state Exp;
branches;
next	1.21;

1.21
date	2002.10.21.18.04.05;	author petere;	state Exp;
branches;
next	1.20;

1.20
date	2002.07.28.15.22.20;	author petere;	state Exp;
branches;
next	1.19;

1.19
date	2002.04.21.19.02.39;	author thomas;	state Exp;
branches;
next	1.18;

1.18
date	2002.01.20.22.19.56;	author petere;	state Exp;
branches;
next	1.17;

1.17
date	2002.01.18.20.32.54;	author momjian;	state Exp;
branches;
next	1.16;

1.16
date	2002.01.06.18.12.00;	author momjian;	state Exp;
branches;
next	1.15;

1.15
date	2002.01.04.18.58.46;	author momjian;	state Exp;
branches;
next	1.14;

1.14
date	2001.12.08.03.24.36;	author thomas;	state Exp;
branches;
next	1.13;

1.13
date	2001.11.28.20.49.10;	author petere;	state Exp;
branches;
next	1.12;

1.12
date	2001.11.18.20.35.02;	author petere;	state Exp;
branches;
next	1.11;

1.11
date	2001.09.14.10.24.35;	author ishii;	state Exp;
branches;
next	1.10;

1.10
date	2001.09.03.12.57.50;	author petere;	state Exp;
branches;
next	1.9;

1.9
date	2001.08.24.22.37.36;	author petere;	state Exp;
branches;
next	1.8;

1.8
date	2001.07.11.03.43.52;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	2001.03.19.16.20.52;	author petere;	state Exp;
branches;
next	1.6;

1.6
date	2000.12.25.23.15.26;	author petere;	state Exp;
branches;
next	1.5;

1.5
date	2000.10.05.19.48.18;	author momjian;	state Exp;
branches;
next	1.4;

1.4
date	2000.09.12.20.58.14;	author momjian;	state Exp;
branches;
next	1.3;

1.3
date	2000.08.23.05.59.11;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	2000.03.31.06.17.52;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	99.07.22.15.09.11;	author thomas;	state Exp;
branches;
next	;

1.26.2.1
date	2003.09.07.04.36.45;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.34
log
@Document --version and --help options for all client applications (they
all support it).

Per report from Josh Kupershmidt
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.33 2010/02/19 03:50:03 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> can
       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>--version</option></term>
     <listitem>
      <para>
       Print the <application>ecpg</application> version and exit.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>--help</option></term>
     <listitem>
      <para>
       Show help about <application>ecpg</application> command line
       arguments, and 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, you 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>
@


1.33
log
@First pass over client applications documentation proofreading.

gabrielle
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.32 2007/01/31 23:26:03 momjian Exp $
d162 1
a162 1
       include path.
d168 1
a168 1
     <term><option>--help</option></term>
d171 1
a171 1
       Show a brief summary of the command usage, then exit.
d177 1
a177 1
     <term><option>--version</option></term>
d180 2
a181 1
       Output version information, then exit.
d185 1
@


1.32
log
@Update reference documentation on may/can/might:

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.31 2006/09/16 00:30:18 momjian Exp $
d195 1
a195 1
   <productname>PostgreSQL</> include directory.  Therefore, one might
@


1.31
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.30 2003/11/29 19:51:38 pgsql Exp $
d83 1
a83 1
       Set a compatibility mode.  <replaceable>mode</replaceable> may
@


1.30
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.29 2003/11/02 12:55:24 petere Exp $
a229 17

<!-- 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:
-->
@


1.29
log
@Complete options help and put it in less random order.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.28 2003/09/20 20:12:05 tgl Exp $
@


1.28
log
@Fix a batch of speling misteaks identified by Peter's spell-checker tool.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.27 2003/08/31 17:32:23 petere Exp $
d80 11
d100 9
d130 11
@


1.27
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.26 2003/03/25 16:15:39 petere Exp $
d45 1
a45 1
   preferrably have the extension <filename>.pgc</filename>, in which
@


1.26
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.25 2003/03/24 14:32:51 petere Exp $
d17 4
@


1.26.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.27 2003/08/31 17:32:23 petere Exp $
a16 4

 <indexterm zone="app-ecpg">
  <primary>ecpg</primary>
 </indexterm>
@


1.25
log
@Another big editing pass for consistent content and presentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.24 2003/01/19 00:13:29 momjian Exp $
d52 1
a52 1
   See the &cite-programmer; for more information on that topic.
a190 10
  </para>
 </refsect1>


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

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


1.24
log
@This patch includes a lot of minor cleanups to the SGML documentation,
including:

- replacing all the appropriate usages of <citetitle>PostgreSQL
...</citetitle> with &cite-user;, &cite-admin;, and so on

- fix an omission in the EXECUTE documentation

- add some more text to the EXPLAIN documentation

- improve the PL/PgSQL RETURN NEXT documentation (more work to do here)

- minor markup fixes


Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.23 2002/11/15 03:11:18 momjian Exp $
d69 1
a69 1
       Automatically generate C code from SQL code.  Currently, this
d104 1
a104 1
       Specifies that <application>ecpg</application> should write all
d114 1
a114 1
       Turn on autocommit of transactions. In this mode, each query is
d116 1
a116 1
       transaction block. In the default mode, queries are committed
d133 1
a133 1
     <term><option>---help</option></term>
d168 1
a168 1
   flags <literal>-L/usr/local/pgsql/lib -lecpg</literal>.
@


1.23
log
@SGML improvements.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.22 2002/10/24 17:48:54 petere Exp $
d52 1
a52 1
   See the &cite-programmer; for that.
d199 2
a200 2
   <citetitle>PostgreSQL Programmer's Guide</citetitle> for a more
   detailed description of the embedded SQL interface
@


1.22
log
@Add introductory sections explaining what each book is about.  Remove Y2K
statement.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.21 2002/10/21 18:04:05 petere Exp $
d160 3
a162 3
   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>).
@


1.21
log
@Improve ECPG documentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/ecpg-ref.sgml,v 1.20 2002/07/28 15:22:20 petere Exp $
d52 1
a52 1
   See &cite-programmer; for that.
@


1.20
log
@Structure reference pages consistently.  Document that structure.
Add information about environment variables.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.19 2002/04/21 19:02:39 thomas Exp $
d8 1
a8 1
  <refentrytitle id="app-ecpg-title"><application>ecpg</application></refentrytitle>
d14 2
a15 6
  <refname>
   <application>ecpg</application>
  </refname>
  <refpurpose>
   embedded SQL C preprocessor
  </refpurpose>
a18 3
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
d21 1
a21 4
   <arg choice="opt">-v</arg>
   <arg choice="opt">-t</arg>
   <arg choice="opt">-I <replaceable>include-path</replaceable></arg>
   <arg choice="opt">-o <replaceable>outfile</replaceable></arg>
d26 1
d31 17
a47 4
   <application>ecpg</application>
   is an embedded SQL preprocessor for the C language and the
   <productname>PostgreSQL</productname>. It
   enables development of C programs with embedded SQL code.
d51 2
a52 7
   Linus Tolke (<email>linus@@epact.se</email>) was the
   original author of <application>ecpg</application> (up to version 0.2).
   Michael Meskes (<email>meskes@@debian.org</email>)
   is the current author and maintainer of <application>ecpg</application>.
   Thomas Good (<email>tomg@@q8.nrnet.org</email>)
   is the author of the last revision of the <application>ecpg</application> man page, on which
   this document is based.
d60 91
a150 67
   <para>
    <application>ecpg</application> accepts the following command
    line arguments:

    <variablelist>
     <varlistentry>
      <term>-v</term>
      <listitem>
       <para>
	Print version information. 
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-t</term>
      <listitem>
       <para>
	Turn on auto-commit 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>-I <replaceable class="parameter">include-path</replaceable></term>
      <listitem>
       <para>
	Specify an additional include path.
	Defaults are <filename>.</filename> (current directory),
	<filename>/usr/local/include</filename>, the
	<productname>PostgreSQL</productname> include path which is
	defined at compile time (default:
	<filename>/usr/local/pgsql/include</filename>), and
	<filename>/usr/include</filename>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-o <replaceable>outfile</replaceable></term>
      <listitem>
       <para>
	Specifies that <application>ecpg</application> should write all its output to <replaceable>outfile</replaceable>.
	If no such option is given the output is written to
	<filename><replaceable>name</replaceable>.c</filename>,
	assuming the input file was 
	named <filename><replaceable>name</replaceable>.pgc</filename>.
	If the input file does have the expected
	<literal>.pgc</literal> suffix, then the output file will have 
	<literal>.pgc</literal> appended to the input file name.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">file</replaceable></term>
      <listitem>
       <para>
	The files to be processed.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
d155 1
a155 1
  <title>Exit Status</title>
d158 5
a162 2
   <application>ecpg</application> returns 0 to the shell on
   successful completion, non-zero for errors.
a163 1
 </refsect1>
d165 5
d171 5
a175 36
 <refsect1>
  <title>Usage</title>

  <refsect2 id="APP-ECPG-preprocessing">
   <title>Preprocessing for Compilation</title>

   <para>
    An embedded SQL source file must be preprocessed before
    compilation: 
<synopsis>
ecpg [ -d ] [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceable>.pgc
</synopsis>

    where the optional <option>-d</option> flag turns on debugging.
    The <literal>.pgc</literal> extension is an 
    arbitrary means of denoting <application>ecpg</application> source.
   </para>

   <para>
    You may want to redirect the preprocessor output to a log file.
   </para>
  </refsect2>

  <refsect2 id="APP-ECPG-compiling">
   <title>Compiling and Linking</title>

   <para>
    Assuming the <productname>PostgreSQL</productname> binaries are in
    <filename>/usr/local/pgsql</filename>, you will need to compile
    and link your preprocessed source file:

<synopsis>
gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceable>.c -L /usr/local/pgsql/lib -lecpg -lpq
</synopsis>
   </para>
  </refsect2>
a177 2
 <refsect1 id="APP-ECPG-grammar">
  <title>Grammar</title>
d179 2
a180 82
  <refsect2 id="APP-ECPG-library">
   <title>Libraries</title>

   <para>
    The preprocessor will prepend two directives to the source:

<programlisting>
#include &lt;ecpgtype.h&gt;
#include &lt;ecpglib.h&gt;
</programlisting>
   </para>
  </refsect2>

  <refsect2 id="APP-ecpg-declaration">
   <title>Variable Declaration</title>

   <para>
    Variables declared within <application>ecpg</application> source code must be prepended with:

<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
</programlisting>
   </para>

   <para>
    Similarly, variable declaration sections must terminate with:

<programlisting>
EXEC SQL END DECLARE SECTION;
</programlisting>

    <note>
     <para>
      Prior to version 2.1.0, each variable had to be declared 
      on a separate line.  As of version 2.1.0 multiple variables may
      be declared on a single line:
<programlisting>
char  foo[16], bar[16];
</programlisting>
     </para>
    </note>
   </para>
  </refsect2>

  <refsect2 id="APP-ECPG-errors">
   <title>Error Handling</title>

   <para>
    The SQL communication area is defined with:

<programlisting>
EXEC SQL INCLUDE sqlca;
</programlisting>
   </para>

    <note>
     <para>
      The <literal>sqlca</literal> is in lowercase.
      While SQL convention may be 
      followed, i.e., using uppercase to separate embedded SQL 
      from C statements, <literal>sqlca</literal> (which includes the <filename>sqlca.h</>
      header file) <emphasis>must</> be lowercase.  This is because the
      EXEC SQL prefix indicates that this inclusion will be parsed by
      <application>ecpg</application>.
      <application>ecpg</application> observes case sensitivity
      (<filename>SQLCA.h</> will not be found).
      <command>EXEC SQL INCLUDE</command>
      can be used to include other header files
      as long as case sensitivity is observed.
     </para>
    </note>

   <para>
    The <literal>sqlprint</literal> command is used with the <literal>EXEC SQL WHENEVER</literal>
    statement to turn on error handling throughout the 
    program:

<programlisting>
EXEC SQL WHENEVER sqlerror sqlprint;
</programlisting>

    and
d182 4
d187 3
a189 1
EXEC SQL WHENEVER not found sqlprint;
a190 119
   </para>

    <note>
     <para>
      This is <emphasis>not</emphasis> an exhaustive example of usage for
      the <command>EXEC SQL WHENEVER</command> statement.
      Further examples of usage may
      be found in SQL manuals (e.g., <citetitle>The LAN TIMES Guide to SQL</> by
      Groff and Weinberg).
     </para>
    </note>
  </refsect2>

  <refsect2 id="APP-ECPG-connecting">
   <title>Connecting to the Database Server</title>

   <para>
    One connects to a database using the following:

<programlisting>
EXEC SQL CONNECT TO <replaceable>dbname</replaceable>;
</programlisting>

    where the database name is not quoted. Prior to version 2.1.0, the 
    database name was required to be inside single quotes.
   </para>

   <para>
    Specifying a server and port name in the connect statement is also 
    possible. The syntax is:

<synopsis>
<replaceable>dbname</replaceable>[@@<replaceable>server</replaceable>][:<replaceable>port</replaceable>]
</synopsis>

    or

<synopsis>
&lt;tcp|unix&gt;:postgresql://<replaceable>server</replaceable>[:<replaceable>port</replaceable>][/<replaceable>dbname</replaceable>][?<replaceable>options</replaceable>]
</synopsis>
   </para>
  </refsect2>

  <refsect2 id="APP-ECPG-queries">
   <title>Queries</title>

   <para>
    In general, SQL queries acceptable to other applications such as
    <application>psql</application> can be embedded into your C
    code. Here are some examples of how to do that.
   </para>

   <para>
    Create Table:

<programlisting>
EXEC SQL CREATE TABLE foo (number int4, ascii char(16));
EXEC SQL CREATE UNIQUE index num1 on foo(number);
EXEC SQL COMMIT;
</programlisting>
   </para>

   <para>
    Insert:

<programlisting>
EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
EXEC SQL COMMIT;
</programlisting>
   </para>

   <para>
    Delete:

<programlisting>
EXEC SQL DELETE FROM foo WHERE number = 9999;
EXEC SQL COMMIT;
</programlisting>
   </para>

   <para>
    Singleton Select:

<programlisting>
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
</programlisting>
   </para>

   <para>
    Select using Cursors:

<programlisting>
EXEC SQL DECLARE foo_bar CURSOR FOR
    SELECT number, ascii FROM foo
    ORDER BY ascii;
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
...
EXEC SQL CLOSE foo_bar;
EXEC SQL COMMIT;
</programlisting>
   </para>

   <para>
    Updates:
<programlisting>
EXEC SQL UPDATE foo
    SET ascii = 'foobar'
    WHERE number = 9999;
EXEC SQL COMMIT;
</programlisting>
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="APP-ECPG-notes">
  <title>Notes</title>
  <para>
   The complete structure definition MUST be listed
   inside the declare section.
a191 6

  <para>
   See the <filename>TODO</filename> file in the source for some more
   missing features.
  </para>

d200 1
a200 1
   detailed description of the embedded SQL interface.
@


1.19
log
@Augment the date/time examples in the User's Guide to reflect the newer
 capabilities of specifying time zones as intervals per SQL9x.
Put refentrytitle contents on the same line as the tag.
 Otherwise, leading whitespace is propagated into the product, which
 (at least) messes up the ToC layout.
Remove (some) docinfo tags containing dates. Best to omit if the dates
 are not accurate; maybe use CVS dates instead or leave them out.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.18 2002/01/20 22:19:56 petere Exp $
d12 1
d21 1
d34 26
a60 7
  <refsect2 id="R2-APP-ECPG-1">
   <refsect2info>
    <date>1999-07-20</date>
   </refsect2info>
   <title>
    Inputs
   </title>
d128 1
a128 1
  </refsect2>
a129 25
  <refsect2 id="R2-APP-ECPG-2">
   <refsect2info>
    <date>1998-11-05</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
    <application>ecpg</application> will create a file or
    write to <filename>stdout</filename>.

    <variablelist>
     <varlistentry>
      <term>Return value</term>
      <listitem>
       <para>
	<application>ecpg</application> returns 0 to the shell on successful completion, non-zero
	for errors.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>
d131 2
a132 8
 <refsect1 id="R1-APP-ECPG-description">
  <title>Description</title>
  <para>
   <application>ecpg</application>
   is an embedded SQL preprocessor for the C language and the
   <productname>PostgreSQL</productname>. It
   enables development of C programs with embedded SQL code.
  </para>
d135 2
a136 7
   Linus Tolke (<email>linus@@epact.se</email>) was the
   original author of <application>ecpg</application> (up to version 0.2).
   Michael Meskes (<email>meskes@@debian.org</email>)
   is the current author and maintainer of <application>ecpg</application>.
   Thomas Good (<email>tomg@@q8.nrnet.org</email>)
   is the author of the last revision of the <application>ecpg</application> man page, on which
   this document is based.
d140 2
a141 1
 <refsect1 id="R1-APP-ECPG-2">
d144 1
a144 1
  <refsect2 id="R2-APP-ECPG-preprocessing">
d164 1
a164 1
  <refsect2 id="R2-APP-ECPG-compiling">
d179 1
a179 1
 <refsect1 id="R1-APP-ECPG-grammar">
d182 1
a182 1
  <refsect2 id="R2-APP-ECPG-library">
d195 1
a195 1
  <refsect2 id="R2-APP-declaration">
d226 1
a226 1
  <refsect2 id="R2-APP-ECPG-errors">
d281 1
a281 1
  <refsect2 id="R2-APP-ECPG-connecting">
d311 1
a311 1
  <refsect2 id="R2-APP-ECPG-queries">
d382 1
a382 1
 <refsect1 id="R1-APP-ECPG-notes">
d395 11
@


1.18
log
@Spell-check and markup police
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.17 2002/01/18 20:32:54 momjian Exp $
d8 1
a8 3
  <refentrytitle id="app-ecpg-title">
   <application>ecpg</application>
  </refentrytitle>
@


1.17
log
@Improve description of autocommit behavior in ecpg manual pages.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.16 2002/01/06 18:12:00 momjian Exp $
d87 1
a87 1
	Specifies that <application>ecpg</application> should write all its output to outfile.
d258 1
a258 1
      from C statements, sqlca (which includes the <filename>sqlca.h</>
d271 1
a271 1
    The sqlprint command is used with the EXEC SQL WHENEVER
@


1.16
log
@Fix ecpg wording to be consistent.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.15 2002/01/04 18:58:46 momjian Exp $
d60 4
a63 1
	Turn on auto-commit of transactions.
a408 26

<!--
.SH FILES
.PD 0
.TP
.B /usr/src/pgsql/postgresql-${ver}/src/interfaces...
 ./ecpg/include.......source for \fIecpg\fP header files.
 ./ecpg/lib...........source for \fIecpg\fP libraries.
 ./ecpg/preproc.......source for \fIecpg\fP header files.
 ./ecpg/test..........source for \fIecpg\fP libraries.
 (test contains examples of syntax for ecpg SQL-C.)
.PD
.TP
.B /usr/local/pgsql/bin 
\fIPostgreSQL\fP binaries including \fIecpg\fP.
.PD
.TP
.B /usr/local/pgsql/include 
\fIPostgreSQL\fP headers including \fIecpglib.h\fP \fIecpgtype.h\fP 
and \fIsqlca.h\fP.
.PD
.TP
.B /usr/local/pgsql/lib 
\fIPostgreSQL\fP libraries including \fIlibecpg.a\fP and 
\fIlibecpg.so\fP.
-->
@


1.15
log
@ecpg.sgml manual page updated to ON.

---------------------------------------------------------------------------

When you run 'ecpg --help' you get the following:

          -t   turn on autocommit of transactions

amongst the other options... Shouldn't this be OFF as per the
documentation?

Best regards, Lee.

--
 Lee Kindness,   Senior Software Engineer,   lkindness@@csl.co.uk
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.14 2001/12/08 03:24:36 thomas Exp $
d60 1
a60 1
	Turn on auto-transaction mode.
@


1.14
log
@Use PostgreSQL consistantly throughout docs. Before, usage was split evenly
 between Postgres and PostgreSQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.13 2001/11/28 20:49:10 petere Exp $
d60 1
a60 1
	Turn off auto-transaction mode.
@


1.13
log
@proof-reading
@
text
@d2 2
a3 2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.12 2001/11/18 20:35:02 petere Exp $
Postgres documentation
@


1.12
log
@Initial round of tweakage for man pages
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.11 2001/09/14 10:24:35 ishii Exp $
d70 1
a70 1
	Defaults are <filename>.</filename>,
d72 1
a72 1
	<productname>Postgres</productname> include path which is
d74 1
a74 1
	<filename>/usr/local/pgsql/lib</filename>), and
d121 1
a121 1
      <term><replaceable>return value</replaceable></term>
d139 1
a139 1
   <productname>Postgres</productname>. It
d163 1
a163 1
    <programlisting>
d165 1
a165 1
    </programlisting>
d181 1
a181 1
    Assuming the <productname>Postgres</productname> binaries are in
d185 1
a185 1
    <programlisting>
d187 1
a187 1
    </programlisting>
d201 1
a201 1
    <programlisting>
d204 1
a204 1
    </programlisting>
d214 1
a214 1
    <programlisting>
d216 1
a216 1
    </programlisting>
d222 1
a222 1
    <programlisting>
d224 1
a224 1
    </programlisting>
d231 1
a231 1
      <programlisting>
d233 1
a233 1
      </programlisting>
d245 1
a245 1
    <programlisting>
d247 2
a248 1
    </programlisting>
d255 6
a260 4
      from C statements, sqlca (which includes the sqlca.h 
      header file) MUST be lowercase.  This is because the EXEC SQL
      prefix indicates that this INCLUDE will be parsed by <application>ecpg</application>.
      <application>ecpg</application> observes case sensitivity (SQLCA.h will not be found).
a265 1
   </para>
d272 1
a272 1
    <programlisting>
d274 1
a274 1
    </programlisting>
d278 1
a278 1
    <programlisting>
d280 2
a281 1
    </programlisting>
d288 1
a288 1
      be found in SQL manuals (e.g., `The LAN TIMES Guide to SQL' by
a291 1
   </para>
d300 1
a300 1
    <programlisting>
d302 1
a302 1
    </programlisting>
d312 1
a312 1
    <programlisting>
d314 1
a314 1
    </programlisting>
d318 1
a318 1
    <programlisting>
d320 1
a320 1
    </programlisting>
d336 1
a336 1
    <programlisting>
d340 1
a340 1
    </programlisting>
d346 1
a346 1
    <programlisting>
d349 1
a349 1
    </programlisting>
d358 1
a358 1
    </programlisting>
d364 1
a364 1
    <programlisting>
d366 1
a366 1
    </programlisting>
d372 1
a372 1
    <programlisting>
d380 1
a380 1
    </programlisting>
d385 1
a385 1
    <programlisting>
d390 1
a390 1
    </programlisting>
@


1.11
log
@Fix typo.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.10 2001/09/03 12:57:50 petere Exp $
d26 8
a33 3
  <synopsis>
ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ]  file1 [ file2 ] [ ... ]
  </synopsis>
d66 1
a66 1
      <term>-I <replaceable class="parameter">path</replaceable></term>
d81 1
a81 1
      <term>-o</term>
@


1.10
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.9 2001/08/24 22:37:36 petere Exp $
d227 1
a227 1
char  foo(16), bar(16);
@


1.9
log
@Add ecpg --help and --version.  Renumber the exit status codes, which were
documented wrong.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.8 2001/07/11 03:43:52 momjian Exp $
d19 1
a19 1
   Embedded SQL C preprocessor
@


1.8
log
@Remove mention that PREPARE is not implemented.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.7 2001/03/19 16:20:52 petere Exp $
d119 1
a119 1
	<application>ecpg</application> returns 0 to the shell on successful completion, -1
@


1.7
log
@Add missing TO.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.6 2000/12/25 23:15:26 petere Exp $
a389 4
  <para>
   There is no <command>EXEC SQL PREPARE</command> statement.
  </para>

@


1.6
log
@Refine some things to create better looking man pages.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.5 2000/10/05 19:48:18 momjian Exp $
d294 1
a294 1
EXEC SQL CONNECT <replaceable>dbname</replaceable>;
@


1.5
log
@Add proofreader's changes to docs.
Fix misspelling of disbursion to dispersion.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.4 2000/09/12 20:58:14 momjian Exp $
d11 1
d79 1
a79 1
	Specifies that ecpg should write all its output to outfile.
d119 1
a119 1
	ecpg returns 0 to the shell on successful completion, -1
d139 1
a139 1
   <ulink url="mailto:linus@@epact.se">Linus Tolke</ulink> was the
d141 1
a141 1
   <ulink url="mailto:meskes@@debian.org">Michael Meskes</ulink>
d143 2
a144 2
   <ulink url="mailto:tomg@@q8.nrnet.org">Thomas Good</ulink>
   is the author of the last revision of the ecpg man page, on which
d207 1
a207 1
    Variables declared within ecpg source code must be prepended with:
d251 2
a252 2
      prefix indicates that this INCLUDE will be parsed by ecpg.
      ecpg observes case sensitivity (SQLCA.h will not be found).
@


1.4
log
@typo fix
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.3 2000/08/23 05:59:11 thomas Exp $
d251 1
a251 1
      ecpg observes case sensitivity (SQLCA.h will not be found.)
@


1.3
log
@Fix several <ulink> tags which refer to e-mail addresses
 but were missing the "mailto:" prefix.
Fix typo.
Thanks to Neil Conway <nconway@@klamath.dyndns.org> for the heads-up.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.2 2000/03/31 06:17:52 thomas Exp $
d54 1
a54 1
	Turn off auto-transactin mode.
@


1.2
log
@Include all information from the old man pages.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.1 1999/07/22 15:09:11 thomas Exp $
d138 1
a138 1
   <ulink url="linus@@epact.se">Linus Tolke</ulink> was the
d140 1
a140 1
   <ulink url="meskes@@debian.org">Michael Meskes</ulink>
d142 1
a142 1
   <ulink url="tomg@@q8.nrnet.org">Thomas Good</ulink>
@


1.1
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 1
$Header$
d42 49
d94 1
d115 1
a115 2
      <term><computeroutput>
       </computeroutput></term>
d118 2
d128 2
a129 7
 <refsect1 id="R1-APP-ECPG-1">
  <refsect1info>
   <date>1998-11-05</date>
  </refsect1info>
  <title>
   Description
  </title>
d131 86
a216 83
<!--
.TH ECPG UNIX 11/28/98 PostgreSQL \fIPostgreSQL\fP
.SH NAME
ecpg - embedded SQL preprocessor for C / PostgreSQL
.SH SYNOPSIS
.\" \fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ]  file1 [ file2 ] [ ... ]
\fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ]  file1 [ file2 ] [ ... ]
.SH DESCRIPTION
.B \fIecpg\fP
is an embedded SQL preprocessor for C / PostgreSQL. It
enables development of C programs with embedded SQL code.
.PP
.B \fIecpg\fP
is ultimately intended to be as compliant as possible with the         
ANSI SQL-2 standard and existing commercial ESQL/C packages.                                               
.SH OPTIONS
.B \fIecpg\fP
interprets the following flags when it is invoked               
on the command line:
.PP
.PD 0
.TP 10
.BI \-v 
Print version information. 
.PD
.TP
.B \-t
Turn off auto-transactin mode.
.PD
.TP
.PD
.TP
.B \-I include-path
Specify additional include path. Defaults are \.,
/usr/local/include, the PostgreSQL include path which is defined at compile
time (default: /usr/local/pgsql/lib), /usr/include
.PD
.TP
.B \-o
Specifies that ecpg should write all its output to outfile.
If no such option is given the output is written to foo.c
(if the input file was named foo.pgc.)
If the input file was named foo.bar the output file will be
named foo.bar.c. 
.PD
.TP
.B file1, file2...
The files to be processed.
.\" 
.SH INSTALLATION
The
.B \fIecpg\fP
preprocessor is built during the PostgreSQL installation.  Binaries and
libraries are installed into the PGBASE (i.e., /usr/local/pgsql/... ) 
subdirectories.
.SH PREPROCESSING FOR COMPILATION
.B \fIecpg\fP
.\" (-d ) (-o file) file.pgc ( 2> ecpf.log)
(-o file) file.pgc 
.LP
.\" The optional \-d flag turns on debugging and 2> ecpg.log
.\" redirects the debug output.  The .pgc extension is an 
.\" arbitrary means of denoting ecpg source.
The .pgc extension is an arbitrary means of denoting ecpg source.
.SH COMPILING AND LINKING
Assuming the \fIPostgreSQL\fP binaries are in /usr/local/pgsql:
.LP
gcc -g -i /usr/local/pgsql/include (-o file) file.c 
-L /usr/local/pgsql/lib -lecpg -lpq
.SH ECPG GRAMMAR
.LP
.SH LIBRARIES
.LP
The preprocessor will prepend two directives to the source:
.LP
\fI#include <ecpgtype.h>\fP and \fI#include <ecpglib.h>\fP
.SH VARIABLE DECLARATION  
Variables declared within ecpg source code must be prepended with:
.LP
EXEC SQL BEGIN DECLARE SECTION;  
.LP        
Similarly, variable declaration sections must terminate with:
.LP
d218 8
a225 5
.LP        
NOTE: prior to version 2.1.0, each variable had to be declared 
on a separate line.  As of version 2.1.0 multiple variables may
be declared on a single line:
.LP
d227 13
a239 4
.LP       
.SH ERROR HANDLING
The SQL communication area is defined with:
.LP
d241 24
a264 14
.LP
NOTE: the lowercase `sqlca'.  While SQL convention may be 
followed, i.e., using uppercase to separate embedded SQL 
from C statements, sqlca (which includes the sqlca.h 
header file) MUST be lowercase.  This is because the EXEC SQL
prefix indicates that this INCLUDE will be parsed by ecpg.
ecpg observes case sensitivity (SQLCA.h will not be found.)
EXEC SQL INCLUDE can be used to include other header files
as long as case sensitivity is observed.
.LP
The sqlprint command is used with the EXEC SQL WHENEVER
statement to turn on error handling throughout the 
program:
.LP
d266 5
a270 1
.LP
d272 59
a330 39
.LP
PLEASE NOTE: this is *not* an exhaustive example of usage for
the EXEC SQL WHENEVER statement.  Further examples of usage may
be found in SQL manuals (e.g., `The LAN TIMES Guide to SQL' by
Groff and Weinberg.)
.LP
.SH CONNECTING TO THE DATABASE SERVER
Prior to version 2.1.0 the database name was single quoted:
.RS
EXEC SQL CONNECT 'test1';
.RE
.LP
As of version 2.1.0, the syntax has been simplified:
.LP
.RS
EXEC SQL CONNECT test1;
.RE
(The database name is no longer quoted.)
.LP
Specifying a server and port name in the connect statement is also possible
as of version 6.4. of PostgreSQL. The syntax is:
.LP
.RS
dbname[@@server][:port]
.RE
.LP
or
.LP
.RS
<tcp|unix>:postgresql://server[:port][/dbname][?options]
.RE
.SH QUERIES
.LP
.SS Create Table:
.LP
EXEC SQL CREATE TABLE foo (number int4, ascii char(16));  
.RS
EXEC SQL CREATE UNIQUE index num1 on foo(number); 
.RE
d332 8
a339 7
.LP 
.SS Insert:
.LP
EXEC SQL INSERT INTO foo (number, ascii)
.RS
VALUES (9999, 'doodad');
.RE
d341 8
a348 7
.LP
.SS Delete:
.LP
EXEC SQL DELETE FROM foo
.RS
WHERE number = 9999;   
.RE
d350 18
a367 17
.LP
.SS Singleton Select:
.LP
EXEC SQL SELECT foo INTO :FooBar FROM table1
.RS
WHERE ascii = 'doodad';  
.RE
.LP
.SS Select using Cursors:
.LP
EXEC SQL DECLARE foo_bar CURSOR FOR     
.RS
SELECT number, ascii FROM foo    
.RS
ORDER BY ascii;
.RE
.RE
a368 1
.LP
a370 1
.RS
d372 6
a377 4
.RE
.LP
.SS Updates
.LP
d379 2
a380 6
.RS
SET ascii = 'foobar'
.RE
.RS
WHERE number = 9999;
.RE
d382 22
a403 22
.LP
.SH BUGS
.LP
The is no EXEC SQL PREPARE statement.
.LP
The complete structure definition MUST be listed
inside the declare section.
.LP
See the TODO file in the source for some more missing features.
.LP
.SH "RETURN VALUE"
.LP
ecpg returns 0 to the shell on successful completion, -1
for errors.
.LP
.SH "SEE ALSO"
.PD 0
.TP
\fIcc\fP(1), \fIpgintro\fP(l), \fIcommit\fP(l), \fIdelete\fP(l)
.TP
\fIfetch\fP(l), \fIselect\fP(l), \fIsql\fP(l) , \fIupdate\fP(l)
.PD
a426 13
.SH AUTHORS
Linus Tolke \fI<linus@@epact.se>\fP
- original author of ECPG (up to version 0.2).
.br
.PP
Michael Meskes \fI<meskes@@debian.org>\fP
- actual author and maintainer of ECPG.
.br
.PP
Thomas Good \fI<tomg@@q8.nrnet.org>\fP
- author of this revision of the ecpg man page.
.br
.zZ
a428 1
  </para>
@
