tpservice

名称

サービス関数のテンプレート

ページの先頭へ

形式

#include <xatmi.h>
void  tpservice(TPSVCINFO  *svcinfo)

#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()がサービス関数の外で使われる場合（例えば，サービスでないルーチンから），何の効果もなくリターンします。

ページの先頭へ

関連項目

tpalloc()，tpcall()，tpconnect()，tpgetrply()，tprecv()，tpreturn()，tpsend()

ページの先頭へ

『OpenTP1で使う場合の注意事項』

1. 『OpenTP1のUAP（サービス関数）の場合には，tpreturn()の直後に，必ずreturnを記述してください。これは，OpenTP1の実行プロセスに制限があるためです。また，tpreturn()を呼び出したら，すぐにreturnを実行してください。tpreturn()とreturnの間で処理はしないでください。トランザクションの処理の範囲でtpreturn()を呼び出してからreturnを実行する前に資源を更新すると，その更新処理もトランザクションに含まれてしまいます。』

2. 『OSI TP通信をするXATMIのエラーは，従来のTCP/IPとエラー動作が異なる場合があります。』

ページの先頭へ