archived-doc-fr/reference/pgsql/functions/pg-prepare.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 5f1a92089fa4efe81e9777f87f9ed93f4853898b Maintainer: lacatoire Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.pg-prepare" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>pg_prepare</refname>
  <refpurpose>
   Envoie une requête au serveur pour créer une instruction préparée avec les paramètres
   donnés et attend l'exécution
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>PgSql\Result</type><type>false</type></type><methodname>pg_prepare</methodname>
   <methodparam choice="opt"><type>PgSql\Connection</type><parameter>connection</parameter></methodparam>
   <methodparam><type>string</type><parameter>stmtname</parameter></methodparam>
   <methodparam><type>string</type><parameter>query</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>pg_prepare</function> crée une requête préparée pour une
   exécution ultérieure avec <function>pg_execute</function> ou
   <function>pg_send_execute</function>. 
   Cette caractéristique permet aux commandes qui seront utilisées à
   plusieurs reprises d'être analysées et planifiées qu'une seule fois,
   plutôt que d'être exécutées chaque fois.
  </para>
  <para>
   La fonction crée une requête préparée nommée
   <parameter>stmtname</parameter> à partir de la chaîne
   <parameter>query</parameter>, celle-ci ne doit contenir qu'une seule commande
   SQL. <parameter>stmtname</parameter> peut être <literal>""</literal> pour créer une
   requête qui n'est pas nommée. Dans ce cas, les requêtes qui existaient et
   qui se trouvaient sans noms sont automatiquement remplacées; autrement, il y
   aura une erreur si le nom de la requête est déjà défini dans la session
   courante. Si des paramètres sont utilisés, ils sont référés à <literal>$1</literal>,
   <literal>$2</literal>, etc.
   dans <parameter>query</parameter>.
  </para>
  <para>
   Des requêtes préparées à utiliser avec <function>pg_prepare</function>
   peuvent être aussi créées en exécutant la requête SQL
   <literal>PREPARE</literal>. (Par contre, <function>pg_prepare</function>
   est plus flexible puisqu'elle ne nécessite pas que les types des paramètres
   soient préspécifiés.) De plus, bien qu'il n'y ait pas de fonction PHP pour
   supprimer une requête préparée, la requête SQL
   <literal>DEALLOCATE</literal> peut être utilisée pour ce motif.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>connection</parameter></term>
     <listitem>
      &pgsql.parameter.connection-with-unspecified-default;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>stmtname</parameter></term>
     <listitem>
      <para>
       Le nom à donner à la requête préparée. Il doit être unique à chaque
       session. Si une chaîne vide est spécifiée <literal>""</literal> alors une requête sans
       nom est créée, écrasant les requêtes sans noms précédemment définies.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>query</parameter></term>
     <listitem>
      <para>
       La requête SQL avec ses paramètres. Elle doit contenir seulement une seule
       requête. Plusieurs requêtes séparées par des points-virgules ne sont
       pas autorisées. Si des paramètres sont utilisés, ils sont référés à
       <literal>$1</literal>, <literal>$2</literal>, etc.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Une instance <classname>PgSql\Result</classname> en cas de succès, &return.falseforfailure;.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     &pgsql.changelog.return-result-object;
     &pgsql.changelog.connection-object;
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>pg_prepare</function></title>
    <programlisting role="php">
<![CDATA[

<?php
// Connexion à une base de données nommée "marie"
$dbconn = pg_connect("dbname=marie");

// Prépare une requête pour l'exécution
$result = pg_prepare($dbconn, "my_query", 'SELECT * FROM magasins WHERE nom = $1');

// Exécute la requête préparée. À noter qu'il n'est pas nécessaire d'échapper
// la chaîne "Joe's Widgets"
$result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

// Exécute la même requête préparée, cette fois avec un paramètre différent
$result = pg_execute($dbconn, "my_query", array("Vêtements Vêtements Vêtements"));

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>pg_execute</function></member>
    <member><function>pg_send_execute</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
-->