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
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<sect1 xml:id="internals2.pdo.pdo-dbh-t" xmlns="http://docbook.org/ns/docbook">
<title>pdo_dbh_t definition</title>
<para>
All fields should be treated as read-only by the driver, unless explicitly
stated otherwise.
</para>
<figure>
<title>pdo_dbh_t</title>
<programlisting role="c">
/* represents a connection to a database */
struct _pdo_dbh_t {
/* driver specific methods */
struct pdo_dbh_methods *methods; <co xml:id="internals2.pdo.dbh.co.methods" linkends="internals2.pdo.dbh.co.methods-co"/>
/* driver specific data */
void *driver_data; <co xml:id="internals2.pdo.dbh.co.driver-data" linkends="internals2.pdo.dbh.co.driver-data-co"/>
/* credentials */
char *username, *password; <co
xml:id="internals2.pdo.dbh.co.credentials"
linkends="internals2.pdo.dbh.co.credentials-co"/>
/* if true, then data stored and pointed at by this handle must all be
* persistently allocated */
unsigned is_persistent:1; <co
xml:id="internals2.pdo.dbh.co.is-persist"
linkends="internals2.pdo.dbh.co.is-persist-co"/>
/* if true, driver should act as though a COMMIT were executed between
* each executed statement; otherwise, COMMIT must be carried out manually
* */
unsigned auto_commit:1; <co
xml:id="internals2.pdo.dbh.co.auto-commit"
linkends="internals2.pdo.dbh.co.auto-commit-co"/>
/* if true, the driver requires that memory be allocated explicitly for
* the columns that are returned */
unsigned alloc_own_columns:1; <co
xml:id="internals2.pdo.dbh.co.alloc-own"
linkends="internals2.pdo.dbh.co.alloc-own-co"/>
/* if true, commit or rollBack is allowed to be called */
unsigned in_txn:1;
/* max length a single character can become after correct quoting */
unsigned max_escaped_char_length:3; <co
xml:id="internals2.pdo.dbh.co.max-esc"
linkends="internals2.pdo.dbh.co.max-esc-co"/>
/* data source string used to open this handle */
const char *data_source; <co xml:id="internals2.pdo.dbh.co.dsn"
linkends="internals2.pdo.dbh.co.dsn-co"/>
unsigned long data_source_len;
/* the global error code. */
pdo_error_type error_code; <co
xml:id="internals2.pdo.dbh.co.error-code"
linkends="internals2.pdo.dbh.co.error-code-co"/>
enum pdo_case_conversion native_case<co xml:id="internals2.pdo.dbh.co-ncase"
linkends="internals2.pdo.dbh.co-ncase-co"/>, desired_case;
};
</programlisting>
</figure>
<calloutlist>
<callout arearefs="internals2.pdo.dbh.co.methods"
xml:id="internals2.pdo.dbh.co.methods-co">
<para>
The driver <emphasis>must</emphasis> set this during
<function>SKEL_handle_factory</function>.
</para>
</callout>
<callout arearefs="internals2.pdo.dbh.co.driver-data"
xml:id="internals2.pdo.dbh.co.driver-data-co">
<para>
This item is for use by the driver; the intended usage is to store a
pointer (during <function>SKEL_handle_factory</function>)
to whatever instance data is required to maintain a connection to
the database.
</para>
</callout>
<callout arearefs="internals2.pdo.dbh.co.credentials"
xml:id="internals2.pdo.dbh.co.credentials-co">
<para>
The username and password that were passed into the PDO constructor.
The driver should use these values when it initiates a connection to the
database.
</para>
</callout>
<callout arearefs="internals2.pdo.dbh.co.is-persist"
xml:id="internals2.pdo.dbh.co.is-persist-co">
<para>
If this is set to 1, then any data that is referenced by the
dbh, including whatever structure your driver allocates,
<emphasis>MUST</emphasis> be allocated persistently. This is easy to
achieve; rather than using the usual <function>emalloc</function> simply
use <function>pemalloc</function> and pass the value of this flag as the
last parameter. Failure to use the appropriate kind of memory can lead
to serious memory faults, resulting (in the best case) a hard crash, and
in the worst case, an exploitable memory problem.
</para>
<para>
If, for whatever reason, your driver is not suitable to run persistently,
you <emphasis>MUST</emphasis> check this flag in your
<function>SKEL_handle_factory</function> and raise an appropriate error.
</para>
</callout>
<callout arearefs="internals2.pdo.dbh.co.auto-commit"
xml:id="internals2.pdo.dbh.co.auto-commit-co">
<para>
You should check this value in your <function>SKEL_handle_doer</function>
and <function>SKEL_stmt_execute</function> functions; if it evaluates to
true, you must attempt to commit the query now. Most database
implementations offer an auto-commit mode that handles this automatically.
</para>
</callout>
<callout arearefs="internals2.pdo.dbh.co.alloc-own"
xml:id="internals2.pdo.dbh.co.alloc-own-co">
<para>
If your database client library API operates by fetching data into a
caller-supplied buffer, you should set this flag to 1 during your
<function>SKEL_handle_factory</function>. When set, PDO will call your
<function>SKEL_stmt_describer</function> earlier than it would
otherwise. This early call allows you to determine those buffer sizes
and issue appropriate calls to the database client library.
</para>
<para>
If your database client library API simply returns pointers to its own
internal buffers for you to copy after each fetch call, you should leave
this value set to 0.
</para>
</callout>
<callout arearefs="internals2.pdo.dbh.co.max-esc"
xml:id="internals2.pdo.dbh.co.max-esc-co">
<para>
If your driver doesn't support native prepared statements
(<parameter>supports_placeholders</parameter> is set to
<constant>PDO_PLACEHOLDER_NONE</constant>), you must set
this value to the maximum length that can be taken up by a single
character when it is quoted by your
<function>SKEL_handle_quoter</function> function. This value is used to
calculate the amount of buffer space required when PDO executes the
statement.
</para>
</callout>
<callout arearefs="internals2.pdo.dbh.co.dsn"
xml:id="internals2.pdo.dbh.co.dsn-co">
<para>
This holds the value of the DSN that was passed into the PDO
constructor. If your driver implementation needed to modify the DSN for
whatever reason, it should update this member during
<function>SKEL_handle_factory</function>. Modifying this member should
be avoided. If you do change it, you must ensure that
<parameter>data_source_len</parameter> is also correct.
</para>
</callout>
<callout arearefs="internals2.pdo.dbh.co.error-code"
xml:id="internals2.pdo.dbh.co.error-code-co">
<para>
Whenever an error occurs during a call to one of your driver methods,
you should set this member to the SQLSTATE code that best describes the
error and return an error. In this HOW-TO, the suggested practice is to
call <function>SKEL_handle_error</function> when an error is detected,
and have it set the error code.
</para>
</callout>
<callout arearefs="internals2.pdo.dbh.co-ncase"
xml:id="internals2.pdo.dbh.co-ncase-co">
<para>
Your driver should set this during
<function>SKEL_handle_factory</function>; the value should reflect how
the database returns the names of the columns in result sets. If the
name matches the case that was used in the query, set it to
<constant>PDO_CASE_NATURAL</constant> (this is actually the default).
If the column names are always returned in upper case, set it to
<constant>PDO_CASE_UPPER</constant>. If the column names are always
returned in lower case, set it to <constant>PDO_CASE_LOWER</constant>.
The value you set is used to determine if PDO should perform case
folding when the user sets the <constant>PDO_ATTR_CASE</constant>
attribute.
</para>
</callout>
</calloutlist>
</sect1>
<!-- 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
-->
|
