EVALDEF (Evaluation definitions)

An evaluation definition identifies the resources in one or more CICS® systems that are to be sampled and evaluated. (For more information about these resources, see the CICSPlex SM Resource Tables Reference book.) When the result of the evaluation is true, an associated analysis definition is used to determine if a notifiable condition has occurred. Examples of how to use this view can be found in Example tasks: real-time analysis.

To display information about existing evaluation definitions, issue the command:

   EVALDEF [evaldef]

where evaldef is the specific or generic name of an evaluation definition. If you omit this parameter, the resulting view, illustrated in Figure 15, includes information about all evaluation definitions for the CICSplex identified as the context.

Figure 15. The EVALDEF view
 27FEB2005  18:29:18 ----------- INFORMATION DISPLAY ---------------------------
 COMMAND  ===>                                                 SCROLL ===> PAGE
 CURR WIN ===> 1        ALT WIN ===>
  W1 =EVALDEF===========EYUPLX01=EYUPLX01=27FEB2005==18:29:18=CPSM=========10===
 CMD Name     Table    Column Name  Intvl Description
 --- -------- -------- ------------ ----- ------------------------------
     EYURTELC MAS                      60 SSet - Licence
     EYURTE01 CONNECT  CONNSTATUS     300 SSet - All connections
     EYURTE02 LOCFILE  ENABLESTATUS    60 SSet - Local File DFHCSD
     EYURTE16 LOCFILE  EMPTYSTATUS    300 SSet - Empty required on files
     EYURTE17 DBCTLSS  MAXTHRDCNT     300 SSet - DBCTL maxthreads
     EYURTE18 CICSRGN  DTRPROGRAM     300 SSet - DTR not set correctly
     EYURTE19 CICSRGN  MONSTAT        300 SSet - MONITORING inactive
     EYURTE20 CICSDSA  PCTFREE        300 SSet - DSA free space
     EYURTE21 EVENT                   300 SSet - Outstanding EVENTs
     EYURTE22 TRANDUMP TDMPSUPP       300 SSet - Dump suppression
 

Action commands

Table 12 summarizes the action commands you can use with the EVALDEF view.

Table 12. EVALDEF view action commands
Primary command Line command Description
n/a BRO Browse an evaluation definition in the data repository.

The format of the resulting panel is similar to that shown in Figure 16. The panel fields are not modifiable.

CREate CRE Create an evaluation definition and add it to the data repository, as described in Creating an evaluation definition.

When you use the primary command CREate, some fields in the new view may contain values supplied by CICSPlex® SM; you may change these values. When you enter the line command CRE next to the name of an evaluation definition, fields in the new view contain values to be modelled (from the existing evaluation definition).

n/a MAP Display a visual map of real-time analysis definitions using the specified definition as a starting point.
n/a REM Remove an evaluation definition from the data repository.
TEMPMP cmasid n/a Change the temporary maintenance point CMAS to a specific CMAS or display a selection list based on a generic CMAS ID.
n/a UPD Update an evaluation definition in the data repository.

The format of the resulting panel is similar to the panel shown in Figure 16. You can modify the contents of any field in the panel except Name.

Hyperlink fields

There are no hyperlink fields on the EVALDEF view.

Creating an evaluation definition

When you use the create primary (CREate) or line (CRE) action command from the EVALDEF view, a sequence of two panels is produced. The first panel includes all of the fields that are required to create an evaluation definition. The second panel contains optional fields for qualifying the evaluation and defining modifications to be made when the specified condition becomes true.

Figure 16 shows the format of the first panel produced when you are creating an evaluation definition.

Figure 16. Creating an evaluation definition - Page 1
 ------------------- Create Evaluation Definition for EYUPLX01------------------
 COMMAND  ===>
 
 Name                  ===> EYURTE01
 Description           ===> Evaluate transaction status
 
 Sample Interval       ===> 60           Interval between samples in seconds
 Table Name            ===> LOCTRAN      Resource Table Name or *
 Instance Pattern      ===> *            Specific or generic pattern
 Result Set Action     ===> ANY          Operation (ALL,ANY,SUM,MIN,MAX,AVG,CNT)
 Separate Task         ===> NO           Run as a separate task (YES, NO)
 
 Evaluation Column     ===> STATUS       Column name to evaluate or *
     either Operator   ===> NE           (EQ,NE,LT,GT,LE,GE)
            Value      ===> ENABLED
            Severity   ===> HS           (VLS,LS,LW,HW,HS,VHS)
 
     or set Thresholds:     Provide 3 low and/or 3 high values, N=Normal
 VLS          LS          LW    (N)    HW          HS         VHS
 
 
 View Invoked          ===> LOCTRAN      View invoked for this Evaluation
 
 
 Type DOWN or UP to view other Evaluation Definition screens.
 Press Enter to create Evaluation Definition.
 Type END or CANCEL to cancel without creating.

