Document revision date: 30 March 2001
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS DCL Dictionary
Previous Contents Index

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:

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:

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-2001: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 the 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 the 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 the 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

#1 

$ 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.

#2 

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

The SUBMIT command in this example queues the command procedure CLIMATE.COM for processing as a batch job. The SET ENTRY command places the job in a hold state and changes the job name to TEMP, assuming that the job has not yet begun execution.

#3 

$ PRINT/FLAG=ALL/AFTER=20:00 MEMO.MEM, LETTER.MEM, REPORT.MEM/SPACE
  Job MEMO (queue SYS$PRINT, entry 172) holding until 20:00
$ SET ENTRY 172 /BURST/NOSPACE/HEADER

The PRINT command in this example requests that three files be printed after 8:00 P.M. on the default printer with flag pages preceding each file. It also requests that the file REPORT.MEM be double-spaced. Later a SET ENTRY command calls for a burst page at the beginning of each file and requests that all files in the job be single-spaced. This command also requests that headers be printed on each page of each file in the job.

SET FILE

Modifies the characteristics of one or more files.

See the qualifier descriptions for restrictions.

Format

SET FILE filespec[,...]

Parameter

filespec[,...]

Specifies one or more files to be modified. If you specify more than one file, separate the file specifications with commas (,). The asterisk (*) and the percent sign (%) wildcard characters are allowed.

Description

The SET FILE command modifies a number of file characteristics.

Qualifiers

/ATTRIBUTE=(file-attribute[,...])

Sets the attributes associated with a file. The following table lists possible keywords and the relationship to both ACP-QIO and OpenVMS RMS File attributes:
Keyword ACP-QIO File Attribute1 OpenVMS RMS File Attribute2
BKS:{value} FAT$B_BKTSIZE={byte} FAB$B_BKS={byte}
DEQ:{value} FAT$W_DEFEXT={word} FAB$W_DEQ={word}
EBK:{value} FAT$L_EFBLK={longword} XAB$L_EBK={longword}
FFB:{value} FAT$W_FFBYTE={word} XAB$W_FFB={word}
FSZ:{value} FAT$B_VFCSIZE={byte} FAB$B_FSZ={byte}
GBC:{value} FAT$W_GBC={word} FAB$W_GBC={word}
HBK:{value} FAT$L_HIBLK={longword} XAB$L_HBK={longword}
LRL:{value} FAT$W_RSIZE={word} XAB$W_LRL={word}
MRS:{value} FAT$W_MAXREC={word} FAB$W_MRS={word}
ORG:IDX FAT$V_FILEORG=FAT$C_INDEXED FAB$B_ORG=FAB$C_IDX
ORG:REL FAT$V_FILEORG=FAT$C_RELATIVE FAB$B_ORG=FAB$C_REL
ORG:SEQ FAT$V_FILEORG=FAT$C_SEQUENTIAL FAB$B_ORG=FAB$C_SEQ
RAT:BLK FAT$B_RATTRIB=FAT$M_NOSPAN FAB$B_RAT=FAB$M_BLK
RAT:CR FAT$B_RATTRIB=FAT$M_IMPLIEDCC FAB$B_RAT=FAB$M_CR
RAT:FTN FAT$B_RATTRIB=FAT$M_FORTRANCC FAB$B_RAT=FAB$M_FTN
RAT:MSB FAT$B_RATTRIB=FAT$M_MSBVAR FAB$B_RAT=FAB$M_MSB
RAT:NONE FAT$B_RATTRIB=0 FAB$B_RAT=0
RAT:PRN FAT$B_RATTRIB=FAT$M_PRINTCC FAB$B_RAT=FAB$M_PRN
RFM:FIX FAT$V_RTYPE=FAT$C_FIXED FAB$B_RFM=FAB$C_FIX
RFM:STM FAT$V_RTYPE=FAT$C_STREAM FAB$B_RFM=FAB$C_STM
RFM:STMCR FAT$V_RTYPE=FAT$C_STREAMCR FAB$B_RFM=FAB$C_STMCR
RFM:STMLF FAT$V_RTYPE=FAT$C_STREAMLF FAB$B_RFM=FAB$C_STMLF
RFM:UDF FAT$V_RTYPE=FAT$C_UNDEFINED FAB$B_RFM=FAB$C_UDF
RFM:VAR FAT$V_RTYPE=FAT$C_VARIABLE FAB$B_RFM=FAB$C_VAR
RFM:VFC FAT$V_RTYPE=FAT$C_VFC FAB$B_RFM=FAB$C_VFC
VRS:{value} FAT$W_VERSIONS={word} XAB$W_VERLIMIT={word}
1For further information, refer to the OpenVMS I/O User's Reference Manual.
2For further information, refer to the OpenVMS Record Management Services Reference Manual.

