7.20 qsub Job Submit Command

Synopsis

qsub [options] [job_file] [parameters]

Description

The qsub command submits a job.

Options

-sys subsystem-number

In the system with multiple subsystems, this option is used to specify the subsystem that you want to operate. Specify the target subsystem number using a range of 0 to 9. If omitted, the default is subsystem 0.

-C comment

Adds a comment to the job. Comments can be specified using up to 511 bytes or less. If blanks are contained in the comment, enclose the entire comment in double quotation marks. An example is given below.

-C "This is a comment."

If no comment is specified in this option, the Job Execution Control searches for the environment variable "JC_COMMENT". If this environment variable is found, the string in JC_COMMENT is recognized as the comment.

If the command contains double quotation marks as characters, put a backslash before each quotation mark so that the double quotation marks are treated as characters. By putting a backslash before each quotation mark, the double quotation marks are treated differently from those for enclosing the entire comment. An example is given below.

-C "This is a \"client listing\""

-ch client-hostname

Specifies the client host name in order to identify the host who requested the job execution.

The client host name must be specified using up to 64 bytes.

When the JCL file is submitted, this option will be valid and the JCL host statement that was specified will be invalid.

-cu client-username

Specifies the client user name in order to identify the user who requested the job execution. The client user name must be specified using up to 64 bytes.

When the JCL file is submitted, this option will be valid and the JCL user statement that was specified will be invalid.

Only the system administrator (user belonging to the Administrator group or superuser) can specify this option.

-dp dispatch-priority

[Windows]

Specify the priority of the threads of the program that are to be executed from the job by specifying an integer value between 0 and 4. The greater the value is, the higher the priority is.

When the JCL file is submitted, this option will be valid and the JCL dprty statement that was specified will be invalid.

If this option is omitted, the default value defined in the "Specify default job priority" (also, can be defined using the dfltdprty operand with queue parameter in the Job Execution Control initialization file) in the [Create Queue] or [Edit Queue] window is set. However, if the dprty statement was specified in the JCL file, this dprty statement will be valid.

[UNIX]

Specify the priority of the processes executed from the job by specifying an integer value between -20 and 19. The priority means the CPU allocation priority during the job execution, and the lowest dispatch priority is 19 and the highest is -20.

When the JCL file is submitted, this option will be valid and the JCL dprty statement that was specified will be invalid.

If this option is omitted, the default value defined in the "Specify default job priority" (also, can be set using the dfltdprty operand with queue parameter in the Job Execution Control initialization file) in the [Create Queue] or [Edit Queue] window is set. However, if the dprty statement was specified in the JCL file, this dprty statement will be valid.

-e [drive-letter:] [path-name] stderr-file [Windows]
-e [path-name] stderr-file [UNIX]

Outputs the standard error output, which is generated during the job execution, as a file named stderr-file to the path name specified at "path-name".

If the path-name is omitted, the current working directory used in submitting the job is assumed as the path name.

If failed to output to the specified path name, it is output to the current working directory.

If this option is omitted, the file name of the standard error output is "job name.ejob number". For example, if the job name is "ACCOUNT", and its job number is "20", the file name of this standard error output is "ACCOUNT.e20".

This option cannot be specified together with the -eo option.

-env environment variable configuration file name [-jo position number]

Specifies an environment variable for a job when submitting a job with the qsub command.

This cannot be used in the job submission API (Mp_SubmitJob).

Environment variables passed to jobs are first specified in a file in the format described in "7.20.1 Environment Variable Configuration File for the Job Execution Control", then the name of the environment variable configuration file is specified when a job is submitted.

It is also possible to specify more than one pattern of environment variable within one environment variable configuration file, and it is possible to specify which pattern of environment variable is to be used with a number.

Up to 32 environment variables can be specified per job.
Up to 64 bytes can be specified for the environment variable names for each environment variable.
Up to 256 bytes can be specified for the environment variable values for each environment variable.
Up to 255 patterns can be specified within each environment variable configuration file.

environment variable configuration file name

Specify when giving a job an environment variable.

If the -env option is specified, it is necessary to specify the environment variable configuration file name immediately after this option. If the environment variable configuration file name is not specified or there is an error in the file name, the job will not be submitted.

The environment variable configuration file stores the environment variable names and environment variable values given to a job. Refer to "7.20.1 Environment Variable Configuration File for the Job Execution Control" for the format.

position number

Specify which of the patterns in the environment variable configuration file specified by the -env option to use. The first pattern will be used if this option is omitted.

-eo

Outputs the standard error output to a standard output file.

Cannot be specified together with the -e option.

-Id HHMM

Specifies the cut-off time of the job. The job on which the cut-off time is specified is cancelled with the completion code "0x40000322" when the specified cut-off time is reached.

