libpq.sgml

PostgreSQL7.4.6 for Linux

must be set up by executing an SQL <command>PREPARE</> command,
which is typically sent with <function>PQexec</> (though any of
<application>libpq</>'s query-submission functions may be used).
A lower-level interface for preparing statements may be offered in a
future release.
</para>

<para>
The
<structname>PGresult</structname><indexterm><primary>PGresult</></>
structure encapsulates the result returned by the server.
<application>libpq</application> application programmers should be
careful to maintain the <structname>PGresult</structname> abstraction.
Use the accessor functions below to get at the contents of
<structname>PGresult</structname>.  Avoid directly referencing the
fields of the <structname>PGresult</structname> structure because they
are subject to change in the future.

<variablelist>
<varlistentry>
<term><function>PQresultStatus</function><indexterm><primary>PQresultStatus</></></term>
<listitem>
<para>
          Returns the result status of the command.
<synopsis>
ExecStatusType PQresultStatus(const PGresult *res);
</synopsis>
</para>

<para>
<function>PQresultStatus</function> can return one of the following values:

<variablelist>
 <varlistentry>
  <term><literal>PGRES_EMPTY_QUERY</literal></term>
  <listitem>
   <para>The string sent to the server was empty.</para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><literal>PGRES_COMMAND_OK</literal></term>
  <listitem>
   <para>Successful completion of a command returning no data.</para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><literal>PGRES_TUPLES_OK</literal></term>
  <listitem>
   <para>Successful completion of a command returning data (such as
   a <command>SELECT</> or <command>SHOW</>).</para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><literal>PGRES_COPY_OUT</literal></term>
  <listitem>
   <para>Copy Out (from server) data transfer started.</para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><literal>PGRES_COPY_IN</literal></term>
  <listitem>
   <para>Copy In (to server) data transfer started.</para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><literal>PGRES_BAD_RESPONSE</literal></term>
  <listitem>
   <para>The server's response was not understood.</para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><literal>PGRES_NONFATAL_ERROR</literal></term>
  <listitem>
   <para>A nonfatal error (a notice or warning) occurred.</para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><literal>PGRES_FATAL_ERROR</literal></term>
  <listitem>
   <para>A fatal error occurred.</para>
  </listitem>
 </varlistentry>
</variablelist>

If the result status is <literal>PGRES_TUPLES_OK</literal>, then the
functions described below can be used to retrieve the rows returned by
the query.  Note that a <command>SELECT</command> command that happens
to retrieve zero rows still shows <literal>PGRES_TUPLES_OK</literal>.
<literal>PGRES_COMMAND_OK</literal> is for commands that can never
return rows (<command>INSERT</command>, <command>UPDATE</command>,
etc.). A response of <literal>PGRES_EMPTY_QUERY</literal> may indicate
a bug in the client software.
</para>

<para>
A result of status <symbol>PGRES_NONFATAL_ERROR</symbol> will never be
returned directly by <function>PQexec</function> or other query
execution functions; results of this kind are instead passed to the notice
processor (see <xref linkend="libpq-notice-processing">).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQresStatus</function><indexterm><primary>PQresStatus</></></term>
<listitem>
<para>
        Converts the enumerated type returned by <function>PQresultStatus</> into
        a string constant describing the status code.
<synopsis>
char *PQresStatus(ExecStatusType status);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQresultErrorMessage</function><indexterm><primary>PQresultErrorMessage</></></term>
<listitem>
<para>
Returns the error message associated with the command, or an empty string
if there was no error.
<synopsis>
char *PQresultErrorMessage(const PGresult *res);
</synopsis>
If there was an error, the returned string will include a trailing newline.
</para>

<para>
Immediately following a <function>PQexec</function> or <function>PQgetResult</function>
call, <function>PQerrorMessage</function> (on the connection) will return the same
string as <function>PQresultErrorMessage</function> (on the result).  However, a
<structname>PGresult</structname> will retain its error message
until destroyed, whereas the connection's error message will change when
subsequent operations are done.  Use <function>PQresultErrorMessage</function> when you want to
know the status associated with a particular <structname>PGresult</structname>; use <function>PQerrorMessage</function>
when you want to know the status from the latest operation on the connection.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQresultErrorField</function><indexterm><primary>PQresultErrorField</></></term>
<listitem>
<para>
Returns an individual field of an error report.
<synopsis>
char *PQresultErrorField(const PGresult *res, int fieldcode);
</synopsis>
<parameter>fieldcode</> is an error field identifier; see the symbols
listed below.  <symbol>NULL</symbol> is returned if the
<structname>PGresult</structname> is not an error or warning result,
or does not include the specified field.  Field values will normally
not include a trailing newline.
</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>
<term><symbol>PG_DIAG_SQLSTATE</>
</term>
<listitem>
<para>
The SQLSTATE code for the error (see <xref linkend="errcodes-appendix">).
Not localizable.  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_CONTEXT</></term>
<listitem>
<para>
An indication of the context in which the error occurred.  Presently
this includes a call stack traceback of active PL functions.  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(PQresult *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.  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>