job add
Applies To: Microsoft HPC Pack 2012, Microsoft HPC Pack 2012 R2
Creates a new task and adds it to the specified job.
For examples of how to use this command, see Examples.
Syntax
job add <jobId> [/depend:<task_name_list>] [/env:<variable_and_value_list>]
[/exclusive[:{true|false}]] [/name:<task_name>]
{[/numcores:<min>[-<max>]] | [/numnodes:<min>[-<max>]] |
[/numprocessors:<min>[-<max>]] | [/numsockets:<min>[-<max>]]}
[/parametric:<index_specification>] [/requirednodes:<node_list>]
[/rerunnable[:{true|false}]] [/runtime:{<time>|Infinite}]
[/scheduler:<name>] [/stderr:[<path>\]<file_name>]
[/stdin:[<path>\]<file_name>] [/stdout:[<path>\]<file_name>]
[/taskfile:<path>\<file_name>] [/type:<type_name>]
[/validexitcodes:{<int>|<intStart>..<intEnd>}[,{<int>|<intStart>..<intEnd>}]*]
[/workdir:<folder>] <command> [<parameters>]
job add {/? | /help}
Parameters
Parameter |
Description |
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
<jobID> |
Specifies the job identifier of the job to which you want to add the task. |
||||||||||||
/depend:<task_name_list> |
Specifies a list of one or more task names in the specified job on which the new task depends. The list should have a format of <task_name1>[,<task_name2>...]. The new task may not start until all tasks that the /depend parameter specifies finish running. Tip A single <task_name> represents one or more tasks within the job, all of which have that <task_name> assigned. |
||||||||||||
/env:<variable_and_value_list> |
Specifies a list of environment variables to set in the run-time environment of the task and the values to assign to those environment variables. The list should have a format of <variable_name1>=<value1> [;<variable_name2>=<value2>...]. Alternatively, you can set multiple environment variables by including multiple /env parameters. Each must be a different argument with a format of <variable_name>=<value>. To unset an environment variable, do not specify a value. For example, <variable_to_unset_name>=. |
||||||||||||
/exclusive[:{true|false}] |
Specifies whether the HPC Job Scheduler Service should ensure that no other task runs on the same node as this task while this task runs. A value of True indicates that the HPC Job Scheduler Service should ensure that no other task runs on the same node while this task runs. A value of False indicates that this task can share compute nodes with other tasks. When you specify the /exclusive parameter without a value, the job add command behaves as if you specified a value of True. If you do not specify the /exclusive parameter, the job add command behaves as if you specified a value of False. |
||||||||||||
/name:<task_name> |
Specifies a name to use for this task in command output and in the user interface. The maximum length for the name is 80 characters. This parameter has no default value. Tip A single <task_name> represents 1 or more tasks within the job, all of which have that <task_name> assigned. Warning If this <task_name> is to be used in conjunction with the /depend parameter, the <task_name> should not contain a comma or space. |
||||||||||||
/numcores:<min>[-<max>] |
Specifies the overall number of cores across the HPC cluster that the task requires, in the format <minimum>[-<maximum>]. The task runs on at least the minimum number of cores and on no more than the maximum. If you specify only one value, this command sets both the maximum and minimum number of cores to that value. If you specify a minimum value that exceeds the total number of cores available across the cluster, an error occurs when you submit the job or if the job is already submitted, when you submit the task. The minimum and maximum values can only be positive integers. /numcores is used only when the job’s UnitType is core. If you do not specify the /numcores, /numnodes, /numprocessors, or /numsockets parameter, the HPC Job Scheduler Service allocates one UnitType as defined by the job. |
||||||||||||
/numnodes:<min>[-<max>] |
Specifies the overall number of nodes across the HPC cluster that the task requires, in the format <minimum>[-<maximum>]. The task runs on at least the minimum number of nodes and on no more than the maximum. If you specify only one value, this command sets both the maximum and minimum number of nodes to that value. If you specify a minimum value that exceeds the total number of nodes available across the cluster, an error occurs when you submit the task or the job that contains the task. The minimum and maximum values can only be positive integers. /numnodes is used only when the job’s UnitType is node. If you do not specify the /numcores, /numnodes, /numprocessors, or /numsockets parameter, the HPC Job Scheduler Service allocates one UnitType as defined by the job. |
||||||||||||
/numprocessors:<min>[-<max>] |
Deprecated. Use the /numcores parameter instead. |
||||||||||||
/numsockets:<min>[-<max>] |
Specifies the overall number of sockets across the HPC cluster that the task requires, in the format <minimum>[-<maximum>]. The task runs on at least the minimum number of sockets and on no more than the maximum. If you specify only one value, this command sets both the maximum and minimum number of sockets to that value. If you specify a minimum value that exceeds the total number of sockets available across the cluster, an error occurs when you submit the task or the job that contains the task. The minimum and maximum values can only be positive integers. /numsockets is used only when the job’s UnitType is socket. If you do not specify the /numcores, /numnodes, /numprocessors, or /numsockets parameter, the HPC Job Scheduler Service allocates one UnitType as defined by the job. |
||||||||||||
/parametric:<index_specification> |
Indicates that the new task is a parametric task. A parametric task runs the specified command multiple times, substituting the current index value for asterisks (*) in the command line. The asterisk is also substituted when specified in the /stdin, /stdout, and /stderr parameters. The index specification for this parameter defines the behavior of the index value. The format for the index specification is [<start>-]<end>[:<increment>]. The current index value starts at the starting index, and increases by the increment value each subsequent time that the command runs. When the current index exceeds the ending index, the task stops running the command. The starting index must be less than the ending index, and the increment value must be a positive integer. If you do not specify an increment value, the default is 1. If you do not specify a start value, the default is 1. If you specify an increment value, you must also specify a start value. Starting in Microsoft® HPC Pack 2008 R2, if you specify the /type parameter with a value other the ParametricSweep, you cannot also specify the /parametric parameter. |
||||||||||||
/requirednodes:<node_list> |
Specifies a list of nodes on which the task must run, in a format of <node1_name>[,<node2_name>…]. The HPC Job Scheduler Service exclusively allocates all of the nodes in this list to run the task. |
||||||||||||
/rerunnable[:{true|false}] |
Specifies whether the HPC Job Scheduler Service attempts to rerun the task if the task runs and fails. A value of True indicates that the HPC Job Scheduler Service can attempt to rerun the task if the task is preempted or if it fails due to a cluster issue, such as a node becoming unreachable. The job scheduler does not attempt to rerun tasks that run to completion and return a with an unsuccessful exit code. A value of False indicates that the HPC Job Scheduler Service should not attempt to rerun the task if the task begins but does not complete due to preemption or cluster issues. Instead it should move the task to the failed state immediately. The cluster administrator can configure the number of times that the HPC Job Scheduler Service tries to rerun a task before moving the task to the failed state. If you do not specify the /rerunnable parameter, the command behaves as if you specified a value of True. |
||||||||||||
/runtime:{<time>|Infinite} |
Specifies the maximum amount of time that the task should run. After the task runs for this amount of time, the HPC Job Scheduler Service cancels the task. You specify the amount of time in a format of [[<days>:]<hours>:]<minutes>. You can also specify Infinite to indicate that the task can run for an unlimited amount of time. If you specify only one part of the [[<days>:]<hours>:]<minutes> format, the command interprets the specified value as the number of minutes. For example, 12 indicates 12 minutes. If you specify two parts of the format, the command interprets the left part as hours and the right part as minutes. For example, 10:30 indicates 10 hours and 30 minutes. You can use one or more digits for each part of the format. The maximum value for each part is 2,147,483,647. If you do not specify the /runtime parameter, the default value is Infinite. |
||||||||||||
/scheduler:<name> |
Specifies the host name or IP address of the head node for the cluster that contains the job to which you want to add the task. The value must be a valid computer name or IP address. If you do not specify the /scheduler parameter, this command uses the scheduler on the head node that the CCP_SCHEDULER environment variable specifies. |
||||||||||||
/stderr:[<path>\]<file_name> |
Specifies the name for the file to which the task should redirect the standard error stream, including the full path or the path that is relative to the working directory for the file if the task should not redirect the standard error stream to a file in the working directory. If you specify a path that does not exist, the task fails. If you do not specify the /stderr parameter, the task stores up to 4 kilobytes (KB) of data in the database for the HPC Job Scheduler Service that the Output property for the task specifies. Any output that exceeds 4 KB is lost. The maximum length of value for this parameter is 160 characters. |
||||||||||||
/stdin:[<path>\]<file_name> |
Specifies the name for the file from which the task should receive standard input, including the full path or the path that is relative to the working directory for the file if the task should not receive standard input from a file in the working directory. If you specify a file or path that does not exist, the task fails. The maximum length of value for this parameter is 160 characters. |
||||||||||||
/stdout:[<path>\]<file_name> |
Specifies the name for the file to which the task should redirect standard output, including the full path or the path that is relative to the working directory for the file if the task should not redirect standard output to a file in the working directory. If you specify a path that does not exist, the task fails. If you do not specify the /stdout parameter, the task stores up to 4 kilobytes (KB) of data in the database for the HPC Job Scheduler Service that the Output property for the task specifies. Any output that exceeds 4 KB is lost. The maximum length of value for this parameter is 160 characters. |
||||||||||||
/taskfile:<path>\<file_name> |
Specifies the name of a task XML file from which to read the settings for the task, including the full or relative path to the file if the file is not in the current directory. You must specify a task XML file for the /taskfile parameter that includes a value for the CommandLine attribute, or specify a command or application name and optional parameters. |
||||||||||||
/type:<type_name> |
Specifies a type for the task, which defines how to run the command for the task. The following table describes the types that you can specify.
The default value for this parameter is Basic unless you also specify the /parametric parameter. If you specify the /parametric parameter, the default value of the /type parameter is ParametricSweep. If you specify the /type parameter with a value other than ParametricSweep, you cannot also specify the /parametric parameter. This parameter was introduced in HPC Pack 2008 R2 and is not available in previous versions. |
||||||||||||
/validexitcodes:{<int>|<intStart>..<intEnd>}[,{<int>|<intStart>..<intEnd>}]* |
Specifies the valid task exit codes to be used for checking whether a task successfully exits. /validexitcodes must be specified by discrete integers and integer ranges separated by commas. min and max can be used as the start or end of a range. For example 0..max represents all non-negative integers. If not defined, /validexitcodes inherits its value from the job’s /validexitcodes parameter. If neither is defined, the default value is 0. Note This parameter was introduced in Microsoft® HPC Pack 2012 and is not supported in previous versions. |
||||||||||||
/workdir:<folder> |
Specifies the working directory under which the task should run. The maximum length of value for this parameter is 160 characters. |
||||||||||||
<command> [<parameters>] |
Specifies the command line for the task, including the command or application name and any necessary parameters. Unless defined within a /taskfile task XML file, a command must exist for the task to be added. The command will be executed relative to the working directory unless it contains a fully qualified path. |
||||||||||||
/? |
Displays Help at the command prompt. |
||||||||||||
/help |
Displays Help at the command prompt. |
Remarks
You can add tasks to jobs that you have not yet submitted, jobs that you have submitted and that are currently waiting in the queue, jobs that are already running, or jobs that have failed or been canceled.
You cannot add tasks to a job that has finished.
When you add a task to a job that is waiting in the queue or running, and the resources that the HPC Job Scheduler Service allocated to the job are available, the task begins to run.
Starting in Microsoft® HPC Pack 2008 R2, you can specify that asterisks (*) in the command line for a parametric task should not be replaced with the current value of the parametric index by preceding the asterisk with three caret (^) characters. For example, if you use the job add command to create a parametric task, and you specify the command line as echo *, the task prints the values of the parametric index. If you instead use the job add command to create a parametric task, and you specify the command line as echo ^^^*, the task prints an asterisk for each value of the parametric index.
Examples
To add a new task named My Task to the job with a job identifier of 39, which runs the hostname.exe program, has a working directory of \\headnode\output share, and redirects standard output to a file named hostname.out in the working directory, use the following command:
job add 39 /name:"My Task" /workdir:\\headnode\output share /stdout:"hostname.out" hostname.exe
To add a new node preparation task to the job with a job identifier of 47 that runs the ver command, type:
job add 47 /type:NodePrep ver
To add a new parametric task named Sweep Task to the job with a job identifier of 25, which runs a series of echo * commands for an index that starts at 10 and increases by 2 until the index reaches 100, and which redirects standard output to a series of files at \\headnode\output share\sweepstep*.out, use the following command:
job add 25 /name:"Sweep Task" /parametric:10-100:2 /stdout:\\headnode\output share\sweepstep*.out echo *
The previous example runs each of the following command lines independently:
echo 10
echo 12
echo 14
...
echo 98
echo 100
This parametric sweep creates the following files in the \\headnode\output shared directory:
sweepstep10.out
sweepstep12.out
...
sweepstep100.out
The parametric sweep creates 45 files in all, each of which contains its index number.
To create a new job, add a task to the job, and then submit the job, run a batch file that includes the following command, which uses the for command to get the identifier of the new job:
for /f "usebackq tokens=4 delims=. " %%i in (`job new`) do (
job add %%i echo Hello World
job submit /id:%%i
)