In "HH", specify any value between 00 and 23 (hour), and in "MM", specify any value between 00 and 59 (minute).

This option cannot be specified with the -lt option or when the [Estimated processing time] box in the [Detail information] sheet of the [Add/Change - Job] window is selected.

-j job-name

Specifies the job name. There is no limit to the length of job name but only the first 64 bytes are valid.

The job name is not allowed to contain spaces, user-defined characters, or the following characters:

/ ? * ; , \ " < > | : ( ) ' . $ `

'#' cannot be specified for the first character.

An ampersand (&) cannot be used for the job name for network jobs and distribute execution jobs.

When the JCL file is submitted, this option will be valid and the job name that was specified in the JCL jobstart statement will be invalid.

If this option is omitted, the job file name (excluding the path name and file extension) is used as the job name. However, if the job name was specified in the jobstart statement in the JCL file, this jobstart statement will be valid.

If the job file name is also omitted, "STDIN" is used as the job name.

If "job-name" is prefixed by a number, the Job Execution Control prefixes the job name with "J".

-lt limittime

Specifies the time limit of job execution.

The value (in seconds) must be specified in a range from 1 to 99999999.

If this option is omitted, the value defined in the "Specify the time limit of job execution" (limittime operand in the queue parameter) in the [Create Queue] or [Edit Queue] window is set.

This option cannot be specified together with the -ld option.

-no

If this option is specified, job results files (job standard output file or error output file) are not generated.

If this option is specified, -o, -e and -eo options cannot be specified to output the standard output and standard error output to a specified file.

-nt [Windows]

Executes the job in no-trace mode. Normally, the Job Execution Control manages the child process or grandchild process by tracing the execution status of the job process. However, under no-trace mode, the management by tracing cannot be performed. Therefore, if the job started with the Job Execution Control failed with an exception code, the error due to the exception code could be cleared because it does not appears for the child/grandchild process.

However, when the job is executed with this option, the child process and grandchild process are not managed. Therefore, the job is recognized as completed when the parent process has completed, even if the child or grandchild process is left incomplete. Also, when the job is cancelled, only the parent process can be stopped forcibly.

This option is only valid when trace mode is specified as the job startup mode. It is ignored in job object mode.

Furthermore, this option cannot be used for the network jobs or the distributed execution jobs. That is, this job (distributed execution job) is executed with no-trace mode on the job submission source server, but the job is executed in normal trace mode on the destination server where it is submitted by remote operation, because the no-trace mode becomes invalid.

Also, this option cannot be written to a batch file. If specified, it is recognized as an invalid option and this specification is ignored.

-nr

Prohibits re-executing the job.

If a system failure occurred while the job executed with this option is running, it is not re-executed automatically when you reboot the Job Execution Control.

If a system failure occurred on the execution server, network jobs and distributed execution jobs are not re-executed when the Job Execution Control is rebooted, regardless of the status of the jobs and whether this option is specified.

-o [drive-letter:] [path-name] stdout-file [Windows]
-o [path-name] stdout-file [UNIX]

Outputs the standard output file, which is generated during the job execution, as a file named "stdout-file" to the path name specified at "path-name".

If the path-name is omitted, the current working directory used in submitting the job is assumed as the path name.

If failed to output to the specified path name, it is output to the current working directory.

If this option is omitted, the file name of the standard output is "job name.ejob number". For example, if the job name is "ACCOUNT", and its job number is "20", the name of this standard output file is "ACCOUNT.e20".

-ofe

Specify this option when the job is to be treated as ending with an error (0x40000008 is set as the completion code) if the output file specified by the MJ_OUTPUTFILES environment variable does not exist on the execution server.

If the -ofe option is not specified, 0x40000008 is not set as the job completion code even if the output file specified by the MJ_OUTPUTFILES environment variable does not exist on the execution server. The job completion code on the execution server is used.

Refer to "7.20.2 Specifying the I/O Files to Transfer" for information on the MJ_OUTPUTFILES environment variable.

-p priority

Specifies the priority of jobs in a queue by specifying an integer value between 0 and 63.

0 is the lowest priority value and 63 is the highest.

The priority specified in this option is to determine the order of job execution in a queue, but not decide the execution priority.

When placing a new job in a queue, the Job Execution Control examines the priority of jobs existing in the queue. When a new job is queued, it is placed in a proper position according to its priority value.

If the job with the same priority value as the new job already exists in the queue, the new job is placed after this job in the queue.

When the JCL file is submitted, this option will be valid and the JCL qprty statement that was specified will be invalid.

If this option is omitted, the default value defined in "Specify default job priority" in the [Define Operating Information] window (also, can be defined using the dfltdprty operand with queue parameter in the Job Execution Control initialization file) is set. If this value has not been defined, "-l" will be displayed. However, if the qprty statement was specified in the JCL file, this qprty statement will be valid.

