名前

tpreturn()−BEA Tuxedo ATMI システム・サービス・ルーチンからの復帰

形式

void tpreturn(int rval, long rcode, char *data, long len, long ¥
flags)

機能説明

tpreturn() は、サービス・ルーチンが完了したことを示します。tpreturn() の働きは、C 言語における return 文と似ています (つまり、tpreturn() が呼び出されると、サービス・ルーチンは BEA Tuxedo ATMI システムのディスパッチャに制御を返します)。制御を BEA Tuxedo ATMI システムのディスパッチャに確実に正しく戻すために、ディスパッチされたサービス・ルーチン内から tpreturn() を呼ぶようにしてください。

tpreturn() はサービスの応答メッセージを送るときに使用します。応答を受け取るプログラムが tpcall()、tpgetrply() または tprecv() で待機している場合、tpreturn() の呼び出しが成功した時点で、受信側のバッファに応答が入ります。

会話型サービスの場合、tpreturn() は接続自体も切断します。したがって、サービス・ルーチンは、tpdiscon() を直接呼び出すことができません。正常な結果を保証するためには、会話型サービスに接続しているプログラムは tpdiscon() を呼び出してはなりません。そのようなプログラムは、会話型サービスが完了したという通知を待たなければなりません (たとえば、そのプログラムは、tpreturn() によって送信される TPEV_SVCSUCC または TPEV_SVCFAIL などのイベントのちの 1 つを待つ必要があります)。

また、サービス・ルーチンがトランザクション・モードにあった場合には、tpreturn() はトランザクションのサービス部分を、そのトランザクションの完了時点でコミットあるいはアボートできる状態にします。サービスは同じトランザクションの一部として複数回呼び出すことができるので、tpcommit() あるいは tpabort() がそのトランザクションのイニシエータによって呼び出されるまでは、完全にコミットあるいはアボートさせる必要は必ずしもありません。

tpreturn() は、該当サービス・ルーチンが出したサービス要求から期待されるすべての応答を受け取った後、呼び出すようにしてください。そうしない場合は、サービスの性質によって決まりますが、TPESVCERR 状態または TPEV_SVCERR イベントのいずれかが、サービス・ルーチンとの接続を開始したプログラムに返ります。受け取られなかった応答は、受信処理の後、通信マネージャによって自動的に取り除かれます。また、これらの応答に対応する記述子は無効になります。

tpreturn() は、サービスが出したすべての接続をクローズした後、呼び出される必要があります。そうしない場合はサービスの性質によって決まりますが、TPESVCERR または TPEV_SVCERR イベントのいずれかが、サービス・ルーチンとの通信を開始したプログラムに返されます。また、即時切断イベント (つまり、TPEV_DISCONIMM) が、オープンしているすべての接続を通して従属側に送信されます。

会話型サービスは、自分で開始しなかったオープン接続を 1 つだけ備えているため、通信マネージャは、送信すべき記述子データ (およびイベント) を認識しています。このため、記述子は、tpreturn() に渡されません。

次に、tpreturn() の引数について説明します。rval は次のいずれかに設定できます。

rval がこれら 3 つの値のいずれかに設定されていない場合、デフォルトの値として TPFAIL が使用されます。

アプリケーションが定義した戻りコード rcode をサービスの応答を受け取るプログラムに送ることもできます。このコードは、応答を正常に送ることができさえすれば (つまり、受信呼び出しが正常に行われる、あるいは TPESVCFAIL が返されれば)、rval の設定には関係なく送ることができます。さらに、会話型サービスでは、このコードは、サービス・ルーチンが tpreturn() を発行したときに接続の制御権を持っている場合のみ送信されます。rcode の値は、受信側の変数 tpurcode() に入ります。

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

data が NULL の場合、len は無視されます。この場合、サービスを起動したプログラムが応答を待っている状態にあると、データなしの応答が返されます。応答を待たない状態にあると、tpreturn() は、必要に応じて data を解放し、応答を送信しないで復帰します。

現在、flags は将来の用途のために予約されており、0 に設定します (0 以外の値に設定すると、応答の受信者は TPESVCERR または TPEV_SVCERR イベントを受信します)。

会話型サービスの場合、アプリケーションの戻りコードとデータ部が送られないケースがいくつかあります。

戻り値

サービス・ルーチンは呼び出し元である BEA Tuxedo ATMI システムのディスパッチャに値を返しません。このため、このルーチンは void として宣言されます。しかし、サービス・ルーチンは tpreturn() または tpforward() を使用して終了させるようになっています。会話型サービス・ルーチンの場合、tpreturn() を使用しなければならず、tpforward() を使用することはできません。サービス・ルーチンを tpreturn() または tpforward() のいずれも使用せずに終了させる場合 (すなわち、このルーチンが C 言語の return 文を使用するか、ごく単純に関数の実行に失敗した場合)、あるいは tpforward() が会話型サーバから呼び出された場合、そのサーバはログに警告メッセージを出し、サービス・エラーをサービスの要求元に返します。従属側へのすべてのオープン接続は、ただちに切断され、未終了の非同期応答はドロップされます。障害時にサーバがトランザクション・モードであった場合、このトランザクションには「ロールバックのみ」のマークが付けられます。tpreturn() や tpforward() がサービス・ルーチンの外部から使用される場合 (たとえば、クライアントや tpsvrinit() あるいは tpsvrdone() で)、これらのルーチンは単に終了するだけです。

エラー

tpreturn() はサービス・ルーチンを終了させるので、引数処理またはサービス処理の間に発生したエラーについて、関数の呼び出し元に示すことはできません。このようなエラーが起こると、tpcall() または tpgetrply() を使用してサービスの結果を受信するプログラムのために tperrno が TPESVCERR に設定されます。またイベント TPEV_SVCERR が、tpsend() または tprecv() を使用するプログラムに、会話を通して送信されます。

UBBCONFIG ファイル中の SVCTIMEOUT か、TM_MIB 中の TA_SVCTIMEOUT が 0 でない場合にサービスのタイムアウトが発生すると、TPEV_SVCERR が返されます。

tperrordetail() と tpstrerrordetail() を使用すると、現在のスレッドの中で呼び出された最新の BEA Tuxedo ATMI システムのルーチンが出したエラーに関して、追加的な情報を取得できます。エラーが起きると、tperrordetail() は数値を返しますが、この数値を trstrerrordetail() への引数として利用することで、エラーの詳細に関するテキストを受け取ることができます。

関連項目