Resource overrides file format

General information

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 RESOVERRIDES system initialization parameter.

A sample resource overrides file, and a resource overrides JSON schema to use when you edit the resource overrides file, are provided. See Setting up a resource overrides configuration file.

To specify resource overrides, use YAML format block collections with lists (also known as sequences) and mappings (key-value pairs). The following information describes the YAML formatting that is supported in the resource overrides file.

YAML flow style notation for lists and mappings (use of indicator characters rather than indentation) is not supported.

schemaVersion: resourceOverrides/major.minor
resourceOverrides: 
- resource-type:
  - selector:
      attribute: value
      attribute:
        - condition-operator: value
    overrides:
      attribute: value
      attribute:
        - action-operator: value

The maximum size of a resource overrides file is 1 MB.

Schema version

You use the schemaVersion mapping to specify the version of the resource overrides JSON schema that describes the required syntax for the resource overrides in the resource overrides file. All resource overrides that you specify in the resource overrides file must be supported by this version of the resource overrides JSON schema.

Specify the schemaVersion key, followed by the name and version number of the corresponding resource overrides JSON schema. The schema name must be resourceOverrides. The name and version number are separated by a forward slash (/). The schema version number is in the format major.minor, where major and minor are the same as the version number of the corresponding JSON schema resourceoverrides-major.minor.micro.json.

The schemaVersion mapping is compatible with changes to the .micro version number of the JSON schema. For example, schemaVersion: resourceOverrides/1.0 indicates that the resource overrides file is supported by the resourceoverrides-1.0.n.json schemas.

You must specify a schema version number that is supported by CICS TS beta. If a resource overrides file is shared across multiple CICS releases, the schema version must be supported for all those CICS releases.

schemaVersion: resourceOverrides/1.300

schemaVersion: resourceOverrides/1.200

schemaVersion: resourceOverrides/1.100

schemaVersion: resourceOverrides/1.0

Resource overrides

To specify the start of the resource overrides in the YAML file, specify the resourceOverrides key. This mapping is followed by the list of CICS resource types that you want to apply overrides to.

resourceOverrides:

To specify a resource overrides file that does not contain any resource types or override rules, you can specify a value of null or ~ for the mapping. Any content that follows must be commented out. For example:

resourceOverrides: null
#  - resource-type:
#     - override rules

Resource types

To specify the CICS resource types that you want to apply overrides to, specify each resource type as a list item after the resourceOverrides mapping. You can list a resource type more than once in the block. List all resource types at the same level in the file.

For the list of resource types that you can apply overrides to, see How it works: Resource definition overrides. For details of valid resource types, resource attributes, and attribute values that you use to specify resource overrides, see Resource definition attributes.

- resource-type:

- program:
    - override rules
- file:
    - override rules

Each resource type is followed by a nested list of one or more override rules.

Override rule

If you do not specify a selector, the overrides mapping applies to all resources of the listed resource type.

  - selector:
    overrides:

or

  - overrides:

Selector mapping (optional)

To specify a selector mapping, specify the selector key, followed by one or more conditions. The conditions specify attribute values to use to select resources, and are processed in the order that they are specified in the file. For a resource type with multiple conditions specified, all conditions must be satisfied to select the resources; that is, conditions are connected by and.

For a simple condition, use a nested attribute: value mapping.

  - selector:
      attribute: value

For conditions that use a condition operator, use a nested attribute followed by a nested list item for each condition-operator: value mapping.

  - selector:
      attribute: 
        - condition-operator: value
        - condition-operator: value

  - selector:
      name: value

  - selector:
      attribute: ""

name: '*ABC'
name: A*BC

name: *ABC
name: A*B*C

- transaction:
  # Select all transactions starting with TR that have an initial program of MYPROG
  - selector:
      name: TR*
      program: MYPROG

- program:
  # Select all programs ending with TEST that are not in the group MYGRP1
  - selector:
      name: '*TEST'
      group:
        - not: MYGRP1

- enqmodel:
  # Select all enqmodel definitions with an enqname value of ENQ*
  - selector:  
      enqname: 
        - literal: ENQ*

Overrides mapping

