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
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-query-params">
<refnamediv>
<refname>pg_query_params</refname>
<refpurpose>Submits a command to the server and waits for the result, with the ability to pass parameters separately from the SQL command text.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>resource</type><methodname>pg_query_params</methodname>
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>resource</type><methodname>pg_query_params</methodname>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
Submits a command to the server and waits for the result, with the ability
to pass parameters separately from the SQL command text.
</para>
<para>
<function>pg_query_params</function> is like <function>pg_query</function>,
but offers additional functionality: parameter
values can be specified separately from the command string proper.
<function>pg_query_params</function> is supported only against PostgreSQL 7.4 or
higher connections; it will fail when using earlier versions.
</para>
<para>
If parameters are used, they are referred to in the <parameter>query</parameter>
string as $1, $2, etc. <parameter>params</parameter> specifies the actual values of the
parameters. A &null; value in this array means the corresponding parameter is SQL
<literal>NULL</literal>.
</para>
<para>
The primary advantage of <function>pg_query_params</function> over <function>pg_query</function>
is that parameter values
may be separated from the <parameter>query</parameter> string, thus avoiding the need for tedious
and error-prone quoting and escaping. Unlike <function>pg_query</function>,
<function>pg_query_params</function> allows at
most one SQL command in the given string. (There can be semicolons in it,
but not more than one nonempty command.)
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>connection</parameter></term>
<listitem>
<para>
PostgreSQL database connection resource. When
<parameter>connection</parameter> is not present, the default connection
is used. The default connection is the last connection made by
<function>pg_connect</function> or <function>pg_pconnect</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>query</parameter></term>
<listitem>
<para>
The parameterised 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 $1, $2, etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>params</parameter></term>
<listitem>
<para>
An array of parameter values to substitute for the $1, $2, etc. placeholders
in the original prepared query string. The number of elements in the array
must match the number of placeholders.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
A query result resource on success, or &false; on failure.</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Using <function>pg_query_params</function></title>
<programlisting role="php">
<![CDATA[
<?php
// Connect to a database named "mary"
$dbconn = pg_connect("dbname=mary");
// Find all shops named Joe's Widgets. Note that it is not necessary to
// escape "Joe's Widgets"
$result = pg_query_params($dbconn, 'SELECT * FROM shops WHERE name = $1', array("Joe's Widgets"));
// Compare against just using pg_query
$str = pg_escape_string("Joe's Widgets");
$result = pg_query($dbconn, "SELECT * FROM shops WHERE name = '{$str}'");
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>pg_query</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:"../../../../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
-->
|
