PMOPT (10-digit signed integer)

PMOPT (10-digit signed integer)

Options that control the action of MQPUT and MQPUT1.
Any or none of the following can be specified. If more than one is required the values can be added together (do not add the same constant more than once). 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:

PMSYP

Put message with syncpoint control.
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 PMNSYP is specified, the put request is not within a unit of work.
PMSYP must not be specified with PMNSYP.

PMNSYP

Put message without syncpoint control.
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 PMSYP is specified, the put request is not within a unit of work.
PMNSYP must not be specified with PMSYP.

Message-identifier and correlation-identifier options: The following options request the queue manager to generate a new message identifier or correlation identifier:

PMNMID

Generate a new message identifier.
This option causes the queue manager to replace the contents of the MDMID 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 PRMID field in the MQPMR structure for details.
Using this option relieves the application of the need to reset the MDMID field to MINONE prior to each MQPUT or MQPUT1 call.

PMNCID

Generate a new correlation identifier.
This option causes the queue manager to replace the contents of the MDCID 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 PRCID field in the MQPMR structure for details.
PMNCID is useful in situations where the application requires a unique correlation identifier.

Group and segment options: The following option relates to the processing of messages in groups and segments of logical messages. These definitions may be of help in understanding 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 (MDMID 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 would be the same as a physical message. But where logical messages are extremely large, system constraints may 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 (MDGID field in MQMD), and the same message sequence number (MDSEQ field in MQMD). The segments are distinguished by differing values for the segment offset (MDOFF 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 (GINONE), 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 will be more than n physical messages in the group.

PMLOGO

Messages in groups and segments of logical messages will be put in logical order.
This option tells the queue manager how the application will put 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 PMLOGO 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 of 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 of 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, as the queue manager does this. Specifically, it means that the application does not need to set the MDGID, MDSEQ, and MDOFF fields in MQMD, as the queue manager sets these to the appropriate values. The application need set only the MDMFL 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 MF* flags in MDMFL in MQMD. If the application tries to put a message not in a group when there is an unterminated message group, or put a message which is not a segment when there is an unterminated logical message, the call fails with reason code RC2241 or RC2242, as appropriate. However, the queue manager retains the information about the current message group and/or current logical message, and the application can terminate them by sending a message (possibly with no application message data) specifying MFLMIG and/or MFLSEG as appropriate, before reissuing the MQPUT call to put the message that is not in the group or not a segment.
Table 31 shows the combinations of options and flags that are valid, and the values of the MDGID, MDSEQ, and MDOFF 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

Indicates whether the PMLOGO option is specified on the call.

MIG

Indicates whether the MFMIG or MFLMIG option is specified on the call.

SEG

Indicates whether the MFSEG or MFLSEG option is specified on the call.

SEG OK

Indicates whether the MFSEGA option is specified on the call.

Cur grp

Indicates whether a current message group exists prior to the call.

Cur log msg

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

MQPMO_RESOLVE_LOCAL_QUEUE

Specifies that the ResolvedQName in the MQPMO structure should be filled in with the name of the local queue which the message actually gets put to. The ResolvedQMgrName will similarly be filled in with the name of the local queue manager hosting the local queue. See MQOO_RESOLVE_LOCAL_QUEUE for what this means. If a user is authorized for a put to a queue then they have the required authority to specify this flag on the MQPUT call. No special authority is needed.

Table 31. 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 MDGID MDSEQ MDOFF
Yes No No No No No GINONE 1 0
Yes No No Yes No No New group id 1 0
Yes No Yes Yes or No No No New group id 1 0
Yes No Yes Yes or No No Yes Previous group id 1 Previous offset + previous segment length
Yes Yes Yes or No Yes or No No No New group id 1 0
Yes Yes Yes or No Yes or No Yes No Previous group id Previous sequence number + 1 0
Yes Yes Yes Yes or No Yes Yes Previous group id Previous sequence number Previous offset + previous segment length
No No No No Yes or No Yes or No GINONE 1 0
No No No Yes Yes or No Yes or No New group id if GINONE, else value in field 1 0
No No Yes Yes or No Yes or No Yes or No New group id if GINONE, else value in field 1 Value in field
No Yes No Yes or No Yes or No Yes or No New group id if GINONE, else value in field Value in field 0
No Yes Yes Yes or No Yes or No Yes or No New group id if GINONE, else value in field Value in field Value in field

Notes:

PMLOGO is not valid on the MQPUT1 call.
For the MDMID field, the queue manager generates a new message identifier if PMNMID or MINONE is specified, and uses the value in the field otherwise.
For the MDCID field, the queue manager generates a new correlation identifier if PMNCID is specified, and uses the value in the field otherwise.

When PMLOGO is specified, the queue manager requires that all messages in a group and segments in a logical message be put with the same value in the MDPER 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 RC2185.
The PMLOGO 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 of 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 consisting 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 RC2245.
When PMLOGO is specified, the MQMD supplied on the MQPUT call must not be less than MDVER2. If this condition is not satisfied, the call fails with reason code RC2257.
If PMLOGO 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 MDGID, MDSEQ, MDOFF, and MDMFL fields have appropriate values.
This is the technique that can be used 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 MDGID, MDSEQ, MDOFF, MDMFL, and MDPER fields to the appropriate values, and then issue the MQPUT call with PMSYP or PMNSYP set as desired, but without specifying PMLOGO. If this call is successful, the queue manager retains the group and segment information, and subsequent MQPUT calls using that queue handle can specify PMLOGO 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 is free to mix MQPUT calls that specify PMLOGO with MQPUT calls that do not, but the following points should be noted:

If PMLOGO 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 PMLOGO is not specified, the call does not fail if there is a current message group or logical message; the call might however succeed with an CCWARN completion code. Table 32 shows the various cases that can arise. In these cases, if the completion code is not CCOK, the reason code is one of the following (as appropriate):

RC2241
RC2242
RC2185
RC2245

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

Table 32. Outcome when MQPUT or MQCLOSE call is not consistent with group and segment information

Current call is Previous call was MQPUT with PMLOGO Previous call was MQPUT without PMLOGO

MQPUT with PMLOGO CCFAIL CCFAIL
MQPUT without PMLOGO CCWARN CCOK
MQCLOSE with an unterminated group or logical message CCWARN CCOK

Applications that simply want to put messages and segments in logical order are recommended to specify PMLOGO, 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 may need more control than provided by the PMLOGO option, and this can be achieved by not specifying that option. If this is done, the application must ensure that the MDGID, MDSEQ, MDOFF, and MDMFL fields in MQMD are set correctly, prior to 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, should not specify PMLOGO. There are two reasons for this:

If the messages are retrieved and put in order, specifying PMLOGO will cause a new group identifier to be assigned to the messages, and this may 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 may arrive out of order. By specifying neither PMLOGO, nor the corresponding GMLOGO 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 should also not specify PMLOGO when putting the report message.
PMLOGO can be specified with any of the other PM* options.

Context options: The following options control the processing of message context:

PMNOC

No context is to be associated with the message.
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

PMDEFC

Use 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

MDUID Determined from the environment if possible; set to blanks otherwise.
MDACC Determined from the environment if possible; set to ACNONE otherwise.
MDAID Set to blanks.
MDPAT Determined from the environment.
MDPAN Determined from the environment if possible; set to blanks otherwise.
MDPD Set to date when message is put.
MDPT Set to time when message is put.
MDAOD 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.

PMPASI

Pass identity context from an input queue handle.
The message is to have context information associated with it. Identity context is taken from the queue handle specified in the PMCT field. Origin context information is generated by the queue manager in the same way that it is for PMDEFC (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 OOPASI 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 OOPASI option.

PMPASA

Pass all context from an input queue handle.
The message is to have context information associated with it. Both identity and origin context are taken from the queue handle specified in the PMCT 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 OOPASA 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 OOPASA option.

PMSETI

Set identity context from the application.
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 PMDEFC (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 OOSETI 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 OOSETI option.

PMSETA

Set all context from the application.
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 OOSETA option. For the MQPUT1 call, the same authorization check is carried out as for the MQOPEN call with the OOSETA option.

Only one of the PM* context options can be specified. If none of these options is specified, PMDEFC is assumed.
Other options: The following options control authorization checking, and what happens when the queue manager is quiescing:

PMALTU

Validate with specified user identifier.
This indicates that the ODAU field in the OBJDSC 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 ODAU 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.

PMFIQ

Fail if queue manager is quiescing.
This option forces the MQPUT or MQPUT1 call to fail if the queue manager is in the quiescing state.
The call returns completion code CCFAIL with reason code RC2161.

Default option: If none of the options described above is required, the following option can be used:

PMNONE

No options specified.
This value can be used to indicate that no other options have been specified; all options assume their default values. PMNONE 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 PMOPT field is PMNONE.

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	MDGID	MDSEQ	MDOFF
Yes	No	No	No	No	No	GINONE	1	0
Yes	No	No	Yes	No	No	New group id	1	0
Yes	No	Yes	Yes or No	No	No	New group id	1	0
Yes	No	Yes	Yes or No	No	Yes	Previous group id	1	Previous offset + previous segment length
Yes	Yes	Yes or No	Yes or No	No	No	New group id	1	0
Yes	Yes	Yes or No	Yes or No	Yes	No	Previous group id	Previous sequence number + 1	0
Yes	Yes	Yes	Yes or No	Yes	Yes	Previous group id	Previous sequence number	Previous offset + previous segment length
No	No	No	No	Yes or No	Yes or No	GINONE	1	0
No	No	No	Yes	Yes or No	Yes or No	New group id if GINONE, else value in field	1	0
No	No	Yes	Yes or No	Yes or No	Yes or No	New group id if GINONE, else value in field	1	Value in field
No	Yes	No	Yes or No	Yes or No	Yes or No	New group id if GINONE, else value in field	Value in field	0
No	Yes	Yes	Yes or No	Yes or No	Yes or No	New group id if GINONE, else value in field	Value in field	Value in field
Notes: PMLOGO is not valid on the MQPUT1 call. For the MDMID field, the queue manager generates a new message identifier if PMNMID or MINONE is specified, and uses the value in the field otherwise. For the MDCID field, the queue manager generates a new correlation identifier if PMNCID is specified, and uses the value in the field otherwise.

Current call is	Previous call was MQPUT with PMLOGO	Previous call was MQPUT without PMLOGO
MQPUT with PMLOGO	CCFAIL	CCFAIL
MQPUT without PMLOGO	CCWARN	CCOK
MQCLOSE with an unterminated group or logical message	CCWARN	CCOK

Field in MQMD	Value used
MDUID	Determined from the environment if possible; set to blanks otherwise.
MDACC	Determined from the environment if possible; set to ACNONE otherwise.
MDAID	Set to blanks.
MDPAT	Determined from the environment.
MDPAN	Determined from the environment if possible; set to blanks otherwise.
MDPD	Set to date when message is put.
MDPT	Set to time when message is put.
MDAOD	Set to blanks.