Processing patterns for a passthrough request

The following information describes the processing that is associated with a passthrough request.

  1. A service requester invokes the runtime environment when it sends a correctly formatted passthrough request message using any of the supported interfaces.

    The request message contains the name of the DPL passthrough stub program (DFHMADPP), which initiates server runtime processing.

    The passthrough request message must include the appropriate header structures and must indicate the following in the header structure (DFHMAH) of the request message:
    • The DFHMAH-UOWCONTROL field must be set to + 3 (DFHMAH-PASSTHROUGH) to indicate passthrough processing mode.
    • The DFHMAH-VERSION field must be set to +2 (DFHMAH-VERSION-2).
    • The DFHMAH-FORMAT field must be set to MAH2 (DFHMAH-PASSTHROUGH-HDR) to indicate the DFHMAH2 header structure follows.

      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).

      The DPL Passthrough Stub program (DFHMADPP) will then call the ADS to XML Converter program (DFHMAXPI) to parse the XML application request tag data and return in a COBOL fixed format structure. The inbound application request tag data in passthrough mode must also include pertinent screen header (CIA-SCREEN-HEADER) and map header (CIA-MAP-HEADER) tag data.

      See XML request and response processing for passthrough and XML message formats for passthrough requests for further information.

  2. The DPL passthrough stub program (DFHMADPP), receives the request through one of the supported interfaces and performs the following processing steps:
    Note: The DPL Passthrough Stub program (DFHMADPP) does NOT read the Properties file (DFHMAMPF) as in the single connector and aggregate connector patterns. The request name (DFHMAH-REQUESTNAME) still must be passed in as part of the request message in the message header structure (DFHMAH), however. See Request message headers for further information.
    1. Defines the BTS process via the BTS command EXEC CICS DEFINE PROCESS:
      EXEC CICS DEFINE PROCESS (<processname>)
                   PROCESSTYPE (<processtype>)
                       TRANSID (<transid>)
                      PROGRAM  (<program>)
                     NOCHECK
                          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 Request message headers for further information.
      • (<processtype>) is equal to value passed in the request message header structure, DFHMAH, field DFHMAH-PROCESSTYPE. See Request message headers for further information.
      • (<transid>) is equal to the Navigation Manager transaction ID (CMAM).
      • (<program>) > is equal to the 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 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.
    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 processing mode (DFHMAH-UOWCONTROL).

    4. Runs the BTS passthrough process in synchronous mode.
      EXEC CICS RUN ACQPROCESS 
                   SYNCHRONOUS 
                           RESP (CICS-RESP) 
                          RESP2 (CICS-RESP2) 
      END-EXEC. 
  3. Once invoked, the Navigation Manager (DFHMAMGR) will perform the following processing steps:
    1. Reads the state information from process container ADAPTER.PROCESS.
    2. Defines the BTS Link3270 Passthrough Manager activity that will process the application request via 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 Link3270 Passthrough Manager transaction ID (CMAL)
      • ADC-NAV-PROGRAM-ID is equal to Link3270 Passthrough Manager program name (DFHMALPT).
    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 passthrough processing, the program and transaction run will not be an Adapter Navigator or a DPL, WebSphere® MQ, FEPI or Link3270 server adapter but rather the Link3270 Passthrough Manager load module (DFHMALPT) as there is no modelled Adapter service.
    4. Runs the BTS Link3270 Passthrough Manager activity in synchronous mode.
      EXEC CICS RUN ACTIVITY (ADC-NAV-ACTIVITY) 
                SYNCHRONOUS 
                        RESP (CICS-RESP) 
                       RESP2 (CICS-RESP2) 
      END-EXEC. 
    Figure 1. DPL Stub program request processing — Passthrough
    The diagram illustrates the program processing performed by the DPL Passthrough Stub program for a passthrough request

    The BTS Link3270 Passthrough Manager activity will perform Link3270 passthrough processing in order to complete the request made by the service requestor.

    The Link3270 Passthrough Manager (DFHMALPT) performs the following operations:
    1. Calls the Link3270 Maintenance program (DFHMALNM).

      The Link3270 Maintenance program performs initialization and exit processing for passthrough processing. It calls the Link3270 Facility State Management program (DFHMALTS), if necessary, to retrieve, store and/or delete Link3270 facility business state information.

    2. Calls the Link3270 Vector Processor (DFHMAVCP).

      The Link3270 Vector Processor program sends vectors to and receives vectors from any CICS target application that uses BMS commands (with some restrictions) where a single send and receive structure inclusive of the Link3270 bridge header (BRIH), the inbound/outbound vector header and appropriate inbound/outbound vector is not greater than 32000 bytes (i.e. the COMMAREA passed to the Link3270 bridge program, DFHL3270, is 32,000 bytes).

      The Link3270 Vector Processor program can also call the Link3270 Vector Log program (DFHMAVCL), if vector logging is on, to log inbound and outbound Link3270 vector header information and data. See DFHMAH2 header structure for information on configuring for vector logging and additional passthrough header fields and definitions.

    Each passthrough request issued by the service requestor results in a different BTS process instance to fulfill that passthrough request.

    Each process instance consists of a Navigation Manager (DFHMAMGR) activity and the one Link3270 Passthrough Manager (DFHMALPT) activity that is needed to support that passthrough request.

    With regards to data-container management, passthrough processing processes as a single connector type.
Figure 2. Navigation Manager program request processing — Passthrough
The diagram illustrates the program processing performed by the Navigation Manager program for a passthrough request