Document revision date: 19 July 1999

Stops the current jobs on the specified queue and requeues them for later processing. The queue does not stop; processing of the first pending job in the queue begins. The /QUEUE qualifier is optional, but the /REQUEUE qualifier is required. The /ENTRY qualifier is required to requeue batch jobs.

Requires delete (D) access to the current or specified job.

Format

STOP/QUEUE/REQUEUE [=queue-name] queue-name[:]

STOP/QUEUE/REQUEUE [=queue-name] /ENTRY=(entry-number[,...]) queue-name[:]

Parameters

queue-name[:]

Specifies the name of the queue that contains the jobs that you want to stop. When you specify a queue name as a parameter for the /REQUEUE qualifier, the jobs are requeued to that queue. Otherwise, the jobs are requeued in the current queue.

entry-number[,...]

Specifies the entry number (or a list of entry numbers) of the jobs you want to requeue. If you specify only one entry number, you can omit the parentheses.

The system assigns a unique entry number to each queued print or batch job in the system. By default, the PRINT and SUBMIT commands display the entry number when they successfully queue a job for processing. These commands also create or update the local symbol $ENTRY to reflect the entry number of the most recently queued job. To find a job's entry number, enter the SHOW ENTRY or SHOW QUEUE command.

Description

The STOP/QUEUE/REQUEUE command causes the system to requeue the jobs for later processing or for execution in the queue. If the print symbiont has sent checkpoint information about a print job to the job controller, printing resumes at the last checkpoint recorded, unless you enter the SET ENTRY/NOCHECKPOINT command before the job is reinitiated. Batch jobs generally restart at the beginning; however, batch jobs that contain SET RESTART_VALUE commands run only those portions of the job that have not completed successfully.

Use the STOP/QUEUE/ABORT command to stop a current print job without requeueing it. Use the STOP/QUEUE/ENTRY command to stop a current batch job without requeueing it. You also can use the STOP/QUEUE/ENTRY command to stop a print job without requeueing it. Use the DELETE/ENTRY command to delete an entry that is queued and is waiting to be executed or processed.

Note If you enter the STOP/QUEUE/REQUEUE command accidentally for a malfunctioning queue, enter the STOP/QUEUE/RESET command to stop the queue in an orderly fashion.

Qualifiers

/ENTRY=(entry-number[,...])

Specifies the entry number of one or more jobs you want to abort. If you specify only one entry number, you can omit the parentheses.

The system assigns a unique entry number to each queued print or batch job in the system. By default, the PRINT and SUBMIT commands display the entry number when they successfully queue a job for processing. These commands also create or update the local symbol $ENTRY to reflect the entry number of the most recently queued job. To find a job's entry number, enter the SHOW ENTRY or the SHOW QUEUE command.

You must use the /ENTRY qualifier when you enter the STOP/QUEUE/REQUEUE command for a batch queue. Entry numbers specified must match entry numbers of executing jobs.

/HOLD

Places the aborted job or jobs in a hold state for later release with the SET ENTRY/RELEASE or SET ENTRY/NOHOLD command.

/PRIORITY=n

Requires OPER (operator) or ALTPRI (alter privilege) privilege to raise the priority value above the value of the system parameter MAXQUEPRI.

Changes the priority of the requeued job or jobs. The parameter n can be from 0 to 255; the default value of the n parameter is the same as the priority value that the job or jobs had when they were stopped.

Generally, the /PRIORITY qualifier is used to lower the priority of a job or jobs, which ensures that the job or jobs runs when the queue contains no other jobs. No privilege is needed to set the priority lower than the MAXQUEPRI value.

/REQUEUE=[queue-name]

Specifies a queue where current jobs are to be requeued. If you do not specify the queue-name parameter, the jobs are requeued in the current queue.

Examples

$ STOP/QUEUE/REQUEUE=LPB0 LPA0
      

In this example, the current print job on queue LPA0 is stopped and requeued to queue LPB0. If the print symbiont sent checkpoint information about the print job to the job controller, printing resumes on LPB0 at the last checkpoint recorded.

$ STOP/QUEUE/REQUEUE/HOLD LPA0
   .
   .
   .
$ SET ENTRY 254/RELEASE
      

