1SUBMIT(1)                  Grid Engine User Commands                 SUBMIT(1)
2
3
4

NAME

6       qsub   -  submit a batch job to Grid Engine.
7
8       qsh    -  submit an interactive X-windows session to Grid Engine.
9
10       qlogin -  submit an interactive login session to Grid Engine.
11
12       qrsh   -  submit an interactive rsh session to Grid Engine.
13
14       qalter -  modify a pending batch job of Grid Engine.
15
16       qresub -  submit a copy of an existing Grid Engine job.
17

SYNTAX

19       qsub [ options ] [ command | -- [ command_args ]]
20
21       qsh [ options ] [ -- xterm_args ]
22
23       qlogin [ options ]
24
25       qrsh [ options ] [ command [ command_args ]]
26
27       qalter [ options ] wc_job_range_list [ -- [ command_args ]]
28
29       qalter [ options ] -u user_list | -uall [ -- [ command_args ]]
30
31       qresub [ options ] job_id_list
32

DESCRIPTION

34       qsub  submits batch jobs to the Grid Engine queuing system. Grid Engine
35       supports single- and multiple-node jobs. Command can be  a  path  to  a
36       binary or a script (see -b below) which contains the commands to be run
37       by the job using a shell (for example, sh(1) or csh(1)).  Arguments  to
38       the  command are given as command_args to qsub .  If command is handled
39       as a script then it is possible to embed flags in the script.   If  the
40       first two characters of a script line either match '#$' or are equal to
41       the prefix string defined with the -C option described below, the  line
42       is parsed for embedded command flags.
43
44       qsh  submits  an  interactive  X-windows  session  to  Grid  Engine. An
45       xterm(1) is brought up from the  executing  machine  with  the  display
46       directed  either  to  the X-server indicated by the DISPLAY environment
47       variable or as specified with the -display qsh option. Interactive jobs
48       are  not  spooled if no resource is available to execute them. They are
49       either dispatched to a suitable machine for  execution  immediately  or
50       the  user  submitting  the  job  is  notified  by  qsh that appropriate
51       resources to execute the job are not available.  xterm_args are  passed
52       to  the  xterm(1) executable.  Note, however, that the -e and -ls xterm
53       options do not work with qsh .
54
55       qlogin is similar to qsh in that it submits an interactive job  to  the
56       queueing  system. It does not open an xterm(1) window on the X display,
57       but uses the current terminal for user I/O. Usually, qlogin establishes
58       a telnet(1) connection with the remote host, using standard client- and
59       server-side commands. These commands can be configured  with  the  qlo‐
60       gin_daemon   and  qlogin_command  in the global and local configuration
61       settings of sge_conf(5).
62
63       On the server-side, an Grid Engine telnetd is used if the parameter  is
64       not   set.   Otherwise,   it   should   be   set   to   something  like
65       /usr/sbin/in.telnetd.  On the client side, an  Grid  Engine  telnet  is
66       used  it the parameter is not set. Otherwise, it should be set to some‐
67       thing like /usr/bin/telnet.
68
69       The client side command is automatically parameterized with the  remote
70       host  name and port number to which to connect, resulting in an invoca‐
71       tion like
72
73              /usr/bin/telnet my_exec_host 2442
74
75       for example.  qlogin is invoked exactly like qsh and its jobs can  only
76       run  on  INTERACTIVE  queues.   qlogin  jobs  can  only  be used if the
77       sge_execd(8) is running under the root account.
78
79       qrsh is similar to qlogin in that it submits an interactive job to  the
80       queuing  system.   It uses the current terminal for user I/O.  Usually,
81       qrsh establishes a rsh(1) connection with the remote host. If  no  com‐
82       mand  is  given  to  qrsh,  an  rlogin(1)  session is established.  The
83       server-side commands used can be configured  with  the  rsh_daemon  and
84       rlogin_daemon parameters in the global and local configuration settings
85       of sge_conf(5).  An Grid Engine rshd or rlogind is used if the  parame‐
86       ters  are  not  set.  If  the parameters are set, they should be set to
87       something  like  /usr/sbin/in.rshd  or  /usr/sbin/in.rlogind.   On  the
88       client-side,  the  rsh_command and rlogin_command parameters can be set
89       in the global and local configuration settings of sge_conf(5).  If they
90       are  not  set, special Grid Engine rsh(1) and rlogin(1) binaries deliv‐
91       ered with Grid Engine are used.  Use the cluster configuration  parame‐
92       ters  to  integrate  mechanisms  like  ssh  or the rsh(1) and rlogin(1)
93       facilities supplied with the operating system.
94
95       qrsh jobs can only run in INTERACTIVE queues unless the option -now  no
96       is used (see below).  They can also only be run, if the sge_execd(8) is
97       running under the root account.
98
99       qrsh provides an additional useful feature for integrating with  inter‐
100       active  tools  providing  a  specific command shell. If the environment
101       variable QRSH_WRAPPER is set when qrsh is invoked, the  command  inter‐
102       preter pointed to by QRSH_WRAPPER will be executed to run qrsh commands
103       instead of the users login shell or any shell  specified  in  the  qrsh
104       command-line.   The options -cwd,  -v,  -V,  and -display only apply to
105       batch jobs.
106
107       qalter can be used to change the attributes of pending jobs. For  array
108       jobs with a mix of running and pending tasks (see the -t option below),
109       modification with qalter only affects the pending  tasks.   qalter  can
110       change  most  of  the  characteristics  of a job (see the corresponding
111       statements in the OPTIONS section below), including  those  which  were
112       defined  as embedded flags in the script file (see above).  Some submit
113       options, such as the job script, cannot be changed with qalter.
114
115       qresub allows the user to create jobs as copies of existing pending  or
116       running  jobs. The copied jobs will have exactly the same attributes as
117       the ones from which they were copied, except with a  new  job  ID.  The
118       only  modification to the copied jobs supported by qresub is assignment
119       of a hold state with the -h option. This option can be  used  to  first
120       copy a job and then change its attributes via qalter.
121
122       Only a user with manager privileges can use qresub on jobs submitted by
123       another user.  Regular users can only use qresub on their own jobs.
124
125       For qsub, qsh, qrsh, and qlogin the  administrator  and  the  user  may
126       define default request files (see sge_request(5)) which can contain any
127       of the options described below.  If an option in a default request file
128       is  understood by qsub and qlogin but not by qsh the option is silently
129       ignored if qsh is invoked. Thus you can maintain shared default request
130       files for both qsub and qsh.
131
132       A   cluster-wide   default   request   file   may   be   placed   under
133       $SGE_ROOT/$SGE_CELL/common/sge_request.  User private  default  request
134       files   are   processed  under  the  locations  $HOME/.sge_request  and
135       $cwd/.sge_request. The working directory local default request file has
136       the  highest  precedence, then the home directory located file and then
137       the cluster global file.  The option  arguments,  the  embedded  script
138       flags and the options in the default request files are processed in the
139       following order:
140
141              left to right in the script line,
142              left to right in the default request files,
143              from top to bottom of the script file (qsub only),
144              from top to bottom of default request files,
145              from left to right of the command line.
146
147       In other words, the command line can be used to override  the  embedded
148       flags  and  the default request settings.  The embedded flags, however,
149       will override the default settings.
150
151       Note, that the -clear option can be used to discard any  previous  set‐
152       tings  at  any  time  in a default request file, in the embedded script
153       flags, or in a command-line option. It is, however, not available  with
154       qalter.
155
156       The  options  described below can be requested either hard or soft.  By
157       default, all requests are considered hard until the -soft  option  (see
158       below) is encountered. The hard/soft status remains in effect until its
159       counterpart is encountered again.  If all the hard requests for  a  job
160       cannot be met, the job will not be scheduled.  Jobs which cannot be run
161       at the present time remain spooled.
162

