What’s in Command Levels 90x

MQ90x StairsIBM MQ released Long Term Support release V9.0.0 back in June 2016 which had a Command Level of 900. The subsequent Continuous Delivery releases, V9.0.1, V9.0.2 and V9.0.3 have each introduced their own Command Levels, 901, 902 and 903 respectively.

This post captures the changes that are available in each of those Command Levels.

Release Command Level Features protected by Command Level – details below
V9.0.0.0 900 AMS Protection Policy enhancement – Confidentiality Policy
LDAP Authorization on Windows
V9.0.1 901 No changes protected by Command Level
V9.0.2 902 Log management features
V9.0.3 903 No changes protected by Command Level

AMS Protection Policy enhancement – Confidentiality Policy

With the introduction of Confidentiality Policies in Command Level 900, there is a new attribute on the Set Policy command. A confidentiality policy has no signature algorithm, but does have a encryption algorithm. The Key Reuse feature is applicable to this type of policy. Jon Rumsey has a great write-up of this IBM MQ V9 feature on the MQDev blog, MQ V9 Fast encrypted messages with MQ – Introducing AMS Confidentiality Policies.

AMS Policy

New Attribute MQSC name
See SET POLICY
Look for KC 9000 indicator
PCF constant and values
See Set Policy
Look for KC 9000 indicator
Key Reuse

KEYREUSE

  • DISABLED
  • UNLIMITED
  • 1 – 9999999

MQIA_KEY_REUSE_COUNT (267)

  • MQKEY_REUSE_DISABLED (0)
  • MQKEY_REUSE_UNLIMITED (-1)
  • 1 – 9999999

LDAP Authorization on Windows

Introduced in Command Level 801 on Unix, this feature extended the V8.0.0 Connection Authentication feature which checked your user ID and password, to allow LDAP authorization as well. The fields now available on Windows are the same as those noted in the earlier post for Command Level 801, and are not repeated here.

Log management

With the introduction of Automatic management of linear log extents, and Automatic writing of media images, in Command Level 902, there are new attributes on the queue manager object, queue manager status, and one on queue objects. Mark Whitlock has written about this in an MQDev Blog Post: Logger enhancements for MQ v9.0.2.

Queue Manager Object

New Attribute MQSC name
See ALTER QMGR
Look for KC 902 indicator
PCF constant and values
See Change Queue Manager
Look for KC 902 indicator
Image Schedule

IMGSCHED

  • AUTO
  • MANUAL

MQIA_MEDIA_IMAGE_SCHEDULING (268)

  • MQMEDIMGSCHED_AUTO (1)
  • MQMEDIMGSCHED_MANUAL (0)
Image Interval

IMGINTVL

  • 1 – 999 999 999
  • OFF

MQIA_MEDIA_IMAGE_INTERVAL (269)

  • 1 – 999 999 999
  • MQMEDIMGINTVL_OFF (0)
Image Log Length

IMGLOGLN

  • 1 – 999 999 999
  • OFF

MQIA_MEDIA_IMAGE_LOG_LENGTH (270)

  • 1 – 999 999 999
  • MQMEDIMGLOGLN_OFF (0)
Image Recover Object

IMGRCOVO

  • NO
  • YES

MQIA_MEDIA_IMAGE_RECOVER_OBJ (271)

  • MQIMGRCOV_NO (0)
  • MQIMGRCOV_YES (1)
Image Recover Queue

IMGRCOVQ

  • NO
  • YES

MQIA_MEDIA_IMAGE_RECOVER_Q (272)

  • MQIMGRCOV_NO (0)
  • MQIMGRCOV_YES (1)

Queue Manager Status

New Attribute MQSC name
See DISPLAY QMSTATUS
Look for KC 902 indicator
PCF constant and values
See Inquire Queue Manager Status
Look for KC 902 indicator
Archive Log Extent Name

ARCHLOG

MQCACF_ARCHIVE_LOG_EXTENT_NAME (3208)

  • String of length MQ_LOG_EXTENT_NAME_LENGTH (24)
Archive Log Size

ARCHSZ

MQIACF_ARCHIVE_LOG_SIZE (1416)

Media Log Size

MEDIASZ

MQIACF_MEDIA_LOG_SIZE (1417)

Restart Log Size

RECSZ

MQIACF_RESTART_LOG_SIZE (1418)

Reusable Log Size

