crtmqm
Create a queue manager.
Purpose
Use the crtmqm command to create a queue manager and define the default and system objects. The objects created by the crtmqm command are listed in System and default objects. When you have created a queue manager, use the strmqm command to start it.
The queue manager is automatically associated with the installation from which the crtmqm command was issued. To change the associated installation, use the setmqm command. Note that the Windows installer does not automatically add the user that performs the installation to the mqm
group. For more details, see Authority to administer IBM® MQ on UNIX, Linux® and Windows systems.
Syntax
Required parameters
QMgrName
-
The name of the queue manager that you want to create. The name can contain up to 48 characters. This parameter must be the last item in the command.
Note: The QMgrName is used by IBM MQ applications, other IBM MQ queue managers, and IBM MQ control commands to identify this queue manager.
No other queue manager with the same name can exist on this machine. Where this queue manager is going to connect to other queue managers you must ensure that queue manager names are unique within that group of queue managers.
The QMgrName is also used to name the directories created on disk for the queue manager. Due to filesystem limitations the name of the directories created might not be identical to the QMgrName supplied on the crtmqm command.
In these cases the directories created will be based upon the supplied QMgrName, but might be modified, or have a suffix such as
.000
or.001
, and so on, added to the queue manager name.
Optional parameters
- -a[r] access_group
- Use the access group parameter to specify a Windows security group, members of which will be granted full access to all queue manager data files. The group can either be a local or global group, depending on the syntax used.
Valid syntax for the group name is as follows:
- LocalGroup
- Domain name\GlobalGroup name
- GlobalGroup name @ Domain name
You must define the additional access group before running the crtmqm command with the -a [r] option.
If you specify the group using -ar instead of -a , the local
mqm
group is not granted access to the queue manager data files. Use this option if the file system hosting the queue manager data files does not support access control entries for locally defined groups.The group is typically a global security group, which is used to provide multi-instance queue managers with access to a shared queue manager data and logs folder. Use the additional security access group to set read and write permissions on the folder or to share containing queue manager data and log files.
The additional security access group is an alternative to using the local group named
mqm
to set permissions on the folder containing queue manager data and logs. Unlike the local groupmqm
, you can make the additional security access group a local or a global group. It must be a global group to set permissions on the shared folders that contain the data and log files used by multi-instance queue managers.The Windows operating system checks the access permissions to read and write queue manager data and log files. It checks the permissions of the user ID that is running queue manager processes. The user ID that is checked depends on whether you started the queue manager as a service or you started it interactively. If you started the queue manager as a service, the user ID checked by the Windows system is the user ID you configured with the Prepare IBM MQ wizard. If you started the queue manager interactively, the user ID checked by the Windows system is the user ID that ran the strmqm command.
The user ID must be a member of the local
mqm
group to start the queue manager. If the user ID is a member of the additional security access group, the queue manager can read and write files that are given permissions by using the group.Restriction: You can specify an additional security access group only on Windows operating system. If you specify an additional security access group on other operating systems, the crtmqm command returns an error. - -c Text
- Descriptive text for this queue manager. You can use up to 64 characters; the default is all blanks.
If you include special characters, enclose the description in single quotation marks. The maximum number of characters is reduced if the system is using a double-byte character set (DBCS).
- -d DefaultTransmissionQueue
- The name of the local transmission queue where remote messages are put if a transmission queue is not explicitly defined for their destination. There is no default.
- -g ApplicationGroup
- The name of the group that contains members that are allowed to perform the following actions:
- Run MQI applications
- Update all IPCC resources
- Change the contents of some queue manager directories
This option applies to IBM MQ for AIX®, Solaris, HP-UX, and Linux.
The default value is -g all , which allows unrestricted access.
The -g
ApplicationGroup
value is recorded in the queue manager configuration file named, qm.ini.The
mqm
user ID and the user running the command must belong to the specified Application Group. For further details of the operation of restricted mode, see Restricted mode. - -h MaximumHandleLimit
- The maximum number of handles that an application can open at the same time.
Specify a value in the range 1 - 999999999. The default value is 256.
The next set of parameter descriptions relate to logging, which is described in Using the log for recovery.
- -lc
- Use circular logging. This method is the default logging method.
- -ld LogPath
- The directory used to store log files. The default directory to store log paths is defined when you install IBM MQ.
If the volume containing the log file directory supports file security, the log file directory must have access permissions. The permissions allow the user IDs, under whose authority the queue manager runs, read and write access to the directory and its subdirectories. When you install IBM MQ, you grant permissions to the user IDs and to the
mqm
group on the default log directory. If you set the LogPath parameter to write the log file to a different directory, you must grant the user IDs permission to read and write to the directory. The user ID and permissions for UNIX and Linux are different from those for the Windows system:- UNIX and Linux
- The directory and its subdirectories must be owned by the user
mqm
in the groupmqm
.If the log file is shared between different instances of the queue manager, the security identifiers (sid) that are used must be the same for the different instances. You must have set the user
mqm
to the samesid
on the different servers running instances of the queue manager. Likewise for the groupmqm
. - Windows
- If the directory is accessed by only one instance of the queue manager, you must give read and write access permission to the directory for the following groups and users:
- The local group
mqm
- The local group
Administrators
- The
SYSTEM
user ID
To give different instances of a queue manager access to the shared log directory, the queue manager must access the log directory using a global user. Give the global group, which contains the global user, read and write access permission to the log directory. The global group is the additional security access group specified in the -a parameter.
- The local group
In IBM MQ for Windows systems, the default directory is
C:\ProgramData\IBM\MQ\log
(assuming that C is your data drive). If the volume supports file security, the SYSTEM ID, Administrators, andmqm
group must be granted read/write access to the directory.In IBM MQ for UNIX and Linux systems, the default directory is
/var/mqm/log
. User IDmqm
and groupmqm
must have full authorities to the log files.If you change the locations of these files, you must give these authorities yourself. If these authorities are set automatically, then the log files are in their default locations.
- -lf LogFilePages
- The log data is held in a series of files called log files. The log file size is specified in units of 4 KB pages.
In IBM MQ for UNIX and Linux systems, the default number of log file pages is 4096, giving a log file size of 16 MB. The minimum number of log file pages is 64 and the maximum is 65535.
In IBM MQ for Windows systems, the default number of log file pages is 4096, giving a log file size of 16 MB. The minimum number of log file pages is 32 and the maximum is 65535.
Note: The size of the log files for a queue manager specified during creation of that queue manager cannot be changed. - -ll LinearLogging
- Use linear logging.
- -lp LogPrimaryFiles
- The log files allocated when the queue manager is created.
On a Windows system, the minimum number of primary log files you can have is 2 and the maximum is 254. On UNIX and Linux systems, the minimum number of primary log files you can have is 2 and the maximum is 510. The default is 3.
On a Windows system, the total number of primary and secondary log files must not exceed 255 and must not be less than 3. On UNIX and Linux systems the total number of primary and secondary log files must not exceed 511 and must not be less than 3.
Operating system limits can reduce the maximum log size.
The value is examined when the queue manager is created or started. You can change it after the queue manager has been created. However, a change in the value is not effective until the queue manager is restarted, and the effect might not be immediate.
For more information about primary log files, see What logs look like.
To calculate the size of the primary log files, see Calculating the size of the log.
- -ls LogSecondaryFiles
- The log files allocated when the primary files are exhausted.
On a Windows system, the minimum number of secondary log files you can have is 1 and the maximum is 253. On UNIX and Linux systems, the minimum number of secondary log files you can have is 2 and the maximum is 509. The default is 2.
On a Windows system, the total number of primary and secondary log files must not exceed 255 and must not be less than 3. On UNIX and Linux systems the total number of primary and secondary log files must not exceed 511 and must not be less than 3.
Operating system limits can reduce the maximum log size.
The value is examined when the queue manager is started. You can change this value, but changes do not become effective until the queue manager is restarted, and even then the effect might not be immediate.
For more information about the use of secondary log files, see What logs look like.
To calculate the size of the secondary log files, see Calculating the size of the log.
- -md DataPath
- The directory used to hold the data files for a queue manager.
In IBM MQ for Windows systems, the default is
C:\ProgramData\IBM\MQ\qmgrs
(assuming that C: is your data drive). If the volume supports file security, the SYSTEM ID, Administrators, andmqm
group must be granted read/write access to the directory.In IBM MQ for UNIX and Linux systems, the default is
/var/mqm/qmgrs
. User IDmqm
and groupmqm
must have full authorities to the log files.The
DataPath
parameter is provided to assist in the configuration of multi-instance queue managers. For example, on UNIX and Linux systems: if the/var/mqm
directory is located on a local file system, use theDataPath
parameter and theLogPath
parameter to point to the shared file systems accessible to multiple queue managers.Note: A queue manager created usingDataPath
parameter runs on versions of IBM MQ earlier than Version 7.0.1, but the queue manager must be reconfigured to remove theDataPath
parameter. You have two options to restore the queue manager to a pre-Version 7.0.1 configuration and run without theDataPath
parameter: If you are confident about editing queue manager configurations, you can manually configure the queue manager using the Prefix queue manager configuration parameter. Alternatively, complete the following steps to edit the queue manager:- Stop the queue manager.
- Save the queue manager data and log directories.
- Delete the queue manager.
- Backout IBM MQ to the pre-v7.0.1 fix level.
- Create the queue manager with the same name.
- Replace the new queue manager data and log directories with the ones you saved.
- -oa group | user
- On UNIX and Linux systems, you can specify whether group or user authorization is to be used. If you do not set this parameter, group authorization is used. You can change the authorization model later by setting the SecurityPolicy parameter in the Service stanza of the qm.ini file (see Service stanza format ).
For further information, see Object authority manager (OAM).
- -p PortNumber
- Create a managed TCP listener on the specified port.
Specify a valid port value in the range 1-65535, to create a TCP listener object that uses the specified port. The new listener is called SYSTEM.LISTENER.TCP.1. This listener is under queue manager control, and is started and stopped along with the queue manager.
- -q
- Makes this queue manager the default queue manager. The new queue manager replaces any existing default queue manager.
If you accidentally use this flag and you want to revert to an existing queue manager as the default queue manager, change the default queue manager as described in Making an existing queue manager the default.
- -sa
- Automatic queue manager startup. For Windows systems only.
The queue manager is configured to start automatically when the IBM MQ Service starts.
This is the default option if you create a queue manager from MQ Explorer.
Queue managers created in IBM MQ releases earlier than Version 7 retain their existing startup type.
- -sax
- Automatic queue manager startup, permitting multiple instances. For Windows systems only.
The queue manager is configured to start automatically when the IBM MQ Service starts.
If an instance of the queue manager is not already running the queue manager starts, the instance becomes active, and standby instances are permitted elsewhere. If a queue manager instance that permits standbys is already active on a different server, the new instance becomes a standby instance.
Only one instance of a queue manager can run on a server.
Queue managers created in IBM MQ versions earlier than Version 7.0.1 retain their existing startup type.
- -si
- Interactive (manual) queue manager startup.
The queue manager is configured to start only when you manually request startup by using the strmqm command. The queue manager runs under the (interactive) user when that user is logged-on. Queue managers configured with interactive startup end when the user who started them logs off.
- -ss
- Service (manual) queue manager startup.
A queue manager configured to start only when manually requested by using the strmqm command. The queue manager then runs as a child process of the service when the IBM MQ Service starts. Queue managers configured with service startup continue to run even after the interactive user has logged off.
This is the default option if you create a queue manager from the command line.
- -t IntervalValue
- The trigger time interval in milliseconds for all queues controlled by this queue manager. This value specifies the length of time triggering is suspended, after the queue manager receives a trigger-generating message. That is, if the arrival of a message on a queue causes a trigger message to be put on the initiation queue, any message arriving on the same queue within the specified interval does not generate another trigger message.
You can use the trigger time interval to ensure that your application is allowed sufficient time to deal with a trigger condition before it is alerted to deal with another trigger condition on the same queue. You might choose to see all trigger events that happen; if so, set a low or zero value in this field.
Specify a value in the range 0 - 999999999. The default is 999999999 milliseconds; a time of more than 11 days. Allowing the default to be used effectively means that triggering is disabled after the first trigger message. However, an application can enable triggering again by servicing the queue using a command to alter the queue to reset the trigger attribute.
- -u DeadLetterQueue
- The name of the local queue that is to be used as the dead-letter (undelivered-message) queue. Messages are put on this queue if they cannot be routed to their correct destination.
The default is no dead-letter queue.
- -x MaximumUncommittedMessages
- The maximum number of uncommitted messages under any one sync point. The uncommitted messages are the sum of:
- The number of messages that can be retrieved from queues
- The number of messages that can be put on queues
- Any trigger messages generated within this unit of work
This limit does not apply to messages that are retrieved or put outside a sync point.
Specify a value in the range 1 - 999999999. The default value is 10000 uncommitted messages.
- -z
- Suppresses error messages.
This flag is used within IBM MQ to suppress unwanted error messages. Do not use this flag when using a command line. Using this flag can result in a loss of information.
Return codes
Return code | Description |
---|---|
0 | Queue manager created |
8 | Queue manager exists |
39 | Invalid parameter specified |
49 | Queue manager stopping |
58 | Inconsistent use of installations detected |
69 | Storage unavailable |
70 | Queue space unavailable |
71 | Unexpected error |
72 | Queue manager name error |
74 | The IBM MQ service is not started. |
100 | Log location invalid |
111 | Queue manager created. However, there was a problem processing the default queue manager definition in the product configuration file. The default queue manager specification might be incorrect. |
115 | Invalid log size |
119 | Permission denied ( Windows only) |
Examples
- The following command creates a default queue manager called
Paint.queue.manager
, with a description ofPaint shop
, and creates the system and default objects. It also specifies that linear logging is to be used:crtmqm -c "Paint shop" -ll -q Paint.queue.manager
- The following command creates a default queue manager called
Paint.queue.manager
, creates the system and default objects, and requests two primary and three secondary log files:crtmqm -c "Paint shop" -ll -lp 2 -ls 3 -q Paint.queue.manager
- The following command creates a queue manager called
travel
, creates the system and default objects, sets the trigger interval to 5000 milliseconds (5 seconds), and specifiesSYSTEM.DEAD.LETTER.QUEUE
as its dead-letter queue.crtmqm -t 5000 -u SYSTEM.DEAD.LETTER.QUEUE travel
- The following command creates a queue manager called
QM1
on UNIX and Linux systems, which has log and queue manager data folders in a common parent directory. The parent directory is to be shared on highly available networked storage to create a multi-instance queue manager. Before issuing the command, create other parameters /MQHA, /MQHA/logs and /MQHA/qmgrs owned by the user and groupmqm
, and with permissionsrwxrwxr-x
.crtmqm -ld /MQHA/logs -md /MQHA/qmgrs QM1