OPTIONS

164       -@ optionfile
165              Forces qsub, qrsh, qsh, or qlogin to use the  options  contained
166              in optionfile. The indicated file may contain all valid options.
167              Comment lines must start with a "#" sign.
168
169       -a date_time
170              Available for qsub and qalter only.
171
172              Defines or redefines the time and date at which a job is  eligi‐
173              ble for execution. Date_time conforms to [[CC]]YY]MMDDhhmm[.SS],
174              where:
175
176              CC  denotes the century in 2 digits.
177              YY  denotes the year in 2 digits.
178              MM  denotes the month in 2 digits.
179              DD  denotes the day in 2 digits.
180              hh  denotes the hour in 2 digits.
181              mm  denotes the minute in 2 digits.
182              ss  denotes the seconds in 2 digits (default 00).
183
184              If any of the optional date fields is omitted, the corresponding
185              value  of the current date is assumed. If CC is not specified, a
186              YY of < 70 means 20YY.
187              Usage of this option may cause unexpected results if the  clocks
188              of  the hosts in the Grid Engine pool are out of sync. Also, the
189              proper behavior of this option very much depends on the  correct
190              setting  of the appropriate timezone, e.g. in the TZ environment
191              variable (see date(1) for details), when the Grid Engine daemons
192              sge_qmaster(8) and sge_execd(8) are invoked.
193
194              qalter  allows changing this option even while the job executes.
195              The modified parameter will only be in effect after a restart or
196              migration of the job, however.
197
198       -ac variable[=value],...
199              Available for qsub, qsh, qrsh, qlogin and qalter only.
200
201              Adds  the  given  name/value pair(s) to the job's context. Value
202              may be omitted. Grid Engine appends the given  argument  to  the
203              list  of  context variables for the job.  Multiple -ac, -dc, and
204              -sc options may be given.  The order is important here.
205
206              qalter allows changing this option even while the job executes.
207
208       -A account_string
209              Available for qsub, qsh, qrsh, qlogin and qalter only.
210
211              Identifies the account to which the resource consumption of  the
212              job  should  be charged. The account_string may be any arbitrary
213              ASCII alphanumeric string but may not contain  "\n", "\t", "\r",
214              "/", ":", "@", "\", "*",  or "?".  In the absence of this param‐
215              eter Grid Engine will place the default account string "sge"  in
216              the accounting record of the job.
217
218              qalter allows changing this option even while the job executes.
219
220       -b y[es]|n[o]
221              Available  for  qsub,  qrsh only. qalter does not allow changing
222              this option. This option cannot be embedded in the  script  file
223              itself.
224
225              Gives  the  user  the possibility to indicate explicitly whether
226              command should be treated as binary or script. If the  value  of
227              -b is 'y', then command  may be a binary or script.  The command
228              might not be  accessible  from  the  submission  host.   Nothing
229              except the path of the command will be transferred from the sub‐
230              mission host to  the  execution  host.  Path  aliasing  will  be
231              applied to the path of command before command will be executed.
232
233              If  the value of -b is 'n' then command needs to be a script and
234              it will be handled as script. The script file has to be accessi‐
235              ble by the submission host. It will be transferred to the execu‐
236              tion host.  qsub/qrsh  will  search  directive  prefixes  within
237              script.
238
239              qsub  will  implicitly use -b n whereas qrsh will apply the -b y
240              option if nothing else is specified.
241
242       -c occasion_specifier
243              Available for qsub and qalter only.
244
245              Defines or redefines whether the job should be checkpointed, and
246              if so, under what circumstances. The specification of the check‐
247              pointing occasions with this option overwrites  the  definitions
248              of  the  when  parameter  in  the checkpointing environment (see
249              checkpoint(5)) referenced by the qsub  -ckpt  switch.   Possible
250              values for occasion_specifier are
251
252              n           no checkpoint is performed.
253              s           checkpoint when batch server is shut down.
254              m           checkpoint at minimum CPU interval.
255              x           checkpoint when job gets suspended.
256              <interval>  checkpoint in the specified time interval.
257
258              The  minimum  CPU interval is defined in the queue configuration
259              (see queue_conf(5) for details).  <interval> has to be specified
260              in  the  format  hh:mm:ss.   The  maximum  of <interval> and the
261              queue's minimum CPU interval is used if <interval> is specified.
262              This  is  done  to  ensure  that  a machine is not overloaded by
263              checkpoints being generated too frequently.
264
265       -ckpt ckpt_name
266              Available for qsub and qalter only.
267
268              Selects the checkpointing environment (see checkpoint(5)) to  be
269              used  for  checkpointing  the job. Also declares the job to be a
270              checkpointing job.
271
272       -clear Available for qsub, qsh, qrsh, and qlogin only.
273
274              Causes all elements of the  job  to  be  reset  to  the  initial
275              default  status  prior  to  applying  any modifications (if any)
276              appearing in this specific command.
277
278       -cwd   Available for qsub, qsh, qrsh and qalter only.
279
280              Execute the job from the current working directory.  This switch
281              will  activate Grid Engine's path aliasing facility, if the cor‐
282              responding configuration files are present (see sge_aliases(5)).
283
284              In the case of qalter, the previous definition  of  the  current
285              working directory will be overwritten if qalter is executed from
286              a different directory than the preceding qsub or qalter.
287
288              qalter allows changing this option even while the job  executes.
289              The modified parameter will only be in effect after a restart or
290              migration of the job, however.
291
292       -C prefix_string
293              Available for qsub and qrsh with script submission (-b n).
294
295              Prefix_string defines the prefix that declares  a  directive  in
296              the  job's  command.  The  prefix  is  not  a job attribute, but
297              affects the behavior of qsub and  qrsh.  If  prefix  is  a  null
298              string, the command will not be scanned for embedded directives.
299              The  directive  prefix  consists  of two ASCII characters which,
300              when appearing in the first two bytes of a script line, indicate
301              that  what  follows  is  an Grid Engine command.  The default is
302              "#$".
303              The user should be aware  that  changing  the  first  delimiting
304              character  can  produce  unforeseen  side effects. If the script
305              file contains anything other than a "#" character in  the  first
306              byte  position of the line, the shell processor for the job will
307              reject the line and may exit the job prematurely.
308              If the -C option is present in the script file, it is ignored.
309
310       -dc variable,...
311              Available for qsub, qsh, qrsh, qlogin and qalter only.
312
313              Removes the given variable(s) from the job's context.   Multiple
314              -ac, -dc, and -sc options may be given.  The order is important.
315
316              qalter allows changing this option even while the job executes.
317
318       -display display_specifier
319              Available for qsh only.
320
321              Directs  xterm(1)  to  use display_specifier in order to contact
322              the X server.  The display_specifier has to contain the hostname
323              part  of  the display name (e.g. myhost:1).  Local display names
324              (e.g. :0) cannot be used in grid environments.  Values set  with
325              the -display option overwrite settings from the submission envi‐
326              ronment and from -v command line options.
327
328       -dl date_time
329              Available for qsub, qsh, qrsh, qlogin and qalter only.
330
331              Specifies the deadline initiation time in  [[CC]YY]MMDDhhmm[.SS]
332              format  (see  -a  option above). The deadline initiation time is
333              the time at which a deadline job has to reach top priority to be
334              able  to  complete  within a given deadline. Before the deadline
335              initiation time the priority of a deadline job  will  be  raised
336              steadily  until it reaches the maximum as configured by the Grid
337              Engine administrator.
338              This option is applicable only for users allowed to submit dead‐
339              line jobs.
340
341       -e [[hostname]:]path,...
342              Available for qsub, qsh, qrsh, qlogin and qalter only.
343
344              Defines or redefines the path used for the standard error stream
345              of the job. For qsh, qrsh and qlogin  only  the  standard  error
346              stream  of prolog and epilog is redirected.  If the path consti‐
347              tutes an absolute path name, the error-path attribute of the job
348              is set to path, including the hostname. If the path name is rel‐
349              ative, Grid Engine expands path either with the current  working
350              directory  path  (if  the -cwd switch (see above) is also speci‐
351              fied) or with the home directory path. If hostname  is  present,
352              the  standard  error  stream will be placed in the corresponding
353              location only if the job runs on the specified host. If the path
354              contains a ":" without a hostname, a leading ":" has to be spec‐
355              ified.
356
357              By default the file name for interactive jobs is /dev/null.  For
358              batch  jobs  the default file name has the form job_name.ejob_id
359              and job_name.ejob_id.task_id for array job tasks (see -t  option
360              below).
361
362              If  path  is  a  directory, the standard error stream of the job
363              will be put in this directory under the default file  name.   If
364              the   pathname  contains  certain  pseudo-environment-variables,
365              their value will be expanded at runtime of the job and  will  be
366              used to constitute the standard error stream path name. The fol‐
367              lowing pseudo-environment-variables are supported currently:
368
369              $HOME       home directory on execution machine
370              $USER       user ID of job owner
371              $JOB_ID     current job ID
372              $JOB_NAME   current job name (see -N option)
373              $HOSTNAME   name of the execution host
374              $TASK_ID    array job task index number
375
376              The tilde sign ("~")  can be  used as an alternative  to  $HOME,
377              as  is common in csh(1) or ksh(1).  Note, that the "~" sign also
378              works in combination with user names, so that "~<user>"  expands
379              to the home directory of <user>. Using another user ID than that
380              of the job owner requires corresponding permissions, of course.
381
382              qalter allows changing this option even while the job  executes.
383              The modified parameter will only be in effect after a restart or
384              migration of the job, however.
385
386       -hard  Available for qsub, qsh, qrsh, qlogin and qalter only.
387
388              Signifies that all resource requirements following in  the  com‐
389              mand  line  will  be  hard requirements and must be satisfied in
390              full before a job can be scheduled.
391              As Grid Engine scans the command line and script file  for  Grid
392              Engine  options  and  parameters  it  builds a list of resources
393              required by a job. All such resource requests are considered  as
394              absolutely  essential  for  the  job  to  commence. If the -soft
395              option (see below) is encountered during the scan then all  fol‐
396              lowing  resources are designated as "soft requirements" for exe‐
397              cution, or "nice-to-have, but not essential". If the -hard  flag
398              is  encountered  at  a  later  stage  of  the scan, all resource
399              requests following it once again become "essential".  The  -hard
400              and -soft options in effect act as "toggles" during the scan.
401
402       -h | -h {u|s|o|n|U|O|S}...
403              Available for qsub, qsh, qrsh, qlogin, qalter and qresub.
404
405              List of holds to place on a job, a task or some tasks of a job.
406
407              `u'  denotes a user hold.
408              `s'  denotes a system hold.
409              `o'  denotes a operator hold.
410              `n'  denotes no hold.
411
412              As  long  as  any hold other than `n' is assigned to the job the
413              job is not eligible for execution. Holds  can  be  released  via
414              qalter  and qrls(1).  In case of qalter this is supported by the
415              following additional option specifiers for the -h switch:
416
417              `U'  removes a user hold.
418              `S'  removes a system hold.
419              `O'  removes a operator hold.
420
421              Grid Engine managers can assign and remove all hold types,  Grid
422              Engine  operators can assign and remove user and operator holds,
423              and users can only assign or remove user holds.
424
425              In the case of qsub only user holds can be placed on a  job  and
426              thus  only the first form of the option with the -h switch alone
427              is allowed.  As opposed to this, qalter requires the second form
428              described above.
429
430              An  alternate  means  to assign hold is provided by the qhold(1)
431              facility.
432
433              If the job is an array job (see the -t option below), all  tasks
434              specified  via  -t  are  affected by the -h operation simultane‐
435              ously.
436
437              qalter allows changing this option even while the job is execut‐
438              ing.  The  modified  parameter  will  only  be in effect after a
439              restart or migration of the job, however.
440
441       -help  Prints  a listing of all options.
442
443       -hold_jid wc_job_list
444              Available for qsub, qrsh, and  qalter  only.  See  sge_types(1).
445              for 504
446
447              Defines  or  redefines  the job dependency list of the submitted
448              job. A reference by job name or pattern is only accepted if  the
449              referenced  job  is owned by the same user as the referring job.
450              The submitted job is not eligible for execution unless all  jobs
451              referenced  in  the  comma-separated job id and/or job name list
452              have completed.  If any of the referenced jobs exits  with  exit
453              code  100,  the  submitted job will remain ineligible for execu‐
454              tion.
455
456              With the help of job names or regular pattern one can specify  a
457              job  dependency  on multiple jobs satisfying the regular pattern
458              or on all jobs with the requested name.  The  name  dependencies
459              are  resolved at submit time and can only be changed via qalter.
460              New jobs or name changes of other jobs will not  be  taken  into
461              account.
462
463              qalter  allows changing this option even while the job executes.
464              The modified parameter will only be in effect after a restart or
465              migration of the job, however.
466
467       -i [[hostname]:]file,...
468              Available for qsub, and qalter only.
469
470              Defines or redefines the file used for the standard input stream
471              of the job. If the file constitutes an  absolute  filename,  the
472              input-path  attribute  of  the job is set to path, including the
473              hostname. If the path name is relative, Grid Engine expands path
474              either  with  the  current  working  directory path (if the -cwd
475              switch (see above) is also specified) or with the home directory
476              path.  If hostname is present, the standard input stream will be
477              placed in the corresponding location only if the job runs on the
478              specified host. If the path contains a ":" without a hostname, a
479              leading ":" has to be specified.
480
481              By default /dev/null is the input stream for the job.
482
483              It is possible to use  certain  pseudo-variables,  whose  values
484              will  be  expanded  at  time  the  job  runs and will be used to
485              express the standard input stream as described in the -e  option
486              for the standard error stream.
487
488              qalter  allows changing this option even while the job executes.
489              The modified parameter will only be in effect after a restart or
490              migration of the job, however.
491
492       -inherit
493              Available only for qrsh and qmake(1).
494
495              qrsh  allows  the  user  to start a task in an already scheduled
496              parallel job.  The option -inherit tells qrsh to read a  job  id
497              from  the  environment  variable  JOB_ID and start the specified
498              command as a task in this job. Please note that  in  this  case,
499              the hostname of the host where the command will be executed must
500              precede the command to execute; the syntax changes to
501
502              qrsh -inherit [ other options ] hostname command [  command_args
503              ]
504
505              Note also, that in combination with -inherit, most other command
506              line options will be ignored.  Only the options -verbose, -v and
507              -V  will be interpreted.  As a replacement to option -cwd please
508              use -v PWD.
509
510              Usually a task should have the same environment  (including  the
511              current working directory) as the corresponding job, so specify‐
512              ing the option -V should be suitable for most applications.
513
514              Note: If in your system the qmaster tcp port is  not  configured
515              as  a service, but rather via the environment variable SGE_QMAS‐
516              TER_PORT, make sure that this variable is set in the environment
517              when calling qrsh or qmake with the -inherit option. If you call
518              qrsh or qmake with the -inherit option from within a job script,
519              export  SGE_QMASTER_PORT  with  the option "-v SGE_QMASTER_PORT"
520              either as a command argument or an embedded directive.
521
522       -j y[es]|n[o]
523              Available for qsub, qsh, qrsh, qlogin and qalter only.
524
525              Specifies whether or not the standard error stream of the job is
526              merged into the standard output stream.
527              If  both  the  -j  y and the -e options are present, Grid Engine
528              sets but ignores the error-path attribute.
529
530              qalter allows changing this option even while the job  executes.
531              The modified parameter will only be in effect after a restart or
532              migration of the job, however.
533
534       -js job_share
535              Available for qsub, qsh, qrsh, qlogin and qalter only.
536
537              Defines or redefines the job share of the job relative to  other
538              jobs.   Job share is an unsigned integer value.  The default job
539              share value for jobs is 0.
540
541              The job share influences the Share Tree  Policy  and  the  Func‐
542              tional  Policy.  It  has  no  effect on the Urgency and Override
543              Policies (see share_tree(5), sched_conf(5) and the  Grid  Engine
544              Installation and Administration Guide for further information on
545              the resource management policies supported by Grid Engine).
546
547              In case of the Share Tree Policy, users can distribute the tick‐
548              ets  to which they are currently entitled among their jobs using
549              different shares assigned via -js. If all jobs have the same job
550              share value, the tickets are distributed evenly. Otherwise, jobs
551              receive tickets relative to the different job shares. Job shares
552              are  treated  like  an additional level in the share tree in the
553              latter case.
554
555              In connection with the Functional Policy, the job share  can  be
556              used to weight jobs within the functional job category.  Tickets
557              are distributed relative to any uneven  job  share  distribution
558              treated  as  a  virtual  share distribution level underneath the
559              functional job category.
560
561              If both the Share Tree and the Functional Policy are active, the
562              job shares will have an effect in both policies, and the tickets
563              independently derived in each of them are  added  to  the  total
564              number of tickets for each job.
565
566       -l resource=value,...
567              Available for qsub, qsh, qrsh, qlogin and qalter only.
568
569              Launch the job in a Grid Engine queue meeting the given resource
570              request list.  In case of  qalter  the  previous  definition  is
571              replaced by the specified one.
572              complex(5) describes how a list of available resources and their
573              associated valid value specifiers can be obtained.
574              There may be multiple -l switches in a single command.  You  may
575              request  multiple -l options to be soft or hard both in the same
576              command line. In case of  a  serial  job  multiple  -l  switches
577              refine the definition for the sought queue.
578
579              qalter  allows changing this option even while the job executes.
580              The modified parameter will only be in effect after a restart or
581              migration of the job, however.
582
583       -m b|e|a|s|n,...
584              Available for qsub, qsh, qrsh, qlogin and qalter only.
585
586              Defines  or  redefines  under  which circumstances mail is to be
587              sent to the job owner or to the users defined with the -M option
588              described  below.  The option arguments have the following mean‐
589              ing:
590
591              `b'     Mail is sent at the beginning of the job.
592              `e'     Mail is sent at the end of the job.
593              `a'     Mail is sent when the job is aborted or
594                      rescheduled.
595              `s'     Mail is sent when the job is suspended.
596              `n'     No mail is sent.
597
598              By default, no mail is sent when a job is suspended.
599
600              qalter allows changing the b, e, and  a  option  arguments  even
601              while  the  job executes. The modification of the b option argu‐
602              ment will only be in effect after a restart or migration of  the
603              job, however.
604
605       -M user[@host],...
606              Available for qsub, qsh, qrsh, qlogin and qalter only.
607
608              Defines  or redefines the list of users to which the server that
609              executes the job has to send mail,  if  the  server  sends  mail
610              about the job.
611
612              qalter allows changing this option even while the job executes.
613
614       -masterq wc_queue_list
615              Available for qsub, qrsh, qsh, qlogin and qalter.  Only meaning‐
616              ful for parallel jobs, i.e. together with the -pe option.
617
618              Defines or redefines a list of cluster queues, queue domains and
619              queue  instances which may be used to become the master queue of
620              this parallel job. A more detailed description of  wc_queue_list
621              can  be  found  in sge_types(1).  The master queue is defined as
622              the queue where the parallel job is started. The other queues to
623              which  the parallel job spawns tasks are called slave queues.  A
624              parallel job only has one master queue.
625
626              This parameter has all the properties of a resource request  and
627              will  be  merged  with  requirements  derived from the -l option
628              described above.
629
630              qalter allows changing this option even while the job  executes.
631              The modified parameter will only be in effect after a restart or
632              migration of the job, however.
633
634       -notify
635              Available for qsub, qrsh (with command) and qalter only.
636
637              This flag, when set causes Grid Engine to send "warning" signals
638              to  a  running job prior to sending the signals themselves. If a
639              SIGSTOP is pending, the job will receive a SIGUSR1 several  sec‐
640              onds  before  the SIGSTOP. If a SIGKILL is pending, the job will
641              receive a SIGUSR2  several  seconds  before  the  SIGKILL.   The
642              amount  of  time  delay is controlled by the notify parameter in
643              each queue configuration (see queue_conf(5)).
644
645              Note that the Linux operating system "misused" the user  signals
646              SIGUSR1  and SIGUSR2 in some early Posix thread implementations.
647              You might not want to use the -notify option if you are  running
648              multi-threaded  applications  in your jobs under Linux, particu‐
649              larly on 2.0 or earlier kernels.
650
651              qalter allows changing this option even while the job executes.
652
653       -now y[es]|n[o]
654              Available for qsub, qsh, qlogin and qrsh.
655
656              -now y tries to start the job immediately or  not  at  all.  The
657              command  returns  0 on success, or 1 on failure (also if the job
658              could not be scheduled immediately).  For array  jobs  submitted
659              with  the -now option, if all tasks cannot be immediately sched‐
660              uled, no tasks are scheduled.  -now y is default for qsh, qlogin
661              and qrsh
662              With  the  -now  n  option, the job will be put into the pending
663              queue if it cannot be executed immediately. -now  n  is  default
664              for qsub.
665
666       -N name
667              Available for qsub, qsh, qrsh, qlogin and qalter only.
668
669              The  name of the job. The name can be any printable set of char‐
670              acters except "\n", "\t", "\r", "/", ":",  "@",  "\",  "*",  and
671              "?",  and  it has to start with an alphabetic character. Invalid
672              job names will be denied at submit time.
673              If the -N option is not present, Grid Engine assigns the name of
674              the  job script to the job after any directory pathname has been
675              removed from the script-name. If the script is read  from  stan‐
676              dard input, the job name defaults to STDIN.
677              If  qsh  or  qlogin  is  run  without  the -N option, the string
678              `INTERACT' is assigned to the job.
679              If qrsh is run without the -N option, the resulting job name  is
680              determined  from  the  qrsh  command  line by using the argument
681              string up to the first occurrence of a semicolon  or  whitespace
682              and removing the directory pathname.
683
684              qalter allows changing this option even while the job executes.
685
686       -noshell
687              Available only for qrsh with a command line.
688
689              Do  not  start  the command line given to qrsh in a user's login
690              shell, i.e.  execute it without the wrapping shell.
691
692              This option can be used to speed up execution as some  overhead,
693              like the shell startup and sourcing the shell resource files, is
694              avoided.
695
696              This option can only be used if no shell-specific  command  line
697              parsing  is  required. If the command line contains shell syntax
698              like environment variable  substitution  or  (back)  quoting,  a
699              shell  must  be  started.   In  this case, either do not use the
700              -noshell option or include the shell call in the command line.
701
702              Example:
703              qrsh echo '$HOSTNAME'
704              Alternative call with the -noshell option
705              qrsh -noshell /bin/tcsh -f -c 'echo $HOSTNAME'
706
707       -nostdin
708              Available only for qrsh.
709
710              Suppress the input stream STDIN - qrsh will pass the  option  -n
711              to  the  rsh(1)  command. This is especially useful, if multiple
712              tasks are executed in parallel using qrsh,  e.g.  in  a  make(1)
713              process  -  it  would  be undefined, which process would get the
714              input.
715
716       -o [[hostname]:]path,...
717              Available for qsub, qsh, qrsh, qlogin and qalter only.
718
719              The path used for the standard output stream  of  the  job.  The
720              path  is  handled as described in the -e option for the standard
721              error stream.
722
723              By default the file  name  for  standard  output  has  the  form
724              job_name.ojob_id  and  job_name.ojob_id.task_id  for  array  job
725              tasks (see -t option below).
726
727              qalter allows changing this option even while the job  executes.
728              The modified parameter will only be in effect after a restart or
729              migration of the job, however.
730
731       -ot override_tickets
732              Available for qalter only.
733
734              Changes the number of override tickets for  the  specified  job.
735              Requires manager/operator privileges.
736
737       -P project_name
738              Available for qsub, qsh, qrsh, qlogin and qalter only.
739
740              Specifies  the project to which this job is assigned. The admin‐
741              istrator needs to give permission to individual users to  submit
742              jobs to a specific project. (see -aprj option to qconf(1)).
743
744       -p priority
745              Available for qsub, qsh, qrsh, qlogin and qalter only.
746
747              Defines  or  redefines the priority of the job relative to other
748              jobs.  Priority is an integer in the range -1023 to  1024.   The
749              default priority value for jobs is 0.
750
751              Users may only decrease the priority of their jobs.  Grid Engine
752              managers and administrators may also increase the priority asso‐
753              ciated  with  jobs.  If a pending job has higher priority, it is
754              earlier eligible for being dispatched by the Grid Engine  sched‐
755              uler.
756
757
758       -pe parallel_environment n[-[m]]|[-]m,...
759              Available for qsub, qsh, qrsh, qlogin and qalter only.
760
761              Start  parallel programming environment (PE). The range descrip‐
762              tor behind the PE name specifies the  number  of  parallel  pro‐
763              cesses  to  be  run.  Grid  Engine will allocate the appropriate
764              resources as  available.  The  sge_pe(5)  manual  page  contains
765              information  about the definition of PEs and about how to obtain
766              a list of currently valid PEs.
767              You can specify a PE name which  uses  the  wildcard  character,
768              "*".   Thus  the request "pvm*" will match any parallel environ‐
769              ment with a name starting with the string "pvm". In the case  of
770              multiple  parallel  environments  whose  names  match  the  name
771              string, the parallel environment with the most  available  slots
772              is chosen.
773              The  range  specification  is a list of range expressions of the
774              form "n-m", where n and m are positive, non-zero integers.   The
775              form "n" is equivalent to "n-n".  The form "-m" is equivalent to
776              "1-m".  The form "n-" is equivalent to "n-infinity".  The  range
777              specification  is  processed  as  follows: The largest number of
778              queues requested is checked first. If enough queues meeting  the
779              specified  attribute  list  are available, all are allocated. If
780              not, the next smaller number of queues is checked, and so forth.
781              If additional -l options are present, they restrict the  set  of
782              eligible queues for the parallel job.
783
784              qalter  allows changing this option even while the job executes.
785              The modified parameter will only be in effect after a restart or
786              migration of the job, however.
787
788       -q wc_queue_list
789              Available for qsub, qrsh, qsh, qlogin and qalter.
790
791              Defines  or redefines a list of cluster queues, queue domains or
792              queue instances which may be used to execute  this  job.  Please
793              find  a  description  of  wc_queue_list  in  sge_types(1).  This
794              parameter has all the properties of a resource request and  will
795              be merged with requirements derived from the -l option described
796              above.
797
798              qalter allows changing this option even while the job  executes.
799              The modified parameter will only be in effect after a restart or
800              migration of the job, however.
801
802       -R y[es]|n[o]
803              Available for qsub, qrsh, qsh, qlogin and qalter.
804
805              Indicates whether a reservation for this  job  should  be  done.
806              Reservation  is never done for immediate jobs, i.e. jobs submit‐
807              ted using the -now yes option.  Please note that  regardless  of
808              the reservation request, job reservation might be disabled using
809              max_reservation in sched_conf(5) and might be limited only to  a
810              certain number of high priority jobs.
811
812              By default jobs are submitted with the -R n option.
813
814       -r y[es]|n[o]
815              Available for qsub and qalter only.
816
817              Identifies  the  ability  of  a  job to be rerun or not.  If the
818              value of -r is 'yes', the job will  be  rerun  if  the  job  was
819              aborted without leaving a consistent exit state.  (This is typi‐
820              cally the case if the node on which the job is running crashes).
821              If  -r  is  'no',  the  job  will not be rerun under any circum‐
822              stances.
823              Interactive jobs submitted with qsh, qrsh or qlogin are not  re-
824              runnable.
825
826              qalter allows changing this option even while the job executes.
827
828
829
830       -sc variable[=value],...
831              Available for qsub, qsh, qrsh, qlogin and qalter only.
832
833              Sets  the given name/value pairs as the job's context. Value may
834              be omitted. Grid Engine replaces the  job's  previously  defined
835              context  with the one given as the argument.  Multiple -ac, -dc,
836              and -sc options may be given.  The order is important.
837              Contexts provide a way to dynamically attach  and  remove  meta-
838              information  to  and  from  a job. The context variables are not
839              passed to the job's execution context in its environment.
840
841              qalter allows changing this option even while the job executes.
842
843       -shell y[es]|n[o]
844              Available only for qsub.
845
846              -shell n causes qsub to execute the command line directly, as if
847              by  exec(2).   No  command  shell  will be executed for the job.
848              This option only applies when -b y is also used.  Without -b  y,
849              -shell n has no effect.
850
851              This  option can be used to speed up execution as some overhead,
852              like the shell startup and sourcing the shell resource files  is
853              avoided.
854
855              This  option  can only be used if no shell-specific command line
856              parsing is required. If the command line contains shell  syntax,
857              like  environment  variable  substitution  or  (back) quoting, a
858              shell must be started.  In this  case  either  do  not  use  the
859              -shell  n  option  or  execute the shell as the command line and
860              pass the path to the executable as a parameter.
861
862              If a job executed with the -shell n option fails due to  a  user
863              error,  such  as an invalid path to the executable, the job will
864              enter the error state.
865
866              -shell y cancels the effect of a previous -shell n.   Otherwise,
867              it has no effect.
868
869              See -b and -noshell for more information.
870
871       -soft  Available for qsub, qsh, qrsh, qlogin and qalter only.
872
873              Signifies  that  all resource requirements following in the com‐
874              mand line will be soft requirements and are to be filled  on  an
875              "as available" basis.
876              As  Grid  Engine scans the command line and script file for Grid
877              Engine options and parameters, it builds  a  list  of  resources
878              required  by  the job. All such resource requests are considered
879              as absolutely essential for the job to commence.  If  the  -soft
880              option  is  encountered  during  the  scan  then  all  following
881              resources are designated as "soft requirements"  for  execution,
882              or  "nice-to-have,  but  not  essential". If the -hard flag (see
883              above) is encountered at a later stage of the scan, all resource
884              requests  following  it once again become "essential". The -hard
885              and -soft options in effect act as "toggles" during the scan.
886
887       -sync y[es]|n[o]
888              Available for qsub.
889
890              -sync y causes qsub to wait for the job to complete before exit‐
891              ing.   If  the job completes successfully, qsub's exit code will
892              be that of the completed job.  If the job fails to complete suc‐
893              cessfully,  qsub  will  print out a error message indicating why
894              the job failed and will have an exit code  of  1.   If  qsub  is
895              interrupted, e.g. with CTRL-C, before the job completes, the job
896              will be canceled.
897              With the -sync n option, qsub will exit with an exit code  of  0
898              as  soon  as  the  job  is  submitted  successfully.  -sync n is
899              default for qsub.
900              If -sync y is used in conjunction with -now y, qsub will  behave
901              as though only -now y were given until the job has been success‐
902              fully scheduled, after which time qsub  will  behave  as  though
903              only -sync y were given.
904              If  -sync  y is used in conjunction with -t n[-m[:i]], qsub will
905              wait for all the job's tasks to complete before exiting.  If all
906              the  job's tasks complete successfully, qsub's exit code will be
907              that of the first completed job tasks with a non-zero exit code,
908              or  0 if all job tasks exited with an exit code of 0.  If any of
909              the job's tasks fail to complete successfully, qsub  will  print
910              out  an  error message indicating why the job task(s) failed and
911              will have an exit code of 1.  If qsub is interrupted, e.g.  with
912              CTRL-C, before the job completes, all of the job's tasks will be
913              canceled.
914
915       -S [[hostname]:]pathname,...
916              Available for qsub, qsh and qalter.
917
918              Specifies the interpreting shell for the job. Only one  pathname
919              component  without  a  host specifier is valid and only one path
920              name for a given host is allowed. Shell paths with host  assign‐
921              ments  define  the interpreting shell for the job if the host is
922              the execution host. The shell path without host specification is
923              used  if  the  execution  host  matches none of the hosts in the
924              list.
925
926              Furthermore, the pathname can be constructed  with  pseudo-envi‐
927              ronment-variables as described for the -e option above.
928
929              In  the  case of qsh the specified shell path is used to execute
930              the corresponding command interpreter in the xterm(1)  (via  its
931              -e option) started on behalf of the interactive job.
932
933              qalter  allows changing this option even while the job executes.
934              The modified parameter will only be in effect after a restart or
935              migration of the job, however.
936
937       -t n[-m[:s]]
938              Available for qsub and qalter only.
939
940              Submits  a so called Array Job, i.e. an array of identical tasks
941              being differentiated only by an index number and  being  treated
942              by Grid Engine almost like a series of jobs. The option argument
943              to -t specifies the number of array job tasks and the index num‐
944              ber  which  will be associated with the tasks. The index numbers
945              will be exported to the job tasks via the  environment  variable
946              SGE_TASK_ID.  The  option arguments n, m and s will be available
947              through the environment variables SGE_TASK_FIRST,  SGE_TASK_LAST
948              and  SGE_TASK_STEPSIZE.
949
950              The following restrictions apply to the values n and m:
951
952                     1 <= n <= MIN(2^31-1, max_aj_tasks)
953                     1 <= m <= MIN(2^31-1, max_aj_tasks)
954                     n <= m
955
956              max_aj_tasks  is  defined  in  the  cluster  configuration  (see
957              sge_conf(5))
958
959              The task id range specified in the option argument may be a sin‐
960              gle  number,  a  simple  range of the form n-m or a range with a
961              step size. Hence, the task id range specified  by  2-10:2  would
962              result in the task id indexes 2, 4, 6, 8, and 10, for a total of
963              5  identical  tasks,  each   with   the   environment   variable
964              SGE_TASK_ID containing one of the 5 index numbers.
965
966              All  array  job  tasks  inherit  the  same resource requests and
967              attribute definitions as specified in the qsub or qalter command
968              line, except for the -t option. The tasks are scheduled indepen‐
969              dently and, provided enough resources exist, concurrently,  very
970              much  like  separate  jobs.   An array job or a sub-array can be
971              accessed, however,  as a single unit by commands like qmod(1) or
972              qdel(1).  See the corresponding manual pages for further detail.
973
974              Array  jobs are commonly used to execute the same type of opera‐
975              tion on varying input data sets correlated with the  task  index
976              number. The number of tasks in a array job is unlimited.
977
978              STDOUT  and  STDERR of array job tasks will be written into dif‐
979              ferent files with the default location
980
981              <jobname>.['e'|'o']<job_id>'.'<task_id>
982
983              In order to change this default, the  -e  and  -o  options  (see
984              above)  can  be  used together with the pseudo-environment-vari‐
985              ables  $HOME,  $USER,   $JOB_ID,   $JOB_NAME,   $HOSTNAME,   and
986              $SGE_TASK_ID.
987
988              Note, that you can use the output redirection to divert the out‐
989              put of all tasks into the same file, but the result of  this  is
990              undefined.
991
992
993
994       -terse
995              Available for qsub only.
996
997              Causes  qsub to display only the job-id of the job being submit‐
998              ted rather than the regular "Your job ..." string.  In  case  of
999              an error the error is reported on stderr as usual.
1000              This  can be helpful for scripts which need to parse qsub output
1001              to get the job-id.
1002
1003       -u username,...
1004              Available for qalter only. Changes are only made on  those  jobs
1005              which  were  submitted  by  users specified in the list of user‐
1006              names.  For managers it is possible to use  the  qalter  -u  '*'
1007              command to modify all jobs of all users.
1008
1009              If you use the -u switch it is not permitted to specify an addi‐
1010              tional wc_job_range_list.
1011
1012       -v variable[=value],...
1013              Available for qsub, qsh, qrsh and qalter.
1014
1015              Defines or redefines the environment variables to be exported to
1016              the  execution  context of the job.  If the -v option is present
1017              Grid Engine will add the environment variables defined as  argu‐
1018              ments  to  the switch and, optionally, values of specified vari‐
1019              ables, to the execution context of the job.
1020
1021              qalter allows changing this option even while the job  executes.
1022              The modified parameter will only be in effect after a restart or
1023              migration of the job, however.
1024
1025       -verbose
1026              Available only for qrsh and qmake(1).
1027
1028              Unlike qsh and qlogin, qrsh does not  output  any  informational
1029              messages  while  establishing  the  session,  compliant with the
1030              standard rsh(1) and rlogin(1) system calls.  If the option -ver‐
1031              bose  is  set,  qrsh  behaves  like the qsh and qlogin commands,
1032              printing information  about  the  process  of  establishing  the
1033              rsh(1) or rlogin(1) session.
1034
1035       -verify
1036              Available for qsub, qsh, qrsh, qlogin and qalter.
1037
1038              Instead  of submitting a job, this option prints detailed infor‐
1039              mation about the would-be job as though qstat(1) -j  were  used,
1040              including  the effects of command-line parameters and the exter‐
1041              nal environment.
1042
1043       -V     Available for qsub, qsh, qrsh with command, qalter and qresub.
1044
1045              Specifies that all environment variables active within the  qsub
1046              utility be exported to the context of the job.
1047
1048       -w e|w|n|v
1049              Available for qsub, qsh, qrsh, qlogin and qalter.
1050
1051              Specifies  a validation level applied to the job to be submitted
1052              (qsub, qlogin, and qsh) or the specified  queued  job  (qalter).
1053              The information displayed indicates whether the job can possibly
1054              be scheduled assuming  an  empty  system  with  no  other  jobs.
1055              Resource requests exceeding the configured maximal thresholds or
1056              requesting unavailable resource attributes are  possible  causes
1057              for jobs to fail this validation.
1058
1059              The  specifiers  e,  w,  n and v define the following validation
1060              modes:
1061
1062              `e'  error - jobs with invalid requests will be
1063                   rejected; the default for qrsh, qsh
1064                   and qlogin.
1065              `w'  warning - only a warning will be displayed
1066                   for invalid requests.
1067              `n'  none - switches off validation; the default for
1068                   qsub and qalter.
1069              `v'  verify - does not submit the job but prints an
1070                   extensive validation report.
1071
1072              Note, that the necessary checks are  performance  consuming  and
1073              hence the checking is switched off by default.
1074
1075              Note  also,  that the reasons for job requirements being invalid
1076              with respect to resource availability of queues are displayed in
1077              the  "-w  v" case using the format as described for the qstat(1)
1078              -F option (see description of Full Format in section OUTPUT FOR‐
1079              MATS of the qstat(1) manual page.
1080
1081       -wd working_dir
1082              Available for qsub, qsh, qrsh and qalter only.
1083
1084              Execute  the  job  from  the directory specified in working_dir.
1085              This switch will activate Grid Engine's path aliasing  facility,
1086              if  the  corresponding  configuration  files  are  present  (see
1087              sge_aliases(5)).
1088
1089              qalter allows changing this option even while the job  executes.
1090              The modified parameter will only be in effect after a restart or
1091              migration of the job, however.
1092
1093       command
1094              Available for qsub and qrsh only.
1095
1096              The job's scriptfile or binary.  If not present or if the  oper‐
1097              and  is  the  single-character string '-', qsub reads the script
1098              from standard input.
1099
1100       command_args
1101              Available for qsub, qrsh and qalter only.
1102
1103              Arguments to the job. Not valid if the script  is  entered  from
1104              standard input.
1105
1106              qalter  allows changing this option even while the job executes.
1107              The modified parameter will only be in effect after a restart or
1108              migration of the job, however.
1109
1110       xterm_args
1111              Available for qsh only.
1112
1113              Arguments to the xterm(1) executable, as defined in the configu‐
1114              ration.  For details, refer to sge_conf(5)).
1115

