<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.18 $ -->
<!-- splitted from ./en/functions/dbx.xml, last change in rev 1.3 -->
  <refentry id="function.dbx-query">
   <refnamediv>
    <refname>dbx_query</refname>
    <refpurpose>Send a query and fetch all results (if any)</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>dbx_query</methodname>
      <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam>
      <methodparam><type>string</type><parameter>sql_statement</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <function>dbx_query</function> returns an object or <literal>1</literal> 
     on success, and <literal>0</literal> on failure. The result object is 
     returned only if the query given in <parameter>sql_statement</parameter>
     produces a result set (i.e. a SELECT query, even if the result set is
     empty). 
    </simpara>
    <example>
     <title>How to handle the returned value</title>
     <programlisting role="php">
<![CDATA[
<?php
$link   = dbx_connect(DBX_ODBC, "", "db", "username", "password")
    or die("Could not connect");

$result = dbx_query($link, 'SELECT id, parentid, description FROM table');

if (is_object($result) ) {
    // ... do some stuff here, see detailed examples below ...
    // first, print out field names and types 
    // then, draw a table filled with the returned field values
} else {
    exit("Query failed");
}

dbx_close($link);
?>
]]>
     </programlisting>
    </example>
    <para>
     The <parameter>flags</parameter> parameter is used to control the amount of
     information that is returned. It may be any combination of the following 
     constants with the bitwise OR operator (|). The DBX_COLNAMES_* flags 
     override the dbx.colnames_case setting from &php.ini;.
     <variablelist>
      <varlistentry>
       <term>
        <constant>DBX_RESULT_INDEX</constant>
       </term>
       <listitem>
        <simpara>
         It is <emphasis>always</emphasis> set, that is, the returned object 
         has a <property>data</property> property which is a 2 dimensional
         array indexed numerically. For example, in the expression 
         <literal>data[2][3]</literal> <literal>2</literal> stands for the row
         (or record) number and <literal>3</literal> stands for the column 
         (or field) number. The first row and column are indexed at 0.
        </simpara>
        <simpara>
         If <constant>DBX_RESULT_ASSOC</constant> is also specified, the 
         returning object contains the information related to 
         <constant>DBX_RESULT_INFO</constant> too, even if it was not specified. 
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <constant>DBX_RESULT_INFO</constant>
       </term>
       <listitem>
        <simpara>
         It provides info about columns, such as field names and field types.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <constant>DBX_RESULT_ASSOC</constant>
       </term>
       <listitem>
        <simpara>
         It effects that the field values can be accessed with the respective 
         column names used as keys to the returned object's 
         <property>data</property> property.
        </simpara>
        <simpara>
         Associated results are actually references to the numerically indexed 
         data, so modifying <literal>data[0][0]</literal> causes that
         <literal>data[0]['field_name_for_first_column']</literal> is modified
         as well.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <constant>DBX_RESULT_UNBUFFERED</constant> (PHP 5)
       </term>
       <listitem>
        <simpara>
         This flag will not create the <property>data</property> property, and 
         the <property>rows</property> property will initially be 0. Use this 
         flag for large datasets, and use <function>dbx_fetch_row</function> to
         retrieve the results row by row.
        </simpara>
        <simpara>
         The <function>dbx_fetch_row</function> function will return rows that
         are conformant to the flags set with this query. Incidentally, it will
         also update the <property>rows</property> each time it is called.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <constant>DBX_COLNAMES_UNCHANGED</constant> (available from PHP 4.3.0)
       </term>
       <listitem>
        <simpara>
         The case of the returned column names will not be changed.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <constant>DBX_COLNAMES_UPPERCASE</constant> (available from PHP 4.3.0)
       </term>
       <listitem>
        <simpara>
         The case of the returned column names will be changed to 
         uppercase.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <constant>DBX_COLNAMES_LOWERCASE</constant> (available from PHP 4.3.0)
       </term>
       <listitem>
        <simpara>
         The case of the returned column names will be changed to 
         lowercase.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
     Note that <constant>DBX_RESULT_INDEX</constant> is always used, regardless 
     of the actual value of <parameter>flags</parameter> parameter. This means 
     that only the following combinations are effective:
     <itemizedlist>
      <listitem>
       <simpara>
        <constant>DBX_RESULT_INDEX</constant>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_RESULT_INDEX</constant> |
        <constant>DBX_RESULT_INFO</constant>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_RESULT_INDEX</constant> |
        <constant>DBX_RESULT_INFO</constant> |
        <constant>DBX_RESULT_ASSOC</constant> - this is the default, if 
        <parameter>flags</parameter> is not specified.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     The returned <varname>object</varname> has four or five
     properties depending on <parameter>flags</parameter>:
     <variablelist>
      <varlistentry>
       <term>
        <property>handle</property>
       </term>
       <listitem>
        <para>
         It is a valid handle for the connected database, and as such it can be
         used in module specific functions (if required).
         <informalexample>
          <programlisting role="php">
