dbd.pm

SinFP是一种新的识别对方计算机操作系统类型的工具

Since DBI v1.06, if a I<dbd_db_login6> macro is defined (for a function
with 6 arguments), it will be used instead with the attribute hash
passed as the sixth argument.

People used to just pick Oracle's dbdimp.c and use the same names,
structures and types.
I strongly recommend against that.
At first glance this saves time, but your implementation will be less
readable.
It was just hell when I had to separate DBI specific parts, Oracle
specific parts, mSQL specific parts and mysql specific parts in
DBD::mysql's I<dbdimp.h> and I<dbdimp.c>.
(DBD::mysql was a port of DBD::mSQL which was based on DBD::Oracle.)
[Seconded, based on the experience taking DBD::Informix apart, even
though the version inherited in 1996 was only based on DBD::Oracle.]

This part of the driver is I<your exclusive part>.
Rewrite it from scratch, so it will be clean and short: in other words,
a better piece of code.
(Of course keep an eye on other people's work.)

  struct imp_drh_st {
      dbih_drc_t com;           /* MUST be first element in structure   */
      /* Insert your driver handle attributes here */
  };

  struct imp_dbh_st {
      dbih_dbc_t com;           /* MUST be first element in structure   */
      /* Insert your database handle attributes here */
  };

  struct imp_sth_st {
      dbih_stc_t com;           /* MUST be first element in structure   */
      /* Insert your statement handle attributes here */
  };

  /*  Rename functions for avoiding name clashes; prototypes are  */
  /*  in dbd_xst.h                                                */
  #define dbd_init         drv_dr_init
  #define dbd_db_login6    drv_db_login
  #define dbd_db_do        drv_db_do
  ... many more here ...

These structures implement your private part of the handles.
You I<have> to use the name I<imp_dbh_{dr|db|st}> and the first field
I<must> be of type I<dbih_drc_t|_dbc_t|_stc_t> and I<must> be called
C<com>.
You should never access these fields directly, except by using the
I<DBIc_xxx> macros below.

=head2 Implementation source dbdimp.c

Conventionally, I<dbdimp.c> is the main implementation file (but
DBD::Informix calls the file dbdimp.ec).
This section includes a short note on each function that is used in the
Driver.xsi template and thus B<has> to be implemented.

Of course, you will probably also need to implement other support
functions, which should usually be file static if the are placed in
I<dbdimp.c>.
If they are placed in other files, you need to list those files in
Makefile.PL (and MANIFEST) to handle them correctly.

It is wise to adhere to a namespace convention for your functions to
avoid conflicts.
For example, for a driver with prefix "drv", you might call externally
visible functions "dbd_drv_xxxx".
You should also avoid non-constant global variables as much as possible
to improve the support for threading.

Since Perl 5.6 requires support for function prototypes (ANSI or ISO or
Standard C), you should write your code using function prototypes too.
Although technically DBI still supports Perl 5.005_03, which did not
mandate prototype support from the C compiler, the only platform where
prototypes are a problem is on HP-UX with the bundled C compiler (which
is strictly K&R).
The solution for that is to get a copy of the GNU Compiler Collection
(GCC, aka the GNU C Compiler) for HP-UX.

It is possible to use either the unmapped names such as C<dbd_init> or
the mapped names such as C<dbd_ix_dr_init> in the C<dbdimp.c> file.
DBD::Informix uses the mapped names which makes it easier to identify
where to look for linkage problems at runtime (which will report errors
using the mapped names).
Most other drivers, and in particular DBD::Oracle, use the unmapped
names in the source code which makes it a little easier to compare code
between drivers and eases discussions on the dbi-dev mailing list.
The majority of the code fragments here will use the unmapped names.

Ultimately, you should provide implementations for most fo the functions
listed in the I<dbd_xsh.h> header.
The exceptions are optional functions (such as I<dbd_st_rows>) and those
functions with alternative signatures, such as I<dbd_db_login6> and
I<dbd_db_login>.
Then you should only implement one of the alternatives, and generally
the newer one of the alternatives.

=head3 The dbd_init method

  #include "Driver.h"

  DBISTATE_DECLARE;

  void dbd_init(dbistate_t* dbistate)
  {
      DBISTATE_INIT;  /*  Initialize the DBI macros  */
  }

The C<dbd_init> function will be called when your driver is first
loaded; the bootstrap command in DBD::Driver::dr::driver triggers this,
and the call is generated in the BOOT section of Driver.xst.
These statements are needed to allow your driver to use the DBI macros.
They will include your private header file I<dbdimp.h> in turn.
Note that DBISTATE_INIT requires the name of the argument to I<dbd_init>
to be called I<dbistate>.

=head3 The dbd_drv_error method

You need a function to record errors so DBI can access them properly.
You can call it whatever you like, but we'll call it C<dbd_drv_error>
here.
The argument list depends on your database software; different systems
provide different ways to get at error information.

  static void dbd_drv_error(SV *h, int rc, const char *what)
  {

Note that I<h> is a generic handle, may it be a driver handle, a
database or a statement handle.

      D_imp_xxh(h);

This macro will declare and initialize a variable I<imp_xxh> with
a pointer to your private handle pointer. You may cast this to
to I<imp_drh_t>, I<imp_dbh_t> or I<imp_sth_t>.

To record the error correctly, equivalent to the set_err() method,
use one of the DBIh_SET_ERR_CHAR(...) or DBIh_SET_ERR_SV(...) macros,
which were added in DBI 1.41:

  DBIh_SET_ERR_SV(h, imp_xxh, err, errstr, state, method);
  DBIh_SET_ERR_CHAR(h, imp_xxh, err_c, err_i, errstr, state, method);

For DBIh_SET_ERR_SV the err, errstr, state, and method parameters are SV*.
For DBIh_SET_ERR_CHAR the err_c, errstr, state, method are char*.
The err_i parameter is an IV that's used instead of err_c is err_c is Null.
The method parameter can be ignored.

The DBIh_SET_ERR_CHAR macro is usually the simplest to use when you
just have an integer error code and an error message string:

  DBIh_SET_ERR_CHAR(h, imp_xxh, Nullch, rc, what, Nullch, Nullch);

As you can see, any parameters that aren't relevant to you can be Null.

To make drivers compatible with DBI < 1.41 you should be using dbivport.h
as described in L</Driver.h> above.

The (obsolete) macros such as DBIh_EVENT2 should be removed from drivers.

The names I<dbis> and I<DBIS>, which were used in previous versions of this document,
should be replaced with the C<DBIc_STATE(imp_xxh)> macro.

The name DBILOGFP, which was also used in previous  versions of this document, should be
replaced by DBIc_LOGPIO(imp_xxh).

Your code should not call the C C<E<lt>stdio.hE<gt>> I/O functions; you should use
C<PerlIO_printf>() as shown:

      if (DBIc_TRACE_LEVEL(imp_xxh) >= 2)
          PerlIO_printf(DBIc_LOGPIO(imp_xxh), "foobar %s: %s\n",
              foo, neatsvpv(errstr,0));

That's the first time we see how tracing works within a DBI
driver.  Make use of this as often as you can! But don't output anything
at a trace level less than 3. Levels 1 and 2 are reserved for the DBI.

You can define up to 8 private trace flags using the top 8 bits of
DBIc_TRACE_FLAGS(imp), that is: 0xFF000000. See the parse_trace_flag() method
elsewhere in this document.

=head3 The dbd_dr_data_sources method

This method is optional; the support for it was added in DBI v1.33.

As noted in the discussion of Driver.pm, if the data sources can be
determined by pure Perl code, do it that way.
If, as in DBD::Informix, the information is obtained by a C function
call, then you need to define a function that matches the prototype:

  extern AV *dbd_dr_data_sources(SV *drh, imp_drh_t *imp_drh, SV *attrs);

An outline implementation for DBD::Informix follows, assuming that the
sqgetdbs() function call shown will return up to 100 databases names,
with the pointers to each name in the array dbsname and the name strings
themselves being stores in dbsarea.
The actual DBD::Informix implementation has a number of extra lines of
code, logs function entry and exit, reports the error from sqgetdbs(),
and uses #define'd constatnts for the array sizes.

  AV *dbd_dr_data_sources(SV *drh, imp_drh_t *imp_drh, SV *attr)
  {
      int ndbs;
      int i;
      char *dbsname[100];
      char  dbsarea[10000];
      AV *av = Nullav;

      if (sqgetdbs(&ndbs, dbsname, 100, dbsarea, sizeof(dbsarea)) == 0)
      {
          av = NewAV();
          av_extend(av, (I32)ndbs);
          sv_2mortal((SV *)av);
          for (i = 0; i < ndbs; i++)
            av_store(av, i, newSVpvf("dbi:Informix:%s", dbsname[i]));
      }
      return(av);
  }

=head3 The dbd_db_login6 method

  int dbd_db_login6(SV* dbh, imp_dbh_t* imp_dbh, char* dbname,
                   char* user, char* auth, SV *attr);

This function will really connect to the database.
The argument I<dbh> is the database handle.
I<imp_dbh> is the pointer to the handles private data, as is I<imp_xxx>
in I<dbd_drv_error> above.
The arguments I<dbname>, I<user>, I<auth> and I<attr> correspond to the
arguments of the driver handle's I<connect> method.

You will quite often use database specific attributes here, that are
specified in the DSN.
I recommend you parse the DSN (using Perl) within the I<connect> method
and pass the segments of the DSN via the attributes parameter through
I<_login> to I<dbd_db_login6>.
Here's how you fetch them; as an example we use I<hostname> attribute,
which can be up to 12 characters long excluding null terminator:

  SV** svp;
  STRLEN len;
  char* hostname;

  if ( (svp = DBD_ATTRIB_GET_SVP(attr, "drv_hostname", 12)) && SvTRUE(*svp)) {
      hostname = SvPV(*svp, len);
      DBD__ATTRIB_DELETE(attr, "drv_hostname", 12); /* avoid later STORE */
  } else {
      hostname = "localhost";
  }

Note that you can also obtain standard attributes such as AutoCommit and
ChopBlanks from the attributes parameter, using DBD_ATTRIB_GET_IV for
integer attributes.
If, for example, your database does not support transactions but
AutoCommit is set off (requesting transaction support), then you can
emulate a 'failure to connect'.

Now you should really connect to the database.
In general, if the connection fails, it is best to ensure that all
allocated resources are released so that the handle does not need to be
destroyed separately.
If you are successful (and possibly even if you fail but you have
allocated some resources), you should use the following macros:

  DBIc_IMPSET_on(imp_dbh);

This indicates that the driver (implementor) has allocated resources in
the imp_dbh structure and that the implementors private dbd_db_destroy
function should be called when the handle is destroyed.

  DBIc_ACTIVE_on(imp_dbh);

This indicates that the handle has an active connection to the server
and that the dbd_db_disconnect function should be called before the
handle is destroyed.

Note that if you do need to fail, you should report errors via the drh
or imp_drh rather than via dbh or imp_dbh because imp_dbh will be
destroyed by the failure, so errors recorded in that handle will not be
visible to DBI, and hence not the user either.
Note to that the function is passed dbh and imp_dbh, and there is a
macro D_imp_drh_from_dbh which can recover the imp_drh from the imp_dbh,
but there is no DBI macro to provide you with the drh given either the
imp_dbh or the dbh or the imp_drh (and there's no way to recover the dbh
given just the imp_dbh).
This suggests that despite the notes about dbd_drv_error above taking an
SV *, it may be better to have two error routines, one taking imp_dbh
and one taking imp_drh instead.
With care, you can factor most of the formatting code out so that these
are small routines calling onto a common error formatter.
See the code in DBD::Informix 1.05.00 for more information.

The I<dbd_db_login6> function should return TRUE for success, FALSE otherwise.

Drivers implemented long ago may define the five-argument function
I<dbd_db_login> instead of I<dbd_db_login6>.
The missing argument is the attributes.
There are ways to work around the missing attributes, but they are
ungainly; it is much better to use the 6-argument form.

=head3 The dbd_db_commit and dbd_db_rollback methods

  int dbd_db_commit(SV *dbh, imp_dbh_t *imp_dbh);
  int dbd_db_rollback(SV* dbh, imp_dbh_t* imp_dbh);

These are used for commit and rollback. They should return TRUE for
success, FALSE for error.

The arguments I<dbh> and I<imp_dbh> are the same as for I<dbd_db_login6>
above; I will omit describing them in what follows, as they appear
always.

These functions should return TRUE for success, FALSE otherwise.

=head3 The dbd_db_disconnect method

This is your private part of the I<disconnect> method. Any dbh with
the I<ACTIVE> flag on must be disconnected. (Note that you have to set
it in I<dbd_db_connect> above.)

  int dbd_db_disconnect(SV* dbh, imp_dbh_t* imp_dbh);

The database handle will return TRUE for success, FALSE otherwise.
In any case it should do a:

  DBIc_ACTIVE_off(imp_dbh);

before returning so DBI knows that I<dbd_db_disconnect> was executed.

Note that there's nothing to stop a dbh being I<disconnected> while it
still have active children.
If your database API reacts badly to trying to use an sth in this
situation then you'll need to add code like this to all sth methods:

  if (!DBIc_ACTIVE(DBIc_PARENT_COM(imp_sth)))
    return 0;

Alternatively, you can add code to your driver to keep explicit track of
the statement handles that exist for each database handle and arrange to
destroy those handles before disconnecting from the database.
There is code to do this in DBD::Informix.
Similar comments apply to the driver handle keeping track of all the
database handles.
Note that the code which destroys the subordinate handles should only
release the associated database resources and mark the handles inactive;
it does not attempt to free the actual handle structures.

This function should return TRUE for success, FALSE otherwise, but
it is not clear what anything can do about a failure.

=head3 The dbd_db_discon_all method

  int dbd_discon_all (SV *drh, imp_drh_t *imp_drh);

This function may be called at shutdown time. It should make
best-efforts to disconnect all database handles - if possible. Some
databases don't support that, in which case you can do nothing
but return 'success'.

This function should return TRUE for success, FALSE otherwise, but
it is not clear what