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.
/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
- You have installed and configured Z Refactoring Assistant as instructed in Getting started.
- You have built the GenApp in the IBM AD Build Client as described in Prerequisite: Building the GenApp project.
Procedures
- Launch your browser and go to https://<hostname>:9443. By default, you will be on the Workspaces tab.
- 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:
- Click the Create workspace button on the upper right corner of the Workspaces page.
- In the
Create workspace
dialog, type a name for the workspace that you want to create, for example, GenApp. - From the AD project drop-down list, select the project that you built with IBM AD Build Client.
- Click Create to create the workspace. When the creation is
completed, the Graph view of the
GenApp
workspace is displayed.
- Type SSMAP in the search box. You will see
SSMAP - Copybook
in the results. - 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. - Type LGTESTP1 in the search box, and select the
LGTESTP1 - Program
result item to compute LGTESTP1 closure. - Click the Action Menu (
) icon on the upper right corner of the LGTESTP1 program node.
- Select 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.
- Right-click the
WHEN ‘1’
on line 81 that corresponds to ENP1OPTO=‘1’, and select Slice on conditional statement to new workbook. ASlice to new workbook
dialog is displayed. - Type a name for the workbook that you create, for example, type Insert Motor API Logic.
- 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: - 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 forInquire
logic from LGIPOL01. - Click the Graph tab on the upper right corner to navigate to the closure view and check the programs that are called by LGTESTP1.
- Click the Action Menu (
) icon on the upper right corner of the LGIPOL01 program node.
- Select the Identify conditional statements option.
The conditional statements in LGIPOL01 are displayed.
- 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.
- In the
Copy to current workbook
dialog that is displayed, click Save. - 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.
- Click the Graph tab on the upper right corner to navigate to the closure view.
- Click the Action Menu (
) icon on the upper right corner of the LGIPDB01 program node.
- Select the Identify conditional statements option.
The conditional statements in LGIPDB01 are displayed.
- In LGIPDB01, trace the
WS-REQUEST-ID
backwards, and you will see thatCA-REQUEST-ID
gets assigned to it. Select the conditionWS-REQUEST-ID= ‘01IMOT’
as shown in the following screen capture, right-click, and select Copy selected lines to current workbook. - 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.