Package com.ibm.etools.pli.application.model.pli

See: Description

Package com.ibm.etools.pli.application.model.pli Description

PL/I Application Model API Specification

This package contains interfaces that represent the nodes of a syntax tree for a PL/I program. Each node of the syntax tree represents part of a PL/I program.

This package was generated from an Eclipse Modeling Framework model, but you do not need to use the EMF capabilities unless they are useful to you. Here is a brief description of some of the terms in the documentation that you might not be familiar with:

In the model, when a list is returned, if there are no items in the list, an empty list is returned, rather than returning null.

Most nodes in the syntax tree subclass the PLINode class. This class contains location information about where the code that is represented by the node is found in the source code, including file, line, and column information.

The ProgramSourceFile node represents the contents of the entire source file. A ProgramSourceFile object contains four features that represent all of the statements and structures in the source file. The getProcessDirectives() method returns a list of ProcessDirective objects, which represent process directives. The getStatements() method returns a list of PLINode objects. This list represents every statement in the source file that is not a process directive. The list does not account for structural elements in the program. Macro language statements and PL/I statements can be interspersed in the list, and appear in the order in which they occur in the source file. The getMacroStructure() method returns a MacroProgramStructureNode object, which contains references to all of the statements in the list returned by getStatements(), and models any structural Macro language objects such as Macro procedures, DO-groups, and SELECT-groups as Macro structure node objects. The getPliStructure() method returns a ProgramStructureNode object, which represents any structural PL/I language objects such as packages, procedures, BEGIN-blocks, DO-groups, and SELECT-groups. Note that PL/I language objects that are excluded in the source due to Macro expansion will not appear in the ProgramStructureNode, but do appear in the "flat" list of statements returned by getStatements(). To investigate individual statements in the source file, you can visit the list of statements retrieved from getStatements() or drill down to individual statements using the structure nodes.

For an example of how the statements and structures are modeled, consider the following code snippet:

 IF X = 0 THEN
   DO;
     DISPLAY('X is zero');
   END;
 ELSE
   DO;
     DISPLAY('X is non-zero');
   END;
In the list of statements returned by getStatements() this snippet is modeled by 8 statements ( IfStatement, DoStatement, DisplayStatement, EndStatement, ElseStatement, DoStatement, DisplayStatement, EndStatement, respectively). However, in the ProgramStructureNode returned by getPliStructure(), the snippet is modeled by an IfElseCompoundStatement. If you drill down into the statement, getIfStatement() returns a NodeReference that points to the IfStatement, getThenUnit() returns a DoGroup that represents the first DO-group, getElseStatement() returns a NodeReference that points to the ElseStatement, and getElseUnit() returns a DoGroup that represents the second DO-group.

If you are interested in examining how types, variables, or constants are declared, locate the DEFINE or DECLARE statement where the item is declared and drill down to the attributes. Note that the attributes returned reflect what is coded in the statement. The returned attributes do not reflect default attributes. The Attribute class is the parent class for all of the attributes that can be used to describe a declared item.

When labels, constants, functions, subroutines, or variables are mentioned in a PL/I statement, a Reference object is used to represent the reference. The Reference class is abstract, and has several subclasses that represent different kinds of references such as simple references, qualified references, and function references. Any Reference object has a getDeclaration() that returns the node where the referenced object was declared. Note that for PL/I language statements that are excluded from the expanded source code due to Macro language statements, the getDeclaration() method will return null. For undeclared objects such as implicit variables and undeclared builtins, the getDeclaration() method returns either an ImplicitDeclaration or ImplicitBuiltinDeclaration object. Note that these objects do not subclass PLINode since they do not actually appear in the source code, and therefore have no location features.

PL/I expressions are represented by the subclasses of the abstract class Expression. The expression subclasses include nodes representing references, unary expressions, and binary expressions (those expressions with an infix operator and left and right expressions).

Limitations

The following list contains the known limitations of the PL/I Application Model. These areas are subject to change in a future release.