tpservice
名称
サービス関数のテンプレート
形式
ANSI C ,C++ の形式
#include <xatmi.h>
void tpservice(TPSVCINFO *svcinfo)
K&R版 Cの形式
#include <xatmi.h>
void tpservice(svcinfo)
TPSVCINFO *svcinfo;
機能
関数tpservice()は,サービス関数を記述するためのテンプレートです。このテンプレートは,tpconnect(),tpsend(),tprecv()関数を経由して,会話するサービスはもちろん,tpcall()やtpacall()関数を経由してサービス要求を受信するサービスにも使われます。
tpcall()やtpacall()を経由して実行されたサービス要求を処理するサービス関数は,多くても一つの入力されたメッセージ(svcinfoのdata要素)を受信して,一つの応答(tpreturn()でサービス関数を出たこと)を送信します。
他方では,会話型サービスは,オープンコネクションを参照する手段のほかに,多くても一つの入力メッセージを伴った,コネクション要求で呼び出されます。会話型サービス関数が起動されると,コネクション要求を出したプログラムも,会話型サービスも,アプリケーションで定義されたデータを送信したり受信したりできるようになります。コネクションは半二重となっています。つまり,プログラムは,コネクションの制御権を明示的に放棄するまで,会話を制御(つまり,データを送信する)できます。
トランザクションに関しては,トランザクションモードで起動した場合,サービス関数は,少なくとも一つのトランザクションに参加できます。サービス関数の作成者は,トランザクションは,サービス関数から戻ることで終了すると考えてください。サービス関数をトランザクションモードで起動しない場合,サービス関数は,必要なだけのトランザクションをtx_begin(),tx_commit(),tx_rollback()を使うことで開始します。
『引数』
サービス関数は,一つの引数で起動します。それは,svcinfoで,サービス情報構造体へのポインタです。この構造体は,次の要素を含みます。
char name[XATMI_SERVICE_NAME_LENGTH];
char *data;
long len;
long flags;
int cd;
nameは,呼び出し側が,サービスを呼び出すときに使うサービスの名称です。サービス関数への入り口でのflagsの設定は,サービス関数が注意したい属性を指します。
flagsには,次に示す値を設定します。
dataは,要求メッセージのデータ部分へのポインタです。lenは,dataの長さです。dataで指すバッファは,tpalloc()で事前にコミュニケーションリソースマネジャ内で割り当てられています。このバッファのサイズは,tprealloc()で大きくできます。ただし,ユーザで解放できません。サービスが終了したら,このバッファはtpreturn()に渡すことをお勧めします。これらのルーチンに異なるバッファが渡された場合は,そのバッファはtpreturn()によって解放されます。
TPCONVがflagsに設定されたとき,cdはコネクションの記述子です。これは,会話を開始したプログラムと通信するためにtpsend(),tprecv()と一緒に使えます。
リターン値
サービス関数は,呼び出し側には値をリターンしないで,コミュニケーションリソースマネジャが割り当てます。そのため,void型の宣言となっています。ただし,サービス関数は,tpreturn()で終了することを期待されます。サービス関数がtpreturn()を使わないで終了した場合(つまり,C言語のreturn()を使うか,または関数が終わったら),サーバはサービス要求者にサービスエラーをリターンします。すべてのサブオーディネータへのオープンコネクションはすぐに切断されて,未解決の非同期応答は捨てられます。サーバがトランザクションモードで失敗した場合は,トランザクションはrollback_only状態になります。
エラー
tpreturn()は,サービス関数を終了させるので,引数をハンドリングしているときか,処理中のときに起こったエラーは,関数の呼び出し側に通知できません。このようなエラーは,tpcall()かtpgetrply()でサービスの結果を受信するプログラムではTPESVCERRがtperrnoに設定する要因となります。tpsend()やtprecv()を使っているプログラムでは,イベントであるTPEV_SVCERRとなります。
関連項目
tpalloc(),tpcall(),tpconnect(),tpgetrply(),tprecv(),tpreturn(),tpsend()
『OpenTP1で使う場合の注意事項』