MQ

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.

When the IBM MQ Multi-version install feature was created in MQ V7.1, the mqm libraries became "smart". That is, they were able to load the correct libraries for the version of queue manager you were connecting to, regardless of the version of the libraries you pointed at. At the same time, they became even smarter still by being able to make both locally bound connections and client channel connections (previously the remit of the mqic libraries).

The mqic libraries are still there, and still work just as they always did (after all you have applications linked to them so they couldn't be removed). But now, if you have need to convert an application which uses a locally bound connection, into one that uses a client channel connection, life is much simpler than it used to be.

Here's the old process (pre MQ V7.1)

• Re-link application to use mqic library instead of mqm library.
• Set MQSERVER environment variable, or point to a CCDT. Set other environment variables as well if using SSL/TLS.
• Run application and connect as a client.

Here's the new process (MQ V7.1 and later)

• Set MQ_CONNECT_TYPE environment variable.
• Set MQSERVER environment variable, or point to a CCDT. Set other environment variables as well if using SSL/TLS.
• Run application and connect as a client.

So instead of having to go to the trouble of re-linking an application, all you need to do is set a single environment variable that does the job instead.

You can even try this out using an MQ Sample. As I'm sure you know, IBM MQ supplies a number of sample programs, usually two versions of each in the bin directories, one which makes local binding connection and one which makes a client channel connection. The client version has the letter 'c' on the end of it's name. So for example, there is an amqsput and an amqsputc executable, both built from the amqsput0.c sample code.

To convert amqsput to run with a client connection, you can try following these steps.

1. Define a server-connection channel on your queue manager.
   DEFINE CHANNEL(MQGEM.SVRCONN) CHLTYPE(SVRCONN) DESCR('Channel to test converting amqsput to client connection')
2. Allow password protected connectivity over that server-connection channel.
   SET CHLAUTH(MQGEM.SVRCONN) TYPE(ADDRESSMAP) ADDRESS(client-machine-ip-address) USERSRC(MAP) MCAUSER('myuserid') CHCKCLNT(REQUIRED) DESCR('Channel to test converting amqsput to client connection')
3. Create a queue for the sample to use.
   DEFINE QLOCAL(MQGEM.Q) DESCR('Queue to test converting amqsput to client connection')
4. Grant group which 'myuserid' is in, the authorities needed to run amqsputc sample.
   • SET AUTHREC                  OBJTYPE(QMGR)  GROUP('mygroup') AUTHADD(CONNECT)
   • SET AUTHREC PROFILE(MQGEM.Q) OBJTYPE(QUEUE) GROUP('mygroup') AUTHADD(PUT)
5. Set the MQ_CONNECT_TYPE environment variable
   
   • On Windows: set MQ_CONNECT_TYPE=CLIENT
   • On UNIX: export MQ_CONNECT_TYPE=CLIENT
6. Set the MQSERVER environment variable
   • On Windows: set MQSERVER=MQGEM.SVRCONN/TCP/qmgr-machine-ip-address(qmgr-port-number)
   • On UNIX: export MQSERVER='MQGEM.SVRCONN/TCP/qmgr-machine-ip-address(qmgr-port-number)'
7. Configure the amqsput sample so that it prompts for a password
   
   • On Windows: set MQSAMP_USER_ID=myuserid
   • On UNIX: export MQSAMP_USER_ID='myuserid'
8. Run the amqsput sample and enter the password for 'myuserid' when prompted
   amqsput MQGEM.Q qmgr-name
9. Leave it running awaiting your input, and issue the following command on your queue manager to prove it is using a client connection.
   DISPLAY CHSTATUS(MQGEM.SVRCONN) ALL

Try both connection types

If you don't set the MQ_CONNECT_TYPE environment variable, the mqm library will in fact try both. First it will try a local connection to the given queue manager name. If that succeeds all is well. If that fails, it will then try to use any client connection settings that are around, e.g. MQSERVER environment variable or a CCDT if one can be found, to see if a client connection can be made to that queue manager.

Writing your own application

You can also make use of this feature in your own application code. Previously you had to make the decision of whether you wanted a client or local connection at link time (unless you went to the lengths of dynamically loading the libraries yourself). Now you can have a parameter to your code and can make the decision at run-time.

To do this your connection code has to use MQCONNX instead of MQCONN and would need to look as follows:

MQCNO   cno   = {MQCNO_DEFAULT};
MQHCONN hConn = MQHC_UNUSABLE_HCONN;
char    QMName[MQ_Q_MGR_NAME_LENGTH+1];
if (... parameter test for connection mode ...)
{
  cno.Options |= MQCNO_CLIENT_BINDING;
}
else
{
  cno.Options |= MQCNO_LOCAL_BINDING;
}  
MQCONNX(QMName,
        &cno,
        &hConn,
        &CompCode,
        &Reason);

You'd link your code with the mqm library, and then can choose at runtime whether you need a locally bound connection or a client channel connection.

You can read more about these MQCONNX options in the IBM Knowledge Center at Connecting to a queue manager using the MQCONNX call.