MQPMO (Put-message options) on IBM i

The MQPMO structure allows the application to specify options that control how messages are placed on queues or published to topics.

Overview

Purpose: The structure is an input/output parameter on the MQPUT and MQPUT1 calls.
Version: The current version of MQPMO is PMVER2. Fields that exist only in the more-recent versions of the structure are identified as such in the descriptions that follow.
The COPY file provided contains the most recent version of MQPMO that is supported by the environment, but with the initial value of the PMVER field set to PMVER1. To use fields that are not present in the version-1 structure, the application must set the PMVER field to the version number of the version required.
Character set and encoding: Data in MQPMO must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT. However, if the application is running as an IBM MQ client, the structure must be in the character set and encoding of the client.

Fields
Initial values
RPG declaration

Fields

The MQPMO structure contains the following fields; the fields are described in alphabetical order:

PMCT (10 digit signed integer)

Object handle of input queue.

If PMPASI or PMPASA 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 PMPASI and PMPASA are not specified, this field is ignored.

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

PMIDC (10 digit signed integer)

Number of messages that could not be sent.

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, and 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 which is not in a distribution list.

Note: This field is set only if the CMPCOD parameter on the MQPUT or MQPUT1 call is CCOK or CCWARN; it is not set if the CMPCOD parameter is CCFAIL.

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

PMKDC (10 digit signed integer)

Number of messages sent successfully to local queues.

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 which 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 PMVER is less than PMVER2.

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 (do not add the same constant more than once). Combinations that are not valid are noted; any other combinations are valid.

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

PMSRTO

Any information filled into the MDRQ and MDRM 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 RC2027 .

PMRET

The publication being sent is to be retained by the queue manager. This 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 SONEWP. If an application is sent a publication which was retained, it is indicated by the mq.IsRetained message property of that publication.

Only one publication can be retained at each node of the topic tree. That means 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 may 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 may be sent to the requesting application. See the description of the MQSUBRQ - Subscription request call for more details.

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

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 this option and PMNSYP are not 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 this option and PMSYP are not 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.

Use this option relieves the application of the need to reset the MDMID field to MINONE before 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 might 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 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 typically 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 are more than n physical messages in the group.

PMLOGO

Messages in groups and segments of logical messages are put in 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 PMLOGO is specified, it indicates that the application uses 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.

This order is called "logical order".

Because the application has told the queue manager how it puts messages in groups and segments of logical messages, the application does not have to maintain and update the group and segment information about 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 or current logical message, and the application can terminate them by sending a message (possibly with no application message data) specifying MFLMIG or MFLSEG as appropriate, before reissuing the MQPUT call to put the message that is not in the group or not a segment.

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

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 before the call.
Cur log msg: Indicates whether a current logical message exists before 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.
PMRLOC: Specifies that the PMRQN in the MQPMO structure must be completed with the name of the local queue which the message actually gets put to. The ResolvedQMgrName is similarly completed with the name of the local queue manager hosting the local queue. See OORLOQ 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 1. MQPUT options relating to messages in groups and segments of logical messages
Options you specify				Group and log-msg status before 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
Note: 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 responsibility of the application 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 necessary, 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 a CCWARN completion code. Table 2 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 2. 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, 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 PMLOGO. There are two reasons for this:

If the messages are retrieved and put in order, specifying PMLOGO causes a new group identifier to be assigned 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 not specifying PMLOGO and the corresponding GMLOGO on the MQGET call, the forwarding application can retrieve and forward each physical message as soon as it arrives, without needing 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 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 about message context, see Message context and Controlling context information.

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 the previous table for values). For more information about message context, see Message context and Controlling context information.

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 about message context, see Message context and Controlling context information.

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 the previous table for values). For more information about message context, see Message context and Controlling context information.

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 about message context, see Message context and Controlling context information.

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.

Put response types. The following options control the response returned to an MQPUT or MQPUT1 call . We can only specify one of these options. If PMARES and PMSRES are not specified, PMRASQ or PMRAST is assumed.

PMARES

The PMARES 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;

MDAID
MDPAT
MDPAN
MDAOD

Additionally, if either or both of PMNMID or PMNCID are specified as options, the MDMID and MDCID returned are also completed. (PMNMID can be implicitly specified by specifying a blank MDMID field).

Only the fields previously specified are completed. Other information that would normally be returned in the MQMD or MQPMO structure is undefined.

When requesting asynchronous put response for MQPUT or MQPUT1, a CMPCOD and REASON of CCOK and RCNONE does not necessarily mean that the message was successfully put to a queue. When developing an MQI application that uses asynchronous put response and require confirmation that messages have been put to a queue you should check both CMPCOD 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/MQPUT1 call might not be returned immediately, the first error that occurred under an asynchronous call can be determined at a later juncture 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 CCFAIL and a reason of RC2003 . The application can make a call to MQSTAT to determine the cause of a previous MQPUT or MQPUT1 failure

PMSRES

Specifying this value for a put option in the MQPMO structure ensures that the MQPUT or MQPUT1 operation is always issued synchronously. If the operation is successful, all fields in the MQMD and MQPMO are completed. It is provided to ensure a synchronous response irrespective of the default put response value defined on the queue or topic object.

PMRASQ

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 opened by the application. If a client application is connected to a queue manager at a level earlier than Version 7.0, it behaves as if PMSRES was specified.

If this option is specified for an MQPUT1 call, the DEFPRESP value from the queue definition is not used. If the MQPUT1 call is using PMSYP it behaves as for PMARES, and if it is using PMNSYP it behaves as for PMSRES.

PMRAST

This is a synonym for PMRASQ for use with topic objects.

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 previously are 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 is 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.

PMPRF (10 digit signed integer)

Flags indicating which MQPMR fields are present.

This field contains flags that must be set to indicate which MQPMR fields are present in the put message records provided by the application. PMPRF is used only when the message is being put to a distribution list. The field is ignored if PMREC is zero, or both PMPRO and PMPRP 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.

One or more of the following flags can be specified to indicate which fields are present in the put message records:

PFMID: Message-identifier field is present.
PFCID: Correlation-identifier field is present.
PFGID: Group-identifier field is present.
PFFB: Feedback field is present.
PFACC: Accounting-token field is present.
If this flag is specified, either PMSETI or PMSETA must be specified in the PMOPT field; if this condition is not satisfied, the call fails with reason code RC2158 .

If no MQPMR fields are present, the following can be specified:

PFNONE

No put-message record fields are present.

If this value is specified, either PMREC must be zero, or both PMPRO and PMPRP must be zero.

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

If PMPRF contains flags which are not valid, or put message records are provided but PMPRF has the value PFNONE, the call fails with reason code RC2158 .

This is an input field. The initial value of this field is PFNONE. This field is ignored if PMVER is less than PMVER2.

PMPRO (10 digit signed integer)

Offset of first put message record from start of MQPMO.

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. PMPRO is used only when the message is being put to a distribution list. The field is ignored if PMREC 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

It is not necessary to specify all of these properties, but whatever subset is chosen, the fields must be specified in the correct order. See the description of the MQPMR structure for further details.

Usually, there should 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 which 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.

It is possible for the number of put message records to differ from the number of object records. If there are fewer put message records than object records, the message properties for the destinations which 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 PMREC of them.

The put message records can be provided in a similar way to the object records in MQOD, either by specifying an offset in PMPRO, or by specifying an address in PMPRP ; for details of how to do this, see the ODORO field described in MQOD (Object descriptor) on IBM i.

No more than one of PMPRO and PMPRP can be used; the call fails with reason code RC2159 if both are nonzero.

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

PMPRP (pointer)

Address of first put message record.

This is the address of the first MQPMR put message record. PMPRP is used only when the message is being put to a distribution list. The field is ignored if PMREC is zero.

Either PMPRP or PMPRO can be used to specify the put message records, but not both; see the description of the PMRRO field for details. If PMPRP is not used, it must be set to the null pointer or null bytes.

This is an input field. The initial value of this field is the null pointer. This field is ignored if PMVER is less than PMVER2.

PMREC (10 digit signed integer)

Number of put message records or response records present.

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 PMREC records of each type.

The value of PMREC 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 PMPRO later in this topic).

If PMREC 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 RC2154 .

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

PMRMN (48 byte character string)

Resolved name of destination queue manager.

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 PMRQN, and can be the name of the local queue manager.

If PMRQN is a shared queue that is owned by the queue sharing group to which the local queue manager belongs, PMRMN is the name of the queue sharing group. If the queue is owned by some other queue sharing group, PMRQN 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 topic, the value returned is undefined.

This is an output field. The length of this field is given by LNQMN. The initial value of this field is 48 blank characters.

PMRQN (48 byte character string)

Resolved name of destination queue.

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

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

