Natural under openUTM - Part 1

This part of the Natural openUTM Interface documentation covers the following topics:


Structure of the Natural openUTM Interface

The Natural openUTM Interface consists of the macros NATUTM, BS2STUB and NURENT and of several utility programs, which enable special requirements to be accommodated.

Non-Reentrant Part - Macro NATUTM

The macro NATUTM is used to generate the non-reentrant part of the Natural openUTM Interface to suit the particular application based on appropriate operand definitions for the parameters. The default values of the parameters are chosen so that, in general, they can be used without alteration for an initial generation.

The front-end part is present once per openUTM task and consists principally of the following components:

  • KDCROOT of openUTM,

  • assembled macro NATUTM,

  • assembled macro BS2STUB,

  • format exit module FREXIT,

  • Adabas interface module.

Reentrant Part - Macro NURENT

The reentrant part of the Natural openUTM Interface is generated by assembling the macro NURENT. This is linked with the reentrant part of the Natural openUTM application. If a shared Natural nucleus is to be used, the generated NURENT module must be linked to the front-end part.

The reentrant part of the Natural openUTM application consists of the following components:

  • NATINV (address module) (must be included as the first module),

  • Natural nucleus,

  • Natural buffer pool manager,

  • NURENT (CSECT name of the assembled macro NURENT),

  • NATSWPMG (Natural swap pool manager),

  • Natural parameter module,

  • NATLAST (end definition) (must be included as the last module).

The reentrant part of the Natural openUTM Interface is only present once in a Natural openUTM application (reentrant) if it is loaded into class 4 storage or into a common memory pool in class 6 storage. The latter is recommended.

A further possibility is to link the reentrant part with the non-reentrant front-end part of the Natural openUTM application.

The Natural and openUTM macro libraries are required when assembling NATUTM, NURENT and all utility programs.

Formatting Messages - FREXIT

Format Exit Module FREXIT

Natural uses its own formatting routines when sending messages to the VDU (openUTM format type "minus"). Messages are processed by the format exit module FREXIT (transfer from logical to physical I/O domain and vice versa, producing RESTART and LOGOFF messages, etc.).

The module FREXIT must be linked with the front-end part of the Natural openUTM application and it must be defined as the format exit module when generating KDCROOT or KDCDEF.

Example:

PROGRAM FREXIT,COMP=ASSEMB
EXIT PROGRAM=FREXIT,USAGE=FORMAT

The program FREXIT supports the format name -END for the LOGOFF message. See the description of the parameter LOFFMAP of the macro NATUTM. No more openUTM administration commands (KDCINF, KDCSHUT N, etc.) can be entered after the format name -END has been used and the LOGOFF message has been output. The LOGOFF message is output in formatted mode; however, openUTM expects administration commands in line mode and therefore any input results in a syntax error. After this error message has been received, all valid administration commands can be input with the administration ID. The messages for asynchronous messages, RESTART and LOGOFF can be changed to suit specific requirements by changing the appropriate text constants in the program FREXIT.

The program FREXIT has a user exit INPTEX that can be satisfied by the utility program INPTEX. See the descriptions of the programs NATDUE and INPTEX in the section Utility Programs.

Another user exit in program FREXIT is TRMIOEX, which can be used for input/output message control.

FREEXIT Macro

The macro FREXIT contains the following parameters:

AMSG=ASAP If there are any "free-running" (asynchronous) messages, a further dialog with Natural is only possible if these messages have previously been read with the command KDCOUT.
AMSG=WAIT (Default) A further dialog with Natural is possible even if any "free-running" messages have not yet been read with the command KDCOUT.
KDCDISP=YES (Default) KDCDISP is supported by a restart message with an automatic ENTER. The last screen output will be refreshed.
KDCDISP=NO KDCDISP is supported by a restart message with a following refresh screen.

If you want to change a default operand of macro FREXIT, you must reassemble FREXIT.

Embedding Natural in an openUTM Application

Embedding Natural in an openUTM Application

Common Memory Pools

The following topics are covered:

Natural Buffer Pool under openUTM

Natural requires a common area into which Natural programs can be read from the Adabas database and where they are also executed. This common memory pool is the Natural buffer pool.

