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

— Natural Web I/O Interface —

Overview of Configuration File Elements

This document covers the following topics:

Contents of the Configuration File
Sessions
Global Settings
Users and Passwords

Contents of the Configuration File

By default, the configuration file is delivered with the following entries, depending on the type of client that you are using:

Natural Web I/O Interface Client

<?xml version="1.0" encoding="utf-8" ?>
<settings>
     <global>
        <last_activity_timeout>3600</last_activity_timeout>
     </global>
    <sessions>
        <session id="Connect to Natural" trace="false">
        </session> 
        <session id="localtestserver" trace="false">
            <natural_server>localhost</natural_server>
            <natural_port>6640</natural_port>
            <natural_program/>
            <user id="" pwd=""/>
            <natural_parameter/>
        </session>
    </sessions>
</settings>

Natural for Ajax

<?xml version="1.0" encoding="utf-8" ?>
<settings>
     <global>
        <last_activity_timeout>3600</last_activity_timeout>
     </global>
    <sessions>
        <session id="Connect to Natural" trace="false">
        </session>
        <session id="Natural for Ajax Examples (UNIX)" trace="false">
            <natural_server>127.0.0.1</natural_server>
            <natural_port>2800</natural_port>
            <natural_program>nwo.sh</natural_program>
            <natural_parameter>STACK=(LOGON SYSEXNJX;MENU-NJX)</natural_parameter>
        </session>
        <session id="Natural for Ajax Examples (Windows)" trace="false">
            <natural_server>127.0.0.1</natural_server>
            <natural_port>2900</natural_port>
            <natural_program>nwo.bat</natural_program>
            <natural_parameter>STACK=(LOGON SYSEXNJX;MENU-NJX)</natural_parameter>
        </session>
        <session id="Natural for Ajax Examples (Mainframe)" trace="false">
            <natural_server>myhost</natural_server>
            <natural_port>4711</natural_port>
            <natural_program>MENU-NJX</natural_program>
            <natural_parameter>STACK=(LOGON SYSEXNJX)</natural_parameter>
        </session>
        <session id="Local" trace="false">
            <natural_program>nwo.bat</natural_program>
        </session>
        <session id="127.0.0.1" trace="false">
            <natural_program>nwo.bat</natural_program>
        </session>
        <session id="Session template" trace="false">
            <natural_server></natural_server>
            <natural_port></natural_port>
            <natural_program></natural_program>
            <user id="" pwd=""/>
            <natural_parameter></natural_parameter>
        </session>
    </sessions>
</settings>

Note:
With Natural for Mainframes, it is recommended to specify the Natural program that starts the application in the element natural_program instead of passing it with the profile parameter STACK.

The first session that is defined in the configuration file has the name "Connect to Natural". This session is automatically preselected in the logon page. Since no further elements are defined for this session, all required input fields for logging on to a session are shown on the logon page and the user has to specify all required information.

Note:
The global section containing the timeout value is only available in a J2EE configuration file. See also Setting the Timeout.

To add a new session definition to the configuration file, you must add a new session element. It should have the following minimum entries:

<session id="your-session-name" trace="false">
  <natural_server>your-Natural-server</natural_server>
  <natural_port>port-ID-of-Natural-server</natural_port>
  <natural_program>Natural-program-name</natural_program>
</session>

Sessions

The following table explains the elements and attributes that can be used in the sessions section of the configuration file for adding a new session.

