Design of the Get sample
The flow through the program logic is:
-
Connect to the queue manager using the MQCONN call. If this
call fails, print the completion and reason codes and stop processing.
Note:
If you are running the sample in a CICS(R) environment, you do not need to issue
an MQCONN call; if you do, it returns DEF_HCONN. You can use the connection
handle MQHC_DEF_HCONN for the MQI calls that follow.
-
Open the queue using the MQOPEN call with the MQOO_INPUT_SHARED
and MQOO_BROWSE options. On input to this call, the program uses the connection
handle that is returned in step 1. For the
object descriptor structure (MQOD), it uses the default values for all fields
except the queue name field, which is passed as a parameter to the program.
If the MQOPEN call fails, print the completion and reason codes and stop processing.
- Create a loop within the program issuing MQGET calls until the required
number of messages are retrieved from the queue. If an MQGET call fails, the
loop is abandoned early, no further MQGET calls are attempted, and the completion
and reason codes are returned. The following options are specified on the
MQGET call:
- MQGMO_NO_WAIT
- MQGMO_ACCEPT_TRUNCATED_MESSAGE
- MQGMO_SYNCPOINT or MQGMO_NO_SYNCPOINT
- MQGMO_BROWSE_FIRST and MQGMO_BROWSE_NEXT
For a description of these options, see the WebSphere MQ Application Programming Reference. For
each message, the message number is printed followed by the length of the
message and the message data.
-
Close the queue using the MQCLOSE call with the object handle
returned in step 2. If this call fails,
print the completion and reason codes.
- Disconnect from the queue manager using the MQDISC call with the connection
handle returned in step 1. If this call fails,
print the completion and reason codes.
Note:
If you are running
the sample in a CICS environment, you do not need to issue an MQDISC call.
The Get samples for the batch environment
To run the samples, edit and run the sample JCL, as described in Preparing and running sample applications for the batch environment.
The programs take the following parameters in an EXEC PARM, separated by
spaces in C and commas in COBOL:
- The name of the queue manager (4 characters)
- The name of the target queue (48 characters)
- The number of messages to get (up to 4 digits)
- The browse/get message option (1 character: B to browse or D to destructively
get the messages)
- The syncpoint control (1 character: S for syncpoint or N for no syncpoint)
If you enter any of the above parameters incorrectly, you receive appropriate
error messages.
Output from the samples is written to the SYSPRINT data set:
=====================================
PARAMETERS PASSED :
QMGR - VC9
QNAME - A.Q
NUMMSGS - 000000002
GET - D
SYNCPOINT - N
=====================================
MQCONN SUCCESSFUL
MQOPEN SUCCESSFUL
000000000 : 000000010 : **********
000000001 : 000000010 : **********
000000002 MESSAGES GOT FROM QUEUE
MQCLOSE SUCCESSFUL
MQDISC SUCCESSFUL
Usage notes
- To keep the samples simple, there are some minor functional differences
between language versions. However, these differences are minimized if you
use the layout of the parameters shown in the sample run JCL, CSQ4BCJR, and
CSQ4BVJR,. None of the differences relate to the MQI.
- CSQ4BCJ1 allows you to enter more than four digits for the number of messages
retrieved.
- Messages longer than 64 KB are truncated.
- CSQ4BCJ1 can only correctly display character messages because it only
displays until the first NULL (\0) character is displayed.
- For the numeric number-of-messages field, enter any digit between 1 and
9999. The value that you enter should be a positive number. For example, to
get a single message, you can enter 1, 01, 001, or 0001 as the value. If you
enter nonnumeric or negative values, you might receive an error. For example,
if you enter -1, the COBOL program retrieves one message, but the C program
does not retrieve any messages.
- For both programs, CSQ4BCJ1 and CSQ4BVJ1, enter B in the get parameter,
++GET++, if you want to browse the messages.
- For both programs, CSQ4BCJ1 and CSQ4BVJ1, enter S in the syncpoint parameter,
++SYNC++, for messages to be retrieved in syncpoint.