IBM WebSphere MQ Q PROGRAM - Middleware News

IBM WebSphere MQ Q PROGRAM - Middleware News


Q is simple pipe line program which takes messages from one source and
outputs to a target. The operation of the 'pipe' is controlled by
switches to the program. The source and target can either be the
console or a WebSphere MQ Queue. Since input/output can be taken from
stdin/stdout these can also be files. Two instances of Q can therefore
be used to implement a primitive file transfer program.

On most platforms a single program, Q, is supplied, which can connect
either as a local application or as a client. The mode of operation
is controlled via the '-l' parameter given below.

On other platforms, such as z/OS, only a single program, Q, is supplied
which runs only as a local application.

USAGE
_____

If the Q program is executed without any parameters or with an invalid
parameter it displays a brief description of each valid parameter. The
parameters, alphabetically, are as follows:

-a Sets message attributes when put to the output queue

p - forces persistence
n - forces non-persistence
q - uses queue default persistence
s - allow segmentation
c - get complete messages
d - put a datagram message type
R - put a request message type
r - put a reply message type
t - put a report message type
a - use read ahead on open and subscribe
A - force no use of read ahead on open and subscribe
C - close temporary queues with quiesce option
D - close temporary queues with delete option
2 - force message properties to be returned as an MQRFH2 header

-A[i|o|a]
Sets the value of an attribute. Should be used in combination
with -C and an appropriate option.

i - Application Identity Data (put and subscribe)
o - Application Origin Data (put only)
a - Accounting Token (put and subscribe)

-c Causes the MQGET call from the input queue to specify GMO_CONVERT
with the CCSID and Encoding values specified. The encoding value
should be specified in hex.

-C Controls whether the message context should be transferred from
input queue to output queue

a - pass all context
i - pass identity context
A - set all context
I - set identity context
n - no context

-d Controls what detail level is output to stdout.

f - Message content is printed formatted if it's an MQ* format
h - Message is printed in hex
l - Print message length
t - Print message offsets
x - Use XML Shortform
X - No XML Auto detect
n - Don't print the message
d/D - Print the MQMD after/before the MQI calls
o/O - Print the MQOD after/before the MQI calls
p/P - Print the MQPMO after/before the MQI calls
g/G - Print the MQGMO after/before the MQI calls
s/S - Print the MQSD after/before the MQI calls
r/R - Print the MQSRO after/before the MQI calls
1 - Low level of detail
2 - Medium level of detail
3 - High level of detail

-e Echo.
Causes the program to MQPUT any messages got from the input
queue to the reply queue.

-E Echo.
Causes the program to MQPUT any messages got from the input
queue to the reply queue, and fill in the Reply QMgr.

-f
Input file.
Each line of the file will be put to output queue as a different
message.
See "Z/OS FILE NAME FORMAT EXAMPLES" for specific z/OS details.

-F[+]
Input/output file.
Entire file will be put to the output queue as a single message.
If '+' is specified the dataset attributes will be retained if
the output dataset exists - z/OS only.
See "Z/OS FILE NAME FORMAT EXAMPLES" for specific z/OS details.

-g Use specific message id or correl id

mMsgId - Get by specified message id of 24 characters
cCorrelId - Get by correlation id of 24 characters
cGroupId - Get by group id of 24 characters
xmMsgId - Get by specified message id in hex
xcCorrelId - Get by correlation id in hex
xcGroupId - Get by group id in hex
pmMsgId - Put with specified message id of 24 characters
pcCorrelId - Put with correlation id of 24 characters
pcGroupId - Put with group id of 24 characters
pxmMsgId - Put with specified message id in hex
pxcCorrelId - Put with correlation id in hex
pxcGroupId - Put with group id in hex
pC - Use MQCI New session

-h
Only pass messages through the pipe that contain the specified
filter string. Must be single word.

-H
Use message selection on open and subscribe

-i The name of the Input Queue name (if any) to browse
See "QUEUE NAME FORMAT" for specific details.

-I The name of the Input Queue name (if any) to do destructive get
See "QUEUE NAME FORMAT" for specific details.

-jThe format name to be used on the MQPUT

-k Use browse lock

-l [ Not all platforms ]
The MQI library to link to, valid values are:

mqm - Queue Manager program

mqic32 or mqic - Client program

If not specified the program will try to use the Queue Manager
interface. If that is not present it will try to use the
MQ Client interface.

-L The maximum number of messages to process.

-m The name of the Queue Manager to connect to if not the default.

-M Allows a single text message to be put

-n"[ca|cad][cd|cdd][e|ed][x|xd]"
Sets the report option when messages are put to the output queue

ca - Confirm on arrival
cad - Confirm on arrival with data
cafd - Confirm on arrival with full data
cd - Confirm on delivery
cdd - confirm on delivery with data
cdfd - confirm on delivery with full data
e - Exceptions
ed - Exceptions with data
efd - Exceptions with full data
x - Expirations
xd - Expirations with data
xfd - Expirations with full data
pan - PAN
nan - NAN
newm - New Message Id
passm - Pass Message Id
copym - Copy Message Id
disc - Discard Message
passd - Pass discard and expiry
act - Activity Reports

