The Browse sample is a batch application that demonstrates how to browse
messages on a queue using the MQGET call. The application steps through
all the messages in a queue, printing the first 80 bytes of each one.
You could use this application to look at the messages on a queue without
changing them.
Source programs and sample run JCL are supplied in the COBOL, assembler,
PL/I, and C languages (see Table 46).
To start the application, you must edit and run the sample run JCL, as
described in Preparing and running sample applications for the batch environment. You can look at messages on one of your own queues
by specifying the name of the queue in the run JCL.
When you run the application (and there are some messages on the queue),
the output data set looks this:
07/12/1998 SAMPLE QUEUE REPORT PAGE 1
QUEUE MANAGER NAME : VC4
QUEUE NAME : CSQ4SAMP.DEAD.QUEUE
RELATIVE
MESSAGE MESSAGE
NUMBER LENGTH ------------------- MESSAGE DATA -------------
1 740 HELLO. PLEASE CALL ME WHEN YOU GET BACK.
2 429 CSQ4BQRM
3 429 CSQ4BQRM
4 429 CSQ4BQRM
5 22 THIS IS A TEST MESSAGE
6 8 CSQ4TEST
7 36 CSQ4MSG - ANOTHER TEST MESSAGE.....!
8 9 CSQ4STOP
********** END OF REPORT **********
If there are no messages on the queue, the data set contains the headings
and the "End of report" message only. If an error occurs with
any of the MQI calls, the completion and reason codes are added to the output
data set.
The Browse sample application uses a single program module--one is
provided in each of the supported programming languages.
The flow through the program logic is:
- Open a print data set and print the title line of the
report. Check that names of the queue manager and queue have been
passed from the run JCL. If both names have been passed, print the
lines of the report that contain the names. If they have not, print an
error message, close the print data set, and stop processing.
The way that the program tests the parameters it is passed from the JCL
depends on the language in which the program is written--for more
information, see Language-dependent design considerations.
- Connect to the queue manager using the MQCONN call. If
this call is not successful, print the completion and reason codes, close the
print data set, and stop processing.
- Open the queue using the MQOPEN call with the MQOO_BROWSE
option. On input to this call, the program uses the connection handle
returned in step 2. For the object descriptor structure (MQOD), it uses
the default values for all the fields except the queue name (which was passed
in step 1). If this call is not successful, print the
completion and reason codes, close the print data set, and stop
processing.
- Browse the first message on the queue, using the MQGET call. On
input to this call, the program specifies:
- The connection and queue handles from steps 2 and 3
- A MQMD structure with all fields set to their initial values
- Two options:
- MQGMO_BROWSE_FIRST
- MQGMO_ACCEPT_TRUNCATED_MSG
- A buffer of size 80 bytes to hold the data copied from the message
The MQGMO_ACCEPT_TRUNCATED_MSG option allows the call to complete
even if the message is longer than the 80-byte buffer specified in the
call. If the message is longer than the buffer, the message is
truncated to fit the buffer, and the completion and reason codes are set to
show this. The sample was designed so that messages are truncated to 80
characters simply to make the report easy to read. The buffer size is
set by a DEFINE statement, so you can easily change it if you want
to.
- Perform the following loop until the MQGET call fails:
- Print a line of the report showing:
- The sequence number of the message (this is a count of the browse
operations).
- The true length of the message (not the truncated length). This
value is returned in the DataLength field of the MQGET call.
- The first 80 bytes of the message data.
- Reset the MsqId and CorrelId
fields of the MQMD structure to nulls
- Browse the next message, using the MQGET call with these two
options:
- MQGMO_BROWSE_NEXT
- MQGMO_ACCEPT_TRUNCATED_MSG
- If the MQGET call fails, test the reason code to see if the call has
failed because the browse cursor has got to the end of the queue. In
this case, print the "End of report" message and go to step 7; otherwise, print the completion and reason codes,
close the print data set, and stop processing.
- Close the queue using the MQCLOSE call with the object handle
returned in step 3.
- Disconnect from the queue manager using the MQDISC call with the
connection handle returned in step 2.
- Close the print data set and stop processing.
Source modules are provided for the Browse sample in four programming
languages. There are two main differences between the source
modules:
- When testing the parameters passed from the run JCL, the COBOL, PL/I, and
assembler-language modules search for the comma character (,). If
the JCL passes PARM=(,LOCALQ1), the application attempts to open
queue LOCALQ1 on the default queue manager. If there is no name after
the comma (or no comma), the application returns an error. The C module
does not search for the comma character. If the JCL passes a single
parameter (for example, PARM=('LOCALQ1')), the C module
uses this as a queue name on the default queue manager.
- To keep the assembler-language module simple, it uses the date format
yy/ddd (for example, 93/116) when it creates the print report. The
other modules use the calendar date in mm/dd/yy format.
© IBM Corporation 1993, 2002. All Rights Reserved