Acquiring an activity

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:

  1. Define an input event that depicts the external interaction. The activity cannot now complete until this input event has been dealt with.
  2. Obtain an activity identifier that uniquely identifies this activity-instance. To do this, it issues an ASSIGN command.

    The transaction that will start the second activation must use this identifier to gain access to the activity.

  3. Save details of the activity identifier and input event to a suitable medium (for example, a VSAM file or MQ queue) to which the transaction that will start the second activation has access.
  4. Return without completing. (That is, issue an EXEC CICS® RETURN command on which the ENDACTIVITY option is omitted. Because of the user event in its event pool--the input event that it has defined--the activity does not complete but becomes dormant.)

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:

  1. Retrieve the activity identifier and input event
  2. Gain access to the activity--by issuing an ACQUIRE ACTIVITYID command that specifies the activity identifier.
  3. Re-activate the activity, and tell it why it is being activated--by issuing a RUN ACQACTIVITY command that specifies the input event.

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.

Figure 21. Acquiring an activity. On its initial activation, the activity sets up the environment and returns without completing. Some time later, the SPAR transaction is started from a terminal; it retrieves the activity identifier and input event, issues an ACQUIRE ACTIVITYID command to gain access to the activity, and re-activates it.
 The picture shows two activations of an activity and a separate transaction, SPAR, that is started from a user terminal. On its first activation, the activity defines an input event, obtains an activity identifier, saves the name of the input event and the activity identifier to a file, and returns without completing. The sequence of commands it issues are: DEFINE INPUT EVENT, ASSIGN ACTIVITY, WRITE FILE, and RETURN. Some time later, the SPAR transaction is started from a user terminal. It retrieves the activity identifier and input event, issues an ACQUIRE ACTIVITYID command to gain access to the activity, and re-activates it. The sequence of commands it issues are: READ FILE, ACQUIRE ACTIVITYID, PUT CONTAINER() ACQACTIVITY FROM(), RUN ACQACTIVITY INPUTEVENT(), and RETURN.

A user-related example

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.

Data flow

Figure 22 shows data flows in the Sale example application when the user actions described above are included.

Figure 22. Data flow in the Sale example application, showing user-related activities. (The root activity is not shown.) Changes from the basic Sale example described in The Sale example application are shown in bold.
 The picture shows the data flows described in the list below. A rectangle represents the Sale business transaction. The rectangle contains several smaller rectangles, representing the Order, Delivery, Confirm, Invoice, and Payment child activities. Another rectangle, outside the Sale transaction, represents the Menu transaction. Input and output data flows are represented by arrows.   The Menu transaction collects input from the user. The output from the Menu transaction becomes the input to the Order activity. The Order activity collects further input from the user. The output from the Order activity becomes the input to the Delivery activity. The output from the Delivery activity becomes the input to the Confirm activity. The output from the Confirm activity (which requires user input) becomes the input to the Invoice activity. The output from the Invoice activity becomes the input to the Payment activity.

  1. User data collected after the user selects the Sale menu option is used as input to the Order activity.
  2. The user data collected by the Order activity is used as input to the Delivery activity.
  3. The output data produced by the Delivery activity is used as input to the Confirm activity.
  4. The output produced by the Confirm activity (which requires user input) is used as input to the Invoice activity.
  5. The output produced by the Invoice activity is used as input to the Payment activity.

The root activity

Figure 23 shows, in COBOL pseudocode, the Sale root activity, with modifications for user-related activities. The changes are in bold text.

Figure 23. The SAL002 root activity program, with user-related modifications highlighted
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.

Implementation of a user-related activity

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.

Figure 24. Pseudocode for the CON001 program, that implements the Confirm 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 initial activation of the Confirm activity

The Confirm activity is activated for the first time after SAL002 issues the RUN ACTIVITY command. On this initial activation, CON001:

  1. Defines an input event for which the activity may subsequently be activated.
  2. Obtains the activity identifier which uniquely identifies this activity-instance.
  3. Saves the name of the input event and the activity identifier in a pending file. The record in the pending file is given a key--which could, for instance, be the customer reference number which has been used throughout to identify this instance of the Sale business transaction.
  4. Returns without completing.

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
    .
The USRX user transaction

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.

Figure 25. Pseudocode for the USRCON program, that implements the USRX transaction
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 second activation of the Confirm activity

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:

  1. Establishes why it has been invoked.
  2. Merges the contents of the two input data-containers, Delivery and User, supplied by SAL002 and USRCON respectively.
  3. Stores the updated delivery details into the Confirm activity’s output data-container (Confirm).

See Figure 24. Finally, CON001 does some clean-up work. It:

  1. Deletes the entry from the pending file.
  2. Deletes the input event defined on its previous invocation. (This is not strictly necessary, because the event would be deleted automatically by CICS on the execution of the RETURN ENDACTIVITY command that follows.)
  3. Issues an EXEC CICS RETURN ENDACTIVITY command to indicate that its processing is complete; the Confirm activity’s completion event (Delivry-Confirmed) is fired.

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.

Related concepts
Introduction
Using the BTS API to write business applications
The Sale example application
Related tasks
Using client/server processing
Transferring data to asynchronous activations
Related reference
Overview of BTS API commands
BTS application programming commands
[[ Contents Previous Page | Next Page Index ]]