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, 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
|---->simple-jndi
|---->*.properties
|----><src>
|---->**/*.java
|----><zos>
|----><C370>
|---->*.C
|---->*.H
|----><JCL>
|---->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 JCLs used by LegStar to compile and link-edit these sources are available from here.
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 endpoint configuration references WebSohere MQ resources that must be available through JNDI.
The relevant endpoint elements for the MQ Transport in the configuration file are:
| hostMQBridgeType | Mandatory | Specify MQCIH to use IBM CICS MQ Bridge, LSMSG otherwise. |
| initialContextFactory | Mandatory | The JNDI initial context factory |
| jndiProviderURL | Optional | The JNDI provider URL |
| jndiUrlPkgPrefixes | Optional | The JNDI provider list of package prefixes |
| jndiProperties | Optional | Additional JNDI provider properties as comma-separated list of key=value pairs |
| jndiConnectionFactoryName | Mandatory | The Websphere MQ connection factory JNDI name |
| jndiRequestQueueName | Mandatory | The Websphere MQ request queue JNDI name |
| jndiReplyQueueName | Mandatory | The Websphere MQ reply queue JNDI name |
| hostCharset | Optional | A valid mainframe character set such as IBM01140 |
| hostUserID | Optional | A host user ID |
| hostPassword | Optional | A host password |
hostCharset, hostUserID and hostPassword can be provided as part of the request Address if they are not provided in the configuration file.
Refer to the samples/quickstarts/cmqrt/readme.txt for instructions on how to run the sample provided.