Managing Libraries in a Natural Project

This document covers the following topics:


Libraries in a Natural Project

Each Natural project can contain one or more Natural libraries. A Natural library is indicated by a green-colored folder icon: Icon.

Other than on the Natural server, a Natural library in the Eclipse workspace contains only the sources. Generated programs (which are also called "GPs" or "cataloged Natural objects") are not stored in the Eclipse workspace. These are executed or debugged directly in the appropriate Natural environment.

In the Eclipse workspace, it is possible to store your Natural objects in arbitrary folder structures. This enables you to organize your objects in a more logical way than with the standard library structure that is mandatory on the Natural server. For example, you can group your objects according to the different tasks that are covered by your application.

Notes:

  1. Keep in mind that the Navigator view shows the objects as they are physically stored in the file system, whereas the Natural Navigator view allows you to view the objects in a logical way.
  2. For an overview of the icons and file extensions that are used for the different types of objects in the Navigator view or in the Natural Navigator view, see Types of Natural Editors.

On the Natural server, the Natural library name and the objects in a library must meet the Natural naming conventions (see the Natural documentation for the appropriate platform for further information). However, in the Eclipse workspace, it is possible to use alternative folder and file names for the libraries and objects.

More detailed information is provided in the topics below:

Library Root Folder

A Natural project may contain a library root folder which has the fixed name "Natural-Libraries".

Library root folder

Library root folders can be created when the Root folder support option is activated in the Natural preferences (see Natural > Project in Setting the Preferences). When you create a new Natural project (either by using the wizard or by downloading objects into a new project), you can then define whether the library root folder is to be created, or not. To do so, you simply have to make sure that the Create the library root folder option is activated. The state of this option is stored and reused the next time you create a new project.

When an existing project does not yet contain a library root folder, you can also create the library root folder by adding a "normal" folder (File > New > Other > General > Folder) in a Natural project and naming this folder "Natural-Libraries". With this name, the folder is considered to belong to Natural and its icon is shown with a green color. Next, you have to move all existing libraries which are still located outside this new library root folder into this new library root folder.

When a project contains the library root folder "Natural-Libraries", any libraries that are located outside this root folder are ignored when the project is built. When a library is located outside the library root folder, its icon is shown with the standard color for folders, which is yellow.

When a project does not contain a "Natural-Libraries" folder, all libraries are stored directly below the project node, and they are considered when the project is built.

Special Folders in a Library

A Natural library may contain the special folders SRC, ERR and RES.

Special folders

  • SRC - Source Folder
    The source folder has the reserved name "SRC". It contains Natural sources (programs, maps, DDMs, etc.).

    Note:
    DDMs in mainframe environments have only long names. When downloading DDMs, the long names are automatically mapped to short names, if necessary.

  • ERR - Error Message Folder
    The error message folder has the reserved name "ERR". It contains application-specific messages. See also Creating Application-Specific Messages.

  • RES - Resource Folder
    The resource folder has the reserved name "RES". It contains resources in the Natural sense of the term, that is, non-Natural files (such as images or HTML files) that are used in a Natural application.

    Resources which belong to a Natural project can be altered using standard Windows or Linux tools, if available.

As long as these folders are stored within a Natural library, they cannot be renamed. However, when you move such a folder outside the library, it can be renamed as desired and can be used as a library of its own.

It is not mandatory to use the above mentioned folders. You can omit them altogether. By default, objects with the file extension .NS* are handled as Natural sources, and objects which adhere to the naming convention for Natural error messages are handled as error messages. All other items are considered to be resources, in the Natural sense of the term.

Exception: If Natural sources or error messages are to be handled as resources, you have to create a subfolder in the library with the reserved name "RES" and move the objects into this subfolder.

Library Folders

A library folder is a folder that is assigned to a specific Natural library. For example, you can have multiple library folders for one and the same Natural library, where each library folder just contains the objects which pertain to a specific part of the application. When the "Natural-Libraries" root folder exists, this works only when the library folders are contained in this root folder.

A library folder is indicated by a green- and yellow-colored folder icon: Icon.

Library folders

Other than the library name which must adhere to the Natural naming conventions (for example, it may only be up to 8 characters long and must not contain lowercase characters), the name of a library folder may be up to 255 characters long. This can be any combination of uppercase and lowercase, but has to follow the rules of the underlying file system (Windows or Linux).

If you want to create a library and a library folder at the same time, you can do this as described in the section Creating Libraries.

