To provide the connection to an MQSeries queue manager, we have created a Java class MQCommunicator. It looks like this:

public class MQCommunicator {.......}

The full code is on the accompanying CD in the directory called mqseries-java clientMQCommunicator.class.

MQSeries provides a number of Java classes, which we can access on Windows NT by importing the package com.ibm.mq.*. In order to make a connection to the relevant queue manager we need to supply the following information:

The code looks like this:

// Setup MQ object

MQComms=newMQCommunictaor(hostname,qManager,channel,requestQueue,replyQueue);

Using the MQSeries supplied environment class MQEnvironment, we set the variables for the host name, queue manager, and the communications port to use:

MQEnvironment.hostname = hostname;            // ARG#1
MQEnvironment.channel  = channel;             // ARG#2
MQEnvironment.port = 1414;                    // Hard code port

The communications port in this case has the system default value of 1414. When no value is set for the port, this value will normally be assumed. This is important if you are using more than one port.

Connection to the selected queue manager is then made by creating an instance of the MQSeries supplied object MQQueueManager:

qMgr = new MQQueueManager(qManager);

Once we have established the connection, we can open the MQSeries queues for use. requestQueue and replyQueue are instances of the MQSeries supplied object MQQueue.

To enable the request queue so that we can place messages on it, we set the relevant open option:

openOptions = MQC.MQOO_OUTPUT ;          // Open queue to perform MQPUTs

This information is then supplied with the open request:

requestQueue = qMgr.accessQueue(aRequestQueue, openOptions,
                   null,           // queue manager on which the queue is defined
                   null,           // no dynamic queue name
                   null);         // no alternate user id

The use of null for the queue manager name denotes that the queue is defined to the queue manager to which this MQQueueManager object is connected.

Similarly, we enable the reply-to queue so that we can get the response message:

openOptions = MQC.MQOO_INPUT_AS_Q_DEF ;
replyQueue = qMgr.accessQueue(aReplyQueue, openOptions,
                   null,            // queue manager on which the queue is defined
                   null,             // no dynamic queue name
                   null);           // no alternate user id

To create an instance of the MQSeries object MQMessage:

sendMessage = new MQMessage();

Default values for the message can be used for most of the message options. The following changes need to be made:

Add the COMMAREA fields to the message buffer:

MQMessage.WriteString
.
Add COMMAREA structure

Under certain circumstances, the message format required for the MQSeries CICS DPL bridge contains an additional structure compared with standard MQSeries messages.

For our simple example (which only starts one program), this MQCIH structure is not required. The MQCIH is required when you want to do one of the following:

The MQCIH header is placed at the start of the message buffer.

The contents of the request COMMAREA for this application always contain the same supplied values apart from the customer account number keyfield. We have chosen to store the COMMAREA fields before the customer account number key-field in the string bufferFront. The fields following the customer account number keyfield are stored in the string bufferEnd.

The bufferFront string is composed as follows:

bufferFront = "NACT02" +   // Program name
         "V1A"+            // Version
         "E"+              // Request type
         "    "+           //
         "    "+
         "     "

We need to supply the remainder of the COMMAREA after the customer account number. It consists of only spaces. As a result, bufferEnd is a string of 378 spaces.

These values are now used to create the message buffer string:

String buffer = new String(bufferFront + customerNumber + bufferEnd);

The customerNumber field is a 5-character string holding the customer account number value.

This is then written to the MQSeries message instance sendMessage:

sendMessage.writeString(buffer);

MQSeries provides an object to specify options for the message being put onto a queue. In most cases the default options are acceptable. We create an instance of this MQPutMessageOptions object pmo:

// Specify the message options...(default)
MQPutMessageOptions pmo = new MQPutMessageOptions();

The message can now be placed on the appropriate queue:

requestQueue.put(sendMessage, pmo);

The response message is recognized by its correlation ID (CorrelId), which matches the original message ID (msgId) passed with the request message. The application copies the global: message ID of the request message into the correlation ID of a new MQMessage object, in this case, the response message.

