Rules for naming IBM MQ objects

IBM MQ object names have maximum lengths and are case-sensitive. Not all characters are supported for every object type, and many objects have rules concerning the uniqueness of names.

There are many different types of IBM MQ object, and objects from each type can all have the same name because they exist in separate object namespaces: For example, a local queue and a sender channel can both have the same name. However, an object cannot have the same name as another object in the same namespace: For example, a local queue cannot have the same name as a model queue, and a sender channel cannot have the same name as a receiver channel.

The following IBM MQ objects exist in separate object namespaces:

  • Authentication information
  • Channel
  • Client channel
  • Listener
  • Namelist
  • Process
  • Queue
  • Service
  • Storage class
  • Subscription
  • Topic


Character length of object names

In general, IBM MQ object names can be up to 48 characters long. This rule applies to the following objects:

  • Authentication information
  • Cluster
  • Listener
  • Namelist
  • Process definition
  • Queue
  • Queue manager
  • Service
  • Subscription
  • Topic

There are restrictions:

  1. On z/OS systems, queue managers must be a maximum of 4 characters, and must be in uppercase characters and numeric characters only.
  2. The maximum length of channel object names and client connection channel names is 20 characters. See Defining the channels for more information about channels.
  3. Topic strings can be a maximum of 10240 bytes. All IBM MQ object names are case-sensitive.
  4. Subscription names can be a maximum of 10240 bytes, and can contain spaces.
  5. The maximum length of storage class names is 8 characters.
  6. The maximum length of CF structure names is 12 characters.


Characters in object names

The valid characters for IBM MQ object names are:

Characters Restrictions
Uppercase A - Z

  • None

Lowercase a - z

  • In MQSC scripts, names with lowercase characters must be enclosed in single quotation marks. This prevents the lowercase characters being folded into uppercase.
  • Systems using EBCDIC Katakana cannot use lowercase a- z characters in object names.
  • There might be restrictions when using lowercase characters on z/OS systems, for example, queue manager names cannot contain lowercase characters.
  • On IBM i systems when using CL commands, names with lowercase characters must be enclosed in single quotation marks. This prevents the lowercase characters being folded into uppercase.

Numerics 0 - 9

  • None

Period (.)

  • None

Underscore (_)

  • None
  • Avoid using names with leading or trailing underscores because they cannot be handled by the IBM MQ for z/OS operations and control panels.

Forward slash (/)

  • On Windows systems, the first character of a queue manager name cannot be a forward slash.
  • On IBM i systems when using CL commands, names containing a forward slash must be enclosed in single quotation marks.
  • None

Percent sign (%)

  • None
  • If we are using RACF as the external security manager for IBM MQ for z/OS, do not use % in object names because the names are not included in security checks when RACF generic profiles are used.
  • On IBM i systems when using CL commands, names containing a percent sign must be enclosed in single quotation marks.

There are also some general rules concerning characters on object names:
  1. Leading or embedded blanks are not allowed.
  2. National language characters are not allowed.
  3. Any name that is less than the full field length can be padded to the right with blanks. All short names that are returned by the queue manager are always padded to the right with blanks.


Queue names

    The name of a queue has two parts:

    • The name of a queue manager
    • The local name of the queue as it is known to that queue manager

    Each part of the queue name is 48 characters long.

    To refer to a local queue, we can omit the name of the queue manager (by replacing it with blank characters or using a leading null character). However, all queue names returned to a program by IBM MQ contain the name of the queue manager.

    A shared queue, accessible to any queue manager in its queue sharing group, cannot have the same name as any non-shared local queue in the same queue sharing group. This restriction avoids the possibility of an application mistakenly opening a shared queue when it intended to open a local queue, or vice versa. Shared queues and queue sharing groups are only available on IBM MQ for z/OS.

    To refer to a remote queue, a program must include the name of the queue manager in the full queue name, or there must be a local definition of the remote queue.

    When an application uses a queue name, that name can be either the name of a local queue (or an alias to one) or the name of a local definition of a remote queue, but the application does not need to know which, unless it needs to get a message from the queue (when the queue must be local). When the application opens the queue object, the MQOPEN call performs a name resolution function to determine on which queue to perform subsequent operations. The significance of this is that the application has no built-in dependency on particular queues being defined at particular locations in a network of queue managers. Therefore, if a system administrator relocates queues in the network, and changes their definitions, the applications that use those queues do not need to be changed.


Reserved object names

Object names that start with SYSTEM. are reserved for objects defined by the queue manager. We can use the Alter, Define, and Replace commands to change these object definitions to suit your installation. The names that are defined for IBM MQ are listed in full in Queue names.

On IBM MQ for z/OS, the coupling facility application structure name CSQSYSAPPL is reserved.

Parent topic: Naming IBM MQ objects