You can also create a library folder by simply renaming a Natural library so that its name is no longer considered to be a valid Natural library name. When this is the case, the library name is modifiable in the properties of the library folder. This allows you to assign the library folder to a different library. If you rename a library folder in such a way that its name adheres again to the Natural naming conventions, the folder is no longer considered as a library folder; it is then considered as a regular Natural library (in this case, the library name is no longer modifiable in the library properties).

You can also create a "normal" folder (File > New > Other > General > Folder) in a Natural project and then assign it to a Natural library by specifying the library name in the folder properties. As long as a "normal" folder has not been assigned to a Natural library, the folder icon still has the standard color, which is yellow. When the folder has been assigned to a library, the color of the folder icon changes to green and yellow, indicating that it is now considered as a library folder.

When you create a subfolder within a Natural library or library folder, this subfolder automatically inherits the library from the parent folder. However, it is also possible to assign a different library to a subfolder.

Important:
Even if the objects of one and the same library are stored in different library folders, all object names must be unique within a library. Keep this in mind, for example, when copying objects to a different library folder.

The library that you assign to a library folder need not necessarily be contained in the workspace. When it does not yet exist on the Natural server, it will be created the next time you upload your changes.

The library folders are only used in the Eclipse workspace. They are not uploaded to the server (for example, when you deploy your application). On the server, only the conventional Natural libraries are used. When the objects in a library folder are uploaded to the server, they are always placed into the libraries that have been assigned to the library folder.

Caution:
As soon as a library folder is assigned to a library, a .paths file is created in the project. This file contains the mappings of the folder names to the Natural library names. You must not change the .paths file manually since this may result in damaging your project.

Group Folders

The Natural objects in a library can be grouped physically into separate folders, according to their object types. For example, all programs can be grouped into a folder named "Programs" and all adapters can be grouped into a folder named "Adapters".

Group folders

This is similar to the Natural Server view where the objects in a library are automatically grouped into different nodes, according to their object types. However, other than in the Natural Server view where the objects are just grouped in a logical way, the objects in the workspace are grouped physically. This means, when an object in the Navigator view is shown within a folder named "Programs", this folder also exists in the file system (for example, \MyFirstProject\Natural-Libraries\TUTORIAL\Programs).

Note:
If you do not want to group the objects physically, the Natural Navigator view offers the possibility to group them in a logical way. See Using the Natural Navigator View.

If you want to make use of physical group folders, you have to select the Group new objects by object type option when you create a new project (either by using the wizard or by downloading an existing library or object from a Natural server into a new project). You can also select this option in the project properties of an existing project. When you create a Natural object or error message, the group folders are then automatically created.

Note:
The default setting of the Group new objects by object type option when creating new projects can be determined in the Natural preferences.

The group folders are only created for existing objects. For example, when a downloaded library does not contain any subprograms, a folder with the name "Subprograms" is not created.

In addition to the group folders for the different Natural object types, it is also possible to have a group folder with the name "Resources". This folder is automatically created when you download resources (that is, non-Natural files such as images or HTML files) from a Natural server.

When you have chosen to use group folders, the special folders with the reserved names "SRC", "ERR" and "RES" are not created.

A group folder is the same as a library folder and is also indicated by a green- and yellow-colored folder icon: Icon.

File Names

In the workspace, different types of names can be used for the Natural objects. In addition to the Natural object names which must adhere to the Natural naming conventions, you can define alternative (long) file names which may be up to 255 characters long (without the file extension). This can be any combination of uppercase and lowercase, but has to follow the rules of the underlying file system (Windows or Linux).

The file name must always be followed by the Natural file extension for the corresponding object type (such as .NSP or .NSS). All alphabetical characters in this file extension must be in uppercase.

Take care: It is also possible to create "long" file names which have less than 8 characters. This is the case, for example, when the name contains lowercase characters which are not allowed for Natural object names.

Important:
Do not confuse the "long" file names with the long names of Natural objects (for example, of subroutines or DDMs). These are two different things.

The file name can either be specified when creating a Natural object or by renaming an existing Natural object. If an object has a file name, the original Natural object name can be modified in the object properties.

The file names are only used in the Eclipse workspace. They are not uploaded to the server (for example, when you deploy your application). On the server, only the conventional Natural object names are used.

Note:
File names are not supported for error messages.

Label Decorations

