
=encoding euc-jp

=head1 NAME

=begin original

DBI - Database independent interface for Perl

=end original

DBI - Perl 用データベース独立インターフェース

(訳注: (TBR)がついている段落は「みんなの自動翻訳＠TexTra」による
機械翻訳です。)

=head1 SYNOPSIS

  use DBI;

  @driver_names = DBI->available_drivers;
  %drivers      = DBI->installed_drivers;
  @data_sources = DBI->data_sources($driver_name, \%attr);

  $dbh = DBI->connect($data_source, $username, $auth, \%attr);

  $rv  = $dbh->do($statement);
  $rv  = $dbh->do($statement, \%attr);
  $rv  = $dbh->do($statement, \%attr, @bind_values);

  $ary_ref  = $dbh->selectall_arrayref($statement);
  $hash_ref = $dbh->selectall_hashref($statement, $key_field);

  $ary_ref  = $dbh->selectcol_arrayref($statement);
  $ary_ref  = $dbh->selectcol_arrayref($statement, \%attr);

  @row_ary  = $dbh->selectrow_array($statement);
  $ary_ref  = $dbh->selectrow_arrayref($statement);
  $hash_ref = $dbh->selectrow_hashref($statement);

  $sth = $dbh->prepare($statement);
  $sth = $dbh->prepare_cached($statement);

  $rc = $sth->bind_param($p_num, $bind_value);
  $rc = $sth->bind_param($p_num, $bind_value, $bind_type);
  $rc = $sth->bind_param($p_num, $bind_value, \%attr);

  $rv = $sth->execute;
  $rv = $sth->execute(@bind_values);
  $rv = $sth->execute_array(\%attr, ...);

  $rc = $sth->bind_col($col_num, \$col_variable);
  $rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind);

  @row_ary  = $sth->fetchrow_array;
  $ary_ref  = $sth->fetchrow_arrayref;
  $hash_ref = $sth->fetchrow_hashref;

  $ary_ref  = $sth->fetchall_arrayref;
  $ary_ref  = $sth->fetchall_arrayref( $slice, $max_rows );

  $hash_ref = $sth->fetchall_hashref( $key_field );

  $rv  = $sth->rows;

  $rc  = $dbh->begin_work;
  $rc  = $dbh->commit;
  $rc  = $dbh->rollback;

  $quoted_string = $dbh->quote($string);

  $rc  = $h->err;
  $str = $h->errstr;
  $rv  = $h->state;

  $rc  = $dbh->disconnect;

=begin original

I<The synopsis above only lists the major methods and parameters.>

=end original

I<上記の概略は主なメソッドとパラメータだけをリストにしています。>

=head2 GETTING HELP

(助けを得る)

=begin original

If you have questions about DBI, or DBD driver modules, you can get
help from the I<dbi-users@perl.org> mailing list.  You don't have to subscribe
to the list in order to post, though I'd recommend it. You can get help on
subscribing and using the list by emailing I<dbi-users-help@perl.org>.

=end original

DBI や DBD ドライバモジュールに関する質問があるなら、
I<dbi-users@perl.org> メーリングリストで助けを得られます。
投稿するのにメーリングリストの購読は必要ではありませんが、購読することを
勧めます。
I<dbi-users-help@perl.org> にメールすることで、メーリングリストの購読および
使用に関する助けが得られます。

=begin original

I don't recommend the DBI cpanforum (at http://www.cpanforum.com/dist/DBI)
because relatively few people read it compared with dbi-users@perl.org.

=end original

私は DBI cpanforum (at http://www.cpanforum.com/dist/DBI) は勧めません;
dbi-users@perl.org に比べて読んでいる人数が少ないからです。

=begin original

To help you make the best use of the dbi-users mailing list,
and any other lists or forums you may use, I I<strongly>
recommend that you read "How To Ask Questions The Smart Way"
by Eric Raymond: L<http://www.catb.org/~esr/faqs/smart-questions.html>.

=end original

dbi-users メーリングリストや、その他のメーリングリストやフォーラムを
うまく利用するために、私は Eric Raymond による
"How To Ask Questions The Smart Way"
L<http://www.catb.org/~esr/faqs/smart-questions.html>
(和訳:「賢い質問のしかた」
L<http://www.ranvis.com/articles/smart-questions.ja.html>) を
読むことを I<強く> 勧めます。

=begin original

If you think you've found a bug then please also read
"How to Report Bugs Effectively" by Simon Tatham:
L<http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>.

=end original

バグを発見したと思ったら、Simon Tatham による
"How to Report Bugs Effectively"
L<http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>
(和訳: 「効果的にバグを報告するには」
L<http://www.chiark.greenend.org.uk/~sgtatham/bugs-jp.html>) も
読んでください。

=begin original

The DBI home page at L<http://dbi.perl.org/> and the DBI FAQ
at L<http://faq.dbi-support.com/> are always worth a visit.
They include links to other resources.

=end original

L<http://dbi.perl.org/> の DBI ホームページと
L<http://faq.dbi-support.com/> の DBI FAQ は常に訪れる価値のある場所です。
これらには他のリソースへのリンクもあります。

=begin original

Before asking any questions, reread this document, consult the
archives and read the DBI FAQ. The archives are listed
at the end of this document and on the DBI home page.

=end original

質問をする前に、このドキュメントを読み返し、アーカイブをあたり、DBI FAQ を
読んでください。
アーカイブはこのリストの最後と DBI ホームページに一覧があります。

=begin original

This document often uses terms like I<references>, I<objects>,
I<methods>.  If you're not familiar with those terms then it would
be a good idea to read at least the following perl manuals first:
L<perlreftut>, L<perldsc>, L<perllol>, and L<perlboot>.

=end original

この文書にはしばしば I<リファレンス>, I<オブジェクト>, I<メソッド> といった
用語を使います。
これらの用語に親しみがないなら、少なくとも以下のマニュアルを先に読むのが
いい考えです:
L<perlreftut>, L<perldsc>, L<perllol>, L<perlboot>

=begin original

Please note that Tim Bunce does not maintain the mailing lists or the
web page (generous volunteers do that).  So please don't send mail
directly to him; he just doesn't have the time to answer questions
personally. The I<dbi-users> mailing list has lots of experienced
people who should be able to help you if you need it. If you do email
Tim he is very likely to just forward it to the mailing list.

=end original

Tim Bunce がそのメーリングリストや Web ページを管理しているわけでは
ないことに注意してください(通常はボランティアがやっています)。
そのため彼に直接メールを送らないで下さい; 彼には個人的に質問に答える時間が
ないだけです。
I<dbi-users> メーリングリストは経験豊富な人たちがたくさんいて、必要であれば
あなたを助けてくれるでしょう。
Tim にメールしても、おそらく単にメーリングリストに転送されるでしょう。

=head2 NOTES

(注意)

=begin original

This is the DBI specification that corresponds to the DBI version 1.612
($Revision$).

=end original

これは DBI バージョン1.612 ($Revision$) に対応した DBI の仕様です。

=begin original

The DBI is evolving at a steady pace, so it's good to check that
you have the latest copy.

=end original

DBI の仕様は、現在、確実なペースで更新されています。
最新のものを持っているかをチェックしてください。

=begin original

The significant user-visible changes in each release are documented
in the L<DBI::Changes> module so you can read them by executing
C<perldoc DBI::Changes>.

=end original

リリース毎のユーザーに見える重要な変更は L<DBI::Changes> モジュールに
文書化されているので、C<perldoc DBI::Changes> を実行することで
これを読むことができます。

=begin original

Some DBI changes require changes in the drivers, but the drivers
can take some time to catch up. Newer versions of the DBI have
added features that may not yet be supported by the drivers you
use.  Talk to the authors of your drivers if you need a new feature
that is not yet supported.

=end original

DBI の変更によってドライバの変更が必要になる場合もありますが、
ドライバは追いつくのに少し時間がかかります。
新しいバージョンの DBI は、今使っているドライバではまだ対応していない
機能を追加していることもあります。
もしまだ対応していない新しい機能が必要なら、ドライバの作者に
話してみてください。

=begin original

Features added after DBI 1.21 (February 2002) are marked in the
text with the version number of the DBI release they first appeared in.

=end original

DBI 1.21 (2002 年 2 月) 以降に追加された機能については、最初に
追加された DBI リリースのバージョン番号を文章中に記しています。

=begin original

Extensions to the DBI API often use the C<DBIx::*> namespace.
See L</Naming Conventions and Name Space>. DBI extension modules
can be found at L<http://search.cpan.org/search?mode=module&query=DBIx>.
And all modules related to the DBI can be found at
L<http://search.cpan.org/search?query=DBI&mode=all>.

=end original

DBI API のエクステンションはしばしば C<DBIx::*> 名前空間が使われます。
L</Naming Conventions and Name Space> を参照してください。
DBI エクステンションモジュールは
L<http://search.cpan.org/search?mode=module&query=DBIx> にあります。
DBI 関連の全てのモジュールは
L<http://search.cpan.org/search?query=DBI&mode=all> にあります。

=cut

=head1 DESCRIPTION

=begin original

The DBI is a database access module for the Perl programming language.  It defines
a set of methods, variables, and conventions that provide a consistent
database interface, independent of the actual database being used.

=end original

DBI は Perl プログラミング言語のためのデータベースアクセスモジュールです。
それはセットになったメソッド、変数そして規約を定義し、実際の使われている
データベースに依存しない一貫性のあるデータベースインターフェースを
提供します。

=begin original

It is important to remember that the DBI is just an interface.
The DBI is a layer
of "glue" between an application and one or more database I<driver>
modules.  It is the driver modules which do most of the real work. The DBI
provides a standard interface and framework for the drivers to operate
within.

=end original

DBI が単なるインターフェースであることを忘れないことは重要です。
DBI はアプリケーションと一つまたは複数のデータベース I<ドライバ>
モジュールとを結び付ける薄い「糊」の層なのです。
実際に働くのはドライバモジュールです。
DBI はドライバを操作するための標準のインターフェースと枠組みを提供します。

=head2 Architecture of a DBI Application

(DBI アプリケーションのアーキテクチャ)

             |<- Scope of DBI ->|
                  .-.   .--------------.   .-------------.
  .-------.       | |---| XYZ Driver   |---| XYZ Engine  |
  | Perl  |       | |   `--------------'   `-------------'
  | script|  |A|  |D|   .--------------.   .-------------.
  | using |--|P|--|B|---|Oracle Driver |---|Oracle Engine|
  | DBI   |  |I|  |I|   `--------------'   `-------------'
  | API   |       | |...
  |methods|       | |... Other drivers
  `-------'       | |...
                  `-'

=begin original

The API, or Application Programming Interface, defines the
call interface and variables for Perl scripts to use. The API
is implemented by the Perl DBI extension.

=end original

API、つまりアプリケーション・プログラミング・インターフェースは
Perl スクリプトが使うための呼び出しインタフェースと変数を定義します。
API は Perl DBI エクステンションによって実装されます。

=begin original

The DBI "dispatches" the method calls to the appropriate driver for
actual execution.  The DBI is also responsible for the dynamic loading
of drivers, error checking and handling, providing default
implementations for methods, and many other non-database specific duties.

=end original

DBI は適切なドライバへ実際の実行のためにメソッド呼び出しを
「発行」(dispatch)します。
DBI はドライバの動的なロード、エラーのチェック/操作、メソッドのための
デフォルトの実装の提供、その他たくさんのデータベース特有なこと以外にも
責任を持ちます。

=begin original

Each driver
contains implementations of the DBI methods using the
private interface functions of the corresponding database engine.  Only authors
of sophisticated/multi-database applications or generic library
functions need be concerned with drivers.

=end original

各ドライバは対応するデータベースエンジンのプライベートなインターフェース
関数を使い、DBI メソッドの実装を持ちます。
高度な/複数のデータベースに対応するアプリーケーションや
汎用ライブラリ関数の作成者だけが、このドライバに関心をもつ必要があります。

=head2 Notation and Conventions

(記法と規約)

=begin original

The following conventions are used in this document:

=end original

このドキュメントでは以下の表記法を使用します:

=begin original

  $dbh    Database handle object
  $sth    Statement handle object
  $drh    Driver handle object (rarely seen or used in applications)
  $h      Any of the handle types above ($dbh, $sth, or $drh)
  $rc     General Return Code  (boolean: true=ok, false=error)
  $rv     General Return Value (typically an integer)
  @ary    List of values returned from the database, typically a row of data
  $rows   Number of rows processed (if available, else -1)
  $fh     A filehandle
  undef   NULL values are represented by undefined values in Perl
  \%attr  Reference to a hash of attribute values passed to methods

=end original

  $dbh    データベースハンドルオブジェクト
  $sth    文ハンドルオブジェクト
  $drh    ドライバハンドルオブジェクト(アプリケーションで目にしたり、使ったりすることはまずありません)
  $h      上記のハンドルのどれか
  $rc     一般的な戻り値(コード)(真偽値: 真=OK, 偽=エラー)
  $rv     一般的な戻り値(値) (通常はinteger)
  @ary    データベースから返される値のリスト。通常はデータの行
  $rows   処理された行の数 (もしあれば。なければ -1)
  $fh     ファイルハンドル
  undef   Perl では NULL値は未定義値で表現される
  \%attr  メソッドに渡される属性値のハッシュのリファレンス

=begin original

Note that Perl will automatically destroy database and statement handle objects
if all references to them are deleted.

=end original

注意:そこへの参照がすべて削除されると、Perl は、自動的にデータベースと
ステートメントオブジェクトを破壊します。

=head2 Outline Usage

(使用法の概要)

=begin original

To use DBI,
first you need to load the DBI module:

=end original

DBI を使うためには、まず DBI モジュールをロードする必要があります:

  use DBI;
  use strict;

=begin original

(The C<use strict;> isn't required but is strongly recommended.)

=end original

(C<use strict;> は必須ではありませんが、強く推奨します。)

=begin original

Then you need to L</connect> to your data source and get a I<handle> for that
connection:

=end original

そしてデータソースに接続(L</connect>)し、その接続のための
I<ハンドル> を取得します:

  $dbh = DBI->connect($dsn, $user, $password,
                      { RaiseError => 1, AutoCommit => 0 });

=begin original

Since connecting can be expensive, you generally just connect at the
start of your program and disconnect at the end.

=end original

接続にはコストがかかるので、一般的にはプログラムの開始した時点で接続し、
終わりで切断します:

=begin original

Explicitly defining the required C<AutoCommit> behaviour is strongly
recommended and may become mandatory in a later version.  This
determines whether changes are automatically committed to the
database when executed, or need to be explicitly committed later.

=end original

要求される C<AutoCommit> の動きを明示的に定義することは強く推奨されます。
将来のバージョンでは必須になるかもしれません。
これは実行したときに変更を自動的にデータベースにコミットするか、後から
明示的にコミットされる必要があるかを決定します。

=begin original

The DBI allows an application to "prepare" statements for later
execution.  A prepared statement is identified by a statement handle
held in a Perl variable.
We'll call the Perl variable C<$sth> in our examples.

=end original

DBI では、アプリケーションはSQL文を後で実行するための
"prepare"(=準備)をしておくことができます。
prepare された文は Perl 変数に入った文ハンドルにより
識別されます。
この例ではその Perl 変数を $sth とします。

=begin original

The typical method call sequence for a C<SELECT> statement is:

=end original

C<SELECT> 文のための典型的なメソッドの順番は以下のようになります:

  prepare,
    execute, fetch, fetch, ...
    execute, fetch, fetch, ...
    execute, fetch, fetch, ...

=begin original

for example:

=end original

例:

  $sth = $dbh->prepare("SELECT foo, bar FROM table WHERE baz=?");

  $sth->execute( $baz );

  while ( @row = $sth->fetchrow_array ) {
    print "@row\n";
  }

=begin original

The typical method call sequence for a I<non>-C<SELECT> statement is:

=end original

C<SELECT> 文 I<以外> のための典型的なメソッドの順番は
以下のようになります:

  prepare,
    execute,
    execute,
    execute.

=begin original

for example:

=end original

例:

  $sth = $dbh->prepare("INSERT INTO table(foo,bar,baz) VALUES (?,?,?)");

  while(<CSV>) {
    chomp;
    my ($foo,$bar,$baz) = split /,/;
	$sth->execute( $foo, $bar, $baz );
  }

=begin original

The C<do()> method can be used for non repeated I<non>-C<SELECT> statement
(or with drivers that don't support placeholders):

=end original

C<do()> メソッドは繰り返されない C<SELECT> I<以外> の文のために
(またはプレースホルダをサポートしないドライバで)使うことができます:

  $rows_affected = $dbh->do("UPDATE your_table SET foo = foo + 1");

=begin original

To commit your changes to the database (when L</AutoCommit> is off):

=end original

データベースへの変更をコミットするためには(L</AutoCommit> がオフの時):

  $dbh->commit;  # or call $dbh->rollback; to undo changes

=begin original

Finally, when you have finished working with the data source, you should
L</disconnect> from it:

=end original

最後に、データソースでの作業を終了するときにはそこから
切断(L</disconnect> )しなければいけません:

  $dbh->disconnect;

=head2 General Interface Rules & Caveats

(一般的なインターフェース規則と留意事項)

=begin original

The DBI does not have a concept of a "current session". Every session
has a handle object (i.e., a C<$dbh>) returned from the C<connect> method.
That handle object is used to invoke database related methods.

=end original

DBI には「現在のセッション」という考えはありません。
各セッションは C<connect>メソッドから返されるハンドルオブジェクト
(つまり C<$dbh>)を持ちます。
そのハンドルオブジェクトがデータベース関連のメソッドを呼び出すために
使われます。

=begin original

Most data is returned to the Perl script as strings. (Null values are
returned as C<undef>.)  This allows arbitrary precision numeric data to be
handled without loss of accuracy.  Beware that Perl may not preserve
the same accuracy when the string is used as a number.

=end original

ほとんどのデータは文字列として Perl スクリプトに返されます(Null 値は
C<undef> として返されます)。
これにより任意の桁数の数値データを精度を落とすことなく扱うことができます。
文字列を数値として扱う際に、Perl が同じ精度を保たないかも
しれないということに注意してください。

=begin original

Dates and times are returned as character strings in the current
default format of the corresponding database engine.  Time zone effects
are database/driver dependent.

=end original

日付(Date)、時刻(Time)は、対応するデータベースエンジンの現在の
デフォルトフォーマットの文字列として返されます。
時間帯の影響はデータベース／ドライバに存します。

=begin original

Perl supports binary data in Perl strings, and the DBI will pass binary
data to and from the driver without change. It is up to the driver
implementors to decide how they wish to handle such binary data.

=end original

Perl スクリプトは文字列のなかにあるバイナリデータをサポートします。
DBI はバイナリデータを変更することなく、ドライバとやりとりします。
そのようなバイナリデータをどのように扱いたいのかを決めることはドライバの
実装者次第です。

=begin original

Perl supports two kinds of strings: Unicode (utf8 internally) and non-Unicode
(defaults to iso-8859-1 if forced to assume an encoding).  Drivers should
accept both kinds of strings and, if required, convert them to the character
set of the database being used. Similarly, when fetching from the database
character data that isn't iso-8859-1 the driver should convert it into utf8.

=end original

Perl は 2 種類の文字列に対応しています: Unicode (内部では utf8) と
非-Unicode (もしエンコーディングを仮定することを強制されるなら
デフォルトは iso-8859-1)。
ドライバはどちらの種類の文字列も受け付けて、もし必要ならデータベースが
使っている文字集合に変換できるべきです。
同様に、iso-8859-1 でない データベース文字データをフェッチしたときには、
ドライバは utf8 に変換するべきです。

=begin original

Multiple SQL statements may not be combined in a single statement
handle (C<$sth>), although some databases and drivers do support this
(notably Sybase and SQL Server).

=end original

データベース、ドライバによってはそれをサポートしているとしても
(特に Sybaseと SQL Server)、複数の SQL 文は１つの
文ハンドル($sth)に結び付けられないかもしれません。

=begin original

Non-sequential record reads are not supported in this version of the DBI.
In other words, records can only be fetched in the order that the
database returned them, and once fetched they are forgotten.

=end original

このバージョンの DBI では順序通りでないレコードの読み込みはできません。
いいかえればレコードは、データベースが返してきた順序にしか
取り出すことはできませんし、一度取り出されると忘れ去られてしまいます。

=begin original

Positioned updates and deletes are not directly supported by the DBI.
See the description of the C<CursorName> attribute for an alternative.

=end original

位置づけての更新、削除を DBI は直接サポートしていません。
その代わりとして C<CursorName> 属性の説明をご覧ください。

=begin original

Individual driver implementors are free to provide any private
functions and/or handle attributes that they feel are useful.
Private driver functions can be invoked using the DBI C<func()> method.
Private driver attributes are accessed just like standard attributes.

=end original

各ドライバを実装する開発者は、使いやすいと思えば、プライベートな関数や
属性を自由に提供することができます。
プライベートなドライバ関数は DBI の C<func()> メソッドを使って
呼び出すことができます。
プライベートなドライバ属性は標準の属性とまったく同じように
アクセスすることができます。

=begin original

Many methods have an optional C<\%attr> parameter which can be used to
pass information to the driver implementing the method. Except where
specifically documented, the C<\%attr> parameter can only be used to pass
driver specific hints. In general, you can ignore C<\%attr> parameters
or pass it as C<undef>.

=end original

多くのメソッドはオプションとして C<\%attr> パラメータを受け取ります。
これを使ってドライバが実装しているメソッドに情報を渡すことができます。
特に記述されていなければ、C<\%attr> パラメータは特定のヒントを渡す場合にのみ
使用されます。
普通は C<\%attr> パラメータを無視するか C<undef> を渡すことができます。

=head2 Naming Conventions and Name Space

(命名規則と名前空間)

=begin original

The DBI package and all packages below it (C<DBI::*>) are reserved for
use by the DBI. Extensions and related modules use the C<DBIx::>
namespace (see L<http://www.perl.com/CPAN/modules/by-module/DBIx/>).
Package names beginning with C<DBD::> are reserved for use
by DBI database drivers.  All environment variables used by the DBI
or by individual DBDs begin with "C<DBI_>" or "C<DBD_>".

=end original

DBI パッケージとその下のパッケージ(C<DBI::*>)　は、DBI によって
予約されてます。
エクステンションと関連するモジュールは C<DBIx::> 名前空間
(http://www.perl.com/CPAN/modules/by-module/DBIx/をご覧下さい)を使います。
C<DBD::> で始まるパッケージ名は DBI データベースドライバによって
使うように予約されています。
DBI または各 DBD によって使われるすべての環境変数は "C<DBI_>" または
"C<DBD_>" で始まります。

=begin original

The letter case used for attribute names is significant and plays an
important part in the portability of DBI scripts.  The case of the
attribute name is used to signify who defined the meaning of that name
and its values.

=end original

属性の名前に使われる文字の大文字/小文字の区別は、DBI スクリプトの
移植性において重要で大きな役割を果たしています。
属性の名前が大文字か小文字かによって、名前と値を誰が決めたのかを示すのに
使われています。

=begin original

  Case of name  Has a meaning defined by
  ------------  ------------------------
  UPPER_CASE    Standards, e.g.,  X/Open, ISO SQL92 etc (portable)
  MixedCase     DBI API (portable), underscores are not used.
  lower_case    Driver or database engine specific (non-portable)

=end original

  名前の大文字／小文字   説明
  ---------------------- -------------------------------------------
  大文字のみ(UPPER_CASE) 標準、つまり X/Open, SQL92 など(移植性あり)
  混合(MixedCase)        DBI API(移植性性あり)アンダースコア(_)は使わない
  小文字のみ(lower_case) ドライバもしくはエンジンに特有(移植性なし)

=begin original

It is of the utmost importance that Driver developers only use
lowercase attribute names when defining private attributes. Private
attribute names must be prefixed with the driver name or suitable
abbreviation (e.g., "C<ora_>" for Oracle, "C<ing_>" for Ingres, etc).

=end original

最も重要なのはドライバ開発者はプライベートな属性を定義するとき、小文字の
属性しか使ってはいけないといことです。
プライベートな属性の名前は、ドライバ名もしくは適切な略語から始まらなければ
なりません。
(例えば C<ora_> はOracle, C<ing_> は Ingres など).

=head2 SQL - A Query Language

(SQL - 問い合わせ言語)

=begin original

Most DBI drivers require applications to use a dialect of SQL
(Structured Query Language) to interact with the database engine.
The L</"Standards Reference Information"> section provides links
to useful information about SQL.

=end original

大半の DBI ドライバではデータベースエンジンとのやりとりに、それぞれの
SQL(Structured Query Language) を使うことが要求とします。
L</"Standards Reference Information"> 章は SQL に関する有用な情報への
リンクを提供しています。

=begin original

The DBI itself does not mandate or require any particular language to
be used; it is language independent. In ODBC terms, the DBI is in
"pass-thru" mode, although individual drivers might not be. The only requirement
is that queries and other statements must be expressed as a single
string of characters passed as the first argument to the L</prepare> or
L</do> methods.

=end original

DBI 自身は特定の言語を使うことを必須とも必要ともしていません;言語から
独立しています。
ODBC の用語でいうとDBI は「パススルー」モード(='pass-thru' mode)に
あたります。
各ドライバはそうでないかもしれません。
唯一必要なことは、L</prepare> または L</do> メソッドへの最初の引数として
渡される問い合せまたはその他の文は、文字による一つの文字列として
表現されなければならないことです。

=begin original

For an interesting diversion on the I<real> history of RDBMS and SQL,
from the people who made it happen, see:

=end original

RDBMS と SQL の I<本当の> 歴史についての興味深いこぼれ話が、実際にそれを
やった人達から出されています:

  http://ftp.digital.com/pub/DEC/SRC/technical-notes/SRC-1997-018-html/sqlr95.html

=begin original

Follow the "Full Contents" then "Intergalactic dataspeak" links for the
SQL history.

=end original

SQLの歴史については
"Full Contents" から "Intergalactic dataspeak" リンクを追ってみてください。

=head2 Placeholders and Bind Values

(プレースホルダとバインド値)

=begin original

Some drivers support placeholders and bind values.
I<Placeholders>, also called parameter markers, are used to indicate
values in a database statement that will be supplied later,
before the prepared statement is executed.  For example, an application
might use the following to insert a row of data into the SALES table:

=end original

ある種のドライバはプレースホルダとバインド値をサポートしています。
プレースホルダはパラメータ・マーカーとも呼ばれ、データベース文の
中の値が後で、準備(prepare)された文が実行される前に
与えられることを示すために使われます。
例えば、以下のようにして、SALES テーブルに行を挿入することができます:

  INSERT INTO sales (product_code, qty, price) VALUES (?, ?, ?)

=begin original

or the following, to select the description for a product:

=end original

あるいは PRODUCTS テーブルから製品の説明 (description) を取得できます

  SELECT description FROM products WHERE product_code = ?

=begin original

The C<?> characters are the placeholders.  The association of actual
values with placeholders is known as I<binding>, and the values are
referred to as I<bind values>.
Note that the C<?> is not enclosed in quotation marks, even when the
placeholder represents a string.

=end original

C<?> という文字がプレースホルダです。
実際の値とプレースホルダとの結びつけが I<バインド>(binding)で、値は
I<バインド値>(bind values) として呼ばれます。
プレースホルダが文字列を表わしているとしても、C<?> が
クォーテーションマークで囲まれていないことに注意してください。

=begin original

Some drivers also allow placeholders like C<:>I<name> and C<:>I<N> (e.g.,
C<:1>, C<:2>, and so on) in addition to C<?>, but their use is not portable.

=end original

ドライバによっては、C<?> だけでなく、C<:>I<名前> や C<:>I<番号>
(例えば C<:1>, C<:2> など)といった形式のプレースホルダを
許しているものもありますが、それは移植可能ではありません。

=begin original

If the C<:>I<N> form of placeholder is supported by the driver you're using,
then you should be able to use either L</bind_param> or L</execute> to bind
values. Check your driver documentation.

=end original

使っているドライバが C<:>I<N> 形式のプレースフォルダに対応しているなら、
値をバインドするのに L</bind_param> あるいは L</execute> を使えるべきです。
ドライバの文書をチェックしてみて下さい。

=begin original

With most drivers, placeholders can't be used for any element of a
statement that would prevent the database server from validating the
statement and creating a query execution plan for it. For example:

=end original

データベースサーバでの文の評価ができず、そのため問い合わせ
計画を作成できなくなるために、多くのドライバではプレースホルダをすべての
文の要素として使えるということではありません。
例えば:

  "SELECT name, age FROM ?"         # wrong (will probably fail)
  "SELECT name, ?   FROM people"    # wrong (but may not 'fail')

=begin original

Also, placeholders can only represent single scalar values.
For example, the following
statement won't work as expected for more than one value:

=end original

またプレースホルダは一つのスカラ値だけを表わします。
例えば以下の文は複数の値を期待してもうまくいかいないでしょう:

  "SELECT name, age FROM people WHERE name IN (?)"    # wrong
  "SELECT name, age FROM people WHERE name IN (?,?)"  # two names

=begin original

When using placeholders with the SQL C<LIKE> qualifier, you must
remember that the placeholder substitutes for the whole string.
So you should use "C<... LIKE ? ...>" and include any wildcard
characters in the value that you bind to the placeholder.

=end original

プレースホルダを SQL の C<LIKE> 修飾子と使う場合には、プレースホルダは
文字列全体を置き換えることを忘れてはいけません。
そのため "C<... LIKE ? ...>" を使い、プレースホルダにバインドする値に
ワイルドカードとなる文字をすべて入れなければなりません。

=begin original

B<NULL Values>

=end original

B<NULL 値>

=begin original

Undefined values, or C<undef>, are used to indicate NULL values.
You can insert and update columns with a NULL value as you would a
non-NULL value.  These examples insert and update the column
C<age> with a NULL value:

=end original

未定義値 (C<undef>) は NULL 値を示すのに使われます。
非 NULL 値と同様、NULL 値で列を挿入および更新できます。
以下は C<age> 列を NULL 値で挿入および更新する例です:

  $sth = $dbh->prepare(qq{
    INSERT INTO people (fullname, age) VALUES (?, ?)
  });
  $sth->execute("Joe Bloggs", undef);

  $sth = $dbh->prepare(qq{
    UPDATE people SET age = ? WHERE fullname = ?
  });
  $sth->execute(undef, "Joe Bloggs");

=begin original

However, care must be taken when trying to use NULL values in a
C<WHERE> clause.  Consider:

=end original

しかし C<WHERE> 句で NULL 値を使う場合には特に注意が必要です。
以下のような場合について考えてみましょう:

  SELECT fullname FROM people WHERE age = ?

=begin original

Binding an C<undef> (NULL) to the placeholder will I<not> select rows
which have a NULL C<age>!  At least for database engines that
conform to the SQL standard.  Refer to the SQL manual for your database
engine or any SQL book for the reasons for this.  To explicitly select
NULLs you have to say "C<WHERE age IS NULL>".

=end original

C<undef> (NULL) をプレースホルダにバインドしても、NULLの C<age> を持つ行は
何も I<選択されません>！
少なくとも SQL 標準に準拠いているデータベースエンジンではそうです。
この理由については、使用しているデータベースエンジンの SQL のマニュアル
または SQL の解説書をご覧ください。
明示的に NULL を SELECT するためには "C<WHERE age IS NULL>"とする必要が
あります。

=begin original

A common issue is to have a code fragment handle a value that could be
either C<defined> or C<undef> (non-NULL or NULL) at runtime.
A simple technique is to prepare the appropriate statement as needed,
and substitute the placeholder for non-NULL cases:

=end original

よくある問題の一つは、実行時に C<defined> か C<undef> か
(非 NULL か NULL か)決定される値を扱うためのコードがあるときです。
簡単なテクニックは、必要に応じて適切な分を準備して、非 NULL の場合の
プレースフォルダを置き換えることです:

  $sql_clause = defined $age? "age = ?" : "age IS NULL";
  $sth = $dbh->prepare(qq{
    SELECT fullname FROM people WHERE $sql_clause
  });
  $sth->execute(defined $age ? $age : ());

=begin original

The following technique illustrates qualifying a C<WHERE> clause with
several columns, whose associated values (C<defined> or C<undef>) are
in a hash %h:

=end original

以下のテクニックは、結びつける値 (C<defined> or C<undef>) がハッシュ %h に
入っている複数の列の C<WHERE> 句の作成方法を示しています:

  for my $col ("age", "phone", "email") {
    if (defined $h{$col}) {
      push @sql_qual, "$col = ?";
      push @sql_bind, $h{$col};
    }
    else {
      push @sql_qual, "$col IS NULL";
    }
  }
  $sql_clause = join(" AND ", @sql_qual);
  $sth = $dbh->prepare(qq{
      SELECT fullname FROM people WHERE $sql_clause
  });
  $sth->execute(@sql_bind);

=begin original

The techniques above call prepare for the SQL statement with each call to
execute.  Because calls to prepare() can be expensive, performance
can suffer when an application iterates many times over statements
like the above.

=end original

上述のテクニックは実行するそれぞれの呼び出しの SQL 文のために prepare を
呼び出します。
prepare() の呼び出しはコストが高いので、上述のようにアプリケーションが
文を何回も繰り返すと性能に影響を与えるかもしれません。

=begin original

A better solution is a single C<WHERE> clause that supports both
NULL and non-NULL comparisons.  Its SQL statement would need to be
prepared only once for all cases, thus improving performance.
Several examples of C<WHERE> clauses that support this are presented
below.  But each example lacks portability, robustness, or simplicity.
Whether an example is supported on your database engine depends on
what SQL extensions it provides, and where it supports the C<?>
placeholder in a statement.

=end original

よりよい解決法は、NULL と非 NULL 比較の両方に対応した単一の
C<WHERE> 句です。
この SQL 文は全ての場合に置いて 1 回だけ prepare する必要があるので、
性能が向上します。
これに対応するためのいくつかの C<WHERE> 句の例を以下に示します。
しかしそれぞれの例には互換性、堅牢性、単純性に欠けています。
あなたが使うデータベースエンジンでどの例が対応しているかは、
どの SQL 拡張を提供しているかと、文中のどこに C<?> プレースホルダが
対応しているかに依存します。

  0)  age = ?
  1)  NVL(age, xx) = NVL(?, xx)
  2)  ISNULL(age, xx) = ISNULL(?, xx)
  3)  DECODE(age, ?, 1, 0) = 1
  4)  age = ? OR (age IS NULL AND ? IS NULL)
  5)  age = ? OR (age IS NULL AND SP_ISNULL(?) = 1)
  6)  age = ? OR (age IS NULL AND ? = 1)

=begin original

Statements formed with the above C<WHERE> clauses require execute
statements as follows.  The arguments are required, whether their
values are C<defined> or C<undef>.

=end original

上述の C<WHERE> 句の形式の文は、以下のように文を実行する必要があります。
値が C<defined> か C<undef> かを示す引数が必要です。

  0,1,2,3)  $sth->execute($age);
  4,5)      $sth->execute($age, $age);
  6)        $sth->execute($age, defined($age) ? 0 : 1);

=begin original

Example 0 should not work (as mentioned earlier), but may work on
a few database engines anyway (e.g. Sybase).  Example 0 is part
of examples 4, 5, and 6, so if example 0 works, these other
examples may work, even if the engine does not properly support
the right hand side of the C<OR> expression.

=end original

例 0 は(前述したように)動作しないかもしれませんが、それでも(Sybase のような)
いくつかのデータベースエンジンでは動作します。
例 0 は例 4, 5, 6 の一部なので、例 0 が動作すれば、例えエンジンが C<OR> 式の
右側を正しく対応していないとしても、他の例も動作します。

=begin original

Examples 1 and 2 are not robust: they require that you provide a
valid column value xx (e.g. '~') which is not present in any row.
That means you must have some notion of what data won't be stored
in the column, and expect clients to adhere to that.

=end original

例 1 と 2 は頑強ではありません: これらは、どの行にも存在しない、
有効な列の値 xx (例えば '~') を提供することを求められます。
これにより、どのデータがその列に保管できないのかについて注意を
払わなければならず、クライアントがそれに従うことを
想定しなければなりません。

=begin original

Example 5 requires that you provide a stored procedure (SP_ISNULL
in this example) that acts as a function: it checks whether a value
is null, and returns 1 if it is, or 0 if not.

=end original

例 5 は、関数のように動作するストアドプロシージャ (例えば SP_ISNULL) を
提供する必要があります: これは値が null かどうかをチェックして、そうなら
1 を、さもなければ 0 を返します。

=begin original

Example 6, the least simple, is probably the most portable, i.e., it
should work with with most, if not all, database engines.

=end original

例 6 は一番複雑ですが、おそらく一番移植性があります; つまり、
(全てでないとしても)ほとんどのデータベースエンジンで動作するはずです。

=begin original

Here is a table that indicates which examples above are known to
work on various database engines:

=end original

以下は様々なデータベースエンジンに対してどの例が動作すると分かっているかの
表です:

                   -----Examples------
                   0  1  2  3  4  5  6
                   -  -  -  -  -  -  -
  Oracle 9         N  Y  N  Y  Y  ?  Y
  Informix IDS 9   N  N  N  Y  N  Y  Y
  MS SQL           N  N  Y  N  Y  ?  Y
  Sybase           Y  N  N  N  N  N  Y
  AnyData,DBM,CSV  Y  N  N  N  Y  Y* Y
  SQLite 3.3       N  N  N  N  Y  N  N

=begin original

* Works only because Example 0 works.

=end original

* 例 0 が動作する場合にのみ動作します。

=begin original

DBI provides a sample perl script that will test the examples above
on your database engine and tell you which ones work.  It is located
in the F<ex/> subdirectory of the DBI source distribution, or here:
L<http://svn.perl.org/modules/dbi/trunk/ex/perl_dbi_nulls_test.pl>
Please use the script to help us fill-in and maintain this table.

=end original

DBI は、上述の例をあなたのデータベースでテストして動作するかどうかを
知らせてくれるサンプル perl スクリプトを提供しています。
これは DBI ソース配布の  F<ex/> サブディレクトリか、以下の場所にあります:
L<http://svn.perl.org/modules/dbi/trunk/ex/perl_dbi_nulls_test.pl>
スクリプトを、この表を埋めて保守する助けに使ってください。

=begin original

B<Performance>

=end original

B<性能>

=begin original

Without using placeholders, the insert statement shown previously would have to
contain the literal values to be inserted and would have to be
re-prepared and re-executed for each row. With placeholders, the insert
statement only needs to be prepared once. The bind values for each row
can be given to the C<execute> method each time it's called. By avoiding
the need to re-prepare the statement for each row, the application
typically runs many times faster. Here's an example:

=end original

プレースホルダを使わなければ、上記の INSERT 文は挿入する値をリテラルで
入れなければなりませんし、各行毎に再準備(re-prepare)し、
再実行(re-execute)しなければいけません。
プレースホルダを使うと、INSERT 文を準備(prepare)する必要があるのは
1 回だけです。
各行のバインド値は C<execute> メソッドを呼び出すときに与えることができます。
各行毎に再準備(re-prepare)する必要がなくなるので、アプリーケーションは
通常、何倍も速くなります。
以下に例を示します:

  my $sth = $dbh->prepare(q{
    INSERT INTO sales (product_code, qty, price) VALUES (?, ?, ?)
  }) or die $dbh->errstr;
  while (<>) {
      chomp;
      my ($product_code, $qty, $price) = split /,/;
      $sth->execute($product_code, $qty, $price) or die $dbh->errstr;
  }
  $dbh->commit or die $dbh->errstr;

=begin original

See L</execute> and L</bind_param> for more details.

=end original

詳細は L</execute> および L</bind_param> をご覧ください。

=begin original

The C<q{...}> style quoting used in this example avoids clashing with
quotes that may be used in the SQL statement. Use the double-quote like
C<qq{...}> operator if you want to interpolate variables into the string.
See L<perlop/"Quote and Quote-like Operators"> for more details.

=end original

この例では、SQL 文のなかで使われるかもしれないクォートの対応が崩れないよう、
C<q{...}> スタイルのクォートを使っています。
文字列に解釈して欲しい変数がある場合には、C<qq{...}> のような
ダブルクォートを使うことができます。
詳細については L<perlop/"Quote and Quote-like Operators"> をご覧ください。

=begin original

See also the L</bind_columns> method, which is used to associate Perl
variables with the output columns of a C<SELECT> statement.

=end original

Perl の変数を C<SELECT> 文の出力カラムに結びつけるために使われる
L</bind_column> メソッドもご覧ください。

=head1 THE DBI PACKAGE AND CLASS

(DBI パッケージとクラス)

=begin original

In this section, we cover the DBI class methods, utility functions,
and the dynamic attributes associated with generic DBI handles.

=end original

このセクションでは、DBI クラスメソッド、ユーティリティ関数そして
一般的な DBI ハンドルに関連する動的属性についてカバーします。

=head2 DBI Constants

(DBI 定数)

=begin original

Constants representing the values of the SQL standard types can be
imported individually by name, or all together by importing the
special C<:sql_types> tag.

=end original

以下の SQL 標準型定数は個別にインポートしたり、特殊な C<:sql_types> タグで
すべてをインポートすることができます:

=begin original

The names and values of all the defined SQL standard types can be
produced like this:

=end original

定義されている全ての SQL 標準型の名前と値は以下のようにして取得できます:

  foreach (@{ $DBI::EXPORT_TAGS{sql_types} }) {
    printf "%s=%d\n", $_, &{"DBI::$_"};
  }

=begin original

These constants are defined by SQL/CLI, ODBC or both.
C<SQL_BIGINT> is (currently) omitted, because SQL/CLI and ODBC provide
conflicting codes.

=end original

これらの定数は SQL/CLI, ODBC あるいは両方で定義されています。
SQL/CLI と ODBC でコードが衝突しているので、C<SQL_BIGINT> is (現状では)
省略されています。

=begin original

See the L</type_info>, L</type_info_all>, and L</bind_param> methods
for possible uses.

=end original

可能な利用法に関しては L</type_info>, L</type_info_all>,
L</bind_param> メソッドを参照してください。

=begin original

Note that just because the DBI defines a named constant for a given
data type doesn't mean that drivers will support that data type.

=end original

あるデータ型について DBI が名前付き定数を定義していないからと言って、
ドライバがそのデータ型に対応していないというわけではないことに
注意してください。

=head2 DBI Class Methods

(DBI クラスメソッド)

=begin original

The following methods are provided by the DBI class:

=end original

DBI クラスによって以下のメソッドが提供されています:

=head3 C<parse_dsn>

  ($scheme, $driver, $attr_string, $attr_hash, $driver_dsn) = DBI->parse_dsn($dsn)
      or die "Can't parse DBI DSN '$dsn'";

=begin original

Breaks apart a DBI Data Source Name (DSN) and returns the individual
parts. If $dsn doesn't contain a valid DSN then parse_dsn() returns
an empty list.

=end original

DBI データソース名(Data Source Name) (DSN) を分解して、それぞれの部分を
返します。
$dsn に有効な DSN が含まれていない場合、parse_dsn() は空リストを返します。

=begin original

$scheme is the first part of the DSN and is currently always 'dbi'.
$driver is the driver name, possibly defaulted to $ENV{DBI_DRIVER},
and may be undefined.  $attr_string is the contents of the optional attribute
string, which may be undefined.  If $attr_string is not empty then $attr_hash
is a reference to a hash containing the parsed attribute names and values.
$driver_dsn is the last part of the DBI DSN string. For example:

=end original

$scheme は DSN の最初の部分で、現在のところ常に 'dbi' です。
$driver はドライバ名で、おそらくデフォルトは $ENV{DBI_DRIVER} で、
未定義値かもしれません。
$attr_string はオプションの属性文字列の内容で、未定義値かもしれません。
$attr_string が空でないなら、$attr_hash はパースされた属性名と値を含む
ハッシュへのリファレンスです。
$driver_dsn は DBI DSN 文字列の最後の部分です。
例えば:

  ($scheme, $driver, $attr_string, $attr_hash, $driver_dsn)
      = DBI->parse_dsn("DBI:MyDriver(RaiseError=>1):db=test;port=42");
  $scheme      = 'dbi';
  $driver      = 'MyDriver';
  $attr_string = 'RaiseError=>1';
  $attr_hash   = { 'RaiseError' => '1' };
  $driver_dsn  = 'db=test;port=42';

=begin original

The parse_dsn() method was added in DBI 1.43.

=end original

parse_dsn() メソッドは DBI 1.43 で追加されました。

=head3 C<connect>

  $dbh = DBI->connect($data_source, $username, $password)
            or die $DBI::errstr;
  $dbh = DBI->connect($data_source, $username, $password, \%attr)
            or die $DBI::errstr;

=begin original

Establishes a database connection, or session, to the requested C<$data_source>.
Returns a database handle object if the connection succeeds. Use
C<$dbh-E<gt>disconnect> to terminate the connection.

=end original

要求された C<$data_source> への接続またはセッションを確立します。
接続が成功するとデータベース・ハンドル・オブジェクトを返します。
接続を終わらせるためには C<$dbh-E<gt>disconnect> を使います。

=begin original

If the connect fails (see below), it returns C<undef> and sets both C<$DBI::err>
and C<$DBI::errstr>. (It does I<not> explicitly set C<$!>.) You should generally
test the return status of C<connect> and C<print $DBI::errstr> if it has failed.

=end original

connect が失敗したら(下記をご覧下さい)C<undef>を返し、
C<$DBI::err>, C<$DBI::errstr> を設定します (C<$!> は明示的には
I<設定しません>)。
一般的には C<connect> の戻りステータスを確認し、失敗していたら
C<$DBI::errstr> を表示します。

=begin original

Multiple simultaneous connections to multiple databases through multiple
drivers can be made via the DBI. Simply make one C<connect> call for each
database and keep a copy of each returned database handle.

=end original

DBI 経由で、複数のデータベースに対しての複数のドライバを使って、同時に
複数接続することができます。
単純に各データベース毎に C<connect> を呼び出し、返された
データベースハンドルのコピーをとっておいてください。

=begin original

The C<$data_source> value must begin with "C<dbi:>I<driver_name>C<:>".
The I<driver_name> specifies the driver that will be used to make the
connection. (Letter case is significant.)

=end original

C<$data_source> の値は "C<dbi:>I<ドライバ名>C<:>" で
始まらなければなりません。
I<ドライバ名> が接続ために使われるドライバを示します。
 (大文字小文字は区別されます).

=begin original

As a convenience, if the C<$data_source> parameter is undefined or empty,
the DBI will substitute the value of the environment variable C<DBI_DSN>.
If just the I<driver_name> part is empty (i.e., the C<$data_source>
prefix is "C<dbi::>"), the environment variable C<DBI_DRIVER> is
used. If neither variable is set, then C<connect> dies.

=end original

便宜上、C<$data_source> フィールドが未定義あるいは空だった場合、DBI は
この値を環境変数 C<DBI_DSN> の値で置換します。
ドライバ名の部分だけが空だった場合(つまり C<$data_source> の始まりが
"C<dbi::>") 、環境変数 C<DBI_DRIVER> が使われます。
もし変数も設定されていなければ C<connect> は die します。

=begin original

Examples of C<$data_source> values are:

=end original

C<$data_source> の値の例は:

  dbi:DriverName:database_name
  dbi:DriverName:database_name@hostname:port
  dbi:DriverName:database=database_name;host=hostname;port=port

=begin original

There is I<no standard> for the text following the driver name. Each
driver is free to use whatever syntax it wants. The only requirement the
DBI makes is that all the information is supplied in a single string.
You must consult the documentation for the drivers you are using for a
description of the syntax they require.

=end original

ドライバ名の後ろにつく文字列については I<標準はありません>。
各ドライバは欲しい書き方をどんなものでも自由に使うことができます。
DBI が要求するのは、すべての情報が一つの文字列として与えられることだけです。
使っているドライバが要求している書き方の説明の説明については、その
ドキュメントを調べなければなりません。

=begin original

It is recommended that drivers support the ODBC style, shown in the
last example above. It is also recommended that that they support the
three common names 'C<host>', 'C<port>', and 'C<database>' (plus 'C<db>'
as an alias for C<database>). This simplifies automatic construction
of basic DSNs: C<"dbi:$driver:database=$db;host=$host;port=$port">.
Drivers should aim to 'do something reasonable' when given a DSN
in this form, but if any part is meaningless for that driver (such
as 'port' for Informix) it should generate an error if that part
is not empty.

=end original

ドライバは上述の最後の例である ODBC 形式に対応することが推奨されています。
また、三つの共通の名前 'C<host>', 'C<port>', 'C<database>' (および
C<database> の別名としての 'C<db>') に対応することも推奨されています。
これにより基本的な DSN の自動的な構築が簡単になります:
C<"dbi:$driver:database=$db;host=$host;port=$port">。
ドライバは、DSN がこの形式で与えられたとき、「何か意味のあることをする」
ことを目指すべきですが、(Infomix にとっての 'port' のように)どれかの部分が
このドライバにとって意味がない場合、その部分が空でないときには
エラーを発生させるべきです。

=begin original

If the environment variable C<DBI_AUTOPROXY> is defined (and the
driver in C<$data_source> is not "C<Proxy>") then the connect request
will automatically be changed to:

=end original

環境変数 C<DBI_AUTOPROXY> が定義されていれば(そして C<$data_source> の
データソースが "C<Proxy>" でなければ)、接続要求は自動的に以下のように
変更されます:

  $ENV{DBI_AUTOPROXY};dsn=$data_source

=begin original

C<DBI_AUTOPROXY> is typically set as "C<dbi:Proxy:hostname=...;port=...>".
If $ENV{DBI_AUTOPROXY} doesn't begin with 'C<dbi:>' then "dbi:Proxy:"
will be prepended to it first.  See the DBD::Proxy documentation
for more details.

=end original

C<DBI_AUTOPROXY> は、通常 "C<dbi:Proxy:hostname=...;port=...>" となります。
$ENV{DBI_AUTOPROXY} が 'C<dbi:>' で始まっていない場合は、先頭に
"dbi:Proxy:" を追加します。
詳細については DBD::Proxyドキュメント をご覧ください。

=begin original

If C<$username> or C<$password> are undefined (rather than just empty),
then the DBI will substitute the values of the C<DBI_USER> and C<DBI_PASS>
environment variables, respectively.  The DBI will warn if the
environment variables are not defined.  However, the everyday use
of these environment variables is not recommended for security
reasons. The mechanism is primarily intended to simplify testing.
See below for alternative way to specify the username and password.

=end original

C<$username> または C<$password> が未定義(あるいは単に空)ならば、
DBI はそれぞれ環境変数 C<DBI_USER> と C<DBI_PASS> の値で置き換えます。
その環境変数が定義されてなければ、DBI は警告します。
しかしながら、これらの環境変数を普段使いすることは、セキュリティ上の理由から
お勧めしません。
この機能は基本的にテストを簡単にすることを目的としています。
ユーザー名とパスワードを指定するための代替案については後述します。

=begin original

C<DBI-E<gt>connect> automatically installs the driver if it has not been
installed yet. Driver installation either returns a valid driver
handle, or it I<dies> with an error message that includes the string
"C<install_driver>" and the underlying problem. So C<DBI-E<gt>connect>
will die
on a driver installation failure and will only return C<undef> on a
connect failure, in which case C<$DBI::errstr> will hold the error message.
Use C<eval { ... }> if you need to catch the "C<install_driver>" error.

=end original

C<DBI-E<gt>connect> は、まだインストールされていないドライバを自動的に
インストールします。
ドライバのインストールは適切なドライバハンドルを返すか、
"C<install_driver>" という文字列と基になった問題が入った
エラーメッセージとともに die するかのどちらかです。
そのため C<DBI-E<gt>connect> はドライバインストールの障害のときには
die して、接続の障害のときには C<undef> を返すだけです;
そのときには C<$DBI::errstr> にエラーの情報が入っています。
"C<install_driver>" エラーを捕捉する必要がある場合は C<eval { ... }> を
使ってください。

=begin original

The C<$data_source> argument (with the "C<dbi:...:>" prefix removed) and the
C<$username> and C<$password> arguments are then passed to the driver for
processing. The DBI does not define any interpretation for the
contents of these fields.  The driver is free to interpret the
C<$data_source>, C<$username>, and C<$password> fields in any way, and supply
whatever defaults are appropriate for the engine being accessed.
(Oracle, for example, uses the ORACLE_SID and TWO_TASK environment
variables if no C<$data_source> is specified.)

=end original

C<$data_source> 引数 ( "C<dbi:...:>" という接頭辞をとったもの)と
C<$username>, C<$password> の引数は、処理のためドライバに渡されます。
DBI はこれらのフィールドの内容の解釈について何も定義していません。
ドライバは C<$data_source>, C<$username>, C<$password> のフィールドを、
どんなふうにも自由に解析することができます。
そしてアクセスされるエンジンに合わせて、いかなるデフォルトも
設定することができます。
(例えば Oracle では、データソースが指定されていなければ、環境変数
ORACLE_SID と TWO_TASK を使います)。

=begin original

The C<AutoCommit> and C<PrintError> attributes for each connection
default to "on". (See L</AutoCommit> and L</PrintError> for more information.)
However, it is strongly recommended that you explicitly define C<AutoCommit>
rather than rely on the default. The C<PrintWarn> attribute defaults to
on if $^W is true, i.e., perl is running with warnings enabled.

=end original

各コネクションの C<AutoCommit> と C<PrintError> 属性のデフォルトは "on" です。
(詳細は C<AutoCommit> と C<PrintError> をご覧ください)。
しかしながら、デフォルトにまかませるよりも明示的に C<AutoCommit> を
定義することが強く推奨されます。
$^W が真なら C<PrintWarn> 属性のデフォルトはオンです; つまり、perl は
警告を有効にして動作します。

=begin original

The C<\%attr> parameter can be used to alter the default settings of
C<PrintError>, C<RaiseError>, C<AutoCommit>, and other attributes. For example:

=end original

C<\%attr> パラメータを使って、C<PrintError>, C<RaiseError>,
C<AutoCommit> などの属性のデフォルト値を変更することができます。
例:

  $dbh = DBI->connect($data_source, $user, $pass, {
	PrintError => 0,
	AutoCommit => 0
  });

=begin original

The username and password can also be specified using the attributes
C<Username> and C<Password>, in which case they take precedence
over the C<$username> and C<$password> parameters.

=end original

ユーザー名とパスワードは属性 C<Username> と C<Password> を使っても
指定でき、この場合は C<$username> と C<$password> のパラメータより
優先されます。

=begin original

You can also define connection attribute values within the C<$data_source>
parameter. For example:

=end original

C<$data_source> パラメータの中で接続属性の値を定義することもできます。
例:

  dbi:DriverName(PrintWarn=>1,PrintError=>0,Taint=>1):...

=begin original

Individual attributes values specified in this way take precedence over
any conflicting values specified via the C<\%attr> parameter to C<connect>.

=end original

この方法で指定される各属性値は、C<connect> への C<\%attr> パラメータを
介して指定された値とぶつかっても優先されます。

=begin original

The C<dbi_connect_method> attribute can be used to specify which driver
method should be called to establish the connection. The only useful
values are 'connect', 'connect_cached', or some specialized case like
'Apache::DBI::connect' (which is automatically the default when running
within Apache).

=end original

C<dbi_connect_method> 属性は接続を確立するさいにどちらのドライバメソッドが
呼ばれるべきかを指定するために使われます。
これには 'connect', 'connect_cached', 'Apache::DBI::connect'
これは Apache で実行されたときには自動的にデフォルトになります)のような
ある特別なケースが使えます。

=begin original

Where possible, each session (C<$dbh>) is independent from the transactions
in other sessions. This is useful when you need to hold cursors open
across transactions--for example, if you use one session for your long lifespan
cursors (typically read-only) and another for your short update
transactions.

=end original

可能であれば、各セッション (C<$dbh>) は他のセッションのトランザクションから
独立しています。
これはカーソルをトランザクションをまたがってオープンしたままにする必要がある
場合には便利です。
例えばあるセッションを長い寿命をもつカーソル(通常は読み込み専用)のために使い、
他のセッションで短い更新トランザクションを実行する場合です。

=begin original

For compatibility with old DBI scripts, the driver can be specified by
passing its name as the fourth argument to C<connect> (instead of C<\%attr>):

=end original

古い DBI スクリプトとの互換性のために、ドライバの名前を C<connect> の
4 番目の引数として(C<\%attr> の代わりに)、ドライバに指定することができます:

  $dbh = DBI->connect($data_source, $user, $pass, $driver);

=begin original

In this "old-style" form of C<connect>, the C<$data_source> should not start
with "C<dbi:driver_name:>". (If it does, the embedded driver_name
will be ignored). Also note that in this older form of C<connect>,
the C<$dbh-E<gt>{AutoCommit}> attribute is I<undefined>, the
C<$dbh-E<gt>{PrintError}> attribute is off, and the old C<DBI_DBNAME>
environment variable is
checked if C<DBI_DSN> is not defined. Beware that this "old-style"
C<connect> will soon be withdrawn in a future version of DBI.

=end original

この C<connect> の「旧スタイル」形式では、C<$data_source> は
"C<dbi:ドライバ名:>" で始まってはいけません。
(もしそうであれば、埋め込まれたドライバ名は無視されます)。
この古い形式の C<connect>では、C<$dbh-E<gt>{AutoCommit}> 属性は未定義、
C<$dbh-E<gt>{PrintError}> はオフ、そして C<DBI_DSN> が定義されていなければ、
古い C<DBI_DBNAME> 環境変数がチェックされます。
この「旧スタイル」の C<connect> は DBI の近い将来のバージョンで
撤廃されるであろうということに用心してください。

=head3 C<connect_cached>

  $dbh = DBI->connect_cached($data_source, $username, $password)
            or die $DBI::errstr;
  $dbh = DBI->connect_cached($data_source, $username, $password, \%attr)
            or die $DBI::errstr;

=begin original

C<connect_cached> is like L</connect>, except that the database handle
returned is also
stored in a hash associated with the given parameters. If another call
is made to C<connect_cached> with the same parameter values, then the
corresponding cached C<$dbh> will be returned if it is still valid.
The cached database handle is replaced with a new connection if it
has been disconnected or if the C<ping> method fails.

=end original

C<connect_cached> は返されるデータベースハンドルが与えられたパラメータと
関連付けられてハッシュにも格納されるという点を除けば、L</connect> に
似ています。
同じパラメータ値で C<connect_cached> がもう一度呼ばれると、それがまだ
適切であれば、キャッシュされた対応する C<$dbh> が返されます。
すでに切断されていたり、C<ping> メソッドが失敗したら、キャッシュされた
データベースハンドルは新しい接続で置きかえられます。

=begin original

Note that the behaviour of this method differs in several respects from the
behaviour of persistent connections implemented by Apache::DBI.
However, if Apache::DBI is loaded then C<connect_cached> will use it.

=end original

このメソッドの動きは、Apache::DBI によって実装されている永続接続の動きとは
多くの点で異なることに注意してください。
しかし、Apache::DBI が読み込まれると、C<connect_cached> はこれを
使います。

=begin original

Caching connections can be useful in some applications, but it can
also cause problems, such as too many connections, and so should
be used with care. In particular, avoid changing the attributes of
a database handle created via connect_cached() because it will affect
other code that may be using the same handle. When connect_cached()
returns a handle the attributes will be reset to their initial values.
This can cause problems, especially with the C<AutoCommit> attribute.

=end original

キャッシュは、あるアプリケーションによっては便利かもしれませんが、
たくさん接続しすぎるといった問題もおこすかもしれませんし、注意して
使わなければなりません。
とくに、connect_cached() で作成したデータベースハンドルの属性を
変えることは避けてください; 同じハンドルを使っている他のコードに
影響を与えることになるからです。
connect_cached() がハンドルを返すとき、属性は初期値にリセットされます。
これは(特に C<AutoCommit> 属性で) 問題になる可能性があります。

=begin original

Where multiple separate parts of a program are using connect_cached()
to connect to the same database with the same (initial) attributes
it is a good idea to add a private attribute to the connect_cached()
call to effectively limit the scope of the caching. For example:

=end original

プログラムの複数の部分がconnect_cached()を使用して、同じ(初期)属性で同じデータベースに接続している場合は、connect_cached()コールにプライベート属性を追加して、キャッシュの範囲を効果的に制限することをお薦めします。
次に例を示します。
(TBR)

  DBI->connect_cached(..., { private_foo_cachekey => "Bar", ... });

=begin original

Handles returned from that connect_cached() call will only be returned
by other connect_cached() call elsewhere in the code if those other
calls also pass in the same attribute values, including the private one.
(I've used C<private_foo_cachekey> here as an example, you can use
any attribute name with a C<private_> prefix.)

=end original

そのconnect_cached()呼び出しから返されたハンドルは、コード内の他のconnect_cached()呼び出しによっても同じ属性値(プライベート値を含む)が渡される場合にのみ、その他のconnect_cached()呼び出しによって返されます(ここでは例としてC<private_foo_cachekey>を使用しています。
C<private_>プレフィクスを持つ任意の属性名を使用できます)。
(TBR)

=begin original

Taking that one step further, you can limit a particular connect_cached()
call to return handles unique to that one place in the code by setting the
private attribute to a unique value for that place:

=end original

これをさらに一歩進めて、private属性をその場所に固有の値に設定することで、特定のconnect_cached()呼び出しがコード内のその場所に固有のハンドルを返すように制限できます。
(TBR)

  DBI->connect_cached(..., { private_foo_cachekey => __FILE__.__LINE__, ... });

=begin original

By using a private attribute you still get connection caching for
the individual calls to connect_cached() but, by making separate
database connections for separate parts of the code, the database
handles are isolated from any attribute changes made to other handles.

=end original

private属性を使用しても、connect_cached()の個々の呼び出しの接続キャッシュを取得できますが、コードの別々の部分に対して別々のデータベース接続を作成することにより、データベースハンドルは、他のハンドルに対して行われた属性の変更から分離されます。
(TBR)

=begin original

The cache can be accessed (and cleared) via the L</CachedKids> attribute:

=end original

キャッシュは L</CachedKids> 属性を介してアクセス(そしてクリア)することが
できます:

  my $CachedKids_hashref = $dbh->{Driver}->{CachedKids};
  %$CachedKids_hashref = () if $CachedKids_hashref;

=head3 C<available_drivers>

  @ary = DBI->available_drivers;
  @ary = DBI->available_drivers($quiet);

=begin original

Returns a list of all available drivers by searching for C<DBD::*> modules
through the directories in C<@INC>. By default, a warning is given if
some drivers are hidden by others of the same name in earlier
directories. Passing a true value for C<$quiet> will inhibit the warning.

=end original

C<@INC> のディレクトリから C<DBD::*> モジュールを検索して、使用可能な
ドライバのリストを返します。
デフォルトでは、先に見つかったディレクトリにある同じ名前のものにより、
隠されてしまうドライバがあれば警告します。
警告を抑止するには C<$quiet> を真の値にします。

=head3 C<installed_drivers>

  %drivers = DBI->installed_drivers();

=begin original

Returns a list of driver name and driver handle pairs for all drivers
'installed' (loaded) into the current process.  The driver name does not
include the 'DBD::' prefix.

=end original

現在のプロセスに「インストールされた」(読み込まれた)全てのドライバの
ドライバ名とドライバハンドルの組のリストを返します。
ドライバ名には 'DBD::' 接頭辞は付いていません。

=begin original

To get a list of all drivers available in your perl installation you can use
L</available_drivers>.

=end original

インストールされている perl で利用可能な全てのドライバのリストを得るには、
L</available_drivers> が使えます。

=begin original

Added in DBI 1.49.

=end original

DBI 1.49 で追加されました。

=head3 C<installed_versions>

  DBI->installed_versions;
  @ary  = DBI->installed_versions;
  %hash = DBI->installed_versions;

=begin original

Calls available_drivers() and attempts to load each of them in turn
using install_driver().  For each load that succeeds the driver
name and version number are added to a hash. When running under
L<DBI::PurePerl> drivers which appear not be pure-perl are ignored.

=end original

available_drivers() を呼び出して、そのそれぞれに対して install_driver() を
使って読み込もうとします。
読み込みに成功したドライバの名前とバージョン番号はハッシュに追加されます。
L<DBI::PurePerl> ドライバで実行するとピュア perl でないように見える
ドライバは無視されます。

=begin original

When called in array context the list of successfully loaded drivers
is returned (without the 'DBD::' prefix).

=end original

配列コンテキストで呼び出されると、読み込みに成功したドライバのリストが
('DBD::' の接頭辞なしで) 返されます。

=begin original

When called in scalar context a reference to the hash is returned
and the hash will also contain other entries for the C<DBI> version,
C<OS> name, etc.

=end original

スカラコンテキストで呼び出されると、ハッシュへのリファレンスが返され、
このハッシュには C<DBI> バージョン、C<OS> 名などのその他のエントリも
含まれます。

=begin original

When called in a void context the installed_versions() method will
print out a formatted list of the hash contents, one per line.

=end original

無効コンテキストで呼び出されると、installed_versions() メソッドは
ハッシュの内容を行単位でフォーマットしたリストを出力します。

=begin original

Due to the potentially high memory cost and unknown risks of loading
in an unknown number of drivers that just happen to be installed
on the system, this method is not recommended for general use.
Use available_drivers() instead.

=end original

潜在的にメモリコストが高いことと、何個か分からないシステムに
インストールされているドライバを読み込むという不明なリスクがあるので、
このメソッドは一般的な使用は推奨されません。
代わりに available_drivers() を使ってください。

=begin original

The installed_versions() method is primarily intended as a quick
way to see from the command line what's installed. For example:

=end original

installed_versions() メソッドは主としてインストールされているものを
コマンドラインから素早く見ることを目的としています。
例えば:

  perl -MDBI -e 'DBI->installed_versions'

=begin original

The installed_versions() method was added in DBI 1.38.

=end original

installed_versions() メソッドは DBI 1.38 で追加されました。

=head3 C<data_sources>

  @ary = DBI->data_sources($driver);
  @ary = DBI->data_sources($driver, \%attr);

=begin original

Returns a list of data sources (databases) available via the named
driver.  If C<$driver> is empty or C<undef>, then the value of the
C<DBI_DRIVER> environment variable is used.

=end original

指定された名前のドライバで使うことができるデータソース(データベース)の
リストを返します。
C<$driver> が空もしくは C<undef> であれば、環境変数 C<DBI_DRIVER> の値が
使われます。

=begin original

The driver will be loaded if it hasn't been already. Note that if the
driver loading fails then data_sources() I<dies> with an error message
that includes the string "C<install_driver>" and the underlying problem.

=end original

まだロードされていなければ、ドライバはロードされます。
もしドライバのローディングが失敗したら、"C<install_driver>" という文字列と
そこにある問題が入ったエラーメッセージで I<die> することに注意してください。

=begin original

Data sources are returned in a form suitable for passing to the
L</connect> method (that is, they will include the "C<dbi:$driver:>" prefix).

=end original

データソースは L</connect> メソッドに渡すのに適したな形式で返されます
(つまり接頭辞 "C<dbi:$driver:>" が入ります。)

=begin original

Note that many drivers have no way of knowing what data sources might
be available for it. These drivers return an empty or incomplete list
or may require driver-specific attributes.

=end original

多くのドライバが利用できるデータソースを調べる方法を
持っていないということに注意してください。
これらのドライバは空もしくは不完全なリストが返したり、
あるいはドライバ特有の属性が与えられることを必要とするかもしれません。

=begin original

There is also a data_sources() method defined for database handles.

=end original

データベースハンドルのために定義されている data_sources() メソッドも
あります。

=head3 C<trace>

  DBI->trace($trace_setting)
  DBI->trace($trace_setting, $trace_filename)
  DBI->trace($trace_setting, $trace_filehandle)
  $trace_setting = DBI->trace;

=begin original

The C<DBI-E<gt>trace> method sets the I<global default> trace
settings and returns the I<previous> trace settings. It can also
be used to change where the trace output is sent.

=end original

C<DBI-E<gt>trace> メソッドは I<グローバルにデフォルトの> トレース設定を
セットし、I<以前の> トレース設定を返します。
これはまた、トレース出力をどこに送るかを変更するためにも使います。

=begin original

There's a similar method, C<$h-E<gt>trace>, which sets the trace
settings for the specific handle it's called on.

=end original

似たようなメソッドして C<$h-E<gt>trace> があり、これは呼び出された
特定のハンドルのトレース設定を設定します。

=begin original

See the L</TRACING> section for full details about the DBI's powerful
tracing facilities.

=end original

DBI の強力なトレース機能に関する完全な詳細については
L</TRACING> の章を参照してください。

=head3 C<visit_handles>

  DBI->visit_handles( $coderef );
  DBI->visit_handles( $coderef, $info );

=begin original

Where $coderef is a reference to a subroutine and $info is an arbitrary value
which, if undefined, defaults to a reference to an empty hash. Returns $info.

=end original

$coderef はサブルーチンへのリファレンスで、$info は任意の値であり、
もし未定義ならデフォルトはからハッシュへのリファレンスとなります。
$info を返します。

=begin original

For each installed driver handle, if any, $coderef is invoked as:

=end original

インストールされているドライバがあれば、そのハンドル毎に、
$coderef は以下のようにして起動されます:

  $coderef->($driver_handle, $info);

=begin original

If the execution of $coderef returns a true value then L</visit_child_handles>
is called on that child handle and passed the returned value as $info.

=end original

$coderef の実行によって真の値が返されると、L</visit_child_handles> が
子ハンドルに呼び出され、返された値を $info として渡します。

=begin original

For example:

=end original

例えば:

  my $info = $dbh->{Driver}->visit_child_handles(sub {
      my ($h, $info) = @_;
      ++$info->{ $h->{Type} }; # count types of handles (dr/db/st)
      return $info; # visit kids
  });

=begin original

See also L</visit_child_handles>.

=end original

L</visit_child_handles> も参照してください。

=head2 DBI Utility Functions

(DBI ユーティリティ関数)

=begin original

In addition to the DBI methods listed in the previous section,
the DBI package also provides several utility functions.

=end original

前のセクションで一覧ししたメソッドに加えて、DBIパッケージはいくつかの
ユーティリティ関数も提供しています。

=begin original

These can be imported into your code by listing them in
the C<use> statement. For example:

=end original

これらは C<use> 文でリストすることであなたのコードにインポートできます。
例えば:

  use DBI qw(neat data_diff);

=begin original

Alternatively, all these utility functions (except hash) can be
imported using the C<:utils> import tag. For example:

=end original

あるいは、(hash を除く)これらのユーティリティ関す全てを
C<:utils> インポートタグを使ってインポートできます。
例えば:

  use DBI qw(:utils);

=head3 C<data_string_desc>

  $description = data_string_desc($string);

=begin original

Returns an informal description of the string. For example:

=end original

文字列に関する略式の記述を返します。
例えば:

  UTF8 off, ASCII, 42 characters 42 bytes
  UTF8 off, non-ASCII, 42 characters 42 bytes
  UTF8 on, non-ASCII, 4 characters 6 bytes
  UTF8 on but INVALID encoding, non-ASCII, 4 characters 6 bytes
  UTF8 off, undef

=begin original

The initial C<UTF8> on/off refers to Perl's internal SvUTF8 flag.
If $string has the SvUTF8 flag set but the sequence of bytes it
contains are not a valid UTF-8 encoding then data_string_desc()
will report C<UTF8 on but INVALID encoding>.

=end original

最初の C<UTF8> on/off は Perl 内部の SvUTF8 フラグを参照します。
$string に SvUTF8 フラグがセットされているけれどもその内容が有効な
UTF-8 エンコーディングでない場合、data_string_desc() は
C<UTF8 on but INVALID encoding> と報告します。

=begin original

The C<ASCII> vs C<non-ASCII> portion shows C<ASCII> if I<all> the
characters in the string are ASCII (have code points <= 127).

=end original

C<ASCII> と C<non-ASCII> の部分は、文字列の I<全ての> 文字が ASCII
(文字位置が <= 127) なら C<ASCII> となります。

=begin original

The data_string_desc() function was added in DBI 1.46.

=end original

data_string_desc() 関数は DBI 1.46 で追加されました。

=head3 C<data_string_diff>

  $diff = data_string_diff($a, $b);

=begin original

Returns an informal description of the first character difference
between the strings. If both $a and $b contain the same sequence
of characters then data_string_diff() returns an empty string.
For example:

=end original

二つの文字列の間で最初に異なる文字の非公式な説明を返します。
$a と $b が同じ文字並びなら、data_string_diff() は空文字列を返します。
例えば:

 Params a & b     Result
 ------------     ------
 'aaa', 'aaa'     ''
 'aaa', 'abc'     'Strings differ at index 2: a[2]=a, b[2]=b'
 'aaa', undef     'String b is undef, string a has 3 characters'
 'aaa', 'aa'      'String b truncated after 2 characters'

=begin original

Unicode characters are reported in C<\x{XXXX}> format. Unicode
code points in the range U+0800 to U+08FF are unassigned and most
likely to occur due to double-encoding. Characters in this range
are reported as C<\x{08XX}='C'> where C<C> is the corresponding
latin-1 character.

=end original

Unicode 文字は C<\x{XXXX}> 形式で報告されます。
U+0800 から U+08FF の範囲の Unicode 符号位置は未定義で、もっとも
ありそうなことは二重エンコーディングです。
この範囲の文字は C<\x{08XX}='C'> として報告されます; ここで
C<C> は対応する latin-1 文字です。

=begin original

The data_string_diff() function only considers logical I<characters>
and not the underlying encoding. See L</data_diff> for an alternative.

=end original

data_string_diff() 関数は、論理的な I<文字> だけを考慮し、その
基礎となるエンコーディングは考慮しません。
代替案に関しては L</data_diff> を参照してください。

=begin original

The data_string_diff() function was added in DBI 1.46.

=end original

data_string_diff() 関数は DBI 1.46 で追加されました。

=head3 C<data_diff>

  $diff = data_diff($a, $b);
  $diff = data_diff($a, $b, $logical);

=begin original

Returns an informal description of the difference between two strings.
It calls L</data_string_desc> and L</data_string_diff>
and returns the combined results as a multi-line string.

=end original

二つの文字列の違いに関する非公式な説明を返します。
これは L</data_string_desc> と L</data_string_diff> を呼び出し、
結合した結果を複数行の文字列として返します。

=begin original

For example, C<data_diff("abc", "ab\x{263a}")> will return:

=end original

例えば、C<data_diff("abc", "ab\x{263a}")> は以下のものを返します:

  a: UTF8 off, ASCII, 3 characters 3 bytes
  b: UTF8 on, non-ASCII, 3 characters 5 bytes
  Strings differ at index 2: a[2]=c, b[2]=\x{263A}

=begin original

If $a and $b are identical in both the characters they contain I<and>
their physical encoding then data_diff() returns an empty string.
If $logical is true then physical encoding differences are ignored
(but are still reported if there is a difference in the characters).

=end original

$a と $b が、含まれている文字列 I<および> その物理的なエンコーディングの
両方において同一の場合、data_diff() は空文字列を返します。
$logical が新なら物理的なエンコーディングの違いは無視されます
(しかし文字に違いがあればやはり報告されます)。

=begin original

The data_diff() function was added in DBI 1.46.

=end original

data_diff() 関数は DBI 1.46 で追加されました。

=head3 C<neat>

  $str = neat($value);
  $str = neat($value, $maxlen);

=begin original

Return a string containing a neat (and tidy) representation of the
supplied value.

=end original

与えられた文字列を整然と(そしてきれいに)整えられた文字列を返します。
 

=begin original

Strings will be quoted, although internal quotes will I<not> be escaped.
Values known to be numeric will be unquoted. Undefined (NULL) values
will be shown as C<undef> (without quotes).

=end original

文字列はクォーテーションで囲まれますが、文字列の中のクォーテーションは
エスケープ I<されません>。
数値であるとわかっている値はクォーテーションで囲まれません。
未定義(NULL) 値は(クォートなしで)C<undef> で表されます。

=begin original

If the string is flagged internally as utf8 then double quotes will
be used, otherwise single quotes are used and unprintable characters
will be replaced by dot (.).

=end original

文字列が内部で UTF8 として記録されていると、ダブルクォートが使われ、
さもなければシングルクォートが使われ、表示できない文字は点(.)で
置き換えられます。

=begin original

For result strings longer than C<$maxlen> the result string will be
truncated to C<$maxlen-4> and "C<...'>" will be appended.  If C<$maxlen> is 0
or C<undef>, it defaults to C<$DBI::neat_maxlen> which, in turn, defaults to 400.

=end original

変換結果の文字列が C<$masxlen> よりも長ければ、文字列は C<$maxlen-4> の
長さに切り詰め、"C<...'>" が後ろにつけられます。
C<$maxlen> が 0 または C<undef> であれば、C<$DBI::neat_maxlen>
(デフォルトは400)が代りにデフォルトになります。

=begin original

This function is designed to format values for human consumption.
It is used internally by the DBI for L</trace> output. It should
typically I<not> be used for formatting values for database use.
(See also L</quote>.)

=end original

この関数は人の目にわかりやすいように値の形式を整えるように考えられています。
これは DBI 内部で L</trace> 出力に使われています。
通常データベースが利用するよう、値の形を整えるために使っては
I<いけません> (L</quote> もご覧ください)。

=head3 C<neat_list>

  $str = neat_list(\@listref, $maxlen, $field_sep);

=begin original

Calls C<neat> on each element of the list and returns a string
containing the results joined with C<$field_sep>. C<$field_sep> defaults
to C<", ">.

=end original

リストの各要素に C<neat> を呼び出し、その結果を C<$field_sep> でつなげた
結果の文字列を返します。
C<$field_sep> のデフォルトは C<", "> です。

=head3 C<looks_like_number>

  @bool = looks_like_number(@array);

=begin original

Returns true for each element that looks like a number.
Returns false for each element that does not look like a number.
Returns C<undef> for each element that is undefined or empty.

=end original

リストの各要素について数値に見えば真を返します。
各要素が数値に見えなければ偽を返します。
各要素が未定義あるいは空であれば、C<undef> もしくは空を返します。

=head3 C<hash>

  $hash_value = DBI::hash($buffer, $type);

=begin original

Return a 32-bit integer 'hash' value corresponding to the contents of $buffer.
The $type parameter selects which kind of hash algorithm should be used.

=end original

$buffer の内容に対応する 32 ビット整数の「ハッシュ」値を返します。
$type パラメータは使用するハッシュアルゴリズムを選択します。

=begin original

For the technically curious, type 0 (which is the default if $type
isn't specified) is based on the Perl 5.1 hash except that the value
is forced to be negative (for obscure historical reasons).
Type 1 is the better "Fowler / Noll / Vo" (FNV) hash. See
L<http://www.isthe.com/chongo/tech/comp/fnv/> for more information.
Both types are implemented in C and are very fast.

=end original

技術的好奇心のために、型 0 (これは $type が指定されなかったときの
デフォルトです) は Perl 5.1 ハッシュを基にしていますが、(はっきりしない
歴史的な理由により) 値は負数に制限されます。
型 1 はよりより "Fowler / Noll / Vo" (FNV) ハッシュです。
さらなる情報については L<http://www.isthe.com/chongo/tech/comp/fnv/> を
参照してください。
どちらの型も C で実装されていてとても速いです。

=begin original

This function doesn't have much to do with databases, except that
it can be handy to store hash values in a database.

=end original

この関数はデータベースに対して何かをするというものではありませんが、
データベースにハッシュ値を補完するのに便利です。

=head3 C<sql_type_cast>

  $sts = DBI->sql_type_cast($sv, $sql_type, $flags);

=begin original

sql_type_cast attempts to cast C<$sv> to the SQL type (see L<DBI
Constants>) specified in C<$sql_type>. At present only the SQL types
C<SQL_INTEGER>, C<SQL_DOUBLE> and C<SQL_NUMERIC> are supported.

=end original

sql_type_cast は C<$sv> を C<$sql_type> で定義されている SQL 型
(L<DBI Constants> 参照) にキャストしようとします。
現在のところ SQL 型 C<SQL_INTEGER>, C<SQL_DOUBLE>, C<SQL_NUMERIC> のみに
対応しています。

=begin original

For C<SQL_INTEGER> the effect is similar to using the value in an expression
that requires an integer. It gives the perl scalar an 'integer aspect'.
(Technically the value gains an IV, or possibly a UV or NV if the value is too
large for an IV.)

=end original

C<SQL_INTEGER>の場合、この効果は、整数を必要とする式で値を使用するのと似ています。
perlスカラーに「整数アスペクト」を与えます。
(技術的には、値はIVを取得します。
IVに対して値が大きすぎる場合は、UVまたはNVを取得する可能性があります。
)
(TBR)

=begin original

For C<SQL_DOUBLE> the effect is similar to using the value in an expression
that requires a general numeric value. It gives the perl scalar a 'numeric
aspect'.  (Technically the value gains an NV.)

=end original

C<SQL_DOUBLE>の場合、この効果は、一般的な数値を必要とする式で値を使用することに似ています。
perlスカラーに「数値的な側面」を与えます(技術的には、値はNVを獲得します)。
(TBR)

=begin original

C<SQL_NUMERIC> is similar to C<SQL_INTEGER> or C<SQL_DOUBLE> but more
general and more cautious.  It will look at the string first and if it
looks like an integer (that will fit in an IV or UV) it will act like
C<SQL_INTEGER>, if it looks like a floating point value it will act
like C<SQL_DOUBLE>, if it looks like neither then it will do nothing -
and thereby avoid the warnings that would be generated by
C<SQL_INTEGER> and C<SQL_DOUBLE> when given non-numeric data.

=end original

C<SQL_NUMERIC>はC<SQL_INTEGER>やC<SQL_DOUBLE>に似ていますが、より一般的でより慎重です。
C<SQL_NUMERIC>は文字列を最初に見て、(IVまたはUVに適合する)整数のように見える場合はC<SQL_INTEGER>のように動作し、浮動小数点値のように見える場合はC<SQL_DOUBLE>のように動作し、どちらでもないように見える場合は何もしません。
これにより、非数値データが与えられたときにC<SQL_INTEGER>とC<SQL_DOUBLE>によって生成される警告を回避します。
(TBR)

=begin original

C<$flags> may be:

=end original

C<$flags> は:

=over 4

=item C<DBIstcf_DISCARD_STRING>

=begin original

If this flag is specified then when the driver successfully casts the
bound perl scalar to a non-string type then the string portion of the
scalar will be discarded.

=end original

このフラグを指定すると、ドライバがバインドされたperlスカラーを文字列以外の型にキャストしたときに、スカラーの文字列部分が破棄されます。
(TBR)

=item C<DBIstcf_STRICT>

=begin original

If C<$sv> cannot be cast to the requested C<$sql_type> then by default
it is left untouched and no error is generated. If you specify
C<DBIstcf_STRICT> and the cast fails, this will generate an error.

=end original

C<$sv>が要求されたC<$sql_type>にキャストできない場合、デフォルトでは変更されず、エラーは生成されません。
C<DBIstcf_STRICT>を指定してキャストが失敗すると、エラーが生成されます。
(TBR)

=back

=begin original

The returned C<$sts> value is:

=end original

返された C<$sts> の値は:

  -2 sql_type is not handled
  -1 sv is undef so unchanged
   0 sv could not be cast cleanly and DBIstcf_STRICT was used
   1 sv could not be case and DBIstcf_STRICT was not used
   2 sv was cast successfully

=begin original

This method is exported by the :utils tag and was introduced in DBI
1.611.

=end original

このメソッドは :utils タグでエクスポートされ、DBI 1.611 で
導入されました。

=head2 DBI Dynamic Attributes

(DBI 動的属性)

=begin original

Dynamic attributes are always associated with the I<last handle used>
(that handle is represented by C<$h> in the descriptions below).

=end original

動的属性は I<最後に使われたハンドル> に関連づけられます。
(そのハンドルは以下の説明では C<$h> で示されます)

=begin original

Where an attribute is equivalent to a method call, then refer to
the method call for all related documentation.

=end original

属性がメソッド呼び出しと同様のところでは、すべての関連する
ドキュメンテーションでそのメソッド呼び出しを参照してください。

=begin original

Warning: these attributes are provided as a convenience but they
do have limitations. Specifically, they have a short lifespan:
because they are associated with
the last handle used, they should only be used I<immediately> after
calling the method that "sets" them.
If in any doubt, use the corresponding method call.

=end original

警告: 便宜上、これらの属性を用意していますが、限界があります。
特にこれらの有効な時間は長くありません: 最後に使われたハンドルに
関連付けられているために、それらを「設定した」メソッドを呼び出した
I<すぐ後> にしか使うことができません。
少しでも疑問があれば、対応するメソッド呼び出しを使ってください。

=head3 C<$DBI::err>

=begin original

Equivalent to C<$h-E<gt>err>.

=end original

C<$h-E<gt>err> と等価です。

=head3 C<$DBI::errstr>

=begin original

Equivalent to C<$h-E<gt>errstr>.

=end original

C<$h-E<gt>errstr> と等価です。

=head3 C<$DBI::state>

=begin original

Equivalent to C<$h-E<gt>state>.

=end original

C<$h-E<gt>state> と等価です。

=head3 C<$DBI::rows>

=begin original

Equivalent to C<$h-E<gt>rows>. Please refer to the documentation
for the L</rows> method.

=end original

C<$h-E<gt>rows> と等価です。
L</rows> メソッドの文書を参照してください。

=head3 C<$DBI::lasth>

=begin original

Returns the DBI object handle used for the most recent DBI method call.
If the last DBI method call was a DESTROY then $DBI::lasth will return
the handle of the parent of the destroyed handle, if there is one.

=end original

最後の DBI メソッド呼び出しに使われた DBI オブジェクトハンドルを返します。
最後の DBI メソッド呼び出しが DESTROY であれば、$DBI::lasth はもしあれば、
破壊されたハンドルの親のハンドルを返します。

=head1 METHODS COMMON TO ALL HANDLES

(全てのハンドルに共通のメソッド)

=begin original

The following methods can be used by all types of DBI handles.

=end original

以下のメソッドは DBI ハンドルのすべてのタイプに使うことができます。

=head3 C<err>

  $rv = $h->err;

=begin original

Returns the I<native> database engine error code from the last driver
method called. The code is typically an integer but you should not
assume that.

=end original

最後のドライバ関数呼び出しについて I<ネイティブ> なデータベースエンジン
エラーコードを返します。
コードは典型的には整数ですが、それを想定するべきではありません。

=begin original

The DBI resets $h->err to undef before almost all DBI method calls, so the
value only has a short lifespan. Also, for most drivers, the statement
handles share the same error variable as the parent database handle,
so calling a method on one handle may reset the error on the
related handles.

=end original

DBI はほとんど全ての DBI メソッドを呼び出す前に $h->err を undef に
リセットするので、この値は短い間だけ有効です。
またほとんどのドライバでは、文ハンドルは同じエラー変数を
親データベースハンドルと共有するので、あるハンドルに対してメソッドを呼び出すと、
関連するtハンドルのエラーをリセットするかもしれません。

=begin original

(Methods which don't reset err before being called include err() and errstr(),
obviously, state(), rows(), func(), trace(), trace_msg(), ping(), and the
tied hash attribute FETCH() and STORE() methods.)

=end original

(コールされる前にerrをリセットしないメソッドには、err()とerrstr()、もちろんstate()、rows()、func()、trace()、trace_msg()、ping()、そしてタイハッシュ属性のFETCH()メソッドとSTORE()メソッドが含まれます。
(TBR)

=begin original

If you need to test for specific error conditions I<and> have your program be
portable to different database engines, then you'll need to determine what the
corresponding error codes are for all those engines and test for all of them.

=end original

特定のエラー状況についてテストする必要があり、I<かつ> あなたのプログラムが
他のデータベース・エンジンに対して移植可能にする必要があれば、それら
すべてのエンジンについて対応するエラーコードが何かを判定し、それらの
すべてについてテストする必要があります。

=begin original

The DBI uses the value of $DBI::stderr as the C<err> value for internal errors.
Drivers should also do likewise.  The default value for $DBI::stderr is 2000000000.

=end original

DBI は $DBI::stderr の値を、内部エラーのための C<err> 値として使います。
ドライバも似たようなことをします。
$DBI::stderr のデフォルト値は 2000000000 です。

=begin original

A driver may return C<0> from err() to indicate a warning condition
after a method call. Similarly, a driver may return an empty string
to indicate a 'success with information' condition. In both these
cases the value is false but not undef. The errstr() and state()
methods may be used to retrieve extra information in these cases.

=end original

ドライバはerr()からC<0>を返して、メソッド呼び出し後の警告条件を示すことができます。
同様に、ドライバは'success with information'条件を示すために空の文字列を返すことができます。
これらの両方の場合、値はfalseですが、undefではありません。
errstr()およびstate()メソッドは、これらの場合に追加情報を取得するために使用できます。
(TBR)

=begin original

See L</set_err> for more information.

=end original

さらなる情報については L</set_err> を参照してください。

=head3 C<errstr>

  $str = $h->errstr;

=begin original

Returns the native database engine error message from the last DBI
method called. This has the same lifespan issues as the L</err> method
described above.

=end original

最後の DBI 関数呼び出しについて、ネイティブなデータベースエンジンエラーメッセージを返します。
上記で説明した L</err> メソッドと同じ有効期間の問題を持っています。

=begin original

The returned string may contain multiple messages separated by
newline characters.

=end original

返された文字列は改行文字で区切られた複数のメッセージを
含んでいるかもしれません。

=begin original

The errstr() method should not be used to test for errors, use err()
for that, because drivers may return 'success with information' or
warning messages via errstr() for methods that have not 'failed'.

=end original

エラーのテストにはerrstr()メソッドを使用しないでください。
エラーのテストにはerr()を使用してください。
これは、「失敗」していないメソッドに対して、ドライバがerrstr()を介して「情報付きの成功」または警告メッセージを返す可能性があるためです。
(TBR)

=begin original

See L</set_err> for more information.

=end original

さらなる情報については L</set_err> を参照してください。

=head3 C<state>

  $str = $h->state;

=begin original

Returns a state code in the standard SQLSTATE five character format.
Note that the specific success code C<00000> is translated to any empty string
(false). If the driver does not support SQLSTATE (and most don't),
then state() will return C<S1000> (General Error) for all errors.

=end original

エラーコードを標準の SQLSTATE の 5 文字形式で返します。
ある正常コード C<00000> は、空文字列(偽)に変換されてしまうことに
注意してください。
もしドライバが SQLSTATE に対応していなければ(ほとんどが
対応していないのですが)、state() はすべてのエラーについて
C<S1000>(一般エラー)を返します。

=begin original

The driver is free to return any value via C<state>, e.g., warning
codes, even if it has not declared an error by returning a true value
via the L</err> method described above.

=end original

ドライバは C<state> でどのような値を返すことも自由です; 例えば
警告コード; 上記の L</err> メソッドを介して真の値を返すことにより
宣言されるエラーでなかったとしても。

=begin original

The state() method should not be used to test for errors, use err()
for that, because drivers may return a 'success with information' or
warning state code via state() for methods that have not 'failed'.

=end original

state()メソッドはエラーのテストには使用しないでください。
err()を使用してください。
これは、ドライバが'情報付きの成功'を返す場合や、'失敗'していないメソッドに対してstate()を介して警告状態コードを返す場合があるためです。
(TBR)

=head3 C<set_err>

  $rv = $h->set_err($err, $errstr);
  $rv = $h->set_err($err, $errstr, $state);
  $rv = $h->set_err($err, $errstr, $state, $method);
  $rv = $h->set_err($err, $errstr, $state, $method, $rv);

=begin original

Set the C<err>, C<errstr>, and C<state> values for the handle.
This method is typically only used by DBI drivers and DBI subclasses.

=end original

ハンドルのための C<err>, C<errstr>, C<state> の値を設定します。
このメソッドは典型的には DBI ドライバと DBI サブクラスでのみ使用されます。

=begin original

If the L</HandleSetErr> attribute holds a reference to a subroutine
it is called first. The subroutine can alter the $err, $errstr, $state,
and $method values. See L</HandleSetErr> for full details.
If the subroutine returns a true value then the handle C<err>,
C<errstr>, and C<state> values are not altered and set_err() returns
an empty list (it normally returns $rv which defaults to undef, see below).

=end original

L</HandleSetErr>属性がサブルーチンへの参照を保持している場合、それが最初に呼び出されます。
サブルーチンは、$err、$errstr、$state、および$method値を変更できます。
詳細については、L</HandleSetErr>を参照してください。
サブルーチンが真の値を返す場合、ハンドルC<err>、C<errstr>、およびC<state>値は変更されず、set_err()は空のリストを返します(通常は$rvを返し、デフォルトはundefです。
以下を参照してください)。
(TBR)

=begin original

Setting C<err> to a I<true> value indicates an error and will trigger
the normal DBI error handling mechanisms, such as C<RaiseError> and
C<HandleError>, if they are enabled, when execution returns from
the DBI back to the application.

=end original

C<err>をI<true>値に設定すると、エラーが示され、C<RaiseError>やC<HandleError>などの通常のDBIエラー処理メカニズムが有効になっている場合は、DBIからアプリケーションに実行が戻されたときに、これらのメカニズムがトリガーされます。
(TBR)

=begin original

Setting C<err> to C<""> indicates an 'information' state, and setting
it to C<"0"> indicates a 'warning' state. Setting C<err> to C<undef>
also sets C<errstr> to undef, and C<state> to C<"">, irrespective
of the values of the $errstr and $state parameters.

=end original

C<err>をC<"">に設定すると「情報」状態を示し、C<"0">に設定すると「警告」状態を示します。
C<err>をC<undef>に設定すると、$errstrおよび$stateパラメータの値に関係なく、C<errstr>がundefに、C<state>がC<"">に設定されます。
(TBR)

=begin original

The $method parameter provides an alternate method name for the
C<RaiseError>/C<PrintError>/C<PrintWarn> error string instead of
the fairly unhelpful 'C<set_err>'.

=end original

$methodパラメータは、C<RaiseError>/C<PrintError>/C<PrintWarn>エラー文字列に対して、あまり役に立たない'C<set_err>'ではなく、代替メソッド名を提供します。
(TBR)

=begin original

The C<set_err> method normally returns undef.  The $rv parameter
provides an alternate return value.

=end original

C<set_err> メソッドは普通は undef を返します。
$rv パラメータは代替となる返り値を提供します。

=begin original

Some special rules apply if the C<err> or C<errstr>
values for the handle are I<already> set...

=end original

ハンドルのための C<err> や C<errstr> の値が I<既に> 設定されている場合は、
いくつかの特別ルールが適用されます…

=begin original

If C<errstr> is true then: "C< [err was %s now %s]>" is appended if $err is
true and C<err> is already true and the new err value differs from the original
one. Similarly "C< [state was %s now %s]>" is appended if $state is true and C<state> is
already true and the new state value differs from the original one. Finally
"C<\n>" and the new $errstr are appended if $errstr differs from the existing
errstr value. Obviously the C<%s>'s above are replaced by the corresponding values.

=end original

C<errstr>がtrueの場合、$errがtrueで、C<err>がすでにtrueで、新しいerr値が元の値と異なる場合は、「C< [err was %s now %s]>」が追加されます。
同様に、$stateがtrueで、C<state>がすでにtrueで、新しいstate値が元の値と異なる場合は、「C< [state was %s now %s]>」が追加されます。
最後に、$errstrが既存のerrstr値と異なる場合は、「C<\n>」と新しい$errstrが追加されます。
明らかに、上記のC<%s>は対応する値に置き換えられます。
(TBR)

=begin original

The handle C<err> value is set to $err if: $err is true; or handle
C<err> value is undef; or $err is defined and the length is greater
than the handle C<err> length. The effect is that an 'information'
state only overrides undef; a 'warning' overrides undef or 'information',
and an 'error' state overrides anything.

=end original

$errがtrueの場合、またはハンドルC<err>の値がundefの場合、または$errが定義されていて、その長さがハンドルC<err>の長さよりも長い場合、ハンドルC<err>の値は$errに設定されます。
その結果、'information'状態はundefのみを上書きし、'warning'はundefまたは'information'を上書きし、'error'状態はすべてを上書きします。
(TBR)

=begin original

The handle C<state> value is set to $state if $state is true and
the handle C<err> value was set (by the rules above).

=end original

$state が真でハンドルの C<err> 値が (上述のルールにより)
設定されているなら、ハンドルの C<state> の値は $state に設定されます。

=begin original

Support for warning and information states was added in DBI 1.41.

=end original

警告と情報状態の対応は DBI 1.41 で追加されました。

=head3 C<trace>

  $h->trace($trace_settings);
  $h->trace($trace_settings, $trace_filename);
  $trace_settings = $h->trace;

=begin original

The trace() method is used to alter the trace settings for a handle
(and any future children of that handle).  It can also be used to
change where the trace output is sent.

=end original

trace() メソッドは、ハンドル(およびそのハンドルの将来の子) の
トレース設定を変更するのに使われます。
これはまたトレース出力をどこに送るのかを変更するのにも使われます。

=begin original

There's a similar method, C<DBI-E<gt>trace>, which sets the global
default trace settings.

=end original

似たようなメソッドとして C<DBI-E<gt>trace> があり、これはグローバルな
デフォルトトレース設定を設定します。

=begin original

See the L</TRACING> section for full details about the DBI's powerful
tracing facilities.

=end original

DBI の強力なトレース機能に関する完全な詳細については
L</TRACING> の章を参照してください。

=head3 C<trace_msg>

  $h->trace_msg($message_text);
  $h->trace_msg($message_text, $min_level);

=begin original

Writes C<$message_text> to the trace file if the trace level is
greater than or equal to $min_level (which defaults to 1).
Can also be called as C<DBI-E<gt>trace_msg($msg)>.

=end original

トレースレベルが $min_level (デフォルトは 1)以上の場合の場合、
C<$message_text> をトレースファイルに書き出します。
C<DBI-E<gt>trace_msg($msg)> と呼び出すこともできます。

=begin original

See L</TRACING> for more details.

=end original

さらなる情報については L</TRACING> を参照してください。

=head3 C<func>

  $h->func(@func_arguments, $func_name) or die ...;

=begin original

The C<func> method can be used to call private non-standard and
non-portable methods implemented by the driver. Note that the function
name is given as the I<last> argument.

=end original

C<func> メソッドにより、ドライバが実装しているプライベートな標準でなく、
移植できないメソッドを呼び出すことができます。
関数名が I<最後の> 引数で与えられることに注意してください。

=begin original

It's also important to note that the func() method does not clear
a previous error ($DBI::err etc.) and it does not trigger automatic
error detection (RaiseError etc.) so you must check the return
status and/or $h->err to detect errors.

=end original

また、func()メソッドは以前のエラー($DBI::errなど)をクリアせず、自動エラー検出(RaiseErrorなど)をトリガーしないことに注意することも重要です。
エラーを検出するには、リターンステータスや$h->errをチェックする必要があります。
(TBR)

=begin original

(This method is not directly related to calling stored procedures.
Calling stored procedures is currently not defined by the DBI.
Some drivers, such as DBD::Oracle, support it in non-portable ways.
See driver documentation for more details.)

=end original

(このメソッドはストアドプロシージャの呼び出しに、直接は関係していません。
ストアドプロシージャ呼び出しは、いまのところ DBI によって定義されていません。
DBD::Oracle のようにいくつかのドライバが移植できない形でサポートしています。
詳細についてはドライバのドキュメントをご覧ください。)

=begin original

See also install_method() in L<DBI::DBD> for how you can avoid needing to
use func() and gain direct access to driver-private methods.

=end original

func() の使用を避けて、ドライバ固有のメソッドに直接アクセスする
方法については L<DBI::DBD> の install_method() も参照してください。

=head3 C<can>

  $is_implemented = $h->can($method_name);

=begin original

Returns true if $method_name is implemented by the driver or a
default method is provided by the DBI.
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.

=end original

$method_name がドライバによって実装されているか、デフォルトメソッドが
DBI によって提供されているなら真を返します。
ドライバがこのメソッドを実装しておらず、DBI によって提供されている
デフォルトメソッドが空のスタブである場合は偽を返します。

=head3 C<parse_trace_flags>

  $trace_settings_integer = $h->parse_trace_flags($trace_settings);

=begin original

Parses a string containing trace settings and returns the corresponding
integer value used internally by the DBI and drivers.

=end original

トレース設定を含む文字列をパースして、DBI とドライバで内部で使用されている
対応する整数値を返します。

=begin original

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">.

=end original

$trace_settings 引数は縦棒 ("C<|>") またはカンマ ("C<,>") 文字で区切られた、
0 から 15 のトレースレベルやトレースフラグ名からなる文字列です。
例: C<"SQL|3|foo">。

=begin original

It uses the parse_trace_flag() method, described below, to process
the individual trace flag names.

=end original

これは個々のトレースフラグ名を処理するために後述する
parse_trace_flag() メソッドを使います。

=begin original

The parse_trace_flags() method was added in DBI 1.42.

=end original

parse_trace_flags() メソッドは DBI 1.42 で追加されました。

=head3 C<parse_trace_flag>

  $bit_flag = $h->parse_trace_flag($trace_flag_name);

=begin original

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 DBI's default parse_trace_flag().

=end original

$trace_flag_name のトレースフラグ名に対応するビットフラグを返します。
ドライバはこのメソッドをオーバーライドして、$trace_flag_name が
ドライバ固有のフラグかどうかをチェックし、そうでなければ DBI の
デフォルトの parse_trace_flag() を呼び出すことを想定されています。

=begin original

The parse_trace_flag() method was added in DBI 1.42.

=end original

parse_trace_flag() メソッドは DBI 1.42 で追加されました。

=head3 C<private_attribute_info>

  $hash_ref = $h->private_attribute_info();

=begin original

Returns a reference to a hash whose keys are the names of driver-private
handle attributes available for the kind of handle (driver, database, statement)
that the method was called on.

=end original

メソッドが呼び出されたハンドルの種類(ドライバ、データベース、文)で
利用可能なドライバ固有のハンドル属性の名前をキーとしたハッシュへの
リファレンスを返します。

=begin original

For example, the return value when called with a DBD::Sybase $dbh could look like this:

=end original

例えば、DBD::Sybase $dbh で呼び出したときの返り値は以下のようになります:

  {
      syb_dynamic_supported => undef,
      syb_oc_version => undef,
      syb_server_version => undef,
      syb_server_version_string => undef,
  }

=begin original

and when called with a DBD::Sybase $sth they could look like this:

=end original

そして DBD::Sybase $sth で呼び出したときは以下のようになります:

  {
      syb_types => undef,
      syb_proc_status => undef,
      syb_result_type => undef,
  }

=begin original

The values should be undef. Meanings may be assigned to particular values in future.

=end original

値は undef であるべきです。
将来特定の値に関する割り当てが行われます。

=head3 C<swap_inner_handle>

  $rc = $h1->swap_inner_handle( $h2 );
  $rc = $h1->swap_inner_handle( $h2, $allow_reparent );

=begin original

Brain transplants for handles. You don't need to know about this
unless you want to become a handle surgeon.

=end original

ハンドルの脳移植です。
ハンドルの外科医になろうと思っているのでない限りこれについて知る
必要はありません。

=begin original

A DBI handle is a reference to a tied hash. A tied hash has an
I<inner> hash that actually holds the contents.  The swap_inner_handle()
method swaps the inner hashes between two handles. The $h1 and $h2
handles still point to the same tied hashes, but what those hashes
are tied to has been swapped.  In effect $h1 I<becomes> $h2 and
vice-versa. This is powerful stuff, expect problems. Use with care.

=end original

DBI ハンドルは tie されたハッシュへのリファレンスです。
tie されたハッシュは実際に内容を保持している I<内部> ハッシュを持っています。
swap_inner_handle() メソッドは二つのハンドルの内部ハッシュを入れ替えます。
$h1 と $h2 のハンドルは同じ tie されたハッシュを示したままですが、
どのハッシュに tie しているかは入れ替わります。
事実上 $h1 は $h2 に I<なり>、逆もまた真なりです。
これは問題もはらんでいる、強力な機能です。
注意して使ってください。

=begin original

As a small safety measure, the two handles, $h1 and $h2, have to
share the same parent unless $allow_reparent is true.

=end original

小さな安全性の尺度として、二つのハンドル $h1 と $h2 は、
$allow_reparent が真でない限り同じ親を共有している必要があります。

=begin original

The swap_inner_handle() method was added in DBI 1.44.

=end original

swap_inner_handle() メソッドは DBI 1.44 で追加されました。

=begin original

Here's a quick kind of 'diagram' as a worked example to help think about what's
happening:

=end original

以下は、何が起きているかについて考える助けとなる動作する例の
「ダイアグラム」です:

    Original state:
            dbh1o -> dbh1i
            sthAo -> sthAi(dbh1i)
            dbh2o -> dbh2i

    swap_inner_handle dbh1o with dbh2o:
            dbh2o -> dbh1i
            sthAo -> sthAi(dbh1i)
            dbh1o -> dbh2i

    create new sth from dbh1o:
            dbh2o -> dbh1i
            sthAo -> sthAi(dbh1i)
            dbh1o -> dbh2i
            sthBo -> sthBi(dbh2i)

    swap_inner_handle sthAo with sthBo:
            dbh2o -> dbh1i
            sthBo -> sthAi(dbh1i)
            dbh1o -> dbh2i
            sthAo -> sthBi(dbh2i)

=head3 C<visit_child_handles>

  $h->visit_child_handles( $coderef );
  $h->visit_child_handles( $coderef, $info );

=begin original

Where $coderef is a reference to a subroutine and $info is an arbitrary value
which, if undefined, defaults to a reference to an empty hash. Returns $info.

=end original

$coderef はサブルーチンへのリファレンスで、$info は任意の値であり、
もし未定義ならデフォルトはからハッシュへのリファレンスとなります。
$info を返します。

=begin original

For each child handle of $h, if any, $coderef is invoked as:

=end original

子ハンドルがあれば、各ハンドル $h 毎に、$coderef は以下のようにして
起動されます:

  $coderef->($child_handle, $info);

=begin original

If the execution of $coderef returns a true value then C<visit_child_handles>
is called on that child handle and passed the returned value as $info.

=end original

$coderef の実行によって真の値が返されると、L</visit_child_handles> が
子ハンドルに呼び出され、返された値を $info として渡します。

=begin original

For example:

=end original

例えば:

  # count database connections with names (DSN) matching a pattern
  my $connections = 0;
  $dbh->{Driver}->visit_child_handles(sub {
      my ($h, $info) = @_;
      ++$connections if $h->{Name} =~ /foo/;
      return 0; # don't visit kids
  })

=begin original

See also L</visit_handles>.

=end original

L</visit_handles> も参照してください。

=head1 ATTRIBUTES COMMON TO ALL HANDLES

(全てのハンドルに共通の属性)

=begin original

These attributes are common to all types of DBI handles.

=end original

これらの属性はDBIの全種類のハンドルについて共通です。

=begin original

Some attributes are inherited by child handles. That is, the value
of an inherited attribute in a newly created statement handle is the
same as the value in the parent database handle. Changes to attributes
in the new statement handle do not affect the parent database handle
and changes to the database handle do not affect existing statement
handles, only future ones.

=end original

属性によっては、子供に継承されるものもあります。つまり新しく作られる
文ハンドルでの継承される属性の値は、その親となる
データベースハンドルでの値と同じになります。
新しい文ハンドルでの属性を変更しても親のデータベースハンドルには
影響を与えませんし、データベースハンドルの属性を変更しても、
既存の文ハンドルには影響を与えません。
新しく作られるものだけです。

=begin original

Attempting to set or get the value of an unknown attribute generates a warning,
except for private driver specific attributes (which all have names
starting with a lowercase letter).

=end original

ドライバ特有のプライベートな属性(これらの名前は小文字ではじまります)を
除いては、決められていない属性を設定あるいは取得しようとすると
警告が発生します。

=begin original

Example:

=end original

例:

  $h->{AttributeName} = ...;	# set/write
  ... = $h->{AttributeName};	# get/read

=head3 C<Warn> (boolean, inherited)

=begin original

The C<Warn> attribute enables useful warnings for certain bad
practices. It is enabled by default and should only be disabled in
rare circumstances.  Since warnings are generated using the Perl
C<warn> function, they can be intercepted using the Perl C<$SIG{__WARN__}>
hook.

=end original

C<Warn> 属性はある種のよくない実践に対する有効な警告を有効にします。
デフォルトでは有効になっています。
これはデフォルトで有効になっていて、特殊な状況でのみ無効にするべきです。
警告は Perl の C<warn> 関数を使って生成されるので、Perl の
C<$SIG{__WARN__}> フックを使って、割り込むことが可能です。 

=begin original

The C<Warn> attribute is not related to the C<PrintWarn> attribute.

=end original

C<Warn> 属性は C<PrintWarn> 属性とは関係ありません。

=head3 C<Active> (boolean, read-only)

=begin original

The C<Active> attribute is true if the handle object is "active". This is rarely used in
applications. The exact meaning of active is somewhat vague at the
moment. For a database handle it typically means that the handle is
connected to a database (C<$dbh-E<gt>disconnect> sets C<Active> off).  For
a statement handle it typically means that the handle is a C<SELECT>
that may have more data to fetch. (Fetching all the data or calling C<$sth-E<gt>finish>
sets C<Active> off.)

=end original

C<Active> 属性は、ハンドルオブジェクトが生きている("Active")であれば
真になります。
アプリケーションで使われることはまずありません。
"Active"の正確な意味は、その時点によって若干違ってきます。
データベースハンドルにとっては、普通そのハンドルがデータベースに
接続されていることを意味します。
(C<$dbh-E<gt>disconnect> は C<Active> をオフにします)。
文ハンドルにとって典型的なものは、まだ取り出せるデータが
存在するであろう C<SELECT> であることを意味します。
(すべてのデータを取り出してしまうか、
C<$sth-E<gt>finish> を実行すると C<Active> をオフに設定します)。 

=head3 C<Executed> (boolean)

=begin original

The C<Executed> attribute is true if the handle object has been "executed".
Currently only the $dbh do() method and the $sth execute(), execute_array(),
and execute_for_fetch() methods set the C<Executed> attribute.

=end original

C<Executed> 属性は、ハンドルオブジェクトが「実行された」場合に真になります。
現在のところ、$dbh の do() メソッドと、$sth の execute(), execute_array(),
execute_for_fetch() メソッドが C<Executed> 属性を設定します。

=begin original

When it's set on a handle it is also set on the parent handle at the
same time. So calling execute() on a $sth also sets the C<Executed>
attribute on the parent $dbh.

=end original

ハンドルに設定すると、同時に親ハンドルにも設定されます。
したがって、$sthでexecute()を呼び出すと、親の$dbhにもC<Executed>属性が設定されます。
(TBR)

=begin original

The C<Executed> attribute for a database handle is cleared by the commit() and
rollback() methods (even if they fail). The C<Executed> attribute of a
statement handle is not cleared by the DBI under any circumstances and so acts
as a permanent record of whether the statement handle was ever used.

=end original

データベースハンドルのC<Executed>属性は、(失敗した場合でも)commit()およびrollback()メソッドによってクリアされます。
文ハンドルのC<Executed>属性は、どのような状況でもDBIによってクリアされないため、文ハンドルが使用されたことがあるかどうかを示す永続的なレコードとして機能します。
(TBR)

=begin original

The C<Executed> attribute was added in DBI 1.41.

=end original

C<Executed> 属性は DBI 1.41 で追加されました。

=head3 C<Kids> (integer, read-only)

=begin original

For a driver handle, C<Kids> is the number of currently existing database
handles that were created from that driver handle.  For a database
handle, C<Kids> is the number of currently existing statement handles that
were created from that database handle.
For a statement handle, the value is zero.

=end original

ドライバハンドルの場合、C<Kids> はそのドライバハンドルから作られ、現在
存在しているデータベースハンドルの数になります。
データベースハンドルの場合、C<Kids> はそのデータベースハンドルから作られ、
現在存在している文ハンドルの数になります。 
文ハンドルの場合、値は 0 です。

=head3 C<ActiveKids> (integer, read-only)

=begin original

Like C<Kids>, but only counting those that are C<Active> (as above).

=end original

C<Kids> と同様ですが、C<Active> なものだけをカウントします(上記参照)。 

=head3 C<CachedKids> (hash ref)

=begin original

For a database handle, C<CachedKids> returns a reference to the cache (hash) of
statement handles created by the L</prepare_cached> method.  For a
driver handle, returns a reference to the cache (hash) of
database handles created by the L</connect_cached> method.

=end original

データベース・ハンドルの場合、C<CachedKids> は
L</prepare_cached> メソッドにより生成された文ハンドルの
キャッシュ(ハッシュ)へのリファレンスを返します。
ドライバハンドルの場合、L</connect_cached> メソッドにより作成された
文ハンドルのキャッシュ(ハッシュ)へのリファレンスを返します。 

=head3 C<Type> (scalar, read-only)

=begin original

The C<Type> attribute identifies the type of a DBI handle.  Returns
"dr" for driver handles, "db" for database handles and "st" for
statement handles.

=end original

C<Type> 属性は DBI ハンドルの種類を識別します。
ドライバハンドルの場合は "dr" を、データベースハンドルの場合は "db" を、
文ハンドルの場合は "st" を返します。

=head3 C<ChildHandles> (array ref)

=begin original

The ChildHandles attribute contains a reference to an array of all the
handles created by this handle which are still accessible.  The
contents of the array are weak-refs and will become undef when the
handle goes out of scope.

=end original

ChildHandles 属性は、このハンドルによって作られてまだアクセス可能な
全てのハンドルの配列へのリファレンスを含みます。
配列の内容は弱い参照で、ハンドルがスコープ外に出ると undef になります。

=begin original

C<ChildHandles> returns undef if your perl version does not support weak
references (check the L<Scalar::Util|Scalar::Util> module).  The referenced
array returned should be treated as read-only.

=end original

Perlのバージョンが弱い参照をサポートしていない場合、C<ChildHandles>はundefを返します(L<Scalar::Util|Scalar::Util>モジュールをチェックしてください)。
返された参照配列は読み取り専用として扱われます。
(TBR)

=begin original

For example, to enumerate all driver handles, database handles and
statement handles:

=end original

例えば、全てのドライバハンドル、データベースハンドル、文ハンドルを
数え上げるには:

    sub show_child_handles {
        my ($h, $level) = @_;
        printf "%sh %s %s\n", $h->{Type}, "\t" x $level, $h;
        show_child_handles($_, $level + 1)
            for (grep { defined } @{$h->{ChildHandles}});
    }

    my %drivers = DBI->installed_drivers();
    show_child_handles($_, 0) for (values %drivers);

=head3 C<CompatMode> (boolean, inherited)

=begin original

The C<CompatMode> attribute is used by emulation layers (such as
Oraperl) to enable compatible behaviour in the underlying driver
(e.g., DBD::Oracle) for this handle. Not normally set by application code.

=end original

C<CompatMode> 属性は(Oraperl のような)エミュレーション層で使われ、
このハンドルのために元になっているドライバ(例えば DBD::Oracle)で
互換性のある動きをすることを可能にします。
アプリケーションプログラムでは通常使われることはありません。 

=begin original

It also has the effect of disabling the 'quick FETCH' of attribute
values from the handles attribute cache. So all attribute values
are handled by the drivers own FETCH method. This makes them slightly
slower but is useful for special-purpose drivers like DBD::Multiplex.

=end original

また、ハンドル属性キャッシュからの属性値の「クイックFETCH」を無効にする効果もあります。
したがって、すべての属性値はドライバ独自のFETCHメソッドによって処理されます。
これにより、それらは少し遅くなりますが、DBD::Multiplexのような特別な目的のドライバには有用です。
(TBR)

=head3 C<InactiveDestroy> (boolean)

=begin original

The default value, false, means a handle will be fully destroyed
as normal when the last reference to it is removed, just as you'd expect.

=end original

デフォルト値である偽は、予想している通り、ハンドルへの最後のリファレンスが
削除されると通常通り完全に破壊されることを意味します。

=begin original

If set true then the handle will be treated by the DESTROY as if it was no
longer Active, and so the I<database engine> related effects of DESTROYing a
handle will be skipped.

=end original

trueに設定すると、ハンドルはDESTROYによってアクティブではなくなったものとして処理されるため、ハンドルをDESTROYingするI<database engine>関連の効果はスキップされます。
(TBR)

=begin original

Think of the name as meaning 'treat the handle as not-Active in the DESTROY
method'.

=end original

名前は「ハンドルを、DESTROY メソッド内では非アクティブとして扱う」という
意味です。

=begin original

For a database handle, this attribute does not disable an I<explicit>
call to the disconnect method, only the implicit call from DESTROY
that happens if the handle is still marked as C<Active>.

=end original

データベースハンドルにとっては、この属性は disconnect メソッドの
I<明示的な> 呼び出しを無効にせず、ハンドルに C<Active> とマークされている
ときに DESTROY から暗黙の呼び出しだけを無効にします。

=begin original

This attribute is specifically designed for use in Unix applications
that "fork" child processes. Either the parent or the child process,
but not both, should set C<InactiveDestroy> true on all their shared handles.
(Note that some databases, including Oracle, don't support passing a
database connection across a fork.)

=end original

この属性は、特に子プロセスを "fork" する UNIX アプリケーションでの
使用について設計されています。
親と子の両方ではなくどちらか片方だけが、共有しているハンドルのすべてに
C<InactiveDestroy> を設定するべきです。
(Oracle を含めて、いくつかのドライバはデータベース接続を fork をまたがって
渡すことをサポートしていないことに注意してください。)

=begin original

To help tracing applications using fork the process id is shown in
the trace log whenever a DBI or handle trace() method is called.
The process id also shown for I<every> method call if the DBI trace
level (not handle trace level) is set high enough to show the trace
from the DBI's method dispatcher, e.g. >= 9.

=end original

forkを使用したアプリケーションのトレースを支援するために、DBIまたはhandle trace()メソッドが呼び出されるたびに、プロセスIDがトレースログに表示されます。
DBIトレースレベル(ハンドルトレースレベルではない)がDBIのメソッドディスパッチャからのトレースを表示するのに十分な高さに設定されている場合(>=9など)、I<every>メソッドコールに対してもプロセスIDが表示されます。
(TBR)

=head3 C<PrintWarn> (boolean, inherited)

=begin original

The C<PrintWarn> attribute controls the printing of warnings recorded
by the driver.  When set to a true value the DBI will check method
calls to see if a warning condition has been set. If so, the DBI
will effectively do a C<warn("$class $method warning: $DBI::errstr")>
where C<$class> is the driver class and C<$method> is the name of
the method which failed. E.g.,

=end original

C<PrintWarn> 属性は、ドライバによって記録された警告の表示を制御します。
真の値に設定されると、
警告条件が設定されたかどうかメソッド呼び出しをチェックします。
その場合、DBI は事実上 C<warn("$class $method warning: $DBI::errstr")> を
実行します; ここで C<$class> はドライバクラスで C<$method> は失敗した
メソッドの名前です。
例えば:

  DBD::Oracle::db execute warning: ... warning text here ...

=begin original

By default, C<DBI-E<gt>connect> sets C<PrintWarn> "on" if $^W is true,
i.e., perl is running with warnings enabled.

=end original

$^W が真なら C<PrintWarn> 属性のデフォルトはオンです; つまり、perl は
警告を有効にして動作します。

=begin original

If desired, the warnings can be caught and processed using a C<$SIG{__WARN__}>
handler or modules like CGI::Carp and CGI::ErrorWrap.

=end original

もし望むなら、C<$SIG{__WARN__}> ハンドラまたは CGI::Carp や
CGI::ErrorWrap のようなモジュールを使って、警告を捕捉して処理できます。

=begin original

See also L</set_err> for how warnings are recorded and L</HandleSetErr>
for how to influence it.

=end original

警告がどのように記録されるかについては L</set_err> も、それがどのように
影響を与えるかについては L</HandleSetErr> も参照してください。

=begin original

Fetching the full details of warnings can require an extra round-trip
to the database server for some drivers. In which case the driver
may opt to only fetch the full details of warnings if the C<PrintWarn>
attribute is true. If C<PrintWarn> is false then these drivers should
still indicate the fact that there were warnings by setting the
warning string to, for example: "3 warnings".

=end original

一部のドライバでは、警告の完全な詳細をフェッチするために、データベースサーバーへの余分なラウンドトリップが必要になる場合があります。
この場合、ドライバは、C<PrintWarn>属性がTRUEの場合にのみ、警告の完全な詳細をフェッチすることを選択できます。
C<PrintWarn>がFALSEの場合でも、これらのドライバは、警告文字列を「3 warnings」などに設定することによって、警告があったことを示す必要があります。
(TBR)

=head3 C<PrintError> (boolean, inherited)

=begin original

The C<PrintError> attribute can be used to force errors to generate warnings (using
C<warn>) in addition to returning error codes in the normal way.  When set
"on", any method which results in an error occurring will cause the DBI to
effectively do a C<warn("$class $method failed: $DBI::errstr")> where C<$class>
is the driver class and C<$method> is the name of the method which failed. E.g.,

=end original

C<PrintError> 属性は、エラーが発生したら、通常の方法でエラーコードを
返すことに加えて、(C<warn> を使って)警告を生成するように強制します。
"on"に設定されているとき、なんらかのメソッドがエラーになると、DBI に
事実上 C<warn("$class $method failed: $DBI::errstr")> を実行させます;
C<$class> にはドライバクラス、C<$method> には失敗したメソッドが入ります。
例えば 

  DBD::Oracle::db prepare failed: ... error text here ...

=begin original

By default, C<DBI-E<gt>connect> sets C<PrintError> "on".

=end original

デフォルトでは、C<DBI-E<gt>connect> は C<PrintError> を
"on" に設定します。

=begin original

If desired, the warnings can be caught and processed using a C<$SIG{__WARN__}>
handler or modules like CGI::Carp and CGI::ErrorWrap.

=end original

もし望むなら、C<$SIG{__WARN__}> ハンドラまたは CGI::Carp や
CGI::ErrorWrap のようなモジュールを使って、警告を捕捉して処理できます。

=head3 C<RaiseError> (boolean, inherited)

=begin original

The C<RaiseError> attribute can be used to force errors to raise exceptions rather
than simply return error codes in the normal way. It is "off" by default.
When set "on", any method which results in an error will cause
the DBI to effectively do a C<die("$class $method failed: $DBI::errstr")>,
where C<$class> is the driver class and C<$method> is the name of the method
that failed. E.g.,

=end original

C<RaiseError> 属性はエラー発生時に通常通り単にエラーコードを返すのではなく、
例外を発生させるために使われます。
デフォルトは"off"です。
"on" に設定されているとき、なんらかのメソッドでエラーになると、DBI に
事実上 C<die("$class $method failed: $DBI::errstr")> を実行させます;
C<$class> にはドライバクラス、C<$method> には失敗したメソッドが入ります。
例えば

  DBD::Oracle::db prepare failed: ... error text here ...

=begin original

If you turn C<RaiseError> on then you'd normally turn C<PrintError> off.
If C<PrintError> is also on, then the C<PrintError> is done first (naturally).

=end original

C<RaiseError> をオンにすると、普通 C<PrintError> はオフにします。
C<PrintError> もオンにすると、(自然なように) C<PrintError> がまず
実行されます。

=begin original

Typically C<RaiseError> is used in conjunction with C<eval { ... }>
to catch the exception that's been thrown and followed by an
C<if ($@) { ... }> block to handle the caught exception.
For example:

=end original

通常、C<RaiseError>は、スローされた例外をキャッチするためにC<eval{.}>とともに使用され、その後に、キャッチされた例外を処理するためのC<if($@){.}>ブロックが続きます。
次に例を示します。
(TBR)

  eval {
    ...
    $sth->execute();
    ...
  };
  if ($@) {
    # $sth->err and $DBI::err will be true if error was from DBI
    warn $@; # print the error
    ... # do whatever you need to deal with the error
  }

=begin original

In that eval block the $DBI::lasth variable can be useful for
diagnosis and reporting if you can't be sure which handle triggered
the error.  For example, $DBI::lasth->{Type} and $DBI::lasth->{Statement}.

=end original

このevalブロックでは、$DBI::lasth変数を使用すると、エラーの原因となったハンドルを特定できない場合に、診断やレポート作成に役立ちます。
たとえば、$DBI::lasth->{Type}や$DBI::lasth->{Statement}などです。
(TBR)

=begin original

See also L</Transactions>.

=end original

L</Transactions> も参照してください。

=begin original

If you want to temporarily turn C<RaiseError> off (inside a library function
that is likely to fail, for example), the recommended way is like this:

=end original

一時的に C<RaiseError> をオフに切り替えたいのであれば(例えば障害が
発生しやすいライブラリ関数の内部など)、以下のようにすることをお勧めします:

  {
    local $h->{RaiseError};  # localize and turn off for this block
    ...
  }

=begin original

The original value will automatically and reliably be restored by Perl,
regardless of how the block is exited.
The same logic applies to other attributes, including C<PrintError>.

=end original

そのブロックからどのように抜けたのかは関係なく、元の値は自動的に、信頼性を
持って Perl により保存されます。
C<PrintError> も含めて、他の属性についても同じロジックが適用されます。

=head3 C<HandleError> (code ref, inherited)

=begin original

The C<HandleError> attribute can be used to provide your own alternative behaviour
in case of errors. If set to a reference to a subroutine then that
subroutine is called when an error is detected (at the same point that
C<RaiseError> and C<PrintError> are handled).

=end original

C<HandleError> 属性は、エラー時に別の独自の振る舞いを提供するために
使われます。
サブルーチンへのリファレンスを設定すると、
エラーが検出されたときに (C<RaiseError> と C<PrintError> が
扱われるのと同じ時点で) そのサブルーチンが呼び出されます。

=begin original

The subroutine is called with three parameters: the error message
string that C<RaiseError> and C<PrintError> would use,
the DBI handle being used, and the first value being returned by
the method that failed (typically undef).

=end original

このサブルーチンは、C<RaiseError>およびC<PrintError>で使用されるエラーメッセージ文字列、使用されるDBIハンドル、および失敗したメソッドによって返される最初の値(通常はundef)の3つのパラメータを指定して呼び出されます。
(TBR)

=begin original

If the subroutine returns a false value then the C<RaiseError>
and/or C<PrintError> attributes are checked and acted upon as normal.

=end original

サブルーチンが偽の値を返すと、C<RaiseError> 属性や C<PrintError> 属性が
チェックされ、通常通り動作します。

=begin original

For example, to C<die> with a full stack trace for any error:

=end original

例えば、全てのエラーについて完全なスタックトレースと共に
C<die> させるには:

  use Carp;
  $h->{HandleError} = sub { confess(shift) };

=begin original

Or to turn errors into exceptions:

=end original

またはエラーを例外に変換するには:

  use Exception; # or your own favourite exception module
  $h->{HandleError} = sub { Exception->new('DBI')->raise($_[0]) };

=begin original

It is possible to 'stack' multiple HandleError handlers by using
closures:

=end original

クロージャを使うことで複数の HandleError ハンドラを「スタック」させることが
できます:

  sub your_subroutine {
    my $previous_handler = $h->{HandleError};
    $h->{HandleError} = sub {
      return 1 if $previous_handler and &$previous_handler(@_);
      ... your code here ...
    };
  }

=begin original

Using a C<my> inside a subroutine to store the previous C<HandleError>
value is important.  See L<perlsub> and L<perlref> for more information
about I<closures>.

=end original

サブルーチン内でC<my>を使用して、前のC<HandleError>値を格納することは重要です。
I<クロージャー>の詳細については、L<perlsub>およびL<perlref>を参照してください。
(TBR)

=begin original

It is possible for C<HandleError> to alter the error message that
will be used by C<RaiseError> and C<PrintError> if it returns false.
It can do that by altering the value of $_[0]. This example appends
a stack trace to all errors and, unlike the previous example using
Carp::confess, this will work C<PrintError> as well as C<RaiseError>:

=end original

C<HandleError>がfalseを返す場合は、C<RaiseError>およびC<PrintError>で使用されるエラーメッセージをC<HandleError>で変更できます。
これは、$_[0]の値を変更することで可能になります。
この例では、すべてのエラーにスタックトレースを追加します。
Carp::analを使用した前述の例とは異なり、これはC<PrintError>およびC<RaiseError>でも機能します:
(TBR)

  $h->{HandleError} = sub { $_[0]=Carp::longmess($_[0]); 0; };

=begin original

It is also possible for C<HandleError> to hide an error, to a limited
degree, by using L</set_err> to reset $DBI::err and $DBI::errstr,
and altering the return value of the failed method. For example:

=end original

C<HandleError>では、L</set_err>を使用して$DBI::errおよび$DBI::errstrをリセットし、失敗したメソッドの戻り値を変更することによって、限られた程度でエラーを非表示にすることもできます。
次に例を示します。
(TBR)

  $h->{HandleError} = sub {
    return 0 unless $_[0] =~ /^\S+ fetchrow_arrayref failed:/;
    return 0 unless $_[1]->err == 1234; # the error to 'hide'
    $h->set_err(undef,undef);	# turn off the error
    $_[2] = [ ... ];	# supply alternative return value
    return 1;
  };

=begin original

This only works for methods which return a single value and is hard
to make reliable (avoiding infinite loops, for example) and so isn't
recommended for general use!  If you find a I<good> use for it then
please let me know.

=end original

これは、単一の値を返すメソッドに対してのみ動作し、信頼性を確保するのが難しい(例えば、無限ループを回避する)ため、一般的な使用には推奨されません!もし、I<good>の使い方を見つけたら、教えてください。
(TBR)

=head3 C<HandleSetErr> (code ref, inherited)

=begin original

The C<HandleSetErr> attribute can be used to intercept
the setting of handle C<err>, C<errstr>, and C<state> values.
If set to a reference to a subroutine then that subroutine is called
whenever set_err() is called, typically by the driver or a subclass.

=end original

C<HandleSetErr> 属性は、C<err>, C<errstr>, C<state> の値を扱う設定に
割り込むために使われます。
サブルーチンへのリファレンスを設定すると、
(典型的にはドライバやサブクラスから)
set_err() が呼び出されたときにこのサブルーチンが呼び出されます。

=begin original

The subroutine is called with five arguments, the first five that
were passed to set_err(): the handle, the C<err>, C<errstr>, and
C<state> values being set, and the method name. These can be altered
by changing the values in the @_ array. The return value affects
set_err() behaviour, see L</set_err> for details.

=end original

サブルーチンは、set_err()に渡された最初の5つの引数(ハンドル、設定されたC<err>、C<errstr>、およびC<state>値、およびメソッド名)を使用して呼び出されます。
これらは@_arrayの値を変更することで変更できます。
戻り値はset_err()の動作に影響します。
詳細についてはL</set_err>を参照してください。
(TBR)

=begin original

It is possible to 'stack' multiple HandleSetErr handlers by using
closures. See L</HandleError> for an example.

=end original

クロージャを使うことで複数の HandleSetErr ハンドラを
「スタック」させることができます:
例については L</HandleError> を参照してください。

=begin original

The C<HandleSetErr> and C<HandleError> subroutines differ in subtle
but significant ways. HandleError is only invoked at the point where
the DBI is about to return to the application with C<err> set true.
It's not invoked by the failure of a method that's been called by
another DBI method.  HandleSetErr, on the other hand, is called
whenever set_err() is called with a defined C<err> value, even if false.
So it's not just for errors, despite the name, but also warn and info states.
The set_err() method, and thus HandleSetErr, may be called multiple
times within a method and is usually invoked from deep within driver code.

=end original

C<HandleSetErr>とC<HandleError>のサブルーチンは、微妙ですが重要な点で異なります。
HandleErrorは、C<err>がtrueに設定された状態でDBIがアプリケーションに戻ろうとする時点でのみ呼び出されます。
別のDBIメソッドによって呼び出されたメソッドの失敗によって呼び出されることはありません。
一方、HandleSetErrは、定義されたC<err>値でset_err()が呼び出されるたびに、falseであっても呼び出されます。
したがって、名前にかかわらずエラーに対してだけでなく、警告状態や情報状態に対しても呼び出されます。
set_err()メソッド、したがってHandleSetErrは、メソッド内で複数回呼び出される可能性があり、通常はドライバコードの奥深くから呼び出されます。
(TBR)

=begin original

In theory a driver can use the return value from HandleSetErr via
set_err() to decide whether to continue or not. If set_err() returns
an empty list, indicating that the HandleSetErr code has 'handled'
the 'error', the driver could then continue instead of failing (if
that's a reasonable thing to do).  This isn't excepted to be
common and any such cases should be clearly marked in the driver
documentation and discussed on the dbi-dev mailing list.

=end original

理論的には、ドライバはset_err()を介してHandleSetErrからの戻り値を使用して、続行するかどうかを決定できます。
set_err()が空のリストを返し、HandleSetErrコードが「エラー」を「処理した」ことを示した場合、ドライバは失敗するのではなく続行できます(それが合理的なことである場合)。
これは一般的であることを除外するものではなく、そのような場合はドライバの文書で明確にマークされ、dbi-devメーリングリストで議論されるべきです。
(TBR)

=begin original

The C<HandleSetErr> attribute was added in DBI 1.41.

=end original

C<HandleSetErr> 属性は DBI 1.41 で追加されました。

=head3 C<ErrCount> (unsigned integer)

=begin original

The C<ErrCount> attribute is incremented whenever the set_err()
method records an error. It isn't incremented by warnings or
information states. It is not reset by the DBI at any time.

=end original

C<ErrCount> 属性は、set_err() メソッドがエラーを記録する毎に
インクリメントされます。
これは警告や情報表示ではインクリメントされません。
これは DBI によってリセットされることはありません。

=begin original

The C<ErrCount> attribute was added in DBI 1.41. Older drivers may
not have been updated to use set_err() to record errors and so this
attribute may not be incremented when using them.

=end original

C<ErrCount> 属性は DBI 1.41 で追加されました。
より古いドライバはエラーを記録するために set_err() を使うときに
更新されないので、この属性はこれらを使ったときに
インクリメントされないかも知れません。

=head3 C<ShowErrorStatement> (boolean, inherited)

=begin original

The C<ShowErrorStatement> attribute can be used to cause the relevant
Statement text to be appended to the error messages generated by
the C<RaiseError>, C<PrintError>, and C<PrintWarn> attributes.
Only applies to errors on statement handles
plus the prepare(), do(), and the various C<select*()> database handle methods.
(The exact format of the appended text is subject to change.)

=end original

C<ShowErrorStatement> 属性は、
C<RaiseError>, C<PrintError>, C<PrintWarn> 属性によって
生成されたエラーメッセージに追加される、関連する Statement のテキストを
追加するために使われます。
文ハンドルのエラーに加えて、prepare(), do() および様々な
 C<select*()> データベースハンドルメソッドのエラーにのみ適用されます。
(追加されるテキストの正確な形式は変更されることがあります。)

=begin original

If C<$h-E<gt>{ParamValues}> returns a hash reference of parameter
(placeholder) values then those are formatted and appended to the
end of the Statement text in the error message.

=end original

C<$h-E<gt>{ParamValues}> がパラメータ(プレースホルダ)の値の
ハッシュリファレンスを返す場合、これらはフォーマットされて
エラーメッセージの Statement のテキストの末尾に追加されます。

=head3 C<TraceLevel> (integer, inherited)

=begin original

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.

=end original

C<TraceLevel> 属性は、DBI トレースレベルと特定のハンドルのトレースフラグを
設定するための L</trace> メソッドの代わりとして使えます。
さらなる詳細については L</TRACING> を参照してください。

=begin original

The C<TraceLevel> attribute is especially useful combined with
C<local> to alter the trace settings for just a single block of code.

=end original

C<TraceLevel> 属性は、特定の一つのブロックのコードでだけトレース設定を
変更するために C<local> を組み合わせると特に便利です。

=head3 C<FetchHashKeyName> (string, inherited)

=begin original

The C<FetchHashKeyName> attribute is used to specify whether the fetchrow_hashref()
method should perform case conversion on the field names used for
the hash keys. For historical reasons it defaults to 'C<NAME>' but
it is recommended to set it to 'C<NAME_lc>' (convert to lower case)
or 'C<NAME_uc>' (convert to upper case) according to your preference.
It can only be set for driver and database handles.  For statement
handles the value is frozen when prepare() is called.

=end original

C<FetchHashKeyName>属性は、fetchrow_uc()メソッドがハッシュキーに使用されるフィールド名に対して大文字と小文字の変換を実行するかどうかを指定するために使用されます。
歴史的な理由により、デフォルトは'C<NAME>'ですが、好みに応じて'C<NAME_lc>'(小文字に変換)または'C<NAME_uc>'(大文字に変換)に設定することをお薦めします。
これは、ドライバおよびデータベースハンドルに対してのみ設定できます。
ステートメントハンドルの場合、prepare()が呼び出されると値が凍結されます。
hashref
(TBR)

=head3 C<ChopBlanks> (boolean, inherited)

=begin original

The C<ChopBlanks> attribute can be used to control the trimming of trailing space
characters from fixed width character (CHAR) fields. No other field
types are affected, even where field values have trailing spaces.

=end original

C<ChopBlanks> 属性は固定長文字列(CHAR)フィールドから末尾の空白を
取り除くことを制御するために使われます。
他のフィールドタイプには、例え末尾に空白がついていても、影響を与えません。 

=begin original

The default is false (although it is possible that the default may change).
Applications that need specific behaviour should set the attribute as
needed.

=end original

デフォルトは偽です。
(しかしデフォルトが変更される可能性があります)。
特定の動きが必要なアプリケーションは、この属性を必要な値に設定します。

=begin original

Drivers are not required to support this attribute, but any driver which
does not support it must arrange to return C<undef> as the attribute value.

=end original

ドライバはこの属性をサポートしなければならないわけではありません。
しかしサポートしていないドライバはこの属性の値として C<undef> を
返すようにしなければなりません。

=head3 C<LongReadLen> (unsigned integer, inherited)

=begin original

The C<LongReadLen> attribute may be used to control the maximum
length of 'long' type fields (LONG, BLOB, CLOB, MEMO, etc.) which the driver will
read from the database automatically when it fetches each row of data.

=end original

C<LongReadLen> 属性は、データ行を取り出す際に、ドライバがデータベースから
自動的に読みこむ「長い」フィールド(LONG, BLOB, CLOB, MEMO など)の
最大長を制御するために使われます。

=begin original

The C<LongReadLen> attribute only relates to fetching and reading
long values; it is not involved in inserting or updating them.

=end original

C<LongReadLen> 属性は「長い」値の取り出しと読みこみにだけ関連します;
挿入や更新のときには関係しません。 

=begin original

A value of 0 means not to automatically fetch any long data.
Drivers may return undef or an empty string for long fields when
C<LongReadLen> is 0.

=end original

値が 0 は、「長い」データは自動的に取り出されないことを意味します。
C<LongReadLen> が 0 のとき、「長い」フィールドの値は undef または
空文字列になります。

=begin original

The default is typically 0 (zero) or 80 bytes but may vary between drivers.
Applications fetching long fields should set this value to slightly
larger than the longest long field value to be fetched.

=end original

デフォルトは通常 0 または 80 バイトですが、ドライバによって違うかもしれません。
「長い」フィールドを取り出すアプリケーションは、取り出される
「長い」フィールドの最大長よりもちょっとだけ大きい値を、
この値に設定しなければなりません。

=begin original

Some databases return some long types encoded as pairs of hex digits.
For these types, C<LongReadLen> relates to the underlying data
length and not the doubled-up length of the encoded string.

=end original

ある種のデータベースは「長い」タイプを 16 進のペアでエンコードして返す
場合があります。
これらのタイプについては、C<LongReadLen> はエンコードされた文字列の
2 倍になった長さではなく、基になっているデータ長に関係します。

=begin original

Changing the value of C<LongReadLen> for a statement handle after it
has been C<prepare>'d will typically have no effect, so it's common to
set C<LongReadLen> on the C<$dbh> before calling C<prepare>.

=end original

既に C<prepare> された後に、文ハンドルの C<LongReadLen> を
変更しても、通常、何も影響を与えません;
そのため普通、C<prepare> を呼び出す前に、C<$dbh> に対して C<LongReadLen> を
設定します。

=begin original

For most drivers the value used here has a direct effect on the
memory used by the statement handle while it's active, so don't be
too generous. If you can't be sure what value to use you could
execute an extra select statement to determine the longest value.
For example:

=end original

ほとんどのドライバではここに使われる値が有効な文ハンドルによって
使われるメモリに対して直接的な影響を与えることに注意してください。
そのため、あまり気前よくならないようにしてください。
この値の使い方がはっきりとわからないなら、一番長い値を決定するために
追加の select 文を実行できます。
例えば:

  $dbh->{LongReadLen} = $dbh->selectrow_array(qq{
      SELECT MAX(OCTET_LENGTH(long_column_name))
      FROM table WHERE ...
  });
  $sth = $dbh->prepare(qq{
      SELECT long_column_name, ... FROM table WHERE ...
  });

=begin original

You may need to take extra care if the table can be modified between
the first select and the second being executed. You may also need to
use a different function if OCTET_LENGTH() does not work for long
types in your database. For example, for Sybase use DATALENGTH() and
for Oracle use LENGTHB().

=end original

最初の選択から2番目の選択が実行されるまでの間に表が変更される可能性がある場合は、特に注意する必要があります。
また、OCTET_LENGTH()がデータベースのlong型に対して機能しない場合は、別の関数を使用する必要があります。
たとえば、Sybaseの場合はDATALENGTH()を使用し、Oracleの場合はLENGTHB()を使用します。
(TBR)

=begin original

See also L</LongTruncOk> for information on truncation of long types.

=end original

長い型の切り詰めに関する情報については L</LongTruncOk> も参照してください。

=head3 C<LongTruncOk> (boolean, inherited)

=begin original

The C<LongTruncOk> attribute may be used to control the effect of
fetching a long field value which has been truncated (typically
because it's longer than the value of the C<LongReadLen> attribute).

=end original

C<LongTruncOk> 属性は、(通常は C<LongReadLen> 属性よりも長いために)
切り捨てられる「長い」フィールドの取り出しの影響を制御するために使われます。 

=begin original

By default, C<LongTruncOk> is false and so fetching a long value that
needs to be truncated will cause the fetch to fail.
(Applications should always be sure to
check for errors after a fetch loop in case an error, such as a divide
by zero or long field truncation, caused the fetch to terminate
prematurely.)

=end original

デフォルトでは C<LongTruncOk> は偽です; そのため切り捨てられる必要がある
「長い」値を取り出すと取り出し失敗となります。
(アプリケーションは、エラーの場合、取り出しループの後で、エラーを常に確実に
チェックしなければなりません。
0 除算、「長い」フィールドの切り捨てなどによって取り出しが早く
終わってしまうことがあります。)

=begin original

If a fetch fails due to a long field truncation when C<LongTruncOk> is
false, many drivers will allow you to continue fetching further rows.

=end original

C<LongTruncOk> が偽のとき、「長い」フィールドにより取り出しが失敗しても、
多くのドライバでは先の行を取り出すことができます。

=begin original

See also L</LongReadLen>.

=end original

L</LongReadLen> も参照してください。

=head3 C<TaintIn> (boolean, inherited)

=begin original

If the C<TaintIn> attribute is set to a true value I<and> Perl is running in
taint mode (e.g., started with the C<-T> option), then all the arguments
to most DBI method calls are checked for being tainted. I<This may change.>

=end original

C<TaintIn>属性が真の値に設定され、I<かつ>Perlが汚染モードで実行されている場合
(たとえば、C<-T>オプションで開始された場合)、ほとんどのDBIメソッド呼び出しの
すべての引数が汚染されているかどうかがチェックされます。
I<これは変更される可能性があります。>
(TBR)

=begin original

The attribute defaults to off, even if Perl is in taint mode.
See L<perlsec> for more about taint mode.  If Perl is not
running in taint mode, this attribute has no effect.

=end original

Perl が汚染モードであっても、この属性のデフォルトはオフです。
汚染モードについてのさらなる情報は L<perlsec> を参照してください。
Perl が汚染モードで実行されていなければ、これは何も効果がありません。

=begin original

When fetching data that you trust you can turn off the TaintIn attribute,
for that statement handle, for the duration of the fetch loop.

=end original

信頼できるデータをフェッチするときには、そのフェッチループの間、
その文ハンドルに対して、TaintIn 属性をオフにできます。

=begin original

The C<TaintIn> attribute was added in DBI 1.31.

=end original

C<TaintIn> 属性は DBI 1.31 で追加されました。

=head3 C<TaintOut> (boolean, inherited)

=begin original

If the C<TaintOut> attribute is set to a true value I<and> Perl is running in
taint mode (e.g., started with the C<-T> option), then most data fetched
from the database is considered tainted. I<This may change.>

=end original

C<TaintOut> 属性に真の値が設定され、I<かつ> Perl が汚染(taint)モード
(例えば C<-T> オプションで開始されて)で実行されていれば、データベースから
取り出されるすべてのデータは汚染されているとチェックされます。
I<これは変更されるかもしれません。>

=begin original

The attribute defaults to off, even if Perl is in taint mode.
See L<perlsec> for more about taint mode.  If Perl is not
running in taint mode, this attribute has no effect.

=end original

Perl が汚染モードであっても、この属性のデフォルトはオフです。
汚染モードについてのさらなる情報は L<perlsec> を参照してください。
Perl が汚染モードで実行されていなければ、これは何も効果がありません。

=begin original

When fetching data that you trust you can turn off the TaintOut attribute,
for that statement handle, for the duration of the fetch loop.

=end original

信頼できるデータを取り出すとき、文ハンドルについて、取り出し
ループの間は C<TaintOut> 属性をオフに切り替えることが出来ます。

=begin original

Currently only fetched data is tainted. It is possible that the results
of other DBI method calls, and the value of fetched attributes, may
also be tainted in future versions. That change may well break your
applications unless you take great care now. If you use DBI Taint mode,
please report your experience and any suggestions for changes.

=end original

現在は取り出されたデータだけが汚染されているとしています。
将来のバージョンでは他の DBI メソッド呼び出しの結果そして取り出された属性の
値も同様に汚染されているとするかもしれません。
今のうちに細心の注意を払わない限り、その変更はアプリケーションを
壊しかねません。
もし DBI を Taint モードで使うのであれば、変更のためにあなたの経験と提案を
報告してください。

=begin original

The C<TaintOut> attribute was added in DBI 1.31.

=end original

C<TaintOut> 属性は DBI 1.31 で追加されました。

=head3 C<Taint> (boolean, inherited)

=begin original

The C<Taint> attribute is a shortcut for L</TaintIn> and L</TaintOut> (it is also present
for backwards compatibility).

=end original

C<Taint> 属性は L</TaintIn> と L</TaintOut> へのショートカットです
(これはまた後方互換性のためにも存在しています)。

=begin original

Setting this attribute sets both L</TaintIn> and L</TaintOut>, and retrieving
it returns a true value if and only if L</TaintIn> and L</TaintOut> are
both set to true values.

=end original

この属性を設定すると、L</TaintIn>とL</TaintOut>の両方が設定されます。
この属性を取得すると、L</TaintIn>とL</TaintOut>の両方がtrue値に設定されている場合にのみtrue値が戻されます。
(TBR)

=head3 C<Profile> (inherited)

=begin original

The C<Profile> attribute enables the collection and reporting of method call timing statistics.
See the L<DBI::Profile> module documentation for I<much> more detail.

=end original

C<Profile> 属性は、メソッド呼び出しタイミング統計の収集と報告を
有効にします。
I<非常に> 細かな詳細については L<DBI::Profile> モジュールの文書を
参照してください。

=begin original

The C<Profile> attribute was added in DBI 1.24.

=end original

C<Profile> 属性は DBI 1.24 で追加されました。

=head3 C<ReadOnly> (boolean, inherited)

=begin original

An application can set the C<ReadOnly> attribute of a handle to a true value to
indicate that it will not be attempting to make any changes using that handle
or any children of it.

=end original

アプリケーションは、ハンドルのC<ReadOnly>属性をtrue値に設定して、そのハンドルまたはその子を使用して変更を試みないことを示すことができます。
(TBR)

=begin original

Note that the exact definition of 'read only' is rather fuzzy.
For more details see the documentation for the driver you're using.

=end original

「読み込み専用」の正確な定義はややあいまいであることに注意してください。
さらなる詳細については使っているドライバの文書を参照してください。

=begin original

If the driver can make the handle truly read-only then it should
(unless doing so would have unpleasant side effect, like changing the
consistency level from per-statement to per-session).
Otherwise the attribute is simply advisory.

=end original

ドライバがハンドルを本当に読み取り専用にできるのであれば、そうすべきです(ただし、整合性レベルを文単位からセッション単位に変更するなど、不快な副作用が発生する場合は除きます)。
そうでない場合は、この属性は単なるアドバイスです。
(TBR)

=begin original

A driver can set the C<ReadOnly> attribute itself to indicate that the data it
is connected to cannot be changed for some reason.

=end original

ドライバは、何らかの理由で変更できないものに接続しているデータであることを
示すために自らの C<ReadOnly> 属性を設定できます。

=begin original

Library modules and proxy drivers can use the attribute to influence their behavior.
For example, the DBD::Gofer driver considers the C<ReadOnly> attribute when
making a decision about whether to retry an operation that failed.

=end original

ライブラリモジュールおよびプロキシドライバは、この属性を使用して動作に影響を与えることができます。
たとえば、DBD::Goferドライバは、失敗した操作を再試行するかどうかを決定するときに、C<ReadOnly>属性を考慮します。
(TBR)

=begin original

The attribute should be set to 1 or 0 (or undef). Other values are reserved.

=end original

属性は 1 または 0 (または undef)に設定されるべきです。
その他の値は予約されています。

=head3 C<Callbacks> (hash ref)

=begin original

The DBI callback mechanism lets you intercept, and optionally replace, any
method call on a DBI handle. At the extreme, it lets you become a puppet
master, deceiving the application in any way you want.

=end original

DBIコールバックメカニズムを使用すると、DBIハンドル上の任意のメソッドコールをインターセプトし、オプションで置き換えることができます。
極端な場合には、それはあなたが操り人形のマスターになり、あなたが望む方法でアプリケーションを欺くことを可能にします。
(TBR)

=begin original

The C<Callbacks> attribute is a hash reference where the keys are DBI method
names and the values are code references. For each key naming a method, the
DBI will execute the associated code reference before executing the method.

=end original

C<Callbacks>属性はハッシュ参照で、キーはDBIメソッド名、値はコード参照です。
メソッドを指定する各キーに対して、DBIはメソッドを実行する前に関連付けられたコード参照を実行します。
(TBR)

=begin original

The arguments to the code reference will be the same as to the method,
including the invocant (a database handle or statement handle). For example,
say that to callback to some code on a call to C<prepare()>:

=end original

コード参照の引数は、invocant(データベースハンドルまたはステートメントハンドル)を含めて、メソッドの引数と同じになります。
たとえば、C<prepare()>の呼び出しでコードにコールバックするには、次のようにします。
(TBR)

  $dbh->{Callbacks} = {
      prepare => sub {
          my ($dbh, $query, $attrs) = @_;
          print "Preparing q{$query}\n"
      },
  };

=begin original

The callback would then be executed when you called the C<prepare()> method:

=end original

C<prepare()> メソッドを呼び出したときに、コールバックが実行されます:

  $dbh->prepare('SELECT 1');

=begin original

And the output of course would be:

=end original

そして出力はもちろん以下のようになります:

  Preparing q{SELECT 1}

=begin original

Because callbacks are executed I<before> the methods
they're associated with, you can modify the arguments before they're passed on
to the method call. For example, to make sure that all calls to C<prepare()>
are immediately prepared by L<DBD::Pg>, add a callback that makes sure that
the C<pg_prepare_now> attribute is always set:

=end original

コールバックは関連付けられたメソッドの<前>に実行されるため、メソッド呼び出しに渡される前に引数を変更できます。
例えば、C<prepare()>へのすべての呼び出しがL<DBD::Pg>によって即座に準備されるようにするには、C<pg_prepare_now>属性が常に設定されるようにするコールバックを追加します。
(TBR)

  my $dbh = DBI->connect($dsn, $username, $auth, {
      Callbacks => {
          prepare => sub {
              $_[2] ||= {};
              $_[2]->{pg_prepare_now} = 1;
              return; # must return nothing
          },
      }
  });

=begin original

Note that we are editing the contents of C<@_> directly. In this case we've
created the attributes hash if it's not passed to the C<prepare> call.

=end original

C<@_> の内容を直接編集していることに注意してください。
この場合、これが C<prepare> 呼び出しに渡されないなら属性ハッシュを
作成しています。

=begin original

You can also prevent the associated method from ever executing. While a
callback executes, C<$_> holds the method name. (This allows multiple callbacks
to share the same code reference and still know what method was called.)
To prevent the method from
executing, simply C<undef $_>. For example, if you wanted to disable calls to
C<ping()>, you could do this:

=end original

関連付けられたメソッドが実行されないようにすることもできます。
コールバックの実行中、C<$_>はメソッド名を保持します。
(これにより、複数のコールバックが同じコード参照を共有し、どのメソッドが呼び出されたかを知ることができます。
)メソッドが実行されないようにするには、単純にC<undef $_>を使用します。
たとえば、C<ping()>の呼び出しを無効にする場合は、次のようにします:
(TBR)

  $dbh->{Callbacks} = {
      ping => sub {
          # tell dispatch to not call the method:
          undef $_;
          # return this value instead:
          return "42 bells";
      }
  };

=begin original

As with other attributes, Callbacks can be specified on a handle or via the
attributes to C<connect()>. Callbacks can also be applied to a statement
methods on a statement handle. For example:

=end original

他の属性と同様に、コールバックはハンドル上で、またはC<connect()>の属性を介して指定できます。
コールバックは、文ハンドル上の文メソッドにも適用できます。
次に例を示します。
(TBR)

  $sth->{Callbacks} = {
      execute => sub {
          print "Executing ", shift->{Statement}, "\n";
      }
  };

=begin original

The C<Callbacks> attribute of a database handle isn't copied to any statement
handles it creates. So setting callbacks for a statement handle requires you to
set the C<Callbacks> attribute on the statement handle yourself, as in the
example above, or use the special C<ChildCallbacks> key described below.

=end original

データベースハンドルのC<Callbacks>属性は、作成された文ハンドルにはコピーされません。
そのため、文ハンドルにコールバックを設定するには、前述の例のように文ハンドルにC<Callbacks>属性を設定するか、次に説明する特殊なC<ChildCallbacks>キーを使用する必要があります。
(TBR)

=begin original

B<Special Keys in Callbacks Attribute>

=end original

B<Callbacks 属性の特殊キー>

=begin original

In addition to DBI handle method names, the C<Callbacks> hash reference
supports three additional keys.

=end original

DBI ハンドルメソッド名に加えて、C<Callbacks> ハッシュリファレンスは
三つの追加のキーに対応しています。

=begin original

The first is the C<ChildCallbacks> key. When a statement handle is created from
a database handle the C<ChildCallbacks> key of the database handle's
C<Callbacks> attribute, if any, becomes the new C<Callbacks> attribute of the
statement handle.
This allows you to define callbacks for all statement handles created from a
database handle. For example, if you wanted to count how many times C<execute>
was called in your application, you could write:

=end original

1つ目はC<ChildCallbacks>キーです。
データベースハンドルから文ハンドルが作成されると、データベースハンドルのC<Callbacks>属性のC<ChildCallbacks>キー(存在する場合)が、文ハンドルの新しいC<Callbacks>属性になります。
これにより、データベースハンドルから作成されたすべての文ハンドルのコールバックを定義できます。
たとえば、アプリケーションでC<execute>が呼び出された回数をカウントする場合は、次のように記述できます。
(TBR)

  my $exec_count = 0;
  my $dbh = DBI->connect( $dsn, $username, $auth, {
      Callbacks => {
          ChildCallbacks => {
              execute => sub { $exec_count++; return; }
          }
      }
  });

  END {
      print "The execute method was called $exec_count times\n";
  }

=begin original

The other two special keys are C<connect_cached.new> and
C<connect_cached.reused>. These keys define callbacks that are called when
C<connect_cached()> is called, but allow different behaviors depending on
whether a new handle is created or a handle is returned. The callback is
invoked with these arguments: C<$dbh, $dsn, $user, $auth, $attr>.

=end original

他の2つの特別なキーは、C<connect_cached.new>およびC<connect_cached.reused>です。
これらのキーは、C<connect_cached()>が呼び出されたときに呼び出されるコールバックを定義しますが、新しいハンドルが作成されるか、ハンドルが返されるかによって異なる動作が許可されます。
コールバックは、次の引数で呼び出されます:C<$dbh, $dsn, $user, $auth, $attr>。
(TBR)

=begin original

For example, some applications uses C<connect_cached()> to connect with
C<AutoCommit> enabled and then disable C<AutoCommit> temporarily for
transactions. If C<connect_cached()> is called during a transaction, perhaps in
a utility method, then it might select the same cached handle and then force
C<AutoCommit> on, forcing a commit of the transaction. See the L</connect_cached>
documentation for one way to deal with that. Here we'll describe an alternative
approach using a callback.

=end original

たとえば、一部のアプリケーションでは、C<connect_cached()>を使用してC<AutoCommit>を有効にして接続し、トランザクションに対して一時的にC<AutoCommit>を無効にします。
トランザクション中にユーティリティメソッドなどでC<connect_cached()>が呼び出されると、キャッシュされた同じハンドルが選択され、C<AutoCommit>が強制的にオンになり、トランザクションが強制的にコミットされる場合があります。
これに対処する1つの方法については、L</connect_cached>の文書を参照してください。
ここでは、コールバックを使用する別のアプローチについて説明します。
(TBR)

=begin original

Because the C<connect_cached.*> callbacks are invoked before connect_cached()
has applied the connect attributes you can use a callback to edit the attributes
that will be applied.  To prevent a cached handle from having its transactions
committed before it's returned, you can eliminate the C<AutoCommit> attribute
in a C<connect_cached.reused> callback, like so:

=end original

C<connect_cached.*>コールバックは、connect_cached()が接続属性を適用する前に呼び出されるため、コールバックを使用して、適用される属性を編集できます。
キャッシュされたハンドルが戻される前にトランザクションがコミットされないようにするには、次のようにC<connect_cached.reused>コールバックのC<AutoCommit>属性を削除します。
(TBR)

  my $cb = {
      ���connect_cached.reused��� => sub { delete $_[4]->{AutoCommit} },
  };

  sub dbh {
      my $self = shift;
      DBI->connect_cached( $dsn, $username, $auth, {
          PrintError => 0,
          RaiseError => 1,
          AutoCommit => 1,
          Callbacks  => $cb,
      });
  }

=begin original

The upshot is that new database handles are created with C<AutoCommit>
enabled, while cached database handles are left in whatever transaction state
they happened to be in when retrieved from the cache.

=end original

その結果、新しいデータベースハンドルはC<AutoCommit>を有効にして作成されますが、キャッシュされたデータベースハンドルは、キャッシュから取得されたときにたまたま存在していたトランザクション状態のままになります。
(TBR)

=begin original

A more common application for callbacks is setting connection state only when a
new connection is made (by connect() or connect_cached()). Adding a callback to
the connected method makes this easy.
This method is a no-op by default (unless you subclass the DBI and change it).
The DBI calls it to indicate that a new connection has been made and the connection
attributes have all been set.  You can
give it a bit of added functionality by applying a callback to it. For
example, to make sure that MySQL understands your application's ANSI-compliant
SQL, set it up like so:

=end original

コールバックのより一般的な用途は、(connect()またはconnect_cached()によって)新しい接続が作成されたときにのみ接続状態を設定することです。
接続されたメソッドにコールバックを追加すると、これが簡単になります。
このメソッドはデフォルトではno-opです(DBIをサブクラス化して変更しない限り)。
DBIはこのメソッドを呼び出して、新しい接続が作成され、接続属性がすべて設定されたことを示します。
コールバックを適用することで、少し機能を追加できます。
たとえば、MySQLがアプリケーションのANSI準拠のSQLを認識できるようにするには、次のように設定します:
(TBR)

  my $dbh = DBI->connect($dsn, $username, $auth, {
      Callbacks => {
          connected => sub {
              shift->do(q{
                  SET SESSION sql_mode='ansi,strict_trans_tables,no_auto_value_on_zero';
              });
              return;
          },
      }
  });

=begin original

One significant limitation with callbacks is that there can only be one per
method per handle. This means it's easy for one use of callbacks to interfere
with, or typically simply overwrite, another use of callbacks. For this reason
modules using callbacks should document the fact clearly so application authors
can tell if use of callbacks by the module will clash with use of callbacks by
the application.

=end original

コールバックの重要な制限の1つは、ハンドルごとにメソッドごとに1つしか存在できないことです。
これは、コールバックのある使用が、コールバックの別の使用と干渉したり、通常は単に上書きしたりすることが容易であることを意味します。
このため、コールバックを使用するモジュールは、モジュールによるコールバックの使用がアプリケーションによるコールバックの使用と競合するかどうかをアプリケーション作成者が判断できるように、その事実を明確に文書化する必要があります。
(TBR)

=begin original

You might be able to work around this issue by taking a copy of the original
callback and calling it within your own. For example:

=end original

元のコールバックのコピーを取って、そちらを呼ぶことでこの問題を
回避できるかもしれません。
例えば:

  my $prev_cb = $h->{Callbacks}{method_name};
  $h->{Callbacks}{method_name} = sub {
    if ($prev_cb) {
        my @result = $prev_cb->(@_);
	return @result if not $_; # $prev_cb vetoed call
    }
    ... your callback logic here ...
  };

=head3 C<private_your_module_name_*>

=begin original

The DBI provides a way to store extra information in a DBI handle as
"private" attributes. The DBI will allow you to store and retrieve any
attribute which has a name starting with "C<private_>".

=end original

DBI は「プライベート」属性として、DBI ハンドルでの特別な情報を格納する
方法を提供しています。
DBI では "C<private_>" で始まる名前の属性を格納、参照することができます。

=begin original

It is I<strongly> recommended that you use just I<one> private
attribute (e.g., use a hash ref) I<and> give it a long and unambiguous
name that includes the module or application name that the attribute
relates to (e.g., "C<private_YourFullModuleName_thingy>").

=end original

ただしプライベート属性は(例えばハッシュのリファレンスを使うなどにより)
I<一つ> だけとし、I<かつ> その属性に関連するモジュールまたは
アプリケーション名が入った長くて他にはないような名前にすることを
I<強く> お勧めします(例えば "C<private_YourFullModuleName_thingy>")。

=begin original

Because of the way the Perl tie mechanism works you cannot reliably
use the C<||=> operator directly to initialise the attribute, like this:

=end original

Perl の tie 機構の動作手法により、以下のように、属性を初期化するために
信頼できる形でC<||=> 演算子を直接使うことはできません。

  my $foo = $dbh->{private_yourmodname_foo} ||= { ... }; # WRONG

=begin original

you should use a two step approach like this:

=end original

以下のように二段階の手法を使うべきです:

  my $foo = $dbh->{private_yourmodname_foo};
  $foo ||= $dbh->{private_yourmodname_foo} = { ... };

=begin original

This attribute is primarily of interest to people sub-classing DBI,
or for applications to piggy-back extra information onto DBI handles.

=end original

この属性は基本的に DBI をサブクラス化する人々や、DBI ハンドルに
その他の情報を追加するアプリケーションが関心を持つものです。

=head1 DBI DATABASE HANDLE OBJECTS

(DBI データベースハンドルオブジェクト)

=begin original

This section covers the methods and attributes associated with
database handles.

=end original

このセクションはデータベース・ハンドルに関連するメソッドと属性について
カバーします。

=head2 Database Handle Methods

(データベースハンドルメソッド)

=begin original

The following methods are specified for DBI database handles:

=end original

以下のメソッドがDBIデータベース・ハンドルに指定されています:

=head3 C<clone>

  $new_dbh = $dbh->clone();
  $new_dbh = $dbh->clone(\%attr);

=begin original

The C<clone> method duplicates the $dbh connection by connecting
with the same parameters ($dsn, $user, $password) as originally used.

=end original

C<clone> メソッドは、$dbh 接続を、同じパラメータ ($dsn, $user, $password) で
接続することで複製します。

=begin original

The attributes for the cloned connect are the same as those used
for the original connect, with some other attributes merged over
them depending on the \%attr parameter.

=end original

複製された接続の属性は元の接続のものと同じものに、\%attr 引数によるものが
マージされたものです。

=begin original

If \%attr is given then the attributes it contains are merged into
the original attributes and override any with the same names.
Effectively the same as doing:

=end original

\%attrが指定された場合、それに含まれる属性は元の属性にマージされ、同じ名前の属性は上書きされます。
次の操作と実質的に同じです。
(TBR)

  %attribues_used = ( %original_attributes, %attr );

=begin original

If \%attr is not given then it defaults to a hash containing all
the attributes in the attribute cache of $dbh excluding any non-code
references, plus the main boolean attributes (RaiseError, PrintError,
AutoCommit, etc.). This behaviour is subject to change.

=end original

\%attrを指定しない場合、デフォルトでは、$dbhの属性キャッシュ内のすべての属性(コード参照以外を除く)に加えて、主要なブール属性(RaiseError、PrintError、AutoCommitなど)を含むハッシュが使用されます。
この動作は変更されることがあります。
(TBR)

=begin original

The clone method can be used even if the database handle is disconnected.

=end original

clone メソッドは例えばデータベースハンドルの接続が切れていても使えます。

=begin original

The C<clone> method was added in DBI 1.33. It is very new and likely
to change.

=end original

C<clone> メソッドは DBI 1.33 で追加されました。
これはとても新しく、変更されるかもしれません。

=head3 C<data_sources>

  @ary = $dbh->data_sources();
  @ary = $dbh->data_sources(\%attr);

=begin original

Returns a list of data sources (databases) available via the $dbh
driver's data_sources() method, plus any extra data sources that
the driver can discover via the connected $dbh. Typically the extra
data sources are other databases managed by the same server process
that the $dbh is connected to.

=end original

$dbhドライバのdata_sources()メソッドで使用可能なデータソース(データベース)のリストと、接続された$dbhを介してドライバが検出できる追加のデータソースを返します。
通常、追加のデータソースは、$dbhが接続されているのと同じサーバプロセスによって管理されている他のデータベースです。
(TBR)

=begin original

Data sources are returned in a form suitable for passing to the
L</connect> method (that is, they will include the "C<dbi:$driver:>" prefix).

=end original

データソースは L</connect> メソッドに渡すのに適したな形式で返されます
(つまり接頭辞 "C<dbi:$driver:>" が入ります。)

=begin original

The data_sources() method, for a $dbh, was added in DBI 1.38.

=end original

$dbh のための data_sources() メソッドは DBI 1.38 で追加されました。

=head3 C<do>

  $rows = $dbh->do($statement)           or die $dbh->errstr;
  $rows = $dbh->do($statement, \%attr)   or die $dbh->errstr;
  $rows = $dbh->do($statement, \%attr, @bind_values) or die ...

=begin original

Prepare and execute a single statement. Returns the number of rows
affected or C<undef> on error. A return value of C<-1> means the
number of rows is not known, not applicable, or not available.

=end original

一つの文を prepare し、execute します。
影響を受けた行の数を、またエラーであれば C<undef> を返します。
C<-1> は行の数が分からないか使用できないことを意味します。

=begin original

This method is typically most useful for I<non>-C<SELECT> statements that
either cannot be prepared in advance (due to a limitation of the
driver) or do not need to be executed repeatedly. It should not
be used for C<SELECT> statements because it does not return a statement
handle (so you can't fetch any data).

=end original

このメソッドは典型的には、(ドライバの制限により)前もって prepare されることが
なかったり、繰り返し実行しない C<SELECT> I<以外> の文でとても有効です。
文ハンドルを返さない(そのために何もデータを取り出せない)ので、
C<SELECT> 文では使うべきではありません。

=begin original

The default C<do> method is logically similar to:

=end original

デフォルトのdoメソッドは、論理的には以下のものと同様です:

  sub do {
      my($dbh, $statement, $attr, @bind_values) = @_;
      my $sth = $dbh->prepare($statement, $attr) or return undef;
      $sth->execute(@bind_values) or return undef;
      my $rows = $sth->rows;
      ($rows == 0) ? "0E0" : $rows; # always return true if no error
  }

=begin original

For example:

=end original

例えば:

  my $rows_deleted = $dbh->do(q{
      DELETE FROM table
      WHERE status = ?
  }, undef, 'DONE') or die $dbh->errstr;

=begin original

Using placeholders and C<@bind_values> with the C<do> method can be
useful because it avoids the need to correctly quote any variables
in the C<$statement>. But if you'll be executing the statement many
times then it's more efficient to C<prepare> it once and call
C<execute> many times instead.

=end original

プレースホルダとバインド変数(C<@bind_values>) を C<do> メソッドで使うと、
C<$statement> の中の変数を正しくクォートしなくてもよくなるためにとても
便利です。
しかしもし文を何度も実行するのであれば、代わりに
一度 C<prepare> し、何度も C<execute> するほうがより効率的です。

=begin original

The C<q{...}> style quoting used in this example avoids clashing with
quotes that may be used in the SQL statement. Use the double-quote-like
C<qq{...}> operator if you want to interpolate variables into the string.
See L<perlop/"Quote and Quote-like Operators"> for more details.

=end original

この例で使われている C<q{ ...}> 形式のクォートは、文で
使われているかもしれないクォートの対応を壊されないように使われています。
文字列に入っている変数を解釈したい場合には、ダブルクォート風
C<qq{...}> 演算子を使います。
詳細は L<perlop/"Quote and Quote-like Operators"> をご覧ください。

=head3 C<last_insert_id>

  $rv = $dbh->last_insert_id($catalog, $schema, $table, $field);
  $rv = $dbh->last_insert_id($catalog, $schema, $table, $field, \%attr);

=begin original

Returns a value 'identifying' the row just inserted, if possible.
Typically this would be a value assigned by the database server
to a column with an I<auto_increment> or I<serial> type.
Returns undef if the driver does not support the method or can't
determine the value.

=end original

可能であれば、挿入された行を'識別する'値を返します。
通常、これはI<auto_increment>またはI<serial>タイプの列にデータベースサーバによって割り当てられた値です。
ドライバがメソッドをサポートしていない場合、または値を判別できない場合は、undefを返します。
(TBR)

=begin original

The $catalog, $schema, $table, and $field parameters may be required
for some drivers (see below).  If you don't know the parameter values
and your driver does not need them, then use C<undef> for each.

=end original

一部のドライバでは、$catalog、$schema、$table、および$fieldパラメータが必要になる場合があります(以下を参照)。
パラメータの値がわからず、ドライバがそれらを必要としない場合は、それぞれにC<undef>を使用します。
(TBR)

=begin original

There are several caveats to be aware of with this method if you want
to use it for portable applications:

=end original

このメソッドを移植性のあるアプリケーションに使いたいなら、注意するべき
いくつかの警告があります:

=begin original

B<*> For some drivers the value may only available immediately after
the insert statement has executed (e.g., mysql, Informix).

=end original

B<*> ドライバによっては(mysql, Informix など)、値が insert 文が実行された
直後でのみ利用可能である場合があります。

=begin original

B<*> For some drivers the $catalog, $schema, $table, and $field parameters
are required, for others they are ignored (e.g., mysql).

=end original

B<*> ドライバによっては (mysql など)、$catalog, $schema, $table,
$field パラメータが必要であったり、無視されたりします。

=begin original

B<*> Drivers may return an indeterminate value if no insert has
been performed yet.

=end original

B<*> insert 文がまだ実行されていない場合、ドライバは不定な値を
返すかもしれません。

=begin original

B<*> For some drivers the value may only be available if placeholders
have I<not> been used (e.g., Sybase, MS SQL). In this case the value
returned would be from the last non-placeholder insert statement.

=end original

B<*>一部のドライバ(Sybase、MS SQLなど)では、プレースホルダI<not>が使用されている場合にのみ値が使用可能です。
この場合、返される値は、最後の非プレースホルダ挿入ステートメントからの値になります。
(TBR)

=begin original

B<*> Some drivers may need driver-specific hints about how to get
the value. For example, being told the name of the database 'sequence'
object that holds the value. Any such hints are passed as driver-specific
attributes in the \%attr parameter.

=end original

B<*>ドライバによっては、値の取得方法に関するドライバ固有のヒントが必要な場合があります。
たとえば、値を保持するデータベースのsequenceオブジェクトの名前が通知されます。
このようなヒントは、\%attrパラメータにドライバ固有の属性として渡されます。
(TBR)

=begin original

B<*> If the underlying database offers nothing better, then some
drivers may attempt to implement this method by executing
"C<select max($field) from $table>". Drivers using any approach
like this should issue a warning if C<AutoCommit> is true because
it is generally unsafe - another process may have modified the table
between your insert and the select. For situations where you know
it is safe, such as when you have locked the table, you can silence
the warning by passing C<Warn> => 0 in \%attr.

=end original

B<*>基盤となるデータベースがこれよりも優れたものを提供しない場合、一部のドライバは"C<select max($field) from $table>"を実行してこのメソッドを実装しようとする可能性があります。
このようなアプローチを使用するドライバは、C<AutoCommit>がtrueの場合に警告を発行する必要があります。
これは、一般的に安全ではないためです。
別のプロセスが挿入と選択の間にテーブルを変更した可能性があります。
テーブルをロックした場合など、安全であることがわかっている状況では、\%attrにC<Warn>=>0を渡すことによって警告を抑止できます。
(TBR)

=begin original

B<*> If no insert has been performed yet, or the last insert failed,
then the value is implementation defined.

=end original

B<*> まだ insert 文が実行されていなかったり、最後の insert 文が
失敗していたりした場合、値は実装依存です。

=begin original

Given all the caveats above, it's clear that this method must be
used with care.

=end original

上述全ての注意点から、このメソッドは注意して使わなければならないことは
明らかです。

=begin original

The C<last_insert_id> method was added in DBI 1.38.

=end original

C<last_insert_id> メソッドは DBI 1.38 で追加されました。

=head3 C<selectrow_array>

  @row_ary = $dbh->selectrow_array($statement);
  @row_ary = $dbh->selectrow_array($statement, \%attr);
  @row_ary = $dbh->selectrow_array($statement, \%attr, @bind_values);

=begin original

This utility method combines L</prepare>, L</execute> and
L</fetchrow_array> into a single call. If called in a list context, it
returns the first row of data from the statement.  The C<$statement>
parameter can be a previously prepared statement handle, in which case
the C<prepare> is skipped.

=end original

このユーティリティーメソッドは、L</prepare>, L</execute>,
L</fetchrow_array> を一回にまとめておこないます。
リストコンテキストで呼ばれれば、その文によって返される
最初の行を返します。
C<$statement> パラメータはすでに C<prepare> されている
文ハンドルにすることができます。
その場合、C<prepare> は飛ばされます。

=begin original

If any method fails, and L</RaiseError> is not set, C<selectrow_array>
will return an empty list.

=end original

いずれかのメソッドがエラーとなり、L</RaiseError> が設定されていなければ、
C<selectrow_array> は空のリストを返します。

=begin original

If called in a scalar context for a statement handle that has more
than one column, it is undefined whether the driver will return
the value of the first column or the last. So don't do that.
Also, in a scalar context, an C<undef> is returned if there are no
more rows or if an error occurred. That C<undef> can't be distinguished
from an C<undef> returned because the first field value was NULL.
For these reasons you should exercise some caution if you use
C<selectrow_array> in a scalar context, or just don't do that.

=end original

複数列のある文ハンドルに対してスカラコンテキストで呼び出すと、
ドライバが最初の列を返すか最後の列を返すかは未定義です。
従って、やってはいけません。
また、スカラコンテキストでは、
もう行がないかエラーが発生したならば、C<undef> が返されます。
この C<undef> は最初にフィールドの値が
NULL であったために返された C<undef> と区別することができません。
これらの理由によって、C<selectrow_array> をスカラコンテキストで
呼び出すときには注意するか、単に使わないようにしてください。

=head3 C<selectrow_arrayref>

  $ary_ref = $dbh->selectrow_arrayref($statement);
  $ary_ref = $dbh->selectrow_arrayref($statement, \%attr);
  $ary_ref = $dbh->selectrow_arrayref($statement, \%attr, @bind_values);

=begin original

This utility method combines L</prepare>, L</execute> and
L</fetchrow_arrayref> into a single call. It returns the first row of
data from the statement.  The C<$statement> parameter can be a previously
prepared statement handle, in which case the C<prepare> is skipped.

=end original

このユーティリティメソッドは、L</prepare>、L</execute>、およびL</fetchrow_arrayref>を1回の呼び出しに結合します。
ステートメントからデータの最初の行を返します。
C<$statement>パラメータには、以前に準備されたステートメントハンドルを指定できます。
この場合、C<prepare>はスキップされます。
(TBR)

=begin original

If any method fails, and L</RaiseError> is not set, C<selectrow_array>
will return undef.

=end original

いずれかのメソッドが失敗して、L</RaiseError> がセットされていない場合は、
C<selectrow_array> は undef を返します。

=head3 C<selectrow_hashref>

  $hash_ref = $dbh->selectrow_hashref($statement);
  $hash_ref = $dbh->selectrow_hashref($statement, \%attr);
  $hash_ref = $dbh->selectrow_hashref($statement, \%attr, @bind_values);

=begin original

This utility method combines L</prepare>, L</execute> and
L</fetchrow_hashref> into a single call. It returns the first row of
data from the statement.  The C<$statement> parameter can be a previously
prepared statement handle, in which case the C<prepare> is skipped.

=end original

このユーティリティメソッドは、L</prepare>、L</execute>、およびL</fetchrow_hashref>を1回の呼び出しに結合します。
ステートメントからデータの最初の行を返します。
C<$statement>パラメータには、以前に準備されたステートメントハンドルを指定できます。
この場合、C<prepare>はスキップされます。
(TBR)

=begin original

If any method fails, and L</RaiseError> is not set, C<selectrow_hashref>
will return undef.

=end original

いずれかのメソッドが失敗して、L</RaiseError> がセットされていない場合は、
C<selectrow_hashref> は undef を返します。

=head3 C<selectall_arrayref>

  $ary_ref = $dbh->selectall_arrayref($statement);
  $ary_ref = $dbh->selectall_arrayref($statement, \%attr);
  $ary_ref = $dbh->selectall_arrayref($statement, \%attr, @bind_values);

=begin original

This utility method combines L</prepare>, L</execute> and
L</fetchall_arrayref> into a single call. It returns a reference to an
array containing a reference to an array (or hash, see below) for each row of
data fetched.

=end original

このユーティリティメソッドは、L</prepare>, L</execute>,
L</fetchall_arrayref> を一回にまとめておこないます。
取り出されたデータの各行の配列(またはハッシュ; 後述)へのリファレンスが入った
配列へのリファレンスを返します。

=begin original

The C<$statement> parameter can be a previously prepared statement handle,
in which case the C<prepare> is skipped. This is recommended if the
statement is going to be executed many times.

=end original

C<$statement> パラメータを既に prepare されている文ハンドルに
することができます;
その場合、C<prepare> は飛ばされます。
これは何回も文が実行する予定であればお勧めです。

=begin original

If L</RaiseError> is not set and any method except C<fetchall_arrayref>
fails then C<selectall_arrayref> will return C<undef>; if
C<fetchall_arrayref> fails then it will return with whatever data
has been fetched thus far. You should check C<$sth-E<gt>err>
afterwards (or use the C<RaiseError> attribute) to discover if the data is
complete or was truncated due to an error.

=end original

L</RaiseError>が設定されておらず、C<fetchall_arrayref>以外のメソッドが失敗した場合、C<selectall_arrayref>はC<undef>を返します。
C<fetchall_arrayref>が失敗した場合は、これまでにフェッチされたデータを返します。
後でC<$sth-E<gt>err>をチェックして(またはC<RaiseError>属性を使用して)、データが完全であるか、エラーのために切り捨てられたかを検出する必要があります。
(TBR)

=begin original

The L</fetchall_arrayref> method called by C<selectall_arrayref>
supports a $max_rows parameter. You can specify a value for $max_rows
by including a 'C<MaxRows>' attribute in \%attr. In which case finish()
is called for you after fetchall_arrayref() returns.

=end original

C<selectall_arrayref>によって呼び出されるL</fetchall_arrayref>メソッドは、$max_rowsパラメータをサポートしています。
\%attrに'C<MaxRows>'属性を含めることによって、$max_rowsの値を指定できます。
この場合、fetchall_arrayref()が返された後にfinish()が呼び出されます。
(TBR)

=begin original

The L</fetchall_arrayref> method called by C<selectall_arrayref>
also supports a $slice parameter. You can specify a value for $slice by
including a 'C<Slice>' or 'C<Columns>' attribute in \%attr. The only
difference between the two is that if C<Slice> is not defined and
C<Columns> is an array ref, then the array is assumed to contain column
index values (which count from 1), rather than perl array index values.
In which case the array is copied and each value decremented before
passing to C</fetchall_arrayref>.

=end original

C<selectall_arrayref>によって呼び出されるL</fetchall_arrayref>メソッドも、$sliceパラメータをサポートします。
\%attrに'C<Slice>'または'C<Columns>'属性を含めることによって、$sliceの値を指定できます。
この2つの唯一の違いは、C<Slice>が定義されておらず、C<Columns>が配列参照である場合、配列にはperl配列インデックス値ではなく、(1からカウントされる)列インデックス値が含まれていると見なされることです。
この場合、配列はコピーされ、各値はC</fetchall_arrayref>に渡される前にデクリメントされます。
(TBR)

=begin original

You may often want to fetch an array of rows where each row is stored as a
hash. That can be done simple using:

=end original

各行をハッシュとして保管している行の配列をフェッチしたいことが多いでしょう。
単純に以下のようにしてできます:

  my $emps = $dbh->selectall_arrayref(
      "SELECT ename FROM emp ORDER BY ename",
      { Slice => {} }
  );
  foreach my $emp ( @$emps ) {
      print "Employee: $emp->{ename}\n";
  }

=begin original

Or, to fetch into an array instead of an array ref:

=end original

または、フェッチ内容を配列リファレンスではなく配列に入れるには:

  @result = @{ $dbh->selectall_arrayref($sql, { Slice => {} }) };

=begin original

See L</fetchall_arrayref> method for more details.

=end original

更なる詳細については L</fetchall_arrayref> メソッドを参照してください。

=head3 C<selectall_hashref>

  $hash_ref = $dbh->selectall_hashref($statement, $key_field);
  $hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr);
  $hash_ref = $dbh->selectall_hashref($statement, $key_field, \%attr, @bind_values);

=begin original

This utility method combines L</prepare>, L</execute> and
L</fetchall_hashref> into a single call. It returns a reference to a
hash containing one entry, at most, for each row, as returned by fetchall_hashref().

=end original

このユーティリティメソッドは、L</prepare>、L</execute>、およびL</fetchall_hashref>を1回の呼び出しに結合します。
fetchall_hashref()によって返されるように、各行に対して最大1つのエントリを含むハッシュへの参照を返します。
(TBR)

=begin original

The C<$statement> parameter can be a previously prepared statement handle,
in which case the C<prepare> is skipped.  This is recommended if the
statement is going to be executed many times.

=end original

C<$statement> パラメータを既に prepare されている文ハンドルに
することができます;
その場合、C<prepare> は飛ばされます。
これは何回も文が実行する予定であればお勧めです。

=begin original

The C<$key_field> parameter defines which column, or columns, are used as keys
in the returned hash. It can either be the name of a single field, or a
reference to an array containing multiple field names. Using multiple names
yields a tree of nested hashes.

=end original

C<$key_field>パラメータは、返されるハッシュでキーとして使用される列を定義します。
単一のフィールドの名前、または複数のフィールド名を含む配列への参照を指定できます。
複数の名前を使用すると、ネストされたハッシュのツリーが生成されます。
(TBR)

=begin original

If a row has the same key as an earlier row then it replaces the earlier row.

=end original

行が以前の行と同じキーの場合、以前の行は置き換えられます。

=begin original

If any method except C<fetchrow_hashref> fails, and L</RaiseError> is not set,
C<selectall_hashref> will return C<undef>.  If C<fetchrow_hashref> fails and
L</RaiseError> is not set, then it will return with whatever data it
has fetched thus far. $DBI::err should be checked to catch that.

=end original

C<fetchrow_hashref> 以外のいずれかのメソッドがエラーとなり、
L</RaiseError> が設定されていなければ、C<selectall_hashref> は
C<undef>を返します。
もし C<fetchrow_hashref> が失敗し、L</RaiseError> が設定されていなければ、
それまでに取り出したデータをなるべく多く返します。
それを捕らえるために $DBI::err をチェックすべきです。

=begin original

See fetchall_hashref() for more details.

=end original

さらなる詳細については fetchall_hashref() を参照してください。

=head3 C<selectcol_arrayref>

  $ary_ref = $dbh->selectcol_arrayref($statement);
  $ary_ref = $dbh->selectcol_arrayref($statement, \%attr);
  $ary_ref = $dbh->selectcol_arrayref($statement, \%attr, @bind_values);

=begin original

This utility method combines L</prepare>, L</execute>, and fetching one
column from all the rows, into a single call. It returns a reference to
an array containing the values of the first column from each row.

=end original

このユーティリティーメソッドは、一回に L</prepare>, L</execute> を
まとめておこない、すべての行から一つのカラムからを取り出します。
各行からの最初のカラムの値が入った配列へのリファレンスを返します。

=begin original

The C<$statement> parameter can be a previously prepared statement handle,
in which case the C<prepare> is skipped. This is recommended if the
statement is going to be executed many times.

=end original

C<$statement> パラメータを既に prepare されている文ハンドルに
することができます;
その場合、C<prepare> は飛ばされます。
これは何回も文が実行する予定であればお勧めです。

=begin original

If any method except C<fetch> fails, and L</RaiseError> is not set,
C<selectcol_arrayref> will return C<undef>.  If C<fetch> fails and
L</RaiseError> is not set, then it will return with whatever data it
has fetched thus far. $DBI::err should be checked to catch that.

=end original

C<fetch> 以外のいずれかのメソッドがエラーとなり、L</RaiseError> が
設定されていなければ、C<selectcol_arrayref> は C<undef> を返します。
もし C<fetch> が失敗し、C</RaiseError> が設定されていなければ、それまでに
取り出したデータをなるべく多く返します。
それを捕らえるために $DBI::err をチェックすべきです。

=begin original

The C<selectcol_arrayref> method defaults to pushing a single column
value (the first) from each row into the result array. However, it can
also push another column, or even multiple columns per row, into the
result array. This behaviour can be specified via a 'C<Columns>'
attribute which must be a ref to an array containing the column number
or numbers to use. For example:

=end original

C<selectcol_arrayref>メソッドのデフォルトでは、各行の単一の列値(最初)が結果配列にプッシュされます。
ただし、別の列、または行ごとに複数の列を結果配列にプッシュすることもできます。
この動作は、'C<Columns>'属性を介して指定できます。
この属性は、使用する列番号を含む配列への参照である必要があります。
次に例を示します。
(TBR)

  # get array of id and name pairs:
  my $ary_ref = $dbh->selectcol_arrayref("select id, name from table", { Columns=>[1,2] });
  my %hash = @$ary_ref; # build hash from key-value pairs so $hash{$id} => name

=begin original

You can specify a maximum number of rows to fetch by including a
'C<MaxRows>' attribute in \%attr.

=end original

最大フェッチ行数は \%attr の 'C<MaxRows>' 属性で指定できます。

=head3 C<prepare>

  $sth = $dbh->prepare($statement)          or die $dbh->errstr;
  $sth = $dbh->prepare($statement, \%attr)  or die $dbh->errstr;

=begin original

Prepares a statement for later execution by the database
engine and returns a reference to a statement handle object.

=end original

一つの文を後でデータベースエンジンによって実行できるように準備し、
文ハンドルオブジェクトへのリファレンスを返します。

=begin original

The returned statement handle can be used to get attributes of the
statement and invoke the L</execute> method. See L</Statement Handle Methods>.

=end original

返される文ハンドルは文の属性を取得したり、
L</execute> メソッドの呼び出しに使われます。
L</Statement Handle Methods> をご覧ください。

=begin original

Drivers for engines without the concept of preparing a
statement will typically just store the statement in the returned
handle and process it when C<$sth-E<gt>execute> is called. Such drivers are
unlikely to give much useful information about the
statement, such as C<$sth-E<gt>{NUM_OF_FIELDS}>, until after C<$sth-E<gt>execute>
has been called. Portable applications should take this into account.

=end original

準備された文という考えが無いドライバでは、通常、返される
ハンドルに文を保存し、C<$sth-E<gt>execute> が呼ばれたらそれを
処理します。
そのようなドライバは C<$sth-E<gt>{NUM_OF_FIELDS}> のような
文について有効な情報を C<$sth-E<gt>execute> が呼ばれるまでは、
取得できることはまずありません。 
移植可能なアプリケーションはこの点を注意する必要があります。

=begin original

In general, DBI drivers do not parse the contents of the statement
(other than simply counting any L</Placeholders>). The statement is
passed directly to the database engine, sometimes known as pass-thru
mode. This has advantages and disadvantages. On the plus side, you can
access all the functionality of the engine being used. On the downside,
you're limited if you're using a simple engine, and you need to take extra care if
writing applications intended to be portable between engines.

=end original

通常、DBIドライバは文を解析しません
(そうでなければ単純にプレースホルダを数えます)。
文はデータベース・エンジンに直接渡されます、いわゆるパススルー
モードです。
これは長所でも短所でもあります。
よく言えば、使われているエンジンのすべての機能にアクセスすることができます。
悪く言えば、簡単なエンジンを使っていれば制限されますし、エンジンをまたがって
移植可能なアプリケーションを書こうとすれば、非常に注意する必要があります。

=begin original

Portable applications should not assume that a new statement can be
prepared and/or executed while still fetching results from a previous
statement.

=end original

移植可能なアプリケーションは、まだ前の文から結果を
取り出している間に、新しい文が prepare でき、そして/あるいは
実行できると想定するべきではありません。

=begin original

Some command-line SQL tools use statement terminators, like a semicolon,
to indicate the end of a statement. Such terminators should not normally
be used with the DBI.

=end original

いくつかのコマンドライン型 SQL ツールは、セミコロンなどのステータスの終わりを
示すために、文末尾文字(statement terminator)を使っています。
通常そうした末尾文字を DBI で使われません。

=head3 C<prepare_cached>

  $sth = $dbh->prepare_cached($statement)
  $sth = $dbh->prepare_cached($statement, \%attr)
  $sth = $dbh->prepare_cached($statement, \%attr, $if_active)

=begin original

Like L</prepare> except that the statement handle returned will be
stored in a hash associated with the C<$dbh>. If another call is made to
C<prepare_cached> with the same C<$statement> and C<%attr> parameter values,
then the corresponding cached C<$sth> will be returned without contacting the
database server.

=end original

C<$dbh> に関連付けられたハッシュに保存されることを除いて L</prepare> と
同様です。
もし同じ C<$statement> と C<%attr> パラメータの値ででもう一度
C<prepare_cached> が呼び出されると、データベースサーバに
コンタクトすることなく、対応する C<$sth> が返されます。

=begin original

The C<$if_active> parameter lets you adjust the behaviour if an
already cached statement handle is still Active.  There are several
alternatives:

=end original

C<$if_active>パラメータを使用すると、すでにキャッシュされているステートメントハンドルがまだアクティブである場合の動作を調整できます。
いくつかの選択肢があります。
(TBR)

=over 4

=item B<0>: A warning will be generated, and finish() will be called on
the statement handle before it is returned.  This is the default
behaviour if $if_active is not passed.

=item B<1>: finish() will be called on the statement handle, but the
warning is suppressed.

=item B<2>: Disables any checking.

=item B<3>: The existing active statement handle will be removed from the
cache and a new statement handle prepared and cached in its place.
This is the safest option because it doesn't affect the state of the
old handle, it just removes it from the cache. [Added in DBI 1.40]

=back

=begin original

Here are some examples of C<prepare_cached>:

=end original

以下は C<prepare_cached> の例です:

  sub insert_hash {
    my ($table, $field_values) = @_;
    # sort to keep field order, and thus sql, stable for prepare_cached
    my @fields = sort keys %$field_values;
    my @values = @{$field_values}{@fields};
    my $sql = sprintf "insert into %s (%s) values (%s)",
	$table, join(",", @fields), join(",", ("?")x@fields);
    my $sth = $dbh->prepare_cached($sql);
    return $sth->execute(@values);
  }

  sub search_hash {
    my ($table, $field_values) = @_;
    # sort to keep field order, and thus sql, stable for prepare_cached
    my @fields = sort keys %$field_values;
    my @values = @{$field_values}{@fields};
    my $qualifier = "";
    $qualifier = "where ".join(" and ", map { "$_=?" } @fields) if @fields;
    $sth = $dbh->prepare_cached("SELECT * FROM $table $qualifier");
    return $dbh->selectall_arrayref($sth, {}, @values);
  }

=begin original

I<Caveat emptor:> This caching can be useful in some applications,
but it can also cause problems and should be used with care. Here
is a contrived case where caching would cause a significant problem:

=end original

I<Caveat emptor:>このキャッシュは、一部のアプリケーションでは便利ですが、問題を引き起こす可能性があるため、注意して使用する必要があります。
キャッシュが重大な問題を引き起こす場合を考えてみましょう。
(TBR)

  my $sth = $dbh->prepare_cached('SELECT * FROM foo WHERE bar=?');
  $sth->execute(...);
  while (my $data = $sth->fetchrow_hashref) {

    # later, in some other code called within the loop...
    my $sth2 = $dbh->prepare_cached('SELECT * FROM foo WHERE bar=?');
    $sth2->execute(...);
    while (my $data2 = $sth2->fetchrow_arrayref) {
      do_stuff(...);
    }
  }

=begin original

In this example, since both handles are preparing the exact same statement,
C<$sth2> will not be its own statement handle, but a duplicate of C<$sth>
returned from the cache. The results will certainly not be what you expect.
Typically the inner fetch loop will work normally, fetching all
the records and terminating when there are no more, but now that $sth
is the same as $sth2 the outer fetch loop will also terminate.

=end original

この例では、両方のハンドルがまったく同じステートメントを準備しているため、C<$sth2>はそれ自体のステートメントハンドルではなく、キャッシュから返されたC<$sth>の複製になります。
結果は期待したものではありません。
通常、内側のフェッチループは正常に動作し、すべてのレコードをフェッチし、それ以上レコードがないときに終了しますが、$sthが$sth2と同じになったので、外側のフェッチループも終了します。
(TBR)

=begin original

You'll know if you run into this problem because prepare_cached()
will generate a warning by default (when $if_active is false).

=end original

prepare_cached()はデフォルトで($if_activeがfalseの場合)警告を生成するので、この問題が発生した場合はすぐにわかります。
(TBR)

=begin original

The cache used by prepare_cached() is keyed by both the statement
and any attributes so you can also avoid this issue by doing something
like:

=end original

prepare_cached()で使用されるキャッシュは、文と属性の両方によってキー設定されるため、次のようにしてこの問題を回避することもできます。
(TBR)

  $sth = $dbh->prepare_cached("...", { dbi_dummy => __FILE__.__LINE__ });

=begin original

which will ensure that prepare_cached only returns statements cached
by that line of code in that source file.

=end original

これにより、prepare_cachedは、そのソースファイル内のそのコード行によってキャッシュされたステートメントのみを返すようになります。
(TBR)

=begin original

If you'd like the cache to managed intelligently, you can tie the
hashref returned by C<CachedKids> to an appropriate caching module,
such as L<Tie::Cache::LRU>:

=end original

キャッシュをインテリジェントに管理したい場合は、C<CachedKids>によって返されるhashrefを、L<Tie::Cache::LRU>のような適切なキャッシュモジュールに結び付けることができます。
(TBR)

  my $cache;
  tie %$cache, 'Tie::Cache::LRU', 500;
  $dbh->{CachedKids} = $cache;

=head3 C<commit>

  $rc  = $dbh->commit     or die $dbh->errstr;

=begin original

Commit (make permanent) the most recent series of database changes
if the database supports transactions and AutoCommit is off.

=end original

データベースがトランザクションをサポートしていて AutoCommit がオフであれば、
データベースに対する直近の一連の変更をコミット(永続化)します。

=begin original

If C<AutoCommit> is on, then calling
C<commit> will issue a "commit ineffective with AutoCommit" warning.

=end original

C<AutoCommit> がオンであれば、C<commit> は
"commit ineffective with AutoCommit" という警告を起こします。

=begin original

See also L</Transactions> in the L</FURTHER INFORMATION> section below.

=end original

後述する L</FURTHER INFORMATION> 章の L</Transactions> も参照してください。

=head3 C<rollback>

  $rc  = $dbh->rollback   or die $dbh->errstr;

=begin original

Rollback (undo) the most recent series of uncommitted database
changes if the database supports transactions and AutoCommit is off.

=end original

データベースがトランザクションをサポートしていて、AutoCommit がオフであれば、
データベースに対する直近の一連の変更をロールバックします(元に戻します)。

=begin original

If C<AutoCommit> is on, then calling
C<rollback> will issue a "rollback ineffective with AutoCommit" warning.

=end original

C<AutoCommit> がオンであれば、C<rollback> は
"rollback ineffective with AutoCommit" という警告を起こします。

=begin original

See also L</Transactions> in the L</FURTHER INFORMATION> section below.

=end original

後述する L</FURTHER INFORMATION> 章の L</Transactions> も参照してください。

=head3 C<begin_work>

  $rc  = $dbh->begin_work   or die $dbh->errstr;

=begin original

Enable transactions (by turning C<AutoCommit> off) until the next call
to C<commit> or C<rollback>. After the next C<commit> or C<rollback>,
C<AutoCommit> will automatically be turned on again.

=end original

次にC<commit>またはC<rollback>を呼び出すまで、(C<AutoCommit>をオフにして)トランザクションを有効にします。
次のC<commit>またはC<rollback>の後、C<AutoCommit>は自動的に再びオンになります。
(TBR)

=begin original

If C<AutoCommit> is already off when C<begin_work> is called then
it does nothing except return an error. If the driver does not support
transactions then when C<begin_work> attempts to set C<AutoCommit> off
the driver will trigger a fatal error.

=end original

C<begin_work>が呼び出されたときにC<AutoCommit>がすでにオフになっている場合は、エラーを返す以外は何もしません。
ドライバがトランザクションをサポートしていない場合、C<begin_work>がC<AutoCommit>をオフに設定しようとすると、ドライバは致命的なエラーをトリガします。
(TBR)

=begin original

See also L</Transactions> in the L</FURTHER INFORMATION> section below.

=end original

後述する L</FURTHER INFORMATION> 章の L</Transactions> も参照してください。

=head3 C<disconnect>

  $rc = $dbh->disconnect  or warn $dbh->errstr;

=begin original

Disconnects the database from the database handle. C<disconnect> is typically only used
before exiting the program. The handle is of little use after disconnecting.

=end original

データベースハンドルをデータベースから切断します。
C<disconnect> は普通プログラムを終了するときにだけ使います。
切断した後、ハンドルほとんど役に立ちません。

=begin original

The transaction behaviour of the C<disconnect> method is, sadly,
undefined.  Some database systems (such as Oracle and Ingres) will
automatically commit any outstanding changes, but others (such as
Informix) will rollback any outstanding changes.  Applications not
using C<AutoCommit> should explicitly call C<commit> or C<rollback> before
calling C<disconnect>.

=end original

残念ながら C<disconnect> メソッドにより、トランザクションがどうなるかは
決まっていません。
ある種のデータベースシステム(Oracle、Ingressなど)は自動的に変更を
コミットしますが、(Infromixなど)変更をロールバックするものもあります。
C<AutoCommit> を使わないアプリケーションは C<disconnect> を呼び出す前に、
明確に C<commit> または C<rollback> を呼び出すべきです。

=begin original

The database is automatically disconnected by the C<DESTROY> method if
still connected when there are no longer any references to the handle.
The C<DESTROY> method for each driver should implicitly call C<rollback> to
undo any uncommitted changes. This is vital behaviour to ensure that
incomplete transactions don't get committed simply because Perl calls
C<DESTROY> on every object before exiting. Also, do not rely on the order
of object destruction during "global destruction", as it is undefined.

=end original

まだ接続していて、ハンドルへの参照がまったくなくなった場合、
C<DESTROY> メソッドによりデータベースは自動的に切断されます。
各ドライバへの C<DESTROY> メソッドはコミットされていない変更を元に戻すため、
暗黙のうちに C<rollback> を呼び出します。
これは終了する前に Perl が単に各オブジェクトに C<DESTROY> を
呼び出すことによって、不完全なトランザクションがコミットされないということを
保証するためにきわめて重要です。
同様に「グローバルな破壊」でのオブジェクトの破壊の順序は信頼できません;
これは未定義です。

=begin original

Generally, if you want your changes to be committed or rolled back when
you disconnect, then you should explicitly call L</commit> or L</rollback>
before disconnecting.

=end original

一般的に、切断する前に変更をコミットまたはロールバックしたいのであれば、
切断する前に明示的に L</commit> または L</rollback> を呼び出すべきです。

=begin original

If you disconnect from a database while you still have active
statement handles (e.g., SELECT statement handles that may have
more data to fetch), you will get a warning. The warning may indicate
that a fetch loop terminated early, perhaps due to an uncaught error.
To avoid the warning call the C<finish> method on the active handles.

=end original

Active な文ハンドル(つまり、まだフェッチするデータがある SELECT 文
ハンドル)があるのにデータベースから切断すると警告を受けます。
警告はフェッチループが早く終わってしまったことを示していて、おそらくは
捕捉していないエラーによるものです。
警告を避けるには、アクティブハンドルに対して C<finish> メソッドを
呼び出します。

=head3 C<ping>

  $rc = $dbh->ping;

=begin original

Attempts to determine, in a reasonably efficient way, if the database
server is still running and the connection to it is still working.
Individual drivers should implement this function in the most suitable
manner for their database engine.

=end original

合理的で効率的な方法で、データベースサーバーが稼動しているか、接続が
動いているかを判定しようとします。各ドライバはこの関数をそれぞれの
データベースに最も適切な方法で実装するべきです。

=begin original

The current I<default> implementation always returns true without
actually doing anything. Actually, it returns "C<0 but true>" which is
true but zero. That way you can tell if the return value is genuine or
just the default. Drivers should override this method with one that
does the right thing for their type of database.

=end original

現在の I<デフォルトの> 実装は、実際には何もせず常に真を返します。
実際には、それは「C<0 だが真>」を返します; これは真ですが 0 です。
これにより返された値が本物なのか単なるデフォルトなのかがわかります。
ドライバはこのメソッドをデータベースのタイプにあったものでこのメソッドを
上書きしなければなりません。

=begin original

Few applications would have direct use for this method. See the specialized
Apache::DBI module for one example usage.

=end original

アプリケーションでこのメソッドを使うことはあまりないでしょう。
使用例としては専門的な Apache::DBI モジュールをご覧ください。

=head3 C<get_info>

  $value = $dbh->get_info( $info_type );

=begin original

Returns information about the implementation, i.e. driver and data
source capabilities, restrictions etc. It returns C<undef> for
unknown or unimplemented information types. For example:

=end original

実装に関する情報(ドライバおよびデータソースの機能、制限など)を戻します。
不明または実装されていない情報タイプの場合は、C<undef>を戻します。
次に例を示します。
(TBR)

  $database_version  = $dbh->get_info(  18 ); # SQL_DBMS_VER
  $max_select_tables = $dbh->get_info( 106 ); # SQL_MAXIMUM_TABLES_IN_SELECT

=begin original

See L</"Standards Reference Information"> for more detailed information
about the information types and their meanings and possible return values.

=end original

情報型とその意味およびあり得る返り値に関するさらに詳しい情報については
L</"Standards Reference Information"> を参照してください。

=begin original

The DBI::Const::GetInfoType module exports a %GetInfoType hash that
can be used to map info type names to numbers. For example:

=end original

DBI::Const::GetInfoType モジュールは、型名を数値にマッピングするために
使える %GetInfoType ハッシュをエクスポートします。
例えば:

  $database_version = $dbh->get_info( $GetInfoType{SQL_DBMS_VER} );

=begin original

The names are a merging of the ANSI and ODBC standards (which differ
in some cases). See L<DBI::Const::GetInfoType> for more details.

=end original

名前は ANSI と ODBC の標準 (一部で異なります) をマージしたものです。
さらなる詳細については L<DBI::Const::GetInfoType> を参照してください。

=begin original

Because some DBI methods make use of get_info(), drivers are strongly
encouraged to support I<at least> the following very minimal set
of information types to ensure the DBI itself works properly:

=end original

DBIメソッドの中にはget_info()を利用するものがあるので、DBI自体が正しく動作するように、ドライバは<少なくとも>以下の最小限の情報タイプをサポートすることを強く推奨します。
(TBR)

 Type  Name                        Example A     Example B
 ----  --------------------------  ------------  ----------------
   17  SQL_DBMS_NAME               'ACCESS'      'Oracle'
   18  SQL_DBMS_VER                '03.50.0000'  '08.01.0721 ...'
   29  SQL_IDENTIFIER_QUOTE_CHAR   '`'           '"'
   41  SQL_CATALOG_NAME_SEPARATOR  '.'           '@'
  114  SQL_CATALOG_LOCATION        1             2

=head3 C<table_info>

  $sth = $dbh->table_info( $catalog, $schema, $table, $type );
  $sth = $dbh->table_info( $catalog, $schema, $table, $type, \%attr );

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

=begin original

Returns an active statement handle that can be used to fetch
information about tables and views that exist in the database.

=end original

データベースに存在するテーブルやビューの情報を取得するために使われる
Active な文・ハンドルを返します。

=begin original

The arguments $catalog, $schema and $table may accept search patterns
according to the database/driver, for example: $table = '%FOO%';
Remember that the underscore character ('C<_>') is a search pattern
that means match any character, so 'FOO_%' is the same as 'FOO%'
and 'FOO_BAR%' will match names like 'FOO1BAR'.

=end original

引数 $catalog, $schema, $table はデータベース／ドライバによって検索
パターンを受け取るかもしれません。
例えば: $table = '%FOO%';
下線文字 ('C<_>') は任意の文字を意味する検索パターンを意味するので、
'FOO_%' は 'FOO%' と同じで、'FOO_BAR%' は 'FOO1BAR' のような名前に
マッチングするということに注意してください。

=begin original

The value of $type is a comma-separated list of one or more types of
tables to be returned in the result set. Each value may optionally be
quoted, e.g.:

=end original

$type の値は結果セットで返されるーブルの一つまたは複数のデータ型のカンマ
区切りのリストです。
それぞれの値はオプションでクォートされるかもしれません; 例えば:

  $type = "TABLE";
  $type = "'TABLE','VIEW'";

=begin original

In addition the following special cases may also be supported by some drivers:

=end original

さらにドライバによっては以下の特殊なケースもサポートされているかもしれません。

=over 4

=item *
If the value of $catalog is '%' and $schema and $table name
are empty strings, the result set contains a list of catalog names.
For example:

  $sth = $dbh->table_info('%', '', '');

=item *
If the value of $schema is '%' and $catalog and $table are empty
strings, the result set contains a list of schema names.

=item *
If the value of $type is '%' and $catalog, $schema, and $table are all
empty strings, the result set contains a list of table types.

=back

=begin original

If your driver doesn't support one or more of the selection filter
parameters then you may get back more than you asked for and can
do the filtering yourself.

=end original

お使いのドライバが1つまたは複数の選択フィルタパラメータをサポートしていない場合は、要求したよりも多くのパラメータが返される可能性があり、自分でフィルタリングを行うことができます。
(TBR)

=begin original

This method can be expensive, and can return a large amount of data.
(For example, small Oracle installation returns over 2000 rows.)
So it's a good idea to use the filters to limit the data as much as possible.

=end original

このメソッドはコストがかかり、大量のデータを戻す可能性があります(たとえば、小規模なOracleインストールでは、2000行を超える行が戻されます)。
そのため、フィルタを使用してデータを可能な限り制限することをお薦めします。
(TBR)

=begin original

The statement handle returned has at least the following fields in the
order show below. Other fields, after these, may also be present.

=end original

返された行ハンドルは少なくとも後述する順序で以下のフィールドを持ちます。
これらの後に、他のフィールドもあるかもしれません。

=begin original

B<TABLE_CAT>: Table catalog identifier. This field is NULL (C<undef>) if not
applicable to the data source, which is usually the case. This field
is empty if not applicable to the table.

=end original

B<TABLE_CAT>: テーブルカタログ識別子。
よくあることですが、データソースに適用できなければ、このフィールドが
NULL(C<undef>)です。
テーブルに適用できなければ、このフィールドは空です。

=begin original

B<TABLE_SCHEM>: The name of the schema containing the TABLE_NAME value.
This field is NULL (C<undef>) if not applicable to data source, and
empty if not applicable to the table.

=end original

B<TABLE_SCHEM>: TABLE_NAME値が入っているスキーマの名前です。
データソースに適用できなければ、このフィールドがNULL(C<undef>)です。
テーブルに適用できなければ、このフィールドは空です。

=begin original

B<TABLE_NAME>: Name of the table (or view, synonym, etc).

=end original

B<TABLE_NAME>: テーブル(またはビュー、シノニムなど)の名前。

=begin original

B<TABLE_TYPE>: One of the following: "TABLE", "VIEW", "SYSTEM TABLE",
"GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM" or a type
identifier that is specific to the data
source.

=end original

B<TABLE_TYPE>: TABLE", "VIEW", "SYSTEM TABLE",
"GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM" または
そのデータソース独自の型識別子のいずれか。

=begin original

B<REMARKS>: A description of the table. May be NULL (C<undef>).

=end original

B<REMARKS>: テーブルの説明。NULL(C<undef>)かもしれません。

=begin original

Note that C<table_info> might not return records for all tables.
Applications can use any valid table regardless of whether it's
returned by C<table_info>.

=end original

C<table_info> がすべてのテーブルについてレコードを返さないかもしれないことに
注意してください。
C<table_info> により返されたかどうかに関係無く、アプリケーションではすべての
適正なテーブルを扱うことができます。

=begin original

See also L</tables>, L</"Catalog Methods"> and
L</"Standards Reference Information">.

=end original

L</tables>, L</"Catalog Methods">, L</"Standards Reference Information"> も
参照してください。

=head3 C<column_info>

  $sth = $dbh->column_info( $catalog, $schema, $table, $column );

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

=begin original

Returns an active statement handle that can be used to fetch
information about columns in specified tables.

=end original

指定された表の行について情報を得るために使える有効な文ハンドルを返します。

=begin original

The arguments $schema, $table and $column may accept search patterns
according to the database/driver, for example: $table = '%FOO%';

=end original

引数 $schema, $table, $column はデータベース/ドライバによる検索パターンを
受け付けます; 例えば: $table = '%FOO%';

=begin original

Note: The support for the selection criteria is driver specific. If the
driver doesn't support one or more of them then you may get back more
than you asked for and can do the filtering yourself.

=end original

注意:選択基準のサポートはドライバ固有です。
ドライバが1つ以上の選択基準をサポートしていない場合は、要求したよりも多くの選択基準が返される可能性があり、自分でフィルタリングを行うことができます。
(TBR)

=begin original

Note: If your driver does not support column_info an undef is
returned.  This is distinct from asking for something which does not
exist in a driver which supports column_info as a valid statement
handle to an empty result-set will be returned in this case.

=end original

注意:ドライバがcolumn_infoをサポートしていない場合は、undefが返されます。
これは、column_infoをサポートするドライバに存在しないものを要求することとは異なります。
この場合、空の結果セットへの有効なステートメントハンドルが返されます。
(TBR)

=begin original

If the arguments don't match any tables then you'll still get a statement
handle, it'll just return no rows.

=end original

引数がどの表にもマッチングしない場合、単に何の行も返さない
文ハンドルが得られます。

=begin original

The statement handle returned has at least the following fields in the
order shown below. Other fields, after these, may also be present.

=end original

返された行ハンドルは少なくとも後述する順序で以下のフィールドを持ちます。
これらの後に、他のフィールドもあるかもしれません。

=begin original

B<TABLE_CAT>: The catalog identifier.
This field is NULL (C<undef>) if not applicable to the data source,
which is often the case.  This field is empty if not applicable to the
table.

=end original

B<TABLE_CAT>: カタログ識別子。
よくあることですが、データソースに適用できなければ、このフィールドが
NULL(C<undef>)です。
テーブルに適用できなければ、このフィールドは空です。

=begin original

B<TABLE_SCHEM>: The schema identifier.
This field is NULL (C<undef>) if not applicable to the data source,
and empty if not applicable to the table.

=end original

B<TABLE_SCHEM>: スキーマ識別子。
データソースに適用できなければ、このフィールドがNULL(C<undef>)です。
テーブルに適用できなければ、このフィールドは空です。

=begin original

B<TABLE_NAME>: The table identifier.
Note: A driver may provide column metadata not only for base tables, but
also for derived objects like SYNONYMS etc.

=end original

B<TABLE_NAME>:表の識別子。
注意:ドライバは、実表の列メタデータのみでなく、SYNONYMSなどの導出オブジェクトの列メタデータも提供できます。
(TBR)

=begin original

B<COLUMN_NAME>: The column identifier.

=end original

B<COLUMN_NAME>: 列識別子。

=begin original

B<DATA_TYPE>: The concise data type code.

=end original

B<DATA_TYPE>: 簡潔なデータ型コード。

=begin original

B<TYPE_NAME>: A data source dependent data type name.

=end original

B<TYPE_NAME>: データソース依存のデータ型名。

=begin original

B<COLUMN_SIZE>: The column size.
This is the maximum length in characters for character data types,
the number of digits or bits for numeric data types or the length
in the representation of temporal types.
See the relevant specifications for detailed information.

=end original

B<COLUMN_SIZE>:列のサイズ。
これは、文字データ型の場合は最大文字数、数値データ型の場合は桁数またはビット数、一時データ型の場合は長さです。
詳細は、関連する仕様を参照してください。
(TBR)

=begin original

B<BUFFER_LENGTH>: The length in bytes of transferred data.

=end original

B<BUFFER_LENGTH>: 転送されたデータのバイト数。

=begin original

B<DECIMAL_DIGITS>: The total number of significant digits to the right of
the decimal point.

=end original

B<DECIMAL_DIGITS>: 小数点の右側の有効桁数。

=begin original

B<NUM_PREC_RADIX>: The radix for numeric precision.
The value is 10 or 2 for numeric data types and NULL (C<undef>) if not
applicable.

=end original

B<NUM_PREC_RADIX>:数値精度の基数。
数値データ型の場合、値は10または2です。
該当しない場合は、NULL(C<undef>)です。
(TBR)

=begin original

B<NULLABLE>: Indicates if a column can accept NULLs.
The following values are defined:

=end original

B<NULLABLE>: 列が NULL を受け付けるかを示す。
以下の値が定義されています:

  SQL_NO_NULLS          0
  SQL_NULLABLE          1
  SQL_NULLABLE_UNKNOWN  2

=begin original

B<REMARKS>: A description of the column.

=end original

B<REMARKS>: 列の説明。

=begin original

B<COLUMN_DEF>: The default value of the column, in a format that can be used
directly in an SQL statement.

=end original

B<COLUMN_DEF>: SQL に直接使える形での、列のデフォルト値。

=begin original

Note that this may be an expression and not simply the text used for the
default value in the original CREATE TABLE statement. For example, given:

=end original

これは式になって、元の CREATE TABLE 文のデフォルトとして使われた単純な
テキストではないかもしれないことに注意してください。
例えば、以下のようにすると:

    col1 char(30) default current_user    -- a 'function'
    col2 char(30) default 'string'        -- a string literal

=begin original

where "current_user" is the name of a function, the corresponding C<COLUMN_DEF>
values would be:

=end original

ここで "current_user" が関数名とすると、対応する C<COLUMN_DEF> の値は
以下のようになります:

    Database        col1                     col2
    --------        ----                     ----
    Oracle:         current_user             'string'
    Postgres:       "current_user"()         'string'::text
    MS SQL:         (user_name())            ('string')

=begin original

B<SQL_DATA_TYPE>: The SQL data type.

=end original

B<SQL_DATA_TYPE>: SQL データ型。

=begin original

B<SQL_DATETIME_SUB>: The subtype code for datetime and interval data types.

=end original

B<SQL_DATETIME_SUB>: 日付時刻と内部データ型のためのサブ型コード。

=begin original

B<CHAR_OCTET_LENGTH>: The maximum length in bytes of a character or binary
data type column.

=end original

B<CHAR_OCTET_LENGTH>: 文字やバイナリデータ型列の最大バイト長。

=begin original

B<ORDINAL_POSITION>: The column sequence number (starting with 1).

=end original

B<ORDINAL_POSITION>: 列シーケンス番号 (1 から開始)。

=begin original

B<IS_NULLABLE>: Indicates if the column can accept NULLs.
Possible values are: 'NO', 'YES' and ''.

=end original

B<IS_NULLABLE>: 列が NULL を受け付けるかを示す。
取り得る値は: 'NO', 'YES', ''.

=begin original

SQL/CLI defines the following additional columns:

=end original

SQL/CLI は以下の追加の列を定義しています:

  CHAR_SET_CAT
  CHAR_SET_SCHEM
  CHAR_SET_NAME
  COLLATION_CAT
  COLLATION_SCHEM
  COLLATION_NAME
  UDT_CAT
  UDT_SCHEM
  UDT_NAME
  DOMAIN_CAT
  DOMAIN_SCHEM
  DOMAIN_NAME
  SCOPE_CAT
  SCOPE_SCHEM
  SCOPE_NAME
  MAX_CARDINALITY
  DTD_IDENTIFIER
  IS_SELF_REF

=begin original

Drivers capable of supplying any of those values should do so in
the corresponding column and supply undef values for the others.

=end original

これらの値のいずれかを提供できるドライバは、対応する列で提供し、他の値にはundef値を提供する必要があります。
(TBR)

=begin original

Drivers wishing to provide extra database/driver specific information
should do so in extra columns beyond all those listed above, and
use lowercase field names with the driver-specific prefix (i.e.,
'ora_...'). Applications accessing such fields should do so by name
and not by column number.

=end original

追加のデータベース/ドライバ固有の情報を提供したいドライバは、上記のすべての列に加えて追加の列を提供する必要があります。
また、ドライバ固有の接頭辞('ora_...')を付けた小文字のフィールド名を使用する必要があります。
このようなフィールドにアクセスするアプリケーションは、列番号ではなく名前で提供する必要があります。
(TBR)

=begin original

The result set is ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME
and ORDINAL_POSITION.

=end original

結果セットは TABLE_CAT, TABLE_SCHEM, TABLE_NAME, ORDINAL_POSITION で
ソートされます。

=begin original

Note: There is some overlap with statement handle attributes (in perl) and
SQLDescribeCol (in ODBC). However, SQLColumns provides more metadata.

=end original

注意: (perl での)文ハンドル属性と (ODBC での) SQLDescribeCol には
重複があります。
しかし、SQLDescribeCol はさらなるメタデータを提供します。

=begin original

See also L</"Catalog Methods"> and L</"Standards Reference Information">.

=end original

L</"Catalog Methods"> と L</"Standards Reference Information"> も
参照してください。

=head3 C<primary_key_info>

  $sth = $dbh->primary_key_info( $catalog, $schema, $table );

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

=begin original

Returns an active statement handle that can be used to fetch information
about columns that make up the primary key for a table.
The arguments don't accept search patterns (unlike table_info()).

=end original

テーブルのための主キーとして設定されているカラムについての情報を
取り出すために使われる Active な文・ハンドルを返します。
引数に検索パターンは受け取りません(table_info()とは違って)。

=begin original

The statement handle will return one row per column, ordered by
TABLE_CAT, TABLE_SCHEM, TABLE_NAME, and KEY_SEQ.
If there is no primary key then the statement handle will fetch no rows.

=end original

ステートメントハンドルは、TABLE_CAT、TABLE_SCHEMA、TABLE_NAMEおよびKEY_SEQの順序で、列ごとに1行を戻します。
プライマリキーがない場合、ステートメントハンドルは行をフェッチしません。
(TBR)

=begin original

Note: The support for the selection criteria, such as $catalog, is
driver specific.  If the driver doesn't support catalogs and/or
schemas, it may ignore these criteria.

=end original

注意:$catalog のような、選択条件のサポートはドライバによります。
もしドライバがカタログやスキーマをサポートしていなければ、これらの条件は
無視されるかもしれません。

=begin original

The statement handle returned has at least the following fields in the
order shown below. Other fields, after these, may also be present.

=end original

返された行ハンドルは少なくとも後述する順序で以下のフィールドを持ちます。
これらの後に、他のフィールドもあるかもしれません。

=begin original

B<TABLE_CAT>: The catalog identifier.
This field is NULL (C<undef>) if not applicable to the data source,
which is often the case.  This field is empty if not applicable to the
table.

=end original

B<TABLE_CAT>: カタログ識別子。
よくあることですが、データソースに適用できなければ、このフィールドが
NULL(C<undef>)です。
テーブルに適用できなければ、このフィールドは空です。

=begin original

B<TABLE_SCHEM>: The schema identifier.
This field is NULL (C<undef>) if not applicable to the data source,
and empty if not applicable to the table.

=end original

B<TABLE_SCHEM>: スキーマ識別子。
データソースに適用できなければ、このフィールドがNULL(C<undef>)です。
テーブルに適用できなければ、このフィールドは空です。

=begin original

B<TABLE_NAME>: The table identifier.

=end original

B<TABLE_NAME>: テーブル識別子。

=begin original

B<COLUMN_NAME>: The column identifier.

=end original

B<COLUMN_NAME>: 列識別子。

=begin original

B<KEY_SEQ>: The column sequence number (starting with 1).
Note: This field is named B<ORDINAL_POSITION> in SQL/CLI.

=end original

B<KEY_SEQ>: カラム順序番号(１始まり)。
注意:SQL/CLI ではこのフィールドは B<ORDINAL_POSITION> と名づけられています。

=begin original

B<PK_NAME>: The primary key constraint identifier.
This field is NULL (C<undef>) if not applicable to the data source.

=end original

B<PK_NAME>: 主キー制約識別子。
データソースに適用できなければ NULL(C<undef>) です。

=begin original

See also L</"Catalog Methods"> and L</"Standards Reference Information">.

=end original

L</"Catalog Methods"> と L</"Standards Reference Information"> も
参照してください。

=head3 C<primary_key>

  @key_column_names = $dbh->primary_key( $catalog, $schema, $table );

=begin original

Simple interface to the primary_key_info() method. Returns a list of
the column names that comprise the primary key of the specified table.
The list is in primary key column sequence order.
If there is no primary key then an empty list is returned.

=end original

primary_key_info() メソッドへの単純なインターフェースです。
指定されたテーブルの主キーを含むカラム目のリストを返します。
このリストは主キーカラム順番号順に入ります。
主キーがない場合、空リストが返されます。

=head3 C<foreign_key_info>

  $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table
                               , $fk_catalog, $fk_schema, $fk_table );

  $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table
                               , $fk_catalog, $fk_schema, $fk_table
                               , \%attr );

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

=begin original

Returns an active statement handle that can be used to fetch information
about foreign keys in and/or referencing the specified table(s).
The arguments don't accept search patterns (unlike table_info()).

=end original

指定されたテーブル内の外部キーに関する情報を取得したり、指定されたテーブルを参照するために使用できる、アクティブなステートメントハンドルを返します。
この引数は検索パターンを受け付けません(table_info()と異なります)。
(TBR)

=begin original

C<$pk_catalog>, C<$pk_schema>, C<$pk_table>
identify the primary (unique) key table (B<PKT>).

=end original

C<$pk_catalog>, C<$pk_schema>, C<$pk_table> は主(ユニーク)キー表
(B<PKT>) を識別します。

=begin original

C<$fk_catalog>, C<$fk_schema>, C<$fk_table>
identify the foreign key table (B<FKT>).

=end original

C<$fk_catalog>, C<$fk_schema>, C<$fk_table> は外部キー表 (B<FKT>) を
識別します。

=begin original

If both B<PKT> and B<FKT> are given, the function returns the foreign key, if
any, in table B<FKT> that refers to the primary (unique) key of table B<PKT>.
(Note: In SQL/CLI, the result is implementation-defined.)

=end original

B<PKT>とB<FKT>の両方が指定された場合、テーブルB<PKT>のプライマリ(一意の)キーを参照する外部キーがテーブルB<FKT>に存在する場合、この関数は外部キーを返します。
(注:SQL/CLIでは、結果は実装によって定義されます。
)
(TBR)

=begin original

If only B<PKT> is given, then the result set contains the primary key
of that table and all foreign keys that refer to it.

=end original

B<PKT> のみが指定されると、結果セットにはその表の主キーと、それを
参照している全ての外部キーが含まれます。

=begin original

If only B<FKT> is given, then the result set contains all foreign keys
in that table and the primary keys to which they refer.
(Note: In SQL/CLI, the result includes unique keys too.)

=end original

B<FKT>のみが指定された場合、結果セットには、そのテーブル内のすべての外部キーと、それらが参照するプライマリキーが含まれます(注:SQL/CLIでは、結果にはユニークキーも含まれます)。
(TBR)

=begin original

For example:

=end original

例えば:

  $sth = $dbh->foreign_key_info( undef, $user, 'master');
  $sth = $dbh->foreign_key_info( undef, undef,   undef , undef, $user, 'detail');
  $sth = $dbh->foreign_key_info( undef, $user, 'master', undef, $user, 'detail');

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

=begin original

Note: The support for the selection criteria, such as C<$catalog>, is
driver specific.  If the driver doesn't support catalogs and/or
schemas, it may ignore these criteria.

=end original

注意:C<$catalog>などの選択基準のサポートはドライバ固有です。
ドライバがカタログやスキーマをサポートしていない場合は、これらの基準が無視される可能性があります。
(TBR)

=begin original

The statement handle returned has the following fields in the order shown below.
Because ODBC never includes unique keys, they define different columns in the
result set than SQL/CLI. SQL/CLI column names are shown in parentheses.

=end original

戻されたステートメントハンドルには、次に示す順序で次のフィールドがあります。
ODBCには一意のキーが含まれないため、結果セットにはSQL/CLIとは異なる列が定義されます。
SQL/CLIの列名はカッコ内に表示されます。
(TBR)

=begin original

B<PKTABLE_CAT    ( UK_TABLE_CAT      )>:
The primary (unique) key table catalog identifier.
This field is NULL (C<undef>) if not applicable to the data source,
which is often the case.  This field is empty if not applicable to the
table.

=end original

B<PKTABLE_CAT ( UK_TABLE_CAT )>:主(一意の)キーテーブルカタログ識別子。
このフィールドは、データソースに適用されない場合はNULL(C<undef>)です。
このフィールドは、テーブルに適用されない場合は空です。
(TBR)

=begin original

B<PKTABLE_SCHEM  ( UK_TABLE_SCHEM    )>:
The primary (unique) key table schema identifier.
This field is NULL (C<undef>) if not applicable to the data source,
and empty if not applicable to the table.

=end original

B<PKTABLE_SCHEMA(UK_TABLE_SCHEMA)>:主(一意の)キーテーブルスキーマ識別子。
このフィールドは、データソースに適用できない場合はNULL(C<undef>)、テーブルに適用できない場合は空です。
(TBR)

=begin original

B<PKTABLE_NAME   ( UK_TABLE_NAME     )>:
The primary (unique) key table identifier.

=end original

B<PKTABLE_NAME   ( UK_TABLE_NAME     )>:
主(ユニーク)キー表識別子。

=begin original

B<PKCOLUMN_NAME  (UK_COLUMN_NAME    )>:
The primary (unique) key column identifier.

=end original

B<PKCOLUMN_NAME  (UK_COLUMN_NAME    )>:
主(ユニーク)キー列識別子。

=begin original

B<FKTABLE_CAT    ( FK_TABLE_CAT      )>:
The foreign key table catalog identifier.
This field is NULL (C<undef>) if not applicable to the data source,
which is often the case.  This field is empty if not applicable to the
table.

=end original

B<FKTABLE_CAT ( FK_TABLE_CAT )>:外部キーテーブルカタログ識別子。
このフィールドは、データソースに適用できない場合はNULL(C<undef>)です。
このフィールドは、テーブルに適用できない場合は空です。
(TBR)

=begin original

B<FKTABLE_SCHEM  ( FK_TABLE_SCHEM    )>:
The foreign key table schema identifier.
This field is NULL (C<undef>) if not applicable to the data source,
and empty if not applicable to the table.

=end original

B<FKTABLE_SCHEMA(FK_TABLE_SCHEMA)>:外部キーテーブルスキーマ識別子。
このフィールドは、データソースに適用できない場合はNULL(C<undef>)、テーブルに適用できない場合は空です。
(TBR)

=begin original

B<FKTABLE_NAME   ( FK_TABLE_NAME     )>:
The foreign key table identifier.

=end original

B<FKTABLE_NAME   ( FK_TABLE_NAME     )>:
外部キー表識別子。

=begin original

B<FKCOLUMN_NAME  ( FK_COLUMN_NAME    )>:
The foreign key column identifier.

=end original

B<FKCOLUMN_NAME  ( FK_COLUMN_NAME    )>:
外部キー列識別子。

=begin original

B<KEY_SEQ        ( ORDINAL_POSITION  )>:
The column sequence number (starting with 1).

=end original

B<KEY_SEQ        ( ORDINAL_POSITION  )>:
列シーケンス番号(1 から開始)。

=begin original

B<UPDATE_RULE    ( UPDATE_RULE       )>:
The referential action for the UPDATE rule.
The following codes are defined:

=end original

B<UPDATE_RULE ( UPDATE_RULE )>:UPDATEルールの参照アクション。
次のコードが定義されています。
(TBR)

  CASCADE              0
  RESTRICT             1
  SET NULL             2
  NO ACTION            3
  SET DEFAULT          4

=begin original

B<DELETE_RULE    ( DELETE_RULE       )>:
The referential action for the DELETE rule.
The codes are the same as for UPDATE_RULE.

=end original

B<DELETE_RULE ( DELETE_RULE )>:DELETEルールの参照アクション。
コードはUPDATE_RULEのものと同じです。
(TBR)

=begin original

B<FK_NAME        ( FK_NAME           )>:
The foreign key name.

=end original

B<FK_NAME        ( FK_NAME           )>:
外部キー名。

=begin original

B<PK_NAME        ( UK_NAME           )>:
The primary (unique) key name.

=end original

B<PK_NAME        ( UK_NAME           )>:
主 (ユニーク) キー名。

=begin original

B<DEFERRABILITY  ( DEFERABILITY      )>:
The deferrability of the foreign key constraint.
The following codes are defined:

=end original

B<DEFERRABILITY(DEFERRABILITY)>:外部キー制約の遅延可能性。
次のコードが定義されています。
(TBR)

  INITIALLY DEFERRED   5
  INITIALLY IMMEDIATE  6
  NOT DEFERRABLE       7

=begin original

B<               ( UNIQUE_OR_PRIMARY )>:
This column is necessary if a driver includes all candidate (i.e. primary and
alternate) keys in the result set (as specified by SQL/CLI).
The value of this column is UNIQUE if the foreign key references an alternate
key and PRIMARY if the foreign key references a primary key, or it
may be undefined if the driver doesn't have access to the information.

=end original

B< ( UNIQUE_OR_PRIMARY )>:この列は、ドライバの結果セットにすべての候補キー(主キーと代替キー)が含まれている場合に必要です(SQL/CLIで指定)。
この列の値は、外部キーが代替キーを参照している場合はUNIQUE、外部キーが主キーを参照している場合はPRIMARYです。
ドライバが情報にアクセスできない場合は、未定義になることがあります。
(TBR)

=begin original

See also L</"Catalog Methods"> and L</"Standards Reference Information">.

=end original

L</"Catalog Methods"> と L</"Standards Reference Information"> も
参照してください。

=head3 C<statistics_info>

=begin original

B<Warning:> This method is experimental and may change.

=end original

B<警告:> このメソッドは実験的であり変更されるかもしれません。

  $sth = $dbh->statistics_info( $catalog, $schema, $table, $unique_only, $quick );

  # then $sth->fetchall_arrayref or $sth->fetchall_hashref etc

=begin original

Returns an active statement handle that can be used to fetch statistical
information about a table and its indexes.

=end original

表とそのインデックスに関する統計情報を取得するのに使える、有効な
文ハンドルを返します。

=begin original

The arguments don't accept search patterns (unlike L</table_info>).

=end original

引数は (L</table_info> と違って) 検索パターンは受け付けません。

=begin original

If the boolean argument $unique_only is true, only UNIQUE indexes will be
returned in the result set, otherwise all indexes will be returned.

=end original

真偽値引数 $unique_only が真なら、ユニークインデックスのみが
結果セットで返され、さもなければ全てのインデックスが返されます。

=begin original

If the boolean argument $quick is set, the actual statistical information
columns (CARDINALITY and PAGES) will only be returned if they are readily
available from the server, and might not be current.  Some databases may
return stale statistics or no statistics at all with this flag set.

=end original

ブール値の引数$quickが設定されている場合、実際の統計情報の列(CARDINALITYおよびPAGES)が返されるのは、それらの列がサーバーからすぐに利用できる場合のみで、最新のものではない可能性があります。
データベースによっては、このフラグを設定すると、古い統計情報が返されたり、統計情報がまったく返されない場合があります。
(TBR)

=begin original

The statement handle will return at most one row per column name per index,
plus at most one row for the entire table itself, ordered by NON_UNIQUE, TYPE,
INDEX_QUALIFIER, INDEX_NAME, and ORDINAL_POSITION.

=end original

ステートメントハンドルは、NON_UNIQUE、TYPE、INDEX_QUALIFIER、INDEX_NAME、およびORDINAL_POSITIONの順序で、インデックスごとに列名ごとに最大1つのローと、テーブル全体で最大1つのローを返します。
(TBR)

=begin original

Note: The support for the selection criteria, such as $catalog, is
driver specific.  If the driver doesn't support catalogs and/or
schemas, it may ignore these criteria.

=end original

注意:$catalog のような、選択条件のサポートはドライバによります。
もしドライバがカタログやスキーマをサポートしていなければ、これらの条件は
無視されるかもしれません。

=begin original

The statement handle returned has at least the following fields in the
order shown below. Other fields, after these, may also be present.

=end original

返された行ハンドルは少なくとも後述する順序で以下のフィールドを持ちます。
これらの後に、他のフィールドもあるかもしれません。

=begin original

B<TABLE_CAT>: The catalog identifier.
This field is NULL (C<undef>) if not applicable to the data source,
which is often the case.  This field is empty if not applicable to the
table.

=end original

B<TABLE_CAT>: カタログ識別子。
よくあることですが、データソースに適用できなければ、このフィールドが
NULL(C<undef>)です。
テーブルに適用できなければ、このフィールドは空です。

=begin original

B<TABLE_SCHEM>: The schema identifier.
This field is NULL (C<undef>) if not applicable to the data source,
and empty if not applicable to the table.

=end original

B<TABLE_SCHEM>: スキーマ識別子。
データソースに適用できなければ、このフィールドがNULL(C<undef>)です。
テーブルに適用できなければ、このフィールドは空です。

=begin original

B<TABLE_NAME>: The table identifier.

=end original

B<TABLE_NAME>: テーブル識別子。

=begin original

B<NON_UNIQUE>: Unique index indicator.
Returns 0 for unique indexes, 1 for non-unique indexes

=end original

B<NON_UNIQUE>: ユニークインデックス指示子。
ユニークインデックスの場合は 0 を、それ以外のインデックスでは 1 を
返します。

=begin original

B<INDEX_QUALIFIER>: Index qualifier identifier.
The identifier that is used to qualify the index name when doing a
C<DROP INDEX>; NULL (C<undef>) is returned if an index qualifier is not
supported by the data source.
If a non-NULL (defined) value is returned in this column, it must be used
to qualify the index name on a C<DROP INDEX> statement; otherwise,
the TABLE_SCHEM should be used to qualify the index name.

=end original

B<INDEX_QUALIFIER>:索引クオリファイア識別子。
C<DROP INDEX>の実行時に索引名の修飾に使用される識別子。
データソースで索引クオリファイアがサポートされていない場合は、NULL(C<undef>)が戻されます。
この列にNULL(定義済)以外の値が戻された場合は、その値を使用してC<DROP INDEX>文の索引名を修飾する必要があります。
それ以外の場合は、TABLE_SCHEMAを使用して索引名を修飾する必要があります。
(TBR)

=begin original

B<INDEX_NAME>: The index identifier.

=end original

B<INDEX_NAME>: インデックス識別子。

=begin original

B<TYPE>: The type of information being returned.  Can be any of the
following values: 'table', 'btree', 'clustered', 'content', 'hashed',
or 'other'.

=end original

B<TYPE>:戻される情報のタイプ。
'table'、'btree'、'clustered'、'content'、'hashed'、または'other'のいずれかの値になります。
(TBR)

=begin original

In the case that this field is 'table', all fields
other than TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TYPE,
CARDINALITY, and PAGES will be NULL (C<undef>).

=end original

このフィールドが'table'の場合、TABLE_CAT、TABLE_SCHEMA、TABLE_NAME、TYPE、CARDINALITY、およびPAGES以外のすべてのフィールドはNULL(C<undef>)になります。
(TBR)

=begin original

B<ORDINAL_POSITION>: Column sequence number (starting with 1).

=end original

B<ORDINAL_POSITION>: 列シーケンス番号 (1 から開始)。

=begin original

B<COLUMN_NAME>: The column identifier.

=end original

B<COLUMN_NAME>: 列識別子。

=begin original

B<ASC_OR_DESC>: Column sort sequence.
C<A> for Ascending, C<D> for Descending, or NULL (C<undef>) if
not supported for this index.

=end original

B<ASC_OR_DESC>:列のソート順序。
昇順の場合はC<A>、降順の場合はC<D>、この索引でサポートされていない場合はNULL(C<undef>)。
(TBR)

=begin original

B<CARDINALITY>: Cardinality of the table or index.
For indexes, this is the number of unique values in the index.
For tables, this is the number of rows in the table.
If not supported, the value will be NULL (C<undef>).

=end original

B<CARDINALITY>:表または索引のカーディナリティ。
索引の場合、これは索引内の一意の値の数です。
表の場合、これは表の行数です。
サポートされていない場合、値はNULL(C<undef>)になります。
(TBR)

=begin original

B<PAGES>: Number of storage pages used by this table or index.
If not supported, the value will be NULL (C<undef>).

=end original

B<PAGES>: この表またはインデックスで使われるページ番号。
対応していない場合は、値は NULL (C<undef>) になります。

=begin original

B<FILTER_CONDITION>: The index filter condition as a string.
If the index is not a filtered index, or it cannot be determined
whether the index is a filtered index, this value is NULL (C<undef>).
If the index is a filtered index, but the filter condition
cannot be determined, this value is the empty string C<''>.
Otherwise it will be the literal filter condition as a string,
such as C<SALARY <= 4500>.

=end original

B<FILTER_CONDITION>:文字列としてのインデックスフィルタ条件。
インデックスがフィルタされたインデックスでない場合、またはインデックスが
フィルタされたインデックスであるかどうかを判別できない場合、
この値はNULL(C<undef>)です。
インデックスがフィルタされたインデックスであるが、フィルタ条件を
判別できない場合、この値は空の文字列C<''>です。
それ以外の場合は、文字列としてのリテラルフィルタ条件
(C<SALARY <= 4500>など)になります。
(TBR)

=begin original

See also L</"Catalog Methods"> and L</"Standards Reference Information">.

=end original

L</"Catalog Methods"> と L</"Standards Reference Information"> も
参照してください。

=head3 C<tables>

  @names = $dbh->tables( $catalog, $schema, $table, $type );
  @names = $dbh->tables;	# deprecated

=begin original

Simple interface to table_info(). Returns a list of matching
table names, possibly including a catalog/schema prefix.

=end original

table_info()への単純なインターフェースです。
テーブル、ビューの名前の単純なリストを返します; 
おそらく頭にスキーマがついてきます。

=begin original

See L</table_info> for a description of the parameters.

=end original

パラメータの説明については L</table_info> を参照してください。

=begin original

If C<$dbh-E<gt>get_info(29)> returns true (29 is SQL_IDENTIFIER_QUOTE_CHAR)
then the table names are constructed and quoted by L</quote_identifier>
to ensure they are usable even if they contain whitespace or reserved
words etc. This means that the table names returned will include
quote characters.

=end original

C<$dbh-E<gt>get_info(29)>がtrueを返す場合(29はSQL_IDENTIFIER_QUOTE_CHAR)、空白や予約語などが含まれていても使用できるように、テーブル名はL</quote_identifier>で構成され、引用符で囲まれます。
これは、返されるテーブル名に引用符文字が含まれることを意味します。
(TBR)

=head3 C<type_info_all>

  $type_info_all = $dbh->type_info_all;

=begin original

Returns a reference to an array which holds information about each data
type variant supported by the database and driver. The array and its
contents should be treated as read-only.

=end original

データベースあるいはドライバによりサポートされるデータ型についての情報が
入った配列へのリファレンスを返します。
配列及びその内容は読み込み専用として扱われなければなりません。

=begin original

The first item is a reference to an 'index' hash of C<Name =>E<gt> C<Index> pairs.
The items following that are references to arrays, one per supported data
type variant. The leading index hash defines the names and order of the
fields within the arrays that follow it.
For example:

=end original

最初の要素は C<名前 => E<gt> C<インデックス>というペアのハッシュへの
リファレンスです。
その後の要素は、配列へのリファレンスで、１つずつがサポートされている
データ型になります。
最初のハッシュが後に続く配列要素のフィールドの名前と順序を定義しています。
例: 

  $type_info_all = [
    {   TYPE_NAME         => 0,
	DATA_TYPE         => 1,
	COLUMN_SIZE       => 2,     # was PRECISION originally
	LITERAL_PREFIX    => 3,
	LITERAL_SUFFIX    => 4,
	CREATE_PARAMS     => 5,
	NULLABLE          => 6,
	CASE_SENSITIVE    => 7,
	SEARCHABLE        => 8,
	UNSIGNED_ATTRIBUTE=> 9,
	FIXED_PREC_SCALE  => 10,    # was MONEY originally
	AUTO_UNIQUE_VALUE => 11,    # was AUTO_INCREMENT originally
	LOCAL_TYPE_NAME   => 12,
	MINIMUM_SCALE     => 13,
	MAXIMUM_SCALE     => 14,
	SQL_DATA_TYPE     => 15,
	SQL_DATETIME_SUB  => 16,
	NUM_PREC_RADIX    => 17,
	INTERVAL_PRECISION=> 18,
    },
    [ 'VARCHAR', SQL_VARCHAR,
	undef, "'","'", undef,0, 1,1,0,0,0,undef,1,255, undef
    ],
    [ 'INTEGER', SQL_INTEGER,
	undef,  "", "", undef,0, 0,1,0,0,0,undef,0,  0, 10
    ],
  ];

=begin original

More than one row may have the same value in the C<DATA_TYPE>
field if there are different ways to spell the type name and/or there
are variants of the type with different attributes (e.g., with and
without C<AUTO_UNIQUE_VALUE> set, with and without C<UNSIGNED_ATTRIBUTE>, etc).

=end original

その型の名前に違った書き方があったり、属性の違いで型のバリエーションが
あったり(例えば C<AUTO_UNIQUE_VALUE> があったりなかったり、
C<UNSIGNED_ATTRIBUTE> があったりなかったりなど)すれば、一つ以上のフィールドが
C<DATA_TYPE> フィールドに同じ値をもつこともあることに注意してください。

=begin original

The rows are ordered by C<DATA_TYPE> first and then by how closely each
type maps to the corresponding ODBC SQL data type, closest first.

=end original

行はまず C<DATA_TYPE> で順に、そして ODBC SQL データ型にどれくらい近く
対応しているかによって近いほど先に順に並びます。

=begin original

The meaning of the fields is described in the documentation for
the L</type_info> method.

=end original

各フィールドの意味は L</type_info> メソッドで説明しています。

=begin original

An 'index' hash is provided so you don't need to rely on index
values defined above.  However, using DBD::ODBC with some old ODBC
drivers may return older names, shown as comments in the example above.
Another issue with the index hash is that the lettercase of the
keys is not defined. It is usually uppercase, as show here, but
drivers may return names with any lettercase.

=end original

'index' ハッシュが提供されるので、上で定義されているインデックス値に
頼る必要はありません。
しかし、古い ODBC ドライバで DBD::ODBC を使うと、上述の例のコメントに
あるように、古い名前を返すかもしれません。
インデックスハッシュに関するもう一つの問題は、キーの大文字小文字が
未定義であることです。
それは通常、ここで見てきたように大文字ですが、ドライバは名前を大文字、
小文字のどちらで返しても自由です。

=begin original

Drivers are also free to return extra driver-specific columns of
information - though it's recommended that they start at column
index 50 to leave room for expansion of the DBI/ODBC specification.

=end original

ドライバは特別なドライバ専用の情報のカラムを返すのも自由です - しかし
DBI/ODBC 仕様の拡張のための空間をあけておくためにカラムインデックス 50 から
始めることをお勧めします。

=begin original

The type_info_all() method is not normally used directly.
The L</type_info> method provides a more usable and useful interface
to the data.

=end original

type_info_all()メソッドは通常直接使用されません。
L</type_info>メソッドは、データへのより使用可能で有用なインタフェースを提供します。
(TBR)

=head3 C<type_info>

  @type_info = $dbh->type_info($data_type);

=begin original

Returns a list of hash references holding information about one or more
variants of $data_type. The list is ordered by C<DATA_TYPE> first and
then by how closely each type maps to the corresponding ODBC SQL data
type, closest first.  If called in a scalar context then only the first
(best) element is returned.

=end original

一つあるいは複数の $data_type の変形についての情報が入ったハッシュへの
リファレンスのリストが返されます。
リストはまず C<DATA_TYPE> によって並べられ、そして各型が ODBC SQL データ型に
どらくらい近く対応しているかによって近いほど先に順に並びます。
スカラコンテキストで呼ばれれば、最初の(もっともよい)要素だけが返されます。

=begin original

If $data_type is undefined or C<SQL_ALL_TYPES>, then the list will
contain hashes for all data type variants supported by the database and driver.

=end original

$data_type が未定義か C<SQL_ALL_TYPES> であれば、リストにはデータベースと
ドライバによってサポートされているすべてのデータ型が入ります。

=begin original

If $data_type is an array reference then C<type_info> returns the
information for the I<first> type in the array that has any matches.

=end original

もし $data_type が配列リファレンスであれば、C<type_info> はその配列の
いずれかが対応する最初の型のための情報を返します。

=begin original

The keys of the hash follow the same letter case conventions as the
rest of the DBI (see L</Naming Conventions and Name Space>). The
following uppercase items should always exist, though may be undef:

=end original

以下のハッシュのキーは DBI の他の部分と同じようにすべて大文字もしくは
小文字で表わされます。
(L</Naming Conventions and Name Space> をご覧ください)。
以下に示す大文字要素は間違い無く存在しますが、未定義かもしれません:

=over 4

=item TYPE_NAME (string)

=begin original

Data type name for use in CREATE TABLE statements etc.

=end original

CREATE TABLE 文などで使われるデータ型名。 

=item DATA_TYPE (integer)

=begin original

SQL data type number.

=end original

SQL データ型番号。

=item COLUMN_SIZE (integer)

=begin original

For numeric types, this is either the total number of digits (if the
NUM_PREC_RADIX value is 10) or the total number of bits allowed in the
column (if NUM_PREC_RADIX is 2).

=end original

数値型については、これは(NUM_PREC_RADIX の値が 10 であれば)総桁数、
もしくは(NUM_PREC_RADIX の値が 2 であれば)カラムの中に許されるビットの
総数。

=begin original

For string types, this is the maximum size of the string in characters.

=end original

文字列型であれば、これは文字列の最大サイズを文字数で表したもの。

=begin original

For date and interval types, this is the maximum number of characters
needed to display the value.

=end original

日付(date)および期間(interval)型であれば、その値を表示するために必要な文字の
最大数です。

=item LITERAL_PREFIX (string)

=begin original

Characters used to prefix a literal. A typical prefix is "C<'>" for characters,
or possibly "C<0x>" for binary values passed as hexadecimal.  NULL (C<undef>) is
returned for data types for which this is not applicable.

=end original

リテラルの最初に使われる文字。
典型的なものとしては文字型には "C<'>"、バイナリ値には 16 進数を表わす
"C<0x>"。 
このデータ型に当てはまらなければ、NULL (C<undef>) が返されます。 

=item LITERAL_SUFFIX (string)

=begin original

Characters used to suffix a literal. Typically "C<'>" for characters.
NULL (C<undef>) is returned for data types where this is not applicable.

=end original

リテラルの最後に使われる文字。
典型的なものとしては文字型には "C<'>"。
このデータ型に当てはまらなければ、NULL (C<undef>)。 

=item CREATE_PARAMS (string)

=begin original

Parameter names for data type definition. For example, C<CREATE_PARAMS> for a
C<DECIMAL> would be "C<precision,scale>" if the DECIMAL type should be
declared as C<DECIMAL(>I<precision,scale>C<)> where I<precision> and I<scale>
are integer values.  For a C<VARCHAR> it would be "C<max length>".
NULL (C<undef>) is returned for data types for which this is not applicable.

=end original

データ型定義のためのパラメータ名。
例えば C<DECIMAL> が C<DECIMAL(>I<precision,scale>C<)> (全体桁数,小数点以下桁数)、
I<precision> と I<scale> は整数値のように宣言されなければならないのであれば、
C<DECIMAL> のための C<CREATE_PARAMS> は "C<precision,scale>" になります。
C<VARCHAR> では "C<max length>"(最大長)になります。
このデータ型に当てはまらなければ、NULL (C<undef>) が返されます。 

=item NULLABLE (integer)

=begin original

Indicates whether the data type accepts a NULL value:
C<0> or an empty string = no, C<1> = yes, C<2> = unknown.

=end original

このデータ型がNULL値を受け入れるかどうかを示します:
( C<0> または空文字列 = 受け入れない, C<1> = 受け入れる, C<2> = 不明) 

=item CASE_SENSITIVE (boolean)

=begin original

Indicates whether the data type is case sensitive in collations and
comparisons.

=end original

このデータ型が照会や比較のさいに大文字、小文字を区別するかどうかを示します。 

=item SEARCHABLE (integer)

=begin original

Indicates how the data type can be used in a WHERE clause, as
follows:

=end original

データタイプが WHERE 句で以下のように使用できるかどうかを示します:

=begin original

  0 - Cannot be used in a WHERE clause
  1 - Only with a LIKE predicate
  2 - All comparison operators except LIKE
  3 - Can be used in a WHERE clause with any comparison operator

=end original

  0 - WHERE 句で使うことはできません
  1 - LIKE と一緒になら使えます。
  2 - LIKE を除いてすべての比較演算子が使えます
  3 - WHERE 句においてすべての比較演算子が使えます

=item UNSIGNED_ATTRIBUTE (boolean)

=begin original

Indicates whether the data type is unsigned.  NULL (C<undef>) is returned
for data types for which this is not applicable.

=end original

データ型が符号なしであるかどうかを示します。
このデータ型に当てはまらなければ、NULL (C<undef>) が返されます。 

=item FIXED_PREC_SCALE (boolean)

=begin original

Indicates whether the data type always has the same precision and scale
(such as a money type).  NULL (C<undef>) is returned for data types
for which
this is not applicable.

=end original

そのデータ型が(money 型のように)常に同じ精度、桁数を持つかどうかを
示します。
このデータ型に当てはまらなければ、NULL (C<undef>) が返されます。 

=item AUTO_UNIQUE_VALUE (boolean)

=begin original

Indicates whether a column of this data type is automatically set to a
unique value whenever a new row is inserted.  NULL (C<undef>) is returned
for data types for which this is not applicable.

=end original

新しい行が挿入するときにはいつも、このデータ型のカラムは自動的に
ユニークな値に設定されるかどうかを示します。
このデータ型に当てはまらなければ、NULL (C<undef>) が返されます。 

=item LOCAL_TYPE_NAME (string)

=begin original

Localized version of the C<TYPE_NAME> for use in dialog with users.
NULL (C<undef>) is returned if a localized name is not available (in which
case C<TYPE_NAME> should be used).

=end original

ユーザとの対話に使われる C<TYPE_NAME> のローカル化されたバージョン。
ローカル化された名前がなければNULL (C<undef>)(この場合は C<TYPE_NAME> を
使わなければなりません)。

=item MINIMUM_SCALE (integer)

=begin original

The minimum scale of the data type. If a data type has a fixed scale,
then C<MAXIMUM_SCALE> holds the same value.  NULL (C<undef>) is returned for
data types for which this is not applicable.

=end original

データ型の最小桁数。
データ型が決まった桁数をもっていれば、C<MAXIMUM_SCALE> と同じになります。
このデータ型に当てはまらなければ、NULL (C<undef>) が返されます。 

=item MAXIMUM_SCALE (integer)

=begin original

The maximum scale of the data type. If a data type has a fixed scale,
then C<MINIMUM_SCALE> holds the same value.  NULL (C<undef>) is returned for
data types for which this is not applicable.

=end original

データ型の最大桁数。
データ型が決まった桁数をもっていれば、C<MINIMUM_SCALE> と同じになります。
このデータ型に当てはまらなければ、NULL (C<undef>) が返されます。 

=item SQL_DATA_TYPE (integer)

=begin original

This column is the same as the C<DATA_TYPE> column, except for interval
and datetime data types.  For interval and datetime data types, the
C<SQL_DATA_TYPE> field will return C<SQL_INTERVAL> or C<SQL_DATETIME>, and the
C<SQL_DATETIME_SUB> field below will return the subcode for the specific
interval or datetime data type. If this field is NULL, then the driver
does not support or report on interval or datetime subtypes.

=end original

期間(interval)と日時(datetime)型を除いては、このカラムは C<DATA_TYPE> と
同じです。
期間(interval)と日時(datetime)型であれば、C<SQL_DATA_TYPE> は
C<SQL_INTERVAL> もしくは C<SQL_DATETIME> を返し、以下の C<SQL_DATETIME_SUB> は
特定の期間(interval)または日時(datetime)型のためのサブコードを返します。
もしこのフィールドが NULL であれば、ドライバは期間(interval)または
日時(datetime)型をサポートしていないか、報告しません。 

=item SQL_DATETIME_SUB (integer)

=begin original

For interval or datetime data types, where the C<SQL_DATA_TYPE>
field above is C<SQL_INTERVAL> or C<SQL_DATETIME>, this field will
hold the I<subcode> for the specific interval or datetime data type.
Otherwise it will be NULL (C<undef>).

=end original

期間(interval)と日時(datetime)型であれば、上記の
C<SQL_DATA_TYPE> は C<SQL_INTERVAL> もしくは C<SQL_DATETIME> を返し、
このフィールドは特定の期間(interval)または日時(datetime)型のための
サブコードを返します。
そうでなければNULL(undef)になります。 

=begin original

Although not mentioned explicitly in the standards, it seems there
is a simple relationship between these values:

=end original

標準には明示的に記述されていませんが、これらの値には単純な関係が
あるようです:

  DATA_TYPE == (10 * SQL_DATA_TYPE) + SQL_DATETIME_SUB

=item NUM_PREC_RADIX (integer)

=begin original

The radix value of the data type. For approximate numeric types,
C<NUM_PREC_RADIX>
contains the value 2 and C<COLUMN_SIZE> holds the number of bits. For
exact numeric types, C<NUM_PREC_RADIX> contains the value 10 and C<COLUMN_SIZE> holds
the number of decimal digits. NULL (C<undef>) is returned either for data types
for which this is not applicable or if the driver cannot report this information.

=end original

そのデータ型の基数を返します。
概算の数値型では、NUM_PREC_RADIX の値は 2 で COLUMN_SIZE はビットの数を
持ちます。
厳密な数値型では C<NUM_PREC_RADIX> の値は 10 で、COLUMN_SIZE には
10 進数の桁数が入ります。
このデータ型に当てはまらないか、ドライバがこの情報を報告できなければ、
NULL (C<undef>) が返されます。 

=item INTERVAL_PRECISION (integer)

=begin original

The interval leading precision for interval types. NULL is returned
either for data types for which this is not applicable or if the driver
cannot report this information.

=end original

期間(interval)型のための先行精度です。
このデータ型に当てはまらないか、ドライバがこの情報を報告できなければ、
NULL (C<undef>) が返されます。

=back

=begin original

For example, to find the type name for the fields in a select statement
you can do:

=end original

例えば select 文でのフィールドのためのデータ型名を見つけるには
以下のようにすることができます:

  @names = map { scalar $dbh->type_info($_)->{TYPE_NAME} } @{ $sth->{TYPE} }

=begin original

Since DBI and ODBC drivers vary in how they map their types into the
ISO standard types you may need to search for more than one type.
Here's an example looking for a usable type to store a date:

=end original

DBI と ODBC ドライバとは型を ISO 標準型にどのようにマッピングするのかが
異なっているため、一つ以上の型を探さなければならないかもしれません。
以下に日付を格納するのに使えるデータ型を探す例を示します:

  $my_date_type = $dbh->type_info( [ SQL_DATE, SQL_TIMESTAMP ] );

=begin original

Similarly, to more reliably find a type to store small integers, you could
use a list starting with C<SQL_SMALLINT>, C<SQL_INTEGER>, C<SQL_DECIMAL>, etc.

=end original

同じように、小さな整数を格納するための型の検索を信頼できるようにするため、
C<SQL_SMALLINT>, C<SQL_INTEGER>, C<SQL_DECIMAL> などから始まるリストを
使うこともできます。

=begin original

See also L</"Standards Reference Information">.

=end original

L</"Standards Reference Information"> も参照してください。

=head3 C<quote>

  $sql = $dbh->quote($value);
  $sql = $dbh->quote($value, $data_type);

=begin original

Quote a string literal for use as a literal value in an SQL statement,
by escaping any special characters (such as quotation marks)
contained within the string and adding the required type of outer
quotation marks.

=end original

文字列の中の(クォーテーションマークのような)特殊な文字をエスケープし、
必要とされるタイプの外側のクォーテーションマークを加えることにより、
文字列リテラルを SQL 文で使うリテラル値として使えるようにクォートします。

  $sql = sprintf "SELECT foo FROM bar WHERE baz = %s",
                $dbh->quote("Don't");

=begin original

For most database types, at least those that conform to SQL standards, quote
would return C<'Don''t'> (including the outer quotation marks). For others it
may return something like C<'Don\'t'>

=end original

ほとんどのデータベースでは、少なくとも SQL 標準に従っているものなら、
quote は C<'Don"t'> を返します(外側のクォーテーションマークを含みます)。
その他の場合は C<'Don\'t'> のようなものを返します。

=begin original

An undefined C<$value> value will be returned as the string C<NULL> (without
single quotation marks) to match how NULLs are represented in SQL.

=end original

未定義の C<$value> の値は SQL で NULL を表すことに対応するよう、文字列 NULL
(シングルクォーテションマークなし)になります。

=begin original

If C<$data_type> is supplied, it is used to try to determine the required
quoting behaviour by using the information returned by L</type_info>.
As a special case, the standard numeric types are optimized to return
C<$value> without calling C<type_info>.

=end original

C<$data_type> が与えられると、L</type_info> から返される情報を元にして
要求されたクォートの処理を決めます。
特殊な場合として、標準の数値型は C<type_info> を呼ばずに、C<$value> を
返すように最適化されています。

=begin original

Quote will probably I<not> be able to deal with all possible input
(such as binary data or data containing newlines), and is not related in
any way with escaping or quoting shell meta-characters.

=end original

quote は(バイナリデータや改行が入っているデータのように)すべての入力に
対応できるわけではありません; そしてシェルのエスケープやメタ文字にはまったく
関連してはいません。

=begin original

It is valid for the quote() method to return an SQL expression that
evaluates to the desired string. For example:

=end original

必要な文字列を評価する SQL 式を返すための quote() メソッドも有効です。
例えば:

  $quoted = $dbh->quote("one\ntwo\0three")

=begin original

may return something like:

=end original

というものは以下のようなものを返します:

  CONCAT('one', CHAR(12), 'two', CHAR(0), 'three')

=begin original

The quote() method should I<not> be used with L</"Placeholders and
Bind Values">.

=end original

quote() メソッドは L</"Placeholders and Bind Values"> と使うべきでは
I<ありません> 。

=head3 C<quote_identifier>

  $sql = $dbh->quote_identifier( $name );
  $sql = $dbh->quote_identifier( $catalog, $schema, $table, \%attr );

=begin original

Quote an identifier (table name etc.) for use in an SQL statement,
by escaping any special characters (such as double quotation marks)
it contains and adding the required type of outer quotation marks.

=end original

SQL文で使用する識別子(テーブル名など)を引用符で囲むには、識別子に含まれる特殊文字(二重引用符など)をエスケープし、必要なタイプの外部引用符を追加します。
(TBR)

=begin original

Undefined names are ignored and the remainder are quoted and then
joined together, typically with a dot (C<.>) character. For example:

=end original

未定義の名前は無視され、残りはクォートされてから互いに
(典型的にはドット (C<.>) 文字で)結合されます。
例えば:

  $id = $dbh->quote_identifier( undef, 'Her schema', 'My table' );

=begin original

would, for most database types, return C<"Her schema"."My table">
(including all the double quotation marks).

=end original

というのは、ほとんどのデータベース型では、
C<"Her schema"."My table"> (ダブルクォートを含みます) を返します。

=begin original

If three names are supplied then the first is assumed to be a
catalog name and special rules may be applied based on what L</get_info>
returns for SQL_CATALOG_NAME_SEPARATOR (41) and SQL_CATALOG_LOCATION (114).
For example, for Oracle:

=end original

3つの名前が指定された場合、最初の名前はカタログ名と見なされ、L</get_info>がSQL_CATALOG_NAME_SEPARATOR(41)およびSQL_CATALOG_LOCATION(114)に対して返す内容に基づいて特別なルールが適用される場合があります。
たとえば、Oracleの場合は次のようになります。
(TBR)

  $id = $dbh->quote_identifier( 'link', 'schema', 'table' );

=begin original

would return C<"schema"."table"@"link">.

=end original

は C<"schema"."table"@"link"> を返します。

=head3 C<take_imp_data>

  $imp_data = $dbh->take_imp_data;

=begin original

Leaves the $dbh in an almost dead, zombie-like, state and returns
a binary string of raw implementation data from the driver which
describes the current database connection. Effectively it detaches
the underlying database API connection data from the DBI handle.
After calling take_imp_data(), all other methods except C<DESTROY>
will generate a warning and return undef.

=end original

$dbhをほとんど動かない、ゾンビのような状態のままにして、現在のデータベース接続を記述するドライバからの生の実装データのバイナリ文字列を返します。
実質的に、基礎となるデータベースAPI接続データをDBIハンドルから切り離します。
take_imp_data()を呼び出した後、C<DESTROY>を除く他のすべてのメソッドは警告を生成し、undefを返します。
(TBR)

=begin original

Why would you want to do this? You don't, forget I even mentioned it.
Unless, that is, you're implementing something advanced like a
multi-threaded connection pool. See L<DBI::Pool>.

=end original

なぜあなたはこれをしたいのですか?あなたはしません、私がそれを言ったことさえ忘れてください。
ただし、マルチスレッド接続プールのような高度なものを実装している場合は除きます。
L<DBI::Pool>を参照してください。
(TBR)

=begin original

The returned $imp_data can be passed as a C<dbi_imp_data> attribute
to a later connect() call, even in a separate thread in the same
process, where the driver can use it to 'adopt' the existing
connection that the implementation data was taken from.

=end original

返された$imp_dataは、後のconnect()呼び出しにCの<dbi_imp_data>属性として渡すことができます。
同じプロセス内の別のスレッドであってもかまいません。
ドライバは、この属性を使用して、実装データが取得された既存の接続を「採用」できます。
(TBR)

=begin original

Some things to keep in mind...

=end original

覚えておくべきことは…

=begin original

B<*> the $imp_data holds the only reference to the underlying
database API connection data. That connection is still 'live' and
won't be cleaned up properly unless the $imp_data is used to create
a new $dbh which is then allowed to disconnect() normally.

=end original

B<*>$imp_dataは、基礎となるデータベースAPI接続データへの唯一の参照を保持しています。
この接続はまだ「有効」であり、$imp_dataを使用して新しい$dbhを作成し、通常どおりdisconnect()できるようにしない限り、適切にクリーンアップされません。
(TBR)

=begin original

B<*> using the same $imp_data to create more than one other new
$dbh at a time may well lead to unpleasant problems. Don't do that.

=end original

B<*>同じ$imp_dataを使用して一度に複数の新しい$dbhを作成すると、不快な問題が発生する可能性があります。
そんなことしないで。
(TBR)

=begin original

Any child statement handles are effectively destroyed when take_imp_data() is
called.

=end original

子文ハンドルは、take_imp_data() が呼び出されると正しく破壊されます。

=begin original

The C<take_imp_data> method was added in DBI 1.36 but wasn't useful till 1.49.

=end original

C<take_imp_data> メソッドは DBI 1.36 で追加されましたが
1.49 までは有用ではありませんでした。

=head2 Database Handle Attributes

(データベースハンドル属性)

=begin original

This section describes attributes specific to database handles.

=end original

このセクションではデータベースハンドルに特有の属性について記述します。

=begin original

Changes to these database handle attributes do not affect any other
existing or future database handles.

=end original

これらのデータベースハンドル属性を変更しても、既存の他の
データベースハンドルあるいはこの後、生成されるデータベースハンドルには
影響を与えません。

=begin original

Attempting to set or get the value of an unknown attribute generates a warning,
except for private driver-specific attributes (which all have names
starting with a lowercase letter).

=end original

ドライバ特有のプライベートな属性(これらの名前は小文字ではじまります)を
除いては、決められていない属性を設定あるいは取得しようとすると
警告が発生します。

=begin original

Example:

=end original

例:

  $h->{AutoCommit} = ...;	# set/write
  ... = $h->{AutoCommit};	# get/read

=head3 C<AutoCommit>  (boolean)

=begin original

If true, then database changes cannot be rolled-back (undone).  If false,
then database changes automatically occur within a "transaction", which
must either be committed or rolled back using the C<commit> or C<rollback>
methods.

=end original

真であれば、データベースの変更をロールバックする(元に戻す)ことは
できません。
偽であれば、データベースの変更は自動的に「トランザクション」の中に入り、
C<commit> または C<rollback> メソッドを使ってコミットあるいは
ロールバックされなければなりません。 

=begin original

Drivers should always default to C<AutoCommit> mode (an unfortunate
choice largely forced on the DBI by ODBC and JDBC conventions.)

=end original

ドライバはデフォルトを C<AutoCommit> モードにしなければいけません
(ODBC と JDBC の決まりにより、残念ながら DBI はこうせざるを得ません。)

=begin original

Attempting to set C<AutoCommit> to an unsupported value is a fatal error.
This is an important feature of the DBI. Applications that need
full transaction behaviour can set C<$dbh-E<gt>{AutoCommit} = 0> (or
set C<AutoCommit> to 0 via L</connect>)
without having to check that the value was assigned successfully.

=end original

C<AutoCommit> をサポートされていない値に設定しようとすると、致命的な
エラーになります。
これは DBI の重要な機能です。
完全なトランザクションを必要とするアプリケーションは、値が正しく代入されたか
どうかをチェックすることなく C<$dbh-E<gt>{AutoCommit} = 0> と
する(または L</connect> メソッドでの C<AutoCommit> を 0 に設定する)ことが
できます。

=begin original

For the purposes of this description, we can divide databases into three
categories:

=end original

この点から、データベースを三つのカテゴリに分けることができます。

=begin original

  Databases which don't support transactions at all.
  Databases in which a transaction is always active.
  Databases in which a transaction must be explicitly started (C<'BEGIN WORK'>).

=end original

  全くトランザクションをサポートしていないデータベース
  いつでもトランザクションが有効なデータベース
  明示的にトランザクションを開始(C<'BEGIN WORK'>などにより)しなければいけないデータベース

=begin original

B<* Databases which don't support transactions at all>

=end original

B<* 全くトランザクションをサポートしていないデータベース>

=begin original

For these databases, attempting to turn C<AutoCommit> off is a fatal error.
C<commit> and C<rollback> both issue warnings about being ineffective while
C<AutoCommit> is in effect.

=end original

これらのデータベースで、C<AutoCommit> をオフにしようとすると
致命的エラーになります。
C<commit>, C<rollback> は C<AutoCommit> が有効な間は無効であるという
警告を起こします。

=begin original

B<* Databases in which a transaction is always active>

=end original

B<* いつでもトランザクションが有効なデータベース>

=begin original

These are typically mainstream commercial relational databases with
"ANSI standard" transaction behaviour.
If C<AutoCommit> is off, then changes to the database won't have any
lasting effect unless L</commit> is called (but see also
L</disconnect>). If L</rollback> is called then any changes since the
last commit are undone.

=end original

「ANSI標準」トランザクション機能を持った商用リレーショナルデータベースでは、
これが主流です。
C<AutoCommit> がオフであると、データベースへの変更は L</commit> されるまで
有効になりません (しかし L</disconnect> もご覧ください)。
もし L</rollback> が呼ばれると、最後のコミット以降のいかなる変更も元に
戻されます。

=begin original

If C<AutoCommit> is on, then the effect is the same as if the DBI
called C<commit> automatically after every successful database
operation. So calling C<commit> or C<rollback> explicitly while
C<AutoCommit> is on would be ineffective because the changes would
have already been committed.

=end original

C<AutoCommit> がオンであると、DBI はまるで正常終了したデータベース操作の後、
自動的に C<commit> を呼んでいるのと同じように振る舞います。
従って C<AutoCommit> がオンの間に C<commit>, C<rollback> を明示的に
呼び出しても、すでにコミットされてしまっているので、何も効果がありません。

=begin original

Changing C<AutoCommit> from off to on will trigger a L</commit>.

=end original

C<AutoCommit> をオフからオンに変えると、大抵のドライバは L</commit> します。

=begin original

For databases which don't support a specific auto-commit mode, the
driver has to commit each statement automatically using an explicit
C<COMMIT> after it completes successfully (and roll it back using an
explicit C<ROLLBACK> if it fails).  The error information reported to the
application will correspond to the statement which was executed, unless
it succeeded and the commit or rollback failed.

=end original

自動コミットモードを特にサポートしていないデータベースでは、ドライバは
各文が正常終了したら、明示的に C<COMMIT> することにより、
自動的にコミットしなければいけません(失敗したら明示的に C<ROLLBACK> して
元に戻さなければいけません)。
アプリケーションに伝えられるエラー情報は、文が正常終了した後、
コミットやロールバックが失敗しない限りは、実行された文に
対応しなければいけません。

=begin original

B<* Databases in which a transaction must be explicitly started>

=end original

B<* トランザクションが明示的に開始されなければならないデータベース>

=begin original

For these databases, the intention is to have them act like databases in
which a transaction is always active (as described above).

=end original

これらのデータベースでは、トランザクションは(上記のような)いつでも
有効になるデータベースと同じようにします。

=begin original

To do this, the driver will automatically begin an explicit transaction
when C<AutoCommit> is turned off, or after a L</commit> or
L</rollback> (or when the application issues the next database
operation after one of those events).

=end original

こうするため、ドライバは C<AutoCommit> がオフになるか、
L</commit> や L</rollback> の後(あるいはアプリケーションがこれらの
イベントの一つの後次のデータベース操作を行ったとき)、自動的に
トランザクションを開始します。

=begin original

In this way, the application does not have to treat these databases
as a special case.

=end original

こうして、アプリケーションはこれらのデータベースを特別なケースとして
扱わなくてもよくなるのです。

=begin original

See L</commit>, L</disconnect> and L</Transactions> for other important
notes about transactions.

=end original

トランザクションについてのほかの重要な情報については L</commit>,
L</disconnect>, L</Transactions> をご覧ください。

=head3 C<Driver>  (handle)

=begin original

Holds the handle of the parent driver. The only recommended use for this
is to find the name of the driver using:

=end original

ハンドルの親ドライバを保持します。
唯一推奨されるこれの使い方は以下のようにしてドライバの名前を
見つけることだけです: 

  $dbh->{Driver}->{Name}

=head3 C<Name>  (string)

=begin original

Holds the "name" of the database. Usually (and recommended to be) the
same as the "C<dbi:DriverName:...>" string used to connect to the database,
but with the leading "C<dbi:DriverName:>" removed.

=end original

データベースの名前が入ります。
通常は(そして推奨されることですが)データベースへの接続に使われる
"C<dbi:DriverName:...>" 文字列から先頭の "C<dbi:DriverName:>" を
取ったものになります。 

=head3 C<Statement>  (string, read-only)

=begin original

Returns the statement string passed to the most recent L</prepare> method
called in this database handle, even if that method failed. This is especially
useful where C<RaiseError> is enabled and the exception handler checks $@
and sees that a 'prepare' method call failed.

=end original

このデータベースハンドルで最後の L</prepare> メソッドに渡された
文文字列を返します。
もしそのメソッドが失敗していたとしてもです。
これは C<RaiseError> が有効になっていて、例外ハンドラが $@ をチェックし、
'prepare' メソッドが失敗したかもしれないと思われるときには特に便利でしょう。 

=head3 C<RowCacheSize>  (integer)

=begin original

A hint to the driver indicating the size of the local row cache that the
application would like the driver to use for future C<SELECT> statements.
If a row cache is not implemented, then setting C<RowCacheSize> is ignored
and getting the value returns C<undef>.

=end original

アプリケーションがドライバに後からの C<SELECT> 文のために使わせたい
ローカルな行キャッシュの大きさを示すドライバへのヒントです。
行キャッシュが実装されていなければ、C<RowCacheSize> の設定は無視され、値は
C<undef> が返ります。 

=begin original

Some C<RowCacheSize> values have special meaning, as follows:

=end original

C<RowCacheSize> の値には以下のような意味があります:

=begin original

  0 - Automatically determine a reasonable cache size for each C<SELECT>
  1 - Disable the local row cache
 >1 - Cache this many rows
 <0 - Cache as many rows that will fit into this much memory for each C<SELECT>.

=end original

  0 - 自動的に各 C<SELECT> に適切なキャッシュサイズを決めます
  1 - ローカル行キャッシュを使用しません
 >1 - この数だけ行をキャッシュします
 <0 - 各 C<SELECT> のためにメモリの量に合わせてできるだけ多くの行をキャッシュします

=begin original

Note that large cache sizes may require a very large amount of memory
(I<cached rows * maximum size of row>). Also, a large cache will cause
a longer delay not only for the first fetch, but also whenever the
cache needs refilling.

=end original

キャッシュの大きさを大きくすると大量のメモリが必要になること
(キャッシュされる行の数×行の最大サイズ)、そして大きなキャッシュをとると
それだけ最初の取得あるいは次のキャッシュ分を取得のさいに時間がかかるように
なることに注意してください。

=begin original

See also the L</RowsInCache> statement handle attribute.

=end original

L</RowsInCache> 文ハンドル属性もご覧ください。

=head3 C<Username>  (string)

=begin original

Returns the username used to connect to the database.

=end original

データベースとの接続に使われたユーザー名を返します。

=head1 DBI STATEMENT HANDLE OBJECTS

(DBI 文ハンドルオブジェクト)

=begin original

This section lists the methods and attributes associated with DBI
statement handles.

=end original

この節では DBI 文ハンドルに関連するメソッドと属性を一覧にします。

=head2 Statement Handle Methods

(文ハンドルメソッド)

=begin original

The DBI defines the following methods for use on DBI statement handles:

=end original

DBI は DBI 文ハンドルのために以下のメソッドを定義しています:

=head3 C<bind_param>

  $sth->bind_param($p_num, $bind_value)
  $sth->bind_param($p_num, $bind_value, \%attr)
  $sth->bind_param($p_num, $bind_value, $bind_type)

=begin original

The C<bind_param> method takes a copy of $bind_value and associates it
(binds it) with a placeholder, identified by $p_num, embedded in
the prepared statement. Placeholders are indicated with question
mark character (C<?>). For example:

=end original

C<bind_param> メソッドは $bind_value のコピーを取って、prepared 文に
埋め込まれている、$p_num で識別されるプレースホルダと結びつけます。
プレースホルダは疑問符(C<?>)により示されます。
例えば:

=begin original

  $dbh->{RaiseError} = 1;        # save having to check each method call
  $sth = $dbh->prepare("SELECT name, age FROM people WHERE name LIKE ?");
  $sth->bind_param(1, "John%");  # placeholders are numbered from 1
  $sth->execute;
  DBI::dump_results($sth);

=end original

  $dbh->{RaiseError} = 1;        # 各メソッド呼び出しをチェックするようにする
  $sth = $dbh->prepare("select name, age from people where name like ?");
  $sth->bind_param(1, "John%");  # プレースホルダは 1 から順番
  $sth->execute;
  DBI::dump_results($sth);

=begin original

See L</"Placeholders and Bind Values"> for more information.

=end original

さらなる情報については L</"Placeholders and Bind Values"> を
参照してください。

=begin original

B<Data Types for Placeholders>

=end original

B<プレースホルダのデータ型>

=begin original

The C<\%attr> parameter can be used to hint at the data type the
placeholder should have. This is rarely needed. Typically, the driver is only
interested in knowing if the placeholder should be bound as a number or a string.

=end original

C<\%attr> パラメータはプレースホルダが持つべきデータ型を指定するために
使われます。
通常、ドライバはプレースホルダが結びつけられるのが数値としてなのか、
文字列としてなのかを知ることだけに関心があります。

  $sth->bind_param(1, $value, { TYPE => SQL_INTEGER });

=begin original

As a short-cut for the common case, the data type can be passed
directly, in place of the C<\%attr> hash reference. This example is
equivalent to the one above:

=end original

よくあるケースのための短縮形として、データ型を直接 C<\%attr>
ハッシュリファレンスの場所に直接、渡すことができます。
この例は、上記のものと同じです。

  $sth->bind_param(1, $value, SQL_INTEGER);

=begin original

The C<TYPE> value indicates the standard (non-driver-specific) type for
this parameter. To specify the driver-specific type, the driver may
support a driver-specific attribute, such as C<{ ora_type =E<gt> 97 }>.

=end original

C<TYPE> の値はこのパラメータでは(ドライバに特有でない)標準の型を示します。
ドライバ特有の型を指定するために、ドライバは C<{ ora_type => 97 }> といった
ドライバ特有の型をサポートしていることがあります。

=begin original

The SQL_INTEGER and other related constants can be imported using

=end original

SQL_INTEGER および関連する定数は以下のようにしてインポートできます

  use DBI qw(:sql_types);

=begin original

See L</"DBI Constants"> for more information.

=end original

さらなる情報については L</"DBI Constants"> を参照してください。

=begin original

The data type is 'sticky' in that bind values passed to execute() are bound
with the data type specified by earlier bind_param() calls, if any.
Portable applications should not rely on being able to change the data type
after the first C<bind_param> call.

=end original

データ型は'sticky'で、execute()に渡されたバインド値は、前のbind_param()呼び出しで指定されたデータ型にバインドされます(存在する場合)。
移植性のあるアプリケーションでは、最初のC<bind_param>呼び出しの後にデータ型を変更できることに依存しないでください。
(TBR)

=begin original

Perl only has string and number scalar data types. All database types
that aren't numbers are bound as strings and must be in a format the
database will understand except where the bind_param() TYPE attribute
specifies a type that implies a particular format. For example, given:

=end original

Perlには、文字列と数値のスカラーデータ型しかありません。
数値以外のすべてのデータベースタイプは文字列としてバインドされ、データベースが理解できるフォーマットでなければなりません。
ただし、bind_param()TYPE属性が特定のフォーマットを示すタイプを指定している場合を除きます。
たとえば、次のようになります。
(TBR)

  $sth->bind_param(1, $value, SQL_DATETIME);

=begin original

the driver should expect $value to be in the ODBC standard SQL_DATETIME
format, which is 'YYYY-MM-DD HH:MM:SS'. Similarly for SQL_DATE, SQL_TIME etc.

=end original

ドライバは、$valueがODBC標準のSQL_DATETIME形式('YYYY-MM-DD HH:MM:SS')であることを想定する必要があります。
SQL_DATE、SQL_TIMEなどについても同様です。
(TBR)

=begin original

As an alternative to specifying the data type in the C<bind_param> call,
you can let the driver pass the value as the default type (C<VARCHAR>).
You can then use an SQL function to convert the type within the statement.
For example:

=end original

データ型を C<bind_param> 呼び出しの際に指定する代わりに、ドライバに
データをデフォルトの型(C<VARCHAR>)として渡すこともできます。
そして SQL 関数で文の中で変換することができます。
例えば:

  INSERT INTO price(code, price) VALUES (?, CONVERT(MONEY,?))

=begin original

The C<CONVERT> function used here is just an example. The actual function
and syntax will vary between different databases and is non-portable.

=end original

C<CONVERT> 関数は単なる例として使われています。
実際の関数と書き方はデータベースによって大きく違いますし、移植性もありません。

=begin original

See also L</"Placeholders and Bind Values"> for more information.

=end original

詳しい情報については L</"Placeholders and Bind Values"> もご覧下さい。

=head3 C<bind_param_inout>

  $rc = $sth->bind_param_inout($p_num, \$bind_value, $max_len)  or die $sth->errstr;
  $rv = $sth->bind_param_inout($p_num, \$bind_value, $max_len, \%attr)     or ...
  $rv = $sth->bind_param_inout($p_num, \$bind_value, $max_len, $bind_type) or ...

=begin original

This method acts like L</bind_param>, but also enables values to be
updated by the statement. The statement is typically
a call to a stored procedure. The C<$bind_value> must be passed as a
reference to the actual value to be used.

=end original

このメソッドは L</bind_param> と似ていますが、文からの更新も
可能としています。
文は通常、ストアドプロシージャと呼ばれます。
C<$bind_value> は実際に使われる変数へのリファレンスとして渡されます。

=begin original

Note that unlike L</bind_param>, the C<$bind_value> variable is not
copied when C<bind_param_inout> is called. Instead, the value in the
variable is read at the time L</execute> is called.

=end original

L</bind_param> とは違い、C<$bind_value> 変数は C<bind_param_inout> が
呼ばれたときにはコピーされないことに注意してください。
変数の値は L</execute> が呼ばれたときに読みこまれます。

=begin original

The additional C<$max_len> parameter specifies the minimum amount of
memory to allocate to C<$bind_value> for the new value. If the value
returned from the database is too
big to fit, then the execution should fail. If unsure what value to use,
pick a generous length, i.e., a length larger than the longest value that would ever be
returned.  The only cost of using a larger value than needed is wasted memory.

=end original

追加された C<$max_len> パラメータは、C<$bin_value> の新しい値のために
確保される最小限のメモリ量を指定します。
もし実際の値が大きすぎて収まらなければ、実行は失敗します。
使用する量がわからなければ、大きな長さを惜しみなく、つまり
返されるかもしれない一番長い値より長く値を指定しましょう。
必要よりも大きな値を使うために犠牲になるのは、メモリの浪費だけです。

=begin original

Undefined values or C<undef> are used to indicate null values.
See also L</"Placeholders and Bind Values"> for more information.

=end original

未定義の値あるいは C<undef> は NULL 値を示すのに使われます。
さらに詳しい情報は L</"Placeholders and Bind Values"> もご覧下さい。

=head3 C<bind_param_array>

  $rc = $sth->bind_param_array($p_num, $array_ref_or_value)
  $rc = $sth->bind_param_array($p_num, $array_ref_or_value, \%attr)
  $rc = $sth->bind_param_array($p_num, $array_ref_or_value, $bind_type)

=begin original

The C<bind_param_array> method is used to bind an array of values
to a placeholder embedded in the prepared statement which is to be executed
with L</execute_array>. For example:

=end original

C<bind_param_array>メソッドは、L</execute_array>で実行される準備文に埋め込まれたプレースホルダに値の配列をバインドするために使用されます。
次に例を示します。
(TBR)

  $dbh->{RaiseError} = 1;        # save having to check each method call
  $sth = $dbh->prepare("INSERT INTO staff (first_name, last_name, dept) VALUES(?, ?, ?)");
  $sth->bind_param_array(1, [ 'John', 'Mary', 'Tim' ]);
  $sth->bind_param_array(2, [ 'Booth', 'Todd', 'Robinson' ]);
  $sth->bind_param_array(3, "SALES"); # scalar will be reused for each row
  $sth->execute_array( { ArrayTupleStatus => \my @tuple_status } );

=begin original

The C<%attr> ($bind_type) argument is the same as defined for L</bind_param>.
Refer to L</bind_param> for general details on using placeholders.

=end original

C<%attr>($bind_type)引数は、L</bind_param>に定義されているものと同じです。
プレースホルダの使用に関する一般的な詳細については、L</bind_param>を参照してください。
(TBR)

=begin original

(Note that bind_param_array() can I<not> be used to expand a
placeholder into a list of values for a statement like "SELECT foo
WHERE bar IN (?)".  A placeholder can only ever represent one value
per execution.)

=end original

(bind_param_array()を使用して、プレースホルダを「SELECT foo WHERE bar IN(?)」のような文の値のリストに展開することはできません。
プレースホルダは、1回の実行で1つの値しか表すことができません。
)
(TBR)

=begin original

Scalar values, including C<undef>, may also be bound by
C<bind_param_array>. In which case the same value will be used for each
L</execute> call. Driver-specific implementations may behave
differently, e.g., when binding to a stored procedure call, some
databases may permit mixing scalars and arrays as arguments.

=end original

C<undef>を含むスカラー値は、C<bind_param_array>によってもバインドできます。
この場合、各L</execute>呼び出しに同じ値が使用されます。
ドライバ固有の実装は、異なる動作をする場合があります。
たとえば、ストアドプロシージャコールにバインドする場合、一部のデータベースでは、引数としてスカラーと配列を混在させることができます。
(TBR)

=begin original

The default implementation provided by DBI (for drivers that have
not implemented array binding) is to iteratively call L</execute> for
each parameter tuple provided in the bound arrays.  Drivers may
provide more optimized implementations using whatever bulk operation
support the database API provides. The default driver behaviour should
match the default DBI behaviour, but always consult your driver
documentation as there may be driver specific issues to consider.

=end original

DBIによって提供されるデフォルトの実装(配列バインディングを実装していないドライバの場合)は、バインドされた配列で提供される各パラメータタプルに対してL</execute>を繰り返し呼び出すことです。
ドライバは、データベースAPIが提供するバルク操作サポートを使用して、より最適化された実装を提供する場合があります。
デフォルトのドライバ動作はデフォルトのDBI動作と一致する必要がありますが、考慮すべきドライバ固有の問題がある可能性があるため、常にドライバの文書を参照してください。
(TBR)

=begin original

Note that the default implementation currently only supports non-data
returning statements (INSERT, UPDATE, but not SELECT). Also,
C<bind_param_array> and L</bind_param> cannot be mixed in the same
statement execution, and C<bind_param_array> must be used with
L</execute_array>; using C<bind_param_array> will have no effect
for L</execute>.

=end original

デフォルトの実装では、現在、データを返さない文(INSERT、UPDATE、SELECT以外)のみをサポートしていることに注意してください。
また、C<bind_param_array>とL</bind_param>を同じ文の実行で混在させることはできません。
また、C<bind_param_array>はL</execute_array>とともに使用する必要があります。
C<bind_param_array>を使用してもL</execute>には影響しません。
(TBR)

=begin original

The C<bind_param_array> method was added in DBI 1.22.

=end original

C<bind_param_array> メソッドは DBI 1.22 で追加されました。

=head3 C<execute>

  $rv = $sth->execute                or die $sth->errstr;
  $rv = $sth->execute(@bind_values)  or die $sth->errstr;

=begin original

Perform whatever processing is necessary to execute the prepared
statement.  An C<undef> is returned if an error occurs.  A successful
C<execute> always returns true regardless of the number of rows affected,
even if it's zero (see below). It is always important to check the
return status of C<execute> (and most other DBI methods) for errors
if you're not using L</RaiseError>.

=end original

prepare された文を実行するために必要な処理をすべて行います。
エラーが発生したら、C<undef> が返されます。
正常な C<execute> は、影響を受けた行の数に関係無く、例えそれが
0 であっても(下記を参照)真を返します。
L</RaiseError> を使っていないなら、C<execute>(そして他のほとんどの
DBI メソッド)の戻りステータスをエラーでないかチェックすることは
常に重要です。

=begin original

For a I<non>-C<SELECT> statement, C<execute> returns the number of rows
affected, if known. If no rows were affected, then C<execute> returns
"C<0E0>", which Perl will treat as 0 but will regard as true. Note that it
is I<not> an error for no rows to be affected by a statement. If the
number of rows affected is not known, then C<execute> returns -1.

=end original

I<非> C<SELECT> 文なら、C<execute> は、もしわかれば影響を受けた行の数を
返します。
影響を受けた行が無い場合には、C<execute> は "C<0E0>" を返します。
Perl はこれを 0 として扱いますが、真と判定します。
影響を受けた行が無いこと自体はエラーではないことに注意してください。
影響を受けた行の数がわからなければ、C<execute> は -1 を返します。

=begin original

For C<SELECT> statements, execute simply "starts" the query within the
database engine. Use one of the fetch methods to retrieve the data after
calling C<execute>.  The C<execute> method does I<not> return the number of
rows that will be returned by the query (because most databases can't
tell in advance), it simply returns a true value.

=end original

C<SELECT> 文では execute は問い合わせを単にエンジンで「開始」するだけです。
C<execute> を呼び出した後は、fetch メソッドのどれかを使ってデータを
取り出してください。
C<execute> メソッドは問い合わせによって返される行の数を I<返しません>
(というのもほとんどのエンジンは前もって教えてくれないからです);
それは単に真を返します。

=begin original

You can tell if the statement was a C<SELECT> statement by checking if
C<$sth-E<gt>{NUM_OF_FIELDS}> is greater than zero after calling C<execute>.

=end original

ステートメントがC<SELECT>ステートメントかどうかは、C<$sth-E<gt>{NUM_OF_FIELDS}>がゼロより大きいかどうかをC<execute>の呼び出し後にチェックすることでわかります。
(TBR)

=begin original

If any arguments are given, then C<execute> will effectively call
L</bind_param> for each value before executing the statement.  Values
bound in this way are usually treated as C<SQL_VARCHAR> types unless
the driver can determine the correct type (which is rare), or unless
C<bind_param> (or C<bind_param_inout>) has already been used to
specify the type.

=end original

何か引数が与えられると、C<execute> は、その文を実行する前に、
それぞれについて効率よく L</bind_param> を呼び出します。
このようにして結び付けられた値は、ドライバが正しい型を判定できるか
(判定できることはまれです)、既に C<bind_param>(または
C<bind_param_inout>)が型を特定するために使われていなければ、通常
C<SQL_VARCHAR> タイプとして扱われます。

=begin original

Note that passing C<execute> an empty array is the same as passing no arguments
at all, which will execute the statement with previously bound values.
That's probably not what you want.

=end original

C<execute>に空の配列を渡すことは、引数をまったく渡さないことと同じであることに注意してください。
これにより、以前にバインドされた値を使用して文が実行されます。
それはおそらくあなたが望むものではないでしょう。
(TBR)

=begin original

If execute() is called on a statement handle that's still active
($sth->{Active} is true) then it should effectively call finish()
to tidy up the previous execution results before starting this new
execution.

=end original

execute()がまだアクティブなステートメントハンドルに対して呼び出された場合($sth->{Active}がtrue)、この新しい実行を開始する前に、前の実行結果を整理するためにfinish()を効果的に呼び出す必要があります。
(TBR)

=head3 C<execute_array>

  $tuples = $sth->execute_array(\%attr) or die $sth->errstr;
  $tuples = $sth->execute_array(\%attr, @bind_values) or die $sth->errstr;

  ($tuples, $rows) = $sth->execute_array(\%attr) or die $sth->errstr;
  ($tuples, $rows) = $sth->execute_array(\%attr, @bind_values) or die $sth->errstr;

=begin original

Execute the prepared statement once for each parameter tuple
(group of values) provided either in the @bind_values, or by prior
calls to L</bind_param_array>, or via a reference passed in \%attr.

=end original

@bind_values、以前のL</bind_param_array>の呼び出し、または\%attrで渡された参照によって提供されたパラメータタプル(値のグループ)ごとに、準備された文を1回実行します。
(TBR)

=begin original

When called in scalar context the execute_array() method returns the
number of tuples executed, or C<undef> if an error occurred.  Like
execute(), a successful execute_array() always returns true regardless
of the number of tuples executed, even if it's zero. If there were any
errors the ArrayTupleStatus array can be used to discover which tuples
failed and with what errors.

=end original

スカラーコンテキストで呼び出されると、execute_array()メソッドは実行されたタプルの数を返します。
エラーが発生した場合はC<undef>を返します。
execute()と同様に、成功したexecute_array()は、実行されたタプルの数に関係なく、0であっても常にtrueを返します。
エラーがあった場合は、ArrayTupleStatus配列を使用して、失敗したタプルとエラーを検出できます。
(TBR)

=begin original

When called in list context the execute_array() method returns two scalars;
$tuples is the same as calling execute_array() in scalar context and $rows is
the sum of the number of rows affected for each tuple, if available or
-1 if the driver cannot determine this.
If you are doing an update operation the returned rows affected may not be what
you expect if, for instance, one or more of the tuples affected the same row
multiple times.  Some drivers may not yet support list context, in which case
$rows will be undef, or may not be able to provide the number of rows affected
when performing this batch operation, in which case $rows will be -1.

=end original

リストコンテキストで呼び出されると、execute_array()メソッドは2つのスカラーを返します。
$tuplesは、スカラーコンテキストでexecute_array()を呼び出すのと同じです。
$rowsは、タプルごとに影響を受ける行数の合計です(利用可能な場合)。
ドライバがこれを判断できない場合は-1です。
更新操作を実行している場合、たとえば、1つ以上のタプルが同じ行に複数回影響を受けた場合、影響を受ける返された行は期待どおりでない可能性があります。
一部のドライバは、リストコンテキストをまだサポートしていない可能性があります。
その場合、$rowsはundefになります。
または、このバッチ操作を実行するときに影響を受ける行数を提供できない可能性があります。
その場合、$rowsは-1になります。
(TBR)

=begin original

Bind values for the tuples to be executed may be supplied row-wise
by an C<ArrayTupleFetch> attribute, or else column-wise in the
C<@bind_values> argument, or else column-wise by prior calls to
L</bind_param_array>.

=end original

実行されるタプルのバインド値は、C<ArrayTupleFetch>属性によって行方向に提供されるか、C<@bind_values>引数で列方向に提供されるか、またはL</bind_param_array>への以前の呼び出しによって列方向に提供されます。
(TBR)

=begin original

Where column-wise binding is used (via the C<@bind_values> argument
or calls to bind_param_array()) the maximum number of elements in
any one of the bound value arrays determines the number of tuples
executed. Placeholders with fewer values in their parameter arrays
are treated as if padded with undef (NULL) values.

=end original

(C<@bind_values>引数またはbind_param_array()の呼び出しによって)列単位のバインドが使用される場合、バインド値配列のいずれかの要素の最大数によって、実行されるタプルの数が決定されます。
パラメータ配列の値が少ないプレースホルダは、undef(NULL)値で埋められているものとして扱われます。
(TBR)

=begin original

If a scalar value is bound, instead of an array reference, it is
treated as a I<variable> length array with all elements having the
same value. It does not influence the number of tuples executed,
so if all bound arrays have zero elements then zero tuples will
be executed. If I<all> bound values are scalars then one tuple
will be executed, making execute_array() act just like execute().

=end original

スカラー値がバインドされている場合、配列参照ではなく、すべての要素が同じ値を持つI<variable>length配列として扱われます。
実行されるタプルの数には影響しないため、バインドされたすべての配列の要素がゼロの場合は、ゼロのタプルが実行されます。
I<all>バインド値がスカラーの場合は、1つのタプルが実行され、execute_array()はexecute()と同様に動作します。
(TBR)

=begin original

The C<ArrayTupleFetch> attribute can be used to specify a reference
to a subroutine that will be called to provide the bind values for
each tuple execution. The subroutine should return an reference to
an array which contains the appropriate number of bind values, or
return an undef if there is no more data to execute.

=end original

C<ArrayTupleFetch>属性を使用して、各タプル実行のバインド値を提供するために呼び出されるサブルーチンへの参照を指定できます。
サブルーチンは、適切な数のバインド値を含む配列への参照を返すか、実行するデータがない場合はundefを返す必要があります。
(TBR)

=begin original

As a convenience, the C<ArrayTupleFetch> attribute can also be
used to specify a statement handle. In which case the fetchrow_arrayref()
method will be called on the given statement handle in order to
provide the bind values for each tuple execution.

=end original

便宜上、C<ArrayTupleFetch>属性を使用してステートメントハンドルを指定することもできます。
その場合、指定されたステートメントハンドルに対してfetchrow_arrayref()メソッドが呼び出され、各タプル実行のバインド値が提供されます。
(TBR)

=begin original

The values specified via bind_param_array() or the @bind_values
parameter may be either scalars, or arrayrefs.  If any C<@bind_values>
are given, then C<execute_array> will effectively call L</bind_param_array>
for each value before executing the statement.  Values bound in
this way are usually treated as C<SQL_VARCHAR> types unless the
driver can determine the correct type (which is rare), or unless
C<bind_param>, C<bind_param_inout>, C<bind_param_array>, or
C<bind_param_inout_array> has already been used to specify the type.
See L</bind_param_array> for details.

=end original

bind_param_array()または@bind_valuesパラメータを介して指定された値は、スカラーまたはarrayrefsのいずれかです。
C<@bind_values>が指定された場合、C<execute_array>は文を実行する前に各値に対してL</bind_param_array>を効果的に呼び出します。
この方法でバインドされた値は、ドライバが正しい型を判別できない限り(まれです)、またはC<bind_param>、C<bind_param_inout>、C<bind_param_array>、またはC<bind_param_inout_array>がすでに型の指定に使用されていない限り、通常はC<SQL_VARCHAR>型として扱われます。
詳細はL</bind_param_array>を参照してください。
(TBR)

=begin original

The C<ArrayTupleStatus> attribute can be used to specify a
reference to an array which will receive the execute status of each
executed parameter tuple. Note the C<ArrayTupleStatus> attribute was
mandatory until DBI 1.38.

=end original

C<ArrayTupleStatus>属性は、実行された各パラメータタプルの実行ステータスを受け取る配列への参照を指定するために使用できます。
DBI 1.38までは、C<ArrayTupleStatus>属性は必須でした。
(TBR)

=begin original

For tuples which are successfully executed, the element at the same
ordinal position in the status array is the resulting rowcount.
If the execution of a tuple causes an error, then the corresponding
status array element will be set to a reference to an array containing
the error code and error string set by the failed execution.

=end original

正常に実行されたタプルの場合、ステータス配列内の同じ順序位置にある要素が結果の行カウントになります。
タプルの実行によってエラーが発生した場合、対応するステータス配列要素は、失敗した実行によって設定されたエラーコードおよびエラー文字列を含む配列への参照に設定されます。
(TBR)

=begin original

If B<any> tuple execution returns an error, C<execute_array> will
return C<undef>. In that case, the application should inspect the
status array to determine which parameter tuples failed.
Some databases may not continue executing tuples beyond the first
failure. In this case the status array will either hold fewer
elements, or the elements beyond the failure will be undef.

=end original

B<any>タプルの実行でエラーが返された場合、C<execute_array>はC<undef>を返します。
その場合、アプリケーションはステータス配列を検査して、どのパラメータタプルが失敗したかを判別する必要があります。
一部のデータベースでは、最初の失敗以降、タプルの実行が続行されない場合があります。
この場合、ステータス配列に保持される要素が少なくなるか、失敗以降の要素がundefになります。
(TBR)

=begin original

If all parameter tuples are successfully executed, C<execute_array>
returns the number tuples executed.  If no tuples were executed,
then execute_array() returns "C<0E0>", just like execute() does,
which Perl will treat as 0 but will regard as true.

=end original

すべてのパラメータタプルが正常に実行された場合、C<execute_array>は、実行されたタプルの数を戻します。
タプルが実行されなかった場合、execute_array()は、execute()と同様に"C<0E0>"を戻します。
これは、Perlでは0として処理されますが、trueとみなされます。
(TBR)

=begin original

For example:

=end original

例えば:

  $sth = $dbh->prepare("INSERT INTO staff (first_name, last_name) VALUES (?, ?)");
  my $tuples = $sth->execute_array(
      { ArrayTupleStatus => \my @tuple_status },
      \@first_names,
      \@last_names,
  );
  if ($tuples) {
      print "Successfully inserted $tuples records\n";
  }
  else {
      for my $tuple (0..@last_names-1) {
          my $status = $tuple_status[$tuple];
          $status = [0, "Skipped"] unless defined $status;
          next unless ref $status;
          printf "Failed to insert (%s, %s): %s\n",
              $first_names[$tuple], $last_names[$tuple], $status->[1];
      }
  }

=begin original

Support for data returning statements such as SELECT is driver-specific
and subject to change. At present, the default implementation
provided by DBI only supports non-data returning statements.

=end original

SELECTなどのデータを返すステートメントのサポートはドライバ固有であり、変更される可能性があります。
現在、DBIによって提供されるデフォルトの実装では、データを返さないステートメントのみがサポートされています。
(TBR)

=begin original

Transaction semantics when using array binding are driver and
database specific.  If C<AutoCommit> is on, the default DBI
implementation will cause each parameter tuple to be individually
committed (or rolled back in the event of an error). If C<AutoCommit>
is off, the application is responsible for explicitly committing
the entire set of bound parameter tuples.  Note that different
drivers and databases may have different behaviours when some
parameter tuples cause failures. In some cases, the driver or
database may automatically rollback the effect of all prior parameter
tuples that succeeded in the transaction; other drivers or databases
may retain the effect of prior successfully executed parameter
tuples. Be sure to check your driver and database for its specific
behaviour.

=end original

配列バインドを使用する場合のトランザクションセマンティクスは、ドライバおよびデータベースに固有です。
C<AutoCommit>がオンの場合、デフォルトのDBI実装では、各パラメータタプルが個別にコミット(またはエラー発生時にロールバック)されます。
C<AutoCommit>がオフの場合、バインドされたパラメータタプルのセット全体を明示的にコミットするのはアプリケーションの責任です。
一部のパラメータタプルで障害が発生した場合、異なるドライバおよびデータベースでは動作が異なる可能性があることに注意してください。
場合によっては、ドライバまたはデータベースは、トランザクションで成功した以前のすべてのパラメータタプルの影響を自動的にロールバックする可能性があります。
他のドライバまたはデータベースは、以前に正常に実行されたパラメータタプルの影響を保持する可能性があります。
ドライバおよびデータベースの特定の動作を必ず確認してください。
(TBR)

=begin original

Note that, in general, performance will usually be better with
C<AutoCommit> turned off, and using explicit C<commit> after each
C<execute_array> call.

=end original

一般に、C<AutoCommit>をオフにし、各C<execute_array>呼び出しの後に明示的にC<commit>を使用すると、パフォーマンスが向上することに注意してください。
(TBR)

=begin original

The C<execute_array> method was added in DBI 1.22, and ArrayTupleFetch
was added in 1.36.

=end original

C<execute_array> メソッドは DBI 1.22 で追加され、ArrayTupleFetch は
1.36 で追加されました。

=head3 C<execute_for_fetch>

  $tuples = $sth->execute_for_fetch($fetch_tuple_sub);
  $tuples = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status);

  ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub);
  ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status);

=begin original

The execute_for_fetch() method is used to perform bulk operations
and is most often used via the execute_array() method, not directly.

=end original

execute_for_fetch()メソッドは、バルクオペレーションを実行するために使用され、ほとんどの場合、直接ではなくexecute_array()メソッドを介して使用されます。
(TBR)

=begin original

The fetch subroutine, referenced by $fetch_tuple_sub, is expected
to return a reference to an array (known as a 'tuple') or undef.

=end original

$fetch_tuple_subによって参照されるフェッチサブルーチンは、配列(「タプル」と呼ばれる)またはundefへの参照を返すことが期待されています。
(TBR)

=begin original

The execute_for_fetch() method calls $fetch_tuple_sub, without any
parameters, until it returns a false value. Each tuple returned is
used to provide bind values for an $sth->execute(@$tuple) call.

=end original

execute_for_fetch()メソッドは、偽の値を返すまで、パラメータなしで$fetch_tuple_subを呼び出します。
返された各タプルは、$sth->execute(@$tuple)呼び出しのバインド値を提供するために使用されます。
(TBR)

=begin original

In scalar context execute_for_fetch() returns C<undef> if there were any
errors and the number of tuples executed otherwise. Like execute() and
execute_array() a zero is returned as "0E0" so execute_for_fetch() is
only false on error.  If there were any errors the @tuple_status array
can be used to discover which tuples failed and with what errors.

=end original

スカラーコンテキストでは、execute_for_fetch()は、エラーがあった場合はC<undef>を返し、それ以外の場合は実行されたタプルの数を返します。
execute()およびexecute_array()と同様に、ゼロは「0E0」として返されるため、execute_for_fetch()はエラーの場合にのみfalseになります。
エラーがあった場合は??????@tuple_status配列を使用して、失敗したタプルとエラーを検出できます。
(TBR)

=begin original

When called in list context execute_for_fetch() returns two scalars;
$tuples is the same as calling execute_for_fetch() in scalar context and $rows is
the sum of the number of rows affected for each tuple, if available or -1
if the driver cannot determine this.
If you are doing an update operation the returned rows affected may not be what
you expect if, for instance, one or more of the tuples affected the same row
multiple times.  Some drivers may not yet support list context, in which case
$rows will be undef, or may not be able to provide the number of rows affected
when performing this batch operation, in which case $rows will be -1.

=end original

リストコンテキストで呼び出された場合、execute_for_fetch()は2つのスカラーを返します。
$tuplesは、スカラーコンテキストでexecute_for_fetch()を呼び出すのと同じです。
$rowsは、タプルごとに影響を受ける行数の合計です(利用可能な場合)。
ドライバがこれを判断できない場合は-1です。
更新操作を実行している場合、たとえば、1つ以上のタプルが同じ行に複数回影響を受けた場合、影響を受ける返された行は期待したものではない可能性があります。
一部のドライバは、リストコンテキストをまだサポートしていない可能性があります。
その場合、$rowsはundefになります。
または、このバッチ操作の実行時に影響を受ける行数を提供できない可能性があります。
その場合、$rowsは-1になります。
(TBR)

=begin original

If \@tuple_status is passed then the execute_for_fetch method uses
it to return status information. The tuple_status array holds one
element per tuple. If the corresponding execute() did not fail then
the element holds the return value from execute(), which is typically
a row count. If the execute() did fail then the element holds a
reference to an array containing ($sth->err, $sth->errstr, $sth->state).

=end original

\@tuple_statusが渡された場合、execute_for_fetchメソッドはそれを使用してステータス情報を返します。
tuple_status配列は、タプルごとに1つの要素を保持します。
対応するexecute()が失敗しなかった場合、要素はexecute()からの戻り値(通常は行カウント)を保持します。
execute()が失敗した場合、要素は($sth->err,$sth->errstr,$sth->state)を含む配列への参照を保持します。
(TBR)

=begin original

If the driver detects an error that it knows means no further tuples can be
executed then it may return, with an error status, even though $fetch_tuple_sub
may still have more tuples to be executed.

=end original

ドライバがエラーを検出し、それ以上タプルを実行できないことがわかった場合、$fetch_tuple_subがまだ実行すべきタプルを保持していても、エラーステータスを返します。
(TBR)

=begin original

Although each tuple returned by $fetch_tuple_sub is effectively used
to call $sth->execute(@$tuple_array_ref) the exact timing may vary.
Drivers are free to accumulate sets of tuples to pass to the
database server in bulk group operations for more efficient execution.
However, the $fetch_tuple_sub is specifically allowed to return
the same array reference each time (which is what fetchrow_arrayref()
usually does).

=end original

$fetch_tuple_subによって返される各タプルは、$sth->execute(@$tuple_array_ref)を呼び出すために効果的に使用されますが、正確なタイミングは異なる場合があります。
ドライバは、より効率的な実行のために、バルクグループ操作でデータベースサーバに渡すタプルのセットを自由に蓄積できます。
ただし、$fetch_tuple_subは、毎回同じ配列参照を返すことができます(これはfetchrow_arrayref()が通常行うことです)。
(TBR)

=begin original

For example:

=end original

例えば:

  my $sel = $dbh1->prepare("select foo, bar from table1");
  $sel->execute;

  my $ins = $dbh2->prepare("insert into table2 (foo, bar) values (?,?)");
  my $fetch_tuple_sub = sub { $sel->fetchrow_arrayref };

  my @tuple_status;
  $rc = $ins->execute_for_fetch($fetch_tuple_sub, \@tuple_status);
  my @errors = grep { ref $_ } @tuple_status;

=begin original

Similarly, if you already have an array containing the data rows
to be processed you'd use a subroutine to shift off and return
each array ref in turn:

=end original

同様に、処理されるデータ行を含む配列がすでにある場合は、サブルーチンを使用してシフトオフし、各配列refを順番に返します。
(TBR)

  $ins->execute_for_fetch( sub { shift @array_of_arrays }, \@tuple_status);

=begin original

The C<execute_for_fetch> method was added in DBI 1.38.

=end original

C<execute_for_fetch> メソッドは DBI 1.38 で追加されました。

=head3 C<fetchrow_arrayref>

  $ary_ref = $sth->fetchrow_arrayref;
  $ary_ref = $sth->fetch;    # alias

=begin original

Fetches the next row of data and returns a reference to an array
holding the field values.  Null fields are returned as C<undef>
values in the array.
This is the fastest way to fetch data, particularly if used with
C<$sth-E<gt>bind_columns>.

=end original

次のデータの行を取り出し、フィールドの値をもった配列へのリファレンスを
返します。
Null のフィールドは C<undef> で返されます。
特に C<$sth-E<gt>bind_columns> を使っているならば、これがデータを取り出す
最も速い方法です。

=begin original

If there are no more rows or if an error occurs, then C<fetchrow_arrayref>
returns an C<undef>. You should check C<$sth-E<gt>err> afterwards (or use the
C<RaiseError> attribute) to discover if the C<undef> returned was due to an
error.

=end original

もう行が無いか、エラーが発生すると、C<fetchrow_arrayref> は
C<undef> を返します。
後で返された C<undef> がエラーによるものかどうかを見るために、
C<$sth-E<gt>err> をチェックするべきです(あるいは C<RaiseError> 属性を
使うか)。

=begin original

Note that the same array reference is returned for each fetch, so don't
store the reference and then use it after a later fetch.  Also, the
elements of the array are also reused for each row, so take care if you
want to take a reference to an element. See also L</bind_columns>.

=end original

現状では、データを取り出すたびに同じ配列リファレンスが返されることが
あることに注意してください。
そのためリファレンスを取っておいて、データの取り出しを進めた後で、
使わないでください。
同様に配列の要素も各行で再使用されます。
要素のリファレンスを取得したいならば、注意してください。
L</bind_columns> もご覧ください。

=head3 C<fetchrow_array>

 @ary = $sth->fetchrow_array;

=begin original

An alternative to C<fetchrow_arrayref>. Fetches the next row of data
and returns it as a list containing the field values.  Null fields
are returned as C<undef> values in the list.

=end original

C<fetchrow_arrayref> の代用品です。
次のデータ行を取り出し、フィールドの値を持った配列を返します。
Null のフィールドはリストの中の C<undef> 値として返されます。

=begin original

If there are no more rows or if an error occurs, then C<fetchrow_array>
returns an empty list. You should check C<$sth-E<gt>err> afterwards (or use
the C<RaiseError> attribute) to discover if the empty list returned was
due to an error.

=end original

もう行が無いか、エラーが発生すると、C<fetchrow_array> は空リストを返します。
後で返された空リストがエラーによるものかどうかを見るために、
C<$sth-E<gt>err> をチェックするべきです(あるいは C<RaiseError> 属性を
使うか)。

=begin original

If called in a scalar context for a statement handle that has more
than one column, it is undefined whether the driver will return
the value of the first column or the last. So don't do that.
Also, in a scalar context, an C<undef> is returned if there are no
more rows or if an error occurred. That C<undef> can't be distinguished
from an C<undef> returned because the first field value was NULL.
For these reasons you should exercise some caution if you use
C<fetchrow_array> in a scalar context.

=end original

複数の列を持つステートメントハンドルに対してスカラーコンテキストで呼び出された場合、ドライバが最初の列の値を返すのか最後の列の値を返すのかは定義されていません。
そのため、そうしないでください。
また、スカラーコンテキストでは、行がなくなった場合やエラーが発生した場合にC<undef>が返されます。
このC<undef>は、最初のフィールド値がNULLであったために返されたC<undef>とは区別できません。
これらの理由から、スカラーコンテキストでC<fetchrow_array>を使用する場合は注意が必要です。
(TBR)

=head3 C<fetchrow_hashref>

 $hash_ref = $sth->fetchrow_hashref;
 $hash_ref = $sth->fetchrow_hashref($name);

=begin original

An alternative to C<fetchrow_arrayref>. Fetches the next row of data
and returns it as a reference to a hash containing field name and field
value pairs.  Null fields are returned as C<undef> values in the hash.

=end original

C<fetchrow_arrayref> の代用品です。
次のデータ行を取り出し、フィールドの名前と値のペアを持ったハッシュへの
リファレンスを返します。
NULL フィールドはハッシュのなかの C<undef> として返されます。

=begin original

If there are no more rows or if an error occurs, then C<fetchrow_hashref>
returns an C<undef>. You should check C<$sth-E<gt>err> afterwards (or use the
C<RaiseError> attribute) to discover if the C<undef> returned was due to an
error.

=end original

もう行が無いか、エラーが発生すると、C<fetchrow_hashref> は C<undef> を
返します。
後で返された C<undef> がエラーによるものかどうかを見るために、
C<$sth-E<gt>err> をチェックするべきです(あるいは C<RaiseError> 属性を
使うか)。

=begin original

The optional C<$name> parameter specifies the name of the statement handle
attribute. For historical reasons it defaults to "C<NAME>", however using
either "C<NAME_lc>" or "C<NAME_uc>" is recommended for portability.

=end original

オプションの C<$name> パラメータには、文ハンドル属性の名前を
指定します。
移植性の面からは "C<NAME_lc>" や "C<NAME_uc>" を使うことが勧められるのですが、
歴史的な理由から、デフォルトは "C<NAME>" になります。

=begin original

The keys of the hash are the same names returned by C<$sth-E<gt>{$name}>. If
more than one field has the same name, there will only be one entry in the
returned hash for those fields, so statements like "C<select foo, foo from bar>"
will return only a single key from C<fetchrow_hashref>. In these cases use
column aliases or C<fetchrow_arrayref>.  Note that it is the database server
(and not the DBD implementation) which provides the I<name> for fields
containing functions like "C<count(*)>" or "C<max(c_foo)>" and they may clash
with existing column names (most databases don't care about duplicate column
names in a result-set). If you want these to return as unique names that are
the same across databases, use I<aliases>, as in "C<select count(*) as cnt>"
or "C<select max(c_foo) mx_foo, ...>" depending on the syntax your database
supports.

=end original

ハッシュのキーは、C<$sth-E<gt>{$name}>によって返される名前と同じです。
複数のフィールドが同じ名前を持つ場合、それらのフィールドに対して返されるハッシュには1つのエントリしかないため、"C<select foo, foo from bar>"のようなステートメントは、C<fetchrow_hashref>から1つのキーのみを返します。
このような場合は、列の別名またはC<fetchrow_arrayref>を使用します。
"C<count(*)>"または"C<max(c_foo)>"のような関数を含むフィールドにI<name>を提供するのはデータベースサーバ(DBD実装ではない)であり、既存の列名と競合する可能性があることに注意してください(ほとんどのデータベースでは、結果セット内の列名の重複は考慮されません)。
これらをデータベース間で同じ一意の名前として返したい場合は、データベースがサポートする構文に応じて、"C<select count(*) as cnt>"または"C<select max(c_foo)mx_foo,.>"のようにI<aliases>を使用します。
(TBR)

=begin original

Because of the extra work C<fetchrow_hashref> and Perl have to perform, it
is not as efficient as C<fetchrow_arrayref> or C<fetchrow_array>.

=end original

C<fetchrow_hashref> は追加の動作をし、さらに Perl が動かなければならないので、
C<fetchrow_arrayref> や C<fetchrow_array> ほど効率よくありません。

=begin original

By default a reference to a new hash is returned for each row.
It is likely that a future version of the DBI will support an
attribute which will enable the same hash to be reused for each
row. This will give a significant performance boost, but it won't
be enabled by default because of the risk of breaking old code.

=end original

デフォルトでは行毎に新しいハッシュリファレンスが返されます。
将来のバージョンの DBI では行毎に同じハッシュを再利用することを有効にする
新しい属性に対応する予定です。
これは大きく性能を改善させますが、古いコードを壊すリスクがあるので
デフォルトでは有効にならない予定です。

=head3 C<fetchall_arrayref>

  $tbl_ary_ref = $sth->fetchall_arrayref;
  $tbl_ary_ref = $sth->fetchall_arrayref( $slice );
  $tbl_ary_ref = $sth->fetchall_arrayref( $slice, $max_rows  );

=begin original

The C<fetchall_arrayref> method can be used to fetch all the data to be
returned from a prepared and executed statement handle. It returns a
reference to an array that contains one reference per row.

=end original

C<fetchall_arrayref> メソッドは prepare され、execute された
文ハンドルから、返されるべきすべてのデータを取り出すために
使います。
1 行につき一つのリファレンスが入っている配列へのリファレンスを返します。

=begin original

If there are no rows to return, C<fetchall_arrayref> returns a reference
to an empty array. If an error occurs, C<fetchall_arrayref> returns the
data fetched thus far, which may be none.  You should check C<$sth-E<gt>err>
afterwards (or use the C<RaiseError> attribute) to discover if the data is
complete or was truncated due to an error.

=end original

もう行が無いかエラーが発生すると、C<fetchall_arrayref> は空の配列への
リファレンスを返します。
エラーが発生したら、C<fetchall_arrayref> はデータを取り出せたところまで
返します(これは空であるかもしれません)。
データが完全であるか、エラーにより切り捨てられたかを見るために、後で
C<$sth-E<gt>err> をチェックするべきです(あるいは C<RaiseError> 属性を
使うか)。

=begin original

If $slice is an array reference, C<fetchall_arrayref> uses L</fetchrow_arrayref>
to fetch each row as an array ref. If the $slice array is not empty
then it is used as a slice to select individual columns by perl array
index number (starting at 0, unlike column and parameter numbers which
start at 1).

=end original

$slice が配列リファレンスなら、C<fetchall_arrayref> は
L</fetchrow_arrayref> を使って配列のリファレンスで各行を取り出します。
もし $slice の配列が空でなければ、perl 配列インデックス番号
(0 から始まります; 1 から始まる列やパラメータの番号とは違います)
によってそれぞれの列を選択し切り出すために使われます。

=begin original

With no parameters, or if $slice is undefined, C<fetchall_arrayref>
acts as if passed an empty array ref.

=end original

パラメータがないか、$slice が未定義値なら、C<fetchall_arrayref> は
空の配列リファレンスが渡されたように動きます。

=begin original

If $slice is a hash reference, C<fetchall_arrayref> uses L</fetchrow_hashref>
to fetch each row as a hash reference. If the $slice hash is empty then
fetchrow_hashref() is simply called in a tight loop and the keys in the hashes
have whatever name lettercase is returned by default from fetchrow_hashref.
(See L</FetchHashKeyName> attribute.) If the $slice hash is not
empty, then it is used as a slice to select individual columns by
name.  The values of the hash should be set to 1.  The key names
of the returned hashes match the letter case of the names in the
parameter hash, regardless of the L</FetchHashKeyName> attribute.

=end original

$slice がハッシュのリファレンスなら、C<fetchall_arrayref> は
L</fetchrow_hashref> を使って、各行をハッシュのリファレンスで取り出します。
$slice ハッシュが空なら、C<fetchrow_hashref> は単にきついループで
呼ばれるだけで、ハッシュのキーは fetchrow_hashref からのデフォルトで
返されるすべての小文字の名前を持つだけです
(L</FetchHashKeyName> 属性をご覧ください)。
$slice ハッシュが空でなければ、名前で個々の列を選択するためのスライスとして
使われます。
ハッシュの値は 1 に設定されるべきです。
かえされたハッシュのキー名は、L</FetchHashKeyName> 属性にかかわらず
パラメータハッシュの名前の小文字とマッチングされます。

=begin original

For example, to fetch just the first column of every row:

=end original

例えば、各行の先頭の列だけを取り出したい場合は:

  $tbl_ary_ref = $sth->fetchall_arrayref([0]);

=begin original

To fetch the second to last and last column of every row:

=end original

各行の一番後ろ、その直前の列を取り出すには:

  $tbl_ary_ref = $sth->fetchall_arrayref([-2,-1]);

=begin original

To fetch all fields of every row as a hash ref:

=end original

各行をハッシュリファレンスとして取り出すためには:

  $tbl_ary_ref = $sth->fetchall_arrayref({});

=begin original

To fetch only the fields called "foo" and "bar" of every row as a hash ref
(with keys named "foo" and "BAR"):

=end original

("foo" および "BAR" というキー名で) 各行の "foo" と "bar" という
フィールドだけを取り出すためには:

  $tbl_ary_ref = $sth->fetchall_arrayref({ foo=>1, BAR=>1 });

=begin original

The first two examples return a reference to an array of array refs.
The third and forth return a reference to an array of hash refs.

=end original

最初の二つの例では、配列リファレンスの配列へのリファレンスを返します。
3 番目と 4 番目の例はハッシュリファレンスの配列へのリファレンスを返します。

=begin original

If $max_rows is defined and greater than or equal to zero then it
is used to limit the number of rows fetched before returning.
fetchall_arrayref() can then be called again to fetch more rows.
This is especially useful when you need the better performance of
fetchall_arrayref() but don't have enough memory to fetch and return
all the rows in one go.

=end original

$max_rowsが定義されていて、0以上の場合は、返される前にフェッチされるローの数を制限するために使用されます。
その後、fetchall_arrayref()を再度呼び出して、さらにローをフェッチすることができます。
これは、fetchall_arrayref()のパフォーマンスを向上させる必要があるが、すべてのローを一度にフェッチして返すための十分なメモリがない場合に特に便利です。
(TBR)

=begin original

Here's an example (assumes RaiseError is enabled):

=end original

以下は例です(RaiseError が有効であることを仮定しています):

  my $rows = []; # cache for batches of rows
  while( my $row = ( shift(@$rows) || # get row from cache, or reload cache:
                     shift(@{$rows=$sth->fetchall_arrayref(undef,10_000)||[]}) )
  ) {
    ...
  }

=begin original

That I<might> be the fastest way to fetch and process lots of rows using the DBI,
but it depends on the relative cost of method calls vs memory allocation.

=end original

これは DBI を使ってたくさんの列をフェッチして処理するための最速の方法
I<かもしれません> が、メソッド呼び出し対メモリ割り当ての相対コストに
依存します。

=begin original

A standard C<while> loop with column binding is often faster because
the cost of allocating memory for the batch of rows is greater than
the saving by reducing method calls. It's possible that the DBI may
provide a way to reuse the memory of a previous batch in future, which
would then shift the balance back towards fetchall_arrayref().

=end original

列バインドを使用した標準のC<while>ループは、多くの場合、より高速です。
これは、行のバッチにメモリを割り当てるコストが、メソッド呼び出しを削減することによる節約よりも大きいためです。
DBIは、将来、以前のバッチのメモリを再利用する方法を提供する可能性があり、それによって、残りの部分がfetchall_arrayref()にシフトバックされます。
(TBR)

=head3 C<fetchall_hashref>

  $hash_ref = $sth->fetchall_hashref($key_field);

=begin original

The C<fetchall_hashref> method can be used to fetch all the data to be
returned from a prepared and executed statement handle. It returns a reference
to a hash containing a key for each distinct value of the $key_field column
that was fetched. For each key the corresponding value is a reference to a hash
containing all the selected columns and their values, as returned by
C<fetchrow_hashref()>.

=end original

C<fetchall_hashref>メソッドを使用すると、準備され実行された文ハンドルから戻されるすべてのデータをフェッチできます。
このメソッドは、フェッチされた$key_field列の個別の値ごとにキーを含むハッシュへの参照を戻します。
各キーに対応する値は、選択されたすべての列とその値を含むハッシュへの参照であり、C<fetchrow_hashref()>によって戻されます。
(TBR)

=begin original

If there are no rows to return, C<fetchall_hashref> returns a reference
to an empty hash. If an error occurs, C<fetchall_hashref> returns the
data fetched thus far, which may be none.  You should check
C<$sth-E<gt>err> afterwards (or use the C<RaiseError> attribute) to
discover if the data is complete or was truncated due to an error.

=end original

返される行がない場合、C<fetchall_hashref>は空のハッシュへの参照を返します。
エラーが発生した場合、C<fetchall_hashref>はそれまでにフェッチされたデータを返しますが、何も返されない場合もあります。
後でC<$sth-E<gt>err>をチェックして(またはC<RaiseError>属性を使用して)、データが完全であるか、エラーのために切り捨てられたかを検出する必要があります。
(TBR)

=begin original

The $key_field parameter provides the name of the field that holds the
value to be used for the key for the returned hash.  For example:

=end original

$key_field パラメータは返されたハッシュのキーのために使われる値を
保持するフィールド名を提供します。
例えば:

  $dbh->{FetchHashKeyName} = 'NAME_lc';
  $sth = $dbh->prepare("SELECT FOO, BAR, ID, NAME, BAZ FROM TABLE");
  $sth->execute;
  $hash_ref = $sth->fetchall_hashref('id');
  print "Name for id 42 is $hash_ref->{42}->{name}\n";

=begin original

The $key_field parameter can also be specified as an integer column
number (counting from 1).  If $key_field doesn't match any column in
the statement, as a name first then as a number, then an error is
returned.

=end original

$key_fieldパラメータは、整数の列番号(1から数える)として指定することもできます。
$key_fieldがステートメント内のどの列とも一致しない場合は、最初に名前、次に番号として、エラーが返されます。
(TBR)

=begin original

For queries returning more than one 'key' column, you can specify
multiple column names by passing $key_field as a reference to an
array containing one or more key column names (or index numbers).
For example:

=end original

複数の'key'列を返すクエリの場合、1つ以上のキー列名(またはインデックス番号)を含む配列への参照として$key_fieldを渡すことにより、複数の列名を指定できます。
次に例を示します。
(TBR)

  $sth = $dbh->prepare("SELECT foo, bar, baz FROM table");
  $sth->execute;
  $hash_ref = $sth->fetchall_hashref( [ qw(foo bar) ] );
  print "For foo 42 and bar 38, baz is $hash_ref->{42}->{38}->{baz}\n";

=begin original

The fetchall_hashref() method is normally used only where the key
fields values for each row are unique.  If multiple rows are returned
with the same values for the key fields then later rows overwrite
earlier ones.

=end original

fetchall_hashref()メソッドは、通常、各行のキーフィールド値が一意である場合にのみ使用されます。
キーフィールドに同じ値を持つ複数の行が返された場合、後の行が前の行を上書きします。
(TBR)

=head3 C<finish>

  $rc  = $sth->finish;

=begin original

Indicate that no more data will be fetched from this statement handle
before it is either executed again or destroyed.  You almost certainly
do I<not> need to call this method.

=end original

もう一度 execute されるか、破壊されるまで、この文ハンドルからは
もうデータが取り出されないことを示します。
ほぼ確実に、このメソッドを呼び出す必要は I<ありません>。

=begin original

Adding calls to C<finish> after loop that fetches all rows is a common mistake,
don't do it, it can mask genuine problems like uncaught fetch errors.

=end original

全ての行をフェッチしたループの後に C<finish> 呼び出しを追加するのは
よくある間違いです; 捕捉されていないフェッチのエラーのような本当の問題を
隠してしまうかもしれないので、そうしてはいけません。

=begin original

When all the data has been fetched from a C<SELECT> statement, the driver will
automatically call C<finish> for you. So you should I<not> call it explicitly
I<except> when you know that you've not fetched all the data from a statement
handle I<and> the handle won't be destroyed soon.

=end original

すべてのデータが C<SELECT> 文から取り出されたら、ドライバは
自動的にあなたに代って C<finish> します。
そのため、文ハンドルから全てのデータを取り出しておらず、
I<かつ> ハンドルがすぐには破壊されない場合 I<以外は>
これを明示的に呼び出すべきでは I<ありません>。

=begin original

The most common example is when you only want to fetch just one row,
but in that case the C<selectrow_*> methods are usually better anyway.

=end original

もっともよくある例は、たった 1 行だけをフェッチしたいだけの場合ですが、
その場合は C<selectrow_*> メソッドの方が普通は優れています。

=begin original

Consider a query like:

=end original

以下のような問い合わせを考えてみてください:

  SELECT foo FROM table WHERE bar=? ORDER BY baz

=begin original

on a very large table. When executed, the database server will have to use
temporary buffer space to store the sorted rows. If, after executing
the handle and selecting just a few rows, the handle won't be re-executed for
some time and won't be destroyed, the C<finish> method can be used to tell
the server that the buffer space can be freed.

=end original

これをとても大きなテーブルに対して行います。
実行されるとデータベースサーバは一時的なバッファ領域をソートされた行を
格納するために使わなければなりません。
もし実行し、数行選択した後で、しばらくハンドルが再実行されなかったり、
破壊されないならば、C<finish> メソッドによってサーバにバッファ領域を
解放することができることを教えることができます。

=begin original

Calling C<finish> resets the L</Active> attribute for the statement.  It
may also make some statement handle attributes (such as C<NAME> and C<TYPE>)
unavailable if they have not already been accessed (and thus cached).

=end original

C<finish> を呼び出すと、その文の L</Active> 属性は
リセットされます。
(C<NAME> や C<TYPE> のような)他の文ハンドル属性のいくつかも、
既にアクセスされて(そしてキャッシュされて)いるのでなければ、
使用できなくなるかもしれません。

=begin original

The C<finish> method does not affect the transaction status of the
database connection.  It has nothing to do with transactions. It's mostly an
internal "housekeeping" method that is rarely needed.
See also L</disconnect> and the L</Active> attribute.

=end original

C<finish> メソッドはデータベース接続のトランザクションの状態にはなにも
影響を与えません。
トランザクションとは無関係です。
これはほとんど内部の「家事的(='housekeeping')」メソッドで、あまり
必要なことはありません。
L</disconnect> と L</Active> 属性もご覧ください。

=begin original

The C<finish> method should have been called C<discard_pending_rows>.

=end original

C<finish> メソッドは C<discard_pending_rows> と呼ばれるべきでした。

=head3 C<rows>

  $rv = $sth->rows;

=begin original

Returns the number of rows affected by the last row affecting command,
or -1 if the number of rows is not known or not available.

=end original

最後のコマンドにより影響を受けた行数を返します。
不明または使用不能の場合は -1 になります。 

=begin original

Generally, you can only rely on a row count after a I<non>-C<SELECT>
C<execute> (for some specific operations like C<UPDATE> and C<DELETE>), or
after fetching all the rows of a C<SELECT> statement.

=end original

通常、行カウントは I<非> C<SELECT> (C<UPDATE> や C<DELETE> のような
特定の操作)の C<execute> または、C<SELECT> 文のすべての行を
取り出した後にしか、信用できません。

=begin original

For C<SELECT> statements, it is generally not possible to know how many
rows will be returned except by fetching them all.  Some drivers will
return the number of rows the application has fetched so far, but
others may return -1 until all rows have been fetched.  So use of the
C<rows> method or C<$DBI::rows> with C<SELECT> statements is not
recommended.

=end original

C<SELECT> 文では、通常、何行返ってくるのかは、すべてを
取り出すまではわかりません。
ドライバによってはそれまでに取得した行数を返すものもありますが、
すべての行が取り出されるまでは -1 を返すものもあります。
そのため C<SELECT> 文に C<rows> メソッドや C<$DBI::rows> を
使うことはお勧めできません。

=begin original

One alternative method to get a row count for a C<SELECT> is to execute a
"SELECT COUNT(*) FROM ..." SQL statement with the same "..." as your
query and then fetch the row count from that.

=end original

C<SELECT> の行カウントを得るための代わりの方法の一つは、
"SELECT COUNT(*) FROM ..." 文を、"..."をあなたの問い合わせと
同じにして実行し、それから行数を取り出すことです。

=head3 C<bind_col>

  $rc = $sth->bind_col($column_number, \$var_to_bind);
  $rc = $sth->bind_col($column_number, \$var_to_bind, \%attr );
  $rc = $sth->bind_col($column_number, \$var_to_bind, $bind_type );

=begin original

Binds a Perl variable and/or some attributes to an output column
(field) of a C<SELECT> statement.  Column numbers count up from 1.
You do not need to bind output columns in order to fetch data.
For maximum portability between drivers, bind_col() should be called
after execute() and not before.
See also C<bind_columns> for an example.

=end original

Perl変数または属性(あるいはその両方)をC<SELECT>ステートメントの出力列(フィールド)にバインドします。
列番号は1からカウントされます。
データをフェッチするために出力列をバインドする必要はありません。
ドライバ間の移植性を最大にするために、bind_col()はexecute()の前ではなく後に呼び出す必要があります。
例については、C<bind_columns>も参照してください。
(TBR)

=begin original

The binding is performed at a low level using Perl aliasing.
Whenever a row is fetched from the database $var_to_bind appears
to be automatically updated simply because it now refers to the same
memory location as the corresponding column value.  This makes using
bound variables very efficient.
Binding a tied variable doesn't work, currently.

=end original

バインドは、Perlエイリアスを使用して低レベルで実行されます。
データベースからローがフェッチされるたびに、$var_to_bindは自動的に更新されるように見えます。
これは、対応するカラム値と同じメモリ位置を参照するようになったためです。
これにより、バウンド変数の使用が非常に効率的になります。
タイ変数のバインドは、現在のところ機能しません。
(TBR)

=begin original

The L</bind_param> method
performs a similar, but opposite, function for input variables.

=end original

L</bind_param>メソッドは、入力変数に対して同様の機能を実行しますが、逆の機能を実行します。
(TBR)

=begin original

B<Data Types for Column Binding>

=end original

B<列バインディングのためのデータ型>

=begin original

The C<\%attr> parameter can be used to hint at the data type
formatting the column should have. For example, you can use:

=end original

C<\%attr>パラメータを使用して、列に必要なデータ型のフォーマットを示すことができます。
たとえば、次のように使用できます。
(TBR)

  $sth->bind_col(1, undef, { TYPE => SQL_DATETIME });

=begin original

to specify that you'd like the column (which presumably is some
kind of datetime type) to be returned in the standard format for
SQL_DATETIME, which is 'YYYY-MM-DD HH:MM:SS', rather than the
native formatting the database would normally use.

=end original

これは、データベースが通常使用するネイティブ形式ではなく、SQL_DATETIMEの標準形式('YYYY-MM-DD HH:MM:SS')で返される列(おそらくある種の日時型)を指定します。
(TBR)

=begin original

There's no $var_to_bind in that example to emphasize the point
that bind_col() works on the underlying column and not just
a particular bound variable.

=end original

この例では、bind_col()が特定のバインドされた変数だけでなく、基礎となる列に対して機能するという点を強調するための$var_to_bindはありません。
(TBR)

=begin original

As a short-cut for the common case, the data type can be passed
directly, in place of the C<\%attr> hash reference. This example is
equivalent to the one above:

=end original

よくあるケースのための短縮形として、データ型を直接 C<\%attr>
ハッシュリファレンスの場所に直接、渡すことができます。
この例は、上記のものと同じです。

  $sth->bind_col(1, undef, SQL_DATETIME);

=begin original

The C<TYPE> value indicates the standard (non-driver-specific) type for
this parameter. To specify the driver-specific type, the driver may
support a driver-specific attribute, such as C<{ ora_type =E<gt> 97 }>.

=end original

C<TYPE> の値はこのパラメータでは(ドライバに特有でない)標準の型を示します。
ドライバ特有の型を指定するために、ドライバは C<{ ora_type => 97 }> といった
ドライバ特有の型をサポートしていることがあります。

=begin original

The SQL_DATETIME and other related constants can be imported using

=end original

SQL_DATETIME と関連する定数は以下のようにしてインポートできます

  use DBI qw(:sql_types);

=begin original

See L</"DBI Constants"> for more information.

=end original

さらなる情報については L</"DBI Constants"> を参照してください。

=begin original

Few drivers support specifying a data type via a C<bind_col> call
(most will simply ignore the data type). Fewer still allow the data
type to be altered once set.

=end original

C<bind_col>呼び出しによるデータ型の指定をサポートするドライバはほとんどありません(ほとんどのドライバは単にデータ型を無視します)。
一度設定されたデータ型を変更できるドライバはさらに少ないです。
(TBR)

=begin original

The TYPE attribute for bind_col() was first specified in DBI 1.41.

=end original

bind_col() の TYPE 属性は DBI 1.41 で最初に定義されました。

=begin original

From DBI 1.611, drivers can use the C<TYPE> attribute to attempt to
cast the bound scalar to a perl type which more closely matches
C<TYPE>. At present DBI supports C<SQL_INTEGER>, C<SQL_DOUBLE> and
C<SQL_NUMERIC>. See L</sql_type_cast> for details of how types are
cast.

=end original

DBI 1.611から、ドライバはC<TYPE>属性を使用して、バインドされたスカラーをC<TYPE>により近いperl型にキャストすることができます。
現在、DBIはC<SQL_INTEGER>、C<SQL_DOUBLE>、およびC<SQL_NUMERIC>をサポートしています。
型のキャスト方法の詳細については、L</sql_type_cast>を参照してください。
(TBR)

=begin original

B<Other attributes for Column Binding>

=end original

B<列のバインディングのためのその他の属性>

=begin original

The C<\%attr> parameter may also contain the following attributes:

=end original

C<\%attr> パラメータには以下の属性を含めることもできます:

=over

=item C<StrictlyTyped>

=begin original

If a C<TYPE> attribute is passed to bind_col, then the driver will
attempt to change the bound perl scalar to match the type more
closely. If the bound value cannot be cast to the requested C<TYPE>
then by default it is left untouched and no error is generated. If you
specify C<StrictlyTyped> as 1 and the cast fails, this will generate
an error.

=end original

C<TYPE>属性がbind_colに渡された場合、ドライバはバインドされたperlスカラーを変更して、型をより厳密に一致させようとします。
バインドされた値を要求されたC<TYPE>にキャストできない場合、デフォルトではそのままであり、エラーは生成されません。
C<StrictlyTyped>を1に指定してキャストが失敗した場合、エラーが生成されます。
(TBR)

=begin original

This attribute was first added in DBI 1.611. When 1.611 was released
few drivers actually supported this attribute but DBD::Oracle and
DBD::ODBC should from versions 1.24.

=end original

この属性は、DBI 1.611で最初に追加されました。
1.611がリリースされたとき、この属性を実際にサポートするドライバはほとんどありませんでしたが、DBD::OracleとDBD::ODBCはバージョン1.24からサポートされるはずです。
(TBR)

=item C<DiscardString>

=begin original

When the C<TYPE> attribute is passed to L</bind_col> and the driver
successfully casts the bound perl scalar to a non-string type
then if C<DiscardString> is set to 1, the string portion of the
scalar will be discarded. By default, C<DiscardString> is not set.

=end original

C<TYPE>属性がL</bind_col>に渡され、ドライバがバインドされたperlスカラーを文字列以外の型にキャストすることに成功した場合、C<DiscardString>が1に設定されていると、スカラーの文字列部分は破棄されます。
デフォルトでは、C<DiscardString>は設定されていません。
(TBR)

=begin original

This attribute was first added in DBI 1.611. When 1.611 was released
few drivers actually supported this attribute but DBD::Oracle and
DBD::ODBC should from versions 1.24.

=end original

この属性は、DBI 1.611で最初に追加されました。
1.611がリリースされたとき、この属性を実際にサポートするドライバはほとんどありませんでしたが、DBD::OracleとDBD::ODBCはバージョン1.24からサポートされるはずです。
(TBR)

=back

=head3 C<bind_columns>

  $rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind);

=begin original

Calls L</bind_col> for each column of the C<SELECT> statement.

=end original

C<SELECT> 文の各カラムに L</bind_col> を呼び出します。

=begin original

The list of references should have the same number of elements as the number of
columns in the C<SELECT> statement. If it doesn't then C<bind_columns> will
bind the elements given, up to the number of columns, and then return an error.

=end original

参照のリストには、C<SELECT>ステートメントの列の数と同じ数の要素が含まれている必要があります。
含まれていない場合、C<bind_columns>は指定された要素を列の数までバインドし、エラーを返します。
(TBR)

=begin original

For maximum portability between drivers, bind_columns() should be called
after execute() and not before.

=end original

ドライバ間の移植性を最大限に高めるためには、bind_columns() は execute() の
後に呼び出さなければなりません。

=begin original

For example:

=end original

例えば:

  $dbh->{RaiseError} = 1; # do this, or check every call for errors
  $sth = $dbh->prepare(q{ SELECT region, sales FROM sales_by_region });
  $sth->execute;
  my ($region, $sales);

  # Bind Perl variables to columns:
  $rv = $sth->bind_columns(\$region, \$sales);

  # you can also use Perl's \(...) syntax (see perlref docs):
  #     $sth->bind_columns(\($region, $sales));

  # Column binding is the most efficient way to fetch data
  while ($sth->fetch) {
      print "$region: $sales\n";
  }

=begin original

For compatibility with old scripts, the first parameter will be
ignored if it is C<undef> or a hash reference.

=end original

昔のスクリプトとの互換性のために、最初の引数が C<undef> もしくは
ハッシュリファレンスであれば、無視されます。

=begin original

Here's a more fancy example that binds columns to the values I<inside>
a hash (thanks to H.Merijn Brand):

=end original

カラムをハッシュの内側の値に結びつけるという、さらにすごい例を
示します(H.Merijn Brand に感謝):

  $sth->execute;
  my %row;
  $sth->bind_columns( \( @row{ @{$sth->{NAME_lc} } } ));
  while ($sth->fetch) {
      print "$row{region}: $row{sales}\n";
  }

=head3 C<dump_results>

  $rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh);

=begin original

Fetches all the rows from C<$sth>, calls C<DBI::neat_list> for each row, and
prints the results to C<$fh> (defaults to C<STDOUT>) separated by C<$lsep>
(default C<"\n">). C<$fsep> defaults to C<", "> and C<$maxlen> defaults to 35.

=end original

C<$sth> からすべての行を取り出し、各行に C<DBI::neat_list> を呼び出し、
その結果を C<$lsep> (デフォルトは C<"\n">)で区切って、C<$fh>(デフォルトは
C<STDOUT>)に、出力します。
C<$fsep> のデフォルトは C<", ">、C<$maxlen> のデフォルトは 35 です。

=begin original

This method is designed as a handy utility for prototyping and
testing queries. Since it uses L</neat_list> to
format and edit the string for reading by humans, it is not recommended
for data transfer applications.

=end original

このメソッドは問い合わせのプロトタイプとテストのための簡単な
ユーティリティとして設計されています。
人の目にわかりやすいように文字列の整形し、編集する L</neat_list> を
使っているので、データ転送アプリケーションにはお勧めしません。

=head2 Statement Handle Attributes

(文ハンドル属性)

=begin original

This section describes attributes specific to statement handles. Most
of these attributes are read-only.

=end original

このセクションでは文・ハンドルの属性について記述します。
大半の属性は読込のみです。

=begin original

Changes to these statement handle attributes do not affect any other
existing or future statement handles.

=end original

これらの文・ハンドル属性を変更しても、既存のほかのハンドルや後で作成される文・ハンドルには影響を与えません。

=begin original

Attempting to set or get the value of an unknown attribute generates a warning,
except for private driver specific attributes (which all have names
starting with a lowercase letter).

=end original

ドライバ特有のプライベートな属性(これらの名前は小文字ではじまります)を
除いては、決められていない属性を設定あるいは取得しようとすると
警告が発生します。

=begin original

Example:

=end original

例:

  ... = $h->{NUM_OF_FIELDS};	# get/read

=begin original

Some drivers cannot provide valid values for some or all of these
attributes until after C<$sth-E<gt>execute> has been successfully
called. Typically the attribute will be C<undef> in these situations.

=end original

ドライバによっては、C<$sth-E<gt>execute> が呼ばれるまでは、一部あるいは
すべての属性について正しい値を提供できないものもあります。
典型的には、このような状況では属性は C<undef> になります。

=begin original

Some attributes, like NAME, are not appropriate to some types of
statement, like SELECT. Typically the attribute will be C<undef>
in these situations.

=end original

NAMEのようないくつかの属性は、SELECTのようないくつかのタイプのステートメントには適切ではありません。
通常、このような状況では属性はC<undef>です。
(TBR)

=begin original

For drivers which support stored procedures and multiple result sets
(see more_results) these attributes relate to the I<current> result set.

=end original

ストアドプロシージャと複数の結果セット(more_resultsを参照)をサポートするドライバの場合、これらの属性はI<current>結果セットに関連します。
(TBR)

=begin original

See also L</finish> to learn more about the effect it
may have on some attributes.

=end original

いくつかの属性に影響を与えるかもしれないことについて、より知るために
L</finish> もご覧ください。

=head3 C<NUM_OF_FIELDS>  (integer, read-only)

=begin original

Number of fields (columns) in the data the prepared statement may return.
Statements that don't return rows of data, like C<DELETE> and C<CREATE>
set C<NUM_OF_FIELDS> to 0 (though it may be undef in some drivers).

=end original

準備(prepare) された SQL 文のフィールド(カラム)の数を返します。
C<DELETE> や C<CREATE> のように行数を返さない文の場合
C<NUM_OF_FIELDS> は 0 を設定します(しかしドライバによっては undef を
返します)。

=head3 C<NUM_OF_PARAMS>  (integer, read-only)

=begin original

The number of parameters (placeholders) in the prepared statement.
See SUBSTITUTION VARIABLES below for more details.

=end original

準備(prepare)されたSQL文のパラメータ(プレースホルダ)の数。
詳細については下記の置換変数をご覧ください。 

=head3 C<NAME>  (array-ref, read-only)

=begin original

Returns a reference to an array of field names for each column. The
names may contain spaces but should not be truncated or have any
trailing space. Note that the names have the letter case (upper, lower
or mixed) as returned by the driver being used. Portable applications
should use L</NAME_lc> or L</NAME_uc>.

=end original

各カラムに対応するフィールド名の配列へのリファレンスを返します。
名前には空白が入っているかもしれませんが、切り捨てられることはありませんし、
後ろの空白を持ちます。
返されるときの文字の大文字、小文字、その混合は使われている
データベースによるということに注意してください。
移植性の高いアプリーケーションは L</NAME_lc> または L</NAME_uc> を使うべきです。 

  print "First column name: $sth->{NAME}->[0]\n";

=begin original

Also note that the name returned for (aggregate) functions like C<count(*)>
or C<max(c_foo)> is determined by the database server and not by C<DBI> or
the C<DBD> backend.

=end original

また、C<count(*)>やC<max(c_foo)>などの(集約)関数に対して返される名前は、C<DBI>やC<DBD>バックエンドではなく、データベースサーバによって決定されることにも注意してください。
(TBR)

=head3 C<NAME_lc>  (array-ref, read-only)

=begin original

Like L</NAME> but always returns lowercase names.

=end original

L</NAME> と同様ですが常に小文字で名前が返されます。 

=head3 C<NAME_uc>  (array-ref, read-only)

=begin original

Like L</NAME> but always returns uppercase names.

=end original

L</NAME> と同様ですが常に大文字で名前が返されます。 

=head3 C<NAME_hash>  (hash-ref, read-only)

=head3 C<NAME_lc_hash>  (hash-ref, read-only)

=head3 C<NAME_uc_hash>  (hash-ref, read-only)

=begin original

The C<NAME_hash>, C<NAME_lc_hash>, and C<NAME_uc_hash> attributes
return column name information as a reference to a hash.

=end original

C<NAME_hash>、C<NAME_lc_hash>、およびC<NAME_uc_hash>属性は、ハッシュへの参照として列名情報を返します。
(TBR)

=begin original

The keys of the hash are the names of the columns.  The letter case of
the keys corresponds to the letter case returned by the C<NAME>,
C<NAME_lc>, and C<NAME_uc> attributes respectively (as described above).

=end original

ハッシュのキーは列の名前です。
キーの大文字小文字は、C<NAME>、C<NAME_lc>およびC<NAME_uc>属性(前述)によってそれぞれ戻される大文字小文字に対応します。
(TBR)

=begin original

The value of each hash entry is the perl index number of the
corresponding column (counting from 0). For example:

=end original

各ハッシュエントリの値は、対応する列のperlインデックス番号です(0から数えます)。
次に例を示します。
(TBR)

  $sth = $dbh->prepare("select Id, Name from table");
  $sth->execute;
  @row = $sth->fetchrow_array;
  print "Name $row[ $sth->{NAME_lc_hash}{name} ]\n";

=head3 C<TYPE>  (array-ref, read-only)

=begin original

Returns a reference to an array of integer values for each
column. The value indicates the data type of the corresponding column.

=end original

各カラムに対応する整数値の配列へのリファレンスを返します。
値は対応するカラムのデータ型を示します。

=begin original

The values correspond to the international standards (ANSI X3.135
and ISO/IEC 9075) which, in general terms, means ODBC. Driver-specific
types that don't exactly match standard types should generally return
the same values as an ODBC driver supplied by the makers of the
database. That might include private type numbers in ranges the vendor
has officially registered with the ISO working group:

=end original

この値は国際規約(ANSI X3.135 と ISO/IEC 9075)(一般には ODBC を意味します)に
対応しています。
標準の型に正確にあてはまらない、ドライバ特有の型では、通常、データベースの
メーカーが提供する ODBC ドライバと同じ値を返さなければいけません。
これはベンダーが公式に ISO ワーキンググループに予約しているプライベートな
型番号を含みます。:

  ftp://sqlstandards.org/SC32/SQL_Registry/

=begin original

Where there's no vendor-supplied ODBC driver to be compatible with,
the DBI driver can use type numbers in the range that is now
officially reserved for use by the DBI: -9999 to -9000.

=end original

DBI ドライバは互換性を持つ ODBC ドライバを提供されているベンダーがなければ、
DBI が使用するために公式に予約されている -9999 から -9000 の範囲の型番号を
使うことができます。

=begin original

All possible values for C<TYPE> should have at least one entry in the
output of the C<type_info_all> method (see L</type_info_all>).

=end original

C<TYPE> がとりうるすべての値は、C<type_info_all> メソッドの出力のなかの、
少なくとも一つの要素として入っていなければなりません
(L<type_info_all> をご覧下さい)。

=head3 C<PRECISION>  (array-ref, read-only)

=begin original

Returns a reference to an array of integer values for each column.

=end original

各カラムに対応する整数値の配列へのリファレンスを返します。

=begin original

For numeric columns, the value is the maximum number of digits
(without considering a sign character or decimal point). Note that
the "display size" for floating point types (REAL, FLOAT, DOUBLE)
can be up to 7 characters greater than the precision (for the
sign + decimal point + the letter E + a sign + 2 or 3 digits).

=end original

数値のカラムでは、値は数値の最大桁数です
(符号文字や小数点を除きます)。
浮動小数点の型(REAL, FLOAT, DOUBLE)では「表示サイズ」は precision よりも
7 文字までは、大きいかもしれません
(符号 + 小数点 + E という文字 + 符号 +2 または 3 桁)。

=begin original

For any character type column the value is the OCTET_LENGTH,
in other words the number of bytes, not characters.

=end original

どの文字タイプ列でも、値はOCTET_LENGTH、つまり文字ではなくバイト数です。
(TBR)

=begin original

(More recent standards refer to this as COLUMN_SIZE but we stick
with PRECISION for backwards compatibility.)

=end original

(最近の標準ではこれをCOLUMN_SIZEと呼んでいますが、後方互換性のためにPRECISIONを使用しています)。
(TBR)

=head3 C<SCALE>  (array-ref, read-only)

=begin original

Returns a reference to an array of integer values for each column.
NULL (C<undef>) values indicate columns where scale is not applicable.

=end original

各カラムに対応する整数値の配列へのリファレンスを返します。
NULL (C<undef>) 値には、scale が適用されないことを示します。 

=head3 C<NULLABLE>  (array-ref, read-only)

=begin original

Returns a reference to an array indicating the possibility of each
column returning a null.  Possible values are C<0>
(or an empty string) = no, C<1> = yes, C<2> = unknown.

=end original

各カラムが NULL にしていいかどうかを示す値を配列へのリファレンスを返します。
とりうる値は、0 (または空文字列)= 受け入れない、1 = 受け入れる、
2 = 不明です。 

  print "First column may return NULL\n" if $sth->{NULLABLE}->[0];

=head3 C<CursorName>  (string, read-only)

=begin original

Returns the name of the cursor associated with the statement handle, if
available. If not available or if the database driver does not support the
C<"where current of ..."> SQL syntax, then it returns C<undef>.

=end original

文ハンドルが使えるのであれば、文ハンドルに
結び付けられたカーソル名を返します。
使えないか、"where current of ..." SQL の書き方をデータベースドライバが
サポートしていなければ C<undef> を返します。 

=head3 C<Database>  (dbh, read-only)

=begin original

Returns the parent $dbh of the statement handle.

=end original

文ハンドルの親 $dbh を返します。

=head3 C<Statement>  (string, read-only)

=begin original

Returns the statement string passed to the L</prepare> method.

=end original

L</prepare> メソッドに渡された、文文字列を返します。

=head3 C<ParamValues>  (hash ref, read-only)

=begin original

Returns a reference to a hash containing the values currently bound
to placeholders.  The keys of the hash are the 'names' of the
placeholders, typically integers starting at 1.  Returns undef if
not supported by the driver.

=end original

現在プレースホルダにバインドされている値を含むハッシュへの参照を返します。
ハッシュのキーはプレースホルダの「名前」で、通常は1から始まる整数です。
ドライバでサポートされていない場合はundefを返します。
(TBR)

=begin original

See L</ShowErrorStatement> for an example of how this is used.

=end original

これの使い方に関する例については L</ShowErrorStatement> を参照してください。

=begin original

* Keys:

=end original

* キー:

=begin original

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 because they can't pre-determine the names.

=end original

ドライバがC<ParamValues>をサポートしていて、値がまだバインドされていない場合、ドライバはキーにプレースホルダ名を持つハッシュを返す必要がありますが、すべての値はundefです。
ただし、ドライバによっては、名前を事前に決定できないため、空のハッシュへの参照を返す場合があります。
(TBR)

=begin original

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.

=end original

C<ParamValues>によって返されるハッシュ内のキーは、準備された文によって暗示されるキーと正確には同じでない可能性があります。
たとえば、DBD::Oracleは'C<?>'プレースホルダを'C<:pN>'に変換します。
ここで、Nは1から始まるシーケンス番号です。
(TBR)

=begin original

* Values:

=end original

* 値:

=begin original

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().
The driver may have slightly modified values in some way based on the
TYPE the value was bound with. For example a floating point value
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. See also L</ParamTypes> below.

=end original

C<ParamValues>によって返されたハッシュの値は、bind_param()またはexecute()に渡された値と<正確に>同じではない可能性があります。
ドライバは、値がバインドされたTYPEに基づいて、何らかの方法でわずかに変更された値を持つ場合があります。
たとえば、SQL_INTEGER型としてバインドされた浮動小数点値は、整数として返される場合があります。
C<ParamValues>によって返された値は、同じTYPEを持つ別のbind_param()メソッドに渡すことができ、データベースでは同じ値として表示されます。
後述のL</ParamTypes>も参照してください。
(TBR)

=begin original

The C<ParamValues> attribute was added in DBI 1.28.

=end original

C<ParamValues> 属性は DBI 1.28 で追加されました。

=head3 C<ParamTypes>  (hash ref, read-only)

=begin original

Returns a reference to a hash containing the type information
currently bound to placeholders.
Returns undef if not supported by the driver.

=end original

現在プレースホルダにバインドされている型情報を含むハッシュへの参照を返します。
ドライバでサポートされていない場合はundefを返します。
(TBR)

=begin original

* Keys:

=end original

* キー:

=begin original

See L</ParamValues> above.

=end original

上述の L</ParamValues> を参照してください。

=begin original

* Values:

=end original

* 値:

=begin original

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).

=end original

ハッシュ値は、さまざまなbind_param()メソッドに渡されるものと同じ形式の型情報のhashrefsです(形式と値についてはL</bind_param>を参照してください)。
(TBR)

=begin original

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 abbreviated form, like this:

=end original

C<ParamTypes>によって返されるハッシュの値は、bind_param()またはexecute()に渡される値と正確には同じでない可能性があります。
param属性は、次のような省略形式を使用して指定されます。
(TBR)

    $sth->bind_param(1, SQL_INTEGER);

=begin original

are returned in the expanded form, as if called like this:

=end original

は、以下のように呼び出されたかのように拡張形式で返されます:

    $sth->bind_param(1, { TYPE => SQL_INTEGER });

=begin original

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).

=end original

ドライバは、バインドされた値、prepare()されたSQLステートメントによって提供される他のヒント、またはドライバまたはターゲットデータベースシステムによって必要とされる代替タイプマッピングに基づいて、何らかの方法でタイプ情報を変更した可能性があります。
ドライバは、プライベートキー(odbc_xxxなど、ドライバの予約済みプレフィクスで始まる名前を持つ)を追加することもできます。
(TBR)

=begin original

* Example:

=end original

* 例:

=begin original

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:

=end original

戻されたハッシュのキーおよび値を様々なbind_param()メソッドに渡して、前のparamバインディングを効果的に再現できます。
次に例を示します。
(TBR)

  # 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();

=begin original

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.

=end original

C<ParamTypes>属性は、DBI 1.49で追加されました。
実装は個々のドライバが行います。
DBIレイヤのデフォルトの実装は、単にundefを返します。
(TBR)

=head3 C<ParamArrays>  (hash ref, read-only)

=begin original

Returns a reference to a hash containing the values currently bound to
placeholders with L</execute_array> or L</bind_param_array>.  The
keys of the hash are the 'names' of the placeholders, typically
integers starting at 1.  Returns undef if not supported by the driver
or no arrays of parameters are bound.

=end original

L</execute_array>またはL</bind_param_array>を持つプレースホルダに現在バインドされている値を含むハッシュへの参照を返します。
ハッシュのキーはプレースホルダの「名前」で、通常は1から始まる整数です。
ドライバでサポートされていない場合、またはパラメータの配列がバインドされていない場合は、undefを返します。
(TBR)

=begin original

Each key value is an array reference containing a list of the bound
parameters for that column.

=end original

各キー値は、その列のバインドされたパラメータのリストを含む配列参照です。
(TBR)

=begin original

For example:

=end original

例えば:

  $sth = $dbh->prepare("INSERT INTO staff (id, name) values (?,?)");
  $sth->execute_array({},[1,2], ['fred','dave']);
  if ($sth->{ParamArrays}) {
      foreach $param (keys %{$sth->{ParamArrays}}) {
	  printf "Parameters for %s : %s\n", $param,
	  join(",", @{$sth->{ParamArrays}->{$param}});
      }
  }

=begin original

It is possible that the values in the hash returned by C<ParamArrays>
are not I<exactly> the same as those passed to L</bind_param_array> or
L</execute_array>.  The driver may have slightly modified values in some
way based on the TYPE the value was bound with. For example a floating
point value bound as an SQL_INTEGER type may be returned as an
integer.

=end original

C<ParamArrays>によって返されたハッシュの値は、L</bind_param_array>またはL</execute_array>に渡された値と<正確に>同じではない可能性があります。
ドライバは、値がバインドされたTYPEに基づいて、何らかの方法でわずかに変更された値を持つ場合があります。
たとえば、SQL_INTEGER型としてバインドされた浮動小数点値は、整数として返される場合があります。
(TBR)

=begin original

It is also possible that the keys in the hash returned by
C<ParamArrays> 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.

=end original

また、C<ParamArrays>によって返されるハッシュ内のキーが、準備された文によって暗示されるキーと正確に同じでない可能性もあります。
たとえば、DBD::Oracleは、'C<?>'プレースホルダを'C<:pN>'に変換します。
ここで、Nは1から始まるシーケンス番号です。
(TBR)

=head3 C<RowsInCache>  (integer, read-only)

=begin original

If the driver supports a local row cache for C<SELECT> statements, then
this attribute holds the number of un-fetched rows in the cache. If the
driver doesn't, then it returns C<undef>. Note that some drivers pre-fetch
rows on execute, whereas others wait till the first fetch.

=end original

ドライバが C<SELECT> 文についてローカルな行キャッシュを
サポートしていれば、この属性はキャシュのなかで fetch されていない行数を
返します。
ドライバがサポートしていなければ、C<undef> を返します。
ドライバによっては execute 時点で前もって取り出すものもありますし、最初の
fetch が来るまで待つものもあります。 

=begin original

See also the L</RowCacheSize> database handle attribute.

=end original

データベースハンドル属性 L</RowCacheSize> もご覧ください。

=head1 FURTHER INFORMATION

(さらなる情報)

=head2 Catalog Methods

(カタログメソッド)

=begin original

An application can retrieve metadata information from the DBMS by issuing
appropriate queries on the views of the Information Schema. Unfortunately,
C<INFORMATION_SCHEMA> views are seldom supported by the DBMS.
Special methods (catalog methods) are available to return result sets
for a small but important portion of that metadata:

=end original

アプリケーションは、情報スキーマのビューに対して適切な問合せを発行することによって、DBMSからメタデータ情報を取得できます。
残念ながら、C<INFORMATION_SCHEMA>ビューはDBMSではほとんどサポートされていません。
そのメタデータの小さいが重要な部分の結果セットを戻すために、特別なメソッド(カタログメソッド)を使用できます。
(TBR)

  column_info
  foreign_key_info
  primary_key_info
  table_info
  statistics_info

=begin original

All catalog methods accept arguments in order to restrict the result sets.
Passing C<undef> to an optional argument does not constrain the search for
that argument.
However, an empty string ('') is treated as a regular search criteria
and will only match an empty value.

=end original

すべてのカタログメソッドは、結果セットを制限するために引数を受け入れます。
オプションの引数にC<undef>を渡しても、その引数の検索は制限されません。
ただし、空の文字列('')は通常の検索基準として扱われ、空の値にのみ一致します。
(TBR)

=begin original

B<Note>: SQL/CLI and ODBC differ in the handling of empty strings. An
empty string will not restrict the result set in SQL/CLI.

=end original

B<注>:SQL/CLIとODBCでは、空の文字列の処理が異なります。
空の文字列は、SQL/CLIの結果セットを制限しません。
(TBR)

=begin original

Most arguments in the catalog methods accept only I<ordinary values>, e.g.
the arguments of C<primary_key_info()>.
Such arguments are treated as a literal string, i.e. the case is significant
and quote characters are taken literally.

=end original

カタログメソッドのほとんどの引数は、I<通常の値>のみを受け入れます。
たとえば、C<primary_key_info()>の引数などです。
このような引数はリテラル文字列として扱われます。
つまり、大文字と小文字は区別され、引用符は文字通りに解釈されます。
(TBR)

=begin original

Some arguments in the catalog methods accept I<search patterns> (strings
containing '_' and/or '%'), e.g. the C<$table> argument of C<column_info()>.
Passing '%' is equivalent to leaving the argument C<undef>.

=end original

C<column_info()>のC<$table>引数など、カタログメソッドの一部の引数は、I<search patterns>(「_」または「%」を含む文字列)を受け入れます。
「%」を渡すことは、引数C<undef>を残すことと同じです。
(TBR)

=begin original

B<Caveat>: The underscore ('_') is valid and often used in SQL identifiers.
Passing such a value to a search pattern argument may return more rows than
expected!
To include pattern characters as literals, they must be preceded by an
escape character which can be achieved with

=end original

B<注意事項>:アンダースコア('_')は有効であり、SQL識別子でよく使用されます。
このような値を検索パターン引数に渡すと、予想よりも多くの行が返される可能性があります!パターン文字をリテラルとして含めるには、パターン文字の前にエスケープ文字を付ける必要があります。
これは
(TBR)

  $esc = $dbh->get_info( 14 );  # SQL_SEARCH_PATTERN_ESCAPE
  $search_pattern =~ s/([_%])/$esc$1/g;

=begin original

The ODBC and SQL/CLI specifications define a way to change the default
behaviour described above: All arguments (except I<list value arguments>)
are treated as I<identifier> if the C<SQL_ATTR_METADATA_ID> attribute is
set to C<SQL_TRUE>.
I<Quoted identifiers> are very similar to I<ordinary values>, i.e. their
body (the string within the quotes) is interpreted literally.
I<Unquoted identifiers> are compared in UPPERCASE.

=end original

ODBCおよびSQL/CLIの仕様では、前述のデフォルトの動作を変更する方法が定義されています。
C<SQL_ATTR_METADATA_ID>属性がC<SQL_TRUE>に設定されている場合、すべての引数(I<list value arguments>を除く)はI<identifier>として扱われます。
I<quoted identifiers>はI<ordinary values>と非常によく似ています。
つまり、本文(引用符で囲まれた文字列)は文字どおりに解釈されます。
I<unquoted identifiers>は大文字で比較されます。
(TBR)

=begin original

The DBI (currently) does not support the C<SQL_ATTR_METADATA_ID> attribute,
i.e. it behaves like an ODBC driver where C<SQL_ATTR_METADATA_ID> is set to
C<SQL_FALSE>.

=end original

DBIは(現在)C<SQL_ATTR_METADATA_ID>属性をサポートしていません。
つまり、C<SQL_ATTR_METADATA_ID>がC<SQL_FALSE>に設定されているODBCドライバのように動作します。
(TBR)

=head2 Transactions

(トランザクション)

=begin original

Transactions are a fundamental part of any robust database system. They
protect against errors and database corruption by ensuring that sets of
related changes to the database take place in atomic (indivisible,
all-or-nothing) units.

=end original

トランザクションはすべての堅牢なデータベースシステムの基本的な部分です。
データベースへの関連する一連の変更が、アトミックな(独立していて
オールオアナッシングな)単位で行われること保証することにより、エラーと
データベース障害から守ります。

=begin original

This section applies to databases that support transactions and where
C<AutoCommit> is off.  See L</AutoCommit> for details of using C<AutoCommit>
with various types of databases.

=end original

この節はトランザクションをサポートし、C<AutoCommit> がオフに
なっているデータベースにあてはまります。
各種のデータベースに対する C<AutoCommit> の使い方の詳細については
L</AutoCommit> をご覧ください。

=begin original

The recommended way to implement robust transactions in Perl
applications is to use C<RaiseError> and S<C<eval { ... }>>
(which is very fast, unlike S<C<eval "...">>). For example:

=end original

Perl アプリケーションで堅牢なトランザクションを実現するためのお勧めの方法は、
C<RaiseError> と S<C<eval { ... }>> を使うことです
(これは S<C<eval "...">> と違ってとても速く動作します)。
例えば:

=begin original

  $dbh->{AutoCommit} = 0;  # enable transactions, if possible
  $dbh->{RaiseError} = 1;
  eval {
      foo(...)        # do lots of work here
      bar(...)        # including inserts
      baz(...)        # and updates
      $dbh->commit;   # commit the changes if we get this far
  };
  if ($@) {
      warn "Transaction aborted because $@";
      # now rollback to undo the incomplete changes
      # but do it in an eval{} as it may also fail
      eval { $dbh->rollback };
      # add other application on-error-clean-up code here
  }

=end original

  $dbh->{AutoCommit} = 0;  # 可能であれば、トランザクションを有効にします
  $dbh->{RaiseError} = 1;
  eval {
      foo(...)        # INSERT や UPDATE を含む
      bar(...)        # 多くの処理を
      baz(...)        # ここでします
      $dbh->commit;   # ここまで来たらコミットします
  };
  if ($@) {
      warn "Transaction aborted because $@";
      # ここで不完全な変更を元に戻すためにロールバックします
      # しかしこれも失敗することがあるので eval{} の中で行います
      eval { $dbh->rollback };
      # 他のアプリケーションの後片付けの処理をここに入れます
  }

=begin original

If the C<RaiseError> attribute is not set, then DBI calls would need to be
manually checked for errors, typically like this:

=end original

C<RaiseError> 属性が設定されていなければ、DBI 呼び出しは手動でエラーの
チェックをする必要があります。
通常は以下のようにします:

  $h->method(@args) or die $h->errstr;

=begin original

With C<RaiseError> set, the DBI will automatically C<die> if any DBI method
call on that handle (or a child handle) fails, so you don't have to
test the return value of each method call. See L</RaiseError> for more
details.

=end original

C<RaiseError> を設定すると、そのハンドル(またはその子供のハンドル)で
呼び出される DBI メソッドが失敗すると、DBI は自動的に die します。
そのため各メソッド呼び出しの戻り値をいちいちチェックする必要が
なくなります。
詳細については L</RaiseError> をご覧ください。

=begin original

A major advantage of the C<eval> approach is that the transaction will be
properly rolled back if I<any> code (not just DBI calls) in the inner
application dies for any reason. The major advantage of using the
C<$h-E<gt>{RaiseError}> attribute is that all DBI calls will be checked
automatically. Both techniques are strongly recommended.

=end original

C<eval> による方法の大きな利点は、アプリケーション内部のいかなる理由で、
(DBI呼び出しに限らず)どのような処理で die しても、トランザクションが
適切にロールバックされることにあります。
$h->{RaiseError} 属性を使う大きな利点は、すべての DBI 呼び出しが自動的に
チェックされることにあります。
どちらのテクニックも強くお勧めします。

=begin original

After calling C<commit> or C<rollback> many drivers will not let you
fetch from a previously active C<SELECT> statement handle that's a child
of the same database handle. A typical way round this is to connect the
the database twice and use one connection for C<SELECT> statements.

=end original

C<commit> や C<rollback> を呼び出した後、多くのドライバは同じ
データベースハンドルの子供で以前はアクティブだった C<SELECT>
文ハンドルからの取り出しをさせてくれません。
これを避ける典型的な方法は、データベースに 2 回接続し、一つの接続を
C<SELECT> 文のために使うことです。

=begin original

See L</AutoCommit> and L</disconnect> for other important information
about transactions.

=end original

トランザクションに関するその他の重要な情報については
L</AutoCommit> と L</disconnect> を参照してください。

=head2 Handling BLOB / LONG / Memo Fields

(BLOB / LONG / Memoフィールドを扱う)

=begin original

Many databases support "blob" (binary large objects), "long", or similar
datatypes for holding very long strings or large amounts of binary
data in a single field. Some databases support variable length long
values over 2,000,000,000 bytes in length.

=end original

多くのデータベースは一つのフィールドにとても長い文字列や、巨大な
バイナリデータを保持するために、"blob" (binary large objects＝巨大なバイナリ
オブジェクト), "long" または同じようなデータ型をサポートしています。
データベースによっては、2,000,000,000 バイトを越えるような長さの可変長の値も
サポートしています。

=begin original

Since values of that size can't usually be held in memory, and because
databases can't usually know in advance the length of the longest long
that will be returned from a C<SELECT> statement (unlike other data
types), some special handling is required.

=end original

その大きさの値を通常メモリに保持することができないこと、(他のデータ型と
違って)C<SELECT> 文によって返される最大長をデータベースは
前もってわからないことから、特別な操作が必要になります。

=begin original

In this situation, the value of the C<$h-E<gt>{LongReadLen}>
attribute is used to determine how much buffer space to allocate
when fetching such fields.  The C<$h-E<gt>{LongTruncOk}> attribute
is used to determine how to behave if a fetched value can't fit
into the buffer.

=end original

このような場合に、そのようなフィールドを取り出すときに、どれくらいの
バッファスペースを確保するかを決めるために、C<$h-E<gt>{LongReadLen}> 属性の
値が使われます。
C<$h-E<gt>{LongTruncOk}> 属性は、取り出した値がバッファに
入りきらなかったときにどのように振る舞うかを決定するのに使われます。

=begin original

See the description of L</LongReadLen> for more information.

=end original

さらなる情報については L</LongReadLen> の記述を参照してください。

=begin original

When trying to insert long or binary values, placeholders should be used
since there are often limits on the maximum size of an C<INSERT>
statement and the L</quote> method generally can't cope with binary
data.  See L</Placeholders and Bind Values>.

=end original

長い値やバイナリの値を挿入するとき、C<INSERT> 文の大きさには
よく限度があり、L</quote> メソッドは通常バイナリデータに対処できないので、
プレースホルダを使わなければなりません。
L</Placeholders and Bind Values> をご覧ください。

=head2 Simple Examples

(簡単な例)

=begin original

Here's a complete example program to select and fetch some data:

=end original

データをいくつか選択(select)し、取り出す(fetch)一通り揃ったプログラム例を
以下に示します:

  my $data_source = "dbi::DriverName:db_name";
  my $dbh = DBI->connect($data_source, $user, $password)
      or die "Can't connect to $data_source: $DBI::errstr";

  my $sth = $dbh->prepare( q{
          SELECT name, phone
          FROM mytelbook
  }) or die "Can't prepare statement: $DBI::errstr";

  my $rc = $sth->execute
      or die "Can't execute statement: $DBI::errstr";

  print "Query will return $sth->{NUM_OF_FIELDS} fields.\n\n";
  print "Field names: @{ $sth->{NAME} }\n";

  while (($name, $phone) = $sth->fetchrow_array) {
      print "$name: $phone\n";
  }
  # check for problems which may have terminated the fetch early
  die $sth->errstr if $sth->err;

  $dbh->disconnect;

=begin original

Here's a complete example program to insert some data from a file.
(This example uses C<RaiseError> to avoid needing to check each call).

=end original

ファイルからデータを挿入する一通り揃ったプログラム例を以下に示します。
(この例では各呼び出しでチェックする必要をなくすために、C<RaiseError> を
使っています)。

  my $dbh = DBI->connect("dbi:DriverName:db_name", $user, $password, {
      RaiseError => 1, AutoCommit => 0
  });

  my $sth = $dbh->prepare( q{
      INSERT INTO table (name, phone) VALUES (?, ?)
  });

  open FH, "<phone.csv" or die "Unable to open phone.csv: $!";
  while (<FH>) {
      chomp;
      my ($name, $phone) = split /,/;
      $sth->execute($name, $phone);
  }
  close FH;

  $dbh->commit;
  $dbh->disconnect;

=begin original

Here's how to convert fetched NULLs (undefined values) into empty strings:

=end original

これは取り出した NULL(未定義値)を空文字列に変換する方法です:

  while($row = $sth->fetchrow_arrayref) {
    # this is a fast and simple way to deal with nulls:
    foreach (@$row) { $_ = '' unless defined }
    print "@$row\n";
  }

=begin original

The C<q{...}> style quoting used in these examples avoids clashing with
quotes that may be used in the SQL statement. Use the double-quote like
C<qq{...}> operator if you want to interpolate variables into the string.
See L<perlop/"Quote and Quote-like Operators"> for more details.

=end original

SQL文で使われているかもしれないクォートの対応が壊れないように、
これら例では C<q{...}> 形式のクォートを使っています。
文字列中の変数を解釈して欲しいときには、C<qq{...}> 演算子のような
ダブル・クォートを使ってください。
詳細は L<perlop/"Quote and Quote-like Operators"> をご覧ください。

=head2 Threads and Thread Safety

(スレッドとスレッドセーフ性)

=begin original

Perl 5.7 and later support a new threading model called iThreads.
(The old "5.005 style" threads are not supported by the DBI.)

=end original

Perl 5.7以降では、iThreadと呼ばれる新しいスレッド化モデルがサポートされています(古い「5.005スタイル」のスレッドはDBIではサポートされていません)。
(TBR)

=begin original

In the iThreads model each thread has it's own copy of the perl
interpreter.  When a new thread is created the original perl
interpreter is 'cloned' to create a new copy for the new thread.

=end original

iThreadモデルでは、各スレッドはperlインタプリタの独自のコピーを持っています。
新しいスレッドが作成されると、元のperlインタプリタが「複製」され、新しいスレッドの新しいコピーが作成されます。
(TBR)

=begin original

If the DBI and drivers are loaded and handles created before the
thread is created then it will get a cloned copy of the DBI, the
drivers and the handles.

=end original

DBIとドライバがロードされ、スレッドが作成される前にハンドルが作成された場合は、DBI、ドライバ、ハンドルのクローンコピーが取得されます。
(TBR)

=begin original

However, the internal pointer data within the handles will refer
to the DBI and drivers in the original interpreter. Using those
handles in the new interpreter thread is not safe, so the DBI detects
this and croaks on any method call using handles that don't belong
to the current thread (except for DESTROY).

=end original

ただし、ハンドル内の内部ポインタデータは、元のインタプリタ内のDBIおよびドライバを参照します。
新しいインタプリタスレッドでこれらのハンドルを使用することは安全ではないため、DBIはこれを検出し、現在のスレッドに属していないハンドル(DESTROYを除く)を使用するメソッド呼び出しを検出します。
(TBR)

=begin original

Because of this (possibly temporary) restriction, newly created
threads must make their own connections to the database. Handles
can't be shared across threads.

=end original

この(おそらく一時的な)制限のため、新しく作成されたスレッドは、データベースへの独自の接続を作成する必要があります。
ハンドルはスレッド間で共有できません。
(TBR)

=begin original

But BEWARE, some underlying database APIs (the code the DBD driver
uses to talk to the database, often supplied by the database vendor)
are not thread safe. If it's not thread safe, then allowing more
than one thread to enter the code at the same time may cause
subtle/serious problems. In some cases allowing more than
one thread to enter the code, even if I<not> at the same time,
can cause problems. You have been warned.

=end original

しかし注意してほしいのですが、基盤となるデータベースAPI(DBDドライバがデータベースと通信するために使用するコードで、データベースベンダによって提供されることが多いもの)の中には、スレッドセーフでないものがあります。
スレッドセーフでない場合、複数のスレッドが同時にコードを入力できるようにすると、微妙な問題や深刻な問題が発生する可能性があります。
場合によっては、複数のスレッドがコードを入力できるようにすると、同時に<しない>場合でも、問題が発生する可能性があります。
警告されました。
(TBR)

=begin original

Using DBI with perl threads is not yet recommended for production
environments. For more information see
L<http://www.perlmonks.org/index.pl?node_id=288022>

=end original

perlスレッドでDBIを使用することは、本番環境ではまだ推奨されていません。
詳細については、L<http://www.perlmonks.org/index.pl?node_id=288022>を参照してください。
(TBR)

=begin original

Note: There is a bug in perl 5.8.2 when configured with threads
and debugging enabled (bug #24463) which causes a DBI test to fail.

=end original

注:perl 5.8.2には、スレッドとデバッグを有効にして設定した場合に、DBIテストが失敗するバグ(バグ#24463)があります。
(TBR)

=head2 Signal Handling and Canceling Operations

(シグナルの扱いとキャンセル操作)

=begin original

[The following only applies to systems with unix-like signal handling.
I'd welcome additions for other systems, especially Windows.]

=end original

[以下はUnixライクなシグナル処理を行うシステムにのみ適用されます。
他のシステム、特にWindowsでの追加を歓迎します。
]
(TBR)

=begin original

The first thing to say is that signal handling in Perl versions less
than 5.8 is I<not> safe. There is always a small risk of Perl
crashing and/or core dumping when, or after, handling a signal
because the signal could arrive and be handled while internal data
structures are being changed. If the signal handling code
used those same internal data structures it could cause all manner
of subtle and not-so-subtle problems.  The risk was reduced with
5.4.4 but was still present in all perls up through 5.8.0.

=end original

最初に言うべきことは、5.8より前のPerlバージョンでのシグナル処理は安全ではないということです。
内部データ構造が変更されている間にシグナルが到着して処理される可能性があるため、シグナルを処理するとき、または処理した後に、Perlがクラッシュしたり、コアダンプしたりする小さなリスクが常にあります。
シグナル処理コードが同じ内部データ構造を使用している場合、あらゆる種類の微妙な問題やそれほど微妙ではない問題が発生する可能性があります。
このリスクは5.4.4年には減少したが、5.8.0年までは全ペルルに依然として存在していた。
(TBR)

=begin original

Beginning in perl 5.8.0 perl implements 'safe' signal handling if
your system has the POSIX sigaction() routine. Now when a signal
is delivered perl just makes a note of it but does I<not> run the
%SIG handler. The handling is 'deferred' until a 'safe' moment.

=end original

perl 5.8.0以降では、システムにPOSIX sigaction()ルーチンがあれば、perlは「安全な」シグナル処理を実装します。
現在では、シグナルが配信されるとperlはそれを記録するだけですが、私は%SIGハンドラを実行しません。
処理は「安全な」瞬間まで「延期」されます。
(TBR)

=begin original

Although this change made signal handling safe, it also lead to
a problem with signals being deferred for longer than you'd like.
If a signal arrived while executing a system call, such as waiting
for data on a network connection, the signal is noted and then the
system call that was executing returns with an EINTR error code
to indicate that it was interrupted. All fine so far.

=end original

この変更によってシグナル処理は安全になりましたが、シグナルが必要以上に遅延されるという問題も発生します。
ネットワーク接続でデータを待機しているときなど、システムコールの実行中にシグナルが到着すると、そのシグナルが記録され、実行中のシステムコールは、中断されたことを示すEINTRエラーコードを返します。
今のところ大丈夫です。
(TBR)

=begin original

The problem comes when the code that made the system call sees the
EINTR code and decides it's going to call it again. Perl doesn't
do that, but database code sometimes does. If that happens then the
signal handler doesn't get called until later. Maybe much later.

=end original

問題は、システムコールを行ったコードがEINTRコードを見て、それを再度呼び出すことを決定したときに発生します。
Perlはそうしませんが、データベースコードは時々そうすることがあります。
そうなった場合、シグナルハンドラは後になるまで呼び出されません。
おそらくもっと後になるでしょう。
(TBR)

=begin original

Fortunately there are ways around this which we'll discuss below.
Unfortunately they make signals unsafe again.

=end original

幸いなことに、これを回避する方法があります。
これについては後で説明します。
残念ながら、それらは信号を再び危険なものにします。
(TBR)

=begin original

The two most common uses of signals in relation to the DBI are for
canceling operations when the user types Ctrl-C (interrupt), and for
implementing a timeout using C<alarm()> and C<$SIG{ALRM}>.

=end original

DBI に関連して最も一般的に使われるシグナルの二つは、Ctrl-C(中断)を
押したときのキャンセル操作と、C<alarm()> と C<$SIG{ALRM}> を使って実現される
タイムアウトです。

=over 4

=item Cancel

(キャンセル)

=begin original

The DBI provides a C<cancel> method for statement handles. The
C<cancel> method should abort the current operation and is designed
to be called from a signal handler.  For example:

=end original

DBI は C<cancel> メソッドを文ハンドルに用意しています。
C<cancel> メソッドはその時点の操作を中断させなければいけません;
そしてシグナルハンドラから呼ばれるように設計されています。
例えば:

  $SIG{INT} = sub { $sth->cancel };

=begin original

However, few drivers implement this (the DBI provides a default
method that just returns C<undef>) and, even if implemented, there
is still a possibility that the statement handle, and even the
parent database handle, will not be usable afterwards.

=end original

しかし、これを実装しているドライバはほとんどなく(DBI は C<undef> を
返すだけのデフォルトのメソッドを提供しています)、たとえ
実装されていたとしても、文ハンドル、さらに場合によっては
親のデータベースハンドルが、それ以降、使えなくなる可能性があります。

=begin original

If C<cancel> returns true, then it has successfully
invoked the database engine's own cancel function.  If it returns false,
then C<cancel> failed. If it returns C<undef>, then the database
driver does not have cancel implemented - very few do.

=end original

C<cancel> が真を返せば、それはデータベースエンジンそのものの
キャンセル機能を呼び出すことに成功しています。
偽を返せば、C<cancel> は失敗しています。
C<undef> を返せば、データベースエンジンはキャンセルを実装していません -
めったにありませんが。

=item Timeout

(タイムアウト)

=begin original

The traditional way to implement a timeout is to set C<$SIG{ALRM}>
to refer to some code that will be executed when an ALRM signal
arrives and then to call alarm($seconds) to schedule an ALRM signal
to be delivered $seconds in the future. For example:

=end original

タイムアウトを実装する従来の方法は、C<$SIG{ALRM}>を設定して、ALRM信号が到着したときに実行されるコードを参照し、次にアラーム($seconds)を呼び出して、ALRM信号が将来$秒間配信されるようにスケジュールすることです。
次に例を示します。
(TBR)

  eval {
    local $SIG{ALRM} = sub { die "TIMEOUT\n" }; # N.B. \n required
    eval {
      alarm($seconds);
      ... code to execute with timeout here (which may die) ...
    };
    # outer eval catches alarm that might fire JUST before this alarm(0)
    alarm(0);  # cancel alarm (if code ran fast)
    die "$@" if $@;
  };
  if ( $@ eq "TIMEOUT\n" ) { ... }
  elsif ($@) { ... } # some other error

=begin original

The first (outer) eval is used to avoid the unlikely but possible
chance that the "code to execute" dies and the alarm fires before it
is cancelled. Without the outer eval, if this happened your program
will die if you have no ALRM handler or a non-local alarm handler
will be called.

=end original

最初の(外部)評価は、「実行するコード」が消滅し、それがキャンセルされる前にアラームが発生する可能性を回避するために使用されます。
外部評価がない場合、これが発生した場合、ALRMハンドラがない場合にプログラムが消滅するか、非ローカルアラームハンドラが呼び出されます。
(TBR)

=begin original

Unfortunately, as described above, this won't always work as expected,
depending on your perl version and the underlying database code.

=end original

残念ながら、上記で説明したように、perlのバージョンと基礎となるデータベースコードによっては、これが常に期待通りに動作するとは限りません。
(TBR)

=begin original

With Oracle for instance (DBD::Oracle), if the system which hosts
the database is down the DBI->connect() call will hang for several
minutes before returning an error.

=end original

例えばOracle(DBD::Oracle)では、データベースをホストしているシステムがダウンした場合、DBI->connect()コールはエラーを返す前に数分間ハングします。
(TBR)

=back

=begin original

The solution on these systems is to use the C<POSIX::sigaction()>
routine to gain low level access to how the signal handler is installed.

=end original

これらのシステムでの解決策は、Cの<POSIX::sigaction()>ルーチンを使用して、シグナルハンドラのインストール方法に低レベルでアクセスすることです。
(TBR)

=begin original

The code would look something like this (for the DBD-Oracle connect()):

=end original

コードは以下のような感じになります (DBD-Oracle connect() の場合):

   use POSIX qw(:signal_h);

   my $mask = POSIX::SigSet->new( SIGALRM ); # signals to mask in the handler
   my $action = POSIX::SigAction->new(
       sub { die "connect timeout\n" },        # the handler code ref
       $mask,
       # not using (perl 5.8.2 and later) 'safe' switch or sa_flags
   );
   my $oldaction = POSIX::SigAction->new();
   sigaction( SIGALRM, $action, $oldaction );
   my $dbh;
   eval {
      eval {
        alarm(5); # seconds before time out
        $dbh = DBI->connect("dbi:Oracle:$dsn" ... );
      };
      alarm(0); # cancel alarm (if connect worked fast)
      die "$@\n" if $@; # connect died
   };
   sigaction( SIGALRM, $oldaction );  # restore original signal handler
   if ( $@ ) {
     if ($@ eq "connect timeout\n") {...}
     else { # connect died }
   }

=begin original

See previous example for the reasoning around the double eval.

=end original

2 重 eval の意味については前述の例を参照してください。

=begin original

Similar techniques can be used for canceling statement execution.

=end original

同様のテクニックは文の実行のキャンセルにも使えます。

=begin original

Unfortunately, this solution is somewhat messy, and it does I<not> work with
perl versions less than perl 5.8 where C<POSIX::sigaction()> appears to be broken.

=end original

残念ながら、この解決策は多少厄介であり、C<POSIX::sigaction()>が壊れているように見えるperl 5.8よりも前のperlバージョンでは動作しません。
(TBR)

=begin original

For a cleaner implementation that works across perl versions, see Lincoln Baxter's
Sys::SigAction module at L<http://search.cpan.org/~lbaxter/Sys-SigAction/>.
The documentation for Sys::SigAction includes an longer discussion
of this problem, and a DBD::Oracle test script.

=end original

Perlバージョン間で動作するよりクリーンな実装については、L<http://search.cpan.org/~lbaxter/Sys-SigAction/>にあるLincoln BaxterのSys::SigActionモジュールを参照してください。
Sys::SigActionの文書には、この問題に関するより長い説明と、DBD::Oracleテストスクリプトが含まれています。
(TBR)

=begin original

Be sure to read all the signal handling sections of the L<perlipc> manual.

=end original

L<perlipc> マニュアルのシグナルハンドリングの章を全て読むようにしてください。

=begin original

And finally, two more points to keep firmly in mind. Firstly,
remember that what we've done here is essentially revert to old
style I<unsafe> handling of these signals. So do as little as
possible in the handler.  Ideally just die(). Secondly, the handles
in use at the time the signal is handled may not be safe to use
afterwards.

=end original

そして最後に、しっかりと心に留めておくべき2つのポイントがあります。
まず、ここで行ったことは、基本的にこれらのシグナルの古いスタイルのI<unsafe>処理に戻すことであることを覚えておいてください。
そのため、ハンドラではできるだけ少なくしてください。
理想的には、die()だけです。
次に、シグナルが処理されるときに使用されているハンドルは、その後使用するには安全ではない可能性があります。
(TBR)

=head2 Subclassing the DBI

(DBI のサブクラス化)

=begin original

DBI can be subclassed and extended just like any other object
oriented module.  Before we talk about how to do that, it's important
to be clear about the various DBI classes and how they work together.

=end original

DBIは、他のオブジェクト指向モジュールと同様にサブクラス化および拡張できます。
その方法について説明する前に、さまざまなDBIクラスとそれらがどのように連携するかを明確にすることが重要です。
(TBR)

=begin original

By default C<$dbh = DBI-E<gt>connect(...)> returns a $dbh blessed
into the C<DBI::db> class.  And the C<$dbh-E<gt>prepare> method
returns an $sth blessed into the C<DBI::st> class (actually it
simply changes the last four characters of the calling handle class
to be C<::st>).

=end original

デフォルトでは、C<$dbh=DBI-E<gt>connect(.)>は、C<DBI::db>クラスに$dbhを返します。
また、C<$dbh-E<gt>prepare>メソッドは、C<DBI::st>クラスに$sを返します(実際には、呼び出しハンドルクラスの最後の4文字をC<::st>に変更するだけです)。
(TBR)

=begin original

The leading 'C<DBI>' is known as the 'root class' and the extra
'C<::db>' or 'C<::st>' are the 'handle type suffixes'. If you want
to subclass the DBI you'll need to put your overriding methods into
the appropriate classes.  For example, if you want to use a root class
of C<MySubDBI> and override the do(), prepare() and execute() methods,
then your do() and prepare() methods should be in the C<MySubDBI::db>
class and the execute() method should be in the C<MySubDBI::st> class.

=end original

先頭の「C<DBI>」は「ルートクラス」と呼ばれ、追加の「C<::db>」または「C<::st>」は「ハンドルタイプの接尾辞」です。
DBIをサブクラス化したい場合は、オーバーライドメソッドを適切なクラスに配置する必要があります。
たとえば、C<MySubDBI>のルートクラスを使用し、do()、prepare()およびexecute()メソッドをオーバーライドする場合は、do()およびprepare()メソッドをC<MySubDBI::db>クラスに、execute()メソッドをC<MySubDBI::st>クラスに配置する必要があります。
(TBR)

=begin original

To setup the inheritance hierarchy the @ISA variable in C<MySubDBI::db>
should include C<DBI::db> and the @ISA variable in C<MySubDBI::st>
should include C<DBI::st>.  The C<MySubDBI> root class itself isn't
currently used for anything visible and so, apart from setting @ISA
to include C<DBI>, it can be left empty.

=end original

継承階層を設定するには、C<MySubDBI::db>の@ISA変数にC<DBI::db>を含め、C<MySubDBI::st>の@ISA変数にC<DBI::st>を含める必要があります。
C<MySubDBI>ルートクラス自体は現在、表示されるものには使用されていないため、C<DBI>を含めるように@ISAを設定する以外は、空のままにしておくことができます。
(TBR)

=begin original

So, having put your overriding methods into the right classes, and
setup the inheritance hierarchy, how do you get the DBI to use them?
You have two choices, either a static method call using the name
of your subclass:

=end original

オーバーライドメソッドを適切なクラスに配置し、継承階層を設定した後、DBIにそれらを使用させるにはどうすればよいのでしょうか。
2つの選択肢があります。
サブクラスの名前を使用した静的メソッド呼び出しです。
(TBR)

  $dbh = MySubDBI->connect(...);

=begin original

or specifying a C<RootClass> attribute:

=end original

または C<RootClass> 属性を指定して:

  $dbh = DBI->connect(..., { RootClass => 'MySubDBI' });

=begin original

If both forms are used then the attribute takes precedence.

=end original

両方の形式が使われると、属性が優先されます。

=begin original

The only differences between the two are that using an explicit
RootClass attribute will a) make the DBI automatically attempt to load
a module by that name if the class doesn't exist, and b) won't call
your MySubDBI::connect() method, if you have one.

=end original

2つの間の唯一の違いは、明示的なRootClass属性を使用すると、a)クラスが存在しない場合にDBIが自動的にその名前でモジュールをロードしようとすること、およびb)MySubDBI::connect()メソッドがある場合にそれを呼び出さないことです。
(TBR)

=begin original

When subclassing is being used then, after a successful new
connect, the DBI->connect method automatically calls:

=end original

サブクラス化が使用されている場合、新しい接続が成功すると、DBI->connectメソッドは自動的に次を呼び出します。
(TBR)

  $dbh->connected($dsn, $user, $pass, \%attr);

=begin original

The default method does nothing. The call is made just to simplify
any post-connection setup that your subclass may want to perform.
The parameters are the same as passed to DBI->connect.
If your subclass supplies a connected method, it should be part of the
MySubDBI::db package.

=end original

デフォルトのメソッドは何もしません。
この呼び出しは、サブクラスが実行する接続後のセットアップを簡単にするために行われます。
パラメータは、DBI->connectに渡されるものと同じです。
サブクラスが接続されたメソッドを提供する場合、それはMySubDBI::dbパッケージの一部である必要があります。
(TBR)

=begin original

One more thing to note: you must let the DBI do the handle creation.  If you
want to override the connect() method in your *::dr class then it must still
call SUPER::connect to get a $dbh to work with. Similarly, an overridden
prepare() method in *::db must still call SUPER::prepare to get a $sth.
If you try to create your own handles using bless() then you'll find the DBI
will reject them with an "is not a DBI handle (has no magic)" error.

=end original

もう1つ注意すべきことは、ハンドルの作成をDBIに行わせる必要があることです。
*::drクラスのconnect()メソッドをオーバーライドする場合は、$dbhを操作するためにSUPER::connectを呼び出す必要があります。
同様に、*::dbのオーバーライドされたprepare()メソッドは、$sthを取得するためにSUPER::prepareを呼び出す必要があります。
bless()を使用して独自のハンドルを作成しようとすると、DBIが「is not a DBI handle(has no magic)」エラーで拒否することがわかります。
(TBR)

=begin original

Here's a brief example of a DBI subclass.  A more thorough example
can be found in F<t/subclass.t> in the DBI distribution.

=end original

DBIサブクラスの簡単な例を次に示します。
より詳細な例は、DBIディストリビューションのF<t/subclass.t>にあります。
(TBR)

  package MySubDBI;

  use strict;

  use DBI;
  use vars qw(@ISA);
  @ISA = qw(DBI);

  package MySubDBI::db;
  use vars qw(@ISA);
  @ISA = qw(DBI::db);

  sub prepare {
    my ($dbh, @args) = @_;
    my $sth = $dbh->SUPER::prepare(@args)
        or return;
    $sth->{private_mysubdbi_info} = { foo => 'bar' };
    return $sth;
  }

  package MySubDBI::st;
  use vars qw(@ISA);
  @ISA = qw(DBI::st);

  sub fetch {
    my ($sth, @args) = @_;
    my $row = $sth->SUPER::fetch(@args)
        or return;
    do_something_magical_with_row_data($row)
        or return $sth->set_err(1234, "The magic failed", undef, "fetch");
    return $row;
  }

=begin original

When calling a SUPER::method that returns a handle, be careful to
check the return value before trying to do other things with it in
your overridden method. This is especially important if you want to
set a hash attribute on the handle, as Perl's autovivification will
bite you by (in)conveniently creating an unblessed hashref, which your
method will then return with usually baffling results later on like
the error "dbih_getcom handle HASH(0xa4451a8) is not a DBI handle (has
no magic".  It's best to check right after the call and return undef
immediately on error, just like DBI would and just like the example
above.

=end original

ハンドルを返すSU PER::メソッドを呼び出す場合、オーバーライドされたメソッドで他の処理を試みる前に、戻り値をチェックするように注意してください。
ハンドルにハッシュ属性を設定したい場合、これは特に重要です。
なぜなら、Perlのautovivificationは、(in)都合のよいことに、恵まれないhashrefを作成することで、あなたを食い物にし、あなたのメソッドは、後でエラー「dbih_getcom handle HASH(0xa4451a8)is not a DBI handle(has no magic)」のような通常不可解な結果を返すからです。
呼び出しの直後にチェックし、エラーが発生したらすぐにundefを返すのが最善です。
これは、DBIの場合と同じで、上記の例と同じです。
(TBR)

=begin original

If your method needs to record an error it should call the set_err()
method with the error code and error string, as shown in the example
above. The error code and error string will be recorded in the
handle and available via C<$h-E<gt>err> and C<$DBI::errstr> etc.
The set_err() method always returns an undef or empty list as
appropriate. Since your method should nearly always return an undef
or empty list as soon as an error is detected it's handy to simply
return what set_err() returns, as shown in the example above.

=end original

メソッドがエラーを記録する必要がある場合は、上記の例に示すように、エラーコードとエラー文字列を指定してset_err()メソッドを呼び出す必要があります。
エラーコードとエラー文字列はハンドルに記録され、C<$h-E<gt>err>およびC<$DBI::errstr>などを介して使用できます。
set_err()メソッドは、常にundefまたは空のリストを適切に返します。
メソッドは、ほとんどの場合、エラーが検出されるとすぐにundefまたは空のリストを返すので、上記の例に示すように、set_err()が返すものを単純に返すと便利です。
(TBR)

=begin original

If the handle has C<RaiseError>, C<PrintError>, or C<HandleError>
etc. set then the set_err() method will honour them. This means
that if C<RaiseError> is set then set_err() won't return in the
normal way but will 'throw an exception' that can be caught with
an C<eval> block.

=end original

ハンドルにC<RaiseError>、C<PrintError>、またはC<HandleError>などが設定されている場合、set_err()メソッドはそれらを尊重します。
これは、C<RaiseError>が設定されている場合、set_err()は通常の方法では返さず、C<eval>ブロックで捕捉できる「例外をスローする」ことを意味します。
(TBR)

=begin original

You can stash private data into DBI handles
via C<$h-E<gt>{private_..._*}>.  See the entry under L</ATTRIBUTES
COMMON TO ALL HANDLES> for info and important caveats.

=end original

C<$h-E<gt>{private_._*}>を使用して、プライベートデータをDBIハンドルに格納できます。
情報および重要な警告については、L</ATTRIBUTES COMMON TO ALL HANDLES>のエントリを参照してください。
(TBR)

=head1 TRACING

(トレース)

=begin original

The DBI has a powerful tracing mechanism built in. It enables you
to see what's going on 'behind the scenes', both within the DBI and
the drivers you're using.

=end original

DBIには、強力なトレースメカニズムが組み込まれています。
これにより、DBI内および使用しているドライバの両方で、「舞台裏」で何が起こっているかを確認できます。
(TBR)

=head2 Trace Settings

(トレース設定)

=begin original

Which details are written to the trace output is controlled by a
combination of a I<trace level>, an integer from 0 to 15, and a set
of I<trace flags> that are either on or off. Together these are known
as the I<trace settings> and are stored together in a single integer.
For normal use you only need to set the trace level, and generally
only to a value between 1 and 4.

=end original

トレース出力に書き込まれる詳細は、I<トレースレベル>、0～15の整数、およびオンまたはオフのI<トレースフラグ>のセットの組み合わせによって制御されます。
これらはI<トレース設定>と呼ばれ、1つの整数にまとめて格納されます。
通常の使用では、トレースレベルを設定する必要があるだけで、通常は1～4の値のみです。
(TBR)

=begin original

Each handle has it's own trace settings, and so does the DBI.
When you call a method the DBI merges the handles settings into its
own for the duration of the call: the trace flags of the handle are
OR'd into the trace flags of the DBI, and if the handle has a higher
trace level then the DBI trace level is raised to match it.
The previous DBI trace settings are restored when the called method
returns.

=end original

各ハンドルには独自のトレース設定があり、DBIも同様です。
メソッドをコールすると、DBIはコール中にハンドル設定を独自の設定にマージします。
ハンドルのトレースフラグはDBIのトレースフラグにORされ、ハンドルのトレースレベルの方が高い場合は、それに合わせてDBIトレースレベルが上げられます。
コールされたメソッドが戻ると、以前のDBIトレース設定が復元されます。
(TBR)

=head2 Trace Levels

(トレースレベル)

=begin original

Trace I<levels> are as follows:

=end original

トレース I<レベル> は以下のようになります: 

=begin original

  0 - Trace disabled.
  1 - Trace top-level DBI method calls returning with results or errors.
  2 - As above, adding tracing of top-level method entry with parameters.
  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.
      This is the first level to trace all the rows being fetched.
  5 to 15 - As above but with more and more internal information.

=end original

  0 - トレース無効
  1 - トップレベル DBI メソッド呼び出しの戻りを結果またはエラーと一緒にトレース
  2 - 加えてトップレベルメソッドのエントリをパラメータと一緒にトレース
  3 - 加えてドライバからのいくつかのハイレベルな情報と
      DBIからのいくつかの内部情報を追加。
  4 - 加えてドライバからのさらに詳細な情報を追加。
      これはフェッチされる全ての行をトレースする最初のレベルです。
  5 から 15 - 上記と同様。しかし大きくなるに従ってさらに内部の情報。

=begin original

Trace level 1 is best for a simple overview of what's happening.
Trace levels 2 thru 4 a good choice for general purpose tracing.
Levels 5 and above are best reserved for investigating a specific
problem, when you need to see "inside" the driver and DBI.

=end original

トレースレベル 1 が何が起こったのかの単純な概要のために最も向いています。
トレースレベル 2 から 4 はトレースの一般的な目的にはよい選択です。
レベル 5 以上は、DBIとドライバの「内部」を見る必要があるとき、
特定の問題を調べるために予約されています。

=begin original

The trace output is detailed and typically very useful. Much of the
trace output is formatted using the L</neat> function, so strings
in the trace output may be edited and truncated by that function.

=end original

トレース出力はとても詳細で、普通とても役に立ちます。
トレース出力の多くが L</neat> 関数を使って形式を整えています。
このためトレース出力での文字列はこの関数によって編集され、
切り捨てられているかもしれません。。

=head2 Trace Flags

(トレースフラグ)

=begin original

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.

=end original

トレース I<フラグ> は DBI とドライバの内部の特定の機能のトレースを
有効にするために使われます。
DBI がいくつかのトレースフラグを定義し、ドライバもいくつか定義します。
通常通り、DBI のトレースフラグ名は大文字で始まり、ドライバ固有の名前は
小文字で始まります。

=begin original

Currently the DBI only defines two trace flags:

=end original

現在のところ DBI は二つのトレースフラグのみを定義しています:

=begin original

  ALL - turn on all DBI and driver flags (not recommended)
  SQL - trace SQL statements executed
        (not yet implemented in DBI but implemented in some DBDs)

=end original

  ALL - 全ての DBI とドライバのフラグを有効にする (勧めません)
  SQL - 実行された SQL 文をトレースする
        (まだ DBI には実装されていませんが一部の DBD で実装されています)

=begin original

The L</parse_trace_flags> and L</parse_trace_flag> methods are used
to convert trace flag names into the corresponding integer bit flags.

=end original

L</parse_trace_flags> メソッドと L</parse_trace_flag> メソッドは
トレースフラグ名を対応する整数ビットフラグに変換するために使われます。

=head2 Enabling Trace

(トレースを有効にする)

=begin original

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.

=end original

C<$h-E<gt>trace> メソッドはハンドルのためのトレース設定を設定し、
C<DBI-E<gt>trace> は DBI のためのものです。

=begin original

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.

=end original

L</trace> メソッドに加えて、Perl を実行する前に環境変数 C<DBI_TRACE> を
設定すれば、同じトレース情報を有効にし、ファイルに出力することができます。
さらなる情報については L</DBI_TRACE> を参照してください。

=begin original

Finally, you can set, or get, the trace settings for a handle using
the C<TraceLevel> attribute.

=end original

最後に、ハンドルのトレース設定は C<TraceLevel> 属性を使って
設定・取得できます。

=begin original

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:

=end original

これら全てのメソッドは parse_trace_flags() を使っているので、
トレースレベルとフラグ名を縦棒 ("C<|>") またはカンマ ("C<,>") 文字で
区切った文字列を使うことでトレースレベルと複数のトレースフラグの同時に
設定できます。
例えば:

  local $h->{TraceLevel} = "3|SQL|foo";

=head2 Trace Output

(トレース出力)

=begin original

Initially trace output is written to C<STDERR>.  Both the
C<$h-E<gt>trace> and C<DBI-E<gt>trace> methods take an optional
$trace_file parameter, which may be either the name of a file to be
opened by DBI in append mode, or a reference to an existing writable
(possibly layered) filehandle. If $trace_file is a filename,
and can be opened in append mode, or $trace_file is a writable
filehandle, then I<all> trace output (currently including that from
other handles) is redirected to that file. A warning is generated
if $trace_file can't be opened or is not writable.

=end original

最初に、トレース出力はC<STDERR>に書き込まれます。
C<$h-E<gt>trace>およびC<DBI-E<gt>trace>メソッドは、オプションの$trace_fileパラメータを取ります。
これは、追加モードでDBIによって開かれるファイルの名前、または既存の書き込み可能な(場合によっては階層化された)ファイルハンドルへの参照です。
$trace_fileがファイル名であり、追加モードで開くことができる場合、または$trace_fileが書き込み可能なファイルハンドルである場合、I<all>トレース出力(現在、他のハンドルからの出力を含む)はそのファイルにリダイレクトされます。
$trace_fileを開くことができない場合、または$trace_fileが書き込み可能でない場合は、警告が生成されます。
(TBR)

=begin original

Further calls to trace() without $trace_file do not alter where
the trace output is sent. If $trace_file is undefined, then
trace output is sent to C<STDERR> and, if the prior trace was opened with
$trace_file as a filename, the previous trace file is closed; if $trace_file was
a filehandle, the filehandle is B<not> closed.

=end original

$trace_fileを指定せずにtrace()を呼び出しても、トレース出力の送信先は変更されません。
$trace_fileが定義されていない場合、トレース出力はC<STDERR>に送信されます。
前のトレースがファイル名として$trace_fileを指定して開かれた場合、前のトレースファイルは閉じられます。
$trace_fileがファイルハンドルの場合、ファイルハンドルは閉じられません。
(TBR)

=begin original

B<NOTE>: If $trace_file is specified as a filehandle, the filehandle
should not be closed until all DBI operations are completed, or the
application has reset the trace file via another call to
C<trace()> that changes the trace file.

=end original

B<注>:$trace_fileがファイルハンドルとして指定されている場合は、すべてのDBI操作が完了するまで、またはトレースファイルを変更するC<trace()>の別の呼び出しによってアプリケーションがトレースファイルをリセットするまで、ファイルハンドルを閉じないでください。
(TBR)

=head2 Tracing to Layered Filehandles

(層のあるファイルハンドルへのトレース)

=begin original

B<NOTE>:

=end original

B<注意>:

=over 4

=item *
Tied filehandles are not currently supported, as
tie operations are not available to the PerlIO
methods used by the DBI.

=item *
PerlIO layer support requires Perl version 5.8 or higher.

=back

=begin original

As of version 5.8, Perl provides the ability to layer various
"disciplines" on an open filehandle via the L<PerlIO> module.

=end original

バージョン 5.8 から、Perl は開いたファイルハンドルに対して
L<PerlIO> モジュールを通して様々な「ディシプリン」を積み重ねる機能を
提供しています。

=begin original

A simple example of using PerlIO layers is to use a scalar as the output:

=end original

PerlIO 層を使った簡単な例はスカラを出力として使います:

    my $scalar = '';
    open( my $fh, "+>:scalar", \$scalar );
    $dbh->trace( 2, $fh );

=begin original

Now all trace output is simply appended to $scalar.

=end original

ここで全てのトレース出力は単純に $scalar に追加されます。

=begin original

A more complex application of tracing to a layered filehandle is the
use of a custom layer (I<Refer to >L<Perlio::via> I<for details
on creating custom PerlIO layers.>). Consider an application with the
following logger module:

=end original

レイヤ化されたファイルハンドルへのトレースのより複雑なアプリケーションは、カスタムレイヤの使用です(I<参照>L<PerlIO::via>I<カスタムPerlIOレイヤの作成の詳細については>)。
次のロガーモジュールを持つアプリケーションを考えてみます。
(TBR)

    package MyFancyLogger;

    sub new
    {
        my $self = {};
        my $fh;
        open $fh, '>', 'fancylog.log';
        $self->{_fh} = $fh;
        $self->{_buf} = '';
        return bless $self, shift;
    }

    sub log
    {
        my $self = shift;
        return unless exists $self->{_fh};
        my $fh = $self->{_fh};
        $self->{_buf} .= shift;
    #
    # DBI feeds us pieces at a time, so accumulate a complete line
    # before outputing
    #
        print $fh "At ", scalar localtime(), ':', $self->{_buf}, "\n" and
        $self->{_buf} = ''
            if $self->{_buf}=~tr/\n//;
    }

    sub close {
        my $self = shift;
        return unless exists $self->{_fh};
        my $fh = $self->{_fh};
        print $fh "At ", scalar localtime(), ':', $self->{_buf}, "\n" and
        $self->{_buf} = ''
            if $self->{_buf};
        close $fh;
        delete $self->{_fh};
    }

    1;

=begin original

To redirect DBI traces to this logger requires creating
a package for the layer:

=end original

DBI トレースをこのロガーにリダイレクトするには、層のためのパッケージを作る
必要があります:

    package PerlIO::via::MyFancyLogLayer;

    sub PUSHED
    {
        my ($class,$mode,$fh) = @_;
        my $logger;
        return bless \$logger,$class;
    }

    sub OPEN {
        my ($self, $path, $mode, $fh) = @_;
        #
        # $path is actually our logger object
        #
        $$self = $path;
        return 1;
    }

    sub WRITE
    {
        my ($self, $buf, $fh) = @_;
        $$self->log($buf);
        return length($buf);
    }

    sub CLOSE {
        my $self = shift;
        $$self->close();
        return 0;
    }

    1;

=begin original

The application can then cause DBI traces to be routed to the
logger using

=end original

アプリケーションは、次のコマンドを使用して、DBIトレースをロガーにルーティングできます。
(TBR)

    use PerlIO::via::MyFancyLogLayer;

    open my $fh, '>:via(MyFancyLogLayer)', MyFancyLogger->new();

    $dbh->trace('SQL', $fh);

=begin original

Now all trace output will be processed by MyFancyLogger's
log() method.

=end original

ここで全てのトレース出力は MyFancyLogger の log() メソッドによって
処理されます。

=head2 Trace Content

(トレースの内容)

=begin original

Many of the values embedded in trace output are formatted using the neat()
utility function. This means they may be quoted, sanitized, and possibly
truncated if longer than C<$DBI::neat_maxlen>. See L</neat> for more details.

=end original

トレース出力に含まれている値の多くは neat() ユーティリティ関数を使って
フォーマットされます。
つまり、クォートされ、サニタイズされ、C<$DBI::neat_maxlen> より長い場合は
切り詰められるかもしれないことを意味します。
さらなる詳細については L</neat> を参照してください。

=head2 Tracing Tips

(トレースの小技)

=begin original

You can add tracing to your own application code using the L</trace_msg> method.

=end original

L</trace_msg> メソッドを使って自身のアプリケーションにトレースを
追加できます。

=begin original

It can sometimes be handy to compare trace files from two different runs of the
same script. However using a tool like C<diff> on the original log output
doesn't work well because the trace file is full of object addresses that may
differ on each run.

=end original

同じスクリプトの2つの異なる実行からのトレースファイルを比較すると便利な場合があります。
しかし、元のログ出力にC<diff>のようなツールを使用すると、トレースファイルが実行ごとに異なるオブジェクトアドレスでいっぱいになるため、うまく機能しません。
(TBR)

=begin original

The DBI includes a handy utility called dbilogstrip that can be used to
'normalize' the log content. It can be used as a filter like this:

=end original

DBIには、ログの内容を「正規化」するために使用できるdbilogstripと呼ばれる便利なユーティリティが含まれています。
これは、次のようなフィルタとして使用できます:
(TBR)

    DBI_TRACE=2 perl yourscript.pl ...args1... 2>&1 | dbilogstrip > dbitrace1.log
    DBI_TRACE=2 perl yourscript.pl ...args2... 2>&1 | dbilogstrip > dbitrace2.log
    diff -u dbitrace1.log dbitrace2.log

=begin original

See L<dbilogstrip> for more information.

=end original

さらなる情報については L<dbilogstrip> を参照してください。

=head1 DBI ENVIRONMENT VARIABLES

(DBI 環境変数)

=begin original

The DBI module recognizes a number of environment variables, but most of
them should not be used most of the time.
It is better to be explicit about what you are doing to avoid the need
for environment variables, especially in a web serving system where web
servers are stingy about which environment variables are available.

=end original

DBIモジュールは多数の環境変数を認識しますが、そのほとんどはほとんどの場合に使用されるべきではありません。
特に、Webサーバーがどの環境変数が使用可能であるかに関して厳密であるWebサービスシステムでは、環境変数の必要性を回避するために、何を行っているかを明示的に示すことをお薦めします。
(TBR)

=head2 DBI_DSN

=begin original

The DBI_DSN environment variable is used by DBI->connect if you do not
specify a data source when you issue the connect.
It should have a format such as "dbi:Driver:databasename".

=end original

DBI_DSN環境変数は、接続を発行するときにデータソースを指定しない場合に、DBI->connectによって使用されます。
この変数は、"dbi:Driver:databasename"のような形式にする必要があります。
(TBR)

=head2 DBI_DRIVER

=begin original

The DBI_DRIVER environment variable is used to fill in the database
driver name in DBI->connect if the data source string starts "dbi::"
(thereby omitting the driver).
If DBI_DSN omits the driver name, DBI_DRIVER can fill the gap.

=end original

DBI_DRIVER環境変数は、データソース文字列が「dbi::」で始まる場合に、DBI->connectでデータベースドライバ名を入力するために使用されます(これにより、ドライバが省略されます)。
DBI_DSNでドライバ名が省略された場合は、DBI_DRIVERでギャップを埋めることができます。
(TBR)

=head2 DBI_AUTOPROXY

=begin original

The DBI_AUTOPROXY environment variable takes a string value that starts
"dbi:Proxy:" and is typically followed by "hostname=...;port=...".
It is used to alter the behaviour of DBI->connect.
For full details, see DBI::Proxy documentation.

=end original

DBI_AUTOPROXY環境変数は、"dbi:Proxy:"で始まる文字列値を取り、通常は"hostname=.;port=."が続きます。
これは、DBI->connectの動作を変更するために使用されます。
詳細は、DBI::Proxyの文書を参照してください。
(TBR)

=head2 DBI_USER

=begin original

The DBI_USER environment variable takes a string value that is used as
the user name if the DBI->connect call is given undef (as distinct from
an empty string) as the username argument.
Be wary of the security implications of using this.

=end original

DBI_USER環境変数は、DBI->connect呼び出しにusername引数としてundef(空の文字列とは別の)が指定された場合に、ユーザ名として使用される文字列値を取ります。
これを使用することによるセキュリティへの影響に注意してください。
(TBR)

=head2 DBI_PASS

=begin original

The DBI_PASS environment variable takes a string value that is used as
the password if the DBI->connect call is given undef (as distinct from
an empty string) as the password argument.
Be extra wary of the security implications of using this.

=end original

DBI_PASS環境変数は、DBI->接続呼び出しがパスワード引数としてundef(空の文字列とは異なる)を指定された場合に、パスワードとして使用される文字列値を取ります。
これを使用することによるセキュリティへの影響には特に注意してください。
(TBR)

=head2 DBI_DBNAME (obsolete)

=begin original

The DBI_DBNAME environment variable takes a string value that is used only when the
obsolescent style of DBI->connect (with driver name as fourth parameter) is used, and
when no value is provided for the first (database name) argument.

=end original

DBI_DBNAME環境変数は、旧式のDBI->connect(4番目のパラメータとしてドライバ名を使用)が使用され、最初の(データベース名)引数に値が指定されていない場合にのみ使用される文字列値を取ります。
(TBR)

=head2 DBI_TRACE

=begin original

The DBI_TRACE environment variable specifies the global default
trace settings for the DBI at startup. Can also be used to direct
trace output to a file. When the DBI is loaded it does:

=end original

DBI_TRACE環境変数は、起動時のDBIのグローバルデフォルトトレース設定を指定します。
トレース出力をファイルに送るためにも使用できます。
DBIがロードされると、次の処理が行われます。
(TBR)

  DBI->trace(split /=/, $ENV{DBI_TRACE}, 2) if $ENV{DBI_TRACE};

=begin original

So if C<DBI_TRACE> contains an "C<=>" character then what follows
it is used as the name of the file to append the trace to.

=end original

したがって、C<DBI_TRACE>に「C<=>」文字が含まれている場合は、その後に続く文字がトレースを追加するファイルの名前として使用されます。
(TBR)

=begin original

output appended to that file. If the name begins with a number
followed by an equal sign (C<=>), then the number and the equal sign are
stripped off from the name, and the number is used to set the trace
level. For example:

=end original

出力はこのファイルに追加されます。
もしファイル名が数字で始まり、後ろに等号(C<=>)がついているのであれば、
数字と等号は名前から切り離され、数字はトレースレベルを設定するのに
使われます。
例えば:

  DBI_TRACE=1=dbitrace.log perl your_test_script.pl

=begin original

On Unix-like systems using a Bourne-like shell, you can do this easily
on the command line:

=end original

unix のようなシステムで Bourne のようなシェルを使っていれば、これを
コマンドラインで簡単に行うことができます:

  DBI_TRACE=2 perl your_test_script.pl

=begin original

See L</TRACING> for more information.

=end original

さらなる情報については L</TRACING> を参照してください。

=head2 PERL_DBI_DEBUG (obsolete)

=begin original

An old variable that should no longer be used; equivalent to DBI_TRACE.

=end original

もはや使うべきではない古い変数です; DBI_TRACE と等価です。

=head2 DBI_PROFILE

=begin original

The DBI_PROFILE environment variable can be used to enable profiling
of DBI method calls. See L<DBI::Profile> for more information.

=end original

DBI_PROFILE 環境変数は DBI メソッド呼び出しのプロファイリングを
有効にするために使われます。
さらなる情報については L<DBI::Profile> を参照してください。

=head2 DBI_PUREPERL

=begin original

The DBI_PUREPERL environment variable can be used to enable the
use of DBI::PurePerl.  See L<DBI::PurePerl> for more information.

=end original

DBI_PUREPERL 環境変数は DBI::PurePerl の使用を有効にするために
使われます。
さらなる情報については L<DBI::PurePerl> を参照してください。

=head1 WARNING AND ERROR MESSAGES

(警告とエラーメッセージ)

=head2 Fatal Errors

(致命的エラー)

=over 4

=item Can't call method "prepare" without a package or object reference

=begin original

The C<$dbh> handle you're using to call C<prepare> is probably undefined because
the preceding C<connect> failed. You should always check the return status of
DBI methods, or use the L</RaiseError> attribute.

=end original

おそらく以前の C<connect> が失敗したために、C<prepare> 呼び出しに使った
C<$dbh> ハンドルが未定義です。
DBI メソッドの戻りステータスを常にチェックするか、L</RaiseError> 属性を
使わなければりません。 

=item Can't call method "execute" without a package or object reference

=begin original

The C<$sth> handle you're using to call C<execute> is probably undefined because
the preceding C<prepare> failed. You should always check the return status of
DBI methods, or use the L</RaiseError> attribute.

=end original

おそらく以前の C<prepare> メソッドが失敗したために、C<execute> 呼び出しに
使った C<$sth> ハンドルが未定義です。
DBI メソッドの戻りステータスを常にチェックするか、L</RaiseError> 属性を
使わなければりません。 

=item DBI/DBD internal version mismatch

=begin original

The DBD driver module was built with a different version of DBI than
the one currently being used.  You should rebuild the DBD module under
the current version of DBI.

=end original

DBD ドライバモジュールが、現在使っている DBI とは異なるバージョンで
ビルドされています。
現在のバージョンの DBI のもとで DBD モジュールを
リビルドしなければなりません。 

=begin original

(Some rare platforms require "static linking". On those platforms, there
may be an old DBI or DBD driver version actually embedded in the Perl
executable being used.)

=end original

(まれにですが、いくつかプラットホームは「静的リンク」(static linking) を
要求します。
古い DBI もしくは DBD ドライバが、使われている Perl の実行可能ファイルに
実際に埋め込まれているのかもしれません。)

=item DBD driver has not implemented the AutoCommit attribute

=begin original

The DBD driver implementation is incomplete. Consult the author.

=end original

DBD ドライバの実装が完全ではありません。
作者に聞いてみてください。 

=item Can't [sg]et %s->{%s}: unrecognised attribute

=begin original

You attempted to set or get an unknown attribute of a handle.  Make
sure you have spelled the attribute name correctly; case is significant
(e.g., "Autocommit" is not the same as "AutoCommit").

=end original

ハンドルの不明な属性を設定または取得しようとしました。
属性の名前が正しいかを確認してください; 大文字／小文字は意味があります
(例えば "Autocommit" は "AutoCommit" と同じではありません)。

=back

=head1 Pure-Perl DBI

(ピュア Perl の DBI)

=begin original

A pure-perl emulation of the DBI is included in the distribution
for people using pure-perl drivers who, for whatever reason, can't
install the compiled DBI. See L<DBI::PurePerl>.

=end original

なんらかの理由によってコンパイルされた DBI をインストールできないために
ピュア Perl ドライバを使う人々のために、DBI の
ピュア Perl エミュレーションがこの配布に含まれています。
L<DBI::PurePerl> を参照してください。

=head1 SEE ALSO

=head2 Driver and Database Documentation

(ドライバとデータベースのドキュメント)

=begin original

Refer to the documentation for the DBD driver that you are using.

=end original

使っている DBD ドライバのドキュメントをご覧下さい。

=begin original

Refer to the SQL Language Reference Manual for the database engine that you are using.

=end original

使っているデータベース・エンジンのための SQL 言語
リファレンスマニュアルをご覧下さい。

=head2 ODBC and SQL/CLI Standards Reference Information

(ODBC と SQL/CLI 標準の参照情報)

=begin original

More detailed information about the semantics of certain DBI methods
that are based on ODBC and SQL/CLI standards is available on-line
via microsoft.com, for ODBC, and www.jtc1sc32.org for the SQL/CLI
standard:

=end original

ODBCおよびSQL/CLI標準に基づく特定のDBIメソッドのセマンティクスの詳細については、microsoft.com(ODBCの場合)およびwww.jtc1sc32.org(SQL/CLI標準の場合)からオンラインで入手できます。
(TBR)

 DBI method        ODBC function     SQL/CLI Working Draft
 ----------        -------------     ---------------------
 column_info       SQLColumns        Page 124
 foreign_key_info  SQLForeignKeys    Page 163
 get_info          SQLGetInfo        Page 214
 primary_key_info  SQLPrimaryKeys    Page 254
 table_info        SQLTables         Page 294
 type_info         SQLGetTypeInfo    Page 239
 statistics_info   SQLStatistics

=begin original

To find documentation on the ODBC function you can use
the MSDN search facility at:

=end original

ODBC関数に関する文書を検索するには、次のMSDN検索機能を使用します。
(TBR)

    http://msdn.microsoft.com/Search

=begin original

and search for something like C<"SQLColumns returns">.

=end original

そして C<"SQLColumns returns"> のような形で検索してください。

=begin original

And for SQL/CLI standard information on SQLColumns you'd read page 124 of
the (very large) SQL/CLI Working Draft available from:

=end original

SQLColumnsに関するSQL/CLIの標準情報については、次のWebサイトで入手可能な(非常に大規模な)SQL/CLI Working Draftの124ページを参照してください。
(TBR)

  http://jtc1sc32.org/doc/N0701-0750/32N0744T.pdf

=head2 Standards Reference Information

(標準の参照情報)

=begin original

A hyperlinked, browsable version of the BNF syntax for SQL92 (plus
Oracle 7 SQL and PL/SQL) is available here:

=end original

SQL92 (plus Oracle 7 SQL and PL/SQL) の BNF 文法の
ハイパーリンク付きでブラウズ可能な版は以下で利用可能です:

  http://cui.unige.ch/db-research/Enseignement/analyseinfo/SQL92/BNFindex.html

=begin original

A BNF syntax for SQL3 is available here:

=end original

SQL3 の BNF 文法は以下で利用可能です:

  http://www.sqlstandards.org/SC32/WG3/Progression_Documents/Informal_working_drafts/iso-9075-2-1999.bnf

=begin original

The following links provide further useful information about SQL.
Some of these are rather dated now but may still be useful.

=end original

以下のリンクは SQL に関するさらに有用な情報を提供します。
これらの一部はやや時間が経っていますが今でも有用です。

  http://www.jcc.com/SQLPages/jccs_sql.htm
  http://www.contrib.andrew.cmu.edu/~shadow/sql.html
  http://www.altavista.com/query?q=sql+tutorial

=head2 Books and Articles

(書籍と記事)

=begin original

Programming the Perl DBI, by Alligator Descartes and Tim Bunce.
L<http://books.perl.org/book/154>

=end original

Programming the Perl DBI, by Alligator Descartes and Tim Bunce.
L<http://books.perl.org/book/154>
(訳注: 入門Perl DBI)

=begin original

Programming Perl 3rd Ed. by Larry Wall, Tom Christiansen & Jon Orwant.
L<http://books.perl.org/book/134>

=end original

Programming Perl 3rd Ed. by Larry Wall, Tom Christiansen & Jon Orwant.
L<http://books.perl.org/book/134>
(訳注: プログラミング Perl)

=begin original

Learning Perl by Randal Schwartz.
L<http://books.perl.org/book/101>

=end original

Learning Perl by Randal Schwartz.
L<http://books.perl.org/book/101>
(訳注: 初めてのPerl)

=begin original

Details of many other books related to perl can be found at L<http://books.perl.org>

=end original

その他の perl に関する多くの本の詳細は L<http://books.perl.org> にあります。

=head2 Perl Modules

(Perl モジュール)

=begin original

Index of DBI related modules available from CPAN:

=end original

CPAN から利用可能な DBI 関連モジュールのインデックス:

 http://search.cpan.org/search?mode=module&query=DBIx%3A%3A
 http://search.cpan.org/search?mode=doc&query=DBI

=begin original

For a good comparison of RDBMS-OO mappers and some OO-RDBMS mappers
(including Class::DBI, Alzabo, and DBIx::RecordSet in the former
category and Tangram and SPOPS in the latter) see the Perl
Object-Oriented Persistence project pages at:

=end original

RDBMS-OO マッパーと OO-RDBMS マッパー(前者は Class::DBI, Alzabo,
DBIx::RecordSet、後者は Tangram と SPOPS)の良い比較については
以下の Perl Object-Oriented Persistence プロジェクトを参照してください:

 http://poop.sourceforge.net

=begin original

A similar page for Java toolkits can be found at:

=end original

Java ツールキットのための似たようなページは以下にあります:

 http://c2.com/cgi-bin/wiki?ObjectRelationalToolComparison

=head2 Mailing List

(メーリングリスト)

=begin original

The I<dbi-users> mailing list is the primary means of communication among
users of the DBI and its related modules. For details send email to:

=end original

I<dbi-users> メーリングリストは DBI とその関連するモジュールの利用者の
コミュニケーションを第一の目的としています。
詳細については下記のアドレスにメールを送ってください:

 dbi-users-help@perl.org

=begin original

There are typically between 700 and 900 messages per month.  You have
to subscribe in order to be able to post. However you can opt for a
'post-only' subscription.

=end original

通常 1 ヶ月に 700 から 900 のメッセージがあります。
投稿できるようになるためには加入しなければなりません。
しかしオプションで「投稿のみ」(post-only)の参加を選択することができます。

=begin original

Mailing list archives (of variable quality) are held at:

=end original

(様々な品質の) メーリングリストのアーカイブは以下のサイトにあります:

 http://groups.google.com/groups?group=perl.dbi.users
 http://www.xray.mpe.mpg.de/mailing-lists/dbi/
 http://www.mail-archive.com/dbi-users%40perl.org/

=head2 Assorted Related WWW Links

(様々な関係する WWW リンク)

=begin original

The DBI "Home Page":

=end original

DBI "ホームページ":

 http://dbi.perl.org/

=begin original

Other DBI related links:

=end original

その他のDBI関連のリンク:

 http://tegan.deltanet.com/~phlip/DBUIdoc.html
 http://dc.pm.org/perl_db.html
 http://wdvl.com/Authoring/DB/Intro/toc.html
 http://www.hotwired.com/webmonkey/backend/tutorials/tutorial1.html
 http://bumppo.net/lists/macperl/1999/06/msg00197.html
 http://gmax.oltrelinux.com/dbirecipes.html

=begin original

Other database related links:

=end original

その他のデータベース関連のリンク:

 http://www.jcc.com/sql_stnd.html
 http://cuiwww.unige.ch/OSG/info/FreeDB/FreeDB.home.html
 http://www.connectionstrings.com/

=begin original

Security, especially the "SQL Injection" attack:

=end original

セキュリティ、特に「SQL インジェクション」攻撃:

 http://www.ngssoftware.com/research/papers.html
 http://www.ngssoftware.com/papers/advanced_sql_injection.pdf
 http://www.ngssoftware.com/papers/more_advanced_sql_injection.pdf
 http://www.esecurityplanet.com/trends/article.php/2243461
 http://www.spidynamics.com/papers/SQLInjectionWhitePaper.pdf
 http://www.imperva.com/application_defense_center/white_papers/blind_sql_server_injection.html
 http://online.securityfocus.com/infocus/1644

=begin original

Commercial and Data Warehouse Links

=end original

商用およびデータウェアハウスのリンク:

 http://www.dwinfocenter.org
 http://www.datawarehouse.com
 http://www.datamining.org
 http://www.olapcouncil.org
 http://www.idwa.org
 http://www.knowledgecenters.org/dwcenter.asp

=begin original

Recommended Perl Programming Links

=end original

推奨される Perl プログラミングのリンク

 http://language.perl.com/style/

=head2 FAQ

=begin original

See L<http://faq.dbi-support.com/>

=end original

L<http://faq.dbi-support.com/> を参照してください。

=head1 AUTHORS

=begin original

DBI by Tim Bunce, L<http://www.tim.bunce.name>

=end original

DBI は Tim Bunce, L<http://www.tim.bunce.name>

=begin original

This pod text by Tim Bunce, J. Douglas Dunlop, Jonathan Leffler and others.
Perl by Larry Wall and the C<perl5-porters>.

=end original

この pod 文書は Tim Bunce, J. Douglas Dunlop, Jonathan Leffler および
その他の人たち。
Perl は Larry Wall および the C<perl5-porters>。

=head1 COPYRIGHT

=begin original

The DBI module is Copyright (c) 1994-2009 Tim Bunce. Ireland.
All rights reserved.

=end original

DBIモジュールは、Copyright(c)1994-2009 Tim Bunce.Ireland.All rights reserved.
(TBR)

=begin original

You may distribute under the terms of either the GNU General Public
License or the Artistic License, as specified in the Perl 5.10.0 README file.

=end original

Perl 5.10.0 READMEファイルに指定されているように、GNU General Public LicenseまたはArtistic Licenseのいずれかの条件に基づいて配布できます。
(TBR)

=head1 SUPPORT / WARRANTY

(サポート / 保証)

=begin original

The DBI is free Open Source software. IT COMES WITHOUT WARRANTY OF ANY KIND.

=end original

DBI はオープンソースソフトウェアです。
いかなる保証もおこないません。

=head2 Support

(サポート)

=begin original

My consulting company, Data Plan Services, offers annual and
multi-annual support contracts for the DBI. These provide sustained
support for DBI development, and sustained value for you in return.
Contact me for details.

=end original

私のコンサルタント会社である Data Plan Services は DBI に対する一年および
複数年のサポート契約を提供しています。
これらは DBI 開発に対する持続的なサポートを提供し、あなたに持続的な
価値を提供します。
詳しくは私に連絡を取ってください。

=head2 Sponsor Enhancements

(スポンサー拡張)

=begin original

The DBI Roadmap is available at L<http://search.cpan.org/~timb/DBI/Roadmap.pod>

=end original

DBI ロードマップは L<http://search.cpan.org/~timb/DBI/Roadmap.pod> に
あります。

=begin original

If your company would benefit from a specific new DBI feature,
please consider sponsoring its development.  Work is performed
rapidly, and usually on a fixed-price payment-on-delivery basis.
Contact me for details.

=end original

あなたの会社が特定の新しいDBI機能の恩恵を受けるのであれば、その開発を支援することを検討してください。
作業は迅速に行われ、通常は固定価格の着払いベースで行われます。
詳細については私に連絡してください。
(TBR)

=begin original

Using such targeted financing allows you to contribute to DBI
development, and rapidly get something specific and valuable in return.

=end original

このような対象を絞った融資を利用することで、DBIの開発に貢献し、その見返りとして特定の価値のあるものを迅速に得ることができます。
(TBR)

=head1 ACKNOWLEDGEMENTS

=begin original

I would like to acknowledge the valuable contributions of the many
people I have worked with on the DBI project, especially in the early
years (1992-1994). In no particular order: Kevin Stock, Buzz Moschetti,
Kurt Andersen, Ted Lemon, William Hails, Garth Kennedy, Michael Peppler,
Neil S. Briscoe, Jeff Urlwin, David J. Hughes, Jeff Stander,
Forrest D Whitcher, Larry Wall, Jeff Fried, Roy Johnson, Paul Hudson,
Georg Rehfeld, Steve Sizemore, Ron Pool, Jon Meek, Tom Christiansen,
Steve Baumgarten, Randal Schwartz, and a whole lot more.

=end original

DBIプロジェクトで、とりわけ最初のころ(1992-1994)に、多大な貢献してくれた
多くの人に感謝します。
順不同で、Kevin Stock, Buzz Moschetti,
Kurt Andersen, Ted Lemon, William Hails, Garth Kennedy, Michael Peppler,
Neil S. Briscoe, Jeff Urlwin, David J. Hughes, Jeff Stander,
Forrest D Whitcher, Larry Wall, Jeff Fried, Roy Johnson, Paul Hudson,
Georg Rehfeld, Steve Sizemore, Ron Pool, Jon Meek, Tom Christiansen,
Steve Baumgarten, Randal Schwartz 他の多くのみなさん。

=begin original

Then, of course, there are the poor souls who have struggled through
untold and undocumented obstacles to actually implement DBI drivers.
Among their ranks are Jochen Wiedmann, Alligator Descartes, Jonathan
Leffler, Jeff Urlwin, Michael Peppler, Henrik Tougaard, Edwin Pratomo,
Davide Migliavacca, Jan Pazdziora, Peter Haworth, Edmund Mergl, Steve
Williams, Thomas Lowery, and Phlip Plumlee. Without them, the DBI would
not be the practical reality it is today.  I'm also especially grateful
to Alligator Descartes for starting work on the first edition of the
"Programming the Perl DBI" book and letting me jump on board.

=end original

そしてもちろん、DBI ドライバ実装への語られないそして文書化されていない
障害と葛藤し、やりとげた哀れな人々にも。
順番をつけると、Jochen Wiedmann, Alligator Descartes, Jonathan
Leffler, Jeff Urlwin, Michael Peppler, Henrik Tougaard, Edwin Pratomo,
Davide Migliavacca, Jan Pazdziora, Peter Haworth, Edmund Mergl, Steve
Williams, Thomas Lowery, Phlip Plumlee。
彼ら無しには DBI は今日のような実際のリアリテイをもたなかったでしょう。
また本 "Programming the Perl DBI" 第一版を始め、参加させてくれた
Alligator Descartes にも特に感謝します。

=begin original

The DBI and DBD::Oracle were originally developed while I was Technical
Director (CTO) of Ingeneering in the UK (L<http://www.ig.co.uk>) (formerly known as the
Paul Ingram Group).  So I'd especially like to thank Paul for his generosity
and vision in supporting this work for many years.

=end original

DBI と DBD::Oracle はもともと私がイギリスの (以前は Paul Ingram Group として
知られていた) Ingeneering の CTO であった間に開発されました。
それで、長年にわたってこの作業を支えてくれた寛大さと先見性に対して、
特に Paul に感謝したいと思います。

=begin original

A couple of specific DBI features have been sponsored by enlightened companies:

=end original

二つの DBI 機能は啓発的な企業によりスポンサーされました:

=begin original

The development of the swap_inner_handle() method was sponsored by BizRate.com (L<http://BizRate.com>)

=end original

swap_inner_handle() メソッドの開発は BizRate.com
(L<http://BizRate.com>) のスポンサーによるものです。

=begin original

The development of DBD::Gofer and related modules was sponsored by
Shopzilla.com (L<http://Shopzilla.com>), where I currently work.

=end original

DBD::Gofer および関連するモジュールの開発は私が現在働いている
Shopzilla.com (L<http://Shopzilla.com>) のスポンサーによるものです。

=head1 CONTRIBUTING

(寄与する)

=begin original

As you can see above, many people have contributed to the DBI and
drivers in many ways over many years.

=end original

上述したように、多くの人々が長年にわたって様々な方法で DBI と
ドライバに寄与してきました。

=begin original

If you'd like to help then see L<http://dbi.perl.org/contributing>
and L<http://search.cpan.org/~timb/DBI/Roadmap.pod>

=end original

もし助けようと思ったなら、L<http://dbi.perl.org/contributing> と
L<http://search.cpan.org/~timb/DBI/Roadmap.pod> を参照してください。

=begin original

If you'd like the DBI to do something new or different then a good way
to make that happen is to do it yourself and send me a patch to the
source code that shows the changes. (But read "Speak before you patch"
below.)

=end original

DBI に対して何か新しいか異なったことをしようと思ったら、自分でそれを
行って、変更点が分かるソースコードのパッチを送ってください。
(しかし後述する L</Speak before you patch> を読んでください。)

=head2 Browsing the source code repository

(ソースコードレポジトリを見る)

=begin original

Use http://svn.perl.org/modules/dbi/trunk (basic)
or  http://svn.perl.org/viewcvs/modules/ (more useful)

=end original

http://svn.perl.org/modules/dbi/trunk (基本) か
http://svn.perl.org/viewcvs/modules/ (より有用) を使ってください。

=head2 How to create a patch using Subversion

(Subversion を使ってパッチを作る方法)

=begin original

The DBI source code is maintained using Subversion (a replacement
for CVS, see L<http://subversion.tigris.org/>). To access the source
you'll need to install a Subversion client. Then, to get the source
code, do:

=end original

DBI のソースコードは Subversion (CVS の代替物です; 
L<http://subversion.tigris.org/> を参照してください) を使って
保守されています。
ソースにアクセスするためには、Subversion クライアントを
インストールする必要があります。
それから、ソースコードを取得するには、以下のようにします:

  svn checkout http://svn.perl.org/modules/dbi/trunk

=begin original

If it prompts for a username and password use your perl.org account
if you have one, else just 'guest' and 'guest'. The source code will
be in a new subdirectory called C<trunk>.

=end original

ユーザー名とパスワードを聞かれたら、もし perl.org のアカウントがあれば
それを、さもなければ単に 'guest' と 'guest' を使ってください。
ソースコードは C<trunk> と呼ばれる新しいディレクトリの下にあります。

=begin original

To keep informed about changes to the source you can send an empty email
to svn-commit-modules-dbi-subscribe@perl.org after which you'll get an email
with the change log message and diff of each change checked-in to the source.

=end original

To keep informed about changes to the source you can send an empty email
to svn-commit-modules-dbi-subscribe@perl.org after which you'll get an email
with the change log message and diff of each change checked-in to the source.
(TBR)

=begin original

After making your changes you can generate a patch file, but before
you do, make sure your source is still up to date using:

=end original

After making your changes you can generate a patch file, but before
you do, make sure your source is still up to date using:
(TBR)

  svn update

=begin original

If you get any conflicts reported you'll need to fix them first.
Then generate the patch file from within the C<trunk> directory using:

=end original

If you get any conflicts reported you'll need to fix them first.
Then generate the patch file from within the C<trunk> directory using:
(TBR)

  svn diff > foo.patch

=begin original

Read the patch file, as a sanity check, and then email it to dbi-dev@perl.org.

=end original

サニティチェックとしてパッチファイルを読んでから、 dbi-dev@perl.org に
メールを送ってください。

=head2 How to create a patch without Subversion

(Subversion なしでパッチを作る方法)

=begin original

Unpack a fresh copy of the distribution:

=end original

最新版のディストリビューションを展開します:

  tar xfz DBI-1.40.tar.gz

=begin original

Rename the newly created top level directory:

=end original

新しく作ったトップレベルディレクトリに名前を変えます:

  mv DBI-1.40 DBI-1.40.your_foo

=begin original

Edit the contents of DBI-1.40.your_foo/* till it does what you want.

=end original

必要なだけ DBI-1.40.your_foo/* の内容を変更します。

=begin original

Test your changes and then remove all temporary files:

=end original

変更をテストして、全ての一時ファイルを削除します:

  make test && make distclean

=begin original

Go back to the directory you originally unpacked the distribution:

=end original

最初にディストリビューションを展開したディレクトリに戻ります:

  cd ..

=begin original

Unpack I<another> copy of the original distribution you started with:

=end original

元のディストリビューションを I<もう一度> 展開します:

  tar xfz DBI-1.40.tar.gz

=begin original

Then create a patch file by performing a recursive C<diff> on the two
top level directories:

=end original

二つのトップレベルディレクトリに対して再帰的に C<diff> を実行することで
パッチファイルを作成します:

  diff -r -u DBI-1.40 DBI-1.40.your_foo > DBI-1.40.your_foo.patch

=head2 Speak before you patch

(パッチする前に話してみる)

=begin original

For anything non-trivial or possibly controversial it's a good idea
to discuss (on dbi-dev@perl.org) the changes you propose before
actually spending time working on them. Otherwise you run the risk
of them being rejected because they don't fit into some larger plans
you may not be aware of.

=end original

普通でない、あるいは議論の余地があるかもしれないものついては、
実際に作業に時間を費やす前に考えている変更について
(dbi-dev@perl.org で)議論するのはよい考えです。
さもなければ、あなたが気付いていなかったより大きな計画に合わないという理由で
拒否されるリスクがあります。

=head1 TRANSLATIONS

(翻訳)

=begin original

A German translation of this manual (possibly slightly out of date) is
available, thanks to O'Reilly, at:

=end original

このマニュアルのドイツ語版が(ちょっと古いかもしれませんが)以下のサイトに
あります; O'Reilly に感謝します:

  http://www.oreilly.de/catalog/perldbiger/

=begin original

Some other translations:

=end original

その他の翻訳:

 http://cronopio.net/perl/                              - Spanish
 http://member.nifty.ne.jp/hippo2000/dbimemo.htm        - Japanese

=head1 TRAINING

(トレーニング)

=begin original

References to DBI related training resources. No recommendation implied.

=end original

DBIに関連したトレーニングへのリファレンスです。
何ら推奨するわけではありません。

  http://www.treepax.co.uk/
  http://www.keller.com/dbweb/

=begin original

(If you offer professional DBI related training services,
please send me your details so I can add them here.)

=end original

(もしあなたがプロフェッショナルな DBI 関係のトレーニングサービスを
提供しているなら、詳細をメールしてもらえればここに追加します。)

=head1 OTHER RELATED WORK AND PERL MODULES

(その他の関係する作品と Perl モジュール)

=over 4

=item Apache::DBI by E.Mergl@bawue.de

=begin original

To be used with the Apache daemon together with an embedded Perl
interpreter like C<mod_perl>. Establishes a database connection which
remains open for the lifetime of the HTTP daemon. This way the CGI
connect and disconnect for every database access becomes superfluous.

=end original

C<mod_perl> のような埋め込み型 perl インタプリタとともに Apache デーモンで
使われます。
http デーモンが生きている間ずっと開かれるデータベース接続を確立します。
これにより CGI がデータベースにアクセスする度に接続、切断することが不必要に
なります。

=item SQL Parser

=begin original

See also the L<SQL::Statement> module, SQL parser and engine.

=end original

SQL パーサとエンジンである L<SQL::Statement> モジュールも参照してください。

=back

=cut

=begin meta

Translated: 川合孝典 <GCD00051@nifty.ne.jp> (1.19)
Updated: SHIRAKATA Kentaro <argrath@ub32.org> (1.612)
Status: stalled

=end meta