Execute a CICS business transaction services process or activity
synchronously or asynchronously, with context-switching.
RUN
>>-RUN--+-ACTIVITY(data-value)-+-------------------------------->
+-ACQACTIVITY----------+
'-ACQPROCESS-----------'
>--+-SYNCHRONOUS--------------------------------+--------------->
'-ASYNCHRONOUS--+--------------------------+-'
'-FACILITYTOKN(data-value)-'
>--+------------------------+----------------------------------><
'-INPUTEVENT(data-value)-'
Conditions: ACTIVITYBUSY, ACTIVITYERR, EVENTERR, INVREQ, IOERR,
LOCKED, NOTAUTH, PROCESSBUSY, PROCESSERR
Description
RUN executes a CICS business
transaction services process or activity synchronously or asynchronously with
the requestor, with context-switching. The process or activity must previously
have been defined to BTS.
RUN causes BTS to attach the process or activity,
by sending it an input event. If the process or activity is in its initial
state—that is, if this is the first time it is to be run, or if the activity
has been reset by a RESET ACTIVITY command—CICS® sends it the DFHINITIAL system event.
If the process or activity is dormant—that is, waiting for a reattachment
event to occur—the input event must be specified on the INPUTEVENT option.
If
the process or activity is in any mode other than INITIAL or DORMANT, it cannot
be run.
The SYNCHRONOUS and ASYNCHRONOUS options allow you to specify
whether the process or activity should be executed synchronously or asynchronously
with the requestor.
Context-switching
When
a process or activity is activated by a RUN command, it is run:
- In a separate unit of work from the requestor.
- With the transaction attributes (TRANSID and USERID) specified on the
DEFINE PROCESS or DEFINE ACTIVITY command.
In other words, a
context-switch takes place. The relationship
of the process or activity to the requestor is as between separate transactions,
except that:
- Data can be passed between the two units of work
- The start and finish of the activity is related to the requestor's syncpoints.
To run a process or activity without context-switching—that
is, in the same UOW and with the same TRANSID and USERID attributes as the
requesting transaction—use the LINK ACQPROCESS, LINK ACQACTIVITY, or LINK
ACTIVITY command. This is possible only if the process or activity is run
synchronously.
If the ability to isolate a failure is more important
than performance, use RUN SYNCHRONOUS rather than LINK.
Activities
The only activities a program can run
are as follows:
- If it is running as the activation of an activity, its own child activities.
It can run several of its child activities within the same unit of work.
- The activity it has acquired, by means of an ACQUIRE ACTIVITYID command,
in the current unit of work.
To check the response from the activity, the CHECK ACTIVITY command
must be used. This is because the response to the request to run the activity
does not contain any information about the success or failure of the activity
itself—only about the success or failure of the request to run it.
Typically,
if the activity is run synchronously, the CHECK command is issued immediately
after the RUN command. If it is run asynchronously, the CHECK command could
be issued:
- When the activity's parent is reattached due to the firing of the activity's
completion event
- When the requestor is reattached due to the expiry of a timer.
The activity's completion event is one of the following:
- The event named on the EVENT option of the DEFINE command for the activity.
- If the DEFINE command did not specify a completion event, an event of
the same name as the activity.
To retry an activity:
- Issue a RESET ACTIVITY command to reset the activity to its initial state.
- Issue a RUN command.
Processes
The only process that a program can run
is the one that it has acquired in the current unit of work—see Acquiring processes
and activities .
To check the response from the process, the CHECK ACQPROCESS command
must be used. This is because the response to the request to run the process
does not contain any information about the success or failure of the process
itself—only about the success or failure of the request to run it.
Typically,
if the process is run synchronously, the CHECK command is issued immediately
after the RUN command. If the process is run asynchronously, the CHECK command
could be issued when the requestor is reattached due to the expiry of a timer.
Options
- ACQACTIVITY
- specifies
that the activity to be run is the one that the current unit of work has acquired
by means of an ACQUIRE ACTIVITYID command.
- ACQPROCESS
- specifies
that the process currently acquired by the requestor is to be run.
- ACTIVITY(data-value)
- specifies
the name (1–16 characters) of the activity to be run. The name must be that
of a child of the current activity.
- ASYNCHRONOUS
- specifies
that the process or activity is to be executed asynchronously with the requestor.
- FACILITYTOKN(data-value)
- specifies
an 8-byte bridge facility token.
This option applies when a BTS client
activity runs a 3270-based pseudoconversational transaction. To ensure that
the existing bridge facility is reused for the next transaction in the pseudoconversation,
the client passes its token to the next child activity. This is explained
in more detail in Reusing existing 3270 applications in BTS .
- INPUTEVENT(data-value)
- specifies
the name (1–16 characters) of the event that causes the process or activity
to be attached.
You must not specify this option if the process
or activity is in its initial state; that is, if this is the first time it
is to be run, or if the activity has been reset by a RESET ACTIVITY command.
In this case, CICS sends the process or activity the DFHINITIAL system event.
You must specify
this option if the process or activity is not in its initial state; that is,
if it has been activated before, and has not been reset by a RESET ACTIVITY
command.
If you specify INPUTEVENT, for the RUN command to be successful
the process or activity to be attached must have defined the named event as
an input event.
If you issue multiple asynchronous RUN commands against
the same activity within the same unit of work:
- If you specify the same input event, each RUN command after the
first fails.
- If you specify different input events, the activity may or may
not be invoked as many times as the number of RUN requests—the only guarantee
is that it will be invoked at least once. For example, if , within the same
unit of work, you issue five asynchronous RUN requests for the same activity,
specifying different input events, the activity might be invoked twice. At
the first invocation, three input events might be presented, and at the second
two.
- SYNCHRONOUS
- specifies
that the process or activity is to be executed synchronously with the requestor.
Conditions
- 107 ACTIVITYBUSY
- RESP2
values:
- 19
- The request timed out. It may be that another task using this activity-record
has been prevented from ending.
- 109 ACTIVITYERR
- RESP2
values:
- 8
- The activity named on the ACTIVITY option could not be found.
- 14
- The activity to be run is not in INITIAL or DORMANT mode.
- 27
- The activity named on the RUN SYNCHRONOUS command has abended.
- 111 EVENTERR
- RESP2
values:
- 7
- The event named on the INPUTEVENT option has not been defined by the activity
or process to be run as an input event; or its fire status is FIRED.
- 16 INVREQ
- RESP2
values:
- 4
- The ACTIVITY option was used to name a child activity, but the command
was issued outside the scope of a currently-active activity.
- 15
- The task that issued the RUN ACQPROCESS command has not defined or acquired
a process.
- 20
- The SYNCHRONOUS option was used, but the activity to be run is suspended.
- 24
- The ACQACTIVITY option was used, but the unit of work that issued the
request has not acquired an activity.
- 28
- CICS could not attach the transaction associated with the process or activity
to be run. (This response occurs only on RUN SYNCHRONOUS commands.)
- 32
- The SYNCHRONOUS option was used, but the transaction associated with the
process or activity to be run is defined as remote. You cannot run a process
or activity synchronously if its transaction is remote.
- 40
- The program that implements the process or activity to be run is remote.
- 17 IOERR
- RESP2
values:
- 29
- The repository file is unavailable.
- 30
- An input/output error has occurred on the repository file.
- 100 LOCKED
- The
request cannot be performed because a retained lock exists against the relevant
record on the repository file.
- 70 NOTAUTH
- RESP2
values:
- 101
- The user associated with the issuing task is not authorized to run the
process or activity.
- 106 PROCESSBUSY
- RESP2
values:
- 13
- The request timed out. It may be that another task using this process-record
has been prevented from ending.
- 108 PROCESSERR
- RESP2
values:
- 6
- You cannot run the current process.
- 9
- The process-type could not be found.
- 14
- The process to be run is not in INITIAL or DORMANT mode.
- 27
- The process named on the RUN SYNCHRONOUS command has abended.