************************************************************
AppConn Java Connector version 6.5
July, 2006

Attachmate Verastream(r) Host Integrator
Copyright (c) 1999 - 2006 Attachmate Corporation.
All rights reserved.

Readme for Host Integrator XML messaging1 demo for Windows.
************************************************************



Contents
--------
A. Description
B. Files
C. Pre-requisites
D. Environment Variables
E. Building the Demo
F. Running the Demo
G. What the Demo is doing.
H. What the Demo does not do
I. Modifying the Demo to run with other JMS-based messaging systems.
J. Limitations


A. Description
--------------

This demo is designed to show how to set up a simple
messaging system for sending/retrieving XML-based messages
to/from Verastream Host Integrator (VHI).

This demo was run and tested using Sun's Java Message Queue 1.1
and the Java Message Service (JMS) API.  JMQ is a relatively
simple messaging system that is easy to install and run.

You can download a developers' trial version of JMQ 1.1 at the
following web site: http://www.sun.com/workshop/jmq/

You can find out more information on the JMS at the following
site: http://java.sun.com/products/jms/index.html

(If either of these websites changes in the future, you can start
by looking at http://java.sun.com)



B. Files Included
-----------------
compile.bat		A DOS script for building the demo.

MessageListener.java    source code for demo.
MessageClient.java
MessageListenerException.java
MessageClientException.java
Shutdown.java

*.class                 All the class files, precompiled.

runMessageListener.bat  A DOS script to run MessageListener.class
runMessageClient.bat    A DOS script to run MessageClient.class
runShutdown.bat         A DOS script to run Shutdown.class

test.xml                A set of AppConn XML commands that this demo
                        will execute against the CICSAccts model.


C. Prerequisites
----------------
Before you begin, be sure you do the following:

1.  Verastream Host Integrator (VHI) must be installed.  You will need to have
    the VHI session server, the AADS server, the Host Emulator, and the Administrative
    Webstation installed and working properly.

2.  If you wish to modify and compile the demo, install Java jdk 1.5 or later
    (skip this step if you want to run against the pre-compiled class files.).

3.  Install Sun's Java Message Queue 1.1 and verify that it
    is running. Make sure you know how to start the messaging
    router. We highly recommend that you run some of the JMQ demos
    that Sun provides with JMQ 1.1 to verify your JMQ system is operational.


D. Environment Variables
------------------------
Before building or running this demo you must have the
following environment variable set:

  JMQ_HOME   Location of JMQ installation.  This should have
             been a part of your installation for JMQ 1.1

In the shell files (mentioned in B) you will need to set
VHI_ROOT to reflect your system's Verastream Host Integrator
root install path (i.e. c:\Progra~1\VHI).


E. Building the Demo
--------------------
This demo is already compiled, so you can proceed directly to
"Running the Demo." If you choose to build the demo,
however, follow these steps:

1.  Examine the compile.bat file and make sure the
    environment variables reflect your local system.

2.  Run the compile.bat script file.



F. Running the Demo
-------------------

1.  Have VHI session server running on your localhost.

2.  Using the Administrative Webstation, make sure the session server
    has the CICSAccts model loaded.  You may need to load it yourself.
    Do this by navigating to the Model Configuration\Models item for
    your particular server.  Make sure you are in "Config" mode by
    selecting the Config Mode button at the top of the Webstation
    window.  Select the Add Model button and add the CICSAccts model.
    It should be configured to run on the Host Name = localhost and
    Host Port ID = 1097.

3.  Start the Host Emulator, if it is not already started.  Select the
    "Configure Host Emulator" icon in your Start Menu:
    Programs\Verastream Host Integrator\Host Emulator\Configure Host Emulator.
    Make sure the CICSAcctsMaster model is being served by the Host
    Emulator and is using the same port as in #2 above (port 1097).
    If the CICSAcctsMaster model is not loaded, click on the "Add Model"
    button and select this model from the Name dropdown box.


4.  Start the JMQ router. You should already know how to do this
    by virture of installing and testing JMQ 1.1

5.  Open a DOS shell window.  Change directory
    to the messaging1 folder. Type "runMessageListener".

    You should see the MessageListener initialize and
    the following lines should appear in the window.

    Creating a new connection factory.
    Creating a new connection.
    Creating a new queue session.
    Creating sender and receiver.
    Creating a Table instance of AppConnXML.
    Server is started and listening for incoming messages on Queue: MESSAGINGQ_1


5.  Open a second DOS shell window. Change directory
    to the messaging1 folder.

    Type "runClient test.xml"

    The MessageClient class will build and send a message,
    containing the XML commands from test.xml, to the queue
    MESSAGINGQ_1.  When MessageClient receives the response
    message, it will print the contents to the screen and
    write them to an output file, named messageclient_out.xml.
    If you have Internet Explorer 5.0 or later, you can view
    messageclient_out.xml as a formatted XML document in the
    browser.


6.  To shut down the MessageListener, do the following:
    From the same command window in which you just executed
    runClient, type "runShutdown".  This will run the
    Shutdown class which simply connects to the messaging
    system and sends a shutdown message to MessageListener.
    MessageListener will then perform an orderly shutdown
    of all messaging and Verastream-related resources. The
    Shutdown class is, in effect, a very simple administrative
    console.



G. What the Demo is doing.
--------------------------

This is a very simple demo.  MessageClient reads the
XML-formatted AppConn commands in test.xml, puts them into the
payload of a JMS TextMessage and sends it to the MESSAGINGQ_1
queue.  Since MessageListener is the only listener on this queue,
the JMQ router sends the message to it.  Message Listener unpacks
the payload and gives the XML AppConn commands to its private
instance of AppConnXML.  AppConnXML processes the AppConn commands
and returns an XML-formated String result which is placed in the
payload of a reply message that is sent back to MessageClient.
MessageClient has blocked on receiving the reply message.  When it
receives the reply, MessageClient writes it to a text file, named
messageclient_out.xml.  Then MessageClient quits. MessageListener
is still running and can service more messages, until it is shutdown
with the runShutDown script.


H. What the Demo does not do
----------------------------
This is a very simple demo. It is not meant to be a fully
capable, enterprise message-processing system.  This demo
simply demonstrates the basics of sending/receiving XML-based
messages for use with Verastream Host Integrator. The demo does not
handle durability of messages if the server goes down.


I. Modifying the Demo to run with other JMS-based messaging systems.
--------------------------------------------------------------------
Currently, the code in MessageListener, MessageClient, and Shutdown
that sets up the messaging system does not use JNDI.  If you examine
the code, you will see that it uses Sun's QueueConnectionFactory explicitly:

com.sun.messaging.QueueConnectionFactory
     aQConnectionFactory = new com.sun.messaging.QueueConnectionFactory();

This will have to be replaced with a JNDI-based lookup or
your specific system's QueueConnectionFactory if you wish
to run the demo with another JMS-capable messaging system
(i.e. IBM's MQSeries).


J. Limitations
--------------
1.  Error detection is minimal.

2.  If you had to ctrl-C to stop the MessageListener, you
    may have messages remaining in the JMQ system folders.
    In this case, you may need to go to your JMQ install
    folder and look under /res/sys/foldername where "foldername"
    is a unique name, (like ap96d78daf.0). In this folder
    you can delete the XXX.dat files (old messages) after
    first closing the Java Message Queue message router.
    After deleting these files, you can restart the JMQ
    message router.

3.  The MessageListener instantiates a Table-layer instance
    of AppConnXML.  That is to say, it can only service AppConn
    commands that are part of the Table command set (the methods
    of the AppConnTable and AppConnChannel interfaces).  If
    you modify the test.xml file to contain Model-layer commands,
    the demo should function correctly, but the XML returned from
    MessageListener will have error messages in it, pertaining to
    your improper use of Model commands with a Table instance
    of AppConnXML.  See the Java docs on the AppConnXML constructors
    for more information on Table vs Model instances of AppConnXML.

4.  The file test.xml tries to connect to the model CICSAccts on
    localhost.  If you want to try connecting to a VHI session server
    on another machine, you will need to edit test.xml and change the
    servername value in the connecttomodel command.  Also, make sure
    that the VHI session server you connect to is servicing the CICSAccts
    model.

5.  We have tested this demo only on Microsoft Windows.  It should
    run on Unix systems with the following changes:
    A. You will need to set up a JMS-enabled messaging system on your
       UNIX machine.
    B. You will need to translate the .bat files in the messaging1 folder
       to their UNIX shell script equivalents.







[end of file]