Debian Codegraph @

doc/driver-guide/drivercaps.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 Capabilities</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 Infrastructure"
14 HREF="driverinfrastructure.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Driver Infrastructure"
17 HREF="driverinfrastructure.html"><LINK
18 REL="NEXT"
19 TITLE="Database directories"
20 HREF="databasedirectories.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="driverinfrastructure.html"
49 ACCESSKEY="P"
50 >Prev</A
51 ></TD
52 ><TD
53 WIDTH="80%"
54 ALIGN="center"
55 VALIGN="bottom"
56 >Chapter 2. Driver Infrastructure</TD
57 ><TD
58 WIDTH="10%"
59 ALIGN="right"
60 VALIGN="bottom"
61 ><A
62 HREF="databasedirectories.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="DRIVERCAPS"
77 >2.1. Driver Capabilities</A
78 ></H1
79 ><P
80 >Driver capabilities are essentially an array of key/value pairs which the drivers set when they're loaded. Both the libdbi framework and programs linked against libdbi can query these capabilities and adjust their behaviour accordingly.</P
81 ><DIV
82 CLASS="SECTION"
83 ><H2
84 CLASS="SECTION"
85 ><A
86 NAME="SETTINGDRIVERCAPS"
87 >2.1.1. Setting driver capabilities</A
88 ></H2
89 ><P
90 >The perfect place to set driver capabilities is in the <A
91 HREF="driverfuncs-infrastructure.html#DBD-INITIALIZE"
92 >dbd_initialize</A
93 > function which is called right after the driver is loaded by libdbi. To set capabilities, call the _dbd_register_driver_cap function for each of them:</P
94 ><DIV
95 CLASS="FUNCSYNOPSIS"
96 ><P
97 ></P
98 ><A
99 NAME="AEN73"
100 ></A
101 ><P
102 ><CODE
103 ><CODE
104 CLASS="FUNCDEF"
105 >void <B
106 CLASS="FSFUNC"
107 >_dbd_register_driver_cap</B
108 ></CODE
109 >(dbi_driver_t *<VAR
110 CLASS="PDPARAM"
111 >driver</VAR
112 >, const char *<VAR
113 CLASS="PDPARAM"
114 >capname</VAR
115 >, int <VAR
116 CLASS="PDPARAM"
117 >value</VAR
118 >);</CODE
119 ></P
120 ><P
121 ></P
122 ></DIV
123 ><P
124 ></P
125 ><DIV
126 CLASS="VARIABLELIST"
127 ><DL
128 ><DT
129 >Arguments</DT
130 ><DD
131 ><P
132 ><TT
133 CLASS="LITERAL"
134 >driver</TT
135 >: the driver as passed to <A
136 HREF="driverfuncs-infrastructure.html#DBD-INITIALIZE"
137 >dbd_initialize</A
138 >.</P
139 ><P
140 ><TT
141 CLASS="LITERAL"
142 >capname</TT
143 >: A string containing the name of the capability (i.e. the key).</P
144 ><P
145 ><TT
146 CLASS="LITERAL"
147 >value</TT
148 >: The value of the capability.</P
149 ></DD
150 ></DL
151 ></DIV
152 ></DIV
153 ><DIV
154 CLASS="SECTION"
155 ><H2
156 CLASS="SECTION"
157 ><A
158 NAME="REQUIREDDRIVERCAPS"
159 >2.1.2. Required driver capabilities</A
160 ></H2
161 ><P
162 >libdbi currently queries only one driver capability.</P
163 ><P
164 ></P
165 ><DIV
166 CLASS="VARIABLELIST"
167 ><DL
168 ><DT
169 >safe_dlclose</DT
170 ><DD
171 ><P
172 >A nonzero value indicates that the driver can safely be unloaded from memory by calling dlclose(). A value of 0 (zero) indicates that the driver should not be unloaded when libdbi is shut down. Drivers must not be unloaded if they, or any library they are linked against, install exit handlers via atexit() as this would leave dangling pointers, causing segfaults on some platforms.</P
173 ></DD
174 ></DL
175 ></DIV
176 ></DIV
177 ><DIV
178 CLASS="SECTION"
179 ><H2
180 CLASS="SECTION"
181 ><A
182 NAME="RECOMMENDEDDRIVERCAPS"
183 >2.1.3. Recommended driver capabilities</A
184 ></H2
185 ><P
186 >Two driver capabilities may be of interest to programs using libdbi and should therefore be published by drivers:</P
187 ><P
188 ></P
189 ><DIV
190 CLASS="VARIABLELIST"
191 ><DL
192 ><DT
193 >transaction_support</DT
194 ><DD
195 ><P
196 >A nonzero value indicates that the database engine supports transactions. Therefore functions to start, commit, or roll back transactions may be safely used.</P
197 ></DD
198 ><DT
199 >savepoint_support</DT
200 ><DD
201 ><P
202 >A nonzero value indicates that the database engine supports savepoints within transactions. Functions to set, release, and roll back to savepoints may be safely used.</P
203 ></DD
204 ></DL
205 ></DIV
206 ></DIV
207 ></DIV
208 ><DIV
209 CLASS="NAVFOOTER"
210 ><HR
211 ALIGN="LEFT"
212 WIDTH="100%"><TABLE
213 SUMMARY="Footer navigation table"
214 WIDTH="100%"
215 BORDER="0"
216 CELLPADDING="0"
217 CELLSPACING="0"
218 ><TR
219 ><TD
220 WIDTH="33%"
221 ALIGN="left"
222 VALIGN="top"
223 ><A
224 HREF="driverinfrastructure.html"
225 ACCESSKEY="P"
226 >Prev</A
227 ></TD
228 ><TD
229 WIDTH="34%"
230 ALIGN="center"
231 VALIGN="top"
232 ><A
233 HREF="index.html"
234 ACCESSKEY="H"
235 >Home</A
236 ></TD
237 ><TD
238 WIDTH="33%"
239 ALIGN="right"
240 VALIGN="top"
241 ><A
242 HREF="databasedirectories.html"
243 ACCESSKEY="N"
244 >Next</A
245 ></TD
246 ></TR
247 ><TR
248 ><TD
249 WIDTH="33%"
250 ALIGN="left"
251 VALIGN="top"
252 >Driver Infrastructure</TD
253 ><TD
254 WIDTH="34%"
255 ALIGN="center"
256 VALIGN="top"
257 ><A
258 HREF="driverinfrastructure.html"
259 ACCESSKEY="U"
260 >Up</A
261 ></TD
262 ><TD
263 WIDTH="33%"
264 ALIGN="right"
265 VALIGN="top"
266 >Database directories</TD
267 ></TR
268 ></TABLE
269 ></DIV
270 ></BODY
271 ></HTML
272 >