CICS Transaction Server resource builder - readme file
======================================================

Use the CICS TS resource builder to manage your CICS resource definitions by using Configuration as Code.

Incorporate the CICS TS resource builder in your DevOps pipeline to validate and build input commands for the CSD update batch utility, DFHCSDUP, from CICS resource definitions in YAML. Use resource models and application constraints to control and validate CICS resource definitions based on site standards.

The CICS TS resource builder is compatible with CICS Transaction Server for z/OS 5.4 and above.


Release changes
------------------

1.0.6
 - Add support for CICS Transaction Server 6.3.
 - Upgrade dependencies
 - Security updates.

1.0.5
- Upgrade dependencies and move to requiring Java 17.

1.0.4
- Add support for CICS Transaction Server 6.2.
- Security updates.

1.0.3
- Security updates.

1.0.2
- Security updates.
- Documentation restructure and refresh.
- Logging directory has been moved from the installation directory to the ".zrb" directory within the user home directory.
- Log files older than 2 weeks are now automatically purged from the logs directory during zrb initialisation to prevent built-up.
- Resource model, application constraints and import YAML files now support an optional schemaVersion property. This allows the CICS resource builder to be upgraded without disrupting existing YAML files.
- Fix: Import no longer resolves application constraints for application constraints files.
- Fix: Schema enhancements to reduce auto-complete duplicates in VS Code.

1.0.1 (release superseded by 1.0.2 before publication to allow for inclusion of security updates)
- Specifying the zrb command without any arguments now displays the same output as zrb --help.
- Add file encoding requirements to the zrb <command> --help output.
- Improved message terminology for zrb import commands.
- Improved error messages for file processing failures.
- Improved validation for application constraints referenced by the resource model that have not been defined.
- Improved detection and reporting where the resource model and resource import YAML files do not correctly specify the target attribute.
- Specifying a CICS configuration list resource in either the resource import or application constraints YAML files will now report an error if a list is defined with a name of "DFHLIST".
- Fix: The zrb build command no longer fails with a null-pointer exception when a prefix constraint is specified on a model-defined type description attribute.
- Fix: The zrb import command now ensures the application constraint ID it provides are unique.
- Fix: The zrb import command no longer produces unnecessary application constraints in output YAML files.
- Fix: The zrb import command --source commands file now supports DFHCSDUP utility DEFINE commands with DESCRIPTION attributes that contain matching round brackets.
- Fix: The zrb import command now correctly reports discard counts.
- Fix: Badly specified zrb commands no longer appear in the log file name.
- Fix: Corrected behaviour when application configuration resources specify blank attributes values.
- Fix: Only unique "ADD GROUP" commands specified in the zrb build command --output file are now produced.

1.0.0
- Create CICS resource definitions in YAML.
- Validate YAML files by using an IDE with JSON schemas.
- Control definable resource definitions and attributes, in YAML, with a resource model and application constraints.
- Build DFHCSDUP commands file from YAML definitions that conforms to the resource model.
- Guided experience to import DFHCSDUP extracted resources into YAML definitions.


Prerequisites
-------------
Before you use the CICS TS resource builder, ensure that you meet the following requirements:

1. Install the Java Runtime Environment (JRE) or Java Software Development Kit (SDK) V8 or higher on your target environment.

2. **Optional:** To create and validate your YAML files, it is recommended to use an Integrated Development Environment (IDE), such as Visual Studio Code (VS Code), with an extension compatible with Red Hat YAML Language Server, for example the YAML Language Support by Red Hat extension.
For more information, see https://developers.redhat.com/blog/2017/10/18/yaml-language-server-extension-vs-code. 


Installing the CICS TS resource builder
---------------------------------------
1. Download the most recent version of the cics-resource-builder-<version>.zip file from the CICS Transaction Server for z/OS product information website.

2. Transfer the cics-resource-builder-<version>.zip file in binary to the target environment.

3. Extract the cics-resource-builder-<version>.zip file to create the cics-resource-builder directory. Issue the command unzip cics-resource-builder-<version>.zip or, if unzip is unavailable, issue the command jar -xf cics-resource-builder-<version>.zip.

4. Ensure that all users requiring access to the CICS TS resource builder have:
- Traverse and read access for all installed directories and files of the CICS TS resource builder.
- Execute permission for the shell scripts zrb and zrb.bat (Windows users).
- Write access for files generated from running zrb commands.

5. As appropriate for the target platform set a PATH environment variable for the zrb script. Also, automatic code page conversions, LE runtime options, and file tagging for z/OS UNIX System Services.

For information about the CICS TS resource builder and examples, see the documentation:
https://www.ibm.com/docs/cics-resource-builder/1.0 


Upgrading the CICS TS resource builder
--------------------------------------
To upgrade the CICS TS resource builder to a newer version:
1. Save any required logs or output from the old installation
2. Delete the cics-resource-builder directory
3. Follow the installation instructions that are contained in the readme file for the new version.


Uninstalling the CICS TS resource builder
-----------------------------------------
To uninstall the CICS TS resource builder, delete the cics-resource-builder directory.


Running the CICS resource builder
---------------------------------
For an overview of the available command line options, run zrb --help on the command line.

For information about the CICS TS resource builder and examples, see the documentation:
https://www.ibm.com/docs/cics-resource-builder/1.0 

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.


=== END ===
