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

Sendet eine Aufforderung an den Server, eine vorbereitete Anfrage mit den

übergebenen Parametern zu erzeugen und wartet auf ihre Beendigung

</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> erzeugt eine vorbereitete Abfrage, die

später mit <function>pg_execute</function> oder

<function>pg_send_execute</function> ausgeführt werden kann. Dank dieser

Eigenschaft brauchen wiederholt ausgeführte Abfragen nur ein einziges Mal

geparst und geplant werden, anstatt bei jeder Ausführung.

<function>pg_prepare</function> wird nur für Verbindungen zu PostgreSQL ab

der Version 7.4 unterstützt und schlägt bei allen niedrigeren Versionen

fehl.

</para>

<para>

Diese Funktion erzeugt aus der Abfrage <parameter>query</parameter> eine

vorbereitete Abfrage mit dem Namen <parameter>stmtname</parameter>.

<parameter>query</parameter> darf nur ein einzelnes SQL-Kommando enthalten.

<parameter>stmtname</parameter> kann <literal>""</literal> sein, um eine

unbenannte Abfrage zu erzeugen, wobei zuvor definierte unbenannte Abfragen

automatisch überschrieben werden. Falls der Name der vorbereiteten Abfrage

in der aktuellen Datenbanksitzung schon vergeben ist, wird ein Fehler

zurückgegeben. Falls irgendwelche Parameter übergeben wurden, werden diese

in <parameter>query</parameter> als <literal>$1</literal>,

<literal>$2</literal> usw. referenziert.

</para>

<para>

Vorbereitete Abfragen, die mit <function>pg_prepare</function> erzeugt

wurden, können ebenso mit dem SQL-Kommando <literal>PREPARE</literal>

erzeugt werden (allerdings ist <function>pg_prepare</function> flexibler,

weil Parametertypen nicht vorab deklariert werden müssen). Obwohl es keine

PHP-Funktion zum Löschen vorbereiteter Anfragen gibt, können diese mit dem

SQL-Kommando <literal>DEALLOCATE</literal> gelöscht werden.

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

Der Name, unter dem die vorbereitete Abfrage gespeichert wird. Dieser

muss für jede Verbindung eindeutig sein. Falls <literal>""</literal>

angegeben wurde, wird eine unbenannte Abfrage erzeugt, die alle zuvor

definierten unbenannten Abfragen überschreibt.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Die parametrisierte vorbereitete Abfrage. Diese darf nur ein einziges

SQL-Kommando enthalten (mehrere Kommandos, durch Semikolon getrennt,

sind nicht zulässig). Falls Parameter übergeben werden, werden sie als

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

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Bei Erfolg wird eine <classname>PgSql\Result</classname>-Instanz zurückgegeben.

&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><function>pg_prepare</function>-Beispiel</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>