amqmdain (services control)

amqmdain is used to configure or control some Windows specific administrative tasks.


Purpose

The amqmdain command applies to IBM MQ for Windows only.

We can usse amqmdain to perform some Windows specific administrative tasks.

Starting a queue manager with amqmdain is equivalent to using the strmqm command with the option -ss. amqmdain makes the queue manager run in a non-interactive session under a different user account. However, to ensure that all queue manager startup feedback is returned to the command line, use the strmqm -ss command rather than amqmdain.

We must use the amqmdain command from the installation associated with the queue manager that we are working with. We can find out which installation a queue manager is associated with using the dspmq command as follows: 
dspmq -o installation

To administer and define IBM MQ service and listener objects, use MQSC commands, PCF commands, or the IBM MQ Explorer.

The amqmdain command has been updated to modify either the .ini files or the registry as appropriate.


Syntax

amqmdain qmgr startQMgrNameqmgr endQMgrName-c-w-i-p-s~ -r-xqmgr alterQMgrName-iInitiation-xMulti-instancerefreshautoQMgrNamemanualQMgrNamestatusQMgrNameallregsecspnQMgrNamesetunsetregQMgrName*RegParams


Keywords and parameters

All parameters are required unless the description states they are optional.

In every case, QMgrName is the name of the queue manager to which the command applies.

    qmgr start QMgrName
    Starts a queue manager.

    This parameter can also be written in the form start QMgrName.

    If you start your queue manager as a service and need the queue manager to continue to run after logoff, use strmqm -ss qmgr instead of amqmdain start qmgr.

    qmgr end QMgrName
    Ends a queue manager.

    This parameter can also be written in the form end QMgrName.

    For consistency across platforms, use endmqm qmgr instead of amqmdain end qmgr.

    For fuller descriptions of the options, see endmqm (end queue manager).

    -c
    Controlled (or quiesced) shutdown.

    -w
    Wait shutdown.

    -i
    Immediate shut down.

    -p
    Pre-emptive shut down.

    -r
    Reconnect clients.

    -s
    Switch over to a standby queue manager instance.

    -x
    End the standby instance of the queue manager without ending the active instance.

    qmgr alter QMgrName
    Alters a queue manager.

    -i Initiation
    Specifies the initiation type. Possible values are:

    Value Description
    auto Sets the queue manager to automatic startup (when the machine starts, or more precisely when the IBM MQ service starts). The syntax is: 
    amqmdain qmgr alter QmgrName -i auto
    interactive Sets the queue manager to manual startup that then runs under the logged on (interactive) user. The syntax is: 
    amqmdain qmgr alter QmgrName -i interactive
    service Sets the queue manager to manual startup that then runs as a service. The syntax is: 
    amqmdain qmgr alter QmgrName -i service

    -x Multi-instance
    Specifies if auto queue manager start by the IBM MQ service permits multiple instances. Equivalent to the -sax option on the crtmqm command. Also specifies if the amqmdain start qmgr command permits standby instances. Possible values are:

    Value Description
    set Sets automatic queue manager startup to permit multiple instances. Issues strmqm -x . The set option is ignored for queue managers that are initiated interactively or as a manual service startup. The syntax of the command is: 
    amqmdain qmgr alter QmgrName -x set
    unset Sets automatic queue manager startup to single instance. Issues strmqm. The unset option is ignored for queue managers that are initiated interactively or as a manual service startup. The syntax of the command is: 
    amqmdain qmgr alter QmgrName -x unset

    refresh
    Refreshes or checks the status of a queue manager. You will not see anything returned on the screen after executing this command.

    auto QMgrName
    Sets a queue manager to automatic startup.

    manual QMgrName
    Sets a queue manager to manual startup.

    status QMgrName| all
    These parameters are optional.

    Header Header
    If no parameter is supplied: Displays the status of the IBM MQ services.
    If a QMgrName is supplied: Displays the status of the named queue manager.
    If the parameter all is supplied: Displays the status of the IBM MQ services and all queue managers.

    regsec
    Ensures that the security permissions assigned to the Registry keys containing installation information are correct.

    spn QMgrName set | unset
    We can set or unset the service principal name for a queue manager.

    reg QMgrName| * RegParams
    Parameters QMgrName, and * are optional.

    Value Description
    If RegParams is specified alone: Modifies queue manager configuration information related to the default queue manager.
    If QMgrName and RegParams are specified: Modifies queue manager configuration information related to the queue manager specified by QMgrName.
    If * and RegParams are specified: Modifies IBM MQ configuration information.
    The parameter, RegParams, specifies the stanzas to change, and the changes that are to be made. RegParams takes one of the following forms:

    • -c add -s stanza -v attribute= value
    • -c remove -s stanza -v [attribute|*]
    • -c display -s stanza -v [attribute|*]

    If we are specifying queue manager configuration information, the valid values for stanza are: 

    XAResourceManager\name
