\input texinfo @c -*-texinfo-*-
@c %**start of header
-@setfilename ecpg
+@setfilename ecpg.info
@settitle Ecpg - Embedded SQL in C for Postgres95
@setchapternewpage odd
@c %**end of header
* Why embedded SQL::
* Simple description of the concept::
* How to use it::
-* How it works::
* Limitations::
* Porting from other DBMSs::
* Installation::
* Index::
+* For the developer::
--- The Detailed Node Listing ---
* Library::
* Error handling::
-How it works
+For the developer
+* To do list::
* The preprocessor::
* A complete example::
* The library::
-
-Limitations
-
-* What can be done with this concept::
-* What will never be included and why::
@end menu
@node Why embedded SQL, Simple description of the concept, Top, Top
can continue with the result.
-@node How to use it, How it works, Simple description of the concept, Top
+@node How to use it, Limitations, Simple description of the concept, Top
@comment node-name, next, previous, up
@chapter How to use it
@code{iname=filename} and @code{oname=filename}. Both arguments must be
present or an error will occur.
-In the alpha version the preprocessor has a lot of flaws:
-@table @asis
-@item Debug text output
-It writes every token parsed to the @code{stderr}.
-@item Looses line numbering
-The line numbers and file name information is lost in the preprocessor.
-This means that when running the program through a debugger you end up
-in the @code{.c}-file that is the output from the preprocessor and not
-in the input to the preprocessor. This can be fixed!
-@item The 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 Cannot do syntax checking on your SQL statements
-Whatever you write is copied more or less exactly to the postgres95 and
-you will not be able to locate your errors until run-time.
-@end table
-
@node Library, Error handling, Preprocessor, How to use it
@section Library
Postgres95 returned PGRES_EMPTY_QUERY.
@item -1, Error: %s line %d.
-Postgres95 returned PGRES_NONFATAL_ERROR, PGRES_FATAL_ERROR or
-PGRES_BAD_RESPONSE. Which one and why is hopefully explained in the
-message.
+This means that Postgres95 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
@end table
-@node How it works, Limitations, How to use it, Top
-@chapter How it works
+@node Limitations, Porting from other DBMSs, How to use it, Top
+@chapter Limitations
+@comment node-name, next, previous, up
+
+What will never be included and why or what cannot be done with this
+concept.
+
+@table @asis
+
+@item oracles single tasking possibility
+@cindex single tasking
+Oracle version 7.0 on AIX 3 uses the OS-supported locks on the shared
+memory segments and allows the application designer to link an
+application in a so called single tasking way. Instead of starting one
+client process per application process both the database part and the
+application part is run in the same process. In later versions of oracle
+this is no longer supported.
+
+This would require a total redesign of the postgres access model and
+that effort can not justify the performance gained.
+
+@end table
+
+
+@node Porting from other DBMSs, Installation, Limitations, Top
+@chapter Porting from other DBMSs
+@comment node-name, next, previous, up
+
+To be written by persons that knows the different DBMSs and that
+actually does port something...
+
+@node Installation, Index, Porting from other DBMSs, Top
+@comment node-name, next, previous, up
+@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
+
+
+@node Index, For the developer, Installation, Top
+@unnumbered Index
+
+@printindex cp
+
+@node For the developer, , Index, Top
@comment node-name, next, previous, up
+@chapter For the developer
-This chapter describes how the things work. The ambition is to make this
-chapter contain things for those that want to have a look inside and the
-chapter on How to use it should be enough for all normal questions.
+This chapter is for those that wants to develop the ecpg interface. It
+describes how the things work. The ambition is to make this chapter
+contain things for those that want to have a look inside and the chapter
+on How to use it should be enough for all normal questions.
So, read this before looking at the internals of the @code{ecpg}. If
you are not interested in how it really works, skip this chapter.
@menu
+* To do list::
* The preprocessor::
* A complete example::
* The library::
@end menu
-@node The preprocessor, A complete example, How it works, How it works
+
+@node To do list, The preprocessor, For the developer, For the developer
+@comment node-name, next, previous, up
+@section To do list
+
+In the alpha version the preprocessor has a lot of flaws:
+@table @asis
+
+@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
+you will not be able to locate your errors until run-time.
+
+@item no restriction to strings only
+The PQ interface, and most of all the PQexec function, that is used by
+the ecpg relies on that the request is built up as a string. In some
+cases, like when the data contains the null character, this will be a
+serious problem.
+
+@item error codes
+There should be different error numbers for the different errors instead
+of just -1 for them all.
+
+@item library functions
+to_date et al.
+
+@item records
+@cindex records
+Possibility to define records or @code{struct}s in the declare section
+in a way that the record can be filled from one row in the database.
+
+This is a simpler way to handle an entire row at a time.
+
+@item array operations
+@cindex array operations
+Oracle has array operations that enhances speed. When implementing it in
+@code{ecpg} it is done for compatibility reasons only. For them to
+improve speed would require a lot more insight in the postgres internal
+mechanisms than I possess.
+
+@item indicator variables
+@cindex indicator variables
+@cindex @code{VARCHAR2}
+Oracle has indicator variables that tell if a value is @code{null} or if
+it is empty. This largely simplifies array operations and provides for a
+way to hack around some design flaws in the handling of @code{VARCHAR2}
+@footnote{like that an empty string isn't distinguishable from a
+@code{null} value}. I am not sure if this is an Oracle extension or part
+of the ANSI standard.
+
+@item typedefs
+@cindex typedef
+As well as complex types like records and arrays, typedefs would be
+a good thing to take care of.
+
+@item conversion of scripts
+@cindex conversion of scripts
+To set up a database you need a few scripts with table definitions and
+other configuration parameters. If you have these scripts for an old
+database you would like to just apply them to get a postgres database
+that works in the same way.
+
+The functionality could be accomplished with some conversion scripts.
+Speed will never be accomplished in this way. To do this you need a
+bigger insight in the database construction and the use of the database
+than could be realised in a script.
+
+@end table
+
+
+
+@node The preprocessor, A complete example, To do list, For the developer
@comment node-name, next, previous, up
@section The preprocessor
@end itemize
-@node A complete example, The library, The preprocessor, How it works
+@node A complete example, The library, The preprocessor, For the developer
@comment node-name, next, previous, up
@section A complete example
Here is a complete example describing the output of the preprocessor:
something that the preprocessor can do.)
-@node The library, , A complete example, How it works
+@node The library, , A complete example, For the developer
@comment node-name, next, previous, up
@section The library
The most important function in the library is the @code{ECPGdo}
To be completed: entries describing the other entries.
-@node Limitations, Porting from other DBMSs, How it works, Top
-@chapter Limitations
-@comment node-name, next, previous, up
-
-I separate the limitations in two different groups. Those that are of
-the kind that I have not gotten around to it yet and those that I will
-never bother to look at.
-
-@menu
-* What can be done with this concept::
-* What will never be included and why::
-@end menu
-
-@node What can be done with this concept, What will never be included and why, Limitations, Limitations
-@comment node-name, next, previous, up
-@section What can be done with this concept
-
-This is a list of things that I have plans to include in some future.
-
-@table @asis
-
-@item no restriction to strings only
-The PQ interface, and most of all the PQexec function, that is used by
-the ecpg relies on that the request is built up as a string. In some
-cases, like when the data contains the null character, this will be a
-serious problem.
-
-@item line numbering
-The preprocessor should generate output with directions to the compiler
-to generate debugging code including the file name and line numbers of
-the input to the preprocessor.
-
-@item error codes
-There should be different error numbers for the different errors instead
-of just -1 for them all.
-
-@item library functions
-to_date et al.
-
-@item records
-@cindex records
-Possibility to define records or @code{struct}s in the declare section
-in a way that the record can be filled from one row in the database.
-
-This is a simpler way to handle an entire row at a time.
-
-@item array operations
-@cindex array operations
-Oracle has array operations that enhances speed. When implementing it in
-@code{ecpg} it is done for compatibility reasons only. For them to
-improve speed would require a lot more insight in the postgres internal
-mechanisms than I possess.
-
-@item indicator variables
-@cindex indicator variables
-@cindex @code{VARCHAR2}
-Oracle has indicator variables that tell if a value is @code{null} or if
-it is empty. This largely simplifies array operations and provides for a
-way to hack around some design flaws in the handling of @code{VARCHAR2}
-@footnote{like that an empty string isn't distinguishable from a
-@code{null} value}. I am not sure if this is an Oracle extension or part
-of the ANSI standard.
-
-@item typedefs
-@cindex typedef
-As well as complex types like records and arrays, typedefs would be
-a good thing to take care of.
-
-@item conversion of scripts
-@cindex conversion of scripts
-To set up a database you need a few scripts with table definitions and
-other configuration parameters. If you have these scripts for an old
-database you would like to just apply them to get a postgres database
-that works in the same way.
-
-The functionality could be accomplished with some conversion scripts.
-Speed will never be accomplished in this way. To do this you need a
-bigger insight in the database construction and the use of the database
-than could be realised in a script.
-
-@end table
-
-
-@node What will never be included and why, , What can be done with this concept, Limitations
-@comment node-name, next, previous, up
-@section What will never be included and why
-
-@table @asis
-
-@item oracles single tasking possibility
-@cindex single tasking
-Oracle version 7.0 on AIX 3 uses the OS-supported locks on the shared
-memory segments and allows the application designer to link an
-application in a so called single tasking way. Instead of starting one
-client process per application process both the database part and the
-application part is run in the same process. In later versions of oracle
-this is no longer supported.
-
-This would require a total redesign of the postgres access model and
-that effort can not justify the performance gained.
-
-@end table
-
-
-@node Porting from other DBMSs, Installation, Limitations, Top
-@chapter Porting from other DBMSs
-@comment node-name, next, previous, up
-
-To be written by persons that knows the different DBMSs and that
-actually does port something...
-
-@node Installation, Index, Porting from other DBMSs, Top
-@comment node-name, next, previous, up
-@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
+@contents
+@bye
-@node Index, , Installation, Top
-@unnumbered Index
-@printindex cp
-@contents
projects / postgresql / commitdiff