Manual of Icwri Tools for IBM WebSphere MQ Version 0.521

Icwri is a lightweight service oriented Java built-in script by Liu Rui. Icwri can run on any system (UNIX/Linux, Windows, Mac, …) with JDK/JRE 1.5 or above installed.

Icwri Tools for IBM WebSphere MQ is a monitor and a group of services based on Icwri script to help WMQ administration and development. It is a cross-platform tool. We can do more advanced and complex administration using Icwri Script with ease. The services include:

• Read/write messages
• Clear queue
• Get queue depth
• Resolve in-doubt transactions
• Resolve in-doubt channel
• Get channel status
• Get listener status
• List queue names
• List channel names
• List listener names

Following are major topics of this manual:

• Getting Start
• Web Based WMQ Monitor
• Demo Scripts
• References

Getting Start

Icwri can run on any system (UNIX/Linux, Windows, MAC, …) with JDK/JRE 1.5 or above installed. The kernel files include icwri.jar and service list files. The service list files can be rewrite by users. Icwri can be installed into any path. Following steps shows how to install Icwri and run some simple demo applications.

If you installed WMQ v7.1, you have already gotten “com.ibm.mq.pcf.jar”. If you use WMQ v6.0 or WMQ v5.1, please download “com.ibm.mq.pcf.jar” from website http://www-01.ibm.com/support/docview.wss?rs=171&uid=swg24000668&loc=en_US&cs=utf-8&lang=en. Or you can just just the “com.ibm.mq.pcf.jar” file in the "samples" directory.

1. For Unix/Linux users

1) Extract the package

$ cd /opt
$ gzip -d ic_wmq_0.521.tar.gz
$ tar vxf ic_wmq_0.521.tar

2) Set environment variables

CLASSPATH=/opt/ic_wmq_0.521/icwri.jar:/opt/ic_wmq_0.521/ic_wmq.jar:/opt/ic_wmq_0.521/ic_web.jar:/usr/mqm/java/lib/com.ibm.mq.jar:/usr/mqm/java/lib/com.ibm.mq.pcf.jar
export CLASSPATH

#AIX example:
LIBPATH=/usr/mqm/java/lib
export LIBPATH

#Solaris/Linux examples:
LD_LIBRARY_PATH=/usr/mqm/java/lib
export LD_LIBRARY_PATH

#HP-UX example:
SHLIB_PATH=/usr/mqm/java/lib
export SHLIB_PATH

3) Run demo script application:

$ java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testConnectQM1
Please input the Queue Manager name:
>> VENUS
Return code = 0

Note:
"-s" argument specifies the service name.
"-f" argument specifies the script file.

2. For Microsoft Windows users

1) Extract the package to directory, for example: c:\ic_wmq_0.521

2) Set environment

set CLASSPATH=c:\ic_wmq_0.521\icwri.jar;c:\ic_wmq_0.521\ic_wmq.jar;c:\ic_wmq_0.521\ic_web.jar;c:\mq\java\lib\com.ibm.mq.jar;c:\mq\java\lib\com.ibm.mq.pcf.jar
set PATH=c:\mq\bin;c:\mq\java\lib;%PATH%

3) Run demo script application

$ java lr.icwri.app.RunScript -f C:/ic_wmq_0.521/samples/test.icw -s !testConnectQM1
Please input the Queue Manager name:
>> VENUS
Return code = 0

Note:
"-s" argument specifies the service name.
"-f" argument specifies the script file.

Web Based WMQ Monitor

To use this web based monitor does not require any other web server.

Before running this sample WMQ Monitor, make sure to set correct environment variables (Please refer to the “Getting Start” chapter).

Run the monitor with following command:

UNIX sample:

java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/testMon.icw -s !testMon1
Please input port of the web server used by monitor (default: 80)
>>
Please input the Queue Manager to monitor
>> VENUS
Icwri WebSphere MQ Monitor v0.521
IcWebAs version 0.1

Windows sample:

java lr.icwri.app.RunScript -f C:/ic_wmq_0.521/samples/testMon.icw -s !testMon1
Please input port of the web server used by monitor (default: 80)
>>
Please input the Queue Manager to monitor
>> VENUS
Icwri WebSphere MQ Monitor v0.521
IcWebAs version 0.1