Provide the following information, as appropriate.

Name
Specify a 1- to 8-character name for the evaluation definition. The name can contain alphabetic, numeric, or national characters. However, the first character must be alphabetic.
Description
(Optional) Specify a 1- to 30-character description of the definition.
Sample Interval
Specify how long, in seconds, CICSPlex SM is to wait between the collection of sample data. The value must be between 1 and 86400.

If the Table Name field identifies a monitor resource table and monitoring for that resource category is active, this sample interval value is ignored. Instead, the sample interval specified for the appropriate monitor specification is used. To prevent this from occurring, specify the equivalent operations resource table in the Table Name field, rather than the monitor table.

Table Name
Enter the specific or generic name of a CICSPlex SM resource table that identifies the resource category you want to evaluate. If you specify a generic value, a list of valid resource tables is displayed.

Start of changeWhen specifying a table name, consider where the evaluation definition and its associated analysis definition will be installed. The definitions may be installed in a variety of CICSPlex SM managed CICS systems, however, not all resource tables are supported in all CICS systems. Therefore, when the definitions are installed, CICSPlex SM determines whether the target system supports the resource table.End of change

Refer to the CICSPlex SM Resource Tables Reference book for a detailed description of each table.

Instance Pattern
Enter a specific resource name or a pattern for the resource occurrences you want to evaluate. A pattern can include the characters + (plus sign), * (asterisk), or both.
Result Set Action
Specify how the information about the resource occurrences is to be evaluated, as:
ALL
Compare the information against the evaluation criteria. If the result shows all occurrences of the resource within the current sample are true, set a true condition.

This action is not supported when evaluating threshold values.

ANY
Compare the information against the evaluation criteria. If the result shows any occurrence of the resource within the current sample is true, set a true condition.

This action is not supported when evaluating threshold values.

AVG
Process the information and compare the resulting average value against the evaluation criteria. If the result for the current sample is true, set the condition true.

This action is available for numeric data only. If you specify this action, you cannot request a modification operation in the Modification String expression field.

CNT
Compare the number of resource occurrences against the evaluation criteria. If the result for the current sample is true, set the condition true.

If you specify this action, you cannot request a modification operation in the Modification string expression field.

Start of changeYou cannot specify an evaluation column with CNT.End of change

MAX
Process the information and compare the resulting maximum value against the evaluation criteria. If the result for the current sample is true, set the condition true.
MIN
Process the information and compare the resulting minimum value against the evaluation criteria. If the result for the current sample is true, set the condition true.
SUM
Total the information and compare the sum against the evaluation criteria. If the result for the current sample is true, set the condition true.

This action is available for numeric data only. If you specify this action, you cannot request a modification operation in the Modification string expression field.

Separate Task
Specify YES or NO to indicate whether the evaluation process should run as a separate task.

The default value of NO allows the evaluation process to run under the MAS long running task (LRT). Depending on the type of evaluation and the number of resources involved, running under the LRT may prevent user tasks with the same priority (255) from running.

If you specify YES, a separate task (COIR) is started to process this evaluation definition. The priority of the task is set according to the value of the COIRTASKPRI system parameter.

Note:
If COIRTASKPRI is set to 0, a separate task is not started for any evaluation definition. For a description of COIRTASKPRI, see the CICS Transaction Server for z/OS® Installation Guide book.
Evaluation Column
Enter the specific or generic name of a column in the specified resource table that is to be part of the evaluation criteria. If you specify a generic value, a list of the columns in that resource table is displayed.

After identifying the column to be evaluated, you must determine the type of evaluation to be performed. You can specify either an evaluation value and its associated operator and severity, or evaluation threshold values. Note, however, that these two types of evaluation are mutually exclusive.

Use evaluation values when your criteria involves numeric data, keywords (such as ENABLED, OPEN, or YES), or Boolean operators. To use a value as your evaluation criteria, specify the following:

Operator
The logical operator to be used in determining if the contents of the evaluation column meet the evaluation criteria. The valid operators are:
LT
Less than
LE
Less than or equal to
EQ
Equal to
GE
Greater than or equal to
GT
Greater than
NE
Not equal to
Value
An alphanumeric value or keyword to be used in determining if the contents of the evaluation column meet the evaluation criteria. This value must be a valid attribute value for the resource table column being evaluated. The value must be a valid output value if the attribute is a CVDA datatype.
Severity
The severity level to be assigned when the resource occurrence meets the evaluation criteria. The severity levels are:
VLS
Very low severe
LS
Low severe
LW
Low warning
HW
High warning
HS
High severe
VHS
Very high severe

