TPRECV
形式
01 TPSVCDEF-REC. COPY TPSVCDEF. 01 TPTYPE-REC. COPY TPTYPE. 01 DATA-REC. COPY Data record definition. 01 TPSTATUS-REC. COPY TPSTATUS. CALL "TPRECV" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
機能
TPRECVは,ほかのプログラムからオープンコネクションを渡って送信されてきたデータを受信するために使います。COMM-HANDLEには,データを受信するためのオープンコネクションを設定します。COMM-HANDLEは,TPCONNECTまたはTPSVCSTARTから返された通信ハンドルです。DATA-RECには,メッセージが読み込まれる位置を設定して,入力の場合は,LENにはDATA-RECに設定するバイトの最大値を設定します。
成功した場合,幾つかのイベントタイプでは,LENには実際にDATA-RECに設定されたバイト長が設定されます。REC-TYPEとSUB-TYPEにはそれぞれ,データのtypeとsubtypeが設定されます。DATA-RECの値よりも応答が大きい場合は,DATA-RECにはレコードに入るだけのバイトが格納されます。応答の残りの部分は捨てられて,TPRECVはTPTRUNCATEを返します。
TPRECVが正常に終了した場合にTPTYPE-RECのLENが0であるときは,応答にはデータ部がなく,DATA-RECは変更されません。入力時にLENに0を設定した場合は,エラーになります。
TPRECVは,コネクションの制御権を持たないプログラムでだけ呼び出せます。
『データ領域』
『●TPSVCDEF-REC
TPRECVの動作を示す値と通信ハンドルを設定します。設定する値と意味は,以降説明します。』
『●TPTYPE-REC
受信するデータのレコード型と,subtypeのレコード名を設定します。』
『●DATA-REC
受信するレコードを示します。』
『●TPSTATUS-REC
TPRECVの実行結果を示すリターン値が設定されます。』
TPSVCDEF-RECには,次に示す値を設定します。
- TPNOCHANGE
-
この値を設定した場合,DATA-RECの型は変更されません。この値を設定した場合は,応答レコードのtypeとsubtypeが,REC-TYPEとSUB-TYPEにそれぞれ必ず一致させてください。TPNOCHANGEまたはTPCHANGEのどちらかを,必ず設定してください。
- TPCHANGE
-
受信レコードのtypeとsubtypeがREC-TYPEまたはSUB-TYPEと異なっていても,受け取り側が認識する限り,それぞれ受信を許可することを示します。TPNOCHANGEまたはTPCHANGEのどちらかを,必ず設定してください。
- TPNOBLOCK
-
TPRECVはデータの到着を待ちません。データがすでに受信できる状態の場合は,TPRECVはデータを受信してリターンします。TPNOBLOCKまたはTPBLOCKのどちらかを,必ず設定してください。
- TPBLOCK
-
TPBLOCKを設定して受信できるデータがない場合は,呼び出し側はデータを受信するまでブロック状態になります。TPNOBLOCKまたはTPBLOCKのどちらかを,必ず設定してください。
- TPNOTIME
-
呼び出し側を無期限にブロックして,ブロッキングタイムアウトが起こらないことを意味します。トランザクションタイムアウトは起こります。TPNOTIMEまたはTPTIMEのどちらかを,必ず設定してください。
- TPTIME
-
ブロッキング監視時間が経過したあとにブロッキング状態がある場合に,ブロッキングタイムアウトが起こることを意味します。TPNOTIMEまたはTPTIMEのどちらかを,必ず設定してください。
- TPSIGRSTRT
-
シグナルが実行中のシステムコールを中断したら,中断したシステムコールを再び呼びます。TPSIGRSTRTまたはTPNOSIGRSTRTのどちらかを,必ず設定してください。
- TPNOSIGRSTRT
-
シグナルが実行中のシステムコールを中断したら,中断したシステムコールを再び呼ばないでルーチンは失敗します。TPSIGRSTRTまたはTPNOSIGRSTRTのどちらかを,必ず設定してください。
イベント
COMM-HANDLEにイベントがあり,TPRECVがエラーにならない場合には,TPRECVはTP-STATUSにTPEEVENTを設定してリターンします。イベントのタイプはTPEVENTに返されます。データはTPEV-SVCSUCC,TPEV-SVCFAILとTPEV-SENDONLYのイベントとともに受信できます。TPRECVで有効なイベントを次に示します。
- TPEV-DISCONIMM
-
会話のサブオーディネータに受信されるこのイベントは,会話のオリジネータがTPDISCONを実行してコネクションをすぐに切断したか,コネクションをオープンしたままでTPRETURN,TXCOMMIT,またはTXROLLBACKを実行したときに受け取られます。また,このイベントは,通信エラーのためにコネクションが切断された場合(例えば,サーバ,マシン,ネットワークがダウンしたとき),オリジネータ,またはサブオーディネータにリターンされます。コネクションの切断はすぐに通知されるので(正常終了ではなく異常終了として),転送中のデータは捨てられます。二つのプログラムが同じトランザクションに参加している場合は,トランザクションはrollback_only状態になります。このコネクションに使われているCOMM-HANDLEは,無効になります。
- TPEV-SENDONLY
-
コネクションの他端点のプログラムは,コネクションの制御権を放棄しています。このイベントの受け取り側はデータの送信が許可されていますが,制御権を放棄するまではデータを受信できません。
- TPEV-SVCERR
-
会話のオリジネータに受信されるこのイベントは,会話のサブオーディネータがTPRETURNを実行していることを示します。TPRETURNは,サービスが成功してリターンすることを妨げるエラーに遭遇しました。例えば,TPRETURNに間違った引数が渡されていたり,サービスがほかのサブオーディネータのためにコネクションをオープンしている間に,TPRETURNが呼ばれたりした場合です。このイベントの性質のために,アプリケーションで定義されたデータやリターン値は役に立ちません。このコネクションは切断されて,COMM-HANDLEは無効になります。このイベントが受信側のトランザクションの一部で起こった場合は,トランザクションはrollback_only状態となります。
- TPEV-SVCFAIL
-
会話のオリジネータで受信されるこのイベントは,会話の他端点上のサブオーディネータのサービスがアプリケーションで指定されて,不成功に終了した(つまり,TPRETURNがTPFAILを設定して呼ばれた)ことを示します。TPRETURNが呼ばれたとき,サブオーディネータのサービスがこのコネクションを制御する場合は,コネクションのオリジネータへレコードを返します。サービスルーチンの終了の部分で,サーバはコネクションを切断します。よって,COMM-HANDLEは無効になります。このイベントが受け取り側のトランザクションの一部で起こった場合は,トランザクションはrollback_only状態となります。
- TPEV-SVCSUCC
-
会話のオリジネータで受信されるこのイベントは,会話の他端点上のサブオーディネータのサービスがアプリケーションで指定されて,成功して終了した(つまり,TPSUCCESSを設定したTPRETURNを呼んだ)ことを示します。サービスルーチンの終了の部分で,サーバはコネクションを切断します。よって,COMM-HANDLEは無効になります。このイベントが受け取り側のトランザクションの一部で起こった場合は,コミットまたはロールバックするために,サーバ(もまた,トランザクションモードの場合)によってなされた処理を引き起こしたトランザクションのコミット(受け取り側がトランザクションを開始した場合)や,ロールバックのどちらかを実行できます。
リターン値
成功した場合,TPRECVはTP-STATUSにTPOKを設定します。TP-STATUSにTPOKかTPESVCFAILが返された場合は,APPL-RETURN-CODEにはTPRETURNの処理でアプリケーションが定義した値が返されます。受信したデータの長さが入力のLENに設定した長さを超えた場合は,TPTRUNCATEが設定され,LENで示す長さ分だけ,DATA-RECに格納されます。受信したデータの残りの部分は捨てられます。
エラー
次のような場合,TPRECVはエラーリターンして,次のうちどれか一つの値をTP-STATUSに設定します。特に示さないかぎり,呼び出し側がトランザクション下にあった場合でも,失敗は呼び出し側のトランザクションに影響を与えません。
- TPEINVAL
-
間違った引数が与えられました(例えば,TPSVCDEF-RECに設定した値が間違っている)。
- TPEBADDESC
-
COMM-HANDLEに間違った通信イベントを設定しています。
- TPEOTYPE
-
到着したメッセージのtypeとsubtypeを,呼び出し側で認識していません。または,TPNOCHANGEを設定しているのに,REC-TYPEとSUB-TYPEは送信されてきたメッセージのtypeとsubtypeに一致していません。呼び出し側のトランザクションとしてサービス要求が実行されている場合は,到着したバッファを捨てるまで,トランザクションはrollback_only状態となります。このエラーが起こった場合,COMM-HANDLEに該当するイベントは捨てられて,会話型通信は,未決着な状態になります。呼び出し側は,すぐに会話型通信を終了させてください。
- TPETIME
-
タイムアウトが起こりました。呼び出し側がトランザクションモードの場合,これはトランザクションタイムアウトで,トランザクションはrollback_only状態となります。そうでない場合は,TPNOBLOCKもTPNOTIMEも設定されていない状態で,ブロッキングタイムアウトが起こったことを意味します。どちらの場合も,DATA-RECもTPTYPE-RECも変更されません。トランザクションタイムアウトが起こった場合は,トランザクションをロールバックするまでは,新しいメッセージを送受信しようとしても,新しいコネクションを開始しようとしても,TPETIMEでエラーリターンします。
- TPEEVENT
-
あるイベントが起こって,そのタイプはTPEVENTに有効な値としてリターンされます。
- TPEBLOCK
-
TPNOBLOCKを設定したTPRECVを実行したときに,ブロッキング状態になりました。
- TPEGOTSIG
-
シグナルは受信されましたが,TPNOSIGRSTRTを設定しています。
- TPEPROTO
-
TPRECVが間違った状況で呼ばれました。
- TPESYSTEM
-
コミュニケーションリソースマネジャシステムでエラーが起こりました。厳密なエラーの性質は,product-specificな方法で定義されます。
- TPEOS
-
オペレーティングシステムにエラーが起こりました。厳密なエラーの性質は,product-specificな方法で定義されます。
関連項目
TPCONNECT,TPDISCON,TPSEND
『OpenTP1で使う場合の注意事項』
-
『TPSIGRSTRTの設定は無効となります。この設定の有無に関係なく,シグナル受信時には,中断したシステムコールを再び呼びます。TPEGOTSIGがリターンすることはありません。』
-
『OpenTP1では,トランザクションタイムアウトが起こったときには,そのプロセスは異常終了します。そのため,TPETIMEがリターンされるのは,ブロッキングタイムアウトの場合だけとなります。』
-
『該当バージョンのOpenTP1では,ロールバックする必要があるエラーは,X/Openで特に指定がないかぎり,TPESYSTEMとしています。ただし,TPESYSTEMがリターンしても,rollback_only状態とならない場合もあります。』
-
『TP1/NET/OSI-TP-Extendedを使ったOSI TP通信をする場合は,会話型サービスの通信はできません。OSI TP通信で会話型サービスの通信を使った場合,システムの動作は保証しません。』