mirror of
https://git.postgresql.org/git/postgresql.git
synced 2025-02-23 19:39:53 +08:00
Break up PQexec() result functions into subsections to be clearer. Both
libpq and libpq++ reorganized.
This commit is contained in:
Bruce Momjian
parent
cfc4d6c510
commit
60ba30d13a
@ -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">
|
<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">
|
<sect1 id="libpqpp-exec">
|
||||||
<title>Query Execution Functions</title>
|
<title>Query Execution Functions</title>
|
||||||
|
|
||||||
|
<sect2 id="libpqpp-exec-main">
|
||||||
|
<title>Main Routines</title>
|
||||||
<para>
|
<para>
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
@ -352,6 +355,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
|
|||||||
</synopsis>
|
</synopsis>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2 id="libpqpp-exec-select-info">
|
||||||
|
<title>Retrieving SELECT Result Information</title>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>Tuples</function>
|
<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>
|
</synopsis>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</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>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>Fields</function>
|
<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.
|
variable size.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
|
||||||
|
<sect2 id="libpqpp-exec-select-values">
|
||||||
|
<title>Retrieving SELECT Result Values</title>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>GetValue</function>
|
<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>
|
</synopsis>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</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>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>GetLine</function>
|
<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>
|
</synopsis>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
<function>OidStatus</function>
|
|
||||||
<synopsis>
|
|
||||||
const char *PgDatabase::OidStatus()
|
|
||||||
</synopsis>
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>EndCopy</function>
|
<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>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
|
</itemizedlist>
|
||||||
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 id="libpqpp-notify">
|
<sect1 id="libpqpp-notify">
|
||||||
|
|||||||
@ -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">
|
<chapter id="libpq">
|
||||||
@ -696,6 +696,8 @@ SSL *PQgetssl(const PGconn *conn);
|
|||||||
Once a connection to a database server has been successfully
|
Once a connection to a database server has been successfully
|
||||||
established, the functions described here are used to perform
|
established, the functions described here are used to perform
|
||||||
SQL queries and commands.
|
SQL queries and commands.
|
||||||
|
<sect2 id="libpq-exec-main">
|
||||||
|
<title>Main Routines</title>
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
@ -807,6 +809,46 @@ when you want to know the status from the latest operation on the connection.
|
|||||||
</para>
|
</para>
|
||||||
</listitem>
|
</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>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>PQntuples</function>
|
<function>PQntuples</function>
|
||||||
@ -829,18 +871,6 @@ int PQnfields(const PGresult *res);
|
|||||||
</para>
|
</para>
|
||||||
</listitem>
|
</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>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
@ -888,6 +918,19 @@ in the source tree.
|
|||||||
</para>
|
</para>
|
||||||
</listitem>
|
</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>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>PQfsize</function>
|
<function>PQfsize</function>
|
||||||
@ -902,21 +945,28 @@ int PQfsize(const PGresult *res,
|
|||||||
tuple, in other words the size of the server's binary representation
|
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.
|
of the data type. -1 is returned if the field is variable size.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>PQfmod</function>
|
<function>PQbinaryTuples</function>
|
||||||
Returns the type-specific modification data of the field
|
Returns 1 if the PGresult contains binary tuple data,
|
||||||
associated with the given field index.
|
0 if it contains ASCII data.
|
||||||
Field indices start at 0.
|
|
||||||
<synopsis>
|
<synopsis>
|
||||||
int PQfmod(const PGresult *res,
|
int PQbinaryTuples(const PGresult *res);
|
||||||
int field_index);
|
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
Currently, binary tuple data can only be returned by a query that
|
||||||
|
extracts data from a <acronym>BINARY</acronym> cursor.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2 id="libpq-exec-select-values">
|
||||||
|
<title>Retrieving SELECT Result Values</title>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>PQgetvalue</function>
|
<function>PQgetvalue</function>
|
||||||
@ -945,22 +995,6 @@ be used past the lifetime of the PGresult structure itself.
|
|||||||
</para>
|
</para>
|
||||||
</listitem>
|
</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>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>PQgetisnull</function>
|
<function>PQgetisnull</function>
|
||||||
@ -978,6 +1012,57 @@ int PQgetisnull(const PGresult *res,
|
|||||||
</para>
|
</para>
|
||||||
</listitem>
|
</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>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<function>PQcmdStatus</function>
|
<function>PQcmdStatus</function>
|
||||||
@ -1032,70 +1117,9 @@ and is not thread-safe.
|
|||||||
</para>
|
</para>
|
||||||
</listitem>
|
</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>
|
</itemizedlist>
|
||||||
|
</sect2>
|
||||||
</para>
|
</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user