/BACKUP

/NOBACKUP

Specifies that the Backup utility (BACKUP) records the contents of the file. The /NOBACKUP qualifier causes BACKUP to record the attributes of the file but not its contents. This qualifier is valid only for Files-11 Structure On-Disk Level 2 and 5 files.

The /NOBACKUP qualifier is useful for saving files that contain unimportant data, such as SWAPFILES.

/BEFORE[=time]

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 the /CREATED or the /MODIFIED qualifier to indicate the time attribute to be used as the basis for selection. The /CREATED qualifier is the default.

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]

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 Guide to System Security.

/CACHING_ATTRIBUTE=keyword

Use this qualifier to control which files are cached by the Extended File Cache. It sets the caching attribute for a file or directory in a Files-11 ODS-2 or ODS-5 volume.

The caching attribute of a file is the default caching option that is used by the Extended File Cache when an application accesses the file without specifying which caching option it wants to use.

The keyword can be either WRITETHROUGH or NO_CACHING. Use WRITETHROUGH for files that you want to be cached. Use NO_CACHING for files that you don't want to be cached.

The Extended File Cache does not cache directories. The caching attribute of a directory controls only how the caching attribute is inherited by new files and subdirectories created in the directory:

When you use the INITIALIZE command to create a new Files-11 volume, the caching attribute of its root directory (000000.DIR;1) is set to write-through. This means that by default, all the files and directories you create in the volume will inherit a caching attribute of write-through unless you use SET FILE /CACHING_ATTRIBUTE.

If you do not want to cache any files in a volume, mount the volume with caching disabled, using MOUNT /NOCACHE, instead of setting the caching attribute of all the files in the volume to NO_CACHING. Using MOUNT /NOCACHE gives better performance, and ensures the minimum caching overhead.

When you change the caching attribute of a directory, it does not affect the caching attribute of any existing files and subdirectories in the directory.

When you change the caching attribute of a file, it does not affect the type of caching being used by any applications that are currently accessing the file.

/CONFIRM

/NOCONFIRM (default)

Controls whether a request is issued before each SET FILE 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. Word responses can be abbreviated 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 Return. 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.

/CREATED (default)

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 /MODIFIED qualifier, which also allows you to select files according to time attributes. The /CREATED qualifier is the default qualifier.

/DATA_CHECK[=([NO]READ,[NO]WRITE)]

Specifies whether a read data check (rereading each record), a write data check (reading each record after it is written), or a combination of the two is performed on the file during transfers. By default, a write data check is performed.

/END_OF_FILE

Resets the end-of-file (EOF) mark to the highest block allocated.

/ENTER=alias-filespec

Use with caution.

Creates an alias for the specified file. Both the original name and the new alias refer to the same file. To remove the alias, use the SET FILE /REMOVE command.

Note
Make sure that the alias and the original name are in different directories, or you may subsequently lose data during a delete or purge operation. The DELETE and PURGE commands and the file version limit feature can behave unpredictably if the original name and the alias are in the same directory.

If you use aliases, you must also be careful when you use the DELETE and SET FILE /REMOVE commands, or you may end up with either an inaccessable file that has no name or a name that does not refer to a file. Follow these guidelines to avoid these problems:

  • Use SET FILE /REMOVE to remove an alias; do not use the DELETE command to remove an alias.
  • Do not use SET FILE /REMOVE to remove the original file name.

If you do not follow these guidelines and encounter problems, use ANALYZE /DISK /REPAIR to move inaccessable files to the SYSLOST directory and remove names that no longer refer to files.

/ERASE_ON_DELETE

Specifies that the specified files are erased from the disk (not just written over) when the DELETE or PURGE command is issued for the files. See the DELETE/ERASE command for more information.

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

Excludes the specified file from the SET FILE operation. You can include a directory name but not a device name in the file specifications. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the file specification; however, you cannot use relative version numbers to exclude a specific version. If you specify only one file, you can omit the parentheses.

/EXPIRATION_DATE=date

/NOEXPIRATION_DATE

Requires read (R), write (W), and control access. Being the owner of the file is one way to get control access.

Controls whether an expiration date is assigned to the specified files.

Specify the date according to the rules described in the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time). Absolute date keywords are allowed. If you specify zero as the date, today's date is used.

/EXTENSION[=n]

Sets the extend quantity default for the file. The value of the parameter n can range from 0 to 65,535. If you omit the value specification or specify a value of 0, OpenVMS Record Management Services (OpenVMS RMS) calculates its own value for the /EXTENSION qualifier.

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
9996PRO_053.HTML