A Natural user exit is an 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 the environment-independent nucleus or to an
environment-dependent nucleus. It is also possible to link it to an alternative Natural 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.
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 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. |
NATUSKnn can be linked to the
environment-independent nucleus or to an environment-dependent nucleus. It is also
possible to link it to an alternative Natural
parameter module, or as a separate module if you are running with profile
parameter RCA=NATUSKnn.
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 object 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 object 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 object USR2003T.