A group of exit points is sure to make the job of the savvy system administrator a lot easier. The group of exit points are all related to user profiles. One exit point, for instance, is defined so that a user exit program can be called whenever a new user profile is created. (See previous tips, "The registration facility helps you tailor your system -- Part I" and The registration facility helps you tailor your system -- Part II" for more information on exit points, exit programs, and the registration facility).
Four user profile-related exit points
There are four exit points related to user profiles:
- QIBM_QSY_CHG_PROFILE. Exit programs defined for this exit point are called when a user profile is changed.
- QIBM_QSY_CRT_PROFILE. Associated exit programs are called when a user profile is created.
- QIBM_QSY_DLT_PROFILE. Associated exit programs are called when a user profile is deleted. Exit programs can be assigned to be called either before the deletion takes place (this is also before any owned objects are deleted) or after the user profile has been deleted.
- QIBM_QSY_RST_PROFILE. Associated exit programs are called when a user profile is restored.
How to define exit programs for the exit points
Exit programs for all four of the above exit points should all have a single parameter at least 38 bytes long. The structure of this parameter is as follows:
- Exit point name (positions 1-20). A 20-character field that will contain the name of the exit point.
- Exit point format name (positions 21-28). An eight-character field that will contain the format name.
- User profile (positions 29-38). A 10-character field that will contain the name of the user profile being change, created, deleted or restored.
The change and create profile exit points are fairly straightforward; the exit programs are called when a profile is changed or created. They can do any processing desired, but they cannot stop the profile from being changed or created (e.g., there is no return value and escape messages sent to the caller are ignored). You can attach unlimited number of programs to these exit points.
The delete profile exit point differs because exit programs can be configured to be called either before or after the user profile is deleted (similar in concept to before and after delete-triggers). The delete profile exit point has two exit point format names associated with it: DLTP0100 and DLTP0200. If you want your exit program to be called after the user profile is deleted, attach the program to the DLTP0100 format. Exit programs attached to the DLTP0200 will be called before the user profile is deleted. You can attach unlimited number of programs to this exit point as well.
The restore user profile exit point operates similarly to the change and create profile exit points. The only exceptions are these:
- Exit programs defined for this exit point are not called when the entire system is being restored (because at the time user profiles are restored, some of the objects required to execute the exit programs will not have been restored yet).
- This exit point supports only 20 exit programs.
Sample code: How to use the user profile exit programs
If your shop is like most, when you add a new user to your system, your work seldom ends with creating a new user profile. There are usually several other things you must do manually to fully configure the new user, such as create other objects or add the user to the system directory for Client Access configuration.
The CRTPRFEP program shown below is an example of a program that can be used as an exit program for the QIBM_QSY_CRT_PROFILE exit point. (Remember, exit programs are just normal programs that are attached to exit points.)
/*----------------------------------------------------------------------+
| +
| PROGRAM: CRTPRFEP +
| +
| DESCRIPTION: EXIT PROGRAM FOR CREATE USER PROFILE. +
| +
| EXIT POINT: QIBM_QSY_CRT_PROFILE +
| +
----------------------------------------------------------------------*/
PGM PARM(&ENTRY_PARM)
DCL VAR(&ENTRY_PARM) TYPE(*CHAR) LEN(38)
DCL VAR(&EXIT_POINT) TYPE(*CHAR) LEN(20)
DCL VAR(&EP_FORMAT) TYPE(*CHAR) LEN(8)
DCL VAR(&USER_PRF) TYPE(*CHAR) LEN(10)
DCL VAR(&SYS_NAME) TYPE(*CHAR) LEN(8)
DCL VAR(&USRPRFTEXT) TYPE(*CHAR) LEN(50)
/* Extract fields from entry parameter structure. */
CHGVAR VAR(&EXIT_POINT) VALUE(%SST(&ENTRY_PARM 1 20))
CHGVAR VAR(&EP_FORMAT) VALUE(%SST(&ENTRY_PARM 21 8))
CHGVAR VAR(&USER_PRF) VALUE(%SST(&ENTRY_PARM 29 10))
/* Get the system name. */
RTVNETA SYSNAME(&SYS_NAME)
/* Get the user profile text. */
RTVUSRPRF USRPRF(&USER_PRF) TEXT(&USRPRFTEXT)
IF COND(&USRPRFTEXT = ' ') THEN(CHGVAR +
VAR(&USRPRFTEXT) VALUE(&USER_PRF))
/* Add user to the system directory. */
ADDDIRE USRID(%SST(&USER_PRF 1 8) &SYS_NAME) +
USRD(&USRPRFTEXT) USER(&USER_PRF) +
SYSNAME(*LCL)
/* Create work library for user. */
CRTLIB LIB(&USER_PRF) TEXT('Work library for user ' +
*CAT &USER_PRF)
/* Change the ownership of the user's library. */
CHGOBJOWN OBJ(&USER_PRF) OBJTYPE(*LIB) +
NEWOWN(&USER_PRF) CUROWNAUT(*SAME)
ENDPGM
When a new user profile is created -- after the actual user profile object has be created -- the system calls this program. The program adds the user to the system directory and creates a library for the user. If your normal procedure for setting up a user differs, simply add the code necessary to this program.
To attach this program to the QIBM_QSY_CRT_PROFILE exit point, execute the following command:
ADDEXITPGM EXITPNT(QIBM_QSY_CRT_PROFILE)
FORMAT(CRTP0100)
PGMNBR(*LOW)
PGM(UCG/CRTPRFEP)
Where to find more information about these exit points
For more information about the user profile exit points, see the System API Reference (SC41-3801, chapter "Security Exit Programs"). For soft copy and Information Center users, the System API Reference is broken into many separate books/links; these exit points are in the Security APIs category.
-----------------------------------
About the author: Ron Turull is editor of Inside Version 5. He has more than 20 years' experience programming for and managing AS/400-iSeries systems.
