Using the application name in supported programming languages

Use this information to learn how the application name is selected in the various languages that IBM® MQ supports.

Recommended application name characters

Application names must be in the character set given by the CodedCharSetId attribute of the queue manager field. For more information on this attribute, see Attributes for the queue manager.

However, if the application is running as an IBM MQ MQI client, the application name must be in the character set and encoding of the client.

To ensure a smooth transition of the application name between queue managers, and to allow application resource monitoring through the resource monitoring topics, application names should contain only single-byte printable characters.
Notes:
  • You should also avoid the use of forward slash and ampersand characters in application names.
  • [MQ 9.3.0 Jun 2022]You should avoid use of the ampersand character in application names. System topic STATAPP metrics for application names containing an ampersand will not be produced.
This limits the name to:
  • Alphanumeric characters: A-Z, a-z, and 0-9
    Note: You should not use the lowercase a-z characters in application names on systems using EBCDIC Katakana.
  • The space character
  • Printable characters that are invariant in EBCDIC: + < = > % * ' ( ) , _ - . : ; ?
  • [MQ 9.3.0 Jun 2022]The / character. When subscribing to activity trace or STATAPP system topic metrics for an application whose name contains a forward slash, you must replace any forward slash characters with an ampersand character. For example, to receive STATAPP metrics for an application called "DEPT1/APPS/STOCKQUOTE" you must subscribe to the topic string "$SYS/MQ/INFO/QMGR/QMBASIC/Monitor/STATAPP/DEPT1&APPS&STOCKQUOTE/INSTANCE". The amqsact and amqsrua sample applications will automatically convert forward slash characters to ampersands when creating their subscriptions.

How you set the characters

The following table summarizes the means by which the application name is chosen in the various languages IBM MQ supports. The means by which the name is chosen is in order of precedence, highest first.
  C bindings and client Java bindings and client JMS bindings and client Managed .NET client Unmanaged .NET bindings and client Managed XMS client Unmanaged .XMS bindings and client
Connection property override   Java connection property override   .NET connection property override .NET connection property override    
Overridden property   Java overridden property   .NET overridden property .NET overridden property    
MQEnvironment   Java MQEnvironment   .NET MQEnvironment .NET MQEnvironment    
Connection factory property     Connection factory property     Connection factory property Connection factory property
JMSAdmin     JMSAdmin     JMSAdmin JMSAdmin
MQCNO Connection options            
Environment variable Environment variables       Environment variables   Environment variables
mqclient.ini

(Applicable to client connections only)

 Client connections       Client connections   Client connections
Java class name   Java class name Java class name        
Default name Default name     .NET Default name .NET Default name .NET Default name .NET Default name
Note: The C bindings and client column applies to the following programming languages as well:
  • COBOL
  • Assembler
  • Visual Basic
  • RPG

Programming language connections

Applications resolving to the IBM MQ libraries in C, and other programming languages, can provide the application name in the following ways.

The methods of connection are listed in order of precedence, starting with the highest.

[UNIX, Linux, Windows, IBM i]Connection options
  • [AIX, Linux, Windows]MQCNO
    [z/OS]Note: When connecting to an IBM MQ for z/OS® queue manager, you can only set the application name by using client mode connections, or by using IBM MQ classes for JMS or IBM MQ classes for Java applications.
  • [IBM i]MQCNO on IBM i
[AIX, Linux, Windows]Environment variables
If you have not yet selected an application name, you can use the MQAPPLNAME environment variable to identify the connection to the queue manager. For example:
export MQAPPLNAME=ExampleApplName
Note that the first 28 characters only are used, and these characters must not be all blanks or nulls.
Note: The attribute applies to the supported programming languages, unmanaged .NET, and unmanaged XMS connections only.
[AIX, Linux, Windows]Client configuration file
If the you have not yet selected an application name, and the connection is a client connection, you can specify the following information in the client configuration file (for example, mqclient.ini) to identify the connection to the queue manager. 

Connection:
	ApplName=ExampleApplName
Notes:
  1. The first 28 characters only are used, and these characters must not be all blanks or nulls.
  2. The attribute applies only to client connections on the supported programming languages, unmanaged .NET, and unmanaged XMS connections only.
For more information, see IBM MQ MQI client configuration file, mqclient.ini.

Default name

If you have still not chosen the application name, the default name continues to be used, which contains as much of the path and executable name as the operating system displays. For more information, see PutApplName.

Managed .NET applications

Managed .NET applications can provide the application name in the following ways.

The methods of connection are listed in order of precedence, starting with the highest.

Connection property override
You can provide a connection details override file to applications in the following way:

<appSettings>
     <add key="overrideConnectionDetails" value="true" />
     <add key="overrideConnectionDetailsFile" value="<location>" />
</appSettings>

The file specified by overrideConnectionDetailsFile contains a list of properties prefixed by mqj. Applications need to define the mqj.APPNAME property where the value of the mqj.APPNAME property specifies the name used to identify the connection to the queue manager.

Only the first 28 characters of the name are used. For example:
mqj.APPNAME=ExampleApplName

Overridden property
A constant MQC.APPNAME_PROPERTY has been defined with the value APPNAME. You can now pass this property to the MQQueueManager constructor, using the first 28 characters only of the name. For example:

Hashtable properties = new Hashtable();
properties.Add( MQC.APPNAME_PROPERTY, "ExampleApplName" );
MQQueueManager qMgr = new MQQueueManager("qmgrname", properties);

For more information, see Managed and unmanaged operations in .NET.

MQEnvironment
The AppName property is added to the MQEnvironmentclass, and the first 28 characters only are used. For example:
MQEnvironment.AppName = "ExampleApplName";

Default name

If you have not provided the application name by any of the means described in the preceding text, the application name is automatically set to be the executable name (and as much of the path that will fit).

XMS applications

The methods of connection are listed in order of precedence, starting with the highest.

Connection factory property

XMS applications can provide the application name on the connection factory using the XMSC.WMQ_APPLICATIONNAME property ("XMSC_WMQ_APPNAME") in a similar way to JMS. You can specify up to 28 characters.

For more information, see XMS .NET creating administered objects and Properties of an XMS message.

JMSAdmin

In the administrative tooling the property is known as "APPLICATIONNAME" or "APPNAME" for short.

Java and JMS bindings applications

The methods of connection are listed in order of precedence, starting with the highest.

[AIX, Linux, Windows]Java and JMS client applications can already specify an application name, and this has been extended on IBM MQ for Multiplatforms to bindings applications, by making use of the MQCNO ApplName field.

Connection property override
The Application name property has been added to the list of connection properties that you can override. For more information, see Using IBM MQ connection property override.
Attention: The connection properties and the way to use the Connection Property Override file is the same for both IBM MQ classes for Java and .NET.

Overridden property

A constant MQC.APPNAME_PROPERTY has been defined with the value APPNAME. You can now pass this property to the MQQueueManager constructor, using the first 28 characters only of the name. For more information, see Using connection property override in IBM MQ classes for Java.

MQEnvironment

The AppName property is added to the MQEnvironment class, and the first 28 characters only are used.

For more information, see Setting up the IBM MQ environment for IBM MQ classes for Java.

Java class name

If you have not provided the application name by any of the means in the preceding text, the application name is derived from the main class name.

For more information, see Setting up the IBM MQ environment for IBM MQ classes for Java.

[IBM i]Attention: On IBM i it is not possible to query the main class name, so IBM MQ client for Java is used instead.