diff --git a/doc/src/sgml/libpq++.sgml b/doc/src/sgml/libpq++.sgml index 06ab5238a8..5e899d5c54 100644 --- a/doc/src/sgml/libpq++.sgml +++ b/doc/src/sgml/libpq++.sgml @@ -1,5 +1,5 @@ @@ -283,6 +283,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26: Query Execution Functions + + + Main Routines @@ -352,6 +355,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26: + + + + + Retrieving SELECT Result Information + + Tuples @@ -361,16 +371,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26: - - - CmdTuples - Returns the number of rows affected after an INSERT, UPDATE or DELETE. - If the command was anything else, it returns -1. - - int PgDatabase::CmdTuples() - - - Fields @@ -451,6 +451,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26: variable size. + + + + + + Retrieving SELECT Result Values + + GetValue @@ -541,6 +549,39 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26: + + + + + Retrieving Non-SELECT Result Information + + + + + CmdTuples + Returns the number of rows affected after an INSERT, UPDATE or DELETE. + If the command was anything else, it returns -1. + + int PgDatabase::CmdTuples() + + + + + + + OidStatus + + const char *PgDatabase::OidStatus() + + + + + + + + Handling COPY Queries + + GetLine @@ -557,14 +598,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26: - - - OidStatus - - const char *PgDatabase::OidStatus() - - - EndCopy @@ -575,7 +608,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26: - + + + Asynchronous Notification diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 003a4dd5c1..94fdd42a01 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ @@ -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. + + Main Routines @@ -807,6 +809,46 @@ when you want to know the status from the latest operation on the connection. + + +PQclear + Frees the storage associated with the PGresult. + Every query result should be freed via PQclear when + it is no longer needed. + +void PQclear(PQresult *res); + + 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 PQclear. Failure to do this will + result in memory leaks in the frontend application. + + + + + +PQmakeEmptyPGresult + Constructs an empty PGresult object with the given status. + +PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); + +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. + + + + + + + Retrieving SELECT Result Information + + PQntuples @@ -829,23 +871,11 @@ int PQnfields(const PGresult *res); - - -PQbinaryTuples - Returns 1 if the PGresult contains binary tuple data, - 0 if it contains ASCII data. - -int PQbinaryTuples(const PGresult *res); - -Currently, binary tuple data can only be returned by a query that -extracts data from a BINARY cursor. - - PQfname - 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. char *PQfname(const PGresult *res, @@ -888,6 +918,19 @@ in the source tree. + + +PQfmod + Returns the type-specific modification data of the field + associated with the given field index. + Field indices start at 0. + +int PQfmod(const PGresult *res, + int field_index); + + + + PQfsize @@ -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. + -PQfmod - Returns the type-specific modification data of the field - associated with the given field index. - Field indices start at 0. +PQbinaryTuples + Returns 1 if the PGresult contains binary tuple data, + 0 if it contains ASCII data. -int PQfmod(const PGresult *res, - int field_index); +int PQbinaryTuples(const PGresult *res); +Currently, binary tuple data can only be returned by a query that +extracts data from a BINARY cursor. + + + + Retrieving SELECT Result Values + + PQgetvalue @@ -945,22 +995,6 @@ be used past the lifetime of the PGresult structure itself. - - -PQgetlength - Returns the length of a field (attribute) in bytes. - Tuple and field indices start at 0. - -int PQgetlength(const PGresult *res, - int tup_num, - int field_num); - -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. - - - PQgetisnull @@ -978,6 +1012,57 @@ int PQgetisnull(const PGresult *res, + + +PQgetlength + Returns the length of a field (attribute) value in bytes. + Tuple and field indices start at 0. + +int PQgetlength(const PGresult *res, + int tup_num, + int field_num); + +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. + + + + + +PQprint + Prints out all the tuples and, optionally, the + attribute names to the specified output stream. + +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 table ... */ + char *caption; /* HTML caption */ + char **fieldName; /* null terminated array of replacement field names */ +} PQprintOpt; + +This function was formerly used by psql +to print query results, but this is no longer the case and this +function is no longer actively supported. + + + + + + + Retrieving Non-SELECT Result Information + + PQcmdStatus @@ -1032,70 +1117,9 @@ and is not thread-safe. - - -PQprint - Prints out all the tuples and, optionally, the - attribute names to the specified output stream. - -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 table ... */ - char *caption; /* HTML caption */ - char **fieldName; /* null terminated array of replacement field names */ -} PQprintOpt; - -This function was formerly used by psql -to print query results, but this is no longer the case and this -function is no longer actively supported. - - - - - -PQclear - Frees the storage associated with the PGresult. - Every query result should be freed via PQclear when - it is no longer needed. - -void PQclear(PQresult *res); - - 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 PQclear. Failure to do this will - result in memory leaks in the frontend application. - - - - - -PQmakeEmptyPGresult - Constructs an empty PGresult object with the given status. - -PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); - -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. - - +