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
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.
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.