mirror of
https://github.com/postgres/postgres.git
synced 2025-08-31 17:02:12 +03:00
841 lines
26 KiB
Plaintext
841 lines
26 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.40 2002/01/07 02:29: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 runtime 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:
|
|
-->
|