Deploying configuration and code to a Websphere MQ

Overview

This guide gives an insight into how with a configuration representing your MQ target(s) you can systematically and securely deploy configuration to the queue manager. Some concepts are discussed at a high level to give an insight into the possibilities but a simple example is used in this instance.

Prerequisites

Before you start this guide it is assumed you have performed the following tasks

  • Created a WMQ_DEPLOY project that has at least the mqdeployment task in the orchestration
  • Created an environment configuration that represents the queue manager topology you wish to deploy (this will be discussed in more detail below)
  • Create an MQSC script to create and manage objects for your queue manager.
  • Configured the Server object and the Environment object with details of your target host and queue manager.

Structure of a MQ configuration

The MQ plugin is used to manage the configuration of queue managers. As described in the best practices documentation it is intended that the plugin be used to manage your queue manager instance in all of its environments from DEV to PRODUCTION. This is achieved by means of using a template MQSC script for your queue manager. This template is a genericised form of your queue manager and as such is tokenized with values that are intended to be replaced (using the corresponding dictionary) at deploy time.

The topology of a MQ configuration is represented in source control (or on local file system) within the project directory structure. A typical structure is reflected below. Showing Directories (D) and Files (f)

(D)             WMQ_DEPLOY
(f)                     midvision-orchestration.xml
(f)                     log4j.properties
(D)                     wmq
(D)                             config
(f)                                     server1.environment1.instance1.app1.dict
(f)                                     server1.environment1.instance1.app1.wmq
(f)                                     server2.environment2.instance2.app2.dict
(f)                                     server2.environment2.instance2.app2.wmq
                                        ...
(D)                             mqsc
(D)                                     <rootFolder>
(D)                                             <folderToInclude1>
(f)                                                     template.mqsc
(D)                                             <folderToInclude2>
(f)                                                     custom.mqsc

It should be noted that this structure is very flexible. One of the dictionary variables for running MQSC into your target queue manager is @@FOLDERS_TO_INCLUDE@@ which enables you to specify different script locations for different environments. This allows you to run a generic template script (which could be called anything) and optionally if your dictionary has specified the folder any custom scripts that may only apply to this single instance of a queue manager. Indeed this structure could allow you to maintain a MQSC script for each queue manager in your estate should you wish that overhead.

A pattern shown below would allow you to maintain a single MQSC script for all the queue managers of the form QMGR_1 (e.g. QMGRD1, QMGRQ1, QMGRP1). The template MQSC script would be tokenized to remove all environmental differences from the file and place them in the corresponding dictionary representing that environment. For example, all channel names, hostnames, port numbers, cluster repositories, listener names could all be tokenized.

wmq
        config
                devServer.QMGRD1.QMGRD1.QMGRD1.dict
                devServer.QMGRD1.QMGRD1.QMGRD1.wmq
                qaServer.QMGRQ1.QMGRQ1.QMGRQ1.dict
                qaServer.QMGRQ1.QMGRQ1.QMGRQ1.wmq
                prodServer.QMGRP1.QMGRP1.QMGRP1.dict
                prodServer.QMGRP1.QMGRP1.QMGRP1.wmq
                ...
        mqsc
                <MASTER>
                        <QMGR_1>
                                template.mqsc

Configuration Files (Dictionary and wmq properties files)

