Updated: 11 December 1998

OpenVMS DCL Dictionary

Changes the current status or attributes of a job not currently executing in a queue.

Requires delete (D) access to the job or manage (M) access to the queue.

Format

SET ENTRY entry-number[,...]

Parameter

entry-number[,...]

Specifies the entry number of the job you want to change. If you specify more than one entry, separate the entry numbers with commas (,).

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.

Description

The SET ENTRY command allows you to change the status or attributes of one or more jobs, as long as the jobs are not executing currently. You cannot affect individual files within a multifile job with the SET ENTRY command.

The qualifiers enable you to specify different attributes or delete attributes. Some qualifiers apply to both batch and print jobs. Others are restricted to either batch jobs or print jobs. The defaults for all the SET ENTRY qualifiers are the attributes and status that the job has before you enter the SET ENTRY command.

This command requires delete (D) access to the job, manage (M) access to the queue, or OPER (operator) privilege.

Qualifiers

/AFTER=time

/NOAFTER

Requests that the specified job be held until after a specific time. If the specified time has already passed, the job is scheduled for processing.

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

Note Releasing or rescheduling a job before its submission time is not supported for security reasons. Therefore, if you set the system time to a future time and submit a job on a node where the queue manager is running, you cannot release or reschedule that job back to the present time if you reset the system time. For example, you can set the system time to a future time of January 1, 2020 and submit a job to run on January 9, 2020. However, if you set the system time back to the present time and try to release the job to the present time, the job will be released to January 1, 2020. This situation impacts the following qualifiers: /AFTER, /NOHOLD, and /RELEASE.

To specify /AFTER for a job on hold, you must also specify /NOHOLD in order to cause the job to be held only until the specified time. Jobs can be released before the specified time by using the /NOAFTER or /RELEASE qualifier with the SET ENTRY command.

/BURST

/NOBURST

Controls whether two file flag pages with a burst bar between them are printed preceding each file in a job.

Use the /[NO]BURST qualifier to override the /DEFAULT qualifier options that have been set for the output queue you are using. The /[NO]BURST qualifier does not override the /SEPARATE qualifier options set for the queue.

When you specify the /BURST qualifier for a file, the /[NO]FLAG qualifier does not add or subtract a flag page from the two flag pages that are printed preceding a file.

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

/NOCHARACTERISTICS

Specifies the name or number 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 print job can be processed on an execution queue 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 name of a command language interpreter (CLI) to use in processing the batch job. The file name specifies that the CLI be SYS$SYSTEM:filename.EXE. If you do not specify the /CLI qualifier, the job is run by the CLI specified in the user authorization file (UAF), or whatever CLI was specified when the job was originally submitted to the queue.

/COPIES=n

Specifies the number of copies to print. The value of n can be any number from 1 to 255. When you use the /COPIES qualifier with the SET ENTRY command, the number of copies can apply only to the entire print job. You cannot use this qualifier to specify different numbers of copies for individual files within a multifile job.

/CPUTIME=time

Specifies a CPU time limit for the batch job. You can specify the time parameter as delta time, the value 0, INFINITE, or NONE. If the queue on which the job executes has a defined CPUMAXIMUM value, the smaller of the specified job 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 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. For information on specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

/FEED

/NOFEED

Controls whether form feeds are inserted into the print job when the printer reaches the bottom margin of the form in use. You can suppress this automatic form feed (without affecting any of the other carriage control functions that are in place) by using the /NOFEED qualifier.

When you use the /FEED qualifier with the SET ENTRY command, the qualifier applies to all files in the print job. You cannot use this qualifier to specify form feeds for individual files within a multifile job.

/FLAG

/NOFLAG

Controls whether a flag page is printed preceding each file in a print job. The flag page contains the name of the user submitting the job, the job entry number, and other information about the file being printed.

Use the /[NO]FLAG qualifier to override the installation-defined defaults that have been set for the output queue you are using or to override the qualifier specified in the PRINT command that queued the job.

