XTRAN Example — Create abstract of COBOL code

Scenario — you have inherited a body of COBOL code, and you want to review it without getting ensnared in its gory details.

XTRAN to the rescue!

The following example uses an XTRAN rules file comprising 288 non-comment lines of XTRAN's rules language ("meta-code") to create an abstract of COBOL from the code itself. The rules took 4 hours to write and 3 hours to debug. (That's right, only 7 hours total!)

The XTRAN rules used for this example are not specific to COBOL; they can be used unchanged to abstract any 3GL language.

The rules are also command-driven, allowing you to easily create a wide variety of different kinds of abstracts. They allow you to specify, via commands, categories of statements. For each category, you can specify:

What statement types are in the category.
What to do with each statement whose type is in the category:
- Don't show the statement or its children in the abstract.
- Don't show the statement in the abstract, but do show its children.
- Show the statement in the abstract, but don't show its children.
- Show only the first in a series of statements in the category at the same level, effectively collapsing the sequence.
A description to show in the abstract.

For this example, we specified, via commands, the following categories and their properties (only those relevant to the example are shown):

Category's statement types	Show statement?	Show children?	Collapse statement sequences?	Description for abstract
`ENVIRONMENT DIVISION`	Yes	No	N/A	`Environment division`
`IDENTIFICATION DIVISION`	Yes	No	N/A	`Identification division`
`PROCEDURE DIVISION`	Yes	Yes	N/A	`Procedure division`
`WORKING-STORAGE SECTION`	Yes	Yes	N/A	`Working storage`
`IF`	Yes	Yes	No	`If`
`ELSE`	Yes	Yes	No	`Else`
`EVALUATE`	Yes	Yes	No	`Selection`
`WHEN`	Yes	Yes	No	`Selection value`
`STOP RUN`	Yes	N/A	No	`Exit program`
(Data declaration)	Yes	No	Yes	`Data declarations`
`ADD`, `COMPUTE`, `SUBTRACT`	Yes	N/A	Yes	`Arithmetic`
`MOVE`	Yes	N/A	Yes	`Data movement`
`END-EVALUATE`, `END-IF`	No	N/A	N/A	N/A

How can such powerful code abstraction be automated in only 7 hours and only 288 code lines of XTRAN rules? Because there is so much capability already available as part of XTRAN's rules language. These rules take advantage of the following functionality:

Text file input and output (to read the commands)
Text manipulation
Delimited list manipulation (to parse the commands)
Environment variable manipulation (to specify the output file)
Content-addressable data bases (to store the abstracting specs)
"Per statement" recursive iterator (to process all statements)
Access to XTRAN's Internal Representation, or XIR (to get statements' types)
XIR's language-independent properties
Navigation in XIR (to explore a statement's context)
Creating new meta-functions written in meta-code, which we call user meta-functions

The input to and output from XTRAN are untouched.

Process Flowchart

Here is a flowchart for this process, in which the elements are color coded:

BLUE for XTRAN versions (runnable programs)
ORANGE for XTRAN rules (text files)
RED for code
PURPLE for text data files

Input to XTRAN:

       IDENTIFICATION DIVISION.
       PROGRAM-ID.    ABSTRACTING-EXAMPLE.
       AUTHOR.        KELLY A DEVELOPER.
       INSTALLATION.  SOME COBOL SHOP SOMEWHERE.
       DATE-WRITTEN.  MAY 2018.
       DATE-COMPILED. May 2018.
      *REMARKS.  JUST TO SHOW OFF XTRAN.
      *
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       SOURCE-COMPUTER. WHIZ-BANG-1000.
       OBJECT-COMPUTER. WHIZ-BANG-1000.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  AMT                    PIC 9(7)V99.
       01  PAGE-TOTAL             PIC 9(8)V99     VALUE 0.
       01  DIFF                   PIC 9(7)V99.
       01  TOTAL                  PIC 9(7)V99.
       PROCEDURE DIVISION.
       DO-IT.
          ADD AMT TO PAGE-TOTAL
          SUBTRACT AMT FROM TOTAL GIVING DIFF
          COMPUTE AMT = AMT + 1
          IF AMT < 1.00 THEN
              MOVE 1.0 TO AMT
              MOVE 2 TO TOTAL
          ELSE
              ADD 2 TO AMT
              MOVE AMT TO TOTAL
              MOVE TOTAL TO PAGE-TOTAL    
              EVALUATE AMT
                  WHEN 1
                       MOVE 2 TO AMT
                       MOVE 1 TO DIFF
                       ADD 1 TO AMT
                       SUBTRACT 1 FROM TOTAL
                  WHEN OTHER
                       ADD 1 TO AMT
                       COMPUTE TOTAL = AMT + 2
                  END-EVALUATE
              END-IF
          ADD 1 TO AMT
          COMPUTE TOTAL = 1
          STOP RUN.

Output from XTRAN:

Identification division
Environment division
Data division
    Working storage
        Data declarations
Procedure division
    Arithmetic
    If
        Data movement
    Else
        Arithmetic
        Data movement
        Selection
            Selection value
                Data movement
                Arithmetic
            Selection value
                Arithmetic
    Arithmetic
    Exit program