HP OpenVMS Systems Documentation

Terminates execution of a command, an image, a command procedure, a command procedure that was interrupted by a Ctrl/Y function, or a detached process or subprocess.

Requires GROUP privilege to stop other processes in the same group. Requires WORLD privilege to stop processes outside your group.

Format

STOP [process-name]

Parameter

process-name

Requires that the process be in your group.

Specifies the name of the process to be deleted. The process name can have from 1 to 15 alphanumeric characters. If the process-name includes spaces or lowercase letters, enclose the name in quotation marks (" ") to preserve the correct spelling.

The specified process must have the same group number in its user identification code (UIC) as the current process; you cannot use the process-name parameter to stop a process outside of your group. To stop a process outside of your group, you must use the qualifier /IDENTIFICATION=pid.

The process name is incompatible with the /IDENTIFICATION qualifier; if you use the /IDENTIFICATION qualifier, the process name is ignored. If you include neither the process-name parameter nor the /IDENTIFICATION qualifier with the STOP command, the image executing in the current process is terminated.

Description

The STOP command causes an abnormal termination of the image that is currently executing. If the image has declared user-mode exit-handling routines using calls to the $DCLEXH system service, by default these exit handlers are not invoked. If execution of exit-handling routines is required, use the EXIT command or the STOP/EXIT command to terminate the image so that the mode-specific exit handlers are invoked.

If the STOP command is executed from a noninteractive process (such as a batch job), the process terminates.

Note that when an image has been interrupted by a Ctrl/Y function and subsequently the DCL RUN command or a non-CLI-based DCL verb is entered, the interrupted image is terminated. However, in this case, exit-handling routines execute before the next image is run. For more information about process and image rundown processing, see the OpenVMS User's Manual or the HP OpenVMS Programming Concepts Manual.

If you press Ctrl/Y to interrupt a command procedure and then enter the STOP command, or if the STOP command is executed in a command procedure, all command levels are unstacked and control returns to command level 0 (DCL level with the $ prompt).

If you specify a process name or process identification (PID) code, the STOP command terminates the image currently executing in the specified process and deletes the process. If the process is noninteractive, no notification of the deletion occurs and the log file for the job is not printed.

Qualifiers

/IDENTIFICATION=pid

Specifies the system-assigned process identification (PID) code. When you create a process with the RUN command, the RUN command displays the PID code of the newly created process. The /IDENTIFICATION qualifier can be used in place of the process name parameter.

You can omit any leading zeros in specifying the PID code.

/IMAGE [/IDENTIFICATION=pid] [process-name]

Calls the $FORCEX system service to stop the image of the target process specified in the process id or process name that is currently executing. The target process is not deleted.

If you omit the /IDENTIFICATION qualifier and the process name, the STOP/IMAGE command is identical to the STOP command.

/EXIT[=access-mode] (default)

/NOEXIT

Specifies an option to call exit handlers prior to deletion of the process.

The following table describes the access mode options:

Mode	Description
EXECUTIVE_MODE	Execute executive and more privileged mode exit handlers (default, if no access mode specified).
KERNEL_MODE	Execute kernel mode exit handlers.
SUPERVISOR_MODE	Execute supervisor and more privileged mode exit handlers.
USER_MODE	Execute user and more privileged mode exit handlers.

Examples

$ RUN MYPROG
   .
   .
   .
[Ctrl/Y]
Interrupt
$ STOP
      

The RUN command in this example begins executing the image MYPROG. Subsequently, the Ctrl/Y function interrupts the execution. The STOP command then terminates the image.

$ @TESTALL
   .
   .
   .
 
[Ctrl/Y]
Interrupt
$ STOP
 
      

The @ (execute procedure) command in this example executes the procedure TESTALL.COM. Subsequently, the Ctrl/Y function interrupts the procedure. The STOP command then returns control to the DCL command interpreter.

$ RUN/PROCESS_NAME=LIBRA  LIBRA 
%RUN-S-PROC_ID, identification of created process is 0013340D
   .
   .
   .
$ STOP LIBRA
 
      

The RUN command in this example creates a subprocess named LIBRA to execute the image LIBRA.EXE. Subsequently, the STOP command causes the image to exit and deletes the process.

$  ON ERROR THEN STOP
   .
   .
   .
      

In a command procedure, the ON command establishes a default action when any error occurs in the execution of a command or program. The STOP command stops all command levels. If this ON command is executed in a command procedure, which in turn is executed from within another procedure, control does not return to the outer procedure, but to DCL command level 0.

$ STOP/EXIT
      

Terminates the process and runs exit handlers beginning at executive mode.

$ STOP/IMAGE/ID=12345678
      

Terminates the current user image being executed by process 12345678.