Troubleshooting IBM MQ Console and REST API problems

Diagnose problems with the IBM® MQ Console and REST API by looking at the available logs. When asked by IBM Support, you might also need to configure trace.

• The status of the mqweb server.
  If the mqweb server is stopped, you cannot use the IBM MQ Console or REST API. You can check the status of the server by using the following command:

  dspmqweb status

  Attention:

  Before you issue either the setmqweb or dspmqweb commands on z/OS®, you must set the WLP_USER_DIR environment variable so that the variable points to your mqweb server configuration.

  To set the WLP_USER_DIR environment variable, issue the following command:

  export WLP_USER_DIR=WLP_user_directory

  where WLP_user_directory is the name of the directory that is passed to crtmqweb. For example:

  export WLP_USER_DIR=/var/mqm/web/installation1

  For more information, see Create the mqweb server.

  Attention:

  Before you issue either the setmqweb or dspmqweb commands in a stand-alone IBM MQ Web Server installation, you must set the MQ_OVERRIDE_DATA_PATH environment variable to the IBM MQ Web Server data directory.

  If the mqweb server is stopped, start the server with the following command:

  strmqweb

  On z/OS, check that the mqweb server started task is running. If necessary, start the procedure that you created in Create a procedure for the mqweb server.

• Ensure that the following mqweb configuration files exist:
  • jvm.options
  • mqwebuser.xml
  • server.xml

  Look for the files in the MQ_DATA_PATH/web/installations/installationName/servers/mqweb/ directory by using the crtmqdir command.

  To check the installation, which includes searching for these files, use the following command:

  crtmqdir -a

  If the files are missing, you can re-create them by using the command:

  crtmqdir -s -f

• Examine the mqweb server log files, console.log, and messages.log.
  These log files can be found in the following location:

  • MQ_DATA_PATH/web/installations/installationName/servers/mqweb/logs
  • The directory that was specified when the crtmqweb script ran to create the mqweb server definition. By default, this directory is /var/mqm/web/installation1/servers/mqweb/logs.
    These files are in UTF-8. To view the files, you can use one of the following methods:

    • Use the oedit command from a z/OS UNIX System Services command line.
    • Enter ISPF option 3.17, and use the va (view ASCII) line command.
• On z/OS, check STDERR and STDOUT in the mqweb server started task output. STDERR contains no messages, unless an error occurred.
• If you cannot access the IBM MQ Console or REST API from a host other than the system where the mqweb server is running, check that remote connections are enabled.
  Issue the following command to display the mqweb server configuration:

  dspmqweb properties -a

  If the value of the httpHost property is localhost, the IBM MQ Console and REST API are available only from the same host as the mqweb server. Enable remote connections to the mqweb server by entering the following command where hostname specifies the IP address or domain name server (DNS) hostname where IBM MQ is installed:

  setmqweb properties -k httpHost -v hostname

  Use an asterisk, *, in double quotation marks, to specify all available network interfaces, as shown in the following example:

  setmqweb properties -k httpHost -v "*"

• If no queue managers are displayed in the local queue manager widget in the IBM MQ Console, check that you have queue managers on the same host as the mqweb server that you can manage with the IBM MQ Console.
  • Only queue managers in the same installation as the mqweb server are listed in the IBM MQ Console.
  • On z/OS, only queue managers that are started at the same version as the mqweb server since the last IPL are listed in the IBM MQ Console.
• If messages are truncated when you browse queues in the IBM MQ Console, adjust the mqConsoleMaxMsgCharsToDisplay and mqConsoleMaxMsgRequestSize properties by using the setmqweb properties command.
• If you are using the messaging REST API with remote queue managers and you cannot connect to the queue manager, check the following things:
  • You are specifying the unique name for the queue manager, not the queue manager name, within the resource URL.
  • You are trying to connect to a queue manager that is visible to the messaging REST API. Some queue managers might be available only to the IBM MQ Console. You can verify whether the queue manager is configured to be visible to the messaging REST API by using the dspmqweb remote command. View the visibility parameter to check whether the queue manager is visible to the messaging REST API.
  • You are not prefixing an asterisk to the queue manager name to specify that you want to connect to a queue manager group. To specify you want to connect to a queue manager group, you must set the group attribute in the remote queue manager configuration. For more information, see Setting up a remote queue manager group to use with the messaging REST API.
  • Ensure that the CCDT file is in the location that is specified by the ccdtUrl parameter in the dspmqweb remote command.
• If you are still experiencing problems, the mqweb server started task might not be configured correctly, or there might be a problem with the IBM MQ for z/OS UNIX System Services Web Components installation files.
  You might see the following message in the IBM MQ Console:

  Lost communication with the server Could not establish communication with the server.

  In the procedure that is used to start the mqweb server check the following things:

  1. Check that the STEPLIB libraries are at the correct level, and are APF authorized.
  2. Check that INSTDIR, USERDIR, PATH, and LIBPATH point to the correct path.

  In z/OS UNIX System Services, enter the following command where PathPrefix is the IBM MQ for z/OS UNIX System Services Components installation path:

  ls -Eltr PathPrefix/web/bin/dspmq

  This command displays an output similar to the following output:

  -rwxr-xr-t a-s- ... /mqm/V10R0M0/web/bin/dspmq

  Check the t and a flags are set. If necessary, use the commands:

  • chmod +t PathPrefix/web/bin/dspmq to set the sticky bit (t)
  • extattr +a PathPrefix/web/bin/dspmq to set the APF-authorized attribute (a)