1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2000-12-26 00:15:27 +01:00
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.6 2000/12/25 23:15:26 petere Exp $
|
1999-07-22 17:09:15 +02:00
|
|
|
Postgres documentation
|
|
|
|
-->
|
|
|
|
|
|
|
|
<refentry id="APP-ECPG">
|
|
|
|
<refmeta>
|
|
|
|
<refentrytitle id="app-ecpg-title">
|
|
|
|
<application>ecpg</application>
|
|
|
|
</refentrytitle>
|
2000-12-26 00:15:27 +01:00
|
|
|
<manvolnum>1</manvolnum>
|
1999-07-22 17:09:15 +02:00
|
|
|
<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>
|
2000-03-31 08:17:52 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term>-v</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Print version information.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>-t</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2000-09-12 22:58:14 +02:00
|
|
|
Turn off auto-transaction mode.
|
2000-03-31 08:17:52 +02:00
|
|
|
</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>
|
2000-12-26 00:15:27 +01:00
|
|
|
Specifies that <application>ecpg</application> should write all its output to outfile.
|
2000-03-31 08:17:52 +02:00
|
|
|
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>
|
|
|
|
|
1999-07-22 17:09:15 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">file</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2000-03-31 08:17:52 +02:00
|
|
|
The files to be processed.
|
1999-07-22 17:09:15 +02:00
|
|
|
</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>
|
2000-03-31 08:17:52 +02:00
|
|
|
<term><replaceable>return value</replaceable></term>
|
1999-07-22 17:09:15 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2000-12-26 00:15:27 +01:00
|
|
|
<application>ecpg</application> returns 0 to the shell on successful completion, -1
|
2000-03-31 08:17:52 +02:00
|
|
|
for errors.
|
1999-07-22 17:09:15 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
</refsect2>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
2000-03-31 08:17:52 +02:00
|
|
|
<refsect1 id="R1-APP-ECPG-description">
|
|
|
|
<title>Description</title>
|
1999-07-22 17:09:15 +02:00
|
|
|
<para>
|
2000-03-31 08:17:52 +02:00
|
|
|
<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>
|
2000-12-26 00:15:27 +01:00
|
|
|
Linus Tolke (<email>linus@epact.se</email>) was the
|
2000-03-31 08:17:52 +02:00
|
|
|
original author of <application>ecpg</application> (up to version 0.2).
|
2000-12-26 00:15:27 +01:00
|
|
|
Michael Meskes (<email>meskes@debian.org</email>)
|
2000-03-31 08:17:52 +02:00
|
|
|
is the current author and maintainer of <application>ecpg</application>.
|
2000-12-26 00:15:27 +01:00
|
|
|
Thomas Good (<email>tomg@q8.nrnet.org</email>)
|
|
|
|
is the author of the last revision of the <application>ecpg</application> man page, on which
|
2000-03-31 08:17:52 +02:00
|
|
|
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 <ecpgtype.h>
|
|
|
|
#include <ecpglib.h>
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</refsect2>
|
|
|
|
|
|
|
|
<refsect2 id="R2-APP-declaration">
|
|
|
|
<title>Variable Declaration</title>
|
|
|
|
|
|
|
|
<para>
|
2000-12-26 00:15:27 +01:00
|
|
|
Variables declared within <application>ecpg</application> source code must be prepended with:
|
2000-03-31 08:17:52 +02:00
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
EXEC SQL BEGIN DECLARE SECTION;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Similarly, variable declaration sections must terminate with:
|
|
|
|
|
|
|
|
<programlisting>
|
1999-07-22 17:09:15 +02:00
|
|
|
EXEC SQL END DECLARE SECTION;
|
2000-03-31 08:17:52 +02:00
|
|
|
</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>
|
1999-07-22 17:09:15 +02:00
|
|
|
char foo(16), bar(16);
|
2000-03-31 08:17:52 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
</para>
|
|
|
|
</refsect2>
|
|
|
|
|
|
|
|
<refsect2 id="R2-APP-ECPG-errors">
|
|
|
|
<title>Error Handling</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The SQL communication area is defined with:
|
|
|
|
|
|
|
|
<programlisting>
|
1999-07-22 17:09:15 +02:00
|
|
|
EXEC SQL INCLUDE sqlca;
|
2000-03-31 08:17:52 +02:00
|
|
|
</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
|
2000-12-26 00:15:27 +01:00
|
|
|
prefix indicates that this INCLUDE will be parsed by <application>ecpg</application>.
|
|
|
|
<application>ecpg</application> observes case sensitivity (SQLCA.h will not be found).
|
2000-03-31 08:17:52 +02:00
|
|
|
<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>
|
1999-07-22 17:09:15 +02:00
|
|
|
EXEC SQL WHENEVER sqlerror sqlprint;
|
2000-03-31 08:17:52 +02:00
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
and
|
|
|
|
|
|
|
|
<programlisting>
|
1999-07-22 17:09:15 +02:00
|
|
|
EXEC SQL WHENEVER not found sqlprint;
|
2000-03-31 08:17:52 +02:00
|
|
|
</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>
|
|
|
|
<tcp|unix>: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);
|
1999-07-22 17:09:15 +02:00
|
|
|
EXEC SQL COMMIT;
|
2000-03-31 08:17:52 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Insert:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
|
1999-07-22 17:09:15 +02:00
|
|
|
EXEC SQL COMMIT;
|
2000-03-31 08:17:52 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Delete:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
EXEC SQL DELETE FROM foo WHERE number = 9999;
|
1999-07-22 17:09:15 +02:00
|
|
|
EXEC SQL COMMIT;
|
2000-03-31 08:17:52 +02:00
|
|
|
</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;
|
1999-07-22 17:09:15 +02:00
|
|
|
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
|
|
|
|
...
|
|
|
|
EXEC SQL CLOSE foo_bar;
|
|
|
|
EXEC SQL COMMIT;
|
2000-03-31 08:17:52 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Updates:
|
|
|
|
<programlisting>
|
1999-07-22 17:09:15 +02:00
|
|
|
EXEC SQL UPDATE foo
|
2000-03-31 08:17:52 +02:00
|
|
|
SET ascii = 'foobar'
|
|
|
|
WHERE number = 9999;
|
1999-07-22 17:09:15 +02:00
|
|
|
EXEC SQL COMMIT;
|
2000-03-31 08:17:52 +02:00
|
|
|
</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>
|
|
|
|
|
|
|
|
<!--
|
1999-07-22 17:09:15 +02:00
|
|
|
.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:
|
|
|
|
-->
|