Understand Phase

Overview of the Understand phase

During the Understand phase an application architect uses Application Discovery and Delivery Intelligence (ADDI) to analyze an application, primarily through its source code, but also often through other artifacts. The analysis performed by ADDI is stored in an ADDI Project, using a relational database schema. The application architect uses the ADDI Analyze Client to create and view charts, graphs and reports in order to help gain a better understanding of the application and identify candidates for refactoring.

Note: Even if an enterprise already has a perfect understanding of their COBOL application, the Understand phase is a prerequisite for the Refactor phase, because the components used in the Refactoring phase read an ADDI project's database.

Note: ADDI is a powerful product, with a large number of features and reports. This lab only scratches the surface of what can be done in ADDI with a realistic application. The Understand phase is a critical part of the watsonx Code Assistant for Z workflow, the importance of which is likely understated by this lab's ADDI-related instructions- in real-world usage scenarios it is to your benefit to learn more about ADDI's capabilities in order to give proper weight to the Understand phase.

Initial login to the lab environment

1. Log in to your IBM Z Virtual Access (zVA) environment. Your lab environment is a Windows system that you will access via your web browser.

   If you are taking this lab during an IBM Washington Systems Center-hosted workshop, then your access details for your environment are on this page. If you are not sure how to access your environment, please ask your lab instructor for help.

   The picture below shows what your browser tab or window should look like after you have successfully logged in to your zVA environment.

   

   Note: All lab instructions, unless explictly noted, are performed within your browser tab or window in which your zVA Windows environment is displayed.

Introducing GenApp

In this lab, you will be using the general insurance application, GenApp. GenApp is a sample CICS COBOL application that provides transactions that could be used by an insurance company to create and manage its customers and insurance policies. Could be was italicized in the previous sentence as GenApp is provided primarily for educational and testing purposes- if you are an actual insurance company it is likely that market forces would encourage you to use transactions that are slightly more sophisticated than the ones in GenApp.

You can read more about GenApp here.

Explore the application using ADDI and IBM Developer for z/OS

In simple terms, ADDI consists of features to build an ADDI project that contains detailed application information, and features to analyze the ADDI project that you have built. For this lab, the build process has already been performed against the GenApp project, and you will start with the analyze process, which you will perform within the IBM Developer for z/OS (IDz) product, using the Application Discovery Browser Perspective.

1. Open IBM Developer for z/OS (IDz) from the taskbar by single-clicking on the icon highlighted below. IDz is built on the open source Eclipse project. The ADDI Analyze Client functionality is delivered via Eclipse-based plugins, so the application architect performs analysis within IDz using functionality provided by these plugins.

   

2. After a short while you will probably see a "splash screen" for IBM Developer for z/OS. Then it will disappear and you may be prompted with the Select a directory as workspace popup window. If you receive this, leave the default workspace path unchanged and click Launch.

   The default workspace path on your lab system should be:

   C:\Users\Administrator\.zosexplorer
   

   

   The launcher window will close, the splash screen may return for a moment, then disappear, and finally the Application Discovery Browser perspective provided by ADDI will be opened up within IDz.

   IDz can take a few minutes to fully load in your lab environment. After clicking Launch, the popup window will close and it may look like the application is not opening. Please be patient- wait at least three minutes before you wake up the instructors.

3. Click the Explore tab in the middle of IDz, near the top. Once you see the Explore projects tab, right-click on the empty list of projects and click Get Project List.

   

   The GenApp project will appear.

   

4. Click the GenApp project to highlight it. This will bring up a new pane on the right side of the page that shows the many charts, graphs and reports that are provided by ADDI. Information about these reports can be found in the ADDI documentation.

   Double-click Program Callgraph in the new pane.

   

