Sign-on component’s subroutines

The sign-on component is entered as a single kernel-managed subroutine, DFHSNUS, which handles some function itself and also acts as a router to further kernel-managed subroutines. Table 99 summarizes the sign-on component’s subroutines. It shows the level-1 trace point IDs of the modules providing the functions for the subroutines, the functions provided by the subroutines, and whether or not the functions are available through the exit programming interface (XPI).

Table 99. Sign-on component’s subroutines
Subroutine Trace Function XPI
DFHSNAS
AP 2050
AP 2051
AP 2052
AP 2053
AP 2054
AP 2055
AP 2056
SIGNON_ATI_SESSION
SIGNOFF_ATI_SESSION
NO
NO
DFHSNPU
AP 2070
AP 2071
AP 2072
AP 2073
AP 2074
AP 2075
AP 2076
AP 2077
AP 2078
AP 2079
SIGNON_PRESET_USERID
SIGNOFF_PRESET_USERID
NO
NO
DFHSNSG
AP 20C0
AP 20C1
AP 20C2
AP 20C3
AP 20C4
AP 20C5
AP 20C6
SIGNOFF_SURROGATE
NO
DFHSNSU
AP 2060
AP 2061
AP 2062
AP 2063
AP 2064
AP 2065
AP 2066
AP 2067
AP 2068
AP 2069
AP 206A
AP 206B
AP 206C
AP 206D
SIGNON_SESSION_USERID
SIGNOFF_SESSION_USERID
NO
NO
DFHSNTU
AP 2080
AP 2081
AP 2082
AP 2083
AP 2084
AP 2085
AP 2086
AP 2087
AP 2088
AP 2089
AP 208A
AP 208B
AP 208C
AP 208D
AP 208E
AP 208F
AP 2090
AP 2091
AP 2092
AP 2093
AP 2094
AP 2095
AP 2096
AP 2097
SIGNON_TERMINAL_USER
SIGNOFF_TERMINAL_USER
NO
NO
DFHSNUS
AP 2040
AP 2041
AP 2042
AP 2043
AP 2044
AP 2045
AP 2046
AP 2047
AP 2048
AP 2049
SIGNON_ATTACH_HEADER
SIGNOFF_ATTACH_HEADER
NO
NO

DFHSNAS subroutine, SIGNON_ATI_SESSION function

The SIGNON_ATI_SESSION function of the DFHSNAS subroutine signs on the appropriate userid to a session when that session is being used by a trigger transaction specified in a DCT with DESTFAC=SYSTEM.

Input parameters

SESSION_TCTTE_PTR
is the address of the TCTTE for the session to be signed on.

Output parameters

RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
UNEXPECTED_REASON
CORRUPT_USER_TOKEN
USER_DOMAIN_FAILURE
USER_TOKEN_MISMATCH
EXCEPTION
INVALID_TERMINAL_TYPE
TERMINAL_ALREADY_SIGNED_ON
SURROGATE_TERMINAL
SECURITY_INACTIVE
INVALID
INVALID_FORMAT
INVALID_FUNCTION

DFHSNAS subroutine, SIGNOFF_ATI_SESSION function

The SIGNOFF_ATI_SESSION function of the DFHSNAS subroutine is used to reverse the effect of a SIGNON_ATI_SESSION.

Input parameters

SESSION_TCTTE_PTR
is the address of the session TCTTE to be signed off.

Output parameters

RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
CORRUPT_USER_TOKEN
USER_DOMAIN_FAILURE
INVALID_USER_TOKEN
EXCEPTION
INVALID_TERMINAL_TYPE
TERMINAL_NOT_SIGNED_ON
SURROGATE_TERMINAL
SECURITY_INACTIVE
INVALID
INVALID_FORMAT
INVALID_FUNCTION

DFHSNPU subroutine, SIGNON_PRESET_USERID function

The SIGNON_PRESET_USERID function of the DFHSNPU subroutine is used to sign on the userid specified in a terminal definition when that terminal is installed.

Input parameters

USERID
is the userid to be assigned to the terminal.
USERID_LENGTH
is the length of the userid.
TCTTE_PTR
is the address of the TCTTE for the terminal to be given preset security.
[NATLANG_SUFFIX]
is an optional one-character national language code to be assigned to the terminal, which will override any national language associated with the userid.
[MESSAGE]
is an optional parameter that specifies whether a message is to be issued when the sign on completes successfully. It can have either of these values:
YES|NO

Output parameters

[SAF_RESPONSE]
is the optional 32-bit SAF response code to the call.
[SAF_REASON]
is the optional 32-bit SAF reason returned with SAF_RESPONSE.
[ESM_RESPONSE]
is the optional 32-bit ESM response code to the call.
[ESM_REASON]
is the optional 32-bit ESM reason returned with ESM_RESPONSE.
RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION_UNKNOWN
CORRUPT_USER_TOKEN
MESSAGE_DOMAIN_FAILURE
USER_DOMAIN_FAILURE
GETMAIN_FAILED
EXCEPTION
INVALID_USERID
INVALID_NATIONAL_LANGUAGE
TERMINAL_ALREADY_SIGNED_ON
UNKNOWN_ESM_RESPONSE
SECURITY_INACTIVE
ESM_INACTIVE
TERMINAL_NOTAUTH
APPLICATION_NOTAUTH
USERID_REVOKED
TERMINAL_NOT_PRESET
GROUP_ACCESS_REVOKED
UNAVAILABLE_NATLANG
SECLABEL_CHECK_FAILED
ESM_TRANQUIL
INVALID
INVALID_FORMAT
INVALID_FUNCTION

DFHSNPU subroutine, SIGNOFF_PRESET_USERID function

The SIGNOFF_PRESET_USERID function of the DFHSNPU subroutine is used to sign off a preallocated userid from a terminal before it is deleted.

Input parameters

TCTTE_PTR
is the address of the TCTTE for the terminal from which preset security is to be removed.
[MESSAGE]
is an optional parameter that specifies whether a message is to be issued when the sign off completes successfully. It can have either of these values:
YES|NO

Output parameters

[SAF_RESPONSE]
is the optional 32-bit SAF response code to the call.
[SAF_REASON]
is the optional 32-bit SAF reason returned with SAF_RESPONSE.
[ESM_RESPONSE]
is the optional 32-bit ESM response code to the call.
[ESM_REASON]
is the optional 32-bit ESM reason returned with ESM_RESPONSE.
RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
CORRUPT_USER_TOKEN
FREEMAIN_FAILED
EXCEPTION
TERMINAL_NOT_SIGNED_ON
TERMINAL_NOT_PRESET
SECURITY_INACTIVE
ESM_INACTIVE
ESM_TRANQUIL
UNKNOWN_ESM_RESPONSE
INVALID
INVALID_FORMAT
INVALID_FUNCTION

DFHSNSG subroutine, SIGNOFF_SURROGATE function

The SIGNOFF_SURROGATE function of the DFHSNSG subroutine is used to sign off a userid from a surrogate terminal that is about to be deleted by the remote terminal builder. (The equivalent sign-on routine is always performed as an inline function, so no SIGNON call to DFHSNSG is ever traced.)

Input parameters

TCTTE_PTR
is the address of the TCTTE for the surrogate terminal being signed off.
SESSION_TCTTE_PTR
is the address of the TCTTE for the associated relay session.

Output parameters

RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED

DFHSNSU subroutine, SIGNON_SESSION_USERID function

The SIGNON_SESSION_USERID function of the DFHSNSU subroutine is used to sign on the USERID (from the SESSIONS definition) or the SECURITYNAME (from the CONNECTION definition) for IRC, LU6.1, and LU6.2 sessions.

Input parameters

[USERID]
is the userid to be signed on.
[USERID_LENGTH]
is the length of the userid to be signed on.
SESSION_TCTTE_PTR
is the address of the TCTTE for the session being signed on.

Output parameters

RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
USER_TOKEN_MISMATCH
MESSAGE_DOMAIN_FAILURE
SURROGATE_TERMINAL
USER_DOMAIN_FAILURE
XS_DOMAIN_FAILURE
EXCEPTION
INVALID_USERID
INVALID_TERMINAL_TYPE
TERMINAL_ALREADY_SIGNED_ON
UNKNOWN_ESM_RESPONSE
SECURITY_INACTIVE
ESM_INACTIVE
APPLICATION_NOTAUTH
USERID_REVOKED
GROUP_ACCESS_REVOKED
SECLABEL_CHECK_FAILED
ESM_TRANQUIL
INVALID
INVALID_FORMAT
INVALID_FUNCTION

DFHSNSU subroutine, SIGNOFF_SESSION_USERID function

The SIGNOFF_SESSION_USERID function of the DFHSNSU subroutine is used to reverse the effect of the SIGNON_SESSION_USERID function.

Input parameters

None

Output parameters

[SAF_RESPONSE]
is the optional 32-bit SAF response code to the call.
[SAF_REASON]
is the optional 32-bit SAF reason returned with SAF_RESPONSE.
[ESM_RESPONSE]
is the optional 32-bit ESM response code to the call.
[ESM_REASON]
is the optional 32-bit ESM reason returned with ESM_RESPONSE.
RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
TERMINAL_NOT_SIGNED_ON
CORRUPT_USER_TOKEN
INVALID_TERMINAL_TYPE
SURROGATE_TERMINAL
SECOND_DELETE_FAILED
MESSAGE_DOMAIN_FAILURE
USER_DOMAIN_FAILURE
EXCEPTION
SECURITY_INACTIVE
ESM_INACTIVE
ESM_TRANQUIL
UNKNOWN_ESM_RESPONSE
INVALID
INVALID_FORMAT
INVALID_FUNCTION

