CMRCV — Receive


CMRCV (conversation_ID, receive_buffer, requested_length, data_received,,
       received_length, status_received, request_to_send_received,,
       return_code) [LOGGING log_byte]

Where

conversation_ID (character input) specifies the conversation identifier of the desired conversation.

receive_buffer (character output) specifies the variable in which the program is to receive data. This parameter contains data only if return_code is set to CM_OK or CM_DEALLOCATED_NORMAL and data_received is not set to CM_NO_DATA_RECEIVED.

requested_length (numeric input) specifies the maximum amount of data the program is to receive. Valid requested_length values range from 0 to 32767.

data_received (numeric output) specifies whether the program received data. Unless return_code is set to CM_OK or CM_DEALLOCATED_NORMAL, the value contained in data_received is meaningless. The data_received variable can have one of the following values:

CM_NO_DATA_RECEIVED (basic and mapped conversations)
CM_DATA_RECEIVED (basic conversations only)
CM_COMPLETE_DATA_RECEIVED (basic and mapped conversations)
CM_INCOMPLETE_DATA_RECEIVED (basic and mapped conversations)

received_length (numeric output) specifies the variable containing the amount of data the program received, up to the maximum. If the program does not receive data on this statement, the value contained in received_length is meaningless.

status_received (numeric output) specifies the variable containing an indication of the conversation status. The status_received variable can have one of the following values:

CM_NO_STATUS_RECEIVED
CM_SEND_RECEIVED
CM_CONFIRM_RECEIVED
CM_CONFIRM_SEND_RECEIVED
CM_CONFIRM_DEALLOC_RECEIVED

request_to_send_received (numeric_output) specifies the variable containing an indication of whether the remote program issued a CMRTS statement. If return_code is set to CM_PROGRAM_PARAMETER_CHECK or CM_PROGRAM_STATE_CHECK, the value contained in request_to_send_received is meaningless. The request_to_send_received variable can have one of the following values:

CM_REQ_TO_SEND_RECEIVED
CM_REQ_TO_SEND_NOT_RECEIVED

return_code (numeric output) specifies the result of the statement execution. The return codes that can be returned depend on the state and characteristics of the conversation at the time this statement is issued.

log_byte is a 1-byte string constant or a string expression that specifies a byte of user data to be associated with this CPI-C statement during logging. log_byte is also associated with the data which may be received when a CMRCV successfully completes. The log_byte remains active until another CPI-C statement is issued. This byte gives users of the Response Time Utility a way to identify transactions from transmitted or received data when gathering statistics by the various user-defined "log_byte" categories. Only the first character or first two hexadecimal digits of the string expression are used. The default log_byte is X'00'.

Function

A program uses the CMRCV statement to simulate the CPI-C CMRCV call, which is used to receive information from a given conversation. The information received can be a data record (on a mapped conversation), data (on a basic conversation), conversation status, or a request for confirmation.

Before issuing the CMRCV statement, a program has the option of issuing one or both of the following statements which affect the function of the CMRCV Statement:

CMSF — Set_Fill
CMSRT — Set_Receive_Type

For more information on CMRCV and its parameters, refer to the Receive (CMRCV) call description in the “Call Reference” chapter of Systems Application Architecture Common Programming Interface Communications Reference.