mirror of https://github.com/postgres/postgres
Include all information from the old man pages.
This commit is contained in:
Thomas G. Lockhart
parent
fb43d74762
commit
f43974f6f1
|
|
@ -1,5 +1,5 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.1 1999/07/22 15:09:11 thomas Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.2 2000/03/31 06:17:52 thomas Exp $
|
||||
Postgres documentation
|
||||
-->
|
||||
|
||||
|
|
@ -38,10 +38,60 @@ ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ]
|
|||
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>
|
||||
|
|
@ -62,10 +112,11 @@ ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ]
|
|||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><computeroutput>
|
||||
</computeroutput></term>
|
||||
<term><replaceable>return value</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
ecpg returns 0 to the shell on successful completion, -1
|
||||
for errors.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -74,239 +125,282 @@ ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ]
|
|||
</refsect2>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-APP-ECPG-1">
|
||||
<refsect1info>
|
||||
<date>1998-11-05</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1 id="R1-APP-ECPG-description">
|
||||
<title>Description</title>
|
||||
<para>
|
||||
<!--
|
||||
.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
|
||||
<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="linus@epact.se">Linus Tolke</ulink> was the
|
||||
original author of <application>ecpg</application> (up to version 0.2).
|
||||
<ulink url="meskes@debian.org">Michael Meskes</ulink>
|
||||
is the current author and maintainer of <application>ecpg</application>.
|
||||
<ulink url="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 <ecpgtype.h>
|
||||
#include <ecpglib.h>
|
||||
</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;
|
||||
.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
|
||||
</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);
|
||||
.LP
|
||||
.SH ERROR HANDLING
|
||||
The SQL communication area is defined with:
|
||||
.LP
|
||||
</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;
|
||||
.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
|
||||
</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;
|
||||
.LP
|
||||
</programlisting>
|
||||
|
||||
and
|
||||
|
||||
<programlisting>
|
||||
EXEC SQL WHENEVER not found sqlprint;
|
||||
.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
|
||||
</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);
|
||||
EXEC SQL COMMIT;
|
||||
.LP
|
||||
.SS Insert:
|
||||
.LP
|
||||
EXEC SQL INSERT INTO foo (number, ascii)
|
||||
.RS
|
||||
VALUES (9999, 'doodad');
|
||||
.RE
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Insert:
|
||||
|
||||
<programlisting>
|
||||
EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
|
||||
EXEC SQL COMMIT;
|
||||
.LP
|
||||
.SS Delete:
|
||||
.LP
|
||||
EXEC SQL DELETE FROM foo
|
||||
.RS
|
||||
WHERE number = 9999;
|
||||
.RE
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Delete:
|
||||
|
||||
<programlisting>
|
||||
EXEC SQL DELETE FROM foo WHERE number = 9999;
|
||||
EXEC SQL COMMIT;
|
||||
.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
|
||||
</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;
|
||||
.LP
|
||||
...
|
||||
EXEC SQL CLOSE foo_bar;
|
||||
.RS
|
||||
EXEC SQL COMMIT;
|
||||
.RE
|
||||
.LP
|
||||
.SS Updates
|
||||
.LP
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Updates:
|
||||
<programlisting>
|
||||
EXEC SQL UPDATE foo
|
||||
.RS
|
||||
SET ascii = 'foobar'
|
||||
.RE
|
||||
.RS
|
||||
WHERE number = 9999;
|
||||
.RE
|
||||
SET ascii = 'foobar'
|
||||
WHERE number = 9999;
|
||||
EXEC SQL COMMIT;
|
||||
.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
|
||||
</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
|
||||
|
|
@ -330,22 +424,8 @@ and \fIsqlca.h\fP.
|
|||
.B /usr/local/pgsql/lib
|
||||
\fIPostgreSQL\fP libraries including \fIlibecpg.a\fP and
|
||||
\fIlibecpg.so\fP.
|
||||
.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
|
||||
-->
|
||||
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue