gtpc2m52 | C/C++ Language Support User's Guide |
This function puts a message on a queue that was opened for output using
the MQOPEN function call.
Format
#include <cmqc.h>
void MQPUT(MQHCONN Hconn,
MQHOBJ Hobj,
PMQVOID pMsgDesc,
PMQVOID pPutMsgOpts,
MQLONG BufferLength,
PMQVOID pBuffer,
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 function call.
- Hobj
- The object handle, which represents the queue to which a message is
added. The value of Hobj was returned by a previous
MQOPEN function call with the MQOO_OUTPUT option specified.
- pMsgDesc (MQMD)
- A pointer to the message descriptor. This structure describes the
attributes of the message being put to 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
output parameter.
- Version (MQLONG)
- The version number of the structure, which must be MQMD_VERSION_1.
This is an output parameter.
- MsgType (MQLONG)
- The type of message. This is an output parameter. The TPF
MQSeries queue manager verifies that the value is valid.
The following values are valid:
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 must 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.
TPF MQSeries supports MQPER_PERSISTENCE_AS_Q_DEF (the default),
MQPER_PERSISTENT, and MQPER_NOT_PERSISTENT.
- MsgId (MQBYTE24)
- The message identifier. This is a byte string that is used to
distinguish one message from another. Messages cannot have the same
identifier, but the queue manager will allow this. The message
identifier is a permanent property of the message and continues across
restarts of the queue manager. Because the message identifier is a byte
string and not a character string, the message identifier is not
converted between character sets when the message flows from one queue manager
to another.
For the MQPUT and MQPUT1 functions, if MQMI_NONE or
MQPMO_NEW_MSG_ID is specified by the application, the queue manager generates
a unique message identifier when the message is placed on a queue, and places
it in the message descriptor that is sent with the message. The queue
manager also returns this message identifier in the message descriptor
belonging to the sending application. The application can use this
value to record information about particular messages and to respond to
queries from other parts of the application.
The sending application can also specify a particular value for the message
identifier other than MQMI_NONE; this stops the queue manager from
generating a unique message identifier. An application that is
forwarding a message can use this facility to propagate the message identifier
of the original message.
The queue manager does not make any use of this field except to:
- Generate a unique value if requested, as described previously
- Deliver the value to the application that issues the MQGET
request for the message.
On return from an MQGET function call, the MsgId field
is set to the message identifier of the message that is returned (if
any).
The following special value may be used:
- MQMI_NONE
- No message identifier is specified.
The value is binary zero for the length of the field.
For C programming language, the constant MQMI_NONE_ARRAY is also
defined; this has the same value as MQMI_NONE, but is an array of
characters instead of a string.
- 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.
The application must provide the appropriate values.
- 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.
The application must provide the appropriate values.
- PutApplType (MQLONG)
- The type of application that put the message (MQAT_TPF for TPF
applications) on the queue.
- PutDate (MQCHAR8)
- The date when the message was put on the queue. YYYYMMDD is set by
the TPF MQSeries queue manager, 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 application are passed
to the destination queue.
- pPutMsgOpts
- A pointer to the options controlling the action of the MQPUT
function.
The following values are valid:
- StrucId (MQCHAR4)
- The type of structure, which must be MQPMO_STRUC_ID.
- Version (MQLONG)
- The version number of the structure, which must be MQPMO_VERSION_1.
- Options (MQLONG)
- The options controlling the action of the MQPUT function:
The following values are valid:
- MQPMO_NONE
- No options are specified.
- MQPMO_NEW_MSG_ID
- Generate a new message identifier in a field in the MQMD.
- Note:
- Using this option overwrites the MsgId field in the
pMsgDesc parameter even if the MsgId field is not set to
MQMI_NONE.
- MQPMO_SYNCPOINT
- Put a message with syncpoint control. The request is to operate
within the normal unit of work. The message is not visible outside the
unit of work until the unit of work is committed. If the unit of work
is backed out, the message is deleted. This option applies to MQSeries
client calls only.
- Note:
- A unit of work is committed by an MQDISC function call, a
tx_commit function call from a local application, or an
MQCMIT function call from the client program over a server
connection channel. It is backed out by an MQBACK or
tx_rollback function call.
- MQPMO_NO_SYNCPOINT
- Put a message without syncpoint control. The request is to operate
within the normal unit of work. The message is available immediately
and it cannot be deleted by backing out the unit of work. This option
applies to MQSeries client calls only.
- ResolvedQMgrName (MQCHAR48)
- The TPF MQSeries queue manager puts the original queue manager name in
this field. The TPF system does not support an alias name.
- ResolvedQName (MQCHAR48)
- The TPF MQSeries queue manager puts the original queue name in this
field. The TPF system does not support an alias name.
- BufferLength
- The length of the message in the buffer. Specify 0 for a message
that has no data.
- pBuffer
- A pointer to the message data. This is a buffer containing the
application data to be sent. If the BufferLength parameter
is zero, the pBuffer parameter can be NULL.
- pCompCode
- A pointer to the location to store the completion code, which is one of
the following:
- MQCC_OK
- Successfully 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_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_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_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_MISSING_REPLY_TO_Q
- The reply to the queue is missing.
- MQRC_MSG_TOO_BIG_FOR_Q
- The message length is greater than the maximum for the queue.
- MQRC_MSG_TYPE_ERROR
- The message type in the message descriptor is not valid.
- MQRC_NOT_OPEN_FOR_OUTPUT
- The queue is not open for output.
- MQRC_OPTIONS_ERROR
- The options are not valid or are not consistent.
- MQRC_PERSISTENCE_ERROR
- Persistence is not valid.
- MQRC_PMO_ERROR
- The put message options structure is not valid.
- MQRC_PUT_INHIBITED
- The put calls are inhibited for the queue.
- MQRC_Q_DELETED
- The queue has been deleted.
- MQRC_Q_FULL
- The queue already contains the maximum number of messages.
- 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.
Programming Considerations
- If the Hconn parameter is not for a local TPF queue manager,
this MQPUT 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.
- If the MQPUT function is called from within a TPF commit scope
and the commit scope is rolled back, the MQPUT function call is
canceled.
- If ReplyToQMgr is blank, the TPF MQSeries queue manager will
resolve ReplyToQ as a local queue, a local definition of a remote
queue, or an alias queue.
- If a program has an open commit scope when it uses the MQPUT or
MQPUT1 function to put a message on a queue, the message is not
visible outside the unit of work until the unit of work is committed.
If the unit of work is rolled back, the message is deleted.
Examples
The following example puts a message on an opened queue.
#include <cmqc.h>
MQBYTE buffer[] = "THIS IS A MESSAGE";
MQMD md = {MQMD_DEFAULT}; /* Message Descriptor */
MQPMO pmo = {MQPMO_DEFAULT}; /* Put Msg Options */
MQLONG msgLength = sizeof(buffer); /* Msg length */
MQHCONN Hcon; /* Connection Handle */
MQHOBJ Hobj; /* Object Handle */
MQLONG CompCode; /* completion code */
MQLONG Reason; /* reason code */
·
·
·
md.Persistence = MQPER_PERSISTENT;
md.MsgType = MQMT_DATAGRAM;
/* Hcon Hobj from previous MQCONN MQOPEN calls */
MQPUT(Hcon, Hobj, &md, &pmo,
msgLength, buffer, &CompCode, &Reason);
if(Reason != MQRC_NONE)
{
printf("MQPUT ended with reason code %d\n", Reason);
} else
{
·
·
·
}
Related Information