Receive (CPI-C)

Receive 呼び出し (関数名 cmrcv) は、パートナー プログラムから現在使用可能なすべてのデータを受信します。 Microsoft Windows の場合は、すべての CPI-C 通信に対してバックグラウンド スレッドを実行し、ユーザー インターフェイス専用のフォアグラウンド スレッドを保持します。

構文

  
CM_ENTRY Receive(   
unsigned char FAR *conversation_ID,    
unsigned char FAR *buffer,             
CM_INT32 FAR *requested_length,        
CM_INT32 FAR *data_received,           
CM_INT32 FAR *received_length,         
CM_INT32 FAR *status_received,         
CM_INT32 FAR *request_to_send_received,    
CM_INT32 FAR *return_code              
);  

パラメーター

conversation_ID
指定されたパラメーター。 会話の識別子を指定します。 このパラメーターの値は 、Initialize_Conversation または Accept_Conversationによって返されました。

buffer
返されたパラメーター。 ローカル プログラムによって受信されたデータを格納するバッファーのアドレスを指定します。

次の条件に該当する場合、バッファーにはデータが含まれます。

• data_received パラメーターは、CM_NO_DATA_RECEIVED以外の値に設定されます。

• return_code パラメーターは、CM_OK または CM_DEALLOCATED_NORMAL に設定されます。

  requested_length
  指定されたパラメーター。 ローカル プログラムが受信するデータの最大バイト数を示します。 範囲は 0 ~ 32767 です。

  data_received
  返されたパラメーター。 プログラムがデータを受信したかどうかを示します。 [パラメーター] セクションの次に、使用できる値を示します。

  received_length
  返されたパラメーター。 この Receive 呼び 出 しでローカル プログラムが受信したデータのバイト数を示します。 return_codeまたはdata_receivedが、プログラムがデータを受信しなかったことを示している場合、この番号は関係ありません。

  status_received
  返されたパラメーター。 会話の状態の変化を示します。 使用できる値を次に示します。 これらのコードは、 return_codeが CM_OK に設定されていない限り、関連しません。 [パラメーター] セクションの次に、使用できる値を示します。

  request_to_send_received
  返されたパラメーター。 受信要求インジケーターを指定します。 [パラメーター] セクションの後に値が一覧表示されます。

  return_code
  この呼び出しから返されたコード。 [パラメーター] セクションの後に値が一覧表示されます。

data_received パラメーターで返される値

これらのコードは、 return_codeが CM_OK または CM_DEALLOCATED_NORMAL に設定されていない限り、関連しません。

CM_DATA_RECEIVED
会話の入力特性が CM_FILL_BUFFER に設定されている場合、基本的な会話に対して返すことができます。これは、プログラムが論理形式とは無関係にデータを受信していることを示します。 ローカル プログラムは、 requested_length またはデータの終了に達するまでデータを受信しました。

データの末尾は、return_code、status_received、およびdata_receivedパラメーター、またはエラー条件に基づいて、別の会話状態への変更によって示されます。 会話の受信の種類がCM_RECEIVE_IMMEDIATEに設定されている場合、受信したデータは、パートナー プログラムから到着したデータの量が少ない場合、 requested_length 未満になる可能性があります。

CM_COMPLETE_DATA_RECEIVED
マップされた会話で、 は、ローカル・プログラムが完全なデータ・レコードまたはデータ・レコードの最後の部分を受け取っていることを示します。

入力特性がCM_FILL_LLに設定されている基本的な会話では、この値は、ローカル・プログラムが完全な論理レコードまたは論理レコードの終わりを受け取っていることを示します。

CM_INCOMPLETE_DATA_RECEIVED
マップされた会話で、 は、ローカル プログラムが不完全なデータ レコードを受信したことを示します。 requested_length パラメーターは、データ レコードの長さより小さい値を指定しました (レコードを読み取る最初の Receive でない場合は、データ レコードの残りの部分より小さい値)。 受信したデータの量は、 requested_length パラメーターと同じです。

