Field details for MQPMO

The MQPMO Put message options structure allows the application to specify options that control how messages are placed on queues, or published to topics. The structure is an input/output parameter on the MQPUT and MQPUT1 calls.

StrucId (MQCHAR4)

This is the structure identifier of the put message options structure. It is always an input field. Its value is MQPMO_STRUC_ID.

The value must be:
MQPMO_STRUC_ID
Identifier for the put message options structure.

For the C programming language, the constant MQPMO_STRUC_ID_ARRAY is also defined. This has the same value as MQPMO_STRUC_ID, but is an array of characters instead of a string.

Version (MQLONG)

Structure version number.

The value must be one of the following:
MQPMO_VERSION_1
Version-1 put-message options structure.

This version is supported in all environments.

MQPMO_VERSION_2
Version-2 put-message options structure.
This version is supported in the following environments:
  • [AIX]AIX®
  • [IBM i]IBM® i
  • [Linux]Linux®
  • [Windows]Windows
and for IBM MQ MQI clients connected to these systems.
MQPMO_VERSION_3
Version-3 put-message options structure.

This version is supported in all environments.

Fields that exist only in the more-recent version of the structure are identified as such in the descriptions of the fields. The following constant specifies the version number of the current version:
MQPMO_CURRENT_VERSION
Current version of put-message options structure.

This is always an input field. The initial value of this field is MQPMO_VERSION_1.

Options (MQLONG)

The Options field controls the operation of MQPUT and MQPUT1 calls.

Scope option

You can specify any or none of the MQPMO options. To specify more than one option, either add the values together (do not add the same constant more than once), or combine the values using the bitwise OR operation (if the programming language supports bit operations). Combinations that are not valid are noted; any other combinations are valid.

The following option controls the scope of the publications sent:
MQPMO_SCOPE_QMGR
The publication is sent only to subscribers that have subscribed on this queue manager. The publication is not forwarded to any remote publish/subscribe queue managers that have made a subscription to this queue manager, which overrides any behavior that has been set using the PUBSCOPE topic attribute.
Note: If not set, the publication scope is determined by the PUBSCOPE topic attribute.

Publishing options

The following options control the way messages are published to a topic:
MQPMO_SUPPRESS_REPLYTO

Any information specified in the ReplyToQ and ReplyToQMgr fields of the MQMD of this publication is not passed on to subscribers. If this option is used with a report option that requires a ReplyToQ, the call fails with MQRC_MISSING_REPLY_TO_Q.

MQPMO_RETAIN

The publication being sent is to be retained by the queue manager. This retention allows a subscriber to request a copy of this publication after the time it was published, by using the MQSUBRQ call. It also allows a publication to be sent to applications which make their subscription after the time this publication was made (unless they choose not to be sent it by using the option MQSO_NEW_PUBLICATIONS_ONLY). If an application is sent a publication which was retained, it is indicated by the MQIsRetained message property of that publication.

Only one publication can be retained at each node of the topic tree. Therefore, if there already is a retained publication for this topic, published by any other application, it is replaced with this publication. It is therefore better to avoid having more than one publisher retaining messages on the same topic.

When retained publications are requested by a subscriber, the subscription used might contain a wildcard in the topic, in which case a number of retained publications might match (at various nodes in the topic tree) and several publications might be sent to the requesting application. See the description of the MQSUBRQ - Subscription request call for more details.

For information about how retained publications interact with subscription levels, see Intercepting publications.

If this option is used and the publication cannot be retained, the message is not published and the call fails with MQRC_PUT_NOT_RETAINED.

MQPMO_NOT_OWN_SUBS
Tells the queue manager that the application does not want to send any of its publications to subscriptions it owns. Subscriptions are considered to be owned by the same application if the connection handles are the same.
MQPMO_WARN_IF_NO_SUBS_MATCHED
If no subscription matches the publication, return a completion code (CompCode) of MQCC_WARNING and reason code MQRC_NO_SUBS_MATCHED.

If MQRC_NO_SUBS_MATCHED is returned by the put operation, the publication was not delivered to any subscriptions. However, if the MQPMO_RETAIN option is specified on the put operation, the message is retained and delivered to any subsequently defined matching subscription.

A subscription on the topic matches the publication if any of the following conditions are met:
  • The message is delivered to the subscription queue
  • The message would have been delivered to the subscription queue but a problem with the queue means that the message cannot be put to the queue, and it was consequently placed on the dead letter queue or discarded.
  • A routing exit is defined that suppresses delivery of the message to the subscription
A subscription on the topic does not match the publication if any of the following conditions are met:
  • The subscription has a selection string that does not match the publication
  • The subscription specified the MQSO_PUBLICATION_ON_REQUEST option
  • The publication is not delivered because the MQPMO_NOT_OWN_SUBS option was specified on the put operation and the subscription matches the identity of the publisher

Syncpoint options

The following options relate to the participation of the MQPUT or MQPUT1 call within a unit of work:
MQPMO_SYNCPOINT
The request is to operate within the normal unit-of-work protocols. 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.

If MQPMO_SYNCPOINT and MQPMO_NO_SYNCPOINT are not specified, the inclusion of the put request in unit-of-work protocols is determined by the environment running the queue manager and not the environment running the application. On z/OS®, the put request is within a unit of work. In all other environments, the put request is not within a unit of work.

Because of these differences, an application that you want to port must not allow this option to default; specify either MQPMO_SYNCPOINT or MQPMO_NO_SYNCPOINT explicitly.

Do not specify MQPMO_SYNCPOINT with MQPMO_NO_SYNCPOINT.

MQPMO_NO_SYNCPOINT
The request is to operate outside the normal unit-of-work protocols. The message is available immediately, and it cannot be deleted by backing out a unit of work.

If MQPMO_NO_SYNCPOINT and MQPMO_SYNCPOINT are not specified, the inclusion of the put request in unit-of-work protocols is determined by the environment running the queue manager and not the environment running the application. On z/OS, the put request is within a unit of work. In all other environments, the put request is not within a unit of work.

Because of these differences, an application that you want to port must not allow this option to default; specify either MQPMO_SYNCPOINT or MQPMO_NO_SYNCPOINT explicitly.

Do not specify MQPMO_NO_SYNCPOINT with MQPMO_SYNCPOINT.

Message-identifier and correlation-identifier options

The following options request the queue manager to generate a new message identifier or correlation identifier:
MQPMO_NEW_MSG_ID
The queue manager replaces the contents of the MsgId field in MQMD with a new message identifier. This message identifier is sent with the message, and returned to the application on output from the MQPUT or MQPUT1 call.

The MQPMO_NEW_MSG_ID option can also be specified when the message is being put to a distribution list; see the description of the MsgId field in the MQPMR structure for details.

Using this option relieves the application of the need to reset the MsgId field to MQMI_NONE before each MQPUT or MQPUT1 call.

MQPMO_NEW_CORREL_ID
The queue manager replaces the contents of the CorrelId field in MQMD with a new correlation identifier. This correlation identifier is sent with the message, and returned to the application on output from the MQPUT or MQPUT1 call.

The MQPMO_NEW_CORREL_ID option can also be specified when the message is being put to a distribution list; see the description of the CorrelId field in the MQPMR structure for details.

MQPMO_NEW_CORREL_ID is useful in situations where the application requires a unique correlation identifier.

Group and segment options

The following options relate to the processing of messages in groups and segments of logical messages. Read the definitions that follow to help you to understand the option.
Attention: You cannot use segmented or grouped messages with Publish/Subscribe.
Physical message
The is the smallest unit of information that can be placed on or removed from a queue; it often corresponds to the information specified or retrieved on a single MQPUT, MQPUT1, or MQGET call. Every physical message has its own message descriptor (MQMD). Generally, physical messages are distinguished by differing values for the message identifier (MsgId field in MQMD), although this is not enforced by the queue manager.
Logical message
A logical message is a single unit of application information for non- z/OS platforms only. In the absence of system constraints, a logical message is the same as a physical message. But where logical messages are extremely large, system constraints might make it advisable or necessary to split a logical message into two or more physical messages, called segments.

A logical message that has been segmented consists of two or more physical messages that have the same non-null group identifier (GroupId field in MQMD), and the same message sequence number (MsgSeqNumber field in MQMD). The segments are distinguished by differing values for the segment offset (Offset field in MQMD), which gives the offset of the data in the physical message from the start of the data in the logical message. Because each segment is a physical message, the segments in a logical message usually have differing message identifiers.

A logical message that has not been segmented, but for which segmentation has been permitted by the sending application, also has a non-null group identifier, although in this case there is only one physical message with that group identifier if the logical message does not belong to a message group. Logical messages for which segmentation has been inhibited by the sending application have a null group identifier (MQGI_NONE), unless the logical message belongs to a message group.

Message group
A message group is a set of one or more logical messages that have the same non-null group identifier. The logical messages in the group are distinguished by differing values for the message sequence number, which is an integer in the range 1 through n, where n is the number of logical messages in the group. If one or more of the logical messages is segmented, there are more than n physical messages in the group.
MQPMO_LOGICAL_ORDER
This option tells the queue manager how the application puts messages in groups and segments of logical messages. It can be specified only on the MQPUT call; it is not valid on the MQPUT1 call.
If MQPMO_LOGICAL_ORDER is specified, it indicates that the application uses successive MQPUT calls to:
  1. Put the segments in each logical message in the order of increasing segment offset, starting from 0, with no gaps.
  2. Put all the segments in one logical message before putting the segments in the next logical message.
  3. Put the logical messages in each message group in the order of increasing message sequence number, starting from 1, with no gaps. IBM MQ increments the message sequence number automatically.
  4. Put all the logical messages in one message group before putting logical messages in the next message group.

For detailed information about MQPMO_LOGICAL_ORDER, see Logical and physical ordering

Context options

The following options control the processing of message context:
MQPMO_NO_CONTEXT
Both identity and origin context are set to indicate no context. This means that the context fields in MQMD are set to:
  • Blanks for character fields
  • Nulls for byte fields
  • Zeros for numeric fields
MQPMO_DEFAULT_CONTEXT
The message is to have default context information associated with it, for both identity and origin. The queue manager sets the context fields in the message descriptor as follows:
Table 1. Default context information values for MQMD fields
Field in MQMD Value used
UserIdentifier Determined from the environment if possible; set to blanks otherwise.
AccountingToken Determined from the environment if possible; set to MQACT_NONE otherwise.
ApplIdentityData Set to blanks.
PutApplType Determined from the environment.
PutApplName Determined from the environment if possible; set to blanks otherwise.
PutDate Set to the date when message is put.
PutTime Set to the time when message is put.
ApplOriginData Set to blanks.
For more information about message context, see Message context.