-o The name of the Output Queue name (if any)
See "QUEUE NAME FORMAT" for specific details.

-O The name of the Output Queue name (if any)
See "QUEUE NAME FORMAT" for specific details.
As above but using Bind on Open

Multiple -o and -O flags can be provided which will cause a
distribution list to be used.

-p
Number of messages after which an MQCMIT is taken. If not
specified message operations are not under syncpoint.

-P
Sets the priority of put messages or on a subscribe

-q Quiet mode - doesn't write messages to screen

-r[+] The name of the Reply Queue to be placed in the message descriptor
when MQPUTing to the output queue.

If '+' is specified then the program will read the reply from the
reply queue before attempting the next put.

-s Force output to stdout. This can be used to monitor messages if
transferring messages from one queue to another.

-$
Sets separator character in queue names
Without this option you can use a queue value of QM1/Q1,QM1#Q1 or
QM1,Q1
However, '/' can be used in a queue name so it may be useful to
restrict the processing of this character.

-t Print timings for API calls

-U Sets the user ID in the message.

If '+' is specified then this instead sets the alternate user ID
for an open and subscribe call.

-v

Controls what information about what the program is doing is
printed.

p - Causes a pause before each API
>=1 - Information about each message is printed
>=2 - Each API call is printed
P - Print out command line parameters

-V[z][c] Sets the return value from the Q program. Default behaviour
is to return MQRC value.

z - Forces a zero return code
c - Return MQCC mapped to 0,4,8

-w Number of seconds to wait for a message if reading from an input
queue.

-W Number of milliseconds to before each MQGET call.
Can be used to represent 'think' time

-x[f][s][c]
Use MQCONNX

f - Use FASTPATH bindings
s - Use STANDARD bindings
i - Use ISOLATED bindings
q - No quiesce option
N - No MQDISC on end
b - Handle share block
n - Handle share noblock
c - Specify channel (for use with client connection)
t - Specify Connection Tag
u - Specify User ID and Password

-X
Loads a message from a file. File must contain hex strings such as the
message output lines from AMQSBCG (not entire output) or the output from
Q itself. Use -F if the file just contains the message characters
directly.
See "Z/OS FILE NAME FORMAT EXAMPLES" for specific z/OS details.

-y Set expiry for messages in 1/10th's of a second

-z Zero out MsgIds before MQPUT

-Z TimeZone (hours) Put Date/Time

-1 Use MQPUT1 rather than MQPUT

=# Set MQ structure versions
eg.-#m1p2g3o4x2 would ask for Version 1 MQMD
Version 2 MQPMO
Version 3 MQGMO
Version 4 MQOD
Version 2 MQCNO
eg.-#c uses current versions

Any group can be specified independantly

-* Repeat execution without program terminating

-= Set Max message size - allows truncation

-! Do not use exit handler

-S Subscribe options

o: Subscribe to Topic Object
s: Subscribe to Topic String
n: Subscription Name
u: l Subscription Level
c - Create the subscription - this is the default for Q
r - Resume an existing subscription
a - Alter an existing subscription
d - the subscription is durable
v - Any user can use this subcription
f - Only the owning user can use this subscription
g - the subscription is a group subscription
N - new publications only - no retained ones
R - get publications on request only
C - Use character based wildcards
T - Use topic based wildcards
D - Remove a durable subscription

-T Publish options

o: Subscribe to Topic Object
s: Subscribe to Topic String
r - publish a retained message
p - suppress the reply-to information on the publication
n - do not publish to any of my own subscriptions


QUEUE NAME FORMAT
_________________

A number of the parameters above allow the specification of a queue
name. For example the output queue. The name is passed to the MQOPEN
verb and can either consist of one or two parts. A one part name is
assumes to be the name of the queue and the queue manager name blank.
With a two part name the name of the queue manager is assumed to be
specified first. A two part name must use one of the following
characters as a separator

/ \ # or ,

For example the following examples tells Q to take input from the
keyboard and put the messages to different queues.

Q -oQ1
Q -oQM2/Q1
Q -oQM3#Q1

PUBLISH/SUBSCRIBE EXAMPLES
--------------------------
Make a managed, durable subscription using both topic object and topic string
and wait for messages to be delivered.
Q -Scdo:STOCK.MARKET -Ss:Prices -Sn:StockPrices -w60

Make a durable subscription using Q1 as the destination queue for publications
and remove it when we're done.
Q -ScdDs:Scores -Sn:ScoresSub -IQ1 -w60

Only receive publications every 20 seconds by requesting subscription only
on demand.
Q -ScRs:Fruit/Apples -W20000 -w120

Publish retained messages on a topic
Q -Trs:PriceList


