名前

buffer()−tmtype_sw_t における要素の意味

形式

int     /* 新しいデータ・バッファの初期化 */
_tminitbuf(char *ptr, long len)
int    /* 再割り当てされたデータ・バッファ */
_tmreinitbuf(char *ptr, long len)
int    /* 解放するデータ・バッファの初期化解除 */
_tmuninitbuf(char *ptr, long len)
long   /* 送信前のバッファの処理 */
_tmpresend(char *ptr, long dlen, long mdlen)
void   /* 送信後のバッファの処理 */
_tmpostsend(char *ptr, long dlen, long mdlen)
long   /* 受信後のバッファの処理 */
_tmpostrecv(char *ptr, long dlen, long mdlen)
long   /* 伝送形式とバッファの間の符号化/復号化 */
_tmencdec(int op, char *encobj, long elen, char *obj, long olen)
int    /* データに基づきルーティングのサーバ・グループを決定 */
_tmroute(char *routing_name, char *service, char *data, long ¥  len, char *group)
int    /* バッファのデータのブール式を評価 */
_tmfilter(char *ptr, long dlen, char *expr, long exprlen)
int    /* 形式文字列に基づくバッファのデータの抽出 */
_tmformat(char *ptr, long dlen, char *fmt, char *result, long ¥  maxresult) 
long   /* 送信前、おそらくコピー生成前のバッファの処理 */
_tmpresend2(char *iptr, long ilen, long mdlen, char *optr, long olen, long *flags )
long  /* マルチバイト・コード・セットの符号化の変換 */ 
_tmconvmb(char *ibufp, long ilen, char *enc_name, char *obufp, long olen, long 
    *flags)

機能説明

要素 type は NULL 以外とし、最大 8 文字でなければなりません。また、要素 subtype には NULL、最大 16 文字の文字列、またはワイルドカード文字 “*” を指定できます。type がスイッチ内で一意でない場合、subtype を使用しなければなりません。type と subtype の組み合わせは、スイッチ内で一意に要素を指定するものでなければなりません。

1 つのタイプに対して、複数のサブタイプが存在してもかまいまいせん。すべてのサブタイプを特定のタイプに対して同じように扱う場合には、ワイルドカード文字 &dlq;*“ を使用することができます。ただし、サブタイプを区別する必要がある場合には、関数 tptypes() を使用して、バッファのタイプとサブタイプを弁別できます。ある特定のタイプ内で一定のサブタイプのサブセットを個別に扱う必要があり、残りを同様に扱う場合には、特定の値でまとめるサブタイプはそのサブタイプをワイルドカードで指定する前にスイッチ内に指定しておく必要があります。このため、まずスイッチ内のタイプとサブタイプの検索が上から下の方向に行われ、ワイルドカードによるサブタイプのエントリは、残りの一致するタイプを受け付けることになります。

要素 dfltsize() は、バッファの割り当てまたは再割り当てを行うときに使用します。tpalloc() と tprealloc() は、dfltsize() およびこれらのルーチンの size パラメータのうち大きい方を使用してバッファの作成または再割り当てを行うことを意味します。固定サイズの C 構造体などの場合、バッファ・サイズはその構造体と同じにするべきです。dfltsize() をこの値に設定すると、呼び出し元はバッファが渡されるルーチンに対してそのバッファの長さを指定する必要はなくなります。dfltsize() は 0 あるいはそれ以下にすることができます。ただし、tpalloc() や tprealloc() を呼び出して、その size パラメータも 0 もしくはそれ以下であると、このルーチンは異常終了します。このため、dfltsize() を 0 以下の値に設定することはお勧めできません。

ルーチンの詳細

以下に指定する関数の名前は、BEA Tuxedo ATMI システム内で使用されるテンプレート名です。新しいルーチンをバッファ・タイプ・スイッチに追加するアプリケーションは、そのアプリケーションあるいはライブラリ・ルーチンが提供する実際の関数に対応する名前を使用しなければなりません。NULL 関数ポインタがバッファ・タイプ・スイッチ・エントリに格納されている場合、BEA Tuxedo ATMI システムは正しい数と引数タイプをとり、デフォルトの値を返すデフォルト関数を呼び出します。

