MQGET: Get message from an open queue

This function gets a message from a local queue that was opened for input by using the MQOPEN function.

Last updated

  • Changed for PUT11.
  • Changed for PUT05.
  • Changed for PUT00.

Format

LIBS := see programming considerations 
#include  <tpf/cmqc.h>
void      MQGET(MQHCONN Hconn,
                MQHOBJ Hobj,
                PMQVOID pMsgDesc,
                PMQVOID pGetMsgOpts,
                MQLONG BufferLength,
                PMQVOID pBuffer,
                PMQLONG pDataLength,
                PMQLONG pCompCode,
                PMQLONG pReason);
Hconn
The connection handle, which represents the connection to the z/TPF MQSeries® queue manager. The value of Hconn was returned by a previous MQCONN call.
Hobj
The object handle, which represents the queue to which a message is to be read. The value of Hobj was returned by a previous MQOPEN function call with the MQOO_INPUT_AS_Q_DEF or MQOO_INPUT_SHARED option specified.
pMsgDesc (MQMD)
A pointer to where the message queuing message descriptor (MQMD) structure is stored. This structure describes the attributes of the message being retrieved from the queue. For more information about this structure and the fields it contains, see Message queuing message descriptor (MQMD).
pGetMsgOpts (MQGMO)
A pointer to the get-message options (MQGMO) structure, which contains the options that control the action of the MQGET function. For more information about this structure and the fields it contains, see Get-message options (MQGMO).
BufferLength
The length, in bytes, of the buffer area supplied to the function.
pBuffer
A pointer to the area where the message data will be copied. If BufferLength is less than the message length, as much of the message as possible is moved into the buffer; this occurs whether MQGMO_ACCEPT_TRUNCATED_MSG is specified on the Options field of the GMO structure or not.

The character set and encoding of data in the buffer are given by the CodedCharSetID and Encoding fields in the pMsgDesc parameter. If these differ from the values required by the application, the application must convert the message data to the character set and encoding required.

pDataLength
A pointer to the length of the message, which is a returned value. This is the length in bytes of the application data in the message. If this is greater than the value of the BufferLength parameter, only the BufferLength number of bytes are returned in the Buffer parameter. If the value is zero, the message does not contain application data.
pCompCode
A pointer to the location to store the completion code, which is one of the following:
MQCC_OK
The call successfully completed.
MQCC_WARNING
The call partially completed.
MQCC_FAILED
The call failed.
pReason
A pointer to the location to store the reason code that qualifies the completion code.

If the completion code is MQCC_OK, the reason code is MQRC_NONE, which indicates a normal return.

If the completion code is MQCC_WARNING or MQCC_FAILED, see Error return for the corresponding reason codes.

Normal return

MQCC_OK
Completion code completed successfully.
MQRC_NONE
Reason code completed successfully.

Error return

