JCL Validation and Adaptation
Contents
- Getting Started with SCM – BMC AMI DevX Code Pipeline
- Code Changes and Generate (AKA Compile)
- Identify the Executing JCL and Validate It
- Confirm the JCL Adaptation
- Verify Adaptation by Testing
- Promotion
Getting Started with SCM – BMC AMI DevX Code Pipeline
The goal of this Test Drive is to show how to adapt your JCL to each environment as it moves through the life cycle, which will enable its proper testing. The Test Drive will also show how to perform JCL validation during your development phase.
This Test Drive will take you through the following activities:
- Create an Assignment
- Add and check out a Cobol program
- Change it using the BMC AMI DevX Workbench for Eclipse editor
- Compile/Generate the program using BMC AMI DevX Code Pipeline
- Identify the impacted JCL
- Modify the JCL and, via Generate, validate it using PRO/JCL
- Deploy the JCL to a testing library
- Confirm the adaptation of the JCL for the target environment and verify by testing it
- Promote the Assignment through the life cycle, validating the adaptation of the JCL after promotions
- Approve the promotion to Production
- Close the Assignment
Instructions:
- This guide contains many screenshots to provide a visual reference
- Please note each place that you must enter your own specific ID or number
- You must complete each step before proceeding to the next to successfully follow the guide
If at any point during your experience the host connection times out, you may need to log back into the Test Drive host connection.
In this Test Drive the screen shots provided have used specific values that may differ from your assigned values. These were provided in your email notice.
Code Changes and Generate (AKA Compile)
Your initial development Task in this Test Drive is to change a Cobol program using DevX Workbench's editor, modify it, and generate it. You will later identify the JCL that executes it.
First, you will find and add a Cobol program into an Code Pipeline Assignment from which you can perform all this work.
- Change the Stream to CWEZ
- Change the Application to your assigned application value (Txxx, where xxx is your unique number)
- Note: SubAppl will be automatically populated with Application
- Set the Level to "PRD" and ensure the Level option is set to "Selected level only" or "All found in level and above." Either setting will return the same results since there is no levels above PRD.
- Filter the view even further by setting the Type to COB, this will allow you to focus only on the Cobol program components available in your stream | application at the PRD level. Click Apply (circled).
The Repository View lists the Cobol Components for your application.
Right-Click on "COB TPROG01 PRD" and click Add to Assignment with Checkout.
From the Add Task dialog box, set the Path to DEV1 if it is not already selected, then click the New button to the right of Assignment. This will allow you to create a new Assignment Container to put your Cobol program into.
Type a description – "Test Drive JCL Validation and Adaptation" – and Click OK. (All other fields may be left unchanged.)
A message will be displayed providing you with your new Assignment name.
Click OK.
Your new Assignment has been created and is ready to have Tasks added to it. An Assignment Container is the only Container Type in Code Pipeline that Tasks can be added to. The Assignment Container is where a developer will spend much of their time.
Your new Assignment number will appear in the Assignment field.
A message will be displayed to inform you that the task has been added to your Assignment.
Click OK.
Your Assignment has been created and you should now have a Cobol program in it. The Assignment view will open and the Task that was added will be listed.
Every operation that needs to be performed on this Task and other Components which are impacted by changing this Task (edit, impact analysis, compile, promote, deployment etc..) can be performed from this Assignment or other Assignments.
Note that the Cobol program in the Assignment is checked out and sitting in the DEV1 level. The checkout date/time and userid is reflected in the Task information. At checkout, a destination level for the checkout was chosen – DEV1.
To see the Life-Cycle, path structure, that was constructed for the Application, Click once on the Task and then Click on the View Life-Cycle icon.
A picture of the Life-Cycle is presented.
By choosing the DEV1 Level, you have defined the Path to Production --> DEV1-QA1-STG-PRD. Other versions of these Components may also exist at other levels and may be passing through the other three paths – FIX, DEV2 or DEV3.
Four paths were created for the application – one for emergencies starting at level FIX and three for development starting at DEV1, DEV2 and DEV3. The application level structure is customizable when defining the applications to Code Pipeline. Any number of paths can be defined with a minimum of three Levels.
Now that you have a Version of a Cobol program the next step would be to make changes to it.
The version's source will be presented in the DevX Workbench COBOL Editor.
If you get the "Copybook Download" prompt, click Yes; DevX Workbench will then download the copybooks.
Next, type your changes. For this tutorial, simply add a comment to the program.
Once you have made your changes, close the Edit view and click Yes.
Note the Operation, date/time and User ID fields have been updated to reflect the change in the Task status.
Next, the Cobol program will be generated/compiled so that it can be tested. When that happens, your Assignment Task List will be updated to reflect the new status.
- The Operation will be Generate
- The User ID, Date/Time will be updated
- The Message will be updated to reflect the successful completion of the generate
Right-click on TPROG01 and click Generate.
The status column will display a message showing that the Task is being generated.
The screen will refresh automatically when the generate is done. The Task will be updated with the date and time of the generate, the user who performed the generate and the operation will reflect a generate has occurred (screenshot not shown).
Identify the Executing JCL and Validate It
At this point you have edited a Cobol program and then generated it. Now you are ready to identify the JCL that executes the program so that it can be validated as part of the life cycle.
Remain in the Tasks view. Right-click on the COB task, mouse over View, and then click Impacts.
This opens the Impacts view, which shows components that reference or are referenced by the Cobol program. The component SJOB01 contains the JCL for the job with which you will be testing (and which executes the Cobol program), so you will now add it to your assignment.
Next, prior to validating the impacted job, you will look at its contents to learn more about it.
Right-click on SJOB01, then click Browse.
Notice that the JCL in SJOB01 executes a CLIST that, along with Cobol program TPROG01, will need to be tested through each level of the life cycle. Since the CLIST is referenced via SYSTSIN control card rather than through a DD statement in the JCL, you will add it to your assignment via the Repository Explorer.
Click on the X to close the Browse tab.
Then, click on the Impacts tab and click on the X to close it as well.
In the Repository Explorer, change Type to CLST and click Apply.
Click on TREXX01 and click the Add to Assignment with Check Out button.
Note that on the SYSPROC DD and the STEPLIB DD, the third DSN qualifier is "PRD" (Production).
You are now going to "break" the JCL.
On the SYSPROC DD statement, change the final DSN qualifier from "CLST" to "CLIST" (with the "I" in upper-case).
Click on the X to close the Edit tab, then click on Yes to save changes.
The JCL validation will be performed via the Generate process. This process, configured by the Code Pipeline administrator, is much like the Generate process used to compile and link-edit source code. Instead, it performs a JCL validation; if successful, it then deploys the JCL from the configured life cycle JCL library to a run-time JCL library in the development environment. In this Test Drive, the validation is performed using PRO/JCL, but any JCL validation tool can be used.
The screen will refresh automatically when the generate is done. The Task will be updated with the date and time of the generate and the user who performed the generate. The Status column indicates that the generate has failed – it is now time to determine why.
Right-click on the task again and click View Generate Listing.
Scroll down several lines to see the error identified by the JCL validation process. Click on the X to close the Listing tab.
Now, undo the previous change to the job so that its original contents are restored. This will enable the JCL validation to complete successfully.
To validate the JCL again, right-click on the task (SJOB01) and click Generate.
This time, the Generate succeeds as expected. The Operation shows as Implement, because the job has also been deployed to a target environment for testing. We will review this in the next section of the Test Drive.
Confirm the JCL Adaptation
Now that the JCL has been validated, you are ready to have Code Pipeline adapt it to reflect the environment in which it is to be tested. Adaptation occurs during a Deploy operation, as configured by the Code Pipeline Administrator; its function is to perform specific edits to components at the time they are deployed, such as changing the names of libraries to reflect the naming conventions of the target environment.
In your Test Drive, the adaptation occurs during the following operations:
- After the Generate operation to validate the JCL, when the job is deployed to a testing environment related to the DEVx level
- After the Promote operation, when the job is deployed to a testing environment related to the target Hold level
It is now time to confirm the first JCL adaptation. which took place after the Generate operation.
On the menu bar, click Window, then Show View, then Other...
Scroll down in the Show View dialog until you see Code Pipeline. Expand Code Pipeline and click on Deployment. Click Open.
This opens the Deployment View.
Click on the latest occurrence of the Request ID that matches your Assignment description (Test Drive JCL Validation and Adaptation). Next, click the View Request Details button.
The Deployment Management Request window is now opened.
Click on "Item 1 SJOB01 JOBS Completed". The field labeled Storage contains the DSN of the deployment target; this is the file to which the adapted JCL was deployed.
Double-click on the Storage DSN so that it is fully highlighted, then right-click on it and click Copy. Click Cancel to close the window.
You will now look at the contents of the deployment target library to confirm that the JCL Adaptation took place as expected.
On the left-hand side of DevX Workbench, click on the Host Explorer view.
Expand the Test Drive host if necessary, then right-click z/OS Datasets and click Add Filter...
In the Filter window, click in the Filter pattern field. Right-click and click Paste. You will see the DSN of the deployment target.
Click Add and then OK.
The dataset filter has now been added.
Click on the arrow next to the filter to expand it and show the dataset name as a folder.
Similarly, click to expand the folder, which opens it and shows the PDS members.
Double-click on SJOB01 to open it and show its contents.
As you can see, the third qualifier of the DSN on the SYSPROC DD statement has been changed (adapted) from PRD to DEV1.
The JCL Adaptation has been successfully executed.
Verify Adaptation by Testing
At this point you have
- Edited a Cobol program and compiled/generated it
- Identified the impacted JCL
- Modified the JCL and, via Generate, validated it using PRO/JCL
- Deployed the JCL to a DEV1 testing library
- Confirmed the adaptation of the JCL from PRD to DEV1
Now you are ready to verify the adaptation of the deployed JCL by testing it in the target environment, which in this situation is DEV1.
Remain in the Host Explorer view. Right-click on member SJOB01 in the PDS matching your filter, then click Submit.
This submits the JCL that includes SYSPROC and STEPLIB DD statements that point to libraries with the DEV1 qualifier in the DSN. You will see the message box indicating that the job was successfully submitted.
After a small amount of time passes, you will then see the Host Explorer Job Completion Notification in the lower right corner of the DevX Workbench. It should indicate completion of the job with MAXCC=0, confirming a successful test of the REXX program and the Cobol program.
Promotion
Through this point of the Test Drive, you have completed several steps as noted in the previous section. In addition to those steps, you have just verified the adaptation of the deployed JCL by testing it in its target environment.
Now you are ready to promote your changes to the QA1 level.
Click on the Containers view to return to it, right-click on your Assignment, and click Promote. Now click on the Tasks view.
This action will create a Set Container. Sets are a special category of container that are used to conduct operations such as promotion and deploy. They are temporary and created by Code Pipeline as needed for the work. Though not done in this instance, this allows you to promote subsets of Tasks within an Assignment container without the need to act on all of the Tasks at once.
When you click Promote, the Tasks in the selected Assignment are placed in a SET container for the promotion. The Code Pipeline Set processor will:
- Perform the promotion of the source to QA1
- Cleanup the DEV1 level (source and parts if applicable)
- Perform generates, in order, of all the Task(s) in the SET which require a generation
- Deploy Tasks (and in certain cases, related parts) in the SET which require deployment to target libraries
A notification will appear in the lower right of the DevX Workbench indicating the Promotion has completed.
In the screenshot below you can see that the Promote operation has completed – the Tasks have been promoted to QA1 (see the Level value and the Operation in the Task List as well as the highlighted Level in the picture).
The SET processor performed a promotion and then a generation for TPROG01 as Code Pipeline recognized that a generate was required for COB types at the QA1 level based on the configuration of this application. Similarly, a generate will not be performed when promoting to levels above QA1. In addition, the SET processor performed a promotion and then a deploy for SJOB01. These processes can be configured by the Code Pipeline Administrator.
It is now time to review the deployment of the job.
Click on the Deployment view. The most recent deployment went to the QA1 environment, as shown.
In the Host Explorer view on the left-hand side of DevX Workbench, right-click on the filter created earlier, then click Edit Filter...
On the left-hand side of the Workbench, click on the Host Explorer view.
Expand the TestDrive host if necessary, then right-click z/OS Datasets and click Add Filter...
Edit the third DSN qualifier from DEV1 to *, then click OK.
If it isn't already done, expand the QA1 RUNJCL library to see that SJOB01 has been deployed to it.
If an expand arrow shows next to the STG RUNJCL library, click on it as well.
You can see that the library for the STG level remains empty.
Let us assume that all the validation and testing at the QA1 level has been successfully completed and you are ready to promote to the STG level.
Click on the Containers view. Select the Assignment as before, right-click, and click Promote.
A Set container is created. The Tasks in the Assignment are placed in a SET container for the promotion. The Code Pipeline Set processor will:
- Perform the promotions of all the parts to STG
- Cleanup the QA1 level (source and parts if applicable)
- Deploy Tasks (and in certain cases, related parts) which require deployment to target libraries
As the Tasks in the SET are being processed, you can monitor the progress by clicking the refresh button.
Click OK.
As the screen shot shows, the promotion has completed. All of the Parts associated with the Tasks in the Assignment have been successfully promoted to STG.
Refresh the Host Explorer view on the left-hand side of DevX Workbench.
Expand its contents to see that SJOB01 has now been deployed to the run-time library for testing at the STG level.
If you wish, double-click this PDS member to see its contents (with appropriately adapted JCL) in the DevX Workbench Editor, then click the X to close the Edit tab.
Assuming all the testing at the STG level has been successfully completed, you are now ready to promote the Assignment to the PRD level.
Select the Assignment as before, right-click on it, and click Promote.
A Set container will be created. The Tasks in the Assignment are placed in the SET container for the promotion. The Code Pipeline Set processor will:
- Perform the promotions of all the parts to the PRD Level
- Cleanup the STG level source and parts as applicable
- Deploy Tasks (and in certain cases, related parts) which require deployment to target libraries
A notification will appear in the lower right of the DevX Workbench indicating the application has been configured to require an approval for the promotion to PRD. The Tasks are locked in a SET for a Promote process, but the SET needs approval before the promote can proceed.
The Approval can be performed from:
- DevX Workbench/Code Pipeline
- TSO/Code Pipeline in the ISPF interface
- Web interface (including mobile browser)
For this Test Drive, you will do the approval from DevX Workbench/Code Pipeline.
Click on the Assignment, then right-click on the STG box in the Life-Cycle diagram.
Click "Approve."
Code Pipeline will now start a SET processor to perform the promotion of the Tasks collected in the SET to the PRD Level.
You can see in the updated screen below that:
- SET processing has completed
- The tasks have been processed for a Promotion and are now at the PRD level
The Promotion to the PRD level has completed. The components and their associated parts were moved to the PRD level Life-Cycle libraries and the STG level libraries were cleaned up as appropriate.
Click on the Tasks view to see the final operation for each task in the Assignment.
The Cobol program and the job that executes it were deployed to run-time libraries (load and JCL, respectively) - hence those Operations show as Implement.
As a Developer you are now finished with your Assignment, so it can be closed. Assignments are closed manually and are usually closed to unclutter the Containers view.
Click on the Containers view.
Right-click on your Assignment and click Close.
A Close confirmation panel is presented.
Click OK to complete the Close.
For audit purposes, Closed Assignments, Sets, and Releases are never deleted from Code Pipeline. They are just filtered out of the standard day-to-day filtering. Once an Assignment, Set, or Release is closed it is removed from the standard filtered list, but it is still part of Code Pipeline history and can be viewed at any time.
You are done! Your job has been to change a Cobol program, find the JCL that executes it, use a tool to validate that JCL, and then adapt that JCL for each level of the life cycle through which it passes so that it and the program can be tested. As a part of this exercise, you have been able to use DevX Workbench and Code Pipeline to execute a workflow:
- Created an Assignment
- Added and checked out a Cobol program
- Changed it using the DevX Workbench Editor
- Compiled/Generated the program
- Identified the impacted JCL
- Modified the JCL and, via Generate, validated it using Control-M JCL verify
- Deployed the JCL to a DEV1 testing library
- Confirmed the adaptation of the JCL from PRD to DEV1 and verified by testing it
- Promoted the Assignment from DEV1 to QA1, QA1 to STG, and STG to PRD
- Validated the adaptation of the JCL after each of the first two promotions
- Approved the promotion to Production
- Closed your Assignment to complete the change cycle
Congratulations! This completes the Code Pipeline tutorial for BMC Test Drive.