Tutorial for the Web UI: Using a copybook as a seed in refactoring a monolithic code behind a z/OS Connect API

Perform the tutorial based on the sample project GenApp to explore how to use a copybook as a seed in refactoring a monolithic code behind a z/OS® Connect API.

Tutorial scenario

Many a time, although the APIs look modular, the code that is invoked behind is still monolithic and intertwined for different business flows. To truly modularize the code and make it easy to maintain, developers need to find only the relevant code for each API and refactor the monolithic code behind APIs. IBM® watsonx Code Assistant™ for Z Refactoring Assistant can help developers address these needs.

Taking the GenApp application as an example, multiple ways can be used to design the z/OS Connect API endpoints in GenApp. APIs can be designed to carry out granular operations for each type of the following insurance policies:
  • /Policy/{Policy Type}/Inquire
  • /Policy/{Policy Type}/Add
  • /Policy/{Policy Type}/Update
  • /Policy/{Policy Type}/Delete

Assuming that the code behind these APIs is the legacy monolithic code, the following tutorial demonstrates how to use copybook as a seed for breaking the monolith service behind a z/OS Connect API with the help of Z Refactoring Assistant.

Assumptions

  • You know the copybook that the API request parameters map to.
  • /Policy/Motor/Inquire API is what you want to isolate code for. The API takes three input parameters, namely Customer number, Policy number, and Request type. Based on the application knowledge, these parameters can be mapped to SSMAP copybook as follows:
    • ENP1CNOO, ENP1PNOO, ENP1OPTO fields of SSMAP copybook
    • Value of ENP1OPTO is passed as '1' for Inquire operation

Prerequisites

Procedures

Complete the following steps to perform the tutorial:
  1. Launch your browser and go to https://<hostname>:9443. By default, you will be on the Workspaces tab.
  2. Skip the following steps if you have created a workspace for GenApp in as described in Tutorial for the Web UI: Isolating or extracting the Update Motor Policy functionality as a service. Otherwise, complete the following steps to create a workspace:
    1. Click the Create workspace button on the upper right corner of the Workspaces page.
    2. In the Create workspace dialog, type a name for the workspace that you want to create, for example, GenApp.
    3. From the AD project drop-down list, select the project that you built with IBM AD Build Client.
    4. Click Create to create the workspace. When the creation is completed, the Graph view of the GenApp workspace is displayed.
  3. Type SSMAP in the search box. You will see SSMAP - Copybook in the results.
    The image shows the search results when you type SSMAP in the search box.
  4. Click the result item SSMAP - Copybook to compute SSMAP closure. You can see that several programs that use SSMAP. In this tutorial, you will look into LGTESTP1, a z/OS Connect API entry program.
    The image shows the SSMAP closure.
  5. Type LGTESTP1 in the search box, and select the LGTESTP1 - Program result item to compute LGTESTP1 closure.
    The image shows the LGTESTP1 closure.
  6. Click the Action Menu (The image shows the Action Menu icon.) icon on the upper right corner of the LGTESTP1 program node.
  7. Select the Identify conditional statements option.
    The image shows the Identify conditional statements option.
    A new workbook page is displayed, which takes you to the source file of LGTESTP1 and presents the conditional statements in this particular program.
    The image shows the source code view of LGTESTP1.
  8. Right-click the WHEN ‘1’ on line 81 that corresponds to ENP1OPTO=‘1’, and select Slice on conditional statement to new workbook. A Slice to new workbook dialog is displayed.
    The image shows the Slice on conditional statement to new workbook option.
  9. Type a name for the workbook that you create, for example, type Insert Motor API Logic.
  10. Click Save to create the workbook. A new workbook pane is displayed on the left, which shows four service code blocks for the Insert Motor API Logic workbook that you created. You will find the first code block for the WHEN ‘1’ branch that is obtained after slicing as follows:
    The image shows the first code block.
  11. Review the program calls, SQL statements if any, and string assignment statements in the code block. You can see MOVE ‘01IMOT’ To CA-REQUEST-ID, an important statement that controls the business logic flow in subsequent program calls. The statement also makes a call to the program LGIPOL01. Therefore, the next step is to get the relevant code for Inquire logic from LGIPOL01.
  12. Click the Graph tab on the upper right corner to navigate to the closure view and check the programs that are called by LGTESTP1.
  13. Click the Action Menu (The image shows the Action Menu icon.) icon on the upper right corner of the LGIPOL01 program node.
  14. Select the Identify conditional statements option.
    The image shows the Identify conditional statements option.

    The conditional statements in LGIPOL01 are displayed.

  15. In LGIPOL01, only a specific portion of Mainline paragraph should be brought into the workbook, since other portions in the program are not performing any business logic specific operations. Select the code portion as shown in the following screen capture, right-click, and select Copy selected lines to current workbook.
    The image shows the selected code portion.
  16. In the Copy to current workbook dialog that is displayed, click Save.
  17. Inspect the newly added code block. You can see that the code block calls LGIPDB01 program. Therefore, next you will identify the key conditional statements for LGIPDB01.
    The image shows the newly added code block.
  18. Click the Graph tab on the upper right corner to navigate to the closure view.
  19. Click the Action Menu (The image shows the Action Menu icon.) icon on the upper right corner of the LGIPDB01 program node.
  20. Select the Identify conditional statements option.
    The image shows the Identify conditional statements option.

    The conditional statements in LGIPDB01 are displayed.

  21. In LGIPDB01, trace the WS-REQUEST-ID backwards, and you will see that CA-REQUEST-ID gets assigned to it. Select the condition WS-REQUEST-ID= ‘01IMOT’ as shown in the following screen capture, right-click, and select Copy selected lines to current workbook.
    The image shows the Copy selected lines to current workbook option.
  22. In the Copy to current workbook dialog that is displayed, click Save.

The workbook now contains the isolated code and is ready to be exported as a COBOL code to create a service. When the service is ready and deployed, the API can invoke the dedicated service instead of calling the monolith code and specify the CA-REQUEST-ID value to be taken.