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()を使うことで開始します。
Note:tpreturn()は,トランザクションの完了に使われません。したがって,サービス関数内で起こったトランザクションを解決しないままにしてtpreturn()を呼ぶと,エラーになります。
『引数』
サービス関数は,一つの引数で起動します。それは,svcinfoで,サービス情報構造体へのポインタです。この構造体は,次の要素を含みます。
char name[XATMI_SERVICE_NAME_LENGTH]; char *data; long len; long flags; int cd;
nameは,呼び出し側が,サービスを呼び出すときに使うサービスの名称です。サービス関数への入り口でのflagsの設定は,サービス関数が注意したい属性を指します。
flagsには,次に示す値を設定します。
- TPCONV
-
会話のためのコネクション要求が受信されて,会話のための記述子cdが使えます。このフラグが設定されていない場合は,これはリクエスト/レスポンス型のサービスであり,cdは使えません。
- TPTRAN
-
サービス関数は,トランザクションモード内にあります。
- TPNOREPLY
-
呼び出し側は応答を期待しません。このオプションは,TPCONVが設定されている場合は,設定されません。
- TPSENDONLY
-
このサービスは,コネクションをわたってデータを送信だけできるように起動されて,コネクションの他端点のプログラムは,データを受信だけできるようになります。このフラグは,TPRECVONLYとは互いに排他的であって,TPCONVが設定されているときだけ,設定できます。
- TPRECVONLY
-
このサービスは,コネクションをわたってデータを受信だけできるように起動されて,コネクションの他端点のプログラムは,データを送信だけできるようになります。このフラグは,TPSENDONLYとは互いに排他的であって,TPCONVが設定されているときだけ,設定できます。
dataは,要求メッセージのデータ部分へのポインタです。lenは,dataの長さです。dataで指すバッファは,tpalloc()で事前にコミュニケーションリソースマネジャ内で割り当てられています。このバッファのサイズは,tprealloc()で大きくできます。ただし,ユーザで解放できません。サービスが終了したら,このバッファはtpreturn()に渡すことをお勧めします。これらのルーチンに異なるバッファが渡された場合は,そのバッファはtpreturn()によって解放されます。
Note:例えtpreturn()に渡されなくても,dataで指されるバッファは次のサービスリクエストに上書きされることに注意してください。サービス要求に付随するデータがなければ,dataはNULLです。この場合は,lenは0です。
TPCONVがflagsに設定されたとき,cdはコネクションの記述子です。これは,会話を開始したプログラムと通信するためにtpsend(),tprecv()と一緒に使えます。
リターン値
サービス関数は,呼び出し側には値をリターンしないで,コミュニケーションリソースマネジャが割り当てます。そのため,void型の宣言となっています。ただし,サービス関数は,tpreturn()で終了することを期待されます。サービス関数がtpreturn()を使わないで終了した場合(つまり,C言語のreturn()を使うか,または関数が終わったら),サーバはサービス要求者にサービスエラーをリターンします。すべてのサブオーディネータへのオープンコネクションはすぐに切断されて,未解決の非同期応答は捨てられます。サーバがトランザクションモードで失敗した場合は,トランザクションはrollback_only状態になります。
Note:tpreturn()がサービス関数の外で使われる場合(例えば,サービスでないルーチンから),何の効果もなくリターンします。
エラー
tpreturn()は,サービス関数を終了させるので,引数をハンドリングしているときか,処理中のときに起こったエラーは,関数の呼び出し側に通知できません。このようなエラーは,tpcall()かtpgetrply()でサービスの結果を受信するプログラムではTPESVCERRがtperrnoに設定する要因となります。tpsend()やtprecv()を使っているプログラムでは,イベントであるTPEV_SVCERRとなります。
関連項目
tpalloc(),tpcall(),tpconnect(),tpgetrply(),tprecv(),tpreturn(),tpsend()
『OpenTP1で使う場合の注意事項』
-
『OpenTP1のUAP(サービス関数)の場合には,tpreturn()の直後に,必ずreturnを記述してください。これは,OpenTP1の実行プロセスに制限があるためです。また,tpreturn()を呼び出したら,すぐにreturnを実行してください。tpreturn()とreturnの間で処理はしないでください。トランザクションの処理の範囲でtpreturn()を呼び出してからreturnを実行する前に資源を更新すると,その更新処理もトランザクションに含まれてしまいます。』
-
『OSI TP通信をするXATMIのエラーは,従来のTCP/IPとエラー動作が異なる場合があります。』