Skip to main content

Installation Exits

Installation exit points allow sites using Mainframe Connector to introduce alternate and/or additional processes into specific functions within Mainframe Connector operation. Seven exit points are currently provided with Mainframe Connector . They are:

  • PSNCUX01 - is invoked from the Mainframe Connector password reset module and is used primarily to indicate what should happen with a userid’s REVOKE/CANCEL/SUSPEND status when the corresponding password value is reset. See Exit PSNCUX01 specifics.

  • PSNCUX02 - is invoked from the Mainframe Connector userid list module and is used primarily to filter the userid list returned to the Bravura Security Fabric server. See Exit PSNCUX02 specifics.

  • PSNCUX03 - is invoked from the Mainframe Connector userid enable module and is used primarily to indicate whether or not a userid should be enabled (resumed) as requested by the Bravura Security Fabric server. See Exit PSNCUX03 specifics.

  • PSNCUX04 - is invoked from the Mainframe Connector password phrase reset module and is used primarily to indicate what should happen with a userid’s REVOKE/CANCEL/SUSPEND status when the corresponding password phrase value is reset. See Exit PSNCUX04 specifics.

  • ISNCUX01 - is invoked from the Mainframe Connector userid create module after a new userid has been successfully created. It allows for site specific operations related to the creation of a new userid. See Exit ISNCUX01 specifics.

  • ISNCUX02 - is invoked from the Mainframe Connector userid delete module after an existing userid has been successfully deleted. It allows for site specific operations related to the deletion of an existing userid. See Exit ISNCUX02 specifics.

  • ISNCUX03 - is invoked from the Mainframe Connector group user add/delete module after the specified userid has been successfully added to or deleted from the target group. It allows for site specific operations related to successfully adding/deleting a userid to/from a group. See Exit ISNCUX03 specifics.

  • ISNCUX04 - is invoked from the Mainframe Connector userid attribute update module after the standard security product attributes have been processed. The exit allows for site specific attribute processing. See Exit ISNCUX04 specifics.

Mainframe Connector provides default exits in all cases. The default exit processing is discussed in the exit specific sections.

Influencing REVOKE/CANCEL/SUSPEND Status and Rejecting Inbound Password Resets - Exit PSNCUX01

The password for a userid can be transparently reset without changing the current active status of the userid. By default, Mainframe Connector ships installation exit PSNCUX01 that leaves the current REVOKE/CANCEL/SUSPEND status of a userid unchanged.

If this default action is not appropriate, the site can provide a customized PSNCUX01 exit. PSNCUX01 is invoked twice for incoming transparent synchronization requests. The pre call occurs just prior to the password reset function in Mainframe Connector . The post call occurs following the password reset function invocation.

PSNCUX01 can also be used to reject an incoming password reset or resetexpire request. This can be useful for sites that want to be able to use their z/OS system as the final arbiter of a proposed new password value.

A sample PSNCUX01 exit is provided in member UX01SAMP of the Mainframe Connector installation library.