入力特性がCM_FILL_LLに設定されている基本的な会話では、この値は、ローカル プログラムが不完全な論理レコードを受信したことを示します。 受信したデータの量は、 requested_length パラメーターと同じです。 (受信したデータが切り捨てられた場合、データの長さは requested_length未満になります)。

この値を受け取ると、ローカル・プログラムは通常 、レコード の次の部分を受け取るために Receive を再発行します。

CM_NO_DATA_RECEIVED
プログラムがデータを受信しませんでした。

return_code パラメーターが CM_OK に設定されている場合は、 status_received パラメーターを使用して状態情報を使用できる場合があることに注意してください。

status_received パラメーターで返される値

CM_NO_STATUS_RECEIVED
この呼び出しで会話の状態の変更は受信されませんでした。

CM_SEND_RECEIVED
パートナー プログラムに対して、会話が RECEIVE 状態に入っていることを示します。 ローカル プログラムの場合、この呼び出しでデータが受信されなかった場合はメッセージ交換が SEND 状態になり、この呼び出しでデータが受信された場合はSEND_PENDING状態になります。

この値を受け取ると、ローカル プログラムは通常 、Send_Data を使用してデータの送信を開始します。

CM_CONFIRM_DEALLOC_RECEIVED
パートナー プログラムが、確認が要求された 状態で割り当て解除 を発行したことを示します。 ローカル プログラムの場合、会話はCONFIRM_DEALLOCATE状態になりました。

この値を受信すると、ローカル プログラムは通常 、Confirmed 呼び出しを発行します。

CM_CONFIRM_RECEIVED
パートナー プログラムが Confirm 呼び出しを発行したことを示します。 ローカル プログラムの場合、会話は CONFIRM 状態です。

この値を受信すると、ローカル プログラムは通常 、Confirmed 呼び出しを発行します。

CM_CONFIRM_SEND_RECEIVED
パートナー プログラムに対して、会話が RECEIVE 状態に入り、確認の要求がローカル プログラムによって受信されたことを示します。 ローカル プログラムの場合、会話はCONFIRM_SEND状態になりました。

プログラムは通常、 Confirmed 呼び出しを発行して応答します。 Confirmed 呼び出しが正常に実行されると、会話はローカル プログラムの SEND 状態に変わります。

request_to_send_received パラメーターで返される値

CM_REQ_TO_SEND_RECEIVED
パートナー・プログラムが Request_To_Send 呼び出しを発行しました。この呼び出しは、ローカル・プログラムに会話を RECEIVE 状態に変更するよう要求します。

CM_REQ_TO_SEND_NOT_RECEIVED
パートナー プログラムは 、Request_To_Send 呼び出しを発行しませんでした。 この値は、return_code パラメーターが CM_PROGRAM_PARAMETER_CHECK または CM_PROGRAM_STATE_CHECK に設定されている場合は関係ありません。

return_code パラメーターで返される値

CM_OK
主なリターン コード。呼び出しが正常に実行されました。

CM_OPERATION_NOT_ACCEPTED
主なリターン コード。この会話に対する前の操作が不完全です。

CM_OPERATION_INCOMPLETE
主なリターン コード。操作が完了せず (処理モードは非ブロッキングのみ)、まだ進行中です。 プログラムは 、Wait_For_Conversation を発行して操作の完了を 待機したり、 操作と会話を取り消Cancel_Conversationしたりできます。 Specify_Windows_Handleが呼び出された場合、アプリケーションは Windows® メッセージによる通知を待機し、Wait_For_Conversationを呼び出す必要はありません。

CM_UNSUCCESSFUL
主なリターン コード。受信の種類は CM_RECEIVE_IMMEDIATE に設定され、パートナー プログラムからすぐに使用できるデータはありません。

