RUN TRANSID

Description

RUN TRANSID starts a task on the local system, optionally passing it a channel. The started task (child task) runs asynchronously with the starting task (parent task), and runs with the same security context as the parent task. The parent task uses the channel to pass input data to the child task. The parent task will get a response back when the API command FETCH CHILD or FETCH ANY is issued.

When a child task is started using EXEC CICS RUN TRANSID, it inherits the security context of the parent task. The security context is checked when RUN TRANSID is issued, and checked again at child task attach. If the child task does not have the authorization to run within the given context, it will abend with code AASA.

If the transaction (specified by TRANSID) is defined with DYNAMIC(YES), this option is ignored and no routing decision is made.

Options

CHANNEL(name)

Specifies the name (1 - 16 characters) of a channel that is to be made available to the child task. The acceptable characters are A-Z a-z 0-9 $ @ # ./-_ % & ? ! : | " = ¬ , ; < >. Leading and embedded blank characters are not permitted. If the name supplied is less than 16 characters, it is padded with trailing blanks up to 16 characters. If the channel does not exist, it is created. This new channel remains in scope until the link level changes. For more information about channel scope, see The scope of a channel.

Channel names are always in EBCDIC. The set of allowed characters for channel names, as listed earlier, includes some characters that do not have the same representation in all EBCDIC code pages. Therefore, if channels are to be shipped between regions, it is advisable to restrict the characters used to name them to A-Z a-z 0-9 & : = , ; < > . - and _.

You can specify the channel name DFHTRANSACTION to use a transaction channel. A transaction channel does not go out of scope when the link level changes: it is always accessible in the transaction. For more information, see Channels and containers.

The program that issues the RUN TRANSID command can do one of the following:

• Create the channel before issuing the RUN TRANSID command, by using one or more PUT CONTAINER CHANNEL or PUT64 CONTAINER commands.
• Specify its current channel, by name.
• Name a channel that does not currently exist. A new empty channel is created.

The child task is given a copy of the channel's containers (and the data that they contain). The copy is made when the RUN TRANSID command is issued.

CHILD(data-area)

Specifies a 16-character binary data area, into which CICS® will place the child token that represents the child task. The child token is used to refer to the child task in order to get a response back from it through an API command such as FETCH CHILD.

TRANSID(name)

Specifies the symbolic identifier (1–4 characters) of the local transaction to be started as the result of a RUN command.

Conditions

122 CHANNELERR

RESP2 values:

1

The channel specified on the CHANNEL option contains an incorrect character or combination of characters.

16 INVREQ

RESP2 values:

17

The started transaction is not shutdown-enabled, and the CICS region is in the process of shutting down. INVREQ also occurs (RESP2 not set) if the RUN command is not valid for processing by CICS.

19

RUN TRANSID was issued during transaction termination.

28 TRANSIDERR

RESP2 values:

1

The transaction identifier specified in a RUN TRANSID command is not defined to CICS.

11

The specified transaction is defined as remote.

70 NOTAUTH

RESP2 values:

101

The user associated with the issuing task is not authorized to run the child task.

84 DISABLED

RESP2 values:

50

The specified transaction is disabled.