Following are the characteristics of the PSNCUX01 user exit:

  • Its name must be PSNCUX01 and it must reside in either the STEPLIB used for the Mainframe Connector started task or the system linklist

  • It should run AMODE(31) RMODE(24)

  • The exit is entered problem state key 8 and should return in this same state otherwise results are unpredictable

  • The exit must be reentrant

  • On entry to the exit, R1 points to the following parameter list:

    UX01STAT DS    XL1    EXIT INVOCATION STATE (PRE OR POST) 
 UX01PRE  EQU   X'80'  PRE INVOCATION 
 UX01POST EQU   X'40'  POST INVOCATION 
 UX01RSRV DS    XL3    RESERVED 
 UX01RSRC DS    F      RESET RETURN CODE (USED FOR POST CALL) 
 UX01UID  DS    CL8    USERID FOR WHICH PASSWORD IS BEING RESET 
 UX01USER DS    F      A WORD FOR THE USER 
 UX01NPWD DS    CL8    REQUESTED NEW PASSWORD VALUE 
 UX01MSGB DS    F      ADDRESS OF 128-BYTE RETURN MESSAGE BUFFER THAT 
 *                     CAN BE USED TO APPEND TO THE DEFAULT MESSAGE 
 *                     THAT IS RETURNED TO THE PWD MANAGER SERVER WHEN 
 *                     A M/F CONNECTOR RESET EVENT IS REJECTED BY 
 *                     THE M/F CONNECTOR PSNCUX01 EXIT.  THE FORMAT OF 
 *                     THIS MESSAGE AREA IS AS FOLLOWS: 
 *                     +0 - TWO BYTE LENGTH OF MESSAGE BEING 
 *                          RETURNED (MAX OF 126) 
 *                     +2 - 126-BYTE MESSAGE BUFFER

    Member PUX01PRM in the INSTLIB dataset contains the DSECT mapping macro for the above parameter list.

  • for the pre exit call, R15 on return contains a return code that will be interpreted as follows:

     R15=0    the current REVOKE/CANCEL/SUSPEND status for 
          the userid will not be changed but the 
          password will be reset to the new value. 
 R15=4    the current REVOKE/CANCEL/SUSPEND status for 
          the userid will be reset and the password 
          will be reset to the new value. 
 R15=8    the reset or resetexpire request should be 
          terminated.  The password value will not be 
          reset to the requested new value.

  • for the post exit call, UX01RSRC contains a return code value from the password revoke/reset request. If UX01RSRC=0 , the requested password reset and revoke update have been successful. Any other value in UX01RSRC indicates that the requested operation did not complete successfully.

  • UX01USER is a word of storage that can be used by the exit routine to maintain state information across the pre and post exit call.

  • UX01NPWD is the requested new password value for the reset or resetexpire request.

TopSecret ASUSPEND

If Mainframe Connector will be running in a TopSecret environment and you do not want a password reset event to reset the ASUSPEND attribute, see TopSecret and REMOVE ASUSPEND to alter this default function.

ACF2 CANCEL

If Mainframe Connector will be running in an ACF2 environment and you do not want a password reset event to reset the CANCEL flag, see ACF2 and Removing the CANCEL Flag to alter this default function.

Influencing Userids returned to Userlist processing - Exit PSNCUX02

One of the inbound requests supported by Mainframe Connector is a request from a Bravura Security Fabric server to provide a list of userids and corresponding user names as defined in the z/OS security product database. By default, Mainframe Connector ships installation exit PSNCUX02 that will return all userids defined in the security product database.

If this default action is not appropriate, the site can provide a customized PSNCUX02 exit. A return code of 4 from PSNCUX02 indicates that the current userid should not be returned to the Bravura Security Fabric server for the current user list request. Optionally, the userid can be modified by the exit to indicate the ’next’ userid that should be returned by the user list function.

A sample PSNCUX02 exit is provided in member UX02SAMP of the Mainframe Connector installation library.

Following are the characteristics of the PSNCUX02 user exit:

  • Its name must be PSNCUX02 and it must reside in either the STEPLIB used for the Mainframe Connector started task or the system linklist

  • It should run AMODE(31) RMODE(24)

  • The exit is entered problem state key 8 and should return in this same state otherwise results are unpredictable

  • The exit must be reentrant

  • On entry to the exit, R1 points to the following parameter list:

     UX02UID  DS    F    ADDR OF THE USERID FLD (8 BYTES) 
 UX02UNAM DS    F    ADDR OF THE USER NAME FLD (20 BYTES)

    Member PUX02PRM in the INSTLIB dataset contains the DSECT mapping macro for the above parameter list.

  • On return, R15 should contain one of the following return codes

     R15=0    the current userid and user name should be returned 

          to the Password Manager server for this user list request. 
 R15=4    the current userid should be bypassed.  PSNCUX02 
          may have provided an alternative 'next' userid in 
          the area pointed to by UX02UID.

Influencing RESUME Requests - Exit PSNCUX03

A Bravura Security Fabric server can request Mainframe Connector to resume/enable a userid. By default, Mainframe Connector ships installation exit PSNCUX03 that will permit the resume/enable operation to continue as requested.

If this default action is not appropriate, the site can provide a customized PSNCUX03 exit. A return code of 4 from PSNCUX03 indicates that the specified userid should not be resumed/enabled and that its current system access status should remain unchanged.

