Stopping a queue manager

We can use the endmqm command to stop a queue manager. This command provides four ways to stop a queue manager: a controlled, or quiesced, shutdown, an immediate shutdown, a preemptive shutdown, and a wait shutdown. Alternatively, on Windows and Linux, we can stop a queue manager by using the IBM MQ Explorer.

About this task

There are four ways to stop a single instance queue manager with the endmqm command:

Controlled (quiesced) shutdown

By default, the endmqm command performs a quiesced shutdown of the specified queue manager. A quiesced shutdown waits until all connected applications have disconnected, so might take a while to complete.

Immediate shutdown

For an immediate shutdown, any current MQI calls are allowed to complete, but any new calls fail. This type of shutdown does not wait for applications to disconnect from the queue manager.

Preemptive shutdown

The queue manager stops immediately. Use this type of shutdown only in exceptional circumstances, for example, when a queue manager does not stop as a result of a normal endmqm command.

Wait shutdown

This type of shutdown is equivalent to a controlled shutdown except that control is returned to you only after the queue manager has stopped.

The endmqm command stops all instances of a multi-instance queue manager in the same way as it stops a single instance queue manager. We can issue the endmqm on either the active instance, or one of the standby instances of a multi-instance queue manager. However, we must issue endmqm on the active instance to end the queue manager.

From IBM MQ Version 9.1.4, you have the option to end the queue manager within a target time of a number of seconds that you specify, either with or without interrupting essential queue manager maintenance tasks.

When you specify a target time, the shutdown type of -w, -i, or -p indicates the starting shutdown type.Note: An immediate shutdown is still orderly, differing from a controlled shutdown primarily in the way that any running applications are quiesced. An immediate shutdown still takes housekeeping actions such as queue compaction, and persisting NPMCLASS(HIGH) messages that could be time consuming, whereas a time limited shutdown quits these additional actions when they interfere with meeting the target time. The queue manager escalates the shutdown type as necessary, in an attempt to meet the target time. For example:

• A 10 second -t target starting at -w might be seven seconds quiescing, two seconds immediate shutdown of the queue manager, including housekeeping, then immediate shutdown without further housekeeping:

  endmqm queue_manager -w -t 10

• A 10 second -tp target might be seven seconds quiescing, two seconds immediate shutdown of the queue manager, including housekeeping, one second immediate shutdown without further housekeeping, then start ending IBM MQ processes:

  endmqm queue_manager -c -tp 10

• A two second -tp target at -i might be one second immediate shutdown of the queue manager, including housekeeping, one second immediate shutdown without further housekeeping, then start ending IBM MQ processes:

  endmqm queue_manager -i -tp 2

• A one second target at -w could be 0.1 seconds at wait, for example, just long enough to send out IBM MQ return codes to connected applications, 0.9 seconds immediate shutdown of the queue manager, including housekeeping, then immediate shutdown without further housekeeping; then start ending IBM MQ processes.

Attention:

• Persistent messages will persist regardless of the type of shutdown used (including manually ending IBM MQ processes), whereas non persistent messages cannot be guaranteed to survive any type of shutdown.

  NPMCLASS(HIGH) saves non-persistent messages on a best can do basis. Using endmqm -t, endmqm -tp, endmqm -p, or manually ending IBM MQ processes reduces the chances of NPMCLASS(HIGH) messages surviving an IBM MQ shutdown or restart cycle compared to endmqm -w or endmqm -i

• The combined time to both end and restart the queue manager can be longer as a result of using a more abrupt shutdown, particularly when using the -p and -tp options.

  If the queue manager has to resort to ending IBM MQ processes to end the queue manager, then more reconciliation of queue manager state is likely to be needed when the queue manager is restarted.

For a detailed description of the endmqm command and its options, see endmqm.

Tip: Problems with shutting down a queue manager are often caused by applications. For example, when applications:

• Do not check MQI return codes properly
• Do not request notification of a quiesce
• Terminate without disconnecting from the queue manager (by issuing an MQDISC call)

If a problem occurs when you try to stop the queue manager, we can break out of the endmqm command by using Ctrl-C. We can then issue another endmqm command, but this time with a parameter that specifies the type of shutdown that you require.

As an alternative to using the endmqm command, on Windows and Linux, we can stop a queue manager by using the IBM MQ Explorer to carry out either a controlled or an immediate shutdown.

Procedure

• To stop the queue manager by using the endmqm command, enter the command followed by the appropriate parameter, if required, and the name of the queue manager that we want to stop. Note: We must use the endmqm command from the installation associated with the queue manager that we are working with. To find out which installation a queue manager is associated with, use the dspmq command:

   dspmq -o installation

  • To carry out a controlled (quiesced) shutdown, enter the endmqm command as shown in the following example, which stops a queue manager called QMB:

    endmqm QMB
    

    Alternatively, entering the endmqm command with the -c parameter, as shown in the following example, is equivalent to an endmqm QMB command.

    endmqm -c QMB

    In both cases, control is returned to you immediately and we are not notified when the queue manager has stopped. If we want the command to wait until all applications have stopped and the queue manager has ended before returning control to you, use the -w parameter instead as shown in the following example.

    endmqm -w QMB
    

  • To carry out an immediate shutdown, enter the endmqm command with the -i parameter as shown in the following example:

    endmqm -i QMB
    

  • To carry out a preemptive shutdown, enter the endmqm command with the -p parameter as shown in the following example:

    endmqm -p QMB
    

    Attention: A preemptive shutdown can have unpredictable consequences for connected applications. Do not use this option unless all other attempts to stop the queue manager by using a normal endmqm command have failed. If the preemptive shutdown does not work, try Stopping a queue manager manually instead.
  • To request automatic client reconnection, enter the endmqm command with the -r parameter. This parameter has the effect of reestablishing the connectivity of clients to other queue managers in their queue manager group. Note: Ending a queue manager by using the default endmqm command does not trigger automatic client reconnection.
  • To transfer to a standby instance of a multi-instance queue manager after shutting down the active instance, enter the endmqm command with the -s parameter on the active instance of the multi-instance queue manager.
  • To end the standby instance of a multi-instance queue manager and leave the active instance running, enter the endmqm command with the -x parameter on the standby instance of the multi-instance queue manager.

• On Windows and Linux, to stop the queue manager by using IBM MQ Explorer, complete the following steps:
  1. Open the IBM MQ Explorer.
  2. Select the queue manager from the Navigator View.
  3. Click Stop. The End Queue Manager panel is displayed.
  4. Select Controlled, or Immediate.
  5. Click OK. The queue manager stops.

Parent topic: Work with queue managers

Related information

• Applying maintenance level updates to multi-instance queue managers on Windows
• Applying maintenance level updates to multi-instance queue managers on UNIX and Linux