doc-fr/reference/ibm_db2/functions/db2-prepare.xml

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

<refentry xml:id="function.db2-prepare" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>db2_prepare</refname>
  <refpurpose>
   Prépare une requête SQL à être exécutée
  </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> crée une requête SQL préparée qui peut
   inclure aucun ou plusieurs marqueurs (caractères <literal>?</literal>)
   représentant les paramètres d'entrée, sortie ou d'entrée/sortie. Vous
   pouvez passer des paramètres à la requête préparée en utilisant la
   fonction <function>db2_bind_param</function>, si vous avez que des entrées,
   vous pouvez utiliser <function>db2_execute</function>.
  </para>
  <para>
   Il y a trois principaux avantages d'utiliser les requêtes préparées dans
   votre application :
   <itemizedlist>
    <listitem>
     <para>
      <emphasis>Performance</emphasis> : lorsque vous préparez une requête, le
      serveur de base de données crée un plan d'accès optimisé pour la
      récupération des données avec la requête. Par la suite, l'envoi de la
      requête préparée avec <function>db2_execute</function> permet à la
      requête de réutiliser le plan d'accès et ainsi d'éviter les surcharges
      du processeurs à chaque envoi de requête qui créerait dynamiquement un
      nouveau plan d'accès.
     </para>
    </listitem>
    <listitem>
     <para>
      <emphasis>Sécurité</emphasis> : lorsque vous préparez une requête, vous
      pouvez inclure des marqueurs pour les valeurs d'entrées. Lorsque vous
      exécutez une requête préparée avec ces valeurs d'entrées, le serveur de
      base de données vérifie chaque valeur d'entrée pour s'assurer que les
      types concordent avec la définition de la colonne ou du paramètre de
      définition.
     </para>
    </listitem>
    <listitem>
     <para>
      <emphasis>Fonctionnalité avancée</emphasis> : Les marqueurs vous permettent
      non seulement de passer des valeurs d'entrées dans les requêtes SQL
      préparées, mais permettent aussi de récupérer des paramètres de SORTIE et
      d'ENTRÉE/SORTIE des procédures d'enregistrement en utilisant la fonction
      <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>
       Une variable ressource de connexion valide retournée par 
       <function>db2_connect</function> ou <function>db2_pconnect</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>statement</parameter></term>
     <listitem>
      <para>
       Une requête SQL qui peut contenir un ou plusieurs marqueurs.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       Un tableau associatif contenant les options de la requête. Vous pouvez
       utiliser ce paramètre pour demander un curseur flottant sur les
       serveurs de base de données qui supportent cette fonctionnalité.
      </para>
      <para>
       Pour une description des options valides, reportez-vous à la fonction
       <function>db2_set_option</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne une variable ressource si la requête SQL était envoyée
   correctement ou &false; si le serveur de base de données a
   retourné une erreur. Vous pouvez déterminer quelle erreur a été retournée
   en appelant la fonction 
   <function>db2_stmt_error</function> ou <function>db2_stmt_errormsg</function>.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Préparation et exécution d'une requête SQL avec des marqueurs</title>
    <para>
     L'exemple suivant prépare une requête INSERT qui accepte quatre
     marqueurs, ensuite itère sur le tableau contenant les valeurs d'entrées
     qui sera passé à la fonction <function>db2_execute</function>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$animaux = array(
    array(0, 'chat', 'Pook', 3.2),
    array(1, 'chien', 'Peaches', 12.3),
    array(2, 'cheval', 'Smarty', 350.0),
);

$insert = 'INSERT INTO animaux (id, race, nom, poids)
    VALUES (?, ?, ?, ?)';
$stmt = db2_prepare($conn, $insert);
if ($stmt) {
    foreach ($animaux as $animal) {
        $result = db2_execute($stmt, $animal);
    }
}
?>
]]>
    </programlisting>
   </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
-->