This is part of an occasional series of small blog posts where I (Morag) will write about some of the quirks in IBM MQ, in the hope of invoking the response, "Well, I didn't know that!" Read other posts in this series.

I came across this behaviour the other day, and didn't know what it meant. We guessed a possible meaning, then looked it up in the IBM MQ docs, and we were right. However, it was new to me, so maybe it will be new to some of you, and therefore definitely worth a little blog post for awareness.

I was writing a multi-threaded application, and wanted to verify that certain queues were being opened by different threads or the same threads, depending on different scenarios.

I started by using the following command:-

DISPLAY QSTATUS(APP.*) TYPE(HANDLE) WHERE(APPLTAG EQ 'My Appl Name') PID TID

What I got then was output like the following:-

QUEUE(APP.Q1) TYPE(HANDLE) APPLTAG(My Appl Name) INPUT(SHARED) OUTPUT(NO)  PID(20292) TID(*)
QUEUE(APP.Q2) TYPE(HANDLE) APPLTAG(My Appl Name) INPUT(NO)     OUTPUT(YES) PID(20292) TID(*)
QUEUE(APP.Q3) TYPE(HANDLE) APPLTAG(My Appl Name) INPUT(SHARED) OUTPUT(NO)  PID(20292) TID(*)

This didn't help me! I tried the following command instead:-

DISPLAY CONN(*) TYPE(ALL) WHERE(APPLTAG EQ 'My Appl Name') PID TID OBJNAME

And then I could see the actual TID values (I've snipped a fair bit of excess out of this output to show you here.

CONN(AD3A706900320240) PID(20292) TID(3) APPLTAG(My Appl Name)
                       OBJNAME(APP.Q1) OPENOPTS(MQOO_INPUT_SHARED)
                       OBJNAME(APP.Q2) OPENOPTS(MQOO_OUTPUT)
CONN(AD3A706900320240) PID(20292) TID(1) APPLTAG(My Appl Name)
                       OBJNAME(APP.Q3) OPENOPTS(MQOO_INPUT_SHARED)

This TID(*) output was new to me. I had never noticed that before. I am used to DISPLAY commands using an asterisk to match upon multiple objects, and also I am used to seeing MCAUSER(*) to suggest that this channel has more than one connection sharing it and they have different MCAUSER values (I even wrote about it here). But in this situation, there was only one thread involved, what was the asterisk trying to tell me?

Anyway, after a little pondering, we came up with a guess that when checked against the IBM MQ docs, turned out to be correct. It means that this object handle is made using a connection handle that is shared, so the thread that it is being used on might have more possible values.

DISPLAY QSTATUS

TID

Number specifying the thread identifier within the application process that has opened the specified queue.

This parameter is not valid on z/OS.

An asterisk indicates that this queue was opened using a shared connection.

For further information about shared connections see Shared (thread independent) connections with MQCONNX.

If you make your connection handle without using any of the MQCNO_HANDLE_SHARE options, then the TID will indeed show up on the QSTATUS output. Changing my application in this way, and then re-running the command, I now see the following output.

QUEUE(APP.Q1) TYPE(HANDLE) APPLTAG(My Appl Name) INPUT(SHARED) OUTPUT(NO)  PID(20292) TID(3)
QUEUE(APP.Q2) TYPE(HANDLE) APPLTAG(My Appl Name) INPUT(NO)     OUTPUT(YES) PID(20292) TID(3)
QUEUE(APP.Q3) TYPE(HANDLE) APPLTAG(My Appl Name) INPUT(SHARED) OUTPUT(NO)  PID(20292) TID(1)

If you view Queue Status through a tool that uses PCF, such as MQ Explorer, MO71 or the MQ Console, then this same behaviour will be shown as a value of zero, rather than an asterisk.

Inquire Queue Status

ThreadId (MQCFIN)

The thread ID of the open application (parameter identifier: MQIACF_THREAD_ID).

A value of zero indicates that the handle was opened by a shared connection. A handle created by a shared connection is logically open to all threads.

So, now I know, and now so do you.

#mquirks
#IBMMQ
#IBMChampion