Natural for Linux stores objects in files accessible by operating system functions. Unlike Natural for z/OS where the objects are stored in Adabas system files, Natural for Linux stores the objects in specific directories on the disk. Thus, a database such as Adabas is not required to run Natural for Linux.
This document covers the following topics:
By default, the Natural libraries are created as subdirectories below the Natural root directory of a specific Natural version. The subdirectories have the same names as the libraries.
The Natural objects are stored as files in the subdirectories. The file name for a Natural object has the following form:
file-name.NKT
| file-name | This the name of the object. See also Object Naming Conventions in Using Natural. | ||||||||
| N | The first character of the extension is always "N". It stands for "Natural". | ||||||||
| K |
|
||||||||
| T | The third character of the extension stands of the type of the object. For valid values, see the list below. | ||||||||
For example, the source program TESTPROG is stored as file
TESTPROG.NSP, while the generated code for the map
TESTMAP is stored as file TESTMAP.NGM.
Note:
The file name is not always identical to the object name. Both the current object
name and the corresponding internal object name are documented in the file FILEDIR.SAG.
The following object types and the respective letters and numbers are used for the extensions available:
| Letter or Number | Object Type |
|---|---|
| A | Parameter data area (PDA) |
| C | Copycode |
| D | DDM |
| G | Global data area (GDA) |
| H | Helproutine |
| L | Local data area (LDA) |
| M | Map |
| N | Subprogram |
| P | Program |
| S | Subroutine |
| T | Text |
| 4 | Class |
| 5 | Command processor |
| 7 | Function |
| 8 | Adapter |
By default, objects allocated by Natural get the access rights
"rw-rw-rw-". This makes sure that users not belonging to
the group of the owner (that is, other users) can recatalog Natural programs. If this is
not desirable, you have to run the Linux utility umask and
set the appropriate mask.
Users developing Natural applications must have read and write access to all objects belonging to the application. In a plain production environment, the write access rights may be restricted to the maintenance team. If an object cannot be accessed due to too low access rights, Natural behaves as if an object was not found.
The Natural system files FNAT (for system programs) and FUSER
(for user-written programs) are located in different subdirectories.
FNAT assumes the following directory structure:
FNATLIBDIR.SAG
The file LIBDIR.SAG, which is only available for
FNAT, contains information on all further installed Software AG products
using Natural. This information can be displayed by using the system command SYSPROD.
FUSER assumes the following directory structure:
FUSER
The name of a user library must not start with "SYS".
The directory structure is generated during the installation of Natural. The directories representing the system and user libraries contain the following:
FILEDIR.SAG
This file contains internal library information used by Natural. For further
information, see The File
FILEDIR.SAG below.
SRC
This subdirectory contains the Natural source objects stored in the library.
GP
This subdirectory contains the generated Natural programs stored in the library.
ERR
This subdirectory contains the error messages stored in the library.
RES
This subdirectory contains the private and shared resources stored in the library.
DDMs can be stored in local libraries. If DDMs are used by a program, Natural first
searches the current library, then the steplibs, and then the library
SYSTEM. If the DDMs are not found, the program does not compile and
displays an error message. However, if FDDM mode has been activated, Natural searches for the DDMs only in the
system file FDDM.
The paths to the system files FNAT, FUSER and
FDDM are defined in the Configuration Utility. System files are version-dependent. Therefore,
Natural can only access system files of the current Natural version. It is recommended
that you only have one FNAT system file. It is possible, however, to define
several FUSER system files (for example, when you have different
development areas for different purposes).
The system file FDDM is a container in which all DDMs can be stored.
FDDM assumes the following directory structure:
FDDM
By default, the system file FDDM is not active. If you want to use it, you
have to activate FDDM mode as described below.
If FDDM mode is activated (both database ID and file number do not equal 0 in the
global configuration file), all DDMs are stored and read in the system file
FDDM. DDMs stored in libraries will no longer be accessible from
Natural. This is similar to the mainframe, where all DDMs are stored in the system
file FDIC.
If the FDDM system file is undefined in the global configuration file,
the DDMs are stored in the Natural libraries FUSER and
FNAT.
To activate FDDM mode
Create an empty directory in which the DDMs are to be stored in FDDM mode. The directory can have any name which corresponds to the Natural naming conventions.
Invoke the Configuration Utility.
In the global configuration file (category System
Files), assign a database ID and file number for the system file
FDDM and define the path to the directory that you have created
in the first step.
Open the required parameter file.
Locate the parameter FDDM.
Tip:
Locate this parameter by searching for "FDDM". See
Finding a
Parameter in the Configuration
Utility documentation for further information.
For the parameter FDDM, specify the same
database ID and file number that you have defined in the global configuration
file.
Save your changes.
Migrate all required DDMs to the system file FDDM as described
below.
All DDMs that are to be available in FDDM mode must be contained in the system file
FDDM. Especially the example DDMs delivered with Natural in library
SYSEXDDM must be available in the system file FDDM.
For migration of DDMs to the FDDM system file, you can choose between
different alternatives:
You can use the Object Handler
which supports the FDDM system file and offers the possibility to
migrate the DDMs into the FDDM system file. The DDMs can be unloaded
from the Natural libraries and can be stored into the FDDM system
file in the active Natural session.
Important:
To migrate a complete development environment, it is recommended to use
the Object Handler.
It is also possible to migrate the DDMs with the copy or move function of the
SYSMAIN
utility. In this case, it is required that
the FDDM parameter is first deactivated so that your old environment
is used again.
These alternatives are described below in detail.
Note:
The INPL utility loads
DDMs either to Natural libraries if FDDM mode is not active or to the system file
FDDM if FDDM mode is active. This may have some impact if the loaded
INPL files are intended to work in both modes. It may be necessary that the DDMs are
available in the Natural libraries as well as in the FDDM system
file.
To migrate DDMs to the system file FDDM using the Object Handler
Activate FDDM mode as described above.
Start Natural using the modified parameter file (that is, the parameter file in
which path for the parameter FDDM has been defined).
Issue the direct command SYSOBJH to invoke the
Object Handler.
The following steps assume that you use the Object Handler wizards.
In the main menu, mark the Unload function and press ENTER.
In the resulting screen, mark the option Unload objects into Natural work file(s) and press ENTER.
In the resulting screen, mark the option Set additional options and press ENTER.
In the resulting screen, deactivate the option Use FDDM file for processing DDMs and press ENTER to return to the previous screen.
This activates your old environment (which contains the DDM to migrated). If you do not deactivate this option, you cannot access the DDMs that are to be migrated.
Press ENTER repeatedly until the screen is shown in which the object type for the unload has to be selected.
The option Natural library objects only is selected by default. This option is required for the next steps.
Press ENTER.
In the resulting screen, enter an asterisk (*) in the fields Library and Object name. In addition, mark the field More detailed specification of objects. Press ENTER.
In the resulting screen, deactivate the options Error messages and Shared resources. In the Natural types field, enter "V" and press ENTER.
Press ENTER to display the command that is to be processed.
Press ENTER to start the unload function.
When the objects have been unloaded, return to the main menu.
In the main menu, mark the Load function and press ENTER.
In the resulting screen, mark the option Load objects from Natural work file(s) and press ENTER.
In the resulting screen, mark the option Set additional options and press ENTER.
In the resulting screen, activate the option Use FDDM file for processing DDMs.
This activates your new environment containing the FDDM system
file.
Note:
In different libraries, DDMs can exist with identical names. To prevent
overwriting DDMs in the FDDM system file and to detect DDMs with
identical names, it is recommended to load the DDMs with the Do not
replace option. This option is located on the same page as the
option Use FDDM file for processing DDMs.
Press ENTER to return to the previous screen.
Press ENTER repeatedly until the screen is shown in which the object type for the load has to be selected.
The option Load all option from the work file is selected by default. This option is required for the next steps.
Press ENTER.
The command that is to be processed is now shown.
Press ENTER to load the objects.
When you have migrated all DDMs to the system file FDDM, you can check
whether FDDM is used.
To check whether FDDM is used
Start Natural.
Issue the system command SYSPROF.
If the FDDM file is displayed, Natural will access only DDMs
stored in this system file.
If the FDDM file is not displayed or if the expected files are not
displayed, revise the parameter file used for your session.
A Natural developer must have read, write and delete rights for all objects.
An end-user must only have read rights for the generated programs (and in some special cases also read rights for the sources).
Do not access Natural files with operating system utilities. These utilities might modify and destroy the Natural directory information.
The use of an external editor is not recommended as code page conflicts may arise. These conflicts can - but not necessarily must - deteriorate your source code.
Do not store private data files in the directories FNAT,
FUSER and FDDM, since Natural may delete or modify them in
an unexpected way.
Do not use one of the directories FNAT, FUSER and
FDDM as working directories for your Linux applications, since this can cause
problems when issuing Natural system commands.
The file name (i.e path including file name in 8.3 format) of any object accessed by Natural must not exceed 255 bytes.
The file FILEDIR.SAG supports up to 60000 objects. It contains internal library information used by Natural including the programming mode of an object (structured or reporting) and internally converted object names. These internal object names are automatically created when storing Natural objects to disk with:
names longer than 8 characters (which can be the case with DDMs);
names containing any special character supported by Natural but not by the operating system.
Internal object names are unique and consist of an abbreviation of the current object name and an arbitrary number. Both the current object name and the corresponding internal object name are documented in FILEDIR.SAG.
Even if an object is located in the correct directory, it can only be used by Natural
after this library information is included in FILEDIR.SAG. For
objects created within Natural, the library information is included automatically.
For all other
objects, the Import function of the SYSMAIN utility should be
used.
The utility FTOUCH can be
used to update FILEDIR.SAG without entering Natural.
The directory file FILEDIR.SAG in a Natural library as well as the
Natural error message files are created in a portable platform-independent format. This
offers, for example, the possibility of exchanging FUSER libraries between
different Windows and Linux platforms simply by copying the libraries via operating
system commands.
The FNAT system file belongs to a Natural installation and is both
version-specific and platform-specific. Therefore, it is not recommended to share
FNAT system files among different platforms. Especially the
FNAT system file on a Windows platform contains a completely different
set of utilities as the FNAT system file on the Linux platform.
Although it is now possible to share an FUSER system file among different
platforms, this possibility should by handled with care because Natural's locking
mechanism does not cross machine boundaries and hence it would be possible for two
Natural sessions on different platforms to modify the same object at the same time with
unpredictable results.
The following topics are covered below:
When the application to be ported uses the system variable *LANGUAGE,
you have to take notice of the following information.
Almost all Natural objects are stored in the system file with a name which contains only upper-case characters. An exception are the language-dependent objects (that is: the objects which have been created for a specific language). Language-dependent objects may contain lower-case characters in their names. Since Windows is a case-preserving operating system (whereas Linux is a case-sensitive operating system), it may happen that names which have been created under Linux cause a conflict in Windows, or that an application which has been developed under Linux yields unexpected results in Windows.
The command SAVE PGM& creates an object where the
object name contains the language identifier. The resulting object name depends on the
setting of *LANGUAGE:
Setting of *LANGUAGE
|
An object with the following name is created |
|---|---|
| 33 | PGMX (with an upper-case X)
|
| 59 | PGMx (with a lower-case x)
|
The separate objects which have been created under Linux
(PGMX.NGP and PGMx.NGP) get entries in the
file FILEDIR.SAG with the names PGMX and
PGMx. These two objects will be treated differently, depending on the
environment in which Natural is being executed:
When you execute PGMX with Natural for Linux, the file
PGMX.NGP is loaded into the buffer pool and executed.
When you execute PGMX with Natural for Windows, either the file
PGMX.NGP or PGMx.NGP is loaded into
the buffer pool and executed. This is because Windows does not distinguish between
these two objects and treats them as one and the same object. Thus it may be
possible that applications which share an FUSER, or a copy of such an
FUSER, behave in a different manner.
Message files in the old, non-portable format which have not been created on a 64-bit platform are not readable.
If you want to migrate your applications from a 32-bit platform to a 64-bit platform, you must first convert your old message files to the portable format. You do this by using the export and import functions of the SYSERR utility. First, you export the message file to a text file, and then you generate a new message file by importing the text file into Natural. This creates a portable message file which is readable on Windows and Linux. For detailed information on the export and import functions, see Generating Message and Text Files in the Tools and Utilities documentation.
Semaphores are used to synchronize access to the Natural system files. Since this
requires additional operating-system resources, you should consider incrementing the
kernel parameters SEMMNI and SEMMNS by the
number of system files to be accessed.
With the usage of semaphores, several users have permission to address the system files
FNAT and FUSER. The semaphore ID is saved together with a
lock file (*.LCK). If a further Natural session is started, the
buffer pool looks for the semaphore ID and the corresponding lock file for
synchronization.
If the lock file is not present, a new semaphore ID and lock file will be generated. This means that no synchronization will be possible.
Caution:
It is not allowed to delete only one of the resources. You must always delete the
semaphore ID and the corresponding lock file.
When you use NFS (Network File System) to store Natural libraries, you can run into problems when the directories in which the Natural libraries are stored are mounted via NFS from a file server in your network.
The reason for this is the need to lock the FILEDIR.SAG file stored in each library during update operations of Natural objects.
If your NFS locking is incompatible or not properly set up between the involved platforms, Natural can hang in an uninterruptible state while waiting for NFS locking requests to be processed. These requests are generally logged on the consoles of the involved systems or in some other system-dependent log file.
The work-around to solve this problem is to store Natural libraries only on local disks if problems with a hanging and uninterruptible nucleus occur.