\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename ecpg.info
-@settitle Ecpg - Embedded SQL in C for Postgres95
+@settitle Ecpg - Embedded SQL in C for PostgreSQL
@setchapternewpage odd
@c %**end of header
@ifinfo
-This file documents an embedded SQL in C package for Postgres 95.
+This file documents an embedded SQL in C package for PostgreSQL.
Copyright 1996 Linus Tolke
Permission is granted to copy and use in the same way as you are allowed
-to copy and use the rest of the Postgres 95.
+to copy and use the rest of the PostgreSQL.
@end ifinfo
@c This title page illustrates only one of the
@titlepage
@title ECPG
-@subtitle Embedded SQL in C for Postgres95
+@subtitle Embedded SQL in C for PostgreSQL
@author Linus Tolke
@c The following two commands
@c start the copyright page.
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1996 Linus Tolke
+Copyright @copyright{} 1996-1997 Linus Tolke, 1998 Michael Meskes
Published by Linus Tolke
Permission is granted to copy and use in the same way as you are allowed
-to copy and use the rest of the Postgres 95.
+to copy and use the rest of the PostgreSQL.
@end titlepage
@node Top, Why embedded SQL, (dir), (dir)
@comment node-name, next, previous, up
@ifinfo
-Ecpg is an embedded sql preprocessor for C and library for Postgres95.
+Ecpg is an embedded sql preprocessor for C and library for PostgresSQL
-It is written by Linus Tolke <linus@@epact.se>
+It is written by Linus Tolke <linus@@epact.se> and Michael Meskes <meskes@@debian.org>.
-This texinfo page and the code is all the documentation you get. There
-will not be any separate manual page, installation description or
-buglist.
@end ifinfo
@menu
extensions so it is difficult to obtain portability even between them
anyway. I have not read the standard but I hope that my implementation
does not deviate to much and that it would be possible to port programs
-with embedded sql written for other DBMS:s to Postgres95 and thus
+with embedded sql written for other DBMS:s to PostgreSQL and thus
promoting the spirit of free software.
@cindex preprocessor
@cindex @code{ecpg}
The preprocessor is called @code{ecpg}. After installation it resides in
-the postgres @code{bin} directory. It accepts two arguments like
-@code{iname=filename} and @code{oname=filename}. Both arguments must be
-present or an error will occur.
+the postgres @code{bin} directory.
@node Library, Error handling, Preprocessor, How to use it
@section Library
@cindex library functions
@cindex @code{libecpg.a}
@cindex @code{-lecpg}
-The library is called @code{libecpg.a}. The library used the pq library
-for the communication to the postgres server so you will have to link
-your program with @code{-lecpg -lpq}.
+The library is called @code{libecpg.a} resp. @code{libecpg.so}. The library
+used the pq library for the communication to the postgres server so you will
+have to link your program with @code{-lecpg -lpq}.
The library has some methods that are "hidden" but that could prove very
useful sometime.
@table @asis
-@item @code{ECPGdebug(int)}
-@cindex @code{ECPGdebug(int)}
+@item @code{ECPGdebug(int, FILE *stream)}
+@cindex @code{ECPGdebug(int, FILE *stream)}
@cindex debuglogging
-If this is called, with a non-zero argument, then debuglogging is turned
-on. Debuglogging is done on @code{stderr}. Most SQL statement logs its
+If this is called, with the first argument non-zero, then debuglogging is turned
+on. Debuglogging is done on @code{stream}. Most SQL statement logs its
arguments and result.
The most important one (@code{ECPGdo}) that is called on all SQL
statements except @code{EXEC SQL COMMIT}, @code{EXEC SQL ROLLBACK},
@code{EXEC SQL CONNECT} logs both its expanded string, i.e. the string
with all the input variables inserted, and the result from the
-postgres95 server. This can be very useful when searching for errors
+PostgreSQL server. This can be very useful when searching for errors
in your SQL statements.
@item @code{ECPGstatus()}
The preprocessor has goofed up and generated some incorrect code.
@item -1, Error starting transaction line %d.
-Postgres95 signalled to us that we cannot open the connection.
+PostgreSQL signalled to us that we cannot open the connection.
@item -1, Postgres error: %s line %d.
-Some postgres95 error. The message contains the error message from the
-postgres95 backend.
+Some PostgreSQL error. The message contains the error message from the
+PostgreSQL backend.
@item 1, Data not found line %d.
This is a "normal" error that tells you that what you are quering cannot
@item -1, Not correctly formatted int type: %s line %d.
This means that the host variable is of an @code{int} type and the field
-in the postgres95 database is of another type and contains a value that
+in the PostgreSQL database is of another type and contains a value that
cannot be interpreted as an @code{int}. The library uses @code{strtol}
for this conversion.
@item -1, Not correctly formatted unsigned type: %s line %d.
This means that the host variable is of an @code{unsigned int} type and
-the field in the postgres95 database is of another type and contains a
+the field in the PostgreSQL database is of another type and contains a
value that cannot be interpreted as an @code{unsigned int}. The library
uses @code{strtoul} for this conversion.
@item -1, Not correctly formatted floating point type: %s line %d.
This means that the host variable is of an @code{float} type and
-the field in the postgres95 database is of another type and contains a
+the field in the PostgreSQL database is of another type and contains a
value that cannot be interpreted as an @code{float}. The library
uses @code{strtod} for this conversion.
@item -1, Too few arguments line %d.
-This means that the postgres95 has returned more records than we have
+This means that PostgreSQL has returned more records than we have
matching variables. Perhaps you have forgotten a couple of the host
variables in the @code{INTO :var1,:var2}-list.
@item -1, Too many arguments line %d.
-This means that th postgres95 has returned fewer records than we have
+This means that PostgreSQL has returned fewer records than we have
host variables. Perhaps you have to many host variables in the
@code{INTO :var1,:var2}-list.
@item -1, Empty query line %d.
-Postgres95 returned PGRES_EMPTY_QUERY.
+PostgreSQL returned PGRES_EMPTY_QUERY.
@item -1, Error: %s line %d.
-This means that Postgres95 returned on of the errors
+This means that PostgreSQL returned on of the errors
PGRES_NONFATAL_ERROR, PGRES_FATAL_ERROR or PGRES_BAD_RESPONSE. Which one
and why is explained in the message.
@item -1, Postgres error line %d.
-Postgres95 returns something that the library does not know how to
-handle. This is probably because the version of postgres95 does not
+PostgreSQL returns something that the library does not know how to
+handle. This is probably because the version of PostgreSQL does not
match the version of the ecpg library.
@item -1, Error committing line %d.
Error during @code{COMMIT}. @code{EXEC SQL COMMIT} is translated to an
-@code{end} operation in postgres95 and that is the operation that could
+@code{end} operation in PostgreSQL and that is the operation that could
not be performed.
@item -1, Error rolling back line %d.
Error during @code{ROLLBACK}. @code{EXEC SQL ROLLBACK} is translated to
-an @code{abort} operation in postgres95 and that is the operation that
+an @code{abort} operation in PostgreSQL and that is the operation that
could not be performed.
@item -1, ECPGconnect: could not open database %s.
@chapter Installation
@cindex installation
-Step by step installation (if everything goes ok):
-
-@enumerate
-@item Fetch everything and unpack
-
-If you are reading this documentation you have probably managed this
-step already.
-
-@item @code{./configure --with-postgres=/path/to/postgres}
-
-This is to be done in the ecpg directory, i.e. the directory containing
-the @file{configure} file.
-
-The @file{/path/to/postgres} is the path to the installed postgres. It
-points out the directory where the include, lib and bin directories
-reside. The include directory is used when building the library and all
-three of them become residents for ecpg include files, library and
-binaries.
-
-@item @code{make all}
-
-@item As the postgres user @code{make install}
-
-The postgres user is the owner of the postgres include, lib and bin
-directories. The installation procedure installs its files there
-alongside the postgres files.
-@item Done.
-
-@end enumerate
-
+Since version 0.5 ecpg is distributed together with PostgreSQL. So you
+should get your precompiler, libraries and header files compiled and
+installed on the fly.
@node Index, For the developer, Installation, Top
@unnumbered Index
@item Preprocessor output
The variables should be static.
-@item The preprocessor interface is strange, to say the least
-It would be better with a consistant unix arguments interface, perhaps
-builtin default filenames so they won't have to be given all the time.
-
@item Preprocessor cannot do syntax checking on your SQL statements
-Whatever you write is copied more or less exactly to the postgres95 and
+Whatever you write is copied more or less exactly to the PostgreSQL and
you will not be able to locate your errors until run-time.
@item no restriction to strings only
@comment node-name, next, previous, up
@section The preprocessor
-First three lines are written to the output. A comment and two include
+First four lines are written to the output. Two comments and two include
lines necessary for the interface to the library.
Then the preprocessor works in one pass only reading the input file and
@example
exec sql open blablabla;
@end example
-and that is ignore and not copied from the output.
+and is ignore and not copied from the output.
@item Commit statement
@cindex Commit statement
projects / postgresql / commitdiff