Specifying options using the MQPMO structure

Use the MQPMO (Put Message Option) structure to pass options to the MQPUT and MQPUT1 calls.

The following sections give you help on filling in the fields of this structure. There is a description of the structure in the WebSphere MQ Application Programming Reference.

The fields of the structure include:

These fields are described below.

StrucId
This identifies the structure as a put-message options structure. This is a 4-character field. Always specify MQPMO_STRUC_ID.
Version
This describes the version number of the structure. The default is MQPMO_VERSION_1. If you enter MQPMO_VERSION_2, you can use distribution lists (see Distribution lists). If you enter MQPMO_CURRENT_VERSION, your application is set always to use the most recent level.
Options
This controls the following:

If you leave the Options field set to the default value (MQPMO_NONE), the message you put has default context information associated with it.

Also, the way that the call operates with syncpoints is determined by the platform. The syncpoint control default is yes in z/OS; for other platforms, it is no.

Context
This states the name of the queue handle that you want context information to be copied from (if requested in the Options field).

For an introduction to message context, see Message context. For information about using the MQPMO structure to control the context information in a message, see Controlling context information.

ResolvedQName
This contains the name (after resolution of any alias name) of the queue that was opened to receive the message. This is an output field.
ResolvedQMgrName
This contains the name (after resolution of any alias name) of the queue manager that owns the queue in ResolvedQName. This is an output field.

The MQPMO can also accommodate fields required for distribution lists (see Distribution lists). If you want to use this facility, Version 2 of the MQPMO structure is used. This includes the following fields:

Version
This field describes the version number of the structure. For distribution lists, you must specify MQPMO_VERSION_2.
RecsPresent
This field contains the number of queues in the distribution list; that is, the number of Put Message Records (MQPMR) and corresponding Response Records (MQRR) present.

The value that you enter can be the same as the number of Object Records provided at MQOPEN. However, if the value is less than the number of Object Records provided on the MQOPEN call, or if you provide no Put Message Records, the values of the queues that are not defined are taken from the default values provided by the message descriptor. Also, if the value is greater than the number of Object Records provided, the excess Put Message Records are ignored.

You are recommended to do one of the following:

Note:
If you are using MQPUT1, the number of Response Record Pointers and Response Record Offsets must be zero.

For a full description of Put Message Records (MQPMR) and Response Records (MQRR), see the WebSphere MQ Application Programming Reference.

PutMsgRecFields
This indicates which fields are present in each Put Message Record (MQPMR). For a list of these fields, see Using the MQPMR structure.
PutMsgRecOffset and PutMsgRecPtr
Pointers (typically in C) and offsets (typically in COBOL) are used to address the Put Message Records (see Using the MQPMR structure for an overview of the MQPMR structure).

Use the PutMsgRecPtr field to specify a pointer to the first Put Message Record, or the PutMsgRecOffset field to specify the offset of the first Put Message Record. This is the offset from the start of the MQPMO. Depending on the PutMsgRecFields field, enter a nonnull value for either PutMsgRecOffset or PutMsgRecPtr.

ResponseRecOffset and ResponseRecPtr
You also use pointers and offsets to address the Response Records (see Using the MQRR structure for further information about Response Records).

Use the ResponseRecPtr field to specify a pointer to the first Response Record, or the ResponseRecOffset field to specify the offset of the first Response Record. This is the offset from the start of the MQPMO structure. Enter a nonnull value for either ResponseRecOffset or ResponseRecPtr.

Note:
If you are using MQPUT1 to put messages to a distribution list, ResponseRecPtr must be null or zero and ResponseRecOffset must be zero.

Additional information for putting to a distribution list (see Distribution lists) is provided in Version 2 of the Put Message Option structure (MQPMR). This is described in the WebSphere MQ Application Programming Reference.