DSNAIMS stored procedure

DSNAIMS is a stored procedure that allows DB2® applications to invoke IMS™ transactions and commands easily, without maintaining their own connections to IMS.

Begin general-use programming interface information.

DSNAIMS uses the IMS Open Transaction Manager Access (OTMA) API to connect to IMS and to execute the transactions.

Environment

DSNAIMS runs in a WLM-established stored procedures address space. DSNAIMS requires DB2 with RRSAF enabled and IMS version 7 or later with OTMA Callable Interface enabled.

To use a two-phase commit process, you must have IMS Version 8 with UQ70789 or later.

Authorization

To set up and run DSNAIMS, you must be authorized to perform the following steps:

Use the job DSNTIJIM to issue the CREATE PROCEDURE statement for DSNAIMS and to grant the execution of DSNAIMS to PUBLIC. DSNTIJIM is provided in the SDSNSAMP data set. You need to customize DSNTIJIM to fit the parameters of your system.
Ensure that the OTMA Callable Interface is initialized.

Syntax

The following syntax diagram shows the SQL CALL statement for invoking this stored procedure:

>>-CALL--SYSPROC.DSNAIMS--(--dsnaims-function,------------------>

>--+-dsnaims-2pc-+-,--xcf-group-name,--xcf-ims-name,------------>
   '-NULL--------'                                     

>--racf-userid,--+-racf-groupid-+-,--+-ims-lterm-+-,------------>
                 '-NULL---------'    '-NULL------'     

>--+-ims-modname-+-,--+-ims-tran-name-+-,--+-ims-data-in-+-,---->
   '-NULL--------'    '-NULL----------'    '-NULL--------'     

>--+-ims-data-out-+-,--+-otma-tpipe-name-+-,-------------------->
   '-NULL---------'    '-NULL------------'     

>--+-otma-dru-name-+-,--+-user-data-in-+-,--user-data-out,------>
   '-NULL----------'    '-NULL---------'                     

>--status-message,--return-code--)-----------------------------><

Option descriptions

dsnaims-function

A string that indicates whether the transaction is send-only, receive-only, or send-and-receive. Possible values are:

SENDRECV: Sends and receives IMS data. SENDRECV invokes an IMS transaction or command and returns the result to the caller. The transaction can be an IMS full function or a fast path transaction. SENDRECV does not support multiple iterations of a conversational transaction
SEND: Sends IMS data. SEND invokes an IMS transaction or command but does not receive IMS data. If result data exists, it can be retrieved with the RECEIVE function. A send-only transaction cannot be an IMS fast path transaction or a conversational transaction.
RECEIVE: Receives IMS data. The data can be the result of a transaction or a command that is initiated by the SEND function, or it can be an unsolicited output message from an IMS application. The RECEIVE function does not initiate an IMS transaction or command.

dsnaims-2pc

Specifies whether to use a two-phase commit process to perform the transaction syncpoint service. Possible values are Y or N. For N, commits and rollbacks that are issued by the IMS transaction do not affect commit and rollback processing in the DB2 application that invokes DSNAIMS. Furthermore, IMS resources are not affected by commits and rollbacks that are issued by the calling DB2 application. If you specify Y, you must also specify SENDRECV. To use a two-phase commit process, you must set the IMS control region parameter (RRS) to Y.

This parameter is optional. The default is N.

xcf-group-name

Specifies the XCF group name that the IMS OTMA joins. You can obtain this name by viewing the GRNAME parameter in IMS PROCLIB member DFSPBxxx or by using the IMS command /DISPLAY OTMA.

xcf-ims-name

Specifies the XCF member name that IMS uses for the XCF group. If IMS is not using the XRF or RSR feature, you can obtain the XCF member name from the OTMANM parameter in IMS PROCLIB member DFSPBxxx. If IMS is using the XRF or RSR feature, you can obtain the XCF member name from the USERVAR parameter in IMS PROCLIB member DFSPBxxx.

racf-userid

Specifies the RACF® user ID that is used for IMS to perform the transaction or command authorization checking. This parameter is required if DSNAIMS is running APF-authorized. If DSNAIMS is running unauthorized, this parameter is ignored, and the EXTERNAL SECURITY setting for the DSNAIMS stored procedure definition determines the user ID that is used by IMS.

racf-groupid

Specifies the RACF group ID that is used for IMS to perform the transaction or command authorization checking. This field is used for stored procedures that are APF-authorized. It is ignored for other stored procedures.

ims-lterm

Specifies an IMS LTERM name that is used to override the LTERM name in the I/O program communication block of the IMS application program.

This field is used as an input and an output field:

For SENDRECV, the value is sent to IMS on input and can be updated by IMS on output.
For SEND, the parameter is IN only.
For RECEIVE, the parameter is OUT only.

An empty or NULL value tells IMS to ignore the parameter.

ims-modname

Specifies the formatting map name that is used by the server to map output data streams, such as 3270 streams. Although this invocation does not have IMS MFS support, the input MODNAME can be used as the map name to define the output data stream. This name is an 8-byte message output descriptor name that is placed in the I/O program communication block. When the message is inserted, IMS places this name in the message prefix with the map name in the program communication block of the IMS application program.

For SENDRECV, the value is sent to IMS on input, and can be updated on output. For SEND, the parameter is IN only. For RECEIVE it is OUT only. IMS ignores the parameter when it is an empty or NULL value.

ims-tran-name

Specifies the name of an IMS transaction or command that is sent to IMS. If the IMS command is longer than eight characters, specify the first eight characters (including the "/" of the command). Specify the remaining characters of the command in the ims-tran-name parameter. If you use an empty or NULL value, you must specify the full transaction name or command in the ims-data-in parameter.

ims-data-in

Specifies the data that is sent to IMS. This parameter is required in each of the following cases:

Input data is required for IMS.
No transaction name or command is passed in ims-tran-name.
The command is longer than eight characters.

This parameter is ignored for RECEIVE functions.

ims-data-out

Data that is returned after successful completion of the transaction. This parameter is required for SENDRECV and RECEIVE functions. The parameter is ignored for SEND functions.

Start of change The length of ims-data-out is 32000 bytes. If the data that is returned from IMS is greater than the length of ims-data-out, the data is truncated. End of change

otma-tpipe-name

Specifies an 8-byte user-defined communication session name that IMS uses for the input and output data for the transaction or the command in a SEND or a RECEIVE function. If the otma_tpipe_name parameter is used for a SEND function to generate an IMS output message, the same otma_pipe_name must be used to retrieve output data for the subsequent RECEIVE function.

otma-dru-name

Specifies the name of an IMS user-defined exit routine, OTMA destination resolution user exit routine, if it is used. This IMS exit routine can format part of the output prefix and can determine the output destination for an IMS ALT_PCB output. If an empty or null value is passed, IMS ignores this parameter.

user-data-in

This optional parameter contains any data that is to be included in the IMS message prefix, so that the data can be accessed by IMS OTMA user exit routines (DFSYIOE0 and DFSYDRU0) and so that it can be tracked by IMS log records. IMS applications that run in dependent regions do not access this data. The specified user data is not included in the output message prefix. You can use this parameter to store input and output correlator tokens or other information. This parameter is ignored for RECEIEVE functions.

user-data-out

On output, this field contains the user-data-in in the IMS output prefix. IMS user exit routines (DFSYIOE0 and DFSYDRU0) can also create user-data-out for SENDRECV and RECEIVE functions. The parameter is not updated for SEND functions.

Start of change The length of user-data-out is 1022 bytes. If the data that is returned from IMS is greater than the length of user-data-out, the data is truncated. End of change

status-message

Indicates any error message that is returned from the transaction or command, OTMA, RRS, or DSNAIMS.

return-code

Indicates the return code that is returned for the transaction or command, OTMA, RRS, or DSNAIMS.

Examples

The following examples show how to call DSNAIMS.

Example 1: Sample parameters for executing an IMS command:

CALL SYSPROC.DSNAIMS("SENDRECV", "N", "IMS7GRP", "IMS7TMEM",
                     "IMSCLNM", "", "", "", "", "",
                     "/LOG Hello World.", ims_data_out, "", "", "",
                     user_out, error_message, rc)

Example 2: Sample parameters for executing an IMS IVTNO transaction:

CALL SYSPROC.DSNAIMS("SENDRECV", "N", "IMS7GRP", "IMS7TMEM",
                     "IMSCLNM", "", "", "", "", "",
                     "IVTNO     DISPLAY LAST1     "", ims_data_out
                     "", "", "", user_out, error_message, rc)

Example 3: Sample parameters for a send-only IMS transaction:

CALL SYSPROC.DSNAIMS("SEND", "N", "IMS7GRP", "IMS7TMEM",
                     "IMSCLNM", "", "", "", "", "",
                     "IVTNO     DISPLAY LAST1     "", ims_data_out,
                     "DSNAPIPE", "", "", user_out, error_message, rc)

Example 4: Sample parameters for a receive-only IMS transaction:

CALL SYSPROC.DSNAIMS("RECEIVE", "N", "IMS7GRP", "IMS7TMEM",
                     "IMSCLNM", "", "", "", "", "",
                     "IVTNO     DISPLAY LAST1     "", ims_data_out,
                     "DSNAPIPE", "", "", user_out, error_message, rc)

Connecting to multiple IMS subsystems with DSNAIMS

By default, DSNAIMS connects to only one IMS subsystem at a time. The first request to DSNAIMS determines to which IMS subsystem the stored procedure connects. DSNAIMS attempts to reconnect to IMS only in the following cases:

IMS is restarted and the saved connection is no longer valid.
WLM loads another DSNAIMS task.

To connect to multiple IMS subsystems simultaneously, perform the following steps:

Make a copy of the DB2-supplied job DSNTIJIM and customize it to your environment, as follows:
- Specify a separate WLM application environment name for each copy of the DSNTIJIM job that connects to a separate IMS subsystem.
- Change the procedure name from SYSPROC.DSNAIMS to another name, such as DSNAIMSB.
Do not change the EXTERNAL NAME option. Leave it as DSNAIMS.
Run the new job to create a second instance of the stored procedure.
To ensure that you connect to the intended IMS target, consistently use the XFC group and member names that you associate with each stored procedure instance. For example:
```
CALL SYSPROC.DSNAIMS("SENDRECV", "N", "IMS7GRP", "IMS7TMEM", ...) 
CALL SYSPROC.DSNAIMSB("SENDRECV", "N", "IMS8GRP", "IMS8TMEM", ...)
```

End general-use programming interface information.