Chapter 6: WebSphere MQ Middleware

This chapter tells you how to configure WebSphere MQ middleware:

On a middle-tier computer and at the mainframe, to support the deployment of eBiz or Data Access Transactions
On a PC on the client tier, to support the testing of eBiz or Data Access Transactions with Mainframe Express.

For details of the WebSphere MQ products that need to be installed on each tier, see the Client Tier, Middle Tier and Mainframe Tier chapters.

WebSphere MQ was formerly called MQSeries. It is still referred to by that name in some places in the SOA Express IDE. Also, WebSphere MQ should not be confused with the WebSphere Application Server.

In this chapter, we assume that the middle tier is physically realized by one or more server-class computers. Although it is possible for the mainframe to host a virtual middle tier, that possibility is not considered further.

In this chapter, we assume that you are using WebSphere MQ Distributed Queue Messaging. We do not consider other approaches such as clustering.

Configuration steps in this chapter apply for both CICS and IMS, except for the setting up of the WebSphere MQ CICS adapter.

Also in this chapter, the term server-server configuration refers to the situation in which WebSphere MQ servers are installed both at the middle-tier computer and at the mainframe. The term client-server configuration means that a WebSphere MQ client is installed on the middle tier and a WebSphere MQ server at the mainframe.

SOA Express and WebSphere MQ

Full details about WebSphere MQ can be found in your WebSphere MQ documentation, particularly IBM WebSphere MQ Intercommunication.

WebSphere MQ Objects Required for SOA Express

The main WebSphere MQ objects required for SOA Express are:

An application queue at the mainframe, on which request messages from the middle-tier computer are placed.
A pool of reply-to queues, on which replies from the mainframe are placed. Reply-to queues are allocated to end-user sessions on a round-robin basis. In a server-server configuration, the pool of queues is held at the middle-tier computer; in a client-server configuration, the pool is held at the mainframe.

For communication in a server-server configuration, matched pairs of sender and receiver message channels are needed, together with their associated transmission queues, at the middle-tier computer and at the mainframe. Because we recommend that you use triggering to ensure these message channels are available, initiation queues are also needed at each end. See Figure 6-1.

Figure 6-1: WebSphere MQ Server-Server Configuration

In contrast, in a client-server configuration, only an MQI server-connection channel is needed and channel triggering is unnecessary. See Figure 6-2.

Figure 6-2: WebSphere MQ Client-Server Configuration

In either case, at the mainframe the CICS task initiator (CKTI) transaction (provided with the WebSphere MQ CICS Adapter) is used to trigger the Micro Focus Message Trigger Monitor (MMTM) transaction whenever there are messages on the application queue. See Figure 6-3.

Figure 6-3: CICS Task Initiator (CKTI)

Defining WebSphere MQ Objects

We recommend that you adopt an extensible naming scheme to define WebSphere MQ objects for SOA Express. Most objects, including queue managers, channels, transmission queues and the application queue, can be re-used by several SOA Express projects. Other objects, such as the reply-to queues, are usually re-usable but can be given project-specific names if this is deemed desirable.

In all cases you will find it useful to construct names from a set of standard identifiers. For example, the template commands in this chapter use the placeholders MidTier and Mainframe; in your organization, these might be instantiated as DEPLOY1 and MVSHOST. In WebSphere MQ, use of the dot separator in names has no functional significance. Refer to your WebSphere MQ documentation for other rules on naming objects.

The template commands in this chapter are shown as command line WebSphere MQ commands, to ensure cross-platform commonality. With WebSphere MQ for Windows, UNIX and Linux, you can define objects by using the WebSphere MQ Explorer snap-in for the Microsoft Management Console, or the WebSphere MQ Web Administration application. You can also define objects by using an Interactive System Productivity Facility (ISPF) panel interface. For more information, refer to your IBM WebSphere MQ Command Reference.

Server-Server Configuration

This section deals with the situation where WebSphere MQ Server is installed at both the middle-tier computer and the mainframe. This implies separate queue managers, which must be configured to communicate with each other by means of matched pairs of sender and receiver channels.

