1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry xml:id="function.pg-prepare" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>pg_prepare</refname>
<refpurpose>
Submits a request to the server to create a prepared statement with the
given parameters, and waits for completion
</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> creates a prepared statement for later execution with
<function>pg_execute</function> or <function>pg_send_execute</function>.
This feature allows commands that will be used repeatedly to
be parsed and planned just once, rather than each time they are executed.
<function>pg_prepare</function> is supported only against PostgreSQL 7.4 or
higher connections; it will fail when using earlier versions.
</para>
<para>
The function creates a prepared statement named <parameter>stmtname</parameter> from the <parameter>query</parameter>
string, which must contain a single SQL command. <parameter>stmtname</parameter> may be <literal>""</literal> to
create an unnamed statement, in which case any pre-existing unnamed
statement is automatically replaced; otherwise it is an error if the
statement name is already defined in the current session. If any parameters
are used, they are referred to in the <parameter>query</parameter> as <literal>$1</literal>,
<literal>$2</literal>, etc.
</para>
<para>
Prepared statements for use with <function>pg_prepare</function> can also be created by
executing SQL <literal>PREPARE</literal> statements. (But <function>pg_prepare</function> is
more flexible since it does not require parameter types to be pre-specified.) Also,
although there is no PHP function for deleting a prepared statement, the
SQL <literal>DEALLOCATE</literal> statement can be used for that purpose.
</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>
The name to give the prepared statement. Must be unique per-connection. If
<literal>""</literal> is specified, then an unnamed statement is created, overwriting any
previously defined unnamed statement.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>query</parameter></term>
<listitem>
<para>
The parameterized SQL statement. Must contain only a single statement
(multiple statements separated by semi-colons are not allowed). If any parameters
are used, they are referred to as <literal>$1</literal>, <literal>$2</literal>, etc.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
An <classname>PgSql\Result</classname> instance on success, &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>Using <function>pg_prepare</function></title>
<programlisting role="php">
<![CDATA[
<?php
// Connect to a database named "mary"
$dbconn = pg_connect("dbname=mary");
// Prepare a query for execution
$result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
// Execute the prepared query. Note that it is not necessary to escape
// the string "Joe's Widgets" in any way
$result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));
// Execute the same prepared query, this time with a different parameter
$result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
?>
]]>
</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
-->
|
