Checking Natural Code with NATstyle

This document covers the following topics:


General Information

NATstyle helps you write Natural code which adheres to your coding standards. It can check the source code of all Natural object types.

Restrictions:

  • NATstyle only checks the Natural objects in the Eclipse workspace. It does not check the objects on a Natural server.

  • NATstyle does not download missing sources from a Natural server when checking code.

  • NATstyle checks only the selected objects. However, if the Parser check option is active in the NATstyle preferences, any objects called using the INCLUDE and USING statements are also checked, if available in the Eclipse workspace.

  • NATstyle uses only the settings from the .natural file (for example, the DC character or steplib settings). It does not download any settings (for example, Natural Security settings) from a Natural server.

Checking the Natural Code

NATstyle uses the settings in the Natural preferences in order to check your Natural code. You can either use the default settings or you can create your own configuration file(s) containing your own rules for checking the Natural code. For further information, see NATstyle in Setting the Preferences.

Start of instruction setTo check the Natural code

  1. In the Project Explorer view or in the Natural Navigator view, select the project, library or source file for which you want to check the Natural code.

  2. Invoke the context menu and choose NaturalONE > NATstyle Check.

    Or:
    Use the keyboard shortcut CTRL+SHIFT+C.

    If you check a large number of files, the check may take a while.

    Any NATstyle violations (that is, found errors, warnings and information messages) are shown in the Problems view. If you want to view, for example, the information messages, you expand the Infos node.

    Problems view

  3. Double-click an entry in the Problems view.

    The Natural editor for this type of object is invoked and the corresponding line is selected. One of the following NATstyle markers is shown for each problematic line:

    Marker Type
    Error Error
    Warning Warning
    Info Information

    In addition to the information in the Problems view and the NATstyle markers in the editors, the icon of each node in the Project Explorer view or Natural Navigator view for which a NATstyle violation has been reported contains a corresponding decoration.

  4. Change the code as appropriate.

    Notes:

    1. The error message "No NATstyle results, parser ended" means that the checked Natural object contains a parser error. Before it is possible to check a Natural object with NATstyle, you have to correct all parser errors.
    2. The source header cannot be modified. When a line in the source header is selected, specify the appropriate information (for example, the programming mode) in the properties for that object.
    3. The line number given for a map can be found on the List page of the map editor.
    4. For DDMs, only general messages are provided which always refer to line 1.
    5. There are messages for which an editor cannot be invoked, for example, "NATdoc library documentation (library.html) missing" which refers to the contents of a library.

Clearing the NATstyle Violations

When you correct your sources, any previously detected NATstyle violations are not automatically removed. This includes the entries in the Problems view, the NATstyle markers in the editors, and the decorations in the Project Explorer view or Natural Navigator view. If you want to remove the NATstyle violations, for example, for a specific library, you can clear them as described below.

Note:
The NATstyle Check command automatically updates the existing NATstyle markers in the editors, the decorations in the Project Explorer view, and the entries in the Problems view.

Start of instruction setTo clear the NATstyle violations

  1. In the Project Explorer view or in the Natural Navigator view, select the project, library or source file for which you want to clear the NATstyle violations.

  2. Invoke the context menu and choose NaturalONE > NATstyle Clear.

    Or:
    Use the keyboard shortcut CTRL+SHIFT+D.

Working with Result Files

The following topics are covered below:

Saving the Result of a NATstyle Check to a File

You can write the result of a NATstyle check to an XML file. The result always applies to the entire project. In this case, no information is written to the Problems view, no decorations are applied in the Project Explorer view or Natural Navigator view, and no NATstyle markers are set in the editors.

When you save the results to the XML file, all Natural object types as specified in the NATstyle preferences are checked. Any previously generated NATstyle information in the Problems view is disregarded. Therefore, it is not necessary to invoke the NATstyle Check command prior to saving the results.

Note:
The NATstyle Save command does not change or remove any already existing information in the Problems view, decorations in the Project Explorer view or Natural Navigator view, or NATstyle markers in the editors.

