MVS Commands Installation Exit

The MVS commands installation exit allows you to modify command processing in a system or sysplex. Use one or more MVS commands exit routines to modify command text or modify the MCS authority of consoles that issue commands (for example, to allow a console to issue a command for which it is not authorized).

You can use MVS commands installation exit routines to:

Change the text of commands
In a sysplex, change the destination of commands by routing them to a different system for execution
Modify a console's MCS authority for a particular command. That is, you can use the exit to:
- Allow the command from a console that normally would not have the MCS authority to issue the command
- Reject the command from a console that normally would have the MCS authority to issue the command
Execute commands
Suppress commands

Installing the Exit Routine

You can insert MVS commands exit routines into the control program by:

Linkediting the routines into an APF-authorized library as part of the LNKLST concatenation. Use 31-bit addresses in the routines and assemble them with AMODE 31. RMODE ANY is recommended.
Specifying the name of each exit routine on the USEREXIT parameter of the .CMD statement of the required MPFLSTxx member of SYS1.PARMLIB. If you specify more than one exit routine, the routines are called in the order in which they are specified on the .CMD statement. The name of each exit routine can be from 1 to 8 alphanumeric characters.
Activating the MPFLSTxx member with SET MPF=xx

For more information on how to specify MVS commands exit routines in the MPFLSTxx member of SYS1.PARMLIB, see z/OS MVS Initialization and Tuning Reference.

Replacing an MVS Commands Exit Routine Without a ReIPL: There may be times when you need to replace a commands exit routine, either because you want to add functions to the routine or because the routine abended when it was processing a particular command.

If you want to replace a commands exit routine with a fresh copy, you must do the following:

Linkedit the new copy of the routine into SYS1.LINKLIB
Refresh LLA with the MODIFY LLA,REFRESH command
Reactivate the exit routine using the SET MPF=xx command

Deactivating a Command Exit: There are times when you might want to deactivate a command exit routine, perhaps because its function is not required at particular times or because you want to modify the routine. You can deactivate a command exit routine in one of two ways:

Specify, on the .CMD statement of the required MPFLSTxx member, the name of a command exit that does not exist in SYS1.LINKLIB, such as 'USEREXIT(NONE)'. Enter the SET MPF=xx command to refresh the MPFLSTxx member.
This action effectively deactivates any command exits that were enabled during the prior MPFLSTxx activation. The system issues an informational message that can be ignored in this case.
Enter the SET MPF=NO command to disable all active MPFLSTxx members. Remove the exit name from the .CMD statement of the appropriate MPFLSTxx member and enter the SET MPF=xx command to resume MPF processing.
Attention: Entering the SET MPF=NO command deactivates all installation-specified MPF options. IBM®-supplied defaults are used until the installation reactivates its MPFLSTxx members.

Exit Routine Environment

MVS commands exit routines receive control in the following environment:

Enabled for interrupts.
In supervisor state with PSW key 0.
In primary ASC mode.
With no locks held; they must return control with no locks held.
In AMODE 31. RMODE ANY is recommended.
In the address space of the routine that issued the command.

Exit Recovery: The MVS commands exit routines must provide their own level of recovery because, with one exception, the system does not continue to pass control to an exit routine after it abnormally terminates. The exception is when the exit routine is to be deleted and the installation has provided a clean-up routine that will get control for termination calls. When the system calls the exits for deletion, a commands exit routine can invoke the clean-up routine to release any work areas the exits may have created.

See Installing the Exit Routine for information on how to reactivate the exit routine if it abnormally terminates.

See Communication Between the Exits for more information on exit routine work areas and clean-up routines.

Exit Routine Processing

The MVS commands exit routines get control whenever a command is issued. Command processing invokes the exit prior to issuing the subsystem interface (SSI) call for command processing.

The MVS commands exit routine parameter list (the CMDX) contains a command buffer (CMDXCLIB). The buffer contains the command text, and the length of the command text, to be processed as it was entered on the console. The exit must place the modified command text and its new length back into this buffer before it returns control to the calling module. The modified command text can be up to 126 bytes long.

Operator commands may contain the following characters:

A to Z
0 to 9
' # $ & ( ) * + , - . / ¢ < | ! ; ¬ % _ > ? : @ " =

The system translates characters that are not valid into null characters (X'00').

If you are modifying the MCS authority of the console for this command in the exit routine, you must place the modified command authority into the CMDXAUTH field in the CMDX. Also you must set the appropriate authority change bits in the CMDXAFLA field in the CMDX.

The CMDX is mapped by the IEZVX101 macro (data area CMDX). See z/OS® MVS Data Areas in the z/OS Internet library for a description of the IEZVX101 mapping.

Changing Command Text with Exit Routines: If a command installation exit changes the text of a command, the system does the following:

Logs the new text of the command (the result of the change by the exit routine)
Issues message IEE295I to display both the original text and the new text.

If the command installation exit specified system symbols in the new command text, the system does not substitute text for those system symbols. The system symbols appear in the new command text in their original format.

To add or change a system symbol in command text and have it processed, the exit can create a copy of the new system symbol text, and then call the ASASYMBM service explicitly to substitute text for the system symbol.

For more information about ASASYMBM, see z/OS MVS Programming: Assembler Services Reference ABE-HSP.

See the topic on sharing system commands in z/OS MVS System Commands for more information about using system symbols in commands.

Considerations for System Symbols: When a command contains system symbols, MVS provides the command text to command installation exits after it substitutes text for the system symbols. For example, if the following command is entered to display a console group on system SYS1:

DISPLAY CNGRP,G=(CN1GRP&SYSCLONE.)

The command installation exit receives the following text (assuming that the default for &SYSCLONE., the last two characters of the system name, is taken):

DISPLAY CNGRP,G=(CN1GRPS1)

If a command installation exit requires the original command text (the one that existed before symbolic substitution), the exit can do the following:

Access the CMDXSYMS field in the CMDX to validate that the command was changed by symbolic substitution
If the command was changed by symbolic substitution, access the CMDXOLIP field in the CMDX to obtain the address of structure CMDXOLIB, which contains the original command text (before symbolic substitution occurred).

For a description of the IEZVX101 mapping macro, which maps the CMDX, see z/OS MVS Data Areas in the z/OS Internet library.

MVS Commands Exit Routines in a Sysplex Environment: In a sysplex, a command can be routed from one system to another. If a .CMD statement specifies MVS commands exit routines in an active MPFLSTxx member for a system, the exit routines on that system are invoked. (For a description of the .CMD statement, see z/OS MVS Initialization and Tuning Reference.) Which system executes command exit routines depends on the following:

If the ROUTE command is used, the MVS commands exit routines, if specified, are invoked on both the system that issued the ROUTE command and the system that received the routed command. However, the exit routines on the target system do not see 'ROUTE'.
If a command is issued with an L= parameter, and the console addressed is on a different system, only the command exit routines on the system that issued the command are invoked. The exit routines on the system in which the console specified by L= is attached, are not invoked.
If the MCS command prefix facility (CPF) is used to route a prefix command from one system to another system, only the command exit routines on the receiving system are invoked.
If commands are directed to a specific system (via the CMDSYS option specified in the CONSOLxx member of SYS1.PARMLIB), only the command exit routines on the receiving system are invoked.

Programming Considerations

When you code an MVS commands exit routine, observe the following conventions:

The MVS commands exit routines get control before the subsystem interface (SSI) passes control to subsystems enabled for function code 10 (command processing SSI call). For information on SSI function code 10, see z/OS MVS Using the Subsystem Interface.
If you specify REMOVE=YES on the CPF macro, the system removes the command's prefix before invoking the MVS commands exit routines. If STRIP is specified for the prefix, the prefix will be stripped before the exit gets control.
The MVS commands exit routines must be reentrant and serially reusable. Do not use macros with expansions that store information into an inline parameter list.
Do not code an exit routine that receives control for a command that the routine issues; this causes an endless loop. The exit routine must be coded so that when it receives control for that command, it does not issue the command again.
If you specify command text, or a text length value, that exceeds the maximum length allowed for that type of command, the system truncates the command.
The LOGON command has been architected so that all keywords and keyword values appear in the same position when the LOGON command is issued. There are two formats of the command depending on if password phrases are permitted or not.
A discriminator is provided so you can determine which format is being used. All LOGON commands are issued as if they were issued from a typical console that is 80 columns wide. For the architected LOGON mapping, which is mapped by CNZMYLGN, see z/OS MVS Data Areas in the z/OS Internet library.
When the discriminator value (CNZLGNOPNDPTYPE) is '40'x, use (CNZ_LGNOPNDPW) to map LOGON information when password phrases are not enabled.
When the discriminator value (CNZLGNOPNDPTYPE) is 'FF'x, use (CNZ_LGNOPNDPP) to map LOGON information when password phrases are enabled.

