Document revision date: 19 July 1999

$ SHOW QUEUE/FULL/ALL/BY_JOB_STATUS=EXECUTING Batch queue HERA_BATCH, available, on HERA:: /AUTOSTART_ON=(HERA::) /BASE_PRIORITY=3 /JOB_LIMIT=25 /OWNER=[SYSTEM] /PROTECTION=(S:M,O:D,G:R,W:R) Entry Jobname Username Status ----- ------- -------- ------ 700 VUE SMITH Executing Submitted 25-FEB-1998 14:46 /KEEP /NOLOG /NOPRINT /PRIORITY=100 File: _$333$DISK1:[SMITH.COM]VUE.COM;19 (executing) Batch queue ZZ_BATCH, available, on ZZ:: /AUTOSTART_ON=(ZZ::) /BASE_PRIORITY=3 /JOB_LIMIT=25 /OWNER=[SYSTEM] /PROTECTION=(S:M,O:D,G:R,W:R) Entry Jobname Username Status ----- ------- -------- ------ 874 PIPE FITZGERALD Executing Submitted 26-FEB-1998 11:25 /KEEP /NOTIFY /NOPRINT /PRIORITY=100 /RESTART=CLUSTER_BATCH /RETAIN=UNTIL="0 01:00" File: _$333$DISK1:[FITZGERALD]PIPE.COM;2 (executing) Server queue NM$QUE01, available, on HERA::, mounted form DEFAULT /BASE_PRIORITY=4 /DEFAULT=(FEED,FORM=DEFAULT) /OWNER=[DOC,SMITH] /PROCESSOR=NM$DAEMON /PROTECTION=(S:M,O:D,G:R,W:R) /RETAIN=ERROR Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 236 NM ROSENBERG 12 Processing Submitted 23-FEB-1998 08:42 /FORM=DEFAULT /PRIORITY=100 File: _$5$DISK3:[FOLK$.NM]NM$J1991072308340647.WRK;1

13.7.1.2 Modifying a Queue

You can use the INITIALIZE/QUEUE, START/QUEUE, and SET QUEUE commands to change queue options; as you change queue options, information about the queue in the queue database is updated. You can use the INITIALIZE and START commands only on stopped queues.

The SET QUEUE command lets you change many queue options without having to stop the queue, initialize it, and restart it. For example, the following command modifies the running batch queue, SYS$BATCH:

$ SET QUEUE/JOB_LIMIT=4/DISABLE_SWAPPING SYS$BATCH

The command in this example changes the job limit for the queue and disables swapping for all jobs processed in SYS$BATCH. All other options of the queue remain the same. The changed options do not affect the execution of current jobs; however, all subsequent jobs are executed with the new options in effect.

How to Perform This Task

To change queue options that cannot be altered with SET QUEUE, use the following procedure:

1. Stop the queue with STOP/QUEUE/NEXT.
2. Restart the queue with START/QUEUE or INITIALIZE/QUEUE/START, specifying the appropriate qualifiers for your options.
   Any qualifiers that you do not specify remain as they were when the queue was previously initialized, started, or set.

Note that initializing an existing queue does not delete any current jobs in that queue. Any new queue settings established by the new INITIALIZE/QUEUE command affect all jobs waiting in the queue or subsequently entering the queue.

See Table 13-1 for a list of the options that you can use for batch and output queues.

13.7.1.3 Pausing a Queue

The STOP/QUEUE command, when used without qualifiers, temporarily suspends the execution of all current jobs in the queue and places the queue in a paused state. Pausing an output queue lets you enter print job positioning and alignment commands to the print symbiont. (See Section 13.7.2.7 for more information about using STOP/QUEUE to control print jobs.)

To resume the execution of a paused queue, enter START/QUEUE.

13.7.1.4 Closing a Queue

When a queue is not available for an extended period of time (for example, when a printer needs servicing), you can prevent new jobs from entering the queue by specifying the /CLOSE qualifier with SET QUEUE, INITIALIZE/QUEUE, or START/QUEUE. The /CLOSE qualifier prevents users from entering jobs in the queue with PRINT or SUBMIT commands. When a user attempts to print or submit a job to a closed queue, the job is rejected, and the user is notified that the queue is closed. For example:

