Prepare_To_Receive

The Prepare_To_Receive call (function name cmptr) changes the state of the conversation for the local program from SEND to RECEIVE.

CM_ENTRY Prepare_To_Receive(
  unsigned char FAR *conversation_ID,  
  CM_INT32 FAR *return_code            
);
 

Parameters

conversation_ID

Supplied parameter. Specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation or Accept_Conversation.

return_code

The code returned from this call. The valid return codes are listed below.

Return Codes

cm_ok

Primary return code; the call executed successfully.

cm_operation_not_accepted

Primary return code; a previous operation on this conversation is incomplete.

cm_operation_incomplete

Primary return code; the operation has not completed (processing mode is nonblocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation and conversation. If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.

cm_program_parameter_check

Primary return code; the value specified by conversation_ID is invalid.

cm_program_state_check

Primary return code; one of the following occurred:

• The conversation state is not SEND or SEND_PENDING.
• For a basic conversation, the conversation is in SEND state. However, the program did not finish sending a logical record.

These return codes can occur if the conversation's prepare-to-receive type is set to CM_PREP_TO_RECEIVE_CONFIRM or if the prepare-to-receive type is set to CM_PREP_TO_RECEIVE_SYNC_LEVEL and the conversation's synchronization level is set to CM_CONFIRM.

cm_product_specific_error

Primary return code; a product-specific error occurred and has been logged in the product's error log.

cm_conversation_type_mismatch

Primary return code; the partner LU or program does not support the conversation type (basic or mapped) specified in the allocation request.

cm_pip_not_specified_correctly

Primary return code; the allocation request was rejected by a non-CPI-C LU 6.2 TP. The partner program requires one or more PIP data variables, which are not supported by CPI-C.

cm_security_not_valid

Primary return code; the user identifier or password specified in the allocation request was not accepted by the partner LU.

cm_sync_level_not_supported_pgm

Primary return code; the partner program does not support the synchronization level specified in the allocation request.

cm_tpn_not_recognized

Primary return code; the partner LU does not recognize the program name specified in the allocation request.

cm_tp_not_available_no_retry

Primary return code; the partner LU cannot start the program specified in the allocation request because of a permanent condition. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

cm_tp_not_available_retry

Primary return code; the partner LU cannot start the program specified in the allocation request because of a temporary condition. The reason for the error may be logged on the remote node. Retry the allocation.

cm_program_error_purging

Primary return code; one of the following occurred:

• While in RECEIVE or CONFIRM state, the partner program issued Send_Error. Data sent but not yet received is purged.
• While in SEND_PENDING state with the error direction set to CM_RECEIVE_ERROR, the partner program issued Send_Error. Data was not purged.

cm_resource_failure_no_retry

Primary return code; one of the following occurred:

• The conversation was terminated prematurely because of a permanent condition. Do not retry until the error has been corrected.
• The partner program did not deallocate the conversation before terminating normally.

cm_resource_failure_retry

Primary return code; the conversation was terminated prematurely because of a temporary condition, such as modem failure. Retry the conversation.

cm_deallocated_abend

Primary return code; the conversation has been deallocated for one of the following reasons:

• The remote program issued Deallocate with the type parameter set to CM_DEALLOCATE_ABEND, or the remote LU did so because of a remote program abnormal-ending condition. If the conversation for the remote program was in RECEIVE state when the call was issued, information sent by the local program and not yet received by the remote program is purged.
• The remote TP terminated normally but did not deallocate the conversation before terminating. Node services at the remote LU deallocated the conversation on behalf of the remote TP.

cm_deallocated_abend_svc

Primary return code; the conversation has been deallocated for one of the following reasons:

• The partner program issued Deallocate with the type parameter set to ABEND_SVC.
• The partner program did not deallocate the conversation before terminating.

If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

cm_deallocated_abend_timer

Primary return code; the conversation has been deallocated because the partner program issued Deallocate with the type parameter set to ABEND_TIMER. If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.

cm_svc_error_purging

Primary return code; while in SEND state, the partner program or partner LU issued Send_Error with the type parameter set to SVC. Data sent to the partner program may have been purged.

State Changes

The conversation can be in SEND or SEND_PENDING state.

State changes, summarized in the following table, are based on the value of the return_code parameter.

Before changing the conversation state, this call performs the equivalent of one of the following:

• The Flush call, sending the contents of the local LU's send buffer to the partner LU and program, if either of the following conditions is true:

  The conversation's prepare-to-receive type is set to CM_PREP_TO_RECEIVE_FLUSH.

  The conversation's prepare-to-receive type is set to CM_PREP_TO_RECEIVE_SYNC_LEVEL and the conversation's synchronization level is set to CM_NONE.

• The Confirm call, sending the contents of the local LU's send buffer and a confirmation request to the partner program, if either of the following conditions is true:

  The conversation's prepare-to-receive type is set to CM_PREP_TO_RECEIVE_CONFIRM.

  The conversation's prepare-to-receive type is set to CM_PREP_TO_RECEIVE_SYNC_LEVEL and the conversation's synchronization level is set to CM_CONFIRM.

The prepare-to-receive type is set by Set_Prepare_To_Receive_Type; the synchronization level is set by Set_Sync_Level.

The conversation cannot change to SEND or SEND_PENDING for the partner program until the partner program receives one of the following values through the status_received parameter of the Receive call:

• cm_send_received
• cm_confirm_send_received and replies with the Confirmed or Send_Error call

Remarks

After this call has successfully executed, the local program can receive data.