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:

<?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>

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 above 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 Java EE 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 7. 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, 6, and 7. Default: 7.
`session`	`ssl`	Java EE only. Optional. If set to "true", a secure connection is established between the Natural Web I/O Interface client 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".
`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`	Java EE 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".
`nattimeout`		Java EE 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.
`screen`	`rows`	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`	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 Java EE, the position of the PF keys is determined in the style sheet. See Using Style Sheets.
`screen`	`showfkeynumbers`	Optional. If set to "true", the PF key numbers are shown next to the PF keys. Default: "false".
`screen`	`checknumfields`	If set to "true" (default), numeric input fields are validated. In this case, only the following characters are allowed in numeric input fields (in addition to the numbers "0" through "9"): `blank` + (plus) - (minus) _ (underscore) , (comma . (period) ? (question mark) If set to "false", numeric input fields are not validated.

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 (Java EE only) below.
`trace_dir`	Optional. Location of a different trace directory. See Tracing below.
`trustfile_name`	Java EE only. Optional. The path to your trust file. See Trust Files (Java EE only) for further information.
`trustfile_password`	Java EE 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 (Java EE 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 Java EE

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):

http://myhost:8080/natuniweb/natural.jsp?natuser=user1...