php-doc-en/reference/pgsql/functions/pg-fetch-array.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.pg-fetch-array">
 <refnamediv>
  <refname>pg_fetch_array</refname>
  <refpurpose>Fetch a row as an array</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>pg_fetch_array</methodname>
   <methodparam><type>resource</type><parameter>result</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>row</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>result_type</parameter></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 indicies 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>
      <para>
       PostgreSQL query result resource, returned by <function>pg_query</function>,
       <function>pg_query_params</function> or <function>pg_execute</function>
       (among others).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>row</parameter></term>
     <listitem>
      <para>
       Row number in result to fetch.  Rows are numbered from 0 upwards.  If omitted,
       next row is fetched.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>result_type</parameter></term>
     <listitem>
      <para>
       An optional parameter that controls
       how the returned <type>array</type> is indexed.
       <parameter>result_type</parameter> is a constant and can take the
       following values: <constant>PGSQL_ASSOC</constant>, 
       <constant>PGSQL_NUM</constant> and <constant>PGSQL_BOTH</constant>.
       Using <constant>PGSQL_NUM</constant>, <function>pg_fetch_array</function>
       will return an array with numerical indices, using
       <constant>PGSQL_ASSOC</constant> it will return only associative indices
       while <constant>PGSQL_BOTH</constant>, the default, will return both
       numerical and associative indices.
      </para>
     </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.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4.1.0</entry>
       <entry>
        The <parameter>row</parameter> parameter became optional.
       </entry>
      </row>
      <row>
       <entry>4.0.0</entry>
       <entry>
        The <parameter>result_type</parameter> parameter was added.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </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 occured.\n";
  exit;
}

$result = pg_query($conn, "SELECT author, email FROM authors");
if (!$result) {
  echo "An error occured.\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";

// As of PHP 4.1.0, 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
-->