view release on metacpan or  search on metacpan

lib/DBI/DBD.pm  view on Meta::CPAN

settings are restored when the called method returns.

=head2 Trace Level

The trace level is the first 4 bits of the trace settings (masked by
C<DBIc_TRACE_FLAGS_MASK>) and represents trace levels of 1 to 15. Do
not output anything at trace levels less than 3 as they are reserved
for DBI.

For advice on what to output at each level see "Trace Levels" in
L<DBI>.

To test for a trace level you can use the C<DBIc_TRACE_LEVEL> macro
like this:

  if (DBIc_TRACE_LEVEL(imp_xxh) >= 2) {
      PerlIO_printf(DBIc_LOGPIO(imp_xxh), "foobar");
  }

Also B<note> the use of PerlIO_printf which you should always use for
tracing and never the C C<stdio.h> I/O functions.

=head2 Trace Flags

Trace 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. For a list of DBI
defined trace flags see "Trace Flags" in L<DBI>.

If you want to use private trace flags you'll probably want to be able
to set them by name. Drivers are expected to override the
parse_trace_flag (note the singular) and check if $trace_flag_name is
a driver specific trace flags and, if not, then call the DBIs default
parse_trace_flag(). To do that you'll need to define a
parse_trace_flag() method like this:

  sub parse_trace_flag {
      my ($h, $name) = @_;
      return 0x01000000 if $name eq 'foo';
      return 0x02000000 if $name eq 'bar';
      return 0x04000000 if $name eq 'baz';
      return 0x08000000 if $name eq 'boo';
      return 0x10000000 if $name eq 'bop';
      return $h->SUPER::parse_trace_flag($name);
  }

All private flag names must be lowercase, and all private flags must
be in the top 8 of the 32 bits of C<DBIc_TRACE_FLAGS(imp)> i.e.,
0xFF000000.

If you've defined a parse_trace_flag() method in ::db you'll also want
it in ::st, so just alias it in:

  *parse_trace_flag = \&DBD::foo:db::parse_trace_flag;

You may want to act on the current 'SQL' trace flag that DBI defines
to output SQL prepared/executed as DBI currently does not do SQL
tracing.

=head2 Trace Macros

Access to the trace level and trace flags is via a set of macros.

  DBIc_TRACE_SETTINGS(imp) returns the trace settings
  DBIc_TRACE_LEVEL(imp) returns the trace level
  DBIc_TRACE_FLAGS(imp) returns the trace flags
  DBIc_TRACE(imp, flags, flaglevel, level)

  e.g.,

  DBIc_TRACE(imp, 0, 0, 4)
    if level >= 4

  DBIc_TRACE(imp, DBDtf_FOO, 2, 4)
    if tracing DBDtf_FOO & level>=2 or level>=4

  DBIc_TRACE(imp, DBDtf_FOO, 2, 0)
    as above but never trace just due to level

=head1 WRITING AN EMULATION LAYER FOR AN OLD PERL INTERFACE

Study F<Oraperl.pm> (supplied with B<DBD::Oracle>) and F<Ingperl.pm> (supplied
with B<DBD::Ingres>) and the corresponding I<dbdimp.c> files for ideas.

Note that the emulation code sets C<$dbh-E<gt>{CompatMode} = 1;> for each
connection so that the internals of the driver can implement behaviour
compatible with the old interface when dealing with those handles.

=head2 Setting emulation perl variables

For example, ingperl has a I<$sql_rowcount> variable. Rather than try
to manually update this in F<Ingperl.pm> it can be done faster in C code.
In C<dbd_init()>:

  sql_rowcount = perl_get_sv("Ingperl::sql_rowcount", GV_ADDMULTI);

In the relevant places do:

  if (DBIc_COMPAT(imp_sth))     /* only do this for compatibility mode handles */
      sv_setiv(sql_rowcount, the_row_count);

=head1 OTHER MISCELLANEOUS INFORMATION

=head2 The imp_xyz_t types

Any handle has a corresponding C structure filled with private data.
Some of this data is reserved for use by B<DBI> (except for using the
DBIc macros below), some is for you. See the description of the
F<dbdimp.h> file above for examples. Most functions in F<dbdimp.c>
are passed both the handle C<xyz> and a pointer to C<imp_xyz>. In
rare cases, however, you may use the following macros:

=over 4

=item D_imp_dbh(dbh)

Given a function argument I<dbh>, declare a variable I<imp_dbh> and
initialize it with a pointer to the handles private data. Note: This
must be a part of the function header, because it declares a variable.