<![CDATA[
<?php
$result = dbx_query($link, "SELECT id FROM table");
mysql_field_len($result->handle, 0);
?>
]]>
          </programlisting>
         </informalexample>
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>cols</property> and <property>rows</property>
       </term>
       <listitem>
        <para>
         These contain the number of columns (or fields) and rows (or records)
         respectively.
         <informalexample>
          <programlisting role="php">
<![CDATA[
<?php
$result = dbx_query($link, 'SELECT id FROM table');
echo $result->rows; // number of records
echo $result->cols; // number of fields 
?>
]]>
          </programlisting>
         </informalexample>
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>info</property> (optional)
       </term>
       <listitem>
        <simpara>
         It is returned only if either <constant>DBX_RESULT_INFO</constant> or
         <constant>DBX_RESULT_ASSOC</constant> is specified in the
         <parameter>flags</parameter> parameter. It is a 2 dimensional array,
         that has two named rows (<literal>name</literal> and 
         <literal>type</literal>) to retrieve column information.
        </simpara>
        <example>
         <title>lists each field's name and type</title>
         <programlisting role="php">
<![CDATA[
<?php
$result = dbx_query($link, 'SELECT id FROM table',
                     DBX_RESULT_INDEX | DBX_RESULT_INFO);

for ($i = 0; $i < $result->cols; $i++ ) {
    echo $result->info['name'][$i] . "\n";
    echo $result->info['type'][$i] . "\n";  
}
?>
]]>
         </programlisting>
        </example>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>data</property>
       </term>
       <listitem>
        <simpara>
         This property contains the actual resulting data, possibly associated 
         with column names as well depending on <parameter>flags</parameter>.
         If <constant>DBX_RESULT_ASSOC</constant> is set, it is possible to use
         <literal>$result->data[2]["field_name"]</literal>.
        </simpara>
        <example>
         <title>outputs the content of data property into HTML table</title>
         <programlisting role="php">
<![CDATA[
<?php
$result = dbx_query($link, 'SELECT id, parentid, description FROM table');

echo "<table>\n";
foreach ($result->data as $row) {
    echo "<tr>\n";
    foreach ($row as $field) {
        echo "<td>$field</td>";
    }
    echo "</tr>\n";
}
echo "</table>\n";
?>
]]>
         </programlisting>
        </example>
        <example>
         <title>How to handle UNBUFFERED queries</title>
         <programlisting role="php">
<![CDATA[
<?php

$result = dbx_query ($link, 'SELECT id, parentid, description FROM table', DBX_RESULT_UNBUFFERED);

echo "<table>\n";
while ($row = dbx_fetch_row($result)) {
    echo "<tr>\n";
    foreach ($row as $field) {
        echo "<td>$field</td>";
    }
    echo "</tr>\n";
}
echo "</table>\n";

?>
]]>
         </programlisting>
        </example>
      </listitem>
      </varlistentry>
     </variablelist>
    </para>
    <note>
     <para>
      Always refer to the module-specific documentation as well.
     </para>
     <para>
      Column names for queries on an Oracle database are returned
      in lowercase.
     </para>
    </note>
    <para>
     See also <function>dbx_escape_string</function>, 
     <function>dbx_fetch_row</function> and 
     <function>dbx_connect</function>.
    </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:"../../../../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
-->