Deploying CICS TG container in IBM zCX

Edit online

IBM z/OS Container Extensions (zCX) is a z/OS feature that enables clients to deploy Linux applications as Docker containers on z/OS as part of a z/OS workload. This maintains operational control of the Linux environment within z/OS, brings z/OS qualities of service to the application deployment, and does not require the provisioning of separate LPARs or system images.

The CICS TG docker image “ibm-cicstg-container-linux-s390x.tar.gz” has been built for IBM Z, and can deploy either in a Linux on Z, or an IBM zCX environment. For more details about the IBM zCX, see https://www.ibm.com/docs/en/zos/2.5.0?topic=solutions-zos-container-extensions

Logging on to the Docker CLI and using zCX

When a zCX instance is provisioned, it automatically starts a container that provides SSH access for zCX users to use the Docker command line interface (CLI).

You can access the zCX Docker CLI environment using an SSH client from your workstation/laptop.

For example,

ssh -i $KEY_PATH/id_rsa -p 8022 admin@zcx_hostname

This ssh client command allows you to login to zCX host box and work with docker CLI.

Through the Docker CLI, users can deploy and manage CICS TG containers in the zCX instance. This includes the ability to deploy new containers, start/stop containers, inspect container logs, delete containers, etc.

The standard Docker CLI commands are available in this environment. To see the Docker commands available, issue the docker --help command. This includes the ability to connect to the Docker daemon running on zCX. Documentation for specific commands can also be obtained using docker command --help. The versions of the Docker client and server components can be determined by issuing the following command: docker version. This may be helpful if consulting Docker documentation to ensure consistency with the level of your zCX. For more details , https://www.ibm.com/docs/en/zos/2.5.0?topic=extensions-logging-docker-cli-using-zcx

Loading CICS TG container in zCX

Follow these steps to deploy the CICS® Transaction Gateway container. The IBM® CICS TG container available in tar.gz format is loaded through docker load command.

docker load -i ibm-cicstg-container-linux-s390x.tar.gz

Upon successful completion of docker load, use the docker images command to view the image.

docker images

Output of the docker images command to view the image

Start the CICS TG container using the docker run in zCX

It is mandatory to accept the terms of the IBM® CICS TG Container license before you start using the image. To accept the license, you must set the ‘LICENSE=accept’ environment variable when you run the container.

docker run -d -p 2006:2006 -p 2810:2810 -e LICENSE=accept --name ctgcontainer 
localhost/ibm-cicstg-container-linux-s390x:10.1

The CICS TG container starts running in zCX in remote mode. The container has the following services provisioned:

CICS TG TCP handler port listening on 2006.
CICS TG Admin port listening on 2810.

The docker run command exposes port 2006 for connecting external CICS TG client applications and port 2810 for CICS TG administration.

Run docker logs to retrieve the CICS TG logs and docker ps output to verify that CICS TG container is running.

docker ps

Output of the docker ps command to verify that the CICS TG container is running

docker logs ctgcontainer

podman logs 385014726a7b
CTG5204I Starting CICS Transaction
Gateway daemon.
ctgd - CICS Transaction Gateway Daemon
Control Program
(C) Copyright IBM Corporation 2004,
2025. All rights reserved.
Starting IBM CICS Transaction Gateway: started as cicstg:cicstg
02/21/25 09:52:00:977 [0] *** IBM CICS Transaction Gateway log V10.1.0.0 Build Level c1010-20250212-1202 ***
02/21/25 09:52:00:977 [0] CTG6400I CICS Transaction Gateway is starting
02/21/25 09:52:00:978 [0] CTG8400I Using configuration file /var/cicscli/ctg.ini
02/21/25 09:52:01:017 [0] CTG8461I Successfully initialized trace plug-in 'com.ibm.ctg.client.FileTrace'
02/21/25 09:52:01:017 [0] CTG6577I Java details: Version=17.0.11 - 64-bit, Path=/opt/ibm/cicstg/jvm17/bin/java
02/21/25 09:52:01:017 [0] CTG6574I Connection logging has been disabled
02/21/25 09:52:01:050 [0] CTG6981I Successfully initialized JNI library
02/21/25 09:52:01:162 [0] CTG6502I Initial Connection managers = 1, Maximum Connection managers = 100
02/21/25 09:52:01:163 [0] CTG6526I Initial workers = 1, Maximum workers = 100
02/21/25 09:52:01:172 [0] CTG6505I Successfully created the initial connection manager and Worker threads
02/21/25 09:52:01:178 [0] CTG6524I Successfully started handler for the tcp: protocol on port 2006
02/21/25 09:52:01:183 [1] CTG8455I Successfully started the local administration handler on port 2810
02/21/25 09:52:01:183 [0] CTG6597I The statistics API handler has not been started
02/21/25 09:52:01:210 [0] CTG9963W Remapped CCSID to 437 as ANSI_X3.4-1968 is not supported
02/21/25 09:52:01:210 [0] CTG6512I CICS Transaction Gateway initialization complete
02/21/25 09:52:01:218 [0] CTG6411I Interval statistics are active with the statistics interval length set to 3 hours, 0 minutes and 0 seconds
02/21/25 09:52:01:218 [0] CTG6415I The statistics end of day time is set to 00:00:00 Greenwich Mean Time

Docker volumes to persist data in zCX

Docker volumes is the recommended method for persisting Docker container data beyond the life of a container. IBM zCX provides the Docker volumes already preconfigured and mounted to the SSH CLI Container:

The AZD_SHARED_VOLUME is for use as a regular Docker volume that can be shared among any Docker containers running in the zCX instance. AZD_SHARED_VOLUME is mounted at /media/azd_shared_volume in the SSH CLI Container. You should be able to access this directory and store or retrieve data from the SSH CLI Container. You should be able to mount the AZD_SHARED_VOLUME to CICS TG Docker containers started in the zCX instance to store or retrieve data.

docker run -d -p 2006:2006 -p 2810:2810 -e LICENSE=accept -v 
AZD_SHARED_VOLUME:/var/cicscli --name ctgcontainer localhost/ibm-cicstg-container-
linux-s390x:10.1

This maps host volume AZD_SHARED_VOLUME to container volume /var/cicscli. This assumes that the configured path of ctg.ini in container is /var/cicscli and /media/azd_shared_volume is the host volume on which the ctg.ini to be present.

Run docker ps output to verify that CICS TG container is running.

docker ps

You can see the CICS TG configuration files and logs in host volume /media/azd_shared_volume.