Chapter 14. Designing an Application to Use the MQSeries-CICS Bridge
In this chapter:
The application described in this chapter is required for the head office to view a customer account. It makes use of the inquire function provided within the NACT02 program. The application needs to allow the user to input a customer account number and retrieve the account details. No modifications to the data will be made.
Background to MQSeries
Programs in the MQSeries application suite can be running on different computers, on different operating systems, and at different locations. The applications are written using a common programming interface known as the Message Queue Interface (MQI), so that applications developed on one platform can be ported to others.
Figure 14-1 shows two applications communicate using messages and queues; one application puts a message on a queue, and the other application gets that message from the queue.
Queue Managers
In MQSeries, queues are managed by a component called a queue manager. The queue manager provides messaging services for the applications and processes the MQI calls they issue. The queue manager ensures that messages are put on the correct queue or that they are routed to another queue manager.
Before applications can send any messages, you must create a queue manager and some queues. MQSeries for Windows NT Version 5.1 provides a utility called MQSeries Explorer to help you do this and to create any other MQSeries objects that you need for your applications.
How Applications Identify Themselves to Queue Managers
Any MQSeries application must make a successful connection to a queue manager before it can make any successful MQI calls. When the application successfully makes the connection, the queue manager returns a connection handle. This is an identifier that the application must specify each time it issues an MQI call.
Opening a Queue
Before your application can use a queue for messaging, it must open the queue. If you are putting a message on a queue, your application must open the queue for putting. Similarly, if you are getting a message from a queue, your application must open the queue for getting. You can specify that a queue is opened for both getting and putting, if required. The queue manager returns an object handle if the open request is successful. The application specifies this handle, together with the connection handle, when it issues a put or a get call. This ensures that the request is carried out on the correct queue.
Putting and Getting Messages
When the open request is confirmed, your application can put a message on the queue. To do this, it uses another MQI call on which you have to specify a number of parameters and data structures. These define all the information about the message you are putting, including the message type, its destination, which options are set, and so on. The message data (that is, the application-specific contents of the message your application is sending) is defined in a buffer, which you specify in the MQI call. When the queue manager processes the call, it completes a message descriptor, which contains information that is needed to ensure the message can be delivered properly. The message descriptor is in a format defined by MQSeries; the message data is defined by your application (this is what you put into the message data buffer in your application code). Bear in mind that these values are not only determined by the queue manager but can also be defined in your program.
The program that gets the messages from the queue must first open the queue for getting messages. It must then issue another MQI call to get the message from the queue. On this call, you have to specify which message you want to get. Finally, it has to close the queue.
If your messaging application has only a low volume throughput, you will find the MQPUT1 call useful. It combines open, put, close in one call; thus, saving computer resources.
Messaging Using More Than One Queue Manager
The arrangement in Figure 14-1 is not typical for a one messaging application because both programs are running on the same computer, and connected to the same queue manager. In a commercial application, the putting and getting programs would probably be on different computers, and so be connected to different queue managers.
Figure 14-2 shows how messaging works where the program putting the message and the program getting the message are on the different computers and are connected to different queue managers.
The difference between Figure 14-1 and Figure 14-2 is the addition of a message channel and a transmission queue.
The MQSeries-CICS Bridge
The MQSeries-CICS bridge enables an application, not running in a CICS environment, to run a program or transaction on CICS and get a response back. This non-CICS application can be run from any environment that has access to an MQSeries network that encompasses MQSeries for OS/390.
A program is a CICS program that can be invoked using the EXEC CICS LINK command. It must conform to the DPL subset of the CICS API; that is, it must not use CICS terminal or syncpoint facilities. The full list is documented in the CICS Application Programming Guide.
A transaction is a CICS transaction designed to run on a 3270 terminal. This transaction can use BMS or Terminal Control (TC) commands. It can be conversational or pseudo-conversational. It is permitted to issue syncpoints.
When To Use the MQSeries-CICS Bridge
The MQSeries-CICS bridge allows an application to run a 3270-based CICS transaction, without knowledge of the 3270 data stream. It uses standard CICS and MQSeries security features and can be configured to authenticate, trust, or ignore the requestor’s user ID. Given this flexibility, there are many instances where the MQSeries-CICS bridge can be used:
To write a new MQSeries application that needs access to logic or data (or both) that reside on your CICS server.
To enable your Lotus Notes application to run CICS programs.
To be able to access your CICS applications from:
Your MQSeries Java client application
A web browser using the MQSeries Internet gateway.
The MQSeries-CICS DPL bridge allows an application to run a single CICS program or a set of CICS programs (often referred to as a unit of work). It caters to the application that waits for a response to come back before it runs the next CICS program (synchronous processing) and to the application that requests one or more CICS programs to run, but doesn’t wait for a response (asynchronous processing). To enable the MQSeries-CICS bridge to work:
MQSeries and CICS must be running in the same OS/390 image.
The MQSeries-CICS bridge queue is local (same queue manager) as the MQSeries-CICS bridge.
The reply-to queue can be either local or remote (on a different queue manager).
The MQSeries-CICS bridge tasks run in the same CICS as the bridge monitor. The user programs can be in the same or a different CICS system.
The MQSeries CICS adapter is enabled.
Enough about the background; what are the key things that have to be done to use the MQSeries-CICS bridge in the sample application?
Designing the Graphical User Interface
The main panel for this Java application has to contain all the fields returned in the COMMAREA from the NACT02 program. The main panel (see Figure 14-3) has a clear separation between the area where data is to be inputted and the fields that are used to hold the information returned from the CICS program. The information returned is itself divided into four areas: top left for customer details, top right for details of others who can charge to the customer’s account, bottom left for card details and bottom right for billing history (see RecordPanel.java for these details). The four sections are similar to those used with the web component of the Account Details panel output screen described in Chapter 8.
Designing the Java Application
The steps required within the Java application are as follows:
Obtain user input of the required Account Number keyfield
Open the relevant MQSeries queues to be used
Create an MQSeries message containing the NACT02 COMMAREA suitable for use with the MQSeries-CICS DPL bridge
Send the message to the appropriate MQSeries for OS/390 queue manager
Receive the reply message containing the updated NACT02 COMMAREA
Check that the CICS program has not reported any errors
Display the relevant information obtained from the COMMAREA
Configuring MQSeries
An MQSeries client is part of an MQSeries product that can be installed on a machine without installing the full queue manager. It is possible to have only an MQSeries client on the machine from which the Java head office application is to run and have all the MQSeries objects that are used defined on the Windows NT server’s queue manager. There are advantages and disadvantages to this which are discussed in detail in MQSeries documentation.
We have chosen to have a queue manager set up on our Windows NT Java machine to improve the robustness of the application should the link to the OS/390 machine be unavailable for any reason. The additional queue manager allows messages to be kept until such times as the channel to the queue manager on the OS/390 machine is available. This is referred to as assured delivery. It ensures that the message is received when the channel connecting the queue managers is available and is sent once and once only.
Whichever of the two methods described is used, there are two changes to the Java application that are necessary. They are the libraries used at link-edit time and the channel definitions; see Figure 14-4.
The Java application, in our case, uses an MQI channel to send and receive messages to and from the local queue manager on the Windows NT workstation.
The queue that it is sending messages to is actually defined to the OS/390 queue manager. Messages are sent over a message channel. Reply messages created by the MQSeries-CICS DPL bridge are sent to the reply-to queue on Windows NT queue manager by means of a separate message channel. Separate message channels are required to send and receive messages between queue managers, as message channels only have the ability to send MQSeries messages in one direction.
To process the MQSeries message sent from the Java application and link to/run the CICS program NACT02, we make use of the MQSeries-CICS DPL bridge.
Running CICS DPL Programs
The MQSeries message provides the data necessary to run the program. The bridge task builds a COMMAREA from this data, and runs the program using the EXEC CICS LINK command. Figure 14-5 shows the sequence taken to process a single message to run a CICS DPL program.
The following describes each step, and explains what takes place:
A message with a request to run a CICS program is put on the CICS bridge queue.
The CICS bridge monitor task, which is waiting for messages, recognizes that a start unit of work message has arrived. This information is contained in the message header in the correlation ID field, which contains a value MQCI_NEW_SESSION.
Relevant authentication checks are made, and a CICS DPL bridge task is started with the appropriate authority.
The CICS DPL bridge task removes the message from the CICS bridge queue.
The CICS DPL bridge task builds a COMMAREA from the data in the message and issues an EXEC CICS LINK for the program requested in the message.
The program executes and returns the response in the COMMAREA used by the request.
The CICS DPL bridge task reads the COMMAREA, creates a message, and puts it on the reply-to queue specified in the request message. All response messages (normal and error, requests and replies) are put to the reply-to queue with default context.
A message is returned to the MQSeries server or client.
A unit of work can be just a single-user program, or it can be multiple-user programs. There is no limit to the number of messages you can send to make up a unit of work.
Why Design It This Way?
The same information could have been obtained by setting up a CICS client to server link; so why have we chosen to use an MQSeries method to obtain the data? MQSeries allows applications on disparate platforms to be accessed and used within a single application. An MQSeries message obtains information from our CICS program on OS/390. A separate message can be used to obtain information from a non-CICS application on a different platform such as a credit check application running on an AIX machine. The asynchronous nature of MQSeries messaging means that messages can be sent almost simultaneously to obtain information from several different programs.
This head office application is seen as a first step in a larger process to create new applications that can provide head office with full customer details and statistics in a single view.
Using MQSeries for Java provides us with what is seen as one of the main advantages of Java: Write once, run anywhere. The Java application is readily portable and the code and structures reusable. The Java application can be transformed easily into a Java applet or servlet if we wish to make it available as part of a web-based application in the future.
What’s Next…
Having introduced the MQSeries-CICS bridge and outlined the design, Chapter 15, leads you through the steps that you need to take to create the application and make all the right connections.