_tminitbuf()

_tminitbuf() は、バッファの割り当て後、tpalloc() の中から呼び出されます。_tminitbuf() は新しいバッファを指すポインタ ptr とそのサイズを渡されるので、適切にバッファを初期化することができます。len は tpalloc() に渡されるより大きな長さであり、かつそのタイプのスイッチ・エントリに dfltsize() で指定されるデフォルト値です。なお、ptr は、tpalloc() と tprealloc() の意味合いから NULL には決してなりません。正常終了すると、ptr が tpalloc() の呼び出し元に返されます。

複数のサブタイプの処理に 1 つのスイッチ・エントリを使用する場合、_tminitbuf() の作成者は tptypes() を使用してそのサブタイプを特定することができます。

バッファを初期化しなおす必要がない場合には、NULL 関数ポインタを使用します。

正常終了の場合、_tminitbuf() は 1 を返します。異常終了の場合には、-1 を返し、これによって tpalloc() も異常終了を示す tperrno を TPESYSTEM に返します。

_tmreinitbuf

_tmreinitbuf() はほとんど _tminitbuf() と同様に働きます。ただし、この関数は再割り当てされたバッファを初期化しなおすときに使用します。このルーチンは、バッファの再割り当ての後、tprealloc() の中から呼び出されます。

バッファを初期化しなおす必要がない場合には、NULL 関数ポインタを使用します。

正常終了の場合、_tmreinitbuf() は 1 を返します。異常終了の場合には、-1 を返し、これにより tprealloc() も異常終了を示す tperrno を TPESYSTEM に返します。

_tmuninitbuf

_tmuninitbuf() は、データ・バッファの解放前に tpfree() から呼び出されます。_tmuninitbuf() には、データ・バッファのアプリケーション部分を指すポインタとそのサイズが渡されるので、これを使用してそのバッファに関連する構造体や状態情報を消去することができます。ptr は、tpfree() のもつ意味合いから決して NULL にはなりません。ただし、_tmuninitbuf() でバッファ自体を解放しないようにしてください。tpfree() 関数は、データ・バッファのすべての FLD_PTR フィールドで自動的に呼び出されます。

バッファを解放する前に何も処理が必要とされない場合には、NULL 関数ポインタを使用してください。

正常終了の場合、_tmuninitbuf() は 1 を返します。異常終了の場合には、-1 が返され、tpfree() はログ・メッセージを出力します。

_tmpresend

_tmpresend() は、tpcall()、tpacall()、tpconnect()、tpsend()、tpbroadcast()、tpnotify()、tpreturn()、あるいは tpforward() でバッファが送られる前に呼び出されます。また、_tmroute() の後、ただし _tmencdec() の前にも呼び出されます。ptr() が NULL でない場合、このルーチンにより、バッファの送信前にバッファに対する前処理を行うことができます。_tmpresend() の最初の引数 ptr は、送信呼び出しに渡されるアプリケーション・データ・バッファです。2 番目の引数 dlen は、送信呼び出しに渡されるデータの長さです。また、3 番目の引数 mdlen は、データがおかれるバッファの実際の長さです。

この関数に関する重要な条件の 1 つは、関数が返るときに、ptr が指すデータが「そのまま」送られるようにすることです。つまり、_tmencdec() が呼び出されるのはバッファが異なるマシンに送られる場合だけであるので、_tmpresend() は戻る際に、ptr が指すバッファのどの要素も、そのバッファに隣接しないデータを指すポインタとならないようにしなければならないのです。

データに対して前処理が必要なく、呼び出し元が指定したデータ量が送信すべきデータ量と同じ場合、NULL 関数ポインタを使用します。デフォルトのルーチンは dlen を返し、バッファに対して何もしません。

_tmpresend2() が NULL 以外の場合、_tmpresend() は呼び出されず、代わりに _tmpresend2() が呼び出されます。

