SUBMIT, Qualifiers
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help SUBMIT, Qualifiers *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
1 - /AFTER
/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 OpenVMS System Management Utilities Reference Manual.
2 - /BACKUP
/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.
3 - /BEFORE
/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).
4 - /BY_OWNER
/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.
5 - /CHARACTERISTICS
/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:
o 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).
o 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).
o 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).
o The job is deleted (using, for example, the DELETE/ENTRY
command).
6 - /CLI
/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).
7 - /CONFIRM
/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.
8 - /CPUTIME
/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.
9 - /CREATED
/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.
10 - /DELETE
/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.
11 - /EXCLUDE
/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.
12 - /EXPIRED
/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.
13 - /HOLD
/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.
14 - /IDENTIFY
/IDENTIFY (default)
/NOIDENTIFY
Displays the job name, the queue name, the entry number, and the
status of the job when it is queued.
15 - /KEEP
/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.
16 - /LOG_FILE
/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. 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.
17 - /MODIFIED
/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.
18 - /NAME
/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.
19 - /NOTE
/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).
20 - /NOTIFY
/NOTIFY
/NONOTIFY (default)
Controls whether a message is broadcast to your terminal session
when the job is completed or aborted.
21 - /PARAMETERS
/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.
22 - /PRINTER
/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.
23 - /PRIORITY
/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.
24 - /QUEUE
/QUEUE=queue-name[:]
Identifies the batch queue on which the job is entered. The
default queue is SYS$BATCH.
25 - /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
26 - /RESTART
/RESTART
/NORESTART (default)
Indicates whether the job restarts after a system failure or
after a STOP/QUEUE/REQUEUE command.
27 - /RETAIN
/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:
o ALWAYS--Holds the job in the queue regardless of the job's
completion status.
o DEFAULT--Holds the job in the queue as specified by the
queue's retention policy.
o ERROR--Holds the job in the queue only if the job completes
unsuccessfully.
o 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.
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
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:
$ SUBMIT/RETAIN=UNTIL=14-DEC-2001:07:31:0.0 MYFILE.COM
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.
28 - /SINCE
/SINCE[=time]
/NOSINCE
Selects 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).
29 - /STYLE
/STYLE=keyword
Specifies the file name format for display purposes.
The valid keywords for this qualifier are CONDENSED and EXPANDED.
Descriptions are as follows:
Keyword Explanation
CONDENSED Displays the file name representation of what is
(default) generated to fit into a 255-length character string.
This file name may contain a DID or FID abbreviation
in the file specification.
EXPANDED Displays the file name representation of what is
stored on disk. This file name does not contain any
DID or FID abbreviations.
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.
30 - /USER
/USER=username
Requires 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.
31 - /WSDEFAULT
/WSDEFAULT=n
Defines 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.
32 - /WSEXTENT
/WSEXTENT=n
Defines 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.
33 - /WSQUOTA
/WSQUOTA=n
Defines 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.
|
|
