tpsubscribe(3c)

名前

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 システムのサーバ・プロセスが、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 Expression) は、次に示すいずれかの規則を 1 回以上適用して作成します。

正規表現

規則	一致対象のテキスト
任意の文字	任意の文字 (以下に示す特殊文字を除く任意の ASCII 文字)。
\ 任意の文字	以下に示す以外の任意の文字。 \\-改行 \\t-タブ \\b-バックスペース \\r-キャリッジ・リターン \\f-フォームフィード
\ 特殊文字	非特殊文字。特殊文字には、ピリオド (.)、*、+、?、|、(、)、[、{、\\、があります。 .-行末文字 (通常は改行文字または NULL 文字) 以外の任意の文字 ^-行頭 $-行末文字
[class]	一連の文字または範囲、あるいはその両方で表すクラス内の任意の文字。範囲は、「character-character」という形式で指定されます。たとえば、文字クラス [a-zA-Z0-9_] は、アルファベット文字またはアンダーライン"_" と一致します。ハイフンをクラスに含めるには、"\\" の後のハイフンをエスケープするか、クラス内の先頭または終わりに指定する必要があります。リテラル "]" の場合は、エスケープするか、またはクラスの先頭に指定します。リテラル "^" がクラスの先頭にある場合は、エスケープする必要があります。
[^ class ]	行末文字を除く、クラスの補集合における ASCII 文字セットに関する文字。
RE RE	正規表現のシーケンス (連結)。
RE | RE	左側の RE または右側の RE (左右の二者択一)。
RE *	RE が 0 回以上発生。
RE +	RE が 1 回以上発生。
RE ?	RE が 0 回または 1 回発生。
RE { n }	RE が n 回発生。n の範囲は 0〜255 です。
RE { m, n }	RE が m〜n の範囲の回数発生。m が指定されない場合は 0 になります。n が指定されない場合は、RE が m 回以上発生することを示します。
( RE )	優先順位またはグループ化を明示的に示します。
( RE ) $ n	テキスト・マッチングの RE は、n 番目のユーザ・バッファにコピーされます。n の範囲は、0〜9 です。 ユーザ・バッファは、マッチング処理の開始までにクリアされ、パターン全体がマッチした場合にのみロードされます。

 

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

戻り値

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

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

エラー

異常終了時には、tpsubscribe() は tperrno() を次のいずれかの値に設定します(特に指定がない限り、障害は、呼び出し元のトランザクションに影響しません)。

関連項目