Remove libpq++ SGML documentation.
This commit is contained in:
Bruce Momjian
parent
ff1793f036
commit
f6353c6ee4
@ -1,4 +1,4 @@
|
|||||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.21 2002/08/05 19:43:31 petere Exp $ -->
|
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.22 2002/08/22 03:17:37 momjian Exp $ -->
|
||||||
|
|
||||||
<!entity history SYSTEM "history.sgml">
|
<!entity history SYSTEM "history.sgml">
|
||||||
<!entity info SYSTEM "info.sgml">
|
<!entity info SYSTEM "info.sgml">
|
||||||
@ -68,7 +68,6 @@
|
|||||||
<!entity jdbc SYSTEM "jdbc.sgml">
|
<!entity jdbc SYSTEM "jdbc.sgml">
|
||||||
<!entity libpgeasy SYSTEM "libpgeasy.sgml">
|
<!entity libpgeasy SYSTEM "libpgeasy.sgml">
|
||||||
<!entity libpq SYSTEM "libpq.sgml">
|
<!entity libpq SYSTEM "libpq.sgml">
|
||||||
<!entity libpqpp SYSTEM "libpq++.sgml">
|
|
||||||
<!entity libpgtcl SYSTEM "libpgtcl.sgml">
|
<!entity libpgtcl SYSTEM "libpgtcl.sgml">
|
||||||
<!entity pygresql SYSTEM "pygresql.sgml">
|
<!entity pygresql SYSTEM "pygresql.sgml">
|
||||||
<!entity lobj SYSTEM "lobj.sgml">
|
<!entity lobj SYSTEM "lobj.sgml">
|
||||||
|
|||||||
@ -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:
|
|
||||||
-->
|
|
||||||
@ -1,5 +1,5 @@
|
|||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.39 2002/01/07 02:29:13 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.40 2002/08/22 03:17:38 momjian Exp $
|
||||||
|
|
||||||
PostgreSQL Programmer's Guide.
|
PostgreSQL Programmer's Guide.
|
||||||
-->
|
-->
|
||||||
@ -29,7 +29,6 @@ PostgreSQL Programmer's Guide.
|
|||||||
|
|
||||||
&libpq;
|
&libpq;
|
||||||
&lobj;
|
&lobj;
|
||||||
&libpqpp;
|
|
||||||
&libpgtcl;
|
&libpgtcl;
|
||||||
&libpgeasy;
|
&libpgeasy;
|
||||||
&ecpg;
|
&ecpg;
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user