Service flows with shared user IDs

Stabilized feature: Service Flow Runtime and Service Flow Modeler capability in IBM Developer for z/OS 14.2.3 are stabilized. Consider exposing and orchestrating applications as API services by using z/OS Connect Enterprise Edition or CICS® web services, or by writing web applications in Java™ or Node.js. See also Stabilization notices and discontinued functions.

If you have shared user IDs in your FEPI service flows, they affect the way the flow navigator uses logical units to establish connections and sessions to CICS regions and applications. You are recommended not to use shared user IDs in your service flows.

A shared user ID is not associated with a single user, but instead more than one user at a time can use it. Logical units (LUs) are required to establish connections and sessions to CICS regions and applications for FEPI server adapters. Assigning logical units to shared user IDs means the following:

  • Logical units (LUs) in the same FEPI pool are assigned to a shared user ID for the duration of the service flow request. This might involve running many FEPI server adapters as part of the service flow.
  • Many service flows might be running concurrently in the CICS region using the same shared user ID. Each invocation of a service flow runs in a separate BTS process.
  • Logical units might remain signed on and in session for a shared user ID across many invocations of subsequent service flows that might have FEPI server adapters. The local unit can remain assigned to the shared user ID in the connection file after a service flow has completed.

In a configuration where the user ID is shared, CICS SFR ensures that logical units in the same FEPI pool are assigned uniquely to the shared user ID. A unique tag is added for each logical unit in the alternate connection file DFHMAC1F. This unique tag comprises the CICS applid and the EIBTASKN of DFHMADPL. The processing is as follows:

  1. In the first FEPI server adapter that is invoked in the service flow, the logical unit owner is updated in the alternate connection file using the unique tag and the shared user ID and pool name.
  2. Any subsequent FEPI server adapter that runs as part of the same BTS process uses the same unique tag identifier to retrieve the correct assigned and in-session logical unit.
  3. The assignment remains in effect for the duration of the service flow, which might include the invocation of multiple FEPI server adapters
  4. The unique tag allows for running concurrent processes with the same shared user ID and does not change when a single process is running.

If the service flow ends abnormally, the service requester handles the condition by one of the following methods:

  • Initiating a service flow to compensate for the failed process
  • Issuing a cancel request to release the BTS resources

In addition, the CICS SFR interface program cleans up the assigned logical units if the service flow ends abnormally.

Error handling in synchronous mode

If a service flow ends abnormally, the logical units can remain assigned to the shared user ID. When the service flow completes, no BTS data-container information is available for subsequent users to locate, use, and log off assigned logical units. For this reason, the CICS SFR interface program closes any FEPI conversations and deletes the assignment of logical units, before returning to the service requester, even if the service flow did not complete successfully.

DFHMADPL uses the unique tag that is stored in the DFHMAC1F file to:

  • Locate all logical units that are used in the BTS process
  • End all the FEPI conversations
  • Delete the assigned logical unit from the connection file record
  • Initialize the target interaction file record

Error handling in asynchronous mode

If a service flow ends abnormally, the BTS process does not complete and the data-containers are available for subsequent use. To complete the failed BTS process and release the BTS resources, the service requester must either invoke a compensating flow in the same mode and use shared user IDs, or issue a cancel request to release the BTS resources and complete the process.

If the service requester invokes a compensating flow, the CICS SFR interface program:

  • Acquires the failed process using the process name and process type.
  • Initiates a new BTS process under which the compensating flow can run.
  • Retrieves the information in the data-containers of the failed process.
  • Cancels the acquired process, completing the failed BTS process and releasing the resources.
  • Put the information into the data-containers associated with the new BTS process.

The unique tag from DFHMAC1F is available to the next service flow and is used to locate all the logical units that were in the failed process. The logical units must be released as part of the following service flow.

If the service requester cancels the failed process, the CICS SFR interface program does the following:

  • Acquires the failed BTS process, gaining access to the data-containers that include the unique tag for the shared user ID.
  • Uses the unique tag and the user ID to locate all of the logical units that were used in the failed process.
  • Ends the FEPI conversation for each logical unit.
  • Deletes the record in the connection file for the logical units.
  • Initializes the target interaction file. This file contains the last screen buffer that was sent or received for the assigned logical unit.
  • Cancels the acquired process, completing the BTS process and releasing BTS resources.