Introduction
The background data, parameters and environment information for a test are stored in a Test Case. Test Cases themselves are organised into Projects. This information is then used when the Test is executed from the Work With Test Cases display, or by running the command Test_IT.
A program to be tested can be initiated either by a CALL instruction with associated parameters, or by issuing the appropriate command (CMD), and in both cases will be held as a Process within the Test Case. Several Processes can be defined for a single Test Case and will be run sequentially when the Test is executed. This enables the same program to be run with multiple parameter sets, or different related functions to be initiated one after the other.
The Test Case is also used to organise the results produced for each run, and is a way of selecting data to be included in a Test Report using Report_IT.
How to Create a New Test Case
The following is a summary of the typical steps involved in setting up a Test Case. Further details of each screen and function are found in later sections.
1 If required, set up a new Project.
2 Use Work With Test Cases and F6 to create the new Test Case with a new Test Case code. Alternatively use the CRTTSTCSE command.
3 You are automatically prompted to define the first Process for the test. Enter the program/library that you are interested in testing, or if this program cannot be successfully initiated using a CALL instruction, enter a command which can be used to access it. If the command is complex, this information can be retrieved from a version of the job that is already running or has been queued. This is the top level of your test and it may include references to other programs which are called, which also make up part of the test.
Both the program/library and command fields can be left blank if this Test Case will never actually be executed but will simply be used to store interactive scripts and notes.
4 On pressing Enter if a program/library has been defined and the program has parameters the source is automatically scanned for parameter definitions. These are presented on screen for modification.
5 Pressing Enter again enables the parameter values to be defined. Complete the values for each calling parameter, and if you wish, how the parameter values are expected to be at the completion of the program execution. The ending parameter values will be monitored by TestBench.
6 The Test Case has now been created. Depending on how you want it to work, you may wish to use some or all of the following steps to set up additional optional features.
7 Once back at the Maintain a Test Case screen further Processes can be defined by pressing F6.
8 F21 enables Test level options to be set up. Key in a job date if the current job date is not going to be used, and number of increments if this date is to be advanced and the test run again each time.
9 Choose whether the data used by the program(s) is to be protected from update by TestBench.
The choices are:
Named Library The objects in a designated library are all protected, regardless of which ones a program under test uses.
*PGMREF All files and Data Areas used by the program under test, and any programs it calls are protected. Protected objects are copied at the start of the test.
*PGM The files and Data Areas used by the program named in the Test Case set up are protected (excluding those used by other programs called). Protected objects are copied at the start of the test.
*NONE No objects are protected. The files and data areas to be used and updated are those found in the library list, or accessed by the program.
*DYNAMIC Objects are protected only when the program referencing them is called.
The above protection options are only valid by default when a program has been specified to be called, rather than the test being started with a command. References for the command processing program will only be included if the ‘Expand command references’ system level option has been set to yes. This option however is not valid for *DYNAMIC type protection.
*ENV Use in conjunction with the ‘Environment’ option to specify a Test Environment to be used when running the Test Case. See separate section Test Environments.
*DIRECT All objects (regardless of how they are accessed) are protected for the program(s) defined as a Process in the Test Case. Then if subsequent programs are called, then all files for the called program will be copied at that time. This is an alternative to *DYNAMIC as it shortcuts the program analysis upfront at the beginning of the test execution.
NOTE Additional objects to be protected (or excluded from protection) can be specified as manual references. If no program is specified, data protection must be a library name or *NONE. Also, a Test Environment can be specified as an alternative to Data Protection.
See sections Test Data Protection and Test Environments for additional information.
10 Decide whether calls to RTVSYSVAL (Retrieve System Value) for the system date and OVRDBF (Override Database File) which might by-pass the library list and protected file should cause the test to be aborted.
11 Default Process settings are updated by pressing F22, and are modified for individual Processes with option 7. Enter decisions on error severity and associated actions, and other flags which are described fully later in the section. If required, the database can be reset to the starting point between each Process.
12 Press F7 to define the library list the programs will require at the start of the job. The library list will be taken from the first available in the following sequence – Environment, Test Case, current. If the library list is not defined for either the Environment or the Test Case, the current library list will be used at run time (or the default from the job description if submitted). If a library list is specified for a Test Case, and the Test Case is linked to an Environment which also has a library list, the Test Case library list will be ignored at run time.
13 Press F10 to define any initial values for the Local Data Area.
14 If using a different job date, enter option 11 against the Process to check each programs usage of system date from the source. If TestBench has not been able to give a clear result, you may wish to check the source manually. If the system date is used by the program, this will bypass the effect of altering the job date and hence may not provide the full date environment required for the test.
15 Manual References can be set up by pressing F19 to specify protection/analysis in addition to that in the Test Data option.
16 F18 enables user-defined commands to be executed at specified points in the Test Run.
17 The program can now be tested. Further data can be set up to assist in the test and verification of the results as follows.
18 F15 Test Items. Use this to define the items from a test script or check lists that are to be examined during the test. This can then be used to keep track of progress against the check list during the test.
19 F16 Data Rules. Data rules can be defined for the Test Case (as well as for all tests in a Project or at a Global level) to check all the updates to protected files during a test run. See the separate section on Data Rules.
20 F8 Intercepts. If the program under test is intended to call another program during its execution, the call to this second program can be intercepted. The parameter values passed may be logged for later diagnosis or substituted by TestBench with values defined for the parameters that TestBench should return to the calling program as if the real program had been called.
See the separate section on Program Interception.
Work with Test Cases – Details
The following panel can be accessed in several ways:-
• Option ‘12’ from the TestBench Main Menu.
• Option ‘12’ against a Project on the Work with Projects display.
• Option ‘9’ against a program within a Plan Case.
• From the WRKTSTCSE command.
Test Cases contain the core information about the programs to be tested, the required environment for the test, and how the test run is to be carried out. A Test Case can be executed from Work With Test Cases, or by calling the command Test_IT.
Limit Key a character or characters to subset the display to records that have the same initial key values. Leave blank to have all records available via scrolling (or page up/down). When entering a ‘Limit To’ value, this will always be used for the ‘Position To’ value in the first instance. Once the ‘Limit To’ range has been established on the screen a ‘Position To’ may also be specified. The last value keyed is stored for each user and will automatically be defaulted into this field when the same panel is next accessed.
Posn This is a volatile field which will position records on the display starting with the characters keyed. Hence, this enables you to move quickly to the end of a long list and from there scroll up or down as required. If entered at the same time as the ‘Limit To’ field, ‘Position To’ will be ignored the next time the enter key is pressed. Once the ‘Limit To’ has been established, ‘Position to can also be keyed. If the ‘Position To’ is outside the range of available records, the display will either start or end with the closest records.
Program Display Test Cases which reference a particular program only.
Options
1 – Run Test Start a test for a Test Case that has already been set up. This has the same effect as calling the command Test_IT, and starts the Test Run Initiation dialogue. This process is described in the following section – Running a Test.
2 – Change To amend the set up of an existing Test Case.
3 – Copy To create a copy of this Test Case, and all its subsidiary information such as Processes and Data Rules. The copy can be in another Project.
4 – Delete This option will delete all information associated with a Test Case, including results of previous runs. A warning is displayed before the delete process begins.
5 – View Display all information associated with the Test Case. See later section for more information.
6 – Report_IT Produces the Test Run report for the selected Test Case. You can choose what level of information is to be printed. See the separate section on Report_IT.
8 – Audit Data Every addition, update and deletion is tracked and displayed.
9 – Notes Record notes for the Test Case which can be included on the Test Report document produced by Report_IT. If there are Notes set up against a Test Case the display shows a ‘¶’ to the left of the Test Case code. There are also notes available for the Project, and for each test run. The Notes Editor is further described in a later chapter, Notes Editor.
10 – Playback Initiate the playback of an existing script. See later section – ‘Native’ Record and Playback.
11 – Record Initiate the recording of a new script using ‘Native’ recording. See later section for details.
20 – Scripts Scripts recorded using the interactive record and playback module TestDrive or the ‘Native’ recording functions and stored against this Test Case can be viewed and modified. See the ‘Native’ Record and Playback chapter for details about these functions.
21 – Results Access details of previous Test Runs. This accesses the same information available through the command WrkTstRun, except WrkTstRun shows runs initiated by a user and this option shows all results for the Test Case in chronological order. This is further described in the later chapter, Results.
22 – Summary Provide summary information about the most recent test runs for this Test Case. See later Results chapter for more information.
Function Keys
F6 – Add Create a new Test Case. Alternatively the CRTTSTCSE command can be used.
F8 – Expand/Fold Alternate view of Work with Test Cases showing the first line of notes for each Test Case in the list.
F16 – Data Rules Data rules can be set up at three levels in TestBench, Global, Project and Test Case. They are used to check the updates to protected or analysed files and to verify that each affected record meets the criteria specified in the rule. Project level rules will normally be applied to all Test Cases in a Project, unless they are turned off during an individual test run. See separate section on Data Rules.
F18 – User Exits User Exits can be set up at three levels in TestBench, Global, Project and Test Case. These enable additional processing to be executed at several points during a Test Run. See the System chapter for more information.
F19 – Environments Provides a link to the Work with Test Case Environments screen which can also be accessed using option ‘23’ from the TestBench main menu.
F20-Joblog Exceptions Define job log message ids, message types or sending programs for this Project that will not generate a warning message in results if the error severity threshold defined in Test Case Process settings has been reached. See the specific section in the System chapter for more information.
Test Case Set Up – Additional Information
Having created the initial Test Case details, you may immediately want to add the additional information which is described further below.
Option 2 from the Work With Test Cases display enables details of a Test Case to be amended. A Test Case comprises Processes, each of which may be a call to a program or a command. They may be several calls to one program, or separate tasks including a combination of interactive and batch processes.
There is a special TestBench command which can be added as a Test Case Process called TBWAIT which will pause the test until all of the previous jobs have ended. Optionally enter a number of seconds as a parameter. A value of 12 means that TestBench will check all previous jobs every 12 seconds for completion, no entry means that there is no time delay between checks.
This can be used to simulate real life situations when there would normally be a time delay between certain steps in a process occurring, allowing time for any batch processing to complete.
All components of the Test Case are available via the function keys and options from this screen, for example:-
• Parameter names, lengths and values for the programs to be tested
• Calling command strings to be used instead of parameter values
• Library list to run the Test
• Programs to be intercepted when called, and substitute parameter values to be returned
• Initial Local Data Area values
• Notes about the Test Case
• Test items from the Test Plan which should be tested
• Data rules to be applied to files and data areas during the test
• Manual references which specify data protection and analysis in addition to that in the Test Data option
• User Exit commands to be executed at specified intervals in the Test Run
• Interactive scripts which are stored against this Test Case
Options
2– Change Redefine the starting point for the Process by modifying the execution program and parameters, or the command which will be used to initiate the test. A message will be displayed if the Test Case is already in use.
3– Copy Create a duplicate of the Test Process definition which will appear after the last Process on the screen.
4– Dlt Remove the Process definition from the Test Case.
6– Parms This will retrieve the current parameter names, lengths and data types from the source (CL, COBOL, RPG, and RPG ILE) if available, and if no parameters have already been defined. If the source is not available, the list will show the known number of parameters for the object and the name and length/type information can be entered. If the program object changes in any way since the Process was set up, you will be required by TestBench to confirm the details and possibly map the old parameter list to the new one. This screen is displayed automatically when a new Process is created.
7– Options Default Process Settings which will be used for all new Processes can be defined for the Test Case. These can be refined for each individual Process using option 7, and are described in detail later in this section.
8– Parm Vals Define the parameter values to be used when calling the program under test, and optionally enter values the program is expected to return at the end of the test.
9 – Notes Record notes for the Test Case Process which can be included on the Test Report document produced by Report_IT. If there are Notes set up the display shows a ‘¶’ to the left of the Test Case Process. 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.
11– Dates This function helps check the source code (currently fixed format only) of an RPG or CL program for usage of system date retrieval operations. If the source is available and when scanned obtains a status of OK, the job date will successfully define the date environment for the program. If the status indicates possible QDATE usage, the program may be using the system date and further analysis of the source code is required to confirm this.
Function Keys
F6 – Add Process Define further Test Processes and use the Sequence Number to determine the order in which the programs will be executed.
F7 – Libl This is used to define the initial library list required to execute the programs under test correctly. It can be left blank in which case the current Job library list is used. This library list will also be used when searching for the objects (Files and Data Areas) which may require protection. If Data Protection is active through either the *PGMREF, *PGM or *DYNAMIC choices, this determines the origin of the objects to be copied to the temporary library for the run, and hence the objects being protected. Within this option, there is an option to retrieve the current Library List into the set up. The library list will be taken from the first available in the following sequence – Environment, Test Case, current. If the library list is not defined for either the Environment or the Test Case, the current library list will be used at run time (or the default from the job description if submitted). If a library list is specified for a Test Case, and the Test Case is linked to an Environment which also has a library list, the Test Case library list will be ignored at run time.
F8 – Intercepts Programs which are called by the program under test can be intercepted by TestBench. There are two ways to use this facility. 1. When the program under test tries to call the program to be intercepted, TestBench will intercept the call and return the parameters designated by the set up as if the intercepted program had successfully been called. Hence where a modular approach has been taken to program design, components can be tested without other programs being in place. 2. The parameters are intercepted, the values recorded within TestBench, and then passed on to the program being called. When this program finishes, the returning parameter values are also recorded. See the later section for more information on program interception.
F10 – LDA Use F10 to define the initial value for the local data area which will be set when the test is started. This information is displayed at the end of the job in the Results together with the ending values. Changes to the LDA are highlighted with an asterisk, and data rules can also be used to check the contents.
F14 – Notes Each Test Case can have text notes which are printed on the Report_IT Test Report document. Use F14 to enter these. See the separate section on using the Notes Editor for more information.
F15 – Items Each Test Case can have a list of Test Items which have been set up to record the functions and aspects of the programs being tested, which are required to be checked during a test. In other words, these are items on the Test Plan which a person testing would refer to and then check or tick as each item is passed during the test. Test Items provide a way of keeping this check list within TestBench, and then annotating it to record the progress made against the Test Plan. Hence at the end of a test, TestBench can report how much of the Test Plan has been carried out, and which items have been successfully passed.
F16 – Rules Data rules are used to check that data written to a file or data area complies with logical rules about the data values. Selection rules are used to identify records/data areas that match given conditions for when the rule applies. Rules can be set up at Global level, Project level and for a Test Case. This function key will access Test Case Data Rules and enables rules to be added, changed or deleted. See the separate section on Data Rules for more information.
F18 – User Exits User Exit commands enable additional processing to be executed at several points during a Test Run. See the separate section on User Exits in the System chapter.
F19 – Manual Refs This provides a means to alter by inclusion or exclusion the list of objects to be protected. 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 Test Data Protection. Any files specified here for protection are in addition to those determined by the Data Protection field for the Test Case. This is especially useful for protecting files that cannot be determined from displaying program references.
F20-Scripts Scripts recorded using the ‘Native’ recording functions and stored against this Test Case can be viewed and modified. See the ‘Native’ Record and Playback chapter for details about these functions.
F23-Exceptions Define job log message ids, message types or sending programs for this Test Case that will not generate a warning message in results if the error severity threshold defined in process settings has been reached. See the specific section in the System chapter for more information.
Test Options
The following display is accessed via F21 from Maintain a Test Case.
Job Date If blank, the current Job Date will be used for the duration of the test run, unless this has been overridden at the Process level. If a Job Date is entered, this will be used when executing the program under test and hence can be used to simulate a future date environment. Use option 11 to scan the source for the program (and programs it calls) to determine if they may retrieve the system date directly. If so, using a different job date may not provide a total future date test.
Increments This refers to the Job Date above and determines the number of times and the number of days that the above Job Date should be advanced. This can be used if the Job Date is blank, in which case the date will be incremented from the current Job Date.
Run Mode Determines whether this test should be run interactively or in batch. This option can be changed at run time.
Independent ASP If the objects being tested reside on an Independent Auxiliary Storage Pool (IASP) other than the default of *SYSBAS, the name of the IASP can be specified here (or selected using F4). Alternatively select *CURRENT to enable whichever IASP is specified for the current job to be used. The Test Case can then contain objects in libraries on the specified IASP and on *SYSBAS.
Data Protection This important option controls data protection during a test run. There is also a separate section later in this chapter and a separate chapter on Test Environments. The choices are:-
*PGMREF All files and data areas updated by the program under test, and any programs it calls, through the whole call stack are protected. It is not appropriate to use this option with, for example, a high level initiation program in an application which may in some way call all the application functions and hence require TestBench to protect all the files in the application under test. If the Test Case is started with a command, the references for the command processing program will only be included if the system level option ‘Expand command references’ has been set to yes.
*PGM The files and data areas used only by the program named in the Test Case set up are protected (excluding those used by other programs called). If the Test Case is started with a command, the references for the command processing program will only be included if the system level option ‘Expand command references’ has been set to yes.
*DYNAMIC Objects are not protected until the program referencing them is called, meaning that objects are only copied into the run time library if and when they are needed. If the Test Case is started with a command, the references for the command processing program will not be included for dynamic protection, even if the system level option ‘Expand command references’ is set to include.
Library name The files and data areas in a designated library are all protected, regardless of which ones a program under test uses. Other files found in the library list which are not in this library may be updated as a consequence.
*NONE No objects are protected. The files to be used and updated are those found in the library list, or accessed by the program. If using this option, analysis of the updates to the files is not available as the updates will not be captured by TestBench. Only use this option when you are not interested in using data rules, viewing file record updates or protecting the original copy of the files from update.
*ENV Use in conjunction with the ‘Environment’ option to specify a Test Environment to be used when running the Test Case. See separate chapter on Test Environments.
If the files and data areas are being protected they are copied at the start of the test run (or when first referenced with *DYNAMIC) into a working library which is placed above the user portion of the library list. The only valid options are *NONE and *ENV if the CHGSYSLIBL command is not being used – see later System Library Pre-checker section for more information. For further information on Data Protection, refer to that section later in this document
Further data protection options are provided by using the Manual References accessed by F19.
Environment Specify the Test Environment to be used when running the Test Case, and set ‘Data Protection’ option to *ENV to use this Environment. See separate chapter on Test Environments.
Pre-Check Scope This option controls which objects will appear on the pre-check warnings screen when the test is executed with either *NONE data protection or Library Name protection. The options are *PGM, *PGMREF or *NONE.
Data Base Rules Rules can be set up at the Global, Project or Test Case level, and this option defines which rules will be applied to the database results for this test.
Display severity All messages that apply to the test run are extracted from the joblog and stored in TestBench. This value determines the default minimum level of messages to be displayed when reviewing results. This can be overridden when viewing messages with F13.
Interceptions RTVSYSVALs This refers to attempts by the program(s) under test to retrieve date values from the System Values. If this takes place, TestBench can intercept this call and will act according to the choice specified. Choice 2 will allow the run to continue, but will place a message in the job log. This option must be set to ‘3’ if the CHGSYSLIBL command is not being used – see later System Library Pre-checker section for more information.
OVRDBFs If a program under test uses Override Data Base File, this potentially could bypass a protected file and write directly to an unprotected copy of the file which may be undesirable. The three options are explained in detail in the section below.
Product Group Enter the functional area of your application to which this Test Case belongs, e.g. INVOICING, ORDERS, GLEDGER. This is used for integration with some Change Management systems to automatically identify which Test Cases should be executed as part of a promotion. Product Groups are set up using option ‘24’ from the Utilities and Information Menu.
Job Description Specify an alternative Job Description to be used when running the test.
Capture Spooled Files 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. This option 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 the entries in the Work With Reports list which is accessed from the Global System Options. Only if there is a match will the report be captured.
Control Options
For each of the following features specify an option ‘1’ if active for this test or an option ‘2’ if inactive.
Job Date Options If set to inactive, ignore any Job Dates set up at the Test or Process levels and run the test with the current Job Date.
Program Intercepts If set to inactive, ignore any interception of Test Case programs which has been set up using F8 from Maintain a Test Case.
Data Queue Logging If active any messages being sent and received by data queues will be captured and logged in results against the Test Sub Run. These can be displayed using option 10 from the Sub Run Detail display. Object Management authority is required to the objects QSNDDTAQ and QRCVDTAQ which are the Send and Receive programs copied by TestBench into the run-time library so that messages can be intercepted. This option must be set to ‘2’ if the CHGSYSLIBL command is not being used – see later System Library Pre-checker section for more information.
Data Queue Protection If active any messages being sent and received by data queues will be protected, which means that there will be no message activity on the data queues specified by the application. Any messages are intercepted as explained above, ensuring that data queues remain unaffected by the test.
WebSphere MQ Intercepts
If set to a ‘1’ messages for the active Queues as defined using option ‘24’ from the TestBench Main Menu will be tracked and stored in the results database against the Test Sub Run. Refer to the separate TestMQ chapter for more information on tracking MQ Messages.
DB Activity Analysis By default, any file or data area which is either protected or journaled by a manual reference journal will have all updates which have occurred during the test logged in results. Setting this option to a ‘2’ means that this database activity will not be stored.
Job Log Analysis This options controls whether or not any job log messages generated by the test will be stored in results.
Automatic Result Compare
If set to a ‘1’, after this test is executed the results will be automatically compared to a previously defined baseline Test Run if one exists. Any differences between the two runs will cause a warning message to be generated. See Results chapter for more information.
Set Attention Program If active, when the Attention key is pressed during a Test Run the list of Test Items defined to the Test Case are displayed. These can be used for reference only or they can be passed or failed depending on the progress of the test. They can also be accessed at the end of the Run from the Work With Test Runs display. If this is inactive the users standard attention program is run.
Function Keys
F4 – Prompt Display valid values for Data Protection, Environment, Pre-Check Scope and Product Group options.
OVRDBFs
This option must be set to ‘5’ if the CHGSYSLIBL command is not being used – see later System Library Pre-checker section for more information.
Option 1 If an override to a hard coded library occurs, any further Test Case Processes will not be run, retaining protection of the data updated by these programs.
Option 2 TestBench allows the hard coded override to take place and the run to continue, but the fact is logged in the job log.
Option 5 No action is taken and any overrides will be allowed to take place.
Process Settings
Default Process settings can be accessed by pressing F22 on the Maintain a Test Case screen. These settings are applied to all new Processes defined to the Test Case. Default settings can be overridden for an individual Process using option 7.
Job Date If a Job Date is entered, this will be used when executing the program under test and hence can be used to simulate a future date environment. However, if any Job Date options have been set up for the Test Case (F21 Test Options) then these will be used in preference and the process setting will be ignored.
Error/Severity If an error greater than or equal to the severity value specified is encountered, the run can be stopped by keying choice 1. Choice 2 allows the run to continue and a warning is generated in the results provided the message is not excluded via the job log message exceptions that can be defined at system, Project or Test Case level.
Keep End Data When data protection is in force (the Data Protection field against the Test Case is not *NONE or *ENV) TestBench makes a copy of the designated files to run the test over, thus protecting the original copy. The value set of this field determines what happens to that copy of the data at the end of the run. Keeping data can be useful if you wish to do further analysis of the output, such as with Comp_IT (file compare), or if this data is to be the starting point for another part of a system test. In each case, regardless of the choices below, details of each record updated, deleted or added to a protected file are stored as part of the test run results.
1 – No The updated copy of the data is not kept, the copy of the files and data areas are deleted at the end.
2 – New Files and data areas that do not already exist in the Target Library (next field on the screen), are copied into the Target library and hence the updates to these new objects are kept.
3 – Match Files and data areas that already exist in the Target Library (next field on the screen), are copied into the Target library and hence the updates to these matching objects are kept. Any data already in the same objects in the target library is replaced by the updated versions.
4 – All All files and data areas protected during the test run are copied into the Target library and hence all the updates are kept. Any data already in the same objects in the target library is replaced by the updated versions.
Track Submit Jobs Jobs submitted by any program in the test can be tracked and their results stored in TestBench with the rest of the results from the test. Any additional objects which require protection must be specified in Manual References. If submitted jobs are not being tracked then please be aware of the following.
1) If the job is submitted with its own library list, this will not include the run time library used by Test_IT. Therefore only updates for any analysed journals will get stored in Results. No other database updates will be captured as the protected files in the run time library will not be used.
2) If the job is submitted without a specific library list, the current Test Case library list will be used. This includes the run time library, so database updates for any protected files may be stored within Results. However, an error will be encountered when TestBench tries to delete the run time environment if the submitted job is still running.
This option must be set to ‘N’ if the CHGSYSLIBL command is not being used – see later System Library Pre-checker section for more information.
When a job is submitted, it is likely that the data objects it references will not be included automatically in Data Protection. You may wish to include the top level program as a manual reference in the Test Case to provide Data Protection for the submitted program and other programs in its call stack.
Tracking Submitted Jobs is not supported when the Data Protection method is *DYNAMIC. If selected, it will be ignored and no results will exist for submitted jobs.
Rules Active Determines whether any Test Case, Project or Global level Data Rules will be applied to any database updates for this Process.
Reset Environment Key Y to indicate that TestBench should reset the test data which has been protected before the execution of this Process. If this is applied to the first Process it will have no effect. TestBench can only reset data which has been protected. See the ‘Data Protection’ field against a Test Case and the separate section on Data Protection for more information.
Reclaim Storage Key Y if you require TestBench to reclaim program resources at the end of the execution of this Process, such as for example to force a termination of a program that normally remains resident in memory (i.e. does not set on LR).
Process Overrides
The default Process Settings (F22) which are applied to all new Processes can be overridden using option 7.
Additional Options
Process Description Optional field, used in Results to identify the Process.
Process Active Key N if this Process should not be executed as part of the test.
Track Process If this Process is active, key Y to store results.
Other fields The other options are the same as those described in the previous section for Process Settings.
Using Parameters and Commands
Each program within TestBench can be initiated either by specifying a program name and parameters, or by using a command. The choice is made on the following display which appears both when a new Process is added and an existing one is changed with option 2.
Execution Program This defines the starting point for the Process if it is to be initiated using parameters.
Library This can be either a library name or *LIBL. If *LIBL is keyed the Test Case library list will be used if present (this can be updated using F7) or if this is blank the current job library list is used. If the library field is left blank then *LIBL is assumed.
Cmd Key in the command to be executed as an alternative to a program/library and associated parameters. If the command is promptable and can be found in the library list, you can use F4 to prompt for the command string data. Press F7 if there is not enough space on screen to enter the full command, or if you wish to retrieve the command string from an existing batch job.
Function Keys
F7 – Libl This is used to define the initial library list required to execute the programs under test correctly. It can be left blank in which case the current Job library list is used. This library list will also be used when searching for the objects (Files and Data Areas) which may require protection and for the program to initiate the test if *LIBL is used when defining the process.
F8 – Extended Cmd Provides a larger field into which long commands can be keyed – see following section for more information.
F15 – Sub Vars Lists the substitution values that can be used in Test Case Processes. These are:
o &EL (Environment Library)
o &PR (Project ID)
o &CN (Test Case ID)
o &TR (Test Run ID)
o &SR (Sub Run ID)
o &RD (Run Description)
o &DD (Day)
o &MM (Month)
o &YY (2 digit Year)
o &LL (4 digit Year)
o &JN (Job Name)
o &J# (Job Number)
o &JU (Job User)
Parameters
If specifying a program name and library, you must ensure that the parameters are defined with the correct lengths and types in option 6 (parameters), and then enter the parameter values using option 9. These screens will be displayed automatically when entering a new Process.
If the source for a program can be found it is scanned for parameter definitions and these are displayed on the above screen. If the source is not available, the list will show the known number of parameters for the object only, and the name and length/type information can be entered. If the parameter set for this program has been defined in System Values (see the System chapter for more information), these can be retrieved using F8. This screen will not be displayed when entering a new Process for a program which has no parameters.
If a parameter is defined within the program as a data structure this will be reflected on the parameter list definition. Any sub-fields will appear below the parameter name and are indented by one character. These will also have an additional Start position defined, hence there is no requirement to define all sub-fields. Any parameter can be defined as a data structure, which is particularly useful when dealing with long parameters where only the final few characters contain relevant data. The maximum individual parameter or sub-field length within TestBench is 1,024 characters, but a data structure can be anything up to 32,000 characters long.
Please note that currently data structure sub-fields can be defined to one level only, although overlaps are permitted.
Sequence Make changes to these values and press F5 or Enter to change the sequence of the parameters.
No A sequential count of the program parameters. Sub-fields for parameters defined as a data structure have no number as they merely represent a method by which a parameter can be split up and values defined for specified sections only.
Reference The name of the parameter as retrieved from the program source or entered/changed manually. Data structure sub-fields are indented by one character.
Start A value in this field is valid for data structure sub-fields only, and along with the Length defines which section of the parameter values can be entered for (see below).
Type Valid values are alphanumeric (A), signed (N), packed (P), Binary (B) and hexadecimal (X).
Function Keys
F5 – Resequence Change the parameter order on screen to reflect any alterations made to the Sequence number field.
F6 – Add Lines Add ten extra input capable lines after the last one to allow additional parameters or sub-fields to be defined.
F7 – Rescan Source Replace the parameter definitions on screen with those in the program source.
F8 – Existing Definition
Retrieve the parameter set for this program if they have previously been defined in System Values (see System chapter for more information).
Parameter Values
Start values Key in the value for each parameter to be used when the program is called. See also the notes below on Values. If a parameter is defined as a data structure and sub-fields, parameter values can be entered for the sub-fields only.
Expected return Key in the expected value for each parameter at the end of the test. TestBench will then compare the actual ending values to the expected values and issue a warning if there is a difference at the end of a test. ‘**’ in this field means that no compare will be done between the end value and the expected value. See also the notes below on Values.
…. Values (notes) Numeric parameters should have a numeric value only, and if not required, zero should be entered. Values will automatically be right-adjusted by TestBench, so it is not necessary to key in any leading zeros to fill up the parameter length. Date data types and Timestamps are treated as alpha fields and any separators should be entered. Also, quotes are not required around alphabetic values.
F4 – Prompt If the input area available on the screen is not large enough for the value to be keyed in, place the cursor in this field and press F4 to enlarge it.
Commands
As an alternative to initiating the program to be tested by issuing a CALL to the program with the required parameters, a command can be executed instead. Use a command when it is not possible to directly call the program you want to test, or when the calling parameters are especially long or complex. For example, you can use a command set to initiate the application to be tested, using the functions in the application to reach the specific area of the application to be tested.
If data protection is required and the system level option ‘Expand command references’ is set to yes, the command program will be used to determine the files and data areas to protect. If this option is not set then Manual References must be used to specify which objects should be protected.
The command and its command string can be retrieved from a current batch job in the system, such as one held or on a job queue. This means that long or complex commands used to initiate batch processes can be captured into TestBench without having to be keyed in by hand.
Command set up is accessed with option 2 from the Maintain a Test Case display, or automatically when a new Process is added. Press F8 to obtain the extended Command display.
Cmd Key in the command to be executed. If the command is promptable and can be found in the library list, you can use F4 to prompt for the command string data.
F9 Retrieve Batch Request
If the program to be tested is a Batch program, and an example of the job which has been started with the required command is available on the system, by specifying the job information the command and its command string data can be retrieved into the command set up inside TestBench. This saves keying long or complex values used in some commands. You may wish to send the jobs to a held job queue for easy reference. Once retrieved, the command and its values can be amended.