The root activity

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:

  1. The root activity requests BTS to run a child activity (possibly several child activities), and to notify it when the child has completed.
  2. The root activity "sleeps" while waiting for the child activity to complete.
  3. BTS reattaches the root activity because the child activity has completed.
  4. The root activity requests the next child activity to run.
  5. Steps 1 through 4 are repeated until the business transaction is complete.

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.

Figure 13. Pseudocode for SAL002, the root activity program for the Sale business transaction
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:

  1. The root activity determines what event caused it to be attached by issuing the following command:
        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.)

  2. The root activity creates its first child activity, which in this case is the Order activity:
         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.

  3. When the Order activity has been added, SAL002 uses the PUT CONTAINER command to provide it with some input data.
        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.

    Note:
    An activity can have many data-containers associated with it. A data-container is associated with an activity simply by being named on a command (such as PUT CONTAINER) that specifies the 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.

  4. SAL002 requests BTS to start the Order activity:
        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.

  5. When the Order activity completes, SAL002 creates the Delivery activity:
         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.

    Note:
    All child activities have completion events, that fire when the activities complete. If the EVENT option of DEFINE ACTIVITY is not used, CICS gives the completion event the same name as the activity itself.

    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.

  6. SAL002 makes the data returned by the Order activity available to the Delivery activity:
        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.

  7. SAL002 requests BTS to start the Delivery activity:
        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.

  8. SAL002 issues an EXEC CICS RETURN command. Because there is a user event in its event pool--the completion event for the Delivery activity--the root activity does not complete but becomes dormant. Control is returned to SAL001, then to MNU001, and finally to CICS. CICS takes a syncpoint and commits the following:

    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.

  9. The SAL002 program is entered at the top again, and so determines what event caused it to be reactivated by issuing the RETRIEVE REATTACH EVENT command. This time, however, the event returned is Delivry-Complete. Having established which child activity has completed, SAL002 determines that the next activity to be started is the Invoice activity.

    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.

  10. The pattern implied in step 9 is repeated until the Payment activity completes, at which point the Sale business transaction is complete. SAL002 issues an EXEC CICS RETURN command on which the ENDACTIVITY option is specified. This indicates to CICS that the root activity’s processing is complete, and that it no longer wants to be reactivated if defined or system events occur. The business transaction ends.

Related concepts
Overview of the Sale application
The initial request
Transferring input and output data
Using the BTS API to write business applications
Related reference
Overview of BTS API commands
BTS application programming commands
[[ Contents Previous Page | Next Page Index ]]