dbs Tue Apr 12 20:37:16 2005 EDT
Modified files:
/phpdoc/en/reference/ibm_db2/functions db2-connect.xml db2-exec.xml
Log:
Add details for db2_exec(). Correct typo in db2_connect().
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-connect.xml?r1=1.2&r2=1.3&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-connect.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-connect.xml:1.2
phpdoc/en/reference/ibm_db2/functions/db2-connect.xml:1.3
--- phpdoc/en/reference/ibm_db2/functions/db2-connect.xml:1.2 Tue Apr 12
19:45:14 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-connect.xml Tue Apr 12
20:37:15 2005
@@ -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>
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-exec.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-exec.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.1
phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.2
--- phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.1 Tue Apr 12
17:12:48 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-exec.xml Tue Apr 12 20:37:15 2005
@@ -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,117 +43,162 @@
<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
- </para>
- </refsect1>
-
- <!-- Use when EXCEPTIONS exist
- <refsect1 role="exceptions">
- &reftitle.exceptions;
- <para>
- When does this function throw exceptions?
+ 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 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... ";
+ }
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+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[
-Use the PEAR Coding Standards
+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>
