Natural Runtime is used to execute applications that have been written using the development version of Natural for Windows.
This document tells you how to port an application from a Natural development workstation to a Natural Runtime workstation. This porting process can be used for a first-time installation of Natural Runtime and for Natural Runtime workstation updates.
You will also learn how to use a service for starting Natural Runtime processes.
The following topics are covered:
Step 1: Packaging the Application on the Development Workstation
Step 3: Installing the Application on the Runtime Workstation
Important:
Before porting an application to a Natural Runtime workstation,
ensure that all objects have been compiled using identical Natural and Natural
Runtime versions.
The following Natural system commands are not supported by Natural Runtime:
CATALL
CATALOG
CHECK
CLEAR
COMPOPT
DEBUG
DELETE
EDIT
GLOBALS
PURGE
READ
RENUMBER
RUN
SAVE
SCAN
SCRATCH
STOW
STRUCT
SYSDDM
SYSMAIN
UNCATALOG
UNLOCK
Natural editors are not supported by Natural Runtime.
Natural utilities providing developer functionality are not supported by Natural Runtime.
To port an application to a runtime workstation, the following steps (which are described in detail later in this section) are required:
Package the application on the development workstation:
Create a collecting directory in your file system.
Customize the global configuration file and copy it to the collecting directory.
Customize the Natural parameter file and copy it to the collecting directory.
Copy or unload all required objects to the collecting directory.
Copy the contents of the collecting directory to a transfer medium (for example, to a CD).
Install Natural Runtime on the runtime workstation.
Install the application on the runtime workstation:
Copy the global configuration file from the transfer medium to the runtime workstation.
Copy the Natural parameter file from the transfer medium to the runtime workstation.
Copy or load the Natural objects from the transfer medium to the runtime workstation.
Start the application on the runtime workstation.
See also Transferring Natural Generated Programs in the Programming Guide.
The following topics are covered below:
Use the Windows Explorer to create a new directory in the file system of the development workstation. Use this temporary directory to collect all files which belong to the application.
You have to create a global configuration file which contains all settings required to run your application on the runtime workstation. To do so, you create a backup version of your current global configuration file, make all required changes for the runtime version, copy the customized global configuration file to the collecting directory and then restore your old global configuration file. This is described in detail below.
To customize and copy the global configuration file
Use the Windows Explorer to back up the existing global configuration file.
Note:
If you do not know where to find the global configuration file,
invoke the Configuration
Utility, expand the Local Configuration
File node and select the
Installation
Assignments node. The full path and name of the global
configuration file is then shown.
Invoke the Configuration Utility and expand the Global Configuration File node.
Adjust the settings of the global configuration file as required for your application and save your changes. See also the notes below.
Important:
As long as the global configuration file with the settings
for the runtime environment is active, you cannot work with the development
version of Natural.
Use the Windows Explorer to copy the customized global configuration file to the collecting directory.
Use the Windows Explorer to restore the backup version of the global configuration file.
Make sure that with every new application you are porting, the new settings are compatible with the old settings.
Example: Your first application accesses an SQL database and the DBID entry applies to this SQL database. Your second application, which you are porting at a later date, accesses an Adabas C database. In this case, you must add a second DBID entry for Adabas C. If you do not add a second entry, the new global configuration file will overwrite the SQL database's DBID and your first application will no longer be able to access its database.
You have to create a Natural parameter file which contains all settings required to run your application on the runtime workstation.
To customize the Natural parameter file
Invoke the Configuration Utility and expand the node for the required parameter file.
Adjust the settings of the parameter file as required for your application to run in the runtime environment.
Ensure that the parameter file contains the name of the program to be started. The examples below show different possibilities for this purpose.
| Parameter | Required Setting |
|---|---|
AUTO |
Must be set to ON so that an automatic logon
is executed at the start of the Natural session.
|
INIT-LIB |
The name of the library into which the application is to be moved. |
STARTUP |
The name of the program that is to be started. |
USER |
The default user ID that is to be set when Natural is started. |
| Parameter | Required Setting |
|---|---|
STACK |
Must contain the library and the program to be started. For
example:
|
Save the modified parameter file with the name that you want to use
in the runtime environment (for example, with the name
RUNPARM).
Use the Windows Explorer to copy the customized parameter file (which has the extension SAG) to the collecting directory.
Note:
If you do not know where to find the parameter file, expand the
Local Configuration File node of the Configuration
Utility and select the
Installation
Assignments node. The location of the Natural
parameter files is then listed as Path to
parameter.
To make compiled code available with Natural Runtime, you have to copy the cataloged objects from the Natural development environment to the runtime environment.
If the Natural application consists of complete Natural libraries, you can copy the libraries with the copy-and-paste functionality of the Windows Explorer.
Another way for porting the objects is use the Object Handler for unloading the objects in the Natural development environment and for loading them in the runtime environment.
To copy the objects
Use Natural Studio to create a new library which is to contain all objects for the runtime version.
Important:
If the application consists of more than one library,
create a new library for each library that is used by the application and
proceed as described below.
Use Natural Studio to copy all cataloged objects, resources and error messages from the development library to the new library. Do not copy the sources.
Use the Windows Explorer to copy the entire directory which corresponds to the new library (including the file FILEDIR.SAG and the subdirectories GP, RES and ERR) to the collecting directory.
Notes:
SYSPROF in
Natural Studio. The Files in File System tab of the
resulting dialog box shows the path to the directory that has been created for
the system file FUSER. Your new library is a subdirectory of the
FUSER directory; it has the same name as defined in Natural
Studio.
FUSER
directory by using the Configuration
Utility: select the parameter file that you have created in a
previous step (that is: the parameter file that will be used to start the
application in the runtime environment), expand the Natural
Execution Configuration node and select the System
Files node. The path to the FUSER directory is shown
on the FUSER tab.
If required, rename the copied directory in in the collecting directory: enter the name of the library that is to be used in the runtime environment.
To unload the objects
From the menu, choose to start the Object Handler.
Start the Unload Wizard.
In the first dialog of the unload wizard, select the option button Unload objects into Natural work file(s).
In the next dialog in which you have to specify the options settings, define a Natural work file in the Unload file text box. This work file must be located in the collecting directory which you have created previously.
If the application uses the same library names in both environments, do not specify any information in the next dialog (which can be used to specify parameters).
However, if the application uses library names in the runtime environment which are different from those used in the development environment, select the option button Use global parameters, choose the button and set the name in the resulting dialog box.
In the next dialog in which you have to specify the object type, select the option button Natural library objects.
In the next dialog in which you have to select the Natural library objects to unload, choose the button.
In the resulting dialog box, specify all cataloged objects, resources and error messages contained in the application. Do not unload the sources: from the S/C-Kind drop-down list box, choose Gp.
Proceed to the next dialog and unload the objects.
After a successful unload, check the work file that has been created in the collecting directory. Use the Load Wizard to scan the work file for all objects.
When all files in the collecting directory are ready for porting, use the Windows Explorer to copy the contents of the collecting directory (including all subdirectories) to the transfer medium (for example, to a CD).
Install Natural Runtime on the runtime workstation. See the Installation documentation for further information.
Note:
This step is not required when updating applications on the Natural
Runtime workstation.
The following topics are covered below:
Use the Windows Explorer to copy the global configuration file (in which the required DBID has been defined) from the transfer medium to the directory on the runtime workstation which contains the global configuration file.
 |