Z/OS FILE NAME FORMAT EXAMPLES
______________________________

Example usage on z/OS for -f, -F and -X parameters.
-f"//MY.FILE" - sequential file (not fully qualified)
-f"//'USERID.MY.FILE'" - sequential file (fully qualified)
-f"//'USERID.MY.PDS(MEMBER)'" - PDS Member (fully qualified)
This doesn't work from within JCL due to
the single quotes round entire parm
string. To use this from within a parm
string in JCL do the following:-
-f"//''USERID.MY.PDS(MEMBER)''" - PDS Member (from within JCL only)
-f"//MY.PDS(MEMBER)" - PDS Member (not fully qualified)
-f"DD:INFILE" - DD Card name
-f"DD:INFILE(MEMBER)" - DD Card definition must not also have
a member defined for this to work.
-F"+DD:INFILE" - Output only example showing + to keep
data set attributes as existing file

For more details see "Chapter 11. Performing OS I/O Operations" in
z/OS C/C++ Programming Guide (SC09-4765-03).

Examples of usage
_________________
Write to a queue : q -oQ1
Write to two queues (Dist list) : q -oQ1 -oQ2
Read from a queue : q -IQ1
Browse from a queue : q -iQ1
Show Message Descriptor : q -iQ1 -dd3
Wait for messages : q -IQ1 -w60
Move messages between Queues : q -IQ1 -oQ2
Copy messages between Queues : q -iQ1 -oQ2
Subscribe to a topic : q -Ss:TopicStr -w60
Make a durable subscription : q -Sds:TopicStr -Sn:MySubName -w60
Publish on a topic : q -Ts:TopicStr


The program also allows multiple Queue Managers to be in use.
____________________________________________________________

Copy messages from QM1 to QM2 : q -xb -m QM1 -i Q1 -m QM2 -oQ2
The -xb parameter is required on some platforms to allow connection
to two difference Queue Managers from the same thread.

Move messages from QM1 to QM2 : q -xb -m QM1 -I Q1 -m QM2 -oQ2 -p20
Note that this doesn't use two phase commit. The transaction is committed
on the target and then on the source.

MESSAGE FORMATS
_______________

When typing messages in from the keyboard and message is generated each
time the return key is pressed. However, a message starting with a '#'
character is interpreted to allow multiple messages to be generated.
The syntax is displayed by entering '?' in message input. It is as
follows :-

#[!][c][Reps/[Size/[Delay/[Commits]]]]

! Don't include the # instruction string as part of the message.

C Asks for the message to be checksumed. The program will
randomly set the characters of the message. Add up the
numerical values of the whole message and print out the result.
This is useful to ensure that messages are being received
complete and without corruption.

REPS Number of message to produce

SIZE Size of each message

DELAY Delay in seconds between each MQPUT

COMMITS Commit interval.

The Size and Delay parameters can be specified negative in which case
the program will randomly choose values for each MQPUT up to the value
specified.


EXAMPLES
________

#!10 HELLO

Sends ten messages each with the content 'Hello'

#!5/1024 HELLO

Sends five messages each of 1024 bytes with the initial data of each
message being 'Hello'

#!10/-10000/-5 HELLO

Sends ten messages of random size up to 10000 bytes with a random delay
of up to 5 seconds between each MQPUT.

Note that on Windows the time interval is specified in milliseconds not
seconds as on Unix and z/OS.

INSTALLATION
____________

The following platforms are supported :
Windows (various flavours)
AIX
HP/UX
Solaris
Linux
z/OS

They are supplied in the InfoZip format file MA01 ZIPBIN.

Download this file (in BINARY) to a temporary directory and uncompress
using InfoZip's Unzip (use the default options to ensure the
subdirectories stored in the ZIP file are re-created).

This will create subdirectories containing the items shown below. Once
unpacked, transfer the appropriate executable to the destination system
and follow any system specific instruction where detailed below.

Windows DIRECTORY
q.exe - will run as a client or a Queue Manager program (see -l parameter).

UNIX DIRECTORY
q - runs as a Queue Manager or a client program (see -l parameter)

zOS DIRECTORY
Q.SEQ - sequential file containing Queue Manager program
Q.JCL - example JCL for running in batch

Transfer the Q.SEQ file to a z/OS system using the following commands
ftp> binary
ftp> quote site fixrecfm 80
ftp> put zOS\Q.SEQ Q.SEQ
In tso use the following command
receive inds(Q.SEQ)
when prompted for a filename, reply
DSN(Q.LOAD)

Q can be run on z/OS in BATCH - an example piece of JCL is provided in
zOS directory.
Q can also be run interactively, e.g. from the TSO/E READY prompt or
the ISPF Command Shell (=6).

z/OS USS
________
To run the program in the USS version you should first convert the
executable. To do this issue the following command.

TSO OPUT 'somewhere.Q.LOAD(Q)' '/u/userid/bin/q' BIN