From 7d831b537953f652227fe44e78b99520d7904ee2 Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Thu, 27 May 1999 15:48:14 +0000 Subject: [PATCH] Significant updates from Vince Vielhaber. --- doc/src/sgml/libpq++.sgml | 723 +++++++++++++++++++++++--------------- 1 file changed, 430 insertions(+), 293 deletions(-) diff --git a/doc/src/sgml/libpq++.sgml b/doc/src/sgml/libpq++.sgml index a7cd9b288b..4fab4d969f 100644 --- a/doc/src/sgml/libpq++.sgml +++ b/doc/src/sgml/libpq++.sgml @@ -1,4 +1,4 @@ - + libpq C++ Binding @@ -20,7 +20,7 @@ queries to the Postgres backend server it is only intended for simple queries that do not return any data. A large object should be seen - as a file stream. In future it should behave much like the C++ file + as a file stream. In the future it should behave much like the C++ file streams cin, cout @@ -40,13 +40,10 @@ - Control and Initialization + Control and Initialization - - - - - Environment Variables + + Environment Variables The following environment variables can be used to set up default @@ -54,245 +51,257 @@ an application program: - Refer to the for a complete + Refer to the for a complete list of available connection options. - + The following environment variables can be used to select default connection parameter values, which will be used by PQconnectdb or PQsetdbLogin if no value is directly specified by the calling code. These are useful to avoid hard-coding database names into simple application programs. + + + libpq++ uses only environment variables or PQconnectdb + conninfo style strings. + + - - - - PGHOST sets the default server name. + + + + PGHOST sets the default server name. If a non-zero-length string is specified, TCP/IP communication is used. Without a host name, libpq will connect using a local Unix domain socket. - - - - - PGPORT sets the default port or local Unix domain socket - file extension for communicating with the Postgres + + + + + PGPORT sets the default port or local Unix domain socket + file extension for communicating with the Postgres backend. - - - - - PGDATABASE sets the default - Postgres database name. - - - - - PGUSER + + + + + PGDATABASE sets the default + Postgres database name. + + + + + PGUSER sets the username used to connect to the database and for authentication. - - - - - PGPASSWORD + + + + + PGPASSWORD sets the password used if the backend demands password authentication. - - - - - PGREALM sets the Kerberos realm to use with - Postgres, + + + + + PGREALM sets the Kerberos realm to use with + Postgres, if it is different from the local realm. If - PGREALM is set, Postgres + PGREALM is set, Postgres applications will attempt authentication with servers for this realm and use separate ticket files to avoid conflicts with local ticket files. This environment variable is only used if Kerberos authentication is selected by the backend. - - - - - PGOPTIONS sets additional runtime options for - the Postgres backend. - - - - - PGTTY sets the file or tty on which debugging + + + + + PGOPTIONS sets additional runtime options for + the Postgres backend. + + + + + PGTTY sets the file or tty on which debugging messages from the backend server are displayed. - - - - + + + + - + The following environment variables can be used to specify user-level default behavior for every Postgres session: - - - - PGDATESTYLE + + + + PGDATESTYLE sets the default style of date/time representation. - - - - - PGTZ + + + + + PGTZ sets the default time zone. - - - - + + + + - + The following environment variables can be used to specify default internal behavior for every Postgres session: - - - - PGGEQO - sets the default mode for the genetic optimizer. - - - - - PGRPLANS - sets the default mode to allow or disable right-sided plans in the optimizer. - - - - - PGCOSTHEAP - sets the default cost for heap searches for the optimizer. - - - - - PGCOSTINDEX - sets the default cost for indexed searches for the optimizer. - - - - - PGQUERY_LIMIT - sets the maximum number of rows returned by a query. - - - - - - - Refer to the SET SQL command - for information on correct values for these environment variables. - - - - - - Database Connection Functions - - - - - - Database Environment Class: <classname>PGenv</classname> - - - The database environment class provides C++ objects for manipulating the - above environment variables: - - PGenv - creates an environment for the running program. - - - PGenv() - PGenv(char* auth, char* host, char* port, char* option, char* tty) - - - The first form of this object's constructor sets up the defaults for - the program from the environment variables listed above. - The second allows the programmer to hardcode the values into the program. - The values of the second form relate directly to the environment variables - above. + PGGEQO + sets the default mode for the genetic optimizer. + + + + + PGRPLANS + sets the default mode to allow or disable right-sided plans in the optimizer. + + + + + PGCOSTHEAP + sets the default cost for heap searches for the optimizer. + + + + + PGCOSTINDEX + sets the default cost for indexed searches for the optimizer. + + + + + PGQUERY_LIMIT + sets the maximum number of rows returned by a query. - - - - Database Class: <classname>PGdatabase</classname> - The database class is a provides C++ objects that have a connection - to a backend server. To create such an object one first need + Refer to the SET SQL command + for information on correct values for these environment variables. + + + + + libpq++ Classes + + + Connection Class: <classname>PgConnection</classname> + + The connection class makes the actual connection to the database and is inherited + by all of the access classes. + + + + Database Class: <classname>PgDatabase</classname> + + The database class provides C++ objects that have a connection + to a backend server. To create such an object one first needs the apropriate environment for the backend to access. The following constructors deal with making a connection to a backend server from a C++ program. - - - - - PGdatabase - makes a new connection to a backend database server. - - PGdatabase(PGenv *env, char *dbName) - - After a PGdatabase has been created it should be checked to make sure - the connection to the database succeded before sending - queries to the object. This can easily be done by - retrieving the current status of the PGdatabase object with the - status method. - - - - - status - returns the status of the PGdatabase object. - - ConnStatus PGdatabase::status() - - - The following values are allowed: - - - CONNECTION_OK - - - CONNECTION_BAD - - - - - - - Query Execution Functions - + Database Connection Functions - PGdatabase::exec - submits a query to Postgres - and returns result status. In case of an error - PGdatabase::errormessage - can be used to get more information on the error. + PgConnection + makes a new connection to a backend database server. - void ExecStatusType PGdatabase::exec(char *query); + PgConnection::PgConnection(const char *conninfo) - - The following status results can be expected: + Although typically called from one of the access classes, a connection to + a backend server is possible by creating a PgConnection object. + + + + + ConnectionBad + returns whether or not the connection to the backend server succeeded or + failed. + + int PgConnection::ConnectionBad() + + Returns TRUE if the connection failed. + + + + + Status + returns the status of the connection to the backend server. + + ConnStatusType PgConnection::Status() + + Returns either CONNECTION_OK or CONNECTION_BAD depending on the state + of the connection. + + + + + PgDatabase + makes a new connection to a backend database server. + + PgDatabase(const char *conninfo) + + After a PgDatabase has been created it should be checked to make sure + the connection to the database succeded before sending + queries to the object. This can easily be done by + retrieving the current status of the PgDatabase object with the + Status or ConnectionBad methods. + + + + + DBName + Returns the name of the current database. + + const char *PgConnection::DBName() + + + + + + Notifies + Returns the next notification from a list of unhandled notification messages + received from the backend. + + PGnotify* PgConnection::Notifies() + + See PQnotifies() for details. + + + + + + + Query Execution Functions + + + + + Exec + Sends a query to the backend server. It's probably more desirable to + use one of the next two functions. + + ExecStatusType PgConnection::Exec(const char* query) + + Returns the result of the query. The following status results can be expected: @@ -322,133 +331,249 @@ - - - - If the result status is PGRES_TUPLES_OK, then the following routines can - be used to retrieve the tuples returned by the query. - - - PGdatabase::ntuples - returns the number of tuples (instances) in the query result. + ExecCommandOk + Sends a command query to the backend server. - int PGdatabase::ntuples() + int PgConnection::ExecCommandOk(const char *query) + Returns TRUE if the command query succeeds. - + - PGdatabase::nfields - returns the number of fields (attributes) in the query result. + ExecTuplesOk + Sends a command query to the backend server. - int PGdatabase::nfields() + int PgConnection::ExecTuplesOk(const char *query) + + Returns TRUE if the command query succeeds and there are tuples to be retrieved. + + + + + ErrorMessage + Returns the last error message text. + + const char *PgConnection::ErrorMessage() - PGdatabase::fieldname - returns the field (attribute) name associated with the given field index. - Field indices start at zero. + Tuples + Returns the number of tuples (instances) in the query result. - char* PGdatabase::fieldname(int field_index) - - - - - - PGdatabase::fieldnum - returns the field (attribute) index associated with the given field name. - - int PGdatabase::fieldnum(char* field_name) + int PgDatabase::Tuples() - PGdatabase::fieldtype - returns the field type of associated with the given field index or name. - The integer returned is an internal coding of the type. Field indices start - at zero. + Fields + Returns the number of fields (attributes) in each tuple of the query result. - Oid PGdatabase::fieldtype(int field_index) - Oid PGdatabase::fieldtype(char* field_name) + int PgDatabase::Fields() - PGdatabase::fieldsize - returns the size in bytes of the field associated with the given field - index or name. If the size returned is -1, the field is a variable length - field. Field indices start at zero. + FieldName + Returns the field (attribute) name associated with the given field index. + Field indices start at 0. - int2 PGdatabase::fieldsize(int field_index) - int2 PGdatabase::fieldsize(char* field_name) + const char *PgDatabase::FieldName(int field_num) - PGdatabase::getvalue - returns the field (attribute) value. For most queries, the values - returned by - PGdatabase::getvalue - is a null-terminated ASCII string representation - of the attribute value. If the query was a result of a - BINARY - cursor, then the values returned by - PGdatabase::getvalue - is the binary representation of the type in the internal format of the - backend server. It is the programmer's responsibility to cast and - convert the data to the correct C++ type. The value return by - PGdatabase::getvalue - points to storage that is part of the PGdatabase structure. - One must - explicitly copy the value into other storage if it is to be used past - the next query. + FieldNum + PQfnumber Returns the field (attribute) index associated with + the given field name. - char* PGdatabase::getvalue(int tup_num, int field_index) - char* PGdatabase::getvalue(int tup_num, char* field_name) + int PgDatabase::FieldNum(const char* field_name) + + -1 is returned if the given name does not match any field. + + + + + FieldType + Returns the field type associated with the given field index. The + integer returned is an internal coding of the type. Field indices + start at 0. + + Oid PgDatabase::FieldType(int field_num) - PGdatabase::getlength - returns the length of a field (attribute) in bytes. If the field - is a struct varlena, - the length returned here does - not - include the size field of the varlena, - i.e., it is 4 bytes less. + FieldType + Returns the field type associated with the given field name. The + integer returned is an internal coding of the type. Field indices + start at 0. - int PGdatabase::getlength(int tup_num, int field_index) - int PGdatabase::getlength(int tup_num, char* field_name) + Oid PgDatabase::FieldType(const char* field_name) - PGdatabase::printtuples - prints out all the tuples and, optionally, the attribute names to the - specified output stream. + FieldSize + Returns the size in bytes of the field associated with the given + field index. Field indices start at 0. - void PGdatabase::printtuples( - FILE* fout, /* output stream */ - int printAttName,/* print attribute names or not*/ - int terseOutput, /* delimiter bars or not?*/ - int width /* width of column, variable width if 0*/ - ); + short PgDatabase::FieldSize(int field_num) + + Returns the space allocated for this field in a database tuple given + the field number. In other words the size of the server's binary + representation of the data type. -1 is returned if the field is + variable size. + + + + + FieldSize + Returns the size in bytes of the field associated with the given + field index. Field indices start at 0. + + short PgDatabase::FieldSize(const char *field_name) + + Returns the space allocated for this field in a database tuple given + the field name. In other words the size of the server's binary + representation of the data type. -1 is returned if the field is + variable size. + + + + + GetValue + Returns a single field (attribute) value of one tuple of a PGresult. + Tuple and field indices start at 0. + + const char *PgDatabase::GetValue(int tup_num, int field_num) + + For most queries, the value returned by GetValue is a null-terminated + ASCII string representation of the attribute value. But if BinaryTuples() + is TRUE, the value returned by GetValue is the binary representation + of the type in the internal format of the backend server (but not including + the size word, if the field is variable-length). It is then the programmer's + responsibility to cast and convert the data to the correct C type. The + pointer returned by GetValue points to storage that is part of the + PGresult structure. One should not modify it, and one must explicitly + copy the value into other storage if it is to be used past the lifetime + of the PGresult structure itself. BinaryTuples() is not yet implemented. + + + + + GetValue + Returns a single field (attribute) value of one tuple of a PGresult. + Tuple and field indices start at 0. + + const char *PgDatabase::GetValue(int tup_num, const char *field_name) + + For most queries, the value returned by GetValue is a null-terminated + ASCII string representation of the attribute value. But if BinaryTuples() + is TRUE, the value returned by GetValue is the binary representation + of the type in the internal format of the backend server (but not including + the size word, if the field is variable-length). It is then the programmer's + responsibility to cast and convert the data to the correct C type. The + pointer returned by GetValue points to storage that is part of the + PGresult structure. One should not modify it, and one must explicitly + copy the value into other storage if it is to be used past the lifetime + of the PGresult structure itself. BinaryTuples() is not yet implemented. + + + + + GetLength + Returns the length of a field (attribute) in bytes. Tuple and field + indices start at 0. + + int PgDatabase::GetLength(int tup_num, int field_num) + + This is the actual data length for the particular data value, that + is the size of the object pointed to by GetValue. Note that for + ASCII-represented values, this size has little to do with the binary + size reported by PQfsize. + + + + + GetLength + Returns the length of a field (attribute) in bytes. Tuple and field + indices start at 0. + + int PgDatabase::GetLength(int tup_num, const char* field_name) + + This is the actual data length for the particular data value, that + is the size of the object pointed to by GetValue. Note that for + ASCII-represented values, this size has little to do with the binary + size reported by PQfsize. + + + + + DisplayTuples + Prints out all the tuples and, optionally, the attribute names to the + specified output stream. + + void PgDatabase::DisplayTuples(FILE *out = 0, int fillAlign = 1, + const char* fieldSep = "|",int printHeader = 1, int quiet = 0) + + + + + + PrintTuples + Prints out all the tuples and, optionally, the attribute names to the + specified output stream. + + void PgDatabase::PrintTuples(FILE *out = 0, int printAttName = 1, + int terseOutput = 0, int width = 0) + + + + + + GetLine + + int PgDatabase::GetLine(char* string, int length) + + + + + + PutLine + + void PgDatabase::PutLine(const char* string) + + + + + + OidStatus + + const char *PgDatabase::OidStatus() + + + + + + EndCopy + + int PgDatabase::EndCopy() - Asynchronous Notification @@ -483,26 +608,26 @@ The libpq++ application must poll the backend to see if there is any pending notification information. After the execution of a query, a frontend may call - PGdatabase::notifies + PgDatabase::Notifies to see if any notification data is currently available from the backend. - PGdatabase::notifies + PgDatabase::Notifies returns the notification from a list of unhandled notifications from the backend. The function eturns NULL if there is no pending notifications from the backend. - PGdatabase::notifies + PgDatabase::Notifies behaves like the popping of a stack. Once a notification is returned - from PGdatabase::notifies, + from PgDatabase::Notifies, it is considered handled and will be removed from the list of notifications. - PGdatabase::notifies + PgDatabase::Notifies retrieves pending notifications from the server. - PGnotify* PGdatabase::notifies() + PGnotify* PgDatabase::Notifies() @@ -513,7 +638,6 @@ notification. - Functions Associated with the COPY Command @@ -528,13 +652,13 @@ - PGdatabase::getline + PgDatabase::GetLine reads a newline-terminated line of characters (transmitted by the backend server) into a buffer string of size length. - int PGdatabase::getline(char* string, int length) + int PgDatabase::GetLine(char* string, int length) @@ -550,7 +674,7 @@ character. - PGdatabase::getline + PgDatabase::GetLine returns EOF at end of file, 0 if the entire line has been read, and 1 if the buffer is full but the terminating newline has not yet been read. @@ -563,16 +687,16 @@ that are more than length-1 characters long, the application must be sure to check the return - value of PGdatabase::getline very carefully. + value of PgDatabase::GetLine very carefully. - PGdatabase::putline + PgDatabase::PutLine Sends a null-terminated string to the backend server. - void PGdatabase::putline(char* string) + void PgDatabase::PutLine(char* string) @@ -582,18 +706,18 @@ - PGdatabase::endcopy + PgDatabase::EndCopy syncs with the backend. - int PGdatabase::endcopy() + int PgDatabase::EndCopy() This function waits until the backend has finished processing the copy. It should either be issued when the last string has been sent to the backend using - PGdatabase::putline + PgDatabase::PutLine or when the last string has been received from the backend using - PGdatabase::getline. + PgDatabase::GetLine. It must be issued or the backend may get out of sync with the frontend. Upon return from this function, the backend is ready to receive the next query. @@ -608,7 +732,7 @@ As an example: - PGdatabase data; + PgDatabase data; data.exec("create table foo (a int4, b char16, d float8)"); data.exec("copy foo from stdin"); data.putline("3\etHello World\et4.5\en"); @@ -620,7 +744,6 @@ - Caveats @@ -628,8 +751,22 @@ The query buffer is 8192 bytes long, and queries over that length will be silently truncated. - - The PGlobj class is largely untested. Use with caution. - - + + +