In this example, the current print job on LPA0 is suspended and placed in the hold state. Later, when you enter the SET ENTRY command with the /RELEASE qualifier, the job is released from the hold state and is rescheduled to print on queue LPA0. If the print symbiont sent checkpoint information about the print job to the job controller, printing resumes at the last checkpoint.

$ STOP/QUEUE/REQUEUE/ENTRY=758 SYS$BATCH
      

In this example, batch job number 758 is stopped and requeued for later processing on SYS$BATCH. If the batch job has been programmed with appropriate SET RESTART_VALUE commands, those portions of the job that have completed successfully are not rerun.

Abruptly stops the queue and returns control to the system. Any jobs that cannot be restarted are aborted immediately.

The /QUEUE qualifier is optional, but you must specify the /RESET qualifier.

Requires manage (M) access to the queue.

Format

STOP/QUEUE/RESET queue-name[:]

Parameter

queue-name[:]

Specifies the name of the queue you want to reset.

Description

The STOP/QUEUE/RESET command stops the queue as soon as the system receives the command. The queue manager requests termination for all executing jobs, but aborts or requeues executing jobs without waiting for termination status to be received. Current jobs that can be restarted are requeued for processing. Current jobs that cannot be restarted are aborted and must be resubmitted for processing. (Print jobs are restartable by default. Batch jobs are restartable if submitted with the SUBMIT/RESTART command.) Use the START/QUEUE command to restart the queue.

For autostart queues, the STOP/QUEUE/RESET command stops the queue and makes it inactive for autostart, so it will not be automatically started. For this reason, you might use this command to prevent an autostart queue from being automatically restarted when a printing device fails and needs to be serviced. Use the START/QUEUE command to reactivate the queue for autostart.

Examples

$ INITIALIZE/QUEUE/AUTOSTART_ON=MYNODE::LPAO/START LPA0
$ENABLE AUTOSTART/QUEUES/ON_NODE=MYNODE
   .
   .
   .
$STOP/QUEUE/RESET LPA0
$START/QUEUE LPA0
      

THE INITIALIZE/QUEUE command in this example creates an autostart output queue named LPA0. The /START qualifier activates the queue for autostart, and the ENABLE AUTOSTART/QUEUES command causes the queue to begin executing.

Suppose the printer LPA0:: runs out of paper. The STOP/QUEUE/RESET command abruptly stops the queue LPA0. The current print job stops immediately and is requeued. The STOP/QUEUE/RESET command also makes the queue inactive for autostart, so it will not be restarted while the printer's paper is being resupplied.

After the printer is loaded with paper, the START/QUEUE command makes the queue active for autostart and allows the queue manager to automatically start it again.

$ STOP/QUEUE/RESET TEXBATCH
      

The STOP/QUEUE/RESET command in this example stops the batch queue TEXBATCH. Any current jobs that were submitted with the /RESTART qualifier are requeued for processing when the queue is restarted. Users might want to resubmit current jobs that were not originally submitted with the /RESTART qualifier.

Stops all queues on the specified node. This command is useful if you want to stop a set of queues on a node with a single command (for example, before shutting down a node), but do not want to stop a queue manager throughout an OpenVMS Cluster.

The /QUEUES qualifier is optional, but the /ON_NODE qualifier is required.

Requires OPER (operator) privilege.

Format

STOP/QUEUES/ON_NODE[=node]

Parameters

None.

Description

The STOP/QUEUES/ON_NODE command notifies the queue manager to perform the following tasks:

• Abort all current jobs that cannot be restarted (in all of that queue manager's execution queues on the appropriate node), and requeue all current restartable jobs.
• Stop all of that queue manager's execution queues on the appropriate node. Force any of that queue manager's autostart queues on the node to fail over to the next available node in the queue's failover list (if any) on which autostart is enabled.
• Prevent any of that queue manager's autostart queues from failing over to the node.

By default, this command affects the node from which it is entered. Specify a nodename with the /ON_NODE qualifier to stop queues on a different node.

By default, the command affects autostart queues managed by the default queue manager, SYS$QUEUE_MANAGER. Specify the /NAME_OF_MANAGER qualifier to disable autostart of a different queue manager's autostart queues (on the node).

The STOP/QUEUES/ON_NODE command affects all autostart and nonautostart execution queues on the appropriate node that are managed by the queue manager. Autostart queues stopped as a result of this command remain active for autostart and will be restarted when the ENABLE AUTOSTART command is entered for the affected node or a node to which the queue can fail over. Nonautostart queues stopped as a result of this command must each be started with a START/QUEUE command specifying the queue name.

If you are using autostart queues, you might want to enter the DISABLE AUTOSTART/QUEUES command. For more information on the relationship between DISABLE AUTOSTART/QUEUES and STOP/QUEUES/ON_NODE, refer to the section on stopping queues before shutting down a system in the chapter about queues in the OpenVMS System Manager's Manual.

The STOP/QUEUES/ON_NODE command is included in the shutdown command procedure SYS$SYSTEM:SHUTDOWN.COM. If you shut down a node without using SHUTDOWN.COM, you might want to enter the STOP/QUEUES/ON_NODE command first. For more information on stopping queues before shutting down a node, refer to the chapter about queues in the OpenVMS System Manager's Manual.

Qualifier

/NAME_OF_MANAGER=name

Specifies the name of the queue manager controlling the queues you want to stop.

If the /NAME_OF_MANAGER qualifier is omitted, then the default queue manager name SYS$QUEUE_MANAGER is used. For more information on multiple queue managers, refer to the chapter about the queue manager in the OpenVMS System Manager's Manual.

Examples

$ STOP/QUEUES/ON_NODE
      

The STOP/QUEUES/ON_NODE command in this example stops all queues on the node from which it is entered. The autostart feature is disabled on this node for all autostart queues.

However, the queue manager process continues to run and schedules jobs as requested for execution on its unstopped queues on other nodes in the OpenVMS Cluster.

This command only affects queues managed by the default queue manager SYS$QUEUE_MANAGER because the /NAME_OF_MANAGER qualifier is not specified.

$INITIALIZE/QUEUE-
_$/AUTOSTART_ON=(JADE::,RUBY::,OPAL::)/BATCH/START BATCH_1
$ENABLE AUTOSTART/QUEUES/ON_NODE=JADE
$ENABLE AUTOSTART/QUEUES/ON_NODE=RUBY
   .
   .
   .
$ STOP/QUEUES/ON_NODE=JADE 
$ SHOW QUEUE BATCH_1
Batch queue BATCH_1, idle, on RUBY:: 
 
      

The INITIALIZE/QUEUE command in this example creates the autostart queue BATCH_1 capable of running on node JADE, RUBY, or OPAL. The /START qualifier activates the queue for autostart. The first ENABLE AUTOSTART/QUEUES command enables autostart of all autostart queues on node JADE, causing the queue BATCH_1 to begin processing on that node. The second ENABLE AUTOSTART/QUEUES command enables autostart for all autostart queues on node RUBY.

Later, suppose node JADE needs to be removed from the cluster. The STOP/QUEUES/ON_NODE command in the example stops all queues on node JADE without stopping the clusterwide queue manager, and causes the autostart queue BATCH_1 to failover to node RUBY, the next available node in its failover list. Because the STOP QUEUES/ON_NODE command disables autostart, the ENABLE AUTOSTART/QUEUES command must be executed on node JADE when it reboots for autostart queues to run on that node in the future.

This command only affects queues managed by the default queue manager SYS$QUEUE_MANAGER because the /NAME_OF_MANAGER qualifier is not specified.

Removes a zone from a running VAXft system. For more information on the STOP/ZONE command, see VAXft systems documentation.

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

Format

STOP/ZONE zone-id

Queues one or more files containing command procedures to a batch queue.

Requires submit (S) access to the queue.

Format

SUBMIT filespec[,...]

Parameter

filespec[,...]

Specifies one or more files containing command procedures. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the directory specification, file name, file type, and version number fields. The default file type is that of the preceding file. If no previous file specification contains an explicit file type, the default file type is COM.

If you specify more than one file, separate the file specifications with either commas (,) or plus signs (+).

If you specify a node name, you must use the /REMOTE qualifier.

Description

The SUBMIT command places the specified files in a batch queue for subsequent execution. By default, this queue is SYS$BATCH. All files queued by a single SUBMIT command are processed serially as one job. By default, the name of the batch job is the name of the first file specified in the SUBMIT command.

The system assigns a unique entry number to each batch job in the queue. When you enter the SUBMIT command, by default, the system displays the job name, the queue name, the entry number, and the job status.

The system automatically creates or updates the local symbol $ENTRY when a SUBMIT command completes successfully. The value of $ENTRY is a string that identifies the entry number of the most recently queued job. If you want to refer to a job's entry number later, store the value of $ENTRY in another symbol.

After you queue a batch job, the version of the file submitted is processed, even if a newer version of the file is created before the batch job runs. Also, another file with the same name and version number as the file queued cannot be substituted for the file that was submitted.

When the system executes a command procedure submitted to a batch queue, it creates a detached process to execute the commands. This process receives the owner's disk and directory defaults and the same resource quotas and privileges that were given to the owner's interactive process when you logged in.

If multiple procedures are submitted, the job terminates as soon as any procedure exits with an error or severe (fatal) error status.

In an OpenVMS Cluster environment, you should periodically keep the cluster in time synchronization using the SET TIME/CLUSTER command because the differences in system times between nodes in an OpenVMS Cluster may vary. This variance may cause a job to begin executing a little before or after the specified time because the redundancy built into the batch and print system allows more than one job controller in the cluster to receive a timer asynchronous system trap (AST) for the job and, thus, to schedule it for execution.

Batch Job Output

By default, all output from each command procedure in a batch job is written to a log file. This log file is queued for printing on SYS$PRINT when the batch job finishes. By default, this log file is deleted after it is printed. When you stop a batch job by using the STOP/QUEUE/ENTRY, the STOP/IDENTIFICATION, or the DELETE/ENTRY command, the log file is not queued for printing.

For information on how to change the system's handling of the log file, see the descriptions of the /LOG_FILE, /PRINTER, and /KEEP qualifiers.

Qualifiers

/AFTER=time

/NOAFTER

Requests that the job be held until after a specific time. If the specified time has passed already, the job is processed immediately.

You can specify time as either absolute time or as a combination of absolute and delta times. For complete information on specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

In an OpenVMS Cluster, a batch job submitted to execute at a specific time may begin execution a little before or after the requested time. This occurs when the clocks of the member systems in the OpenVMS Cluster are not synchronized. For example, a job submitted using the DCL command SUBMIT/AFTER=TOMORROW may execute at 11:58 P.M. relative to the host system's clock.

This problem can occur in a cluster even if a job is run on the same machine from which it was submitted, because the redundancy built into the batch/print system allows more than one job controller in the cluster to receive a timer asynchronous system trap (AST) for the job and, thus, to schedule it for execution. Moreover, this behavior is exacerbated if the batch job immediately resubmits itself to run the next day using the same SUBMIT command. This can result in having multiple instances of the job executing simultaneously because TOMORROW (after midnight) might be only a minute or two in the future.

A solution to this problem is to place the SUBMIT command in a command procedure that begins with a WAIT command, where the delta-time specified in the WAIT command is greater than the maximum difference in time between any two systems in the cluster. Use the SHOW TIME command on each system to determine this difference in time. Use the SYSMAN command CONFIGURATION SET TIME to synchronize clocks on the cluster. For complete information on the SYSMAN command CONFIGURATION SET TIME, refer to the OpenVMS System Management Utilities Reference Manual.

/BACKUP

/NOBACKUP

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /BACKUP qualifier selects files according to the dates of their most recent backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/BEFORE[=time]

/NOBEFORE

Selects only those files dated prior to the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

For complete information on specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

/BY_OWNER[=uic]

/NOBY_OWNER

Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.

Specify the UIC by using standard UIC format as described in the OpenVMS User's Manual.

/CHARACTERISTICS=(characteristic[,...])

Specifies the name or numbers of one or more characteristics to be associated with the job. Characteristics can refer to such things as color of ink. If you specify only one characteristic, you can omit the parentheses.

A characteristic's number must range from 0 to 127. To see which characteristics have been defined for your system, use the SHOW QUEUE/CHARACTERISTICS command. To see which characteristics are associated with a particular queue, use the SHOW QUEUE/FULL command.

A job can be executed on a queue only if none, some, or all of the characteristics associated with the queue also are associated with the job. That is, the job's characteristics must be a subset of the queue's characteristics. However, if any of the characteristics associated with the job are not associated with the queue, the job remains pending until one or more of the following occurs:

• The characteristics specified with the queue are changed to make the job's characteristics a subset of the queue's characteristics (using, for example, the SET QUEUE/CHARACTERISTICS command).
• The characteristics specified with the job are changed to make the job's characteristics a subset of the queue's characteristics (using, for example, the SET ENTRY/CHARACTERISTICS command).
• The job is moved to a queue on which all the job's characteristics have been specified (using, for example, the SET ENTRY/REQUEUE command).
• The job is deleted (using, for example, the DELETE/ENTRY command).

/CLI=filename

Specifies the command language interpreter (CLI) to be used to process the job. The file specification assumes the device name SYS$SYSTEM: and the file type EXE (SYS$SYSTEM:filename.EXE). The default CLI is that defined in the user authorization file (UAF).

/CONFIRM

/NOCONFIRM (default)

Controls whether a request is issued before each submit operation to confirm that the operation should be performed on that file. The following responses are valid:

YES	NO	QUIT
TRUE	FALSE	Ctrl/Z
1	0	ALL
	[Return]

You can use any combination of uppercase and lowercase letters for word responses. You can abbreviate word responses to one or more letters (for example, T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, and pressing the Return key. Entering QUIT or pressing Ctrl/Z indicates that you want to stop processing the command at that point. When you respond by entering ALL, the command continues to process, but no further prompts are given. If you type a response other than one of those in the list, DCL issues an error message and redisplays the prompt.

/CPUTIME=time

Defines a CPU time limit for the batch job. You can specify time as delta time, 0, INFINITE, or NONE. If the queue on which the job executes has a defined CPUMAXIMUM value, the smaller of the SUBMIT command and queue values is used. If the queue on which the job executes does not have a specified maximum CPU time limit, the smaller of the SUBMIT command and user authorization file (UAF) values is used. If the queue on which the job executes does not have a specified maximum CPU time limit and the UAF has a specified CPU time limit of NONE, either the value 0 or the keyword INFINITE allows unlimited CPU time. If you specify the keyword NONE, the specified queue or UAF value is used. CPU time values must be greater than or equal to the number specified by the system parameter PQL_MCPULM. For more information on specifying CPU time limits, see the CPU Time Limit Specifications and Actions table for the INITIALIZE/QUEUE command.

/CREATED (default)

/NOCREATED

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /CREATED qualifier selects files based on their dates of creation. This qualifier is incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/DELETE

/NODELETE (default)

Positional qualifier.

Controls whether files are deleted after processing. If you specify the /DELETE qualifier after the SUBMIT command name, all files in the job are deleted after processing. If you specify the /DELETE qualifier after a file specification, only that file is deleted after it is processed.

For the /DELETE qualifier to work, the protection code on the input files must allow delete (D) access to the user identification code (UIC) of the user submitting the job. If delete (D) access is not allowed, or if any file in the command parameter list cannot be opened as input, command processing stops and no batch job is created.

/EXCLUDE=(filespec[,...])

/NOEXCLUDE

Excludes the specified files from the submit operation. You can include a directory but not a device in the file specification. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the file specification. If you specify only one file, you can omit the parentheses.

/EXPIRED

/NOEXPIRED

Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /EXPIRED qualifier selects files according to their expiration dates. (The expiration date is set with the SET FILE/EXPIRATION_DATE command.) The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/HOLD

/NOHOLD (default)

Controls whether the job is made available for immediate processing. The /HOLD qualifier holds the job until it is released by the SET ENTRY/RELEASE or the SET ENTRY/NOHOLD command.

/IDENTIFY (default)

/NOIDENTIFY

Displays the job name, the queue name, the entry number, and the status of the job when it is queued.

/KEEP

/NOKEEP

Controls whether the log file is deleted after it is printed; the /NOKEEP qualifier is the default unless the /NOPRINTER qualifier is specified.

/LOG_FILE[=filespec]

/NOLOG_FILE

Names the log file. The asterisk (*) and the percent sign (%) wildcard characters are not allowed in the file specification.

---

Previous

Next

Contents

Index

	privacy and legal statement
9996PRO_076.HTML