cvs: phpdoc /en/reference/ibm_db2/functions db2-connect.xml db2-exec.xml

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>