A client developed in WebSphere Message Broker IBM-CICS

WebSphere Message Broker (WMB) is ideally suited to this client task as it is by nature an asynchronous subsystem. WMB allows easy facilitation of the Web service calls via native HTTPRequest nodes and the new ability to import WSDL files as message definition files.

WMB is much too large a topic to be introduced at more than a superficial level here. However, the level of complexity of this message flow is basic, so the reader should have little difficulty following the logic of this approach.

1. Creating the RetrieveAddressWeb Message Flow

The RetrieveAddress message flow should perform the following tasks:

  • Retrieve an address hash from a subscription queue.
  • Check the local customer database for any clients whose address matches this address hash.
  • Invoke the StandardName Web service for each name returned to obtain the standard format of this entity.
  • Call the RetrieveAddress CICS Web service for each matching client, supplying the standard-name of the client and the address hash.
  • Update the local customer database with the changed address, if RetrieveAddress returns a new address for client.

The Customer database

The Customer database can be just about any type of data repository required, but in most cases, this will be a database. But it could just as well be a spreadsheet or a VSAM dataset on a mainframe. In this implementation, the database is a DB2 table on Windows. For simplicity, we created a single, linear table to hold our customer data. It looks similar to Figure.

The Customer database table format

The Customer database table format

Now since the RetrieveAddress Web service returns no information about the identity of the user for which it publishes a hash, we must already have clients in the Customer database table, together with hash values of their current addresses. This could be done using DB2 Control Center’s spreadsheet-like graphical input or some simple SQL INSERTS—which is what is more likely to happen in a real business situation. The Hash code is returned by a call to the GetHash CICS Web service. We created the following entries in our Customer database table with these hash codes (not shown).

Sample contents of the Customer database table

Sample contents of the Customer database table

Creating a Message Set from the RetrieveAddress WSDL

Just as we created a message set in the broker by importing a C Header structure, we now create a message set for the call to the RetrieveAddress message set.

  1. Create a new Message Set project. As previously mentioned, it is best practice to separate different classes of messages. We call both the Message Set project and Message Set CICSWSAPWSDLMsgSet. The physical format will be XML because WSDL is an XML schema.
  2. Import the WSDL file into the work space before creating a Message Definition file from it. (File → Import → File System.)
  3. Locate the RetrieveAddress.wsdl file and import it into the CICSWSAPWSDLMsgSet project.
  4. Import the RetrieveAddress WSDL file

    Import the RetrieveAddress WSDL file

  5. Create the Message Definition, by selecting File → New → Message Definition File, and then choose: WSDL File.
  6. Locate the WSDL file in the CICSWSAPWSDLMsgSet project.
  7. Locate the WSDL file

    Locate the WSDL file

  8. Click Next. We are asked what Message set in which we want to save the definition. Choose CICSWSAPWSDLMsgSet, and click Next. We take the default on WSDL Warnings and leave the NameSpaces as is. Take defaults until the message definition file is created.

Constructing the RetrieveAddress Message Flow

Our RetrieveAddress message flow looks similar to Figure.

The RetrieveAddress message flow

The RetrieveAddress message flow

Most of the nodes in this message flow are Trace nodes, which are essentially there to help with run-time errors. They are all configured to write to the Local Error Log. For example the Query Failed node looks similar to Figure.

A typical Trace node

A typical Trace node

Ignoring error conditions for now, the Message Flow commences with the receipt of a published hash onto our subscription queue. Our queue name was indicated on our subscription request and matches the value on the MQInput node.

The subscription queue on the MQInput node

The subscription queue on the MQInput node

Essential information about the structure of the message is indicated in the Default tab.

The Message format data

The Message format dat

So, at this stage, the MQInput node knows what queue it takes messages from and also understands the format of the message. The parsed message tree is passed to the next node, which is a query to our local Customer database table to see if we have any clients with a matching hash key. The Database node needs to know what database it is using.

The Database Node properties

