<?xml version="1.0" encoding="utf-8"?>

<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">

</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>