These are the default values and actions if no context options are specified.

MQPMO_PASS_IDENTITY_CONTEXT
The message is to have context information associated with it. Identity context is taken from the queue handle specified in the Context field. Origin context information is generated by the queue manager in the same way that it is for MQPMO_DEFAULT_CONTEXT (see the preceding table for values). For more information about message context, see Message context.

For the MQPUT call, the queue must have been opened with the MQOO_PASS_IDENTITY_CONTEXT option (or an option that implies it). For the MQPUT1 call, the same authorization check is carried out as for the MQOPEN call with the MQOO_PASS_IDENTITY_CONTEXT option.

MQPMO_PASS_ALL_CONTEXT
The message is to have context information associated with it. Context is taken from the queue handle specified in the Context field. For more information about message context, see Controlling context information.

For the MQPUT call, the queue must have been opened with the MQOO_PASS_ALL_CONTEXT option (or an option that implies it). For the MQPUT1 call, the same authorization check is carried out as for the MQOPEN call with the MQOO_PASS_ALL_CONTEXT option.

MQPMO_SET_IDENTITY_CONTEXT
The message is to have context information associated with it. The application specifies the identity context in the MQMD structure. Origin context information is generated by the queue manager in the same way that it is for MQPMO_DEFAULT_CONTEXT (see the preceding table for values). For more information about message context, see Message context.

For the MQPUT call, the queue must have been opened with the MQOO_SET_IDENTITY_CONTEXT option (or an option that implies it). For the MQPUT1 call, the same authorization check is carried out as for the MQOPEN call with the MQOO_SET_IDENTITY_CONTEXT option.

MQPMO_SET_ALL_CONTEXT
The message is to have context information associated with it. The application specifies the identity, origin, and user context in the MQMD structure. For more information about message context, see Message context.

For the MQPUT call, the queue must have been opened with the MQOO_SET_ALL_CONTEXT option. For the MQPUT1 call, the same authorization check is carried out as for the MQOPEN call with the MQOO_SET_ALL_CONTEXT option.

You can specify only one of the MQPMO_*_CONTEXT context options. If you specify none, MQPMO_DEFAULT_CONTEXT is assumed.

Property options

The following option relates to the properties of the message:
MQPMO_MD_FOR_OUTPUT_ONLY
The message descriptor parameter must only be used for output to return the message descriptor of the message that was put. The message descriptor fields associated with the NewMsgHandle, OriginalMsgHandle, or both fields, of the MQPMO structure must be used for input.

If a valid message handle is not provided then the call fails with reason code MQRC_MD_ERROR.

Put response options

The following options control the response returned to an MQPUT or MQPUT1 call. You can specify only one of these options. If MQPMO_ASYNC_RESPONSE and MQPMO_SYNC_RESPONSE are not specified, MQPMO_RESPONSE_AS_Q_DEF or MQPMO_RESPONSE_AS_TOPIC_DEF is assumed.
MQPMO_ASYNC_RESPONSE
The MQPMO_ASYNC_RESPONSE option requests that an MQPUT or MQPUT1 operation is completed without the application waiting for the queue manager to complete the call. Using this option can improve messaging performance, particularly for applications using client bindings. An application can periodically check, using the MQSTAT verb, whether an error has occurred during any previous asynchronous calls.
With this option, only the following fields are guaranteed to be completed in the MQMD;
  • ApplIdentityData
  • PutApplType
  • PutApplName
  • ApplOriginData
Additionally, if either or both of MQPMO_NEW_MSG_ID or MQPMO_NEW_CORREL_ID are specified as options, the MsgId and CorrelId returned are also completed. (MQPMO_NEW_MSG_ID can be implicitly specified by specifying a blank MsgId field).
Only the preceding specified fields are completed. Other information that would normally be returned in the MQMD or MQPMO structure is undefined.
When requesting asynchronous put response for MQPUT1, the ResolvedQName and ResolvedQMgrName returned in the MQOD structure are undefined.
When requesting asynchronous put response for MQPUT or MQPUT1, a CompCode and Reason of MQCC_OK and MQRC_NONE does not necessarily mean that the message was successfully put to a queue. When developing an MQI application that uses asynchronous put response and requires confirmation that messages have been put to a queue you must check both CompCode and Reason codes from the put operations and also use MQSTAT to query asynchronous error information.
Although the success or failure of each individual MQPUT or MQPUT1 call mightnot be returned immediately, the first error that occurred under an asynchronous call can be determined later through a call to MQSTAT.
If a persistent message under syncpoint fails to be delivered using asynchronous put response, and you attempt to commit the transaction, the commit fails and the transaction is backed out with a completion code of MQCC_FAILED and a reason of MQRC_BACKED_OUT. The application can make a call to MQSTAT to determine the cause of a previous MQPUT or MQPUT1 failure.
If a non-persistent message under syncpoint fails to be delivered using asynchronous put response, and you attempt to commit the transaction, the commit succeeds but the non-persistent message is lost. To avoid this situation, the application should make a call to MQSTAT to determine if there were any previous MQPUT or MQPUT1 failures, before calling MQCMIT. If there were failures, the application should call MQBACK.
MQPMO_SYNC_RESPONSE
Specifying this put response type ensures that the MQPUT or MQPUT1 operation is always issued synchronously. If the put operation is successful, all fields in the MQMD and MQPMO are completed.
This option ensures a synchronous response irrespective of the default put response value defined on the queue or topic object.
MQPMO_RESPONSE_AS_Q_DEF
If this value is specified for an MQPUT call, the put response type used is taken from the DEFPRESP value specified on the queue when it was first opened by the application.
  • If the queue is a cluster queue, and this value is specified for an MQPUT call, the put response type used is taken from the DEFPRESP attribute defined at the destination queue manager that owns the particular instance of the queue on which the message is placed.

    When there are multiple instances of the cluster queue, and they differ in this attribute, the value from one of them is picked and it cannot be predicted which one will be used. You should therefore set this attribute to the same value on all instances. If this is not the case, error message AMQ9407 is issued to the queue manager logs. See also How are destination object attributes resolved for aliases, remote and cluster queues?

  • If the queue is not a cluster queue, and this value is specified for an MQPUT call, the put response type used is taken from the DEFPRESP attribute defined at the local queue manager, even if the destination queue manager is remote.
If a client application is connected to a queue manager at a level earlier than IBM WebSphere® MQ 7.0, it behaves as if MQPMO_SYNC_RESPONSE was specified.
If this option is specified for an MQPUT1 call, the value of the DEFPRESP attribute is not known before the request is sent to the server. By default, if the MQPUT1 call is using MQPMO_SYNCPOINT it behaves as for MQPMO_ASYNC_RESPONSE, and if it is using MQPMO_NO_SYNCPOINT it behaves as for MQPMO_SYNC_RESPONSE. However, you can override this default behavior by setting the Put1DefaultAlwaysSync property in the client configuration file, see CHANNELS stanza of the client configuration file.
MQPMO_RESPONSE_AS_TOPIC_DEF
MQPMO_RESPONSE_AS_TOPIC_DEF is a synonym for MQPMO_RESPONSE_AS_Q_DEF for use with topic objects.

Other options

The following options control authorization checking, what happens when the queue manager is quiescing, and resolving queue and queue manager names:
MQPMO_ALTERNATE_USER_AUTHORITY
MQPMO_ALTERNATE_USER_AUTHORITY indicates that the AlternateUserId field in the ObjDesc parameter of the MQPUT1 call contains a user identifier that is to be used to validate authority to put messages on the queue. The call can succeed only if AlternateUserId is authorized to open the queue with the specified options, regardless of whether the user identifier under which the application is running is authorized to do so. (This does not apply to the context options specified, however, which are always checked against the user identifier under which the application is running.)

This option is valid only with the MQPUT1 call.

MQPMO_FAIL_IF_QUIESCING
This option forces the MQPUT or MQPUT1 call to fail if the queue manager is in the quiescing state.

On z/OS, this option also forces the MQPUT or MQPUT1 call to fail if the connection (for a CICS® or IMS application) is in the quiescing state.

The call returns completion code MQCC_FAILED with reason code MQRC_Q_MGR_QUIESCING or MQRC_CONNECTION_QUIESCING.

MQPMO_RESOLVE_LOCAL_Q
Use this option to fill ResolvedQName in the MQPMO structure with the name of the local queue to which the message is put, and ResolvedQMgrName with the name of the local queue manager that hosts the local queue. For more information about MQPMO_RESOLVE_LOCAL_Q, see topic MQOO_RESOLVE_LOCAL_Q.

If you are authorized to put to a queue, you have the required authority to specify this flag on the MQPUT call; no special authority is needed.

Default option

If you need none of the options described, use the following option:
MQPMO_NONE
Use this value to indicate that no other options have been specified; all options assume their default values. MQPMO_NONE is defined to aid program documentation; it is not intended that this option be used with any other, but as its value is zero, such use cannot be detected.

MQPMO_NONE is an input field. The initial value of the Options field is MQPMO_NONE.

Timeout (MQLONG)

This is a reserved field; its value is not significant. The initial value of this field is -1.

Context (MQHOBJ)

If MQPMO_PASS_IDENTITY_CONTEXT or MQPMO_PASS_ALL_CONTEXT is specified, this field must contain the input queue handle from which context information to be associated with the message being put is taken.

If neither MQPMO_PASS_IDENTITY_CONTEXT nor MQPMO_PASS_ALL_CONTEXT is specified, this field is ignored.

This is an input field. The initial value of this field is 0.

KnownDestCount (MQLONG)

This is the number of messages that the current MQPUT or MQPUT1 call has sent successfully to queues in the distribution list that are local queues. The count does not include messages sent to queues that resolve to remote queues (even though a local transmission queue is used initially to store the message). This field is also set when putting a message to a single queue that is not in a distribution list.

This is an output field. The initial value of this field is 0. This field is not set if Version is less than MQPMO_VERSION_1.

[z/OS]This field is undefined on z/OS because distribution lists are not supported.

UnknownDestCount (MQLONG)

This is the number of messages that the current MQPUT or MQPUT1 call has sent successfully to queues in the distribution list that resolve to remote queues. Messages that the queue manager retains temporarily in distribution-list form count as the number of individual destinations that those distribution lists contain. This field is also set when putting a message to a single queue that is not in a distribution list.

This is an output field. The initial value of this field is 0. This field is not set if Version is less than MQPMO_VERSION_1.

[z/OS]This field is undefined on z/OS because distribution lists are not supported.

InvalidDestCount (MQLONG)

