DECLARE STATEMENT

リファレンスガイドへ
- Firebird SQLリファレンスへ

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

Firebird SQLリファレンス:DECLARE STATEMENT, DESCRIBE, EXECUTE, EXECUTE IMMEDIATE, PREPARE, WHENEVER
DECLARE STATEMENT
- 構文
- 詳細の説明
- 用例
- 参照
DESCRIBE
- 構文
- 詳細の説明
- 用例
- 参照
EXECUTE
- 構文
- 詳細の説明
- 用例
- 参照
EXECUTE IMMEDIATE
- 構文
- 詳細の説明
- 用例
- 参照
PREPARE
- 構文
- 詳細の説明
- 用例
- 参照
WHENEVER

DECLARE STATEMENT

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

構文

DECLARE <statement> STATEMENT;

引数	説明
statement	SQL変数の名前です。実行時にユーザーより提供される、実行させたいSQL文のための物です。

詳細の説明

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;

引数	説明
OUTPUT	省略時デフォルトです。列情報が、XSQLDAにより返されるべきであることを示します。
INPUT	動的パラメータの情報が、XSQLDAに格納されるべきであることを示します。
statement	DESCRIBEよりも前に定義された文の別名です。
statement	・別名の定義は、PREPAREを使用します。
{INTO｜USING} SQL DESCRIPTOR xsqlda	DESCRIBEで使用するXSQLDAを指定します。

詳細の説明

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

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

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

文	使用目的
PREPARE	実行するDSQL文の準備を行います。
DESCRIBE	文の実行に関する情報を、XSQLDAに設定します。
EXECUTE	事前のPREPARE文により準備されたDSQL文を、実際に実行します。
EXECUTE IMMEDIATE	本文１回の実行で、PREPAREによるDSQL文の準備とEXECUTEにより実行を行います。ただし、実行結果はそのまま廃棄されます。

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];

引数	説明
TRANSACTION transaction	指定したトランザクション下で実行されます。
statement	事前にPREPAREなどで準備した実行文の別名です。
USING SQL DESCRIPTOR	準備された文用のパラメータと対応するXSQLDAを指定します。
INTO SQL DESCRIPTOR	実行の結果として返って来た値を格納する、XSQLDAを指定します。
xsqlda	XSQLDA ホスト言語変数です。

詳細の説明

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

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

文	使用目的
PREPARE	実行するDSQL文の準備を行います。
DESCRIBE	文の実行に関する情報を、XSQLDAに設定します。
EXECUTE	事前のPREPARE文により準備されたDSQL文を、実際に実行します。
EXECUTE IMMEDIATE	本文１回の実行で、PREPAREによるDSQL文の準備とEXECUTEにより実行を行います。ただし、実行結果はそのまま廃棄されます。

　文を実行する前に、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];

引数	説明
TRANSACTION transaction	指定したトランザクション下で実行されます。
:variable	実行したいDSQL文を格納したホスト言語変数です。
'string'	実行したいDSQL文を含んだ文字時列リテラルです。
USING SQL DESCRIPTOR	準備された文用のパラメータと対応するXSQLDAを指定します。
xsqlda 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'};

引数	説明
TRANSACTION transaction	指定したトランザクション下で実行されます。
statement	準備を行う文の別名を宣言します。DESCRIBEやEXECUTEに先立って宣言する必要があります。
INTO xsqlda	準備する文の実行結果(選択列リスト)を格納する、XSQLDAを指定します。
:variable｜'string'	準備するDSQL文です。格納したホスト言語変数または文字列リテラルにより指定します。

詳細の説明

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

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

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

文	使用目的
PREPARE	実行するDSQL文の準備を行います。
DESCRIBE	文の実行に関する情報を、XSQLDAに設定します。
EXECUTE	事前のPREPARE文により準備されたDSQL文を、実際に実行します。
EXECUTE IMMEDIATE	本文１回の実行で、PREPAREによるDSQL文の準備とEXECUTEにより実行を行います。ただし、実行結果はそのまま廃棄されます。

　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};

引数	説明
NOT FOUND	SQLCODE = 100 の条件でトラップします。（クエリの実行結果で行が取得できなかった）
SQLERROR	SQLCODE < 0 の条件でトラップします。（実行失敗）
SQLWARNING	SQLCODE > 0 AND < 100 の条件でトラップします。（システムの警告またはインフォーメーションメッセージ）
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 を参照して下さい。