DFHSNTU subroutine, SIGNON_TERMINAL_USER function

The SIGNON_TERMINAL_USER function of the DFHSNTU subroutine is used to implement the EXEC CICS® SIGNON command and signs on a specific user at the principal facility terminal.

Input parameters

USERID
is the userid being signed on to the principal facility terminal.
USERID_LENGTH
is the length of the userid.
[PASSWORD]
is the optional password associated with the userid. The external security manager determines whether the password is required or not.
[PASSWORD_LENGTH]
is the length of the password.
[NEW_PASSWORD]
is the optional new password that is to replace the existing password
[NEW_PASSWORD_LENGTH]
is the length of the new password.
[OIDCARD]
is the text obtained from an operator identification card. The external security manager determines whether operator identification card data, or a password, or both, or neither, are required.
[GROUPID]
is the optional group name to be associated with the userid for this sign on.
[GROUPID_LENGTH]
is the length of the group name.
[NATIONAL_LANGUAGE]
is the optional three-letter national language code to be associated with the terminal for the duration of this sign on. The code should be one of those specified in Table 120.
[SCOPE_CHECK]
is an optional parameter that specifies whether this sign on is to be subject to the constraints imposed by the SNSCOPE system initialization parameter. It can have either of these values:
YES|NO

Output parameters

[SAF_RESPONSE]
is the optional 32-bit SAF response code to the call.
[SAF_REASON]
is the optional 32-bit SAF reason returned with SAF_RESPONSE.
[ESM_RESPONSE]
is the optional 32-bit ESM response code to the call.
[ESM_REASON]
is the optional 32-bit ESM reason returned with ESM_RESPONSE.
RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
ADD_USER_FAILURE
GETMAIN_FAILED
EXCEPTION_UNKNOWN
INQUIRE_DEFAULT_ERROR
MESSAGE_DOMAIN_FAILURE
USER_DOMAIN_FAILURE
XMIQ_FAILURE
CORRUPT_USER_TOKEN
SNXR_FAILURE
SUSX_FAILURE
EXCEPTION
INVALID_USERID
INVALID_PASSWORD
INVALID_NEW_PASSWORD
INVALID_OIDCARD
INVALID_GROUPID
USERID_NOT_IN_GROUP
INVALID_TERMINAL_TYPE
INVALID_NATIONAL_LANGUAGE
UNAVAILABLE_NATLANG
TERMINAL_ALREADY_SIGNED_ON
USERID_ALREADY_SIGNED_ON
SURROGATE_TERMINAL
PRESET_SECURITY_TERMINAL
NO_TERMINAL_WITH_TASK
USERID_REQUIRED
PASSWORD_REQUIRED
NEW_PASSWORD_REQUIRED
OIDCARD_REQUIRED
UNKNOWN_ESM_RESPONSE
SECURITY_INACTIVE
ESM_INACTIVE
TERMINAL_NOTAUTH
APPLICATION_NOTAUTH
USERID_REVOKED
GROUP_ACCESS_REVOKED
SECLABEL_CHECK_FAILED
ESM_TRANQUIL
INVALID
INVALID_FORMAT
INVALID_FUNCTION

DFHSNTU subroutine, SIGNOFF_TERMINAL_USER function

The SIGNOFF_TERMINAL_USER function of the DFHSNTU subroutine is used to implement the EXEC CICS SIGNOFF command and reverses the effect of a SIGNON_TERMINAL_USER function. It effectively associates the terminal with the default userid specified in the DFLTUSER system initialization parameter.

Input parameters

[TCTTE_PTR]
is the optional TCTTE address of a terminal that is to be signed off.

Output parameters

[SAF_RESPONSE]
is the optional 32-bit SAF response code to the call.
[SAF_REASON]
is the optional 32-bit SAF reason returned with SAF_RESPONSE.
[ESM_RESPONSE]
is the optional 32-bit ESM response code to the call.
[ESM_REASON]
is the optional 32-bit ESM reason returned with ESM_RESPONSE.
RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
FREEMAIN_FAILED
LOOP
XMIQ_FAILURE
ADD_TXN_USER_ERROR
INVALID_USER_TOKEN
EXCEPTION
INVALID_TERMINAL_TYPE
TERMINAL_NOT_SIGNED_ON
PRESET_SECURITY_TERMINAL
SURROGATE_TERMINAL
NO_TERMINAL_WITH_TASK
SECURITY_INACTIVE
ESM_INACTIVE
ESM_TRANQUIL
UNKNOWN_ESM_RESPONSE
INVALID
INVALID_FORMAT
INVALID_FUNCTION

