Troubleshooting: Websphere MQ

Table 1. Troubleshooting Websphere MQ
Problem	Description	Solution
WebSphere® MQ `error 2009 (MQRC_CONNECTION_BROKEN)` When you are using a publisher, if the error `Publish Error putting (publishing) message - An error occurred while putting the message on the queue "default". Cause: MQJE001: Completion Code 2, Reason 2009` is displayed, verify that all the transport details are correct and that the correct queue manager is connected.	A common reason for this error is that the channel on the queue manager is not set up correctly.	This channel needs to be configured as a Server Connection channel and have suitable access rights that are applied to it. For more information, see 2009 (07D9) (RC2009): MQRC_CONNECTION_BROKEN.
WebSphere® MQ error 2035 (MQRC_NOT_AUTHORIZED)	(1) When you are using any of the messaging operations, access to the queue is made; if the settings on the queue differ from the defaults within the application, you must override the values. The actual values can be obtained from documentation. By default, WebSphere® MQ 7.1 has more security settings. (2) Authentication from a Java client to the WebSphere® MQ queue manager fails when the authentication password length is greater than 12 characters.	(1) Ensure that user authorization is configured correctly for accessing the message queue. (1) A quick way to overcome most permission errors is to configure the server connection channel to use the appropriate WebSphere® MQ administrator user account (or mqm, if you are using Unix-like systems), which has privileges to access most objects. (2) Add the `Use MQCSP authentication` property and set its value to `true` in the WebSphere® MQ transport message settings. For more information about this property, see Connection authentication with the Java client.
WebSphere® MQ error 2033 (MQRC_NO_MSG_AVAILABLE)	WebSphere® MQ recording fails with a MQRC_NO_MSG_AVAILABLE [MQRC.2033] error.	Recording is started by using the User ID and Password configured on the WebSphere® MQ Server Physical Transport. If none is configured, then the Windows User ID and password that was used to log in to HCL OneTest™ API is used to start recording.
WebSphere® MQ error 2042 (MQRC_OBJECT_IN_USE)	If a stub attempts to read from a WebSphere® MQ local queue, an error of the following format might be displayed: `[Error] Instance 1: Receive Request:"MQ Message" on queue "RIT_TARGET" using schema "MQ Message" via "winmvs3i_MQ71" Error accessing queue (RIT_TARGET): MQRC_OBJECT_IN_USE [MQRC.2042].`	In WebSphere® MQ, a queue can be opened in any of the following ways: Default access, which uses the queue's default definition for access type. Exclusive access, which means that applications that open the queue for input have exclusive access to the messages on the queue. Shared access, which means that any number of applications that open a queue for input can access the messages on the queue. For stubs, to ensure greater throughput, HCL OneTest™ API uses multiple connections to a queue manager. If a queue has been opened with exclusive access, any other attempt to open that queue, either from the same application or other applications, will result in the MQRC_OBJECT_IN_USE error. Examples of queues being opened with exclusive access are when an application that opened the queue (in this case, HCL OneTest™ API) explicitly requested exclusive access, or the application used default access and the queue object was configured with exclusive as the default access option. For more information, see 2042 (07FA) (RC2042): MQRC_OBJECT_IN_USE.
WebSphere® MQ error 2374 (MQRC_API_EXIT_ERROR)	This error indicates that an API exit function returned an invalid response code, or failed in some other way. The most likely cause of this error is that an API exits files were copied to the incorrect directory of the server that is running the queue manager that is supposed to use the API exit.	For more information, see Installing and configuring HCL OneTest API API exits and 2374 (0946) (RC2374): MQRC_API_EXIT_ERROR.
Unable to edit transport or formatter unavailable	It is probable that Library Manager was not used to configure the required JAR files.	Use the Library Manager to configure the files. See Working with Library Manager.
Messages not recording when you are using API exits	When you start recording queues and you are using the HCL OneTest™ API API exit, HCL OneTest™ API configures the queue manager automatically so that it puts copies of messages into the queues that are used by HCL OneTest™ API. However, this configuration will apply only to connections made to the queue manager after you start the recording.	If any process maintains a connection to the queue manager before the recording started, you do not see events that are put into these queues. Depending on how your publishing applications are written, you must restart them after recording starts. HCL OneTest™ API adds reply queues to those being recorded automatically when it sees a message that is being sent with a reply queue. However, if the subscriber already has an open connection to the queue manager, you do not see it in Recording Studio when it puts a response to the reply queue. Restarting the subscriber after it processes one message can work around this problem. Alternatively, use the Record-the-transport option to record all queues. For more information about the API exits supplied with HCL OneTest™ API, see Installing and configuring HCL OneTest API API exits. Note: If WebSphere® MQ exits are used, the WebSphere® MQ messages that are already in the queue are not processed. You can either record the messages or the stub can process only the new messages that are published after you start the operation.
RIT8806E Failed to start proxy route: An exception occurred while adding a rule to the rules namelist [rit.divert.rules]	When you use a queue for the stub update locking mechanism, the stub fails to start with RIT8806E shown	To find the cause, go to the JVM console to see the following message. WARNING: Could not lock namelist as could not access the queue: rit.divert.rules_LCK com.ibm.mq.MQException: MQJE001: Completion Code '2', Reason '2085'. As an administrator either create the queue named in the JVM console, or to give the RIT user sufficient authority to create queues. Note that in the former case, where the queue manager is in a Queue Sharing Group, a shared queue should be created.
WebSphere® MQ Error 2045 (MQRC_OPTION_NOT_VALID_FOR_TYPE)	If your stubbing mode is set to direct, and you attempt to run a stub where the request queue is a remote queue, the stub will fail with this error. For other scenarios that might cause an MQ 2045 reason code, see the WebSphere® MQ documentation.	If the request queue is a remote queue, change the stubbing mode to use the sift-and-pass-through capability. For more information see Using WebSphere MQ transports on distributed platforms to test traffic to and from WebSphere MQ on z/OS.
WebSphere® MQ Error 2085 (MQRC_UNKNOWN_OBJECT_NAME)	If you attempt to run a stub where the request queue is located on a remote queue manager, you might see this error if your operation is not set up correctly, or if the stubbing mode is set to direct.	Ensure that the stubbing mode is set to use the sift-and-pass-through capability, and ensure that the operation is defined according to the guidelines in Using WebSphere MQ transports on distributed platforms to test traffic to and from WebSphere MQ on z/OS.
`The field found in the received message was unexpected (Action = "Validate Message Children")`	Starting with HCL OneTest™ API 10.0.0, HCL OneTest™ API captures attributes specified within RFH2 user-defined folders. If you created a WebSphere® MQ request/reply test in releases before HCL OneTest™ API 10.0.0, and you ran that test by using HCL OneTest™ API 10.0.0, and the reply message contains attributes within an RFH2 user-defined folder, you receive this message.	Edit the Receive Reply test step, select the folder within the MQRFH2, and select the Ignore additional fields in received message check box. Another solution is to recreate the test step by using HCL OneTest™ API 10.0.0 or above.
Messages with MQCIH headers are incorrectly passed through by stubs with a message similar to this message: `Message Case: "MQ Message" using schema "MQ Message" "/CIHv1/Encoding" - Expected value "785", found value "0" (Action = "Equality"), trying next..`	According to WebSphere® MQ documentation, the encoding field within the MQCIH is reserved. See Encoding (MQLONG). Since the field is reserved for future use by IBM, it is best not to filter on this field.	Edit the stub so that no filtering is performed on the MQCIH encoding field.

