Working with Queues

Queues are lists of jobs OpenVMS will perform on behalf of users. For example, when you issue a PRINT or SUBMIT command, a queue entry is created representing the request. The following paragraphs show you how to create, examine, and modify queue entries.

Printing a File

Use the PRINT command to submit a file for printing:

    $ PRINT file1[,file2,file3...] 

The PRINT command will submit a print job to the printer queue identified by the name SYS$PRINT (which may be a logical name or the name of an actual queue). Your system manager can tell you whether this queue is appropriate for you. If it is not, you may use the /QUEUE qualifier to override it or create a logical name SYS$PRINT to represent the correct printer. For example, if your normal printer is called LASER4, you could issue this command:

    $ PRINT /QUEUE=LASER4 file 

Or you could place the following line in your LOGIN.COM:

    $ DEFINE SYS$PRINT LASER4 

Once the logical name SYS$PRINT exists, your print jobs will automatically be assigned to the queue indicated by the logical name.

Qualifiers for the PRINT command you may find useful include the following:

/AFTER="time"—holds the print job until a specified time. Times may be specified in absolute format, such as /AFTER="04-JAN-2003 15:00." If you omit the day, the present day is assumed. Times may also be relative, such as /AFTER="00:00:00" (five days from now) or "TOMORROW10:00" (three days and ten hours from midnight tonight). Time formats are described later in this chapter.

/HOLD—holds the print job until it is explicitly released (queue entries are maintained across system reboots.)

/BURST=ALL, /BURST=ONE, /NOBURST, /FLAG=ALL, /FLAG=ONE, /NOFLAG—control whether separator pages will precede each file in the print job (ALL), only the first file (ONE), or not at all (/NOBURST, /NOFLAG). Separators are helpful with busy printers by allowing users to identify quickly where one job ends and the next begins. /BURST prints two separator pages, and /FLAG prints one. Another qualifier, /TRAILER, places a similar page at the end of a job.

/COPIES=number—controls the number of copies of a job (when placed after PRINT) or a file within a job (when placed after a file specification) to be printed. If omitted, one copy will be assumed.

/JOB_COUNT=number—specifies how many copies of the entire job will be printed. This is useful if different files within the job have different values for /COPIES.

/DELETE—causes the file(s) to be deleted after printing. Use with caution; a paper jam or other printer malfunction could cause the loss of some portion of the file.

/FORM=form-name—controls the type of paper stock on which the job will be printed. Forms vary from site to site; use SHOW QUEUE/FORM on your system to see what forms are available.

/CHARACTERISTICS—controls the site-defined characteristics a printer queue must possess to process this job. Characteristics may represent any arbitrary printer attributes as defined by the system manager. Use SHOW QUEUE /CHARACTERISTICS to see what characteristics, if any, are available at your site.

/NOTIFY—causes a message to be sent to your terminal when the job completes.

/PRIORITY=n—allows you to set the priority of the queue entry. Priorities are in the range of 0 (the lowest) through 255. On most systems, the default queue priority for most users is 100. Jobs with higher priorities are executed first. You must hold the ALTPRI or OPER privilege to raise the priority above your default priority.

Other qualifiers are available; use HELP PRINT for descriptions.

Submitting a Batch Job

A batch job is a command procedure (see Chapter 9, "Command Procedures") that you submit to the system to execute on your behalf. Since batch jobs and print jobs use the same OpenVMS queuing mechanism, submitting a batch job is quite similar to queuing a print job, as covered previously.

You use the SUBMIT command to submit a batch job for execution:

    $ SUBMIT CLEANUP 

This command submits the command procedure CLEANUP.COM to the batch queue SYS$BATCH for execution as soon as an execution queue is available.

Batch queues have adjustable limits to the number of jobs that may execute at once. Your job may have to wait until previous jobs complete. Once your job starts, a BATCH mode process is created on your behalf, which executes your command procedure. By default, a log file is created in your SYS$LOGIN directory, logging the activities of the command procedure. In this example, the log file CLEANUP.LOG would be created.

Useful qualifiers include the following:

/AFTER and /HOLD—work exactly as they do for the PRINT command, see above.

/QUEUE=queue-name—directs your batch job to a particular queue instead of SYS$BATCH.

/LOG=filename—controls the name of the batch log file. Use /NOLOG to disable the logfile altogether. Use SET [NO]VERIFY within your command procedure to control the verbosity of the logfile contents, as discussed below.

