Home

 

Options (MQLONG)

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:

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 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:

  • 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 neither this option nor MQPMO_SYNCPOINT is specified, the inclusion of the put request in unit-of-work protocols is determined by the environment:

  • 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.

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.

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.

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:

Physical message

This 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

This is a single unit of application information. 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 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.

Message group

This is a set of one or more logical messages that have the same nonnull 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 will use successive MQPUT calls to:

  • Put the segments in each logical message in the order of increasing segment offset, starting from 0, with no gaps.

  • Put all the segments in one logical message before putting the segments in the next logical message.

  • Put the logical messages in each message group in the order of increasing message sequence number, starting from 1, with no gaps.

  • Put all the logical messages in one message group before putting logical messages in the next message group.

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:

LOG ORD

Whether the MQPMO_LOGICAL_ORDER option is specified on the call.

MIG

Whether the MQMF_MSG_IN_GROUP or MQMF_LAST_MSG_IN_GROUP option is specified on the call.

SEG

Whether the MQMF_SEGMENT or MQMF_LAST_SEGMENT option is specified on the call.

SEG OK

Whether the MQMF_SEGMENTATION_ALLOWED option is specified on the call.

Cur grp

Whether a current message group exists prior to the call.

Cur log msg

Whether a current logical message exists prior to the call.

Other columns

Show the values that the queue manager uses. Previous denotes the value used for the field in the previous message for the queue handle.
Table 53. MQPUT options relating to messages in groups and segments of logical messages
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:

  • MQPMO_LOGICAL_ORDER is not valid on the MQPUT1 call.

  • For the MsgId field, the queue manager generates a new message identifier if MQPMO_NEW_MSG_ID or MQMI_NONE is specified, and uses the value in the field otherwise.

  • For the CorrelId field, the queue manager generates a new correlation identifier if MQPMO_NEW_CORREL_ID is specified, and uses the value in the field otherwise.

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 the first physical message in a group or logical message is put within a unit of work, all the other physical messages in the group or logical message must be put within a unit of work, if the same queue handle is used. However, they need not be put within the same unit of work. This allows a message group or logical message that consists of many physical messages to be split across two or more consecutive units of work for the queue handle.

  • If the first physical message in a group or logical message is not put within a unit of work, none of the other physical messages in the group or logical message can be put within a unit of work, if the same queue handle is used.

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:

  • If MQPMO_LOGICAL_ORDER is not specified, each successful MQPUT call causes the queue manager to set the group and segment information for the queue handle to the values specified by the application; this replaces the existing group and segment information retained by the queue manager for the queue handle.

  • If MQPMO_LOGICAL_ORDER is not specified, the call does not fail if there is a current message group or logical message; the call might succeed with an MQCC_WARNING completion code. Table 54 shows the various cases that can arise. In these cases, if the completion code is not MQCC_OK, the reason code is one of the following (as appropriate):

    • MQRC_INCOMPLETE_GROUP

    • MQRC_INCOMPLETE_MSG

    • MQRC_INCONSISTENT_PERSISTENCE

    • MQRC_INCONSISTENT_UOW

    Note:
    The queue manager does not check the group and segment information for the MQPUT1 call.

Table 54. Outcome when MQPUT or MQCLOSE call is not consistent with group and segment information
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:

  • If the messages are retrieved and put in order, specifying MQPMO_LOGICAL_ORDER assigns a new group identifier to the messages, and this might make it difficult or impossible for the originator of the messages to correlate any reply or report messages that result from the message group.

  • In a complex network with multiple paths between sending and receiving queue managers, the physical messages might arrive out of order. By specifying neither MQPMO_LOGICAL_ORDER nor the corresponding MQGMO_LOGICAL_ORDER on the MQGET call, the forwarding application can retrieve and forward each physical message as soon as it arrives, without having to wait for the next one in logical order to arrive.

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:

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:
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 on message context, see the WebSphere MQ Application Programming Guide.

This is the default action 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 above for values). For more information on message context, see the WebSphere MQ Application Programming Guide.

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. Both identity and origin context are taken from the queue handle specified in the Context field. For more information on message context, see the WebSphere MQ Application Programming Guide.

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 above for values). For more information on message context, see the WebSphere MQ Application Programming Guide.

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 and origin context in the MQMD structure. For more information on message context, see the WebSphere MQ Application Programming Guide.

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.

We 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:

MQPMO_ALTERNATE_USER_AUTHORITY

This 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 this 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 detail on this, see 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 we 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.

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




 

Home