libpq.sgml

PostgreSQL7.4.6 for Linux

<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.
<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.
 Result column numbers start at 0.
<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><indexterm><primary>PQfformat</></></term>
<listitem>
<para>
 Returns the format code indicating the format of the given column.
 Column numbers start at 0.
<synopsis>
int PQfformat(const PGresult *res,
              int column_number);
</synopsis>
</para>

<para>
Format code zero indicates textual data representation, while format
code one indicates binary representation.  (Other codes are reserved
for future definition.)
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQftype</function><indexterm><primary>PQftype</></></term>
<listitem>
<para>
          Returns the data type associated with the
          given  column number.  The  integer  returned is the
          internal OID number of the type.  Column numbers start
          at 0.
<synopsis>
Oid PQftype(const PGresult *res,
            int column_number);
</synopsis>
</para>

<para>
You can query the system table <literal>pg_type</literal> to obtain
the names and properties of the various data types. The <acronym>OID</acronym>s
of the built-in data types are defined in the file <filename>src/include/catalog/pg_type.h</filename>
in the source tree.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQfmod</function><indexterm><primary>PQfmod</></></term>
<listitem>
<para>
          Returns  the type modifier of the column
          associated with the given column number.
          Column numbers start at 0.
<synopsis>
int PQfmod(const PGresult *res,
           int column_number);
</synopsis>
</para>

<para>
The interpretation of modifier values is type-specific; they typically
indicate precision or size limits.  The value -1 is used to indicate
<quote>no information available</>.  Most data types do not use modifiers,
in which case the value is always -1.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQfsize</function><indexterm><primary>PQfsize</></></term>
<listitem>
<para>
          Returns  the  size  in bytes of the column
          associated with the given column number.
          Column numbers start at 0.
<synopsis>
int PQfsize(const PGresult *res,
            int column_number);
</synopsis>
</para>

<para>
<function>PQfsize</> returns the space allocated for this column in a database
row, in other words the size of the server's internal representation
of the data type.  (Accordingly, it is not really very useful to clients.)
A negative value indicates the data type is variable-length.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQbinaryTuples</function><indexterm><primary>PQbinaryTuples</></></term>
<listitem>
<para>
Returns 1 if the <structname>PGresult</> contains binary data
and 0 if it contains text data.
<synopsis>
int PQbinaryTuples(const PGresult *res);
</synopsis>
</para>

<para>
This function is deprecated (except for its use in connection with
<command>COPY</>), because it is possible for a single
<structname>PGresult</>
to contain text data in some columns and binary data in others.
<function>PQfformat</> is preferred.  <function>PQbinaryTuples</>
returns 1 only if all columns of the result are binary (format 1).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQgetvalue</function><indexterm><primary>PQgetvalue</></></term>
<listitem>
<para>
            Returns a single field value of one row
            of a <structname>PGresult</structname>.
            Row and column numbers start at 0.
<synopsis>
char* PQgetvalue(const PGresult *res,
                 int row_number,
                 int column_number);
</synopsis>
</para>

<para>
For data in text format, the value returned by <function>PQgetvalue</function>
is a null-terminated character string  representation
of the field value.  For data in binary format, the value is in the binary
representation determined by the data type's <function>typsend</> and
<function>typreceive</> functions.  (The value is actually followed by
a zero byte in this case too, but that is not ordinarily useful, since
the value is likely to contain embedded nulls.)
</para>

<para>
An empty string is returned if the field value is null.  See
<function>PQgetisnull</> to distinguish null values from empty-string values.
</para>

<para>
The pointer
returned  by  <function>PQgetvalue</function> points to storage that is
part of the <structname>PGresult</structname> structure.  One should not modify the data it points to,
and one must explicitly 
copy the data into other storage if it is to
be used past the lifetime of the  <structname>PGresult</structname>  structure itself.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQgetisnull</function><indexterm><primary>PQgetisnull</></></term>
<indexterm><primary>null value</><secondary sortas="libpq">in libpq</></indexterm><listitem>
<para>
           Tests a field for a null value.
           Row and column numbers start at 0.
<synopsis>
int PQgetisnull(const PGresult *res,
                int row_number,
                int column_number);
</synopsis>
</para>

<para>
This function returns  1 if the field is null and 0 if
it contains a non-null value.  (Note that <function>PQgetvalue</function>
will return an empty string, not a null pointer, for a null field.)
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQgetlength</function><indexterm><primary>PQgetlength</></></term>
<listitem>
<para>
          Returns the actual length of a field value in bytes.
          Row and column numbers start at 0.
<synopsis>
int PQgetlength(const PGresult *res,
                int row_number,
                int column_number);
</synopsis>
</para>

<para>
This is the actual data length for the particular data value, that is, the
size of the object pointed to by <function>PQgetvalue</function>.  For text
data format this is the same as <function>strlen()</>.  For binary format
this is essential information.  Note that one should <emphasis>not</> rely
on <function>PQfsize</function> to obtain the actual data length.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQprint</function><indexterm><primary>PQprint</></></term>
<listitem>
<para>
          Prints out all the rows and,  optionally,  the
          column names  to  the specified output stream.
<synopsis>
void PQprint(FILE* fout,      /* output stream */
             const PGresult *res,
             const PQprintOpt *po);

typedef 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;   /* attributes for HTML table element */
    char    *caption;    /* HTML table caption */
    char    **fieldName; /* null-terminated array of replacement field names */
} PQprintOpt;
</synopsis>
</para>

<para>
This function was formerly used by <application>psql</application>
to print query results, but this is no longer the case.  Note that it
assumes all the data is in text format.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="libpq-exec-nonselect">
  <title>Retrieving Result Information for Other Commands</title>

<para>
These functions are used to extract information from
<structname>PGresult</structname> objects that are not <command>SELECT</>
results.
</para>

<variablelist>
<varlistentry>
<term><function>PQcmdStatus</function><indexterm><primary>PQcmdStatus</></></term>
<listitem>
<para>
          Returns the command status tag from the SQL command that
          generated the <structname>PGresult</structname>.
<synopsis>
char * PQcmdStatus(PGresult *res);
</synopsis>
</para>
<para>
Commonly this is just the name of the command, but it may include additional
data such as the number of rows processed.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQcmdTuples</function><indexterm><primary>PQcmdTuples</></></term>
<listitem>
<para>
          Returns the number of rows affected by the SQL command.
<synopsis>
char * PQcmdTuples(PGresult *res);
</synopsis>
</para>

<para>
          If the <acronym>SQL</acronym> command that generated the
          <structname>PGresult</structname> was <command>INSERT</>,
          <command>UPDATE</>, <command>DELETE</command>, <command>MOVE</>,
          or <command>FETCH</>, this returns a
          string containing the number of rows affected.  If the
          command was anything else, it returns the empty string.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQoidValue</function><inde