IBM MQ Family

IBM MQ Little Gem #13: mqclient.ini

By Morag Hughson posted 06-22-2016 02:41 PM

  
This is part of a series of small blog posts which will cover some of the smaller, perhaps less likely to be noticed, features of IBM MQ. Read other posts in this series.

MQ Client applications which run on machines where there is no queue manager are a common deployment. I'm sure you're all familiar with them. There are a number of different way to configure them from the simple MQSERVER environment variable to the full function CCDT. Depending on which mechanism you use, you end up setting a variety of different environment variables.

A simple client application might only need the MQSERVER environment variable.

set MQSERVER=SYSTEM.ADMIN.SVRCONN/TCP/win4.mqgem.com(1727)

A full function client using SSL/TLS might have several different ones set.

set MQCHLLIB=C:\MQGem
set MQCHLTAB=MQGEM.TAB
set MQSSLKEYR=C:\MQGem\key
set MQCERTLABL=MQGemClient
set MQSSLRESET=5000000

When deploying a change to a client application that requires some different environment variables to be set, it can be problematic to ensure that all the correct ones are set. What would be useful is if all these items could be put into one file and them when a change was required, a new copy of the file could be provided. Since the location of the file could be set up correctly when the application was first deployed, it wouldn't have to change, but the contents could be easily changed on subsequent deployments.

mqclient ini V9.jpgWell, you're in luck, since all the environment variables you see examples of above, and more, can alternatively be set in an mqclient.ini file.

The mqclient.ini file can be located in one of a number of different places, for example the working directory of the application - the full list of locations is detailed in Location of the client configuration file.

Here are the same requirements from above, showing what the contents of the mqclient.ini file would look like.

A simple client application might only need the ServerConnectionParms.

CHANNELS:
  ServerConnectionParms=SYSTEM.ADMIN.SVRCONN/TCP/win4.mqgem.com(1727)

A full function client using SSL/TLS might have several different settings.

CHANNELS:
  ChannelDefinitionDirectory=C:\MQGem
  ChannelDefinitionFile=MQGEM.TAB
SSL:
  SSLKeyRepository=C:\MQGem\key
  CertificateLabel=MQGemClient
  SSLKeyResetCount=500000

I've written about the mqclient.ini file before with a table of all the environment variables and their equivalent mqclient.ini file representations. Here's the table again, this time showing all mqclient.ini file attributes (not all of which have environment variables) and updated for IBM MQ V9. I've also included a column to show which things are also taken notice of by the Java and managed .Net clients (everything is used by the C Client, and thus the unmanaged .NET client); and a column showing any attributes that were introduced in V8 or V9, everything not otherwise noted is available in V7.0.0 and above which is when the mqclient.ini file was first introduced.

So, consider using an mqclient.ini file when deploying your next new client application and save yourself time in the future.

mqclient.ini Environment Variable Description Used by Ver
stanza:
  value
Java JMS .NET
CHANNELS:
   CCSID MQCCSID The coded character set number to be used
