Calling flow between Classic Interface and user security exit

Calling flow between the Classic User Interface and your user security exit routine takes place at initialization, during command verification, at relogon, and at termination.

Calling flow at initialization

At initialization, the Classic User Interface passes control to your user exit routine. The initialization call is indicated by an I in the U#CHTYP field. This indicates that the Classic User Interface requires a logon validation.

This list shows the conditions that apply to the calling flow at initialization:

  • If the user ID field length is nonzero, the user ID and password information are available.
  • If additional information or some form of retry is required, the routine can request a reshow of the screen. It can also reset any field lengths to indicate that no data, such as user ID, password, group, or new password, is available.

    To perform a reshow in VTAM® mode, perform these steps:

    1. Set a message of up to 120 bytes length in the U#CHMSG field.
    2. Set the U@CHRSHO bit in the U#CHRESP field.
    3. Return to the caller.

    The message appears below the panel. Appropriate fields, such as original user ID and password, are filled in, unless overridden (length = 0).

  • After validation is complete, a return code of 0 from the user exit indicates that the user is allowed to log on.

    Any other return code stops the session.

  • After successful logon, the validation routine can perform resource validation.

    Optionally, it assigns a command security level (0, 1, 2, or 3) to the user. The default level is 0.

    Place the appropriate number into the U#CHAUT4 field. To force the user to use only this level, you must also set the U@CH1LOK bit in the U#CHAUT1 field.

Calling flow during command verification

During command verification, the Classic User Interface places a C in the U#CHTYP field. At this point, the user authorization can be checked.

If a command is allowed, the user can use this account on subsequent tries until security is reset with the /PWD command.

If a command is not allowed, the user cannot use this account on subsequent tries until security is reset with the /PWD command.

Each time the user attempts to use the command, the user exit is notified. Also, an audit record can be written, and a customized error message can be issued.

Return codes from the exit routine can be:

RC = 0
Indicates that the command is allowed.

For RACF® and ACF.

RC = 4
Indicates that the command is unknown.

The Classic User Interface allows the command to execute. For information about how to define a command to RACF, refer to Modifying RACF security rules.

For RACF only.

RC = 8
Indicates that the command is known to the security package and that access is denied.

For RACF and ACF.

Important: When you authorize commands, the Classic User Interface modifies the command name. For example, it makes the following replacements:
  • It replaces the slash of the INFO-line commands with a dollar sign. For example, /ccccc becomes $ccccc.
  • It replaces the period of the immediate commands with @. For example, .cccc becomes @cccc.

Calling flow at relogon

At relogon, the Classic User Interface places an R in the U#CHTYP field to indicate a logon validation.

The processing is identical to the one for initialization, except that users might not enter a new password or group because the Classic User Interface does not display the logon panel.

Calling flow at termination

At termination, the Classic User Interface passes a T to the user exit routine.

You can then do any termination cleanup required, such as freeing user control blocks, or perform a FREEMAIN for any GETMAIN areas.