-q queue-name

Specifies the name of the queue in which the job is queued.

If a queue name is not specified in this option, the Job Execution Control searches for the environment variable "QSUB_QUEUE". If this environment variable is found, the string in QSUB_QUEUE is recognized as the queue.

If this option is not specified and if the environment variable QSUB_QUEUE is not found, the job is queued in the default queue set by the system administrator.

If this option is not specified and the environment variable QSUB_QUEUE is not found, and if the default queue is not set up, "not specify" is displayed, and the job is not queued.

-R resource-name[,resource-type]

Specifies the resource name and the exclusivity attribute used in the job. "resource-name" must be specified using up to 64 characters. Specify either of the following for "resource-type".

sh

Shares resources with other jobs

This is the default for resource-type.

ex

Exclusively occupies resources

A comma (,) is used as a separator between resource-name and resource-type.

The following is an example when the resource name "RDB" and its exclusivity attribute is set to "ex".

-R RDB,ex

When the JCL file is submitted, this option will be valid and the JCL resource statement that was specified will be invalid.

-rh hostname

If you specify this option for a particular job, the job is executed on the specified server. However, the standard output and standard error output files of the job are generated on the server from which the job was submitted.

Consider the following when specifying this option:

If the job is JCL, this option is ignored.
If submitting the job with this option into the distributed execution queue, submitting is rejected.

The queue to which the job is submitted is determined in the following sequence:

The queue having the same name as the execution queue on the server that submitted the job (which is the queue specified at submitting the job, or default queue) can be set.
If the condition of the above 1. is not met, the default queue defined in "Specify default queue to submit jobs to" in the [Define Operating Information] window (also, can be defined using the dfltqueue operand with system parameter in the Job Execution Control initialization file) can be set.
If the above 2. default queue name has not been specified, "not specify" is displayed, and queuing the job failed.

If the job is requested to another server as the network job by specifying this option, the network job cannot be executed under the following condition a., b., or c.:

The network job that meets all of the following conditions cannot be executed:
- Both the job submission server and the job execution server (the server specified in this option) are the Windows-based servers
- The "Execute jobs under the respective job owner's authority" in the [Define Operating Information] window on the execution server is selected.(also, this can be defined using the execasuser parameter in the Job Execution Control initialization file)
- The job has been submitted by the user having the name "root".
- The password for the user who submitted the job (the above user named "root") and the password for the user who was logged in the "Systemwalker MpMjes" service on the execution server do not match.
The network job that meets all of the following conditions cannot be executed:
- It is the network job that is submitted from the UNIX-based server and is to be executed on the Windows-based server.
- The "Execute jobs under the respective job owner's authority" in the [Define Operating Information] window on the execution server is selected.(also, this can be defined using the execasuser parameter in the Job Execution Control initialization file)
The job queued in the distributed execution queue as the network job cannot be executed.

Still, the user who has submitted the job (the above (a)) is the user name "root" and not necessarily the system administrator.

The user who has submitted the job refers to the following:

Owner of the project executed from the Jobscheduler
Client user name specified in the qsub command with the "-cu" option (if the option is omitted, the user who executed the qsub command is defaulted as the client user)
User who executed the application which uses a job submission API

-rsys execution destination subsystem number

Specifies the subsystem number on the server where the network job is to be executed. The job will be submitted to the subsystem with the specified subsystem number on the execution destination server. The subsystem number must be a number between 0 and 9.

Specify the "-rh" option together with the "-rsys" option when requesting a network job to a subsystem on a host other than the local host. The "-rh" option does not need to be specified when requesting a network job to a subsystem on the local host.

For example, to request that a job file named "job.bat" be passed to subsystem 1 on the request host "Ahost", specify as follows:

qsub -rh Ahost -jft -rsys 1 job.bat

Jobs for which this option is specified cannot be submitted to distributed execution queues or compatibility mode load distribution queues, or else an error will occur.

-jft

Transfers the job file to the server specified with the -rh option or the distributed job execution server, and executes it on the transfer destination server. If this option is not specified, the job file existing on the server specified with the -rh option or the distributed job execution server is executed.

This option is only valid under the following conditions:

The job file is not a JCL file.
The -rh option is specified. Or, the job is submitted into the distributed execution queue.

-x

Makes all the existing environment variables available in the job execution environment when the job is submitted.

Do not specify this option together with the -rh option.

To pass the environment variables to the execution server, use the -env option instead of this option and set the required environment variables.

-z

Prevents a message from displaying when the job is submitted.

If this option is specified, a message reporting the successful submission does not appear even when the job is successfully submitted.

If, however, the job submission failed, an error message is always displayed regardless of this option.

If this option is omitted, a message similar to the following format is displayed when the job is submitted successfully:

