Global Options

These options can be accessed from the Utilities and System Setup menu. They control all settings that can be applied at the global or system level throughout the product.

Script Exceptions
Fields to be excluded from comparison for all scripts played back in TestDrive or ‘Natively’ on the iSeries. See specific sections on Exceptions in the TestDrive and Native R&P chapters for further information.

Joblog Message Exceptions
When a test is executed, all joblog messages are stored in the results database and it is also possible to define an error severity for a Test Case which, if reached, causes a warning message to be generated. However, there may be instances where a specific message id is expected during a test but whose severity would generate an unwanted warning message. In this case the message id can be excluded, as can specific message types or sending programs, for all Test Cases on the system.

This option is also available at the Project and Test Case levels.

Manual References
This provides a means to alter by inclusion or exclusion the list of objects to be protected during a test and the references defined here will be applied to all Test Cases on the system. This option also exists at the Test Case level. Individual objects and objects implied from a program can be specified for or excluded from protection in a Test Case. Data analysis can also be achieved without data protection by specifying a journal to analyse. Further information can be found in the Test Data Protection section in the Testing chapter.

Program Parameter Definitions
The following display enables programs which have complex parameter structures which either cannot be accessed via source scanning or need to be modified from the program definition to be defined and stored here. When a Test Case is defined for one of these programs, pressing F8 to retrieve the existing definition will retrieve the parameter structure as it has been saved here.

2 – Change Modify the parameter structure for a program which has already been defined.

4 – Delete Remove the program and its parameters.

F6 – Add Add a new program. The source of the program is scanned for the parameter definitions which can then be modified prior to being saved.

Data Rule Definitions
Any Data Rules entered here will be applied to all Test Cases executed within all Projects within TestBench. Data Rules can also be specified at the Project and Test Case levels. Further information can be found in the Data Rules section in the Testing chapter.

User Exits
User Exit Commands can be defined to allow additional processing to be executed during the course of a Test Case, Data Case or Comp Case execution. When the option is selected, a screen is displayed which enables the type of User Exit (Test, Data or Comp) to be chosen. Any User Exits entered here for Test Cases, for example, will be applied to all Test Cases executed within all Projects within TestBench.

User Exit Commands can be defined at the Global, Project and individual Test Case, Data Case and Comp Case levels to allow additional processing to be executed during the course of a Test Run, Data Run or Comp Case Run. These commands can be defined in several places:

• From the Global Options menu (Global level).
• Option ‘19’ on the Work With Projects display (Project level).
• F18 from Work With Test Cases (Project level).
• F18 from Test Case Maintenance (Test Case level).
• F22 from the Test Run Score Sheet which is accessed by pressing the Escape or Attention key during a Test Run.
• F18 from Work With Data Cases (Project level).
• F18 from Data Case Objects (Data Case level).
• F18 from Work With Comp Cases (Project level).
• F18 from Comp Case Objects (Comp Case level).

Any rules defined at the Global level apply to all Cases within the entire TestBench system and those at the Project level will be executed by every Case within the Project.

Seq Use this value to alter the command processing sequence within User Exit type.

When Determines at which point in the execution the command will be run. See the following sections for more information.

Active Key a ‘2’ if this command should not be executed.

Prompt Key a ‘1’ if you wish the prompt screen for the command to appear at run time.

F15 – Substitution Variables
The available variables which can be used in the User Exit command are listed below for each Case type.

The additional processing performed by User Exits can be executed at various points during the Test, Data or Comp Case execution. These exit point differ slightly according to the Case type being run. There are also different substitution variables that can be used.

Test Cases
The following exit points are available for Test Cases.