The discussion makes the following assumptions:

WebSphere MQ is installed and you have already defined the queue managers at each end.
WebSphere MQ's triggering feature is used to ensure that a sender channel is always available when a message is ready to be sent. (This is optional, you may decide to use some other means of ensuring that sender channels are available.)
The sender and receiver message channels use the TCP/IP communication protocol. If you want to use SNA or some other protocol instead, refer to your WebSphere MQ documentation for guidance on the correct WebSphere MQ commands to use.
For CICS, WebSphere MQ's triggering feature is used to activate the Micro Focus Message Trigger Monitor, MMTM, whenever a message is received at the mainframe. (This use of triggering is mandatory.)
For IMS no trigger is needed. See the chapter IMS Support in your User's Guide and the appendix Deploying IMS eBiz Transactions in your Deployment Guide.

At the Middle-Tier Computer

Here are the WebSphere MQ objects that must be defined at the middle-tier computer, with templates for the corresponding WebSphere MQ commands. Refer to Figure 6-4.

Figure 6-4: WebSphere MQ Objects at the Middle Tier

Reply-to queues
A pool of local queues to accept replies from the mainframe. Each name is constructed from a root Reply-to_Queue_Name and a two-digit suffix. The default root name on the SOA Express Project Properties dialog is CG.WS.REPLY and the default number of queues is 3, so the default reply-to queues are named CG.WS.REPLY01, CG.WS.REPLY02 and CG.WS.REPLY03. For details of those WebSphere MQ objects which need to be specified on the SOA Express Project Properties dialog, see the section Specifying WebSphere MQ Parameters in the SOA Express IDE
```
DEFINE QLOCAL(Reply-to_Queue_Name01) +
       SHARE DEFSOPT(SHARED)

DEFINE QLOCAL(Reply-to_Queue_Name02) +
       SHARE DEFSOPT(SHARED)

DEFINE QLOCAL(Reply-to_Queue_Name03) +
       SHARE DEFSOPT(SHARED)
...
DEFINE QLOCAL(Reply-to_Queue_NameXX) +
       SHARE DEFSOPT(SHARED)
```
Transmission queue
The local queue for messages ready to be transmitted to the mainframe. By convention, it has the same name as the mainframe's WebSphere MQ queue manager. The definition refers to an initiation queue which triggers the sender MCA when the first message is placed on the queue. If you do not intend to use channel triggering, omit the INITQ, TRIGGER, TRIGTYPE and TRIGDATA parameters.
```
DEFINE QLOCAL(Mainframe_Queue_Manager_Name) +
       USAGE(XMITQ) +
       INITQ(MidTier.Mainframe.CHINIT.QUEUE) +
       TRIGGER TRIGTYPE(FIRST) +
       TRIGDATA(MidTier.Mainframe.TCP)
```
Channel initiation queue
The local queue used for sender channel triggering. If you do not intend to use channel triggering, omit this definition.
```
DEFINE QLOCAL(MidTier.Mainframe.CHINIT.QUEUE) +
       LIKE(SYSTEM.DEFAULT.LOCAL.QUEUE)
```
Application queue
A remote queue object corresponding to the application queue at the mainframe (the RNAME parameter) on which messages from the middle-tier computer are received. The definition identifies the remote queue manager and refers to the middle-tier computer's transmission queue. Be sure that QREMOTE and RNAME are identical.
```
DEFINE QREMOTE(Application_Queue_Name) +
       RNAME(Application_Queue_Name) +
       RQMNAME('Mainframe_Queue_Manager_Name') +
       XMITQ(Mainframe_Queue_Manager_Name)
```
Sender channel
The middle-tier computer's sender channel. The Mainframe_HostName may be either a DNS name or an IP address. The default PortNo is 1414. You should verify the port number in use on the mainframe. If the default port number is being used, you can omit the PortNo parameter.
```
DEFINE CHANNEL(MidTier.Mainframe.TCP) +
       CHLTYPE(SDR) +
       TRPTYPE(TCP) +
       CONNAME('Mainframe_HostName(PortNo)') +
       XMITQ(Mainframe_Queue_Manager_Name)
```

