DEFINE EXIT
Authorization
Privilege Class: A
Purpose
Use DEFINE EXIT to dynamically define a new exit point in CP.
You can also dynamically define a new CP exit point during system initialization using the DEFINE EXIT configuration file statement. For more information, see DEFINE EXIT Statement in z/VM®: CP Planning and Administration.
Operands
- exit
- is the number of the exit point you are defining. This value must be a hexadecimal number between X'0' and X'FFFF'. The recommended value is between X'F000' and X'FFFF', because that range is reserved for customer use. All other exit numbers are reserved for IBM, vendor, or general use.
- AT entry + offset instruction
- identifies the location of the exit point you are defining and the instruction that is located at the exit point. The variable entry must be a 1-to-8-character string. The first character must be alphabetic or one of the following special characters: $ (dollar sign), # (number sign), _ (underscore), or @ (at sign). The rest of the string can be alphabetic or numeric characters, the four special characters ($, #, _, or @), or any combination. The variable offset must be a 1-to-4-character even hexadecimal number between X'0' and X'FFFE'. The variable instruction must be a 2-, 4-, or 6-character hexadecimal number.
- NORESolve
- tells CP to resolve the entry points associated with this exit number the first time they are called. This is the default.
- RESolve
- tells CP to resolve the entry points associated with this exit number when the association is first established. Any existing associated entry points are resolved immediately.
- PARM parameter
- is a list of one or more parameters to be supplied to the exit. Five kinds of tokens can be used
to define a parameter:
- Addresses: strings up to eight characters long, consisting of the hexadecimal digits 0 through 9 and A through F.
- General Registers: strings beginning with G or R, followed by a decimal number between 0 and 15 or a hexadecimal digit, designating the contents of a general register.
- Indirection: a percent sign (%), which causes the contents of an address or the contents of an address in a register to be used instead of the address or register contents itself.
- Arithmetic: a plus sign (+) or minus sign (-).
- Displacement: strings of up to four hexadecimal digits.
Each parameter string specifies how to combine these tokens to generate a parameter value to be passed to an exit routine. The following is a Backus-Naur definition of the syntax of a parameter:<parameter> ::= <anchor> | <anchor><vector> <anchor> ::= <reg> | 0...FFFFFFFF | <anchor>% <vector> ::= <modifier> | <vector>% | <vector><modifier> <modifier> ::= +<disp> | -<disp> | +<reg> | -<reg> <reg> ::= G<digit> | R<digit> <digit> ::= 0...15 | 0...9, A...F <disp> ::= 0...7FFF
Usage Notes
- To load the exit processing code into the system execution space, use the CPXLOAD command (see CPXLOAD).
- To assign entry points or external symbols to an exit point, use the ASSOCIATE EXIT command (see ASSOCIATE EXIT).
- To activate a new exit after defining it, use the ENABLE EXITS command (see ENABLE EXITS).
- To change the definition of an existing dynamic exit point, or to remove the exit point from the system, use the MODIFY EXIT command (see MODIFY EXIT).
- To display information about an exit (status, entry point name, and parameters), use the QUERY EXITS command (see QUERY EXITS).
- Exit numbers are allocated as follows:
- X'0000' to X'7FFF' are reserved for IBM® use.
- X'8000' to X'EFFF' are reserved for vendor and general use.
- X'F000' to X'FFFF' are reserved for private customer use.
- The RESOLVE option ensures that the entry names associated with an exit point are defined.
- Each exit is passed a parameter list that begins with three standard parameters, as described in z/VM: CP Exit Customization. Additional parameters, specified by the PARM operand, are optional and follow the first three in the order in which they are specified.
- Errors (for example, addressing exceptions) during evaluation of user-defined parameters when an exit is being invoked cause CP to abend.
- For more information about user-defined exits, see z/VM: CP Exit Customization.
Examples
Example 1:
To define an exit that will be entered every time a MESSAGE command is issued, enter the
following:
define exit f422 at hcpxmgms + 4 41700000
Ready;
Example 2:
To define exit X'F800', pass it two additional parameters, and associate it with entry
point QWERTY, enter the following:
define exit f800 at hcplog + 7ce 41204028 parm gl+8% g4
Ready;
associate exit f800 epname qwerty
Ready;
enable exits f800
Ready;
query exits f800
Exit Status Calls Returns Seconds
F800 Enabled 0 0 0.000000
Location Instruction Resolution
HCPLOG +0FCE 41204028 NORESOLVE
Defined by: MAINT on 09/03/98 at 13:27:54
PARM R1+8%
R4
EPNAME Attempts Calls Seconds
QWERTY 0 0 0.000000
Ready;
Messages
For the list of general messages for the DEFINE command, see Messages.