Preparing for Production: Application

chapter includes the following topics:

Overview
For Newcomers to INCONTROL Products and the IOA Environment
Finding Data in Reports and Files
Saving Data as Opposed to Using Local Variables
Implementation Hints
Quality Control and Avoiding Errors
Invoking Control-M/Analyzer from Other Applications in the Processing Environment
Structured Approach for Implementation

Overview

The purpose of this chapter is to provide suggestions and recommendations for implementation of Control-M/Analyzer applications in your production environment. Its primary audience is those responsible for defining balancing applications and rules, and setting standards for user application development.

If you require further detail on any of the options discussed in this chapter, refer to the Control-M/Analyzer for z/OS User Guide.

The first section of this chapter is for those who are not familiar with INCONTROL products or the IOA environment. If you are already familiar with INCONTROL and IOA, you may want to continue with Finding Data in Reports and Files.

For Newcomers to INCONTROL Products and the IOA Environment

The Integrated Operations Architecture (IOA) is the software architecture of the INCONTROL family of Automated Systems Operations products. The purpose of IOA is to establish an operations software environment in which the goal of true unattended operations can be realized.

You interact with all INCONTROL products through the use of a single user-friendly online interface. The interface gives you the capability to control and administer all functions in the automated data center environment from a single terminal. This single user interface is available in every online environment, including TSO/native, TSO/ISPF, CA-ROSCOE, CICS, IMS/DC, COM-PLETE, and VTAM.

All INCONTROL products use a single integrated database containing all production information relating to the operation of all data center functions. This single database facilitates the automation of the links, and the scheduling of events, among the INCONTROL products.

All INCONTROL products are centrally scheduled and coordinated by a single scheduling facility. In this manner, you can specify the entire process through a single scheduling screen. For example, through that single scheduling screen you can

schedule a production job
conduct balancing and quality control of the output report for a job
restart a job in case of job failure
direct the printing and distribution of reports

Further, the single scheduling facility enables the specification of dependent relationships across functions. That is, the occurrence of an event in one automated function, such as the printing of a report, can be made dependent on the occurrence of an event in another function, such as the successful finish of a job.

INCONTROL products are distributed on one installation tape, with an accompanying unified installation process. An automatic maintenance procedure keeps all INCONTROL products at the same maintenance level.

Integrated IOA Activity Log

The integrated IOA Activity Log contains automatically generated messages that record every significant event in the activities supervised by different INCONTROL products. The IOA Log can be viewed online.

Integrated Management Reporting

IOA provides a special report generation language called the KeyStroke Reporting Language (KSL). KSL can be used to generate cross-product reports from a single database.

INCONTROL Products

The integration of INCONTROL products offers you the benefits of

a single application
a common user interface
a single database

The INCONTROL family of products includes:

Table 6 List of INCONTROL Products

Product	Description
Control-M	Automated Production Control and Scheduling System Manages and automates the setup, scheduling and execution of jobs in the data center.
Control-M/Restart	Restart Management System Automates the activities that must be performed when restarting failed jobs, including the scratching and uncataloging of datasets created by failed jobs.
Control-M/Tape	Removable Media Management System Increases utilization of removable media and controls retention periods. Prevents misuse of media, and provides tape library and vault control.
Control-M/Analyzer	Automated Information Integrity System Performs in-stream validation, accuracy, and reasonability checks on information used by data center production tasks (for example, reports, databases).
Control-D	Output Management System Automatically schedules and controls every aspect of report processing and distribution, including report decollating, bundling, printing, online viewing, and archiving.
Control-V	Quick Access Archive Viewing System Provides online access to archived reports and documents by indexed data retrieval.
Control-D/ Page On Demand	Report Retrieval and Display System Enables end users to retrieve and view pages of reports that reside on mainframe storage in real time. Indexed reports can be retrieved by index name and value. AFP and XEROX reports can also be retrieved and displayed using Control-D/WebAccess Server or Control-D/Page On Demand API.
Control-D/Image	Image Output Management System Enables output from commercial imaging equipment to be imported into either Control-D or Control-V for decollation, distribution and viewing, and into Control-V for archiving and indexed retrieval.
Control-O	Console Automation System and Desired State Monitoring System Monitors and automatically responds to messages, commands, and dataset events, as well as various other system events. The Control-O/COSMOS feature allows for status monitoring while maintaining all critical system objects in a desired and ideal status.

Suggested Conventions

You may find it advantageous to have a method of organizing groups, variables, and libraries. If you organize in this way before your applications begin to grow, it will be easier to find and update information within Control-M/Analyzer.

Finding Data in Reports and Files

Usually, when performing a balancing job, you are given a report or file to work with, and that report or file clearly was not designed with Control-M/Analyzer in mind. You may be working with a report that was designed a long time ago, or one that is very complex.