DFHSNUS subroutine, SIGNON_ATTACH_HEADER function

The SIGNON_ATTACH_HEADER function of the DFHSNUS subroutine causes a sign on for the userid received in an LU6.2 function management header type 5, also known as an attach header or an FMH5.

Input parameters

TCTTE_PTR
is the address of the TCTTE for which the FMH5 sign on is being performed.
[USERID]
is the userid obtained from the FMH5, if any.
[USERID_LENGTH]
is the length of the userid
[PASSWORD]
is the password obtained fron the FMH5, if any.
[PASSWORD_LENGTH]
is the length of the password.
[GROUPID]
is the group name obtained from the profile name in the FMH5, if any.
[GROUPID_LENGTH]
is the length of the group name.
[ENTRY_PORT_NAME]
is the optional name of the entry port (terminal) at which the userid was signed on in the terminal-owning region.
[ENTRY_PORT_TYPE]
is the optional terminal type associated with the port of entry. It can have either of these values:
TERMINAL|CONSOLE
[APPLID]
is the optional applid at which the userid was signed on in the terminal-owning region.
ATTACHSEC_TYPE
specifies whether the ATTACHSEC associated with the connection is LOCAL or not. It can have either of these values:
LOCAL|NON_LOCAL
ALREADY_VERIFIED
specifies whether the already-verified indicator (AV) is present in the FMH5. It can have either of these values:
YES|NO
PERSISTENT_SIGNON
specifies whether the persistent-sign on indicator (PV2) is present in the FMH5. It can have either of these values:
YES|NO
PERSISTENT_VERIFY
specifies whether the persistent-verification indicator (PV1) is present in the FMH5. It can have either of these values:
YES|NO

Output parameters

[SAF_RESPONSE]
is the optional 32-bit SAF response code to the call.
[SAF_REASON]
is the optional 32-bit SAF reason returned with SAF_RESPONSE.
[ESM_RESPONSE]
is the optional 32-bit ESM response code to the call.
[ESM_REASON]
is the optional 32-bit ESM reason returned with ESM_RESPONSE.
RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
USER_DOMAIN_FAILURE
MESSAGE_DOMAIN_FAILURE
CORRUPT_USER_TOKEN
ZCUT_FAILURE
EXCEPTION
TERMINAL_ALREADY_SIGNED_ON
INVALID_USERID
INVALID_PASSWORD
INVALID_GROUPID
USERID_NOT_IN_GROUP
PRESET_SECURITY_TERMINAL
USERID_REQUIRED
PROTOCOL_VIOLATION
PASSWORD_REQUIRED
UNKNOWN_ESM_RESPONSE
SECURITY_INACTIVE
ESM_INACTIVE
TERMINAL_NOTAUTH
LUIT_ENTRY_NOT_FOUND
APPLICATION_NOTAUTH
USERID_REVOKED
GROUP_ACCESS_REVOKED
SECLABEL_CHECK_FAILED
SIGNON_SURROGATE_ERROR
ESM_TRANQUIL
INVALID
INVALID_FORMAT
INVALID_FUNCTION

DFHSNUS subroutine, SIGNOFF_ATTACH_HEADER function

The SIGNOFF_ATTACH_HEADER function of the DFHSNUS subroutine is used to reverse the effect of a SIGNON_ATTACH_HEADER function when the transaction initiated by the FMH5 attach header terminates.

Input parameters

TCTTE_PTR
is the address of the TCTTE for which the FMH5 sign off is being performed.

Output parameters

[SAF_RESPONSE]
is the optional 32-bit SAF response code to the call.
[SAF_REASON]
is the optional 32-bit SAF reason returned with SAF_RESPONSE.
[ESM_RESPONSE]
is the optional 32-bit ESM response code to the call.
[ESM_REASON]
is the optional 32-bit ESM reason returned with ESM_RESPONSE.
RESPONSE
is the subroutine’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
ZCUT_FAILURE
CORRUPT_USER_TOKEN
EXCEPTION
INVALID_TERMINAL_TYPE
PRESET_SECURITY_TERMINAL
SURROGATE_TERMINAL
SECURITY_INACTIVE
ESM_INACTIVE
ESM_TRANQUIL
UNKNOWN_ESM_RESPONSE
INVALID
INVALID_FORMAT
INVALID_FUNCTION
[[ Contents Previous Page | Next Page Index ]]