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