How to run Containerized CICS TS resource builder

The containerized CICS TS resource builder image can be run with any container engine capable of running OCI compliant containers.  In the examples below we use podman as our container engine.  In order to generate a DFHCSDUP file that contains the resources required by the Application Programmer, CICS TS resource builder uses a Resource Description file (which contains a description of the resources to be created) and a Resource Model file (which describes what resources can be created and changed).  It also produces an output file (the DFHCSDUP file).  In order to use these files within the container, the directories of the file need to be mounted into the container.  In podman this is done using the -v volume mount option.  An example of this is shown below:

-v $PWD/local_resource_definitions:/container_resource_definition -v $PWD/local_resource_models:/container_resource_models -v $PWD/local_output:/container_output

Taking the first directory as an example, local_resource_defintions is the real place on disk that the resource definitions file is held.  Container_resource_definitions is the location inside the container the local directory is mounted to.  Using this is in a full podman CICS TS resource builder build command looks as follows:

podman run -it --rm -v $PWD/local_resource_definitions:/container_resource_definition -v $PWD/local_resource_models:/container_resource_models -v $PWD/local_output:/container_output location_of_resource_build_container build -r /container_resource_definition/definitionfile.yaml -m /container_resource_models/modelfile.yaml -o /container_output/DFHCSDUP

Breaking the above command down further:

• podman run – this tells podman to pull the container image and run the container
• -it – indicates we are feeding input into the container
• --rm – indicates that we want to remove the container when it completes
• -v section – volume mounts as described above
• build – this is a CICS TS resource builder command that generates a DFHCSDUP file from a Resource Definition file and a Resource Model file.
• -r /container_resource_definition/definitionfile.yaml – the mounted location in the container of the Resource Definitions file
• -m /container_resource_models/modelfile.yaml – the mounted location in the container of the Resource Model file
• -o /container_output/DFHCSDUP – the mounted location in the container where the DFHCSDUP output file will be written to.

Example

In Company ABC, Application Developers who wish to be able to add new URI Maps to a test system, currently must ask a System Programmer to do this. Company ABC has decided that the Application Developers should be able to create their own URI Map resources, using CICS TS resource builder, which would live along with the code in the SCM. This will mean System Programmers no longer need to be involved in the creation of the new URI Maps, and the configuration required by the code can travel with it through the SCM system.

The first required step is for the System Programmer to create a schema that will detail what resource Application Developers can create. In CICS TS resource builder this is known as a Resource Model. A simple example of a URI Map schema is shown below:

schemaVersion: resourceModel/1.0
application:
  name: Urimap model
  description: "Urimap model"
resourceModel:
  target: cicsts-6.1.0
  defines:
    - id: client-urimap
      description: For calling outbound URIs
      type: urimap
      attributes:
        public:
          name:
            required: true
            description: Specfiy the name of URIMAP for outbound URIs
          group:
           required: true
            description: Specify the name of the RDO group
          description:
            required: false
          path:
            required: true
            description: Specify path component of client URIs

We can see from this schema that we are going to create a resource with an ID of client-urimap and a type of urimap.  If we wanted, we could have more than one schema for a URI Map.  We differentiate between these schemas by the ID we assign to them.  For example, I may have a separate schema for my server-side URI Maps with an ID of server-urimap.

Looking further down the schema we can see that we have a set of public attributes.  These are the attributes that the Application Developers can see and modify.  If it was required, a private set of attributes could be provided.  These attributes have values that are set by the System Programmer and cannot be changed by the Application Developer.  In my public attributes I have name which must be provided by the Application Developer.  This is simply the name of the URI Map that will eventually be created on the CSD.  The schema also requires that a group name must be provided.  There is then an optional description that may be provided but is not required.  Finally, the Application Developer must specify a path for the URI map.

Once the System Developer has completed the schema for the Resource Model, the Application Developer can pick it up and use it to create a YAML file containing the URI Map resources they want to create. This file is called the Resource Definition file. An example of a simple Resource Definition file can be seen below:

resourceDefinitions:
  - client-urimap:
      name: APCLNT01
      description: URIMAP for calling outbound URIs
      group: WEBAPP
      path: /apclnt01

Here we can see that the Application Developer wants to create a URI Map called APCLNT01.  They have supplied a description of the resource, and they have associated it with a group called WEBAPP and set a path of /apclnt01.

The next step is to run the Container version of the CICS TS resource builder to generate a DFHCSUP file that can be used to load the newly created definition into a CICS regions CSD. An example of this command is shown below:

podman run --name <container-name> -it -v $PWD/resources:/input <internal-image-registry>/<image-name> build --resources /input/definitionfile.yaml --model /input/modelfile.yaml --output /output/DFHCSDUP

Finally we can look at the DFHCSDUP output file that was generated by the CICS TS resource builder.  This file can be integrated with any existing resource update processes.

* ---
* createTime: 2024-10-22T14:23:18.003Z
* createTimeFileEncoding: IBM-1047
* application:
*   description: Urimap model
*   name: Urimap model
*   source: ""
* resourceModel:
*   source: /resourceModels/model.yaml
*   target: cicsts-6.1.0
* resourceDefinitions:
*   source: /resourceDefinitions/resource.yaml
DEFINE URIMAP(APCLNT01) GROUP(WEBAPP)
DESCRIPTION(URIMAP for calling outbound URIs)
       PATH(/apclnt01)

Conclusion

By using a containerized version of CICS TS resource builder, you can ensure that everyone across the organization is using the latest version of the tool.  Everyone pulls the same image, and every time an image is run, the container engine will check to see if it has the latest version of the image, and if not, will pull the new version.  In doing this it removes the need to manage multiple installations of CICS TS resource builder across the organization, reducing support costs as everyone is using exactly the same version of the tool.  It also means tooling is not installed on a user’s workstation when they no longer require it; the tool only exists for the lifetime of the container.

If you would like to know more about the containerized version of CICS TS resource builder please see the CICS TS resource builder documentation here.