CICS region tagging file
This topic explains the schema and matching algorithm of the CICS® region tagging file.
For an overview of region tagging, see Classifying CICS regions with region tagging.
Schema
The region tagging file is formatted according to the YAML 1.2 standard. YAML files must conform to specific formatting to ensure correct processing.
To help you to format the region tagging YAML file correctly, CICS provides a JSON schema in the JSON Schema Store. Some schema-aware editors, such as Visual Studio Code, PyCharm, and IntelliJ IDEA, support directly downloading schemas from that site.
Alternatively, you can manually apply a schema to relevant files. The schema is also provided with CICS as cicstags-1.0.0.json and it is located in USSHOME/schemas. This schema can be used in a suitable code editor or integrated development environment (IDE) that supports schema validation; for example, Microsoft Visual Studio Code. The schema number increments when updates occur, which helps you to identify when to refresh your schema file in your selected IDE.
Experienced users might want to extend the schema validation to cover how you set up APPLIDs or region user IDs to match your naming conventions. You might also want to extend the schema to validate your custom labels in the YAML file. Extending the schema in this way is recommended only for experienced users.
The matching algorithm for region tags
CICS supports wildcard characters * and ? in the tag's filter
criteria that identify matching regions: APPLID,
RegionUserID, and JobName.
The wildcard character matching works to deliver a best-match result. If the *
wildcard is found, it is treated as the end of the string. The length, L, of a string without an
* is considered to be 8. The length of a string with an * is the
number of characters that precede the *. This count includes any ?
wildcard characters that might also be present. If Q is the number of ? wildcard
characters present and A is the number of * wildcard characters present, a pattern match value is
calculated by using this algorithm:
This algorithm gives more importance to specified characters than to any wildcard. The more actual characters that you specify, the higher the calculated value is. The calculated value is in the range 17 - 1. Zero is returned if no characters at all match.
The table shows examples of APPLIDs or region user IDs with various lengths and wildcard characters and the resulting values. It also shows the rank order that follows from the calculated value. Fully-specified names rank higher than any values that have one or more wildcard characters.
| Name | A (number of *) |
Q (number of ?) |
L (length) | Value | Rank order |
|---|---|---|---|---|---|
| ABCDEFG | 0 | 0 | 8 | 17 | 1 |
| ABCDEFGH | 0 | 0 | 8 | 17 | 1 |
| AB?DEFG | 0 | 1 | 8 | 16 | 2 |
| AB?DEFGH | 0 | 1 | 8 | 16 | 2 |
| AB?D?FG | 0 | 2 | 8 | 15 | 3 |
| AB?D?FGH | 0 | 2 | 8 | 15 | 3 |
| ABCDEF* | 1 | 0 | 6 | 7 | 4 |
| AB?DEF* | 1 | 1 | 6 | 6 | 5 |
| AB?D?F* | 1 | 2 | 6 | 5 | 6 |
| AB* | 1 | 0 | 2 | 3 | 7 |
| * | 1 | 0 | 0 | 1 | 7 |