Overriding resource definitions

You can provide a consistent approach to the creation of certain resources by applying environment-specific overrides through a resource overrides file. You can override the resource definition for any currently supported resource type that can be defined by using resource definition online (RDO).

This feature enables a system programmer to tailor the resources for a specific CICS® environment, and provides the following advantages:

You can take a set of CICS definitions from development through to a production environment without change. Resource attributes can be overridden to support each environment as required.
You can use system-specific symbols such as the LPAR or APPLID to override attribute values dynamically when a resource is installed.
You can apply standards by ensuring that certain attribute values are always turned on or off, or set to a specific value.

You specify the resource definition overrides in a YAML file with a flexible syntax that enables you to set what you want to override by resource type and attribute. You can apply broad override rules, or be very specific. The aim is to provide consistency for all installed resources that match the override rules in the CICS region throughout the lifetime of that region.

For example, you might want to use a single CICS system definition file (CSD) that is based on your production system, but modify some resources such as programs, files, and TCP/IP services for a development or test environment.

This feature is intended for use to make infrequent system-wide changes, rather than short-term resource overrides.

This feature is available when the feature toggle com.ibm.cics.resourceoverrides.file is set, and a valid YAML configuration file, which is known as the resource overrides file, exists in a specific location on zFS. See Enabling resource definition overrides.

After you create a suitable resource overrides file, you can deliver it to a source code management system (SCM) for use in a DevOps delivery pipeline. The configuration file is then available for reliable provision of the required CICS environment.

The resource overrides file is loaded during CICS startup, and the overrides are applied during startup when CICS resources are installed.

Note: During startup, the resource overrides file is read from zFS and parsed. Any errors are flagged during this parse, and when the parsing is complete, CICS initialization terminates with message DFHSI1612.

The overrides also apply to any CICS resources that are installed during the lifetime of the CICS region. For example, overrides are applied at CICS startup during a GRPLIST install, and during the lifetime of the CICS region when resources are installed by using CEDA commands or CICS Explorer®. The resource definitions with the overrides applied are stored in the global catalog. The CSD file or the CICSPlex® SM EYUDREP data repository is unchanged.

Figure 1 provides an overview of the installation methods that support resource overrides and how overrides are applied to a Program resource.

Installing a PROGRAM resource showing input from CSD or DREP and the resource overrides file. Installation request is from CEDA, GRPLIST, SPI, CICS Explorer, or CICSPlex SM WUI and overridden resource is cataloged in the global catalog. — Figure 1. Installing a CICS Program resource and applying resource overrides

If you change the resource overrides file after CICS startup, those changes do not affect the resources in the current CICS region. The resource overrides file is loaded and processed each time that CICS starts, so the changed resource overrides file takes effect when CICS is restarted. The type of CICS start (for example, cold or warm start) also affects which set of resource overrides are applied to various resources. This behavior is described in detail in the following sections, but has the following implications:

If you need to ensure that a consistent set of resource overrides is applied, it is not advisable to change the resource overrides file during the lifetime of the CICS region, or before a warm or emergency start.
When you want to change resource overrides, change the resource overrides file, then restart CICS by using an initial or cold start.

Autoinstalled resources

For autoinstalled resources, you can override the resource attributes by applying resource overrides to the autoinstall model that CICS uses to autoinstall the resources. Overriding the autoinstall model ensures that resource overrides are applied correctly when the resources are dynamically installed. For certain resource types, the autoinstall program can override resource attributes. In this situation, the overrides from the autoinstall program are used for these attributes, rather than those from the resource overrides file.

The effect of resource overrides on autoinstalled resources during a warm or emergency start of the CICS region depends on whether the autoinstall model or the autoinstalled resources are configured to be cataloged. This behavior is described in the following sections.

You can also apply resource overrides to the following default autoinstall models that are provided with CICS and that are defined in the CSD groups that are shown in Table 1. For example, you can override the default autoinstall program model DFHPGAPG in CSD group DFHPGAIP when it is installed. You cannot apply overrides to other resources that are defined in CSD groups that start with the reserved characters DFH.

Table 1. Default autoinstall models
Model resource definition	Resource type	CICS-supplied resource definition	DFH group
APPC parallel-session connection initiated by BIND	CONNECTION SESSION	CBPS. See Resource definitions for APPC connections.	DFHAI62
APPC single-session connection initiated by BIND	CONNECTION SESSION	CBSS. See Resource definitions for APPC connections.	DFHAI62
APPC single-session connection initiated by CINIT	CONNECTION SESSION	CCPS. See Resource definitions for APPC connections.	DFHAI62
Map set	MAPSET	DFHPGAMP. See Model definitions in group DFHPGAIP.	DFHPGAIP
MVS console	TERMINAL	AUTC. See CICS-supplied groups not in DFHLIST.	DFHTERMC
Partition set	PARTITIONSET	DFHPGAPT. See Model definitions in group DFHPGAIP.	DFHPGAIP
Program	PROGRAM	DFHPGAPG. See Model definitions in group DFHPGAIP.	DFHPGAIP
Terminal	TERMINAL TYPETERM	All resource definitions listed in TYPETERM definitions in group DFHTYPE and Model TERMINAL definitions in group DFHTERM.	DFHTERM DFHTYPE

For more information about using autoinstall for resources, see Autoinstall.

Initial or cold start

For an initial or cold start of a CICS region, the resource overrides file is loaded during CICS startup. The overrides that are specified in that file are active for the lifetime of the CICS region. Overrides are applied when CICS resources are installed during CICS startup, and when CICS resources are installed during the lifetime of the CICS region. The resource definitions with any overrides applied are stored in the global catalog, and the CSD file or the CICSPlex SM EYUDREP data repository is unchanged.

If the autoinstall model or autoinstalled resources are configured to be cataloged, those resources with any overrides applied are also stored in the global catalog.

Warm or emergency start

For a warm or emergency start of a CICS region, CICS resources are restored in their current state from the global catalog. That is, recovered resources retain their existing attributes, including any values that were overridden when the resource was originally installed. Overrides are not applied to those resources during CICS startup. For CICS bundles, the BUNDLE resource is restored from the global catalog, but not the resources that are installed through the bundle. For autoinstalled resources, if the autoinstall model or autoinstalled resources were configured to be cataloged, those resources are restored from the global catalog.

During CICS startup, the latest resource overrides file is loaded and the overrides that are specified in that file are active for the lifetime of the CICS region. Overrides from this current resource overrides file are applied in the following situations:

During CICS startup for CICS resources that are installed through a CICS bundle, because those resources are re-created during a restart.
However, resource overrides cannot be applied to resources that can be defined only by using bundles, for example EP adapters, event bindings, OSGi bundles, or policies.
When new CICS resources are installed, or when resources are discarded then reinstalled, during the lifetime of the CICS region.
When autoinstall models and autoinstalled resources that were not configured to be cataloged are installed during the lifetime of the CICS region.

If the resource overrides file was changed before the warm or emergency start, different overrides could apply to recovered resources and newly installed resources. To avoid this inconsistency, don't change the resource overrides file during the lifetime of the CICS region, or before a warm or emergency start.

Resource overrides file

The resource overrides file is a configuration file that uses a subset of the YAML Version 1.2 format and must use a UTF-8 character encoding. The file must be located in the ussconfig/resourceoverrides directory, where ussconfig is the location that is specified by the USSCONFIG system initialization parameter, for example /var/cicsts/dfhconfig/resourceoverrides. The file name must be the name that is specified by the com.ibm.cics.resourceoverrides.file feature toggle.

You use YAML format to specify each CICS resource type, followed by one or more override rules. Each override rule specifies which resources to override and one or more override actions to apply. The actions specify the operation to perform and the attribute values to apply as overrides. You can specify the following operations in an action:

Set. Replaces an attribute value with the value that is specified by the override. Supported for all types of attribute: character, integer, and CICS-value data area (CVDA).
Find and replace. Find all instances of specified string in an attribute value and replace them. Supported for character attributes only.
Prefix. Prefix an attribute value. Supported for character attributes only.
Suffix. Suffix an attribute value. Supported for character attributes only.

For example:

schemaVersion: resourceOverrides/1.0
resourceOverrides:
# Set CEDF to YES for all programs defined in the CSD group MYGRP  
- program:
   - selector:
       group: MYGRP
     overrides:
       cedf: YES

For more details, see Resource overrides file format.

Security considerations

As with other CICS TS configuration files on z/OS® UNIX, appropriate security must be set for the resource overrides file. This configuration file is used to implement system-wide changes, so access must be restricted appropriately. Only the following access permissions are required:

The CICS region user ID must have read access to the resourceoverrides_file_name.yaml file in the ussconfig/resourceoverrides zFS directory, where ussconfig is the location that is specified by the USSCONFIG system initialization parameter. For more information about setting up security, see Authorizing access to z/OS UNIX System Services.
System programmers must have write access to the resourceoverrides_file_name.yaml file to enable updates to the file.

Tip:

Message DFHPA1956I in the system message log shows the name of the resource overrides file resourceoverrides_file_name.yaml that is set by the com.ibm.cics.resourceoverrides.file feature toggle for your CICS region.

Message DFHPA2002I in the system message log shows the path of the ussconfig/resourceoverrides directory for your CICS region.

Resource types that can be overridden

You can apply overrides to resource types that can be defined by using RDO:

A-J	J-P	S-W
ATOMSERVICE	JVMSERVER	SESSIONS
BUNDLE	LIBRARY	TCPIPSERVICE
CONNECTION	LSRPOOL	TDQUEUE
DB2CONN	MAPSET	TERMINAL
DB2ENTRY	MQCONN	TRANCLASS
DB2TRAN	MQMONITOR	TRANSACTION
DOCTEMPLATE	PARTITIONSET	TSMODEL
DUMPCODE	PARTNER	TYPETERM
ENQMODEL	PIPELINE	URIMAP
FILE	PROCESSTYPE	WEBSERVICE
IPCONN	PROFILE
JOURNALMODEL	PROGRAM

Overrides can be applied to these resource types when they are installed as part of a CICS bundle. However, it is important to understand which set of resource overrides are applying to such resources during a warm or emergency start of a CICS region, as described earlier.

Restrictions

You cannot override a resource name, or the CSD group attribute when a resource is installed during a GRPLIST install or by using CEDA.

You cannot apply overrides to the following resources:

Most resources that are defined in CSD groups that start with the reserved characters DFH. The exceptions are the default autoinstall models in the CSD groups that are listed in Table 1.
Resources where the source of the resource definition is CICS or CICSPlex SM (DEFINESOURCE=SYSTEM). This includes any CICSPlex SM resources that are defined during CICS startup by using EXEC CICS CREATE commands.
Resources that can be defined only by using bundles:
- Atom configuration file
- Db2® package set
- Event binding
- Event processing adapter
- Event processing adapter set
- Node.js application
- OSGi bundle
- Policy
Resources that are not supported in this release of CICS TS.