You can define your individual label decorations for the different nodes in the Navigator view and Natural Navigator view. For example, you can define to show the object size, the long name and the code page with the name of an object. For information on the label decorations that can be used with a Natural project, see Label Decorations in Setting the Preferences.

By default, several defined names are shown in the label decoration of a library folder or object:

  • For a library folder, the folder name is shown first, followed by the name of the Natural library, in parentheses, to which this folder has been assigned.

  • For an object, the file name is shown first, followed by the Natural object name in parentheses. When a long name is available (for example, of a subroutine), it is additionally shown, also in parentheses.

Example:

Project structure

Notes:

  1. In the Natural Navigator view, the visibility of the folder names depends on your settings. See Using the Natural Navigator View.
  2. NaturalONE also uses other label decorations. The visibility of the label decorations is controlled by the Eclipse preferences under General > Appearance > Label Decorations. If you do not want to see a specific type of label decoration, you can deselect the corresponding option in the Eclipse preferences.

Creating Libraries

In the Eclipse workspace, you can create a Natural library in different ways:

Start of instruction setTo create a new library using a wizard

  1. In the Navigator view or in the Natural Navigator view, select the Natural project in which you want to create the library.

  2. From the File menu, choose New > Natural Library.

    Or:
    Invoke the context menu and choose New > Natural Library.

    The following dialog box appears.

    Create Natural library

  3. Specify the following information:

    Option Description
    Project The project in which the library is to be created. If you have selected a project before invoking this dialog box, the project name is automatically shown in this text box. However, if you have not selected a project (or if you have invoked the dialog box, for example, in a new empty workspace), you have to enter the name of a project to be created.
    Folder If you want to store your new library at a different location within the selected project, choose the Browse button. You can then select a library, library folder or even a subfolder such as SRC. See also Library Folders.
    Library A unique name for the new library. This name must adhere to the Natural naming conventions.
    Use new folder as library folder Only enabled when you have specified a folder name. If you want to create a library and a library folder at the same time, enable this check box. In this case, the new library is created as a library folder. The folder name you have specified is used as the name for the library folder.

    It is important that you specify the new folder name as shown in the following example:

    /mylibfolder

    Do not omit the slash.

    Load library properties from secured environment Only enabled when Natural Security is active in the associated Natural environment. When enabled, this check box is activated by default. In this case, the library properties for the newly created library are loaded from the server. If a corresponding library does not exist on the server, the properties from the logon library of that server are used. If the associated Natural environment is not accessible, a dialog box appears. In this case, you can either cancel or continue the operation. If you continue, the properties are set to the defaults of the selected project.

    When Natural Security is active and this check box is deactivated, the properties for the newly created library are set to the defaults of the selected project.

  4. Choose the Finish button.

    The new library or library folder is created in the specified project. When you have just created a library (and no library folder), the library contains empty folders for Natural sources, resources (that is, non-Natural objects) and application-specific messages (see also Special Folders in a Library).

    You can now add Natural objects to the new library as described in Creating Natural Objects.

    Notes:

    1. If you do not need one of the empty folders (for example, the resource folder), you may delete it. If you need such a folder later, you can recreate it by selecting the library and then choosing New > Other > General > Folder from the File menu.
    2. After having created the library contents, the Upload or Build Natural Project command generates this library on the appropriate Natural server during the upload process. See Updating the Objects in the Natural Environment for further information.

Changing the Library Properties

The information below applies to both libraries and library folders.

