endmqm (end queue manager)
Stop a queue manager or switch to a standby queue manager or to a replica queue manager.
Purpose
- Controlled or quiesced shutdown
- Immediate shutdown
- Pre-emptive shut down
- Wait shutdown
The endmqm command stops all instances of a multi-instance queue manager in the same way as it stops a single instance queue manager. You 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, you 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, you 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.
You can issue the endmqm command on the active or replica nodes of a Native HA group. A check is performed to see if stopping the specified instance breaks the group's quorum, and the command fails if it does. If you issue endmqm -s on the active instance, that instance stops and one of the replicas becomes the active instance. If you issue endmqm -x on a replica instance, the instance is stopped.
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 Stopping 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.
You must use the endmqm command from the installation associated with the
queue manager that you are working with. You 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. You 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
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
-
For a multi-instance queue manager, 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. You 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.
For the active instance of a Native HA group, switch over to a replica instance after shutting down.- Specify the
-r
option to help client applications to reconnect to another instance. - If this instance is not the active instance in the Native HA group then the command fails.
- If ending this active instance would cause the group quorum to fail then the command fails. (If other instances end or become unavailable at the same time as you run this command, the quorum check might not detect this, the Native HA group ends and can only be restarted when enough instances are available.)
- Specify the
- -w
- 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. 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
-
For a multi-instance queue manager, end a standby instance of the queue manager, without ending the active instance of the queue manager.
For a replica instance of a Native HA group, stop the instance:- If this instance is the active instance in the Native HA group then the command fails.
- If ending this replica instance would cause the group quorum to fail then the command fails. (If other instances end or become unavailable at the same time as you run this command, the quorum check might not detect this, the Native HA group ends and can only be restarted when enough instances are available.)
- -z
- Suppresses error messages on the command.
- -t <interval>
- The target time in which ending the queue manager within <interval> seconds is attempted, escalating the phases of application disconnection. Essential queue manager maintenance tasks are allowed to complete, which might prolong the phase of the queue manager ending. (For more information, see Ending a queue manager within a target time.)
- -tp <interval>
- The target time in which ending the queue manager within <interval> seconds is attempted, escalating the phases of application disconnection. Essential queue manager maintenance tasks are interrupted if necessary.
Return codes
Return code | Description |
---|---|
0 | Queue manager ended |
3 | Queue manager being created |
16 | Queue manager does not exist |
39 | Invalid parameter specified |
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 |
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
- 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
- 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
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. |
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. | |
Native HA Active | - | 0 | - | Active instance ended. Remaining instances communicate and elect a new Active, if they can find a quorum. | |
Native HA Replica | - | 0 | - | Replica instance ended. Remaining instances continue, if they have quorum. | |
-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. | |
-s | Native HA Active | Quorum would remain | 0 | - | Active instance ended. |
Native HA Active | Quorum would be broken | 79 | AMQ7275 | Instance has not ended because it would cause quorum to be lost. | |
Native HA Replica | - | 90 | AMQ7277 | This operation is not valid on a Replica instance. | |
-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. | |
-x | Native HA Active | - | 79 | AMQ8367 | Active instance of IBM MQ queue manager 'MG' not ended. |
Native HA Replica | Quorum would remain | 0 | - | Replica instance ended. | |
Native HA Replica | Quorum would be broken | 90 | AMQ7275 | Instance has not ended because it would cause quorum to be lost. |