The SAL001 program starts a new instance of the Sale business transaction by starting the SAL002 program, running under the transid SALE. SAL002 implements a root activity that manages the inter-relationship, ordering, and execution of the child activities that make up the Sale business transaction.
A root activity program such as SAL002 is designed to be reattached by CICS® business transaction services when events in which it is interested are triggered. The activity program determines which of the possible events caused it to be attached and what to do as a result. A typical sequence (somewhat simplified) is:
Thus, even though the root activity is not initiated from a terminal, you could think of its style as being "pseudoconversational".
Figure 13 shows, in COBOL pseudocode, the Sale root activity program, SAL002.
Identification Division.
Program-id. SAL002.
Environment Division.
Data Division.
Working-Storage Section.
01 RC pic s9(8) comp.
01 Process-Name pic x(36).
01 Event-Name pic x(16).
88 DFH-Initial value 'DFHINITIAL'.
88 Delivery-Complete value 'Delivry-Complete'.
88 Invoice-Complete value 'Invoice-Complete'.
88 Payment-Complete value 'Payment-Complete'.
01 Sale-Container pic x(16) value 'Sale'.
01 Order-Container pic x(16) value 'Order'.
01 Order-Buffer pic x(..).
01 Delivery-Container pic x(16) value 'Delivery'.
01 Delivery-Buffer pic x(..).
01 Invoice-Container pic x(16) value 'Invoice'.
01 Invoice-Buffer pic x(..).
Linkage Section.
01 DFHEIBLK.
.
Procedure Division.
Begin-Process.
.
EXEC CICS RETRIEVE REATTACH EVENT(Event-Name)
RESP(RC) END-EXEC
.
If RC NOT = DFHRESP(NORMAL)
.
End-If.
.
Evaluate True
When DFH-Initial
Perform Initial-Activity
Perform Order-Activity
Perform Delivery-Activity
When Delivery-Complete
Perform Invoice-Activity
When Invoice-Complete
Perform Payment-Activity
When Payment-Complete
Perform End-Process
When Other
.
End Evaluate.
.
EXEC CICS RETURN END-EXEC
.
Initial-Activity.
.
EXEC CICS ASSIGN PROCESS(Process-Name)
RESP(data-area) RESP2(data-area) END-EXEC
.
Order-Activity.
.
EXEC CICS DEFINE ACTIVITY('Order')
TRANSID('SORD')
PROGRAM('ORD001')
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS PUT CONTAINER(Sale-Container)
ACTIVITY('Order') FROM(Process-Name)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS LINK ACTIVITY('Order')
RESP(data-area) RESP2(data-area) END-EXEC
.
Delivery-Activity.
.
EXEC CICS DEFINE ACTIVITY('Delivery')
TRANSID('SDEL')
EVENT('Delivry-Complete')
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS GET CONTAINER(Order-Container)
ACTIVITY('Order') INTO(Order-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS PUT CONTAINER(Order-Container)
ACTIVITY('Delivery') FROM(Order-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS RUN ACTIVITY('Delivery')
ASYNCHRONOUS
RESP(data-area) RESP2(data-area) END-EXEC
.
Invoice-Activity.
.
EXEC CICS DEFINE ACTIVITY('Invoice')
TRANSID('SINV')
EVENT('Invoice-Complete')
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS GET CONTAINER(Delivery-Container)
ACTIVITY('Delivery') INTO(Delivery-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS PUT CONTAINER(Delivery-Container)
ACTIVITY('Invoice') FROM(Delivery-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS RUN ACTIVITY('Invoice')
ASYNCHRONOUS
RESP(data-area) RESP2(data-area) END-EXEC
.
Payment-Activity.
.
EXEC CICS DEFINE ACTIVITY('Payment')
TRANSID('SPAY')
EVENT('Payment-Complete')
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS GET CONTAINER(Invoice-Container)
ACTIVITY('Invoice') INTO(Invoice-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS PUT CONTAINER(Invoice-Container)
ACTIVITY('Payment') FROM(Invoice-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS RUN ACTIVITY('Payment')
ASYNCHRONOUS
RESP(data-area) RESP2(data-area) END-EXEC
.
End-Process.
.
EXEC CICS RETURN ENDACTIVITY
RESP(data-area) RESP2(data-area) END-EXEC
End Program.
The following discussion steps through the SAL002 pseudocode shown in Figure 13:
EXEC CICS RETRIEVE REATTACH EVENT(Event-Name)
RESP(data-area) RESP2(data-area) END-EXEC
The first time an activity is started during a process, the event returned is the system event DFHINITIAL. This tells the activity that it should perform any initial housekeeping.
In this example, CICS initially invokes the SAL002 root activity as a result of the RUN ACQPROCESS command issued by the SAL001 program. As part of its initial housekeeping, SAL002 uses the EXEC CICS ASSIGN PROCESS command to discover the name of this instance of the business transaction (process). (The name of the process instance was assigned by the DEFINE PROCESS command, and might be, for example, a customer reference or account number.)
EXEC CICS DEFINE ACTIVITY('Order')
TRANSID('SORD')
PROGRAM('ORD001')
RESP(data-area) RESP2(data-area) END-EXEC
The DEFINE ACTIVITY command requests CICS business transaction services to add an activity to a business transaction (process). In this example, SAL002 adds an activity called Order to the Sale business transaction. It is implemented by program ORD001. The TRANSID option specifies that, if the Order activity is run in its own unit of work, it will run under transaction identifier SORD.
EXEC CICS PUT CONTAINER(Sale-Container)
ACTIVITY('Order') FROM(Process-Name)
RESP(data-area) RESP2(data-area) END-EXEC
The input data is placed in a data-container named Sale (the value of the variable Sale-Container). The ACTIVITY option of PUT CONTAINER associates the Sale data-container with the Order activity.
Two or more activities can each have a data-container named, for example, Order.
The data put into the Sale data-container is the process name--that is, the unique reference that identifies this instance of the Sale business transaction. The process name in this case is the customer reference or account number specified on the DEFINE PROCESS command in SAL001.
EXEC CICS LINK ACTIVITY('Order')
RESP(data-area) RESP2(data-area) END-EXEC
The LINK ACTIVITY command causes the ORD001 program to be executed synchronously with SAL002 and to be included as part of the current unit of work. The TRANSID option of the DEFINE ACTIVITY command is ignored--LINK ACTIVITY causes the Order activity to run under the requestor’s transaction identifier, SALE.
The Order activity collects order details from the terminal operator and validates them. The ORD001 program converses with the terminal operator until the order is accepted. It then returns the validated details in an output data-container.
EXEC CICS DEFINE ACTIVITY('Delivery')
TRANSID('SDEL')
EVENT('Delivry-Complete')
RESP(data-area) RESP2(data-area) END-EXEC
The Delivery activity is to be executed asynchronously with the root activity. When an activity completes, its completion event fires. The EVENT option names the Delivery activity’s completion event as Delivry-Complete, and thus defines it. Defining the event allows it to be referenced and checked for.
CICS reattaches an activity on the firing of any event, other than a sub-event, that is in its event pool. (An activity’s event pool contains events that have been defined to the activity, plus the DFHINITIAL system event.) Thus, the SAL002 root activity will be reattached when the Delivery activity’s completion event (Delivry-Complete) fires.
For child activities like the Order activity, that will always be executed synchronously with the parent, the EVENT option is not often used. Normally, the firing of a synchronous activity’s completion event does not cause the parent to be reattached, because the event is deleted (by a CHECK ACTIVITY command) during the parent’s current activation. Therefore the event never needs to be tested for by name, among several other possible reattachment events.
The CHECK ACTIVITY command is described in Dealing with BTS errors and response codes.
EXEC CICS GET CONTAINER(Order-Container)
ACTIVITY('Order') INTO(Order-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
EXEC CICS PUT CONTAINER(Order-Container)
ACTIVITY('Delivery') FROM(Order-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
Here, the GET and PUT commands are used to transfer data from the Order activity’s output data-container to the Delivery activity’s input data-container (both of which are named Order). Note that these are different data-containers--although they share the same name, they are associated with different activities.
EXEC CICS RUN ACTIVITY('Delivery')
ASYNCHRONOUS
RESP(data-area) RESP2(data-area) END-EXEC
Because RUN rather than LINK is used, the Delivery activity will be executed as a separate unit of work, and under the transaction identifier specified on the TRANSID option of the DEFINE ACTIVITY command. (The RUN command always activates the specified process or activity in a new unit of work.) Because the ASYNCHRONOUS option is used, the Delivery activity will be executed asynchronously with SAL002, and will start only if the current unit of work completes successfully.
After the CICS syncpoint, the menu of business transactions is redisplayed on the user’s terminal, ready for further selection. The remaining activities will be completed, without reference to the terminal user, under the control of CICS business transaction services. The SAL002 program no longer exists in memory, and the existence of this instance of the Sale business transaction is known only to BTS.
CICS business transaction services start the Delivery activity (SDEL) as requested. (BTS participates as a resource manager for the transaction.) On completion of the Delivery activity, BTS reactivates the Sale root activity--that is, the SAL002 program under the transaction identifier SALE.
As with the Delivery activity, SAL002 sets the Invoice activity’s parameters, input data, and execution options before requesting the activity to be run. It then issues an EXEC CICS RETURN command and becomes dormant, waiting to be reactivated for this instance of the Sale business transaction.