REUSESZ

MQIACF_REUSABLE_LOG_SIZE (1419)

Archive Log In Use

LOGINUSE

MQIACF_LOG_IN_USE (1420)

Archive Log Utilization

LOGUTIL

MQIACF_LOG_UTILIZATION (1421)

Reset QMgr command

Updated attribute MQSC name
See RESET QMGR
Look for KC 902 indicator
PCF constant and values
See Reset Queue Manager
Look for KC 902 indicator
Action

TYPE

  • REDUCELOG
  • ARCHLOG

MQIACF_ACTION (1086)

  • MQACT_REDUCE_LOG (10)
  • MQACT_ARCHIVE_LOG (11)
Archived Log

ARCHIVED

MQCACF_ARCHIVE_LOG_EXTENT_NAME (3208)

  • String of length MQ_LOG_EXTENT_NAME_LENGTH (24)
Log Reduction

REDUCE

  • AUTO
  • ONE
  • MAX

MQIACF_LOG_REDUCTION (1422)

  • MQLR_AUTO (-1)
  • MQLR_ONE (1)
  • MQLR_MAX (-2)

Queue Local and Queue Model

New Attribute MQSC name
See DEFINE queues
Look for KC 902 indicator
PCF constant and values
See Change, Copy, and Create Queue
Look for KC 902 indicator
Image Recover Queue

IMGRCOVQ

  • NO
  • YES
  • QMGR

MQIA_MEDIA_IMAGE_RECOVER_Q (272)

  • MQIMGRCOV_NO (0)
  • MQIMGRCOV_YES (1)
  • MQIMGRCOV_AS_Q_MGR (2)

You can get the equivalent information for earlier Command Levels from these posts.

Advertisements

Creating a CCDT for any version

You may have read an earlier post where we described being able to determine what version of CCDT you had in your hand.

CCDT Version

How often have you had a CCDT file in your hand and wondered what version it was and whether you can give it to some of your known back-level client machines to use.

MQSCX can help you determine this. Open up your CCDT using the mqscx -n mode and then you can quite simply display the version number of all your client channels therein.

What you may not have realised from that post however, was that not only can MQSCX help to investigate what version number your CCDT is made for, it can also make a CCDT for the correct version as well. If you have back-level clients, it can be a real pain having to keep a queue manager of the same level around just to be able to create a CCDT that it will understand. Well, you can ditch that queue manager and use MQSCX instead. It’s really easy to do as well.

To use MQSCX to work with a CCDT, you need to use the -n parameter. This will then look for the CCDT file in the location specified by the MQCHLLIB and MQCHLTAB environment variables unless you provide the -t parameter to give it a specific file name. If one doesn’t exist, it will make a new one for you, and if one does exist it will read it and allow you to update it. In order to control the version of CCDT you are creating, you should additionally use the -V parameter which allows you to specify the version the CCDT file should be written as.

Here’s an example, run the MQSCX program like this:

mqscx -n -t C:\MQGem\CCDT\MQGEM.TAB -V7.0

And then you can use it to make DISPLAY, ALTER and DELETE commands.

MQSCX Extended MQSC Program – Version 8.0.0

CCDT commands directed to file ‘C:\MQGem\CCDT\MQGEM.TAB’

Licenced to Paul Clarke

Licence Location: Head Office

[12:02:10] DISPLAY CHANNEL(*) CONNAME VERSION

_________________________________________________

CHANNEL(MQG1.SVRCONN) CHLTYPE(CLNTCONN)

CONNAME(win12.mqgem.com(1602)) VERSION(8.0)

_________________________________________________

CHANNEL(MQG2.SVRCONN) CHLTYPE(CLNTCONN)

CONNAME(aix5.mqgem.com(4231)) VERSION(8.0)

_________________________________________________

CHANNEL(MQG3.SVRCONN) CHLTYPE(CLNTCONN)

CONNAME(mvs1.mqgem.com(1255)) VERSION(8.0)

_________________________________________________

Total display responses – Received:3

>

As you can see, at the moment all the channels in this CCDT are at V8.0 which means my V7.0 client won’t be able to read them. I need to make a change to each record to ensure MQSCX will write it out at version V7.0 as I have indicated on my start command. Helpfully, I can do that in one single command:-

ALTER CHANNEL(*)

