Skip to content

P
Postgres FD Implementation
Commit c701639b authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Updates from Vince Vielhaber are the first since 1997.

parent 045013cb
Show whitespace changes
Inline Side-by-side
Showing with 625 additions and 588 deletions
doc/src/sgml/libpq++.sgml
View file @ c701639b
<chapter id="libpqplusplus"> <chapter id="libpqplusplus">
<title>libpq C++ Binding</title> <title>libpq C++ Binding</title>
<para> <para>
<filename>libpq++</filename> is the C++ API to <filename>libpq++</filename> is the C++ API to
<productname>Postgres</productname>. <productname>Postgres</productname>.
<filename>libpq++</filename> is a set of classes which allow <filename>libpq++</filename> is a set of classes which allow
client programs to connect to the client programs to connect to the
<productname>Postgres</productname> backend server. These connections <productname>Postgres</productname> backend server. These connections
come in two forms: a Database Class and a Large Object class. come in two forms: a Database Class and a Large Object class.
</para>
<para> <para>
The Database Class is intended for manipulating a database. You can The Database Class is intended for manipulating a database. You can
send all sorts of SQL queries to the <productname>Postgres</productname> send all sorts of SQL queries to the <productname>Postgres</productname>
backend server and retrieve the responses of the server. backend server and retrieve the responses of the server.
</para>
<para> <para>
The Large Object Class is intended for manipulating a large object The Large Object Class is intended for manipulating a large object
in a database. Although a Large Object instance can send normal in a database. Although a Large Object instance can send normal
queries to the <productname>Postgres</productname> backend server queries to the <productname>Postgres</productname> backend server
it is only intended for simple it is only intended for simple
queries that do not return any data. A large object should be seen queries that do not return any data. A large object should be seen
as a file stream. In future it should behave much like the C++ file as a file stream. In future it should behave much like the C++ file
streams streams
<literal>cin</literal>, <literal>cin</literal>,
<literal>cout</literal> <literal>cout</literal>
and and
<literal>cerr</literal>. <literal>cerr</literal>.
</para>
<para> <para>
This chapter is based on the documentation This chapter is based on the documentation
for the <filename>libpq</filename> C library. Three for the <filename>libpq</filename> C library. Three
short programs are listed at the end of this section as examples of short programs are listed at the end of this section as examples of
<filename>libpq++</filename> programming <filename>libpq++</filename> programming
(though not necessarily of good programming). (though not necessarily of good programming).
There are several examples of <filename>libpq++</filename> There are several examples of <filename>libpq++</filename>
applications in applications in
<filename>src/libpq++/examples</filename>, including the source <filename>src/libpq++/examples</filename>, including the source
code for the three examples in this chapter. code for the three examples in this chapter.
</para>
<sect1> <sect1>
<title>Control and Initialization</title> <title>Control and Initialization</title>
<para> <para>
<sect2> <sect2>
<title>Environment Variables</title> <title>Environment Variables</title>
<para> <para>
The following environment variables can be used to set up default The following environment variables can be used to set up default
values for an environment and to avoid hard-coding database names into values for an environment and to avoid hard-coding database names into
an application program: an application program:
<note>
<note> <para>
<para> Refer to the <xref linkend="libpq-envars" endterm="libpq"> for a complete
Refer to the <xref linkend="libpq" endterm="libpq-envars"> for a complete list of available connection options.
list of available connection options. </para>
</note> </note>
</para>
<Para> <Para>
The following environment variables can be used to select default The following environment variables can be used to select default
connection parameter values, which will be used by PQconnectdb or connection parameter values, which will be used by PQconnectdb or
PQsetdbLogin if no value is directly specified by the calling code. PQsetdbLogin if no value is directly specified by the calling code.
These are useful to avoid hard-coding database names into simple These are useful to avoid hard-coding database names into simple
application programs. application programs.
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGHOST</Acronym> sets the default server name. <Acronym>PGHOST</Acronym> sets the default server name.
If a non-zero-length string is specified, TCP/IP communication is used. If a non-zero-length string is specified, TCP/IP communication is used.
Without a host name, libpq will connect using a local Unix domain socket. Without a host name, libpq will connect using a local Unix domain socket.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGPORT</Acronym> sets the default port or local Unix domain socket <Acronym>PGPORT</Acronym> sets the default port or local Unix domain socket
file extension for communicating with the <ProductName>Postgres</ProductName> file extension for communicating with the <ProductName>Postgres</ProductName>
backend. backend.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGDATABASE</Acronym> sets the default <Acronym>PGDATABASE</Acronym> sets the default
<ProductName>Postgres</ProductName> database name. <ProductName>Postgres</ProductName> database name.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGUSER</Acronym> <Acronym>PGUSER</Acronym>
sets the username used to connect to the database and for authentication. sets the username used to connect to the database and for authentication.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGPASSWORD</Acronym> <Acronym>PGPASSWORD</Acronym>
sets the password used if the backend demands password authentication. sets the password used if the backend demands password authentication.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGREALM</Acronym> sets the Kerberos realm to use with <Acronym>PGREALM</Acronym> sets the Kerberos realm to use with
<ProductName>Postgres</ProductName>, <ProductName>Postgres</ProductName>,
if it is different from the local realm. If if it is different from the local realm. If
<Acronym>PGREALM</Acronym> is set, <ProductName>Postgres</ProductName> <Acronym>PGREALM</Acronym> is set, <ProductName>Postgres</ProductName>
applications will attempt applications will attempt
authentication with servers for this realm and use authentication with servers for this realm and use
separate ticket files to avoid conflicts with local separate ticket files to avoid conflicts with local
ticket files. This environment variable is only ticket files. This environment variable is only
used if Kerberos authentication is selected by the backend. used if Kerberos authentication is selected by the backend.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGOPTIONS</Acronym> sets additional runtime options for <Acronym>PGOPTIONS</Acronym> sets additional runtime options for
the <ProductName>Postgres</ProductName> backend. the <ProductName>Postgres</ProductName> backend.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGTTY</Acronym> sets the file or tty on which debugging <Acronym>PGTTY</Acronym> sets the file or tty on which debugging
messages from the backend server are displayed. messages from the backend server are displayed.
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</Para> </Para>
<Para> <Para>
The following environment variables can be used to specify user-level default The following environment variables can be used to specify user-level default
behavior for every Postgres session: behavior for every Postgres session:
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGDATESTYLE</Acronym> <Acronym>PGDATESTYLE</Acronym>
sets the default style of date/time representation. sets the default style of date/time representation.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGTZ</Acronym> <Acronym>PGTZ</Acronym>
sets the default time zone. sets the default time zone.
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</Para> </Para>
<Para> <Para>
The following environment variables can be used to specify default internal The following environment variables can be used to specify default internal
behavior for every Postgres session: behavior for every Postgres session:
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGGEQO</Acronym> <Acronym>PGGEQO</Acronym>
sets the default mode for the genetic optimizer. sets the default mode for the genetic optimizer.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGRPLANS</Acronym> <Acronym>PGRPLANS</Acronym>
sets the default mode to allow or disable right-sided plans in the optimizer. sets the default mode to allow or disable right-sided plans in the optimizer.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGCOSTHEAP</Acronym> <Acronym>PGCOSTHEAP</Acronym>
sets the default cost for heap searches for the optimizer. sets the default cost for heap searches for the optimizer.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGCOSTINDEX</Acronym> <Acronym>PGCOSTINDEX</Acronym>
sets the default cost for indexed searches for the optimizer. sets the default cost for indexed searches for the optimizer.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGQUERY_LIMIT</Acronym> <Acronym>PGQUERY_LIMIT</Acronym>
sets the maximum number of rows returned by a query. sets the maximum number of rows returned by a query.
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</Para> </Para>
<Para> <Para>
Refer to the <command>SET</command> <acronym>SQL</acronym> command Refer to the <command>SET</command> <acronym>SQL</acronym> command
for information on correct values for these environment variables. for information on correct values for these environment variables.
</Para> </Para>
</sect2>
<sect1> </sect1>
<title>Database Connection Functions</title> <sect1>
<title>Database Connection Functions</title>
<para>
<para>
<sect2>
<title>Database Environment Class: <classname>PGenv</classname></title> <sect2>
<title>Database Environment Class: <classname>PGenv</classname></title>
<para>
The database environment class provides C++ objects for manipulating the <para>
above environment variables: The database environment class provides C++ objects for manipulating the
above environment variables:
<itemizedlist>
<listitem> <itemizedlist>
<para> <listitem>
<function>PGenv</function> <para>
creates an environment for the running program. <function>PGenv</function>
creates an environment for the running program.
<synopsis>
PGenv() <synopsis>
PGenv(char* auth, char* host, char* port, char* option, char* tty) PGenv()
</synopsis> PGenv(char* auth, char* host, char* port, char* option, char* tty)
</synopsis>
The first form of this object's constructor sets up the defaults for
the program from the environment variables listed above. The first form of this object's constructor sets up the defaults for
The second allows the programmer to hardcode the values into the program. the program from the environment variables listed above.
The values of the second form relate directly to the environment variables The second allows the programmer to hardcode the values into the program.
above. The values of the second form relate directly to the environment variables
above.
</itemizedlist> </para>
</listitem>
<sect2> </itemizedlist>
<title>Database Class: <classname>PGdatabase</classname></title> </para>
</sect2>
<para>
The database class is a provides C++ objects that have a connection <sect2>
to a backend server. To create such an object one first need <title>Database Class: <classname>PGdatabase</classname></title>
the apropriate environment for the backend to access.
The following constructors deal with making a connection to a backend <para>
server from a C++ program. The database class is a provides C++ objects that have a connection
to a backend server. To create such an object one first need
<itemizedlist> the apropriate environment for the backend to access.
<listitem> The following constructors deal with making a connection to a backend
<para> server from a C++ program.
<function>PGdatabase</function>
makes a new connection to a backend database server. <itemizedlist>
<synopsis> <listitem>
PGdatabase(PGenv *env, char *dbName) <para>
</synopsis> <function>PGdatabase</function>
After a PGdatabase has been created it should be checked to make sure makes a new connection to a backend database server.
the connection to the database succeded before sending <synopsis>
queries to the object. This can easily be done by PGdatabase(PGenv *env, char *dbName)
retrieving the current status of the PGdatabase object with the </synopsis>
<function>status</function> method. After a PGdatabase has been created it should be checked to make sure
the connection to the database succeded before sending
<listitem> queries to the object. This can easily be done by
<para> retrieving the current status of the PGdatabase object with the
<function>status</function> <function>status</function> method.
returns the status of the PGdatabase object. </para>
<synopsis> </listitem>
ConnStatus PGdatabase::status() <listitem>
</synopsis> <para>
<function>status</function>
The following values are allowed: returns the status of the PGdatabase object.
<simplelist> <synopsis>
<member> ConnStatus PGdatabase::status()
CONNECTION_OK </synopsis>
<member>
CONNECTION_BAD The following values are allowed:
</simplelist> <simplelist>
<member>
</itemizedlist> CONNECTION_OK
</member>
<sect1> <member>
<title>Query Execution Functions</title> CONNECTION_BAD
</member>
<para> </simplelist>
<itemizedlist> </para>
<listitem> </listitem>
<para> </itemizedlist>
<function>PGdatabase::exec</function> </para>
submits a query to <productname>Postgres</productname> </sect2>
and returns result status. In case of an error </sect1>
<function>PGdatabase::errormessage</function> <sect1>
can be used to get more information on the error. <title>Query Execution Functions</title>
<synopsis>
void ExecStatusType PGdatabase::exec(char *query); <para>
</synopsis> <itemizedlist>
<listitem>
The following status results can be expected: <para>
<function>PGdatabase::exec</function>
<simplelist> submits a query to <productname>Postgres</productname>
<member> and returns result status. In case of an error
PGRES_EMPTY_QUERY <function>PGdatabase::errormessage</function>
<member> can be used to get more information on the error.
PGRES_COMMAND_OK, if the query was a command <synopsis>
<member> void ExecStatusType PGdatabase::exec(char *query);
PGRES_TUPLES_OK, if the query successfully returned tuples </synopsis>
<member>
PGRES_COPY_OUT The following status results can be expected:
<member>
PGRES_COPY_IN <simplelist>
<member> <member>
PGRES_BAD_RESPONSE, if an unexpected response was received PGRES_EMPTY_QUERY
<member> </member>
PGRES_NONFATAL_ERROR <member>
<member> PGRES_COMMAND_OK, if the query was a command
PGRES_FATAL_ERROR </member>
</simplelist> <member>
PGRES_TUPLES_OK, if the query successfully returned tuples
</itemizedlist> </member>
<member>
<para> PGRES_COPY_OUT
If the result status is PGRES_TUPLES_OK, then the following routines can </member>
be used to retrieve the tuples returned by the query. <member>
PGRES_COPY_IN
<itemizedlist> </member>
<listitem> <member>
<para> PGRES_BAD_RESPONSE, if an unexpected response was received
<function>PGdatabase::ntuples</function> </member>
returns the number of tuples (instances) in the query result. <member>
<synopsis> PGRES_NONFATAL_ERROR
int PGdatabase::ntuples() </member>
</synopsis> <member>
PGRES_FATAL_ERROR
<listitem> </member>
<para> </simplelist>
<function>PGdatabase::nfields</function> </para>
returns the number of fields (attributes) in the query result. </listitem>
<synopsis> </itemizedlist>
int PGdatabase::nfields() </para>
</synopsis> <para>
If the result status is PGRES_TUPLES_OK, then the following routines can
<listitem> be used to retrieve the tuples returned by the query.
<para>
<function>PGdatabase::fieldname</function> <itemizedlist>
returns the field (attribute) name associated with the given field index. <listitem>
Field indices start at zero. <para>
<synopsis> <function>PGdatabase::ntuples</function>
char* PGdatabase::fieldname(int field_index) returns the number of tuples (instances) in the query result.
</synopsis> <synopsis>
int PGdatabase::ntuples()
<listitem> </synopsis>
<para> </para>
<function>PGdatabase::fieldnum</function> </listitem>
returns the field (attribute) index associated with the given field name. <listitem>
<synopsis> <para>
int PGdatabase::fieldnum(char* field_name) <function>PGdatabase::nfields</function>
</synopsis> returns the number of fields (attributes) in the query result.
<synopsis>
<listitem> int PGdatabase::nfields()
<para> </synopsis>
<function>PGdatabase::fieldtype</function> </para>
returns the field type of associated with the given field index or name. </listitem>
The integer returned is an internal coding of the type. Field indices start <listitem>
at zero. <para>
<synopsis> <function>PGdatabase::fieldname</function>
Oid PGdatabase::fieldtype(int field_index) returns the field (attribute) name associated with the given field index.
Oid PGdatabase::fieldtype(char* field_name) Field indices start at zero.
</synopsis> <synopsis>
char* PGdatabase::fieldname(int field_index)
<listitem> </synopsis>
<para> </para>
<function>PGdatabase::fieldsize</function> </listitem>
returns the size in bytes of the field associated with the given field <listitem>
index or name. If the size returned is -1, the field is a variable length <para>
field. Field indices start at zero. <function>PGdatabase::fieldnum</function>
<synopsis> returns the field (attribute) index associated with the given field name.
int2 PGdatabase::fieldsize(int field_index) <synopsis>
int2 PGdatabase::fieldsize(char* field_name) int PGdatabase::fieldnum(char* field_name)
</synopsis> </synopsis>
</para>
<listitem> </listitem>
<para> <listitem>
<function>PGdatabase::getvalue</function> <para>
returns the field (attribute) value. For most queries, the values <function>PGdatabase::fieldtype</function>
returned by returns the field type of associated with the given field index or name.
<function>PGdatabase::getvalue</function> The integer returned is an internal coding of the type. Field indices start
is a null-terminated ASCII string representation at zero.
of the attribute value. If the query was a result of a <synopsis>
<parameter>BINARY</parameter> Oid PGdatabase::fieldtype(int field_index)
cursor, then the values returned by Oid PGdatabase::fieldtype(char* field_name)
<function>PGdatabase::getvalue</function> </synopsis>
is the binary representation of the type in the internal format of the </para>
backend server. It is the programmer's responsibility to cast and </listitem>
convert the data to the correct C++ type. The value return by <listitem>
<function>PGdatabase::getvalue</function> <para>
points to storage that is part of the <classname>PGdatabase</classname> structure. <function>PGdatabase::fieldsize</function>
returns the size in bytes of the field associated with the given field
index or name. If the size returned is -1, the field is a variable length
field. Field indices start at zero.
<synopsis>
int2 PGdatabase::fieldsize(int field_index)
int2 PGdatabase::fieldsize(char* field_name)
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PGdatabase::getvalue</function>
returns the field (attribute) value. For most queries, the values
returned by
<function>PGdatabase::getvalue</function>
is a null-terminated ASCII string representation
of the attribute value. If the query was a result of a
<parameter>BINARY</parameter>
cursor, then the values returned by
<function>PGdatabase::getvalue</function>
is the binary representation of the type in the internal format of the
backend server. It is the programmer's responsibility to cast and
convert the data to the correct C++ type. The value return by
<function>PGdatabase::getvalue</function>
points to storage that is part of the <classname>PGdatabase</classname> structure.
One must One must
explicitly copy the value into other storage if it is to be used past explicitly copy the value into other storage if it is to be used past
the next query. the next query.
<synopsis> <synopsis>
char* PGdatabase::getvalue(int tup_num, int field_index) char* PGdatabase::getvalue(int tup_num, int field_index)
char* PGdatabase::getvalue(int tup_num, char* field_name) char* PGdatabase::getvalue(int tup_num, char* field_name)
</synopsis> </synopsis>
</para>
<listitem> </listitem>
<para> <listitem>
<function>PGdatabase::getlength</function> <para>
returns the length of a field (attribute) in bytes. If the field <function>PGdatabase::getlength</function>
is a <literal>struct varlena</literal>, returns the length of a field (attribute) in bytes. If the field
the length returned here does is a <literal>struct varlena</literal>,
<emphasis>not</emphasis> the length returned here does
include the size field of the <literal>varlena</literal>, <emphasis>not</emphasis>
i.e., it is 4 bytes less. include the size field of the <literal>varlena</literal>,
<synopsis> i.e., it is 4 bytes less.
int PGdatabase::getlength(int tup_num, int field_index) <synopsis>
int PGdatabase::getlength(int tup_num, char* field_name) int PGdatabase::getlength(int tup_num, int field_index)
</synopsis> int PGdatabase::getlength(int tup_num, char* field_name)
</synopsis>
<listitem> </para>
<para> </listitem>
<function>PGdatabase::printtuples</function> <listitem>
prints out all the tuples and, optionally, the attribute names to the <para>
specified output stream. <function>PGdatabase::printtuples</function>
<synopsis> prints out all the tuples and, optionally, the attribute names to the
void PGdatabase::printtuples( specified output stream.
<synopsis>
void PGdatabase::printtuples(
FILE* fout, /* output stream */ FILE* fout, /* output stream */
int printAttName,/* print attribute names or not*/ int printAttName,/* print attribute names or not*/
int terseOutput, /* delimiter bars or not?*/ int terseOutput, /* delimiter bars or not?*/
int width /* width of column, variable width if 0*/ int width /* width of column, variable width if 0*/
); );
</synopsis> </synopsis>
</para>
</itemizedlist> </listitem>
</itemizedlist>
<sect1> </para>
<title>Asynchronous Notification</title> </sect1>
<sect1>
<para> <title>Asynchronous Notification</title>
<productname>Postgres</productname> supports asynchronous notification
via the <command>LISTEN</command> and <command>NOTIFY</command> <para>
commands. A backend registers its interest in a particular semaphore <productname>Postgres</productname> supports asynchronous notification
with the <command>LISTEN</command> command. 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 All backends that are listening on a
particular named semaphore will be notified asynchronously when particular named semaphore will be notified asynchronously when
a <command>NOTIFY</command> of a <command>NOTIFY</command> of
that name is executed by another backend. No additional that name is executed by another backend. No additional
information is passed from the notifier to the listener. Thus, information is passed from the notifier to the listener. Thus,
typically, any actual data that needs to be communicated is transferred typically, any actual data that needs to be communicated is transferred
through the relation. through the relation.
<note> <note>
<para> <para>
In the past, the documentation has associated the names used for asyncronous In the past, the documentation has associated the names used for asyncronous
notification with relations or classes. However, there is in fact no notification with relations or classes. However, there is in fact no
direct linkage of the two concepts in the implementation, and the direct linkage of the two concepts in the implementation, and the
named semaphore in fact does not need to have a corresponding relation named semaphore in fact does not need to have a corresponding relation
previously defined. previously defined.
</note> </para>
</note>
<para> </para>
<filename>libpq++</filename> applications are notified whenever a <para>
connected backend has <filename>libpq++</filename> applications are notified whenever a
received an asynchronous notification. However, the communication from connected backend has
the backend to the frontend is not asynchronous. received an asynchronous notification. However, the communication from
The <filename>libpq++</filename> application the backend to the frontend is not asynchronous.
must poll the backend to see if there is any pending notification The <filename>libpq++</filename> application
information. After the execution of a query, a frontend may call must poll the backend to see if there is any pending notification
<function>PGdatabase::notifies</function> information. After the execution of a query, a frontend may call
to see if any notification data is currently available from the backend. <function>PGdatabase::notifies</function>
<function>PGdatabase::notifies</function> to see if any notification data is currently available from the backend.
returns the notification from a list of unhandled notifications from the <function>PGdatabase::notifies</function>
backend. The function eturns NULL if there is no pending notifications from the returns the notification from a list of unhandled notifications from the
backend. backend. The function eturns NULL if there is no pending notifications from the
<function>PGdatabase::notifies</function> backend.
behaves like the popping of a stack. Once a notification is returned <function>PGdatabase::notifies</function>
from <function>PGdatabase::notifies</function>, behaves like the popping of a stack. Once a notification is returned
it is considered handled and will be removed from the list of from <function>PGdatabase::notifies</function>,
notifications. it is considered handled and will be removed from the list of
notifications.
<itemizedlist>
<listitem> <itemizedlist>
<para> <listitem>
<function>PGdatabase::notifies</function> <para>
retrieves pending notifications from the server. <function>PGdatabase::notifies</function>
retrieves pending notifications from the server.
<synopsis>
PGnotify* PGdatabase::notifies() <synopsis>
</synopsis> PGnotify* PGdatabase::notifies()
</synopsis>
</itemizedlist> </para>
</listitem>
<para> </itemizedlist>
The second sample program gives an example of the use of asynchronous </para>
notification. <para>
The second sample program gives an example of the use of asynchronous
<sect1> notification.
<title>Functions Associated with the COPY Command</title> </para>
</sect1>
<para> <sect1>
The <command>copy</command> command in <productname>Postgres</productname> <title>Functions Associated with the COPY Command</title>
has options to read from or write to the network
connection used by <filename>libpq++</filename>. <para>
Therefore, functions are necessary to The <command>copy</command> command in <productname>Postgres</productname>
access this network connection directly so applications may take full has options to read from or write to the network
advantage of this capability. connection used by <filename>libpq++</filename>.
Therefore, functions are necessary to
<itemizedlist> access this network connection directly so applications may take full
<listitem> advantage of this capability.
<para>
<function>PGdatabase::getline</function> <itemizedlist>
reads a newline-terminated line of characters (transmitted by the <listitem>
backend server) into a buffer <para>
<replaceable class="parameter">string</replaceable> <function>PGdatabase::getline</function>
of size <replaceable class="parameter">length</replaceable>. reads a newline-terminated line of characters (transmitted by the
<synopsis> backend server) into a buffer
int PGdatabase::getline(char* string, int length) <replaceable class="parameter">string</replaceable>
</synopsis> of size <replaceable class="parameter">length</replaceable>.
<synopsis>
<para> int PGdatabase::getline(char* string, int length)
Like the Unix system routine </synopsis>
<function>fgets (3)</function>, </para>
this routine copies up to <para>
<literal><replaceable class="parameter">length</replaceable>-1</literal> Like the Unix system routine
characters into <function>fgets (3)</function>,
<replaceable class="parameter">string</replaceable>. this routine copies up to
It is like <literal><replaceable class="parameter">length</replaceable>-1</literal>
<function>gets (3)</function>, characters into
however, in that it converts the terminating newline into a null <replaceable class="parameter">string</replaceable>.
character. It is like
<function>gets (3)</function>,
<para> however, in that it converts the terminating newline into a null
<function>PGdatabase::getline</function> character.
returns EOF at end of file, 0 if the entire line has been read, and 1 if the </para>
buffer is full but the terminating newline has not yet been read. <para>
<function>PGdatabase::getline</function>
<para> returns EOF at end of file, 0 if the entire line has been read, and 1 if the
Notice that the application must check to see if a new line consists buffer is full but the terminating newline has not yet been read.
of a single period ("."), which indicates that the backend </para>
server has finished sending the results of the <para>
<command>copy</command>. Notice that the application must check to see if a new line consists
Therefore, if the application ever expects to receive lines of a single period ("."), which indicates that the backend
that are more than server has finished sending the results of the
<literal><replaceable class="parameter">length</replaceable>-1</literal> <command>copy</command>.
characters long, the application must be sure to check the return Therefore, if the application ever expects to receive lines
value of <function>PGdatabase::getline</function> very carefully. that are more than
<literal><replaceable class="parameter">length</replaceable>-1</literal>
<listitem> characters long, the application must be sure to check the return
<para> value of <function>PGdatabase::getline</function> very carefully.
<function>PGdatabase::putline</function> </para>
Sends a null-terminated <replaceable class="parameter">string</replaceable> </listitem>
to the backend server. <listitem>
<synopsis> <para>
void PGdatabase::putline(char* string) <function>PGdatabase::putline</function>
</synopsis> Sends a null-terminated <replaceable class="parameter">string</replaceable>
to the backend server.
<para> <synopsis>
The application must explicitly send a single period character (".") void PGdatabase::putline(char* string)
to indicate to the backend that it has finished sending its data. </synopsis>
</para>
<listitem> <para>
<para> The application must explicitly send a single period character (".")
<function>PGdatabase::endcopy</function> to indicate to the backend that it has finished sending its data.
syncs with the backend. </para>
<synopsis> </listitem>
int PGdatabase::endcopy() <listitem>
</synopsis> <para>
<function>PGdatabase::endcopy</function>
syncs with the backend.
<synopsis>
int PGdatabase::endcopy()
</synopsis>
This function waits until the backend has This function waits until the backend has
finished processing the <command>copy</command>. finished processing the <command>copy</command>.
It should either be issued when the It should either be issued when the
last string has been sent to the backend using last string has been sent to the backend using
<function>PGdatabase::putline</function> <function>PGdatabase::putline</function>
or when the last string has been received from the backend using or when the last string has been received from the backend using
<function>PGdatabase::getline</function>. <function>PGdatabase::getline</function>.
It must be issued or the backend may get <quote>out of sync</quote> with 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 the frontend. Upon return from this function, the backend is ready to
receive the next query. receive the next query.
</para>
<para> <para>
The return value is 0 on successful completion, nonzero otherwise. The return value is 0 on successful completion, nonzero otherwise.
</para>
</itemizedlist> </listitem>
</itemizedlist>
<para> </para>
As an example: <para>
As an example:
<programlisting>
PGdatabase data; <programlisting>
data.exec("create table foo (a int4, b char16, d float8)"); PGdatabase data;
data.exec("copy foo from stdin"); data.exec("create table foo (a int4, b char16, d float8)");
data.putline("3\etHello World\et4.5\en"); data.exec("copy foo from stdin");
data.putline("4\etGoodbye World\et7.11\en"); data.putline("3\etHello World\et4.5\en");
\&... data.putline("4\etGoodbye World\et7.11\en");
data.putline(".\en"); \&...
data.endcopy(); data.putline(".\en");
data.endcopy();
</programlisting>
</programlisting>
<sect1> </para>
<title>Caveats</title> </sect1>
<sect1>
<para> <title>Caveats</title>
The query buffer is 8192 bytes long, and queries over that length will
be silently truncated. <para>
The query buffer is 8192 bytes long, and queries over that length will
<para> be silently truncated.
The <classname>PGlobj</classname> class is largely untested. Use with caution. </para>
<para>
The <classname>PGlobj</classname> class is largely untested. Use with caution.
</para>
</sect1>
</chapter> </chapter>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment