database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-26 01:22:12 +03:00
Code Activity

Updates from Vince Vielhaber are the first since 1997.

Browse Source
This commit is contained in:
Thomas G. Lockhart
1999-03-30 15:21:42 +00:00
parent 045013cba3
commit c701639b1f
1 changed files with 625 additions and 588 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -8,12 +8,12 @@
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
@ -26,7 +26,7 @@ streams
<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
@ -37,7 +37,7 @@ 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>
@ -50,13 +50,13 @@ code for the three examples in this chapter.
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" endterm="libpq-envars"> for a complete Refer to the <xref linkend="libpq-envars" endterm="libpq"> 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
@ -187,7 +187,8 @@ sets the maximum number of rows returned by a query.
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> <sect1>
<title>Database Connection Functions</title> <title>Database Connection Functions</title>
@ -216,8 +217,11 @@ the program from the environment variables listed above.
The second allows the programmer to hardcode the values into the program. The second allows the programmer to hardcode the values into the program.
The values of the second form relate directly to the environment variables The values of the second form relate directly to the environment variables
above. above.
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
</sect2>
<sect2> <sect2>
<title>Database Class: <classname>PGdatabase</classname></title> <title>Database Class: <classname>PGdatabase</classname></title>
@ -242,7 +246,8 @@ the connection to the database succeded before sending
queries to the object. This can easily be done by queries to the object. This can easily be done by
retrieving the current status of the PGdatabase object with the retrieving the current status of the PGdatabase object with the
<function>status</function> method. <function>status</function> method.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
<function>status</function> <function>status</function>
@ -255,12 +260,17 @@ The following values are allowed:
<simplelist> <simplelist>
<member> <member>
CONNECTION_OK CONNECTION_OK
</member>
<member> <member>
CONNECTION_BAD CONNECTION_BAD
</member>
</simplelist> </simplelist>
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
</sect2>
</sect1>
<sect1> <sect1>
<title>Query Execution Functions</title> <title>Query Execution Functions</title>
@ -282,24 +292,33 @@ The following status results can be expected:
<simplelist> <simplelist>
<member> <member>
PGRES_EMPTY_QUERY PGRES_EMPTY_QUERY
</member>
<member> <member>
PGRES_COMMAND_OK, if the query was a command PGRES_COMMAND_OK, if the query was a command
</member>
<member> <member>
PGRES_TUPLES_OK, if the query successfully returned tuples PGRES_TUPLES_OK, if the query successfully returned tuples
</member>
<member> <member>
PGRES_COPY_OUT PGRES_COPY_OUT
</member>
<member> <member>
PGRES_COPY_IN PGRES_COPY_IN
</member>
<member> <member>
PGRES_BAD_RESPONSE, if an unexpected response was received PGRES_BAD_RESPONSE, if an unexpected response was received
</member>
<member> <member>
PGRES_NONFATAL_ERROR PGRES_NONFATAL_ERROR
</member>
<member> <member>
PGRES_FATAL_ERROR PGRES_FATAL_ERROR
</member>
</simplelist> </simplelist>
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
<para> <para>
If the result status is PGRES_TUPLES_OK, then the following routines can If the result status is PGRES_TUPLES_OK, then the following routines can
be used to retrieve the tuples returned by the query. be used to retrieve the tuples returned by the query.
@ -312,7 +331,8 @@ returns the number of tuples (instances) in the query result.
<synopsis> <synopsis>
int PGdatabase::ntuples() int PGdatabase::ntuples()
</synopsis> </synopsis>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::nfields</function> <function>PGdatabase::nfields</function>
@ -320,7 +340,8 @@ returns the number of fields (attributes) in the query result.
<synopsis> <synopsis>
int PGdatabase::nfields() int PGdatabase::nfields()
</synopsis> </synopsis>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::fieldname</function> <function>PGdatabase::fieldname</function>
@ -329,7 +350,8 @@ Field indices start at zero.
<synopsis> <synopsis>
char* PGdatabase::fieldname(int field_index) char* PGdatabase::fieldname(int field_index)
</synopsis> </synopsis>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::fieldnum</function> <function>PGdatabase::fieldnum</function>
@ -337,7 +359,8 @@ returns the field (attribute) index associated with the given field name.
<synopsis> <synopsis>
int PGdatabase::fieldnum(char* field_name) int PGdatabase::fieldnum(char* field_name)
</synopsis> </synopsis>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::fieldtype</function> <function>PGdatabase::fieldtype</function>
@ -348,7 +371,8 @@ at zero.
Oid PGdatabase::fieldtype(int field_index) Oid PGdatabase::fieldtype(int field_index)
Oid PGdatabase::fieldtype(char* field_name) Oid PGdatabase::fieldtype(char* field_name)
</synopsis> </synopsis>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::fieldsize</function> <function>PGdatabase::fieldsize</function>
@ -359,7 +383,8 @@ field. Field indices start at zero.
int2 PGdatabase::fieldsize(int field_index) int2 PGdatabase::fieldsize(int field_index)
int2 PGdatabase::fieldsize(char* field_name) int2 PGdatabase::fieldsize(char* field_name)
</synopsis> </synopsis>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::getvalue</function> <function>PGdatabase::getvalue</function>
@ -383,7 +408,8 @@ the next query.
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> <listitem>
<para> <para>
<function>PGdatabase::getlength</function> <function>PGdatabase::getlength</function>
@ -397,7 +423,8 @@ i.e., it is 4 bytes less.
int PGdatabase::getlength(int tup_num, int field_index) int PGdatabase::getlength(int tup_num, int field_index)
int PGdatabase::getlength(int tup_num, char* field_name) int PGdatabase::getlength(int tup_num, char* field_name)
</synopsis> </synopsis>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::printtuples</function> <function>PGdatabase::printtuples</function>
@ -411,9 +438,11 @@ void PGdatabase::printtuples(
int width /* width of column, variable width if 0*/ int width /* width of column, variable width if 0*/
); );
</synopsis> </synopsis>
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
</sect1>
<sect1> <sect1>
<title>Asynchronous Notification</title> <title>Asynchronous Notification</title>
@ -437,8 +466,9 @@ 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.
</para>
</note> </note>
</para>
<para> <para>
<filename>libpq++</filename> applications are notified whenever a <filename>libpq++</filename> applications are notified whenever a
connected backend has connected backend has
@ -468,13 +498,15 @@ retrieves pending notifications from the server.
<synopsis> <synopsis>
PGnotify* PGdatabase::notifies() PGnotify* PGdatabase::notifies()
</synopsis> </synopsis>
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
<para> <para>
The second sample program gives an example of the use of asynchronous The second sample program gives an example of the use of asynchronous
notification. notification.
</para>
</sect1>
<sect1> <sect1>
<title>Functions Associated with the COPY Command</title> <title>Functions Associated with the COPY Command</title>
@ -497,7 +529,7 @@ 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>
Like the Unix system routine Like the Unix system routine
<function>fgets (3)</function>, <function>fgets (3)</function>,
@ -509,12 +541,12 @@ It is like
<function>gets (3)</function>, <function>gets (3)</function>,
however, in that it converts the terminating newline into a null however, in that it converts the terminating newline into a null
character. character.
</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> <para>
Notice that the application must check to see if a new line consists Notice that the application must check to see if a new line consists
of a single period ("."), which indicates that the backend of a single period ("."), which indicates that the backend
@ -525,7 +557,8 @@ 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>
</listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::putline</function> <function>PGdatabase::putline</function>
@ -534,11 +567,12 @@ to the backend server.
<synopsis> <synopsis>
void PGdatabase::putline(char* string) void PGdatabase::putline(char* string)
</synopsis> </synopsis>
</para>
<para> <para>
The application must explicitly send a single period character (".") The application must explicitly send a single period character (".")
to indicate to the backend that it has finished sending its data. to indicate to the backend that it has finished sending its data.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
<function>PGdatabase::endcopy</function> <function>PGdatabase::endcopy</function>
@ -556,12 +590,13 @@ or when the last string has been received from the backend using
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>
</listitem>
</itemizedlist> </itemizedlist>
</para>
<para> <para>
As an example: As an example:
@ -576,15 +611,17 @@ data.putline(".\en");
data.endcopy(); data.endcopy();
</programlisting> </programlisting>
</para>
</sect1>
<sect1> <sect1>
<title>Caveats</title> <title>Caveats</title>
<para> <para>
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. The <classname>PGlobj</classname> class is largely untested. Use with caution.
</para>
</sect1>
</chapter> </chapter>