5. A new window will appear where you can select which programs to analyze. It may take a moment for the program names to appear in the Available programs pane within the window. Once they do, click the double arrow button to move all of the programs from Available programs to Selected programs, then click Finish.

   

   Please be patient. This can take a minute or two to fully load.

   When loaded, you will see a call graph for all programs, CICS transactions, tables, and other files in the GenApp application and the interdependencies between them.

   

   This is an interactive graph. You can zoom in and scroll around the graph to see different objects. One way to zoom in is to click the Interactive Zoom Tool icon in the toolbar at the upper right, above the graph. Hover over the icons until you find the Interactive Zoom Tool, then click on it. Then click on the graph and very slowly drag your cursor down in order to zoom in on the graph. You can zoom out on the graph by very slowly dragging your cursor up. When you're satisfied with the readability of the objects, you can switch to the Mouse Pan tool, which is the icon that looks like a hand, and should be a couple icons to the left of the Interactive Zoom Tool icon. The Mouse Pan Tool is convenient for bringing different parts of the graph into view. You can also right-click the objects to see more specific details about them.

   Note: Trying to zoom in and out on the graph in the zVA browser tab or window can be difficult- it is easy to get in a state where you wish you could start over. You can- just close the graph by clicking the x icon on its tab and then repeat step 4 and this step.

6. In the left side of the page, you will see a Graph Inventory. Notice that the CICS transactions, COBOL Programs, and different object types have been identified. Expand the COBOL Programs section to see the list of COBOL programs that are part of GenApp.

   

7. In the Graph Inventory, right-click the GETPAVG program, hover over Mainframe Graphs, and select Program Callgraph.

   

8. Leave the default options unchanged and click Finish.

   

   A new callgraph will be generated that is scoped to only the objects in the application flow that are used by the GETPAVG program or by other programs that are called by GETPAVG.

   

   Two COBOL programs should be displayed in the callgraph:

   1. The main program GETPAVG. This program accesses the input and output files.
   2. A called program named GETAAVG. This program accesses various SQL tables shown at the bottom of the callgraph.

9. Double-click on the COBOL program named GETAAVG to open a new panel at the bottom with the COBOL source code of GETAAVG. Maximize the source code by clicking the button in the top-right of the panel.

   

   The COBOL program GETAAVG should now be maximized.

   

   If you look through the GETAAVG source code, you will find that in the 2000-CHECK-TYPE paragraph it will perform different operations depending on the request ID (IN-REQUEST-ID data item) passed in to GETAAVG via its LINKAGE SECTION:

   1. Customer Action (0AVCUS)
   2. Get Average Premium (0AVMOT)
   3. Get Endowment (0AVEND)
   4. Get House (0AVHO)
   5. Get Commercial (0AVCOM)

   For the purposes of this lab, let's assume that the application architect has identified the paragraph that implements the Get Average Premium functionality as a good candidate for refactoring. (This is why we've highlighted Get Average Premium in the above list.)

10. Scroll down to line 342 in the COBOL code until you find the 3100-GET-AVG-MOT-PREMIUM paragraph. Pro tip: You may find that using Navigate->Go to line... from the IDz menu is a more enjoyable experience than scrolling.

    

    Hint: You can check the line you're on using the first number pointed out in the image above- this shows the location of the current cursor position so you may need to click inside the source code after you've scrolled.

    The 3100-GET-AVG-MOT-PREMIUM paragraph is one small part of the overall GenApp sample application. It is called when the request ID is 0AVMOT.

    This paragraph calculates the average premiums for a customer's motor vehicle insurance policies. For this lab we are going to assume that the application architect has decided that this would be a good service to refactor into a modular business service.

    In the next section of the lab, you will refactor this paragraph into a separate COBOL service, and then in the section after that, you will transform this service into Java code.

    You will not be using IDz anymore in the lab instructions so you may either minimize it or exit from it altogether.

In the Understand phase,

1. We selected the GETPAVG program to understand its flow and related components.
2. We explored the called program GETAAVG and its 3100-GET-AVG-MOT-PREMIUM paragraph and decided that the functionality in this paragraph is a good candidate for refactoring into a modular COBOL service and for then transforming into Java code.