[IBMi]

Making initial checks on IBM i

Before you start problem determination in detail, consider whether there is an obvious cause of the problem, or an area of investigation that is likely to give useful results. This approach to diagnosis can often save a lot of work by highlighting a simple error, or by narrowing down the range of possibilities.

The cause of your problem could be in any of the following:
  • Hardware
  • Operating system
  • Related software, for example, a language compiler
  • The network
  • The IBM® MQ product
  • Your IBM MQ application
  • Other applications
  • Site operating procedures

This section contains a list of questions to consider. As you go through the list, make a note of anything that might be relevant to the problem. Even if your observations do not suggest a cause straight away, they might be useful later if you have to carry out a systematic problem determination exercise.

The following steps are intended to help you isolate the problem and are taken from the viewpoint of an IBM MQ application. Check all the suggestions at each stage.
  1. Has IBM MQ for IBM i run successfully before?
    Yes
    Proceed to Step 2.
    No
    It is likely that you have not installed or set up IBM MQ correctly.
  2. Has the IBM MQ application run successfully before?
    Yes
    Proceed to Step 3.
    No
    Consider the following:
    1. The application might have failed to compile or link, and fails if you attempt to invoke it. Check the output from the compiler or linker.

      Refer to the appropriate programming language reference information, or see Developing applications, for information about how to build your application.

    2. Consider the logic of the application. For example, do the symptoms of the problem indicate that a function is failing and, therefore, that a piece of code is in error.
      Check the following common programming errors:
      • Assuming that queues can be shared, when they are in fact exclusive.
      • Trying to access queues and data without the correct security authorization.
      • Passing incorrect parameters in an MQI call; if the wrong number of parameters is passed, no attempt can be made to complete the completion code and reason code fields, and the task is ended abnormally.
      • Failing to check return codes from MQI requests.
      • Using incorrect addresses.
      • Passing variables with incorrect lengths specified.
      • Passing parameters in the wrong order.
      • Failing to initialize MsgId and CorrelId correctly.
  3. Has the IBM MQ application changed since the last successful run?
    Yes
    It is likely that the error lies in the new or modified part of the application. Check all the changes and see if you can find an obvious reason for the problem.
    1. Have all the functions of the application been fully exercised before?

      Could it be that the problem occurred when part of the application that had never been invoked before was used for the first time? If so, it is likely that the error lies in that part of the application. Try to find out what the application was doing when it failed, and check the source code in that part of the program for errors.

    2. If the program has run successfully before, check the current queue status and files that were being processed when the error occurred. It is possible that they contain some unusual data value that causes a rarely used path in the program to be invoked.
    3. The application received an unexpected MQI return code. For example:
      • Does your application assume that the queues it accesses are shareable? If a queue has been redefined as exclusive, can your application deal with return codes indicating that it can no longer access that queue?
      • Have any queue definition or security profiles been changed? An MQOPEN call could fail because of a security violation; can your application recover from the resulting return code?

      See MQI Applications reference for your programming language for a description of each return code.

    4. If you have applied any PTF to IBM MQ for IBM i, check that you received no error messages when you installed the PTF.
    No
    Ensure that you have eliminated all the preceding suggestions and proceed to Step 4.
  4. Has the server system remained unchanged since the last successful run?
    Yes
    Proceed to Problem characteristics.
    No
    Consider all aspects of the system and review the appropriate documentation on how the change might have affected the IBM MQ application. For example :
    • Interfaces with other applications
    • Installation of new operating system or hardware
    • Application of PTFs
    • Changes in operating procedures

See the following sections for some additional tips for problem determination for system administrators and application developers.

Tips for system administrators

Tips for application developers

  • Check the return codes from the MQI calls in your applications. For a list of reason codes, see API completion and reason codes. Use the information provided in the return code to determine the cause of the problem. Follow the steps in the Programmer response sections of the reason code to resolve the problem.
  • If you are unsure whether your application is working as expected, for example, you are not unsure of the parameters being passed into the MQI or out of the MQI, you can use trace to collect information about all the inputs and outputs of your MQI calls. For more information about using trace, see Using trace.
  • For more information about handling errors in MQI applications, see Handling program errors.