Note: The system does not substitute text for system symbols specified in the LOGON command.

Communication Between the Exits

Common Data Area: The MVS commands exits receive from the system the address of a 12-byte common data area in the exit routine parameter list. The common data area allows the exit routines to:

Share data (in common work areas) across invocations.
Supply the address of an installation-supplied routine that will clean up the common work areas when the exit routines are deleted. Deleted exit routines occur when:
- MPF terminates (via a SET MPF=NO command) or
- MPF is refreshed with a new MPFLSTxx that contains a new .CMD userexit name. MPF is then refreshed with that member using the SET MPF=xx command.

Sharing data: To enable your MVS commands exit routines to share data across invocations, code one of the exit routines to:

Create work areas in the extended common storage area (ECSA) by issuing a GETMAIN or STORAGE macro.
Place the addresses of the work areas in the second and third words of the common data area.

Whenever they are invoked, the MVS commands exit routines can access the common data area to obtain the addresses of the work areas. If the data required by the exits is 8 bytes or less, you can place the data itself within the second and third words of the common data area instead of creating work areas.

Supplying the address of a clean-up routine: You can also use the common data area to hold the address of an installation-supplied clean-up routine that will get control when the exits are to be deleted. The clean-up routine can perform any processing that is usually associated with exit routine work areas (such as releasing storage or clearing a control block). When you want to use a common data area specified clean-up routine, do the following:

Code the clean-up routine.
Supply the address of the clean-up routine in the first word of the common data area, which is pointed to by CMDXCWKP (the system initializes this field to 0).
The clean-up routine will be invoked when:
1. MPF terminates or
2. MPF is refreshed with a new MPFLSTxx that contains a new .CMD userexit name.
The clean-up routine will get control via a BALR 14, 15 instruction with the CMDXCCDA bit set to 1. Register 1 will be a pointer to an address that points to CMDX.

Note: There is a restriction on the data that resides in the first word of a storage pointed to by CMDXCWKP. It MUST be a valid address of your clean-up routine or zero. During command exit termination, the SET MPF processor checks the first word of the storage pointed to by CMDXCWKP, and if it is non-zero BALR 14, 15 is executed, where register 15 contains the first word pointed to by CMDXCWKP. So, if the first word pointed to by CMDXCWKP is not a valid address of a clean-up routine (it contains any non-zero value) an ABEND can be encountered.

Setting up the common data area: Normally, the first exit routine that anchors work areas from the last 8 bytes of the common data area will also initialize the first 4 bytes to the address of the clean-up routine, as shown in Table 1.

Table 1. Setting Up the Common Data Area
Field	Description
Word 1	Address of an installation-supplied clean-up routine that the exit routine calls when it is to be deleted
Word 2	Address of an installation-defined value (such as the address of a work area)
Word 3	Address of an installation-defined value (such as the address of a work area)

The system initializes the common data area to 0; thereafter, the common data area contains whatever values the exit routines place in it.

The exit routines must manage serialization of the common data area.

Individual Data Area

In addition to the common data area, the MVS commands exit routines each receive from the system the address of an individual 8-byte data area (in field CMDXIWKP of the CMDX) whenever they are invoked. Each exit routine can use its individual data area to:

Pass data to itself (in a work area) across invocations
Process the data during exit deletion

Passing data to itself: To enable an exit routine to pass data to itself across invocations, code the exit routine to:

Create a work area in the ECSA by issuing a GETMAIN or STORAGE macro
Place the address of the work area in the individual data area.

To obtain the address of the work area, code the exit routine to access the individual data area. As with the common data area, each individual data area is initialized to zero by the system and subsequently contains whatever values the exit routine places in it.

Processing during exit deletion: A command exit will be invoked once before deletion if its individual work area is non-zero. For this final invocation, the bit CMDXCIDA will be set to 1. The exit should then clean up and free any storage pointed to from the individual work area. Exit deletion occurs when:

MPF terminates or
MPF is refreshed with a new MPFLSTxx that contains a new .CMD userexit name.

Note: There is NO restriction on the data pointed to by CMDXIWKP. The data can be bits or pointers to other data areas that contain data.