Description Code Notes
Before BN The Test environment has not yet been created Environment
Before All BA All elements of the environment have been created and a Test Run Header exists at a ‘Running’ status. Objects to be protected have not yet been duplicated.
Before Each BE All elements of a Test Sub-run have been created including the control record.
Before Submit BS Immediately prior to the SBMJOB command being issued.
Before Rollback BR Prior to any rollback to an environment checkpoint via the ROLL_IT command.
After Rollback AR After any rollback to an environment checkpoint via the ROLL_IT command.
After Submit AS The submitted job has completed.
After Each AE All elements of a Test Sub-run are still available although the associated control record will be marked as completed.
After All AA All elements of the Test Run are still available.
After Environment AN The Test environment has been deleted.

The following substitution variables are available for Test Cases.

Code Description
&EL Environment Library
&PR Project ID
&CN Test Case ID
&TR Test Run ID
&SR Sub Run ID
&RD Run Description
&DD Day
&MM Month
&YY Year (2)
&LL Year (4)
&JN Job Name
&J# Job Number
&JU Job User

Data Cases
The following exit points are available for all Data Cases.

Description Code Notes
Before BN The environment has not yet been created
Environment
Before All BA Before the data in the first file is copied.
Before Each BE Before the data in each file is copied.
After Each AE After each target file is populated with data.
After All AA After all target files have been populated with data.
After AN The environment has been deleted.
Environment

The following exit points are available for Remote Data Cases only and will be executed on the remote server.

Description Code Notes
Before All RA Before the data in the first file is copied.
Before Each RB Before the data in each file is copied.
After Each RY After each target file is populated with data.
After Each RZ After each target file is populated with data.
After FTP RF After the FTP transfer process

The following substitution variables are available for Data Cases.

Code Description
&PR Project ID
&CN Case ID
&DD Day
&MM Month
&YY Year (2)
&LL Year (4)
&JN Job Name
&J# Job Number
&JU Job User
&OL Object Library
&ON Object Name
&OT Object Type
&MB Member
&TL Target Library
&RL Remote Data Library
&RS Restore Data Library

Comp Cases
The following exit points are available for Comp Cases.

Description Code Notes
Before All BA Before any of the files are compared.
Before Each BE Before each file pair is compared.
After Each AE After each file pair is compared.
After All AA After all file comparisons have finished.

The following substitution variables are available for Comp Cases.

Code Description
&PR Project ID
&CN Case ID
&DD Day
&MM Month
&YY Year (2)
&LL Year (4)
&JN Job Name
&J# Job Number
&JU Job User
&AL File A Library
&AF File A File Name
&AM File A Member
&BL File B Library
&BF File B File Name
&BM File B Member

Processing Sequence
a) Global User Exits are executed first. Then commands specified at a Project level are executed before those defined at a Case level.
b) Within each level the commands are processed according to their sequence.

Processing Errors
Any errors in User Exit Commands are monitored and the Job Log will record the details of the processing failure. They are also reported as Run Warnings, but you are responsible for ensuring that your commands achieve your intended results.

Example: Start Commitment Control
If you are testing a program which opens files under commitment control but does not start the commitment environment itself (STRCMTCTL), by default the program under test will crash. There are two ways of tackling this issue. Firstly, you could start the test by calling the higher level program containing the commitment environment through the Process Command options. Here we explore an alternative approach.

Create at either the Project or Test Case level the following entries:
a) As a ‘Before All’, specify the command: STRCMTCTL LCKLVL(*CHG)
b) As an ‘After Each’ consider whether you need to issue the commitment commands: COMMIT or ROLLBACK
c) As an ‘After All’, specify the command: ENDCMTCTL
This will ensure that the commitment environment is active for the program under test.

Example: Incrementing Dates
If you need to exercise a program many times at different dates using TestBench’s control of the job date, you may also wish to move your data in line with each program execution. User Exit Points allow this to be elegantly achieved:

a) As a ‘Before Each’ specify the command after ensuring that the Warp Case exists:

WARP_IT PROJECT(xxxxxxxxxx) WARPCASE(xxxxxxxxxx)

