General Information

This document covers the following topics:


Types of Natural Editors

The following table indicates which type of editor is used for a specific object type:

Icon Object Type Extension Editor
Icon Program NSP Source editor
Icon Class NS4
Icon Subprogram NSN
Icon Subroutine NSS
Icon Function NS7
Icon Copycode NSC
Icon Helproutine NSH
Icon Text NST
Icon Dialog NS3
Icon Adapter NS8
Icon Global data area (GDA) NSG
Icon Local data area (LDA) NSL
Icon Parameter data area (PDA) NSA
Icon Map NSM Map editor
Icon Data definition module (DDM) NSD DDM editor

The above icons are used for the sources in the Navigator view, in the Natural Navigator view and in the Dependencies view.

They are also used in the Natural Server view. On a Natural server, however, Natural objects can consist of the source, the generated object (for example, a generated program) or both. The difference is reflected in the icon. Therefore, in the Natural Server view, the above icons can be shown as follows (example for a program):

Icon Description
Icon Without a green ball and not gray: only the source of the object is available.
Icon With a green ball and not gray: source and generated object are available.
Icon With a green ball and gray: only a generated object is available and no source.

Invoking a Natural Editor

A Natural editor is invoked when you open an existing Natural object or when you create a new Natural object.

You can open an existing object either from a Natural project in the Eclipse workspace (Navigator view or Natural Navigator view) or directly on the Natural server (Natural Server view). For further information, see the following sections:

You can create a new object in a Natural project in the Eclipse workspace (Navigator view or Natural Navigator view). For further information, see the following section:

Editing Data Areas

NaturalONE makes use of the Natural source editor for data area editing. The wizard for creating new objects generates a skeleton for the DEFINE DATA statement. Within this skeleton, you are able to write the variable definition. Editing of the data area is well supported through the Natural parser.

Data areas that are downloaded from a Natural server are automatically normalized. This means that the internal data area format is converted into a DEFINE DATA statement. The benefit is that the data area can be defined quickly and that versioning of the data area source is possible. When you use the Build Natural Project or Upload command, the normalization is reversed: the internal data format of the Natural server is then generated from the DEFINE DATA statement.

Viewing Dialogs, Classes and Adapters

NaturalONE does not support dialogs and classes (see also Are all Natural object types supported? in Frequently Asked Questions). However, it is possible to view (and even edit, although this is not recommended) the source code of such an object using the source editor. With NaturalONE, it is not possible to create these objects from scratch. The same is true for adapters which are generated by Natural for Ajax.

Note:
When certain prerequisites are fulfilled, Natural Studio's dialog editor can be accessed directly from NaturalONE. See Working with Dialogs.

Problems in Your Natural Sources

When a syntax error is detected in a project after an object has been saved, or when a compiler problem is detected in a project during a server update (that is, when a source could not be cataloged on the server), this is indicated in the Navigator view or in the Natural Navigator view.

Note:
Syntax parsing of dependent objects can be enabled and disabled. For further information, see Parsing Dependent Objects.

In the case of a problem, the icon of a project contains a corresponding decoration. The subnodes containing the problem also contain the decoration in their icons.

Error

Note:
The label decorations for the server problems are controlled by the preferences under General > Appearance > Label Decorations. If you do not want to have these label decorations, just go to the above mentioned preference page and deselect Natural Compiler Problems.

The Problems view shows the corresponding error message(s). When you double-click an error in the Problems view (or when you select the error and then choose Go to from the context menu), the corresponding line in the editor is selected.

Error

Two types of errors are shown in the Problems view. Errors starting with "NAT" are Natural system error messages which are issued by Natural on the server. Errors starting with "E_" are issued by the local NaturalONE parser when an error is found in the editor.

When you select an error in the Problems view, the error message is also shown at the bottom left of the Eclipse window.

In the Natural preferences, you can specify whether information is to be shown in the Problems view. See Source Editor in Setting the Preferences.

Parsing Dependent Objects

When syntax parsing of dependant objects is enabled in the Natural preferences (see Natural > Builder in Setting the Preferences), any dependent objects containing syntax errors are shown with an error marker in the Navigator view or in the Natural Navigator view. In addition, a corresponding error message is shown in the Problems view.

A dependent object is, for example, a program which uses the fields from a data area. If the data area is changed, this change must also be considered in the dependent program.

In the Natural preferences, you can also specify that syntax parsing is to be stopped after the first error (see Natural > Builder in Setting the Preferences).

Depending on your settings, syntax parsing is either done automatically or can be started manually. This is explained in the topics below:

Automatic Parsing

When automatic parsing is enabled, all dependent objects are automatically parsed after a Natural source has been saved.

Automatic parsing can be enabled and disabled using the Parse Syntax Automatically command or by setting the corresponding option in the Natural preferences (see Natural > Builder in Setting the Preferences). When you choose the Parse Syntax Automatically command, the setting in the preferences is adapted accordingly, and vice versa.