正常終了の場合、_tmpresend() は送信するデータ量を返します。異常終了の場合には、-1 を返し、_tmpresend() の呼び出し元も異常終了を示す tperrno を TPESYSTEM に返します。

_tmpostsend()

_tmpostsend() は、tpcall()、tpbroadcast()、tpnotify()、tpacall()、tpconnect()、または tpsend() でバッファが送信された後呼び出されます。このルーチンにより、バッファの送信後、関数が戻る前にバッファに対して後処理を行うことができます。送信呼び出しに渡されるバッファは戻り時に異なっていてはならないので、_tmpostsend() を呼び出して、_tmpresend() によってなされたバッファへの変更を修復します。この関数の最初の引数 ptr は、_tmpresend() の実行結果として送信されたデータを指すポインタです。2 番目の引数 dlen は、_tmpresend() から返されるデータの長さです。3 番目の引数 mdlen は、データがおかれるバッファの実際の長さです。このルーチンは、ptr が NULL 以外の場合にのみ呼び出されます。

後処理が必要ない場合には、NULL 関数ポインタを指定します。

_tmpostrecv

_tmpostrecv() は、バッファを受信した後、おそらく tpgetrply()、tpcall()、tprecv()、あるいは BEA Tuxedo ATMI システムのサーバ用の関数で復号化された後、アプリケーションに返される前に呼び出されます。ptr が NULL でない場合は、_tmpostrecv() により、バッファが受信された後、アプリケーションに渡される前にそのバッファに対して後処理を行うことができます。最初の引数 ptr は、受信したバッファのデータ部分を指すポインタです。2 番目の引数 dlen は、_tmpostrecv() に入るデータのサイズを指定します。また、3 番目の引数 mdlen は、データがおかれるバッファの実際のサイズです。

_tmpostrecv() が後処理でデータ長を変更した場合は、新しいデータ長を返す必要があります。返される長さは、使用された呼び出しに基づく方法でアプリケーションに渡されます (たとえば、tpcall() は呼び出し元が戻り時にチェックする引数の 1 つにデータ長を設定します)。

後処理が成功するには、バッファの大きさが十分でない可能性があります。容量がさらに必要な場合、_tmpostrecv() は望ましいバッファ・サイズの負の絶対値を返します。次いで呼び出しルーチンはバッファの大きさを変更し、_tmpostrecv() を再度呼び出します。

データに対して後処理が不要で、受け取ったデータ量がアプリケーションに返されるデータ量と同じであれば、NULL 関数ポインタを使用します。デフォルトのルーチンは dlen を返し、バッファに対して何もしません。

正常終了の場合、_tmpostrecv() は、そのバッファが対応する受信呼び出しから渡されるときにアプリケーションが知っているべきデータの長さを返します。異常終了の場合、-1 を返し、_tmpostrecv() の呼び出し元も異常終了を示す tperrno を TPESYSTEM に返します。

_tmencdec

_tmencdec() は、異なるデータ表現を使用するマシン間でネットワークを介してバッファを送受信するときに符号化/復号化を行うために使用します。BEA Tuxedo ATMI システムでは、XDR の使用が推奨されていますが、このルーチンの意味合いに則っていればどのような符号化/復号化方式をとってもかまいません。

この関数は tpcall()、tpacall()、tpbroadcast()、tpnotify()、tpconnect()、tpsend()、tpreturn()、または tpforward() によって呼び出され、呼び出し元のバッファを符号化します。ただし、この関数は異なるマシンにバッファを送るときにのみ呼び出します。これらの呼び出しの中で、_tmencdec() は _tmroute() と _tmpresend() の後で呼び出されます。ここで、_tmencdec() に渡されるバッファには、そのバッファに隣接しないデータを指すポインタが含まれない、という _tmpresend() の説明を思い出してください。

受信側では、tprecv()、tpgetrply()、tpcall() の受信側、およびサーバ用の関数はすべて _tmencdec() を呼び出して、異なるマシンからバッファを受け取った後、_tmpostrecv() を呼び出す前にこのバッファを復号化します。

