Natural under TIAM

This document describes the functionality of the Natural TIAM interface (product code NRT) and the operation and individual components of Natural in a TIAM environment.

This following topics are covered:

Related Documents:


Structure of the Natural TIAM Interface

The Natural TIAM interface consists of two components:

  • the non-reentrant front-end part

  • the reentrant part NATRENT (default)

Both components are elements of the macro NAMTIAM and are generated with two separate assembly runs; see also Parameters in Macro NAMTIAM, parameter CODE.

The front-end part is generally linked with the Adabas interface module ADALNK to form the initialization routine which is run once only during the establishment of a Natural under TIAM session. During the initialization phase, based on the operand values of the corresponding parameters, various functions, for example, the establishment/connection to the Natural buffer pool, loading or linking of the Natural nucleus, establishing the physical terminal buffer, are executed. The front-end part must be loaded for each user (task).

The reentrant part NATRENT is linked as a modular element to the Natural nucleus and contains various entry points for TP system dependent routines (memory management, terminal communication, etc.). If a shared Natural nucleus is to be used, the generated NATRENT module must be linked to the front-end part.

The Natural nucleus is completely environment-independent (shared code) and must be loaded only once for all users.

Parameters in Macro NAMTIAM

The macro NAMTIAM has to be generated twice: for the front-end part of the Natural TIAM Interface and for the reentrant part. For which part it is generated is determined by the parameter CODE in the NAMTIAM macro.

For the generation of the front-end part and the reentrant part, a label can be provided in the macro call to NAMTIAM. This label defines the CSECT name, under which the module is stored in the module library. If no label is specified, the name for the front-end part is NATFRONT and the name for the reentrant part is NATRENT.

Example of NAMTIAM Macro for Front-End Part:

NATTESTF NAMTIAM CODE=FRONT,NUCNAME=NB2RENT,PARMOD=31

In this example, the CSECT name of the front-end part is defined as NATTESTF.

Example of NAMTIAM Macro for Reentrant Part:

NATTESTR NAMTIAM CODE=RENT,CLRKEY=K4,PARMOD=31

In this example, the CSECT name of the reentrant part is defined as NATTESTR.

Parameters:

The individual parameters which can be specified in macro NAMTIAM are explained below:

ADACOM | ADDBUFF | APPLNAM | ATTKEY | CLRKEY | CODE | CURPRO | DELETE | DYNPAR | HCASK | ILCS | LF | LINK | LINK2/LINK3/LINK4 | NUCNAME | PARMOD | PFK | REFRKEY | REQMLOC | SYSDTA | TIMESTMP | TRACE | TTYLS | TTYPS | T975X | USERID |

ADACOM - Usage of Adabas Link Module

This parameter applies to the generation of the Natural environment-dependent nucleus (see in the Installation documentation). It determines which Adabas link module is to be used. Possible values are:

Value: Explanation:
ADAUSER The module ADAUSER is linked to the environment-dependent nucleus.
ADABAS The module ADAUSER is linked to the environment-dependent nucleus.
ADALNK

The module ADALNK is linked to the environment-dependent nucleus or the modules ADALNK and SSFB2C are linked to the environment-dependent nucleus.

This is the default value.

In any case a resolve to the Adabas module library has to be given in the linkage step for the environment-dependent nucleus.

ADDBUFF - Additional Number of Pages

This parameter applies to the generation of the front-end part. It determines the additional number of pages for the terminal I/O buffer. Possible values are:

Value Explanation
1 to 8 or no operand Additional number of pages in 4 KB units.
no operand By default, no operand is specified.

APPLNAM - Application Name

This parameter applies to the generation of the front-end part. Possible values are:

Value Explanation
name The name (maximum 8 characters) of the Natural TIAM application. This name is part of the serialization ID when the Natural TIAM task is initialized.
NATTIAM This is the default value.

ATTKEY - Interrupt Mode

This parameter applies to the generation of the reentrant part. Possible values are:

Value Explanation
ON Pressing the K2 key on your terminal is intercepted by an STXIT routine. Natural creates an ATTENTION INTERRUPT and returns a NAT1016 error message.
OFF

Pressing the K2 key leads to a normal BS2000/OSD interrupt.

This is the default value.

CLRKEY - Alternate Clear Key