To specify the overrides mapping, specify the overrides key, followed by one or more actions. The actions specify the attribute values to apply as overrides, and are processed in the order that they are specified in the file.

You cannot override a resource name or a group attribute.

For a set action, you can use a nested attribute: value mapping, or an action operator.

  - overrides:
      attribute: value

For actions that use an action operator such as set, prefix, or suffix, use a nested attribute followed by a nested list for each action-operator: value mapping. For the find and replace action, use a nested attribute followed by a nested list item for the pair of action-operator: value mappings.

  - overrides:
      attribute: 
        - action-operator: value
        - action-operator: value

You can specify the following operators in an action, depending on whether the attribute is a character attribute, an integer, or a CVDA.

set

You can set character attributes, integer attributes, and CVDAs in one of the following ways:

• Use an attribute: value mapping.
• After the attribute, use a nested list item for the action-operator: value mapping, where the action operator is set.

The following example sets a CVDA and an integer attribute. The first overrides mapping sets the CICS execution diagnostic facility (CEDF) on for programs. The second overrides mapping sets the purgecycle for DB2CONN resources to 5 minutes, 0 seconds:

- program:
    - overrides:
        cedf: YES
- db2conn:
    - overrides:
        purgecycle: 05,00

The following example also sets CEDF on for programs, but uses the set action operator.

- program:
    - overrides:
        cedf: 
          - set: YES

For attributes where it is valid to set a null string, you can remove any current attribute value by specifying an empty value "" or a null string. This applies to most character attributes and a minority of CVDAs, but not integer attributes. For example:

- transaction:
    - overrides:
        alias: ""    

For attributes which take a default value if not specified setting a null string will reset the default value. For example:

- transaction:
    - overrides:
        tranclass: ""    

will clear any value specified for transaction class and set the default value, e.g. DFHTCL00.

For a character attribute, you can use symbols and symbol substrings in the attribute value. See Symbols and symbol substrings.

For some integer attributes, it is valid to set specific character values. For example, SYSTEM is a valid value for the RUNAWAY attribute of a TRANSACTION resource, and NO is a valid value for some timeout attributes.

find and replace

You can use find and replace for character attributes.

After the attribute, use a nested list item for the pair of action-operator: value mappings, where the action operators are find and replace.

    - overrides:
        attribute: 
          - find: value
            replace: value

For example:

- urimap:
  # Modify the path for URIMAP resources to change all instances of prod to test
  - overrides:
      path:
        - find: prod
          replace: test

You can use symbols and symbol substrings in the attribute values. See Symbols and symbol substrings.

prefix

You can add a prefix to a character attribute with an existing value. You cannot prefix a null attribute value.

After the attribute, use a nested list item for the action-operator: value mapping, where the action operator is prefix.

  - overrides:
      attribute: 
        - prefix: value

For example:

- file:
  - overrides:
      dsname: 
        - prefix: TESTLPAR.

You can use symbols and symbol substrings in the attribute value. See Symbols and symbol substrings.

suffix

You can add a suffix to a character attribute with an existing value. You cannot suffix a null attribute value.

After the attribute, use a nested list item for the action-operator: value mapping, where the action operator is suffix.

  - overrides:
      attribute: 
        - suffix: value

For example:

- file:
  - overrides:
      dsname: 
        - suffix: .DEV

You can use symbols and symbol substrings in the attribute value. See Symbols and symbol substrings.

Symbols and symbol substrings

You can use symbols and symbol substrings in character attribute values in override mappings.

- file:
    - overrides:
        dsname: "{{CICS_APPLID}}.ZUSER.CATALOG.FILEA"

- file:
    - overrides:
        dsname: 
          - find: "{{ CICS_REGION_USERID }}"
            replace: "{{ CICS_APPLID }}"

- transaction
    - overrides:
        tranclass:
          - prefix: "{{CICS_APPLID[0:1]}}"

- file:
    - overrides:
        dsname: "USER{{CICS_SYSID[2::2]}}.ZUSER.CATALOG.FILEA"

Examples

schemaVersion: resourceOverrides/1.300
resourceOverrides: 
- program:
    # Set CEDF on for all programs in the group "MYGRP"
    - selector:
        name: '*'
        group: MYGRP 
      overrides:
        cedf: YES
    # Change CONCURRENCY from QUASIRENT to THREADSAFE for all programs, 
    # except those in the groups "MYGRP1" and "MYGRP2"
    - selector:
        group: 
          - not: MYGRP1
          - not: MYGRP2
        concurrency: QUASIRENT
      overrides:
        concurrency: THREADSAFE
    # Set CEDF on for all programs autoinstalled using the default autoinstall 
    # program model "DFHPGAPG" if defined in RDO group "DFHPGAIP"      
    - selector:
        name: DFHPGAPG
        group: DFHPGAIP 
      overrides:
        cedf: 
          - set: YES
- db2conn:
    # Set the PURGECYCLE attribute for the DB2CONN "DB2AAA" to 
    # 5 minutes and 0 seconds
    - selector:
        name: DB2AAA
      overrides:
        purgecycle: 05,00
- transaction:
    # Remove the ALIAS attribute for all transactions that start with the 
    # characters "TR"
    - selector:
        name: TR*
      overrides:
        alias: ""
    # Set the TRANCLASS attribute to "TCLTEST" for all transactions whose  
    # name start with the characters "tr" and end with "1" 
    - selector:
        name: tr*1
      overrides:
        tranclass: "TCLTEST"
    # Prefix the TRANCLASS attribute of all transactions with the first 
    # two characters of the CICS_APPLID
    - overrides:
        tranclass:
          - prefix: "{{CICS_APPLID[0:1]}}"
    # Change the value of the WAITTIME attribute to 2055 mins (1 day, 
    # 10 hours, 15 minutes) for the transaction "RUNA" in group "EXMP8"
    # if the current WAITTIME is 1563 mins (1 day, 2 hours and 3 minutes) 
    - selector:
        name: RUNA
        group: EXMP8
        waittime: 1,2,3
      overrides:
        waittime: 1,10,15
    # Set RUNAWAY attribute to 300 milliseconds for all transactions 
    # defined with default value of SYSTEM
    - selector:
        runaway: SYSTEM
      overrides:
        runaway: 300
- file:
    # Set the DSNAME attribute of FILE "FILEA" using the value of 
    # the APPLID symbol  
    - selector:
        name: FILEA
      overrides:
        dsname: "{{CICS_APPLID}}.FILEA" 
    # Prefix the DSNAME attribute of the FILE "FILEA" with the string 
    # "TESTLPAR."
    - selector:
        name: FILEA
      overrides:
        dsname: 
          - prefix: TESTLPAR.
    # Modify the DSNAME attribute of the FILE "FILEA" to change all 
    # instances of "EXAMPLE" to "MYEXMPL", prefix it with "MYCOPY." 
    # and suffix it with ".TEST"
    - selector:
         name: FILEA
      overrides:
        dsname:
          - find: EXAMPLE
            replace: MYEXMPL 
          - prefix: MYCOPY.
          - suffix: .TEST
    # Change a remote FILE named "REMFILE" to be a local file that 
    # uses the data set "DEV.CATALOG.FILEA" 
    - selector:
        name: REMFILE
      overrides:
        dsname: DEV.CATALOG.FILEA
        remotename: ""
        remotesystem: ""   
- jvmserver:
    # Set THREADLIMIT attribute for a JVMSERVER named TESTSERV to 5
    - selector:
        name: TESTSERV
      overrides:
        threadlimit: 5
- tsmodel:
    # Modify the PREFIX attribute for all TSMODEL resources defined in the 
    # group "EXMP6" with a LOCATION of MAIN to change all instances of 
    # "PROD" to "TEST"  
    - selector:
        name: TSMOD*
        group: EXMP6
        location: MAIN  
      overrides:
        prefix:
          - find: PROD
            replace: TEST
- sessions:
    # For all SESSION resources with MAXIMUM attribute set to the default
    # value of 01,00 change the value to to 99,99  
    - selector:
        maximum: 01,00
      overrides:
        maximum: 99,99
- enqmodel:
    # Select all ENQMODEL resources with an ENQNAME that equals "ENQ*" 
    # and change value to "MYENQ"
    - selector:  
        enqname: 
          - literal: ENQ*
      overrides: 
        enqname: MYENQ