ENVIRONMENTAL VARIABLES

1117       SGE_ROOT       Specifies the location of the Grid Engine standard  con‐
1118                      figuration files.
1119
1120       SGE_CELL       If  set,  specifies  the  default  Grid  Engine cell. To
1121                      address a Grid Engine cell qsub, qsh, qlogin  or  qalter
1122                      use (in the order of precedence):
1123
1124                             The name of the cell specified in the environment
1125                             variable SGE_CELL, if it is set.
1126
1127                             The name of the default cell, i.e. default.
1128
1129
1130       SGE_DEBUG_LEVEL
1131                      If set, specifies that debug information should be writ‐
1132                      ten  to stderr. In addition the level of detail in which
1133                      debug information is generated is defined.
1134
1135       SGE_QMASTER_PORT
1136                      If set, specifies the tcp port on  which  sge_qmaster(8)
1137                      is  expected to listen for communication requests.  Most
1138                      installations will use a services map entry for the ser‐
1139                      vice "sge_qmaster" instead to define that port.
1140
1141       DISPLAY        For qsh jobs the DISPLAY has to be specified at job sub‐
1142                      mission.  If the DISPLAY is not set by using  the  -dis‐
1143                      play or the -v switch, the contents of the DISPLAY envi‐
1144                      ronment variable are used as default.
1145
1146       In addition to those environment variables specified to be exported  to
1147       the  job  via the -v or the -V option (see above) qsub, qsh, and qlogin
1148       add the following variables with the indicated values to  the  variable
1149       list:
1150
1151
1152       SGE_O_HOME     the home directory of the submitting client.
1153
1154       SGE_O_HOST     the  name  of the host on which the submitting client is
1155                      running.
1156
1157       SGE_O_LOGNAME  the LOGNAME of the submitting client.
1158
1159       SGE_O_MAIL     the MAIL of the submitting  client.  This  is  the  mail
1160                      directory of the submitting client.
1161
1162       SGE_O_PATH     the executable search path of the submitting client.
1163
1164       SGE_O_SHELL    the SHELL of the submitting client.
1165
1166       SGE_O_TZ       the time zone of the submitting client.
1167
1168       SGE_O_WORKDIR  the  absolute  path  of the current working directory of
1169                      the submitting client.
1170
1171       Furthermore, Grid Engine sets additional variables into the job's envi‐
1172       ronment, as listed below.
1173
1174       SGE_ARCH       The  Grid  Engine architecture name of the node on which
1175                      the job is  running.  The  name  is  compiled  into  the
1176                      sge_execd(8) binary.
1177
1178       SGE_CKPT_ENV   Specifies  the  checkpointing  environment  (as selected
1179                      with the -ckpt option) under which a  checkpointing  job
1180                      executes. Only set for checkpointing jobs.
1181
1182       SGE_CKPT_DIR   Only  set for checkpointing jobs. Contains path ckpt_dir
1183                      (see checkpoint(5) ) of the checkpoint interface.
1184
1185       SGE_STDERR_PATH
1186                      the pathname of the file to  which  the  standard  error
1187                      stream of the job is diverted. Commonly used for enhanc‐
1188                      ing the output with error messages from prolog,  epilog,
1189                      parallel   environment   start/stop   or   checkpointing
1190                      scripts.
1191
1192       SGE_STDOUT_PATH
1193                      the pathname of the file to which  the  standard  output
1194                      stream of the job is diverted. Commonly used for enhanc‐
1195                      ing the output with messages from prolog, epilog, paral‐
1196                      lel environment start/stop or checkpointing scripts.
1197
1198       SGE_STDIN_PATH the  pathname  of the file from which the standard input
1199                      stream of the job is taken. This variable might be  used
1200                      in  combination with SGE_O_HOST in prolog/epilog scripts
1201                      to transfer the input file from the submit to the execu‐
1202                      tion host.
1203
1204       SGE_JOB_SPOOL_DIR
1205                      The  directory  used  by  sge_shepherd(8)  to  store job
1206                      related data during job  execution.  This  directory  is
1207                      owned by root or by a Grid Engine administrative account
1208                      and commonly is not open for read  or  write  access  to
1209                      regular users.
1210
1211       SGE_TASK_ID    The  index  number of the current array job task (see -t
1212                      option above). This is an unique number  in  each  array
1213                      job  and  can  be used to reference different input data
1214                      records, for example. This environment variable  is  set
1215                      to  "undefined"  for  non-array  jobs. It is possible to
1216                      change the predefined value of this variable with -v  or
1217                      -V (see options above).
1218
1219       SGE_TASK_FIRST The  index  number  of  the first array job task (see -t
1220                      option above). It is possible to change  the  predefined
1221                      value  of  this  variable  with  -v  or  -V (see options
1222                      above).
1223
1224       SGE_TASK_LAST  The index number of the last  array  job  task  (see  -t
1225                      option  above).  It is possible to change the predefined
1226                      value of this  variable  with  -v  or  -V  (see  options
1227                      above).
1228
1229       SGE_TASK_STEPSIZE
1230                      The  stepsize  of  the  array  job specification (see -t
1231                      option above). It is possible to change  the  predefined
1232                      value  of  this  variable  with  -v  or  -V (see options
1233                      above).
1234
1235       ENVIRONMENT    The ENVIRONMENT variable is set  to  BATCH  to  identify
1236                      that  the  job  is being executed under Grid Engine con‐
1237                      trol.
1238
1239       HOME           The user's home directory path from the passwd(5) file.
1240
1241       HOSTNAME       The hostname of the node on which the job is running.
1242
1243       JOB_ID         A unique identifier assigned by the sge_qmaster(8)  when
1244                      the  job  was submitted. The job ID is a decimal integer
1245                      in the range 1 to 99999.
1246
1247       JOB_NAME       The job name.  For batch jobs or jobs submitted by  qrsh
1248                      with a command, the job name is built as basename of the
1249                      qsub script filename resp. the qrsh command.  For inter‐
1250                      active  jobs  it  is  set to `INTERACTIVE' for qsh jobs,
1251                      `QLOGIN' for qlogin jobs and  `QRLOGIN'  for  qrsh  jobs
1252                      without a command.
1253
1254                      This default may be overwritten by the -N.  option.
1255
1256       LOGNAME        The user's login name from the passwd(5) file.
1257
1258       NHOSTS         The number of hosts in use by a parallel job.
1259
1260       NQUEUES        The number of queues allocated for the job (always 1 for
1261                      serial jobs).
1262
1263       NSLOTS         The number of queue slots in use by a parallel job.
1264
1265       PATH           A default shell search path of:
1266                      /usr/local/bin:/usr/ucb:/bin:/usr/bin
1267
1268       SGE_BINARY_PATH
1269                      The path where the Grid Engine binaries  are  installed.
1270                      The value is the concatenation of the cluster configura‐
1271                      tion  value  binary_path  and  the   architecture   name
1272                      $SGE_ARCH environment variable.
1273
1274       PE             The  parallel  environment  under which the job executes
1275                      (for parallel jobs only).
1276
1277       PE_HOSTFILE    The path of a file containing the definition of the vir‐
1278                      tual parallel machine assigned to a parallel job by Grid
1279                      Engine. See the description of the $pe_hostfile  parame‐
1280                      ter in sge_pe(5) for details on the format of this file.
1281                      The environment variable is only available for  parallel
1282                      jobs.
1283
1284       QUEUE          The  name  of the cluster queue in which the job is run‐
1285                      ning.
1286
1287       REQUEST        Available for batch jobs only.
1288
1289                      The request name of a  job  as  specified  with  the  -N
1290                      switch  (see  above)  or  taken  as  the name of the job
1291                      script file.
1292
1293       RESTARTED      This variable is set to 1 if a job was restarted  either
1294                      after  a  system crash or after a migration in case of a
1295                      checkpointing job. The variable has the value  0  other‐
1296                      wise.
1297
1298       SHELL          The  user's  login  shell from the passwd(5) file. Note:
1299                      This is not necessarily the shell in use for the job.
1300
1301       TMPDIR         The absolute path to the job's temporary working  direc‐
1302                      tory.
1303
1304       TMP            The same as TMPDIR; provided for compatibility with NQS.
1305
1306       TZ             The  time  zone  variable  imported from sge_execd(8) if
1307                      set.
1308
1309       USER           The user's login name from the passwd(5) file.
1310

