This part of the Natural openUTM Interface documentation covers the following topics:
To better control the use of resources by Natural openUTM
applications, accounting records are made available by the user exits
ACCINIT and ACCEXIT.
The user exit ACCINIT is activated by the Natural
openUTM Interface at the beginning of each dialog step.
The user exit ACCEXIT is activated by the Natural
openUTM Interface depending on the parameter
ACCNT in macro
NURENT:
ACCNT=DIAL |
The user exit ACCEXIT is activated at the end of
each dialog step.
|
ACCNT=APPL |
The user exit ACCEXIT is activated at each change
of application (new Natural logon ID).
|
In both cases, an accounting record is also provided at the end of the
session (FIN system command or
TERMINATE statement).
| 0 - 7 | Logical openUTM terminal name | DS | CL8 |
| 8 - 15 | User ID | DS | CL8 |
| 16 - 23 | Current Natural application name | DS | CL8 |
| 24 - 27 | Number of Adabas calls | DS | F |
| 28 - 31 | Accumulated message length | DS | F |
| 32 - 35 | Elapsed time in Natural including subroutines (milliseconds) | DS | F |
| 36 - 37 | Number of pages printed | DS | H |
| 38 - 39 | Number of terminal I/O transfers | DS | H |
| 40 - 49 | (user area) | DS | CL10 |
| 50 - 51 | unused | DS | CL2 |
| 52 - 55 | Adabas command time (milliseconds) | DS | F |
| 56 - 63 | Name of last transaction program | DS | CL8 |
The user area of the accounting record can (if required) be used for additional application-specific accounting information. The accounting area is in the user-specific openUTM communication area KB (Kommunikationsbereich).
The current address of the openUTM KBs can be found with the
entry CMKBADR of macro NATUTM as necessary;
otherwise, the operand of the parameter KB of macro NATUTM
must be set to YES. In this case, Natural passes the address of
the communication area as the first parameter of every subroutine call.
The user exit routine ACCEXIT can store the accounting
records in an Adabas file, in a shared sequential PAM data set or in a
task-specific SAM data set. The program ACCEXIT shows an example
of the method for storing accounting records; see
Software
Exchange.
Several utility programs are provided for use with Natural under openUTM.
The following rules apply to their usage:
The Natural and openUTM macro libraries must be used when assembling these utilities.
When a particular program is to be used:
its name must be specified with the parameter
LINK or
LINK2
of macro NATUTM
and the program itself must be linked to the Natural environment-dependent nucleus (see the Installation documentation).
A short-form description of these utility programs is given below.
NATDUE |
INPTEX |
NATPRNT |
UTMTAC |
TACSWTCH
A detailed description, including the interface, valid parameter values and a summary of the logic, can be found in each program's maintenance log.
The program NATDUE can be used to find out within a
Natural program whether the user has entered data in the current dialog step or
whether merely EM/DÜ or DÜ was pressed.
The utility program INPTEX must be used
if NATDUE is to be called. The program INPTEX
satisfies the user exit INPTEX in the format exit module
FREXIT and
checks at each dialog step whether data were entered. According to the result
of this test, a flag that is subsequently interrogated by the program
NATDUE is set in the communication area KB
(Kommunikationsbereich).
* PROG1 - EXAMPLE FOR CALLING THE SUBROUTINE 'NATDUE' RESET P1(A1) ... ... INPUT USING MAP ... CALL 'NATDUE' P1 IF P1 = 'Y' DO ... /* INPUT FROM USER IF P1 = 'N' DO ... /* NO INPUT FROM USER IF P1 = 'E' DO ... /* ERROR ... END
The utility program INPTEX satisfies the user exit of the
same name in the format exit FREXIT.
Important:INPTEX must be linked to the Natural
environment-dependent
nucleus (see the Installation
documentation).
 |
Warning: Any modifications that can be made to this program, for example, ignoring data entered in a particular line on the terminal screen, are made at the user's risk. |
The function of this program is to check each input message for the presence of input from the terminal, or whether merely EM/DÜ or DÜ was pressed.
It is not necessary to define the program name INPTEX with
the parameter LINK
or LINK2 of
macro NATUTM.
The program NATPRNT provides the following special service
functions for operating local printers:
accepting the logical name of the target printer;
verifying the printer name against a list of valid printer names;
setting a marker for building variable length print records.
The program UTMTAC, which can be called from a Natural
program, yields the current openUTM TAC. This makes it possible for a
central Natural program to perform openUTM TAC-controlled
"navigation" within a Natural openUTM application.
The utility program TACSWTCH is a macro which can be used
to dynamically assign an openUTM TAC for a PEND
PR(OGRAM) from within a Natural program. The specified
openUTM TAC is checked against the generated openUTM table
and saved accordingly. Also, information can be passed to the PEND
PR(OGRAM). To use this utility, proceed as follows:
Define the valid openUTM TACs and assemble the
TACSWTCH macro:
For Example: TACSWTCH
TAC=(tac1,tac2,tac3,...tacn) These TACs have
to be defined in KDCDEF as well, and for the generation of
KDCROOT they have to be assigned to the corresponding
openUTM partial programs.
Define the program TACSWTCH with the parameters
LINK to
LINK4
in macro NATUTM.
Link program TACSWTCH to the Natural
environment-dependent
nucleus (see the Installation
documentation).
Interface description: CALL 'TACSWTCH' P1 [P2] P3
P1 (A8)
|
Contains the openUTM
TAC to be used for a PEND PR.
|
|
P2 (A
n)
|
Is optional and contains the
length and data of a message to the PEND PR.
The structure of |
|
LLL |
Message length (3 digits, no length field); minimum length:
000, maximum length: 160.
|
|
DDD |
Message area. | |
P3 (A1)
|
Has two functions:
On call and if On return, Possible return codes are: |
|
0 |
The operation has been executed without error. | |
1 |
TAC has not been found in the TAC table. | |
2 |
Message length was less than 000.
|
|
3 |
Message length was over 160.
|
|
Once TACSWTCH has
been called without error, a PEND PR(OGRAM) can be
executed by either issuing a FIN command or with a
TERMINATE statement or by activating the function key for
PEND PR; see the parameter
PRKEY.
|
||
You can use the first TACSWTCH parameter with
the following values:
| Value | Explanation |
|---|---|
RESET |
The openUTM TAC currently available will be cleared,
that is, the session will be terminated with PEND
FI.
|
GETP
|
Data will be moved from the print buffer to the adequate data area of the calling Natural program. |
GETU
|
Data will be moved from the KB user extension to the adequate data area of the calling Natural program. |
The first two bytes (format: binary) in the print buffer or in the KB user extension must contain the data length (including these first two bytes).
| Value | Explanation |
|---|---|
PUTP |
Data will be moved from the adequate data area of the calling Natural program to the print buffer. |
PUTU |
Data will be moved from the adequate data area of the calling Natural program to the KB user extension. |
The first two bytes (format: binary) in the data area of the Natural program must contain the data length (including these first two bytes). The data will be moved including the first two bytes.
DEFINE DATA LOCAL 01 P1(A8) /* FUNCTION CODE/UTM TAC 01 P2(A252) /* FIRST PART OF DATA AREA 01 REDEFINE P2 02 P21(B2) /* DATA LENGTH INCLUDING FIRST TWO BYTES 02 P22(A250) 01 A1(A250) /* SECOND PART OF DATA AREA 01 P3(N1) /* RETURN CODE END-DEFINE ... /* PROGRAM LOGIC MOVE 'PUTP' TO P1 /* MOVE FUNCTION CODE FOR TACSWTCH MOVE 502 TO P21 /* MOVE TOTAL LENGTH OF DATA CALL 'TACSWTCH' P1 P2 P3 /* PUT DATA INTO PRINT BUFFER IF P2 NE 0 /* RETURN CODE CONTROLLING DO... /* ERROR LOGIC MOVE 'NAT1' TO P1 /* MOVE ADEQUATE UTM TAC MOVE 'G' TO P3 /* EXECUTE PEND PR WITH TAC NAT1 CALL 'TACSWTCH' P1 P3 IF P3 NE 0 /* RETURN CODE CONTROLLING DO... /* ERROR LOGIC INPUT ' ' /* DUMMY MESSAGE FOR DRIVER CONTROL
Now the Natural openUTM driver gets control and runs with the following logic:
It ignores the dummy message (INPUT ' ').
MPUT with LENGTH=0 and PEND
PR with TAC 'NAT1' for the openUTM partial
program.
The openUTM partial program gets the Natural program data
through the print buffer. The print buffer is located in the openUTM
SPAB and the address of the print buffer is defined in the field
'KBAPBUFF', which is located in the openUTM KB:
It moves data for the Natural program into the print buffer (the first two bytes must contain the data length in binary format, including the two-byte length field).
It executes an MPUT with LENGTH=0 and a
PEND PR with the TAC defined for the Natural
openUTM driver.
The Natural openUTM driver gets control
(INIT/MGET).
It simulates ONLY ENTER for Natural.
It resumes with Natural as follows:
MOVE 'RESET' TO P1 /* MOVE FUNCTION CODE FOR TACSWTCH CALL 'TACSWTCH' P1 P3 /* RESET PEND PR TAC (NAT1) IF P3 NE 0 /* RETURN CODE CONTROLLING DO... /* ERROR LOGIC MOVE 'GETP' TO P1 /* MOVE FUNCTION CODE FOR TACSWTCH CALL 'TACSWTCH' P1 P2 P3 /* GET DATA FROM PRINT BUFFER IF P3 NE 0 /* RETURN CODE CONTROLLING DO... /* ERROR LOGIC ... /* PROGRAM LOGIC END
If the parameter KBSAVE of macro
NATUTM is set to YES, the called openUTM
partial program may use the openUTM KB (from the end of the header
plus first twelve bytes). In this case, the openUTM KB will be saved
(beginning from KB header plus first twelve bytes) with SPUT and
will be refreshed with SGET.
When defining openUTM transaction codes for the transaction logic between Natural and other openUTM partial programs, the following rule applies:
For a PEND PR from another openUTM partial
program to the Natural openUTM driver, the preceding start TAC may
never be used. The fact that the Natural openUTM driver was called by
a PEND PR can only be recognized if the contents of the preceding
start TAC in field KCTACVG are different from the current TAC in
field KCTACAL. (Normally, field KCTACVG contains the
TAC with which the user has entered the application.)
Software AG's customers have developed programs that meet certain specific needs found in their Natural openUTM applications. These programs are made available to all interested users via the "Software Exchange". This also applies to programs developed by Software AG that demonstrate example solutions to particular problems.
These programs, which are available free of charge, are not maintained by Software AG. The complete documentation of each program is usually included in the maintenance log of the source listing.
A short-form description of each program is given below:
XAMDUSA |
UTMCOB |
UTMNAV |
NUEXAMPL |
ACCEXIT |
TABMOD
This program saves and restores the current user-specific
WORKING-STORAGE SECTION of the calling COBOL program.
This enables user-specific data areas, for example tables, to be accessible over many dialog steps and without regard to the openUTM task in which the user is currently running. The data are saved in a PAM file using logical/physical chained PAM-I/O.
Program UTMCOB is an example of a user-specific
openUTM partial program within a Natural openUTM application.
It shows the fundamental logical structure of a program that, as a
openUTM partial program:
Can be activated by the user by associated openUTM TACs.
Activates the Natural openUTM Interface and hence the
Natural application by means of PEND PR(OGRAM) with dynamic
Natural parameters.
Can be activated from the Natural openUTM Interface by means
of PEND PR(OGRAM).
See also Calling openUTM Chained Partial Programs.
Program UTMNAV is another example of a user-specific
openUTM partial program within a Natural openUTM
application:
It can be activated by the user or with PEND PR(OGRAM)
by the associated openUTM TAC.
It interprets passed messages as dynamic Natural parameters.
It provides screen output of information on the program logic.
Previously received screen input (Natural dynamic parameters) is sent
with MPUT and passed to the Natural openUTM Interface
with PEND PR(OGRAM).
Program UTMNAV contains an example of how the
openUTM KB can be used as a "common" user area.
Program NUEXAMPL is an example of a user-specific
openUTM partial program which can exchange data with a Natural
program. The program logic of NUEXAMPL and of the calling Natural
program is described in the maintenance log of NUEXAMPL.
Program ACCEXIT is an example of a program that saves
accounting data on a shared ISAM data set. The user exits
ACCEXIT and
SHUTEX2 of the Natural openUTM Interface are used. See
also Accounting for
Natural openUTM Applications.
The program TABMOD, which can be called from a Natural
program, performs the following functions:
load data records, for example a table, into a common memory pool using a unique key when an application is started and whilst an application is running;
transfer data records according to the requirements of the calling Natural program.
This makes it possible to load frequently-needed data into storage once only and then keep them resident.
TABMOD is available as a macro in the library
NUTnnn.MAC. It contains all information
necessary for its installation and usage.
Natural programs can allocate openUTM TAC classes to optimize resource control using the openUTM TACCLASS concept in a Natural openUTM application.
The following procedure should be followed when generating the Natural openUTM application and creating the Natural program:
OPTION GEN=ALL,ROOTSRC=INPUT.KDCROOT.KDCNATP ROOT KDCNATP MAX APPLINAME=NATUTM,APPLIMODE=S,KDCFILE=(NATUTM,S) MAX KB=400,SPAB=8192,NB=5120,TRMSGLTH=5120 MAX TASKS=10 MAX ASYNTASKS=3 ... EXIT PROGRAM=NUSTART,USAGE=START EXIT PROGRAM=NUSTART,USAGE=SHUT EXIT PROGRAM=FREXIT,USAGE=FORMAT ... DEFAULT PROGRAM COMP=ASSEMB PROGRAM NUSTART PROGRAM FREXIT PROGRAM NUERROR PROGRAM KDCADM,COMP=SPL4 ... DEFAULT TAC TYPE=D,PROGRAM=NUSTART,EXIT=NUERROR,CALL=BOTH,... TAC NAT,TIME=(3600000,5400),TACCLASS=1,... TAC NAT1,TIME=(3600000,5400),TACCLASS=2,... ... DEFAULT TAC TYPE=A,PROGRAM=NUSTART,EXIT=NUERROR,CALL=FIRST,... TAC NATAS,TACCLASS=9 TAC NATAS1,TACCLASS=10 ... TACCLASS 1,TASKS=3 TACCLASS 2,TASKS=1 TACCLASS 9,TASKS=2 TACCLASS 10,TASKS=1 ... END
See also the openUTM documentation openUTM Generierung und Administration (openUTM Generation and Administration).
Notes on the openUTM TACs Defined
| openUTM TAC | Explanation |
|---|---|
NAT
|
This is the openUTM TAC for less resource-intensive synchronous transactions; that is, transactions of short duration. |
NAT1
|
This is the openUTM TAC for more resource-intensive synchronous transactions; that is, transactions of longer duration. |
NATAS
|
This is the openUTM TAC for less resource-intensive asynchronous transactions. |
NATAS1
|
This is the openUTM TAC for more resource-intensive asynchronous transactions. |
The name of the job is EN.NATUTM.
/.NATUTM LOGON Natural,E,,TIME=10000 /SYSFILE SYSOUT=PROT.UTMSTAT /FILE NATUTM.KDCA,LINK=KDCFILE /ERASE NATUTM.PRINTCONTROL /STEP /FILE LOG.NATUTM,LINK=SYSLOG /FILE NATUTM.SWAPFILE,LINK=PAMNAT,SHARUPD=Y /SYSFILE TASKLIB=NAT210.MOD /.REPEAT EXEC NATUTM.E .UTM START FILEBASE=NATUTM START TASKS=7 START ASYNTASKS=3 START STARTNAME=EN.NATUTM .UTM END /SKIP .REPEAT /STEP /SYSFILE SYSOUT=(PRIMARY) /STEP /SYSFILE SYSLST=(PRIMARY) /CAT NATUTM.PRINTCONTROL,SHARE=YES /PRINT LST.NATUTM.,SPACE=E /ERASE LST.NATUTM. /STEP /LOGOFF NOSPOOL
The TAC-class of synchronous openUTM transactions can be changed by a Natural program with the statements:
CALL 'NATTAC' operand1[operand2] [operand3]INPUT 'TACCLASS
where:
operand1
|
Must contain the value
S=n, where S denotes
"synchronous" and n is an
integer value (0 - 4) that denotes the priority level of the
transaction in subroutine NATTAC's table of transaction codes for
synchronous TACs.
|
|
If
n is 0, the table of
transaction codes is not used. The TAC to be used is passed explicitly in
operand2 when NATTAC is
called.
|
||
If
n is a value in the range 1 -
4, the priority level of the desired TAC is taken from the appropriate
parameter TCLS1 to
TCLS4
(for synchronous transactions) or TCLA1 to
TCLA4 (for
asynchronous transactions).
|
||
If the subroutine
NATTAC detects an error in
operand1, it returns immediately to the
calling program with an error code in
operand1:
|
||
E01 |
The first two characters of operand1
were neither S= nor A=.
|
|
E02 |
The third character of
operand1 was <0 or
>4.
|
|
E03 |
No openUTM TAC was defined for the specified priority
level when the Natural openUTM application was generated, which means
that the corresponding parameter (TCLS
n or TCLA
n) has the value -.
|
|
| operand2 | Optional. Must contain the
openUTM TAC for the desired TAC class if the third character of
operand1 is 0.
|
|
| operand3 | Optional. Must contain the value
Y if the current user's subsequent dialog is to be executed with
the openUTM TAC defined in
operand1 or
operand2. If
operand3 is omitted when
NATTAC is called, or if
operand3 has some value other than
Y, the START transaction code for the current user is
used again with the first terminal output (standard function). If
operand3 has the value Y
when NATTAC is called, further processing for the current user
takes place with the openUTM TAC specified in
operand1 (implicit) or
operand2 (explicit)
.
|
|
The statement INPUT 'TACCLASS' does not perform any
terminal I/O; its function is merely to control the TACCLASS allocation.
Alternatively, a Natural program can call the Natural subprogram
NATTAC with a CALLNAT statement. For this, the
INPUT 'NATTAC' statement is omitted; the operands are the same as
for the CALL statement (see above):
CALLNAT 'NATTAC' operand1[operand2] [operand3]
This procedure can be used with synchronous as well as asynchronous
transactions. NATTAC is contained in the library
SYSTEM.
A Natural program that allocates an openUTM TAC explicitly to assign a new TAC class and then changes over to the START openUTM TAC.
* TACCLASS - EXAMPLE FOR A TACCLASS SWITCH RESET CONTROL(A3) NEWTAC(A8) NR(N3) REDEFINE CONTROL (ERRFLD(A1)) INPUT 'TEST FOR A TACCLASS SWITCH - NEW TAC: NAT1' IFELD(A1) MOVE 'S=0' TO CONTROL /* SYNCHR. TAC, EXPLICIT --> Note 1 MOVE 'NAT1' TO NEWTAC /* SET NEW TAC --> Note 2 CALL 'NATTAC' CONTROL NEWTAC /* INVOKE TAC SWITCH --> Note 3 IF ERRFLD = 'E' DO /* ERROR CHECK --> Note 4 DISPLAY 'ERROR' CONTROL 'FROM NATTAC' TERMINATE DOEND INPUT 'TACCLASS' /* ACTIVATE NEW TAC --> Note 5 READ (50) AUTOMOBILES BY MAKE /* NOW IN NEW TACCLASS --> Note 6 ADD 1 TO NR WRITE NOTITLE NOHDR NR MAKE MODEL /* START TAC IS USED --> Note 7 LOOP ON ERROR DISPLAY 'ERROR IN PROGRAM TACCLASS' END
| Note | |
|---|---|
| 1 | The value S=0 indicates that it is a synchronous
transaction and that the TAC is passed explicitly in the second parameter of
the CALL 'NATTAC', which means that the TAC table is not
used.
|
| 2 | The new TAC (NAT1) is set up for the call to
NATTAC.
|
| 3 | The change of TAC class is initialized by calling
NATTAC.
|
| 4 | An error check is performed after returning from subroutine
NATTAC.
|
| 5 | A pseudo-MPUT and a PEND
PA are executed with the new TAC.
|
| 6 | The program is now running in the TAC class for
NAT1.
|
| 7 | When the first terminal output starts, the START openUTM TAC takes effect again. |
In this example, the AUTOMOBILE file is read using the
openUTM TAC NAT1. When the first terminal output begins,
the START openUTM TAC (NAT) takes effect again.
When NATTAC is called, a flag is set in the
openUTM communication area (Kommunikationsbereich) indicating
that a change of TACCLASS is pending.
The openUTM TAC passed by the program is also stored in the
user-specific communication area. The operation INPUT 'TACCLASS'
causes terminal output from Natural, which causes the openUTM
Interface to issue an MPUT and a PEND 'PA' with the
new openUTM TAC (the message is received by the Natural
openUTM Interface itself). When the message is received (in the new
TAC class), the presence of the TACCLASS change flag causes the interface to
simulate an ETX/DÜ in its input area. Further processing runs in
the new TAC class.
Depending upon the value of the operand in the previous call of
NATTAC, the first message sent to the terminal can cause an
MPUT and a PEND 'PR' with the user's
START openUTM TAC; that is, a further TACCLASS change may take
place.
A Natural program that allocates a openUTM TAC explicitly to assign a new TAC class without changing over to the START openUTM TAC.
* TACCLAS1 - EXAMPLE FOR A TACCLASS SWITCH RESET CONTROL(A3) NEWTAC(A8) SWOFF(A1) INPUT 'TEST FOR A TACCLASS SWITCH - NEW TAC: NAT1' IFELD(A1) MOVE 'S=0' TO CONTROL /* SYNCHR. TAC, EXPLICIT MOVE 'NAT1' TO NEWTAC /* SET NEW TAC MOVE 'Y' TO SWOFF /* NO RESET TO START TAC CALL 'NATTAC' CONTROL NEWTAC SWOFF /* INVOKE TAC SWITCH INPUT 'TACCLASS' /* ACTIVATE NEW TAC FETCH 'TACCLAS2' /* NOW IN NEW TACCLASS END * TACCLAS2 - THIS PROGRAM IS FETCHED FROM PROGRAM TACCLAS1 RESET NR(N3) READ (25) AUTOMOBILES BY MAKE /* TACCLASS IS NAT1 ADD 1 TO NR WRITE NOTITLE NOHDR NR MAKE MODEL HORSEPOWER YEAR LOOP FETCH 'MAINMENU' /* TACCLASS = NAT1 END
In this example, processing is assigned to a new TAC class with TAC
NAT1. Switching to the user's START openUTM TAC is
avoided by the presence of the third parameter (SWOFF)
in the call to NATTAC with value Y.
It is also possible to perform several TACCLASS changes within one Natural program.
A Natural program that performs two explicit and one implicit TACCLASS changes.
*TACMULT - EXAMPLE FOR TWO TACCLASS SWITCHES IN ONE PROGRAM RESET CONTROL(A3) NEWTAC(A8) SWOFF(A1) NR(N4) INPUT 'TEST FOR 2 TACCLASS SWITCHES' IFELD(A1) MOVE 'S=0' TO CONTROL /* SYNCHR. TAC, EXPLICIT MOVE 'NAT1' TO NEWTAC /* SET NEW TAC MOVE 'Y' TO SWOFF /* NO RESET TO START TAC CALL 'NATTAC' CONTROL NEWTAC SWOFF /* INVOKE TAC SWITCH INPUT 'TACCLASS' /* ACTIVATE NEW TAC READ (50) AUTOMOBILES BY MAKE /* NOW IN NEW TACCLASS ADD 1 TO NR WRITE NR MAKE MODEL YEAR LOOP EJECT /* ACTIVATE NEW OUTPUT ***** MOVE 'S=0' TO CONTROL /* SYNCHR. TAC, EXPLICIT MOVE 'NAT2' TO NEWTAC /* SET NEW TAC CALL 'NATTAC' CONTROL NEWTAC /* INVOKE TAC SWITCH INPUT 'TACCLASS' /* ACTIVATE NEW TAC READ (100) AUTOMOBILES BY MAKE /* NOW IN NEW TACCLASS WRITE MAKE MODEL YEAR /* NOW START TAC IS USED LOOP ON ERROR DISPLAY 'ERROR IN PROGRAM TACMULT' END
The openUTM TAC NAT2 has not been considered in
the preceding examples; it must be defined in KDCROOT and
KDCDEF.
If an explicit TACCLASS change is to take place after a
WRITE, PRINT or DISPLAY statement, an
EJECT must be issued before assigning the new TAC. This operation
performs an unconditional output to the terminal before executing the
INPUT 'TACCLASS'. Instead of the EJECT, the following
statements can be used:
STACK TOP DATA 'A' INPUT A(A1)
This sequence also performs an unconditional output to the terminal
before executing the INPUT 'TACCLASS'.
A Natural program that allocates an openUTM TAC implicitly to
assign a new TAC class and then changes over to the START openUTM TAC.
This example uses the TAC table for synchronous transactions in the subroutine
NATTAC.
* TACIMP1 - EXAMPLE FOR AN IMPLICIT TACCLASS SWITCH RESET CONTROL(A3) NR(N3) REDEFINE CONTROL (ERRFLD(A1)) INPUT 'TEST FOR AN IMPLICIT TACCLASS SWITCH' IFELD(A1) MOVE 'S=1' TO CONTROL /* USE 1ST TAC IN TABLE --> Note CALL 'NATTAC' CONTROL /* INVOKE TAC SWITCH IF ERRFLD = 'E' DO /* ERROR CHECK DISPLAY 'ERROR' CONTROL 'FROM NATTAC' TERMINATE DOEND INPUT 'TACCLASS' /* ACTIVATE NEW TAC READ (100) AUTOMOBILES BY MAKE /* NOW IN NEW TACCLASS ADD 1 TO NR WRITE NOTITLE NOHDR NR MAKE MODEL /* START TAC IS USED LOOP ON ERROR DISPLAY 'ERROR IN PROGRAM TACIMP1' END
Note: The value S=1 indicates that it is a synchronous
transaction and that the TAC is to be taken from the first entry in the TAC
table. This is the TAC that was defined as the value of the operand of the
parameter TCLS1
(default value: NAT1). The third character of the first parameter in the
CALL 'NATTAC' indicates which of the four parameters
TCLS1 to
TCLS4
applies.
A Natural program that allocates an openUTM TAC implicitly to
assign a new TAC class but does not change over to the START openUTM
TAC. This example uses the TAC table for synchronous transactions in the
subroutine NATTAC, and processing continues with this TAC.
* TACIMP2 - EXAMPLE FOR AN IMPLICIT TACCLASS SWITCH RESET CONTROL (A3) SWOFF(A1) NR(N3) REDEFINE CONTROL (ERRFLD(A1)) MOVE 'S=4' TO CONTROL /* USE 4TH TAC IN TABLE --> Note MOVE 'Y' TO SWOFF /* NO RESET TO START TAC CALL 'NATTAC' CONTROL SWOFF /* INVOKE TAC SWITCH IF ERRFLD = 'E' DO /* ERROR CHECK DISPLAY 'ERROR' CONTROL 'FROM NATTAC' TERMINATE DOEND INPUT 'TACCLASS' /* ACTIVATE NEW TAC READ (100) AUTOMOBILES BY MAKE /* NOW IN NEW TACCLASS ADD 1 TO NR WRITE NR MAKE MODEL YEAR LOOP ON ERROR DISPLAY 'ERROR IN PROGRAM TACIMP2' END
Note: The value S=4 indicates that it is a synchronous
transaction and that the TAC is to be taken from the fourth entry in the TAC
table. This is the TAC that was defined as the value of the operand of the
parameter TCLS4 (default
value: NAT4). The TAC NAT4 is not defined in the
examples of KDCROOT and KDCDEF; in practice, the user
must supply suitable definitions.
Using the TAC table has the advantage that the openUTM TAC does not have to be coded explicitly in the Natural program. The Natural programs contain merely the relative priority "weights" of the transactions to be executed. The system administrator can allocate and change the names of the openUTM TACs without having to change the Natural programs.
For testing Natural programs with TACCLASS change for synchronous
transactions, please note the following: To verify correct operation of the
TACCLASS change, the Natural program can be tested without the statement(s)
CALL 'NATTAC' operand1
(operand2)
(operand3). If the INPUT
'TACCLASS' statement produces only the output 'TACCLASS' on
the terminal, the program is correct. The operand(s) for the call to
NATTAC must be set correctly. The openUTM processing
terminates with Error Code KM01 whenever an openUTM TAC
that is not defined in KDCROOT and KDCDEF is
used.
The TAC class for asynchronous transactions within a Natural openUTM application can be changed with the statement:
CALL 'NATTAC'operand1[operand2]
operand1
|
Must contain the value A=
n, where A denotes
"asynchronous" and n is an
integer in the range from 0 to 4 that denotes the
priority level of the transaction in subroutine NATTAC's table of transaction
codes for asynchronous TACs. The form of the operand is analogous to the form
of the operand for synchronous transactions.
|
operand2
|
Optional. Contains the openUTM TAC for the required
TAC class if operand1 has the value
A=0.
|
All openUTM TACs for asynchronous transactions must begin with
the character string which is defined as unique identifier for asynchronous
TACs in parameter ASYNTAC of macro
NATUTM. Conversely, the openUTM TACs for synchronous
transactions must not begin with this string.
A Natural program that performs initialization for asynchronous
transaction processing, using the openUTM TAC NATAS. This
is the standard TAC for asynchronous transactions. See also the description of
the parameter ASYNTAC of macro
NATUTM.
* STARTAS - EXAMPLE FOR ASYNCHRONOUS TRANSACTION WORKING
* WITHIN ONE APPLICATION - USING THE STANDARD TAC
FORMAT LS=145
RESET PARM1(A144) PRDEST(A8) LTDEST(A8)
MOVE 'PRINTER1' TO PRDEST
MOVE *INITID TO LTDEST
COMPRESS 'SENDER=' PRDEST ',OUTDEST=' LTDEST ','
'MENU=F,STACK=(LOGON APPL1;READAUTO)' INTO PARM1
LEAVING NO
CALL 'NATASYN'
SET CONTROL 'H'
WRITE NOTITLE NOHDR PARM1
INPUT 'ASYNTASK INVOKED - HOPEFULLY' IFELD(A1)
END
A Natural program that initializes asynchronous transaction processing
and allocates the openUTM TAC NATAS1 for assignment to
another TAC class.
* STASTAC - EXAMPLE FOR ASYNCHRONOUS TRANSACTION WORKING
* WITHIN ONE APPLICATION
* AND SWITCH TO A NEW TACCLASS
FORMAT LS=145
RESET PARM1(A144) PRDEST(A8) LTDEST(A8) CONTROL(A3) NEWTAC(A8)
REDEFINE CONTROL (ERRFLD(A1))
MOVE 'PRINTER1' TO PRDEST
MOVE *INIT-ID TO LTDEST
COMPRESS 'SENDER=' PRDEST ',OUTDEST=' LTDEST ','
'MENU=F,STACK=(LOGON APPL1;READAUTO)' INTO PARM1
LEAVING NO
MOVE 'A=0' TO CONTROL /* ASYNCHR. TAC, EXPLICIT --> NOTE
MOVE 'NATAS1' TO NEWTAC /* SET NEW TAC
CALL 'NATTAC' CONTROL NEWTAC /* INVOKE TAC SWITCH
IF ERRFLD = 'E' DO /* ERROR CHECK
DISPLAY 'ERROR' CONTROL 'FROM NATTAC'
TERMINATE
DOEND
CALL 'NATASYN' /* INVOKE ASYNCHRONOUS TAC
SET CONTROL 'H'
WRITE NOTITLE NOHDR PARM1
INPUT 'ASYNTAC INVOKED - HOPEFULLY' IFELD(A1)
END
The value A=0 indicates that it is an asynchronous
transaction and that the TAC is passed explicitly in the second parameter of
the CALL 'NATTAC', which means that the TAC table is not used.
MOVE 'A=1' TO CONTROL CALL 'NATTAC' CONTROL
The procedure for using the TAC table (see the parameters
TCLA1 to
TCLA4
in the section Parameters of Macro
NATUTM) corresponds to the procedure for synchronous
transactions.
An example of the program that is to be executed asynchronously
(READAUTO):
* READAUTO - ASYNCHRONOUS Natural PROGRAM READ (75) AUTOMOBILES BY MAKE WRITE MAKE MODEL HORSEPOWER BODY-TYPE YEAR LOOP ON ERROR TERMINATE TERMINATE END
The desired openUTM TAC must always be allocated in the
Natural program that initializes the asynchronous transaction processing (the
use of the standard TAC for asynchronous transaction processing is an
exception; see the description of the parameter ASYNTAC in the macro
NATUTM. The program that is to be executed asynchronously then
runs in the desired TAC class. Since each asynchronous Natural program must be
ended with the TERMINATE statement, the openUTM DC
transaction is also ended (PEND 'FI') when the program ends.
The program that initializes the asynchronous transaction processing
always runs in a synchronous transaction. Thus it is feasible to perform a
change of TACCLASS using the procedure for synchronous transactions. This
change can take place before allocating the asynchronous TACs or after
initializing the asynchronous transaction (INPUT statement).
It is not necessary to call NATTAC for asynchronous
transaction processing between two Natural openUTM applications. The
necessary openUTM TAC is allocated explicitly in the Natural program;
see also Asynchronous
Transaction Processing.
The following figure illustrates the logic of an openUTM TACCLASS switch for synchronous transactions:
The following programs and macros must be assembled to generate a Natural openUTM application:
KDCROOT |
openUTM interface module. |
NATUTM
|
Front-end part of the Natural openUTM Interface. |
BS2STUB
|
Common memory pool definition. |
FREXIT
|
Format exit module (only if the default parameter is to be changed). |
NURENT
|
Reentrant part of the Natural openUTM Interface. |
NTPRM
|
Natural parameter module. |
NTSWPRM
|
Swap pool parameter module. |
This list does not include the utility programs of the Natural openUTM Interface.
The following example shows how to generate an application.
OPTION GEN=ALL,ROOTSRC=INPUT.KDCROOT.KDCNATP ROOT KDCNATP MAX APPLINAME=NATUTM,APPLIMODE=S,KDCFILE=(NATUTM,S) MAX KB=400,SPAB=8192,NB=5120,TRMSGLTH=5120 MAX TASKS=10,ASYNTASKS=3 MAX GSSBS=0,KSSBS=1 MAX LOGACKWAIT=600,RESWAIT=(600,1200),TERMWAIT=(1800,0) MAX PGPOOL=(88,80,95),CONRTIME=2,RECBUF=(400,2048) MAX DPUTLIMIT1=(001,23,59,59),DPUTLIMIT2=(001,23,59,59) MAX LPUTLTH=0 *+---------------------------------------------------------------------------+ *I EXIT DEFINITIONS: STARTUP (CSECT NAME OF NATUTM) I *I SHUTDOWN (CSECT NAME OF NATUTM) I *I FORMAT (FREXIT) I *+---------------------------------------------------------------------------+ EXIT PROGRAM=NUSTART,USAGE=START EXIT PROGRAM=NUSTART,USAGE=SHUT EXIT PROGRAM=FREXIT,USAGE=FORMAT *+---------------------------------------------------------------------------+ *I P R O G R A M D E F I N I T I O N S I *+---------------------------------------------------------------------------+ DEFAULT PROGRAM COMP=ASSEMB PROGRAM NUSTART PROGRAM FREXIT PROGRAM NUERROR PROGRAM AUTOTAC PROGRAM KDCADM,COMP=SPL4 *+---------------------------------------------------------------------------+ *I SYNCHRONOUS TACS FOR Natural/UTM I *I THE ERROR EXIT 'NUERROR' MUST BE DEFINED FOR EACH TAC I *+---------------------------------------------------------------------------+ DEFAULT TAC TYPE=D,PROGRAM=NUSTART,EXIT=NUERROR,CALL=BOTH TAC NAT,ADMIN=NO,TIME=0 TAC AUTOCONN *+---------------------------------------------------------------------------+ *I BADTACS DEFINITION FOR Natural/UTM I *I THE ERROR EXIT 'NUERROR' MUST BE DEFINED FOR EACH TAC I *+---------------------------------------------------------------------------+ TAC KDCBADTC,CALL=FIRST,PROGRAM=AUTOTAC,EXIT=NUERROR,TYPE=D *+---------------------------------------------------------------------------+ *I ASYNCHRONOUS TACS FOR Natural/UTM I *I THE ERROR EXIT 'NUERROR' MUST BE DEFINED FOR EACH TAC I *+---------------------------------------------------------------------------+ DEFAULT TAC TYPE=A,PROGRAM=NUSTART,EXIT=NUERROR,CALL=FIRST TAC NATAS TAC NATSY *+---------------------------------------------------------------------------+ *I UTM ADMINISTRATOR TACS I *+---------------------------------------------------------------------------+ DEFAULT TAC PROGRAM=KDCADM,ADMIN=Y,TYPE=D,CALL=BOTH TAC KDCTAC TAC KDCLOG TAC KDCSHUT TAC KDCAPPL TAC KDCINF TAC KDCUSER TAC KDCSEND TAC KDCDIAG TAC KDCLTERM TAC KDCPTERM TAC KDCSWTCH TAC KDCHELP *+---------------------------------------------------------------------------+ *I PTERM 9750 DEFINITION I *+---------------------------------------------------------------------------+ DEFAULT PTERM PRONAM=VR,PTYPE=T9750,TERMN=FE,CONNECT=N PTERM DFDSS001,LTERM=DF97501 PTERM DFDSS002,LTERM=DF97502 PTERM DFDSS003,LTERM=DF97503 *+---------------------------------------------------------------------------+ *I LTERM DEFINITION I *+---------------------------------------------------------------------------+ DEFAULT LTERM USAGE=D,STATUS=ON,ANNOAMSG=YES,RESTART=YES LTERM=DF97501 LTERM=DF97502 LTERM=DF97503 *+---------------------------------------------------------------------------+ *I SFUNC DEFINITION I *+---------------------------------------------------------------------------+ SFUNC F1,RET=21Z SFUNC F2,RET=22Z SFUNC F3,RET=23Z SFUNC F4,RET=24Z SFUNC F5,RET=25Z SFUNC K1,RET=26Z SFUNC K2,RET=27Z SFUNC K3,RET=28Z SFUNC K4,RET=29Z END
See also the openUTM documentation UTM Generierung und Administration (openUTM Generation and Administration).
The operands of the parameters of macro
NATUTM must be set to the correct values as required;
the macro NATUTM must then be assembled.
Example of NATUTM Macro Call:
NUSTART NATUTM APPLNAM=NATUTM, --> Note 1 -
NUCNAME=NATvrs
, --> Note 2 -
LINK=TACSWTCH --> Note 3 -
PARMOD=24, --> Note 4 -
ROLLACC=UPAM-AS, --> Note 5 -
ROLLTSZ=180, --> Note 6 -
TERMTAB=(SWP,TERMNAME), --> Note 7 -
UMODE=(S,G) --> Note 8
where vrs represents the
current product version number.
| Notes | |
|---|---|
| 1 | The CSECT name of the non-reentrant part of the
Natural openUTM Interface is specified as NUSTART
(default value). The name of the Natural openUTM application is
specified as NATUTM.
|
| 2 | The name of the link-edited reentrant part of the Natural
open Interface is specified as
NATvrs; this is also the name of the
common memory pool into which the reentrant part will be loaded.
|
| 3 | A TABLE macro call is to be executed for program
TACSWTCH. This means that this program must be linked in the
front-end part of the Natural openUTM application.
|
| 4 | The Natural openUTM application runs in 24-bit addressing mode. |
| 5 | The access method to the Natural roll file is specified as
UPAM with P1-Eventing for asynchronous
writes.
|
| 6 | The maximum thread size of the Natural roll file is specified
as 180 (KB).
|
| 7 | The internal terminal control table is allocated in the Natural swap pool; the logical terminal name will be used for identifying the entries in the terminal control table. |
| 8 | The user dialog with Natural is to take place in "single" mode; that is, one terminal can initiate one Natural session. Messages at restart, logoff and also free-running messages (asynchronous processing) are to be output in German. |
The operands of the other parameters of macro NATUTM are
not specified since the default values apply.
Assemble the macro NURENT (the reentrant part of the
Natural openUTM Interface). In this example, no changes are required
to the parameters. The CSECT name of the assembled macro
NURENT is NURENT.
Assemble the macro BS2STUB with the common memory pool
definitions specified in macro
ADDON.
Assemble the Natural parameter module. The sample
NTPRM macro
call must be adapted to suit the local environment.
Assemble the swap pool parameter module (macro
NTSWPRM).
The Natural environment-dependent nucleus and the
environment-independent nucleus can be linked using the JCL supplied. This JCL
should be checked and modified as required to suit the local environment
(library names, etc.) before being used. Special features in the JCL are
indicated by REMARK statements.
The size of the Natural swap file must be calculated and the file must
be allocated with link name PAMNAT.
JCL examples for starting the Natural openUTM application are supplied. Before use, the JCL should be checked and modified as required (openUTM startup parameters, data set names, etc.).
The following points should be considered if the performance of a Natural openUTM application is unsatisfactory:
Can poor performance be localized to one or more particular
Natural programs?
If so, optimize the program(s) by redesigning. These programs can be
identified by using the Natural monitor in library SYSTP.
Is the swap I/O rate too high?
By using the program MENU in library SYSTP
you can check how efficiently the Natural swap pool is being used. The
statistical information provided about the swap pool also helps to answer the
following questions:
Is the number of logical swap pools and their slot lengths
appropriate?
Function SW in the main menu of SYSTP
offers various possibilities for controlling the Natural swap pool
optimization.
Has the Natural swap pool been defined large enough?
Increasing the size of the swap pool and/or generating
swap pool data space
reduces the swap I/O rate considerably.
Is the Natural buffer pool too small?
Information about the size and occupancy of the Natural buffer pool
can be obtained with the Natural utility SYSBPM, which is described
in the Natural Utilities documentation.
Has the number of openUTM tasks been chosen
correctly?
This is strongly dependent upon the path lengths of the individual
transactions and the number of terminals connected.
Is it possible that particular transactions (so-called long jobs)
are loading the available openUTM tasks so heavily that the shorter
transactions are suffering from poor throughput as a result?
If this is the case, the openUTM TACCLASS concept and/or the
asynchronous transaction processing facilities should be used.
Does the Natural Roll File consist of too many extents on one disk
drive (physical chained I/O is not possible over extent boundaries), or is the
Natural Roll File on a very heavily used disk drive?
If possible, allocate the Natural Roll File to one or more
lightly-used disk drives, with only one extent on each.
These suggestions should be considered in the light of the total system environment, including such factors as available storage, storage paging rates, disk and channel I/O traffic loads, etc.
For more information on the Natural nucleus components mentioned in this section, refer to Environment-Independent Nucleus and Environment-Dependent Nucleus in the Installation for BS2000 documentation.
To save storage space, it can be desirable for several Natural openUTM applications to share the environment-independent nucleus in a common memory pool in the class 6 storage. The following steps must be taken when generating the Natural openUTM application:
The global Natural load pool must be defined with the parameters of module CMPSTART, for example:
NAME=NATSHARE,POSI=ABOVE,ADDR=250,PFIX=YES,SIZE=2MB LIBR=NATvrs.USER.MOD
where vrs represents the current
product version
number.
For more information, see CMPSTART Program in the Natural Operations documentation.
Notes:
NATSHARE is the name of the linked
environment-independent
nucleus. It is also the name of the common memory pool.
PFIX must be
YES.
ADDR must be
defined.
LIBR must contain
the name of the module library from which the environment-dependent nucleus is
to be loaded.
NURENT) must be linked to the
environment-dependent nucleus.
NUCNAME must be
defined for each assembly of macro NATUTM as the same (in this
example: NUCNAME=NATSHARE).
ADDON macro
for the assembly of macro BS2STUB must be the same for all
applications, for example: STUBSHAR BS2STUB
PARMOD=31,PROGMOD=ANY ADDON NAME=NATSHARE,STAT=GLOBALFor more information, see ADDON Macro in the Natural Operations documentation.
If application-specific Natural parameter modules are to be used, they must be linked to the environment-dependent nucleus, which means that there is a parameter module in each environment-dependent nucleus. This also applies to the swap pool parameter module.
Only the addresses defined in the CSTATIC list of the
parameter module of the environment-dependent nucleus are considered in the
entry point table of callable 3GL programs; if any of these addresses cannot be
resolved in the environment-dependent nucleus (because they refer to modules
which are linked to the
environment-independent
nucleus), Natural tries to resolve these addresses with the
CSTATIC list in the parameter module of the reentrant part. Thus
it is allowed to have unresolved CSTATIC addresses when linking
the environment-dependent nucleus, provided they can be resolved by the
environment-independent nucleus.
As the CSTATIC list of the environment-independent nucleus
is only used for those addresses which cannot be resolved by the
environment-dependent nucleus, all CSTATIC entries to be
used (whether they are in the environment-dependent nucleus or in the
environment-independent nucleus) must be defined in the CSTATIC
list of the parameter module of the environment-dependent nucleus.
The following possibilities exist for entering and defining the Natural dynamic parameters:
entering the dynamic parameters together with the openUTM TAC when logging on to the application;
passing the dynamic parameters from another openUTM partial
program using MPUT and PEND
PR(OGRAM);
defining the dynamic parameters in the operand of the parameter
MSPAR1. They then apply to all users of this application
and cannot be changed.
When a Natural session is started, any Natural dynamic parameters
defined are saved up to a length which is defined in the operand of parameter
SVDYPRM in macro NATUTM. In case of a user
restart situation, these saved data are automatically reused when the Natural
session is started again. This also applies when the start of the Natural
session results from a PEND PR(OGRAM) of another
openUTM partial program.
See also Global (Restartable) Swap Pool in the Natural Operations documentation.
Adabas priority control has no connection with the priority control of
BS2000. Unlike with BS2000 priority control, for Adabas a higher priority value
means higher priority. If several requests are in the Adabas command queue at
the same time, the request with the highest priority is processed first by
Adabas and 1 is added to the priority of the other requests that
are in the command queue at this time.
Under certain conditions, it may be useful to assign to the Adabas task a lower BS2000 priority than to the openUTM tasks.
The following parameters in macro NATUTM can be used to control Adabas
priority control for openUTM transactions:
ADAPRI
|
Activation of Adabas priority control for openUTM transactions. |
APRISTD
|
Assignment of standard Adabas priority for all openUTM transactions to which no priority is assigned individually. |
TCLS
n
|
Assignment of Adabas priority for individual synchronous openUTM transactions. |
TCLA
n
|
Assignment of Adabas priority for individual asynchronous openUTM transactions. |
If Adabas priority control is activated for openUTM
transactions (parameter ADAPRI=YES), it is also in effect for
non-Natural programs which access Adabas via the subroutine
ADACALL; see the parameter ADACALL in the macro NATUTM.
By defining different Adabas priorities for different transactions with the above parameters, and at the same time using the openUTM TACCLASS concept, it is possible to set up a very sophisticated system of priority control. However, when you explicitly assign Adabas priorities to openUTM transaction, you should take into consideration the standard priorities Adabas assigns to other processes (for example, TIAM or batch processing).