otma_send_async API

The otma_send_async API is invoked to send a transaction or command to IMS.

Invocation

Called by the client in TCB mode.

Restriction: This API cannot be used to submit an IMS fast path transaction, a protected transaction (the transactions with z/OS® Resource Recovery Services context IDs), or an IMS conversational transaction. For these three types of transactions, use the otma_send_receive API instead.

Input

*anchor

Pointer to anchor word that was set up by otma_open.

*lterm

Pointer to lterm name field. If there is no input lterm, specify a NULL.

*modname

Pointer to MODname name field. If there is no input MODname, specify a NULL.

*otma_user_data

Pointer to the OTMA user data. This 1022-byte field is optional. The OTMA user data field can contain any data that is used to identify your input, or to correlate input with output. If a value is specified in this field, the data is sent to IMS. IMS user exits OTMAIOED and DFSYDRU0 can read or change the data. The data is returned if the otma_receive_async API with otma_user_data is issued.

If there is no OTMA user data, specify a NULL for this field.

*prfname

Pointer to string holding the RACF® group name for transaction commands. This parameter is optional. If there is no input RACF group name, specify a NULL.

*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. This parameter is required for multi-segment input messages. If specified, the first element needs to contain the count of total input segments. This field is optional for single segment input. If a single segment is to be sent, either the first element or the address of the array can be zero.

*special_options

Pointer to an area codifying non-standard options. Currently, no special options are supported. Specify a NULL for this parameter.

*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.

*transaction

Name of IMS transaction or command to be sent to IMS.

If the IMS command entered is longer than eight characters, the first eight characters of the command can be provided in this parameter. The rest of the characters of the command need to be provided in the beginning of the send buffer.

If NULL or blanks are specified in this parameter, OTMA C/I expects you to include the IMS transaction name or command in the beginning of the send buffer.

*username

Pointer to a string holding the RACF username for transaction/commands.

For calls from authorized programs, the input username is trusted and passed to IMS. For calls from unauthorized programs, OTMA C/I invokes a RACF call with the current accessor environment element (ACEE) context to obtain the username. The input username, if any, will be ignored. A NULL can be specified for callers from unauthorized programs.

Output

*ecb Event: Event control block to be posted when IMS receives or rejects the input.
*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.
*retrsn: Pointer to the return and reason code structure. If IMS OTMA rejects the input, the NAK code and its associated reason code are available in OTMA C/I reason codes 2 and 3. See IMS Version 15.3 Messages and Codes, Volume 2: Non-DFS Messages for an explanation of the NAK code.

C-language function prototype

    otma_send_async(
                 otma_anchor_t  *anchor,                  [in]
                 otma_retrsn_t  *retrsn,                  [out]
                 ecb_t          *ecb,                     [out]
 
                 tpipe_name_t   *tpipe_name,              [in]
                 tran_name_t    *transaction,             [in]
                 racf_uid_t     *username,                [in]
                 racf_prf_t     *prfname,                 [in]
                 lterm_name_t   *lterm,                   [in]
                 mod_name_t     *modname,                 [in]
                     otma_user_t    *otma_userdata,           [in] 
 
                 char           *send_buffer,             [in]
                 data_leng_t    *send_length,             [in]
                 data_leng_t    *send_segment_list[],     [in]
                 char           *error_message,           [out]
                 void           *special_options);        [in]

Post codes

0: Normal completion.
8: Invalid input.
12: Input failed.
16: Input canceled (IMS is down or OTMA is stopped).
20: Error or information message 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.3 Communications and Connections.

0: Normal completion.
8: No anchor/bad input.
12: Send failed.
16: Input canceled (IMS is down or OTMA is stopped).
20: Error or information message from IMS.