$ PRINT/QUE=$PRINTER_1 REPORT.TXT; %PRINT-F-CREJOB, error creating job -JBC-E-QUE_CLOSED, queue closed, jobs not accepted

Jobs currently in the queue are not affected.

When the queue is available again, use the /OPEN qualifier to open the queue for incoming jobs.

13.7.1.5 Stopping a Queue

To stop a queue, enter one of the following commands:

Command	Description
STOP/QUEUE/NEXT	Lets all currently executing jobs complete and then stops the queue. Once you enter this command, all new jobs are prevented from executing.
STOP/QUEUE/RESET	Abruptly stops the queue and returns control to the system. Any jobs that are currently executing are stopped immediately. If the queue is not set to retain jobs completed with an error status, use SET QUEUE/RETAIN=ERROR to do so before stopping the queue with STOP/QUEUE/RESET. This causes the queue to retain information about aborted jobs. For print jobs retained on error, use SET ENTRY/RELEASE/NOCHECKPOINT to restart the interrupted jobs from the beginning. Print jobs are restartable by default; batch jobs are not restartable unless submitted with the /RESTART qualifier.

For autostart queues, these commands deactivate a queue for autostart as explained in Section 13.7.1.6. To restart a stopped nonautostart queue or to reactivate a deactivated autostart queue, enter START/QUEUE.

13.7.1.6 Preventing Autostart Queues from Starting

The STOP/QUEUE/NEXT or STOP/QUEUE/RESET command stops an autostart queue and marks it inactive for autostart until you enter START/QUEUE. This feature prevents an autostart output queue from accidentally restarting when a printer is being serviced.

13.7.1.7 Disabling Autostart on a Node

The DISABLE AUTOSTART/QUEUES command notifies the queue manager to perform the following tasks on the affected node:

• Prevent autostart queues from failing over to the node.
• Mark all autostart queues on the node as "stop pending" in preparation for a planned shutdown. This lets jobs currently executing on the queues complete.
• Upon completion of any jobs currently executing on one of the node's autostart queues, force the queue to fail over to the next available node in the queue's failover list on which autostart is enabled. (An autostart queue can only fail over if you have set it up to run on more than one node.)

By default, DISABLE AUTOSTART/QUEUES affects the node from which it is entered. Specify the /ON_NODE qualifier to disable autostart on a different node.

Use DISABLE AUTOSTART/QUEUES prior to shutting down a node. For more information, see Section 13.7.1.9.

13.7.1.8 Stopping All Queues on a Node

To stop all queues on a node without stopping the queue manager, enter STOP/QUEUES/ON_NODE. By default, this command affects the node on which the command is entered. To stop queues on a different node, specify the name of the node on which queues are to be stopped as follows:

STOP/QUEUES/ON_NODE=node

When you enter STOP/QUEUES/ON_NODE, nonautostart queues and autostart queues without a failover list are stopped. Autostart queues created or started with a failover list fail over to the next available node in that list that has autostart enabled. In all cases, currently executing jobs are aborted.

However, you can allow jobs executing on autostart queues to complete by entering the DISABLE AUTOSTART/QUEUES command and waiting for jobs to complete before entering the STOP/QUEUES/ON_NODE command. For more information, see Section 13.7.1.9.

13.7.1.9 Stopping Queues Before Shutting Down a System

The following commands are included in the shutdown command procedure SYS$SYSTEM:SHUTDOWN.COM and are automatically executed when you shut down a node using SHUTDOWN.COM:

• DISABLE AUTOSTART/QUEUES
• STOP/QUEUES/ON_NODE

Allowing Jobs to Complete Before Stopping Autostart Queues

STOP/QUEUES/ON_NODE aborts jobs and stops all queues on a node; DISABLE AUTOSTART allows jobs on autostart queues to finish processing before failing over or stopping autostart queues. If your configuration uses autostart queues, you might want to allow jobs on those queues to complete before stopping your queues.

