mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2024-11-27 07:21:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Break up PQexec() result functions into subsections to be clearer. Both

Browse Source 
libpq and libpq++ reorganized.
This commit is contained in:
Bruce Momjian 2001-04-30 17:38:00 +00:00
parent cfc4d6c510
commit 60ba30d13a
2 changed files with 177 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:01 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.26 2001/04/30 17:38:00 momjian Exp $
-->
<chapter id="libpqplusplus">
@ -283,6 +283,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
<sect1 id="libpqpp-exec">
<title>Query Execution Functions</title>
<sect2 id="libpqpp-exec-main">
<title>Main Routines</title>
<para>
<itemizedlist>
<listitem>
@ -352,6 +355,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
</synopsis>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="libpqpp-exec-select-info">
<title>Retrieving SELECT Result Information</title>
<itemizedlist>
<listitem>
<para>
<function>Tuples</function>
@ -361,16 +371,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>CmdTuples</function>
Returns the number of rows affected after an INSERT, UPDATE or DELETE.
If the command was anything else, it returns -1.
<synopsis>
int PgDatabase::CmdTuples()
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>Fields</function>
@ -451,6 +451,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
variable size.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="libpqpp-exec-select-values">
<title>Retrieving SELECT Result Values</title>
<itemizedlist>
<listitem>
<para>
<function>GetValue</function>
@ -541,6 +549,39 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
</synopsis>
</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 INSERT, UPDATE or DELETE.
If the command was anything else, it returns -1.
<synopsis>
int PgDatabase::CmdTuples()
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>OidStatus</function>
<synopsis>
const char *PgDatabase::OidStatus()
</synopsis>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="libpqpp-exec-copy">
<title>Handling COPY Queries</title>
<itemizedlist>
<listitem>
<para>
<function>GetLine</function>
@ -557,14 +598,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>OidStatus</function>
<synopsis>
const char *PgDatabase::OidStatus()
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>EndCopy</function>
@ -575,6 +608,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
</listitem>
</itemizedlist>
</para>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="libpqpp-notify">

