.\\" auto-generated by docbook2man-spec $Revision: 1.2 $
.TH "DECLARE" "" "2004-06-19" "SQL - 言語" "SQL コマンド"
.SH NAME
DECLARE \- カーソルの定義

.SH SYNOPSIS
.sp
.nf
DECLARE \fIname\fR [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ]
    CURSOR [ { WITH | WITHOUT } HOLD ] FOR \fIquery\fR
    [ FOR { READ ONLY | UPDATE [ OF \fIcolumn\fR [, ...] ] } ]
.sp
.fi
.SH "説明"
.PP
\fBDECLARE\fR によって、ユーザは巨大な問い合わせの中から一度に少数の行を取り出すために使用できるカーソルを作成することができます。 
FETCH [\fBfetch\fR(l)] を使用して、カーソルからテキストもしくはバイナリのどちらかの形式でデータを取り出すことができます。
.PP
通常のカーソルは、\fBSELECT\fR の出力同様のテキスト形式でデータを返します。
元のデータは固有のバイナリ形式で保存されていますので、システムはテキスト形式を生成するために変換を行なう必要があります。
情報がテキスト形式で返されると、クライアントアプリケーションは情報を処理するためにバイナリ形式に変換する必要になることがあります。
また、テキスト形式の場合、対応するバイナリ形式よりもそのサイズが大きくなることがよくあります。 
BINARY カーソルによって、固有のバイナリ表現でデータを返すことができ、より簡単に操作することができます。
それにもかかわらず、とにかくデータをテキストとして表示する予定であるのならばテキスト形式でデータを取り出すことにより、クライアント側の処理を軽減させることになります。
.PP
例えば、問い合わせが整数の列から 1 の値を返す場合、デフォルトのカーソルでは 1 という文字列を入手することになりますが、バイナリ形式のカーソルの場合はその値の内部表現から成る 4 バイトの値を(ビッグエンディアンのバイトオーダで)入手することになります。
.PP
BINARY カーソルは注意して使わなければなりません。 
\fBpsql\fR のような多くのアプリケーションは、バイナリ形式のカーソルを扱うようにはなっていず、データはテキスト形式で返されるものとみなしています。
.sp
.RS
.B "Note:"
クライアントアプリケーションが``拡張問い合わせ''プロトコルを使用して \fBFETCH\fRコマンドを発行する場合、バインドプロトコルメッセージは、テキスト形式かバイナリ形式かいずれかでデータを受け取るかを指定します。
この選択は、カーソル定義での指定を上書きします。
こういったバイナリカーソルの概念は、全てのカーソルはテキストとしてもバイナリとしても扱うことができる拡張問い合わせプロトコルでは旧式なものです。
.RE
.sp
.SH "パラメータ"
.TP
\fB\fIname\fB\fR
作成されるカーソルの名前です。
.TP
\fBBINARY\fR
カーソルによるデータの取得が、テキスト形式ではなくバイナリ形式になります。
.TP
\fBINSENSITIVE\fR
カーソルから取り出されたデータが、そのカーソルが存在する間、その背後にあるテーブルの更新の影響を受けないことを示します。
PostgreSQLでは、カーソルは全て更新の影響を受けません。
このキーワードを使用しても効果はなく、標準SQLとの互換性のために存在するものです。
.TP
\fBSCROLL\fR
.TP
\fBNO SCROLL\fR
SCROLL は、そのカーソルは順序通りでない方法(例えば後方)で行を取り出すことができることを指定します。
問い合わせの実行計画の複雑さに依存して、SCROLL指定は、問い合わせの実行時間において、性能的なペナルティが課せられる可能性があります。
NO SCROLL は、カーソルは順序通りでない方法では行を取り出すことができないことを指定します。
.TP
\fBWITH HOLD\fR
.TP
\fBWITHOUT HOLD\fR
WITH HOLD は、カーソルを生成したトランザクションが終了した後でもそのカーソルを続行できることを指定します。
WITHOUT HOLD は、カーソルを生成したトランザクションの外部では、そのカーソルを使用できないことを指定します。
WITH HOLD もWITHOUT HOLD も指定されない場合、WITHOUT HOLD がデフォルトとなります。
.TP
\fB\fIquery\fB\fR
カーソルによって返される行を提供する \fBSELECT\fR コマンドです。
有効な問い合わせについての詳細は、SELECT [\fBselect\fR(l)] を参照してください。
.TP
\fBFOR READ ONLY\fR
.TP
\fBFOR UPDATE\fR
FOR READ ONLY は、カーソルが読み取り専用モードで使用されることを示します。
FOR UPDATE は、カーソルがテーブルを更新するために使用されることを示します。
現時点ではPostgreSQLはカーソルでの更新をサポートしていませんので、FOR UPDATE はエラーメッセージを表示し、また、FOR READ ONLY の指定は効果がありません。
.TP
\fB\fIcolumn\fB\fR
カーソルによって更新される列(複数可)です。
現時点ではPostgreSQLはカーソルでの更新をサポートしていませんので、FOR UPDATE 句はエラーメッセージを誘発します。
.PP
BINARY、INSENSITIVE、SCROLL キーワードは任意の順番で指定することができます。
.PP
.SH "注釈"
.PP
WITH HOLD が指定されなければ、このコマンドで生成されるカーソルは現在のトランザクションの中でのみ使用することができます。
従って、WITH HOLDの無い\fBDECLARE\fRはトランザクションブロックの外側では意味がありません。その場合カーソルはこの文が完了するまでのみ有効です。
そのため、PostgreSQL はトランザクションブロックの外部でこのコマンドが使用された場合エラーを報告します。
トランザクションブロックを定義するには、BEGIN [\fBbegin\fR(l)]、COMMIT [\fBcommit\fR(l)]、ROLLBACK [\fBrollback\fR(l)] を使用してください。
.PP
WITH HOLD が指定され、カーソルを作成したトランザクションのコミットに成功した場合、同一セッション内でその後のトランザクションでもそのカーソルにアクセスすることができます。
(しかし、トランザクションがアボートした場合、そのカーソルは削除されます。)
WITH HOLD付きで作成されたカーソルは、そのカーソルに対して明示的な\fBCLOSE\fR が発行された場合やセッションが終了した時に閉ざされます。
現在の実装では、保持されたカーソルで表される行は、その後のトランザクションでも利用できるように、一時ファイルかメモリ領域にコピーされます。
.PP
SCROLL オプションは、定義するカーソルが後方向に取り出すために使用する時には指定しなければなりません。
これは標準 SQL で要求されています。
しかし、以前のバージョンとの互換性のために、PostgreSQL では、カーソルの問い合わせ計画が単純でそのサポートに余計なオーバーヘッドが必要無い場合、 SCROLL なしでも後方向に取り出すことができます。
しかし、アプリケーション開発者にはSCROLL無しで作成されたカーソルからの後方向の取り出しができることに依存しないことを勧めます。
NO SCROLL を指定した場合は、後方向取り出しはどのような場合でも行うことができません。
.PP
標準SQLでは、組み込みSQLにおけるカーソルのみ規定されています。
PostgreSQL サーバはカーソル用の \fBOPEN\fR 文を実装していません。
カーソルは宣言された時に開いたものとみなされています。 
しかし、PostgreSQL 用の埋め込み SQL プリプロセッサである \fBECPG\fR では、\fBDECLARE\fR と \fBOPEN\fR 文などを含め、標準SQLのカーソル規定をサポートしています。
.SH "例"
.PP
カーソルを宣言します。
.sp
.nf
DECLARE liahona CURSOR FOR SELECT * FROM films;
.sp
.fi
カーソル使用のより多くの例については FETCH [\fBfetch\fR(l)] を参照してください。
.SH "互換性"
.PP
標準SQLでは、カーソルを埋め込み SQL 内とモジュール内でのみ使用できます。
PostgreSQLでは対話式にカーソルを使うことができます。
.PP
標準SQLでは、カーソルを使ってデータベースのデータを更新することができます。
全てのPostgreSQLのカーソルは読み取り専用です。 
.PP
BINARY カーソルは PostgreSQL の拡張です。
