qsub Interface - Intergraph Batch Services - Help

Intergraph Batch Services Help

Language
English
Product
Intergraph Batch Services
Search by Category
Help

The qsub utility accepts as an argument the file name of a shell script to execute. If no such argument is given, the utility reads from stdin until an end of file is encountered, and uses this input as the shell script. By default, the job name is the name of the shell script. If the shell script is read from stdin, STDIN is the default job name.

The name of a script should not contain any characters that have special meaning to the shell associated with the queue.

The qsub utility returns a unique job-identification string (job-id). You can use the job-ID to track the job.

The return value indicates the success or failure of the submission. If qsub is invoked without the -z option, qsub returns a message informing you whether or not the job submission was successful.

If an option requires an argument, you must specify the argument when using the option. For example, if you specify qsub -j but do not specify y|n, any options following -j will cause an error. The qsub utility accepts the following options:

-A account -- Defines an account string to use. The account can be an arbitrary string of unlimited length.

-a time -- Does not run the batch request until the specified date-time parameter. If a date-time specification is composed of two or more words, the date-time specification must be in double quotes as in: "-a July, 4, 2026 12:31".

-C directive_prefix -- Defines the string of characters used to identify qsub options that appear on the first line of a shell script. The default is the value of the environment variable POSIX2_PBS_DPREFIX. If this variable is not defined, then the character string "#@$" is be the default.

-e file -- Saves stderr into file. A remote file name may be specified, as described in Name Syntax. If a local file is specified without a full pathname, the current working directory is used. The default stderr file name is "jobname.e." This name may be truncated due to file system limitations. If the filename for stderr is invalid, the file is placed into the current user's home directory on the execution computer.

-eo -- Writes stderr to stdout.

-h -- Submits the job with a user hold in place. The job will not run until the hold is released. The hold can be released using either qmgr or the Batch Manager user interface.

-j y|n -- Specifies whether or not to join (write) stderr to stdout. The default is not to join stderr to stdout.

-k keep_list -- Defines which files to retain on the execution computer. keep_list is a string which can contain one of the following:

  • n -- Do not keep any files. This is the default.

  • eo -- Keep both stderr and stdout.

  • e -- Same as -ke (described below). This option has no effect if the "-eo" flag is used, or if an explicit computer name has been given with the "-e" option.

  • o -- Same as -ko (described below). This option has no effect if an explicit computer name has been given with the "-o" option.

-ke -- Retains the stderr file on the execution computer, in the directory in which the job was executed. This option has no effect if the "-eo" flag is used, or if an explicit computer name has been given with the "-e" option.

-ko -- Retains the stdout file on the execution computer, in the directory in which the job was executed.

-ln priority -- Sets the execution priority. The default run time priority is set by the queue. A valid priority is a number in the range -20 to 20, or one of the following priority names (corresponding numerical values are provided):

priority name

valid ranges

will be run at

IDLE

10 ...20

20

NORMAL

0...9

0

HIGH

-1...-10

-10

REALTIME

-11...-20

-20

  • A REALTIME process preempts all other processes, including the operating system. Intergraph recommends that you avoid using the REALTIME priority.

  • If a job is submitted with a run priority that does not match the run priority of the queue to which it is submitted, the submission fails and qsub will return an error.

-M mail_list -- Defines a list of addresses to which mail is sent, where mail_list is a list of mail addresses, separated by semi-colons. Supported mail addresses are SMTP format(user@host) and messages via the event log (\\host). If no mailing address is specified, the default mail address is the Universal Naming Convention (UNC) name of the local host (\\local_host). Because of Windows's built-in security, messages will be placed in the event log of the batch server where the job executed.

-m mailoptions -- Defines when or if mail should be sent about the submitted job. Mailoptions may include any of the following:

  • b -- Sends mail when the job begins (same as -mb).

  • e -- Sends mail when the job ends (same as -me).

  • a -- Sends mail if the job is aborted (same as -ma). This is the default.

  • n -- Sends no mail

