The Get samples

The Get sample programs get messages from a queue using the MQGET call.

The source programs are supplied in C and COBOL in the batch and CICS environments (see Table 45 and Table 50).

Design of the Get sample

The flow through the program logic is:

1. 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 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.

2. 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.
3. 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 WebSphere MQ Application Programming Reference. For each message, the message number is printed followed by the length of the message and the message data.

4. 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.
5. 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, you must 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:

1. The name of the queue manager (4 characters)
2. The name of the target queue (48 characters)
3. The number of messages to get (up to 4 digits)
4. The browse/get message option (1 character: 'B' to browse or 'D' to destructively get the messages)
5. The syncpoint control (1 character: 'S' for syncpoint or 'N' for no syncpoint)

If you enter any of the above parameters wrongly, you will 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 the layout of the parameters shown in the sample run JCL, CSQ4BCJR, and CSQ4BVJR, are used. 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 as 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 you enter should be a positive number. For example, to get a single message, you can enter 1 or 01 or 001 or 0001 as the value. If you enter non-numeric or negative values, you may receive an error. For example, if you enter '-1', the COBOL program will retrieve one message, but the C program will not retrieve any messages.
• For both programs, CSQ4BCJ1 and CSQ4BVJ1, you must enter 'B' in the get parameter, ++GET++, if you want to browse the messages.
• For both programs, CSQ4BCJ1 and CSQ4BVJ1, you must enter 'S' in the syncpoint parameter, ++SYNC++, for messages to be retrieved in syncpoint.

The Get samples for the CICS environment

The transactions take the following parameters in an EXEC PARM, separated by commas:

1. The number of messages to get (up to 4 digits)
2. The browse/get message option (1 character: 'B' to browse or 'D' to destructively get the messages)
3. The syncpoint control (1 character: 'S' for syncpoint or 'N' for no syncpoint)
4. The name of the target queue (48 characters)

If you enter any of the above parameters wrongly, you will receive appropriate error messages.

For the COBOL sample, invoke the Get sample in the CICS environment by entering:

  MVGT,9999,B,S,QUEUE.NAME

For the C sample, invoke the Get sample in the CICS environment by entering:

  MCGT,9999,B,S,QUEUE.NAME

When the messages are retrieved from the queue, they are put on a CICS temporary storage queue with the same name as the CICS transaction (for example, MCGT for the C sample).

Here is example output of the Get samples:

****************************  TOP OF QUEUE  ************************
000000000 : 000000010: **********
000000001 : 000000010 :**********
***************************  BOTTOM OF QUEUE  **********************

Usage notes

• To keep the samples simple, there are some minor functional differences between language versions. None of the differences relate to the MQI.
• If you enter a queue name that is longer than 48 characters, its length is truncated to the maximum of 48 characters but no error message is returned.
• Before entering the transaction, press the 'CLEAR' key.
• CSQ4CCJ1 can only correctly display character messages as it only displays until the first NULL (\0) character is displayed.
• For the numeric field, enter any number between 1 and 9999. The value you enter should be a positive number. For example, to get a single message, you can enter the value 1 or 01 or 001 or 0001. If you enter a non-numeric or negative value, you may receive an error.
• Messages longer than 24 526 bytes in C and 9 950 bytes in COBOL are truncated. This is due to the way the CICS temporary storage queues are used.
• For both programs, CSQ4CCK1 and CSQ4CVK1, you must enter 'B' in the get parameter if you want to browse the messages, otherwise enter 'D'. This will perform destructive MQGET calls. If you enter any other value you will receive an error message.
• For both programs, CSQ4CCJ1 and CSQ4CVJ1, you must enter 'S' in the syncpoint parameter for messages to be retrieved in syncpoint. If you enter 'N' in the syncpoint parameter the MQGET calls will be issued out of syncpoint. If you enter any other value you will receive an error message.