tpforward(3c)

名前

tpforward()-サービス要求を他のサービス・ルーチンに転送するルーチン

形式

#include <atmi.h>
void tpforward(char *svc, char *data, long len, long flags)

機能説明

tpforward() を使用すると、サービス・ルーチンはクライアントの要求を別のサービス・ルーチンに転送して処理させることができます。tpforward() の働きは、サービス・ルーチンの中で最後に呼び出されるという点で tpreturn() と似ています。tpreturn() のように、tpforward() は、BEA Tuxedo ATMI システムのディスパッチャに制御を正常に返すことを保証するために、ディスパッチされるサービス・ルーチン内から呼び出されます。tpforward() は会話型サービス内から呼び出すことはできません。

この関数は、data が指すデータを使用して svc によって指定されるサービスに要求を転送します。サービス名の先頭に "." を付けてはいけません。要求を転送するサービス・ルーチンは応答を受け取りません。要求の転送が終わると、サービス・ルーチンは、通信マネージャ・ディスパッチャに戻り、他の作業を行える状態になります。なお、転送された要求からの応答は期待しないため、この要求は、その要求を転送するサービスと同じ実行形式内の任意のサービス・ルーチンに、エラーなして転送することができます。

サービス・ルーチンがトランザクション・モードであると、この関数はトランザクションの呼び出し元の部分を、そのトランザクションのイニシエータが tpcommit() または tpabort() のいずれかを出したときに完了できるような状態にします。トランザクションがサービス・ルーチンの実行中に tpbegin() により明示的に開始された場合、このトランザクションを tpcommit() または tpabort() で終了させてから、tpforward() を呼び出さなければなりません。このため、転送チェインに関与するすべてのサービスは、トランザクション・モードで起動するか、あるいはどれもトランザクション・モードでは起動しないようにします。

転送チェインの最後のサーバは、tpreturn() を使用して要求の発信元に応答を返します。要約して言えば、tpforward() は待機しているリクエスタに応答を返す役割を別のサーバに転送するわけです。

tpforward() は、サービス・ルーチンが出したサービス要求から期待されるすべての応答を受け取った後、呼び出すようにします。受信されていない未終了の応答は、受信後、通信マネージャ・ディスパッチャによって自動的に取り除かれます。さらに、以後、これらの応答の記述子は無効になり、要求は svc に転送されません。

data は送信される応答のデータ部を指すポインタです。data が NULL でない場合、tpalloc() を呼び出して事前に確保したバッファを指すポインタでなければなりません。このバッファが、サービス・ルーチン起動時にサービス・ルーチンに渡されたバッファと同じバッファである場合、そのバッファの配置は、BEA Tuxedo ATMI システム・ディスパッチャに一任されます。したがって、サービス・ルーチンをコーディングする人は、バッファが解放されているかどうかを気にする必要はありません。実際、ユーザがこのバッファを解放しようとしてもできません。しかし、tpforward() に渡されるバッファが、サービスが起動したものに等しいものでない場合は、tpforward() はそのバッファを解放します。len には送信するデータ・バッファの大きさを指定します。data が長さの指定を必要としないバッファを指すポインタである場合 (FML フィールド化バッファなど)、len は 0 でもかまいません。data が NULL の場合、len は無視され、長さ 0 のデータの要求が送信されます。

引数 flags は使用されません。この引数は将来の用途のために予約されており、0 (ゼロ) に設定されます。

戻り値

エラー

関数に渡すパラメータの処理あるいはその関数のどちらかで何らかのエラーが発生した場合は、応答が送信されない限り、「失敗」メッセージが要求を起動した側に返されます。未終了の応答または従属する接続、あるいは「アボートのみ」とマーク付けされている呼び出し元のトランザクションがある場合、異常終了メッセージを生成する異常終了と見なされます。

ubbconfig ファイル中の SVCTIMEOUT か、TM_MIB 中の TA_SVCTIMEOUT が 0 でない場合にサービスのタイムアウトが発生すると、TPEV_SVCERR が返されます。この場合、tperrordetail(3) は TPED_SVCTIMEOUT を返します。

要求者は、エラーを示す TPESVCERR エラーによって、異常終了メッセージを検出します。このようなエラーが発生した場合、呼び出し元のデータは、送信されません。また、このエラーが発生すると、呼び出し元の現在のトランザクションは、「アボートのみ」とマーク付けされます。

サービス・ルーチンの処理中あるいは要求の転送中にトランザクション・タイムアウトになると、tpcall() または tpgetrply() で応答を待つ要求元は TPETIME エラーを受け取ります。また、待ち状態にある要求側は、どのようなデータも受信しません。サービス・ルーチンは、tpreturn() あるいは tpforward() のどちらかを使用して終了します。ただし、会話型サービス・ルーチンは tpreturn() を使用しなければならず、tpforward() は使用できません。

サービス・ルーチンが、tpreturn() または tpforward() のどちらも使用しないで戻る場合、(すなわち、サービス・ルーチンが C 言語の return 文を使用するかあるいは単に「関数の終わりで終了する」場合)、あるいは tpforward() が従来のサーバから呼び出される場合、サーバは、ログ・ファイルに警告メッセージを出力し、サービス・エラーを要求の起動側に返します。従属側へのすべてのオープン接続は、ただちに切断され、未終了の非同期応答は「処理済み」のマークが付けられます。障害が発生したときにサーバがトランザクション・モードの場合、そのトランザクションは「アボートのみ」とマークされます。tpreturn() または tpforward() がサービス・ルーチンの範囲外で (たとえば、クライアントで、あるいは、tpsvrinit() または tpsvrdone() で) 使用された場合は、これらのルーチンは、一切影響を及ぼすことなく単に終了します。

関連項目