ApiExitLocal\name
Channels
ExitPath
InstanceData
Log
QueueManagerStartup
TCP
LU62
SPX
NetBios
Connection
QMErrorLog
Broker

ExitPropertiesLocal
SSL
    If we are modifying IBM MQ configuration information, the valid values for stanza are: 
    ApiExitCommon\name
ApiExitTemplate\name
ACPI
AllQueueManagers
Channels
DefaultQueueManager
LogDefaults
ExitProperties
    Note the following usage considerations:

    • amqmdain does not validate the values you specify for name, attribute, or value.
    • When you specify add, and an attribute exists, it is modified.
    • If a stanza does not exist, amqmdain creates it.
    • When you specify remove, we can use the value * to remove all attributes.
    • When you specify display, we can use the value * to display all attributes which have been defined. This value only displays the attributes which have been defined and not the complete list of valid attributes.
    • If we use remove to delete the only attribute in a stanza, the stanza itself is deleted.
    • Any modification you make to the Registry re-secures all IBM MQ Registry entries.


Examples

The following example adds an XAResourceManager to queue manager TEST. The commands issued are: 
amqmdain reg TEST -c add -s XAResourceManager\Sample -v SwitchFile=sf1
amqmdain reg TEST -c add -s XAResourceManager\Sample -v ThreadOfControl=THREAD
amqmdain reg TEST -c add -s XAResourceManager\Sample -v XAOpenString=openit
amqmdain reg TEST -c add -s XAResourceManager\Sample -v XACloseString=closeit
To display the values set by the commands, use: 
amqmdain reg TEST -c display -s XAResourceManager\Sample -v *
The display would look something like the following: 
0784726, 5639-B43 (C) Copyright IBM Corp. 1994, 2020. ALL RIGHTS RESERVED.
Displaying registry value for Queue Manager 'TEST'
        Attribute = Name, Value = Sample
        Attribute = SwitchFile, Value = sf1
        Attribute = ThreadOfControl, Value = THREAD
        Attribute = XAOpenString, Value = openit
        Attribute = XACloseString, Value = closeit
To remove the XAResourceManager from queue manager TEST, use: 
amqmdain reg TEST -c remove -s XAResourceManager\Sample -v *


Return codes

Return code Description
0 Command completed normally
-2 Syntax error
-3 Failed to initialize MFC
-6 Feature no longer supported
-7 Configuration failed
-9 Unexpected Registry error
-16 Failed to configure service principal name
-29 Inconsistent use of installations detected
62 The queue manager is associated with a different installation
71 Unexpected error
119 Permission denied (Windows only)
Note:
  1. If the qmgr start QMgrName command is issued, all return codes that can be returned with strmqm, can be returned here also. For a list of these return codes, see strmqm (start queue manager).
  2. If the qmgr end QMgrName command is issued, all return codes that can be returned with endmqm, can be returned here also. For a list of these return codes, see endmqm (end queue manager).