Any or none of the following can be specified. If more than one is required the values can be:
Combinations that are not valid are noted; any other combinations are valid.
Syncpoint options: The following options relate to the participation of the MQPUT or MQPUT1 call within a unit of work:
If neither this option nor MQPMO_NO_SYNCPOINT is specified, the inclusion of the put request in unit-of-work protocols is determined by the environment:
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.
If neither this option nor MQPMO_SYNCPOINT is specified, the inclusion of the put request in unit-of-work protocols is determined by the environment:
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:
This 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 prior to each MQPUT or MQPUT1 call.
This option is supported on all WebSphere MQ V6.0 systems.
This 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.
This option is supported on all WebSphere MQ V6.0 systems.
Group and segment options: The following option relates to the processing of messages in groups and segments of logical messages. Read the definitions that follow to help you to understand the option:
A logical message that has been segmented consists of two or more physical messages that have the same nonnull 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 nonnull 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.
If MQPMO_LOGICAL_ORDER is specified, it indicates that the application will use successive MQPUT calls to:
The above order is called logical order.
Because the application has told the queue manager how it will put messages in groups and segments of logical messages, the application does not have to maintain and update the group and segment information on each MQPUT call, because the queue manager does this. Specifically, it means that the application does not need to set the GroupId, MsgSeqNumber, and Offset fields in MQMD, becauses the queue manager sets these to the appropriate values. The application needs to set only the MsgFlags field in MQMD, to indicate when messages belong to groups or are segments of logical messages, and to indicate the last message in a group or last segment of a logical message.
Once a message group or logical message has been started, subsequent MQPUT calls must specify the appropriate MQMF_* flags in MsgFlags in MQMD. If the application tries to put a message that is not in a group when there is an unterminated message group, or put a message that is not a segment when there is an unterminated logical message, the call fails with reason code MQRC_INCOMPLETE_GROUP or MQRC_INCOMPLETE_MSG, as appropriate. However, the queue manager retains the information about the current message group or current logical message, and the application can terminate them by sending a message (possibly with no application message data) specifying MQMF_LAST_MSG_IN_GROUP or MQMF_LAST_SEGMENT as appropriate, before reissuing the MQPUT call to put the message that is not in the group or not a segment.
Table 53 shows the combinations of options and flags that are valid, and the values of the GroupId, MsgSeqNumber, and Offset fields that the queue manager uses in each case. Combinations of options and flags that are not shown in the table are not valid. The columns in the table have the following meanings; Either means Yes or No:
Options you specify | Group and log-msg status prior to call | Values the queue manager uses | ||||||
---|---|---|---|---|---|---|---|---|
LOG ORD | MIG | SEG | SEG OK | Cur grp | Cur log msg | GroupId | MsgSeqNumber | Offset |
Yes | No | No | No | No | No | MQGI_NONE | 1 | 0 |
Yes | No | No | Yes | No | No | New group id | 1 | 0 |
Yes | No | Yes | Either | No | No | New group id | 1 | 0 |
Yes | No | Yes | Either | No | Yes | Previous group id | 1 | Previous offset + previous segment length |
Yes | Yes | Either | Either | No | No | New group id | 1 | 0 |
Yes | Yes | Either | Either | Yes | No | Previous group id | Previous sequence number + 1 | 0 |
Yes | Yes | Yes | Either | Yes | Yes | Previous group id | Previous sequence number | Previous offset + previous segment length |
No | No | No | No | Either | Either | MQGI_NONE | 1 | 0 |
No | No | No | Yes | Either | Either | New group id if MQGI_NONE, else value in field | 1 | 0 |
No | No | Yes | Either | Either | Either | New group id if MQGI_NONE, else value in field | 1 | Value in field |
No | Yes | No | Either | Either | Either | New group id if MQGI_NONE, else value in field | Value in field | 0 |
No | Yes | Yes | Either | Either | Either | New group id if MQGI_NONE, else value in field | Value in field | Value in field |
Notes:
|
When you specify MQPMO_LOGICAL_ORDER, the queue manager requires that all messages in a group and segments in a logical message are put with the same value in the Persistence field in MQMD, that is, all must be persistent, or all must be nonpersistent. If this condition is not satisfied, the MQPUT call fails with reason code MQRC_INCONSISTENT_PERSISTENCE.
The MQPMO_LOGICAL_ORDER option affects units of work as follows:
If these conditions are not satisfied, the MQPUT call fails with reason code MQRC_INCONSISTENT_UOW.
When MQPMO_LOGICAL_ORDER is specified, the MQMD supplied on the MQPUT call must not be less than MQMD_VERSION_2. If this condition is not satisfied, the call fails with reason code MQRC_WRONG_MD_VERSION.
If MQPMO_LOGICAL_ORDER is not specified, messages in groups and segments of logical messages can be put in any order, and it is not necessary to put complete message groups or complete logical messages. It is the application's responsibility to ensure that the GroupId, MsgSeqNumber, Offset, and MsgFlags fields have appropriate values.
Use this technique to restart a message group or logical message in the middle, after a system failure has occurred. When the system restarts, the application can set the GroupId, MsgSeqNumber, Offset, MsgFlags, and Persistence fields to the appropriate values, and then issue the MQPUT call with MQPMO_SYNCPOINT or MQPMO_NO_SYNCPOINT set as desired, but without specifying MQPMO_LOGICAL_ORDER. If this call is successful, the queue manager retains the group and segment information, and subsequent MQPUT calls using that queue handle can specify MQPMO_LOGICAL_ORDER as normal.
The group and segment information that the queue manager retains for the MQPUT call is separate from the group and segment information that it retains for the MQGET call.
For any given queue handle, the application can mix MQPUT calls that specify MQPMO_LOGICAL_ORDER with MQPUT calls that do not, but note the following points:
Current call is | Previous call was MQPUT with MQPMO_LOGICAL_ORDER | Previous call was MQPUT without MQPMO_LOGICAL_ORDER |
---|---|---|
MQPUT with MQPMO_LOGICAL_ORDER | MQCC_FAILED | MQCC_FAILED |
MQPUT without MQPMO_LOGICAL_ORDER | MQCC_WARNING | MQCC_OK |
MQCLOSE with an unterminated group or logical message | MQCC_WARNING | MQCC_OK |
For applications that put messages and segments in logical order, specify MQPMO_LOGICAL_ORDER, as this is the simplest option to use. This option relieves the application of the need to manage the group and segment information, because the queue manager manages that information. However, specialized applications might need more control than that provided by the MQPMO_LOGICAL_ORDER option, and this can be achieved by not specifying that option. If this is done, the application must ensure that the GroupId, MsgSeqNumber, Offset, and MsgFlags fields in MQMD are set correctly, before each MQPUT or MQPUT1 call.
For example, an application that wants to forward physical messages that it receives, without regard for whether those messages are in groups or segments of logical messages, must not specify MQPMO_LOGICAL_ORDER. There are two reasons for this:
Applications that generate report messages for messages in groups or segments of logical messages must also not specify MQPMO_LOGICAL_ORDER when putting the report message.
MQPMO_LOGICAL_ORDER can be specified with any of the other MQPMO_* options.
Context options: The following options control the processing of message context:
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. |
This is the default action if no context options are specified.
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.
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.
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.
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.
Other options: The following options control authorization checking, what happens when the queue manager is quiescing, and resolving queue and queue manager names:
This option is valid only with the MQPUT1 call.
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.
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:
This is an input field. The initial value of the Options field is MQPMO_NONE.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
js01791 |