Receiver channel

The middle-tier computer's receiver channel.

DEFINE CHANNEL(Mainframe.MidTier.TCP) +
       CHLTYPE(RCVR) +
       TRPTYPE(TCP)

Java server-connection channel (JavaBeans and EJB only; not needed for .NET)
An MQI server-connection channel between the queue manager at the middle-tier computer and the middle-tier MWI which, by means of the WebSphere MQ classes for Java, appears as a WebSphere MQ Java client. This channel must use TCP/IP.
```
DEFINE CHANNEL(MidTier.JAVA.TCP) +
       CHLTYPE(SVRCONN) +
       TRPTYPE(TCP)
```
There is no need to define an MQI client-connection channel as this is implicit in the WebSphere MQ classes for Java.

For channel triggering to work, the middle-tier computer's channel initiator must be started as follows:

Enter RUNMQSC to start the WebSphere MQ command interpreter.
Enter START CHINIT INITQ(MidTier.Mainframe.CHINIT.QUEUE).
Enter END to exit.

At the Mainframe

Here are the WebSphere MQ objects that must be defined at the mainframe, with templates for the corresponding WebSphere MQ commands. Refer to Figure 6-5.

Figure 6-5: WebSphere MQ Objects at the Mainframe

Application queue
The local queue upon which all SOA Express-related messages are received.

For CICS, the definition refers to an initiation queue which, via the CICS task initiator CKTI, triggers the Micro Focus Message Trigger Monitor transaction MMTM the first time a message is placed on the queue.

For IMS, the application queue is specified as part of the Mainframe Access server configuration for SOA Express IMS. (In Mainframe Express, the queue is specified on a JCL parameter.)

In either case, Mainframe Access (or Mainframe Express) monitors the designated queue.

For CICS:
```
DEFINE QLOCAL(Application_Queue_Name) +
       LIKE(SYSTEM.DEFAULT.LOCALQ) +
       INITQ(MICROFOCUS.CG.INITQ) +
       PROCESS(MICROFOCUS.CG.MWI.PROCESS) +
       TRIGGER TRIGTYPE(FIRST) +
       SHARE DEFSOPT(SHARED)
```
For IMS:
```
DEFINE QLOCAL(Application_Queue_Name) +
       LIKE(SYSTEM.DEFAULT.LOCALQ) +
       SHARE DEFSOPT(SHARED)
```
MMTM initiation queue (CICS only)
The local queue used for MMTM triggering.
```
DEFINE QLOCAL(MICROFOCUS.CG.INITQ) +
       LIKE(SYSTEM.DEFAULT.LOCALQ)
```
Channel initiation queue
The local queue used for sender channel triggering. If you are not using channel triggering, omit this definition.
```
DEFINE QLOCAL(Mainframe.MidTier.CHINIT.QUEUE) +
       LIKE(SYSTEM.DEFAULT.LOCALQ)
```
MMTM initiation process (CICS only)
The process that contains the transaction ID of the Micro Focus Message Trigger Monitor.
```
DEFINE PROCESS(MICROFOCUS.CG.MWI.PROCESS) +
       APPLTYPE(CICS) APPLCID(MMTM)
```
Channel initiation process (CICS only)
The process that activates the CICS sender MCA transaction CKSG. If you are not using channel triggering, omit this definition.
```
DEFINE PROCESS(Mainframe.MidTier.CHINIT.PROCESS) +
       APPLTYPE(CICS) APPLCID(CKSG) +
       USERDATA(Mainframe.MidTier.TCP)
```
Transmission queue
The local queue for messages ready to be transmitted back to the middle-tier computer. By convention, it has the same name as the middle-tier server's queue manager. The definition refers to an initiation queue and an associated process which triggers the sender MCA when the first message is placed on the queue. If you are not using channel triggering, omit the INITQ, TRIGGER, TRIGTYPE and PROCESS parameters.
```
DEFINE QLOCAL(MidTier_Queue_Manager_Name) +
       USAGE(XMITQ) +
       INITQ(Mainframe.MidTier.CHINIT.QUEUE) +
       TRIGGER TRIGTYPE(FIRST) +
       PROCESS(Mainframe.MidTier.CHINIT.PROCESS)
```

Reply-to queues

Remote queue objects corresponding to the reply-to queues at the middle-tier computer. The number of remote definitions for reply-to queues should match the number of reply queues defined on the middle tier. Be sure that QREMOTE and RNAME are identical.

DEFINE QREMOTE(Reply-to_Queue_Name01) +
       RNAME(Reply-to_Queue_Name01) +
       RQMNAME('MidTier_Queue_Manager_Name') +
       XMITQ(MidTier_Queue_Manager_Name)

DEFINE QREMOTE(Reply-to_Queue_Name02) +
       RNAME(Reply-to_Queue_Name02) +
       RQMNAME('MidTier_Queue_Manager_Name') +
       XMITQ(MidTier_Queue_Manager_Name)

DEFINE QREMOTE(Reply-to_Queue_Name03) +
       RNAME(Reply-to_Queue_Name03) +
       RQMNAME('MidTier_Queue_Manager_Name') +
       XMITQ(MidTier_Queue_Manager_Name)
...
DEFINE QREMOTE(Reply-to_Queue_NameXX) +
       RNAME(Reply-to_Queue_NameXX) +
       RQMNAME('MidTier_Queue_Manager_Name') +
       XMITQ(MidTier_Queue_Manager_Name)

Sender channel
The mainframe's sender channel. TheMidTier_HostName can be either a DNS name or an IP address. The default PortNo is 1414. You should verify the port number in use on the middle tier. If the default port number is being used, you can omit the PortNo parameter.
```
DEFINE CHANNEL(Mainframe.MidTier.TCP) +
       CHLTYPE(SDR) +
       TRPTYPE(TCP) +
       CONNAME('MidTier_HostName(PortNo)') +
       XMITQ(MidTier_Queue_Manager_Name)
```

Receiver channel

The mainframe's receiver channel.

DEFINE CHANNEL(MidTier.Mainframe.TCP) +
       CHLTYPE(RCVR) +
       TRPTYPE(TCP)

(CICS only) For both MMTM and channel triggering to work, two instances of the CICS task initiator CKTI must be started:

Enter CKQC STARTCKTI MICROFOCUS.CG.INITQ at the CICS command line.
Enter CKQC STARTCKTI Mainframe.MidTier.CHINIT.QUEUE. (Omit this step if you are not using channel triggering.)

We recommend that you put these commands in a startup script to ensure that CKTI is restarted when CICS is restarted.

Client-Server Configuration

This section deals with the situation where a WebSphere MQ Client is installed at the middle-tier computer, rather than a WebSphere MQ server. In this case, the WebSphere MQ client is owned by the queue manager in the WebSphere MQ Server running on the mainframe. There is no concept of a remote queue, as all queues are local to the queue manager at the mainframe. A single bidirectional server-connection (SVRCONN) channel is used instead of pairs of sender and receiver channels, and channel triggering is not required.

The discussion assumes that WebSphere MQ is installed and that you have already defined the queue manager.

Here are the WebSphere MQ objects that must defined at the mainframe, with templates for the corresponding WebSphere MQ commands. No objects need be defined at the middle-tier computer. Refer to Figure 6-6.

Figure 6-6: WebSphere MQ Objects at the Mainframe

Application queue
The local queue upon which all SOA Express-related messages are received.

For CICS, the definition refers to an initiation queue which, via the CICS task initiator CKTI, triggers the Micro Focus Message Trigger Monitor transaction MMTM the first time a message is placed on the queue.

For IMS, the application queue is specified as part of the Mainframe Access server configuration for SOA Express IMS. (In Mainframe Express, the queue is specified on a JCL parameter.)

In either case, Mainframe Access (or Mainframe Express) monitors the designated queue.

For CICS:
```
DEFINE QLOCAL(Application_Queue_Name) +
       LIKE(SYSTEM.DEFAULT.LOCALQ) +
       INITQ(MICROFOCUS.CG.INITQ) +
       PROCESS(MICROFOCUS.CG.MWI.PROCESS) +
       TRIGGER TRIGTYPE(FIRST) +
       SHARE DEFSOPT(SHARED)
```
For IMS:
```
DEFINE QLOCAL(Application_Queue_Name) +
       LIKE(SYSTEM.DEFAULT.LOCALQ) +
       SHARE DEFSOPT(SHARED)
```
MMTM initiation queue (CICS only)
The local queue used for MMTM triggering.
```
DEFINE QLOCAL(MICROFOCUS.CG.INITQ) +
       LIKE(SYSTEM.DEFAULT.LOCALQ)
```
MMTM initiation process (CICS only)
The process that contains the transaction ID of the Micro Focus Message Trigger Monitor.
```
DEFINE PROCESS(MICROFOCUS.CG.MWI.PROCESS) +
       APPLTYPE(CICS) APPLCID(MMTM)
```

Reply-to queues

A pool of local queues to accept replies from the mainframe. Each name is constructed from a root Reply-to_Queue_Name and a two-digit suffix. The default root name is CG.WS.REPLY and the default number of queues is 3.

DEFINE QLOCAL(Reply-to_Queue_Name01) +
       SHARE DEFSOPT(SHARED)

DEFINE QLOCAL(Reply-to_Queue_Name02) +
       SHARE DEFSOPT(SHARED)

DEFINE QLOCAL(Reply-to_Queue_Name03) +
       SHARE DEFSOPT(SHARED)
...
DEFINE QLOCAL(Reply-to_Queue_NameXX) +
       SHARE DEFSOPT(SHARED)

Java server-connection channel (JavaBeans and EJB only; not needed for .NET)
An MQI server-connection channel between the queue manager at the mainframe and the middle-tier MWI which, by means of the WebSphere MQ classes for Java, appears as a WebSphere MQ client. Note that this channel must use TCP/IP.
```
DEFINE CHANNEL(MidTier.JAVA.TCP) +
       CHLTYPE(SVRCONN) +
       TRPTYPE(TCP)
```
There is no need to define an MQI client-connection channel as this is implicit in the WebSphere MQ classes for Java.

For MMTM triggering to work, the CICS task initiator, CKTI, must be started as follows from the CICS command line:

CKQC STARTCKTI MICROFOCUS.CG.INITQ

We recommend that you put this command in a startup script to ensure that CKTI is restarted when CICS is restarted.

Specifying WebSphere MQ Parameters in the SOA Express IDE

The names of some WebSphere MQ objects need to be specified within the SOA Express IDE for each project. In particular, you need to specify the items below (template names shown in brackets, where applicable). It is important to understand that you merely specify the objects in the SOA Express IDE, you do not define them. The objects must be defined with WebSphere MQ commands, as described earlier.

Java server-connection channel name MidTier.JAVA.TCP (JavaBeans and EJB only; specify a dummy name for .NET)
DNS name or IP address of the computer that hosts the local WebSphere MQ queue manager (either MidTier_HostName for a server-server configuration or Mainframe_HostName for a client-server configuration)
IP port number used by the local WebSphere MQ queue manager (the default is 1414)
Local WebSphere MQ queue manager name (either MidTier_Queue_Manager_Name for a server-server configuration or Mainframe_Queue_Manager_Name for a client-server configuration)
Application queue name (Application_Queue_Name)
Reply-to queue prefix (Reply-to_Queue_Name; the default is CG.WS.REPLY)
Number of reply-to queues (the default is 3)

