<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.19 2002/04/21 19:02:39 thomas Exp $
PostgreSQL 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 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>
</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 <ecpgtype.h>
#include <ecpglib.h>
</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, <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
<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>
<tcp|unix>: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>
</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:
-->