In Figure 16, for example, if a local transaction (LOCTRAN) is found to have a status not equal to ENABLED, the evaluation is true and a severity of high severe (HS) is assigned.

Alternatively, you can establish a range of threshold values for the resource occurrence that, if met, result in varying severity levels. To use thresholds as your evaluation criteria, specify the following:

Thresholds
A threshold value for each severity level. The value type and its format must be valid for the evaluation column you specified. Threshold values are used to assign a severity level to resource occurrences that meet the evaluation criteria.

For severity levels to the left of normal (N), the specified threshold is the upper bound. For severity levels to the right of normal (N), the specified threshold is the lower bound.

For example, if the evaluation thresholds are:

  VLS     LS     LW    (N)    HW     HS     VHS
    1      3      5           7      9      11
 

then:

  • a value of 4 produces a severity level of LW.
  • a value of 6 indicates the resource is within its normal range.
  • a value of 8 produces a severity level of HW.

You may specify the values in either ascending or descending numerical order.

Also, it is possible to specify unidirectional thresholds, evaluating for only a high or low condition, but not both. To use only half of the evaluation threshold range, specify threshold values either for VLS, LS, and LW or for VHS, HS, and HW. When you specify values for only half of the threshold range, the fields in the other half must be blank.

View Invoked
(Optional) Specify the name of the CICSPlex SM view that is to appear in the View field of the EVENTDTL view when a notifiable condition occurs. This field should identify the view associated with the resource table specified in the Table Name field.

If the evaluation definition is complete, press Enter to add it to the data repository. If you want to qualify the evaluation or define modifications to be made, issue the DOWN command.

Figure 17 shows the format of the panel produced when you issue the DOWN command.

Figure 17. Creating an evaluation definition - Page 2
 ------------------- Create Evaluation Definition for EYUPLX01------------------
 COMMAND  ===>
 
 Name                  ===> EYURTE01
 
 Filter string expression:  (Use FILTER command to list columns)
 ===> PROGRAM=AB* AND (USECOUNT>0 OR RESTARTCNT>0).
 ===>
 ===>
 ===>
 ===>
 ===>
 ===>
 ===>
 ===>
 ===>
 
 Modification string expression:  (Use MODIFY command to list alterable columns)
 ===> STATUS=ENABLED.
 ===>
 ===>
 ===>
 
 Type DOWN or UP to view other Evaluation Definition screens.
 Press Enter to create Evaluation Definition.
 Type END or CANCEL to cancel without creating.

Provide the following information, as appropriate.

Filter string expression
(Optional) Identifies attributes in the specified resource table that are to be used to qualify the condition described in the Evaluation Column fields.

In Figure 17, for example, only those local transactions that have a first program name beginning with AB and either a use count greater than 0 or a restart count greater than 0 are evaluated.

A filter expression can be made up of one or more attribute expressions in the form:

Read syntax diagramSkip visual syntax diagramFilter Expression
 
>>-| logic_expr |--.-------------------------------------------><
 
logic_expr:
 
   .-AND/OR----------------------------.
   V                                   |
|----+-----+--+-| attr_expr |--------+-+------------------------|
     '-NOT-'  '-(--| logic_expr |--)-'
 
attr_expr:
 
|--attr--oper--value--------------------------------------------|
 

where:

attr
Is the name of an attribute in the resource table. You can name the same attribute more than once in a filter expression.
oper
Is one of the following comparison operators:
<
Less than
<=
Less than or equal to
=
Equal to
>=
Greater than or equal to
>
Greater than
¬=
Not equal to
value
Is the value for which the attribute is being tested. The value must be a valid one for the attribute. The value must be a valid output value if the attribute is a CVDA datatype.

If the attribute accepts character data, this value can be a generic. Generic values can contain:

  • An asterisk (*), to represent any number of characters, including zero. The asterisk must be the last or only character in the specified value. For example:
      TRANID=PAY*
  • A plus sign (+), to represent a single character. A + can appear in one or more positions in the specified value. For example:
      TRANID=PAY++96

If the value contains imbedded blanks or special characters (such as periods, commas, or equal signs), the entire value string must be enclosed in single quotes. For example:

  TERMID=‘Z AB’

To include a single quote or apostrophe in a value, you must repeat the character, like this:

  DESCRIPTION=‘October''s Payroll’
