FrontPageへ

Firebird SQLリファレンス:DECLARE STATEMENT, DESCRIBE, EXECUTE, EXECUTE IMMEDIATE, PREPARE, WHENEVER


DECLARE STATEMENT

　埋め込みSQLのプログラムにおいて、PREPARE,EXECUTEを実行する前準備として 動的SQL文の識別子を宣言します。 SQLで使用可能です。


構文 

DECLARE <statement> STATEMENT;



詳細の説明

DECLARE STATEMENT により、実行時にユーザーより提供されるSQL文を実行する ためのSQL変数の指定を行います。DECLARE STATEMENT 文の実行は行われませんので、 実行時にエラーが発生することはありません。この文は、内部作業用 ドキュメンテーションとして使用されます。


用例

　埋め込みSQLの例です。Q1 が PREPARE,EXECUTEのための文字列であることを宣言 します。

EXEC SQL
 DECLARE Q1 STATEMENT;


参照

　EXECUTE , EXECUTE IMMEDIATE , PREPARE




DESCRIBE

動的SQL文(DSQL)により検索される列に関する情報、または動的パラメータに 関する情報を提供します。 SQLで使用可能です。


構文 

DESCRIBE [OUTPUT | INPUT] statement
 {INTO | USING} SQL DESCRIPTOR xsqlda;



詳細の説明


DESCRIBE には、２つの用途があります。

  • OUTPUTを指定した場合、PREPAREに提供する選択リストで作成される列の情報を XSQLDAに格納します。PREPAREにINTO句を含む場合は、OUTPUTを指定したDESCRIBE は不要です。
  • INPUTを指定した場合、前のPREPAREに対する動的パラメータをXSQLDAに格納します。


DESCRIBEは、下表に示すようなDSQLを処理するための文の1つです。


INPUT指定DESCRIBEとOUTPUT指定のDESCRIBEは、個別に発行する必要があります。 動的パラメータを格納する場合には、必ずINPUT指定によるDESCRIBEを実行する 必要があります。


重要　OUTPUT指定のDESCRIBEにおいて、もしもXSQLDAのsqldフィールドに返される 値がsqlnフィールドの値よりも大きい場合、あなたは次のことを行う必要があります。


  • XSQLVARに割当てられた記憶領域の割当量を増やします。
  • DESCRIBE文を再実行します。


※　同じ XSQLDA構造体を、入力と出力で使用することも出来ます。


用例


　すべて埋め込みSQLでの例です。

  • SELECT文による検索結果出力についての情報を示します。 
    EXEC SQL
 DESCRIBE Q INTO xsqlda

  • 実行時に引き渡す動的パラメータに関する情報を格納します。 
    EXEC SQL
 DESCRIBE INPUT Q2 USING SQL DESCRIPTOR xsqlda;

参照

　EXECUTE , EXECUTE IMMEDIATE , PREPARE


　これ以上の情報が欲しい場合は、Embedded SQL Guideの DSQL programming と、 XSQLDAに関する項を参照して下さい。



EXECUTE


　事前に準備された動的SQL(DSQL)文を実行します。 SQLで使用できます。


構文 

EXECUTE [TRANSACTION transaction] statement
 [USING SQL DESCRIPTOR xsqlda] [INTO SQL DESCRIPTOR xsqlda];



詳細の説明

　EXECUTE により、事前に(PREPAREで)準備された DSQL 文を発行します。 １つの文で、１グループのDSQL文を処理できます。


　EXECUTEは、下表に示すようなDSQLを処理するための文の1つです。


　文を実行する前に、PREPARE文による準備が行われている必要があります。 実行される文は、DSQLでサポートしているデータ定義、操作、トランザクション管理 などのすべての文が使用できます。また、１回のPRPAREに対し複数のEXECUTEを実行 することも出来ます。


　TRANSACTION句は、多重トランザクション処理を行うSQLアプリケーションにおいて、 どのトランザクション下で EXECUTE の処理が行われるかを明示するために使用 します。


