CDEMATCH

Purpose

The CDEMATCH command performs a function similar to a table search. It uses code values that are specified in the automation policy to create a table. You define the table match criteria and a control keyword or result field. Results from the search are returned to the automation procedure and are typically used to alter the automation procedure logic flow or an automation procedure command or reply.

A typical use is to extract feedback and return codes from the message you are automating, and then perform a search in the automation control file using those codes. The result of that search alters the action the automation procedure takes.

Syntax

Notes:

¹ You can define VAR1 - VAR9.

Parameters

MSGTYP=type

This is the value that is entered in the Message id field for the MESSAGES/USER DATA policy item of the automation policy. This policy item is used to define the codes that are to be searched through for a match. MSGTYP is typically coded with the message ID of an automated message, but can also be a pseudo message ID such as CAPMSGS or INGALERT.

CODE1=code1 CODE2=code2 CODE3=code3

These code parameter values are used to search the code entries of the specified message ID for a matching code definition. You must supply at least one code parameter but you can supply all three code parameters, if desired. The code parameters can be specified in any order.

The values for the code parameters may have been extracted as variable values from an automated message but can also be any other values that a matching code definition is searched for. The code parameter values correspond to the related Code fields in the Code Processing panel of the MESSAGES/USER DATA policy item.

ENTRY=entry

This value is:

For APLs - the Subsystem Name
For MTR - the Monitor Entry Name, prefixed with 0
For APG - the Automation Name, prefixed with 1
For MVC - MVSESA

The default value for this parameter is determined by the task global variables SUBSTYPE and SUBSAPPL. If the value of SUBSTYPE is SUBSYSTEM, the value of SUBSAPPL is taken as the default value for the ENTRY parameter. Otherwise, the value of SUBSTYPE is taken as the default value. You must call the AOCQRY command before CDEMATCH for the defaults to work.

VARn

Variables to substitute '&n' placeholders in the value returned. n can be 1 - 9.

Restrictions and Limitations

The CDEMATCH command can be called only by another automation procedure or a command processor.

Return Codes

0: A match was found. The resulting Value Returned of the matching code definition is provided in the task global variable EHKACTION.
1: No match was found.
4: Incorrect parameters were passed to the command.
6: SA z/OS initialization incomplete, unable to process command request.

Usage

When a matching code definition is found in the automation policy for the passed parameters and control is returned to the calling automation procedure, task global variable EHKACTION contains the data from the Value Returned field in the Code Processing panel of the customization dialog. If no matching code definition is found, the value of the task global variable EHKACTION is null.
Code matching specifications in the automation policy are order-dependent. The first matching code definition is used.
Any code parameters (CODE1, CODE2, or CODE3) that are not specified when calling CDEMATCH are considered as matching regardless of what exists in the automation policy.
The format of code matching specifications in the automation policy allows the use of the wildcard characters * and % and the use of comparison operators. For more details about the format of code definitions in the customization dialog see IBM Z® System Automation Defining Automation Policy.

Task Global Variables

EHKACTION: This variable provides the returned value of the matching code definition as specified in the Value Returned field in the Code Processing panel of the customization dialog.
When the return code for CDEMATCH is greater than zero, the value of this variable is null.

Example

This example shows the relationship between CDEMATCH and the automation control file. The message to automate, $HASP095, is produced by the JES2 subsystem and indicates that a catastrophic-level problem has occurred. This example assumes the full message text is passed to the automation procedure. The automation procedure breaks the message apart, calls CDEMATCH to determine whether the error codes are in the automation control file.

The code matching information is specified in the automation policy as follows.

Select the MESSAGES/USER DATA policy item for the JES2 Application object. On the Message Processing panel for the JES2 subsystem enter COD as the action for the message $HASP095.

The Code Processing panel for message $HASP095 is displayed, as shown in Figure 1.

Figure 1. Code Processing Sample Panel

 Code 1          Code 2          Code 3          Value Returned                 
 *               $PJ*                            OPERCANCEL                     
 ERROR*          $K03                            IPLREQ                         
 ERROR*          $K08                            IPLREQ                         
 ERROR*          $K15                            IPLREQ                         
 ABEND*          SA22                            OPERCANCEL

The automation procedure is as follows:

/* REXX CLIST to respond to $HASP095                           */
/* Check whether automation is allowed and set TGLOBALs        */
‘AOCQRY JES2 RECOVERY’
:
/* Get text of triggering message and save it in msg.1         */
’PIPE SAFE * | STEM msg.’

If msg.0 > 0 Then Do
  /* Parse the input message:                                  */
  /* $HASP095 JES2 CATASTROPHIC type.  CODE = cde RC=rc        */
  Parse Var msg.1 ’CATASTROPHIC’ code1 . ’CODE =’ code2 . 
  /* Look for a match                                          */
  ’CDEMATCH MSGTYP=$HASP095,CODE1=’code1’,CODE2=’code2
  Select
    When rc = 0 Then Do /* Match found: check the action field */ 
      ’GLOBALV GETT EHKACTION’ 
      If ehkaction = ’IPLREQ’ Then Do 
        : 
      End 
    End 
    When rc = 1 Then Do /* No match found: warn if required    */  
      : 
    End 
    Otherwise           /* Error: perform warning action       */
      :
  End
End

This is how the automation procedure proceeds:

The automation procedure gets the triggering message $HASP095 from the PIPE default SAFE and stores the only message text line in stem variable msg.1.
The message text is parsed using literal string patterns to extract the error type and the error code in variables code1 and code2. Both values are passed to CDEMATCH as parameters.
According to the code specifications in the automation policy, CDEMATCH first checks the passed error code (code2) for $PJ in the first three characters. This checking traps both $PJ2 and $PJF, which indicate that command $PJES2,ABEND or $PJES2,ABEND,FORCE has been issued.
In the case of a match, CDEMATCH returns the value OPERCANCEL in the task global variable EHKACTION.
If no match occurs for the first code definition, CDEMATCH checks for the error codes $K03, $K08, or $K15 and returns the value IPLREQ if there is a match.
If no match has occurred yet, CDEMATCH checks for the abend code SA22 and returns the value OPERCANCEL if there is a match.
Further processing in the automation procedure depends on whether a matching code definition has been found and, if so, on the returned value of the matching code definition.

When calling CDEMATCH, the ENTRY parameter is not coded and defaults to JES2. This default occurs only if AOCQRY was previously called and task global variable SUBSTYPE is properly filled in. Refer to AOCQRY for more information.