Automatic configuration from an MQSC script at startup

From IBM MQ Version 9.2.0, we can configure your queue manager to automatically apply the contents of an MQSC script, or set of MQSC scripts, on every queue manager start.

We can use this functionality to have a configuration which can be modified, and automatically replayed at the next queue manager restart. As an example, if the script or scripts are located on a mounted drive, it is possible to have a centralized configuration where the latest version gets applied to every queue manager as they start.

A particular scenario in which this can be useful, is to ensure a uniform cluster contains the same definitions on all queue managers in the cluster, by having a single set of configuration which they all apply. For an example of this, see Create a new uniform cluster.

Before starting

1. A single script, and create a text file using MQSC commands.
2. A set of MQSC scripts:
   • To identify a directory where the configurations will exist, and
   • In that directory, create files, each with the extension .mqsc, for example queues.mqsc.

Given that this script is reapplied on every queue manager start, it is important that commands can be replayed. For example, a DEFINE command must include the REPLACE string, otherwise the command appears as a failure on the second queue manager start, as the object already exists.

Note that in an MQSC script, any line prefixed with * is treated as a comment.

Enable automatic configuration of MQSC scripts

We can configure a new queue manager by using the -ic flag to the crtmqm command, and pointing either at a specific file, or directory. The supplied value is stored in the qm.ini file under the AutoConfig stanza, as attribute MQSCConfig.

AutoConfig:
   MQSCConfig=C:\mq_configuration\uniclus.mqsc

How does automatic configuration work?

During queue manager startup, the configuration identified by the AutoConfig stanza attribute MQSCConfig is passed through runmqsc validation, to ensure valid syntax, and then stored in the queue manager data tree into the autocfg directory as a single file cached.mqsc.

When multiple files from a directory are processed in, they are processed in alphabetical order, and if it contains an MQSC end or quit command, the rest of the contents of that file are skipped.

During the first ever start of the queue manager, an inability to read the file or directory, or a file with MQSC syntax that is not valid, prevents the queue manager from starting, with an appropriate error message both to the console and to the queue manager error log.

On subsequent restarts, if the file or directory pointed to is unreadable or contains invalid MQSC syntax, the previously cached file is used and a message written to the error log of the queue manager highlights this.

At the point the queue manager is enabled for applications to connect, the contents of the cached.mqsc are applied to the queue manager. The runmqsc log of the configuration being applied is stored in the errors directory of the queue manager, as a file called autocfgmqsc.LOG.

In addition, any MQSC command that does not complete successfully, is logged to the queue manager error log, identifying why the command fails.