libpq++

The libpq++ library enables C++ applications to interface with the PostgreSQL back end. Fundamentally, it operates in the same way as the libpq library except that much of it is implemented as classes.

libpq++ provides two main classes: PgConnection and PgDatabase.

PgConnection

This class provides the functions needed to connect to a PostgreSQL database.

PgConnection::PgConnection(const char *conninfo)

The connection info can be specified either by the connect-string argument (as in the preceding) or by expressly setting the following environmental variables:

PGDATABASE	Sets the database name.
PGDATESTYLE	Sets the default date style.
PGGEQO	Sets the default Genetic Optimizer.
PGHOST	Sets the database host.
PGOPTIONS	Sets various run-time options.
PGPASSWORD	Sets the user's password.
PGPORT	Sets the server port.
PGREALM	Sets the Kerberos realm.
PGTTY	Sets the debug/error tty or file.
PGTZ	Sets the default time zone.
PGUSER	Sets the username.

The connect-string argument, if the environmental variables are not used, can be specified with the following options (in the form option=value):

Option	Description
dbname	The specific database to connect to.
host	The hostname (or UNIX path) to connect to.
hostaddr	For TCP/IP connections, the IP address.
options	Trace/debug options.
password	If authentication is required, the password.
port	The port of the server.
requiressl	Set to 1 to mandate SSL connections.
tty	The file or tty to send debugging information to.
user	Connect as this user.

This class provides several functions that assist in database connection.

• int PgConnection::ConnectionBad()

  Returns TRUE if the connection succeeded; otherwise, returns FALSE.

• int ConnStatusType PgConnection::Status()

  Returns the status of the connection to the back-end server, either CONNECTION_OK or CONNECTION_BAD.

• ExecStatusType PgConnection::Exec(const char* query)

  Sends a query to the back-end server for execution. Returns the results of the query.The status should report one of the following:

  PGRES_EMPTY_QUERY

  PGRES_COMMAND_OK

  PGRES_TUPLES_OK

  PGRES_COPY_OUT

  PGRES_COPY_IN

  PGRES_BAD_RESPONSE

  PGRES_NONFATAL_ERROR

  PGRES_FATAL_ERROR

• const char *PgConnection::ErrorMessage()

  Returns the last error message text.

PgDatabase

The pgDatabase class provides access to the elements residing in a return set of data. Specifically, this class is useful for returning information pertaining to how many rows or fields were affected by a given query. The following are the class functions:

• int PgDatabase::Tuples()

  Returns the number of rows in the query result.

• int PgDatabase::CmdTuples()

  Returns the number of rows affected after an INSERT, UPDATE, or DELETE. If the command was anything else, it returns –1.

• int PgDatabase::Fields()

  Returns the number of fields in the query result.

• const char *PgDatabase::FieldName(int field_num)

  Returns the field name associated with the given index. The field indices start at 0.

• int PgDatabase::FieldNum(const char* field_name)

  Returns the field index associated with the field name specified.

• Oid PgDatabase::FieldType(int field_num)

  Returns the field type associated with the given index. The integer returned is an internal coding of the type.

• short PgDatabase::FieldSize(int field_num)

  Returns the number of bytes occupied by the given field. Field indices start at 0.

• const char *PgDatabase::GetValue(int tup_num, int field_num)

  Returns a single field value from a row of a PGresult. Row and field indices start at 0. For most queries, the value returned by GetValue is a null-terminated ASCII string.

• int PgDatabase::GetLength(int tup_num, int field_num)

  Returns the length of a field in bytes.

• void PgDatabase::PrintTuples(FILE *out = 0, int printAttName = 1, int terseOutput = 0, int width = 0)

  Prints out all the tuples and/or the attribute names.

• int PgDatabase::GetLine(char* string, int length)

  Reads a line directly from the socket.

• void PgDatabase::PutLine(const char* string)

  Writes a line directly to the connection socket.

• int PgDatabase::EndCopy()

  Ensures that client and server will be synchronized, in case direct access methods caused communications to get out of sync.