This makes no actual change to the attributes of the channel definition, but does ‘touch’ each record to ensure that it gets the new version. Displaying the records again as above will show that the version number for each channel mentioned by the ALTER command (in this example all of them), now indicates it is at version V7.0, just what my back-level client application needs.

Exiting MQSCX and re-running it will show you that this earlier version of the CCDT has indeed been hardened.

Note that if you had been using some attributes introduced in later versions than V7.0, this information would be lost when altering the channel definition to be an earlier version.


If you’d like to try out MQSCX, please email support@mqgem.com to request a trial licence.

Be sure of your CCDT Version

CCDT VersionWe all know that you can’t use a CCDT file with a client that is older than the CCDT version. For example, a version 6 client can’t understand what the channel definitions in a V8 produced CCDT mean.

How often have you had a CCDT file in your hand and wondered what version it was and whether you can give it to some of your known back-level client machines to use.

MQSCX can help you determine this. Open up your CCDT using the mqscx -n mode and then you can quite simply display the version number of all your client channels therein.

DISPLAY CHANNEL(*) VERSION

CHANNEL(MQGEM.SVRCONN)            CHLTYPE(CLNTCONN)   VERSION(8.0)
CHANNEL(MQGEM.SVRCONN.SSL)        CHLTYPE(CLNTCONN)   VERSION(9.0)
CHANNEL(MQGEM.SVRCONN.ADMIN)      CHLTYPE(CLNTCONN)   VERSION(7.0)

Alternatively, you might like to write a little script that could iterate through all the channels in the table and tell you the minimum and maximum versions in use within that CCDT.

if (_ccdtmode)
  @minVer = 999999999
  @maxVer = 0
  foreach (DISPLAY CHANNEL(*) VERSION)
    if (VERSION < @minVer)
      @minVer = VERSION
    endif
    if (VERSION > @maxVer)
      @maxVer = VERSION
    endif
  endfor
  if (_numEach)
    print "Channel version in",_ccdt
    print "Minimum:",@minVer,"Maximum:",@maxVer
  else
    print "No channels found in",_ccdt
  endif
else
  print "Run this script with MQSCX in CCDT mode"
endif

Running this against a multi-version CCDT might produce output such as:-

Channel version in C:\MQGem\CCDT\MQGEM101.TAB
Minimum: 7.00 Maximum: 9.00

foreachThis type of CCDT analysis is possible due to the recent addition of the foreach construct to the CCDT processing in MQSCX.

If you are a current MQSCX licence holder, you can simply download the new version of MQSCX and start using it. If you’re not a current licence holder, and you’d like to try out MQSCX, please email support@mqgem.com to request a trial licence.

Scripts using foreach on the CCDT

foreachThere are different types of users who use MQSCX. Some like the interactive experience, with tab auto-complete of commands, keywords and objects names. Others like the ability to create and edit CCDT files suitable for any required version of IBM MQ. Others again like the powerful control language which makes writing scripts to interrogate your queue manager a breeze.

Freaking awesome, Paul! I wrote several reporting scripts for a customer a couple of months back. They declined to purchase MQSCX so I was forced to do much of the logic in the script, giving me I have a good basis for comparison of both approaches. The differential in lines of code, complexity and amount of additional billable time I spent would have paid for a site license for several years. The ROI is now more than doubled, possibly even 5x what it was.

User comment on MQSCX – see more at What our customers say

Sometimes those different use cases come together. The control language has a for loop concept where you can easily iterate over all the queue manager objects that are returned by the command server as the answer to an MQSC command, with a script something like this:-

@total = 0
foreach(DISPLAY QLOCAL(*) WHERE(CURDEPTH GT 0))
  @total = @total + CURDEPTH
endfor
print 'Total CURDEPTH =',@total

You can also write scripts that operate, not on queue manager objects, but on the contents of a CCDT file.

With the latest version of MQSCX, you can use the foreach construct on the items in your CCDT file in just same way as above. Here’s a small example:-

@ssl = 0;
foreach(DISPLAY CHANNEL(*) SSLCIPH)
  if (SSLCIPH)
    @ssl = @ssl + 1
  endif
endfor
print 'Found',@ssl,'SSL Channels out of',_numEach

Now with MQSCX V9.0.0 you can use the powerful control language to analyse and manipulate your CCDT files. Another example of using the foreach construct on a CCDT file can be see in Be sure of your CCDT Version