CM_DEALLOCATED_NORMAL
プライマリ リターン コード。会話の割り当てが正常に解除されました。 発行されたパートナー プログラムは、CM_NONEとして指定されたスレッドの同期レベルをCM_DEALLOCATE_FLUSHまたはCM_DEALLOCATE_SYNC_LEVELに設定された、スレッドの割り当て解除の種類を使用して割り 当てを解除 します。

CM_PROGRAM_PARAMETER_CHECK
プライマリ リターン コード。次のいずれかが発生しました。

• conversation_IDで指定された値が無効です。

• requested_length で指定された値が範囲外 (32767 より大きい) です。

  プログラムがこの戻りコードを受け取った場合、他の戻りパラメーターは無効です。

  CM_PROGRAM_STATE_CHECK
  プライマリ リターン コード。次のいずれかが発生しました。

• 受信の種類が CM_RECEIVE_AND_WAIT に設定され、会話の状態が RECEIVE、SEND、またはSEND_PENDINGではありません。

• 受信の種類は CM_RECEIVE_IMMEDIATE に設定され、会話の状態は RECEIVE ではありません。

• 基本的な会話では、会話は SEND 状態で、受信の種類はCM_RECEIVE_AND_WAITに設定され、プログラムは論理レコードの送信を完了しませんでした。

  プログラムがこの戻りコードを受け取った場合、他の戻りパラメーターは無効です。

  CM_PRODUCT_SPECIFIC_ERROR
  プライマリ リターン コード。製品固有のエラーが発生し、製品エラー ログに記録されています。

  CM_CONVERSATION_TYPE_MISMATCH
  プライマリ リターン コード。パートナー論理ユニット (LU) またはプログラムは、割り当て要求で指定された会話の種類 (基本またはマップ) をサポートしていません。

  CM_PIP_NOT_SPECIFIED_CORRECTLY
  プライマリ リターン コード。割り当て要求は、CPI-C LU 6.2 以外のトランザクション プログラム (TP) によって拒否されました。 パートナー・プログラムには、CPI-C ではサポートされていない 1 つ以上の PIP データ変数が必要です。

  CM_SECURITY_NOT_VALID
  プライマリ リターン コード。割り当て要求で指定されたユーザー ID またはパスワードが、パートナー LU によって受け入れられなかった。

  CM_SYNC_LEVEL_NOT_SUPPORTED_PGM
  プライマリ リターン コード。パートナー プログラムは、割り当て要求で指定された同期レベルをサポートしていません。

  CM_TPN_NOT_RECOGNIZED
  プライマリ リターン コード。パートナー LU は、割り振り要求で指定されたプログラム名を認識しません。

  CM_TP_NOT_AVAILABLE_NO_RETRY
  プライマリ リターン コード。永続的な条件のため、パートナー LU は割り振り要求で指定されたプログラムを開始できません。 エラーの理由が、リモート ノードでログに記録されている可能性があります。 エラーが修正されるまで、割り当てを再試行しないでください。

  CM_TP_NOT_AVAILABLE_RETRY
  プライマリ リターン コード。一時的な条件のため、パートナー LU は割り当て要求で指定されたプログラムを開始できません。 エラーの理由が、リモート ノードでログに記録されている可能性があります。 割り当てを再試行してください。

  CM_PROGRAM_ERROR_NO_TRUNC
  プライマリ リターン コード。エラーの方向がCM_SEND_ERRORに設定されている状態またはSEND_PENDING状態の場合、パートナー プログラムは Send_Errorを発行します。 データは切り捨てられませんでした。

  CM_PROGRAM_ERROR_PURGING
  プライマリ リターン コード。次のいずれかが発生しました。

• RECEIVE または CONFIRM 状態の間に、パートナー プログラムが Send_Error発行しました。 送信されたデータがまだ受信されていないデータは消去されます。

