=encoding euc-jp =head1 NAME =begin original DBI::DBD - Perl DBI Database Driver Writer's Guide =end original DBI::DBD - DBI データベースドライバ作成者ガイド =head1 SYNOPSIS perldoc DBI::DBD =head2 Version and volatility (バージョンと変更可能性) =begin original This document is I a minimal draft which is in need of further work. =end original このドキュメントは I<未だに> さらに作業を進めるために必要最小限のドラフトです。 =begin original The changes will occur both because the B specification is changing and hence the requirements on B drivers change, and because feedback from people reading this document will suggest improvements to it. =end original B の仕様変更やその結果 B ドライバに要求されることが変更されること、そしてこのドキュメントを読んだ人たちからフィードバックが改善を提案することの二つの理由により変更が発生します。 =begin original Please read the B documentation first and fully, including the B FAQ. Then reread the B specification again as you're reading this. It'll help. =end original まず B FAQを含めてすべての B ドキュメントをお読みください。これを読むときには B 仕様を読み返します。これは助けとなるでしょう。 =begin original This document is a patchwork of contributions from various authors. More contributions (preferably as patches) are very welcome. =end original このドキュメントは多くの作者からよせられた原稿を集めたものです。さらなる寄稿(どちらかといえばパッチとして)は大歓迎です。 =head1 DESCRIPTION =begin original This document is primarily intended to help people writing new database drivers for the Perl Database Interface (Perl DBI). It may also help others interested in discovering why the internals of a B driver are written the way they are. =end original このドキュメントは第一に Perl データベースインターフェース(Perl DBI)のための新しいデータベースドライバを作成する人達を助けることを目指しています。 B ドライバの内部がどうしてそのように書かれているのかを理解したい他の人たちにも助けになるでしょう。 =begin original This is a guide. Few (if any) of the statements in it are completely authoritative under all possible circumstances. This means you will need to use judgement in applying the guidelines in this document. If in I doubt at all, please do contact the I mailing list (details given below) where Tim Bunce and other driver authors can help. =end original これはガイドです。すべての可能な環境下で完全に権威のある文は (もしあったとしても)あまりありません。つまりこのドキュメントでのガイドラインを適用するときには判断が必要になります。もし I<少しでも> 疑問な点があれば、どうか Tim Bunce や他のドライバの作者が助けてくれる I メーリングリスト(詳細は以下にあります)にコンタクトしてください。 =head1 CREATING A NEW DRIVER (新しいドライバを作る) =begin original The first rule for creating a new database driver for the Perl DBI is very simple: B =end original Perl DBI のための新しいデータベースドライバを作るための最初の規則はとても単純です: B<作らない!> =begin original There is usually a driver already available for the database you want to use, almost regardless of which database you choose. Very often, the database will provide an ODBC driver interface, so you can often use B to access the database. This is typically less convenient on a Unix box than on a Microsoft Windows box, but there are numerous options for ODBC driver managers on Unix too, and very often the ODBC driver is provided by the database supplier. =end original There is usually a driver already available for the database you want to use, almost regardless of which database you choose. Very often, the database will provide an ODBC driver interface, so you can often use B to access the database. This is typically less convenient on a Unix box than on a Microsoft Windows box, but there are numerous options for ODBC driver managers on Unix too, and very often the ODBC driver is provided by the database supplier. (TBT) =begin original Before deciding that you need to write a driver, do your homework to ensure that you are not wasting your energies. =end original Before deciding that you need to write a driver, do your homework to ensure that you are not wasting your energies. (TBT) =begin original [As of December 2002, the consensus is that if you need an ODBC driver manager on Unix, then the unixODBC driver (available from L) is the way to go.] =end original [As of December 2002, the consensus is that if you need an ODBC driver manager on Unix, then the unixODBC driver (available from L) is the way to go.] (TBT) =begin original The second rule for creating a new database driver for the Perl DBI is also very simple: B =end original The second rule for creating a new database driver for the Perl DBI is also very simple: B (TBT) =begin original Nevertheless, there are occasions when it is necessary to write a new driver, often to use a proprietary language or API to access the database more swiftly, or more comprehensively, than an ODBC driver can. Then you should read this document very carefully, but with a suitably sceptical eye. =end original Nevertheless, there are occasions when it is necessary to write a new driver, often to use a proprietary language or API to access the database more swiftly, or more comprehensively, than an ODBC driver can. Then you should read this document very carefully, but with a suitably sceptical eye. (TBT) =begin original If there is something in here that does not make any sense, question it. You might be right that the information is bogus, but don't come to that conclusion too quickly. =end original If there is something in here that does not make any sense, question it. You might be right that the information is bogus, but don't come to that conclusion too quickly. (TBT) =head2 URLs and mailing lists (URL とメーリングリスト) =begin original The primary web-site for locating B software and information is =end original B ソフトウェアと情報が置いてある第一の WEB サイトは http://dbi.perl.org/ =begin original There are two main and one auxiliary mailing lists for people working with B. The primary lists are I for general users of B and B drivers, and I mainly for B driver writers (don't join the I list unless you have a good reason). The auxiliary list is I for announcing new releases of B or B drivers. =end original B で作業している人々のために主には二つ、そして補助的な一つのメーリングリストがあります。主なリストは、B と B ドライバの一般的な利用者のための I、主に B ドライバの作者のための I(たいした理由も無く I リストには参加しないで下さい)。補助的なリストは B または B ドライバの新しいリリースをアナウンスするための I です。 =begin original You can join these lists by accessing the web-site L. The lists are closed so you cannot send email to any of the lists unless you join the list first. =end original これらのリストには Web サイト L から参加することができます。そのリストは閉じているので、まずリストに参加しなければリストのメールを送信することが出来ません。 =begin original You should also consider monitoring the I newsgroups, especially I. =end original また I ニュースグループ、特に I をモニタすることも考慮してください。 =head2 The Cheetah book (チータ本) =begin original The definitive book on Perl DBI is the Cheetah book, so called because of the picture on the cover. Its proper title is 'I' by Alligator Descartes and Tim Bunce, published by O'Reilly Associates, February 2000, ISBN 1-56592-699-4. Buy it now if you have not already done so, and read it. =end original Perl DBI についての決定版はチータ本(表紙の絵からこう呼ばれます)です。正しいタイトルは 'I' by Alligator Descartes and Tim Bunce, published by O'Reilly Associates, February 2000, ISBN 1-56592-699-4 です (訳注:和訳は「入門Perl DBI」ISBN 4873110505)。まだ買っていなければ、今すぐ買いましょう。 =head2 Locating drivers (ドライバの置き場所) =begin original Before writing a new driver, it is in your interests to find out whether there already is a driver for your database. If there is such a driver, it would be much easier to make use of it than to write your own! =end original 新しいドライバを書く前に、あなたのデータベースのためのドライバがあるかどうかが気になるでしょう。そのようなドライバがあれば、自分自身で作成するよりももっと簡単です! =begin original The primary web-site for locating Perl software is L. You should look under the various modules listings for the software you are after. For example: =end original Perl ソフトウェアを置いておくための一番の WEB サイトは L です。たくさんのモジュールのリストがあります。例えば: http://search.cpan.org/modlist/Database_Interfaces =begin original Follow the B and B links at the top to see those subsets. =end original これらのサブセットを見るために一番上の B と B のリンクを辿ってください。 =begin original See the B docs for information on B web sites and mailing lists. =end original 情報については B Web サイトの B ドキュメントやメーリングリストをご覧下さい。 =head2 Registering a new driver (新しいドライバを登録する) =begin original Before going through any official registration process, you will need to establish that there is no driver already in the works. You'll do that by asking the B mailing lists whether there is such a driver available, or whether anybody is working on one. =end original 公式の登録処理を始める前に、すでに作業に入っているドライバが無いことを確認する必要があります。 DBI メーリングリストに利用できるそのようなドライバがあるか、だれかがそれについて作業していないかを尋ねることによって、確認することができます。 =begin original When you get the go ahead, you will need to establish the name of the driver and a prefix for the driver. Typically, the name is based on the name of the database software it uses, and the prefix is a contraction of that. Hence, B has the name I and the prefix 'I'. The prefix must be lowercase and contain no underscores other than the one at the end. =end original When you get the go ahead, you will need to establish the name of the driver and a prefix for the driver. Typically, the name is based on the name of the database software it uses, and the prefix is a contraction of that. Hence, B has the name I and the prefix 'I'. The prefix must be lowercase and contain no underscores other than the one at the end. (TBT) =begin original This information will be recorded in the B module. Apart from documentation purposes, registration is a prerequisite for L. =end original This information will be recorded in the B module. Apart from documentation purposes, registration is a prerequisite for L. (TBT) =begin original If you are writing a driver which will not be distributed on CPAN, then you should choose a prefix beginning with 'I', to avoid potential prefix collisions with drivers registered in the future. Thus, if you wrote a non-CPAN distributed driver called B, the prefix might be 'I'. =end original If you are writing a driver which will not be distributed on CPAN, then you should choose a prefix beginning with 'I', to avoid potential prefix collisions with drivers registered in the future. Thus, if you wrote a non-CPAN distributed driver called B, the prefix might be 'I'. (TBT) =begin original This document assumes you are writing a driver called B, and that the prefix 'I' is assigned to the driver. =end original This document assumes you are writing a driver called B, and that the prefix 'I' is assigned to the driver. (TBT) =head2 Two styles of database driver (2 種類のデータベースドライバ) =begin original There are two distinct styles of database driver that can be written to work with the Perl DBI. =end original Perl DBI と共に動作するために書かれるデータベースドライバには二つの異なった種類があります。 =begin original Your driver can be written in pure Perl, requiring no C compiler. When feasible, this is the best solution, but most databases are not written in such a way that this can be done. Some examples of pure Perl drivers are B and B. =end original ドライバを、C コンパイラを必要としないピュア Perl で書くことができます。可能なら、これが最善の解法ですが、ほとんどのデータベースはこれができるような方法で書かれていません。ピュア Perl ドライバの例は B と B です。 =begin original Alternatively, and most commonly, your driver will need to use some C code to gain access to the database. This will be classified as a C/XS driver. =end original もう一つの、そしてより一般的な方法として、ドライバはデータベースへのアクセスを得るためにいくらかの C コードを使うことが必要です。これは C/XS ドライバと分類されます。 =head2 What code will you write? (書く必要のあるコードは?) =begin original There are a number of files that need to be written for either a pure Perl driver or a C/XS driver. There are no extra files needed only by a pure Perl driver, but there are several extra files needed only by a C/XS driver. =end original There are a number of files that need to be written for either a pure Perl driver or a C/XS driver. There are no extra files needed only by a pure Perl driver, but there are several extra files needed only by a C/XS driver. (TBT) =head3 Files common to pure Perl and C/XS drivers =begin original Assuming that your driver is called B, these files are: =end original Assuming that your driver is called B, these files are: (TBT) =over 4 =item * F =item * F =item * F =item * F =item * F =item * F =item * F =item * F =back =begin original The first four files are mandatory. F is used to control how the driver is built and installed. The F file tells people who download the file about how to build the module and any prerequisite software that must be installed. The F file is used by the standard Perl module distribution mechanism. It lists all the source files that need to be distributed with your module. F is what is loaded by the B code; it contains the methods peculiar to your driver. =end original The first four files are mandatory. F is used to control how the driver is built and installed. The F file tells people who download the file about how to build the module and any prerequisite software that must be installed. The F file is used by the standard Perl module distribution mechanism. It lists all the source files that need to be distributed with your module. F is what is loaded by the B code; it contains the methods peculiar to your driver. (TBT) =begin original Although the F file is not B you are advised to create one. Of particular importance are the I and I attributes which newer CPAN modules understand. You use these to tell the CPAN module (and CPANPLUS) that your build and configure mechanisms require DBI. The best reference for META.yml (at the time of writing) is L. You can find a reasonable example of a F in DBD::ODBC. =end original Although the F file is not B you are advised to create one. Of particular importance are the I and I attributes which newer CPAN modules understand. You use these to tell the CPAN module (and CPANPLUS) that your build and configure mechanisms require DBI. The best reference for META.yml (at the time of writing) is L. You can find a reasonable example of a F in DBD::ODBC. (TBT) =begin original The F file allows you to specify other Perl modules on which yours depends in a format that allows someone to type a simple command and ensure that all the pre-requisites are in place as well as building your driver. =end original The F file allows you to specify other Perl modules on which yours depends in a format that allows someone to type a simple command and ensure that all the pre-requisites are in place as well as building your driver. (TBT) =begin original The F file contains (an updated version of) the information that was included - or that would have been included - in the appendices of the Cheetah book as a summary of the abilities of your driver and the associated database. =end original The F file contains (an updated version of) the information that was included - or that would have been included - in the appendices of the Cheetah book as a summary of the abilities of your driver and the associated database. (TBT) =begin original The files in the F subdirectory are unit tests for your driver. You should write your tests as stringently as possible, while taking into account the diversity of installations that you can encounter: =end original The files in the F subdirectory are unit tests for your driver. You should write your tests as stringently as possible, while taking into account the diversity of installations that you can encounter: (TBT) =over 4 =item * =begin original Your tests should not casually modify operational databases. =end original Your tests should not casually modify operational databases. (TBT) =item * =begin original You should never damage existing tables in a database. =end original You should never damage existing tables in a database. (TBT) =item * =begin original You should code your tests to use a constrained name space within the database. For example, the tables (and all other named objects) that are created could all begin with 'I'. =end original You should code your tests to use a constrained name space within the database. For example, the tables (and all other named objects) that are created could all begin with 'I'. (TBT) =item * =begin original At the end of a test run, there should be no testing objects left behind in the database. =end original At the end of a test run, there should be no testing objects left behind in the database. (TBT) =item * =begin original If you create any databases, you should remove them. =end original If you create any databases, you should remove them. (TBT) =item * =begin original If your database supports temporary tables that are automatically removed at the end of a session, then exploit them as often as possible. =end original If your database supports temporary tables that are automatically removed at the end of a session, then exploit them as often as possible. (TBT) =item * =begin original Try to make your tests independent of each other. If you have a test F that depends upon the successful running of F, people cannot run the single test case F. Further, running F twice in a row is likely to fail (at least, if F modifies the database at all) because the database at the start of the second run is not what you saw at the start of the first run. =end original Try to make your tests independent of each other. If you have a test F that depends upon the successful running of F, people cannot run the single test case F. Further, running F twice in a row is likely to fail (at least, if F modifies the database at all) because the database at the start of the second run is not what you saw at the start of the first run. (TBT) =item * =begin original Document in your F file what you do, and what privileges people need to do it. =end original Document in your F file what you do, and what privileges people need to do it. (TBT) =item * =begin original You can, and probably should, sequence your tests by including a test number before an abbreviated version of the test name; the tests are run in the order in which the names are expanded by shell-style globbing. =end original You can, and probably should, sequence your tests by including a test number before an abbreviated version of the test name; the tests are run in the order in which the names are expanded by shell-style globbing. (TBT) =item * =begin original It is in your interests to ensure that your tests work as widely as possible. =end original It is in your interests to ensure that your tests work as widely as possible. (TBT) =back =begin original Many drivers also install sub-modules B for any of a variety of different reasons, such as to support the metadata methods (see the discussion of L below). Such sub-modules are conventionally stored in the directory F. The module itself would usually be in a file F. All such sub-modules should themselves be version stamped (see the discussions far below). =end original Many drivers also install sub-modules B for any of a variety of different reasons, such as to support the metadata methods (see the discussion of L below). Such sub-modules are conventionally stored in the directory F. The module itself would usually be in a file F. All such sub-modules should themselves be version stamped (see the discussions far below). (TBT) =head3 Extra files needed by C/XS drivers =begin original The software for a C/XS driver will typically contain at least four extra files that are not relevant to a pure Perl driver. =end original The software for a C/XS driver will typically contain at least four extra files that are not relevant to a pure Perl driver. (TBT) =over 4 =item * F =item * F =item * F =item * F =back =begin original The F file is used to generate C code that Perl can call to gain access to the C functions you write that will, in turn, call down onto your database software. =end original The F file is used to generate C code that Perl can call to gain access to the C functions you write that will, in turn, call down onto your database software. (TBT) =begin original The F header is a stylized header that ensures you can access the necessary Perl and B macros, types, and function declarations. =end original The F header is a stylized header that ensures you can access the necessary Perl and B macros, types, and function declarations. (TBT) =begin original The F is used to specify which functions have been implemented by your driver. =end original The F is used to specify which functions have been implemented by your driver. (TBT) =begin original The F file is where you write the C code that does the real work of translating between Perl-ish data types and what the database expects to use and return. =end original The F file is where you write the C code that does the real work of translating between Perl-ish data types and what the database expects to use and return. (TBT) =begin original There are some (mainly small, but very important) differences between the contents of F and F for pure Perl and C/XS drivers, so those files are described both in the section on creating a pure Perl driver and in the section on creating a C/XS driver. =end original There are some (mainly small, but very important) differences between the contents of F and F for pure Perl and C/XS drivers, so those files are described both in the section on creating a pure Perl driver and in the section on creating a C/XS driver. (TBT) =begin original Obviously, you can add extra source code files to the list. =end original Obviously, you can add extra source code files to the list. (TBT) =head2 Requirements on a driver and driver writer (ドライバとドライバ作者に必要なこと) =begin original To be remotely useful, your driver must be implemented in a format that allows it to be distributed via CPAN, the Comprehensive Perl Archive Network (L and L). Of course, it is easier if you do not have to meet this criterion, but you will not be able to ask for much help if you do not do so, and no-one is likely to want to install your module if they have to learn a new installation mechanism. =end original To be remotely useful, your driver must be implemented in a format that allows it to be distributed via CPAN, the Comprehensive Perl Archive Network (L and L). Of course, it is easier if you do not have to meet this criterion, but you will not be able to ask for much help if you do not do so, and no-one is likely to want to install your module if they have to learn a new installation mechanism. (TBT) =head1 CREATING A PURE PERL DRIVER (ピュア Perl ドライバを作る) =begin original Writing a pure Perl driver is surprisingly simple. However, there are some problems you should be aware of. The best option is of course picking up an existing driver and carefully modifying one method after the other. =end original 純粋な Perl ドライバを書くことは驚くほど簡単です。しかし気をつけなければならない問題があります。もちろん一番よい選択子は既にあるドライバをピックアップして、注意深く一つ一つののメソッドを変更していくことです。 =begin original Also look carefully at B and B. =end original Also look carefully at B and B. (TBT) =begin original As an example we take a look at the B driver, a driver for accessing plain files as tables, which is part of the B package. =end original 例として B ドライバについて見ていきます; これはプレーンなファイルをテーブルとしてアクセスするもので B の一部です。 =begin original The minimal set of files we have to implement are F, F, F and F. =end original 最低限、実装しなければいけないファイルは F, F, F, F です。 =head2 Pure Perl version of Makefile.PL (ピュア Perl 版の Makefile.PL) =begin original You typically start with writing F, a Makefile generator. The contents of this file are described in detail in the L man pages. It is definitely a good idea if you start reading them. At least you should know about the variables I, I, I, I, I, I, I, I, I, I, I, I, I, I, I, I from the L man page: these are used in almost any F. =end original まず通常は Makefile ジェネレータである F を書くことから始めます。このファイルの内容は L の man ページに詳しく記述されています。まずこれを読むことはとてもよいことです。最低限 L man ページから I, I, I, I, I, I, I, I, I, I, I, I, I, I, I, I 変数について知っておいてください: これらはほとんどすべての F で使われます。 =begin original Additionally read the section on I and the descriptions of the I, I and I targets: They will definitely be useful for you. =end original さらに I (MakeMaker メソッドのオーバーライド)の節や stcheck, disttest, dist ターゲットの説明についても読んでください: それらは間違い無く有用です。 =begin original Of special importance for B drivers is the I method from the L man page. =end original B ドライバにとって特に重要なのは L man ページでの I メソッドです。 =begin original For Emacs users, I recommend the I method, which removes Emacs backup files (file names which end with a tilde '~') from lists of files. =end original Eamcs ユーザには I メソッドをお勧めします; which removes Emacs backup files (file names which end with a tilde '~') from lists of files. (TBT) =begin original Now an example, I use the word C wherever you should insert your driver's name: =end original さて例です; C という単語を使っているところにはあなたのドライバの名前を入れてください: # -*- perl -*- use ExtUtils::MakeMaker; WriteMakefile( dbd_edit_mm_attribs( { 'NAME' => 'DBD::Driver', 'VERSION_FROM' => 'Driver.pm', 'INC' => '', 'dist' => { 'SUFFIX' => '.gz', 'COMPRESS' => 'gzip -9f' }, 'realclean' => { FILES => '*.xsi' }, 'PREREQ_PM' => '1.03', 'CONFIGURE' => sub { eval {require DBI::DBD;}; if ($@) { warn $@; exit 0; } my $dbi_arch_dir = dbd_dbi_arch_dir(); if (exists($opts{INC})) { return {INC => "$opts{INC} -I$dbi_arch_dir"}; } else { return {INC => "-I$dbi_arch_dir"}; } } }, { create_pp_tests => 1}) ); package MY; sub postamble { return main::dbd_postamble(@_); } sub libscan { my ($self, $path) = @_; ($path =~ m/\~$/) ? undef : $path; } =begin original Note the calls to C and C. =end original Note the calls to C and C. (TBT) =begin original The second hash reference in the call to C (containing C) is optional; you should not use it unless your driver is a pure Perl driver (that is, it does not use C and XS code). Therefore, the call to C is not relevant for C/XS drivers and may be omitted; simply use the (single) hash reference containing NAME etc as the only argument to C. =end original The second hash reference in the call to C (containing C) is optional; you should not use it unless your driver is a pure Perl driver (that is, it does not use C and XS code). Therefore, the call to C is not relevant for C/XS drivers and may be omitted; simply use the (single) hash reference containing NAME etc as the only argument to C. (TBT) =begin original Note that the C code will fail if you do not have a F sub-directory containing at least one test case. =end original Note that the C code will fail if you do not have a F sub-directory containing at least one test case. (TBT) =begin original I tells MakeMaker that DBI (version 1.03 in this case) is required for this module. This will issue a warning that DBI 1.03 is missing if someone attempts to install your DBD without DBI 1.03. See I below for why this does not work reliably in stopping cpan testers failing your module if DBI is not installed. =end original I tells MakeMaker that DBI (version 1.03 in this case) is required for this module. This will issue a warning that DBI 1.03 is missing if someone attempts to install your DBD without DBI 1.03. See I below for why this does not work reliably in stopping cpan testers failing your module if DBI is not installed. (TBT) =begin original I is a subroutine called by MakeMaker during C. By putting the C in this section we can attempt to load DBI::DBD but if it is missing we exit with success. As we exit successfully without creating a Makefile when DBI::DBD is missing cpan testers will not report a failure. This may seem at odds with I but I does not cause C to fail (unless you also specify PREREQ_FATAL which is strongly discouraged by MakeMaker) so C would continue to call C and fail. =end original I is a subroutine called by MakeMaker during C. By putting the C in this section we can attempt to load DBI::DBD but if it is missing we exit with success. As we exit successfully without creating a Makefile when DBI::DBD is missing cpan testers will not report a failure. This may seem at odds with I but I does not cause C to fail (unless you also specify PREREQ_FATAL which is strongly discouraged by MakeMaker) so C would continue to call C and fail. (TBT) =begin original All drivers must use C or risk running into problems. =end original All drivers must use C or risk running into problems. (TBT) =begin original Note the specification of I; the named file (F) will be scanned for the first line that looks like an assignment to I<$VERSION>, and the subsequent text will be used to determine the version number. Note the commentary in L on the subject of correctly formatted version numbers. =end original Note the specification of I; the named file (F) will be scanned for the first line that looks like an assignment to I<$VERSION>, and the subsequent text will be used to determine the version number. Note the commentary in L on the subject of correctly formatted version numbers. (TBT) =begin original If your driver depends upon external software (it usually will), you will need to add code to ensure that your environment is workable before the call to C. If you need to check for the existence of an external library and perhaps modify I to include the paths to where the external library header files are located and you cannot find the library or header files make sure you output a message saying they cannot be found but C (success) B calling C or CPAN testers will fail your module if the external library is not found. =end original If your driver depends upon external software (it usually will), you will need to add code to ensure that your environment is workable before the call to C. If you need to check for the existence of an external library and perhaps modify I to include the paths to where the external library header files are located and you cannot find the library or header files make sure you output a message saying they cannot be found but C (success) B calling C or CPAN testers will fail your module if the external library is not found. (TBT) =begin original A full-fledged I can be quite large (for example, the files for B and B are both over 1000 lines long, and the Informix one uses - and creates - auxiliary modules too). =end original A full-fledged I can be quite large (for example, the files for B and B are both over 1000 lines long, and the Informix one uses - and creates - auxiliary modules too). (TBT) =begin original See also L and L. Consider using L in place of I. =end original See also L and L. Consider using L in place of I. (TBT) =head2 README =begin original The L file should describe what the driver is for, the pre-requisites for the build process, the actual build process, how to report errors, and who to report them to. =end original L ファイルは何のためのドライバか、ビルド処理のために事前に必要なことは何か、実際のビルド処理、どうやって誰にエラーを報告するかについて記述するべきです。 =begin original Users will find ways of breaking the driver build and test process which you would never even have dreamed to be possible in your worst nightmares. Therefore, you need to write this document defensively, precisely and concisely. =end original あなたの最悪の悪夢のなかですら思っても見なかったような方法で、利用者はドライバのビルドやテスト処理を失敗させる方法を見つけます。従って、このためこのドキュメントは守りを固めて、正確に、簡潔に書く必要があります。 =begin original As always, use the F from one of the established drivers as a basis for your own; the version in B is worth a look as it has been quite successful in heading off problems. =end original いつも通り、既にあるドライバの F を、あなたのものの基本として使いましょう; the version in B is worth a look as it has been quite successful in heading off problems. (TBT) =over 4 =item * =begin original Note that users will have versions of Perl and B that are both older and newer than you expected, but this will seldom cause much trouble. When it does, it will be because you are using features of B that are not supported in the version they are using. =end original Note that users will have versions of Perl and B that are both older and newer than you expected, but this will seldom cause much trouble. When it does, it will be because you are using features of B that are not supported in the version they are using. (TBT) =item * =begin original Note that users will have versions of the database software that are both older and newer than you expected. You will save yourself time in the long run if you can identify the range of versions which have been tested and warn about versions which are not known to be OK. =end original Note that users will have versions of the database software that are both older and newer than you expected. You will save yourself time in the long run if you can identify the range of versions which have been tested and warn about versions which are not known to be OK. (TBT) =item * =begin original Note that many people trying to install your driver will not be experts in the database software. =end original Note that many people trying to install your driver will not be experts in the database software. (TBT) =item * =begin original Note that many people trying to install your driver will not be experts in C or Perl. =end original Note that many people trying to install your driver will not be experts in C or Perl. (TBT) =back =head2 MANIFEST =begin original The F will be used by the Makefile's dist target to build the distribution tar file that is uploaded to CPAN. It should list every file that you want to include in your distribution, one per line. =end original F は Makefile の dist ターゲットによって、CPAN にアップロードされる配布 tar ファイルを構築するために使われます。配布に含めたいすべてのファイルを 1 行ずつリストにします。 =head2 lib/Bundle/DBD/Driver.pm =begin original The CPAN module provides an extremely powerful bundle mechanism that allows you to specify pre-requisites for your driver. =end original CPAN モジュールは、あなたのドライバにあらかじめ必要なものを指定することを可能とするとても強力なバンドル機構を提供します。 =begin original The primary pre-requisite is B; you may want or need to add some more. With the bundle set up correctly, the user can type: =end original まずあらかじめ必要なものは B; あなたは他のものも欲しかったり、必要だったりするかもしれません。バンドル設定を正しく行えば、ユーザが以下のようにタイプすると: perl -MCPAN -e 'install Bundle::DBD::Driver' =begin original and Perl will download, compile, test and install all the Perl modules needed to build your driver. =end original Perl はあなたのドライバを構築するために必要とされるすべての Perl モジュールをダウンロード、コンパイル、テスト、インストールしてくれます。 =begin original The prerequisite modules are listed in the C section, with the official name of the module followed by a dash and an informal name or description. =end original あらかじめ必要なモジュールは C セクションに、公式の名前とダッシュを付けて非公式な名前または説明を一覧にします。 =over 4 =item * =begin original Listing B as the main pre-requisite simplifies life. =end original B を主要なあらかじめ必要なものとしてリストに載せることは、ものごとを簡単にさせます。 =item * =begin original Don't forget to list your driver. =end original あなたのドライバをリストに載せるのを忘れないで下さい。 =item * =begin original Note that unless the DBMS is itself a Perl module, you cannot list it as a pre-requisite in this file. =end original DBMS そのものは Perl モジュールでなければ、このファイルでのあらかじめ必要なもののリストに載せることが出来ないことに注意してください。 =item * =begin original You should keep the version of the bundle the same as the version of your driver. =end original バンドルのバージョンはあなたのドライバのバージョンと同じにするべきです。 =item * =begin original You should add configuration management, copyright, and licencing information at the top. =end original 構成管理、著作権、ライセンス情報をを加えたいかもしれません。 =back =begin original A suitable skeleton for this file is shown below. =end original このファイルの適切な骨格を以下に示します。 package Bundle::DBD::Driver; $VERSION = '0.01'; 1; __END__ =head1 NAME Bundle::DBD::Driver - A bundle to install all DBD::Driver related modules =head1 SYNOPSIS C =head1 CONTENTS Bundle::DBI - Bundle for DBI by TIMB (Tim Bunce) DBD::Driver - DBD::Driver by YOU (Your Name) =head1 DESCRIPTION This bundle includes all the modules used by the Perl Database Interface (DBI) driver for Driver (DBD::Driver), assuming the use of DBI version 1.13 or later, created by Tim Bunce. If you've not previously used the CPAN module to install any bundles, you will be interrogated during its setup phase. But when you've done it once, it remembers what you told it. You could start by running: C =head1 SEE ALSO Bundle::DBI =head1 AUTHOR Your Name EFE =head1 THANKS This bundle was created by ripping off Bundle::libnet created by Graham Barr EFE, and radically simplified with some information from Jochen Wiedmann EFE. The template was then included in the DBI::DBD documentation by Jonathan Leffler EFE. =cut =head2 lib/DBD/Driver/Summary.pm =begin original There is no substitute for taking the summary file from a driver that was documented in the Perl book (such as B or B or B, to name but three), and adapting it to describe the facilities available via B when accessing the Driver database. =end original There is no substitute for taking the summary file from a driver that was documented in the Perl book (such as B or B or B, to name but three), and adapting it to describe the facilities available via B when accessing the Driver database. (TBT) =head2 Pure Perl version of Driver.pm (ピュア Perl 版の Driver.pm) =begin original The F file defines the Perl module B for your driver. It will define a package B along with some version information, some variable definitions, and a function C which will have a more or less standard structure. =end original F ファイルは Perl モジュール B をあなたのドライバ用として定義します。いくつかのバージョン情報、いくつかの変数定義、そして関数 C とともに、標準よりも多くあるいは少ない構造を持つパッケージ B を定義します。 =begin original It will also define three sub-packages of B: =end original It will also define three sub-packages of B: (TBT) =over 4 =item DBD::Driver::dr =begin original with methods C, C and C; =end original with methods C, C and C; (TBT) =item DBD::Driver::db =begin original with methods such as C; =end original with methods such as C; (TBT) =item DBD::Driver::st =begin original with methods such as C and C. =end original with methods such as C and C. (TBT) =back =begin original The F file will also contain the documentation specific to B in the format used by perldoc. =end original F ファイルには perldoc によって使われるフォーマットで B についての仕様のドキュメントも入れます。 =begin original In a pure Perl driver, the F file is the core of the implementation. You will need to provide all the key methods needed by B. =end original In a pure Perl driver, the F file is the core of the implementation. You will need to provide all the key methods needed by B. (TBT) =begin original Now let's take a closer look at an excerpt of F as an example. We ignore things that are common to any module (even non-DBI modules) or really specific to the B package. =end original さあ例として F の引用について詳しく見てみましょう。どのモジュールにも共通となる(DBI 以外のモジュールでさえ)こと、あるいは本当に B パッケージに特有のものについては無視します。 =head3 The DBD::Driver package =head4 The header package DBD::File; use strict; use vars qw($VERSION $drh); $VERSION = "1.23.00" # Version number of DBD::File =begin original This is where the version number of your driver is specified, and is where F looks for this information. Please ensure that any other modules added with your driver are also version stamped so that CPAN does not get confused. =end original This is where the version number of your driver is specified, and is where F looks for this information. Please ensure that any other modules added with your driver are also version stamped so that CPAN does not get confused. (TBT) =begin original It is recommended that you use a two-part (1.23) or three-part (1.23.45) version number. Also consider the CPAN system, which gets confused and considers version 1.10 to precede version 1.9, so that using a raw CVS, RCS or SCCS version number is probably not appropriate (despite being very common). =end original It is recommended that you use a two-part (1.23) or three-part (1.23.45) version number. Also consider the CPAN system, which gets confused and considers version 1.10 to precede version 1.9, so that using a raw CVS, RCS or SCCS version number is probably not appropriate (despite being very common). (TBT) =begin original For Subversion you could use: =end original For Subversion you could use: (TBT) $VERSION = sprintf("12.%06d", q$Revision: 12345 $ =~ /(\d+)/o); =begin original (use lots of leading zeros on the second portion so if you move the code to a shared repository like svn.perl.org the much larger revision numbers won't cause a problem, at least not for a few years). For RCS or CVS you can use: =end original (use lots of leading zeros on the second portion so if you move the code to a shared repository like svn.perl.org the much larger revision numbers won't cause a problem, at least not for a few years). For RCS or CVS you can use: (TBT) $VERSION = sprintf "%d.%02d", '$Revision: 11.21 $ ' =~ /(\d+)\.(\d+)/; =begin original which pads out the fractional part with leading zeros so all is well (so long as you don't go past x.99) =end original which pads out the fractional part with leading zeros so all is well (so long as you don't go past x.99) (TBT) $drh = undef; # holds driver handle once initialized =begin original This is where the driver handle will be stored, once created. Note that you may assume there is only one handle for your driver. =end original 作成されたら、ここにドライバハンドルが格納されます。ドライバにはたった一つのハンドルしかないと想定できるということに注意してください。 =head4 The driver constructor =begin original The C method is the driver handle constructor. Note that the C method is in the B package, not in one of the sub-packages B, B, or B. =end original C メソッドがドライバハンドルのコンストラクタです。 Note that the C method is in the B package, not in one of the sub-packages B, B, or B. (TBT) sub driver { return $drh if $drh; # already created - return same one my ($class, $attr) = @_; $class .= "::dr"; DBD::Driver::db->install_method('drv_example_dbh_method'); DBD::Driver::st->install_method('drv_example_sth_method'); # not a 'my' since we use it above to prevent multiple drivers $drh = DBI::_new_drh($class, { 'Name' => 'File', 'Version' => $VERSION, 'Attribution' => 'DBD::File by Jochen Wiedmann', }) or return undef; return $drh; } =begin original This is a reasonable example of how B implements its handles. There are three kinds: B (typically stored in I<$drh>; from now on called I or I<$drh>), B (from now on called I or I<$dbh>) and B