　USING DESCRIPTOR句は、アプリケーションが設定するXSQLDA構造体により提供 される文用のパラメータを、EXECUTE時に引き渡すために使用します。動的パラメータ を必要とする文を実行するときにのみ使用します。


　INTO DESCRIPTOR句は、EXECUTEにより返ってくる結果をアプリケーションが参照 するために、その実行結果を格納する XSQLDA 構造体を指定します。値を返すDSQL文 を実行する場合のみ使用します。


※　もしも、EXECUTEで実行する文が USING DESCRIPTOR と INTO DESCRIPTOR の両方 を使用する場合、XSQLDA構造体は２つ用意する必要があります。


用例

　すべて埋め込みSQLでの例です。

  • 事前に準備されたDSQL文を実行します。 
    EXEC SQL
 EXECUTE DOUBLE_SMALL_BUDGET;
  • 事前に準備された、XSQLDAに格納されたパラメータを使用する文を実行します。 
    EXEC SQL
 EXECUTE Q USING DESCRIPTOR xsqlda;
  • 事前に準備された、XSQLDAに格納されたパラメータを使用し、実行結果を２つめ のXSQLDAに格納する文を実行します。 
    EXEC SQL
 EXECUTE Q USING DESCRIPTOR xsqlda_1 INTO DESCRIPTOR xsqlda_2;


参照

　DESCRIBE , EXECUTE IMMEDIATE , PREPARE


　これ以上の情報が欲しい場合は、Embedded SQL Guideの DSQL programming と、 XSQLDAに関する項を参照して下さい。



EXECUTE IMMEDIATE

　動的SQL(DSQL)文の、準備と実行を１回で行いますが、実行結果は取得できません。 SQLで使用できます。


構文 

EXECUTE IMMEDIATE [TRANSACTION transaction]
 {:variable | 'string'} [USING SQL DESCRIPTOR xsqlda];


詳細の説明

　EXECUTE IMMEDIATE により、ホスト言語変数に格納もしくは文字列リテラルで 指定したDSQL文を実行出来ます。ただし、その結果の取得はできません。 DSQL文を繰り返し実行する場合や検索などの結果を取得したい場合は、 EXECUTE IMMDIATE の代わりに PREPARE と EXECUTE を使用してください。


　TRANSACTION句は、多重トランザクション処理を行うSQLアプリケーションにおいて、 どのトランザクション下で EXECUTE IMMEDIATE の処理が行われるかを明示するために 使用します。


　実行したDSQL文は、ホスト言語変数に格納もしくは文字列リテラルの指定により 与えます。これに含めることが出来るSQL文は、データ定義またはデータ操作文と なります。


　USING DESCRIPTOR句は、アプリケーションが設定するXSQLDA構造体により提供 される文用のパラメータを、EXECUTE IMMEDIATE時に引き渡すために使用します。 動的パラメータを必要とする文を実行するときにのみ使用します。

用例

　埋め込みSQLでの例です。ホスト言語変数(insert_date)で与えられた文を、 準備して即実行します。

EXEC SQL
 EXECUTE IMMEDIATE :insert_date;

参照

　DESCRIBE , EXECUTE IMMEDIATE , PREPARE

　これ以上の情報が欲しい場合は、Embedded SQL Guideの DSQL programming と、 XSQLDAに関する項を参照して下さい。




PREPARE

　動的SQL(DQSL)文を実行するための、準備を行います。 SQLで使用できます。

構文 

PREPARE [TRANSACTION transaction] statement
 [INTO SQL DESCRIPTOR xsqlda] FROM {:variable | 'string'};



詳細の説明

　PREPARE により、繰り返し実行する DSQL 文に対して、以下のような準備を 行います。

  • 文に対する文法チェックが行われます。
  • オプションにより指定された動的パラメータのデータ型を決定します。
  • 文の最適化を行います。
  • EXECUTEによる実行を行うためのコンパイル作業を行います。


　PREPARE は、下表に示すようなDSQLを処理するための文の1つです。