This parameter applies to the generation of the reentrant part.

This parameter can be used to define an alternate CLEARKEY in addition to LSP and DUE1. Possible values are:

Value Explanation
K1 to K4, F1 to F4, DUE2 Name of alternate CLEARKEY.
K4 This is the default value.

CODE - Generation Mode

This parameter applies to the generation of both the front-end and reentrant parts.

It determines which part of the Natural TIAM Interface is to be generated. Possible values are:

Value Explanation
FRONT

Indicates the generation/assembly of the front-end part.

This is the default value.

RENT

Indicates the generation/assembly of the reentrant part.

CURPRO - Cursor Positioning on Protected Fields

This parameter applies to the generation of the non-reentrant part.

It controls whether the cursor can be positioned to a protected field. Possible values are:

Value Explanation
ON

The cursor cannot be positioned to a protected field.

This is the default value.

OFF The cursor can also be placed in a protected field (for example, for field-specific help functions).

DELETE - Deletion of Dynamically Loaded Programs

This parameter applies to the generation of the reentrant part. Possible values are:

Value Explanation
ON

The setting of the profile parameter DELETE in the Natural parameter module determines whether dynamically loaded non-Natural programs are unloaded at the end of the Natural program in which they are loaded or whether they are unloaded when command mode is entered.

This is the default value.

OFF A dynamically loaded non-Natural program once loaded is kept for the duration of the whole Natural session.

DYNPAR - Reading of Dynamic Parameters

This parameter applies to the generation of the non-reentrant part. Possible values are:

Value Explanation
DIALOG The dynamic parameters are read from terminal input.
YES The dynamic parameters are read from terminal input. YES has the same effect as DIALOG; it is kept for compatibility reasons.
YES,LC or DIALOG,LC Same as DIALOG or YES. However, the parameter string is not translated to upper case.
SYSDTA The dynamic parameters are read from SYSDTA.
SYSIPT The dynamic parameters are read from SYSIPT.
FILE

The dynamic parameters are read from a sequential file. The input of this SAM file is interpreted as one single text string, which means that the individual entries must be separated from each other by a comma, even at the end of a line. Such a parameter file must be defined with a FILE command by using the LINK parameter CMPRMIN.

See also the example given below.

NO

No dynamic parameters are read from terminal input.

This is the default value.

Example for DYNPAR=FILE:

/FILE NAT.PARAMS,LINK=CMPRMIN

HCASK - Hardcopy Output Device Specification

This parameter applies to the generation of the reentrant part.

It determines whether a user is asked to specify an output device each time he or she produces a hardcopy (with terminal command %H). Possible values are:

Value Explanation
ON

The user is asked to specify a device for each hardcopy.

This is the default value.

OFF The device used for the previous hardcopy is used again.

ILCS - Invoking 3GL Subprograms

This parameter applies to the generation of the reentrant part. Possible values are:

Value Explanation
CRTE 3GL subprograms are invoked with common runtime environment convention. To be able to do so, the ILCS initialization routine IT0SL# must be linked to the Natural environment-dependent nucleus (see the Installation documentation), as shown below:
INCLUDE IT0SL#,SYSLNK.CRTE.010
RESOLVE,SYSLNK.CRTE.010
YES 3GL subprograms are invoked with enhanced ILCS linkage convention. To be able to do so, the ILCS initialization routine IT0INITS must be linked to the Natural environment-dependent nucleus (see the Installation documentation), as shown below:
INCLUDE IT0INITS,SYSLNK.ILCS
RESOLVE,SYSLNK.ILCS
NO

Standard processing applies.

This is the default value.

LF - Line Advance Control Character

This parameter applies to the generation of the non-reentrant part.

With this parameter you specify the control character to be used for line advance when printing on the local printer. Possible values are:

Value Explanation
X'zz' Control character.
X'25' This is the default value.

LINK - Linking Programs and Modules

This parameter applies to the generation of the non-reentrant part. Possible values are:

Value Explanation
name (name, name ,...) The name(s) of programs and modules that are called from Natural programs and linked with the non-reentrant part must be specified with this parameter. See below.

No default value is provided.

Conversely, the programs and modules whose names are specified must be linked with the non-reentrant part, otherwise the application is put into status SYSTEMERROR and all users are rejected with an error message.

A TABLE macro call is performed for the specified programs and modules, which enters their load addresses into the dynamic loader's link table. It is therefore not necessary to dynamically load these programs when they are called by Natural programs.

Example:

LINK=PROG1
LINK=(PROG1,PROG2,MODUL111)

LINK2/LINK3/LINK4 - LINK Parameter Operand Extensions

These parameters apply for the generation of the non-reentrant part.

The parameters LINK2, LINK3 and LINK4 are an extension of the LINK parameter. Since an operand definition cannot be longer than 127 characters (including parentheses), these parameters are provided for cases where the operand of parameter LINK would be too long. The syntax is analogous to that of LINK. Possible values are:

Value Explanation
name (name, name,...) The name(s) of programs and modules that are called from Natural programs and linked with the non-reentrant part must be specified with this parameter.

No default value is provided.

Examples:

NAMTIAM LINK=(PROG1,PROG2,...), 
                  LINK2=(PROG54,...)
NAMTIAM LINK=(PROG1,PROG2,PROG3,PROG4)

NUCNAME - Name of Reentrant Natural Module

This parameter applies to the generation of the non-reentrant part.

With this parameter you specify the name of the bounded, reentrant Natural module. You must use this name for the Natural pool and load information in macro ADDON (BS2STUB assembles macro ADDON). Possible values are:

Value Explanation
name The name of the bounded, reentrant Natural module.
NB2RENT This is the default value.

PARMOD - Application Address Mode and Location

This parameter applies to the generation of both the non-reentrant part and the reentrant part.

The first part of this parameter nn is used to define an addressing mode (24-bit or 31-bit mode) for the Natural TIAM application.

The second part of this parameter loc is used to define the front part location of the Natural TIAM application. If you load the Natural environment-dependent nucleus (see the Installation documentation), this must be defined in the environment-dependent nucleus link procedure as follows:

LOADPT=*XS
LOADPT=X'address'

Possible values are:

Value Explanation
nn 24/31
loc BELOW/ABOVE
(31,ABOVE) This is the default value.

Example:

/EXEC TSOLINK
PROG NATvrs,FILENAM=NATvrs,LOADPT=*XS,...
TRAITS RMODE=ANY,AMODE=31
INCLUDE..../* 
PARMOD=(nn,loc) MUST BE IDENTICAL IN THE NON-REENTRANT AND REENTRANT PART

where vrs represents the relevant product version.

PFK - Function Key Mode

This parameter applies to the generation of the non-reentrant part. It is used to set one of the following function-key modes:

Value Explanation
(KN, y) Either literals %K1 to %K20 and send-key code or send-key codes F1 to F20 are loaded to the function keys; this depends on the device type.

Where y can be either L or N: - "L" means that the function keys are loaded; N means that the corresponding mode is activated, but function keys will not be loaded.

(KO, y) The literals 01 to 20 and send-key code F5 are loaded to the function keys.
(KS, y) The literals A to T and send-key code F5 are loaded to the function keys; in addition, with every output message a dummy field is generated at the last two positions of the screen. This dummy field is used to receive and pass the key value.
OFF No function key mode is generated.
(KS,L) This is the default value.

REFRKEY - Refresh Key

This parameter applies to the generation of the reentrant part.

It can be used to define a function key. If this function key is pressed, the last full Natural screen is refreshed. Thus it is possible to continue the dialog with Natural after the screen has been overwritten by messages from the operator or the operating system. Possible values are:

Value Explanation
K1 to K14 Function key designation.
NO No function key defined.
K14 (keys ESC + :) This is the default value.

The send-key code is not passed to the Natural application. The interface sets the Natural key code to ENTER.

The key defined with the REFRKEY parameter must be different from the one defined with the CLRKEY parameter.

REQMLOC

This parameter applies to the generation of both the non-reentrant part and the reentrant part in 31-bit mode (PARMOD=31).

It determines where the requested Natural work areas are to be allocated via request memory by the system. Possible values are:

Value Explanation
BELOW All areas are requested below 16 MB.
ABOVE All areas are requested above 16 MB.
RES

All areas are requested depending on the location of the reentrant part.

This is the default value.

The REQMLOC parameter corresponds to the LOC parameter of the BS2000/OSD system macro REQM.

SYSDTA

This parameter applies to the generation of the front-end part. Possible values are:

Value Explanation
PRIMARY

After reading of dynamic Natural parameters from SYSDTA, SYSDTA is set to SYSFILE SYSDTA=(PRIMARY).

This is the default value.

SYSCMD After reading of dynamic Natural parameters from SYSDTA, SYSDTA is set to SYSFILE SYSDTA=(SYSCMD).

TIMESTMP

This parameter applies to the generation of the non-reentrant part.

It determines the timebase for all system variables and timestamps derived from the machine time.

Possible values:

Value Explanation
TIMESTMP=UTC Timebase is UTC (former GMT).

This is the default.

TIMESTMP=LOCAL Timebase is the local machine time

TRACE - Trace File Number and Print Record Length

This parameter applies to the generation of the reentrant part.

With this parameter, you specify the number of a trace file and the maximal length of a trace print record. Possible values are:

Value Explanation
(nn ,ll) nn : 01...99 nn is the number for the SYSLSTnn trace file.
ll : 71...132 ll is the maximal length in characters of a trace print record.
(99,71) This is the default value.

If any external Natural trace function is active, the trace records will be written to SYSLSTnn. In this case, the Natural TIAM driver creates the following trace file:

Example:

NATURAL.TRACE.TIAM.TTTT,SPACE=(30,3)
SYSFILE SYSLSTnn=NATURAL.TRACE.TIAM.TTTT
/* TTTT is the task sequence number

Before the Natural TIAM session is terminated, the trace file will be closed as follows:

SYSFILE SYSLSTnn=(PRIMARY)

TTYLS - Line Length for Telex Machine

This parameter applies to the generation of the non-reentrant part.

With this parameter you can adjust Natural's physical line length to different paper formats used with a telex machine. Possible values are:

Value Explanation
nn nn specifies the physical line size for TTY devices.
80 This is the default value.

TTYPS - Page Size for Telex Machine

This parameter applies to the generation of the non-reentrant part.

With this parameter you can adjust Natural's physical page size to different paper formats used with a telex machine. Possible values are:

Value Explanation
nn nn specifies the physical page size (number of lines) for TTY devices.
24 This is the default value.

T975X - Device-Type-Specific Message Optimization

This parameter applies to the generation of the non-reentrant part.

It is used to determine for which device types messages are to be optimized when using data stations which were generated in PDN as 9750. Possible values are:

Value Explanation
9750, 9755, 9756 or 9763 Device type.
9750 This is the default value.

USERID - Natural User ID

This parameter applies to the generation of the non-reentrant part. Possible values are:

Value Explanation
SYSTEM
or
YES
The Natural user ID is created by using the BS2000/OSD user ID.
USER
or
NO

The Natural user ID is created by using the job name; that is, the /.JOBNAME of the LOGON command. If no BS2000/OSD job name has been specified with the LOGON command, the Natural user ID is created as with USERID=SYSTEM or USERID=YES.

This is the default value.

Common Memory Pools under TIAM

You use the macro ADDON (which assembles module BS2STUB) either to generate the local common memory pools, or to define attachment to the global common memory pools.

The programs CMPSTART and CMPEND start and stop global common memory pools. They are described in the section Global Common Memory Pools in the Natural Operations documentation.

A Natural TIAM application needs the following common memory pools:

  • Natural load pool
    The linked reentrant part of Natural is loaded into this common memory pool.

  • Natural buffer pool
    The executable Natural programs and the Natural global data areas are loaded into this common memory pool. Those compiled Natural programs whose objects are reentrant are executed from this memory pool.

  • Natural/Adabas nucleus communication memory pool
    Natural connects to an additional common memory pool which is established by Adabas during startup.

The sum of the memory assigned to common memory pools, as well as the local area of the Natural environment-dependent nucleus (see the Installation documentation), must completely fit into the virtual user address space.

If the Adabas pool exceeds the user address space, error message 148 is produced during the OP command execution. At the beginning of the session, Natural issues the error message NAT8148 and, in the following session termination, the message NAT9989 (incorrect system file).

Environment-Independent Nucleus

For TIAM applications, it is possible to use a common environment-independent nucleus. The rules that apply in this case are documented in the relevant section in the Natural Installation documentation.