Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # $Id: DBD.pm,v 10.9 2001/05/29 23:25:55 timbo Exp $ |
2 | # | |
3 | # Copyright (c) 1997-2000 Jonathan Leffler, Jochen Wiedmann and Tim Bunce | |
4 | # | |
5 | # You may distribute under the terms of either the GNU General Public | |
6 | # License or the Artistic License, as specified in the Perl README file. | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | DBI::DBD - DBD Driver Writer's Guide | |
11 | ||
12 | =head1 SYNOPSIS | |
13 | ||
14 | perldoc DBI::DBD | |
15 | ||
16 | =head1 VERSION and VOLATILITY | |
17 | ||
18 | $Revision: 10.9 $ | |
19 | $Date: 2001/05/29 23:25:55 $ | |
20 | ||
21 | This document is a minimal draft which is in need of further work. | |
22 | ||
23 | The changes will occur both because the DBI specification is changing | |
24 | and hence the requirements on DBD drivers change, and because feedback | |
25 | from people reading this document will suggest improvements to it. | |
26 | ||
27 | Please read the DBI documentation first and fully, including the DBI FAQ. | |
28 | The reread the DBI specification again as you're reading this. It'll help. | |
29 | ||
30 | This document is a patchwork of contributions from various authors. | |
31 | More contributions (preferably as patches) are very welcome. | |
32 | ||
33 | =head1 DESCRIPTION | |
34 | ||
35 | This document is primarily intended to help people writing new | |
36 | database drivers for the Perl Database Interface (Perl DBI). | |
37 | It may also help others interested in discovering why the internals of | |
38 | a DBD driver are written the way they are. | |
39 | ||
40 | This is a guide. Few (if any) of the statements in it are completely | |
41 | authoritative under all possible circumstances. This means you will | |
42 | need to use judgement in applying the guidelines in this document. | |
43 | If in I<any> doubt at all, please do contact the dbi-dev mailing list | |
44 | (details given below) where Tim Bunce and other driver authors can help. | |
45 | ||
46 | The primary web-site for locating DBI software and information is | |
47 | ||
48 | http://www.symbolstone.org/technology/perl/DBI | |
49 | ||
50 | There are 2 main and one auxilliary mailing lists for people working | |
51 | with DBI. The primary lists are dbi-users@isc.org for general users | |
52 | of DBI and DBD drivers, and dbi-dev@isc.org mainly for DBD driver | |
53 | writers (don't join the dbi-dev list unless you have a good reason). | |
54 | The auxilliary list is dbi-announce@isc.org for announcing new | |
55 | releases of DBI or DBD drivers. | |
56 | ||
57 | You can join these lists by accessing the web-site | |
58 | L<http://www.isc.org/dbi-lists.html>. | |
59 | The lists are closed so you cannot send email to any of the lists | |
60 | unless you join the list first. | |
61 | ||
62 | You should also consider monitoring the comp.lang.perl.* newsgroups. | |
63 | ||
64 | =head1 BOOK | |
65 | ||
66 | The definitive book on Perl DBI is 'Programming the Perl DBI: Database | |
67 | programming with Perl' by Alligator Descartes and Tim Bunce, published | |
68 | by O'Reilly Associates, February 2000, ISBN 1-56592-699-4. Buy it now | |
69 | if you have not already done so. | |
70 | ||
71 | =head1 REGISTERING A NEW DRIVER | |
72 | ||
73 | Before writing a new driver, it is in your interests to find out | |
74 | whether there already is a driver for your database. If there is such | |
75 | a driver, it would be much easier to make use of it than to write your | |
76 | own! | |
77 | ||
78 | =head2 Locating drivers | |
79 | ||
80 | The primary web-site for locating Perl software is | |
81 | L<http://www.perl.com/CPAN>. | |
82 | You should look under the various modules listings for the software | |
83 | you are after. | |
84 | Two of the main pages you should look at are: | |
85 | ||
86 | http://www.perl.org/CPAN/modules/by-category/07_Database_Interfaces/DBI | |
87 | ||
88 | http://www.perl.org/CPAN/modules/by-category/07_Database_Interfaces/DBD | |
89 | ||
90 | See the DBI docs for information on DBI web sites and mailing lists. | |
91 | ||
92 | =head2 Registering a new driver | |
93 | ||
94 | Before going through any official registration process, you will need | |
95 | to establish that there is no driver already in the works. | |
96 | You'll do that by asking the DBI mailing lists whether there is such a | |
97 | driver available, or whether anybody is working on one. | |
98 | ||
99 | ||
100 | =head1 CREATING A NEW DRIVER USING PURE PERL | |
101 | ||
102 | Writing a pure Perl driver is surprisingly simple. However, there are | |
103 | some problems one should be aware of. The best option is of course | |
104 | picking up an existing driver and carefully modifying one method | |
105 | after the other. | |
106 | ||
107 | As an example we take a look at the I<DBD::File> driver, a driver for | |
108 | accessing plain files as tables, which is part of the I<DBD::CSV> | |
109 | package. In what follows I assume the name C<Driver> for your new | |
110 | package: The least thing we have to implement are the files | |
111 | C<Makefile.PL> and C<Driver.pm>. | |
112 | ||
113 | ||
114 | =head2 Makefile.PL | |
115 | ||
116 | You typically start with writing C<Makefile.PL>, a Makefile generator. | |
117 | The contents of this file are described in detail in the MakeMaker | |
118 | man pages, it's definitely a good idea if you start reading them. | |
119 | At least you should know about the variables I<CONFIGURE>, I<DEFINED>, | |
120 | I<DIR>, I<EXE_FILES>, I<INC>, I<LIBS>, I<LINKTYPE>, I<NAME>, I<OPTIMIZE>, | |
121 | I<PL_FILES>, I<VERSION>, I<VERSION_FROM>, I<clean>, I<depend>, I<realclean> | |
122 | from the C<ExtUtils::MakeMaker> man page: These are used in almost any | |
123 | Makefile.PL. Additionally read the section on I<Overriding MakeMaker Methods> | |
124 | and the descriptions of the I<distcheck>, I<disttest> and I<dist> targets: | |
125 | They will definitely be useful for you. | |
126 | ||
127 | Of special importance for DBI drivers is the I<postamble> method from | |
128 | the C<ExtUtils::MM_Unix> man page. And for Emacs users I recommend | |
129 | the I<libscan> method. | |
130 | ||
131 | Now an example, I use the word C<Driver> wherever you should insert | |
132 | your drivers name: | |
133 | ||
134 | # -*- perl -*- | |
135 | ||
136 | use DBI 1.03; | |
137 | use DBI::DBD; | |
138 | use ExtUtils::MakeMaker; | |
139 | ||
140 | ExtUtils::MakeMaker::WriteMakefile( | |
141 | 'NAME' => 'DBD::Driver', | |
142 | 'VERSION_FROM' => 'Driver.pm', | |
143 | 'INC' => $DBI_INC_DIR, | |
144 | 'dist' => { 'SUFFIX' => '.gz', | |
145 | 'COMPRESS' => 'gzip -9f' }, | |
146 | 'realclean' => '*.xsi' | |
147 | ); | |
148 | ||
149 | package MY; | |
150 | sub postamble { dbd_postamble(@_); } | |
151 | sub libscan { | |
152 | my($self, $path) = @_; | |
153 | ($path =~ /\~$/) ? undef : $path; | |
154 | } | |
155 | ||
156 | See also L<ExtUtils::MakeMaker(3)>. L<ExtUtils::MM_Unix(3)>. | |
157 | ||
158 | ||
159 | =head2 README file | |
160 | ||
161 | The README file should describe what the driver is for, the | |
162 | pre-requisites for the build process, the actual build process, and how | |
163 | to report errors. Users will find ways of breaking the driver build and | |
164 | test process which you would never even dreamed to be possible in your | |
165 | nightmares. :-) Therefore, you need to write this document defensively | |
166 | and precisely. Also, it is in your interests to ensure that your tests | |
167 | work as widely as possible. As always, use the README from one of the | |
168 | established drivers as a basis for your own. | |
169 | ||
170 | ||
171 | =head2 MANIFEST | |
172 | ||
173 | The MANIFEST will be used by the Makefile'd dist target to build the | |
174 | distribution tar file that is uploaded to CPAN. It should list every | |
175 | file that you want to include in your distribution, one per line. | |
176 | ||
177 | ||
178 | =head2 lib/Bundle/DBD/Driver.pm | |
179 | ||
180 | The CPAN module provides an extremely powerful bundle mechanism that | |
181 | allows you to specify pre-requisites for your driver. | |
182 | The primary pre-requisite is Bundle::DBI; you may want or need to add | |
183 | some more. | |
184 | With the bundle set up correctly, the user can type: | |
185 | ||
186 | perl -MCPAN -e 'install Bundle::DBD::Driver' | |
187 | ||
188 | and Perl will download, compile, test and install all the Perl modules | |
189 | needed to build your driver. | |
190 | ||
191 | A suitable skeleton for this file is shown below. | |
192 | The prerequisite modules are listed in the CONTENTS section, with the | |
193 | official name of the module followed by a dash and an informal name or | |
194 | description. | |
195 | Listing Bundle::DBI as the main pre-requisite simplifies life. | |
196 | Don't forget to list your driver. | |
197 | Note that unless the DBMS is itself a Perl module, you cannot list it | |
198 | as a pre-requisite in this file. | |
199 | You are strongly advised to keep the version of the bundle in sync | |
200 | with the version of your driver. | |
201 | You might want to add configuration management, copyright, and | |
202 | licencing information at the top. | |
203 | ||
204 | ||
205 | package Bundle::DBD::Driver; | |
206 | ||
207 | $VERSION = '0.01'; | |
208 | ||
209 | 1; | |
210 | ||
211 | __END__ | |
212 | ||
213 | =head1 NAME | |
214 | ||
215 | Bundle::DBD::Driver - A bundle to install all DBD::Driver related modules | |
216 | ||
217 | =head1 SYNOPSIS | |
218 | ||
219 | C<perl -MCPAN -e 'install Bundle::DBD::Driver'> | |
220 | ||
221 | =head1 CONTENTS | |
222 | ||
223 | Bundle::DBI - Bundle for DBI by TIMB (Tim Bunce) | |
224 | ||
225 | DBD::Driver - DBD::Driver by YOU (Your Name) | |
226 | ||
227 | =head1 DESCRIPTION | |
228 | ||
229 | This bundle includes all the modules used by the Perl Database | |
230 | Interface (DBI) driver for Driver (DBD::Driver), assuming the | |
231 | use of DBI version 1.13 or later, created by Tim Bunce. | |
232 | ||
233 | If you've not previously used the CPAN module to install any | |
234 | bundles, you will be interrogated during its setup phase. | |
235 | But when you've done it once, it remembers what you told it. | |
236 | You could start by running: | |
237 | ||
238 | C<perl -MCPAN -e 'install Bundle::CPAN'> | |
239 | ||
240 | =head1 SEE ALSO | |
241 | ||
242 | Bundle::DBI | |
243 | ||
244 | =head1 AUTHOR | |
245 | ||
246 | Your Name E<lt>F<you@yourdomain.com>E<gt> | |
247 | ||
248 | =head1 THANKS | |
249 | ||
250 | This bundle was created by ripping off Bundle::libnet created by | |
251 | Graham Barr E<lt>F<gbarr@ti.com>E<gt>, and radically simplified | |
252 | with some information from Jochen Wiedmann E<lt>F<joe@ispsoft.de>E<gt>. | |
253 | The template was then included in the DBI::DBD documentation by | |
254 | Jonathan Leffler E<lt>F<jleffler@informix.com>E<gt>. | |
255 | ||
256 | =cut | |
257 | ||
258 | ||
259 | =head2 Driver.pm | |
260 | ||
261 | The Driver.pm file defines the Perl module DBD::Driver for your driver. | |
262 | It will define a package DBD::Driver along with some version information, | |
263 | some variable definitions, and a function driver() which will have a more | |
264 | or less standard structure. | |
265 | ||
266 | It will also define a package DBD::Driver::dr (with methods connect(), | |
267 | data_sources() and disconnect_all()), and a package DBD::Driver::db | |
268 | (which will define a function prepare() etc), and a package DBD::Driver::st | |
269 | with methods execute(), fetch() and the like. | |
270 | ||
271 | The Driver.pm file will also contain the documentation specific to | |
272 | DBD::Driver in the format used by perldoc. | |
273 | ||
274 | Now let's take a closer look at an excerpt of File.pm as an example. | |
275 | We ignore things that are common to any module (even non-DBI(D) modules) | |
276 | or really specific for the DBD::File package. | |
277 | ||
278 | =over 2 | |
279 | ||
280 | =item The header | |
281 | ||
282 | package DBD::File; | |
283 | ||
284 | use strict; | |
285 | use vars qw($err $errstr $state $drh); | |
286 | ||
287 | $err = 0; # holds error code for DBI::err | |
288 | $errstr = ""; # holds error string for DBI::errstr | |
289 | $sqlstate = ""; # holds SQL state for DBI::state | |
290 | ||
291 | These variables are used for storing error states and messages. | |
292 | However, it is crucial to understand that you must not modify | |
293 | them directly; instead use the I<event> method, see below. | |
294 | ||
295 | $drh = undef; # holds driver handle once initialized | |
296 | ||
297 | This is where the driver handle will be stored, once created. Note, | |
298 | that you may assume, there's only one handle for your driver. | |
299 | ||
300 | =item The driver constructor | |
301 | ||
302 | sub driver { | |
303 | return $drh if $drh; # already created - return same one | |
304 | my($class, $attr) = @_; | |
305 | ||
306 | $class .= "::dr"; | |
307 | ||
308 | # not a 'my' since we use it above to prevent multiple drivers | |
309 | $drh = DBI::_new_drh($class, { | |
310 | 'Name' => 'File', | |
311 | 'Version' => $VERSION, | |
312 | 'Err' => \$DBD::File::err, | |
313 | 'Errstr' => \$DBD::File::errstr, | |
314 | 'State' => \$DBD::File::state, | |
315 | 'Attribution' => 'DBD::File by Jochen Wiedmann', | |
316 | }); | |
317 | ||
318 | return $drh; | |
319 | } | |
320 | ||
321 | The I<driver> method is the driver handle constructor. It's a | |
322 | reasonable example of how DBI implements its handles. There are three | |
323 | kinds: B<driver handles> (typically stored in C<$drh>, from now on | |
324 | called C<drh>), B<database handles> (from now on called C<dbh> or | |
325 | C<$dbh>) and B<statement handles>, (from now on called C<sth> or | |
326 | C<$sth>). | |
327 | ||
328 | The prototype of DBI::_new_drh is | |
329 | ||
330 | $drh = DBI::_new_drh($class, $attr1, $attr2); | |
331 | ||
332 | with the following arguments: | |
333 | ||
334 | =over 4 | |
335 | ||
336 | =item I<$class> | |
337 | ||
338 | is typically your drivers class, e.g., "DBD::File::dr", passed as first | |
339 | argument to the I<driver> method. | |
340 | ||
341 | =item I<$attr1> | |
342 | ||
343 | is a hash ref to attributes like I<Name>, I<Version>, I<Err>, I<Errstr> | |
344 | I<State> and I<Attributrion>. These are processed and used by DBI, you | |
345 | better not make any assumptions on them nor should you add private | |
346 | attributes here. | |
347 | ||
348 | =item I<$attr2> | |
349 | ||
350 | This is another (optional) hash ref with your private attributes. DBI | |
351 | will leave them alone. | |
352 | ||
353 | =back | |
354 | ||
355 | The I<DBI::new_drh> method and the I<driver> method | |
356 | both return C<undef> for failure (in which case you must look at | |
357 | $DBI::err and $DBI::errstr, because you have no driver handle). | |
358 | ||
359 | ||
360 | =item The database handle constructor | |
361 | ||
362 | The next lines of code look as follows: | |
363 | ||
364 | package DBD::Driver::dr; # ====== DRIVER ====== | |
365 | ||
366 | $DBD::Driver::dr::imp_data_size = 0; | |
367 | ||
368 | Note that no @ISA is needed here, or for the other DBD::Driver::* | |
369 | classes, because the DBI takes care of that for you when the driver is | |
370 | loaded. | |
371 | ||
372 | The database handle constructor is a driver method, thus we have | |
373 | to change the namespace. | |
374 | ||
375 | sub connect { | |
376 | my($drh, $dbname, $user, $auth, $attr)= @_; | |
377 | ||
378 | # Some database specific verifications, default settings | |
379 | # and the like following here. This should only include | |
380 | # syntax checks or similar stuff where it's legal to | |
381 | # 'die' in case of errors. | |
382 | ||
383 | # create a 'blank' dbh (call superclass constructor) | |
384 | my $dbh = DBI::_new_dbh($drh, { | |
385 | 'Name' => $dbname, | |
386 | 'USER' => $user, | |
387 | 'CURRENT_USER' => $user, | |
388 | }); | |
389 | ||
390 | # Process attributes from the DSN; we assume ODBC syntax | |
391 | # here, that is, the DSN looks like var1=val1;...;varN=valN | |
392 | ||
393 | my $var; | |
394 | foreach $var (split(/;/, $dbname)) { | |
395 | if ($var =~ /(.*?)=(,*)/) { | |
396 | # Not !!! $dbh->{$var} = $val; | |
397 | $dbh->STORE($var, $val); | |
398 | } | |
399 | } | |
400 | $dbh; | |
401 | } | |
402 | ||
403 | This is mostly the same as in the I<driver handle constructor> above. | |
404 | The arguments are described in the DBI man page. See L<DBI(3)>. | |
405 | The constructor is called, returning a database handle. The constructors | |
406 | prototype is | |
407 | ||
408 | $dbh = DBI::_new_dbh($drh, $attr1, $attr2); | |
409 | ||
410 | with the same arguments as in the I<driver handle constructor>, the | |
411 | exception being C<$class> replaced by C<$drh>. | |
412 | ||
413 | Note the use of the I<STORE> method for setting the dbh attributes. | |
414 | That's because within the driver code, the handle object you have is | |
415 | the 'inner' handle of a tied hash, not the outer handle that the | |
416 | users of your driver have. | |
417 | ||
418 | Because you have the inner handle, tie magic doesn't get invoked | |
419 | when you get or set values in the hash. This is often very handy for | |
420 | speed when you want to get or set simple non-special driver-specific | |
421 | attributes. | |
422 | ||
423 | However, some attribute values, such as those handled by the DBI | |
424 | like PrintError, don't actually exist in the hash and must be | |
425 | read via $h->FETCH($attrib) and set via $h->STORE($attrib, $value). | |
426 | If in any doubt, use these methods. | |
427 | ||
428 | ||
429 | =item Error handling | |
430 | ||
431 | It is quite likely that something fails in the connect method. With | |
432 | DBD::File for example, you might catch an error when setting the | |
433 | current directory to something not existant by using the f_dir | |
434 | attribute. | |
435 | ||
436 | To report an error, you use the C<DBI::set_err> function/method: | |
437 | ||
438 | $h->DBI::set_err($errcode, $errmsg); | |
439 | ||
440 | This will ensure that the error is recorded correctly and that | |
441 | RaiseError and PrintError etc are handled correctly. Typically you'll | |
442 | always use the method instance, aka your method's first argument. | |
443 | ||
444 | As set_err always returns undef your error handling code can | |
445 | usually be simplified to something like this: | |
446 | ||
447 | return $h->DBI::set_err($errcode, $errmsg) if ...; | |
448 | ||
449 | ||
450 | =item Other driver handle methods | |
451 | ||
452 | may follow here. In particular you should consider a I<data_sources> | |
453 | method, and a (possibly empty) I<disconnect_all> method. See L<DBI(3)>. | |
454 | ||
455 | ||
456 | =item The statement handle constructor | |
457 | ||
458 | There's nothing much new in the statement handle constructor. | |
459 | ||
460 | package DBD::Driver::db; # ====== DATABASE ====== | |
461 | ||
462 | $DBD::Driver::db::imp_data_size = 0; | |
463 | ||
464 | sub prepare { | |
465 | my($dbh, $statement, @attribs)= @_; | |
466 | ||
467 | # create a 'blank' sth | |
468 | my $sth = DBI::_new_sth($dbh, { | |
469 | 'Statement' => $statement, | |
470 | }); | |
471 | ||
472 | # Setup module specific data | |
473 | $sth->STORE('driver_params', []); | |
474 | $sth->STORE('NUM_OF_PARAMS', ($statement =~ tr/?//)); | |
475 | ||
476 | $sth; | |
477 | } | |
478 | ||
479 | This is still the same: Check the arguments and call the super class | |
480 | constructor I<DBI::_new_sth>. Note the prefix I<driver_> in the | |
481 | attribute names: It is required that your private attributes | |
482 | are lowercased and use such a prefix. See the DBI manual. | |
483 | ||
484 | Note that we parse the statement here in order to setup the attribute | |
485 | I<NUM_OF_PARAMS>. We could as well do this in the I<execute> method | |
486 | below, the DBI specs explicitly allow to defer this. However, one | |
487 | could not call I<bind_param> in that case. | |
488 | ||
489 | ||
490 | =item Transaction handling | |
491 | ||
492 | Pure Perl drivers will rarely support transactions. Thus you're I<commit> | |
493 | and I<rollback> methods will typically be quite simple: | |
494 | ||
495 | sub commit { | |
496 | my($dbh) = @_; | |
497 | if ($dbh->FETCH('Warn')) { | |
498 | warn("Commit ineffective while AutoCommit is on"); | |
499 | } | |
500 | 1; | |
501 | } | |
502 | ||
503 | sub rollback { | |
504 | my($dbh) = @_; | |
505 | if ($dbh->FETCH('Warn')) { | |
506 | warn("Rollback ineffective while AutoCommit is on"); | |
507 | } | |
508 | 0; | |
509 | } | |
510 | ||
511 | ||
512 | =item The STORE and FETCH methods | |
513 | ||
514 | These methods (that we have already used, see above) are called for | |
515 | you, whenever the user does a | |
516 | ||
517 | $dbh->{$attr} = $val; | |
518 | ||
519 | or, respectively, | |
520 | ||
521 | $val = $dbh->{$attr}; | |
522 | ||
523 | See L<perltie(1)> for details on tied hash refs to understand why these | |
524 | methods are required. | |
525 | ||
526 | The DBI will handle most attributes for you, in particular attributes | |
527 | like I<RaiseError> or I<PrintError>. All you have to do handle your | |
528 | driver's private attributes and any attributes, like AutoCommit, that | |
529 | the DBI can't handle for you. A good example might look like this: | |
530 | ||
531 | sub STORE { | |
532 | my($dbh, $attr, $val) = @_; | |
533 | if ($attr eq 'AutoCommit') { | |
534 | # AutoCommit is currently the only standard attribute we have | |
535 | # to consider. | |
536 | if (!$val) { die "Can't disable AutoCommit"; } | |
537 | return 1; | |
538 | } | |
539 | if ($attr =~ /^driver_/) { | |
540 | # Handle only our private attributes here | |
541 | # Note that we could trigger arbitrary actions. | |
542 | # Ideally we should catch unknown attributes. | |
543 | $dbh->{$attr} = $val; # Yes, we are allowed to do this, | |
544 | return 1; # but only for our private attributes | |
545 | } | |
546 | # Else pass up to DBI to handle for us | |
547 | $dbh->SUPER::STORE($attr, $val); | |
548 | } | |
549 | ||
550 | sub FETCH { | |
551 | my($dbh, $attr) = @_; | |
552 | if ($attr eq 'AutoCommit') { return 1; } | |
553 | if ($attr =~ /^driver_/) { | |
554 | # Handle only our private attributes here | |
555 | # Note that we could trigger arbitrary actions. | |
556 | return $dbh->{$attr}; # Yes, we are allowed to do this, | |
557 | # but only for our private attributes | |
558 | } | |
559 | # Else pass up to DBI to handle | |
560 | $dbh->SUPER::FETCH($attr); | |
561 | } | |
562 | ||
563 | The DBI will actually store and fetch driver-specific attributes (with all | |
564 | lowercase names) without warning or error, so there's actually no need to | |
565 | implement driver-specific any code in your FETCH and STORE methods unless | |
566 | you need extra logic/checks, beyond getting or setting the value. | |
567 | ||
568 | ||
569 | =item Other database handle methods | |
570 | ||
571 | may follow here. In particular you should consider a (possibly empty) | |
572 | I<disconnect> method, a I<quote> method (if DBI's default isn't good | |
573 | for you). | |
574 | ||
575 | ||
576 | =item The execute method | |
577 | ||
578 | This is perhaps the most difficult method because we have to consider | |
579 | parameter bindings here. We present a simplified implementation by | |
580 | using the I<driver_params> attribute from above: | |
581 | ||
582 | package DBD::Driver::st; | |
583 | ||
584 | $DBD::Driver::st::imp_data_size = 0; | |
585 | ||
586 | sub bind_param { | |
587 | my($sth, $pNum, $val, $attr) = @_; | |
588 | my $type = (ref $attr) ? $attr->{TYPE} : $attr; | |
589 | if ($type) { | |
590 | my $dbh = $sth->{Database}; | |
591 | $val = $dbh->quote($sth, $type); | |
592 | } | |
593 | my $params = $sth->FETCH('driver_params'); | |
594 | $params->[$pNum-1] = $val; | |
595 | 1; | |
596 | } | |
597 | ||
598 | sub execute { | |
599 | my($sth, @bind_values) = @_; | |
600 | my $params = (@bind_values) ? | |
601 | \@bind_values : $sth->FETCH('driver_params'); | |
602 | my $numParam = $sth->FETCH('NUM_OF_PARAMS'); | |
603 | if (@$params != $numParam) { ... } | |
604 | my $statement = $sth->{'Statement'}; | |
605 | for (my $i = 0; $i < $numParam; $i++) { | |
606 | $statement =~ s/?/$params->[$i]/e; | |
607 | } | |
608 | # Do anything ... we assume that an array ref of rows is | |
609 | # created and store it: | |
610 | $sth->{'driver_data'} = $data; | |
611 | $sth->{'driver_rows'} = @$data; # number of rows | |
612 | $sth->STORE('NUM_OF_FIELDS') = $numFields; | |
613 | @$data || '0E0'; | |
614 | } | |
615 | ||
616 | Things you should note here: We setup the NUM_OF_FIELDS attribute | |
617 | here, because this is essential for I<bind_columns> to work. And | |
618 | we use attribute I<$sth->{'Statement'}> which we have created | |
619 | within I<prepare>. The attribute I<$sth->{'Database'}>, which is | |
620 | nothing else than the I<dbh>, was automatically created by DBI. | |
621 | ||
622 | Finally note that we return the string '0E0' instead of the number | |
623 | 0, so that | |
624 | ||
625 | if (!$sth->execute()) { die $sth->errstr } | |
626 | ||
627 | works. | |
628 | ||
629 | ||
630 | =item Fetching data | |
631 | ||
632 | We need not implement the methods I<fetchrow_array>, I<fetchall_arrayref>, | |
633 | ... because these are already part of DBI. All we need is the method | |
634 | I<fetchrow_arrayref>: | |
635 | ||
636 | sub fetchrow_arrayref { | |
637 | my($sth) = @_; | |
638 | my $data = $sth->FETCH('driver_data'); | |
639 | my $row = shift @$data; | |
640 | if (!$row) { return undef; } | |
641 | if ($sth->FETCH('ChopBlanks')) { | |
642 | map { $_ =~ s/\s+$//; } @$row; | |
643 | } | |
644 | return $sth->_set_fbav($row); | |
645 | } | |
646 | *fetch = \&fetchrow_arrayref; # required alias for fetchrow_arrayref | |
647 | ||
648 | sub rows { my($sth) = @_; $sth->FETCH('driver_rows'); } | |
649 | ||
650 | Note the use of the method I<_set_fbav>: This is required so that | |
651 | I<bind_col> and I<bind_columns> work. | |
652 | ||
653 | Fixing the broken implementation for correct handling of quoted | |
654 | question marks is left as an exercise to the reader. :-) | |
655 | ||
656 | ||
657 | =item Statement attributes | |
658 | ||
659 | The main difference between dbh and sth attributes is, that you | |
660 | should implement a lot of attributes here that are required by | |
661 | the DBI: For example I<NAME>, I<NULLABLE>, I<TYPE>, ... | |
662 | ||
663 | Besides that the STORE and FETCH methods are mainly the same | |
664 | as above for dbh's. | |
665 | ||
666 | ||
667 | =item Other statement methods | |
668 | ||
669 | A trivial C<finish> method to discard the stored data and do | |
670 | $sth->SUPER::finish; | |
671 | ||
672 | A C<table_info> method to return details of available tables. | |
673 | ||
674 | A C<type_info_all> method to return details of supported types. | |
675 | ||
676 | And perhaps some other methods that are not part of the DBI specs, in | |
677 | particular make metadata available. Considering Tim's last articles do | |
678 | yourself a favour and follow the ODBC driver. | |
679 | ||
680 | ||
681 | =back | |
682 | ||
683 | ||
684 | =head2 Tests | |
685 | ||
686 | The test process should conform as closely as possibly to the Perl | |
687 | standard test harness. | |
688 | ||
689 | In particular, most of the tests should be run in the t sub-directory, | |
690 | and should simply produce an 'ok' when run under 'make test'. | |
691 | For details on how this is done, see the Camel book and the section in | |
692 | Chapter 7, "The Standard Perl Library" on L<Test::Harness>. | |
693 | ||
694 | The tests may need to adapt to the type of database which is being | |
695 | used for testing, and to the privileges of the user testing the | |
696 | driver. | |
697 | ||
698 | The DBD::Informix test code has to adapt in a number of places to the | |
699 | type of database to which it is connected as different Informix | |
700 | databases have different capabilities. | |
701 | ||
702 | [...More info TBS...] | |
703 | ||
704 | ||
705 | =head1 CREATING A NEW DRIVER USING C/XS | |
706 | ||
707 | Creating a new C/XS driver from scratch will always be a daunting task. | |
708 | You can and should greatly simplify your task by taking a good | |
709 | reference driver implementation and modifying that to match the | |
710 | database product for which you are writing a driver. | |
711 | ||
712 | The de facto reference driver has been the one for DBD::Oracle, written | |
713 | by Tim Bunce who is also the author of the DBI package. The DBD::Oracle | |
714 | module is a good example of a driver implemented around a C-level API. | |
715 | ||
716 | Nowadays it it seems better to base on DBD::ODBC, another driver | |
717 | maintained by Tim and Jeff Urlwin, because it offers a lot of metadata | |
718 | and seems to become the guideline for the future development. (Also as | |
719 | DBD::Oracle digs deeper into the Oracle 8 OCI interface it'll get even | |
720 | more hairly than it is now.) | |
721 | ||
722 | The DBD::Informix driver is a good reference for a driver implemented | |
723 | using 'embedded SQL'. DBD::Ingres may also be worth a look. | |
724 | ||
725 | [...More info TBS...] | |
726 | ||
727 | =head2 REQUIREMENTS ON A DRIVER | |
728 | ||
729 | T.B.S. | |
730 | ||
731 | =head2 CODE TO BE WRITTEN | |
732 | ||
733 | A minimal driver will typically contain 9 files plus some tests. | |
734 | Assuming that your driver is called DBD::Driver, these files are: | |
735 | ||
736 | =over 4 | |
737 | ||
738 | =item Driver.pm | |
739 | ||
740 | =item Driver.xs | |
741 | ||
742 | =item Driver.h | |
743 | ||
744 | =item dbdimp.h | |
745 | ||
746 | =item dbdimp.c | |
747 | ||
748 | =item Makefile.PL | |
749 | ||
750 | =item README | |
751 | ||
752 | =item MANIFEST | |
753 | ||
754 | =item lib/Bundle/DBD/Driver.pm | |
755 | ||
756 | =back | |
757 | ||
758 | ||
759 | =head2 Driver.pm | |
760 | ||
761 | The Driver.pm file is the same as for Pure Perl modules, see above. | |
762 | However, there are some subtile differences: | |
763 | ||
764 | =over 8 | |
765 | ||
766 | =item * | |
767 | ||
768 | The variables $DBD::File::dr|db|st::imp_data_size are not defined | |
769 | here, but in the XS code, because they declare the size of certain | |
770 | C structures. | |
771 | ||
772 | =item * | |
773 | ||
774 | Some methods are typically moved to the XS code, in particular | |
775 | I<prepare>, I<execute>, I<disconnect>, I<disconnect_all> and the STORE | |
776 | and FETCH methods. | |
777 | ||
778 | =item * | |
779 | ||
780 | Other methods are still part of C<Driver.pm>, but have callbacks in | |
781 | the XS code. | |
782 | ||
783 | =back | |
784 | ||
785 | ||
786 | Now let's take a closer look at an excerpt of Oracle.pm (around version | |
787 | 0.54, prior to Oracle 8 support) as an example. We ignore things that | |
788 | are already discussed for Pure Perl drivers or really Oracle specific. | |
789 | ||
790 | =over 2 | |
791 | ||
792 | =item The database handle constructor | |
793 | ||
794 | sub connect { | |
795 | my($drh, $dbname, $user, $auth)= @_; | |
796 | ||
797 | # Some database specific verifications, default settings | |
798 | # and the like following here. This should only include | |
799 | # syntax checks or similar stuff where it's legal to | |
800 | # 'die' in case of errors. | |
801 | ||
802 | # create a 'blank' dbh (call superclass constructor) | |
803 | my $dbh = DBI::_new_dbh($drh, { | |
804 | 'Name' => $dbname, | |
805 | 'USER' => $user, 'CURRENT_USER' => $user, | |
806 | }); | |
807 | ||
808 | # Call Oracle OCI orlon func in Oracle.xs file | |
809 | # and populate internal handle data. | |
810 | DBD::Oracle::db::_login($dbh, $dbname, $user, $auth) | |
811 | or return undef; | |
812 | ||
813 | $dbh; | |
814 | } | |
815 | ||
816 | This is mostly the same as in the Pure Perl case, the exception being | |
817 | the use of the private I<_login> callback: This will really connect to | |
818 | the database. It is implemented in Driver.xst (you should not implement | |
819 | it) and calls I<dbd_db_login> from I<dbdimp.c>. See below for details. | |
820 | ||
821 | Since the DBI::_new_xxh methods can't fail in normal situations, we | |
822 | don't both checking $dbh before calling _login. | |
823 | ||
824 | =item The statement handle constructor | |
825 | ||
826 | There's nothing much new in the statement handle constructor. Like | |
827 | the I<connect> method it now has a C callback: | |
828 | ||
829 | package DBD::Oracle::db; # ====== DATABASE ====== | |
830 | use strict; | |
831 | ||
832 | sub prepare { | |
833 | my($dbh, $statement, @attribs)= @_; | |
834 | ||
835 | # create a 'blank' sth | |
836 | my $sth = DBI::_new_sth($dbh, { | |
837 | 'Statement' => $statement, | |
838 | }); | |
839 | ||
840 | # Call Oracle OCI oparse func in Oracle.xs file. | |
841 | # (This will actually also call oopen for you.) | |
842 | # and populate internal handle data. | |
843 | ||
844 | DBD::Oracle::st::_prepare($sth, $statement, @attribs) | |
845 | or return undef; | |
846 | ||
847 | $sth; | |
848 | } | |
849 | ||
850 | =back | |
851 | ||
852 | ||
853 | =head2 Driver.xs | |
854 | ||
855 | Driver.xs should look something like this: | |
856 | ||
857 | #include "Driver.h" | |
858 | ||
859 | DBISTATE_DECLARE; | |
860 | ||
861 | INCLUDE: Driver.xsi | |
862 | ||
863 | MODULE = DBD::Driver PACKAGE = DBD::Driver::db | |
864 | ||
865 | /* Non-standard dbh XS methods following here, if any. */ | |
866 | /* Currently this includes things like _list_tables from */ | |
867 | /* DBD::mSQL and DBD::mysql. */ | |
868 | ||
869 | MODULE = DBD::Driver PACKAGE = DBD::Driver::st | |
870 | ||
871 | /* Non-standard sth XS methods following here, if any. */ | |
872 | /* In particular this includes things like _list_fields from */ | |
873 | /* DBD::mSQL and DBD::mysql for accessing metadata. */ | |
874 | ||
875 | Note especially the include of I<Driver.xsi> here: DBI inserts stub | |
876 | functions for almost all private methods here which will typically | |
877 | do much work for you. Wherever you really have to implement something, | |
878 | it will call a private function in I<dbdimp.c>: This is what you have | |
879 | to implement. | |
880 | ||
881 | ||
882 | =head2 Driver.h | |
883 | ||
884 | Driver.h should look like this: | |
885 | ||
886 | #define NEED_DBIXS_VERSION 93 | |
887 | ||
888 | #include <DBIXS.h> /* installed by the DBI module */ | |
889 | ||
890 | #include "dbdimp.h" | |
891 | ||
892 | #include <dbd_xsh.h> /* installed by the DBI module */ | |
893 | ||
894 | ||
895 | =head2 Implementation header dbdimp.h | |
896 | ||
897 | This header file has two jobs: | |
898 | ||
899 | First it defines data structures for your private part of the handles. | |
900 | ||
901 | Second it defines macros that rename the generic names like | |
902 | I<dbd_db_login> to database specific names like I<ora_db_login>. This | |
903 | avoids name clashes and enables use of different drivers when you work | |
904 | with a statically linked perl. | |
905 | ||
906 | It also will have the important task of disabling XS methods that you | |
907 | don't want to implement. | |
908 | ||
909 | Finally, the macros will also be used to select alternate | |
910 | implementations of some functions. For example, the currently defined | |
911 | C<dbd_db_login> function is not passed the attribute hash. In future, | |
912 | if a dbd_db_login6 macro is defined (for a function with 6 arguments), | |
913 | it will be used instead with the attribute hash passed at the sixth | |
914 | argument. | |
915 | ||
916 | People liked to just pick Oracle's dbdimp.c and use the same names, | |
917 | structures and types. I strongly recommend against that: At first | |
918 | glance this saves time, but your implementation will be less readable. | |
919 | It was just a hell when I had to separate DBI specific parts, Oracle | |
920 | specific parts, mSQL specific parts and mysql specific parts in | |
921 | DBD::mysql's I<dbdimp.h> and I<dbdimp.c>. (DBD::mysql was a port of | |
922 | DBD::mSQL which was based on DBD::Oracle.) This part of the driver | |
923 | is I<your exclusive part>. Rewrite it from scratch, so it will be | |
924 | clean and short, in other words: A better piece of code. (Of course | |
925 | have an eye at other people's work.) | |
926 | ||
927 | struct imp_drh_st { | |
928 | dbih_drc_t com; /* MUST be first element in structure */ | |
929 | ||
930 | /* Insert your driver handle attributes here */ | |
931 | }; | |
932 | ||
933 | struct imp_dbh_st { | |
934 | dbih_dbc_t com; /* MUST be first element in structure */ | |
935 | ||
936 | /* Insert your database handle attributes here */ | |
937 | }; | |
938 | ||
939 | struct imp_sth_st { | |
940 | dbih_stc_t com; /* MUST be first element in structure */ | |
941 | ||
942 | /* Insert your statement handle attributes here */ | |
943 | }; | |
944 | ||
945 | /* Rename functions for avoiding name clashes; prototypes are */ | |
946 | /* in dbd_xst.h */ | |
947 | #define dbd_init ora_init | |
948 | #define dbd_db_login ora_db_login | |
949 | #define dbd_db_do ora_db_do | |
950 | ... many more here ... | |
951 | ||
952 | This structures implement your private part of the handles. You I<have> | |
953 | to use the name I<imp_dbh_dr|db|st> and the first field I<must> be of | |
954 | type I<dbih_drc|dbc|stc_t>. You should never access this fields directly, | |
955 | except of using the I<DBIc_xxx> macros below. | |
956 | ||
957 | ||
958 | =head2 Implementation source dbdimp.c | |
959 | ||
960 | This is the main implementation file. I will drop a short note on any | |
961 | function here that's used in the I<Driver.xsi> template and thus B<has> | |
962 | to be implemented. Of course you can add private or better static | |
963 | functions here. | |
964 | ||
965 | Note that most people are still using Kernighan & Ritchie syntax here. | |
966 | I personally don't like this and especially in this documentation it | |
967 | cannot be of harm, so let's use ANSI. Finally Tim Bunce has announced | |
968 | interest in moving the DBI sources to ANSI as well. | |
969 | ||
970 | =over 2 | |
971 | ||
972 | =item Initialization | |
973 | ||
974 | #include "Driver.h" | |
975 | ||
976 | DBISTATE_DECLARE; | |
977 | ||
978 | void dbd_init(dbistate_t* dbistate) { | |
979 | DBIS = dbistate; /* Initialize the DBI macros */ | |
980 | } | |
981 | ||
982 | dbd_init will be called when your driver is first loaded. These | |
983 | statements are needed for use of the DBI macros. They will include your | |
984 | private header file I<dbdimp.h> in turn. | |
985 | ||
986 | =item do_error | |
987 | ||
988 | You need a function to handle recording of errors. You can call it | |
989 | whatever you like, but we'll call it C<do_error> here. | |
990 | ||
991 | void do_error(SV* h, int rc, char* what) { | |
992 | ||
993 | Note that I<h> is a generic handle, may it be a driver handle, a | |
994 | database or a statement handle. | |
995 | ||
996 | D_imp_xxh(h); | |
997 | ||
998 | This macro will declare and initialize a variable I<imp_xxh> with | |
999 | a pointer to your private handle pointer. You may cast this to | |
1000 | to I<imp_drh_t>, I<imp_dbh_t> or I<imp_sth_t>. | |
1001 | ||
1002 | SV *errstr = DBIc_ERRSTR(imp_xxh); | |
1003 | sv_setiv(DBIc_ERR(imp_xxh), (IV)rc); /* set err early */ | |
1004 | sv_setpv(errstr, what); | |
1005 | DBIh_EVENT2(h, ERROR_event, DBIc_ERR(imp_xxh), errstr); | |
1006 | ||
1007 | Note the use of the macros DBIc_ERRSTR and DBIc_ERR for accessing the | |
1008 | handles error string and error code. | |
1009 | ||
1010 | The macro DBIh_EVENT2 will ensure that the attributes I<RaiseError> | |
1011 | and I<PrintError> work: That's all what you have to deal with them. :-) | |
1012 | ||
1013 | if (dbis->debug >= 2) | |
1014 | fprintf(DBILOGFP, "%s error %d recorded: %s\n", | |
1015 | what, rc, SvPV(errstr,na)); | |
1016 | ||
1017 | That's the first time we see how debug/trace logging works within a DBI | |
1018 | driver. Make use of this as often as you can! | |
1019 | ||
1020 | =item dbd_db_login | |
1021 | ||
1022 | int dbd_db_login(SV* dbh, imp_dbh_t* imp_dbh, char* dbname, | |
1023 | char* user, char* auth) { | |
1024 | ||
1025 | This function will really connect to the database. The argument I<dbh> | |
1026 | is the database handle. I<imp_dbh> is the pointer to the handles private | |
1027 | data, as is I<imp_xxx> in I<do_error> above. The arguments I<dsn>, | |
1028 | I<user> and I<auth> correspond to the arguments of the driver handles | |
1029 | I<connect> method. | |
1030 | ||
1031 | You will quite often use database specific attributes here, that are | |
1032 | specified in the DSN. I recommend you parse the DSN within the | |
1033 | I<connect> method and pass them as handle attributes to I<dbd_db_login>. | |
1034 | Here's how you fetch them, as an example we use I<hostname> and I<port> | |
1035 | attributes: | |
1036 | ||
1037 | /* This code assumes that the *second* attribute parameter to | |
1038 | * DBI::_new_dbh was used to store an hash with login attributes | |
1039 | */ | |
1040 | SV* imp_data = DBIc_IMP_DATA(dbh); | |
1041 | HV* hv; | |
1042 | SV** svp; | |
1043 | char* hostname; | |
1044 | char* port; | |
1045 | ||
1046 | if (!SvTRUE(imp_data) || !SvROK(imp_data) || | |
1047 | SvTYPE(hv = (HV*) SvRV(imp_data)) != SVt_PVHV) { | |
1048 | croak("Implementation dependent data invalid: Not a hash ref.\n"); | |
1049 | } | |
1050 | if ((svp = hv_fetch(hv, "hostname", strlen("hostname"), FALSE)) && | |
1051 | SvTRUE(*svp)) { | |
1052 | hostname = SvPV(*svp, na); | |
1053 | } else { | |
1054 | hostname = "localhost"; | |
1055 | } | |
1056 | if ((svp = hv_fetch(hv, "port", strlen("port"), FALSE)) && | |
1057 | SvTRUE(*svp)) { | |
1058 | port = SvPV(*svp, na); /* May be a service name */ | |
1059 | } else { | |
1060 | port = DEFAULT_PORT; | |
1061 | } | |
1062 | ||
1063 | Now you should really connect to the database. If you are successful | |
1064 | (or even if you fail, but you have allocated some resources), you should | |
1065 | use the following macros: | |
1066 | ||
1067 | DBIc_IMPSET_on(imp_dbh); | |
1068 | ||
1069 | This indicates that the driver (implementor) has allocated resources in | |
1070 | the imp_dbh structure and that the implementors private dbd_db_destroy | |
1071 | function should be called when the handle is destroyed. | |
1072 | ||
1073 | DBIc_ACTIVE_on(imp_dbh); | |
1074 | ||
1075 | This indicates that the handle has an active connection to the server | |
1076 | and that the dbd_db_disconnect function should be called before the | |
1077 | handle is destroyed. | |
1078 | ||
1079 | The dbd_db_login function should return TRUE for success, FALSE otherwise. | |
1080 | ||
1081 | ||
1082 | =item dbd_db_commit | |
1083 | ||
1084 | =item dbd_db_rollback | |
1085 | ||
1086 | int dbd_db_commit( SV* dbh, imp_dbh_t* imp_dbh ); | |
1087 | int dbd_db_rollback( SV* dbh, imp_dbh_t* imp_dbh ); | |
1088 | ||
1089 | These are used for commit and rollback. They should return TRUE for | |
1090 | success, FALSE for error. | |
1091 | ||
1092 | The arguments I<dbh> and I<imp_dbh> are like above, I will omit | |
1093 | describing them in what follows, as they appear always. | |
1094 | ||
1095 | ||
1096 | =item dbd_db_disconnect | |
1097 | ||
1098 | This is your private part of the I<disconnect> method. Any dbh with | |
1099 | the I<ACTIVE> flag on must be disconnected. (Note that you have to set | |
1100 | it in I<dbd_db_connect> above.) | |
1101 | ||
1102 | int dbd_db_disconnect(SV* dbh, imp_dbh_t* imp_dbh); | |
1103 | ||
1104 | The database handle will return TRUE for success, FALSE otherwise. | |
1105 | In any case it should do a | |
1106 | ||
1107 | DBIc_ACTIVE_off(imp_dbh); | |
1108 | ||
1109 | before returning so DBI knows that I<dbd_db_disconnect> was executed. | |
1110 | ||
1111 | ||
1112 | =item dbd_db_discon_all | |
1113 | ||
1114 | int dbd_discon_all (SV *drh, imp_drh_t *imp_drh) { | |
1115 | ||
1116 | This function may be called at shutdown time. It should make | |
1117 | best-efforts to disconnect all database handles - if possible. Some | |
1118 | databases don't support that, in which case you can do nothing | |
1119 | but return 'success'. | |
1120 | ||
1121 | You guess what the return codes are? (Hint: See the last functions | |
1122 | above ... :-) | |
1123 | ||
1124 | ||
1125 | =item dbd_db_destroy | |
1126 | ||
1127 | This is your private part of the database handle destructor. Any dbh with | |
1128 | the I<IMPSET> flag on must be destroyed, so that you can safely free | |
1129 | resources. (Note that you have to set it in I<dbd_db_connect> above.) | |
1130 | ||
1131 | void dbd_db_destroy(SV* dbh, imp_dbh_t* imp_dbh) { | |
1132 | DBIc_IMPSET_off(imp_dbh); | |
1133 | } | |
1134 | ||
1135 | The DBI Driver.xst code will have called dbd_db_disconnect for you, | |
1136 | if the handle is still 'active', before calling dbd_db_destroy. | |
1137 | ||
1138 | Before returning the function must switch IMPSET to off, so DBI knows | |
1139 | that the destructor was called. | |
1140 | ||
1141 | ||
1142 | =item dbd_db_STORE_attrib | |
1143 | ||
1144 | This function handles | |
1145 | ||
1146 | $dbh->{$key} = $value; | |
1147 | ||
1148 | its prototype is | |
1149 | ||
1150 | int dbd_db_STORE_attrib(SV* dbh, imp_dbh_t* imp_dbh, SV* keysv, | |
1151 | SV* valuesv); | |
1152 | ||
1153 | You do not handle all attributes, in contrary you should not handle | |
1154 | DBI attributes here: Leave this to DBI. (There's one exception, | |
1155 | I<AutoCommit>, which you should care about.) | |
1156 | ||
1157 | The return value is TRUE, if you have handled the attribute or FALSE | |
1158 | otherwise. If you are handling an attribute and something fails, you | |
1159 | should call I<do_error>, so DBI can raise exceptions, if desired. | |
1160 | If I<do_error> returns, however, you have a problem: The user will | |
1161 | never know about the error, because he typically will not check | |
1162 | C<$dbh-E<gt>errstr>. | |
1163 | ||
1164 | I cannot recommend a general way of going on, if I<do_error> returns, | |
1165 | but there are examples where even the DBI specification expects that | |
1166 | you croak(). (See the I<AutoCommit> method in L<DBI(3)>.) | |
1167 | ||
1168 | If you have to store attributes, you should either use your private | |
1169 | data structure imp_xxx, the handle hash (via (HV*)SvRV(dbh)), or use | |
1170 | the private imp_data. | |
1171 | ||
1172 | The first is best for internal C values like integers or pointers and | |
1173 | where speed is important within the driver. The handle hash is best for | |
1174 | values the user may want to get/set via driver-specific attributes. | |
1175 | The private imp_data is an additional SV attached to the handle. You | |
1176 | could think of it as an unnamed handle attribute. It's not normally used. | |
1177 | ||
1178 | ||
1179 | =item dbd_db_FETCH_attrib | |
1180 | ||
1181 | This is the counterpart of dbd_db_STORE_attrib, needed for | |
1182 | ||
1183 | $value = $dbh->{$key}; | |
1184 | ||
1185 | Its prototype is: | |
1186 | ||
1187 | SV* dbd_db_FETCH_attrib(SV* dbh, imp_dbh_t* imp_dbh, SV* keysv) { | |
1188 | ||
1189 | Unlike all previous methods this returns an SV with the value. Note | |
1190 | that you should normally execute sv_2mortal, if you return a nonconstant | |
1191 | value. (Constant values are C<&sv_undef>, C<&sv_no> and C<&sv_yes>.) | |
1192 | ||
1193 | Note, that DBI implements a caching algorithm for attribute values. | |
1194 | If you think, that an attribute may be fetched, you store it in the | |
1195 | dbh itself: | |
1196 | ||
1197 | if (cacheit) /* cache value for later DBI 'quick' fetch? */ | |
1198 | hv_store((HV*)SvRV(dbh), key, kl, cachesv, 0); | |
1199 | ||
1200 | ||
1201 | =item dbd_st_prepare | |
1202 | ||
1203 | This is the private part of the I<prepare> method. Note that you | |
1204 | B<must not> really execute the statement here. You may, for example, | |
1205 | preparse and validate the statement or do similar things. | |
1206 | ||
1207 | int dbd_st_prepare(SV* sth, imp_sth_t* imp_sth, char* statement, | |
1208 | SV* attribs); | |
1209 | ||
1210 | A typical, simple possibility is just to store the statement in the | |
1211 | imp_data hash ref and use it in dbd_st_execute. If you can, you should | |
1212 | setup attributes like NUM_OF_FIELDS, NAME, ... here, but DBI | |
1213 | doesn't require that. However, if you do, document it. | |
1214 | ||
1215 | In any case you should set the IMPSET flag, as you did in | |
1216 | I<dbd_db_connect> above: | |
1217 | ||
1218 | DBIc_IMPSET_on(imp_sth); | |
1219 | ||
1220 | ||
1221 | =item dbd_st_execute | |
1222 | ||
1223 | This is where a statement will really be executed. | |
1224 | ||
1225 | int dbd_st_execute(SV* sth, imp_sth_t* imp_sth); | |
1226 | ||
1227 | Note, that you must be aware, that a statement may be executed repeatedly. | |
1228 | Also, you should not expect, that I<finish> will be called between | |
1229 | two executions. | |
1230 | ||
1231 | If your driver supports binding of parameters (he should!), but the | |
1232 | database doesn't, you must probably do it here. This can be done as | |
1233 | follows: | |
1234 | ||
1235 | char* statement = dbd_st_get_statement(sth, imp_sth); | |
1236 | /* Its your drivers task to implement this function. It */ | |
1237 | /* must restore the statement passed to preparse. */ | |
1238 | /* See use of imp_data above for an example of how to do */ | |
1239 | /* this. */ | |
1240 | int numParam = DBIc_NUM_PARAMS(imp_sth); | |
1241 | int i; | |
1242 | ||
1243 | for (i = 0; i < numParam; i++) { | |
1244 | char* value = dbd_db_get_param(sth, imp_sth, i); | |
1245 | /* Its your drivers task to implement dbd_db_get_param, */ | |
1246 | /* it must be setup as a counterpart of dbd_bind_ph. */ | |
1247 | /* Look for '?' and replace it with 'value'. Difficult */ | |
1248 | /* task, note that you may have question marks inside */ | |
1249 | /* quotes and the like ... :-( */ | |
1250 | /* See DBD::mysql for an example. (Don't look too deep into */ | |
1251 | /* the example, you will notice where I was lazy ...) */ | |
1252 | } | |
1253 | ||
1254 | The next thing is you really execute the statement. Note that you must | |
1255 | prepare the attributes NUM_OF_FIELDS, NAME, ... when the statement is | |
1256 | successfully executed if you have not already done so: They may be used even before a potential | |
1257 | I<fetchrow>. In particular you have to tell DBI the number of fields, | |
1258 | that the statement has, because it will be used by DBI internally. | |
1259 | Thus the function will typically ends with: | |
1260 | ||
1261 | if (isSelectStatement) { | |
1262 | DBIc_NUM_FIELDS(imp_sth) = numFields; | |
1263 | DBIc_ACTIVE_on(imp_sth); | |
1264 | } | |
1265 | ||
1266 | It is important that the ACTIVE flag only be set for select statements. | |
1267 | See I<dbd_st_preparse> and I<dbd_db_connect> above for more explanations. | |
1268 | ||
1269 | ||
1270 | =item dbd_st_fetch | |
1271 | ||
1272 | This function fetches a row of data. The row is stored in in an array, | |
1273 | of SV's that DBI prepares for you. This has two advantages: It is fast | |
1274 | (you even reuse the SV's, so they don't have to be created after the | |
1275 | first fetchrow) and it guarantees, that DBI handles I<bind_cols> for | |
1276 | you. | |
1277 | ||
1278 | What you do is the following: | |
1279 | ||
1280 | AV* av; | |
1281 | int numFields = DBIc_NUM_FIELDS(imp_sth); /* Correct, if NUM_FIELDS | |
1282 | is constant for this statement. There are drivers where this is | |
1283 | not the case! */ | |
1284 | int chopBlanks = DBIc_is(imp_sth, DBIcf_ChopBlanks); | |
1285 | int i; | |
1286 | ||
1287 | if (!fetch_new_row_of_data(...)) { | |
1288 | ... /* check for error or end-of-data */ | |
1289 | DBIc_ACTIVE_off(imp_sth); /* turn off Active flag automatically */ | |
1290 | return Nullav; | |
1291 | } | |
1292 | /* get the fbav (field buffer array value) for this row */ | |
1293 | /* it is very important to only call this after you know */ | |
1294 | /* that you have a row of data to return. */ | |
1295 | av = DBIS->get_fbav(imp_sth); | |
1296 | for (i = 0; i < numFields; i++) { | |
1297 | SV* sv = fetch_a_field(..., i); | |
1298 | if (chopBlanks && SvOK(sv) && type_is_blank_padded(field_type[i])) { | |
1299 | /* Remove white space from end (only) of sv */ | |
1300 | } | |
1301 | sv_setsv(AvARRAY(av)[i], sv); /* Note: (re)use! */ | |
1302 | } | |
1303 | return av; | |
1304 | ||
1305 | There's no need to use a fetch_a_field function returning an SV*. | |
1306 | It's more common to use your database API functions to fetch the | |
1307 | data as character strings and use code like this: | |
1308 | ||
1309 | sv_setpvn(AvARRAY(av)[i], char_ptr, char_count); | |
1310 | ||
1311 | NULL values must be returned as undef. You can use code like this: | |
1312 | ||
1313 | SvOK_off(AvARRAY(av)[i]); | |
1314 | ||
1315 | The function returns the AV prepared by DBI for success or C<Nullav> | |
1316 | otherwise. | |
1317 | ||
1318 | ||
1319 | =item dbd_st_finish | |
1320 | ||
1321 | This function can be called if the user wishes to indicate that no | |
1322 | more rows will be fetched even if the server has more rows to offer. | |
1323 | See the DBI docs for more background details. | |
1324 | ||
1325 | All it I<needs> to do is turn off the Active flag for the sth. | |
1326 | It will only be called by Driver.xst code, if the driver has set | |
1327 | ACTIVE to on for the sth. | |
1328 | ||
1329 | Minimal example (the DBI default method just does this): | |
1330 | ||
1331 | int dbd_st_finish(SV* sth, imp_sth_t* imp_sth) { | |
1332 | DBIc_ACTIVE_off(imp_sth); | |
1333 | return 1; | |
1334 | } | |
1335 | ||
1336 | The function returns TRUE for success, FALSE otherwise. | |
1337 | ||
1338 | ||
1339 | =item dbd_st_destroy | |
1340 | ||
1341 | This function is the private part of the statement handle destructor. | |
1342 | ||
1343 | void dbd_st_destroy(SV* sth, imp_sth_t* imp_sth); | |
1344 | ... /* any clean-up that's needed */ | |
1345 | DBIc_IMPSET_off(imp_sth); /* let DBI know we've done it */ | |
1346 | } | |
1347 | ||
1348 | The DBI Driver.xst code will call dbd_st_finish for you, if the sth has | |
1349 | the ACTIVE flag set, before calling dbd_st_destroy. | |
1350 | ||
1351 | =item dbd_st_STORE_attrib | |
1352 | ||
1353 | =item dbd_st_FETCH_attrib | |
1354 | ||
1355 | These functions correspond to dbd_db_STORE|FETCH attrib above, except | |
1356 | that they are for statement handles. See above. | |
1357 | ||
1358 | int dbd_st_STORE_attrib(SV* sth, imp_sth_t* imp_sth, SV* keysv, | |
1359 | SV* valuesv); | |
1360 | SV* dbd_st_FETCH_attrib(SV* sth, imp_sth_t* imp_sth, SV* keysv); | |
1361 | ||
1362 | ||
1363 | =item dbd_bind_ph | |
1364 | ||
1365 | This function is internally used by the I<bind_param> method, the | |
1366 | I<bind_param_inout> method and by the DBI Driver.xst code if C<execute> | |
1367 | is called with any bind parameters. | |
1368 | ||
1369 | int dbd_bind_ph (SV *sth, imp_sth_t *imp_sth, SV *param, | |
1370 | SV *value, IV sql_type, SV *attribs, | |
1371 | int is_inout, IV maxlen); | |
1372 | ||
1373 | The I<param> argument holds an IV with the parameter number (1, 2, ...). | |
1374 | The I<value> argument is the parameter value and I<sql_type> is its type. | |
1375 | ||
1376 | If your driver does not support bind_param_inout then you should | |
1377 | ignore I<maxlen> and croak if I<is_inout> is TRUE. | |
1378 | ||
1379 | If your driver I<does> support bind_param_inout then you should | |
1380 | note that I<value> is the SV I<after> dereferencing the reference | |
1381 | passed to bind_param_inout. | |
1382 | ||
1383 | In drivers of simple databases the function will, for example, store | |
1384 | the value in a parameter array and use it later in I<dbd_st_execute>. | |
1385 | See the I<DBD::mysql> driver for an example. | |
1386 | ||
1387 | ||
1388 | =back | |
1389 | ||
1390 | =head2 Implementing bind_param_inout support | |
1391 | ||
1392 | To provide support for parameters bound by reference rather than by | |
1393 | value, the driver must do a number of things. First, and most | |
1394 | importantly, it must note the references and stash them in its own | |
1395 | driver structure. Secondly, when a value is bound to a column, the | |
1396 | driver must discard any previous reference bound to the column. On | |
1397 | each execute, the driver must evaluate the references and internally | |
1398 | bind the values resulting from the references. This is only applicable | |
1399 | if the user writes: | |
1400 | ||
1401 | $sth->execute; | |
1402 | ||
1403 | If the user writes: | |
1404 | ||
1405 | $sth->execute(@values); | |
1406 | ||
1407 | then DBI automatically calls the binding code for each element of | |
1408 | @values. These calls are indistinguishable from explicit user calls to | |
1409 | bind_param. | |
1410 | ||
1411 | ||
1412 | =head2 Makefile.PL | |
1413 | ||
1414 | This is exactly as in the Pure Perl case. To be honest, the above | |
1415 | Makefile.PL contains some things that are superfluous for Pure Perl | |
1416 | drivers. :-) | |
1417 | ||
1418 | ||
1419 | =head1 METHODS WHICH DO NOT NEED TO BE WRITTEN | |
1420 | ||
1421 | The DBI code implements the majority of the methods which are | |
1422 | accessed using the notation DBI->function(), the only exceptions being | |
1423 | DBI->connect() and DBI->data_sources() which require support from the | |
1424 | driver. | |
1425 | ||
1426 | The DBI code implements the following documented driver, database and | |
1427 | statement functions which do not need to be written by the DBD driver | |
1428 | writer. | |
1429 | ||
1430 | =over 4 | |
1431 | ||
1432 | =item $dbh->do() | |
1433 | ||
1434 | The default implementation of this function prepares, executes and | |
1435 | destroys the statement. This can be replaced if there is a better | |
1436 | way to implement this, such as EXECUTE IMMEDIATE which can | |
1437 | sometimes be used if there are no parameters. | |
1438 | ||
1439 | =item $h->errstr() | |
1440 | ||
1441 | =item $h->err() | |
1442 | ||
1443 | =item $h->state() | |
1444 | ||
1445 | =item $h->trace() | |
1446 | ||
1447 | The DBD driver does not need to worry about these routines at all. | |
1448 | ||
1449 | =item $h->{ChopBlanks} | |
1450 | ||
1451 | This attribute needs to be honured during fetch operations, but does | |
1452 | not need to be handled by the attribute handling code. | |
1453 | ||
1454 | =item $h->{RaiseError} | |
1455 | ||
1456 | The DBD driver does not need to worry about this attribute at all. | |
1457 | ||
1458 | =item $h->{PrintError} | |
1459 | ||
1460 | The DBD driver does not need to worry about this attribute at all. | |
1461 | ||
1462 | =item $sth->bind_col() | |
1463 | ||
1464 | Assuming the driver uses the DBIS->get_fbav() function (C drivers, | |
1465 | see below), or the $sth->_set_fbav($data) method (Perl drivers) | |
1466 | the driver does not need to do anything about this routine. | |
1467 | ||
1468 | =item $sth->bind_columns() | |
1469 | ||
1470 | Regardless of whether the driver uses DBIS->get_fbav(), the driver | |
1471 | does not need to do anything about this routine as it simply | |
1472 | iteratively calls $sth->bind_col(). | |
1473 | ||
1474 | =back | |
1475 | ||
1476 | The DBI code implements a default implementation of the following | |
1477 | functions which do not need to be written by the DBD driver writer | |
1478 | unless the default implementation is incorrect for the Driver. | |
1479 | ||
1480 | =over 4 | |
1481 | ||
1482 | =item $dbh->quote() | |
1483 | ||
1484 | This should only be written if the database does not accept the ANSI | |
1485 | SQL standard for quoting strings, with the string enclosed in single | |
1486 | quotes and any embedded single quotes replaced by two consecutive | |
1487 | single quotes. | |
1488 | ||
1489 | For the two argument form of quote, you need to implement the | |
1490 | C<type_info> method to provide the information that quote needs. | |
1491 | ||
1492 | =item $dbh->ping() | |
1493 | ||
1494 | This should be implemented as a simple efficient way to determine | |
1495 | whether the connection to the database is still alive. Typically | |
1496 | code like this: | |
1497 | ||
1498 | sub ping { | |
1499 | my $dbh = shift; | |
1500 | $sth = $dbh->prepare_cached(q{ | |
1501 | select * from A_TABLE_NAME where 1=0 | |
1502 | }) or return 0; | |
1503 | $sth->execute or return 0; | |
1504 | $sth->finish; | |
1505 | return 1; | |
1506 | } | |
1507 | ||
1508 | where A_TABLE_NAME is the name of a table that always exists (such as a | |
1509 | database system catalogue). | |
1510 | ||
1511 | =back | |
1512 | ||
1513 | ||
1514 | =head1 WRITING AN EMULATION LAYER FOR AN OLD PERL INTERFACE | |
1515 | ||
1516 | Study Oraperl.pm (supplied with DBD::Oracle) and Ingperl.pm (supplied | |
1517 | with DBD::Ingres) and the corresponding dbdimp.c files for ideas. | |
1518 | ||
1519 | Note that the emulation code sets $dbh->{CompatMode} = 1; for each | |
1520 | connection so that the internals of the driver can implement behaviour | |
1521 | compatible with the old interface when dealing with those handles. | |
1522 | ||
1523 | =head2 Setting emulation perl variables | |
1524 | ||
1525 | For example, ingperl has a $sql_rowcount variable. Rather than try | |
1526 | to manually update this in Ingperl.pm it can be done faster in C code. | |
1527 | In dbd_init(): | |
1528 | ||
1529 | sql_rowcount = perl_get_sv("Ingperl::sql_rowcount", GV_ADDMULTI); | |
1530 | ||
1531 | In the relevant places do: | |
1532 | ||
1533 | if (DBIc_COMPAT(imp_sth)) /* only do this for compatibility mode handles */ | |
1534 | sv_setiv(sql_rowcount, the_row_count); | |
1535 | ||
1536 | ||
1537 | =head1 OTHER MISCELLANEOUS INFORMATION | |
1538 | ||
1539 | =head2 The imp_xyz_t types | |
1540 | ||
1541 | Any handle has a corresponding C structure filled with private data. | |
1542 | Some of this data is reserved for use by DBI (except for using the | |
1543 | DBIc macros below), some is for you. See the description of the | |
1544 | I<dbdimp.h> file above for examples. The most functions in dbdimp.c | |
1545 | are passed both the handle C<xyz> and a pointer to C<imp_xyz>. In | |
1546 | rare cases, however, you may use the following macros: | |
1547 | ||
1548 | =over 2 | |
1549 | ||
1550 | =item D_imp_dbh(dbh) | |
1551 | ||
1552 | Given a function argument I<dbh>, declare a variable I<imp_dbh> and | |
1553 | initialize it with a pointer to the handles private data. Note: This | |
1554 | must be a part of the function header, because it declares a variable. | |
1555 | ||
1556 | =item D_imp_sth(sth) | |
1557 | ||
1558 | Likewise for statement handles. | |
1559 | ||
1560 | =item D_imp_xxx(h) | |
1561 | ||
1562 | Given any handle, declare a variable I<imp_xxx> and initialize it | |
1563 | with a pointer to the handles private data. It is safe, for example, | |
1564 | to cast I<imp_xxx> to C<imp_dbh_t*>, if DBIc_TYPE(imp_xxx) == DBIt_DB. | |
1565 | (You can also call sv_derived_from(h, "DBI::db"), but that's much | |
1566 | slower.) | |
1567 | ||
1568 | =item D_imp_sth_from_dbh | |
1569 | ||
1570 | Given a imp_sth, declare a variable I<imp_dbh> and initialize it with a | |
1571 | pointer to the parent database handles implementors structure. | |
1572 | ||
1573 | =back | |
1574 | ||
1575 | ||
1576 | =head2 Using DBIc_IMPSET_on | |
1577 | ||
1578 | The driver code which initializes a handle should use DBIc_IMPSET_on() | |
1579 | as soon as its state is such that the cleanup code must be called. | |
1580 | When this happens is determined by your driver code. | |
1581 | ||
1582 | Failure to call this can lead to corruption of data structures. | |
1583 | For example, DBD::Informix maintains a linked list of database handles | |
1584 | in the driver, and within each handle, a linked list of statements. | |
1585 | Once a statement is added to the linked list, it is crucial that it is | |
1586 | cleaned up (removed from the list). | |
1587 | When DBIc_IMPSET_on() was being called too late, it was able to cause | |
1588 | all sorts of problems. | |
1589 | ||
1590 | ||
1591 | =head2 Using DBIc_is(), DBIc_has(), DBIc_on() and DBIc_off() | |
1592 | ||
1593 | Once upon a long time ago, the only way of handling the internal DBI | |
1594 | boolean flags/attributes was through macros such as: | |
1595 | ||
1596 | DBIc_WARN DBIc_WARN_on DBIc_WARN_off | |
1597 | DBIc_COMPAT DBIc_COMPAT_on DBIc_COMPAT_off | |
1598 | ||
1599 | Each of these took an imp_xxh pointer as an argument. | |
1600 | ||
1601 | Since then, new attributes have been added such as ChopBlanks, | |
1602 | RaiseError and PrintError, and these do not have the full set of | |
1603 | macros. | |
1604 | The approved method for handling these is now the four macros: | |
1605 | ||
1606 | DBIc_is(imp, flag) | |
1607 | DBIc_has(imp, flag) an alias for DBIc_is | |
1608 | DBIc_on(imp, flag) | |
1609 | DBIc_off(imp, flag) | |
1610 | ||
1611 | Consequently, the DBIc_XXXXX family of macros is now mostly deprecated | |
1612 | and new drivers should avoid using them, even though the older drivers | |
1613 | will probably continue to do so for quite a while yet. However... | |
1614 | ||
1615 | There is an I<important exception> to that. The ACTIVE and IMPSET | |
1616 | flags should be set via the DBIc_ACTIVE_on and DBIc_IMPSET_on macros, | |
1617 | and unset via the DBIc_ACTIVE_off and DBIc_IMPSET_off macros. | |
1618 | ||
1619 | ||
1620 | =head2 Using DBIS->get_fbav() | |
1621 | ||
1622 | The $sth->bind_col() and $sth->bind_columns() documented in the DBI | |
1623 | specification do not have to be implemented by the driver writer | |
1624 | becuase DBI takes care of the details for you. | |
1625 | However, the key to ensuring that bound columns work is to call the | |
1626 | function DBIS->get_fbav() in the code which fetches a row of data. | |
1627 | This returns an AV, and each element of the AV contains the SV which | |
1628 | should be set to contain the returned data. | |
1629 | ||
1630 | The above is for C drivers only. The Perl equivalent is the | |
1631 | $sth->_set_fbav($data) method, as described in the part on Pure | |
1632 | Perl drivers. | |
1633 | ||
1634 | ||
1635 | =head1 SUBCLASSING DBI DRIVERS | |
1636 | ||
1637 | This is definitely an open subject. It can be done, as demonstrated by | |
1638 | the I<DBD::File> driver, but it is not as simple as one might think. | |
1639 | ||
1640 | (Note that this topic is different from subclassing the DBI. For an | |
1641 | example of that, see the t/subclass.t file supplied with the DBI.) | |
1642 | ||
1643 | The main problem is that the dbh's and sth's that your I<connect> and | |
1644 | I<prepare> methods return are not instances of your I<DBD::Driver::db> | |
1645 | or I<DBD::Driver::st> packages, they are not even derived from it. | |
1646 | Instead they are instances of the I<DBI::db> or I<DBI::st> classes or | |
1647 | a derived subclass. Thus, if you write a method I<mymethod> and do a | |
1648 | ||
1649 | $dbh->mymethod() | |
1650 | ||
1651 | then the autoloader will search for that method in the package I<DBI::db>. | |
1652 | Of course you can instead to a | |
1653 | ||
1654 | $dbh->func('mymethod') | |
1655 | ||
1656 | and that will indeed work, even if I<mymethod> is inherited, but not | |
1657 | without additional work. Setting C<@ISA> is not sufficient. | |
1658 | ||
1659 | ||
1660 | =head2 Overwriting methods | |
1661 | ||
1662 | The first problem is, that the I<connect> method has no idea of | |
1663 | subclasses. For example, you cannot implement base class and subclass | |
1664 | in the same file: The I<install_driver> method wants to do a | |
1665 | ||
1666 | require DBD::Driver; | |
1667 | ||
1668 | In particular, your subclass B<has> to be a separate driver, from | |
1669 | the view of DBI, and you cannot share driver handles. | |
1670 | ||
1671 | Of course that's not much of a problem. You should even be able | |
1672 | to inherit the base classes I<connect> method. But you cannot | |
1673 | simply overwrite the method, unless you do something like this, | |
1674 | quoted from I<DBD::CSV>: | |
1675 | ||
1676 | sub connect ($$;$$$) { | |
1677 | my($drh, $dbname, $user, $auth, $attr) = @_; | |
1678 | ||
1679 | my $this = $drh->DBD::File::dr::connect($dbname, $user, $auth, $attr); | |
1680 | if (!exists($this->{csv_tables})) { | |
1681 | $this->{csv_tables} = {}; | |
1682 | } | |
1683 | ||
1684 | $this; | |
1685 | } | |
1686 | ||
1687 | Note that we cannot do a | |
1688 | ||
1689 | $srh->SUPER::connect($dbname, $user, $auth, $attr); | |
1690 | ||
1691 | as we would usually do in a an OO environment, because $drh is an instance | |
1692 | of I<DBI::dr>. And note, that the I<connect> method of I<DBD::File> is | |
1693 | able to handle subclass attributes. See the description of Pure Perl | |
1694 | drivers above. | |
1695 | ||
1696 | It is essential that you always call superclass method in the above | |
1697 | manner. However, that should do. | |
1698 | ||
1699 | ||
1700 | =head2 Attribute handling | |
1701 | ||
1702 | Fortunately the DBI specs allow a simple, but still performant way of | |
1703 | handling attributes. The idea is based on the convention that any | |
1704 | driver uses a prefix I<driver_> for its private methods. Thus it's | |
1705 | always clear whether to pass attributes to the super class or not. | |
1706 | For example, consider this STORE method from the I<DBD::CSV> class: | |
1707 | ||
1708 | sub STORE { | |
1709 | my($dbh, $attr, $val) = @_; | |
1710 | if ($attr !~ /^driver_/) { | |
1711 | return $dbh->DBD::File::db::STORE($attr, $val); | |
1712 | } | |
1713 | if ($attr eq 'driver_foo') { | |
1714 | ... | |
1715 | } | |
1716 | ||
1717 | ||
1718 | =head1 ACKNOWLEDGEMENTS | |
1719 | ||
1720 | Tim Bunce - for writing DBI and managing the DBI specification and the | |
1721 | DBD::Oracle driver. | |
1722 | ||
1723 | ||
1724 | =head1 AUTHORS | |
1725 | ||
1726 | Jonathan Leffler <jleffler@informix.com>, | |
1727 | Jochen Wiedmann <joe@ispsoft.de>, | |
1728 | and Tim Bunce. | |
1729 | ||
1730 | =cut | |
1731 | ||
1732 | ||
1733 | package DBI::DBD; | |
1734 | ||
1735 | use Exporter (); | |
1736 | use Config; | |
1737 | use Carp; | |
1738 | use strict; | |
1739 | use vars qw( | |
1740 | @ISA @EXPORT $VERSION | |
1741 | $is_dbi | |
1742 | ); | |
1743 | ||
1744 | BEGIN { if ($^O eq 'VMS') { | |
1745 | require vmsish; | |
1746 | import vmsish; | |
1747 | require VMS::Filespec; | |
1748 | import VMS::Filespec; | |
1749 | }} | |
1750 | ||
1751 | @ISA = qw(Exporter); | |
1752 | ||
1753 | $VERSION = substr(q$Revision: 10.9 $, 10); | |
1754 | ||
1755 | @EXPORT = qw( | |
1756 | dbd_dbi_dir dbd_dbi_arch_dir | |
1757 | dbd_edit_mm_attribs dbd_postamble | |
1758 | ); | |
1759 | ||
1760 | BEGIN { | |
1761 | $is_dbi = (-r 'DBI.pm' && -r 'DBI.xs' && -r 'DBIXS.h'); | |
1762 | require DBI unless $is_dbi; | |
1763 | } | |
1764 | ||
1765 | ||
1766 | sub dbd_edit_mm_attribs { | |
1767 | my %a = @_; | |
1768 | ||
1769 | return %a; | |
1770 | } | |
1771 | ||
1772 | ||
1773 | sub dbd_dbi_dir { | |
1774 | return '.' if $is_dbi; | |
1775 | my $dbidir = $INC{'DBI.pm'} || die "DBI.pm not in %INC!"; | |
1776 | $dbidir =~ s:/DBI\.pm$::; | |
1777 | return $dbidir; | |
1778 | } | |
1779 | ||
1780 | sub dbd_dbi_arch_dir { | |
1781 | if ($is_dbi) { | |
1782 | return '$(INST_ARCHAUTODIR)' | |
1783 | } | |
1784 | my $dbidir = dbd_dbi_dir(); | |
1785 | my @try = map { "$_/auto/DBI" } @INC; | |
1786 | my @xst = grep { -f "$_/Driver.xst" } @try; | |
1787 | Carp::croak("Unable to locate Driver.xst in @try") unless @xst; | |
1788 | Carp::carp( "Multiple copies of Driver.xst found in: @xst") if @xst > 1; | |
1789 | print "Using DBI $DBI::VERSION installed in $xst[0]\n"; | |
1790 | return $xst[0]; | |
1791 | } | |
1792 | ||
1793 | ||
1794 | sub dbd_postamble { | |
1795 | my $dbidir = dbd_dbi_dir(); | |
1796 | my $xstdir = dbd_dbi_arch_dir(); | |
1797 | my $xstfile= '$(DBI_INSTARCH_DIR)/Driver.xst'; | |
1798 | if ($^O eq 'VMS') { | |
1799 | $dbidir = vmsify($dbidir.'/'); | |
1800 | $xstdir = vmsify($xstdir.'/') unless $is_dbi; | |
1801 | $xstfile= '$(DBI_INSTARCH_DIR)Driver.xst'; | |
1802 | } | |
1803 | ||
1804 | # we must be careful of quotes, expecially for Win32 here. | |
1805 | ' | |
1806 | # This section was generated by DBI::DBD::dbd_postamble() | |
1807 | DBI_INST_DIR='.$dbidir.' | |
1808 | DBI_INSTARCH_DIR='.$xstdir.' | |
1809 | DBI_DRIVER_XST='.$xstfile.' | |
1810 | ||
1811 | # The main dependancy (technically correct but probably not used) | |
1812 | $(BASEEXT).c: $(BASEEXT).xsi | |
1813 | ||
1814 | # This dependancy is needed since MakeMaker uses the .xs.o rule | |
1815 | $(BASEEXT)$(OBJ_EXT): $(BASEEXT).xsi | |
1816 | ||
1817 | $(BASEEXT).xsi: $(DBI_DRIVER_XST) | |
1818 | $(PERL) -p -e "s/~DRIVER~/$(BASEEXT)/g" < $(DBI_DRIVER_XST) > $(BASEEXT).xsi | |
1819 | '; | |
1820 | } | |
1821 | ||
1822 | 1; | |
1823 | ||
1824 | __END__ |