This is the number of messages that could not be sent to queues in the distribution list. The count includes queues that failed to open, as well as queues that were opened successfully but for which the put operation failed. This field is also set when putting a message to a single queue that is not in a distribution list.

Note: This field is set if the CompCode parameter on the MQPUT or MQPUT1 call is MQCC_OK or MQCC_WARNING; it might be set if the CompCode parameter is MQCC_FAILED, but do not rely on this in application code.

This is an output field. The initial value of this field is 0. This field is not set if Version is less than MQPMO_VERSION_1.

[z/OS]This field is undefined on z/OS because distribution lists are not supported.

ResolvedQName (MQCHAR48)

This is the name of the destination queue after name resolution has been performed by the local queue manager. The name returned is the name of a queue that exists on the queue manager identified by ResolvedQMgrName.

A nonblank value is returned only if the object is a single queue; if the object is a distribution list or a topic, the value returned is undefined.

This is an output field. The length of this field is given by MQ_Q_NAME_LENGTH. The initial value of this field is the null string in C, and 48 blank characters in other programming languages.

ResolvedQMgrName (MQCHAR48)

This is the name of the destination queue manager after name resolution has been performed by the local queue manager. The name returned is the name of the queue manager that owns the queue identified by ResolvedQName, and can be the name of the local queue manager.

If ResolvedQName is a shared queue that is owned by the queue sharing group to which the local queue manager belongs, ResolvedQMgrName is the name of the queue sharing group. If the queue is owned by some other queue sharing group, ResolvedQName can be the name of the queue sharing group or the name of a queue manager that is a member of the queue sharing group (the nature of the value returned is determined by the queue definitions that exist at the local queue manager).

A nonblank value is returned only if the object is a single queue; if the object is a distribution list or a topic, the value returned is undefined.

This is an output field. The length of this field is given by MQ_Q_MGR_NAME_LENGTH. The initial value of this field is the null string in C, and 48 blank characters in other programming languages.

RecsPresent (MQLONG)

This is the number of MQPMR put message records or MQRR response records that have been provided by the application. This number can be greater than zero only if the message is being put to a distribution list. Put message records and response records are optional; the application need not provide any records, or it can choose to provide records of only one type. However, if the application provides records of both types, it must provide RecsPresent records of each type.

The value of RecsPresent need not be the same as the number of destinations in the distribution list. If too many records are provided, the excess are not used; if too few records are provided, default values are used for the message properties for those destinations that do not have put message records (see PutMsgRecOffset).

If RecsPresent is less than zero, or is greater than zero but the message is not being put to a distribution list, the call fails with reason code MQRC_RECS_PRESENT_ERROR.

This is an input field. The initial value of this field is 0. This field is ignored if Version is less than MQPMO_VERSION_2.

PutMsgRecFields (MQLONG)

This field contains flags that indicate which MQPMR fields are present in the put message records provided by the application. Use PutMsgRecFields only when the message is being put to a distribution list. The field is ignored if RecsPresent is zero, or both PutMsgRecOffset and PutMsgRecPtr are zero.

For fields that are present, the queue manager uses for each destination the values from the fields in the corresponding put message record. For fields that are absent, the queue manager uses the values from the MQMD structure.

Use one or more of the following flags to indicate which fields are present in the put message records:
MQPMRF_MSG_ID
Message-identifier field is present.
MQPMRF_CORREL_ID
Correlation-identifier field is present.
MQPMRF_GROUP_ID
Group-identifier field is present.
MQPMRF_FEEDBACK
Feedback field is present.
MQPMRF_ACCOUNTING_TOKEN
Accounting-token field is present.

If you specify this flag, specify either MQPMO_SET_IDENTITY_CONTEXT or MQPMO_SET_ALL_CONTEXT in the Options field; if this condition is not satisfied, the call fails with reason code MQRC_PMO_RECORD_FLAGS_ERROR.

If no MQPMR fields are present, the following can be specified:
MQPMRF_NONE
No put-message record fields are present.

If this value is specified, either RecsPresent must be zero, or both PutMsgRecOffset and PutMsgRecPtr must be zero.

MQPMRF_NONE is defined to aid program documentation. It is not intended that this constant be used with any other, but as its value is zero, such use cannot be detected.

If PutMsgRecFields contains flags that are not valid, or put message records are provided but PutMsgRecFields has the value MQPMRF_NONE, the call fails with reason code MQRC_PMO_RECORD_FLAGS_ERROR.

This is an input field. The initial value of this field is MQPMRF_NONE. This field is ignored if Version is less than MQPMO_VERSION_2.

PutMsgRecOffset (MQLONG)

This is the offset in bytes of the first MQPMR put message record from the start of the MQPMO structure. The offset can be positive or negative. PutMsgRecOffset is used only when the message is being put to a distribution list. The field is ignored if RecsPresent is zero.

When the message is being put to a distribution list, an array of one or more MQPMR put message records can be provided in order to specify certain properties of the message for each destination individually; these properties are:
  • Message identifier
  • Correlation identifier
  • Group identifier
  • Feedback value
  • Accounting token

You do not need to specify all these properties, but whatever subset you choose, specify the fields in the correct order. See the description of the MQPMR structure for further details.

Usually, there must be as many put message records as there are object records specified by MQOD when the distribution list is opened; each put message record supplies the message properties for the queue identified by the corresponding object record. Queues in the distribution list that fail to open must still have put message records allocated for them at the appropriate positions in the array, although the message properties are ignored in this case.

