MODIFY DIAGNOSE Statement

Purpose

Use the MODIFY DIAGNOSE statement to redefine an existing DIAGNOSE code on the system during initialization.

You can also redefine an existing DIAGNOSE code after initialization using the MODIFY DIAGNOSE command. For more information, see MODIFY DIAGNOSE.

How to Specify

Include as many statements as needed; they are optional. You can place MODIFY DIAGNOSE statements anywhere in the system configuration file. If you specify more than one statement with the same operands, the last operand definition overrides any previous specifications.

Operands

diag

is the number of the DIAGNOSE code that you are redefining. The variable diag must be a hexadecimal number between X'0100' and X'01FC' and must be a multiple of 4. All other DIAGNOSE code numbers are reserved for IBM® use only.

RESET

tells CP to stop using the customer-written DIAGNOSE code and return to using the existing DIAGNOSE code that was shipped with the z/VM® product.

EPName name

tells CP the name of the entry point that contains the code to process the DIAGNOSE code. The variable name 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 alphanumeric characters, the 4 special characters ($, #, _, and @), or any combination thereof.

PRIVCLASSANY

tells CP that users with any privilege class can issue the DIAGNOSE code that you are redefining.

PRIVclasses classes

tells CP that only users with 1 or more of the specified privilege classes can issue the DIAGNOSE code that you are redefining. Whatever you specify on this operand will replace the current privilege classes. The variable classes is 1 or more privilege classes in the range A through Z, 1 through 6, or an asterisk (*). Privilege class * indicates all privilege classes (A-Z and 1-6).

Note: If you want more than one privilege class, specify your classes in one string of characters. Do not separate the classes with blank spaces. For example, specify privclasses abc123, not privclasses a b c 1 2 3.

CHECKR15 YES

CHECKR15 NO

indicates whether the diagnose router should check register 15 upon return from the diagnose handler.

Usage Notes

1. To define a new DIAGNOSE code, use the DEFINE DIAGNOSE statement or CP command. For more information, see DEFINE DIAGNOSE Statement and DEFINE DIAGNOSE.
   Note: Unless you specify the ENABLE operand of the DEFINE DIAGNOSE statement or command, the new DIAGNOSE code is initially in a disabled state after being defined.
2. To load the DIAGNOSE processing code into the system execution space, use the CPXLOAD statement or CPXLOAD CP command. For more information, see CPXLOAD Statement and CPXLOAD.
3. If you do not specify the ENABLE operand, a new DIAGNOSE code is initially in a disabled state after being defined. CP treats disabled DIAGNOSE codes as if they were never defined. If you try to use a disabled DIAGNOSE code in a program, CP will give you a program check specification exception.
4. To activate a DIAGNOSE code while defining it, use the ENABLE operand of the DEFINE DIAGNOSE statement or command. For more information, see DEFINE DIAGNOSE Statement and DEFINE DIAGNOSE.
5. To activate a new DIAGNOSE code after defining it, use the ENABLE DIAGNOSE statement or ENABLE DIAGNOSE CP command. For more information, see ENABLE DIAGNOSE Statement and ENABLE DIAGNOSE.
6. To display information about a DIAGNOSE code (status, entry point name, and privilege class) after initialization, use the QUERY DIAGNOSE command. For more information, see QUERY DIAGNOSE.
7. To display the address of the CP DIAGNOSE code table block for a DIAGNOSE code after initialization, use the LOCATE DGNBK command. For more information, see LOCATE DGNBK.
8. To deactivate a DIAGNOSE code after defining it, use the DISABLE DIAGNOSE statement or command. For more information, see DISABLE DIAGNOSE Statement and DISABLE DIAGNOSE.
9. To deactivate a DIAGNOSE code while defining it, use the DISABLE operand of the DEFINE DIAGNOSE statement or command. For more information, see DEFINE DIAGNOSE Statement and DEFINE DIAGNOSE.
10. To remove the DIAGNOSE processing code from the system execution space, use the CPXUNLOAD command. For more information, see CPXUNLOAD.
11. Many external security managers (ESMs) do not support DIAGNOSE codes above X'03FC'. For this reason, CP does not support DIAGNOSE codes above X'03FC'. The DIAGNOSE codes between X'0000' and X'03FC' are divided as follows:

    X'0000' to X'00FC'

    Reserved for IBM use

    X'0100' to X'01FC'

    Reserved for customer use

    X'0200' to X'03FC'

    Reserved for IBM use.

12. When CHECKR15 YES is specified, the diagnose router will check register 15 on return from the diagnose handler. If register 15 contains:

    RC = 0

    Processing was successful. Complete the guest instruction.

    RC = 4

    Processing failed due to a condition which would cause a guest program check. Simulate guest program interruption passed in R0.

    RC = 8

    Nullify the instruction.

    RC = 12

    Present the machine check then nullify the instruction. R2 will contain the address of the MCRBK which will contain the machine check information.

    RC = 16

    Generate machine check for processing damage, then go to HCPENDOP to terminate the instruction.

    RC = 20

    Present the machine check, then go to HCPENDOP to terminate the instruction. R2 will contain the address of the MCRBK, which contains machine check information.

    RC = 24

    Issue error message or soft abend for paging I/O error, then nullify the instruction. R1 has the message or abend number.

    If a return code is invalid (negative, not a multiple of 4 or too big ( RC > 24 )), then a soft abend will occur.

13. For more information about user-defined DIAGNOSE codes, see z/VM: CP Exit Customization.