When automatic parsing is enabled, a checkmark is shown next to the Parse Syntax Automatically command.

Start of instruction setTo enable or disable automatic parsing of dependent objects

  • From the Project menu, choose Parse Syntax Automatically.

Manual Parsing

When automatic parsing is disabled, the Parse All command is enabled and can be used to invoke the parser manually. All dependent objects which need parsing since you enabled syntax parsing are then considered by the parser.

When you correct and save your sources, the error markers in the Navigator view or in the Natural Navigator view and the entries in the Problems view are not automatically removed. To remove them, you have to invoke the Parse All command once more (or you have to switch on automatic parsing).

Start of instruction setTo parse dependent objects manually

  • From the Project menu, choose Parse All.

    Or:
    Press CTRL+ALT+P.

Unicode and Code Page Support

When a source is downloaded from a Natural server into the Eclipse workspace, the source is always converted from the server encoding to the Eclipse text file encoding UTF-8.

The server encoding of the source is stored in the source header (for further information on the source header, see below).

Caution:
When you edit a source in the Eclipse workspace and this source has UTF-8 encoding, you can enter any Unicode characters, however, only characters which are contained in the server encoding can be uploaded to the server.

In the Navigator view or in the Natural Navigator view, you can change the server encoding of the source in the Properties dialog box of the source. The supported ICU encodings depend on the Natural server. See Changing the Object Properties.

When a source is transferred back to a Natural server, it is converted to the server encoding that is defined in the Properties dialog box of the source. When the source contains "unsupported" characters, it cannot be saved on the Natural server and the server returns an error.

Note:
The SRETAIN profile parameter (set on the Natural server) is not evaluated when uploading a source to a Natural server. You have to define a suitable project encoding in the Natural project properties or a suitable server encoding in the object properties of the individual Natural objects. For example, if you leave the text box for the project encoding blank in the project properties, a code page will not be assigned to all newly created Natural objects. This is also true for a temporary project which is created when you edit a source in the Natural Server view.

In the Natural Server view (on UNIX, Windows and OpenVMS servers only), you can also change the encoding of a Natural object in the Properties dialog box (on the Object Details page). Changing the encoding of an object means that the encoding information which is stored on the server is changed; it does not mean that the content of the object is converted in any way.

For more information, see Unicode and Code Page Support in the Natural documentation for the appropriate platform.

Bidirectional Language Support

Some languages, for example Arabic and Hebrew, are written from right-to-left (RTL), whereas the majority of the languages, for example English and German, are written from left-to-right (LTR). Text which contains both left-to-right and right-to-left characters is called bidirectional text.

In addition to the bidirectional language support of the Eclipse workbench (see the Eclipse online help for further information), NaturalONE offers special bidirectional support which is described in the topics below:

RTL Visual Order View

The RTL Visual Order view is used to support applications that have been originally written for terminals which support inverse (right-to-left) print mode, but no bidirectional data. These applications create the display order of bidirectional data in the application code, that is, the application data is stored in visual order.

Note:
This view is not shown by default when you open the NaturalONE perspective. For information on how to display it, see Showing a View of the NaturalONE Perspective.

RTL Visual Order view

The RTL Visual Order view can be used in the following cases:

The selected line in the active editor (either in the source editor or on the Source page of the map editor) is converted from visual to logical format and is displayed in right-to-left screen direction (first text box in the view) and left-to-right screen direction (second text box in the view).

If you want to change the currently selected line in the active editor, you can do this in the RTL Visual Order view. Every change is immediately reflected in the editor.

Visual Order Option

When the Visual order option is selected in the Natural preferences (see Regional Settings > RTL Languages in Setting the Preferences), the application data (that is, Natural sources and data from databases) is assumed to be in visual order. In this case, several editors and tools convert the data from visual order to logical order before displaying the data. When the data is saved, it is converted back to visual order.

Map Editor and PM=I

The settings for bidirectional language support are defined in the Natural preferences. See Map Editor in Setting the Preferences.

Inverse print mode is supported for maps and data fields. The corresponding parameter (PM=I) can be set in the Properties view. See Changing the Properties for the Map in the description of the map editor.

Arabic Shaping

Important:
With the current version of NaturalONE, support for Arabic shaping is provided as a preview version. There will be no support for this preview version. Any feedback from our customers on this new feature is greatly appreciated. Since support for Arabic shaping is still under development, a later version of NaturalONE may include substantial changes to this type of support.

In Arabic text, all characters of a string are normally connected with each other. For this reason, Arabic characters have up to 4 presentation forms: the isolated, the final, the initial and the medial form. The form that will be used depends on the position of the character in the string. For example, the Arabic character "MEEM" has the following forms in Unicode:

U+0645 Arabic letter ARABIC LETTER MEEM
U+FEE1 Arabic letter ARABIC LETTER MEEM ISOLATED FORM
U+FEE2 Arabic letter ARABIC LETTER MEEM FINAL FORM
U+FEE3 Arabic letter ARABIC LETTER MEEM INITIAL FORM
U+FEE4 Arabic letter ARABIC LETTER MEEM MEDIAL FORM