The number of put message records can differ from the number of object records. If there are fewer put message records than object records, the message properties for the destinations that do not have put message records are taken from the corresponding fields in the message descriptor MQMD. If there are more put message records than object records, the excess are not used (although it must still be possible to access them). Put message records are optional, but if they are supplied there must be RecsPresent of them.

Provide the put message records in a similar way to the object records in MQOD, either by specifying an offset in PutMsgRecOffset, or by specifying an address in PutMsgRecPtr ; for details of how to do this, see the ObjectRecOffset field described inMQOD - Object descriptor.

No more than one of PutMsgRecOffset and PutMsgRecPtr can be used; the call fails with reason code MQRC_PUT_MSG_RECORDS_ERROR if both are nonzero.

This is an input field. The initial value of this field is 0. This field is ignored if Version is less than MQPMO_VERSION_2.

ResponseRecOffset (MQLONG)

This is the offset in bytes of the first MQRR response record from the start of the MQPMO structure. The offset can be positive or negative. ResponseRecOffset is used only when the message is being put to a distribution list. The field is ignored if RecsPresent is zero.

When putting the message to a distribution list, you can provide an array of one or more MQRR response records to identify the queues to which the message was not sent successfully (CompCode field in MQRR), and the reason for each failure (Reason field in MQRR). The message might not have been sent either because the queue failed to open, or because the put operation failed. The queue manager sets the response records only when the outcome of the call is mixed (that is, some messages were sent successfully while others failed, or all failed but for differing reasons); reason code MQRC_MULTIPLE_REASONS from the call indicates this case. If the same reason code applies to all queues, that reason is returned in the Reason parameter of the MQPUT or MQPUT1 call, and the response records are not set.

Usually, there are as many response records as there are object records specified by MQOD when the distribution list is opened; when necessary, each response record is set to the completion code and reason code for the put to the queue identified by the corresponding object record. Queues in the distribution list that fail to open must still have response records allocated for them at the appropriate positions in the array, although they are set to the completion code and reason code resulting from the open operation, rather than the put operation.

The number of response records can differ from the number of object records. If there are fewer response records than object records, the application might not be able to identify all the destinations for which the put operation failed, or the reasons for the failures. If there are more response records than object records, the excess are not used (although it must still be possible to access them). Response records are optional, but if they are supplied there must be RecsPresent of them.

Provide the response records in a similar way to the object records in MQOD, either by specifying an offset in ResponseRecOffset, or by specifying an address in ResponseRecPtr ; for details of how to do this, see the ObjectRecOffset field described in MQOD - Object descriptor. However, use no more than one of ResponseRecOffset and ResponseRecPtr ; the call fails with reason code MQRC_RESPONSE_RECORDS_ERROR if both are nonzero.

For the MQPUT1 call, this field must be zero. This is because the response information (if requested) is returned in the response records specified by the object descriptor MQOD.

This is an input field. The initial value of this field is 0. This field is ignored if Version is less than MQPMO_VERSION_2.

PutMsgRecPtr (MQPTR)

This is the address of the first MQPMR put message record. Use PutMsgRecPtr only when the message is being put to a distribution list. The field is ignored if RecsPresent is zero.

You can use either PutMsgRecPtr or PutMsgRecOffset can be used to specify the put message records, but not both; for details, see PutMsgRecOffset. If you do not use PutMsgRecPtr, set it to the null pointer or null bytes.

This is an input field. The initial value of this field is the null pointer in those programming languages that support pointers, and an all-null byte string otherwise. This field is ignored if Version is less than MQPMO_VERSION_2.

Note: On platforms where the programming language does not support the pointer data type, this field is declared as a byte string of the appropriate length, with the initial value being the all-null byte string.

ResponseRecPtr (MQPTR)

This is the address of the first MQRR response record. ResponseRecPtr is used only when the message is being put to a distribution list. The field is ignored if RecsPresent is zero.

Use either ResponseRecPtr or ResponseRecOffset to specify the response records, but not both; for details, see ResponseRecOffset. If you do not use ResponseRecPtr set it to the null pointer or null bytes.

For the MQPUT1 call, this field must be the null pointer or null bytes. This is because the response information (if requested) is returned in the response records specified by the object descriptor MQOD.

This is an input field. The initial value of this field is the null pointer in those programming languages that support pointers, and an all-null byte string otherwise. This field is ignored if Version is less than MQPMO_VERSION_2.

Note: On platforms where the programming language does not support the pointer data type, this field is declared as a byte string of the appropriate length, with the initial value being the all-null byte string.

OriginalMsgHandle (MQHMSG)

This is an optional handle to a message. It might have been previously retrieved from a queue. The use of this handle is subject to the value of the Action field; see also NewMsgHandle.

The contents of the original message handle will not be altered by the MQPUT or MQPUT1 call.

This is an input field. The initial value of this field is MQHM_NONE. This field is ignored if Version is less than MQPMO_VERSION_3.

NewMsgHandle (MQHMSG)

This is an optional handle to the message being put subject to the value of the Action field. It defines the properties of the message and overrides the values of the OriginalMsgHandle, if specified.

On return from the MQPUT or MQPUT1 call, the contents of the handle reflect the message that was actually put.

This is an input field. The initial value of this field is MQHM_NONE. This field is ignored if Version is less than MQPMO_VERSION_3.