/FORM=form

Specifies the name or number of the form to be associated with the print job. If you omit the /FORM qualifier, the default form for the execution queue is associated with the job.

Forms have attributes such as print image width and length or paper stock, which the print symbiont associates with a job when the job is processed. To see which forms have been defined for your system, use the SHOW QUEUE/FORM command. To find out which form is mounted currently on a particular queue and which form is specified as that queue's default form, use the SHOW QUEUE/FULL command.

The stock of the form associated with the job must match the stock of the form mounted on the execution queue on which you want the job to be processed. If the stocks do not match, the job remains pending until one or more of the following occurs:

• A form with the same stock as the job's form is mounted on the queue (using, for example, the SET QUEUE/FORM_MOUNTED command).
• A form with the same stock as the queue's mounted form is specified with the job (using, for example, the SET ENTRY/FORM command).
• The job is moved to a queue on which the stock of the mounted form matches the stock of the job's form (using, for example, the SET ENTRY/REQUEUE command).
• The job is deleted (using, for example, the DELETE/ENTRY command).

/HEADER

/NOHEADER

Controls whether a heading line is printed at the top of each output page in a print job.

/HOLD

/NOHOLD

Controls whether the job is to be made available for processing or held for processing later. If you specify the /HOLD qualifier, the job is not released for processing until you enter SET ENTRY/NOHOLD or SET ENTRY/RELEASE.

You can use the /NOHOLD qualifier to release jobs that have been held for the following reasons:

• A job was submitted with the /HOLD qualifier.
• A completed job is being retained in a queue.
• A user-written symbiont has refused a job.

Note Releasing or rescheduling a job before its submission time is not supported for security reasons. Therefore, if you set the system time to a future time and submit a job on a node where the queue manager is running, you cannot release or reschedule that job back to the present time if you reset the system time. For example, you can set the system time to a future time of January 1, 2020 and submit a job to run on January 9, 2020. However, if you set the system time back to the present time and try to release the job to the present time, the job will be released to January 1, 2020. This situation impacts the following qualifiers: /AFTER, /NOHOLD, and /RELEASE.

/JOB_COUNT=n

Requests that an entire print job be printed n times, where n is a decimal integer from 1 to 255. This qualifier overrides the /JOB_COUNT qualifier with the PRINT command.

/KEEP

/NOKEEP

Controls whether the batch job log file is deleted after it is printed.

/LOG_FILE[=filespec]

/NOLOG_FILE

Creates a log file with the specified file specification. You can specify a different device name, as long as the process executing the batch job has access to the device on which the log file will reside. Logical names in the file specification are translated in the context of the process that executes the SET ENTRY command.

If you omit the /LOG_FILE qualifier and specify the /NAME qualifier, the log file is written to a file having the same file name as that specified by the /NAME qualifier; the file type is .LOG. When you omit the /LOG_FILE qualifier, the job-name value used with the /NAME qualifier must be a valid file name.

/LOWERCASE

/NOLOWERCASE

Indicates whether the print job must be printed on a printer that can print both uppercase and lowercase letters. The /NOLOWERCASE qualifier means that files can be printed on printers that print only uppercase letters. If all available printers can print both uppercase and lowercase letters, you do not need to specify the /LOWERCASE qualifier.

/NAME=job-name

Names the job. The job name must be 1 to 39 alphanumeric characters. The SHOW ENTRY and SHOW QUEUE commands display the job name. For batch jobs, the job name is also used for the batch job log file. For print jobs, the job name is also used on the flag page of the printed output.

The default job name is the name of the first file in the job.

/NOCHECKPOINT

For a batch job, erases the value established by the most recently executed SET RESTART_VALUE command. For a print job, clears the stored checkpoint so that the job will restart from the beginning.

/NODELETE

Cancels file deletion for a job that was submitted with the /DELETE qualifier. If you did not specify the /DELETE qualifier when the job was originally submitted to the queue, you cannot use the SET ENTRY command to establish file deletion at a later time. You cannot use the /NODELETE qualifier to cancel deletion of individual files in a multifile job.

