This part of the Natural openUTM Interface documentation covers the following topics:
When used in this document, the notation vrs or vr represents the relevant product version (see also Version in the Glossary).
Several user exits are provided in the Natural openUTM Interface. These are described below.
To use any of these exits, the corresponding user program must be linked
with the Natural
environment-dependent
nucleus (see the Installation documentation).
The user exit RP2PRNT is an exception.
User exit routines are called with the customary register conventions.
ACCEXIT |
ACCINIT |
INPTEX |
RP2PRNT |
RMSPOOL |
SHUTALL |
SHUTLST |
STRTALL |
STRTFST |
TRMIOEX |
UINPEX |
UOUTEX |
UVGEXIT |
WHCEXT
The user exit ACCEXIT can be used to retrieve accounting
information. Depending on the value of the parameter ACCNT in macro
NURENT, this user exit is activated either at the end of each
dialog step or at each change of application (new Natural logon ID); see also
Accounting for
Natural openUTM Applications.
The user exit ACCINIT can be used to gather accounting
information. It is activated at the beginning of each dialog step; see also
Accounting for
Natural openUTM Applications.
The user exit INPTEX is activated whenever an input
message is read. See also the description of the program
INPTEX in
the section Utility Programs
for Use with Natural under openUTM.
The user exit RP2PRNT is intended as an interface to other
manufacturers' spooling systems. The user exit routine (spooling program) must
be reentrant and linked with the reentrant part of the Natural openUTM
application. See also Other Spooling
Systems and the description of the parameter
SPOOL in
the section Parameters of Macro
NATUTM.
If you wish to write your own spooling interface program, call it
RMSPOOL. The program RMSPOOL can be linked to the
non-reentrant part or to the reentrant part of the Natural openUTM
application. If it is to be linked to the reentrant part, the program itself
must be written so as to be reentrant.
Important:
If program RMSPOOL is to be used, the
SPOOL parameter in the macros
NATUTM and
NURENT must be set to
SPOOL=RMSPOOL.
The Natural openUTM Interface passes the following parameters
to program RMSPOOL:
| Address (Format/Length) | Contents | |
|---|---|---|
| 1st Address (A2) | Function code. Possible function codes are: | |
OP |
The print file has to be opened, and the first print record is passed. | |
PR |
Any subsequent print record is passed. | |
CL |
The print file has to be closed. | |
| 2nd Address | Print record (data to be
printed).
The first byte of the print record contains the line/form feed
character. (If function code |
|
| 3rd Address (B2) | Length of print record (including
feed character).
(If function code |
|
| 4th Address (A8) | Printer name. | |
| 5th Address | Print buffer.
This buffer can be used as work area by |
|
| 6th Address (B2) | Length of print buffer. | |
| 7th Address (A8) | Current user ID (as in the system
variable *USER).
|
|
| 8th Address (A8) | Current terminal ID (as in the
system variable *INIT-ID).
|
|
| 9th Address (A8) | Current Natural library name (as
in the system variable *LIBRARY-ID).
|
|
| 10th Address (A8) | Current Natural program name (as
in the system variable *PROGRAM).
|
|
| 11th Address (A4/B4) | Return code.
When |
|
The user exit specified with the SHUTALL parameter in macro
NATUTM is activated whenever a openUTM task is terminated
(KDCSHUTn). By default,
this user exit is SHUTEX1.
If the user exit specified with SHUTALL is
to be used, the parameter USAGE=SHUT in KDCDEF for
the Natural openUTM Interface must have been set when generating
KDCROOT.
The user exit specified with the SHUTLST parameter in macro
NATUTM is activated when the last openUTM task
is terminated (KDCSHUTn).
By default, this user exit is SHUTEX2.
If the user exit specified with SHUTLST is
to be used, the parameter USAGE=SHUT in KDCDEF for
the Natural openUTM Interface must have been set when generating
KDCROOT.
The user exit specified with the STRTALL parameter in macro
NATUTM is activated whenever an openUTM task is started.
By default, this user exit is STARTEX.
The user exit specified with the STRTFST parameter in macro
NATUTM is activated when the first openUTM task
is started. By default, this user exit is STAPPLX.
The user exit TRMIOEX is activated with each formatted input or output message.
The user exit specified with the UINPEX parameter in macro
NURENT is activated after a terminal message has been
sent. By default, this user exit is INPSCR.
Natural under openUTM passes the following parameters to the user exit:
| Address (Format/Length) | Contents |
|---|---|
| 1st Address | Address input buffer. |
| 2nd Address (B2) | Address message length. |
The user exit specified with the UOUTEX parameter in macro
NURENT is activated before a terminal message is to be
sent. By default, this user exit is OUTSCR.
Natural under openUTM passes the following parameters to the user exit:
| Address (Format/Length) | Contents |
|---|---|
| 1st Address | Address output buffer. |
| 2nd Address (B2) | Address message length. |
The user exit UVGEXIT is activated at the start, restart
and end (normal or abnormal) of an openUTM DC transaction. The current
task ID (Vorgangskennzeichen, KCKNZVG) is passed to the
user exit routine.
The user exit WHCEXT can be used to modify an output which
is to be printed before it is passed by FPUT to openUTM.
When WHCEXT is called, Register 9 contains the address of the
output to be printed and Register 13 the address of the save area.
WHCEXT must be reentrant and it must be linked to the
reentrant part of the Natural openUTM application. For further
information, please refer to the source listing of the assembled macro
NURENT (Label 'NUWHC').
To start an asynchronous transaction, the service routine
NATASYN in the Natural openUTM Interface has to be
called.
The start of an asynchronous transaction in a Natural program is done by passing dynamic parameters according to the following pattern:
... COMPRESS dynamic parameters INTO field CALL 'NATASYN'[parameter area SET CONTROL 'H' WRITE NOTITLE NOHDR field [WRITE ...] INPUT 'text' ifield (A1) END
If the length of the dynamic parameters exceeds 250 bytes (that is, if
more than one WRITE statement is required), a parameter
area has to be passed with the CALL 'NATASYN' statement.
The parameter area is also required if the asynchronous transaction is
to be started with openUTM DPUT; that is, at a specific
time. The aggregate length of the dynamic parameters must not exceed 3750
bytes. The parameter area for the CALL 'NATASYN' has the
following structure:
| Bytes | Contents | |
|---|---|---|
| 01-02 | Number of WRITE
statements.
|
|
| 03 | DPUT time indicator:
|
|
R |
a relative time, | |
A |
an absolute time | |
| blank | FPUT |
|
| 04-06 | Day of the year. | |
| 07-08 | Hours. | |
| 09-10 | Minutes. | |
| 11-12 | Seconds. | |
For the contents of Bytes 03 - 12, the same rules apply as described for
DPUT calls in the respective openUTM documentation.
Natural programming examples can be found in the Natural library
SYSEXTP (programs STARTAS1, ASYNMULT,
STARTAS, READAUTO, AWINDOW1,
AWINDOW2).
For asynchronous transaction processing, KDCROOT,
KDCDEF and the openUTM startup job must be modified as
necessary (see the openUTM documentation).
All openUTM TACs for asynchronous transactions must begin with
the character sequence which is defined as a unique identifier for asynchronous
TACs in parameter ASYNTAC of macro
NATUTM. Conversely, the first five characters of openUTM
TACs for synchronous transactions must not be this character
string.
Mixed transaction processing (that is, both within a single openUTM application and between two openUTM applications) is not possible.
If transactions are to be processed asynchronously within a Natural
openUTM application, the operands of the parameters
SYAPPLI and
ASAPPLI of macro
NATUTM must be set to NO (this is the default
value).
This is an example of a Natural program that initializes an asynchronous transaction within a Natural openUTM application.
* STARTAS - EXAMPLE OF THE INITIALIZATION FOR ASYNCHRONOUS * TRANSACTION WORKING WITHIN ONE UTM APPLICATION * PARMS ARE SEPARATED BY ',' * SUBLIST IN STACK IS SEPARATED BY ';' FORMAT LS=145 RESET PARM1(A144) PRDEST(A8) LTDEST(A8) MOVE 'PRINTER1' TO PRDEST /* --> Note 1 MOVE *INIT-ID TO LTDEST /* --> Note 2 COMPRESS 'SENDER=' PRDEST ',OUTDEST=' LTDEST ',' 'MENU=F,STACK=(LOGON APPL1;READAUTO)' INTO PARM1 LEAVING NO /* --> Note 3 CALL 'NATASYN' /* --> Note 4 SET CONTROL 'H' /* --> Note 5 WRITE NOTITLE NOHDR PARM1 /* --> Note 6 INPUT 'ASYNTASK INVOKED - HOPEFULLY' IFELD(A1) /* --> Note 7 END
| Note | |
|---|---|
| 1 | The name (dummy) of a printer is moved into field
PRDEST.
|
| 2 | The logical name of the openUTM terminal is moved into
field LTDEST.
|
| 3 | The message that is to be sent and processed by Natural is
assembled, with the following information:
|
| 4 | When the subroutine NATASYN (in macro
NATUTM) is called, a marker is set to indicate that an
asynchronous transaction is to be initialized. The subroutine
NATASYN conforms to the conventions for calling non-Natural
programs.
|
| 5 | The Natural offline report is activated. |
| 6 | The message (PARM1) is output by FPUT
as an asynchronous transaction.
|
| 7 | The Natural offline report is "switched off" by
means of an INPUT statement that must have at least one input
field.
|
An example of the program that is to be executed asynchronously:
* READAUTO - EXAMPLE FOR ASYNCHRONOUS TRANSACTION WORKING
READ (75) AUTOMOBILES BY MAKE
WRITE MAKE MODEL HORSEPOWER YEAR
LOOP
ON ERROR DO /* --> Note 1
ERRNO(A4) = *ERROR
WRITE '********************************************************'
/'ERROR NO.: ' ERRNO ' IN ASYNCHRONOUS PROGRAM ' *PROGRAM
/'********************************************************'
TERMINATE
DOEND
TERMINATE /* --> Note 2
END
| Note | |
|---|---|
| 1 | An ON ERROR routine must be defined in each
program that is to be executed asynchronously. The routine must end with a
TERMINATE statement.
|
| 2 | Each program that is to be executed asynchronously must end
with a TERMINATE statement.
|
When processing transactions asynchronously between two Natural
openUTM applications, the logical openUTM terminal name
(LTERM name) of the synchronous application must be defined with
the parameter SYAPPLI of macro
NATUTM, and the logical openUTM terminal name
(LTERM name) of the asynchronous application must be defined with
the parameter ASAPPLI of macro
NATUTM.
 |
Warning:KDCROOT and KDCDEF must be generated as
appropriate for both applications. |
NUSTART NATUTM SYAPPLI=LNATUTM,ASAPPLI=LNATASY,... ASYNDRV NATUTM SYAPPLI=LNATUTM,ASAPPLI=LNATASY,...
OPTION GEN=ALL,ROOTSRC=INPUT.KDCROOT.KDCNATS ROOT.KDCNATS MAX KB=400,SPAB=8192,NB=5120,TRMSGLTH=520 MAX APPLINAME=NATUTM,APPLIMODE=S,KDCFILE=(NATUTM,S) MAX TASKS=10,ASYNTASKS=5 . . 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 . . DEFAULT TAC TYPE=D,PROGRAM=NUSTART,EXIT=NUERROR,CALL=BOTH,... TAC NAT,ADMIN=NO,TIME=0 TAC NAT1,ADMIN=NO,TIME=0 . . DEFAULT TAC TYPE=A,PROGRAM=NUSTART,EXIT=NUERROR,CALL=FIRST,... TAC NATSY TAC NATAS . . PTERM NATASY,PRONAM=HOST,PTYPE=APPLI,TERMN=A1,LTERM=LNATASI DEFAULT PTERM PRONAM=PCDF,PTYPE=T9750,TERMN=FE,CONNECT=N,STATUS=ON PTERM DFDSS001,LTERM=DF97501 PTERM DFDSS002,LTERM=DF97502 . . LTERM LNATASY DEFAULT LTERM USAGE=D,STATUS=ON,ANNOAMSG=Y,RESTART=YES LTERM DF97501 LTERM DF97502 . . SFUNC F1,RET=21Z . . END
OPTION GEN=ALL,ROOTSRC=INPUT.KDCROOT.KDCNATA ROOT.KDCNATA MAX KB=400,SPAB=8192,NB=5120,TRMSGLTH=520 MAX APPLINAME=NATASY,APPLIMODE=S,KDCFILE=(NATASY,S) MAX TASKS=10,ASYNTASKS=5 . . EXIT PROGRAM=ASYNDRV,USAGE=START EXIT PROGRAM=ASYNDRV,USAGE=SHUT EXIT PROGRAM=FREXIT,USAGE=FORMAT . . DEFAULT PROGRAM COMP=ASSEMB PROGRAM ASYNDRV PROGRAM FREXIT PROGRAM NUERROR . . DEFAULT TAC TYPE=D,PROGRAM=ASYNDRV,EXIT=NUERROR,CALL=BOTH,... TAC NAT,ADMIN=NO,TIME=0 TAC NAT1,ADMIN=NO,TIME=0 . . DEFAULT TAC TYPE=A,PROGRAM=ASYNDRV,EXIT=NUERROR,CALL=FIRST,... TAC NATSY TAC NATAS . . PTERM NATUTM,PRONAM=HOST,PTYPE=APPLI,TERMN=A1,LTERM=LNATUTM DEFAULT PTERM PRONAM=PCDF,PTYPE=T9750,TRMN=FE,CONNECT=N,STATUS=ON PTERM DFDSS001,LTERM=97501 PTERM DFDSS002,LTERM=97502 . . LTERM LNATUM DEFAULT LTERM USAGE=D,STATUS=ON,ANNOAMSG=Y,RESTART=YES LTERM DF97501 LTERM DF97502 . . SFUNC F1,RET=21Z . . END
Please see also the openUTM documentation. If the asynchronous application is primarily intended for processing asynchronous transactions, storage can be saved by generating this application with a small (local) Natural swap pool of about 64 KB.
Important:
The TAC that was defined with the parameter
SYNTAC (the
default value is NATSY) must always be defined for
KDCDEF with TYPE=A; this is an exception to the rules
for naming openUTM TACs. If, in addition, the synchronous application
uses the openUTM TACCLASS concept, an asynchronous TAC class must also
be allocated to this TAC
* ASYNAPPL - EXAMPLE OF INITIALIZATION FOR ASYNCHRONOUS
* TRANSACTION WORKING BETWEEN TWO UTM APPLICATIONS
FORMAT LS=145
RESET PARM1(A144) PRDEST(A8) LTDEST(A8) ASYNTAC(A8)
MOVE 'PRINTER1' TO PRDEST /* --> Note 1
MOVE *INIT-ID TO LTDEST /* --> Note 2
MOVE 'NATSY' TO ASYNTAC /* --> Note 3
COMPRESS 'NATAS' ' SENDER=' PRDEST ',OUTDEST=' LTDEST
',ASYNNAME=' ASYNTAC ','
'MENU=F,STACK=(LOGON APPL1;READAUTO)'
INTO PARM1 LEAVING NO /* --> Note 4
CALL 'NATASYN' /* --> Note 5
SET CONTROL 'H' /* --> Note 6
WRITE NOTITLE NOHDR PARM1 /* --> Note 7
INPUT 'ASYNTASK INVOKED - HOPEFULLY' IFELD(A1) /* --> Note 8
END
| Notes | |
|---|---|
| 1 | The name of a printer (simulation) is moved into the field
PRDEST.
|
| 2 | The logical name of the openUTM terminal
(KCLOGTER) is moved into the field LTDEST.
|
| 3 | The standard TAC for sending "free-running"
messages from the asynchronous application to the synchronous application is
put in the field ASYNTAC. See also the description of the
parameter SYNTAC
of macro NATUTM.
|
| 4 | The message that is to be sent and processed by Natural is
assembled, with the following information:
|
| 5 | When subroutine NATASYN (in macro
NATUTM) is called, a marker for the initialization of an
asynchronous transaction is set. The subroutine conforms to the conventions for
calling non-Natural programs.
|
| 6 | The Natural offline report is activated. |
| 7 | The message (PARM1) is output with
FPUT as an asynchronous transaction.
|
| 8 | The Natural offline report is "switched off" by
means of an INPUT statement with at least one input field.
|
The program to be executed asynchronously (READAUTO) must
conform to the conventions that apply to asynchronous transaction processing
within one Natural openUTM application.
The following topics are covered:
A Natural program that wishes to use local printers without spooling
(that is, with FPUT via openUTM), should proceed as shown
in the following example.
* TESTPRNT - TEST FOR THE Natural OFFLINE REPORT RESET PARAM(A9) REDEFINE PARAM (PARAM1(A1) PARAM2(A8)) MOVE 'H' TO PARAM1 /* --> Note 1 MOVE 'PRINTER1' TO PARAM2 /* --> Note 2 SET CONTROL PARAM /* --> Note 3 READ (50) AUTOMOBILES BY MAKE WRITE NOTITLE NOHDR MAKE MODEL HORSEPOWER YEAR /* --> Note 4 LOOP EJECT INPUT 'PRINT ORDER WAS EXECUTED' IFELD(A1) /* --> Note 5 END
| Notes | |
|---|---|
| 1 | The Natural offline report is activated by putting an
H in the first position of the field PARAM.
|
| 2 | The logical openUTM printer name is defined starting
at the second position of the field PARAM.
|
| 3 | The SET CONTROL statement, together with the
content of the field PARAM, activates the Natural offline report
and specifies the name of the printer. To ensure compatibility for existing
programs written using Natural Version 1, the programs CMLIST and
NATPRNT continue to be available; see
Utility
Programs for Use with Natural under openUTM.
|
| 4 | The print records are passed to openUTM from the
Natural openUTM Interface using FPUT.
|
| 5 | The INPUT statement (which must have at least one
input field) deactivates the Natural offline report.
|
All the necessary steps for using local printers must have been taken when generating openUTM; for further details, please refer to the openUTM documentation. The appropriate openUTM administration commands can be used to verify that a connection to the defined printers exists.
The parameter SPOOL of macro
NATUTM is provided for using NATSPOOL under
openUTM. Further details are given in the section
Parameters of Macro
NATUTM. Please refer also to the BS2000/OSD-specific
installation information in the Natural Advanced
Facilities documentation.
If in an asynchronous openUTM transaction printing is to be
done with NATSPOOL, the TERMINATE statement must be
preceded by an END OF TRANSACTION statement.
The User Exit RP2PRNT is provided for interfacing to other
spooling systems. This user exit is activated if REPRO-2000 is
specified with the parameter SPOOL in macro
NURENT. (This value should be used for all spooling systems.)
Since it must be linked with the reentrant part of the Natural
openUTM application, the user exit routine RP2PRNT must
be reentrant.
The logic of the transfer of print records from Natural, buffer
processing, etc., can be seen in macro NURENT (labels
CMWTERM and CMWHC) and the appropriate routines in
macro NATUTM.
As an alternative, it is possible to use the User Exit
RMSPOOL; see section
User Exits
above.
Software AG does not provide support for this interface to other spooling systems except as described in the preceding paragraphs.
Non-Natural programs are called using the standard register conventions
for inter-program communication. If the program to be called is reentrant (uses
shared code), it can be defined with the profile parameter
CSTATIC
in the Natural parameter module (macro
NTPRM)
and linked to the reentrant part of the openUTM application.
Otherwise, one of the following procedures can be used:
The programs can be dynamically loaded at runtime. To do this, the
programs must be in the library defined with the profile parameter
LIBNAM in
the Natural parameter module or in the BLSLIB libraries specified
in the openUTM start job;
The programs can be linked to the Natural
environment-dependent
nucleus (see the Installation documentation).
To do this, the names of the programs must be defined in the operand of the
parameter LINK,
LINK2,
LINK3 or LINK4 of
macro NATUTM. This procedure is always necessary for programs that
contain an EXTRN reference to an ENTRY that is
already present in the Natural
environment-dependent
nucleus. The Natural openUTM Interface executes a
TABLE macro call for the programs that have been defined in this
way. This makes an entry in the dynamic loader's LINK table,
indicating that it is not necessary to dynamically load the programs when they
are called by the Natural program.
In both cases, the maximum number of called non-Natural programs must be
defined with the parameter CDYNAM of macro
NATUTM; see Parameters of
Macro NATUTM.
Note:
If parameter KB in macro NATUTM
is set to YES, Natural always passes the address of the
openUTM communication area KB (Kommunikationsbereich) as the
first parameter address. This does not apply to programs which are defined with
profile parameter CSTATIC.
Several methods are provided for ending a Natural session
(FIN or TERMINATE) with a PEND PR(OGRAM)
instead of a PEND FI(NISH), so that another openUTM
partial program is called:
The openUTM TAC for the openUTM partial program that
is to be called can be passed using the Natural dynamic parameter
PROGRAM
at the start of the Natural session, for example:
STACK=(LOGON APPL1;MENU),PROGRAM=NAT10
The openUTM TAC for the openUTM partial program that
is to be called can be defined in the operand of the parameter
PENDPR of macro
NATUTM, for example:
NATUTM PENDPR='NAT10'
The utility program TACSWTCH can be
used.
In all cases, the Natural openUTM Interface would execute a
PEND PR(OGRAM) with the openUTM TAC NAT10 at
the end of the Natural session, which means that the openUTM partial
program associated with this TAC would be started.
Another way to execute a PEND PR(OGRAM) is by activating
the function key defined for this purpose, which suspends, but not terminates,
the Natural session. On return from the openUTM partial program with
PEND PR(OGRAM), the Natural session can be continued from the
point at which it has been suspended; see also the parameter
PRKEY. If the
function key for PEND PR(OGRAM) is activated without a
openUTM TAC for another openUTM partial program being
defined, an appropriate error message is displayed.
Note:
The programs NUEXAMPL, UTMNAV and
UTMCOB show
examples of the logic necessary in an openUTM partial program that
wishes to communicate with the Natural openUTM Interface (and
therefore with Natural itself) - see the descriptions of programs
UTMCOB and UTMNAV in the section
Software
Exchange.
If a Natural program calls a non-Natural program that also includes
Adabas calls, the appropriate field in the Adabas control block must be
supplied with the current Adabas user ID. In this case, generate the
CSECT ADACALL in the Natural openUTM Interface.
ADACALL contains an entry which is defined with the
parameter ADACALL in macro
NATUTM (the default value of this parameter is
ADABAS).
This entry is activated for every CALL [ADABAS] USING ....
The current Adabas user ID is passed to the field ADDITIONS2 of
the Adabas command block, and subsequent processing of the Adabas call is
passed to the Adabas interface module ADALNN; see also the
parameter ADACALL.
The Natural session (and thereby also the openUTM task) can be
abnormally terminated by entering the CANCEL parameter's
value of the Natural parameter module (default is *CANCEL in
upper-case letters).