NaturalONE Version 8.3.7
 —  Using NaturalONE  —

Managing Natural Projects

This document covers the following topics:


Creating Natural Projects

The name of a Natural project must meet the Eclipse naming conventions.

You can create a Natural project in different ways:

Downloading an Existing Library or Object from a Natural Server

You can download entire libraries from a Natural server. A library is either placed in a newly created project or in an existing project, depending on the command that you use.

It is also possible to download only single objects of a library. These objects are then downloaded into a library which has the same name as the library on the Natural server (into a new or existing project, depending on the command that you use).

Only the sources are downloaded from the Natural server. Since a Natural application can only be executed (and debugged) directly in the Natural server environment, the generated programs (which are also called "GPs" or "cataloged Natural objects") remain on the server.

When you download into a new project, a number of required Natural profile parameter settings is also downloaded to the project. These settings are stored as the default settings in the .natural file. See also Changing the Project Properties.

Notes:

  1. In a UNIX, OpenVMS or Windows environment, it is possible to download an inactive library into a new project. However, when you upload the content of such a library later, it is always uploaded to the active system file and not to the inactive library from which it was downloaded.
  2. When the option Console output is enabled on the Runtime Execution page of the Natural preferences, information about the download process is shown in the Console view.

Start of instruction setTo download a library or object

  1. In the Natural Server view, map the required Natural server as described in the section Mapping a Natural Environment.

  2. Expand the node for the mapped Natural server.

  3. Expand the node for the required system file (for example, User Libraries).

  4. Select one or more of the following: a library, a node for an object type (for example, Program) or a single object.

    Tip:
    Type the first letters of the library name to select the first library that starts with these letters. When you type all letters of a name quickly, without a pause, you can immediately select the corresponding library.

    If you want to download several single objects at a time, open the library node(s), then open the node(s) for the object type(s), and then select the object(s).

    If you want to download, for example, all subprograms of a library, select the corresponding node for this object type.

    Notes:

    1. When Natural Security is not active on the Natural server, you can also select the node for a system file if you want to download all libraries contained in this system file at the same time.
    2. When Natural Security is active on the Natural server, it is only possible to download objects for which editing and listing is allowed. Since the access to specific libraries may be restricted, it is not possible to download all libraries of a system file at the same time by selecting the node for the system file. In this case, you have to select the nodes for all libraries that you are allowed to use. Moreover, if editing or listing is not allowed for one object type in a library, it is not possible to download the complete library. In this case, you have to select the group nodes for the types which you are allowed to use.
    3. When Natural Security is active on the Natural server, "copy from library" must be enabled in the SYSMAIN utility profile of Natural Security in order to download objects. See also Protecting the Natural Development Environment in Eclipse in the Natural Security documentation, which is part of the Natural documentation.
  5. Invoke the context menu and choose either Add to New Project or Add to Existing Project.

    With Add to New Project, a new Natural project is created and the project properties are set. The properties apply to the Natural server environment from which the objects are downloaded.

    With Add to Existing Project, the project properties of the existing project are not modified even if they do not apply to the Natural server environment from which the objects are downloaded.

  6. When you have chosen to download to a new project, a dialog box appears and you can specify a project name. The name of the (first) selected node is offered as the default name. When a project with this name already exists in your workspace, the dialog box informs you and you have to specify a project name that is not yet used.

    Add to new project

    If you want to create the "Natural-Libraries" root folder in the new project, make sure that the option Create the library root folder is selected. This option is only shown when root folder support has been enabled in the Natural preferences. For further information, see Natural > Project in Setting the Preferences.

    If you want to group the downloaded Natural objects into separate folders within the new project, according to their object types, make sure that the option Group new objects by object type is selected. For further information, see Group Folders.

    Or:
    When you have chosen to download into an existing project, a dialog box appears in which you have to select the project.

    Add to existing project

  7. Choose the OK button to continue.

    A dialog box is shown indicating the download progress. When you download a small number of objects, this dialog box is only briefly shown. However, when you download a large number of objects, you can choose to download the objects in the background so that you are able to continue working. A progress indicator is shown at the right bottom of the Eclipse window.

    The downloaded libraries or objects are shown in the Navigator view and in the Natural Navigator view.

