4
<!-- Manpage converted by man2html 3.0.1 -->
6
qsub - submit a batch job to Grid Engine.
8
qsh - submit an interactive X-windows session to Grid
11
qlogin - submit an interactive login session to Grid
14
qrsh - submit an interactive rsh session to Grid Engine.
16
qalter - modify a pending batch job of Grid Engine.
18
qresub - submit a copy of an existing Grid Engine job.
21
qsub [ options ] [ command | -- [ command_args ]]
23
qsh [ options ] [ -- xterm_args ]
27
qrsh [ options ] [ command [ command_args ]]
29
qalter [ options ] wc_job_range_list [ -- [ command_args ]]
31
qalter [ options ] -u user_list | -uall [ -- [ command_args
34
qresub [ options ] job_id_list
37
<I>Qsub</I> submits batch jobs to the Grid Engine queuing system.
38
Grid Engine supports single- and multiple-node jobs. Command
39
can be a path to a binary or a script (see -b below) which
40
contains the commands to be run by the job using a shell
41
(for example, <B><A HREF="../htmlman1/sh.html">sh(1)</A></B> or <B><A HREF="../htmlman1/csh.html">csh(1)</A></B>). Arguments to the command
42
are given as command_args to <I>qsub</I> . If command is handled as
43
a script then it is possible to embed flags in the script.
44
If the first two characters of a script line either match
45
'#$' or are equal to the prefix string defined with the -C
46
option described below, the line is parsed for embedded com-
49
<I>Qsh</I> submits an interactive X-windows session to Grid Engine.
50
An <B><A HREF="../htmlman1/xterm.html">xterm(1)</A></B> is brought up from the executing machine with
51
the display directed either to the X-server indicated by the
52
DISPLAY environment variable or as specified with the
53
-<I>display</I> <I>qsh</I> option. Interactive jobs are not spooled if no
54
resource is available to execute them. They are either
55
dispatched to a suitable machine for execution immediately
56
or the user submitting the job is notified by <I>qsh</I> that
57
appropriate resources to execute the job are not available.
58
xterm_args are passed to the <B><A HREF="../htmlman1/xterm.html">xterm(1)</A></B> executable. Note,
59
however, that the -<I>e</I> and -<I>ls</I> xterm options do not work with
62
<I>Qlogin</I> is similar to <I>qsh</I> in that it submits an interactive
63
job to the queueing system. It does not open an <B><A HREF="../htmlman1/xterm.html">xterm(1)</A></B>
64
window on the X display, but uses the current terminal for
65
user I/O. Usually, <I>qlogin</I> establishes a <B><A HREF="../htmlman1/telnet.html">telnet(1)</A></B> connection
66
with the remote host, using standard client- and server-side
67
commands. These commands can be configured with the
68
qlogin_daemon (server-side, Grid Engine <I>telnetd</I> if not set,
69
otherwise something like /usr/sbin/in.telnetd) and
70
qlogin_command (client-side, Grid Engine <I>telnet</I> if not set,
71
otherwise something like /usr/bin/telnet) parameters in the
72
global and local configuration settings of <B><A HREF="../htmlman5/sge_conf.html">sge_conf(5)</A></B>. The
73
client side command is automatically parameterized with the
74
remote host name and port number to which to connect,
75
resulting in an invocation like
77
/usr/bin/telnet my_exec_host 2442
79
for example. <I>Qlogin</I> is invoked exactly like <I>qsh</I> and its
80
jobs can only run on INTERACTIVE queues. <I>Qlogin</I> jobs can
81
only be used if the <B><A HREF="../htmlman8/sge_execd.html">sge_execd(8)</A></B> is running under the root
84
<I>Qrsh</I> is similar to <I>qlogin</I> in that it submits an interactive
85
job to the queuing system. It uses the current terminal for
86
user I/O. Usually, <I>qrsh</I> establishes a <B><A HREF="../htmlman1/rsh.html">rsh(1)</A></B> connection with
87
the remote host. If no command is given to <I>qrsh</I>, an <I>rlo-</I>
88
<B><A HREF="../htmlman1/gin.html">gin(1)</A></B> session is established. The server-side commands
89
used can be configured with the rsh_daemon and rlogin_daemon
90
parameters in the global and local configuration settings of
91
<B><A HREF="../htmlman5/sge_conf.html">sge_conf(5)</A></B>. An Grid Engine <I>rshd</I> or <I>rlogind</I> is used if the
92
parameters are not set. If the parameters are set, they
93
should be set to something like /usr/sbin/in.rshd or
94
/usr/sbin/in.rlogind. On the client-side, the rsh_command
95
and rlogin_command parameters can be set in the global and
96
local configuration settings of <B><A HREF="../htmlman5/sge_conf.html">sge_conf(5)</A></B>. If they are
97
not set, special Grid Engine <B><A HREF="../htmlman1/rsh.html">rsh(1)</A></B> and <B><A HREF="../htmlman1/rlogin.html">rlogin(1)</A></B> binaries
98
delivered with Grid Engine are used. Use the cluster confi-
99
guration parameters to integrate mechanisms like <I>ssh</I> or the
100
<B><A HREF="../htmlman1/rsh.html">rsh(1)</A></B> and <B><A HREF="../htmlman1/rlogin.html">rlogin(1)</A></B> facilities supplied with the operating
103
<I>Qrsh</I> jobs can only run in INTERACTIVE queues unless the
104
option -now no is used (see below). They can also only be
105
run, if the <B><A HREF="../htmlman8/sge_execd.html">sge_execd(8)</A></B> is running under the root account.
107
<I>Qrsh</I> provides an additional useful feature for integrating
108
with interactive tools providing a specific command shell.
109
If the environment variable QRSH_WRAPPER is set when <I>qrsh</I> is
110
invoked, the command interpreter pointed to by QRSH_WRAPPER
111
will be executed to run <I>qrsh</I> commands instead of the users
112
login shell or any shell specified in the <I>qrsh</I> command-line.
114
<I>Qalter</I> can be used to change the attributes of pending jobs.
115
For array jobs with a mix of running and pending tasks (see
116
the -t option below), modification with <I>qalter</I> only affects
117
the pending tasks. <I>Qalter</I> can change most of the charac-
118
teristics of a job (see the corresponding statements in the
119
OPTIONS section below), including those which were defined
120
as embedded flags in the script file (see above). Some sub-
121
mit options, such as the job script, cannot be changed with
124
<I>Qresub</I> allows the user to create jobs as copies of existing
125
pending or running jobs. The copied jobs will have exactly
126
the same attributes as the ones from which they were copied,
127
except with a new job ID. The only modification to the
128
copied jobs supported by <I>qresub</I> is assignment of a hold
129
state with the -h option. This option can be used to first
130
copy a job and then change its attributes via <I>qalter</I>.
132
Only a manager can use <I>qresub</I> on jobs submitted by another
133
user. Regular users can only use <I>qresub</I> on their own jobs.
135
For <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, and <I>qlogin</I> the administrator and the
136
user may define default request files (see <B><A HREF="../htmlman5/sge_request.html">sge_request(5)</A></B>)
137
which can contain any of the options described below. If an
138
option in a default request file is understood by <I>qsub</I> and
139
<I>qlogin</I> but not by <I>qsh</I> the option is silently ignored if <I>qsh</I>
140
is invoked. Thus you can maintain shared default request
141
files for both <I>qsub</I> and <I>qsh</I>.
143
A cluster wide default request file may be placed under
144
$SGE_ROOT/$SGE_CELL/common/sge_request. User private
145
default request files are processed under the locations
146
$HOME/.sge_request and $cwd/.sge_request. The working direc-
147
tory local default request file has the highest precedence,
148
then the home directory located file and then the cluster
149
global file. The option arguments, the embedded script
150
flags and the options in the default request files are pro-
151
cessed in the following order:
153
left to right in the script line,
154
left to right in the default request files,
155
from top to bottom of the script file (<I>qsub</I> only),
156
from top to bottom of default request files,
157
from left to right of the command line.
159
In other words, the command line can be used to override the
160
embedded flags and the default request settings. The
161
embedded flags, however, will override the default settings.
163
Note, that the -<I>clear</I> option can be used to discard any pre-
164
vious settings at any time in a default request file, in the
165
embedded script flags, or in a command-line option. It is,
166
however, not available with <I>qalter</I>.
168
The options described below can be requested either hard or
169
soft. By default, all requests are considered hard until
170
the -soft option (see below) is encountered. The hard/soft
171
status remains in effect until its counterpart is encoun-
172
tered again. If all the hard requests for a job cannot be
173
met, the job will not be scheduled. Jobs which cannot be
174
run at the present time remain spooled.
178
Forces <I>qsub</I>, <I>qrsh</I>, <I>qsh</I>, or <I>qlogin</I> to use the options
179
contained in optionfile. The indicated file may contain
180
all valid options. Comment lines must start with a "#"
184
Available for <I>qsub</I> and <I>qalter</I> only.
186
Defines or redefines the time and date at which a job
187
is eligible for execution. Date_time conforms to
188
[[CC]]YY]MMDDhhmm.[ss], where:
190
CC denotes the century in 2 digits.
191
YY denotes the year in 2 digits.
192
MM denotes the month in 2 digits.
193
DD denotes the day in 2 digits.
194
hh denotes the hour in 2 digits.
195
mm denotes the minute in 2 digits.
196
ss denotes the seconds in 2 digits (default 00).
198
If any of the optional date fields is omitted, the
199
corresponding value of the current date is assumed. If
200
CC is not specified, a YY of < 70 means 20YY.
201
Usage of this option may cause unexpected results if
202
the clocks of the hosts in the Grid Engine pool are out
203
of sync. Also, the proper behavior of this option very
204
much depends on the correct setting of the appropriate
205
timezone, e.g. in the TZ environment variable (see
206
<B><A HREF="../htmlman1/date.html">date(1)</A></B> for details), when the Grid Engine daemons
207
<B><A HREF="../htmlman8/sge_qmaster.html">sge_qmaster(8)</A></B> and <B><A HREF="../htmlman8/sge_execd.html">sge_execd(8)</A></B> are invoked.
209
<I>Qalter</I> allows changing this option even while the job
210
executes. The modified parameter will only be in effect
211
after a restart or migration of the job, however.
213
-ac variable[=value],...
214
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
216
Adds the given name/value pair(s) to the job's context.
217
Value may be omitted. Grid Engine appends the given
218
argument to the list of context variables for the job.
219
Multiple -ac, -dc, and -sc options may be given. The
220
order is important here.
222
<I>Qalter</I> allows changing this option even while the job
226
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
228
Identifies the account to which the resource consump-
229
tion of the job should be charged. The account_string
230
may be any arbitrary ASCII alphanumeric string but may
231
not contain "\n", "\t", "\r", "/", ":", "@", "\", "*",
232
or "?". In the absence of this parameter Grid Engine
233
will place the default account string "sge" in the
234
accounting record of the job.
236
<I>Qalter</I> allows changing this option even while the job
240
Available for <I>qsub</I>, <I>qrsh</I> only. <I>Qalter</I> does not allow
241
changing this option. This option cannot be embedded in
242
the script file itself.
244
Gives the user the possibility to indicate explicitly
245
whether command should be treated as binary or script.
246
If the value of -b is 'y', then command may be a
247
binary or script. The command might not be accessible
248
from the submission host. Nothing except the path of
249
the command will be transferred from the submission
250
host to the execution host. Path aliasing will be
251
applied to the path of command before command will be
254
If the value of -b is 'n' then command needs to be a
255
script and it will be handled as script. The script
256
file has to be accessible by the submission host. It
257
will be transferred to the execution host. <I>qsub</I>/<I>qrsh</I>
258
will search directive prefixes within script.
260
<I>qsub</I> will implicitly use -b n whereas <I>qrsh</I> will apply
261
the -b y option if nothing else is specified.
263
-c occasion_specifier
264
Available for <I>qsub</I> and <I>qalter</I> only.
265
Defines or redefines whether the job should be check-
266
pointed, and if so, under what circumstances. The
267
specification of the checkpointing occasions with this
268
option overwrites the definitions of the <I>when</I> parameter
269
in the checkpointing environment (see <B><A HREF="../htmlman5/checkpoint.html">checkpoint(5)</A></B>)
270
referenced by the <I>qsub</I> -<I>ckpt</I> switch. Possible values
271
for occasion_specifier are
273
n no checkpoint is performed.
274
s checkpoint when batch server is shut down.
275
m checkpoint at minimum CPU interval.
276
x checkpoint when job gets suspended.
277
<interval> checkpoint in the specified time interval.
279
The minimum CPU interval is defined in the queue confi-
280
guration (see <B><A HREF="../htmlman5/queue_conf.html">queue_conf(5)</A></B> for details). <interval>
281
has to be specified in the format hh:mm:ss. The max-
282
imum of <interval> and the queue's minimum CPU interval
283
is used if <interval> is specified. This is done to
284
ensure that a machine is not overloaded by checkpoints
285
being generated too frequently.
288
Available for <I>qsub</I> and <I>qalter</I> only.
290
Selects the checkpointing environment (see <I>check-</I>
291
<B><A HREF="../htmlman5/point.html">point(5)</A></B>) to be used for checkpointing the job. Also
292
declares the job to be a checkpointing job.
295
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, and <I>qlogin</I> only.
297
Causes all elements of the job to be reset to the ini-
298
tial default status prior to applying any modifications
299
(if any) appearing in this specific command.
301
-cwd Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I> and <I>qalter</I> only.
303
Execute the job from the current working directory.
304
This switch will activate Grid Engine's path aliasing
305
facility, if the corresponding configuration files are
306
present (see <B><A HREF="../htmlman5/sge_aliases.html">sge_aliases(5)</A></B>).
308
In the case of <I>qalter</I>, the previous definition of the
309
current working directory will be overwritten if <I>qalter</I>
310
is executed from a different directory than the preced-
311
ing <I>qsub</I> or <I>qalter</I>.
313
<I>Qalter</I> allows changing this option even while the job
314
executes. The modified parameter will only be in effect
315
after a restart or migration of the job, however.
318
Available for <I>qsub</I> and qrsh with script submission (-b
321
<I>Prefix</I>_<I>string</I> defines the prefix that declares a direc-
322
tive in the job's command. The prefix is not a job
323
attribute, but affects the behavior of <I>qsub</I> and <I>qrsh</I>.
324
If prefix is a null string, the command will not be
325
scanned for embedded directives.
326
The directive prefix consists of two ASCII characters
327
which, when appearing in the first two bytes of a
328
script line, indicate that what follows is an Grid
329
Engine command. The default is "#$".
330
The user should be aware that changing the first delim-
331
iting character can produce unforeseen side effects. If
332
the script file contains anything other than a "#"
333
character in the first byte position of the line, the
334
shell processor for the job will reject the line and
335
may exit the job prematurely.
336
If the -C option is present in the script file, it is
340
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
342
Removes the given variable(s) from the job's context.
343
Multiple -ac, -dc, and -sc options may be given. The
346
<I>Qalter</I> allows changing this option even while the job
349
-display display_specifier
350
Available for <I>qsh</I> only.
352
Directs <B><A HREF="../htmlman1/xterm.html">xterm(1)</A></B> to use display_specifier in order to
353
contact the X server. The display_specifier has to
354
contain the hostname part of the display name (e.g.
355
myhost:1). Local display names (e.g. :0) cannot be used
356
in grid environments. Values set with the -display
357
option overwrite settings from the submission environ-
358
ment and from -v command line options.
361
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
363
Specifies the deadline initiation time in
364
[[CC]YY]MMDDhhmm[.SS] format (see -a option above). The
365
deadline initiation time is the time at which a dead-
366
line job has to reach top priority to be able to com-
367
plete within a given deadline. Before the deadline ini-
368
tiation time the priority of a deadline job will be
369
raised steadily until it reaches the maximum as config-
370
ured by the Grid Engine administrator.
371
This option is applicable only for users allowed to
372
submit deadline jobs.
374
-e [[hostname]:]path,...
375
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
377
Defines or redefines the path used for the standard
378
error stream of the job. For <I>qsh</I>, <I>qrsh</I> and <I>qlogin</I> only
379
the standard error stream of prolog and epilog is
380
redirected. If the path constitutes an absolute path
381
name, the error-path attribute of the job is set to
382
path, including the hostname. If the path name is rela-
383
tive, Grid Engine expands path either with the current
384
working directory path (if the -cwd switch (see above)
385
is also specified) or with the home directory path. If
386
hostname is present, the standard error stream will be
387
placed in the corresponding location only if the job
388
runs on the specified host. If the path contains a ":"
389
without a hostname, a leading ":" has to be specified.
391
By default the file name for interactive jobs is
392
/<I>dev</I>/<I>null</I>. For batch jobs the default file name has the
393
form <I>job</I>_<I>name</I>.e<I>job</I>_<I>id</I> and <I>job</I>_<I>name</I>.e<I>job</I>_<I>id</I>.task_id for
394
array job tasks (see -t option below).
396
If path is a directory, the standard error stream of
397
the job will be put in this directory under the default
398
file name. If the pathname contains certain pseudo
399
environment variables, their value will be expanded at
400
runtime of the job and will be used to constitute the
401
standard error stream path name. The following pseudo
402
environment variables are supported currently:
404
$HOME home directory on execution machine
405
$USER user ID of job owner
406
$JOB_ID current job ID
407
$JOB_NAME current job name (see -N option)
408
$HOSTNAME name of the execution host
409
$TASK_ID array job task index number
411
Alternatively to $HOME the tilde sign "~" can be used
412
as common in <B><A HREF="../htmlman1/csh.html">csh(1)</A></B> or <B><A HREF="../htmlman1/ksh.html">ksh(1)</A></B>. Note, that the "~" sign
413
also works in combination with user names, so that
414
"~<user>" expands to the home directory of <user>.
415
Using another user ID than that of the job owner
416
requires corresponding permissions, of course.
418
<I>Qalter</I> allows changing this option even while the job
419
executes. The modified parameter will only be in effect
420
after a restart or migration of the job, however.
423
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
425
Signifies that all resource requirements following in
426
the command line will be hard requirements and must be
427
satisfied in full before a job can be scheduled.
428
As Grid Engine scans the command line and script file
429
for Grid Engine options and parameters it builds a list
430
of resources required by a job. All such resource
431
requests are considered as absolutely essential for the
432
job to commence. If the -soft option (see below) is
433
encountered during the scan then all following
434
resources are designated as "soft requirements" for
435
execution, or "nice-to-have, but not essential". If the
436
-hard flag is encountered at a later stage of the scan,
437
all resource requests following it once again become
438
"essential". The -hard and -soft options in effect act
439
as "toggles" during the scan.
441
-h | -h {u|s|o|n|U|O|S}...
442
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I>, <I>qalter</I> and
445
List of holds to place on a job, a task or some tasks
448
`u' denotes a user hold.
449
`s' denotes a system hold.
450
`o' denotes a operator hold.
453
As long as any hold other than `n' is assigned to the
454
job the job is not eligible for execution. Holds can be
455
released via <I>qalter</I> and <B><A HREF="../htmlman1/qrls.html">qrls(1)</A></B>. In case of <I>qalter</I>
456
this is supported by the following additional option
457
specifiers for the -h switch:
459
`U' removes a user hold.
460
`S' removes a system hold.
461
`O' removes a operator hold.
463
Grid Engine managers can assign and remove all hold
464
types, Grid Engine operators can assign and remove user
465
and operator holds, and users can only assign or remove
468
In the case of <I>qsub</I> only user holds can be placed on a
469
job and thus only the first form of the option with the
470
-h switch alone is allowed. As opposed to this, <I>qalter</I>
471
requires the second form described above.
473
An alternate means to assign hold is provided by the
474
<B><A HREF="../htmlman1/qhold.html">qhold(1)</A></B> facility.
476
If the job is a array job (see the -t option below),
477
all tasks specified via -t are affected by the -h
478
operation simultaneously.
480
<I>Qalter</I> allows changing this option even while the job
481
executes. The modified parameter will only be in effect
482
after a restart or migration of the job, however.
485
Prints a listing of all options.
487
-hold_jid wc_job_list
488
Available for <I>qsub</I>, <I>qrsh</I>, and <I>qalter</I> only. See
489
<B><A HREF="../htmlman1/sge_types.html">sge_types(1)</A></B>. for 528.sp 1 Defines or redefines the
490
job dependency list of the submitted job. A reference
491
by job name or pattern is only accepted if the refer-
492
enced job is owned by the same user as the referring
493
job. The submitted job is not eligible for execution
494
unless all jobs referenced in the comma-separated job
495
id and/or job name list have completed. If any of the
496
referenced jobs exits with exit code 100, the submitted
497
job will remain ineligible for execution.
499
With the help of job names or regular pattern one can
500
specify a job dependency on multiple jobs satisfying
501
the regular pattern or on all jobs with the requested
502
name. The name dependencies are resolved at submit time
503
and can only be changed via qalter. New jobs or name
504
changes of other jobs will not be taken into account.
506
<I>Qalter</I> allows changing this option even while the job
507
executes. The modified parameter will only be in effect
508
after a restart or migration of the job, however.
510
-i [[hostname]:]file,...
511
Available for <I>qsub</I>, and <I>qalter</I> only.
513
Defines or redefines the file used for the standard
514
input stream of the job. If the <I>file</I> constitutes an
515
absolute filename, the input-path attribute of the job
516
is set to path, including the hostname. If the path
517
name is relative, Grid Engine expands path either with
518
the current working directory path (if the -cwd switch
519
(see above) is also specified) or with the home direc-
520
tory path. If hostname is present, the standard input
521
stream will be placed in the corresponding location
522
only if the job runs on the specified host. If the path
523
contains a ":" without a hostname, a leading ":" has to
526
By default /dev/null is the input stream for the job.
528
It is possible to use certain pseudo variables, whose
529
values will be expanded at runtime of the job and will
530
be used to express the standard input stream as
531
described in the -<I>e</I> option for the standard error
534
<I>Qalter</I> allows changing this option even while the job
535
executes. The modified parameter will only be in effect
536
after a restart or migration of the job, however.
539
Available only for <I>qrsh</I> and <B><A HREF="../htmlman1/qmake.html">qmake(1)</A></B>.
541
<I>qrsh</I> allows the user to start a task in an already
542
scheduled parallel job. The option -inherit tells <I>qrsh</I>
543
to read a job id from the environment variable JOB_ID
544
and start the specified command as a task in this job.
545
Please note that in this case, the hostname of the host
546
where the command will be executed must precede the
547
command to execute; the syntax changes to
549
qrsh -inherit [ other options ] hostname command [
552
Note also, that in combination with -inherit, most
553
other command line options will be ignored. Only the
554
options -verbose, -v and -V will be interpreted. As a
555
replacement to option -cwd please use -v PWD.
557
Usually a task should have the same environment
558
(including the current working directory) as the
559
corresponding job, so specifying the option -V should
560
be suitable for most applications.
562
<I>Note</I>: If in your system the qmaster tcp port is not
563
configured as a service, but rather via the environment
564
variable SGE_QMASTER_PORT, make sure that this variable
565
is set in the environment when calling <I>qrsh</I> or <I>qmake</I>
566
with the -inherit option. If you call <I>qrsh</I> or <I>qmake</I>
567
with the -inherit option from within a job script,
568
export SGE_QMASTER_PORT with the option "-v
569
SGE_QMASTER_PORT" either as a command argument or an
573
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
575
Specifies whether or not the standard error stream of
576
the job is merged into the standard output stream.
577
If both the -j y and the -e options are present, Grid
578
Engine sets but ignores the error-path attribute.
580
<I>Qalter</I> allows changing this option even while the job
581
executes. The modified parameter will only be in effect
582
after a restart or migration of the job, however.
585
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
587
Defines or redefines the job share of the job relative
588
to other jobs. Job share is an unsigned integer value.
589
The default job share value for jobs is 0.
591
The job share influences the Share Tree Policy and the
592
Functional Policy. It has no effect on the Urgency and
593
Override Policies (see <B><A HREF="../htmlman5/share_tree.html">share_tree(5)</A></B>, <B><A HREF="../htmlman5/sched_conf.html">sched_conf(5)</A></B> and
594
the <I>Grid</I> <I>Engine</I> <I>Installation</I> <I>and</I> <I>Administration</I> <I>Guide</I>
595
for further information on the resource management pol-
596
icies supported by Grid Engine).
598
In case of the Share Tree Policy, users can distribute
599
the tickets to which they are currently entitled among
600
their jobs using different shares assigned via -js. If
601
all jobs have the same job share value, the tickets are
602
distributed evenly. Otherwise, jobs receive tickets
603
relative to the different job shares. Job shares are
604
treated like an additional level in the share tree in
607
In connection with the Functional Policy, the job share
608
can be used to weight jobs within the functional job
609
category. Tickets are distributed relative to any
610
uneven job share distribution treated as a virtual
611
share distribution level underneath the functional job
614
If both the Share Tree and the Functional Policy are
615
active, the job shares will have an effect in both pol-
616
icies, and the tickets independently derived in each of
617
them are added to the total number of tickets for each
620
-l resource=value,...
621
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
623
Launch the job in a Grid Engine queue meeting the given
624
resource request list. In case of <I>qalter</I> the previous
625
definition is replaced by the specified one.
626
<B><A HREF="../htmlman5/complex.html">complex(5)</A></B> describes how a list of available resources
627
and their associated valid value specifiers can be
629
There may be multiple -l switches in a single command.
630
You may request multiple -l options to be soft or hard
631
both in the same command line. In case of a serial job
632
multiple -l switches refine the definition for the
635
<I>Qalter</I> allows changing this option even while the job
636
executes. The modified parameter will only be in effect
637
after a restart or migration of the job, however.
640
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
642
Defines or redefines under which circumstances mail is
643
to be sent to the job owner or to the users defined
644
with the -M option described below. The option argu-
645
ments have the following meaning:
647
`b' Mail is sent at the beginning of the job.
648
`e' Mail is sent at the end of the job.
649
`a' Mail is sent when the job is aborted or
651
`s' Mail is sent when the job is suspended.
654
Currently no mail is sent when a job is suspended.
656
<I>Qalter</I> allows changing the b, e, and a option arguments
657
even while the job executes. The modification of the b
658
option argument will only be in effect after a restart
659
or migration of the job, however.
662
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
664
Defines or redefines the list of users to which the
665
server that executes the job has to send mail, if the
666
server sends mail about the job. Default is the job
667
owner at the originating host.
669
<I>Qalter</I> allows changing this option even while the job
672
-masterq wc_queue_list
673
Available for <I>qsub</I>, <I>qrsh</I>, <I>qsh</I>, <I>qlogin</I> and <I>qalter</I>. Only
674
meaningful for parallel jobs, i.e. together with the
677
Defines or redefines a list of cluster queues, queue
678
domains and queue instances which may be used to become
679
the so called <I>master</I> <I>queue</I> of this parallel job. A more
680
detailed description of <I>wc</I>_<I>queue</I>_<I>list</I> can be found in
681
<B><A HREF="../htmlman1/sge_types.html">sge_types(1)</A></B>. The <I>master</I> <I>queue</I> is defined as the queue
682
where the parallel job is started. The other queues to
683
which the parallel job spawns tasks are called <I>slave</I>
684
<I>queues</I>. A parallel job only has one <I>master</I> <I>queue</I>.
686
This parameter has all the properties of a resource
687
request and will be merged with requirements derived
688
from the -l option described above.
690
<I>Qalter</I> allows changing this option even while the job
691
executes. The modified parameter will only be in effect
692
after a restart or migration of the job, however.
695
Available for <I>qsub</I>, <I>qrsh</I> (with command) and <I>qalter</I>
698
This flag, when set causes Grid Engine to send "warn-
699
ing" signals to a running job prior to sending the sig-
700
nals themselves. If a SIGSTOP is pending, the job will
701
receive a SIGUSR1 several seconds before the SIGSTOP.
702
If a SIGKILL is pending, the job will receive a SIGUSR2
703
several seconds before the SIGKILL. The amount of time
704
delay is controlled by the notify parameter in each
705
queue configuration (see <B><A HREF="../htmlman5/queue_conf.html">queue_conf(5)</A></B>).
707
Note that the Linux operating system "misused" the user
708
signals SIGUSR1 and SIGUSR2 in some early Posix thread
709
implementations. You might not want to use the -notify
710
option if you are running multi-threaded applications
711
in your jobs under Linux, particularly on 2.0 or ear-
714
<I>Qalter</I> allows changing this option even while the job
718
Available for <I>qsub</I>, <I>qsh</I>, <I>qlogin</I> and <I>qrsh</I>.
720
-now y tries to start the job immediately or not at
721
all. The command returns 0 on success, or 1 on failure
722
(also if the job could not be scheduled immediately).
723
For array jobs submitted with the -now option, if all
724
tasks cannot be immediately scheduled, no tasks are
725
scheduled. -now y is default for <I>qsh</I>, <I>qlogin</I> and <I>qrsh</I>
726
With the -now n option, the job will be put into the
727
pending queue if it cannot be executed immediately.
728
-now n is default for <I>qsub</I>.
731
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
733
The name of the job. The name can be any printable set
734
of characters except "\n", "\t", "\r", "/", ":", "@",
735
"\", "*", and "?", and it has to start with an alpha-
736
betic character. Invalid job names will be denied at
738
If the -N option is not present, Grid Engine assigns
739
the name of the job script to the job after any direc-
740
tory pathname has been removed from the script-name. If
741
the script is read from standard input, the job name
743
In the case of <I>qsh</I> or <I>qlogin</I> with the -N option is
744
absent, the string `INTERACT' is assigned to the job.
745
In the case of <I>qrsh</I> if the -N option is absent, the
746
resulting job name is determined from the qrsh command
747
line by using the argument string up to the first
748
occurrence of a semicolon or whitespace and removing
749
the directory pathname.
751
<I>Qalter</I> allows changing this option even while the job
755
Available only for <I>qrsh</I> with a command line.
757
Do not start the command line given to <I>qrsh</I> in a user's
758
login shell, i.e. execute it without the wrapping
761
This option can be used to speed up execution as some
762
overhead, like the shell startup and sourcing the shell
763
resource files, is avoided.
765
This option can only be used if no shell-specific com-
766
mand line parsing is required. If the command line con-
767
tains shell syntax like environment variable substitu-
768
tion or (back) quoting, a shell must be started. In
769
this case, either do not use the -noshell option or
770
include the shell call in the command line.
773
qrsh echo '$HOSTNAME'
774
Alternative call with the -noshell option
775
qrsh -noshell /bin/tcsh -f -c 'echo $HOSTNAME'
778
Available only for <I>qrsh</I>.
780
Suppress the input stream STDIN - <I>qrsh</I> will pass the
781
option -n to the <B><A HREF="../htmlman1/rsh.html">rsh(1)</A></B> command. This is especially
782
useful, if multiple tasks are executed in parallel
783
using <I>qrsh</I>, e.g. in a <B><A HREF="../htmlman1/make.html">make(1)</A></B> process - it would be
784
undefined, which process would get the input.
786
-o [[hostname]:]path,...
787
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
789
The path used for the standard output stream of the
790
job. The path is handled as described in the -e option
791
for the standard error stream.
793
By default the file name for standard output has the
794
form <I>job</I>_<I>name</I>.o<I>job</I>_<I>id</I> and <I>job</I>_<I>name</I>.o<I>job</I>_<I>id</I>.task_id for
795
array job tasks (see -t option below).
797
<I>Qalter</I> allows changing this option even while the job
798
executes. The modified parameter will only be in effect
799
after a restart or migration of the job, however.
802
Available for <I>qalter</I> only.
804
Changes the number of override tickets for the speci-
805
fied job. Requires manager/operator privileges.
808
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
810
Specifies the project to which this job is assigned.
811
The administrator needs to give permission to indivi-
812
dual users to submit jobs to a specific project. (see
813
-aprj option to <B><A HREF="../htmlman1/qconf.html">qconf(1)</A></B>).
816
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
818
Defines or redefines the priority of the job relative
819
to other jobs. Priority is an integer in the range
820
-1023 to 1024. The default priority value for jobs is
823
Users may only decrease the priority of their jobs.
824
Grid Engine managers and administrators may also
825
increase the priority associated with jobs. If a pend-
826
ing job has higher priority, it is earlier eligible for
827
being dispatched by the Grid Engine scheduler.
830
-pe parallel_environment n[-[m]]|[-]m,...
831
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
833
Parallel programming environment (PE) to instantiate.
834
The range descriptor behind the PE name specifies the
835
number of parallel processes to be run. Grid Engine
836
will allocate the appropriate resources as available.
837
The <B><A HREF="../htmlman5/sge_pe.html">sge_pe(5)</A></B> manual page contains information about
838
the definition of PEs and about how to obtain a list of
840
You can specify a PE name which uses the wildcard char-
841
acter, "*". Thus the request "pvm*" will match any
842
parallel environment with a name starting with the
843
string "pvm". In the case of multiple parallel environ-
844
ments whose names match the name string, the parallel
845
environment with the most available slots is chosen.
846
The range specification is a list of range expressions
847
of the form "n-m", where n and m are positive, non-zero
848
integers. The form "n" is equivalent to "n-n". The
849
form "-m" is equivalent to "1-m". The form "n-" is
850
equivalent to "n-infinity". The range specification is
851
processed as follows: The largest number of queues
852
requested is checked first. If enough queues meeting
853
the specified attribute list are available, all are
854
allocated. If not, the next smaller number of queues is
855
checked, and so forth.
856
If additional -l options are present, they restrict the
857
set of eligible queues for the parallel job.
859
<I>Qalter</I> allows changing this option even while the job
860
executes. The modified parameter will only be in effect
861
after a restart or migration of the job, however.
864
Available for <I>qsub</I>, <I>qrsh</I>, <I>qsh</I>, <I>qlogin</I> and <I>qalter</I>.
866
Defines or redefines a list of cluster queues, queue
867
domains or queue instances which may be used to execute
868
this job. Please find a description of <I>wc</I>_<I>queue</I>_<I>list</I> in
869
<B><A HREF="../htmlman1/sge_types.html">sge_types(1)</A></B>. This parameter has all the properties of
870
a resource request and will be merged with requirements
871
derived from the -l option described above.
873
<I>Qalter</I> allows changing this option even while the job
874
executes. The modified parameter will only be in effect
875
after a restart or migration of the job, however.
878
Available for <I>qsub</I>, <I>qrsh</I>, <I>qsh</I>, <I>qlogin</I> and <I>qalter</I>.
880
Indicates whether a reservation for this job should be
881
done. Reservation is never done for immediate jobs,
882
i.e. jobs submitted using the -now yes option. Please
883
note that regardless of the reservation request, job
884
reservation might be disabled using max_reservation in
885
<B><A HREF="../htmlman5/sched_conf.html">sched_conf(5)</A></B> and might be limited only to a certain
886
number of high priority jobs.
888
By default jobs are submitted with the -R n option.
891
Available for <I>qsub</I> and <I>qalter</I> only.
893
Identifies the ability of a job to be rerun or not. If
894
the value of -r is 'yes', the job will be rerun if the
895
job was aborted without leaving a consistent exit
896
state. (This is typically the case if the node on
897
which the job is running crashes). If -r is 'no', the
898
job will not be rerun under any circumstances.
899
Interactive jobs submitted with <I>qsh</I>, <I>qrsh</I> or <I>qlogin</I> are
902
<I>Qalter</I> allows changing this option even while the job
907
-sc variable[=value],...
908
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
910
Sets the given name/value pairs as the job's context.
911
Value may be omitted. Grid Engine replaces the job's
912
previously defined context with the one given as the
913
argument. Multiple -ac, -dc, and -sc options may be
914
given. The order is important.
915
Contexts provide a way to dynamically attach and remove
916
meta-information to and from a job. The context vari-
917
ables are not passed to the job's execution context in
920
<I>Qalter</I> allows changing this option even while the job
924
Available only for <I>qsub</I>.
926
-shell n causes qsub to execute the command line
927
directly, as if by <B><A HREF="../htmlman2/exec.html">exec(2)</A></B>. No command shell will be
928
executed for the job. This option only applies when -b
929
y is also used. Without -b y, -shell n has no effect.
931
This option can be used to speed up execution as some
932
overhead, like the shell startup and sourcing the shell
933
resource files is avoided.
935
This option can only be used if no shell-specific com-
936
mand line parsing is required. If the command line con-
937
tains shell syntax, like environment variable substitu-
938
tion or (back) quoting, a shell must be started. In
939
this case either do not use the -shell n option or exe-
940
cute the shell as the command line and pass the path to
941
the executable as a parameter.
942
If a job executed with the -shell n option fails due to
943
a user error, such as an invalid path to the execut-
944
able, the job will enter the error state.
946
-shell y cancels the effect of a previous -shell n.
947
Otherwise, it has no effect.
949
See -b and -noshell for more information.
952
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I> only.
954
Signifies that all resource requirements following in
955
the command line will be soft requirements and are to
956
be filled on an "as available" basis.
957
As Grid Engine scans the command line and script file
958
for Grid Engine options and parameters, it builds a
959
list of resources required by the job. All such
960
resource requests are considered as absolutely essen-
961
tial for the job to commence. If the -soft option is
962
encountered during the scan then all following
963
resources are designated as "soft requirements" for
964
execution, or "nice-to-have, but not essential". If the
965
-hard flag (see above) is encountered at a later stage
966
of the scan, all resource requests following it once
967
again become "essential". The -hard and -soft options
968
in effect act as "toggles" during the scan.
971
Available for <I>qsub</I>.
973
-sync y causes <I>qsub</I> to wait for the job to complete
974
before exiting. If the job completes successfully,
975
<I>qsub</I>'<I>s</I> exit code will be that of the completed job. If
976
the job fails to complete successfully, <I>qsub</I> will print
977
out a error message indicating why the job failed and
978
will have an exit code of 1. If <I>qsub</I> is interrupted,
979
e.g. with CTRL-C, before the job completes, the job
981
With the -sync n option, <I>qsub</I> will exit with an exit
982
code of 0 as soon as the job is submitted successfully.
983
-sync n is default for <I>qsub</I>.
984
If -sync y is used in conjunction with -now y, <I>qsub</I>
985
will behave as though only -now y were given until the
986
job has been successfully scheduled, after which time
987
<I>qsub</I> will behave as though only -sync y were given.
988
If -sync y is used in conjunction with -t n[-m[:i]],
989
<I>qsub</I> will wait for all the job's tasks to complete
990
before exiting. If all the job's tasks complete suc-
991
cessfully, <I>qsub</I>'<I>s</I> exit code will be that of the first
992
completed job tasks with a non-zero exit code, or 0 if
993
all job tasks exited with an exit code of 0. If any of
994
the job's tasks fail to complete successfully, <I>qsub</I>
995
will print out an error message indicating why the job
996
task(s) failed and will have an exit code of 1. If
997
<I>qsub</I> is interrupted, e.g. with CTRL-C, before the job
998
completes, all of the job's tasks will be canceled.
1000
-S [[hostname]:]pathname,...
1001
Available for <I>qsub</I>, <I>qsh</I> and <I>qalter</I>.
1003
Specifies the interpreting shell for the job. Only one
1004
pathname component without a host specifier is valid
1005
and only one path name for a given host is allowed.
1006
Shell paths with host assignments define the interpret-
1007
ing shell for the job if the host is the execution
1008
host. The shell path without host specification is used
1009
if the execution host matches none of the hosts in the
1012
Furthermore, the pathname can be constructed with
1013
pseudo environment variables as described for the -e
1016
In the case of <I>qsh</I> the specified shell path is used to
1017
execute the corresponding command interpreter in the
1018
<B><A HREF="../htmlman1/xterm.html">xterm(1)</A></B> (via its -<I>e</I> option) started on behalf of the
1021
<I>Qalter</I> allows changing this option even while the job
1022
executes. The modified parameter will only be in effect
1023
after a restart or migration of the job, however.
1026
Available for <I>qsub</I> and <I>qalter</I> only.
1028
Submits a so called <I>Array</I> <I>Job</I>, i.e. an array of identi-
1029
cal tasks being differentiated only by an index number
1030
and being treated by Grid Engine almost like a series
1031
of jobs. The option argument to -t specifies the number
1032
of array job tasks and the index number which will be
1033
associated with the tasks. The index numbers will be
1034
exported to the job tasks via the environment variable
1035
SGE_TASK_ID. The option arguments n, m and s will be
1036
available through the environment variables
1037
SGE_TASK_FIRST, SGE_TASK_LAST and SGE_TASK_STEPSIZE.
1039
Following restrictions apply to the values n and m:
1041
1 <= n <= MIN(2^31-1, max_aj_tasks)
1042
1 <= m <= MIN(2^31-1, max_aj_tasks)
1045
<I>max</I>_<I>aj</I>_<I>tasks</I> is defined in the cluster configuration
1046
(see <B><A HREF="../htmlman5/sge_conf.html">sge_conf(5)</A></B>)
1048
The task id range specified in the option argument may
1049
be a single number, a simple range of the form n-m or a
1050
range with a step size. Hence, the task id range speci-
1051
fied by 2-10:2 would result in the task id indexes 2,
1052
4, 6, 8, and 10, for a total of 5 identical tasks, each
1053
with the environment variable SGE_TASK_ID containing
1054
one of the 5 index numbers.
1056
All array job tasks inherit the same resource requests
1057
and attribute definitions as specified in the <I>qsub</I> or
1058
<I>qalter</I> command line, except for the -t option. The
1059
tasks are scheduled independently and, provided enough
1060
resources exist, concurrently, very much like separate
1061
jobs. However, an array job or a sub-array there of
1062
can be accessed as a single unit by commands like
1063
<B><A HREF="../htmlman1/qmod.html">qmod(1)</A></B> or <B><A HREF="../htmlman1/qdel.html">qdel(1)</A></B>. See the corresponding manual pages
1066
Array jobs are commonly used to execute the same type
1067
of operation on varying input data sets correlated with
1068
the task index number. The number of tasks in a array
1071
STDOUT and STDERR of array job tasks will be written
1072
into different files with the default location
1074
<jobname>.['e'|'o']<job_id>'.'<task_id>
1076
In order to change this default, the -e and -o options
1077
(see above) can be used together with the pseudo
1078
environment variables $HOME, $USER, $JOB_ID, $JOB_NAME,
1079
$HOSTNAME, and $SGE_TASK_ID.
1081
Note, that you can use the output redirection to divert
1082
the output of all tasks into the same file, but the
1083
result of this is undefined.
1087
Available for <I>qalter</I> only. Changes are only made on
1088
those jobs which were submitted by users specified in
1089
the list of usernames. For managers it is possible to
1090
use the qalter -u '*' command to modify all jobs of all
1093
If you use the -u switch it is not permitted to specify
1094
an additional <I>wc</I>_<I>job</I>_<I>range</I>_<I>list</I>.
1096
-v variable[=value],...
1097
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I> and <I>qalter</I>.
1098
Defines or redefines the environment variables to be
1099
exported to the execution context of the job. If the
1100
-v option is present Grid Engine will add the environ-
1101
ment variables defined as arguments to the switch and,
1102
optionally, values of specified variables, to the exe-
1103
cution context of the job.
1105
<I>Qalter</I> allows changing this option even while the job
1106
executes. The modified parameter will only be in effect
1107
after a restart or migration of the job, however.
1110
Available only for <I>qrsh</I> and <B><A HREF="../htmlman1/qmake.html">qmake(1)</A></B>.
1112
Unlike <I>qsh</I> and <I>qlogin</I>, <I>qrsh</I> does not output any infor-
1113
mational messages while establishing the session, com-
1114
pliant with the standard <B><A HREF="../htmlman1/rsh.html">rsh(1)</A></B> and <B><A HREF="../htmlman1/rlogin.html">rlogin(1)</A></B> system
1115
calls. If the option -verbose is set, <I>qrsh</I> behaves
1116
like the <I>qsh</I> and <I>qlogin</I> commands, printing information
1117
about the process of establishing the <B><A HREF="../htmlman1/rsh.html">rsh(1)</A></B> or <I>rlo-</I>
1118
<B><A HREF="../htmlman1/gin.html">gin(1)</A></B> session.
1121
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I>.
1123
Instead of submitting a job, prints detailed informa-
1124
tion about the would-be job as though <B><A HREF="../htmlman1/qstat.html">qstat(1)</A></B> -j were
1125
used, including the effects of command-line parameters
1126
and the external environment.
1128
-V Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I> <I>with</I> <I>command</I>, <I>qalter</I> and
1131
Specifies that all environment variables active within
1132
the <I>qsub</I> utility be exported to the context of the job.
1135
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I>, <I>qlogin</I> and <I>qalter</I>.
1137
Specifies a validation level applied to the job to be
1138
submitted (<I>qsub</I>, <I>qlogin</I>, and <I>qsh</I>) or the specified
1139
queued job (<I>qalter</I>). The information displayed indi-
1140
cates whether the job can possibly be scheduled assum-
1141
ing an empty system with no other jobs. Resource
1142
requests exceeding the configured maximal thresholds or
1143
requesting unavailable resource attributes are possible
1144
causes for jobs to fail this validation.
1146
The specifiers e, w, n and v define the following vali-
1149
`e' error - jobs with invalid requests will be
1150
rejected; the default for <I>qrsh</I>, <I>qsh</I>
1152
`w' warning - only a warning will be displayed
1153
for invalid requests.
1154
`n' none - switches off validation; the default for
1155
<I>qsub</I> and <I>qalter</I>.
1156
`v' verify - does not submit the job but prints an
1157
extensive validation report.
1159
Note, that the necessary checks are performance consum-
1160
ing and hence the checking is switched off by default.
1162
Note also, that the reasons for job requirements being
1163
invalid with respect to resource availability of queues
1164
are displayed in the "-w v" case using the format as
1165
described for the <B><A HREF="../htmlman1/qstat.html">qstat(1)</A></B> -F option (see description
1166
of Full Format in section OUTPUT FORMATS of the
1167
<B><A HREF="../htmlman1/qstat.html">qstat(1)</A></B> manual page.
1170
Available for <I>qsub</I>, <I>qsh</I>, <I>qrsh</I> and <I>qalter</I> only.
1172
Execute the job from the directory specified in
1173
working_dir. This switch will activate Grid Engine's
1174
path aliasing facility, if the corresponding configura-
1175
tion files are present (see <B><A HREF="../htmlman5/sge_aliases.html">sge_aliases(5)</A></B>).
1177
<I>Qalter</I> allows changing this option even while the job
1178
executes. The modified parameter will only be in effect
1179
after a restart or migration of the job, however.
1182
Available for <I>qsub</I> and <I>qrsh</I> only.
1184
The job's scriptfile or binary. If not present or if
1185
the operand is the single-character string '-', <I>qsub</I>
1186
reads the script from standard input.
1189
Available for <I>qsub</I>, <I>qrsh</I> and <I>qalter</I> only.
1191
Arguments to the job. Not valid if the script is
1192
entered from standard input.
1194
<I>Qalter</I> allows changing this option even while the job
1195
executes. The modified parameter will only be in effect
1196
after a restart or migration of the job, however.
1199
Available for <I>qsh</I> only.
1201
Arguments to the <B><A HREF="../htmlman1/xterm.html">xterm(1)</A></B> executable, as defined in the
1202
configuration. For details, refer to <B><A HREF="../htmlman5/sge_conf.html">sge_conf(5)</A></B>).
1204
ENVIRONMENTAL VARIABLES
1205
SGE_ROOT Specifies the location of the Grid Engine
1206
standard configuration files.
1208
SGE_CELL If set, specifies the default Grid Engine
1209
cell. To address a Grid Engine cell <I>qsub</I>,
1210
<I>qsh</I>, <I>qlogin</I> or <I>qalter</I> use (in the order of
1213
The name of the cell specified in the
1214
environment variable SGE_CELL, if it is
1217
The name of the default cell, i.e.
1222
If set, specifies that debug information
1223
should be written to stderr. In addition the
1224
level of detail in which debug information is
1225
generated is defined.
1228
If set, specifies the tcp port on which
1229
<B><A HREF="../htmlman8/sge_qmaster.html">sge_qmaster(8)</A></B> is expected to listen for com-
1230
munication requests. Most installations will
1231
use a services map entry for the service
1232
"sge_qmaster" instead to define that port.
1234
DISPLAY For <I>qsh</I> jobs the DISPLAY has to be specified
1235
at job submission. If the DISPLAY is not set
1236
by using the -display or the -v switch, the
1237
contents of the DISPLAY environment variable
1238
are used as default.
1240
In addition to those environment variables specified to be
1241
exported to the job via the -v or the -V option (see above)
1242
<I>qsub</I>, <I>qsh</I>, and <I>qlogin</I> add the following variables with the
1243
indicated values to the variable list:
1246
SGE_O_HOME the home directory of the submitting client.
1248
SGE_O_HOST the name of the host on which the submitting
1251
SGE_O_LOGNAME the LOGNAME of the submitting client.
1253
SGE_O_MAIL the MAIL of the submitting client. This is
1254
the mail directory of the submitting client.
1256
SGE_O_PATH the executable search path of the submitting
1259
SGE_O_SHELL the SHELL of the submitting client.
1261
SGE_O_TZ the time zone of the submitting client.
1263
SGE_O_WORKDIR the absolute path of the current working
1264
directory of the submitting client.
1266
Furthermore, Grid Engine sets additional variables into the
1267
job's environment, as listed below.
1271
SGE_ARCH The Grid Engine architecture name of the node
1272
on which the job is running. The name is
1273
compiled-in into the <B><A HREF="../htmlman8/sge_execd.html">sge_execd(8)</A></B> binary.
1275
SGE_CKPT_ENV Specifies the checkpointing environment (as
1276
selected with the -ckpt option) under which a
1277
checkpointing job executes. Only set for
1280
SGE_CKPT_DIR Only set for checkpointing jobs. Contains
1281
path <I>ckpt</I>_<I>dir</I> (see <B><A HREF="../htmlman5/checkpoint.html">checkpoint(5)</A></B> ) of the
1282
checkpoint interface.
1285
the pathname of the file to which the stan-
1286
dard error stream of the job is diverted.
1287
Commonly used for enhancing the output with
1288
error messages from prolog, epilog, parallel
1289
environment start/stop or checkpointing
1293
the pathname of the file to which the stan-
1294
dard output stream of the job is diverted.
1295
Commonly used for enhancing the output with
1296
messages from prolog, epilog, parallel
1297
environment start/stop or checkpointing
1300
SGE_STDIN_PATH the pathname of the file from which the stan-
1301
dard input stream of the job is taken. This
1302
variable might be used in combination with
1303
SGE_O_HOST in prolog/epilog scripts to
1304
transfer the input file from the submit to
1308
The directory used by <B><A HREF="../htmlman8/sge_shepherd.html">sge_shepherd(8)</A></B> to
1309
store job related data during job execution.
1310
This directory is owned by root or by a Grid
1311
Engine administrative account and commonly is
1312
not open for read or write access to regular
1315
SGE_TASK_ID The index number of the current array job
1316
task (see -t option above). This is an unique
1317
number in each array job and can be used to
1318
reference different input data records, for
1319
example. This environment variable is set to
1320
"undefined" for non-array jobs. It is possi-
1321
ble to change the predefined value of this
1322
variable with -v or -V (see options above).
1324
SGE_TASK_FIRST The index number of the first array job task
1325
(see -t option above). It is possible to
1326
change the predefined value of this variable
1327
with -v or -V (see options above).
1329
SGE_TASK_LAST The index number of the last array job task
1330
(see -t option above). It is possible to
1331
change the predefined value of this variable
1332
with -v or -V (see options above).
1335
The step size of the array job specification
1336
(see -t option above). It is possible to
1337
change the predefined value of this variable
1338
with -v or -V (see options above).
1340
ENVIRONMENT The ENVIRONMENT variable is set to BATCH to
1341
identify that the job is being executed under
1342
Grid Engine control.
1344
HOME The user's home directory path from the
1345
<B><A HREF="../htmlman5/passwd.html">passwd(5)</A></B> file.
1347
HOSTNAME The hostname of the node on which the job is
1350
JOB_ID A unique identifier assigned by the
1351
<B><A HREF="../htmlman8/sge_qmaster.html">sge_qmaster(8)</A></B> when the job was submitted.
1352
The job ID is a decimal integer in the range
1355
JOB_NAME The job name. For batch jobs or jobs submit-
1356
ted by <I>qrsh</I> with a command, the job name is
1357
built as basename of the <I>qsub</I> script filename
1358
resp. the <I>qrsh</I> command. For interactive jobs
1359
it is set to `INTERACTIVE' for <I>qsh</I> jobs,
1360
`QLOGIN' for <I>qlogin</I> jobs and `QRLOGIN' for
1361
<I>qrsh</I> jobs without a command.
1363
This default may be overwritten by the -<I>N</I>.
1366
LOGNAME The user's login name from the <B><A HREF="../htmlman5/passwd.html">passwd(5)</A></B>
1369
NHOSTS The number of hosts in use by a parallel job.
1371
NQUEUES The number of queues allocated for the job
1372
(always 1 for serial jobs).
1374
NSLOTS The number of queue slots in use by a paral-
1377
PATH A default shell search path of:
1378
/usr/local/bin:/usr/ucb:/bin:/usr/bin
1381
The path where the Grid Engine binaries are
1382
installed. The value is the concatenation of
1383
the cluster configuration value binary_path
1384
and the architecture name $SGE_ARCH environ-
1387
PE The parallel environment under which the job
1388
executes (for parallel jobs only).
1390
PE_HOSTFILE The path of a file containing the definition
1391
of the virtual parallel machine assigned to a
1392
parallel job by Grid Engine. See the descrip-
1393
tion of the $pe_hostfile parameter in
1394
<B><A HREF="../htmlman5/sge_pe.html">sge_pe(5)</A></B> for details on the format of this
1395
file. The environment variable is only avail-
1396
able for parallel jobs.
1398
QUEUE The name of the cluster queue in which the
1401
REQUEST Available for batch jobs only.
1403
The request name of a job as specified with
1404
the -N switch (see above) or taken as the
1405
name of the job script file.
1407
RESTARTED This variable is set to 1 if a job was res-
1408
tarted either after a system crash or after a
1409
migration in case of a checkpointing job. The
1410
variable has the value 0 otherwise.
1412
SHELL The user's login shell from the <B><A HREF="../htmlman5/passwd.html">passwd(5)</A></B>
1413
file. Note: This is not necessarily the shell
1416
TMPDIR The absolute path to the job's temporary
1419
TMP The same as TMPDIR; provided for compatibil-
1422
TZ The time zone variable imported from
1423
<B><A HREF="../htmlman8/sge_execd.html">sge_execd(8)</A></B> if set.
1425
USER The user's login name from the <B><A HREF="../htmlman5/passwd.html">passwd(5)</A></B>
1429
There is no controlling terminal for batch jobs under Grid
1430
Engine, and any tests or actions on a controlling terminal
1431
will fail. If these operations are in your .login or .cshrc
1432
file, they may cause your job to abort.
1434
Insert the following test before any commands that are not
1435
pertinent to batch jobs in your .login:
1437
if ( $?JOB_NAME) then
1438
echo "Grid Engine spooled job"
1442
Don't forget to set your shell's search path in your shell
1443
start-up before this code.
1446
The following exit values are returned:
1448
0 Operation was executed successfully.
1450
25 It was not possible to register a new job according to
1451
the configured <I>max</I>_<I>u</I>_<I>jobs</I> or <I>max</I>_<I>jobs</I> limit. Additional
1452
information may be found in <B><A HREF="../htmlman5/sge_conf.html">sge_conf(5)</A></B>
1454
>0 Error occurred.
1457
The following is the simplest form of a Grid Engine script
1460
=====================================================
1467
=====================================================
1469
The next example is a more complex Grid Engine script.
1471
=====================================================
1475
# Which account to be charged cpu time
1478
# date-time to run, format [[CC]yy]MMDDhhmm[.SS]
1481
# to run I want 6 or more parallel processes
1482
# under the PE pvm. the processes require
1484
#$ -pe pvm 6- -l mem=128
1486
# If I run on dec_x put stderr in /tmp/foo, if I
1487
# run on sun_y, put stderr in /usr/me/foo
1488
#$ -e dec_x:/tmp/foo,sun_y:/usr/me/foo
1490
# Send mail to these users
1491
#$ -M santa@nothpole,claus@northpole
1493
# Mail at beginning/end/on suspension
1496
# Export these environmental variables
1497
#$ -v PVM_ROOT,FOOBAR=BAR
1499
# The job is located in the current
1500
# working directory.
1505
==========================================================
1509
$<I>REQUEST</I>.<I>oJID</I>[.<I>TASKID</I>] STDOUT of job #JID
1510
$<I>REQUEST</I>.<I>eJID</I>[.<I>TASKID</I>] STDERR of job
1511
$<I>REQUEST</I>.<I>poJID</I>[.<I>TASKID</I>] STDOUT of par. env. of job
1512
$<I>REQUEST</I>.<I>peJID</I>[.<I>TASKID</I>] STDERR of par. env. of job
1513
$<I>REQUEST</I>.<I>hostsJID</I>[.<I>TASKID</I>] hosts file of par. env. of job
1516
$<I>cwd</I>/.<I>sge</I>_<I>aliases</I> cwd path aliases
1517
$<I>cwd</I>/.<I>sge</I>_<I>request</I> cwd default request
1518
$<I>HOME</I>/.<I>sge</I>_<I>aliases</I> user path aliases
1519
$<I>HOME</I>/.<I>sge</I>_<I>request</I> user default request
1520
<<I>sge</I>_<I>root</I>>/<<I>cell</I>>/<I>common</I>/<I>sge</I>_<I>aliases</I>
1521
cluster path aliases
1522
<<I>sge</I>_<I>root</I>>/<<I>cell</I>>/<I>common</I>/<I>sge</I>_<I>request</I>
1523
cluster default request
1524
<<I>sge</I>_<I>root</I>>/<<I>cell</I>>/<I>common</I>/<I>act</I>_<I>qmaster</I>
1525
Grid Engine master host file
1528
<B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B>, <B><A HREF="../htmlman1/qconf.html">qconf(1)</A></B>, <B><A HREF="../htmlman1/qdel.html">qdel(1)</A></B>, <B><A HREF="../htmlman1/qhold.html">qhold(1)</A></B>, <B><A HREF="../htmlman1/qmod.html">qmod(1)</A></B>, <B><A HREF="../htmlman1/qrls.html">qrls(1)</A></B>,
1529
<B><A HREF="../htmlman1/qstat.html">qstat(1)</A></B>, <B><A HREF="../htmlman5/accounting.html">accounting(5)</A></B>, <B><A HREF="../htmlman5/sge_aliases.html">sge_aliases(5)</A></B>, <B><A HREF="../htmlman5/sge_conf.html">sge_conf(5)</A></B>,
1530
<B><A HREF="../htmlman5/sge_request.html">sge_request(5)</A></B>, <B><A HREF="../htmlman5/sge_pe.html">sge_pe(5)</A></B>, <B><A HREF="../htmlman5/complex.html">complex(5)</A></B>.
1533
If configured correspondingly, <I>qrsh</I> and <I>qlogin</I> contain por-
1534
tions of the <I>rsh</I>, <I>rshd</I>, <I>telnet</I> and <I>telnetd</I> code copyrighted
1535
by The Regents of the University of California. Therefore,
1536
the following note applies with respect to <I>qrsh</I> and <I>qlogin</I>:
1537
This product includes software developed by the University
1538
of California, Berkeley and its contributors.
1540
See <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B> as well as the information provided in
1541
<sge_root>/3rd_party/qrsh and <sge_root>/3rd_party/qlogin
1542
for a statement of further rights and permissions.
1571
Man(1) output converted with
1572
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
added
removed
doc/htmlman/htmlman1/qsh.html
