Broker Response message

A Broker Response message is sent from a broker to the ReplyToQ of a publisher or a subscriber, to indicate the success or failure of a command message received by the broker if the command message descriptor specified that a response is required.

The response message is contained within the NameValueData field of the MQRFH2 header, in a <pscr> folder.

In the case of a warning or error, the response message contains the <psc> folder from the command message as well as the <pscr> folder. The message data, if any, is not contained in the broker response message. In the case of an error, none of the message that caused an error has been processed; in the case of a warning, some of the message might have been processed successfully.

If there is a failure sending a response:
  • For publication messages, the broker tries to send the response to the WebSphere MQ dead-letter queue if the MQPUT fails. This allows the publication to be sent to subscribers even if the response cannot be sent back to the publisher.
  • For other messages, or if the publication response cannot be sent to the dead-letter queue, an error is logged and the command message is normally rolled back. Whether this happens depends on how the MQInput node has been configured.

Properties

<Completion> (MQPSCR_COMPLETION)
The completion code, which can take one of three values:
ok
Command completed successfully
warning
Command completed but with warning
error
Command failed
<Response> (MQPSCR_RESPONSE)
The response to a command message, if that command produced a completion code of warning or error. It contains a <Reason> property, and might contain other properties that indicate the cause of the warning or error.

In the case of one or more errors, there is only one response folder, indicating the cause of the first error only. In the case of one or more warnings, there is a response folder for each warning.

<Reason> (MQPSCR_REASON)
The reason code qualifying the completion code, if the completion code is a warning or error. It is set to one of the error codes listed below. The <Reason> property is contained within a <Response> folder. The reason code can be followed by any valid property from the <psc> folder (for example, a topic name), indicating the cause of the error or warning.

Examples

Here are some examples of NameValueData in a Broker Response message. A successful response might be the following:
 <pscr>
   <Completion>ok</Completion>
 </pscr>
Here is an example of a failure response; the failure is a filter error. The first NameValueData string contains the response; the second contains the original command.
 <pscr>
   <Completion>error</Completion>
   <Response>
     <Reason>3150</Reason>
   </Reponse>
 </pscr>
 
 <psc>
  ...
  command message (to which
  the broker is responding)
  ...
 </psc>
Here is an example of a warning response (due to unauthorized topics). The first NameValueData string contains the response; the second NameValueData string contains the original command.
 <pscr>
   <Completion>warning</Completion>
   <Response>
     <Reason>3081</Reason>
     <Topic>topic1</Topic>
   </Reponse>
   <Response>
     <Reason>3081</Reason>
     <Topic>topic2</Topic>
   </Reponse>
 </pscr>
 
 <psc>
  ...
  command message (to which
  the broker is responding)
  ...
 </psc>

Reason codes

The following reason codes might be returned in the Reason field of a publish/subscribe response <pscr> folder. Constants that can be used to represent these codes in the C or C++ programming languages are also given. The MQRC_ constants require the WebSphere MQ cmqc.h header file. The MQRCCF_ constants require the WebSphere MQ cmqcfc.h header file (apart from MQRCCF_FILTER_ERROR and MQRCCF_WRONG_USER, which require the WebSphere Business Integration Event Broker BipRfc.h header file).

Reason code and text Explanation Issued by
2336

MQRC_RFH_COMMAND_ERROR

Valid values for the <Command> field of a <psc> folder are: RegSub, DeregSub, Publish, DeletePub, and ReqUpdate. Any other values result in this error code being issued. Any command
2337

MQRC_RFH_ PARM_ERROR

The <psc> and <mcd> folders both have a set of valid parameters that can be specified within them. Check the descriptions of these folders and ensure that you have not specified incorrect parameters. Any command
2338

MQRC_RFH_DUPLICATE_PARM

Some parameters (for example, Topic) within a <psc> folder can be repeated, but others (for example, Command) cannot be repeated. Check that you have not duplicated a non-repeatable parameter. Any command
2339

MQRC_RFH_PARM_MISSING

Some parameters within <psc> or <mcd> folders are optional and can be omitted; some are mandatory and must not be omitted. Check that you have included all mandatory parameters within your <psc> and <mcd> folders. Any command
3008