Start of instruction setTo save the result of a NATstyle check to a file

  1. In the Project Explorer view or in the Natural Navigator view, select the project for which you want to save the results.

  2. Invoke the context menu and choose NaturalONE > NATstyle Save.

    A dialog box appears, providing the file name NATstyleResult.xml as a proposal.

  3. Specify a file name.

    It is recommended that you store the result file in the project for which it is created. This is helpful, if you later want to load the result file for this project.

  4. Choose the Save button to create the NATstyle result file.

Loading a NATstyle Result File

You can load a previously saved NATstyle result file. This updates the existing NATstyle information in the Problems view, the decorations in the Project Explorer view or Natural Navigator view, and the NATstyle markers in any previously opened editors.

Start of instruction setTo load a NATstyle result file

  1. In the Project Explorer view or in the Natural Navigator view, select the project for which you want to load the result file.

  2. Invoke the context menu and choose NaturalONE > NATstyle Load.

    A dialog box appears showing the root directory of the selected project.

  3. Select the result file which has been created for this project.

  4. Choose the Open button.

Invoking NATstyle from Outside Eclipse

You can invoke NATstyle without having to invoke Eclipse. To do so, you invoke the class com.softwareag.naturalone.natural.natstyle with certain command line parameters.

For example, when you invoke NATstyle from within a batch file, the command line parameters can be specified as follows:

"%JAVAPATH%\bin\java.exe" -cp %CLASSPATH% 
com.softwareag.naturalone.natural.natstyle.NATstyle -projectpath %PROJECTPATH% 
-rootfolder -o %OUT%\NATstyleResult.xml >%OUT%\NATstyleGeneration.log

Note:
Make sure to specify the above information in a single line.

It is important that the following classes can be found in your class path:

com.softwareag.naturalone.natural.auxiliary
com.softwareag.naturalone.natural.common
com.softwareag.naturalone.natural.parser

The following command line parameters are available:

Command Line Parameter Description
-projectpath directory Path to the directory which contains the Natural project. For example: C:\Users\user01\workspace\MyProject.
-rootfolder Enable library root folder support. The folder Natural-Libraries is available. For example: C:\Users\user01\workspace\MyProject\Natural-Libraries .
-sourcepath directory Path to the source files, including library and root folder.
-c file Name of the configuration file, including path and extension. For example: C:\Users\user01\NATstyleConfig.xml.
-o file Name of the output (result) file, including path and extension. For example: C:\Users\user01\NATstyleResult.xml.
-sourcefiles file-names With this option individual sources can be selected for the NATstyle check. The names of the Natural sources (with file extension) preceded by the library container are specified. The library/source name pairs are separated using the semicolon (;) character. For example:

-sourcefiles MYLIB1/MYPGM1.NSP;MYLIB1/MYSUB1.NSN;MYLIB2/MYCPYCDE.NSC

Note:
It is not necessary to specify the used libraries with the -libraries option.

-libraries library-names Names of the Natural libraries to be checked. Separate the names using the semicolon (;) character. For example:

-libraries MYLIB1;MYLIB2

-exclude library-names Names of the Natural libraries to be excluded from checking. Separate the names using the semicolon (;) character.
-quiet Do not display status messages.
-help Display command line options and exit.

Overview of NATstyle Rules, Error Messages and Solutions

Rules for the following types of checks can be defined in the NATstyle preferences:

The rule names in the tables below are the names that are used in the Configuration group box of the NATstyle preferences.

Source Check

NATstyle provides the following rules for checking Natural sources:

Rule Description
Line length Check the length of every source code line. For compatibility with the mainframe, the line length should be less than or equal to 72. In Linux and Windows environments, Natural allows lines which are up to 245 characters long.
Error Messages

Line too long.

No input file.

Value is not in range 10 - 245.

Solution Reduce the line length. Line constants may be split so that they use more than one line.
Whitespace Check whether additional blank characters or tabs are used at the end of a source code line. Tab characters may cause problems in mainframe environments.
Error Messages

Line has trailing spaces.

Line has trailing tabs.

No input file.

Solution Remove any blank characters or tabs at the end of a line.
Tab character Check whether tab characters are used. Tab characters may cause problems in mainframe environments.
Error Messages

Line contains tabs.

No input file.

Solution Replace the tab characters with blanks.
Line numbers Check the first four characters of every source line. If these characters are numeric and ascending, the source has line numbers. Numbered sources are only used in the server environment. NaturalONE does not use numbered lines.
Error Messages

