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

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.3 2000/08/23 05:59:11 thomas Exp $
Postgres documentation
-->

<refentry id="APP-ECPG">
 <refmeta>
  <refentrytitle id="app-ecpg-title">
   <application>ecpg</application>
  </refentrytitle>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   <application>ecpg</application>
  </refname>
  <refpurpose>
   Embedded SQL C preprocessor
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
  <synopsis>
ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ]  file1 [ file2 ] [ ... ]
  </synopsis>

  <refsect2 id="R2-APP-ECPG-1">
   <refsect2info>
    <date>1999-07-20</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <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 off auto-transactin mode.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-I <replaceable class="parameter">path</replaceable></term>
      <listitem>
       <para>
	Specify an additional include path.
	Defaults are <filename>.</filename>,
	<filename>/usr/local/include</filename>, the
	<productname>Postgres</productname> include path which is
	defined at compile time (default:
	<filename>/usr/local/pgsql/lib</filename>), and
	<filename>/usr/include</filename>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-o</term>
      <listitem>
       <para>
	Specifies that ecpg should write all its output to outfile.
	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>
  </refsect2>

  <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><replaceable>return value</replaceable></term>
      <listitem>
       <para>
	ecpg returns 0 to the shell on successful completion, -1
	for errors.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>

 <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>Postgres</productname>. It
   enables development of C programs with embedded SQL code.
  </para>

  <para>
   <ulink url="mailto:linus@epact.se">Linus Tolke</ulink> was the
   original author of <application>ecpg</application> (up to version 0.2).
   <ulink url="mailto:meskes@debian.org">Michael Meskes</ulink>
   is the current author and maintainer of <application>ecpg</application>.
   <ulink url="mailto:tomg@q8.nrnet.org">Thomas Good</ulink>
   is the author of the last revision of the ecpg man page, on which
   this document is based.
  </para>
 </refsect1>

 <refsect1 id="R1-APP-ECPG-2">
  <title>Usage</title>

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

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

    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="R2-APP-ECPG-compiling">
   <title>Compiling and Linking</title>

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

    <programlisting>
gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceable>.c -L /usr/local/pgsql/lib -lecpg -lpq
    </programlisting>
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="R1-APP-ECPG-grammar">
  <title>Grammar</title>

  <refsect2 id="R2-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="R2-APP-declaration">
   <title>Variable Declaration</title>

   <para>
    Variables declared within ecpg 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="R2-APP-ECPG-errors">
   <title>Error Handling</title>

   <para>
    The SQL communication area is defined with:

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

    <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, 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.)
      <command>EXEC SQL INCLUDE</command>
      can be used to include other header files
      as long as case sensitivity is observed.
     </para>
    </note>
   </para>

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

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

    and

    <programlisting>
EXEC SQL WHENEVER not found sqlprint;
    </programlisting>

    <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., `The LAN TIMES Guide to SQL' by
      Groff and Weinberg).
     </para>
    </note>
   </para>
  </refsect2>

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

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

    <programlisting>
EXEC SQL CONNECT <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:

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

    or

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

  <refsect2 id="R2-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="R1-APP-ECPG-notes">
  <title>Notes</title>
  <para>
   There is no <command>EXEC SQL PREPARE</command> statement.
  </para>

  <para>
   The complete structure definition MUST be listed
   inside the declare section.
  </para>

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

<!--
.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.
-->

 </refsect1>
</refentry>

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