Skip to content

P
Postgres FD Implementation
Commit f43974f6 authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Include all information from the old man pages.

parent fb43d747
Hide whitespace changes
Inline Side-by-side
Showing with 315 additions and 235 deletions
doc/src/sgml/ref/ecpg-ref.sgml
View file @ f43974f6
<!-- <!--
$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 Postgres documentation
--> -->
...@@ -38,10 +38,60 @@ ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ] ...@@ -38,10 +38,60 @@ ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ]
line arguments: line arguments:
<variablelist> <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> <varlistentry>
<term><replaceable class="parameter">file</replaceable></term> <term><replaceable class="parameter">file</replaceable></term>
<listitem> <listitem>
<para> <para>
The files to be processed.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -62,10 +112,11 @@ ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ] ...@@ -62,10 +112,11 @@ ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ]
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><computeroutput> <term><replaceable>return value</replaceable></term>
</computeroutput></term>
<listitem> <listitem>
<para> <para>
ecpg returns 0 to the shell on successful completion, -1
for errors.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -74,239 +125,282 @@ ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ] ...@@ -74,239 +125,282 @@ ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ]
</refsect2> </refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-APP-ECPG-1"> <refsect1 id="R1-APP-ECPG-description">
<refsect1info> <title>Description</title>
<date>1998-11-05</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<!-- <application>ecpg</application>
.TH ECPG UNIX 11/28/98 PostgreSQL \fIPostgreSQL\fP is an embedded SQL preprocessor for the C language and the
.SH NAME <productname>Postgres</productname>. It
ecpg - embedded SQL preprocessor for C / PostgreSQL enables development of C programs with embedded SQL code.
.SH SYNOPSIS </para>
.\" \fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ] file1 [ file2 ] [ ... ]
\fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ] file1 [ file2 ] [ ... ] <para>
.SH DESCRIPTION <ulink url="linus@epact.se">Linus Tolke</ulink> was the
.B \fIecpg\fP original author of <application>ecpg</application> (up to version 0.2).
is an embedded SQL preprocessor for C / PostgreSQL. It <ulink url="meskes@debian.org">Michael Meskes</ulink>
enables development of C programs with embedded SQL code. is the current author and maintainer of <application>ecpg</application>.
.PP <ulink url="tomg@q8.nrnet.org">Thomas Good</ulink>
.B \fIecpg\fP is the author of the last revision of the ecpg man page, on which
is ultimately intended to be as compliant as possible with the this document is based.
ANSI SQL-2 standard and existing commercial ESQL/C packages. </para>
.SH OPTIONS </refsect1>
.B \fIecpg\fP
interprets the following flags when it is invoked <refsect1 id="R1-APP-ECPG-2">
on the command line: <title>Usage</title>
.PP
.PD 0 <refsect2 id="R2-APP-ECPG-preprocessing">
.TP 10 <title>Preprocessing for Compilation</title>
.BI \-v
Print version information. <para>
.PD An embedded SQL source file must be preprocessed before
.TP compilation:
.B \-t <programlisting>
Turn off auto-transactin mode. ecpg [ -d ] [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceable>.pgc
.PD </programlisting>
.TP
.PD where the optional <option>-d</option> flag turns on debugging.
.TP The <literal>.pgc</literal> extension is an
.B \-I include-path arbitrary means of denoting <application>ecpg</application> source.
Specify additional include path. Defaults are \., </para>
/usr/local/include, the PostgreSQL include path which is defined at compile
time (default: /usr/local/pgsql/lib), /usr/include <para>
.PD You may want to redirect the preprocessor output to a log file.
.TP </para>
.B \-o </refsect2>
Specifies that ecpg should write all its output to outfile.
If no such option is given the output is written to foo.c <refsect2 id="R2-APP-ECPG-compiling">
(if the input file was named foo.pgc.) <title>Compiling and Linking</title>
If the input file was named foo.bar the output file will be
named foo.bar.c. <para>
.PD Assuming the <productname>Postgres</productname> binaries are in
.TP <filename>/usr/local/pgsql</filename>, you will need to compile
.B file1, file2... and link your preprocessed source file:
The files to be processed.
.\" <programlisting>
.SH INSTALLATION gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceable>.c -L /usr/local/pgsql/lib -lecpg -lpq
The </programlisting>
.B \fIecpg\fP </para>
preprocessor is built during the PostgreSQL installation. Binaries and </refsect2>
libraries are installed into the PGBASE (i.e., /usr/local/pgsql/... ) </refsect1>
subdirectories.
.SH PREPROCESSING FOR COMPILATION <refsect1 id="R1-APP-ECPG-grammar">
.B \fIecpg\fP <title>Grammar</title>
.\" (-d ) (-o file) file.pgc ( 2> ecpf.log)
(-o file) file.pgc <refsect2 id="R2-APP-ECPG-library">
.LP <title>Libraries</title>
.\" The optional \-d flag turns on debugging and 2> ecpg.log
.\" redirects the debug output. The .pgc extension is an <para>
.\" arbitrary means of denoting ecpg source. The preprocessor will prepend two directives to the source:
The .pgc extension is an arbitrary means of denoting ecpg source.
.SH COMPILING AND LINKING <programlisting>
Assuming the \fIPostgreSQL\fP binaries are in /usr/local/pgsql: #include &lt;ecpgtype.h&gt;
.LP #include &lt;ecpglib.h&gt;
gcc -g -i /usr/local/pgsql/include (-o file) file.c </programlisting>
-L /usr/local/pgsql/lib -lecpg -lpq </para>
.SH ECPG GRAMMAR </refsect2>
.LP
.SH LIBRARIES <refsect2 id="R2-APP-declaration">
.LP <title>Variable Declaration</title>
The preprocessor will prepend two directives to the source:
.LP <para>
\fI#include <ecpgtype.h>\fP and \fI#include <ecpglib.h>\fP Variables declared within ecpg source code must be prepended with:
.SH VARIABLE DECLARATION
Variables declared within ecpg source code must be prepended with: <programlisting>
.LP EXEC SQL BEGIN DECLARE SECTION;
EXEC SQL BEGIN DECLARE SECTION; </programlisting>
.LP </para>
Similarly, variable declaration sections must terminate with:
.LP <para>
Similarly, variable declaration sections must terminate with:
<programlisting>
EXEC SQL END DECLARE SECTION; EXEC SQL END DECLARE SECTION;
.LP </programlisting>
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 <note>
be declared on a single line: <para>
.LP 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); char foo(16), bar(16);
.LP </programlisting>
.SH ERROR HANDLING </para>
The SQL communication area is defined with: </note>
.LP </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; EXEC SQL INCLUDE sqlca;
.LP </programlisting>
NOTE: the lowercase `sqlca'. While SQL convention may be
followed, i.e., using uppercase to separate embedded SQL <note>
from C statements, sqlca (which includes the sqlca.h <para>
header file) MUST be lowercase. This is because the EXEC SQL The <literal>sqlca</literal> is in lowercase.
prefix indicates that this INCLUDE will be parsed by ecpg. While SQL convention may be
ecpg observes case sensitivity (SQLCA.h will not be found.) followed, i.e., using uppercase to separate embedded SQL
EXEC SQL INCLUDE can be used to include other header files from C statements, sqlca (which includes the sqlca.h
as long as case sensitivity is observed. header file) MUST be lowercase. This is because the EXEC SQL
.LP prefix indicates that this INCLUDE will be parsed by ecpg.
The sqlprint command is used with the EXEC SQL WHENEVER ecpg observes case sensitivity (SQLCA.h will not be found.)
statement to turn on error handling throughout the <command>EXEC SQL INCLUDE</command>
program: can be used to include other header files
.LP 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; EXEC SQL WHENEVER sqlerror sqlprint;
.LP </programlisting>
and
<programlisting>
EXEC SQL WHENEVER not found sqlprint; EXEC SQL WHENEVER not found sqlprint;
.LP </programlisting>
PLEASE NOTE: this is *not* an exhaustive example of usage for
the EXEC SQL WHENEVER statement. Further examples of usage may <note>
be found in SQL manuals (e.g., `The LAN TIMES Guide to SQL' by <para>
Groff and Weinberg.) This is <emphasis>not</emphasis> an exhaustive example of usage for
.LP the <command>EXEC SQL WHENEVER</command> statement.
.SH CONNECTING TO THE DATABASE SERVER Further examples of usage may
Prior to version 2.1.0 the database name was single quoted: be found in SQL manuals (e.g., `The LAN TIMES Guide to SQL' by
.RS Groff and Weinberg).
EXEC SQL CONNECT 'test1'; </para>
.RE </note>
.LP </para>
As of version 2.1.0, the syntax has been simplified: </refsect2>
.LP
.RS <refsect2 id="R2-APP-ECPG-connecting">
EXEC SQL CONNECT test1; <title>Connecting to the Database Server</title>
.RE
(The database name is no longer quoted.) <para>
.LP One connects to a database using the following:
Specifying a server and port name in the connect statement is also possible
as of version 6.4. of PostgreSQL. The syntax is: <programlisting>
.LP EXEC SQL CONNECT <replaceable>dbname</replaceable>;
.RS </programlisting>
dbname[@server][:port]
.RE where the database name is not quoted. Prior to version 2.1.0, the
.LP database name was required to be inside single quotes.
or </para>
.LP
.RS <para>
<tcp|unix>:postgresql://server[:port][/dbname][?options] Specifying a server and port name in the connect statement is also
.RE possible. The syntax is:
.SH QUERIES
.LP <programlisting>
.SS Create Table: <replaceable>dbname</replaceable>[@<replaceable>server</replaceable>][:<replaceable>port</replaceable>]
.LP </programlisting>
EXEC SQL CREATE TABLE foo (number int4, ascii char(16));
.RS or
EXEC SQL CREATE UNIQUE index num1 on foo(number);
.RE <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; EXEC SQL COMMIT;
.LP </programlisting>
.SS Insert: </para>
.LP
EXEC SQL INSERT INTO foo (number, ascii) <para>
.RS Insert:
VALUES (9999, 'doodad');
.RE <programlisting>
EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
EXEC SQL COMMIT; EXEC SQL COMMIT;
.LP </programlisting>
.SS Delete: </para>
.LP
EXEC SQL DELETE FROM foo <para>
.RS Delete:
WHERE number = 9999;
.RE <programlisting>
EXEC SQL DELETE FROM foo WHERE number = 9999;
EXEC SQL COMMIT; EXEC SQL COMMIT;
.LP </programlisting>
.SS Singleton Select: </para>
.LP
EXEC SQL SELECT foo INTO :FooBar FROM table1 <para>
.RS Singleton Select:
WHERE ascii = 'doodad';
.RE <programlisting>
.LP EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
.SS Select using Cursors: </programlisting>
.LP </para>
EXEC SQL DECLARE foo_bar CURSOR FOR
.RS <para>
SELECT number, ascii FROM foo Select using Cursors:
.RS
ORDER BY ascii; <programlisting>
.RE EXEC SQL DECLARE foo_bar CURSOR FOR
.RE SELECT number, ascii FROM foo
ORDER BY ascii;
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad; EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
.LP
... ...
EXEC SQL CLOSE foo_bar; EXEC SQL CLOSE foo_bar;
.RS
EXEC SQL COMMIT; EXEC SQL COMMIT;
.RE </programlisting>
.LP </para>
.SS Updates
.LP <para>
Updates:
<programlisting>
EXEC SQL UPDATE foo EXEC SQL UPDATE foo
.RS SET ascii = 'foobar'
SET ascii = 'foobar' WHERE number = 9999;
.RE
.RS
WHERE number = 9999;
.RE
EXEC SQL COMMIT; EXEC SQL COMMIT;
.LP </programlisting>
.SH BUGS </para>
.LP </refsect2>
The is no EXEC SQL PREPARE statement. </refsect1>
.LP
The complete structure definition MUST be listed <refsect1 id="R1-APP-ECPG-notes">
inside the declare section. <title>Notes</title>
.LP <para>
See the TODO file in the source for some more missing features. There is no <command>EXEC SQL PREPARE</command> statement.
.LP </para>
.SH "RETURN VALUE"
.LP <para>
ecpg returns 0 to the shell on successful completion, -1 The complete structure definition MUST be listed
for errors. inside the declare section.
.LP </para>
.SH "SEE ALSO"
.PD 0 <para>
.TP See the <filename>TODO</filename> file in the source for some more
\fIcc\fP(1), \fIpgintro\fP(l), \fIcommit\fP(l), \fIdelete\fP(l) missing features.
.TP </para>
\fIfetch\fP(l), \fIselect\fP(l), \fIsql\fP(l) , \fIupdate\fP(l)
.PD <!--
.SH FILES .SH FILES
.PD 0 .PD 0
.TP .TP
...@@ -330,22 +424,8 @@ and \fIsqlca.h\fP. ...@@ -330,22 +424,8 @@ and \fIsqlca.h\fP.
.B /usr/local/pgsql/lib .B /usr/local/pgsql/lib
\fIPostgreSQL\fP libraries including \fIlibecpg.a\fP and \fIPostgreSQL\fP libraries including \fIlibecpg.a\fP and
\fIlibecpg.so\fP. \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> </refsect1>
</refentry> </refentry>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment