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

指定したパラメータでプリペアドステートメントを作成するリクエストを

サーバーに送信し、その完了を待つ

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

<function>pg_execute</function> あるいは <function>pg_send_execute</function>

で後に実行するためのプリペアドステートメントを作成します。これにより、

繰り返し使用されるコマンドについての構文解析や実行計画作成が最初の

一度だけですみます。

</para>

<para>

この関数は <parameter>stmtname</parameter> という名前の

プリペアドステートメントを <parameter>query</parameter> 文字列から作成します。

この文字列には 1 つの SQL コマンドが含まれている必要があります。

<parameter>stmtname</parameter> を <literal>""</literal> にすることで無名ステートメントを

作成することが可能で、既存の無名ステートメントは自動的に上書きされます。

それ以外の場合、もしカレントのセッションで既に定義済みのステートメント名を

使用した場合にはエラーとなります。パラメータを使用する際は、

<parameter>query</parameter> 内で <literal>$1</literal>、<literal>$2</literal> のような形式で参照されます。

</para>

<para>

<function>pg_prepare</function> で使用するプリペアドステートメントは、

SQLの <literal>PREPARE</literal> 文を実行することでも作成可能です

（しかし、パラメータの型を事前に指定する必要がないという点で

<function>pg_prepare</function> のほうがより柔軟です）。

また、PHP にはプリペアドステートメントを削除する関数がありませんが、

この目的のためには SQLの <literal>DEALLOCATE</literal> 文が使用可能です。

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

プリペアドステートメントにつける名前。接続内で一意である必要があります。

<literal>""</literal> が指定された場合は無名ステートメントが作成され、以前に定義された

無名ステートメントを上書きします。

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

パラメータ化した SQL 文。ひとつの文のみである必要があります

（複数の文をセミコロンで区切る形式は使用できません）。パラメータを

使用する際は <literal>$1</literal>、<literal>$2</literal> などの形式で参照されます。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

成功した場合に

<classname>PgSql\Result</classname>

クラスのインスタンスを返します。

&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> の使用法</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>