MQRCCF_COMMAND_FAILED

An internal error occurred which prevented the command from executing correctly. The error might occur if the command is reissued. The system event log for the broker contains information which should be used when reporting the problem to IBM. Any command
3072

MQRCCF_TOPIC_ERROR

One or more of the values you supplied for the Topic parameter are incorrect. Check that your values for Topic conform to the specified restrictions. Any command
3073

MQRCCF_NOT_REGISTERED

The combination of SubPoint, Topic, and Filter that you specified on your DeregSub or ReqUpdate command was either not a combination with which you had previously registered or, for the DeregSub command if the DeregAll option was specified, one of the SubPoint, Topic, or Filter properties was not used to deregister any subscription. Deregister Subscriber and Request Update commands
3074

MQRCCF_Q_MGR_NAME_ERROR

The specified queue manager was not valid, or the queue manager was not available or did not exist. Deregister Subscriber, Publish, Register Subscriber, and Request Update commands
3076

MQRCCF_Q_NAME_ERROR

The specified queue name was not valid, or the queue did not exist on the specified queue manager. Deregister Subscriber, Publish, Register Subscriber, and Request Update commands
3077

MQRCCF_NO_RETAINED_MSG

There were no retained messages for the topic you specified. This might or might not be an error, depending on the design of your application program. Request Update command
3079

MQRCCF_INCORRECT_Q

RegSub, DeregSub, and ReqUpdate commands are always sent to the SYSTEM.BROKER.CONTROL.QUEUE queue of the broker for which they are intended. Publish and Delete Publication commands are sent to the input queue for the particular publish/subscribe message flow for which they are intended; this is determined when the message flow is designed. This error code is returned if a command is sent to the wrong queue. Any command
3080

MQRCCF_CORREL_ID_ERROR

You have specified CorrelAsId as one of your RegOpt parameters. However, the CorrelId field of the MQMD does not contain a valid correlation identifier (that is, it is set to MQCI_NONE). Deregister Subscriber and Register Subscriber commands
3081

MQRCCF_NOT_AUTHORIZED

You are not authorized to perform the requested action. Authorization settings for the broker are handled by the system administrator using the Topics Hierarchy editor. Publish and Register Subscriber commands
3083

MQRCCF_REG_OPTIONS_ERROR

You have specified an unrecognized RegOpt parameter in the <psc> folder that contains your DeregSub command. Deregister Subscriber and Register Subscriber commands
3084

MQRCCF_PUB_OPTIONS_ERROR

You have specified an unrecognized PubOpt parameter in the <psc> folder that contains your Publish command. Publish command
3087

MQRCCF_DEL_OPTIONS_ERROR

You have specified an unrecognized DelOpt parameter in the <psc> folder that contains your DeletePub command. Delete Publication command
3150

MQRCCF_FILTER_ERROR

The value specified for the Filter parameter is not valid. Check the section that describes the valid syntax for filter expressions and ensure that your expression conforms. Deregister Subscriber, Register Subscriber, and Request Update commands
3151

MQRCCF_WRONG_USER

A subscription that matches the one specified already exists; however, it was registered by a different user. A subscription can only be changed or de-registered by the user who originally registered it. Deregister Subscriber, Register Subscriber, and Request Update commands
3152

MQRCCF_DUPLICATE_SUBSCRIPTION

A matching subscription already exists with a different subscription name.  
3153

MQRCCF_SUB_NAME_ERROR

Either the format of the subscription name is not valid, or a matching subscription already exists with no subscription name.  
3154

MQRCCF_SUB_IDENTITY_ERROR

The subscription identity parameter is in error. Either the supplied value exceeds the maximum length allowed, or the subscription identity is not currently a member of the subscription's identity set and a Join registration option was not specified.  
3155

MQRCCF_SUBSCRIPTION_IN_USE

An attempt to modify or deregister a subscription was attempted by a member of the identity set when it was not the only member of this set.  
3156

MQRCCF_SUBSCRIPTION_LOCKED

The subscription is currently exclusively locked by another identity.  
3157

MQRCCF_ALREADY_JOINED

A Join registration option was specified but the subscriber identity was already a member of the subscription's identity set.