You use the parameters of macro ADDON (which assembles module BS2STUB) either to define a local Natural buffer pool, or to define the connection to a global Natural buffer pool. For more information, see ADDON Macro in the Natural Operations documentation.

You use the parameters of module CMPSTART to define a global Natural buffer pool. For more information on this module, see CMPSTART Program in the Natural Operations documentation.

To display statistical information about the buffer pool, use the Natural utility SYSBPM; see the Natural Utilities documentation.

Natural Swap Pool under openUTM

A Natural user work area is required for each online Natural user. This user work area must be in the computer's main store whenever the user initiates any form of dialog transaction. To reduce the frequency with which the user work area is rolled out to the swap file and rolled in again, it is possible to set up a Natural Swap Pool. For details on the swap pool, please refer to Natural Swap Pool in the Natural Operations documentation.

You use the parameters of macro ADDON (which assembles the module BS2STUB) either to define a local Natural swap pool, or to define the connection to a global Natural swap pool. For more information, see ADDON Macro in the Natural Operations documentation.

You use the parameters of module CMPSTART to define a global Natural swap pool. For more information, see CMPSTART Program in the Natural Operations documentation.

Loading Natural in a Common Memory Pool - Natural Load Pool

The reentrant part of the Natural openUTM application can be loaded in class 4 storage or linked with the front-end part of the Natural openUTM application. Alternatively, it can be loaded in a common memory pool in class 6 storage. This last method is recommended. The amount of storage required in the common memory pool depends upon the size of the linked reentrant part of the Natural openUTM application; this can be read from the linker listing. The parameter NUCNAME of macro NATUTM is used if Natural is to be loaded into a common memory pool in class 6 storage. This parameter specifies the name of the linked, reentrant Natural nucleus. This is also the name of the Natural load pool. See also Parameters of Macro NATUTM.

You use the parameters of macro ADDON (which assembles module BS2STUB) either to define a local Natural load pool, or to define the connection to a global Natural load pool (shared Natural nucleus). For more information, see ADDON Macro in the Natural Operations documentation.

You use the parameters of module CMPSTART to define a global Natural load pool (shared Natural nucleus). For more information, see CMPSTART Program in the Natural Operations documentation.

Natural Monitor Pool

The Natural Monitor utility requires a common memory pool for data storage. This common memory pool is allocated when the Monitor utility is activated, and released when the Monitor utility is deactivated.

You use the parameters of macro ADDON (which assembles module BS2STUB) either to define a local Natural monitor pool, or to define the connection to a global Natural monitor pool. For more information, see ADDON Macro in the Natural Operations documentation.

You use the parameters of module CMPSTART to define a global Natural monitor pool. For more information, see CMPSTART Program in the Natural Operations documentation.

For details on the Monitor utility, see SYSTP Utility in the Natural Utilities documentation.

Other Storage Areas

Natural User Thread

For each openUTM task a storage area with a size of MAXSIZE is generated. This area contains the Natural user area in decompressed form.

Natural User Work Area Asynchronous Write Buffer

The Natural user work area can be written out either asynchronously ("write without wait") or synchronously ("write with wait").

If the asynchronous option is used (this is the default option), a write buffer having the size of defined operand for parameter ROLLTSZ is generated for each openUTM task. Using this technique, the compressed user work area is copied from the swap pool into the write buffer, the asynchronous write is started and processing can continue immediately. This option gives better performance, but at the cost of increased storage.

If roll-outs are to be performed synchronously, the parameter ROLLACC must have the value UPAM-SY. In this case, it is not necessary to allocate a write buffer. Processing is suspended until the user work area has successfully been written to the swap file.

Natural User Area for Asynchronous Transactions

A storage area of MAXSIZE is allocated for each asynchronous transaction in a Natural openUTM application (Natural user work area for this transaction). It is released at the end of the transaction. The Natural swap pool is not used to store the user work area associated with asynchronous transactions. Every Natural program that runs asynchronously must end with a TERMINATE statement; that is, the openUTM DC transaction is ended with PEND 'FI(NISH)'. This applies to asynchronous transactions both within an application and between two Natural openUTM applications; see also Asynchronous Transaction Processing under openUTM.

