Natural User Exits

#### Search Results

Search

# 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:

- NATUEX1 - User Exit for Authorization Control

- NATSREX2 and NATSREX3 - User Exits for Sort Processing

- NATUSKnn - User Exit for Computation of Sort Keys

- NATPM - User Exit for Inverted Output

- NREXPG - User Exit for NATRJE

- USR0070P - User Exit for Editor Profiles

- USR2002P - User Exit for Help Window Text Strings

- USR2003P - User Exit for Main Menu

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 the following 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.)
6 | Address of work area (6KB length)

The values of addresses 1 to 5 can be modified by the user exit. Address 6 points to an area of 6KB that can be used as working storage.

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

### On this page

- NATUEX1 - User Exit for Authorization Control
- NATSREX2 and NATSREX3 - User Exits for Sort Processing
- NATUSKnn - User Exit for Computation of Sort Keys
- NATPM - User Exit for Inverted Output
- NREXPG - User Exit for NATRJE
- USR0070P - User Exit for Editor Profiles
- USR2002P - User Exit for Help Window Text Strings
- USR2003P - User Exit for Main Menu