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
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry id="function.db2-prepare">
<refnamediv>
<refname>db2_prepare</refname>
<refpurpose>
Prepares an SQL statement to be executed
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>resource</type><methodname>db2_prepare</methodname>
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>statement</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
<function>db2_prepare</function> creates a prepared SQL statement which can
include 0 or more parameter markers (<literal>?</literal> characters)
representing parameters for input, output, or input/output. You can pass
parameters to the prepared statement using
<function>db2_bind_param</function>, or for input values only, as an array
passed to <function>db2_execute</function>.
</para>
<para>
There are three main advantages to using prepared statements in your
application:
<itemizedlist>
<listitem>
<para>
<emphasis>Performance</emphasis>: when you prepare a statement, the
database server creates an optimized access plan for retrieving data with
that statement. Subsequently issuing the prepared statement with
<function>db2_execute</function> enables the statements to reuse that
access plan and avoids the overhead of dynamically creating a new access
plan for every statement you issue.
</para>
</listitem>
<listitem>
<para>
<emphasis>Security</emphasis>: when you prepare a statement, you can
include parameter markers for input values. When you execute a prepared
statement with input values for placeholders, the database server checks
each input value to ensure that the type matches the column definition or
parameter definition.
</para>
</listitem>
<listitem>
<para>
<emphasis>Advanced functionality</emphasis>: Parameter markers not only
enable you to pass input values to prepared SQL statements, they also
enable you to retrieve OUT and INOUT parameters from stored procedures
using <function>db2_bind_param</function>.
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>connection</parameter></term>
<listitem>
<para>
A valid database connection resource variable as returned from
<function>db2_connect</function> or <function>db2_pconnect</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>statement</parameter></term>
<listitem>
<para>
An SQL statement, optionally containing one or more parameter markers..
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
<para>
An associative array containing statement options. You can use this
parameter to request a scrollable cursor on database servers that
support this functionality.
<variablelist>
<varlistentry>
<term><parameter>cursor</parameter></term>
<listitem>
<para>
Passing the <literal>DB2_FORWARD_ONLY</literal> value requests a
forward-only cursor for this SQL statement. This is the default
type of cursor, and it is supported by all database servers. It is
also much faster than a scrollable cursor.
</para>
<para>
Passing the <literal>DB2_SCROLLABLE</literal> value requests a
scrollable cursor for this SQL statement. This type of cursor
enables you to fetch rows non-sequentially from the database
server. However, it is only supported by DB2 servers, and is much
slower than forward-only cursors.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a statement resource if the SQL statement was successfully parsed and
prepared by the database server. Returns &false; if the database server
returned an error. You can determine which error was returned by calling
<function>db2_stmt_error</function> or <function>db2_stmt_errormsg</function>.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Preparing and executing an SQL statement with parameter markers</title>
<para>
The following example prepares an INSERT statement that accepts four
parameter markers, then iterates over an array of arrays containing the
input values to be passed to <function>db2_execute</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
$animals = array(
array(0, 'cat', 'Pook', 3.2),
array(1, 'dog', 'Peaches', 12.3),
array(2, 'horse', 'Smarty', 350.0),
);
$insert = 'INSERT INTO animals (id, breed, name, weight)
VALUES (?, ?, ?, ?)';
$stmt = db2_prepare($conn, $insert);
if ($stmt) {
foreach ($animals as $animal) {
$result = db2_execute($stmt, $animal);
}
}
?>
]]>
</programlisting>
</example>
<!--
<example>
<title>Preventing SQL injection attacks using parameter markers</title>
<para>
Parameter markers make it impossible for a malicious user of your
application to pass input values that map to more than one database
field or stored procedure parameter. The following example demonstrates
a common tactic for attacking database-driven Web applications, SQL
injection, which takes advantage of applications that often simply
interpolate the input values from a user directly into an SQL statement
rather than defining parameter markers and binding the input values to
those parameter markers.
</para>
<para>
In the following example, assume that the PHP script has been placed on
a publically accessible Web server and the application provides
different levels of access for different users. We shall also assume
that the application issues an SQL statement that updates the privilege
level of a newly registered user to the lowest level, taking the user ID
from a GET input variable. In the following example, a malicious user
can pass <userinput>userid=0+OR+1=1</userinput> (instead of the expected
<userinput>userid=0</userinput>) to trick your application into
setting the privilege level of every user in the database to the lowest
level.
</para>
<programlisting role="php">
<![CDATA[
<?php
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
]]>
</screen>
</example>
-->
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>db2_bind_param</function></member>
<member><function>db2_execute</function></member>
<member><function>db2_stmt_error</function></member>
<member><function>db2_stmt_errormsg</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
-->
|