The configuration directory contains all of the dictionary items for each Server.Environment.instance.App you have defined. There are basically 2 types of file (more are covered in the generic documentation). A wmq file and a dict file.

  • wmq files
    • This is a key=value file for the queue manager in question. It can be tokenized if required. Currently you would maintain a property file for each environment but this could be simplified if they were all identical and kept in sync. This still allows flexibility to make subtle changes on an environmental basis. The properties contained in this file are all the required parameters to create and configure a queue manager (e.g. log file sizes, binary installation location, logging type etc.)
    • Below is an example of a wmq file which would suit the structure above
      #RapidDeploy auto generated or edited environment file
      #Mon Nov 12 14:18:34 UTC 2012
      wmq.qmgr.qmgr1.binaryinstalllocation=@@WMQ_BINARY_INSTALL@@
      wmq.qmgr.qmgr1.rootfolder=@@ROOT_FOLDER@@
      wmq.qmgr.qmgr1.folderstoinclude=@@FOLDERS_TO_INCLUDE@@
      wmq.qmgr.qmgr1.connection=@@QMGR_NAME@@\:@@QMGR_HOST@@\:@@QMGR_PORT@@\:@@QMGR_CHANNEL@@
      wmq.qmgr.qmgr1.description=@@QMGR_DESCRIPTION@@
      wmq.qmgr.qmgr1.logfilesize=@@QMGR_LOGFILE_PAGESIZE@@
      wmq.qmgr.qmgr1.datapath=@@QMGR_DATA_FILE_PATH@@
      wmq.qmgr.qmgr1.version=@@WMQ_VERSION@@
      wmq.qmgr.qmgr1.secondarylogs=@@QMGR_SECONDARY_LOG_FILES@@
      wmq.qmgr.qmgr1.deploymentmode=@@QMGR_DEPLOYMENT_MODE@@
      wmq.qmgr.names=qmgr1
      wmq.qmgr.qmgr1.os=@@QMGR_TARGET_OS@@
      wmq.qmgr.qmgr1.logpath=@@QMGR_LOG_FILE_PATH@@
      wmq.qmgr.qmgr1.createqmgr=true
      wmq.qmgr.qmgr1.listener=@@QMGR_LISTENER@@
      wmq.qmgr.qmgr1.primarylogs=@@QMGR_PRIMARY_LOG_FILES@@
      wmq.qmgr.qmgr1.logging=@@QMGR_LOGGING@@
  • dict files
    • This is a simple key=value file for your specific environment. These will typically differe for each configured Server.Environment.Instance.App.dict file you have created. A dictionary can be used to replace parameters in any non-binary file within the deployment package (except for the dictionary files themselves)
    • Below is are examples of a dictionary files
      devServer.QMGRD1.QMGRD1.QMGRD1.dict
              @@ROOT_FOLDER@@=MASTER
              @@FOLDERS_TO_INCLUDE@@=QMGR_1
              @@QMGR_LOGGING@@=CIRCULAR
              @@QMGR_NAME@@=QMGRD1
              @@QMGR_HOST@@=devServer
              @@QMGR_SECONDARY_LOG_FILES@@=5
              @@QMGR_PRIMARY_LOG_FILES@@=3
              ...
      
      qaServer.QMGRQ1.QMGRQ1.QMGRQ1.dict
              @@ROOT_FOLDER@@=MASTER
              @@FOLDERS_TO_INCLUDE@@=QMGR_1
              @@QMGR_LOGGING@@=CIRCULAR
              @@QMGR_NAME@@=QMGRQ1
              @@QMGR_HOST@@=qaServer
              @@QMGR_SECONDARY_LOG_FILES@@=10
              @@QMGR_PRIMARY_LOG_FILES@@=5
              @@QMGR_CHANNEL@@=SYSTEM.ADMIN.SVRCONN
              ...

template.mqsc

Every queue manager would most likely have a template mqsc file to create the required MQ objects within that queue manager. Depending on the way you split your projects you may wish to create projects that create queue managers separate from those that deploy mqsc to them, but in the main some form of MQSC could apply even in that approach (e.g. setting up certain admin channels and default values for model queues).

The template provides a model for your queue manager. It is standard MQSC with various parts tokenised as per your requirements. An example of a template is shown below

ALTER QMGR CHLAUTH(DISABLED)
 
def chl(@@QMGR_CHANNEL@@) chltype(svrconn) trptype(tcp) mcauser('mqm') replace
  
*** Maximum message size of 100Mb
    ALT QMGR MAXMSGL(@@QMGR_MAXMSGL@@)
 
 
*** Default Local Queue
    DEFINE QLOCAL('SYSTEM.DEFAULT.LOCAL.QUEUE') REPLACE  +
    DEFPSIST(YES)       +
    MAXDEPTH(5000)     +
    MAXMSGL(@@QMGR_MAXMSGL@@) +
    PROPCTL(FORCE)
 
*** Default Remote Queue
    DEFINE QREMOTE('SYSTEM.DEFAULT.REMOTE.QUEUE') REPLACE +
    DEFPSIST(YES)
 
*** Default Channel Definitions
 
