pg-fetch-array.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.pg-fetch-array" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>pg_fetch_array</refname>
  <refpurpose>Fetch a row as an array</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>pg_fetch_array</methodname>
   <methodparam><type>PgSql\Result</type><parameter>result</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>row</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer><constant>PGSQL_BOTH</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>pg_fetch_array</function> returns an array that
   corresponds to the fetched row (record).
  </para>
  <para>
   <function>pg_fetch_array</function> is an extended version of
   <function>pg_fetch_row</function>.  In addition to storing the
   data in the numeric indices (field number) to the result array, it
   can also store the data using associative indices (field name).
   It stores both indices by default.
  </para>
  &database.fetch-null;
  <para>
   <function>pg_fetch_array</function> is NOT significantly
   slower than using <function>pg_fetch_row</function>, and
   is significantly easier to use.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>result</parameter></term>
     <listitem>
      &pgsql.parameter.result;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>row</parameter></term>
     <listitem>
      <para>
       Row number in result to fetch. Rows are numbered from 0 upwards. If
       omitted or &null;, the next row is fetched.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      &pgsql.parameter.mode;
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   An <type>array</type> indexed numerically (beginning with 0) or
   associatively (indexed by field name), or both.
   Each value in the <type>array</type> is represented as a 
   <type>string</type>.  Database <literal>NULL</literal>
   values are returned as &null;.
  </para>
  <para>
   &false; is returned if <parameter>row</parameter> exceeds the number
   of rows in the set, there are no more rows, or on any other error.
   Fetching from the result of a query other than SELECT will also return &false;.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     &pgsql.changelog.result-object;
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>pg_fetch_array</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php 

$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
  echo "An error occurred.\n";
  exit;
}

$result = pg_query($conn, "SELECT author, email FROM authors");
if (!$result) {
  echo "An error occurred.\n";
  exit;
}

$arr = pg_fetch_array($result, 0, PGSQL_NUM);
echo $arr[0] . " <- Row 1 Author\n";
echo $arr[1] . " <- Row 1 E-mail\n";

// The row parameter is optional; NULL can be passed instead,
// to pass a result_type.  Successive calls to pg_fetch_array
// will return the next row.
$arr = pg_fetch_array($result, NULL, PGSQL_ASSOC);
echo $arr["author"] . " <- Row 2 Author\n";
echo $arr["email"] . " <- Row 2 E-mail\n";

$arr = pg_fetch_array($result);
echo $arr["author"] . " <- Row 3 Author\n";
echo $arr[1] . " <- Row 3 E-mail\n";

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>pg_fetch_row</function></member>
    <member><function>pg_fetch_object</function></member>
    <member><function>pg_fetch_result</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->