Start of instruction setTo change the library properties

  1. Select the library or library folder in the Navigator view or in the Natural Navigator view.

  2. Invoke the context menu and choose Properties.

    The Properties dialog box appears.

  3. In the tree on the left side of the dialog box, expand the Natural node.

    When Natural Security is active in the associated Natural environment, a Security subnode is shown. Information on the pages that are available for this subnode is provided in the topics below.

    Properties

    When Natural Security is not active, only the Natural node is shown, without any further subnodes.

    Notes:

    1. With Natural Security, steplibs and some profile parameters can be defined for each library. The library properties override the project properties. In the library properties, however, it is only possible to change the parameters which can also be changed with Natural Security in the Natural environment. All other parameters, which are shown in gray on the different property pages of the Security subnode, are inherited from the project properties and cannot be changed here.
    2. If Natural Security is not active, it is not possible to specify any steplib information or profile parameters in the library properties. In this case, you can only define these properties for a project.

    When you select Natural in the tree, the information that is shown depends on whether you have selected a library or a library folder in the Navigator view or in the Natural Navigator view.

    • The following information is shown for a library:

      Natural

      The information on the private-mode library is only shown when private mode has been enabled. For each library in a project, you can create a private-mode library in the associated server environment. You can do this in one of the following ways:

      • Leave the Private-mode library name text box empty and choose the Generate Private-mode Library button. The generated name for this library includes the prefix which is defined in the Natural preferences; see Natural > Options in Setting the Preferences.

      • Enter the name for the library in the Private-mode library name text box. The name of the button then changes to Create Private-mode Library. Choose this button to create the private-mode library with the name you have just specified.

      Once the private-mode library exists in the server environment, its name is shown in the Private-mode library name text box (which is read-only in this case) and the name of the command button changes to Delete Private-mode Library. When you choose this button, a dialog box appears, asking whether you want to delete the private-mode library in the server environment. When you delete the private-mode library and the server environment is protected by Natural Security, the corresponding entries in Natural Security's system file are also deleted.

    • The following information is shown for a library folder. In this case, you have the possibility to assign the library folder to a different library.

      Natural

      See also Renaming Objects and Libraries.

  4. Make all required changes.

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

    Note:
    When a library is downloaded from Natural environment which is protected by Natural Security, the steplib information and a number of profile parameters are downloaded from the security profile which is located in the Natural environment and are saved in the Eclipse workspace. Any changes to the library properties are written to the .natural file. They are not written back to the security profile.

When you expand the Security node (which is only shown when Natural Security is active in the associated Natural environment), the following property pages are available:

Security

When you select Security in the tree, the following property page is shown. It shows the settings for the FNAT, FUSER and FSEC system files. If information on a system file cannot be found, "unknown" is shown.

Security

Parser

When you select Parser in the tree, the following property page is shown.

Parser

This property page provides different tabs. On these tabs, you can define the profile parameters that are relevant for a library when Natural Security is active. More information on these tabs is provided under Parser in the section Changing the Project Properties.

Regional Settings

When you select Regional Settings in the tree, the following property page is shown.

Regional settings

This property page provides different tabs. On these tabs, you can define the profile parameters that are relevant for a library when Natural Security is active. More information on these tabs is provided under Regional Settings in the section Changing the Project Properties.

Runtime

When you select Runtime in the tree, the following property page is shown.

Runtime

On this property page, you can define the LT profile parameter which is relevant for a library when Natural Security is active. See also Runtime in the section Changing the Project Properties.

Steplibs

When you select Steplibs in the tree, the following property page is shown.

Steplibs

When Natural Security is active, steplibs can only be defined in the library properties. In this case, it is not possible to define them in the project properties.

It is possible to define different development modes for the individual libraries that are contained in a project.

When private mode is defined for the library, it is possible to define private-mode names for the steplibs which exist in the project.

For detailed information on the information that you can specify on this property page, see Steplibs in Changing the Project Properties.

The property page in the library properties provides the following command button which is not available in the project properties:

Update Steplib Definitions

When you choose this button, the steplib definitions in your local workspace are updated with the steplib definitions from the associated Natural environment.

When Natural Security is active, it is important that your local steplib definitions match those in the Natural environment. For example, when you update a project in a Natural environment which is protected by Natural Security, the local steplibs are first compared with those in the Natural environment. When they match, the project is updated. When they do not match (for example, when different names are used or additional steplibs are defined in the local workspace), a dialog box appears listing the local steplib names and the steplib names in the Natural environment. Using the buttons in this dialog box, you can either update the local steplib definitions automatically and continue with the update, or you can cancel the update.

Updating the Library Properties with the Settings from the Server

When the project containing a library pertains to a Natural environment which is protected by Natural Security, you can update the Natural profile parameters settings of a library in your workspace (such as the programming mode or the input delimiter character) with those which are currently active on the server. This is helpful, for example, when the Natural builder finds an error due to conflicting settings in the Eclipse and Natural server environments.

Start of instruction setTo update the library properties with the settings from the server

  1. In the Navigator view or in the Natural Navigator view, select the library that you want to update

  2. Invoke the context menu and choose NaturalONE > Update Library Properties from Server.

    Note:
    This command is only visible when the library belongs to a project where the associated server environment is protected by Natural Security.

    The settings from the server are now available in your library properties.

Copying, Pasting, Moving, Renaming and Deleting Libraries

You copy, paste, move, rename and delete Natural libraries in the same way as any Natural object. For detailed information, see the following topics: