otma_send_receive API

The otma_send_receive API is invoked to initiate a message exchange with IMS.

Description

The caller gives buffer definitions for both send and receive. Both send buffer and receive buffer information is provided. By providing receive information at the same time as send there are no unexpected messages from IMS, greatly simplifying the protocol. When the reply arrives from IMS the ECB will be posted. All the work of buffer management is handled in the message exit routine.

An extended version of the otma_send_receive API, which is called otma_send_receivex, provides extended functionality.

Invocation

Called by the client in TCB mode.

Input

*anchor

Pointer to anchor word that was set up by otma_open.

*session_handle

Pointer to session handle for tpipe returned by otma_alloc.

*lterm

Pointer to lterm name field. On input is passed to IMS. Will be updated on output to lterm field returned by IMS. Can be blank in both cases.

*modname

Pointer to MODname name field. On input is passed to IMS. Will be updated on output to MODname field returned by IMS. May be blank in both cases.

If the input modname is DFSM01, DFSMO2, or DFSM05, it will be treated as blanks.

*send_buffer

Pointer to the data to be sent to IMS. When a NULL is specified for the transaction parameter, the client code must provide the transaction name or command, and a blank, to the data in this buffer when sending to IMS.

*send_length

Length of send data.

*send_segment_list

An array of lengths of message segments to be sent to IMS. First element is count of following segment lengths. Optional: If a single segment is to be sent, either the first element or the address of the array can be zero.

*receive_buffer

Pointer to buffer to receive reply message from IMS.

*receive_length

Length of buffer available to receive message.

*receive_segment_list

An array to hold the number of segments sent by IMS. First element must be set as the number of elements in the array. Optional: If a single segment is to be received, either the first element or the address of the array can be zero. In which case all segments will be received contiguously without indication of segmentation boundaries.

*context_id

Null or Distributed Sync Point Context ID from z/OS® Resource Recovery Services.

For an authorized caller, OTMA C/I passes the Context ID directly to IMS and does not validate the Context ID data.
For an unauthorized caller, OTMA C/I invokes the CTXSWCH call to disassociate the token and to validate if the token is current for a task. When OTMA C/I receives a response from IMS, it switches the context back onto the task before returning control to the caller.

Output

*retrsn: Pointer to return code structure.
*ecb Event: Control block to be posted when the message exchange is complete.
*received_length: Field to receive length of data received to receive_buffer. Should be equal to the sum of the segment lengths.
*receive_segment_list: An array of lengths of message segments received from IMS. First element is count of following segment lengths and must be set by client to indicate maximum length of array. It will be modified by receive.
*error_message: Address of the pointer to the error message field. It is provided by the user to receive error or informational messages from IMS. If the post code returns a 20, then this field will contain data.

C-language function prototype

    otma_send_receive(
                 otma_anchor_t  *anchor,                  [in]
                 otma_retrsn_t  *retrsn,                  [out]
                 ecb_t          *ecb,                     [out]
 
                 sess_handle_t  *session_handle,          [in]
                 lterm_name_t   *lterm,                   [in/out]
                 mod_name_t     *modname,                 [in/out]
 
                 char           *send_buffer,             [in]
                 data_leng_t    *send_length,             [in]
                 ioseg_list_t   *send_seg_list,           [in]
 
                 char           *receive buffer,          [in]
                 data_leng_t    *receive_length,          [in]
                 data_leng_t    *received_length,         [out]
                 ioseg_list_t   *receive_segment_list,    [in/out]
                 context_t      *context_id,              [in]
 
                 char           *error_message);          [out]

Post codes

0: Normal completion.
8: No anchor/bad session handle/segment too large.
12: Send failed.
16: Receive has been canceled.
20: Error from IMS.

Return values (rc value)

The rc and reason are valid after ECB has been posted. For the complete description of each error, see IMS Version 15.2 Communications and Connections.

0: Normal completion.
8: No anchor/bad session handle/segment too large.
12: Send failed.
16: Receive has been canceled.
20: Error from IMS.