From a598115f4068afb83e86514d86ff75b121034906 Mon Sep 17 00:00:00 2001
From: Dan Scott <dbs@php.net>
Date: Wed, 13 Apr 2005 00:37:15 +0000
Subject: [PATCH] Add details for db2_exec(). Correct typo in db2_connect().

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@184243 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/ibm_db2/functions/db2-connect.xml |   4 +-
 reference/ibm_db2/functions/db2-exec.xml    | 206 +++++++++++++-------
 2 files changed, 136 insertions(+), 74 deletions(-)

diff --git a/reference/ibm_db2/functions/db2-connect.xml b/reference/ibm_db2/functions/db2-connect.xml
index c3c493a267..d48f1a1659 100644
--- a/reference/ibm_db2/functions/db2-connect.xml
+++ b/reference/ibm_db2/functions/db2-connect.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
 <refentry id="function.db2-connect">
  <refnamediv>
@@ -117,7 +117,7 @@
      <term><parameter>options</parameter></term>
      <listitem>
       <para>
-       An associative array connection options that affect the behavior
+       An associative array of connection options that affect the behavior
        of the connection, where valid array keys include:
        <variablelist>
         <varlistentry>
diff --git a/reference/ibm_db2/functions/db2-exec.xml b/reference/ibm_db2/functions/db2-exec.xml
index 1beeb7435a..7d40be154c 100644
--- a/reference/ibm_db2/functions/db2-exec.xml
+++ b/reference/ibm_db2/functions/db2-exec.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
 <refentry id="function.db2-exec">
  <refnamediv>
@@ -13,11 +13,28 @@
   <methodsynopsis>
    <type>resource</type><methodname>db2_exec</methodname>
    <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
-   <methodparam><type>string</type><parameter>stmt_string</parameter></methodparam>
+   <methodparam><type>string</type><parameter>statement</parameter></methodparam>
    <methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
   </methodsynopsis>
 
-  &warn.undocumented.func;
+  &warn.experimental.func;
+
+  <para>
+   Prepares and executes an SQL statement.
+  </para>
+  <para>
+   If you plan to interpolate PHP variables into the SQL statement, understand
+   that this is one of the more common security exposures. Consider calling
+   <function>db2_prepare</function> to prepare an SQL statement with parameter
+   markers for input values. Then you can call <function>db2_execute</function>
+   to pass in the input values and avoid SQL injection attacks.
+  </para>
+  <para>
+   If you plan to repeatedly issue the same SQL statement with different
+   parameters, consider calling <function>db2_prepare</function> and
+   <function>db2_execute</function> to enable the database server to reuse its
+   access plan and increase the efficiency of your database access.
+  </para>
 
  </refsect1>
  <refsect1 role="parameters">
@@ -26,90 +43,102 @@
    <variablelist>
     <varlistentry>
      <term><parameter>connection</parameter></term>
-      <listitem>
-       <para>
-        Its description
-       </para>
-      </listitem>
-     </varlistentry>
+     <listitem>
+      <para>
+       A valid database connection resource variable as returned from
+       <function>db2_connect</function> or <function>db2_pconnect</function>.
+      </para>
+     </listitem>
+    </varlistentry>
     <varlistentry>
-     <term><parameter>stmt_string</parameter></term>
-      <listitem>
-       <para>
-        Its description
-       </para>
-      </listitem>
-     </varlistentry>
+     <term><parameter>statement</parameter></term>
+     <listitem>
+      <para>
+       An SQL statement.
+      </para>
+     </listitem>
+    </varlistentry>
     <varlistentry>
      <term><parameter>options</parameter></term>
-      <listitem>
-       <para>
-        Its description
-       </para>
-      </listitem>
-     </varlistentry>
+     <listitem>
+      <para>
+       An associative array containing statement options. You can use this
+       parameter to request a scrollable cursor on database servers that
+       support this functionality.
+       <variablelist>
+        <varlistentry>
+         <term><parameter>cursor</parameter></term>
+         <listitem>
+          <para>
+           Passing the <literal>DB2_FORWARD_ONLY</literal> value requests a
+           forward-only cursor for this SQL statement. This is the default
+           type of cursor, and it is supported by all database servers. It is
+           also much faster than a scrollable cursor.
+          </para>
+          <para>
+           Passing the <literal>DB2_SCROLLABLE</literal> value requests a
+           scrollable cursor for this SQL statement. This type of cursor
+           enables you to fetch rows non-sequentially from the database
+           server. However, it is only supported by DB2 servers, and is much
+           slower than forward-only cursors.
+          </para>
+         </listitem>
+        </varlistentry>
+       </variablelist>
+
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   What the function returns, first on success, then on failure. See
-   also the &return.success; entity
+   Returns a statement resource if the SQL statement was issued successfully,
+   or &false; if the database failed to execute the SQL statement.
   </para>
  </refsect1>
 
