TPL rule syntax

WHEN MATCH "search expression" THEN <ACTION>

     WHEN <location range> MATCH "search expression"
     THEN BEGIN
       <ACTION>;
       <ACTION>;
     END

• "search expression" is a regular expression enclosed in quotes. Output Manager supports POSIX-compliant regular expressions in the text-matching search string of TPL rules. For more information on creating regular expressions for the TPL search string, see Regular expressions in TPL search strings.
• <location range> is an optional parameter that specifies the input lines on which the search expression must match. Valid values may include: BEFORE LINE <line>, BEFORE PAGE <page>, AFTER LINE <line>, and AFTER PAGE <page>. You can specify multiple location values, but each location type may only be specified once. For example: WHEN BEFORE LINE 120.
  Note: It is not recommended to use location range values for selectors that process MSGCLASS SYSOUT. The order that SAPI delivers these data sets to Output Manager cannot be determined in advance.
• <ACTION>: is the action to be performed when the search expression criteria is matched. Valid values include WTO, STOP, HIGHLIGHT, SET ARCNAME, and SET COND.
  Note: You can only reset the condition code when a match is found in NON-JES2 datasets.
  • WTO (ROUTE=n, DESCRIPTOR=n) "output string": When the search expression is matched, issue a Write To Operator (WTO) message. "Output string" is the text of the WTO, up to 126 characters long, to be written to the operator. This string must be enclosed in quotes and can include any combination of the following:
    • ROUTE and DESCRIPTOR: Optionally, you can specify the route code and descriptor code for the WTO. The defaults are 0. If you specify ROUTE and DESCRIPTOR, you must use the following format:

      WTO (ROUTE=nn, DESCRIPTOR=nn) "output string"

      Note: In order to specify the ROUTE and DESCRIPTOR options, you must have a detailed knowledge of MVS™ system messages. See the "Routing codes" and "Descriptor codes" sections of the MVS System Messages InfoCenter for more information. At the time of publication, these sections can be found at https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.ieam600/route.htm, and https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.ieam600/desc.htm.
    • output string: Any text included in the quotes of the output string not prefaced by the & (ampersand) symbol will be used as literal text to be written to the operator. Note: Because the primary purpose of WTOs is to drive system automation processes, it is recommended that the first word of the WTO output string be a unique message ID. Discuss installation-specific standards with your automation team.
    • &0 (ampersand zero): the text that was matched by the entire search expression)
    • &(integer): the text of a fragment of the matched search expression, where integer is the number of a marked subexpression of the search expression, &1 being the first fragment enclosed in parentheses, &2 being the second, etc.
    • JES variables associated with the job that generated the SYSOUT that the selector or subselector matched: &JOBNAME, &JOBID, &STEPNAME, &DEST, &WRITER.
    • &DSNAME: the name of the ITOM archive data set name that the data is being written to. For example: "msgnnnx MSGCLASS FLAG DETECTED, JOB:&JOBNAME, JESNUM:&JOBID"
  • STOP: When the search expression matches a SYSOUT, Output Manager stops TPL processing for that SYSOUT, after the matched TPL rule ends. No TPL rules linked to this selector will execute for the remaining records in this SYSOUT data set. For example, to find only the first occurrence of "foo", include the STOP action:

    WHEN MATCH "FOO" THEN BEGIN WTO "FOUND FOO";
     STOP;
    END

    To find all occurrences of "foo", do not include the STOP action:

    WHEN MATCH "FOO" THEN BEGIN WTO "FOUND FOO"

  • HIGHLIGHT (COLOR="RED | PINK | BLUE | TURQUOISE | GREEN | YELLOW | WHITE", STYLE="USCORE|REVERSE", INTENSITY="HIGH|LOW") "&n": When the search expression criteria is matched, highlight the matching text. The format of the highlight is determined by the COLOR, STYLE, and INTENSITY options. The text &n parameter specifies which part of the matching text is highlighted.
    • COLOR: Specifies the color of the highlight. Color values include RED, PINK, BLUE, TURQUOISE, GREEN, YELLOW, or WHITE, and must be surrounded by quotation marks. Alternatively, you can specify the RGB value of a color, or RGB values in hex. For example, HIGHLIGHT (COLOR="#FF0000" or COLOR="RED").
    • STYLE: Optional stylistic changes to the highlighted text. Valid values include USCORE (underscore) and REVERSE (reverses the highlight color with the text color), and must be surrounded by quotation marks.
      Note: When REVERSE is specified, Output Manager selects the color of the text by determining which color (either black or white) provides the most contrast with the specified highlight color. If the highlight is a light color, such as yellow, the font color is black. If the highlight is a dark color, such as black, the font color is white.
    • INTENSITY: Optional stylistic change that modifies the intensity of the color of the highlighted text. Valid values are HIGH and LOW, and must be surrounded by quotation marks. HIGH uses more saturated colors (values of #FF for each RGB component). LOW uses muted colors (#80 for each component.)
    • &n: Specifies which part of the matching text to highlight. If &0 (ampersand zero) is specified, highlight the text that was matched by the entire search expression. If &(n) is specified, highlight only the text of a fragment of the matched search expression, where integer is the number of a marked subexpression of the search expression, &1 being the first fragment enclosed in parentheses, &2 being the second, etc.

      The following examples would match the line of text "HELLO ABC WORLD", but the words highlighted differ based on the &n option:

      WHEN MATCH ".* ABC" THEN HIGHLIGHT (COLOR="RED", STYLE="USCORE", INTENSITY="HIGH") "&0"

      would highlight "HELLO ABC", but WORLD would not be highlighted.

      WHEN MATCH ".* (ABC)" THEN HIGHLIGHT (COLOR="RED", STYLE="USCORE", INTENSITY="HIGH") "&1"

      would highlight ABC, but HELLO and WORLD would not be highlighted.