Natural User Exits

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


NATUEX1 - User Exit for Authorization Control

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.

NATSREX2 and NATSREX3 - User Exits for Sort Processing

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.

NATUSKnn - User Exit for Computation of Sort Keys

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.

Sample User Exit Programs

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.

NATPM - User Exit for Inverted Output

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.

Inversion Logic

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.

Field User Exit

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 - User Exit for NATRJE

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.

USR0070P - User Exit for Editor Profiles

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.

USR2002P - User Exit for Help Window Text Strings

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.

USR2003P - User Exit for Main Menu

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.