File has line numbers.

File has line numbers (not ascending).

No input file.

Solution Remove the line numbers. The file may have been copied directly from the server environment (for example, using Natural Studio). It is recommended that you use the Natural Server view in order to download your sources into a project of your Eclipse workspace.
Empty lines Check whether the source code contains empty lines. For compatibility with the mainframe, empty lines should be avoided because the Natural editors on the mainframe remove empty lines.
Error Messages

Empty line.

No input file.

Solution Remove the empty line or mark the line as a comment.
Regular expression for single source lines Check each source code line against a regular expression. For example, when you search for "find loop", this will only be found if the entire string is contained in a single line. For examples on regular expressions, search the internet for "java.util.regex.Pattern".
Error Messages

Regular expression not valid: %1%.

Line matches regex: '%1%'.

No input file.

Solution Remove or change the found code.
Regular expression for multiple source lines Check the complete source against a regular expression. For example, when you search for "find loop", this will also be found if there is a line break between "find" and "loop". For examples on regular expressions, search the internet for "java.util.regex.Pattern".
Error Messages

Regular expression not valid: %1%.

Source matches regex: '%1%'.

No input file.

Solution Remove or change the found code.
Newline at end of line missing Check whether a file ends with a newline character.
Error Messages

File does not end with newline.

No input file.

Solution Add an empty line at the end of the file.
Maximum number of source lines Check whether the maximum number of source lines (9999) has been exceeded.
Error Messages

Too many source lines.

No input file.

Value is not in range 10 - 9999.

Solution Reduce the number of source lines. For example, you can externalize parts of the program or delete comment lines.

Source Header Check

NATstyle provides the following rules for checking the Natural source header:

Rule Description
Header Check whether the source has a valid Natural source header.
Error Messages

Has no source header.

No Natural source type.

No input file.

Solution Open the file with the source editor and save it. A source header will then be added automatically.
Has different Natural name Check whether the source has a valid Natural source header, and check whether it contains a Natural object name (:NatName). The Natural object name is only shown in the source header when a file name exists for the object.
Error Messages

Source has different Natural name: %1%.

No Natural source type.

No input file.

Solution Rename the file with a name that matches the naming conventions.
Programming mode Check the programming mode of the source.
Error Messages

Is structured mode.

Is reporting mode.

No Natural source type.

No input file.

Solution Rewrite the program with the appropriate programming mode.
File name naming convention If the source header contains a Natural object name, check the file name of the source.
Error Messages

Natural source name does not match naming conventions '%1%'.

No Natural source type.

No input file.

Solution Rename the file so that it matches your regular expression.
Struct Check whether the source code lines are indented in such a way that the indentation reflects the structure of the program.
Error Messages

Not structed correctly.

Struct ended with error: %1%.

No Natural source type.

No input file.

Value is not in range 10 - 245.

Value is not in range 1 - 9.

Solution Open the source with the source editor and use the Struct command.
DDM naming convention Check whether the names of DDMs match the naming conventions.
Error Messages

DDM name does not match naming conventions '%1%'.

No Natural source type.

No input file.

Solution Rename the DDM so that it matches the naming conventions.

Parser Check

NATstyle provides the following rules for checks on parser level:

Rule Description
Data area define data Check whether at least one variable has been defined in the DEFINE DATA block of a local data area, global data area or parameter data area.
Error Messages

Data area does not define any variable.

Data area does not contain DEFINE DATA statement.

No input file.

Solution Delete the data area. Then create a new data area and add at least one variable definition.
Unused local variables Check whether the variables that are defined in the source are used.
Error Messages

Unreferenced variable: %1%.

Unreferenced USING: %1%.

No input file.

Solution Remove the variable, or remove the USING definition for a data area.
Unused search fields Check whether the variables that are defined in the source are used as search fields.
Error Messages

Unreferenced search field: %1%.

No input file.

Solution The view variable is only used as a search field and can be removed from the view.
Used AIV variables Check whether the source uses application-independent variables (AIVs) that are not defined or whether they do not match a regular expression.
Error Messages

AIV variable: %1% used.

No input file.

