Technical information

RainCode can parse virtually all PL/1 dialects available today, including Native recognition of most CICS and SQL statements. The input can be raw source, and facilities to remove leading numbering and/or trailing annotation are included. Similary, a pattern-based mechanism can be used to process listing or JCL files where the source code is mixed with various external textual components.

Typical uses

• Quality assessment for outsourced work. When a project is submitted to an external company, precise coding guidelines can be defined formally as part of the assignment. Such guidelines can then be checked continuously or at delivery time on the entire source code, rather than relying on random sampling. Besides, an exhaustive analysis provides a number of metrics that quantify the degree of compliance, which gives you a precise estimation of the amount of work required to achieve full compliance, rather than a binary answer.
• In a migration project, performing large amounts of updates automatically, identifying the places that must be updated manually, predicting the total effort required for this manual update, and monitoring the progress of the entire migration. Examples of such migrations cover the replacement of a compiler by another, the change of platforms, TP monitor or database.
• Integration in a compilation chain to ensure that every source code is compliant before it can even be tested. The standard language within an organisation or a project moves from plain PL/1 to PL/1 restricted by the coding guidelines.
• Implementation of a complete metrics and quality strategy. This includes monitoring the quality and maintainability of all components continuously, predicting maintenance costs, detecting abnormal entropy within systems before it becomes a maintenance issue. Metrics, such as cyclomatic complexity of functions, can be performed on a daily basis.

The RainCode Engine for PL/1 is used to generate the RainCode Roadmap for PL/1.

How does it work ?

RainCode actually reads the PL/1 source code and builds an annotated parse tree after a fully documented object model, including inheritance relationships (IfStatement inherits from Statement). A scripting language can then be used to walk through the parse tree, taking full advantage of the features provided by the object model. By using the parse tree rather than its underlying textual representation, RainCode can deal with cases far too complex to be handled by text manipulation tools such as Perl.

RainCode supports both procedural and event-driven programming, the latter being used for simple scripts, such as:

    ON GotoStatement DO
      OUT.WriteLn ('Goto statement found on line ', X.LineNr);
      END;

The scripting language is a very simple dynamically-typed ALGOL-like language, and provides various features specifically designed for the purpose of manipulating parse trees:

• Quantifiers:

         c := COUNT [var] IN ROOT.SubNodes :- (var IS DataReference)
                                              AND (var.Ref = VOID);
         IF c > 0 THEN
           OUT.WriteLn ('There are ',
                        c,
                        ' variables, which are implictly declared');
          END;
  

  The above example counts the number of variables for which there is no explicit declaration. If there are some, the count of such variables is displayed.
  
  
• Annotations to add user-defined information to the parse tree
• Convenient list and set-manipulation primitives

• Access to the system resources (reading and writing files, spawning sub-processes)
• Library of string and mathematical functions
• Access to XML tree via the DOM API
• Modularity, so that libraries of routines can be built, and reused in several scripts

RainCode comes with numerous documented scripts that implement various checking and documentation functions that can be used out of the box or changed to adapt to a specific environment. It also includes the entire script source code of the RainCode Roadmap.

Available information

The parse tree provided by RainCode includes the entire syntactical information (that is, for every component, access to its sub-components, the image of identifiers, whether optional keywords have been used or not, etc.), and positioning information to be able to resynchronize on source code. It also includes semantic information, such as the variable an identifier refers to, the statement block (section or paragraph) a GOTO statement branches to, etc. In case of an identifier that refers to a variable, RainCode also provides information about the way in which it uses the variable: read, write or read/write. This information can be used to perform sophisticated impact analysis.

The patch mechanism

RainCode also supports a complete patching mechanism to perform changes on the source code. This can range from trivial cosmetic changes such as pretty printing to normalization issues such as adding explicit declaration for all implicitly declared variables. The patch mechanism can also be used for far more exotic things. For instance, it has been used to produce wrappers around CICS transactions so that they could be triggered from within WEB-based applications.

Distribution

The RainCode distribution includes:

• A binary executable for NT
• Obfuscated source code for easy recompilation on most Unix platforms (tested under Solaris, Linux, AIX, HP/Unix)
• A printed documentation set
• The PostScript source for this documentation, so that additional copies can be produced conviently
• The entire documentation, including the user manual and a reference guide, structured as a set of HTML files
• Numerous thoroughly documented sample scripts