-
libpq C++ Binding
-
-libpq++ is the C++ API to
-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
-
-
-
-sets the username used to connect to the database and for authentication.
-
-
-
-sets the password used if the backend demands password authentication.
-
-
-
-
PGREALM sets the Kerberos realm to use with
- 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
-
-
-
-
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:
-
-
-
-sets the default style of date/time representation.
-
-
-
-sets the default time zone.
-
-
-
-
-
-The following environment variables can be used to specify default internal
-behavior for every Postgres session:
-
-
-
-sets the default mode for the genetic optimizer.
-
-
-
-sets the default mode to allow or disable right-sided plans in the optimizer.
-
-
-
-sets the default cost for heap searches for the optimizer.
-
-
-
-sets the default cost for indexed searches for the optimizer.
-
-
-
-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
-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
+ 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.
+
+
+
+ sets the username used to connect to the database and for authentication.
+
+
+
+ sets the password used if the backend demands password authentication.
+
+
+
+
PGREALM sets the Kerberos realm to use with
+ 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
+
+
+
+
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:
+
+
+
+ sets the default style of date/time representation.
+
+
+
+ sets the default time zone.
+
+
+
+
+
+ The following environment variables can be used to specify default internal
+ behavior for every Postgres session:
+
+
+
+ sets the default mode for the genetic optimizer.
+
+
+
+ sets the default mode to allow or disable right-sided plans in the optimizer.
+
+
+
+ sets the default cost for heap searches for the optimizer.
+
+
+
+ sets the default cost for indexed searches for the optimizer.
+
+
+
+ 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
+ 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.
+
+
projects / postgresql.git / commitdiff