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

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.13 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->

<refentry id="APP-ECPG">
 <refmeta>
  <refentrytitle id="app-ecpg-title">
   <application>ecpg</application>
  </refentrytitle>
  <manvolnum>1</manvolnum>
  <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>
  <cmdsynopsis>
   <command>ecpg</command>
   <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>
   <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
  </cmdsynopsis>

  <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-transaction mode.
       </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 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>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>

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

  <para>
   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.
  </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: 
<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="R2-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>
 </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 <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="R2-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, sqlca (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 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>
   </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="R2-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="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>
   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:
-->