mirror of https://github.com/postgres/postgres
Bruce Momjian
23 years ago
parent
ff1793f036
commit
f6353c6ee4
@ -1,845 +0,0 @@ |
||||
<!-- |
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.43 2002/08/19 04:05:00 ishii 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 deprecated; use <envar>PGPASSWORDFILE</envar> instead. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
<envar>PGPASSWORDFILE</envar> |
||||
sets the password file used if the backend demands password |
||||
authentication. Refer to the libpq documentation for more details. |
||||
</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: |
||||
--> |
||||
Loading…
Reference in new issue