/NOTE=string

Specifies a message of up to 255 characters to appear on the flag page of the print job. Enclose messages containing lowercase letters, blanks, or other nonalphanumeric characters (including spaces) in quotation marks (" ").

/NOTIFY

/NONOTIFY

Controls whether a message notifies you when your job has been completed or aborted. Notification is sent to any terminal session on the same OpenVMS Cluster system to which you are logged in.

/OPERATOR=string

Specifies a message string of up to 255 characters to be sent to the operator just before the print job begins to print. Enclose the message in quotation marks (" ") if it contains spaces, special characters, or lowercase characters.

/PAGES=([lowlim,]uplim)

Specifies the number of pages to print for the specified job. You can use the /PAGES qualifier to print portions of long files. By default, all pages of the file are printed. When you use the /PAGES qualifier with the SET ENTRY command, the qualifier can apply only to an entire job. You cannot use this qualifier to specify different numbers of pages to be printed for individual files within a multifile job.

The lowlim specifier refers to the first page of the file that you want to print. If you omit the lowlim specifier, the printing starts on the first page of the file.

The uplim specifier refers to the last page of the file that you want to print. When you want to print to the end of the file but do not know how many pages are in the file, use quotation marks (" ") as the uplim specifier.

You can omit the parentheses when you specify only a value for the uplim specifier. For example, /PAGES=10 prints the first 10 pages of the file; /PAGES=(5,10) prints pages 5 to 10; /PAGES=(5,"") starts printing at page 5 and continues until the end of the file is reached.

/PARAMETERS=(parameter[,...])

Specifies from one to eight optional parameters to be passed to the job. Each parameter can have as many as 255 characters. If you specify only one parameter, you can omit the parentheses. To specify a parameter that contains any special characters or delimiters, enclose the parameter in quotation marks.

For batch jobs, the parameters define values to be equated to the symbols named P1 to P8 in each command procedure in the job. The symbols are local to the specified command procedures.

/PASSALL

/NOPASSALL

Specifies whether the symbiont bypasses all formatting of the print job and sends the output QIO to the driver with format suppressed. All qualifiers affecting formatting, as well as the /HEADER, /PAGES, and /PAGE_SETUP qualifiers, are ignored.

When you use the /PASSALL qualifier with the SET ENTRY command, the qualifier applies to the entire job. You cannot use this qualifier to specify PASSALL mode for individual files within a multifile job.

/PRINTER[=queue-name]

/NOPRINTER

Queues the batch job log file for printing when the job is completed. The default output queue for the log file is SYS$PRINT. The /PRINTER qualifier allows you to specify an output queue. The /NOPRINTER qualifier assumes the /KEEP qualifier.

/PRIORITY=n

Requires OPER (operator) or ALTPRI (alter priority) privilege to raise the priority above the value of the queue's maximum scheduling priority.

Specifies the job-scheduling priority of the job. The value of n is an integer in the range of 0 to 255, where 0 is the lowest priority and 255 is the highest.

The default value for the /PRIORITY qualifier is the value of the system parameter DEFQUEPRI. No privilege is needed to set the priority lower than the queue's maximum scheduling priority.

/RELEASE

You can use the /RELEASE qualifier to release jobs that have been held for the following reasons:

• A job was submitted with the /AFTER qualifier.
• A job was submitted with the /HOLD qualifier.
• A completed job is being retained in a queue.
• A user-written symbiont has refused a job.

Note Releasing or rescheduling a job before its submission time is not supported for security reasons. Therefore, if you set the system time to a future time and submit a job on a node where the queue manager is running, you cannot release or reschedule that job back to the present time if you reset the system time. For example, you can set the system time to a future time of January 1, 2020 and submit a job to run on January 9, 2020. However, if you set the system time back to the present time and try to release the job to the present time, the job will be released to January 1, 2020. This situation impacts the following qualifiers: /AFTER, /NOHOLD, and /RELEASE.

