Skip to content
Snippets Groups Projects
Commit 60ba30d1 authored by Bruce Momjian's avatar Bruce Momjian
Browse files

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

libpq and libpq++ reorganized.
parent cfc4d6c5
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/src/sgml/libpq++.sgml
+ 53
− 18
View file @ 60ba30d1
<!--
$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,27 +549,52 @@ $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>GetLine</function>
<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::GetLine(char* string, int length)
int PgDatabase::CmdTuples()
</synopsis>
</para>
</listitem>
<listitem>
<para>
<function>PutLine</function>
<function>OidStatus</function>
<synopsis>
void PgDatabase::PutLine(const char* string)
const char *PgDatabase::OidStatus()
</synopsis>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="libpqpp-exec-copy">
<title>Handling COPY Queries</title>
<itemizedlist>
<listitem>
<para>
<function>OidStatus</function>
<function>GetLine</function>
<synopsis>
const char *PgDatabase::OidStatus()
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>
......@@ -575,7 +608,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
</listitem>
</itemizedlist>
</para>
</sect1>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="libpqpp-notify">
<title>Asynchronous Notification</title>
......
doc/src/sgml/libpq.sgml
+ 119
− 95
View file @ 60ba30d1
<!--
$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,23 +871,11 @@ 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>
<function>PQfname</function>
Returns the field (attribute) name associated with the given field index.
Returns the field (attribute) name associated with the given field index.
Field indices start at 0.
<synopsis>
char *PQfname(const PGresult *res,
......@@ -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,10 +995,27 @@ be used past the lifetime of the PGresult structure itself.
</para>
</listitem>
<listitem>
<para>
<function>PQgetisnull</function>
Tests a field for a NULL entry.
Tuple and field indices start at 0.
<synopsis>
int PQgetisnull(const PGresult *res,
int tup_num,
int field_num);
</synopsis>
This function returns 1 if the field contains a NULL, 0 if
it contains a non-null value. (Note that PQgetvalue
will return an empty string, not a null pointer, for a NULL
field.)
</para>
</listitem>
<listitem>
<para>
<function>PQgetlength</function>
Returns the length of a field (attribute) in bytes.
Returns the length of a field (attribute) value in bytes.
Tuple and field indices start at 0.
<synopsis>
int PQgetlength(const PGresult *res,
......@@ -963,21 +1030,39 @@ values, this size has little to do with the binary size reported by PQfsize.
<listitem>
<para>
<function>PQgetisnull</function>
Tests a field for a NULL entry.
Tuple and field indices start at 0.
<synopsis>
int PQgetisnull(const PGresult *res,
int tup_num,
int field_num);
</synopsis>
This function returns 1 if the field contains a NULL, 0 if
it contains a non-null value. (Note that PQgetvalue
will return an empty string, not a null pointer, for a NULL
field.)
<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>
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment