DEFINE ACTIVITY

Description

DEFINE ACTIVITY defines an activity to CICS business transaction services. It is used to add a child activity to the current activity.

The name of the program used in the execution of the new activity is taken either from the PROGRAM option, or, if PROGRAM is not specified, from the transaction definition pointed to by the TRANSID option.

The transaction attributes specified on the TRANSID and USERID options take effect when the activity is activated by a RUN command, but not if it is activated by a LINK command—see Context-switching.

BTS does not commit the addition of the activity until the requesting transaction has taken a successful syncpoint.

Options

ACTIVITY(data-value)

specifies the name (1–16 characters) of the new activity. The name must not be the name of another child activity of the activity that issues the DEFINE command.

The acceptable characters are A-Z a-z 0-9 $ @ # / % & ? ! : | " = ¬ , ; < > . - and _. 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.

ACTIVITYID(data-area)

returns the 52-character identifier assigned by CICS to the newly-defined activity. This identifier is unique across the sysplex.

EVENT(data-value)

specifies the name (1–16 characters) of the completion event for the activity. The completion event is sent to the activity's parent when the activity completes.

If EVENT is not specified, the completion event is given the same name as the activity itself.

The acceptable characters are A-Z a-z 0-9 $ @ # . - and _. 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.

PROGRAM(data-value)

specifies the name (1–8 characters) of the program for the activity being defined. If no program is specified, the name is taken from the TRANSID definition.

TRANSID(data-value)

specifies the name (1–4 characters) of the transaction under which the activity is to run, when it is activated by a RUN command.

Note: If the activity is activated by a LINK command, it is run under the TRANSID of the transaction that issues the LINK.

The transaction must be defined in the CICS region in which the process is running.

USERID(data-value)

specifies the userid (1–8 characters) under whose authority the activity is to run, when it is activated by a RUN command.

Note: If the activity is activated by a LINK command, it is run under the userid of the transaction that issues the LINK.

The value of this field is known as the defined userid.

If you omit USERID, the defined userid defaults to the userid under which the transaction that issues the DEFINE command is running—we can call this the command userid.

If USERID is specified, CICS performs (at define time) a surrogate security check to verify that the command userid is authorized to use the defined userid. Thus, if you specify USERID, you must authorize the command userid as a surrogate user of the defined userid.

Conditions

109 ACTIVITYERR

RESP2 values:

3

The name specified on the ACTIVITY option has already been used to name another child of the current activity.

111 EVENTERR

RESP2 values:

7

The completion event specified on the EVENT option has already been defined to the current activity's event pool.

16 INVREQ

RESP2 values:

4

The DEFINE ACTIVITY command was issued outside the scope of a currently-active activity.

17

The activity name specified on the ACTIVITY option, or the event name specified on the EVENT option, is invalid.

17 IOERR

RESP2 values:

29

The repository file is unavailable.

30

An input/output error has occurred on the repository file.

70 NOTAUTH

RESP2 values:

101

The user associated with the issuing task is not authorized to access the file associated with the BTS repository data set on which details of the activity are to be stored.

102

The user associated with the issuing task is not authorized as a surrogate of the defined userid specified on the USERID option.

28 TRANSIDERR

The transaction identifier specified on the TRANSID option is not defined to CICS.