Moreover, some characters are combined to a new form if they appear consecutively in a string. This is called a "ligature". For example, the characters

U+0644 Arabic letter ARABIC LETTER LAM
U+0627 Arabic letter ARABIC LETTER ALEF

have the following combined form:

U+FEFB Arabic letter ARABIC LIGATURE LAM WITH ALEF ISOLATED FORM

Unicode strings should include only the Arabic characters in the Arabic block (U+0600 through U+06FF) or the Arabic Supplement block (U+0750 through U+077F); it is not recommended to use the presentation forms in regular Arabic text. It is up to the user interface to display the correct shapes of the characters. However, applications which have been originally written on simple terminals often use Arabic presentation forms in the strings.

If data containing characters from the Arabic presentation forms has to be handled in the Eclipse context, it is necessary to unshape the Arabic characters for getting full bidirectional support from Eclipse. "Unshape" means that every Arabic presentation form character is converted to its base character. For example, U+FEE2 (ARABIC LETTER MEEM FINAL FORM) is converted to U+0645 (ARABIC LETTER MEEM).

When the data is transferred back to the original server, it is necessary to shape the Arabic strings again for getting full bidirectional support on the server platform. "Shape" means that every Arabic base character is converted to the appropriate Arabic presentation form. For example, if U+0645 (ARABIC LETTER MEEM) is used as the last character of a string, it is converted to U+FEE2 (ARABIC LETTER MEEM FINAL FORM).

NaturalONE supports Arabic shaping for the mainframe code page IBM420 during source transfer. Using the Natural preferences for Arabic shaping (see Regional Settings > RTL Languages in Setting the Preferences), Arabic shaping conversion can be controlled. The unshape operation is performed when sources are added to a Natural project and the shape operation is performed when sources are uploaded to a server.

Notes:

  1. It is not guaranteed that a source will be absolutely the same as the original source after performing an unshape/shape operation. The shape operation will always use ligature forms if possible, even if the original source contains the single character forms. Moreover, if the original source contains an "improper" shape (for example, a final form where an initial form is expected), the shape operation will not restore the original character.
  2. Sources which contain Arabic strings both in visual left-to-right (LTR) order and in logical order cannot be handled with NaturalONE. NaturalONE assumes that all strings in a source are stored in the same order.
  3. Arabic shaping is currently only supported for the EBCDIC code page IBM420.

Source Header

A source header is used to maintain some source properties (such as programming mode or code page).

The source header is part of a Natural source. It is removed when the source is transferred to the Natural server and is reinserted when the source is read from the server into the Eclipse workspace. Since the header belongs to the source, it remains in the source when it is stored in the repository of your version control system.

When using a Natural editor in Eclipse, the source header is protected. In this case, it cannot be modified or deleted. The background color for the protected lines which make up the source header can be changed in the Natural preferences. See Syntax Coloring in Setting the Preferences.

Caution:
When using a non-Natural editor, do not modify or delete the source header. This may result in compile errors or properties which can no longer be assigned correctly.

Line Numbers

By default, Eclipse has no line number information associated with a source. Line numbers make it almost impossible to version sources in a version control system: each new or removed line would result in a renumbering of the subsequent lines and these lines would be marked as changed. Therefore, NaturalONE strips off the Natural line numbers from the source.

However, it is possible to switch on the display of the Eclipse line numbers (Preferences > General > Editors > Text Editors > Show line numbers). This may be especially useful in the case of an error because the parser indicates the error position by its line number. This may also be useful when executing a Natural application: in the case of an error, the Natural runtime uses the line number to inform the user about the error position.

Eclipse uses an increment of 1 for line numbering. When Natural objects are downloaded to the Eclipse workspace, all line number references in the source code are renumbered accordingly. When the objects are uploaded to the Natural server, the line number references are all changed back to the original increment.

The following patterns are recognized as being valid line number references (where nnnn is a four-digit number):

(nnnn)
(nnnn/
(nnnn,

The source editor supports the line number references.

Caution:
If the Natural sources are modified with an editor other than the source editor, line number references may be destroyed.

By default, line number references in constants are not renumbered when you are editing a source. If they are to be renumbered while editing, you have to enable the Renumber line numbers in constants option in the project properties. See Editor in Changing the Project Properties. However, when you are downloading a source using the Add to New Project or Add to Existing Project command from a server where RNCONST is set to ON, the line number references in constants are always renumbered.

During the download, it is possible to replace the line number references with labels. This can be enabled in the Natural preferences. See Natural > Options in Setting the Preferences.

Important:
When the above mentioned option is set in the Natural preferences, all valid line numbers (as described above) will be replaced with labels. It will not be checked whether the result is valid Natural syntax. Therefore, it is up to you to check the result of the replacement.