Some of the challenges you may encounter, when searching for data in a report or file are:

knowing when and how to use the NOT EQUAL parameter
the data for which you are searching do not always appear in the same line or place on a report page
difficulty in uniquely identifying data in a WHEN clause
knowing how to use the TYPE AV and TYPE SU parameters

These parameters operate only on numeric data. Therefore, variables that are extracted from a file or report with one of these operators must be numeric.

The following are some suggestions for alternate approaches:

Using the NOT EQUAL Condition to Identify Data

Sometimes a group of report lines or file records can be readily identified because they are the only lines that do not contain certain characters. See, for example, Problem 4: Balance Divisional Accounting Files.

In this example, two types of file records exist—detail records and total records. One way of separating the two types of records is to describe detail records as not having the characters "TOTALINVOICES" in columns 3 through 15.

In using a NOT EQUAL condition, it is important to be 100% precise when specifying the column width. You cannot specify a column range where the string can be found. Instead, you must specify the exact columns where the string is located. This is because Control-M/Analyzer compares the string which it has extracted from the file, character by character, to the string that you specified in the WHEN statement.

For example, what would happen if you were to specify a WHEN parameter to search for detail records as described above? Assume that your WHEN statement specifies columns 1 through 20 for a string NOT EQUAL to TOTALINVOICES. All the detail lines meet the NOTEQUAL search criteria, which is exactly what you expected. But, when the TOTALINVOICES line in the report is examined, it also meets the criteria. This is because a blank in column 1 had been compared to the character "T" from the WHEN statement. Because the blank and the character "T" are not equal, the total line is therefore presented as a detail line.

Data in Different Locations in a Report

Sometimes a line of data that you are looking for cannot be uniquely identified by itself. For example, you might have a sales analysis report that shows detailed sales information for a product, followed by a line of total amounts for that product. Further, the total line has no special characters, such as "TOTAL SALES," with which it can be identified. Also, the number of detail lines occurring before the total line is printed may be any number. Therefore the total line can occur almost anywhere on the page.

For Control-M/Analyzer to be able to find the line, you must establish a unique relationship between this total line and another line.

For example, perhaps the line can always be found two lines before the next product heading, which contains the characters SALES ANALYSIS FOR PRODUCT.

You could then define a WHEN clause that searches for the string "SALES ANALYSIS FOR PRODUCT," and then define a DO EXTRACT from that line, minus 2.

Data that Must Be Associated with External Data before Balancing

Assume, for example, that you have a summary report of all of the accounting transactions for your organization for three months. The report shows the three month time period range as a heading line on the report, but the exact date is not shown within each detail line. However, each detail line does have a transaction number from which it is possible to determine a transaction date by looking up this number in a database, such as DB2, ADABAS, or ORACLE.

The auditing department has asked for a balancing report showing all the transactions for one account number, for one month.

Assume that you can define a WHEN parameter to select all transactions for a given account number from the report. However, to determine the time period to which a transaction belongs, you need to

examine the detail line, which contains a transaction number
find the date with which this transaction is associated
To do this, you have two alternative approaches:
- You can set up a table of variables that provides a transaction date for a range of transaction numbers, and look up the transaction number in this table.
- You can issue a DO CALLUSER parameter. This would call a user-written routine that would look up a transaction number in a database, and return a date to your rule.
use groups of IF statements to determine if this transaction meets your criteria

Problem 6 in chapter 2 illustrates an example of how to set up and use a table of variables.

Saving Data as Opposed to Using Local Variables

Local variables are those variables that are used within a rule, but are not saved permanently. At the time your rule terminates, whatever values that existed in its local variables are wiped from memory.

You may instead want to save these variables in the Control-M/Analyzer database, or in an AutoEdit PDS library member, for the following reasons:

to reference it within other rules
to retain it for an audit trail or for other historic purposes
to have the information online, so you can retrieve at any time
to reference it by other INCONTROL products
to use for "debugging," meaning, to reconstruct what actually happened when a rule has been executed

The following discusses the advantages and disadvantages of either saving variables to the Control-M/Analyzer database, or alternatively, an AutoEdit PDS library member. The nature of the data you need to save in a balancing application will help you determine which of these methods to use.

Saving Data in the Control-M/Analyzer Database

When deciding if you should store variables in the Control-M/Analyzer database, consider the following questions:

Will the data be used by another rule or application?
Is the data required for online viewing?
Are you reasonably certain that the data will be required at some time in the near future?

If you cannot affirmatively answer at least one of these questions, you should consider alternatives to storing data permanently in the database.

An alternative to storing those variables that are only required for debugging or audit trail purposes, is to print the values of the variables in a report. There are two standard reports provided when a rule executes—the SYSUSER report and the SYSPRINT Invocation Report. For debugging and audit trail purposes, it is probably better to print these local variable values using DO PRINT parameters to the Invocation Report.

