Updating dynamic exits

Use the SETPROG EXIT command to:
  • Add an exit routine to an exit
  • Replace an exit routine for an exit
  • Change the state of an exit routine
  • Delete an exit routine from an exit
  • Undefine an implicitly-defined exit
  • Change the attributes of an exit
You can use the SETPROG EXIT command to control exits that have been defined to the dynamic exits facility. Dynamic exits services are implemented by:
  • The EXIT statement of the PROGxx parmlib member. The EXIT statement of PROGxx allows an installation to add exit routines to an exit, delete an exit routine for an exit, change the state of an exit routine, change the attributes of an exit, and undefine an implicitly defined exit.

    The PROGxx EXIT statement interacts with the PROG=xx parameter of IEASYSxx and the SET PROG=xx command. At IPL, you can use PROG=xx to specify the particular PROGxx parmlib member the system is to use. During normal processing, you can use the SET PROG=xx command to set a current PROGxx parmlib member. See z/OS MVS Initialization and Tuning Reference for information about the PROGxx parmlib member.

  • The SETPROG EXIT command.
  • The CSVDYNEX macro. The CSVDYNEX macro can be used to define exits to the dynamic exits facility, control their use within a program, and associate one or more exit routines with those exits. It can also be used to associate exit routines with the existing SMF and allocation exits, which have been defined to the dynamic exits facility.

An installation can use any of these methods to control dynamic exits. An exit routine, for example, can be associated with an exit using the CSVDYNEX ADD request, the SETPROG EXIT,ADD operator command, or the EXIT statement of PROGxx.

The complete syntax for the SETPROG EXIT command is:
 
SETPROG EXIT,{ADD,EXITNAME=exitname,MODNAME=modname       }
                  [,STATE={ACTIVE|INACTIVE}]         
                     [,DSNAME=dsname]                      
                  [,JOBNAME={jobname|*}]                   
                     [,ABENDNUM=(n[,CONSEC])]              
                     [,FIRST|LAST]                         
                  [,PARAM=param]                           
                  Start of change[,DELETEFORCE={NO|YES}]End of change
                  Start of change[,SERVICEMASK=servicemask]End of change
  
             {ATTRIB,EXITNAME=exitname,KEEPRC=(compare,kk)}
  
             {DELETE,EXITNAME=exitname,MODNAME=modname    }
                  [,FORCE={YES|NO}]                  
  
             {MODIFY,EXITNAME=exitname,MODNAME=modname    }
                  [,STATE={ACTIVE|INACTIVE}]               
                     [,JOBNAME={jobname|*}]                
  
             {REPLACE,EXITNAME=exitname,MODNAME=modname,  }
                               [,STATE={ACTIVE|INACTIVE}]  
                                  [,DSNAME=dsname]         
                               Start of change[,SERVICEMASK=servicemask]End of change
  
             {UNDEFINE,EXITNAME=exitname                  }
   
Notes:
  1. This command requires a /* */ around comments. Refer to System command formats for further information.
  2. The EXITNAME parameter must be the first parameter following the ADD, ATTRIB, DELETE, MODIFY, REPLACE, or UNDEFINE keywords.
ADD
Adds an exit routine to an exit.
ATTRIB
Changes the attributes of an exit.
DELETE
Deletes an exit routine from an exit.
MODIFY
Changes the state of an exit routine.
REPLACE
Replaces an exit routine for an exit.
UNDEFINE
Undefines an implicitly-defined exit. An exit is implicitly defined when:
  • You add exit routines to an exit before the exit is defined
  • You set attributes using the ATTRIB parameter before defining the exit.
EXITNAME=exitname or EX=exitname or EN=exitname
The 1-16 character name of the exit.
MODNAME=modname or MOD=modname
The 1-8 character name of the exit routine. If DSNAME is not specified, the system tries to locate the exit routine using the LPA, the LNKLST concatenation, and the nucleus.
DSNAME=dsname or DSN=dsname
The 1-44 character data set name of a load library in which the named exit routine resides. The data set must be cataloged, but does not need to be APF-authorized.

If the data set has been migrated, processing of the SETPROG command is delayed until the data set has been retrieved.

JOBNAME={jobname|*}
The 1-8 character name of the job(s) for which this exit routine is to get control. If some other job calls the exit, this exit routine does not get control.

You can use the JOBNAME parameter to limit most exit routines to processing a particular job. However, you cannot use this parameter to restrict processing of the IEFUJV exit routine to a particular job.

To indicate more than one job name, use an asterisk as the last character. A matching jobname is one that matches all characters preceding the asterisk.

Specify JOBNAME=* to request that the system not check for the jobname. The default for the ADD parameter is *. The default for the MODIFY parameter is to leave the jobname unchanged.

Based on the characteristics of the particular exit, the JOBNAME parameter might not be effective if the exit is driven before the job name has been set in a batch initiator.

STATE
Indicates the state of the exit routine. ACTIVE indicates that the exit routine is to be given control when the exit is called. INACTIVE indicates that the exit routine is not to be given control when the exit is called.