-mb -- Sends mail when the job begins (same as -m b).

-me -- Sends mail when the job ends (same as -m e).

-mu mailaddress -- Specifies the user or users to whom mail will be sent. Supported mail addresses are SMTP format and messages via the event log. If no mailing address is specified, the default mail address is \\local_host. Messages that are sent using the default address can be viewed in the local host's event log.

-N name -- Names the batch job. The job name is not limited in length. The default job name is the basename of the submitted shell script, or STDIN if the script is read from the command line. This option is the same as "-r name."

-nr -- Specifies not to restart the job. By default, jobs are restartable.

-o file -- Writes stdout to the specified file. A remote file name may be specified as described in Name Syntax. If a local file is specified without a full pathname, the current working directory is used. The default stdout file name is "jobname.o" (the name of the job). This name may be truncated due to file system limitations. If the filename for stdout is invalid, the file is placed into the current user's home directory on the execution computer.

-O descriptor -- Specifies reoccurrence of a job. The descriptor takes the form of fFFiIImMMwWWyYY, where "f" is a flag and the value for FF is a hexadecimal number and can have the value 00 (hourly), 02 (daily), 04 (weekly), 28 (specific monthly), 30 (specific yearly), 48 (determined monthly), and 50 (determined yearly). "i" is the interval value. "m" is the monthly interval. "w" is the weekly interval and is Hexadecimal. It contains either the day of the week mask, or the day of the month value. The "y" value is the month of the year in decimal. -O f01i01m00w3ey00 would cause the job to reoccur every hour on Monday through Friday. For more information on reoccurrence descriptor, see The reoccurrence descriptor table in Handling Batch Job Output Files.

-p priority -- Specifies the scheduling priority for the job. The default scheduling priority is set by the batch queue to which the job is submitted. The scheduling priority must be in the range of -1024 to 1023.

-q queue -- Specifies the queue to which the job is submitted. Queue may take one of the following forms:

  • A simple queue name which submits the job to the specified queue on the local server

  • A remote queue name that submits the job to the specified queue on the remote server. A remote queue may be specified as described in Name Syntax.

  • If -q is not specified, the job is submitted to the default queue on the local batch server.

-r name -- Names the batch job. The default name is the filename of the script file. This option is the same as "-N name."

-re -- Writes the stderr file directly instead of spooling it. The -re flag forces the stderr file to be sent to the destination directory as output is generated during execution. This option is only available when the execution computer is the local computer.

-ro -- Writes the stdout file directly instead of spooling it. The -ro flag forces the stdout file to be sent to the destination directory as the output is generated during execution. This option is only available when the execution computer is the local computer.

-s shell -- Specifies the name of the command interpreter to use. If the specified shell is on a removable media, a dialog will prompt you to insert the media.

-si destfile=sourcefile -- Copies sourcefile to destfile before the job is executed. Destfile specifies a pathname on the execution computer. Sourcefile may be a remote file as described in Name Syntax. See File Staging for more information.

-so destfile=sourcefile -- Moves sourcefile to destfile after job execution. Destfile may be a remote file as described in Name Syntax. Sourcefile specifies a pathname on the execution computer. See File Staging for more information.

-V -- Exports all current environment variables with the job. This option is the same as "-x."

-v var_list -- Exports the named environment variables with the job. The varlist is a comma separated list of environment variables of the form name[=value]. The value is optional. If no value is specified, it will be taken from the current environment. In the case of conflicting environment variable names, values specified with -v take precedence over those imported with -x or -V. Values on the command line take precedence over those specified by embedded options in the script.

-x -- Exports all current environment variables with the job. This option is the same as "-V."

-z -- Suppresses warning and error messages

Examples:

qsub -q \\gene\myqueue -O f01i01m00w3ey00 "c:\users\default\myscript.bat<tab>/help” will cause the script file "myscript.bat" to execute every hour starting at the current time on Monday through Friday. The "<tab>" represents the tab character, and is used to separate arguments from the script name.