mirror of
https://github.com/postgres/postgres.git
synced 2025-05-03 22:24:49 +03:00
New ecpg man page.
This commit is contained in:
Bruce Momjian
parent
0ad5d2a3a8
commit
b693983004
305
src/man/ecpg.1
305
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
|
.SH NAME
|
||||||
ecpg - embedded SQL preprocessor for C
|
ecpg - embedded SQL preprocessor for C / PostgreSQL
|
||||||
.SH SYNOPSIS
|
.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
|
.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
|
.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
|
.TP
|
||||||
.BR "-v"
|
.B \-t
|
||||||
Print version information.
|
Turn off auto-transactin mode.
|
||||||
|
.PD
|
||||||
.TP
|
.TP
|
||||||
.BR "-d"
|
.PD
|
||||||
Turn on debugging.
|
|
||||||
.TP
|
.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
|
.TP
|
||||||
.BR "file1, file2, ..."
|
.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.
|
The files to be processed.
|
||||||
.SH "BUGS"
|
.\"
|
||||||
The return code is alway -1 in case of an error. You cannot see which error
|
.SH INSTALLATION
|
||||||
occured by examining the return code.
|
The
|
||||||
.TP
|
.B \fIecpg\fP
|
||||||
The cursor is opened when the declare statement is issued.
|
preprocessor is built during the PostgreSQL installation. Binaries and
|
||||||
.TP
|
libraries are installed into the PGBASE (i.e., /usr/local/pgsql/... )
|
||||||
ecpg does not understand enum datatypes.
|
subdirectories.
|
||||||
.TP
|
.SH PREPROCESSING FOR COMPILATION
|
||||||
The is no exec sql prepare statement.
|
.B \fIecpg\fP
|
||||||
.TP
|
.\" (-d ) (-o file) file.pgc ( 2> ecpf.log)
|
||||||
The complete structure definition has to be listed inside the declare section for ecpg to be able to understand it.
|
(-o file) file.pgc
|
||||||
.TP
|
.LP
|
||||||
Each variable has to be defined on a line on its own.
|
.\" The optional \-d flag turns on debugging and 2> ecpg.log
|
||||||
.TP
|
.\" redirects the debug output. The .pgc extension is an
|
||||||
There is no way yet to fill a complete array with one call except arrays of [unsigned] char
|
.\" arbitrary means of denoting ecpg source.
|
||||||
which are considered strings.
|
The .pgc extension is an arbitrary means of denoting ecpg source.
|
||||||
.TP
|
.SH COMPILING AND LINKING
|
||||||
ecpg cannot use pointer variables except [unsigned] char *
|
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"
|
.SH "RETURN VALUE"
|
||||||
.IR ecpg
|
.LP
|
||||||
returns 0 to the shell on successful completion, -1 for errors,
|
ecpg returns 0 to the shell on successful completion, -1
|
||||||
|
for errors.
|
||||||
|
.LP
|
||||||
.SH "SEE ALSO"
|
.SH "SEE ALSO"
|
||||||
cc(1).
|
.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
|
||||||
|
.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.
|
||||||
|
.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
|
||||||
Loading…
x
Reference in New Issue
Block a user