Author: timbo Date: Wed Mar 18 03:44:42 2009 New Revision: 12611 Modified: dbi/trunk/DBI.pm dbi/trunk/t/85gofer.t
Log: Rework ParamType and ParamValue docs, and move Statement attr docs above them. Partly to address http://annocpan.org/~TIMB/DBI-1.607/DBI.pm#note_2115 Bump up t/85gofer.t gofer test timeout further to address http://www.nntp.perl.org/group/perl.cpan.testers/2009/03/msg3501941.html Modified: dbi/trunk/DBI.pm ============================================================================== --- dbi/trunk/DBI.pm (original) +++ dbi/trunk/DBI.pm Wed Mar 18 03:44:42 2009 @@ -6362,6 +6362,11 @@ Returns the parent $dbh of the statement handle. +=head3 C<Statement> (string, read-only) + +Returns the statement string passed to the L</prepare> method. + + =head3 C<ParamValues> (hash ref, read-only) Returns a reference to a hash containing the values currently bound @@ -6371,10 +6376,19 @@ See L</ShowErrorStatement> for an example of how this is used. +* Keys: + If the driver supports C<ParamValues> but no values have been bound yet then the driver should return a hash with placeholders names in the keys but all the values undef, but some drivers may return -a ref to an empty hash. +a ref to an empty hash because they can't pre-determine the names. + +It is possible that the keys in the hash returned by C<ParamValues> +are not exactly the same as those implied by the prepared statement. +For example, DBD::Oracle translates 'C<?>' placeholders into 'C<:pN>' +where N is a sequence number starting at 1. + +* Values: It is possible that the values in the hash returned by C<ParamValues> are not I<exactly> the same as those passed to bind_param() or execute(). @@ -6383,15 +6397,61 @@ bound as an SQL_INTEGER type may be returned as an integer. The values returned by C<ParamValues> can be passed to another bind_param() method with the same TYPE and will be seen by the -database as the same value. - -It is also possible that the keys in the hash returned by C<ParamValues> -are not exactly the same as those implied by the prepared statement. -For example, DBD::Oracle translates 'C<?>' placeholders into 'C<:pN>' -where N is a sequence number starting at 1. +database as the same value. See also L</ParamTypes> below. The C<ParamValues> attribute was added in DBI 1.28. +=head3 C<ParamTypes> (hash ref, read-only) + +Returns a reference to a hash containing the type information +currently bound to placeholders. +Returns undef if not supported by the driver. + +* Keys: + +See L</ParamValues> above. + +* Values: + +The hash values are hashrefs of type information in the same form as that +passed to the various bind_param() methods (See L</bind_param> for the format +and values). + +It is possible that the values in the hash returned by C<ParamTypes> +are not exactly the same as those passed to bind_param() or execute(). +Param attributes specified using the abreviated form, like this: + + $sth->bind_param(1, SQL_INTEGER); + +are returned in the expanded form, as if called like this: + + $sth->bind_param(1, { TYPE => SQL_INTEGER }); + +The driver may have modified the type information in some way based +on the bound values, other hints provided by the prepare()'d +SQL statement, or alternate type mappings required by the driver or target +database system. The driver may also add private keys (with names beginning +with the drivers reserved prefix, e.g., odbc_xxx). + +* Example: + +The keys and values in the returned hash can be passed to the various +bind_param() methods to effectively reproduce a previous param binding. +For example: + + # assuming $sth1 is a previously prepared statement handle + my $sth2 = $dbh->prepare( $sth1->{Statement} ); + my $ParamValues = $sth1->{ParamValues} || {}; + my $ParamTypes = $sth1->{ParamTypes} || {}; + $sth2->bind_param($_, $PV->{$_} $PT->{$_}) + for keys %{ %$PV, %$PT }; + $sth2->execute(); + +The C<ParamTypes> attribute was added in DBI 1.49. Implementation +is the responsibility of individual drivers; the DBI layer default +implementation simply returns undef. + + =head3 C<ParamArrays> (hash ref, read-only) Returns a reference to a hash containing the values currently bound to @@ -6426,46 +6486,6 @@ prepared statement. For example, DBD::Oracle translates 'C<?>' placeholders into 'C<:pN>' where N is a sequence number starting at 1. -=head3 C<ParamTypes> (hash ref, read-only) - -Returns a reference to a hash containing the type information -currently bound to placeholders. The keys of the hash are the -'names' of the placeholders: either integers starting at 1, or, -for drivers that support named placeholders, the actual parameter -name string. The hash values are hashrefs of type information in -the same form as that provided to the various bind_param() methods -(See L</bind_param> for the format and values), -plus anything else that was passed as the third argument to bind_param(). -Returns undef if not supported by the driver. - -If the driver supports C<ParamTypes>, but no values have been bound -yet, then the driver should return a hash with the placeholder name -keys, but all the values undef; however, some drivers may return -a ref to an empty hash, or, alternately, may provide type -information supplied by the database (only a few databases can do that). - -It is possible that the values in the hash returned by C<ParamTypes> -are not I<exactly> the same as those passed to bind_param() or execute(). -The driver may have modified the type information in some way based -on the bound values, other hints provided by the prepare()'d -SQL statement, or alternate type mappings required by the driver or target -database system. - -It is also possible that the keys in the hash returned by C<ParamTypes> -are not exactly the same as those implied by the prepared statement. -For example, DBD::Oracle translates 'C<?>' placeholders into 'C<:pN>' -where N is a sequence number starting at 1. - -The C<ParamTypes> attribute was added in DBI 1.49. Implementation -is the responsibility of individual drivers; the DBI layer default -implementation simply returns undef. - - -=head3 C<Statement> (string, read-only) - -Returns the statement string passed to the L</prepare> method. - - =head3 C<RowsInCache> (integer, read-only) If the driver supports a local row cache for C<SELECT> statements, then Modified: dbi/trunk/t/85gofer.t ============================================================================== --- dbi/trunk/t/85gofer.t (original) +++ dbi/trunk/t/85gofer.t Wed Mar 18 03:44:42 2009 @@ -46,7 +46,7 @@ } my $remote_driver_dsn = "dbm_type=$opt_dbm;lockfile=0"; my $remote_dsn = "dbi:DBM:$remote_driver_dsn"; -my $timeout = 60; # for slow/overloaded systems (incl virtual machines with low priority) +my $timeout = 90; # for slow/overloaded systems (incl virtual machines with low priority) plan 'no_plan';
