The IBM z/OS Provisioning Toolkit (zospt) V1.0 is a simple USS utility that you can use with the IBM z/OSMF sample workflows for IBM MQ (shipped with IBM MQ V9.0.1 for z/OS), to dynamically provision a development IBM MQ for z/OS queue manager.
Note: In the sample IBM z/OSMF workflows for IBM MQ, the qmgrActions.xml file defines the list of actions that you can perform against a provisioned IBM MQ for z/OS queue manager. The action to start an IBM MQ queue manager is currently called “startQMgr“ and the action to stop an IBM MQ queue manager is called “stopQMgr“. zospt requires that the actions be called simply “start“ and “stop“. So, before you can start or stop an image (see below), you need to change the action names in the actionList from “startQMgr“ and “stopQMgr“ to “start“ and “stop“, respectively.
This article gives you a step by step guide of how to provision an IBM MQ for z/OS queue manager for use in a development environment.
Downloading the toolkit
The toolkit is provided as a zip file that contains a .pax file which you need to be upload and unpax into to a USS directory on the target z/OS system. You can download the toolkit from: download zospt toolkit.
Installing the toolkit
The readme file provided in the toolkit zip file lists the steps you need to perform to install the toolkit. The toolkit is by default installed in a subfolder called zospt e.g. I installed it in USS directory /u/mayur:
Note: For the purposes of this article, the toolkit is installed on host ‘my.host.com‘. You will of course install it on your suitable host.
Before your start to create an IBM MQ image, you need to set up the IBM z/OSMF server connection properties in the zosmf.properties file in the zospt/config directory. The zosmf.properties file is in UTF-8 encoding so you need to use a suitable editor when updating this file.
Note: I actually entered ISPF option 3.17 and used the eu (edit UTF-8) option to edit and save the file in encoding UTF-8:
zospt will use these properties to establish a connection with the IBM z/OSMF server when required. For example, when running an IBM MQ image to create an IBM MQ for z/OS queue manager.
Creating an IBM MQ image
Create a directory for the IBM MQ image in the zospt/samples directory (e.g. mq_v9):
Change to this new directory and create a file called zosptfile in encoding UTF-8. Use your favorite editor to enter the following text into the file:
FROM scratch defines the image on which this image is based. A value of FROM scratch, will make the image you are creating the base image.
Set environment variable ZOSMF_TEMPLATE to the name of a IBM z/OSMF template that you previously created and published, and which you want to use to provision an IBM MQ for z/OS queue manager (e.g. PrvMQ).
Note: I actually entered ISPF option 3.17 and used the eu (edit UTF-8) option to create, edit and save the file in encoding UTF-8:
but, you can use whichever editor you feel comfortable with.
Check that the file creation was successful:
Building an IBM MQ image
From within the directory that contains the zosptfile, issue zospt build to build the IBM MQ image. The -t option allows you to tag a name to the image (e.g. mq) and the period (.) specifies the path to the directory that contains the zosptfile (e.g. the current directory):
You can see the image (e.g. mq.tar) in the images directory:
You can also list images by issuing zospt images:
Setting optional environment variables
By default, zospt uses the default IBM z/OSMF domain and tenant. Depending on the domain and tenant you associated the published IBM z/OSMF template (e.g. PrvMQ) with, you may need to set the following environment variables:
Running an IBM MQ image (i.e. provision an IBM MQ for z/OS queue manager)
Issue zospt run and specify the name of the image you want to run (e.g. mq). The workflows associated with the IBM z/OSMF template perform the required steps to create an IBM MQ for z/OS queue manager:
Once you have created the IBM MQ for z/OS queue manager, the Queue Manager name/SSID (z/OS Subsystem Identifier) and number of the TCP/IP port provisioned for inbound connections are displayed (e.g. ZC05 and 25005, respectively). The name of the container and the container id, which need to be specified on some commands (see below), are also displayed.
Adding the IBM MQ for z/OS queue manager to the IBM MQ Explorer
You can then use the host name, queue manager name and TCP/IP port number to establish a connection to the queue manager. For example, you can establish a connection to it using Add Remote Queue Manager… in the IBM MQ Explorer:
Defining a local queue on the IBM MQ for z/OS queue manager
You can now administer the queue manager from the IBM MQ Explorer. For example, you could define a local queue called TEST.QUEUE:
Defining MQSERVER to allow client connections to the IBM MQ for z/OS queue manager
You can define the MQSERVER variable so that you can run client applications to access IBM MQ resources on the IBM MQ for z/OS queue manager:
Note: The IBM MQ for z/OS queue manager is by default created with Channel Authentication enabled (i.e. CHLAUTH(ENABLED)). Therefore, before clients can connect to the IBM MQ for z/OS queue manager, you need to either define Channel Authentication rules (refer to the IBM MQ V9.0.1 Knowledge Center for further details) or disable Channel Authentication from the IBM MQ Explorer (or, if you are familiar with this, you could alter the IBM MQ for z/OS queue manager attributes and set CHLAUTH(DISABLED)):
Running client applications against the IBM MQ for z/OS queue manager
Once you have set up Channel Authentication, you can run sample program amqsputc to put a message on local queue TEST.QUEUE (created above), for example:
Displaying running containers
You can issue zospt ps to display running containers:
Starting an IBM MQ image (i.e. starting an IBM MQ for z/OS queue manager)
The sample IBM z/OSMF workflow to provision an IBM MQ for z/OS queue manager also starts the queue manager but, if required, you can start an image by issuing zospt start and specifying the container name or container id of the image you want to start.
Stopping an IBM MQ image (i.e. stopping an IBM MQ for z/OS queue manager)
Issue zospt stop and specify the container name or container id of the image you want to stop.
Removing an IBM MQ image (i.e. deprovision an IBM MQ for z/OS queue manager)
Issue zospt rm with the force flag (-f) and specify the container name or container id of the image you want to remove:
This article shows you how to use the z/OS Provisioning Toolkit to provision a development IBM MQ for z/OS queue manager and how to then connect to the queue manager and make use of the resources on the queue manager.
For more information about the IBM z/OS Provisioning Toolkit, see: IBM z/OS Provisioning Toolkit
For more information about using IBM z/OSMF to provision IBM MQ resources, see: Using_z_OSMF_V2_2_Cloud_Provisioning_to_stand_up_MQ_resources and Using IBM z/OSMF to automate IBM MQ