From 028c72525d4c74c035311c3bd68ebab05d45dc1b Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Wed, 31 Oct 2001 20:37:39 +0000 Subject: [PATCH] Reformat some non-sensical markup. --- doc/src/sgml/ecpg.sgml | 901 ++++++++++++++++++++++------------------- 1 file changed, 483 insertions(+), 418 deletions(-) diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index 8f4e599a5f..522e6ca321 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -1,5 +1,5 @@ @@ -120,27 +120,27 @@ $Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.26 2001/10/18 20:43:05 momjia - 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 - your SQL statements. + 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 + your SQL statements. - 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. @@ -180,7 +180,7 @@ struct sqlca /* 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 */ @@ -216,265 +216,265 @@ struct sqlca -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. - - Some Postgres error. - The message contains the error message from the - Postgres backend. - + + Some Postgres error. + The message contains the error message from the + Postgres backend. + -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. + @@ -486,30 +486,26 @@ struct sqlca 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. @@ -545,15 +541,15 @@ struct sqlca 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. @@ -580,77 +576,74 @@ struct sqlca 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. + @@ -680,269 +673,341 @@ exec sql insert select from statement 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 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. - + + 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 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: - + + 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. - + + 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] - - + + 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] - - + + + tcp:postgresql://server[:port][/dbname][as + connection name][user user name] + + - - unix: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 + + + + - - character variable[as - connection name][user user name] - - + + There are also different ways to specify the user name: - - character string[as - connection name][user] - - + + + + userid + + - - default - - + + + userid/password + + - - user - - - - + + + userid identified by password + + - - There are also different ways to specify the user name: - - - userid - - - - userid/password - - - - userid identified by password - - - - userid using password - - - - + + + userid using password + + + + - - Finally, the userid and password may be a constant text, a - character variable, or a character string. - + + 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. - + + It closes the connection to the specified database. + - - The connection target can be specified in the - following ways: - - - connection name - - - - default - - - - current - - - - all - - - - + + 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. - + + 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. - + + 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: + + 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). - - + + + + 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). + + + + @@ -956,16 +1021,16 @@ exec sql rollback; 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>; @@ -980,12 +1045,12 @@ exec sql select res into :result from mytable where index = :index; /* 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.) @@ -1009,60 +1074,60 @@ ECPGdo(__LINE__, NULL, "select res from mytable where index = ? ", 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. +