Solution Remove the AIV variable.
TODO comment Check whether the sources contain TODO comments.
Error Messages

TODO: %1%.

Error: DDM parser %1%.

No input file.

Solution Remove the TODO comment.
FIXME comment Check whether the sources contain FIXME comments.
Error Messages

FIXME: %1%.

Error: DDM parser %1%.

No input file.

Solution Remove the FIXME comment.
NATdoc source Check the NATdoc header comments for consistency.
Error Messages

NATdoc missing.

NATdoc first sentence missing.

Error: DDM parser %1%.

No input file.

Solution Add NATdoc comments and make sure that the first sentence ends with a period (.)
NATdoc variable Check whether the source uses NATdoc field tags.
Error Messages

NATdoc field tag :out or :inout for %1% not valid for input-only field (BY VALUE).

NATdoc field tag :in, :out or :inout for %1% missing.

NATdoc field tag :redef for %1% missing.

NATdoc field tag :in, :out or :inout for redefinition %1% missing.

Error: DDM parser %1%.

No input file.

Solution Add missing field tags.
NATdoc style Check whether NATdoc header comments exist.
Error Messages

NATdoc field tag %1% missing.

NATdoc field tag parameter %1% missing.

Error: DDM parser %1%.

No input file.

Solution Add missing field tags.
Upper case translation of source Check whether all required strings have correctly been translated to upper case.
Error Messages

Source is not translated to upper case: %1%.

No input file or parser not initialized.

Solution Enable case translation in the Natural preferences or change the string to upper case manually.
Local variables shadow view Check whether a view field exists which has the same name as a variable of the Natural source.
Error Messages

Variable: %1% may shadow view field %2%.

No input file.

Solution Rename the locally defined field.
Fully qualified variables Check whether the variables in a Natural source are fully qualified. This rule applies to view fields and group fields.
Error Messages

Variable %1% not fully qualified as %2%.

No input file.

Solution Add a group or view name to fully qualify the variable.
NPath complexity Check the Npath complexity of the program.
Error Messages

NPath complexity of %1% (Highest = %2%).

NPath complexity of subroutine %3% %1% (Highest = %2%).

No input file.

Solution Split the program or reduce its complexity.
Cyclomatic complexity Check the cyclomatic complexity of the program. The cyclomatic complexity number is also known as "McCabe metric". To approximate this value, each Natural block statement increments the complexity by one. The complexity is evaluated separately for the main program and each inline subroutine.
Error Messages

Cyclomatic complexity of %1% (Highest = %2%).

Cyclomatic complexity of subroutine %3% %1% (Highest = %2%).

No input file.

Value is not in range 10 - 9223372036854775807.

Solution Split the program or reduce its complexity.
Boolean complexity Check Boolean expressions in IF and DECIDE statements of the Natural code. Count the number of the Boolean operators OR and AND.
Error Messages

Boolean expression complexity of %1% (Highest = %2%).

No input file or parser not initialized.

Value is not in range 10 - 9223372036854775807.

Solution Rewrite the program to reduce the complexity.
Function naming convention Check whether the names of functions match the naming conventions.
Error Messages

Function name does not match naming conventions '%1%'.

No input file.

Solution Rename the function.
Class naming convention Check whether the names of classes match the naming conventions.
Error Messages

Class name does not match naming conventions '%1%'.

No input file.

Solution Rename the class.
Subroutine naming convention Check whether the names of inline subroutines and external subroutines match the naming conventions.
Error Messages

Subroutine name does not match naming conventions '%1%'.

Regular expression not valid: %1%.

No input file.

Solution Rename the subroutine.

Error Check

NATstyle provides the following rules for checking error message files:

Rule Description
Error file name Check whether the names of error message files match the Natural naming conventions.
Error Messages

Name contains invalid language code.

Name does not match naming conventions.

No input file.

Solution Rename the error message file, or (even better) delete the error message file and create a new error message file.

Resource Check

NATstyle provides the following rules for checking Natural resources:

Rule Description
Resource file name Check whether Natural resources with a specific file extension match a specific naming convention (as defined with the regex property).
Error Messages

File name does not match naming conventions '%1%'.

Regular expression not valid: %1%.

No input file.

Solution Rename the resource file.

Library Check

NATstyle provides the following rules for checking Natural libraries:

Rule Description
Library directly below root folder Check whether a Natural library is located directly below the library root folder. The library root folder is used if new objects are created for this library and no folder is specified.
Error Messages

For library %1%, no library can be found directly below the library root folder.

No library or library folder found.

Solution Create a new library below the library root folder.
Duplicate libraries Check whether the project contains more than one folder with the name of a Natural library.
Error Messages

Project contains more than one library for Natural library %1%.

No library or library folder found.

Solution Make sure that only one library is created. It should be placed directly below the "Natural-Libraries" root folder.
Library folder names Check whether the library folders match the naming conventions.

The following folders are not tested: a folder with the same name as a Natural library, a folder named after a Natural object type, and the special folders with the reserved names "SRC", "ERR" and "RES".

Error Messages

Library folder %1% does not match naming conventions (%2%).

No library or library folder found.

Solution Change the name of the library folder.
Mixed object grouping Check whether a library contains group folders or the special folders with the reserved names "SRC", "ERR" and "RES". Only one type of grouping should be used.
Error Messages Library %1% contains a mix of special folders and group folders.
Solution Remove folders so that only one type of grouping is used.
Special folders Check whether a Natural library only contains the special folders with the reserved names "SRC", "ERR" and "RES". All other folders will be marked as wrong.
Error Messages

Library %1% should only contain special folders.

No library or library folder found.

Solution Remove all marked folders. Only special folders with the reserved names "SRC", "ERR" and "RES" are valid.
Group folders Check whether a Natural library only contains group folders. All other folders will be marked as wrong.
Error Messages

Library %1% should only contain group folders.

No library or library folder found.

Solution Remove all marked folders. Only group folders are valid (that is, folders which are named after a Natural object type or with the names "Resource" and "Error").
NATdoc library documentation (library.html) Check whether a Natural library contains a library comment file with the name library.html.
Error Messages

NATdoc library documentation (library.html) missing.

No library or library folder found.

Solution Add a library comment file with the name library.html to the root of the library.

DTDs Used by NATstyle

The following topics are covered below:

Structure of the Configuration File

The following DTD defines the structure of the configuration file:

<!ELEMENT naturalStyleCheck (packages?, checks+)>
<!ATTLIST naturalStyleCheck version CDATA #IMPLIED>
<!ELEMENT packages (package+)>

<!ELEMENT package  EMPTY>
<!ATTLIST package  url      CDATA #REQUIRED>

<!ELEMENT checks   (check+)>
<!ATTLIST checks   type     (source|header|parser|error
                            |resource|library) #REQUIRED>

<!ELEMENT check    (property*)>
<!ATTLIST check    class    CDATA #REQUIRED
                   name     CDATA #IMPLIED
                   severity (error|info|warning) #REQUIRED
                   disabled (true|false) #IMPLIED>

<!ELEMENT property EMPTY>
<!ATTLIST property value    CDATA #REQUIRED
                   name     CDATA #REQUIRED>

The elements of the DTD are described in the following table:

Element Description
naturalStyleCheck Top-level element. Contains the version of the used naturalStyleCheck implementation.
packages Contains one or more package definitions. Each package contains the url to a JAR file that contains user-written extensions to NATstyle.

Note:
User-written extensions to NATstyle are currently not supported.

checks Checks are categorized for specific test groups. Each of these type categories contains different tests.
check A check needs a type-specific implementation within a Java class. The implementation is identified by the class name and the category type of the checks. Each check has a severity containing the found violation. The name is a meaningful short description of the test and will be used as the name in the property pages. With the disabled flag, a check can be switched on and off.
property Each check may contain different properties. Each property has a name and a value. The range of values is defined in the implementing class.

An implementation class can be specified for more than one check. It can be used, for example, if more then one "Regular expression to each source line" check is to be performed with different settings. The following document shows part of the default configuration file:

<?xml version="1.0" encoding=" utf-8"?>
<naturalStyleCheck version="1.0">
  <checks type="source">
    <check class="CheckLineLength" name="Line length" severity="warning">
      <property name="max" value="72"/>
      <property name="exclude" value="D3"/>
    </check>
    <check class="CheckWhiteSpace" name="Whitespace" severity="info">
      <property name="noTab" value="false"/>
      <property name="exclude" value="D3T"/>
    </check>
    <check class="CheckTabs" name="Tab character" severity="info"/>
    <check class="CheckHasLineNumbers" name="Line numbers" severity="warning"/>
    <check class="CheckEmptyLine" name="Empty lines" severity="info">
      <property name="exclude" value="D3T"/>
    </check>
    <check class="CheckRegExLine" name="Regular expression to each source line"
                                  severity="warning" disabled="true">
      <property name="exclude" value=""/>
      <property name="regex" value=""/>
    </check>
    <check class="CheckRegExSource" name="Regular expression to test source"
                                    severity="warning" disabled="true">
      <property name="exclude" value=""/>
      <property name="regex" value=""/>
    </check>
    <check class="CheckNewlineAtEndOfFile" name="Newline at end of file missing"
                                           severity="info">
      <property name="exclude" value="D"/>
    </check>
  </checks>
...
</naturalStyleCheck>

For more information on NATstyle configuration files, see NATstyle in Setting the Preferences.

Structure of a NATstyle Result File

The following DTD defines the structure of the generated result files:

<!ELEMENT NATstyle (fatal*, file*)>
<!ATTLIST NATstyle  version  CDATA #REQUIRED>
<!ELEMENT fatal EMPTY>
<!ATTLIST fatal     class    CDATA #REQUIRED
                    message  CDATA #REQUIRED
                    name     CDATA #IMPLIED>
<!ELEMENT file (error*, fatal*)>
<!ATTLIST file      type     (lib|err|res|src) #REQUIRED
                    location CDATA #REQUIRED>
<!ELEMENT error EMPTY>
<!ATTLIST error     class    CDATA #REQUIRED
                    message  CDATA #REQUIRED
                    severity (error|info|warning) #REQUIRED
                    name     CDATA #IMPLIED
                    line     CDATA #IMPLIED>

The elements of the DTD are described in the following table:

Element Description
NATstyle Top-level element. Contains the version of the used NATstyle implementation.
file Each tested file is added to the result. The location of the file specifies the full path to the file. The type attribute categorizes whether the file is used as Natural source (src), Natural error message file (err), Natural resource (res) or Natural library (lib).
error If a check is violated, an error element is added. The error element specifies the class that generated this entry, a meaningful name and the severity of the error. If available, the error line will be specified. The message describes the kind of violation.
fatal In case the checks or a specific check on a file fails, a fatal entry is added. The class specifies the implementation that failed and the message contains detailed information about the failure.

The following is an example of a generated result file:

<?xml version="1.0" encoding="UTF-8"?>
<NATstyle version="1.0">

<file type="src" location="P:\SYSEXPG\Natural-Libraries\SYSEXPG\Programs\CNOTX04.NSP">
  <error severity="warning" line="11" message="Unreferenced search field: CITY."
    class="com.softwareag.naturalone.natural.natstyle.check.src.parser.CheckUnusedSearchFields"
    name="Unused Search Fields"/>
  <error severity="warning" message="NATdoc missing."
    class="com.softwareag.naturalone.natural.natstyle.check.src.parser.CheckNATdocSource" 
    name="NATdoc Source"/>
  <error severity="warning" line="20" message="Variable BONUS not fully qualified as INCOME.BONUS."
    class="com.softwareag.naturalone.natural.natstyle.check.src.parser.CheckFullQualifiedVariable"
    name="Fully qualified variables."/>
</file>

<file type="src" location="P:\SYSEXPG\Natural-Libraries\SYSEXPG\Programs\COMPRX03.NSP">
  <error severity="info" line="29" message="Not structed correctly."
    class="com.softwareag.naturalone.natural.natstyle.check.src.header.CheckStruct" name="Struct"/>
  <error severity="warning" line="10" message="Unreferenced search field: CITY."
    class="com.softwareag.naturalone.natural.natstyle.check.src.parser.CheckUnusedSearchFields"
    name="Unused Search Fields"/>
  <error severity="warning" message="NATdoc missing."
    class="com.softwareag.naturalone.natural.natstyle.check.src.parser.CheckNATdocSource" 
    name="NATdoc Source"/>
</file>

</NATstyle>