svn: /phpdoc/en/trunk/reference/oci8/functions/ oci-fetch-object.xml

sixd Thu, 19 Nov 2009 18:21:48 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=291021 Log: Update and add examples Changed paths: U phpdoc/en/trunk/reference/oci8/functions/oci-fetch-object.xml Modified: phpdoc/en/trunk/reference/oci8/functions/oci-fetch-object.xml =================================================================== --- phpdoc/en/trunk/reference/oci8/functions/oci-fetch-object.xml 2009-11-19 18:06:01 UTC (rev 291020) +++ phpdoc/en/trunk/reference/oci8/functions/oci-fetch-object.xml 2009-11-19 18:21:48 UTC (rev 291021) @@ -3,7 +3,7 @@ <refentry xml:id="function.oci-fetch-object" xmlns="http://docbook.org/ns/docbook"> <refnamediv> <refname>oci_fetch_object</refname> - <refpurpose>Returns the next row from the result data as an object</refpurpose> + <refpurpose>Returns the next row from a query as an object</refpurpose> </refnamediv> <refsect1 role="description"> @@ -13,12 +13,11 @@ <methodparam><type>resource</type><parameter>statement</parameter></methodparam> </methodsynopsis> <para> - Returns the next row from the result data as an object. + Returns an object containing the next result-set row of a query. + Each attribute of the object 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> - <para> - Subsequent calls to <function>oci_fetch_object</function> will return the - next row from the result or &false; if there are no more rows. - </para> &oci.datatypes; </refsect1> @@ -29,9 +28,7 @@ <varlistentry> <term><parameter>statement</parameter></term> <listitem> - <para> - A valid OCI statement identifier. - </para> + &oci.arg.statement.id; </listitem> </varlistentry> </variablelist> @@ -41,26 +38,170 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - Returns an object, which attributes correspond to fields in statement, or - &false; if there are no more rows in the <parameter>statement</parameter>. + Returns an object. Each attribute of the object corresponds to a + column of the row. If there are no more rows in + the <parameter>statement</parameter> then &false; is returned. </para> - &database.fetch-null; - <note> - <simpara> - Oracle returns all field names in uppercase and associative indices in - the result object will be uppercased too. - </simpara> - </note> + <para> + Any <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 attribute names. Case-sensitive column names will have + attribute names using the exact column case. + Use <function>var_dump</function> on the result object to verify + the appropriate case to use for each query. + </para> + <para> + Attribute values will be &null; for any <literal>NULL</literal> + data fields. + </para> </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>oci_fetch_object</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +/* + Before running, create the table: + CREATE TABLE mytab (id NUMBER, description VARCHAR2(30)); + INSERT INTO mytab (id, description) values (1, 'Fish and Chips'); + 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_object($stid))) { + // Use upper case attribute names for each standard Oracle column + echo $row->ID . "<br>\n"; + echo $row->DESCRIPTION . "<br>\n"; +} + +// Output is: +// 1 +// Fish and Chips + +oci_free_statement($stid); +oci_close($conn); + +?> +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title><function>oci_fetch_object</function> with case sensitive column names</title> + <programlisting role="php"> +<![CDATA[ +<?php + +/* + Before running, create the table with a case sensitive column name: + CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30)); + INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee'); + 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, "MyDescription" FROM mytab'); +oci_execute($stid); + +while (($row = oci_fetch_object($stid))) { + // Use upper case attribute names for each standard Oracle column + echo $row->ID . "<br>\n"; + // Use the exact case for the case sensitive column name + echo $row->MyDescription . "<br>\n"; +} + +// Output is: +// 1 +// Iced Coffee + +oci_free_statement($stid); +oci_close($conn); + +?> +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title><function>oci_fetch_object</function> with LOBs</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_object($stid))) { + echo $row->ID . "<br>\n"; + // The following will output the first 11 bytes from DESCRIPTION + echo $row->DESCRIPTION->read(11) . "<br>\n"; +} + +// Output is: +// 1 +// A very long + +oci_free_statement($stid); +oci_close($conn); + +?> +]]> + </programlisting> + </example> + </para> + </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_array</function></member> - <member><function>oci_fetch_assoc</function></member> <member><function>oci_fetch_row</function></member> - <member><function>oci_fetch_all</function></member> </simplelist> </para> </refsect1>