A sample PSNCUX03 exit is provided in member UX03SAMP of the Mainframe Connector installation library.

Following are the characteristics of the PSNCUX03 user exit:

  • Its name must be PSNCUX03 and it must reside in either the STEPLIB used for the Mainframe Connector started task or the system linklist

  • It should run AMODE(31) RMODE(24)

  • The exit is entered problem state key 8 and should return in this same state otherwise results are unpredictable

  • The exit must be reentrant

  • On entry to the exit, R1 points to the following parameter list:

    UX03UID  DS    CL8       USERID FOR ENABLE/RESUME REQUEST 
UX03MSGB DS    F         ADDRESS OF 128-BYTE RETURN MESSAGE BUFFER THAT 
*                        CAN BE USED TO APPEND TO THE DEFAULT MESSAGE 
*                        THAT IS RETURNED TO THE PWD (OR ID) MANAGER 
*                        SERVER WHEN AN ENABLE/RESUME EVENT IS REJECTED 
*                        BY THE M/F CONNECTOR PSNCUX03 EXIT.  THE 
*                        FORMAT OF THIS MESSAGE AREA IS AS FOLLOWS: 
*                        +0 - TWO BYTE LENGTH OF MESSAGE BEING 
*                             RETURNED (MAX OF 126) 
*                        +2 - 126-BYTE MESSAGE BUFFER

    Member PUX03PRM in the INSTLIB dataset contains the DSECT mapping macro for the above parameter list.

  • on return, R15 should contain one of the following return codes

     R15=0    the specified userid should be resumed/enabled by the 
          Mainframe Connector resume module. 
 R15=4    the system access status for the specified userid 
          should remain unchanged.

Influencing REVOKE/CANCEL/SUSPEND Status and Rejecting Inbound Password Phrase Resets - Exit PSNCUX04

The password phrase for a userid can be reset without changing the current active status of the userid. By default, Mainframe Connector ships installation exit PSNCUX04 that leaves the current REVOKE/CANCEL/SUSPEND status of a userid unchanged.

If this default action is not appropriate, the site can provide a customized PSNCUX04 exit. PSNCUX04 is invoked twice for incoming transparent synchronization requests. The pre call occurs just prior to the password phrase reset function in Mainframe Connector . The post call occurs following the password phrase reset function invocation.

PSNCUX04 can also be used to reject an incoming password phrase reset or resetexpire request. This can be useful for sites that want to be able to use their z/OS system as the final arbiter of a proposed new password phrase value.

A sample PSNCUX04 exit is provided in member UX04SAMP of the Mainframe Connector installation library.

Following are the characteristics of the PSNCUX04 user exit:

  • Its name must be PSNCUX04 and it must reside in either the STEPLIB used for the Mainframe Connector started task or the system linklist

  • It should run AMODE(31) RMODE(24)

  • The exit is entered problem state key 8 and should return in this same state otherwise results are unpredictable

  • The exit must be reentrant

  • On entry to the exit, R1 points to the following parameter list:

     UX04STAT DS    XL1    EXIT INVOCATION STATE (PRE OR POST) 
 UX04PRE  EQU   X'80'  PRE INVOCATION 
 UX04POST EQU   X'40'  POST INVOCATION 
 UX04RSRV DS    XL3    RESERVED 
 UX04RSRC DS    F      RESET RETURN CODE (USED FOR POST CALL) 
 UX04UID  DS    CL8    USERID FOR WHICH PWD PHRASE IS BEING RESET 
 UX04USER DS    F      A WORD FOR THE USER 
 UX04NPHR DS    CL100  REQUESTED NEW PASSWORD PHRASE VALUE 
 UX04MSGB DS    F      ADDRESS OF 128-BYTE RETURN MESSAGE BUFFER THAT 
 *                     CAN BE USED TO APPEND TO THE DEFAULT MESSAGE 
 *                     THAT IS RETURNED TO THE PWD MANAGER SERVER WHEN 
 *                     A M/F CONNECTOR RESET EVENT IS REJECTED BY 
 *                     THE M/F CONNECTOR PSNCUX04 EXIT.  THE FORMAT OF 
 *                     THIS MESSAGE AREA IS AS FOLLOWS: 
 *                     +0 - TWO BYTE LENGTH OF MESSAGE BEING 
 *                          RETURNED (MAX OF 126) 
 *                     +2 - 126-BYTE MESSAGE BUFFER

    Member PUX04PRM in the INSTLIB dataset contains the DSECT mapping macro for the above parameter list.

  • For the pre exit call, R15 on return contains a return code that will be interpreted as follows:

     R15=0    the current REVOKE/CANCEL/SUSPEND status for 
          the userid will not be changed but the 
          password phrase will be reset to the new value. 
 R15=4    the current REVOKE/CANCEL/SUSPEND status for 
          the userid will be reset and the password phrase 
          will be reset to the new value. 
 R15=8    the reset or resetexpire request should be 
          terminated.  The password phrase value will not be 
          reset to the requested new value.

  • For the post exit call, UX04RSRC contains a return code value from the password phrase revoke/reset request. If UX04RSRC=0 , the requested password phrase reset and revoke update have been successful. Any other value in UX04RSRC indicates that the requested operation did not complete successfully.

  • UX04USER is a word of storage that can be used by the exit routine to maintain state information across the pre and post exit call.

  • UX04NPHR is the requested new password phrase value for the reset or resetexpire request.