/PARAMETERS=("P1","P2",..."P8")—supplies parameters to batch jobs. Command procedures executed interactively accept parameters from the command line; the /PARAMETERS qualifier provides the same functionality for batch jobs.

/PRIORITY=n—allows you to set the priority of the queue entry. Priorities are in the range of 0 (the lowest) through 255. On most systems, the default queue priority for most users is 100. Jobs with higher priorities are executed first. You must hold the ALTPRI or OPER privilege to raise the priority above your default priority. This priority refers to the priority of the batch queue entry, not the scheduling priority of the resulting batch process.

Batch Mode Caveats

[NO]VERIFY in Batch Jobs

Depending on the contents of SYLOGIN.COM and your own LOGIN.COM, your batch jobs may have verification turned on by default. Verification causes each line of your command procedure to be recorded in the log file as it is executed. This can result in large log files with mostly uninteresting contents. Consider using the following command in your LOGIN.COM if you usually do not need to see this information:

    $ if f$mode() .eqs. "BATCH" then $ set noverify 

If placed in your LOGIN.COM, this will disable verification in all of your batch logs by default. You can always use SET VERIFY and SET NOVERIFY within a given procedure to enable or disable verification at will.

Modifying a Command Procedure Already Queued

If you make a change to a command procedure that is already queued for execution, your change will not be honored when the job runs. This is true even if you reset the version number of the file back to what it was when it was queued, because the file is queued by its unique file ID, not its name. Furthermore, if you make a change and then PURGE the original version, the job will fail altogether, resulting in a "file not found" message alone in the log file.

If you change a procedure, you must delete the old queue entry (shown further on in this chapter) and queue the file again. If your batch job resubmits itself to run again later, you may wait and let your change take effect on the second run, as the old version will submit the updated version.

Be Careful of Your Directories

When your batch job begins, its default directory will be SYS$LOGIN, your home directory. This is true no matter which directory contains the procedure, or what your default directory was when you queued the job.

You should take this into account when writing your procedures. You may use SET DEFAULT within your procedures (consider restoring the original directory at exit as shown below) or fully specify any files referenced within the procedure.

    $ !    $ ! How to use F$ENVIRONMENT() to preserve your original directory    $ ! when a command procedure must work in another directory.    $ ! This may also be useful if the procedure will be used in    $ ! interactive mode.    $ !    $ original_dir = f$environment("default")    $ set default working_directory      .      . (intervening work)      .    $ !    $ ! Restore our directory to what it was when the procedure started.    $ !    $ set default 'original_dir    $ exit 

Finding Batch Queues and Printers

To locate queues on your OpenVMS system, use the SHOW QUEUE command. Use /BATCH to narrow the search to batch queues or /DEVICE to limit it to printer queues.

    $ SHOW QUEUE/BATCH    Batch queue SYS$BATCH, idle, on PHOEBE::      Entry  Jobname         Username            Status      -----  -------         --------            ------        951  CHECK_EXPIRED   MIKE                Holding until 8-APR-2003 16:33:15        702  HOUSEKEEPING    MIKE                Holding until 9-APR-2003 00:00:00 

In the example above, there is only one batch queue on the system. If the system or cluster has more than one batch queue, they will all be listed. If you have any jobs currently in the queue(s), each will be shown after the queue in which it resides.

    $ SHOW QUEUE/DEVICE    Printer queue COLOR, available, on LTA157:, mounted form DEFAULT    Printer queue LASER, busy, on LTA244:, mounted form DEFAULT      Entry  Jobname         Username     Blocks  Status      -----  -------         --------     ------  ------        149  REPORT3         MIKE             49  Printing    Printer queue PRINTER1, available, on LTA300:, mounted form DEFAULT    Printer queue PRINTER2, available, on LTA301:, mounted form DEFAULT    Generic printer queue SYS$PRINT 

In the example above, there are four printer queues and one generic printer queue. Generic queues can route jobs to the next available printer queue matching the job's requirements. Printer LASER is currently printing the print job called REPORT3.

To see jobs submitted by all users, use the /ALL qualifier. If your account has suitable privileges, all jobs will be shown. Otherwise, you may be shown only the number of intervening jobs.

    $ SHOW QUEUE/BATCH/ALL    Batch queue SYS$BATCH, idle, on PHOEBE::      Entry  Jobname         Username            Status      -----  -------         --------            ------        951  CHECK_EXPIRED   MIKE                Holding until  8-APR-2003 16:33:15        697  CLIENT          TIMESERVER          Holding until  8-APR-2003 23:43:12        702  HOUSEKEEPING    MIKE                Holding until  9-APR-2003 00:00:00        710  FINDHI          MIKE                Holding until  9-APR-2003 00:21:55        426  REMINDER        LAWRENCE            Holding until  9-APR-2003 08:00:00 