If the completion code is MQCC_WARNING, the reason code is dependent on the value of MQGMO_ACCEPT_TRUNCATED_MSG and is one of the following:
MQRC_NO_MSG_LOCKED
No message locked.
MQRC_TRUNCATED_MSG_ACCEPTED
The MQGMO_ACCEPT_TRUNCATED_MSG option was specified in the Get-Message Options (MQGMO) MQSeries structure and the truncated message is accepted.
MQRC_TRUNCATED_MSG_FAILED
The MQGMO_ACCEPT_TRUNCATED_MSG option was not specified in the MQGMO MQSeries structure and the truncated message failed.
If the completion code is MQCC_FAILED, the function failed with one of the following reason codes:
MQRC_BUFFER_ERROR
The buffer parameter is not valid.
MQRC_BUFFER_LENGTH_ERROR
The buffer length parameter is not valid.
MQRC_DATA_LENGTH_ERROR
The data length parameter is NULL.
MQRC_GET_INHIBITED
Get is inhibited for the queue.
MQRC_GMO_ERROR
Get message options structure is not valid.
MQRC_HCONN_ERROR
The connection handle is not valid.
MQRC_HOBJ_ERROR
The object handle is not valid.
MQRC_INVALID_MSG_UNDER_CURSOR
The message under the cursor is not valid for retrieval.
MQRC_MATCH_OPTIONS_ERROR
The match options are not valid.
MQRC_MD_ERROR
The message descriptor is not valid.
MQRC_NO_MSG_AVAILABLE
No message is available.
MQRC_NO_MSG_UNDER_CURSOR
The browse cursor is not positioned on a message or the message on which it is positioned has expired.
MQRC_NOT_OPEN_FOR_BROWSE
The queue is not open for browsing.
MQRC_NOT_OPEN_FOR_INPUT
The queue is not open for input.
MQRC_OBJECT_DAMAGED
The object is damaged.
MQRC_OPTIONS_ERROR
The options are not valid or are not consistent.
MQRC_Q_DELETED
The queue has been deleted.
MQRC_Q_MGR_NOT_ACTIVE
The queue manager is not active.
MQRC_Q_MGR_NOT_AVAILABLE
The queue manager is not available.
MQRC_STORAGE_NOT_AVAILABLE
There is not enough storage available.
MQRC_UNEXPECTED_ERROR
An unexpected error occurred.
MQRC_WAIT_INTERVAL_ERROR
The wait interval specified in the WaitInterval field is not correct.

Programming considerations

  • The library that is required to use this function is determined by the following situations:
    • If the application will exclusively access a remote queue manager rather than the local z/TPF IBM® MQ queue manager, you can include the CMQI library in the makefile and add the -D_TPF_CLIENTONLY option to the CFLAGS_PGMX or CXXFLAGS_PGMY statement to improve the application performance.
    • If the queue manager that the application will access is not known, or if the application is accessing the local z/TPF IBM MQ queue manager, you must include the CMQS library in the makefile and not add the -D_TPF_CLIENTONLY option to the CFLAGS_PGMX or CXXFLAGS_PGMY statement.
  • If the Hconn parameter is not for a local z/TPF MQSeries queue manager, this MQGET function call will be sent by z/TPF MQSeries client support to the remote queue manager for processing. The options supported by the remote queue manager can differ from the options specified for the local z/TPF MQSeries queue manager.
  • The retrieved message is deleted from the queue. The deletion will occur as part of the MQGET function call except for completion code MQCC_FAILED or reason code MQRC_TRUNCATED_MSG_FAILED, or as part of a TX_COMMIT function call if the MQGET function is called from a transaction scope.
  • When the MQGET function call occurs in a commit scope, the message is marked as being unavailable to other applications, but it is deleted from the queue only when the unit of work is committed. The message is made available again if the unit of work is rolled back.

Examples

The following example gets a message from a queue. 
#include <tpf/cmqc.h>

MQHOBJ  Hobj;
MQLONG  Msglen;
MQBYTE  *buffer;
MQLONG  CompCode;                        /* completion code        */
MQLONG  Reason;                          /* reason code            */
MQHCONN Hcon;                            /* Connection Handle      */
MQGMO gmo = {MQGMO_DEFAULT};             /* Get Msg Options        */
MQLONG  bufLength = 100;
MQMD md = {MQMD_DEFAULT};
⋮

/*********************************************/
/*GET MESSAGE FROM THE QUEUE                 */
/*********************************************/

buffer = (MQBYTE *) calloc(1,bufLength);

/* Hcon and Hobj from previous MQCONN MQOPEN                       */
MQGET(Hcon, Hobj, &md, &gmo, bufLength,
            buffer, &Msglen, &CompCode, &Reason);

if(Reason != MQRC_NONE && Reason != MQRC_TRUNCATED_MSG_ACCEPTED)
 {
    printf("MQGET ended with reason code %d.\n",Reason);
 }

else
 {
⋮
 };
 free(buffer);