This will cause the dates to be aged in accordance with the defined Warp factors. You should ensure that the Processes ask for the Database to be reset before each run otherwise the incremental effect will not occur. (Note that you should not attempt to warp the versions of the file in the temporary run time library as these represent the data state at the end of the run, not the start).
In this case the files in the Warp Case will be physically updated irrelevant of the Data Protection selected, so if the initial file states will be required again, you should take backup copies, potentially by additional User Exit Commands.
Example: Comparing Spool Files
If you are executing a test from which spool files are produced, you may wish to compare these either with previous tests or with a base line copy of a report which is known to show the correct results. Firstly, create two physical files with a record length of 198 (the maximum report length). Use the CPYSPLF command to copy the base line report into one of the files. You may need to specify parameters such as Spooled File Number to identify the correct report. Then set up a compare case to do a sequential comparison (compare type 1) of the two files. User Exit Points can then be used as follows:

a) As an ‘After Each’ use the CPYSPLF command to copy your spool file into the other physical file previously created. The SPLNBR(*LAST) ensures that if there are multiple copies of the report on the spool queue the most recent will be used:

    CPYSPLF  FILE(PRINTKEY) TOFILE(SPOOLFILE/                      
                LIBRARY) SPLNBR(*LAST)

b) Create another ‘After Each’ or ‘After All’ User Exit to execute the COMP_IT command for the Compare Case previously created:

    COMP_IT PROJECT(xxxxxxxxxx) COMPCASE
                (xxxxxxxxxx)  

This Compare Case will report any differences between the same lines on each report.

To give a more meaningful result, Alternate File Descriptions can be used to tailor specific areas of the report for comparison. Use the substring facility to split each report line into fields which can be selected for comparison in COMP_IT.

Environment Exclusions
This options enables any files which should be excluded from journaling and therefore from the rollback process to be defined. After using this option, the Test Environment must be scanned and any checkpoints re-set in order for the changes to take effect. Please refer to the Test Environments chapter for more information.

Library Scan and Replace
This function enables the TestBench database to be searched for a specific library name and replaced with an alternative library. This is particularly useful when information within an existing TestBench Project is being re-used for a new release of the application which is using different test libraries.

Scan for Library All occurrences of this library will be scanned for within the TestBench modules that have been included in the scan. There is no validation on this field as the old library may already have been deleted.

Replace with Library The library that will replace the library being scanned for. There is no validation on this field as the new library may not yet have been created.

Confirm Updates If this option is set to ‘1’, every time an occurrence of the library being scanned for is found, a confirmation screen is displayed at which point the library can be replaced or retained. Any further confirmation screens can also be switched off at this time. If this is set to ‘2’ no confirmation screens are displayed, all instances of the library being scanned for are replaced with the new library.

Scan Project Key *ALL if all Projects within the TestBench database are to be scanned, or enter an individual Project name.

Perform Precheck There are several errors which may prevent the successful execution of the scan and replace and these are all included on the report which is produced at the end of every execution. It is however possible to get advance notice of any issues by running the pre-check. Examples of these errors are:
• Security prevents the User from performing the action.
• The TestBench object is being locked by another User.
• An AFD of the same name already exists in the replacement library.
The following warnings are also reported but do not prevent the library replacement from occurring:
• The object does not exist in the new library.
• The replacement will cause duplicate library names in the library list.

Include Modules Specify which areas of TestBench are to be included in the scan and replace.
• Test Cases: Processes, job description, library list, target library for keeping data, manual reference libraries for journals.
• Data Cases: Objects, job description, target library.
• Comp Cases: Object libraries.
• Warp Cases: Object libraries, synchronised scrambling fields user exit program library and master file library.
• Integrity Cases: Object Libraries.
• Action Maps: Commands, Data Case target library, library list, job description.
• Data Rules: Object libraries. Please note that Global Data Rules are only included if the scan Project is *ALL.
• User Exits: Commands.
• AFDs: Object library.

