qsub(1) CLIX qsub(1)
NAME
qsub - Submits an NQS batch request
SYNOPSIS
qsub [flag ... ] [script-file]
FLAGS
-a date-time Does not run the batch request until the specified date
and/or time.
If a date-time specification is composed of two or more
tokens separated by white space characters, the date-time
specification must be in double quotes as in: "-a July, 4,
2026 12:31-EDT". If not specified in double quotes, it
should be escaped so that the shell will interpret the
date-time specification as a single lexical token.
The syntax accepted for the date-time parameter is
flexible. Unspecified date and time values default to the
current date and time.
A date can be specified as a month and a day (current year
assumed). The year can also be explicitly specified. It
is also possible to specify the date as a weekday name (for
example, ``Tues''), or as one of the strings ``today'' or
``tomorrow.'' Weekday and month names can be abbreviated
by any three-character (or longer) prefix to the actual
name. An optional dot can follow an abbreviated month or
day name.
The time of day can be specified using a 24-hour clock or
``am'' and ``pm'' specifications. When a meridian is not
specified, a twenty-four hour clock is assumed. The time
of day specification is interpreted using the precise
meridian definitions. ``12am'' refers to the 24-hour clock
time of 0:00:00; ``12m'' refers to noon; and ``12-pm''
refers to 24:00:00. Alternatively, the phrases
``midnight'' and ``noon'' are accepted as time of day
specifications, where ``midnight'' refers to 24:00:00.
A timezone may also appear at any point in the date-time
specification. Thus, it is legal to say: "April 1, 1987
13:01-PDT". When a timezone is not specified, the local
timezone is assumed, with daylight savings time being
inferred when appropriate.
All alphabetic comparisons are not case-sensitive. Both
``WeD'' and ``weD'' refer to Wednesday.
2/94 - Intergraph Corporation 1
qsub(1) CLIX qsub(1)
Examples of valid date-time specifications are:
"01-Jan-1986 12am, PDT"
"Tuesday, 23:00:00"
"11pm tues."
"tomorrow 23-MST"
-mb Sends mail to the user on the originating machine when the
request begins execution. If -mu is also present, mail is
sent to the user specified by -mu instead of the invoking
user.
-me Sends mail to the invoking user on the originating machine
when the request has ended execution. If -mu is also
present, mail is sent to the user specified by -mu instead
of the invoking user.
-mu username Specifies that any mail concerning the request should be
delivered to the user username. Username has the form
user[@machine]. When this flag is not specified, any mail
concerning the request is sent to the invoker on the
originating machine.
-p priority Assigns an intraqueue priority to this request. The
specified priority must be an integer, and must be in the
range 0-63, inclusive. A value of 63 defines the highest
intraqueue request priority, while a value of 0 defines the
lowest. This priority does not determine the execution
priority of the request. This priority is only used to
determine the relative ordering of requests within a queue.
When a request is added to a queue, it is placed at a
specific position within the queue so that it appears ahead
of all existing requests with priorities less than the
priority of the new request. Similarly, all requests with
a higher priority remain ahead of the new request when the
queuing process is complete. When the priority of the new
request equals the priority of an existing request, the
existing request takes precedence over the new request.
If the user does not choose an intraqueue priority, the
value configured by the system administrator will be used.
If a value has not been configured by the system
administrator, a default value of 31 is assigned to the
request.
-q queue-name Specifies the queue to which the batch request is to be
submitted. If the -q queue-name specification is not
given, the user's environment is searched for the variable
QSUB_QUEUE. If this environment variable is found, the
2 Intergraph Corporation - 2/94
qsub(1) CLIX qsub(1)
character string value for QSUB_QUEUE is presumed to be the
name of the queue to which the request should be submitted.
If the QSUB_QUEUE environment variable is not found, the
request is submitted to the default batch queue if one has
been defined by the local system administrator. Otherwise,
the request cannot be queued and an appropriate error
message is displayed.
-r request-name
Assigns a name to this request. When -r is not specified,
the request-name defaults to script-file (leading pathname
removed). If a script-file is not specified, the default
request-name assigned to the request is stdin.
In all cases, if the request-name begins with a digit, the
character ``R'' is prefixed to prevent a request-name from
beginning with a digit. All request-names are truncated to
a maximum length of 15 characters.
-e [machine:] stderr-filename
Directs stderr output generated by the batch request to
stderr-filename on machine. If an explicit machine
destination is not specified, the destination machine
defaults to the machine where the batch request originated
or to the machine where the request will eventually be run,
depending on the absence or presence of -ke.
If a machine destination is not specified and the stderr-
filename does not begin with a ``/'', the current working
directory is prefixed to create a fully-qualified pathname,
if -ke is absent. In all other cases, any partial stderr-
filename is interpreted relative to the user's home
directory on the stderr destination machine. This flag
cannot be specified when -eo is present.
If -eo and -e are not specified, all stderr output for the
batch request is sent to the file whose name consists of
the first seven characters of the request name followed by
the characters ``.e'', followed by the sequence number
portion of the request-ID. Without -ke, the default stderr
output file will be placed in the directory where the
request was submitted on the originating machine.
Otherwise, the file will be placed in the user's home
directory on the execution machine.
-o [machine:] stdout-filename
Directs stdout output generated by the batch request to
stdout-filename on machine.
If an explicit machine destination is not specified, the
destination machine defaults to the machine where the batch
2/94 - Intergraph Corporation 3
qsub(1) CLIX qsub(1)
request originated or to the machine where the request will
eventually be run, depending on the absence or presence of
-ko.
If a machine destination is not specified and the stdout-
filename does not begin with a ``/'', the current working
directory is prefixed to create a fully-qualified pathname,
if -ko is absent. In all other cases, any partial stdout-
filename is interpreted relative to the user's home
directory on the stdout destination machine.
If -o is not specified, all stdout output for the batch
request is sent to the file whose name consists of the
first seven characters of the request name followed by the
characters ``.o'', followed by the sequence number portion
of the request-ID. If -ko is not specified, the default
stdout output file will be placed in the directory where
the request was submitted on the originating machine.
Otherwise, the file will be placed in the user's home
directory on the execution machine.
-eo Directs all output that would normally be sent to the
stderr file to the stdout file. This flag cannot be
specified when -e is present.
-ke In the absence of an explicit machine destination for the
stderr file produced by a batch request, the destination
chosen is the machine where the batch request originated.
The -ke flag, however, instructs NQS to leave any stderr
output file produced by the request on the machine where
the batch request was executed.
This flag is meaningless if -eo is specified and cannot be
specified if an explicit machine destination is given with
-e.
-ko In the absence of an explicit machine destination for the
stdout file produced by a batch request, the destination
chosen is the machine where the batch request originated.
The -ko flag, however, instructs NQS to leave any stdout
output file produced by the request on the machine where
the batch request was executed.
This flag cannot be specified if an explicit machine
destination is given with -o.
-ro, -re Normally, the stdout and stderr log files are kept
internally by NQS until the batch job ends. The files are
then returned to the intended directories. The -ro and -re
flags force the stdout and stderr log files to be sent to
the destination directories as the output is generated
4 Intergraph Corporation - 2/94
qsub(1) CLIX qsub(1)
during execution. These flags cannot be used if the
destination is a remote machine.
-lf file-size-limit
Sets a per-process file size limit for all processes that
constitute the running batch request. If any process in
the running request attempts to write to a file such that
the file size exceeds file-size-limit, that process is
terminated by a signal chosen by the underlying
implementation.
The format for file-size-limit is either .fraction[units]
or integer[.fraction][units] when the limit is a finite
limit. If an infinite limit is needed, the file-size-limit
may be specified as ``unlimited'' or any initial substring.
The integer and fraction portions of a finite limit may be
specified as strings of up to eight decimal digits. The
units may be specified as one of the following case-
insensitive strings.
b Bytes
w Words
kb Kilobytes (2^10 bytes)
kw Kilowords (2^10 words)
mb Megabytes (2^20 bytes)
mw Megawords (2^20 words)
gb Gigabytes (2^30 bytes)
gw Gigabytes (2^30 words)
When units are not specified, bytes are used. If the limit
is set to ``unlimited'', the only limitations imposed are
those of the physical hardware involved.
-ln nice-value Sets a nice value for all processes run from this batch
request. A nice value determines the execution-time
priority of a process relative to all other processes in
the system. By letting the user set a nice value, all
processes in the running request will receive CPU resources
less often.
Ascending nice values cause the relative execution priority
of a process to decrease while descending nice values cause
the relative priority to increase. Thus, -ln -10 has a
lower execution priority than -ln 1.
2/94 - Intergraph Corporation 5
qsub(1) CLIX qsub(1)
The nice-value must be acceptable to the batch queue in
which the request is ultimately placed.
-nr Upon system reboot NQS will automatically restart any
request that was running at the time of shutdown. The -nr
flag will disable restart of a request that was running.
Requests that were not running are always preserved.
-s shell-name Specifies the absolute pathname for the shell that will
interpret the batch request script. This flag
unconditionally overrides any shell strategy configured on
the execution machine. When this flag is not specified,
the NQS system on the execution machine will use one of
three shell strategies, fixed, free, or login (see
qlimit(1) for a description of the shell strategies), to
determine the shell that will be used.
-si[l] [destination_filename=] [machine:] source_filename
Stages-in (moves) a file before executing. The file
source_filename on machine is copied to the file
destination_filename on the executing machine before the
request is executed.
If machine is not specified, it defaults to the machine on
which the request originated. If destination_filename is
not specified, source_filename and destination_filename are
assumed to be the same. If full pathnames are not
specified, the appropriate home directory is used.
Staging-in of files is done just before a request is
executed. If any stage-in event fails, the request is
aborted and the originator is notified. If the l flag is
not specified, destination_filename will be removed after
the request has completed.
Note: this flag only works between servers. Client-only
installations cannot use this staging flag.
-so [machine:]destination_filename[=source_filename]
Stages-out (moves) a file after execution. The file
source_filename on the executing machine is copied to
destination_filename on machine after the request is
finished executing.
If machine is not specified, it defaults to the machine on
which the request originated. If source_filename is not
specified, destination_filename and source_filename are
assumed to be the same. If full pathnames are not used,
the appropriate home directory is assumed.
Staging-out of files is done just after the request has
6 Intergraph Corporation - 2/94
qsub(1) CLIX qsub(1)
finished executing, but before the staged-in files are
removed. Thus it is possible to stage-out a file which has
been staged-in. If a stage-out event fails, the originator
is notified through mail.
Note: this flag only works between servers. Client-only
installations cannot use this staging flag.
-x When a batch request is submitted, this flag automatically
exports the current values of the following environment
variables: HOME, SHELL, PATH, LOGNAME, MAIL, and TZ. When
the batch request is spawned, these variables are re-
created as the environment variables QSUB_HOME, QSUB_SHELL,
QSUB_PATH, QSUB_LOGNAME, QSUB_MAIL, and QSUB_TZ,
respectively. If -x is specified, all remaining
environment variables, with names that do not conflict with
the automatically-exported variables, are also exported.
When the batch request is spawned, these additional
variables are re-created with the same name.
-z Submits the batch request silently. If the request is
submitted successfully, messages are not displayed
indicating this fact. Error messages will always be
displayed.
DESCRIPTION
The qsub command submits a batch request to the Network Queuing System
(NQS). If a script-file is not specified, qsub reads from stdin. All
script-files are spooled so that later changes will not affect previously
queued batch requests.
NQS has queue access restrictions. For each queue with a queue type other
than ``network,'' access may be either ``unrestricted'' or ``restricted.''
If access is ``unrestricted,'' any request may enter the queue. If access
is ``restricted,'' a request can only enter the queue if the requester or
the requester's login group has access to that queue (see qmgr(1)).
Requests submitted by the superuser are an exception; they are always
queued, even if the superuser has not explicitly been given access. The
qstat command may be used to determine who has access to a particular
queue.
The qpr command displays a request-ID to stdout, upon the successful
queuing of a request. This request-ID can be compared with information
reported by qdev and qstat to learn what happened to a request. It can
also be given as an argument to qdel to delete a request. A request-ID
has the form seqno.hostname where seqno refers to the sequence number
assigned to the NQS request, and hostname refers to the name of
originating machine. This identifier is used throughout NQS to uniquely
identify the request anywhere in the network.
2/94 - Intergraph Corporation 7
qsub(1) CLIX qsub(1)
All of the command line flags can also be specified within the first
comment block in the batch request script-file as embedded default flags.
Such flags appearing in the batch request script-file set default
characteristics for the batch request. If the same flag is specified on
the command line, the command line flag (and any associated value) takes
precedence over the embedded flag. The algorithm used to scan for
embedded default flags is as follows:
1. Read the first line of the script-file.
2. If the current line contains only white space characters, or the first
nonwhite space character of the line is colon (:), go to step 7.
3. If the first nonwhite space character of the current line is not a
pound symbol (#), go to step 8.
4. If the second nonwhite space character in the current line is not an
at symbol (@) or the character immediately following the second
nonwhite space character in the current line is not a dollar symbol
($), go to step 7.
5. If a hyphen (-) is not the character immediately following the @$
sequence, go to step 8.
6. Process the embedded flag, stop the parsing process when the end of
the line or the first unquoted # character is reached.
7. Read the next line of the script-file. Go to step 2.
8. End. Embedded flags will no longer be recognized.
The following is an example of using embedded flags within a script-file.
#
# Batch request script example:
#
# @$-a "11:30pm EDT"
# # Run request after 11:30 EDT by default,
# @$-mb -me # Send mail at beginning and end of
# # request execution.
# @$-q batch1 # Submit request to queue, batch1 by
# # default.
# @$ # No more embedded flags.
#
make all
The following sequence of events takes place when an NQS batch request is
spawned:
1. The process that will head the process group for all processes
composing the batch request is created by NQS.
8 Intergraph Corporation - 2/94
qsub(1) CLIX qsub(1)
2. Resource limits are enforced.
3. The real and effective group IDs of the process are set to the group
ID as defined in the password file on the originating machine of the
request owner.
4. The real and effective user IDs of the process are set to the real
user ID of the batch request owner.
5. The user file creation mask is set to the value that the user had on
the originating machine when the batch request was submitted.
6. The shell with which to execute the batch request script is chosen.
7. The environment variables HOME, SHELL, PATH, LOGNAME, and MAIL are set
from the user's password file entry as though the user had logged
directly into the execution machine.
8. The environment string: ENVIRONMENT=BATCH is added to the environment
so that shell scripts (and the user's .profile (Bourne shell) or
.cshrc and .login (C-shell) scripts) can test for batch request
execution when appropriate and not set any terminal characteristics,
since a batch request is not connected to a terminal.
9. The environment variables QSUB_WORKDIR, QSUB_HOST, QSUB_REQNAME, and
QSUB_REQID are added to the environment. These environment variables
equal the respective strings of the working directory when the request
was submitted, the name of the originating host, the name of the
request, and the ID of the request.
10. All remaining environment variables saved for re-creation when the
batch request is spawned are added at this point to the environment.
11. The current working directory is then set to the user's home directory
on the execution machine and the chosen shell is execed. If the
Bourne shell is chosen, the .profile file is read. If the C-shell is
chosen, the .cshrc and .login scripts are read. The batch request is
then executed with the environment as constructed in the steps
outlined above.
EXAMPLES
1. The following command submits a batch job for the shell script test.sh
to run after noon on queue sysbatch.
qsub -a noon -me -mb -q sysbatch test.sh
Mail will be sent when the job begins and ends.
2. The following command submits a job called Batchjob to the default
batch queue defined for the local system.
2/94 - Intergraph Corporation 9
qsub(1) CLIX qsub(1)
cat test.sh | qsub -p 50 -r Batchjob -nr
The scheduling priority of the job is 50, and the job is
nonrestartable. Note that the shell script is taken from stdin.
3. The following command submits test.sh to the default batch queue.
qsub -s /bin/sh -ln 10 test.sh
The script is run with the /bin/sh shell, and has a nice value of 10.
4. The following command submits test.sh to the default batch queue.
This command also moves the in.dat file from the submitters' home
directory on mymachine to the file datain in the batch job's working
directory on the execution machine before the job is executed.
qsub -sil datain=mymachine:in.dat -so mymachine:out.dat=dataout test.sh
After the job has ended, the file dataout is moved to the file out.dat
on mymachine. The staged-in file is not removed from the executing
machine.
NOTES
When an NQS batch request is spawned, a new process group is established
so that all processes of the request exist in the same process group. If
the qdel command is used to send a signal to an NQS 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 successfully
executes a setpgrp() call, the processes will not receive signals sent by
the qdel command. The kill command may be used to delete such processes.
All processes of an NQS request should catch SIGTERM signals. By default,
the receipt of a SIGTERM signal causes the receiving process to die. NQS
sends a SIGTERM signal to all processes in the established process group
for a batch request as a notification that the request should be prepared
to be killed.
The spawned shell ignores SIGTERM signals. If an immediate child of the
shell does not ignore or catch SIGTERM signals, it will be killed by the
SIGTERM signal and the shell will proceed to execute the next command from
the script (if there is one). In any case, the shell will not be killed
by the SIGTERM signal, though the executing command will have been killed.
After receiving a SIGTERM signal delivered from NQS, a process of a batch
request typically has 60 seconds before receiving a SIGKILL signal.
A method of echoing commands executed by the Bourne shell and C-shell are
not available. While the C-shell can be spawned so that it echoes the
commands it executes, it is often difficult to distinguish an echoed
command from output produced by the batch request because a magic
10 Intergraph Corporation - 2/94
qsub(1) CLIX qsub(1)
character such as a $ is not displayed in front of the echoed command.
The Bourne shell does not support any echo option. Thus, one of the
better ways to write the shell script for a batch request is to place
lines in the shell script of the form:
echo "explanatory-message"
CAUTIONS
Network queues have not yet been implemented.
In this implementation, it is not possible to see the stderr or stdout
files produced by the batch request while the request is running unless
the -re and -ro flags have been specified, respectively.
DIAGNOSTICS
Most of the diagnostic messages are self-explanatory. The following
messages are some of the most common:
The -a flag was given twice:
Multiple request start-after time specifications
The time and date argument for the -a flag could not be deciphered:
Invalid date/time syntax.
No -q flag was given, and there was no default print queue defined for
NQS.
No request queue specified, and no local default has been defined.
An internal or NQS error occurred. Seek help from the NQS manager or the
system administrator.
Seek help from system support personnel.
EXIT VALUES
The qsub command exits with a value of 0 if successful. If unsuccessful,
qsub exits with a value of 1.
RELATED INFORMATION
Commands: qdel(1), qdev(1), qlimit(1), qpr(1), qstat(1), qmgr(8), mail(1),
vqmgr(1), nice(1)
Functions: setpgrp(2), signal(2), kill(2)
2/94 - Intergraph Corporation 11