DEFINE COMMAND / CMD

Authorization

Privilege Class: A

Purpose

Use DEFINE COMMAND or DEFINE CMD to define a new CP command or a new version (by IBM® class) of an existing CP command on the system.

You can also define a new CP command during initialization using the DEFINE COMMAND or DEFINE CMD configuration file statements. For more information, see DEFINE COMMAND / CMD Statement in z/VM: CP Planning and Administration.

Operands

command

is the name of the command that you are defining. The variable command is a 1- to 12-character string.

Query SUBCmd subcommand

tells CP the name of the CP QUERY subcommand that you are defining. The variable subcommand is a 1- to 12-character string.

Query Virtual SUBCmd subcommand

tells CP the name of the CP QUERY VIRTUAL subcommand that you are defining. The variable subcommand is a 1- to 12-character string.

Set SUBCmd subcommand

tells CP the name of the CP SET subcommand that you are defining. The variable subcommand is a 1- to 12-character string.

ABBRevlength nn

is the length of the smallest acceptable abbreviation of the command or subcommand that you are defining. The variable nn is a decimal number between 1 and the length of the full command or subcommand name.

AFTer_logon

tells CP that the command version you are defining will only be issued by users after they log onto the system. Most CP commands fall into this category. The default is AFTER_LOGON.

BEFore_logon

tells CP that the command you are defining will only be issued by users before they log onto the system. For example, the CP DIAL command can only be used before logon.

Note: If you specify BEFORE_LOGON, you must specify PRIVCLASSANY because CP cannot check privilege classes before a user logs on. Thus, you cannot specify BEFORE_LOGON with the PRIVCLASSES or IBMCLASS operands.

ANYTime

tells CP that the command version you are defining can be issued by users both before and after they log onto the system. For example, many systems let users issue the CP MESSAGE or MSG commands before and after logon.

Note: If you specify ANYTIME, you must specify PRIVCLASSANY because CP cannot check privilege classes before a user logs on. Thus, you cannot specify ANYTIME with the PRIVCLASSES or IBMCLASS operands.

AUDIT

tells the external security manager (ESM) to audit the command that you are defining. When you audit a command, the ESM logs each attempt by users to issue this command.

DISAble

tells CP not to call the entry points and external symbols associated with this CP command until you enable it. (For more information about enabling CP commands, see Usage Note 4.) If omitted, DISABLE is the default.

ENable

tells CP to immediately start calling the entry points and external symbols associated with this CP command.

EPName name

tells CP the name of the entry point that contains the code to process the command. 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.

Note: If you are defining a new command, you must specify EPNAME. If you are defining a new version of an existing command, specifying EPNAME is optional. This is because CP only allows one entry point per command, regardless of how many versions that command has. So, when you define a new version of an existing command, CP already knows the entry point name.

The QUERY and SET commands are the only exceptions, because they have subcommands. Note that CP only allows one entry point per subcommand, regardless of how many versions that subcommand has.

MAC

tells CP to enable mandatory access control (MAC) for the command that you are defining. When MAC is enabled for your command, the external security manager (ESM) compares the security label of the user who issued your command to the security label of the resource or user that your command will affect. If you want the ESM to dynamically turn MAC on or off for this command, specify the VMAC operand.

PRIVCLASSANY

tells CP that users with any privilege class can issue the command that you are defining.

PRIVclasses classes

tells CP that only users with 1 or more of the specified privilege classes can issue the command that you are defining. 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:

1. 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.
2. If you specify PRIVCLASSES, you must also specify IBMCLASS. You can specify these 2 operands in any order.

IBMclass c

tells CP what type of command you are defining. The variable c can be any 1 of the following:

A

this is a system-control command to be used by the primary system operator.

B

this is a command for operational control of real devices.

C

this is a command to alter system storage.

D

this is a command for system-wide control of spool files.

E

this is a command to examine system storage.

F

this is a command for service control of real devices.

G

this is a general-use command used to control the functions of a virtual machine.

Note: If you specify IBMCLASS, you must also specify PRIVCLASSES. You can specify these 2 operands in any order.

PROC

tells CP that, after performing the initial privilege class checks, your command processor will be responsible for any further calls to the external security manager (ESM) for the command that you are defining.

PROT

tells the external security manager (ESM) to protect the command that you are defining. When protection is enabled for your command, the ESM checks an access list to ensure that the user who issued your command is authorized to do so. If you want the ESM to dynamically turn protection on or off for your command, specify the VPROT operand.

SILENTly

tells CP that the responses from the command you are defining can be suppressed by invoking it using the SILENTLY command. For more information, see SILENTLY.

Note: Response suppression is supported only for the ATTACH, DETACH, and GIVE commands.

VMAC

gives the external security manager (ESM) the power to dynamically turn mandatory access control (MAC) on or off. If you specify MAC and VMAC for this command, you are enabling MAC and allowing the external security manager (ESM) to dynamically disable MAC. If you specify VMAC and you do not specify MAC for this command, you are disabling MAC and allowing the ESM to dynamically enable MAC.