If you are a current MQSCX licence holder, you can simply download the new version of MQSCX and start using it. If you’re not a current licence holder, and you’d like to try out MQSCX, please email support@mqgem.com to request a trial licence.

Only run MQSC script on intended Queue Manager

Correct QMgr?IBM MQ is a robust product and queue managers can run without problems for months, or even years at a time. In fact, often when problems do occur they are the result of human error, and one example of such as error can be running an MQSC script against an unintended queue manager.

I think we have all pushed an MQSC file into the wrong queue manager. 😦

So, the question was asked, how can I ensure that I only run my MQSC script against the queue manager it was intended for?

This is something that MQSCX can help you with. There are a few ways you can do this.

Check that you are connected to the correct queue manager

One way to protect against running an MQSC script against the wrong queue manager is to start the script with a quick test to see which queue manager it is currently connected to and to exit the script immediately if it is found to be administering the wrong one.

if ( _qmgr != "QM1" )
  print "Wrong queue manager! Script expects to be used on QM1"
  leave
endif

_qmgr is an MQSCX system variable that tells you which queue manager you are administering. There are also some others that might be helpful when coding up checks at the start of a script, _connqmgr tells you which queue manager you are connected to, and will be different from _qmgr if you are using a via connection. _client tells you if you are connected as a client. You can see these in action in the DISPLAY DQM for Distributed blog post.

You could also make the check broader and have it query some attribute of the queue manager to determine if it was an appropriate queue manager to run the script against. For example, looking for the word “(Test)” in the queue manager description. This means a script couldn’t accidentally be run against one of your production queue managers. Using this simple technique, each script can be limited to a class of queue managers; Production, Test, Devt and so on.

DISPLAY QMGR DESCR
if (!findstr("(Test)",DESCR))
  print "Queue Manager",_qmgr,"does not appear to be a test QMgr"
  print "Queue Manager",_qmgr,"DESCR(",:n:DESCR,:n:")"
  leave
endif

Have the script connect to the appropriate queue manager

As an alternative, rather than having the script check that the human running it has used the correct queue manager, the script could make the connection itself.

=conn qm(QM1)
if (_lastrc)
  leave
endif
ALTER QMGR ...
DEFINE CHANNEL ...

A script with commands for different queue managers

Having made a script that connects to the correct queue manager before running the commands against it, it is not difficult to make the next step where you can have a script that issues commands on multiple queue managers – has a section for each queue manager prefixed by an =conn command.

=conn qm(QM1)
ALTER QMGR ...
ALTER CHANNEL ...
 
=conn qm(QM2)
ALTER QMGR ...
ALTER QLOCAL ...
 
=conn qm(Q3)
ALTER QLOCAL ...

This is only scratching the surface of what MQSCX can do, but it can certainly make administration of your IBM MQ queue managers less error prone.


If you’re not a current MQSCX licence holder, and you’d like to try out MQSCX, please email support@mqgem.com to request a trial licence.


I was prompted to write this post as a result of this list-server question.

Adding up

When answering this question I offered a suggestion that you could total the number of connections coming over a set of SVRCONN channels by using the following single line in MQSCX.

@total=0;foreach(DISPLAY CHSTATUS(*) CURSHCNV);@total=@total+CURSHCNV;endfor;print @total

This totaled all the CURSHCNV values for all the channels whose status was displayed.