*** Defaults for a server channel
    DEFINE CHANNEL(SYSTEM.DEF.SERVER) CHLTYPE(SVR) +
    TRPTYPE(TCP) +
    XMITQ(' ') +
    CONNAME(' ') +
    DISCINT(0) +
    MAXMSGL(@@QMGR_MAXMSGL@@) +
    REPLACE DESCR(' ') +
    NPMSPEED(NORMAL)
 
*** Defaults for a requester channel
    DEFINE CHANNEL(SYSTEM.DEF.REQUESTER) CHLTYPE(RQSTR) +
    TRPTYPE(TCP) +
    CONNAME(' ') +
    HBINT(60) +
    MAXMSGL(@@QMGR_MAXMSGL@@) +
    REPLACE DESCR(' ') +
    NPMSPEED(NORMAL)
 
*** Default Channel queues
    DEFINE QLOCAL('SYSTEM.CHANNEL.INITQ') REPLACE +
    DESCR('MQM Channel initiation queue')    +
    PUT(ENABLED)      +
    GET(ENABLED)      +
    DEFPSIST(NO)      +
    MAXDEPTH(1000)    +
    MAXMSGL(2000)     +
    NOSHARE           +
    DEFSOPT(EXCL)     +
    USAGE(NORMAL)     +
    TRIGTYPE(NONE)
 
*** Default Cluster Receiver Channel.
    DEFINE CHANNEL(SYSTEM.DEF.CLUSRCVR) CHLTYPE(CLUSRCVR) REPLACE +
    NPMSPEED(NORMAL) MAXMSGL(@@QMGR_MAXMSGL@@)
 
*** Default Cluster Sender Channel.
    DEF CHL(SYSTEM.DEF.CLUSSDR) CHLTYPE(CLUSSDR) REPLACE +
    NPMSPEED(NORMAL) MAXMSGL(@@QMGR_MAXMSGL@@)
 
*** Default Cluster Transimit Queue
    ALTER QL(SYSTEM.CLUSTER.TRANSMIT.QUEUE) MAXMSGL(@@QMGR_MAXMSGL@@)
 
 
*** Default Alias queues
    DEFINE QALIAS('SYSTEM.DEFAULT.ALIAS.QUEUE') REPLACE  +
    DESCR('MQM Alias Queue')    +
    PUT(ENABLED)      +
    GET(ENABLED)      +
    DEFPSIST(YES) +
    PROPCTL(FORCE)

*** Default Server Connection Channel.
    DEFINE CHANNEL(SYSTEM.DEF.SVRCONN) CHLTYPE(SVRCONN) REPLACE +
    MAXMSGL(@@QMGR_MAXMSGL@@)
 
*** Default Client Connection Channel.
    DEF CHL(SYSTEM.DEF.CLNTCONN) CHLTYPE(CLNTCONN) REPLACE +
    MAXMSGL(@@QMGR_MAXMSGL@@)

Deployment

Once you are comfortable with your environment configuration and mqsc template deployment is a simple matter of creating a Deployment Package and then deploying to the target.

  • Navigate to the packaging screen using the left hand menu (Resources > Software Management > Packages)
  • Select your WMQ_DEPLOY project
  • Click Add New package Wizard edit the name as per your standards and select the skip to finish checkbox
  • Click Next and then Create this deployment Package confirming all dialogs

To deploy the package

  • Navigate to the Deployment screen using the left hand menu (Jobs > New Job)
  • Select your WMQ_DEPLOY project
  • Select the Queue Manager (Server.Environment.Instance.App) object from the dropdown pane on the left and click Next
  • Select the deployment package just created and check the skip to finish button
  • Click Next and then Execute this deployment confirming all dialogs

Progress can be viewed from the Executing jobs screen, further information can be displayed by clicking on the line entry in the table. Logs can be viewed by expanding the Progress section.

Step by step tutorial to create sample RD project

  1. Create RD project (code deploy) and as a Product choose WMQ plugin.
  2. In environment tab select server and environment that you were using to create Queue Manager.
  3. When your project is created edit it again, go to the Orchestration tab and add WmqDeploymentTaskOrchestration tab
  4. Now you need to specify new properties in Environment Configuration (wmq.qmgr.names, wmq.qmgr.TestQM1.os, wmq.qmgr.TestQM1.connection, wmq.qmgr.TestQM1.deploymentmode, wmq.qmgr.TestQM1.folderstoinclude)Environment configuration
  5. Now everything is ready, so you need to create package and start the deployment.