You will need WebSphere MQ for z/OS version 5.3 or above.
The only constraint on the z/OS side, apart from having WebSphere MQ installed, is that CICS runs Language Environment (LE).
The triggering mechanism in CICS is provided by the standard CICS MQ Adapter (CKTI). The CICS MQ Adapter must be installed in the target CICS region (Try transaction CKQC to check).
If you decide to use IBM CICS MQ Bridge instead of LegStar on the mainframe side, you need to make sure that it is also installed in the target CICS region (the IBM CICS group CSQCKB must be installed).
If you decide to use LegStar on the mainframe side instead of CICS MQ Bridge, the LegStar mainframe side C370 programs must be installed. The easiest way to do that is to use the common distribution of all LegStar z/OS modules, available here.
The main C370 program for Cmqrt is LSMQHBIN, the CICS Server for WebSphere MQ. This program uses the following libraries:
If you need to regulate LSMQHBIN activity (high volumes for instance) read the LSMQCBIN readmedocument.
Java 1.5+ and ANT 1.6.5+ are both prerequisites for LegStar. Make sure JAVA_HOME and ANT_HOME environment variables are set and that $JAVA_HOME/bin (%JAVA_HOME%/bin on Windows) and $ANT_HOME/bin (%ANT_HOME%/bin on Windows) are both in your system path.
These instructions apply if you are installing from the Cmqrt standalone distribution. If you are installing the complete LegStar distribution please refer to legstar distribution.
The directory tree should look like this:
<installDir>
|---->LICENSE
|---->NOTICE
|---->README
|----><lib>
|---->*.jar
|----><samples>
|----><quickstarts>
|----><cmqrt>
|---->readme.txt
|---->build.xml
|---->legstar-invoker-config.xml
|---->lsfileae.properties
|----><src>
|---->**/*.java
|----><zos>
|----><C370>
|---->*.C
|---->*.H
|----><JCL>
|---->C370*
|---->MQDEFJCL
|----><docs>
|---->*-README
This is needed only if you are not using CICS MQ Bridge.
We encourage you to use the common distribution of all LegStar z/OS modules. Instructions on how to install are available here.
If you decide to install the CICS programs from sources, they are available from the zos folder. The JCL sub folder contains sample compilation JCL that will help you. LSMQHBIN actually uses a library called LSMQLLIB that you need to compile first (see C370CMQL for a sample JCL).
Finally each module has some documentation under zos/docs.
This section describeds Queues and Triggers needed when you use LegStar on the mainframe. In you use CICS MQ Bridge instead, please refer to the IBM documentation.
Use the sample MQDEFJCL as a guide to creating the various MQ resources that are necessary to connect from client to host over MQ. Pay close attention to the PROCESS USERDATA parameters.
Once the MQ resources are created, you need to start CKTI on the new initiation queue that was just created (Use transaction CKQC). You can also have such a transaction start automatically on CICS startup by adding something similar to this in your CICS System initialization parameters:
INITPARM=(CSQCPARM='SN=CSQ1,TN=001,IQ=CICSA.INITQ')
If you decide to use the LSMQCBIN regulation program, then:
Associate the LSMQCBIN program with a CICS transaction (say LEGR) and replace the LEGQ transaction by LEGR as the triggered CICS transaction associated with your trigger process.
If you did not use the RDO JCL that comes with the ZOS common distribution You need to create a TRANCLASS for the handler transaction (usually LEGQ) and set an appropriate MAXACTIVE limit. LSMQCBIN will not start more than MAXACTIVE simultaneous handlers.
The WebSphere MQ Transport expects a configuration file such as the legstar-invoker-config.xml sample provided.
The hostConnectionFactory element in the configuration file must be:
<hostConnectionfactoryClass>com.legstar.mq.client.CicsMQConnectionFactory</hostConnectionfactoryClass>
The relevant endpoint elements for the MQ Transport in the configuration file are:
| hostIPAddress | Mandatory | CICS TCPIP address |
| hostIPPort | Optional | CICS MQ listening TCPIP port (Usually 1414) |
| hostCharset | Optional | A valid character set such as IBM01140 |
| hostUserID | Optional | A host user ID |
| hostPassword | Optional | A host password |
| hostMQManager | Mandatory | The name of the host MQ Manager (exemple CSQ1) |
| hostMQChannel | Mandatory | An MQ channel setup to the host MQ system (exemple CLIENT.TO.FRAME) |
| hostMQRequestQueue | Mandatory | An MQ queue to receive execution requests. See sample MQDEFJCL for definition. |
| hostMQResponseQueue | Mandatory | An MQ queue to receive execution replies. |
| hostMQBridgeType | Mandatory | Specify MQCIH to use IBM CICS MQ Bridge, LSMSG otherwise. |
Parameters marked as optional can be provided as part of the request Address if they are not provided in the configuration file.
Type ant in the samples/quickstarts/cmqrt folder, this should compile and run the test. Check the output of the ant script.
Documentation available at http://www.legsem.com/legstar/legstar-cmqrt