Version 6.3.8 for OpenVMS
 —  Natural Web I/O Interface  —

Installing and Configuring the Natural Web I/O Interface Server

On OpenVMS, the server part of the Natural Web I/O Interface is implemented as a daemon.

This document covers the following topics:


Installing the Natural Web I/O Interface Daemon

The installation of the Natural Web I/O Interface daemon is part of the Natural for OpenVMS installation.

Top of page

Directories

The following directories are created when Natural is installed together with the Natural Web I/O Interface on an OpenVMS system:

Directory Description
SAG$ROOT:[NATURAL] Top-level Natural directory (NATDIR).
NATDIR:[V<version>] Directory with all components for the current Natural version.
NATDIR:[V<version>.INSTALL] Contains the command procedures for the post-installation.
NATDIR:[V<version>.NWO] Contains the command procedure START_NWOSRVD.COM for starting the daemon.
NATDIR:[NWO.<nodename>] Work directory. Contains the template file NWOSRVD.CONF, the generated command procedure, and the log file for each daemon.
NWODIR:[NWOEXUEX.USEREXIT1] Contains the files for building the LIBNWOUSEREXIT1.EXE.
NWODIR:[NWOEXUEX.USEREXIT2] Contains the files for building the LIBNWOUSEREXIT2.EXE.

Note:
The above table lists the most important directories and files.

Environment Variables Description
NATDIR="SAG$ROOT:[NATURAL]" Top-level Natural directory.
NATVERS Current Natural version.
NWODIR="NATDIR:[NWO]" Top-level Natural Web I/O Interface directory.
NWONODE Name of the machine.

Top of page

Configuring the Natural Web I/O Interface Daemon on OpenVMS

When the Natural installation has finished, the directory NATDIR:[NWO.<nodename>] contains the file NWOSRVD.CONF.

The configuration of the Natural Web I/O Interface daemon can be done using the Natural Web I/O Interface daemon commands or by editing the configuration file NWOSRVD.CONF.

The following topics are covered below:

Natural Web I/O Interface Daemon Commands

The following commands can be specified at the OpenVMS command prompt:

Command Description
nwosrvd –help

Shows all available Natural Web I/O Interface daemon commands and subcommands.

nwosrvd –v

Shows the version of the Natural Web I/O Interface daemon.

nwosrvd nnnn

Defines the listening port number.

nwosrvd –show

Shows the configuration of the Natural Web I/O Interface daemon.

nwosrvd -config keys

Changes the configuration of the Natural Web I/O Interface daemon. The following keys can be specified:

-userexit1=pathname

The message defined with this key is saved in the UserExit1 key of the configuration file NWOSRVD.CONF, section [UserExits].

–userexit2=pathname

The message defined with this key is saved in the UserExit2 key of the configuration file NWOSRVD.CONF, section [UserExits].

–logging=option

The option defined with this key is saved in the Logging key of the configuration file nwosrvd.conf, section [Miscellaneous].

-ssl=[yes|no]

The option defined with this key is saved in the ssl key of the configuration file nwosrvd.conf, section [SSL].

To remove any user exits from the configuration, enter the following command:

nwosrvd –config –userexit1=

Once the configuration was changed, the Natural Web I/O Interface daemon must be restarted.

NWOSRVD.CONF - Configuration File for the Natural Web I/O Interface Daemon

The configuration file NWOSRVD.CONF contains information that the user exits need for the Natural Web I/O Interface daemon. It has the following content:

[Miscellaneous]
Logging=I

[UserExits]
;UserExit1=DISK$USER:[DIR.NWOEXUEX]LIBNWOUSEREXIT1.EXE 
;UserExit2=DISK$USER:[DIR.NWOEXUEX]LIBNWOUSEREXIT2.EXE

[SSL]
ssl=no
Section in Configuration File Description
[Miscellaneous]

The key Logging is used to define the amount of logging information that is to be reported. One of the following options can be specified:

E for errors.
W for warnings.
I for information.

See also Logging Information.

[UserExits]

Two user exits can be defined:

UserExit1

The library that is defined by UserExit1 contains the following function:

int nwo_CheckUsernameAndPassword(const char *pUsername, const char *pPassword, const char *pNewPassword, char *pErrorMessage)

If the key UserExit1 is defined in the configuration file, the function nwo_CheckUsernameAndPassword is responsible for checking the user name and password. If a new password is received, user exit 1 is also responsible for changing the password.

In the case of an error, the return code of the function must be "0"; in this case, the pErrorMessage is returned to the client. When user name and password are correct, the return code must be a value other than "0".

UserExit2

The library that is defined by UserExit2 contains the following functions:

  • int nwo_Messages(int *iNumberOfMessages, char *pMessage[])

    iNumberOfMessages: Number of messages returned in the array.

    pMessage: Array of messages.

    If the key UserExit2 is defined in the configuration file, the function nwo_Messages is called when a new connection (client) is accepted and the messages returned by this function are sent to the client. User exit 2 may be used, for example, to send a message such as the following: "For maintenance reasons, the Natural application XXXXX will be down next monday, from 18:00 until 19:00".

    In the case of an error, the return code of the function must be "0".

    After the function nwo_Messages has been called, the function nwo_FreeMessages is called.

  • int nwo_FreeMessages(int iNumberOfMessages, char *pMessage[])

    iNumberOfMessages: Number of messages.

    pMessage: Array of messages.

    If the key UserExit2 is defined, the function nwo_FreeMessages is called to free any resources (normally memory) allocated in the function nwo_Messages.

    In the case of an error, the return code of the function must be "0".

[SSL]

The key ssl is used to define whether the SSL protocol is to be used. One of the following values can be specified: "yes" or "no".

See also SSL Support.

START_NWOSRVD.COM - Command Procedure for Starting the Natural Web I/O Interface Daemon

The command procedure START_NWOSRVD.COM is used to start the Natural Web I/O Interface daemon. For further information, see Starting and Stopping the Natural Web I/O Interface Daemon.

Environment Variables

In the command procedure START_NWOSRVD.COM, several environment variables can be set for the Natural session that is started by the daemon:

DEFINE NWO_ENABLE_ACK [YES|NO]

This environment variable is used for asynchronous screens (SET CONTROL N).

YES When asynchronous screens are sent to the client, Natural will wait to receive an ACK package before the next screen can be sent.
NO No waiting between asynchronous screens. Default value.
DEFINE NWO_TIMEOUT [number-of-seconds]

The maximum time, in seconds, that Natural waits to receive any input from the client before it closes the session. If the number of seconds is "0", Natural waits infinitely (no timeout). The default value is "0".

Error NAT5466 is returned at timeout. In Natural, the application can handle this error and decide how to continue or terminate.

Top of page

Logging Information

The logging information system reports errors, warnings and/or session information, depending on the option that has been defined with the following Natural Web I/O Interface daemon command:

nwosrvd -config -logging=option

option can be one of the following:

Option Description
E

Error.

When this option is specified, the Natural Web I/O Interface daemon reports only errors.

In the case of an error, the daemon usually exits immediately.

W

Warning.

When this option is specified, the Natural Web I/O Interface daemon reports errors and warnings for uncritical errors.

In the case of a warning, the daemon continues to run.

I

Information.

When this option is specified, the Natural Web I/O Interface daemon reports errors, warnings and information.

The information messages allow to check the session parameters, IP address, etc.

Help information, for example, on how to run, configure and install the Natural Web I/O Interface daemon is always provided. The messages which inform you when the daemon has been started or stopped are also part of the help information.

To find out which logging option is currently active, enter the following Natural Web I/O Interface daemon command:

nwosrvd -show

The logging messages are shown directly for the standard output. The format of the messages is as in the following example:

%NWOSRVD-E: 18.01.2008 14:55:20 NWO_SRVDCONF is not established.

The following information is provided:

If you want to save these messages, you have to redirect the standard output to a file.

Example:

DEFINE/USER SYS$OUTPUT file-name
nwosrvd -show

Top of page

SSL Support

SSL is used for a secure connection between the Natural Web I/O Interface server and the Natural Web I/O Interface client or Natural for Ajax. Server authentication cannot be switched off. A certificate and a private key is always required on the server.

To create and use an SSL certificate and a private key on the server, proceed as described below.

Top of page

Working with the OpenVMS Components of the Natural Web I/O Interface

The OpenVMS components of the Natural Web I/O Interface are used to start the Natural applications linked with the Natural Web I/O Interface library.

The following topics are covered below:

Starting and Stopping the Natural Web I/O Interface Daemon

The Natural Web I/O Interface daemons are responsible for accepting new sessions.

Before you start the Natural Web I/O Interface daemon, you have to make sure that all requirements as described in the section General Information for Starting the Daemons of the Installation documentation are met.

The command procedure START_NWOSRVD.COM is used to start the Natural Web I/O Interface daemon:

@NATDIR:[V<version>.NWO]START_NWOSRVD.COM <portnumber>

The process which is created by the command procedure START_NWOSRVD.COM has the name NWOSRVD_<portnumber> (for example, NWOSRVD_2800).

Note:
The daemon must be started on a port which is not yet used.

To stop the daemon process, enter the following command:

STOP NWOSRVD_<portnumber>

Starting a Natural Application

See Configuring the Client for information on how to set up the client.

Top of page