　PREPARE により文の準備を行った場合、その文を現在のセッションのまま複数回 実行することが出来ます。準備と実行を１回しか行わない場合は、EXECUTE IMMEDIATE を使用出来ます。


　PREPARE により、準備するDSQL文を抽象化するためのシンボル名を宣言します。 その宣言はホスト変数の宣言ではありません。また、C言語以外の環境では大文字と 小文字の区別は行われません。("B"と"b"は同じ文字として扱われます)。 C言語では、プリプロセッサ処理の"gpre -either_case"オプションの指定により、 動作を選択できます。


　オプションのINTO が指定された場合、PREPARE の実行により拡張SQL ディスクリプションエリア(XSQLDA)に対し、選択リスト列の情報(データ型、長さ、 名前)が設定されます。この記述を使用するのは、準備する文がSELECTである場合 のみです。 ※　INTO 句で XSQLDA を設定する代わりに、DESCRIBE文を使用することも可能です。


　FROM では、PRPARE により準備を行いたい実際の DSQL 文を指定します。 指定は、ホスト言語変数もしくはシングルクォーテーションで囲んだ文字列リテラル により行います。PRPARE で使用できる DSQL 文は、すべての SQLデータ定義、操作、 トランザクション制御文です。


用例

　すべて埋め込みSQLでの例です。

  • ホスト言語変数によりDSQL文を与えて準備を行います。SELECT文をホスト言語変数 に格納するので、INTO の指定も同時に行っています。 
    EXEC SQL
 PREPARE Q INTO xsqlda FROM :buf;
  • 上の例と同じですが、PREPARE と DESCRIBE を使用しています。 
    EXEC SQL
 PREPARE Q FROM :buf;
EXEC SQL
 DESCRIBE Q INTO SQL DESCRIPTOR xsqlda;


参照

　DESCRIBE , EXECUTE , EXECUTE IMMEDIATE




WHENEVER

　SQLCODE によるエラーや警告をトラップします。 SQLで使用できます。


構文 

WHENEVER {NOT FOUND | SQLERROR | SQLWARNING}
 {GOTO label | CONTINUE};



詳細の説明

　WHENEVER により、SQLCODE に設定されたエラーと警告をトラップできます。 すべての実行可能なSQL文は、SQLCODEに処理成功または失敗を示す値を設定します。 もしも SQLCODE が 0 であるならば、処理は成功しています。0以外の値が設定 されている場合は、エラー、警告、検索行なしのいずれかの状態を示しています。


　WHENEVERにより指定した状態をトラップした場合は、下記のいずれかの処理を 行います。

  • GOTOを指定した場合は、ラベルで指定したエラーをハンドリングするルーチンに ジャンプします。
  • CONTINUEを指定した場合は、エラーなどの状態は無視されます。


　WHENEVER を使用することにより、アプリケーションのサイズを小さくすることが 可能です。なぜなら、一揃いのエラー・警告処理ルーチンをすべてのエラー処理で 使用することが可能となるためです。


　WHENEVER は、エラーを発生させる可能性があるどのような SQL 文よりも前で 使用されるべきです。 　また、トラップする条件ごとに WHENEVER 文を用意する必要があります。 このため、WHENEVER を省略した条件がある場合は、その条件はトラップされて いません。


※　エラールーチンによる無限ループを防ぐために、エラーハンドリング処理 では "WHENEVER ... CONTINUE" を先行して配置するようにして下さい。


用例

　埋め込みSQLでの例です。３つの WHENEVER 文によりエラーと警告をハンドリング しています。

EXEC SQL
 WHENEVER SQLERROR GO TO Error; /* Trap all errors. */

EXEC SQL
 WHENEVER NOT FOUND GO TO AllDone; /* Trap SQLCODE = 100 */

EXEC SQL
WHENEVER SQLWARNING CONTINUE; /* Ignore all warnings. */


　これ以上の情報が欲しい場合は、Embedded SQL Guide の error-handling methods and programming を参照して下さい。