From 5690b1a18fc1f91a4604dcaacda95f958e1153cb Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 21 May 1999 00:36:46 +0000 Subject: [PATCH] Minor updates to libpq documentation. --- doc/src/sgml/libpq.sgml | 48 ++++++++++++++++++++--------- src/man/libpq.3 | 80 +++++++++++++++++++++++++++++++++++-------------- 2 files changed, 92 insertions(+), 36 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 3442185fd4..e9d7343cb9 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -432,6 +432,24 @@ PGRES_FATAL_ERROR +PQresStatus + Converts the enumerated type returned by PQresultStatus into + a string constant describing the status code. + +const char *PQresStatus(ExecStatusType status); + +Older code may perform this same operation by direct access to a constant +string array inside libpq, + +extern const char * const pgresStatus[]; + +However, using the function is recommended instead, since it is more portable +and will not fail on out-of-range values. + + + + + PQresultErrorMessage returns the error message associated with the query, or an empty string if there was no error. @@ -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). @@ -1230,10 +1247,10 @@ int PQendcopy(PGconn *conn); As an example: -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<TAB>hello world<TAB>4.5\n"); -PQputline(conn,"4<TAB>goodbye world<TAB>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() /* - * testlibpq2.c Test of the asynchronous notification interface - * - * populate a database with the following: + * testlibpq2.c + * Test of the asynchronous notification interface * - * CREATE TABLE TBL1 (i int4); + * Start this program, then from psql in another window do + * NOTIFY TBL2; * - * CREATE TABLE TBL2 (i int4); + * Or, if you want to get fancy, try this: + * Populate a database with the following: * - * CREATE RULE r1 AS ON INSERT TO TBL1 DO [INSERT INTO TBL2 values - * (new.i); NOTIFY TBL2]; + * CREATE TABLE TBL1 (i int4); * - * Then start up this program After the program has begun, do + * CREATE TABLE TBL2 (i int4); * - * 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 <stdio.h> diff --git a/src/man/libpq.3 b/src/man/libpq.3 index 064d33b80e..adb431c110 100644 --- a/src/man/libpq.3 +++ b/src/man/libpq.3 @@ -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, "3hello world4.5\en"); -PQputline(conn,"4goodbye world7.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 -- 2.11.0