ecpg - Embedded SQL C preprocessor


SYNOPSIS

       ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ]  file1 [ file2 ] [ ... ]

   INPUTS
       ecpg accepts the following command line arguments:

       -v     Print version information.

       -t     Turn off auto-transaction mode.

       -I path
              Specify  an  additional include path.  Defaults are
              ., /usr/local/include, the  Postgres  include  path
              which   is   defined   at  compile  time  (default:
              /usr/local/pgsql/lib), and /usr/include.

       -o     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 comple­
              tion, -1 for errors.


DESCRIPTION

       ecpg is an embedded SQL preprocessor for  the  C  language
       and  the  Postgres.  It  enables development of C programs
       with embedded SQL code.

       Linus Tolke (<linus@epact.se>) was the original author  of
       ecpg    (up    to    version    0.2).     Michael   Meskes
       (<meskes@debian.org>) is the current author and maintainer
       of  ecpg.  Thomas Good (<tomg@q8.nrnet.org>) is the author
       of the last revision of the ecpg man page, on  which  this
       document is based.


USAGE

   PREPROCESSING FOR COMPILATION
       An  embedded  SQL  source file must be preprocessed before


       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 Postgres 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 <ecpgtype.h>
       #include <ecpglib.h>

   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);

       The SQL communication area is defined with:

       EXEC SQL INCLUDE sqlca;

              Note: The sqlca is in lowercase.  While SQL conven­
              tion may be followed, i.e., using uppercase to sep­
              arate embedded SQL from C statements, sqlca  (which
              includes  the  sqlca.h  header file) MUST be lower­
              case. 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.

       The  sqlprint  command  is used with the EXEC SQL WHENEVER
       statement to turn on error handling  throughout  the  pro­
       gram:

       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 exam­
              ples  of  usage  may be found in SQL manuals (e.g.,
              `The LAN TIMES Guide to SQL'  by  Groff  and  Wein­
              berg).

   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]


       <tcp|unix>:postgresql://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'

       EXEC SQL COMMIT;


NOTES

       There is no EXEC SQL PREPARE statement.

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

       See the TODO file in the source for some more missing fea­
       tures.


Man(1) output converted with man2html