This is an output field. The length of this field is given by LNQN. The initial value of this field is 48 blank characters.

PMRRO (10 digit signed integer)

Offset of first response record from start of MQPMO.

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. PMRRO is used only when the message is being put to a distribution list. The field is ignored if PMREC is zero.

When the message is being put to a distribution list, an array of one or more MQRR response records can be provided in order to identify the queues to which the message was not sent successfully (RRCC field in MQRR), and the reason for each failure (RRREA 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 RC2136 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 should be 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 which 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.

It is possible for the number of response records to differ from the number of object records. If there are fewer response records than object records, it may not be possible for the application to identify all of 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 PMREC of them.

The response records can be provided in a similar way to the object records in MQOD, either by specifying an offset in PMRRO, or by specifying an address in PMRRP ; for details of how to do this, see the ODORO field described in MQOD (Object descriptor) on IBM i. However, no more than one of PMRRO and PMRRP can be used; the call fails with reason code RC2156 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 PMVER is less than PMVER2.

PMRRP (pointer)

Address of first response record.

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

Either PMRRP or PMRRO can be used to specify the response records, but not both; see the description of the PMRRO field for details. If PMRRP is not used, it must be set 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. This field is ignored if PMVER is less than PMVER2.

PMSID (4 byte character string)

Structure identifier.

The value must be:

PMSIDV: Identifier for put-message options structure.

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

PMSL (MQLONG)

The level of subscription targeted by this publication.

Only those subscriptions with the highest PMSL less than or equal to this value receives this publication. This value must be in the range zero to 9; zero is the lowest level.

The initial value of this field is 9.

PMTO (10 digit signed integer)

Reserved.

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

PMUDC (10 digit signed integer)

Number of messages sent successfully to remote queues.

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 which 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 PMVER is less than PMVER2.

PMVER (10 digit signed integer)

Structure version number.

The value must be one of the following:

PMVER1: Version-1 put-message options structure.
PMVER2: Version-2 put-message options structure.

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:

PMVERC: Current version of put-message options structure.

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

Initial values

Table 3. Initial values of fields in MQPMO
Field name	Name of constant	Value of constant
PMSID	PMSIDV	'PMO¬'
PMVER	PMVER1	1
PMOPT	PMNONE	0
PMTO	None	-1
PMCT	None	0
PMKDC	None	0
PMUDC	None	0
PMIDC	None	0
PMRQN	None	Blanks
PMRMN	None	Blanks
PMREC	None	0
PMPRF	PFNONE	0
PMPRO	None	0
PMRRO	None	0
PMPRP	None	Null pointer or null bytes
PMRRP	None	Null pointer or null bytes
Note: The symbol ¬ represents a single blank character.

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D* MQPMO Structure
     D*
     D* Structure identifier
     D  PMSID                  1      4    INZ('PMO ')
     D* Structure version number
     D  PMVER                  5      8I 0 INZ(1)
     D* Options that control the action of MQPUT and MQPUT1
     D  PMOPT                  9     12I 0 INZ(0)
     D* Reserved
     D  PMTO                  13     16I 0 INZ(-1)
     D* Object handle of input queue
     D  PMCT                  17     20I 0 INZ(0)
     D* Number of messages sent successfully to local queues
     D  PMKDC                 21     24I 0 INZ(0)
     D* Number of messages sent successfully to remote queues
     D  PMUDC                 25     28I 0 INZ(0)
     D* Number of messages that could notbe sent
     D  PMIDC                 29     32I 0 INZ(0)
     D* Resolved name of destination queue
     D  PMRQN                 33     80    INZ
     D* Resolved name of destination queue manager
     D  PMRMN                 81    128    INZ
     D* Number of put message records or response records present
     D  PMREC                129    132I 0 INZ(0)
     D* Flags indicating which MQPMR fields are present
     D  PMPRF                133    136I 0 INZ(0)
     D* Offset of first put message record from start of MQPMO
     D  PMPRO                137    140I 0 INZ(0)
     D* Offset of first response record from start of MQPMO
     D  PMRRO                141    144I 0 INZ(0)
     D* Address of first put message record
     D  PMPRP                145    160*   INZ(*NULL)
     D* Address of first response record
     D  PMRRP                161    176*   INZ(*NULL)
     D* Original message handle
     D  PMOMH                177    184I 0
     D* New message handle
     D  PMNMH                185    190I 0
     D* The action being performed
     D  PMACT                191    194I 0
     D* Reserved
     D  PMRE1                195    198I 0