oci-fetch-array.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e85d788eabb67456a5101afd7b994b69a495af4f Maintainer: seros Status: ready -->
<!-- Reviewed: yes Maintainer: seros -->
<refentry xml:id="function.oci-fetch-array" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>oci_fetch_array</refname>
  <refpurpose>Devuelve la siguiente fila de una consulta como un array asociativo o numérico
  </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>
   Devuelve un array que contiene la siguiente fila del conjunto de resultados de una consulta.
   Cada entrada del array corresponde a una columna de la fila. Esta función
   se invoca normamente en un bucle hasta que devuelva &false;, indicando
   que no existen más filas.
  </para>
  <para>
   Si <parameter>statement</parameter> se corresponde con un bloque de PL/SQL
   devuelto por Conjuntos de Resultados Implícitos de Oracle Database 12c, entonces las filas
   de todos los conjuntos se obtienen consecutivamente. Si
   <parameter>statement</parameter> es devuelto por
   <function>oci_get_implicit_resultset</function>, solamente son
   devueltos los subconjuntos de filas para una consulta hija.
  </para>
  &oci.datatypes;
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>statement</parameter></term>
     <listitem>
      &oci.arg.statement.id;
      <para>
       También puede ser un identificador de sentencia devuelto por <function>oci_get_implicit_resultset</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       Este segundo parámetro opcional puede ser cualquier combinación de las siguientes
       contantes:
       <table>
        <title>Modos de <function>oci_fetch_array</function></title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Constante</entry>
           <entry>Descripción</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>OCI_BOTH</constant></entry>
           <entry>Devuelve un array con índices tanto asociativos como
            numéricos. Es lo mismo que
            con <constant>OCI_ASSOC</constant>
            + <constant>OCI_NUM</constant>. Es el comportamiento
            predeterminado.</entry>
          </row>
          <row>
           <entry><constant>OCI_ASSOC</constant></entry>
           <entry>Devuelve un array asociativo.</entry>
          </row>
          <row>
           <entry><constant>OCI_NUM</constant></entry>
           <entry>Devuelve un array numérico.</entry>
          </row>
          <row>
           <entry><constant>OCI_RETURN_NULLS</constant></entry>
           <entry>Crea elementos para campos &null;. Los valores
            de los elementos serán &null; de PHP.
           </entry>
          </row>
          <row>
           <entry><constant>OCI_RETURN_LOBS</constant></entry>
           <entry>Devuelve el contenido de los LOB en lugar de los descriptores
            de los mismos.</entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <para>
       El valor predeterminado de <parameter>mode</parameter> es <constant>OCI_BOTH</constant>.
      </para>
      <para>
       Use el operador de adición &quot;+&quot; para especificar más de
       un modo a la vez.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve un array con los índices asociativos y/o numéricos. Si no existen
   más filas en <parameter>statement</parameter>, devolverá
   &false;.
  </para>
  <para>
   Por omisión, las columnas <literal>LOB</literal> son devueltas como descriptores LOB.
  </para>
  <para>
   Las columnas <literal>DATE</literal> son devueltas como string con
   el formato de fecha actual. El formato predeterminado se puede cambiar con
   las variables de entorno de Oracle, como <literal>NLS_LANG</literal>, o
   ejecutando previamente un comando <literal>ALTER SESSION SET
   NLS_DATE_FORMAT</literal>.
  </para>
  <para>
   Los nombres de columna predeterminados de Oracle que no consideran mayúsculas/minúsculas 
   tendrán claves de array en mayúsculas. Los nombres de columnas sensibles al uso de
   mayúsculas/minúsculas tendrán claves de array que usan el nombre exacto de la columna.
   Use <function>var_dump</function> en el array resultante para verificar el uso apropiado
   de mayúsculas/minúsculas en cada consulta.
  </para>
  <para>
   El nombre de la tabla no está incluído en el índice del array. Si la consulta
   contiene dos columnas diferentes con el mismo nombre,
   use <constant>OCI_NUM</constant> o añada un alias de columna a la consulta
   para asegurarse de la unicidad de los nombres (véase el ejemplo #7). De lo contrario,
   solamente será devuelta una columna mediante PHP.
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>oci_fetch_array</function> con <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)) != false) {
    // Usar nombres de columna en mayúsculas para los índices del array asociativo
    echo $row[0] . " y " . $row['DEPARTMENT_ID']   . " son lo mismo<br>\n";
    echo $row[1] . " y " . $row['DEPARTMENT_NAME'] . " son lo mismo<br>\n";
}

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_array</function> con <constant>OCI_NUM</constant></title>
    <programlisting role="php">