In SHUTDOWN.COM, STOP/QUEUES/ON_NODE is executed shortly before the node is shut down. When using SHUTDOWN.COM, you can ensure that jobs on autostart queues have time to complete before the queues are stopped by specifying the time interval between DISABLE AUTOSTART/QUEUES and the shutdown.

Use one of the following methods:

Timing	Method
Before executing SHUTDOWN.COM	Define the logical name SHUTDOWN$DISABLE_AUTOSTART to be the number of minutes in the following format: DEFINE/SYSTEM/EXECUTIVE_MODE SHUTDOWN$DISABLE_AUTOSTART number-of-minutes
While executing SHUTDOWN.COM	Specify the number of minutes as a shutdown option as follows: Shutdown options [NONE]:DISABLE_AUTOSTART=number-of-minutes

Determine an appropriate number of minutes for your configuration, based on the number and type of jobs in the autostart queues.

If you shut down a node without using SHUTDOWN.COM, you might want to enter DISABLE AUTOSTART/QUEUES and wait a few minutes to allow jobs on autostart queues to finish processing before you enter STOP/QUEUES/ON_NODE.

13.7.1.10 Assigning a Logical Queue

When a problem occurs with a print device, you can reroute the queue associated with that device to another queue associated with a functioning device. You do this by creating a logical queue. Use the following procedure to create a logical queue that redirects its jobs to another queue:

1. Stop the queue associated with the malfunctioning print device by entering a command in the following format:

   STOP/QUEUE/NEXT queue-name[:]

   
   This command inhibits new jobs from processing but lets the current job finish processing, unless the print device is not operating at all. If the device is inoperable, use STOP/QUEUE/RESET to halt the queue and immediately cancel all output from the device.

2. Take the device off line.
3. Reroute existing jobs from the malfunctioning print device to another print device by entering a command in the following format:

   ASSIGN/QUEUE queue-name[:] logical-queue-name[:]

   
   Ensure that the options of the new print device are appropriate for processing the new jobs.

How to Deassign a Logical Queue

To deassign the logical queue, enter a command in the following format:

DEASSIGN/QUEUE logical-queue-name[:]

13.7.1.11 Moving All Jobs from One Queue to Another

Before you delete a queue, you might want to requeue all jobs in the queue to another queue. To do so, enter a command in the following format:

ASSIGN/MERGE target-queue source-queue

where target-queue is the queue to which you are moving the jobs; source-queue is the queue to be deleted.

The ASSIGN/MERGE command moves all jobs currently in the source queue. If new jobs are entered into the source queue before it is deleted, those new jobs remain in the source queue, and are not transferred to the target queue. You might want to close the queue to prevent new jobs from being entered in the queue, as explained in Section 13.7.1.4, before entering ASSIGN/MERGE.

For ongoing redirection of jobs, use the ASSIGN/QUEUE command as explained in Section 13.7.1.10.

13.7.1.12 Deleting a Queue

Perform the following steps to delete a queue:

1. Stop the queue by entering STOP/QUEUE/NEXT. (Use STOP/QUEUE/RESET to abort all executing jobs.)
2. Wait for executing jobs to complete.
3. Requeue the entries still pending in the queue. If you do not perform this step, jobs will be deleted along with the queue.
4. Remove all references to the queue from generic queues or jobs. See Section 13.8.5 for more information about removing references to queues.
5. Delete the queue by entering DELETE/QUEUE.

Some routine tasks for controlling the flow of batch and print jobs and for maintaining efficient job processing performance include the following actions:

Task	Reference
Monitoring jobs	Section 13.7.2.1
Modifying job processing options	Section 13.7.2.2
Holding and releasing a job	Section 13.7.2.3
Requeuing an executing job	Section 13.7.2.4
Requeuing a pending job	Section 13.7.2.5
Deleting a job	Section 13.7.2.6
Pausing an output queue to control print job position and alignment	Section 13.7.2.7

13.7.2.1 Monitoring Jobs

Use the SHOW ENTRY command to monitor the status of batch and print jobs. (For information about job status, see Table 13-6.)