_tmencdec() の最初の引数 op は、この関数がデータの符号化または復号化のいずれを行うかを指定します。op には TMENCODE または TMDECODE のいずれかを指定します。

op に TMENCODE を指定すると、encobj は BEA Tuxedo ATMI システムによって割り当てられたバッファを指します (このバッファにデータの符号化版が複写されます)。非符号化データは obj におかれます。つまり、op が TMENCODE であると、_tmencdec() は obj をその符号化形式に変換し、結果を encobj に入れます。encobj が指すバッファのサイズは elen によって指定され、obj によって示されるバッファの長さ (olen) の少なくとも 4 倍です。olen は、_tmpresend によって返される長さです。_tmencdec() は、符号化されたデータの長さを encobj で返します (つまり、実際に送信するデータ量)。_tmencdec() は、この関数に渡されるバッファのいずれも解放しないものとします。

op に TMDECODE を指定すると、encobj は BEA Tuxedo ATMI システムによって割り当てられたバッファを指します (このバッファにデータの符号化版がおかれます)。バッファの長さは elen です。obj は、encobj が指すバッファ (ここに復号化されたデータが複写されます) と少なくとも同じサイズを持つバッファのポインタです。obj の長さは、olen です。obj はアプリケーションによって最終的に返されるバッファであるため、BEA Tuxedo ATMI システムは _tmencdec() を呼び出す前に、復号化データを収めるのに十分な大きさになるようこのバッファのサイズを大きくすることができます。_tmencdec() は、復号化データのサイズを obj に返します。_tmencdec() が戻ると、_tmpostrecv() がその最初の引数として obj、2 番目の引数として _tmencdec() の戻り値、そして 3 番目の引数として olen をとって呼び出されます。_tmencdec() は、この関数に渡されるバッファのいずれも解放しないものとします。

_tmencdec() は、NULL 以外のデータを符号化あるいは復号化する必要がある場合にのみ呼び出されます。

異なるマシンがネットワーク上に存在する場合でもデータに符号化あるいは復号化を行う必要がない場合には、NULL 関数ポインタを使用します。このルーチンは olen (op は TMENCODE と同じ) あるいは elen (op は TMDECODE と同じ) のいずれかを返します。

正常終了の場合、_tmencdec() は、上述のように負でないバッファ長を返します。異常終了の場合、-1 を返し、_tmencdec() の呼び出し元も異常終了を示す tperrno を TPESYSTEM に返します。

_tmroute

メッセージは、デフォルトの設定では、要求されたサービスを提供する任意のサーバ・グループにルーティングされます。UBBCONFIG ファイルに記述する各サービス・エントリでは、ROUTING パラメータを使用して該当サービスのルーティング基準の論理名を指定することができます。複数のサービスが同じルーティング基準を共有することができます。あるサービスがルーティング基準名を指定されている場合、_tmroute() を使用して、メッセージ中のデータに基づいてそのメッセージが送信されるサーバ・グループを判別します。データとサーバ・グループのこの対応付け方法を、「データ依存型ルーティング」と呼んでいます。_tmroute() の呼び出しは、バッファの送信前 (そして、_tmpresend() と _tmencdec() が呼び出される前) に tpcall()、tpacall()、tpconnect()、および tpforward() で行います。

routing_name は、ルーティング基準の論理名 (UBBCONFIG ファイルに指定されている) であり、データ依存ルーティングを必要とするサービスと関連付けられています。service は、要求の対象となるサービスの名前です。パラメータ data は、要求で送出されるデータを指し、len はそのデータの長さです。ここで説明している他のルーチンと異なり、_tmroute() は ptr が NULL の場合でも呼び出されます。group パラメータは、要求の送り先になるグループの名前を返すときに使用します。このグループ名は、UBBCONFIG ファイルに記述されているグループ名の 1 つ (および、そのグループが選択されたときにアクティブであったグループ名) と一致していなければなりません。要求を指定サービスを提供する任意のサーバに送ることができる場合、group を NULL 文字列に設定し、この関数が 1 を返すようにしてください。

