php-doc-en/reference/sdodasrel/functions/SDO-DAS-Relational-executeQuery.xml

<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.8 $ -->
<refentry xml:id="function.SDO-DAS-Relational-executeQuery" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>SDO_DAS_Relational::executeQuery</refname>
  <refpurpose>
	    Executes a given SQL query against a relational database 
        and returns the results as a normalised data graph.
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>SDODataObject</type>
   <methodname>SDO_DAS_Relational::executeQuery</methodname>
   <methodparam>
    <type>PDO</type>
    <parameter>database_handle</parameter>
   </methodparam>
   <methodparam>
    <type>string</type>
    <parameter>SQL_statement</parameter>
   </methodparam>
   <methodparam choice="opt">
    <type>array</type>
    <parameter>column_specifier</parameter>
   </methodparam>
  </methodsynopsis>
	
	  &warn.experimental.func;
	
  <para>
   Executes a given query against the relational database, 
   using the supplied PDO database handle.
   Uses the model that it built from the the metadata 
   to interpret the result set.
   Returns a data graph.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term>PDO_database_handle</term>
     <listitem>
      <para>
       Constructed using the PDO extension. 
       A typical line to construct a PDO database handle might look 
       like this:
       <programlisting role="php" xml:id="sdo.das.rel.eq.examples.pdo">
<![CDATA[
$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD);
]]>
       </programlisting>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>SQL_statement</term>
     <listitem>
      <para>
       The SQL statement to be executed against the database.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>column_specifier</term>
     <listitem>
      <para>
       The Relational DAS needs to examine the result set and 
       for every column, know which table and which column of 
       that table it came from.
       In some circumstances it can find this information for itself, 
       but sometimes it cannot.
       In these cases a column specifier is needed, 
       which is an array that identifies the columns.
       Each entry in the array is simply a string in the form
       <varname>table-name.column_name</varname>.
      </para>
	          

      <para>
       The column specifier is needed when there are duplicate 
       column names in the database metadata.
       For example, in the database used within the examples, 
       all the tables have both a
       <varname>id</varname>
       and a
       <varname>name</varname>
       column.
       When the Relational DAS fetches the result set from PDO 
       it can do so with the PDO_FETCH_ASSOC attribute, 
       which will cause the columns in the results set 
       to be labelled with  the column name, but will not distinguish 
       duplicates.
       So this will only work when there are no duplicates 
       possible in the results set.
      </para>
	          
      <para>
       To summarise, specify a column specifier array whenever there 
       is any uncertainty about which column could be from which table and
       only omit it when every column name in the database metadata is unique.
      </para>
	          
      <para>
       All of the examples in the
       <link linkend='sdo.das.rel.examples'>Examples</link>
       use a column specifier.
       There is one example in the
       <filename>Scenarios</filename>
       directory of the installation that does not: 
       that which works with just the employee table, 
       and because it works with just one table, 
       there can not exist duplicate column names.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a data graph. 
   Specifically, it returns a root object of a special type.
   Under this root object will be the data from the result set.
   The root object will have a multi-valued containment property 
   with the same name as the application root type 
   specified on the constructor,
   and that property will contain one or more data objects 
   of the application root type.
  </para>
  <para>
   In the event that the query returns no data, 
   the special root object will still be returned but 
   the containment property for the application root type will be empty.
  </para>
 </refsect1>
	
 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   <function>SDO_DAS_Relational::executeQuery</function>
   can throw an SDO_DAS_Relational_Exception if it is unable 
   to construct the data graph correctly.
   This can occur for a  number of reasons: 
   for example if it finds that it does not have primary keys 
   in the result set for all the objects.
   It also catches any PDO exceptions and obtains PDO 
   diagnostic information which it includes in an 
   SDO_DAS_Relational_Exception which it then throws.
  </para>
 </refsect1>
	
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   Please see the
   <link linkend='sdo.das.rel.examples'>Examples</link>
   section in the general information about the 
   Relational DAS for many examples of calling this method.
  </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
-->