Data Rules

Data Rules represent a key component of TestBench as they allow the database effects of a test run to be proactively checked without requiring further action by the user. TestBench also supports user driven analysis of database effects through the Comp_IT File Comparison facility, described elsewhere in this manual.

Data Rules can be defined at the Global level, Project level or for an individual Test Case. If defined at a Global or Project level then they will be automatically applied to all Test Cases, unless the Data Base Rules Test Option is set to exclude them, or Rules are not active for a Process.

Data Rules can be defined for any physical file or data area and there is no limit to the number of Data Rules that can be defined for an object. TestBench tracks changes to the underlying physical file even if the change was applied through a logical view, and hence rules are still applied to the data.

Data Rules can be used in all aspects of testing, but they are often constructed by Systems Analysts, Database Designers and Technical staff. However, their power to validate can be maximised if they are also applied during later phases of testing such as regression or UAT. With TestBench this does not mean the persons testing at this stage have to understand or be familiar with the rules, as the tests they perform can still benefit from the knowledge invested in the rules by others. For this reason, it is recommended to define rules at the highest appropriate level (such as Global or Project) whenever possible and have only very specific rules defined at the Test Case level.

Data Rules can also be combined into an Integrity Case and in this configuration can be applied to a database outside of the execution of a test. See the separate chapter for more information.
How Data Rules Work
A data rule consists of two main components – WHEN rules (selection conditions) and TEST rules (rules for validating data). The WHEN portion of the rule is used to identify which records the TEST portion can be applied to. This means that different rules can be set up for data in different conditions, for example one rule for Invoices and another for Credit Notes. If there are no WHEN conditions, the rule will apply to all records.

A data rule is only applied to Physical files which have been included in a analysed journal. This is normally a part of a Data Protection or Environment Protection strategy, although a journal included as a Manual Reference in a Test Case will also enable rules to be applied to file effects captured from this journal. A Data Rule can also be applied to a Data Area object which has been included in Data Protection (not supported in Environment Protection) and will apply to the ending data values in the Data Area at the conclusion of the Test Process.

At the end of each Test Process (which appears in results as a sub-run), Data Rules are applied and checked against the File and Data Area effects captured from the Test and any discrepancies are reported as Warnings. The full details of the discrepancy can be viewed side by side with the Data Rule as a Sub-run option.

The TEST portion of a Data Rule contains the data validation specification. This can be created in one of two basic forms:-

  1. Static Rule. Data field compared to static value(s)
  2. Cross-file Data Rules. Data field compared to derived values from a field in another (linked) file/record. Not supported for Data Areas.

A Data Rule may combine both techniques within the same rule.

Data Rule Examples and Conditions
There follows some examples of rules and how these can be used. There are other combinations and possibilities, these are listed to illustrate ways in which Data Rules might be used.
Static rule. Data field to static value.
The operation codes available for a static value rule are:-
DATE Valid Date
EQ Equal To
GE Greater Than or Equal To
GT Greater Than
LE Less Than or Equal To
LIST List Check, value must be one of those listed
LT Less Than
NE Not Equal To
NLIST Not In List
NRANGE Not in Range Check
NSAME Different to before
RANGE Range Check
SAME Same as before
TIME Valid Time

Examples

Possible values for the field ‘STATUS are 0,1,2 and 3.
STATUS RANGE 0 3

REGION is one of four possible values, NE, SE, NW, and SW.
REGION LIST NE SE NW SW

VDATE (eg 2004/06/26) a valid date between 01Jan2004 and 31Dec 2005
VDATE DATE LMD
VDATE RANGE 20040101 20041231

The customer number must be present.
CUST NE 0

Cross-file Data Rules
Cross-file Data Rules are used to validate data in one file against data in another file. This is achieved by linking the first file to the linked file and by using one of the following operation codes:-

COUNT Count the number of records
SUM Summarise the value
MAX Maximum Value
MIN Minimum Value
AVG Average Value
EXISTS Existence Check

Examples

The total price in the header should equal the sum of the invoice line prices in the file INVLIN.
TOTP SUM (invlin.lval), Linked by INV#

Every invoice header should have at least one line.
INV# EXISTS (invlin.inv#)
(no link is required, the link is implied in the above using the same field name)

