New ecpg man page.

src/man/ecpg.1

@@ -1,67 +1,260 @@
-.\" This is -*-nroff-*-
+.TH ECPG UNIX 11/28/98 PostgreSQL \fIPostgreSQL\fP
-.\" XXX standard disclaimer belongs here....
-.TH ECPG UNIX 2/11/98 PostgreSQL PostgreSQL
 .SH NAME
-ecpg - embedded SQL preprocessor for C
+ecpg - embedded SQL preprocessor for C / PostgreSQL
 .SH SYNOPSIS
-.BR ecpg
+.\" \fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ]  file1 [ file2 ] [ ... ]
-[\c
+\fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ]  file1 [ file2 ] [ ... ]
-.BR "-v"
-]
-[\c
-.BR "-d"
-]
-[\c
-.BR "-o"
-outfile
-]
-file1
-[file2]
-[...]
-.in -5n
 .SH DESCRIPTION
-ecpg an embedded SQL in C package for PostgreSQL. It enables you to
+.B \fIecpg\fP
-develop C programs with embedded SQL code.
+is an embedded SQL preprocessor for C / PostgreSQL. It
+enables development of C programs with embedded SQL code.
 .PP
-.IR "ecpg"
+.B \fIecpg\fP
-understands the following command-line options:
+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
-.BR "-v"
+.B \-t
-Print version information.
+Turn off auto-transactin mode.
+.PD
 .TP
-.BR "-d"
+.PD
-Turn on debugging.
 .TP
-.BR "-o" " outfile"
+.B \-I include-path
-Specifies that
+Specify additional include path. Defaults are \.,
-.IR "ecpg"
+/usr/local/include, the PostgreSQL include path which is defined at compile
-should write all its output to 
+time (default: /usr/local/pgsql/lib), /usr/include
-.IR "outfile". If no such option is given the output is written to foo.c
+.PD
-if the input file was name foo.pgc or to foo.bar.c if the input file was
-foo.bar.
 .TP
-.BR "file1, file2, ..."
+.B \-o
-The files to be processed.
+Specifies that ecpg should write all its output to outfile.
-.SH "BUGS"
+If no such option is given the output is written to foo.c
-The return code is alway -1 in case of an error. You cannot see which error
+(if the input file was named foo.pgc.)
-occured by examining the return code.
+If the input file was named foo.bar the output file will be
+named foo.bar.c. 
+.PD
 .TP
-The cursor is opened when the declare statement is issued.
+.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
+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
+char  foo(16), bar(16);
+.LP       
+.SH ERROR HANDLING
+The SQL communication area is defined with:
+.LP
+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
+EXEC SQL WHENEVER sqlerror sqlprint;
+.LP
+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
+EXEC SQL COMMIT;
+.LP 
+.SS Insert:
+.LP
+EXEC SQL INSERT INTO foo (number, ascii)
+.RS
+VALUES (9999, 'doodad');
+.RE
+EXEC SQL COMMIT;
+.LP
+.SS Delete:
+.LP
+EXEC SQL DELETE FROM foo
+.RS
+WHERE number = 9999;   
+.RE
+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
+EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
+.LP
+...
+EXEC SQL CLOSE foo_bar;
+.RS
+EXEC SQL COMMIT;
+.RE
+.LP
+.SS Updates
+.LP
+EXEC SQL UPDATE foo
+.RS
+SET ascii = 'foobar'
+.RE
+.RS
+WHERE number = 9999;
+.RE
+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
-ecpg does not understand enum datatypes.
+\fIcc\fP(1), \fIpgintro\fP(l), \fIcommit\fP(l), \fIdelete\fP(l)
 .TP
-The is no exec sql prepare statement.
+\fIfetch\fP(l), \fIselect\fP(l), \fIsql\fP(l) , \fIupdate\fP(l)
+.PD
+.SH FILES
+.PD 0
 .TP
-The complete structure definition has to be listed inside the declare section for ecpg to be able to understand it.
+.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
-Each variable has to be defined on a line on its own.
+.B /usr/local/pgsql/bin 
+\fIPostgreSQL\fP binaries including \fIecpg\fP.
+.PD
 .TP
-There is no way yet to fill a complete array with one call except arrays of [unsigned] char
+.B /usr/local/pgsql/include 
-which are considered strings.
+\fIPostgreSQL\fP headers including \fIecpglib.h\fP \fIecpgtype.h\fP 
+and \fIsqlca.h\fP.
+.PD
 .TP
-ecpg cannot use pointer variables except [unsigned] char *
+.B /usr/local/pgsql/lib 
-.SH "RETURN VALUE"
+\fIPostgreSQL\fP libraries including \fIlibecpg.a\fP and 
-.IR ecpg
+\fIlibecpg.so\fP.
-returns 0 to the shell on successful completion, -1 for errors,
+.SH AUTHORS
-.SH "SEE ALSO"
+Linus Tolke \fI<linus@epact.se>\fP
-cc(1).
+- 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