Pre-check Warnings
If the Perform Precheck option is set to ‘1’ the following screen is displayed which lists all potential issues with the library replacement. Some errors prevent the successful replacement of that item whereas others are warnings only, see above for examples.

5 – Display Message View the full warning text.

Update Confirmation
There are four different formats for the confirmation screen, one each for simple values such as Test Case Processes, Library Lists, Commands and AFDs.

Confirm Update Option ‘1’ is the default value which will cause the library to be replaced with the new value, option ‘2’ will leave the existing library in place.

F8 – Bypass Do not show any more confirmation screens, all further occurrences of the library will automatically be replaced.

NOTE: When a command is updated all instances of the library name within the command will be changed and the replaced library name will always be in upper case. It is however possible that commands may be incorrectly changed, for example if we take the existing command:

CPYF FROMFILE(SBASSETT2/TBPPRO) TOFILE(QTEMP/TBPPRO)

Scan library: SBASSETT Replace library: SBISHOP

New command:
CPYF FROMFILE(SBISHOP2/TBPPRO) TOFILE(QTEMP/TBPPRO)

The new library SBISHOP2 is incorrect and in such circumstances the confirm updates option should be used.

Cross Function Audit Enquiry
As well as the ability to view audit trail information for each Project, Case or Script within TestBench, it is also possible to view all audit trail information using this function. The information can limited by User ID, and also includes any deletions which would not otherwise be seen.

F8 – Expand/Drop View script name and the program creating the audit trail record.

Product Groups
Product Groups are used for integration with some Change Management systems to automatically identify which Test Cases should be executed as part of a promotion. Each Test Case and Script can have an associated Product Group and these are maintained on the following panel.

2 – Change Modify the Product Group description.

4 – Delete Remove the Product Group. If this Group is associated with a Test Case or Script an error message is displayed and the deletion will not proceed. Use option ‘6’ to identify where this Product Group is being used and remove the linkages before attempting the deletion again.

6 – Where used Display a list of all Test Cases and Scripts which are part of this Product Group. If you are using a participating Change Management System (see individual White Papers for further information), these are the Test Cases or Scripts that will be automatically executed during a promotion when this Product Group has been selected.

F6 – Add Create a new Product Group which can then be added to a Test Case or Script.

Report Compare Rule Definitions
As part of a test execution it is possible to capture the reports generated during the test and store these with the rest of the test run results. An option against the Test Case determines whether all reports, no reports or only specified reports are captured. If the option to capture only specified reports is selected, the report name and user data will be compared to all entries in the Work With Reports list shown below and only if there is a match will the report be captured.

In addition to helping to determine which reports are captured, these screens also assist with the report comparison function which runs as part of result comparison. When two test runs are compared, their reports can also be compared. With a pure line by line comparison, as soon as one of the reports had an additional or missing line, the rest of the report lines would be compared incorrectly and therefore show in error. To avoid this, rules can be created for a report which control how the comparison should take place.

2 – Define Modify the User Data and description of the report that will be captured.

3 – Copy This option is useful if you have multiple reports for which a similar set of rules is required. When option 3 is taken you can select the name and User Data of the new report. You can then optionally copy the report layout and report comparison rules to the new definition.

4 – Delete Remove the report definition.

5 – Rules Create the rules which will control how reports stored against the two test runs are compared.

F6 – Capture Capture a report which exists on a spool queue and add it to the Work With Reports list.

Locate the sample report on the spool queue and specify the parameters which allow it to be uniquely identified and captured. By default only the first 3 pages and final 2 pages of the report will be captured, this will usually be enough of a sample to enable the rules to be defined. However these options can be modified to capture additional pages if necessary.

Once a report has been captured, key an option 5 to define the rules to display a screen similar to the one below. The report sample is shown to the right of the screen, the rules that define the comparison to the left. The width assigned to each of these can be changed by using the mouse to left click anywhere along the ruler line at the top of the display.

