名前

tpsubscribe()−イベントをサブスクライブする

形式

#include <atmi.h> 
long tpsubscribe(char *eventexpr, char *filter, TPEVCTL *ctl, long flags)

機能説明

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

サブスクライバが BEA Tuxedo ATMI のクライアント・プロセスで、ctl が NULL の場合は、サブスクライブしているイベントがポストされたときに、イベント・ブローカはサブスクライバに任意通知型メッセージを送ります。この場合、eventexpr に対して評価が成功するイベント名がポストされると、イベント・ブローカは eventexpr に対応したフィルタ・ルールに対してポストされたデータをテストします。データがフィルタ・ルールを通過した場合、またはそのイベントに対する適用すべきフィルタ・ルールが存在しない場合は、サブスクライバはイベントと共にポストされたすべてのデータと共に任意通知型の通知を受け取ります。任意通知型メッセージを受け取るためには、クライアントは任意通知処理ルーチンを (tpsetunsol() を利用して) 登録しておく必要があります。BEA Tuxedo ATMI システムのサーバ・プロセスが、ctl パラメータを NULL にして tpsubscribe() を呼び出した場合は、tpsubscribe() は異常終了して tperrno を TPEPROTO に設定します。

サブスクライバが (プロセス・タイプにかかわらず) イベント通知をサービス・ルーチンまたは安定記憶域内のキューに送りたい場合は、ctl パラメータは有効な TPEVCTL 構造体を指さなければいけません。この構造体には次のエレメントが含まれます。

long    flags;  
char    name1[32];  
char    name2[32];  
TPQCTL  qctl;

次に、ctl—>flags 要素に指定する、イベントをサブスクライブするための制御オプションの有効なビットの一覧を示します。

イベント・ブローカのアクティブなサブスクリプションのリストに、tpsubscribe() が要求するサブスクリプションと一致するものがある場合は、この関数は異常終了して tperrno に TPEMATCH を設定します。サブスクリプションが既存のサブスクリプションと一致するためには、eventexpr と filter の両方が、イベント・ブローカのアクティブなサブスクリプションのリストにすでに存在するサブスクリプションの eventexpr と filter に一致しなければなりません。さらに、通知メソッドによって異なりますが、一致を調べるために他の基準も使用されます。

サブスクライバがBEA Tuxedo ATMI システムのクライアント・プロセスで、(イベントがポストされたときに、呼び出し元が任意通知を受け取るように) ctl に NULL を設定した場合は、システム定義によるそのクライアント識別子 (CLIENTID と呼ばれています) も一致を調べるために使用されます。つまり tpsubscribe() は、eventexpr、filter、および呼び出し元の CLIENTID が、イベント・ブローカにすでに知られているサブスクリプションが持つそれらの値と一致する場合に異常終了します。

呼び出し元が ctl—>flags に TPEVSERVICE を設定した場合は、eventexpr、filter、および ctl—>name1 に設定されたサービス名が、イベント・ブローカにすでに知られているサブスクリプションが持つそれらの値と一致する場合に tpsubscribe() は異常終了します。

安定記憶域内のキュー、キュー・スペース、およびキューの名前へのサブスクリプションの場合は、一致を調べる際に eventexpr および filter に加えて相関識別子が使用されます。相関識別子を利用することにより、同じ送信先の、同じイベント式やフィルタ・ルールに対する複数のサブスクリプションを区別することができます。したがって、呼び出し元が ctl—>flags に TPEVQUEUE を設定し、ctl—>qctl.flags に TPQCOORID が設定されなかった場合、eventexpr、filter、ctl—>name1 に設定されたキュー・スペース名、および ctl—>name2 に設定されたキュー名が、イベント・ブローカにすでに知られている (相関識別子が指定された) サブスクリプションが持つそれらの値と一致すると tpsubscribe() は異常終了します。さらに、ctl—>qctl.flags に TPQCOORID が設定されている場合は、eventexpr、filter、ctl—>name1、ctl—>name2、および ctl—>qctl.corrid が イベント・ブローカに既に知られている (同じ相関識別子が指定された) サブスクリプションのデータと一致すると、tpsubscribe() は異常終了します。

次に tpsubscribe() に指定できる有効な flags の一覧を示します。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT 状態のスレッドは、tpsubscribe() の呼び出しを発行できません。

正規表現

正規表現 (RE: Regular Expressions) は、次に示すいずれかの規則を 1 回以上適用して作成します。

優先順位のレベルは 3 つあります。結合の強さの順に並べると、次のようになります。

上記のとおり、かっこは優先順位が高いことを明示的に示すために使用します。

戻り値

tpsubscribe() は正常終了すると、イベント・ブローカのアクティブなサブスクリプションのリストからこのサブスクリプションを削除するために使用できるハンドルを返します。サブスクライバやその他のプロセスは、いずれも返されたハンドルを利用してこのサブスクリプションを削除することができます。

異常終了すると、tpsubscribe() は -1 を返し、tperrno を設定してエラー条件を示します。

エラー

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

関連項目