To see complete information about queues and entries, use the /FULL qualifier.

    $ SHOW QUEUE/BATCH/FULL    Batch queue SYS$BATCH, idle, on PHOEBE::      /BASE_PRIORITY=0 /JOB_LIMIT=1 /OWNER=[SYSTEM] /PROTECTION=(S:M,O:D,G:R,W:S)        951  CHECK_EXPIRED   MIKE               Holding until 8-APR-2003 16:33:15             Submitted 8-APR-2003 14:33:15.59 /LOG=DKA100:[LOGS]CHECK_EXPIRED.LOG;             /PRIORITY=100             File: _PHOEBE$DKA100:[LOGS]CHECK_EXPIRED.COM;10 

To examine only a single queue, specify it as the parameter:

     $ SHOW QUEUE queue_name [/all] [/full] 

Examining a Queue Entry

A single entry (job) may be examined using the SHOW ENTRY command:

    $ SHOW ENTRY 951      Entry  Jobname        Username   Blocks  Status      -----  -------        --------   ------  ------        951  CHECK_EXPIRED  MIKE               Holding until  8-APR-2003 16:33:15             On idle batch queue SYS$BATCH 

You may add the /FULL qualifier to see more information:

    $ SHOW ENTRY 951 /FULL      Entry  Jobname         Username   Blocks  Status      -----  -------         --------   ------  ------        951  CHECK_EXPIRED   MIKE               Holding until  8-APR-2003 16:33:15        On idle batch queue SYS$BATCH        Submitted 8-APR-2003 14:33:15.59 /LOG=DKA100:[LOGS]CHECK_EXPIRED.LOG;        /PRIORITY=100        File: _PHOEBE$DKA100:[LOGS]CHECK_EXPIRED.COM;10 

Modifying a Queue Entry

You may use the SET ENTRY command to change the characteristics of a job already in a queue.

     $ SET ENTRY entry_number [/qualifiers] 

Common qualifiers include the following:

/AFTER="time"—changes the time at which the job should execute. Use "dd-mmm-yyyy hh:mm:ss.cc" format—for example, "23-MAY-2003 15:00" or "18:30". If you omit the day, the current day is assumed.

/HOLD—causes the job to be held indefinitely. Use /RELEASE to release a holding job for immediate execution.

     $ SHOW ENTRY 951       Entry  Jobname         Username   Blocks  Status       -----  -------         --------   ------  ------         951  CHECK_EXPIRED   MIKE               Holding until 8-APR-2003 16:33:15             On idle batch queue SYS$BATCH     $ SET ENTRY 951/HOLD     $ SHOW ENTRY 951       Entry  Jobname         Username   Blocks  Status       -----  -------         --------   ------  ------         951  CHECK_EXPIRED   MIKE               Holding              On idle batch queue SYS$BATCH 

Use HELP SET ENTRY for more information about modifying entries.

Deleting a Queue Entry

To delete an entry, whether or not the job has already started, use DELETE /ENTRY= entry-number:

    $ SHOW ENTRY 951      Entry  Jobname         Username   Blocks  Status      -----  -------         --------   ------  ------        951  CHECK_EXPIRED   MIKE Holding             On idle batch queue SYS$BATCH    $ DELETE/ENTRY=951    $ SHOW ENTRY 951    %JBC-E-NOSUCHENT, no such entry 

Queue Entry Numbers

Normally, OpenVMS queue entry numbers start at 1, increase by 1 until reaching 1,000, and then start over from 1. If more entry numbers are needed, OpenVMS will automatically use larger numbers. Some older versions of OpenVMS incremented entry numbers by values other than 1.

The special DCL symbol $ENTRY contains the number of the queue entry you created most recently. If you have not created a queue entry since logging in, the symbol will not exist. This feature is particularly helpful for command procedures that submit jobs and then need to examine or manipulate them or record their numbers. Some older versions of OpenVMS do not include the $ENTRY symbol.

    $ SUBMIT CLEANUP    Job CLEANUP (queue SYS$BATCH, entry 952) pending         pending status caused by queue busy state    $ SHOW SYMBOL $ENTRY      $ENTRY = "952"