Working with JSON CCDT files

A recent feature added to IBM MQ are Client Channel Definition Table (CCDT) files in JSON format.

One of the features of MQSCX is to work with CCDT files, both the binary format, and now (since MQSCX V9.2.0) the JSON format.

With MQSCX you can display or create/alter a JSON CCDT file using familiar MQSC commands. Your tried and tested scripts for creating binary format CCDT files, can be used to create the same in JSON format.

For example, this file:

DEFINE CHANNEL(MQG1.SVRCONN) CHLTYPE(CLNTCONN) +
       CONNAME('gemmvs(1701)') QMNAME(MQG1)
DEFINE CHANNEL(MQG2.SVRCONN) CHLTYPE(CLNTCONN) +
       CONNAME('gemmvs(1702)') QMNAME(MQG2)

ClientChls.mqs

Run with this command:

mqscx -j -i ClientChls.mqs

Will produce a JSON CCDT file like this where the MQCHLLIB and MQCHLTAB environment variables point:

ClientChls.json

{
  "channel":
  [
    {
      "name": "MQG1.SVRCONN",
      "type": "clientConnection",
      "clientConnection":
      {
        "connection": 
        [
          {
            "host": "gemmvs",
            "port": 1701
          }
        ],
        "queueManager": "MQG1"
      }
    },
    {
      "name": "MQG2.SVRCONN",
      "type": "clientConnection",
      "clientConnection":
      {
        "connection": 
        [
          {
            "host": "gemmvs",
            "port": 1702
          }
        ],
        "queueManager": "MQG2"
      }
    }
  ]
}

You can also use MQSCX interactively and type in these familiar MQSC commands, using TAB auto-complete to assist, and create a JSON CCDT that way too.

Validation

One of the benefits of using a JSON format CCDT is that it is a text file instead of the proprietary binary file. So why do you need a tool like MQSCX to create one? Well the answer is validation. If you create a JSON CCDT file by hand, you may have a typo or spelling error in any of the field names. If you do this and display your file using runmqsc, or run it using an MQ Client, neither will inform you of your typo because they are designed to be future proof. There is no versioning on a JSON CCDT file, so if the MQ Client uses one that is from a newer version of MQ, it just ignores anything that it doesn’t recognise. This includes your misspelled attributes, that you actually wanted it to use!

Misspelled attributes

Here’s an example JSON CCDT with a typo:

{
  "channel":
  [
    {
      "name": "MQGEM.SVRCONN",
      "type": "clientConnection",
      "clientConnection":
      {
        "connection":
        [
          {
            "host": "localhost",
            "port": 1701
          }
        ]
      },
      "connectionManagement":
      {
         "hbInterval": 60
      }
    }
  ]
}

HBintClnt.json

If I use runmqsc to look at it, it won’t complain and it will tell me that my heartbeat interval value is 300.

Note: runmqsc can be used to display the contents of the JSON CCDT file, but not to create or edit its contents.

runmqsc -n

5724-H72 (C) Copyright IBM Corp. 1994, 2019.
Starting local MQSC for 'HBintClnt.json'.
DISPLAY CHANNEL(*) HBINT
     1 : DISPLAY CHANNEL(*) HBINT
AMQ8414I: Display Channel details.
   CHANNEL(MQGEM.SVRCONN)                  CHLTYPE(CLNTCONN)
   HBINT(300) 

With a SVRCONN defined with HBINT(60), a client running using this CCDT, which should be using 60 seconds for the heartbeat interval, will actually use 300, and so the running SVRCONN will end up with 300 as well.

AMQ8417I: Display Channel Status details.
   CHANNEL(MQGEM.SVRCONN)                  CHLTYPE(SVRCONN)
   CONNAME(127.0.0.1)                      CURRENT
   HBINT(300)                              STATUS(RUNNING)
   SUBSTATE(RECEIVE)                    

Running MQSCX to look at this JSON CCDT file, will show the following:

MQSCX Extended MQSC Program – Version 9.2.0

At line 20 of file ‘C:\MQGem\HBintClnt.json’, unrecognised field name ‘hbInterval’ found