In the first 3 pages, please choose queues, channels, and listeners to monitor. Then it goes to the main monitor page:

Following conmand is for remote monitor (please configure security before use it):

java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/testMon.icw -s !testMon2

Following conmand is using REST interfaces:

java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/testMonA.icw -s !testMon1

Demo Scripts

The following chapters are only for advanced users:

You can find the demos in "samples/test.icw". The demo use the default queue manager name as "VENUS", which has local queues "Q1" and "Q2".

Service “!testConnectQM1” uses server binding mode to connect to queue mqnqger. Service “!testConnectQM2” uses java client mode to connect to queue mqnqger. Run service “!testConnectQM1” and “!testConnectQM2” with following commands:

# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testConnectQM1
Please input the Queue Manager name:
>> VENUS
Return code = 0
# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testConnectQM2
Return code = 0

Service “!testWriteMsg1” writes a message to the "Q1" queue of "VENUS".

# testWriteMsg1

Service “!testReadMsg1” reads a message in non-block mode. Service “!testReadMsg2” reads a message in block mode (for infinite time).

# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testReadMsg1
Got message = [Hello World!]
# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testReadMsg2
Got message = [Hello World!]

Service “!testClearQue1” clears Q1 of VENUS. Service “!testClearQue2” requires to queue manager and queues to be cleared. Service “!testClearQue3” shows how to use command arguments to input queue and queue manager names. (Note: command line arguments after "-X" can be used in Icwri script).

# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testClearQue1
Clearing queue completed!
# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testClearQue2
Please input QMGR name:
>> VENUS
Please input QUE name (empty to exit):
>> Q1
Clearing queue: Q1 completed!
Please input QUE name (empty to exit):
>>
# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testClearQue3 -X -M VENUS -q Q1
Clearing queue: Q1 of [VENUS] completed!

Service “!testResolveQM” can resolve in-doubt transactions. Service “!testResolveChn1” can resolve in-doubt channels.

# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testResolveQM
Please input QMGR name:
>> VENUS
!resolveQM: VENUS completed!
# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testResolveChn1
!resolveChn completed!

Service “!testGetQueDepth1” the depth of "Q1" and "Q2" in "VENUS". Service “!testGetQueDepth1” the depth of "Q1" and "Q2" every 2 seconds.

# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testGetQueDepth1
Depth of Q1 is 0
Depth of Q2 is 0
# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testGetQueDepth2
Depth of Q1 is 0
Depth of Q2 is 0
Depth of Q1 is 0
Depth of Q2 is 0
Depth of Q1 is 0
Depth of Q2 is 0
... ...

Service “!testGetChnState1” and “!testGetLsnState1” can get the status of specified channel and listener:

# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testGetChnState1
Please input Channel name (default is SYSTEM.DEF.SENDER):
>> VENUS.SERVER
State of channel VENUS.SERVER is RUNNING
# java lr.icwri.app.RunScript -f /opt/ic_wmq_0.521/samples/test.icw -s !testGetLsnState1
Please input Listener name (default is LN1):
>> LI1
State of listener LI1 is RUNNING
#

References

Generic considerations of Icwri script:

• Icwri script is case sensitive.
• Character ":" (colon) is used for assignment in stead of "=" (equal sign) to avoid confusion. In Icwri script character "=" (equal sign) is just an operator to compare two value of constant or attribute.
• Character "`" (backticks) is used to enclose a constant string instead of quotation marks or apostrophe.
• It is not required to put statement in one line. Statement must be ended with character ";" (semicolon).
• Prefixes are used to distinguish keywords. In Icwri script all words except constant and operators (e.g. "+", "-", ">" ...) must have a prefix. For example: service names are all prefixed by character “!”; Icwri commands are all prefixed by character “%”; attributes are prefixed by character "@"; aliases of attributes are prefixed by character "$".

Thanks for Your Interest in Icwri

Coding, testing, helping to answer questions and making documents are all appreciated. Welcome to contact liurui@lrsolution.com to report defects and tell your suggestions.

-- Liu Rui