gtpc2m4z | C/C++ Language Support User's Guide |
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
- If the Hconn parameter is not for a local TPF MQSeries queue
manager, this MQGET function call will be sent by 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 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 <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