The Database Node properties

In this case, our database is called UWC (Unified Widget Corporation), which contains just one user table called Customer. The Statement field indicates the name of an ESQL module containing the database query, which is follows in Figure.

The query

The query

This ESQL places the result of the query in the Environment branch of the parse tree where this result will be available to subsequent nodes.

The next significant node in the message flow is a Compute node, which constructs the call to the RetrieveAddress Web service. It takes the results of the above ESQL query and places the first, middle, and last names, as well as the hash value, into the Web service call parameter structure.

Setting up the call to the RetrieveAddress Web service

Setting up the call to the RetrieveAddress Web service

The output of this node is now suitable for the following node, the actual call to the Web service via the HTTPRequest node. Essential information about this node includes the following:

  • The actual URL of the Web service
  • Transport properties like whether SSL is in use
  • The names of the message sets, so we can interpret the results of the Web service call and parse the results ready for the next node.

The HTTP Request node properties –

The HTTP Request node properties –

The HTTPRequest node properties - 2

The HTTPRequest node properties - 2

The next Compute node in the sequence simply checks the success or otherwise of the Web service call and sets an indicator for the next node: the RouteToLabel, depending on the error condition. If successful, the next significant node is the UpdateCustomer Database node. Here, we attempt to update the client record in the local DB2 table with the results of the RetrieveAddress Web service call. The properties of this node indicate the database being targeted: UWC. This node contains ESQL to perform the update.

Updating the local Customer database

Updating the local Customer database

And with the success of this update, the message flow fulfilled it’s purpose.

Testing the RetrieveAddress Message Flow

We can now perform an end-to-end test of the AddressChange message flow presuming everything described so far is in place. It should now just be a case of updating one of the known customer’s address details on the CICS application (Option 3). This generates the hash, which is published by our Hash Publication message flow. All registered subscribers, including our RetrieveAddress message flow receive this message. If the message flow runs through to successful completion, we expect to see a message logged indicating the success, as well as an update to our Customer database table.

  1. First, we update the address of Thomas J. Watson.
  2. Change Thomas J Watson’s address

    Testing the RetrieveAddress Message Flow

    Update confirmed

    Update confirmed

  3. Look at the Windows Event Viewer for evidence of the success or otherwise of the update on the client side.
  4. Example: An error log event indicating success of the update

    The description for Event ID ( 19003 ) in Source ( WebSphere Broker v6002 ) could not be found.
    It contains the following insertion string(s): .
  5. Ensure that the Customer database table update occurred. A simple SQL query will suffice, similar to Example:

Example: Querying the CUSTOMER database

The message flow performed its designated task.

Running the message flow on a System z Broker

Although this message flow was developed on Windows, we tested it on a System z WebSphere Message Broker. We chose to run a cut-down version of the message flow, leaving out the database nodes. This was purely due to time constraints.

We discovered a couple of changes were necessary. When we first tried to run the message flow, we could see no trace node output. Clearly Local Error Log is not appropriate as a destination for System z broker trace nodes. We changed this to File with /var/wmqi/MQ8GBRK/output/RetrieveAddress.log as the destination.

Secondly, out RetrieveAddress Web service call failed with the diagnostic in Example:
Example: Error in RetrieveAddress Web service call

We reasoned that the only difference between the Windows and System z platform was the code-page and encoding schemes. We added two lines at the start of the our ESQL on the Setup WS Call compute node to set the CodedCharacterSet and Encoding values as suggested by the trace output above.

This change worked as we wanted. Figure shows the modified ESQL:

The modified ESQL

The modified ESQL

Possible improvements

  • Usually more than one person lives at an address. This sample message flow needs to be able to handle multiple clients with same address hash.
  • Use HTTPS on the RetrieveAddress Web service call to secure possibly personal information
  • Message flow should invoke the StandardName Web service before the RetrieveAddress Web service. These are currently dummy functions.

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

IBM-CICS Topics