RESTRICTIONS

1312       There is no controlling terminal for batch jobs under Grid Engine,  and
1313       any  tests  or  actions  on  a controlling terminal will fail. If these
1314       operations are in your .login or .cshrc file, they may cause  your  job
1315       to abort.
1316
1317       Insert the following test before any commands that are not pertinent to
1318       batch jobs in your .login:
1319
1320              if ( $?JOB_NAME) then
1321                     echo "Grid Engine spooled job"
1322                     exit 0
1323              endif
1324
1325       Don't forget to set your shell's search path  in  your  shell  start-up
1326       before this code.
1327

EXIT STATUS

1329       The following exit values are returned:
1330
1331       0    Operation was executed successfully.
1332
1333       25   It was not possible to register a new job according to the config‐
1334            ured max_u_jobs or max_jobs limit. Additional information  may  be
1335            found in sge_conf(5)
1336
1337       >0   Error occurred.
1338

EXAMPLES

1340       The following is the simplest form of a Grid Engine script file.
1341
1342       =====================================================
1343
1344
1345       #!/bin/csh
1346          a.out
1347
1348
1349       =====================================================
1350
1351       The next example is a more complex Grid Engine script.
1352
1353       =====================================================
1354
1355       #!/bin/csh
1356
1357       # Which account to be charged cpu time
1358       #$ -A santa_claus
1359
1360       # date-time to run, format [[CC]yy]MMDDhhmm[.SS]
1361       #$ -a 12241200
1362
1363       # to run I want 6 or more parallel processes
1364       # under the PE pvm. the processes require
1365       # 128M of memory
1366       #$ -pe pvm 6- -l mem=128
1367
1368       # If I run on dec_x put stderr in /tmp/foo, if I
1369       # run on sun_y, put stderr in /usr/me/foo
1370       #$ -e dec_x:/tmp/foo,sun_y:/usr/me/foo
1371
1372       # Send mail to these users
1373       #$ -M santa@nothpole,claus@northpole
1374
1375       # Mail at beginning/end/on suspension
1376       #$ -m bes
1377
1378       # Export these environmental variables
1379       #$ -v PVM_ROOT,FOOBAR=BAR
1380
1381       # The job is located in the current
1382       # working directory.
1383       #$ -cwd
1384
1385       a.out
1386
1387       ==========================================================
1388
1389