Start of instruction setTo download a library or object to an existing project using drag-and-drop

  1. In the Natural Server view, select one or more libraries or objects as described above.

  2. Drag the selected nodes onto an existing project node in the Navigator view or in the Natural Navigator view.

Creating a New Project Using a Wizard

Instead of downloading a library as a project from a Natural server, you can also create a Natural project manually.

You only have to provide a project name. The project wizard creates a Natural project structure that contains the .natural file with the default settings of the project properties. All other project information may be entered at a later point in time. See also Changing the Project Properties.

Start of instruction setTo create a project using a wizard

  1. From the File menu, choose New > Natural Project.

    Or:
    In the Navigator view or in the Natural Navigator view, invoke the context menu and choose New > Natural Project.

    The following dialog box appears.

    Create Natural project

  2. Specify the following information:

    Option Description
    Project A unique name for the new project.
    Create the library root folder If you want to create the "Natural-Libraries" root folder in the new project, make sure that this option is selected. This option is only shown when root folder support has been enabled in the Natural preferences. For further information, see Natural > Project in Setting the Preferences.
    Group new objects by object type If you want to group the Natural objects in this project into separate folders, according to their object types, make sure that this option is selected. For further information, see Group Folders.
  3. Optional. Choose the Next button repeatedly if you want to change the default settings.

    On the next pages of the dialog box, you can then specify the following information:

    See Changing the Project Properties for further information.

    Note:
    Many default settings (such as the parser settings, project encoding and character assignments) are defined in the Natural preferences. For further information, see Setting the Preferences.

  4. Choose the Finish button.

Importing a Project from a Version Control System

You use the standard Eclipse functionality to import a Natural project from a version control system.

Importing an Existing Natural Project into the Workspace

You use the standard Eclipse functionality to import a Natural project from a different workspace into the current workspace.

When you import a Natural project into your workspace or check it out from the repository of a version control system, the user ID on the Runtime page of the project properties may differ from your current user ID. On import or checkout, the user ID is always set to the default user ID and the password is set to blank. The default user ID is either the ID that you have used to log on to your operating system or - if already entered in the project wizard - the user ID that is persistently stored in Eclipse. It is your responsibility to enter the appropriate user ID and password for the defined server connection.

Top of page

Types of Natural Projects

There are different types of Natural projects with different characteristics:

Top of page

Changing the Project Properties

The Natural project properties are made up of information and profile parameters that are important for the development of a Natural application.

When a project is created using the wizard, the project properties are preset and can be changed in the wizard. The properties are then written as the default settings into the .natural file. For some properties, default values can be defined in the Natural preferences.

When a project is created by downloading a library or object from a Natural server into a new project, the properties from the server are written as the default settings into the .natural file.

The settings stored in the .natural file are the so-called "default settings". They are important when you work with a version control system. When you change any settings in the project properties and just choose the OK or Apply button, these changes are stored persistently under the control of Eclipse, but they are not automatically written to the .natural file. The content of the .natural file is only changed when you do this explicitly by also choosing the Store new Defaults button (see the description of the Natural property page below).

When you change the settings for a project, your changes are uploaded to the appropriate Natural environment the next time you update the Natural environment with an object in this project. The uploaded changes include the default settings in the .natural file, plus your user settings which are stored persistently under the control of Eclipse. In this case, the user settings always superimpose the default settings.

Start of instruction setTo change the project properties

  1. Select the project in the Navigator view or in the Natural Navigator view.

  2. Invoke the context menu and choose Properties.

  3. In the tree of the resulting dialog box, expand the Natural node.

    Project properties

    Different pages are provided for setting different types of properties.

    Notes:

    1. The Debug Attach Settings node is only shown when a debug attach server has been enabled in the Natural preferences.
    2. The Steplibs node is only shown when the project pertains to a server environment which is not protected by Natural Security.
  4. Select one of the property pages in the tree and set the required options as described in the topics below.

  5. Choose the OK button to save your changes and to close the dialog box.

