JSON Client Connection Definition Table

A client connection is a communication path between an IBM® Message Queue (MQ) client and an IBM® MQ server. Client connections are stored in a Client Connection Definition Table (CCDT). MQ clients parse this file to determine which queue manager (QM) to connect to and how to connect to it.

Prior to MQ v9.1.2 the CCDT was stored in binary format. From MQ v9.1.2 onwards we have the additional option of creating a CCDT in JavaScript Object Notation (JSON) format. The new format can be used to simplify configuration of QM groups, clusters and uniform-clusters. For more details on the JSON CCDT see the IBM® Knowledge Centre JSON CCDT documentation.

Format & validation

The binary CCDT is a proprietary format that requires the use of tools provided by MQ, such as runmqsc or the MQ Explorer.

The newly available JSON CCDT file is created as a flat file with a .json extension which can be created, viewed and edited with a generic text editor or other JSON tooling. Syntactical and semantic validation of the JSON CCDT can be assured by inputting the CCDT and the CCDT JSON schema into a JSON linter.

The CCDT schema ‘ccdt_schema.json’ is included with the MQ product and redistributable client packages in the following locations:

  • UNIX & I-Series: $MQ_INSTALLATION_PATH/lib and /lib in the product and client packages respectively.
  • Windows: %MQ_INSTALLATION_PATH%\bin and \bin in the product and client packages respectively.

The JSON linter can be an application of choice or a generic linter found online such as herokuapp, however care must be taken to protect sensitive information when using online linters.

Versatility

The flat file format of the JSON CCDT has an advantage in its versatility integrating with specialist tooling. For example it can be integrated with version control tools to track the CCDT change history or integrated with automation tools in a continuous deployment pipeline.

Both binary and JSON formats of the CCDT can be stored in a shared local or remote location which can be referenced by a client connected application with one of the following methods:

You can use directory path and file name to reference a CCDT locally or use one of the file, ftp, or http URL Uniform Resource Locators to define a CCDT remotely.

Compatibility

From MQ v9.1.2 Java, C & .NET clients are supported, these clients can use the JSON CCDT to connect to QMs on distributed or Z/OS platforms. Also runmqsc can be used to view but not edit JSON CCDTs. From MQ v9.1.2 clients and QMs of all versions greater than or equal to MQ v9.1.2 will be will be forwards and backwards compatible with the JSON CCDT.

For C MQI and Java™/JMS clients using the binary CCDT, the version of the C MQI client libraries or MQ JAR files respectively, must be equal to or greater than the version of the QM that was used to build the CCDT. From v9.1.2 onwards for C MQI and Java™/JMS clients using the JSON CCDT, upgrading the C MQI client libraries or MQ JAR files is no longer necessary when integrating a new JSON CCDT version.

Simplified configuration for existing IBM® MQ features

The JSON CCDT format has other benefits that can simplify configuration of multiple QMs when using CCDT features such as QM Groups.

The binary CCDT prohibits the definition of multiple channels of the same name, consequently each QM requires distinct SVRCONN channel configurations. With the JSON CCDT each QM can use the same SVRCONN channel name which reduces the complexity of configuring multiple QMs within a QM Group.

A client connected application utilising the binary CCDT needs to define multiple channel names which are updated whenever a new QM is added to the group. Whereas with the JSON CCDT new client channel definitions might be almost identical with the exception of the conname attribute used to specify the host and port of the target QM.

New IBM® MQ features

The JSON CCDT format also helps facilitate new features introduced in MQ v9.1.2 such as the Uniform Cluster with support for application balancing. A Uniform Cluster is cluster of QMs that share near-identical configuration to offer the same messaging services to a pool of reconnectable client connected applications.

Client connected application workload balancing is provided by the Uniform Cluster whereby an algorithm communicated across the QMs dynamically redistributes reconnectable client connections across the QMs by assessing each QM’s current capacity. For more information on application rebalancing see the following blog article: Auto application rebalancing using the Uniform Cluster pattern.

