The SUBMIT command places the specified files in a batch queue for
subsequent execution. By default, this queue is SYS$BATCH. All files
queued by a single SUBMIT command are processed serially as one job. By
default, the name of the batch job is the name of the first file
specified in the SUBMIT command.
The system assigns a unique entry number to each batch job in the
queue. When you enter the SUBMIT command, by default, the system
displays the job name, the queue name, the entry number, and the job
status.
The system automatically creates or updates the local symbol $ENTRY
when a SUBMIT command completes successfully. The value of $ENTRY is a
string that identifies the entry number of the most recently queued
job. If you want to refer to a job's entry number later, store the
value of $ENTRY in another symbol.
After you queue a batch job, the version of the file submitted is
processed, even if a newer version of the file is created before the
batch job runs. Also, another file with the same name and version
number as the file queued cannot be substituted for the file that was
submitted.
When the system executes a command procedure submitted to a batch
queue, it creates a detached process to execute the commands. This
process receives the owner's disk and directory defaults and the same
resource quotas and privileges that were given to the owner's
interactive process when you logged in.
If multiple procedures are submitted, the job terminates as soon as any
procedure exits with an error or severe (fatal) error status.
In an OpenVMS Cluster environment, you should periodically keep the
cluster in time synchronization using the SET TIME/CLUSTER command
because the differences in system times between nodes in an OpenVMS
Cluster may vary. This variance may cause a job to begin executing a
little before or after the specified time because the redundancy built
into the batch and print system allows more than one job controller in
the cluster to receive a timer asynchronous system trap (AST) for the
job and, thus, to schedule it for execution.
Batch Job Output
By default, all output from each command procedure in a batch job is
written to a log file. This log file is queued for printing on
SYS$PRINT when the batch job finishes. By default, this log file is
deleted after it is printed. When you stop a batch job by using the
STOP/QUEUE/ENTRY, the STOP/IDENTIFICATION, or the DELETE/ENTRY command,
the log file is not queued for printing.
For information on how to change the system's handling of the log file,
see the descriptions of the /LOG_FILE, /PRINTER, and /KEEP qualifiers.
/AFTER=time
/NOAFTER
Requests that the job be held until after a specific time. If the
specified time has passed already, the job is processed immediately.
You can specify time as either absolute time or as a combination of
absolute and delta times. For complete information on specifying time
values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips
(subtopic Date_Time).
In an OpenVMS Cluster, a batch job submitted to execute at a specific
time may begin execution a little before or after the requested time.
This occurs when the clocks of the member systems in the OpenVMS
Cluster are not synchronized. For example, a job submitted using the
DCL command SUBMIT/AFTER=TOMORROW may execute at 11:58 P.M. relative to
the host system's clock.
This problem can occur in a cluster even if a job is run on the same
machine from which it was submitted, because the redundancy built into
the batch/print system allows more than one job controller in the
cluster to receive a timer asynchronous system trap (AST) for the job
and, thus, to schedule it for execution. Moreover, this behavior is
exacerbated if the batch job immediately resubmits itself to run the
next day using the same SUBMIT command. This can result in having
multiple instances of the job executing simultaneously because TOMORROW
(after midnight) might be only a minute or two in the future.
A solution to this problem is to place the SUBMIT command in a command
procedure that begins with a WAIT command, where the delta-time
specified in the WAIT command is greater than the maximum difference in
time between any two systems in the cluster. Use the SHOW TIME command
on each system to determine this difference in time. Use the SYSMAN
command CONFIGURATION SET TIME to synchronize clocks on the cluster.
For complete information on the SYSMAN command CONFIGURATION SET TIME,
refer to the HP OpenVMS System Management Utilities Reference Manual.
/BACKUP
/NOBACKUP
Modifies the time value specified with the /BEFORE or the /SINCE
qualifier. The /BACKUP qualifier selects files according to the dates
of their most recent backups. This qualifier is incompatible with the
/CREATED, /EXPIRED, and /MODIFIED qualifiers, which also allow you to
select files according to time attributes. If you specify none of these
four time qualifiers, the default is the /CREATED qualifier.
/BEFORE[=time]
/NOBEFORE
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 one of the following
qualifiers with the /BEFORE qualifier to indicate the time attribute to
be used as the basis for selection: /BACKUP, /CREATED (default),
/EXPIRED, or /MODIFIED.
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]
/NOBY_OWNER
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 User's Manual.
/CHARACTERISTICS=(characteristic[,...])
Specifies the name or numbers 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 job can be executed on a queue only 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 command language interpreter (CLI) to be used to process
the job. The file specification assumes the device name SYS$SYSTEM: and
the file type .EXE (SYS$SYSTEM:filename.EXE). The default CLI is that
defined in the user authorization file (UAF).
/CONFIRM
/NOCONFIRM (default)
Controls whether a request is issued before each submit 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. You can abbreviate word responses 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.
/CPUTIME=time
Defines a CPU time limit for the batch job. You can specify time as
delta time, 0, INFINITE, or NONE. If the queue on which the job
executes has a defined CPUMAXIMUM value, the smaller of the SUBMIT
command 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 the keyword 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.
/CREATED (default)
/NOCREATED
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 /BACKUP, /EXPIRED,
and /MODIFIED qualifiers, which also allow you to select files
according to time attributes. If you specify none of these four time
qualifiers, the default is the /CREATED qualifier.
/DELETE
/NODELETE (default)
Positional qualifier.
Controls whether files are deleted after processing. If you specify the
/DELETE qualifier after the SUBMIT command name, all files in the job
are deleted after processing. If you specify the /DELETE qualifier
after a file specification, only that file is deleted after it is
processed.
For the /DELETE qualifier to work, the protection code on the input
files must allow delete (D) access to the user identification code
(UIC) of the user submitting the job. If delete (D) access is not
allowed, or if any file in the command parameter list cannot be opened
as input, command processing stops and no batch job is created.
/EXCLUDE=(filespec[,...])
/NOEXCLUDE
Excludes the specified files from the submit operation. You can include
a directory but not a device in the file specification. The asterisk
(*) and the percent sign (%) wildcard characters are allowed in the
file specification. If you specify only one file, you can omit the
parentheses.
/EXPIRED
/NOEXPIRED
Modifies the time value specified with the /BEFORE or the /SINCE
qualifier. The /EXPIRED qualifier selects files according to their
expiration dates. (The expiration date is set with the SET
FILE/EXPIRATION_DATE command.) The /EXPIRED qualifier is incompatible
with the /BACKUP, /CREATED, and /MODIFIED qualifiers, which also allow
you to select files according to time attributes. If you specify none
of these four time qualifiers, the default is the /CREATED qualifier.
/HOLD
/NOHOLD (default)
Controls whether the job is made available for immediate processing.
The /HOLD qualifier holds the job until it is released by the SET
ENTRY/RELEASE or the SET ENTRY/NOHOLD command.
/IDENTIFY (default)
/NOIDENTIFY
Displays the job name, the queue name, the entry number, and the status
of the job when it is queued.
/KEEP
/NOKEEP
Controls whether the log file is deleted after it is printed; the
/NOKEEP qualifier is the default unless the /NOPRINTER qualifier is
specified.
/LOG_FILE[=filespec]
/NOLOG_FILE
Names the log file. The asterisk (*) and the percent sign (%) wildcard
characters are not allowed in the file specification.
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.
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.
/MODIFIED
/NOMODIFIED
Modifies 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-name
Names 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=text
Specifies 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).
/NOTIFY
/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.
/PRINTER[=queue-name](default)
/NOPRINTER
Queues 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=n
Requires 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.
/RAD=n (Alpha only)
Specifies the RAD number on which the submitted batch job is to execute.
When a job is submitted to a batch queue that does not have a RAD
setting, the job will execute using the RAD specified. If the batch
queue has a RAD setting, the job will execute using the RAD specified
on the queue.
When you specify a RAD on a batch job, the job controller creates the
process with the $CREPRC home_rad argument set to the
RAD value on the job. If the RAD specified on the job is invalid on the
target system, the job fails to execute and the job controller outputs
a message to the operator console indicating that a bad RAD was
specified. If the bad RAD value matches the RAD setting on the batch
queue, the batch queue is stopped and the job remains in the queue.
Supported only on AlphaServer GS series systems.
/REMOTE
Queues 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:
|
/BACKUP
|
/BEFORE
|
/BY_OWNER
|
/CONFIRM
|
|
/CREATED
|
/EXCLUDE
|
/EXPIRED
|
/MODIFIED
|
|
/SINCE
|
|
|
|
/RESTART
/NORESTART (default)
Indicates whether the job restarts after a system failure or after 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 SUBMIT command (as
system managers can with the commands INITIALIZE/QUEUE, START/QUEUE,
and SET QUEUE); however, you can specify /RETAIN=DEFAULT with the
SUBMIT 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.