Action (MQLONG)

This specifies the type of put being performed and the relationship between the original message specified by the OriginalMsgHandle field and the new message specified by the NewMsgHandle field. The properties of the message are chosen by the queue manager according to the value of the Action specified.

You can choose to supply the contents of the message descriptor using the MsgDesc parameter on the MQPUT or MQPUT1 calls. Alternatively it is possible not to supply the MsgDesc parameter, or to specify that it is output-only by including MQPMO_MD_FOR_OUTPUT_ONLY in the Options field of the MQPMO structure.

If the MsgDesc parameter is not supplied, or if it is specified to be output-only, then the message descriptor for the new message is populated from the message handle fields of the MQPMO, according to the rules described in this topic.

The context setting and passing activities described in Controlling context information take effect after the message descriptor has been composed.

If an incorrect action value is specified, the call fails with the reason code MQRC_ACTION_ERROR.

Any one of the following actions can be specified:
MQACTP_NEW
A new message is being put, and no relationship to a previous message is being specified by the program. The message descriptor is composed as follows:
  • If a MsgDesc is supplied on the MQPUT or MQPUT1 call, and MQPMO_MD_FOR_OUTPUT_ONLY is not in the MQPMO.Options, this is used as the message descriptor unmodified.
  • If a MsgDesc is not supplied, or MQPMO_MD_FOR_OUTPUT_ONLY is in the MQPMO.Options then the queue manager generates the message descriptor using a combination of properties from OriginalMsgHandle and NewMsgHandle. Any message descriptor fields explicitly set on the new message handle take precedence over those in the original message handle.
Message data is taken from the MQPUT or MQPUT1 Buffer parameter.
MQACTP_FORWARD
A previously retrieved message is being forwarded. The original message handle specifies the message that was previously retrieved.

The new message handle specifies any modifications to the properties (including any in the message descriptor) in the original message handle.

The message descriptor is composed as follows:
  • If a MsgDesc is supplied on the MQPUT or MQPUT1 call, and MQPMO_MD_FOR_OUTPUT_ONLY is not in the MQPMO.Options, this is used as the message descriptor unmodified.
  • If a MsgDesc is not supplied, or MQPMO_MD_FOR_OUTPUT_ONLY is in the MQPMO.Options then the queue manager generates the message descriptor using a combination of properties from OriginalMsgHandle and NewMsgHandle. Any message descriptor fields explicitly set on the new message handle take precedence over those in the original message handle.
  • If MQPMO_NEW_MSG_ID or MQPMO_NEW_CORREL_ID are specified in the MQPMO.Options, then these are honoured.
The message properties are composed as follows:
  • All properties from the original message handle which have MQCOPY_FORWARD in the MQPD.CopyOptions
  • All properties from the new message handle. For each property in the new message handle that has the same name as a property in the original message handle, the value is taken from the new message handle. The only exception to this rule is the special case when the property in the new message handle has the same name as a property in the original message handle, but the value of the property is null. In this case the property is removed from the message.

The message data to be forwarded is taken from the MQPUT or MQPUT1 Buffer parameter.

MQACTP_REPLY
A reply is being made to a previously retrieved message. The original message handle specifies the message that was previously retrieved.

The new message handle specifies any modifications to the properties (including any in the message descriptor) in the original message handle.

The message descriptor is composed as follows:
  • If a MsgDesc is supplied on the MQPUT or MQPUT1 call, and MQPMO_MD_FOR_OUTPUT_ONLY is not in the MQPMO.Options, this is used as the message descriptor unmodified.
  • If a MsgDesc is not supplied, or MQPMO_MD_FOR_OUTPUT_ONLY is in the MQPMO.Options, then initial message descriptor fields are chosen as follows:
    Table 2. Reply message handle transformation
    Field in MQMD Value used
    Report
    If MQRO_PASS_DISCARD_AND_EXPIRY
    and MQRO_DISCARD_MSG are set:
    MQRO_DISCARD_MSG
    otherwise
    MQRO_NONE
    MsgType MQMT_REPLY
    Expiry
    If MQRO_PASS_DISCARD_AND_EXPIRY
    is set:
    Copied from the input message
    otherwise
    MQEI_UNLIMITED
    Feedback MQFB_NONE
    MsgId
    If MQPMO_NEW_MSG_ID is set:
    A new message identifier is generated
    else if MQRO_PASS_MSG_ID is set:
    Copied from the input message
    otherwise
    MQMI_NONE
    CorrelId
    If MQPMO_NEW_CORREL_ID is set:
    A new correlation identifier is generated
    else if MQRO_COPY_MSG_ID_TO_CORREL_ID is set:
    Copied from the MsgId field of the
    input message
    else if MQRO_PASS_CORREL_ID is set:
    Copied from the CorrelId field of the
    input message
    otherwise
    MQCI_NONE
    BackoutCount 0
    ReplyToQ Blanks
    ReplyToQMgr Blanks
    GroupId MQGI_NONE
    MsgSeqNumber 1
    Offset 0
    MsgFlags MQMF_NONE
    OriginalLength MQOL_UNDEFINED
  • The message descriptor is then modified by the new message handle - any message descriptor fields explicitly set as properties in the new message handle take precedence over the message descriptor fields as described previously.