<![CDATA[
<?php

/*
  Antes de ejecutarlo, cree la tabla:
      CREATE TABLE mytab (id NUMBER, description CLOB);
      INSERT INTO mytab (id, description) values (1, 'Un string muy largo');
      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)) != false) {
    echo $row[0] . "<br>\n";
    echo $row[1]->read(11) . "<br>\n"; // esto imprimirá los primeros 11 bytes de DESCRIPTION
}

// La salida es:
//    1
//    Un string m

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_array</function> con <constant>OCI_ASSOC</constant></title>
    <programlisting role="php">
<![CDATA[
<?php

/*
  Antes de ejecutarlo, cree la tabla:
      CREATE TABLE mytab (id NUMBER, description CLOB);
      INSERT INTO mytab (id, description) values (1, 'Un string muy largo');
      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)) != false) {
    echo $row['ID'] . "<br>\n";
    echo $row['DESCRIPTION']->read(11) . "<br>\n"; // esto imprimirá los primeros 11 bytes de DESCRIPTION
}

// La salida es:
//    1
//    Un string m

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_array</function> con <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)) != false) { // Ignorar los NULL
    var_dump($row);
}

/*
El código de arriba imprime:
  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)) != false) { // Obtener los NULL
    var_dump($row);
}

/*
El código de arriba imprime:
  array(2) {
    [1]=>
    string(1) "1"
    ["NULL"]=>
    NULL
  }
*/

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_array</function> con <constant>OCI_RETURN_LOBS</constant></title>
    <programlisting role="php">
<![CDATA[
<?php

/*
  Antes de ejecutarlo, cree la tabla:
      CREATE TABLE mytab (id NUMBER, description CLOB);
      INSERT INTO mytab (id, description) values (1, 'Un string muy largo');
      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)) != false) {
    echo $row['ID'] . "<br>\n";
    echo $row['DESCRIPTION'] . "<br>\n"; // contiene todo lo de DESCRIPTION
    // En un bucle, liberar la variable grande de la 2ª obtención reduce en uso de memoria de picos de PHP
    unset($row); 
}

// La salida es:
//    1
//    Un string muy largo

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_array</function> con nombres de columna sensibles al uso de mayúsculas/minúsculas</title>
    <programlisting role="php">
<![CDATA[
<?php

/*
  Antes de ejecutarlo, cree la tabla:
      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);

// Ya que 'Name' fue creado como columna sensible al uso de mayúsculas/minúsculas,
// se usa lo mismo para el índice del array. Sin embargo, debe usarse 'CITY' en
// mayúsculas para los índices de columna insensibles al uso de mayúsculas/minúsculas
print $row['Name'] . "<br>\n";   //  imprime Chris
print $row['CITY'] . "<br>\n";   //  imprime Melbourne

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_array</function> con columnas que tienen nombres duplicados</title>
    <programlisting role="php">
<![CDATA[
<?php

/*
  Antes de ejecutarlo, cree la tabla:
      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);

// La salida únicamente contiene la entrada "NAME":
//    array(1) {
//      ["NAME"]=>
//      string(9) "Australia"
//    }

// En consultas con nombres de columnas repetidos use un alias de columna de SQL, como "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);

// La salida ahora contiene ambas columnas seleccionadas:
//    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> con columnas <literal>DATE</literal></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);
}

// Establecer el formato de fecha para esta conexión.
// Por razones de rendimiento, considere cambiar el formato
// en un disparador o con variables de entorno en su lugar
$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";  // imprime 1997-06-14

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_array</function> con <literal>REF CURSOR</literal></title>
    <programlisting role="php">
<![CDATA[
<?php
/*
  Cree el procedimiento almacenado PL/SQL:

  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);

// Ejecutar el REF CURSOR devuelto y obtenerlo como un identificador de sentencia
oci_execute($refcur);  
echo "<table border='1'>\n";
while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
    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>Paginación con <function>oci_fetch_array</function> usando una consulta como <literal>LIMIT</literal></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);
}

// Buscar la versión de la base de datos
preg_match('/Release ([0-9]+)\./', oci_server_version($conn), $matches);
$oracleversion = $matches[1];

// Esta es la consulta que se quiere "paginar"
$sql = 'SELECT city, postal_code FROM locations ORDER BY city';

if ($oracleversion >= 12) {
    // Usar la sintaxis de Oracle 12c de OFFSET / FETCH NEXT
    $sql = $sql . ' OFFSET :offset ROWS FETCH NEXT :numrows ROWS ONLY';
} else {
    // Versiones antiguas de Oracle necesitaban una consulta anidada para
    // seleccionar un subconjunto de $sql. O, si la sentencia SQL es conocida
    // durante el desarrollo, considere usar una función row_number() en lugar
    // de esta solución anidada. En entornos de producción, tenga cuidado para
    // evitar problemas con inyecciones SQL con concatenaciones.
    $sql = "SELECT * FROM (SELECT a.*, ROWNUM AS my_rnum
                           FROM ($sql) a
                           WHERE ROWNUM <= :offset + :numrows)
            WHERE my_rnum > :offset";
}

$offset  = 0;  // saltar estas filas
$numrows = 5;  // devolver 5 filas
$stid = oci_parse($conn, $sql);
oci_bind_by_name($stid, ':numrows', $numrows);
oci_bind_by_name($stid, ':offset', $offset);
oci_execute($stid);

while (($row = oci_fetch_array($stid, OCI_ASSOC + OCI_RETURN_NULLS)) != false) {
    echo $row['CITY'] . " " . $row['POSTAL_CODE'] . "<br>\n";
}

// La salida es:
//    Beijing 190518
//    Bern 3095
//    Bombay 490231
//    Geneva 1730
//    Hiroshima 6823

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_array</function> con Conjuntos de Resultados Implícitos de Oracle Database 12<emphasis>c</emphasis></title>
    <programlisting role="php">
<![CDATA[
<?php

$conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

// Requiere OCI8 2.0 y Oracle Database 12c
// Véase también oci_get_implicit_resultset()
$sql = 'DECLARE
           c1 SYS_REFCURSOR;
        BEGIN
           OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
           DBMS_SQL.RETURN_RESULT(c1);
           OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
           DBMS_SQL.RETURN_RESULT(c1);
        END;';

$stid = oci_parse($conn, $sql);
oci_execute($stid);

// Nota: oci_fetch_all y oci_fetch() no se pueden usar de esta manera
echo "<table>\n";
while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
    echo "<tr>\n";
    foreach ($row as $item) {
        echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"")."</td>\n";
    }
    echo "</tr>\n";
}
echo "</table>\n";

// La salida es:
//    Beijing 190518
//    Bern    3095
//    Bombay  490231
//    CN
//    CH
//    IN

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Los índices de arrays asociativos tienen que estar en mayúsculas para las columnas estándar
    de Oracle que fueron creadas con nombres insensibles al uso de mayúsculas/minúsculas.
   </para>
  </note>
  <note>
   &oci.use.setprefetch;
  </note>
  <note>
   <para>
    La función <function>oci_fetch_array</function>
    es <emphasis>insignificativamente</emphasis> más lenta que
    <function>oci_fetch_assoc</function>
    o <function>oci_fetch_row</function>, pero es más 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
-->