FILES

1391       $REQUEST.oJID[.TASKID]      STDOUT of job #JID
1392       $REQUEST.eJID[.TASKID]      STDERR of job
1393       $REQUEST.poJID[.TASKID]     STDOUT of par. env. of job
1394       $REQUEST.peJID[.TASKID]     STDERR of par. env. of job
1395       $REQUEST.hostsJID[.TASKID]  hosts file of par. env. of job
1396
1397       $cwd/.sge_aliases        cwd path aliases
1398       $cwd/.sge_request        cwd default request
1399       $HOME/.sge_aliases       user path aliases
1400       $HOME/.sge_request       user default request
1401       $SGE_ROOT/$SGE_CELL/common/sge_aliases
1402                                cluster path aliases
1403       $SGE_ROOT/$SGE_CELL/common/sge_request
1404                                cluster default request
1405       $SGE_ROOT/$SGE_CELL/common/act_qmaster
1406                                Grid Engine master host file
1407

SEE ALSO

1409       sge_intro(1),  qconf(1), qdel(1), qhold(1), qmod(1), qrls(1), qstat(1),
1410       accounting(5), sge_aliases(5), sge_conf(5), sge_request(5),  sge_pe(5),
1411       complex(5).
1412
1414       If  configured correspondingly, qrsh and qlogin contain portions of the
1415       rsh, rshd, telnet and telnetd code copyrighted by The  Regents  of  the
1416       University  of  California.  Therefore, the following note applies with
1417       respect to qrsh and qlogin: This product includes software developed by
1418       the University of California, Berkeley and its contributors.
1419
1420       See   sge_intro(1)   as   well   as   the   information   provided   in
1421       $SGE_ROOT/3rd_party/qrsh and $SGE_ROOT/3rd_party/qlogin for a statement
1422       of further rights and permissions.
1423
1424
1425
1426GE 6.1                   $Date: 2007/07/19 08:17:16 $                SUBMIT(1)
Impressum