Select Git revision
libpq++.sgml
-
Peter Eisentraut authoredPeter Eisentraut authored
libpq++.sgml 26.28 KiB
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.41 2002/03/22 19:20:12 petere Exp $
-->
<chapter id="libpqplusplus">
<title><application>libpq++</application> - C++ Binding Library</title>
<indexterm zone="libpqplusplus">
<primary>libpq++</primary>
</indexterm>
<indexterm zone="libpqplusplus">
<primary>C++</primary>
</indexterm>
<sect1 id="libpqpp-introduction">
<title>Introduction</title>
<para>
<application>libpq++</application> is the C++ API to
<productname>PostgreSQL</productname>.
<application>libpq++</application> is a set of classes that allow
client programs to connect to the
<productname>PostgreSQL</productname> backend server. These connections
come in two forms: a database class and a large object class.
</para>
<para>
The database class is intended for manipulating a database. You can
send all sorts of SQL queries and commands to the <productname>PostgreSQL</productname>
backend server and retrieve the responses of the server.
</para>
<para>
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 <productname>PostgreSQL</productname> 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 the future it should behave much like the C++ file
streams
<literal>cin</literal>,
<literal>cout</literal>
and
<literal>cerr</literal>.
</para>
<para>
This chapter is based on the documentation for the
<application>libpq</application> C library (see <xref
linkend="libpq">). There
are several examples of <application>libpq++</application>
applications in
<filename>src/interfaces/libpq++/examples</filename> in the source
distribution.
</para>
</sect1>
<sect1 id="libpqpp-init">
<title>Control and Initialization</title>
<sect2>
<title>Environment Variables</title>
<para>
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:
<note>
<para>
Refer to <xref linkend="libpq-envars"> for a complete
list of available connection options. </para>
</note>
</para>
<para>
The following environment variables can be used to select default
connection parameter values, which will be used by
<function>PQconnectdb</> or
<function>PQsetdbLogin</> if no value is directly specified by the calling code.
These are useful to avoid hard-coding database names into simple
application programs.
<note>
<para>
<filename>libpq++</filename> uses only environment variables or
<filename>libpq</>'s <function>PQconnectdb</>
<parameter>conninfo</parameter> style strings.
</para>
</note>
<itemizedlist>
<listitem>
<para>
<envar>PGHOST</envar> sets the default server name.
If this begins with a slash, it specifies Unix-domain communication
rather than TCP/IP communication; the value is the name of the
directory in which the socket file is stored (default <filename>/tmp</filename>).
</para>
</listitem>
<listitem>
<para>
<envar>PGPORT</envar> sets the default TCP port number or Unix-domain
socket file extension for communicating with the
<productname>PostgreSQL</productname> backend.
</para>
</listitem>
<listitem>
<para>
<envar>PGDATABASE</envar> sets the default
<productname>PostgreSQL</productname> database name.
</para>
</listitem>
<listitem>
<para>
<envar>PGUSER</envar>
sets the user name used to connect to the database and for authentication.
</para>
</listitem>
<listitem>
<para>
<envar>PGPASSWORD</envar>
sets the password used if the backend demands password
authentication. This is not recommended because the password can
be read by others using the <command>ps</command> command with special options
on some platforms.
</para>
</listitem>
<listitem>
<para>
<envar>PGREALM</envar> sets the Kerberos realm to use with
<productname>PostgreSQL</productname>,
if it is different from the local realm. If
<envar>PGREALM</envar> is set, <productname>PostgreSQL</productname>
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.
</para>
</listitem>
<listitem> <para>
<envar>PGOPTIONS</envar> sets additional run-time options for
the <productname>PostgreSQL</productname> backend.
</para>
</listitem>
<listitem>
<para>
<envar>PGTTY</envar> sets the file or <acronym>tty</acronym> on which debugging
messages from the backend server are displayed.
</para>
</listitem>
</itemizedlist>
</para>
<para>
The following environment variables can be used to specify user-level default
behavior for every <productname>PostgreSQL</productname> session:
<itemizedlist>
<listitem>
<para>
<envar>PGDATESTYLE</envar>
sets the default style of date/time representation.
</para>
</listitem>
<listitem>
<para>
<envar>PGTZ</envar>
sets the default time zone.
</para>
</listitem>
</itemizedlist>
</para>
<para>
The following environment variables can be used to specify default internal
behavior for every <productname>PostgreSQL</productname> session:
<itemizedlist>
<listitem>
<para>
<envar>PGGEQO</envar>
sets the default mode for the genetic optimizer.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Refer to the <command>SET</command> <acronym>SQL</acronym> command
for information on correct values for these environment variables.
</para>
</sect2>
</sect1>
<sect1 id="libpqpp-classes">
<title><application>libpq++</application> Classes</title>
<sect2>
<title>Connection Class: <classname>PgConnection</classname></title>
<para>
The connection class makes the actual connection to the database and is inherited
by all of the access classes.
</para>
</sect2>
<sect2>
<title>Database Class: <classname>PgDatabase</classname></title>
<para>
The database class provides C++ objects that have a connection
to a backend server. To create such an object one first needs
the appropriate environment for the backend to access.
The following constructors deal with making a connection to a backend
server from a C++ program.
</para>
</sect2>
</sect1>
<sect1 id="libpqpp-connect">
<title>Database Connection Functions</title>
<para>
<itemizedlist>
<listitem>
<para>
<function>PgConnection</function>
makes a new connection to a backend database server.
<synopsis>
PgConnection::PgConnection(const char *conninfo)
</synopsis>
The <parameter>conninfo</> string is the same as for the underlying
<application>libpq</> <function>PQconnectdb</> function.
</para>
<para>
Although typically called from one of the access classes, a connection to
a backend server is possible by creating a <classname>PgConnection</> object.
</para>
</listitem>
<listitem>
<para>
<function>ConnectionBad</function>
returns whether or not the connection to the backend server succeeded or
failed.
<synopsis>
bool PgConnection::ConnectionBad() const
</synopsis>
Returns true if the connection failed.
</para>
</listitem>
<listitem>
<para>
<function>Status</function>
returns the status of the connection to the backend server.
<synopsis>
ConnStatusType PgConnection::Status()
</synopsis>
Returns either <symbol>CONNECTION_OK</> or
<symbol>CONNECTION_BAD</> depending on the state of the
connection.
</para>
</listitem>
<listitem>
<para>
<function>PgDatabase</function>
makes a new connection to a backend database server.
<synopsis>
PgDatabase(const char *conninfo)
</synopsis>
After a <classname>PgDatabase</classname> has been created it should be checked to make sure
the connection to the database succeeded before sending
queries to the object. This can easily be done by
retrieving the current status of the <classname>PgDatabase</classname> object with the
<function>Status</function> or <function>ConnectionBad</function> methods.
</para>
</listitem>
<listitem>
<para>
<function>DBName</function>
returns the name of the current database.
<synopsis>
const char *PgConnection::DBName()
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>Notifies</function>
returns the next notification from a list of unhandled notification messages
received from the backend.
<synopsis>
PGnotify* PgConnection::Notifies()
</synopsis>
See <function>PQnotifies</function> in <application>libpq</> for details.
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id="libpqpp-exec">
<title>Query Execution Functions</title>
<sect2 id="libpqpp-exec-main">
<title>Main Routines</title>
<para>
<itemizedlist>
<listitem>
<para>
<function>Exec</function>
sends a command to the backend server. It's probably more desirable to
use one of the next two functions.
<synopsis>
ExecStatusType PgConnection::Exec(const char* query)
</synopsis>
Returns the result status of the command. The following status
results can be expected:
<simplelist>
<member>
<symbol>PGRES_EMPTY_QUERY</symbol>
</member>
<member>
<symbol>PGRES_COMMAND_OK</symbol>, if the command was not a query
</member>
<member>
<symbol>PGRES_TUPLES_OK</symbol>, if the query successfully returned tuples
</member>
<member>
<symbol>PGRES_COPY_OUT</symbol>
</member>
<member>
<symbol>PGRES_COPY_IN</symbol>
</member>
<member>
<symbol>PGRES_BAD_RESPONSE</symbol>, if an unexpected response was received
</member>
<member>
<symbol>PGRES_NONFATAL_ERROR</symbol>
</member>
<member>
<symbol>PGRES_FATAL_ERROR</symbol>
</member>
</simplelist> </para>
</listitem>
<listitem>
<para>
<function>ExecCommandOk</function> sends a non-query command
(one that does not return rows) to the backend server.
<synopsis>
int PgConnection::ExecCommandOk(const char *query)
</synopsis>
Returns true (1) if the command succeeds.
</para>
</listitem>
<listitem>
<para>
<function>ExecTuplesOk</function>
Sends a query command (one that returns rows) to the backend server.
<synopsis>
int PgConnection::ExecTuplesOk(const char *query)
</synopsis>
Returns true (1) if the query succeeds.
</para>
</listitem>
<listitem>
<para>
<function>ErrorMessage</function>
returns the last error message text.
<synopsis>
const char *PgConnection::ErrorMessage()
</synopsis>
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
<sect2 id="libpqpp-exec-select-info">
<title>Retrieving SELECT Result Information</title>
<itemizedlist>
<listitem>
<para>
<function>Tuples</function>
returns the number of tuples (rows) in the query result.
<synopsis>
int PgDatabase::Tuples() const
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>Fields</function>
returns the number of fields (rows) in each tuple of the query result.
<synopsis>
int PgDatabase::Fields()
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>FieldName</function>
returns the field (column) name associated with the given field index.
Field indices start at 0.
<synopsis>
const char *PgDatabase::FieldName(int field_num) const
</synopsis> </para>
</listitem>
<listitem>
<para>
<function>FieldNum</function>
returns the field (column) index associated with
the given field name.
<synopsis>
int PgDatabase::FieldNum(const char* field_name) const
</synopsis>
-1 is returned if the given name does not match any field.
</para>
</listitem>
<listitem>
<para>
<function>FieldType</function>
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.
<synopsis>
Oid PgDatabase::FieldType(int field_num) const
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>FieldType</function>
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.
<synopsis>
Oid PgDatabase::FieldType(const char* field_name) const
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>FieldSize</function>
returns the size in bytes of the field associated with the given
field index. Field indices start at 0.
<synopsis>
int PgDatabase::FieldSize(int field_num) const
</synopsis>
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.
</para>
</listitem>
<listitem>
<para>
<function>FieldSize</function>
returns the size in bytes of the field associated with the given
field index. Field indices start at 0.
<synopsis>
int PgDatabase::FieldSize(const char *field_name) const
</synopsis>
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.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="libpqpp-exec-select-values">
<title>Retrieving SELECT Result Values</title>
<itemizedlist>
<listitem>
<para>
<function>GetValue</function> returns a single field (column)
value of one tuple of a <structname>PGresult</structname>.
Tuple and field indices start at 0.
<synopsis>
const char *PgDatabase::GetValue(int tup_num, int field_num) const
</synopsis>
For most queries, the value returned by
<function>GetValue</function> is a null-terminated string
representation of the attribute value. But if
<function>BinaryTuples</function> is true, the value returned by
<function>GetValue</function> 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
<function>GetValue</function> points to storage that is part of
the <structname>PGresult</structname> 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
<structname>PGresult</structname> structure itself.
<function>BinaryTuples</function> is not yet implemented.
</para>
</listitem>
<listitem>
<para>
<function>GetValue</function> returns a single field (column)
value of one tuple of a <structname>PGresult</structname>.
Tuple and field indices start at 0.
<synopsis>
const char *PgDatabase::GetValue(int tup_num, const char *field_name) const
</synopsis>
For most queries, the value returned by
<function>GetValue</function> is a null-terminated string
representation of the attribute value. But if
<function>BinaryTuples</function> is true, the value returned by
<function>GetValue</function> 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
<function>GetValue</function> points to storage that is part of
the <structname>PGresult</structname> 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
<structname>PGresult</structname> structure itself.
<function>BinaryTuples</function> is not yet implemented.
</para>
</listitem>
<listitem>
<para>
<function>GetLength</function> returns the length of a field
(column) in bytes. Tuple and field indices start at 0.
<synopsis>
int PgDatabase::GetLength(int tup_num, int field_num) const
</synopsis>
This is the actual data length for the particular data value,
that is the size of the object pointed to by
<function>GetValue</function>. Note that for
character-represented values, this size has little to do with
the binary size reported by <function>PQfsize</function>. </para>
</listitem>
<listitem>
<para>
<function>GetLength</function> returns the length of a field
(column) in bytes. Tuple and field indices start at 0.
<synopsis>
int PgDatabase::GetLength(int tup_num, const char* field_name) const
</synopsis>
This is the actual data length for the particular data value,
that is the size of the object pointed to by
<function>GetValue</function>. Note that for
character-represented values, this size has little to do with
the binary size reported by <function>PQfsize</function>.
</para>
</listitem>
<listitem>
<para>
<function>GetIsNull</function>
returns whether a field has the null value.
<synopsis>
bool GetIsNull(int tup_num, int field_num) const
</synopsis>
Note that <function>GetValue</function> will return the empty
string for null fields, not the NULL pointer.
</para>
</listitem>
<listitem>
<para>
<function>GetIsNull</function> returns whether a field has the
null value.
<synopsis>
bool GetIsNull(int tup_num, const char *field_name) const
</synopsis>
Note that <function>GetValue</function> will return the empty
string for null fields, not the NULL pointer.
</para>
</listitem>
<listitem>
<para>
<function>DisplayTuples</function> prints out all the tuples
and, optionally, the attribute names to the specified output
stream.
<synopsis>
void PgDatabase::DisplayTuples(FILE *out = 0, bool fillAlign = true,
const char* fieldSep = "|", bool printHeader = true, bool quiet = false) const
</synopsis>
This function is obsolescent.
</para>
</listitem>
<listitem>
<para>
<function>PrintTuples</function> prints out all the tuples and,
optionally, the attribute names to the specified output stream.
<synopsis>
void PgDatabase::PrintTuples(FILE *out = 0, bool printAttName = true,
bool terseOutput = false, bool fillAlign = false) const
</synopsis>
This function is obsolescent.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="libpqpp-exec-nonselect"> <title>Retrieving Non-SELECT Result Information</title>
<itemizedlist>
<listitem>
<para>
<function>CmdTuples</function> returns the number of rows
affected after an <command>INSERT</command>,
<command>UPDATE</command>, or <command>DELETE</command>. If the
command was anything else, it returns -1.
<synopsis>
int PgDatabase::CmdTuples() const
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>OidStatus</function>
<synopsis>
const char *PgDatabase::OidStatus() const
</synopsis>
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="libpqpp-notify">
<title>Asynchronous Notification</title>
<para>
<productname>PostgreSQL</productname> supports asynchronous
notification via the <command>LISTEN</command> and
<command>NOTIFY</command> commands. A backend registers its
interest in a particular notification condition with the
<command>LISTEN</command> command. All backends that are
listening on a particular condition will be notified
asynchronously when a <command>NOTIFY</command> 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 a
relation.
</para>
<para>
<application>libpq++</application> 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 <application>libpq++</application> application
must poll the backend to see if there is any pending notification
information. After the execution of a command, a frontend may call
<function>PgDatabase::Notifies</function>
to see if any notification data is currently available from the backend.
<function>PgDatabase::Notifies</function>
returns the notification from a list of unhandled notifications from the
backend. The function returns <symbol>NULL</symbol> if there are no pending notifications
from the backend.
<function>PgDatabase::Notifies</function>
behaves like the popping of a stack. Once a notification is returned
from <function>PgDatabase::Notifies</function>,
it is considered handled and will be removed from the list of
notifications.
<itemizedlist>
<listitem>
<para>
<function>PgDatabase::Notifies</function>
retrieves pending notifications from the server.
<synopsis>
PGnotify* PgDatabase::Notifies()
</synopsis>
</para>
</listitem>
</itemizedlist>
</para>
<para>
The second sample program gives an example of the use of asynchronous
notification.
</para>
</sect1>
<sect1 id="libpqpp-copy">
<title>Functions Associated with the COPY Command</title>
<para>
The <command>COPY</command> command in <productname>PostgreSQL</productname>
has options to read from or write to the network
connection used by <application>libpq++</application>.
Therefore, functions are necessary to
access this network connection directly so applications may take full
advantage of this capability.
<itemizedlist>
<listitem>
<para>
<function>PgDatabase::GetLine</function>
reads a newline-terminated line of characters (transmitted by the
backend server) into a buffer
<replaceable class="parameter">string</replaceable>
of size <replaceable class="parameter">length</replaceable>.
<synopsis>
int PgDatabase::GetLine(char* string, int length)
</synopsis>
</para>
<para>
Like the Unix system routine
<function>fgets()</function>,
this routine copies up to
<literal><replaceable class="parameter">length</replaceable>-1</literal>
characters into
<replaceable class="parameter">string</replaceable>.
It is like
<function>gets()</function>,
however, in that it converts the terminating newline into a zero byte.
</para>
<para>
<function>PgDatabase::GetLine</function>
returns <symbol>EOF</symbol> 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.
</para>
<para>
Notice that the application must check to see if a new line consists
of a backslash followed by a period (<literal>\.</>), which indicates
that the backend
server has finished sending the results of the
<command>COPY</command>.
Therefore, if the application ever expects to receive lines
that are more than
<literal><replaceable class="parameter">length</replaceable>-1</literal>
characters long, the application must be sure to check the return
value of <function>PgDatabase::GetLine</function> very carefully.
</para>
</listitem>
<listitem>
<para>
<function>PgDatabase::PutLine</function> Sends a null-terminated <replaceable class="parameter">string</replaceable>
to the backend server.
<synopsis>
void PgDatabase::PutLine(char* string)
</synopsis>
</para>
<para>
The application must explicitly send the characters <literal>\.</literal>
to indicate to the backend that it has finished sending its data.
</para>
</listitem>
<listitem>
<para>
<function>PgDatabase::EndCopy</function>
synchronizes with the backend.
<synopsis>
int PgDatabase::EndCopy()
</synopsis>
This function waits until the backend has
finished processing the <command>COPY</command>.
It should either be issued when the
last string has been sent to the backend using
<function>PgDatabase::PutLine</function>
or when the last string has been received from the backend using
<function>PgDatabase::GetLine</function>.
It must be issued or the backend may get <quote>out of sync</quote> with
the frontend. Upon return from this function, the backend is ready to
receive the next command.
</para>
<para>
The return value is 0 on successful completion, nonzero otherwise.
</para>
</listitem>
</itemizedlist>
</para>
<para>
As an example:
<programlisting>
PgDatabase data;
data.Exec("CREATE TABLE foo (a int4, b char(16), d double precision)");
data.Exec("COPY foo FROM STDIN");
data.PutLine("3\tHello World\t4.5\n");
data.PutLine("4\tGoodbye World\t7.11\n");
...
data.PutLine("\\.\n");
data.EndCopy();
</programlisting>
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->