VPROT

gives the external security manager (ESM) the power to dynamically turn command access protection on or off. If you specify PROT and VPROT for this command, you are enabling protection and allowing the external security manager (ESM) to dynamically disable that protection. If you specify VPROT and you do not specify PROT for this command, you are disabling protection and allowing the ESM to dynamically enable that protection.

Usage Notes

1. For each existing CP command, CP has at least 1 command table entry block. If the command has more than 1 privilege class, CP has 1 command table entry block for each version of the command. The only exceptions to this are the QUERY and SET commands. CP has at least 1 command table entry block for each QUERY and SET subcommand.
2. When you define a new CP command or a new version of an existing CP command, you must supply CP with certain information about that command. The amount of information you must supply varies depending on what you are defining. You must always supply the command (or subcommand) information and the following table lists any other operands you are required to supply when defining a new command or a new command version.

   When Adding a New:	You Must Specify:
   Command	EPNAME EPNAME PRIVCLASSANY - or - PRIVCLASSES IBMCLASS
   Command Version	PRIVCLASSANY - or - PRIVCLASSES IBMCLASS

3. To load the command processing code into the system execution space, use the CPXLOAD command (see CPXLOAD).
4. If you do not specify the ENABLE operand, the new CP command is initially in a disabled state. This means that the command and any alias that is defined for this command will not function. To activate a CP command after defining it, use the ENABLE COMMAND or CMD command (see ENABLE COMMAND / CMD). This means that the command you defined will now function, as will any alias you have defined and explicitly enabled for that command.
5. To display the address of the CP command table entry block, the current IBM class, and the current privilege class for a specified CP command, use the LOCATE CMDBK command (see LOCATE CMDBK).
6. To change the definition of an existing CP command, use the MODIFY COMMAND or CMD command (see MODIFY COMMAND / CMD).
7. To deactivate a CP command after defining it, use the DISABLE COMMAND or CMD command (see DISABLE COMMAND / CMD). If you disable a base command, any alias that is defined for that command will not function.
8. To obtain information such as the enable/disable status for the command you have defined, use the QUERY CPCMDS command (see QUERY CPCMDS).
9. To remove the command processing code from the system execution space, use the CPXUNLOAD command (see CPXUNLOAD).
10. When specifying a command or subcommand name, you can use special characters in the name. However, we do not recommend that you use the pattern matching characters (* and %). You can use these characters to define commands, but they may seem confusing when you issue the LOCATE CMDBK command. For example, suppose you define 2 new commands: CPU% — to calculate recent CPU busy as a percentage, and CPU1 — to cause some action on real processor number 1. If you issue LOCATE CMDBK CPU%, CP displays information on both CPU% and CPU1, because CP interprets the % in your LOCATE command to be a pattern matching character.

    CP places no restriction on the use of special characters such as *, %, comma, (, ), blank, ⁄, ;, $, #, and @ in command names. However, some External Security Managers (EMSs) restrict their use. Please consult your ESM documentation for information on restricted characters.

11. If you try to define a minimum abbreviation that matches the abbreviation for an existing command, subcommand, or alias, CP rejects your DEFINE command. For example, if you created a QUEUE command with a minimum abbreviation of 2, CP would reject your QUEUE command because QU is an abbreviation for the QUERY command. In this case, you would need to specify a minimum abbreviation greater than or equal to 4 because the first 3 characters of QUERY and QUEUE are identical.
12. Once defined, commands, subcommands, aliases, and Diagnose codes cannot be deleted. They may be altered in various appropriate ways, but they remain in existence until a SHUTDOWN or RESTART IPL is done.
13. MODIFY COMMAND RESET will not allow a RESET to occur if the resulting command versions would have different EPNAMEs. This can occur if you change the EPNAME for a command then add a new version for that command. To avoid this restriction, you should add new versions of a command before changing the EPNAMEs associated with the command.
14. The DEFINE COMMAND or DEFINE DIAGNOSE commands should not be used on a system with an active External Security Manager (ESM); unpredictable results could occur. To safely define a CP command add the DEFINE COMMAND or DEFINE DIAGNOSE statement to the SYSTEM CONFIG file and re-IPL the system. This allows the command and diagnose additions to control structures to be made prior to activating the ESM.
15. For more information about user-defined commands, see z/VM: CP Exit Customization.

Responses

Response 1:

define cmd tell epname hcpxmgms ibmclass a privclasses a
Ready;
define command tell ibmclass b privclasses b
Ready;
define command tell anytime privclassany
Ready;

Response 2:

define cmd continue abbr 4 epname hcpcmcbe ibmclass g priv g
Ready;
define command resume epname hcpcmcbe ibmclass g priv g
Ready;

Messages

For the list of general messages for the DEFINE command, see Messages.