DECLARE STATEMENTのソース

[[FrontPage]]へ~
-[[リファレンスガイド]]へ~
--[[Firebird SQLリファレンス]]へ~
&br;
----
*Firebird SQLリファレンス:DECLARE STATEMENT, DESCRIBE, EXECUTE, EXECUTE IMMEDIATE, PREPARE, WHENEVER [#m0ffc5cd]

#contents

----

&br;
&aname(declare_statement);
*DECLARE STATEMENT [#g7aabedc]
　埋め込みSQLのプログラムにおいて、PREPARE,EXECUTEを実行する前準備として 動的SQL文の識別子を宣言します。 SQLで使用可能です。

&br;
**構文 [#q29e2965]
 DECLARE <statement> STATEMENT;

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

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

&br;
**用例 [#c8f08dd5]
　埋め込みSQLの例です。Q1 が PREPARE,EXECUTEのための文字列であることを宣言 します。
 EXEC SQL
  DECLARE Q1 STATEMENT;

&br;
**参照 [#h82d4699]
　[[EXECUTE>#execute]] , [[EXECUTE IMMEDIATE>#execute_immediate]] , [[PREPARE>#prepare]]

&br;
----
&br;
&br;
&aname(describe);
*DESCRIBE [#r0dc70e6]
動的SQL文(DSQL)により検索される列に関する情報、または動的パラメータに 関する情報を提供します。 SQLで使用可能です。

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

&br;
**詳細の説明 [#pdd7dcba]

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

&br;
DESCRIBEは、下表に示すようなDSQLを処理するための文の1つです。
&br;
|文|使用目的|h
|PREPARE|実行するDSQL文の準備を行います。|
|DESCRIBE|文の実行に関する情報を、XSQLDAに設定します。|
|EXECUTE|事前のPREPARE文により準備されたDSQL文を、実際に実行します。|
|EXECUTE IMMEDIATE|本文１回の実行で、PREPAREによるDSQL文の準備とEXECUTEにより実行を行います。ただし、実行結果はそのまま廃棄されます。|

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

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

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

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

&br;
**用例 [#g73544d7]
&br;
　すべて埋め込みSQLでの例です。
&br;
-SELECT文による検索結果出力についての情報を示します。
 EXEC SQL
  DESCRIBE Q INTO xsqlda
&br;
-実行時に引き渡す動的パラメータに関する情報を格納します。
 EXEC SQL
  DESCRIBE INPUT Q2 USING SQL DESCRIPTOR xsqlda;
&br;
**参照 [#r365a053]
　[[EXECUTE>#execute]] , [[EXECUTE IMMEDIATE>#execute_immediate]] , [[PREPARE>#prepare]]

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


&br;
----


&br;
&aname(execute);
*EXECUTE [#fe9bad58]
&br;
　事前に準備された動的SQL(DSQL)文を実行します。 SQLで使用できます。

&br;
**構文 [#p32fe673]
 EXECUTE [TRANSACTION transaction] statement
  [USING SQL DESCRIPTOR xsqlda] [INTO SQL DESCRIPTOR xsqlda];


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


&br;
**詳細の説明 [#lb5fae5d]
　EXECUTE により、事前に(PREPAREで)準備された DSQL 文を発行します。 １つの文で、１グループのDSQL文を処理できます。

&br;
　EXECUTEは、下表に示すようなDSQLを処理するための文の1つです。
&br;
|文|使用目的|h
|PREPARE|実行するDSQL文の準備を行います。|
|DESCRIBE|文の実行に関する情報を、XSQLDAに設定します。|
|EXECUTE|事前のPREPARE文により準備されたDSQL文を、実際に実行します。|
|EXECUTE IMMEDIATE|本文１回の実行で、PREPAREによるDSQL文の準備とEXECUTEにより実行を行います。ただし、実行結果はそのまま廃棄されます。|
&br;


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

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

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

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

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


&br;
**用例 [#df151a22]
　すべて埋め込み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;

&br;

**参照 [#edeaef2a]
　[[DESCRIBE>#describe]] , [[EXECUTE IMMEDIATE>#execute_immediate]] , [[PREPARE>#prepare]]

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




&br;
----

&br;
&aname(execute_immediate);
*EXECUTE IMMEDIATE [#x2a592fc]
　動的SQL(DSQL)文の、準備と実行を１回で行いますが、実行結果は取得できません。 SQLで使用できます。

&br;
**構文 [#a345670f]
 EXECUTE IMMEDIATE [TRANSACTION transaction]
  {:variable | 'string'} [USING SQL DESCRIPTOR xsqlda];



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

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

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

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

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



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

 EXEC SQL
  EXECUTE IMMEDIATE :insert_date;


**参照 [#s61359df]
　[[DESCRIBE>#describe]] , [[EXECUTE IMMEDIATE>#execute_immediate]] , [[PREPARE>#prepare]]


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


&br;
----

&br;
&br;
&aname(prepare);
*PREPARE [#x9e4ee39]
　動的SQL(DQSL)文を実行するための、準備を行います。 SQLで使用できます。


**構文 [#fe1638d9]
 PREPARE [TRANSACTION transaction] statement
  [INTO SQL DESCRIPTOR xsqlda] FROM {:variable | 'string'};


&br;

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


&br;
**詳細の説明 [#ddb6ad8d]
　PREPARE により、繰り返し実行する DSQL 文に対して、以下のような準備を 行います。

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

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

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

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

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

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

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


&br;
**用例 [#j6286171]
　すべて埋め込み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;

&br;
**参照 [#necaabe1]
　[[DESCRIBE>#describe]] , [[EXECUTE>#execute]] ,  [[EXECUTE IMMEDIATE>#execute_immediate]]





&br;
----
&br;
&br;
&aname(whenever);
*WHENEVER [#n837c5b6]
　SQLCODE によるエラーや警告をトラップします。 SQLで使用できます。

&br;
**構文 [#r905e450]
 WHENEVER {NOT FOUND | SQLERROR | SQLWARNING}
  {GOTO label | CONTINUE};


&br;
|引数|説明|h
|NOT FOUND|SQLCODE = 100 の条件でトラップします。（クエリの実行結果で行が取得できなかった）|
|SQLERROR|SQLCODE < 0 の条件でトラップします。（実行失敗）|
|SQLWARNING|SQLCODE > 0 AND < 100 の条件でトラップします。（システムの警告またはインフォーメーションメッセージ）|
|GOTO label|指定エラーを検知したときにジャンプする位置を指定するラベルを指定します。|
|CONTINUE|警告やエラーを無視して、可能な限り実行を継続します。|

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

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

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

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

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

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


&br;
**用例 [#z975e4c8]
　埋め込み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. */

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