<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.22 $ -->
<refentry xml:id="function.dbx-query" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>dbx_query</refname>
  <refpurpose>Send a query and fetch all results (if any)</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <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>
  <para>
   Sends a query and fetch all results.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>link_identifier</parameter></term>
     <listitem>
      <para>
       The DBX link object returned by <function>dbx_connect</function>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>sql_statement</parameter></term>
     <listitem>
      <para>
       SQL statement.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <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>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <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). 
  </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>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <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>
 </refsect1>
 <refsect1 role="notes">
  &reftitle.notes;
  <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>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>dbx_escape_string</function></member>
    <member><function>dbx_fetch_row</function></member>
    <member><function>dbx_connect</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:"../../../../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
-->