In a similar way to which we built the request message, we first create an instance of the MQSeries object MQGetMessageOptions, which is used to set the options for getting the response message:

MQGetMessageOptions gmo = new MQGetMessageOptions();

You can modify the default values of this new instance gmo as follows:

We already have the required MQSeries message object in the instance StoredMessage which is supplied as the parameter replyMessage. The code to get the message is:

ReplyQueue.get(replyMessage,gmo);

The COMMAREA returned by NACT02 within the response message contains a response code and reason code. These need to be checked in order to determine whether the request to retrieve the customer details was successful or whether some error was encountered. For a non-zero return code, the following need to be checked:

//informUser("Message received!");
//print("Message is: "+messageReturned);
//Check that inquire has been successful
CICSresponseCode = messageReturned.substring(12,16);
print(">CICS response code" +CICSresponseCode+"#");

CICSreasonCode=messageReturned.substring(16,20);
print(">CICS reason code" + CICSreasonCode+"#");
if (CICSresponseCOde.equals("0000")){
    //Strip off the fields preceding the customer record
    customerDetails = messageReturned.substring(25,408);
    AccountRecord retrieved=new AccountRecord(customerDetails);
    displayRecord(retreived);
    return;
}
//No valid record to display so clear fields
clearDisplay();
    //Check out error response returned by CICS
    if(CICSresponseCode.equals("0013")){
        informUser("No record can be found for the custimer number given.")
        return;
    }
    if(CICSresponseCode.equals("LOCK")){
        informUser("The requested record is currently unavailable, possibly being
            updated."
                     + "
Please try again later.");
         return;
    }
    if(CICSresponseCode.equals("ABND")){
        informUser("Please inform the systems administrator the the CICS system has"
            +"
abnormally ended with code" + CICSreasonCode + "Severe Error");
        return;
    }
    if((CICSresponseCode.equals("FRMT")) & (CICSreasonCode.equals("LENE")){
        informUser("Please inform the systems administrator that the call to the CICS
            program" + "
has failed due to an error in the length of the data
            supplied.");
    }
    if((CICSresponseCode.equals("FRMT")) & (CICSreasonCode.equals("REQE"))){
        informUser("Please inform the systems administrator that the call to the CICS
             program + "
has failed due to an error in the type of request made.");
    }
    informUser("Please inform the systems administrator that the call to the CICS
         program + "
has failed with the following error" + "
         nEIBRESP="CICSresponseCode+"EIBRESP2=" CICSreasonCode);
    }finally{
        enableDisableListitems(true);
    }

The next step is to create retrieved, a new instance of AccountRecord and pass the appropriate portion of the response message string as a parameter. The constructor class for this instance of AccountRecord uses the supplied string held in customerDetails to construct the various fields that make up the customer information returned within the COMMAREA from the NACT02 program. The basic method is to assign substrings based on position to the various declared fields of the AccountRecord structure. A getfieldname method is provided for each record field so that the fields can be easily retrieved by other Java classes. The code looks like:

AccountRecord retrieved = new AccountRecord(customerDetails);

The MQClient method displayRecord can then be used to populate the various fields displayed on our main panel:

displayRecord(retrieved);

Before you start, we have included a series of files on the CD that create and start all the queue manager, queues, and channels that you need on MQSeries for Windows NT. Of course, you have to edit the files so that the IP address, queue, and channel names are appropriate. The first three steps are found in MQSeries-Java ClientMQSeries Client directory.

There are a number of standard definitions supplied by MQSeries that can be used to quickly set up the relevant required MQSeries objects. There may well be a suitable MQSeries set up on your machine that can be modified to enable communications with the CICS system.

Before you start, you need to know the IP address of the OS/390 machine you intend to communicate with, the name of the queue manager on that machine, and the name of the message channels that will be used to send messages to and from that machine.

The commands can be entered from a command prompt. Alternatively, MQSeries for Windows NT Version 5.1 supplies a Graphical User Interface, known as MQSeries Explorer, that can be used. To start MQSeries Explorer select Start, Programs, IBM MQSeries, and MQSeries Explorer. When you’ve defined the queues and queue managers, you’ll see the following screen shown in Figure 15-1.

Alternatively, you can use the following command files that we have provided on the CD-ROM. To do this:

You can also enter the commands from a command prompt, which if you are using MQSeries from other platforms, you will have to:

Figure 15-2. Queue Manager, Channel, and Queue names for the sample application

These definitions can be implemented using the following command. The results and any error messages are written to admvs.out:

runmqsc "< admvs.def > admvs.out"

Provided there have been no errors in establishing the channel connections, the Windows NT machine now has all the required definitions to send and receive messages from the queue manager MQQ1 on the OS/390 machine.

Error messages relating to the channel can normally be found in an error log Amqerrnn.log where nn is a number such as “01”. A typical directory for this log file is:

C:mqmqmgrsNTQMGRerrors

At this point you will have all the definitions ready on your Windows NT system and now need a similar set of definitions on MQSeries for OS/390.

Setting up MQSeries and its definition to CICS on the OS/390 server machine would normally be handled by a system programmer who has been assigned that responsibility. The full details of setting up your MQSeries server can be found in the MQSeries for OS/390: System Management Guide.

Assuming that MQSeries has been installed and a queue manager set up, the following shows the steps that the system programmer would have to undertake to allow the MQSeries-CICS DPL bridge to work:

You need to define the following CICS bridge transactions and programs using the resource definition utilities DFHCSDUP and CSQ4CKBC as input:

By default, your CICS DPL programs run under transaction code CKBP. You need to change the TASKDATALOC attribute if you are going to run 24-bit programs. If you wish to run your programs under different transaction codes, you need to install copies of the definition of CKBP, changing the transaction name to the ones of your choice.

The most straightforward way to define queues and channels on OS/390 is to have a PDS member with all the definitions in it and include it in the CSQINP2 DD concatentation of the startup job. For the purposes of this book we are using option 6 from ISPF so that we can step through and describe each of the definitions.

We need to define two queues, a local queue as our transmission queue and a remote queue. In addition, we need to define both the SENDER and RECEIVER channels:

Figure 15-4. MQSeries for OS/390: Changing the queue manager

Figure 15-5. MQSeries for OS/390: Defining a local queue

You need to define a transmission queue and a receiver channel on OS/390 so that you can send data to your Windows NT system:

Finally, return to the main menu and select option 6 to start the SENDER Channel. Enter CHLSENDER as the object type and the name of your sender channel MQQ1.TO.NTQMGR. Now press Enter.

Having started the MQSeries channels, you now have to start the MQSeries-CICS bridge monitor from your CICS region:

Figure 15-11. MQSeries for OS/390: The Connection pulldown

Figure 15-12. MQSeries for OS/390: Display Connection panel

The following guidelines will help you start the CICS bridge:

Alternatively, you can enter CECI START TRANSACTION(CKBR), which runs the transaction independently of your terminal. To check if the transaction is running, enter CEMT INQUIRE TASK.

You may have to stop and restart the listener to be sure that the application works. To do this:

Figure 15-13. MQSeries for OS/390: Start a System Function

To check that OS/390 is listening on the same port number that the Windows NT Sender channel, choose option 1 from the MQSeries for OS/390 Main Menu and enter SYSTEM for the Object type. On the “Display a System Function” screen, select option 1 for distributed queueing; the next screen shows you the port number that your system is using, as shown in Figure 15-14.

Figure 15-14. MQSeries for OS/390: Display a System Function

The following guidlines will help you run the application for the workstation:

Table 15-1 lists the ways of checking errors that may occur when you are trying to make the connections between CICS and MQSeries and Windows NT and OS/390.

Figure 15-15. Input screen of MQSeries-Java client