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; see attributes for the queue manager for details of this attribute.

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 [MQ 9.2.0 Jul 2020]

, 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.
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: + < = > % * ' ( ) , _ - . : ; ?
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.

Connection options

MQCNO
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.
MQCNO on IBM i

Environment variables

If the you have not yet selected an application name, you can use the following environment variable, MQAPPLNAME, to identify the connection to the queue manager. For example:

export MQAPPLNAME=ExampleApplName

See Environment variables descriptions for more information.

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.

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 in the client configuration file ( for example mqclient.ini) to identify the connection to the queue manager.


Connection:
	ApplName=ExampleApplName

Notes:

The first 28 characters only are used, and these characters must not be all blanks or nulls.
The attribute applies only to client connections on the supported programming languages, Unmanaged .NET, and Unmanaged XMS connections only.

See Configuring a client using a configuration file for an example configuration file.

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. See PutApplName for more information.

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);

See Managed and unmanaged operations in .NET for more information.

MQEnvironment

The AppName property is added to the MQEnvironment class, 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 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”) similarly to JMS. You can specify up to 28 characters.

See XMS .NET creating administered objects and Properties of an XMS message for more information.

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. See Using IBM MQ connection property override for more information.

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

MQEnvironment

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

See Setting up the IBM MQ environment for IBM MQ classes for Java for more information.

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.

See Setting up the IBM MQ environment for IBM MQ classes for Java for more information.

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