Request processing patterns for Aggregate connector — persistent and nonpersistent

All processing in the aggregate connector pattern is the same whether it is run with the persistent or nonpersistent option with the exception of the BTS DEFINE PROCESS command in the DPL stub program (DFHMADPL).

The following information describes the request processing that is associated with Adapter services of the aggregate connector type:

  1. A service requestor initiates the CICS® Service Flow Runtime when it sends a correctly formatted request using any of the supported interfaces.
  2. The DPL stub program (DFHMADPL), receives the request through one of the supported interfaces and reads the properties file (DFHMAMPF) using the request name (DFHMAH-REQUESTNAME) that was passed in as part of the request message in the message header structure (DFHMAH).

    See Properties file record descriptor (DFHMARPF) to view the structure of the Properties file.

    See Request properties for request property value settings and descriptions. If the request message is in XML format, the DPL stub program will call the XML Header to COBOL Converter program (DFHMAXMI) to parse the XML header tag data and return in a COBOL fixed format (DFHMAH). This call is made before reading the Properties file.

    The DPL stub program will then call a user-defined program to parse the XML application request tag data and return in a COBOL fixed format structure. The application program name is determined by the request properties file field, MP-XML-PARSE-PROGRAMID. See Request properties for further information.

    See XML request and response processing and XML message formats for non-passthrough for further information regarding XML message processing.

  3. When the request properties record indicates that the processing pattern is of the aggregate connector type (see Request properties for request property value settings and descriptions); MP-DEPLOYMENT-IND = 2, the DPL stub program (DFHMADPL) performs the following processing steps:
    1. Defines the BTS process using the BTS command EXEC CICS DEFINE PROCESS:
      For MP-PERSISTENCE-IND = 0 (nonpersistent):
      EXEC CICS DEFINE PROCESS (<processname>)
                   PROCESSTYPE (<processtype>)
                       TRANSID (<transid>)
                      PROGRAM  (<program>)
                     NOCHECK
                          RESP (CICS-RESP) 
                         RESP2 (CICS-RESP2)
      END-EXEC.
      For MP-PERSISTENCE-IND =1 (persistent):
      EXEC CICS DEFINE PROCESS (<processname>)
                   PROCESSTYPE (<processtype>)
                       TRANSID (<transid>)
                      PROGRAM  (<program>)
                          RESP (CICS-RESP) 
                         RESP2 (CICS-RESP2)
      END-EXEC.
      where:
      • (<processname>) is equal to value passed in the request message header structure, DFHMAH, field DFHMAH-PROCESSNAME or a unique value generated by CICS Service Flow Runtime. See DFHMAH field definitions for further information.
      • (<processtype>) is equal to value passed in the request message header structure, DFHMAH, field DFHMAH-PROCESSTYPE. See DFHMAH field definitions for further information.
      • (<transid>) is equal to Navigation Manager transaction ID (CMAM).
      • (<program>) > is equal to Navigation Manager program name (DFHMAMGR). The Navigation Manager runs as the BTS root activity (DFHROOT).

      The NOCHECK processing option indicates that no record is to be written to the BTS repository data set to reserve the name of the process. Using the BTS NOCHECK option improves BTS performance by removing the write to the repository and its associated logging. See the CICS Business Transaction Services manual for further information on the DEFINE PROCESS command and options.

    2. Writes application request data to the process input data-container ADAPTER.INPUT. The Adapter navigator program activity reads the input data-container ADAPTER.INPUT to retrieve the application request data that is used in Adapter service processing.
    3. Writes state information to the process data-container ADAPTER.PROCESS.

      State information includes the request name (DFHMAH-REQUESTNAME) as specified in the message header (DFHMAH) and the program name and transaction that will process the application request data as defined by request properties, MP-INITIAL-PROGRAMID and MP-INITIAL-TRANSID fields, respectively.

      For Adapter services of the aggregate connector type, the program and transaction defined and run will be an Adapter Navigator. The Adapter Navigator will perform the request processing (i.e., manage the flow navigation of the Adapter service and run the server adapters required to process the business request).
    4. Runs the BTS process either in synchronous or asynchronous mode as defined by request property, MP-REQUESTTYPE.
      Note: If you are using a synchronous interface (i.e., ECI, EXI or DPL) to invoke server runtime processing, and if the service requestor expects a response, your Adapter service request must be run in synchronous mode. Asynchronous mode processing assumes a WebSphere MQ interface.
      Synchronous BTS RUN command (MP-REQUESTTYPE = 1 or 2)
      EXEC CICS RUN ACQPROCESS 
                   SYNCHRONOUS 
                         RESP (CICS-RESP) 
                        RESP2 (CICS-RESP2) 
      END-EXEC. 
      Asynchronous BTS RUN command (MP-REQUESTTYPE = 0)
      EXEC CICS RUN ACQPROCESS 
                 ASYNCHRONOUS 
                          RESP (CICS-RESP) 
                         RESP2 (CICS-RESP2) 
      END-EXEC.
    Figure 1. DPL Stub program request processing — aggregate connector type
    The diagram illustrates the program processing performed by the DPL Stub program for an Adapter service of the aggregate connector type
  4. Once invoked, the Navigation Manager (DFHMAMGR) performs the following processing steps:
    1. Reads the adapter state information from process container ADAPTER.PROCESS.
    2. Defines the Adapter Navigator BTS activity that will process the application request using the BTS command EXEC CICS DEFINE ACTIVITY:
      EXEC CICS DEFINE ACTIVITY  (ADC-NAV-ACTIVITY)
                          EVENT  (<completionevent>)
                        TRANSID  (ADC-NAV-TRANSACTION)
                        PROGRAM  (ADC-NAV-PROGRAM-ID)
                     ACTIVITYID  (ADC-NAV-ACTIVITYID)
                           RESP  (CICS-RESP)
                          RESP2  (CICS-RESP2)
      END-EXEC.   
      where:
      • ADC-NAV-ACTIVITY is equal to the request name value passed and stored in the process container ADAPTER.PROCESS.
      • ADC-NAV-TRANSACTION is equal to the initial transaction ID as indicated on the request properties, field MP-INITIAL-TRANSID, and stored in process container ADAPTER.PROCESS
      • ADC-NAV-PROGRAM-ID is equal to the initial program name as indicated on the request properties, field MP-INITIAL-PROGRAMID, and also stored in process container ADAPTER.PROCESS.
    3. Writes adapter state information to container ADAPTER.PROCESS. Additional state information includes the ACTIVITYID, CICS applid where the Navigation Manager (DFHMAMGR) is running, EIBTASKN of the running Navigation Manager, etc.
      Note: For Adapter services of the aggregate connector type, the program and transaction invoked will be an Adapter Navigator . The Adapter Navigator will perform the request processing (i.e., manage the flow navigation of the Adapter service and run the server adapters required to process the business request).
    4. Runs the Adapter Navigator BTS activity as defined by the Adapter service, either in synchronous or asynchronous mode, as defined by request property, MP-REQUESTTYPE.
      Synchronous BTS RUN command (MP-REQUESTTYPE = 1 or 2)
      EXEC CICS RUN ACTIVITY (ADC-NAV-ACTIVITY)
                 SYNCHRONOUS
                        RESP (CICS-RESP)
                       RESP2 (CICS-RESP2)
      END-EXEC.
      Asynchronous BTS RUN command (MP-REQUESTTYPE = 0)
      EXEC CICS RUN ACTIVITY (ADC-NAV-ACTIVITY)
                ASYNCHRONOUS
                        RESP (CICS-RESP)
                       RESP2 (CICS-RESP2)
      END-EXEC.
