User Exits

#### Search Results

Search

# User Exits

This section describes the user exits available with Natural Security. It contains information on:

- Logon-Related User Exits

- RPC-Related User Exit

- Other User Exits

## Logon-Related User Exits

The following logon-related user exits are available:

- LOGONEX0

- LOGONEX1

- LOGONEX2

- LOGONEX3

- LOGONEX5

- LOGONSX1

Note
The user exit `LOGONEX4` is not related to Natural Security's regular logon handling, but is only relevant in in conjunction with a logon of an RPC client to a Natural RPC server in an RPC environment. It is described under RPC-Related User Exit below.

#### General Information on Sources and Objects

`LOGONEX0`, `LOGONEX1`, `LOGONEX2`, `LOGONEX3`, `LOGONEX5` and `LOGONSX1` are Natural subprograms which have to be stored in the library `SYSLIB` to be invoked.

The corresponding sources and object modules of these user exits are available in the library `SYSSEC` under the following names:

User Exit in SYSLIB | Sources and Object Modules in SYSSEC
--- | ---
`LOGONEX0` | `NOGONEX0`
`LOGONEX1` | `NOGONEX1`
`LOGONEX2` | `NOGONEX2`
`LOGONEX3` | `NOGONEX3`
`LOGONEX4` | `NOGONEX4`
`LOGONEX5` | `NOGONEX5`
`LOGONSX1` | `NOGONSX1`

You can modify each of the user exits to suit your requirements. To do so, you make a copy of `NOGONEXn` (`n` = `0`, `1`, `2`, `3` or `5`), store it under the name `LOGONEXn`, make your adjustments to it, and then copy it into `SYSLIB`.

To ensure that the user exits are always present in `SYSLIB`, Natural Security proceeds as follows: The installation procedure, after loading all modules into their respective libraries, checks whether there already is a subprogram `LOGONEXn` contained in `SYSLIB`. If there is, it will be left untouched. If there is not, the object module of `NOGONEXn` will automatically be copied from `SYSSEC` to `SYSLIB` and stored there under the name `LOGONEXn`. At the same time, this ensures that your customized versions of the user exits are not accidentally overwritten by an installation procedure.

The above also applies to the user exit `LOGONSX1/NOGONSX1`.

### LOGONEX0

If the option Password phrases active in User Preset Values is set to `Y` or `A`, `LOGONEX0` (instead of `LOGONEX1`) is invoked by the Natural Security logon program.

Unless modified, `LOGONEX0` invokes the Natural Security logon screen (map `LOGONMX1` or dialog box `GLOGONMX1`; see Logon Screen / Logon Dialog Box). By modifying `LOGONEX0` you can invoke your own logon screens.

`LOGONEX0` supports the use of password phrases, that is, passwords which are longer than 8 characters.

### LOGONEX1

If the option Password phrases active in User Preset Values is set to `N`, `LOGONEX1` (instead of `LOGONEX0`) is invoked by the Natural Security logon program.

Unless modified, `LOGONEX1` invokes the Natural Security logon screen (map `LOGONM1` or dialog box `GLOGONM1`; see Logon Screen / Logon Dialog Box). By modifying `LOGONEX1` you can invoke your own logon screens.

`LOGONEX1` only supports the use of "regular" passwords of up to 8 characters.

### LOGONEX2

`LOGONEX2` is invoked by the Natural Security logon program under any of the following conditions:

- when `#` is entered as the library ID (or is passed from `LOGONEX1` as library ID);

- when no library ID has been specified for the logon and neither a default library nor a private library exists which could have been invoked (see also Logon Without Library ID in the section Logging On).

When `LOGONEX2` is invoked, the user ID and password have already been checked and found valid by the logon program. At this point, the Natural system variable `*USER` contains a valid value, which may be used.

Unless modified, `LOGONEX2` consists of nothing but an `END` statement. On return to the logon program, a valid library ID must be passed to the logon program, otherwise the logon will be rejected. Moreover, it is possible to return one of possibly several IDs using which a user is linked to a library.

As the user ID/password check has already established the validity of the user-specific logon data when `LOGONEX2` is invoked, `LOGONEX2` may be used to implement additional user-specific procedures or to request user-specific data. For example, the application programming interface `SECNOTE` may be invoked to read user security notes.

When the logon program invokes `LOGONEX1` or `LOGONEX2`, it passes the parameters `PUSERDUMMY1` and `PUSERDUMMY2` to the subprograms. Both parameters are provided for your use; their format/length is A8. You may assign values to these parameters in `LOGONEX1` and subsequently use these values in `LOGONEX2`, as they are passed without modification from one subprogram to the other.

