Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit b693983

Browse files
bmomjianbmomjian
committed
New ecpg man page.
1 parent 0ad5d2a commit b693983

File tree

1 file changed

+245
-52
lines changed

1 file changed

+245
-52
lines changed

‎src/man/ecpg.1

Lines changed: 245 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,260 @@
1-
.\" This is -*-nroff-*-
2-
.\" XXX standard disclaimer belongs here....
3-
.TH ECPG UNIX 2/11/98 PostgreSQL PostgreSQL
1+
.TH ECPG UNIX 11/28/98 PostgreSQL \fIPostgreSQL\fP
42
.SH NAME
5-
ecpg - embedded SQL preprocessor for C
3+
ecpg - embedded SQL preprocessor for C / PostgreSQL
64
.SH SYNOPSIS
7-
.BR ecpg
8-
[\c
9-
.BR "-v"
10-
]
11-
[\c
12-
.BR "-d"
13-
]
14-
[\c
15-
.BR "-o"
16-
outfile
17-
]
18-
file1
19-
[file2]
20-
[...]
21-
.in -5n
5+
.\" \fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ] file1 [ file2 ] [ ... ]
6+
\fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ] file1 [ file2 ] [ ... ]
227
.SH DESCRIPTION
23-
ecpg an embedded SQL in C package for PostgreSQL. It enables you to
24-
develop C programs with embedded SQL code.
8+
.B \fIecpg\fP
9+
is an embedded SQL preprocessor for C / PostgreSQL. It
10+
enables development of C programs with embedded SQL code.
2511
.PP
26-
.IR "ecpg"
27-
understands the following command-line options:
12+
.B \fIecpg\fP
13+
is ultimately intended to be as compliant as possible with the
14+
ANSI SQL-2 standard and existing commercial ESQL/C packages.
15+
.SH OPTIONS
16+
.B \fIecpg\fP
17+
interprets the following flags when it is invoked
18+
on the command line:
19+
.PP
20+
.PD 0
21+
.TP 10
22+
.BI \-v
23+
Print version information.
24+
.PD
2825
.TP
29-
.BR "-v"
30-
Print version information.
26+
.B \-t
27+
Turn off auto-transactin mode.
28+
.PD
3129
.TP
32-
.BR "-d"
33-
Turn on debugging.
30+
.PD
3431
.TP
35-
.BR "-o" " outfile"
36-
Specifies that
37-
.IR "ecpg"
38-
should write all its output to
39-
.IR "outfile". If no such option is given the output is written to foo.c
40-
if the input file was name foo.pgc or to foo.bar.c if the input file was
41-
foo.bar.
32+
.B \-I include-path
33+
Specify additional include path. Defaults are \.,
34+
/usr/local/include, the PostgreSQL include path which is defined at compile
35+
time (default: /usr/local/pgsql/lib), /usr/include
36+
.PD
4237
.TP
43-
.BR "file1, file2, ..."
44-
The files to be processed.
45-
.SH "BUGS"
46-
The return code is alway -1 in case of an error. You cannot see which error
47-
occured by examining the return code.
38+
.B \-o
39+
Specifies that ecpg should write all its output to outfile.
40+
If no such option is given the output is written to foo.c
41+
(if the input file was named foo.pgc.)
42+
If the input file was named foo.bar the output file will be
43+
named foo.bar.c.
44+
.PD
4845
.TP
49-
The cursor is opened when the declare statement is issued.
46+
.B file1, file2...
47+
The files to be processed.
48+
.\"
49+
.SH INSTALLATION
50+
The
51+
.B \fIecpg\fP
52+
preprocessor is built during the PostgreSQL installation. Binaries and
53+
libraries are installed into the PGBASE (i.e., /usr/local/pgsql/... )
54+
subdirectories.
55+
.SH PREPROCESSING FOR COMPILATION
56+
.B \fIecpg\fP
57+
.\" (-d ) (-o file) file.pgc ( 2> ecpf.log)
58+
(-o file) file.pgc
59+
.LP
60+
.\" The optional \-d flag turns on debugging and 2> ecpg.log
61+
.\" redirects the debug output. The .pgc extension is an
62+
.\" arbitrary means of denoting ecpg source.
63+
The .pgc extension is an arbitrary means of denoting ecpg source.
64+
.SH COMPILING AND LINKING
65+
Assuming the \fIPostgreSQL\fP binaries are in /usr/local/pgsql:
66+
.LP
67+
gcc -g -i /usr/local/pgsql/include (-o file) file.c
68+
-L /usr/local/pgsql/lib -lecpg -lpq
69+
.SH ECPG GRAMMAR
70+
.LP
71+
.SH LIBRARIES
72+
.LP
73+
The preprocessor will prepend two directives to the source:
74+
.LP
75+
\fI#include <ecpgtype.h>\fP and \fI#include <ecpglib.h>\fP
76+
.SH VARIABLE DECLARATION
77+
Variables declared within ecpg source code must be prepended with:
78+
.LP
79+
EXEC SQL BEGIN DECLARE SECTION;
80+
.LP
81+
Similarly, variable declaration sections must terminate with:
82+
.LP
83+
EXEC SQL END DECLARE SECTION;
84+
.LP
85+
NOTE: prior to version 2.1.0, each variable had to be declared
86+
on a separate line. As of version 2.1.0 multiple variables may
87+
be declared on a single line:
88+
.LP
89+
char foo(16), bar(16);
90+
.LP
91+
.SH ERROR HANDLING
92+
The SQL communication area is defined with:
93+
.LP
94+
EXEC SQL INCLUDE sqlca;
95+
.LP
96+
NOTE: the lowercase `sqlca'. While SQL convention may be
97+
followed, i.e., using uppercase to separate embedded SQL
98+
from C statements, sqlca (which includes the sqlca.h
99+
header file) MUST be lowercase. This is because the EXEC SQL
100+
prefix indicates that this INCLUDE will be parsed by ecpg.
101+
ecpg observes case sensitivity (SQLCA.h will not be found.)
102+
EXEC SQL INCLUDE can be used to include other header files
103+
as long as case sensitivity is observed.
104+
.LP
105+
The sqlprint command is used with the EXEC SQL WHENEVER
106+
statement to turn on error handling throughout the
107+
program:
108+
.LP
109+
EXEC SQL WHENEVER sqlerror sqlprint;
110+
.LP
111+
EXEC SQL WHENEVER not found sqlprint;
112+
.LP
113+
PLEASE NOTE: this is *not* an exhaustive example of usage for
114+
the EXEC SQL WHENEVER statement. Further examples of usage may
115+
be found in SQL manuals (e.g., `The LAN TIMES Guide to SQL' by
116+
Groff and Weinberg.)
117+
.LP
118+
.SH CONNECTING TO THE DATABASE SERVER
119+
Prior to version 2.1.0 the database name was single quoted:
120+
.RS
121+
EXEC SQL CONNECT 'test1';
122+
.RE
123+
.LP
124+
As of version 2.1.0, the syntax has been simplified:
125+
.LP
126+
.RS
127+
EXEC SQL CONNECT test1;
128+
.RE
129+
(The database name is no longer quoted.)
130+
.LP
131+
Specifying a server and port name in the connect statement is also possible
132+
as of version 6.4. of PostgreSQL. The syntax is:
133+
.LP
134+
.RS
135+
dbname[@server][:port]
136+
.RE
137+
.LP
138+
or
139+
.LP
140+
.RS
141+
<tcp|unix>:postgresql://server[:port][/dbname][?options]
142+
.RE
143+
.SH QUERIES
144+
.LP
145+
.SS Create Table:
146+
.LP
147+
EXEC SQL CREATE TABLE foo (number int4, ascii char(16));
148+
.RS
149+
EXEC SQL CREATE UNIQUE index num1 on foo(number);
150+
.RE
151+
EXEC SQL COMMIT;
152+
.LP
153+
.SS Insert:
154+
.LP
155+
EXEC SQL INSERT INTO foo (number, ascii)
156+
.RS
157+
VALUES (9999, 'doodad');
158+
.RE
159+
EXEC SQL COMMIT;
160+
.LP
161+
.SS Delete:
162+
.LP
163+
EXEC SQL DELETE FROM foo
164+
.RS
165+
WHERE number = 9999;
166+
.RE
167+
EXEC SQL COMMIT;
168+
.LP
169+
.SS Singleton Select:
170+
.LP
171+
EXEC SQL SELECT foo INTO :FooBar FROM table1
172+
.RS
173+
WHERE ascii = 'doodad';
174+
.RE
175+
.LP
176+
.SS Select using Cursors:
177+
.LP
178+
EXEC SQL DECLARE foo_bar CURSOR FOR
179+
.RS
180+
SELECT number, ascii FROM foo
181+
.RS
182+
ORDER BY ascii;
183+
.RE
184+
.RE
185+
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
186+
.LP
187+
...
188+
EXEC SQL CLOSE foo_bar;
189+
.RS
190+
EXEC SQL COMMIT;
191+
.RE
192+
.LP
193+
.SS Updates
194+
.LP
195+
EXEC SQL UPDATE foo
196+
.RS
197+
SET ascii = 'foobar'
198+
.RE
199+
.RS
200+
WHERE number = 9999;
201+
.RE
202+
EXEC SQL COMMIT;
203+
.LP
204+
.SH BUGS
205+
.LP
206+
The is no EXEC SQL PREPARE statement.
207+
.LP
208+
The complete structure definition MUST be listed
209+
inside the declare section.
210+
.LP
211+
See the TODO file in the source for some more missing features.
212+
.LP
213+
.SH "RETURN VALUE"
214+
.LP
215+
ecpg returns 0 to the shell on successful completion, -1
216+
for errors.
217+
.LP
218+
.SH "SEE ALSO"
219+
.PD 0
50220
.TP
51-
ecpg does not understand enum datatypes.
221+
\fIcc\fP(1), \fIpgintro\fP(l), \fIcommit\fP(l), \fIdelete\fP(l)
52222
.TP
53-
The is no exec sql prepare statement.
223+
\fIfetch\fP(l), \fIselect\fP(l), \fIsql\fP(l) , \fIupdate\fP(l)
224+
.PD
225+
.SH FILES
226+
.PD 0
54227
.TP
55-
The complete structure definition has to be listed inside the declare section for ecpg to be able to understand it.
228+
.B /usr/src/pgsql/postgresql-${ver}/src/interfaces...
229+
./ecpg/include.......source for \fIecpg\fP header files.
230+
./ecpg/lib...........source for \fIecpg\fP libraries.
231+
./ecpg/preproc.......source for \fIecpg\fP header files.
232+
./ecpg/test..........source for \fIecpg\fP libraries.
233+
(test contains examples of syntax for ecpg SQL-C.)
234+
.PD
56235
.TP
57-
Each variable has to be defined on a line on its own.
236+
.B /usr/local/pgsql/bin
237+
\fIPostgreSQL\fP binaries including \fIecpg\fP.
238+
.PD
58239
.TP
59-
There is no way yet to fill a complete array with one call except arrays of [unsigned] char
60-
which are considered strings.
240+
.B /usr/local/pgsql/include
241+
\fIPostgreSQL\fP headers including \fIecpglib.h\fP \fIecpgtype.h\fP
242+
and \fIsqlca.h\fP.
243+
.PD
61244
.TP
62-
ecpg cannot use pointer variables except [unsigned] char *
63-
.SH "RETURN VALUE"
64-
.IR ecpg
65-
returns 0 to the shell on successful completion, -1 for errors,
66-
.SH "SEE ALSO"
67-
cc(1).
245+
.B /usr/local/pgsql/lib
246+
\fIPostgreSQL\fP libraries including \fIlibecpg.a\fP and
247+
\fIlibecpg.so\fP.
248+
.SH AUTHORS
249+
Linus Tolke \fI<linus@epact.se>\fP
250+
- original author of ECPG (up to version 0.2).
251+
.br
252+
.PP
253+
Michael Meskes \fI<meskes@debian.org>\fP
254+
- actual author and maintainer of ECPG.
255+
.br
256+
.PP
257+
Thomas Good \fI<tomg@q8.nrnet.org>\fP
258+
- author of this revision of the ecpg man page.
259+
.br
260+
.zZ

0 commit comments

Comments
 (0)