Natural Roll File - LINK=PAMNAT

A PAM file is required for swapping the Natural user work areas. Writing to and reading from this file is done by physical chained PAM-I/O. However, this is only possible as long as the swap file does not cross an extent boundary. This can be checked using SPCCNTRL.

The LINK name of the Natural swap file is PAMNAT. The size of the roll file can be computed as follows:

NP=([(MS+4+31)/32]*32*NT+4)/2

where:

NP Size of data set in PAM pages
MS Parameter ROLLTSZ in Kbytes, rounded up to next even number
NT Number of terminals online

Example:

ROLLTSZ = 80 KBytes (per user), number of terminals online = 40

Size of data set = ( [ ( 80 + 4 + 31 ) / 32 ] * 32 * 40 + 4 ) / 2
                = ( [ 115 / 32 ] * 32 * 40 + 4 ) / 2
                = ( [ 3.59375 ] * 32 * 40 + 4 ) / 2
                = ( 3 * 32 * 40 + 4 ) / 2
                = 3844 / 2
                = 1922 PAM pages

FILE statement:

/FILE NATUTM.SWAPFILE,LINK=PAMNAT,SPACE=(1922,96)

When a local swap pool is used, each Natural openUTM application requires its own Natural swap file. When a user logs on to the application, the Natural openUTM Interface checks whether there is sufficient space available for the new user in the Natural roll file. If there is not enough space, error message NUS0033 is output.

When a global swap pool is used, all Natural openUTM applications which are connected to the same global swap pool must use the same Natural roll file.

Generating KDCROOT

The following Natural-specific definitions must be entered when generating KDCROOT for a Natural openUTM application:

MAX KB=400,SPAB=8192,NB=5120,TRMSGLTH=5120 (see Note 1)
PROGRAM NUSTART,COMP=ASSEMB                (see Note 2)
PROGRAM NUERROR,COMP=ASSEMB                (see Note 2)
TAC NAT,PROGRAM=NUSTART,EXIT=NUERROR       (see Note 2)
EXIT PROGRAM=FREXIT,USAGE=FORMAT           (see Note 3)
PROGRAM FREXIT,COMP=ASSEMB                 (see Note 3) 
Note  
1 The area needed for the openUTM KB has a minimum length of 400 bytes. The necessary KB length for operand KB=nnn in the MAX parameter of KDCDEF must be calculated as follows:

Fixed KB length is 400 bytes
+ length of KB user extension (parameter KBUSEXT)
+ length of dynamic parameter save area (parameter SVDYPRM)
+ (only if MULTI-PASS is used) length of session key areas, which has to be calculated as follows: n *72, where n is the number of parallel session minus 1

The openUTM I/O areas NB and TRMSLGTH need a length of 5120 bytes.

2 In a Natural openUTM application there is as a rule only one user-specific openUTM partial program.

This program is the front-end part of the Natural openUTM Interface, which must be defined in the adequate parameters of KDCDEF under the name specified in the operand of the parameter CSECT of macro NATUTM (default = NUSTART).

Any number of openUTM transaction codes can be assigned, providing the naming rule is observed.

The name of the DC transaction exit routine NUERROR must be defined for the front-end part of the Natural openUTM Interface and for each other openUTM partial program.

3 The format exit module FREXIT must be defined with the parameters EXIT and PROGRAM.

All other definitions relating to the generation of KDCROOT are either specific to openUTM or else they are dependent upon the values defined in the operands of the appropriate parameters of macro NATUTM.

Defining the openUTM Resources - KDCDEF

The following Natural-specific points must be observed when defining the openUTM resources:

Special Definition for Type 9755/9756 Terminals

The TERMN operand of the PTERM command must be set to the value X1 or FG for 9755-type terminals and to the value X2 for 9756-type terminals. These are special values and not described in the appropriate table in the openUTM documentation.

For all other types of terminals, the TERMN operand must be set to the value shown in the tables.

Example:

PTERM ss19,lterm=ltdf1900,pronam=vr,ptype=t9755,TERMN=X1

Treatment of K Keys and F Keys

