User ID Security Exit Support › Logon Verification Call Parameter List

Logon Verification Call Parameter List

On entry to the security exit, Register 1 points to a list of ten full words, as shown in this diagram.

The contents of the parameter list are as follows:

• Word 1

  Is a full word containing the address of function code F'16'.

• Word 2

  Is the address of a subfunction code. This code defines the source of the logon verification call and has values set as follows:

  Subfunction Code	Value
  F'0'	Call is from an &SECCALL CHECK verb, the LOCK facility, or APPC region validation.
  F'4'	Call is from INMC link activation.
  F'8'	Call is from APPC link activation.

• Word 3

  Is the address of a 16-character field, blank-padded, containing the 8-character-character user ID whose password and logon capability is to be verified, followed by the 8-character system default MODLUSER name, or blanks if no model user has been defined.

• Word 4

  Is the address of three full words containing the user session correlator and the address of the user token (UTOKEN) of the submitter of the logon verification call, or zero if called from EASINET.

• Word 5

  Varies according to subfunction code:

  Subfunction Code	Value
  F'0'	Address of the 8-character terminal ID, followed by the 8-character user ID of the submitting user. This field can be blank; if so, treat the user ID being checked as the submitting user.
  F'4'	Address of the 8-character LU name of the link, followed by the 12-character NMPCID.
  F'8'	Address of the 35-character APPC link partners. The format of the link session partners is NETID.LU1.LU2 where NETID.LU1 is the source partner and LU2 is the destination LU of the APPC link.

• Word 6

  Varies according to subfunction code:

  Subfunction Code	Value
  Subfunction F'0'	Address of the 8-character, blank-padded user ID password.
  Subfunction F'4'	Word 6 is set to zero.
  Subfunction F'8'	Address of an 8-character area into which the exit can place the session key for this APPC link.

• Word 7

  Is set to zero.

• Word 8

  Is the address of an 82-character area into which the exit can place an error message. If an error message is returned, it must be formatted as follows:

  • Bytes 00 to 01

    Specifies the hexadecimal length of the message text (excluding these two bytes).

  • Bytes 02 to nn

    Specifies the error message text.

    Limits: 80 characters

    Error message text is converted to upper case. An error message might be returned in this area for return codes 20 or 24. A message set in this area for any other return code is ignored.

• Word 9

  Is set to zero.

• Word 10

  If you have a full security exit, this word is set to zero.

  If you have a partial security exit this word is set to zero if the user ID is not defined on the UAMS data set. Otherwise word 10 points to a list of full words, ended by a full word of X'FFFFFFFF'. Each address in the list points to a single structured field representing one attribute of the user ID to be verified. This list therefore provides the exit with access to the entire current definition of this user ID.

Return Codes from Logon Verification Call

The exit must return a completion code in Register 15 on return. Completion codes are supported as described below.

The return codes listed below are for subfunction codes 0 and 4. They are the only codes that are accepted in response to a Logon Verification call. Any other return code is rejected and set to 24.

• 0

  Indicates that the password is valid. Logon is successful.

• 4

  Indicates that the password is valid but expired. This is not a new user ID. The user is prompted to change the password before logon is successful.

• 8

  Indicates that the password is valid but this is a new user ID. The user is prompted to change the password before logon is successful.

• 16

  Indicates that the password is wrong.

• 20

  Indicates that the password is correct but logon is rejected. The exit might return an explanatory message in the error message area addressed by word 8 of the parameter list.

• 24

  Indicates that the request failed or function is not supported by the exit. The exit might return an explanatory message in the error message area addressed by word 8 of the parameter list.

The return codes listed below are for subfunction code 8. They are the only codes that are accepted in response to an APPC link establishment Logon Verification call. Any other return code is rejected and set to 24.

• 0

  Indicates that link activation is successful. The session key is addressed by word 6 of the parameter list.

• 4

  Indicates that link activation is successful. No session key is available.

• 8

  N/A

• 16

  Indicates that link activation is unsuccessful.

• 20

  N/A

• 24

  Indicates that the function is not supported. The link establishment is to continue without a session key.

Notes:

• When a Logon Verification Call to the exit is made by a &SECCALL CHECK statement or by NMPC link activation, no user correlator information can be provided. Word 4 of the parameter list is set to zero.
• The Logon Verification Call return codes do not strictly correlate with the &SECCALL CHECK return code values. For an explanation of &SECCALL CHECK return codes, see the Network Control Language Reference.
• If the Logon Verification call is made by the LOCK facility, the call is being made on behalf of a logged-on user. Consequently, the parameter list provides the address of the appropriate user session correlator.

The Logon Verification Call is primarily a means of querying the validity of a password, and the exit can be written to provide only this function. The option of supporting return code 20 is provided to complement support of return code 24 from the Logon Request Call, which allows the exit to refuse a logon request for reasons other than password error.