This section describes the user exits available with Natural Security. It contains information on:
The following logon-related user exits are available:
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.
LOGONEX1
, LOGONEX2
,
LOGONEX3
, LOGONEX5
and LOGONSX1
are
Natural subprograms which have to be stored in the library SYSLIB
to be invoked.
The sources and object modules of these user exits are available in the
library SYSSEC
under the names NOGONEX1
,
NOGONEX2
, NOGONEX3
, NOGONEX5
and
NOGONSX1
respectively.
You can modify each of the user exits to suit your requirements. To do
so, you make a copy of NOGONEXn
(n
= 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
.
LOGONEX1
is invoked by the Natural Security logon program
and, unless modified, 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.
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
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
is invoked by the Natural Security logon program
whenever the system command LOGOFF
is executed.
This user exit is only available on UNIX 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.
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).
The library SYSSEC
contains several other user exits:
User Exit | Function |
---|---|
NSCXXEX1
|
where
The object-type-specific
|
NSCUSEX2 |
This user exit is invoked when you use the function
Edit Group Members and
|
NSCXXEX3
|
where
The object-type-specific
The sources of |
The parameters of these user exits are not modifiable.
For details, see the source codes of the user exits themselves.