This part of the Natural openUTM Interface documentation covers the following topics:
The Natural openUTM Interface consists of the macros
NATUTM, BS2STUB and NURENT and of
several utility programs, which enable special requirements to be
accommodated.
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.
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.
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.
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.
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.
The following topics are covered:
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.
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.
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.
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.
For each openUTM task a storage area with a size of
MAXSIZE
is generated. This area contains the Natural user area in decompressed
form.
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.
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.
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 |
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.
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 The openUTM I/O areas |
| 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
Any number of openUTM transaction codes can be assigned, providing the naming rule is observed. The name of the DC transaction exit routine
|
| 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.
The following Natural-specific points must be observed when defining the openUTM resources:
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.
PTERM ss19,lterm=ltdf1900,pronam=vr,ptype=t9755,TERMN=X1
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.
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 |
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.
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.
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.
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.