db2-prepare.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry xml:id="function.db2-prepare" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>db2_prepare</refname>
  <refpurpose>
   Prepares an SQL statement to be executed
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>db2_prepare</methodname>
   <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
   <methodparam><type>string</type><parameter>statement</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
  </methodsynopsis>


  <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">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>connection</parameter></term>
     <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>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>
       An associative array containing statement options. You can use this
       parameter to request a scrollable cursor on database servers that
       support this functionality.
      </para>
      <para>
       For a description of valid statement options, see 
       <function>db2_set_option</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   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>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Preparing and executing an SQL statement with parameter markers</title>
    <para>
     The following example prepares an INSERT statement that accepts four
     parameter markers, then iterates over an array of arrays containing the
     input values to be passed to <function>db2_execute</function>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$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[
]]>
    </screen>
   </example>
   -->
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <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>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->