Design of the Browse sample on z/OS

The Browse sample application uses a single program module; one is provided in each of the supported programming languages.

1. Open a print data set and print the title line of the report. Check that the 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 on z/OS.

2. 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.
3. 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.
4. 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
   • An 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 to make the report easy to read. The buffer size is set by a DEFINE statement, so we can easily change it if we want to.

5. Perform the following loop until the MQGET call fails:
   1. 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.

   2. Reset the MsqId and CorrelId fields of the MQMD structure to nulls
   3. Browse the next message, using the MQGET call with these two options:
      • MQGMO_BROWSE_NEXT
      • MQGMO_ACCEPT_TRUNCATED_MSG

6. 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.
7. Close the queue using the MQCLOSE call with the object handle returned in step 3.
8. Disconnect from the queue manager using the MQDISC call with the connection handle returned in step 2.
9. Close the print data set and stop processing.

Parent topic: The Browse sample on z/OS