The message properties are composed as follows:
  • All properties from the original message handle which have MQCOPY_REPLY in the MQPD.CopyOptions
  • All properties from the new message handle. For each property in the new message handle that has the same name as a property in the original message handle, the value is taken from the new message handle. The only exception to this rule is the special case when the property in the new message handle has the same name as a property in the original message handle, but the value of the property is null. In this case the property is removed from the message.
The message data to be forwarded is taken from the MQPUT/MQPUT1 Buffer parameter.
MQACTP_REPORT
A report is being generated as a result of a previously retrieved message. The original message handle specifies the message causing the report to be generated.

The new message handle specifies any modifications to the properties (including any in the message descriptor) in the original message handle.

The message descriptor is composed as follows:
  • If a MsgDesc is supplied on the MQPUT or MQPUT1 call, and MQPMO_MD_FOR_OUTPUT_ONLY is not in the MQPMO.Options, this is used as the message descriptor unmodified.
  • If a MsgDesc is not supplied, or MQPMO_MD_FOR_OUTPUT_ONLY is in the MQPMO.Options then initial message descriptor fields are chosen as follows:
    Table 3. Report message handle transformation
    Field in MQMD Value used
    Report
    If MQRO_PASS_DISCARD_AND_EXPIRY and
    MQRO_DISCARD_MSG are set:
    MQRO_DISCARD_MSG
    otherwise
    MQRO_NONE
    MsgType MQMT_REPORT
    Expiry
    If MQRO_PASS_DISCARD_AND_EXPIRY
    is set:
    Copied from the input message
    otherwise
    MQEI_UNLIMITED
    MsgId
    If MQPMO_NEW_MSG_ID is set:
    A new message identifier is generated
    else if MQRO_PASS_MSG_ID is set:
    Copied from the input message
    otherwise
    MQMI_NONE
    CorrelId
    If MQPMO_NEW_CORREL_ID is set:
    A new correlation identifier is generated
    else if MQRO_COPY_MSG_ID_TO_CORREL_ID is set:
    Copied from the MsgId field of the
    input message
    else if MQRO_PASS_CORREL_ID is set:
    Copied from the CorrelId field of the
    input message
    otherwise
    MQCI_NONE
    BackoutCount 0
    ReplyToQ Blanks
    ReplyToQMgr Blanks
    OriginalLength Set to the BufferLength
  • The message descriptor is then modified by the new message handle - any message descriptor fields explicitly set as properties in the new message handle take precedence over the message descriptor fields as described previously.
The message properties are composed as follows:
  • All properties from the original message handle which have MQCOPY_REPORT in the MQPD.CopyOptions
  • All properties from the new message handle. For each property in the new message handle that has the same name as a property in the original message handle, the value is taken from the new message handle. The only exception to this rule is the special case when the property in the new message handle has the same name as a property in the original message handle, but the value of the property is null. In this case the property is removed from the message.

The Feedback field in the resultant MQMD represents the report that is to be generated. A Feedback value of MQFB_NONE causes the MQPUT or MQPUT1 call to fail with reason code MQRC_FEEDBACK_ERROR.

To choose the user data of the report message, IBM MQ consults the Report and Feedback fields in the resultant MQMD, and the Buffer and BufferLength parameters of the MQPUT or MQPUT1 call.
  • If Feedback is MQFB_COA, MQFB_COD or MQFB_EXPIRATION then the value of Report is inspected.
  • If any of the following cases is true, the full message data from Buffer for a length of BufferLength is used.
    • Feedback is MQFB_EXPIRATION and Report contains MQRO_EXPIRATION_WITH_FULL_DATA
    • Feedback is MQFB_COD and Report contains MQRO_COD_WITH_FULL_DATA
    • Feedback is MQFB_COA and Report contains MQRO_COA_WITH_FULL_DATA
  • If any of the following cases is true, the first 100 bytes of the message (or BufferLength if this is less than 100) from Buffer are used
    • Feedback is MQFB_EXPIRATION and Report contains MQRO_EXPIRATION_WITH_DATA
    • Feedback is MQFB_COD and Report contains MQRO_COD_WITH_DATA
    • Feedback is MQFB_COA and Report contains MQRO_COA_WITH_DATA
  • If Feedback is MQFB_EXPIRATION, MQFB_COD or MQFB_COA, and Report does not contain the *_WITH_FULL_DATA or *_WITH_DATA options relevant to that Feeback value, then no user data is included with the message.
  • If Feedback takes a different value from those listed above, then Buffer and BufferLength are used as normal.
The derivation of the user data described in the previous list is also shown in the following table:
Table 4. Source of user data
  MQFB_COA MQFB_COD MQFB_EXPIRATION
MQRO_EXPIRATION _WITH_FULL_DATA None None Buffer(Bufferlength)
MQRO_COD_WITH _FULL_DATA None Buffer(Bufferlength) None
MQRO_COA_WITH _FULL_DATA Buffer(Bufferlength) None None
MQRO_EXPIRATION _WITH_DATA None None Buffer(First 100 bytes)
MQRO_COD_WITH_DATA None Buffer(First 100 bytes) None
MQRO_COA_WITH_DATA Buffer(First 100 bytes) None None

PubLevel (MQLONG)

The initial value of this field is 9. The level of subscription targeted by this publication. Only those subscriptions with the highest SubLevel less than or equal to this value receive this publication. This value must be in the range zero to 9; zero is the lowest level. However, if a publication has been retained, it is no longer available to subscribers at higher levels because it is republished at PubLevel 1.

For information, see Intercepting publications.