From b6093f02caf17a35b75c19715f6d448747cf8234 Mon Sep 17 00:00:00 2001
From: Christopher Jones <sixd@php.net>
Date: Wed, 11 Nov 2009 01:01:39 +0000
Subject: [PATCH] Add example and correct grammar

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@290495 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/oci8/functions/oci-parse.xml | 57 +++++++++++++++++++-------
 1 file changed, 43 insertions(+), 14 deletions(-)

diff --git a/reference/oci8/functions/oci-parse.xml b/reference/oci8/functions/oci-parse.xml
index 5c9c7bfafe..8e6d542836 100644
--- a/reference/oci8/functions/oci-parse.xml
+++ b/reference/oci8/functions/oci-parse.xml
@@ -3,7 +3,7 @@
 <refentry xml:id="function.oci-parse" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>oci_parse</refname>
-  <refpurpose>Prepares Oracle statement for execution</refpurpose>
+  <refpurpose>Prepares an Oracle statement for execution</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
@@ -11,10 +11,10 @@
   <methodsynopsis>
    <type>resource</type><methodname>oci_parse</methodname>
    <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
-   <methodparam><type>string</type><parameter>query</parameter></methodparam>
+   <methodparam><type>string</type><parameter>sql_text</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Prepares the <parameter>query</parameter>using
+   Prepares the <parameter>sql_text</parameter>using
    <parameter>connection</parameter> and returns the statement identifier,
    which can be used with <function>oci_bind_by_name</function>, 
    <function>oci_execute</function> and other functions.
@@ -30,15 +30,15 @@
      <listitem>
       <para>
        An Oracle connection identifier, returned by 
-       <function>oci_connect</function> or <function>oci_pconnect</function>.
+       <function>oci_connect</function>, <function>oci_pconnect</function>, or <function>oci_new_connect</function>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>query</parameter></term>
+     <term><parameter>sql_text</parameter></term>
      <listitem>
       <para>
-       The SQL query.
+       The SQL or PL/SQL statement.
       </para>
      </listitem>
     </varlistentry>
@@ -49,7 +49,38 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns a statement handler on success, or &false; on error.
+   Returns a statement handle on success, or &false; on error.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>oci_parse</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$connection = oci_connect("hr", "welcome", "localhost/XE");
+
+$statement = oci_parse($connection, "SELECT * FROM employees");
+oci_execute($statement);
+
+echo "<table border='1'>\n";
+while ($row = oci_fetch_array($statement, OCI_ASSOC+OCI_RETURN_NULLS)) {
+    echo "<tr>\n";
+    foreach ($row as $item) {
+        echo "    <td>".($item!==null?htmlentities($item, ENT_QUOTES):"&nbsp;")."</td>\n";
+    }
+    echo "</tr>\n";
+}
+echo "</table>\n";
+
+?>
+]]>
+    </programlisting>
+   </example>
   </para>
  </refsect1>
 
@@ -58,17 +89,15 @@
   <note>
    <para>
     This function <emphasis>does not</emphasis> validate 
-    <parameter>query</parameter>. The only way to find out if
-    <parameter>query</parameter> is valid SQL or PL/SQL statement - is to
-    execute it.
+    <parameter>sql_text</parameter>. The only way to find out if
+    <parameter>sql_text</parameter> is a valid SQL or PL/SQL statement
+    is to execute it.
    </para>
   </note>
   <note>
    <para>
-    In PHP versions before 5.0.0 you must use <function>ociparse</function> instead.
-    This name still can be used, it was left as alias of
-    <function>oci_parse</function> for downwards compatability.
-    This, however, is deprecated and not recommended.
+    In PHP versions before 5.0.0 you must
+    use <function>ociparse</function> instead.  &oci.name.compat.note;
    </para>
   </note>
  </refsect1>