mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-20 19:08:54 +00:00
dad4f149ab
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@291567 c90b9560-bf6c-de11-be94-00142212c4b1
613 lines
16 KiB
XML
613 lines
16 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xml:id="function.oci-fetch-array" xmlns="http://docbook.org/ns/docbook">
|
|
<refnamediv>
|
|
<refname>oci_fetch_array</refname>
|
|
<refpurpose>Returns the next row from a query as an associative or numeric array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>oci_fetch_array</methodname>
|
|
<methodparam><type>resource</type><parameter>statement</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Returns an array containing the next result-set row of a query.
|
|
Each array entry corresponds to a column of the row. This function
|
|
is typically called in a loop until it returns &false;, indicating
|
|
no more rows exist.
|
|
</para>
|
|
&oci.datatypes;
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>statement</parameter></term>
|
|
<listitem>
|
|
&oci.arg.statement.id;
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>mode</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
An optional second parameter can be any combination of the following
|
|
constants:
|
|
<table>
|
|
<title><function>oci_fetch_array</function> Modes</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Constant</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><constant>OCI_BOTH</constant></entry>
|
|
<entry>Returns an array with both associative and numeric
|
|
indices. This is the same
|
|
as <constant>OCI_ASSOC</constant>
|
|
+ <constant>OCI_NUM</constant> and is the default
|
|
behavior.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>OCI_ASSOC</constant></entry>
|
|
<entry>Returns an associative array.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>OCI_NUM</constant></entry>
|
|
<entry>Returns a numeric array.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>OCI_RETURN_NULLS</constant></entry>
|
|
<entry>Creates elements for &null; fields. The element
|
|
values will be a PHP &null;.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>OCI_RETURN_LOBS</constant></entry>
|
|
<entry>Returns the contents of LOBs instead of the LOB
|
|
descriptors.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
<para>
|
|
The default <parameter>mode</parameter> is <constant>OCI_BOTH</constant>.
|
|
</para>
|
|
<para>
|
|
Use the addition operator "+" to specify more than
|
|
one mode at a time.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
Returns an array with associative and/or numeric indices. If there
|
|
are no more rows in the <parameter>statement</parameter> then
|
|
&false; is returned.
|
|
</para>
|
|
<para>
|
|
By default, <literal>LOB</literal> columns are returned as LOB descriptors.
|
|
</para>
|
|
<para>
|
|
<literal>DATE</literal> columns are returned as strings formatted
|
|
to the current date format. The default format can be changed with
|
|
Oracle environment variables such as <literal>NLS_LANG</literal> or
|
|
by a previously executed <literal>ALTER SESSION SET
|
|
NLS_DATE_FORMAT</literal> command.
|
|
</para>
|
|
<para>
|
|
Oracle's default, non-case sensitive column names will have
|
|
uppercase associative indices in the result array. Case-sensitive
|
|
column names will have array indices using the exact column case.
|
|
Use <function>var_dump</function> on the result array to verify the
|
|
appropriate case to use for each query.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title><function>oci_fetch_array</function> with <constant>OCI_BOTH</constant></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
|
|
if (!$conn) {
|
|
$e = oci_error();
|
|
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
|
|
}
|
|
|
|
$stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
|
|
oci_execute($stid);
|
|
|
|
while (($row = oci_fetch_array($stid, OCI_BOTH))) {
|
|
// Use the uppercase column names for the associative array indices
|
|
echo $row[0] . " and " . $row['DEPARTMENT_ID'] . " are the same<br>\n";
|
|
echo $row[1] . " and " . $row['DEPARTMENT_NAME'] . " are the same<br>\n";
|
|
}
|
|
|
|
oci_free_statement($stid);
|
|
oci_close($conn);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>oci_fetch_array</function> with <constant>OCI_NUM</constant></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
/*
|
|
Before running, create the table:
|
|
CREATE TABLE mytab (id NUMBER, description CLOB);
|
|
INSERT INTO mytab (id, description) values (1, 'A very long string');
|
|
COMMIT;
|
|
*/
|
|
|
|
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
|
|
if (!$conn) {
|
|
$e = oci_error();
|
|
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
|
|
}
|
|
|
|
$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
|
|
oci_execute($stid);
|
|
|
|
while (($row = oci_fetch_array($stid, OCI_NUM))) {
|
|
echo $row[0] . "<br>\n";
|
|
echo $row[1]->read(11) . "<br>\n"; // this will output first 11 bytes from DESCRIPTION
|
|
}
|
|
|
|
// Output is:
|
|
// 1
|
|
// A very long
|
|
|
|
oci_free_statement($stid);
|
|
oci_close($conn);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>oci_fetch_array</function> with <constant>OCI_ASSOC</constant></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
/*
|
|
Before running, create the table:
|
|
CREATE TABLE mytab (id NUMBER, description CLOB);
|
|
INSERT INTO mytab (id, description) values (1, 'A very long string');
|
|
COMMIT;
|
|
*/
|
|
|
|
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
|
|
if (!$conn) {
|
|
$e = oci_error();
|
|
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
|
|
}
|
|
|
|
$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
|
|
oci_execute($stid);
|
|
|
|
while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
|
|
echo $row['ID'] . "<br>\n";
|
|
echo $row['DESCRIPTION']->read(11) . "<br>\n"; // this will output first 11 bytes from DESCRIPTION
|
|
}
|
|
|
|
// Output is:
|
|
// 1
|
|
// A very long
|
|
|
|
oci_free_statement($stid);
|
|
oci_close($conn);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>oci_fetch_array</function> with <constant>OCI_RETURN_NULLS</constant></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
|
|
if (!$conn) {
|
|
$e = oci_error();
|
|
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
|
|
}
|
|
|
|
$stid = oci_parse($conn, 'SELECT 1, null FROM dual');
|
|
oci_execute($stid);
|
|
while (($row = oci_fetch_array ($stid, OCI_ASSOC))) { // Ignore NULLs
|
|
var_dump($row);
|
|
}
|
|
|
|
/*
|
|
The above code prints:
|
|
array(1) {
|
|
[1]=>
|
|
string(1) "1"
|
|
}
|
|
*/
|
|
|
|
$stid = oci_parse($conn, 'SELECT 1, null FROM dual');
|
|
oci_execute($stid);
|
|
while (($row = oci_fetch_array ($stid, OCI_ASSOC+OCI_RETURN_NULLS))) { // Fetch NULLs
|
|
var_dump($row);
|
|
}
|
|
|
|
/*
|
|
The above code prints:
|
|
array(2) {
|
|
[1]=>
|
|
string(1) "1"
|
|
["NULL"]=>
|
|
NULL
|
|
}
|
|
*/
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>oci_fetch_array</function> with <constant>OCI_RETURN_LOBS</constant></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
/*
|
|
Before running, create the table:
|
|
CREATE TABLE mytab (id NUMBER, description CLOB);
|
|
INSERT INTO mytab (id, description) values (1, 'A very long string');
|
|
COMMIT;
|
|
*/
|
|
|
|
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
|
|
if (!$conn) {
|
|
$e = oci_error();
|
|
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
|
|
}
|
|
|
|
$stid = oci_parse($conn, 'SELECT id, description FROM mytab');
|
|
oci_execute($stid);
|
|
|
|
while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS))) {
|
|
echo $row['ID'] . "<br>\n";
|
|
echo $row['DESCRIPTION'] . "<br>\n"; // this contains all of DESCRIPTION
|
|
}
|
|
|
|
// Output is:
|
|
// 1
|
|
// A very long string
|
|
|
|
oci_free_statement($stid);
|
|
oci_close($conn);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>oci_fetch_array</function> with case sensitive column names</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
/*
|
|
Before running, create the table:
|
|
CREATE TABLE mytab ("Name" VARCHAR2(20), city VARCHAR2(20));
|
|
INSERT INTO mytab ("Name", city) values ('Chris', 'Melbourne');
|
|
COMMIT;
|
|
*/
|
|
|
|
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
|
|
if (!$conn) {
|
|
$e = oci_error();
|
|
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
|
|
}
|
|
|
|
$stid = oci_parse($conn, 'select * from mytab');
|
|
oci_execute($stid);
|
|
$row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
|
|
|
|
// Because 'Name' was created as a case-sensitive column, that same
|
|
// case is used for the array index. However uppercase 'CITY' must
|
|
// be used for the case-insensitive column index
|
|
print $row['Name'] . "<br>\n"; // prints Chris
|
|
print $row['CITY'] . "<br>\n"; // prints Melbourne
|
|
|
|
oci_free_statement($stid);
|
|
oci_close($conn);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>oci_fetch_array</function> with columns having duplicate names</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
/*
|
|
Before running, create the tables:
|
|
CREATE TABLE mycity (id NUMBER, name VARCHAR2(20));
|
|
INSERT INTO mycity (id, name) values (1, 'Melbourne');
|
|
CREATE TABLE mycountry (id NUMBER, name VARCHAR2(20));
|
|
INSERT INTO mycountry (id, name) values (1, 'Australia');
|
|
COMMIT;
|
|
*/
|
|
|
|
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
|
|
if (!$conn) {
|
|
$e = oci_error();
|
|
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
|
|
}
|
|
|
|
$sql = 'SELECT mycity.name, mycountry.name
|
|
FROM mycity, mycountry
|
|
WHERE mycity.id = mycountry.id';
|
|
$stid = oci_parse($conn, $sql);
|
|
oci_execute($stid);
|
|
$row = oci_fetch_array($stid, OCI_ASSOC);
|
|
var_dump($row);
|
|
|
|
// Output only contains one "NAME" entry:
|
|
// array(1) {
|
|
// ["NAME"]=>
|
|
// string(9) "Australia"
|
|
// }
|
|
|
|
// To query a repeated column name, use a SQL column alias like "AS ctnm":
|
|
$sql = 'SELECT mycity.name AS ctnm, mycountry.name
|
|
FROM mycity, mycountry
|
|
WHERE mycity.id = mycountry.id';
|
|
$stid = oci_parse($conn, $sql);
|
|
oci_execute($stid);
|
|
$row = oci_fetch_array($stid, OCI_ASSOC);
|
|
var_dump($row);
|
|
|
|
// Output now contains both columns selected:
|
|
// array(2) {
|
|
// ["CTNM"]=>
|
|
// string(9) "Melbourne"
|
|
// ["NAME"]=>
|
|
// string(9) "Australia"
|
|
// }
|
|
|
|
|
|
oci_free_statement($stid);
|
|
oci_close($conn);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>oci_fetch_array</function> with <literal>DATE</literal> columns</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
|
|
if (!$conn) {
|
|
$e = oci_error();
|
|
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
|
|
}
|
|
|
|
// Set the date format for this connection.
|
|
// For performance reasons, consider changing the format
|
|
// in a trigger or with environment variables instead
|
|
$stid = oci_parse($conn, "ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD'");
|
|
oci_execute($stid);
|
|
|
|
$stid = oci_parse($conn, 'SELECT hire_date FROM employees WHERE employee_id = 188');
|
|
oci_execute($stid);
|
|
$row = oci_fetch_array($stid, OCI_ASSOC);
|
|
echo $row['HIRE_DATE'] . "<br>\n"; // prints 1997-06-14
|
|
|
|
oci_free_statement($stid);
|
|
oci_close($conn);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>oci_fetch_array</function> with <literal>REF CURSOR</literal></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/*
|
|
Create the PL/SQL stored procedure as:
|
|
|
|
CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
|
|
BEGIN
|
|
OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
|
|
END;
|
|
*/
|
|
|
|
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
|
|
if (!$conn) {
|
|
$e = oci_error();
|
|
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
|
|
}
|
|
|
|
$stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
|
|
$refcur = oci_new_cursor($conn);
|
|
oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
|
|
oci_execute($stid);
|
|
|
|
// Execute the returned REF CURSOR and fetch from it like a statement identifier
|
|
oci_execute($refcur);
|
|
echo "<table border='1'>\n";
|
|
while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) {
|
|
echo "<tr>\n";
|
|
foreach ($row as $item) {
|
|
echo " <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : " ")."</td>\n";
|
|
}
|
|
echo "</tr>\n";
|
|
}
|
|
echo "</table>\n";
|
|
|
|
oci_free_statement($refcur);
|
|
oci_free_statement($stid);
|
|
oci_close($conn);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>oci_fetch_array</function> with a <literal>LIMIT</literal>-like query</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
|
|
if (!$conn) {
|
|
$e = oci_error();
|
|
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
|
|
}
|
|
|
|
// This is the query you want to execute
|
|
$sql = 'SELECT city, postal_code FROM locations ORDER BY city';
|
|
|
|
// This nested query selects a subset of rows from $sql.
|
|
// In production environments, be careful to avoid SQL Injection
|
|
// issues with concatenated SQL statements
|
|
$limit_sql =
|
|
'select *
|
|
from ( select a.*, rownum as rnum
|
|
from (' . $sql . ') a
|
|
where rownum < :FIRST_ROW + :NUM_ROWS )
|
|
where rnum >= :FIRST_ROW';
|
|
|
|
$first = 1; // start with the first row
|
|
$num = 5; // return 5 rows
|
|
$stid = oci_parse($conn, $limit_sql);
|
|
oci_bind_by_name($stid, ':FIRST_ROW', $first);
|
|
oci_bind_by_name($stid, ':NUM_ROWS', $num);
|
|
oci_execute($stid);
|
|
|
|
while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
|
|
echo $row['CITY'] . " " . $row['POSTAL_CODE'] . "<br>\n";
|
|
}
|
|
|
|
// Output is:
|
|
// Beijing 190518x
|
|
// Bern 3095x
|
|
// Bombay 490231x
|
|
// Geneva 1730x
|
|
// Hiroshima 6823x
|
|
|
|
oci_free_statement($stid);
|
|
oci_close($conn);
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
<note>
|
|
<para>
|
|
Associative array indices need to be in uppercase for standard
|
|
Oracle columns that were created with case insensitive names.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
&oci.use.setprefetch;
|
|
</note>
|
|
<note>
|
|
<para>
|
|
The function <function>oci_fetch_array</function>
|
|
is <emphasis>insignificantly</emphasis> slower than
|
|
<function>oci_fetch_assoc</function>
|
|
or <function>oci_fetch_row</function>, but is more flexible.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>oci_fetch</function></member>
|
|
<member><function>oci_fetch_all</function></member>
|
|
<member><function>oci_fetch_assoc</function></member>
|
|
<member><function>oci_fetch_object</function></member>
|
|
<member><function>oci_fetch_row</function></member>
|
|
<member><function>oci_set_prefetch</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
|
|
-->
|
|
|