How to Leverage Endevor Processors to Test Batch Applications
Editor: Vaughn Marshall
Agile and DevOps methodologies promise the ability to go faster while retaining quality. A key pillar supporting this is the use of automated testing in place of manual tests. There are a number of technologies, including Test4z, which provide test-centric APIs to allow tests to be written in any number of freely available modern testing frameworks. Another approach for the more Endevor-centric is to add automated tests leveraging Endevor processors as a first step or as a complement to the Open-first approach for Mainframe test automation provided by Test4z.
Automated Testing of Batch Applications in Endevor
Endevor has long been capable of automating the steps needed to move software changes from development into production. Given that, it should be no surprise that automated testing is a natural fit for Endevor-managed processes. Particularly close to Endevor are “batch” processes. Job Control Language (JCL) is the primary method for executing batch applications on the mainframe, and JCL is the language used for Endevor processors.
Using the sample Endevor processors and scripts located here, you can create a simple facility for tailoring and running automated tests of batch application changes.
How Does it Work?
State-of-the-art Endevor configurations leverage a simple language called “OPTIONS”, which specifies operating instructions to Endevor processors. OPTIONS may contain one or more statements in the following format:
Variablename = ‘value’An OPTIONS statement assigns a value to a variable. Modern and legacy developers alike recognize them. The syntax is supported in computer languages such as Java, C, Python, Rexx, JCL, and many more. Endevor’s OPTIONS variable names may use mixed case characters and be up to 250 characters in length. Variable names can be descriptive, making them easy to recognize and use. They are also recognized by Endevor processors that operate on them. Generally, Endevor’s OPTIONS are stored as an element type name such as OPTIONS, OPT, PARM, or some other user-preferred name.
These example OPTIONS statements support processing of COBOL elements in today’s modern Endevor processor:
IGYCRCTL =’OBJECT,APOST,AWO,DATA(31),FASTSRT,LIB,FLAG(W),RENT’
IEWL=’LIST,MAP,RENT,REUS,NOLET,XREF,SIZE=(256K,64K),’The first statement provides instruction for a COBOL compile step, and the second statement instructs the Linker/Binder step in the Endevor processor.
How Can Options Initiate Automated Batch Tests?
By broadening the Endevor OPTIONS feature, instructions can be provided for invoking automated batch tests. Suppose that following a successful COBOL Generate or Move action, you want Endevor to initiate an automated batch test. The test might involve one or more of the JCL’s that execute your COBOL program. In this case, you could include additional AutomatedTest options statements such as these:
IGYCRCTL =’OBJECT,APOST,AWO,DATA(31),FASTSRT,LIB,FLAG(W),RENT’
IEWL=’LIST,MAP,RENT,REUS,NOLET,XREF,SIZE=(256K,64K),’
*
* (An asterisk in column 1 indicates a comment line)
* Kick off an automated test of JCL's TESTJOB1 then TESTJOB2
* when this program is Moved or generated in stage UTC.
*
AutomatedTest@UTC.1 = ‘TESTJOB1’
AutomatedTest@UTC.2 = ‘TESTJOB2 FROM SUBSYSTEM JCLTEST’AutomatedTest is the prefix used for initiating automated batch tests. Within the variable name is also the name of an Endevor location, where testing is expected to occur. A location can be an Environment or Stage or other values— such as the target location for a Deploy to Test action. The examples indicate two automated tests are expected when the COBOL program reaches Endevor’s UTC stage. The second test is to be submitted only after the first one is completed. The value portions of the statements name a JCL element to be used for the automated test. If the JCL element has a different System or Subsystem than that of the COBOL element, you can specify them, as shown in the second example.
Element names for OPTIONS must match the element names of other types. An OPTIONS element for a COBOL program must have the same element name given to the COBOL program. Other element types may also have their own OPTIONS, including Assembler, PL/I, Easytrieve, Proc, Control Card, and JCL.
A key element to testing batch applications in JCL is to tailor the JCL for the environment where the test is being run. If a JCL is being prepared in the DEV environment, then references to production resources such as input datasets, databases, and other objects, must be replaced with references to DEV resources. Additionally, it might be required that the job name and class values be modified to non-production job names and job classes. Once the preparations of the JCL are complete, the tailored JCL can be submitted. When the submitted job finishes, its outputs are captured, compared, and a determination is made to succeed or fail. All of these are actions taken by the Endevor processor of the Automated Test Facility.
How Are Inputs Tailored for Automated Tests?
OPTIONS statements control all aspects of automated testing. Consider an Endevor life cycle that includes UTC and QATURN stages. Statements like these for a JCL element instruct the processor to tailor the JCL for automated tests at the two stages, using paired search and replace instructions.
* OPTIONS for JCL TESTJOB1JCL.UTC.FindTxt.1 = ‘//WALJO11P ‘
JCL.UTC.Replace.1 = ‘//WALJO11T ‘JCL.UTC.FindTxt.2 = ‘CLASS=P’
JCL.UTC.Replace.2 = ‘CLASS=T’JCL.UTC.FindTxt.3 = ‘SYSDE32.NDVR.TEAM.REXX’
JCL.UTC.Replace.3 = ‘SYSDE32.NDVR.TEST.CATSNDVR.CLSTREXX’JCL.QATURN.FindTxt.1= ‘OPTIONS SEARCH RETURN ‘
JCL.QATURN.Replace.1= ‘OPTIONS NOSEARCH RETURN ‘JCL.QATURN.FindTxt.2= ‘//WALJO11P ‘
JCL.QATURN.Replace.2= ‘//WALJO11Q ‘
Delimiter characters, such as periods, underscores, “at signs”, and others may be used to separate words within the variable names. The result is that the OPTIONS read like simple English, and require very little introduction. The first three pairs apply only to the UTC stage in the examples above, and the last two apply only to the QATURN stage. The variable names also include action words — “FindTxt” and “Replace”. The numbered portion at the end of each variable name establishes the pairing. As you might expect, text within the JCL matching a given “FindTxt” value is replaced with the paired “Replace” value. The first pair changes the job name from ‘WALJO11P’ to ‘WALJO11T’ when testing in the UTC stage.
Not all preparations for testing can be made by applying search and replace text strings. A variation of the “REPLACE” action instructs the replacement of an entire DD specification, such as a STEPLIB. An “Insertx” statement allows text inserts to be strategically placed into the JCL — either before or after a “FindTxt” string. You can insert steps into your test job which execute FILE MASTER™ PLUS, for example, to prepare the data for the test. At or near the end of your test job, you can insert steps to conduct comparisons of the test results, contributing to the decision of whether the overall test was a success or failure.
Replaced and inserted JCL lines can be more than just pure text. Additional variables can be embedded within the text to provide even greater flexible substitutions. Variable names can be defined by the JCL processor to fetch values known by Endevor, including values defined on a Site Symbol table. The examples below show instructions for the DEV2 stage and demonstrate the use of common Endevor processor variables within the REPLACE values. Variables named C1STAGE, C1SYSTEM, and C1SUBSYS are replaced with values provided by Endevor.
* Replace all STEPLIBs ...
JCL.DEV2.REPLACE.STEPLIB. =,
'SYSDE32.NDVR.&C1STAGE.&C1SYSTEM.&C1SUBSYS.LOADLIB ',
'SYSDE32.NDVR.PRD.FINANCE.ACCTPAY.LOADLIB'* Comment the submitted JCL with Endevor classification...
JCL.DEV2.FindTxt.2 = '//*JCLLIB ORDER='
JCL.DEV2.where.2 = 'AFTER'
JCL.DEV2.Insertx.2 = '//* Running in Stg &C1STAGE ',
'Sys &C1SYSTEM Sbs &C1SUBSYS'* Bypass steps after STEP7 ...
JCL.DEV2.FindTxt.3 = '//STEP8 EXEC'
JCL.DEV2.where.3 = 'BEFORE'
JCL.DEV2.Insertx.3 = '// '* Modify the test job's ORDER to include location for inserted steps
JCL.UNITTEST.FindTxt.5 = 'ORDER=(NDV.MOTM.ESCMSNDV.SHRD.D1.INCLJ,'
JCL.UNITTEST.where.5 = 'AFTER'
JCL.UNITTEST.Insertx.5 = '// ',
' CATSNDVR.NDVR.EMER.JCL)'
* Insert File Master Step to prepare test data
JCL.UNITTEST.FindTxt.6 = '//TEST001 EXEC PGM=IRXJCL,'
JCL.UNITTEST.where.6 = 'BEFORE'
JCL.UNITTEST.Insertx.6 = '//* Prepare the test Data ',
'// INCLUDE MEMBER=FM#EMPL1 <- Filemaster - prepare Data',
'//*---- Prepared the test Data '
How long will the processor wait for the job to run?
OPTIONS statements provide all detailed instructions. The Endevor processor loops a designated number of times, and at the end of each loop, determines whether the submitted job is completed. If the job is not completed, the processor waits in sleep mode for a period of time before checking again.
Options statements indicate the maximum number of loops and the length of the wait time between each loop. For example:
WaitLoops = 12
LoopSeconds = 2These statements indicate that the processor will loop up to 12 times. The processor will “sleep” for 2 seconds between each loop without using any computer resources. Each JCL can have its own values specified within its corresponding OPTIONS. If the submitted job fails or uses all of the designated WaitLoops, the processor marks the JCL element and the automated test as “FAILED”.
How Are Test Results Compared?
Dates, times, job numbers, and other text strings in the job outputs will likely never match. Therefore, additional OPTIONS statements allow for the “masking” of outputs to render a comparison that produces meaningful results. For example, output results for the submitted job might contain text that looks like this:
15.39.33 JOB20306 — — MONDAY, 24 MAY 2021 — —
15.39.33 JOB20306 TSS7000I WALJO11 Last-Used 24 May 21 14:
15.39.33 JOB20306 TSS7001I Count=00807 Mode=Fail Locktime=
15.39.33 JOB20306 $HASP373 WAITINGJ STARTED — WLM INIT -
15.39.33 JOB20306 IEF403I WAITINGJ — STARTED — TIME=15.39.
15.39.36 JOB20306 CAJR250I STEPNAME STEP PGM= CCODE E
15.39.36 JOB20306 CAJR251I SAVEMBR 1 IRXJCL 0000
15.39.36 JOB20306 CAJR251I GO 2 IEFBR14 0000
15.39.36 JOB20306 IEF404I WAITINGJ — ENDED — TIME=15.39.36
15.39.36 JOB20306 CAJR252I JOB ENDED. TOTAL EST-COSTBefore a comparison is made, “masking” instructions would modify the test results to look something like this.
99.99.99 JO929999 — — DayOfWeek- DD MMM YYYY — —
99.99.99 JOB99999 TSS7000I WALJO11 LAST-USED DD MMM YY 99:
99.99.99 JOB99999 TSS7001I COUNT=99999 MODE=FAIL LOCKTIME=
99.99.99 JOB99999 $HASP373 WAITINGJ STARTED — WLM INIT -
99.99.99 JOB99999 IEF403I WAITINGJ — STARTED — TIME=99.99.
99.99.99 JOB99999 CAJR250I STEPNAME STEP PGM= CCODE E
99.99.99 JOB99999 CAJR251I SAVEMBR 1 IRXJCL 0000
99.99.99 JOB99999 CAJR251I GO 2 IEFBR14 0000
99.99.99 JOB99999 IEF404I WAITINGJ — ENDED — TIME=99.99.99
99.99.99 JOB99999 CAJR252I JOB ENDED. TOTAL EST-COSTMany “masking” instructions are built into the Automated Test Facility. However, if a JCL has its own unique outputs that need to be “masked” before the comparison, then the MoreMasks OPTIONS statement can be used.
For initial automated testing, and for cases where test result comparisons will never match, a MaxReturnCode OPTIONS statement can be used to indicate that compare differences are acceptable.
By default, the results of each test will be compared with the results of the previous test. However, with a Baseline statement, you can name the test results you want each test to be compared to.
JCL.DEV2.Baseline = 'BASELINE.PDS.DEV2.RESULTS(TESTJOB2)'
JCL.DEV2.MaxReturnCode = 4MoreMasks = ‘=9999/99/99 9999/99/9 ’
What This Means for the Developer
Automated testing can be triggered by normal Endevor activity, from GENERATE actions and/or MOVE actions. Modern developers' methods to access Endevor, such as using Zowe commands or IDE plugins or integrations to Git, may also be used to manage the elements that control automated batch testing. You can even layer on added things like Static Application Analysis to find bugs without ever running the code by combining this Endevor automation with pipelines and external 3rd party tools.
While these are just a few examples, hopefully, you can see how Endevor provides the infrastructure to take the ‘manual’ out of testing and replace it with standard, repeatable processes that can improve your developer's velocity and keep their time focused on doing what they love most — writing code”.
See this site for Endevor-native batch testing using Endevor processors. You can press the “Autonomous Mode” button, and take the manual effort out of your testing, and automated application testing will be a new opportunity at your site.
