Function Code, Parameters, and Return Codes

Setting Up User Exits › Signon and Signoff Exit › Function Code, Parameters, and Return Codes

Function Code, Parameters, and Return Codes

The following table lists functions, parameters, return codes, and comments for the signon and signoff exit. The code for each function is shown in parenthesis to the right of the name of the function.

Function Codes	Parameters	Return Codes	Comments
CA TPX startup (0) Builds user data areas required for subsequent exit requests.	N/A	0 Always	This is a general purpose first call exit to permit the user to initialize the security environment. This exit is called from the initialization processes and will be called again if TPXONOFF abnormally terminates as a part of the TPXONOFF re-initialization process (the shutdown exit point is not called in this situation).
Signon data (4) Inspects and modifies input signon.	See the Parameter List.	0 Always	Alter Generic to real name or national character changes. The addresses of parameters 2 and 3 are unpredictable. The SMRTUADS field addresses the first UINDEX entry. UIDXNEXT can be used to chain through the in-storage user entries.
Pre-security (8) Selects the security system.	See the Parameter List.	0 Continue with signon. 4 Reject the signon with the message supplied. 16 Switch to the system named by the affinity parameter.	The UINDEX block that describes this user can be altered either to inhibit the call to the security package or to select a different package than the one coded in the profile or the system options table (SMRT). UIDXSCTY contains either zero (0) to indicate no security, or the value specified in the user's definition. You can assign one of the following values to this byte to select a different security mechanism: X'80' CA TPX X'40' RACF X'20' CA ACF2 X'10' User (Code 12) X'08' CA Top Secret X'04' VM Security X'02' SAF (RACF Security Access Facility if implemented) X'01' Not applicable Equates for these values can be found in the SMRT macro expansion as SEC$TPX, SEC$RACF, and so on. You can also use this call to cause an Affinity switch to another system before the authentication process is started.
Security (12) This is an alternative security authentication routine.	See the Parameter List.	0 User ID and Password or password phrase have been accepted. 4 Reject logon with a message to the user. 8 Prompt the user to enter a new password or password phrase. 12 Continue with signon and send the message when signon is complete.	You can use this call to provide your own security algorithm. This call is made if the value of the Security system field in the system options table is USER and no override was found in the user's UINDEX record. The call will also be made if the UINDEX record indicates that a value of USER was set by the pre-security exit or was specified in the Security system field in User Maintenance.
Post-security Determines what action to take if the security mechanism rejects the signon request.	See the Parameter List.	0 Continue with the rejection signaled by the security package or by the function. 4 Continue with the rejection, but display your own message. 8 Ignore the rejection and permit normal signon to continue. 12 Ignore the rejection and permit normal signon to continue and send message when signon is complete. 16 Switch to the system named by the affinity parameter	This call is made only if the security mechanism has not authorized the user to use this product and has not reprompted the user. You can take further action to decide whether or not the user is allowed to continue. The return codes are arranged in an order that ensures that omitting this exit and substituting a dummy exit with all the return codes set to zero will not affect the normal operation of the security mechanism. If you use this exit to cause an Affinity switch to another system, make sure that an invalid user ID does not cause a loop, being rejected and switched repeatedly.
Get Profile (20) Requests a model profile.	See the Parameter List.	0 Use the profile name currently in the standard parameter list to build a profile for the user. 4 Reject the signon with the message supplied. 8 Use the default dynamic user profile in the systems options table. 12 The exit has issued ADDPROF statements to build the user, or user-level or profile-level profile selection is being used, as shown in the sample exit TPXUSNSF. 16 Switch to the system named in the affinity parameter.	This call is made if a user entry has been dynamically built. A UINDEX entry is built for all users that are not known to this product if the Dynamic Users Allowed field in the system options table is set to Y. On exit, if return code 0, 8, or 12 is used, the specified profile must already be defined in profile maintenance. This exit could determine that a switch to another system will take place and avoid unnecessarily building a profile for a dynamically added user.
Alter Profile (24) Updates the user profile.	See the Parameter List.	0 Continue to switch systems if either the parameter list or UINDEX implies switching. 4 Inhibit any implied switching. 8 Continue with signon and send the message when signon is complete. 12 Reject the signon with the supplied message.	This function is always called and allows you to further tailor a user's profile. UIDXPTR points to the chain of the user's application entries. You can use UENTNEXT to chain through to the next entry. When the call is completed, any implied switch to another CA TPX will take place unless inhibited by a suitable return code. The supplied parameter list will be inspected before the UIDXOWN field to determine the name of the destination system.
Affinity Failure (28) Recovers from the situation in which the target system is not accepting logons at the time of the switch.	See the Parameter List.	0 Continue as if no switch was requested. 4 Reject the signon with the message supplied. 12 Continue as if no switch was requested but issue a message when signon is complete. 16 Attempt to switch again using the value in the parameter list. If parameter list value is blank, use the value in UINDEX. 20 Go back to just after pre-security point and issue the security system call.	This call is made if a switch request is rejected because the destination CA TPX or Access is unavailable or not accepting logons. You can use this call to determine what action is to be taken. If continue is requested, the signon process will continue as if the switch request was never made. The processing logic of subsequent exits can cause this exit to be called more than once. The continue request will only apply to the switch attempt that failed. Any subsequent calls must take the appropriate action.
Signoff (32) Processes signoff requests.	+0 Address of the user ID. +4 Address of the UINDEX record.	0 Always	This exit point can be used to clean up any user indicators previously set in the signon entry points. Any ENQs issued can be dequeued. All UINDEX and UENTRY control blocks will be deleted unless either the Keep ACB or the Propagate ACB field in user maintenance is set to Y. The control blocks are deleted after the user's last active session has been terminated. If the user signs off and then signs on again before the sessions have been terminated, the control blocks will not be deleted.
Shutdown (36) Closes down the security facility.	N/A	0 Always	Any files opened by the security facility can be closed prior to termination. This exit is called in all normal and most abnormal termination situations. The exit cannot be called when the software is not notified of a failure such as CP failure or abends. The exit will not be called if the security subtask ONOFF abnormally terminates.
Signon complete (40) Indicates that signon processing has been completed.	+0 Address of the user ID +4 Address of the Password or password phrase +8 Address of the new password or password phrase +12 Address of the UINDEX record	0 Always	This exit can be used to generate commands internally to be issued to CA TPX through the $COMMAND macro.
Terminal Lock (44) Allows you to change the lockword to be something other than the user's password.	+0 Address of the user ID +4 Address of the Password	0 Lockword not changed 4 Lockword changed
Terminal Unlock (48) Allows you to determine how CA TPX reacts when the user attempts to unlock a locked terminal.	+0 Address of the user ID +4 Address of the Password +8 Address of the Password entered by the user	0 No change 4 User exceeded password retries, issue /F 8 User exceeded password retries, issue /K 12 User exceeded password retries, issue /F and inactivate sessions 16 User exceeded password retries, issue /K and inactivate sessions

