The annotated trace of the scenario IBM-CICS

The following traces describe the most common scenario of the Change of Address application, that is, the actual change of address. In this scenario, the postal service operator makes a change to a registered person’s address using option 3 of the Change of Address application. This makes the change to the mainframe DB2 table and puts the hash code of the old address onto the publication queue. The CICS program finally sends a response screen to the operator indicating success and the new hashcode.

The HashPublication message flow running on the System z broker now publishes the hashcode to all the registered subscribers of the topic:

CICSWSAP/AddressChange, of which there are 3 in this trace example. This is the end of the HashPublication message flow.

The third component is a trace of a broker message flow, which represents the client side of the application. The client code receives the notification of the address change via the hashcode publication and checks to see if they have a client with that particular hashvalue. If so, it calls the CICS RetrieveAddress Web service to retrieve the new address for that person. If successful, the message flow updates the local customer database with the new address. This is the end of the sequence.

The flowcharts in the following pages may help to understand the time sequence and interactions of the various components. Note these flowcharts only represent this particular scenario and not the full logic of the application.

Flow of the Address Update CICS programs ITSOUA04/03

Flow of the Address Update CICS programs ITSOUA04/03

1. The trace through CICS

This section shows a trace through one scenario of the Change of Address application.

The trace begins with the postal service operator invoking the Address Change option by selecting Option 3 from the IT00 main menu. The sequence of events from a CICS perspective involves three maps and is seen in Figures below.

Option 3 to Add/Update Address

Option 3 to Add/Update Address

The operator then enters the new address details:

Entering new address details

Entering new address details

Next the operator presses ENTER to perform the update.

New address successfully entered

New address successfully entered

The flowchart in Figure describes the action of this update process and names the CICS business logic programs that are invoked for this scenario:

  • ITSOUA04 - updates the new address in a local database and publishes the notification of the update to the broker using MQPUT.
  • ITSOUA03 - INSERTs the new address into a database.

a. Start the transaction
The CICS trace in Example shows the start of program ITSOUA01, which SENDs the entered name and new address details from Figure and then returns with transaction IT14.

Example: Starting the transaction

b. Call DB2 and generate an AddressHash
Transaction IT14 starts program ITSOUA02, which receives the entered data into a commarea and then LINKS to the business logic module ITSOUA04. This program performs the following and is highlighted in Example:

  • Call DB2 to retrieve the record for the person from the local database.
  • Link to program ITSOGH03 to generate a hash value for the new address.
  • Link to program ITSOUA03.

Example : Check that name exists, and generate a Hash value

c. Update database with new address

Program ITSOUA03 now adds the new address and new hash value to the local database. Example shows that the following is performed:

  • ITSOUA03 starts.
  • Link to ITSOGH03 to GetHash value.
  • Call to DB2 to INSERT new address and hash value into the database.
  • Example: Update new address

    Call MQ to write the old AddressHash to a queue

    The processing has now returned to ITSOUA04, which performs the following actions and is highlighted in Example:

    • Call to DB2 to UPDATE the new address and hash in the NAMES table.
    • Call to MQ to MQPUT the Old AddressHash value to the queue named CICSWSAP.PUBLICATION.QUEUE.
    • Return to presentation logic program ITSOUA02.

    Example: Call to MQ to write the Old AddressHash

    d. Display results in CICS and terminate task

    This is the conclusion of the CICS processing with a return to the presentation logic in program ITSOUA02 and task cleanup. Example shows the following actions:

    • ITSOUA02 SENDs the map containing the results of the Add/Update Address to the terminal. This is also seen in Figure.
    • The CICS task is then terminated.

    Example: Results are displayed to the terminal, and the CICS task is terminated

2. Tracing the Broker on System z

The flowchart in Figure shows the Hash Publication message flow.

The Hash Publication Flow

The Hash Publication Flow

Example: The HashPublication message flow trace

3. Tracing the Broker on Windows

Now the RetrieveAddressWithDB message flow is triggered on the Windows platform by the

receipt of the hash publication.

Example RetrieveAddressWithDB MsgFlow Pt1

4. Tracing the CICS Web service

We now pick up the trace on the CICS side where the CICS Web service pipeline processes the Web service request for the RetrieveAddress logic and hands back the result. The flowchart in Figure shows the interaction between the message flow running in the Broker on the client Windows platform and the Web service in CICS where we are exposing our business logic as a service provider.
The CICS program being called is ITSORA03.

Client calling CICS RetrieveAddress Web service

Client calling CICS RetrieveAddress Web service

a. The Web service request enters CICS

When the client broker submits the Web service request to the CICS region, the receiving TCPIPSERVICE detects the incoming request and the actions are performed and displayed in the trace in Example.

  • Transaction CWXN starts and invokes program DFHWBXN to handle the incoming request.
  • The CICS SOAP HTTP Inbound Router transaction CPIH is attached.

Example: Request for Web services enters CICS

URI Mapping

Of interest in the trace entries for Example 9-10 on page 234, is further detail on the trace point for WB 0905 that shows the URI mapping in the CICS FULL trace output in Example. In this entry you can see the following in the eyecatcher area:

  • Transaction CPIH
  • Pipeline WSPIPE01
  • The name of the Web service to be invoked - RetrieveAddress
  • The relative URI for the service - /cicswsap/RetrieveAddress

Example: The FULL trace output showing URI mapping

b. A service provider pipeline is started

Transaction CPIH invokes the CICS program DFHPIDSH—the pipeline HTTP inbound router module—starting a service provider pipeline. This is shown in Example.

Example : Service provider pipeline is started

Pipeline details

The FULL trace entry for trace point ID PI 0A2F shows the details of the PIPELINE, including the configuration file name, the HFS shelf, and pickup directories. This is seen in Example and shows the following:

  • The pipeline name - WSPIPE01
  • The configuration file name –
  • The HFS shelf directory - u/jnott/cicswsap/shelf
  • The HFS pickup directory - u/jnott/cicswsap/wsbind/provider

Example : Full trace entry showing pipeline details

The incoming request

The trace point PI 0A41 contains the incoming request. The FULL entry showing the entire request is shown in Example.

Example: Full trace record of the incoming request data

c. Handling the Request

The trace in Example shows the CICS processing that continues:

  • Program DFHPISN1 starts, which is the handler program for SOAP 1.1.
  • DFHPIEP is invoked, which parses the incoming SOAP request.

Example: Parsing the incoming SOAP request

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd Protection Status