• エラーの方向がCM_RECEIVE_ERRORに設定された状態SEND_PENDING、パートナー プログラムは Send_Error発行します。 データが消去されませんでした。

  CM_RESOURCE_FAILURE_NO_RETRY
  プライマリ リターン コード。次のいずれかが発生しました。

• 永続的な状態のため、会話が途中で終了しました。 エラーが修正されるまで再試行しないでください。

• パートナー プログラムは、正常に終了する前に会話の割り当てを解除しませんでした。

  CM_RESOURCE_FAILURE_RETRY
  プライマリ リターン コード。モデム障害などの一時的な状態が原因で、メッセージ交換が途中で終了しました。 会話を再試行します。

  CM_DEALLOCATED_ABEND
  プライマリ リターン コード。次のいずれかの理由で、会話の割り当てが解除されました。

• リモート・プログラムが、タイプ・パラメーター・セットを使用してCM_DEALLOCATE_ABEND割 り振り解除 を発行したか、リモート・プログラムの異常終了状態のためにリモート LU が割り当てを解除しました。 呼び出しの発行時にリモート・プログラムの会話が RECEIVE 状態であった場合、ローカル・プログラムによって送信され、リモート・プログラムによってまだ受信されていない情報は消去されます。

• リモート TP は正常に終了しましたが、終了する前に会話の割り当てを解除しませんでした。 リモート LU のノード サービスは、リモート TP に代わって会話の割り当てを解除しました。

  CM_DEALLOCATED_ABEND_SVC
  プライマリ リターン コード。次のいずれかの理由で、会話の割り当てが解除されました。

• 型パラメーターが ABEND_SVC に設定された状態で、パートナー プログラムによって 割り当て解除 が発行されました。

• パートナー プログラムは、終了する前に会話の割り当てを解除しませんでした。

  この呼び出しがローカル・プログラムによって発行されたときに、パートナー・プログラムのメッセージ交換が RECEIVE 状態の場合、ローカル・プログラムによって送信され、まだパートナー・プログラムによって受信されていないデータは消去されます。

  CM_DEALLOCATED_ABEND_TIMER
  プライマリ リターン コード。パートナー プログラムが型パラメーターを ABEND_TIMER に設定して 割り当て解除 を発行したため、会話の割り当てが解除されました。 この呼び出しがローカル・プログラムによって発行されたときに、パートナー・プログラムのメッセージ交換が RECEIVE 状態の場合、ローカル・プログラムによって送信され、まだパートナー・プログラムによって受信されていないデータは消去されます。

  CM_SVC_ERROR_PURGING
  プライマリ リターン コード。が SEND 状態の場合、タイプ パラメーターが SVC に設定 された状態 でパートナー プログラムまたはパートナー LU がSend_Error発行されます。 パートナー プログラムに送信されたデータが消去されている可能性があります。

  CM_SVC_ERROR_NO_TRUNC
  プライマリ リターン コード。が SEND 状態の場合、タイプ パラメーターが SVC に設定 された状態 でパートナー プログラムまたはパートナー LU がSend_Error発行されます。 パートナー プログラムに送信されたデータが消去されている可能性があります。

  CM_PROGRAM_ERROR_TRUNC
  プライマリ リターン コード。SEND 状態では、完全な論理レコードの送信が完了する前に、パートナー・プログラムが Send_Error発行しました。 ローカル プログラムは、Receive 呼び出しを介して論理レコードの最初の部分を 受信 した可能性があります。

  CM_SVC_ERROR_TRUNC
  プライマリ リターン コード。RECEIVE または CONFIRM 状態の場合、パートナー・プログラムまたはパートナー LU は、 完全な論理レコードの送信を完了する前に、タイプ・パラメーターが SVC に設定された状態でSend_Error発行されます。 ローカル・プログラムが論理レコードの最初の部分を受け取った可能性があります。

  状態の変更

  会話は、RECEIVE、SEND、またはSEND_PENDING状態にすることができます。

  receive_typeが CM_RECEIVE_IMMEDIATE に設定されている場合、会話は RECEIVE 状態である必要があります。

  メッセージ交換が SEND またはSEND_PENDING状態の間に Receive を発行すると、ローカル LU は送信バッファー内の情報と送信インジケーターをパートナー プログラムに送信します。 data_receivedとstatus_receivedに基づいて、会話はローカル プログラムの RECEIVE 状態に変更できます。

  新しい会話の状態は、次の方法で決定されます。