Please note that blank lines are automatically excluded from the comparison. When a spooled file is captured, only lines with data are included.

Page Up/Page Down Scroll the captured report up and down.

F13/F14 Rules Up/Down Scroll the rule definitions up and down.

F19/F20 Left/Right Scroll the captured report left and right.

Key Breaks
Reports, by their nature, list different sets of data one after the other in a similar layout. This predictability allows us to identify where a new data set begins. The top of a report will often have some static text which is normally accompanied by a value. An example would be a printed invoice which may read “Invoice Number: 000123”. By recording the position of this invoice number we can create a unique identifier which can help in matching the reports, ensuring that data for the a specific invoice number on one report is compared to the same invoice number on the second report regardless of position within the reports.

In the above example two key breaks exist. A Batch Number appears on the fist line of the report sample (off the screen to the right) and the Product Code appears in a column part way down. It would therefore be possible to match each line by both of these identifiers, rather than relying on the data being reported in the exact same sequence.

Please note that if two key breaks are created on the same line, they are added in creation sequence. The user must add the higher key first, values are not sorted according to their position on the line.

Right click anywhere beneath the Key Breaks title to display the following options.

Create Add a new key break, see below for more information.
Edit Edit the selected key break.

Delete Remove the selected key break.

When the Create option is selected, the following screen is displayed.

Any Line The key break could be found on any line number on the report.

Fixed Line The key break will always be found on the specific line number for which the break has been defined.

Then perform the following actions to define the key break.

• Click Next to re-display the captured report with a message at the bottom of the screen reading ‘Select the break text’.

• Use the left mouse button to click on the beginning of the text that defines the break value, in the above examples this would be ‘Batch’ or ‘CODE’. Once this is done another message ‘Click on the end of the break text’ is displayed.

• Left click the final word of the text defining the break value. The message ‘Now click on the break value’ is displayed at the bottom of the screen.

• Now repeat the previous two steps to define the break value, in our example this would be product code ‘33208’. Once this is done the text and value will be highlighted, along with all instances of the key break across the entire captured report as shown below.

• If you are defining a column where the value is on a line below the break text, an additional screen is displayed where the start and end positions of the data in the column must be specified. See the Column Value Location option below for a full explanation of the three options. If your column has no title, select the first value as the title. Then once the column break has been defined, edit the break and change it to be a fixed line break.

Once a key break has been created, it can be edited by right clicking and selecting the Edit option.

Line number If this is a fixed line key break, the report line number containing the break text is shown here. Please note that because blank lines are not included on the report capture, this may not equate to the visible line number on the display. If this is an any line key break the line number will be zero.

Control text The text that is used to identify the break value. This can be modified if a report changes.

Text Start Column The start column position of the text which defines the break value. This can be modified if a report changes.

Control Value Start Column, Length and Type
The position, length and type of the break value. These can be modified if the report layout changes.

Break Type If the control text is on the same line as the key value, this will be a Line break. If however the value is beneath the control text, this is a Column break.

Column Value Location
For column breaks, this option determines where the corresponding break value begins and ends. If the value in the column is always the same length then choose option 1. If however the value is a piece of text that can vary in length, choose option 2. Finally if the value is a number which can vary in length and is right aligned on the report, choose option 3.

Include previous lines If there is some information on previous lines on the report that relates to this key value, set this option to ‘1’.

Number of lines to include
If the previous option is set to ‘1’ then this is the number of previous report lines that relate to this key value.
Format Breaks
Format breaks provide a means of re-starting the comparison for a report. Once a format break is encountered, the line matching begins again, so if there were different numbers of lines on the two reports which had caused previous lines to match incorrectly, this will be resolved from the format break onwards.

Right click anywhere beneath the Format Breaks title to display the following options.

Create Add a new format break, see below for more information.

Edit Edit the selected format break.

Delete Remove the selected format break.

When the Create option is selected, the following screen is displayed.

