<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mysqli-result.fetch-fields" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysqli_result::fetch_fields</refname>
  <refname>mysqli_fetch_fields</refname>
  <refpurpose>Returns an array of objects representing the fields in a result set</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>&style.oop;</para>
  <methodsynopsis role="oop">
   <type>array</type><methodname>mysqli_result::fetch_fields</methodname>
   <void/>
  </methodsynopsis>
  <para>&style.procedural;</para>
  <methodsynopsis>
   <type>array</type><methodname>mysqli_fetch_fields</methodname>
   <methodparam><type>mysqli_result</type><parameter>result</parameter></methodparam>
  </methodsynopsis>

  <para>
   This function serves an identical purpose to the 
   <function>mysqli_fetch_field</function> function with the single
   difference that, instead of returning one object at a time for each field,
   the columns are returned as an array of objects.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &mysqli.result.description;
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an array of objects which contains field definition information or
   &false; if no field information is available.
  </para>
  <para>
  <table>
   <title>Object properties</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Property</entry>
      <entry>Description</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>name</entry>
      <entry>The name of the column</entry>
     </row>
     <row>
      <entry>orgname</entry>
      <entry>Original column name if an alias was specified</entry>
     </row>
     <row>
      <entry>table</entry>
      <entry>The name of the table this field belongs to (if not calculated)</entry>
     </row>
     <row>
      <entry>orgtable</entry>
      <entry>Original table name if an alias was specified</entry>
     </row>
     <row>
      <entry>max_length</entry>
      <entry>The maximum width of the field for the result set.</entry>
     </row>
     <row>
      <entry>length</entry>
      <entry>
       The width of the field, in bytes, as specified in the table definition. Note that 
       this number (bytes) might differ from your table definition value (characters), depending on
       the character set you use. For example, the character set utf8 has 3 bytes per character, 
       so varchar(10) will return a length of 30 for utf8 (10*3), but return 10 for latin1 (10*1).
      </entry>
     </row>
     <row>
      <entry>charsetnr</entry>
      <entry>The character set number (id) for the field.</entry>
     </row>
     <row>
      <entry>flags</entry>
      <entry>An integer representing the bit-flags for the field.</entry>
     </row>
     <row>
      <entry>type</entry>
      <entry>The data type used for this field</entry>
     </row>
     <row>
      <entry>decimals</entry>
      <entry>The number of decimals used (for integer fields)</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>&style.oop;</title>
   <programlisting role="php">
<![CDATA[
<?php
$mysqli = new mysqli("127.0.0.1", "root", "foofoo", "sakila");

/* check connection */
if ($mysqli->connect_errno) {
    printf("Connect failed: %s\n", $mysqli->connect_error);
    exit();
}

foreach (array('latin1', 'utf8') as $charset) {

    // Set character set, to show its impact on some values (e.g., length in bytes)
    $mysqli->set_charset($charset);

    $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

    echo "======================\n";
    echo "Character Set: $charset\n";
    echo "======================\n";
    
    if ($result = $mysqli->query($query)) {

        /* Get field information for all columns */
        $finfo = $result->fetch_fields();

        foreach ($finfo as $val) {
            printf("Name:      %s\n",   $val->name);
            printf("Table:     %s\n",   $val->table);
            printf("Max. Len:  %d\n",   $val->max_length);
            printf("Length:    %d\n",   $val->length);
            printf("charsetnr: %d\n",   $val->charsetnr);
            printf("Flags:     %d\n",   $val->flags);
            printf("Type:      %d\n\n", $val->type);
        }
        $result->free();
    }
}
$mysqli->close();
?>
]]>
   </programlisting>
  </example>
  <example>
   <title>&style.procedural;</title>
   <programlisting role="php">
<![CDATA[
<?php
$link = mysqli_connect("127.0.0.1", "my_user", "my_password", "sakila");

/* check connection */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

foreach (array('latin1', 'utf8') as $charset) {

    // Set character set, to show its impact on some values (e.g., length in bytes)
    mysqli_set_charset($link, $charset);

    $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

    echo "======================\n";
    echo "Character Set: $charset\n";
    echo "======================\n";

    if ($result = mysqli_query($link, $query)) {

        /* Get field information for all columns */
        $finfo = mysqli_fetch_fields($result);

        foreach ($finfo as $val) {
            printf("Name:      %s\n",   $val->name);
            printf("Table:     %s\n",   $val->table);
            printf("Max. Len:  %d\n",   $val->max_length);
            printf("Length:    %d\n",   $val->length);
            printf("charsetnr: %d\n",   $val->charsetnr);
            printf("Flags:     %d\n",   $val->flags);
            printf("Type:      %d\n\n", $val->type);
        }
        mysqli_free_result($result);
    }
}

mysqli_close($link);
?>
]]>
   </programlisting>
   &examples.outputs;
   <screen>
<![CDATA[
======================
Character Set: latin1
======================
Name:      actor_id
Table:     actor
Max. Len:  3
Length:    5
charsetnr: 63
Flags:     49699
Type:      2

Name:      last_name
Table:     actor
Max. Len:  12
Length:    45
charsetnr: 8
Flags:     20489
Type:      253

======================
Character Set: utf8
======================
Name:      actor_id
Table:     actor
Max. Len:  3
Length:    5
charsetnr: 63
Flags:     49699
Type:      2

Name:      last_name
Table:     actor
Max. Len:  12
Length:    135
charsetnr: 33
Flags:     20489
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mysqli_num_fields</function></member>
    <member><function>mysqli_fetch_field_direct</function></member>
    <member><function>mysqli_fetch_field</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
-->