db2-prepare.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e41806c30bf6975e452c0d4ce35ab0984c2fa68c Maintainer: yago Status: ready -->
<!-- Reviewed: no -->

<!-- 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>
   Prepara un comando SQL para su ejecución
  </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> Crea un comando SQL preparado que puede incluir
   0 o más marcadores de parámetro (con el carácter <literal>?</literal>)
   los cuales representan parámetros de entrada, salida o entrada/salida.
   Se pueden pasar parámetros al comando SQL preparado usando <function>db2_bind_param</function>,
   o sólo para valores de entrada, como un arreglo enviado a <function>db2_execute</function>.
  </para>
  <para>
   Hay tres ventajas principales al usar comandos SQL preparados en una aplicación:
   <itemizedlist>
    <listitem>
     <para>
      <emphasis>Rendimiento</emphasis>: Cuando se prepara un comando SQL, el servidor 
      de base de datos crea un plan de acceso optimizado para devolver datos con
      ese comando SQL.   Posteriormente al enviar el comando SQL preparado a través de
      <function>db2_execute</function> se podrá reutilizar el plan de acceso y así se evitará 
      la sobrecarga que se produce cuando éste debe crearse nuevamente.
     </para>
    </listitem>
    <listitem>
     <para>
      <emphasis>Seguridad</emphasis>: Cuando se prepara un comando SQL, se pueden incluir
      marcadores de parámetros para valores de entrada.   Cuando se ejecuta ese comando
      usando los marcadores con valores de entrada, la base de datos puede chequear cada 
      valor de entrada para asegurar que el tipo de dato enviado coincide con la definición
      del campo o del parámetro.
     </para>
    </listitem>
    <listitem>
     <para>
      <emphasis>Funcionalidad avanzada</emphasis>: Los marcadores de parámetros
      no solo permiten pasar valores de entrada, además permiten obtener datos
      OUT e INOUT desde procedimientos almacenados usando <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>
       Una variable de conexión obtenida con <function>db2_connect</function>
       o con <function>db2_pconnect</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>statement</parameter></term>
     <listitem>
      <para>
       Un comando SQL, que puede contener opcionalmente uno o más marcadores de parámetros.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       Un arreglo asociativo que contiene opciones para el comando.  Se puede usar
       para solicitar un cursor desplazable en servidores que lo permitan.
      </para>
      <para>
       Se pueden revisar las opciones en <function>db2_set_option</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Si el comando SQL fue parseado y preparado exitosamente devuelve un <type>resource</type>,
   o &false; en caso de producirse un error.   Se puede determinar qué error ocurrió utilizando
   <function>db2_stmt_error</function> o <function>db2_stmt_errormsg</function>.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Preparando y ejecutando un comando SQL con marcadores de parámetros.</title>
    <para>
     El siguiente ejemplo prepara un comando INSERT que acepta cuatro marcadores
     de parámetros, y luego ejecuta iteraciones sobre un arreglo que contiene
     los valores de entrada, y éstos son enviados a través de <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
-->