otma_receive_async API

The otma_receive_async API is invoked to receive an IMS output message or an unsolicited message. The caller provides the buffer definitions to receive the IMS message. When the IMS message arrives, the ECB is posted.

Invocation

Called by the client in TCB mode.

Input

*anchor: Pointer to anchor word that was set up by otma_open.
*tpipe_name: Pointer to OTMA tpipe name field. This name must be different from the tpipe name specified for the otma_create and otma_open APIs.
receive_length: Length of buffer available to receive message.

Output

*ecb Event: Event control block to be posted when IMS receives the reply.
*error_message: Address of the pointer to the error message field. You provide this address to receive error or informational messages from IMS. If the post code returns a 20, then this field will contain data.
*lterm: Pointer to lterm name field. Can be updated with lterm value that is returned by IMS.
*modname: Pointer to MODname name field. Can be updated with MODname value that is returned by IMS.
*otma_user_data: Pointer to the OTMA user data. This 1022-byte field is optional. If the field is specified and IMS returns the OTMA user data, the data is passed back to the caller.
The OTMA user data received is either provided in the otma_send_async API or created by the IMS DRU exit DFSYDRU0.
*receive_buffer: Pointer to buffer to receive reply message from IMS.
*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. The client must set the first element to indicate the maximum number of message segments that can be received. After all the segments are received, the first array element indicates the actual number of segments received, and the rest of the array elements indicate the length of each segment received.
*retrsn: Pointer to the return and reason code structure.
*special_options: Pointer to an area codifying non-standard options. Currently, no special are options supported. Specify a NULL for this parameter.

C-language function prototype

    otma_receive_async(
                 otma_anchor_t  *anchor,                  [in]
                 otma_retrsn_t  *retrsn,                  [out]
                 ecb_t          *ecb,                     [out]
 
                 tpipe_name_t   *tpipe_name,              [in]
                 lterm_name_t   *lterm,                   [out]
                 mod_name_t     *modname,                 [out]
                     otma_user_t    *otma_userdata,           [out] 
 
                 char           *receive_buffer,          [out]
                 data_leng_t    *receive_length,          [in]
                 data_leng_t    *received_length,         [out]
                 data_leng_t    *receive_segment_list[],  [in/out]

                 void           *special_options);        [in]

Post codes

0: Normal completion.
12: Receive failed.

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.4 Communications and Connections.

0: Normal completion.
8: No anchor/bad session handle/segment too large.
12: Send failed.