diff --git a/doc/src/sgml/libpq++.sgml b/doc/src/sgml/libpq++.sgml index 2327eb5e26..39c026a41a 100644 --- a/doc/src/sgml/libpq++.sgml +++ b/doc/src/sgml/libpq++.sgml @@ -1,590 +1,627 @@ -libpq C++ Binding - - -libpq++ is the C++ API to -Postgres. -libpq++ is a set of classes which allow -client programs to connect to the -Postgres backend server. These connections -come in two forms: a Database Class and a Large Object class. - - -The Database Class is intended for manipulating a database. You can -send all sorts of SQL queries to the Postgres -backend server and retrieve the responses of the server. - - -The Large Object Class is intended for manipulating a large object -in a database. Although a Large Object instance can send normal -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 -streams -cin, -cout -and -cerr. - - -This chapter is based on the documentation -for the libpq C library. Three -short programs are listed at the end of this section as examples of -libpq++ programming -(though not necessarily of good programming). -There are several examples of libpq++ -applications in -src/libpq++/examples, including the source -code for the three examples in this chapter. - - -Control and Initialization - - - - -Environment Variables - - -The following environment variables can be used to set up default -values for an environment and to avoid hard-coding database names into -an application program: - - - -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. - - - - -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 -backend. - - - - -PGDATABASE sets the default -Postgres database name. - - - - -PGUSER -sets the username used to connect to the database and for authentication. - - - - -PGPASSWORD -sets the password used if the backend demands password authentication. - - - - -PGREALM sets the Kerberos realm to use with -Postgres, - if it is different from the local realm. If -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 -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 -sets the default style of date/time representation. - - - - -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. - - - - -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 -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 - - - - - -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. - -void ExecStatusType PGdatabase::exec(char *query); - - -The following status results can be expected: - - - -PGRES_EMPTY_QUERY - -PGRES_COMMAND_OK, if the query was a command - -PGRES_TUPLES_OK, if the query successfully returned tuples - -PGRES_COPY_OUT - -PGRES_COPY_IN - -PGRES_BAD_RESPONSE, if an unexpected response was received - -PGRES_NONFATAL_ERROR - -PGRES_FATAL_ERROR - - - - - -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. - -int PGdatabase::ntuples() - - - - -PGdatabase::nfields -returns the number of fields (attributes) in the query result. - -int PGdatabase::nfields() - - - - -PGdatabase::fieldname -returns the field (attribute) name associated with the given field index. -Field indices start at zero. - -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) - - - - -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. - -Oid PGdatabase::fieldtype(int field_index) -Oid PGdatabase::fieldtype(char* field_name) - - - - -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. - -int2 PGdatabase::fieldsize(int field_index) -int2 PGdatabase::fieldsize(char* field_name) - - - - -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. - -char* PGdatabase::getvalue(int tup_num, int field_index) -char* PGdatabase::getvalue(int tup_num, char* field_name) - - - - -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. - -int PGdatabase::getlength(int tup_num, int field_index) -int PGdatabase::getlength(int tup_num, char* field_name) - - - - -PGdatabase::printtuples -prints out all the tuples and, optionally, the attribute names to the -specified output stream. - -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*/ - ); - - - - - -Asynchronous Notification - - -Postgres supports asynchronous notification -via the LISTEN and NOTIFY -commands. A backend registers its interest in a particular semaphore -with the LISTEN command. - All backends that are listening on a -particular named semaphore will be notified asynchronously when -a NOTIFY of -that name is executed by another backend. No additional -information is passed from the notifier to the listener. Thus, -typically, any actual data that needs to be communicated is transferred -through the relation. - - - -In the past, the documentation has associated the names used for asyncronous -notification with relations or classes. However, there is in fact no -direct linkage of the two concepts in the implementation, and the -named semaphore in fact does not need to have a corresponding relation -previously defined. - - - -libpq++ applications are notified whenever a -connected backend has -received an asynchronous notification. However, the communication from -the backend to the frontend is not asynchronous. -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 -to see if any notification data is currently available from the backend. -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 -behaves like the popping of a stack. Once a notification is returned -from PGdatabase::notifies, -it is considered handled and will be removed from the list of -notifications. - - - - -PGdatabase::notifies -retrieves pending notifications from the server. - - -PGnotify* PGdatabase::notifies() - - - - - -The second sample program gives an example of the use of asynchronous -notification. - - -Functions Associated with the COPY Command - - -The copy command in Postgres -has options to read from or write to the network -connection used by libpq++. -Therefore, functions are necessary to -access this network connection directly so applications may take full -advantage of this capability. - - - - -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) - - - -Like the Unix system routine -fgets (3), -this routine copies up to -length-1 -characters into -string. -It is like -gets (3), -however, in that it converts the terminating newline into a null -character. - - -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. - - -Notice that the application must check to see if a new line consists -of a single period ("."), which indicates that the backend -server has finished sending the results of the -copy. -Therefore, if the application ever expects to receive lines -that are more than -length-1 -characters long, the application must be sure to check the return -value of PGdatabase::getline very carefully. - - - -PGdatabase::putline -Sends a null-terminated string -to the backend server. - -void PGdatabase::putline(char* string) - - - -The application must explicitly send a single period character (".") -to indicate to the backend that it has finished sending its data. - - - -PGdatabase::endcopy -syncs with the backend. - -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 -or when the last string has been received from the backend using -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. - - -The return value is 0 on successful completion, nonzero otherwise. - - - - -As an example: - - -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"); -data.putline("4\etGoodbye World\et7.11\en"); -\&... -data.putline(".\en"); -data.endcopy(); - - - - -Caveats - - -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. - + libpq C++ Binding + + + libpq++ is the C++ API to + Postgres. + libpq++ is a set of classes which allow + client programs to connect to the + Postgres backend server. These connections + come in two forms: a Database Class and a Large Object class. + + + The Database Class is intended for manipulating a database. You can + send all sorts of SQL queries to the Postgres + backend server and retrieve the responses of the server. + + + The Large Object Class is intended for manipulating a large object + in a database. Although a Large Object instance can send normal + 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 + streams + cin, + cout + and + cerr. + + + This chapter is based on the documentation + for the libpq C library. Three + short programs are listed at the end of this section as examples of + libpq++ programming + (though not necessarily of good programming). + There are several examples of libpq++ + applications in + src/libpq++/examples, including the source + code for the three examples in this chapter. + + + Control and Initialization + + + + + Environment Variables + + + The following environment variables can be used to set up default + values for an environment and to avoid hard-coding database names into + an application program: + + + 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. + + + + + 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 + backend. + + + + + PGDATABASE sets the default + Postgres database name. + + + + + PGUSER + sets the username used to connect to the database and for authentication. + + + + + PGPASSWORD + sets the password used if the backend demands password authentication. + + + + + PGREALM sets the Kerberos realm to use with + Postgres, + if it is different from the local realm. If + 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 + 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 + sets the default style of date/time representation. + + + + + 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. + + + + + + + + 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 + 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 + + + + + + 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. + + void ExecStatusType PGdatabase::exec(char *query); + + + The following status results can be expected: + + + + PGRES_EMPTY_QUERY + + + PGRES_COMMAND_OK, if the query was a command + + + PGRES_TUPLES_OK, if the query successfully returned tuples + + + PGRES_COPY_OUT + + + PGRES_COPY_IN + + + PGRES_BAD_RESPONSE, if an unexpected response was received + + + PGRES_NONFATAL_ERROR + + + PGRES_FATAL_ERROR + + + + + + + + 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. + + int PGdatabase::ntuples() + + + + + + PGdatabase::nfields + returns the number of fields (attributes) in the query result. + + int PGdatabase::nfields() + + + + + + PGdatabase::fieldname + returns the field (attribute) name associated with the given field index. + Field indices start at zero. + + 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) + + + + + + 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. + + Oid PGdatabase::fieldtype(int field_index) + Oid PGdatabase::fieldtype(char* field_name) + + + + + + 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. + + int2 PGdatabase::fieldsize(int field_index) + int2 PGdatabase::fieldsize(char* field_name) + + + + + + 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. + + char* PGdatabase::getvalue(int tup_num, int field_index) + char* PGdatabase::getvalue(int tup_num, char* field_name) + + + + + + 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. + + int PGdatabase::getlength(int tup_num, int field_index) + int PGdatabase::getlength(int tup_num, char* field_name) + + + + + + PGdatabase::printtuples + prints out all the tuples and, optionally, the attribute names to the + specified output stream. + + 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*/ + ); + + + + + + + + Asynchronous Notification + + + Postgres supports asynchronous notification + via the LISTEN and NOTIFY + commands. A backend registers its interest in a particular semaphore + with the LISTEN command. + All backends that are listening on a + particular named semaphore will be notified asynchronously when + a NOTIFY of + that name is executed by another backend. No additional + information is passed from the notifier to the listener. Thus, + typically, any actual data that needs to be communicated is transferred + through the relation. + + + + In the past, the documentation has associated the names used for asyncronous + notification with relations or classes. However, there is in fact no + direct linkage of the two concepts in the implementation, and the + named semaphore in fact does not need to have a corresponding relation + previously defined. + + + + + libpq++ applications are notified whenever a + connected backend has + received an asynchronous notification. However, the communication from + the backend to the frontend is not asynchronous. + 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 + to see if any notification data is currently available from the backend. + 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 + behaves like the popping of a stack. Once a notification is returned + from PGdatabase::notifies, + it is considered handled and will be removed from the list of + notifications. + + + + + PGdatabase::notifies + retrieves pending notifications from the server. + + + PGnotify* PGdatabase::notifies() + + + + + + + The second sample program gives an example of the use of asynchronous + notification. + + + + Functions Associated with the COPY Command + + + The copy command in Postgres + has options to read from or write to the network + connection used by libpq++. + Therefore, functions are necessary to + access this network connection directly so applications may take full + advantage of this capability. + + + + + 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) + + + + Like the Unix system routine + fgets (3), + this routine copies up to + length-1 + characters into + string. + It is like + gets (3), + however, in that it converts the terminating newline into a null + character. + + + 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. + + + Notice that the application must check to see if a new line consists + of a single period ("."), which indicates that the backend + server has finished sending the results of the + copy. + Therefore, if the application ever expects to receive lines + that are more than + length-1 + characters long, the application must be sure to check the return + value of PGdatabase::getline very carefully. + + + + + PGdatabase::putline + Sends a null-terminated string + to the backend server. + + void PGdatabase::putline(char* string) + + + + The application must explicitly send a single period character (".") + to indicate to the backend that it has finished sending its data. + + + + + PGdatabase::endcopy + syncs with the backend. + + 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 + or when the last string has been received from the backend using + 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. + + + The return value is 0 on successful completion, nonzero otherwise. + + + + + + As an example: + + + 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"); + data.putline("4\etGoodbye World\et7.11\en"); + \&... + data.putline(".\en"); + data.endcopy(); + + + + + + Caveats + + + 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. + +