The reply-to queue prefix and the number of reply-to queues together specify the names of the reply-to queue objects. Thus the default values of CG.WS.REPLY and 3 specify queues named CG.WS.REPLY01, CG.WS.REPLY02 and CG.WS.REPLY03.

In the SOA Express IDE, you can save the settings you've entered, as a named configuration. You can load a saved configuration by name, so you don't need to re-enter all the details. You may find this especially useful if you are switching back and forth between using mainframe emulation and using the real mainframe.

How to...

Defining WebSphere MQ Objects for Mainframe Emulation

This section assumes you have read the section Defining WebSphere MQ Objects.

You can set up a mainframe emulation environment at a PC on the client tier using Micro Focus Mainframe Express and IBM WebSphere MQ Server. This enables you to test the eBiz Transactions generated by SOA Express without necessarily affecting your mainframe's operation. Mainframe Express CICS Option includes an emulation of the CICS task initiator, CKTI. For more information, see the section on Mainframe Emulation Environment in the chapter Client Tier. For information on configuring Mainframe Express for use with eBiz or Data Access Transactions, see your User's Guide and the Mainframe Express CICS Option Technical Guide.

Server-Server Configuration

This section assumes that the middle-tier computer and the emulating PC are two different machines.

At the emulating PC, you need to define mostly the same WebSphere MQ objects as you would at the mainframe, with the exception of those items listed below.

All WebSphere MQ queue manager names on a network should be unique. You must, therefore, use a different queue manager name on the Mainframe Express PC to that used on the mainframe. This means that you must also alter the queue manager name in the WebSphere MQ parameters specified within the SOA Express IDE and that the middle-tier components must be regenerated for production.

For IMS, as shown above in the section At the Mainframe in the section Server-Server Configuration in the section Defining WebSphere MQ Objects, the application queue definition does not need the PROCESS, Initiation queue, or triggering parameters.

For CICS, the CKSG transaction supplied by the WebSphere MQ CICS Adapter is not available (and is not emulated by Mainframe Express CICS Option). Therefore, if you want to use channel triggering you need to use a different definition for the transmission queue, and the channel initiation process definition (Mainframe.MidTier.CHINIT.PROCESS) can be omitted. The revised transmission queue definition is:

DEFINE QLOCAL(MidTier_Queue_Manager_Name) +
       USAGE(XMITQ) +
       INITQ(Mainframe.MidTier.CHINIT.QUEUE) +
       TRIGGER TRIGTYPE(FIRST) +
       TRIGDATA(Mainframe.MidTier.TCP)

At the middle-tier computer, you must temporarily redefine the sender channel so that it refers to the DNS name or IP address of the emulating PC rather than the mainframe:

DEFINE CHANNEL(MidTier.Mainframe.TCP) +
       CHLTYPE(SDR) +
       TRPTYPE(TCP) +
       CONNAME('PC_HostName(PortNo)') +
       XMITQ(Mainframe_Queue_Manager_Name)

Client-Server Configuration

If WebSphere MQ is installed on the emulating PC, define exactly the same WebSphere MQ objects at the emulating PC as you would at the mainframe with the exception of the queue manager name. Specify the name of the queue manager running on the emulating PC in the WebSphere MQ parameters in the SOA Express IDE.

You can install the WebSphere MQ Client on both the middle-tier computer and the emulating PC, provided that both clients are owned by the same queue manager - for example, the WebSphere MQ Clients on the middle tier and the emulating PC might be owned by the queue manager running on the mainframe. In this case, refer to the WebSphere MQ Client-Server configuration definitions shown in the previous section and define the same WebSphere MQ objects on the owning queue manager (WebSphere MQ Server) machine. Specify the name of the owning queue manager in the WebSphere MQ parameters in the SOA Express IDE.

In the client-server configuration, no objects need to be defined on the middle tier, but you must temporarily change the WebSphere MQ host name and port parameters (specified within the SOA Express IDE) to refer to the host name and port of the machine running the owning queue manager (either another PC running WebSphere MQ Server or the mainframe).

These changes mean that the middle-tier components must be regenerated for production.