Any Line The format break could be found on any line number on the report.

Fixed Line The format break will always be found on the specific line number for which the break has been defined.

Then perform the following actions to define the format break.

• Click Next to re-display the captured report with a message at the bottom of the screen reading ‘Select the break text’.

• Use the left mouse button to click on the beginning of the text that defines the break, for example it could be a sub-heading called ‘Totals’. Once this is done another message ‘Click on the end of the break text’ is displayed.

• Left click the final word of the text defining the break. The captured report is displayed with all instances of the format break highlighted.

Once a format break has been created, it can be edited by right clicking and selecting the Edit option.

Line number If this is a fixed line format break, the report line number containing the break text is shown here. Please note that because blank lines are not included on the report capture, this may not equate to the visible line number on the display. If this is an any line format break the line number will be zero.

Break text The text that is used to identify the format break. This can be modified if a report changes.

Text Start Column The start column position of the text which defines the format break. This can be modified if a report changes.

Include previous lines If the format break should actually begin on a previous line, set this option to ‘1’.

Number of lines If the previous option is set to ‘1’ then this is the number of previous report lines that are included in this format break.

Exclusions
There may be specific values or even sections of a report that are likely to differ between test runs, but these differences are expected and therefore should not be reported as errors in report comparison results.

Headers and Footers
These include sections at the beginning and end of each page on the report that will be excluded from the comparison. Right click the Headers or Footers text and click the Create option, then click on either the last line of the header or the fist line of the footer on the report image. All preceding/following lines respectively will then be excluded. Once a header or footer has been set, Edit and Delete right click options are also available.

Other Exclusions
Right click the text ‘None’ and select the ‘Create’ option to add a new exclusion. The following screen is displayed.

Exclude Value Create an exclusion for a specific location on the report. You will prompted to enter a description for this exclusion. Then messages will ask you to click on the start and end of the value on the captured report. Following this, any value that overlaps the horizontal position of this value will be excluded.

Exclude Conditioned Value
This excludes a location on the report, but only if the specified qualifying text is also found. You will be prompted via messages to define the qualifying text and value using mouse clicks on the captured report.

Exclude Line This excludes an entire line on the report if the specified qualifying text is found on that line. You will be prompted via messages to define the qualifying text using mouse clicks on the captured report.

Any Line The exclusion can be applied to any line number on the report.

Fixed Line The exclusion will always be found on the specific line number against which the exclusion has been defined.

Global Exclusion This exclusion will be applied to the entire report, regardless of any key or format breaks that have been defined.

Break Exclusion The exclusion will only be applied to the key or format break inside which it has been defined. Please note that for these types of exclusions, if the break is deleted then the exclusion is also removed.

Environment Scan and Replace
This function enables Test Cases within the TestBench database to be searched for a specific test Environment and replaced with an alternative one. This is particularly useful when information within an existing TestBench Project is being re-used for a new release of the application which is using different test databases.

Scan for Environment All occurrences of this Test Environment will be scanned for within the Test Cases that have been included in the scan. Use F4 to select from a list of valid Test Environments.

Replace with Library The Test Environment that will replace the one being scanned for. Use F4 to select from a list of valid Test Environments.

Confirm Updates If this option is set to ‘1’, every time an occurrence of the Test Environment being scanned for is found, a confirmation screen is displayed at which point the Environment can be replaced or retained. Any further confirmation screens can also be switched off at this time. If this is set to ‘2’ no confirmation screens are displayed, all instances of the Environment being scanned for are replaced with the new one.

If a confirmation has been requested, the following screen is displayed.

Confirm Update Option ‘1’ is the default value which will cause the Test Environment on the Test Case to be replaced with the new value, option ‘2’ will leave the existing Test Environment in place.

F8 – Bypass Do not show any more confirmation screens, all further occurrences of the Test Environment will automatically be replaced.

A report is generated at the end of the process which lists out all Test Cases which have had their values changed.