tpservice(3c)

名前

tpservice()-サービス・ルーチンのテンプレート

形式

#include <atmi.h>                   /* C インターフェイス */  
void tpservice(TPSVCINFO *svcinfo)  /* C++ インターフェイス - 
                                     * C リンケージが必要 */
extern "C" void tpservice(TPSVCINFO *svcinfo) 

機能説明

tpservice() は、サービス・ルーチン作成時のテンプレートです。このテンプレートは、ルーチン tpcall()、tpacall()、または tpforward() を介して要求を受け取るサービス、およびルーチン tpconnect()、tpsend()、または tprecv() を介して通信を行うサービスに使用できます。

tpcall() または tpacall() を介して行われる要求を処理するサービス・ルーチンは、１ つだけ着信メッセージを受け取り (svcinfo の data 要素内に)、１ つだけ応答を送る (tpreturn() を使用してサービス・ルーチンを終了するとき) ことができます。

一方、会話型サービスは、１ つの受信メッセージとオープン接続記述子を持つ接続要求により呼び出されます。会話型サービス・ルーチンが呼び出されると、接続元プログラムあるいは会話型サービスはアプリケーション側で定義されたようにデータの送信および受信を行うことができます。この接続は半二重方式で確立されます。つまり、一方は他方から明示的に制御権を渡されるまで、会話権を得られません (データを送信できません)。

トランザクションとの関連で言えば、サービス・ルーチンはトランザクション・モードで呼び出されると、１つのトランザクションにしか参加できません。サービス・ルーチン作成者側から見るかぎり、トランザクションはサービス・ルーチンから返った時点で終了します。サービス・ルーチンは、トランザクション・モードで呼び出されなかった場合、tpbegin()、tpcommit() および tpabort() を使用して必要な回数だけトランザクションを起動できます。ただし、トランザクションの終了には tpreturn() を使用しません。したがって、サービス・ルーチン内から起動された未終了のトランザクションについて、tpreturn() を呼び出すと、エラーになります。

サービス・ルーチンは、サービス情報を収めた構造体を指すポインタ svcinfo を引数として呼び出されます。この構造体には、次のメンバが含まれます。

char        name[32];
char        *data;
long        len;  
long        flags;  
int         cd;  
long        appkey;  
CLIENTID    cltid;

name には、要求元がサービスの呼び出しに使用したサービス名を指定します。

サービス・ルーチンに入った時点で設定される flags は、サービス・ルーチンが注目する必要のある属性を示します。以下に、flags に指定できる値を示します。

data は要求メッセージのデータ部を指し、len はデータの長さです。datadata によって指されたバッファは、通信マネージャで tpalloc() により割り当てられたものです。このバッファのサイズは、ユーザが tprealloc() を使用して大きくすることができます。ただし、これをユーザが解放することはできません。このバッファは、サービス終了時に tpreturn() または tpforward() に渡すようにしてください。異なるバッファをこれらのルーチンに渡すと、そのバッファはそれらによって解放されてしまいます。なお、data によって指されるバッファは、このバッファが tpreturn() または tpforward() に渡されない場合でも、次に出されたサービス要求によって変更されてしまいます。data は、要求とともにデータが渡されなかった場合には NULL になります。この場合、len は 0 になります。

TPCONV を flags に設定する場合、cd に接続記述子を指定しますが、これはこの会話を開始したプログラムとのコミュニケーションを行うために tpsend() および tprecv() とともに使用します。

appkey は、アプリケーション側で定義した認証サービスが要求クライアントに割り当てるアプリケーション・キーに設定します。このキー値は、このサービス・ルーチンのこの呼び出し中になされたあらゆるサービス要求とともに渡されます。アプリケーション認証サービスを通らないクライアントを起動する場合には、appkey の値は -1 になります。

cltid は、このサービス要求に対応する元のクライアントを示す一意のクライアント識別子です。この構造体は atmi.h にのみ、アプリケーションが利用できるよう定義されているので、必要によりアプリケーション・サーバ間でクライアント識別子をやりとりすることができます。このため、以下に定義されているフィールドの意味は明記されていません。アプリケーション側では CLIENTID 構造体の内容を操作しないようにしてください。内容を操作してしまうと、この構造体自体が無効になってしまいます。CLIENTID 構造体には、次のようなメンバが含まれます。

long        clientdata[4];

C++ では、サービス関数に C リンケージが必要なことに注意してください。リンケージは、関数を 'extern "C"' と宣言することで行えます。

戻り値

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

エラー

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

関連項目