AND/OR
Combines attribute expressions into compound logic expressions using the logical operators AND and OR, like this:
  attr_expr AND attr_expr.

Filter expressions are evaluated from left to right. You can use parentheses to vary the meaning of a filter expression. For example, this expression:

  attr_expr AND (attr_expr OR attr_expr).

has a different meaning than this one:

  (attr_expr AND attr_expr) OR attr_expr.
NOT
Negates one or more attribute expressions.

You can negate a single attribute expression, like this:

  NOT attr_expr

You can also negate multiple attribute expressions or even a whole filter expression, like this:

  NOT (attr_expr OR attr_expr).

Note that you must place parentheses around the attribute expressions (or the filter expression) to be negated.

To see a list of the attributes in the resource table, type FILTER in the COMMAND field and press Enter. Figure 18 shows the format of the panel produced when you issue the FILTER command. For more information on these attributes, see the CICSPlex SM Resource Tables Reference book.

Figure 18. List of attributes in a resource table
-------------------------- List of CICSplex Resources------------- Row 1 of 34
COMMAND ===>                                                    Scroll ==> PAGE
Available columns in resource table: LOCTRAN
 
 
ColumnName   Type   Len   Description
------------ ------ ----- ------------------------------
CMDSEC       CVDAS  00004 Command security
DTB          CVDAS  00004 Dynamic Trans Bacout Option
DTIMEOUT     BINARY 00004 Data Timeout
DUMPING      CVDAS  00004 Dumping Option
INDOUBTWAIT  CVDAS  00004 Transaction Indoubtwait option
ISOLATEST    CVDAS  00004 Isolation status
LOCALCNT     BINARY 00004 Times run local via DTR
PRIORITY     BINARY 00004 Priority
PROFILE      CHAR   00008 Transaction Profile
PROGRAM      CHAR   00008 First program name
PURGEABILITY CVDAS  00004 Purgability ( SPURGE )
RUNAWAY      BINARY 00004 Runaway time in milliseconds
RUNAWAYTYPE  CVDAS  00004 Runaway time type              
Modification string expression
(Optional) Identifies attributes in the specified resource table that are to be modified if the condition described by this evaluation definition becomes true.
Note:
CICSPlex SM attempts to perform the requested modification only once. If the modification is not successful for any reason (such as the resource is in use or is not available), it is not retried. If the condition generates a CICSPlex SM event, the event remains displayed on the EVENT view, if the modification cannot be made.

A modification expression can be made up of one or more attribute expressions in the form:

Read syntax diagramSkip visual syntax diagramModification Expression
 
   .-,--------------.
   V                |
>>---attr--=--value-+--.---------------------------------------><
 

where:

attr
Is the name of a modifiable attribute in the resource table.
value
Is the value to which you want the attribute set. The following restrictions apply:
  • The value must be a valid one for the attribute.
  • If the value contains imbedded blanks or special characters (such as periods, commas, or equal signs), the entire value string must be enclosed in single quotes, like this:
      DESCRIPTION=‘Payroll.OCT’
  • To include a single quote or apostrophe in a value, you must repeat the character, like this:
      DESCRIPTION=‘October''s Payroll’
  • The value must be a valid output value if the attribute is a CVDA datatype.

To see a list of attributes in the resource table that can be modified, type MODIFY in the COMMAND field and press Enter. Figure 19 shows the format of the panel produced when you issue the MODIFY command. For more information on these attributes, see the CICSPlex SM Resource Tables Reference book.

Figure 19. List of modifiable attributes in a resource table
-------------------------- List of CICSplex Resources------------- Row 1 of 10
COMMAND ===>                                                    Scroll ==> PAGE
 
Available columns in resource table: LOCTRAN
 
 
ColumnName   Type   Len   Description
------------ ------ ----- ------------------------------
DUMPING      CVDAS  00004 Dumping Option
PRIORITY     BINARY 00004 Priority
PURGEABILITY CVDAS  00004 Purgability ( SPURGE )
RUNAWAY      BINARY 00004 Runaway time in milliseconds
RUNAWAYTYPE  CVDAS  00004 Runaway time type
SHUTDOWN     CVDAS  00004 Shutdown run status
STATUS       CVDAS  00004 Enabled Status
TRACING      CVDAS  00004 Tracing option
TRANCLASS    CHAR   00008 Transaction Class
TRANID       CHAR   00008 Name
**************************** Bottom of Data *********************************
Note:
You cannot specify a modification expression when:
[[ Contents Previous Page | Next Page Index ]]