- <!-- Use when EXCEPTIONS exist
- <refsect1 role="exceptions">
-  &reftitle.exceptions;
-  <para>
-   When does this function throw exceptions?
-  </para>
- </refsect1>
- -->
-
-
- <!-- Use when a CHANGELOG exists
- <refsect1 role="changelog">
-  &reftitle.changelog;
-  <para>
-   <informaltable>
-    <tgroup cols="2">
-     <thead>
-      <row>
-       <entry>&Version;</entry>
-       <entry>&Description</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Enter the PHP version of change here
-       <entry>Description of change
-      </row>
-     </tbody>
-    </tgroup>
-   </informaltable>
-  </para>
- </refsect1>
- -->
-
-
- <!-- Use when examples exist
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
    <example>
-    <title>A <function>db2_exec</function> example</title>
+    <title>Creating a table with <function>db2_exec</function></title>
     <para>
-     Any text that describes the purpose of the example, or
-     what goes on in the example should go here (inside the
-     <example> tag, not out
+     The following example uses <function>db2_exec</function> to issue a set
+     of DDL statements in the process of creating a table.
     </para>
     <programlisting role="php">
 <![CDATA[
 <?php
-if ($anexample === true) {
-    echo 'Use the PEAR Coding Standards';
+$conn = db2_connect($database, $user, $password);
+
+// Create the test table
+$create = 'CREATE TABLE animals (id INTEGER, breed VARCHAR(32),
+    name CHAR(16), weight DECIMAL(7,2))';
+$result = db2_exec($conn, $create);
+if ($result) {
+    print "Successfully created the table.\n";
+}
+
+// Populate the test table
+$animals = array(
+    array(0, 'cat', 'Pook', 3.2),
+    array(1, 'dog', 'Peaches', 12.3),
+    array(2, 'horse', 'Smarty', 350.0),
+    array(3, 'gold fish', 'Bubbles', 0.1),
+    array(4, 'budgerigar', 'Gizmo', 0.2),
+    array(5, 'goat', 'Rickety Ride', 9.7),
+    array(6, 'llama', 'Sweater', 150)
+);
+
+foreach ($animals as $animal) {
+    $rc = db2_exec($conn, "INSERT INTO animals (id, breed, name, weight)
+      VALUES ('{$animal[0]}', '{$animal[1]}', '{$animal[2]}', {$animal[3]})");
+    if ($rc) {
+        print "Insert... ";
+    }
 }
 ?>
 ]]>
@@ -117,26 +146,59 @@ if ($anexample === true) {
     &example.outputs;
     <screen>
 <![CDATA[
-Use the PEAR Coding Standards
+Successfully created the table.
+Insert... Insert... Insert... Insert... Insert... Insert... Insert... 
+]]>
+    </screen>
+   </example>
+
+   <example>
+    <title>Executing a SELECT statement with a scrollable cursor</title>
+    <para>
+     The following example demonstrates how to request a scrollable cursor for
+     an SQL statement issued by <function>db2_exec</function>.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$conn = db2_connect($database, $user, $password);
+$sql = "SELECT name FROM animals
+    WHERE weight < 10.0
+    ORDER BY name";
+if ($conn) {
+    require_once('prepare.inc');
+    $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
+    while ($row = db2_fetch_into($stmt)) {
+        print "$row[0]\n";
+    }
+} 
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+Bubbles
+Gizmo
+Pook
+Rickety Ride
 ]]>
     </screen>
    </example>
   </para>
  </refsect1>
- -->
 
 
- <!-- Use when adding See Also links
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function></function></member>
-    <member>Or <link linkend="somethingelse">something else</link></member>
+    <member><function>db2_execute</function></member>
+    <member><function>db2_prepare</function></member>
+    <member><function>db2_setoption</function></member>
    </simplelist>
   </para>
  </refsect1>
- -->
 
 
 </refentry>