From f43974f6f12c9f2ac8dc02585bd2a156ff608453 Mon Sep 17 00:00:00 2001
From: "Thomas G. Lockhart" <lockhart@fourpalms.org>
Date: Fri, 31 Mar 2000 06:17:52 +0000
Subject: [PATCH] Include all information from the old man pages.

---
 doc/src/sgml/ref/ecpg-ref.sgml | 550 +++++++++++++++++++--------------
 1 file changed, 315 insertions(+), 235 deletions(-)

diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml
index 04f86d57fe..8bb1dd27f1 100644
--- a/doc/src/sgml/ref/ecpg-ref.sgml
+++ b/doc/src/sgml/ref/ecpg-ref.sgml
@@ -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 &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 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>
+&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;
-.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>