Imagine a particular activity’s processing to be organized in two activations. The first activation sets up the environment. The second activation is started when a defined external interaction occurs.
To set up the environment to enable the second activation to take place, the first activation must:
The transaction that will start the second activation must use this identifier to gain access to the activity.
When the external interaction occurs--for example, a clerk enters some data at a terminal--the transaction that will start the second activation of the activity is invoked. This transaction must:
Figure 21 shows an activity that interacts with the outside world. The first activation sets up the environment, saves details of the activity identifier and input event to a VSAM file, and returns without completing. Some time later, a user starts the SPAR transaction from a terminal. The SPAR transaction retrieves the activity identifier and input event, issues an ACQUIRE ACTIVITYID command to gain access to the activity, supplies the activity with some input data, and re-activates it.
The Sale example application described in The Sale example application assumed that none of its later activities required human involvement. (The only child activity to require human involvement was the first (Order), and this was included as part of the initial terminal request to start the new business transaction.)
To demonstrate user-related activities, this section changes the logic and process flow of the Sale business transaction. Now, instead of the Invoice activity being started automatically after the Delivery activity has completed, it is not started until a user has notified the Sale transaction that the delivery has actually taken place. In addition, the Payment activity requires user input.
Figure 22 shows data flows in the Sale example application when the user actions described above are included.
Figure 23 shows, in COBOL pseudocode, the Sale root activity, with modifications for user-related activities. The changes are in bold text.
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 Delivery-Confirmed value 'Delivry-Confirmd'.
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 Confirm-Container pic x(16) value 'Confirm'.
01 Confirm-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 Order-Response
Perform Delivery-Activity
When Delivery-Complete
Perform Delivery-Response
Perform Delivery-Confirmation
When Delivery-Confirmed
Perform Confirm-Response
Perform Invoice-Activity
When Invoice-Complete
Perform Invoice-Response
Perform Payment-Activity
When Payment-Complete
Perform Payment-Response
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
.
Order-Response.
.
EXEC CICS CHECK ACTIVITY('Order') COMPSTATUS(status)
RESP(RC) RESP2(data-area) END-EXEC
.
If RC NOT = DFHRESP(NORMAL)
.
End-If.
.
If status NOT = DFHVALUE(NORMAL)
.
End-If.
.
.
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
.
Delivery-Response.
.
EXEC CICS CHECK ACTIVITY('Delivery') COMPSTATUS(status)
RESP(RC) RESP2(data-area) END-EXEC
.
If RC NOT = DFHRESP(NORMAL)
.
End-If.
.
If status NOT = DFHVALUE(NORMAL)
.
End-If.
.
.
Delivery-Confirmation.
.
EXEC CICS DEFINE ACTIVITY('Confirm')
TRANSID('SCON')
PROGRAM('CON001')
EVENT('Delivry-Confirmd')
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('Confirm') FROM(Delivery-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS RUN ACTIVITY('Confirm')
ASYNCHRONOUS
RESP(data-area) RESP2(data-area) END-EXEC
.
Confirm-Response.
.
EXEC CICS CHECK ACTIVITY('Confirm') COMPSTATUS(status)
RESP(RC) RESP2(data-area) END-EXEC
.
If RC NOT = DFHRESP(NORMAL)
.
End-If.
.
If status NOT = DFHVALUE(NORMAL)
.
End-If.
.
.
Invoice-Activity.
.
EXEC CICS DEFINE ACTIVITY('Invoice')
TRANSID('SINV')
EVENT('Invoice-Complete')
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS GET CONTAINER(Confirm-Container)
ACTIVITY('Confirm') INTO(Confirm-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS PUT CONTAINER(Confirm-Container)
ACTIVITY('Invoice') FROM(Confirm-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS RUN ACTIVITY('Invoice')
ASYNCHRONOUS
RESP(data-area) RESP2(data-area) END-EXEC
.
Invoice-Response.
.
EXEC CICS CHECK ACTIVITY('Invoice') COMPSTATUS(status)
RESP(RC) RESP2(data-area) END-EXEC
.
If RC NOT = DFHRESP(NORMAL)
.
End-If.
.
If status NOT = DFHVALUE(NORMAL)
.
End-If.
.
.
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
.
Payment-Response.
.
EXEC CICS CHECK ACTIVITY('Payment') COMPSTATUS(status)
RESP(RC) RESP2(data-area) END-EXEC
.
If RC NOT = DFHRESP(NORMAL)
.
End-If.
.
If status NOT = DFHVALUE(NORMAL)
.
End-If.
.
.
End-Process.
.
EXEC CICS RETURN ENDACTIVITY
RESP(data-area) RESP2(data-area) END-EXEC
End Program.
The main change to SAL002 is to introduce a new Confirm activity. The purpose of the Confirm activity is to confirm that delivery has taken place, before the Invoice activity is started. Confirmation requires user input. The following pseudocode creates the Confirm activity:
Delivery-Confirmation.
.
EXEC CICS DEFINE ACTIVITY('Confirm')
TRANSID('SCON')
EVENT('Delivry-Confirmd')
RESP(data-area) RESP2(data-area) END-EXEC
.
Because the Confirm activity will be executed asynchronously with the root activity, the EVENT option of DEFINE ACTIVITY is used to name the activity’s completion event as Delivry-Confirmd. CICS will reattach SAL002 when this event fires--that is, when the Confirm activity completes.
SAL002 places the input data for the Confirm activity into a data-container named Delivery, and issues the RUN command:
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('Confirm') FROM(Delivery-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS RUN ACTIVITY('Confirm')
ASYNCHRONOUS
RESP(data-area) RESP2(data-area) END-EXEC
Now SAL002 terminates, returning control to CICS. BTS will reattach the root activity only when the Confirm activity has completed.
The Confirm activity is used to notify the Sale business transaction that actual delivery has taken place. Figure 24 shows, in COBOL pseudocode, how program CON001 implements the Confirm user-related activity.
Identification Division.
Program-id. CON001
Environment Division.
Data Division.
Working-Storage Section.
01 RC pic s9(8) comp.
01 Event-Name pic x(16).
88 DFH-Initial value 'DFHINITIAL'
88 User-Ready value 'User-Ready'.
01 Data-Record.
03 User-Reference pic x(60).
03 Act-Id pic x(52).
03 Usr-Event pic x(16).
01 Data-Record-Len pic s9(8) comp.
.
01 Delivery-Container pic x(16) value 'Delivery'.
01 User-Container pic x(16) value 'User'.
01 Confirm-Container pic x(16) value 'Confirm'.
01 Delivery-Details.
03 Deliv-Details ..
03 User-Details ..
.
Linkage Section.
01 DFHEIBLK.
.
Procedure Division.
In-The-Beginning.
.
EXEC CICS RETRIEVE REATTACH EVENT(Event-Name)
RESP(RC) END-EXEC
.
If RC NOT = DFHRESP(NORMAL)
.
End-If.
.
Evaluate True
When DFH-Initial
Perform Initialization
When User-Ready
Perform Do-Work
When Other
.
End Evaluate.
.
EXEC CICS RETURN END-EXEC
.
Initialization.
.
EXEC CICS DEFINE INPUT EVENT(User-Ready)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS ASSIGN ACTIVITYID(Act-Id)
RESP(data-area) RESP2(data-area) END-EXEC
.
MOVE User-Ready TO Usr-Event
MOVE LENGTH OF Data-Record TO Data-Record-Len
.
EXEC CICS WRITE FILE('PENDING')
FROM(Data-Record) LENGTH(Data-Record-Len)
RIDFLD(User-Reference)
RESP(data-area) RESP2(data-area) END-EXEC
.
Do-Work.
.
Merge contents of two input data-containers into Delivery-Details
.
EXEC CICS GET CONTAINER(Delivery-Container)
INTO(Deliv-Details)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS GET CONTAINER(User-Container)
INTO(User-Details)
RESP(data-area) RESP2(data-area) END-EXEC
.
Set up the output data-container
.
EXEC CICS PUT CONTAINER(Confirm-Container)
FROM(Delivery-Details)
RESP(data-area) RESP2(data-area) END-EXEC
.
Clean up
.
EXEC CICS DELETE FILE('PENDING') RIDFLD(User-Reference)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS DELETE EVENT(User-Ready)
RESP(data-area) RESP2(data-area) END-EXEC
.
End the activity
.
EXEC CICS RETURN ENDACTIVITY
RESP(data-area) END-EXEC
.
End Program.
The Confirm activity is activated for the first time after SAL002 issues the RUN ACTIVITY command. On this initial activation, CON001:
Initialization.
.
EXEC CICS DEFINE INPUT EVENT(User-Ready)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS ASSIGN ACTIVITYID(Act-Id)
RESP(data-area) RESP2(data-area) END-EXEC
.
MOVE User-Ready TO Usr-Event
MOVE LENGTH OF Data-Record TO Data-Record-Len
.
EXEC CICS WRITE FILE('PENDING')
FROM(Data-Record) LENGTH(Data-Record-Len)
RIDFLD(User-Reference)
RESP(data-area) RESP2(data-area) END-EXEC
.
When the user is ready to confirm delivery, he or she invokes the USRX user-written transaction, which starts the USRCON program. USRCON executes outside the BTS environment--it is not part of the SAL001 process that contains the Confirm activity. Figure 25 shows, in COBOL pseudocode, the USRCON program.
Identification Division.
Program-id. USRCON.
Environment Division.
Data Division.
Working-Storage Section.
01 Pending-Record.
03 User-Reference pic x(60).
03 Act-Id pic x(52).
03 Usr-Event pic x(16).
.
01 User-Container pic x(16) value 'User'.
01 Confirmation-Details.
03 ..
.
Linkage Section.
01 DFHEIBLK.
.
01 DFHCOMMAREA.
.
Procedure Division using DFHEIBLK DFHCOMMAREA.
In-The-Beginning.
.
EXEC CICS SEND MAP('......') MAPSET('......') ...
.
EXEC CICS RECEIVE MAP('......') MAPSET('......) ..
.
Move ..unique.. to User-Reference.
.
EXEC CICS READ FILE('PENDING')
INTO(Pending-Record) RIDFLD(User-Reference)
RESP(data-area) RESP2(data-area) END-EXEC
.
. Acquire access to the Confirm activity of the SAL001 process
.
EXEC CICS ACQUIRE ACTIVITYID(Act-Id)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS PUT CONTAINER(User-Container)
ACQACTIVITY
FROM(Confirmation-Details)
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS RUN ACQACTIVITY
INPUTEVENT(Usr-Event)
SYNCHRONOUS
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS CHECK ACQACTIVITY COMPSTATUS(status)
RESP(RC) RESP2(data-area) END-EXEC
.
If RC NOT = DFHRESP(NORMAL)
.
End-If.
.
If status NOT = DFHVALUE(NORMAL)
.
End-If.
.
EXEC CICS RETURN
RESP(data-area) END-EXEC
.
End Program.
First, USRCON sends a map to the user’s screen and requests a unique reference. This must be the same as the key used by the CON001 program. It might be the customer reference or account number that has been used throughout to identify this instance of the Sale business transaction. However, it may need to be more specific than this. This would be the case if, for example:
Using the unique reference, USRCON selects the appropriate record from the pending file. It then uses the value of Act-Id to acquire access to the Confirm activity for the SAL001 instance of the Sale business transaction:
EXEC CICS ACQUIRE ACTIVITYID(Act-Id)
RESP(data-area) RESP2(data-area) END-EXEC
If the ACQUIRE command is successful, USRCON has access to the Confirm activity’s containers. USRCON creates a new data-container for the Confirm activity (User), and puts some confirmation details into it:
EXEC CICS PUT CONTAINER(User-Container)
ACQACTIVITY
FROM(Confirmation-Details)
RESP(data-area) RESP2(data-area) END-EXEC
The ACQACTIVITY option associates the new User container with the activity that USERCON has acquired.
Finally, USERCON re-activates the Confirm activity, checks whether it completes successfully, and ends:
.
EXEC CICS RUN ACQACTIVITY
INPUTEVENT(Usr-Event)
SYNCHRONOUS
RESP(data-area) RESP2(data-area) END-EXEC
.
EXEC CICS CHECK ACQACTIVITY COMPSTATUS(status)
RESP(RC) RESP2(data-area) END-EXEC
.
EXEC CICS RETURN
RESP(data-area) END-EXEC
.
The value of the INPUTEVENT option of the RUN command is the name of the input event previously defined by the Confirm activity. Note that although USRCON can check whether the activity it has acquired completes successfully, the execution of the CHECK ACQACTIVITY command does not cause CICS to delete the Confirm activity’s completion event. CICS deletes a completed activity’s completion event only after the execution of a CHECK ACTIVITY command issued by the activity’s parent.
The Confirm activity is activated for a second, and final, time due to the RUN ACQACTIVITY command issued by USRCON. On its second activation, CON001:
See Figure 24. Finally, CON001 does some clean-up work. It:
CICS notes completion of the Confirm activity and reattaches the root activity, because of the firing of the Delivry-Confirmd completion event defined by SAL002. After the execution of the CHECK ACTIVITY command issued by SAL002, CICS deletes the Confirm activity’s completion event.