Each exit routine must manage serialization of its individual data area.

Macro Instructions and Restrictions

The MVS commands exit routines can issue system macros, but you should be aware of the following restrictions:

Do not install an exit routine that issues the WAIT macro or calls a service that issues a WAIT. WAITs and implied WAITs can terminate console communications.
Do not use macros whose expansions store data into an in-line parameter list.
Do not issue the GETMAIN or STORAGE macro for subpools that represent space within a region (0 — 127, 240, or 250—252). Because the exit routines execute as part of the control program, they can use subpools 229, 230, and 249.
Do not issue the DYNALLOC macro. Requesting dynamic allocation functions can cause an abend if your exit is processing a command that originated from a console. To avoid the abend, create a subsystem that runs in its own address space, and request dynamic allocation functions through that subsystem.

Security Consideration

It is the responsibility of your installation to provide any required security for an exit routine that issues system commands. For example, the routine can issue the RACROUTE REQUEST=VERIFYX macro to obtain the user token for a user id that is authorized to the command and then append the security token to the MGCRE macro parameter list. See System Authorization Facility (SAF) in the z/OS MVS Programming: Authorized Assembler Services Guide for further information on the security interface.

Entry Specifications

On entry, register 1 points to the address of the MVS commands exit parameter list (CMDX).

Registers at Entry: The contents of the registers on entry to the exit are as follows:

Register: Contents
0: Not applicable
1: Address of the pointer to the CMDX
2-12: Not applicable
13: Register save area
14: Return address
15: Entry point address of the exit routine

Parameter List Contents: Register 1 contains a pointer to the address of the commands exit parameter list (CMDX). The CMDX is mapped by the IEZVX101 macro (data area CMDX). See z/OS MVS Data Areas in the z/OS Internet library for a description of the IEZVX101 mapping.

Return Specifications

Registers at Exit: Upon return from the exit, the register contents must be:

Register

Contents

0-14

Restored to contents at entry

15

One of the following return codes:

Return Code: Explanation
0: Indicates that the exit routine requests that the system process the command in the parameter list. The routine takes no action in processing the command itself.
2: Indicates that the user is not authorized to issue the command. No more exits are invoked for the command, and the subsystem call is bypassed.
4: Indicates that the exit routine (or module called from the routine) has processed the command. On return, the system takes no further action.
8: Indicates that the exit (or module called by the exit) should process the command but cannot at this time. The system issues message IEE707I. No more exits are invoked, and the subsystem call is bypassed.

Any value higher than 8 indicates an error condition.

Note: Installation-modified command text is used only when the exit routine returns a 0 return code.

Coded Example of the Exit Routine

The following is a coded example of an MVS commands installation routine that can be used to modify command processing:

*******************************************************************
*                                                                 *
* MODULE NAME      : CMDXIT                                       *
*                                                                 *
* DESCRIPTIVE NAME : SAMPLE COMMUNICATIONS TASK INSTALLATION EXIT *
*                    MODIFYING DISPLAY COMMANDS.                  *
*                                                                 *
* FUNCTION         : FOR DISPLAY TIME COMMANDS,                   *
*                    THIS EXIT PERMITS THE COMMAND TO BE          *
*                    ENTERED WITHOUT THE BLANK BETWEEN THE VERB   *
*                    AND THE PARAMETER. SPECIFICALLY              *
*                    - DT BECOMES DISPLAY T                       *
*                                                                 *
*  OPERATION       : GET THE ADDRESS OF THE COMMAND BUFFER WHICH  *
*                     IS POINTED TO BY CMDXCLIP.                  *
*                    DETERMINE IF THE COMMAND IS 'DT'. NO         *
*                     PROCESSING IS DONE IN THIS EXIT FOR ANY     *
*                     OTHER COMMANDS.                             *
*                    FOR DT CHANGE THE COMMAND TO DISPLAY T.      *
*                                                                 *
*  NOTES           : FIRST 2 BYTES OF THE COMMAND BUFFER          *
*                    CONTAINS THE LENGTH OF THE COMMAND AND       *
*                    THE REST OF THE BUFFER CONTAINS THE COMMAND  *
*                    IMAGE. THE BUFFER IS 128 BYTES LONG.         *
*                                                                 *
* ENTRY POINT      : CMDXIT                                       *
*                                                                 *
*  PURPOSE         : ADD A BLANK BETWEEN THE DISPLAY VERB AND     *
*                    SUBPARAMETER 'T' TO PERMIT A SHORTER FORM    *
*                    OF THE COMMAND.                              *
*                                                                 *
*  LINKAGE         : BALR                                         *
*                                                                 *
*  INPUT DATA      : REG1 POINTER TO THE ADDRESS OF THE CMDX      *
*                  : REG13 ADDRESS OF STANDARD SAVE AREA          *
*                  : REG14 RETURN ADDRESS                         *
*                  : REG15 ENTRY POINT                            *
*                                                                 *
*  REGISTERS SAVED : REG14 - REG12                                *
*                                                                 *
*  REGISTER USAGE  : REG0 - PARAMETER REGISTER                    *
*                    REG1 - PARAMETER REGISTER                    *
*                    REG2 - WORK REGISTER                         *
*                    REG3 - WORK REGISTER                         *
*                    REG4 - WORK REGISTER                         *
*                    REG5 - CMDX                                  *
*                    REG6 - COMMAND BUFFER                        *
*                    REG7 - UNUSED                                *
*                    REG8 - UNUSED                                *

