Send_Mapped_Data - Sending data and format identifier

A program uses the Send_Mapped_Data (CMSNDM) call to send data and a format identifier 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; that is when the program has received permission to send.

Syntax

CMSNDM (conversation_ID, map_name, map_name_length, buffer, send_length, control_information_received, return_code)

Parameters

--> conversation_ID	Identifier of the conversation.
--> map_name	Format identifier sent to the UTM application. The format identifier specifies the structure information for the recipient of the data.
--> map_name_length	Length of the format identifier in bytes.
--> buffer	Address of the 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_Mapped_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_Mapped_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.

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.

CM_MAP_ROUTINE_ERROR

Possible causes:

• In the UTM partner application, format identifiers are not supported in the UPIC protocol.

• The length of the format identifier is less than 0 or greater than 8.

State change

• If the return code is CM_OK, the program remains in the “Send” state.

• If the return code is one of the following the program enters the “Reset” state:
  CM_TPN_NOT_RECOGNIZED
  CM_DEALLOCATED_ABEND
  CM_RESOURCE_FAILURE_RETRY/NO_RETRY

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

Notes

• The data is always transferred transparently. The data sent is shown to the partner UTM service in the MGET call.
  The format identifier in map_name is transferred to the UTM service in the KCMF/kcfn field during the MGET call.

• For performance reasons, UPIC buffers the data to be sent, and does not send it to the UTM server until later (with a follow-up call). Consequently, termination of the UTM application may not be returned immediately, and may not be reported until the next call has been issued.

• map_name is reset as soon as the value of map_name is sent to UTM.

Behavior in the event of errors

CM_RESOURCE_FAILURE_RETRY

Re-establish conversation. If the error recurs, the page pool of the UTM application may be too small and should be enlarged (MAX statement, PGPOOL=).

CM_PROGRAM_STATE_CHECK

Modify program.

CM_PROGRAM_PARAMETER_CHECK

Modify program.

Function declaration: Send_Mapped_Data

CM_ENTRY Send_Mapped_Data(unsigned char CM_PTR  conversation_ID,
        unsigned char                   CM_PTR  map_name,
        CM_INT32                        CM_PTR  map_name_length,
        unsigned_char                   CM_PTR  buffer,
        CM_INT32                        CM_PTR  send_length,
        CM_CONTROL_INFORMATION_RECEIVED CM_PTR  control_information_received,
        CM_RETURN_CODE                  CM_PTR  return_code )