Saving Data in AutoEdit Members

There are several advantages and disadvantages to saving data in an AutoEdit member as opposed to the Control-M/Analyzer database.

The advantages are:

AutoEdit members are available to other INCONTROL products. They are used mainly by Control-M for JCL setup.
AutoEdit members can contain more than one variable. Therefore, a group of variables can be retrieved into memory by one DO GETMEM parameter.
New variables can be added dynamically to an AutoEdit member by the DO ADDSYM parameter.
The values in the member can be edited and corrected.

The disadvantages are:

Multiple generations, with audit trail information, cannot be automatically maintained by Control-M/Analyzer.
No automatic rollback mechanism is available for AutoEdit members.

Implementation Hints

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

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 Advanced Problems and Solutions 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.

Quality Control and Avoiding Errors

Control-M/Analyzer is a product designed to enhance the data balancing and quality control function within an organization. As such, it should not be exempt from its own quality control procedures.

Within a rule, consider using the quality control techniques described in this section. These techniques can be used during testing of the rule and then removed after testing. For future maintenance, however, you might also consider leaving these quality control techniques in place after testing, but modifying them temporarily so that none of their output is written to the Invocation Report.

Use totals to check that your data selections (WHEN parameters) and other DO actions are correct

You can total numeric fields within the report or file being analyzed. These total amounts can be used to check that an input file or report contains all of the data that you are expecting. This is also a way of verifying that you are, in fact, processing the correct file from the correct source and date.

Once you have established some initial totals, even on fields that you may not be verifying, you can use these as a base or control figure to compare against other balancing actions in the rule. For example, if you are extracting certain sales figures that you believe represent about 10% of the total sales in a report, you can calculate a total on the report lines extracted to see if they do represent about 10% of the total dollar amount of sales.

Have another person check any output which you are producing

When you are focusing on developing rules, you may occasionally miss some obvious errors. An important rule of quality control is to always have one person check the work of another person.

When checking the validity of a rule, use test reports or files which contain many test cases

The greater the variety of error conditions in your test report or file, the greater the chances that your rule will work as expected on the live report. On the other hand, if your test report or file is too large, you will not have the time to check everything it is doing.

After testing with your own "made-up" report or file, use a live report or file

No matter how many conditions you may think of for testing your rule, there are usually some surprises waiting for you in the real data. Before implementing your rule in production, it is a good idea to test it on some actual reports or files, and review the results with users. You may use the Control-M/Analyzer "simulation" mode for this purpose.

Keep the test reports and files, and re-use them when any changes are made to a rule. Compare output after the rule change to previous output

To ensure that you have not overlooked anything when you change a rule, you should have a "base of comparison." The results of the rule before the change should be kept on file, with sample reports and files, and sample outputs produced, including the Invocation Report.

When you make a change, all outputs should be compared.

Run the TRACE facility to debug your rule

The TRACE facility produces a complete printed output of every command executing during rule processing.

Invoking Control-M/Analyzer from Other Applications in the Processing Environment

Within the overall processing environment in your Data Center, you will eventually want to establish a close connection between a Control-M/Analyzer balancing job and other jobs or job steps from other applications and environments.

There are many ways to invoke the Control-M/Analyzer environment from other environments, which can be done

from a job step
from an application program
from the Control-M Production Control System
from the Control-D Output Management System
by a Control-M/Analyzer balancing mission

Invoking the Rule from a Job

Two examples of invoking Control-M/Analyzer include

adding a Control-M/Analyzer step as the last step of a job, to check the outputs of that job
executing a Control-M/Analyzer rule in the middle of a job in order to check an input file prior to a database update

In these cases, you would add a job step to an already existing job in the correct location in that job. This job step would then call the Control-M/Analyzer balancing rule. You would not need to define special scheduling criteria for the balancing rule, as the rule would fit into whatever scheduling criteria are specified for the existing job.

Invoking the Rule from a Balancing Mission

If your Data Center has no job scheduler application, then scheduling and other criteria can be specified within a balancing mission. In this case, a job or job step would be established to invoke the Control-M/Analyzer environment, specifying the mission to be run. For more information on Control-M/Analyzer balancing missions, refer to the Control-M/Analyzer for z/OS User Guide.

Structured Approach for Implementation

Much of the effort involved in implementing a complete balancing system takes place before sitting down at a terminal to define a rule. Users are consulted, the problems are discussed, objectives are established, criteria for determining errors are documented, and desired reports and actions are designed.

To assist you before you get to a terminal, definition templates are provided here. These templates are designed to help data balancing designers organize their thoughts, and to make it subsequently easier to define rules, missions, and variables.