*** empty log message ***
This commit is contained in:
Michael Meskes
parent
5ae9d85f77
commit
9abf246b91
|
|
@ -29,7 +29,7 @@ This describes an embedded <Acronym>SQL</Acronym> in <Acronym>C</Acronym>
|
|||
package for <ProductName>Postgres</ProductName>.
|
||||
|
||||
It is written by <ULink url="mailto:linus@epact.se">Linus Tolke</ULink>
|
||||
and <ULink url="mailto:meskes@debian.org">Michael Meskes</ULink>.
|
||||
and <ULink url="mailto:meskes@postgresql.org">Michael Meskes</ULink>.
|
||||
|
||||
<Note>
|
||||
<Para>
|
||||
|
|
@ -143,10 +143,8 @@ Debug logging is done on <replaceable class="parameter">stream</replaceable>.
|
|||
|
||||
<Para>
|
||||
The most important one (<Function>ECPGdo</Function>)
|
||||
that is called on all <Acronym>SQL</Acronym>
|
||||
statements except <Command>EXEC SQL COMMIT</Command>,
|
||||
<Command>EXEC SQL ROLLBACK</Command>,
|
||||
<Command>EXEC SQL CONNECT</Command> logs both its expanded string,
|
||||
that is called on almost all <Acronym>SQL</Acronym>
|
||||
statements logs both its expanded string,
|
||||
i.e. the string
|
||||
with all the input variables inserted, and the result from the
|
||||
<ProductName>Postgres</ProductName> server.
|
||||
|
|
@ -177,12 +175,37 @@ exec sql include sqlca;
|
|||
in the include section of your file. This will define a struct and a
|
||||
variable with the name <Parameter>sqlca</Parameter> as following:
|
||||
<ProgramListing>
|
||||
struct sqlca {
|
||||
int sqlcode;
|
||||
struct {
|
||||
int sqlerrml;
|
||||
char sqlerrmc[1000];
|
||||
} sqlerrm;
|
||||
struct sqlca
|
||||
{
|
||||
char sqlcaid[8];
|
||||
long sqlabc;
|
||||
long sqlcode;
|
||||
struct
|
||||
{
|
||||
int sqlerrml;
|
||||
char sqlerrmc[70];
|
||||
} sqlerrm;
|
||||
char sqlerrp[8];
|
||||
long sqlerrd[6];
|
||||
/* 0: empty */
|
||||
/* 1: empty */
|
||||
/* 2: number of rows processed in an INSERT, UPDATE */
|
||||
/* or DELETE statement */
|
||||
/* 3: empty */
|
||||
/* 4: empty */
|
||||
/* 5: empty */
|
||||
char sqlwarn[8];
|
||||
/* 0: set to 'W' if at least one other is 'W' */
|
||||
/* 1: if 'W' at least one character string */
|
||||
/* value was truncated when it was */
|
||||
/* stored into a host variable. */
|
||||
/* 2: empty */
|
||||
/* 3: empty */
|
||||
/* 4: empty */
|
||||
/* 5: empty */
|
||||
/* 6: empty */
|
||||
/* 7: empty */
|
||||
char sqlext[8];
|
||||
} sqlca;
|
||||
</ProgramListing>
|
||||
</Para>
|
||||
|
|
@ -199,9 +222,8 @@ the table did not contain the requested row.
|
|||
|
||||
<Para>
|
||||
sqlca.sqlerrm.sqlerrmc will contain a string that describes the error.
|
||||
The string ends with <Quote>line 23.</Quote> where the line is the line number
|
||||
in the source file (actually the file generated by the preprocessor but
|
||||
I hope I can fix this to be the line number in the input file.)
|
||||
The string ends with the line number
|
||||
in the source file.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
|
|
@ -209,7 +231,17 @@ List of errors that can occur:
|
|||
|
||||
<VariableList>
|
||||
<VarListEntry>
|
||||
<Term>-1, Unsupported type %s on line %d.</Term>
|
||||
<Term>-12, Out of memory in line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
Does not normally occur. This is a sign that your virtual memory is
|
||||
exhausted.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-200, Unsupported type %s on line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
Does not normally occur. This is a sign that the preprocessor has
|
||||
|
|
@ -220,66 +252,42 @@ are running incompatible versions of the preprocessor and the library.
|
|||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Too many arguments line %d.</Term>
|
||||
<Term>-201, Too many arguments line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
The preprocessor has goofed up and generated some incorrect code.
|
||||
This means that <ProductName>Postgres</ProductName> has returned more
|
||||
arguments than we have
|
||||
matching variables. Perhaps you have forgotten a couple of the host
|
||||
variables in the <Command>INTO :var1,:var2</Command>-list.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Too few arguments line %d.</Term>
|
||||
<Term>-202, Too few arguments line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
The preprocessor has goofed up and generated some incorrect code.
|
||||
This means that <ProductName>Postgres</ProductName> has returned fewer
|
||||
arguments than we have
|
||||
host variables. Perhaps you have too many host variables in the
|
||||
<Command>INTO :var1,:var2</Command>-list.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-203, Too many matches line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
This means that the query has returned several lines but the
|
||||
variables specified are no arrays. The <Command>SELECT</Command> you made
|
||||
probably was not unique.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Error starting transaction line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
<ProductName>Postgres</ProductName> signalled to us that we cannot open
|
||||
the connection.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Postgres error: %s line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
Some <ProductName>Postgres</ProductName> error.
|
||||
The message contains the error message from the
|
||||
<ProductName>Postgres</ProductName> backend.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>1, Data not found line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
This is a "normal" error that tells you that what you are quering cannot
|
||||
be found or we have gone through the cursor.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, To many matches line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
This means that the query has returned several lines.
|
||||
The <Command>SELECT</Command> you made probably was not unique.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Not correctly formatted int type: %s line %d.</Term>
|
||||
<Term>-204, Not correctly formatted int type: %s line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
This means that the host variable is of an <Type>int</Type> type and the field
|
||||
|
|
@ -292,7 +300,7 @@ for this conversion.
|
|||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Not correctly formatted unsigned type: %s line %d.</Term>
|
||||
<Term>-205, Not correctly formatted unsigned type: %s line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
This means that the host variable is of an <Type>unsigned int</Type> type and
|
||||
|
|
@ -305,10 +313,10 @@ uses <Function>strtoul</Function> for this conversion.
|
|||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Not correctly formatted floating point type: %s line %d.</Term>
|
||||
<Term>-206, Not correctly formatted floating point type: %s line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
This means that the host variable is of an <Type>float</Type> type and
|
||||
This means that the host variable is of a <Type>float</Type> type and
|
||||
the field in the <ProductName>Postgres</ProductName> database is of another
|
||||
type and contains a
|
||||
value that cannot be interpreted as an <Type>float</Type>. The library
|
||||
|
|
@ -318,96 +326,93 @@ uses <Function>strtod</Function> for this conversion.
|
|||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Too few arguments line %d.</Term>
|
||||
<Term>-207, Unable to convert %s to bool on line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
This means that <ProductName>Postgres</ProductName> has returned more records
|
||||
than we have
|
||||
matching variables. Perhaps you have forgotten a couple of the host
|
||||
variables in the <Command>INTO :var1,:var2</Command>-list.
|
||||
This means that the host variable is of a <Type>bool</Type> type and
|
||||
the field in the <ProductName>Postgres</ProductName> database is neither 't'
|
||||
nor 'f'.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Too many arguments line %d.</Term>
|
||||
<Term>-208, Empty query line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
This means that <ProductName>Postgres</ProductName> has returned fewer records
|
||||
than we have
|
||||
host variables. Perhaps you have to many host variables in the
|
||||
<Command>INTO :var1,:var2</Command>-list.
|
||||
<ProductName>Postgres</ProductName> returned PGRES_EMPTY_QUERY, probably
|
||||
because the query indeed was empty.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Empty query line %d.</Term>
|
||||
<Term>-220, No such connection %s in line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
<ProductName>Postgres</ProductName> returned PGRES_EMPTY_QUERY.
|
||||
The program tries to access a connection that does not exist.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Error: %s line %d.</Term>
|
||||
<Term>-221, Not connected in line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
This means that <ProductName>Postgres</ProductName> returned on of the errors
|
||||
PGRES_NONFATAL_ERROR, PGRES_FATAL_ERROR or PGRES_BAD_RESPONSE. Which one
|
||||
and why is explained in the message.
|
||||
The program tries to access a connection that does exist but is not open.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Postgres error line %d.</Term>
|
||||
<Term>-230, Invalid statement name %s in line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
<ProductName>Postgres</ProductName> returns something that the library does
|
||||
not know how to
|
||||
handle. This is probably because the version of
|
||||
<ProductName>Postgres</ProductName> does not
|
||||
match the version of the <Application>ecpg</Application> library.
|
||||
The statement you are trying to use has not been prepared.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Error committing line %d.</Term>
|
||||
<Term>-400, Postgres error: %s line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
Error during <Command>COMMIT</Command>. <Command>EXEC SQL COMMIT</Command>
|
||||
is translated to an
|
||||
<Command>end</Command> operation in <ProductName>Postgres</ProductName>
|
||||
and that is the operation that could
|
||||
not be performed.
|
||||
Some <ProductName>Postgres</ProductName> error.
|
||||
The message contains the error message from the
|
||||
<ProductName>Postgres</ProductName> backend.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, Error rolling back line %d.</Term>
|
||||
<Term>-401, Error in transaction processing line %d. </Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
Error during <Command>ROLLBACK</Command>.
|
||||
<Command>EXEC SQL ROLLBACK</Command> is translated to
|
||||
an <Command>abort</Command> operation in <ProductName>Postgres</ProductName>
|
||||
and that is the operation that
|
||||
could not be performed.
|
||||
<ProductName>Postgres</ProductName> signalled to us that we cannot start,
|
||||
commit or rollback the transaction.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>-1, ECPGconnect: could not open database %s.</Term>
|
||||
<Term>-402, connect: could not open database %s.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
The connect to the database did not work.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>100, Data not found line %d.</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
This is a "normal" error that tells you that what you are quering cannot
|
||||
be found or we have gone through the cursor.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
</VariableList>
|
||||
</Para>
|
||||
</Sect2>
|
||||
|
|
@ -447,9 +452,41 @@ that effort can not justify the performance gained.
|
|||
<Title>Porting From Other <Acronym>RDBMS</Acronym> Packages</Title>
|
||||
|
||||
<Para>
|
||||
To be written by someone who knows the different
|
||||
<Acronym>RDBMS</Acronym> packages and who
|
||||
actually does port something...
|
||||
The design of <Application>ecpg</Application> follows SQL standard. So
|
||||
porting from a standard RDBMS should not be a problem. Unfortunately there
|
||||
is no such thing as a standard RDBMS. So <Application>ecpg</Application>
|
||||
also tries to understand syntax additions as long as they do not create
|
||||
conflicts with the standard.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
The following list shows all the known incompatibilities. If you find one
|
||||
not listed please notify <ULink url="mailto:meskes@postgresql.org">Michael
|
||||
Meskes</ULink>. Note, however, that we list only incompatibilities from
|
||||
a precompiler of another RDBMS to <Application>ecpg</Application> and not
|
||||
additional <Application>ecpg</Application> features that these RDBMS do not
|
||||
have.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
<VariableList>
|
||||
<VarListEntry>
|
||||
<Term>Syntax of FETCH command</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
The standard syntax of the FETCH command is:
|
||||
|
||||
<Para>
|
||||
FETCH [direction] [amount] IN|FROM <Replaceable>cursor name</Replaceable>.
|
||||
</Para>
|
||||
|
||||
<Application>ORACLE</Application>, however, does not use the keywords IN
|
||||
resp. FROM. This feature cannot be added since it would create parsing
|
||||
conflicts.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
</VariableList>
|
||||
</Para>
|
||||
</sect1>
|
||||
|
||||
|
|
@ -487,67 +524,31 @@ This version the preprocessor has some flaws:
|
|||
|
||||
<VariableList>
|
||||
<VarListEntry>
|
||||
<Term>no restriction to strings only</Term>
|
||||
<Term>Library functions</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
The PQ interface, and most of all the PQexec function, that is used by
|
||||
the <Application>ecpg</Application> 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.
|
||||
to_date et al. do not exists. But then <ProductName>Postgres</ProductName>
|
||||
has some good conversion routines itself. So you probably won't miss these.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>error codes</Term>
|
||||
<Term>Structures ans unions</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
There should be different error numbers for the different errors instead
|
||||
of just -1 for them all.
|
||||
Structures and unions have to be defined in the declare section.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>library functions</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
to_date et al.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>records</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
Records or structures have to be defined in the declare section.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>missing statements</Term>
|
||||
<Term>Missing statements</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
The following statements are not implemented thus far:
|
||||
<VariableList>
|
||||
<VarListEntry>
|
||||
<Term> exec sql type</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
</Para>
|
||||
</listitem>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term> exec sql prepare</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
</Para>
|
||||
</listitem>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term> exec sql allocate</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
|
|
@ -555,14 +556,7 @@ The following statements are not implemented thus far:
|
|||
</listitem>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term> exec sql free</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
</Para>
|
||||
</listitem>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term> exec sql whenever sqlwarning</Term>
|
||||
<Term> exec sql deallocate</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
</Para>
|
||||
|
|
@ -581,7 +575,7 @@ The following statements are not implemented thus far:
|
|||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>message ´no data found´</Term>
|
||||
<Term>message 'no data found'</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
The error message for "no data" in an exec sql insert select from statement
|
||||
|
|
@ -591,7 +585,7 @@ has to be 100.
|
|||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>sqlwanr[6]</Term>
|
||||
<Term>sqlwarn[6]</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
sqlwarn[6] should be 'W' if the PRECISION or SCALE value specified in a SET
|
||||
|
|
@ -599,25 +593,6 @@ DESCRIPTOR statement will be ignored.
|
|||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term>conversion of scripts</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
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
|
||||
<ProductName>Postgres</ProductName> database that works in the same way.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
To set up a database you need a few scripts with table definitions and
|
||||
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.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
</VariableList>
|
||||
</Para>
|
||||
</sect2>
|
||||
|
|
@ -626,19 +601,20 @@ than could be realised in a script.
|
|||
<Title>The Preprocessor</Title>
|
||||
|
||||
<Para>
|
||||
First four lines are written to the output. Two comments and two include
|
||||
lines necessary for the interface to the library.
|
||||
The first four lines written to the output are constant additions by ecpg.
|
||||
These are two comments and two include lines necessary for the interface to the
|
||||
library.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
Then the preprocessor works in one pass only reading the input file and
|
||||
Then the preprocessor works in one pass only, reading the input file and
|
||||
writing to the output as it goes along. Normally it just echoes
|
||||
everything to the output without looking at it further.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
When it comes to an <Command>EXEC SQL</Command> statements it interviens and
|
||||
changes them depending on what iit is.
|
||||
When it comes to an <Command>EXEC SQL</Command> statements it intervenes and
|
||||
changes them depending on what it is.
|
||||
The <Command>EXEC SQL</Command> statement can be one of these:
|
||||
|
||||
<VariableList>
|
||||
|
|
@ -659,6 +635,12 @@ declare within this section is also entered in a list of variables
|
|||
indexed on their name together with the corresponding type.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
In particular the definition of a structure or union also has to be listed
|
||||
inside a declare section. Otherwise <Application>ecpg</Application> cannot
|
||||
handle these types since it simply does not know the definition.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
The declaration is echoed to the file to make the variable a normal
|
||||
C-variable also.
|
||||
|
|
@ -686,11 +668,17 @@ An include statement looks like:
|
|||
<ProgramListing>
|
||||
exec sql include filename;
|
||||
</ProgramListing>
|
||||
It is converted into
|
||||
Not that this is NOT the same as
|
||||
<ProgramListing>
|
||||
#include <filename.h>
|
||||
</ProgramListing>
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
Instead the file specified is parsed by <Application>ecpg</Application>
|
||||
itself. So the contents of the specified file is included in the resulting C
|
||||
code. This way you are able to specify EXEC SQL commands in an include file.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
|
|
@ -700,16 +688,102 @@ It is converted into
|
|||
<Para>
|
||||
A connect statement looks like:
|
||||
<ProgramListing>
|
||||
exec sql connect '<Replaceable>database</Replaceable>';
|
||||
</ProgramListing>
|
||||
That statement is converted into
|
||||
<ProgramListing>
|
||||
ECPGconnect("<Replaceable>database</Replaceable>");
|
||||
exec sql connect to <Replaceable>connection target</Replaceable>;
|
||||
</ProgramListing>
|
||||
It creates a connection to the specified database.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
The <Replaceable>connection target</Replaceable> can be specified in the
|
||||
following ways:
|
||||
<VariableList>
|
||||
<VarListEntry>
|
||||
<Term>dbname[@server][:port][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>tcp:postgresql://server[:port][/dbname][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>unix:postgresql://server[:port][/dbname][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term><Replaceable>character variable</Replaceable>[as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term><Replaceable>character string</Replaceable>[as <Replaceable>connection name</Replaceable>][<Replaceable>user</Replaceable>]</Term>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>default</Term>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>user</Term>
|
||||
</VarListEntry>
|
||||
</VariableList>
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
There are also different ways to specify the user name:
|
||||
<VariableList>
|
||||
<VarListEntry>
|
||||
<Term><Replaceable>userid</Replaceable></Term>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term><Replaceable>userid</Replaceable>/<Replaceable>password</Replaceable></Term>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term><Replaceable>userid</Replaceable> identified by <Replaceable>password</Replaceable></Term>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term><Replaceable>userid</Replaceable> using <Replaceable>password</Replaceable></Term>
|
||||
</VarListEntry>
|
||||
</VariableList>
|
||||
</Para>
|
||||
|
||||
<Para> Finally the userid and the password. Each may be a constant text, a
|
||||
character variable or a chararcter string.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
<VarListEntry>
|
||||
<Term>Disconnect statements</Term>
|
||||
<ListItem>
|
||||
<Para>
|
||||
A disconnect statement looks loke:
|
||||
<ProgramListing>
|
||||
exec sql disconnect [<Replaceable>connection target</Replaceable>];
|
||||
</ProgramListing>
|
||||
It closes the connection to the specified database.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
The <Replaceable>connection target</Replaceable> can be specified in the
|
||||
following ways:
|
||||
<VariableList>
|
||||
<VarListEntry>
|
||||
<Term><Replaceable>connection name</Replaceable></Term>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term>default</Term>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term>current</Term>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term>all</Term>
|
||||
</VarListEntry>
|
||||
</VariableList>
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
WARNING: FROM HERE ON THE TEXT IS OUTDATED!
|
||||
<VarListEntry>
|
||||
<Term>Open cursor statement</Term>
|
||||
<ListItem>
|
||||
|
|
@ -755,6 +829,7 @@ ECPGrollback(__LINE__);
|
|||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
||||
STARTING HERE IT IS OKAY AGAIN!
|
||||
<VarListEntry>
|
||||
<Term>Other statements</Term>
|
||||
<ListItem>
|
||||
|
|
@ -767,32 +842,30 @@ as an <Acronym>SQL</Acronym> statement and parsed for variable substitution.
|
|||
|
||||
<Para>
|
||||
Variable substitution occur when a symbol starts with a colon
|
||||
(<Command>:</Command>).
|
||||
Then a variable with that name is found among the variables
|
||||
that were previously declared within a declare section and depending on
|
||||
whether or not the <Acronym>SQL</Acronym> statements knows it to be
|
||||
a variable for input or
|
||||
output the pointers to the variables are written to the output to allow
|
||||
for access by the function.
|
||||
(<Command>:</Command>). Then a variable with that name is looked for among
|
||||
the variables that were previously declared within a declare section and
|
||||
depending on the variable being for input or output the pointers to the
|
||||
variables are written to the output to allow for access by the function.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
For every variable that is part of the <Acronym>SQL</Acronym> request
|
||||
the function gets another five arguments:
|
||||
the function gets another ten arguments:
|
||||
|
||||
<SimpleList>
|
||||
<Member>The type as a special symbol</Member>
|
||||
<Member>A pointer to the value</Member>
|
||||
<Member>The size of the variable if it is a varchar</Member>
|
||||
<Member>Number of elements in the array (for array fetches)</Member>
|
||||
<Member>The type as a special symbol.</Member>
|
||||
<Member>A pointer to the value or a pointer to the pointer.</Member>
|
||||
<Member>The size of the variable if it is a char or varchar.</Member>
|
||||
<Member>Number of elements in the array (for array fetches).</Member>
|
||||
<Member>The offset to the next element in the array (for array fetches)</Member>
|
||||
<Member>The type of the indicator variable as a special symbol.</Member>
|
||||
<Member>A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.</Member>
|
||||
<Member>0.</Member>
|
||||
<Member>Number of elements in the indicator array (for array fetches).</Member>
|
||||
<Member>The offset to the next element in the indicator array (for array fetches)</Member>
|
||||
</SimpleList>
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
Since the array fetches are not implemented yet the two last arguments
|
||||
are not really important. They could perhaps have been left out.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
</VariableList>
|
||||
|
|
@ -803,32 +876,38 @@ are not really important. They could perhaps have been left out.
|
|||
<Title>A Complete Example</Title>
|
||||
|
||||
<Para>
|
||||
Here is a complete example describing the output of the preprocessor:
|
||||
Here is a complete example describing the output of the preprocessor of a
|
||||
file foo.pgc:
|
||||
<ProgramListing>
|
||||
exec sql begin declare section;
|
||||
int index;
|
||||
int result;
|
||||
exec sql end declare section;
|
||||
...
|
||||
exec sql select res into :result from mytable where index = :index;
|
||||
exec sql select res into :result from mytable where index = :index;
|
||||
</ProgramListing>
|
||||
is translated into:
|
||||
<ProgramListing>
|
||||
/* Processed by ecpg (2.6.0) */
|
||||
/* These two include files are added by the preprocessor */
|
||||
#include <ecpgtype.h>
|
||||
#include <ecpglib.h>
|
||||
#include <ecpgtype.h>;
|
||||
#include <ecpglib.h>;
|
||||
|
||||
/* exec sql begin declare section */
|
||||
|
||||
#line 1 "foo.pgc"
|
||||
|
||||
int index;
|
||||
int result;
|
||||
/* exec sql end declare section */
|
||||
|
||||
...
|
||||
ECPGdo(__LINE__, "select res from mytable where index = ;;",
|
||||
ECPGt_int,&index,0,0,sizeof(int),
|
||||
ECPGt_EOIT,
|
||||
ECPGt_int,&result,0,0,sizeof(int),
|
||||
ECPGt_EORT );
|
||||
ECPGdo(__LINE__, NULL, "select res from mytable where index = ? ",
|
||||
ECPGt_int,&(index),1L,1L,sizeof(int),
|
||||
ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
|
||||
ECPGt_int,&(result),1L,1L,sizeof(int),
|
||||
ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
|
||||
#line 147 "foo.pgc"
|
||||
|
||||
</ProgramListing>
|
||||
(the indentation in this manual is added for readability and not
|
||||
something that the preprocessor can do.)
|
||||
|
|
@ -840,9 +919,9 @@ something that the preprocessor can do.)
|
|||
|
||||
<Para>
|
||||
The most important function in the library is the <Function>ECPGdo</Function>
|
||||
function. It takes a variable amount of arguments. Hopefully we wont run
|
||||
function. It takes a variable amount of arguments. Hopefully we will not run
|
||||
into machines with limits on the amount of variables that can be
|
||||
accepted by a varchar function. This could easily add up to 50 or so
|
||||
accepted by a vararg function. This could easily add up to 50 or so
|
||||
arguments.
|
||||
</Para>
|
||||
|
||||
|
|
@ -877,7 +956,7 @@ should go the string contains <Quote>;</Quote>.
|
|||
<ListItem>
|
||||
<Para>
|
||||
As described in the section about the preprocessor every input variable
|
||||
gets five arguments.
|
||||
gets ten arguments.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
|
@ -896,7 +975,7 @@ An enum telling that there are no more input variables.
|
|||
<ListItem>
|
||||
<Para>
|
||||
As described in the section about the preprocessor every input variable
|
||||
gets five arguments. These variables are filled by the function.
|
||||
gets ten arguments. These variables are filled by the function.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
|
|
@ -913,10 +992,11 @@ An enum telling that there are no more variables.
|
|||
</Para>
|
||||
|
||||
<Para>
|
||||
All the <Acronym>SQL</Acronym> statements are performed in one transaction
|
||||
unless you issue
|
||||
a commit transaction. This works so that the first transaction or the
|
||||
first after a commit or rollback always begins a transaction.
|
||||
All the <Acronym>SQL</Acronym> statements are performed in one transaction
|
||||
unless you issue a commit transaction. To get this auto-transaction going
|
||||
the first statement or the first after statement after a commit or rollback
|
||||
always begins a transaction. To disable this feature per default use the
|
||||
'-t' option on the commandline
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
|
|
|
|||
Loading…
Reference in New Issue