Setting a custom application name in IBM MQ

Setting a custom application name in MQ v9.1.2

Mark Whitlock
Published on 09/04/2019

In MQ v9.1.2, applications on multiplatforms can set their application name programmatically or administratively. This enables applications to provide a more meaningful platform-independent name when you configure application activity trace or when output from various runmqsc commands. In the cloud, v9.1.2 adds the ability to rebalance applications across a uniform cluster. Providing meaningful names for your applications enables you to better administer this rebalancing. The behaviour on z/OS is slightly different, and is explained later.

Before v912 (and this part hasn’t changed)

The application name is output from….

• runmqsc DISPLAY CONN APPLTAG
• runmqsc DISPLAY QSTATUS TYPE(HANDLE) APPLTAG
• runmqsc DISPLAY CHSTATUS RAPPLTAG
• MQMD.PutApplName
• application activity trace

The application name is also used when configuring application activity trace. The default application name for non-java applications is the truncated name of the executable, except on Windows and iSeries. On Windows the default name is the fully qualified executable name, truncated to 28 characters on the left. On iSeries, the default name is the job name. For java applications it is the class name prefixed by the package name truncated on the left to 28 characters. See https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.ref.dev.doc/q097620_.htm

Various ways of setting the application name

Before v9.1.2, applications (except java clients) could not set their name, without renaming the executable. But in v9.1.2, C, JMS, base java, .NET and XMS .NET applications running in bindings and client modes can now set their application name. You can change your application to set the name by setting fields or properties. Or you can set the application name administratively using an environment variable, ini file, override file or in a connection factory in JNDI. Here are the tables for each language that show which methods of setting the name are available to which applications, and the order of precedence….

C

Java and JMS

.NET

XMS

The lowest precedence way of MQ discovering the application name is using the program name, and the highest precedence is using the connection property override. However the application name is set, it cannot be set to all blanks or nulls and will be truncated to 28 characters. The following descriptions explain the various ways of setting the application name, from lowest precedence to highest…

The application name can be set in the client configuration file mqclient.ini using the new ApplName attribute in the Connection stanza, for instance…

Connection:
ApplName=ExampleApplName

The application name can be set using the new environment variable, MQAPPLNAME, for instance….

export MQAPPLNAME=ExampleApplName

The application name can be set using the new CNO field ApplName. This is available in CNO version 7. For instance…

MQCNO cno = {MQCNO_DEFAULT};
cno.Version = MQCNO_VERSION_7;
strncpy(cno.ApplName, "ExampleApplName", 28);

The application name can be set in JNDI using the existing connection factory attribute APPLICATIONNAME or APPNAME for short. For instance….

InitCtx> define qcf(qma) appname(ExampleApplName)

InitCtx> display qcf(qma)

APPLICATIONNAME(ExampleApplName)
ASYNCEXCEPTION(CONNECTIONBROKEN)
COMPHDR(NONE )
COMPMSG(NONE )
CONNOPT(STANDARD)
FAILIFQUIESCE(YES)
MAPNAMESTYLE(STANDARD)
MSGBATCHSZ(10)
MSGRETENTION(YES)
POLLINGINT(5000)
PROVIDERVERSION(UNSPECIFIED)
QMANAGER()
RESCANINT(5000)
SENDCHECKCOUNT(0)
SHARECONVALLOWED(YES)
SYNCPOINTALLGETS(NO)
TARGCLIENTMATCHING(YES)
TEMPMODEL(SYSTEM.DEFAULT.MODEL.QUEUE)
TEMPQPREFIX()
TRANSPORT(BIND)
USECONNPOOLING(YES)
USERAUTHMQCSP(NO)
VERSION(7)
WILDCARDFORMAT(TOPIC_ONLY)

The application name can be set using the connection factory property XMSC.WMQ_APPLICATIONNAME or WMQConstants.WMQ_APPLICATIONNAME (for JMS)…

JmsFactoryFactory ff = JmsFactoryFactory.getInstance(WMQConstants.WMQ_PROVIDER);
JmsConnectionFactory cf = ff.createConnectionFactory();
cf.setStringProperty(WMQConstants.WMQ_APPLICATIONNAME, "ExampleApplName");

The application name can be set in the MQEnvironment using the APPNAME_PROPERTY, so for base java….

MQEnvironment.properties.put(MQConstants.APPNAME_PROPERTY, "ExampleApplName");

And for .NET…

MQEnvironment.AppName = "ExampleApplName";

The application name can be set by passing the APPNAME_PROPERTY to the queue manager constructor….

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

The application name can be set in a connection property override file using mqj.$APPNAME_PROPERTY in base java or mqj.APPNAME in XMS .NET. For instance, this can be done in base java by creating a javaapp.config that contains…

mqj.$APPNAME_PROPERTY=ExampleApplName

… and then invoking the application by setting -Dcom.ibm.mq.overrideConnectionDetails=true -Dcom.ibm.msg.client.config.location=javaapp.config as java overrides.
In XMS .NET, for instance, the application name can be set in a connection property override file that contains….

mqj.APPNAME=ExampleApplName

This connection property override file must be in the same directory as the .NET executable and called by the same name as the executable with a .props extension.

Valid characters

For bindings applications, names must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by MQENC_NATIVE. For client applications, names must be in the character set and encoding of the client. The queue manager does not police what characters are in the application name, so you could use any character in the name. But for client applications, the name is codepage translated when passed to the queue manager. Restricting the characters you use to A-Z, a-z, 0-9, space and + < = > % & * ‘ ( ) , _ – . / : ; ? ensures that the name will be codepage translated correctly.

z/OS support

Client applications running on multiplatforms connecting to a z/OS queue manager can set their application name in the ways described above. For C bindings applications, the new CNO.ApplName field is present, so applications that use it will build, but if the ApplName is set, it must be set to blanks (which will be ignored) otherwise the MQCONNX will return MQRC_CNO_ERROR. For JMS and base java bindings applications, setting the application name will be ignored and the name will default. The default application name is different between z/OS and multiplatforms and that hasn’t changed in v912. The name defaults to the batch job name, the TSO userid, the CICS APPLID or the IMS region name.

Other languages

Various other programming languages have bindings that enable applications written in them to connect to a queue manager and put and get messages. Some of these language bindings are shipped as supportpacs on MQ such as go and nodejs. Other language bindings are shipped by 3rd parties. In time these other language bindings may support ways of setting the application name programmatically. Whether or not such programmatic support is available, it should still be possible to set the application name adminstratively using the environment variable or (in client mode) mqclient.ini if those language bindings call the MQI C bindings to communicate with the queue manager.

In conclusion, v912 provides mechanisms to set an application’s name which can enable you to manage your MQ estate better and provides a step towards moving your queue managers into the cloud.