Rule Definition

When you are ready to define your first Control-M/Analyzer rules, consider the following implementation hints:

Build and test your rule piece by piece

• Start with simple WHEN statements that extract data from a file or report. Test the success of the WHEN statements by printing some data you've extracted. The Invocation Report will tell you if you have successfully defined the ON block—meaning, if the WHEN search criteria were actually met.
• Add a simple DO BLOCK parameter to analyze the data that was found in the WHEN parameter. Use DO PRINT parameters to verify that each DO action you are taking has done what you expected it to do. Test your rule again.
• Add an ON block that will handle the termination of the rule. Test the rule again, and check the Invocation Report to see if the rule ended as you anticipated, with the proper user code.
• Review the many examples of rule definition in this guide and in the Control-M/Analyzer for z/OS User Guide.

Do research before working online

Before beginning to work online, determine the following:

• what external data you need to analyze, such as reports, files, or Control-D compressed files
• what will be the file and report layout
• how do you identify the data you want to analyze
• what internal data, such as a database and AutoEdit variables, do you need
• what analysis do you want to perform
• what database or AutoEdit variables do you need to commit if the rule executes OK
• under what conditions do you consider the balancing result OK, tolerable, or NOTOK—and what codes will be used to indicate the various possible results?

Many people prefer to work out these details on paper, before approaching the computer terminal. To assist you, a series of organized forms has been provided in Structured Approach for Implementation.

Analyze unexpected results

When the unexpected happens after executing a rule, use the following facilities to trace the steps the rule took:

• Run the TRACE Facility

  Run the TRACE facility to examine Control-M/Analyzer commands while a rule is executing and after its termination. When a trace run is requested, and during rule execution, the Control-M/Analyzer commands of the rule being executed are printed by block. The TRACE facility is also discussed in detail in the Control-M/Analyzer for z/OS User Guide.

• Use the Invocation Report

  The Invocation Report tells you which ON blocks have been executed, from the very start of the rule until the rule terminated. This is done using an ENTERING BLOCK print line, which shows the name of the ON block executed, and what type of block it is, such as FILE, SYSOUT, or DATA. The report also shows each line printed with a DO PRINT parameter, each variable committed with a DO COMMIT parameter, and other selected actions. At the end of the rule, the Invocation Report shows how the rule ended, how many variables were committed, and any resulting user code.

• Add parameters to the rule to print values of local variables and other information that can help you analyze what the rule is doing

  There are some actions, such as results of DO SET parameters, which the Invocation Report does not automatically show. If you believe that your unexpected results are because of changes in local variable values caused by a DO SET parameter, you can easily trace this. All that you need to do is add selective DO PRINT instructions in your rule to print the values of these local variables as they are changed.

  If you are using more than one such DO PRINT lines then you may wish to identify where they came from in the printout by putting a line number in the remark, or putting the actual DO SET instruction in the remark.

• Change a parameter specification slightly

  For example, you may be using WHEN clauses to search for a string in your report. Unexpectedly, Control-M/Analyzer does not find the data for which you are searching. Yet when you look at the report, you see that the data exists, and the characters for which you are searching are exactly as you expected them to be.

  By making a small change in your parameter specification, it may give you a clue as to why the desired data are not being located. For example, you may have defined the length of the string, or the positions (columns, or line numbers to search in), incorrectly. Try specifying a broader or a narrower column or line range.

  Try changing a .NE. (not equal) search string to an .EQ. (equal) or a .GE. (greater than or equal to) condition. Try embedding the string you are searching for in quotes if it contains any blanks or special characters.

• Check each WHEN statement separately

  If you have a complex compound WHEN statement, try checking each WHEN specification separately. First, ensure that the outermost WHEN finds its string in each line of the report or file. When you are sure that this specification is working, add the next WHEN statement.

• Ask another Control-M/Analyzer user for help

  As the Control-M/Analyzer expertise builds in your organization, help will be readily at hand. You may also take advantage of support from your supplier.

Use short ON blocks rather than long ON blocks

There are times when you can write an entire rule within one or two ON blocks. There are two occasions when it may be desirable to split one long ON block into two or more ON blocks:

• Unnecessary duplication within the rule definition

  Assume the following:

  • every time the rule prints a line, it follows the printed line with two blank lines and two lines consisting of all dashes
  • the rule prints 30 different lines in the report

  With all of the DO PRINT instructions in one ON block, there would be an extra 120 DO PRINT instructions (4 times 30) for the separator lines. On the other hand, if you set up a separate PRINT block in the rule, you would have to write the print instructions for the separator lines only once and then issue a DO BLOCK instruction 30 times, saving a net of 90 instructions.

• Better tracing through the Invocation Report

  The Invocation Report shows which ON blocks of your rule have been executed. Sometimes an ON block uses labels so that a separate part of the ON block can be executed repeatedly. See Problems 4, 5, and 6, in Chapter 2 for examples of this structure.

  In this case, the processing flow that occurs when these labelled parts of an ON block are executed would not be readily discernible from the Invocation Report. If, instead, you split the ON block into multiple ON blocks, it may be easier to use the report to trace what is happening in the rule.

Using the Control-M/Analyzer Rule Definition Editor versus the System Editor

Rules can be defined using the Control-M/Analyzer Rule Definition facility or by using a standard system editor. Until you are very familiar with the syntax of Control-M/Analyzer rules, it is highly recommended that you use the Control-M/Analyzer Rule Definition facility.

The Control-M/Analyzer Rule Definition facility contains many helpful messages. When you omit a parameter, or fill it in incorrectly, the rule definition editor informs you immediately. It also uses a fill-in-the-blanks approach, avoiding the need to know the syntax of the parameters.