- ECPGdebug(int on, FILE
- *stream) turns on debug
- logging if called with the first argument non-zero. Debug
- logging is done on stream. Most
-
SQL statement log their arguments and results.
+ ECPGdebug(int on, FILE
+ *stream) turns on debug
+ logging if called with the first argument non-zero. Debug
+ logging is done on stream. Most
+
SQL statement log their arguments and results.
- The most important function , ECPGdo, logs
- all
SQL statements with both the expanded
- string, i.e. the string with all the input variables inserted,
- and the result from the
Postgres- server. This can be very useful when searching for errors in
+ The most important function , ECPGdo, logs
+
all
SQL statements with both the expanded
+ string, i.e. the string with all the input variables inserted,
+
and the result from the
Postgres+ server. This can be very useful when searching for errors in
- ECPGstatus()
- This method returns TRUE if we are connected to a database and FALSE if not.
+ ECPGstatus()
+ This method returns TRUE if we are connected to a database and FALSE if not.
/* 5: empty */
char sqlwarn[8];
/* 0: set to 'W' if at least one other is 'W' */
- /* 1: if 'W' at least one character string */
+ /* 1: if 'W' at least one character string */
/* value was truncated when it was */
/* stored into a host variable. */
/* 2: empty */
-12, Out of memory in line %d.
- Should not normally occur. This indicates your virtual memory is
- exhausted.
-
+ Should not normally occur. This indicates your virtual memory is
+ exhausted.
+
-200 (ECPG_UNSUPPORTED): Unsupported type %s on line %d.
- Should not normally occur. This indicates the preprocessor has
- generated something that the library does not know about.
- Perhaps you are running incompatible versions of the
- preprocessor and the library.
-
+ Should not normally occur. This indicates the preprocessor has
+ generated something that the library does not know about.
+ Perhaps you are running incompatible versions of the
+ preprocessor and the library.
+
-201 (ECPG_TOO_MANY_ARGUMENTS): Too many arguments line %d.
- This means that
Postgres has
- returned more arguments than we have matching variables.
- Perhaps you have forgotten a couple of the host variables in
- the INTO :var1,:var2-list.
-
+
This means that
Postgres has
+ returned more arguments than we have matching variables.
+ Perhaps you have forgotten a couple of the host variables in
+ the INTO :var1,:var2-list.
+
-202 (ECPG_TOO_FEW_ARGUMENTS): Too few arguments line %d.
- This means that
Postgres has
- returned fewer arguments than we have host variables. Perhaps
- you have too many host variables in the INTO
- :var1,:var2-list.
-
+
This means that
Postgres has
+ returned fewer arguments than we have host variables. Perhaps
+ you have too many host variables in the INTO
+ :var1,:var2-list.
+
-203 (ECPG_TOO_MANY_MATCHES): Too many matches line %d.
- This means the query has returned several rows but the
- variables specified are not arrays. The
- SELECT command was not unique.
-
+ This means the query has returned several rows but the
+ variables specified are not arrays. The
+ SELECT command was not unique.
+
-204 (ECPG_INT_FORMAT): Not correctly formatted int type: %s line %d.
- This means the host variable is of type int and
- the field in the
Postgres database
- is of another type and contains a value that cannot be
- interpreted as an int. The library uses
- strtol() for this conversion.
-
+ This means the host variable is of type int and
+
the field in the
Postgres database
+ is of another type and contains a value that cannot be
+ interpreted as an int. The library uses
+ strtol() for this conversion.
+
-205 (ECPG_UINT_FORMAT): Not correctly formatted unsigned type: %s line %d.
- This means the host variable is of type unsigned
- int and the field in the
-
Postgres database is of another type
- and contains a value that cannot be interpreted as an
- unsigned int. The library uses
- strtoul() for this conversion.
-
+ This means the host variable is of type unsigned
+ int and the field in the
+
Postgres database is of another type
+ and contains a value that cannot be interpreted as an
+ unsigned int. The library uses
+ strtoul() for this conversion.
+
-206 (ECPG_FLOAT_FORMAT): Not correctly formatted floating point type: %s line %d.
- This means the host variable is of type float and
- the field in the
Postgres database
- is of another type and contains a value that cannot be
- interpreted as a float. The library uses
- strtod() for this conversion.
-
+ This means the host variable is of type float and
+
the field in the
Postgres database
+ is of another type and contains a value that cannot be
+ interpreted as a float. The library uses
+ strtod() for this conversion.
+
-207 (ECPG_CONVERT_BOOL): Unable to convert %s to bool on line %d.
- This means the host variable is of type bool and
- the field in the
Postgres database
- is neither 't' nor 'f'.
-
+ This means the host variable is of type bool and
+
the field in the
Postgres database
+ is neither 't' nor 'f'.
+
-208 (ECPG_EMPTY): Empty query line %d.
-
Postgres returned
PGRES_EMPTY_QUERY, probably
- because the query indeed was empty.
-
+
Postgres returned
PGRES_EMPTY_QUERY, probably
+ because the query indeed was empty.
+
-209 (ECPG_MISSING_INDICATOR): NULL value without indicator in line %d.
-
Postgres returned
ECPG_MISSING_INDICATOR- because a NULL was returned and no NULL indicator variable was supplied.
-
+
Postgres returned
ECPG_MISSING_INDICATOR+ because a NULL was returned and no NULL indicator variable was supplied.
+
-210 (ECPG_NO_ARRAY): Variable is not an array in line %d.
-
Postgres returned
ECPG_NO_ARRAY- because an ordinary variable was used in a place that requires
- an array.
-
+
Postgres returned
ECPG_NO_ARRAY+ because an ordinary variable was used in a place that requires
+ an array.
+
-211 (ECPG_DATA_NOT_ARRAY): Data read from backend is not an array in line %d.
-
Postgres returned
ECPG_DATA_NOT_ARRAY- because the database returned an ordinary variable in a place
- that requires array value.
-
+
Postgres returned
ECPG_DATA_NOT_ARRAY+ because the database returned an ordinary variable in a place
+ that requires array value.
+
-220 (ECPG_NO_CONN): No such connection %s in line %d.
- The program tried to access a connection that does not exist.
-
+ The program tried to access a connection that does not exist.
+
-221 (ECPG_NOT_CONN): Not connected in line %d.
- The program tried to access a connection that does exist but is
- not open.
-
+ The program tried to access a connection that does exist but is
+ not open.
+
-230 (ECPG_INVALID_STMT): Invalid statement name %s in line %d.
- The statement you are trying to use has not been prepared.
-
+ The statement you are trying to use has not been prepared.
+
-240 (ECPG_UNKNOWN_DESCRIPTOR): Descriptor %s not found in line %d.
- The descriptor specified was not foundstatement you are trying to use has not been prepared.
-
+ The descriptor specified was not foundstatement you are trying to use has not been prepared.
+
-241 (ECPG_INVALID_DESCRIPTOR_INDEX): Descriptor index out of range in line %d.
- The descriptor index specified was out of range.
-
+ The descriptor index specified was out of range.
+
-242 (ECPG_UNKNOWN_DESCRIPTOR_ITEM): Descriptor %s not found in line %d.
- The descriptor specified was not foundstatement you are trying to use has not been prepared.
-
+ The descriptor specified was not foundstatement you are trying to use has not been prepared.
+
-243 (ECPG_VAR_NOT_NUMERIC): Variable is not a numeric type in line %d.
- The database returned a numeric value and the variable was not
- numeric.
-
+ The database returned a numeric value and the variable was not
+ numeric.
+
-244 (ECPG_VAR_NOT_CHAR): Variable is not a character type in line %d.
- The database returned a non-numeric value and the variable was
- numeric.
-
+ The database returned a non-numeric value and the variable was
+ numeric.
+
-400 (ECPG_PGSQL): Postgres error: %s line %d.
- The message contains the error message from the
-
+ The message contains the error message from the
+
-401 (ECPG_TRANS): Error in transaction processing line %d.
-
Postgres signaled that we cannot start,
- commit or rollback the transaction.
-
+
Postgres signaled that we cannot start,
+ commit or rollback the transaction.
+
-402 (ECPG_CONNECT): Could not connect to database %s in line %d.
- The connect to the database did not work.
-
+ The connect to the database did not work.
+
100 (ECPG_NOT_FOUND): Data not found line %d.
- This is a normal
error that tells you that what you are querying cannot
- be found or you are at the end of the cursor.
-
+ This is a normal
error that tells you that what you are querying cannot
+ be found or you are at the end of the cursor.
+
Limitations
- What will never be included and why it cannot be done.
-
-
-
+ What will never be included and why it cannot be done:
+
Oracle's single tasking
- Oracle version 7.0 on AIX 3 uses OS-supported locks in shared
- memory that allow an application designer to link an application
- in a single tasking
way. Instead of starting one client
- process per application process, both the database part and the
- application part run in the same process. In later versions of
- Oracle this is no longer supported.
+ Oracle version 7.0 on AIX 3 uses OS-supported locks in shared
+ memory that allow an application designer to link an application
+ in a single tasking
way. Instead of starting one client
+ process per application process, both the database part and the
+ application part 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 the
- performance gain does not justify the effort.
+ This would require a total redesign of the
+
Postgres access model and the
+ performance gain does not justify the effort.
Syntax of FETCH
- The standard syntax for FETCH is:
+ The standard syntax for FETCH is:
- FETCH [direction] [amount] IN|FROM cursor.
+ FETCH [direction] [amount] IN|FROM cursor.
-
ORACLE, however, does not use the keywords IN
- or FROM. This feature cannot be added since it would create parsing
- conflicts.
+
ORACLE, however, does not use the keywords IN
+ or FROM. This feature cannot be added since it would create parsing
+ conflicts.
Library functions
- to_date et al. does not exist. However,
-
Postgres has some good conversion
- routines so you probably won't miss them.
-
+ to_date et al. does not exist. However,
+
Postgres has some good conversion
+ routines so you probably won't miss them.
+
Structures and unions
- Structures and unions have to be defined in the
- declare section.
-
+ Structures and unions have to be defined in the
+ declare section.
+
Missing statements
- The following statements are not implemented thus far:
-
-
- exec sql allocate
-
-
-
-
-
- exec sql deallocate
-
-
-
-
-
- SQLSTATE
-
-
-
-
-
-
+ The following statements are not implemented thus far:
+
+
+
+ exec sql allocate
+
+
+
+
+ exec sql deallocate
+
+
+
+
+ SQLSTATE
+
+
+
+
message 'no data found'
- The error message for no data
in:
+ The error message for no data
in:
exec sql insert select from statement
-
- has to be 100.
-
+
+ has to be 100.
+
sqlwarn[6]
- sqlwarn[6] should be W if the PRECISION
- or SCALE value specified in a SET
- DESCRIPTOR statement was ignored.
-
+ sqlwarn[6] should be W if the PRECISION
+ or SCALE value specified in a SET
+ DESCRIPTOR statement was ignored.
+
Declare sections
- Declare sections begin with:
+ Declare sections begin with:
exec sql begin declare section;
-
- and end with:
+
+ and end with:
exec sql end declare section;
-
- In this section only variable declarations are allowed. Every
- variable declared within this section is stored in a list
- of variables indexed by name together with its corresponding
- type.
-
-
- In particular the definition of a structure or union also must
- be listed inside a declare section. Otherwise
-
ecpg cannot handle these types since
- it does not know the definition.
-
-
- The declaration is also echoed to the file to make it a normal
- C variable.
-
-
- The special types VARCHAR and VARCHAR2 are converted into a named struct
- for every variable. A declaration like:
+
+ In this section only variable declarations are allowed. Every
+ variable declared within this section is stored in a list
+ of variables indexed by name together with its corresponding
+ type.
+
+
+ In particular the definition of a structure or union also must
+ be listed inside a declare section. Otherwise
+
ecpg cannot handle these types since
+ it does not know the definition.
+
+
+ The declaration is also echoed to the file to make it a normal
+ C variable.
+
+
+ The special types VARCHAR and VARCHAR2 are converted into a named struct
+ for every variable. A declaration like:
VARCHAR var[180];
-
- is converted into:
+
+ is converted into:
struct varchar_var { int len; char arr[180]; } var;
-
-
+
+
Include statements
- An include statement looks like:
+ An include statement looks like:
exec sql include filename;
-
- Note that this is NOT the same as:
+
+ Note that this is NOT the same as:
#include <filename.h>
-
-
-
- Instead the file specified is parsed by
-
ecpg so the contents of the file are
- included in the resulting C code. This way you are able to
- specify EXEC SQL commands in an include file.
-
+
+
+
+ Instead the file specified is parsed by
+
ecpg so the contents of the file are
+ included in the resulting C code. This way you are able to
+ specify EXEC SQL commands in an include file.
+
Connect statement
- A connect statement looks like:
+ A connect statement looks like:
exec sql connect to connection target;
-
- It creates a connection to the specified database.
-
-
- The connection target can be specified in the
- following ways:
-
-
- dbname[@server][:port][as connection
- name][user user name]
-
-
-
- tcp:postgresql://server[:port][/dbname][as
- connection name][user user name]
-
-
-
- unix:postgresql://server[:port][/dbname][as
- connection name][user user name]
-
-
-
- character variable[as
- connection name][user user name]
-
-
-
- character string[as
- connection name][user]
-
-
-
- default
-
-
-
- user
-
-
-
-
- There are also different ways to specify the user name:
-
-
- userid
-
-
- userid/password
-
-
- userid identified by password
-
-
- userid using password
-
-
-
-
- Finally, the userid and password may be a constant text, a
- character variable, or a character string.
-
+
+ It creates a connection to the specified database.
+
+
+ The connection target can be specified in the
+ following ways:
+
+
+
+ dbname[@server][:port][as connection
+ name][user user name]
+
+
+
+
+
+ tcp:postgresql://server[:port][/dbname][as
+ connection name][user user name]
+
+
+
+
+
+ unix:postgresql://server[:port][/dbname][as
+ connection name][user user name]
+
+
+
+
+
+ character variable[as
+ connection name][user user name]
+
+
+
+
+
+ character string[as
+ connection name][user]
+
+
+
+
+
+ default
+
+
+
+
+
+ user
+
+
+
+
+
+ There are also different ways to specify the user name:
+
+
+
+
+ userid
+
+
+
+
+
+ userid/password
+
+
+
+
+
+ userid identified by password
+
+
+
+
+
+ userid using password
+
+
+
+
+
+ Finally, the userid and password may be a constant text, a
+ character variable, or a character string.
+
Disconnect statements
- A disconnect statement looks like:
+ A disconnect statement looks like:
exec sql disconnect [connection target];
-
- It closes the connection to the specified database.
-
-
- The connection target can be specified in the
- following ways:
-
-
- connection name
-
-
- default
-
-
- current
-
-
- all
-
-
-
+
+ It closes the connection to the specified database.
+
+
+ The connection target can be specified in the
+ following ways:
+
+
+
+
+ connection name
+
+
+
+
+
+ default
+
+
+
+
+
+ current
+
+
+
+
+
+ all
+
+
+
+
Open cursor statement
- An open cursor statement looks like:
+ An open cursor statement looks like:
exec sql open cursor;
-
- and is not copied to the output. Instead, the cursor's
- DECLARE command is used because it opens the cursor
- as well.
-
+
+ and is not copied to the output. Instead, the cursor's
+ DECLARE command is used because it opens the cursor
+ as well.
+
Commit statement
- A commit statement looks like:
+ A commit statement looks like:
exec sql commit;
-
-
+
+
Rollback statement
- A rollback statement looks like:
+ A rollback statement looks like:
exec sql rollback;
-
-
+
+
Other statements
- Other
SQL statements are used by
- starting with exec sql and ending with
- ;. Everything in between is treated as an
-
SQL statement and parsed for variable
- substitution.
-
-
- Variable substitution occurs when a symbol starts with a colon
- (:). The variable with that name is looked
- up among the variables that were previously declared within a
- declare section. Depending on whether the variable is
- being use for input or output, a pointer to the variable is
- output to allow access by the function.
-
-
- For every variable that is part of the
SQL- query, the function gets other arguments:
-
-
- The type as a special symbol.
- A pointer to the value or a pointer to the pointer.
- The size of the variable if it is a char or varchar.
- The number of elements in the array (for array fetches).
- The offset to the next element in the array (for array fetches).
- The type of the indicator variable as a special symbol.
- A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.
- 0.
- Number of elements in the indicator array (for array fetches).
- The offset to the next element in the indicator array
- (for array fetches).
-
-
+ Other
SQL statements are used by
+ starting with exec sql and ending with
+ ;. Everything in between is treated as an
+
SQL statement and parsed for variable
+ substitution.
+
+
+ Variable substitution occurs when a symbol starts with a colon
+ (:). The variable with that name is looked
+ up among the variables that were previously declared within a
+ declare section. Depending on whether the variable is
+ being use for input or output, a pointer to the variable is
+ output to allow access by the function.
+
+
+ For every variable that is part of the
SQL+ query, the function gets other arguments:
+
+
+
+ The type as a special symbol.
+
+
+
+
+ A pointer to the value or a pointer to the pointer.
+
+
+
+
+ The size of the variable if it is a char or varchar.
+
+
+
+
+ The number of elements in the array (for array fetches).
+
+
+
+
+ The offset to the next element in the array (for array fetches).
+
+
+
+
+ The type of the indicator variable as a special symbol.
+
+
+
+
+ A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.
+
+
+
+
+ 0.
+
+
+
+
+ Number of elements in the indicator array (for array fetches).
+
+
+
+
+ The offset to the next element in the indicator array (for
+ array fetches).
+
+
+
+
Here is a complete example describing the output of the preprocessor of a
file foo.pgc:
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;
-
+
is translated into:
/* Processed by ecpg (2.6.0) */
/* These two include files are added by the preprocessor */
#include <ecpgtype.h>;
/* exec sql end declare section */
...
ECPGdo(__LINE__, NULL, "select res from mytable where index = ? ",
- ECPGt_int,&(index),1L,1L,sizeof(int),
+ 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"
-
+
(The indentation in this manual is added for readability and not
something the preprocessor does.)
A line number
- This is a line number of the original line; used in error messages only.
-
+ This is a line number of the original line; used in error messages only.
+
A string
- This is the
SQL query that is to be issued.
- It is modified by the input variables, i.e. the variables that
- where not known at compile time but are to be entered in the
- query. Where the variables should go the string contains
- ?.
-
+
This is the
SQL query that is to be issued.
+ It is modified by the input variables, i.e. the variables that
+ where not known at compile time but are to be entered in the
+ query. Where the variables should go the string contains
+ ?.
+
Input variables
- As described in the section about the preprocessor, every input variable
- gets ten arguments.
-
+ As described in the section about the preprocessor, every input variable
+ gets ten arguments.
+
ECPGt_EOIT
- An enum telling that there are no more input variables.
-
+ An enum telling that there are no more input variables.
+
Output variables
- As described in the section about the preprocessor, every input variable
- gets ten arguments. These variables are filled by the function.
-
+ As described in the section about the preprocessor, every input variable
+ gets ten arguments. These variables are filled by the function.
+
ECPGt_EORT
- An enum telling that there are no more variables.
-
+ An enum telling that there are no more variables.
+
projects / postgresql.git / commitdiff