218
doc/src/sgml/libpq.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.59 2001/03/21 19:09:03 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.60 2001/04/30 17:38:00 momjian Exp $
-->
<chapter id="libpq">
@ -696,6 +696,8 @@ SSL *PQgetssl(const PGconn *conn);
Once a connection to a database server has been successfully
established, the functions described here are used to perform
SQL queries and commands.
<sect2 id="libpq-exec-main">
<title>Main Routines</title>
<itemizedlist>
<listitem>
<para>
@ -807,6 +809,46 @@ when you want to know the status from the latest operation on the connection.
</para>
</listitem>
<listitem>
<para>
<function>PQclear</function>
Frees the storage associated with the PGresult.
Every query result should be freed via PQclear when
it is no longer needed.
<synopsis>
void PQclear(PQresult *res);
</synopsis>
You can keep a PGresult object around for as long as you
need it; it does not go away when you issue a new query,
nor even if you close the connection. To get rid of it,
you must call <function>PQclear</function>. Failure to do this will
result in memory leaks in the frontend application.
</para>
</listitem>
<listitem>
<para>
<function>PQmakeEmptyPGresult</function>
Constructs an empty PGresult object with the given status.
<synopsis>
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
</synopsis>
This is libpq's internal routine to allocate and initialize an empty
PGresult object. It is exported because some applications find it
useful to generate result objects (particularly objects with error
status) themselves. If conn is not NULL and status indicates an error,
the connection's current errorMessage is copied into the PGresult.
Note that PQclear should eventually be called on the object, just
as with a PGresult returned by libpq itself.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="libpq-exec-select-info">
<title>Retrieving SELECT Result Information</title>
<itemizedlist>
<listitem>
<para>
<function>PQntuples</function>
@ -829,18 +871,6 @@ int PQnfields(const PGresult *res);
</para>
</listitem>
<listitem>
<para>
<function>PQbinaryTuples</function>
Returns 1 if the PGresult contains binary tuple data,
0 if it contains ASCII data.
<synopsis>
int PQbinaryTuples(const PGresult *res);
</synopsis>
Currently, binary tuple data can only be returned by a query that
extracts data from a <acronym>BINARY</acronym> cursor.
</para>
</listitem>
<listitem>
<para>
@ -888,6 +918,19 @@ in the source tree.
</para>
</listitem>
<listitem>
<para>
<function>PQfmod</function>
Returns the type-specific modification data of the field
associated with the given field index.
Field indices start at 0.
<synopsis>
int PQfmod(const PGresult *res,
int field_index);
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PQfsize</function>
@ -902,21 +945,28 @@ int PQfsize(const PGresult *res,
tuple, 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>PQfmod</function>
Returns the type-specific modification data of the field
associated with the given field index.
Field indices start at 0.
<function>PQbinaryTuples</function>
Returns 1 if the PGresult contains binary tuple data,
0 if it contains ASCII data.
<synopsis>
int PQfmod(const PGresult *res,
int field_index);
int PQbinaryTuples(const PGresult *res);
</synopsis>
Currently, binary tuple data can only be returned by a query that
extracts data from a <acronym>BINARY</acronym> cursor.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="libpq-exec-select-values">
<title>Retrieving SELECT Result Values</title>
<itemizedlist>
<listitem>
<para>
<function>PQgetvalue</function>
@ -945,22 +995,6 @@ be used past the lifetime of the PGresult structure itself.
</para>
</listitem>
<listitem>
<para>
<function>PQgetlength</function>
Returns the length of a field (attribute) in bytes.
Tuple and field indices start at 0.
<synopsis>
int PQgetlength(const PGresult *res,
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 PQgetvalue. Note that for ASCII-represented
values, this size has little to do with the binary size reported by PQfsize.
</para>
</listitem>
<listitem>
<para>
<function>PQgetisnull</function>
@ -978,6 +1012,57 @@ int PQgetisnull(const PGresult *res,
</para>
</listitem>
<listitem>
<para>
<function>PQgetlength</function>
Returns the length of a field (attribute) value in bytes.
Tuple and field indices start at 0.
<synopsis>
int PQgetlength(const PGresult *res,
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 PQgetvalue. Note that for ASCII-represented
values, this size has little to do with the binary size reported by PQfsize.
</para>
</listitem>
<listitem>
<para>
<function>PQprint</function>
Prints out all the tuples and, optionally, the
attribute names to the specified output stream.
<synopsis>
void PQprint(FILE* fout, /* output stream */
const PGresult *res,
const PQprintOpt *po);
struct {
pqbool header; /* print output field headings and row count */
pqbool align; /* fill align the fields */
pqbool standard; /* old brain dead format */
pqbool html3; /* output html tables */
pqbool expanded; /* expand tables */
pqbool pager; /* use pager for output if needed */
char *fieldSep; /* field separator */
char *tableOpt; /* insert to HTML <replaceable>table ...</replaceable> */
char *caption; /* HTML <replaceable>caption</replaceable> */
char **fieldName; /* null terminated array of replacement field names */
} PQprintOpt;
</synopsis>
This function was formerly used by <application>psql</application>
to print query results, but this is no longer the case and this
function is no longer actively supported.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="libpq-exec-nonselect">
<title>Retrieving Non-SELECT Result Information</title>
<itemizedlist>
<listitem>
<para>
<function>PQcmdStatus</function>
@ -1032,70 +1117,9 @@ and is not thread-safe.
</para>
</listitem>
<listitem>
<para>
<function>PQprint</function>
Prints out all the tuples and, optionally, the
attribute names to the specified output stream.
<synopsis>
void PQprint(FILE* fout, /* output stream */
const PGresult *res,
const PQprintOpt *po);
struct {
pqbool header; /* print output field headings and row count */
pqbool align; /* fill align the fields */
pqbool standard; /* old brain dead format */
pqbool html3; /* output html tables */
pqbool expanded; /* expand tables */
pqbool pager; /* use pager for output if needed */
char *fieldSep; /* field separator */
char *tableOpt; /* insert to HTML <replaceable>table ...</replaceable> */
char *caption; /* HTML <replaceable>caption</replaceable> */
char **fieldName; /* null terminated array of replacement field names */
} PQprintOpt;
</synopsis>
This function was formerly used by <application>psql</application>
to print query results, but this is no longer the case and this
function is no longer actively supported.
</para>
</listitem>
<listitem>
<para>
<function>PQclear</function>
Frees the storage associated with the PGresult.
Every query result should be freed via PQclear when
it is no longer needed.
<synopsis>
void PQclear(PQresult *res);
</synopsis>
You can keep a PGresult object around for as long as you
need it; it does not go away when you issue a new query,
nor even if you close the connection. To get rid of it,
you must call <function>PQclear</function>. Failure to do this will
result in memory leaks in the frontend application.
</para>
</listitem>
<listitem>
<para>
<function>PQmakeEmptyPGresult</function>
Constructs an empty PGresult object with the given status.
<synopsis>
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
</synopsis>
This is libpq's internal routine to allocate and initialize an empty
PGresult object. It is exported because some applications find it
useful to generate result objects (particularly objects with error
status) themselves. If conn is not NULL and status indicates an error,
the connection's current errorMessage is copied into the PGresult.
Note that PQclear should eventually be called on the object, just
as with a PGresult returned by libpq itself.
</para>
</listitem>
</itemizedlist>
</sect2>
</para>
</sect1>