Reference Guide › User Exit Reference › Implementing User Exits

Implementing User Exits

All CA VM:Director user exits, except the NEWUSER user exit, must be modified at your site by an Assembler or REXX programmer. Prototype files, as listed in the table above, are available to make these modifications easier. Your programmers can customize these prototype user exits to meet your site’s needs, and implement them using the steps below.

Note: CA VM:Director must receive control from a user exit with the environment in the same state it was when control went to the user exit. If you have a user exit directly manipulate interrupt tasks in either the PSW or control register zero, you must have it return control to CA VM:Director with the same tasks restored.

1. Modify the prototype user exit file. Each prototype user exit file contains comment records that explain how the user exit works and suggest ways to modify the user exit. CA VM:Director passes the standard CMS PLIST (parameter list) to REXX user exits and both the standard CMS PLIST and an extended PLIST to Assembler user exits.

   The standard CMS PLIST varies, depending on whether you are writing the user exit in Assembler, EXEC, or REXX.

   • With the standard CMS Assembler PLIST, the tokens begin with the name of the routine called. For CA VM:Director user exits, this is the name of the user exit, for example, ACCOUNT, NEWUSER, or SCRATCH.
   • If you are coding user exits in REXX or EXEC, the first argument is the actual value passed to the exit and not the name of the user exit. In most of the user exits, the first argument is the user ID that is attempting the action.

   If you are using IPv4 addresses, you may want to use the extended PLIST for the RULEUPDT and COMMAND user exits because CA VM:Director can pass these user exits 15‑byte IP addresses.

   The extended PLIST for exits called with password parameters are also required, if password phrase support is configured. These are: PASSWORD, PASSCHNG, CHKPASS, USERPASS, and TERMPASS exits.

2. If you have coded the user exit in REXX or EXEC2, change the filetype of the user exit to EXEC. If you have used Assembler, assemble the user exit to obtain the TEXT file.
3. Add a USEREXIT record to the PRODUCT CONFIG file for that user exit. For example, to use the NEWUSER user exit when the file name of your user exit is NEW2, enter this record:

   USEREXIT NEWUSER NEW2 EXEC
   

   Note: For more information about using the USEREXIT record, see USEREXIT Record.

4. The configuration file you loaded from the distribution tape contains a USEREXIT record for each prototype user exit, preceded by an asterisk. To activate these records, remove the asterisks.
5. Put the user exits on the CA VM:Director 191 minidisk after you have customized them. They will then be found by CA VM:Director initialization processing.