The Natural openUTM Interface supports the function keys K1, K2, K3, K4, F1, F2, F3, F4 and F5 (for P keys). The function key which has been pressed can be identified by means of the openUTM return code, which must be defined using the SFUNC statement of KDCDEF:

SFUNC K1,RET=26Z
SFUNC K2,RET=27Z
SFUNC K3,RET=28Z
SFUNC K4,RET=29Z
SFUNC F1,RET=21Z
SFUNC F2,RET=22Z
SFUNC F3,RET=23Z
SFUNC F4,RET=24Z
SFUNC F5,RET=25Z
SFUNC nn,RET=nnZ 

(for the PRKEY, see the parameter PRKEY)

Using other function keys or using valid function keys that have not been defined in KDCDEF results in an error message.

Support of 3270-Type Terminals

In an appropriate system configuration, 3270-type terminals are supported by the Natural openUTM Interface.

This means that terminal types of the 975n series (974n, 975n and 976n) as well as terminal types of 3270 devices can be connected to a Natural openUTM application. Natural adjusts screen output to the specific terminal type used. 3270-type terminals have to be defined as such to KDCDEF in the PTERM command (see the openUTM documentation).

For the support of function keys, the SFUNC statements of KDCDEF have to be defined as follows:

975n-Type Key 3270-Type Key openUTM Return Code
F1 PF1 21Z
F2 PF2 22Z
F3 PF3 23Z
F4 PF4 24Z
F5 PF5 25Z
K1 PA1 26Z
K2 PA2 27Z
K3 PF6 + PF13 28Z
K4 PF7 + PF14 29Z
K5 PF8 + PF15 30Z
K6 PF9 + PF16 31Z
K7 PF10 + PF17 32Z
K8 PF11 + PF18 33Z
K9 PF12 + PF19 34Z
K10 PF20 35Z
K11 PF21 36Z
K12 PF22 37Z
K13 PF23 38Z
K14 PF24 39Z

Support of TTY Terminals

For terminals which are to be used in TTY mode, the TERMN operand of the PTERM command must be set to TERMN=X9.

The following restrictions apply to TTY mode:

  • Asynchronous transaction processing is not supported.

  • MULTI-PASS is not supported.

openUTM DC-Transaction Exit Routine NUERROR

An openUTM DC-transaction exit routine is defined in the front-end part of the Natural openUTM Interface. This routine is called at the beginning of a DC transaction, when a DC transaction is restarted, at normal termination and at abnormal termination (PEND ER). The user exit UVGEXIT can be used in any of these circumstances.

In the case of abnormal termination, the affected user is deleted from the internal terminal control table, the Natural recovery procedures are executed and the user's user area is released from the swap pool directory if necessary.

The DC-transaction exit routine NUERROR must be defined in the adequate parameters of KDCDEF for the front-end part of the Natural openUTM Interface (generation of KDCROOT); see also Generating KDCROOT.

openUTM Startup Function

If the user exit STARTEX (default value of parameter STRTALL ) is to be used, EXIT PROGRAM=NUSTART,USAGE=START must be defined in the KDCDEF parameter for the front-end part of the Natural openUTM Interface.

One of the effects of this is that the task initialization routines (allocation of common memory pools, loading Natural, etc.) are activated immediately following the start of each openUTM task. Errors that occur are output on the console and all users are sent an appropriate message; if SYSLST=YES, errors are also output to SYSLST.

If the openUTM startup function is not used, the openUTM task(s) are not initialized until they are activated when a user logs on. If an error occurs under these circumstances, the error message is sent to the terminal that caused the error. All other users are given an appropriate message when they try to log on to the application.

openUTM Shutdown Function

If you want to use the shutdown function of openUTM to obtain statistics about the Natural swap pool and Natural user threads, you have to use the user exits SHUTEX1 and/or SHUTEX2 (default values of parameters SHUTALL and SHUTLST). The statistics collected by the Natural openUTM Interface are then output when the last openUTM task terminates.

You activate the user exits by defining the following in the KDCDEF parameter (KDCROOT) for the front-end part of the Natural openUTM Interface:

EXIT PROGRAM=NUSTART,USAGE=SHUT

If the openUTM shutdown function is not used, the user exits defined with SHUTALL and SHUTLST cannot be used and the statistics are not available.