Debian Codegraph @

doc/driver-guide/driverfuncs-infrastructure.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <HTML
3 ><HEAD
4 ><TITLE
5 >Driver Infrastructure Functions</TITLE
6 ><META
7 NAME="GENERATOR"
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9 REL="HOME"
10 TITLE="Database Independent Abstraction Layer for C"
11 HREF="index.html"><LINK
12 REL="UP"
13 TITLE="Driver Functions"
14 HREF="driverfuncs.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Driver Functions"
17 HREF="driverfuncs.html"><LINK
18 REL="NEXT"
19 TITLE="Internal Database Query Functions"
20 HREF="driverfuncs-dbquery.html"></HEAD
21 ><BODY
22 CLASS="SECTION"
23 BGCOLOR="#FFFFFF"
24 TEXT="#000000"
25 LINK="#0000FF"
26 VLINK="#840084"
27 ALINK="#0000FF"
28 ><DIV
29 CLASS="NAVHEADER"
30 ><TABLE
31 SUMMARY="Header navigation table"
32 WIDTH="100%"
33 BORDER="0"
34 CELLPADDING="0"
35 CELLSPACING="0"
36 ><TR
37 ><TH
38 COLSPAN="3"
39 ALIGN="center"
40 >Database Independent Abstraction Layer for C: libdbi Driver Author's Guide</TH
41 ></TR
42 ><TR
43 ><TD
44 WIDTH="10%"
45 ALIGN="left"
46 VALIGN="bottom"
47 ><A
48 HREF="driverfuncs.html"
49 ACCESSKEY="P"
50 >Prev</A
51 ></TD
52 ><TD
53 WIDTH="80%"
54 ALIGN="center"
55 VALIGN="bottom"
56 >Chapter 3. Driver Functions</TD
57 ><TD
58 WIDTH="10%"
59 ALIGN="right"
60 VALIGN="bottom"
61 ><A
62 HREF="driverfuncs-dbquery.html"
63 ACCESSKEY="N"
64 >Next</A
65 ></TD
66 ></TR
67 ></TABLE
68 ><HR
69 ALIGN="LEFT"
70 WIDTH="100%"></DIV
71 ><DIV
72 CLASS="SECTION"
73 ><H1
74 CLASS="SECTION"
75 ><A
76 NAME="DRIVERFUNCS-INFRASTRUCTURE"
77 >3.1. Driver Infrastructure Functions</A
78 ></H1
79 ><P
80 >These functions are called by libdbi at startup and when the libdbi user establishes or takes down a database engine connection.</P
81 ><DIV
82 CLASS="SECTION"
83 ><H2
84 CLASS="SECTION"
85 ><A
86 NAME="DBD-REGISTER-DRIVER"
87 >3.1.1. dbd_register_driver</A
88 ></H2
89 ><DIV
90 CLASS="FUNCSYNOPSIS"
91 ><P
92 ></P
93 ><A
94 NAME="AEN150"
95 ></A
96 ><P
97 ><CODE
98 ><CODE
99 CLASS="FUNCDEF"
100 >void <B
101 CLASS="FSFUNC"
102 >dbd_register_driver</B
103 ></CODE
104 >(const dbi_info_t **<VAR
105 CLASS="PDPARAM"
106 >_driver_info</VAR
107 >, const char ***<VAR
108 CLASS="PDPARAM"
109 >_custom_functions</VAR
110 >, const char ***<VAR
111 CLASS="PDPARAM"
112 >_reserved_words</VAR
113 >);</CODE
114 ></P
115 ><P
116 ></P
117 ></DIV
118 ><P
119 >This is the first function called after the driver module is loaded into memory. It passes back meta-information back to libdbi through the pointers passed as arguments.</P
120 ><P
121 ></P
122 ><DIV
123 CLASS="VARIABLELIST"
124 ><DL
125 ><DT
126 >Arguments</DT
127 ><DD
128 ><P
129 ><TT
130 CLASS="LITERAL"
131 >_driver_info</TT
132 >: A pointer used to link to the driver's information struct.</P
133 ><P
134 ><TT
135 CLASS="LITERAL"
136 >_custom_functions</TT
137 >: A pointer used to link to the driver's string array of custom database-specific functions.</P
138 ><P
139 ><TT
140 CLASS="LITERAL"
141 >_reserved_words</TT
142 >: A pointer used to link to the driver's string array of reserved words.</P
143 ></DD
144 ></DL
145 ></DIV
146 ></DIV
147 ><DIV
148 CLASS="SECTION"
149 ><H2
150 CLASS="SECTION"
151 ><A
152 NAME="DBD-INITIALIZE"
153 >3.1.2. dbd_initialize</A
154 ></H2
155 ><DIV
156 CLASS="FUNCSYNOPSIS"
157 ><P
158 ></P
159 ><A
160 NAME="AEN173"
161 ></A
162 ><P
163 ><CODE
164 ><CODE
165 CLASS="FUNCDEF"
166 >int <B
167 CLASS="FSFUNC"
168 >dbd_initialize</B
169 ></CODE
170 >(dbi_driver_t *<VAR
171 CLASS="PDPARAM"
172 >driver</VAR
173 >);</CODE
174 ></P
175 ><P
176 ></P
177 ></DIV
178 ><P
179 >Performs any database-specific server initialization. This is called right after dbd_register_driver().</P
180 ><P
181 ></P
182 ><DIV
183 CLASS="VARIABLELIST"
184 ><DL
185 ><DT
186 >Arguments</DT
187 ><DD
188 ><P
189 ><TT
190 CLASS="LITERAL"
191 >driver</TT
192 >: The driver's pointer.</P
193 ></DD
194 ><DT
195 >Returns</DT
196 ><DD
197 ><P
198 >-1 on error, 0 on success. If -1 is returned, the driver will not be added to the list of available drivers.</P
199 ></DD
200 ></DL
201 ></DIV
202 ></DIV
203 ><DIV
204 CLASS="SECTION"
205 ><H2
206 CLASS="SECTION"
207 ><A
208 NAME="DBD-CONNECT"
209 >3.1.3. dbd_connect</A
210 ></H2
211 ><DIV
212 CLASS="FUNCSYNOPSIS"
213 ><P
214 ></P
215 ><A
216 NAME="AEN192"
217 ></A
218 ><P
219 ><CODE
220 ><CODE
221 CLASS="FUNCDEF"
222 >int <B
223 CLASS="FSFUNC"
224 >dbd_connect</B
225 ></CODE
226 >(dbi_conn_t *<VAR
227 CLASS="PDPARAM"
228 >conn</VAR
229 >);</CODE
230 ></P
231 ><P
232 ></P
233 ></DIV
234 ><P
235 >Connects to the database, setting the connection's DB-specific connection handle and current database name. Connection parameters are already filled through the connection's option settings. The standard options that all drivers must recognize (if applicable) are: host, port, username, password, dbname, and encoding. Any driver-specific functions must be prefixed with the name of the driver and an underscore, such as "mysql_compression".</P
236 ><P
237 ></P
238 ><DIV
239 CLASS="VARIABLELIST"
240 ><DL
241 ><DT
242 >Arguments</DT
243 ><DD
244 ><P
245 ><TT
246 CLASS="LITERAL"
247 >conn</TT
248 >: The target connection instance of the driver.</P
249 ></DD
250 ><DT
251 >Returns</DT
252 ><DD
253 ><P
254 >&lt;0 on error, 0 on success.</P
255 ></DD
256 ></DL
257 ></DIV
258 ></DIV
259 ><DIV
260 CLASS="SECTION"
261 ><H2
262 CLASS="SECTION"
263 ><A
264 NAME="DBD-DISCONNECT"
265 >3.1.4. dbd_disconnect</A
266 ></H2
267 ><DIV
268 CLASS="FUNCSYNOPSIS"
269 ><P
270 ></P
271 ><A
272 NAME="AEN211"
273 ></A
274 ><P
275 ><CODE
276 ><CODE
277 CLASS="FUNCDEF"
278 >int <B
279 CLASS="FSFUNC"
280 >dbd_disconnect</B
281 ></CODE
282 >(dbi_conn_t *<VAR
283 CLASS="PDPARAM"
284 >conn</VAR
285 >);</CODE
286 ></P
287 ><P
288 ></P
289 ></DIV
290 ><P
291 >Disconnects from the database server.</P
292 ><P
293 ></P
294 ><DIV
295 CLASS="VARIABLELIST"
296 ><DL
297 ><DT
298 >Arguments</DT
299 ><DD
300 ><P
301 ><TT
302 CLASS="LITERAL"
303 >conn</TT
304 >: The target connection instance of the driver.</P
305 ></DD
306 ><DT
307 >Returns</DT
308 ><DD
309 ><P
310 >-1 on error, 0 on success.</P
311 ></DD
312 ></DL
313 ></DIV
314 ></DIV
315 ><DIV
316 CLASS="SECTION"
317 ><H2
318 CLASS="SECTION"
319 ><A
320 NAME="DBD-GETERROR"
321 >3.1.5. dbd_geterror</A
322 ></H2
323 ><DIV
324 CLASS="FUNCSYNOPSIS"
325 ><P
326 ></P
327 ><A
328 NAME="AEN230"
329 ></A
330 ><P
331 ><CODE
332 ><CODE
333 CLASS="FUNCDEF"
334 >int <B
335 CLASS="FSFUNC"
336 >dbd_geterror</B
337 ></CODE
338 >(dbi_conn_t *<VAR
339 CLASS="PDPARAM"
340 >conn</VAR
341 >, int *<VAR
342 CLASS="PDPARAM"
343 >errno</VAR
344 >, char **<VAR
345 CLASS="PDPARAM"
346 >errstr</VAR
347 >);</CODE
348 ></P
349 ><P
350 ></P
351 ></DIV
352 ><P
353 >Retrieves and stores error information, in numeric and/or string format.</P
354 ><P
355 ></P
356 ><DIV
357 CLASS="VARIABLELIST"
358 ><DL
359 ><DT
360 >Arguments</DT
361 ><DD
362 ><P
363 ><TT
364 CLASS="LITERAL"
365 >conn</TT
366 >: The target connection.</P
367 ><P
368 ><TT
369 CLASS="LITERAL"
370 >errno</TT
371 >: The int variable to hold the error number.</P
372 ><P
373 ><TT
374 CLASS="LITERAL"
375 >errstr</TT
376 >: The string to hold the error description. The driver is supposed to provide the string as allocated memory which is further managed by libdbi.</P
377 ></DD
378 ><DT
379 >Returns</DT
380 ><DD
381 ><P
382 >0 if there was an error, 1 if errno was filled, 2 if errstr was filled, 3 if both errno and errstr were filled.</P
383 ></DD
384 ></DL
385 ></DIV
386 ></DIV
387 ><DIV
388 CLASS="SECTION"
389 ><H2
390 CLASS="SECTION"
391 ><A
392 NAME="DBD-GET-SOCKET"
393 >3.1.6. dbd_get_socket</A
394 ></H2
395 ><DIV
396 CLASS="FUNCSYNOPSIS"
397 ><P
398 ></P
399 ><A
400 NAME="AEN257"
401 ></A
402 ><P
403 ><CODE
404 ><CODE
405 CLASS="FUNCDEF"
406 >int <B
407 CLASS="FSFUNC"
408 >dbd_get_socket</B
409 ></CODE
410 >(dbi_conn_t *<VAR
411 CLASS="PDPARAM"
412 >conn</VAR
413 >);</CODE
414 ></P
415 ><P
416 ></P
417 ></DIV
418 ><P
419 >Retrieves the socket of the client/server connection used by the database client library, if applicable.</P
420 ><P
421 ></P
422 ><DIV
423 CLASS="VARIABLELIST"
424 ><DL
425 ><DT
426 >Arguments</DT
427 ><DD
428 ><P
429 ><TT
430 CLASS="LITERAL"
431 >conn</TT
432 >: The target connection.</P
433 ></DD
434 ><DT
435 >Returns</DT
436 ><DD
437 ><P
438 >The file descriptor of the socket if successful, -1 if there was an error. Drivers of database engines that do not use sockets should return 0.</P
439 ></DD
440 ></DL
441 ></DIV
442 ></DIV
443 ></DIV
444 ><DIV
445 CLASS="NAVFOOTER"
446 ><HR
447 ALIGN="LEFT"
448 WIDTH="100%"><TABLE
449 SUMMARY="Footer navigation table"
450 WIDTH="100%"
451 BORDER="0"
452 CELLPADDING="0"
453 CELLSPACING="0"
454 ><TR
455 ><TD
456 WIDTH="33%"
457 ALIGN="left"
458 VALIGN="top"
459 ><A
460 HREF="driverfuncs.html"
461 ACCESSKEY="P"
462 >Prev</A
463 ></TD
464 ><TD
465 WIDTH="34%"
466 ALIGN="center"
467 VALIGN="top"
468 ><A
469 HREF="index.html"
470 ACCESSKEY="H"
471 >Home</A
472 ></TD
473 ><TD
474 WIDTH="33%"
475 ALIGN="right"
476 VALIGN="top"
477 ><A
478 HREF="driverfuncs-dbquery.html"
479 ACCESSKEY="N"
480 >Next</A
481 ></TD
482 ></TR
483 ><TR
484 ><TD
485 WIDTH="33%"
486 ALIGN="left"
487 VALIGN="top"
488 >Driver Functions</TD
489 ><TD
490 WIDTH="34%"
491 ALIGN="center"
492 VALIGN="top"
493 ><A
494 HREF="driverfuncs.html"
495 ACCESSKEY="U"
496 >Up</A
497 ></TD
498 ><TD
499 WIDTH="33%"
500 ALIGN="right"
501 VALIGN="top"
502 >Internal Database Query Functions</TD
503 ></TR
504 ></TABLE
505 ></DIV
506 ></BODY
507 ></HTML
508 >