Action (MQLONG)

This specifies the type of put being performed and the relationship between the original message specified by the OriginalMsgHandle field and the new message specified by the NewMsgHandle field. The properties of the message are chosen by the queue manager according to the value of the Action specified.

You can choose to supply the contents of the message descriptor using the MsgDesc parameter on the MQPUT or MQPUT1 calls. Alternatively it is possible not to supply the MsgDesc parameter, or to specify that it is output-only by including MQPMO_MD_FOR_OUTPUT_ONLY in the Options field of the MQPMO structure.

If the MsgDesc parameter is not supplied, or if it is specified to be output-only, then the message descriptor for the new message is populated from the message handle fields of the MQPMO, according to the rules described in this topic.

The context setting and passing activities described in Controlling context information take effect after the message descriptor has been composed.

If an incorrect action value is specified, the call fails with the reason code MQRC_ACTION_ERROR.

Any one of the following actions can be specified:
MQACTP_NEW
A new message is being put, and no relationship to a previous message is being specified by the program. The message descriptor is composed as follows:
  • If a MsgDesc is supplied on the MQPUT or MQPUT1 call, and MQPMO_MD_FOR_OUTPUT_ONLY is not in the MQPMO.Options, this is used as the message descriptor unmodified.
  • If a MsgDesc is not supplied, or MQPMO_MD_FOR_OUTPUT_ONLY is in the MQPMO.Options then the queue manager generates the message descriptor using a combination of properties from OriginalMsgHandle and NewMsgHandle. Any message descriptor fields explicitly set on the new message handle take precedence over those in the original message handle.
Message data is taken from the MQPUT or MQPUT1 Buffer parameter.
MQACTP_FORWARD
A previously retrieved message is being forwarded. The original message handle specifies the message that was previously retrieved.

The new message handle specifies any modifications to the properties (including any in the message descriptor) in the original message handle.

The message descriptor is composed as follows:
  • If a MsgDesc is supplied on the MQPUT or MQPUT1 call, and MQPMO_MD_FOR_OUTPUT_ONLY is not in the MQPMO.Options, this is used as the message descriptor unmodified.
  • If a MsgDesc is not supplied, or MQPMO_MD_FOR_OUTPUT_ONLY is in the MQPMO.Options then the queue manager generates the message descriptor using a combination of properties from OriginalMsgHandle and NewMsgHandle. Any message descriptor fields explicitly set on the new message handle take precedence over those in the original message handle.
  • If MQPMO_NEW_MSG_ID or MQPMO_NEW_CORREL_ID are specified in the MQPMO.Options, then these are honoured.
The message properties are composed as follows:
  • All properties from the original message handle which have MQCOPY_FORWARD in the MQPD.CopyOptions
  • All properties from the new message handle. For each property in the new message handle that has the same name as a property in the original message handle, the value is taken from the new message handle. The only exception to this rule is the special case when the property in the new message handle has the same name as a property in the original message handle, but the value of the property is null. In this case the property is removed from the message.

The message data to be forwarded is taken from the MQPUT or MQPUT1 Buffer parameter.

MQACTP_REPLY
A reply is being made to a previously retrieved message. The original message handle specifies the message that was previously retrieved.

The new message handle specifies any modifications to the properties (including any in the message descriptor) in the original message handle.

The message descriptor is composed as follows:
  • If a MsgDesc is supplied on the MQPUT or MQPUT1 call, and MQPMO_MD_FOR_OUTPUT_ONLY is not in the MQPMO.Options, this is used as the message descriptor unmodified.
  • If a MsgDesc is not supplied, or MQPMO_MD_FOR_OUTPUT_ONLY is in the MQPMO.Options, then initial message descriptor fields are chosen as follows:
    Table 1. Reply message handle transformation
    Field in MQMD Value used
    Report
    If MQRO_PASS_DISCARD_AND_EXPIRY
    and MQRO_DISCARD_MSG are set:
    MQRO_DISCARD_MSG
    otherwise
    MQRO_NONE
    MsgType MQMT_REPLY
    Expiry
    If MQRO_PASS_DISCARD_AND_EXPIRY
    is set:
    Copied from the input message
    otherwise
    MQEI_UNLIMITED
    Feedback MQFB_NONE
    MsgId
    If MQPMO_NEW_MSG_ID is set:
    A new message identifier is generated
    else if MQRO_PASS_MSG_ID is set:
    Copied from the input message
    otherwise
    MQMI_NONE
    CorrelId
    If MQPMO_NEW_CORREL_ID is set:
    A new correlation identifier is generated
    else if MQRO_COPY_MSG_ID_TO_CORREL_ID is set:
    Copied from the MsgId field of the
    input message
    else if MQRO_PASS_CORREL_ID is set:
    Copied from the CorrelId field of the
    input message
    otherwise
    MQCI_NONE
    BackoutCount 0
    ReplyToQ Blanks
    ReplyToQMgr Blanks
    GroupId MQGI_NONE
    MsgSeqNumber 1
    Offset 0
    MsgFlags MQMF_NONE
    OriginalLength MQOL_UNDEFINED
  • The message descriptor is then modified by the new message handle - any message descriptor fields explicitly set as properties in the new message handle take precedence over the message descriptor fields as described previously.
