This chapter tells you how to configure WebSphere MQ middleware:
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.
Full details about WebSphere MQ can be found in your WebSphere MQ documentation, particularly IBM WebSphere MQ Intercommunication.
The main WebSphere MQ objects required for SOA Express are:
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)
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.
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:
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
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)
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)
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)
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)
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)
The middle-tier computer's receiver channel.
DEFINE CHANNEL(Mainframe.MidTier.TCP) + CHLTYPE(RCVR) + TRPTYPE(TCP)
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:
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
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)
The local queue used for MMTM triggering.
DEFINE QLOCAL(MICROFOCUS.CG.INITQ) + LIKE(SYSTEM.DEFAULT.LOCALQ)
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)
The process that contains the transaction ID of the Micro Focus Message Trigger Monitor.
DEFINE PROCESS(MICROFOCUS.CG.MWI.PROCESS) + APPLTYPE(CICS) APPLCID(MMTM)
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)
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)
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)
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)
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:
We recommend that you put these commands in a startup script to ensure that CKTI is restarted when CICS is restarted.
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
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)
The local queue used for MMTM triggering.
DEFINE QLOCAL(MICROFOCUS.CG.INITQ) + LIKE(SYSTEM.DEFAULT.LOCALQ)
The process that contains the transaction ID of the Micro Focus Message Trigger Monitor.
DEFINE PROCESS(MICROFOCUS.CG.MWI.PROCESS) + APPLTYPE(CICS) APPLCID(MMTM)
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)
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.
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.
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.
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.
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)
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.
Copyright © 2007 Micro Focus (IP) Ltd. All rights reserved.