• プログラムが呼び出しを発行したときの会話の状態。

• return_code パラメーター。

• data_receivedパラメーターとstatus_received パラメーター。

  現在使用できるデータがなく、受信の種類 ( Set_Receive_Typeによって設定) が CM_RECEIVE_AND_WAIT に設定されている場合、ローカル プログラムはデータの到着を待機します。 受信の種類が CM_RECEIVE_IMMEDIATE に設定されている場合、ローカル プログラムは待機しません。

  データを受信するプロセスは次のとおりです。

• ローカル プログラムは、データの完全な単位の受信が完了するまで、受信呼び出しを発行します。 ローカル プログラムでは、データの完全な単位を受け取るために Receive を複数回発行する必要がある場合があります。 data_received パラメーターは、データの受信が完了したかどうかを示します。

  受信するデータは次のとおりです。

  • マップされた会話で送信される 1 つのデータ レコード。

  • 基本的な会話で送信される 1 つの論理レコードで、会話の入力特性が CM_FILL_LL に設定されています。

  • 入力特性が CM_FILL_BUFFER に設定された基本的な会話で、論理レコード形式とは無関係に受信したデータのバッファー。

    データの完全な単位を受信すると、ローカル プログラムで操作できます。

• ローカル プログラムは、 status_receivedを介して受信した制御情報に基づいて、次に実行するアクションを決定します。 ローカル・プログラムは、制御情報を受け取るために Receive を再発行しなければならない場合があります。

  会話の種類は 、Set_Conversation_Typeによって設定されます。 フィル特性は 、Set_Fillによって設定されます。

  次の表は、 Receive が RECEIVE 状態で会話と共に発行され、 return_codeがCM_OK されたときに発生する可能性がある状態の変更をまとめたものです。

data_received	status_received	新しい状態
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	変更なし
受信CM_COMPLETE_DATA_	CM_NO_STATUS_RECEIVED	変更なし
受信CM_INCOMPLETE_DATA_	CM_SEND_RECEIVED	SEND_PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	SEND

return_codeがCM_UNSUCCESSFULに設定されている場合、つまり、receive_typeがCM_RECEIVE_IMMEDIATEに設定されていて、使用可能なデータがない場合、状態の変更はありません。

次の表は、SEND 状態のメッセージ交換で Receive が発行され、 return_codeがCM_OK されたときに発生する可能性がある状態の変更をまとめたものです。

data_received	status_received	新しい状態
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
受信CM_COMPLETE_DATA_	CM_NO_STATUS_RECEIVED	RECEIVE
受信CM_INCOMPLETE_DATA_	CM_SEND_RECEIVED	SEND_PENDING
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	変更なし

次の表は、メッセージ交換が SEND_PENDING 状態で Receive が発行され、 return_code がCM_OKされたときに発生する可能性がある状態の変更をまとめたものです。

data_received	status_received	新しい状態
CM_DATA_RECEIVED	CM_NO_STATUS_RECEIVED	RECEIVE
受信CM_COMPLETE_DATA_	CM_NO_STATUS_RECEIVED	RECEIVE
受信CM_INCOMPLETE_DATA_	CM_SEND_RECEIVED	変更なし
CM_NO_DATA_RECEIVED	CM_SEND_RECEIVED	SEND

次のトピックでは、許可された状態で Receive が発行されたときに発生する可能性がある状態の変更をまとめています。

このセクションの内容

• 確認

• 通常の割り当て解除

• 異常終了

• エラー