reference/pdo/pdo/setattribute.xml
c60137e9d56c40861f6235d60c4553937c77af22
c60137e9d56c40861f6235d60c4553937c77af22
...
...
@@ -1,4 +1,4 @@
1
-
<?xml version="1.0" encoding="UTF-8"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<refentry xml:id="pdo.setattribute" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
...
...
@@ -9,92 +9,256 @@
9
9
</refnamediv>
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
-
<methodsynopsis>
13
-
<type>bool</type><methodname>PDO::setAttribute</methodname>
12
+
<methodsynopsis role="PDO">
13
+
<modifier>public</modifier> <type>bool</type><methodname>PDO::setAttribute</methodname>
14
14
<methodparam><type>int</type><parameter>attribute</parameter></methodparam>
15
15
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
16
16
</methodsynopsis>
17
17
18
18
<para>
19
-
Sets an attribute on the database handle. Some of the available generic
19
+
Sets an attribute on the database handle. Some available generic
20
20
attributes are listed below; some drivers may make use of
21
21
additional driver specific attributes.
22
-
<itemizedlist>
23
-
<listitem><para>
24
-
<literal>PDO::ATTR_CASE</literal>: Force column names to a specific case.
25
-
<itemizedlist>
26
-
<listitem><para>
27
-
<literal>PDO::CASE_LOWER</literal>: Force column names to lower case.
28
-
</para></listitem>
29
-
<listitem><para>
30
-
<literal>PDO::CASE_NATURAL</literal>: Leave column names as returned by
31
-
the database driver.
32
-
</para></listitem>
33
-
<listitem><para>
34
-
<literal>PDO::CASE_UPPER</literal>: Force column names to upper case.
35
-
</para></listitem>
36
-
</itemizedlist>
37
-
</para></listitem>
38
-
<listitem><para><literal>PDO::ATTR_ERRMODE</literal>: Error reporting.
39
-
<itemizedlist>
40
-
<listitem><para><literal>PDO::ERRMODE_SILENT</literal>:
41
-
Just set error codes.</para></listitem>
42
-
<listitem><para><literal>PDO::ERRMODE_WARNING</literal>:
43
-
Raise <link linkend="errorfunc.constants.errorlevels.e-warning">E_WARNING</link>.</para></listitem>
44
-
<listitem><para><literal>PDO::ERRMODE_EXCEPTION</literal>:
45
-
Throw <link linkend="class.pdoexception">exceptions</link>.</para></listitem>
46
-
</itemizedlist>
47
-
</para></listitem>
48
-
<listitem><para><literal>PDO::ATTR_ORACLE_NULLS</literal>
49
-
(available with all drivers, not just Oracle):
50
-
Conversion of NULL and empty strings.
51
-
<itemizedlist>
52
-
<listitem><para><literal>PDO::NULL_NATURAL</literal>:
53
-
No conversion.</para></listitem>
54
-
<listitem><para><literal>PDO::NULL_EMPTY_STRING</literal>:
55
-
Empty string is converted to &null;.</para></listitem>
56
-
<listitem><para><literal>PDO::NULL_TO_STRING</literal>:
57
-
NULL is converted to an empty string.</para></listitem>
58
-
</itemizedlist>
59
-
</para></listitem>
60
-
<listitem><para><literal>PDO::ATTR_STRINGIFY_FETCHES</literal>:
61
-
Convert numeric values to strings when fetching.
62
-
Requires <type>bool</type>.
63
-
</para></listitem>
64
-
<listitem><para><literal>PDO::ATTR_STATEMENT_CLASS</literal>:
65
-
Set user-supplied statement class derived from PDOStatement.
66
-
Cannot be used with persistent PDO instances.
67
-
Requires <literal>array(string classname, array(mixed constructor_args))</literal>.
68
-
</para></listitem>
69
-
<listitem><para><literal>PDO::ATTR_TIMEOUT</literal>:
70
-
Specifies the timeout duration in seconds. Not all drivers support this option,
71
-
and it's meaning may differ from driver to driver. For example, sqlite will wait
72
-
for up to this time value before giving up on obtaining an writable lock, but
73
-
other drivers may interpret this as a connect or a read timeout interval.
74
-
Requires <type>int</type>.
75
-
</para></listitem>
76
-
<listitem><para><literal>PDO::ATTR_AUTOCOMMIT</literal>
77
-
(available in OCI, Firebird and MySQL):
78
-
Whether to autocommit every single statement.
79
-
</para></listitem>
80
-
<listitem><para><literal>PDO::ATTR_EMULATE_PREPARES</literal>
81
-
Enables or disables emulation of prepared statements. Some drivers do
82
-
not support native prepared statements or have limited support for them.
83
-
Use this setting to force PDO to either always emulate prepared
84
-
statements (if &true;), or to try to use native prepared statements (if
85
-
&false;). It will always fall back to emulating the prepared statement
86
-
if the driver cannot successfully prepare the current query.
87
-
Requires <type>bool</type>.
88
-
</para></listitem>
89
-
<listitem><para><literal>PDO::MYSQL_ATTR_USE_BUFFERED_QUERY</literal>
90
-
(available in MySQL):
91
-
Use buffered queries.
92
-
</para></listitem>
93
-
<listitem><para><literal>PDO::ATTR_DEFAULT_FETCH_MODE</literal>:
94
-
Set default fetch mode. Description of modes is available in
95
-
<function>PDOStatement::fetch</function> documentation.
96
-
</para></listitem>
97
-
</itemizedlist>
22
+
Note that driver specific attributes <emphasis>must not</emphasis> be used
23
+
with other drivers.
24
+
<variablelist>
25
+
<varlistentry>
26
+
<term><constant>PDO::ATTR_CASE</constant></term>
27
+
<listitem>
28
+
<para>
29
+
Force column names to a specific case.
30
+
Can take one of the following values:
31
+
</para>
32
+
<variablelist>
33
+
<varlistentry>
34
+
<term><constant>PDO::CASE_LOWER</constant></term>
35
+
<listitem>
36
+
<simpara>
37
+
Force column names to lower case.
38
+
</simpara>
39
+
</listitem>
40
+
</varlistentry>
41
+
<varlistentry>
42
+
<term><constant>PDO::CASE_NATURAL</constant></term>
43
+
<listitem>
44
+
<simpara>
45
+
Leave column names as returned by the database driver.
46
+
</simpara>
47
+
</listitem>
48
+
</varlistentry>
49
+
<varlistentry>
50
+
<term><constant>PDO::CASE_UPPER</constant></term>
51
+
<listitem>
52
+
<simpara>
53
+
Force column names to upper case.
54
+
</simpara>
55
+
</listitem>
56
+
</varlistentry>
57
+
</variablelist>
58
+
</listitem>
59
+
</varlistentry>
60
+
<varlistentry>
61
+
<term><constant>PDO::ATTR_ERRMODE</constant></term>
62
+
<listitem>
63
+
<para>
64
+
Error reporting mode of PDO.
65
+
Can take one of the following values:
66
+
</para>
67
+
<variablelist>
68
+
<varlistentry>
69
+
<term><constant>PDO::ERRMODE_SILENT</constant></term>
70
+
<listitem>
71
+
<simpara>
72
+
Only sets error codes.
73
+
</simpara>
74
+
</listitem>
75
+
</varlistentry>
76
+
<varlistentry>
77
+
<term><constant>PDO::ERRMODE_WARNING</constant></term>
78
+
<listitem>
79
+
<simpara>
80
+
Raises <constant>E_WARNING</constant> diagnostics.
81
+
</simpara>
82
+
</listitem>
83
+
</varlistentry>
84
+
<varlistentry>
85
+
<term><constant>PDO::ERRMODE_EXCEPTION</constant></term>
86
+
<listitem>
87
+
<simpara>
88
+
Throws <classname>PDOException</classname>s.
89
+
</simpara>
90
+
</listitem>
91
+
</varlistentry>
92
+
</variablelist>
93
+
</listitem>
94
+
</varlistentry>
95
+
<varlistentry>
96
+
<term><constant>PDO::ATTR_ORACLE_NULLS</constant></term>
97
+
<listitem>
98
+
<note>
99
+
<simpara>
100
+
This attribute is available with all drivers, not just Oracle.
101
+
</simpara>
102
+
</note>
103
+
<para>
104
+
Determines if and how &null; and empty strings should be converted.
105
+
Can take one of the following values:
106
+
</para>
107
+
<variablelist>
108
+
<varlistentry>
109
+
<term><constant>PDO::NULL_NATURAL</constant></term>
110
+
<listitem>
111
+
<simpara>
112
+
No conversion takes place.
113
+
</simpara>
114
+
</listitem>
115
+
</varlistentry>
116
+
<varlistentry>
117
+
<term><constant>PDO::NULL_EMPTY_STRING</constant></term>
118
+
<listitem>
119
+
<simpara>
120
+
Empty strings get converted to &null;.
121
+
</simpara>
122
+
</listitem>
123
+
</varlistentry>
124
+
<varlistentry>
125
+
<term><constant>PDO::NULL_TO_STRING</constant></term>
126
+
<listitem>
127
+
<simpara>
128
+
&null; gets converted to an empty string.
129
+
</simpara>
130
+
</listitem>
131
+
</varlistentry>
132
+
</variablelist>
133
+
</listitem>
134
+
</varlistentry>
135
+
<varlistentry>
136
+
<term><constant>PDO::ATTR_STRINGIFY_FETCHES</constant></term>
137
+
<listitem>
138
+
<para>
139
+
Whether to convert numeric values to strings when fetching.
140
+
Takes a value of type <type>bool</type>: &true; to enable and
141
+
&false; to disable. <!-- By default, ??? TODO. -->
142
+
</para>
143
+
</listitem>
144
+
</varlistentry>
145
+
<varlistentry>
146
+
<term><constant>PDO::ATTR_STATEMENT_CLASS</constant></term>
147
+
<listitem>
148
+
<para>
149
+
Set user-supplied statement class derived from PDOStatement.
150
+
<!-- TODO improve description of the value it takes, or refer to other docs -->
151
+
Requires <literal>array(string classname, array(mixed constructor_args))</literal>.
152
+
</para>
153
+
<caution>
154
+
<simpara>
155
+
Cannot be used with persistent PDO instances.
156
+
</simpara>
157
+
</caution>
158
+
</listitem>
159
+
</varlistentry>
160
+
<varlistentry>
161
+
<term><constant>PDO::ATTR_TIMEOUT</constant></term>
162
+
<listitem>
163
+
<para>
164
+
Specifies the timeout duration in seconds.
165
+
Takes a value of type <type>int</type>.
166
+
</para>
167
+
<note>
168
+
<para>
169
+
Not all drivers support this option, and its meaning may differ from
170
+
driver to driver. For example, SQLite will wait for up to this time
171
+
value before giving up on obtaining a writable lock, but other drivers
172
+
may interpret this as a connection or a read timeout interval.
173
+
</para>
174
+
</note>
175
+
</listitem>
176
+
</varlistentry>
177
+
<varlistentry>
178
+
<term><constant>PDO::ATTR_AUTOCOMMIT</constant></term>
179
+
<listitem>
180
+
<note>
181
+
<simpara>
182
+
Only available for the OCI, Firebird, and MySQL drivers.
183
+
</simpara>
184
+
</note>
185
+
<para>
186
+
Whether to autocommit every single statement.
187
+
Takes a value of type <type>bool</type>: &true; to enable and
188
+
&false; to disable. By default, &true;.
189
+
</para>
190
+
</listitem>
191
+
</varlistentry>
192
+
<varlistentry>
193
+
<term><constant>PDO::ATTR_EMULATE_PREPARES</constant></term>
194
+
<listitem>
195
+
<note>
196
+
<simpara>
197
+
Only available for the OCI, Firebird, and MySQL drivers.
198
+
</simpara>
199
+
</note>
200
+
<para>
201
+
Whether enable or disable emulation of prepared statements.
202
+
Some drivers do not support prepared statements natively or have
203
+
limited support for them.
204
+
If set to &true; PDO will always emulate prepared statements,
205
+
otherwise PDO will attempt to use native prepared statements.
206
+
In case the driver cannot successfully prepare the current query,
207
+
PDO will always fall back to emulating the prepared statement.
208
+
</para>
209
+
</listitem>
210
+
</varlistentry>
211
+
<varlistentry>
212
+
<term><constant>PDO::MYSQL_ATTR_USE_BUFFERED_QUERY</constant></term>
213
+
<listitem>
214
+
<note>
215
+
<simpara>
216
+
Only available for the MySQL driver.
217
+
</simpara>
218
+
</note>
219
+
<para>
220
+
Whether to use buffered queries.
221
+
Takes a value of type <type>bool</type>: &true; to enable and
222
+
&false; to disable. By default, &true;.
223
+
</para>
224
+
</listitem>
225
+
</varlistentry>
226
+
<varlistentry>
227
+
<term><constant>PDO::ATTR_DEFAULT_FETCH_MODE</constant></term>
228
+
<listitem>
229
+
<para>
230
+
Set the default fetch mode.
231
+
A description of the modes and how to use them is available in the
232
+
<methodname>PDOStatement::fetch</methodname> documentation.
233
+
</para>
234
+
</listitem>
235
+
</varlistentry>
236
+
</variablelist>
237
+
</para>
238
+
</refsect1>
239
+
240
+
<refsect1 role="parameters">
241
+
&reftitle.parameters;
242
+
<para>
243
+
<variablelist>
244
+
<varlistentry>
245
+
<term><parameter>attribute</parameter></term>
246
+
<listitem>
247
+
<para>
248
+
The attribute to modify.
249
+
</para>
250
+
</listitem>
251
+
</varlistentry>
252
+
<varlistentry>
253
+
<term><parameter>value</parameter></term>
254
+
<listitem>
255
+
<para>
256
+
The value to set the <parameter>attribute</parameter>,
257
+
might require a specific type depending on the attribute.
258
+
</para>
259
+
</listitem>
260
+
</varlistentry>
261
+
</variablelist>
98
262
</para>
99
263
</refsect1>
100
264
...
...
@@ -105,8 +269,18 @@
105
269
</para>
106
270
</refsect1>
107
271
108
-
</refentry>
272
+
<refsect1 role="seealso">
273
+
&reftitle.seealso;
274
+
<para>
275
+
<simplelist>
276
+
<member><function>PDO::getAttribute</function></member>
277
+
<member><function>PDOStatement::getAttribute</function></member>
278
+
<member><function>PDOStatement::setAttribute</function></member>
279
+
</simplelist>
280
+
</para>
281
+
</refsect1>
109
282
283
+
</refentry>
110
284
<!-- Keep this comment at the end of the file
111
285
Local variables:
112
286
mode: sgml
113
287