rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

*** empty log message ***

This commit is contained in:
Michael Meskes 1999-03-24 14:54:10 +00:00
parent 5ae9d85f77
commit 9abf246b91
1 changed files with 298 additions and 218 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

516
doc/src/sgml/ecpg.sgml
View File

@ -29,7 +29,7 @@ This describes an embedded <Acronym>SQL</Acronym> in <Acronym>C</Acronym>
package for <ProductName>Postgres</ProductName>. package for <ProductName>Postgres</ProductName>.
It is written by <ULink url="mailto:linus@epact.se">Linus Tolke</ULink> 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> <Note>
<Para> <Para>
@ -143,10 +143,8 @@ Debug logging is done on <replaceable class="parameter">stream</replaceable>.
<Para> <Para>
The most important one (<Function>ECPGdo</Function>) The most important one (<Function>ECPGdo</Function>)
that is called on all <Acronym>SQL</Acronym> that is called on almost all <Acronym>SQL</Acronym>
statements except <Command>EXEC SQL COMMIT</Command>, statements logs both its expanded string,
<Command>EXEC SQL ROLLBACK</Command>,
<Command>EXEC SQL CONNECT</Command> logs both its expanded string,
i.e. the string i.e. the string
with all the input variables inserted, and the result from the with all the input variables inserted, and the result from the
<ProductName>Postgres</ProductName> server. <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 in the include section of your file. This will define a struct and a
variable with the name <Parameter>sqlca</Parameter> as following: variable with the name <Parameter>sqlca</Parameter> as following:
<ProgramListing> <ProgramListing>
struct sqlca { struct sqlca
int sqlcode; {
struct { char sqlcaid[8];
int sqlerrml; long sqlabc;
char sqlerrmc[1000]; long sqlcode;
} sqlerrm; 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; } sqlca;
</ProgramListing> </ProgramListing>
</Para> </Para>
@ -199,9 +222,8 @@ the table did not contain the requested row.
<Para> <Para>
sqlca.sqlerrm.sqlerrmc will contain a string that describes the error. 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 The string ends with the line number
in the source file (actually the file generated by the preprocessor but in the source file.
I hope I can fix this to be the line number in the input file.)
</Para> </Para>
<Para> <Para>
@ -209,7 +231,17 @@ List of errors that can occur:
<VariableList> <VariableList>
<VarListEntry> <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> <ListItem>
<Para> <Para>
Does not normally occur. This is a sign that the preprocessor has 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>
<VarListEntry> <VarListEntry>
<Term>-1, Too many arguments line %d.</Term> <Term>-201, Too many arguments line %d.</Term>
<ListItem> <ListItem>
<Para> <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> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>-1, Too few arguments line %d.</Term> <Term>-202, Too few arguments line %d.</Term>
<ListItem> <ListItem>
<Para> <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> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>-1, Error starting transaction line %d.</Term> <Term>-204, Not correctly formatted int type: %s 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>
<ListItem> <ListItem>
<Para> <Para>
This means that the host variable is of an <Type>int</Type> type and the field 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>
<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> <ListItem>
<Para> <Para>
This means that the host variable is of an <Type>unsigned int</Type> type and 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>
<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> <ListItem>
<Para> <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 the field in the <ProductName>Postgres</ProductName> database is of another
type and contains a type and contains a
value that cannot be interpreted as an <Type>float</Type>. The library 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>
<VarListEntry> <VarListEntry>
<Term>-1, Too few arguments line %d.</Term> <Term>-207, Unable to convert %s to bool on line %d.</Term>
<ListItem> <ListItem>
<Para> <Para>
This means that <ProductName>Postgres</ProductName> has returned more records This means that the host variable is of a <Type>bool</Type> type and
than we have the field in the <ProductName>Postgres</ProductName> database is neither 't'
matching variables. Perhaps you have forgotten a couple of the host nor 'f'.
variables in the <Command>INTO :var1,:var2</Command>-list.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>-1, Too many arguments line %d.</Term> <Term>-208, Empty query line %d.</Term>
<ListItem> <ListItem>
<Para> <Para>
This means that <ProductName>Postgres</ProductName> has returned fewer records <ProductName>Postgres</ProductName> returned PGRES_EMPTY_QUERY, probably
than we have because the query indeed was empty.
host variables. Perhaps you have to many host variables in the
<Command>INTO :var1,:var2</Command>-list.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>-1, Empty query line %d.</Term> <Term>-220, No such connection %s in line %d.</Term>
<ListItem> <ListItem>
<Para> <Para>
<ProductName>Postgres</ProductName> returned PGRES_EMPTY_QUERY. The program tries to access a connection that does not exist.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>-1, Error: %s line %d.</Term> <Term>-221, Not connected in line %d.</Term>
<ListItem> <ListItem>
<Para> <Para>
This means that <ProductName>Postgres</ProductName> returned on of the errors The program tries to access a connection that does exist but is not open.
PGRES_NONFATAL_ERROR, PGRES_FATAL_ERROR or PGRES_BAD_RESPONSE. Which one
and why is explained in the message.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>-1, Postgres error line %d.</Term> <Term>-230, Invalid statement name %s in line %d.</Term>
<ListItem> <ListItem>
<Para> <Para>
<ProductName>Postgres</ProductName> returns something that the library does The statement you are trying to use has not been prepared.
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.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>-1, Error committing line %d.</Term> <Term>-400, Postgres error: %s line %d.</Term>
<ListItem> <ListItem>
<Para> <Para>
Error during <Command>COMMIT</Command>. <Command>EXEC SQL COMMIT</Command> Some <ProductName>Postgres</ProductName> error.
is translated to an The message contains the error message from the
<Command>end</Command> operation in <ProductName>Postgres</ProductName> <ProductName>Postgres</ProductName> backend.
and that is the operation that could
not be performed.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>-1, Error rolling back line %d.</Term> <Term>-401, Error in transaction processing line %d. </Term>
<ListItem> <ListItem>
<Para> <Para>
Error during <Command>ROLLBACK</Command>. <ProductName>Postgres</ProductName> signalled to us that we cannot start,
<Command>EXEC SQL ROLLBACK</Command> is translated to commit or rollback the transaction.
an <Command>abort</Command> operation in <ProductName>Postgres</ProductName>
and that is the operation that
could not be performed.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>-1, ECPGconnect: could not open database %s.</Term> <Term>-402, connect: could not open database %s.</Term>
<ListItem> <ListItem>
<Para> <Para>
The connect to the database did not work. The connect to the database did not work.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </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> </VariableList>
</Para> </Para>
</Sect2> </Sect2>
@ -447,9 +452,41 @@ that effort can not justify the performance gained.
<Title>Porting From Other <Acronym>RDBMS</Acronym> Packages</Title> <Title>Porting From Other <Acronym>RDBMS</Acronym> Packages</Title>
<Para> <Para>
To be written by someone who knows the different The design of <Application>ecpg</Application> follows SQL standard. So
<Acronym>RDBMS</Acronym> packages and who porting from a standard RDBMS should not be a problem. Unfortunately there
actually does port something... 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> </Para>
</sect1> </sect1>
@ -487,67 +524,31 @@ This version the preprocessor has some flaws:
<VariableList> <VariableList>
<VarListEntry> <VarListEntry>
<Term>no restriction to strings only</Term> <Term>Library functions</Term>
<ListItem> <ListItem>
<Para> <Para>
The PQ interface, and most of all the PQexec function, that is used by to_date et al. do not exists. But then <ProductName>Postgres</ProductName>
the <Application>ecpg</Application> relies on that the request is built has some good conversion routines itself. So you probably won't miss these.
up as a string. In some
cases, like when the data contains the null character, this will be a
serious problem.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>error codes</Term> <Term>Structures ans unions</Term>
<ListItem> <ListItem>
<Para> <Para>
There should be different error numbers for the different errors instead Structures and unions have to be defined in the declare section.
of just -1 for them all.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>library functions</Term> <Term>Missing statements</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>
<ListItem> <ListItem>
<Para> <Para>
The following statements are not implemented thus far: The following statements are not implemented thus far:
<VariableList> <VariableList>
<VarListEntry> <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> <Term> exec sql allocate</Term>
<ListItem> <ListItem>
<Para> <Para>
@ -555,14 +556,7 @@ The following statements are not implemented thus far:
</listitem> </listitem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term> exec sql free</Term> <Term> exec sql deallocate</Term>
<ListItem>
<Para>
</Para>
</listitem>
</VarListEntry>
<VarListEntry>
<Term> exec sql whenever sqlwarning</Term>
<ListItem> <ListItem>
<Para> <Para>
</Para> </Para>
@ -581,7 +575,7 @@ The following statements are not implemented thus far:
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>message ´no data found´</Term> <Term>message 'no data found'</Term>
<ListItem> <ListItem>
<Para> <Para>
The error message for "no data" in an exec sql insert select from statement The error message for "no data" in an exec sql insert select from statement
@ -591,7 +585,7 @@ has to be 100.
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term>sqlwanr[6]</Term> <Term>sqlwarn[6]</Term>
<ListItem> <ListItem>
<Para> <Para>
sqlwarn[6] should be 'W' if the PRECISION or SCALE value specified in a SET 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> </Para>
</ListItem> </ListItem>
</VarListEntry> </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> </VariableList>
</Para> </Para>
</sect2> </sect2>
@ -626,19 +601,20 @@ than could be realised in a script.
<Title>The Preprocessor</Title> <Title>The Preprocessor</Title>
<Para> <Para>
First four lines are written to the output. Two comments and two include The first four lines written to the output are constant additions by ecpg.
lines necessary for the interface to the library. These are two comments and two include lines necessary for the interface to the
library.
</Para> </Para>
<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 writing to the output as it goes along. Normally it just echoes
everything to the output without looking at it further. everything to the output without looking at it further.
</Para> </Para>
<Para> <Para>
When it comes to an <Command>EXEC SQL</Command> statements it interviens and When it comes to an <Command>EXEC SQL</Command> statements it intervenes and
changes them depending on what iit is. changes them depending on what it is.
The <Command>EXEC SQL</Command> statement can be one of these: The <Command>EXEC SQL</Command> statement can be one of these:
<VariableList> <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. indexed on their name together with the corresponding type.
</Para> </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> <Para>
The declaration is echoed to the file to make the variable a normal The declaration is echoed to the file to make the variable a normal
C-variable also. C-variable also.
@ -686,11 +668,17 @@ An include statement looks like:
<ProgramListing> <ProgramListing>
exec sql include filename; exec sql include filename;
</ProgramListing> </ProgramListing>
It is converted into Not that this is NOT the same as
<ProgramListing> <ProgramListing>
#include &lt;filename.h&gt; #include &lt;filename.h&gt;
</ProgramListing> </ProgramListing>
</Para> </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> </ListItem>
</VarListEntry> </VarListEntry>
@ -700,16 +688,102 @@ It is converted into
<Para> <Para>
A connect statement looks like: A connect statement looks like:
<ProgramListing> <ProgramListing>
exec sql connect '<Replaceable>database</Replaceable>'; exec sql connect to <Replaceable>connection target</Replaceable>;
</ProgramListing>
That statement is converted into
<ProgramListing>
ECPGconnect("<Replaceable>database</Replaceable>");
</ProgramListing> </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> </Para>
</ListItem> </ListItem>
</VarListEntry> </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> <VarListEntry>
<Term>Open cursor statement</Term> <Term>Open cursor statement</Term>
<ListItem> <ListItem>
@ -755,6 +829,7 @@ ECPGrollback(__LINE__);
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
STARTING HERE IT IS OKAY AGAIN!
<VarListEntry> <VarListEntry>
<Term>Other statements</Term> <Term>Other statements</Term>
<ListItem> <ListItem>
@ -767,32 +842,30 @@ as an <Acronym>SQL</Acronym> statement and parsed for variable substitution.
<Para> <Para>
Variable substitution occur when a symbol starts with a colon Variable substitution occur when a symbol starts with a colon
(<Command>:</Command>). (<Command>:</Command>). Then a variable with that name is looked for among
Then a variable with that name is found among the variables the variables that were previously declared within a declare section and
that were previously declared within a declare section and depending on depending on the variable being for input or output the pointers to the
whether or not the <Acronym>SQL</Acronym> statements knows it to be variables are written to the output to allow for access by the function.
a variable for input or
output the pointers to the variables are written to the output to allow
for access by the function.
</Para> </Para>
<Para> <Para>
For every variable that is part of the <Acronym>SQL</Acronym> request 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> <SimpleList>
<Member>The type as a special symbol</Member> <Member>The type as a special symbol.</Member>
<Member>A pointer to the value</Member> <Member>A pointer to the value or a pointer to the pointer.</Member>
<Member>The size of the variable if it is a varchar</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>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 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> </SimpleList>
</Para> </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> </ListItem>
</VarListEntry> </VarListEntry>
</VariableList> </VariableList>
@ -803,32 +876,38 @@ are not really important. They could perhaps have been left out.
<Title>A Complete Example</Title> <Title>A Complete Example</Title>
<Para> <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> <ProgramListing>
exec sql begin declare section; exec sql begin declare section;
int index; int index;
int result; int result;
exec sql end declare section; 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> </ProgramListing>
is translated into: is translated into:
<ProgramListing> <ProgramListing>
/* Processed by ecpg (2.6.0) */
/* These two include files are added by the preprocessor */ /* These two include files are added by the preprocessor */
#include &lt;ecpgtype.h&gt; #include &lt;ecpgtype.h&gt;;
#include &lt;ecpglib.h&gt; #include &lt;ecpglib.h&gt;;
/* exec sql begin declare section */ /* exec sql begin declare section */
#line 1 "foo.pgc"
int index; int index;
int result; int result;
/* exec sql end declare section */ /* exec sql end declare section */
... ...
ECPGdo(__LINE__, "select res from mytable where index = ;;", ECPGdo(__LINE__, NULL, "select res from mytable where index = ? ",
ECPGt_int,&amp;index,0,0,sizeof(int), ECPGt_int,&amp;(index),1L,1L,sizeof(int),
ECPGt_EOIT, ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
ECPGt_int,&amp;result,0,0,sizeof(int), ECPGt_int,&amp;(result),1L,1L,sizeof(int),
ECPGt_EORT ); ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
#line 147 "foo.pgc"
</ProgramListing> </ProgramListing>
(the indentation in this manual is added for readability and not (the indentation in this manual is added for readability and not
something that the preprocessor can do.) something that the preprocessor can do.)
@ -840,9 +919,9 @@ something that the preprocessor can do.)
<Para> <Para>
The most important function in the library is the <Function>ECPGdo</Function> 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 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. arguments.
</Para> </Para>
@ -877,7 +956,7 @@ should go the string contains <Quote>;</Quote>.
<ListItem> <ListItem>
<Para> <Para>
As described in the section about the preprocessor every input variable As described in the section about the preprocessor every input variable
gets five arguments. gets ten arguments.
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
@ -896,7 +975,7 @@ An enum telling that there are no more input variables.
<ListItem> <ListItem>
<Para> <Para>
As described in the section about the preprocessor every input variable 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> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
@ -913,10 +992,11 @@ An enum telling that there are no more variables.
</Para> </Para>
<Para> <Para>
All the <Acronym>SQL</Acronym> statements are performed in one transaction All the <Acronym>SQL</Acronym> statements are performed in one transaction
unless you issue unless you issue a commit transaction. To get this auto-transaction going
a commit transaction. This works so that the first transaction or the the first statement or the first after statement after a commit or rollback
first after a commit or rollback always begins a transaction. always begins a transaction. To disable this feature per default use the
'-t' option on the commandline
</Para> </Para>
<Para> <Para>