argra****@users*****
argra****@users*****
2011年 12月 22日 (木) 19:36:26 JST
Index: docs/modules/DBI-1.612/DBI.pod
diff -u docs/modules/DBI-1.612/DBI.pod:1.1 docs/modules/DBI-1.612/DBI.pod:1.2
--- docs/modules/DBI-1.612/DBI.pod:1.1 Wed Dec 21 03:34:11 2011
+++ docs/modules/DBI-1.612/DBI.pod Thu Dec 22 19:36:26 2011
@@ -82,6 +82,8 @@
=head2 GETTING HELP
+(助けを得る)
+
=begin original
If you have questions about DBI, or DBD driver modules, you can get
@@ -199,6 +201,8 @@
=head2 NOTES
+(注意)
+
=begin original
This is the DBI specification that corresponds to the DBI version 1.612
@@ -312,6 +316,8 @@
=head2 Architecture of a DBI Application
+(DBI アプリケーションのアーキテクチャ)
+
|<- Scope of DBI ->|
.-. .--------------. .-------------.
.-------. | |---| XYZ Driver |---| XYZ Engine |
@@ -368,6 +374,8 @@
=head2 Notation and Conventions
+(記法と規約)
+
=begin original
The following conventions are used in this document:
@@ -396,12 +404,12 @@
$sth ステートメントハンドルオブジェクト
$drh ドライバハンドルオブジェクト(アプリケーションで目にしたり、使ったりすることはまずありません)
$h 上記のハンドルのどれか
- $rc 一般的な戻り値(コード)(ブール値: true=ok, false=error)
+ $rc 一般的な戻り値(コード)(真偽値: 真=OK, 偽=エラー)
$rv 一般的な戻り値(値) (通常はinteger)
@ary データベースから返される値のリスト。通常はデータの行
$rows 処理された行の数 (もしあれば。なければ -1)
$fh ファイルハンドル
- undef PerlではNULL値は未定義値で表現される
+ undef Perl では NULL値は未定義値で表現される
\%attr メソッドに渡される属性値のハッシュのリファレンス
=begin original
@@ -416,6 +424,8 @@
=head2 Outline Usage
+(使用法の概要)
+
=begin original
To use DBI,
@@ -583,6 +593,8 @@
=head2 General Interface Rules & Caveats
+(一般的なインターフェース規則と留意事項)
+
=begin original
The DBI does not have a concept of a "current session". Every session
@@ -722,6 +734,8 @@
=head2 Naming Conventions and Name Space
+(命名規則と名前空間)
+
=begin original
The DBI package and all packages below it (C<DBI::*>) are reserved for
@@ -766,11 +780,11 @@
=end original
-名前の大文字／小文字 説 明
----------------------- -------------------------------------------
-大文字のみ(UPPER_CASE) 標準、つまり X/Open, SQL92 など(移植性あり)
-混合(MixedCase) DBI API(移植性性あり)アンダースコア(_)は使わない
-小文字のみ(lower_case) ドライバもしくはエンジンに特有(移植性なし)
+ 名前の大文字／小文字 説明
+ ---------------------- -------------------------------------------
+ 大文字のみ(UPPER_CASE) 標準、つまり X/Open, SQL92 など(移植性あり)
+ 混合(MixedCase) DBI API(移植性性あり)アンダースコア(_)は使わない
+ 小文字のみ(lower_case) ドライバもしくはエンジンに特有(移植性なし)
=begin original
@@ -789,6 +803,8 @@
=head2 SQL - A Query Language
+(SQL - 問い合わせ言語)
+
=begin original
Most DBI drivers require applications to use a dialect of SQL
@@ -848,6 +864,8 @@
=head2 Placeholders and Bind Values
+(プレースホルダとバインド値)
+
=begin original
Some drivers support placeholders and bind values.
@@ -966,7 +984,7 @@
=end original
-B<NULL Values>
+B<NULL 値>
(TBT)
=begin original
@@ -1315,6 +1333,8 @@
=head1 THE DBI PACKAGE AND CLASS
+(DBI パッケージとクラス)
+
=begin original
In this section, we cover the DBI class methods, utility functions,
@@ -1327,6 +1347,8 @@
=head2 DBI Constants
+(DBI 定数)
+
=begin original
Constants representing the values of the SQL standard types can be
@@ -1390,6 +1412,8 @@
=head2 DBI Class Methods
+(DBI クラスメソッド)
+
=begin original
The following methods are provided by the DBI class:
@@ -1668,7 +1692,7 @@
=end original
-C<$data_source 引数 ( "C<dbi:...:>" という接頭辞をとったもの)と
+C<$data_source> 引数 ( "C<dbi:...:>" という接頭辞をとったもの)と
C<$username>, C<$password> の引数は、処理のためドライバに渡されます。
DBI はこれらのフィールドの内容の解釈について何も定義していません。
ドライバは C<$data_source>, C<$username>, C<$password> のフィールドを、
@@ -2270,6 +2294,8 @@
=head2 DBI Utility Functions
+(DBI ユーティリティ関数)
+
=begin original
In addition to the DBI methods listed in the previous section,
@@ -2760,6 +2786,8 @@
=head2 DBI Dynamic Attributes
+(DBI 動的属性)
+
=begin original
Dynamic attributes are always associated with the I<last handle used>
@@ -2859,6 +2887,8 @@
=head1 METHODS COMMON TO ALL HANDLES
+(全てのハンドルに共通のメソッド)
+
=begin original
The following methods can be used by all types of DBI handles.
@@ -3637,6 +3667,8 @@
=head1 ATTRIBUTES COMMON TO ALL HANDLES
+(全てのハンドルに共通の属性)
+
=begin original
These attributes are common to all types of DBI handles.
@@ -5494,6 +5526,8 @@
=head1 DBI DATABASE HANDLE OBJECTS
+(DBI データベースハンドルオブジェクト)
+
=begin original
This section covers the methods and attributes associated with
@@ -5505,6 +5539,8 @@
=head2 Database Handle Methods
+(データベースハンドルメソッド)
+
=begin original
The following methods are specified for DBI database handles:
@@ -8597,7 +8633,7 @@
=end original
データ型定義のためのパラメータ名。
-例えば C<DECIMAL が C<DECIMAL(>I<precision,scale>C<)> (全体桁数,小数点以下桁数)、
+例えば 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>"(最大長)になります。
@@ -9150,12 +9186,15 @@
=head2 Database Handle Attributes
+(データベースハンドル属性)
+
=begin original
This section describes attributes specific to database handles.
=end original
+このセクションではデータベースハンドルに特有の属性について記述します。
=begin original
@@ -9164,6 +9203,9 @@
=end original
+これらのデータベースハンドル属性を変更しても、既存の他の
+データベースハンドルあるいはこの後、生成されるデータベースハンドルには
+影響を与えません。
=begin original
@@ -9173,6 +9215,9 @@
=end original
+ドライバ毎のプライベートな属性(属性は名前が小文字ではじまります)を
+除いては、決められていない属性を設定あるいは取得しようとすると
+警告が発生します。
=begin original
@@ -9180,6 +9225,7 @@
=end original
+例:
$h->{AutoCommit} = ...; # set/write
... = $h->{AutoCommit}; # get/read
@@ -9195,6 +9241,11 @@
=end original
+真であれば、データベースの変更をロールバックする(元に戻す)ことは
+できません。
+偽であれば、データベースの変更は自動的に「トランザクション」の中に入り、
+C<commit> または C<rollback> メソッドを使ってコミットあるいは
+ロールバックされなければなりません。
=begin original
@@ -9203,6 +9254,8 @@
=end original
+ドライバはデフォルトを C<AutoCommit> モードにしなければいけません
+(ODBC と JDBC の決まりにより、残念ながら DBI はこうせざるを得ません。)
=begin original
@@ -9214,6 +9267,13 @@
=end original
+C<AutoCommit> をサポートされていない値に設定しようとすると、致命的な
+エラーになります。
+これは DBI の重要な機能です。
+完全なトランザクションを必要とするアプリケーションは、値が正しく代入されたか
+どうかをチェックすることなく C<$dbh-E<gt>{AutoCommit} = 0> と
+する(または L</connect> メソッドでの C<AutoCommit> を 0 に設定する)ことが
+できます。
=begin original
@@ -9222,17 +9282,27 @@
=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
@@ -9242,6 +9312,10 @@
=end original
+これらのデータベースで、C<AutoCommit> をオフにしようとすると
+致命的エラーになります。
+C<commit>, C<rollback> は C<AutoCommit> が有効な間は無効であるという
+警告を起こします。
=begin original
@@ -9249,6 +9323,7 @@
=end original
+B<* いつでもトランザクションが有効なデータベース>
=begin original
@@ -9261,6 +9336,12 @@
=end original
+「ANSI標準」トランザクション機能を持った商用リレーショナルデータベースでは、
+これが主流です。
+C<AutoCommit> がオフであると、データベースへの変更は L</commit> されるまで
+有効になりません (しかし L</disconnect> もご覧ください)。
+もし L</rollback> が呼ばれると、最後のコミット以降のいかなる変更も元に
+戻されます。
=begin original
@@ -9272,6 +9353,10 @@
=end original
+C<AutoCommit> がオンであると、DBI はまるで正常終了したデータベース操作の後、
+自動的に C<commit> を呼んでいるのと同じように振る舞います。
+従って C<AutoCommit> がオンの間に C<commit>, C<rollback> を明示的に
+呼び出しても、すでにコミットされてしまっているので、何も効果がありません。
=begin original
@@ -9279,6 +9364,7 @@
=end original
+C<AutoCommit> をオフからオンに変えると、大抵のドライバは L</commit> します。
=begin original
@@ -9291,6 +9377,13 @@
=end original
+自動コミットモードを特にサポートしていないデータベースでは、ドライバは
+各ステートメントが正常終了したら、明示的に C<COMMIT> することにより、
+自動的にコミットしなければいけません(失敗したら明示的に C<ROLLBACK> して
+元に戻さなければいけません)。
+アプリケーションに伝えられるエラー情報は、ステートメントが正常終了した後、
+コミットやロールバックが失敗しない限りは、実行されたステートメントに
+対応しなければいけません。
=begin original
@@ -9298,6 +9391,7 @@
=end original
+B<* トランザクションが明示的に開始されなければならないデータベース>
=begin original
@@ -9306,6 +9400,8 @@
=end original
+これらのデータベースでは、トランザクションは(上記のような)いつでも
+有効になるデータベースと同じようにします。
=begin original
@@ -9316,6 +9412,10 @@
=end original
+こうするため、ドライバは C<AutoCommit> がオフになるか、
+L</commit> や L</rollback> の後(あるいはアプリケーションがこれらの
+イベントの一つの後次のデータベース操作を行ったとき)、自動的に
+トランザクションを開始します。
=begin original
@@ -9324,6 +9424,8 @@
=end original
+こうして、アプリケーションはこれらのデータベースを特別なケースとして
+扱わなくてもよくなるのです。
=begin original
@@ -9332,7 +9434,8 @@
=end original
-
+トランザクションについてのほかの重要な情報については L</commit>,
+L</disconnect>, L</Transactions> をご覧ください。
=head3 C<Driver> (handle)
@@ -9343,10 +9446,12 @@
=end original
+ハンドルの親ドライバを保持します。
+唯一推奨されるこれの使い方は以下のようにしてドライバの名前を
+見つけることだけです:
$dbh->{Driver}->{Name}
-
=head3 C<Name> (string)
=begin original
@@ -9357,7 +9462,10 @@
=end original
-
+データベースの名前が入ります。
+通常は(そして推奨されることですが)データベースへの接続に使われる
+"C<dbi:DriverName:...>" 文字列から先頭の "C<dbi:DriverName:>" を
+取ったものになります。
=head3 C<Statement> (string, read-only)
@@ -9370,7 +9478,11 @@
=end original
-
+このデータベースハンドルで最後の L</prepare> メソッドに渡された
+ステートメント文字列を返します。
+もしそのメソッドが失敗していたとしてもです。
+これは C<RaiseError> が有効になっていて、例外ハンドラが $@ をチェックし、
+'prepare' メソッドが失敗したかもしれないと思われるときには特に便利でしょう。
=head3 C<RowCacheSize> (integer)
@@ -9383,6 +9495,10 @@
=end original
+アプリケーションがドライバに後からの C<SELECT> 文のために使わせたい
+ローカルな行キャッシュの大きさを示すドライバへのヒントです。
+行キャッシュが実装されていなければ、C<RowCacheSize> の設定は無視され、値は
+C<undef> が返ります。
=begin original
@@ -9390,12 +9506,22 @@
=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
@@ -9405,6 +9531,10 @@
=end original
+キャッシュの大きさを大きくすると大量のメモリが必要になること
+(キャッシュされる行の数×行の最大サイズ)、そして大きなキャッシュをとると
+それだけ最初の取得あるいは次のキャッシュ分を取得のさいに時間がかかるように
+なることに注意してください。
=begin original
@@ -9412,6 +9542,7 @@
=end original
+L</RowsInCache> ステートメントハンドル属性もご覧ください。
=head3 C<Username> (string)
@@ -9421,10 +9552,13 @@
=end original
-
+Returns the username used to connect to the database.
+(TBT)
=head1 DBI STATEMENT HANDLE OBJECTS
+(DBI ステートメントハンドルオブジェクト)
+
=begin original
This section lists the methods and attributes associated with DBI
@@ -9432,15 +9566,19 @@
=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>
@@ -9457,6 +9595,12 @@
=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 ?");
@@ -9464,13 +9608,22 @@
$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
-
+See L</"Placeholders and Bind Values"> for more information.
+(TBT)
=begin original
@@ -9478,6 +9631,7 @@
=end original
+B<プレースホルダのデータ型>
=begin original
@@ -9487,6 +9641,7 @@
=end original
+\%attr パラメータはプレースホルダが持つべきデータ型を指定するために使われます。通常、ドライバはプレースホルダが結びつけられるのが数値としてなのか、文字列としてなのかを知ることだけに関心があります。
$sth->bind_param(1, $value, { TYPE => SQL_INTEGER });
@@ -9498,6 +9653,7 @@
=end original
+よくあるケースのための短縮形として、データ型を直接attrハッシュ・リファレンスの場所に直接、渡すことができます。この例は、上記のものと同じです。
$sth->bind_param(1, $value, SQL_INTEGER);
@@ -9509,6 +9665,8 @@
=end original
+TYPEの値はこのパラメータでは(ドライバに特有でない)標準の型を示します。
+ドライバ特有の型を指定するために、ドライバは { ora_type => 97 }といったドライバ特有の型をサポートしていることがあります。
=begin original
@@ -9516,6 +9674,8 @@
=end original
+The SQL_INTEGER and other related constants can be imported using
+(TBT)
use DBI qw(:sql_types);
@@ -9525,6 +9685,8 @@
=end original
+See L</"DBI Constants"> for more information.
+(TBT)
=begin original
@@ -9535,6 +9697,11 @@
=end 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.
+(TBT)
=begin original
@@ -9545,6 +9712,12 @@
=end original
+Perl は文字と数値のスカラデータ型だけを持っています。
+数値でないすべてのデータベース型は文字列に結び付けられ、データベースが
+理解できる形式に変換されなければなりません。
+except where the bind_param() TYPE attribute
+specifies a type that implies a particular format. For example, given:
+(TBT)
$sth->bind_param(1, $value, SQL_DATETIME);
@@ -9555,6 +9728,9 @@
=end 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.
+(TBT)
=begin original
@@ -9565,6 +9741,10 @@
=end original
+データ型を C<bind_param> 呼び出しの際に指定する代わりに、ドライバに
+データをデフォルトの型(C<VARCHAR>)として渡すこともできます。
+そして SQL 関数でステートメントの中で変換することができます。
+例えば:
INSERT INTO price(code, price) VALUES (?, CONVERT(MONEY,?))
@@ -9575,6 +9755,8 @@
=end original
+C<CONVERT> 関数は単なる例として使われています。
+実際の関数と書き方はデータベースによって大きく違いますし、移植性もありません。
=begin original
@@ -9582,7 +9764,7 @@
=end original
-
+詳しい情報については L</"Placeholders and Bind Values"> もご覧下さい。
=head3 C<bind_param_inout>
@@ -9599,6 +9781,10 @@
=end original
+このメソッドは L</bind_param> と似ていますが、ステートメントからの更新も
+可能としています。
+ステートメントは通常、ストアドプロシージャと呼ばれます。
+C<$bind_value> は実際に使われる変数へのリファレンスとして渡されます。
=begin original
@@ -9608,6 +9794,9 @@
=end original
+L</bind_param> とは違い、C<$bind_value> 変数は C<bind_param_inout> が
+呼ばれたときにはコピーされないことに注意してください。
+変数の値は L</execute> が呼ばれたときに読みこまれます。
=begin original
@@ -9620,6 +9809,12 @@
=end original
+追加された C<$max_len> パラメータは、C<$bin_value> の新しい値のために
+確保される最小限のメモリ量を指定します。
+もし実際の値が大きすぎて収まらなければ、実行は失敗します。
+使用する量がわからなければ、大きな長さを惜しみなく、つまり
+返されるかもしれない一番長い値より長く値を指定しましょう。
+必要よりも大きな値を使うために犠牲になるのは、メモリの浪費だけです。
=begin original
@@ -9628,7 +9823,8 @@
=end original
-
+未定義の値あるいは C<undef> は NULL 値を示すのに使われます。
+さらに詳しい情報は L</"Placeholders and Bind Values"> もご覧下さい。
=head3 C<bind_param_array>
@@ -9644,6 +9840,10 @@
=end 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:
+(TBT)
$dbh->{RaiseError} = 1; # save having to check each method call
$sth = $dbh->prepare("INSERT INTO staff (first_name, last_name, dept) VALUES(?, ?, ?)");
@@ -9659,6 +9859,9 @@
=end 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.
+(TBT)
=begin original
@@ -9669,6 +9872,11 @@
=end 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.)
+(TBT)
=begin original
@@ -9680,6 +9888,12 @@
=end 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.
+(TBT)
=begin original
@@ -9693,6 +9907,14 @@
=end 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.
+(TBT)
=begin original
@@ -9705,6 +9927,13 @@
=end 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>.
+(TBT)
=begin original
@@ -9712,6 +9941,8 @@
=end original
+The C<bind_param_array> method was added in DBI 1.22.
+(TBT)
=head3 C<execute>
@@ -9729,6 +9960,13 @@
=end original
+prepare されたステートメントを実行するために必要な処理をすべて行います。
+エラーが発生したら、C<undef> が返されます。
+正常な C<execute> は、影響を受けた行の数に関係無く、例えそれが
+0 であっても(下記を参照)真を返します。
+L</RaiseError> を使っていないなら、C<execute>(そして他のほとんどの
+DBI メソッド)の戻りステータスをエラーでないかチェックすることは
+常に重要です。
=begin original
@@ -9740,6 +9978,12 @@
=end original
+I<非> C<SELECT> 文なら、C<execute> は、もしわかれば影響を受けた行の数を
+返します。
+影響を受けた行が無い場合には、C<execute> は "C<0E0>" を返します。
+Perl はこれを 0 として扱いますが、真と判定します。
+影響を受けた行が無いこと自体はエラーではないことに注意してください。
+影響を受けた行の数がわからなければ、C<execute> は -1 を返します。
=begin original
@@ -9751,6 +9995,12 @@
=end original
+C<SELECT> 文では execute は問い合わせを単にエンジンで「開始」するだけです。
+C<execute> を呼び出した後は、fetch メソッドのどれかを使ってデータを
+取り出してください。
+C<execute> メソッドは問い合わせによって返される行の数を I<返しません>
+(というのもほとんどのエンジンは前もって教えてくれないからです);
+それは単に真を返します。
=begin original
@@ -9759,6 +10009,9 @@
=end 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>.
+(TBT)
=begin original
@@ -9771,6 +10024,12 @@
=end original
+何か引数が与えられると、C<execute> は、そのステートメントを実行する前に、
+それぞれについて効率よく L</bind_param> を呼び出します。
+このようにして結び付けられた値は、ドライバが正しい型を判定できるか
+(判定できることはまれです)、既に C<bind_param>(または
+C<bind_param_inout>)が型を特定するために使われていなければ、通常
+C<SQL_VARCHAR> タイプとして扱われます。
=begin original
@@ -9780,6 +10039,10 @@
=end 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.
+(TBT)
=begin original
@@ -9790,6 +10053,11 @@
=end 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.
+(TBT)
=head3 C<execute_array>
@@ -9807,6 +10075,10 @@
=end 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.
+(TBT)
=begin original
@@ -9819,6 +10091,13 @@
=end 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.
+(TBT)
=begin original
@@ -9834,6 +10113,16 @@
=end 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.
+(TBT)
=begin original
@@ -9844,6 +10133,11 @@
=end 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>.
+(TBT)
=begin original
@@ -9855,6 +10149,12 @@
=end 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.
+(TBT)
=begin original
@@ -9867,6 +10167,13 @@
=end 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().
+(TBT)
=begin original
@@ -9878,6 +10185,12 @@
=end 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.
+(TBT)
=begin original
@@ -9888,6 +10201,11 @@
=end 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.
+(TBT)
=begin original
@@ -9903,6 +10221,16 @@
=end 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.
+(TBT)
=begin original
@@ -9913,6 +10241,11 @@
=end 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.
+(TBT)
=begin original
@@ -9924,6 +10257,12 @@
=end 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.
+(TBT)
=begin original
@@ -9936,6 +10275,13 @@
=end 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.
+(TBT)
=begin original
@@ -9946,6 +10292,11 @@
=end 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.
+(TBT)
=begin original
@@ -9953,6 +10304,8 @@
=end original
+For example:
+(TBT)
$sth = $dbh->prepare("INSERT INTO staff (first_name, last_name) VALUES (?, ?)");
my $tuples = $sth->execute_array(
@@ -9981,6 +10334,10 @@
=end 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.
+(TBT)
=begin original
@@ -10000,6 +10357,20 @@
=end 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.
+(TBT)
=begin original
@@ -10009,6 +10380,10 @@
=end 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.
+(TBT)
=begin original
@@ -10017,6 +10392,9 @@
=end original
+The C<execute_array> method was added in DBI 1.22, and ArrayTupleFetch
+was added in 1.36.
+(TBT)
=head3 C<execute_for_fetch>
@@ -10033,6 +10411,9 @@
=end original
+The execute_for_fetch() method is used to perform bulk operations
+and is most often used via the execute_array() method, not directly.
+(TBT)
=begin original
@@ -10041,6 +10422,9 @@
=end original
+The fetch subroutine, referenced by $fetch_tuple_sub, is expected
+to return a reference to an array (known as a 'tuple') or undef.
+(TBT)
=begin original
@@ -10050,6 +10434,10 @@
=end 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.
+(TBT)
=begin original
@@ -10061,6 +10449,12 @@
=end 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.
+(TBT)
=begin original
@@ -10076,6 +10470,16 @@
=end 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.
+(TBT)
=begin original
@@ -10088,15 +10492,26 @@
=end original
-
-=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
+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).
+(TBT)
+
+=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
+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.
+(TBT)
=begin original
@@ -10110,6 +10525,14 @@
=end 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).
+(TBT)
=begin original
@@ -10117,6 +10540,8 @@
=end original
+For example:
+(TBT)
my $sel = $dbh1->prepare("select foo, bar from table1");
$sel->execute;
@@ -10136,6 +10561,10 @@
=end 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:
+(TBT)
$ins->execute_for_fetch( sub { shift @array_of_arrays }, \@tuple_status);
@@ -10145,6 +10574,8 @@
=end original
+The C<execute_for_fetch> method was added in DBI 1.38.
+(TBT)
=head3 C<fetchrow_arrayref>
@@ -10162,6 +10593,11 @@
=end original
+次のデータの行を取り出し、フィールドの値をもった配列へのリファレンスを
+返します。
+Null のフィールドは C<undef> で返されます。
+特に C<$sth-E<gt>bind_columns> を使っているならば、これがデータを取り出す
+最も速い方法です。
=begin original
@@ -10172,6 +10608,11 @@
=end original
+もう行が無いか、エラーが発生すると、C<fetchrow_arrayref> は
+C<undef> を返します。
+後で返された C<undef> がエラーによるものかどうかを見るために、
+C<$sth-E<gt>err> をチェックするべきです(あるいは C<RaiseError> 属性を
+使うか)。
=begin original
@@ -10182,6 +10623,13 @@
=end original
+現状では、データを取り出すたびに同じ配列リファレンスが返されることが
+あることに注意してください。
+そのためリファレンスを取っておいて、データの取り出しを進めた後で、
+使わないでください。
+同様に配列の要素も各行で再使用されます。
+要素のリファレンスを取得したいならば、注意してください。
+L</bind_columns> もご覧ください。
=head3 C<fetchrow_array>
@@ -10195,6 +10643,9 @@
=end original
+C<fetchrow_arrayref> の代用品です。
+次のデータ行を取り出し、フィールドの値を持った配列を返します。
+Null のフィールドはリストの中の C<undef> 値として返されます。
=begin original
@@ -10205,6 +10656,10 @@
=end original
+もう行が無いか、エラーが発生すると、C<fetchrow_array> は空リストを返します。
+後で返された空リストがエラーによるものかどうかを見るために、
+C<$sth-E<gt>err> をチェックするべきです(あるいは C<RaiseError> 属性を
+使うか)。
=begin original
@@ -10219,6 +10674,16 @@
=end 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.
+また、スカラコンテキストでは、もう行がないか、エラーが発生すると
+C<undef> が返されます。
+この C<undef> を最初のフィールドの値が NULL のために返される C<undef> とは
+区別することは出来ません。
+これらの理由により、C<fetchrow_array> をスカラコンテキストで使うならば
+注意を払う必要があります。
+(TBT)
=head3 C<fetchrow_hashref>
@@ -10233,6 +10698,10 @@
=end original
+C<fetchrow_arrayref> の代用品です。
+次のデータ行を取り出し、フィールドの名前と値のペアを持ったハッシュへの
+リファレンスを返します。
+NULL フィールドはハッシュのなかの C<undef> として返されます。
=begin original
@@ -10243,6 +10712,11 @@
=end original
+もう行が無いか、エラーが発生すると、C<fetchrow_hashref> は C<undef> を
+返します。
+後で返された C<undef> がエラーによるものかどうかを見るために、
+C<$sth-E<gt>err> をチェックするべきです(あるいは C<RaiseError> 属性を
+使うか)。
=begin original
@@ -10252,6 +10726,10 @@
=end original
+オプションの C<$name> パラメータには、ステートメントハンドル属性の名前を
+指定します。
+移植性の面からは "C<NAME_lc>" や "C<NAME_uc>" を使うことが勧められるのですが、
+歴史的な理由から、デフォルトは "C<NAME>" になります。
=begin original
@@ -10270,6 +10748,20 @@
=end original
+ハッシュのキーは C<$sth-E<gt>{$name}> によって返される名前と同じです。
+複数のフィールドが同じ名前であった場合、返されたハッシュの中のそれらの
+フィールドためのエントリはただ一つになるので、
+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.
+(TBT)
=begin original
@@ -10278,6 +10770,8 @@
=end original
+C<fetchrow_hashref> は追加の動作をし、さらに Perl が動かなければならないので、
+C<fetchrow_arrayref> や C<fetchrow_array> ほど効率よくありません。
=begin original
@@ -10289,7 +10783,11 @@
=end original
-
+デフォルトでは行毎に新しいハッシュリファレンスが返されます。
+将来のバージョンの DBI では行毎に同じハッシュを再利用することを有効にする
+新しい属性に対応する予定です。
+これは大きく性能を改善させますが、古いコードを壊すリスクがあるので
+デフォルトでは有効にならない予定です。
=head3 C<fetchall_arrayref>
@@ -10305,6 +10803,10 @@
=end original
+C<fetchall_arrayref> メソッドは prepare され、execute された
+ステートメントハンドルから、返されるべきすべてのデータを取り出すために
+使います。
+1 行につき一つのリファレンスが入っている配列へのリファレンスを返します。
=begin original
@@ -10316,6 +10818,13 @@
=end original
+もう行が無いかエラーが発生すると、C<fetchall_arrayref> は空の配列への
+リファレンスを返します。
+エラーが発生したら、C<fetchall_arrayref> はデータを取り出せたところまで
+返します(これは空であるかもしれません)。
+データが完全であるか、エラーにより切り捨てられたかを見るために、後で
+C<$sth-E<gt>err> をチェックするべきです(あるいは C<RaiseError> 属性を
+使うか)。
=begin original
@@ -10327,6 +10836,11 @@
=end original
+$slice が配列リファレンスなら、C<fetchall_arrayref> は
+L</fetchrow_arrayref> を使って配列のリファレンスで各行を取り出します。
+もし $slice の配列が空でなければ、perl 配列インデックス番号
+(0 から始まります; 1 から始まる列やパラメータの番号とは違います)
+によってそれぞれの列を選択し切り出すために使われます。
=begin original
@@ -10335,6 +10849,8 @@
=end original
+パラメータがないか、$slice が未定義値なら、C<fetchall_arrayref> は
+空の配列リファレンスが渡されたように動きます。
=begin original
@@ -10350,6 +10866,21 @@
=end original
+$slice がハッシュのリファレンスなら、C<fetchall_arrayref> は
+L</fetchrow_hashref> を使って、各行をハッシュのリファレンスで取り出します。
+$slice ハッシュが空なら、C<fetchrow_hashref> は単にきついループで
+呼ばれるだけで、ハッシュのキーは fetchrow_hashref からのデフォルトで
+返されるすべての小文字の名前を持つだけです
+(L</FetchHashKeyName> 属性をご覧ください)。
+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.
+$slice ハッシュが空でなければ、名前によってそれぞれの列を選択し切り出すための
+スライスとして使われます。
+ハッシュの値は 1 に設定するべきです。
+L</FetchHashKeyName> 属性に関わらず、名前は小文字でなければなりません。
=begin original
@@ -10357,6 +10888,7 @@
=end original
+例えば、各行の先頭の列だけを取り出したい場合は:
$tbl_ary_ref = $sth->fetchall_arrayref([0]);
@@ -10366,6 +10898,7 @@
=end original
+各行の一番後ろ、その直前の列を取り出すには:
$tbl_ary_ref = $sth->fetchall_arrayref([-2,-1]);
@@ -10375,6 +10908,7 @@
=end original
+各行をハッシュリファレンスとして取り出すためには:
$tbl_ary_ref = $sth->fetchall_arrayref({});
@@ -10385,6 +10919,8 @@
=end original
+("foo" および "BAR" というキー名で) 各行の "foo" と "bar" という
+フィールドだけを取り出すためには:
$tbl_ary_ref = $sth->fetchall_arrayref({ foo=>1, BAR=>1 });
@@ -10395,6 +10931,8 @@
=end original
+最初の二つの例では、配列リファレンスの配列へのリファレンスを返します。
+3 番目と 4 番目の例はハッシュリファレンスの配列へのリファレンスを返します。
=begin original
@@ -10407,6 +10945,13 @@
=end 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.
+(TBT)
=begin original
@@ -10414,6 +10959,8 @@
=end original
+Here's an example (assumes RaiseError is enabled):
+(TBT)
my $rows = []; # cache for batches of rows
while( my $row = ( shift(@$rows) || # get row from cache, or reload cache:
@@ -10429,6 +10976,9 @@
=end 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.
+(TBT)
=begin original
@@ -10440,6 +10990,12 @@
=end 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().
+(TBT)
=head3 C<fetchall_hashref>
@@ -10457,6 +11013,13 @@
=end 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()>.
+(TBT)
=begin original
@@ -10468,6 +11031,12 @@
=end 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.
+(TBT)
=begin original
@@ -10476,6 +11045,9 @@
=end 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:
+(TBT)
$dbh->{FetchHashKeyName} = 'NAME_lc';
$sth = $dbh->prepare("SELECT FOO, BAR, ID, NAME, BAZ FROM TABLE");
@@ -10492,6 +11064,11 @@
=end 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.
+(TBT)
=begin original
@@ -10502,6 +11079,11 @@
=end 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:
+(TBT)
$sth = $dbh->prepare("SELECT foo, bar, baz FROM table");
$sth->execute;
@@ -10517,6 +11099,11 @@
=end 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.
+(TBT)
=head3 C<finish>
@@ -10530,6 +11117,9 @@
=end original
+もう一度 execute されるか、破壊されるまで、このステートメントハンドルからは
+もうデータが取り出されないことを示します。
+ほぼ確実に、このメソッドを呼び出す必要は I<ありません>。
=begin original
@@ -10538,6 +11128,9 @@
=end 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.
+(TBT)
=begin original
@@ -10548,6 +11141,11 @@
=end original
+すべてのデータが C<SELECT> ステートメントから取り出されたら、ドライバは
+自動的にあなたに代って C<finish> します。
+そのため、ステートメントハンドルから全てのデータを取り出しておらず、
+I<かつ> ハンドルがすぐには破壊されない場合 I<以外は>
+これを明示的に呼び出すべきでは I<ありません>。
=begin original
@@ -10556,6 +11154,9 @@
=end 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.
+(TBT)
=begin original
@@ -10563,6 +11164,7 @@
=end original
+以下のような問い合わせを考えてみてください:
SELECT foo FROM table WHERE bar=? ORDER BY baz
@@ -10576,6 +11178,12 @@
=end original
+これをとても大きなテーブルに対して行います。
+実行されるとデータベースサーバは一時的なバッファ領域をソートされた行を
+格納するために使わなければなりません。
+もし実行し、数行選択した後で、しばらくハンドルが再実行されなかったり、
+破壊されないならば、C<finish> メソッドによってサーバにバッファ領域を
+解放することができることを教えることができます。
=begin original
@@ -10585,6 +11193,11 @@
=end original
+C<finish> を呼び出すと、そのステートメントの L</Active> 属性は
+リセットされます。
+(C<NAME> や C<TYPE> のような)他のステートメントハンドル属性のいくつかも、
+既にアクセスされて(そしてキャッシュされて)いるのでなければ、
+使用できなくなるかもしれません。
=begin original
@@ -10595,6 +11208,12 @@
=end original
+C<finish> メソッドはデータベース接続のトランザクションの状態にはなにも
+影響を与えません。
+トランザクションとは無関係です。
+これはほとんど内部の「家事的(='housekeeping')」メソッドで、あまり
+必要なことはありません。
+L</disconnect> と L</Active> 属性もご覧ください。
=begin original
@@ -10602,7 +11221,8 @@
=end original
-
+The C<finish> method should have been called C<discard_pending_rows>.
+(TBT)
=head3 C<rows>
@@ -10615,6 +11235,8 @@
=end original
+最後のコマンドにより影響を受けた行数を返します。
+不明または使用不能の場合は -1 になります。
=begin original
@@ -10624,6 +11246,9 @@
=end original
+通常、行カウントは I<非> C<SELECT> (C<UPDATE> や C<DELETE> のような
+特定の操作)の C<execute> または、C<SELECT> ステートメントのすべての行を
+取り出した後にしか、信用できません。
=begin original
@@ -10636,6 +11261,12 @@
=end original
+C<SELECT> ステートメントでは、通常、何行返ってくるのかは、すべてを
+取り出すまではわかりません。
+ドライバによってはそれまでに取得した行数を返すものもありますが、
+すべての行が取り出されるまでは -1 を返すものもあります。
+そのため C<SELECT> ステートメントに rows メソッドや $DBI::rows を
+使うことはお勧めできません。
=begin original
@@ -10645,7 +11276,9 @@
=end original
-
+C<SELECT> の行カウントを得るための代わりの方法の一つは、
+"SELECT COUNT(*) FROM ..." ステートメントを、"..."をあなたの問い合わせと
+同じにして実行し、それから行数を取り出すことです。
=head3 C<bind_col>
@@ -10664,6 +11297,15 @@
=end original
+C<SELECT> ステートメントの出力カラム(フィールド)にperlの変数と属性を結び付けます。
+カラム番号は1から数えます。
+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.
+例として下記の C<bind_columns> をご覧下さい。
+(TBT)
=begin original
@@ -10676,6 +11318,13 @@
=end original
+バインディングは Perl エイリアスを使い、下位のレベルで実行されます。
+データベースから行が取り出されると、$var_to_bind が自動的に更新されます
+because it now refers to the same
+memory location as the corresponding column value.
+これはバインドされた変数を非常に効率よく使います。
+Binding a tied variable doesn't work, currently.
+(TBT)
=begin original
@@ -10684,6 +11333,9 @@
=end original
+The L</bind_param> method
+performs a similar, but opposite, function for input variables.
+(TBT)
=begin original
@@ -10691,6 +11343,8 @@
=end original
+B<Data Types for Column Binding>
+(TBT)
=begin original
@@ -10699,6 +11353,9 @@
=end original
+The C<\%attr> parameter can be used to hint at the data type
+formatting the column should have. For example, you can use:
+(TBT)
$sth->bind_col(1, undef, { TYPE => SQL_DATETIME });
@@ -10711,6 +11368,11 @@
=end 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.
+(TBT)
=begin original
@@ -10720,6 +11382,10 @@
=end 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.
+(TBT)
=begin original
@@ -10729,6 +11395,10 @@
=end 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:
+(TBT)
$sth->bind_col(1, undef, SQL_DATETIME);
@@ -10740,6 +11410,10 @@
=end 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 }>.
+(TBT)
=begin original
@@ -10747,6 +11421,8 @@
=end original
+The SQL_DATETIME and other related constants can be imported using
+(TBT)
use DBI qw(:sql_types);
@@ -10756,6 +11432,8 @@
=end original
+See L</"DBI Constants"> for more information.
+(TBT)
=begin original
@@ -10765,6 +11443,10 @@
=end 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.
+(TBT)
=begin original
@@ -10772,6 +11454,8 @@
=end original
+The TYPE attribute for bind_col() was first specified in DBI 1.41.
+(TBT)
=begin original
@@ -10783,6 +11467,12 @@
=end 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.
+(TBT)
=begin original
@@ -10790,6 +11480,8 @@
=end original
+B<Other attributes for Column Binding>
+(TBT)
=begin original
@@ -10797,6 +11489,8 @@
=end original
+The C<\%attr> parameter may also contain the following attributes:
+(TBT)
=over
@@ -10813,6 +11507,13 @@
=end 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.
+(TBT)
=begin original
@@ -10822,6 +11523,10 @@
=end 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.
+(TBT)
=item C<DiscardString>
@@ -10834,6 +11539,11 @@
=end 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.
+(TBT)
=begin original
@@ -10843,10 +11553,13 @@
=end 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.
+(TBT)
=back
-
=head3 C<bind_columns>
$rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind);
@@ -10857,6 +11570,7 @@
=end original
+C<SELECT> ステートメントの各カラムに L</bind_col> を呼び出します。
=begin original
@@ -10866,6 +11580,10 @@
=end 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.
+(TBT)
=begin original
@@ -10874,6 +11592,8 @@
=end original
+ドライバ間の移植性を最大限に高めるためには、bind_columns() は execute() の
+後に呼び出さなければなりません。
=begin original
@@ -10881,6 +11601,9 @@
=end original
+例えば:
+
+=begin original
$dbh->{RaiseError} = 1; # do this, or check every call for errors
$sth = $dbh->prepare(q{ SELECT region, sales FROM sales_by_region });
@@ -10898,6 +11621,24 @@
print "$region: $sales\n";
}
+=end original
+
+ $dbh->{RaiseError} = 1; # こうするか、呼び出しのたびにエラーをチェックしてください
+ $sth = $dbh->prepare(q{ SELECT region, sales FROM sales_by_region });
+ $sth->execute;
+ my ($region, $sales);
+
+ # Perl の変数をカラムに結び付けます:
+ $rv = $sth->bind_columns(\$region, \$sales);
+
+ # Perl の\(...) という書き方をつかうこともできます(perlref ドキュメントをご覧ください):
+ # $sth->bind_columns(\($region, $sales));
+
+ # カラムの結びつけはデータの取り出し方では最も効率的な方法です
+ while ($sth->fetch) {
+ print "$region: $sales\n";
+ }
+
=begin original
For compatibility with old scripts, the first parameter will be
@@ -10905,6 +11646,8 @@
=end original
+昔のスクリプトとの互換性のために、最初の引数が C<undef> もしくは
+ハッシュリファレンスであれば、無視されます。
=begin original
@@ -10913,6 +11656,8 @@
=end original
+カラムをハッシュの内側の値に結びつけるという、さらにすごい例を
+示します(H.Merijn Brand に感謝):
$sth->execute;
my %row;
@@ -10921,7 +11666,6 @@
print "$row{region}: $row{sales}\n";
}
-
=head3 C<dump_results>
$rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh);
@@ -10934,6 +11678,10 @@
=end original
+C<$sth> からすべての行を取り出し、各行に C<DBI::neat_list> を呼び出し、
+その結果を C<$lsep> (デフォルトは C<"\n">)で区切って、C<$fh>(デフォルトは
+C<STDOUT>)に、出力します。
+C<$fsep> のデフォルトは C<", ">、C<$maxlen> のデフォルトは 35 です。
=begin original
@@ -10944,7 +11692,10 @@
=end original
-
+このメソッドは問い合わせのプロトタイプとテストのための簡単な
+ユーティリティとして設計されています。
+人の目にわかりやすいように文字列の整形し、編集する L</neat_list> を
+使っているので、データ転送アプリケーションにはお勧めしません。
=head2 Statement Handle Attributes
@@ -10955,6 +11706,8 @@
=end original
+このセクションではステートメント・ハンドルの属性について記述します。
+大半の属性は読込のみです。
=begin original
@@ -10963,6 +11716,7 @@
=end original
+これらのステートメント・ハンドル属性を変更しても、既存のほかのハンドルや後で作成されるステートメント・ハンドルには影響を与えません。
=begin original
@@ -10972,6 +11726,7 @@
=end original
+ドライバ毎のプライベートな属性を除いては、決められていない属性を設定あるいは取得しようとすると致命的なエラーになります。(ドライバ毎のプライベートな属性は名前が小文字ではじまります)
=begin original
@@ -10979,6 +11734,7 @@
=end original
+例:
... = $h->{NUM_OF_FIELDS}; # get/read
@@ -10990,6 +11746,10 @@
=end original
+ドライバによっては、C<$sth-E<gt>execute> が呼ばれるまでは、一部あるいは
+すべての属性について正しい値を提供できないものもあります。
+Typically the attribute will be C<undef> in these situations.
+(TBT)
=begin original
@@ -10999,6 +11759,10 @@
=end 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.
+(TBT)
=begin original
@@ -11007,6 +11771,9 @@
=end original
+For drivers which support stored procedures and multiple result sets
+(see more_results) these attributes relate to the I<current> result set.
+(TBT)
=begin original
@@ -11015,6 +11782,8 @@
=end original
+いくつかの属性に影響を与えるかもしれないことについて、より知るために
+L</finish> もご覧ください。
=head3 C<NUM_OF_FIELDS> (integer, read-only)
@@ -11026,7 +11795,10 @@
=end original
-
+準備(prepare) された SQL 文のフィールド(カラム)の数を返します。
+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).
+(TBT)
=head3 C<NUM_OF_PARAMS> (integer, read-only)
@@ -11037,7 +11809,8 @@
=end original
-
+準備(prepare)されたSQL文のパラメータ(プレースホルダ)の数。
+詳細については下記の置換変数をご覧ください。
=head3 C<NAME> (array-ref, read-only)
@@ -11051,6 +11824,12 @@
=end original
+各カラムに対応するフィールド名の配列へのリファレンスを返します。
+名前には空白が入っているかもしれませんが、切り捨てられることはありませんし、
+後ろの空白を持ちます。
+返されるときの文字の大文字、小文字、その混合は使われている
+データベースによるということに注意してください。
+移植性の高いアプリーケーションは L</NAME_lc> または L</NAME_uc> を使うべきです。
print "First column name: $sth->{NAME}->[0]\n";
@@ -11062,6 +11841,10 @@
=end 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.
+(TBT)
=head3 C<NAME_lc> (array-ref, read-only)
@@ -11071,6 +11854,7 @@
=end original
+L</NAME> と同様ですが常に小文字で名前が返されます。
=head3 C<NAME_uc> (array-ref, read-only)
@@ -11080,6 +11864,7 @@
=end original
+L</NAME> と同様ですが常に大文字で名前が返されます。
=head3 C<NAME_hash> (hash-ref, read-only)
@@ -11094,6 +11879,9 @@
=end 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.
+(TBT)
=begin original
@@ -11103,6 +11891,10 @@
=end 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).
+(TBT)
=begin original
@@ -11111,6 +11903,9 @@
=end original
+The value of each hash entry is the perl index number of the
+corresponding column (counting from 0). For example:
+(TBT)
$sth = $dbh->prepare("select Id, Name from table");
$sth->execute;
@@ -11127,6 +11922,7 @@
=end original
+各カラムに対応する整数値の配列へのリファレンスを返します。値は対応するカラムのデータ型を示します。
=begin original
@@ -11139,6 +11935,12 @@
=end original
+この値は国際規約(ANSI X3.135 と ISO/IEC 9075)、一般には ODBC を意味します、に
+対応しています。
+標準の型に正確にあてはまらない、ドライバ特有の型では、通常、データベースの
+メーカーが提供する ODBC ドライバと同じ値を返さなければいけません。
+これはベンダーが公式に ISO ワーキンググループに予約しているプライベートな
+型番号を含みます。:
ftp://sqlstandards.org/SC32/SQL_Registry/
@@ -11150,6 +11952,9 @@
=end original
+DBI ドライバは互換性を持つ ODBC ドライバを提供されているベンダーがなければ、
+DBI が使用するために公式に予約されている -9999 から -9000 の範囲の型番号を
+使うことができます。
=begin original
@@ -11158,6 +11963,9 @@
=end original
+C<TYPE> がとりうるすべての値は、C<type_info_all> メソッドの出力のなかの、
+少なくとも一つの要素として入っていなければなりません
+(L<type_info_all> をご覧下さい)。
=head3 C<PRECISION> (array-ref, read-only)
@@ -11167,6 +11975,7 @@
=end original
+各カラムに対応する整数値の配列へのリファレンスを返します。
=begin original
@@ -11178,6 +11987,11 @@
=end original
+数値のカラムでは、値は数値の最大桁数です
+(符号文字や小数点を除きます)。
+浮動小数点の型(REAL, FLOAT, DOUBLE)では「表示サイズ」は precision よりも
+7 文字までは、大きいかもしれません
+(符号 + 小数点 + E という文字 + 符号 +2 または 3 桁)。
=begin original
@@ -11186,6 +12000,9 @@
=end original
+For any character type column the value is the OCTET_LENGTH,
+in other words the number of bytes, not characters.
+(TBT)
=begin original
@@ -11194,6 +12011,9 @@
=end original
+(More recent standards refer to this as COLUMN_SIZE but we stick
+with PRECISION for backwards compatibility.)
+(TBT)
=head3 C<SCALE> (array-ref, read-only)
@@ -11204,6 +12024,8 @@
=end original
+各カラムに対応する整数値の配列へのリファレンスを返します。
+NULL (C<undef>) 値には、scale が適用されないことを示します。
=head3 C<NULLABLE> (array-ref, read-only)
@@ -11215,10 +12037,12 @@
=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
@@ -11229,7 +12053,10 @@
=end original
-
+ステートメントハンドルが使えるのであれば、ステートメントハンドルに
+結び付けられたカーソル名を返します。
+使えないか、"where current of ..." SQL の書き方をデータベースドライバが
+サポートしていなければ C<undef> を返します。
=head3 C<Database> (dbh, read-only)
@@ -11239,7 +12066,8 @@
=end original
-
+Returns the parent $dbh of the statement handle.
+(TBT)
=head3 C<Statement> (string, read-only)
@@ -11249,7 +12077,7 @@
=end original
-
+L</prepare> メソッドに渡された、ステートメント文字列を返します。
=head3 C<ParamValues> (hash ref, read-only)
@@ -11262,6 +12090,11 @@
=end 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.
+(TBT)
=begin original
@@ -11269,6 +12102,8 @@
=end original
+See L</ShowErrorStatement> for an example of how this is used.
+(TBT)
=begin original
@@ -11276,6 +12111,8 @@
=end original
+* Keys:
+(TBT)
=begin original
@@ -11286,6 +12123,11 @@
=end 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.
+(TBT)
=begin original
@@ -11296,6 +12138,11 @@
=end 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.
+(TBT)
=begin original
@@ -11303,6 +12150,8 @@
=end original
+* Values:
+(TBT)
=begin original
@@ -11317,6 +12166,15 @@
=end 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.
+(TBT)
=begin original
@@ -11324,6 +12182,8 @@
=end original
+The C<ParamValues> attribute was added in DBI 1.28.
+(TBT)
=head3 C<ParamTypes> (hash ref, read-only)
@@ -11335,6 +12195,10 @@
=end original
+Returns a reference to a hash containing the type information
+currently bound to placeholders.
+Returns undef if not supported by the driver.
+(TBT)
=begin original
@@ -11342,6 +12206,8 @@
=end original
+* Keys:
+(TBT)
=begin original
@@ -11349,6 +12215,8 @@
=end original
+See L</ParamValues> above.
+(TBT)
=begin original
@@ -11356,6 +12224,8 @@
=end original
+* Values:
+(TBT)
=begin original
@@ -11365,6 +12235,10 @@
=end 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).
+(TBT)
=begin original
@@ -11374,6 +12248,10 @@
=end 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:
+(TBT)
$sth->bind_param(1, SQL_INTEGER);
@@ -11383,6 +12261,8 @@
=end original
+are returned in the expanded form, as if called like this:
+(TBT)
$sth->bind_param(1, { TYPE => SQL_INTEGER });
@@ -11396,6 +12276,12 @@
=end 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).
+(TBT)
=begin original
@@ -11403,6 +12289,8 @@
=end original
+* Example:
+(TBT)
=begin original
@@ -11412,6 +12300,10 @@
=end 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:
+(TBT)
# assuming $sth1 is a previously prepared statement handle
my $sth2 = $dbh->prepare( $sth1->{Statement} );
@@ -11429,6 +12321,10 @@
=end 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.
+(TBT)
=head3 C<ParamArrays> (hash ref, read-only)
@@ -11443,6 +12339,12 @@
=end 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.
+(TBT)
=begin original
@@ -11451,6 +12353,9 @@
=end original
+Each key value is an array reference containing a list of the bound
+parameters for that column.
+(TBT)
=begin original
@@ -11458,6 +12363,8 @@
=end original
+For example:
+(TBT)
$sth = $dbh->prepare("INSERT INTO staff (id, name) values (?,?)");
$sth->execute_array({},[1,2], ['fred','dave']);
@@ -11479,6 +12386,13 @@
=end 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.
+(TBT)
=begin original
@@ -11489,6 +12403,11 @@
=end 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.
+(TBT)
=head3 C<RowsInCache> (integer, read-only)
@@ -11501,6 +12420,12 @@
=end original
+ドライバが C<SELECT> ステートメントについてローカルな行キャッシュを
+サポートしていれば、この属性はキャシュのなかで fetch されていない行数を
+返します。
+ドライバがサポートしていなければ、C<undef> を返します。
+ドライバによっては execute 時点で前もって取り出すものもありますし、最初の
+fetch が来るまで待つものもあります。
=begin original
@@ -11508,11 +12433,16 @@
=end original
+データベースハンドル属性 L</RowCacheSize> もご覧ください。
=head1 FURTHER INFORMATION
+(さらなる情報)
+
=head2 Catalog Methods
+(カタログメソッド)
+
=begin original
An application can retrieve metadata information from the DBMS by issuing
@@ -11523,6 +12453,12 @@
=end 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:
+(TBT)
column_info
foreign_key_info
@@ -11540,6 +12476,12 @@
=end 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.
+(TBT)
=begin original
@@ -11548,6 +12490,9 @@
=end 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.
+(TBT)
=begin original
@@ -11558,6 +12503,11 @@
=end 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.
+(TBT)
=begin original
@@ -11567,6 +12517,10 @@
=end 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>.
+(TBT)
=begin original
@@ -11578,6 +12532,12 @@
=end 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
+(TBT)
$esc = $dbh->get_info( 14 ); # SQL_SEARCH_PATTERN_ESCAPE
$search_pattern =~ s/([_%])/$esc$1/g;
@@ -11594,6 +12554,14 @@
=end 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.
+(TBT)
=begin original
@@ -11603,10 +12571,15 @@
=end 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>.
+(TBT)
=head2 Transactions
+(トランザクション)
+
=begin original
Transactions are a fundamental part of any robust database system. They
@@ -11616,6 +12589,10 @@
=end original
+トランザクションはすべての堅牢なデータベースシステムの基本的な部分です。
+データベースへの関連する一連の変更が、アトミックな(独立していて
+オールオアナッシングな)単位で行われること保証することにより、エラーと
+データベース障害から守ります。
=begin original
@@ -11625,6 +12602,10 @@
=end original
+この節はトランザクションをサポートし、C<AutoCommit> がオフに
+なっているデータベースにあてはまります。
+各種のデータベースに対する C<AutoCommit> の使い方の詳細については
+L</AutoCommit> をご覧ください。
=begin original
@@ -11634,6 +12615,12 @@
=end original
+Perl アプリケーションで堅牢なトランザクションを実現するためのお勧めの方法は、
+C<RaiseError> と S<C<eval { ... }>> を使うことです
+(これは S<C<eval "...">> と違ってとても速く動作します)。
+例えば:
+
+=begin original
$dbh->{AutoCommit} = 0; # enable transactions, if possible
$dbh->{RaiseError} = 1;
@@ -11651,6 +12638,24 @@
# 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
@@ -11658,6 +12663,9 @@
=end original
+C<RaiseError> 属性が設定されていなければ、DBI 呼び出しは手動でエラーの
+チェックをする必要があります。
+通常は以下のようにします:
$h->method(@args) or die $h->errstr;
@@ -11670,6 +12678,11 @@
=end original
+C<RaiseError> を設定すると、そのハンドル(またはその子供のハンドル)で
+呼び出される DBI メソッドが失敗すると、DBI は自動的に die します。
+そのため各メソッド呼び出しの戻り値をいちいちチェックする必要が
+なくなります。
+詳細については L</RaiseError> をご覧ください。
=begin original
@@ -11681,6 +12694,12 @@
=end original
+C<eval> による方法の大きな利点は、アプリケーション内部のいかなる理由で、
+(DBI呼び出しに限らず)どのような処理で die しても、トランザクションが
+適切にロールバックされることにあります。
+$h->{RaiseError} 属性を使う大きな利点は、すべての DBI 呼び出しが自動的に
+チェックされることにあります。
+どちらのテクニックも強くお勧めします。
=begin original
@@ -11691,6 +12710,11 @@
=end original
+C<commit> や C<rollback> を呼び出した後、多くのドライバは同じ
+データベースハンドルの子供で以前はアクティブだった C<SELECT>
+ステートメントハンドルからの取り出しをさせてくれません。
+これを避ける典型的な方法は、データベースに 2 回接続し、一つの接続を
+C<SELECT> ステートメントのために使うことです。
=begin original
@@ -11699,10 +12723,14 @@
=end original
-
+See L</AutoCommit> and L</disconnect> for other important information
+about transactions.
+(TBT)
=head2 Handling BLOB / LONG / Memo Fields
+(BLOB / LONG / Memoフィールドを扱う)
+
=begin original
Many databases support "blob" (binary large objects), "long", or similar
@@ -11712,6 +12740,11 @@
=end original
+多くのデータベースは一つのフィールドにとても長い文字列や、巨大な
+バイナリデータを保持するために、"blob" (binary large objects＝巨大なバイナリ
+オブジェクト), "long" または同じようなデータ型をサポートしています。
+データベースによっては、2,000,000,000 バイトを越えるような長さの可変長の値も
+サポートしています。
=begin original
@@ -11722,6 +12755,9 @@
=end original
+その大きさの値を通常メモリに保持することができないこと、(他のデータ型と
+違って)C<SELECT> ステートメントによって返される最大長をデータベースは
+前もってわからないことから、特別な操作が必要になります。
=begin original
@@ -11733,6 +12769,11 @@
=end original
+このような場合に、そのようなフィールドを取り出すときに、どれくらいの
+バッファスペースを確保するかを決めるために、C<$h-E<gt>{LongReadLen}> 属性の
+値が使われます。
+C<$h-E<gt>{LongTruncOk}> 属性は、取り出した値がバッファに
+入りきらなかったときにどのように振る舞うかを決定するのに使われます。
=begin original
@@ -11740,6 +12781,8 @@
=end original
+See the description of L</LongReadLen> for more information.
+(TBT)
=begin original
@@ -11750,16 +12793,23 @@
=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)
@@ -11791,6 +12841,9 @@
=end original
+ファイルからデータを挿入する一通り揃ったプログラム例を以下に示します。
+(この例では各呼び出しでチェックする必要をなくすために、C<RaiseError> を
+使っています)。
my $dbh = DBI->connect("dbi:DriverName:db_name", $user, $password, {
RaiseError => 1, AutoCommit => 0
@@ -11817,6 +12870,7 @@
=end original
+これは取り出した NULL(未定義値)を空文字列に変換する方法です:
while($row = $sth->fetchrow_arrayref) {
# this is a fast and simple way to deal with nulls:
@@ -11833,9 +12887,16 @@
=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.
@@ -11843,6 +12904,9 @@
=end 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.)
+(TBT)
=begin original
@@ -11852,6 +12916,10 @@
=end 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.
+(TBT)
=begin original
@@ -11861,6 +12929,10 @@
=end 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.
+(TBT)
=begin original
@@ -11872,6 +12944,12 @@
=end 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).
+(TBT)
=begin original
@@ -11881,6 +12959,10 @@
=end 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.
+(TBT)
=begin original
@@ -11894,6 +12976,14 @@
=end 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.
+(TBT)
=begin original
@@ -11903,6 +12993,10 @@
=end 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>
+(TBT)
=begin original
@@ -11911,9 +13005,14 @@
=end 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.
+(TBT)
=head2 Signal Handling and Canceling Operations
+(シグナルの扱いとキャンセル操作)
+
=begin original
[The following only applies to systems with unix-like signal handling.
@@ -11921,6 +13020,9 @@
=end original
+[The following only applies to systems with unix-like signal handling.
+I'd welcome additions for other systems, especially Windows.]
+(TBT)
=begin original
@@ -11935,6 +13037,16 @@
=end original
+まず最初にいうべきことは、Perl バージョン 5.8 以前でのシグナル操作は
+安全ではI<ない> ということです。
+シグナルを扱ったときまたは後に、Perlがクラッシュする、またははコアダンプを
+おこす危険性がまだ若干あります;
+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.
+(TBT)
=begin original
@@ -11945,6 +13057,11 @@
=end 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.
+(TBT)
=begin original
@@ -11957,6 +13074,13 @@
=end 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.
+(TBT)
=begin original
@@ -11967,6 +13091,11 @@
=end 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.
+(TBT)
=begin original
@@ -11975,6 +13104,9 @@
=end original
+Fortunately there are ways around this which we'll discuss below.
+Unfortunately they make signals unsafe again.
+(TBT)
=begin original
@@ -11984,11 +13116,16 @@
=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
@@ -11997,6 +13134,10 @@
=end original
+DBI は C<cancel> メソッドをステートメントハンドルに用意しています。
+C<cancel> メソッドはその時点の操作を中断させなければいけません;
+そしてシグナルハンドラから呼ばれるように設計されています。
+例えば:
$SIG{INT} = sub { $sth->cancel };
@@ -12009,6 +13150,10 @@
=end original
+しかし、これを実装しているドライバはほとんどなく(DBI は C<undef> を
+返すだけのデフォルトのメソッドを提供しています)、たとえ
+実装されていたとしても、ステートメントハンドル、さらに場合によっては
+親のデータベースハンドルが、それ以降、使えなくなる可能性があります。
=begin original
@@ -12019,9 +13164,16 @@
=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}>
@@ -12031,6 +13183,11 @@
=end 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:
+(TBT)
eval {
local $SIG{ALRM} = sub { die "TIMEOUT\n" }; # N.B. \n required
@@ -12055,6 +13212,12 @@
=end 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.
+(TBT)
=begin original
@@ -12063,6 +13226,9 @@
=end original
+Unfortunately, as described above, this won't always work as expected,
+depending on your perl version and the underlying database code.
+(TBT)
=begin original
@@ -12072,6 +13238,10 @@
=end 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.
+(TBT)
=back
@@ -12082,6 +13252,9 @@
=end 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.
+(TBT)
=begin original
@@ -12089,6 +13262,8 @@
=end original
+The code would look something like this (for the DBD-Oracle connect()):
+(TBT)
use POSIX qw(:signal_h);
@@ -12121,6 +13296,8 @@
=end original
+See previous example for the reasoning around the double eval.
+(TBT)
=begin original
@@ -12128,6 +13305,8 @@
=end original
+Similar techniques can be used for canceling statement execution.
+(TBT)
=begin original
@@ -12136,6 +13315,9 @@
=end 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.
+(TBT)
=begin original
@@ -12146,6 +13328,11 @@
=end 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.
+(TBT)
=begin original
@@ -12153,6 +13340,8 @@
=end original
+Be sure to read all the signal handling sections of the L<perlipc> manual.
+(TBT)
=begin original
@@ -12165,10 +13354,18 @@
=end 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.
+(TBT)
=head2 Subclassing the DBI
+(DBI のサブクラス化)
+
=begin original
DBI can be subclassed and extended just like any other object
@@ -12177,6 +13374,10 @@
=end 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.
+(TBT)
=begin original
@@ -12188,6 +13389,12 @@
=end 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>).
+(TBT)
=begin original
@@ -12201,6 +13408,14 @@
=end 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.
+(TBT)
=begin original
@@ -12212,6 +13427,12 @@
=end 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.
+(TBT)
=begin original
@@ -12222,6 +13443,11 @@
=end 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:
+(TBT)
$dbh = MySubDBI->connect(...);
@@ -12231,6 +13457,8 @@
=end original
+or specifying a C<RootClass> attribute:
+(TBT)
$dbh = DBI->connect(..., { RootClass => 'MySubDBI' });
@@ -12240,6 +13468,8 @@
=end original
+If both forms are used then the attribute takes precedence.
+(TBT)
=begin original
@@ -12250,6 +13480,11 @@
=end 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.
+(TBT)
=begin original
@@ -12258,6 +13493,9 @@
=end original
+When subclassing is being used then, after a successful new
+connect, the DBI->connect method automatically calls:
+(TBT)
$dbh->connected($dsn, $user, $pass, \%attr);
@@ -12271,6 +13509,12 @@
=end 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.
+(TBT)
=begin original
@@ -12283,6 +13527,13 @@
=end 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.
+(TBT)
=begin original
@@ -12291,6 +13542,9 @@
=end 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.
+(TBT)
package MySubDBI;
@@ -12340,6 +13594,17 @@
=end 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.
+(TBT)
=begin original
@@ -12354,6 +13619,15 @@
=end 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.
+(TBT)
=begin original
@@ -12365,6 +13639,12 @@
=end 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.
+(TBT)
=begin original
@@ -12374,10 +13654,15 @@
=end 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.
+(TBT)
=head1 TRACING
+(トレース)
+
=begin original
The DBI has a powerful tracing mechanism built in. It enables you
@@ -12386,9 +13671,15 @@
=end 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.
+(TBT)
=head2 Trace Settings
+(トレース設定)
+
=begin original
Which details are written to the trace output is controlled by a
@@ -12400,6 +13691,13 @@
=end 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.
+(TBT)
=begin original
@@ -12413,9 +13711,19 @@
=end 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.
+(TBT)
=head2 Trace Levels
+(トレースレベル)
+
=begin original
Trace I<levels> are as follows:
@@ -12476,6 +13784,8 @@
=head2 Trace Flags
+(トレースフラグ)
+
=begin original
Trace I<flags> are used to enable tracing of specific activities
@@ -12486,6 +13796,12 @@
=end 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.
+(TBT)
=begin original
@@ -12493,6 +13809,8 @@
=end original
+Currently the DBI only defines two trace flags:
+(TBT)
ALL - turn on all DBI and driver flags (not recommended)
SQL - trace SQL statements executed
@@ -12505,9 +13823,14 @@
=end 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.
+(TBT)
=head2 Enabling Trace
+(トレースを有効にする)
+
=begin original
The C<$h-E<gt>trace> method sets the trace settings for a handle
@@ -12515,6 +13838,9 @@
=end 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.
+(TBT)
=begin original
@@ -12525,6 +13851,9 @@
=end original
+L</trace> メソッドに加えて、Perl を実行する前に環境変数 C<DBI_TRACE> を
+設定すれば、同じトレース情報を有効にし、ファイルに出力することができます。
+さらなる情報については L</DBI_TRACE> を参照してください。
=begin original
@@ -12533,6 +13862,9 @@
=end original
+Finally, you can set, or get, the trace settings for a handle using
+the C<TraceLevel> attribute.
+(TBT)
=begin original
@@ -12543,11 +13875,18 @@
=end 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:
+(TBT)
local $h->{TraceLevel} = "3|SQL|foo";
=head2 Trace Output
+(トレース出力)
+
=begin original
Initially trace output is written to C<STDERR>. Both the
@@ -12562,6 +13901,16 @@
=end 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.
+(TBT)
=begin original
@@ -12573,6 +13922,12 @@
=end 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.
+(TBT)
=begin original
@@ -12583,25 +13938,52 @@
=end 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.
+(TBT)
=head2 Tracing to Layered Filehandles
+(層のあるファイルハンドルへのトレース)
+
=begin original
B<NOTE>:
=end original
+B<NOTE>:
+(TBT)
=over 4
=item *
+
+=begin original
+
+Tied filehandles are not currently supported, as
+tie operations are not available to the PerlIO
+methods used by the DBI.
+
+=end original
+
Tied filehandles are not currently supported, as
tie operations are not available to the PerlIO
methods used by the DBI.
+(TBT)
=item *
+
+=begin original
+
+PerlIO layer support requires Perl version 5.8 or higher.
+
+=end original
+
PerlIO layer support requires Perl version 5.8 or higher.
+(TBT)
=back
@@ -12612,6 +13994,9 @@
=end original
+As of version 5.8, Perl provides the ability to layer various
+"disciplines" on an open filehandle via the L<PerlIO> module.
+(TBT)
=begin original
@@ -12619,6 +14004,8 @@
=end original
+A simple example of using PerlIO layers is to use a scalar as the output:
+(TBT)
my $scalar = '';
open( my $fh, "+>:scalar", \$scalar );
@@ -12630,6 +14017,8 @@
=end original
+Now all trace output is simply appended to $scalar.
+(TBT)
=begin original
@@ -12640,6 +14029,11 @@
=end 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:
+(TBT)
package MyFancyLogger;
@@ -12688,6 +14082,9 @@
=end original
+To redirect DBI traces to this logger requires creating
+a package for the layer:
+(TBT)
package PerlIO::via::MyFancyLogLayer;
@@ -12730,6 +14127,9 @@
=end original
+The application can then cause DBI traces to be routed to the
+logger using
+(TBT)
use PerlIO::via::MyFancyLogLayer;
@@ -12744,9 +14144,14 @@
=end original
+Now all trace output will be processed by MyFancyLogger's
+log() method.
+(TBT)
=head2 Trace Content
+(トレースの内容)
+
=begin original
Many of the values embedded in trace output are formatted using the neat()
@@ -12755,15 +14160,23 @@
=end 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.
+(TBT)
=head2 Tracing Tips
+(トレースの小技)
+
=begin original
You can add tracing to your own application code using the L</trace_msg> method.
=end original
+You can add tracing to your own application code using the L</trace_msg> method.
+(TBT)
=begin original
@@ -12774,6 +14187,11 @@
=end 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.
+(TBT)
=begin original
@@ -12782,6 +14200,9 @@
=end 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:
+(TBT)
DBI_TRACE=2 perl yourscript.pl ...args1... 2>&1 | dbilogstrip > dbitrace1.log
DBI_TRACE=2 perl yourscript.pl ...args2... 2>&1 | dbilogstrip > dbitrace2.log
@@ -12793,9 +14214,13 @@
=end original
+See L<dbilogstrip> for more information.
+(TBT)
=head1 DBI ENVIRONMENT VARIABLES
+(DBI 環境変数)
+
=begin original
The DBI module recognizes a number of environment variables, but most of
@@ -13016,8 +14441,12 @@
=head1 WARNING AND ERROR MESSAGES
+(警告とエラーメッセージ)
+
=head2 Fatal Errors
+(致命的エラー)
+
=over 4
=item Can't call method "prepare" without a package or object reference
@@ -13107,6 +14536,8 @@
=head1 Pure-Perl DBI
+(ピュア Perl の DBI)
+
=begin original
A pure-perl emulation of the DBI is included in the distribution
@@ -13145,6 +14576,8 @@
=head2 ODBC and SQL/CLI Standards Reference Information
+(ODBC と SQL/CLI 標準の参照情報)
+
=begin original
More detailed information about the semantics of certain DBI methods
@@ -13207,6 +14640,8 @@
=head2 Standards Reference Information
+(標準の参照情報)
+
=begin original
A hyperlinked, browsable version of the BNF syntax for SQL92 (plus
@@ -13249,6 +14684,8 @@
=head2 Books and Articles
+(書籍と記事)
+
=begin original
Programming the Perl DBI, by Alligator Descartes and Tim Bunce.
@@ -13293,6 +14730,8 @@
=head2 Perl Modules
+(Perl モジュール)
+
=begin original
Index of DBI related modules available from CPAN:
@@ -13335,6 +14774,8 @@
=head2 Mailing List
+(メーリングリスト)
+
=begin original
The I<dbi-users> mailing list is the primary means of communication among
@@ -13374,6 +14815,8 @@
=head2 Assorted Related WWW Links
+(様々な関係する WWW リンク)
+
=begin original
The DBI "Home Page":
@@ -13494,6 +14937,8 @@
=head1 SUPPORT / WARRANTY
+(サポート / 保証)
+
=begin original
The DBI is free Open Source software. IT COMES WITHOUT WARRANTY OF ANY KIND.
@@ -13505,6 +14950,8 @@
=head2 Support
+(サポート)
+
=begin original
My consulting company, Data Plan Services, offers annual and
@@ -13522,6 +14969,8 @@
=head2 Sponsor Enhancements
+(スポンサー拡張)
+
=begin original
The DBI Roadmap is available at L<http://search.cpan.org/~timb/DBI/Roadmap.pod>
@@ -13651,6 +15100,8 @@
=head1 CONTRIBUTING
+(寄与する)
+
=begin original
As you can see above, many people have contributed to the DBI and
@@ -13690,6 +15141,8 @@
=head2 Browsing the source code repository
+(ソースコードレポジトリを見る)
+
=begin original
Use http://svn.perl.org/modules/dbi/trunk (basic)
@@ -13703,6 +15156,8 @@
=head2 How to create a patch using Subversion
+(Subversion を使ってパッチを作る方法)
+
=begin original
The DBI source code is maintained using Subversion (a replacement
@@ -13783,6 +15238,8 @@
=head2 How to create a patch without Subversion
+(Subversion なしでパッチを作る方法)
+
=begin original
Unpack a fresh copy of the distribution:
@@ -13862,6 +15319,8 @@
=head2 Speak before you patch
+(パッチする前に話してみる)
+
=begin original
For anything non-trivial or possibly controversial it's a good idea
@@ -13881,6 +15340,8 @@
=head1 TRANSLATIONS
+(翻訳)
+
=begin original
A German translation of this manual (possibly slightly out of date) is
@@ -13906,6 +15367,8 @@
=head1 TRAINING
+(トレーニング)
+
=begin original
References to DBI related training resources. No recommendation implied.
@@ -13931,6 +15394,8 @@
=head1 OTHER RELATED WORK AND PERL MODULES
+(その他の関係する作品と Perl モジュール)
+
=over 4
=item Apache::DBI by E.Mer****@bawue*****
@@ -13963,6 +15428,12 @@
=back
+=begin meta
+
+Translated: 川合孝典 <GCD00****@nifty*****> (1.19)
+Updated: SHIRAKATA Kentaro <argra****@ub32*****> (1.612)
+
+=end meta
=cut