名前

TPSUBSCRIBE()−イベントのサブスクライブ

形式

01 TPEVTDEF-REC.
 COPY TPEVTDEF. 
 
01 TPQUEDEF-REC.
 COPY TPQUEDEF. 
 
01 TPSTATUS-REC.
 COPY TPSTATUS.
 
CALL "TPSUBSCRIBE" USING TPEVTDEF-REC TPQUEDEF-REC TPSTATUS-REC.

機能説明

呼び出し元は、TPEVTDEF-REC の EVENT-EXPR で指定されたイベントまたはイベント・セットをサブスクライブする際に TPSUBSCRIBE() を使用します。サブスクリプションは BEA Tuxedo のイベント・ブローカ、TMUSREVT() によって管理され、イベントが TPPOST() を介して通知されるときサブスクライバに知らせるために使用されます。それぞれのサブスクリプションには、通知メソッドを指定します。通知メソッドは、クライアント通知、サービス呼び出し、または安定記憶域内のキューへのメッセージ登録の 3 つの内いずれかの形式をとります。通知方法は、サブスクライバのプロセス・タイプおよび TPEVTDEF-REC の TPEV-METHOD-FLAG によって決定されます。

サブスクライブするイベントまたはイベント・セットの名前は、正規表現、すなわち TPEVTDEF-REC の EVENT-EXPR によって指定されますが、EVENT-EXPR フィールドが SPACES であってはなりません。正規表現は、tpsubscribe(3c) で指定される形式です。たとえば、EVENT-EXPR が "¥e¥e..*" のとき、呼び出し元はシステムが生成したすべてのイベントをサブスクライブし、EVENT-EXPR が "¥e¥e.SysServer.*" であれば、システムが生成したサーバ関連のイベントをサブスクライブします。また、EVENT-EXPR が "[A-Z].*" であれば、呼び出し元はアルファベットの A から Z の文字で始まるすべてのユーザ・イベントをサブスクライブし、EVENT-EXPR が ".*(ERR|err).*" であれば、"ERR" または "err" という文字列を含むすべてのユーザ・イベントをサブスクライブします。たとえば、"account_error" や "ERROR_STATE" というイベントはどちらもその対象となります。

TPEVTDEF-REC の EVENT-FILTER は、論理型フィルタ規則を含む文字列で、イベント・ブローカがイベントを通知する前に、有効であることが評価されなければなりません。ポストするイベントを受け取ると、イベント・ブローカはそのイベントのデータにフィルタ規則 (存在する場合) を適用します。データがフィルタ・ルールのチェックにパスした場合、イベント・ブローカは通知メソッドを呼び出します。データがフィルタ・ルールを通過しない場合は、イベント・ブローカは対応する通知メソッドを呼び出しません。呼び出し元は、異なるフィルタ・ルールを利用して同じイベントを何度でもサブスクライブすることができます。

サブスクライバが BEA Tuxedo ATMI のクライアント・プロセスであり、TPEVTDEF-REC の TPEVNOTIFY が設定されている場合、サブスクライブしたイベントが通知されると、イベント・ブローカはサブスクライバに任意通知型メッセージを送出します。つまり、EVENT-EXPR に対して有効であると評価されるイベント名が通知されると、イベント・ブローカは、EVENT-EXPR に関連するフィルタ規則を使用して、通知されるデータをチェックします。データがフィルタ・ルールによるチェックにパスした場合、あるいはそのイベントに対して適用すべきフィルタ・ルールが存在しない場合は、サブスクライバはイベントとそのデータ、および任意通知型メッセージを受け取ることになります。任意通知型メッセージを受け取るためには、クライアントは任意通知処理ルーチンを (TPSETUNSOL() を利用して) 登録しておく必要があります。BEA Tuxedo ATMI のサーバ・プロセスが TPEVNOTIFY を設定して TPSUBSCRIBE() を呼び出すと、TPSUBSCRIBE() は異常終了し、TPSTATUS-REC の TP-STATUS に [TPEPROTO] が設定されます。