It occurred to me that there are many other examples of commands where you might want to total up some integer attribute from a set of objects or status records.

  • DISPLAY QLOCAL(SYSTEM.ADMIN.*.EVENT) CURDEPTH
    How many event messages you have
  • DISPLAY CHSTATUS(*) WHERE(RQMNAME EQ MQG2) MSGS
    How many messages have been sent to queue manager MQG2
  • DISPLAY TPSTATUS(‘#’) TYPE(SUB) NUMMSGS
    How many messages have been sent to susbcribers
  • DISPLAY QLOCAL(*) OPPROCS
    How many putting applications are around

Instead of repeating the single line each time with changes to reflect the different command, it might be handy to have a little function that you could just throw a command at and it would do the totaling up for you. For example, you could do something like this:-

func totals(Command,Attribute)
  @total = 0
  foreach(@Command + ' ' + @Attribute)
    @total = @total + eval(@Attribute)
  endfor
  print 'Total of',@Attribute,'for all',@Command,'is',@total
endfunc

And then call it and get the result like so:-

totals("DISPLAY QLOCAL(Q*)","CURDEPTH")

Total of CURDEPTH for all DISPLAY QLOCAL(Q*) is 8

MQSCX functions are just so handy!

DISPLAY DQM for Distributed

If you’re familiar with the IBM MQ for z/OS product, you may have issued the DISPLAY DQM command which gives you the following output:

CSQX830I M901 CSQXRDQM Channel initiator active
CSQX831I M901 CSQXRDQM 8 adapter subtasks started, 8 requested 
CSQX832I M901 CSQXRDQM 5 dispatchers started, 5 requested
CSQX833I M901 CSQXRDQM 0 SSL server subtasks started, 0 requested
CSQX840I M901 CSQXRDQM 5 channels current, maximum 200 
CSQX841I M901 CSQXRDQM 4 channels active, maximum 200, including 0 paused 
CSQX842I M901 CSQXRDQM 0 channels starting, 1 stopped, 0 retrying
CSQX836I M901 CSQXRDQM Maximum channels - TCP/IP 200, LU 6.2 200 
CSQX845I M901 CSQXRDQM TCP/IP system name is TCPIP 
CSQX846I M901 CSQXRDQM TCP/IP listener INDISP=QMGR started, for port 1591 address *
CSQX849I M901 CSQXRDQM LU 6.2 listener INDISP=QMGR not started 

There is no equivalent command for a distributed queue manager, however, you can get most of the same information from various other commands. So we have created an MQSCX script to create an equivalent set of output for a distributed queue manager.

Clearly some of the information simply doesn’t apply to distributed queue managers; for example the number of adapter, dispatcher and SSL Server subtasks. Also the TCP/IP system name doesn’t really have an equivalent on a distributed platform – or at least certainly not one that can be retrieved from the command server. The equivalents of DISPLAY QMGR MAXCHL ACTCHL TCPCHL LU62CHL is to look in the queue manager’s qm.ini file for MaxChannels and MaxActiveChannels on distributed, which is something that cannot work unless you are running the script local to the queue manager.

So the script issues the various commands required to get the information and then prints out a set of equivalent looking lines to give you a similar output:

MQG1 Channel initiator active
MQG1 14 channels current, maximum 400
MQG1 12 channels active, maximum 400, including 0 paused
MQG1 0 channels starting, 1 stopped, 1 retrying
MQG1 TCP/IP listener TCP.LSTR started, for port 1701 address *
MQG1 LU6.2 listener not started

It starts by checking whether the Channel initiator is active, which for most people will be since it gets started automatically by the queue manager these days.

DISPLAY QMSTATUS CHINIT
if (CHINIT = "RUNNING")
  print _qmgr,'Channel initiator active'
endif

Then it looks in the qm.ini file (but only if you’re not connected by a client or via connection). MQSCX can read environment variables just as if they were user variables, so it can make use of the MQ environment variable MQ_DATA_PATH which is setup by setmqenv. The _client system variable is new in MQSCX V9.0.0.

if (!(_client | (_connqmgr != _qmgr)))
  @filename = @MQ_DATA_PATH+"/qmgrs/"+_qmgr+"/qm.ini"
  @hf = fopen(@filename,"r")
  if (@hf)
    while (fgets(@hf,@line) >= 0)

For each line in the qm.ini file it will check for MaxChannels and MaxActiveChannels.

if (findstri(@line, "MaxChannels") > 0)
  @offset = findstr(@line, "=")
  if (@offset > 0)
    @MaxChannelsStr = substr(@line,@offset+1,strlen(@line)-@offset)
    @MaxChannels = eval(@MaxChannelsStr)
  endif
endif

A simple foreach loop allows the script to total up the number of different channel states currently on show. This then allows the various channel status lines in the output to be printed.

Finally the script has another simple foreach loop for listeners which also makes use of the new _numEach system variable to detect if the loop has never been called.

foreach(DISPLAY LSSTATUS(*) ALL WHERE(TRPTYPE EQ TCP))
  print _qmgr, 'TCP/IP listener', LISTENER ,'started, for port', PORT, 'address', IPADDR
endfor
if (_numEach = 0)
  print _qmgr, 'TCP/IP listener not started'
endif

The complete function is available to download in our Example Scripts bundle.


If you’re not a current licence holder, and you’d like to try out MQSCX, please email support@mqgem.com to request a trial licence.