HP OpenVMS Systems Documentation
OpenVMS DCL Dictionary
When you use the /LOG_FILE qualifier, the system writes the batch job's output to the file you specify. If you use the /NOLOG_FILE qualifier, no log file is created. By default, a log file is created, is written to the directory defined by the logical name SYS$LOGIN in the UAF, and is given the batch job's name as its file name with a file type of .LOG. By default, a log file also is given the batch job's name as its file name with a file type of .LOG.
You can use the /LOG_FILE qualifier to write the log file to a different device. Logical names in the file specification are translated in the context of the process that submits the job. The process executing the batch job must have access to the device on which the log file will reside.
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 with the file type .LOG. When you omit the /LOG_FILE qualifier, the job-name value used with the /NAME qualifier must be a valid file name.
/NOMODIFIEDModifies the time value specified with the /BEFORE or the /SINCE qualifier. The /MODIFIED qualifier selects files according to the dates on which they were last modified. This qualifier is incompatible with the /BACKUP, /CREATED, and /EXPIRED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time modifiers, the default is the /CREATED qualifier.
/NAME=job-nameNames the job (and possibly the batch job log file). The job name must be 1 to 39 alphanumeric characters. If characters other than alphanumeric characters, underscores (_), or dollar signs ($) are used in the name, enclose the name in quotation marks (" "). The default job name is the name of the first file in the job.
If you omit the /LOG_FILE qualifier, the job-name value must be a valid file name. The SHOW ENTRY and SHOW QUEUE/FULL commands display the job name.
/NOTE=textSpecifies a message string of up to 255 characters. This message string appears as part of the display on a SHOW QUEUE/FULL command and can thus be used to convey information concerning a job. The message specified with the /NOTE qualifier is also printed on the flag page of the log file (if printed).
/NONOTIFY (default)Controls whether a message is broadcast to your terminal session when the job is completed or aborted.
/PARAMETERS=(parameter[,...])Provides the values of up to eight optional parameters (equated to the symbols P1 to P8, respectively, for each command procedure in the job). The symbols are local to the specified command procedure.
Commas (,) separate individual parameters. If you specify only one parameter, you can omit the parentheses.
If the parameter contains spaces, special characters, or lowercase characters, enclose it in quotation marks. The size of the parameter can be from 1 to 255 characters.
/NOPRINTERQueues the job log file for printing when your job is completed. The /PRINTER qualifier allows you to specify a particular print queue; the default print queue is SYS$PRINT. If you specify the /NOPRINTER qualifier, the /KEEP qualifier is assumed.
When batch and output queues are managed by the same queue manager, the queue manager checks to ensure that the queue specified on the SUBMIT/PRINTER command is an output queue and that the user has access to the output queue. These checks are not made if the batch queue specified by the SUBMIT command and the output queue specified by the /PRINTER qualifier are managed by different queue managers.
If you explicitly specify an output queue for the log file when submitting a batch job, be sure the queue you specify with the /PRINTER qualifier is an output queue and not a batch queue. Also, be sure that you have access to the output queue.
/PRIORITY=nRequires OPER (operator) or ALTPRI (alter privilege) privilege to specify a priority greater than the queue's maximum scheduling priority.
Specifies the job-scheduling priority for the batch job with respect to other jobs in the same queue. 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 is the value of the system parameter DEFQUEPRI. No privilege is needed to set the priority lower than the queue's maximum scheduling priority, which is the value of the system parameter MAXQUEPRI.
The /PRIORITY qualifier has no effect on the job's process execution priority. The job's process execution priority is determined by the base priority attribute of the INITIALIZE/QUEUE/BASE_PRIORITY command.
/QUEUE=queue-name[:]Identifies the batch queue on which the job is entered. The default queue is SYS$BATCH.
/REMOTEQueues the job to SYS$BATCH on the remote node specified. When you use the /REMOTE qualifier, you must include the node name in the file specification.
Note that, unlike submitting a job on a local node, multiple command procedures queued by a single SUBMIT/REMOTE command are considered separate jobs.
You can specify only the following qualifiers with the /REMOTE qualifier:
/NORESTART (default)Indicates whether the job restarts after a system failure or after a STOP/QUEUE/REQUEUE command.
/RETAIN=optionSpecifies 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:
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 describes 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.
The queue manager then 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, 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 the job MYFILE in the queue until 7:31 on December 14, when the job will automatically be deleted from the queue:
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 an absolute time. If you specify a delta time, the delta begins when the job completes. For example, if you specify SUBMIT/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.
/NOSINCESelects only those files dated on or after 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 /SINCE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.
For complete information about specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).
/STYLE=keywordSpecifies the file name format for display purposes.
The valid keywords for this qualifier are CONDENSED and EXPANDED. Descriptions are as follows:
The keywords CONDENSED and EXPANDED are mutually exclusive. This qualifier specifies which file name format is displayed in the output message, along with the confirmation if requested.
File errors are displayed with the CONDENSED file specification unless the EXPANDED keyword is specified.
Refer to the OpenVMS Guide to Extended File Specifications for more information.
/USER=usernameRequires CMKRNL (change mode to kernel) privilege and read (R) and write (W) access to the user authorization file (UAF).
Allows you to submit a job on behalf of another user. The job runs exactly as if that user had submitted it. The job runs under that user's user name and user identification code (UIC), and accounting information is logged to that user's account. By default, the user identification comes from the requesting process. The username qualifier value can be any user name that is validated on your system. The name must be 1 to 12 alphanumeric characters.
/WSDEFAULT=nDefines for a batch job a working set default, 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 0, the smaller of the specified job and UAF values (value established in the user authorization file) is used.
Specify the value of n as a number of 512-byte pagelets on Alpha or 512-byte pages on VAX. Note that OpenVMS systems round 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 the value 0 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=nDefines for the batch job a working set extent, 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 0, the smaller of the specified job 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 OpenVMS systems round 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 the value 0 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=nDefines for the batch job a working set quota, 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 0, the smaller of the specified job 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 OpenVMS systems round 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 the value 0 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.
Defines the beginning of a subroutine in a command procedure. The SUBROUTINE command must be the first executable statement in a subroutine. For more information about the SUBROUTINE command, refer to the description of the CALL command.
Holds the process issuing the command until the specified job completes execution.
The SYNCHRONIZE command provides job synchronization by placing a process in a wait state until the specified job completes. If the specified job is not a current job in the system, the SYNCHRONIZE command displays an error message.