A Natural user exit is a programming object that is invoked by Natural, a subcomponent or a subproduct. Usually, a sample user exit is delivered in source form. The instructions contained in the user exit have to be written or adjusted by the user. The purpose of a user exit is to manipulate data or make decisions. Most user exits take advantage of the Natural programming language; a small subset has to be written in Assembler language.
This document describes the following Natural user exits:
Other Natural user exits and application programming interfaces are described in the relevant places in the Natural subcomponent or subproduct documentation (Natural RPC, TP Monitor Interfaces, Utilities, add-on products, etc.).
The user exit NATUEX1 is called whenever a user session is
activated. It can be used to determine whether or not the user is authorized to
use Natural. The security data used to determine this can be retrieved from the
security system being used (for example, RACF or ACF2).
NATUEX1 is called using standard calling conventions:
| Register | Contents |
|---|---|
|
15 |
Entry address of NATUEX1 |
|
14 |
Return address of Natural |
|
13 |
Address of a save area of 18 words |
|
1 |
Address of a parameter list |
The parameter list contains five addresses:
| Address | Points to an 8-byte field containing the value which is used to fill the Natural system variable |
|---|---|
|
1 |
*INIT-USER |
|
2 |
*ETID |
|
3 |
*INIT-ID |
|
4 |
*INIT-PROGRAM |
|
5 |
*USER (Note that this system
variable will be overwritten during a Natural Security logon.)
|
These five values can be modified by the user exit.
For normal completion, the user exit must return control with Register
15 set to 0. If Register 15 does not contain 0, the
Natural session is terminated with the condition code equal to the value in
Register 15.
NATUEX1 can be linked to a shared nucleus or to an
environment-independent nucleus. It is also possible to link it to an
alternative parameter module, or as a separate module if you are running with
profile parameter RCA.
An example of the user exit is available as member XNATUEX1
in the Natural source library.
For CICS: See also NCIUIDEX - User ID Exit Interface in the Natural TP Monitor Interfaces documentation.
Natural provides two user exits for sort processing:
NATSREX2 and NATSREX3.
The two user exits can be used with Natural's own sort program as well
as with an external sort program. The exits are activated automatically when
they are linked to the nucleus and so their addresses get resolved. Since,
under z/OS and z/VSE, many external SORT programs already supply
several exit functions, the exits NATSREX2 and
NATSREX3 may especially be used either with Natural's internal
sort program or with external SORT under BS2000/OSD.
NATSREX2 is always called when Natural passes a record to
the sort program. NATSREX3 is called when the sort program, upon
completion of the sort run, passes a record to Natural. The example delivered
shows how you can establish your own collating sequence for a
SORT.
When the user exits are activated, the following register conventions must be adhered to:
| Register | Contents |
|---|---|
|
15 |
Entry addresses of NATSREX2 and
NATSREX3 |
|
14 |
Return address of Natural |
|
13 |
Address of the 18-word save area |
|
1 |
Address of the sort record |
|
3 |
Length of the sort record |
The user exits have to secure the Natural registers and restore them upon returning control to Natural.
As the sort exit module is linked to the module NAT2SORT,
programming has to be reentrant. The format and structure of the sort records
must not be modified.
Some national languages contain characters which are not sorted in the
correct alphabetical order by a sort program or database system. With the
system function SORTKEY you can convert
such "incorrectly sorted" characters into other characters that
are "correctly sorted" alphabetically.
When you use the SORTKEY function in a Natural program, the
user exit NATUSKnn will be invoked -
nn being the current language code
(that is, the current value of the system variable
*LANGUAGE).
You can write a NATUSKnn user
exit in any programming language that provides a standard CALL
interface. The character string specified with SORTKEY will be
passed to the user exit. The user exit has to be programmed so that it converts
"incorrectly sorted" characters in this string into corresponding
"correctly sorted" characters. The converted character string is
then used in the Natural program for further processing.
For the conversion, NATUSKnn may
use the translation table NTUTAB1 of the configuration module
NATCONFG; this means
that NTUTAB1 may have to be adjusted accordingly.
NATUSKnn is called using
standard calling conventions:
| Register | Contents |
|---|---|
|
15 |
Entry address of
NATUSKnn
|
|
14 |
Return address of Natural |
|
13 |
Address of a save area of 18 fullwords |
|
1 |
Address of a parameter list |
The parameter list contains the following addresses:
| Offset | Address of |
|---|---|
|
+0 |
The character string passed from Natural. |
|
+4 |
The length of the character string (fullword). |
|
+8 |
The character string resulting from the conversion. |
|
+12 |
The length of the result string (fullword). |
|
+16 |
The translation table NTUTAB1.
|
NATUSKnn has to to secure all
registers, except 14 and 15, and restore them upon returning control to
Natural.
For normal completion, the user exit must return control with Register 15 set to Return Code 0. If Register 15 does not contain "0", a corresponding Natural error will be issued.
The following sample user exits are provided in source code form:
| Program | Function |
|---|---|
NATUSK01 |
Applies to English and converts all English lower-case letters in the character string to upper-case. |
NATUSK02 |
Applies to German and converts the German umlauts ä, ö, ü, and ß into their corresponding replacement characters ae, oe, ue, ss in order to provide a different sort sequence. |
When a shared nucleus is used,
NATUSKnn can be linked to the
environment-independent part of the nucleus.
It is also possible to link it to an alternative parameter module, or as
a separate module if you supply the name(s) of the invoked
NATUSKnn module(s) with the profile
parameter RCA.
For linkage and loading conventions, see also the
CALL statement in the
Natural Statements documentation.
The NATPM module is used to support inverse direction
terminals. It contains the user exit routine for field and line conversion
which is called by Natural at terminal I/Os if for some fields the print mode
(profile parameter PM) has been set to
I.
PM=I indicates inverse direction and is used to support
languages writing from right to left (for example, bi-directional languages);
see also the description of the profile parameter
PM.
The module NATPM is delivered as a source module and can be
modified if required.
Natural provides a user-exit routine which is called for each field
where the resulting attribute is PM=I and for each line to be
printed via hardcopy, additional report and primary batch output. This exit is
called with three parameters:
the source field to be inverted,
the target field to receive the inverted data,
a length field specifying the length of the source and target fields.
As this user exit routine is available in source code to all users, it
might be used as an explicit field exit triggered by the PM=I
attribute. The user is then able to check and modify line contents or field
contents.
The user exit in NATPM will be called for every field
where the attribute PM=I is set.
This attribute can be set by the Natural programmer, or is
automatically set for numeric fields when the global print mode is set to
PM=I. It does not matter whether the output is generated for the
terminal, for hardcopy, for additional reports or for the primary output in
batch.
For printing devices, Natural does not expect automatic inversion from
the hardware, but calls NATPM again for the complete line. This
feature can be used in countries where the field inversion is not required to
establish interface logic with Natural based on a field attribute.
NREXPG is a user exit for
Natural Remote Job Entry
(NATRJE). After the job is complete, each JCL card is passed to
the exit before it is submitted to the operating system. The following data are
available to the exit:
the JCL card to be submitted,
a return code field,
the name of the Natural program currently being executed,
the Natural user identification,
a 240-byte work area.
After each call, the exit passes a return code to NATRJE
indicating one of the following events:
| Code | Explanation |
|---|---|
0 |
Submission: the card is submitted; the exit may modify the card before submission. |
4 |
Termination: the card is submitted; the exit is disabled for further cards of the current job. |
8 |
Insertion: the card is skipped based on the assumption that it contains only an insert character, for example, the percent sign (%); additional specified cards are submitted. |
10 |
Deletion: the card is not submitted. |
12 |
The current job is flushed. |
An example of the user exit, called NREXPG,
is available as member XNATRJE in the Natural source library. The
exit can be assembled and linked according to the rules of programs specified
as CSTATIC. However, a CSTATIC entry for
NREXPG is not required.
The user exit routine USR0070P enables you to modify the
parameter settings for the Natural program editor or data area editor in the
default profile SYSTEM.
For further information on the editor profile, see General Information in the Editors documentation.
USR0070P provides a list of all parameters which are to
receive a default setting.
With this user exit, you can also determine whether editor profiles are
to be stored in the FNAT system file, the FUSER
system file or the scratch-pad file.
In addition, USR0070P considers DBCS support and sets the
editor profile options Editing in Lower Case and Dynamic
Conversion of Lower Case correspondingly.
An example of this user exit routine is available in the library
SYSEXT on the
FNAT system file, both in object and source form. Information on
how to use it is contained in the text member USR0070T.
The user exit routine USR2002P can be used to customize the
text strings for the Current Natural Message window that
is invoked by pressing the Help key while the cursor is on the message line.
The object USR2002P itself contains the text strings used
within the Current
Natural Message window, for example, the window title and the
descriptive texts, such as, the field names Sh (short message),
Tx (long message), Ex (explanation) and
Ac (action).
An example of this user exit routine is available in the library
SYSEXT on the
FNAT system file, both in object and source form. Information on
how to use it is contained in the text member USR2002T.
The user exit routine USR2003P can be used to customize the
following settings for the
Natural Main
Menu and its subordinate menus:
position and color of the message line,
position and color of the PF key lines.
An example of this user exit routine is available in the library
SYSEXT on the
FNAT system file, both in object and source form. Information on
how to use it is contained in the text member USR2003T.
