database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-30 11:03:19 +03:00
Code Activity

Significant updates from Vince Vielhaber.

Browse Source
This commit is contained in:
Thomas G. Lockhart
1999-05-27 15:48:14 +00:00
parent b04b01638b
commit 7d831b5379
1 changed files with 430 additions and 293 deletions
Download Patch File Download Diff File Expand all files Collapse all files

723
doc/src/sgml/libpq++.sgml
View File

@ -1,4 +1,4 @@
<chapter id="libpqplusplus"> <chapter id="libpqplusplus">
<title>libpq C++ Binding</title> <title>libpq C++ Binding</title>
<para> <para>
@ -20,7 +20,7 @@
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 the future it should behave much like the C++ file
streams streams
<literal>cin</literal>, <literal>cin</literal>,
<literal>cout</literal> <literal>cout</literal>
@ -40,13 +40,10 @@
</para> </para>
<sect1> <sect1>
<title>Control and Initialization</title> <title>Control and Initialization</title>
<para> <sect2>
</para> <title>Environment Variables</title>
<sect2>
<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
@ -54,245 +51,257 @@
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 endterm="libpq" linkend="libpq-envars"> for a complete
list of available connection options. list of available connection options.
</para> </para>
</note> </note>
</para> </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.
<note>
<para>
<filename>libpq++</filename> uses only environment variables or PQconnectdb
conninfo style strings.
</para>
</note>
<ItemizedList> <itemizedlist>
<ListItem> <listitem>
<Para> <para>
<Acronym>PGHOST</Acronym> sets the default server name. <envar>PGHOST</envar> 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 <envar>PGPORT</envar> 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 <envar>PGDATABASE</envar> sets the default
<ProductName>Postgres</ProductName> database name. <productname>Postgres</productname> database name.
</Para> </para>
</ListItem> </listitem>
<ListItem> <listitem>
<Para> <para>
<Acronym>PGUSER</Acronym> <envar>PGUSER</envar>
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> <envar>PGPASSWORD</envar>
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 <envar>PGREALM</envar> 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> <envar>PGREALM</envar> 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 <envar>PGOPTIONS</envar> 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 <envar>PGTTY</envar> 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> <envar>PGDATESTYLE</envar>
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> <envar>PGTZ</envar>
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>
<ListItem>
<Para>
<Acronym>PGGEQO</Acronym>
sets the default mode for the genetic optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGRPLANS</Acronym>
sets the default mode to allow or disable right-sided plans in the optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGCOSTHEAP</Acronym>
sets the default cost for heap searches for the optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGCOSTINDEX</Acronym>
sets the default cost for indexed searches for the optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGQUERY_LIMIT</Acronym>
sets the maximum number of rows returned by a query.
</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>
<title>Database Connection Functions</title>
<para>
</para>
<sect2>
<title>Database Environment Class: <classname>PGenv</classname></title>
<para>
The database environment class provides C++ objects for manipulating the
above environment variables:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<function>PGenv</function> <envar>PGGEQO</envar>
creates an environment for the running program. sets the default mode for the genetic optimizer.
</para>
<synopsis> </listitem>
PGenv() <listitem>
PGenv(char* auth, char* host, char* port, char* option, char* tty) <para>
</synopsis> <envar>PGRPLANS</envar>
sets the default mode to allow or disable right-sided plans in the optimizer.
The first form of this object's constructor sets up the defaults for </para>
the program from the environment variables listed above. </listitem>
The second allows the programmer to hardcode the values into the program. <listitem>
The values of the second form relate directly to the environment variables <para>
above. <envar>PGCOSTHEAP</envar>
sets the default cost for heap searches for the optimizer.
</para>
</listitem>
<listitem>
<para>
<envar>PGCOSTINDEX</envar>
sets the default cost for indexed searches for the optimizer.
</para>
</listitem>
<listitem>
<para>
<envar>PGQUERY_LIMIT</envar>
sets the maximum number of rows returned by a query.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
</sect2>
<sect2>
<title>Database Class: <classname>PGdatabase</classname></title>
<para> <para>
The database class is a provides C++ objects that have a connection Refer to the <command>SET</command> <acronym>SQL</acronym> command
to a backend server. To create such an object one first need for information on correct values for these environment variables.
</para>
</sect2>
</sect1>
<sect1>
<title>libpq++ Classes</title>
<para></para>
<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 apropriate environment for the backend to access. the apropriate environment for the backend to access.
The following constructors deal with making a connection to a backend The following constructors deal with making a connection to a backend
server from a C++ program. server from a C++ program.
<itemizedlist>
<listitem>
<para>
<function>PGdatabase</function>
makes a new connection to a backend database server.
<synopsis>
PGdatabase(PGenv *env, char *dbName)
</synopsis>
After a PGdatabase has been created it should be checked to make sure
the connection to the database succeded before sending
queries to the object. This can easily be done by
retrieving the current status of the PGdatabase object with the
<function>status</function> method.
</para>
</listitem>
<listitem>
<para>
<function>status</function>
returns the status of the PGdatabase object.
<synopsis>
ConnStatus PGdatabase::status()
</synopsis>
The following values are allowed:
<simplelist>
<member>
CONNECTION_OK
</member>
<member>
CONNECTION_BAD
</member>
</simplelist>
</para>
</listitem>
</itemizedlist>
</para> </para>
</sect2> </sect2>
</sect1> </sect1>
<sect1> <sect1>
<title>Query Execution Functions</title> <title>Database Connection Functions</title>
<para> <para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::exec</function> <function>PgConnection</function>
submits a query to <productname>Postgres</productname> makes a new connection to a backend database server.
and returns result status. In case of an error
<function>PGdatabase::errormessage</function>
can be used to get more information on the error.
<synopsis> <synopsis>
void ExecStatusType PGdatabase::exec(char *query); PgConnection::PgConnection(const char *conninfo)
</synopsis> </synopsis>
Although typically called from one of the access classes, a connection to
The following status results can be expected: a backend server is possible by creating a PgConnection object.
</para>
</listitem>
<listitem>
<para>
<function>ConnectionBad</function>
returns whether or not the connection to the backend server succeeded or
failed.
<synopsis>
int PgConnection::ConnectionBad()
</synopsis>
Returns TRUE if the connection failed.
</para>
</listitem>
<listitem>
<para>
<function>Status</function>
returns the status of the connection to the backend server.
<synopsis>
ConnStatusType PgConnection::Status()
</synopsis>
Returns either CONNECTION_OK or CONNECTION_BAD depending on the state
of the connection.
</para>
</listitem>
<listitem>
<para>
<function>PgDatabase</function>
makes a new connection to a backend database server.
<synopsis>
PgDatabase(const char *conninfo)
</synopsis>
After a PgDatabase has been created it should be checked to make sure
the connection to the database succeded before sending
queries to the object. This can easily be done by
retrieving the current status of the PgDatabase 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 PQnotifies() for details.
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
<sect1>
<title>Query Execution Functions</title>
<para>
<itemizedlist>
<listitem>
<para>
<function>Exec</function>
Sends a query to the backend server. It's probably more desirable to
use one of the next two functions.
<synopsis>
ExecStatusType PgConnection::Exec(const char* query)
</synopsis>
Returns the result of the query. The following status results can be expected:
<simplelist> <simplelist>
<member> <member>
@ -322,133 +331,249 @@
</simplelist> </simplelist>
</para> </para>
</listitem> </listitem>
</itemizedlist>
</para>
<para>
If the result status is PGRES_TUPLES_OK, then the following routines can
be used to retrieve the tuples returned by the query.
<itemizedlist>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::ntuples</function> <function>ExecCommandOk</function>
returns the number of tuples (instances) in the query result. Sends a command query to the backend server.
<synopsis> <synopsis>
int PGdatabase::ntuples() int PgConnection::ExecCommandOk(const char *query)
</synopsis> </synopsis>
Returns TRUE if the command query succeeds.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::nfields</function> <function>ExecTuplesOk</function>
returns the number of fields (attributes) in the query result. Sends a command query to the backend server.
<synopsis> <synopsis>
int PGdatabase::nfields() int PgConnection::ExecTuplesOk(const char *query)
</synopsis>
Returns TRUE if the command query succeeds and there are tuples to be retrieved.
</para>
</listitem>
<listitem>
<para>
<function>ErrorMessage</function>
Returns the last error message text.
<synopsis>
const char *PgConnection::ErrorMessage()
</synopsis> </synopsis>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::fieldname</function> <function>Tuples</function>
returns the field (attribute) name associated with the given field index. Returns the number of tuples (instances) in the query result.
Field indices start at zero.
<synopsis> <synopsis>
char* PGdatabase::fieldname(int field_index) int PgDatabase::Tuples()
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PGdatabase::fieldnum</function>
returns the field (attribute) index associated with the given field name.
<synopsis>
int PGdatabase::fieldnum(char* field_name)
</synopsis> </synopsis>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::fieldtype</function> <function>Fields</function>
returns the field type of associated with the given field index or name. Returns the number of fields (attributes) in each tuple of the query result.
The integer returned is an internal coding of the type. Field indices start
at zero.
<synopsis> <synopsis>
Oid PGdatabase::fieldtype(int field_index) int PgDatabase::Fields()
Oid PGdatabase::fieldtype(char* field_name)
</synopsis> </synopsis>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::fieldsize</function> <function>FieldName</function>
returns the size in bytes of the field associated with the given field Returns the field (attribute) name associated with the given field index.
index or name. If the size returned is -1, the field is a variable length Field indices start at 0.
field. Field indices start at zero.
<synopsis> <synopsis>
int2 PGdatabase::fieldsize(int field_index) const char *PgDatabase::FieldName(int field_num)
int2 PGdatabase::fieldsize(char* field_name)
</synopsis> </synopsis>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::getvalue</function> <function>FieldNum</function>
returns the field (attribute) value. For most queries, the values PQfnumber Returns the field (attribute) index associated with
returned by the given field name.
<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
explicitly copy the value into other storage if it is to be used past
the next query.
<synopsis> <synopsis>
char* PGdatabase::getvalue(int tup_num, int field_index) int PgDatabase::FieldNum(const char* field_name)
char* PGdatabase::getvalue(int tup_num, char* field_name) </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)
</synopsis> </synopsis>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::getlength</function> <function>FieldType</function>
returns the length of a field (attribute) in bytes. If the field Returns the field type associated with the given field name. The
is a <literal>struct varlena</literal>, integer returned is an internal coding of the type. Field indices
the length returned here does start at 0.
<emphasis>not</emphasis>
include the size field of the <literal>varlena</literal>,
i.e., it is 4 bytes less.
<synopsis> <synopsis>
int PGdatabase::getlength(int tup_num, int field_index) Oid PgDatabase::FieldType(const char* field_name)
int PGdatabase::getlength(int tup_num, char* field_name)
</synopsis> </synopsis>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::printtuples</function> <function>FieldSize</function>
prints out all the tuples and, optionally, the attribute names to the Returns the size in bytes of the field associated with the given
specified output stream. field index. Field indices start at 0.
<synopsis> <synopsis>
void PGdatabase::printtuples( short PgDatabase::FieldSize(int field_num)
FILE* fout, /* output stream */ </synopsis>
int printAttName,/* print attribute names or not*/ Returns the space allocated for this field in a database tuple given
int terseOutput, /* delimiter bars or not?*/ the field number. In other words the size of the server's binary
int width /* width of column, variable width if 0*/ 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>
short PgDatabase::FieldSize(const char *field_name)
</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>
<listitem>
<para>
<function>GetValue</function>
Returns a single field (attribute) value of one tuple of a PGresult.
Tuple and field indices start at 0.
<synopsis>
const char *PgDatabase::GetValue(int tup_num, int field_num)
</synopsis>
For most queries, the value returned by GetValue is a null-terminated
ASCII string representation of the attribute value. But if BinaryTuples()
is TRUE, the value returned by GetValue 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 GetValue points to storage that is part of the
PGresult 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 PGresult structure itself. BinaryTuples() is not yet implemented.
</para>
</listitem>
<listitem>
<para>
<function>GetValue</function>
Returns a single field (attribute) value of one tuple of a PGresult.
Tuple and field indices start at 0.
<synopsis>
const char *PgDatabase::GetValue(int tup_num, const char *field_name)
</synopsis>
For most queries, the value returned by GetValue is a null-terminated
ASCII string representation of the attribute value. But if BinaryTuples()
is TRUE, the value returned by GetValue 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 GetValue points to storage that is part of the
PGresult 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 PGresult structure itself. BinaryTuples() is not yet implemented.
</para>
</listitem>
<listitem>
<para>
<function>GetLength</function>
Returns the length of a field (attribute) in bytes. Tuple and field
indices start at 0.
<synopsis>
int PgDatabase::GetLength(int tup_num, int field_num)
</synopsis>
This is the actual data length for the particular data value, that
is the size of the object pointed to by GetValue. Note that for
ASCII-represented values, this size has little to do with the binary
size reported by PQfsize.
</para>
</listitem>
<listitem>
<para>
<function>GetLength</function>
Returns the length of a field (attribute) in bytes. Tuple and field
indices start at 0.
<synopsis>
int PgDatabase::GetLength(int tup_num, const char* field_name)
</synopsis>
This is the actual data length for the particular data value, that
is the size of the object pointed to by GetValue. Note that for
ASCII-represented values, this size has little to do with the binary
size reported by PQfsize.
</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, int fillAlign = 1,
const char* fieldSep = "|",int printHeader = 1, int quiet = 0)
</synopsis>
</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, int printAttName = 1,
int terseOutput = 0, int width = 0)
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>GetLine</function>
<synopsis>
int PgDatabase::GetLine(char* string, int length)
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PutLine</function>
<synopsis>
void PgDatabase::PutLine(const char* string)
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>OidStatus</function>
<synopsis>
const char *PgDatabase::OidStatus()
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>EndCopy</function>
<synopsis>
int PgDatabase::EndCopy()
</synopsis> </synopsis>
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
</sect1> </sect1>
<sect1> <sect1>
<title>Asynchronous Notification</title> <title>Asynchronous Notification</title>
@ -483,26 +608,26 @@
The <filename>libpq++</filename> application The <filename>libpq++</filename> application
must poll the backend to see if there is any pending notification must poll the backend to see if there is any pending notification
information. After the execution of a query, a frontend may call information. After the execution of a query, a frontend may call
<function>PGdatabase::notifies</function> <function>PgDatabase::Notifies</function>
to see if any notification data is currently available from the backend. to see if any notification data is currently available from the backend.
<function>PGdatabase::notifies</function> <function>PgDatabase::Notifies</function>
returns the notification from a list of unhandled notifications from the returns the notification from a list of unhandled notifications from the
backend. The function eturns NULL if there is no pending notifications from the backend. The function eturns NULL if there is no pending notifications from the
backend. backend.
<function>PGdatabase::notifies</function> <function>PgDatabase::Notifies</function>
behaves like the popping of a stack. Once a notification is returned behaves like the popping of a stack. Once a notification is returned
from <function>PGdatabase::notifies</function>, from <function>PgDatabase::Notifies</function>,
it is considered handled and will be removed from the list of it is considered handled and will be removed from the list of
notifications. notifications.
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::notifies</function> <function>PgDatabase::Notifies</function>
retrieves pending notifications from the server. retrieves pending notifications from the server.
<synopsis> <synopsis>
PGnotify* PGdatabase::notifies() PGnotify* PgDatabase::Notifies()
</synopsis> </synopsis>
</para> </para>
</listitem> </listitem>
@ -513,7 +638,6 @@
notification. notification.
</para> </para>
</sect1> </sect1>
<sect1> <sect1>
<title>Functions Associated with the COPY Command</title> <title>Functions Associated with the COPY Command</title>
@ -528,13 +652,13 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::getline</function> <function>PgDatabase::GetLine</function>
reads a newline-terminated line of characters (transmitted by the reads a newline-terminated line of characters (transmitted by the
backend server) into a buffer backend server) into a buffer
<replaceable class="parameter">string</replaceable> <replaceable class="parameter">string</replaceable>
of size <replaceable class="parameter">length</replaceable>. of size <replaceable class="parameter">length</replaceable>.
<synopsis> <synopsis>
int PGdatabase::getline(char* string, int length) int PgDatabase::GetLine(char* string, int length)
</synopsis> </synopsis>
</para> </para>
<para> <para>
@ -550,7 +674,7 @@
character. character.
</para> </para>
<para> <para>
<function>PGdatabase::getline</function> <function>PgDatabase::GetLine</function>
returns EOF at end of file, 0 if the entire line has been read, and 1 if the returns EOF at end of file, 0 if the entire line has been read, and 1 if the
buffer is full but the terminating newline has not yet been read. buffer is full but the terminating newline has not yet been read.
</para> </para>
@ -563,16 +687,16 @@
that are more than that are more than
<literal><replaceable class="parameter">length</replaceable>-1</literal> <literal><replaceable class="parameter">length</replaceable>-1</literal>
characters long, the application must be sure to check the return characters long, the application must be sure to check the return
value of <function>PGdatabase::getline</function> very carefully. value of <function>PgDatabase::GetLine</function> very carefully.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::putline</function> <function>PgDatabase::PutLine</function>
Sends a null-terminated <replaceable class="parameter">string</replaceable> Sends a null-terminated <replaceable class="parameter">string</replaceable>
to the backend server. to the backend server.
<synopsis> <synopsis>
void PGdatabase::putline(char* string) void PgDatabase::PutLine(char* string)
</synopsis> </synopsis>
</para> </para>
<para> <para>
@ -582,18 +706,18 @@
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::endcopy</function> <function>PgDatabase::EndCopy</function>
syncs with the backend. syncs with the backend.
<synopsis> <synopsis>
int PGdatabase::endcopy() int PgDatabase::EndCopy()
</synopsis> </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.
@ -608,7 +732,7 @@
As an example: As an example:
<programlisting> <programlisting>
PGdatabase data; PgDatabase data;
data.exec("create table foo (a int4, b char16, d float8)"); data.exec("create table foo (a int4, b char16, d float8)");
data.exec("copy foo from stdin"); data.exec("copy foo from stdin");
data.putline("3\etHello World\et4.5\en"); data.putline("3\etHello World\et4.5\en");
@ -620,7 +744,6 @@
</programlisting> </programlisting>
</para> </para>
</sect1> </sect1>
<sect1> <sect1>
<title>Caveats</title> <title>Caveats</title>
@ -628,8 +751,22 @@
The query buffer is 8192 bytes long, and queries over that length will The query buffer is 8192 bytes long, and queries over that length will
be silently truncated. be silently truncated.
</para> </para>
<para>
The <classname>PGlobj</classname> class is largely untested. Use with caution.
</para>
</sect1> </sect1>
</chapter> </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:
-->