qsub - Submit an NQS request to lsbatch
qsub [ flags ] [ script-file ]
qsub is an lsNQS version of the NQS command of the same name.
NQS batch request to the load sharing batch system, lsbatch
(see
lsbatch(1)
).
If script-file is not specified, the set of commands to be exe-
cuted as a
batch request is taken directly from the standard input file
(stdin).
Like NQS, the script-file is spooled.
All of the flags that you can specify on the command line can
also be
specified within the first comment block inside the batch
request scriptfile
as embedded default flags. These flags set default
characteristics
for the batch request. If you specify the same flag on the com-
mand line,
the command line flag (and any associated value) takes pre-
cedence over the
embedded flag. See the section entitled OPTIONS for more
information on
embedded default flags.
The following options for the qsub command in the original NQS
system are
supported by the lsNQS version of qsub (see the section OPTIONS
for the
complete definition and syntax used for each of these flags).
The following options for the qsub command in the original NQS
system are
not supported by the lsNQS version of qsub:
It is possible to specify default flags within the batch
request script
file that configure the default behavior of the batch request.
used to scan for such embedded default flags within a
batch request
script file is:
1. Read the first line of the script file.
2. If the current line contains only whitespace charac-
ters, or the
first non-whitespace character of the line is ``:'',
go to step
7.
3. If the first non-whitespace character or characters
of the
current line are not ``#'' or ``$!'', go to step 8.
4. If the second non-whitespace character in the current
line is not
the ``@'' character, or the character immediately
following the
second non-whitespace character in the current line
is not a
``$'', go to step 7.
5. If no ``-'' is present as the character immediately
following the
``@$'' sequence, go to step 8.
6. Process the embedded flag, stopping the parsing pro-
cess upon
reaching the end of the line, or upon reaching the
first unquoted
``#'' or ``$!'' character or characters.
7. Read the next script file line. Go to step 2.
8. End. No more embedded flags are recognized.
Here is an example of the use of embedded flags within the script file.
#
# Batch request script example:
#
# @$-a «11:30pm EDT» -lt «21:10, 20:00"
-a date-time
Do not run the batch request before the specified
date and/or
time. If a date-time specification is composed of
two or more
tokens separated by whitespace characters. You must
place the
date-time specification within double quotes as in
-a «July, 4,
2026 12:31-EDT» or otherwise escaped such that qsub
and the
shell will interpret the entire date-time specifi-
cation as a
single-character string. This restriction also
applies when an
embedded default -a flag with accompanying date-
time specification
appears within the batch request script file.
The syntax accepted for the date-time parameter is
relatively
flexible. Unspecified date and time values default
to an
appropriate value (for example, if no date is
specified, the
current month, day, and year are assumed).
You can specify a date as a month and day (current
year
assumed), or you can also explicitly specify the
year. It is
also possible to specify the date as a weekday name
(e.g.
``Tues''), or as one of the strings: ``today'' or
``tomorrow''.
Weekday names and month names can be abbreviated by
any threecharacter
(or longer) prefix of the actual name.
period can follow an abbreviated month or day name.
You can give the time of day specifications using a
twenty-four
hour clock, or you can use the ``am'' and ``pm''
specifications.
In the absence of a meridian specification,
a twentyfour
hour clock is assumed.
You must note that the time of day specification is
interpreted
using the precise meridian definitions whereby
``12am'' refers
to the twenty-four hour clock time of 0:00:00,
``12m'' refers
to noon, and ``12-pm'' refers to 24:00:00. Alter-
natively, the
phrases ``midnight'' and ``noon'' are accepted as
time of day
specifications, where ``midnight'' refers to the
time of
24:00:00.
A time zone may also appear at any point in the
date-time
specification. Thus, it is legal to say: ``April
1, 1987
13:01-PDT''. In the absence of a time zone specif-
ication, the
local time zone is assumed, with daylight savings
time being
inferred when appropriate, based on the date speci-
fied.
All alphabetic comparisons are performed in a case
insensitive
fashion such that both ``WeD'' and ``weD'' refer to
the day of
Wednesday.
Some valid date-time examples are:
01-Jan-1986 12am, PDT
Tuesday, 23:00:00
11pm tues.
tomorrow 23:00-MST
-e [[/]path/] stderr-filename
Direct output generated by the batch request which
is otherwise
sent to the stderr file to the named file
[[/]path/] stderrfilename.
The brackets ``['' and ``]'' enclose optional por-
tions of the
stderr destination path and stderr-filename.
If the path/file name does not begin with a ``/'',
the partial
path name is interpreted relative to the user's
current working
directory when the request is submitted.
You cannot specify this flag when the -eo flag
option is also
present.
If the -eo and -e [[/]path/] stderr-filename flag
options are
not present, then all stderr output for the batch
request is
appended to the file whose name consists of the
first seven
characters of the request-name followed by the
characters:
``.e''.
-lx limit-argument
Set a resource limit. Available limits are summar-
ized in the
following table:
Resource Limits
Limit Option Limited resource Enforce-
ment
-lc soft-limit per-process corefile size trunca-
tion
The per-process corefile size limit sets the max-
imum size of a
corefile created by a process. The per-process
data-segment
size limit sets the maximum size to which a
process's datasegment
can grow. The per-process file-size limit
sets the
maximum size to which a file written by a process
can grow.
The per-process memory size limit sets the maximum
amount of
memory a process can consume. The per-process
stack-segment
size limit sets the maximum size to which a
process's stacksegment
can grow. The per-process CPU time limit
sets the maximum
amount of CPU time a process can consume. The
per-process
working set size limit sets the maximum amount of
physical
memory each process within a running batch request
must use.
Enforcement of the limits is done by the underlying
normally through termination by a sig-
nal. Perprocess
limits are enforced only on the process
exceeding the
limit. Not all UNIX implementations support all the
resource
limits listed above. The qsub command will pass
all the specified
limits on to the execution machine. If a
batch request
specifies a limit, and the machine on which the
batch request
is eventually run does not support the enforcement
of that
limit, the limit is ignored. lsNQS makes no dis-
tinction between
permanent and temporary files; all files are
treated as permanent.
The `Enforcement' column of the table above indi-
cates a sample
enforcement policy of each resource limit.
See the section LIMITS for more information on the
implementation
of batch request limits and for a description
of the precise
syntax of the various limit arguments.
-o [[/]path/] stdout-filename
Direct output generated by the batch request which
is otherwise
sent to the stdout file to the named file
[[/]path/] stdoutfilename
The brackets ``['' and ``]'' enclose optional por-
tions of the
stdout destination machine, path, and stdout-
filename.
If the path/filename does not begin with a ``/'',
the partial
path/filename is interpreted relative to the user's
current
directory when the request is submitted.
If no -o [[/]path/] stdout-filename flag is speci-
fied, then all
stdout output for the batch request is appended to
the file
whose name consists of the first seven characters
of the
request-name followed by the characters: ``.o''.
-q queue-name
Specifies the queue to which the batch request is
submitted.
If no -q queue-name specification is given, the
request is submitted
to the default batch request of lsbatch
queue as defined
by the local system administrator.
-r request-name
Assign the specified request-name to the request.
absence of an explicit -r request-name specifica-
tion, the
request-name defaults to the name of the script
file (leading
path name removed) given on the command line. If
no script
file was given, the default request-name assigned
to the
request is STDIN.
In all cases, if the request-name is found to begin
with a
digit, the character ``R'' is prepended to prevent
a requestname
from beginning with a digit. All request-
names are truncated
to a maximum length of 15 characters.
-s shell-name
Specify the absolute path name of the shell that is
used to
interpret the batch request script. In the absence
of this
flag, the lsbatch system at the execution machine
uses the
Bourne shell for the execution of the batch
request. lsbatch
exports all environment variables. This is the
default. When a
batch request is submitted, the user's execution
environment,
such as current working directory, file creation
mask, and all
the environment variables, is saved for the execu-
tion of the
batch job. In addition, two lsbatch environment
variables are
set before starting the batch job: BJOBID and
is set to the job ID of the job, as returned by
qsub command.
LSB_HOST is set to a string listing the names of
all the hosts
used by the batch job.
If the batch request is successfully submitted, and
the -z flag
has not been specified, then a unique job ID (a
positive
number) is printed together with the queue to which
the job has
been submitted. You can later use this job ID to
operate on
the job.
Batch queue names and characteristics are set up by the lsbatch
system
administrator. The command qstat produces a summary of the
supported
queues (see qstat(1)
).
lsbatch supports queue access restrictions. For each queue,
the access can
be either unrestricted or restricted. If access is
unrestricted, then any
request may enter the queue. If access is restricted, then a
request can
only enter the queue if the requester or the requester's group
has been
given access to that queue.
Use qstat(1) to determine who has access to a particular queue.
lsNQS (and lsbatch) supports many batch request resource limit
types that
can be applied to a batch request. The existence of configur-
able resource
limits allows an lsNQS user to set resource limits within which
his or her
request must execute.
The syntax used to specify a limit-value for one of the limit-
flags (-lx),
is quite flexible and describes values for three general limit
categories.
These three general categories respectively deal with time
limits and
file/memory size limits.
All the limit-flags expect a single limit-argument. If the
limit-argument
contains any whitespace character, which will cause it to be
passed to qsub
as multiple tokens, then it must be enclosed within double
quotes or
otherwise escaped such that it is passed a single, character-
string token.
This also applies to limit-arguments associated with limit-
flags embedded
within the batch request script file.
For finite CPU time limits, the limit-value is expressed in the
reasonably
obvious format:
[[hours :] minutes : ] seconds [.milliseconds]
Whitespace can appear anywhere between the principal tokens,
with the
exception that no whitespace can appear around the decimal
point. NOTE:
The milliseconds value is ignored. lsNQS only supports granu-
larity of 1
minute for time limit. Extressive parts of the time limit
smaller than 1
minute are truncated.
Example time limit-values are:
For the finite size limits the acceptable syntax is:
where the integer and fraction tokens represent strings of up
to eight
decimal digits, denoting the obvious values. In both cases,
the units of
allocation may also be specified as one of the case insensitive
strings:
In the absence of any units specification, the units of bytes
are assumed.
At the time, any size limit less than 1 Kbytes is truncated.
For all limit types, it is possible to state that no limit must
be applied.
This is done by specifying a limit-value of ``unlimited'' or
any initial
substring thereof. Whenever an infinite limit-value is speci-
fied for a
particular resource type, the batch request operates as though
no explicit
limits have been placed upon the corresponding resource, other
than by the
limitations of the physical hardware involved.
After each limit-value has been converted as described above,
each resulting
value is then silently truncated by the limit configured to
the destination
queue.
Those limits are soft limits for all processes belonging to
this batch
request. A corresponding signal is sent to the process by UNIX
when the
resource consumption has gone beyond the limit.
When a batch request is spawned, a new process-group is esta-
blished such
that all processes of the request exist in the same process-
group. If the
qdel(1)
command is used to send a signal to a batch request,
the signal is
sent to all processes of the request in the created process-
group.
However, if one or more processes of the request choose to suc-
cessfully
execute a setpgrp(2)
system call, such processes will not
receive any signals
sent by the qdel(1)
command. This can lead to ``rogue''
requests
whose constituent processes must be killed by other means such
as the
kill(1)
command.