名前

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

サービス・ルーチンがトランザクション・モードであると、tpforward() はトランザクションの呼び出し元の部分を、そのトランザクションのイニシエータが 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 が返されます。

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

サービス・ルーチンの処理中あるいは要求の転送中にトランザクション・タイムアウトになると、tpcall() または tpgetrply() で応答を待つ要求元は TPETIME エラーを受け取ります。サービスがトランザクション内部で失敗すると、そのトランザクションはタイムアウトになり、TX_ROLLBACK_ONLY 状態になります。また、そのトランザクションの後続の ATMI 呼び出しは、すべて TPETIME で異常終了します。待ち状態にある要求元は、どのようなデータも受信しません。しかし、サービス・ルーチンは tpreturn() または tpforward() を使用して終了させるようになっています。会話型サービス・ルーチンの場合、tpreturn() を使用しなければならず、tpforward() を使用することはできません。

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

関連項目