HELPLIB.HLB  —  SUBMIT  Qualifiers

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, see the OpenVMS User's Manual or the
    online help topic Date.

    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, see
    the VSI 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, see the
    OpenVMS User's Manual or the online help topic Date.

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.

    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    /RAD

       /RAD=n

    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.

    RAD is supported on AlphaServer GS series systems and starting
    from OpenVMS Version 8.4, support is extended to NUMA capable
    Integrity servers.

26    /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

27    /RESTART

       /RESTART
       /NORESTART (default)

    Indicates whether the job restarts after a system failure or
    after a STOP/QUEUE/REQUEUE command.

28    /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, see the OpenVMS User's Manual.

29    /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, JOB_LOGIN, 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, see the
    OpenVMS User's Manual or the online help topic Date.

30    /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.

    See the OpenVMS User's Manual for more information.

31    /SYMLINK

       /SYMLINK=keyword

    The valid keywords for this qualifier are [NO]WILDCARD and
    [NO]ELLIPSIS. Descriptions are as follows:

    Keyword     Explanation

    WILDCARD    Indicates that symlinks are enabled during wildcard
                searches.
    NOWILDCARD  Indicates that symlinks are disabled during directory
                wildcard searches.
    ELLIPSIS    Equivalent to WILDCARD (included for command
                symmetry).
    NOELLIPSIS  Indicates that symlinks are matched for all wildcard
                fields except for ellipsis.

    If the file named in the SUBMIT command is a symlink, the command
    operates on the symlink target.

32    /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.

33    /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.
    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.

34    /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.
    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.

35    /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.
    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.
Close Help