blib/lib/DBI/DBD.pm untested

filter: Statementstmt 0.0% 0 / 140 Branchbran 0.0% 0 / 40 Conditioncond 0.0% 0 / 40 MC/DCmcdc 0.0% 0 / 23 Subroutinesub 0.0% 0 / 18 Podpod 0.0% 0 / 7 totaltotal 0.0% 0 / 268 CC 21 SCAR 36.1
CC
21
Cov
0%
dbd_edit_mm_attribs
110.0
_inst_checks
30.0
dbd_dbi_arch_dir
20.0
CRAP 36.8
1 package DBI::DBD;
2 # vim:ts=8:sw=4
3 use strict;
4 use warnings;
5  
6 # set $VERSION early so we don't confuse PAUSE/CPAN etc
7 # don't use Revision here because that's not in svn:keywords so that the
8 # examples that use it below won't be messed up
9 our $VERSION = "12.015129";
10  
11 # $Id: DBD.pm 15128 2012-02-04 20:51:39Z Tim $
12 #
13 # Copyright (c) 1997-2006 Jonathan Leffler, Jochen Wiedmann, Steffen
14 # Goeldner and Tim Bunce
15 #
16 # You may distribute under the terms of either the GNU General Public
17 # License or the Artistic License, as specified in the Perl README file.
18  
19 =head1 NAME
20  
21 DBI::DBD - Perl DBI Database Driver Writer's Guide
22  
23 =head1 SYNOPSIS
24  
25 perldoc DBI::DBD
26  
27 =head2 Version and volatility
28  
29 This document is I<still> a minimal draft which is in need of further work.
30  
31 Please read the B<DBI> documentation first and fully. Then look at the
32 implementation of some high-profile and regularly maintained drivers like
33 DBD::Oracle, DBD::ODBC, DBD::Pg etc. (Those are in no particular order.)
34  
35 Then reread the B<DBI> specification and the code of those drivers again as
36 you're reading this. It'll help. Where this document and the driver code
37 differ it's likely that the driver code is more correct, especially if multiple
38 drivers do the same thing.
39  
40 This document is a patchwork of contributions from various authors.
41 More contributions (preferably as patches) are very welcome.
42  
43 =head1 DESCRIPTION
44  
45 This document is primarily intended to help people writing new
46 database drivers for the Perl Database Interface (Perl DBI).
47 It may also help others interested in discovering why the internals of
48 a B<DBD> driver are written the way they are.
49  
50 This is a guide. Few (if any) of the statements in it are completely
51 authoritative under all possible circumstances. This means you will
52 need to use judgement in applying the guidelines in this document.
53 If in I<any> doubt at all, please do contact the I<dbi-dev> mailing list
54 (details given below) where Tim Bunce and other driver authors can help.
55  
56 =head1 CREATING A NEW DRIVER
57  
58 The first rule for creating a new database driver for the Perl DBI is
59 very simple: B<DON'T!>
60  
61 There is usually a driver already available for the database you want
62 to use, almost regardless of which database you choose. Very often, the
63 database will provide an ODBC driver interface, so you can often use
64 B<DBD::ODBC> to access the database. This is typically less convenient
65 on a Unix box than on a Microsoft Windows box, but there are numerous
66 options for ODBC driver managers on Unix too, and very often the ODBC
67 driver is provided by the database supplier.
68  
69 Before deciding that you need to write a driver, do your homework to
70 ensure that you are not wasting your energies.
71  
72 [As of December 2002, the consensus is that if you need an ODBC driver
73 manager on Unix, then the unixODBC driver (available from
74 L<http://www.unixodbc.org/>) is the way to go.]
75  
76 The second rule for creating a new database driver for the Perl DBI is
77 also very simple: B<Don't -- get someone else to do it for you!>
78  
79 Nevertheless, there are occasions when it is necessary to write a new
80 driver, often to use a proprietary language or API to access the
81 database more swiftly, or more comprehensively, than an ODBC driver can.
82 Then you should read this document very carefully, but with a suitably
83 sceptical eye.
84  
85 If there is something in here that does not make any sense, question it.
86 You might be right that the information is bogus, but don't come to that
87 conclusion too quickly.
88  
89 =head2 URLs and mailing lists
90  
91 The primary web-site for locating B<DBI> software and information is
92  
93 http://dbi.perl.org/
94  
95 There are two main and one auxiliary mailing lists for people working
96 with B<DBI>. The primary lists are I<dbi-users@perl.org> for general users
97 of B<DBI> and B<DBD> drivers, and I<dbi-dev@perl.org> mainly for B<DBD> driver
98 writers (don't join the I<dbi-dev> list unless you have a good reason).
99 The auxiliary list is I<dbi-announce@perl.org> for announcing new
100 releases of B<DBI> or B<DBD> drivers.
101  
102 You can join these lists by accessing the web-site L<http://dbi.perl.org/>.
103 The lists are closed so you cannot send email to any of the lists
104 unless you join the list first.
105  
106 You should also consider monitoring the I<comp.lang.perl.*> newsgroups,
107 especially I<comp.lang.perl.modules>.
108  
109 =head2 The Cheetah book
110  
111 The definitive book on Perl DBI is the Cheetah book, so called because
112 of the picture on the cover. Its proper title is 'I<Programming the
113 Perl DBI: Database programming with Perl>' by Alligator Descartes
114 and Tim Bunce, published by O'Reilly Associates, February 2000, ISBN
115 1-56592-699-4. Buy it now if you have not already done so, and read it.
116  
117 =head2 Locating drivers
118  
119 Before writing a new driver, it is in your interests to find out
120 whether there already is a driver for your database. If there is such
121 a driver, it would be much easier to make use of it than to write your
122 own!
123  
124 The primary web-site for locating Perl software is
125 L<http://search.cpan.org/>. You should look under the various
126 modules listings for the software you are after. For example:
127  
128 http://search.cpan.org/modlist/Database_Interfaces
129  
130 Follow the B<DBD::> and B<DBIx::> links at the top to see those subsets.
131  
132 See the B<DBI> docs for information on B<DBI> web sites and mailing lists.
133  
134 =head2 Registering a new driver
135  
136 Before going through any official registration process, you will need
137 to establish that there is no driver already in the works. You'll do
138 that by asking the B<DBI> mailing lists whether there is such a driver
139 available, or whether anybody is working on one.
140  
141 When you get the go ahead, you will need to establish the name of the
142 driver and a prefix for the driver. Typically, the name is based on the
143 name of the database software it uses, and the prefix is a contraction
144 of that. Hence, B<DBD::Oracle> has the name I<Oracle> and the prefix
145 'I<ora_>'. The prefix must be lowercase and contain no underscores other
146 than the one at the end.
147  
148 This information will be recorded in the B<DBI> module. Apart from
149 documentation purposes, registration is a prerequisite for
150 L<installing private methods|DBI/install_method>.
151  
152 If you are writing a driver which will not be distributed on CPAN, then
153 you should choose a prefix beginning with 'I<x_>', to avoid potential
154 prefix collisions with drivers registered in the future. Thus, if you
155 wrote a non-CPAN distributed driver called B<DBD::CustomDB>, the prefix
156 might be 'I<x_cdb_>'.
157  
158 This document assumes you are writing a driver called B<DBD::Driver>, and
159 that the prefix 'I<drv_>' is assigned to the driver.
160  
161 =head2 Two styles of database driver
162  
163 There are two distinct styles of database driver that can be written to
164 work with the Perl DBI.
165  
166 Your driver can be written in pure Perl, requiring no C compiler.
167 When feasible, this is the best solution, but most databases are not
168 written in such a way that this can be done. Some examples of pure
169 Perl drivers are B<DBD::File> and B<DBD::CSV>.
170  
171 Alternatively, and most commonly, your driver will need to use some C
172 code to gain access to the database. This will be classified as a C/XS
173 driver.
174  
175 =head2 What code will you write?
176  
177 There are a number of files that need to be written for either a pure
178 Perl driver or a C/XS driver. There are no extra files needed only by
179 a pure Perl driver, but there are several extra files needed only by a
180 C/XS driver.
181  
182 =head3 Files common to pure Perl and C/XS drivers
183  
184 Assuming that your driver is called B<DBD::Driver>, these files are:
185  
186 =over 4
187  
188 =item * F<Makefile.PL>
189  
190 =item * F<META.yml>
191  
192 =item * F<README>
193  
194 =item * F<MANIFEST>
195  
196 =item * F<Driver.pm>
197  
198 =item * F<lib/Bundle/DBD/Driver.pm>
199  
200 =item * F<lib/DBD/Driver/Summary.pm>
201  
202 =item * F<t/*.t>
203  
204 =back
205  
206 The first four files are mandatory. F<Makefile.PL> is used to control
207 how the driver is built and installed. The F<README> file tells people
208 who download the file about how to build the module and any prerequisite
209 software that must be installed. The F<MANIFEST> file is used by the
210 standard Perl module distribution mechanism. It lists all the source
211 files that need to be distributed with your module. F<Driver.pm> is what
212 is loaded by the B<DBI> code; it contains the methods peculiar to your
213 driver.
214  
215 Although the F<META.yml> file is not B<required> you are advised to
216 create one. Of particular importance are the I<build_requires> and
217 I<configure_requires> attributes which newer CPAN modules understand.
218 You use these to tell the CPAN module (and CPANPLUS) that your build
219 and configure mechanisms require DBI. The best reference for META.yml
220 (at the time of writing) is
221 L<http://module-build.sourceforge.net/META-spec-v1.4.html>. You can find
222 a reasonable example of a F<META.yml> in DBD::ODBC.
223  
224 The F<lib/Bundle/DBD/Driver.pm> file allows you to specify other Perl
225 modules on which yours depends in a format that allows someone to type a
226 simple command and ensure that all the pre-requisites are in place as
227 well as building your driver.
228  
229 The F<lib/DBD/Driver/Summary.pm> file contains (an updated version of) the
230 information that was included - or that would have been included - in
231 the appendices of the Cheetah book as a summary of the abilities of your
232 driver and the associated database.
233  
234 The files in the F<t> subdirectory are unit tests for your driver.
235 You should write your tests as stringently as possible, while taking
236 into account the diversity of installations that you can encounter:
237  
238 =over 4
239  
240 =item *
241  
242 Your tests should not casually modify operational databases.
243  
244 =item *
245  
246 You should never damage existing tables in a database.
247  
248 =item *
249  
250 You should code your tests to use a constrained name space within the
251 database. For example, the tables (and all other named objects) that are
252 created could all begin with 'I<dbd_drv_>'.
253  
254 =item *
255  
256 At the end of a test run, there should be no testing objects left behind
257 in the database.
258  
259 =item *
260  
261 If you create any databases, you should remove them.
262  
263 =item *
264  
265 If your database supports temporary tables that are automatically
266 removed at the end of a session, then exploit them as often as possible.
267  
268 =item *
269  
270 Try to make your tests independent of each other. If you have a
271 test F<t/t11dowhat.t> that depends upon the successful running
272 of F<t/t10thingamy.t>, people cannot run the single test case
273 F<t/t11dowhat.t>. Further, running F<t/t11dowhat.t> twice in a row is
274 likely to fail (at least, if F<t/t11dowhat.t> modifies the database at
275 all) because the database at the start of the second run is not what you
276 saw at the start of the first run.
277  
278 =item *
279  
280 Document in your F<README> file what you do, and what privileges people
281 need to do it.
282  
283 =item *
284  
285 You can, and probably should, sequence your tests by including a test
286 number before an abbreviated version of the test name; the tests are run
287 in the order in which the names are expanded by shell-style globbing.
288  
289 =item *
290  
291 It is in your interests to ensure that your tests work as widely
292 as possible.
293  
294 =back
295  
296 Many drivers also install sub-modules B<DBD::Driver::SubModule>
297 for any of a variety of different reasons, such as to support
298 the metadata methods (see the discussion of L</METADATA METHODS>
299 below). Such sub-modules are conventionally stored in the directory
300 F<lib/DBD/Driver>. The module itself would usually be in a file
301 F<SubModule.pm>. All such sub-modules should themselves be version
302 stamped (see the discussions far below).
303  
304 =head3 Extra files needed by C/XS drivers
305  
306 The software for a C/XS driver will typically contain at least four
307 extra files that are not relevant to a pure Perl driver.
308  
309 =over 4
310  
311 =item * F<Driver.xs>
312  
313 =item * F<Driver.h>
314  
315 =item * F<dbdimp.h>
316  
317 =item * F<dbdimp.c>
318  
319 =back
320  
321 The F<Driver.xs> file is used to generate C code that Perl can call to gain
322 access to the C functions you write that will, in turn, call down onto
323 your database software.
324  
325 The F<Driver.h> header is a stylized header that ensures you can access the
326 necessary Perl and B<DBI> macros, types, and function declarations.
327  
328 The F<dbdimp.h> is used to specify which functions have been implemented by
329 your driver.
330  
331 The F<dbdimp.c> file is where you write the C code that does the real work
332 of translating between Perl-ish data types and what the database expects
333 to use and return.
334  
335 There are some (mainly small, but very important) differences between
336 the contents of F<Makefile.PL> and F<Driver.pm> for pure Perl and C/XS
337 drivers, so those files are described both in the section on creating a
338 pure Perl driver and in the section on creating a C/XS driver.
339  
340 Obviously, you can add extra source code files to the list.
341  
342 =head2 Requirements on a driver and driver writer
343  
344 To be remotely useful, your driver must be implemented in a format that
345 allows it to be distributed via CPAN, the Comprehensive Perl Archive
346 Network (L<http://www.cpan.org/> and L<http://search.cpan.org>).
347 Of course, it is easier if you do not have to meet this criterion, but
348 you will not be able to ask for much help if you do not do so, and
349 no-one is likely to want to install your module if they have to learn a
350 new installation mechanism.
351  
352 =head1 CREATING A PURE PERL DRIVER
353  
354 Writing a pure Perl driver is surprisingly simple. However, there are
355 some problems you should be aware of. The best option is of course
356 picking up an existing driver and carefully modifying one method
357 after the other.
358  
359 Also look carefully at B<DBD::AnyData> and B<DBD::Template>.
360  
361 As an example we take a look at the B<DBD::File> driver, a driver for
362 accessing plain files as tables, which is part of the B<DBD::CSV> package.
363  
364 The minimal set of files we have to implement are F<Makefile.PL>,
365 F<README>, F<MANIFEST> and F<Driver.pm>.
366  
367 =head2 Pure Perl version of Makefile.PL
368  
369 You typically start with writing F<Makefile.PL>, a Makefile
370 generator. The contents of this file are described in detail in
371 the L<ExtUtils::MakeMaker> man pages. It is definitely a good idea
372 if you start reading them. At least you should know about the
373 variables I<CONFIGURE>, I<DEFINED>, I<PM>, I<DIR>, I<EXE_FILES>,
374 I<INC>, I<LIBS>, I<LINKTYPE>, I<NAME>, I<OPTIMIZE>, I<PL_FILES>,
375 I<VERSION>, I<VERSION_FROM>, I<clean>, I<depend>, I<realclean> from
376 the L<ExtUtils::MakeMaker> man page: these are used in almost any
377 F<Makefile.PL>.
378  
379 Additionally read the section on I<Overriding MakeMaker Methods> and the
380 descriptions of the I<distcheck>, I<disttest> and I<dist> targets: They
381 will definitely be useful for you.
382  
383 Of special importance for B<DBI> drivers is the I<postamble> method from
384 the L<ExtUtils::MM_Unix> man page.
385  
386 For Emacs users, I recommend the I<libscan> method, which removes
387 Emacs backup files (file names which end with a tilde '~') from lists of
388 files.
389  
390 Now an example, I use the word C<Driver> wherever you should insert
391 your driver's name:
392  
393 # -*- perl -*-
394  
395 use ExtUtils::MakeMaker;
396  
397 WriteMakefile(
398 dbd_edit_mm_attribs( {
399 'NAME' => 'DBD::Driver',
400 'VERSION_FROM' => 'Driver.pm',
401 'INC' => '',
402 'dist' => { 'SUFFIX' => '.gz',
403 'COMPRESS' => 'gzip -9f' },
404 'realclean' => { FILES => '*.xsi' },
405 'PREREQ_PM' => '1.03',
406 'CONFIGURE' => sub {
407 eval {require DBI::DBD;};
408 if ($@) {
409 warn $@;
410 exit 0;
411 }
412 my $dbi_arch_dir = dbd_dbi_arch_dir();
413 if (exists($opts{INC})) {
414 return {INC => "$opts{INC} -I$dbi_arch_dir"};
415 } else {
416 return {INC => "-I$dbi_arch_dir"};
417 }
418 }
419 },
420 { create_pp_tests => 1})
421 );
422  
423 package MY;
424 sub postamble { return main::dbd_postamble(@_); }
425 sub libscan {
426 my ($self, $path) = @_;
427 ($path =~ m/\~$/) ? undef : $path;
428 }
429  
430 Note the calls to C<dbd_edit_mm_attribs()> and C<dbd_postamble()>.
431  
432 The second hash reference in the call to C<dbd_edit_mm_attribs()>
433 (containing C<create_pp_tests()>) is optional; you should not use it
434 unless your driver is a pure Perl driver (that is, it does not use C and
435 XS code). Therefore, the call to C<dbd_edit_mm_attribs()> is not
436 relevant for C/XS drivers and may be omitted; simply use the (single)
437 hash reference containing NAME etc as the only argument to C<WriteMakefile()>.
438  
439 Note that the C<dbd_edit_mm_attribs()> code will fail if you do not have a
440 F<t> sub-directory containing at least one test case.
441  
442 I<PREREQ_PM> tells MakeMaker that DBI (version 1.03 in this case) is
443 required for this module. This will issue a warning that DBI 1.03 is
444 missing if someone attempts to install your DBD without DBI 1.03. See
445 I<CONFIGURE> below for why this does not work reliably in stopping cpan
446 testers failing your module if DBI is not installed.
447  
448 I<CONFIGURE> is a subroutine called by MakeMaker during
449 C<WriteMakefile>. By putting the C<require DBI::DBD> in this section
450 we can attempt to load DBI::DBD but if it is missing we exit with
451 success. As we exit successfully without creating a Makefile when
452 DBI::DBD is missing cpan testers will not report a failure. This may
453 seem at odds with I<PREREQ_PM> but I<PREREQ_PM> does not cause
454 C<WriteMakefile> to fail (unless you also specify PREREQ_FATAL which
455 is strongly discouraged by MakeMaker) so C<WriteMakefile> would
456 continue to call C<dbd_dbi_arch_dir> and fail.
457  
458 All drivers must use C<dbd_postamble()> or risk running into problems.
459  
460 Note the specification of I<VERSION_FROM>; the named file
461 (F<Driver.pm>) will be scanned for the first line that looks like an
462 assignment to I<$VERSION>, and the subsequent text will be used to
463 determine the version number. Note the commentary in
464 L<ExtUtils::MakeMaker> on the subject of correctly formatted version
465 numbers.
466  
467 If your driver depends upon external software (it usually will), you
468 will need to add code to ensure that your environment is workable
469 before the call to C<WriteMakefile()>. If you need to check for the
470 existence of an external library and perhaps modify I<INC> to include
471 the paths to where the external library header files are located and
472 you cannot find the library or header files make sure you output a
473 message saying they cannot be found but C<exit 0> (success) B<before>
474 calling C<WriteMakefile> or CPAN testers will fail your module if the
475 external library is not found.
476  
477 A full-fledged I<Makefile.PL> can be quite large (for example, the
478 files for B<DBD::Oracle> and B<DBD::Informix> are both over 1000 lines
479 long, and the Informix one uses - and creates - auxiliary modules
480 too).
481  
482 See also L<ExtUtils::MakeMaker> and L<ExtUtils::MM_Unix>. Consider using
483 L<CPAN::MakeMaker> in place of I<ExtUtils::MakeMaker>.
484  
485 =head2 README
486  
487 The L<README> file should describe what the driver is for, the
488 pre-requisites for the build process, the actual build process, how to
489 report errors, and who to report them to.
490  
491 Users will find ways of breaking the driver build and test process
492 which you would never even have dreamed to be possible in your worst
493 nightmares. Therefore, you need to write this document defensively,
494 precisely and concisely.
495  
496 As always, use the F<README> from one of the established drivers as a basis
497 for your own; the version in B<DBD::Informix> is worth a look as it has
498 been quite successful in heading off problems.
499  
500 =over 4
501  
502 =item *
503  
504 Note that users will have versions of Perl and B<DBI> that are both older
505 and newer than you expected, but this will seldom cause much trouble.
506 When it does, it will be because you are using features of B<DBI> that are
507 not supported in the version they are using.
508  
509 =item *
510  
511 Note that users will have versions of the database software that are
512 both older and newer than you expected. You will save yourself time in
513 the long run if you can identify the range of versions which have been
514 tested and warn about versions which are not known to be OK.
515  
516 =item *
517  
518 Note that many people trying to install your driver will not be experts
519 in the database software.
520  
521 =item *
522  
523 Note that many people trying to install your driver will not be experts
524 in C or Perl.
525  
526 =back
527  
528 =head2 MANIFEST
529  
530 The F<MANIFEST> will be used by the Makefile's dist target to build the
531 distribution tar file that is uploaded to CPAN. It should list every
532 file that you want to include in your distribution, one per line.
533  
534 =head2 lib/Bundle/DBD/Driver.pm
535  
536 The CPAN module provides an extremely powerful bundle mechanism that
537 allows you to specify pre-requisites for your driver.
538  
539 The primary pre-requisite is B<Bundle::DBI>; you may want or need to add
540 some more. With the bundle set up correctly, the user can type:
541  
542 perl -MCPAN -e 'install Bundle::DBD::Driver'
543  
544 and Perl will download, compile, test and install all the Perl modules
545 needed to build your driver.
546  
547 The prerequisite modules are listed in the C<CONTENTS> section, with the
548 official name of the module followed by a dash and an informal name or
549 description.
550  
551 =over 4
552  
553 =item *
554  
555 Listing B<Bundle::DBI> as the main pre-requisite simplifies life.
556  
557 =item *
558  
559 Don't forget to list your driver.
560  
561 =item *
562  
563 Note that unless the DBMS is itself a Perl module, you cannot list it as
564 a pre-requisite in this file.
565  
566 =item *
567  
568 You should keep the version of the bundle the same as the version of
569 your driver.
570  
571 =item *
572  
573 You should add configuration management, copyright, and licensing
574 information at the top.
575  
576 =back
577  
578 A suitable skeleton for this file is shown below.
579  
580 package Bundle::DBD::Driver;
581  
582 $VERSION = '0.01';
583  
584 1;
585  
586 __END__
587  
588 =head1 NAME
589  
590 Bundle::DBD::Driver - A bundle to install all DBD::Driver related modules
591  
592 =head1 SYNOPSIS
593  
594 C<perl -MCPAN -e 'install Bundle::DBD::Driver'>
595  
596 =head1 CONTENTS
597  
598 Bundle::DBI - Bundle for DBI by TIMB (Tim Bunce)
599  
600 DBD::Driver - DBD::Driver by YOU (Your Name)
601  
602 =head1 DESCRIPTION
603  
604 This bundle includes all the modules used by the Perl Database
605 Interface (DBI) driver for Driver (DBD::Driver), assuming the
606 use of DBI version 1.13 or later, created by Tim Bunce.
607  
608 If you've not previously used the CPAN module to install any
609 bundles, you will be interrogated during its setup phase.
610 But when you've done it once, it remembers what you told it.
611 You could start by running:
612  
613 C<perl -MCPAN -e 'install Bundle::CPAN'>
614  
615 =head1 SEE ALSO
616  
617 Bundle::DBI
618  
619 =head1 AUTHOR
620  
621 Your Name E<lt>F<you@yourdomain.com>E<gt>
622  
623 =head1 THANKS
624  
625 This bundle was created by ripping off Bundle::libnet created by
626 Graham Barr E<lt>F<gbarr@ti.com>E<gt>, and radically simplified
627 with some information from Jochen Wiedmann E<lt>F<joe@ispsoft.de>E<gt>.
628 The template was then included in the DBI::DBD documentation by
629 Jonathan Leffler E<lt>F<jleffler@informix.com>E<gt>.
630  
631 =cut
632  
633 =head2 lib/DBD/Driver/Summary.pm
634  
635 There is no substitute for taking the summary file from a driver that
636 was documented in the Perl book (such as B<DBD::Oracle> or B<DBD::Informix> or
637 B<DBD::ODBC>, to name but three), and adapting it to describe the
638 facilities available via B<DBD::Driver> when accessing the Driver database.
639  
640 =head2 Pure Perl version of Driver.pm
641  
642 The F<Driver.pm> file defines the Perl module B<DBD::Driver> for your driver.
643 It will define a package B<DBD::Driver> along with some version information,
644 some variable definitions, and a function C<driver()> which will have a more
645 or less standard structure.
646  
647 It will also define three sub-packages of B<DBD::Driver>:
648  
649 =over 4
650  
651 =item DBD::Driver::dr
652  
653 with methods C<connect()>, C<data_sources()> and C<disconnect_all()>;
654  
655 =item DBD::Driver::db
656  
657 with methods such as C<prepare()>;
658  
659 =item DBD::Driver::st
660  
661 with methods such as C<execute()> and C<fetch()>.
662  
663 =back
664  
665 The F<Driver.pm> file will also contain the documentation specific to
666 B<DBD::Driver> in the format used by perldoc.
667  
668 In a pure Perl driver, the F<Driver.pm> file is the core of the
669 implementation. You will need to provide all the key methods needed by B<DBI>.
670  
671 Now let's take a closer look at an excerpt of F<File.pm> as an example.
672 We ignore things that are common to any module (even non-DBI modules)
673 or really specific to the B<DBD::File> package.
674  
675 =head3 The DBD::Driver package
676  
677 =head4 The header
678  
679 package DBD::File;
680  
681 use strict;
682  
683 our $VERSION = "1.23.00" # Version number of DBD::File
684  
685 This is where the version number of your driver is specified, and is
686 where F<Makefile.PL> looks for this information. Please ensure that any
687 other modules added with your driver are also version stamped so that
688 CPAN does not get confused.
689  
690 It is recommended that you use a two-part (1.23) or three-part (1.23.45)
691 version number. Also consider the CPAN system, which gets confused and
692 considers version 1.10 to precede version 1.9, so that using a raw CVS,
693 RCS or SCCS version number is probably not appropriate (despite being
694 very common).
695  
696 For Subversion you could use:
697  
698 our $VERSION = "12.012346";
699  
700 (use lots of leading zeros on the second portion so if you move the code to a
701 shared repository like svn.perl.org the much larger revision numbers won't
702 cause a problem, at least not for a few years). For RCS or CVS you can use:
703  
704 our $VERSION = "11.22";
705  
706 which pads out the fractional part with leading zeros so all is well
707 (so long as you don't go past x.99)
708  
709 our $drh = undef; # holds driver handle once initialized
710  
711 This is where the driver handle will be stored, once created.
712 Note that you may assume there is only one handle for your driver.
713  
714 =head4 The driver constructor
715  
716 The C<driver()> method is the driver handle constructor. Note that
717 the C<driver()> method is in the B<DBD::Driver> package, not in
718 one of the sub-packages B<DBD::Driver::dr>, B<DBD::Driver::db>, or
719 B<DBD::Driver::db>.
720  
721 sub driver
722 {
723 return $drh if $drh; # already created - return same one
724 my ($class, $attr) = @_;
725  
726 $class .= "::dr";
727  
728 DBD::Driver::db->install_method('drv_example_dbh_method');
729 DBD::Driver::st->install_method('drv_example_sth_method');
730  
731 # not a 'my' since we use it above to prevent multiple drivers
732 $drh = DBI::_new_drh($class, {
733 'Name' => 'File',
734 'Version' => $VERSION,
735 'Attribution' => 'DBD::File by Jochen Wiedmann',
736 })
737 or return undef;
738  
739 return $drh;
740 }
741  
742 This is a reasonable example of how B<DBI> implements its handles. There
743 are three kinds: B<driver handles> (typically stored in I<$drh>; from
744 now on called I<drh> or I<$drh>), B<database handles> (from now on
745 called I<dbh> or I<$dbh>) and B<statement handles> (from now on called
746 I<sth> or I<$sth>).
747  
748 The prototype of C<DBI::_new_drh()> is
749  
750 $drh = DBI::_new_drh($class, $public_attrs, $private_attrs);
751  
752 with the following arguments:
753  
754 =over 4
755  
756 =item I<$class>
757  
758 is typically the class for your driver, (for example, "DBD::File::dr"),
759 passed as the first argument to the C<driver()> method.
760  
761 =item I<$public_attrs>
762  
763 is a hash ref to attributes like I<Name>, I<Version>, and I<Attribution>.
764 These are processed and used by B<DBI>. You had better not make any
765 assumptions about them nor should you add private attributes here.
766  
767 =item I<$private_attrs>
768  
769 This is another (optional) hash ref with your private attributes.
770 B<DBI> will store them and otherwise leave them alone.
771  
772 =back
773  
774 The C<DBI::_new_drh()> method and the C<driver()> method both return C<undef>
775 for failure (in which case you must look at I<$DBI::err> and I<$DBI::errstr>
776 for the failure information, because you have no driver handle to use).
777  
778  
779 =head4 Using install_method() to expose driver-private methods
780  
781 DBD::Foo::db->install_method($method_name, \%attr);
782  
783 Installs the driver-private method named by $method_name into the
784 DBI method dispatcher so it can be called directly, avoiding the
785 need to use the func() method.
786  
787 It is called as a static method on the driver class to which the
788 method belongs. The method name must begin with the corresponding
789 registered driver-private prefix. For example, for DBD::Oracle
790 $method_name must being with 'C<ora_>', and for DBD::AnyData it
791 must begin with 'C<ad_>'.
792  
793 The C<\%attr> attributes can be used to provide fine control over how the DBI
794 dispatcher handles the dispatching of the method. However it's undocumented
795 at the moment. See the IMA_* #define's in DBI.xs and the O=>0x000x values in
796 the initialization of %DBI::DBI_methods in DBI.pm. (Volunteers to polish up
797 and document the interface are very welcome to get in touch via dbi-dev@perl.org).
798  
799 Methods installed using install_method default to the standard error
800 handling behaviour for DBI methods: clearing err and errstr before
801 calling the method, and checking for errors to trigger RaiseError
802 etc. on return. This differs from the default behaviour of func().
803  
804 Note for driver authors: The DBD::Foo::xx->install_method call won't
805 work until the class-hierarchy has been setup. Normally the DBI
806 looks after that just after the driver is loaded. This means
807 install_method() can't be called at the time the driver is loaded
808 unless the class-hierarchy is set up first. The way to do that is
809 to call the setup_driver() method:
810  
811 DBI->setup_driver('DBD::Foo');
812  
813 before using install_method().
814  
815  
816 =head4 The CLONE special subroutine
817  
818 Also needed here, in the B<DBD::Driver> package, is a C<CLONE()> method
819 that will be called by perl when an interpreter is cloned. All your
820 C<CLONE()> method needs to do, currently, is clear the cached I<$drh> so
821 the new interpreter won't start using the cached I<$drh> from the old
822 interpreter:
823  
824 sub CLONE {
825 undef $drh;
826 }
827  
828 See L<http://search.cpan.org/dist/perl/pod/perlmod.pod#Making_your_module_threadsafe>
829 for details.
830  
831 =head3 The DBD::Driver::dr package
832  
833 The next lines of code look as follows:
834  
835 package DBD::Driver::dr; # ====== DRIVER ======
836  
837 $DBD::Driver::dr::imp_data_size = 0;
838  
839 Note that no I<@ISA> is needed here, or for the other B<DBD::Driver::*>
840 classes, because the B<DBI> takes care of that for you when the driver is
841 loaded.
842  
843 *FIX ME* Explain what the imp_data_size is, so that implementors aren't
844 practicing cargo-cult programming.
845  
846 =head4 The database handle constructor
847  
848 The database handle constructor is the driver's (hence the changed
849 namespace) C<connect()> method:
850  
851 sub connect
852 {
853 my ($drh, $dr_dsn, $user, $auth, $attr) = @_;
854  
855 # Some database specific verifications, default settings
856 # and the like can go here. This should only include
857 # syntax checks or similar stuff where it's legal to
858 # 'die' in case of errors.
859 # For example, many database packages requires specific
860 # environment variables to be set; this could be where you
861 # validate that they are set, or default them if they are not set.
862  
863 my $driver_prefix = "drv_"; # the assigned prefix for this driver
864  
865 # Process attributes from the DSN; we assume ODBC syntax
866 # here, that is, the DSN looks like var1=val1;...;varN=valN
867 foreach my $var ( split /;/, $dr_dsn ) {
868 my ($attr_name, $attr_value) = split '=', $var, 2;
869 return $drh->set_err($DBI::stderr, "Can't parse DSN part '$var'")
870 unless defined $attr_value;
871  
872 # add driver prefix to attribute name if it doesn't have it already
873 $attr_name = $driver_prefix.$attr_name
874 unless $attr_name =~ /^$driver_prefix/o;
875  
876 # Store attribute into %$attr, replacing any existing value.
877 # The DBI will STORE() these into $dbh after we've connected
878 $attr->{$attr_name} = $attr_value;
879 }
880  
881 # Get the attributes we'll use to connect.
882 # We use delete here because these no need to STORE them
883 my $db = delete $attr->{drv_database} || delete $attr->{drv_db}
884 or return $drh->set_err($DBI::stderr, "No database name given in DSN '$dr_dsn'");
885 my $host = delete $attr->{drv_host} || 'localhost';
886 my $port = delete $attr->{drv_port} || 123456;
887  
888 # Assume you can attach to your database via drv_connect:
889 my $connection = drv_connect($db, $host, $port, $user, $auth)
890 or return $drh->set_err($DBI::stderr, "Can't connect to $dr_dsn: ...");
891  
892 # create a 'blank' dbh (call superclass constructor)
893 my ($outer, $dbh) = DBI::_new_dbh($drh, { Name => $dr_dsn });
894  
895 $dbh->STORE('Active', 1 );
896 $dbh->{drv_connection} = $connection;
897  
898 return $outer;
899 }
900  
901 This is mostly the same as in the I<driver handle constructor> above.
902 The arguments are described in L<DBI>.
903  
904 The constructor C<DBI::_new_dbh()> is called, returning a database handle.
905 The constructor's prototype is:
906  
907 ($outer, $inner) = DBI::_new_dbh($drh, $public_attr, $private_attr);
908  
909 with similar arguments to those in the I<driver handle constructor>,
910 except that the I<$class> is replaced by I<$drh>. The I<Name> attribute
911 is a standard B<DBI> attribute (see L<DBI/Database Handle Attributes>).
912  
913 In scalar context, only the outer handle is returned.
914  
915 Note the use of the C<STORE()> method for setting the I<dbh> attributes.
916 That's because within the driver code, the handle object you have is
917 the 'inner' handle of a tied hash, not the outer handle that the
918 users of your driver have.
919  
920 Because you have the inner handle, tie magic doesn't get invoked
921 when you get or set values in the hash. This is often very handy for
922 speed when you want to get or set simple non-special driver-specific
923 attributes.
924  
925 However, some attribute values, such as those handled by the B<DBI> like
926 I<PrintError>, don't actually exist in the hash and must be read via
927 C<$h-E<gt>FETCH($attrib)> and set via C<$h-E<gt>STORE($attrib, $value)>.
928 If in any doubt, use these methods.
929  
930 =head4 The data_sources() method
931  
932 The C<data_sources()> method must populate and return a list of valid data
933 sources, prefixed with the "I<dbi:Driver>" incantation that allows them to
934 be used in the first argument of the C<DBI-E<gt>connect()> method.
935 An example of this might be scanning the F<$HOME/.odbcini> file on Unix
936 for ODBC data sources (DSNs).
937  
938 As a trivial example, consider a fixed list of data sources:
939  
940 sub data_sources
941 {
942 my($drh, $attr) = @_;
943 my(@list) = ();
944 # You need more sophisticated code than this to set @list...
945 push @list, "dbi:Driver:abc";
946 push @list, "dbi:Driver:def";
947 push @list, "dbi:Driver:ghi";
948 # End of code to set @list
949 return @list;
950 }
951  
952 =head4 The disconnect_all() method
953  
954 If you need to release any resources when the driver is unloaded, you
955 can provide a disconnect_all method.
956  
957 =head4 Other driver handle methods
958  
959 If you need any other driver handle methods, they can follow here.
960  
961 =head4 Error handling
962  
963 It is quite likely that something fails in the connect method.
964 With B<DBD::File> for example, you might catch an error when setting the
965 current directory to something not existent by using the
966 (driver-specific) I<f_dir> attribute.
967  
968 To report an error, you use the C<set_err()> method:
969  
970 $h->set_err($err, $errmsg, $state);
971  
972 This will ensure that the error is recorded correctly and that
973 I<RaiseError> and I<PrintError> etc are handled correctly.
974  
975 Typically you'll always use the method instance, aka your method's first
976 argument.
977  
978 As C<set_err()> always returns C<undef> your error handling code can
979 usually be simplified to something like this:
980  
981 return $h->set_err($err, $errmsg, $state) if ...;
982  
983 =head3 The DBD::Driver::db package
984  
985 package DBD::Driver::db; # ====== DATABASE ======
986  
987 $DBD::Driver::db::imp_data_size = 0;
988  
989 =head4 The statement handle constructor
990  
991 There's nothing much new in the statement handle constructor, which
992 is the C<prepare()> method:
993  
994 sub prepare
995 {
996 my ($dbh, $statement, @attribs) = @_;
997  
998 # create a 'blank' sth
999 my ($outer, $sth) = DBI::_new_sth($dbh, { Statement => $statement });
1000  
1001 $sth->STORE('NUM_OF_PARAMS', ($statement =~ tr/?//));
1002  
1003 $sth->{drv_params} = [];
1004  
1005 return $outer;
1006 }
1007  
1008 This is still the same -- check the arguments and call the super class
1009 constructor C<DBI::_new_sth()>. Again, in scalar context, only the outer
1010 handle is returned. The I<Statement> attribute should be cached as
1011 shown.
1012  
1013 Note the prefix I<drv_> in the attribute names: it is required that
1014 all your private attributes use a lowercase prefix unique to your driver.
1015 As mentioned earlier in this document, the B<DBI> contains a registry of
1016 known driver prefixes and may one day warn about unknown attributes
1017 that don't have a registered prefix.
1018  
1019 Note that we parse the statement here in order to set the attribute
1020 I<NUM_OF_PARAMS>. The technique illustrated is not very reliable; it can
1021 be confused by question marks appearing in quoted strings, delimited
1022 identifiers or in SQL comments that are part of the SQL statement. We
1023 could set I<NUM_OF_PARAMS> in the C<execute()> method instead because
1024 the B<DBI> specification explicitly allows a driver to defer this, but then
1025 the user could not call C<bind_param()>.
1026  
1027 =head4 Transaction handling
1028  
1029 Pure Perl drivers will rarely support transactions. Thus your C<commit()>
1030 and C<rollback()> methods will typically be quite simple:
1031  
1032 sub commit
1033 {
1034 my ($dbh) = @_;
1035 if ($dbh->FETCH('Warn')) {
1036 warn("Commit ineffective while AutoCommit is on");
1037 }
1038 0;
1039 }
1040  
1041 sub rollback {
1042 my ($dbh) = @_;
1043 if ($dbh->FETCH('Warn')) {
1044 warn("Rollback ineffective while AutoCommit is on");
1045 }
1046 0;
1047 }
1048  
1049 Or even simpler, just use the default methods provided by the B<DBI> that
1050 do nothing except return C<undef>.
1051  
1052 The B<DBI>'s default C<begin_work()> method can be used by inheritance.
1053  
1054 =head4 The STORE() and FETCH() methods
1055  
1056 These methods (that we have already used, see above) are called for
1057 you, whenever the user does a:
1058  
1059 $dbh->{$attr} = $val;
1060  
1061 or, respectively,
1062  
1063 $val = $dbh->{$attr};
1064  
1065 See L<perltie> for details on tied hash refs to understand why these
1066 methods are required.
1067  
1068 The B<DBI> will handle most attributes for you, in particular attributes
1069 like I<RaiseError> or I<PrintError>. All you have to do is handle your
1070 driver's private attributes and any attributes, like I<AutoCommit> and
1071 I<ChopBlanks>, that the B<DBI> can't handle for you.
1072  
1073 A good example might look like this:
1074  
1075 sub STORE
1076 {
1077 my ($dbh, $attr, $val) = @_;
1078 if ($attr eq 'AutoCommit') {
1079 # AutoCommit is currently the only standard attribute we have
1080 # to consider.
1081 if (!$val) { die "Can't disable AutoCommit"; }
1082 return 1;
1083 }
1084 if ($attr =~ m/^drv_/) {
1085 # Handle only our private attributes here
1086 # Note that we could trigger arbitrary actions.
1087 # Ideally we should warn about unknown attributes.
1088 $dbh->{$attr} = $val; # Yes, we are allowed to do this,
1089 return 1; # but only for our private attributes
1090 }
1091 # Else pass up to DBI to handle for us
1092 $dbh->SUPER::STORE($attr, $val);
1093 }
1094  
1095 sub FETCH
1096 {
1097 my ($dbh, $attr) = @_;
1098 if ($attr eq 'AutoCommit') { return 1; }
1099 if ($attr =~ m/^drv_/) {
1100 # Handle only our private attributes here
1101 # Note that we could trigger arbitrary actions.
1102 return $dbh->{$attr}; # Yes, we are allowed to do this,
1103 # but only for our private attributes
1104 }
1105 # Else pass up to DBI to handle
1106 $dbh->SUPER::FETCH($attr);
1107 }
1108  
1109 The B<DBI> will actually store and fetch driver-specific attributes (with all
1110 lowercase names) without warning or error, so there's actually no need to
1111 implement driver-specific any code in your C<FETCH()> and C<STORE()>
1112 methods unless you need extra logic/checks, beyond getting or setting
1113 the value.
1114  
1115 Unless your driver documentation indicates otherwise, the return value of
1116 the C<STORE()> method is unspecified and the caller shouldn't use that value.
1117  
1118 =head4 Other database handle methods
1119  
1120 As with the driver package, other database handle methods may follow here.
1121 In particular you should consider a (possibly empty) C<disconnect()>
1122 method and possibly a C<quote()> method if B<DBI>'s default isn't correct for
1123 you. You may also need the C<type_info_all()> and C<get_info()> methods,
1124 as described elsewhere in this document.
1125  
1126 Where reasonable use C<$h-E<gt>SUPER::foo()> to call the B<DBI>'s method in
1127 some or all cases and just wrap your custom behavior around that.
1128  
1129 If you want to use private trace flags you'll probably want to be
1130 able to set them by name. To do that you'll need to define a
1131 C<parse_trace_flag()> method (note that's "parse_trace_flag", singular,
1132 not "parse_trace_flags", plural).
1133  
1134 sub parse_trace_flag {
1135 my ($h, $name) = @_;
1136 return 0x01000000 if $name eq 'foo';
1137 return 0x02000000 if $name eq 'bar';
1138 return 0x04000000 if $name eq 'baz';
1139 return 0x08000000 if $name eq 'boo';
1140 return 0x10000000 if $name eq 'bop';
1141 return $h->SUPER::parse_trace_flag($name);
1142 }
1143  
1144 All private flag names must be lowercase, and all private flags
1145 must be in the top 8 of the 32 bits.
1146  
1147 =head3 The DBD::Driver::st package
1148  
1149 This package follows the same pattern the others do:
1150  
1151 package DBD::Driver::st;
1152  
1153 $DBD::Driver::st::imp_data_size = 0;
1154  
1155 =head4 The execute() and bind_param() methods
1156  
1157 This is perhaps the most difficult method because we have to consider
1158 parameter bindings here. In addition to that, there are a number of
1159 statement attributes which must be set for inherited B<DBI> methods to
1160 function correctly (see L</Statement attributes> below).
1161  
1162 We present a simplified implementation by using the I<drv_params>
1163 attribute from above:
1164  
1165 sub bind_param
1166 {
1167 my ($sth, $pNum, $val, $attr) = @_;
1168 my $type = (ref $attr) ? $attr->{TYPE} : $attr;
1169 if ($type) {
1170 my $dbh = $sth->{Database};
1171 $val = $dbh->quote($sth, $type);
1172 }
1173 my $params = $sth->{drv_params};
1174 $params->[$pNum-1] = $val;
1175 1;
1176 }
1177  
1178 sub execute
1179 {
1180 my ($sth, @bind_values) = @_;
1181  
1182 # start of by finishing any previous execution if still active
1183 $sth->finish if $sth->FETCH('Active');
1184  
1185 my $params = (@bind_values) ?
1186 \@bind_values : $sth->{drv_params};
1187 my $numParam = $sth->FETCH('NUM_OF_PARAMS');
1188 return $sth->set_err($DBI::stderr, "Wrong number of parameters")
1189 if @$params != $numParam;
1190 my $statement = $sth->{'Statement'};
1191 for (my $i = 0; $i < $numParam; $i++) {
1192 $statement =~ s/?/$params->[$i]/; # XXX doesn't deal with quoting etc!
1193 }
1194 # Do anything ... we assume that an array ref of rows is
1195 # created and store it:
1196 $sth->{'drv_data'} = $data;
1197 $sth->{'drv_rows'} = @$data; # number of rows
1198 $sth->STORE('NUM_OF_FIELDS') = $numFields;
1199 $sth->{Active} = 1;
1200 @$data || '0E0';
1201 }
1202  
1203 There are a number of things you should note here.
1204  
1205 We initialize the I<NUM_OF_FIELDS> and I<Active> attributes here,
1206 because they are essential for C<bind_columns()> to work.
1207  
1208 We use attribute C<$sth-E<gt>{Statement}> which we created
1209 within C<prepare()>. The attribute C<$sth-E<gt>{Database}>, which is
1210 nothing else than the I<dbh>, was automatically created by B<DBI>.
1211  
1212 Finally, note that (as specified in the B<DBI> specification) we return the
1213 string C<'0E0'> instead of the number 0, so that the result tests true but
1214 equal to zero.
1215  
1216 $sth->execute() or die $sth->errstr;
1217  
1218 =head4 The execute_array(), execute_for_fetch() and bind_param_array() methods
1219  
1220 In general, DBD's only need to implement C<execute_for_fetch()> and
1221 C<bind_param_array>. DBI's default C<execute_array()> will invoke the
1222 DBD's C<execute_for_fetch()> as needed.
1223  
1224 The following sequence describes the interaction between
1225 DBI C<execute_array> and a DBD's C<execute_for_fetch>:
1226  
1227 =over
1228  
1229 =item 1
1230  
1231 App calls C<$sth-E<gt>execute_array(\%attrs, @array_of_arrays)>
1232  
1233 =item 2
1234  
1235 If C<@array_of_arrays> was specified, DBI processes C<@array_of_arrays> by calling
1236 DBD's C<bind_param_array()>. Alternately, App may have directly called
1237 C<bind_param_array()>
1238  
1239 =item 3
1240  
1241 DBD validates and binds each array
1242  
1243 =item 4
1244  
1245 DBI retrieves the validated param arrays from DBD's ParamArray attribute
1246  
1247 =item 5
1248  
1249 DBI calls DBD's C<execute_for_fetch($fetch_tuple_sub, \@tuple_status)>,
1250 where C<&$fetch_tuple_sub> is a closure to iterate over the
1251 returned ParamArray values, and C<\@tuple_status> is an array to receive
1252 the disposition status of each tuple.
1253  
1254 =item 6
1255  
1256 DBD iteratively calls C<&$fetch_tuple_sub> to retrieve parameter tuples
1257 to be added to its bulk database operation/request.
1258  
1259 =item 7
1260  
1261 when DBD reaches the limit of tuples it can handle in a single database
1262 operation/request, or the C<&$fetch_tuple_sub> indicates no more
1263 tuples by returning undef, the DBD executes the bulk operation, and
1264 reports the disposition of each tuple in \@tuple_status.
1265  
1266 =item 8
1267  
1268 DBD repeats steps 6 and 7 until all tuples are processed.
1269  
1270 =back
1271  
1272 E.g., here's the essence of L<DBD::Oracle>'s execute_for_fetch:
1273  
1274 while (1) {
1275 my @tuple_batch;
1276 for (my $i = 0; $i < $batch_size; $i++) {
1277 push @tuple_batch, [ @{$fetch_tuple_sub->() || last} ];
1278 }
1279 last unless @tuple_batch;
1280 my $res = ora_execute_array($sth, \@tuple_batch,
1281 scalar(@tuple_batch), $tuple_batch_status);
1282 push @$tuple_status, @$tuple_batch_status;
1283 }
1284  
1285 Note that DBI's default execute_array()/execute_for_fetch() implementation
1286 requires the use of positional (i.e., '?') placeholders. Drivers
1287 which B<require> named placeholders must either emulate positional
1288 placeholders (e.g., see L<DBD::Oracle>), or must implement their own
1289 execute_array()/execute_for_fetch() methods to properly sequence bound
1290 parameter arrays.
1291  
1292 =head4 Fetching data
1293  
1294 Only one method needs to be written for fetching data, C<fetchrow_arrayref()>.
1295 The other methods, C<fetchrow_array()>, C<fetchall_arrayref()>, etc, as well
1296 as the database handle's C<select*> methods are part of B<DBI>, and call
1297 C<fetchrow_arrayref()> as necessary.
1298  
1299 sub fetchrow_arrayref
1300 {
1301 my ($sth) = @_;
1302 my $data = $sth->{drv_data};
1303 my $row = shift @$data;
1304 if (!$row) {
1305 $sth->STORE(Active => 0); # mark as no longer active
1306 return undef;
1307 }
1308 if ($sth->FETCH('ChopBlanks')) {
1309 map { $_ =~ s/\s+$//; } @$row;
1310 }
1311 return $sth->_set_fbav($row);
1312 }
1313 *fetch = \&fetchrow_arrayref; # required alias for fetchrow_arrayref
1314  
1315 Note the use of the method C<_set_fbav()> -- this is required so that
1316 C<bind_col()> and C<bind_columns()> work.
1317  
1318 If an error occurs which leaves the I<$sth> in a state where remaining rows
1319 can't be fetched then I<Active> should be turned off before the method returns.
1320  
1321 The C<rows()> method for this driver can be implemented like this:
1322  
1323 sub rows { shift->{drv_rows} }
1324  
1325 because it knows in advance how many rows it has fetched.
1326 Alternatively you could delete that method and so fallback
1327 to the B<DBI>'s own method which does the right thing based
1328 on the number of calls to C<_set_fbav()>.
1329  
1330 =head4 The more_results method
1331  
1332 If your driver doesn't support multiple result sets, then don't even implement this method.
1333  
1334 Otherwise, this method needs to get the statement handle ready to fetch results
1335 from the next result set, if there is one. Typically you'd start with:
1336  
1337 $sth->finish;
1338  
1339 then you should delete all the attributes from the attribute cache that may no
1340 longer be relevant for the new result set:
1341  
1342 delete $sth->{$_}
1343 for qw(NAME TYPE PRECISION SCALE ...);
1344  
1345 for drivers written in C use:
1346  
1347 hv_delete((HV*)SvRV(sth), "NAME", 4, G_DISCARD);
1348 hv_delete((HV*)SvRV(sth), "NULLABLE", 8, G_DISCARD);
1349 hv_delete((HV*)SvRV(sth), "NUM_OF_FIELDS", 13, G_DISCARD);
1350 hv_delete((HV*)SvRV(sth), "PRECISION", 9, G_DISCARD);
1351 hv_delete((HV*)SvRV(sth), "SCALE", 5, G_DISCARD);
1352 hv_delete((HV*)SvRV(sth), "TYPE", 4, G_DISCARD);
1353  
1354 Don't forget to also delete, or update, any driver-private attributes that may
1355 not be correct for the next resultset.
1356  
1357 The NUM_OF_FIELDS attribute is a special case. It should be set using STORE:
1358  
1359 $sth->STORE(NUM_OF_FIELDS => 0); /* for DBI <= 1.53 */
1360 $sth->STORE(NUM_OF_FIELDS => $new_value);
1361  
1362 for drivers written in C use this incantation:
1363  
1364 /* Adjust NUM_OF_FIELDS - which also adjusts the row buffer size */
1365 DBIc_NUM_FIELDS(imp_sth) = 0; /* for DBI <= 1.53 */
1366 DBIc_STATE(imp_xxh)->set_attr_k(sth, sv_2mortal(newSVpvn("NUM_OF_FIELDS",13)), 0,
1367 sv_2mortal(newSViv(mysql_num_fields(imp_sth->result)))
1368 );
1369  
1370 For DBI versions prior to 1.54 you'll also need to explicitly adjust the
1371 number of elements in the row buffer array (C<DBIc_FIELDS_AV(imp_sth)>)
1372 to match the new result set. Fill any new values with newSV(0) not &sv_undef.
1373 Alternatively you could free DBIc_FIELDS_AV(imp_sth) and set it to null,
1374 but that would mean bind_columns() wouldn't work across result sets.
1375  
1376  
1377 =head4 Statement attributes
1378  
1379 The main difference between I<dbh> and I<sth> attributes is, that you
1380 should implement a lot of attributes here that are required by
1381 the B<DBI>, such as I<NAME>, I<NULLABLE>, I<TYPE>, etc. See
1382 L<DBI/Statement Handle Attributes> for a complete list.
1383  
1384 Pay attention to attributes which are marked as read only, such as
1385 I<NUM_OF_PARAMS>. These attributes can only be set the first time
1386 a statement is executed. If a statement is prepared, then executed
1387 multiple times, warnings may be generated.
1388  
1389 You can protect against these warnings, and prevent the recalculation
1390 of attributes which might be expensive to calculate (such as the
1391 I<NAME> and I<NAME_*> attributes):
1392  
1393 my $storedNumParams = $sth->FETCH('NUM_OF_PARAMS');
1394 if (!defined $storedNumParams or $storedNumFields < 0) {
1395 $sth->STORE('NUM_OF_PARAMS') = $numParams;
1396  
1397 # Set other useful attributes that only need to be set once
1398 # for a statement, like $sth->{NAME} and $sth->{TYPE}
1399 }
1400  
1401 One particularly important attribute to set correctly (mentioned in
1402 L<DBI/ATTRIBUTES COMMON TO ALL HANDLES> is I<Active>. Many B<DBI> methods,
1403 including C<bind_columns()>, depend on this attribute.
1404  
1405 Besides that the C<STORE()> and C<FETCH()> methods are mainly the same
1406 as above for I<dbh>'s.
1407  
1408 =head4 Other statement methods
1409  
1410 A trivial C<finish()> method to discard stored data, reset any attributes
1411 (such as I<Active>) and do C<$sth-E<gt>SUPER::finish()>.
1412  
1413 If you've defined a C<parse_trace_flag()> method in B<::db> you'll also want
1414 it in B<::st>, so just alias it in:
1415  
1416 *parse_trace_flag = \&DBD::foo:db::parse_trace_flag;
1417  
1418 And perhaps some other methods that are not part of the B<DBI>
1419 specification, in particular to make metadata available.
1420 Remember that they must have names that begin with your drivers
1421 registered prefix so they can be installed using C<install_method()>.
1422  
1423 If C<DESTROY()> is called on a statement handle that's still active
1424 (C<$sth-E<gt>{Active}> is true) then it should effectively call C<finish()>.
1425  
1426 sub DESTROY {
1427 my $sth = shift;
1428 $sth->finish if $sth->FETCH('Active');
1429 }
1430  
1431 =head2 Tests
1432  
1433 The test process should conform as closely as possibly to the Perl
1434 standard test harness.
1435  
1436 In particular, most (all) of the tests should be run in the F<t> sub-directory,
1437 and should simply produce an C<ok> when run under C<make test>.
1438 For details on how this is done, see the Camel book and the section in
1439 Chapter 7, "The Standard Perl Library" on L<Test::Harness>.
1440  
1441 The tests may need to adapt to the type of database which is being used
1442 for testing, and to the privileges of the user testing the driver. For
1443 example, the B<DBD::Informix> test code has to adapt in a number of
1444 places to the type of database to which it is connected as different
1445 Informix databases have different capabilities: some of the tests are
1446 for databases without transaction logs; others are for databases with a
1447 transaction log; some versions of the server have support for blobs, or
1448 stored procedures, or user-defined data types, and others do not.
1449  
1450 When a complete file of tests must be skipped, you can provide a reason
1451 in a pseudo-comment:
1452  
1453 if ($no_transactions_available)
1454 {
1455 print "1..0 # Skip: No transactions available\n";
1456 exit 0;
1457 }
1458  
1459 Consider downloading the B<DBD::Informix> code and look at the code in
1460 F<DBD/Informix/TestHarness.pm> which is used throughout the
1461 B<DBD::Informix> tests in the F<t> sub-directory.
1462  
1463 =head1 CREATING A C/XS DRIVER
1464  
1465 Please also see the section under L<CREATING A PURE PERL DRIVER>
1466 regarding the creation of the F<Makefile.PL>.
1467  
1468 Creating a new C/XS driver from scratch will always be a daunting task.
1469 You can and should greatly simplify your task by taking a good
1470 reference driver implementation and modifying that to match the
1471 database product for which you are writing a driver.
1472  
1473 The de facto reference driver has been the one for B<DBD::Oracle> written
1474 by Tim Bunce, who is also the author of the B<DBI> package. The B<DBD::Oracle>
1475 module is a good example of a driver implemented around a C-level API.
1476  
1477 Nowadays it it seems better to base on B<DBD::ODBC>, another driver
1478 maintained by Tim and Jeff Urlwin, because it offers a lot of metadata
1479 and seems to become the guideline for the future development. (Also as
1480 B<DBD::Oracle> digs deeper into the Oracle 8 OCI interface it'll get even
1481 more hairy than it is now.)
1482  
1483 The B<DBD::Informix> driver is one driver implemented using embedded SQL
1484 instead of a function-based API.
1485 B<DBD::Ingres> may also be worth a look.
1486  
1487 =head2 C/XS version of Driver.pm
1488  
1489 A lot of the code in the F<Driver.pm> file is very similar to the code for pure Perl modules
1490 - see above. However,
1491 there are also some subtle (and not so subtle) differences, including:
1492  
1493 =over 8
1494  
1495 =item *
1496  
1497 The variables I<$DBD::Driver::{dr|db|st}::imp_data_size> are not defined
1498 here, but in the XS code, because they declare the size of certain
1499 C structures.
1500  
1501 =item *
1502  
1503 Some methods are typically moved to the XS code, in particular
1504 C<prepare()>, C<execute()>, C<disconnect()>, C<disconnect_all()> and the
1505 C<STORE()> and C<FETCH()> methods.
1506  
1507 =item *
1508  
1509 Other methods are still part of F<Driver.pm>, but have callbacks to
1510 the XS code.
1511  
1512 =item *
1513  
1514 If the driver-specific parts of the I<imp_drh_t> structure need to be
1515 formally initialized (which does not seem to be a common requirement),
1516 then you need to add a call to an appropriate XS function in the driver
1517 method of C<DBD::Driver::driver()>, and you define the corresponding function
1518 in F<Driver.xs>, and you define the C code in F<dbdimp.c> and the prototype in
1519 F<dbdimp.h>.
1520  
1521 For example, B<DBD::Informix> has such a requirement, and adds the
1522 following call after the call to C<_new_drh()> in F<Informix.pm>:
1523  
1524 DBD::Informix::dr::driver_init($drh);
1525  
1526 and the following code in F<Informix.xs>:
1527  
1528 # Initialize the DBD::Informix driver data structure
1529 void
1530 driver_init(drh)
1531 SV *drh
1532 CODE:
1533 ST(0) = dbd_ix_dr_driver_init(drh) ? &sv_yes : &sv_no;
1534  
1535 and the code in F<dbdimp.h> declares:
1536  
1537 extern int dbd_ix_dr_driver_init(SV *drh);
1538  
1539 and the code in F<dbdimp.ec> (equivalent to F<dbdimp.c>) defines:
1540  
1541 /* Formally initialize the DBD::Informix driver structure */
1542 int
1543 dbd_ix_dr_driver(SV *drh)
1544 {
1545 D_imp_drh(drh);
1546 imp_drh->n_connections = 0; /* No active connections */
1547 imp_drh->current_connection = 0; /* No current connection */
1548 imp_drh->multipleconnections = (ESQLC_VERSION >= 600) ? True : False;
1549 dbd_ix_link_newhead(&imp_drh->head); /* Empty linked list of connections */
1550 return 1;
1551 }
1552  
1553 B<DBD::Oracle> has a similar requirement but gets around it by checking
1554 whether the private data part of the driver handle is all zeroed out,
1555 rather than add extra functions.
1556  
1557 =back
1558  
1559 Now let's take a closer look at an excerpt from F<Oracle.pm> (revised
1560 heavily to remove idiosyncrasies) as an example, ignoring things that
1561 were already discussed for pure Perl drivers.
1562  
1563 =head3 The connect method
1564  
1565 The connect method is the database handle constructor.
1566 You could write either of two versions of this method: either one which
1567 takes connection attributes (new code) and one which ignores them (old
1568 code only).
1569  
1570 If you ignore the connection attributes, then you omit all mention of
1571 the I<$auth> variable (which is a reference to a hash of attributes), and
1572 the XS system manages the differences for you.
1573  
1574 sub connect
1575 {
1576 my ($drh, $dbname, $user, $auth, $attr) = @_;
1577  
1578 # Some database specific verifications, default settings
1579 # and the like following here. This should only include
1580 # syntax checks or similar stuff where it's legal to
1581 # 'die' in case of errors.
1582  
1583 my $dbh = DBI::_new_dbh($drh, {
1584 'Name' => $dbname,
1585 })
1586 or return undef;
1587  
1588 # Call the driver-specific function _login in Driver.xs file which
1589 # calls the DBMS-specific function(s) to connect to the database,
1590 # and populate internal handle data.
1591 DBD::Driver::db::_login($dbh, $dbname, $user, $auth, $attr)
1592 or return undef;
1593  
1594 $dbh;
1595 }
1596  
1597 This is mostly the same as in the pure Perl case, the exception being
1598 the use of the private C<_login()> callback, which is the function
1599 that will really connect to the database. It is implemented in
1600 F<Driver.xst> (you should not implement it) and calls
1601 C<dbd_db_login6()> or C<dbd_db_login6_sv> from F<dbdimp.c>. See below
1602 for details.
1603  
1604 If your driver has driver-specific attributes which may be passed in the
1605 connect method and hence end up in C<$attr> in C<dbd_db_login6> then it
1606 is best to delete any you process so DBI does not send them again
1607 via STORE after connect. You can do this in C like this:
1608  
1609 DBD_ATTRIB_DELETE(attr, "my_attribute_name",
1610 strlen("my_attribute_name"));
1611  
1612 However, prior to DBI subversion version 11605 (and fixed post 1.607)
1613 DBD_ATTRIB_DELETE segfaulted so if you cannot guarantee the DBI version
1614 will be post 1.607 you need to use:
1615  
1616 hv_delete((HV*)SvRV(attr), "my_attribute_name",
1617 strlen("my_attribute_name"), G_DISCARD);
1618  
1619 *FIX ME* Discuss removing attributes in Perl code.
1620  
1621 =head3 The disconnect_all method
1622  
1623 *FIX ME* T.B.S
1624  
1625 =head3 The data_sources method
1626  
1627 If your C<data_sources()> method can be implemented in pure Perl, then do
1628 so because it is easier than doing it in XS code (see the section above
1629 for pure Perl drivers).
1630  
1631 If your C<data_sources()> method must call onto compiled functions, then
1632 you will need to define I<dbd_dr_data_sources> in your F<dbdimp.h> file, which
1633 will trigger F<Driver.xst> (in B<DBI> v1.33 or greater) to generate the XS
1634 code that calls your actual C function (see the discussion below for
1635 details) and you do not code anything in F<Driver.pm> to handle it.
1636  
1637 =head3 The prepare method
1638  
1639 The prepare method is the statement handle constructor, and most of it
1640 is not new. Like the C<connect()> method, it now has a C callback:
1641  
1642 package DBD::Driver::db; # ====== DATABASE ======
1643 use strict;
1644  
1645 sub prepare
1646 {
1647 my ($dbh, $statement, $attribs) = @_;
1648  
1649 # create a 'blank' sth
1650 my $sth = DBI::_new_sth($dbh, {
1651 'Statement' => $statement,
1652 })
1653 or return undef;
1654  
1655 # Call the driver-specific function _prepare in Driver.xs file
1656 # which calls the DBMS-specific function(s) to prepare a statement
1657 # and populate internal handle data.
1658 DBD::Driver::st::_prepare($sth, $statement, $attribs)
1659 or return undef;
1660 $sth;
1661 }
1662  
1663 =head3 The execute method
1664  
1665 *FIX ME* T.B.S
1666  
1667 =head3 The fetchrow_arrayref method
1668  
1669 *FIX ME* T.B.S
1670  
1671 =head3 Other methods?
1672  
1673 *FIX ME* T.B.S
1674  
1675 =head2 Driver.xs
1676  
1677 F<Driver.xs> should look something like this:
1678  
1679 #include "Driver.h"
1680  
1681 DBISTATE_DECLARE;
1682  
1683 INCLUDE: Driver.xsi
1684  
1685 MODULE = DBD::Driver PACKAGE = DBD::Driver::dr
1686  
1687 /* Non-standard drh XS methods following here, if any. */
1688 /* If none (the usual case), omit the MODULE line above too. */
1689  
1690 MODULE = DBD::Driver PACKAGE = DBD::Driver::db
1691  
1692 /* Non-standard dbh XS methods following here, if any. */
1693 /* Currently this includes things like _list_tables from */
1694 /* DBD::mSQL and DBD::mysql. */
1695  
1696 MODULE = DBD::Driver PACKAGE = DBD::Driver::st
1697  
1698 /* Non-standard sth XS methods following here, if any. */
1699 /* In particular this includes things like _list_fields from */
1700 /* DBD::mSQL and DBD::mysql for accessing metadata. */
1701  
1702 Note especially the include of F<Driver.xsi> here: B<DBI> inserts stub
1703 functions for almost all private methods here which will typically do
1704 much work for you.
1705  
1706 Wherever you really have to implement something, it will call a private
1707 function in F<dbdimp.c>, and this is what you have to implement.
1708  
1709 You need to set up an extra routine if your driver needs to export
1710 constants of its own, analogous to the SQL types available when you say:
1711  
1712 use DBI qw(:sql_types);
1713  
1714 *FIX ME* T.B.S
1715  
1716 =head2 Driver.h
1717  
1718 F<Driver.h> is very simple and the operational contents should look like this:
1719  
1720 #ifndef DRIVER_H_INCLUDED
1721 #define DRIVER_H_INCLUDED
1722  
1723 #define NEED_DBIXS_VERSION 93 /* 93 for DBI versions 1.00 to 1.51+ */
1724 #define PERL_NO_GET_CONTEXT /* if used require DBI 1.51+ */
1725  
1726 #include <DBIXS.h> /* installed by the DBI module */
1727  
1728 #include "dbdimp.h"
1729  
1730 #include "dbivport.h" /* see below */
1731  
1732 #include <dbd_xsh.h> /* installed by the DBI module */
1733  
1734 #endif /* DRIVER_H_INCLUDED */
1735  
1736 The F<DBIXS.h> header defines most of the interesting information that
1737 the writer of a driver needs.
1738  
1739 The file F<dbd_xsh.h> header provides prototype declarations for the C
1740 functions that you might decide to implement. Note that you should
1741 normally only define one of C<dbd_db_login()>, C<dbd_db_login6()> or
1742 C<dbd_db_login6_sv> unless you are intent on supporting really old
1743 versions of B<DBI> (prior to B<DBI> 1.06) as well as modern
1744 versions. The only standard, B<DBI>-mandated functions that you need
1745 write are those specified in the F<dbd_xsh.h> header. You might also
1746 add extra driver-specific functions in F<Driver.xs>.
1747  
1748 The F<dbivport.h> file should be I<copied> from the latest B<DBI> release
1749 into your distribution each time you modify your driver. Its job is to
1750 allow you to enhance your code to work with the latest B<DBI> API while
1751 still allowing your driver to be compiled and used with older versions
1752 of the B<DBI> (for example, when the C<DBIh_SET_ERR_CHAR()> macro was added
1753 to B<DBI> 1.41, an emulation of it was added to F<dbivport.h>). This makes
1754 users happy and your life easier. Always read the notes in F<dbivport.h>
1755 to check for any limitations in the emulation that you should be aware
1756 of.
1757  
1758 With B<DBI> v1.51 or better I recommend that the driver defines
1759 I<PERL_NO_GET_CONTEXT> before F<DBIXS.h> is included. This can significantly
1760 improve efficiency when running under a thread enabled perl. (Remember that
1761 the standard perl in most Linux distributions is built with threads enabled.
1762 So is ActiveState perl for Windows, and perl built for Apache mod_perl2.)
1763 If you do this there are some things to keep in mind:
1764  
1765 =over 4
1766  
1767 =item *
1768  
1769 If I<PERL_NO_GET_CONTEXT> is defined, then every function that calls the Perl
1770 API will need to start out with a C<dTHX;> declaration.
1771  
1772 =item *
1773  
1774 You'll know which functions need this, because the C compiler will
1775 complain that the undeclared identifier C<my_perl> is used if I<and only if>
1776 the perl you are using to develop and test your driver has threads enabled.
1777  
1778 =item *
1779  
1780 If you don't remember to test with a thread-enabled perl before making
1781 a release it's likely that you'll get failure reports from users who are.
1782  
1783 =item *
1784  
1785 For driver private functions it is possible to gain even more
1786 efficiency by replacing C<dTHX;> with C<pTHX_> prepended to the
1787 parameter list and then C<aTHX_> prepended to the argument list where
1788 the function is called.
1789  
1790 =back
1791  
1792 See L<perlguts/How multiple interpreters and concurrency are supported> for
1793 additional information about I<PERL_NO_GET_CONTEXT>.
1794  
1795 =head2 Implementation header dbdimp.h
1796  
1797 This header file has two jobs:
1798  
1799 First it defines data structures for your private part of the handles.
1800 Note that the DBI provides many common fields for you. For example
1801 the statement handle (imp_sth) already has a row_count field with an IV type
1802 that accessed via the DBIc_ROW_COUNT(imp_sth) macro. Using this is strongly
1803 recommended as it's built in to some DBI internals so the DBI can 'just work'
1804 in more cases and you'll have less driver-specific code to write.
1805 Study DBIXS.h to see what's included with each type of handle.
1806  
1807 Second it defines macros that rename the generic names like
1808 C<dbd_db_login()> to database specific names like C<ora_db_login()>. This
1809 avoids name clashes and enables use of different drivers when you work
1810 with a statically linked perl.
1811  
1812 It also will have the important task of disabling XS methods that you
1813 don't want to implement.
1814  
1815 Finally, the macros will also be used to select alternate
1816 implementations of some functions. For example, the C<dbd_db_login()>
1817 function is not passed the attribute hash.
1818  
1819 Since B<DBI> v1.06, if a C<dbd_db_login6()> macro is defined (for a function
1820 with 6 arguments), it will be used instead with the attribute hash
1821 passed as the sixth argument.
1822  
1823 Since B<DBI> post v1.607, if a C<dbd_db_login6_sv()> macro is defined (for
1824 a function like dbd_db_login6 but with scalar pointers for the dbname,
1825 username and password), it will be used instead. This will allow your
1826 login6 function to see if there are any Unicode characters in the
1827 dbname.
1828  
1829 Similarly defining dbd_db_do4_iv is preferred over dbd_db_do4, dbd_st_rows_iv
1830 over dbd_st_rows, and dbd_st_execute_iv over dbd_st_execute. The *_iv forms are
1831 declared to return the IV type instead of an int.
1832  
1833 People used to just pick Oracle's F<dbdimp.c> and use the same names,
1834 structures and types. I strongly recommend against that. At first glance
1835 this saves time, but your implementation will be less readable. It was
1836 just hell when I had to separate B<DBI> specific parts, Oracle specific
1837 parts, mSQL specific parts and mysql specific parts in B<DBD::mysql>'s
1838 I<dbdimp.h> and I<dbdimp.c>. (B<DBD::mysql> was a port of B<DBD::mSQL>
1839 which was based on B<DBD::Oracle>.) [Seconded, based on the experience
1840 taking B<DBD::Informix> apart, even though the version inherited in 1996
1841 was only based on B<DBD::Oracle>.]
1842  
1843 This part of the driver is I<your exclusive part>. Rewrite it from
1844 scratch, so it will be clean and short: in other words, a better piece
1845 of code. (Of course keep an eye on other people's work.)
1846  
1847 struct imp_drh_st {
1848 dbih_drc_t com; /* MUST be first element in structure */
1849 /* Insert your driver handle attributes here */
1850 };
1851  
1852 struct imp_dbh_st {
1853 dbih_dbc_t com; /* MUST be first element in structure */
1854 /* Insert your database handle attributes here */
1855 };
1856  
1857 struct imp_sth_st {
1858 dbih_stc_t com; /* MUST be first element in structure */
1859 /* Insert your statement handle attributes here */
1860 };
1861  
1862 /* Rename functions for avoiding name clashes; prototypes are */
1863 /* in dbd_xsh.h */
1864 #define dbd_init drv_dr_init
1865 #define dbd_db_login6_sv drv_db_login_sv
1866 #define dbd_db_do drv_db_do
1867 ... many more here ...
1868  
1869 These structures implement your private part of the handles.
1870  
1871 You I<have> to use the name C<imp_dbh_{dr|db|st}> and the first field
1872 I<must> be of type I<dbih_drc_t|_dbc_t|_stc_t> and I<must> be called
1873 C<com>.
1874  
1875 You should never access these fields directly, except by using the
1876 I<DBIc_xxx()> macros below.
1877  
1878 =head2 Implementation source dbdimp.c
1879  
1880 Conventionally, F<dbdimp.c> is the main implementation file (but
1881 B<DBD::Informix> calls the file F<dbdimp.ec>). This section includes a
1882 short note on each function that is used in the F<Driver.xsi> template
1883 and thus I<has> to be implemented.
1884  
1885 Of course, you will probably also need to implement other support
1886 functions, which should usually be file static if they are placed in
1887 F<dbdimp.c>. If they are placed in other files, you need to list those
1888 files in F<Makefile.PL> (and F<MANIFEST>) to handle them correctly.
1889  
1890 It is wise to adhere to a namespace convention for your functions to
1891 avoid conflicts. For example, for a driver with prefix I<drv_>, you
1892 might call externally visible functions I<dbd_drv_xxxx>. You should also
1893 avoid non-constant global variables as much as possible to improve the
1894 support for threading.
1895  
1896 Since Perl requires support for function prototypes (ANSI or ISO or
1897 Standard C), you should write your code using function prototypes too.
1898  
1899 It is possible to use either the unmapped names such as C<dbd_init()> or
1900 the mapped names such as C<dbd_ix_dr_init()> in the F<dbdimp.c> file.
1901 B<DBD::Informix> uses the mapped names which makes it easier to identify
1902 where to look for linkage problems at runtime (which will report errors
1903 using the mapped names).
1904  
1905 Most other drivers, and in particular B<DBD::Oracle>, use the unmapped
1906 names in the source code which makes it a little easier to compare code
1907 between drivers and eases discussions on the I<dbi-dev> mailing list.
1908 The majority of the code fragments here will use the unmapped names.
1909  
1910 Ultimately, you should provide implementations for most of the
1911 functions listed in the F<dbd_xsh.h> header. The exceptions are
1912 optional functions (such as C<dbd_st_rows()>) and those functions with
1913 alternative signatures, such as C<dbd_db_login6_sv>,
1914 C<dbd_db_login6()> and I<dbd_db_login()>. Then you should only
1915 implement one of the alternatives, and generally the newer one of the
1916 alternatives.
1917  
1918 =head3 The dbd_init method
1919  
1920 #include "Driver.h"
1921  
1922 DBISTATE_DECLARE;
1923  
1924 void dbd_init(dbistate_t* dbistate)
1925 {
1926 DBISTATE_INIT; /* Initialize the DBI macros */
1927 }
1928  
1929 The C<dbd_init()> function will be called when your driver is first
1930 loaded; the bootstrap command in C<DBD::Driver::dr::driver()> triggers this,
1931 and the call is generated in the I<BOOT> section of F<Driver.xst>.
1932 These statements are needed to allow your driver to use the B<DBI> macros.
1933 They will include your private header file F<dbdimp.h> in turn.
1934 Note that I<DBISTATE_INIT> requires the name of the argument to C<dbd_init()>
1935 to be called C<dbistate()>.
1936  
1937 =head3 The dbd_drv_error method
1938  
1939 You need a function to record errors so B<DBI> can access them properly.
1940 You can call it whatever you like, but we'll call it C<dbd_drv_error()>
1941 here.
1942  
1943 The argument list depends on your database software; different systems
1944 provide different ways to get at error information.
1945  
1946 static void dbd_drv_error(SV *h, int rc, const char *what)
1947 {
1948  
1949 Note that I<h> is a generic handle, may it be a driver handle, a
1950 database or a statement handle.
1951  
1952 D_imp_xxh(h);
1953  
1954 This macro will declare and initialize a variable I<imp_xxh> with
1955 a pointer to your private handle pointer. You may cast this to
1956 to I<imp_drh_t>, I<imp_dbh_t> or I<imp_sth_t>.
1957  
1958 To record the error correctly, equivalent to the C<set_err()> method,
1959 use one of the C<DBIh_SET_ERR_CHAR(...)> or C<DBIh_SET_ERR_SV(...)> macros,
1960 which were added in B<DBI> 1.41:
1961  
1962 DBIh_SET_ERR_SV(h, imp_xxh, err, errstr, state, method);
1963 DBIh_SET_ERR_CHAR(h, imp_xxh, err_c, err_i, errstr, state, method);
1964  
1965 For C<DBIh_SET_ERR_SV> the I<err>, I<errstr>, I<state>, and I<method>
1966 parameters are C<SV*> (use &sv_undef instead of NULL).
1967  
1968 For C<DBIh_SET_ERR_CHAR> the I<err_c>, I<errstr>, I<state>, I<method>
1969 parameters are C<char*>.
1970  
1971 The I<err_i> parameter is an C<IV> that's used instead of I<err_c> if
1972 I<err_c> is C<Null>.
1973  
1974 The I<method> parameter can be ignored.
1975  
1976 The C<DBIh_SET_ERR_CHAR> macro is usually the simplest to use when you
1977 just have an integer error code and an error message string:
1978  
1979 DBIh_SET_ERR_CHAR(h, imp_xxh, Nullch, rc, what, Nullch, Nullch);
1980  
1981 As you can see, any parameters that aren't relevant to you can be C<Null>.
1982  
1983 To make drivers compatible with B<DBI> < 1.41 you should be using F<dbivport.h>
1984 as described in L</Driver.h> above.
1985  
1986 The (obsolete) macros such as C<DBIh_EVENT2> should be removed from drivers.
1987  
1988 The names C<dbis> and C<DBIS>, which were used in previous versions of
1989 this document, should be replaced with the C<DBIc_DBISTATE(imp_xxh)> macro.
1990  
1991 The name C<DBILOGFP>, which was also used in previous versions of this
1992 document, should be replaced by C<DBIc_LOGPIO(imp_xxh)>.
1993  
1994 Your code should not call the C C<E<lt>stdio.hE<gt>> I/O functions; you
1995 should use C<PerlIO_printf()> as shown:
1996  
1997 if (DBIc_TRACE_LEVEL(imp_xxh) >= 2)
1998 PerlIO_printf(DBIc_LOGPIO(imp_xxh), "foobar %s: %s\n",
1999 foo, neatsvpv(errstr,0));
2000  
2001 That's the first time we see how tracing works within a B<DBI> driver. Make
2002 use of this as often as you can, but don't output anything at a trace
2003 level less than 3. Levels 1 and 2 are reserved for the B<DBI>.
2004  
2005 You can define up to 8 private trace flags using the top 8 bits
2006 of C<DBIc_TRACE_FLAGS(imp)>, that is: C<0xFF000000>. See the
2007 C<parse_trace_flag()> method elsewhere in this document.
2008  
2009 =head3 The dbd_dr_data_sources method
2010  
2011 This method is optional; the support for it was added in B<DBI> v1.33.
2012  
2013 As noted in the discussion of F<Driver.pm>, if the data sources
2014 can be determined by pure Perl code, do it that way. If, as in
2015 B<DBD::Informix>, the information is obtained by a C function call, then
2016 you need to define a function that matches the prototype:
2017  
2018 extern AV *dbd_dr_data_sources(SV *drh, imp_drh_t *imp_drh, SV *attrs);
2019  
2020 An outline implementation for B<DBD::Informix> follows, assuming that the
2021 C<sqgetdbs()> function call shown will return up to 100 databases names,
2022 with the pointers to each name in the array dbsname and the name strings
2023 themselves being stores in dbsarea.
2024  
2025 AV *dbd_dr_data_sources(SV *drh, imp_drh_t *imp_drh, SV *attr)
2026 {
2027 int ndbs;
2028 int i;
2029 char *dbsname[100];
2030 char dbsarea[10000];
2031 AV *av = Nullav;
2032  
2033 if (sqgetdbs(&ndbs, dbsname, 100, dbsarea, sizeof(dbsarea)) == 0)
2034 {
2035 av = NewAV();
2036 av_extend(av, (I32)ndbs);
2037 sv_2mortal((SV *)av);
2038 for (i = 0; i < ndbs; i++)
2039 av_store(av, i, newSVpvf("dbi:Informix:%s", dbsname[i]));
2040 }
2041 return(av);
2042 }
2043  
2044 The actual B<DBD::Informix> implementation has a number of extra lines of
2045 code, logs function entry and exit, reports the error from C<sqgetdbs()>,
2046 and uses C<#define>'d constants for the array sizes.
2047  
2048 =head3 The dbd_db_login6 method
2049  
2050 int dbd_db_login6_sv(SV* dbh, imp_dbh_t* imp_dbh, SV* dbname,
2051 SV* user, SV* auth, SV *attr);
2052  
2053 or
2054  
2055 int dbd_db_login6(SV* dbh, imp_dbh_t* imp_dbh, char* dbname,
2056 char* user, char* auth, SV *attr);
2057  
2058 This function will really connect to the database. The argument I<dbh>
2059 is the database handle. I<imp_dbh> is the pointer to the handles private
2060 data, as is I<imp_xxx> in C<dbd_drv_error()> above. The arguments
2061 I<dbname>, I<user>, I<auth> and I<attr> correspond to the arguments of
2062 the driver handle's C<connect()> method.
2063  
2064 You will quite often use database specific attributes here, that are
2065 specified in the DSN. I recommend you parse the DSN (using Perl) within
2066 the C<connect()> method and pass the segments of the DSN via the
2067 attributes parameter through C<_login()> to C<dbd_db_login6()>.
2068  
2069 Here's how you fetch them; as an example we use I<hostname> attribute,
2070 which can be up to 12 characters long excluding null terminator:
2071  
2072 SV** svp;
2073 STRLEN len;
2074 char* hostname;
2075  
2076 if ( (svp = DBD_ATTRIB_GET_SVP(attr, "drv_hostname", 12)) && SvTRUE(*svp)) {
2077 hostname = SvPV(*svp, len);
2078 DBD_ATTRIB_DELETE(attr, "drv_hostname", 12); /* avoid later STORE */
2079 } else {
2080 hostname = "localhost";
2081 }
2082  
2083 If you handle any driver specific attributes in the dbd_db_login6
2084 method you probably want to delete them from C<attr> (as above with
2085 DBD_ATTRIB_DELETE). If you don't delete your handled attributes DBI
2086 will call C<STORE> for each attribute after the connect/login and this
2087 is at best redundant for attributes you have already processed.
2088  
2089 B<Note: Until revision 11605 (post DBI 1.607), there was a problem with
2090 DBD_ATTRIBUTE_DELETE so unless you require a DBI version after 1.607
2091 you need to replace each DBD_ATTRIBUTE_DELETE call with:>
2092  
2093 hv_delete((HV*)SvRV(attr), key, key_len, G_DISCARD)
2094  
2095 Note that you can also obtain standard attributes such as I<AutoCommit> and
2096 I<ChopBlanks> from the attributes parameter, using C<DBD_ATTRIB_GET_IV> for
2097 integer attributes.
2098  
2099 If, for example, your database does not support transactions but
2100 I<AutoCommit> is set off (requesting transaction support), then you can
2101 emulate a 'failure to connect'.
2102  
2103 Now you should really connect to the database. In general, if the
2104 connection fails, it is best to ensure that all allocated resources are
2105 released so that the handle does not need to be destroyed separately. If
2106 you are successful (and possibly even if you fail but you have allocated
2107 some resources), you should use the following macros:
2108  
2109 DBIc_IMPSET_on(imp_dbh);
2110  
2111 This indicates that the driver (implementor) has allocated resources in
2112 the I<imp_dbh> structure and that the implementors private C<dbd_db_destroy()>
2113 function should be called when the handle is destroyed.
2114  
2115 DBIc_ACTIVE_on(imp_dbh);
2116  
2117 This indicates that the handle has an active connection to the server
2118 and that the C<dbd_db_disconnect()> function should be called before the
2119 handle is destroyed.
2120  
2121 Note that if you do need to fail, you should report errors via the I<drh>
2122 or I<imp_drh> rather than via I<dbh> or I<imp_dbh> because I<imp_dbh> will be
2123 destroyed by the failure, so errors recorded in that handle will not be
2124 visible to B<DBI>, and hence not the user either.
2125  
2126 Note too, that the function is passed I<dbh> and I<imp_dbh>, and there
2127 is a macro C<D_imp_drh_from_dbh> which can recover the I<imp_drh> from
2128 the I<imp_dbh>. However, there is no B<DBI> macro to provide you with the
2129 I<drh> given either the I<imp_dbh> or the I<dbh> or the I<imp_drh> (and
2130 there's no way to recover the I<dbh> given just the I<imp_dbh>).
2131  
2132 This suggests that, despite the above notes about C<dbd_drv_error()>
2133 taking an C<SV *>, it may be better to have two error routines, one
2134 taking I<imp_dbh> and one taking I<imp_drh> instead. With care, you can
2135 factor most of the formatting code out so that these are small routines
2136 calling a common error formatter. See the code in B<DBD::Informix>
2137 1.05.00 for more information.
2138  
2139 The C<dbd_db_login6()> function should return I<TRUE> for success,
2140 I<FALSE> otherwise.
2141  
2142 Drivers implemented long ago may define the five-argument function
2143 C<dbd_db_login()> instead of C<dbd_db_login6()>. The missing argument is
2144 the attributes. There are ways to work around the missing attributes,
2145 but they are ungainly; it is much better to use the 6-argument form.
2146 Even later drivers will use C<dbd_db_login6_sv()> which provides the
2147 dbname, username and password as SVs.
2148  
2149 =head3 The dbd_db_commit and dbd_db_rollback methods
2150  
2151 int dbd_db_commit(SV *dbh, imp_dbh_t *imp_dbh);
2152 int dbd_db_rollback(SV* dbh, imp_dbh_t* imp_dbh);
2153  
2154 These are used for commit and rollback. They should return I<TRUE> for
2155 success, I<FALSE> for error.
2156  
2157 The arguments I<dbh> and I<imp_dbh> are the same as for C<dbd_db_login6()>
2158 above; I will omit describing them in what follows, as they appear
2159 always.
2160  
2161 These functions should return I<TRUE> for success, I<FALSE> otherwise.
2162  
2163 =head3 The dbd_db_disconnect method
2164  
2165 This is your private part of the C<disconnect()> method. Any I<dbh> with
2166 the I<ACTIVE> flag on must be disconnected. (Note that you have to set
2167 it in C<dbd_db_connect()> above.)
2168  
2169 int dbd_db_disconnect(SV* dbh, imp_dbh_t* imp_dbh);
2170  
2171 The database handle will return I<TRUE> for success, I<FALSE> otherwise.
2172 In any case it should do a:
2173  
2174 DBIc_ACTIVE_off(imp_dbh);
2175  
2176 before returning so B<DBI> knows that C<dbd_db_disconnect()> was executed.
2177  
2178 Note that there's nothing to stop a I<dbh> being I<disconnected> while
2179 it still have active children. If your database API reacts badly to
2180 trying to use an I<sth> in this situation then you'll need to add code
2181 like this to all I<sth> methods:
2182  
2183 if (!DBIc_ACTIVE(DBIc_PARENT_COM(imp_sth)))
2184 return 0;
2185  
2186 Alternatively, you can add code to your driver to keep explicit track of
2187 the statement handles that exist for each database handle and arrange
2188 to destroy those handles before disconnecting from the database. There
2189 is code to do this in B<DBD::Informix>. Similar comments apply to the
2190 driver handle keeping track of all the database handles.
2191  
2192 Note that the code which destroys the subordinate handles should only
2193 release the associated database resources and mark the handles inactive;
2194 it does not attempt to free the actual handle structures.
2195  
2196 This function should return I<TRUE> for success, I<FALSE> otherwise, but
2197 it is not clear what anything can do about a failure.
2198  
2199 =head3 The dbd_db_discon_all method
2200  
2201 int dbd_discon_all (SV *drh, imp_drh_t *imp_drh);
2202  
2203 This function may be called at shutdown time. It should make
2204 best-efforts to disconnect all database handles - if possible. Some
2205 databases don't support that, in which case you can do nothing
2206 but return 'success'.
2207  
2208 This function should return I<TRUE> for success, I<FALSE> otherwise, but
2209 it is not clear what anything can do about a failure.
2210  
2211 =head3 The dbd_db_destroy method
2212  
2213 This is your private part of the database handle destructor. Any I<dbh> with
2214 the I<IMPSET> flag on must be destroyed, so that you can safely free
2215 resources. (Note that you have to set it in C<dbd_db_connect()> above.)
2216  
2217 void dbd_db_destroy(SV* dbh, imp_dbh_t* imp_dbh)
2218 {
2219 DBIc_IMPSET_off(imp_dbh);
2220 }
2221  
2222 The B<DBI> F<Driver.xst> code will have called C<dbd_db_disconnect()> for you,
2223 if the handle is still 'active', before calling C<dbd_db_destroy()>.
2224  
2225 Before returning the function must switch I<IMPSET> to off, so B<DBI> knows
2226 that the destructor was called.
2227  
2228 A B<DBI> handle doesn't keep references to its children. But children
2229 do keep references to their parents. So a database handle won't be
2230 C<DESTROY>'d until all its children have been C<DESTROY>'d.
2231  
2232 =head3 The dbd_db_STORE_attrib method
2233  
2234 This function handles
2235  
2236 $dbh->{$key} = $value;
2237  
2238 Its prototype is:
2239  
2240 int dbd_db_STORE_attrib(SV* dbh, imp_dbh_t* imp_dbh, SV* keysv,
2241 SV* valuesv);
2242  
2243 You do not handle all attributes; on the contrary, you should not handle
2244 B<DBI> attributes here: leave this to B<DBI>. (There are two exceptions,
2245 I<AutoCommit> and I<ChopBlanks>, which you should care about.)
2246  
2247 The return value is I<TRUE> if you have handled the attribute or I<FALSE>
2248 otherwise. If you are handling an attribute and something fails, you
2249 should call C<dbd_drv_error()>, so B<DBI> can raise exceptions, if desired.
2250 If C<dbd_drv_error()> returns, however, you have a problem: the user will
2251 never know about the error, because he typically will not check
2252 C<$dbh-E<gt>errstr()>.
2253  
2254 I cannot recommend a general way of going on, if C<dbd_drv_error()> returns,
2255 but there are examples where even the B<DBI> specification expects that
2256 you C<croak()>. (See the I<AutoCommit> method in L<DBI>.)
2257  
2258 If you have to store attributes, you should either use your private
2259 data structure I<imp_xxx>, the handle hash (via C<(HV*)SvRV(dbh)>), or use
2260 the private I<imp_data>.
2261  
2262 The first is best for internal C values like integers or pointers and
2263 where speed is important within the driver. The handle hash is best for
2264 values the user may want to get/set via driver-specific attributes.
2265 The private I<imp_data> is an additional C<SV> attached to the handle. You
2266 could think of it as an unnamed handle attribute. It's not normally used.
2267  
2268 =head3 The dbd_db_FETCH_attrib method
2269  
2270 This is the counterpart of C<dbd_db_STORE_attrib()>, needed for:
2271  
2272 $value = $dbh->{$key};
2273  
2274 Its prototype is:
2275  
2276 SV* dbd_db_FETCH_attrib(SV* dbh, imp_dbh_t* imp_dbh, SV* keysv);
2277  
2278 Unlike all previous methods this returns an C<SV> with the value. Note
2279 that you should normally execute C<sv_2mortal()>, if you return a nonconstant
2280 value. (Constant values are C<&sv_undef>, C<&sv_no> and C<&sv_yes>.)
2281  
2282 Note, that B<DBI> implements a caching algorithm for attribute values.
2283 If you think, that an attribute may be fetched, you store it in the
2284 I<dbh> itself:
2285  
2286 if (cacheit) /* cache value for later DBI 'quick' fetch? */
2287 hv_store((HV*)SvRV(dbh), key, kl, cachesv, 0);
2288  
2289 =head3 The dbd_st_prepare method
2290  
2291 This is the private part of the C<prepare()> method. Note that you
2292 B<must not> really execute the statement here. You may, however,
2293 preparse and validate the statement, or do similar things.
2294  
2295 int dbd_st_prepare(SV* sth, imp_sth_t* imp_sth, char* statement,
2296 SV* attribs);
2297  
2298 A typical, simple, possibility is to do nothing and rely on the perl
2299 C<prepare()> code that set the I<Statement> attribute on the handle. This
2300 attribute can then be used by C<dbd_st_execute()>.
2301  
2302 If the driver supports placeholders then the I<NUM_OF_PARAMS> attribute
2303 must be set correctly by C<dbd_st_prepare()>:
2304  
2305 DBIc_NUM_PARAMS(imp_sth) = ...
2306  
2307 If you can, you should also setup attributes like I<NUM_OF_FIELDS>, I<NAME>,
2308 etc. here, but B<DBI> doesn't require that - they can be deferred until
2309 execute() is called. However, if you do, document it.
2310  
2311 In any case you should set the I<IMPSET> flag, as you did in
2312 C<dbd_db_connect()> above:
2313  
2314 DBIc_IMPSET_on(imp_sth);
2315  
2316 =head3 The dbd_st_execute method
2317  
2318 This is where a statement will really be executed.
2319  
2320 int dbd_st_execute(SV* sth, imp_sth_t* imp_sth);
2321  
2322 C<dbd_st_execute> should return -2 for any error, -1 if the number of
2323 rows affected is unknown else it should be the number of affected
2324 (updated, inserted) rows.
2325  
2326 Note that you must be aware a statement may be executed repeatedly.
2327 Also, you should not expect that C<finish()> will be called between two
2328 executions, so you might need code, like the following, near the start
2329 of the function:
2330  
2331 if (DBIc_ACTIVE(imp_sth))
2332 dbd_st_finish(h, imp_sth);
2333  
2334 If your driver supports the binding of parameters (it should!), but the
2335 database doesn't, you must do it here. This can be done as follows:
2336  
2337 SV *svp;
2338 char* statement = DBD_ATTRIB_GET_PV(h, "Statement", 9, svp, "");
2339 int numParam = DBIc_NUM_PARAMS(imp_sth);
2340 int i;
2341  
2342 for (i = 0; i < numParam; i++)
2343 {
2344 char* value = dbd_db_get_param(sth, imp_sth, i);
2345 /* It is your drivers task to implement dbd_db_get_param, */
2346 /* it must be setup as a counterpart of dbd_bind_ph. */
2347 /* Look for '?' and replace it with 'value'. Difficult */
2348 /* task, note that you may have question marks inside */
2349 /* quotes and comments the like ... :-( */
2350 /* See DBD::mysql for an example. (Don't look too deep into */
2351 /* the example, you will notice where I was lazy ...) */
2352 }
2353  
2354 The next thing is to really execute the statement.
2355  
2356 Note that you must set the attributes I<NUM_OF_FIELDS>, I<NAME>, etc
2357 when the statement is successfully executed if the driver has not
2358 already done so: they may be used even before a potential C<fetchrow()>.
2359 In particular you have to tell B<DBI> the number of fields that the
2360 statement has, because it will be used by B<DBI> internally. Thus the
2361 function will typically ends with:
2362  
2363 if (isSelectStatement) {
2364 DBIc_NUM_FIELDS(imp_sth) = numFields;
2365 DBIc_ACTIVE_on(imp_sth);
2366 }
2367  
2368 It is important that the I<ACTIVE> flag only be set for C<SELECT>
2369 statements (or any other statements that can return many
2370 values from the database using a cursor-like mechanism). See
2371 C<dbd_db_connect()> above for more explanations.
2372  
2373 There plans for a preparse function to be provided by B<DBI>, but this has
2374 not reached fruition yet.
2375 Meantime, if you want to know how ugly it can get, try looking at the
2376 C<dbd_ix_preparse()> in B<DBD::Informix> F<dbdimp.ec> and the related
2377 functions in F<iustoken.c> and F<sqltoken.c>.
2378  
2379 =head3 The dbd_st_fetch method
2380  
2381 This function fetches a row of data. The row is stored in in an array,
2382 of C<SV>'s that B<DBI> prepares for you. This has two advantages: it is fast
2383 (you even reuse the C<SV>'s, so they don't have to be created after the
2384 first C<fetchrow()>), and it guarantees that B<DBI> handles C<bind_cols()> for
2385 you.
2386  
2387 What you do is the following:
2388  
2389 AV* av;
2390 int numFields = DBIc_NUM_FIELDS(imp_sth); /* Correct, if NUM_FIELDS
2391 is constant for this statement. There are drivers where this is
2392 not the case! */
2393 int chopBlanks = DBIc_is(imp_sth, DBIcf_ChopBlanks);
2394 int i;
2395  
2396 if (!fetch_new_row_of_data(...)) {
2397 ... /* check for error or end-of-data */
2398 DBIc_ACTIVE_off(imp_sth); /* turn off Active flag automatically */
2399 return Nullav;
2400 }
2401 /* get the fbav (field buffer array value) for this row */
2402 /* it is very important to only call this after you know */
2403 /* that you have a row of data to return. */
2404 av = DBIc_DBISTATE(imp_sth)->get_fbav(imp_sth);
2405 for (i = 0; i < numFields; i++) {
2406 SV* sv = fetch_a_field(..., i);
2407 if (chopBlanks && SvOK(sv) && type_is_blank_padded(field_type[i])) {
2408 /* Remove white space from end (only) of sv */
2409 }
2410 sv_setsv(AvARRAY(av)[i], sv); /* Note: (re)use! */
2411 }
2412 return av;
2413  
2414 There's no need to use a C<fetch_a_field()> function returning an C<SV*>.
2415 It's more common to use your database API functions to fetch the
2416 data as character strings and use code like this:
2417  
2418 sv_setpvn(AvARRAY(av)[i], char_ptr, char_count);
2419  
2420 C<NULL> values must be returned as C<undef>. You can use code like this:
2421  
2422 SvOK_off(AvARRAY(av)[i]);
2423  
2424 The function returns the C<AV> prepared by B<DBI> for success or C<Nullav>
2425 otherwise.
2426  
2427 *FIX ME* Discuss what happens when there's no more data to fetch.
2428 Are errors permitted if another fetch occurs after the first fetch
2429 that reports no more data. (Permitted, not required.)
2430  
2431 If an error occurs which leaves the I<$sth> in a state where remaining
2432 rows can't be fetched then I<Active> should be turned off before the
2433 method returns.
2434  
2435 =head3 The dbd_st_finish3 method
2436  
2437 The C<$sth-E<gt>finish()> method can be called if the user wishes to
2438 indicate that no more rows will be fetched even if the database has more
2439 rows to offer, and the B<DBI> code can call the function when handles are
2440 being destroyed. See the B<DBI> specification for more background details.
2441  
2442 In both circumstances, the B<DBI> code ends up calling the
2443 C<dbd_st_finish3()> method (if you provide a mapping for
2444 C<dbd_st_finish3()> in F<dbdimp.h>), or C<dbd_st_finish()> otherwise.
2445 The difference is that C<dbd_st_finish3()> takes a third argument which
2446 is an C<int> with the value 1 if it is being called from a C<destroy()>
2447 method and 0 otherwise.
2448  
2449 Note that B<DBI> v1.32 and earlier test on C<dbd_db_finish3()> to call
2450 C<dbd_st_finish3()>; if you provide C<dbd_st_finish3()>, either define
2451 C<dbd_db_finish3()> too, or insist on B<DBI> v1.33 or later.
2452  
2453 All it I<needs> to do is turn off the I<Active> flag for the I<sth>.
2454 It will only be called by F<Driver.xst> code, if the driver has set I<ACTIVE>
2455 to on for the I<sth>.
2456  
2457 Outline example:
2458  
2459 int dbd_st_finish3(SV* sth, imp_sth_t* imp_sth, int from_destroy) {
2460 if (DBIc_ACTIVE(imp_sth))
2461 {
2462 /* close cursor or equivalent action */
2463 DBIc_ACTIVE_off(imp_sth);
2464 }
2465 return 1;
2466 }
2467  
2468 The from_destroy parameter is true if C<dbd_st_finish3()> is being called
2469 from C<DESTROY()> - and so the statement is about to be destroyed.
2470 For many drivers there is no point in doing anything more than turning off
2471 the I<Active> flag in this case.
2472  
2473 The function returns I<TRUE> for success, I<FALSE> otherwise, but there isn't
2474 a lot anyone can do to recover if there is an error.
2475  
2476 =head3 The dbd_st_destroy method
2477  
2478 This function is the private part of the statement handle destructor.
2479  
2480 void dbd_st_destroy(SV* sth, imp_sth_t* imp_sth) {
2481 ... /* any clean-up that's needed */
2482 DBIc_IMPSET_off(imp_sth); /* let DBI know we've done it */
2483 }
2484  
2485 The B<DBI> F<Driver.xst> code will call C<dbd_st_finish()> for you, if the
2486 I<sth> has the I<ACTIVE> flag set, before calling C<dbd_st_destroy()>.
2487  
2488 =head3 The dbd_st_STORE_attrib and dbd_st_FETCH_attrib methods
2489  
2490 These functions correspond to C<dbd_db_STORE()> and C<dbd_db_FETCH()> attrib
2491 above, except that they are for statement handles.
2492 See above.
2493  
2494 int dbd_st_STORE_attrib(SV* sth, imp_sth_t* imp_sth, SV* keysv,
2495 SV* valuesv);
2496 SV* dbd_st_FETCH_attrib(SV* sth, imp_sth_t* imp_sth, SV* keysv);
2497  
2498 =head3 The dbd_bind_ph method
2499  
2500 This function is internally used by the C<bind_param()> method, the
2501 C<bind_param_inout()> method and by the B<DBI> F<Driver.xst> code if
2502 C<execute()> is called with any bind parameters.
2503  
2504 int dbd_bind_ph (SV *sth, imp_sth_t *imp_sth, SV *param,
2505 SV *value, IV sql_type, SV *attribs,
2506 int is_inout, IV maxlen);
2507  
2508 The I<param> argument holds an C<IV> with the parameter number (1, 2, ...).
2509 The I<value> argument is the parameter value and I<sql_type> is its type.
2510  
2511 If your driver does not support C<bind_param_inout()> then you should
2512 ignore I<maxlen> and croak if I<is_inout> is I<TRUE>.
2513  
2514 If your driver I<does> support C<bind_param_inout()> then you should
2515 note that I<value> is the C<SV> I<after> dereferencing the reference
2516 passed to C<bind_param_inout()>.
2517  
2518 In drivers of simple databases the function will, for example, store
2519 the value in a parameter array and use it later in C<dbd_st_execute()>.
2520 See the B<DBD::mysql> driver for an example.
2521  
2522 =head3 Implementing bind_param_inout support
2523  
2524 To provide support for parameters bound by reference rather than by
2525 value, the driver must do a number of things. First, and most
2526 importantly, it must note the references and stash them in its own
2527 driver structure. Secondly, when a value is bound to a column, the
2528 driver must discard any previous reference bound to the column. On
2529 each execute, the driver must evaluate the references and internally
2530 bind the values resulting from the references. This is only applicable
2531 if the user writes:
2532  
2533 $sth->execute;
2534  
2535 If the user writes:
2536  
2537 $sth->execute(@values);
2538  
2539 then B<DBI> automatically calls the binding code for each element of
2540 I<@values>. These calls are indistinguishable from explicit user calls to
2541 C<bind_param()>.
2542  
2543 =head2 C/XS version of Makefile.PL
2544  
2545 The F<Makefile.PL> file for a C/XS driver is similar to the code needed
2546 for a pure Perl driver, but there are a number of extra bits of
2547 information needed by the build system.
2548  
2549 For example, the attributes list passed to C<WriteMakefile()> needs
2550 to specify the object files that need to be compiled and built into
2551 the shared object (DLL). This is often, but not necessarily, just
2552 F<dbdimp.o> (unless that should be F<dbdimp.obj> because you're building
2553 on MS Windows).
2554  
2555 Note that you can reliably determine the extension of the object files
2556 from the I<$Config{obj_ext}> values, and there are many other useful pieces
2557 of configuration information lurking in that hash.
2558 You get access to it with:
2559  
2560 use Config;
2561  
2562 =head2 Methods which do not need to be written
2563  
2564 The B<DBI> code implements the majority of the methods which are accessed
2565 using the notation C<DBI-E<gt>function()>, the only exceptions being
2566 C<DBI-E<gt>connect()> and C<DBI-E<gt>data_sources()> which require
2567 support from the driver.
2568  
2569 The B<DBI> code implements the following documented driver, database and
2570 statement functions which do not need to be written by the B<DBD> driver
2571 writer.
2572  
2573 =over 4
2574  
2575 =item $dbh->do()
2576  
2577 The default implementation of this function prepares, executes and
2578 destroys the statement. This can be replaced if there is a better
2579 way to implement this, such as C<EXECUTE IMMEDIATE> which can
2580 sometimes be used if there are no parameters.
2581  
2582 =item $h->errstr()
2583  
2584 =item $h->err()
2585  
2586 =item $h->state()
2587  
2588 =item $h->trace()
2589  
2590 The B<DBD> driver does not need to worry about these routines at all.
2591  
2592 =item $h->{ChopBlanks}
2593  
2594 This attribute needs to be honored during C<fetch()> operations, but does
2595 not need to be handled by the attribute handling code.
2596  
2597 =item $h->{RaiseError}
2598  
2599 The B<DBD> driver does not need to worry about this attribute at all.
2600  
2601 =item $h->{PrintError}
2602  
2603 The B<DBD> driver does not need to worry about this attribute at all.
2604  
2605 =item $sth->bind_col()
2606  
2607 Assuming the driver uses the C<DBIc_DBISTATE(imp_xxh)-E<gt>get_fbav()>
2608 function (C drivers, see below), or the C<$sth-E<gt>_set_fbav($data)>
2609 method (Perl drivers) the driver does not need to do anything about this
2610 routine.
2611  
2612 =item $sth->bind_columns()
2613  
2614 Regardless of whether the driver uses
2615 C<DBIc_DBISTATE(imp_xxh)-E<gt>get_fbav()>, the driver does not need
2616 to do anything about this routine as it simply iteratively calls
2617 C<$sth-E<gt>bind_col()>.
2618  
2619 =back
2620  
2621 The B<DBI> code implements a default implementation of the following
2622 functions which do not need to be written by the B<DBD> driver writer
2623 unless the default implementation is incorrect for the Driver.
2624  
2625 =over 4
2626  
2627 =item $dbh->quote()
2628  
2629 This should only be written if the database does not accept the ANSI
2630 SQL standard for quoting strings, with the string enclosed in single
2631 quotes and any embedded single quotes replaced by two consecutive
2632 single quotes.
2633  
2634 For the two argument form of quote, you need to implement the
2635 C<type_info()> method to provide the information that quote needs.
2636  
2637 =item $dbh->ping()
2638  
2639 This should be implemented as a simple efficient way to determine
2640 whether the connection to the database is still alive. Typically
2641 code like this:
2642  
2643 sub ping {
2644 my $dbh = shift;
2645 $sth = $dbh->prepare_cached(q{
2646 select * from A_TABLE_NAME where 1=0
2647 }) or return 0;
2648 $sth->execute or return 0;
2649 $sth->finish;
2650 return 1;
2651 }
2652  
2653 where I<A_TABLE_NAME> is the name of a table that always exists (such as a
2654 database system catalogue).
2655  
2656 =item $drh->default_user
2657  
2658 The default implementation of default_user will get the database
2659 username and password fields from C<$ENV{DBI_USER}> and
2660 C<$ENV{DBI_PASS}>. You can override this method. It is called as
2661 follows:
2662  
2663 ($user, $pass) = $drh->default_user($user, $pass, $attr)
2664  
2665 =back
2666  
2667 =head1 METADATA METHODS
2668  
2669 The exposition above ignores the B<DBI> MetaData methods.
2670 The metadata methods are all associated with a database handle.
2671  
2672 =head2 Using DBI::DBD::Metadata
2673  
2674 The B<DBI::DBD::Metadata> module is a good semi-automatic way for the
2675 developer of a B<DBD> module to write the C<get_info()> and C<type_info()>
2676 functions quickly and accurately.
2677  
2678 =head3 Generating the get_info method
2679  
2680 Prior to B<DBI> v1.33, this existed as the method C<write_getinfo_pm()>
2681 in the B<DBI::DBD> module. From B<DBI> v1.33, it exists as the method
2682 C<write_getinfo_pm()> in the B<DBI::DBD::Metadata> module. This
2683 discussion assumes you have B<DBI> v1.33 or later.
2684  
2685 You examine the documentation for C<write_getinfo_pm()> using:
2686  
2687 perldoc DBI::DBD::Metadata
2688  
2689 To use it, you need a Perl B<DBI> driver for your database which implements
2690 the C<get_info()> method. In practice, this means you need to install
2691 B<DBD::ODBC>, an ODBC driver manager, and an ODBC driver for your
2692 database.
2693  
2694 With the pre-requisites in place, you might type:
2695  
2696 perl -MDBI::DBD::Metadata -we \
2697 "write_getinfo_pm (qw{ dbi:ODBC:foo_db username password Driver })"
2698  
2699 The procedure writes to standard output the code that should be added to
2700 your F<Driver.pm> file and the code that should be written to
2701 F<lib/DBD/Driver/GetInfo.pm>.
2702  
2703 You should review the output to ensure that it is sensible.
2704  
2705 =head3 Generating the type_info method
2706  
2707 Given the idea of the C<write_getinfo_pm()> method, it was not hard
2708 to devise a parallel method, C<write_typeinfo_pm()>, which does the
2709 analogous job for the B<DBI> C<type_info_all()> metadata method. The
2710 C<write_typeinfo_pm()> method was added to B<DBI> v1.33.
2711  
2712 You examine the documentation for C<write_typeinfo_pm()> using:
2713  
2714 perldoc DBI::DBD::Metadata
2715  
2716 The setup is exactly analogous to the mechanism described in
2717 L</Generating the get_info method>.
2718  
2719 With the pre-requisites in place, you might type:
2720  
2721 perl -MDBI::DBD::Metadata -we \
2722 "write_typeinfo_pm (qw{ dbi:ODBC:foo_db username password Driver })"
2723  
2724 The procedure writes to standard output the code that should be added to
2725 your F<Driver.pm> file and the code that should be written to
2726 F<lib/DBD/Driver/TypeInfo.pm>.
2727  
2728 You should review the output to ensure that it is sensible.
2729  
2730 =head2 Writing DBD::Driver::db::get_info
2731  
2732 If you use the B<DBI::DBD::Metadata> module, then the code you need is
2733 generated for you.
2734  
2735 If you decide not to use the B<DBI::DBD::Metadata> module, you
2736 should probably borrow the code from a driver that has done so (e.g.
2737 B<DBD::Informix> from version 1.05 onwards) and crib the code from
2738 there, or look at the code that generates that module and follow
2739 that. The method in F<Driver.pm> will be very simple; the method in
2740 F<lib/DBD/Driver/GetInfo.pm> is not very much more complex unless your
2741 DBMS itself is much more complex.
2742  
2743 Note that some of the B<DBI> utility methods rely on information from the
2744 C<get_info()> method to perform their operations correctly. See, for
2745 example, the C<quote_identifier()> and quote methods, discussed below.
2746  
2747 =head2 Writing DBD::Driver::db::type_info_all
2748  
2749 If you use the C<DBI::DBD::Metadata> module, then the code you need is
2750 generated for you.
2751  
2752 If you decide not to use the C<DBI::DBD::Metadata> module, you
2753 should probably borrow the code from a driver that has done so (e.g.
2754 C<DBD::Informix> from version 1.05 onwards) and crib the code from
2755 there, or look at the code that generates that module and follow
2756 that. The method in F<Driver.pm> will be very simple; the method in
2757 F<lib/DBD/Driver/TypeInfo.pm> is not very much more complex unless your
2758 DBMS itself is much more complex.
2759  
2760 =head2 Writing DBD::Driver::db::type_info
2761  
2762 The guidelines on writing this method are still not really clear.
2763 No sample implementation is available.
2764  
2765 =head2 Writing DBD::Driver::db::table_info
2766  
2767 *FIX ME* The guidelines on writing this method have not been written yet.
2768 No sample implementation is available.
2769  
2770 =head2 Writing DBD::Driver::db::column_info
2771  
2772 *FIX ME* The guidelines on writing this method have not been written yet.
2773 No sample implementation is available.
2774  
2775 =head2 Writing DBD::Driver::db::primary_key_info
2776  
2777 *FIX ME* The guidelines on writing this method have not been written yet.
2778 No sample implementation is available.
2779  
2780 =head2 Writing DBD::Driver::db::primary_key
2781  
2782 *FIX ME* The guidelines on writing this method have not been written yet.
2783 No sample implementation is available.
2784  
2785 =head2 Writing DBD::Driver::db::foreign_key_info
2786  
2787 *FIX ME* The guidelines on writing this method have not been written yet.
2788 No sample implementation is available.
2789  
2790 =head2 Writing DBD::Driver::db::tables
2791  
2792 This method generates an array of names in a format suitable for being
2793 embedded in SQL statements in places where a table name is expected.
2794  
2795 If your database hews close enough to the SQL standard or if you have
2796 implemented an appropriate C<table_info()> function and and the appropriate
2797 C<quote_identifier()> function, then the B<DBI> default version of this method
2798 will work for your driver too.
2799  
2800 Otherwise, you have to write a function yourself, such as:
2801  
2802 sub tables
2803 {
2804 my($dbh, $cat, $sch, $tab, $typ) = @_;
2805 my(@res);
2806 my($sth) = $dbh->table_info($cat, $sch, $tab, $typ);
2807 my(@arr);
2808 while (@arr = $sth->fetchrow_array)
2809 {
2810 push @res, $dbh->quote_identifier($arr[0], $arr[1], $arr[2]);
2811 }
2812 return @res;
2813 }
2814  
2815 See also the default implementation in F<DBI.pm>.
2816  
2817 =head2 Writing DBD::Driver::db::quote
2818  
2819 This method takes a value and converts it into a string suitable for
2820 embedding in an SQL statement as a string literal.
2821  
2822 If your DBMS accepts the SQL standard notation for strings (single
2823 quotes around the string as a whole with any embedded single quotes
2824 doubled up), then you do not need to write this method as B<DBI> provides a
2825 default method that does it for you.
2826  
2827 If your DBMS uses an alternative notation or escape mechanism, then you
2828 need to provide an equivalent function. For example, suppose your DBMS
2829 used C notation with double quotes around the string and backslashes
2830 escaping both double quotes and backslashes themselves. Then you might
2831 write the function as:
2832  
2833 sub quote
2834 {
2835 my($dbh, $str) = @_;
2836 $str =~ s/["\\]/\\$&/gmo;
2837 return qq{"$str"};
2838 }
2839  
2840 Handling newlines and other control characters is left as an exercise
2841 for the reader.
2842  
2843 This sample method ignores the I<$data_type> indicator which is the
2844 optional second argument to the method.
2845  
2846 =head2 Writing DBD::Driver::db::quote_identifier
2847  
2848 This method is called to ensure that the name of the given table (or
2849 other database object) can be embedded into an SQL statement without
2850 danger of misinterpretation. The result string should be usable in the
2851 text of an SQL statement as the identifier for a table.
2852  
2853 If your DBMS accepts the SQL standard notation for quoted identifiers
2854 (which uses double quotes around the identifier as a whole, with any
2855 embedded double quotes doubled up) and accepts I<"schema"."identifier">
2856 (and I<"catalog"."schema"."identifier"> when a catalog is specified), then
2857 you do not need to write this method as B<DBI> provides a default method
2858 that does it for you.
2859  
2860 In fact, even if your DBMS does not handle exactly that notation but
2861 you have implemented the C<get_info()> method and it gives the correct
2862 responses, then it will work for you. If your database is fussier, then
2863 you need to implement your own version of the function.
2864  
2865 For example, B<DBD::Informix> has to deal with an environment variable
2866 I<DELIMIDENT>. If it is not set, then the DBMS treats names enclosed in
2867 double quotes as strings rather than names, which is usually a syntax
2868 error. Additionally, the catalog portion of the name is separated from
2869 the schema and table by a different delimiter (colon instead of dot),
2870 and the catalog portion is never enclosed in quotes. (Fortunately,
2871 valid strings for the catalog will never contain weird characters that
2872 might need to be escaped, unless you count dots, dashes, slashes and
2873 at-signs as weird.) Finally, an Informix database can contain objects
2874 that cannot be accessed because they were created by a user with the
2875 I<DELIMIDENT> environment variable set, but the current user does not
2876 have it set. By design choice, the C<quote_identifier()> method encloses
2877 those identifiers in double quotes anyway, which generally triggers a
2878 syntax error, and the metadata methods which generate lists of tables
2879 etc omit those identifiers from the result sets.
2880  
2881 sub quote_identifier
2882 {
2883 my($dbh, $cat, $sch, $obj) = @_;
2884 my($rv) = "";
2885 my($qq) = (defined $ENV{DELIMIDENT}) ? '"' : '';
2886 $rv .= qq{$cat:} if (defined $cat);
2887 if (defined $sch)
2888 {
2889 if ($sch !~ m/^\w+$/o)
2890 {
2891 $qq = '"';
2892 $sch =~ s/$qq/$qq$qq/gm;
2893 }
2894 $rv .= qq{$qq$sch$qq.};
2895 }
2896 if (defined $obj)
2897 {
2898 if ($obj !~ m/^\w+$/o)
2899 {
2900 $qq = '"';
2901 $obj =~ s/$qq/$qq$qq/gm;
2902 }
2903 $rv .= qq{$qq$obj$qq};
2904 }
2905 return $rv;
2906 }
2907  
2908 Handling newlines and other control characters is left as an exercise
2909 for the reader.
2910  
2911 Note that there is an optional fourth parameter to this function which
2912 is a reference to a hash of attributes; this sample implementation
2913 ignores that.
2914  
2915 This sample implementation also ignores the single-argument variant of
2916 the method.
2917  
2918 =head1 TRACING
2919  
2920 Tracing in DBI is controlled with a combination of a trace level and a
2921 set of flags which together are known as the trace settings. The trace
2922 settings are stored in a single integer and divided into levels and
2923 flags by a set of masks (C<DBIc_TRACE_LEVEL_MASK> and
2924 C<DBIc_TRACE_FLAGS_MASK>).
2925  
2926 Each handle has it's own trace settings and so does the DBI. When you
2927 call a method the DBI merges the handles settings into its own for the
2928 duration of the call: the trace flags of the handle are OR'd into the
2929 trace flags of the DBI, and if the handle has a higher trace level
2930 then the DBI trace level is raised to match it. The previous DBI trace
2931 settings are restored when the called method returns.
2932  
2933 =head2 Trace Level
2934  
2935 The trace level is the first 4 bits of the trace settings (masked by
2936 C<DBIc_TRACE_FLAGS_MASK>) and represents trace levels of 1 to 15. Do
2937 not output anything at trace levels less than 3 as they are reserved
2938 for DBI.
2939  
2940 For advice on what to output at each level see "Trace Levels" in
2941 L<DBI>.
2942  
2943 To test for a trace level you can use the C<DBIc_TRACE_LEVEL> macro
2944 like this:
2945  
2946 if (DBIc_TRACE_LEVEL(imp_xxh) >= 2) {
2947 PerlIO_printf(DBIc_LOGPIO(imp_xxh), "foobar");
2948 }
2949  
2950 Also B<note> the use of PerlIO_printf which you should always use for
2951 tracing and never the C C<stdio.h> I/O functions.
2952  
2953 =head2 Trace Flags
2954  
2955 Trace flags are used to enable tracing of specific activities within
2956 the DBI and drivers. The DBI defines some trace flags and drivers can
2957 define others. DBI trace flag names begin with a capital letter and
2958 driver specific names begin with a lowercase letter. For a list of DBI
2959 defined trace flags see "Trace Flags" in L<DBI>.
2960  
2961 If you want to use private trace flags you'll probably want to be able
2962 to set them by name. Drivers are expected to override the
2963 parse_trace_flag (note the singular) and check if $trace_flag_name is
2964 a driver specific trace flags and, if not, then call the DBIs default
2965 parse_trace_flag(). To do that you'll need to define a
2966 parse_trace_flag() method like this:
2967  
2968 sub parse_trace_flag {
2969 my ($h, $name) = @_;
2970 return 0x01000000 if $name eq 'foo';
2971 return 0x02000000 if $name eq 'bar';
2972 return 0x04000000 if $name eq 'baz';
2973 return 0x08000000 if $name eq 'boo';
2974 return 0x10000000 if $name eq 'bop';
2975 return $h->SUPER::parse_trace_flag($name);
2976 }
2977  
2978 All private flag names must be lowercase, and all private flags must
2979 be in the top 8 of the 32 bits of C<DBIc_TRACE_FLAGS(imp)> i.e.,
2980 0xFF000000.
2981  
2982 If you've defined a parse_trace_flag() method in ::db you'll also want
2983 it in ::st, so just alias it in:
2984  
2985 *parse_trace_flag = \&DBD::foo:db::parse_trace_flag;
2986  
2987 You may want to act on the current 'SQL' trace flag that DBI defines
2988 to output SQL prepared/executed as DBI currently does not do SQL
2989 tracing.
2990  
2991 =head2 Trace Macros
2992  
2993 Access to the trace level and trace flags is via a set of macros.
2994  
2995 DBIc_TRACE_SETTINGS(imp) returns the trace settings
2996 DBIc_TRACE_LEVEL(imp) returns the trace level
2997 DBIc_TRACE_FLAGS(imp) returns the trace flags
2998 DBIc_TRACE(imp, flags, flaglevel, level)
2999  
3000 e.g.,
3001  
3002 DBIc_TRACE(imp, 0, 0, 4)
3003 if level >= 4
3004  
3005 DBIc_TRACE(imp, DBDtf_FOO, 2, 4)
3006 if tracing DBDtf_FOO & level>=2 or level>=4
3007  
3008 DBIc_TRACE(imp, DBDtf_FOO, 2, 0)
3009 as above but never trace just due to level
3010  
3011 =head1 WRITING AN EMULATION LAYER FOR AN OLD PERL INTERFACE
3012  
3013 Study F<Oraperl.pm> (supplied with B<DBD::Oracle>) and F<Ingperl.pm> (supplied
3014 with B<DBD::Ingres>) and the corresponding I<dbdimp.c> files for ideas.
3015  
3016 Note that the emulation code sets C<$dbh-E<gt>{CompatMode} = 1;> for each
3017 connection so that the internals of the driver can implement behaviour
3018 compatible with the old interface when dealing with those handles.
3019  
3020 =head2 Setting emulation perl variables
3021  
3022 For example, ingperl has a I<$sql_rowcount> variable. Rather than try
3023 to manually update this in F<Ingperl.pm> it can be done faster in C code.
3024 In C<dbd_init()>:
3025  
3026 sql_rowcount = perl_get_sv("Ingperl::sql_rowcount", GV_ADDMULTI);
3027  
3028 In the relevant places do:
3029  
3030 if (DBIc_COMPAT(imp_sth)) /* only do this for compatibility mode handles */
3031 sv_setiv(sql_rowcount, the_row_count);
3032  
3033 =head1 OTHER MISCELLANEOUS INFORMATION
3034  
3035 =head2 The imp_xyz_t types
3036  
3037 Any handle has a corresponding C structure filled with private data.
3038 Some of this data is reserved for use by B<DBI> (except for using the
3039 DBIc macros below), some is for you. See the description of the
3040 F<dbdimp.h> file above for examples. Most functions in F<dbdimp.c>
3041 are passed both the handle C<xyz> and a pointer to C<imp_xyz>. In
3042 rare cases, however, you may use the following macros:
3043  
3044 =over 4
3045  
3046 =item D_imp_dbh(dbh)
3047  
3048 Given a function argument I<dbh>, declare a variable I<imp_dbh> and
3049 initialize it with a pointer to the handles private data. Note: This
3050 must be a part of the function header, because it declares a variable.
3051  
3052 =item D_imp_sth(sth)
3053  
3054 Likewise for statement handles.
3055  
3056 =item D_imp_xxx(h)
3057  
3058 Given any handle, declare a variable I<imp_xxx> and initialize it
3059 with a pointer to the handles private data. It is safe, for example,
3060 to cast I<imp_xxx> to C<imp_dbh_t*>, if C<DBIc_TYPE(imp_xxx) == DBIt_DB>.
3061 (You can also call C<sv_derived_from(h, "DBI::db")>, but that's much
3062 slower.)
3063  
3064 =item D_imp_dbh_from_sth
3065  
3066 Given a I<imp_sth>, declare a variable I<imp_dbh> and initialize it with a
3067 pointer to the parent database handle's implementors structure.
3068  
3069 =back
3070  
3071 =head2 Using DBIc_IMPSET_on
3072  
3073 The driver code which initializes a handle should use C<DBIc_IMPSET_on()>
3074 as soon as its state is such that the cleanup code must be called.
3075 When this happens is determined by your driver code.
3076  
3077 B<Failure to call this can lead to corruption of data structures.>
3078  
3079 For example, B<DBD::Informix> maintains a linked list of database
3080 handles in the driver, and within each handle, a linked list of
3081 statements. Once a statement is added to the linked list, it is crucial
3082 that it is cleaned up (removed from the list). When I<DBIc_IMPSET_on()>
3083 was being called too late, it was able to cause all sorts of problems.
3084  
3085 =head2 Using DBIc_is(), DBIc_has(), DBIc_on() and DBIc_off()
3086  
3087 Once upon a long time ago, the only way of handling the internal B<DBI>
3088 boolean flags/attributes was through macros such as:
3089  
3090 DBIc_WARN DBIc_WARN_on DBIc_WARN_off
3091 DBIc_COMPAT DBIc_COMPAT_on DBIc_COMPAT_off
3092  
3093 Each of these took an I<imp_xxh> pointer as an argument.
3094  
3095 Since then, new attributes have been added such as I<ChopBlanks>,
3096 I<RaiseError> and I<PrintError>, and these do not have the full set of
3097 macros. The approved method for handling these is now the four macros:
3098  
3099 DBIc_is(imp, flag)
3100 DBIc_has(imp, flag) an alias for DBIc_is
3101 DBIc_on(imp, flag)
3102 DBIc_off(imp, flag)
3103 DBIc_set(imp, flag, on) set if on is true, else clear
3104  
3105 Consequently, the C<DBIc_XXXXX> family of macros is now mostly deprecated
3106 and new drivers should avoid using them, even though the older drivers
3107 will probably continue to do so for quite a while yet. However...
3108  
3109 There is an I<important exception> to that. The I<ACTIVE> and I<IMPSET>
3110 flags should be set via the C<DBIc_ACTIVE_on()> and C<DBIc_IMPSET_on()> macros,
3111 and unset via the C<DBIc_ACTIVE_off()> and C<DBIc_IMPSET_off()> macros.
3112  
3113 =head2 Using the get_fbav() method
3114  
3115 B<THIS IS CRITICAL for C/XS drivers>.
3116  
3117 The C<$sth-E<gt>bind_col()> and C<$sth-E<gt>bind_columns()> documented
3118 in the B<DBI> specification do not have to be implemented by the driver
3119 writer because B<DBI> takes care of the details for you.
3120  
3121 However, the key to ensuring that bound columns work is to call the
3122 function C<DBIc_DBISTATE(imp_xxh)-E<gt>get_fbav()> in the code which
3123 fetches a row of data.
3124  
3125 This returns an C<AV>, and each element of the C<AV> contains the C<SV> which
3126 should be set to contain the returned data.
3127  
3128 The pure Perl equivalent is the C<$sth-E<gt>_set_fbav($data)> method, as
3129 described in the part on pure Perl drivers.
3130  
3131 =head2 Casting strings to Perl types based on a SQL type
3132  
3133 DBI from 1.611 (and DBIXS_REVISION 13606) defines the
3134 sql_type_cast_svpv method which may be used to cast a string
3135 representation of a value to a more specific Perl type based on a SQL
3136 type. You should consider using this method when processing bound
3137 column data as it provides some support for the TYPE bind_col
3138 attribute which is rarely used in drivers.
3139  
3140 int sql_type_cast_svpv(pTHX_ SV *sv, int sql_type, U32 flags, void *v)
3141  
3142 C<sv> is what you would like cast, C<sql_type> is one of the DBI defined
3143 SQL types (e.g., C<SQL_INTEGER>) and C<flags> is a bitmask as follows:
3144  
3145 =over
3146  
3147 =item DBIstcf_STRICT
3148  
3149 If set this indicates you want an error state returned if the cast
3150 cannot be performed.
3151  
3152 =item DBIstcf_DISCARD_STRING
3153  
3154 If set and the pv portion of the C<sv> is cast then this will cause
3155 sv's pv to be freed up.
3156  
3157 =back
3158  
3159 sql_type_cast_svpv returns the following states:
3160  
3161 -2 sql_type is not handled - sv not changed
3162 -1 sv is undef, sv not changed
3163 0 sv could not be cast cleanly and DBIstcf_STRICT was specified
3164 1 sv could not be case cleanly and DBIstcf_STRICT was not specified
3165 2 sv was cast ok
3166  
3167 The current implementation of sql_type_cast_svpv supports
3168 C<SQL_INTEGER>, C<SQL_DOUBLE> and C<SQL_NUMERIC>. C<SQL_INTEGER> uses
3169 sv_2iv and hence may set IV, UV or NV depending on the
3170 number. C<SQL_DOUBLE> uses sv_2nv so may set NV and C<SQL_NUMERIC>
3171 will set IV or UV or NV.
3172  
3173 DBIstcf_STRICT should be implemented as the StrictlyTyped attribute
3174 and DBIstcf_DISCARD_STRING implemented as the DiscardString attribute
3175 to the bind_col method and both default to off.
3176  
3177 See DBD::Oracle for an example of how this is used.
3178  
3179 =head1 SUBCLASSING DBI DRIVERS
3180  
3181 This is definitely an open subject. It can be done, as demonstrated by
3182 the B<DBD::File> driver, but it is not as simple as one might think.
3183  
3184 (Note that this topic is different from subclassing the B<DBI>. For an
3185 example of that, see the F<t/subclass.t> file supplied with the B<DBI>.)
3186  
3187 The main problem is that the I<dbh>'s and I<sth>'s that your C<connect()> and
3188 C<prepare()> methods return are not instances of your B<DBD::Driver::db>
3189 or B<DBD::Driver::st> packages, they are not even derived from it.
3190 Instead they are instances of the B<DBI::db> or B<DBI::st> classes or
3191 a derived subclass. Thus, if you write a method C<mymethod()> and do a
3192  
3193 $dbh->mymethod()
3194  
3195 then the autoloader will search for that method in the package B<DBI::db>.
3196 Of course you can instead to a
3197  
3198 $dbh->func('mymethod')
3199  
3200 and that will indeed work, even if C<mymethod()> is inherited, but not
3201 without additional work. Setting I<@ISA> is not sufficient.
3202  
3203 =head2 Overwriting methods
3204  
3205 The first problem is, that the C<connect()> method has no idea of
3206 subclasses. For example, you cannot implement base class and subclass
3207 in the same file: The C<install_driver()> method wants to do a
3208  
3209 require DBD::Driver;
3210  
3211 In particular, your subclass B<has> to be a separate driver, from
3212 the view of B<DBI>, and you cannot share driver handles.
3213  
3214 Of course that's not much of a problem. You should even be able
3215 to inherit the base classes C<connect()> method. But you cannot
3216 simply overwrite the method, unless you do something like this,
3217 quoted from B<DBD::CSV>:
3218  
3219 sub connect ($$;$$$) {
3220 my ($drh, $dbname, $user, $auth, $attr) = @_;
3221  
3222 my $this = $drh->DBD::File::dr::connect($dbname, $user, $auth, $attr);
3223 if (!exists($this->{csv_tables})) {
3224 $this->{csv_tables} = {};
3225 }
3226  
3227 $this;
3228 }
3229  
3230 Note that we cannot do a
3231  
3232 $drh->SUPER::connect($dbname, $user, $auth, $attr);
3233  
3234 as we would usually do in a an OO environment, because I<$drh> is an instance
3235 of B<DBI::dr>. And note, that the C<connect()> method of B<DBD::File> is
3236 able to handle subclass attributes. See the description of Pure Perl
3237 drivers above.
3238  
3239 It is essential that you always call superclass method in the above
3240 manner. However, that should do.
3241  
3242 =head2 Attribute handling
3243  
3244 Fortunately the B<DBI> specifications allow a simple, but still
3245 performant way of handling attributes. The idea is based on the
3246 convention that any driver uses a prefix I<driver_> for its private
3247 methods. Thus it's always clear whether to pass attributes to the super
3248 class or not. For example, consider this C<STORE()> method from the
3249 B<DBD::CSV> class:
3250  
3251 sub STORE {
3252 my ($dbh, $attr, $val) = @_;
3253 if ($attr !~ /^driver_/) {
3254 return $dbh->DBD::File::db::STORE($attr, $val);
3255 }
3256 if ($attr eq 'driver_foo') {
3257 ...
3258 }
3259  
3260 =cut
3261  
3262 use Exporter ();
3263 use Config qw(%Config);
3264 use Carp;
3265 use Cwd;
3266 use File::Spec;
3267 use strict;
3268  
3269 BEGIN {
3270 if ($^O eq 'VMS') {
3271 require vmsish;
3272 import vmsish;
3273 require VMS::Filespec;
3274 import VMS::Filespec;
3275 }
3276 else {
3277 *vmsify = sub { return $_[0] };
3278 *unixify = sub { return $_[0] };
3279 }
3280 }
3281  
3282 our @ISA = qw(Exporter);
3283  
3284 our @EXPORT = qw(
3285 dbd_dbi_dir
3286 dbd_dbi_arch_dir
3287 dbd_edit_mm_attribs
3288 dbd_postamble
3289 );
3290  
3291 our $is_dbi;
3292 BEGIN {
3293 $is_dbi = (-r 'DBI.pm' && -r 'DBI.xs' && -r 'DBIXS.h');
3294 require DBI unless $is_dbi;
3295 }
3296  
3297 my $done_inst_checks;
3298  
3299 sub _inst_checks {
3300 return if $done_inst_checks++;
3301 my $cwd = cwd();
3302 if ($cwd =~ /\Q$Config{path_sep}/) {
3303 warn "*** Warning: Path separator characters (`$Config{path_sep}') ",
3304 "in the current directory path ($cwd) may cause problems\a\n\n";
3305 sleep 2;
3306 }
3307 if ($cwd =~ /\s/) {
3308 warn "*** Warning: whitespace characters ",
3309 "in the current directory path ($cwd) may cause problems\a\n\n";
3310 sleep 2;
3311 }
3312 if ( $^O eq 'MSWin32'
3313 && $Config{cc} eq 'cl'
3314 && !(exists $ENV{'LIB'} && exists $ENV{'INCLUDE'}))
3315 {
3316 die <<EOT;
3317 *** You're using Microsoft Visual C++ compiler or similar but
3318 the LIB and INCLUDE environment variables are not both set.
3319  
3320 You need to run the VCVARS32.BAT batch file that was supplied
3321 with the compiler before you can use it.
3322  
3323 A copy of vcvars32.bat can typically be found in the following
3324 directories under your Visual Studio install directory:
3325 Visual C++ 6.0: vc98\\bin
3326 Visual Studio .NET: vc7\\bin
3327  
3328 Find it, run it, then retry this.
3329  
3330 If you think this error is not correct then just set the LIB and
3331 INCLUDE environment variables to some value to disable the check.
3332 EOT
3333 }
3334 }
3335  
3336 sub dbd_edit_mm_attribs {
3337 # this both edits the attribs in-place and returns the flattened attribs
3338 my $mm_attr = shift;
3339 my $dbd_attr = shift || {};
3340 croak "dbd_edit_mm_attribs( \%makemaker [, \%other ]): too many parameters"
3341 if @_;
3342 _inst_checks();
3343  
3344 # what can be done
3345 my %test_variants = (
3346 p => { name => "DBI::PurePerl",
3347 match => qr/^\d/,
3348 add => [ '$ENV{DBI_PUREPERL} = 2',
3349 'END { delete $ENV{DBI_PUREPERL}; }' ],
3350 },
3351 g => { name => "DBD::Gofer",
3352 match => qr/^\d/,
3353 add => [ q{$ENV{DBI_AUTOPROXY} = 'dbi:Gofer:transport=null;policy=pedantic'},
3354 q|END { delete $ENV{DBI_AUTOPROXY}; }| ],
3355 },
3356 n => { name => "DBI::SQL::Nano",
3357 match => qr/^(?:48dbi_dbd_sqlengine|49dbd_file|5\ddbm_\w+|85gofer)\.t$/,
3358 add => [ q{$ENV{DBI_SQL_NANO} = 1},
3359 q|END { delete $ENV{DBI_SQL_NANO}; }| ],
3360 },
3361 # mx => { name => "DBD::Multiplex",
3362 # add => [ q{local $ENV{DBI_AUTOPROXY} = 'dbi:Multiplex:';} ],
3363 # }
3364 # px => { name => "DBD::Proxy",
3365 # need mechanism for starting/stopping the proxy server
3366 # add => [ q{local $ENV{DBI_AUTOPROXY} = 'dbi:Proxy:XXX';} ],
3367 # }
3368 );
3369  
3370 # decide what needs doing
3371 $dbd_attr->{create_pp_tests} or delete $test_variants{p};
3372 $dbd_attr->{create_nano_tests} or delete $test_variants{n};
3373 $dbd_attr->{create_gap_tests} or delete $test_variants{g};
3374  
3375 # expand for all combinations
3376 my @all_keys = my @tv_keys = sort keys %test_variants;
3377 while( @tv_keys ) {
3378 my $cur_key = shift @tv_keys;
3379 last if( 1 < length $cur_key );
3380 my @new_keys;
3381 foreach my $remain (@tv_keys) {
3382 push @new_keys, $cur_key . $remain unless $remain =~ /$cur_key/;
3383 }
3384 push @tv_keys, @new_keys;
3385 push @all_keys, @new_keys;
3386 }
3387  
3388 my %uniq_keys;
3389 foreach my $key (@all_keys) {
3390 @tv_keys = sort split //, $key;
3391 my $ordered = join( '', @tv_keys );
3392 $uniq_keys{$ordered} = 1;
3393 }
3394 @all_keys = sort { length $a <=> length $b or $a cmp $b } keys %uniq_keys;
3395  
3396 # do whatever needs doing
3397 if( keys %test_variants ) {
3398 # XXX need to convert this to work within the generated Makefile
3399 # so 'make' creates them and 'make clean' deletes them
3400 opendir DIR, 't' or die "Can't read 't' directory: $!";
3401 my @tests = grep { /\.t$/ } readdir DIR;
3402 closedir DIR;
3403  
3404 foreach my $test_combo (@all_keys) {
3405 @tv_keys = split //, $test_combo;
3406 my @test_names = map { $test_variants{$_}->{name} } @tv_keys;
3407 printf "Creating test wrappers for " . join( " + ", @test_names ) . ":\n";
3408 my @test_matches = map { $test_variants{$_}->{match} } @tv_keys;
3409 my @test_adds;
3410 foreach my $test_add ( map { $test_variants{$_}->{add} } @tv_keys) {
3411 push @test_adds, @$test_add;
3412 }
3413 my $v_type = $test_combo;
3414 $v_type = 'x' . $v_type if length( $v_type ) > 1;
3415  
3416 TEST:
3417 foreach my $test (sort @tests) {
3418 foreach my $match (@test_matches) {
3419 next TEST if $test !~ $match;
3420 }
3421 my $usethr = ($test =~ /(\d+|\b)thr/ && $Config{useithreads});
3422 my $v_test = "t/zv${v_type}_$test";
3423 my $v_perl = ($test =~ /taint/) ? "perl -wT" : "perl -w";
3424 printf "%s %s\n", $v_test, ($usethr) ? "(use threads)" : "";
3425 open PPT, ">$v_test" or warn "Can't create $v_test: $!";
3426 print PPT "#!$v_perl\n";
3427 print PPT "use threads;\n" if $usethr;
3428 print PPT "$_;\n" foreach @test_adds;
3429 print PPT "require './t/$test'; # or warn \$!;\n";
3430 close PPT or warn "Error writing $v_test: $!";
3431 }
3432 }
3433 }
3434 return %$mm_attr;
3435 }
3436  
3437 sub dbd_dbi_dir {
3438 _inst_checks();
3439 return '.' if $is_dbi;
3440 my $dbidir = $INC{'DBI.pm'} || die "DBI.pm not in %INC!";
3441 $dbidir =~ s:/DBI\.pm$::;
3442 return $dbidir;
3443 }
3444  
3445 sub dbd_dbi_arch_dir {
3446 _inst_checks();
3447 return '$(INST_ARCHAUTODIR)' if $is_dbi;
3448 my $dbidir = dbd_dbi_dir();
3449 my %seen;
3450 my @try = grep { not $seen{$_}++ } map { vmsify( unixify($_) . "/auto/DBI/" ) } @INC;
3451 my @xst = grep { -f vmsify( unixify($_) . "/Driver.xst" ) } @try;
3452 Carp::croak("Unable to locate Driver.xst in @try") unless @xst;
3453 Carp::carp( "Multiple copies of Driver.xst found in: @xst") if @xst > 1;
3454 print "Using DBI $DBI::VERSION (for perl $] on $Config{archname}) installed in $xst[0]\n";
3455 return File::Spec->canonpath($xst[0]);
3456 }
3457  
3458 sub dbd_postamble {
3459 my $self = shift;
3460 _inst_checks();
3461 my $dbi_instarch_dir = ($is_dbi) ? "." : dbd_dbi_arch_dir();
3462 my $dbi_driver_xst= File::Spec->catfile($dbi_instarch_dir, 'Driver.xst');
3463 my $xstf_h = File::Spec->catfile($dbi_instarch_dir, 'Driver_xst.h');
3464  
3465 # we must be careful of quotes, especially for Win32 here.
3466 return '
3467 # --- This section was generated by DBI::DBD::dbd_postamble()
3468 DBI_INSTARCH_DIR='.$dbi_instarch_dir.'
3469 DBI_DRIVER_XST='.$dbi_driver_xst.'
3470  
3471 # The main dependency (technically correct but probably not used)
3472 $(BASEEXT).c: $(BASEEXT).xsi
3473  
3474 # This dependency is needed since MakeMaker uses the .xs.o rule
3475 $(BASEEXT)$(OBJ_EXT): $(BASEEXT).xsi
3476  
3477 $(BASEEXT).xsi: $(DBI_DRIVER_XST) '.$xstf_h.'
3478 $(PERL) -p -e "s/~DRIVER~/$(BASEEXT)/g" $(DBI_DRIVER_XST) > $(BASEEXT).xsi
3479  
3480 # ---
3481 ';
3482 }
3483  
3484 package DBDI; # just to reserve it via PAUSE for the future
3485  
3486 1;
3487  
3488 __END__