CREATE EXCEPTIONのソース

FrontPageへ

- リファレンスガイドへ
-- Firebird SQLリファレンスへ
----
* Firebird SQLリファレンス:CREATE EXCEPTION, ALTER EXCEPTION, DROP EXCEPTION, EVENT INIT, EVENT WAIT [#u14d0878]

#contents
----


* CREATE EXCEPTION [#u4a44677]

　ストアドプロシージャやトリガで使用する、ユーザー定義のエラーとメッセージを作成します。 DSQL,isql で使用できます。
　この文書は、公開されているIB6のSQLリファレンスを基としています。

** 構文 [#o425e001]

 CREATE EXCEPTION name 'message';


※　DSQLで使用する場合、終端文字のセミコロンは不要です。 isqlでは行の終わりを示すために終端文字は必要です。

|~引数|~説明|
|name|例外メッセージと関連付ける名前です。所属するデータベース内での例外名において、一意である必要があります。|
|'message'|英数字と句読点で構成された例外メッセージを、シングルクォーテーションで囲んだ文字列です。最大で78文字となっています。|



** 詳細の説明 [#vf662c49]

　[[CREATE EXCEPTION]] により、例外(メッセージと関連付けられたユーザーが定義するエラー)を作成します。定義した例外は、トリガやストアドプロシージャなどで発生させることが出来ます。

　定義した例外は、データベース内でグローバルなものとなります。設定したメッセージやメッセージのセットは、すべてのストアドプロシージャやトリガで使用することが出来ます。
　例えば、データベースで例外に対するメッセージとして英語とフランス語版の２つを持ち、使用するときに必要とする適切なセットを選択することが出来ます。

　トリガまたはストアドプロシージャで例外を発生させた場合、

- そのトリガ、プロシージャの処理は終了します。また、それらが行ったアクションは、直接・間接を問わずにすべて取り消されます。
- エラーメッセージを、呼び出したアプリケーションに返します。isqlでは、出力がリダイレクトされていない限り、エラーメッセージが画面に表示されます。


　WHENによりストアドプロシ−ジャやトリガ内における例外トラップとハンドルをっている場合、その処理が閉じている場合もあります。


** 用例 [#k6f43b08]

- 以下、一連の動作になっています。
-- isqlにより、UNKNOWN_EMP_IDという名前の例外を作成します。

 CREATE EXCEPTION UNKNOWN_EMP_ID 'Invalid employee number or project id.';

-- 以降に定義するストアドプロシージャ内で、SQLCODE -530(FOREIGN KEY制約違反) をハンドルし、そこで作成済みの例外(UNKNOWN_EMP_ID)を発生させます。したの例は、ストアドプロシージャの該当部分の処理のみを示しているので注意して下さい。

 . . .
 WHEN SQLCODE -530 DO
 EXCEPTION UNKNOWN_EMP_ID;
 . . .


** 参照 [#mee66646]

　[[ALTER EXCEPTION>#alter_exception]] , [[ALTER PROCEDURE>CREATE PROCEDURE#alter_procedure]] , [[ALTER TRIGGER>CREATE TRIGGER#alter_trigger]] , [[CREATE PROCEDURE]] , [[CREATE TRIGGER]] , [[DROP EXCEPTION>#drop_exception]]

　これ以上の情報が欲しい場合は、Data Definition Guide の creating, raising, and handling exceptions を参照して下さい。


&aname(alter_exception);
* ALTER EXCEPTION [#qb6d84b2]

　既存の例外に対して、関連付けられたメッセージを変更します。 DSQL,isqlで使用できます。
　この文書は、公開されているIB6のSQLリファレンスを基としています。


** 構文 [#w42a8a09]

 ALTER EXCEPTION name 'message'


|~引数|~説明|
|name|例外メッセージと関連付ける既存の例外名です。|
|'message'|英数字と句読点で構成された例外メッセージを、シングルクォーテーションで囲んだ文字列です。最大で78文字となっています。|



** 詳細の説明 [#f20f1dbf]

　ALTER EXCEPTION により、既存の例外エラーメッセージのテキストを変更できます。

　例外の変更が出来るのは、作成者、SYSDBAユーザーまたはOSの管理者権限を持ったユーザーのみです。


** 用例 [#j3c125b1]

　isqlにより、例外のエラーメッセージを変更します。

 ALTER EXCEPTION CUSTOMER_CHECK 'Hold shipment for customer remittance.';



** 参照 [#h5152ceb]

　[[ALTER PROCEDURE>CREATE PROCEDURE#alter_procedure]] , [[ALTER TRIGGER>CREATE TRIGGER#alter_trigger]] , [[CREATE EXCEPTION]] , [[CREATE PROCEDURE]] , [[CREATE TRIGGER]] , [[DROP EXCEPTION>#drop_exception]]

　これ以上の情報が欲しい場合は、Data Definition Guide の creating, raising, and handling exceptions を参照して下さい。



&aname(drop_exception);
* DROP EXCEPTION [#gfc1a87b]

　データベースから例外を削除します。 DSQL,isql で使用できます。
　この文書は、公開されているIB6のSQLリファレンスを基としています。


** 構文 [#h4200ab4]

 DROP EXCEPTION name


|~引数|~説明|
|name|削除を行う、既存である例外の名前です。|



** 詳細の説明 [#q4f0f8ab]

　DROP EXCEPTION により、データベースから例外を削除します。

　削除したい例外が既存のプロシ−ジャやトリガで使用されている場合、削除を行うことは出来ません。

※　isql で SHOW EXCEPTION コマンドを使用することにより、例外とプロシージャ・トリガ間での関連性を表示できます。

　例外の削除を出来るのは、作成者、SYSDBAユーザーおよびOSの管理者権限を持つユーザーのみです。


** 用例 [#y07b272e]

　isql で例外の削除を行う例です。

 DROP EXCEPTION UNKNOWN_EMP_ID;



** 参照 [#y755d715]

　[[ALTER EXCEPTION>#alter_exception]], [[ALTER PROCEDURE>CREATE PROCEDURE#alter_procedure]] , [[ALTER TRIGGER>CREATE TRIGGER#alter_trigger]] , [[CREATE EXCEPTION]] , [[CREATE PROCEDURE]] , [[CREATE TRIGGER]]






&aname(event_init);
* EVENT INIT [#ke00d710]

　データベースエンジンのイベントマネージャにいくつかのイベントを登録します。 SQLで使用できます。
　この文書は、公開されているIB6のSQLリファレンスを基としています。
　またSQLリファレンスの情報が少ないため、IB6 の Embedded SQL Guide からの情報を元に、独自に補足しました。

** 構文 [#ra609f92]

 EVENT INIT request_name [dbhandle]
  [('string' | :variable [, 'string' | :variable …])];


|~引数|~説明|
|request_name|アプリケーションイベントハンドルです。|
|dbhandle|イベント発生を監視するデータベースを指定します。省略した場合、最も最近 SET DATABASE で指定したデータベースとなります。|
|'string'|イベントに関連付けられたイベント名です。一意にイベントを識別できる名前でなければなりません。(訳注:最大の長さは15文字となっています。)|
|:variable|文字配列のホスト言語変数でイベント名のリストを指定します。|



** 詳細の説明 [#rb837fe4]

　EVENT INIT により、データベースエンジンの同期イベントメカニズムの第一段階を行います。同期イベント処理は２つの段階に分かれており、それは以下のようになっています。
+ アプリケーションが EVENT INIT により、イベントを登録します。
+ EVENT WAITにより、イベント発生が報告されるまでアプリケーションは待ちます。

　アプリケーションは、監視を行いたいイベントのリストを括弧で括り、EVENT INIT を実行します。そのリストは、データベースのストアドプロシージャやトリガによりポストされるイベントと一致するべきです。アプリケーションが多重のイベント監視登録を１つの EVENT INIT で行った場合、アプリケーションはどのイベントが発生したのかを判別する必要があります。(訳注:埋め込みSQLの場合、どのイベントが発生したのかを受け渡すシステム変数が用意されています。詳しくは、EVENT WAIT を参照して下さい。)

　ストアドプロシージャまたはトリガでの POST_EVENT によりイベントはポストされます。

　イベントマネージャは、依頼を受けたイベントの追跡を行います。イベントマネージャは、イベントが発生するとその監視を依頼したアプリケーションに通知します。

※訳注 イベント処理のプログラムは、Firebird API を直接叩く方法でも作成できます。どちらかというと、そちらの方が一般的かもしれません。


** 用例 [#md1dbf97]

　埋め込みSQLにより、監視するイベントを登録します。

 EXEC SQL
 EVENT INIT ORDER_WAIT EMPDB ('new_order');



参照

　[[CREATE PROCEDURE]] , [[CREATE TRIGGER]] , [[EVENT WAIT>#event_wait]] , [[SET DATABASE]]

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


&aname(event_wait);
* EVENT WAIT [#z5f16319]

　イベント発生が報告されるまでアプリケーションは処理を待ちます。 SQLで使用できます。
　この文書は、公開されているIB6のSQLリファレンスを基としています。
　またSQLリファレンスの情報が少ないため、IB6 の Embedded SQL Guide からの情報を元に、独自に補足しました。

** 構文 [#f523b048]

 EVENT WAIT request_name;


|~引数|~説明|
|request_name|事前に EVENT INIT により宣言された、アプリケーションイベントハンドルです。|



** 詳細の説明 [#da1d3d2f]

　EVENT WAIT により、データベースエンジンの同期イベントメカニズムの第二段階を行います。監視するイベントを登録した後に EVENT WAIT を実行することにより、その監視するイベントが発生するまでの間、アプリケーションはスリープ状態となります。

（訳注:１度に監視できるのは、１セットのイベントのみということです。ここで言う１セットとは、１つの EVENT INIT で監視設定したイベントということです。複数のイベントを同時に監視したい場合は、そのイベントをリストにして指定した、多重イベントの処理が必要です。）

　通常の１つのイベントを監視するアプリケーションの場合、アプリケーションがサスペンド(スリープ)状態から復帰したときは、どのイベントが報告されたかは明らかです。
　しかし、複数のイベントを指定して１つの EVENT INIT を実行する多重イベントの待ち合わせを行った場合には、イベント配列 isc_event[] によりどのイベントが報告されたのをかを判別する必要があります。イベント配列は、コンパイルのプリプロセッサ処理時に自動生成されます。この配列は、各々の要素が EVENT INIT の引数で指定したイベントリストと対応しています。この配列は、同じイベントハンドルで最後に実行された EVENT WAIT 文以降に報告をうけたイベントの回数を保持しています。
　以下は、３つのイベント監視を登録後にそのままサスペンド状態に入ってイベントの報告を待つ処理の例です。

EXEC SQL
  EVENT INIT RESPOND_MANY ('new_order', 'change_order', 'cancel_order');
EXEC SQL
  EVENT WAIT RESPOND_MANY;
/* もし、"new_order","change_order","cancel_order"のイベントのどれかが
   ポストされて、かつそのトランザクションがコミットされた場合は、
   イベントマネージャーはそれをアプリケーションに報告し、アプリケーション
   の処理を再開させます。
   続いて、アプリケーションはどのイベント報告を受けたかを判別します。 */
for (i = 0; i < 3; i++)
{
    if (isc_$event[i] > 0)
    {
        /* this event occurred, so process it */
        . . .
    }
}



** 用例 [#sc1c776d]

　埋め込み SQL で、イベント名を指定して監視イベントの登録を行い、そのままイベントの報告待ちを行います。

 EXEC SQL
   EVENT INIT ORDER_WAIT EMPDB ('new_order');
 EXEC SQL
   EVENT WAIT ORDER_WAIT;



** 参照 [#e465d34a]

　[[EVENT INIT>#event_init]]

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