Warning: An existing global configuration file will be overwritten. |
Note:
If you do not know where to find the global configuration file,
invoke the Configuration
Utility on the runtime workstation, expand the Local
Configuration File node and select the
Installation
Assignments node. The full path and name of the global
configuration file is then shown.
Use the Windows Explorer to copy the Natural parameter file from the transfer medium to the directory on the runtime workstation which contains the Natural parameter files.
|
Warning: An existing parameter file will be overwritten. |
Note:
If you do not know where to find the parameter files, select the
Installation Assignments node of the Configuration
Utility as described above. The location of the Natural parameter files is then
listed as Path to parameter.
Depending on how the objects have been packaged (see Copying or Unloading the Objects), the transfer medium contains either complete libraries or a Natural work file.
If complete libraries have been copied using the Windows Explorer, the transfer medium contains directories with Natural library names. Each directory reflects the Natural library structure: it contains the file FILEDIR.SAG and the subdirectories GP, RES and ERR. In this case, you have to copy the libraries as described below.
If the objects have been unloaded into a Natural work file using the Object Handler, the transfer medium contains this work file. In this case, you have to load the objects using the Object Handler as described below.
To copy the libraries
Use the Windows Explorer to copy the libraries (including all
subdirectories) to the directory for the FUSER system file.
Note:
If you do not know where to find this directory, invoke the
Configuration Utility, select
the parameter file that you have copied in a previous step, expand the
Natural Execution Configuration node and select the
System Files node. The path to the
FUSER directory is shown on the FUSER
tab.
To load the objects
Invoke the Configuration
Utility and make sure that the FUSER settings
of the parameter file NATPARM have the same DBID and FNR as the
parameter file that you have copied in a previous step.
Note:
The DBID and FNR of the FUSER are shown
on the FUSER tab which is invoked as described
above.
From the Windows menu, choose .
Note:
The Start menu group name (by default, this
is "Software AG") can be changed during the
installation.
This invokes Natural Runtime with the standard parameter file
NATPARM.
Logon to the library SYSOBJH.
Execute the program MENU in the library
SYSOBJH.
The Object Handler window appears.
In the first dialog of the load wizard, select the option button Load objects from Natural work file(s).
In the next dialog in which you have to specify the options settings, define your Natural work file in the Load file text box. This must be the work file which is located on the transfer medium.
Note:
If DBID and FNR of the new parameter file differ from the
standard NATPARM settings, enter the values used by the new
parameter file in the next dialog (which can be used to specify parameters):
Select the option button Use global parameters and choose
the button. In the resulting dialog box, select the
Load Target tab and enter the corresponding values for
DBID and FNR in theLoad FUSER group box.
In the next dialog in which you have to specify the object type, select the option button Load all objects from work file.
Proceed to the next dialog and load the objects.
Exit the Object Handler and then exit Natural Runtime.
When all required files have been copied to the runtime workstation, you can start your application. It is recommended that you create a shortcut for each application. You can then define the name of the parameter file which is required to run the application in the shortcut.
On the runtime workstation, you can start the application in different ways:
With naturalr.exe
The user interface, which appears when you do not specify the name of
a parameter file with the naturalr.exe command, runs
invisibly in the background. For example:
"C:\SoftwareAG\Natural\Bin\naturalr.exe" PARM=file-name
where file-name is the name you have assigned to your customized Natural parameter file (without any file extension).
The user interface becomes visible only if the application for which
it was started does not terminate this runtime process properly (for example,
if the application does not issue a TERMINATE statement). This
user interface increases the consumption of system resources, even if it does
not appear.
With natrt.exe
This so-called "mini runtime" does not have a user
interface that would allow the user to select an application for execution. It
requires that the name of the program that is to be started is defined in the
parameter file. For example:
"C:\SoftwareAG\Natural\Bin\natrt.exe" PARM=file-name
where file-name is the name you have assigned to your customized Natural parameter file (without any file extension).
The mini runtime terminates as soon as all commands in the parameter file have been processed.
If a program name is not specified in the parameter file, the mini runtime terminates immediately.
When you use the mini runtime, the consumption of system resources is decreased and it is ensured that the runtime process terminates at the end of the application processing.
When the Natural Runtime startup service has been installed and is active, it is possible to start one or more Natural Runtime processes automatically when the PC is booted.
You can define parameter templates which are used to hold Natural parameters. It is thus possible to start a Natural Runtime process with all parameters that are defined in the template.
A Natural Runtime process is normally used to run a Natural
application. For this purpose, the Natural Runtime process has to be started
with a template in which the STACK parameter has
been defined as follows:
STACK=(LOGON library-name; program-name)
When the STACK parameter has not been defined,
Natural is started without running any application.
By default, the Natural Runtime startup service is not installed. You have to install it as described below.
The following topics are covered below:
The file natrtsvc.exe, which is stored in the bin directory of Natural Runtime, is used to execute the service commands.
The following service commands can be specified in the Command Prompt window of Windows:
| Command | Description | ||||||
|---|---|---|---|---|---|---|---|
NATRTSVC INSTALL
mode |
|
||||||
NATRTSVC REMOVE |
Removes the Natural Runtime startup service from the system. | ||||||
NATRTSVC START |
Starts the Natural Runtime startup service if
it had not been started yet. The service searches for previously created
parameter templates for which the start parameter has
been set to "yes". In addition, it starts a Natural
Runtime process with the Natural parameters which are also stored in the
template.
|
||||||
NATRTSVC START
template-name |
Starts a Natural Runtime process with the Natural parameters stored in the specified template. If the Natural Runtime startup service has not been started (automatically at boot time or manually by the user) an error message is displayed. | ||||||
NATRTSVC STOP |
Stops the Natural Runtime startup service and all Natural Runtime processes that have been started by the Natural Runtime startup service. | ||||||
NATRTSVC STOP
template-name |
Stops the Natural Runtime processes that have been started by the Natural Runtime startup service with the Natural parameters stored in the specified template. | ||||||
NATRTSVC CREATE
template-name |
Creates a new parameter template to be started by the Natural Runtime startup service. | ||||||
NATRTSVC DELETE
template-name |
Deletes the specified template from the Natural Runtime startup service. | ||||||
NATRTSVC SET
template-name
start=mode |
|
||||||
NATRTSVC SET
template-name
Natural-parameters |
Stores the Natural parameters in the specified template. For valid Natural parameters, refer to the Parameter Reference. When you specify more than one parameter, you have to separate the parameters with blanks. Instead of parameters, it is also possible to specify the name of a Natural parameter file. | ||||||
NATRTSVC SHOW |
Displays the startup settings and the stored Natural parameters for all templates. | ||||||
NATRTSVC SHOW
template-name |
Displays the startup settings and the stored Natural parameters for the specified template. | ||||||
NATRTSVC STATUS |
Displays the status of all templates, that is: whether these templates are active or not active. | ||||||
NATRTSVC STATUS
template-name |
Displays the status of the specified template, that is: whether this template is active or not active. | ||||||
This example explains how to install the Natural Runtime startup service, create a new template and start the corresponding Natural process each time the PC is booted.
To start a Natural process when the PC is booted
Invoke the Command Prompt window of Windows.
Go to the Natural bin directory which contains the file natrtsvc.exe.
Enter the following command to install the Natural Runtime startup service:
NATRTSVC INSTALL automatic
The following information is shown:
%NATRTSVC-I: Natural n.n Startup Service (1) %NATRTSVC-I: Natural n.n Startup Service (1) successfully installed %NATRTSVC-I: Path of binary is C:\SOFTWAREAG\NATURAL\BIN\NATRTSVC.EXE %NATRTSVC-I: Startup mode of Natural n.n Startup Service (1) is 'Automatic' %NATRTSVC-I: Natural n.n Startup Service (1)
From now on, the Natural Runtime startup service will be started automatically each time the PC is booted.
Enter the following command to create an empty parameter template with the name "exa_temp":
NATRTSVC CREATE exa_temp
The following information is shown:
%NATRTSVC-I: Natural n.n Startup Service (1) %NATRTSVC-I: New Natural instance 'exa_temp' created %NATRTSVC-I: Natural n.n Startup Service (1)
Enter the following command to define that a Natural Runtime process with the Natural parameters stored in the parameter template "exa_temp" is to be started when the Natural Runtime startup service is started:
NATRTSVC SET exa_temp start=yes
The following information is shown:
%NATRTSVC-I: Natural n.n Startup Service (1) %NATRTSVC-I: Configuration successfully set %NATRTSVC-I: Natural n.n Startup Service (1)
Enter the following command to store the contents of the Natural parameter file "myparm" in the parameter template "exa_temp":
NATRTSVC SET exa_temp parm=myparm
The following information is shown:
%NATRTSVC-I: Natural n.n Startup Service (1) %NATRTSVC-I: Configuration successfully set %NATRTSVC-I: Natural n.n Startup Service (1)
Reboot your PC.
Since you have defined the automatic startup mode for the Natural Runtime startup service, the defined Natural Runtime processes are started automatically after Windows has been started.
Enter the following command to display the status of all parameter templates that are currently defined:
NATRTSVC STATUS
The following information is shown:
%NATRTSVC-I: Natural n.n Startup Service (1) %NATRTSVC-I: Send request to Natural n.n Startup Service (1) %NATRTSVC-I: exa_temp is active %NATRTSVC-I: Natural n.n Startup Service (1)