gtpc2m53 | C/C++ Language Support User's Guide |
This function places a single message on a queue; the queue does not
have to be open.
Format
#include <cmqc.h>
void MQPUT1(MQHCONN Hconn,
PMQVOID pObjDesc,
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 call.
- pObjDesc
- A pointer to the object descriptor. This structure identifies the
queue to which the message is added.
- pMsgDesc (MQMD)
- A pointer to the message descriptor. This structure describes the
attributes of the message being put on 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.
- Version (MQLONG)
- The version number of the structure, which must be MQMD_VERSION_1.
- MsgType (MQLONG)
- The type of message. 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_PERSISTENT (the default) 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 reply to queue when the MsgType parameter is
MQMT_REQUEST.
The application must provide the appropriate values.
- ReplyToQMgr (MQCHAR48)
- The name of the reply to queue manager 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 MQPUT1
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 MQPUT1
function:
- 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 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_ALIAS_BASE_Q_TYPE_ERROR
- The alias base queue is not a remote queue or local queue.
- 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_MESSAGE_TYPE_ERROR
- The message type in the message descriptor is not valid.
- MQRC_NAME_NOT_VALID_FOR_TYPE
- The object type is MQOT_Q_MGR but ObjectName is not
blank.
- MQRC_NOT_OPEN_FOR_OUTPUT
- The queue is not open for output.
- MQRC_OBJECT_DAMAGED
- The object is damaged.
- MQRC_OBJECT_TYPE_ERROR
- The object type is not MQOT_Q_MGR or MQOT_Q.
- MQRC_OD_ERROR
- The object decriptor structure is not valid.
- MQRC_OPTIONS_ERROR
- The options are not valid or are not consistent.
- MQRC_OPTION_NOT_VALID_FOR_TYPE
- The specified option is not valid for the object type.
- 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.
- MQRC_UNKNOWN_ALIAS_BASE_Q
- The alias base queue is not defined.
- MQRC_UNKNOWN_OBJECT_NAME
- The object name is not known.
- MQRC_UNKNOWN_OBJECT_Q_MGR
- The object type is MQOT_Q_MGR but ObjectQMgrName is neither
blank nor the name of the local queue manager.
- MQRC_UNKNOWN_REMOTE_Q_MGR
- The remote queue manager is not defined.
- MQRC_UNKNOWN_XMIT_Q
- The transmission queue that is specified in the remote queue definition
does not exist.
- MQRC_XMIT_Q_TYPE_ERROR
- The transmission queue that is specified in the remote queue definition is
not a local queue.
- MQRC_XMIT_Q_USAGE_ERROR
- The transmission queue that is specified in the remote queue definition is
not a transmission queue.
Programming Considerations
- If the Hconn parameter is not for a local TPF MQSeries queue
manager, this MQPUT1 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 MQPUT1 function is called from within a TPF commit scope
and the commit scope is rolled back, the MQPUT1 function call is
canceled.
- 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 opens a queue, puts a single message on it, and then
closes it.
#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 */
MQLONG CompCode; /* completion code */
MQLONG Reason; /* reason code */
MQOD od = {MQOD_DEFAULT};
·
·
·
md.Persistence = MQPER_PERSISTENT;
md.MsgType = MQMT_DATAGRAM;
/* Hcon from previous MQCONN calls */
MQPUT1(Hcon, &od, &md, &pmo,
msgLength, buffer, &CompCode, &Reason);
if(Reason != MQRC_NONE)
{
printf("MQPUT ended with reason code %d\n", Reason);
} else
{
·
·
·
}
Related Information