CCDT file ‘C:\MQGem\HBintClnt.json’, 1 channels read

Licenced to Paul Clarke

Licence Location: Head Office

So, you are immediately aware of the issue in your CCDT file.

Missing mandatory attributes

There aren’t many mandatory attributes on a client channel definition, but those that are, are important!

If you omit a mandatory attribute, again runmqsc won’t complain, but of course the client channel will when it tries to make a connection.

Here’s an example JSON CCDT with a channel that hasn’t specified a connection name:

{
  "channel":
  [
    {
      "name": "MQGEM.SVRCONN",
      "type": "clientConnection",
    }
  ]
}

ConnameClnt.json

When a client application attempts to run using this, you’ll get something like the following in your client AMQERR01.LOG:

AMQ9203E: A configuration error for TCP/IP occurred.

EXPLANATION:
Error in configuration for communications to host ' '.  Allocation of
a TCP/IP conversation to host ' ' was not possible.

Running MQSCX to view, and therefore validate, this JSON CCDT file, will show the following:

MQSCX Extended MQSC Program – Version 9.2.0

The channel definition ending at line 7 of file ‘C:\MQGem\ConnameClnt.json’ has not specified a connection name

CCDT file ‘C:\MQGem\ConnameClnt.json’, 1 channels read

Licenced to Paul Clarke

Licence Location: Head Office

Enhanced Filtering

In addition to the above, using MQSCX to view and manipulate your CCDTs (both binary and JSON) allows you to utilise the power of MQSCX filtering. For example you can use a command like the following, which wouldn’t be allowed through runmqsc.

DISPLAY CHANNEL(*MQGEM*)

Or you could use enhanced WHERE clauses that are more powerful than the IBM MQ supplied WHERE clause. For example, you can use a command like the following:

DISPLAY CHANNEL(*) =WHERE(NOT(SCYEXIT AND SCYDATA))

Re-ordering your JSON defined channels

The order that an MQ client will pick channels to use from your JSON CCDT is dependant on the order they are in the file, and you control that order. In the binary CCDT, the file was always internally ordered alphabetically, but with a text file like the JSON CCDT you are in complete control.

As it is a text file, you can just use your favourite editor to copy the lines around, just make sure you have all the right brackets and commas in place. Alternatively, you can use MQSCX to reorder your file just how you want it as follows.

MOVE CHANNEL(MQG1.SVRCONN) POSITION(1) NEWPOS(2)

You can also indicate the position in the file for a channel definition at the time you create it, for example, using a command like this to make the new channel first in the file:

DEFINE CHANNEL(MQG1.SVRCONN) CHLTYPE(CLNTCONN) +
       CONNAME('gemmvs(1701)') QMNAME(MQG1) INDEX(BEFORE)

JSON file format

You also have some control over the contents of the JSON CCDT file that is created by MQSCX with three options on how the fields are output.

• =set jsonfields(all)
  This option will create a JSON CCDT file with all the values output, even those that just contain the default or blank values. This makes your JSON CCDT file bigger of course, but might be useful if you need to manually edit it later and you are unsure of the field names.
• =set jsonfields(date)
  This option will create a JSON CCDT file with the minimum set of fields (see below) and additionally the alteration date/time field. The MQ Client does not make use the of this date information, so it is only added if you ask for it. We assume, since it is in the JSON CCDT schema that someone might want it for something.
• =set jsonfields(min)
  This is the default setting, and only outputs the channel fields are have non-default or non-blank values. This will make your JSON CCDT file much smaller than you would get with jsonfields(all), and is the minimum the MQ Client needs to work with.

Summary

So if you’re starting to look into using JSON CCDT files, perhaps for their ability to define channels with the same name within one CCDT, and you’re not a JSON format expert, take a look at MQSCX to produce your CCDTs and ensure that you always have a valid format CCDT file to use with your MQ Clients.

---

If you don’t already have MQSCX and you’d like to try it out, please email support@mqgem.com to request a trial licence. You can download MQSCX from our website.