#**********************************************************************#
#*                                                                    *#
#* Copyright (c) 2001 by Sun Microsystems, Inc.                       *#
#* All rights reserved.                                               *#
#*                                                                    *#
#**********************************************************************#

Application Overview
--------------------
There are two applications that demonstrate the use of a JCICS transaction
triggered by the WebSphere MQ trigger monitoring facility within a Sun MTP 
environment.

The first application takes a person's name as input and submits a request 
to a JCICS program for the alias for that corresponds to the name. The name 
and alias together constitute the resulting output message, which is written
to the unikixmain.log file. This application demonstrates the use of the 
JMS API and the JCICS API. The application program name is GetAliasJMSListener.

The second application is similar in that it requests an alias that corresponds
to a name application. However, it also demonstrates the use of the MQ JMS API
for opening a connection to an MQ output queue where the output message is
placed. The application program name is GetAliasJMSListenerExMQJMS.

Prerequisites and Reference
---------------------------
Perform the following tasks:

1.  Install the Java(tm) Development Kit (JDK) 1.4 (or later).

2.  Install and configure WebSphere MQ Client on the same system where the 
    Sun MTP region is running.

3.  Install and configure WebSphere MQ Server on a host that is accessible 
    to the Sun MTP host via TCP/IP communications.  
    
    This example assumes that Sun MTP and MQ Server are running on the same
    host.  
   
4.  If Sun MTP and MQ Server are not running on the same host, you must
    compile the kixmqtst program on the host that is running MQ Server.
    
    a.  Copy the C source files and the data file MQCOBAppl_GetAlias.data to 
        the host running MQ Server. 
    
    b.  Build the application according to compiler and MQ specifications for 
        that host.
        
5.  From the MQ administrator, get the port number for the MQ listener.
   
    You will need this information when you are executing the application.

Refer to the Sun MTP Configuration Guide for information about configuring
the unikixrc.cfg file for MQ clients. Refer to the Sun MTP Developer's
Guide for information about using the MQ-JMS Bridge with Sun MTP.


Contents of Directories
-----------------------
     ### Java JMS application source files ###
     ------------------------------------------
         progs/GetAliasJMSListener.java
         progs/GetAliasJMSListenerExMQJMS.java
         progs/GetAlias.java
         progs/GetAliasCommAreaRecord.java
         progs/GetAliasDPL.java
         progs/GetAliasInMemoryStore.java
         progs/NameAlias.java

     ### Resource tables and properties file for the Sun MTP region ###
     ------------------------------------------------------------------
         sys/gct.tbl
         sys/pct.tbl
         sys/snt.tbl
         sys/ppt.tbl
	 sys/jva.tbl
	 sys/unikixrc.cfg

     ### C program (kixmqtst) for loading the MQ queue ###
     -----------------------------------------------------
         progs/kixmqerr.c
         progs/kixmqerr.h
         progs/kixmqtst.c

     ### Data to be loaded by kixmqtst ###
     -------------------------------------
         util/MQJMSAppl_GetAlias.data

     ### MQ configuation command file ###
     ------------------------------------
         util/kixmqtst.mqconfig

     ### makefile for rebuilding or modifying the sample application ###
     --------------------------------------------------------------------
         makefile

     ### MQ-JMS properties, classpath, and librarypath files ###
     -----------------------------------------------------------
         sys/kix_java/MQJMS.properties
	 sys/kix_java/Classpath.appends
	 sys/kix_java/Libpath.appends


Setting Up and Building the Region Executables
----------------------------------------------
1.  Copy the $UNIKIX/examples/mq/jms directory structure to a new
    location.

2.  Change to that directory.

3.  Edit the setup file for your environment.

4.  Source the setup file.

5.  Change to the sys ($KIXSYS) directory.

6.  Verify that the following lines are in the unikixrc.cfg file:

       MQServer*Active:            True
       MQServer*QueueManagerName:  "TESTQM"
       MQServer*QueueName:         "UNIKIX.TRIGGER.QUEUE"
          
7.  Edit the $KIXSYS/kix_java/Classpath.appends file. Uncomment the following
    lines:
       /opt/mqm/java/lib/com.ibm.mqjms.jar
       /opt/mqm/java/lib/com.ibm.mq.jar
       /opt/mqm/java/lib/jms.jar
       /opt/mqm/java/lib/jndi.jar
       /opt/mqm/java/lib/connector.jar
       /opt/mqm/java/lib

    In each of the lines above, change the path to the jar file if necessary.
    For example, you might need to change /opt/mqm to the actual install 
    directory for MQ Client on your system.
    
8.  Edit the $KIXSYS/kix_java/Libpath.appends file. At the end of the file,
    add the following line:
       /opt/mqm/java/lib

    The path /opt/mqm might be different on your system.

9.  Edit the $KIXSYS/kix_java/MQJMS.properties file.
    
    a. Verify that the value for "host" is equal to the host name running 
       MQ Server. If MQ Server is running on the same host as Sun MTP, the 
       default value of "localhost" is acceptable.
    
    b. Verify that the value for "port" is the same as the value from the
       MQSERVER variable and the listener startup command.

    c. If you want to run the second example, GetAliasJMSListenerExMQJMS, edit
       the following lines in the MQJMS.properties file:
       
	  PROG2 = scouser.GetAliasJMSListener
	  #PROG2 = scouser.GetAliasJMSListenerExMQJMS
	  
       so that the GetAliasJMSListener line is commented, and the
       GetAliasJMSListenerExMQJMS line is uncommented. For example:
       
	  #PROG2 = scouser.GetAliasJMSListener
	  PROG2 = scouser.GetAliasJMSListenerExMQJMS
           
     Note: If you want to change from one program to the other, you must
     	   restart the region after editing the MQJMS.properties file.

     See the comments in the MQJMS.properties sample file for more details.

