
	Version 6.3.12 for OpenVMS	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— 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
Directories
Configuring the Natural Web I/O Interface Daemon on OpenVMS
Logging Information
SSL Support
Working with the OpenVMS Components of the Natural Web I/O Interface

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.

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.

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
NWOSRVD.CONF - Configuration File for the Natural Web I/O Interface Daemon
START_NWOSRVD.COM - Command Procedure for Starting the Natural Web I/O Interface Daemon
Environment Variables

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

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.

[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.

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.

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

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.

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:

%NWOSRVD is the internal name of the Natural Web I/O Interface daemon.
The message type is shown directly after %NWOSRVD. It can be one of the following: -E (error), -W (warning), -I (information), or -H (help).
Date and time when the message was reported.
Any text or message which pertains to the error, warning, information or help.

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

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.

Generate a certificate signing request and a private RSA key:
```
@SSL$COM:SSL$CERT_TOOL
```
In the resulting menu, choose 3. Create a Certificate Signing Request and follow the instructions on the screen.
Generate a self-signed certificate:
```
@SSL$COM:SSL$CERT_TOOL
```
In the resulting menu, choose 4. Create a Self-Signed Certificate and follow the instructions on the screen.

Note:
The certificate can be self-signed or it can be signed by a CA (Certificate Authority) such as VeriSign.
Put the generated files from SSL$KEY into NATDIR:[NWO.<nodename>]. Change the default file names so that they contain "cert.": server.cert.csr, server.cert.crt and server.cert.key.
Import the generated files to a truststore on the client. See also Trust Files (Java EE-based servers only).

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
Starting a Natural Application

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.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT