opensourcemirror
/
postgresql
mirror of git://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Minor updates to libpq documentation.

This commit is contained in:
Tom Lane 1999-05-21 00:36:46 +00:00
parent 3de11d6526
commit 5690b1a18f
2 changed files with 92 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -430,6 +430,24 @@ PGRES_FATAL_ERROR
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQresStatus</Function>
Converts the enumerated type returned by PQresultStatus into
a string constant describing the status code.
<synopsis>
const char *PQresStatus(ExecStatusType status);
</synopsis>
Older code may perform this same operation by direct access to a constant
string array inside libpq,
<synopsis>
extern const char * const pgresStatus[];
</synopsis>
However, using the function is recommended instead, since it is more portable
and will not fail on out-of-range values.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQresultErrorMessage</Function>
@ -910,8 +928,7 @@ terms is readable data on the file descriptor identified by PQsocket.
When the main loop detects input ready, it should call PQconsumeInput
to read the input. It can then call PQisBusy, followed by PQgetResult
if PQisBusy returns FALSE. It can also call PQnotifies to detect NOTIFY
messages (see "Asynchronous Notification", below). An example is given
in the sample programs section.
messages (see "Asynchronous Notification", below).
</Para>
<Para>
@ -1230,10 +1247,10 @@ int PQendcopy(PGconn *conn);
As an example:
<ProgramListing>
PQexec(conn, "create table foo (a int4, b char16, d float8)");
PQexec(conn, "create table foo (a int4, b char(16), d float8)");
PQexec(conn, "copy foo from stdin");
PQputline(conn, "3&lt;TAB&gt;hello world&lt;TAB&gt;4.5\n");
PQputline(conn,"4&lt;TAB&gt;goodbye world&lt;TAB&gt;7.11\n");
PQputline(conn, "3\thello world\t4.5\n");
PQputline(conn,"4\tgoodbye world\t7.11\n");
...
PQputline(conn,"\\.\n");
PQendcopy(conn);
@ -1671,22 +1688,25 @@ main()
<Para>
<ProgramListing>
/*
* testlibpq2.c Test of the asynchronous notification interface
* testlibpq2.c
* Test of the asynchronous notification interface
*
* populate a database with the following:
* Start this program, then from psql in another window do
* NOTIFY TBL2;
*
* CREATE TABLE TBL1 (i int4);
* Or, if you want to get fancy, try this:
* Populate a database with the following:
*
* CREATE TABLE TBL2 (i int4);
* CREATE TABLE TBL1 (i int4);
*
* CREATE RULE r1 AS ON INSERT TO TBL1 DO [INSERT INTO TBL2 values
* (new.i); NOTIFY TBL2];
* CREATE TABLE TBL2 (i int4);
*
* Then start up this program After the program has begun, do
*
* INSERT INTO TBL1 values (10);
* CREATE RULE r1 AS ON INSERT TO TBL1 DO
* (INSERT INTO TBL2 values (new.i); NOTIFY TBL2);
*
* and do
*
* INSERT INTO TBL1 values (10);
*
*/
#include &lt;stdio.h&gt;

80
src/man/libpq.3
View File

@ -1,6 +1,6 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.26 1999/04/17 17:18:41 momjian Exp $
.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.27 1999/05/21 00:36:01 tgl Exp $
.TH LIBPQ INTRO 08/08/98 PostgreSQL PostgreSQL
.SH DESCRIPTION
Current documentation for this topic is available in the new Programmer's Guide
@ -266,9 +266,44 @@ PGRES_NONFATAL_ERROR,
PGRES_FATAL_ERROR
.fi
.IP
If the result status is PGRES_TUPLES_OK, then the following routines can
be used to retrieve the tuples returned by the query.
If the result status is PGRES_TUPLES_OK, then the
routines described below can be used to retrieve the
tuples returned by the query. Note that a SELECT that
happens to retrieve zero tuples still shows PGRES_TUPLES_OK.
PGRES_COMMAND_OK is for commands that can never return tuples.
.PP
.B PQresStatus
.IP
Converts the enumerated type returned by PQresultStatus into
a string constant describing the status code.
.nf
const char *PQresStatus(ExecStatusType status);
.fi
.IP
Older code may perform this same operation by direct access to a constant
string array inside libpq,
.nf
extern const char * const pgresStatus[];
.fi
.IP
However, using the function is recommended instead, since it is more portable
and will not fail on out-of-range values.
.PP
.B PQresultErrorMessage
.IP
returns the error message associated with the query, or an empty string
if there was no error.
.nf
const char *PQresultErrorMessage(PGresult *res);
.fi
.IP
Immediately following a PQexec or PQgetResult call, PQerrorMessage
(on the connection) will return the same string as PQresultErrorMessage
(on the result). However, a PGresult will retain its error message
until destroyed, whereas the connection's error message will change when
subsequent operations are done. Use PQresultErrorMessage when you want to
know the status associated with a particular PGresult; use PQerrorMessage
when you want to know the status from the latest operation on the connection.
.B PQntuples
returns the number of tuples (instances) in the query result.
@ -558,8 +593,7 @@ terms is readable data on the file descriptor identified by PQsocket.
When the main loop detects input ready, it should call PQconsumeInput
to read the input. It can then call PQisBusy, followed by PQgetResult
if PQisBusy returns FALSE. It can also call PQnotifies to detect NOTIFY
messages (see "Asynchronous Notification", below). An example is given
in the sample programs section.
messages (see "Asynchronous Notification", below).
.PP
A frontend that uses PQsendQuery/PQgetResult can also attempt to cancel
@ -789,12 +823,12 @@ int PQendcopy(PGconn *conn);
.fi
As an example:
.nf
PQexec(conn, "create table foo (a int4, b name, d float8)");
PQexec(conn, "create table foo (a int4, b char(16), d float8)");
PQexec(conn, "copy foo from stdin");
PQputline(conn, "3<TAB>hello world<TAB>4.5\en");
PQputline(conn,"4<TAB>goodbye world<TAB>7.11\en");
PQputline(conn, "3\ethello world\et4.5\en");
PQputline(conn,"4\etgoodbye world\et7.11\en");
\&...
PQputline(conn,"\\.\en");
PQputline(conn,"\e\e.\en");
PQendcopy(conn);
.fi
.PP
@ -1048,20 +1082,22 @@ main()
* testlibpq2.c
* Test of the asynchronous notification interface
*
populate a database with the following:
CREATE TABLE TBL1 (i int4);
CREATE TABLE TBL2 (i int4);
CREATE RULE r1 AS ON INSERT TO TBL1 DO [INSERT INTO TBL2 values (new.i); NOTIFY TBL2];
* Then start up this program
* After the program has begun, do
INSERT INTO TBL1 values (10);
* Start this program, then from psql in another window do
* NOTIFY TBL2;
*
* Or, if you want to get fancy, try this:
* Populate a database with the following:
*
* CREATE TABLE TBL1 (i int4);
*
* CREATE TABLE TBL2 (i int4);
*
* CREATE RULE r1 AS ON INSERT TO TBL1 DO
* (INSERT INTO TBL2 values (new.i); NOTIFY TBL2);
*
* and do
*
* INSERT INTO TBL1 values (10);
*
*/
#include <stdio.h>