*                    REG9 - UNUSED                                *
*                    REG10 - UNUSED                               *
*                    REG11 - UNUSED                               *
*                    REG12 - MODULE BASE REGISTER                 *
*                    REG13 - STANDARD SAVE AREA                   *
*                    REG14 - RETURN ADDRESS                       *
*                    REG15 - RETURN CODE ON EXIT                  *
*                                                                 *
*  REGISTERS RESTORED :  REG14 - REG12                            *
*                                                                 *
* CONTROL BLOCKS   :                                              *
*                                                                 *
*  NAME        MAPPING MACRO      REASON USED             USAGE   *
*  ----        -------------      -----------             -----   *
*  CMDX        IEZVX101           CMD INSTALLATION EXIT   R,W     *
*                                 PARAMETER LIST                  *
*                                                                 *
*  KEY = R-READ, W-WRITE, C-CREATE, D-DELETE                      *
*                                                                 *
*  DATA TABLE       : NONE                                        *
*                                                                 *
*  DATA AREA        : NONE                                        *
*                                                                 *
* EXECUTABLE MACROS : WTO                                         *
*                                                                 *
*                                                                 *
*******************************************************************
CMDXIT   CSECT
CMDXIT   AMODE 31                      31 BIT ADDRESSING MODE
CMDXIT   RMODE ANY                     31 BIT RESIDENCE
REG1     EQU   1
REG2     EQU   2
REG4     EQU   4
CMDXPTR  EQU   5
BUFFPTR  EQU   6
REG12    EQU   12
REG14    EQU   14
REG15    EQU   15
         EJECT ,
         BAKR  REG14,0                 SAVE CALLER'S REGISTERS
         BALR  REG12,0                 ESTABLISH MODULE BASE
         USING *,REG12
         L     CMDXPTR,0(REG1)         GET CMDX ADDRESS
         USING CMDX,CMDXPTR            ACCESS THE CMDX
         L     BUFFPTR,CMDXCLIP        GET THE COMMAND BUFFER ADDRESS
         USING CMDXCLIB,BUFFPTR        ACCESS THE BUFFER
         LA    REG2,CMDXCMDI           ACCESS START OF TEXT
         CLC   0(L'DT,REG2),DT         IS THIS DT
         BNE   EXIT                    NO, NO PROCESSING FOR COMMAND

*******************************************************************
*        PROCESS THE DT COMMAND.                                  *
*        1. ALTER THE TEXT IN THE COMMAND BUFFER TO D T           *
*        2. INDICATE TEXT CHANGE REQUEST                          *
*******************************************************************
         MVC   CMDXCMDI(L'D_T),D_T     MOVE IN D T
         LA    REG4,L'D_T              GET NEW COMMAND LENGTH
         STH   REG4,CMDXCMDL           STORE NEW COMMAND LENGTH
         OI    CMDXRFL1,CMDXRCMI       REQUEST TEXT CHANGE
EXIT     EQU   *
         XR    REG15,REG15             SYSTEM TO PROCESS COMMAND
         PR                            RETURN TO CALLER
DT       DC    C'DT'                   SHORT FORM OF D T
D_T      DC    C'D T'                  REAL D T
         IEZVX101
         END   CMDXIT