PL/I Code Explanation examples

Examples

2.4+

For a selected PL/I source code, the code explanation service provides three levels of code explanation: Simple, Detailed, and Guided.

Given here is an example for the different levels of AI-generated explanations from watsonx Code Assistantâ„¢ for Z using the following PL/I code.

Example: Selected PL/I step

FMT_TOT1: FORMAT ( SKIP,X(2),A(15),X(4),A(11),A(11),
                             X(3),A(11),A(11),X(3),A(11),A(11) );
     PUT FILE (CUSTRPT) SKIP (1) LIST ( SPACE );
     PUT FILE (CUSTRPT) SKIP (1) LIST ('TOTALS REPORT');
     PUT FILE (CUSTRPT) SKIP (1) LIST ((99)'-');
     IF ( NUM_PRINT_COMPLETED > 0 ) THEN DO;
       NUMA_7V2 = BALANCE_TOTAL;
       NUMB_7V2 = BALANCE_MAX;
       NUMC_7V2 = BALANCE_AVG;
       PUT FILE (CUSTRPT)
          EDIT ('ACCT BALANCE:',
          '     TOTAL:', NUMA_7V2,
          '       MAX:', NUMB_7V2,
          '   AVERAGE:', NUMC_7V2 )
          (R(FMT_TOT1));
       NUMA_11 = NUM_CUSTFILE_RECS;
       NUMB_11 = NUM_CUSTOMER_RECS;
       PUT FILE (CUSTRPT)
          EDIT ('RECORD COUNTS:',
          ' ALL TYPES:', NUMA_11,
          ' ALL TYPES:', NUMA_11,
          ' CUST RECS:', NUMB_11 )
          (R(FMT_TOT1));
       NUMA_11 = NUM_TRANSACTIONS;
       NUMB_11 = NUM_TRANSACTIONS - NUM_TRAN_ERRORS;
       NUMC_11 = NUM_TRAN_ERRORS;
       PUT FILE (CUSTRPT)
          EDIT ('TRANSACTIONS:',
          '     COUNT:', NUMA_11,
          ' PROCESSED:', NUMB_11,
          '    ERRORS:', NUMC_11 )
          (R(FMT_TOT1));
       NUM_TOTALS_COMPLETED = NUM_TOTALS_COMPLETED + 1;
     END;     /*  IF NUM_PRINT_COMPLETED > 0   */
     ELSE DO;
       PUT FILE (CUSTRPT) SKIP (1)
          LIST ('CANNOT COMPLETE TOTALS TRAN. ',
                'A PRINT TRAN MUST BE REQUESTED/PROCESSED FIRST.');
     END;

Example 1: Simple PL/I explanation

Summary of the business purpose of the code: The code is part of a larger program that processes customer transactions in a banking system. It calculates various totals related to account balances, transaction counts, and error rates. These totals are then printed out in a report format.
Input and output records: There are no explicit input or output records mentioned in the code snippet provided. However, it is assumed that there are global variables defined elsewhere in the program that hold the necessary data for calculations and printing.
Free-text summary of the code logic: 
1. The code defines a format called `FMT_TOT1` which specifies how certain values should be displayed in the final report. This includes formatting options such as spacing and alignment.
2. The code begins by skipping one line before printing the title "TOTALS REPORT".
3. Next, the code prints a horizontal line consisting of dashes using the `PUT FILE (CUSTRPT) SKIP (1) LIST ((99)'-')` statement.
4. If the variable `NUM_PRINT_COMPLETED` is greater than zero, indicating that at least one print transaction has been completed, the code proceeds to calculate and display several totals.
   - `NUMA_7V2`, `NUMB_7V2`, and `NUMC_7V2` are assigned values based on other global variables representing different aspects of the total balance calculation.
   - These calculated values are then used in an `EDIT` statement along with text labels to create formatted output lines using the `FMT_TOT1` format.
   - Finally, these output lines are printed using the `PUT FILE (CUSTRPT)` statement.
5. After displaying the account balance totals, the code continues to calculate and display record counts for all types of records (`NUMA_11`), only customer records (`NUMB_11`), and transaction errors (`NUMC_11`). Again, these calculated values are used in an `EDIT` statement along with text labels to create formatted output lines using the `FMT_TOT1` format.
6. Lastly, the code increments the variable `NUM_TOTALS_COMPLETED` to keep track of the number of times this section of code has executed successfully.
Example 2: Detailed PL/I explanation
The given PL/I procedure is used to generate a report for account balances in a banking system. The report includes various details such as total balance, maximum balance, average balance, record counts, transaction counts, processed transactions, and error transactions. 
The inputs to the procedure are the file CUSTRPT which is the output file where the report will be written, and the variables NUM_PRINT_COMPLETED, BALANCE_TOTAL, BALANCE_MAX, BALANCE_AVG, NUM_CUSTFILE_RECS, NUM_CUSTOMER_RECS, NUM_TRANSACTIONS, and NUM_TRAN_ERRORS which contain the necessary data for generating the report.
The outputs from the procedure are the updated values of the input variables NUM_TOTALS_COMPLETED and NUM_TOTALS_ERRORS if any errors occur during processing.
Here's a detailed functional summary per function:
1. OPEN FILES: Opens the output file CUSTRPT for writing.
2. WRITE HEADER LINES: Writes header lines including "TOTALS REPORT" and a line of dashes below it.
3. CHECK FOR DATA: Checks if there is any data available for processing by checking if NUM_PRINT_COMPLETED is greater than zero. If not, writes an error message indicating that a print transaction must be requested or processed first.
4. CALCULATE AND WRITE DETAIL LINES: Calculates and writes detail lines for account balance totals, record counts, and transaction counts using the provided variables.
5. UPDATE COUNTERS: Updates the counters NUM_TOTALS_COMPLETED and NUM_TOTALS_ERRORS based on whether any errors occurred during processing.
Example 3: Guided PL/I explanation
1. Business Purpose: The purpose of this PL/I procedure is to generate a report that displays the total account balance and record counts for customer records in a database. It also calculates the number of transactions processed and errors encountered during processing.
2. Code Logic Summary:
   Step 1: Define the format for the output report using the FORMAT statement.
   Step 2: Open the file CUSTRPT for writing.
   Step 3: Print a page heading "TOTALS REPORT" followed by a line of dashes.
   Step 4: Check if there are any completed print transactions available. If so, calculate and display the total account balance, maximum balance, average balance, count of all types of records, count of customer records, count of transactions processed, and count of transaction errors. Increment the counter variable NUM_TOTALS_COMPLETED.
   Step 5: If no completed print transactions are available, display an error message indicating that a print transaction must be requested or processed first.