dbs Wed Apr 13 14:49:30 2005 EDT
Modified files:
/phpdoc/en/reference/ibm_db2 configure.xml
/phpdoc/en/reference/ibm_db2/functions db2-conn-error.xml
db2-conn-errormsg.xml
db2-exec.xml db2-execute.xml
db2-prepare.xml
Log:
More ibm_db2 function documentation goodness.
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/configure.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ibm_db2/configure.xml
diff -u phpdoc/en/reference/ibm_db2/configure.xml:1.1
phpdoc/en/reference/ibm_db2/configure.xml:1.2
--- phpdoc/en/reference/ibm_db2/configure.xml:1.1 Tue Apr 12 19:45:14 2005
+++ phpdoc/en/reference/ibm_db2/configure.xml Wed Apr 13 14:49:24 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<section id="ibm_db2.installation">
&reftitle.install;
<para>
@@ -17,11 +17,11 @@
<para>
ibm_db2 is a <ulink url="&url.pecl;">PECL</ulink> extension, so follow the
instructions in <xref linkend='install.pecl' /> to install the ibm_db2
- extension for PHP. Issue the <command>configure</command> to point
+ extension for PHP. Issue the <command>configure</command> command to point
to the location of your DB2 header files and libraries as follows:
<screen>
<![CDATA[
-bash$ ./configure --with-IBM_DB2
+bash$ ./configure --with-IBM_DB2=/path/to/DB2
]]>
</screen>
The <command>configure</command> command defaults to
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml:1.1
phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml:1.2
--- phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml:1.1 Tue Apr
12 17:12:48 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml Wed Apr 13
14:49:29 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-conn-error">
<refnamediv>
@@ -15,8 +15,27 @@
<methodparam
choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
</methodsynopsis>
- &warn.undocumented.func;
+ &warn.experimental.func;
+ <para>
+ <function>db2_conn_error</function> returns an SQLSTATE value representing
+ the reason the last attempt to connect to a database failed. As
+ <function>db2_connect</function> returns &false; in the event of a failed
+ connection attempt, you do not pass any parameters to
+ <function>db2_conn_error</function> to retrieve the SQLSTATE value.
+ </para>
+ <para>
+ If, however, the connection was successful but becomes invalid over time,
+ you can pass the <parameter>connection</parameter> parameter to retrieve
+ the SQLSTATE value for a specific connection.
+ </para>
+ <para>
+ To learn what the SQLSTATE value means, you can issue the following command
+ at a DB2 Command Line Processor prompt:
+ <userinput>db2 '? <parameter>sqlstate-value</parameter>'</userinput>. You
+ can also call <function>db2_conn_errormsg</function> to retrieve an
+ explicit error message and the associated SQLCODE value.
+ </para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -24,74 +43,41 @@
<variablelist>
<varlistentry>
<term><parameter>connection</parameter></term>
- <listitem>
- <para>
- Its description
- </para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>
+ A connection resource associated with a connection that initially
+ succeeded, but which over time became invalid.
+ </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?
- </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>
+ Returns the SQLSTATE value resulting from a failed connection attempt.
+ Returns an empty string if there is no error associated with the last
+ connection attempt.
</para>
</refsect1>
- -->
-
- <!-- Use when examples exist
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
- <title>A <function>db2_conn_error</function> example</title>
+ <title>Retrieving an SQLSTATE value for a failed connection attempt</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 demonstrates how to return an SQLSTATE value
+ after deliberately passing invalid parameters to
+ <function>db2_connect</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
-if ($anexample === true) {
- echo 'Use the PEAR Coding Standards';
+$conn = db2_connect('badname', 'baduser', 'badpassword');
+if (!$conn) {
+ print "SQLSTATE value: " . db2_conn_error();
}
?>
]]>
@@ -99,26 +85,24 @@
&example.outputs;
<screen>
<![CDATA[
-Use the PEAR Coding Standards
+SQLSTATE value: 08001
]]>
</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_conn_errormsg</function></member>
+ <member><function>db2_connect</function></member>
+ <member><function>db2_stmt_error</function></member>
+ <member><function>db2_stmt_errormsg</function></member>
</simplelist>
</para>
</refsect1>
- -->
</refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml:1.1
phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml:1.2
--- phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml:1.1 Tue Apr
12 17:12:48 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml Wed Apr 13
14:49:30 2005
@@ -1,11 +1,11 @@
<?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-conn-errormsg">
<refnamediv>
<refname>db2_conn_errormsg</refname>
<refpurpose>
- Returns a string containing the last connection error message
+ Returns the last connection error message and SQLCODE value
</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -15,8 +15,20 @@
<methodparam
choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
</methodsynopsis>
- &warn.undocumented.func;
-
+ &warn.experimental.func;
+ <para>
+ <function>db2_conn_errormsg</function> returns an error message and SQLCODE
+ value representing the reason the last database connection attempt failed.
+ As <function>db2_connect</function> returns &false; in the event of a failed
+ connection attempt, do not pass any parameters to
+ <function>db2_conn_errormsg</function> to retrieve the associated error
+ message and SQLCODE value.
+ </para>
+ <para>
+ If, however, the connection was successful but becomes invalid over time,
+ you can pass the <parameter>connection</parameter> parameter to retrieve
+ the associated error message and SQLCODE value for a specific connection.
+ </para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -26,7 +38,8 @@
<term><parameter>connection</parameter></term>
<listitem>
<para>
- Its description
+ A connection resource associated with a connection that initially
+ succeeded, but which over time became invalid.
</para>
</listitem>
</varlistentry>
@@ -36,62 +49,29 @@
<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?
- </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>
+ Returns a string containing the error message and SQLCODE value resulting
+ from a failed connection attempt. If there is no error associated with the
last
+ connection attempt, <function>db2_conn_errormsg</function> returns an empty
+ string.
</para>
</refsect1>
- -->
-
- <!-- Use when examples exist
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
- <title>A <function>db2_conn_errormsg</function> example</title>
+ <title>Retrieving the error message returned by a failed connection
attempt</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 demonstrates how to return an error message and
+ SQLCODE value after deliberately passing invalid parameters to
+ <function>db2_connect</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
-if ($anexample === true) {
- echo 'Use the PEAR Coding Standards';
+$conn = db2_connect('badname', 'baduser', 'badpassword');
+if (!$conn) {
+ print db2_conn_errormsg();
}
?>
]]>
@@ -99,27 +79,26 @@
&example.outputs;
<screen>
<![CDATA[
-Use the PEAR Coding Standards
+Msg:[IBM][CLI Driver] SQL1013N The database alias name
+or database name "BADNAME" could not be found. SQLSTATE=42705
+ Err Code: -1013
]]>
</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_conn_error</function></member>
+ <member><function>db2_connect</function></member>
+ <member><function>db2_stmt_error</function></member>
+ <member><function>db2_stmt_errormsg</function></member>
</simplelist>
</para>
</refsect1>
- -->
-
</refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-exec.xml?r1=1.2&r2=1.3&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-exec.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.2
phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.3
--- phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.2 Tue Apr 12
20:37:15 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-exec.xml Wed Apr 13 14:49:30 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-exec">
<refnamediv>
@@ -54,7 +54,7 @@
<term><parameter>statement</parameter></term>
<listitem>
<para>
- An SQL statement.
+ An SQL statement. The statement cannot contain any parameter markers.
</para>
</listitem>
</varlistentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-execute.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-execute.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-execute.xml:1.1
phpdoc/en/reference/ibm_db2/functions/db2-execute.xml:1.2
--- phpdoc/en/reference/ibm_db2/functions/db2-execute.xml:1.1 Tue Apr 12
17:12:48 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-execute.xml Wed Apr 13
14:49:30 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-execute">
<refnamediv>
@@ -13,10 +13,31 @@
<methodsynopsis>
<type>bool</type><methodname>db2_execute</methodname>
<methodparam><type>resource</type><parameter>stmt</parameter></methodparam>
- <methodparam
choice="opt"><type>array</type><parameter>parameters_array</parameter></methodparam>
+ <methodparam
choice="opt"><type>array</type><parameter>parameters</parameter></methodparam>
</methodsynopsis>
- &warn.undocumented.func;
+ &warn.experimental.func;
+
+ <para>
+ <function>db2_execute</function> executes an SQL statement that was
+ prepared by <function>db2_prepare</function>.
+ </para>
+ <para>
+ If the SQL statement returns a result set, for example, a SELECT statement
+ or a CALL to a stored procedure that returns one or more result sets, you
+ can retrieve a row as an array from the <literal>stmt</literal> resource
+ using <function>db2_fetch_assoc</function>,
+ <function>db2_fetch_both</function>, or
+ <function>db2_fetch_into</function>. Alternatively, you can use
+ <function>db2_fetch_row</function> to move the result set pointer to the
+ next row and fetch a column at a time from that row with
+ <function>db2_result</function>.
+ </para>
+ <para>
+ Refer to <function>db2_prepare</function> for a brief discussion of the
+ advantages of using <function>db2_prepare</function> and
+ <function>db2_execute</function> rather than <function>db2_exec</function>.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -27,15 +48,16 @@
<term><parameter>stmt</parameter></term>
<listitem>
<para>
- Its description
+ A prepared statement returned from <function>db2_prepare</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><parameter>parameters_array</parameter></term>
+ <term><parameter>parameters</parameter></term>
<listitem>
<para>
- Its description
+ An array of input parameters matching any parameter markers contained
+ in the prepared statement.
</para>
</listitem>
</varlistentry>
@@ -45,62 +67,34 @@
<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?
+ &return.success;
</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_execute</function> example</title>
+ <title>Preparing and executing an SQL statement with parameter
markers</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 prepares an INSERT statement that accepts four
+ parameter markers, then iterates over an array of arrays containg the
+ input values to be passed to <function>db2_execute</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
-if ($anexample === true) {
- echo 'Use the PEAR Coding Standards';
+$pet = array(0, 'cat', 'Pook', 3.2);
+
+$insert = 'INSERT INTO animals (id, breed, name, weight)
+ VALUES (?, ?, ?, ?)';
+
+$stmt = db2_prepare($conn, $insert);
+if ($stmt) {
+ $result = db2_execute($stmt, $pet);
+ if ($result) {
+ print "Successfully added new pet.";
+ }
}
?>
]]>
@@ -108,26 +102,59 @@
&example.outputs;
<screen>
<![CDATA[
-Use the PEAR Coding Standards
+Successfully added new pet.
]]>
</screen>
</example>
+ <example>
+ <title>Calling a stored procedure with an OUT parameter</title>
+ <para>
+ The following example prepares a CALL statement that accepts one
+ parameter marker representing an OUT parameter, binds the PHP variable
+ <literal>$my_pets</literal> to the parameter using
+ <function>db2_bind_param</function>, then issues
+ <function>db2_execute</function> to execute the CALL statement. After the
+ CALL to the stored procedure has been made, the value of
+ <literal>$num_pets</literal> changes to reflect the value returned by the
+ stored procedure for that OUT parameter.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$num_pets = 0;
+$res = db2_prepare($conn, "CALL count_my_pets(?)");
+$rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT);
+$rc = db2_execute($res);
+print "I have $num_pets pets!";
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+I have 7 pets!
+]]>
+ </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_exec</function></member>
+ <member><function>db2_fetch_assoc</function></member>
+ <member><function>db2_fetch_both</function></member>
+ <member><function>db2_fetch_into</function></member>
+ <member><function>db2_fetch_row</function></member>
+ <member><function>db2_prepare</function></member>
+ <member><function>db2_result</function></member>
</simplelist>
</para>
</refsect1>
- -->
</refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml:1.1
phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml:1.2
--- phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml:1.1 Tue Apr 12
17:12:48 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml Wed Apr 13
14:49:30 2005
@@ -1,11 +1,11 @@
<?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-prepare">
<refnamediv>
<refname>db2_prepare</refname>
<refpurpose>
- Prepares an SQL statement
+ Prepares an SQL statement to be executed
</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -13,11 +13,53 @@
<methodsynopsis>
<type>resource</type><methodname>db2_prepare</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>
+ <function>db2_prepare</function> creates a prepared SQL statement which can
+ include 0 or more parameter markers (<literal>?</literal> characters)
+ representing parameters for input, output, or input/output. You can pass
+ parameters to the prepared statement using
+ <function>db2_bind_param</function>, or for input values only, as an array
+ passed to <function>db2_execute</function>.
+ </para>
+ <para>
+ There are three main advantages to using prepared statements in your
+ application:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Performance</emphasis>: when you prepare a statement, the
+ database server creates an optimized access plan for retrieving data with
+ that statement. Subsequently issuing the prepared statement with
+ <function>db2_execute</function> enables the statements to reuse that
+ access plan and avoids the overhead of dynamically creating a new access
+ plan for every statement you issue.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Security</emphasis>: when you prepare a statement, you can
+ include parameter markers for input values. When you execute a prepared
+ statement with input values for placeholders, the database server checks
+ each input value to ensure that the type matches the column definition or
+ parameter definition.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Advanced functionality</emphasis>: Parameter markers not only
+ enable you to pass input values to prepared SQL statements, they also
+ enable you to retrieve OUT and INOUT parameters from stored procedures
+ using <function>db2_bind_param</function>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -26,118 +68,148 @@
<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, optionally containing one or more parameter markers..
+ </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?
- </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>
+ Returns a statement resource if the SQL statement was successfully parsed
and
+ prepared by the database server. Returns &false; if the database server
+ returned an error. You can determine which error was returned by calling
+ <function>db2_stmt_error</function> or
<function>db2_stmt_errormsg</function>.
</para>
</refsect1>
- -->
-
- <!-- Use when examples exist
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
- <title>A <function>db2_prepare</function> example</title>
+ <title>Preparing and executing an SQL statement with parameter
markers</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 prepares an INSERT statement that accepts four
+ parameter markers, then iterates over an array of arrays containg the
+ input values to be passed to <function>db2_execute</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
-if ($anexample === true) {
- echo 'Use the PEAR Coding Standards';
+$animals = array(
+ array(0, 'cat', 'Pook', 3.2),
+ array(1, 'dog', 'Peaches', 12.3),
+ array(2, 'horse', 'Smarty', 350.0),
+);
+
+$insert = 'INSERT INTO animals (id, breed, name, weight)
+ VALUES (?, ?, ?, ?)';
+$stmt = db2_prepare($conn, $insert);
+if ($stmt) {
+ foreach ($animals as $animal) {
+ $result = db2_execute($stmt, $animal);
+ }
}
?>
]]>
</programlisting>
+ </example>
+ <!--
+ <example>
+ <title>Preventing SQL injection attacks using parameter markers</title>
+ <para>
+ Parameter markers make it impossible for a malicious user of your
+ application to pass input values that map to more than one database
+ field or stored procedure parameter. The following example demonstrates
+ a common tactic for attacking database-driven Web applications, SQL
+ injection, which takes advantage of applications that often simply
+ interpolate the input values from a user directly into an SQL statement
+ rather than defining parameter markers and binding the input values to
+ those parameter markers.
+ </para>
+ <para>
+ In the following example, assume that the PHP script has been placed on
+ a publically accessible Web server and the application provides
+ different levels of access for different users. We shall also assume
+ that the application issues an SQL statement that updates the privilege
+ level of a newly registered user to the lowest level, taking the user ID
+ from a GET input variable. In the following example, a malicious user
+ can pass <userinput>userid=0+OR+1=1</userinput> (instead of the expected
+ <userinput>userid=0</userinput>) to trick your application into
+ setting the privilege level of every user in the database to the lowest
+ level.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+?>
+]]>
+ </programlisting>
&example.outputs;
<screen>
<![CDATA[
-Use the PEAR Coding Standards
]]>
</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_bind_param</function></member>
+ <member><function>db2_execute</function></member>
+ <member><function>db2_stmt_error</function></member>
+ <member><function>db2_stmt_errormsg</function></member>
</simplelist>
</para>
</refsect1>
- -->
-
</refentry>
