<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Executes a given SQL query against a relational database
and returns the results as a normalised data graph.</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="sdo-das-relational.executepreparedquery.html">SDO_DAS_Relational::executePreparedQuery</a></div>
<div class="next" style="text-align: right; float: right;"><a href="book.sdo-das-xml.html">SDO DAS XML</a></div>
<div class="up"><a href="ref.sdodasrel.html">SDO-DAS-Relational Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="sdo-das-relational.executequery" class="refentry">
<div class="refnamediv">
<h1 class="refname">SDO_DAS_Relational::executeQuery</h1>
<p class="verinfo">(^)</p><p class="refpurpose"><span class="refname">SDO_DAS_Relational::executeQuery</span> — <span class="dc-title">
Executes a given SQL query against a relational database
and returns the results as a normalised data graph.
</span></p>
</div>
<div class="refsect1 description" id="refsect1-sdo-das-relational.executequery-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type"><span class="type SDODataObject">SDODataObject</span></span>
<span class="methodname"><strong>SDO_DAS_Relational::executeQuery</strong></span>
( <span class="methodparam">
<span class="type"><a href="class.pdo.html" class="type PDO">PDO</a></span>
<code class="parameter">$database_handle</code>
</span>
, <span class="methodparam">
<span class="type">string</span>
<code class="parameter">$SQL_statement</code>
</span>
[, <span class="methodparam">
<span class="type">array</span>
<code class="parameter">$column_specifier</code>
</span>
] )</div>
<div class="warning"><strong class="warning">Warning</strong><p class="simpara">This function is
<em class="emphasis">EXPERIMENTAL</em>. The behaviour of this function, its name, and
surrounding documentation may change without notice in a future release of PHP.
This function should be used at your own risk.
</p></div>
<p class="para">
Executes a given query against the relational database,
using the supplied PDO database handle.
Uses the model that it built from the metadata
to interpret the result set.
Returns a data graph.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-sdo-das-relational.executequery-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term">PDO_database_handle</span>
<dd>
<p class="para">
Constructed using the PDO extension.
A typical line to construct a PDO database handle might look
like this:
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD);</span>
</code></div>
</div>
</p>
</dd>
</dt>
<dt>
<span class="term">SQL_statement</span>
<dd>
<p class="para">
The SQL statement to be executed against the database.
</p>
</dd>
</dt>
<dt>
<span class="term">column_specifier</span>
<dd>
<p class="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
<var class="varname"><var class="varname">table-name.column_name</var></var>.
</p>
<p class="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
<var class="varname"><var class="varname">id</var></var>
and a
<var class="varname"><var class="varname">name</var></var>
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.
</p>
<p class="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.
</p>
<p class="para">
All of the examples in the
<a href="sdodasrel.examples.html" class="link">Examples</a>
use a column specifier.
There is one example in the
<var class="filename">Scenarios</var>
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.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-sdo-das-relational.executequery-returnvalues">
<h3 class="title">Return Values</h3>
<p class="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.
</p>
<p class="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.
</p>
</div>
<div class="refsect1 errors" id="refsect1-sdo-das-relational.executequery-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
<span class="function"><strong>SDO_DAS_Relational::executeQuery()</strong></span>
can throw an <strong class="classname">SDO_DAS_Relational_Exception</strong> 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
<strong class="classname">SDO_DAS_Relational_Exception</strong> which it then throws.
</p>
</div>
<div class="refsect1 examples" id="refsect1-sdo-das-relational.executequery-examples">
<h3 class="title">Examples</h3>
<p class="para">
Please see the
<a href="sdodasrel.examples.html" class="link">Examples</a>
section in the general information about the
Relational DAS for many examples of calling this method.
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="sdo-das-relational.executepreparedquery.html">SDO_DAS_Relational::executePreparedQuery</a></div>
<div class="next" style="text-align: right; float: right;"><a href="book.sdo-das-xml.html">SDO DAS XML</a></div>
<div class="up"><a href="ref.sdodasrel.html">SDO-DAS-Relational Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