The following property pages are available for Natural projects:

Natural

This property page is shown when you select the Natural node.

Natural

One of the following messages can be shown next to Security:

Message Meaning
Environment is secured This environment is protected by Natural Security.
No secured environment This environment is not protected by Natural Security.

Note:
The environment is defined on the Runtime page.

You can modify the following settings:

Group new objects by object type

If you want to group the Natural objects in this project into separate folders, according to their object types, make sure that this option is selected. For further information, see Group Folders.

Support old internal data area format

This option applies to the internal format of data areas in a Natural for Windows, UNIX and OpenVMS environment.

With Natural Version 6.1 for Windows and UNIX and Natural Version 6.3 for OpenVMS, a new internal format was introduced for data areas which supports, for example, dynamic and large variables.

When data areas are uploaded to the Natural environment, the new internal data area format is used by default. It is strongly recommended that you keep this default (that is, do not select this check box).

Data areas with the new format are not downward-compatible. Therefore, it is not possible to use them with Version 5.1 and below. Select this check box only, if you require data areas in the old format that are to be used with Natural Version 5.1 or below.

Note:
The default setting for this option can be changed in the Natural preferences. See Natural > Options in Setting the Preferences.

Delete error messages on server before upload

When selected, all error messages are deleted in the appropriate library on the server before the error messages from the project are uploaded.

When not selected (default), all error messages are uploaded to the server. Any error messages which are no longer available in the project are not deleted on the server. This may cause inconsistencies.

See also Creating Application-Specific Messages.

Note:
The default setting for this option can be changed in the Natural preferences. See Natural > Options in Setting the Preferences.

Store new Defaults / Restore from Defaults

The .natural file contains the default settings of the Natural project properties. The following command buttons are available:

Builder

This property page allows you to define a project-specific build sequence. This sequence is used by the Build Natural Project command to upload and stow objects in the Natural environment. If required, you can use the up-arrow and down-arrow buttons to change the build sequence for the current project.

The default sequence for new projects is defined in the Natural preferences. See also Natural > Build Sequence in Setting the Preferences.

Builder

Debug Attach Settings

This property page (and its corresponding link in the tree) is only shown when a debug attach server has been enabled in the Natural preferences. See Debug Attach Settings in Setting the Preferences.

The debug attach server uses a client ID to manage its attach records. A new unique client ID is generated for each project each time you start NaturalONE. This client ID is shown on this property page.

Debug attach settings

Generation type

It is recommended that you do not change the generation type. You should leave it with unique.

However, if you want to debug an external Natural application or, if necessary, for testing purposes, you can define a custom client ID. You should only do this if you want to start a particular Natural runtime server manually. In this case, select custom from the drop-down list box and specify a client ID in the text box.

Editor

This property page allows you to change editor settings.

Editor

You can modify the following Natural profile parameter on this page:

Option Corresponding Natural Profile Parameter
Renumber line numbers in constants RNCONST

For detailed information on this profile parameter, see the Natural documentation for the appropriate platform.

If Renumber line numbers in constants is enabled, the line number references in constants are automatically renumbered while you are editing a source (see also Line Numbers).

Note:
The setting of the above option is only taken into account when a source is being opened. If you change the setting while a source is already open, you have to close and reopen the source so that the changed setting becomes active.

The following applies when you are downloading a source from the server:

When you upload a source from a project in which the Renumber line numbers in constants is enabled, all line number references in constants are automatically renumbered during the upload (irrespective of the RNCONST setting on the server).

Logging

This property page allows you to write the history of the Natural builder to a log file.

Logging

Write history of Natural builder to log file

When this check box is enabled, all other options on this page are also enabled and information is written to a log file each time you change, delete or add a source. The log file is created as soon as the first action occurs which requires an update in the server environment. These are the actions for which flags will be shown in the label decorations when your projects are not automatically built (see also Flags in a Label Decoration).

New history information is appended to the log file. As long as you do not enable or disable the option Store only one log entry for each Natural object (see below), the content of the log file is not deleted.

The following is an example of a log file:

[2012/03/29][10:25:14.817],MYLIB-A,COPY1,C,SAVE 
[2012/03/29][10:25:14.817],MYLIB-A,PROG1,P,CAT 
[2012/03/29][10:25:27.330],MYLIB-B,LDA1,L,STOW 
[2012/03/29][10:25:27.330],MYLIB-A,PROG1,P,CAT 
[2012/03/29][10:25:27.330],MYLIB-A,PROG3,P,CAT 
[2012/03/29][10:25:35.641],MYLIB-A,PROG1,P,STOW 
[2012/03/29][10:25:40.072],MYLIB-B,HLPRT2,H,STOW 
[2012/03/29][10:25:40.072],MYLIB-A,PROG3,P,STOW 
[2012/03/29][10:25:46.945],MYLIB-B,SUBP1,N,SCRATCH

For each operation, the log file provides the following information, separated by commas:

Location of log file with history of Natural builder

Using the following option buttons, you can define where the log file is to be stored:

When a log file exists at the selected location (either in the Natural log folder or in the project), the Delete Log File button is enabled. You can use this button to delete the log file at the selected location. When you choose this button, a dialog appears, asking whether you want to delete the log file. It is not possible to undo the deletion.

Store only one log entry for each Natural object

Caution:
When you change the setting of this option and if a log file exists at the selected location, a dialog box appears, informing you that the current contents of the log file will be deleted. You are asked whether you want to continue.

When enabled, each Natural object is listed only once in the log file. The log file is written in the same format as described above. However, its sort sequence is different. The entries are no longer sorted according to the timestamp (that is, new information is not always appended at the end of the file). Instead, the following sort sequence is used: library name, object type, object name. This is similar to the sort sequence which is used by CATALL.

The following is an example of such a log file:

[2012/04/05][10:26:52.633],MY_LIB1,SUBPGM2,N,STOW
[2012/04/05][10:27:03.345],MY_LIB1,PGM1,P,STOW
[2012/04/05][10:26:56.954],MY_LIB1,PGM2,P,STOW
[2012/04/05][10:26:48.930],MY_LIB2,PGM2,P,STOW
[2012/04/05][10:26:58.954],MY_STEP1,CPYCDE1,C,SAVE
[2012/04/05][10:26:50.930],MY_STEP1,LDA1,L,STOW
[2012/04/05][10:27:07.126],MY_STEP1,SUBROUT1,S,STOW
[2012/04/05][10:27:03.345],MY_STEP2,CPYCDE2,C,SAVE

The content of the log file can be seen as a compilation of all actions which are needed to deploy updates. Each time an action is performed on an object, either a new entry is created in the log file or the stored entry is updated.

For example, when the log file already contains a SAVE entry for an object and a CAT entry is later added for the same object, both log entries are automatically combined into a single STOW entry (which logically contains the SAVE and CAT operations).

Or, when a STOW operation occurs several times for the same object, only the latest STOW operation (with the corresponding timestamp) is shown in the log file.

Parser

This property page provides the following tabs:

Note:
If Natural Security is active, the parser settings can also be defined in the properties of a library. In this case, the library properties override the project properties. See Changing the Library Properties.

Options

Options

On this tab, you can modify the following Natural profile parameters:

Option Corresponding Natural Profile Parameter
Interpretation of database field short name DBSHORT
Length/format specification FS
Keyword checking KCHECK
Parameter checking for CALLNAT statements PCHECK
Structured mode SM

For detailed information on these profile parameters, see the Natural documentation for the appropriate platform.

The Parser mode drop-down list box, which is also provided on this tab, allows you to define the platform for which the Natural language syntax is to be checked. You can select one of the following options:

Parameters

Parameters

On this tab, you can modify the following Natural profile parameters:

Option Corresponding Natural Profile Parameter
Line size LS
Page size PS
Spacing factor SF
Maximum year MAXYEAR

For detailed information on these profile parameters, see the Natural documentation for the appropriate platform.

Regional Settings

This property page provides the following tabs:

Character Assignments

Character assignments

On this tab, you can modify the following Natural profile parameters:

