NAME qsub - submit a job to the queue system 'fair que' SYNOPSIS qsub [-p ncpus] [-m mem] [-d disk] [-t time[s|m|h|d]] [-u user] [-q host1[,host2]] [[filename] | -i] DESCRIPTION The qsub utility submits a batch job to the queue system 'fair que'. The job will be executed on the designated execution server as soon as the necessary resources are available. Three types of resources are recognized: processors, memory and local disk space. In order to make efficient job scheduling possible, the user must estimate how long the execution time (wall clock time) of the job will be. If the batch job is submitted successfully, qsub returns a numeric job id. Otherwise an error report is printed. OPTIONS The following options are supported: -p ncpus Specify the number of processors that the job requires. The default value is 1. -m mem Specify how much physical memory the job needs. Memory is measured in MB. This flag is mandatory. -d disk Reserve disk MB of local disk space for the job. If this flag is not included no local disk space will be reserved. -t duration Inform the scheduling system about the execution time of the job. The syntax for duration is an integer number immediately followed by the letter s, m, h or d meaning seconds, minutes, hours or days, respectively. This flag is mandatory. There is no default value. -u user If the submitting user has several queue system accounts, one of them must be specified by this flag. Normally each user has only one account, so this flag is seldom needed. -q host1[,host2...] Tell the scheduler that this job may only be run on the hosts given as arguments to the -q flag. If this flag is not present, the scheduler is free to choose the first host that becomes available. -i Request an interactive session on one of the execution hosts. No filename must be given. When the reserved resources are available, a letter with login instructions is sent to the submitting user. The user should then login within half an hour; otherwise the job is cancelled automatically be the queue system. An interactive session starts when the letter is sent to the user. It ends when the user logs out and all background jobs that were started during the session has ended. The reserved resources are are reserved for exclusive use, so the cost per wall-clock hour is the same as the batch job cost. OPERANDS The following operand is supported: file The path name of the job. A job is normally a shell script, even though binary executables are allowed. If no file is specified, command lines are read from the standard input. FILE FORMATS If the submitted job is a shell script, it is possible to specify the resource requirements by embedding directives in file. The following directives are supported: #@ CPU ncpu #@ MEMORY mem #@ DISK disk #@ TIME duration Because they start with a comment character, they are ignored by the shell. If the same resource appears both on the command line and as a directive, the value specified on the command line has precedence. EXAMPLES 1. The following command: example% qsub -t 5m myjob submits the job 'myjob' in the current directory to the queue system. One cpu is reserved, but no memory or disk. The specified execution time is five minutes. 2. The following command: example% qsub -p 4 -m 840 -d 500 -t 8h large submits the job 'large' for parallel execution on four processors. The job is allowed to use a total of 840 MB memory and 500 MB local disk space. The estimated run time is eight hours. ENVIRONMENT When the qsub command is run, the current directory is saved. Before the job is started to the execution server, the queue system attempts to 'cd' to the same directory. In addition, the following environment variables are defined: CPU contains the number of reserved processors. MEMORY is set to the reserved memory in MB. DISK is set to the reserved local disk space in MB. TIME contains the estimated execution time in seconds. TEMP_DIR points to a directory that is suitable for local storage of up to $DISK MB of data. JOBID contains the numeric job id. MP_SET_NUMTHREADS contains the number of reserved processors (IRIX only.) FILES Output (stdout and stderr) from the running job is stored in the file out. in the current directory. If the current directory is not writable, the file is created in the home directory of the user instead. SEE ALSO qdel, qshow NOTES If the job should exceed the estimated running time, no specific action is taken in the current release of 'fair que'. However a job running on overtime may delay other jobs, and because the queue system has no way to know when the job will eventually terminate, new jobs cannot be started in order to fill the gap in schedule. Therefore running on overtime costs extra (each overtime hour is counted twice.) If the job terminates before the estimated execution time has elapsed, the user is only charged for the time spent so far. Users are encouraged to try to make good estimates of resource requirements, because they make it possible to schedule the jobs more efficiently. This decreases the waiting time for all users. Note that the compilers by default may use up to four processors in parallel during the IPA optimisation phase. A serial jobs that runs the compilers may therefore have to limit the amount of parallellism using the flag -IPA:max_job=1 (otherwise the queue system may kill the job due to cpu over utilization.) This flag should only be added when IPA is used (i.e. together with the -Ofast or -IPA flags.) (c) Lennart Bengtsson Last change: 3 Dec 1998 CTH