### LOGONEX3

`LOGONEX3` is invoked by the Natural Security logon program under any of the following conditions:

- if there are mailboxes to be displayed;

- if at least one of the parameters `PUSERDUMMY1` or `PUSERDUMMY2`, passed from `LOGONEX1` or `LOGONEX2` respectively, is not blank.

`LOGONEX3` is invoked immediately after a successful logon and before control is passed from the logon program to the library invoked; when `LOGONEX3` is invoked, logon processing is completed except for the display of the mailboxes.

If `LOGONEX3` is left unmodified, it performs the subprogram calls necessary for the display of mailboxes.

You may modify `LOGONEX3` for one of the following purposes:

- to suppress the display of mailboxes;

- to have non-library-specific processing to be carried out immediately after a successful logon but before any library-specific transactions are executed.

### LOGONEX5

`LOGONEX5` is invoked by the Natural Security logon program whenever the system command `LOGOFF` is executed.

### LOGONSX1

This user exit is only available on Linux and Windows.

If the Authentication Type is set to "LDAP" in the LDAP security profile, `LOGONSX1` - instead of `LOGONEX1` - is invoked by the Natural Security logon program.

Unless modified, `LOGONSX1` invokes the Natural Security logon screen (map `LOGONSM1` or dialog box `GLOGONS1`; see Logon Screen / Logon Dialog Box).

By modifying `LOGONSX1` you can invoke your own logon screens.

## RPC-Related User Exit

The user exit `LOGONEX4` is a Natural subprogram which is only used in an RPC environment. It is invoked by the Natural Security RPC logon program after a successful logon of an RPC client to a Natural RPC server.

Note
The logon of an RPC client to a Natural RPC server does not cause any of the user exits described under Logon-Related User Exits (see above) to be invoked.

Invoking `LOGONEX4` is always the last task performed by the logon program when all other logon processing has been completed, and before an RPC service is performed. At this time, the user ID and password have already been checked and found valid by the logon program, and the Natural system variables `*USER` and `*LIBRARY-ID` contain valid values, which may be used.

In conversational mode, the user exit is invoked when the conversation is started.

The input parameters for the user exit are the library ID and subprogram name. The output parameter of the user exit is a return code; this may be used to terminate the RPC logon with a non-zero return code. If this is the case, Natural issues error NAT1696 with reason code 10.

A sample source module for `LOGONEX4` is available in the library `SYSSEC` under the name `NOGONEX4`. To invoke the user exit, its object module has to be stored under the name `LOGONEX4` in the library `SYSTEM` on the FNAT system file assigned to the RPC server. After copying it to this library, the RPC server has to be restarted.

Once the user exit has been invoked, it remains active until the end of the RPC server session.

To deactivate the user exit, you have to first terminate the RPC server, and then remove the object `LOGONEX4` from the library `SYSTEM`.

Do not remove `LOGONEX4` while an RPC server session using that FNAT system file is still active, because this would make the RPC server session inoperable (error NAT0082 would be issued at the next logon to the RPC server).

## Other User Exits

The library `SYSSEC` contains several other user exits:

User Exit | Function
--- | ---
`NSCXXEX1` | where `XX` is the object type: `US` = user, `LI` = library, `SF` = environment, `DD` = DDM, `FI` = file, `UT` = utility, `OB` = external object, `MA` = mailbox. The object-type-specific `NSCXXEX1` user exit is invoked immediately after a maintenance function for an object of this type has been performed.
`NSCUSEX2` | This user exit is invoked when you use the function Edit Group Members and `CATALOG` the changes you have made. It displays a list of the group's members, indicating which members have been added to the group and which have been removed from it.
`NSCXXEX3` | where `XX` is the object type: `US` = user, `LI` = library, `DD` = DDM, `FI` = file, `OB` = external object, `MA` = mailbox. The object-type-specific `NSCXXEX3` user exit is invoked when a maintenance function for an object of this type has been invoked and after data have been entered - but before these data are validated and processed by Natural Security. The sources of `NSCXXEX3` are supplied under the names `ESCXXEX3`. The activate one of them, you have to catalog it under the name `NSCXXEX3` in the library `SYSSEC`.

The parameters of these user exits are not modifiable.

For details, see the source codes of the user exits themselves.

### On this page

- Logon-Related User Exits
- RPC-Related User Exit
- Other User Exits