gtpc2m4zC/C++ Language Support User's Guide

MQGET-Get Message from an Open Queue

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

Format

#include  <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 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 option specified.

pMsgDesc (MQMD)
A pointer to where the message queuing message descriptor (MQMD) structure will be stored. This structure describes the attributes of the message being retrieved from the queue.

The following are the fields in the message queuing message descriptor (MQMD):

StrucId (MQCHAR4)
The type of structure, which must be MQMD_STRUC_ID. This is an input parameter.

Version (MQLONG)
The version number of the structure, which must be MQMD_VERSION_1. This is an input parameter.

MsgType (MQLONG)
The type of message. This is returned as an output parameter.

The following values are returned:

MQMT_DATAGRAM
The message does not require a reply.

MQMT_REQUEST
The message requires a reply. The name of the queue to which the reply should be sent will be specified in the ReplyToQ field.

MQMT_REPLY
The message is a reply to an earlier request message (MQMT_REQUEST). The message should be sent to the queue indicated by the ReplyToQ field of the request message.
Note:
The TPF MQSeries queue manager does not enforce the request-reply relationship; this is an application responsibility.

Persistence (MQLONG)
Message persistence. This is returned as an output parameter.

Valid values returned are MQPER_PERSISTENT and MQPER_NOT_PERSISTENT.

ReplyToQ (MQCHAR48)
The name of the queue which the reply should be sent to is returned in this field when the MsgType parameter is MQMT_REQUEST.

ReplyToQMgr (MQCHAR48)
The name of the queue manager which the reply should be sent to is returned in this field when the MsgType parameter is MQMT_REQUEST.

PutApplType (MQLONG)
The type of application that put the message on the queue is returned in this field (MQAT_TPF for TPF applications).

PutDate (MQCHAR8)
The date when the message was put on the queue is returned in this field, where:

YYYY
Year (4 numeric digits)

MM
Month of year (01 to 12)

DD
Day of month (01 to 31).

PutTime (MQCHAR8)
The time when the message was put on the queue. HHMMSSTH is set by the TPF MQSeries queue manager, where:

HH
Hours (00 to 23)

MM
Minutes (00 to 59)

SS
Seconds (00 to 59)

T
Tenths of a second (0 to 9)

H
Hundredths of a second (0 to 9).

Note:
For all other fields in the MQMD, the TPF MQSeries queue manager does not process the field. The values filled in by the originating application are passed to the destination queue.

pGetMsgOpts (MQGMO)
A pointer to the message queuing get message options (GMO) structure, which contains the options that control the action of the MQGET function.

StrucId (MQCHAR4)
The type of structure, which must be MQGMO_STRUC_ID.

Version (MQLONG)
The version number of the structure, which must be MQGMO_VERSION_1.

Options (MQLONG)
The options that control the action of the MQGET function:

MQGMO_WAIT
Wait for the message to arrive. When this option is specified in the MQGMO structure, the MQGET function is suspended until a message arrives. If a message is available in queue, the MQGET function returns to the application immediately. Use the WaitInterval field of the MQGMO structure to specify the maximum time (in milliseconds) that you want an MQGET function call to wait for a message to arrive on a queue. If no suitable message has arrived after this time has elapsed, the call is completed with MQCC_FAILED and reason code MQRC_NO_MSG_AVAILABLE. You can specify an unlimited wait interval using the MQWI_UNLIMITED constant in the WaitInterval field.

MQGMO_NO_WAIT
Return immediately if no message is in the queue. This is the default if MQGMO_WAIT or MQGMO_NO_WAIT is not specified.

MQGMO_SYNCPOINT
Get a message with syncpoint control. The request is to operate within the normal unit-of-work protocols. 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 backed out. If an application already holds a commit scope, the MQGMO_SYNCPOINT option does not change the unit of work. When an application does not hold a commit scope, the MQGMO_SYNCPOINT option opens a new commit scope. This option applies to MQSeries client calls only. An implicit syncpoint occurs for any uncommitted requests when an MQDISC function call is issued from a server.

MQGMO_NO_SYNCPOINT
Get a message without syncpoint control. The request is to operate outside the normal unit of work. The message is deleted from the queue immediately. The message cannot be made available again by backing out the unit of work. This option applies to MQSeries client calls only.

MQGMO_ACCEPT_TRUNCATED_MSG
Allow truncation of message data.

WaitInterval (MQLONG)
Wait interval in milliseconds. Specify a positive number or the constant MQWI_UNLIMITED in the WaitInterval field. This is the approximate time that an MQGET function call waits for a suitable message to arrive. If no suitable message has arrived after this time has elapsed, the call is completed with MQCC_FAILED and reason code MQRC_NO_MSG_AVAILABLE.

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
Successfully completed.

MQCC_WARNING
The message was truncated.

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.

See MQSeries Application Programming Reference and MQSeries Message Queue Interface Technical Reference for more information about MQSeries data types and parameters.

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_TRUNCATED_MSG_ACCEPTED
The truncated message is accepted.

MQRC_TRUNCATED_MSG_FAILED
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_MD_ERROR
The message descriptor is not valid.

MQRC_NO_MSG_AVAILABLE
No message is available.

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

Examples

The following example gets a message from a queue.

#include <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);

Related Information