Prepare_To_Receive - Changing state from “Send” to “Receive”

The Prepare_To_Receive (CMPTR) call has the following effect:

• All data which is still stored in the local send buffer at the time of the call is transferred to the UTM service together with permission to send.

• Once the data has been transferred from the send buffer to the UTM service, the conversation switches from the “Send” state to the “Receive” state.

Prepare_To_Receive can only be called when the conversation is in the “Send” state, but not directly after the Allocate call or after receipt of permission to send from the partner. In these two exceptional cases, a Send_Data or Send_Mapped_Data call must be issued before the Prepare_To_Receive call.

After the Prepare_To_Receive call, a Receive or Receive_Mapped_Data call must be issued. Before the Receive or Receive_Mapped_Data call, however, Set_Receive_Timer or Set_Receive_Type may be called.

Syntax

CMPTR (conversation_ID, return_code)

Parameters

--> conversation_ID	Identifier of the conversation
<-- return_code	Result of the function call

Result (return_code)

CM_OK

The call is OK. The conversation has switched from the “Send” state to the “Receive” state.

CM_DEALLOCATED_ABEND

Possible causes:

• abnormal termination of the UTM service

• termination of the UTM application

• connection shutdown by UTM administration

• connection shutdown by the transport system

• Connection shutdown by openUTM because the maximum permitted number of users (MAX statement, CONN-USERS=) has been exceeded. This may also occur if an administrator user was transferred in the Set_Conversation_Security_User_ID call. This is the case if a user ID that has no administration authorization is assigned to the LTERM partner of the CPI-C program in the UTM application (via LTERM ...USER=).

The program enters the “Reset” state.

CM_PRODUCT_SPECIFIC_ERROR

Possible causes:

• The UPIC instance could not be found.

• The Prepare_To_Receive call was issued immediately after an Allocate call instead of a Send_Data or Send_Mapped_Data call.

CM_PROGRAM_STATE_CHECK

The call is not permitted in the current state of the conversation.

CM_PROGRAM_PARAMETER_CHECK

The value of conversation_ID is invalid.

CM_RESOURCE_FAILURE_NO_RETRY

An error has occurred which led to a premature termination of the conversation (e.g. a protocol error or a premature loss of the network connection). The program enters the “Reset” state.

State change

• If the result of the call is CM_OK, the state of the conversation changes from “Send” to “Receive”.

• With the following results, the program enters the “Reset” state:
  CM_DEALLOCATED_ABEND
  CM_RESOURCE_FAILURE_NO_RETRY

• In all other error conditions, the program does not change its state.

Behavior in the event of errors

CM_PRODUCT_SPECIFIC_ERROR

• Modify program.

• The operating system cannot provide sufficient memory for the internal buffers. Check whether the memory requirement of your program is too high and if necessary reboot your system.

CM_PROGRAM_STATE_CHECK

Modify program.

CM_PROGRAM_PARAMETER_CHECK

Modify program.

CM_RESOURCE_FAILURE_NO_RETRY

Inform the service department and produce a diagnostic report. A fault in the transport system could also be the reason for this error code.

Function declaration: Prepare_To_Receive

CM_ENTRY Prepare_To_Receive (unsigned char CM_PTR conversation_ID,
                            CM_RETURN_CODE CM_PTR return_code )