Start of changeNote that the STATE parameter activates or deactivates the exit routine independently from other parameters, such as JOBNAME. For instance, STATE=INACTIVE,JOBNAME=jobname does not mean to make the exit routine inactive for jobname; it means to make the exit routine inactive, and it defines jobname as the job for which the exit routine is to get control (when the exit routine is active).End of change

The default for the ADD parameter is STATE=ACTIVE. The default for the MODIFY parameter is to leave the state unchanged.

PARAM=param
The 1 - 8 character parameter that is passed to the exit routine. If this parameter is less than 8 bytes, it is padded with blanks until it is 8 bytes. The first 4 bytes are passed to the exit routine in access register 0. The second 4 bytes are passed to the exit routine in access register 1. If you specify characters other than the following characters within the PARAM string you must enclose the parameter string within single quotes:
  • uppercase alphabetics A - Z
  • numerics 0 - 9
  • special characters @, $ , #
  • period, asterisk, question mark, underscore, hyphen
ABENDNUM=(n[,CONSEC])
Indicates when the system should stop giving control to the exit routine in case of abends. ABENDNUM=n indicates that the exit routine is not to be given control after the nth abend. ABENDNUM=n,CONSEC indicates that there must be n consecutive abends before the system stops giving control to the exit routine. CONSEC is not supported if this exit has FASTPATH processing in effect, and either a PSW key 8 to 15 or ANYKEY processing in effect.

The default is to use the ABENDNUM characteristics that were specified (or defaulted) when the exit was defined. The ABENDNUM value must not exceed 8 decimal digits.

FIRST
Specifies that the system is to call the exit routine before all other exit routines associated with this exit, unless another exit routine, added after it, also specifies FIRST.

If you specify neither the FIRST nor the LAST parameter, the system may call the exit routines associated with this exit in any order.

LAST
Specifies that the system is to call the exit routine after all other exit routines associated with this exit, unless other exit routines are added after it.

If you specify neither the FIRST nor the LAST parameter, the system may call the exit routines associated with this exit in any order.

FORCE={NO|YES}
Indicates that the system is to delete the exit routine. The exit routine will no longer be given control. Specify FORCE=YES for an exit with FASTPATH processing in effect, and either a PSW key 8 to 15 or ANYKEY processing in effect. Assuming the exit has FASTPATH processing in effect, and the PSW key is 8 to 15, or ANYKEY processing is in effect:
  • FORCE=NO, the default, changes the state of the exit routine to inactive. The system does not free the storage.
  • FORCE=YES frees the storage of the exit routine immediately. Use FORCE=YES only if you are sure that no exit is running that exit routine.

For exits that are non-FASTPATH or whose PSW key is 0 to 7, and are not ANYKEY, the system frees the storage when it determines that no other exits are using the exit routine.

KEEPRC=(compare,kk)
Specifies a comparison and a return code which, if true, cause the information produced by this exit routine to be returned to the exit caller. The valid choices for compare are EQ, NE, GT, LT, GE, and LE. For example, with KEEPRC=(NE,4), if the exit routine produces a return code of 8, the compare for not-equal with 4 is true, and KEEPRC processing causes the information produced by this exit routine to be returned to the exit caller.

The default is not to perform KEEPRC processing. Do not enter more than 8 decimal digits when specifying a value for kk.

If return codes from more than one exit routine match the conditions specified, the system returns information from the exit routine that finished first.

Start of changeDELETEFORCE={NO|YES}End of change
Start of changeSpecifies whether any deletion of the exit routine (by CSVDYNEX, SETPROG, or an EXIT DELETE statement in PROGxx) must specify FORCE=YES:
  • DELETEFORCE=NO, the default, specifies that exit routine deletion does not require FORCE=YES.
  • DELETEFORCE=YES specifies that exit routine deletion does require FORCE=YES. If the deletion request does not specify FORCE=YES, the request is rejected.

DELETEFORCE can be abbreviated as DELFORCE.

End of change
Start of changeSERVICEMASK=servicemaskEnd of change
Start of changeSpecifies a service mask for the exit routine that is used to determine whether the exit routine will be called for a given caller.
Specify servicemask as one of:
  • x1
  • (x1)
  • (x1,x2)

where each x1 and x2 is a one to eight digit hexadecimal number. x1 and x2 are padded on the left with zeros to a length of 8 and thus each identifies 4 bytes of the service mask. x1 represents bytes 0 to 3 of the mask, x2 represents bytes 4 to 7 of the mask (when no x2 is specified, those bytes are zeroes). For example, SERVICEMASK=(1,4003) will produce a mask of (hexadecimal) 0000000100004003.

The service mask is applied to the service ID of the exit caller. Only if the ANDed value of the service mask and the service ID is nonzero for a given call and a given exit routine will that exit routine be called.

SERVICEMASK can be abbreviated as SERVMASK

End of change

Example:

Associate exit routine MYMOD with the SMF exit known as SYS.IEFUJI, defined through the SYS statement in a SMFPRMxx parmlib member. The load module is in data set MY.DSN.
SETPROG EXIT,ADD,EXITNAME=SYS.IEFUJI,MODNAME=MYMOD,DSNAME=MY.DSN,
        STATE=ACTIVE