Element Name	Attribute Name	Description
`session`	`id`	Mandatory. A session name of your choice. On the logon page, the session name is provided in a drop-down list box.
`session`	`type`	Optional. The platform on which user ID and password are authenticated. Possible values: MF Natural for Mainframes. User ID and password can have a maximum of 8 characters. MF-NSC Natural for Mainframes with Natural Security. User ID and password can have a maximum of 8 characters. The user ID must comply with the Natural naming conventions for library names. OS Natural for UNIX, Natural for OpenVMS or Natural for Windows: User ID and password can have a maximum of 32 characters. When a domain is required, you have to specify it together with the user ID (in the form "`domain`\`user-ID`"). Default: "OS".
`session`	`protocol`	Optional. The current protocol version for the Natural Web I/O Interface is 6. The latest Natural versions automatically use the appropriate protocol version. For older Natural versions, it is required to define the appropriate protocol version in the configuration file: Natural versions 6.2.1 through 6.2.4 (UNIX) require protocol version 2. As of version 6.2.5 it is no longer required to define a protocol version. Natural versions 6.3.1 and 6.3.2 (UNIX) require protocol version 3. As of version 6.3.3, it is no longer required to define a protocol version. Natural versions up to version 4.2.3.2 (mainframe) require protocol version 3. As of version 4.2.3.3 and 4.2.4, it is no longer required to define a protocol version. Possible values: 2, 3, 4, 5 and 6. Default: 6.
`session`	`ssl`	J2EE only. Optional. If set to "true", a secure connection is established between the Natural Web I/O Interface client or Natural for Ajax on the application server and the Natural Web I/O Interface server. Important: If you want to use SSL with Natural for Mainframes, the type "MF" or "MF-NSC" must be defined; the type must not be "OS". The other way around, if you want to use SSL with Natural for Windows, UNIX or OpenVMS, the type must be "OS". Default: "false".
`session`	`trace`	Optional. Should only be set to "true" when requested by Software AG support. For further information, see Tracing. Default: "false".
`session`	`savesessionuser`	Natural for Ajax only. Applies only to applications that are designed as Application Designer workplaces. If set to "true" (default), the default behavior of `sharesessionuser` applies. If set to "false", the user credentials (user ID and password) are not saved in the Application Designer session and are therefore not available for an Application Designer subsession. An example for a workplace application is available under the following URL: http://`<host>`:`<port>`/cisnatural/servlet/StartCISPage ?PAGEURL=/njxdemos/wpworkplace.html where `<host>` and `<port>` are the host name and port number of your application server. Default: "true".
`session`	`sharesessionuser`	Natural for Ajax only. Applies only to applications that are designed as Application Designer workplaces. If set to "false" (default), the user credentials of the main Application Designer session are automatically used in an Application Designer subsession if the server and port of the subsession is the same as in the main session. If the server and port are not the same, the user has to specify the user ID and password in a logon dialog. If set to "true", the user credentials of the Application Designer main session are always used for all Application Designer subsessions on all involved servers - even if the server and port are different. Default: "false".
`user`	`id`	Optional. A valid user ID for the current machine. When this attribute is specified, the corresponding field does not appear on the logon page.
`user`	`pwd`	Optional. A valid password for the above user ID. When this attribute is specified, the corresponding field does not appear on the logon page.
`user`	`encrypted`	J2EE only. Used by the configuration tool which stores the password in encrypted form.
`user`	`ucase`	Optional. If set to "true", the input field for the user ID is in upper-case mode. Default: "false".
`natural_server`		The name or TCP/IP address of the server on which Natural and the Natural Web I/O Interface daemon (Natural for UNIX and Natural for OpenVMS) or the Natural Web I/O Interface server (Natural for Mainframes) or the Natural Web I/O Interface service (Natural for Windows) are running. When this element is specified, the corresponding field does not appear on the logon page.
`natural_port`		The TCP/IP port number on which the Natural Web I/O Interface daemon (Natural for UNIX and Natural for OpenVMS) or the Natural Web I/O Interface server (Natural for Mainframes) or the Natural Web I/O Interface service (Natural for Windows) is listening. When this element is specified, the corresponding field does not appear on the logon page.
`natural_program`		Natural for Mainframes The name of the Natural program or a command sequence that starts your application as you would enter it on the `NEXT` prompt. Example: `TEST01 data1,data2` Natural for UNIX The name of the UNIX shell script for starting the Natural application (a file similar to nwo.sh). Natural for OpenVMS The name of the Natural image file (for example, natural<version> or natural<version>.exe). Natural for Windows The name of the Windows command file (.bat) for starting the Natural application. When this element is specified, the corresponding field does not appear on the logon page.
`natural_parameter`		Optional. Parameters for starting the Natural application. This can be stack parameters, a parameter file/module or other Natural-specific information. Natural for Mainframes This element is used to pass dynamic Natural profile parameters to the session, for example: `SYSPARM=(MYPARMS) STACK=(LOGON MYAPPL)` Note: It is recommended to specify the Natural program that starts the application in the element `natural_program` instead of passing it with the profile parameter `STACK`. Natural for UNIX and Natural for Windows This element is used when the above shell script (UNIX) or command file (Windows) uses the parameter `$5` after "natural", for example: `PARM=MYPARM STACK=(LOGON MYLIB;MENU)` Natural for OpenVMS This element is used for starting a Natural application, for example: `BP=BPnode-name NLDCHK WEBIO=ON "STACK=(LOGON SYSEXT;MENU)"`
`natural_parameter`	`visible`	IIS only. If set to "true", a field containing the Natural parameters is shown on the logon page. Default: "false".
`language`		Natural for Ajax only. Sets the language to be used. You can specify a one-character code which corresponds to one of the language codes which can be set in the Natural system variable `*LANGUAGE`. See also Multi Language Management in the Natural for Ajax documentation. Default: English.
`double_click`		Natural for Ajax only. Applies only to Natural maps, not to rich GUI pages. The key that is to be simulated when double-clicking an output field. Possible values: "50" for the ENTER key (default). "1" through "12" for PF1 through PF12. "disabled" to disable the double-click behavior. Tip: When context-sensitive help has been defined for the output fields, it may be useful to define PF1. The help function will then be invoked when the user double-clicks an output field.
`pfkeys_display`		Natural for Ajax only. Applies only to Natural maps, not to rich GUI pages. The number of PF keys that are to be shown as buttons. Possible values: "0": only the named function keys are shown (default). "1": the function keys PF1 through PF12 are shown. "2": the function keys PF1 through PF24 are shown. "3": the function keys PF1 through PF36 are shown. "4": the function keys PF1 through PF48 are shown. The values "1" through "4" always shows buttons for all function keys, including those which do not have names. Each line always contains 12 function key buttons. The first line also contains a button for the ENTER key. Each function key button is always displayed at the same position.
`nattimeout`		J2EE only. Optional. Timeout for the response from the host. See Setting the Timeout.
`theme`		IIS only. The theme (style) that the web page is using. For a first test, you can use the theme with the name "3270Theme" (see Using Themes (IIS only)). When this element is specified, the corresponding field does not appear on the logon page. When themes are shown on the logon page, they are provided in a drop-down list box.
`style_sheet`		Natural for Ajax only. The name of the style sheet which determines the colors, fonts and PF key button style of the current session. See Using Style Sheets. When this element is specified, a fixed style sheet is used. In this case, the corresponding field does not appear on the logon page and the user is thus not able to select a different style sheet. Default: natural.css.
`screen`	`styleselect`	Natural for Ajax only. With Natural for Ajax, the users can switch to another style sheet during a running session. Optional. If set to "false", the users are no longer able to select another style sheet. Default: "true".
`screen`	`rows`	Applies only to Natural maps, not to rich GUI pages. Optional. The number of rows in the output window. Possible values: minimum 24, no upper limit. Default: 24. Not used by Natural for Mainframes which uses the profile parameter `TMODEL` instead.
`screen`	`columns`	Applies only to Natural maps, not to rich GUI pages. Optional. The number of columns in the output window. Possible values: minimum 80, no upper limit. Default: 80. Not used by Natural for Mainframes which uses the profile parameter `TMODEL` instead.
`screen`	`top`	IIS only. The top position of the output window inside the browser. Use "0" for the very top. This value is given in Natural units, not pixels.
`screen`	`left`	IIS only. The left position of the output window inside the browser. Use "0" for the very left. This value is given in Natural units, not pixels.
`screen`	`size`	IIS only. The size of the output window. Possible values: "normal", "small", "tiny" and "extratiny". Default: "normal".
`screen`	`pfkeypos`	IIS only. The position of the PF keys. Possible values: "bottom" and "right". Default: "bottom". Note: For J2EE, the position of the PF keys is determined in the style sheet. See Using Style Sheets.
`screen`	`showfkeynumbers`	Applies only to Natural maps, not to rich GUI pages. Optional. If set to "true", the PF key numbers are shown next to the PF keys. Default: "false".

