tpcall
形式
ANSI C,C++の形式
#include <xatmi.h> int tpcall(char *svc,char *idata,long ilen,char **odata, long *olen,long flags)
K&R版 Cの形式
#include <xatmi.h> int tpcall(svc,idata,ilen,odata,olen,flags) char *svc; char *idata; long ilen; char **odata; long *olen; long flags;
機能
関数tpcall()は,サービス要求を送信して,同期的に応答を待ちます。この関数を呼ぶことは,tpacall()を呼び出して,すぐにtpgetrply()を呼び出すのと同じことです。関数tpcall()はsvcで示されたサービスにサービス要求を送信します。サービス要求のデータ部は,idataで指しています。バッファは,事前にtpalloc()で割り当てておきます。引数ilenには,idataをどれだけ送信するかを設定します。
Note:idataが,長さを指定する必要がないバッファ型を指す場合は,ilenは無視されます(0にしてください)。長さが必要なバッファ型をidataが指す場合は,ilenには0を設定しないでください。idataがNULLの場合も,ilenは無視されます。idataのtypeとsubtypeは,svcで認識できるtypeとsubtypeのうちのどれか一つに必ず一致させてください。
odataは応答が読み込まれるバッファへのポインタのアドレスであり,その応答の長さは*olenにリターンされます。*odataは,tpalloc()であらかじめ割り当てたバッファを必ず指すようにしてください。送信と受信に同じバッファを使用する場合は,odataにidataのアドレスを入れておいてください。
応答のバッファのサイズを変更したかどうかの判断は,tpcall()を呼び出す前のバッファの合計サイズと*olenの長さを比較します。*olenの方が長い場合は,バッファは大きくなっています。長くない場合は,バッファのサイズは変わりません。
また,tpcall()が呼び出されたときに,idataと*odataが等しくても,*odataが変更されたときは,idataが指しているアドレスは無効です。
Note:*odataはバッファのサイズを増やす以外の理由でも変わるかも知れません。*olenに0が返ってきたら,応答にはデータ部がなくて,*odataとそれが指すバッファは変更されません。*odataやolenがNULLの場合はエラーになります。
『引数』
『●svc
要求するサービスのサービス名を設定します。』
『●idata
送信バッファへのポインタを設定します。』
『●ilen
送信バッファの長さを設定します。』
『●odata
応答データを格納するバッファへのポインタのアドレスを設定します。』
『●olen
応答バッファの長さを示すlong型へのポインタを示します。』
『●flags』
flagsには,次に示す値を設定します。
- TPNOTRAN
-
呼び出し側がトランザクションモードで,かつこのフラグを設定している場合,起動されたsvcは,呼び出し側のトランザクションの一部にはなりません。呼び出し側がトランザクションモードで,かつsvcがトランザクション処理ができない場合は,このフラグを必ず設定してください。呼び出し側がトランザクションモードであれば,このフラグを設定していても,トランザクションタイムアウトは起こります(トランザクションモードでなければ起こりません)。このフラグで起動されたサービスが失敗しても,呼び出し側のトランザクションには影響しません。
- TPNOCHANGE
-
バッファが*odataで指しているバッファ型と異なる型のデータを受信したとき,このフラグを設定していなければ,*odataのバッファ型は受け取り側がそのバッファ型を認識しているかぎり,受信したデータのバッファ型に変換されます。このフラグを設定した場合は,*odataで指しているバッファ型は変換されません。つまり,受信したバッファのtype,subtype,および*odataで指しているバッファのtypeとsubtypeは必ず一致させてください。
- TPNOBLOCK
-
ブロッキング状態の場合(例えば,送信されたメッセージで内部バッファが満杯),サービス要求は送信されません。
Note:このフラグは,tpcall()の送信時だけ有効となります。この関数は,応答を待っているときはブロックします。TPNOBLOCKが設定されていないで,ブロッキング状態のときは,呼び出し側は状況が収まるか,タイムアウト(トランザクション,またはブロッキングタイムアウト)が起こるまで,ブロッキングしています。
- TPNOTIME
-
呼び出し側を無期限にブロックして,ブロッキングタイムアウトが起こらないことを意味します。トランザクションタイムアウトは起こります。
- TPSIGRSTRT
-
シグナルが実行中のシステムコールを中断したら,中断したシステムコールを再び呼びます。
リターン値
tpcall()が正常リターンするか,またはTPESVCFAILがtperrnoに設定されてリターンしたとき,アプリケーションがtpreturn()の引数として渡した定義値は,グローバル変数tpurcodeとして参照できます。エラー時には,-1をリターンして,tperrnoにエラーの状態を示す値を設定します。
エラー
次のような場合,tpcall()はエラーリターンして,次のうちどれか一つの値をtperrnoに設定します。特に示さないかぎり,呼び出し側のトランザクションがあった場合でも,失敗は呼び出し側のトランザクションに影響を与えません。
リターン値 |
リターン値(数値) |
意味 |
---|---|---|
TPEBLOCK |
3 |
TPNOBLOCKを設定したtpcall()で送信したときに,ブロッキング状態になりました。 |
TPEINVAL |
4 |
間違った引数が与えられました(例えば,svcがNULLか,またはflagsに設定した値が間違っている)。 |
TPENOENT |
6 |
svcで示すサービスが存在しないので,送信できません。 |
TPEOS |
7 |
オペレーティングシステムにエラーが起こりました。厳密なエラーの性質は,product-specificな方法で定義されます。 |
TPEPROTO |
9 |
tpcall()が間違った状況で呼ばれました。 |
TPESVCERR |
10 |
このエラーは,サービス関数を呼び出しているときか,tpreturn()で完了するときに起こります(例えば,適切でない引数を設定した)。このエラーが起こったときは,応答のデータはリターンされません(つまり,*odataも*olenも変わっていません)。サービスに応答する処理が呼び出し側のトランザクションとして実行された場合は,トランザクションはrollback_only状態になります。
|
TPESVCFAIL |
11 |
呼び出し側の応答を送信するサービス関数が,TPFAILを設定したtpreturn()を呼び出しました。これは,アプリケーションレベルの失敗です。送信されたサービスの応答の内容は,*odataで指すバッファとして有効になります。サービス要求が呼び出し側の現在のトランザクションとして実行されている場合は,トランザクションはrollback_only状態となります。
|
TPESYSTEM |
12 |
コミュニケーションリソースマネジャシステムでエラーが起こりました。厳密なエラーの性質は,product-specificな方法で定義されます。 |
TPETIME |
13 |
タイムアウトが起こりました。呼び出し側がトランザクションモードの場合,これはトランザクションタイムアウトで,トランザクションはrollback_only状態となります。そうでない場合は,TPNOBLOCKもTPNOTIMEも設定されていない状態で,ブロッキングタイムアウトが起こったことを意味します。どちらの場合も,*odataも*olenも変わっていません。トランザクションタイムアウトが起こった場合は,トランザクションをロールバックするまでは,新しく送信しようとしていた送信や,解決していない応答は,TPETIMEでエラーリターンします。 |
TPETRAN |
14 |
svcがトランザクション処理をできないにもかかわらず,TPNOTRANが設定されていません。 |
TPEGOTSIG |
15 |
シグナルは受信されましたが,TPSIGRSTRTが設定されていません。 |
TPEITYPE |
17 |
idataのtypeとsubtypeが,svcで使える形式ではありません。 |
TPEOTYPE |
18 |
応答のtypeとsubtypeを,呼び出し側で認識できません。または,TPNOCHANGEのフラグが設定されているのに,*odataで指しているバッファのtypeとsubtypeが,サービスから送信されてきた応答のバッファのtypeとsubtypeに一致していません。このエラーが起こった場合,*odataと*olenは変更されません。 呼び出し側のトランザクションとしてサービス要求が実行されている場合は,応答を捨てるまで,トランザクションはrollback_only状態となります。 |
関連項目
tpalloc(),tpacall(),tpgetrply(),tpreturn().
『OpenTP1で使う場合の注意事項』
-
『該当バージョンのOpenTP1では,TPNOBLOCKフラグは無効となります。そのため,TPEBLOCKがtperrnoにリターンすることはありません。OpenTP1では,ブロッキング状態のため通信ができない場合は,ネットワークダウンが原因で通信ができない場合と同様に,TPESYSTEMをリターンする仕様となっています。』
-
『該当バージョンのOpenTP1では,TPNOTIMEフラグは応答受信時にだけ有効です。サービス要求の送信時にブロッキング状態が起こった場合は,TPNOTIMEフラグは無効です。』
-
『TPSIGRSTRTフラグは無効となります。このフラグの有無に関係なく,シグナル受信時には,中断したシステムコールを再び呼びます。TPEGOTSIGがリターンすることはありません。』
-
『該当バージョンのOpenTP1では,TPEITYPEはリターンされません。svcで使えないタイプのdataを渡した場合,TPESYSTEMがリターンされます。もし呼び出し側がトランザクションモードの場合は,rollback_only状態となります。』
-
『OpenTP1では,トランザクションタイムアウトが起こったときには,そのプロセスは異常終了します。そのため,TPETIMEがリターンされるのは,ブロッキングタイムアウトの場合だけとなります。』
-
『該当バージョンのOpenTP1では,ロールバックする必要があるエラーは,X/Openで特に指定がないかぎり,TPESYSTEMとしています。ただし,TPESYSTEMがリターンしても,rollback_only状態とならない場合もあります。
-
『サービス要求先のSPPが異常終了した場合,定義のwatch_timeに指定した時間よりも早く,TPETIMEでエラーリターンするときがあります。また,watch_timeに0(応答を受信するまで無限に待つ)を指定している場合,TPEPROTOでエラーリターンするときがあります。』
-
『OpenTP1のセキュリティ機能を使っている場合で,サービス要求が認証されなかったときは,TPEPROTOでエラーリターンします。サービス要求が認証されなかったことが原因かどうかは,UAPトレースの詳細エラーコードで確認してください。』
-
『TP1/NET/OSI-TP-Extendedを使ったOSI TP通信では,回線障害はTPESVCERRでエラーリターンします。』
-
『TP1/NET/OSI-TP-Extendedを使ったOSI TP通信をする場合,送受信するデータの長さは NET/Library共通定義のNETバッファグループ定義 nettbufにあるlengthオペランドに指定した値を超えないようにしてください。』
-
『次の場合,OSI TP通信では,tpcall,またはtpgetrplyでTPESVCERRのエラーになり,TCP/IP通信ではTPENOENT,またはTPESYSTEMのエラーになります。
-
指定したサービスが要求先に存在しない
-
タイプトバッファがサーバに認識されない
-
サービス起動中にエラーになる』
-
-
『OSI TP通信で,システムのアソシエーション本数が足りない場合,ログメッセージを出力し,TPESYSTEMでリターンします。』
-
『OSI TP通信では,TPNOTIMEを指定しても,ブロッキングタイムアウトします。TCP/IP通信では,トランザクションでないとき,ブロッキングタイムアウトします。』
-
『OSI TP通信では,ユーザサービス定義のmessage_store_buflenは,nettbuf -gで指定したサイズ以上を定義してください。TCP/IP通信では,dc_rpc_callと同様です。』
-
『TP1間でOSI TP通信を行う場合で,atomic_updateオペランドが'N'のサービスをトランザクションとして呼ばれる場合,サービス要求元には,TPESVCERRが返ります。』
-
『TCP/IP通信で呼び出されたサービスから,さらにOSI TP通信でサービスを呼び出し,応答を受け取らないでサービス関数を終了した場合,TCP/IP通信でサービスを呼び出したUAPには正常な応答電文が返り,tpcall(),tpgetrply()はエラーリターンしません。』
-
『OSI TP通信をするXATMIのエラーは,従来のTCP/IPとエラー動作が異なる場合があります。』