WebSphere® MQ error 2009 (MQRC_CONNECTION_BROKEN) When you are using a publisher, if the error

Publish Error putting (publishing) message - An error occurred while putting the message on
         the queue "default". Cause: MQJE001: Completion Code 2, Reason 2009

is displayed, verify that all the transport details are correct and that the correct queue manager is connected.

A common reason for this error is that the channel on the queue manager is not set up correctly.

This channel needs to be configured as a Server Connection channel and have suitable access rights that are applied to it.

For more information, see 2009 (07D9) (RC2009): MQRC_CONNECTION_BROKEN.

WebSphere® MQ error 2035 (MQRC_NOT_AUTHORIZED)

(1) When you are using any of the messaging operations, access to the queue is made; if the settings on the queue differ from the defaults within the application, you must override the values. The actual values can be obtained from documentation. By default, WebSphere® MQ 7.1 has more security settings.

(2) Authentication from a Java client to the WebSphere® MQ queue manager fails when the authentication password length is greater than 12 characters.

(1) Ensure that user authorization is configured correctly for accessing the message queue.

(1) A quick way to overcome most permission errors is to configure the server connection channel to use the appropriate WebSphere® MQ administrator user account (or mqm, if you are using Unix-like systems), which has privileges to access most objects.

(2) Add the Use MQCSP authentication property and set its value to true in the WebSphere® MQ transport message settings. For more information about this property, see Connection authentication with the Java client.

WebSphere® MQ error 2033 (MQRC_NO_MSG_AVAILABLE)

WebSphere® MQ recording fails with a MQRC_NO_MSG_AVAILABLE [MQRC.2033] error.

Recording is started by using the User ID and Password configured on the WebSphere® MQ Server Physical Transport. If none is configured, then the Windows User ID and password that was used to log in to HCL OneTest™ API is used to start recording.

WebSphere® MQ error 2042 (MQRC_OBJECT_IN_USE)

If a stub attempts to read from a WebSphere® MQ local queue, an error of the following format might be displayed: [Error] Instance 1: Receive Request:"MQ Message" on queue "RIT_TARGET" using schema "MQ Message" via "winmvs3i_MQ71" Error accessing queue (RIT_TARGET): MQRC_OBJECT_IN_USE [MQRC.2042].