If a field is not to appear on the logon page, you can specify the corresponding element or attribute as described above. To do so, you either specify a value for the attribute or element or you omit the value. For example, you can specify either of the following:

<natural_program></natural_program>

<natural_program>sysprof</natural_program>

In both cases, the corresponding field does not appear on the logon page.

Only when an element name or attribute name is not mentioned at all, the corresponding field is shown on the logon page.

Global Settings

The following table explains the global settings that can be defined in the global section of the configuration file.

Element	Description
`last_activity_timeout`	The timeout after the last activity of the user. See Setting the Timeout (J2EE only) below.
`trace_dir`	Optional. Location of a different trace directory. See Tracing below.
`trustfile_name`	J2EE only. Optional. The path to your trust file. See Trust Files (J2EE only) for further information.
`trustfile_password`	J2EE only. If your trust file is password-protected, the appropriate password is required. The password can only be specified with the configuration tool. It is stored in encrypted form.

Setting the Timeout (J2EE only)

You can set two different timeouts:

Last activity timeout
This is the timeout after the last activity of the user. It is defined with last_activity_timeout in the global section of the configuration file and is set in seconds. The default is 3600 seconds (1 hour). When the defined number of seconds has been reached, the session is closed.
```
<?xml version="1.0" encoding="utf-8"?>
<settings>
  <global>
     <last_activity_timeout>3600</last_activity_timeout>
  </global>
  <sessions>
  ...
```
Natural server timeout
This timeout defines the number of seconds that the client waits for an answer from Natural after an update of a page was sent to Natural. It is defined in the nattimeout element of a session definition. The default is 60 seconds. Normally, you need not change this default value. This timeout can be set individually for each session.
```
...
    <session id="Test (UNIX)" trace="false">
      <natural_server>Myserver2</natural_server>
      <natural_port>4321</natural_port>
      <natural_program>test.sh</natural_program>
      <nattimeout>60</nattimeout>
    </session>
...
```