データ依存ルーティングが該当バッファ・タイプに必要とされない場合には、NULL 関数ポインタを使用してください。このルーチンは group を NULL 文字列に設定し、1 を返します。

正常終了の場合、_tmroute() は 1 を返します。異常終了の場合、-1 を返し、_tmroute() の呼び出し元も異常終了を返します。これにより、tperrno が TPESYSTEM にセットされます。サーバあるいはサービスが利用できないために _tmroute() が異常終了した場合は、tperrno は TPENOENT にセットされます。

group が無効なサーバ・グループの名前に設定されると、_tmroute() を呼び出す関数はエラーを返し、tperrno を TPESYSTEM に設定します。

_tmfilter()

_tmfilter() は、tppost() によってポストされたバッファの内容を分析するためにイベント・ブローカ・サーバによって呼び出されます。サブスクライバ (tpsubscribe()) が提供した式がバッファの内容を基に評価されます。式が真の場合、_tmfilter() は 1 を返し、イベント・ブローカはサブスクライバへの通知処理を実行します。_tmfilter() が 0 を返した場合は、イベント・ブローカはこのポストをサブスクリプションの「一致」とみなしません。

exprlen が -1 の場合、expr は NULL で終わる文字列とみなされます。それ以外の場合、expr は exprlen バイトのバイナリ・データとみなされます。exprlen が 0 の場合は、式がないことを示します。

フィルタリングがこのバッファ・タイプに適用しない場合は、NULL 関数ポインタを指定します。デフォルトのルーチンは、式がないか、expr が空の NULL で終わる文字列の場合は 1 を返します。それ以外の場合、デフォルトのルーチンは 0 を返します。

_tmformat()

_tmformat() は、fmt という形式指定に従って、バッファのデータを表示可能な文字列に変換するためにイベント・ブローカ・サーバによって呼び出されます。イベント・ブローカは、userlog または system 通知処理の入力のためにポストされたバッファを文字列に変換します。

出力は、result が指すメモリの位置に文字列として格納されます。result には、終端 NULL 文字を含めて最大 maxresult バイト書き込まれます。result の大きさが十分でない場合は、_tmformat() は出力を切り捨てます。出力文字列は、必ず NULL で終わります。

正常終了の場合、_tmformat() は負でない整数を返します。1 は正常終了、2 は出力文字列が切り捨てられたことを示します。異常終了の場合、-1 を返し、result に空の文字列を格納します。

形式設定がこのバッファ・タイプに適用しない場合は、NULL 関数ポインタを指定します。デフォルトのルーチンが後を引き継ぎ、result に空の文字列を返します。

_tmpresend2

_tmpresend2() は、tpcall()、tpacall()、tpconnect()、tpsend()、tpbroadcast()、tpnotify()、tpreturn()、および tpforward() でバッファが送られる前に呼び出されます。また、_tmroute() の後 (ただし _tmencdec() の前) にも呼び出されます。iptr が NULL 以外の場合、このルーチンにより、バッファの送信前に、バッファに対する前処理を行うことができます。

_tmpresend2() の最初の引数 iptr は、送信呼び出しに渡されるアプリケーション・データ・バッファです。2 番目の引数 ilen は、送信呼び出しに渡されるデータの長さです。3 番目の引数 mdlen は、データがおかれるバッファの実際の長さです。

_tmpresend() とは異なり、_tmpresend2() は必要な処理がすべて終了した後で、ポインタ optr を受信し、これを使って iptr のデータを置くバッファを指すポインタを渡します。このポインタを使用するのは、入力バッファを修正する代わりに、_tmpresend2() が修正したデータに新しいバッファを使用する場合です。5 番目の引数 olen は、optr バッファのサイズです。6 番目の引数 flags は、処理されるバッファが親バッファ (送信先バッファ) かどうかを _tmpresend2() に通知します。_tmpresend2() は flags 引数を返して、処理結果を示します。

optr バッファの大きさが不十分で、後処理ができない場合がります。容量がさらに必要な場合、_tmpresend2() は必要なバッファ・サイズの負の絶対値を返します。optr バッファの olen バイトはすべて維持されます。次に呼び出しルーチンがバッファの大きさを変更し、_tmpresend2() を再度呼び出します。