任意通知型メッセージを介してイベント通知を受け取るクライアントは、終了する前に、イベント・ブローカのアクティブなサブスクリプションのリストから、それぞれのサブスクリプションを削除する必要があります (詳細は TPUNSUBSCRIBE() を参照)。クライアントは、TPUNSUBSCRIB() のワイルドカード・ハンドル、-1 を使用することにより、任意通知メソッドに関連するサブスクリプションを含むあらゆる「非永続的」サブスクリプションを削除することができます。プロセス終了後も存続するサブスクリプションおよびそれらに関連する通知メソッドについては、以下の TPEVPERSIST の説明を参照してください。クライアントが非持続型のサブスクリプションを削除せずに終了した場合は、イベント・ブローカはクライアントにアクセスできなくなったことを検出すると、そのクライアントのサブスクリプションを削除します。

TPEVNOTIFY が設定される場合は、TPEVNOTRAN と TPEVNOPERSIST も設定される必要があります。そうでない場合、TPSUBSCRIBE() は異常終了し、TP-STATUS に [TPEINVAL] が設定されます。このことは、任意通知型の通知メソッドを持つクライアントによるサブスクリプションは、トランザクショナルでも、持続型でもあり得ないことを意味します。

サブスクライバ (プロセスのタイプとは無関係) が TPEVTDEF-REC の TPEVSERVICE() を設定すると、イベント通知は TPEVTDEF-REC の NAME-1 で指定された BEA Tuxedo ATMI のサービス・ルーチンに送信されます。つまり、EVENT-EXPR に対して有効であると評価されるイベント名が通知されると、イベント・ブローカは、EVENT-EXPR に関連するフィルタ規則を使用して、通知されるデータをチェックします。データがフィルタ・ルールによるチェックにパスした場合、あるいはそのイベントに適用すべきフィルタ・ルールが存在しない場合は、サービス要求はそのイベントに付随するデータとともに NAME-1 に渡されます。NAME-1 には BEA Tuxedo ATMI の有効なあらゆるサービス名をセットすることができ、また、サブスクリプションが行われた時点でアクティブであってもアクティブでなくてもかまいません。イベント・ブローカによって呼び出されたサービス・ルーチンは、応答データなしで戻ります。すなわち、これらのサービス・ルーチンは、TPRETURN() を呼び出す際には TPTYPE-REC の REC-TYPE を SPACES にセットする必要があります。TPRETURN() に渡されるデータは、すべて切り捨てられます。

サブスクライバ (プロセスのタイプは無関係) が TPEVTDEF-REC の TPEVQUEUE() を設定すると、イベント通知は TPEVTDEF-REC の NAME-1 で指定されたキュー・スペースの、TPEVTDEF-REC の NAME-2 で指定されたキューに登録されます。つまり、EVENT-EXPR に対して有効であると評価されるイベント名が通知されると、イベント・ブローカは、EVENT-EXPR に関連するフィルタ規則を使用して、通知されるデータをチェックします。データがフィルタ規則によるチェックにパスした場合、あるいはそのイベントに適用すべきフィルタ規則が存在しない場合、イベント・ブローカは、イベントとともに通知されるあらゆるデータとメッセージを、NAME-1 で指定されたキュー・スペースの NAME-2 で指定されたキューに登録します。キュー・スペースとキューは、BEA Tuxedo システムで使用できるあらゆるキュー・スペースおよびキューを指定でき、どちらもサブスクリプションの時点で存在していても存在していなくてもかまいません。

TPQUEDEF-REC には、通知されるイベントをイベント・ブローカがキューに登録する際の手順をさらに詳しく指示するためのオプションを含めることができます。呼び出し元で指定すべきオプションがない場合は、TPQUEDEF-REC を LOW-VALUE にセットします。一方、指定すべきオプションがある場合は、TPENQUEUE() の項の「制御パラメータ」のセクションで説明した方法でオプションを指定します (特に TPENQUEUE() の入力データ制御の有効なフラグ設定について説明した箇所を参照のこと)。

