HP OpenVMS Systems Documentation

Starts the clusterwide queue manager for the queuing system and opens that queue manager's queue database files. The /QUEUE qualifier is optional, but the /MANAGER qualifier is required.

By default, the command affects the default queue manager, SYS$QUEUE_MANAGER. Specify the /NAME_OF_MANAGER qualifier to start a queue manager other than the default.

For more information, refer to the chapter on the queue manager in the HP OpenVMS System Manager's Manual.

Requires OPER (operator) and SYSNAM (system logical name) privileges.

Format

START/QUEUE/MANAGER [dirspec]

Parameter

dirspec

Specifies the directory location to contain the system queue and journal files of the queue database. The queue file has a file type of QMAN$QUEUES and contains queue definitions. The journal file has a file type of QMAN$JOURNAL and contains job and other information that lets the queue manager to return to its last known state should a system be stopped unexpectedly. These files must reside in the same directory.

The default location of the queue and journal files is SYS$COMMON:[SYSEXE]. The optional dirspec parameter is used only for specifying an alternate location for the queue and journal files. The specification must include at least the device and directory name. The asterisk (*) and the percent sign (%) wildcard characters are not allowed in the directory specification.

The directory you specify must be available to all nodes that can run the queue manager. If the directory specification is a concealed logical name, it must be identically defined on all nodes in the cluster.

The location of the queue and journal files is stored in the master file of the queue database. You do not have to respecify the directory location with subsequent START/QUEUE/MANAGER commands.

For information about changing the location of any of the queue database files, refer to the chapter on the queue manager in the HP OpenVMS System Manager's Manual.

Description

The START/QUEUE/MANAGER command has the following uses:

• Enter the command START/QUEUE/MANAGER/NEW_VERSION to create the queue database and initially start a queue manager. See the description of the /NEW_VERSION qualifier for more information. Once the queue manager has been started, it will remain running unless it is explicitly stopped with the STOP/QUEUE/MANAGER/CLUSTER command.
• If the STOP/QUEUE/MANAGER/CLUSTER command has been executed, enter the START/QUEUE/MANAGER command to restart a queue manager.
• In an OpenVMS Cluster, enter the START/QUEUE/MANAGER command with the /ON qualifier to modify the list of preferred nodes on which a queue manager can run. See the description of the /ON qualifier for more information.
• In an OpenVMS Cluster, enter the START/QUEUE/MANAGER command to ensure that a queue manager process is executing on the most preferred, available node. If the queue manager is not running on the most preferred, available node, the queue manager will be moved to that node without interruption of service. If you are using the default node list (*), the queue manager will not move. For more information, see the description of the /ON qualifier.

If the queue manager is in a location other than the default, and in OpenVMS Cluster environments with multiple system disks, you must define the logical name QMAN$MASTER. For instructions, refer to the chapter about the queue manager and queue database in the HP OpenVMS System Manager's Manual.

If a queue manager does not start when you enter the START/QUEUE/MANAGER command, you will receive the following message:

%JBC-E-QMANNOTSTARTED, queue manager could not be started

If you see this message, search the operator log file SYS$MANAGER:OPERATOR.LOG (or look on the operator console) for messages from the facilities QUEUE_MANAGE and JOB_CONTROL for information about the problem, as follows:

$ SEARCH SYS$MANAGER:OPERATOR.LOG /WINDOW=5 QUEUE_MANAGE,JOB_CONTROL

Qualifiers

/ADD

Creates an additional queue manager in the existing queue database. If the named queue manager already exists, the request will be rejected.

/NAME_OF_MANAGER=name

Creates a non-default queue manager. The required name value may be up to 31 characters long and may be a logical. The name will serve as the identifier for the queue manager process and the portion of the database that it is managing.

/NEW_VERSION

/NONEW_VERSION (default)

Specifies that a new (empty) version of the queue database is to be created. This qualifier is required when initially creating and starting the queuing system.

If you specify this qualifier and a queue database already exists, the new master and queue files of the queue database supersede existing versions of those files; however, the journal file of the existing queue database is deleted. Jobs and other information are lost.

/ON=(node[,...])

In an OpenVMS Cluster, specifies the nodes on which a clusterwide queue manager can run. The default value for the node list is the asterisk (*) wildcard character, meaning that all nodes in the cluster are eligible to run the queue manager. If the node on which the queue manager is running leaves the cluster, the queue manager can automatically fail over to any available node in the cluster. However, to specify a preferred order in which the nodes should claim the queue manager, or to limit the nodes which can run it, you must specify the /ON qualifier.

