Penguin
Recent Changes
Annotated edit history of ecpg(1) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 ECPG
2 !!!ECPG
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 USAGE
7 GRAMMAR
8 NOTES
9 ----
10 !!NAME
11
12
13 ecpg - embedded SQL C preprocessor
14 !!SYNOPSIS
15
16
17 __ecpg__ [[ __-v__ ] [[ __-t__ ] [[ __-I__
18 ''include-path'' ] [[ __-o__ ''outfile'' ]
19 ''file''...
20
21
22 __INPUTS__
23
24
25 __ecpg__ accepts the following command line
26 arguments:
27
28
29 __-v__
30
31
32 Print version information.
33
34
35 __-t__
36
37
38 Turn on auto-commit of transactions. In this mode, each
39 query is automatically committed unless it is inside an
40 explicit transaction block. In the default mode, queries are
41 committed only when __exec sql commit__ is
42 issued.
43
44
45 __-I__ ''include-path''
46
47
48 Specify an additional include path. Defaults are ''.''
49 (current directory), ''/usr/local/include'', the
50 PostgreSQL include path which is defined at compile time
51 (default: ''/usr/local/pgsql/include''), and
52 ''/usr/include''.
53
54
55 __-o__ ''outfile''
56
57
58 Specifies that __ecpg__ should write all its output to
59 ''outfile''. If no such option is given the output is
60 written to ''name.c'', assuming the input file was named
61 ''name.pgc''. If the input file does have the expected
62 .pgc suffix, then the output file will have .pgc appended to
63 the input file name.
64
65
66 ''file''
67
68
69 The files to be processed.
70
71
72 __OUTPUTS__
73
74
75 __ecpg__ will create a file or write to
76 ''stdout''.
77
78
79 __Return value__
80
81
82 __ecpg__ returns 0 to the shell on successful completion,
83 non-zero for errors.
84 !!DESCRIPTION
85
86
87 __ecpg__ is an embedded SQL preprocessor for the C
88 language and the PostgreSQL. It enables development of C
89 programs with embedded SQL code.
90
91
92 Linus Tolke (
93 ecpg__ (up to version 0.2). Michael Meskes
94 (
95 __ecpg__. Thomas Good
96 (
97 __ecpg__ man page, on which this document
98 is based.
99 !!USAGE
100
101
102 __PREPROCESSING FOR COMPILATION__
103
104
105 An embedded SQL source file must be preprocessed before
106 compilation:
107
108
109 ecpg [[ -d ] [[ -o ''file'' ] ''file''.pgc
110 where the optional __-d__ flag turns on debugging. The .pgc extension is an arbitrary means of denoting __ecpg__ source.
111
112
113 You may want to redirect the preprocessor output to a log
114 file.
115
116
117 __COMPILING AND LINKING__
118
119
120 Assuming the PostgreSQL binaries are in
121 ''/usr/local/pgsql'', you will need to compile and link
122 your preprocessed source file:
123
124
125 gcc -g -I /usr/local/pgsql/include [[ -o ''file'' ] ''file''.c -L /usr/local/pgsql/lib -lecpg -lpq
126 !!GRAMMAR
127
128
129 __LIBRARIES__
130
131
132 The preprocessor will prepend two directives to the
133 source:
134
135
136 #include
137
138
139 __VARIABLE DECLARATION__
140
141
142 Variables declared within __ecpg__ source code must be
143 prepended with:
144
145
146 EXEC SQL BEGIN DECLARE SECTION;
147 Similarly, variable declaration sections must terminate with:
148
149
150 EXEC SQL END DECLARE SECTION;
151
152
153 __Note:__ Prior to version 2.1.0, each variable had to be
154 declared on a separate line. As of version 2.1.0 multiple
155 variables may be declared on a single line:
156
157
158 char foo[[16], bar[[16];
159
160
161 __ERROR HANDLING__
162
163
164 The SQL communication area is defined with:
165
166
167 EXEC SQL INCLUDE sqlca;
168
169
170 __Note:__ The sqlca is in lowercase. While SQL convention
171 may be followed, i.e., using uppercase to separate embedded
172 SQL from C statements, sqlca (which includes the
173 ''sqlca.h'' header file) __must__ be lowercase. This
174 is because the EXEC SQL prefix indicates that this inclusion
175 will be parsed by __ecpg__. __ecpg__ observes case
176 sensitivity (''SQLCA.h'' will not be found). __EXEC SQL
177 INCLUDE__ can be used to include other header files as
178 long as case sensitivity is observed.
179
180
181 The sqlprint command is used with the EXEC SQL WHENEVER
182 statement to turn on error handling throughout the
183 program:
184
185
186 EXEC SQL WHENEVER sqlerror sqlprint;
187 and
188
189
190 EXEC SQL WHENEVER not found sqlprint;
191
192
193 __Note:__ This is __not__ an exhaustive example of
194 usage for the __EXEC SQL WHENEVER__ statement. Further
195 examples of usage may be found in SQL manuals (e.g., ''The
196 LAN TIMES Guide to SQL'' by Groff and
197 Weinberg).
198
199
200 __CONNECTING TO THE DATABASE SERVER__
201
202
203 One connects to a database using the following:
204
205
206 EXEC SQL CONNECT TO ''dbname'';
207 where the database name is not quoted. Prior to version 2.1.0, the database name was required to be inside single quotes.
208
209
210 Specifying a server and port name in the connect statement
211 is also possible. The syntax is:
212
213
214 ''dbname''[[@''server''][[:''port'']
215 or
216
217
218 server''[[:''port''][[/''dbname''][[?''options'']
219
220
221 __QUERIES__
222
223
224 In general, SQL queries acceptable to other applications
225 such as __psql__ can be embedded into your C code. Here
226 are some examples of how to do that.
227
228
229 Create Table:
230
231
232 EXEC SQL CREATE TABLE foo (number int4, ascii char(16));
233 EXEC SQL CREATE UNIQUE index num1 on foo(number);
234 EXEC SQL COMMIT;
235 Insert:
236
237
238 EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
239 EXEC SQL COMMIT;
240 Delete:
241
242
243 EXEC SQL DELETE FROM foo WHERE number = 9999;
244 EXEC SQL COMMIT;
245 Singleton Select:
246
247
2 perry 248 EXEC SQL SELECT foo INTO :!FooBar FROM table1 WHERE ascii = 'doodad';
1 perry 249 Select using Cursors:
250
251
252 EXEC SQL DECLARE foo_bar CURSOR FOR
253 SELECT number, ascii FROM foo
254 ORDER BY ascii;
2 perry 255 EXEC SQL FETCH foo_bar INTO :!FooBar, !DooDad;
1 perry 256 EXEC SQL CLOSE foo_bar;
257 EXEC SQL COMMIT;
258 Updates:
259
260
261 EXEC SQL UPDATE foo
262 SET ascii = 'foobar'
263 WHERE number = 9999;
264 EXEC SQL COMMIT;
265 !!NOTES
266
267
268 The complete structure definition MUST be listed inside the
269 declare section.
270
271
272 See the ''TODO'' file in the source for some more missing
273 features.
274 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.