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:
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.
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:
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.
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:
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.
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:
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":
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:
|
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 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:
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:
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:
Both identity and origin context are set to indicate no context. This means that the context fields in MQMD are set to:
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. |
This is the default action if no context options are specified.
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.
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.
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.
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:
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.
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:
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.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
js51462 |