The message properties are composed as follows:
  • All properties from the original message handle which have MQCOPY_REPLY in the MQPD.CopyOptions
  • All properties from the new message handle. For each property in the new message handle that has the same name as a property in the original message handle, the value is taken from the new message handle. The only exception to this rule is the special case when the property in the new message handle has the same name as a property in the original message handle, but the value of the property is null. In this case the property is removed from the message.
The message data to be forwarded is taken from the MQPUT/MQPUT1 Buffer parameter.
MQACTP_REPORT
A report is being generated as a result of a previously retrieved message. The original message handle specifies the message causing the report to be generated.

The new message handle specifies any modifications to the properties (including any in the message descriptor) in the original message handle.

The message descriptor is composed as follows:
  • If a MsgDesc is supplied on the MQPUT or MQPUT1 call, and MQPMO_MD_FOR_OUTPUT_ONLY is not in the MQPMO.Options, this is used as the message descriptor unmodified.
  • If a MsgDesc is not supplied, or MQPMO_MD_FOR_OUTPUT_ONLY is in the MQPMO.Options then initial message descriptor fields are chosen as follows:
    Table 2. Report message handle transformation
    Field in MQMD Value used
    Report
    If MQRO_PASS_DISCARD_AND_EXPIRY and
    MQRO_DISCARD_MSG are set:
    MQRO_DISCARD_MSG
    otherwise
    MQRO_NONE
    MsgType MQMT_REPORT
    Expiry
    If MQRO_PASS_DISCARD_AND_EXPIRY
    is set:
    Copied from the input message
    otherwise
    MQEI_UNLIMITED
    MsgId
    If MQPMO_NEW_MSG_ID is set:
    A new message identifier is generated
    else if MQRO_PASS_MSG_ID is set:
    Copied from the input message
    otherwise
    MQMI_NONE
    CorrelId
    If MQPMO_NEW_CORREL_ID is set:
    A new correlation identifier is generated
    else if MQRO_COPY_MSG_ID_TO_CORREL_ID is set:
    Copied from the MsgId field of the
    input message
    else if MQRO_PASS_CORREL_ID is set:
    Copied from the CorrelId field of the
    input message
    otherwise
    MQCI_NONE
    BackoutCount 0
    ReplyToQ Blanks
    ReplyToQMgr Blanks
    OriginalLength Set to the BufferLength
  • The message descriptor is then modified by the new message handle - any message descriptor fields explicitly set as properties in the new message handle take precedence over the message descriptor fields as described previously.
The message properties are composed as follows:
  • All properties from the original message handle which have MQCOPY_REPORT in the MQPD.CopyOptions
  • All properties from the new message handle. For each property in the new message handle that has the same name as a property in the original message handle, the value is taken from the new message handle. The only exception to this rule is the special case when the property in the new message handle has the same name as a property in the original message handle, but the value of the property is null. In this case the property is removed from the message.

The Feedback field in the resultant MQMD represents the report that is to be generated. A Feedback value of MQFB_NONE causes the MQPUT or MQPUT1 call to fail with reason code MQRC_FEEDBACK_ERROR.

To choose the user data of the report message, IBM® MQ consults the Report and Feedback fields in the resultant MQMD, and the Buffer and BufferLength parameters of the MQPUT or MQPUT1 call.
  • If Feedback is MQFB_COA, MQFB_COD or MQFB_EXPIRATION then the value of Report is inspected.
  • If any of the following cases is true, the full message data from Buffer for a length of BufferLength is used.
    • Feedback is MQFB_EXPIRATION and Report contains MQRO_EXPIRATION_WITH_FULL_DATA
    • Feedback is MQFB_COD and Report contains MQRO_COD_WITH_FULL_DATA
    • Feedback is MQFB_COA and Report contains MQRO_COA_WITH_FULL_DATA
  • If any of the following cases is true, the first 100 bytes of the message (or BufferLength if this is less than 100) from Buffer are used
    • Feedback is MQFB_EXPIRATION and Report contains MQRO_EXPIRATION_WITH_DATA
    • Feedback is MQFB_COD and Report contains MQRO_COD_WITH_DATA
    • Feedback is MQFB_COA and Report contains MQRO_COA_WITH_DATA
  • If Feedback is MQFB_EXPIRATION, MQFB_COD or MQFB_COA, and Report does not contain the *_WITH_FULL_DATA or *_WITH_DATA options relevant to that Feeback value, then no user data is included with the message.
  • If Feedback takes a different value from those listed above, then Buffer and BufferLength are used as normal.
The derivation of the user data described in the previous list is also shown in the following table:
Table 3. Source of user data
  MQFB_COA MQFB_COD MQFB_EXPIRATION
MQRO_EXPIRATION _WITH_FULL_DATA None None Buffer(Bufferlength)
MQRO_COD_WITH _FULL_DATA None Buffer(Bufferlength) None
MQRO_COA_WITH _FULL_DATA Buffer(Bufferlength) None None
MQRO_EXPIRATION _WITH_DATA None None Buffer(First 100 bytes)
MQRO_COD_WITH_DATA None Buffer(First 100 bytes) None
MQRO_COA_WITH_DATA Buffer(First 100 bytes) None None