Tutorial for the VS Code extension: Isolating or extracting the Update Motor Policy functionality as a service

Perform the tutorial based on the sample project GenApp to explore how to isolate or extract a functionality as a service.

Tutorial scenario

Application refactoring is essential in the journey to application modernization. To tap into the full potential of an existing application and ensure that it evolves over time for growing business needs, usually developers have to refactor an existing application into modular services. IBM® watsonx Code Assistant™ for Z Refactoring Assistant comes to developers' aid in such scenarios and help them identify parts of an application to refactor into services. In this tutorial, you will learn how to isolate or extract the functionality of a sample application as a service.

Assumption

The following tutorial assumes that you need to create a service for the functionality of Updating Motor Policy to meet your business needs. Therefore, to begin with, you want to use Z Refactoring Assistant to extract the relevant portions of the code that perform the functionality. Check the following instructions to learn how to use Z Refactoring Assistant to get the relevant parts of the GenApp application involved in the functionality of Updating Motor Policy.

Prerequisites

Procedures

Complete the following steps to perform the tutorial:
  1. Launch your Visual Studio Code application.
  2. Select File > Open Folder.
  3. Select a folder that is used to contain the refactored service code extracted from the GenApp project files and click Select Folder to confirm your selection. The workspace folder is opened in your Visual Studio Code window.
  4. Open the Visual Studio Code Command Palette by selecting View > Command Palette from the Visual Studio Code menu.
  5. Enter Preferences: Open User Settings in the command palette.
  6. Search for IBM watsonx Code Assistant for Z Refactoring Assistant to locate the extension settings.
  7. Enter the URL of the Refactoring Assistant server as the Refactoring Assistant Server: URL property value.
  8. Click the Accounts icon in the Visual Studio Code Activity Bar and select Sign in with IBM ADDI to use IBM watsonx Code Assistant for Z Refactoring Assistant.
  9. After you log into ADDI, you will be prompted to select an AD project. From the AD project drop-down list, select the project that you built with IBM AD Build Client.
  10. The Graph view of the GenApp project is displayed.
    Note: The Graph view maintains the connection to the Refactoring Assistant server and should remain open while working with AD projects. If this window is closed, use the Visual Studio Code Accounts icon to log into the server again.
  11. Type MOTOR in the search box. You will see MOTOR - Db2® table in the results.
  12. Click the result item MOTOR - Db2 table and then press Enter. This operation computes a table closure by taking the Motor Policy as the seed that is of type Table. A table closure provides the programs that perform some kind of operations on the table that is provided as a seed, and then it shows the call chain of those programs all the way to transactions. Closures help you narrow the focus to the artifacts of relevance as a starting point.
    The image shows the table closure that takes Motor Policy as the seed.

    Three programs are involved in the Motor Db2 table: LGUPDB01, LGIPDB01, and LGAPDB01. With the graph, you can further check the relevant chains from programs to specific transactions.

    So far, with Refactoring Assistant, you have narrowed down the large number of artifacts for GenApp to the preceding three programs that perform the functionality about Motor Policy. However, based on the naming convention, you decide to explore further with the program LGUPDB01 first since it seems more relevant to the functionality of Updating Motor Policy.

  13. Click the Action Menu (The image shows the Action Menu icon.) icon on the upper right corner of the LGUPDB01 program node. You will see the following options available:
    • View properties option to view more details of the artifact
    • Identify conditional statements option to see the conditional statements of the program as the drivers of business functionality
    • Identify paragraphs option to identify the paragraphs of the program that can be service candidates
    • Identify table/file access statements option to identify the table or file access statements of the program
    The following steps of the tutorial will illustrate the Identify conditional statements option in more details.
  14. Select Identify conditional statements.
    The image shows the Identify conditional statements option.

    A read-only editor opens with the source code for program LGUPDB01. The Project Artifacts view displays any AD project source file that you have referenced.

    In the Key Conditions view, you will see a list of all the key conditions that are identified in the program. The key conditions are listed in descending order of importance score, instead of the sequential order of the statements. The importance score indicates how relevant and useful the highlighted statement could be for the program that you selected. Therefore, you can analyze the top few statements as a starting point to investigate the key conditional statements.

  15. From the Key Conditions view, click the conditional statement that you want to investigate further, which scrolls the source code view to the location of the selected conditional statement. Use the filter icon in the Key Conditions view to select a key condition type such as Conditional statements or Paragraphs to narrow down the key conditions to a specific type.

    In this example, you can click any of the top two conditional statements to take you to the main logic in LGUPDB01 program.

    Based on the code comments and your knowledge, you will find that the following piece of code seems to have the code for Updating Motor Policy.
    The image shows a piece of code.

    After further investigation on the code, you determine that the WHEN '01UMOT' statement is the code portion that you want to extract.

  16. In the Key Conditions view, click the ellipsis next to the WHEN '01UMOT' conditional statement and then select Slice on condition to new service.
    The image shows the Slice on condition to new service option.
  17. Enter a name for the newly created service file by entering UPDMOTOR, which contains the COBOL service file UPDMOTOR.cbls. Select the Forward slice direction, and append any relevant tags required.
    The image shows the screenshot when you enter UPDMOTOR as the service name.
  18. The workbook editor opens on the UPDMOTOR.cbls file. You will find the WHEN '01UMOT' code block that you just sliced and all the subsequent code blocks that are involved. If the editor is opened in an editor group next to the read-only LGUPDB01.cbl file, select a code block to scroll the source file to the selected block so that you can view the block in context.
    The image shows an opened editor.
    Now you have extracted the code portions from the LGUPDB01 program that are related to the functionality of Updating Motor Policy. Next, you will explore further with the program that invokes LGUPDB01.
  19. Select the Refactoring Assistant tab to view the closure graph.
  20. Click the LGUPDB01 program node and then you will see that the LGUPOL01 program invokes LGUPDB01.
    The image shows the LGUPDB01 program node.
  21. Click the Action Menu (The image shows the Action Menu icon.) icon on the upper right corner of the LGUPOL01 program node.
  22. Select Identify conditional statements to inspect the conditional statements for LGUPOL01.
    The image shows the Identify conditional statements option.

    Based on your investigation with LGUPDB01 and knowledge, you determine that WHEN '01UMOT' is the relevant statement. Therefore, you can slice it and add it into the workbook you created in the previous steps.

  23. Right-click WHEN '01UMOT' in the Key Conditions view and then select Slice on condition to existing service.
    The image shows the Slice on condition to existing service option.
  24. Select the UPDMOTOR.cbls service file from the dialog list, and then select the forward slice direction, and append any relevant tags that are required.
    The image shows that the service file is selected.
    Then you will see that the WHEN '01UMOT' statements in LGUPOL01 are attached to end of the list of code blocks in the workbook editor.
    Now you have explored how to slice the highlighted code portions from programs into a workbook.
    The image shows the list of code blocks.
  25. You can repeat the process of getting the code blocks from additional programs in the call chain until you are content with the coverage. When all the required code blocks are finalized, right click the UPDMOTOR.cbls file in the Visual Studio Code Explorer view and select Z Refactoring Assistant > Generate Service Code.
    The image shows the Generate Service Code option.
  26. Enter UPDMOTR as the name of the generated service. The UPDMOTR.cbl file will be created in the workspace, along with any referenced copybooks.
    The image shows the generated service and its referenced copybooks.
    Note: The referenced copybooks are available only when they are part of the ADDI project. Therefore, for a copybook that is not in the ADDI project, for example, an SQLCA copybook, you must obtain a copy of the copybook from somewhere else to make it available.