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

Overview of Configuration File Elements

This document covers the following topics:


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:

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>

Top of page

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>

or

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

Top of 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:

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.

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:

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.

Top of page

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

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

Top of page