Option Corresponding Natural Profile Parameter
Set terminal command character CF
Terminal command character
Decimal character DC
Input assign character IA
Input delimiter character ID
Dynamic thousands separator THSEP
Thousands separator character THSEPCH

For detailed information on these profile parameters, see the Natural documentation for the appropriate platform.

Options

Options

On this tab, you can modify the following Natural profile parameters:

Option Corresponding Natural Profile Parameter
Date representation DTFORM
User language ULANG

For detailed information on these profile parameters, see the Natural documentation for the appropriate platform.

The Project encoding drop-down list box, which is also provided on this tab, provides for selection all code pages that are valid for the Natural environment (Natural server or local Natural runtime) which is currently defined on the Runtime page of the project properties. When set to blank, a code page is not defined for the project. When the Natural environment is updated, the default code page defined in this environment will be used. New sources will be created using the code page that is defined for the project.

Runtime

This property page shows the mapping information for the Natural environment (Natural server or local Natural runtime) to which this project belongs. This information is used, for example, when you execute an object.

Runtime

For information on the Natural server connection and startup options on this property page, see Mapping a Natural Environment.

The Use local Natural runtime option button is only visible when the local Natural runtime has been installed. When the local Natural runtime is selected, host name and port number are automatically provided and the corresponding text boxes appear gray.

If you want, you can assign your project to a different Natural environment. If you do so, it is likely that the security status of the project no longer matches the security status of the new Natural environment. Therefore, a dialog box appears which allows you to change or keep the current security status:

You can modify the following Natural profile parameter on this page:

Option Corresponding Natural Profile Parameter
Processing loop limit number LT

For detailed information on this profile parameter, see the Natural documentation for the appropriate platform.

Note:
If Natural Security is active, this profile parameter can also be set in the properties of a library. In this case, the library properties override the project properties. See Changing the Library Properties.

Steplibs

This page is only available when the project pertains to a server environment which is not protected by Natural Security. If the server environment is protected by Natural Security, you can only define steplibs for a library; see Changing the Library Properties.

On this property page, you can define steplibs and the development mode in which the build is to be performed on the Natural server.

Steplibs

Development mode

When the Natural server is updated (see Updating the Objects in the Natural Environment), all new and changed sources of a project are uploaded to the server and are stowed there. The development mode that you define determines the target libraries on the server. Two modes are available:

Steplibs

A steplib is a Natural user library or system library that is concatenated with the current user or system library. This avoids redundant storage of identical objects and helps organize applications. Natural searches in a steplib when an object is not found in the current library. The standard steplibs are the libraries SYSTEM in the system files FUSER and FNAT. The additional steplibs that you define on this property page are searched for an object before the standard steplibs.

Top of page

Quickly Viewing the Properties

The Properties view shows enhanced, Natural-specific information for a node which is currently selected in the Natural Navigator view. Such information is not shown when working with the standard Navigator view of Eclipse.

The information that is shown in the Properties view depends on the type of node that is currently selected in the Natural Navigator view. It is very similar to the information that is shown when using the Properties command. But it also provides additional information such as the number of objects in a node.

When accessed via the Natural Navigator view, the Properties view provides different tabs. You can immediately see the settings for a selected project, library or object. For example, you can see the following information at a glance:

In addition, you can quickly compare the settings for two different nodes. For example, when you display the Parser tab for one library and then select a different library in the tree, the Parser tab is also shown for the newly selected library.

Top of page

Enabling a Project for NaturalONE

You can use any kind of project (for example, a Java project) with NaturalONE. However, you have to enable it first.

Natural projects which have been created with Natural for Eclipse cannot be used immediately with NaturalONE. If you have imported such a project into NaturalONE or if you have checked it out from your version control system, you first have to enable it for NaturalONE. A Natural project which has not yet been enabled for NaturalONE is indicated by the following icon: Icon.

Start of instruction setTo enable a project for NaturalONE

  1. In the Navigator view or in the Natural Navigator view, select the project that you want to enable.

  2. Invoke the context menu and choose Enable for NaturalONE.

    Note:
    This command is only visible when you select a project which has not been created with NaturalONE.

Top of page