
=head1 INTRODUCTION

This module implements a perl5 API for the IBM MQSeries messaging
middleware product API (often referred to as the MQI), as well as an
Object Oriented interface to the MQI, an OO interface to the MQSeries
administrative commands via PCF or MQSC, and an OO interface to the
Publish/Subscribe subsystem.

For more information on the MQSeries product itself, see the IBM
website at: http://www.ibm.com/software/mqseries

=head1 PREREQUISITES

This release requires perl5.004 or later, and some release of the IBM
MQSeries product installed, either V2, V5.0 or V5.1.

The PubSub extensions, and the RulesFormat message support require
either V5.1, or V5.0 with CSD05 or later.

=head1 PLATFORMS

This package has been known to build with the following combinations
of software.  Those marked with an asterix (*) are platforms the
author can not test personally, so there is a remote possibility that
there may be new bugs in these platforms.  Please report problems to
the author, of course.

  Operating System	MQSeries Version	Perl Version	
  ================	================	============	
  SunOS 5.5.1	        5.0			5.00404
						5.00405
						5.00502
						5.00502 (w/ -Dusethreads)
						5.00503
						5.00503 (w/ -Dusethreads)
  SunOS 5.7		5.1			Same as SunOS 5.5.1
  IRIX 6.5		2.x			Same as SunOS 5.5.1	
  HP-UX 11.0 32bit	5.1			5.00503
  NT 4.0		5.0			AS build 521
  NT 4.0		5.1			AS build 521
 *SuSE Linux 6.3	5.1			5.00503
 *HP-UX 10.20		??			??
 *Redhat Linux 5.2	?? 			??
 *Redhat Linux 6.1	?? 			??

NOTE: The ?? indicates that I received reports of a successful test
suite run, but I never received confirmation of the MQSeries version.
if you have built in on these platforms, *PLEASE* help save the free
world by letting me know what version of MQSeries, compiler, perl,
etc. you built it with.

If you succeed in making this work on any other platform, please send
the changes (in the form of a context diff) to the author, so I can
integrate it.

ANOTHER NOTE: The IRIX 6.5 tests were client only, as we used the
WillowTech port of the 2.x code base, which doesn't include support
for the MQSeries server.  

YET ANOTHER NOTE: I do not have an NT 4.0 MQSeries 5.0 queue manager
against which to test, but the same code works fine for 5.1, so I
assume it will work.  I would appreciate a positive confirmation is
anyone can test this configuration.

=head1 INSTALLATION

This module installs much like anything else available on CPAN.

  perl Makefile.PL
  make
  make test
  make install
                                                                     
Before building the module, you need to edit the CONFIG file and
change, minimally, the name of the queue manager against which the
tests will run.  The rest of the defaults should be reasonable, but
you will have to customize this file to match your local environment.
The CONFIG file has comments which document each of the parameters, so
go read it for more information.

You will obviously need to create the queue used for the test suite on
the queue manager you specified in the CONFIG file.

NOTE: If you do not support client channel table files, then you may
have to set the MQSERVER environment variable in order to allow the
client tests to work.  

Any failure in the test suite should a cause for concern.  In order to
get more details from it, run it via:

  make test TEST_VERBOSE=1

If you can't figure out what broke, then send the author the output
from "perl -V", as well as the output from the verbose test run.
Please include as many details as possible about the operating system
and MQSeries software on both the host being used to compile this
extension, as well as the queue manager to which the test suite is
connecting.

=head1 RELEASE NOTES

The Changes.html file has a complete, historical list of all
user-visible (and some invisible) changes to this code.

=head1 DOCUMENTATION

The documentation will be installed as man pages by default, but the
location of them depends entirely on how you have perl built and
installed.  Watch the installation, and you will see where they get
installed.  Prepend that to your MANPATH environment variable, and
then, all of these man commands will work.

Personally, the author prefers the results of "pod2html", but the
perl5 Makefile.PL infrastructure won't do this for you automatically.

  man MQSeries

will provide the documentation for the core MQI interface, and,

  man MQSeries::QueueManager
  man MQSeries::Queue
  man MQSeries::Message

will provide the core documentation for the OO interface.  

The following man pages document the classes that handle various
special MQSeries message types:

  man MQSeries::Message::Event
  man MQSeries::Message::Storable
  man MQSeries::Message::XML-Dumper
  man MQSeries::Message::PCF
  man MQSeries::Message::RulesFormat

There is an OO interface to the Command Server:

  man MQSeries::Command
  man MQSeries::Command::Request
  man MQSeries::Command::Response

There is also an interface to the Publish/Subscribe system:

  man MQSeries::PubSub::Broker
  man MQSeries::PubSub::Stream
  man MQSeries::PubSub::Command
  man MQSeries::PubSub::Message
  man MQSeries::PubSub::AdminMessage

=head1 AUTHORS

The code is currently maintained and supported by:

  W. Phillip Moore <Phil.Moore@msdw.com>

I also have to give credit to:

  Brian T. Shelden <shelden@shelden-associates.com>

for his help in porting and testing the code.

This module was originally developed as an IBM SupportPac, so credit
must also go to the original author:

  David J. Lennon <davidl@bristol.com>

Although, nothing remains of the original code.... (sorry, David :-)

=cut

#
# $Id: README,v 13.2 2000/04/11 20:46:05 wpm Exp $
#
# (c) 1999 Morgan Stanley Dean Witter and Co.
# See ..../src/LICENSE for terms of distribution.
#