As mentioned the introduction of the JSON CCDT has simplified the configuration for deploying client connected applications to groups of QMs. Removing the dependency on runmqsc to edit the CCDT also simplifies the dynamic scaling of Uniform Clusters and client connected applications by making it easier to automate changes to the CCDT as the shape of a Uniform Cluster environment changes. For more information on Uniform Clusters see the following blog article: IBM Private Cloud and MQ’s Uniform Cluster.

JSON CCDT Example

Two client connection channels of the same name:

{
    "channel":
    [
        {
            "name": "duplicatedChannel",
            "clientConnection":
            {
                "connection":
                [
                    {
                        "host": "localhost",
                        "port": 1415
                    }
                ],
                "queueManager": "QM1"
            },
            "type": "clientConnection"
        },
        {
            "name": "duplicatedChannel",
            "clientConnection":
            {
                "connection":
                [
                    {
                        "host": "localhost",
                        "port": 1416
                    }
                ],
                "queueManager": "QM2"
            },
            "type": "clientConnection"
        }
    ]
}

6 comments on"New JSON CCDT & Uniform Cluster features in IBM Cloud Private"

  1. Louis Horsley April 10, 2019

    Hi,

    Thank you for your comment, yes mqclient.ini and the MQCHLLIB environment variable will also take an ftp, file or http URL,

    I have updated the article to remove ambiguity.

    Thanks, Louis

  2. Please note that the MQCHLLIB and MQCHLTAB environment variables, and the mqclient.ini attribute can all be used to reference a web-hosted (i.e. http URI) CCDT.

  3. Louis Horsley April 09, 2019

    Hi,

    The links have been updated, thank you,

    Louis

  4. Can you fix your links? Most of them are pointing to internal IBM web server, so people on the internet cannot reach the link you are referencing. i.e. “rtpdoc01.rtp.raleigh.ibm.com” is not accessible to people outside of IBM.

  5. Louis Horsley April 08, 2019

    Hi,

    Thank you for your comment and references, I have updated the article to take into account the maintenance release fix packs.

    Thanks, Louis.

  6. Regarding this statement:
    Prior to MQ v9.0 clients can use a binary CCDT built by the same or earlier version QM, but not a binary CCDT built by a later version QM.

    While 9.0 was the first version where this ability was included in the GA release (9.0.0.0), the enhancement was added to 7.1, 7.5, and 8.0 via maintenance release, see below:

    https://www-01.ibm.com/support/docview.wss?uid=swg21312967:

    For Java/JMS client applications:

    http://www.ibm.com/support/docview.wss?uid=swg1IT10863
    IT10863: WEBSPHERE MQ CLASSES FOR JAVA/JMS APPLICATIONS CAN NOT USE CCDT FILES GENERATED ON A NEWER LEVEL QUEUE MANAGER
    Version Maintenance Level
    v7.0 7.0.1.14
    v7.1 7.1.0.8
    v7.5 7.5.0.6
    v8.0 8.0.0.3

    For C based (and non-Java/JMS) client applications:

    http://www.ibm.com/support/docview.wss?uid=swg1IT11547 (MQ 7.x, MQ 8.0, MQ 9.0 and MQ 9.1 compatibility with previous versions – including usage of CCDT files, JMS .bindings, SSL/TLS) states the following:

    There are 2 APARs that allow OLDER MQ clients to use NEWER CCDT files!
    These APARs relax the restriction by allowing newer CCDTs to be used on older clients but with the caveat that the older client cannot make use of any of the newer channel attributes. These attributes will assume their default values when the CCDT is negotiated with the queue manager.

    For Java/JMS client applications:

    IT11547: WEBSPHERE MQ CLIENT APPLICATIONS CANNOT USE CCDT FILES GENERATED ON A NEWER LEVEL QUEUE MANAGER.
    This applies to C based and non-Java/JMS applications.
    Version Maintenance Level
    v7.1 7.1.0.8
    v7.5 7.5.0.7
    v8.0 8.0.0.3

Join The Discussion

Your email address will not be published.