Putting messages on a local queue using the MQPUT call
Use this information to learn about putting messages on a local queue using the MQPUT call.
- A connection handle (Hconn).
- A queue handle (Hobj).
- A description of the message that you want to put on the queue. This is in the form of a message descriptor structure (MQMD).
- Control information, in the form of a put-message options structure (MQPMO).
- The length of the data contained within the message (MQLONG).
- The message data itself.
- A reason code (MQLONG)
- A completion code (MQLONG)
If the call completes successfully, it also returns your options
structure and your message descriptor structure. The call modifies
your options structure to show the name of the queue and the queue
manager to which the message was sent. If you request that the queue
manager generates a unique value for the identifier of the message
you are putting (by specifying binary zero in the MsgId
field
of the MQMD structure), the call inserts the value in the MsgId
field
before returning this structure to you. Reset this value before you
issue another MQPUT.
There is a description of the MQPUT call in MQPUT.
Specifying handles
For
the connection handle (Hconn
)
in CICS® on z/OS® applications, you can specify
the constant MQHC_DEF_HCONN (which has the value zero), or you can
use the connection handle returned by the MQCONN or MQCONNX call.
For other applications, always use the connection handle returned
by the MQCONN or MQCONNX call.
Whatever environment you are
working in, use the same queue handle (Hobj
)
that is returned by the MQOPEN call.
Defining messages using the MQMD structure
The message descriptor structure (MQMD) is an input/output parameter for the MQPUT and MQPUT1 calls. Use it to define the message you are putting on a queue.
If MQPRI_PRIORITY_AS_Q_DEF or MQPER_PERSISTENCE_AS_Q_DEF is specified for the message and the queue is a cluster queue, the values used are those of the queue to which the MQPUT resolves. If that queue is disabled for MQPUT, the call will fail. See Configuring a queue manager cluster for more information.
MsgId
and CorrelId
are
unique. The values in these fields are returned on a successful MQPUT.There is an introduction to the message properties that MQMD describes in IBM WebSphere MQ messages, and there is a description of the structure itself in MQMD.
Specifying options using the MQPMO structure
Use the MQPMO (Put Message Option) structure to pass options to the MQPUT and MQPUT1 calls.
The following sections give you help on filling in the fields of this structure. There is a description of the structure in MQPMO.
StrucId
Version
Options
Context
ResolvedQName
ResolvedQMgrName
RecsPresent
PutMsgRecsFields
ResponseRecOffset and ResponseRecPtr
OriginalMsgHandle
NewMsgHandle
Action
PubLevel
- StrucId
- This identifies the structure as a put-message options structure. This is a 4-character field. Always specify MQPMO_STRUC_ID.
- Version
- This describes the version number of the structure. The default is MQPMO_VERSION_1. If you enter MQPMO_VERSION_2, you can use distribution lists (see Distribution lists). If you enter MQPMO_VERSION_3, you can use message handles and message properties. If you enter MQPMO_CURRENT_VERSION, your application is set always to use the most recent level.
- Options
- This
controls the following:
- Whether the put operation is included in a unit of work
- How much context information is associated with a message
- Where the context information is taken from
- Whether the call fails if the queue manager is in a quiescing state
- Whether grouping or segmentation is allowed
- Generation of a new message identifier and correlation identifier
- The order in which messages and segments are put on a queue
- Whether to resolve local queue names
If you leave the
Options
field set to the default value (MQPMO_NONE), the message you put has default context information associated with it.Also, the way that the call operates with sync points is determined by the platform. The sync point control default is yes in z/OS; for other platforms, it is no.
- Context
- This
states the name of the queue handle that you want context information
to be copied from (if requested in the
Options
field).For an introduction to message context, see Message context. For information about using the MQPMO structure to control the context information in a message, see Controlling context information.
- ResolvedQName
- This contains the name (after resolution of any alias name) of the queue that was opened to receive the message. This is an output field.
- ResolvedQMgrName
- This contains the name (after resolution of any alias name) of
the queue manager that owns the queue in
ResolvedQName
. This is an output field.
- RecsPresent
- This
field contains the number of queues in the distribution list; that
is, the number of Put Message Records (MQPMR) and corresponding Response
Records (MQRR) present.
The value that you enter can be the same as the number of Object Records provided at MQOPEN. However, if the value is less than the number of Object Records provided on the MQOPEN call, or if you provide no Put Message Records, the values of the queues that are not defined are taken from the default values provided by the message descriptor. Also, if the value is greater than the number of Object Records provided, the excess Put Message Records are ignored.
You are recommended to do one of the following:- If you want to receive a report or reply from each destination,
enter the same value as appears in the MQOR structure and use MQPMRs
containing
MsgId
fields. Either initialize theseMsgId
fields to zeros or specify MQPMO_NEW_MSG_ID.When you have put the message to the queue,
MsgId
values that the queue manager has created become available in the MQPMRs; you can use these to identify which destination is associated with each report or reply. - If you do not want to receive reports or replies, choose one of
the following:
- If you want to identify destinations that fail immediately, you
might still want to enter the same value in the
RecsPresent
field as appears in the MQOR structure and provide MQRRs to identify these destinations. Do not specify any MQPMRs. - If you do not want to identify failed destinations, enter zero
in the
RecsPresent
field and do not provide MQPMRs nor MQRRs.
- If you want to identify destinations that fail immediately, you
might still want to enter the same value in the
Note: If you are using MQPUT1, the number of Response Record Pointers and Response Record Offsets must be zero.For a full description of Put Message Records (MQPMR) and Response Records (MQRR), see MQPMR and MQRR.
- If you want to receive a report or reply from each destination,
enter the same value as appears in the MQOR structure and use MQPMRs
containing
- PutMsgRecFields
- This indicates which fields are present in each Put Message Record (MQPMR). For a list of these fields, see Using the MQPMR structure.
PutMsgRecOffset
andPutMsgRecPtr
- Pointers (typically in C) and offsets (typically
in COBOL) are used to address the Put Message Records (see Using the MQPMR structure for an
overview of the MQPMR structure).
Use the
PutMsgRecPtr
field to specify a pointer to the first Put Message Record, or thePutMsgRecOffset
field to specify the offset of the first Put Message Record. This is the offset from the start of the MQPMO. Depending on thePutMsgRecFields
field, enter a nonnull value for eitherPutMsgRecOffset
orPutMsgRecPtr
. - ResponseRecOffset and ResponseRecPtr
- You
also use pointers and offsets to address the Response Records (see Using the MQRR structure for further
information about Response Records).
Use the
ResponseRecPtr
field to specify a pointer to the first Response Record, or theResponseRecOffset
field to specify the offset of the first Response Record. This is the offset from the start of the MQPMO structure. Enter a nonnull value for eitherResponseRecOffset
orResponseRecPtr
.Note: If you are using MQPUT1 to put messages to a distribution list,ResponseRecPtr
must be null or zero andResponseRecOffset
must be zero.
- OriginalMsgHandle
- The use you can make of this field depends on the value of the Action field. If you are putting a new message with associated message properties, set this field to the message handle you previously created and set properties on. If you are forwarding, replying to, or generating a report in response to a previously retrieved message, this field contains the message handle of that message.
- NewMsgHandle
- If you specify a NewMsgHandle, any properties associated with the handle override properties associated with the OriginalMsgHandle. For more information, see Action (MQLONG).
- Action
- Use this field to specify the type of put being performed. Possible
values and their meanings are as follows:
- MQACTP_NEW
- This is a new message unrelated to any other.
- MQACTP_FORWARD
- This message was retrieved previously and is now being forwarded.
- MQACTP_REPLY
- This message is a reply to a previously retrieved message.
- MQACTP_REPORT
- This message is a report generated as a result of a previously retrieved message.
- PubLevel
- If this message is a publication, you can set this field to determine which subscriptions receive it. Only subscriptions with a SubLevel less than or equal to this value will receive this publication. The default value is 9 which is the highest level and means that subscriptions with any SubLevel can receive this publication.
The data in your message
Give the address of the buffer that contains your
data in the Buffer
parameter
of the MQPUT call. You can include anything in the data in your messages.
The amount of data in the messages, however, affects the performance
of the application that is processing them.
- The
MaxMsgLength
attribute of the queue manager - The
MaxMsgLength
attribute of the queue on which you are putting the message - The size of any message header added by WebSphere MQ (including the dead-letter header, MQDLH and the distribution list header, MQDH)
The MaxMsgLength
attribute
of the queue manager holds the size of message that the queue manager
can process. This has a default of 100 MB for all
WebSphere MQ
products at V6 or higher.
To determine the value of this attribute, use the MQINQ call on the queue manager object. For large messages, you can change this value.
The MaxMsgLength
attribute
of a queue determines the maximum size of message that you can put
on the queue. If you attempt to put a message with a size larger than
the value of this attribute, your MQPUT call fails. If you are putting
a message on a remote queue, the maximum size of message that you
can successfully put is determined by the MaxMsgLength
attribute
of the remote queue, of any intermediate transmission queues that
the message is put on along the route to its destination, and of the
channels used.
For an MQPUT operation, the size of the message
must be smaller than or equal to the MaxMsgLength
attribute
of both the queue and the queue manager. The values of these attributes
are independent, but you are recommended to set the MaxMsgLength
of
the queue to a value less than or equal to that of the queue manager.
- When you put a message on a remote queue, WebSphere MQ adds a transmission header structure (MQXQH) to the message. This structure includes the name of the destination queue and its owning queue manager.
- If WebSphere MQ cannot deliver a message to a remote queue, it attempts to put the message on the dead-letter (undelivered-message) queue. It adds an MQDLH structure to the message. This structure includes the name of the destination queue and the reason that the message was put on the dead-letter queue.
- If you want to send a message to multiple destination queues, WebSphere MQ adds an MQDH header to the message. This describes the data that is present in a message, belonging to a distribution list, on a transmission queue. Consider this when choosing an optimum value for the maximum message length.
- If the message is a segment or a message in a group, WebSphere MQ might add an MQMDE.
These structures are described in MQDH and MQMDE.
- Make the size of your
messages smaller than the
MaxMsgLength
attribute of the transmission and dead-letter queues. Allow at least the value of the MQ_MSG_HEADER_LENGTH constant (more for large distribution lists). - Make sure that the
MaxMsgLength
attribute of the dead-letter queue is set to the same as theMaxMsgLength
of the queue manager that owns the dead-letter queue.
The attributes for the queue manager and the message queuing constants are described in Attributes for the queue manager.
Putting messages: Using message handles
Two message handles are available in the MQPMO structure, OriginalMsgHandle and NewMsgHandle. The relationship between these message handles is defined by the value of the MQPMO Action field.
For full details see Action (MQLONG). A message handle is not necessarily required in order to put a message. Its purpose is to associate properties with a message, so it is required only if you are using message properties.