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
+
+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
-
-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,
+
+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
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
+
+PQgetisnull
+ Tests a field for a NULL entry.
+ Tuple and field indices start at 0.
+
+int PQgetisnull(const PGresult *res,
+ int tup_num,
+ int field_num);
+
+ 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.)
+
+
+
PQgetlength
- 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.
int PQgetlength(const PGresult *res,
-PQgetisnull
- Tests a field for a NULL entry.
- Tuple and field indices start at 0.
-
-int PQgetisnull(const PGresult *res,
- int tup_num,
- int field_num);
-
- 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.)
+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
-
-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.
-
-
+
projects / postgresql.git / commitdiff