opensourcemirror
/
postgresql
mirror of git://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Updated ECPG From: Michael Meskes <meskes@topsystem.de>

This commit is contained in:
Marc G. Fournier 1998-02-10 16:37:01 +00:00
parent 0386a50f31
commit a8313f9671
3 changed files with 179 additions and 191 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/interfaces/ecpg/Makefile
View File

@ -1,4 +1,4 @@
SUBDIRS = src/include src/lib src/preproc
SUBDIRS = include lib preproc
all install uninstall clean::
all install uninstall clean:
for i in $(SUBDIRS); do ( cd $$i; make $@ ); done

7
src/interfaces/ecpg/TODO
View File

@ -4,7 +4,7 @@ The variables should be static.
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.
filenames so they won't have to be given all the time. (Done: MM 2/5/98)
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
@ -46,3 +46,8 @@ 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.
Now comes my list (MM):
libecpg should be made a shared library.
Makefiles have to able to correctly install and clean.

359
src/interfaces/ecpg/doc/ecpg.texinfo
View File

@ -1,6 +1,6 @@
\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
@ -51,11 +51,11 @@ buglist.
* 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 ---
@ -65,16 +65,12 @@ How to use it
* 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
@ -120,7 +116,7 @@ statement the SQL statement is performed against the database and you
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
@ -143,23 +139,6 @@ 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.
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
@ -289,9 +268,9 @@ host variables. Perhaps you have to many host variables in the
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
@ -313,24 +292,175 @@ The connect to the database did not work.
@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
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.
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 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
@ -454,7 +584,7 @@ are not really important. They could perhaps have been left out.
@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:
@ -488,7 +618,7 @@ is translated into:
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}
@ -524,156 +654,9 @@ first after a commit or rollback always begins a transaction.
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
@node Index, , Installation, Top
@unnumbered Index
@printindex cp
@contents
@bye