Function Codes

Parameters

Return Codes

Comments

CA TPX startup (0)

Builds user data areas required for subsequent exit requests.

N/A

0 Always

This is a general purpose first call exit to permit the user to initialize the security environment. This exit is called from the initialization processes and will be called again if TPXONOFF abnormally terminates as a part of the TPXONOFF re-initialization process (the shutdown exit point is not called in this situation).

Signon data (4)

Inspects and modifies input signon.

See the Parameter List.

0 Always

Alter Generic to real name or national character changes. The addresses of parameters 2 and 3 are unpredictable. The SMRTUADS field addresses the first UINDEX entry. UIDXNEXT can be used to chain through the in-storage user entries.

Pre-security (8)

Selects the security system.

See the Parameter List.

0 Continue with signon.

4 Reject the signon with the message supplied.

16 Switch to the system named by the affinity parameter.

The UINDEX block that describes this user can be altered either to inhibit the call to the security package or to select a different package than the one coded in the profile or the system options table (SMRT). UIDXSCTY contains either zero (0) to indicate no security, or the value specified in the user's definition. You can assign one of the following values to this byte to select a different security mechanism:

X'80' CA TPX
X'40' RACF
X'20' CA ACF2
X'10' User (Code 12)
X'08' CA Top Secret
X'04' VM Security
X'02' SAF (RACF Security Access Facility if implemented)
X'01' Not applicable

Equates for these values can be found in the SMRT macro expansion as SEC$TPX, SEC$RACF, and so on.

You can also use this call to cause an Affinity switch to another system before the authentication process is started.

Security (12)

This is an alternative security authentication routine.

See the Parameter List.

0 User ID and Password or password phrase have been accepted.

4 Reject logon with a message to the user.

8 Prompt the user to enter a new password or password phrase.

12 Continue with signon and send the message when signon is complete.

You can use this call to provide your own security algorithm. This call is made if the value of the Security system field in the system options table is USER and no override was found in the user's UINDEX record. The call will also be made if the UINDEX record indicates that a value of USER was set by the pre-security exit or was specified in the Security system field in User Maintenance.

Post-security

Determines what action to take if the security mechanism rejects the signon request.