/REQUEUE=queue-name[:]

Requests that the job be moved from the original queue to the specified queue.

/RESTART

/NORESTART

Specifies whether a batch or print job is restarted after a system failure or a STOP/QUEUE/REQUEUE command.

/RETAIN=option

Specifies the circumstances under which you want your jobs to be retained in a queue. When a job is retained in the queue, you can issue the SHOW QUEUE command after the job completes to see the status of the job. Without job retention, no record of a job is left in a queue after a job completes.

Use the following options to specify job retention:

• ALWAYS---Holds the job in the queue regardless of the job's completion status.
• DEFAULT---Holds the job in the queue as specified by the queue's retention policy.
• ERROR---Holds the job in the queue only if the job completes unsuccessfully.
• UNTIL=time-value----Holds the job in the queue for the specified length of time, regardless of the job's completion status.

Note You cannot specify a /NORETAIN qualifier with the SET ENTRY command (as system managers can with the commands INITIALIZE/QUEUE, START/QUEUE, and SET QUEUE). However, you can specify /RETAIN=DEFAULT with the SET ENTRY command. The default option holds the job in the queue as specified by the queue's retention policy. If the system manager has not specified retention for the queue, the job is not retained.

How Job Retention Is Determined

Although you can specify job retention options for your own jobs, the job retention option you specify may be overridden by the job retention option of the queue on which your job executed. If you submit or print a job to a generic queue, the generic queue's job retention setting may also override the job retention option you specify. This section describes how job retention is determined.

An execution queue's job retention setting takes precedence over a generic queue's job retention setting. However, if the job's completion status does not match the job retention setting (if any) on the execution queue, then the generic queue's job retention setting attempts to control job retention. If the job's completion status does not match the job retention setting (if any) on the generic queue, then the user-specified job retention setting is used. Jobs submitted directly to execution queues are not affected by job retention settings on generic queues.

If the execution queue's retention setting applies, the job is retained on the execution queue. Likewise, if the generic queue's retention setting applies, the job is retained on the generic queue. If the user-specified setting applies, the job is retained in the queue to which it was submitted.

The following example illustrates how the queue manager determines job retention:

Suppose you submit a job to a generic queue and specify /RETAIN=ALWAYS, and the job completes successfully.

First, the queue manager compares the job's completion status to the execution queue's retention setting. Suppose the queue is set with /RETAIN=ERROR (retains only jobs that complete unsuccessfully). The job is not retained in the execution queue because the error condition was not met.

Second, the queue manager compares the job's completion status to the generic queue's retention setting. Suppose the generic queue has no retention setting. The queue manager's comparison again fails to retain the job.

Finally, the queue manager compares the job's completion status to the retention setting you specified for the job. This comparison reveals that the job should be retained. Because the user-specified setting leads the queue manager to retain the job, the job is held in the queue to which the job was submitted---in this case, the generic queue.

For more information on types of queues, see the INITIALIZE/QUEUE command. For more information on setting retention options for queues, see the INITIALIZE/QUEUE, START/QUEUE, or SET QUEUE command.

Timed Retention

Timed retention, which you specify using the UNTIL=time-value option, allows you to retain a job in the queue only as long as you need it. This eliminates the need to delete the job from the queue later.

For example, the following command retains job 172 in the queue until 7:31 on April 19, when the job will automatically be deleted from the queue.

$ SET ENTRY/RETAIN=UNTIL=19-APR-1998:07:31:0.0 172

However, depending on the queue's job retention policy, the job might be retained indefinitely. The job retention policy set on the queue takes precedence over the user-specified job retention setting. Because system managers cannot specify timed job retention for a queue, any jobs retained as a result of a queue's setting are retained indefinitely.

