Author: timbo
Date: Sat Jun 26 14:56:07 2004
New Revision: 369
Modified:
dbi/trunk/Changes
dbi/trunk/DBI.pm
dbi/trunk/ToDo
Log:
Added docs for parse_trace_flags() and parse_trace_flag().
Updates to Changes and ToDo.
Modified: dbi/trunk/Changes
==============================================================================
--- dbi/trunk/Changes (original)
+++ dbi/trunk/Changes Sat Jun 26 14:56:07 2004
@@ -4,8 +4,6 @@
=cut
-Document $t->parse_trace_flags etc
-
=head1 CHANGES in DBI 1.43 (svn rev XXX), XXth XXX 2004
Extended bind_col() TYPE attribute specification to imply
@@ -23,6 +21,7 @@
Fixed DBI::ProfileDumper new() docs thanks to Michael Schwern.
Fixed _load_class to propagate $@ thanks to Drew Taylor.
Fixed compile warnings on Win32 thanks to Robert Baron.
+ Fixed problem building with recent versions of MakeMaker.
Changed selectall_arrayref() to call finish() if
$attr->{MaxRows} is defined.
@@ -32,6 +31,7 @@
Added DBI->parse_dsn($dsn) method.
Added warning if build directory path contains whitespace.
+ Added docs for parse_trace_flags() and parse_trace_flag().
Removed "may change" warnings from the docs for table_info(),
primary_key_info(), and foreign_key_info() methods.
Modified: dbi/trunk/DBI.pm
==============================================================================
--- dbi/trunk/DBI.pm (original)
+++ dbi/trunk/DBI.pm Sat Jun 26 14:56:07 2004
@@ -258,7 +258,7 @@
}
# Alias some handle methods to also be DBI class methods
-for (qw(trace_msg set_err parse_trace_flags parse_trace_flag)) {
+for (qw(trace_msg set_err parse_trace_flag parse_trace_flags)) {
no strict;
*$_ = \&{"DBD::_::common::$_"};
}
@@ -1252,7 +1252,7 @@
my $level = 0;
my $flags = 0;
my @unknown;
- for my $word (split /\s*[|&]\s*/, $spec) {
+ for my $word (split /\s*[|&,]\s*/, $spec) {
if (DBI::looks_like_number($word) && $word <= 0xF && $word >= 0) {
$level = $word;
} elsif ($word eq 'ALL') {
@@ -2823,6 +2823,29 @@
It returns false where a driver hasn't implemented a method and the
default method is provided by the DBI is just an empty stub.
+=item C<parse_trace_flags>
+
+ $trace_settings_integer = $h->parse_trace_flags($trace_settings);
+
+Parses a string containing trace settings and returns the corresponding
+integer value used internally by the DBI and drivers.
+
+The $trace_settings argument is a string containing a trace level
+between 0 and 15 and/or trace flag names separated by vertical bar
+("C<|>") or comma ("C<,>") characters. For example: C<"SQL|3|foo">.
+
+It uses the parse_trace_flag() method, described below, to process
+the individual trage flag names.
+
+=item C<parse_trace_flag>
+
+ $bit_flag = $h->parse_trace_flag($trace_flag_name);
+
+Returns the bit flag corresponding to the trace flag name in
+$trace_flag_name. Drivers are expected to override this method and
+check if $trace_flag_name is a driver specific trace flags and, if
+not, then call the DBIs default parse_trace_flag().
+
=back
@@ -3146,7 +3169,10 @@
The C<TraceLevel> attribute can be used as an alternative to the
L</trace> method to set the DBI trace level and trace flags for a
-specific handle. See L</TRACING> for more details.
+specific handle. See L</TRACING> for more details.
+
+The C<TraceLevel> attribute is especially useful combined with
+C<local> to alter the trace settings for just a single block of code.
=item C<FetchHashKeyName> (string, inherited)
@@ -6202,22 +6228,9 @@
The previous DBI trace setings are restored when the called method
returns.
-=head1 Enabling Trace
-
-The C<$h-E<gt>trace> method sets the trace settings for a handle
-and C<DBI-E<gt>trace> does the same for the DBI.
-
-In addition to the L</trace> method, you can enable the same trace
-information, and direct the output to a file, by setting the
-C<DBI_TRACE> environment variable before starting Perl.
-See L</DBI_TRACE> for more information.
-
-Finally, you can set, or get, the trace settings for a handle using
-the C<TraceLevel> attribute.
-
=head2 Trace Levels
-Trace levels are as follows:
+Trace I<levels> are as follows:
0 - Trace disabled.
1 - Trace DBI method calls returning with results or errors.
@@ -6225,7 +6238,7 @@
3 - As above, adding some high-level information from the driver
and some internal information from the DBI.
4 - As above, adding more detailed information from the driver.
- 5 and above - As above but with more and more obscure information.
+ 5 to 15 - As above but with more and more obscure information.
Trace level 1 is best for a simple overview of what's happening.
Trace level 2 is a good choice for general purpose tracing.
@@ -6236,6 +6249,42 @@
trace output is formatted using the L</neat> function, so strings
in the trace output may be edited and truncated by that function.
+=head2 Trace Flags
+
+Trace I<flags> are used to enable tracing of specific activities
+within the DBI and drivers. The DBI defines some trace flags and
+drivers can define others. DBI trace flag names begin with a capital
+letter and driver specific names begin with a lowercase letter, as
+usual.
+
+Curently the DBI only defines two trace flags:
+
+ ALL - turn on all DBI and driver flags (not recommended)
+ SQL - trace SQL statements executed (not yet implemented)
+
+The L</parse_trace_flags> and L</parse_trace_flag> methods are used
+to convert trace flag names into the coresponding integer bit flags.
+
+=head2 Enabling Trace
+
+The C<$h-E<gt>trace> method sets the trace settings for a handle
+and C<DBI-E<gt>trace> does the same for the DBI.
+
+In addition to the L</trace> method, you can enable the same trace
+information, and direct the output to a file, by setting the
+C<DBI_TRACE> environment variable before starting Perl.
+See L</DBI_TRACE> for more information.
+
+Finally, you can set, or get, the trace settings for a handle using
+the C<TraceLevel> attribute.
+
+All of those methods use parse_trace_flags() and so allow you set
+both the trace level and multiple trace flags by using a string
+containing the trace level and/or flag names separated by vertical
+bar ("C<|>") or comma ("C<,>") characters. For example:
+
+ local $h->{TraceLevel} = "3|SQL|foo";
+
=head2 Trace Output
Initially trace output is written to C<STDERR>. Both the
Modified: dbi/trunk/ToDo
==============================================================================
--- dbi/trunk/ToDo (original)
+++ dbi/trunk/ToDo Sat Jun 26 14:56:07 2004
@@ -2,6 +2,9 @@
--- Changes that may impact applications:
+Redefine tables() to default to tables accessible from current
+schema without further qualification.
+
Turning AutoCommit on should trigger rollback not commit.
(ODBC does a commit) This will break code that assumes a commit.
@@ -56,9 +59,6 @@
$h->{KidsHandles} = ref to cache (array or hash?)
of weakrefs to child handles.
-DBI::Profile: some way to get count of 'executions' only, not all method calls.
-So avg time is totaltime/executions not totaltime/methodcalls.
-
Document DbTypeSubclass (ala DBIx::AnyDBD)
Polish up and document _dbtype_names with an external interface and using get_info.
@@ -94,6 +94,10 @@
SQL_DATETIME => { TYPE => SQL_DATETIME, OnFetch => \&foo },
}
+Add utility function that does SvUTF8_on(sv) if the sv contains
+valid-looking utf8. To be used (perhaps via OnFetch hook) where
+utf8 data is being stored in a non-utf8 aware database.
+
Add a handle flag to say that the driver has a hash that maps error
codes into SQLSTATE values. The error event mechanism could check for
the flag and lookup the SQLSTATE value for the error from the hash.
@@ -189,8 +193,6 @@
Remove dummy 'Switch' driver.
-Add %time to per-node DBI::Profile dump
-
Sponge behave_like - generalize into new_child()
copy RaiseError, PrintError, HandleError etc from the specified handle
but which attributes? LongReadLen, LongTruncOk etc? Presumably all
@@ -401,22 +403,33 @@
Alternatively, and perferably, add sufficient hooks for this to be
done efficiently externally.
+Devel::Leak integration?
+
+--- DBI::Profile
+
+Add %time to per-node DBI::Profile dump
+
+DBI::Profile: some way to get count of 'executions' only, not all method calls.
+So avg time is totaltime/executions not totaltime/methodcalls.
DBI::Profile: add simple way to normalise the sql (convert constants
to placeholders) so profiling is more effective for drivers/applications
which don't use placeholders. Requires preparse()?
-
-Devel::Leak
-
DBI::Profile: Add calc of approx XS method call and timing overhead
by calling perl_call("DBI::dbi_time") x100 at boot time for profile,
and add 1/100 (x2) to each sample. Beware Win32 where resolution
is too small and overhead will be 0 normally but may be eg 100ms
if overhead probe is on cusp of time unit.
+Add mechanism so "call path" can be included in the Path of the
+profile data. Something like "<basename>@<linenum>;..." or
+optionally just the basename part.
+
Fix dbi_time for Windows by using or linking-to Time::HiRes code.
+---
+
Add a C call to return boolean for is a number' for a given SV.
Needs to do the right thing for a non-numeric string SV that's been
tested in a numeric context (eg $a='S23'; foo() if $a==-1; $sth->execute($a))