The node list you specify is stored in the queue database. Anytime the START/QUEUE/MANAGER command is entered and neither the /NEW_VERSION nor /ON qualifier is specified, the /ON list stored in the queue database remains unchanged.

For highest availability, specify the asterisk (*) wildcard character as the last node in the node list to indicate that any remaining unlisted node can claim the queue manager, with no preferred order. If you do not specify the asterisk (*) wildcard character last in the node list, the queue manager can only fail over if one of the nodes in the list is available; however, if you want to exclude certain nodes from being eligible to run the queue manager, you cannot use the asterisk (*) wildcard character. You cannot specify the asterisk (*) wildcard character as part of a node name.

Anytime the START/QUEUE/MANAGER command is entered (with or without the /ON qualifier), the job controller will check to see if one or more preferred queue manager nodes was currently or previously specified with the /ON qualifier. If one or more preferred nodes was specified, and the queue manager is running on a node other than the first available node of those specified, the queue manager process is moved from its current node and restarted on the first available preferred node. Despite the transition, queues on the running nodes are not stopped. All requests to the queuing system, for example, PRINT, SUBMIT, and SHOW ENTRY requests, will complete as expected.

Examples

$ START/QUEUE/MANAGER/NEW_VERSION
$ SHOW QUEUE
%JBC-E-NOSUCHQUE, no such queue

      

The START/QUEUE/MANAGER command in this example starts the queue manager and creates the queue and journal files in the default location, SYS$COMMON:[SYSEXE]. Because the asterisk (*) wildcard character is used as the default value for the list of nodes on which the queue manager can run, the queue manager will be able to fail over to any available node in the cluster.

This command starts the default queue manager SYS$QUEUE_MANAGER because the /NAME_OF_MANAGER qualifier is not specified.

Both the SYS$COMMON:[SYSEXE] location and the asterisk value for the /ON qualifier are stored in the queue database for future reference. The newly created queue database contains no queues or jobs. The SHOW QUEUE command shows that no queues are defined on this cluster.

$ START/QUEUE/MANAGER/NEW_VERSION -
_$ /ON=(SATURN,VENUS,NEPTUN,*) DUA5:[SYSQUE]
      

The START/QUEUE/MANAGER command in this example creates the queue and journal files on the cluster-accessible disk volume DUA5, in directory SYSQUE. You must mount the disk before you enter the START/QUEUE/MANAGER command.

The /ON qualifier specifies that the queue manager should run first on node SATURN. If SATURN leaves the cluster, the queue manager will attempt to fail over to VENUS. If VENUS is not available, the queue manager will attempt to fail over to NEPTUN. If NEPTUN is not available, the queue manager will fail over to any other available node in the cluster.

$ START/QUEUE/MANAGER/NEW_VERSION -
_$ /ON=(SATURN,VENUS,NEPTUN,*) DUA5:[SYSQUE])
   .
   .
   .
$ START/QUEUE/MANAGER
      

The START/QUEUE/MANAGER command in this example creates the queue database as shown in the previous example. Suppose the queue manager started on node SATURN.

Later, SATURN is removed from the cluster, and the queue manager fails over to node VENUS. When SATURN rejoins the cluster, the second START/QUEUE/MANAGER command in the example is entered to move the queue manager back to node SATURN.

The second START/QUEUE/MANAGER command does not specify the DUA5:[SYSQUE] parameter value or the /ON qualifier and its node list because those previously supplied pieces of information are stored in the queue database. The queue manager continues to use the queue and journal files found at the location stored in its database. The /ON list, stored as a result of the previous START/QUEUE/MANAGER command, also remains unchanged.

$ START/QUEUE/MANAGER DUA4:[SYSQUE]
%JBC-E-QMANNOTSTARTED, queue manager could not be started
$ SEARCH SYS$MANAGER:OPERATOR.LOG /WINDOW=5 QUEUE_MANAGE,JOB_CONTROL
%%%%%%%%%%%  OPCOM  14-DEC-2001 18:55:18.23  %%%%%%%%%%%
Message from user QUEUE_MANAGE on QMUNGR
%QMAN-E-OPENERR, error opening DUA4:[SYSQUE]SYS$QUEUE_MANAGER.QMAN$QUEUES;

%%%%%%%%%%%  OPCOM  14-DEC-2001 18:55:18.29  %%%%%%%%%%%
Message from user QUEUE_MANAGE on QMUNGR
-RMS-F-DEV, error in device name or inappropriate device type for operation

%%%%%%%%%%%  OPCOM  14-DEC-2001 18:55:18.31  %%%%%%%%%%%
Message from user QUEUE_MANAGE on QMUNGR
-SYSTEM-W-NOSUCHDEV, no such device available
$ START/QUEUE/MANAGER DUA5:[SYSQUE]
      

