libpq.sgml

关系型数据库 Postgresql 6.5.2

The <Function>PGresult</Function> structure encapsulates the query result
returned by the backend.
<FileName>libpq</FileName> application programmers should be careful to
maintain the PGresult abstraction.  Use the accessor functions below to get
at the contents of PGresult.  Avoid directly referencing the fields of the
PGresult structure because they are subject to change in the future.
(Beginning in <ProductName>Postgres</ProductName> release 6.4, the
definition of struct PGresult is not even provided in libpq-fe.h.  If you
have old code that accesses PGresult fields directly, you can keep using it
by including libpq-int.h too, but you are encouraged to fix the code
soon.)

<ItemizedList>
<ListItem>
<Para>
<Function>PQresultStatus</Function>
          Returns the result status of the query.  PQresultStatus can return one of the following values:
<synopsis>
PGRES_EMPTY_QUERY,
PGRES_COMMAND_OK,       /* the query was a command returning no data */
PGRES_TUPLES_OK,        /* the query successfully returned tuples */
PGRES_COPY_OUT,         /* Copy Out (from server) data transfer started */
PGRES_COPY_IN,          /* Copy In (to server) data transfer started */
PGRES_BAD_RESPONSE,     /* an unexpected response was received */
PGRES_NONFATAL_ERROR,
PGRES_FATAL_ERROR
</synopsis>
          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.
</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>
returns the error message associated with the query, or an empty string
if there was no error.
<synopsis>
const char *PQresultErrorMessage(PGresult *res);
</synopsis>
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.
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQntuples</Function>
          Returns the number of tuples (instances)
          in the query result.
<synopsis>
int PQntuples(PGresult *res);
</synopsis>
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQnfields</Function>
          Returns   the   number    of    fields
          (attributes) in each tuple of the query result.
<synopsis>
int PQnfields(PGresult *res);
</synopsis>
</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(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.
 Field  indices start at 0.
<synopsis>
char *PQfname(PGresult *res,
              int field_index);
</synopsis>
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQfnumber</Function>
            Returns  the  field  (attribute)  index
          associated with the given field name.
<synopsis>
int PQfnumber(PGresult *res,
              char* field_name);
</synopsis>
</Para>

<Para>
        -1 is returned if the given name does not match any field.
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQftype</Function>
            Returns the field type associated with the
          given  field  index.  The  integer  returned is an
          internal coding of the type.  Field indices  start
          at 0.
<synopsis>
Oid PQftype(PGresult *res,
            int field_num);
</synopsis>
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQfsize</Function>
          Returns  the  size  in bytes of the field
          associated with the given field index.
          Field indices start at 0.
<synopsis>
int PQfsize(PGresult *res,
            int field_index);
</synopsis>
	PQfsize returns the space allocated for this field in a database
	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.
<synopsis>
int PQfmod(PGresult *res,
           int field_index);
</synopsis>
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQgetvalue</Function>
            Returns a single field  (attribute)  value of one tuple
	    of a PGresult.
	    Tuple and field indices start at 0.
<synopsis>
char* PQgetvalue(PGresult *res,
                 int tup_num,
                 int field_num);
</synopsis>
          For most queries, the value returned by PQgetvalue
          is a null-terminated ASCII  string  representation
          of the attribute value.  But if PQbinaryTuples() is TRUE,
          the  value  returned  by
          PQgetvalue  is  the  binary  representation of the
          type in the internal format of the backend server
	  (but not including the size word, if the field is variable-length).
          It  is then the programmer's responsibility to cast and
          convert the data to the correct C type.  The pointer
          returned  by  PQgetvalue points to storage that is
          part of the PGresult structure.  One should not modify it,
          and one must explicitly 
          copy the value into other storage if it is to
          be used past the lifetime of the  PGresult  structure itself.
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQgetlength</Function>
          Returns   the   length  of  a  field (attribute) in bytes.
          Tuple and field indices start at 0.
<synopsis>
int PQgetlength(PGresult *res,
                int tup_num,
                int field_num);
</synopsis>
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.
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQgetisnull</Function>
           Tests a field for a NULL entry.
           Tuple and field indices start at 0.
<synopsis>
int PQgetisnull(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>PQcmdStatus</Function>
          Returns the command status string from the SQL command that
	  generated the PGresult.
<synopsis>
char *PQcmdStatus(PGresult *res);
</synopsis>
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQcmdTuples</Function>
	  Returns the number of rows affected by the SQL command.
<synopsis>
const char *PQcmdTuples(PGresult *res);
</synopsis>
          If the SQL command that generated the
	  PGresult was INSERT, UPDATE or DELETE, this returns a
	  string containing the number of rows affected.  If the
          command was anything else, it returns the empty string.
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQoidStatus</Function>
          Returns a string with the object id of  the  tuple
          inserted,  if  the SQL command was an INSERT.
          Otherwise, returns an empty string.
<synopsis>
char* PQoidStatus(PGresult *res);
</synopsis>
</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 */
             PGresult* res,
             PQprintOpt* po);

struct _PQprintOpt
        {
                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 &lt;table ...&gt; */
                char    *caption;    /* HTML &lt;caption&gt; */
                char    **fieldName; /* null terminated array of replacement field names */
        };
</synopsis>
	This function is intended to replace PQprintTuples(), which is
	now obsolete.  The <FileName>psql</FileName> program uses
	PQprint() to display query results.
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQprintTuples</Function>
          Prints out all the  tuples  and,  optionally,  the
          attribute  names  to  the specified output stream.
<synopsis>
void PQprintTuples(PGresult* res,
                   FILE* fout,      /* output stream */
                   int printAttName,/* print attribute names or not*/
                   int terseOutput, /* delimiter bars or not?*/
                   int width);      /* width of column, variable width if 0*/
</synopsis>
</Para>
</ListItem>

<ListItem>
<Para>
<Function>PQdisplayTuples</Function>
          Prints out all the  tuples  and,  optionally,  the
          attribute  names  to  the specified output stream.
<synopsis>
void PQdisplayTuples(PGresult* res,
                     FILE* fout,           /* output stream */
                     int fillAlign,        /* space fill to align columns */
                     const char *fieldSep, /* field separator */
                     int printHeader,      /* display headers? */
                     int quiet);           /* suppress print of row count at end */
</synopsis>
          PQdisplayTuples() was intended to supersede PQprintTuples(), and
          is in turn superseded by PQprint().
</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 PQclear.  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>
</Para>
</Sect1>

<Sect1>
<Title>Asynchronous Query Processing</Title>

<Para>
The PQexec function is adequate for submitting queries in simple synchronous
applications.  It has a couple of major deficiencies however:

<ItemizedList>
<ListItem>
<Para>
PQexec waits for the query to be completed.  The application may have other
work to do (such as maintaining a user interface), in which case it won't
want to block waiting for the response.
</Para>
</ListItem>
<ListItem>
<Para>
Since control is buried inside PQexec, it is hard for the frontend
to decide it would like to try to cancel the ongoing query.  (It can be
done from a signal handler, but not otherwise.)
</Para>
</ListItem>