Use the following format to specify the SHOW ENTRY command:

SHOW ENTRY [entry-number[,...]], [job-name[,...]]

If you do not specify an entry number or job name, the system displays all jobs owned by you or by the user specified with the /USER_NAME qualifier. If you specify a job name, the system displays all jobs owned by you or by the user specified with /USER_NAME that match the specified character string. You can also display a group of jobs by entering a list of entry numbers or job names, or both, on the command line.

Specify qualifiers with the SHOW ENTRY command to specify the type of job information you want to display. For more information, refer to the OpenVMS DCL Dictionary.

Table 13-6 describes the job statuses returned by the SHOW ENTRY command.

Table 13-6 Job Statuses Returned by SHOW ENTRY

Status	Description
Aborting	Executing job is halting prior to normal completion and will not continue processing.
Executing	Job is executing from a batch queue.
Holding	Job is being held in the queue indefinitely. For more information, see Section 13.7.2.3.
Pending	Job is waiting its turn to execute. For more information, see Section 13.8.2.
Printing	Job is executing from a printer or terminal queue.
Processing	Job is executing from a server queue.
Retained	Job remains in the queue upon completion. For more information, see Section 13.6.2.3.
Stalled or Suspended	Job stopped during processing but should continue when the cause is resolved.
Starting	Job is beginning to be processed.
Timed_release	Job is being held in the queue for execution at a specified time.

Examples

1. The following command displays jobs owned by user GARDNER:

   $ SHOW ENTRY/USER_NAME=GARDNER Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 4 TEST GARDNER Holding On available batch queue OPAL_BATCH 611 SET GARDNER 140 Pending On stopped printer queue LQPRINT

2. In the following example, the /FULL qualifier displays job status information, the time the job was submitted, the file specification, and the job processing options:

   $ SHOW ENTRY/FULL 4,611 Entry Jobname Username Blocks Status ----- ------- -------- ------ ------ 4 TEST GARDNER Holding On available batch queue OPAL_BATCH Submitted 15-JAN-1998 16:12 /LOG=_$5$DUA1:[GARDNER]TEST.LOG; /PRIORITY=100 File: _$5$DUA1:[GARDNER]TEST.COM;8 611 SET GARDNER 140 Pending (queue stopped) On stopped printer queue LQPRINT Submitted 21-JAN-1998 16:23 /FORM=DEFAULT /PRIORITY=200 File: _$5$DUA1:[GARDNER]SET.TXT;5 File: _$5$DUA1:[GARDNER]WAIT.TXT;1

You can modify many job processing options by specifying qualifiers with a command in the following format:

SET ENTRY/qualifier[,...] entry-number

Table 13-7 lists some qualifiers that are frequently used to change jobs. For a list of all the job processing options you can change with the SET ENTRY command, refer to the OpenVMS DCL Dictionary.

Table 13-7 SET ENTRY Qualifiers for Changing Jobs

Qualifier	Description	For More Information
/[NO]AFTER= time	Controls whether a job is held until after a specified time.	Section 13.7.2.3
/CHARACTERISTICS =( characteristic[,...])	Specifies the name or number of one or more characteristics associated with a batch or print job.	Section 13.6.3
/FORM= form	Specifies the name or number of the form to be associated with a print job.	Section 13.6.7
/[NO]HOLD	Controls whether a job is available for immediate processing or held until it is released for processing.	Section 13.7.2.3
/PRIORITY= n	Specifies the scheduling priority of the job.	Section 13.6.5.2
/RELEASE	Releases a previously held job.	Section 13.7.2.3
/REQUEUE= queue-name[:]	Requests that the job be moved from the original queue to the specified queue; you can also do this by using the STOP/QUEUE/REQUEUE/ENTRY command.	Section 13.7.2.5
/RESTART	Specifies whether a batch or print job is restarted after a system failure or a STOP/QUEUE/REQUEUE command. Print jobs are restartable by default. Batch jobs are restartable only if submitted or modified with the /RESTART qualifier.

	privacy and legal statement
6017PRO_062.HTML