ChannelDefinitionDirectory MQCHLLIB The directory path to the file containing the CCDT. Combine with ChannelDefinitionFile for the equivalent to the MQCCDTURL environment variable.
MQCCDTURL V9
ChannelDefinitionFile MQCHLTAB The name of the file containing the CCDT
ReconDelay Configurable delay for client reconnect attempts V701
DefRecon Whether client reconnection is to be used V701
MQReconnectTimeout The total period for which client reconnect will be attempted V701
ServerConnectionParms MQSERVER The location of the MQ server and the communication method to be used
Put1DefaultAlwaysSync Control over Asynchronous put for MQPUT1 calls
PasswordProtection Control over Password protection algorithm negotiation V8
ClientExitPath:
ExitsDefaultPath Path for exits for 32-bit clients
ExitsDefaultPath64 Path for exits for 64-bit clients
JavaExitsClassPath Class path additions for Java exits
MessageBuffer:
MaximumSize Read-ahead client side buffer
PurgeTime Read-ahead buffer messages are purged after this interval
UpdatePercentage Control over how much reading ahead is done
SSL:
CDPCheckExtensions Whether to check CrlDistributionPoint servers for revoked certificates V7.1
CertificateLabel MQCERTLABL Defines the certificate label V8
CertificateValPolicy MQCERTVPOL Determines the type of certificate validation used V7.1
FP2
ClientRevocationChecks Controls client side certificate revocation checking V8
EncryptionPolicySuiteB MQSUITEB Whether Suite B compliant cryptography is to be used V7.1
OCSPAuthentication Controls client side OCSP checking behaviour V701
OCSPCheckExtensions Controls whether the client acts on AIA certificate extensions V701
SSLCryptoHardware MQSSLCRYP The parameter string required to configure PKCS #11 cryptographic hardware
SSLFipsRequired MQSSLFIPS Whether only FIPS-certified algorithms are to be used
SSLHTTPProxyName MQSSLPROXY The HTTP Proxy server that is to be used by GSKit for OCSP checks
SSLKeyRepository MQSSLKEYR The location of the key repository that holds the user's digital certificate
SSLKeyResetCount MQSSLRESET The number of unencrypted bytes sent and received before the secret key is renegotiated
JMQI: (not used by 'C' or .NET clients)
useMQCSPauthentication Controls choice of Compatibility mode or MQCSP authentication mode for user ID and password authentication. V8
TCP:
ClntRcvBuffSize TCP/IP receive buffer size
ClntSndBuffSize TCP/IP send buffer size
Connect_Timeout MQTCPTIMEOUT How long MQ waits for a TCP connect call
IPAddressVersion MQIPADDRV Specifies which IP protocol to use for a channel connection
KeepAlive Controls Keep Alive function
PreConnect:
Data PreConnect Exit Data V701
Function PreConnect Exit Entry Point Name V701
Module PreConnect Exit Module V701
Sequence PreConnect Exit Sequence Number V701

Morag Hughson is an MQ expert. She spent 18 years in the MQ Devt organisation before taking on her current job writing MQ Technical education courses with MQGem. She also blogs for MQGem. You can connect with her here on IMWUC or on Twitter and LinkedIn.
9 comments
10 views

Permalink

Comments

06-21-2017 07:12 PM

JMQI Stanza added

Added a row to cover the JMQI stanza attribute now that it is publicly acknowledged in IBM Knowledge Center.

05-16-2017 12:27 AM

Added extra column and more ticks

Added a JMS column, since Java and JMS are not identical w.r.t. their use of mqclient.ini, and added ticks for Put1DefaultAlwaysSync, DefRecon, PasswordProtection and ReconDelay, as a result of interaction with the JMS Service team. Updates to IBM Knowledge Center are underway to document these.

03-29-2017 10:48 PM

Minor Update

Noted that PasswordProtection value in the CHANNELS stanza is paid attention to by the Java client as discovered by an MQ customer through a PMR.

07-08-2016 01:47 AM

Gone back a little further

Hi Peter,

I've taken it back to V7.0.0 which is where (I think) the mqclient.ini file was introduced. Certainly it wasn't around in V6 - you still had the qm.ini for use by the client then - but I'm not 100% certain whether it was V7.0.0 or V7.0.1 that created it since there's no V7.0.0 doc anymore :-(

Cheers
Morag

07-01-2016 06:46 AM

Thanks

It would still be useful to go back a couple more versions, as many sites do have out of date MQ clients (or are on extended support).

07-01-2016 06:40 AM

Version added

Peter, I have added a column showing the version. Most things have been around since at least V7.1. I haven't gone back any further back than that since beyond that is out of service.

07-01-2016 05:02 AM

Version needed?

Are all these variables available in all versions of the MQ client? If not could you please indicate the version that it is available from?

06-23-2016 12:52 AM

Thanks Katie

Thanks Katie - I'm glad to hear you found it useful.

Cheers,
Morag

06-22-2016 06:59 PM

Great Read

Thanks for this awesome resource!