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

Envía una solicitud al servidor para crear una sentencia preparada con los parámetros

dados y espera la ejecución

</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> crea una consulta preparada para una

ejecución posterior con <function>pg_execute</function> o

<function>pg_send_execute</function>.

Esta característica permite que las órdenes que serán utilizadas

repetidamente sean analizadas y planificadas una sola vez,

en lugar de ser ejecutadas cada vez.

</para>

<para>

La función crea una consulta preparada llamada

<parameter>stmtname</parameter> a partir de la cadena

<parameter>query</parameter>, la cual debe contener una sola orden

SQL. <parameter>stmtname</parameter> puede ser <literal>""</literal> para crear una

consulta sin nombre. En este caso, las consultas que existían y

que no tenían nombres son automáticamente sobrescritas; de lo contrario, habrá un error si el nombre de la consulta ya está definido en la sesión actual. Si se utilizan parámetros, estos son referenciados como <literal>$1</literal>,

<literal>$2</literal>, etc.

en <parameter>query</parameter>.

</para>

<para>

Las consultas preparadas para ser utilizadas con <function>pg_prepare</function>

también pueden ser creadas ejecutando la orden SQL

<literal>PREPARE</literal>. (Sin embargo, <function>pg_prepare</function>

es más flexible ya que no requiere que los tipos de los parámetros

sean preespecificados.) Además, aunque no existe una función PHP para

eliminar una consulta preparada, la orden SQL

<literal>DEALLOCATE</literal> puede ser utilizada para este propósito.

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

El nombre a dar a la consulta preparada. Debe ser único para cada

sesión. Si se especifica una cadena vacía <literal>""</literal> entonces se crea una consulta sin

nombre, sobrescribiendo las consultas sin nombres previamente definidas.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>query</parameter></term>

<listitem>

<para>

La consulta SQL con sus parámetros. Debe contener solo una sola

consulta. Varios comandos separados por punto y coma no son

permitidos. Si se utilizan parámetros, estos son referenciados como

<literal>$1</literal>, <literal>$2</literal>, etc.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Una instancia <classname>PgSql\Result</classname> en caso de éxito, &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>Ejemplo con <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>