In this example, the first START/QUEUE/MANAGER command specifies device DUA4: as the location of the queue and journal files. The error message indicates that the queue manager does not start. The SEARCH command searches the operator log file for relevent messages, and reveals that device DUA4: does not exist. The second START/QUEUE/MANAGER command specifies the correct device name, DUA5:.

Adds a zone to the running VAXft system. For more information on the START/ZONE command, refer to the VAXft systems documentation.

Applies only to the VAXft system. Requires CMKRNL (change mode to kernel) privilege.

Format

START/ZONE

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, refer to the OpenVMS User's Manual or the 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.

Stops the specified secondary processor or processors (and any associated vector processors). The /CPU qualifier is required.

Applies only to OpenVMS multiprocessing systems. Requires CMKRNL (change mode to kernel) privilege.

Format

STOP/CPU [cpu-id[,...]]

Parameter

cpu-id[,...]

Specifies a decimal value representing the identity of a processor in an OpenVMS multiprocessing system. On a VAX 6000 system or an Alpha 7000 system, the CPU ID is the backplane slot number of the processor. If you do not specify a CPU ID, the STOP/CPU command selects a processor in the current active set to stop.

Description

The STOP/CPU command removes a secondary processor from the active set in an OpenVMS multiprocessing system. If the secondary processor is not executing a process when the STOP/CPU command is issued, it enters the STOPPED state. If the secondary is executing a process at the time, it continues to execute the current process until it attempts to schedule another process. When this occurs, the secondary enters the STOPPED state.

The OpenVMS operating system subjects a processor to a set of checks when it is the object of a STOP/CPU command. As a result, you may not be permitted to stop certain processors that are vital to the functioning of the system. In these cases, there is usually a process in the system that can execute only on the processor you intend to stop. You can determine this by issuing a SHOW CPU/FULL command. In unusual circumstances, you can bypass the checking mechanism by using the /OVERRIDE_CHECKS qualifier in the command.

The STOP/CPU command has no effect if its object processor is already in the STOPPED state when it is issued.

Qualifiers

/ALL

Stops all eligible secondary processors in the system's active set.

/ASSIGN=option (Alpha only)

Assigns specified processors to the hard partition node after they are stopped.

Option	Description
$$HARD_PARTITION	The configuration tree hard partition node. All instances running in the hard partition defined by this node have visibility and access to CPUs owned at this level.

Supported only on AlphaServer systems that support partitioning.

/MIGRATE (Alpha only)

Transfers ownership of the CPU from the current instance to another soft partition.

Option	Description
instance_name	The name of any valid running instance in the current hard partition.
partitionID	The numeric ID of any partition (reflected in the configuration tree) in the current hard partition. An operating system instance is not required to be running with this identifier.

Supported only on AlphaServer systems that support partitioning.

/OVERRIDE_CHECKS

Directs the STOP/CPU command to bypass a series of OpenVMS scheduling checks that determine whether the specified processor is eligible for removal from the active set.

Note that this is not an unconditional operation; other CPU load or configuration constraints may prevent the specified processor from being stopped.

/POWER=OFF (Alpha only)

Powers down the CPU after it is removed from the active set. The CPU will be powered down while still owned by the instance, prior to any assignments.

The /POWER qualifier cannot be used in conjunction with the /MIGRATE qualifier.

Supported only on AlphaServer GS series systems.

Examples

$ STOP/CPU
      

The STOP/CPU command in this example selects a processor and removes it from the multiprocessing system's active set.

$ STOP/CPU 4,7
      

The STOP/CPU command in this example selects the processors with CPU IDs 4 and 7 and removes them from the multiprocessing system's active set.

$ STOP/CPU/OVERRIDE_CHECKS 8
      

The STOP/CPU/OVERRIDE_CHECKS command in this example overrides some OpenVMS scheduling states that ordinarily prevent the operation and stops the processor with the CPU ID of 8. Then it is removed from active participation in the multiprocessing system.

$ STOP/CPU/ALL
      

The STOP/CPU/ALL command in this example stops all eligible secondary processors in the active set and removes them from the multiprocessing system.

$ STOP/CPU/MIGRATE=WFGLXE 5
      

The STOP/CPU/MIGRATE command in this example removes CPU 5 from the current instance's active set and transfers ownership to instance WFGLXE in the current hard partition.

$ STOP/CPU/ASSIGN=$$HARD 6
      

The STOP/CPU/MIGRATE command in this example removes CPU 6 from the current instance's active set and transfers ownership to the hard partition node in the configuration tree. The CPU is immediately available for assignment for any instance within the hard partition defined by that node.