mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-10-03 06:46:54 +02:00
826 lines
27 KiB
Plaintext
826 lines
27 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.33 2001/10/12 23:32:34 momjian Exp $
|
|
-->
|
|
|
|
<chapter id="libpqplusplus">
|
|
<title><application>libpq++</application> - C++ Binding Library</title>
|
|
|
|
<para>
|
|
<filename>libpq++</filename> is the C++ API to
|
|
<productname>Postgres</productname>.
|
|
<filename>libpq++</filename> is a set of classes that allow
|
|
client programs to connect to the
|
|
<productname>Postgres</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 to the <productname>Postgres</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>Postgres</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 <filename>libpq</filename> C library. Three
|
|
short programs are listed at the end of this section as examples of
|
|
<filename>libpq++</filename> programming
|
|
(though not necessarily of good programming).
|
|
There are several examples of <filename>libpq++</filename>
|
|
applications in
|
|
<filename>src/libpq++/examples</filename>, including the source
|
|
code for the three examples in this chapter.
|
|
</para>
|
|
|
|
<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>Postgres</productname> backend.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGDATABASE</envar> sets the default
|
|
<productname>Postgres</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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGREALM</envar> sets the Kerberos realm to use with
|
|
<productname>Postgres</productname>,
|
|
if it is different from the local realm. If
|
|
<envar>PGREALM</envar> is set, <productname>Postgres</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 runtime options for
|
|
the <productname>Postgres</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 Postgres 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 Postgres 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>
|
|
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 CONNECTION_OK or 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> 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 query 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 of the query. The following status results can be expected:
|
|
|
|
<simplelist>
|
|
<member>
|
|
<symbol>PGRES_EMPTY_QUERY</symbol>
|
|
</member>
|
|
<member>
|
|
<symbol>PGRES_COMMAND_OK</symbol>, if the query was a command
|
|
</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 command query to the backend server.
|
|
<synopsis>
|
|
int PgConnection::ExecCommandOk(const char *query)
|
|
</synopsis>
|
|
Returns TRUE if the command query succeeds.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<function>ExecTuplesOk</function>
|
|
Sends a command query to the backend server.
|
|
<synopsis>
|
|
int PgConnection::ExecTuplesOk(const char *query)
|
|
</synopsis>
|
|
Returns TRUE if the command 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 (attributes) in each tuple of the query result.
|
|
<synopsis>
|
|
int PgDatabase::Fields()
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<function>FieldName</function>
|
|
Returns the field (attribute) 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>
|
|
<function>PQfnumber</function> Returns the field (attribute) 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 (attribute) 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 (attribute) 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 (attribute) 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
|
|
ASCII-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 (attribute) 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
|
|
ASCII-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>
|
|
OBSOLESCENT: 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>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<function>PrintTuples</function>
|
|
OBSOLESCENT: 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>
|
|
</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 INSERT, UPDATE or DELETE.
|
|
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>
|
|
|
|
<sect2 id="libpqpp-exec-copy">
|
|
<title>Handling COPY Queries</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>GetLine</function>
|
|
<synopsis>
|
|
int PgDatabase::GetLine(char* string, int length)
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<function>PutLine</function>
|
|
<synopsis>
|
|
void PgDatabase::PutLine(const char* string)
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<function>EndCopy</function>
|
|
<synopsis>
|
|
int PgDatabase::EndCopy()
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="libpqpp-notify">
|
|
<title>Asynchronous Notification</title>
|
|
|
|
<para>
|
|
<productname>Postgres</productname> supports asynchronous notification
|
|
via the <command>LISTEN</command> and <command>NOTIFY</command>
|
|
commands. A backend registers its interest in a particular semaphore
|
|
with the <command>LISTEN</command> command.
|
|
All backends that are listening on a
|
|
particular named semaphore 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 the relation.
|
|
|
|
<note>
|
|
<para>
|
|
In the past, the documentation has associated the names used for asynchronous
|
|
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.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
<filename>libpq++</filename> 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 <filename>libpq++</filename> application
|
|
must poll the backend to see if there is any pending notification
|
|
information. After the execution of a query, 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 NULL 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>Postgres</productname>
|
|
has options to read from or write to the network
|
|
connection used by <filename>libpq++</filename>.
|
|
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 (3)</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 (3)</function>,
|
|
however, in that it converts the terminating newline into a null
|
|
character.
|
|
</para>
|
|
<para>
|
|
<function>PgDatabase::GetLine</function>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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
|
|
<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 a single period character (".")
|
|
to indicate to the backend that it has finished sending its data.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<function>PgDatabase::EndCopy</function>
|
|
syncs 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 query.
|
|
</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:
|
|
-->
|