In WebSphere® MQ, a queue can be opened in any of the following ways:
- Default access, which uses the queue's default definition for access type.
- Exclusive access, which means that applications that open the queue for input have exclusive access to the messages on the queue.
- Shared access, which means that any number of applications that open a queue for input can access the messages on the queue.
For stubs, to ensure greater throughput, HCL OneTest™ API uses multiple connections to a queue manager. If a queue has been opened with exclusive access, any other attempt to open that queue, either from the same application or other applications, will result in the MQRC_OBJECT_IN_USE error. Examples of queues being opened with exclusive access are when an application that opened the queue (in this case, HCL OneTest™ API) explicitly requested exclusive access, or the application used default access and the queue object was configured with exclusive as the default access option.

For more information, see 2042 (07FA) (RC2042): MQRC_OBJECT_IN_USE.

WebSphere® MQ error 2374 (MQRC_API_EXIT_ERROR)

This error indicates that an API exit function returned an invalid response code, or failed in some other way. The most likely cause of this error is that an API exits files were copied to the incorrect directory of the server that is running the queue manager that is supposed to use the API exit.

For more information, see Installing and configuring HCL OneTest API API exits and 2374 (0946) (RC2374): MQRC_API_EXIT_ERROR.

Unable to edit transport or formatter unavailable

It is probable that Library Manager was not used to configure the required JAR files.

Use the Library Manager to configure the files. See Working with Library Manager.

Messages not recording when you are using API exits

When you start recording queues and you are using the HCL OneTest™ API API exit, HCL OneTest™ API configures the queue manager automatically so that it puts copies of messages into the queues that are used by HCL OneTest™ API. However, this configuration will apply only to connections made to the queue manager after you start the recording.

If any process maintains a connection to the queue manager before the recording started, you do not see events that are put into these queues. Depending on how your publishing applications are written, you must restart them after recording starts.

HCL OneTest™ API adds reply queues to those being recorded automatically when it sees a message that is being sent with a reply queue. However, if the subscriber already has an open connection to the queue manager, you do not see it in Recording Studio when it puts a response to the reply queue. Restarting the subscriber after it processes one message can work around this problem. Alternatively, use the Record-the-transport option to record all queues.

For more information about the API exits supplied with HCL OneTest™ API, see Installing and configuring HCL OneTest API API exits.

Note: If WebSphere® MQ exits are used, the WebSphere® MQ messages that are already in the queue are not processed. You can either record the messages or the stub can process only the new messages that are published after you start the operation.

RIT8806E Failed to start proxy route: An exception occurred while adding a rule to the rules namelist [rit.divert.rules]

When you use a queue for the stub update locking mechanism, the stub fails to start with RIT8806E shown

To find the cause, go to the JVM console to see the following message.

WARNING: Could not lock namelist as could not access the queue: rit.divert.rules_LCK com.ibm.mq.MQException: MQJE001: Completion Code '2', Reason '2085'.

As an administrator either create the queue named in the JVM console, or to give the RIT user sufficient authority to create queues.

Note that in the former case, where the queue manager is in a Queue Sharing Group, a shared queue should be created.

WebSphere® MQ Error 2045 (MQRC_OPTION_NOT_VALID_FOR_TYPE)

If your stubbing mode is set to direct, and you attempt to run a stub where the request queue is a remote queue, the stub will fail with this error. For other scenarios that might cause an MQ 2045 reason code, see the WebSphere® MQ documentation.

If the request queue is a remote queue, change the stubbing mode to use the sift-and-pass-through capability. For more information see Using WebSphere MQ transports on distributed platforms to test traffic to and from WebSphere MQ on z/OS.

WebSphere® MQ Error 2085 (MQRC_UNKNOWN_OBJECT_NAME)

If you attempt to run a stub where the request queue is located on a remote queue manager, you might see this error if your operation is not set up correctly, or if the stubbing mode is set to direct.

Ensure that the stubbing mode is set to use the sift-and-pass-through capability, and ensure that the operation is defined according to the guidelines in Using WebSphere MQ transports on distributed platforms to test traffic to and from WebSphere MQ on z/OS.

The field found in the received message was unexpected (Action =
         "Validate Message Children")

Starting with HCL OneTest™ API 10.0.0, HCL OneTest™ API captures attributes specified within RFH2 user-defined folders. If you created a WebSphere® MQ request/reply test in releases before HCL OneTest™ API 10.0.0, and you ran that test by using HCL OneTest™ API 10.0.0, and the reply message contains attributes within an RFH2 user-defined folder, you receive this message.

Edit the Receive Reply test step, select the folder within the MQRFH2, and select the Ignore additional fields in received message check box.

Another solution is to recreate the test step by using HCL OneTest™ API 10.0.0 or above.

Messages with MQCIH headers are incorrectly passed through by stubs with a message similar to this message:

Message Case: "MQ Message" using schema "MQ Message"
         "/CIHv1/Encoding" - Expected value "785", found value "0" (Action = "Equality"), trying
         next..

According to WebSphere® MQ documentation, the encoding field within the MQCIH is reserved. See Encoding (MQLONG). Since the field is reserved for future use by IBM, it is best not to filter on this field.

Edit the stub so that no filtering is performed on the MQCIH encoding field.