Job job submitted to queue: queue-name

The "job" is displayed in the following format.

For more details on each attribute, see "7.6 qjalter Job Attribute Alter Command".

job-name(jobno.hostname)

"queue-name" is the name of the queue in which the job is queued.

-r retrycount

Performs retries if a line problem occurs while execution request of the network job is being made. The number of retries must be specified with any value between 1 and 20.

By default, the retry interval is set to 300 seconds. If the Change the connection retry settings for network jobs option in the Network sheet of the Define Operating Information window is enabled, the retry interval that you specified will be applied.

Also note that, no retries are performed with this option if a line problem occurs during waiting for completion of the job after its execution request was completed.

Operands

job_file

Specifies the job file to be executed. The files that can be specified are as follow:

Batch file/shell script
A file with the extension "BAT" or "CMD" [Windows]
Execution program
A file with the extension "EXE" or "COM" [Windows]
JCL file
A file with the extension "JCL", which is created in the Job Control Language (JCL) provided by Job Execution Control
Systemwalker script file
A file with the extension "SWT", which is created in the Systemwalker script language

parameters

Specifies parameters to be passed to the batch file/shell script, execution program, Systemwalker script, or JCL.

The following is an example if the parameters "0822" and "1000" are passed to the job file "job.bat":

qsub job.bat 0822 1000

If the string specified for the parameter contains the characters such as (*), (?), ([), or (]) that have special meanings depending on shells, enclose each string in single or double quotes. The following is a sample shell scrip where /usr/bin/ls is set as the job file, and -l, /home/guest/*, and /home/guest/work/??? are set as the parameters [UNIX]:

qsub /usr/bin/ls -l '/home/guest/*' '/home/guest/work/???'

Return Values

Return Value	Meaning
0	The command processing has terminated normally.
Other than 0	The command processing has failed. An error message is output.

Command Location

Windows	<Systemwalker Operation Manager installation directory>\MpWalker.JM\bin
Solaris Linux	/opt/FJSVMJS/usr/bin
HP-UX	/opt/FHPMJS/usr/bin
AIX	/opt/FAIXMJS/usr/bin

Cautions

If the job_file operand is omitted, a command is loaded from the standard input file (STDIN) as the job to be executed. If the standard input is performed from a console, press the following keys to end the command entry.
[Windows]
```
[Ctrl+Z], [Enter]
```
[UNIX]
```
[Ctrl+D]
```
The file specified in the job_file operand could be copied to the spool for the Job Execution Control as a work file when the qsub command is submitted. (This is performed when selecting the "Copy the scripts specified when registering jobs before execution" option in the [Backward compatibility] sheet of the [Define Operating Information] window.) In this case, the Job Execution Control executes the job by referencing the work file, so the changes made to the job_file after queuing cannot be applied to the job execution.
All the options that can be specified in the command lines can be also written in the first comment block of the batch file. [Windows]
If you specify the same option entered in the batch file to the command lines, the option specified on the command lines and its arguments take priority.
Do not specify the qsub command of Job Execution Control or batch files or shell scripts that are calling the qsub command of the Job Execution Control to the job_file operand.
Do not execute the qsub command as a user that has a space in the user name. Also, do not specify a user name in the -cu option that has a space.
Do not use spaces in the following directory and file names:
- Job file name specified in the job_file operand
- Path and file names specified in the -e option
- Path and file names specified in the -o option
Do not use spaces in the path names in PATH environment variables if these are to be read.
If this command is executed from a Systemwalker Operation Manager job, the behavior of Systemwalker Operation Manager and Systemwalker Centric Manager is not guaranteed. Refer to "Commands that Should Not Be Executed as Jobs" in the Systemwalker Operation Manager User's Guide for details.

About Batch File [Windows]

Inputting options in a batch file gets rid of the need for specifying those options when submitting the qsub command.

However, when the "Copy the scripts specified when registering jobs before execution" option is not selected in the [Backward compatibility] sheet of the [Define Operating Information] window, the options cannot be identified.

Algorithms for Identifying Options

One line is read from a batch file. If it is the end of the file, the process proceeds to step 8.
If it is an empty line, or if the first character encountered is ":", the process proceeds to step 1.
If the first word encountered is not "rem", the process proceeds to step 8.
If the character encountered after "rem" is not "@$", the process proceeds to step 1.
If the characters "@$" is not followed by "-", the process proceeds to step 8.
Option parsing is performed.
Search is performed for the next "-" character. The process proceeds to step 6 when "-" is encountered. If the end of the line is reached without encountering "-", the process proceeds to step 1.
End. All the options that follow are ignored.

Example of Option Statement

rem batch file example
rem
rem CLASSA is specified for the queue to which the job is submitted.
rem @$-q CLASSA
rem
rem All the options that follow are ignored.
rem @$