FrontPage


Firebird SQLリファレンス:OPEN, FETCH, CLOSE, DECLARE CURSOR, INSERT CURSOR, BASED ON, BEGIN DECLARE SECTION, END DECLARE SECTION



OPEN

 行を読み込むためのカーソルを宣言します。 SQL,DSQL で使用できます。

構文

SQL 形式 :

OPEN [TRANSACTION transaction] cursor;

DSQL 形式 :

OPEN [TRANSACTION transaction] cursor [USING SQL DESCRIPTOR xsqlda]


BLOB 形式 : OPEN(BLOB)を参照。

引数説明
TRANSACTION transaction指定したトランザクション下で実行されます。
cursor指定した名前でカーソルを開きます。カーソル名は、事前に宣言を行っておく必要があります。
USING DESCRIPTOR xsqldaDSQLで使用します。PREPARE系の文で渡したパラメータと対応する、XSQLDAを渡します。


詳細の説明

 OPEN により、DECLARE CURSOR 文で指定したカーソルの条件検索の評価が行われ ます。その結果選択された行のセットが、カーソルで取り扱えるようになります。
 カーソルとは、DECLARE CURSOR 文中の SELECT により選別された行群をアクセス するための一方向のポインタです。それは行単位でのシーケンシャルなアクセスを 行うためのポインタであり、また検索順にのみ進行することが出来ます。
 カーソルの操作は、4つの文の連携により行います。

実行順序解説
1DECLARE CURSORカーソルの宣言を行います。SELECTにより、カーソルでアクセスする行を決定するための検索方法を指定します。
2OPENDECLARE CURSORで指定された検索を実行します。その検索結果が、カーソルの有効な行セットとなります。
3FETCHカーソルの有効な行セットから、現在カーソルが示す行を取り出します。最初の実行で最初の行が取り出せます。
・FETCHの実行により、カーソルは進行します。
4CLOSEカーソルをクローズし、システムリソースを解放します。


用例

 埋め込みSQLで、カーソルを開く例です。

EXEC SQL
  OPEN C;


参照

 CLOSE , DECLARE CURSOR , FETCH






OPEN (BLOB)

 BLOB用カーソルのカーソルを開き、読み込みや挿入のための準備を行います。 SQLで使用できます。

構文

OPEN [TRANSACTION name] cursor {INTO | USING} :blob_id;



引数説明
TRANSACTION transaction指定したトランザクション下で実行されます。省略すると、デフォルトのトランザクションが使用されます。
cursorBLOBカーソルの名前です。
INTO|USINGカーソルのタイプがどちらかを指定します。
INTO : INSERT BLOB用です。
USING : READ BLOB用です。
blob_idBLOB列の識別子です。


詳細の説明

 OPEN により、事前に宣言されたカーソルによる、BLOBデータの読み込みや挿入 のための準備を行います。DECLARE CURSOR 文において READ または INSERT を 指定することにより、そのための OPEN で指定する BLOB ID を取得できます。

  • READ BLOB の場合、blob_id は外のTABLEカーソルから得られます。
  • INSERT BLOB の場合、blob_id はシステムから返されます。
    (訳注:INSERTは行の新規追加なので、新たにIDがシステムで割り振られるのに対し、 READは既存のBLOBをアクセスするためのIDとしてテーブルから取得されたものを 使うという意味だと思われます。ちなみに、BLOBのデータ本体は、通常の列とは 管理方法が異なります。)


用例

 埋め込みSQL用です。BLOBカーソルを宣言した後に開きます。

EXEC SQL
  DECLARE BC CURSOR FOR
    INSERT BLOB PROJ_DESC INTO PRJOECT;

EXEC SQL
  OPEN BC INTO :blob_id;


参照

 CLOSE (BLOB) , DECLARE CURSOR (BLOB) , FETCH (BLOB) , INSERT CURSOR (BLOB)






CLOSE

 開いているカーソルを閉じます。 SQLで使用できます。

構文

CLOSE cursor;



引数説明
cursorクローズしたい、開いているカーソルの名前です。


詳細の説明

 CLOSEにより、指定したカーソルの処理を中断し、カーソル中の有効な行セットや その他のシステムリソースを解放します。
 カーソルとは、DECLARE CURSOR 文中の SELECT により選別された行群をアクセス するための一方向のポインタです。それは行単位でのシーケンシャルなアクセスを 行うためのポインタであり、また検索順にのみ進行することが出来ます。
 カーソルの操作は、4つの文の連携により行います。

実行順序解説
1DECLARE CURSORカーソルの宣言を行います。SELECTにより、カーソルでアクセスする行を決定するための検索方法を指定します。
2OPENDECLARE CURSORで指定された検索を実行します。その検索結果が、カーソルの有効な行セットとなります。
3FETCHカーソルの有効な行セットから、現在カーソルが示す行を取り出します。最初の実行で最初の行が取り出せます。
・FETCHの実行により、カーソルは進行します。
4CLOSEカーソルをクローズし、システムリソースを解放します。


 FETCH 文を、閉じたカーソルに対して実行することは出来ません。カーソルが 閉じられた場合、カーソルが再度オープンされるまでデータベースエンジンは 検索の再評価は行いません。カーソルを再度開くまでの間に他ユーザーによって データベースの変更がコミットされた場合、カーソルの有効な行セットはそれに 応じて変わります。

※COMMIT や ROLLBACK を行うと、個別にCLOSEを行わなくても開いているすべて のカーソルが閉じられます。

用例

 埋め込みSQLで、カーソルのクローズを行う例です。

EXEC SQL
  CLOSE BC;


参照

 CLOSE (BLOB) , COMMIT , DECLARE CURSOR , FETCH , OPEN , ROLLBACK






CLOSE (BLOB)

 開いているBLOBカーソルを閉じ、システムリソースを解放します。 SQLで使用できます。

構文

CLOSE blob_cursor;



引数説明
cursorクローズしたい、開いているBLOBカーソルの名前です。


詳細の説明

 CLOSEにより、現在開いている読み込み・挿入用のBLOBカーソルを閉じます。

 一般的には、以下に示すように、カーソルに対するすべてのBLOBの処理が完全に 終了し、あとは閉じれば良いという状態であることが望ましいです。

  • BLOB READ の場合、そのBLOBセグメントのすべてを読み込んだ状態。
  • BLOB INSERT の場合、そのBLOBセグメントに対する挿入がすべて完了した状態。


用例

 埋め込みSQLで、BLOBカーソルを閉じる例です。

EXEC SQL
  CLOSE BC;


参照

 DECLARE CURSOR (BLOB) , FETCH (BLOB) , INSERT CURSOR (BLOB) , OPEN (BLOB)






FETCH

 開いたカーソルの有効な行セットから検索結果を取得し、ポインタを次の行に 進めます。  SQL,DSQLで使用できます。

構文

SQL 形式 :

FETCH cursor
[INTO :hostvar [[INDICATOR] :indvar]
[, :hostvar [[INDICATOR] :indvar] …]];

DSQL 形式 :

FETCH cursor {INTO | USING} SQL DESCRIPTOR xsqlda

BLOB 形式 : FETCH (BLOB)を参照。



引数説明
cursor行を取得したい開いているカーソルの名前です。
:hostvarFETCHによる検索の値を保持するホスト言語変数です。
・DELETEやUPDATEを行うFETCHによる行取得の場合にはオプションとなります。
・DELETEやUPDATEで変更前の列を表示したい場合には指定が必要です。
:indvar列が不明またはNULL値であることを示すインジケーター変数です。
[INTO|USING] SQL DESCRIPTORXSQLDAを指定するために使用します。
xsqldaXSQLDAが格納されたホスト言語変数です。


詳細の説明

 FETCHにより、プログラムはカーソルの有効な行セットより1行のデータを取り 出します。最初の FETCH では、検索結果の最初の行が取得されます。以降の行は、 FETCHを実行することにより取り出しますが、取得する行がなくなると SQLCOOE に 100 がセットされます。

 カーソルとは、DECLARE CURSOR 文中の SELECT により選別された行群をアクセス するための一方向のポインタです。それは行単位でのシーケンシャルなアクセスを 行うためのポインタであり、また検索順にのみ進行することが出来ます。
 カーソルの操作は、4つの文の連携により行います。

実行順序解説
1DECLARE CURSORカーソルの宣言を行います。SELECTにより、カーソルでアクセスする行を決定するための検索方法を指定します。
2OPENDECLARE CURSORで指定された検索を実行します。その検索結果が、カーソルの有効な行セットとなります。
3FETCHカーソルの有効な行セットから、現在カーソルが示す行を取り出します。最初の実行で最初の行が取り出せます。
・FETCHの実行により、カーソルは進行します。
4CLOSEカーソルをクローズし、システムリソースを解放します。


 FETCH で指定する変数の数、サイズ、データタイプ、列の指定順などは、それに 対応する DECLARE CURSOR のクエリ式における指定と適合している必要があります。 もしも適合していない場合は、間違った変数に値が設定されます。

用例

 埋め込みSQLで、カーソルの有効な行セットから列値を取り出す例です。

EXEC SQL
  FETCH PROJ_CNT INTO :department, :hcnt;


参照

 CLOSE , DECLARE CURSOR , DELETE , FETCH (BLOB) , OPEN

 これ以上の情報が欲しい場合、Embedded SQL Guide の cursors と XSQLDA の項 を参照して下さい。






FETCH (BLOB)

 BLOB列の次の有効なセグメントを検索して、指定したバッファに読み込みます。 SQLで使用できます。

構文

FETCH cursor INTO [:<buffer> [[INDICATOR] :segment_length];



引数説明
cursorセグメントを取り出す、開いているBLOBカーソルの名前です。
:bufferBLOB列のセグメントを保管するためのホスト言語変数です。事前に必要なサイズのバッファを確保しておく必要があります。
INDICATORオプションです。今回のFETCHで取り出されたバイト数を格納するホスト言語変数を指定することを指定します。
:segment_lengthFETCHで取り出されたバイト数を格納するホスト言語変数です。


詳細の説明

 FETCHにより、BLOB列の次の有効なセグメントを検索して、指定したバッファに 読み込みます。

 ホスト言語変数 segment_length を指定すると、バッファに取り込まれたバイト数 を取得することが出来ます。これは、バッファとして確保したホスト言語変数よりも 読み込んだデータサイズが小さい場合に有用です。例えば、BLOBの最後のセグメント を読み込む場合などです。

 FETCH は、SQLCODE に二種類の値を返します。

  • SQLCODE = 100 : 取り出すべきBLOBセグメントが以降存在しないことを示します。
  • SQLCODE = 101 : BLOBセグメントの一部が、バッファに設定されていることを 示します。


※確保したホスト言語変数によるバッファのサイズが、FETCH で読み込む BLOB セグメントサイズよりも大きいことを保証するために、BASED ON 文の SEGMENT オプションを使用してください。

用例

 埋め込みSQLで、BLOB に対する FETCH を行う例です。

while (SQLCODE != 100)
{
    EXEC SQL
      OPEN BLOB_CUR USING :blob_id;
    EXEC SQL
      FETCH BLOB_CUR INTO :blob_segment :blob_seg_len;
    while (SQLCODE !=100 || SQLCODE == 101)
    {
        blob_segment{blob_seg_len + 1] = '0';
        printf("%*.*s",blob_seg_len,blob_seg_len,blob_segment);
        blob_segment{blob_seg_len + 1] = ‘ ’;
        EXEC SQL
          FETCH BLOB_CUR INTO :blob_segment :blob_seg_len;
    }
    /* その他の処理 */
}


参照

 BASED ON , CLOSE (BLOB) , DECLARE CURSOR (BLOB) , INSERT CURSOR (BLOB) , OPEN (BLOB)






DECLARE CURSOR

 テーブルに対するカーソルを宣言します。カーソルの名前と、SELECT文により 指定される行セットを関連付けます。 SQL,DQLで使用できます。

構文

SQL 形式 :

DECLARE cursor CURSOR FOR <select> [FOR UPDATE OF <col> [, <col>…]];


DSQL 形式 :

DECLARE cursor CURSOR FOR <statement_id>


BLOB 形式 : DECLARE CURSOR (BLOB)を参照



引数説明
cursorカーソルの名前です。
selectカーソルの行セットとして選択する行を決定する SELECT 文です。SQLでのみ指定します。
FOR UPDATE OF col [, col …]検索行の指定した列に対する UPDATE、DELETE を可能とします。
statement_id事前に(PREPARE)により準備された SQL 文の名前です。その文は SELECT である必要があります。DSQLでのみ使用します。


詳細の説明

 DECLARE CURSOR により、カーソルと名前を宣言し、それにより検索できる行セット を定義します。それは、シーケンシャルに使用しなければならない、テーブルカーソル ステートメントグループの最初のメンバーです。

 selectで指定した SELECT 文で検索される行が行セットに設定されます。 そのSELECT文には、INTO や ORDER BY句を含むことは出来ません。

 FOR UPDATE OF 句は、更新や削除を行うために WHERE CURRENT OF と UPDATE/DELETE を併用する場合に、指定を行う必要があります。

 カーソルとは、DECLARE CURSOR 文中の SELECT により選別された行群をアクセス するための一方向のポインタです。それは行単位でのシーケンシャルなアクセスを 行うためのポインタであり、また検索順にのみ進行することが出来ます。
 カーソルの操作は、4つの文の連携により行います。

実行順序解説
1DECLARE CURSORカーソルの宣言を行います。SELECTにより、カーソルでアクセスする行を決定するための検索方法を指定します。
2OPENDECLARE CURSORで指定された検索を実行します。その検索結果が、カーソルの有効な行セットとなります。
3FETCHカーソルの有効な行セットから、現在カーソルが示す行を取り出します。最初の実行で最初の行が取り出せます。
・FETCHの実行により、カーソルは進行します。
4CLOSEカーソルをクローズし、システムリソースを解放します。


用例

  • 埋め込みSQLでの例です。検索条件を指定してカーソルを宣言しています。
    EXEC SQL
      DECLARE C CURSOR FOR
        SELECT CUST_NO, ORDER_STATUS
          FROM SALES
          WHERE ORDER_STATUS IN ('open', 'shipping');


  • DSQLで、QUERY1という名前の事前に準備された文をもとにしてカーソルを宣言 します。
    DECLARE Q CURSOR FOR QUERY1


参照

 CLOSE , DECLARE CURSOR (BLOB) , FETCH , OPEN , PREPARE , SELECT






DECLARE CURSOR (BLOB)

 読み込みや挿入用BLOBカーソルを宣言します。 SQLで使用できます。

構文

DECLARE cursor CURSOR FOR
  {READ BLOB column FROM table | INSERT BLOB column INTO table}
  [FILTER [FROM subtype] TO subtype]
  [MAXIMUM_SEGMENT length];



引数説明
cursorBLOBカーソルの名前です。
columnBLOBカーソルと関連付けるBLOB列の名前です。
tableテーブルの名前です。
READ BLOBBLOBの読込みに使用するカーソルであることを宣言します。
INSERT BLOBBLOBの書込みに使用するカーソルであることを宣言します。
[FILTER [FROM subtype] TO subtype]オプション指定です。BLOBフィルタによるユーザー指定のフォーマット変換を行います。指定したサブタイプにより、どのフィルタにより変換が行われるかを決定します。
MAXIMUM_SEGMENT lengthFETCH実行時にBLOBのデータを受取るローカル変数のサイズを指定します。


詳細の説明

 DECLARE CURSOR により、BLOBデータの読込みや挿入を行うためのカーソルを 宣言します。BLOBカーソルは、BLOB列以外と関連付けることは出来ません。

 読込みに使用するホスト言語変数のサイズが BLOB セグメントのサイズよりも 小さい場合には、MAXIMUM_SEGMENT 句を指定して宣言を行ってください。 その長さが、BLOBセグメントのサイズよりも小さい場合、FETCHは読込んだバイト数 を返します。未指定デフォルトの場合やセグメントのサイズよりも大きい場合は、 すべてのセグメントを読込みます。

用例

  • 埋め込みSQLの例です。MAXIMUM_SEGMENT オプションの指定と同時に READ BLOB カーソルを宣言します。
    EXEC SQL
      DECLARE BC CURSOR FOR
        READ BLOB JOB_REQUIREMENT FROM JOB MAXIMUM_SEGMENT 40;


  • 埋め込みSQLの例です。INSERT BLOB カーソルを宣言します。
    EXEC SQL
      DECLARE BC CURSOR FOR
        INSERT BLOB JOB_REQUIREMENt INTO JOB;


参照

 CLOSE (BLOB) , FETCH (BLOB) , INSERT CURSOR (BLOB) , OPEN (BLOB)






INSERT CURSOR (BLOB)

 BLOBセグメント単位もしくはそれ以下のサイズのデータを、BLOBカーソルにより 挿入します。 SQLで使用できます。

構文

INSERT CURSOR cursor VALUES (:buffer [INDICATOR] :bufferlen);



引数説明
cursorBLOBカーソルの名前です。
VALUES挿入するバッファ変数とその長さを指定します。
:buffer挿入するデータのバッファとなるホスト変数です。
INDICATORバッファのデータ長が続いて指定されることを示します。
:bufferlen挿入するバッファのデータ長です。バイト数指定です。


詳細の説明

 INSERT CURSOR により、BLOBデータを列に書き込みます。一回の書き込みで、 BLOBセグメントサイズまたそれ以下のデータを書き込めます。
 BLOBカーソルにデータを挿入する前に、

  • ローカル変数とバッファを宣言し、そこに挿入するデータを設定してください。
  • バッファのサイズを格納する変数を宣言してください。
  • BLOBカーソルを INSERT としてオープンしてください。


 一回のBLOB列へのINSERTで、その時に指定したバッファの内容を挿入します。 文と文の間でバッファに新しいデータを設定してください。そして、それぞれの バッファのBLOBへの書き込みが終わるまで、それを繰り返します。

重要 INSERT CURSOR を実行するには、テーブルの対する INSERT 特権が必要 です。特権は、GRANT や REVOKE 文により制御されます。

用例

 埋め込みSQLでの例です。BLOBカーソルによる挿入を行います。

EXEC SQL
  INSERT CURSOR BC VALUES (:line INDICATOR :len);


参照

 CLOSE (BLOB) , DECLARE CURSOR (BLOB) , FETCH (BLOB) , OPEN (BLOB)






BASED ON

 列の仕様に基づいたアクセス用ホスト言語変数を宣言します。 SQLで使用できます。

構文

BASED [ON] [dbhandle.]table.col[.SEGMENT] variable;



引数説明
dbhandleマルチデータベースプログラムにおいて、データベースのハンドルを指定します。事前に SET DATABASE により宣言されている必要があります。
table.col変数のベースとなる、テーブル名とその列名です。
.SEGMENTローカル変数のサイズを、BLOB FETCH 操作のために BLOB 列のセグメントサイズとします。table.colの列がBLOB型のときに指定できます。
variable指定したデータベース列の仕様を継承するホスト言語変数名です。


詳細の説明

 BASED ON はプリプロセッサ用のディレクティブであり、列定義に基づいたホスト 言語変数を作成します。そのホスト言語変数は、列定義のために記述された特徴や 変数型を、プログラム中で扱えるようにします。例えば、C言語でVARCHARに基づいた 変数を作成する場合、NULLターミネータを設定するためにサイズが1加算されます。

 BASED ON は、プログラムの変数宣言を行うセクションで使用します。

※ BASED ONは、キーワード EXEC SQL を必要としません。

 BLOB用のホスト言語変数を作成する場合、FETCH操作でのBLOBセグメントサイズ よりも大きなサイズの変数を確保するために、SEGMENTオプションを BASED ON で 指定して下さい。これにより、変数のサイズはBLOB列のセグメント長から決定され ます。このため、データベースのBLOBセグメントサイズが変更された場合は、 プログラムの再コンパイルを行い、BASED ON によるホスト言語変数のサイズを 再調整する必要があります。

用例

 埋め込みSQLの例です。列に基づいたホスト変数を宣言しています。

EXEC SQL
  BEGIN DECLARE SECTION;

BASED_ON EMPLOYEE.SALARY salary;

EXEC SQL
  END DECLARE SECTION;


参照

 BEGIN DECLARE SECTION , CREATE TABLE , END DECLARE SECTION






BEGIN DECLARE SECTION

 ホスト言語変数宣言セクションの開始を示します。 SQLで使用できます。

構文

BEGIN DECLARE SECTION;

詳細の説明

 BEGIN DECLARE SECTION により、埋め込みSQLアプリケーションにおいて以降の SQL文で使用できるホスト言語変数宣言の開始を示します。 BEGIN DECLARE SECTION はプリプロセッサのディレクティブです。また、この文に より、gpre は SQLCODE をアプリケーションプログラマが使用できるよう、自動的 に宣言します。

重要 BEGIN DECLARE SECTION は、常にモジュールのグローバル変数を宣言する セクションで使用される必要があります。

用例

 埋め込みSQLで、ホスト言語変数を宣言する例です。

EXEC SQL
  BEGIN DECLARE SECTION;

BASED ON EMPLOYEE.SALARY salary;

EXEC SQL
  END DECLARE SECTION;


参照

 BASED ON , END DECLARE SECTION






END DECLARE SECTION

 ホスト言語変数宣言セクションの終了を示します。 SQLで使用できます。

構文

END DECLARE SECTION;

詳細の説明

 END DECLARE SECTION により、埋め込みSQLアプリケーションにおいて以降の SQL文で使用できるホスト言語変数宣言セクションの終了を示します。

用例

 埋め込みSQLで、宣言セクションにおいて1つのホスト言語変数を宣言する例です。

EXEC SQL
  BEGIN DECLARE SECTION;

BASED_ON EMPLOYEE.SALARY salary;

EXEC SQL
  END DECLARE SECTION;


参照

 BASED ON , BEGIN DECLARE SECTION