Tracing

Tracing should only be enabled when requested by Software AG support. To enable tracing, you set the trace attribute in a session definition to "true". Example:

<session id="MySession" trace="true">

Default Trace Directory for J2EE

By default, the trace files are written to the directory which has been set by the Java property java.io.tmpdir. On Windows, this is normally the environment variable TMP for the user who started the application server. On UNIX, this is normally /tmp or /var/tmp.

You can also set this property in the start script for the application server. The following examples apply to JBoss.

Example for Windows (run.bat):

set JAVA_OPTS=%JAVA_OPTS% -Djava.io.tmpdir=C:\temp

Example for UNIX (run.sh):

set JAVA_OPTS="$JAVA_OPTS -Djava.io.tmpdir=/tmp

Default Trace Directory for IIS

By default, the trace files are written to the Software AG\Natural WebIO\Traces directory. The path to this directory depends on the operating system:

Windows XP
<drive>:\Documents and Settings\<pc-name>\ASPNET\Local Settings\Application Data\Software AG\Natural WebIO\Traces
Windows 2003 Server
<drive>:\Documents and Settings\Default User\Application Data\Software AG\Natural WebIO\Traces
Windows Vista
<drive>:\Windows\ServiceProfiles\NetworkService\AppData\Local\Software AG\Natural WebIO\Traces

Defining a Different Trace Directory

It is possible to define a different trace directory by defining the element trace_dir in the global element of the configuration file. Example:

<global>
  <trace_dir>E:\mytracedir</trace_dir>
</global>

When a different trace directory is not defined, the default trace directory will be used.

Users and Passwords

It is possible to predefine Natural users and their passwords. This is done in the users section of the configuration file.

The syntax is as follows:

<settings>
  ...
  <users>
    <user id="user1" pwd="password1"/>
    <user id="user2" pwd="password2"/>
    <user id="user3" pwd="password3"/>
  </users>
  ... 
</settings>

When a Natural page is opened with a URL that specifies a user in the URL parameter natuser, the specified user is matched against the list of users in the configuration file. When the specified user is defined in the configuration file, the corresponding password is used to authenticate the user when the Natural session is started. See also Starting a Natural Application with a URL.

Example

When the following URL is used, the password defined for "user1" is used (which is "password1" in the above syntax example):

Natural Web I/O Interface Client
http://myhost:8080/natuniweb/natural.jsp?natuser=user1...
Natural for Ajax
http://myhost:8080/cisnatural/servlet/StartCISPage?PAGEURL=/cisnatural/NatLogon.html&xciParameters.natuser=user1 ...

Note:
With Natural for Ajax, the URL parameters have the prefix xciParameters.

SEARCH CONTENTS | PDF PAGE PDF BOOKS | HOME UP PREV NEXT