Note: You can skip the next two steps if the region executables have      
      been built using kixinstall and you have selected the
      MQ option.

10.  Change to the $UNIKIX/src directory.

11.  Build the region executables using kixinstall. 


Preparing the Application Components
------------------------------------

1.  Change to the MQ-JMS Bridge sample application directory you created in the
    procedure "Setting Up and Building the Region Executables."

2.  Compile the application components:

     $ make


Starting the Region
-------------------
1.  Start the region.

     $ kixstart


MQ Setup
--------

Perform the following tasks on the MQ Server host machine.

1.  Create an MQ queue manager named TESTQM.

      crtmqm -lf64 -q TESTQM

2.  Start the TESTQM queue manager.

      strmqm TESTQM

3.  Put the sample configuration into the queue manager.

      runmqsc TESTQM < util/kixmqtst.mqconfig

    The kixmqtst.mqconfig file is in the sample directory (mq/jms/util). It
    contains definitions of the queues, procedures, and channel used by the
    test application. If you are running MQ Server on a different host
    than your Sun MTP region, you must copy this file to that host.

4.  Start the listener with the following command:

      runmqlsr -t tcp -m TESTQM -p nnn &

	(nnn is the port number)

5.  Load the MQ input queue with message data from the MQJMSAppl_GetAlias.data
    file:

       kixmqtst -m TESTQM -q UNIKIXMQ1 -i util/MQJMSAppl_GetAlias.data

    This causes the data to be loaded on the input queue and a trigger message
    to be placed on the trigger queue.

6.  The Sun MTP unikixqm daemon process monitors the queue UNIKIX.TRIGGER.QUEUE.
    The trigger monitor starts the MQJV transaction as a result of the trigger
    message placed on the queue in Step 5.

7.  The transaction MQJV puts (WHAT DOES PUTS MEAN HERE???) the data read from
    the queue and starts the appropriate JMS application based on the
    configuration in the MQJMS.properties file.  
    
8.  Verify the results of the sample application:

       - For GetAliasJMSListener, look in the file $KIXSYS/unikixmain.log for
         the name and alias output messages.
       
       - For GetAliasJMSListenerExMQJMS, use the MQ utility amqsgbrc to browse
         the output queue.
	   
	   amqsgbrc UNIKIXMQ2

The following data is defined for the two GetAlias  applications:

       Name				Alias
       -----------------------------  -------------------------------
       George Herman Ruth		The BABE
       Frank Sinatra			Old Blue Eyes
       Daffy Duck			A Fine Feathered Friends
       Davey Jones			Soggy Sailor
       Humpty Dumpty Smith		Crazy Egghead
       Kemo Sabe			The Lone Ranger
       Clark Kent			Superman
       Don Diego de laVega		Zorro
       Elfego Baca			The Dude with Nine Lives
       Randy Johnson			The Big Unit
       Sugar Daddy			Uncle Sam

You can modify the MQJMSAppl_GetAlias.data file and add names, one
per line. If the name added is the same as a name in the 'Name' field
above, the resulting output will contain the corresponding alias. 
If the name is not on the list, the output will be displayed as
"Couldn't match name."  Note that names are case-sensitive.


Shutdown procedures
-------------------
1.  Stop the Sun MTP region using either method:

       - Type the kixstop command at a UNIX shell prompt.
       - Type CSMT SHUT,YES on a blank transaction screen.

2.  Stop the queue managers.

       endmqm TESTQM

    The following message is displayed:
        Quiesce request accepted. The queue manager will stop when all
        outstanding work is complete.

3.  Stop the listener.

       endmqlsr -m TESTQM

    The following message is displayed:
        An MQSeries listener will end shortly.

4.  Delete the TESTQM queue manager.

       dltmqm TESTQM

     The following message is displayed:
        MQSeries queue manager deleted



**********************************************************************
If you are running the MQ queue manager on one platform and the 
Sun MTP region with a JMS application as a client on another 
platform, read the following troubleshooting information.
**********************************************************************

*** Problem #1 ***   ####################################

On the client side, the following error message is written to 
the unikixmain.err log file along with a sizeable Java trace. 
It usually means that the 'host=' argument in the MQJMS.properties file
is set to 'localhost' when it should contain the host name of the 
server platform where the MQ queue manager is running.

java.lang.UnsatisfiedLinkError: /opt/mqm/java/lib/libmqjbnd02.so:
          ld.so.1: unikixtran: fatal: libmqm.so: open failed:
				No such file or directory


Solution: Edit the MQJMS.properties file and retry.


*** Problem #2 ***   ####################################

On the client side, the following error message is written to the
unikixmain.err log file:

07/10/2001 15:39:31 unikixqm    :KIX3001E MQCONN() Error 2  Reason 2035

This error message is the result of an MQ Client attempting a connect
to the queue manager without proper authorization. Refer to the IBM MQ
documentation for an interpretation of the reason code.

Solution:

  1. On the queue manager server, set the MCAUSER(...) argument on the 
     DEFINE CHANNEL command in the kixmqtst.mqconfig file equal to the 
     server's login ID name and restart the MQ queue manager. For example:

	MCAUSER('MQserv_logon_ID')

  2. On the MQ client platform, define the MQ_USER_ID environment variable 
     in the Sun MTP region setup file to the same login ID as in #1 above.
     For example:

	export MQ_USER_ID=MQserv_logon_ID

  3. Restart the Sun MTP region.

Refer to the MQ documentation for additional information.

