otma_alloc API

Invocation

Called by the client in TCB mode.

Input

*anchor

Pointer to anchor word that was set up by otma_open.

*username

Pointer to 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.

*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 of the subsequent otma_send_receive API.

If this parameter is left blank, then the IMS transaction name or command must be specified (left aligned) in the beginning of the send buffer of the subsequent otma_send_receive API.

*prfname

Pointer to a string holding the RACF group name for transactions/commands.

*special_options

Pointer to the processing options for the subsequent otma_send_receive or otma_send_receivex API call. The supported processing options include:

Bit 0

SyncOnReturn - with this option, IMS is asked to process the message without the z/OS® Resource Recovery Services (RRS) context token; in this case, the user ID is obtained when RRS CTXRDTA is invoked.

Bit 1

SyncLevel1 - with this option, OTMA send_then_commit sync level 1 is used instead of sync level 0, which is the default for OTMA C/I. Refer to the DFSYCO header file for additional information.

Output

*retrsn

Pointer to return code structure.

*session_handle

Pointer to session handle that uniquely identifies the session for the subsequent otma_send_receive.

C-language function prototype

otma_alloc(
          otma_anchor_t  *anchor,           [in]
          otma_retrsn_t  *retrsn,           [out]
          sess_handle_t  *session_handle,   [out]
          otma_profile_t *special_options,  [in]
          tran_name_t    *transaction,      [in]
          racf_uid_t     *username,         [in]
         racf_prf_t     *prfname);          [in]

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

Success.

4

Session limit reached.

8

Null anchor.