Rational Developer for System z

Using the COBOL Application Model APIs

Use the Custom Rules API for COBOL Code Review and the COBOL Application Model API (CAM) to analyze the COBOL language elements that you selected for your user-written custom rule.
Note: For the latest information see IBM® technotes for Rational® Developer for System z®.

The COBOL Application Model APIs

The two APIs are complementary and some knowledge of both is required to implement a user-written custom rule:

  • Custom Rules API for COBOL Code Review

    This API provides the base class for user-written rules and includes useful classes for manipulating the objects in the COBOL Application Model (CAM).

    To read the documentation for this API click Reference > Application Programming Interfaces > COBOL Application Model APIs > Custom Rules API for COBOL Code Review in the table of contents of the online help.

  • COBOL Application Model (CAM) API

    This API provides interfaces for accessing the elements of a COBOL source code program while the program is being analyzed by the COBOL Code Review component.

    To read the documentation for this API click Reference > Application Programming Interfaces > COBOL Application Model APIs > COBOL Application Model API in the table of contents of the online help.
    Note: To read an overview of this API:
    1. Open the API documentation. The first topic is Package com.ibm.etools.cobol.application.model.cobol.
    2. Scroll to the end of the topic and read the Description section.

Implementing code analysis for a custom rule

To implement the code analysis for a custom rule:
  1. Open the generated Java™ source file for the custom rule:
    1. Open the Plug-in Development perspective if it is not already open.
    2. In the Package Explorer, right-click the Java source file that was generated for your custom rule, then click Open With > Java Editor.
      Note:
      • The location of the Java file in the Package Explorer is project_name > src > package_name > class_name.java.
      • For example: MyPluginProject > src > com.example > CobolRule.java.
  2. In the Java editor, add Java code as needed to each of the generated visit() methods to do the required code analysis.

    A visit() method is generated for each nonabstract subinterface of the Cobol Application Model interface corresponding to the COBOL language element that you selected.

    For example, suppose that you selected the ACCEPT element in the Program tree on the third page of the creation wizard:
    • The CAM interface corresponding to ACCEPT is the AcceptStmt interface.
    • The javadoc for the AcceptStmt interface shows, under the heading All Known Subinterfaces, that AcceptStmt has two subinterfaces: AcceptDataTranferStmt and AcceptSystemInfoTransferStmt.
    • Therefor two visit() methods are generated, one for each of the two subinterfaces.
    Note:
    • The visit() methods belong to the Interface ICOBOLVisitor, in the package com.ibm.rsar.analysis.codereview.cobol.custom.model.util, in the Custom Rules API for COBOL Code Review. Subclassing AbstractCOBOLVisitor rather than implementing ICOBOLVistor directly is recommended. In this example the generated visit() methods are as follows:
      • boolean visit(com.ibm.etools.cobol.application.model.cobol.AcceptDataTransferStmt n)
      • boolean visit(com.ibm.etools.cobol.application.model.cobol.AcceptSystemInfoTransferStmt n)
    • The node passed as input to a visit() method is a subinterface of the interface ASTNode in the package com.ibm.etools.cobol.application.model.cobol in the COBOL Application Model (CAM) API.

    When a code analysis is performed on a COBOL source file, the code analyzer invokes a visit() method whenever it encounters an instance of the corresponding ASTNode. In each visit() method, add Java code to do the following:

    1. Use the ASTNode n that is passed as input to the visit() method to get information about the instance of the COBOL language element that you are analyzing. For example, to get the Program ID attribute of the Identification division, where n is an IdentificationDivision object, you could write:
      String myProgramID = n.getProgramId();
    2. Perform the code analysis required by your custom rule. If you have more than one visit() method for your rule, you will probably also need to write Java code to coordinate the results from the individual visit() methods.
    3. Set the return code and the return information. Return true to continue visiting child nodes of the current node or false to skip visiting child nodes. If the COBOL language element that is being analyzed violates the rule, add the corresponding node to the tokens list.
    4. When you are finished close the Java editor.

Feedback