 -----
 Release Notes
 -----

PREREQUISITES:

 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 {{{../legstar-distribution-zos/index.html}here}}.

 The main C370 program for Cmqrt is {{{./LSMQHBIN-readme.html}LSMQHBIN, the CICS
 Server for WebSphere MQ}}. This program uses the following libraries:

 * {{{../legstar-invoker/LSLNKBIN-readme.html}LSLNKBIN CICS LINK library}}

 * {{{../legstar-invoker/LSLNKCOM-readme.html}LSLNKCOM CICS COMMAREA LINK library}}

 * {{{../legstar-invoker/LSLNKCTN-readme.html}LSLNKCTN CICS CONTAINERS LINK library}}

 * {{{../legstar-messaging/LSMSGLIB-readme.html}LSMSGLIB Messaging library}}

 * {{{../legstar-messaging/LSCOMLOG-readme.html}LSCOMLOG Tracing and logging library}}

[]

 If you need to regulate LSMQHBIN activity (high volumes for instance) read 
 the {{{./LSMQCBIN-readme.html}LSMQCBIN readme}}document.

 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.
 
INSTALLING/UNINSTALLING:

 These instructions apply if you are installing from the Cmqrt standalone
 distribution. If you are installing the complete LegStar distribution please
 refer to {{{http://www.legsem.com/legstar/legstar-distribution/install-instructions.html}legstar distribution}}.

 [[1]] Unzip the binary distribution package into the directory of your choice,
       referred to as <installDir> in the following steps.

   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
                
+---------------------------------------+
   
 [[2]] Install the LegStar mainframe C370 programs.
 
 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
 {{{../legstar-distribution-zos/install-instructions.html}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 {{{../legstar-distribution-zos/index.html}here}}.
 
 Finally each module has some documentation under zos/docs.
   
 [[3]] To uninstall, remove the installDir folder.
 
CONFIGURING AND RUNNING THE SAMPLE:

 [[1]]  Setup Queues and Triggers:
 
 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.
 
 [[2]] Setup the invoker configuration:

 The WebSphere MQ Transport expects a configuration file such as the
 {{{./samples/legstar-invoker-config.xml}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.
  
 [[3]] Run the sample provided:
 
 Refer to the samples/quickstarts/cmqrt/readme.txt for instructions on how to run the sample provided.