TopSecret ASUSPEND

If Mainframe Connector will be running in a TopSecret environment and you do not want a password phrase reset event to reset the ASUSPEND attribute, see TopSecret and REMOVE ASUSPEND to alter this default function.

ACF2 CANCEL

If Mainframe Connector will be running in an ACF2 environment and you do not want a password phrase reset event to reset the CANCEL flag, see ACF2 and Removing the CANCEL Flag to alter this default function.

Userid Create Installation Exit - Exit ISNCUX01

An Bravura Identity server can request Mainframe Connector create a new userid. By default, Mainframe Connector ships installation exit ISNCUX01 that performs no additional processing with respect to a userid create operation.

If this default function is insufficient, the site can provide a customized ISNCUX01 exit. This exit can be used to provide any additional operations that a site may require that extend beyond the specific creation of the userid. An example of this might be the creation of a master catalog userid alias.

A sample ISNCUX01 exit is provided in member UX1ISAMP of the Mainframe Connector installation library.

Following are the characteristics of the ISNCUX01 user exit:

  • Its name must be ISNCUX01 and it must reside in either the STEPLIB used for the Mainframe Connector started task or the system linklist

  • It should run AMODE(31) RMODE(24)

  • The exit is entered problem state key 8 and should return in this same state otherwise results are unpredictable

  • The exit must be reentrant

  • On entry to the exit, R1 points to the following parameter list:

     UX1IREQ  DS    CL8       SPECIFIES OPERATION TYPE 'CREATE' 
 UX1IUID  DS    CL8       USERID THAT HAS BEEN CREATED 
 UX1IMDL  DS    CL8       USERID USED AS MODEL USERID 
 UX1IUNM  DS    CL20      USER NAME OF CREATE USERID 
 UX1UAVA  DS    F         ADDRESS OF ATTRIBUTE VECTOR 
 UX1UAVC  DS    F         ADDRESS OF ATTRIBUTE VECTOR COUNT ADDRESS

    Member PUX1IPRM in the INSTLIB dataset contains the DSECT mapping macro for the above parameter list.

  • A return code value in R15 is not currently examined on return to the userid create module

Userid Delete Installation Exit - Exit ISNCUX02

An Bravura Identity server can request Mainframe Connector delete an existing userid. By default, Mainframe Connector ships installation exit ISNCUX02 that performs no additional processing with respect to a userid delete operation.

If this default function is insufficient, the site can provide a customized ISNCUX02 exit. This exit can be used to provide any additional operations that a site may require that extend beyond the specific deletion of the userid. An example of this might be to delete the master catalog userid alias.

Specific to sites using Mainframe Connector in a RACF environment, an option to automatically execute suggested cleanup commands such as PERMIT, DELETE, RALTER, and RDELETE upon return from ISNCUX02 is provided. The suggested commands are passed in buffers which may be examined, and for which automatic command execution may be requested via return codes and bit flag settings. This has no impact or effect on Mainframe Connector operation in ACF2 or TopSecret environments.