デフォルトでは、BEA Tuxedo のイベント・ブローカは、通知先のリソースが使用不可能である場合はサブスクリプションを削除します。たとえば、イベントのサブスクリプションに関連するサービス・ルーチン、またはキュー・スペースとキューにイベント・ブローカがアクセスできない場合などです。TPEVTDEF-REC の TPEVPERSIST は、サブスクライバがこのようなエラーに遭遇したあとも (将来リソースが再度使用可能になった場合に備えて) 引き続きサブスクリプションを維持したい場合にセットします。永続的なサブスクリプションは、TPEVSERVICE() および TPEVQUEUE() の通知メソッドでしか利用できません。TPEVNOTIFY が設定されるときに TPEVPERSIST を使用することはできません。使用した場合、関数は異常終了し、TP-STATUS に [TPEINVAL] が設定されます。TPEVNOPERSIST を設定した場合、サブスクリプションで指定されたクライアント、サービス名、またはキュー・スペースとキュー名にアクセスする際にエラーが発生すると、イベント・ブローカはこのサブスクリプションを削除します。

TPEVPERSIST と TPEVTRAN がともに設定されて、イベント通知時にリソースが使用できなかった場合、イベント・ブローカはポスト元に戻り、トランザクションがアボートされるようにします。すなわち、サブスクリプションが保持されている場合でも、リソースが使用できなければポスト元のトランザクションは異常終了します。

TPSUBSCRIBE() で要求されるサブスクリプションと一致するものがイベント・ブローカのアクティブなサブスクリプションのリストに既に存在する場合、関数は異常終了し、TP-STATUS に [TPEMATCH] が設定されます。サブスクリプションが既存のサブスクリプションと一致すると判断されるには、EVENT-EXPR と EVENT-FILTER の両方が、イベント・ブローカのアクティブなサブスクリプションのリストに既に存在するサブスクリプションのものと一致することが条件です。また、通知メソッドによっては、サブスクリプションの一致を判断する際にこれ以外の基準も使用されます。

TPEVNOTIFY がセットされていると、呼び出し元の CLIENTID (システムが定義したクライアント識別子) もサブスクリプションの一致を検出する際の判断材料に加えられます。つまり、EVENT-EXPR、EVENT-FILTER、および呼び出し元の CLIENTID がイベント・ブローカのリストに既に存在するサブスクリプションのデータと一致する場合、TPSUBSCRIBE() は異常終了します。

TPEVSERVICE() が設定されている場合は、EVENT-EXPR、EVENT-FILTER、および NAME-1 で指定されるサービス名がイベント・ブローカのリストに既に存在するサブスクリプションのそれと一致すると、TPSUBSCRIBE() は異常終了します。

TPEVQUEUE() が設定されている場合は、イベント・ブローカはサブスクリプションの一致を判断する際に、EVENT-EXPR や EVENT-FILTER のほか、キュー・スペース、キュー名、および相関識別子を使用します。相関識別子を利用することにより、同じ送信先の、同じイベント式やフィルタ・ルールに対する複数のサブスクリプションを区別することができます。したがって、呼び出し元が TPEVQUEUE() と TPQNOCOORID() の両方を設定した場合は、EVENT-EXPR、EVENT-FILTER、NAME-1 で指定されるキュー・スペースの名前、および NAME-2 で指定されるキューの名前が、イベント・ブローカのリストに既に存在するサブスクリプション (相関識別子は指定されていない) のデータと一致すると、TPSUBSCRIBE() は異常終了します。さらに、TPQCOORID() が設定されている場合、EVENT-EXPR、EVENT-FILTER、NAME-1、 NAME-2、および TPQUEDEF-REC の CORRID がイベント・ブローカのリストに既に存在するサブスクリプション (同じ相関識別子を持つ) のデータと一致すると、TPSUBSCRIBE() は異常終了します。

次に、TPEVTDEF-REC の設定の一覧を示します。

戻り値

TPSUBSCRIBE() は正常終了時には、TP-STATUS に [TPOK] を設定します。また、TPSUBSCRIBE() は、TPEVTDEF-REC の SUBSCRIPTION-HANDLE にこのサブスクリプションのハンドルを設定します。SUBSCRIPTION-HANDLE は、イベント・ブローカのアクティブなサブスクリプションのリストからこのサブスクリプションを削除するために TPUNSUBSCRIBE() を呼び出す際に利用できます。サブスクライバやその他のプロセスは、いずれも返されたハンドルを利用してこのサブスクリプションを削除することができます。

エラー

次の条件が発生すると、TPSUBSCRIBE() は異常終了し、TP-STATUS に次のいずれかの値を設定します (特に記述した場合を除いては、エラーが呼び出し元のトランザクションに影響を及ぼすことはありません)。

関連項目