ecpg accepts the following command line arguments:
ecpg will create a file or write to stdout.
ecpg is an embedded SQL preprocessor for the C language and the PostgreSQL. It enables development of C programs with embedded SQL code.
Linus Tolke (<firstname.lastname@example.org>) was the original author of ecpg (up to version 0.2). Michael Meskes (<email@example.com>) is the current author and maintainer of ecpg. Thomas Good (<firstname.lastname@example.org>) is the author of the last revision of the ecpg man page, on which this document is based.
An embedded SQL source file must be preprocessed before compilation:
ecpg [ -d ] [ -o file ] file.pgcwhere the optional -d flag turns on debugging. The .pgc extension is an arbitrary means of denoting ecpg source.
Assuming the PostgreSQL binaries are in /usr/local/pgsql, you will need to compile and link your preprocessed source file:
gcc -g -I /usr/local/pgsql/include [ -o file ] file.c -L /usr/local/pgsql/lib -lecpg -lpq
The preprocessor will prepend two directives to the source:
#include <ecpgtype.h> #include <ecpglib.h>
Variables declared within ecpg source code must be prepended with:
EXEC SQL BEGIN DECLARE SECTION;
Similarly, variable declaration sections must terminate with:
EXEC SQL END DECLARE SECTION;
char foo, bar;
The SQL communication area is defined with:
EXEC SQL INCLUDE sqlca;
The sqlprint command is used with the EXEC SQL WHENEVER statement to turn on error handling throughout the program:
EXEC SQL WHENEVER sqlerror sqlprint;and
EXEC SQL WHENEVER not found sqlprint;
One connects to a database using the following:
EXEC SQL CONNECT TO dbname;where the database name is not quoted. Prior to version 2.1.0, the database name was required to be inside single quotes.
Specifying a server and port name in the connect statement is also possible. The syntax is:
In general, SQL queries acceptable to other applications such as psql can be embedded into your C code. Here are some examples of how to do that.
EXEC SQL CREATE TABLE foo (number int4, ascii char(16)); EXEC SQL CREATE UNIQUE index num1 on foo(number); EXEC SQL COMMIT;
EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad'); EXEC SQL COMMIT;
EXEC SQL DELETE FROM foo WHERE number = 9999; EXEC SQL COMMIT;
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
Select using Cursors:
EXEC SQL DECLARE foo_bar CURSOR FOR SELECT number, ascii FROM foo ORDER BY ascii; EXEC SQL FETCH foo_bar INTO :FooBar, DooDad; EXEC SQL CLOSE foo_bar; EXEC SQL COMMIT;
EXEC SQL UPDATE foo SET ascii = 'foobar' WHERE number = 9999; EXEC SQL COMMIT;
The complete structure definition MUST be listed inside the declare section.
See the TODO file in the source for some more missing features.