データに対して後処理が不要で、受け取ったデータ量がアプリケーションに返されるデータ量と同じであれば、NULL 関数ポインタを使用します。デフォルトのルーチンは ilen を返し、バッファに対して何もしません。

以下は、_tmpresend2() に入力可能なフラグです。

flags で返されるフラグは、_tmpresend2() の結果を示します。可能な値は次のとおりです。

TMUSEOPTR が返された場合、メッセージ伝送後の処理が _tmpresend() の処理とは異なります。つまり、iptr バッファは変更されず _tmpostsend() は呼び出されません。TMUSEIPTR が返された場合、_tmpostsend() で呼び出されるように _tmpresend() が呼び出されます。optr バッファの割り当てと、解放またはキャッシュは、呼び出し元が行います。

型付きバッファにこの方法を用いるのは、次のような理由によります。

_tmpresend2() 関数は、関数が返るときに、バッファ内の送信データをそのまま送信できるようにします。_tmencdec() は類似しないマシンにバッファが送信される場合にだけ呼び出されるため、_tmpresend2() は、すべてのデータが送信されるバッファ内に隣接して保存されるようにします。

データに対する前処理が不要で、呼び出し元が指定したデータ量が送信すべきデータ量と同じ場合、バッファ・タイプ・スイッチの _tmpresend2() に NULL の関数ポインタを指定します。_tmpresend2() が NULL の場合、デフォルト設定によって _tmpresend() が呼び出されます。

正常終了時には、_tmpresend2() は送信するデータ量を返します。より大きなバッファが必要な場合は、必要なバッファ・サイズの負の絶対値を返します。異常終了時には -1 を返し、これによって _tmpresend2() の呼び出し元も異常終了を返して tperrno を TPESYSTEM に設定します。

_tmconvmb

_tmconvmb() は、tmpostrecv() がマルチバイト・データをソースの符号化からターゲットの符号化に変換した後に呼び出されます。_tmconvmb() の最初の引数 ibufp は、変換するバイトのストリーム (マルチバイト・データ) を指すポインタです。2 番目の引数 ilen は、ibufp 内のバイト数です。3 番目の引数 enc_name は、処理で使用するいずれかの符号化名です。MBSTRING バッファの場合、この引数はターゲットの符号化名になります。FML32 バッファの場合、この引数はソースの符号化名になります。

_tmconvmb() は、必要なコード・セットの符号化の変換がすべて終了した後で、ポインタ obufp を受信し、これを使って ibufp のデータを置くバッファを指すポインタを渡します。このポインタを使用するのは、入力ポインタを修正する代わりに、_tmconvmb() が変換したデータに新しいバッファを使用する場合です。5 番目の引数 olen は、obufp バッファのサイズです。_tmconvmb() は flags 引数を返して、処理結果を示します。

obufp バッファのサイズが不十分で、後処理ができない場合があります。容量がさらに必要な場合、_tmconvmb() は必要なバッファ・サイズの負の絶対値を返します。ibufp バッファの ilen バイトはすべて維持されます。次に呼び出しルーチンがバッファの大きさを変更し、_tmconvmb() を再度呼び出します。

データのコード・セットの符号化変換が必要ない場合、送信側のプロセスの符号化名と受信側のプロセスの符号化名が同じ場合は、NULL 関数ポインタを指定します。デフォルトのルーチンは ilen を返し、バッファに対して変換を行いません。コード・セットの符号化の変換方法が不明の場合、この関数は -1 を返します。

flags で返される値は、_tmconvmb() の結果を示します。可能な値は次のとおりです。

正常終了時には、_tmconvmb() は、コード・セットの符号化の変換が行われたデータ・バッファの大きさを返します。より大きなバッファが必要な場合は、必要なバッファ・サイズの負の絶対値を返します。異常終了時には -1 を返し、これによって _tmconvmb() の呼び出し元も異常終了を返して tperrno を TPESYSTEM に設定します。

関連項目