Similarly, the customer number must exist in the customer master file
CUST EXISTS (custmast.cust#)

The last line number in the invoice file should match the line count in the header file.
LINE MAX (invlin.lin#), Linked by INV#

The last line number count should be the total of the number of invoice lines.
LINE COUNT, linked by INV#

When is a Data Rule on a File Checked?

  1. A file effect must be generated in the journal or journals associated with the Test Case because of an add, or update operation. Whilst delete operations will also generate file effects, rules are not applied to deletes.
  2. The rule must be active. Rules at Test Case, Project and Global level can be set to inactive for a test run.
  3. The data in the record must match any selection (when) conditions for the rule.
  4. The event must match the timing condition for the rule. I.e. the option in a Data Rule to determine if it should be applied to all updates, or only to the final one detected in that process.
    If the above conditions are met for the main file in the rule, the rule checking will be applied at the end of the test process. If this record is also linked to other records in the system (cross-file data rule) then this data also will be used to validate the result in the main file.

Using a Cross File Data Rule
Cross file Data Rules are set up in the normal Data Rule set up screens but use special operation codes. These are:-

SUM. The field in the main file represents the sum of the values of a number of other records. This can only be used for numeric fields.
COUNT. The field in main file is a number which matches the count of a number of records. Numeric fields only.
MAX. The field in the main file is equal to the maximum value found from a number of other records. Numeric fields only.
MIN. The field in the main file is equal to the minimum value found from a number of other records. Numeric fields only.
AVG. The field value in the main file is equal to the average value found from a number of other records. Numeric fields only.
EXISTS. The field value is equal to the value in another record, or an instance thereof can be found in a number of other records.
In all the above cases, the field must be linked to another file and field. This can be the same file as the main file if required.

This is achieved in two parts.

  1. Key in the field on the current file and the operation code as shown below, then press F17.
  2. Fill in the rule definition on the following screen.

Library The library in which the linked file can be found. If the library name is *LIBL, the library list will be used both during rule set up and at the time of the test run. Bear in mind these may be different depending on your current library list values and the settings against the test case.

File The name of the linked file, which can be the same as the file defined in the main part of the Rule.

Member The name of the member to which the rule applies in the linked file.

Field The field which is the subject of the operation code, i.e. which will be summed, averaged, checked for existence etc.

This File/Based On The Rule is executed by linking or joining the record in the main file to the related records in the linked file. This requires a field or a number of fields in both files to have matching data values which can be used to perform this ‘join’. Fields of different names, types and lengths can be linked for the purposes of achieving the join between the two files. Press F4 to select from a list of fields on the files.

Once Enter is pressed on the above screen, the rule definition is formatted and added into the Values column as shown below.

If there are no records retrieved for a link (null return), this will be treated as a failure in most cases except for the following specific examples

COUNT = 0
COUNT <= X
COUNT < X

In which case a null return will be considered as a rule pass.

Library List use in Cross-file Data Rules
The set up and checking of cross file data rules has been designed to enable values in the main file to be validated against any other file whether this other (linked) file is affected by the test or not. The main file must have captured file effects and then the values found in the file effects can be checked to other files and fields. If the linked file to be checked against is in a known static library and is not copied as part of a data protection strategy, you may wish to reference the library name directly, particularly if this library is not part of the test library list.
If however, the file is copied during data protection to the run-time library, you probably want to omit the library name from the set up so that the library list at run time will be used. This facility gives you the choice of checking against a file which is changing during the test or one which is static. File effects are not necessary for the linked file, only for the main file.

Re-Running Rules
It is possible to re-run Static type Data Rules for a set of results to enable corrections to rules to be made without having to repeat the complete test. However, this is not permitted for Cross-file Data Rules as the linked file may be in a different state or may not even exist.

Available Data Rules Display

This screen shows all the Data Rules that have been defined for the current Project or Test Case or all Global Data Rules. You will reach this screen by taking Project level Data Rules from Work With Projects or Work With Test Cases. Alternatively you will reach this screen by taking Test Case level Data Rules from Test Case Maintenance. Global Data Rules are accessed using option ‘16’ from the System Values Menu.

Options

2 – Change This option will take you to Data Rule Details (see specific sections).

3 – Copy This option will allow you to copy the selected Data Rule and all its definition to another Data Rule.

4 – Delete This option will delete all information associated with the Data Rule. A confirmation screen is displayed before the deletion occurs.
5 – View Display all information associated with the Data Rule.

9 – Notes Record notes for the Data Rule. If there are Notes set up against a Data Rule the display shows a ‘¶’ to the left of the code. There are also notes available for the Project, Test Case and for each test run. The Notes Editor is further described in a later chapter, Notes Editor.

Function Keys

F5 – Refresh To refresh the display. The description of this function key will be highlighted whenever details of any Data Rule have been altered through Data Rule Details.

F6 – Add Allows you to add a new Data Rule via Data Rule Details (see below).

Data Rule Details

This screen allows you to define the file or data area for the Data Rule and the details of the rule itself. You will reach this screen from the Available Data Rules display.

Header Entries

These entries must be completed and Enter pressed before you will be able to key the WHEN and TEST details.

Code In Add mode you should key an identifier for the Data Rule which must be unique within the current Project and Data Case. This field cannot be altered in Change mode.

Description Key appropriate text to describe the current Data Rule.

Object Specify a valid physical file name or data area name that will be found in the library.
Library Specify a valid iSeries library name that currently exists, or *LIBL to use the current interactive library list for Project level rules and the Test Case library list for Test Case level rules.

Type Specify either *FILE or *DTAARA to indicate the type of object.

Function Keys

F4 – Prompt To show a list of available entries for Object (within current Type) and Library.

F17/F18 – Use/Maintain AFD
Press F17 to toggle AFD usage on and off for the file to which the Data Rule applies. If no AFD exists for the file either in the specified library or for *LIBL, the AFD maintenance program will be called so that one can be created. AFD usage is ON by default for all new Data Rules where an appropriate AFD exists.
Press F18 to maintain AFD’s.

Data Rule Details – Fields and Values

WHEN and TEST Entries

The details of a Static Data Rule when comparing a field to a static value comprise two parts; ‘WHEN’ and ‘TEST’. The WHEN part defines the criteria under which records from the file or sections of a data area are to be tested. The TEST part defines the criteria that the record or section of the data area must match to satisfy the test. Press F11 to toggle between the two views, the function key is highlighted if any WHEN/TEST entries exist. If any entries are made on a line, then the following validation must be satisfied.

In the case of a cross-file data rule (not supported for Data Areas), there is a third component, the link between the two files.

Data Areas

Reference Key a short description for this section of the data area.

Length Specify the length of the section of a data area that is to be tested.
Start Specify the starting position of the section of a data area that is to be tested. For decimal data areas only the complete length can be validated with a data rule.

Files

Field Specify the name of any field from the current file subject to the field type limitations (refer to Technical Information).

Both

Test Code This must be a valid code that is currently supported for Data Rules. Position the cursor on this field and press F4 to see a list of currently supported Test Codes. The test operation codes of COUNT, SUM, MAX, MIN, AVERAGE and EXISTS are only valid for cross-file type data rules.

Value Key the value with which the Field or data area section is to be tested in combination with the Test Code. Quotation marks are not required for alphanumeric fields, a sign can be keyed in the first position for numeric fields, and values for Date type fields should be keyed with their separator characters.
If the Test Codes RANGE, NRANGE, LIST or NLIST are entered, the values should be keyed one after the other separated by a blank space. If there is not enough room on one line to key the values then F4 provides an extended display.
Press F4 on this field if the Test Codes ‘DATE’ or ‘TIME’ (valid date or time) have been entered. This will give a list of valid Date or Time formats. Enter the format of the field which is to be tested.

The value field is also used to specify the target file and field in a cross-file data rule.  This is entered in the following format (including the parenthesis).
(library/filename.fieldname)
These values must be valid values.  If a separate link has been specified to join the files, an ‘L’ will indicate this to the right of the value field.  In the cases of an EXISTS rule, if a link is not separately specified, the link will be created automatically based on the field name in the Field column and the field specified in the (filename.fieldname) value.  If the library is omitted, the library list will be used, which means that the object will need to be in the current library list as the rule is created, and the library list at run time will be used when checking.

Function Keys

F4 – Prompt To show a list of available entries for Fields, Test Codes, and formats if doing valid Date or Time tests. Provides an extended values entry display if required.

F9 – Insert Add a blank line before the one on which the cursor is currently placed. All following entries will be moved down a line.

F11 – Show WHENs/TESTs
Change between the WHEN conditions which determine under which conditions the test will take place and the TEST which defines the actual criteria that must be met. This function key is highlighted if any WHEN/TEST entries exist.

F14 – Sample Data To access the Sample Data facility where the actual data from the current file will be shown according to cursor position.

F17 – Links This function key accesses the window to enter links between the main file and a related file for cross file data rules. If a link has been set up already for a line in a Data Rule, an ‘L’ is shown to the right of the Value field. See earlier section on defining links.

Sample Data
This facility shows the values of a single selected field in a maximum of the first eighty records. You will reach this screen by pressing F14=Prompt on any of the Field Names in Data Rule Details. This can assist in the choice of the correct field or value for the rule.