endmqm (end queue manager)

Stop a queue manager or switch to a standby queue manager.


Purpose

Use the endmqm command to end (stop) a specified queue manager. This command stops a queue manager in one of three modes:

  • Controlled or quiesced shutdown
  • Immediate shutdown
  • Pre-emptive shut down

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. You must issue endmqm on the active instance to end the queue manager.

If you issue the endmqm command on the active instance of a multi-instance queue manager, we can permit a standby instance to switch over to being the new active instance when the current active instance completes its shutdown.

If you issue the endmqm command on a standby instance of a multi-instance queue manager, we can end the standby instance by adding the -x option, and leave the active instance running. The queue manager reports an error if you issue endmqm on the standby instance without the -x option.

Issuing the endmqm command will affect any client application connected through a server-connection channel. The effect varies depending on the parameter used, but it is as though a STOP CHANNEL command was issued in one of the three possible modes. See Stop MQI channels, for information about the effects of STOP CHANNEL modes on server-connection channels. The endmqm optional parameter descriptions state which STOP CHANNEL mode they will be equivalent to.

If you issue endmqm to stop a queue manager, reconnectable clients do not try to reconnect. To override this behavior, specify either the -r or -s option to enable clients to start trying to reconnect. Note: If a queue manager or a channel ends unexpectedly, reconnectable clients start trying to reconnect. Note: The client might not reconnect to this queue manager. Depending on the MQCONNX reconnect option the client has used, and the definition of the queue manager group in the client connection table, the client might reconnect to a different queue manager. We can configure the client to force it to reconnect to the same queue manager.

You must use the endmqm command from the installation associated with the queue manager that you are working with. We can find out which installation a queue manager is associated with using the dspmq -o installation command.

The attributes of the queue manager and the objects associated with it are not affected by the endmqm command. We can restart the queue manager using the strmqm (Start queue manager) command.

To delete a queue manager, stop it and then use the dltmqm (Delete queue manager) command.


Syntax

endmqm   -z   -c   -w   -i   -p   -s -r-x QMgrName


Required parameters

    QMgrName
    The name of the message queue manager to be stopped.


Optional parameters

    -c
    Controlled (or quiesced) shutdown. This parameter is the default.

    The queue manager stops, but only after all applications have disconnected. Any MQI calls currently being processed are completed. In the unlikely event that a dspmq (display queue managers) command is issued in the small timeframe between the applications disconnecting and the queue manager actually stopping, the dspmq (display queue managers) command might transiently report the status as Ending immediately , even though a controlled shutdown was requested.

    Control is returned to you immediately and you are not notified of when the queue manager has stopped.

    The effect on any client applications connected through a server-connection channel is equivalent to a STOP CHANNEL command issued in QUIESCE mode.

    -i
    Immediate shutdown. The queue manager stops after it has completed all the MQI calls currently being processed. Any MQI requests issued after the command has been issued fail. Any incomplete units of work are rolled back when the queue manager is next started.

    Control is returned after the queue manager has ended.

    The effect on any client applications connected through a server-connection channel is equivalent to a STOP CHANNEL command issued in FORCE mode.

    -p
    Pre-emptive shutdown. Important: 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.

    The queue manager might stop without waiting for applications to disconnect or for MQI calls to complete. This can give unpredictable results for IBM MQ applications. The shutdown mode is set to immediate shutdown. If the queue manager has not stopped after a few seconds, the shutdown mode is escalated, and all remaining queue manager processes are stopped.

    The effect on any client applications connected through a server-connection channel is equivalent to a STOP CHANNEL command issued in TERMINATE mode.

    -r
    Start trying to reconnect reconnectable clients. This parameter has the effect of reestablishing the connectivity of clients to other queue managers in their queue manager group.
    -s
    Switch over to a standby queue manager instance after shutting down. The command checks that there is a standby instance running before ending the active instance. It does not wait for the standby instance to start before ending.

    Connections to the queue manager are broken by the active instance shutting down. Reconnectable clients start trying to reconnect.

    We can configure the reconnection options of a client to reconnect only to another instance of the same queue manager, or to reconnect to other queue managers in the queue manager group.

    -w
    Wait shutdown.

    This type of shutdown is equivalent to a controlled shutdown except that control is returned to we only after the queue manager has stopped. You receive the message Waiting for queue manager qmName to end while shutdown progresses. In the unlikely event that a dspmq (display queue managers) command is issued in the small timeframe between the applications disconnecting and the queue manager actually stopping, the dspmq (display queue managers) command might transiently report the status as Ending immediately , even though a controlled shutdown was requested.

    The effect on any client applications connected through a server-connection channel is equivalent to a STOP CHANNEL command issued in QUIESCE mode.

    -x
    End a standby instance of the queue manager, without ending the active instance of the queue manager.
    -z
    Suppresses error messages on the command.


Return codes

Return code Description
0 Queue manager ended
3 Queue manager being created
16 Queue manager does not exist
40 Queue manager not available
49 Queue manager stopping
58 Inconsistent use of installations detected
62 The queue manager is associated with a different installation
69 Storage not available
71 Unexpected error
72 Queue manager name error
77 IBM MQ queue manager cannot switch over
79 Active instance of IBM MQ queue manager QmgrName not ended
90 Standby instance of IBM MQ queue manager QmgrName not ended
119 Permission denied


Examples

The following examples show commands that stop the specified queue managers.
  1. This command ends the queue manager named mercury.queue.manager in a controlled way. All applications currently connected are allowed to disconnect.
    endmqm mercury.queue.manager
    
  2. This command ends the queue manager named saturn.queue.manager immediately. All current MQI calls complete, but no new ones are allowed.
    endmqm -i saturn.queue.manager
    
The results of issuing endmqm to the local instance of a multi-instance queue manager are shown in Table 1. The results of the command depend on whether the -s or -x switch is used, and the running status of local and remote instances of the queue manager.
Table 1. endmqm actions.
endmqm option Local machine Remote machine RC Message Result
  Active None 0 - Queue manager ended.
Standby Queue manager ended, including the standby instance.
Standby Active 90 AMQ8368 Standby instance of IBM MQ queue manager QmgrName not ended.
-s Active None 77 AMQ7276 IBM MQ queue manager cannot switch over.
Standby 0 - Queue manager QMNAME ended, permitting switchover to a standby instance.
Standby Active 90 AMQ8368 Standby instance of IBM MQ queue manager QmgrName not ended.
-x Active None 79 AMQ8367 Active instance of IBM MQ queue manager QmgrName not ended.
Standby
Standby Active 0 - Standby instance of queue manager QMNAME ended.