This document covers the following topics:
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.
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.
To check the Natural code
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.
Invoke the context menu and choose
.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.
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 | |
Warning | |
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.
Change the code as appropriate.
Notes:
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 command
automatically updates the existing NATstyle markers in the editors, the
decorations in the Project Explorer view, and the entries
in the Problems view.
To clear the NATstyle violations
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.
Invoke the context menu and choose
.Or:
Use the keyboard shortcut CTRL+SHIFT+D.
The following topics are covered below:
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 command prior to saving the results.
Note:
The 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.
To save the result of a NATstyle check to a file
In the Project Explorer view or in the Natural Navigator view, select the project for which you want to save the results.
Invoke the context menu and choose
.A dialog box appears, providing the file name NATstyleResult.xml as a proposal.
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.
Choose the
button to create the 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.
To load a NATstyle result file
In the Project Explorer view or in the Natural Navigator view, select the project for which you want to load the result file.
Invoke the context menu and choose
.A dialog box appears showing the root directory of the selected project.
Select the result file which has been created for this project.
Choose the
button.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:
Note: |
-libraries
library-names |
Names of the Natural libraries to be
checked. Separate the names using the semicolon (;) character. For example:
|
-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. |
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.
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 UNIX, OpenVMS 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. |
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 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. |
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. |
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. |
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. |
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. |
The following topics are covered below:
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: |
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.
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>