A sample ISNCUX02 exit is provided in member UX2ISAMP of the Mainframe Connector installation library.

Following are the characteristics of the ISNCUX02 user exit:

  • Its name must be ISNCUX02 and it must reside in either the STEPLIB used for the Mainframe Connector started task or the system linklist

  • It should run AMODE(31) RMODE(24)

  • The exit is entered problem state key 8 and should return in this same state otherwise results are unpredictable

  • The exit must be reentrant

  • On entry to the exit, R1 points to the following parameter list:

     UX2IREQ  DS    CL8   SPECIFIES OPERATION TYPE 'DELETE' 
 UX2IUID  DS    CL8   USERID THAT HAS BEEN DELETED 
 UX2IFCBA DS    A     FIRST CMD BUFF ADDR OR 0 IF NO CMD BUFFS PRESENT

    Member PUX2IPRM in the INSTLIB dataset contains the DSECT mapping macro for the above parameter list. Member PUX2ICMB in the INSTLIB dataset contains the DSECT mapping macro for the command buffer contents.

  • the following R15 return codes have the associated meaning upon exit from ISNCUX02

    • 0: Do not automatically execute any commands.

    • 4: Automatically execute only those commands for which the UX2ICA bit flag has been set in the command buffer.

    • 8: Automatically execute all commands. All UX2ICA bit flags are ignored and need not be set.

Group User Add/Delete Installation Exit - Exit ISNCUX03

An Bravura Identity server can request Mainframe Connector add or delete a userid from a RACF or TopSecret group. By default, Mainframe Connector ships installation exit ISNCUX03 that performs no additional processing when a userid is added to or deleted from a RACF or TopSecret group.

If this default function is insufficient, the site can provide a customized ISNCUX03 exit. This exit can be used to provide any additional operations that a site may require that extend beyond the group user add or group user delete operation.

A sample ISNCUX03 exit is provided in member UX3ISAMP of the Mainframe Connector installation library.

Following are the characteristics of the ISNCUX03 user exit:

  • Its name must be ISNCUX03 and it must reside in either the STEPLIB used for the Mainframe Connector started task or the system linklist

  • It should run AMODE(31) RMODE(24)

  • The exit is entered problem state key 8 and should return in this same state otherwise results are unpredictable

  • The exit must be reentrant

  • On entry to the exit, R1 points to the following parameter list:

     UX3IREQ  DS    CL8       REQUEST TYPE (EITHER 'ADD' OR 'DEL') 
 UX3IUID  DS    CL8       USERID BEING ADDED OR DELETED 
 UX3IGRP  DS    CL8       GROUP FOR USERID ADD OR DELETE

    Member PUX3IPRM in the INSTLIB dataset contains the DSECT mapping macro for the above parameter list.

  • A return code value in R15 is not currently examined on return to the userid group add/delete module

Userid Attribute Update Exit - Exit ISNCUX04

An Bravura Identity server can request Mainframe Connector make updates to userid attributes. By default, Mainframe Connector ships installation exit ISNCUX04 that performs no additional processing when a userid’s attributes are updated.

If this default function is insufficient, the site can provide a customized ISNCUX04 exit. This exit can be used to provide any additional operations that a site may require beyond the standard attribute updates.

A sample ISNCUX04 exit is provided in member UX4ISAMP of the Mainframe Connector installation library.

Following are the characteristics of the ISNCUX04 user exit:

  • Its name must be ISNCUX04 and it must reside in either the STEPLIB used for the Mainframe Connector started task or the system linklist

  • It should run AMODE(31) RMODE(24)

  • The exit is entered problem state key 8 and should return in this same state otherwise results are unpredictable

  • The exit must be reentrant

  • On entry to the exit, R1 points to the following parameter list:

     UX4UID   DS    CL8       USERID 
 UX4UAVA  DS    F         USER ATTR VECTOR ADDR 
 UX4UAVC  DS    F         USER ATTR VECTOR COUNT ADDR

    Member PUX4IPRM in the INSTLIB dataset contains the DSECT mapping macro for the above parameter list.

  • A return code value in R15 is not currently examined on return to the userid attribute update module

In this section: