libpq.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

result directly. It will be freed when the
associated <structname>PGresult</> handle is passed to
<function>PQclear</function>.
</para>

<para>
The following field codes are available:
<variablelist>

<varlistentry>
<term><symbol>PG_DIAG_SEVERITY</></term>
<listitem>
<para>
The severity; the field contents are <literal>ERROR</>,
<literal>FATAL</>, or <literal>PANIC</> (in an error message), or
<literal>WARNING</>, <literal>NOTICE</>, <literal>DEBUG</>,
<literal>INFO</>, or <literal>LOG</> (in a notice message), or a
localized translation of one of these.  Always present.
</para>
</listitem>
</varlistentry>

<varlistentry>
 <indexterm>
  <primary>error codes</primary>
  <secondary>libpq</secondary>
 </indexterm>
<term><symbol>PG_DIAG_SQLSTATE</>
</term>
<listitem>
<para>
The SQLSTATE code for the error. The SQLSTATE code identifies the type
of error that has occurred; it can be used by front-end applications
to perform specific operations (such as error handling) in response to
a particular database error. For a list of the possible SQLSTATE
codes, see <xref linkend="errcodes-appendix">. This field is not
localizable, and is always present.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><symbol>PG_DIAG_MESSAGE_PRIMARY</></term>
<listitem>
<para>
The primary human-readable error message (typically one line).  Always
present.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><symbol>PG_DIAG_MESSAGE_DETAIL</></term>
<listitem>
<para>
Detail: an optional secondary error message carrying more detail about
the problem.  May run to multiple lines.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><symbol>PG_DIAG_MESSAGE_HINT</></term>
<listitem>
<para>
Hint: an optional suggestion what to do about the problem.  This is
intended to differ from detail in that it offers advice (potentially
inappropriate) rather than hard facts.  May run to multiple lines.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><symbol>PG_DIAG_STATEMENT_POSITION</></term>
<listitem>
<para>
A string containing a decimal integer indicating an error cursor
position as an index into the original statement string.  The first
character has index 1, and positions are measured in characters not
bytes.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><symbol>PG_DIAG_INTERNAL_POSITION</></term>
<listitem>
<para>
This is defined the same as the <symbol>PG_DIAG_STATEMENT_POSITION</>
field, but it is used when the cursor position refers to an internally
generated command rather than the one submitted by the client.
The <symbol>PG_DIAG_INTERNAL_QUERY</> field will always appear when this field
appears.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><symbol>PG_DIAG_INTERNAL_QUERY</></term>
<listitem>
<para>
The text of a failed internally-generated command.
This could be, for example, a SQL query issued by a PL/pgSQL function.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><symbol>PG_DIAG_CONTEXT</></term>
<listitem>
<para>
An indication of the context in which the error occurred.
Presently this includes a call stack traceback of active
procedural language functions and internally-generated queries.
The trace is one entry per line, most recent first.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><symbol>PG_DIAG_SOURCE_FILE</></term>
<listitem>
<para>
The file name of the source-code location where the error was
reported.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><symbol>PG_DIAG_SOURCE_LINE</></term>
<listitem>
<para>
The line number of the source-code location where the error was
reported.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><symbol>PG_DIAG_SOURCE_FUNCTION</></term>
<listitem>
<para>
The name of the source-code function reporting the error.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>
The client is responsible for formatting displayed information to meet
its needs; in particular it should break long lines as needed.
Newline characters appearing in the error message fields should be
treated as paragraph breaks, not line breaks.
</para>

<para>
Errors generated internally by <application>libpq</application> will
have severity and primary message, but typically no other fields.
Errors returned by a pre-3.0-protocol server will include severity and
primary message, and sometimes a detail message, but no other fields.
</para>

<para>
Note that error fields are only available from
<structname>PGresult</structname> objects, not
<structname>PGconn</structname> objects; there is no
<function>PQerrorField</function> function.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQclear</function><indexterm><primary>PQclear</></></term>
<listitem>
<para>
          Frees  the  storage  associated with a <structname>PGresult</structname>.
          Every command result should be freed via <function>PQclear</function> when
          it  is  no  longer needed.
<synopsis>
void PQclear(PGresult *res);
</synopsis>
</para>

<para>
          You can keep a <structname>PGresult</structname> object around for as long as you
          need it; it does not go away when you issue a new command,
          nor even if you close the connection.  To get rid of it,
          you must call <function>PQclear</function>.  Failure to do this will
          result in memory leaks in your application.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQmakeEmptyPGresult</function><indexterm><primary>PQmakeEmptyPGresult</></></term>
<listitem>
<para>
          Constructs an empty <structname>PGresult</structname> object with the given status.
<synopsis>
PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
</synopsis>
</para>

<para>
This is <application>libpq</>'s internal function to allocate and
initialize an empty <structname>PGresult</structname> object.  This
function returns NULL if memory could not be allocated. It is exported
because some applications find it useful to generate result objects
(particularly objects with error status) themselves.  If
<parameter>conn</parameter> is not null and <parameter>status</>
indicates an error, the current error message of the specified
connection is copied into the <structname>PGresult</structname>.  Note
that <function>PQclear</function> should eventually be called on the
object, just as with a <structname>PGresult</structname> returned by
<application>libpq</application> itself.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>

<sect2 id="libpq-exec-select-info">
  <title>Retrieving Query Result Information</title>

<para>
These functions are used to extract information from a
<structname>PGresult</structname> object that represents a successful
query result (that is, one that has status
<literal>PGRES_TUPLES_OK</literal>).  For objects with other status
values they will act as though the result has zero rows and zero columns.
</para>

<variablelist>
<varlistentry>
<term><function>PQntuples</function><indexterm><primary>PQntuples</></></term>
<listitem>
<para>
          Returns the number of rows (tuples)
          in the query result.
<synopsis>
int PQntuples(const PGresult *res);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQnfields</function><indexterm><primary>PQnfields</></></term>
<listitem>
<para>
          Returns the number of columns (fields)
          in each row of the query result.
<synopsis>
int PQnfields(const PGresult *res);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQfname</function><indexterm><primary>PQfname</></></term>
<listitem>
<para>
Returns the column name associated with the given column number.
Column numbers start at 0. The caller should not free the result
directly. It will be freed when the associated <structname>PGresult</>
handle is passed to <function>PQclear</function>.
<synopsis>
char *PQfname(const PGresult *res,
              int column_number);
</synopsis>
</para>

<para>
<symbol>NULL</symbol> is returned if the column number is out of range.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQfnumber</function><indexterm><primary>PQfnumber</></></term>
<listitem>
<para>
          Returns the column number associated with the given column name.
<synopsis>
int PQfnumber(const PGresult *res,
              const char *column_name);
</synopsis>
</para>

<para>
        -1 is returned if the given name does not match any column.
</para>

<para>
        The given name is treated like an identifier in an SQL command,
        that is, it is downcased unless double-quoted.  For example,
        given a query result generated from the SQL command
<programlisting>
select 1 as FOO, 2 as "BAR";
</programlisting>
        we would have the results:
<programlisting>
PQfname(res, 0)              <lineannotation>foo</lineannotation>
PQfname(res, 1)              <lineannotation>BAR</lineannotation>
PQfnumber(res, "FOO")        <lineannotation>0</lineannotation>
PQfnumber(res, "foo")        <lineannotation>0</lineannotation>
PQfnumber(res, "BAR")        <lineannotation>-1</lineannotation>
PQfnumber(res, "\"BAR\"")    <lineannotation>1</lineannotation>
</programlisting>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQftable</function><indexterm><primary>PQftable</></></term>
<listitem>
<para>
 Returns the OID of the table from which the given column was fetched.
 Column numbers start at 0.
<synopsis>
Oid PQftable(const PGresult *res,
             int column_number);
</synopsis>
</para>

<para>
<literal>InvalidOid</> is returned if the column number is out of range,
or if the specified column is not a simple reference to a table column,
or when using pre-3.0 protocol.
You can query the system table <literal>pg_class</literal> to determine
exactly which table is referenced.
</para>

<para>
          The type <type>Oid</type> and the constant
          <literal>InvalidOid</literal> will be defined when you include
          the <application>libpq</application> header file. They will
          both be some integer type.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQftablecol</function><indexterm><primary>PQftablecol</></></term>
<listitem>
<para>
 Returns the column number (within its table) of the column making up
 the specified query result column.
 Query-result column numbers start at 0, but table columns have nonzero
 numbers.
<synopsis>
int PQftablecol(const PGresult *res,
                int column_number);
</synopsis>
</para>

<para>
Zero is returned if the column number is out of range,
or if the specified column is not a simple reference to a table column,
or when using pre-3.0 protocol.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQfformat</function><