database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-27 12:41:57 +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
<productname>Postgres</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 to the <productname>Postgres</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
@ -26,7 +26,7 @@ streams
<literal>cout</literal>
and
<literal>cerr</literal>.
</para>
<para>
This chapter is based on the documentation
for the <filename>libpq</filename> C library. Three
@ -37,7 +37,7 @@ There are several examples of <filename>libpq++</filename>
applications in
<filename>src/libpq++/examples</filename>, including the source
code for the three examples in this chapter.
</para>
<sect1>
<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
values for an environment and to avoid hard-coding database names into
an application program:
<note>
<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.
</para>
</note>
</para>
<Para>
The following environment variables can be used to select default
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
for information on correct values for these environment variables.
</Para>
</sect2>
</sect1>
<sect1>
<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 values of the second form relate directly to the environment variables
above.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
<sect2>
<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
retrieving the current status of the PGdatabase object with the
<function>status</function> method.
</para>
</listitem>
<listitem>
<para>
<function>status</function>
@ -255,12 +260,17 @@ The following values are allowed:
<simplelist>
<member>
CONNECTION_OK
</member>
<member>
CONNECTION_BAD
</member>
</simplelist>
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
<sect1>
<title>Query Execution Functions</title>
@ -282,24 +292,33 @@ The following status results can be expected:
<simplelist>
<member>
PGRES_EMPTY_QUERY
</member>
<member>
PGRES_COMMAND_OK, if the query was a command
</member>
<member>
PGRES_TUPLES_OK, if the query successfully returned tuples
</member>
<member>
PGRES_COPY_OUT
</member>
<member>
PGRES_COPY_IN
</member>
<member>
PGRES_BAD_RESPONSE, if an unexpected response was received
</member>
<member>
PGRES_NONFATAL_ERROR
</member>
<member>
PGRES_FATAL_ERROR
</member>
</simplelist>
</para>
</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.
@ -312,7 +331,8 @@ returns the number of tuples (instances) in the query result.
<synopsis>
int PGdatabase::ntuples()
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PGdatabase::nfields</function>
@ -320,7 +340,8 @@ returns the number of fields (attributes) in the query result.
<synopsis>
int PGdatabase::nfields()
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PGdatabase::fieldname</function>
@ -329,7 +350,8 @@ Field indices start at zero.
<synopsis>
char* PGdatabase::fieldname(int field_index)
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PGdatabase::fieldnum</function>
@ -337,7 +359,8 @@ returns the field (attribute) index associated with the given field name.
<synopsis>
int PGdatabase::fieldnum(char* field_name)
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PGdatabase::fieldtype</function>
@ -348,7 +371,8 @@ at zero.
Oid PGdatabase::fieldtype(int field_index)
Oid PGdatabase::fieldtype(char* field_name)
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PGdatabase::fieldsize</function>
@ -359,7 +383,8 @@ field. Field indices start at zero.
int2 PGdatabase::fieldsize(int field_index)
int2 PGdatabase::fieldsize(char* field_name)
</synopsis>
</para>
</listitem>
<listitem>
<para>
<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, char* field_name)
</synopsis>
</para>
</listitem>
<listitem>
<para>
<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, char* field_name)
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PGdatabase::printtuples</function>
@ -411,9 +438,11 @@ void PGdatabase::printtuples(
int width /* width of column, variable width if 0*/
);
</synopsis>
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
<sect1>
<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
named semaphore in fact does not need to have a corresponding relation
previously defined.
</para>
</note>
</para>
<para>
<filename>libpq++</filename> applications are notified whenever a
connected backend has
@ -468,13 +498,15 @@ 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>
<title>Functions Associated with the COPY Command</title>
@ -497,7 +529,7 @@ 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 (3)</function>,
@ -509,12 +541,12 @@ It is like
<function>gets (3)</function>,
however, in that it converts the terminating newline into a null
character.
</para>
<para>
<function>PGdatabase::getline</function>
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.
</para>
<para>
Notice that the application must check to see if a new line consists
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>
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>
@ -534,11 +567,12 @@ to the backend server.
<synopsis>
void PGdatabase::putline(char* string)
</synopsis>
</para>
<para>
The application must explicitly send a single period character (".")
to indicate to the backend that it has finished sending its data.
</para>
</listitem>
<listitem>
<para>
<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
the frontend. Upon return from this function, the backend is ready to
receive the next query.
</para>
<para>
The return value is 0 on successful completion, nonzero otherwise.
</para>
</listitem>
</itemizedlist>
</para>
<para>
As an example:
@ -576,15 +611,17 @@ data.putline(".\en");
data.endcopy();
</programlisting>
</para>
</sect1>
<sect1>
<title>Caveats</title>
<para>
The query buffer is 8192 bytes long, and queries over that length will
be silently truncated.
</para>
<para>
The <classname>PGlobj</classname> class is largely untested. Use with caution.
</para>
</sect1>
</chapter>