Replace an exit routine for an exit

Replacing an exit routine for an exit means removing the association of an active exit routine and replacing it with a newer version while making sure that either the old or new version, but not both, gets control when the exit is called.

On the CSVDYNEX REPLACE request, you:

Name the exit that the exit routine is to be associated with (EXITNAME parameter)
Identify where to find the exit routine (MODNAME, DSNAME, and MODADDR parameters)
Request that the system send a message to the operator if the system encounters certain error conditions when processing the exit routine (MESSAGE parameter)

The CSVDYNEX DELETE request deletes an exit routine that was added to an exit by the CSVDYNEX REPLACE request.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	One of the following: Supervisor state PSW key 0-7 PKM allowing key 0-7 APF-authorized SAF UPDATE authority to FACILITY class entity CSVDYNEX.exitname.modname.
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks to be held.
Control parameters:	Control parameters and the area that contains the data set name (specified on DSNAME) must be in the primary address space or, for AR-mode callers, must be in an address space or data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).

Programming requirements

Include the CSVEXRET mapping macro to define symbolic names and values for return and reason codes returned by CSVDYNEX. See z/OS MVS Data Areas in the z/OS Internet library for more information.

Restrictions

The caller must not have functional recovery routines (FRRs) established.

Input register information

See Input register information for CSVDYNEX for input register information for the CSVDYNEX REPLACE request.

Output register information

See Output register information for CSVDYNEX for output register information for the CSVDYNEX REPLACE request.

Syntax

The standard form of the REPLACE request on the CSVDYNEX macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␣	One or more blanks must precede CSVDYNEX.

CSVDYNEX

␣	One or more blanks must follow CSVDYNEX.

REQUEST=REPLACE

,EXITNAME=`exitname`	`exitname`: RS-type address or register (2) - (12).

,MODNAME=`modname`	`modname`: RS-type address or register (2) - (12).

,MESSAGE=NO	Default: MESSAGE=NO
,MESSAGE=ERROR
,MESSAGE=FOUNDBUTERROR

,DSNAME=`dsname`	`dsname`: RS-type address or register (2) - (12).
,MODADDR=`modaddr`	`modaddr`: RS-type address or register (2) - (12).

,STATE=UNCHANGED
,STATE=ACTIVE
,STATE=INACTIVE

,SERVICEMASK=`servicemask`	`servicemask`: RS-type address or address in register (2)-(12)
,SERVICEMASK=ALL_SERVICES	Default: SERVICEMASK=ALL_SERVICES

,RETCODE=`retcode`	`retcode`: RS-type address or register (2) - (12).

,RSNCODE=`rsncode`	`rsncode`: RS-type address or register (2) - (12).

,MF=S

Parameters

The parameters are explained as follows:

REQUEST=REPLACE

Replaces an exit routine for an exit.

The following attributes of the added exit routine are maintained:

the state (active or inactive)
the jobname or STOKEN
the ADDABENDNUM characteristic
the ABENDCONSEC characteristic

The exit routine gets control in the same sequence of exit routines that the replaced routine did.

,EXITNAME=exitname

Specifies a 16-byte field (or a register containing the address of a 16-byte field) containing the 16-character name of an exit that has been defined to the dynamic exits facility.

If the name has fewer than 16 characters, you must left-justify the name and pad the field with blanks.

,MODNAME=modname

Specifies an 8-byte field (or a register containing the address of an 8-byte field) containing the name of an exit routine to be replaced for the exit.

The first character must not be X'00' or blank.

If you specify MODADDR, modname is the name of the exit routine.

If you do not specify MODADDR, modname designates a load module or alias. The entry point of the load module or alias is the starting address of the exit routine.

If the name has fewer than 8 characters, you must left-justify the name and pad the field with blanks.

,MESSAGE=NO

,MESSAGE=ERROR

,MESSAGE=FOUNDBUTERROR

Specifies whether the system is to send message CSV431I to the operator if the system encounters certain errors when processing the exit routine.

MESSAGE=NO, the default, requests that the system send the return and reason codes only.
MESSAGE=ERROR requests that the system send message CSV431I if any of the following situations are encountered:
- The exit requires reentrancy; the exit routine is not reentrant.
- The exit requires AMODE=31, but the exit routine is AMODE=24; or the exit requires AMODE=24, but the exit routine is AMODE=31.
- The exit allows only one exit routine; one routine is already associated with this exit.
- The exit routine could not be located.
- A CSVDYNEX REPLACE request specified that the exit routine must be loaded from a particular data set, but that data set is not APF-authorized, and the caller is in problem state, with PSW key 8-15, and is not APF-authorized.
MESSAGE=FOUNDBUTERROR requests that the system send message CSV431I if it encounters any of the circumstances covered by MESSAGE=ERROR, except the following circumstance:
- The exit routine could not be located.

,DSNAME=dsname

,MODADDR=modaddr

Tells the system how to find the exit routine to be added.

If neither DSNAME nor MODADDR are specified, the system attempts to find the module using LPA, the LNKLST concatenation, and the nucleus.

DSNAME specifies a field (or a register containing the address of a field) containing the 44-character name of a data set or library from which the module is to be obtained. The following actions must be performed when specifying DSNAME:

Allocate the data set as a PDS or a PDSE.
If the 44-character name has fewer than 44 characters, you must left-justify the name and pad it with blanks.
Do not specify the data set name beginning with a blank or X'00'. The system responds as if you have specified no data set.
If the caller is in problem state with PSW key 8 to 15, and is not APF-authorized, the data set must be APF-authorized.
The data set must be cataloged.

Note:

Specify DSNAME only if dynamic allocations are enabled within the caller's primary address space.
If the data set has been migrated, your program waits for the system to retrieve it.

MODADDR specifies a fullword (or a register containing the address of a fullword) that contains the address of the exit routine to be added.

If the exit routine is to get control in 31-bit mode, bit 0 must be on. If the exit routine is to get control in 24-bit mode, bit 0 must be off.

The system assumes that the designated exit routine is reentrant.

MODADDR cannot be used if the caller is in problem state with PSW key 8 to 15 and is not APF-authorized.

If you specify MODADDR, ensure that the subpool and the key where the exit routine is stored are appropriate for the address spaces and keys in which the exit routine can get control. For example, if you specify STOKEN, the exit routine can be stored in the private area of the address space designated by STOKEN. If you do not specify STOKEN, and the exit routine can be called from other address spaces, ensure that the exit routine is stored in the common area.

If the storage is fetch-protected, the storage key must not conflict with the PSW key on entry to the exit routine. To prevent modification by unauthorized users, the storage for exit routines that get control in system key must not be PSW key 8-15.

,STATE=UNCHANGED

,STATE=ACTIVE

,STATE=INACTIVE

Specifies that you want the state of the exit routine to be unchanged or that you want to change the state to active or inactive.

An active exit routine is associated with an exit and is called when the exit is called.

An inactive exit routine is associated with an exit, but is not called when the exit is called.

,SERVICEMASK=servicemask

,SERVICEMASK=ALL_SERVICES

An optional input parameter containing the mask for this exit routine, to be 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. The default is ALL_SERVICES.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,RETCODE=retcode

Specifies a fullword (or a register) where the system is to store the CSVDYNEX return code. The return code is also in GPR 15.

,RSNCODE=rsncode

Specifies a fullword (or a register) where the system is to store the CSVDYNEX reason code. The reason code is also in GPR 0.

,MF=S

Specifies the standard form of the CSVDYNEX macro.

ABEND codes

None.

Return and reason codes

See Return and reason codes for the return and reason codes for the CSVDYNEX REPLACE request.

Example

None.