Setting up CICS region tags

CICS® region tags allow you to classify regions based on the assigned APPLID, region user ID, and job name for the region. You can then use these region tag definitions to aid with auditing, running CICS health checks, or providing categorization information for operators. Region tagging is optional for use in CICS.

For an overview of region tagging, see Classifying CICS regions with region tagging.

The file that is used to specify CICS region tags is distinct from the region-level file for feature toggles. For information about the region-level file for feature toggles, see Setting up a region-level configuration file.

Before you begin

The CICS region tagging file (cicstags.yaml or cicstags.yml) is a YAML file following the YAML 1.2 standard.

You're recommended to install an editor that supports YAML, such as Visual Studio Code, PyCharm, or IntelliJ IDEA, to edit it.

About this task

In a YAML file, a key-value pair is identified by a colon (:), in the format of key: value. This is how you define region tags and their attributes in cicstags.yaml.

A hyphen (-) indicates a list item and indentation (spaces) indicates nesting or hierarchy. You can define a list of tags that are nested within a certain tag type, or a list of attributes for a tag.

Comment lines start with a hash sign (#).

An example cicstags.yaml file is provided as example cicstags.yaml.

Important:

When you edit cicstags.yaml, you must use the single-byte character set (SBCS) elements of UTF-8. For more information, see the Appendix titled EBCDIC and ISO-8 Codes in z/Architecture Principles of Operation.
CICS reads the region tagging file during initialization. If you make changes to your cicstags.yaml file and want the changes to take effect in a running CICS region, use SET TAGS REFRESH to force the CICS region to re-read and parse the tagging file. For more information, see SET TAGS REFRESH.

Procedure

Configure your editor to use the CICS-provided JSON schema for the region tagging file.
- CICS publishes the CICS TS region tagging JSON schema to the JSON Schema Store. If your code editor supports the JSON Schema Store, such as Visual Studio Code, PyCharm, or IntelliJ IDEA, follow its documentation to automatically pull available schemas from the JSON Schema Store into the editor. For example, in Visual Studio Code, you can install the YAML extension and enable automatic synchronization with the JSON Schema Store's catalog, as described in the extension's documentation.
  Figure 1. YAML extension settings in VS Code
- CICS also provides the schema with the product. It's called cicstags-1.0.0.json and located in USSHOME/schemas. Alternatively, you can associate the schema with YAML files manually.
Note: If you create your own tag labels instead of using the CICS-provided ones, you need to edit the schema to validate the labels. Otherwise the custom tag labels might be marked as invalid. For more information about the schema and how to extend it, see CICS region tagging file.
Create a file named cicstags.yaml in the root directory of USSCONFIG. You can customize the sample file provided in USSHOME/samples/cicstags.
The first line identifies the schema in use for this cicstags.yaml, for example:
```
schemaVersion: regionTagging/1.0.0
```
Following the regiontags: line, define tags for region classification.
The syntax must follow this structure:
```
regiontags:
- tagtype:
  - Unique: "Yes | No"              
  - tagkey:                    
    - Tag: "tag name"
    - APPLID: "matching criteria"               
    - Jobname: "matching criteria"
    - RegionUserID: "matching criteria"
```
where:
tagtype

Contains tags of the same type. CICS provides the following three tagtypes.
Each tagtype label has its own associated tagkey that further defines the tag.

cicsts-RegionTypes

Defines the types of region, for example, TOR or AOR.

Contains tag key RegionTag.

cicsts-RegionUsage

Defines region usage, for example, Production, Development, or Sandpit.

Contains tag key UsageTag.

cicsts-Applications

Defines CICS regions that run certain applications, for example, Mortgage, Banking, or Travel.

Contains tag key AppTag.
You can define your own tagtypes and their associated tagkeys, for example:
- MyExtraLabel: - ExtraTag: - Tag: "This_is_a_new_tag" - APPLID: "E*"
If you define your own tag labels, you need to edit the schema to validate the custom labels. Otherwise they might be marked as invalid by the schema. For more information about the schema, see CICS region tagging file.
tagkey

Contains attributes of a given tag, such as the tag name and matching criteria, in the format of key-value pair. CICS provides three tagkey labels.

Each tagkey corresponds to a tagtype label.

RegionTag

Nested in the cicsts-RegionTypes label, it specifies a tag that identifies a group of regions with matching criteria.

UsageTag

Nested in the cicsts-RegionUsage label, it specifies a tag that identifies a group of regions with matching criteria.

AppTag

Nested in the cicsts-Applications label, it specifies a tag that identifies a group of regions with matching criteria.

Unique

Specifies whether the matching regions can apply to multiple tags of the same type (Unique: "No") or only one tag (Unique: "Yes").

If not specified, the default value is used. Unique defaults to Yes for cicsts-RegionUsage tags while No for all the other tagtypes.
The following example shows that a region might be both a TOR and an AOR, which means the region is not unique:
```
- cicsts-RegionTypes:
  - Unique: "No"
  - RegionTag:
    - Tag: "TOR"
    - APPLID: "??T*"
  - RegionTag: 
    - Tag: "AOR"
    - APPLID: "???A*"
```
This examples shows that a region cannot be both a Production and a Development region, which means the region is unique:
```
- cicsts-RegionUsage:
  - Unique: "Yes"
  - UsageTag: 
    - Tag: "Development"
    - APPLID: "DEV*"
  - UsageTag:
    - Tag: "Production"
    - APPLID: "PROD123"
    - Jobname: "PROD*"
```
Tag

Specifies a descriptive name for the defined tag.

APPLID

Defines the matching characteristics of a region's APPLID that identifies it is in the tag group. Valid characters are: 0–9 A–Z # $ * ? @
A match can either be an exact text match with no wildcard characters, or a pattern that uses the wildcard characters. The question mark (?) wildcard represents any single valid character. The asterisk (*) wildcard represents 0 or more characters and must be used only at the end of a string. If a definition applies to all regions, use the * wildcard character as the value for the selected tag.

JobName

Defines the matching characteristics for the region job name that identifies it is in the tag group. Valid characters are: 0–9 A–Z # $ * ? @
A match can either be an exact text match with no wildcard characters, or a pattern that uses the wildcard characters. The question mark (?) wildcard represents any single valid character. The asterisk (*) wildcard represents 0 or more characters and must be used only at the end of a string. If a definition applies to all regions, use the * wildcard character as the value for the selected tag.

RegionUserID

Defines the matching characteristics of a region's user ID that identifies it is in the tag group. Valid characters are: 0–9 A–Z # $ * ? @
A match can either be an exact text match with no wildcard characters, or a pattern that uses the wildcard characters. The question mark (?) wildcard represents any single valid character. The asterisk (*) wildcard represents 0 or more characters and must be used only at the end of a string. If a definition applies to all regions, use the * wildcard character as the value for the selected tag.
Additionally, you can define health check exclusions.
The syntax must follow this structure:
```
- cicsts-HealthCheckExcludedRegions: 
  - ExcludeUsage: "Usage tag name" 

- cicsts-ExcludedHealthChecks:
  - Check: "Message No. Descriptive text"
```
where:
cicsts-HealthCheckExcludedRegions

Contains the regions that are to be excluded from all CICS health checks.

Contains the ExcludeUsage label.

ExcludeUsage

Nested in cicsts-HealthCheckExcludedRegions, it specifies the usage tag of the regions that are to be excluded from all health checks. For example, Development.
Note: The usage tag that is referenced by ExcludeUsage must have been defined on Tag in the UsageTag section.

cicsts-ExcludedHealthChecks

Contains CICS health checks that are to be excluded for all regions.

Contains the Check label.

Check

Nested in the cicsts-ExcludedHealthChecks label, it specifies the health check to be excluded for all regions. The health checks are identified by the message number that issues when the check fails, for example, DFHH0402 or DFHH0409.

The string value must begin with the message number. Optionally, you can add other text for further description. For example, Check: "DFHH0409 RESSEC is set to ASIS."
Checks from the following sets of health checks can be excluded:

CICS_REGION_CONFIGURATION

CICS_RESOURCE_CONFIGURATION

CICS_RESOURCE_SECURITY

CICS_STABILIZED_FUNCTIONS

CICS_USS_CONFIGURATION
Definitions in cicsts-HealthCheckExcludedRegions and cicsts-ExcludedHealthChecks are independent from each other.

For more information about heath checks in CICS, see Reference: Available CICS health checks supported by IBM Health Checker for z/OS.

Results

You have created and configured a CICS regions tagging file cicstags.yaml in the root directory of USSCONFIG.

You can use the Region Tagging view in CICS Explorer® to check what tags are applied to a CICS region or CICSplex. For more information, see Region Tagging view in CICS Explorer documentation.

Example

Example cicstags.yaml:

schemaVersion: regionTagging/1.0.0
regiontags:
# Region type tag example
- cicsts-RegionTypes:
  - Unique: "No"
  - RegionTag:
    - Tag: "TOR"
    - APPLID: "??T*"
  - RegionTag: 
    - Tag: "AOR"
    - APPLID: "???A*"
    - APPLID: "AORS1?D5" 
  - RegionTag:
    - Tag: "QOR"
    - APPLID: "QORTSQ*"   
    - Jobname: "CICSQOR*"

# Region usage tag example
- cicsts-RegionUsage:
  - Unique: "Yes"
  - UsageTag: 
    - Tag: "Development"
    - APPLID: "DEV*"
    - APPLID: "IQWD*"
  - UsageTag:
    - Tag: "Sandpit"
    - RegionUserID: "TEST1" 

# Application tag example
- cicsts-Applications:
  - Unique: "No"
  - AppTag: 
    - Tag: "Banking"
    - APPLID: "B*"
  - AppTag:
    - Tag: "Mortgage"
    - APPLID: "M*"

# User-defined tag examples
- MyExtraLabel:
  - ExtraTag:
    - Tag: "This is a new tag"
    - APPLID: "E*"
- Owning-Department:
  - PurchasingDepartment:
    - Tag: "Purchasing Department"
    - APPLID: "PD*"
  - SalesDepartment:
    - Tag: "Sales Department"
    - APPLID: "SD*"
- Country:
  - UnitedKingdom:
    - Tag: "United Kingdom"
    - APPLID: "????UK*"
  - UnitedStates:
    - Tag: "United States"
    - APPLID: "????US*"

# Exclude regions from all health checks
# Value of ExcludeUsage must match an existing region usage tag
- cicsts-HealthCheckExcludedRegions: 
  - ExcludeUsage: "Development" 
  - ExcludeUsage: "Sandpit"

# Exclude health checks for all regions
- cicsts-ExcludedHealthChecks:
  - Check: "DFHH0401 SEC=NO has been specified."
  - Check: "DFHH0402 XTRAN=NO has been specified."
  - Check: "DFHH0403 XUSER=NO has been specified."