See the Parameter List.

0 Continue with the rejection signaled by the security package or by the function.

4 Continue with the rejection, but display your own message.

8 Ignore the rejection and permit normal signon to continue.

12 Ignore the rejection and permit normal signon to continue and send message when signon is complete.

16 Switch to the system named by the affinity parameter

This call is made only if the security mechanism has not authorized the user to use this product and has not reprompted the user. You can take further action to decide whether or not the user is allowed to continue.

The return codes are arranged in an order that ensures that omitting this exit and substituting a dummy exit with all the return codes set to zero will not affect the normal operation of the security mechanism.

If you use this exit to cause an Affinity switch to another system, make sure that an invalid user ID does not cause a loop, being rejected and switched repeatedly.

Get Profile (20)

Requests a model profile.

See the Parameter List.

0 Use the profile name currently in the standard parameter list to build a profile for the user.

4 Reject the signon with the message supplied.

8 Use the default dynamic user profile in the systems options table.
12 The exit has issued ADDPROF statements to build the user, or user-level or profile-level profile selection is being used, as shown in the sample exit TPXUSNSF.

16 Switch to the system named in the affinity parameter.

This call is made if a user entry has been dynamically built. A UINDEX entry is built for all users that are not known to this product if the Dynamic Users Allowed field in the system options table is set to Y. On exit, if return code 0, 8, or 12 is used, the specified profile must already be defined in profile maintenance. This exit could determine that a switch to another system will take place and avoid unnecessarily building a profile for a dynamically added user.

Alter Profile (24)

Updates the user profile.

See the Parameter List.

0 Continue to switch systems if either the parameter list or UINDEX implies switching.

4 Inhibit any implied switching.

8 Continue with signon and send the message when signon is complete.

12 Reject the signon with the supplied message.

This function is always called and allows you to further tailor a user's profile. UIDXPTR points to the chain of the user's application entries. You can use UENTNEXT to chain through to the next entry. When the call is completed, any implied switch to another CA TPX will take place unless inhibited by a suitable return code. The supplied parameter list will be inspected before the UIDXOWN field to determine the name of the destination system.

Affinity Failure (28)

Recovers from the situation in which the target system is not accepting logons at the time of the switch.

See the Parameter List.

0 Continue as if no switch was requested.

4 Reject the signon with the message supplied.

12 Continue as if no switch was requested but issue a message when signon is complete.

16 Attempt to switch again using the value in the parameter list. If parameter list value is blank, use the value in UINDEX.

20 Go back to just after pre-security point and issue the security system call.

This call is made if a switch request is rejected because the destination CA TPX or Access is unavailable or not accepting logons. You can use this call to determine what action is to be taken. If continue is requested, the signon process will continue as if the switch request was never made.

The processing logic of subsequent exits can cause this exit to be called more than once. The continue request will only apply to the switch attempt that failed. Any subsequent calls must take the appropriate action.

Signoff (32)

Processes signoff requests.

+0 Address of the user ID.

+4 Address of the UINDEX record.

0 Always

This exit point can be used to clean up any user indicators previously set in the signon entry points. Any ENQs issued can be dequeued. All UINDEX and UENTRY control blocks will be deleted unless either the Keep ACB or the Propagate ACB field in user maintenance is set to Y. The control blocks are deleted after the user's last active session has been terminated. If the user signs off and then signs on again before the sessions have been terminated, the control blocks will not be deleted.

Shutdown (36)

Closes down the security facility.

N/A

0 Always

Any files opened by the security facility can be closed prior to termination. This exit is called in all normal and most abnormal termination situations. The exit cannot be called when the software is not notified of a failure such as CP failure or abends. The exit will not be called if the security subtask ONOFF abnormally terminates.

Signon complete (40)

Indicates that signon processing has been completed.

+0 Address of the user ID

+4 Address of the Password or password phrase

+8 Address of the new password or password phrase

+12 Address of the UINDEX record

0 Always

This exit can be used to generate commands internally to be issued to CA TPX through the $COMMAND macro.

Terminal Lock (44)

Allows you to change the lockword to be something other than the user's password.

+0 Address of the user ID

+4 Address of the Password

0 Lockword not changed

4 Lockword changed

Terminal Unlock (48)

Allows you to determine how CA TPX reacts when the user attempts to unlock a locked terminal.

+0 Address of the user ID

+4 Address of the Password

+8 Address of the Password entered by the user

0 No change

4 User exceeded password retries, issue /F

8 User exceeded password retries, issue /K

12 User exceeded password retries, issue /F and inactivate sessions

16 User exceeded password retries, issue /K and inactivate sessions