If you specify the /RETAIN=UNTIL=time-value option, you must supply a time value. The time value is first interpreted as a delta time, then as a combination time, and finally as absolute time. If you specify a delta time, the delta begins when the job completes. For example, if you specify SET ENTRY/RETAIN=UNTIL="+3:00", the job will be retained for three hours after the job completes. For information on specifying time values, refer to the OpenVMS User's Manual.

/SETUP=module[,...]

Extracts the specified modules from the device control library (containing escape sequence modules for programmable printers) and copies the modules to the printer before each file in a print job is printed.

When you use the /SETUP qualifier with the SET ENTRY command, the qualifier applies to the entire print job. You cannot use this qualifier to specify different setup modules for individual files within a multifile job.

/SPACE

/NOSPACE

Controls whether the output of a print job is double-spaced. Specifying the /NOSPACE qualifier causes the output to be single-spaced. When you use the /SPACE qualifier with the SET ENTRY command, the qualifier applies to the entire job. You cannot use this qualifier to specify different spacing for individual files within a multifile job.

/TRAILER

/NOTRAILER

Controls whether a trailer page is printed at the end of each file in a print job. The trailer page displays the entry number, as well as information about the user submitting the job and the files being printed.

When you use the /TRAILER qualifier with the SET ENTRY command, trailer pages are placed at the end of each file in a multifile job.

Use the /[NO]TRAILER qualifier to override the installation-defined defaults that have been set for the output queue you are using or the qualifier specified in the PRINT command that queued the job.

/WSDEFAULT=n

Defines, for a batch job, a working set default, which is the default number of physical pages that the job can use.

If the queue on which the job executes has a nonzero default working set, the smaller of the specified job and queue values is used. If the queue on which the job executes has a working set default of zero, the smaller of the specified job value and the value established in the user authorization file (UAF) is used.

Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that the operating system rounds up this value to the nearest CPU-specific page so that actual amount of physical memory allowed may be larger than the specified amount on Alpha. If you specify zero or NONE, the specified queue or UAF value is used. Working set default values must range between the numbers specified by the system parameters PQL_MWSDEFAULT and WSMAX.

/WSEXTENT=n

Defines, for the batch job, a working set extent, which is the maximum amount of physical memory that the job can use. The job uses the maximum amount of physical memory only when the system has excess free pages. If the queue on which the job executes has a nonzero working set extent, the smaller of the specified job and queue values is used. If the queue on which the job executes has a working set extent of zero, the smaller of the specified job value and the value established in the user authorization file (UAF) is used.

Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that the operating system rounds up this value to the nearest CPU-specific page so that actual amount of physical memory allowed may be larger than the specified amount on Alpha. If you specify zero or NONE, the specified queue or UAF value is used. Working set extent values must range between the numbers specified by the system parameters PQL_MWSEXTENT and WSMAX.

/WSQUOTA=n

Defines, for the batch job, a working set quota, which is the amount of physical memory that the job is guaranteed. If the queue on which the job executes has a nonzero working set quota, the smaller of the specified job and queue values is used. If the queue on which the job executes has a working set quota of zero, the smaller of the specified job value or the value established in the user authorization file (UAF) is used.

Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that the operating system rounds up this value to the nearest CPU-specific page so that actual amount of physical memory allowed may be larger than the specified amount on Alpha. If you specify zero or NONE, the specified queue or UAF value is used. Working set quota values must range between the numbers specified by the system parameters PQL_MWSQUOTA and WSMAX.

Examples

$ PRINT/HOLD   MYFILE.DAT
  Job MYFILE (queue SYS$PRINT, entry 112) holding
$ SET ENTRY 112/RELEASE/JOB_COUNT=3
 
      

The PRINT command in this example requests that the file MYFILE.DAT be queued to the system printer, but placed in a hold status. The SET ENTRY command releases the job for printing and requests that three copies of the job be printed.

$ SUBMIT CLIMATE
  Job CLIMATE (queue SYS$BATCH, entry 211) pending
$ SET ENTRY 211/HOLD/NAME=TEMP
      

---

Previous

Next

Contents

Index

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

9996PRO_050.HTML