Figure 2. Navigation Manager program request processing — aggregate connector type
The diagram illustrates the request processing performed by the Navigation Manager (DFHMAMGR) program for an Adapter service of the aggregate connector type

As a result of the Navigation Manager (DFHMAMGR) running the Adapter Navigator activity, the DPL, WebSphere MQ, FEPI and/or Link3270 server adapter will perform business request processing (as modelled in Service Flow Modeler) in order to complete the request made by the service requestor.

For example, the generated and deployed Adapter service (an Adapter Navigator and 1 to n server adapters of any type) might perform the following steps:
  1. Invoke a server adapter to interact with a CICS and IMS™ application using a 3270 data stream and retain the result. This processing consists of screen navigation.
  2. Invoke a server adapter to interact with a WebSphere MQ-enabled application and post the result of the first server adapter's processing to an WebSphere MQ queue.
  3. Invoke a server adapter to interact with one or more CICS transactions via DPL and send the result of the first server adapter. For example, it could write a record to a DB2® database.
  4. Invoke a custom program via DPL that executes complex rules such as logic or complex input and output. A custom program can be developed to augment CICS Service Flow Runtime.
  5. Return application reply data to the Navigation Manager (DFHMAMGR). It could contain the final result.

Each business request issued by the service requestor results in a different BTS process instance to fulfill the appropriate Adapter service as defined by the business request name.

Each process instance consists of a Navigation Manager (DFHMAMGR) activity, an Adapter Navigator activity and those server adapter activities that are needed to support that Adapter service.