[ Index ] |
PHP Cross Reference of Unnamed Project |
[Summary view] [Print] [Text view]
1 # $Id: DBI.pm 11570 2008-07-22 21:45:16Z timbo $ 2 # vim: ts=8:sw=4:noet 3 # 4 # Copyright (c) 1994-2008 Tim Bunce Ireland 5 # 6 # See COPYRIGHT section in pod text below for usage and distribution rights. 7 # 8 9 require 5.006_00; 10 11 BEGIN { 12 $DBI::VERSION = "1.607"; # ==> ALSO update the version in the pod text below! 13 } 14 15 =head1 NAME 16 17 DBI - Database independent interface for Perl 18 19 =head1 SYNOPSIS 20 21 use DBI; 22 23 @driver_names = DBI->available_drivers; 24 %drivers = DBI->installed_drivers; 25 @data_sources = DBI->data_sources($driver_name, \%attr); 26 27 $dbh = DBI->connect($data_source, $username, $auth, \%attr); 28 29 $rv = $dbh->do($statement); 30 $rv = $dbh->do($statement, \%attr); 31 $rv = $dbh->do($statement, \%attr, @bind_values); 32 33 $ary_ref = $dbh->selectall_arrayref($statement); 34 $hash_ref = $dbh->selectall_hashref($statement, $key_field); 35 36 $ary_ref = $dbh->selectcol_arrayref($statement); 37 $ary_ref = $dbh->selectcol_arrayref($statement, \%attr); 38 39 @row_ary = $dbh->selectrow_array($statement); 40 $ary_ref = $dbh->selectrow_arrayref($statement); 41 $hash_ref = $dbh->selectrow_hashref($statement); 42 43 $sth = $dbh->prepare($statement); 44 $sth = $dbh->prepare_cached($statement); 45 46 $rc = $sth->bind_param($p_num, $bind_value); 47 $rc = $sth->bind_param($p_num, $bind_value, $bind_type); 48 $rc = $sth->bind_param($p_num, $bind_value, \%attr); 49 50 $rv = $sth->execute; 51 $rv = $sth->execute(@bind_values); 52 $rv = $sth->execute_array(\%attr, ...); 53 54 $rc = $sth->bind_col($col_num, \$col_variable); 55 $rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind); 56 57 @row_ary = $sth->fetchrow_array; 58 $ary_ref = $sth->fetchrow_arrayref; 59 $hash_ref = $sth->fetchrow_hashref; 60 61 $ary_ref = $sth->fetchall_arrayref; 62 $ary_ref = $sth->fetchall_arrayref( $slice, $max_rows ); 63 64 $hash_ref = $sth->fetchall_hashref( $key_field ); 65 66 $rv = $sth->rows; 67 68 $rc = $dbh->begin_work; 69 $rc = $dbh->commit; 70 $rc = $dbh->rollback; 71 72 $quoted_string = $dbh->quote($string); 73 74 $rc = $h->err; 75 $str = $h->errstr; 76 $rv = $h->state; 77 78 $rc = $dbh->disconnect; 79 80 I<The synopsis above only lists the major methods and parameters.> 81 82 83 =head2 GETTING HELP 84 85 If you have questions about DBI, or DBD driver modules, you can get 86 help from the I<dbi-users@perl.org> mailing list. You don't have to subscribe 87 to the list in order to post, though I'd recommend it. You can get help on 88 subscribing and using the list by emailing I<dbi-users-help@perl.org>. 89 90 I don't recommend the DBI cpanform (at http://www.cpanforum.com/dist/DBI) 91 because relatively few people read it compared with dbi-users@perl.org. 92 93 To help you make the best use of the dbi-users mailing list, 94 and any other lists or forums you may use, I I<strongly> 95 recommend that you read "How To Ask Questions The Smart Way" 96 by Eric Raymond: L<http://www.catb.org/~esr/faqs/smart-questions.html>. 97 98 If you think you've found a bug then please also read 99 "How to Report Bugs Effectively" by Simon Tatham: 100 L<http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>. 101 102 The DBI home page at L<http://dbi.perl.org/> and the DBI FAQ 103 at L<http://faq.dbi-support.com/> are always worth a visit. 104 They include links to other resources. 105 106 Before asking any questions, reread this document, consult the 107 archives and read the DBI FAQ. The archives are listed 108 at the end of this document and on the DBI home page. 109 110 This document often uses terms like I<references>, I<objects>, 111 I<methods>. If you're not familar with those terms then it would 112 be a good idea to read at least the following perl manuals first: 113 L<perlreftut>, L<perldsc>, L<perllol>, and L<perlboot>. 114 115 Please note that Tim Bunce does not maintain the mailing lists or the 116 web page (generous volunteers do that). So please don't send mail 117 directly to him; he just doesn't have the time to answer questions 118 personally. The I<dbi-users> mailing list has lots of experienced 119 people who should be able to help you if you need it. If you do email 120 Tim he's very likely to just forward it to the mailing list. 121 122 =head2 NOTES 123 124 This is the DBI specification that corresponds to the DBI version 1.607 125 ($Revision: 11570 $). 126 127 The DBI is evolving at a steady pace, so it's good to check that 128 you have the latest copy. 129 130 The significant user-visible changes in each release are documented 131 in the L<DBI::Changes> module so you can read them by executing 132 C<perldoc DBI::Changes>. 133 134 Some DBI changes require changes in the drivers, but the drivers 135 can take some time to catch up. Newer versions of the DBI have 136 added features that may not yet be supported by the drivers you 137 use. Talk to the authors of your drivers if you need a new feature 138 that's not yet supported. 139 140 Features added after DBI 1.21 (February 2002) are marked in the 141 text with the version number of the DBI release they first appeared in. 142 143 Extensions to the DBI API often use the C<DBIx::*> namespace. 144 See L</Naming Conventions and Name Space>. DBI extension modules 145 can be found at L<http://search.cpan.org/search?mode=module&query=DBIx>. 146 And all modules related to the DBI can be found at 147 L<http://search.cpan.org/search?query=DBI&mode=all>. 148 149 =cut 150 151 # The POD text continues at the end of the file. 152 153 154 package DBI; 155 156 use Carp(); 157 use DynaLoader (); 158 use Exporter (); 159 160 BEGIN { 161 @ISA = qw(Exporter DynaLoader); 162 163 # Make some utility functions available if asked for 164 @EXPORT = (); # we export nothing by default 165 @EXPORT_OK = qw(%DBI %DBI_methods hash); # also populated by export_ok_tags: 166 %EXPORT_TAGS = ( 167 sql_types => [ qw( 168 SQL_GUID 169 SQL_WLONGVARCHAR 170 SQL_WVARCHAR 171 SQL_WCHAR 172 SQL_BIGINT 173 SQL_BIT 174 SQL_TINYINT 175 SQL_LONGVARBINARY 176 SQL_VARBINARY 177 SQL_BINARY 178 SQL_LONGVARCHAR 179 SQL_UNKNOWN_TYPE 180 SQL_ALL_TYPES 181 SQL_CHAR 182 SQL_NUMERIC 183 SQL_DECIMAL 184 SQL_INTEGER 185 SQL_SMALLINT 186 SQL_FLOAT 187 SQL_REAL 188 SQL_DOUBLE 189 SQL_DATETIME 190 SQL_DATE 191 SQL_INTERVAL 192 SQL_TIME 193 SQL_TIMESTAMP 194 SQL_VARCHAR 195 SQL_BOOLEAN 196 SQL_UDT 197 SQL_UDT_LOCATOR 198 SQL_ROW 199 SQL_REF 200 SQL_BLOB 201 SQL_BLOB_LOCATOR 202 SQL_CLOB 203 SQL_CLOB_LOCATOR 204 SQL_ARRAY 205 SQL_ARRAY_LOCATOR 206 SQL_MULTISET 207 SQL_MULTISET_LOCATOR 208 SQL_TYPE_DATE 209 SQL_TYPE_TIME 210 SQL_TYPE_TIMESTAMP 211 SQL_TYPE_TIME_WITH_TIMEZONE 212 SQL_TYPE_TIMESTAMP_WITH_TIMEZONE 213 SQL_INTERVAL_YEAR 214 SQL_INTERVAL_MONTH 215 SQL_INTERVAL_DAY 216 SQL_INTERVAL_HOUR 217 SQL_INTERVAL_MINUTE 218 SQL_INTERVAL_SECOND 219 SQL_INTERVAL_YEAR_TO_MONTH 220 SQL_INTERVAL_DAY_TO_HOUR 221 SQL_INTERVAL_DAY_TO_MINUTE 222 SQL_INTERVAL_DAY_TO_SECOND 223 SQL_INTERVAL_HOUR_TO_MINUTE 224 SQL_INTERVAL_HOUR_TO_SECOND 225 SQL_INTERVAL_MINUTE_TO_SECOND 226 ) ], 227 sql_cursor_types => [ qw( 228 SQL_CURSOR_FORWARD_ONLY 229 SQL_CURSOR_KEYSET_DRIVEN 230 SQL_CURSOR_DYNAMIC 231 SQL_CURSOR_STATIC 232 SQL_CURSOR_TYPE_DEFAULT 233 ) ], # for ODBC cursor types 234 utils => [ qw( 235 neat neat_list $neat_maxlen dump_results looks_like_number 236 data_string_diff data_string_desc data_diff 237 ) ], 238 profile => [ qw( 239 dbi_profile dbi_profile_merge dbi_profile_merge_nodes dbi_time 240 ) ], # notionally "in" DBI::Profile and normally imported from there 241 ); 242 243 $DBI::dbi_debug = 0; 244 $DBI::neat_maxlen = 1000; 245 $DBI::stderr = 2_000_000_000; # a very round number below 2**31 246 247 # If you get an error here like "Can't find loadable object ..." 248 # then you haven't installed the DBI correctly. Read the README 249 # then install it again. 250 if ( $ENV{DBI_PUREPERL} ) { 251 eval { bootstrap DBI } if $ENV{DBI_PUREPERL} == 1; 252 require DBI::PurePerl if $@ or $ENV{DBI_PUREPERL} >= 2; 253 $DBI::PurePerl ||= 0; # just to silence "only used once" warnings 254 } 255 else { 256 bootstrap DBI; 257 } 258 259 $EXPORT_TAGS{preparse_flags} = [ grep { /^DBIpp_\w\w_/ } keys %{__PACKAGE__."::"} ]; 260 261 Exporter::export_ok_tags(keys %EXPORT_TAGS); 262 263 } 264 265 # Alias some handle methods to also be DBI class methods 266 for (qw(trace_msg set_err parse_trace_flag parse_trace_flags)) { 267 no strict; 268 *$_ = \&{"DBD::_::common::$_"}; 269 } 270 271 use strict; 272 273 DBI->trace(split /=/, $ENV{DBI_TRACE}, 2) if $ENV{DBI_TRACE}; 274 275 $DBI::connect_via ||= "connect"; 276 277 # check if user wants a persistent database connection ( Apache + mod_perl ) 278 if ($INC{'Apache/DBI.pm'} && $ENV{MOD_PERL}) { 279 $DBI::connect_via = "Apache::DBI::connect"; 280 DBI->trace_msg("DBI connect via $DBI::connect_via in $INC{'Apache/DBI.pm'}\n"); 281 } 282 283 # check for weaken support, used by ChildHandles 284 my $HAS_WEAKEN = eval { 285 require Scalar::Util; 286 # this will croak() if this Scalar::Util doesn't have a working weaken(). 287 Scalar::Util::weaken( \my $test ); # same test as in t/72childhandles.t 288 1; 289 }; 290 291 %DBI::installed_drh = (); # maps driver names to installed driver handles 292 sub installed_drivers { %DBI::installed_drh } 293 %DBI::installed_methods = (); # XXX undocumented, may change 294 sub installed_methods { %DBI::installed_methods } 295 296 # Setup special DBI dynamic variables. See DBI::var::FETCH for details. 297 # These are dynamically associated with the last handle used. 298 tie $DBI::err, 'DBI::var', '*err'; # special case: referenced via IHA list 299 tie $DBI::state, 'DBI::var', '"state'; # special case: referenced via IHA list 300 tie $DBI::lasth, 'DBI::var', '!lasth'; # special case: return boolean 301 tie $DBI::errstr, 'DBI::var', '&errstr'; # call &errstr in last used pkg 302 tie $DBI::rows, 'DBI::var', '&rows'; # call &rows in last used pkg 303 sub DBI::var::TIESCALAR{ my $var = $_[1]; bless \$var, 'DBI::var'; } 304 sub DBI::var::STORE { Carp::croak("Can't modify \$DBI::${$_[0]} special variable") } 305 306 { # used to catch DBI->{Attrib} mistake 307 sub DBI::DBI_tie::TIEHASH { bless {} } 308 sub DBI::DBI_tie::STORE { Carp::carp("DBI->{$_[1]} is invalid syntax (you probably want \$h->{$_[1]})");} 309 *DBI::DBI_tie::FETCH = \&DBI::DBI_tie::STORE; 310 } 311 tie %DBI::DBI => 'DBI::DBI_tie'; 312 313 # --- Driver Specific Prefix Registry --- 314 315 my $dbd_prefix_registry = { 316 ad_ => { class => 'DBD::AnyData', }, 317 ado_ => { class => 'DBD::ADO', }, 318 amzn_ => { class => 'DBD::Amazon', }, 319 best_ => { class => 'DBD::BestWins', }, 320 csv_ => { class => 'DBD::CSV', }, 321 db2_ => { class => 'DBD::DB2', }, 322 dbi_ => { class => 'DBI', }, 323 dbm_ => { class => 'DBD::DBM', }, 324 df_ => { class => 'DBD::DF', }, 325 f_ => { class => 'DBD::File', }, 326 file_ => { class => 'DBD::TextFile', }, 327 go_ => { class => 'DBD::Gofer', }, 328 ib_ => { class => 'DBD::InterBase', }, 329 ing_ => { class => 'DBD::Ingres', }, 330 ix_ => { class => 'DBD::Informix', }, 331 jdbc_ => { class => 'DBD::JDBC', }, 332 monetdb_ => { class => 'DBD::monetdb', }, 333 msql_ => { class => 'DBD::mSQL', }, 334 mvsftp_ => { class => 'DBD::MVS_FTPSQL', }, 335 mysql_ => { class => 'DBD::mysql', }, 336 mx_ => { class => 'DBD::Multiplex', }, 337 nullp_ => { class => 'DBD::NullP', }, 338 odbc_ => { class => 'DBD::ODBC', }, 339 ora_ => { class => 'DBD::Oracle', }, 340 pg_ => { class => 'DBD::Pg', }, 341 plb_ => { class => 'DBD::Plibdata', }, 342 proxy_ => { class => 'DBD::Proxy', }, 343 rdb_ => { class => 'DBD::RDB', }, 344 sapdb_ => { class => 'DBD::SAP_DB', }, 345 solid_ => { class => 'DBD::Solid', }, 346 sponge_ => { class => 'DBD::Sponge', }, 347 sql_ => { class => 'SQL::Statement', }, 348 syb_ => { class => 'DBD::Sybase', }, 349 tdat_ => { class => 'DBD::Teradata', }, 350 tmpl_ => { class => 'DBD::Template', }, 351 tmplss_ => { class => 'DBD::TemplateSS', }, 352 tuber_ => { class => 'DBD::Tuber', }, 353 uni_ => { class => 'DBD::Unify', }, 354 vt_ => { class => 'DBD::Vt', }, 355 wmi_ => { class => 'DBD::WMI', }, 356 x_ => { }, # for private use 357 xbase_ => { class => 'DBD::XBase', }, 358 xl_ => { class => 'DBD::Excel', }, 359 yaswi_ => { class => 'DBD::Yaswi', }, 360 }; 361 362 sub dump_dbd_registry { 363 require Data::Dumper; 364 local $Data::Dumper::Sortkeys=1; 365 local $Data::Dumper::Indent=1; 366 print Data::Dumper->Dump([$dbd_prefix_registry], [qw($dbd_prefix_registry)]); 367 } 368 369 # --- Dynamically create the DBI Standard Interface 370 371 my $keeperr = { O=>0x0004 }; 372 373 %DBI::DBI_methods = ( # Define the DBI interface methods per class: 374 375 common => { # Interface methods common to all DBI handle classes 376 'DESTROY' => { O=>0x004|0x10000 }, 377 'CLEAR' => $keeperr, 378 'EXISTS' => $keeperr, 379 'FETCH' => { O=>0x0404 }, 380 'FETCH_many' => { O=>0x0404 }, 381 'FIRSTKEY' => $keeperr, 382 'NEXTKEY' => $keeperr, 383 'STORE' => { O=>0x0418 | 0x4 }, 384 _not_impl => undef, 385 can => { O=>0x0100 }, # special case, see dispatch 386 debug => { U =>[1,2,'[$debug_level]'], O=>0x0004 }, # old name for trace 387 dump_handle => { U =>[1,3,'[$message [, $level]]'], O=>0x0004 }, 388 err => $keeperr, 389 errstr => $keeperr, 390 state => $keeperr, 391 func => { O=>0x0006 }, 392 parse_trace_flag => { U =>[2,2,'$name'], O=>0x0404, T=>8 }, 393 parse_trace_flags => { U =>[2,2,'$flags'], O=>0x0404, T=>8 }, 394 private_data => { U =>[1,1], O=>0x0004 }, 395 set_err => { U =>[3,6,'$err, $errmsg [, $state, $method, $rv]'], O=>0x0010 }, 396 trace => { U =>[1,3,'[$trace_level, [$filename]]'], O=>0x0004 }, 397 trace_msg => { U =>[2,3,'$message_text [, $min_level ]' ], O=>0x0004, T=>8 }, 398 swap_inner_handle => { U =>[2,3,'$h [, $allow_reparent ]'] }, 399 private_attribute_info => { }, 400 }, 401 dr => { # Database Driver Interface 402 'connect' => { U =>[1,5,'[$db [,$user [,$passwd [,\%attr]]]]'], H=>3, O=>0x8000 }, 403 'connect_cached'=>{U=>[1,5,'[$db [,$user [,$passwd [,\%attr]]]]'], H=>3, O=>0x8000 }, 404 'disconnect_all'=>{ U =>[1,1], O=>0x0800 }, 405 data_sources => { U =>[1,2,'[\%attr]' ], O=>0x0800 }, 406 default_user => { U =>[3,4,'$user, $pass [, \%attr]' ] }, 407 dbixs_revision => $keeperr, 408 }, 409 db => { # Database Session Class Interface 410 data_sources => { U =>[1,2,'[\%attr]' ], O=>0x0200 }, 411 take_imp_data => { U =>[1,1], O=>0x10000 }, 412 clone => { U =>[1,2,'[\%attr]'] }, 413 connected => { U =>[1,0], O => 0x0004 }, 414 begin_work => { U =>[1,2,'[ \%attr ]'], O=>0x0400 }, 415 commit => { U =>[1,1], O=>0x0480|0x0800 }, 416 rollback => { U =>[1,1], O=>0x0480|0x0800 }, 417 'do' => { U =>[2,0,'$statement [, \%attr [, @bind_params ] ]'], O=>0x3200 }, 418 last_insert_id => { U =>[5,6,'$catalog, $schema, $table_name, $field_name [, \%attr ]'], O=>0x2800 }, 419 preparse => { }, # XXX 420 prepare => { U =>[2,3,'$statement [, \%attr]'], O=>0xA200 }, 421 prepare_cached => { U =>[2,4,'$statement [, \%attr [, $if_active ] ]'], O=>0xA200 }, 422 selectrow_array => { U =>[2,0,'$statement [, \%attr [, @bind_params ] ]'], O=>0x2000 }, 423 selectrow_arrayref=>{U =>[2,0,'$statement [, \%attr [, @bind_params ] ]'], O=>0x2000 }, 424 selectrow_hashref=>{ U =>[2,0,'$statement [, \%attr [, @bind_params ] ]'], O=>0x2000 }, 425 selectall_arrayref=>{U =>[2,0,'$statement [, \%attr [, @bind_params ] ]'], O=>0x2000 }, 426 selectall_hashref=>{ U =>[3,0,'$statement, $keyfield [, \%attr [, @bind_params ] ]'], O=>0x2000 }, 427 selectcol_arrayref=>{U =>[2,0,'$statement [, \%attr [, @bind_params ] ]'], O=>0x2000 }, 428 ping => { U =>[1,1], O=>0x0404 }, 429 disconnect => { U =>[1,1], O=>0x0400|0x0800|0x10000 }, 430 quote => { U =>[2,3, '$string [, $data_type ]' ], O=>0x0430 }, 431 quote_identifier=> { U =>[2,6, '$name [, ...] [, \%attr ]' ], O=>0x0430 }, 432 rows => $keeperr, 433 434 tables => { U =>[1,6,'$catalog, $schema, $table, $type [, \%attr ]' ], O=>0x2200 }, 435 table_info => { U =>[1,6,'$catalog, $schema, $table, $type [, \%attr ]' ], O=>0x2200|0x8800 }, 436 column_info => { U =>[5,6,'$catalog, $schema, $table, $column [, \%attr ]'],O=>0x2200|0x8800 }, 437 primary_key_info=> { U =>[4,5,'$catalog, $schema, $table [, \%attr ]' ], O=>0x2200|0x8800 }, 438 primary_key => { U =>[4,5,'$catalog, $schema, $table [, \%attr ]' ], O=>0x2200 }, 439 foreign_key_info=> { U =>[7,8,'$pk_catalog, $pk_schema, $pk_table, $fk_catalog, $fk_schema, $fk_table [, \%attr ]' ], O=>0x2200|0x8800 }, 440 statistics_info => { U =>[6,7,'$catalog, $schema, $table, $unique_only, $quick, [, \%attr ]' ], O=>0x2200|0x8800 }, 441 type_info_all => { U =>[1,1], O=>0x2200|0x0800 }, 442 type_info => { U =>[1,2,'$data_type'], O=>0x2200 }, 443 get_info => { U =>[2,2,'$info_type'], O=>0x2200|0x0800 }, 444 }, 445 st => { # Statement Class Interface 446 bind_col => { U =>[3,4,'$column, \\$var [, \%attr]'] }, 447 bind_columns => { U =>[2,0,'\\$var1 [, \\$var2, ...]'] }, 448 bind_param => { U =>[3,4,'$parameter, $var [, \%attr]'] }, 449 bind_param_inout=> { U =>[4,5,'$parameter, \\$var, $maxlen, [, \%attr]'] }, 450 execute => { U =>[1,0,'[@args]'], O=>0x1040 }, 451 452 bind_param_array => { U =>[3,4,'$parameter, $var [, \%attr]'] }, 453 bind_param_inout_array => { U =>[4,5,'$parameter, \\@var, $maxlen, [, \%attr]'] }, 454 execute_array => { U =>[2,0,'\\%attribs [, @args]'], O=>0x1040|0x4000 }, 455 execute_for_fetch => { U =>[2,3,'$fetch_sub [, $tuple_status]'], O=>0x1040|0x4000 }, 456 457 fetch => undef, # alias for fetchrow_arrayref 458 fetchrow_arrayref => undef, 459 fetchrow_hashref => undef, 460 fetchrow_array => undef, 461 fetchrow => undef, # old alias for fetchrow_array 462 463 fetchall_arrayref => { U =>[1,3, '[ $slice [, $max_rows]]'] }, 464 fetchall_hashref => { U =>[2,2,'$key_field'] }, 465 466 blob_read => { U =>[4,5,'$field, $offset, $len [, \\$buf [, $bufoffset]]'] }, 467 blob_copy_to_file => { U =>[3,3,'$field, $filename_or_handleref'] }, 468 dump_results => { U =>[1,5,'$maxfieldlen, $linesep, $fieldsep, $filehandle'] }, 469 more_results => { U =>[1,1] }, 470 finish => { U =>[1,1] }, 471 cancel => { U =>[1,1], O=>0x0800 }, 472 rows => $keeperr, 473 474 _get_fbav => undef, 475 _set_fbav => { T=>6 }, 476 }, 477 ); 478 479 while ( my ($class, $meths) = each %DBI::DBI_methods ) { 480 my $ima_trace = 0+($ENV{DBI_IMA_TRACE}||0); 481 while ( my ($method, $info) = each %$meths ) { 482 my $fullmeth = "DBI::$class}::$method"; 483 if ($DBI::dbi_debug >= 15) { # quick hack to list DBI methods 484 # and optionally filter by IMA flags 485 my $O = $info->{O}||0; 486 printf "0x%04x %-20s\n", $O, $fullmeth 487 unless $ima_trace && !($O & $ima_trace); 488 } 489 DBI->_install_method($fullmeth, 'DBI.pm', $info); 490 } 491 } 492 493 { 494 package DBI::common; 495 @DBI::dr::ISA = ('DBI::common'); 496 @DBI::db::ISA = ('DBI::common'); 497 @DBI::st::ISA = ('DBI::common'); 498 } 499 500 # End of init code 501 502 503 END { 504 return unless defined &DBI::trace_msg; # return unless bootstrap'd ok 505 local ($!,$?); 506 DBI->trace_msg(sprintf(" -- DBI::END (\$\@: %s, \$!: %s)\n", $@||'', $!||''), 2); 507 # Let drivers know why we are calling disconnect_all: 508 $DBI::PERL_ENDING = $DBI::PERL_ENDING = 1; # avoid typo warning 509 DBI->disconnect_all() if %DBI::installed_drh; 510 } 511 512 513 sub CLONE { 514 my $olddbis = $DBI::_dbistate; 515 _clone_dbis() unless $DBI::PurePerl; # clone the DBIS structure 516 DBI->trace_msg(sprintf "CLONE DBI for new thread %s\n", 517 $DBI::PurePerl ? "" : sprintf("(dbis %x -> %x)",$olddbis, $DBI::_dbistate)); 518 while ( my ($driver, $drh) = each %DBI::installed_drh) { 519 no strict 'refs'; 520 next if defined &{"DBD::$driver}::CLONE"}; 521 warn("$driver has no driver CLONE() function so is unsafe threaded\n"); 522 } 523 %DBI::installed_drh = (); # clear loaded drivers so they have a chance to reinitialize 524 } 525 526 sub parse_dsn { 527 my ($class, $dsn) = @_; 528 $dsn =~ s/^(dbi):(\w*?)(?:\((.*?)\))?://i or return; 529 my ($scheme, $driver, $attr, $attr_hash) = (lc($1), $2, $3); 530 $driver ||= $ENV{DBI_DRIVER} || ''; 531 $attr_hash = { split /\s*=>?\s*|\s*,\s*/, $attr, -1 } if $attr; 532 return ($scheme, $driver, $attr, $attr_hash, $dsn); 533 } 534 535 536 # --- The DBI->connect Front Door methods 537 538 sub connect_cached { 539 # For library code using connect_cached() with mod_perl 540 # we redirect those calls to Apache::DBI::connect() as well 541 my ($class, $dsn, $user, $pass, $attr) = @_; 542 my $dbi_connect_method = ($DBI::connect_via eq "Apache::DBI::connect") 543 ? 'Apache::DBI::connect' : 'connect_cached'; 544 $attr = { 545 $attr ? %$attr : (), # clone, don't modify callers data 546 dbi_connect_method => $dbi_connect_method, 547 }; 548 return $class->connect($dsn, $user, $pass, $attr); 549 } 550 551 sub connect { 552 my $class = shift; 553 my ($dsn, $user, $pass, $attr, $old_driver) = my @orig_args = @_; 554 my $driver; 555 556 if ($attr and !ref($attr)) { # switch $old_driver<->$attr if called in old style 557 Carp::carp("DBI->connect using 'old-style' syntax is deprecated and will be an error in future versions"); 558 ($old_driver, $attr) = ($attr, $old_driver); 559 } 560 561 my $connect_meth = $attr->{dbi_connect_method}; 562 $connect_meth ||= $DBI::connect_via; # fallback to default 563 564 $dsn ||= $ENV{DBI_DSN} || $ENV{DBI_DBNAME} || '' unless $old_driver; 565 566 if ($DBI::dbi_debug) { 567 local $^W = 0; 568 pop @_ if $connect_meth ne 'connect'; 569 my @args = @_; $args[2] = '****'; # hide password 570 DBI->trace_msg(" -> $class->$connect_meth(".join(", ",@args).")\n"); 571 } 572 Carp::croak('Usage: $class->connect([$dsn [,$user [,$passwd [,\%attr]]]])') 573 if (ref $old_driver or ($attr and not ref $attr) or ref $pass); 574 575 # extract dbi:driver prefix from $dsn into $1 576 $dsn =~ s/^dbi:(\w*?)(?:\((.*?)\))?://i 577 or '' =~ /()/; # ensure $1 etc are empty if match fails 578 my $driver_attrib_spec = $2 || ''; 579 580 # Set $driver. Old style driver, if specified, overrides new dsn style. 581 $driver = $old_driver || $1 || $ENV{DBI_DRIVER} 582 or Carp::croak("Can't connect to data source '$dsn' " 583 ."because I can't work out what driver to use " 584 ."(it doesn't seem to contain a 'dbi:driver:' prefix " 585 ."and the DBI_DRIVER env var is not set)"); 586 587 my $proxy; 588 if ($ENV{DBI_AUTOPROXY} && $driver ne 'Proxy' && $driver ne 'Sponge' && $driver ne 'Switch') { 589 my $dbi_autoproxy = $ENV{DBI_AUTOPROXY}; 590 $proxy = 'Proxy'; 591 if ($dbi_autoproxy =~ s/^dbi:(\w*?)(?:\((.*?)\))?://i) { 592 $proxy = $1; 593 $driver_attrib_spec = join ",", 594 ($driver_attrib_spec) ? $driver_attrib_spec : (), 595 ($2 ) ? $2 : (); 596 } 597 $dsn = "$dbi_autoproxy;dsn=dbi:$driver:$dsn"; 598 $driver = $proxy; 599 DBI->trace_msg(" DBI_AUTOPROXY: dbi:$driver($driver_attrib_spec):$dsn\n"); 600 } 601 # avoid recursion if proxy calls DBI->connect itself 602 local $ENV{DBI_AUTOPROXY}; 603 604 my %attributes; # take a copy we can delete from 605 if ($old_driver) { 606 %attributes = %$attr if $attr; 607 } 608 else { # new-style connect so new default semantics 609 %attributes = ( 610 PrintError => 1, 611 AutoCommit => 1, 612 ref $attr ? %$attr : (), 613 # attributes in DSN take precedence over \%attr connect parameter 614 $driver_attrib_spec ? (split /\s*=>?\s*|\s*,\s*/, $driver_attrib_spec, -1) : (), 615 ); 616 } 617 $attr = \%attributes; # now set $attr to refer to our local copy 618 619 my $drh = $DBI::installed_drh{$driver} || $class->install_driver($driver) 620 or die "panic: $class->install_driver($driver) failed"; 621 622 # attributes in DSN take precedence over \%attr connect parameter 623 $user = $attr->{Username} if defined $attr->{Username}; 624 $pass = $attr->{Password} if defined $attr->{Password}; 625 delete $attr->{Password}; # always delete Password as closure stores it securely 626 if ( !(defined $user && defined $pass) ) { 627 ($user, $pass) = $drh->default_user($user, $pass, $attr); 628 } 629 $attr->{Username} = $user; # force the Username to be the actual one used 630 631 my $connect_closure = sub { 632 my ($old_dbh, $override_attr) = @_; 633 634 #use Data::Dumper; 635 #warn "connect_closure: ".Data::Dumper::Dumper([$attr,\%attributes, $override_attr]); 636 637 my $dbh; 638 unless ($dbh = $drh->$connect_meth($dsn, $user, $pass, $attr)) { 639 $user = '' if !defined $user; 640 $dsn = '' if !defined $dsn; 641 # $drh->errstr isn't safe here because $dbh->DESTROY may not have 642 # been called yet and so the dbh errstr would not have been copied 643 # up to the drh errstr. Certainly true for connect_cached! 644 my $errstr = $DBI::errstr; 645 # Getting '(no error string)' here is a symptom of a ref loop 646 $errstr = '(no error string)' if !defined $errstr; 647 my $msg = "$class connect('$dsn','$user',...) failed: $errstr"; 648 DBI->trace_msg(" $msg\n"); 649 # XXX HandleWarn 650 unless ($attr->{HandleError} && $attr->{HandleError}->($msg, $drh, $dbh)) { 651 Carp::croak($msg) if $attr->{RaiseError}; 652 Carp::carp ($msg) if $attr->{PrintError}; 653 } 654 $! = 0; # for the daft people who do DBI->connect(...) || die "$!"; 655 return $dbh; # normally undef, but HandleError could change it 656 } 657 658 # merge any attribute overrides but don't change $attr itself (for closure) 659 my $apply = { ($override_attr) ? (%$attr, %$override_attr ) : %$attr }; 660 661 # handle basic RootClass subclassing: 662 my $rebless_class = $apply->{RootClass} || ($class ne 'DBI' ? $class : ''); 663 if ($rebless_class) { 664 no strict 'refs'; 665 if ($apply->{RootClass}) { # explicit attribute (ie not static methd call class) 666 delete $apply->{RootClass}; 667 DBI::_load_class($rebless_class, 0); 668 } 669 unless (@{"$rebless_class\::db::ISA"} && @{"$rebless_class\::st::ISA"}) { 670 Carp::carp("DBI subclasses '$rebless_class\::db' and ::st are not setup, RootClass ignored"); 671 $rebless_class = undef; 672 $class = 'DBI'; 673 } 674 else { 675 $dbh->{RootClass} = $rebless_class; # $dbh->STORE called via plain DBI::db 676 DBI::_set_isa([$rebless_class], 'DBI'); # sets up both '::db' and '::st' 677 DBI::_rebless($dbh, $rebless_class); # appends '::db' 678 } 679 } 680 681 if (%$apply) { 682 683 if ($apply->{DbTypeSubclass}) { 684 my $DbTypeSubclass = delete $apply->{DbTypeSubclass}; 685 DBI::_rebless_dbtype_subclass($dbh, $rebless_class||$class, $DbTypeSubclass); 686 } 687 my $a; 688 foreach $a (qw(Profile RaiseError PrintError AutoCommit)) { # do these first 689 next unless exists $apply->{$a}; 690 $dbh->{$a} = delete $apply->{$a}; 691 } 692 while ( my ($a, $v) = each %$apply) { 693 eval { $dbh->{$a} = $v } or $@ && warn $@; 694 } 695 } 696 697 # confirm to driver (ie if subclassed) that we've connected sucessfully 698 # and finished the attribute setup. pass in the original arguments 699 $dbh->connected(@orig_args); #if ref $dbh ne 'DBI::db' or $proxy; 700 701 DBI->trace_msg(" <- connect= $dbh\n") if $DBI::dbi_debug; 702 703 return $dbh; 704 }; 705 706 my $dbh = &$connect_closure(undef, undef); 707 708 $dbh->{dbi_connect_closure} = $connect_closure if $dbh; 709 710 return $dbh; 711 } 712 713 714 sub disconnect_all { 715 keys %DBI::installed_drh; # reset iterator 716 while ( my ($name, $drh) = each %DBI::installed_drh ) { 717 $drh->disconnect_all() if ref $drh; 718 } 719 } 720 721 722 sub disconnect { # a regular beginners bug 723 Carp::croak("DBI->disconnect is not a DBI method (read the DBI manual)"); 724 } 725 726 727 sub install_driver { # croaks on failure 728 my $class = shift; 729 my($driver, $attr) = @_; 730 my $drh; 731 732 $driver ||= $ENV{DBI_DRIVER} || ''; 733 734 # allow driver to be specified as a 'dbi:driver:' string 735 $driver = $1 if $driver =~ s/^DBI:(.*?)://i; 736 737 Carp::croak("usage: $class->install_driver(\$driver [, \%attr])") 738 unless ($driver and @_<=3); 739 740 # already installed 741 return $drh if $drh = $DBI::installed_drh{$driver}; 742 743 $class->trace_msg(" -> $class->install_driver($driver" 744 .") for $^O perl=$] pid=$$ ruid=$< euid=$>\n") 745 if $DBI::dbi_debug; 746 747 # --- load the code 748 my $driver_class = "DBD::$driver"; 749 eval qq{package # hide from PAUSE 750 DBI::_firesafe; # just in case 751 require $driver_class; # load the driver 752 }; 753 if ($@) { 754 my $err = $@; 755 my $advice = ""; 756 if ($err =~ /Can't find loadable object/) { 757 $advice = "Perhaps DBD::$driver was statically linked into a new perl binary." 758 ."\nIn which case you need to use that new perl binary." 759 ."\nOr perhaps only the .pm file was installed but not the shared object file." 760 } 761 elsif ($err =~ /Can't locate.*?DBD\/$driver\.pm in \@INC/) { 762 my @drv = $class->available_drivers(1); 763 $advice = "Perhaps the DBD::$driver perl module hasn't been fully installed,\n" 764 ."or perhaps the capitalisation of '$driver' isn't right.\n" 765 ."Available drivers: ".join(", ", @drv)."."; 766 } 767 elsif ($err =~ /Can't load .*? for module DBD::/) { 768 $advice = "Perhaps a required shared library or dll isn't installed where expected"; 769 } 770 elsif ($err =~ /Can't locate .*? in \@INC/) { 771 $advice = "Perhaps a module that DBD::$driver requires hasn't been fully installed"; 772 } 773 Carp::croak("install_driver($driver) failed: $err$advice\n"); 774 } 775 if ($DBI::dbi_debug) { 776 no strict 'refs'; 777 (my $driver_file = $driver_class) =~ s/::/\//g; 778 my $dbd_ver = ${"$driver_class\::VERSION"} || "undef"; 779 $class->trace_msg(" install_driver: $driver_class version $dbd_ver" 780 ." loaded from $INC{qq($driver_file.pm)}\n"); 781 } 782 783 # --- do some behind-the-scenes checks and setups on the driver 784 $class->setup_driver($driver_class); 785 786 # --- run the driver function 787 $drh = eval { $driver_class->driver($attr || {}) }; 788 unless ($drh && ref $drh && !$@) { 789 my $advice = ""; 790 $@ ||= "$driver_class->driver didn't return a handle"; 791 # catch people on case in-sensitive systems using the wrong case 792 $advice = "\nPerhaps the capitalisation of DBD '$driver' isn't right." 793 if $@ =~ /locate object method/; 794 Carp::croak("$driver_class initialisation failed: $@$advice"); 795 } 796 797 $DBI::installed_drh{$driver} = $drh; 798 $class->trace_msg(" <- install_driver= $drh\n") if $DBI::dbi_debug; 799 $drh; 800 } 801 802 *driver = \&install_driver; # currently an alias, may change 803 804 805 sub setup_driver { 806 my ($class, $driver_class) = @_; 807 my $type; 808 foreach $type (qw(dr db st)){ 809 my $class = $driver_class."::$type"; 810 no strict 'refs'; 811 push @{"$class}::ISA"}, "DBD::_::$type" 812 unless UNIVERSAL::isa($class, "DBD::_::$type"); 813 my $mem_class = "DBD::_mem::$type"; 814 push @{"$class}_mem::ISA"}, $mem_class 815 unless UNIVERSAL::isa("$class}_mem", $mem_class) 816 or $DBI::PurePerl; 817 } 818 } 819 820 821 sub _rebless { 822 my $dbh = shift; 823 my ($outer, $inner) = DBI::_handles($dbh); 824 my $class = shift(@_).'::db'; 825 bless $inner => $class; 826 bless $outer => $class; # outer last for return 827 } 828 829 830 sub _set_isa { 831 my ($classes, $topclass) = @_; 832 my $trace = DBI->trace_msg(" _set_isa([@$classes])\n"); 833 foreach my $suffix ('::db','::st') { 834 my $previous = $topclass || 'DBI'; # trees are rooted here 835 foreach my $class (@$classes) { 836 my $base_class = $previous.$suffix; 837 my $sub_class = $class.$suffix; 838 my $sub_class_isa = "$sub_class}::ISA"; 839 no strict 'refs'; 840 if (@$sub_class_isa) { 841 DBI->trace_msg(" $sub_class_isa skipped (already set to @$sub_class_isa)\n") 842 if $trace; 843 } 844 else { 845 @$sub_class_isa = ($base_class) unless @$sub_class_isa; 846 DBI->trace_msg(" $sub_class_isa = $base_class\n") 847 if $trace; 848 } 849 $previous = $class; 850 } 851 } 852 } 853 854 855 sub _rebless_dbtype_subclass { 856 my ($dbh, $rootclass, $DbTypeSubclass) = @_; 857 # determine the db type names for class hierarchy 858 my @hierarchy = DBI::_dbtype_names($dbh, $DbTypeSubclass); 859 # add the rootclass prefix to each ('DBI::' or 'MyDBI::' etc) 860 $_ = $rootclass.'::'.$_ foreach (@hierarchy); 861 # load the modules from the 'top down' 862 DBI::_load_class($_, 1) foreach (reverse @hierarchy); 863 # setup class hierarchy if needed, does both '::db' and '::st' 864 DBI::_set_isa(\@hierarchy, $rootclass); 865 # finally bless the handle into the subclass 866 DBI::_rebless($dbh, $hierarchy[0]); 867 } 868 869 870 sub _dbtype_names { # list dbtypes for hierarchy, ie Informix=>ADO=>ODBC 871 my ($dbh, $DbTypeSubclass) = @_; 872 873 if ($DbTypeSubclass && $DbTypeSubclass ne '1' && ref $DbTypeSubclass ne 'CODE') { 874 # treat $DbTypeSubclass as a comma separated list of names 875 my @dbtypes = split /\s*,\s*/, $DbTypeSubclass; 876 $dbh->trace_msg(" DbTypeSubclass($DbTypeSubclass)=@dbtypes (explicit)\n"); 877 return @dbtypes; 878 } 879 880 # XXX will call $dbh->get_info(17) (=SQL_DBMS_NAME) in future? 881 882 my $driver = $dbh->{Driver}->{Name}; 883 if ( $driver eq 'Proxy' ) { 884 # XXX Looking into the internals of DBD::Proxy is questionable! 885 ($driver) = $dbh->{proxy_client}->{application} =~ /^DBI:(.+?):/i 886 or die "Can't determine driver name from proxy"; 887 } 888 889 my @dbtypes = (ucfirst($driver)); 890 if ($driver eq 'ODBC' || $driver eq 'ADO') { 891 # XXX will move these out and make extensible later: 892 my $_dbtype_name_regexp = 'Oracle'; # eg 'Oracle|Foo|Bar' 893 my %_dbtype_name_map = ( 894 'Microsoft SQL Server' => 'MSSQL', 895 'SQL Server' => 'Sybase', 896 'Adaptive Server Anywhere' => 'ASAny', 897 'ADABAS D' => 'AdabasD', 898 ); 899 900 my $name; 901 $name = $dbh->func(17, 'GetInfo') # SQL_DBMS_NAME 902 if $driver eq 'ODBC'; 903 $name = $dbh->{ado_conn}->Properties->Item('DBMS Name')->Value 904 if $driver eq 'ADO'; 905 die "Can't determine driver name! ($DBI::errstr)\n" 906 unless $name; 907 908 my $dbtype; 909 if ($_dbtype_name_map{$name}) { 910 $dbtype = $_dbtype_name_map{$name}; 911 } 912 else { 913 if ($name =~ /($_dbtype_name_regexp)/) { 914 $dbtype = lc($1); 915 } 916 else { # generic mangling for other names: 917 $dbtype = lc($name); 918 } 919 $dbtype =~ s/\b(\w)/\U$1/g; 920 $dbtype =~ s/\W+/_/g; 921 } 922 # add ODBC 'behind' ADO 923 push @dbtypes, 'ODBC' if $driver eq 'ADO'; 924 # add discovered dbtype in front of ADO/ODBC 925 unshift @dbtypes, $dbtype; 926 } 927 @dbtypes = &$DbTypeSubclass($dbh, \@dbtypes) 928 if (ref $DbTypeSubclass eq 'CODE'); 929 $dbh->trace_msg(" DbTypeSubclass($DbTypeSubclass)=@dbtypes\n"); 930 return @dbtypes; 931 } 932 933 sub _load_class { 934 my ($load_class, $missing_ok) = @_; 935 DBI->trace_msg(" _load_class($load_class, $missing_ok)\n", 2); 936 no strict 'refs'; 937 return 1 if @{"$load_class\::ISA"}; # already loaded/exists 938 (my $module = $load_class) =~ s!::!/!g; 939 DBI->trace_msg(" _load_class require $module\n", 2); 940 eval { require "$module.pm"; }; 941 return 1 unless $@; 942 return 0 if $missing_ok && $@ =~ /^Can't locate \Q$module.pm\E/; 943 die $@; 944 } 945 946 947 sub init_rootclass { # deprecated 948 return 1; 949 } 950 951 952 *internal = \&DBD::Switch::dr::driver; 953 954 955 sub available_drivers { 956 my($quiet) = @_; 957 my(@drivers, $d, $f); 958 local(*DBI::DIR, $@); 959 my(%seen_dir, %seen_dbd); 960 my $haveFileSpec = eval { require File::Spec }; 961 foreach $d (@INC){ 962 chomp($d); # Perl 5 beta 3 bug in #!./perl -Ilib from Test::Harness 963 my $dbd_dir = 964 ($haveFileSpec ? File::Spec->catdir($d, 'DBD') : "$d/DBD"); 965 next unless -d $dbd_dir; 966 next if $seen_dir{$d}; 967 $seen_dir{$d} = 1; 968 # XXX we have a problem here with case insensitive file systems 969 # XXX since we can't tell what case must be used when loading. 970 opendir(DBI::DIR, $dbd_dir) || Carp::carp "opendir $dbd_dir: $!\n"; 971 foreach $f (readdir(DBI::DIR)){ 972 next unless $f =~ s/\.pm$//; 973 next if $f eq 'NullP'; 974 if ($seen_dbd{$f}){ 975 Carp::carp "DBD::$f in $d is hidden by DBD::$f in $seen_dbd{$f}\n" 976 unless $quiet; 977 } else { 978 push(@drivers, $f); 979 } 980 $seen_dbd{$f} = $d; 981 } 982 closedir(DBI::DIR); 983 } 984 985 # "return sort @drivers" will not DWIM in scalar context. 986 return wantarray ? sort @drivers : @drivers; 987 } 988 989 sub installed_versions { 990 my ($class, $quiet) = @_; 991 my %error; 992 my %version = ( DBI => $DBI::VERSION ); 993 $version{"DBI::PurePerl"} = $DBI::PurePerl::VERSION 994 if $DBI::PurePerl; 995 for my $driver ($class->available_drivers($quiet)) { 996 next if $DBI::PurePerl && grep { -d "$_/auto/DBD/$driver" } @INC; 997 my $drh = eval { 998 local $SIG{__WARN__} = sub {}; 999 $class->install_driver($driver); 1000 }; 1001 ($error{"DBD::$driver"}=$@),next if $@; 1002 no strict 'refs'; 1003 my $vers = ${"DBD::$driver" . '::VERSION'}; 1004 $version{"DBD::$driver"} = $vers || '?'; 1005 } 1006 if (wantarray) { 1007 return map { m/^DBD::(\w+)/ ? ($1) : () } sort keys %version; 1008 } 1009 if (!defined wantarray) { # void context 1010 require Config; # add more detail 1011 $version{OS} = "$^O\t($Config::Config{osvers})"; 1012 $version{Perl} = "$]\t($Config::Config{archname})"; 1013 $version{$_} = (($error{$_} =~ s/ \(\@INC.*//s),$error{$_}) 1014 for keys %error; 1015 printf " %-16s: %s\n",$_,$version{$_} 1016 for reverse sort keys %version; 1017 } 1018 return \%version; 1019 } 1020 1021 1022 sub data_sources { 1023 my ($class, $driver, @other) = @_; 1024 my $drh = $class->install_driver($driver); 1025 my @ds = $drh->data_sources(@other); 1026 return @ds; 1027 } 1028 1029 1030 sub neat_list { 1031 my ($listref, $maxlen, $sep) = @_; 1032 $maxlen = 0 unless defined $maxlen; # 0 == use internal default 1033 $sep = ", " unless defined $sep; 1034 join($sep, map { neat($_,$maxlen) } @$listref); 1035 } 1036 1037 1038 sub dump_results { # also aliased as a method in DBD::_::st 1039 my ($sth, $maxlen, $lsep, $fsep, $fh) = @_; 1040 return 0 unless $sth; 1041 $maxlen ||= 35; 1042 $lsep ||= "\n"; 1043 $fh ||= \*STDOUT; 1044 my $rows = 0; 1045 my $ref; 1046 while($ref = $sth->fetch) { 1047 print $fh $lsep if $rows++ and $lsep; 1048 my $str = neat_list($ref,$maxlen,$fsep); 1049 print $fh $str; # done on two lines to avoid 5.003 errors 1050 } 1051 print $fh "\n$rows rows".($DBI::err ? " ($DBI::err: $DBI::errstr)" : "")."\n"; 1052 $rows; 1053 } 1054 1055 1056 sub data_diff { 1057 my ($a, $b, $logical) = @_; 1058 1059 my $diff = data_string_diff($a, $b); 1060 return "" if $logical and !$diff; 1061 1062 my $a_desc = data_string_desc($a); 1063 my $b_desc = data_string_desc($b); 1064 return "" if !$diff and $a_desc eq $b_desc; 1065 1066 $diff ||= "Strings contain the same sequence of characters" 1067 if length($a); 1068 $diff .= "\n" if $diff; 1069 return "a: $a_desc\nb: $b_desc\n$diff"; 1070 } 1071 1072 1073 sub data_string_diff { 1074 # Compares 'logical' characters, not bytes, so a latin1 string and an 1075 # an equivalent unicode string will compare as equal even though their 1076 # byte encodings are different. 1077 my ($a, $b) = @_; 1078 unless (defined $a and defined $b) { # one undef 1079 return "" 1080 if !defined $a and !defined $b; 1081 return "String a is undef, string b has ".length($b)." characters" 1082 if !defined $a; 1083 return "String b is undef, string a has ".length($a)." characters" 1084 if !defined $b; 1085 } 1086 1087 require utf8; 1088 # hack to cater for perl 5.6 1089 *utf8::is_utf8 = sub { (DBI::neat(shift)=~/^"/) } unless defined &utf8::is_utf8; 1090 1091 my @a_chars = (utf8::is_utf8($a)) ? unpack("U*", $a) : unpack("C*", $a); 1092 my @b_chars = (utf8::is_utf8($b)) ? unpack("U*", $b) : unpack("C*", $b); 1093 my $i = 0; 1094 while (@a_chars && @b_chars) { 1095 ++$i, shift(@a_chars), shift(@b_chars), next 1096 if $a_chars[0] == $b_chars[0];# compare ordinal values 1097 my @desc = map { 1098 $_ > 255 ? # if wide character... 1099 sprintf("\\x{%04X}", $_) : # \x{...} 1100 chr($_) =~ /[[:cntrl:]]/ ? # else if control character ... 1101 sprintf("\\x%02X", $_) : # \x.. 1102 chr($_) # else as themselves 1103 } ($a_chars[0], $b_chars[0]); 1104 # highlight probable double-encoding? 1105 foreach my $c ( @desc ) { 1106 next unless $c =~ m/\\x\{08(..)}/; 1107 $c .= "='" .chr(hex($1)) ."'" 1108 } 1109 return sprintf "Strings differ at index $i: a[$i]=$desc[0], b[$i]=$desc[1]"; 1110 } 1111 return "String a truncated after $i characters" if @b_chars; 1112 return "String b truncated after $i characters" if @a_chars; 1113 return ""; 1114 } 1115 1116 1117 sub data_string_desc { # describe a data string 1118 my ($a) = @_; 1119 require bytes; 1120 require utf8; 1121 1122 # hacks to cater for perl 5.6 1123 *utf8::is_utf8 = sub { (DBI::neat(shift)=~/^"/) } unless defined &utf8::is_utf8; 1124 *utf8::valid = sub { 1 } unless defined &utf8::valid; 1125 1126 # Give sufficient info to help diagnose at least these kinds of situations: 1127 # - valid UTF8 byte sequence but UTF8 flag not set 1128 # (might be ascii so also need to check for hibit to make it worthwhile) 1129 # - UTF8 flag set but invalid UTF8 byte sequence 1130 # could do better here, but this'll do for now 1131 my $utf8 = sprintf "UTF8 %s%s", 1132 utf8::is_utf8($a) ? "on" : "off", 1133 utf8::valid($a||'') ? "" : " but INVALID encoding"; 1134 return "$utf8, undef" unless defined $a; 1135 my $is_ascii = $a =~ m/^[\000-\177]*$/; 1136 return sprintf "%s, %s, %d characters %d bytes", 1137 $utf8, $is_ascii ? "ASCII" : "non-ASCII", 1138 length($a), bytes::length($a); 1139 } 1140 1141 1142 sub connect_test_perf { 1143 my($class, $dsn,$dbuser,$dbpass, $attr) = @_; 1144 Carp::croak("connect_test_perf needs hash ref as fourth arg") unless ref $attr; 1145 # these are non standard attributes just for this special method 1146 my $loops ||= $attr->{dbi_loops} || 5; 1147 my $par ||= $attr->{dbi_par} || 1; # parallelism 1148 my $verb ||= $attr->{dbi_verb} || 1; 1149 my $meth ||= $attr->{dbi_meth} || 'connect'; 1150 print "$dsn: testing $loops sets of $par connections:\n"; 1151 require "FileHandle.pm"; # don't let toke.c create empty FileHandle package 1152 local $| = 1; 1153 my $drh = $class->install_driver($dsn) or Carp::croak("Can't install $dsn driver\n"); 1154 # test the connection and warm up caches etc 1155 $drh->connect($dsn,$dbuser,$dbpass) or Carp::croak("connect failed: $DBI::errstr"); 1156 my $t1 = dbi_time(); 1157 my $loop; 1158 for $loop (1..$loops) { 1159 my @cons; 1160 print "Connecting... " if $verb; 1161 for (1..$par) { 1162 print "$_ "; 1163 push @cons, ($drh->connect($dsn,$dbuser,$dbpass) 1164 or Carp::croak("connect failed: $DBI::errstr\n")); 1165 } 1166 print "\nDisconnecting...\n" if $verb; 1167 for (@cons) { 1168 $_->disconnect or warn "disconnect failed: $DBI::errstr" 1169 } 1170 } 1171 my $t2 = dbi_time(); 1172 my $td = $t2 - $t1; 1173 printf "$meth %d and disconnect them, %d times: %.4fs / %d = %.4fs\n", 1174 $par, $loops, $td, $loops*$par, $td/($loops*$par); 1175 return $td; 1176 } 1177 1178 1179 # Help people doing DBI->errstr, might even document it one day 1180 # XXX probably best moved to cheaper XS code if this gets documented 1181 sub err { $DBI::err } 1182 sub errstr { $DBI::errstr } 1183 1184 1185 # --- Private Internal Function for Creating New DBI Handles 1186 1187 # XXX move to PurePerl? 1188 *DBI::dr::TIEHASH = \&DBI::st::TIEHASH; 1189 *DBI::db::TIEHASH = \&DBI::st::TIEHASH; 1190 1191 1192 # These three special constructors are called by the drivers 1193 # The way they are called is likely to change. 1194 1195 our $shared_profile; 1196 1197 sub _new_drh { # called by DBD::<drivername>::driver() 1198 my ($class, $initial_attr, $imp_data) = @_; 1199 # Provide default storage for State,Err and Errstr. 1200 # Note that these are shared by all child handles by default! XXX 1201 # State must be undef to get automatic faking in DBI::var::FETCH 1202 my ($h_state_store, $h_err_store, $h_errstr_store) = (undef, 0, ''); 1203 my $attr = { 1204 # these attributes get copied down to child handles by default 1205 'State' => \$h_state_store, # Holder for DBI::state 1206 'Err' => \$h_err_store, # Holder for DBI::err 1207 'Errstr' => \$h_errstr_store, # Holder for DBI::errstr 1208 'TraceLevel' => 0, 1209 FetchHashKeyName=> 'NAME', 1210 %$initial_attr, 1211 }; 1212 my ($h, $i) = _new_handle('DBI::dr', '', $attr, $imp_data, $class); 1213 1214 # XXX DBI_PROFILE unless DBI::PurePerl because for some reason 1215 # it kills the t/zz_*_pp.t tests (they silently exit early) 1216 if ($ENV{DBI_PROFILE} && !$DBI::PurePerl) { 1217 # The profile object created here when the first driver is loaded 1218 # is shared by all drivers so we end up with just one set of profile 1219 # data and thus the 'total time in DBI' is really the true total. 1220 if (!$shared_profile) { # first time 1221 $h->{Profile} = $ENV{DBI_PROFILE}; 1222 $shared_profile = $h->{Profile}; 1223 } 1224 else { 1225 $h->{Profile} = $shared_profile; 1226 } 1227 } 1228 return $h unless wantarray; 1229 ($h, $i); 1230 } 1231 1232 sub _new_dbh { # called by DBD::<drivername>::dr::connect() 1233 my ($drh, $attr, $imp_data) = @_; 1234 my $imp_class = $drh->{ImplementorClass} 1235 or Carp::croak("DBI _new_dbh: $drh has no ImplementorClass"); 1236 substr($imp_class,-4,4) = '::db'; 1237 my $app_class = ref $drh; 1238 substr($app_class,-4,4) = '::db'; 1239 $attr->{Err} ||= \my $err; 1240 $attr->{Errstr} ||= \my $errstr; 1241 $attr->{State} ||= \my $state; 1242 _new_handle($app_class, $drh, $attr, $imp_data, $imp_class); 1243 } 1244 1245 sub _new_sth { # called by DBD::<drivername>::db::prepare) 1246 my ($dbh, $attr, $imp_data) = @_; 1247 my $imp_class = $dbh->{ImplementorClass} 1248 or Carp::croak("DBI _new_sth: $dbh has no ImplementorClass"); 1249 substr($imp_class,-4,4) = '::st'; 1250 my $app_class = ref $dbh; 1251 substr($app_class,-4,4) = '::st'; 1252 _new_handle($app_class, $dbh, $attr, $imp_data, $imp_class); 1253 } 1254 1255 1256 # end of DBI package 1257 1258 1259 1260 # -------------------------------------------------------------------- 1261 # === The internal DBI Switch pseudo 'driver' class === 1262 1263 { package # hide from PAUSE 1264 DBD::Switch::dr; 1265 DBI->setup_driver('DBD::Switch'); # sets up @ISA 1266 1267 $DBD::Switch::dr::imp_data_size = 0; 1268 $DBD::Switch::dr::imp_data_size = 0; # avoid typo warning 1269 my $drh; 1270 1271 sub driver { 1272 return $drh if $drh; # a package global 1273 1274 my $inner; 1275 ($drh, $inner) = DBI::_new_drh('DBD::Switch::dr', { 1276 'Name' => 'Switch', 1277 'Version' => $DBI::VERSION, 1278 'Attribution' => "DBI $DBI::VERSION by Tim Bunce", 1279 }); 1280 Carp::croak("DBD::Switch init failed!") unless ($drh && $inner); 1281 return $drh; 1282 } 1283 sub CLONE { 1284 undef $drh; 1285 } 1286 1287 sub FETCH { 1288 my($drh, $key) = @_; 1289 return DBI->trace if $key eq 'DebugDispatch'; 1290 return undef if $key eq 'DebugLog'; # not worth fetching, sorry 1291 return $drh->DBD::_::dr::FETCH($key); 1292 undef; 1293 } 1294 sub STORE { 1295 my($drh, $key, $value) = @_; 1296 if ($key eq 'DebugDispatch') { 1297 DBI->trace($value); 1298 } elsif ($key eq 'DebugLog') { 1299 DBI->trace(-1, $value); 1300 } else { 1301 $drh->DBD::_::dr::STORE($key, $value); 1302 } 1303 } 1304 } 1305 1306 1307 # -------------------------------------------------------------------- 1308 # === OPTIONAL MINIMAL BASE CLASSES FOR DBI SUBCLASSES === 1309 1310 # We only define default methods for harmless functions. 1311 # We don't, for example, define a DBD::_::st::prepare() 1312 1313 { package # hide from PAUSE 1314 DBD::_::common; # ====== Common base class methods ====== 1315 use strict; 1316 1317 # methods common to all handle types: 1318 1319 sub _not_impl { 1320 my ($h, $method) = @_; 1321 $h->trace_msg("Driver does not implement the $method method.\n"); 1322 return; # empty list / undef 1323 } 1324 1325 # generic TIEHASH default methods: 1326 sub FIRSTKEY { } 1327 sub NEXTKEY { } 1328 sub EXISTS { defined($_[0]->FETCH($_[1])) } # XXX undef? 1329 sub CLEAR { Carp::carp "Can't CLEAR $_[0] (DBI)" } 1330 1331 sub FETCH_many { # XXX should move to C one day 1332 my $h = shift; 1333 return map { $h->FETCH($_) } @_; 1334 } 1335 1336 *dump_handle = \&DBI::dump_handle; 1337 1338 sub install_method { 1339 # special class method called directly by apps and/or drivers 1340 # to install new methods into the DBI dispatcher 1341 # DBD::Foo::db->install_method("foo_mumble", { usage => [...], options => '...' }); 1342 my ($class, $method, $attr) = @_; 1343 Carp::croak("Class '$class' must begin with DBD:: and end with ::db or ::st") 1344 unless $class =~ /^DBD::(\w+)::(dr|db|st)$/; 1345 my ($driver, $subtype) = ($1, $2); 1346 Carp::croak("invalid method name '$method'") 1347 unless $method =~ m/^([a-z]+_)\w+$/; 1348 my $prefix = $1; 1349 my $reg_info = $dbd_prefix_registry->{$prefix}; 1350 Carp::carp("method name prefix '$prefix' is not associated with a registered driver") unless $reg_info; 1351 1352 my $full_method = "DBI::$subtype}::$method"; 1353 $DBI::installed_methods{$full_method} = $attr; 1354 1355 my (undef, $filename, $line) = caller; 1356 # XXX reformat $attr as needed for _install_method 1357 my %attr = %{$attr||{}}; # copy so we can edit 1358 DBI->_install_method("DBI::$subtype}::$method", "$filename at line $line", \%attr); 1359 } 1360 1361 sub parse_trace_flags { 1362 my ($h, $spec) = @_; 1363 my $level = 0; 1364 my $flags = 0; 1365 my @unknown; 1366 for my $word (split /\s*[|&,]\s*/, $spec) { 1367 if (DBI::looks_like_number($word) && $word <= 0xF && $word >= 0) { 1368 $level = $word; 1369 } elsif ($word eq 'ALL') { 1370 $flags = 0x7FFFFFFF; # XXX last bit causes negative headaches 1371 last; 1372 } elsif (my $flag = $h->parse_trace_flag($word)) { 1373 $flags |= $flag; 1374 } 1375 else { 1376 push @unknown, $word; 1377 } 1378 } 1379 if (@unknown && (ref $h ? $h->FETCH('Warn') : 1)) { 1380 Carp::carp("$h->parse_trace_flags($spec) ignored unknown trace flags: ". 1381 join(" ", map { DBI::neat($_) } @unknown)); 1382 } 1383 $flags |= $level; 1384 return $flags; 1385 } 1386 1387 sub parse_trace_flag { 1388 my ($h, $name) = @_; 1389 # 0xddDDDDrL (driver, DBI, reserved, Level) 1390 return 0x00000100 if $name eq 'SQL'; 1391 return; 1392 } 1393 1394 sub private_attribute_info { 1395 return undef; 1396 } 1397 1398 } 1399 1400 1401 { package # hide from PAUSE 1402 DBD::_::dr; # ====== DRIVER ====== 1403 @DBD::_::dr::ISA = qw(DBD::_::common); 1404 use strict; 1405 1406 sub default_user { 1407 my ($drh, $user, $pass, $attr) = @_; 1408 $user = $ENV{DBI_USER} unless defined $user; 1409 $pass = $ENV{DBI_PASS} unless defined $pass; 1410 return ($user, $pass); 1411 } 1412 1413 sub connect { # normally overridden, but a handy default 1414 my ($drh, $dsn, $user, $auth) = @_; 1415 my ($this) = DBI::_new_dbh($drh, { 1416 'Name' => $dsn, 1417 }); 1418 # XXX debatable as there's no "server side" here 1419 # (and now many uses would trigger warnings on DESTROY) 1420 # $this->STORE(Active => 1); 1421 # so drivers should set it in their own connect 1422 $this; 1423 } 1424 1425 1426 sub connect_cached { 1427 my $drh = shift; 1428 my ($dsn, $user, $auth, $attr) = @_; 1429 1430 my $cache = $drh->{CachedKids} ||= {}; 1431 my $key = do { local $^W; 1432 join "!\001", $dsn, $user, $auth, DBI::_concat_hash_sorted($attr, "=\001", ",\001", 0, 0) 1433 }; 1434 my $dbh = $cache->{$key}; 1435 $drh->trace_msg(sprintf(" connect_cached: key '$key', cached dbh $dbh\n", DBI::neat($key), DBI::neat($dbh))) 1436 if $DBI::dbi_debug >= 4; 1437 1438 my $cb = $attr->{Callbacks}; # take care not to autovivify 1439 if ($dbh && $dbh->FETCH('Active') && eval { $dbh->ping }) { 1440 # If the caller has provided a callback then call it 1441 if ($cb and $cb = $cb->{"connect_cached.reused"}) { 1442 local $_ = "connect_cached.reused"; 1443 $cb->($dbh, $dsn, $user, $auth, $attr); 1444 } 1445 return $dbh; 1446 } 1447 1448 # If the caller has provided a callback then call it 1449 if ($cb and $cb = $cb->{"connect_cached.new"}) { 1450 local $_ = "connect_cached.new"; 1451 $cb->($dbh, $dsn, $user, $auth, $attr); 1452 } 1453 1454 $dbh = $drh->connect(@_); 1455 $cache->{$key} = $dbh; # replace prev entry, even if connect failed 1456 return $dbh; 1457 } 1458 1459 } 1460 1461 1462 { package # hide from PAUSE 1463 DBD::_::db; # ====== DATABASE ====== 1464 @DBD::_::db::ISA = qw(DBD::_::common); 1465 use strict; 1466 1467 sub clone { 1468 my ($old_dbh, $attr) = @_; 1469 my $closure = $old_dbh->{dbi_connect_closure} or return; 1470 unless ($attr) { 1471 # copy attributes visible in the attribute cache 1472 keys %$old_dbh; # reset iterator 1473 while ( my ($k, $v) = each %$old_dbh ) { 1474 # ignore non-code refs, i.e., caches, handles, Err etc 1475 next if ref $v && ref $v ne 'CODE'; # HandleError etc 1476 $attr->{$k} = $v; 1477 } 1478 # explicitly set attributes which are unlikely to be in the 1479 # attribute cache, i.e., boolean's and some others 1480 $attr->{$_} = $old_dbh->FETCH($_) for (qw( 1481 AutoCommit ChopBlanks InactiveDestroy 1482 LongTruncOk PrintError PrintWarn Profile RaiseError 1483 ShowErrorStatement TaintIn TaintOut 1484 )); 1485 } 1486 # use Data::Dumper; warn Dumper([$old_dbh, $attr]); 1487 my $new_dbh = &$closure($old_dbh, $attr); 1488 unless ($new_dbh) { 1489 # need to copy err/errstr from driver back into $old_dbh 1490 my $drh = $old_dbh->{Driver}; 1491 return $old_dbh->set_err($drh->err, $drh->errstr, $drh->state); 1492 } 1493 return $new_dbh; 1494 } 1495 1496 sub quote_identifier { 1497 my ($dbh, @id) = @_; 1498 my $attr = (@id > 3 && ref($id[-1])) ? pop @id : undef; 1499 1500 my $info = $dbh->{dbi_quote_identifier_cache} ||= [ 1501 $dbh->get_info(29) || '"', # SQL_IDENTIFIER_QUOTE_CHAR 1502 $dbh->get_info(41) || '.', # SQL_CATALOG_NAME_SEPARATOR 1503 $dbh->get_info(114) || 1, # SQL_CATALOG_LOCATION 1504 ]; 1505 1506 my $quote = $info->[0]; 1507 foreach (@id) { # quote the elements 1508 next unless defined; 1509 s/$quote/$quote$quote/g; # escape embedded quotes 1510 $_ = qq{$quote$_$quote}; 1511 } 1512 1513 # strip out catalog if present for special handling 1514 my $catalog = (@id >= 3) ? shift @id : undef; 1515 1516 # join the dots, ignoring any null/undef elements (ie schema) 1517 my $quoted_id = join '.', grep { defined } @id; 1518 1519 if ($catalog) { # add catalog correctly 1520 $quoted_id = ($info->[2] == 2) # SQL_CL_END 1521 ? $quoted_id . $info->[1] . $catalog 1522 : $catalog . $info->[1] . $quoted_id; 1523 } 1524 return $quoted_id; 1525 } 1526 1527 sub quote { 1528 my ($dbh, $str, $data_type) = @_; 1529 1530 return "NULL" unless defined $str; 1531 unless ($data_type) { 1532 $str =~ s/'/''/g; # ISO SQL2 1533 return "'$str'"; 1534 } 1535 1536 my $dbi_literal_quote_cache = $dbh->{'dbi_literal_quote_cache'} ||= [ {} , {} ]; 1537 my ($prefixes, $suffixes) = @$dbi_literal_quote_cache; 1538 1539 my $lp = $prefixes->{$data_type}; 1540 my $ls = $suffixes->{$data_type}; 1541 1542 if ( ! defined $lp || ! defined $ls ) { 1543 my $ti = $dbh->type_info($data_type); 1544 $lp = $prefixes->{$data_type} = $ti ? $ti->{LITERAL_PREFIX} || "" : "'"; 1545 $ls = $suffixes->{$data_type} = $ti ? $ti->{LITERAL_SUFFIX} || "" : "'"; 1546 } 1547 return $str unless $lp || $ls; # no quoting required 1548 1549 # XXX don't know what the standard says about escaping 1550 # in the 'general case' (where $lp != "'"). 1551 # So we just do this and hope: 1552 $str =~ s/$lp/$lp$lp/g 1553 if $lp && $lp eq $ls && ($lp eq "'" || $lp eq '"'); 1554 return "$lp$str$ls"; 1555 } 1556 1557 sub rows { -1 } # here so $DBI::rows 'works' after using $dbh 1558 1559 sub do { 1560 my($dbh, $statement, $attr, @params) = @_; 1561 my $sth = $dbh->prepare($statement, $attr) or return undef; 1562 $sth->execute(@params) or return undef; 1563 my $rows = $sth->rows; 1564 ($rows == 0) ? "0E0" : $rows; 1565 } 1566 1567 sub _do_selectrow { 1568 my ($method, $dbh, $stmt, $attr, @bind) = @_; 1569 my $sth = ((ref $stmt) ? $stmt : $dbh->prepare($stmt, $attr)) 1570 or return; 1571 $sth->execute(@bind) 1572 or return; 1573 my $row = $sth->$method() 1574 and $sth->finish; 1575 return $row; 1576 } 1577 1578 sub selectrow_hashref { return _do_selectrow('fetchrow_hashref', @_); } 1579 1580 # XXX selectrow_array/ref also have C implementations in Driver.xst 1581 sub selectrow_arrayref { return _do_selectrow('fetchrow_arrayref', @_); } 1582 sub selectrow_array { 1583 my $row = _do_selectrow('fetchrow_arrayref', @_) or return; 1584 return $row->[0] unless wantarray; 1585 return @$row; 1586 } 1587 1588 # XXX selectall_arrayref also has C implementation in Driver.xst 1589 # which fallsback to this if a slice is given 1590 sub selectall_arrayref { 1591 my ($dbh, $stmt, $attr, @bind) = @_; 1592 my $sth = (ref $stmt) ? $stmt : $dbh->prepare($stmt, $attr) 1593 or return; 1594 $sth->execute(@bind) || return; 1595 my $slice = $attr->{Slice}; # typically undef, else hash or array ref 1596 if (!$slice and $slice=$attr->{Columns}) { 1597 if (ref $slice eq 'ARRAY') { # map col idx to perl array idx 1598 $slice = [ @{$attr->{Columns}} ]; # take a copy 1599 for (@$slice) { $_-- } 1600 } 1601 } 1602 my $rows = $sth->fetchall_arrayref($slice, my $MaxRows = $attr->{MaxRows}); 1603 $sth->finish if defined $MaxRows; 1604 return $rows; 1605 } 1606 1607 sub selectall_hashref { 1608 my ($dbh, $stmt, $key_field, $attr, @bind) = @_; 1609 my $sth = (ref $stmt) ? $stmt : $dbh->prepare($stmt, $attr); 1610 return unless $sth; 1611 $sth->execute(@bind) || return; 1612 return $sth->fetchall_hashref($key_field); 1613 } 1614 1615 sub selectcol_arrayref { 1616 my ($dbh, $stmt, $attr, @bind) = @_; 1617 my $sth = (ref $stmt) ? $stmt : $dbh->prepare($stmt, $attr); 1618 return unless $sth; 1619 $sth->execute(@bind) || return; 1620 my @columns = ($attr->{Columns}) ? @{$attr->{Columns}} : (1); 1621 my @values = (undef) x @columns; 1622 my $idx = 0; 1623 for (@columns) { 1624 $sth->bind_col($_, \$values[$idx++]) || return; 1625 } 1626 my @col; 1627 if (my $max = $attr->{MaxRows}) { 1628 push @col, @values while @col<$max && $sth->fetch; 1629 } 1630 else { 1631 push @col, @values while $sth->fetch; 1632 } 1633 return \@col; 1634 } 1635 1636 sub prepare_cached { 1637 my ($dbh, $statement, $attr, $if_active) = @_; 1638 1639 # Needs support at dbh level to clear cache before complaining about 1640 # active children. The XS template code does this. Drivers not using 1641 # the template must handle clearing the cache themselves. 1642 my $cache = $dbh->{CachedKids} ||= {}; 1643 my $key = do { local $^W; 1644 join "!\001", $statement, DBI::_concat_hash_sorted($attr, "=\001", ",\001", 0, 0) 1645 }; 1646 my $sth = $cache->{$key}; 1647 1648 if ($sth) { 1649 return $sth unless $sth->FETCH('Active'); 1650 Carp::carp("prepare_cached($statement) statement handle $sth still Active") 1651 unless ($if_active ||= 0); 1652 $sth->finish if $if_active <= 1; 1653 return $sth if $if_active <= 2; 1654 } 1655 1656 $sth = $dbh->prepare($statement, $attr); 1657 $cache->{$key} = $sth if $sth; 1658 1659 return $sth; 1660 } 1661 1662 sub ping { 1663 my $dbh = shift; 1664 $dbh->_not_impl('ping'); 1665 # "0 but true" is a special kind of true 0 that is used here so 1666 # applications can check if the ping was a real ping or not 1667 ($dbh->FETCH('Active')) ? "0 but true" : 0; 1668 } 1669 1670 sub begin_work { 1671 my $dbh = shift; 1672 return $dbh->set_err($DBI::stderr, "Already in a transaction") 1673 unless $dbh->FETCH('AutoCommit'); 1674 $dbh->STORE('AutoCommit', 0); # will croak if driver doesn't support it 1675 $dbh->STORE('BegunWork', 1); # trigger post commit/rollback action 1676 return 1; 1677 } 1678 1679 sub primary_key { 1680 my ($dbh, @args) = @_; 1681 my $sth = $dbh->primary_key_info(@args) or return; 1682 my ($row, @col); 1683 push @col, $row->[3] while ($row = $sth->fetch); 1684 Carp::croak("primary_key method not called in list context") 1685 unless wantarray; # leave us some elbow room 1686 return @col; 1687 } 1688 1689 sub tables { 1690 my ($dbh, @args) = @_; 1691 my $sth = $dbh->table_info(@args[0,1,2,3,4]) or return; 1692 my $tables = $sth->fetchall_arrayref or return; 1693 my @tables; 1694 if ($dbh->get_info(29)) { # SQL_IDENTIFIER_QUOTE_CHAR 1695 @tables = map { $dbh->quote_identifier( @{$_}[0,1,2] ) } @$tables; 1696 } 1697 else { # temporary old style hack (yeach) 1698 @tables = map { 1699 my $name = $_->[2]; 1700 if ($_->[1]) { 1701 my $schema = $_->[1]; 1702 # a sad hack (mostly for Informix I recall) 1703 my $quote = ($schema eq uc($schema)) ? '' : '"'; 1704 $name = "$quote$schema$quote.$name" 1705 } 1706 $name; 1707 } @$tables; 1708 } 1709 return @tables; 1710 } 1711 1712 sub type_info { # this should be sufficient for all drivers 1713 my ($dbh, $data_type) = @_; 1714 my $idx_hash; 1715 my $tia = $dbh->{dbi_type_info_row_cache}; 1716 if ($tia) { 1717 $idx_hash = $dbh->{dbi_type_info_idx_cache}; 1718 } 1719 else { 1720 my $temp = $dbh->type_info_all; 1721 return unless $temp && @$temp; 1722 # we cache here because type_info_all may be expensive to call 1723 # (and we take a copy so the following shift can't corrupt 1724 # the data that may be returned by future calls to type_info_all) 1725 $tia = $dbh->{dbi_type_info_row_cache} = [ @$temp ]; 1726 $idx_hash = $dbh->{dbi_type_info_idx_cache} = shift @$tia; 1727 } 1728 1729 my $dt_idx = $idx_hash->{DATA_TYPE} || $idx_hash->{data_type}; 1730 Carp::croak("type_info_all returned non-standard DATA_TYPE index value ($dt_idx != 1)") 1731 if $dt_idx && $dt_idx != 1; 1732 1733 # --- simple DATA_TYPE match filter 1734 my @ti; 1735 my @data_type_list = (ref $data_type) ? @$data_type : ($data_type); 1736 foreach $data_type (@data_type_list) { 1737 if (defined($data_type) && $data_type != DBI::SQL_ALL_TYPES()) { 1738 push @ti, grep { $_->[$dt_idx] == $data_type } @$tia; 1739 } 1740 else { # SQL_ALL_TYPES 1741 push @ti, @$tia; 1742 } 1743 last if @ti; # found at least one match 1744 } 1745 1746 # --- format results into list of hash refs 1747 my $idx_fields = keys %$idx_hash; 1748 my @idx_names = map { uc($_) } keys %$idx_hash; 1749 my @idx_values = values %$idx_hash; 1750 Carp::croak "type_info_all result has $idx_fields keys but ".(@{$ti[0]})." fields" 1751 if @ti && @{$ti[0]} != $idx_fields; 1752 my @out = map { 1753 my %h; @h{@idx_names} = @{$_}[ @idx_values ]; \%h; 1754 } @ti; 1755 return $out[0] unless wantarray; 1756 return @out; 1757 } 1758 1759 sub data_sources { 1760 my ($dbh, @other) = @_; 1761 my $drh = $dbh->{Driver}; # XXX proxy issues? 1762 return $drh->data_sources(@other); 1763 } 1764 1765 } 1766 1767 1768 { package # hide from PAUSE 1769 DBD::_::st; # ====== STATEMENT ====== 1770 @DBD::_::st::ISA = qw(DBD::_::common); 1771 use strict; 1772 1773 sub bind_param { Carp::croak("Can't bind_param, not implement by driver") } 1774 1775 # 1776 # ******************************************************** 1777 # 1778 # BEGIN ARRAY BINDING 1779 # 1780 # Array binding support for drivers which don't support 1781 # array binding, but have sufficient interfaces to fake it. 1782 # NOTE: mixing scalars and arrayrefs requires using bind_param_array 1783 # for *all* params...unless we modify bind_param for the default 1784 # case... 1785 # 1786 # 2002-Apr-10 D. Arnold 1787 1788 sub bind_param_array { 1789 my $sth = shift; 1790 my ($p_id, $value_array, $attr) = @_; 1791 1792 return $sth->set_err($DBI::stderr, "Value for parameter $p_id must be a scalar or an arrayref, not a ".ref($value_array)) 1793 if defined $value_array and ref $value_array and ref $value_array ne 'ARRAY'; 1794 1795 return $sth->set_err($DBI::stderr, "Can't use named placeholder '$p_id' for non-driver supported bind_param_array") 1796 unless DBI::looks_like_number($p_id); # because we rely on execute(@ary) here 1797 1798 return $sth->set_err($DBI::stderr, "Placeholder '$p_id' is out of range") 1799 if $p_id <= 0; # can't easily/reliably test for too big 1800 1801 # get/create arrayref to hold params 1802 my $hash_of_arrays = $sth->{ParamArrays} ||= { }; 1803 1804 # If the bind has attribs then we rely on the driver conforming to 1805 # the DBI spec in that a single bind_param() call with those attribs 1806 # makes them 'sticky' and apply to all later execute(@values) calls. 1807 # Since we only call bind_param() if we're given attribs then 1808 # applications using drivers that don't support bind_param can still 1809 # use bind_param_array() so long as they don't pass any attribs. 1810 1811 $$hash_of_arrays{$p_id} = $value_array; 1812 return $sth->bind_param($p_id, undef, $attr) 1813 if $attr; 1814 1; 1815 } 1816 1817 sub bind_param_inout_array { 1818 my $sth = shift; 1819 # XXX not supported so we just call bind_param_array instead 1820 # and then return an error 1821 my ($p_num, $value_array, $attr) = @_; 1822 $sth->bind_param_array($p_num, $value_array, $attr); 1823 return $sth->set_err($DBI::stderr, "bind_param_inout_array not supported"); 1824 } 1825 1826 sub bind_columns { 1827 my $sth = shift; 1828 my $fields = $sth->FETCH('NUM_OF_FIELDS') || 0; 1829 if ($fields <= 0 && !$sth->{Active}) { 1830 return $sth->set_err($DBI::stderr, "Statement has no result columns to bind" 1831 ." (perhaps you need to successfully call execute first)"); 1832 } 1833 # Backwards compatibility for old-style call with attribute hash 1834 # ref as first arg. Skip arg if undef or a hash ref. 1835 my $attr; 1836 $attr = shift if !defined $_[0] or ref($_[0]) eq 'HASH'; 1837 1838 my $idx = 0; 1839 $sth->bind_col(++$idx, shift, $attr) or return 1840 while (@_ and $idx < $fields); 1841 1842 return $sth->set_err($DBI::stderr, "bind_columns called with ".($idx+@_)." values but $fields are needed") 1843 if @_ or $idx != $fields; 1844 1845 return 1; 1846 } 1847 1848 sub execute_array { 1849 my $sth = shift; 1850 my ($attr, @array_of_arrays) = @_; 1851 my $NUM_OF_PARAMS = $sth->FETCH('NUM_OF_PARAMS'); # may be undef at this point 1852 1853 # get tuple status array or hash attribute 1854 my $tuple_sts = $attr->{ArrayTupleStatus}; 1855 return $sth->set_err($DBI::stderr, "ArrayTupleStatus attribute must be an arrayref") 1856 if $tuple_sts and ref $tuple_sts ne 'ARRAY'; 1857 1858 # bind all supplied arrays 1859 if (@array_of_arrays) { 1860 $sth->{ParamArrays} = { }; # clear out old params 1861 return $sth->set_err($DBI::stderr, 1862 @array_of_arrays." bind values supplied but $NUM_OF_PARAMS expected") 1863 if defined ($NUM_OF_PARAMS) && @array_of_arrays != $NUM_OF_PARAMS; 1864 $sth->bind_param_array($_, $array_of_arrays[$_-1]) or return 1865 foreach (1..@array_of_arrays); 1866 } 1867 1868 my $fetch_tuple_sub; 1869 1870 if ($fetch_tuple_sub = $attr->{ArrayTupleFetch}) { # fetch on demand 1871 1872 return $sth->set_err($DBI::stderr, 1873 "Can't use both ArrayTupleFetch and explicit bind values") 1874 if @array_of_arrays; # previous bind_param_array calls will simply be ignored 1875 1876 if (UNIVERSAL::isa($fetch_tuple_sub,'DBI::st')) { 1877 my $fetch_sth = $fetch_tuple_sub; 1878 return $sth->set_err($DBI::stderr, 1879 "ArrayTupleFetch sth is not Active, need to execute() it first") 1880 unless $fetch_sth->{Active}; 1881 # check column count match to give more friendly message 1882 my $NUM_OF_FIELDS = $fetch_sth->{NUM_OF_FIELDS}; 1883 return $sth->set_err($DBI::stderr, 1884 "$NUM_OF_FIELDS columns from ArrayTupleFetch sth but $NUM_OF_PARAMS expected") 1885 if defined($NUM_OF_FIELDS) && defined($NUM_OF_PARAMS) 1886 && $NUM_OF_FIELDS != $NUM_OF_PARAMS; 1887 $fetch_tuple_sub = sub { $fetch_sth->fetchrow_arrayref }; 1888 } 1889 elsif (!UNIVERSAL::isa($fetch_tuple_sub,'CODE')) { 1890 return $sth->set_err($DBI::stderr, "ArrayTupleFetch '$fetch_tuple_sub' is not a code ref or statement handle"); 1891 } 1892 1893 } 1894 else { 1895 my $NUM_OF_PARAMS_given = keys %{ $sth->{ParamArrays} || {} }; 1896 return $sth->set_err($DBI::stderr, 1897 "$NUM_OF_PARAMS_given bind values supplied but $NUM_OF_PARAMS expected") 1898 if defined($NUM_OF_PARAMS) && $NUM_OF_PARAMS != $NUM_OF_PARAMS_given; 1899 1900 # get the length of a bound array 1901 my $maxlen; 1902 my %hash_of_arrays = %{$sth->{ParamArrays}}; 1903 foreach (keys(%hash_of_arrays)) { 1904 my $ary = $hash_of_arrays{$_}; 1905 next unless ref $ary eq 'ARRAY'; 1906 $maxlen = @$ary if !$maxlen || @$ary > $maxlen; 1907 } 1908 # if there are no arrays then execute scalars once 1909 $maxlen = 1 unless defined $maxlen; 1910 my @bind_ids = 1..keys(%hash_of_arrays); 1911 1912 my $tuple_idx = 0; 1913 $fetch_tuple_sub = sub { 1914 return if $tuple_idx >= $maxlen; 1915 my @tuple = map { 1916 my $a = $hash_of_arrays{$_}; 1917 ref($a) ? $a->[$tuple_idx] : $a 1918 } @bind_ids; 1919 ++$tuple_idx; 1920 return \@tuple; 1921 }; 1922 } 1923 # pass thru the callers scalar or list context 1924 return $sth->execute_for_fetch($fetch_tuple_sub, $tuple_sts); 1925 } 1926 1927 sub execute_for_fetch { 1928 my ($sth, $fetch_tuple_sub, $tuple_status) = @_; 1929 # start with empty status array 1930 ($tuple_status) ? @$tuple_status = () : $tuple_status = []; 1931 1932 my $rc_total = 0; 1933 my $err_count; 1934 while ( my $tuple = &$fetch_tuple_sub() ) { 1935 if ( my $rc = $sth->execute(@$tuple) ) { 1936 push @$tuple_status, $rc; 1937 $rc_total = ($rc >= 0 && $rc_total >= 0) ? $rc_total + $rc : -1; 1938 } 1939 else { 1940 $err_count++; 1941 push @$tuple_status, [ $sth->err, $sth->errstr, $sth->state ]; 1942 # XXX drivers implementing execute_for_fetch could opt to "last;" here 1943 # if they know the error code means no further executes will work. 1944 } 1945 } 1946 my $tuples = @$tuple_status; 1947 return $sth->set_err($DBI::stderr, "executing $tuples generated $err_count errors") 1948 if $err_count; 1949 $tuples ||= "0E0"; 1950 return $tuples unless wantarray; 1951 return ($tuples, $rc_total); 1952 } 1953 1954 1955 sub fetchall_arrayref { # ALSO IN Driver.xst 1956 my ($sth, $slice, $max_rows) = @_; 1957 1958 # when batch fetching with $max_rows were very likely to try to 1959 # fetch the 'next batch' after the previous batch returned 1960 # <=$max_rows. So don't treat that as an error. 1961 return undef if $max_rows and not $sth->FETCH('Active'); 1962 1963 my $mode = ref($slice) || 'ARRAY'; 1964 my @rows; 1965 my $row; 1966 if ($mode eq 'ARRAY') { 1967 # we copy the array here because fetch (currently) always 1968 # returns the same array ref. XXX 1969 if ($slice && @$slice) { 1970 $max_rows = -1 unless defined $max_rows; 1971 push @rows, [ @{$row}[ @$slice] ] 1972 while($max_rows-- and $row = $sth->fetch); 1973 } 1974 elsif (defined $max_rows) { 1975 push @rows, [ @$row ] 1976 while($max_rows-- and $row = $sth->fetch); 1977 } 1978 else { 1979 push @rows, [ @$row ] while($row = $sth->fetch); 1980 } 1981 } 1982 elsif ($mode eq 'HASH') { 1983 $max_rows = -1 unless defined $max_rows; 1984 if (keys %$slice) { 1985 my @o_keys = keys %$slice; 1986 my @i_keys = map { lc } keys %$slice; 1987 # XXX this could be made faster by pre-binding a local hash 1988 # using bind_columns and then copying it per row 1989 while ($max_rows-- and $row = $sth->fetchrow_hashref('NAME_lc')) { 1990 my %hash; 1991 @hash{@o_keys} = @{$row}{@i_keys}; 1992 push @rows, \%hash; 1993 } 1994 } 1995 else { 1996 # XXX assumes new ref each fetchhash 1997 push @rows, $row 1998 while ($max_rows-- and $row = $sth->fetchrow_hashref()); 1999 } 2000 } 2001 else { Carp::croak("fetchall_arrayref($mode) invalid") } 2002 return \@rows; 2003 } 2004 2005 sub fetchall_hashref { 2006 my ($sth, $key_field) = @_; 2007 2008 my $hash_key_name = $sth->{FetchHashKeyName} || 'NAME'; 2009 my $names_hash = $sth->FETCH("$hash_key_name}_hash"); 2010 my @key_fields = (ref $key_field) ? @$key_field : ($key_field); 2011 my @key_indexes; 2012 my $num_of_fields = $sth->FETCH('NUM_OF_FIELDS'); 2013 foreach (@key_fields) { 2014 my $index = $names_hash->{$_}; # perl index not column 2015 $index = $_ - 1 if !defined $index && DBI::looks_like_number($_) && $_>=1 && $_ <= $num_of_fields; 2016 return $sth->set_err($DBI::stderr, "Field '$_' does not exist (not one of @{[keys %$names_hash]})") 2017 unless defined $index; 2018 push @key_indexes, $index; 2019 } 2020 my $rows = {}; 2021 my $NAME = $sth->FETCH($hash_key_name); 2022 my @row = (undef) x $num_of_fields; 2023 $sth->bind_columns(\(@row)); 2024 while ($sth->fetch) { 2025 my $ref = $rows; 2026 $ref = $ref->{$row[$_]} ||= {} for @key_indexes; 2027 @{$ref}{@$NAME} = @row; 2028 } 2029 return $rows; 2030 } 2031 2032 *dump_results = \&DBI::dump_results; 2033 2034 sub blob_copy_to_file { # returns length or undef on error 2035 my($self, $field, $filename_or_handleref, $blocksize) = @_; 2036 my $fh = $filename_or_handleref; 2037 my($len, $buf) = (0, ""); 2038 $blocksize ||= 512; # not too ambitious 2039 local(*FH); 2040 unless(ref $fh) { 2041 open(FH, ">$fh") || return undef; 2042 $fh = \*FH; 2043 } 2044 while(defined($self->blob_read($field, $len, $blocksize, \$buf))) { 2045 print $fh $buf; 2046 $len += length $buf; 2047 } 2048 close(FH); 2049 $len; 2050 } 2051 2052 sub more_results { 2053 shift->{syb_more_results}; # handy grandfathering 2054 } 2055 2056 } 2057 2058 unless ($DBI::PurePerl) { # See install_driver 2059 { @DBD::_mem::dr::ISA = qw(DBD::_mem::common); } 2060 { @DBD::_mem::db::ISA = qw(DBD::_mem::common); } 2061 { @DBD::_mem::st::ISA = qw(DBD::_mem::common); } 2062 # DBD::_mem::common::DESTROY is implemented in DBI.xs 2063 } 2064 2065 1; 2066 __END__ 2067 2068 =head1 DESCRIPTION 2069 2070 The DBI is a database access module for the Perl programming language. It defines 2071 a set of methods, variables, and conventions that provide a consistent 2072 database interface, independent of the actual database being used. 2073 2074 It is important to remember that the DBI is just an interface. 2075 The DBI is a layer 2076 of "glue" between an application and one or more database I<driver> 2077 modules. It is the driver modules which do most of the real work. The DBI 2078 provides a standard interface and framework for the drivers to operate 2079 within. 2080 2081 2082 =head2 Architecture of a DBI Application 2083 2084 |<- Scope of DBI ->| 2085 .-. .--------------. .-------------. 2086 .-------. | |---| XYZ Driver |---| XYZ Engine | 2087 | Perl | | | `--------------' `-------------' 2088 | script| |A| |D| .--------------. .-------------. 2089 | using |--|P|--|B|---|Oracle Driver |---|Oracle Engine| 2090 | DBI | |I| |I| `--------------' `-------------' 2091 | API | | |... 2092 |methods| | |... Other drivers 2093 `-------' | |... 2094 `-' 2095 2096 The API, or Application Programming Interface, defines the 2097 call interface and variables for Perl scripts to use. The API 2098 is implemented by the Perl DBI extension. 2099 2100 The DBI "dispatches" the method calls to the appropriate driver for 2101 actual execution. The DBI is also responsible for the dynamic loading 2102 of drivers, error checking and handling, providing default 2103 implementations for methods, and many other non-database specific duties. 2104 2105 Each driver 2106 contains implementations of the DBI methods using the 2107 private interface functions of the corresponding database engine. Only authors 2108 of sophisticated/multi-database applications or generic library 2109 functions need be concerned with drivers. 2110 2111 =head2 Notation and Conventions 2112 2113 The following conventions are used in this document: 2114 2115 $dbh Database handle object 2116 $sth Statement handle object 2117 $drh Driver handle object (rarely seen or used in applications) 2118 $h Any of the handle types above ($dbh, $sth, or $drh) 2119 $rc General Return Code (boolean: true=ok, false=error) 2120 $rv General Return Value (typically an integer) 2121 @ary List of values returned from the database, typically a row of data 2122 $rows Number of rows processed (if available, else -1) 2123 $fh A filehandle 2124 undef NULL values are represented by undefined values in Perl 2125 \%attr Reference to a hash of attribute values passed to methods 2126 2127 Note that Perl will automatically destroy database and statement handle objects 2128 if all references to them are deleted. 2129 2130 2131 =head2 Outline Usage 2132 2133 To use DBI, 2134 first you need to load the DBI module: 2135 2136 use DBI; 2137 use strict; 2138 2139 (The C<use strict;> isn't required but is strongly recommended.) 2140 2141 Then you need to L</connect> to your data source and get a I<handle> for that 2142 connection: 2143 2144 $dbh = DBI->connect($dsn, $user, $password, 2145 { RaiseError => 1, AutoCommit => 0 }); 2146 2147 Since connecting can be expensive, you generally just connect at the 2148 start of your program and disconnect at the end. 2149 2150 Explicitly defining the required C<AutoCommit> behaviour is strongly 2151 recommended and may become mandatory in a later version. This 2152 determines whether changes are automatically committed to the 2153 database when executed, or need to be explicitly committed later. 2154 2155 The DBI allows an application to "prepare" statements for later 2156 execution. A prepared statement is identified by a statement handle 2157 held in a Perl variable. 2158 We'll call the Perl variable C<$sth> in our examples. 2159 2160 The typical method call sequence for a C<SELECT> statement is: 2161 2162 prepare, 2163 execute, fetch, fetch, ... 2164 execute, fetch, fetch, ... 2165 execute, fetch, fetch, ... 2166 2167 for example: 2168 2169 $sth = $dbh->prepare("SELECT foo, bar FROM table WHERE baz=?"); 2170 2171 $sth->execute( $baz ); 2172 2173 while ( @row = $sth->fetchrow_array ) { 2174 print "@row\n"; 2175 } 2176 2177 The typical method call sequence for a I<non>-C<SELECT> statement is: 2178 2179 prepare, 2180 execute, 2181 execute, 2182 execute. 2183 2184 for example: 2185 2186 $sth = $dbh->prepare("INSERT INTO table(foo,bar,baz) VALUES (?,?,?)"); 2187 2188 while(<CSV>) { 2189 chomp; 2190 my ($foo,$bar,$baz) = split /,/; 2191 $sth->execute( $foo, $bar, $baz ); 2192 } 2193 2194 The C<do()> method can be used for non repeated I<non>-C<SELECT> statement 2195 (or with drivers that don't support placeholders): 2196 2197 $rows_affected = $dbh->do("UPDATE your_table SET foo = foo + 1"); 2198 2199 To commit your changes to the database (when L</AutoCommit> is off): 2200 2201 $dbh->commit; # or call $dbh->rollback; to undo changes 2202 2203 Finally, when you have finished working with the data source, you should 2204 L</disconnect> from it: 2205 2206 $dbh->disconnect; 2207 2208 2209 =head2 General Interface Rules & Caveats 2210 2211 The DBI does not have a concept of a "current session". Every session 2212 has a handle object (i.e., a C<$dbh>) returned from the C<connect> method. 2213 That handle object is used to invoke database related methods. 2214 2215 Most data is returned to the Perl script as strings. (Null values are 2216 returned as C<undef>.) This allows arbitrary precision numeric data to be 2217 handled without loss of accuracy. Beware that Perl may not preserve 2218 the same accuracy when the string is used as a number. 2219 2220 Dates and times are returned as character strings in the current 2221 default format of the corresponding database engine. Time zone effects 2222 are database/driver dependent. 2223 2224 Perl supports binary data in Perl strings, and the DBI will pass binary 2225 data to and from the driver without change. It is up to the driver 2226 implementors to decide how they wish to handle such binary data. 2227 2228 Perl supports two kinds of strings: unicode (utf8 internally) and non-unicode 2229 (defaults to iso-8859-1 if forced to assume an encoding). Drivers should 2230 accept both kinds of strings and, if required, convert them to the character 2231 set of the database being used. Similarly, when fetching from the database 2232 character data that isn't iso-8859-1 the driver should convert it into utf8. 2233 2234 Multiple SQL statements may not be combined in a single statement 2235 handle (C<$sth>), although some databases and drivers do support this 2236 (notably Sybase and SQL Server). 2237 2238 Non-sequential record reads are not supported in this version of the DBI. 2239 In other words, records can only be fetched in the order that the 2240 database returned them, and once fetched they are forgotten. 2241 2242 Positioned updates and deletes are not directly supported by the DBI. 2243 See the description of the C<CursorName> attribute for an alternative. 2244 2245 Individual driver implementors are free to provide any private 2246 functions and/or handle attributes that they feel are useful. 2247 Private driver functions can be invoked using the DBI C<func()> method. 2248 Private driver attributes are accessed just like standard attributes. 2249 2250 Many methods have an optional C<\%attr> parameter which can be used to 2251 pass information to the driver implementing the method. Except where 2252 specifically documented, the C<\%attr> parameter can only be used to pass 2253 driver specific hints. In general, you can ignore C<\%attr> parameters 2254 or pass it as C<undef>. 2255 2256 2257 =head2 Naming Conventions and Name Space 2258 2259 The DBI package and all packages below it (C<DBI::*>) are reserved for 2260 use by the DBI. Extensions and related modules use the C<DBIx::> 2261 namespace (see L<http://www.perl.com/CPAN/modules/by-module/DBIx/>). 2262 Package names beginning with C<DBD::> are reserved for use 2263 by DBI database drivers. All environment variables used by the DBI 2264 or by individual DBDs begin with "C<DBI_>" or "C<DBD_>". 2265 2266 The letter case used for attribute names is significant and plays an 2267 important part in the portability of DBI scripts. The case of the 2268 attribute name is used to signify who defined the meaning of that name 2269 and its values. 2270 2271 Case of name Has a meaning defined by 2272 ------------ ------------------------ 2273 UPPER_CASE Standards, e.g., X/Open, ISO SQL92 etc (portable) 2274 MixedCase DBI API (portable), underscores are not used. 2275 lower_case Driver or database engine specific (non-portable) 2276 2277 It is of the utmost importance that Driver developers only use 2278 lowercase attribute names when defining private attributes. Private 2279 attribute names must be prefixed with the driver name or suitable 2280 abbreviation (e.g., "C<ora_>" for Oracle, "C<ing_>" for Ingres, etc). 2281 2282 2283 =head2 SQL - A Query Language 2284 2285 Most DBI drivers require applications to use a dialect of SQL 2286 (Structured Query Language) to interact with the database engine. 2287 The L</"Standards Reference Information"> section provides links 2288 to useful information about SQL. 2289 2290 The DBI itself does not mandate or require any particular language to 2291 be used; it is language independent. In ODBC terms, the DBI is in 2292 "pass-thru" mode, although individual drivers might not be. The only requirement 2293 is that queries and other statements must be expressed as a single 2294 string of characters passed as the first argument to the L</prepare> or 2295 L</do> methods. 2296 2297 For an interesting diversion on the I<real> history of RDBMS and SQL, 2298 from the people who made it happen, see: 2299 2300 http://ftp.digital.com/pub/DEC/SRC/technical-notes/SRC-1997-018-html/sqlr95.html 2301 2302 Follow the "Full Contents" then "Intergalactic dataspeak" links for the 2303 SQL history. 2304 2305 =head2 Placeholders and Bind Values 2306 2307 Some drivers support placeholders and bind values. 2308 I<Placeholders>, also called parameter markers, are used to indicate 2309 values in a database statement that will be supplied later, 2310 before the prepared statement is executed. For example, an application 2311 might use the following to insert a row of data into the SALES table: 2312 2313 INSERT INTO sales (product_code, qty, price) VALUES (?, ?, ?) 2314 2315 or the following, to select the description for a product: 2316 2317 SELECT description FROM products WHERE product_code = ? 2318 2319 The C<?> characters are the placeholders. The association of actual 2320 values with placeholders is known as I<binding>, and the values are 2321 referred to as I<bind values>. 2322 Note that the C<?> is not enclosed in quotation marks, even when the 2323 placeholder represents a string. 2324 2325 Some drivers also allow placeholders like C<:>I<name> and C<:>I<N> (e.g., 2326 C<:1>, C<:2>, and so on) in addition to C<?>, but their use is not portable. 2327 2328 If the C<:>I<N> form of placeholder is supported by the driver you're using, 2329 then you should be able to use either L</bind_param> or L</execute> to bind 2330 values. Check your driver documentation. 2331 2332 With most drivers, placeholders can't be used for any element of a 2333 statement that would prevent the database server from validating the 2334 statement and creating a query execution plan for it. For example: 2335 2336 "SELECT name, age FROM ?" # wrong (will probably fail) 2337 "SELECT name, ? FROM people" # wrong (but may not 'fail') 2338 2339 Also, placeholders can only represent single scalar values. 2340 For example, the following 2341 statement won't work as expected for more than one value: 2342 2343 "SELECT name, age FROM people WHERE name IN (?)" # wrong 2344 "SELECT name, age FROM people WHERE name IN (?,?)" # two names 2345 2346 When using placeholders with the SQL C<LIKE> qualifier, you must 2347 remember that the placeholder substitutes for the whole string. 2348 So you should use "C<... LIKE ? ...>" and include any wildcard 2349 characters in the value that you bind to the placeholder. 2350 2351 B<NULL Values> 2352 2353 Undefined values, or C<undef>, are used to indicate NULL values. 2354 You can insert and update columns with a NULL value as you would a 2355 non-NULL value. These examples insert and update the column 2356 C<age> with a NULL value: 2357 2358 $sth = $dbh->prepare(qq{ 2359 INSERT INTO people (fullname, age) VALUES (?, ?) 2360 }); 2361 $sth->execute("Joe Bloggs", undef); 2362 2363 $sth = $dbh->prepare(qq{ 2364 UPDATE people SET age = ? WHERE fullname = ? 2365 }); 2366 $sth->execute(undef, "Joe Bloggs"); 2367 2368 However, care must be taken when trying to use NULL values in a 2369 C<WHERE> clause. Consider: 2370 2371 SELECT fullname FROM people WHERE age = ? 2372 2373 Binding an C<undef> (NULL) to the placeholder will I<not> select rows 2374 which have a NULL C<age>! At least for database engines that 2375 conform to the SQL standard. Refer to the SQL manual for your database 2376 engine or any SQL book for the reasons for this. To explicitly select 2377 NULLs you have to say "C<WHERE age IS NULL>". 2378 2379 A common issue is to have a code fragment handle a value that could be 2380 either C<defined> or C<undef> (non-NULL or NULL) at runtime. 2381 A simple technique is to prepare the appropriate statement as needed, 2382 and substitute the placeholder for non-NULL cases: 2383 2384 $sql_clause = defined $age? "age = ?" : "age IS NULL"; 2385 $sth = $dbh->prepare(qq{ 2386 SELECT fullname FROM people WHERE $sql_clause 2387 }); 2388 $sth->execute(defined $age ? $age : ()); 2389 2390 The following technique illustrates qualifying a C<WHERE> clause with 2391 several columns, whose associated values (C<defined> or C<undef>) are 2392 in a hash %h: 2393 2394 for my $col ("age", "phone", "email") { 2395 if (defined $h{$col}) { 2396 push @sql_qual, "$col = ?"; 2397 push @sql_bind, $h{$col}; 2398 } 2399 else { 2400 push @sql_qual, "$col IS NULL"; 2401 } 2402 } 2403 $sql_clause = join(" AND ", @sql_qual); 2404 $sth = $dbh->prepare(qq{ 2405 SELECT fullname FROM people WHERE $sql_clause 2406 }); 2407 $sth->execute(@sql_bind); 2408 2409 The techniques above call prepare for the SQL statement with each call to 2410 execute. Because calls to prepare() can be expensive, performance 2411 can suffer when an application iterates many times over statements 2412 like the above. 2413 2414 A better solution is a single C<WHERE> clause that supports both 2415 NULL and non-NULL comparisons. Its SQL statement would need to be 2416 prepared only once for all cases, thus improving performance. 2417 Several examples of C<WHERE> clauses that support this are presented 2418 below. But each example lacks portability, robustness, or simplicity. 2419 Whether an example is supported on your database engine depends on 2420 what SQL extensions it provides, and where it supports the C<?> 2421 placeholder in a statement. 2422 2423 0) age = ? 2424 1) NVL(age, xx) = NVL(?, xx) 2425 2) ISNULL(age, xx) = ISNULL(?, xx) 2426 3) DECODE(age, ?, 1, 0) = 1 2427 4) age = ? OR (age IS NULL AND ? IS NULL) 2428 5) age = ? OR (age IS NULL AND SP_ISNULL(?) = 1) 2429 6) age = ? OR (age IS NULL AND ? = 1) 2430 2431 Statements formed with the above C<WHERE> clauses require execute 2432 statements as follows. The arguments are required, whether their 2433 values are C<defined> or C<undef>. 2434 2435 0,1,2,3) $sth->execute($age); 2436 4,5) $sth->execute($age, $age); 2437 6) $sth->execute($age, defined($age) ? 0 : 1); 2438 2439 Example 0 should not work (as mentioned earlier), but may work on 2440 a few database engines anyway (e.g. Sybase). Example 0 is part 2441 of examples 4, 5, and 6, so if example 0 works, these other 2442 examples may work, even if the engine does not properly support 2443 the right hand side of the C<OR> expression. 2444 2445 Examples 1 and 2 are not robust: they require that you provide a 2446 valid column value xx (e.g. '~') which is not present in any row. 2447 That means you must have some notion of what data won't be stored 2448 in the column, and expect clients to adhere to that. 2449 2450 Example 5 requires that you provide a stored procedure (SP_ISNULL 2451 in this example) that acts as a function: it checks whether a value 2452 is null, and returns 1 if it is, or 0 if not. 2453 2454 Example 6, the least simple, is probably the most portable, i.e., it 2455 should work with with most, if not all, database engines. 2456 2457 Here is a table that indicates which examples above are known to 2458 work on various database engines: 2459 2460 -----Examples------ 2461 0 1 2 3 4 5 6 2462 - - - - - - - 2463 Oracle 9 N Y N Y Y ? Y 2464 Informix IDS 9 N N N Y N Y Y 2465 MS SQL N N Y N Y ? Y 2466 Sybase Y N N N N N Y 2467 AnyData,DBM,CSV Y N N N Y Y* Y 2468 SQLite 3.3 N N N N Y N N 2469 2470 * Works only because Example 0 works. 2471 2472 DBI provides a sample perl script that will test the examples above 2473 on your database engine and tell you which ones work. It is located 2474 in the F<ex/> subdirectory of the DBI source distribution, or here: 2475 L<http://svn.perl.org/modules/dbi/trunk/ex/perl_dbi_nulls_test.pl> 2476 Please use the script to help us fill-in and maintain this table. 2477 2478 B<Performance> 2479 2480 Without using placeholders, the insert statement shown previously would have to 2481 contain the literal values to be inserted and would have to be 2482 re-prepared and re-executed for each row. With placeholders, the insert 2483 statement only needs to be prepared once. The bind values for each row 2484 can be given to the C<execute> method each time it's called. By avoiding 2485 the need to re-prepare the statement for each row, the application 2486 typically runs many times faster. Here's an example: 2487 2488 my $sth = $dbh->prepare(q{ 2489 INSERT INTO sales (product_code, qty, price) VALUES (?, ?, ?) 2490 }) or die $dbh->errstr; 2491 while (<>) { 2492 chomp; 2493 my ($product_code, $qty, $price) = split /,/; 2494 $sth->execute($product_code, $qty, $price) or die $dbh->errstr; 2495 } 2496 $dbh->commit or die $dbh->errstr; 2497 2498 See L</execute> and L</bind_param> for more details. 2499 2500 The C<q{...}> style quoting used in this example avoids clashing with 2501 quotes that may be used in the SQL statement. Use the double-quote like 2502 C<qq{...}> operator if you want to interpolate variables into the string. 2503 See L<perlop/"Quote and Quote-like Operators"> for more details. 2504 2505 See also the L</bind_columns> method, which is used to associate Perl 2506 variables with the output columns of a C<SELECT> statement. 2507 2508 =head1 THE DBI PACKAGE AND CLASS 2509 2510 In this section, we cover the DBI class methods, utility functions, 2511 and the dynamic attributes associated with generic DBI handles. 2512 2513 =head2 DBI Constants 2514 2515 Constants representing the values of the SQL standard types can be 2516 imported individually by name, or all together by importing the 2517 special C<:sql_types> tag. 2518 2519 The names and values of all the defined SQL standard types can be 2520 produced like this: 2521 2522 foreach (@{ $DBI::EXPORT_TAGS{sql_types} }) { 2523 printf "%s=%d\n", $_, &{"DBI::$_"}; 2524 } 2525 2526 These constants are defined by SQL/CLI, ODBC or both. 2527 C<SQL_BIGINT> is (currently) omitted, because SQL/CLI and ODBC provide 2528 conflicting codes. 2529 2530 See the L</type_info>, L</type_info_all>, and L</bind_param> methods 2531 for possible uses. 2532 2533 Note that just because the DBI defines a named constant for a given 2534 data type doesn't mean that drivers will support that data type. 2535 2536 2537 =head2 DBI Class Methods 2538 2539 The following methods are provided by the DBI class: 2540 2541 =head3 C<parse_dsn> 2542 2543 ($scheme, $driver, $attr_string, $attr_hash, $driver_dsn) = DBI->parse_dsn($dsn) 2544 or die "Can't parse DBI DSN '$dsn'"; 2545 2546 Breaks apart a DBI Data Source Name (DSN) and returns the individual 2547 parts. If $dsn doesn't contain a valid DSN then parse_dsn() returns 2548 an empty list. 2549 2550 $scheme is the first part of the DSN and is currently always 'dbi'. 2551 $driver is the driver name, possibly defaulted to $ENV{DBI_DRIVER}, 2552 and may be undefined. $attr_string is the contents of the optional attribute 2553 string, which may be undefined. If $attr_string is not empty then $attr_hash 2554 is a reference to a hash containing the parsed attribute names and values. 2555 $driver_dsn is the last part of the DBI DSN string. For example: 2556 2557 ($scheme, $driver, $attr_string, $attr_hash, $driver_dsn) 2558 = DBI->parse_dsn("DBI:MyDriver(RaiseError=>1):db=test;port=42"); 2559 $scheme = 'dbi'; 2560 $driver = 'MyDriver'; 2561 $attr_string = 'RaiseError=>1'; 2562 $attr_hash = { 'RaiseError' => '1' }; 2563 $driver_dsn = 'db=test;port=42'; 2564 2565 The parse_dsn() method was added in DBI 1.43. 2566 2567 =head3 C<connect> 2568 2569 $dbh = DBI->connect($data_source, $username, $password) 2570 or die $DBI::errstr; 2571 $dbh = DBI->connect($data_source, $username, $password, \%attr) 2572 or die $DBI::errstr; 2573 2574 Establishes a database connection, or session, to the requested C<$data_source>. 2575 Returns a database handle object if the connection succeeds. Use 2576 C<$dbh-E<gt>disconnect> to terminate the connection. 2577 2578 If the connect fails (see below), it returns C<undef> and sets both C<$DBI::err> 2579 and C<$DBI::errstr>. (It does I<not> explicitly set C<$!>.) You should generally 2580 test the return status of C<connect> and C<print $DBI::errstr> if it has failed. 2581 2582 Multiple simultaneous connections to multiple databases through multiple 2583 drivers can be made via the DBI. Simply make one C<connect> call for each 2584 database and keep a copy of each returned database handle. 2585 2586 The C<$data_source> value must begin with "C<dbi:>I<driver_name>C<:>". 2587 The I<driver_name> specifies the driver that will be used to make the 2588 connection. (Letter case is significant.) 2589 2590 As a convenience, if the C<$data_source> parameter is undefined or empty, 2591 the DBI will substitute the value of the environment variable C<DBI_DSN>. 2592 If just the I<driver_name> part is empty (i.e., the C<$data_source> 2593 prefix is "C<dbi::>"), the environment variable C<DBI_DRIVER> is 2594 used. If neither variable is set, then C<connect> dies. 2595 2596 Examples of C<$data_source> values are: 2597 2598 dbi:DriverName:database_name 2599 dbi:DriverName:database_name@hostname:port 2600 dbi:DriverName:database=database_name;host=hostname;port=port 2601 2602 There is I<no standard> for the text following the driver name. Each 2603 driver is free to use whatever syntax it wants. The only requirement the 2604 DBI makes is that all the information is supplied in a single string. 2605 You must consult the documentation for the drivers you are using for a 2606 description of the syntax they require. 2607 2608 It is recommended that drivers support the ODBC style, shown in the 2609 last example above. It is also recommended that that they support the 2610 three common names 'C<host>', 'C<port>', and 'C<database>' (plus 'C<db>' 2611 as an alias for C<database>). This simplifies automatic construction 2612 of basic DSNs: C<"dbi:$driver:database=$db;host=$host;port=$port">. 2613 Drivers should aim to 'do something reasonable' when given a DSN 2614 in this form, but if any part is meaningless for that driver (such 2615 as 'port' for Informix) it should generate an error if that part 2616 is not empty. 2617 2618 If the environment variable C<DBI_AUTOPROXY> is defined (and the 2619 driver in C<$data_source> is not "C<Proxy>") then the connect request 2620 will automatically be changed to: 2621 2622 $ENV{DBI_AUTOPROXY};dsn=$data_source 2623 2624 C<DBI_AUTOPROXY> is typically set as "C<dbi:Proxy:hostname=...;port=...>". 2625 If $ENV{DBI_AUTOPROXY} doesn't begin with 'C<dbi:>' then "dbi:Proxy:" 2626 will be prepended to it first. See the DBD::Proxy documentation 2627 for more details. 2628 2629 If C<$username> or C<$password> are undefined (rather than just empty), 2630 then the DBI will substitute the values of the C<DBI_USER> and C<DBI_PASS> 2631 environment variables, respectively. The DBI will warn if the 2632 environment variables are not defined. However, the everyday use 2633 of these environment variables is not recommended for security 2634 reasons. The mechanism is primarily intended to simplify testing. 2635 See below for alternative way to specify the username and password. 2636 2637 C<DBI-E<gt>connect> automatically installs the driver if it has not been 2638 installed yet. Driver installation either returns a valid driver 2639 handle, or it I<dies> with an error message that includes the string 2640 "C<install_driver>" and the underlying problem. So C<DBI-E<gt>connect> 2641 will die 2642 on a driver installation failure and will only return C<undef> on a 2643 connect failure, in which case C<$DBI::errstr> will hold the error message. 2644 Use C<eval { ... }> if you need to catch the "C<install_driver>" error. 2645 2646 The C<$data_source> argument (with the "C<dbi:...:>" prefix removed) and the 2647 C<$username> and C<$password> arguments are then passed to the driver for 2648 processing. The DBI does not define any interpretation for the 2649 contents of these fields. The driver is free to interpret the 2650 C<$data_source>, C<$username>, and C<$password> fields in any way, and supply 2651 whatever defaults are appropriate for the engine being accessed. 2652 (Oracle, for example, uses the ORACLE_SID and TWO_TASK environment 2653 variables if no C<$data_source> is specified.) 2654 2655 The C<AutoCommit> and C<PrintError> attributes for each connection 2656 default to "on". (See L</AutoCommit> and L</PrintError> for more information.) 2657 However, it is strongly recommended that you explicitly define C<AutoCommit> 2658 rather than rely on the default. The C<PrintWarn> attribute defaults to 2659 on if $^W is true, i.e., perl is running with warnings enabled. 2660 2661 The C<\%attr> parameter can be used to alter the default settings of 2662 C<PrintError>, C<RaiseError>, C<AutoCommit>, and other attributes. For example: 2663 2664 $dbh = DBI->connect($data_source, $user, $pass, { 2665 PrintError => 0, 2666 AutoCommit => 0 2667 }); 2668 2669 The username and password can also be specified using the attributes 2670 C<Username> and C<Password>, in which case they take precedence 2671 over the C<$username> and C<$password> parameters. 2672 2673 You can also define connection attribute values within the C<$data_source> 2674 parameter. For example: 2675 2676 dbi:DriverName(PrintWarn=>1,PrintError=>0,Taint=>1):... 2677 2678 Individual attributes values specified in this way take precedence over 2679 any conflicting values specified via the C<\%attr> parameter to C<connect>. 2680 2681 The C<dbi_connect_method> attribute can be used to specify which driver 2682 method should be called to establish the connection. The only useful 2683 values are 'connect', 'connect_cached', or some specialized case like 2684 'Apache::DBI::connect' (which is automatically the default when running 2685 within Apache). 2686 2687 Where possible, each session (C<$dbh>) is independent from the transactions 2688 in other sessions. This is useful when you need to hold cursors open 2689 across transactions--for example, if you use one session for your long lifespan 2690 cursors (typically read-only) and another for your short update 2691 transactions. 2692 2693 For compatibility with old DBI scripts, the driver can be specified by 2694 passing its name as the fourth argument to C<connect> (instead of C<\%attr>): 2695 2696 $dbh = DBI->connect($data_source, $user, $pass, $driver); 2697 2698 In this "old-style" form of C<connect>, the C<$data_source> should not start 2699 with "C<dbi:driver_name:>". (If it does, the embedded driver_name 2700 will be ignored). Also note that in this older form of C<connect>, 2701 the C<$dbh-E<gt>{AutoCommit}> attribute is I<undefined>, the 2702 C<$dbh-E<gt>{PrintError}> attribute is off, and the old C<DBI_DBNAME> 2703 environment variable is 2704 checked if C<DBI_DSN> is not defined. Beware that this "old-style" 2705 C<connect> will soon be withdrawn in a future version of DBI. 2706 2707 =head3 C<connect_cached> 2708 2709 $dbh = DBI->connect_cached($data_source, $username, $password) 2710 or die $DBI::errstr; 2711 $dbh = DBI->connect_cached($data_source, $username, $password, \%attr) 2712 or die $DBI::errstr; 2713 2714 C<connect_cached> is like L</connect>, except that the database handle 2715 returned is also 2716 stored in a hash associated with the given parameters. If another call 2717 is made to C<connect_cached> with the same parameter values, then the 2718 corresponding cached C<$dbh> will be returned if it is still valid. 2719 The cached database handle is replaced with a new connection if it 2720 has been disconnected or if the C<ping> method fails. 2721 2722 That the behaviour of this method differs in several respects from the 2723 behaviour of persistent connections implemented by Apache::DBI. 2724 However, if Apache::DBI is loaded then C<connect_cached> will use it. 2725 2726 Caching connections can be useful in some applications, but it can 2727 also cause problems, such as too many connections, and so should 2728 be used with care. In particular, avoid changing the attributes of 2729 a database handle created via connect_cached() because it will affect 2730 other code that may be using the same handle. 2731 2732 Where multiple separate parts of a program are using connect_cached() 2733 to connect to the same database with the same (initial) attributes 2734 it is a good idea to add a private attribute to the connect_cached() 2735 call to effectively limit the scope of the caching. For example: 2736 2737 DBI->connect_cached(..., { private_foo_cachekey => "Bar", ... }); 2738 2739 Handles returned from that connect_cached() call will only be returned 2740 by other connect_cached() call elsewhere in the code if those other 2741 calls also pass in the same attribute values, including the private one. 2742 (I've used C<private_foo_cachekey> here as an example, you can use 2743 any attribute name with a C<private_> prefix.) 2744 2745 Taking that one step further, you can limit a particular connect_cached() 2746 call to return handles unique to that one place in the code by setting the 2747 private attribute to a unique value for that place: 2748 2749 DBI->connect_cached(..., { private_foo_cachekey => __FILE__.__LINE__, ... }); 2750 2751 By using a private attribute you still get connection caching for 2752 the individual calls to connect_cached() but, by making separate 2753 database conections for separate parts of the code, the database 2754 handles are isolated from any attribute changes made to other handles. 2755 2756 The cache can be accessed (and cleared) via the L</CachedKids> attribute: 2757 2758 my $CachedKids_hashref = $dbh->{Driver}->{CachedKids}; 2759 %$CachedKids_hashref = () if $CachedKids_hashref; 2760 2761 2762 =head3 C<available_drivers> 2763 2764 @ary = DBI->available_drivers; 2765 @ary = DBI->available_drivers($quiet); 2766 2767 Returns a list of all available drivers by searching for C<DBD::*> modules 2768 through the directories in C<@INC>. By default, a warning is given if 2769 some drivers are hidden by others of the same name in earlier 2770 directories. Passing a true value for C<$quiet> will inhibit the warning. 2771 2772 =head3 C<installed_drivers> 2773 2774 %drivers = DBI->installed_drivers(); 2775 2776 Returns a list of driver name and driver handle pairs for all drivers 2777 'installed' (loaded) into the current process. The driver name does not 2778 include the 'DBD::' prefix. 2779 2780 To get a list of all drivers available in your perl instalation you can use 2781 L</available_drivers>. 2782 2783 Added in DBI 1.49. 2784 2785 =head3 C<installed_versions> 2786 2787 DBI->installed_versions; 2788 @ary = DBI->installed_versions; 2789 %hash = DBI->installed_versions; 2790 2791 Calls available_drivers() and attempts to load each of them in turn 2792 using install_driver(). For each load that succeeds the driver 2793 name and version number are added to a hash. When running under 2794 L<DBI::PurePerl> drivers which appear not be pure-perl are ignored. 2795 2796 When called in array context the list of successfully loaded drivers 2797 is returned (without the 'DBD::' prefix). 2798 2799 When called in scalar context a reference to the hash is returned 2800 and the hash will also contain other entries for the C<DBI> version, 2801 C<OS> name, etc. 2802 2803 When called in a void context the installed_versions() method will 2804 print out a formatted list of the hash contents, one per line. 2805 2806 Due to the potentially high memory cost and unknown risks of loading 2807 in an unknown number of drivers that just happen to be installed 2808 on the system, this method is not recommended for general use. 2809 Use available_drivers() instead. 2810 2811 The installed_versions() method is primarily intended as a quick 2812 way to see from the command line what's installed. For example: 2813 2814 perl -MDBI -e 'DBI->installed_versions' 2815 2816 The installed_versions() method was added in DBI 1.38. 2817 2818 =head3 C<data_sources> 2819 2820 @ary = DBI->data_sources($driver); 2821 @ary = DBI->data_sources($driver, \%attr); 2822 2823 Returns a list of data sources (databases) available via the named 2824 driver. If C<$driver> is empty or C<undef>, then the value of the 2825 C<DBI_DRIVER> environment variable is used. 2826 2827 The driver will be loaded if it hasn't been already. Note that if the 2828 driver loading fails then data_sources() I<dies> with an error message 2829 that includes the string "C<install_driver>" and the underlying problem. 2830 2831 Data sources are returned in a form suitable for passing to the 2832 L</connect> method (that is, they will include the "C<dbi:$driver:>" prefix). 2833 2834 Note that many drivers have no way of knowing what data sources might 2835 be available for it. These drivers return an empty or incomplete list 2836 or may require driver-specific attributes. 2837 2838 There is also a data_sources() method defined for database handles. 2839 2840 2841 =head3 C<trace> 2842 2843 DBI->trace($trace_setting) 2844 DBI->trace($trace_setting, $trace_filename) 2845 DBI->trace($trace_setting, $trace_filehandle) 2846 $trace_setting = DBI->trace; 2847 2848 The C<DBI-E<gt>trace> method sets the I<global default> trace 2849 settings and returns the I<previous> trace settings. It can also 2850 be used to change where the trace output is sent. 2851 2852 There's a similar method, C<$h-E<gt>trace>, which sets the trace 2853 settings for the specific handle it's called on. 2854 2855 See the L</TRACING> section for full details about the DBI's powerful 2856 tracing facilities. 2857 2858 2859 2860 =head2 DBI Utility Functions 2861 2862 In addition to the DBI methods listed in the previous section, 2863 the DBI package also provides several utility functions. 2864 2865 These can be imported into your code by listing them in 2866 the C<use> statement. For example: 2867 2868 use DBI qw(neat data_diff); 2869 2870 Alternatively, all these utility functions (except hash) can be 2871 imported using the C<:utils> import tag. For example: 2872 2873 use DBI qw(:utils); 2874 2875 =head3 C<data_string_desc> 2876 2877 $description = data_string_desc($string); 2878 2879 Returns an informal description of the string. For example: 2880 2881 UTF8 off, ASCII, 42 characters 42 bytes 2882 UTF8 off, non-ASCII, 42 characters 42 bytes 2883 UTF8 on, non-ASCII, 4 characters 6 bytes 2884 UTF8 on but INVALID encoding, non-ASCII, 4 characters 6 bytes 2885 UTF8 off, undef 2886 2887 The initial C<UTF8> on/off refers to Perl's internal SvUTF8 flag. 2888 If $string has the SvUTF8 flag set but the sequence of bytes it 2889 contains are not a valid UTF-8 encoding then data_string_desc() 2890 will report C<UTF8 on but INVALID encoding>. 2891 2892 The C<ASCII> vs C<non-ASCII> portion shows C<ASCII> if I<all> the 2893 characters in the string are ASCII (have code points <= 127). 2894 2895 The data_string_desc() function was added in DBI 1.46. 2896 2897 =head3 C<data_string_diff> 2898 2899 $diff = data_string_diff($a, $b); 2900 2901 Returns an informal description of the first character difference 2902 between the strings. If both $a and $b contain the same sequence 2903 of characters then data_string_diff() returns an empty string. 2904 For example: 2905 2906 Params a & b Result 2907 ------------ ------ 2908 'aaa', 'aaa' '' 2909 'aaa', 'abc' 'Strings differ at index 2: a[2]=a, b[2]=b' 2910 'aaa', undef 'String b is undef, string a has 3 characters' 2911 'aaa', 'aa' 'String b truncated after 2 characters' 2912 2913 Unicode characters are reported in C<\x{XXXX}> format. Unicode 2914 code points in the range U+0800 to U+08FF are unassigned and most 2915 likely to occur due to double-encoding. Characters in this range 2916 are reported as C<\x{08XX}='C'> where C<C> is the corresponding 2917 latin-1 character. 2918 2919 The data_string_diff() function only considers logical I<characters> 2920 and not the underlying encoding. See L</data_diff> for an alternative. 2921 2922 The data_string_diff() function was added in DBI 1.46. 2923 2924 =head3 C<data_diff> 2925 2926 $diff = data_diff($a, $b); 2927 $diff = data_diff($a, $b, $logical); 2928 2929 Returns an informal description of the difference between two strings. 2930 It calls L</data_string_desc> and L</data_string_diff> 2931 and returns the combined results as a multi-line string. 2932 2933 For example, C<data_diff("abc", "ab\x{263a}")> will return: 2934 2935 a: UTF8 off, ASCII, 3 characters 3 bytes 2936 b: UTF8 on, non-ASCII, 3 characters 5 bytes 2937 Strings differ at index 2: a[2]=c, b[2]=\x{263A} 2938 2939 If $a and $b are identical in both the characters they contain I<and> 2940 their physical encoding then data_diff() returns an empty string. 2941 If $logical is true then physical encoding differences are ignored 2942 (but are still reported if there is a difference in the characters). 2943 2944 The data_diff() function was added in DBI 1.46. 2945 2946 =head3 C<neat> 2947 2948 $str = neat($value); 2949 $str = neat($value, $maxlen); 2950 2951 Return a string containing a neat (and tidy) representation of the 2952 supplied value. 2953 2954 Strings will be quoted, although internal quotes will I<not> be escaped. 2955 Values known to be numeric will be unquoted. Undefined (NULL) values 2956 will be shown as C<undef> (without quotes). 2957 2958 If the string is flagged internally as utf8 then double quotes will 2959 be used, otherwise single quotes are used and unprintable characters 2960 will be replaced by dot (.). 2961 2962 For result strings longer than C<$maxlen> the result string will be 2963 truncated to C<$maxlen-4> and "C<...'>" will be appended. If C<$maxlen> is 0 2964 or C<undef>, it defaults to C<$DBI::neat_maxlen> which, in turn, defaults to 400. 2965 2966 This function is designed to format values for human consumption. 2967 It is used internally by the DBI for L</trace> output. It should 2968 typically I<not> be used for formatting values for database use. 2969 (See also L</quote>.) 2970 2971 =head3 C<neat_list> 2972 2973 $str = neat_list(\@listref, $maxlen, $field_sep); 2974 2975 Calls C<neat> on each element of the list and returns a string 2976 containing the results joined with C<$field_sep>. C<$field_sep> defaults 2977 to C<", ">. 2978 2979 =head3 C<looks_like_number> 2980 2981 @bool = looks_like_number(@array); 2982 2983 Returns true for each element that looks like a number. 2984 Returns false for each element that does not look like a number. 2985 Returns C<undef> for each element that is undefined or empty. 2986 2987 =head3 C<hash> 2988 2989 $hash_value = DBI::hash($buffer, $type); 2990 2991 Return a 32-bit integer 'hash' value corresponding to the contents of $buffer. 2992 The $type parameter selects which kind of hash algorithm should be used. 2993 2994 For the technically curious, type 0 (which is the default if $type 2995 isn't specified) is based on the Perl 5.1 hash except that the value 2996 is forced to be negative (for obscure historical reasons). 2997 Type 1 is the better "Fowler / Noll / Vo" (FNV) hash. See 2998 L<http://www.isthe.com/chongo/tech/comp/fnv/> for more information. 2999 Both types are implemented in C and are very fast. 3000 3001 This function doesn't have much to do with databases, except that 3002 it can be handy to store hash values in a database. 3003 3004 3005 =head2 DBI Dynamic Attributes 3006 3007 Dynamic attributes are always associated with the I<last handle used> 3008 (that handle is represented by C<$h> in the descriptions below). 3009 3010 Where an attribute is equivalent to a method call, then refer to 3011 the method call for all related documentation. 3012 3013 Warning: these attributes are provided as a convenience but they 3014 do have limitations. Specifically, they have a short lifespan: 3015 because they are associated with 3016 the last handle used, they should only be used I<immediately> after 3017 calling the method that "sets" them. 3018 If in any doubt, use the corresponding method call. 3019 3020 =head3 C<$DBI::err> 3021 3022 Equivalent to C<$h-E<gt>err>. 3023 3024 =head3 C<$DBI::errstr> 3025 3026 Equivalent to C<$h-E<gt>errstr>. 3027 3028 =head3 C<$DBI::state> 3029 3030 Equivalent to C<$h-E<gt>state>. 3031 3032 =head3 C<$DBI::rows> 3033 3034 Equivalent to C<$h-E<gt>rows>. Please refer to the documentation 3035 for the L</rows> method. 3036 3037 =head3 C<$DBI::lasth> 3038 3039 Returns the DBI object handle used for the most recent DBI method call. 3040 If the last DBI method call was a DESTROY then $DBI::lasth will return 3041 the handle of the parent of the destroyed handle, if there is one. 3042 3043 3044 =head1 METHODS COMMON TO ALL HANDLES 3045 3046 The following methods can be used by all types of DBI handles. 3047 3048 =head3 C<err> 3049 3050 $rv = $h->err; 3051 3052 Returns the I<native> database engine error code from the last driver 3053 method called. The code is typically an integer but you should not 3054 assume that. 3055 3056 The DBI resets $h->err to undef before almost all DBI method calls, so the 3057 value only has a short lifespan. Also, for most drivers, the statement 3058 handles share the same error variable as the parent database handle, 3059 so calling a method on one handle may reset the error on the 3060 related handles. 3061 3062 (Methods which don't reset err before being called include err() and errstr(), 3063 obviously, state(), rows(), func(), trace(), trace_msg(), ping(), and the 3064 tied hash attribute FETCH() and STORE() methods.) 3065 3066 If you need to test for specific error conditions I<and> have your program be 3067 portable to different database engines, then you'll need to determine what the 3068 corresponding error codes are for all those engines and test for all of them. 3069 3070 The DBI uses the value of $DBI::stderr as the C<err> value for internal errors. 3071 Drivers should also do likewise. The default value for $DBI::stderr is 2000000000. 3072 3073 A driver may return C<0> from err() to indicate a warning condition 3074 after a method call. Similarly, a driver may return an empty string 3075 to indicate a 'success with information' condition. In both these 3076 cases the value is false but not undef. The errstr() and state() 3077 methods may be used to retrieve extra information in these cases. 3078 3079 See L</set_err> for more information. 3080 3081 =head3 C<errstr> 3082 3083 $str = $h->errstr; 3084 3085 Returns the native database engine error message from the last DBI 3086 method called. This has the same lifespan issues as the L</err> method 3087 described above. 3088 3089 The returned string may contain multiple messages separated by 3090 newline characters. 3091 3092 The errstr() method should not be used to test for errors, use err() 3093 for that, because drivers may return 'success with information' or 3094 warning messages via errstr() for methods that have not 'failed'. 3095 3096 See L</set_err> for more information. 3097 3098 =head3 C<state> 3099 3100 $str = $h->state; 3101 3102 Returns a state code in the standard SQLSTATE five character format. 3103 Note that the specific success code C<00000> is translated to any empty string 3104 (false). If the driver does not support SQLSTATE (and most don't), 3105 then state() will return C<S1000> (General Error) for all errors. 3106 3107 The driver is free to return any value via C<state>, e.g., warning 3108 codes, even if it has not declared an error by returning a true value 3109 via the L</err> method described above. 3110 3111 The state() method should not be used to test for errors, use err() 3112 for that, because drivers may return a 'success with information' or 3113 warning state code via state() for methods that have not 'failed'. 3114 3115 =head3 C<set_err> 3116 3117 $rv = $h->set_err($err, $errstr); 3118 $rv = $h->set_err($err, $errstr, $state); 3119 $rv = $h->set_err($err, $errstr, $state, $method); 3120 $rv = $h->set_err($err, $errstr, $state, $method, $rv); 3121 3122 Set the C<err>, C<errstr>, and C<state> values for the handle. 3123 This method is typically only used by DBI drivers and DBI subclasses. 3124 3125 If the L</HandleSetErr> attribute holds a reference to a subroutine 3126 it is called first. The subroutine can alter the $err, $errstr, $state, 3127 and $method values. See L</HandleSetErr> for full details. 3128 If the subroutine returns a true value then the handle C<err>, 3129 C<errstr>, and C<state> values are not altered and set_err() returns 3130 an empty list (it normally returns $rv which defaults to undef, see below). 3131 3132 Setting C<err> to a I<true> value indicates an error and will trigger 3133 the normal DBI error handling mechanisms, such as C<RaiseError> and 3134 C<HandleError>, if they are enabled, when execution returns from 3135 the DBI back to the application. 3136 3137 Setting C<err> to C<""> indicates an 'information' state, and setting 3138 it to C<"0"> indicates a 'warning' state. Setting C<err> to C<undef> 3139 also sets C<errstr> to undef, and C<state> to C<"">, irrespective 3140 of the values of the $errstr and $state parameters. 3141 3142 The $method parameter provides an alternate method name for the 3143 C<RaiseError>/C<PrintError>/C<PrintWarn> error string instead of 3144 the fairly unhelpful 'C<set_err>'. 3145 3146 The C<set_err> method normally returns undef. The $rv parameter 3147 provides an alternate return value. 3148 3149 Some special rules apply if the C<err> or C<errstr> 3150 values for the handle are I<already> set... 3151 3152 If C<errstr> is true then: "C< [err was %s now %s]>" is appended if $err is 3153 true and C<err> is already true and the new err value differs from the original 3154 one. Similarly "C< [state was %s now %s]>" is appended if $state is true and C<state> is 3155 already true and the new state value differs from the original one. Finally 3156 "C<\n>" and the new $errstr are appended if $errstr differs from the existing 3157 errstr value. Obviously the C<%s>'s above are replaced by the corresponding values. 3158 3159 The handle C<err> value is set to $err if: $err is true; or handle 3160 C<err> value is undef; or $err is defined and the length is greater 3161 than the handle C<err> length. The effect is that an 'information' 3162 state only overrides undef; a 'warning' overrides undef or 'information', 3163 and an 'error' state overrides anything. 3164 3165 The handle C<state> value is set to $state if $state is true and 3166 the handle C<err> value was set (by the rules above). 3167 3168 Support for warning and information states was added in DBI 1.41. 3169 3170 =head3 C<trace> 3171 3172 $h->trace($trace_settings); 3173 $h->trace($trace_settings, $trace_filename); 3174 $trace_settings = $h->trace; 3175 3176 The trace() method is used to alter the trace settings for a handle 3177 (and any future children of that handle). It can also be used to 3178 change where the trace output is sent. 3179 3180 There's a similar method, C<DBI-E<gt>trace>, which sets the global 3181 default trace settings. 3182 3183 See the L</TRACING> section for full details about the DBI's powerful 3184 tracing facilities. 3185 3186 =head3 C<trace_msg> 3187 3188 $h->trace_msg($message_text); 3189 $h->trace_msg($message_text, $min_level); 3190 3191 Writes C<$message_text> to the trace file if the trace level is 3192 greater than or equal to $min_level (which defaults to 1). 3193 Can also be called as C<DBI-E<gt>trace_msg($msg)>. 3194 3195 See L</TRACING> for more details. 3196 3197 =head3 C<func> 3198 3199 $h->func(@func_arguments, $func_name) or die ...; 3200 3201 The C<func> method can be used to call private non-standard and 3202 non-portable methods implemented by the driver. Note that the function 3203 name is given as the I<last> argument. 3204 3205 It's also important to note that the func() method does not clear 3206 a previous error ($DBI::err etc.) and it does not trigger automatic 3207 error detection (RaiseError etc.) so you must check the return 3208 status and/or $h->err to detect errors. 3209 3210 (This method is not directly related to calling stored procedures. 3211 Calling stored procedures is currently not defined by the DBI. 3212 Some drivers, such as DBD::Oracle, support it in non-portable ways. 3213 See driver documentation for more details.) 3214 3215 See also install_method() in L<DBI::DBD> for how you can avoid needing to 3216 use func() and gain direct access to driver-private methods. 3217 3218 =head3 C<can> 3219 3220 $is_implemented = $h->can($method_name); 3221 3222 Returns true if $method_name is implemented by the driver or a 3223 default method is provided by the DBI. 3224 It returns false where a driver hasn't implemented a method and the 3225 default method is provided by the DBI is just an empty stub. 3226 3227 =head3 C<parse_trace_flags> 3228 3229 $trace_settings_integer = $h->parse_trace_flags($trace_settings); 3230 3231 Parses a string containing trace settings and returns the corresponding 3232 integer value used internally by the DBI and drivers. 3233 3234 The $trace_settings argument is a string containing a trace level 3235 between 0 and 15 and/or trace flag names separated by vertical bar 3236 ("C<|>") or comma ("C<,>") characters. For example: C<"SQL|3|foo">. 3237 3238 It uses the parse_trace_flag() method, described below, to process 3239 the individual trage flag names. 3240 3241 The parse_trace_flags() method was added in DBI 1.42. 3242 3243 =head3 C<parse_trace_flag> 3244 3245 $bit_flag = $h->parse_trace_flag($trace_flag_name); 3246 3247 Returns the bit flag corresponding to the trace flag name in 3248 $trace_flag_name. Drivers are expected to override this method and 3249 check if $trace_flag_name is a driver specific trace flags and, if 3250 not, then call the DBIs default parse_trace_flag(). 3251 3252 The parse_trace_flag() method was added in DBI 1.42. 3253 3254 =head3 C<private_attribute_info> 3255 3256 $hash_ref = $h->private_attribute_info(); 3257 3258 Returns a reference to a hash whose keys are the names of driver-private 3259 attributes available for the kind of handle (driver, database, statement) 3260 that the method was called on. 3261 3262 For example, the return value when called with a DBD::Sybase $dbh could look like this: 3263 3264 { 3265 syb_dynamic_supported => undef, 3266 syb_oc_version => undef, 3267 syb_server_version => undef, 3268 syb_server_version_string => undef, 3269 } 3270 3271 and when called with a DBD::Sybase $sth they could look like this: 3272 3273 { 3274 syb_types => undef, 3275 syb_proc_status => undef, 3276 syb_result_type => undef, 3277 } 3278 3279 The values should be undef. Meanings may be assigned to particular values in future. 3280 3281 =head3 C<swap_inner_handle> 3282 3283 $rc = $h1->swap_inner_handle( $h2 ); 3284 $rc = $h1->swap_inner_handle( $h2, $allow_reparent ); 3285 3286 Brain transplants for handles. You don't need to know about this 3287 unless you want to become a handle surgeon. 3288 3289 A DBI handle is a reference to a tied hash. A tied hash has an 3290 I<inner> hash that actually holds the contents. The swap_inner_handle() 3291 method swaps the inner hashes between two handles. The $h1 and $h2 3292 handles still point to the same tied hashes, but what those hashes 3293 are tied to has been swapped. In effect $h1 I<becomes> $h2 and 3294 vice-versa. This is powerful stuff, expect problems. Use with care. 3295 3296 As a small safety measure, the two handles, $h1 and $h2, have to 3297 share the same parent unless $allow_reparent is true. 3298 3299 The swap_inner_handle() method was added in DBI 1.44. 3300 3301 Here's a quick kind of 'diagram' as a worked example to help think about what's 3302 happening: 3303 3304 Original state: 3305 dbh1o -> dbh1i 3306 sthAo -> sthAi(dbh1i) 3307 dbh2o -> dbh2i 3308 3309 swap_inner_handle dbh1o with dbh2o: 3310 dbh2o -> dbh1i 3311 sthAo -> sthAi(dbh1i) 3312 dbh1o -> dbh2i 3313 3314 create new sth from dbh1o: 3315 dbh2o -> dbh1i 3316 sthAo -> sthAi(dbh1i) 3317 dbh1o -> dbh2i 3318 sthBo -> sthBi(dbh2i) 3319 3320 swap_inner_handle sthAo with sthBo: 3321 dbh2o -> dbh1i 3322 sthBo -> sthAi(dbh1i) 3323 dbh1o -> dbh2i 3324 sthAo -> sthBi(dbh2i) 3325 3326 3327 =head1 ATTRIBUTES COMMON TO ALL HANDLES 3328 3329 These attributes are common to all types of DBI handles. 3330 3331 Some attributes are inherited by child handles. That is, the value 3332 of an inherited attribute in a newly created statement handle is the 3333 same as the value in the parent database handle. Changes to attributes 3334 in the new statement handle do not affect the parent database handle 3335 and changes to the database handle do not affect existing statement 3336 handles, only future ones. 3337 3338 Attempting to set or get the value of an unknown attribute generates a warning, 3339 except for private driver specific attributes (which all have names 3340 starting with a lowercase letter). 3341 3342 Example: 3343 3344 $h->{AttributeName} = ...; # set/write 3345 ... = $h->{AttributeName}; # get/read 3346 3347 =head3 C<Warn> (boolean, inherited) 3348 3349 The C<Warn> attribute enables useful warnings for certain bad 3350 practices. It is enabled by default and should only be disabled in 3351 rare circumstances. Since warnings are generated using the Perl 3352 C<warn> function, they can be intercepted using the Perl C<$SIG{__WARN__}> 3353 hook. 3354 3355 The C<Warn> attribute is not related to the C<PrintWarn> attribute. 3356 3357 =head3 C<Active> (boolean, read-only) 3358 3359 The C<Active> attribute is true if the handle object is "active". This is rarely used in 3360 applications. The exact meaning of active is somewhat vague at the 3361 moment. For a database handle it typically means that the handle is 3362 connected to a database (C<$dbh-E<gt>disconnect> sets C<Active> off). For 3363 a statement handle it typically means that the handle is a C<SELECT> 3364 that may have more data to fetch. (Fetching all the data or calling C<$sth-E<gt>finish> 3365 sets C<Active> off.) 3366 3367 =head3 C<Executed> (boolean) 3368 3369 The C<Executed> attribute is true if the handle object has been "executed". 3370 Currently only the $dbh do() method and the $sth execute(), execute_array(), 3371 and execute_for_fetch() methods set the C<Executed> attribute. 3372 3373 When it's set on a handle it is also set on the parent handle at the 3374 same time. So calling execute() on a $sth also sets the C<Executed> 3375 attribute on the parent $dbh. 3376 3377 The C<Executed> attribute for a database handle is cleared by the commit() and 3378 rollback() methods (even if they fail). The C<Executed> attribute of a 3379 statement handle is not cleared by the DBI under any circumstances and so acts 3380 as a permanent record of whether the statement handle was ever used. 3381 3382 The C<Executed> attribute was added in DBI 1.41. 3383 3384 =head3 C<Kids> (integer, read-only) 3385 3386 For a driver handle, C<Kids> is the number of currently existing database 3387 handles that were created from that driver handle. For a database 3388 handle, C<Kids> is the number of currently existing statement handles that 3389 were created from that database handle. 3390 For a statement handle, the value is zero. 3391 3392 =head3 C<ActiveKids> (integer, read-only) 3393 3394 Like C<Kids>, but only counting those that are C<Active> (as above). 3395 3396 =head3 C<CachedKids> (hash ref) 3397 3398 For a database handle, C<CachedKids> returns a reference to the cache (hash) of 3399 statement handles created by the L</prepare_cached> method. For a 3400 driver handle, returns a reference to the cache (hash) of 3401 database handles created by the L</connect_cached> method. 3402 3403 =head3 C<Type> (scalar, read-only) 3404 3405 The C<Type> attribute identifies the type of a DBI handle. Returns 3406 "dr" for driver handles, "db" for database handles and "st" for 3407 statement handles. 3408 3409 =head3 C<ChildHandles> (array ref) 3410 3411 The ChildHandles attribute contains a reference to an array of all the 3412 handles created by this handle which are still accessible. The 3413 contents of the array are weak-refs and will become undef when the 3414 handle goes out of scope. 3415 3416 C<ChildHandles> returns undef if your perl version does not support weak 3417 references (check the L<Scalar::Util|Scalar::Util> module). The referenced 3418 array returned should be treated as read-only. 3419 3420 For example, to enumerate all driver handles, database handles and 3421 statement handles: 3422 3423 sub show_child_handles { 3424 my ($h, $level) = @_; 3425 printf "%sh %s %s\n", $h->{Type}, "\t" x $level, $h; 3426 show_child_handles($_, $level + 1) 3427 for (grep { defined } @{$h->{ChildHandles}}); 3428 } 3429 3430 my %drivers = DBI->installed_drivers(); 3431 show_child_handles($_, 0) for (values %drivers); 3432 3433 =head3 C<CompatMode> (boolean, inherited) 3434 3435 The C<CompatMode> attribute is used by emulation layers (such as 3436 Oraperl) to enable compatible behaviour in the underlying driver 3437 (e.g., DBD::Oracle) for this handle. Not normally set by application code. 3438 3439 It also has the effect of disabling the 'quick FETCH' of attribute 3440 values from the handles attribute cache. So all attribute values 3441 are handled by the drivers own FETCH method. This makes them slightly 3442 slower but is useful for special-purpose drivers like DBD::Multiplex. 3443 3444 =head3 C<InactiveDestroy> (boolean) 3445 3446 The default value, false, means a handle will be fully destroyed 3447 as normal when the last reference to it is removed, just as you'd expect. 3448 3449 If set true then the handle will be treated by the DESTROY as if it was no 3450 longer Active, and so the I<database engine> related effects of DESTROYing a 3451 handle will be skipped. 3452 3453 Think of the name as meaning 'treat the handle as not-Active in the DESTROY 3454 method'. 3455 3456 For a database handle, this attribute does not disable an I<explicit> 3457 call to the disconnect method, only the implicit call from DESTROY 3458 that happens if the handle is still marked as C<Active>. 3459 3460 This attribute is specifically designed for use in Unix applications 3461 that "fork" child processes. Either the parent or the child process, 3462 but not both, should set C<InactiveDestroy> true on all their shared handles. 3463 (Note that some databases, including Oracle, don't support passing a 3464 database connection across a fork.) 3465 3466 To help tracing applications using fork the process id is shown in 3467 the trace log whenever a DBI or handle trace() method is called. 3468 The process id also shown for I<every> method call if the DBI trace 3469 level (not handle trace level) is set high enough to show the trace 3470 from the DBI's method dispatcher, e.g. >= 9. 3471 3472 =head3 C<PrintWarn> (boolean, inherited) 3473 3474 The C<PrintWarn> attribute controls the printing of warnings recorded 3475 by the driver. When set to a true value the DBI will check method 3476 calls to see if a warning condition has been set. If so, the DBI 3477 will effectively do a C<warn("$class $method warning: $DBI::errstr")> 3478 where C<$class> is the driver class and C<$method> is the name of 3479 the method which failed. E.g., 3480 3481 DBD::Oracle::db execute warning: ... warning text here ... 3482 3483 By default, C<DBI-E<gt>connect> sets C<PrintWarn> "on" if $^W is true, 3484 i.e., perl is running with warnings enabled. 3485 3486 If desired, the warnings can be caught and processed using a C<$SIG{__WARN__}> 3487 handler or modules like CGI::Carp and CGI::ErrorWrap. 3488 3489 See also L</set_err> for how warnings are recorded and L</HandleSetErr> 3490 for how to influence it. 3491 3492 Fetching the full details of warnings can require an extra round-trip 3493 to the database server for some drivers. In which case the driver 3494 may opt to only fetch the full details of warnings if the C<PrintWarn> 3495 attribute is true. If C<PrintWarn> is false then these drivers should 3496 still indicate the fact that there were warnings by setting the 3497 warning string to, for example: "3 warnings". 3498 3499 =head3 C<PrintError> (boolean, inherited) 3500 3501 The C<PrintError> attribute can be used to force errors to generate warnings (using 3502 C<warn>) in addition to returning error codes in the normal way. When set 3503 "on", any method which results in an error occuring will cause the DBI to 3504 effectively do a C<warn("$class $method failed: $DBI::errstr")> where C<$class> 3505 is the driver class and C<$method> is the name of the method which failed. E.g., 3506 3507 DBD::Oracle::db prepare failed: ... error text here ... 3508 3509 By default, C<DBI-E<gt>connect> sets C<PrintError> "on". 3510 3511 If desired, the warnings can be caught and processed using a C<$SIG{__WARN__}> 3512 handler or modules like CGI::Carp and CGI::ErrorWrap. 3513 3514 =head3 C<RaiseError> (boolean, inherited) 3515 3516 The C<RaiseError> attribute can be used to force errors to raise exceptions rather 3517 than simply return error codes in the normal way. It is "off" by default. 3518 When set "on", any method which results in an error will cause 3519 the DBI to effectively do a C<die("$class $method failed: $DBI::errstr")>, 3520 where C<$class> is the driver class and C<$method> is the name of the method 3521 that failed. E.g., 3522 3523 DBD::Oracle::db prepare failed: ... error text here ... 3524 3525 If you turn C<RaiseError> on then you'd normally turn C<PrintError> off. 3526 If C<PrintError> is also on, then the C<PrintError> is done first (naturally). 3527 3528 Typically C<RaiseError> is used in conjunction with C<eval { ... }> 3529 to catch the exception that's been thrown and followed by an 3530 C<if ($@) { ... }> block to handle the caught exception. 3531 For example: 3532 3533 eval { 3534 ... 3535 $sth->execute(); 3536 ... 3537 }; 3538 if ($@) { 3539 # $sth->err and $DBI::err will be true if error was from DBI 3540 warn $@; # print the error 3541 ... # do whatever you need to deal with the error 3542 } 3543 3544 In that eval block the $DBI::lasth variable can be useful for 3545 diagnosis and reporting if you can't be sure which handle triggered 3546 the error. For example, $DBI::lasth->{Type} and $DBI::lasth->{Statement}. 3547 3548 See also L</Transactions>. 3549 3550 If you want to temporarily turn C<RaiseError> off (inside a library function 3551 that is likely to fail, for example), the recommended way is like this: 3552 3553 { 3554 local $h->{RaiseError}; # localize and turn off for this block 3555 ... 3556 } 3557 3558 The original value will automatically and reliably be restored by Perl, 3559 regardless of how the block is exited. 3560 The same logic applies to other attributes, including C<PrintError>. 3561 3562 =head3 C<HandleError> (code ref, inherited) 3563 3564 The C<HandleError> attribute can be used to provide your own alternative behaviour 3565 in case of errors. If set to a reference to a subroutine then that 3566 subroutine is called when an error is detected (at the same point that 3567 C<RaiseError> and C<PrintError> are handled). 3568 3569 The subroutine is called with three parameters: the error message 3570 string that C<RaiseError> and C<PrintError> would use, 3571 the DBI handle being used, and the first value being returned by 3572 the method that failed (typically undef). 3573 3574 If the subroutine returns a false value then the C<RaiseError> 3575 and/or C<PrintError> attributes are checked and acted upon as normal. 3576 3577 For example, to C<die> with a full stack trace for any error: 3578 3579 use Carp; 3580 $h->{HandleError} = sub { confess(shift) }; 3581 3582 Or to turn errors into exceptions: 3583 3584 use Exception; # or your own favourite exception module 3585 $h->{HandleError} = sub { Exception->new('DBI')->raise($_[0]) }; 3586 3587 It is possible to 'stack' multiple HandleError handlers by using 3588 closures: 3589 3590 sub your_subroutine { 3591 my $previous_handler = $h->{HandleError}; 3592 $h->{HandleError} = sub { 3593 return 1 if $previous_handler and &$previous_handler(@_); 3594 ... your code here ... 3595 }; 3596 } 3597 3598 Using a C<my> inside a subroutine to store the previous C<HandleError> 3599 value is important. See L<perlsub> and L<perlref> for more information 3600 about I<closures>. 3601 3602 It is possible for C<HandleError> to alter the error message that 3603 will be used by C<RaiseError> and C<PrintError> if it returns false. 3604 It can do that by altering the value of $_[0]. This example appends 3605 a stack trace to all errors and, unlike the previous example using 3606 Carp::confess, this will work C<PrintError> as well as C<RaiseError>: 3607 3608 $h->{HandleError} = sub { $_[0]=Carp::longmess($_[0]); 0; }; 3609 3610 It is also possible for C<HandleError> to hide an error, to a limited 3611 degree, by using L</set_err> to reset $DBI::err and $DBI::errstr, 3612 and altering the return value of the failed method. For example: 3613 3614 $h->{HandleError} = sub { 3615 return 0 unless $_[0] =~ /^\S+ fetchrow_arrayref failed:/; 3616 return 0 unless $_[1]->err == 1234; # the error to 'hide' 3617 $h->set_err(undef,undef); # turn off the error 3618 $_[2] = [ ... ]; # supply alternative return value 3619 return 1; 3620 }; 3621 3622 This only works for methods which return a single value and is hard 3623 to make reliable (avoiding infinite loops, for example) and so isn't 3624 recommended for general use! If you find a I<good> use for it then 3625 please let me know. 3626 3627 =head3 C<HandleSetErr> (code ref, inherited) 3628 3629 The C<HandleSetErr> attribute can be used to intercept 3630 the setting of handle C<err>, C<errstr>, and C<state> values. 3631 If set to a reference to a subroutine then that subroutine is called 3632 whenever set_err() is called, typically by the driver or a subclass. 3633 3634 The subroutine is called with five arguments, the first five that 3635 were passed to set_err(): the handle, the C<err>, C<errstr>, and 3636 C<state> values being set, and the method name. These can be altered 3637 by changing the values in the @_ array. The return value affects 3638 set_err() behaviour, see L</set_err> for details. 3639 3640 It is possible to 'stack' multiple HandleSetErr handlers by using 3641 closures. See L</HandleError> for an example. 3642 3643 The C<HandleSetErr> and C<HandleError> subroutines differ in subtle 3644 but significant ways. HandleError is only invoked at the point where 3645 the DBI is about to return to the application with C<err> set true. 3646 It's not invoked by the failure of a method that's been called by 3647 another DBI method. HandleSetErr, on the other hand, is called 3648 whenever set_err() is called with a defined C<err> value, even if false. 3649 So it's not just for errors, despite the name, but also warn and info states. 3650 The set_err() method, and thus HandleSetErr, may be called multiple 3651 times within a method and is usually invoked from deep within driver code. 3652 3653 In theory a driver can use the return value from HandleSetErr via 3654 set_err() to decide whether to continue or not. If set_err() returns 3655 an empty list, indicating that the HandleSetErr code has 'handled' 3656 the 'error', the driver could then continue instead of failing (if 3657 that's a reasonable thing to do). This isn't excepted to be 3658 common and any such cases should be clearly marked in the driver 3659 documentation and discussed on the dbi-dev mailing list. 3660 3661 The C<HandleSetErr> attribute was added in DBI 1.41. 3662 3663 =head3 C<ErrCount> (unsigned integer) 3664 3665 The C<ErrCount> attribute is incremented whenever the set_err() 3666 method records an error. It isn't incremented by warnings or 3667 information states. It is not reset by the DBI at any time. 3668 3669 The C<ErrCount> attribute was added in DBI 1.41. Older drivers may 3670 not have been updated to use set_err() to record errors and so this 3671 attribute may not be incremented when using them. 3672 3673 3674 =head3 C<ShowErrorStatement> (boolean, inherited) 3675 3676 The C<ShowErrorStatement> attribute can be used to cause the relevant 3677 Statement text to be appended to the error messages generated by 3678 the C<RaiseError>, C<PrintError>, and C<PrintWarn> attributes. 3679 Only applies to errors on statement handles 3680 plus the prepare(), do(), and the various C<select*()> database handle methods. 3681 (The exact format of the appended text is subject to change.) 3682 3683 If C<$h-E<gt>{ParamValues}> returns a hash reference of parameter 3684 (placeholder) values then those are formatted and appended to the 3685 end of the Statement text in the error message. 3686 3687 =head3 C<TraceLevel> (integer, inherited) 3688 3689 The C<TraceLevel> attribute can be used as an alternative to the 3690 L</trace> method to set the DBI trace level and trace flags for a 3691 specific handle. See L</TRACING> for more details. 3692 3693 The C<TraceLevel> attribute is especially useful combined with 3694 C<local> to alter the trace settings for just a single block of code. 3695 3696 =head3 C<FetchHashKeyName> (string, inherited) 3697 3698 The C<FetchHashKeyName> attribute is used to specify whether the fetchrow_hashref() 3699 method should perform case conversion on the field names used for 3700 the hash keys. For historical reasons it defaults to 'C<NAME>' but 3701 it is recommended to set it to 'C<NAME_lc>' (convert to lower case) 3702 or 'C<NAME_uc>' (convert to upper case) according to your preference. 3703 It can only be set for driver and database handles. For statement 3704 handles the value is frozen when prepare() is called. 3705 3706 3707 =head3 C<ChopBlanks> (boolean, inherited) 3708 3709 The C<ChopBlanks> attribute can be used to control the trimming of trailing space 3710 characters from fixed width character (CHAR) fields. No other field 3711 types are affected, even where field values have trailing spaces. 3712 3713 The default is false (although it is possible that the default may change). 3714 Applications that need specific behaviour should set the attribute as 3715 needed. 3716 3717 Drivers are not required to support this attribute, but any driver which 3718 does not support it must arrange to return C<undef> as the attribute value. 3719 3720 3721 =head3 C<LongReadLen> (unsigned integer, inherited) 3722 3723 The C<LongReadLen> attribute may be used to control the maximum 3724 length of 'long' type fields (LONG, BLOB, CLOB, MEMO, etc.) which the driver will 3725 read from the database automatically when it fetches each row of data. 3726 3727 The C<LongReadLen> attribute only relates to fetching and reading 3728 long values; it is not involved in inserting or updating them. 3729 3730 A value of 0 means not to automatically fetch any long data. 3731 Drivers may return undef or an empty string for long fields when 3732 C<LongReadLen> is 0. 3733 3734 The default is typically 0 (zero) or 80 bytes but may vary between drivers. 3735 Applications fetching long fields should set this value to slightly 3736 larger than the longest long field value to be fetched. 3737 3738 Some databases return some long types encoded as pairs of hex digits. 3739 For these types, C<LongReadLen> relates to the underlying data 3740 length and not the doubled-up length of the encoded string. 3741 3742 Changing the value of C<LongReadLen> for a statement handle after it 3743 has been C<prepare>'d will typically have no effect, so it's common to 3744 set C<LongReadLen> on the C<$dbh> before calling C<prepare>. 3745 3746 For most drivers the value used here has a direct effect on the 3747 memory used by the statement handle while it's active, so don't be 3748 too generous. If you can't be sure what value to use you could 3749 execute an extra select statement to determine the longest value. 3750 For example: 3751 3752 $dbh->{LongReadLen} = $dbh->selectrow_array(qq{ 3753 SELECT MAX(OCTET_LENGTH(long_column_name)) 3754 FROM table WHERE ... 3755 }); 3756 $sth = $dbh->prepare(qq{ 3757 SELECT long_column_name, ... FROM table WHERE ... 3758 }); 3759 3760 You may need to take extra care if the table can be modified between 3761 the first select and the second being executed. You may also need to 3762 use a different function if OCTET_LENGTH() does not work for long 3763 types in your database. For example, for Sybase use DATALENGTH() and 3764 for Oracle use LENGTHB(). 3765 3766 See also L</LongTruncOk> for information on truncation of long types. 3767 3768 =head3 C<LongTruncOk> (boolean, inherited) 3769 3770 The C<LongTruncOk> attribute may be used to control the effect of 3771 fetching a long field value which has been truncated (typically 3772 because it's longer than the value of the C<LongReadLen> attribute). 3773 3774 By default, C<LongTruncOk> is false and so fetching a long value that 3775 needs to be truncated will cause the fetch to fail. 3776 (Applications should always be sure to 3777 check for errors after a fetch loop in case an error, such as a divide 3778 by zero or long field truncation, caused the fetch to terminate 3779 prematurely.) 3780 3781 If a fetch fails due to a long field truncation when C<LongTruncOk> is 3782 false, many drivers will allow you to continue fetching further rows. 3783 3784 See also L</LongReadLen>. 3785 3786 =head3 C<TaintIn> (boolean, inherited) 3787 3788 If the C<TaintIn> attribute is set to a true value I<and> Perl is running in 3789 taint mode (e.g., started with the C<-T> option), then all the arguments 3790 to most DBI method calls are checked for being tainted. I<This may change.> 3791 3792 The attribute defaults to off, even if Perl is in taint mode. 3793 See L<perlsec> for more about taint mode. If Perl is not 3794 running in taint mode, this attribute has no effect. 3795 3796 When fetching data that you trust you can turn off the TaintIn attribute, 3797 for that statement handle, for the duration of the fetch loop. 3798 3799 The C<TaintIn> attribute was added in DBI 1.31. 3800 3801 =head3 C<TaintOut> (boolean, inherited) 3802 3803 If the C<TaintOut> attribute is set to a true value I<and> Perl is running in 3804 taint mode (e.g., started with the C<-T> option), then most data fetched 3805 from the database is considered tainted. I<This may change.> 3806 3807 The attribute defaults to off, even if Perl is in taint mode. 3808 See L<perlsec> for more about taint mode. If Perl is not 3809 running in taint mode, this attribute has no effect. 3810 3811 When fetching data that you trust you can turn off the TaintOut attribute, 3812 for that statement handle, for the duration of the fetch loop. 3813 3814 Currently only fetched data is tainted. It is possible that the results 3815 of other DBI method calls, and the value of fetched attributes, may 3816 also be tainted in future versions. That change may well break your 3817 applications unless you take great care now. If you use DBI Taint mode, 3818 please report your experience and any suggestions for changes. 3819 3820 The C<TaintOut> attribute was added in DBI 1.31. 3821 3822 =head3 C<Taint> (boolean, inherited) 3823 3824 The C<Taint> attribute is a shortcut for L</TaintIn> and L</TaintOut> (it is also present 3825 for backwards compatibility). 3826 3827 Setting this attribute sets both L</TaintIn> and L</TaintOut>, and retrieving 3828 it returns a true value if and only if L</TaintIn> and L</TaintOut> are 3829 both set to true values. 3830 3831 =head3 C<Profile> (inherited) 3832 3833 The C<Profile> attribute enables the collection and reporting of method call timing statistics. 3834 See the L<DBI::Profile> module documentation for I<much> more detail. 3835 3836 The C<Profile> attribute was added in DBI 1.24. 3837 3838 =head3 C<ReadOnly> (boolean, inherited) 3839 3840 An application can set the C<ReadOnly> attribute of a handle to a true value to 3841 indicate that it will not be attempting to make any changes using that handle 3842 or any children of it. 3843 3844 Note that the exact definition of 'read only' is rather fuzzy. 3845 For more details see the documentation for the driver you're using. 3846 3847 If the driver can make the handle truly read-only then it should 3848 (unless doing so would have unpleasant side effect, like changing the 3849 consistency level from per-statement to per-session). 3850 Otherwise the attribute is simply advisory. 3851 3852 A driver can set the C<ReadOnly> attribute itself to indicate that the data it 3853 is connected to cannot be changed for some reason. 3854 3855 Library modules and proxy drivers can use the attribute to influence their behavior. 3856 For example, the DBD::Gofer driver considers the C<ReadOnly> attribute when 3857 making a decison about whether to retry an operation that failed. 3858 3859 The attribute should be set to 1 or 0 (or undef). Other values are reserved. 3860 3861 =head3 C<private_your_module_name_*> 3862 3863 The DBI provides a way to store extra information in a DBI handle as 3864 "private" attributes. The DBI will allow you to store and retrieve any 3865 attribute which has a name starting with "C<private_>". 3866 3867 It is I<strongly> recommended that you use just I<one> private 3868 attribute (e.g., use a hash ref) I<and> give it a long and unambiguous 3869 name that includes the module or application name that the attribute 3870 relates to (e.g., "C<private_YourFullModuleName_thingy>"). 3871 3872 Because of the way the Perl tie mechanism works you cannot reliably 3873 use the C<||=> operator directly to initialise the attribute, like this: 3874 3875 my $foo = $dbh->{private_yourmodname_foo} ||= { ... }; # WRONG 3876 3877 you should use a two step approach like this: 3878 3879 my $foo = $dbh->{private_yourmodname_foo}; 3880 $foo ||= $dbh->{private_yourmodname_foo} = { ... }; 3881 3882 This attribute is primarily of interest to people sub-classing DBI, 3883 or for applications to piggy-back extra information onto DBI handles. 3884 3885 =head1 DBI DATABASE HANDLE OBJECTS 3886 3887 This section covers the methods and attributes associated with 3888 database handles. 3889 3890 =head2 Database Handle Methods 3891 3892 The following methods are specified for DBI database handles: 3893 3894 =head3 C<clone> 3895 3896 $new_dbh = $dbh->clone(); 3897 $new_dbh = $dbh->clone(\%attr); 3898 3899 The C<clone> method duplicates the $dbh connection by connecting 3900 with the same parameters ($dsn, $user, $password) as originally used. 3901 3902 The attributes for the cloned connect are the same as those used 3903 for the original connect, with some other attribute merged over 3904 them depending on the \%attr parameter. 3905 3906 If \%attr is given then the attributes it contains are merged into 3907 the original attributes and override any with the same names. 3908 Effectively the same as doing: 3909 3910 %attribues_used = ( %original_attributes, %attr ); 3911 3912 If \%attr is not given then it defaults to a hash containing all 3913 the attributes in the attribute cache of $dbh excluding any non-code 3914 references, plus the main boolean attributes (RaiseError, PrintError, 3915 AutoCommit, etc.). This behaviour is subject to change. 3916 3917 The clone method can be used even if the database handle is disconnected. 3918 3919 The C<clone> method was added in DBI 1.33. It is very new and likely 3920 to change. 3921 3922 =head3 C<data_sources> 3923 3924 @ary = $dbh->data_sources(); 3925 @ary = $dbh->data_sources(\%attr); 3926 3927 Returns a list of data sources (databases) available via the $dbh 3928 driver's data_sources() method, plus any extra data sources that 3929 the driver can discover via the connected $dbh. Typically the extra 3930 data sources are other databases managed by the same server process 3931 that the $dbh is connected to. 3932 3933 Data sources are returned in a form suitable for passing to the 3934 L</connect> method (that is, they will include the "C<dbi:$driver:>" prefix). 3935 3936 The data_sources() method, for a $dbh, was added in DBI 1.38. 3937 3938 =head3 C<do> 3939 3940 $rows = $dbh->do($statement) or die $dbh->errstr; 3941 $rows = $dbh->do($statement, \%attr) or die $dbh->errstr; 3942 $rows = $dbh->do($statement, \%attr, @bind_values) or die ... 3943 3944 Prepare and execute a single statement. Returns the number of rows 3945 affected or C<undef> on error. A return value of C<-1> means the 3946 number of rows is not known, not applicable, or not available. 3947 3948 This method is typically most useful for I<non>-C<SELECT> statements that 3949 either cannot be prepared in advance (due to a limitation of the 3950 driver) or do not need to be executed repeatedly. It should not 3951 be used for C<SELECT> statements because it does not return a statement 3952 handle (so you can't fetch any data). 3953 3954 The default C<do> method is logically similar to: 3955 3956 sub do { 3957 my($dbh, $statement, $attr, @bind_values) = @_; 3958 my $sth = $dbh->prepare($statement, $attr) or return undef; 3959 $sth->execute(@bind_values) or return undef; 3960 my $rows = $sth->rows; 3961 ($rows == 0) ? "0E0" : $rows; # always return true if no error 3962 } 3963 3964 For example: 3965 3966 my $rows_deleted = $dbh->do(q{ 3967 DELETE FROM table 3968 WHERE status = ? 3969 }, undef, 'DONE') or die $dbh->errstr; 3970 3971 Using placeholders and C<@bind_values> with the C<do> method can be 3972 useful because it avoids the need to correctly quote any variables 3973 in the C<$statement>. But if you'll be executing the statement many 3974 times then it's more efficient to C<prepare> it once and call 3975 C<execute> many times instead. 3976 3977 The C<q{...}> style quoting used in this example avoids clashing with 3978 quotes that may be used in the SQL statement. Use the double-quote-like 3979 C<qq{...}> operator if you want to interpolate variables into the string. 3980 See L<perlop/"Quote and Quote-like Operators"> for more details. 3981 3982 =head3 C<last_insert_id> 3983 3984 $rv = $dbh->last_insert_id($catalog, $schema, $table, $field); 3985 $rv = $dbh->last_insert_id($catalog, $schema, $table, $field, \%attr); 3986 3987 Returns a value 'identifying' the row just inserted, if possible. 3988 Typically this would be a value assigned by the database server 3989 to a column with an I<auto_increment> or I<serial> type. 3990 Returns undef if the driver does not support the method or can't 3991 determine the value. 3992 3993 The $catalog, $schema, $table, and $field parameters may be required 3994 for some drivers (see below). If you don't know the parameter values 3995 and your driver does not need them, then use C<undef> for each. 3996 3997 There are several caveats to be aware of with this method if you want 3998 to use it for portable applications: 3999 4000 B<*> For some drivers the value may only available immediately after 4001 the insert statement has executed (e.g., mysql, Informix). 4002 4003 B<*> For some drivers the $catalog, $schema, $table, and $field parameters 4004 are required, for others they are ignored (e.g., mysql). 4005 4006 B<*> Drivers may return an indeterminate value if no insert has 4007 been performed yet. 4008 4009 B<*> For some drivers the value may only be available if placeholders 4010 have I<not> been used (e.g., Sybase, MS SQL). In this case the value 4011 returned would be from the last non-placeholder insert statement. 4012 4013 B<*> Some drivers may need driver-specific hints about how to get 4014 the value. For example, being told the name of the database 'sequence' 4015 object that holds the value. Any such hints are passed as driver-specific 4016 attributes in the \%attr parameter. 4017 4018 B<*> If the underlying database offers nothing better, then some 4019 drivers may attempt to implement this method by executing 4020 "C<select max($field) from $table>". Drivers using any approach 4021 like this should issue a warning if C<AutoCommit> is true because 4022 it is generally unsafe - another process may have modified the table 4023 between your insert and the select. For situations where you know 4024 it is safe, such as when you have locked the table, you can silence 4025 the warning by passing C<Warn> => 0 in \%attr. 4026 4027 B<*> If no insert has been performed yet, or the last insert failed, 4028 then the value is implementation defined. 4029 4030 Given all the caveats above, it's clear that this method must be 4031 used with care. 4032 4033 The C<last_insert_id> method was added in DBI 1.38. 4034 4035 =head3 C<selectrow_array> 4036 4037 @row_ary = $dbh->selectrow_array($statement); 4038 @row_ary = $dbh->selectrow_array($statement, \%attr); 4039 @row_ary = $dbh->selectrow_array($statement, \%attr, @bind_values); 4040 4041 This utility method combines L</prepare>, L</execute> and 4042 L</fetchrow_array> into a single call. If called in a list context, it 4043 returns the first row of data from the statement. The C<$statement> 4044 parameter can be a previously prepared statement handle, in which case 4045 the C<prepare> is skipped. 4046 4047 If any method fails, and L</RaiseError> is not set, C<selectrow_array> 4048 will return an empty list. 4049 4050 If called in a scalar context for a statement handle that has more 4051 than one column, it is undefined whether the driver will return 4052 the value of the first column or the last. So don't do that. 4053 Also, in a scalar context, an C<undef> is returned if there are no 4054 more rows or if an error occurred. That C<undef> can't be distinguished 4055 from an C<undef> returned because the first field value was NULL. 4056 For these reasons you should exercise some caution if you use 4057 C<selectrow_array> in a scalar context, or just don't do that. 4058 4059 4060 =head3 C<selectrow_arrayref> 4061 4062 $ary_ref = $dbh->selectrow_arrayref($statement); 4063 $ary_ref = $dbh->selectrow_arrayref($statement, \%attr); 4064 $ary_ref = $dbh->selectrow_arrayref($statement, \%attr, @bind_values); 4065 4066 This utility method combines L</prepare>, L</execute> and 4067 L</fetchrow_arrayref> into a single call. It returns the first row of 4068 data from the statement. The C<$statement> parameter can be a previously 4069 prepared statement handle, in which case the C<prepare> is skipped. 4070 4071 If any method fails, and L</RaiseError> is not set, C<selectrow_array> 4072 will return undef. 4073 4074 4075 =head3 C<selectrow_hashref> 4076 4077 $hash_ref = $dbh->selectrow_hashref($statement); 4078 $hash_ref = $dbh->selectrow_hashref($statement, \%attr); 4079 $hash_ref = $dbh->selectrow_hashref($statement, \%attr, @bind_values); 4080 4081 This utility method combines L</prepare>, L</execute> and 4082 L</fetchrow_hashref> into a single call. It returns the first row of 4083 data from the statement. The C<$statement> parameter can be a previously 4084 prepared statement handle, in which case the C<prepare> is skipped. 4085 4086 If any method fails, and L</RaiseError> is not set, C<selectrow_hashref> 4087 will return undef. 4088 4089 4090 =head3 C<selectall_arrayref> 4091 4092 $ary_ref = $dbh->selectall_arrayref($statement); 4093 $ary_ref = $dbh->selectall_arrayref($statement, \%attr); 4094 $ary_ref = $dbh->selectall_arrayref($statement, \%attr, @bind_values); 4095 4096 This utility method combines L</prepare>, L</execute> and 4097 L</fetchall_arrayref> into a single call. It returns a reference to an 4098 array containing a reference to an array (or hash, see below) for each row of 4099 data fetched. 4100 4101 The C<$statement> parameter can be a previously prepared statement handle, 4102 in which case the C<prepare> is skipped. This is recommended if the 4103 statement is going to be executed many times. 4104 4105 If L</RaiseError> is not set and any method except C<fetchall_arrayref> 4106 fails then C<selectall_arrayref> will return C<undef>; if 4107 C<fetchall_arrayref> fails then it will return with whatever data 4108 has been fetched thus far. You should check C<$sth-E<gt>err> 4109 afterwards (or use the C<RaiseError> attribute) to discover if the data is 4110 complete or was truncated due to an error. 4111 4112 The L</fetchall_arrayref> method called by C<selectall_arrayref> 4113 supports a $max_rows parameter. You can specify a value for $max_rows 4114 by including a 'C<MaxRows>' attribute in \%attr. In which case finish() 4115 is called for you after fetchall_arrayref() returns. 4116 4117 The L</fetchall_arrayref> method called by C<selectall_arrayref> 4118 also supports a $slice parameter. You can specify a value for $slice by 4119 including a 'C<Slice>' or 'C<Columns>' attribute in \%attr. The only 4120 difference between the two is that if C<Slice> is not defined and 4121 C<Columns> is an array ref, then the array is assumed to contain column 4122 index values (which count from 1), rather than perl array index values. 4123 In which case the array is copied and each value decremented before 4124 passing to C</fetchall_arrayref>. 4125 4126 You may often want to fetch an array of rows where each row is stored as a 4127 hash. That can be done simple using: 4128 4129 my $emps = $dbh->selectall_arrayref( 4130 "SELECT ename FROM emp ORDER BY ename", 4131 { Slice => {} } 4132 ); 4133 foreach my $emp ( @$emps ) { 4134 print "Employee: $emp->{ename}\n"; 4135 } 4136 4137 Or, to fetch into an array instead of an array ref: 4138 4139 @result = @{ $dbh->selectall_arrayref($sql, { Slice => {} }) }; 4140 4141 See L</fetchall_arrayref> method for more details. 4142 4143 =head3 C<selectall_hashref> 4144 4145 $hash_ref = $dbh->selectall_hashref($statement, $key_field); 4146 $hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr); 4147 $hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr, @bind_values); 4148 4149 This utility method combines L</prepare>, L</execute> and 4150 L</fetchall_hashref> into a single call. It returns a reference to a 4151 hash containing one entry, at most, for each row, as returned by fetchall_hashref(). 4152 4153 The C<$statement> parameter can be a previously prepared statement handle, 4154 in which case the C<prepare> is skipped. This is recommended if the 4155 statement is going to be executed many times. 4156 4157 The C<$key_field> parameter defines which column, or columns, are used as keys 4158 in the returned hash. It can either be the name of a single field, or a 4159 reference to an array containing multiple field names. Using multiple names 4160 yields a tree of nested hashes. 4161 4162 If a row has the same key as an earlier row then it replaces the earlier row. 4163 4164 If any method except C<fetchrow_hashref> fails, and L</RaiseError> is not set, 4165 C<selectall_hashref> will return C<undef>. If C<fetchrow_hashref> fails and 4166 L</RaiseError> is not set, then it will return with whatever data it 4167 has fetched thus far. $DBI::err should be checked to catch that. 4168 4169 See fetchall_hashref() for more details. 4170 4171 =head3 C<selectcol_arrayref> 4172 4173 $ary_ref = $dbh->selectcol_arrayref($statement); 4174 $ary_ref = $dbh->selectcol_arrayref($statement, \%attr); 4175 $ary_ref = $dbh->selectcol_arrayref($statement, \%attr, @bind_values); 4176 4177 This utility method combines L</prepare>, L</execute>, and fetching one 4178 column from all the rows, into a single call. It returns a reference to 4179 an array containing the values of the first column from each row. 4180 4181 The C<$statement> parameter can be a previously prepared statement handle, 4182 in which case the C<prepare> is skipped. This is recommended if the 4183 statement is going to be executed many times. 4184 4185 If any method except C<fetch> fails, and L</RaiseError> is not set, 4186 C<selectcol_arrayref> will return C<undef>. If C<fetch> fails and 4187 L</RaiseError> is not set, then it will return with whatever data it 4188 has fetched thus far. $DBI::err should be checked to catch that. 4189 4190 The C<selectcol_arrayref> method defaults to pushing a single column 4191 value (the first) from each row into the result array. However, it can 4192 also push another column, or even multiple columns per row, into the 4193 result array. This behaviour can be specified via a 'C<Columns>' 4194 attribute which must be a ref to an array containing the column number 4195 or numbers to use. For example: 4196 4197 # get array of id and name pairs: 4198 my $ary_ref = $dbh->selectcol_arrayref("select id, name from table", { Columns=>[1,2] }); 4199 my %hash = @$ary_ref; # build hash from key-value pairs so $hash{$id} => name 4200 4201 You can specify a maximum number of rows to fetch by including a 4202 'C<MaxRows>' attribute in \%attr. 4203 4204 =head3 C<prepare> 4205 4206 $sth = $dbh->prepare($statement) or die $dbh->errstr; 4207 $sth = $dbh->prepare($statement, \%attr) or die $dbh->errstr; 4208 4209 Prepares a statement for later execution by the database 4210 engine and returns a reference to a statement handle object. 4211 4212 The returned statement handle can be used to get attributes of the 4213 statement and invoke the L</execute> method. See L</Statement Handle Methods>. 4214 4215 Drivers for engines without the concept of preparing a 4216 statement will typically just store the statement in the returned 4217 handle and process it when C<$sth-E<gt>execute> is called. Such drivers are 4218 unlikely to give much useful information about the 4219 statement, such as C<$sth-E<gt>{NUM_OF_FIELDS}>, until after C<$sth-E<gt>execute> 4220 has been called. Portable applications should take this into account. 4221 4222 In general, DBI drivers do not parse the contents of the statement 4223 (other than simply counting any L</Placeholders>). The statement is 4224 passed directly to the database engine, sometimes known as pass-thru 4225 mode. This has advantages and disadvantages. On the plus side, you can 4226 access all the functionality of the engine being used. On the downside, 4227 you're limited if you're using a simple engine, and you need to take extra care if 4228 writing applications intended to be portable between engines. 4229 4230 Portable applications should not assume that a new statement can be 4231 prepared and/or executed while still fetching results from a previous 4232 statement. 4233 4234 Some command-line SQL tools use statement terminators, like a semicolon, 4235 to indicate the end of a statement. Such terminators should not normally 4236 be used with the DBI. 4237 4238 4239 =head3 C<prepare_cached> 4240 4241 $sth = $dbh->prepare_cached($statement) 4242 $sth = $dbh->prepare_cached($statement, \%attr) 4243 $sth = $dbh->prepare_cached($statement, \%attr, $if_active) 4244 4245 Like L</prepare> except that the statement handle returned will be 4246 stored in a hash associated with the C<$dbh>. If another call is made to 4247 C<prepare_cached> with the same C<$statement> and C<%attr> parameter values, 4248 then the corresponding cached C<$sth> will be returned without contacting the 4249 database server. 4250 4251 The C<$if_active> parameter lets you adjust the behaviour if an 4252 already cached statement handle is still Active. There are several 4253 alternatives: 4254 4255 =over 4 4256 4257 =item B<0>: A warning will be generated, and finish() will be called on 4258 the statement handle before it is returned. This is the default 4259 behaviour if $if_active is not passed. 4260 4261 =item B<1>: finish() will be called on the statement handle, but the 4262 warning is suppressed. 4263 4264 =item B<2>: Disables any checking. 4265 4266 =item B<3>: The existing active statement handle will be removed from the 4267 cache and a new statement handle prepared and cached in its place. 4268 This is the safest option because it doesn't affect the state of the 4269 old handle, it just removes it from the cache. [Added in DBI 1.40] 4270 4271 =back 4272 4273 Here are some examples of C<prepare_cached>: 4274 4275 sub insert_hash { 4276 my ($table, $field_values) = @_; 4277 # sort to keep field order, and thus sql, stable for prepare_cached 4278 my @fields = sort keys %$field_values; 4279 my @values = @{$field_values}{@fields}; 4280 my $sql = sprintf "insert into %s (%s) values (%s)", 4281 $table, join(",", @fields), join(",", ("?")x@fields); 4282 my $sth = $dbh->prepare_cached($sql); 4283 return $sth->execute(@values); 4284 } 4285 4286 sub search_hash { 4287 my ($table, $field_values) = @_; 4288 # sort to keep field order, and thus sql, stable for prepare_cached 4289 my @fields = sort keys %$field_values; 4290 my @values = @{$field_values}{@fields}; 4291 my $qualifier = ""; 4292 $qualifier = "where ".join(" and ", map { "$_=?" } @fields) if @fields; 4293 $sth = $dbh->prepare_cached("SELECT * FROM $table $qualifier"); 4294 return $dbh->selectall_arrayref($sth, {}, @values); 4295 } 4296 4297 I<Caveat emptor:> This caching can be useful in some applications, 4298 but it can also cause problems and should be used with care. Here 4299 is a contrived case where caching would cause a significant problem: 4300 4301 my $sth = $dbh->prepare_cached('SELECT * FROM foo WHERE bar=?'); 4302 $sth->execute(...); 4303 while (my $data = $sth->fetchrow_hashref) { 4304 4305 # later, in some other code called within the loop... 4306 my $sth2 = $dbh->prepare_cached('SELECT * FROM foo WHERE bar=?'); 4307 $sth2->execute(...); 4308 while (my $data2 = $sth2->fetchrow_arrayref) { 4309 do_stuff(...); 4310 } 4311 } 4312 4313 In this example, since both handles are preparing the exact same statement, 4314 C<$sth2> will not be its own statement handle, but a duplicate of C<$sth> 4315 returned from the cache. The results will certainly not be what you expect. 4316 Typically the the inner fetch loop will work normally, fetching all 4317 the records and terminating when there are no more, but now $sth 4318 is the same as $sth2 the outer fetch loop will also terminate. 4319 4320 You'll know if you run into this problem because prepare_cached() 4321 will generate a warning by default (when $if_active is false). 4322 4323 The cache used by prepare_cached() is keyed by both the statement 4324 and any attributes so you can also avoid this issue by doing something 4325 like: 4326 4327 $sth = $dbh->prepare_cached("...", { dbi_dummy => __FILE__.__LINE__ }); 4328 4329 which will ensure that prepare_cached only returns statements cached 4330 by that line of code in that source file. 4331 4332 If you'd like the cache to managed intelligently, you can tie the 4333 hashref returned by C<CachedKids> to an appropriate caching module, 4334 such as L<Tie::Cache::LRU>: 4335 4336 my $cache; 4337 tie %$cache, 'Tie::Cache::LRU', 500; 4338 $dbh->{CachedKids} = $cache; 4339 4340 =head3 C<commit> 4341 4342 $rc = $dbh->commit or die $dbh->errstr; 4343 4344 Commit (make permanent) the most recent series of database changes 4345 if the database supports transactions and AutoCommit is off. 4346 4347 If C<AutoCommit> is on, then calling 4348 C<commit> will issue a "commit ineffective with AutoCommit" warning. 4349 4350 See also L</Transactions> in the L</FURTHER INFORMATION> section below. 4351 4352 =head3 C<rollback> 4353 4354 $rc = $dbh->rollback or die $dbh->errstr; 4355 4356 Rollback (undo) the most recent series of uncommitted database 4357 changes if the database supports transactions and AutoCommit is off. 4358 4359 If C<AutoCommit> is on, then calling 4360 C<rollback> will issue a "rollback ineffective with AutoCommit" warning. 4361 4362 See also L</Transactions> in the L</FURTHER INFORMATION> section below. 4363 4364 =head3 C<begin_work> 4365 4366 $rc = $dbh->begin_work or die $dbh->errstr; 4367 4368 Enable transactions (by turning C<AutoCommit> off) until the next call 4369 to C<commit> or C<rollback>. After the next C<commit> or C<rollback>, 4370 C<AutoCommit> will automatically be turned on again. 4371 4372 If C<AutoCommit> is already off when C<begin_work> is called then 4373 it does nothing except return an error. If the driver does not support 4374 transactions then when C<begin_work> attempts to set C<AutoCommit> off 4375 the driver will trigger a fatal error. 4376 4377 See also L</Transactions> in the L</FURTHER INFORMATION> section below. 4378 4379 4380 =head3 C<disconnect> 4381 4382 $rc = $dbh->disconnect or warn $dbh->errstr; 4383 4384 Disconnects the database from the database handle. C<disconnect> is typically only used 4385 before exiting the program. The handle is of little use after disconnecting. 4386 4387 The transaction behaviour of the C<disconnect> method is, sadly, 4388 undefined. Some database systems (such as Oracle and Ingres) will 4389 automatically commit any outstanding changes, but others (such as 4390 Informix) will rollback any outstanding changes. Applications not 4391 using C<AutoCommit> should explicitly call C<commit> or C<rollback> before 4392 calling C<disconnect>. 4393 4394 The database is automatically disconnected by the C<DESTROY> method if 4395 still connected when there are no longer any references to the handle. 4396 The C<DESTROY> method for each driver should implicitly call C<rollback> to 4397 undo any uncommitted changes. This is vital behaviour to ensure that 4398 incomplete transactions don't get committed simply because Perl calls 4399 C<DESTROY> on every object before exiting. Also, do not rely on the order 4400 of object destruction during "global destruction", as it is undefined. 4401 4402 Generally, if you want your changes to be commited or rolled back when 4403 you disconnect, then you should explicitly call L</commit> or L</rollback> 4404 before disconnecting. 4405 4406 If you disconnect from a database while you still have active 4407 statement handles (e.g., SELECT statement handles that may have 4408 more data to fetch), you will get a warning. The warning may indicate 4409 that a fetch loop terminated early, perhaps due to an uncaught error. 4410 To avoid the warning call the C<finish> method on the active handles. 4411 4412 4413 =head3 C<ping> 4414 4415 $rc = $dbh->ping; 4416 4417 Attempts to determine, in a reasonably efficient way, if the database 4418 server is still running and the connection to it is still working. 4419 Individual drivers should implement this function in the most suitable 4420 manner for their database engine. 4421 4422 The current I<default> implementation always returns true without 4423 actually doing anything. Actually, it returns "C<0 but true>" which is 4424 true but zero. That way you can tell if the return value is genuine or 4425 just the default. Drivers should override this method with one that 4426 does the right thing for their type of database. 4427 4428 Few applications would have direct use for this method. See the specialized 4429 Apache::DBI module for one example usage. 4430 4431 4432 =head3 C<get_info> 4433 4434 $value = $dbh->get_info( $info_type ); 4435 4436 Returns information about the implementation, i.e. driver and data 4437 source capabilities, restrictions etc. It returns C<undef> for 4438 unknown or unimplemented information types. For example: 4439 4440 $database_version = $dbh->get_info( 18 ); # SQL_DBMS_VER 4441 $max_select_tables = $dbh->get_info( 106 ); # SQL_MAXIMUM_TABLES_IN_SELECT 4442 4443 See L</"Standards Reference Information"> for more detailed information 4444 about the information types and their meanings and possible return values. 4445 4446 The DBI::Const::GetInfoType module exports a %GetInfoType hash that 4447 can be used to map info type names to numbers. For example: 4448 4449 $database_version = $dbh->get_info( $GetInfoType{SQL_DBMS_VER} ); 4450 4451 The names are a merging of the ANSI and ODBC standards (which differ 4452 in some cases). See L<DBI::Const::GetInfoType> for more details. 4453 4454 Because some DBI methods make use of get_info(), drivers are strongly 4455 encouraged to support I<at least> the following very minimal set 4456 of information types to ensure the DBI itself works properly: 4457 4458 Type Name Example A Example B 4459 ---- -------------------------- ------------ ---------------- 4460 17 SQL_DBMS_NAME 'ACCESS' 'Oracle' 4461 18 SQL_DBMS_VER '03.50.0000' '08.01.0721 ...' 4462 29 SQL_IDENTIFIER_QUOTE_CHAR '`' '"' 4463 41 SQL_CATALOG_NAME_SEPARATOR '.' '@' 4464 114 SQL_CATALOG_LOCATION 1 2 4465 4466 =head3 C<table_info> 4467 4468 $sth = $dbh->table_info( $catalog, $schema, $table, $type ); 4469 $sth = $dbh->table_info( $catalog, $schema, $table, $type, \%attr ); 4470 4471 # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc 4472 4473 Returns an active statement handle that can be used to fetch 4474 information about tables and views that exist in the database. 4475 4476 The arguments $catalog, $schema and $table may accept search patterns 4477 according to the database/driver, for example: $table = '%FOO%'; 4478 Remember that the underscore character ('C<_>') is a search pattern 4479 that means match any character, so 'FOO_%' is the same as 'FOO%' 4480 and 'FOO_BAR%' will match names like 'FOO1BAR'. 4481 4482 The value of $type is a comma-separated list of one or more types of 4483 tables to be returned in the result set. Each value may optionally be 4484 quoted, e.g.: 4485 4486 $type = "TABLE"; 4487 $type = "'TABLE','VIEW'"; 4488 4489 In addition the following special cases may also be supported by some drivers: 4490 4491 =over 4 4492 4493 =item * 4494 If the value of $catalog is '%' and $schema and $table name 4495 are empty strings, the result set contains a list of catalog names. 4496 For example: 4497 4498 $sth = $dbh->table_info('%', '', ''); 4499 4500 =item * 4501 If the value of $schema is '%' and $catalog and $table are empty 4502 strings, the result set contains a list of schema names. 4503 4504 =item * 4505 If the value of $type is '%' and $catalog, $schema, and $table are all 4506 empty strings, the result set contains a list of table types. 4507 4508 =back 4509 4510 If your driver doesn't support one or more of the selection filter 4511 parameters then you may get back more than you asked for and can 4512 do the filtering yourself. 4513 4514 This method can be expensive, and can return a large amount of data. 4515 (For example, small Oracle installation returns over 2000 rows.) 4516 So it's a good idea to use the filters to limit the data as much as possible. 4517 4518 The statement handle returned has at least the following fields in the 4519 order show below. Other fields, after these, may also be present. 4520 4521 B<TABLE_CAT>: Table catalog identifier. This field is NULL (C<undef>) if not 4522 applicable to the data source, which is usually the case. This field 4523 is empty if not applicable to the table. 4524 4525 B<TABLE_SCHEM>: The name of the schema containing the TABLE_NAME value. 4526 This field is NULL (C<undef>) if not applicable to data source, and 4527 empty if not applicable to the table. 4528 4529 B<TABLE_NAME>: Name of the table (or view, synonym, etc). 4530 4531 B<TABLE_TYPE>: One of the following: "TABLE", "VIEW", "SYSTEM TABLE", 4532 "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM" or a type 4533 identifier that is specific to the data 4534 source. 4535 4536 B<REMARKS>: A description of the table. May be NULL (C<undef>). 4537 4538 Note that C<table_info> might not return records for all tables. 4539 Applications can use any valid table regardless of whether it's 4540 returned by C<table_info>. 4541 4542 See also L</tables>, L</"Catalog Methods"> and 4543 L</"Standards Reference Information">. 4544 4545 =head3 C<column_info> 4546 4547 $sth = $dbh->column_info( $catalog, $schema, $table, $column ); 4548 4549 # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc 4550 4551 Returns an active statement handle that can be used to fetch 4552 information about columns in specified tables. 4553 4554 The arguments $schema, $table and $column may accept search patterns 4555 according to the database/driver, for example: $table = '%FOO%'; 4556 4557 Note: The support for the selection criteria is driver specific. If the 4558 driver doesn't support one or more of them then you may get back more 4559 than you asked for and can do the filtering yourself. 4560 4561 If the arguments don't match any tables then you'll still get a statement 4562 handle, it'll just return no rows. 4563 4564 The statement handle returned has at least the following fields in the 4565 order shown below. Other fields, after these, may also be present. 4566 4567 B<TABLE_CAT>: The catalog identifier. 4568 This field is NULL (C<undef>) if not applicable to the data source, 4569 which is often the case. This field is empty if not applicable to the 4570 table. 4571 4572 B<TABLE_SCHEM>: The schema identifier. 4573 This field is NULL (C<undef>) if not applicable to the data source, 4574 and empty if not applicable to the table. 4575 4576 B<TABLE_NAME>: The table identifier. 4577 Note: A driver may provide column metadata not only for base tables, but 4578 also for derived objects like SYNONYMS etc. 4579 4580 B<COLUMN_NAME>: The column identifier. 4581 4582 B<DATA_TYPE>: The concise data type code. 4583 4584 B<TYPE_NAME>: A data source dependent data type name. 4585 4586 B<COLUMN_SIZE>: The column size. 4587 This is the maximum length in characters for character data types, 4588 the number of digits or bits for numeric data types or the length 4589 in the representation of temporal types. 4590 See the relevant specifications for detailed information. 4591 4592 B<BUFFER_LENGTH>: The length in bytes of transferred data. 4593 4594 B<DECIMAL_DIGITS>: The total number of significant digits to the right of 4595 the decimal point. 4596 4597 B<NUM_PREC_RADIX>: The radix for numeric precision. 4598 The value is 10 or 2 for numeric data types and NULL (C<undef>) if not 4599 applicable. 4600 4601 B<NULLABLE>: Indicates if a column can accept NULLs. 4602 The following values are defined: 4603 4604 SQL_NO_NULLS 0 4605 SQL_NULLABLE 1 4606 SQL_NULLABLE_UNKNOWN 2 4607 4608 B<REMARKS>: A description of the column. 4609 4610 B<COLUMN_DEF>: The default value of the column. 4611 4612 B<SQL_DATA_TYPE>: The SQL data type. 4613 4614 B<SQL_DATETIME_SUB>: The subtype code for datetime and interval data types. 4615 4616 B<CHAR_OCTET_LENGTH>: The maximum length in bytes of a character or binary 4617 data type column. 4618 4619 B<ORDINAL_POSITION>: The column sequence number (starting with 1). 4620 4621 B<IS_NULLABLE>: Indicates if the column can accept NULLs. 4622 Possible values are: 'NO', 'YES' and ''. 4623 4624 SQL/CLI defines the following additional columns: 4625 4626 CHAR_SET_CAT 4627 CHAR_SET_SCHEM 4628 CHAR_SET_NAME 4629 COLLATION_CAT 4630 COLLATION_SCHEM 4631 COLLATION_NAME 4632 UDT_CAT 4633 UDT_SCHEM 4634 UDT_NAME 4635 DOMAIN_CAT 4636 DOMAIN_SCHEM 4637 DOMAIN_NAME 4638 SCOPE_CAT 4639 SCOPE_SCHEM 4640 SCOPE_NAME 4641 MAX_CARDINALITY 4642 DTD_IDENTIFIER 4643 IS_SELF_REF 4644 4645 Drivers capable of supplying any of those values should do so in 4646 the corresponding column and supply undef values for the others. 4647 4648 Drivers wishing to provide extra database/driver specific information 4649 should do so in extra columns beyond all those listed above, and 4650 use lowercase field names with the driver-specific prefix (i.e., 4651 'ora_...'). Applications accessing such fields should do so by name 4652 and not by column number. 4653 4654 The result set is ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME 4655 and ORDINAL_POSITION. 4656 4657 Note: There is some overlap with statement attributes (in perl) and 4658 SQLDescribeCol (in ODBC). However, SQLColumns provides more metadata. 4659 4660 See also L</"Catalog Methods"> and L</"Standards Reference Information">. 4661 4662 =head3 C<primary_key_info> 4663 4664 $sth = $dbh->primary_key_info( $catalog, $schema, $table ); 4665 4666 # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc 4667 4668 Returns an active statement handle that can be used to fetch information 4669 about columns that make up the primary key for a table. 4670 The arguments don't accept search patterns (unlike table_info()). 4671 4672 The statement handle will return one row per column, ordered by 4673 TABLE_CAT, TABLE_SCHEM, TABLE_NAME, and KEY_SEQ. 4674 If there is no primary key then the statement handle will fetch no rows. 4675 4676 Note: The support for the selection criteria, such as $catalog, is 4677 driver specific. If the driver doesn't support catalogs and/or 4678 schemas, it may ignore these criteria. 4679 4680 The statement handle returned has at least the following fields in the 4681 order shown below. Other fields, after these, may also be present. 4682 4683 B<TABLE_CAT>: The catalog identifier. 4684 This field is NULL (C<undef>) if not applicable to the data source, 4685 which is often the case. This field is empty if not applicable to the 4686 table. 4687 4688 B<TABLE_SCHEM>: The schema identifier. 4689 This field is NULL (C<undef>) if not applicable to the data source, 4690 and empty if not applicable to the table. 4691 4692 B<TABLE_NAME>: The table identifier. 4693 4694 B<COLUMN_NAME>: The column identifier. 4695 4696 B<KEY_SEQ>: The column sequence number (starting with 1). 4697 Note: This field is named B<ORDINAL_POSITION> in SQL/CLI. 4698 4699 B<PK_NAME>: The primary key constraint identifier. 4700 This field is NULL (C<undef>) if not applicable to the data source. 4701 4702 See also L</"Catalog Methods"> and L</"Standards Reference Information">. 4703 4704 =head3 C<primary_key> 4705 4706 @key_column_names = $dbh->primary_key( $catalog, $schema, $table ); 4707 4708 Simple interface to the primary_key_info() method. Returns a list of 4709 the column names that comprise the primary key of the specified table. 4710 The list is in primary key column sequence order. 4711 If there is no primary key then an empty list is returned. 4712 4713 =head3 C<foreign_key_info> 4714 4715 $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table 4716 , $fk_catalog, $fk_schema, $fk_table ); 4717 4718 $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table 4719 , $fk_catalog, $fk_schema, $fk_table 4720 , \%attr ); 4721 4722 # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc 4723 4724 Returns an active statement handle that can be used to fetch information 4725 about foreign keys in and/or referencing the specified table(s). 4726 The arguments don't accept search patterns (unlike table_info()). 4727 4728 C<$pk_catalog>, C<$pk_schema>, C<$pk_table> 4729 identify the primary (unique) key table (B<PKT>). 4730 4731 C<$fk_catalog>, C<$fk_schema>, C<$fk_table> 4732 identify the foreign key table (B<FKT>). 4733 4734 If both B<PKT> and B<FKT> are given, the function returns the foreign key, if 4735 any, in table B<FKT> that refers to the primary (unique) key of table B<PKT>. 4736 (Note: In SQL/CLI, the result is implementation-defined.) 4737 4738 If only B<PKT> is given, then the result set contains the primary key 4739 of that table and all foreign keys that refer to it. 4740 4741 If only B<FKT> is given, then the result set contains all foreign keys 4742 in that table and the primary keys to which they refer. 4743 (Note: In SQL/CLI, the result includes unique keys too.) 4744 4745 For example: 4746 4747 $sth = $dbh->foreign_key_info( undef, $user, 'master'); 4748 $sth = $dbh->foreign_key_info( undef, undef, undef , undef, $user, 'detail'); 4749 $sth = $dbh->foreign_key_info( undef, $user, 'master', undef, $user, 'detail'); 4750 4751 # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc 4752 4753 Note: The support for the selection criteria, such as C<$catalog>, is 4754 driver specific. If the driver doesn't support catalogs and/or 4755 schemas, it may ignore these criteria. 4756 4757 The statement handle returned has the following fields in the order shown below. 4758 Because ODBC never includes unique keys, they define different columns in the 4759 result set than SQL/CLI. SQL/CLI column names are shown in parentheses. 4760 4761 B<PKTABLE_CAT ( UK_TABLE_CAT )>: 4762 The primary (unique) key table catalog identifier. 4763 This field is NULL (C<undef>) if not applicable to the data source, 4764 which is often the case. This field is empty if not applicable to the 4765 table. 4766 4767 B<PKTABLE_SCHEM ( UK_TABLE_SCHEM )>: 4768 The primary (unique) key table schema identifier. 4769 This field is NULL (C<undef>) if not applicable to the data source, 4770 and empty if not applicable to the table. 4771 4772 B<PKTABLE_NAME ( UK_TABLE_NAME )>: 4773 The primary (unique) key table identifier. 4774 4775 B<PKCOLUMN_NAME (UK_COLUMN_NAME )>: 4776 The primary (unique) key column identifier. 4777 4778 B<FKTABLE_CAT ( FK_TABLE_CAT )>: 4779 The foreign key table catalog identifier. 4780 This field is NULL (C<undef>) if not applicable to the data source, 4781 which is often the case. This field is empty if not applicable to the 4782 table. 4783 4784 B<FKTABLE_SCHEM ( FK_TABLE_SCHEM )>: 4785 The foreign key table schema identifier. 4786 This field is NULL (C<undef>) if not applicable to the data source, 4787 and empty if not applicable to the table. 4788 4789 B<FKTABLE_NAME ( FK_TABLE_NAME )>: 4790 The foreign key table identifier. 4791 4792 B<FKCOLUMN_NAME ( FK_COLUMN_NAME )>: 4793 The foreign key column identifier. 4794 4795 B<KEY_SEQ ( ORDINAL_POSITION )>: 4796 The column sequence number (starting with 1). 4797 4798 B<UPDATE_RULE ( UPDATE_RULE )>: 4799 The referential action for the UPDATE rule. 4800 The following codes are defined: 4801 4802 CASCADE 0 4803 RESTRICT 1 4804 SET NULL 2 4805 NO ACTION 3 4806 SET DEFAULT 4 4807 4808 B<DELETE_RULE ( DELETE_RULE )>: 4809 The referential action for the DELETE rule. 4810 The codes are the same as for UPDATE_RULE. 4811 4812 B<FK_NAME ( FK_NAME )>: 4813 The foreign key name. 4814 4815 B<PK_NAME ( UK_NAME )>: 4816 The primary (unique) key name. 4817 4818 B<DEFERRABILITY ( DEFERABILITY )>: 4819 The deferrability of the foreign key constraint. 4820 The following codes are defined: 4821 4822 INITIALLY DEFERRED 5 4823 INITIALLY IMMEDIATE 6 4824 NOT DEFERRABLE 7 4825 4826 B< ( UNIQUE_OR_PRIMARY )>: 4827 This column is necessary if a driver includes all candidate (i.e. primary and 4828 alternate) keys in the result set (as specified by SQL/CLI). 4829 The value of this column is UNIQUE if the foreign key references an alternate 4830 key and PRIMARY if the foreign key references a primary key, or it 4831 may be undefined if the driver doesn't have access to the information. 4832 4833 See also L</"Catalog Methods"> and L</"Standards Reference Information">. 4834 4835 =head3 C<statistics_info> 4836 4837 B<Warning:> This method is experimental and may change. 4838 4839 $sth = $dbh->statistics_info( $catalog, $schema, $table, $unique_only, $quick ); 4840 4841 # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc 4842 4843 Returns an active statement handle that can be used to fetch statistical 4844 information about a table and its indexes. 4845 4846 The arguments don't accept search patterns (unlike L</table_info>). 4847 4848 If the boolean argument $unique_only is true, only UNIQUE indexes will be 4849 returned in the result set, otherwise all indexes will be returned. 4850 4851 If the boolean argument $quick is set, the actual statistical information 4852 columns (CARDINALITY and PAGES) will only be returned if they are readily 4853 available from the server, and might not be current. Some databases may 4854 return stale statistics or no statistics at all with this flag set. 4855 4856 The statement handle will return at most one row per column name per index, 4857 plus at most one row for the entire table itself, ordered by NON_UNIQUE, TYPE, 4858 INDEX_QUALIFIER, INDEX_NAME, and ORDINAL_POSITION. 4859 4860 Note: The support for the selection criteria, such as $catalog, is 4861 driver specific. If the driver doesn't support catalogs and/or 4862 schemas, it may ignore these criteria. 4863 4864 The statement handle returned has at least the following fields in the 4865 order shown below. Other fields, after these, may also be present. 4866 4867 B<TABLE_CAT>: The catalog identifier. 4868 This field is NULL (C<undef>) if not applicable to the data source, 4869 which is often the case. This field is empty if not applicable to the 4870 table. 4871 4872 B<TABLE_SCHEM>: The schema identifier. 4873 This field is NULL (C<undef>) if not applicable to the data source, 4874 and empty if not applicable to the table. 4875 4876 B<TABLE_NAME>: The table identifier. 4877 4878 B<NON_UNIQUE>: Unique index indicator. 4879 Returns 0 for unique indexes, 1 for non-unique indexes 4880 4881 B<INDEX_QUALIFIER>: Index qualifier identifier. 4882 The identifier that is used to qualify the index name when doing a 4883 C<DROP INDEX>; NULL (C<undef>) is returned if an index qualifier is not 4884 supported by the data source. 4885 If a non-NULL (defined) value is returned in this column, it must be used 4886 to qualify the index name on a C<DROP INDEX> statement; otherwise, 4887 the TABLE_SCHEM should be used to qualify the index name. 4888 4889 B<INDEX_NAME>: The index identifier. 4890 4891 B<TYPE>: The type of information being returned. Can be any of the 4892 following values: 'table', 'btree', 'clustered', 'content', 'hashed', 4893 or 'other'. 4894 4895 In the case that this field is 'table', all fields 4896 other than TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TYPE, 4897 CARDINALITY, and PAGES will be NULL (C<undef>). 4898 4899 B<ORDINAL_POSITION>: Column sequence number (starting with 1). 4900 4901 B<COLUMN_NAME>: The column identifier. 4902 4903 B<ASC_OR_DESC>: Column sort sequence. 4904 C<A> for Ascending, C<D> for Descending, or NULL (C<undef>) if 4905 not supported for this index. 4906 4907 B<CARDINALITY>: Cardinality of the table or index. 4908 For indexes, this is the number of unique values in the index. 4909 For tables, this is the number of rows in the table. 4910 If not supported, the value will be NULL (C<undef>). 4911 4912 B<PAGES>: Number of storage pages used by this table or index. 4913 If not supported, the value will be NULL (C<undef>). 4914 4915 B<FILTER_CONDITION>: The index filter condition as a string. 4916 If the index is not a filtered index, or it cannot be determined 4917 whether the index is a filtered index, this value is NULL (C<undef>). 4918 If the index is a filtered index, but the filter condition 4919 cannot be determined, this value is the empty string C<''>. 4920 Otherwise it will be the literal filter condition as a string, 4921 such as C<SALARY <= 4500>. 4922 4923 See also L</"Catalog Methods"> and L</"Standards Reference Information">. 4924 4925 =head3 C<tables> 4926 4927 @names = $dbh->tables( $catalog, $schema, $table, $type ); 4928 @names = $dbh->tables; # deprecated 4929 4930 Simple interface to table_info(). Returns a list of matching 4931 table names, possibly including a catalog/schema prefix. 4932 4933 See L</table_info> for a description of the parameters. 4934 4935 If C<$dbh-E<gt>get_info(29)> returns true (29 is SQL_IDENTIFIER_QUOTE_CHAR) 4936 then the table names are constructed and quoted by L</quote_identifier> 4937 to ensure they are usable even if they contain whitespace or reserved 4938 words etc. This means that the table names returned will include 4939 quote characters. 4940 4941 =head3 C<type_info_all> 4942 4943 $type_info_all = $dbh->type_info_all; 4944 4945 Returns a reference to an array which holds information about each data 4946 type variant supported by the database and driver. The array and its 4947 contents should be treated as read-only. 4948 4949 The first item is a reference to an 'index' hash of C<Name =>E<gt> C<Index> pairs. 4950 The items following that are references to arrays, one per supported data 4951 type variant. The leading index hash defines the names and order of the 4952 fields within the arrays that follow it. 4953 For example: 4954 4955 $type_info_all = [ 4956 { TYPE_NAME => 0, 4957 DATA_TYPE => 1, 4958 COLUMN_SIZE => 2, # was PRECISION originally 4959 LITERAL_PREFIX => 3, 4960 LITERAL_SUFFIX => 4, 4961 CREATE_PARAMS => 5, 4962 NULLABLE => 6, 4963 CASE_SENSITIVE => 7, 4964 SEARCHABLE => 8, 4965 UNSIGNED_ATTRIBUTE=> 9, 4966 FIXED_PREC_SCALE => 10, # was MONEY originally 4967 AUTO_UNIQUE_VALUE => 11, # was AUTO_INCREMENT originally 4968 LOCAL_TYPE_NAME => 12, 4969 MINIMUM_SCALE => 13, 4970 MAXIMUM_SCALE => 14, 4971 SQL_DATA_TYPE => 15, 4972 SQL_DATETIME_SUB => 16, 4973 NUM_PREC_RADIX => 17, 4974 INTERVAL_PRECISION=> 18, 4975 }, 4976 [ 'VARCHAR', SQL_VARCHAR, 4977 undef, "'","'", undef,0, 1,1,0,0,0,undef,1,255, undef 4978 ], 4979 [ 'INTEGER', SQL_INTEGER, 4980 undef, "", "", undef,0, 0,1,0,0,0,undef,0, 0, 10 4981 ], 4982 ]; 4983 4984 More than one row may have the same value in the C<DATA_TYPE> 4985 field if there are different ways to spell the type name and/or there 4986 are variants of the type with different attributes (e.g., with and 4987 without C<AUTO_UNIQUE_VALUE> set, with and without C<UNSIGNED_ATTRIBUTE>, etc). 4988 4989 The rows are ordered by C<DATA_TYPE> first and then by how closely each 4990 type maps to the corresponding ODBC SQL data type, closest first. 4991 4992 The meaning of the fields is described in the documentation for 4993 the L</type_info> method. 4994 4995 An 'index' hash is provided so you don't need to rely on index 4996 values defined above. However, using DBD::ODBC with some old ODBC 4997 drivers may return older names, shown as comments in the example above. 4998 Another issue with the index hash is that the lettercase of the 4999 keys is not defined. It is usually uppercase, as show here, but 5000 drivers may return names with any lettercase. 5001 5002 Drivers are also free to return extra driver-specific columns of 5003 information - though it's recommended that they start at column 5004 index 50 to leave room for expansion of the DBI/ODBC specification. 5005 5006 The type_info_all() method is not normally used directly. 5007 The L</type_info> method provides a more usable and useful interface 5008 to the data. 5009 5010 =head3 C<type_info> 5011 5012 @type_info = $dbh->type_info($data_type); 5013 5014 Returns a list of hash references holding information about one or more 5015 variants of $data_type. The list is ordered by C<DATA_TYPE> first and 5016 then by how closely each type maps to the corresponding ODBC SQL data 5017 type, closest first. If called in a scalar context then only the first 5018 (best) element is returned. 5019 5020 If $data_type is undefined or C<SQL_ALL_TYPES>, then the list will 5021 contain hashes for all data type variants supported by the database and driver. 5022 5023 If $data_type is an array reference then C<type_info> returns the 5024 information for the I<first> type in the array that has any matches. 5025 5026 The keys of the hash follow the same letter case conventions as the 5027 rest of the DBI (see L</Naming Conventions and Name Space>). The 5028 following uppercase items should always exist, though may be undef: 5029 5030 =over 4 5031 5032 =item TYPE_NAME (string) 5033 5034 Data type name for use in CREATE TABLE statements etc. 5035 5036 =item DATA_TYPE (integer) 5037 5038 SQL data type number. 5039 5040 =item COLUMN_SIZE (integer) 5041 5042 For numeric types, this is either the total number of digits (if the 5043 NUM_PREC_RADIX value is 10) or the total number of bits allowed in the 5044 column (if NUM_PREC_RADIX is 2). 5045 5046 For string types, this is the maximum size of the string in characters. 5047 5048 For date and interval types, this is the maximum number of characters 5049 needed to display the value. 5050 5051 =item LITERAL_PREFIX (string) 5052 5053 Characters used to prefix a literal. A typical prefix is "C<'>" for characters, 5054 or possibly "C<0x>" for binary values passed as hexadecimal. NULL (C<undef>) is 5055 returned for data types for which this is not applicable. 5056 5057 5058 =item LITERAL_SUFFIX (string) 5059 5060 Characters used to suffix a literal. Typically "C<'>" for characters. 5061 NULL (C<undef>) is returned for data types where this is not applicable. 5062 5063 =item CREATE_PARAMS (string) 5064 5065 Parameter names for data type definition. For example, C<CREATE_PARAMS> for a 5066 C<DECIMAL> would be "C<precision,scale>" if the DECIMAL type should be 5067 declared as C<DECIMAL(>I<precision,scale>C<)> where I<precision> and I<scale> 5068 are integer values. For a C<VARCHAR> it would be "C<max length>". 5069 NULL (C<undef>) is returned for data types for which this is not applicable. 5070 5071 =item NULLABLE (integer) 5072 5073 Indicates whether the data type accepts a NULL value: 5074 C<0> or an empty string = no, C<1> = yes, C<2> = unknown. 5075 5076 =item CASE_SENSITIVE (boolean) 5077 5078 Indicates whether the data type is case sensitive in collations and 5079 comparisons. 5080 5081 =item SEARCHABLE (integer) 5082 5083 Indicates how the data type can be used in a WHERE clause, as 5084 follows: 5085 5086 0 - Cannot be used in a WHERE clause 5087 1 - Only with a LIKE predicate 5088 2 - All comparison operators except LIKE 5089 3 - Can be used in a WHERE clause with any comparison operator 5090 5091 =item UNSIGNED_ATTRIBUTE (boolean) 5092 5093 Indicates whether the data type is unsigned. NULL (C<undef>) is returned 5094 for data types for which this is not applicable. 5095 5096 =item FIXED_PREC_SCALE (boolean) 5097 5098 Indicates whether the data type always has the same precision and scale 5099 (such as a money type). NULL (C<undef>) is returned for data types 5100 for which 5101 this is not applicable. 5102 5103 =item AUTO_UNIQUE_VALUE (boolean) 5104 5105 Indicates whether a column of this data type is automatically set to a 5106 unique value whenever a new row is inserted. NULL (C<undef>) is returned 5107 for data types for which this is not applicable. 5108 5109 =item LOCAL_TYPE_NAME (string) 5110 5111 Localized version of the C<TYPE_NAME> for use in dialog with users. 5112 NULL (C<undef>) is returned if a localized name is not available (in which 5113 case C<TYPE_NAME> should be used). 5114 5115 =item MINIMUM_SCALE (integer) 5116 5117 The minimum scale of the data type. If a data type has a fixed scale, 5118 then C<MAXIMUM_SCALE> holds the same value. NULL (C<undef>) is returned for 5119 data types for which this is not applicable. 5120 5121 =item MAXIMUM_SCALE (integer) 5122 5123 The maximum scale of the data type. If a data type has a fixed scale, 5124 then C<MINIMUM_SCALE> holds the same value. NULL (C<undef>) is returned for 5125 data types for which this is not applicable. 5126 5127 =item SQL_DATA_TYPE (integer) 5128 5129 This column is the same as the C<DATA_TYPE> column, except for interval 5130 and datetime data types. For interval and datetime data types, the 5131 C<SQL_DATA_TYPE> field will return C<SQL_INTERVAL> or C<SQL_DATETIME>, and the 5132 C<SQL_DATETIME_SUB> field below will return the subcode for the specific 5133 interval or datetime data type. If this field is NULL, then the driver 5134 does not support or report on interval or datetime subtypes. 5135 5136 =item SQL_DATETIME_SUB (integer) 5137 5138 For interval or datetime data types, where the C<SQL_DATA_TYPE> 5139 field above is C<SQL_INTERVAL> or C<SQL_DATETIME>, this field will 5140 hold the I<subcode> for the specific interval or datetime data type. 5141 Otherwise it will be NULL (C<undef>). 5142 5143 Although not mentioned explicitly in the standards, it seems there 5144 is a simple relationship between these values: 5145 5146 DATA_TYPE == (10 * SQL_DATA_TYPE) + SQL_DATETIME_SUB 5147 5148 =item NUM_PREC_RADIX (integer) 5149 5150 The radix value of the data type. For approximate numeric types, 5151 C<NUM_PREC_RADIX> 5152 contains the value 2 and C<COLUMN_SIZE> holds the number of bits. For 5153 exact numeric types, C<NUM_PREC_RADIX> contains the value 10 and C<COLUMN_SIZE> holds 5154 the number of decimal digits. NULL (C<undef>) is returned either for data types 5155 for which this is not applicable or if the driver cannot report this information. 5156 5157 =item INTERVAL_PRECISION (integer) 5158 5159 The interval leading precision for interval types. NULL is returned 5160 either for data types for which this is not applicable or if the driver 5161 cannot report this information. 5162 5163 =back 5164 5165 For example, to find the type name for the fields in a select statement 5166 you can do: 5167 5168 @names = map { scalar $dbh->type_info($_)->{TYPE_NAME} } @{ $sth->{TYPE} } 5169 5170 Since DBI and ODBC drivers vary in how they map their types into the 5171 ISO standard types you may need to search for more than one type. 5172 Here's an example looking for a usable type to store a date: 5173 5174 $my_date_type = $dbh->type_info( [ SQL_DATE, SQL_TIMESTAMP ] ); 5175 5176 Similarly, to more reliably find a type to store small integers, you could 5177 use a list starting with C<SQL_SMALLINT>, C<SQL_INTEGER>, C<SQL_DECIMAL>, etc. 5178 5179 See also L</"Standards Reference Information">. 5180 5181 5182 =head3 C<quote> 5183 5184 $sql = $dbh->quote($value); 5185 $sql = $dbh->quote($value, $data_type); 5186 5187 Quote a string literal for use as a literal value in an SQL statement, 5188 by escaping any special characters (such as quotation marks) 5189 contained within the string and adding the required type of outer 5190 quotation marks. 5191 5192 $sql = sprintf "SELECT foo FROM bar WHERE baz = %s", 5193 $dbh->quote("Don't"); 5194 5195 For most database types, at least those that conform to SQL standards, quote 5196 would return C<'Don''t'> (including the outer quotation marks). For others it 5197 may return something like C<'Don\'t'> 5198 5199 An undefined C<$value> value will be returned as the string C<NULL> (without 5200 single quotation marks) to match how NULLs are represented in SQL. 5201 5202 If C<$data_type> is supplied, it is used to try to determine the required 5203 quoting behaviour by using the information returned by L</type_info>. 5204 As a special case, the standard numeric types are optimized to return 5205 C<$value> without calling C<type_info>. 5206 5207 Quote will probably I<not> be able to deal with all possible input 5208 (such as binary data or data containing newlines), and is not related in 5209 any way with escaping or quoting shell meta-characters. 5210 5211 It is valid for the quote() method to return an SQL expression that 5212 evaluates to the desired string. For example: 5213 5214 $quoted = $dbh->quote("one\ntwo\0three") 5215 5216 may return something like: 5217 5218 CONCAT('one', CHAR(12), 'two', CHAR(0), 'three') 5219 5220 The quote() method should I<not> be used with L</"Placeholders and 5221 Bind Values">. 5222 5223 =head3 C<quote_identifier> 5224 5225 $sql = $dbh->quote_identifier( $name ); 5226 $sql = $dbh->quote_identifier( $catalog, $schema, $table, \%attr ); 5227 5228 Quote an identifier (table name etc.) for use in an SQL statement, 5229 by escaping any special characters (such as double quotation marks) 5230 it contains and adding the required type of outer quotation marks. 5231 5232 Undefined names are ignored and the remainder are quoted and then 5233 joined together, typically with a dot (C<.>) character. For example: 5234 5235 $id = $dbh->quote_identifier( undef, 'Her schema', 'My table' ); 5236 5237 would, for most database types, return C<"Her schema"."My table"> 5238 (including all the double quotation marks). 5239 5240 If three names are supplied then the first is assumed to be a 5241 catalog name and special rules may be applied based on what L</get_info> 5242 returns for SQL_CATALOG_NAME_SEPARATOR (41) and SQL_CATALOG_LOCATION (114). 5243 For example, for Oracle: 5244 5245 $id = $dbh->quote_identifier( 'link', 'schema', 'table' ); 5246 5247 would return C<"schema"."table"@"link">. 5248 5249 =head3 C<take_imp_data> 5250 5251 $imp_data = $dbh->take_imp_data; 5252 5253 Leaves the $dbh in an almost dead, zombie-like, state and returns 5254 a binary string of raw implementation data from the driver which 5255 describes the current database connection. Effectively it detaches 5256 the underlying database API connection data from the DBI handle. 5257 After calling take_imp_data(), all other methods except C<DESTROY> 5258 will generate a warning and return undef. 5259 5260 Why would you want to do this? You don't, forget I even mentioned it. 5261 Unless, that is, you're implementing something advanced like a 5262 multi-threaded connection pool. See L<DBI::Pool>. 5263 5264 The returned $imp_data can be passed as a C<dbi_imp_data> attribute 5265 to a later connect() call, even in a separate thread in the same 5266 process, where the driver can use it to 'adopt' the existing 5267 connection that the implementation data was taken from. 5268 5269 Some things to keep in mind... 5270 5271 B<*> the $imp_data holds the only reference to the underlying 5272 database API connection data. That connection is still 'live' and 5273 won't be cleaned up properly unless the $imp_data is used to create 5274 a new $dbh which is then allowed to disconnect() normally. 5275 5276 B<*> using the same $imp_data to create more than one other new 5277 $dbh at a time may well lead to unpleasant problems. Don't do that. 5278 5279 Any child statement handles are effectively destroyed when take_imp_data() is 5280 called. 5281 5282 The C<take_imp_data> method was added in DBI 1.36 but wasn't useful till 1.49. 5283 5284 5285 =head2 Database Handle Attributes 5286 5287 This section describes attributes specific to database handles. 5288 5289 Changes to these database handle attributes do not affect any other 5290 existing or future database handles. 5291 5292 Attempting to set or get the value of an unknown attribute generates a warning, 5293 except for private driver-specific attributes (which all have names 5294 starting with a lowercase letter). 5295 5296 Example: 5297 5298 $h->{AutoCommit} = ...; # set/write 5299 ... = $h->{AutoCommit}; # get/read 5300 5301 =head3 C<AutoCommit> (boolean) 5302 5303 If true, then database changes cannot be rolled-back (undone). If false, 5304 then database changes automatically occur within a "transaction", which 5305 must either be committed or rolled back using the C<commit> or C<rollback> 5306 methods. 5307 5308 Drivers should always default to C<AutoCommit> mode (an unfortunate 5309 choice largely forced on the DBI by ODBC and JDBC conventions.) 5310 5311 Attempting to set C<AutoCommit> to an unsupported value is a fatal error. 5312 This is an important feature of the DBI. Applications that need 5313 full transaction behaviour can set C<$dbh-E<gt>{AutoCommit} = 0> (or 5314 set C<AutoCommit> to 0 via L</connect>) 5315 without having to check that the value was assigned successfully. 5316 5317 For the purposes of this description, we can divide databases into three 5318 categories: 5319 5320 Databases which don't support transactions at all. 5321 Databases in which a transaction is always active. 5322 Databases in which a transaction must be explicitly started (C<'BEGIN WORK'>). 5323 5324 B<* Databases which don't support transactions at all> 5325 5326 For these databases, attempting to turn C<AutoCommit> off is a fatal error. 5327 C<commit> and C<rollback> both issue warnings about being ineffective while 5328 C<AutoCommit> is in effect. 5329 5330 B<* Databases in which a transaction is always active> 5331 5332 These are typically mainstream commercial relational databases with 5333 "ANSI standard" transaction behaviour. 5334 If C<AutoCommit> is off, then changes to the database won't have any 5335 lasting effect unless L</commit> is called (but see also 5336 L</disconnect>). If L</rollback> is called then any changes since the 5337 last commit are undone. 5338 5339 If C<AutoCommit> is on, then the effect is the same as if the DBI 5340 called C<commit> automatically after every successful database 5341 operation. So calling C<commit> or C<rollback> explicitly while 5342 C<AutoCommit> is on would be ineffective because the changes would 5343 have already been commited. 5344 5345 Changing C<AutoCommit> from off to on will trigger a L</commit>. 5346 5347 For databases which don't support a specific auto-commit mode, the 5348 driver has to commit each statement automatically using an explicit 5349 C<COMMIT> after it completes successfully (and roll it back using an 5350 explicit C<ROLLBACK> if it fails). The error information reported to the 5351 application will correspond to the statement which was executed, unless 5352 it succeeded and the commit or rollback failed. 5353 5354 B<* Databases in which a transaction must be explicitly started> 5355 5356 For these databases, the intention is to have them act like databases in 5357 which a transaction is always active (as described above). 5358 5359 To do this, the driver will automatically begin an explicit transaction 5360 when C<AutoCommit> is turned off, or after a L</commit> or 5361 L</rollback> (or when the application issues the next database 5362 operation after one of those events). 5363 5364 In this way, the application does not have to treat these databases 5365 as a special case. 5366 5367 See L</commit>, L</disconnect> and L</Transactions> for other important 5368 notes about transactions. 5369 5370 5371 =head3 C<Driver> (handle) 5372 5373 Holds the handle of the parent driver. The only recommended use for this 5374 is to find the name of the driver using: 5375 5376 $dbh->{Driver}->{Name} 5377 5378 5379 =head3 C<Name> (string) 5380 5381 Holds the "name" of the database. Usually (and recommended to be) the 5382 same as the "C<dbi:DriverName:...>" string used to connect to the database, 5383 but with the leading "C<dbi:DriverName:>" removed. 5384 5385 5386 =head3 C<Statement> (string, read-only) 5387 5388 Returns the statement string passed to the most recent L</prepare> method 5389 called in this database handle, even if that method failed. This is especially 5390 useful where C<RaiseError> is enabled and the exception handler checks $@ 5391 and sees that a 'prepare' method call failed. 5392 5393 5394 =head3 C<RowCacheSize> (integer) 5395 5396 A hint to the driver indicating the size of the local row cache that the 5397 application would like the driver to use for future C<SELECT> statements. 5398 If a row cache is not implemented, then setting C<RowCacheSize> is ignored 5399 and getting the value returns C<undef>. 5400 5401 Some C<RowCacheSize> values have special meaning, as follows: 5402 5403 0 - Automatically determine a reasonable cache size for each C<SELECT> 5404 1 - Disable the local row cache 5405 >1 - Cache this many rows 5406 <0 - Cache as many rows that will fit into this much memory for each C<SELECT>. 5407 5408 Note that large cache sizes may require a very large amount of memory 5409 (I<cached rows * maximum size of row>). Also, a large cache will cause 5410 a longer delay not only for the first fetch, but also whenever the 5411 cache needs refilling. 5412 5413 See also the L</RowsInCache> statement handle attribute. 5414 5415 =head3 C<Username> (string) 5416 5417 Returns the username used to connect to the database. 5418 5419 5420 =head1 DBI STATEMENT HANDLE OBJECTS 5421 5422 This section lists the methods and attributes associated with DBI 5423 statement handles. 5424 5425 =head2 Statement Handle Methods 5426 5427 The DBI defines the following methods for use on DBI statement handles: 5428 5429 =head3 C<bind_param> 5430 5431 $sth->bind_param($p_num, $bind_value) 5432 $sth->bind_param($p_num, $bind_value, \%attr) 5433 $sth->bind_param($p_num, $bind_value, $bind_type) 5434 5435 The C<bind_param> method takes a copy of $bind_value and associates it 5436 (binds it) with a placeholder, identified by $p_num, embedded in 5437 the prepared statement. Placeholders are indicated with question 5438 mark character (C<?>). For example: 5439 5440 $dbh->{RaiseError} = 1; # save having to check each method call 5441 $sth = $dbh->prepare("SELECT name, age FROM people WHERE name LIKE ?"); 5442 $sth->bind_param(1, "John%"); # placeholders are numbered from 1 5443 $sth->execute; 5444 DBI::dump_results($sth); 5445 5446 See L</"Placeholders and Bind Values"> for more information. 5447 5448 5449 B<Data Types for Placeholders> 5450 5451 The C<\%attr> parameter can be used to hint at the data type the 5452 placeholder should have. This is rarely needed. Typically, the driver is only 5453 interested in knowing if the placeholder should be bound as a number or a string. 5454 5455 $sth->bind_param(1, $value, { TYPE => SQL_INTEGER }); 5456 5457 As a short-cut for the common case, the data type can be passed 5458 directly, in place of the C<\%attr> hash reference. This example is 5459 equivalent to the one above: 5460 5461 $sth->bind_param(1, $value, SQL_INTEGER); 5462 5463 The C<TYPE> value indicates the standard (non-driver-specific) type for 5464 this parameter. To specify the driver-specific type, the driver may 5465 support a driver-specific attribute, such as C<{ ora_type =E<gt> 97 }>. 5466 5467 The SQL_INTEGER and other related constants can be imported using 5468 5469 use DBI qw(:sql_types); 5470 5471 See L</"DBI Constants"> for more information. 5472 5473 The data type for a placeholder cannot be changed after the first 5474 C<bind_param> call. In fact the whole \%attr parameter is 'sticky' 5475 in the sense that a driver only needs to consider the \%attr parameter 5476 for the first call, for a given $sth and parameter. After that the driver 5477 may ignore the \%attr parameter for that placeholder. 5478 5479 Perl only has string and number scalar data types. All database types 5480 that aren't numbers are bound as strings and must be in a format the 5481 database will understand except where the bind_param() TYPE attribute 5482 specifies a type that implies a particular format. For example, given: 5483 5484 $sth->bind_param(1, $value, SQL_DATETIME); 5485 5486 the driver should expect $value to be in the ODBC standard SQL_DATETIME 5487 format, which is 'YYYY-MM-DD HH:MM:SS'. Similarly for SQL_DATE, SQL_TIME etc. 5488 5489 As an alternative to specifying the data type in the C<bind_param> call, 5490 you can let the driver pass the value as the default type (C<VARCHAR>). 5491 You can then use an SQL function to convert the type within the statement. 5492 For example: 5493 5494 INSERT INTO price(code, price) VALUES (?, CONVERT(MONEY,?)) 5495 5496 The C<CONVERT> function used here is just an example. The actual function 5497 and syntax will vary between different databases and is non-portable. 5498 5499 See also L</"Placeholders and Bind Values"> for more information. 5500 5501 5502 =head3 C<bind_param_inout> 5503 5504 $rc = $sth->bind_param_inout($p_num, \$bind_value, $max_len) or die $sth->errstr; 5505 $rv = $sth->bind_param_inout($p_num, \$bind_value, $max_len, \%attr) or ... 5506 $rv = $sth->bind_param_inout($p_num, \$bind_value, $max_len, $bind_type) or ... 5507 5508 This method acts like L</bind_param>, but also enables values to be 5509 updated by the statement. The statement is typically 5510 a call to a stored procedure. The C<$bind_value> must be passed as a 5511 reference to the actual value to be used. 5512 5513 Note that unlike L</bind_param>, the C<$bind_value> variable is not 5514 copied when C<bind_param_inout> is called. Instead, the value in the 5515 variable is read at the time L</execute> is called. 5516 5517 The additional C<$max_len> parameter specifies the minimum amount of 5518 memory to allocate to C<$bind_value> for the new value. If the value 5519 returned from the database is too 5520 big to fit, then the execution should fail. If unsure what value to use, 5521 pick a generous length, i.e., a length larger than the longest value that would ever be 5522 returned. The only cost of using a larger value than needed is wasted memory. 5523 5524 Undefined values or C<undef> are used to indicate null values. 5525 See also L</"Placeholders and Bind Values"> for more information. 5526 5527 5528 =head3 C<bind_param_array> 5529 5530 $rc = $sth->bind_param_array($p_num, $array_ref_or_value) 5531 $rc = $sth->bind_param_array($p_num, $array_ref_or_value, \%attr) 5532 $rc = $sth->bind_param_array($p_num, $array_ref_or_value, $bind_type) 5533 5534 The C<bind_param_array> method is used to bind an array of values 5535 to a placeholder embedded in the prepared statement which is to be executed 5536 with L</execute_array>. For example: 5537 5538 $dbh->{RaiseError} = 1; # save having to check each method call 5539 $sth = $dbh->prepare("INSERT INTO staff (first_name, last_name, dept) VALUES(?, ?, ?)"); 5540 $sth->bind_param_array(1, [ 'John', 'Mary', 'Tim' ]); 5541 $sth->bind_param_array(2, [ 'Booth', 'Todd', 'Robinson' ]); 5542 $sth->bind_param_array(3, "SALES"); # scalar will be reused for each row 5543 $sth->execute_array( { ArrayTupleStatus => \my @tuple_status } ); 5544 5545 The C<%attr> ($bind_type) argument is the same as defined for L</bind_param>. 5546 Refer to L</bind_param> for general details on using placeholders. 5547 5548 (Note that bind_param_array() can I<not> be used to expand a 5549 placeholder into a list of values for a statement like "SELECT foo 5550 WHERE bar IN (?)". A placeholder can only ever represent one value 5551 per execution.) 5552 5553 Scalar values, including C<undef>, may also be bound by 5554 C<bind_param_array>. In which case the same value will be used for each 5555 L</execute> call. Driver-specific implementations may behave 5556 differently, e.g., when binding to a stored procedure call, some 5557 databases may permit mixing scalars and arrays as arguments. 5558 5559 The default implementation provided by DBI (for drivers that have 5560 not implemented array binding) is to iteratively call L</execute> for 5561 each parameter tuple provided in the bound arrays. Drivers may 5562 provide more optimized implementations using whatever bulk operation 5563 support the database API provides. The default driver behaviour should 5564 match the default DBI behaviour, but always consult your driver 5565 documentation as there may be driver specific issues to consider. 5566 5567 Note that the default implementation currently only supports non-data 5568 returning statements (INSERT, UPDATE, but not SELECT). Also, 5569 C<bind_param_array> and L</bind_param> cannot be mixed in the same 5570 statement execution, and C<bind_param_array> must be used with 5571 L</execute_array>; using C<bind_param_array> will have no effect 5572 for L</execute>. 5573 5574 The C<bind_param_array> method was added in DBI 1.22. 5575 5576 =head3 C<execute> 5577 5578 $rv = $sth->execute or die $sth->errstr; 5579 $rv = $sth->execute(@bind_values) or die $sth->errstr; 5580 5581 Perform whatever processing is necessary to execute the prepared 5582 statement. An C<undef> is returned if an error occurs. A successful 5583 C<execute> always returns true regardless of the number of rows affected, 5584 even if it's zero (see below). It is always important to check the 5585 return status of C<execute> (and most other DBI methods) for errors 5586 if you're not using L</RaiseError>. 5587 5588 For a I<non>-C<SELECT> statement, C<execute> returns the number of rows 5589 affected, if known. If no rows were affected, then C<execute> returns 5590 "C<0E0>", which Perl will treat as 0 but will regard as true. Note that it 5591 is I<not> an error for no rows to be affected by a statement. If the 5592 number of rows affected is not known, then C<execute> returns -1. 5593 5594 For C<SELECT> statements, execute simply "starts" the query within the 5595 database engine. Use one of the fetch methods to retrieve the data after 5596 calling C<execute>. The C<execute> method does I<not> return the number of 5597 rows that will be returned by the query (because most databases can't 5598 tell in advance), it simply returns a true value. 5599 5600 You can tell if the statement was a C<SELECT> statement by checking if 5601 C<$sth-E<gt>{NUM_OF_FIELDS}> is greater than zero after calling C<execute>. 5602 5603 If any arguments are given, then C<execute> will effectively call 5604 L</bind_param> for each value before executing the statement. Values 5605 bound in this way are usually treated as C<SQL_VARCHAR> types unless 5606 the driver can determine the correct type (which is rare), or unless 5607 C<bind_param> (or C<bind_param_inout>) has already been used to 5608 specify the type. 5609 5610 Note that passing C<execute> an empty array is the same as passing no arguments 5611 at all, which will execute the statement with previously bound values. 5612 That's probably not what you want. 5613 5614 If execute() is called on a statement handle that's still active 5615 ($sth->{Active} is true) then it should effectively call finish() 5616 to tidy up the previous execution results before starting this new 5617 execution. 5618 5619 =head3 C<execute_array> 5620 5621 $tuples = $sth->execute_array(\%attr) or die $sth->errstr; 5622 $tuples = $sth->execute_array(\%attr, @bind_values) or die $sth->errstr; 5623 5624 ($tuples, $rows) = $sth->execute_array(\%attr) or die $sth->errstr; 5625 ($tuples, $rows) = $sth->execute_array(\%attr, @bind_values) or die $sth->errstr; 5626 5627 Execute the prepared statement once for each parameter tuple 5628 (group of values) provided either in the @bind_values, or by prior 5629 calls to L</bind_param_array>, or via a reference passed in \%attr. 5630 5631 When called in scalar context the execute_array() method returns the 5632 number of tuples executed, or C<undef> if an error occured. Like 5633 execute(), a successful execute_array() always returns true regardless 5634 of the number of tuples executed, even if it's zero. If there were any 5635 errors the ArrayTupleStatus array can be used to discover which tuples 5636 failed and with what errors. 5637 5638 When called in list context the execute_array() method returns two scalars; 5639 $tuples is the same as calling execute_array() in scalar context and $rows is 5640 the sum of the number of rows affected for each tuple, if available or 5641 -1 if the driver cannot determine this. 5642 If you are doing an update operation the returned rows affected may not be what 5643 you expect if, for instance, one or more of the tuples affected the same row 5644 multiple times. Some drivers may not yet support list context, in which case 5645 $rows will be undef, or may not be able to provide the number of rows affected 5646 when performing this batch operation, in which case $rows will be -1. 5647 5648 Bind values for the tuples to be executed may be supplied row-wise 5649 by an C<ArrayTupleFetch> attribute, or else column-wise in the 5650 C<@bind_values> argument, or else column-wise by prior calls to 5651 L</bind_param_array>. 5652 5653 Where column-wise binding is used (via the C<@bind_values> argument 5654 or calls to bind_param_array()) the maximum number of elements in 5655 any one of the bound value arrays determines the number of tuples 5656 executed. Placeholders with fewer values in their parameter arrays 5657 are treated as if padded with undef (NULL) values. 5658 5659 If a scalar value is bound, instead of an array reference, it is 5660 treated as a I<variable> length array with all elements having the 5661 same value. It's does not influence the number of tuples executed, 5662 so if all bound arrays have zero elements then zero tuples will 5663 be executed. If I<all> bound values are scalars then one tuple 5664 will be executed, making execute_array() act just like execute(). 5665 5666 The C<ArrayTupleFetch> attribute can be used to specify a reference 5667 to a subroutine that will be called to provide the bind values for 5668 each tuple execution. The subroutine should return an reference to 5669 an array which contains the appropriate number of bind values, or 5670 return an undef if there is no more data to execute. 5671 5672 As a convienience, the C<ArrayTupleFetch> attribute can also be 5673 used to specify a statement handle. In which case the fetchrow_arrayref() 5674 method will be called on the given statement handle in order to 5675 provide the bind values for each tuple execution. 5676 5677 The values specified via bind_param_array() or the @bind_values 5678 parameter may be either scalars, or arrayrefs. If any C<@bind_values> 5679 are given, then C<execute_array> will effectively call L</bind_param_array> 5680 for each value before executing the statement. Values bound in 5681 this way are usually treated as C<SQL_VARCHAR> types unless the 5682 driver can determine the correct type (which is rare), or unless 5683 C<bind_param>, C<bind_param_inout>, C<bind_param_array>, or 5684 C<bind_param_inout_array> has already been used to specify the type. 5685 See L</bind_param_array> for details. 5686 5687 The C<ArrayTupleStatus> attribute can be used to specify a 5688 reference to an array which will receive the execute status of each 5689 executed parameter tuple. Note the C<ArrayTupleStatus> attribute was 5690 mandatory until DBI 1.38. 5691 5692 For tuples which are successfully executed, the element at the same 5693 ordinal position in the status array is the resulting rowcount. 5694 If the execution of a tuple causes an error, then the corresponding 5695 status array element will be set to a reference to an array containing 5696 the error code and error string set by the failed execution. 5697 5698 If B<any> tuple execution returns an error, C<execute_array> will 5699 return C<undef>. In that case, the application should inspect the 5700 status array to determine which parameter tuples failed. 5701 Some databases may not continue executing tuples beyond the first 5702 failure. In this case the status array will either hold fewer 5703 elements, or the elements beyond the failure will be undef. 5704 5705 If all parameter tuples are successfully executed, C<execute_array> 5706 returns the number tuples executed. If no tuples were executed, 5707 then execute_array() returns "C<0E0>", just like execute() does, 5708 which Perl will treat as 0 but will regard as true. 5709 5710 For example: 5711 5712 $sth = $dbh->prepare("INSERT INTO staff (first_name, last_name) VALUES (?, ?)"); 5713 my $tuples = $sth->execute_array( 5714 { ArrayTupleStatus => \my @tuple_status }, 5715 \@first_names, 5716 \@last_names, 5717 ); 5718 if ($tuples) { 5719 print "Successfully inserted $tuples records\n"; 5720 } 5721 else { 5722 for my $tuple (0..@last_names-1) { 5723 my $status = $tuple_status[$tuple]; 5724 $status = [0, "Skipped"] unless defined $status; 5725 next unless ref $status; 5726 printf "Failed to insert (%s, %s): %s\n", 5727 $first_names[$tuple], $last_names[$tuple], $status->[1]; 5728 } 5729 } 5730 5731 Support for data returning statements such as SELECT is driver-specific 5732 and subject to change. At present, the default implementation 5733 provided by DBI only supports non-data returning statements. 5734 5735 Transaction semantics when using array binding are driver and 5736 database specific. If C<AutoCommit> is on, the default DBI 5737 implementation will cause each parameter tuple to be inidividually 5738 committed (or rolled back in the event of an error). If C<AutoCommit> 5739 is off, the application is responsible for explicitly committing 5740 the entire set of bound parameter tuples. Note that different 5741 drivers and databases may have different behaviours when some 5742 parameter tuples cause failures. In some cases, the driver or 5743 database may automatically rollback the effect of all prior parameter 5744 tuples that succeeded in the transaction; other drivers or databases 5745 may retain the effect of prior successfully executed parameter 5746 tuples. Be sure to check your driver and database for its specific 5747 behaviour. 5748 5749 Note that, in general, performance will usually be better with 5750 C<AutoCommit> turned off, and using explicit C<commit> after each 5751 C<execute_array> call. 5752 5753 The C<execute_array> method was added in DBI 1.22, and ArrayTupleFetch 5754 was added in 1.36. 5755 5756 =head3 C<execute_for_fetch> 5757 5758 $tuples = $sth->execute_for_fetch($fetch_tuple_sub); 5759 $tuples = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status); 5760 5761 ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub); 5762 ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status); 5763 5764 The execute_for_fetch() method is used to perform bulk operations 5765 and is most often used via the execute_array() method, not directly. 5766 5767 The fetch subroutine, referenced by $fetch_tuple_sub, is expected 5768 to return a reference to an array (known as a 'tuple') or undef. 5769 5770 The execute_for_fetch() method calls $fetch_tuple_sub, without any 5771 parameters, until it returns a false value. Each tuple returned is 5772 used to provide bind values for an $sth->execute(@$tuple) call. 5773 5774 In scalar context execute_for_fetch() returns C<undef> if there were any 5775 errors and the number of tuples executed otherwise. Like execute() and 5776 execute_array() a zero is returned as "0E0" so execute_for_fetch() is 5777 only false on error. If there were any errors the @tuple_status array 5778 can be used to discover which tuples failed and with what errors. 5779 5780 When called in list context execute_for_fetch() returns two scalars; 5781 $tuples is the same as calling execute_for_fetch() in scalar context and $rows is 5782 the sum of the number of rows affected for each tuple, if available or -1 5783 if the driver cannot determine this. 5784 If you are doing an update operation the returned rows affected may not be what 5785 you expect if, for instance, one or more of the tuples affected the same row 5786 multiple times. Some drivers may not yet support list context, in which case 5787 $rows will be undef, or may not be able to provide the number of rows affected 5788 when performing this batch operation, in which case $rows will be -1. 5789 5790 If \@tuple_status is passed then the execute_for_fetch method uses 5791 it to return status information. The tuple_status array holds one 5792 element per tuple. If the corresponding execute() did not fail then 5793 the element holds the return value from execute(), which is typically 5794 a row count. If the execute() did fail then the element holds a 5795 reference to an array containing ($sth->err, $sth->errstr, $sth->state). 5796 5797 If the driver detects an error that it knows means no further tuples can be 5798 executed then it may return, with an error status, even though $fetch_tuple_sub 5799 may still have more tuples to be executed. 5800 5801 Although each tuple returned by $fetch_tuple_sub is effectively used 5802 to call $sth->execute(@$tuple_array_ref) the exact timing may vary. 5803 Drivers are free to accumulate sets of tuples to pass to the 5804 database server in bulk group operations for more efficient execution. 5805 However, the $fetch_tuple_sub is specifically allowed to return 5806 the same array reference each time (which is what fetchrow_arrayref() 5807 usually does). 5808 5809 For example: 5810 5811 my $sel = $dbh1->prepare("select foo, bar from table1"); 5812 $sel->execute; 5813 5814 my $ins = $dbh2->prepare("insert into table2 (foo, bar) values (?,?)"); 5815 my $fetch_tuple_sub = sub { $sel->fetchrow_arrayref }; 5816 5817 my @tuple_status; 5818 $rc = $ins->execute_for_fetch($fetch_tuple_sub, \@tuple_status); 5819 my @errors = grep { ref $_ } @tuple_status; 5820 5821 Similarly, if you already have an array containing the data rows 5822 to be processed you'd use a subroutine to shift off and return 5823 each array ref in turn: 5824 5825 $ins->execute_for_fetch( sub { shift @array_of_arrays }, \@tuple_status); 5826 5827 The C<execute_for_fetch> method was added in DBI 1.38. 5828 5829 5830 =head3 C<fetchrow_arrayref> 5831 5832 $ary_ref = $sth->fetchrow_arrayref; 5833 $ary_ref = $sth->fetch; # alias 5834 5835 Fetches the next row of data and returns a reference to an array 5836 holding the field values. Null fields are returned as C<undef> 5837 values in the array. 5838 This is the fastest way to fetch data, particularly if used with 5839 C<$sth-E<gt>bind_columns>. 5840 5841 If there are no more rows or if an error occurs, then C<fetchrow_arrayref> 5842 returns an C<undef>. You should check C<$sth-E<gt>err> afterwards (or use the 5843 C<RaiseError> attribute) to discover if the C<undef> returned was due to an 5844 error. 5845 5846 Note that the same array reference is returned for each fetch, so don't 5847 store the reference and then use it after a later fetch. Also, the 5848 elements of the array are also reused for each row, so take care if you 5849 want to take a reference to an element. See also L</bind_columns>. 5850 5851 =head3 C<fetchrow_array> 5852 5853 @ary = $sth->fetchrow_array; 5854 5855 An alternative to C<fetchrow_arrayref>. Fetches the next row of data 5856 and returns it as a list containing the field values. Null fields 5857 are returned as C<undef> values in the list. 5858 5859 If there are no more rows or if an error occurs, then C<fetchrow_array> 5860 returns an empty list. You should check C<$sth-E<gt>err> afterwards (or use 5861 the C<RaiseError> attribute) to discover if the empty list returned was 5862 due to an error. 5863 5864 If called in a scalar context for a statement handle that has more 5865 than one column, it is undefined whether the driver will return 5866 the value of the first column or the last. So don't do that. 5867 Also, in a scalar context, an C<undef> is returned if there are no 5868 more rows or if an error occurred. That C<undef> can't be distinguished 5869 from an C<undef> returned because the first field value was NULL. 5870 For these reasons you should exercise some caution if you use 5871 C<fetchrow_array> in a scalar context. 5872 5873 =head3 C<fetchrow_hashref> 5874 5875 $hash_ref = $sth->fetchrow_hashref; 5876 $hash_ref = $sth->fetchrow_hashref($name); 5877 5878 An alternative to C<fetchrow_arrayref>. Fetches the next row of data 5879 and returns it as a reference to a hash containing field name and field 5880 value pairs. Null fields are returned as C<undef> values in the hash. 5881 5882 If there are no more rows or if an error occurs, then C<fetchrow_hashref> 5883 returns an C<undef>. You should check C<$sth-E<gt>err> afterwards (or use the 5884 C<RaiseError> attribute) to discover if the C<undef> returned was due to an 5885 error. 5886 5887 The optional C<$name> parameter specifies the name of the statement handle 5888 attribute. For historical reasons it defaults to "C<NAME>", however using either 5889 "C<NAME_lc>" or "C<NAME_uc>" is recomended for portability. 5890 5891 The keys of the hash are the same names returned by C<$sth-E<gt>{$name}>. If 5892 more than one field has the same name, there will only be one entry in 5893 the returned hash for those fields. 5894 5895 Because of the extra work C<fetchrow_hashref> and Perl have to perform, it 5896 is not as efficient as C<fetchrow_arrayref> or C<fetchrow_array>. 5897 5898 By default a reference to a new hash is returned for each row. 5899 It is likely that a future version of the DBI will support an 5900 attribute which will enable the same hash to be reused for each 5901 row. This will give a significant performance boost, but it won't 5902 be enabled by default because of the risk of breaking old code. 5903 5904 5905 =head3 C<fetchall_arrayref> 5906 5907 $tbl_ary_ref = $sth->fetchall_arrayref; 5908 $tbl_ary_ref = $sth->fetchall_arrayref( $slice ); 5909 $tbl_ary_ref = $sth->fetchall_arrayref( $slice, $max_rows ); 5910 5911 The C<fetchall_arrayref> method can be used to fetch all the data to be 5912 returned from a prepared and executed statement handle. It returns a 5913 reference to an array that contains one reference per row. 5914 5915 If there are no rows to return, C<fetchall_arrayref> returns a reference 5916 to an empty array. If an error occurs, C<fetchall_arrayref> returns the 5917 data fetched thus far, which may be none. You should check C<$sth-E<gt>err> 5918 afterwards (or use the C<RaiseError> attribute) to discover if the data is 5919 complete or was truncated due to an error. 5920 5921 If $slice is an array reference, C<fetchall_arrayref> uses L</fetchrow_arrayref> 5922 to fetch each row as an array ref. If the $slice array is not empty 5923 then it is used as a slice to select individual columns by perl array 5924 index number (starting at 0, unlike column and parameter numbers which 5925 start at 1). 5926 5927 With no parameters, or if $slice is undefined, C<fetchall_arrayref> 5928 acts as if passed an empty array ref. 5929 5930 If $slice is a hash reference, C<fetchall_arrayref> uses L</fetchrow_hashref> 5931 to fetch each row as a hash reference. If the $slice hash is empty then 5932 fetchrow_hashref() is simply called in a tight loop and the keys in the hashes 5933 have whatever name lettercase is returned by default from fetchrow_hashref. 5934 (See L</FetchHashKeyName> attribute.) If the $slice hash is not 5935 empty, then it is used as a slice to select individual columns by 5936 name. The values of the hash should be set to 1. The key names 5937 of the returned hashes match the letter case of the names in the 5938 parameter hash, regardless of the L</FetchHashKeyName> attribute. 5939 5940 For example, to fetch just the first column of every row: 5941 5942 $tbl_ary_ref = $sth->fetchall_arrayref([0]); 5943 5944 To fetch the second to last and last column of every row: 5945 5946 $tbl_ary_ref = $sth->fetchall_arrayref([-2,-1]); 5947 5948 To fetch all fields of every row as a hash ref: 5949 5950 $tbl_ary_ref = $sth->fetchall_arrayref({}); 5951 5952 To fetch only the fields called "foo" and "bar" of every row as a hash ref 5953 (with keys named "foo" and "BAR"): 5954 5955 $tbl_ary_ref = $sth->fetchall_arrayref({ foo=>1, BAR=>1 }); 5956 5957 The first two examples return a reference to an array of array refs. 5958 The third and forth return a reference to an array of hash refs. 5959 5960 If $max_rows is defined and greater than or equal to zero then it 5961 is used to limit the number of rows fetched before returning. 5962 fetchall_arrayref() can then be called again to fetch more rows. 5963 This is especially useful when you need the better performance of 5964 fetchall_arrayref() but don't have enough memory to fetch and return 5965 all the rows in one go. 5966 5967 Here's an example (assumes RaiseError is enabled): 5968 5969 my $rows = []; # cache for batches of rows 5970 while( my $row = ( shift(@$rows) || # get row from cache, or reload cache: 5971 shift(@{$rows=$sth->fetchall_arrayref(undef,10_000)||[]}) ) 5972 ) { 5973 ... 5974 } 5975 5976 That I<might> be the fastest way to fetch and process lots of rows using the DBI, 5977 but it depends on the relative cost of method calls vs memory allocation. 5978 5979 A standard C<while> loop with column binding is often faster because 5980 the cost of allocating memory for the batch of rows is greater than 5981 the saving by reducing method calls. It's possible that the DBI may 5982 provide a way to reuse the memory of a previous batch in future, which 5983 would then shift the balance back towards fetchall_arrayref(). 5984 5985 5986 =head3 C<fetchall_hashref> 5987 5988 $hash_ref = $sth->fetchall_hashref($key_field); 5989 5990 The C<fetchall_hashref> method can be used to fetch all the data to be 5991 returned from a prepared and executed statement handle. It returns a reference 5992 to a hash containing a key for each distinct value of the $key_field column 5993 that was fetched. For each key the corresponding value is a reference to a hash 5994 containing all the selected columns and their values, as returned by fetchrow_hashref(). 5995 5996 If there are no rows to return, C<fetchall_hashref> returns a reference 5997 to an empty hash. If an error occurs, C<fetchall_hashref> returns the 5998 data fetched thus far, which may be none. You should check 5999 C<$sth-E<gt>err> afterwards (or use the C<RaiseError> attribute) to 6000 discover if the data is complete or was truncated due to an error. 6001 6002 The $key_field parameter provides the name of the field that holds the 6003 value to be used for the key for the returned hash. For example: 6004 6005 $dbh->{FetchHashKeyName} = 'NAME_lc'; 6006 $sth = $dbh->prepare("SELECT FOO, BAR, ID, NAME, BAZ FROM TABLE"); 6007 $sth->execute; 6008 $hash_ref = $sth->fetchall_hashref('id'); 6009 print "Name for id 42 is $hash_ref->{42}->{name}\n"; 6010 6011 The $key_field parameter can also be specified as an integer column 6012 number (counting from 1). If $key_field doesn't match any column in 6013 the statement, as a name first then as a number, then an error is 6014 returned. 6015 6016 For queries returing more than one 'key' column, you can specify 6017 multiple column names by passing $key_field as a reference to an 6018 array containing one or more key column names (or index numbers). 6019 For example: 6020 6021 $sth = $dbh->prepare("SELECT foo, bar, baz FROM table"); 6022 $sth->execute; 6023 $hash_ref = $sth->fetchall_hashref( [ qw(foo bar) ] ); 6024 print "For foo 42 and bar 38, baz is $hash_ref->{42}->{38}->{baz}\n"; 6025 6026 The fetchall_hashref() method is normally used only where the key 6027 fields values for each row are unique. If multiple rows are returned 6028 with the same values for the key fields then later rows overwrite 6029 earlier ones. 6030 6031 =head3 C<finish> 6032 6033 $rc = $sth->finish; 6034 6035 Indicate that no more data will be fetched from this statement handle 6036 before it is either executed again or destroyed. The C<finish> method 6037 is rarely needed, and frequently overused, but can sometimes be 6038 helpful in a few very specific situations to allow the server to free 6039 up resources (such as sort buffers). 6040 6041 When all the data has been fetched from a C<SELECT> statement, the 6042 driver should automatically call C<finish> for you. So you should 6043 I<not> normally need to call it explicitly I<except> when you know 6044 that you've not fetched all the data from a statement handle. 6045 The most common example is when you only want to fetch one row, 6046 but in that case the C<selectrow_*> methods are usually better anyway. 6047 Adding calls to C<finish> after each fetch loop is a common mistake, 6048 don't do it, it can mask genuine problems like uncaught fetch errors. 6049 6050 Consider a query like: 6051 6052 SELECT foo FROM table WHERE bar=? ORDER BY foo 6053 6054 where you want to select just the first (smallest) "foo" value from a 6055 very large table. When executed, the database server will have to use 6056 temporary buffer space to store the sorted rows. If, after executing 6057 the handle and selecting one row, the handle won't be re-executed for 6058 some time and won't be destroyed, the C<finish> method can be used to tell 6059 the server that the buffer space can be freed. 6060 6061 Calling C<finish> resets the L</Active> attribute for the statement. It 6062 may also make some statement handle attributes (such as C<NAME> and C<TYPE>) 6063 unavailable if they have not already been accessed (and thus cached). 6064 6065 The C<finish> method does not affect the transaction status of the 6066 database connection. It has nothing to do with transactions. It's mostly an 6067 internal "housekeeping" method that is rarely needed. 6068 See also L</disconnect> and the L</Active> attribute. 6069 6070 The C<finish> method should have been called C<discard_pending_rows>. 6071 6072 6073 =head3 C<rows> 6074 6075 $rv = $sth->rows; 6076 6077 Returns the number of rows affected by the last row affecting command, 6078 or -1 if the number of rows is not known or not available. 6079 6080 Generally, you can only rely on a row count after a I<non>-C<SELECT> 6081 C<execute> (for some specific operations like C<UPDATE> and C<DELETE>), or 6082 after fetching all the rows of a C<SELECT> statement. 6083 6084 For C<SELECT> statements, it is generally not possible to know how many 6085 rows will be returned except by fetching them all. Some drivers will 6086 return the number of rows the application has fetched so far, but 6087 others may return -1 until all rows have been fetched. So use of the 6088 C<rows> method or C<$DBI::rows> with C<SELECT> statements is not 6089 recommended. 6090 6091 One alternative method to get a row count for a C<SELECT> is to execute a 6092 "SELECT COUNT(*) FROM ..." SQL statement with the same "..." as your 6093 query and then fetch the row count from that. 6094 6095 6096 =head3 C<bind_col> 6097 6098 $rc = $sth->bind_col($column_number, \$var_to_bind); 6099 $rc = $sth->bind_col($column_number, \$var_to_bind, \%attr ); 6100 $rc = $sth->bind_col($column_number, \$var_to_bind, $bind_type ); 6101 6102 Binds a Perl variable and/or some attributes to an output column 6103 (field) of a C<SELECT> statement. Column numbers count up from 1. 6104 You do not need to bind output columns in order to fetch data. 6105 For maximum portability between drivers, bind_col() should be called 6106 after execute() and not before. 6107 See also C<bind_columns> for an example. 6108 6109 The binding is performed at a low level using Perl aliasing. 6110 Whenever a row is fetched from the database $var_to_bind appears 6111 to be automatically updated simply because it now refers to the same 6112 memory location as the corresponding column value. This makes using 6113 bound variables very efficient. 6114 Binding a tied variable doesn't work, currently. 6115 6116 The L</bind_param> method 6117 performs a similar, but opposite, function for input variables. 6118 6119 B<Data Types for Column Binding> 6120 6121 The C<\%attr> parameter can be used to hint at the data type 6122 formatting the column should have. For example, you can use: 6123 6124 $sth->bind_col(1, undef, { TYPE => SQL_DATETIME }); 6125 6126 to specify that you'd like the column (which presumably is some 6127 kind of datetime type) to be returned in the standard format for 6128 SQL_DATETIME, which is 'YYYY-MM-DD HH:MM:SS', rather than the 6129 native formatting the database would normally use. 6130 6131 There's no $var_to_bind in that example to emphasize the point 6132 that bind_col() works on the underlying column value and not just 6133 a particular bound variable. 6134 6135 As a short-cut for the common case, the data type can be passed 6136 directly, in place of the C<\%attr> hash reference. This example is 6137 equivalent to the one above: 6138 6139 $sth->bind_col(1, undef, SQL_DATETIME); 6140 6141 The C<TYPE> value indicates the standard (non-driver-specific) type for 6142 this parameter. To specify the driver-specific type, the driver may 6143 support a driver-specific attribute, such as C<{ ora_type =E<gt> 97 }>. 6144 6145 The SQL_DATETIME and other related constants can be imported using 6146 6147 use DBI qw(:sql_types); 6148 6149 See L</"DBI Constants"> for more information. 6150 6151 The data type for a bind variable cannot be changed after the first 6152 C<bind_col> call. In fact the whole \%attr parameter is 'sticky' 6153 in the sense that a driver only needs to consider the \%attr parameter 6154 for the first call for a given $sth and column. 6155 6156 The TYPE attribute for bind_col() was first specified in DBI 1.41. 6157 6158 6159 =head3 C<bind_columns> 6160 6161 $rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind); 6162 6163 Calls L</bind_col> for each column of the C<SELECT> statement. 6164 6165 The list of references should have the same number of elements as the number of 6166 columns in the C<SELECT> statement. If it doesn't then C<bind_columns> will 6167 bind the elements given, upto the number of columns, and then return an error. 6168 6169 For maximum portability between drivers, bind_columns() should be called 6170 after execute() and not before. 6171 6172 For example: 6173 6174 $dbh->{RaiseError} = 1; # do this, or check every call for errors 6175 $sth = $dbh->prepare(q{ SELECT region, sales FROM sales_by_region }); 6176 $sth->execute; 6177 my ($region, $sales); 6178 6179 # Bind Perl variables to columns: 6180 $rv = $sth->bind_columns(\$region, \$sales); 6181 6182 # you can also use Perl's \(...) syntax (see perlref docs): 6183 # $sth->bind_columns(\($region, $sales)); 6184 6185 # Column binding is the most efficient way to fetch data 6186 while ($sth->fetch) { 6187 print "$region: $sales\n"; 6188 } 6189 6190 For compatibility with old scripts, the first parameter will be 6191 ignored if it is C<undef> or a hash reference. 6192 6193 Here's a more fancy example that binds columns to the values I<inside> 6194 a hash (thanks to H.Merijn Brand): 6195 6196 $sth->execute; 6197 my %row; 6198 $sth->bind_columns( \( @row{ @{$sth->{NAME_lc} } } )); 6199 while ($sth->fetch) { 6200 print "$row{region}: $row{sales}\n"; 6201 } 6202 6203 6204 =head3 C<dump_results> 6205 6206 $rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh); 6207 6208 Fetches all the rows from C<$sth>, calls C<DBI::neat_list> for each row, and 6209 prints the results to C<$fh> (defaults to C<STDOUT>) separated by C<$lsep> 6210 (default C<"\n">). C<$fsep> defaults to C<", "> and C<$maxlen> defaults to 35. 6211 6212 This method is designed as a handy utility for prototyping and 6213 testing queries. Since it uses L</neat_list> to 6214 format and edit the string for reading by humans, it is not recomended 6215 for data transfer applications. 6216 6217 6218 =head2 Statement Handle Attributes 6219 6220 This section describes attributes specific to statement handles. Most 6221 of these attributes are read-only. 6222 6223 Changes to these statement handle attributes do not affect any other 6224 existing or future statement handles. 6225 6226 Attempting to set or get the value of an unknown attribute generates a warning, 6227 except for private driver specific attributes (which all have names 6228 starting with a lowercase letter). 6229 6230 Example: 6231 6232 ... = $h->{NUM_OF_FIELDS}; # get/read 6233 6234 Some drivers cannot provide valid values for some or all of these 6235 attributes until after C<$sth-E<gt>execute> has been successfully 6236 called. Typically the attribute will be C<undef> in these situations. 6237 6238 Some attributes, like NAME, are not appropriate to some types of 6239 statement, like SELECT. Typically the attribute will be C<undef> 6240 in these situations. 6241 6242 For drivers which support stored procedures and multiple result sets 6243 (see L</more_results>) these attributes relate to the I<current> result set. 6244 6245 See also L</finish> to learn more about the effect it 6246 may have on some attributes. 6247 6248 =head3 C<NUM_OF_FIELDS> (integer, read-only) 6249 6250 Number of fields (columns) in the data the prepared statement may return. 6251 Statements that don't return rows of data, like C<DELETE> and C<CREATE> 6252 set C<NUM_OF_FIELDS> to 0 (though it may be undef in some drivers). 6253 6254 6255 =head3 C<NUM_OF_PARAMS> (integer, read-only) 6256 6257 The number of parameters (placeholders) in the prepared statement. 6258 See SUBSTITUTION VARIABLES below for more details. 6259 6260 6261 =head3 C<NAME> (array-ref, read-only) 6262 6263 Returns a reference to an array of field names for each column. The 6264 names may contain spaces but should not be truncated or have any 6265 trailing space. Note that the names have the letter case (upper, lower 6266 or mixed) as returned by the driver being used. Portable applications 6267 should use L</NAME_lc> or L</NAME_uc>. 6268 6269 print "First column name: $sth->{NAME}->[0]\n"; 6270 6271 =head3 C<NAME_lc> (array-ref, read-only) 6272 6273 Like L</NAME> but always returns lowercase names. 6274 6275 =head3 C<NAME_uc> (array-ref, read-only) 6276 6277 Like L</NAME> but always returns uppercase names. 6278 6279 =head3 C<NAME_hash> (hash-ref, read-only) 6280 6281 =head3 C<NAME_lc_hash> (hash-ref, read-only) 6282 6283 =head3 C<NAME_uc_hash> (hash-ref, read-only) 6284 6285 The C<NAME_hash>, C<NAME_lc_hash>, and C<NAME_uc_hash> attributes 6286 return column name information as a reference to a hash. 6287 6288 The keys of the hash are the names of the columns. The letter case of 6289 the keys corresponds to the letter case returned by the C<NAME>, 6290 C<NAME_lc>, and C<NAME_uc> attributes respectively (as described above). 6291 6292 The value of each hash entry is the perl index number of the 6293 corresponding column (counting from 0). For example: 6294 6295 $sth = $dbh->prepare("select Id, Name from table"); 6296 $sth->execute; 6297 @row = $sth->fetchrow_array; 6298 print "Name $row[ $sth->{NAME_lc_hash}{name} ]\n"; 6299 6300 6301 =head3 C<TYPE> (array-ref, read-only) 6302 6303 Returns a reference to an array of integer values for each 6304 column. The value indicates the data type of the corresponding column. 6305 6306 The values correspond to the international standards (ANSI X3.135 6307 and ISO/IEC 9075) which, in general terms, means ODBC. Driver-specific 6308 types that don't exactly match standard types should generally return 6309 the same values as an ODBC driver supplied by the makers of the 6310 database. That might include private type numbers in ranges the vendor 6311 has officially registered with the ISO working group: 6312 6313 ftp://sqlstandards.org/SC32/SQL_Registry/ 6314 6315 Where there's no vendor-supplied ODBC driver to be compatible with, 6316 the DBI driver can use type numbers in the range that is now 6317 officially reserved for use by the DBI: -9999 to -9000. 6318 6319 All possible values for C<TYPE> should have at least one entry in the 6320 output of the C<type_info_all> method (see L</type_info_all>). 6321 6322 =head3 C<PRECISION> (array-ref, read-only) 6323 6324 Returns a reference to an array of integer values for each column. 6325 6326 For numeric columns, the value is the maximum number of digits 6327 (without considering a sign character or decimal point). Note that 6328 the "display size" for floating point types (REAL, FLOAT, DOUBLE) 6329 can be up to 7 characters greater than the precision (for the 6330 sign + decimal point + the letter E + a sign + 2 or 3 digits). 6331 6332 For any character type column the value is the OCTET_LENGTH, 6333 in other words the number of bytes, not characters. 6334 6335 (More recent standards refer to this as COLUMN_SIZE but we stick 6336 with PRECISION for backwards compatibility.) 6337 6338 =head3 C<SCALE> (array-ref, read-only) 6339 6340 Returns a reference to an array of integer values for each column. 6341 NULL (C<undef>) values indicate columns where scale is not applicable. 6342 6343 =head3 C<NULLABLE> (array-ref, read-only) 6344 6345 Returns a reference to an array indicating the possibility of each 6346 column returning a null. Possible values are C<0> 6347 (or an empty string) = no, C<1> = yes, C<2> = unknown. 6348 6349 print "First column may return NULL\n" if $sth->{NULLABLE}->[0]; 6350 6351 6352 =head3 C<CursorName> (string, read-only) 6353 6354 Returns the name of the cursor associated with the statement handle, if 6355 available. If not available or if the database driver does not support the 6356 C<"where current of ..."> SQL syntax, then it returns C<undef>. 6357 6358 6359 =head3 C<Database> (dbh, read-only) 6360 6361 Returns the parent $dbh of the statement handle. 6362 6363 6364 =head3 C<ParamValues> (hash ref, read-only) 6365 6366 Returns a reference to a hash containing the values currently bound 6367 to placeholders. The keys of the hash are the 'names' of the 6368 placeholders, typically integers starting at 1. Returns undef if 6369 not supported by the driver. 6370 6371 See L</ShowErrorStatement> for an example of how this is used. 6372 6373 If the driver supports C<ParamValues> but no values have been bound 6374 yet then the driver should return a hash with placeholders names 6375 in the keys but all the values undef, but some drivers may return 6376 a ref to an empty hash. 6377 6378 It is possible that the values in the hash returned by C<ParamValues> 6379 are not I<exactly> the same as those passed to bind_param() or execute(). 6380 The driver may have slightly modified values in some way based on the 6381 TYPE the value was bound with. For example a floating point value 6382 bound as an SQL_INTEGER type may be returned as an integer. 6383 The values returned by C<ParamValues> can be passed to another 6384 bind_param() method with the same TYPE and will be seen by the 6385 database as the same value. 6386 6387 It is also possible that the keys in the hash returned by C<ParamValues> 6388 are not exactly the same as those implied by the prepared statement. 6389 For example, DBD::Oracle translates 'C<?>' placeholders into 'C<:pN>' 6390 where N is a sequence number starting at 1. 6391 6392 The C<ParamValues> attribute was added in DBI 1.28. 6393 6394 =head3 C<ParamArrays> (hash ref, read-only) 6395 6396 Returns a reference to a hash containing the values currently bound to 6397 placeholders with L</execute_array> or L</bind_param_array>. The 6398 keys of the hash are the 'names' of the placeholders, typically 6399 integers starting at 1. Returns undef if not supported by the driver 6400 or no arrays of parameters are bound. 6401 6402 Each key value is an array reference containing a list of the bound 6403 parameters for that column. 6404 6405 For example: 6406 6407 $sth = $dbh->prepare("INSERT INTO staff (id, name) values (?,?)"); 6408 $sth->execute_array({},[1,2], ['fred','dave']); 6409 if ($sth->{ParamArrays}) { 6410 foreach $param (keys %{$sth->{ParamArrays}}) { 6411 printf "Parameters for %s : %s\n", $param, 6412 join(",", @{$sth->{ParamArrays}->{$param}}); 6413 } 6414 } 6415 6416 It is possible that the values in the hash returned by C<ParamArrays> 6417 are not I<exactly> the same as those passed to L</bind_param_array> or 6418 L</execute_array>. The driver may have slightly modified values in some 6419 way based on the TYPE the value was bound with. For example a floating 6420 point value bound as an SQL_INTEGER type may be returned as an 6421 integer. 6422 6423 It is also possible that the keys in the hash returned by 6424 C<ParamArrays> are not exactly the same as those implied by the 6425 prepared statement. For example, DBD::Oracle translates 'C<?>' 6426 placeholders into 'C<:pN>' where N is a sequence number starting at 1. 6427 6428 =head3 C<ParamTypes> (hash ref, read-only) 6429 6430 Returns a reference to a hash containing the type information 6431 currently bound to placeholders. The keys of the hash are the 6432 'names' of the placeholders: either integers starting at 1, or, 6433 for drivers that support named placeholders, the actual parameter 6434 name string. The hash values are hashrefs of type information in 6435 the same form as that provided to the various bind_param() methods 6436 (See L</bind_param> for the format and values), 6437 plus anything else that was passed as the third argument to bind_param(). 6438 Returns undef if not supported by the driver. 6439 6440 If the driver supports C<ParamTypes>, but no values have been bound 6441 yet, then the driver should return a hash with the placeholder name 6442 keys, but all the values undef; however, some drivers may return 6443 a ref to an empty hash, or, alternately, may provide type 6444 information supplied by the database (only a few databases can do that). 6445 6446 It is possible that the values in the hash returned by C<ParamTypes> 6447 are not I<exactly> the same as those passed to bind_param() or execute(). 6448 The driver may have modified the type information in some way based 6449 on the bound values, other hints provided by the prepare()'d 6450 SQL statement, or alternate type mappings required by the driver or target 6451 database system. 6452 6453 It is also possible that the keys in the hash returned by C<ParamTypes> 6454 are not exactly the same as those implied by the prepared statement. 6455 For example, DBD::Oracle translates 'C<?>' placeholders into 'C<:pN>' 6456 where N is a sequence number starting at 1. 6457 6458 The C<ParamTypes> attribute was added in DBI 1.49. Implementation 6459 is the responsibility of individual drivers; the DBI layer default 6460 implementation simply returns undef. 6461 6462 6463 =head3 C<Statement> (string, read-only) 6464 6465 Returns the statement string passed to the L</prepare> method. 6466 6467 6468 =head3 C<RowsInCache> (integer, read-only) 6469 6470 If the driver supports a local row cache for C<SELECT> statements, then 6471 this attribute holds the number of un-fetched rows in the cache. If the 6472 driver doesn't, then it returns C<undef>. Note that some drivers pre-fetch 6473 rows on execute, whereas others wait till the first fetch. 6474 6475 See also the L</RowCacheSize> database handle attribute. 6476 6477 =head1 FURTHER INFORMATION 6478 6479 =head2 Catalog Methods 6480 6481 An application can retrieve metadata information from the DBMS by issuing 6482 appropriate queries on the views of the Information Schema. Unfortunately, 6483 C<INFORMATION_SCHEMA> views are seldom supported by the DBMS. 6484 Special methods (catalog methods) are available to return result sets 6485 for a small but important portion of that metadata: 6486 6487 column_info 6488 foreign_key_info 6489 primary_key_info 6490 table_info 6491 statistics_info 6492 6493 All catalog methods accept arguments in order to restrict the result sets. 6494 Passing C<undef> to an optional argument does not constrain the search for 6495 that argument. 6496 However, an empty string ('') is treated as a regular search criteria 6497 and will only match an empty value. 6498 6499 B<Note>: SQL/CLI and ODBC differ in the handling of empty strings. An 6500 empty string will not restrict the result set in SQL/CLI. 6501 6502 Most arguments in the catalog methods accept only I<ordinary values>, e.g. 6503 the arguments of C<primary_key_info()>. 6504 Such arguments are treated as a literal string, i.e. the case is significant 6505 and quote characters are taken literally. 6506 6507 Some arguments in the catalog methods accept I<search patterns> (strings 6508 containing '_' and/or '%'), e.g. the C<$table> argument of C<column_info()>. 6509 Passing '%' is equivalent to leaving the argument C<undef>. 6510 6511 B<Caveat>: The underscore ('_') is valid and often used in SQL identifiers. 6512 Passing such a value to a search pattern argument may return more rows than 6513 expected! 6514 To include pattern characters as literals, they must be preceded by an 6515 escape character which can be achieved with 6516 6517 $esc = $dbh->get_info( 14 ); # SQL_SEARCH_PATTERN_ESCAPE 6518 $search_pattern =~ s/([_%])/$esc$1/g; 6519 6520 The ODBC and SQL/CLI specifications define a way to change the default 6521 behaviour described above: All arguments (except I<list value arguments>) 6522 are treated as I<identifier> if the C<SQL_ATTR_METADATA_ID> attribute is 6523 set to C<SQL_TRUE>. 6524 I<Quoted identifiers> are very similar to I<ordinary values>, i.e. their 6525 body (the string within the quotes) is interpreted literally. 6526 I<Unquoted identifiers> are compared in UPPERCASE. 6527 6528 The DBI (currently) does not support the C<SQL_ATTR_METADATA_ID> attribute, 6529 i.e. it behaves like an ODBC driver where C<SQL_ATTR_METADATA_ID> is set to 6530 C<SQL_FALSE>. 6531 6532 6533 =head2 Transactions 6534 6535 Transactions are a fundamental part of any robust database system. They 6536 protect against errors and database corruption by ensuring that sets of 6537 related changes to the database take place in atomic (indivisible, 6538 all-or-nothing) units. 6539 6540 This section applies to databases that support transactions and where 6541 C<AutoCommit> is off. See L</AutoCommit> for details of using C<AutoCommit> 6542 with various types of databases. 6543 6544 The recommended way to implement robust transactions in Perl 6545 applications is to use C<RaiseError> and S<C<eval { ... }>> 6546 (which is very fast, unlike S<C<eval "...">>). For example: 6547 6548 $dbh->{AutoCommit} = 0; # enable transactions, if possible 6549 $dbh->{RaiseError} = 1; 6550 eval { 6551 foo(...) # do lots of work here 6552 bar(...) # including inserts 6553 baz(...) # and updates 6554 $dbh->commit; # commit the changes if we get this far 6555 }; 6556 if ($@) { 6557 warn "Transaction aborted because $@"; 6558 # now rollback to undo the incomplete changes 6559 # but do it in an eval{} as it may also fail 6560 eval { $dbh->rollback }; 6561 # add other application on-error-clean-up code here 6562 } 6563 6564 If the C<RaiseError> attribute is not set, then DBI calls would need to be 6565 manually checked for errors, typically like this: 6566 6567 $h->method(@args) or die $h->errstr; 6568 6569 With C<RaiseError> set, the DBI will automatically C<die> if any DBI method 6570 call on that handle (or a child handle) fails, so you don't have to 6571 test the return value of each method call. See L</RaiseError> for more 6572 details. 6573 6574 A major advantage of the C<eval> approach is that the transaction will be 6575 properly rolled back if I<any> code (not just DBI calls) in the inner 6576 application dies for any reason. The major advantage of using the 6577 C<$h-E<gt>{RaiseError}> attribute is that all DBI calls will be checked 6578 automatically. Both techniques are strongly recommended. 6579 6580 After calling C<commit> or C<rollback> many drivers will not let you 6581 fetch from a previously active C<SELECT> statement handle that's a child 6582 of the same database handle. A typical way round this is to connect the 6583 the database twice and use one connection for C<SELECT> statements. 6584 6585 See L</AutoCommit> and L</disconnect> for other important information 6586 about transactions. 6587 6588 6589 =head2 Handling BLOB / LONG / Memo Fields 6590 6591 Many databases support "blob" (binary large objects), "long", or similar 6592 datatypes for holding very long strings or large amounts of binary 6593 data in a single field. Some databases support variable length long 6594 values over 2,000,000,000 bytes in length. 6595 6596 Since values of that size can't usually be held in memory, and because 6597 databases can't usually know in advance the length of the longest long 6598 that will be returned from a C<SELECT> statement (unlike other data 6599 types), some special handling is required. 6600 6601 In this situation, the value of the C<$h-E<gt>{LongReadLen}> 6602 attribute is used to determine how much buffer space to allocate 6603 when fetching such fields. The C<$h-E<gt>{LongTruncOk}> attribute 6604 is used to determine how to behave if a fetched value can't fit 6605 into the buffer. 6606 6607 See the description of L</LongReadLen> for more information. 6608 6609 When trying to insert long or binary values, placeholders should be used 6610 since there are often limits on the maximum size of an C<INSERT> 6611 statement and the L</quote> method generally can't cope with binary 6612 data. See L</Placeholders and Bind Values>. 6613 6614 6615 =head2 Simple Examples 6616 6617 Here's a complete example program to select and fetch some data: 6618 6619 my $data_source = "dbi::DriverName:db_name"; 6620 my $dbh = DBI->connect($data_source, $user, $password) 6621 or die "Can't connect to $data_source: $DBI::errstr"; 6622 6623 my $sth = $dbh->prepare( q{ 6624 SELECT name, phone 6625 FROM mytelbook 6626 }) or die "Can't prepare statement: $DBI::errstr"; 6627 6628 my $rc = $sth->execute 6629 or die "Can't execute statement: $DBI::errstr"; 6630 6631 print "Query will return $sth->{NUM_OF_FIELDS} fields.\n\n"; 6632 print "Field names: @{ $sth->{NAME} }\n"; 6633 6634 while (($name, $phone) = $sth->fetchrow_array) { 6635 print "$name: $phone\n"; 6636 } 6637 # check for problems which may have terminated the fetch early 6638 die $sth->errstr if $sth->err; 6639 6640 $dbh->disconnect; 6641 6642 Here's a complete example program to insert some data from a file. 6643 (This example uses C<RaiseError> to avoid needing to check each call). 6644 6645 my $dbh = DBI->connect("dbi:DriverName:db_name", $user, $password, { 6646 RaiseError => 1, AutoCommit => 0 6647 }); 6648 6649 my $sth = $dbh->prepare( q{ 6650 INSERT INTO table (name, phone) VALUES (?, ?) 6651 }); 6652 6653 open FH, "<phone.csv" or die "Unable to open phone.csv: $!"; 6654 while (<FH>) { 6655 chomp; 6656 my ($name, $phone) = split /,/; 6657 $sth->execute($name, $phone); 6658 } 6659 close FH; 6660 6661 $dbh->commit; 6662 $dbh->disconnect; 6663 6664 Here's how to convert fetched NULLs (undefined values) into empty strings: 6665 6666 while($row = $sth->fetchrow_arrayref) { 6667 # this is a fast and simple way to deal with nulls: 6668 foreach (@$row) { $_ = '' unless defined } 6669 print "@$row\n"; 6670 } 6671 6672 The C<q{...}> style quoting used in these examples avoids clashing with 6673 quotes that may be used in the SQL statement. Use the double-quote like 6674 C<qq{...}> operator if you want to interpolate variables into the string. 6675 See L<perlop/"Quote and Quote-like Operators"> for more details. 6676 6677 =head2 Threads and Thread Safety 6678 6679 Perl 5.7 and later support a new threading model called iThreads. 6680 (The old "5.005 style" threads are not supported by the DBI.) 6681 6682 In the iThreads model each thread has it's own copy of the perl 6683 interpreter. When a new thread is created the original perl 6684 interpreter is 'cloned' to create a new copy for the new thread. 6685 6686 If the DBI and drivers are loaded and handles created before the 6687 thread is created then it will get a cloned copy of the DBI, the 6688 drivers and the handles. 6689 6690 However, the internal pointer data within the handles will refer 6691 to the DBI and drivers in the original interpreter. Using those 6692 handles in the new interpreter thread is not safe, so the DBI detects 6693 this and croaks on any method call using handles that don't belong 6694 to the current thread (except for DESTROY). 6695 6696 Because of this (possibly temporary) restriction, newly created 6697 threads must make their own connctions to the database. Handles 6698 can't be shared across threads. 6699 6700 But BEWARE, some underlying database APIs (the code the DBD driver 6701 uses to talk to the database, often supplied by the database vendor) 6702 are not thread safe. If it's not thread safe, then allowing more 6703 than one thread to enter the code at the same time may cause 6704 subtle/serious problems. In some cases allowing more than 6705 one thread to enter the code, even if I<not> at the same time, 6706 can cause problems. You have been warned. 6707 6708 Using DBI with perl threads is not yet recommended for production 6709 environments. For more information see 6710 L<http://www.perlmonks.org/index.pl?node_id=288022> 6711 6712 Note: There is a bug in perl 5.8.2 when configured with threads 6713 and debugging enabled (bug #24463) which causes a DBI test to fail. 6714 6715 =head2 Signal Handling and Canceling Operations 6716 6717 [The following only applies to systems with unix-like signal handling. 6718 I'd welcome additions for other systems, especially Windows.] 6719 6720 The first thing to say is that signal handling in Perl versions less 6721 than 5.8 is I<not> safe. There is always a small risk of Perl 6722 crashing and/or core dumping when, or after, handling a signal 6723 because the signal could arrive and be handled while internal data 6724 structures are being changed. If the signal handling code 6725 used those same internal data structures it could cause all manner 6726 of subtle and not-so-subtle problems. The risk was reduced with 6727 5.4.4 but was still present in all perls up through 5.8.0. 6728 6729 Beginning in perl 5.8.0 perl implements 'safe' signal handling if 6730 your system has the POSIX sigaction() routine. Now when a signal 6731 is delivered perl just makes a note of it but does I<not> run the 6732 %SIG handler. The handling is 'defered' until a 'safe' moment. 6733 6734 Although this change made signal handling safe, it also lead to 6735 a problem with signals being defered for longer than you'd like. 6736 If a signal arrived while executing a system call, such as waiting 6737 for data on a network connection, the signal is noted and then the 6738 system call that was executing returns with an EINTR error code 6739 to indicate that it was interrupted. All fine so far. 6740 6741 The problem comes when the code that made the system call sees the 6742 EINTR code and decides it's going to call it again. Perl doesn't 6743 do that, but database code sometimes does. If that happens then the 6744 signal handler doesn't get called untill later. Maybe much later. 6745 6746 Fortunately there are ways around this which we'll discuss below. 6747 Unfortunately they make signals unsafe again. 6748 6749 The two most common uses of signals in relation to the DBI are for 6750 canceling operations when the user types Ctrl-C (interrupt), and for 6751 implementing a timeout using C<alarm()> and C<$SIG{ALRM}>. 6752 6753 =over 4 6754 6755 =item Cancel 6756 6757 The DBI provides a C<cancel> method for statement handles. The 6758 C<cancel> method should abort the current operation and is designed 6759 to be called from a signal handler. For example: 6760 6761 $SIG{INT} = sub { $sth->cancel }; 6762 6763 However, few drivers implement this (the DBI provides a default 6764 method that just returns C<undef>) and, even if implemented, there 6765 is still a possibility that the statement handle, and even the 6766 parent database handle, will not be usable afterwards. 6767 6768 If C<cancel> returns true, then it has successfully 6769 invoked the database engine's own cancel function. If it returns false, 6770 then C<cancel> failed. If it returns C<undef>, then the database 6771 driver does not have cancel implemented - very few do. 6772 6773 =item Timeout 6774 6775 The traditional way to implement a timeout is to set C<$SIG{ALRM}> 6776 to refer to some code that will be executed when an ALRM signal 6777 arrives and then to call alarm($seconds) to schedule an ALRM signal 6778 to be delivered $seconds in the future. For example: 6779 6780 eval { 6781 local $SIG{ALRM} = sub { die "TIMEOUT\n" }; 6782 alarm($seconds); 6783 ... code to execute with timeout here ... 6784 alarm(0); # cancel alarm (if code ran fast) 6785 }; 6786 alarm(0); # cancel alarm (if eval failed) 6787 if ( $@ eq "TIMEOUT\n" ) { ... } 6788 6789 Unfortunately, as described above, this won't always work as expected, 6790 depending on your perl version and the underlying database code. 6791 6792 With Oracle for instance (DBD::Oracle), if the system which hosts 6793 the database is down the DBI->connect() call will hang for several 6794 minutes before returning an error. 6795 6796 =back 6797 6798 The solution on these systems is to use the C<POSIX::sigaction()> 6799 routine to gain low level access to how the signal handler is installed. 6800 6801 The code would look something like this (for the DBD-Oracle connect()): 6802 6803 use POSIX ':signal_h'; 6804 6805 my $mask = POSIX::SigSet->new( SIGALRM ); # signals to mask in the handler 6806 my $action = POSIX::SigAction->new( 6807 sub { die "connect timeout" }, # the handler code ref 6808 $mask, 6809 # not using (perl 5.8.2 and later) 'safe' switch or sa_flags 6810 ); 6811 my $oldaction = POSIX::SigAction->new(); 6812 sigaction( 'ALRM', $action, $oldaction ); 6813 my $dbh; 6814 eval { 6815 alarm(5); # seconds before time out 6816 $dbh = DBI->connect("dbi:Oracle:$dsn" ... ); 6817 alarm(0); # cancel alarm (if connect worked fast) 6818 }; 6819 alarm(0); # cancel alarm (if eval failed) 6820 sigaction( 'ALRM', $oldaction ); # restore original signal handler 6821 if ( $@ ) .... 6822 6823 Similar techniques can be used for canceling statement execution. 6824 6825 Unfortunately, this solution is somewhat messy, and it does I<not> work with 6826 perl versions less than perl 5.8 where C<POSIX::sigaction()> appears to be broken. 6827 6828 For a cleaner implementation that works across perl versions, see Lincoln Baxter's 6829 Sys::SigAction module at L<http://search.cpan.org/~lbaxter/Sys-SigAction/>. 6830 The documentation for Sys::SigAction includes an longer discussion 6831 of this problem, and a DBD::Oracle test script. 6832 6833 Be sure to read all the signal handling sections of the L<perlipc> manual. 6834 6835 And finally, two more points to keep firmly in mind. Firstly, 6836 remember that what we've done here is essentially revert to old 6837 style I<unsafe> handling of these signals. So do as little as 6838 possible in the handler. Ideally just die(). Secondly, the handles 6839 in use at the time the signal is handled may not be safe to use 6840 afterwards. 6841 6842 6843 =head2 Subclassing the DBI 6844 6845 DBI can be subclassed and extended just like any other object 6846 oriented module. Before we talk about how to do that, it's important 6847 to be clear about the various DBI classes and how they work together. 6848 6849 By default C<$dbh = DBI-E<gt>connect(...)> returns a $dbh blessed 6850 into the C<DBI::db> class. And the C<$dbh-E<gt>prepare> method 6851 returns an $sth blessed into the C<DBI::st> class (actually it 6852 simply changes the last four characters of the calling handle class 6853 to be C<::st>). 6854 6855 The leading 'C<DBI>' is known as the 'root class' and the extra 6856 'C<::db>' or 'C<::st>' are the 'handle type suffixes'. If you want 6857 to subclass the DBI you'll need to put your overriding methods into 6858 the appropriate classes. For example, if you want to use a root class 6859 of C<MySubDBI> and override the do(), prepare() and execute() methods, 6860 then your do() and prepare() methods should be in the C<MySubDBI::db> 6861 class and the execute() method should be in the C<MySubDBI::st> class. 6862 6863 To setup the inheritance hierarchy the @ISA variable in C<MySubDBI::db> 6864 should include C<DBI::db> and the @ISA variable in C<MySubDBI::st> 6865 should include C<DBI::st>. The C<MySubDBI> root class itself isn't 6866 currently used for anything visible and so, apart from setting @ISA 6867 to include C<DBI>, it can be left empty. 6868 6869 So, having put your overriding methods into the right classes, and 6870 setup the inheritance hierarchy, how do you get the DBI to use them? 6871 You have two choices, either a static method call using the name 6872 of your subclass: 6873 6874 $dbh = MySubDBI->connect(...); 6875 6876 or specifying a C<RootClass> attribute: 6877 6878 $dbh = DBI->connect(..., { RootClass => 'MySubDBI' }); 6879 6880 If both forms are used then the attribute takes precedence. 6881 6882 The only differences between the two are that using an explicit 6883 RootClass attribute will a) make the DBI automatically attempt to load 6884 a module by that name if the class doesn't exist, and b) won't call 6885 your MySubDBI::connect() method, if you have one. 6886 6887 When subclassing is being used then, after a successful new 6888 connect, the DBI->connect method automatically calls: 6889 6890 $dbh->connected($dsn, $user, $pass, \%attr); 6891 6892 The default method does nothing. The call is made just to simplify 6893 any post-connection setup that your subclass may want to perform. 6894 The parameters are the same as passed to DBI->connect. 6895 If your subclass supplies a connected method, it should be part of the 6896 MySubDBI::db package. 6897 6898 One more thing to note: you must let the DBI do the handle creation. If you 6899 want to override the connect() method in your *::dr class then it must still 6900 call SUPER::connect to get a $dbh to work with. Similarly, an overridden 6901 prepare() method in *::db must still call SUPER::prepare to get a $sth. 6902 If you try to create your own handles using bless() then you'll find the DBI 6903 will reject them with an "is not a DBI handle (has no magic)" error. 6904 6905 Here's a brief example of a DBI subclass. A more thorough example 6906 can be found in F<t/subclass.t> in the DBI distribution. 6907 6908 package MySubDBI; 6909 6910 use strict; 6911 6912 use DBI; 6913 use vars qw(@ISA); 6914 @ISA = qw(DBI); 6915 6916 package MySubDBI::db; 6917 use vars qw(@ISA); 6918 @ISA = qw(DBI::db); 6919 6920 sub prepare { 6921 my ($dbh, @args) = @_; 6922 my $sth = $dbh->SUPER::prepare(@args) 6923 or return; 6924 $sth->{private_mysubdbi_info} = { foo => 'bar' }; 6925 return $sth; 6926 } 6927 6928 package MySubDBI::st; 6929 use vars qw(@ISA); 6930 @ISA = qw(DBI::st); 6931 6932 sub fetch { 6933 my ($sth, @args) = @_; 6934 my $row = $sth->SUPER::fetch(@args) 6935 or return; 6936 do_something_magical_with_row_data($row) 6937 or return $sth->set_err(1234, "The magic failed", undef, "fetch"); 6938 return $row; 6939 } 6940 6941 When calling a SUPER::method that returns a handle, be careful to 6942 check the return value before trying to do other things with it in 6943 your overridden method. This is especially important if you want to 6944 set a hash attribute on the handle, as Perl's autovivification will 6945 bite you by (in)conveniently creating an unblessed hashref, which your 6946 method will then return with usually baffling results later on like 6947 the error "dbih_getcom handle HASH(0xa4451a8) is not a DBI handle (has 6948 no magic". It's best to check right after the call and return undef 6949 immediately on error, just like DBI would and just like the example 6950 above. 6951 6952 If your method needs to record an error it should call the set_err() 6953 method with the error code and error string, as shown in the example 6954 above. The error code and error string will be recorded in the 6955 handle and available via C<$h-E<gt>err> and C<$DBI::errstr> etc. 6956 The set_err() method always returns an undef or empty list as 6957 approriate. Since your method should nearly always return an undef 6958 or empty list as soon as an error is detected it's handy to simply 6959 return what set_err() returns, as shown in the example above. 6960 6961 If the handle has C<RaiseError>, C<PrintError>, or C<HandleError> 6962 etc. set then the set_err() method will honour them. This means 6963 that if C<RaiseError> is set then set_err() won't return in the 6964 normal way but will 'throw an exception' that can be caught with 6965 an C<eval> block. 6966 6967 You can stash private data into DBI handles 6968 via C<$h-E<gt>{private_..._*}>. See the entry under L</ATTRIBUTES 6969 COMMON TO ALL HANDLES> for info and important caveats. 6970 6971 6972 =head1 TRACING 6973 6974 The DBI has a powerful tracing mechanism built in. It enables you 6975 to see what's going on 'behind the scenes', both within the DBI and 6976 the drivers you're using. 6977 6978 =head2 Trace Settings 6979 6980 Which details are written to the trace output is controlled by a 6981 combination of a I<trace level>, an integer from 0 to 15, and a set 6982 of I<trace flags> that are either on or off. Together these are known 6983 as the I<trace settings> and are stored together in a single integer. 6984 For normal use you only need to set the trace level, and generally 6985 only to a value between 1 and 4. 6986 6987 Each handle has it's own trace settings, and so does the DBI. 6988 When you call a method the DBI merges the handles settings into its 6989 own for the duration of the call: the trace flags of the handle are 6990 OR'd into the trace flags of the DBI, and if the handle has a higher 6991 trace level then the DBI trace level is raised to match it. 6992 The previous DBI trace setings are restored when the called method 6993 returns. 6994 6995 =head2 Trace Levels 6996 6997 Trace I<levels> are as follows: 6998 6999 0 - Trace disabled. 7000 1 - Trace top-level DBI method calls returning with results or errors. 7001 2 - As above, adding tracing of top-level method entry with parameters. 7002 3 - As above, adding some high-level information from the driver 7003 and some internal information from the DBI. 7004 4 - As above, adding more detailed information from the driver. 7005 This is the first level to trace all the rows being fetched. 7006 5 to 15 - As above but with more and more internal information. 7007 7008 Trace level 1 is best for a simple overview of what's happening. 7009 Trace levels 2 thru 4 a good choice for general purpose tracing. 7010 Levels 5 and above are best reserved for investigating a specific 7011 problem, when you need to see "inside" the driver and DBI. 7012 7013 The trace output is detailed and typically very useful. Much of the 7014 trace output is formatted using the L</neat> function, so strings 7015 in the trace output may be edited and truncated by that function. 7016 7017 =head2 Trace Flags 7018 7019 Trace I<flags> are used to enable tracing of specific activities 7020 within the DBI and drivers. The DBI defines some trace flags and 7021 drivers can define others. DBI trace flag names begin with a capital 7022 letter and driver specific names begin with a lowercase letter, as 7023 usual. 7024 7025 Curently the DBI only defines two trace flags: 7026 7027 ALL - turn on all DBI and driver flags (not recommended) 7028 SQL - trace SQL statements executed (not yet implemented) 7029 7030 The L</parse_trace_flags> and L</parse_trace_flag> methods are used 7031 to convert trace flag names into the coresponding integer bit flags. 7032 7033 =head2 Enabling Trace 7034 7035 The C<$h-E<gt>trace> method sets the trace settings for a handle 7036 and C<DBI-E<gt>trace> does the same for the DBI. 7037 7038 In addition to the L</trace> method, you can enable the same trace 7039 information, and direct the output to a file, by setting the 7040 C<DBI_TRACE> environment variable before starting Perl. 7041 See L</DBI_TRACE> for more information. 7042 7043 Finally, you can set, or get, the trace settings for a handle using 7044 the C<TraceLevel> attribute. 7045 7046 All of those methods use parse_trace_flags() and so allow you set 7047 both the trace level and multiple trace flags by using a string 7048 containing the trace level and/or flag names separated by vertical 7049 bar ("C<|>") or comma ("C<,>") characters. For example: 7050 7051 local $h->{TraceLevel} = "3|SQL|foo"; 7052 7053 =head2 Trace Output 7054 7055 Initially trace output is written to C<STDERR>. Both the 7056 C<$h-E<gt>trace> and C<DBI-E<gt>trace> methods take an optional 7057 $trace_file parameter, which may be either the name of a file to be 7058 openned by DBI in append mode, or a reference to an existing writable 7059 (possibly layered) filehandle. If $trace_file is a filename, 7060 and can be opened in append mode, or $trace_file is a writable 7061 filehandle, then I<all> trace output (currently including that from 7062 other handles) is redirected to that file. A warning is generated 7063 if $trace_file can't be opened or is not writable. 7064 7065 Further calls to trace() without $trace_file do not alter where 7066 the trace output is sent. If $trace_file is undefined, then 7067 trace output is sent to C<STDERR> and, if the prior trace was openned with 7068 $trace_file as a filename, the previous trace file is closed; if $trace_file was 7069 a filehandle, the filehandle is B<not> closed. 7070 7071 B<NOTE>: If $trace_file is specified as a filehandle, the filehandle 7072 should not be closed until all DBI operations are completed, or the 7073 application has reset the trace file via another call to 7074 C<trace()> that changes the trace file. 7075 7076 =head2 Tracing to Layered Filehandles 7077 7078 B<NOTE>: 7079 7080 =over 4 7081 7082 =item * 7083 Tied filehandles are not currently supported, as 7084 tie operations are not available to the PerlIO 7085 methods used by the DBI. 7086 7087 =item * 7088 PerlIO layer support requires Perl version 5.8 or higher. 7089 7090 =back 7091 7092 As of version 5.8, Perl provides the ability to layer various 7093 "disciplines" on an open filehandle via the L<PerlIO> module. 7094 7095 A simple example of using PerlIO layers is to use a scalar as the output: 7096 7097 my $scalar = ''; 7098 open( my $fh, "+>:scalar", \$scalar ); 7099 $dbh->trace( 2, $fh ); 7100 7101 Now all trace output is simply appended to $scalar. 7102 7103 A more complex application of tracing to a layered filehandle is the 7104 use of a custom layer (I<Refer to >L<Perlio::via> I<for details 7105 on creating custom PerlIO layers.>). Consider an application with the 7106 following logger module: 7107 7108 package MyFancyLogger; 7109 7110 sub new 7111 { 7112 my $self = {}; 7113 my $fh; 7114 open $fh, '>', 'fancylog.log'; 7115 $self->{_fh} = $fh; 7116 $self->{_buf} = ''; 7117 return bless $self, shift; 7118 } 7119 7120 sub log 7121 { 7122 my $self = shift; 7123 return unless exists $self->{_fh}; 7124 my $fh = $self->{_fh}; 7125 $self->{_buf} .= shift; 7126 # 7127 # DBI feeds us pieces at a time, so accumulate a complete line 7128 # before outputing 7129 # 7130 print $fh "At ", scalar localtime(), ':', $self->{_buf}, "\n" and 7131 $self->{_buf} = '' 7132 if $self->{_buf}=~tr/\n//; 7133 } 7134 7135 sub close { 7136 my $self = shift; 7137 return unless exists $self->{_fh}; 7138 my $fh = $self->{_fh}; 7139 print $fh "At ", scalar localtime(), ':', $self->{_buf}, "\n" and 7140 $self->{_buf} = '' 7141 if $self->{_buf}; 7142 close $fh; 7143 delete $self->{_fh}; 7144 } 7145 7146 1; 7147 7148 To redirect DBI traces to this logger requires creating 7149 a package for the layer: 7150 7151 package PerlIO::via::MyFancyLogLayer; 7152 7153 sub PUSHED 7154 { 7155 my ($class,$mode,$fh) = @_; 7156 my $logger; 7157 return bless \$logger,$class; 7158 } 7159 7160 sub OPEN { 7161 my ($self, $path, $mode, $fh) = @_; 7162 # 7163 # $path is actually our logger object 7164 # 7165 $$self = $path; 7166 return 1; 7167 } 7168 7169 sub WRITE 7170 { 7171 my ($self, $buf, $fh) = @_; 7172 $$self->log($buf); 7173 return length($buf); 7174 } 7175 7176 sub CLOSE { 7177 my $self = shift; 7178 $$self->close(); 7179 return 0; 7180 } 7181 7182 1; 7183 7184 7185 The application can then cause DBI traces to be routed to the 7186 logger using 7187 7188 use PerlIO::via::MyFancyLogLayer; 7189 7190 open my $fh, '>:via(MyFancyLogLayer)', MyFancyLogger->new(); 7191 7192 $dbh->trace('SQL', $fh); 7193 7194 Now all trace output will be processed by MyFancyLogger's 7195 log() method. 7196 7197 =head2 Trace Content 7198 7199 Many of the values embeded in trace output are formatted using the neat() 7200 utility function. This means they may be quoted, sanitized, and possibly 7201 truncated if longer than C<$DBI::neat_maxlen>. See L</neat> for more details. 7202 7203 =head2 Tracing Tips 7204 7205 You can add tracing to your own application code using the L</trace_msg> method. 7206 7207 It can sometimes be handy to compare trace files from two different runs of the 7208 same script. However using a tool like C<diff> on the original log output 7209 doesn't work well because the trace file is full of object addresses that may 7210 differ on each run. 7211 7212 The DBI includes a handy utility called dbilogstrip that can be used to 7213 'normalize' the log content. It can be used as a filter like this: 7214 7215 DBI_TRACE=2 perl yourscript.pl ...args1... 2>&1 | dbilogstrip > dbitrace1.log 7216 DBI_TRACE=2 perl yourscript.pl ...args2... 2>&1 | dbilogstrip > dbitrace2.log 7217 diff -u dbitrace1.log dbitrace2.log 7218 7219 See L<dbilogstrip> for more information. 7220 7221 =head1 DBI ENVIRONMENT VARIABLES 7222 7223 The DBI module recognizes a number of environment variables, but most of 7224 them should not be used most of the time. 7225 It is better to be explicit about what you are doing to avoid the need 7226 for environment variables, especially in a web serving system where web 7227 servers are stingy about which environment variables are available. 7228 7229 =head2 DBI_DSN 7230 7231 The DBI_DSN environment variable is used by DBI->connect if you do not 7232 specify a data source when you issue the connect. 7233 It should have a format such as "dbi:Driver:databasename". 7234 7235 =head2 DBI_DRIVER 7236 7237 The DBI_DRIVER environment variable is used to fill in the database 7238 driver name in DBI->connect if the data source string starts "dbi::" 7239 (thereby omitting the driver). 7240 If DBI_DSN omits the driver name, DBI_DRIVER can fill the gap. 7241 7242 =head2 DBI_AUTOPROXY 7243 7244 The DBI_AUTOPROXY environment variable takes a string value that starts 7245 "dbi:Proxy:" and is typically followed by "hostname=...;port=...". 7246 It is used to alter the behaviour of DBI->connect. 7247 For full details, see DBI::Proxy documentation. 7248 7249 =head2 DBI_USER 7250 7251 The DBI_USER environment variable takes a string value that is used as 7252 the user name if the DBI->connect call is given undef (as distinct from 7253 an empty string) as the username argument. 7254 Be wary of the security implications of using this. 7255 7256 =head2 DBI_PASS 7257 7258 The DBI_PASS environment variable takes a string value that is used as 7259 the password if the DBI->connect call is given undef (as distinct from 7260 an empty string) as the password argument. 7261 Be extra wary of the security implications of using this. 7262 7263 =head2 DBI_DBNAME (obsolete) 7264 7265 The DBI_DBNAME environment variable takes a string value that is used only when the 7266 obsolescent style of DBI->connect (with driver name as fourth parameter) is used, and 7267 when no value is provided for the first (database name) argument. 7268 7269 =head2 DBI_TRACE 7270 7271 The DBI_TRACE environment variable specifies the global default 7272 trace settings for the DBI at startup. Can also be used to direct 7273 trace output to a file. When the DBI is loaded it does: 7274 7275 DBI->trace(split /=/, $ENV{DBI_TRACE}, 2) if $ENV{DBI_TRACE}; 7276 7277 So if C<DBI_TRACE> contains an "C<=>" character then what follows 7278 it is used as the name of the file to append the trace to. 7279 7280 output appended to that file. If the name begins with a number 7281 followed by an equal sign (C<=>), then the number and the equal sign are 7282 stripped off from the name, and the number is used to set the trace 7283 level. For example: 7284 7285 DBI_TRACE=1=dbitrace.log perl your_test_script.pl 7286 7287 On Unix-like systems using a Bourne-like shell, you can do this easily 7288 on the command line: 7289 7290 DBI_TRACE=2 perl your_test_script.pl 7291 7292 See L</TRACING> for more information. 7293 7294 =head2 PERL_DBI_DEBUG (obsolete) 7295 7296 An old variable that should no longer be used; equivalent to DBI_TRACE. 7297 7298 =head2 DBI_PROFILE 7299 7300 The DBI_PROFILE environment variable can be used to enable profiling 7301 of DBI method calls. See L<DBI::Profile> for more information. 7302 7303 =head2 DBI_PUREPERL 7304 7305 The DBI_PUREPERL environment variable can be used to enable the 7306 use of DBI::PurePerl. See L<DBI::PurePerl> for more information. 7307 7308 =head1 WARNING AND ERROR MESSAGES 7309 7310 =head2 Fatal Errors 7311 7312 =over 4 7313 7314 =item Can't call method "prepare" without a package or object reference 7315 7316 The C<$dbh> handle you're using to call C<prepare> is probably undefined because 7317 the preceding C<connect> failed. You should always check the return status of 7318 DBI methods, or use the L</RaiseError> attribute. 7319 7320 =item Can't call method "execute" without a package or object reference 7321 7322 The C<$sth> handle you're using to call C<execute> is probably undefined because 7323 the preceeding C<prepare> failed. You should always check the return status of 7324 DBI methods, or use the L</RaiseError> attribute. 7325 7326 =item DBI/DBD internal version mismatch 7327 7328 The DBD driver module was built with a different version of DBI than 7329 the one currently being used. You should rebuild the DBD module under 7330 the current version of DBI. 7331 7332 (Some rare platforms require "static linking". On those platforms, there 7333 may be an old DBI or DBD driver version actually embedded in the Perl 7334 executable being used.) 7335 7336 =item DBD driver has not implemented the AutoCommit attribute 7337 7338 The DBD driver implementation is incomplete. Consult the author. 7339 7340 =item Can't [sg]et %s->{%s}: unrecognised attribute 7341 7342 You attempted to set or get an unknown attribute of a handle. Make 7343 sure you have spelled the attribute name correctly; case is significant 7344 (e.g., "Autocommit" is not the same as "AutoCommit"). 7345 7346 =back 7347 7348 =head1 Pure-Perl DBI 7349 7350 A pure-perl emulation of the DBI is included in the distribution 7351 for people using pure-perl drivers who, for whatever reason, can't 7352 install the compiled DBI. See L<DBI::PurePerl>. 7353 7354 =head1 SEE ALSO 7355 7356 =head2 Driver and Database Documentation 7357 7358 Refer to the documentation for the DBD driver that you are using. 7359 7360 Refer to the SQL Language Reference Manual for the database engine that you are using. 7361 7362 =head2 ODBC and SQL/CLI Standards Reference Information 7363 7364 More detailed information about the semantics of certain DBI methods 7365 that are based on ODBC and SQL/CLI standards is available on-line 7366 via microsoft.com, for ODBC, and www.jtc1sc32.org for the SQL/CLI 7367 standard: 7368 7369 DBI method ODBC function SQL/CLI Working Draft 7370 ---------- ------------- --------------------- 7371 column_info SQLColumns Page 124 7372 foreign_key_info SQLForeignKeys Page 163 7373 get_info SQLGetInfo Page 214 7374 primary_key_info SQLPrimaryKeys Page 254 7375 table_info SQLTables Page 294 7376 type_info SQLGetTypeInfo Page 239 7377 statistics_info SQLStatistics 7378 7379 For example, for ODBC information on SQLColumns you'd visit: 7380 7381 http://msdn.microsoft.com/library/en-us/odbc/htm/odbcsqlcolumns.asp 7382 7383 If that URL ceases to work then use the MSDN search facility at: 7384 7385 http://search.microsoft.com/us/dev/ 7386 7387 and search for C<SQLColumns returns> using the exact phrase option. 7388 The link you want will probably just be called C<SQLColumns> and will 7389 be part of the Data Access SDK. 7390 7391 And for SQL/CLI standard information on SQLColumns you'd read page 124 of 7392 the (very large) SQL/CLI Working Draft available from: 7393 7394 http://jtc1sc32.org/doc/N0701-0750/32N0744T.pdf 7395 7396 =head2 Standards Reference Information 7397 7398 A hyperlinked, browsable version of the BNF syntax for SQL92 (plus 7399 Oracle 7 SQL and PL/SQL) is available here: 7400 7401 http://cui.unige.ch/db-research/Enseignement/analyseinfo/SQL92/BNFindex.html 7402 7403 A BNF syntax for SQL3 is available here: 7404 7405 http://www.sqlstandards.org/SC32/WG3/Progression_Documents/Informal_working_drafts/iso-9075-2-1999.bnf 7406 7407 The following links provide further useful information about SQL. 7408 Some of these are rather dated now but may still be useful. 7409 7410 http://www.jcc.com/SQLPages/jccs_sql.htm 7411 http://www.contrib.andrew.cmu.edu/~shadow/sql.html 7412 http://www.altavista.com/query?q=sql+tutorial 7413 7414 7415 =head2 Books and Articles 7416 7417 Programming the Perl DBI, by Alligator Descartes and Tim Bunce. 7418 L<http://books.perl.org/book/154> 7419 7420 Programming Perl 3rd Ed. by Larry Wall, Tom Christiansen & Jon Orwant. 7421 L<http://books.perl.org/book/134> 7422 7423 Learning Perl by Randal Schwartz. 7424 L<http://books.perl.org/book/101> 7425 7426 Details of many other books related to perl can be found at L<http://books.perl.org> 7427 7428 =head2 Perl Modules 7429 7430 Index of DBI related modules available from CPAN: 7431 7432 http://search.cpan.org/search?mode=module&query=DBIx%3A%3A 7433 http://search.cpan.org/search?mode=doc&query=DBI 7434 7435 For a good comparison of RDBMS-OO mappers and some OO-RDBMS mappers 7436 (including Class::DBI, Alzabo, and DBIx::RecordSet in the former 7437 category and Tangram and SPOPS in the latter) see the Perl 7438 Object-Oriented Persistence project pages at: 7439 7440 http://poop.sourceforge.net 7441 7442 A similar page for Java toolkits can be found at: 7443 7444 http://c2.com/cgi-bin/wiki?ObjectRelationalToolComparison 7445 7446 =head2 Mailing List 7447 7448 The I<dbi-users> mailing list is the primary means of communication among 7449 users of the DBI and its related modules. For details send email to: 7450 7451 dbi-users-help@perl.org 7452 7453 There are typically between 700 and 900 messages per month. You have 7454 to subscribe in order to be able to post. However you can opt for a 7455 'post-only' subscription. 7456 7457 Mailing list archives (of variable quality) are held at: 7458 7459 http://groups.google.com/groups?group=perl.dbi.users 7460 http://www.xray.mpe.mpg.de/mailing-lists/dbi/ 7461 http://www.mail-archive.com/dbi-users%40perl.org/ 7462 7463 =head2 Assorted Related WWW Links 7464 7465 The DBI "Home Page": 7466 7467 http://dbi.perl.org/ 7468 7469 Other DBI related links: 7470 7471 http://tegan.deltanet.com/~phlip/DBUIdoc.html 7472 http://dc.pm.org/perl_db.html 7473 http://wdvl.com/Authoring/DB/Intro/toc.html 7474 http://www.hotwired.com/webmonkey/backend/tutorials/tutorial1.html 7475 http://bumppo.net/lists/macperl/1999/06/msg00197.html 7476 http://gmax.oltrelinux.com/dbirecipes.html 7477 7478 Other database related links: 7479 7480 http://www.jcc.com/sql_stnd.html 7481 http://cuiwww.unige.ch/OSG/info/FreeDB/FreeDB.home.html 7482 http://www.connectionstrings.com/ 7483 7484 Security, especially the "SQL Injection" attack: 7485 7486 http://www.ngssoftware.com/research/papers.html 7487 http://www.ngssoftware.com/papers/advanced_sql_injection.pdf 7488 http://www.ngssoftware.com/papers/more_advanced_sql_injection.pdf 7489 http://www.esecurityplanet.com/trends/article.php/2243461 7490 http://www.spidynamics.com/papers/SQLInjectionWhitePaper.pdf 7491 http://www.imperva.com/application_defense_center/white_papers/blind_sql_server_injection.html 7492 http://online.securityfocus.com/infocus/1644 7493 7494 Commercial and Data Warehouse Links 7495 7496 http://www.dwinfocenter.org 7497 http://www.datawarehouse.com 7498 http://www.datamining.org 7499 http://www.olapcouncil.org 7500 http://www.idwa.org 7501 http://www.knowledgecenters.org/dwcenter.asp 7502 7503 Recommended Perl Programming Links 7504 7505 http://language.perl.com/style/ 7506 7507 7508 =head2 FAQ 7509 7510 See L<http://faq.dbi-support.com/> 7511 7512 =head1 AUTHORS 7513 7514 DBI by Tim Bunce, L<http://www.tim.bunce.name> 7515 7516 This pod text by Tim Bunce, J. Douglas Dunlop, Jonathan Leffler and others. 7517 Perl by Larry Wall and the C<perl5-porters>. 7518 7519 =head1 COPYRIGHT 7520 7521 The DBI module is Copyright (c) 1994-2008 Tim Bunce. Ireland. 7522 All rights reserved. 7523 7524 You may distribute under the terms of either the GNU General Public 7525 License or the Artistic License, as specified in the Perl README file. 7526 7527 =head1 SUPPORT / WARRANTY 7528 7529 The DBI is free Open Source software. IT COMES WITHOUT WARRANTY OF ANY KIND. 7530 7531 =head2 Support 7532 7533 My consulting company, Data Plan Services, offers annual and 7534 multi-annual support contracts for the DBI. These provide sustained 7535 support for DBI development, and sustained value for you in return. 7536 Contact me for details. 7537 7538 =head2 Sponsor Enhancements 7539 7540 The DBI Roadmap is available at L<http://search.cpan.org/~timb/DBI/Roadmap.pod> 7541 7542 If your company would benefit from a specific new DBI feature, 7543 please consider sponsoring its development. Work is performed 7544 rapidly, and usually on a fixed-price payment-on-delivery basis. 7545 Contact me for details. 7546 7547 Using such targeted financing allows you to contribute to DBI 7548 development, and rapidly get something specific and valuable in return. 7549 7550 =head1 ACKNOWLEDGEMENTS 7551 7552 I would like to acknowledge the valuable contributions of the many 7553 people I have worked with on the DBI project, especially in the early 7554 years (1992-1994). In no particular order: Kevin Stock, Buzz Moschetti, 7555 Kurt Andersen, Ted Lemon, William Hails, Garth Kennedy, Michael Peppler, 7556 Neil S. Briscoe, Jeff Urlwin, David J. Hughes, Jeff Stander, 7557 Forrest D Whitcher, Larry Wall, Jeff Fried, Roy Johnson, Paul Hudson, 7558 Georg Rehfeld, Steve Sizemore, Ron Pool, Jon Meek, Tom Christiansen, 7559 Steve Baumgarten, Randal Schwartz, and a whole lot more. 7560 7561 Then, of course, there are the poor souls who have struggled through 7562 untold and undocumented obstacles to actually implement DBI drivers. 7563 Among their ranks are Jochen Wiedmann, Alligator Descartes, Jonathan 7564 Leffler, Jeff Urlwin, Michael Peppler, Henrik Tougaard, Edwin Pratomo, 7565 Davide Migliavacca, Jan Pazdziora, Peter Haworth, Edmund Mergl, Steve 7566 Williams, Thomas Lowery, and Phlip Plumlee. Without them, the DBI would 7567 not be the practical reality it is today. I'm also especially grateful 7568 to Alligator Descartes for starting work on the first edition of the 7569 "Programming the Perl DBI" book and letting me jump on board. 7570 7571 The DBI and DBD::Oracle were originally developed while I was Technical 7572 Director (CTO) of Ingeneering in the UK (L<http://www.ig.co.uk>) (formerly known as the 7573 Paul Ingram Group). So I'd especially like to thank Paul for his generosity 7574 and vision in supporting this work for many years. 7575 7576 A couple of specific DBI features have been sponsored by enlightened companies: 7577 7578 The development of the swap_inner_handle() method was sponsored by BizRate.com (L<http://BizRate.com>) 7579 7580 The development of DBD::Gofer and related modules was sponsored by 7581 Shopzilla.com (L<http://Shopzilla.com>), where I currently work. 7582 7583 7584 =head1 CONTRIBUTING 7585 7586 As you can see above, many people have contributed to the DBI and 7587 drivers in many ways over many years. 7588 7589 If you'd like to help then see L<http://dbi.perl.org/contributing> 7590 and L<http://search.cpan.org/~timb/DBI/Roadmap.pod> 7591 7592 If you'd like the DBI to do something new or different then a good way 7593 to make that happen is to do it yourself and send me a patch to the 7594 source code that shows the changes. (But read "Speak before you patch" 7595 below.) 7596 7597 =head2 Browsing the source code repository 7598 7599 Use http://svn.perl.org/modules/dbi/trunk (basic) 7600 or http://svn.perl.org/viewcvs/modules/ (more useful) 7601 7602 =head2 How to create a patch using Subversion 7603 7604 The DBI source code is maintained using Subversion (a replacement 7605 for CVS, see L<http://subversion.tigris.org/>). To access the source 7606 you'll need to install a Subversion client. Then, to get the source 7607 code, do: 7608 7609 svn checkout http://svn.perl.org/modules/dbi/trunk 7610 7611 If it prompts for a username and password use your perl.org account 7612 if you have one, else just 'guest' and 'guest'. The source code will 7613 be in a new subdirectory called C<trunk>. 7614 7615 To keep informed about changes to the source you can send an empty email 7616 to svn-commit-modules-dbi-subscribe@perl.org after which you'll get an email 7617 with the change log message and diff of each change checked-in to the source. 7618 7619 After making your changes you can generate a patch file, but before 7620 you do, make sure your source is still upto date using: 7621 7622 svn update 7623 7624 If you get any conflicts reported you'll need to fix them first. 7625 Then generate the patch file from within the C<trunk> directory using: 7626 7627 svn diff > foo.patch 7628 7629 Read the patch file, as a sanity check, and then email it to dbi-dev@perl.org. 7630 7631 =head2 How to create a patch without Subversion 7632 7633 Unpack a fresh copy of the distribution: 7634 7635 tar xfz DBI-1.40.tar.gz 7636 7637 Rename the newly created top level directory: 7638 7639 mv DBI-1.40 DBI-1.40.your_foo 7640 7641 Edit the contents of DBI-1.40.your_foo/* till it does what you want. 7642 7643 Test your changes and then remove all temporary files: 7644 7645 make test && make distclean 7646 7647 Go back to the directory you originally unpacked the distribution: 7648 7649 cd .. 7650 7651 Unpack I<another> copy of the original distribution you started with: 7652 7653 tar xfz DBI-1.40.tar.gz 7654 7655 Then create a patch file by performing a recursive C<diff> on the two 7656 top level directories: 7657 7658 diff -r -u DBI-1.40 DBI-1.40.your_foo > DBI-1.40.your_foo.patch 7659 7660 =head2 Speak before you patch 7661 7662 For anything non-trivial or possibly controversial it's a good idea 7663 to discuss (on dbi-dev@perl.org) the changes you propose before 7664 actually spending time working on them. Otherwise you run the risk 7665 of them being rejected because they don't fit into some larger plans 7666 you may not be aware of. 7667 7668 =head1 TRANSLATIONS 7669 7670 A German translation of this manual (possibly slightly out of date) is 7671 available, thanks to O'Reilly, at: 7672 7673 http://www.oreilly.de/catalog/perldbiger/ 7674 7675 Some other translations: 7676 7677 http://cronopio.net/perl/ - Spanish 7678 http://member.nifty.ne.jp/hippo2000/dbimemo.htm - Japanese 7679 7680 7681 =head1 TRAINING 7682 7683 References to DBI related training resources. No recommendation implied. 7684 7685 http://www.treepax.co.uk/ 7686 http://www.keller.com/dbweb/ 7687 7688 (If you offer professional DBI related training services, 7689 please send me your details so I can add them here.) 7690 7691 =head1 OTHER RELATED WORK AND PERL MODULES 7692 7693 =over 4 7694 7695 =item Apache::DBI by E.Mergl@bawue.de 7696 7697 To be used with the Apache daemon together with an embedded Perl 7698 interpreter like C<mod_perl>. Establishes a database connection which 7699 remains open for the lifetime of the HTTP daemon. This way the CGI 7700 connect and disconnect for every database access becomes superfluous. 7701 7702 =item SQL Parser 7703 7704 See also the L<SQL::Statement> module, SQL parser and engine. 7705 7706 =back 7707 7708 =cut
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Tue Mar 17 22:47:18 2015 | Cross-referenced by PHPXref 0.7.1 |