View Source: ecpg(1) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
ECPG
!!!ECPG
NAME
SYNOPSIS
DESCRIPTION
USAGE
GRAMMAR
NOTES
----
!!NAME


ecpg - embedded SQL C preprocessor
!!SYNOPSIS


__ecpg__ [[ __-v__ ] [[ __-t__ ] [[ __-I__
''include-path'' ] [[ __-o__ ''outfile'' ]
''file''...


__INPUTS__


__ecpg__ accepts the following command line
arguments:


__-v__


Print version information.


__-t__


Turn on auto-commit of transactions. In this mode, each
query is automatically committed unless it is inside an
explicit transaction block. In the default mode, queries are
committed only when __exec sql commit__ is
issued.


__-I__ ''include-path''


Specify an additional include path. Defaults are ''.''
(current directory), ''/usr/local/include'', the
PostgreSQL include path which is defined at compile time
(default: ''/usr/local/pgsql/include''), and
''/usr/include''.


__-o__ ''outfile''


Specifies that __ecpg__ should write all its output to
''outfile''. If no such option is given the output is
written to ''name.c'', assuming the input file was named
''name.pgc''. If the input file does have the expected
.pgc suffix, then the output file will have .pgc appended to
the input file name.


''file''


The files to be processed.


__OUTPUTS__


__ecpg__ will create a file or write to
''stdout''.


__Return value__


__ecpg__ returns 0 to the shell on successful completion,
non-zero for errors.
!!DESCRIPTION


__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 (
ecpg__ (up to version 0.2). Michael Meskes
(
__ecpg__. Thomas Good
(
__ecpg__ man page, on which this document
is based.
!!USAGE


__PREPROCESSING FOR COMPILATION__


An embedded SQL source file must be preprocessed before
compilation:


ecpg [[ -d ] [[ -o ''file'' ] ''file''.pgc
where the optional __-d__ flag turns on debugging. The .pgc extension is an arbitrary means of denoting __ecpg__ source.


You may want to redirect the preprocessor output to a log
file.


__COMPILING AND LINKING__


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
!!GRAMMAR


__LIBRARIES__


The preprocessor will prepend two directives to the
source:


#include


__VARIABLE DECLARATION__


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;


__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:


char  foo[[16], bar[[16];


__ERROR HANDLING__


The SQL communication area is defined with:


EXEC SQL INCLUDE sqlca;


__Note:__ The sqlca is in lowercase. 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 inclusion
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.


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;


__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).


__CONNECTING TO THE DATABASE SERVER__


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:


''dbname''[[@''server''][[:''port'']
or


server''[[:''port''][[/''dbname''][[?''options'']


__QUERIES__


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.


Create Table:


EXEC SQL CREATE TABLE foo (number int4, ascii char(16));
EXEC SQL CREATE UNIQUE index num1 on foo(number);
EXEC SQL COMMIT;
Insert:


EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
EXEC SQL COMMIT;
Delete:


EXEC SQL DELETE FROM foo WHERE number = 9999;
EXEC SQL COMMIT;
Singleton Select:


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;
Updates:


EXEC SQL UPDATE foo
SET ascii = 'foobar'
WHERE number = 9999;
EXEC SQL COMMIT;
!!NOTES


The complete structure definition MUST be listed inside the
declare section.


See the ''TODO'' file in the source for some more missing
features.
----
One page links to ecpg(1):
Man1e
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Monday, June 3, 2002 6:50:09 pm by "perry"
Edit PageHistory Diff Info LikePages