A program uses the Send_Data (CMSEND) call to send data to a UTM service. A program must issue a Send_Data or Send_Mapped_Data call each time it receives permission to send. This is the case:
immediately after a successful Allocate call or
when status_received has the value CM_SEND_RECEIVED after the Receive() or Receive_Mapped_Data() call (i.e. when the program has received permission to send).
CMSEND (conversation_ID, buffer, send_length, control_information_received, return_code)
Parameters
--> conversation_ID | Identifier of the conversation. |
--> buffer | Buffer with the data to be sent. The length of the data is specified in the send_length parameter. |
--> send_length | Length in bytes of data to be sent. Minimum: 0, maximum: 32767 A Send_Data call with length 0 means that a message with length 0 is sent. |
<-- control_information_received | This is only supported syntactically and always has the value CM_REQ_TO_SEND_NOT_RECEIVED. If the return code is not CM_OK, the value of control_information_received is undefined. |
<-- return_code | Result of the function call. |
Result ( return_code )
CM_OK
The call is OK.
CM_TPN_NOT_RECOGNIZED
This return code can only occur with the first Send_Data call after an Allocate() call. After the conversation was established, an error occurred which led to termination of the conversation.
CM_DEALLOCATED_ABEND
Possible causes:
termination of UTM application
connection shutdown by UTM administration
connection shutdown by the transport system
CM_RESOURCE_FAILURE_RETRY
A temporary resource bottleneck led to termination of the conversation. It may not be possible to buffer any further data in the UTM page pool.
Action: Increase the size of the UTM page pool (MAX statement PGPOOL=).
CM_PROGRAM_STATE_CHECK
The call is not permitted in the current state.
CM_PROGRAM_PARAMETER_CHECK
The conversation_ID is invalid or the value of send_length is greater than 32767 or less than 0.
State change
If the return code is CM_OK, the program remains in the “Send” state.
If the return code is CM_TPN_NOT_RECOGNIZED, CM_DEALLOCATED_ABEND, or CM_RESOURCE_FAILURE_RETRY/NO_RETRY, the program enters the “Reset” state.
In all other error conditions, the program does not change its state.
Note
UPIC buffers the data to be sent, and does not send it to the UTM server until a later point in time. Consequently, termination of the UTM application may not be returned immediately, and may not be reported until the next call has been issued.
Behavior in the event of errors
CM_RESOURCE_FAILURE_RETRY
Re-establish conversation.
CM_PROGRAM_STATE_CHECK
Modify program.
CM_PROGRAM_PARAMETER_CHECK
Modify program.
CM_ENTRY Send_Data ( unsigned char CM_PTR conversation_ID,
unsigned char CM_PTR buffer,
CM_INT32 CM_PTR send_length,
CM_CONTROLINFORMATION_RECEIVED CM_PTR control_information_received,
CM_RETURN_CODE CM_PTR return_code )