job new
Applies To: Microsoft HPC Pack 2012, Microsoft HPC Pack 2012 R2
Creates a new job with the specified settings on an HPC cluster.
For examples of how to use this command, see Examples.
Syntax
job new [/askednodes:<node_list>] [/corespernode:<min>[-<max>]]
[/customproperties:<property_list>]
[/emailaddress:<address>] [/estimatedprocessmemory:<memory>)] [/exclusive[:{true|false}]]
[/faildependenttasks[:{true|false}]] [/failontaskfailure[:{true|false}]]
[/holduntil:[{<DateTime>|<minutes>}]] [/jobenv:<variable_and_value_list>]
[/jobfile:<path>\<file_name>] [/jobname:<job_name>]
[/jobtemplate:<job_template_name>] [/license:<license_list>]
[/memorypernode:<min>[-<max>]] [/nodegroup:<node_group_list>]
[/nodegroupop:{Intersect|Uniform|Union}] [/notifyoncompletion[:{true|false}]]
[/notifyonstart[:{true|false}]]{[/numcores:<min>[-<max>]]
| [/numnodes:<min>[-<max>]] | [/numprocessors:<min>[-<max>]]
| [/numsockets:<min>[-<max>]]} [/orderby:<primary>[,<secondary>]]
[/progress:<percent_progress>] [/parentjobids:<jobID_list>]
[/priority:<priority_specification>][/progress:progress]
[/progressmsg:<message>] [/priority:<priority>]
[/projectname:<name>] [/requestednodes:<node1_name>[,<node2_name>…]]
[/Runtime:{<time>|Infinite} [/rununtilcanceled[:{true|false}]]
[/scheduler:<name>] [/singlenode:{true|false}]
[/taskexecutionfailureretrylimit:<retry_limit>]
[/validexitcodes:int|intStart..intEnd[,int|intStart..intEnd]*]
job new {/? | /help}
Parameters
Parameter |
Description |
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
/askednodes:<node_list> |
Deprecated. Use the /requestednodes parameter instead. |
||||||||||||
/corespernode:<min>[-<max>] |
Specifies the minimum and, optionally, the maximum number of cores that a node can have for the HPC Job Scheduler Service to consider the node as a candidate node on which to run the job. The job will not run on a node that has fewer cores than the minimum value or more cores than the maximum value that this parameter specifies. If all of the nodes in the cluster have a number of cores that falls outside the range that you specify for this parameter, an error occurs when you submit the job. The default values for this parameter are:
|
||||||||||||
/customproperties:<property_list> |
Specifies the names and values for the custom properties for the job in a format of <name1>=<value1>[;<name2>=<value2>...]. Custom property names are case insensitive, and will reflect the case used when they were first defined. Note This parameter was introduced in HPC Pack 2012 and is not supported in previous versions. |
||||||||||||
/emailaddress:<address> |
Sends notifications for this job to this email address. Note This parameter was introduced in HPC Pack 2012 and is not supported in previous versions. |
||||||||||||
/estimatedprocessmemory:<memory >) |
The maximum amount of memory in megabytes (MB) that each process in this job is estimated to consume. |
||||||||||||
/exclusive[:{true|false}] |
Specifies whether the HPC Job Scheduler Service should ensure that no other job runs on the same node as this job while this job runs. A value of True indicates that the HPC Job Scheduler Service should ensure that no other job runs on the same node as this job while this job runs. A value of False indicates that this job can share compute nodes with other jobs. When you specify the /exclusive parameter without a value, the job new command behaves as if you specified a value of True. If you do not specify the /exclusive parameter, the job new command behaves as if you specified a value of False. |
||||||||||||
/faildependenttasks[:{true|false}] |
Fails all dependent tasks if a task fails or is canceled. If this parameter is not set the default behavior is false. If /faildependenttasks is defined but no value is declared, true is assumed. Note This parameter was introduced in HPC Pack 2012 and is not supported in previous versions. |
||||||||||||
/failontaskfailure[:{true|false}] |
Specifies whether the HPC Job Scheduler Service should stop the job and fail the entire job immediately when a task in the job fails. A value of True indicates that the HPC Job Scheduler Service should stop the job and fail the entire job immediately when a task in the job fails. A value of False indicates that the HPC Job Scheduler Service should continue running the rest of the tasks in the job after any task in the job fails. When you specify the /failontaskfailure parameter without a value, the job new command behaves as if you specified a value of True. If you do not specify the /failontaskfailure parameter, the job new command behaves as if you specified a value of False. |
||||||||||||
/holduntil:[{<DateTime>|<minutes>}] |
Specifies the date and time in local time or number of minutes until which the HPC Job Scheduler Service should wait before trying to start the job. If this parameter is not set, the job can start when resources are available. The HPC Job Scheduler Service only runs the job at the date and time that this parameter specifies if the resources needed for the job are available. If the resources needed for the job are not available at that date and time, the job remains queued until the necessary resources become available. You can specify the date and time in any format that the .NET Framework can parse for the current operating system culture. For information about how the .NET Framework parses date and time strings, see Parsing Date and Time Strings. You can specify the /holduntil parameter for a job as long as the job is not running or completed. Note The time specified using /holduntil is converted internally to UTC, and will not reflect local Daylight Savings Time. If the minutes value is used, it must be an integer. The minutes to hold are converted to UTC at the time job new is applied. If the value for /holduntil is empty, the job is not pending due to that parameter. Note This parameter was introduced in HPC Pack 2012 and is not supported in previous versions. |
||||||||||||
/jobenv:<variable_and_value_list> |
Specifies the environment variables that you want to set in the run-time environment of the job and the values to which you want to set 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 /jobenv parameters, each with 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>=″. If you set or unset an environment variable for a job, that environment variable is also set or unset for each task in the job unless you override that environment variable setting for the task by specifying a new setting with the /env parameter of the job add command. Note This parameter was introduced in HPC Pack 2008 R2 and is not supported in previous versions. |
||||||||||||
/jobfile:<path>\<file_name> |
Specifies the file name and path for a job XML file that contains settings to use for the job that you want to create. If you specify other parameters in addition to the /jobfile parameter, the values for those parameters override the settings in the job XML file. This parameter is only used when importing a job from an XML file. In that case it is required. |
||||||||||||
/jobname:<job_name> |
Specifies a name to use for this job in command output and in the user interface. The maximum length for the name of a job is 80 characters. |
||||||||||||
/jobtemplate:<job_template_name> |
Specifies the name of the job template to use for the job. The maximum length for the name of a job template is 80 characters. By default, the job new command uses the Default job template for the new job. |
||||||||||||
/license:<license_list> |
Specifies a list of features for which the job requires licenses and the number of licenses required for each. Use a format of <license_name1>:<number1> [,<license_name2>:<number2>…] for this list. For example, License1:10,License2:20,License3:12. The list has a maximum length of 160 characters. |
||||||||||||
/memorypernode:<min>[-<max>] |
Specifies the minimum and, optionally, the maximum amount of memory in megabytes (MB) that a node can have for the HPC Job Scheduler Service to consider the node as a candidate node on which to run the job. The job will not run on a node that has less memory than the minimum value or more memory than the maximum value that this parameter specifies. If all of the nodes in the cluster have an amount of memory that falls outside the range that you specify for this parameter, an error occurs when you submit the job. The default values for this parameter are:
|
||||||||||||
/nodegroup:<node_group_list> |
Specifies the list of node groups on which this job can run in the format <node_group1_name>[,<node_group2_name>…]. The HPC Job Scheduler Service allocates resources to the job from nodes that belong to all of the node groups in the list by default, or to the nodes resulting from the operation of the /nodegroupop parameter, if specified, on the list of groups. If you specify values for the /nodegroups and the /requestednodes parameters, the job runs only on the nodes in the list of nodes for the /requestednodes that also belong to the list of nodes defined with the /nodegroup and /nodegroupop parameters. The /nodegroup parameter ensures that there are nodes within the valid node list. However, if a job’s resource requirements from the above parameter cannot be met from within the node list, the job will fail during job submission. If you specify parameter /requestednodes for a task and /nodegroups for the job, the job will fail during submission if the requested nodes are not in the nodes listed in conjunction with the /nodegroup and the /nodegroupop parameters. |
||||||||||||
/nodegroupop:{Intersect|Uniform|Union} |
Specifies the operator for the list specified by the /nodegroup parameter. Valid values are:
The default value for this parameter is Intersect. Note This parameter was introduced in HPC Pack 2012 and is not supported in previous versions. |
||||||||||||
/notifyoncompletion[:{true|false}] |
Specifies whether or not the HPC Job Scheduler Service should send email notification when then job ends. A value of True indicates that the HPC Job Scheduler Service should send email notification when then job ends. A value of False indicates that the HPC Job Scheduler Service should not send email notification when then job ends. A job ends and notification is sent when the state of the job changes to Finished, Failed, or Canceled. A cluster administrator must configure notification for the HPC cluster before you can receive notification about a job. When you specify the /notifyoncompletion parameter without a value, the job new command behaves as if you specified a value of True. If you do not specify the /notifyoncompletion parameter, the job new command behaves as if you specified a value of False. This parameter was introduced in HPC Pack 2008 R2 and is not supported in earlier versions. |
||||||||||||
/notifyonstart[:{true|false}] |
Specifies whether or not the HPC Job Scheduler Service should send email notification when then job starts. A value of True indicates that the HPC Job Scheduler Service should send email notification when then job starts. A value of False indicates that the HPC Job Scheduler Service should not send email notification when then job starts. A cluster administrator must configure notification for the HPC cluster before you can receive notification about a job. When you specify the /notifyonstart parameter without a value, the job new command behaves as if you specified a value of True. If you do not specify the /notifyonstart parameter, the job new command behaves as if you specified a value of False. Note This parameter was introduced in HPC Pack 2008 R2 and is not supported in earlier versions. |
||||||||||||
/numcores:<min>[-<max>] |
Specifies the overall number of cores across the HPC cluster that the job requires in the format <minimum>[-<maximum>]. The job 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 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. The minimum and maximum values can only be positive integers or an asterisk (*). If you specify the minimum or maximum value as an asterisk, the HPC Job Scheduler Service automatically calculates the minimum or maximum number of cores at run time based on the minimum and maximum number of cores for the tasks in the job. You cannot specify the /numcores parameter if you also specify the /numnodes, /numprocessors, or /numsockets parameter. If you do not specify any of these four parameters, the resource type for the job defaults to cores and the minimum and maximum resources are calculated automatically at run time, based the minimum and maximum resources for the tasks in the job. |
||||||||||||
/numnodes:<min>[-<max>] |
Specifies the overall number of nodes across the HPC cluster that the job requires in the format <minimum>[-<maximum>]. The job 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 job. The minimum and maximum values can only be positive integers or an asterisk (*). If you specify the minimum or maximum value as an asterisk, the HPC Job Scheduler Service automatically calculates the minimum or maximum number of nodes at run time based on the minimum and maximum number of nodes for the tasks in the job. You cannot specify the /numnodes parameter if you also specify the /numcores, /numprocessors, or /numsockets parameter. If you do not specify any of these four parameters, the resource type for the job defaults to cores and the minimum and maximum resources are calculated automatically at run time, based the minimum and maximum resources for the tasks in 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 job requires in the format <minimum>[-<maximum>]. The job 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 job. The minimum and maximum values can only be positive integers or an asterisk (*). If you specify the minimum or maximum value as an asterisk, the HPC Job Scheduler Service automatically calculates the minimum or maximum number of sockets at run time based on the minimum and maximum number of sockets for the tasks in the job. You cannot specify the /numsockets parameter if you also specify the /numcores, /numprocessors, or /numnodes parameter. If you do not specify any of these four parameters, the resource type for the job defaults to cores and the minimum and maximum resources are calculated automatically at run time based the minimum and maximum resources for the tasks in the job. |
||||||||||||
/orderby:<primary>[,<secondary>] |
Specifies the order that the HPC Job Scheduler Service should use to allocate nodes to the job, in the format <primary_order>[,<secondary_order>]. The primary_order and secondary_order portions of the value can each be one of the following values:
When you specify a secondary order, the HPC Job Scheduler Service sorts the nodes according to the primary order first. For subsets of nodes that have the same amount of the resource that the primary order specifies, the HPC Job Scheduler Service then sorts the nodes within the subset using the secondary sort order. For example, if you specify memory,-cores, the HPC Job Scheduler Service sorts the nodes from the highest amount of memory to the lowest. Then, for subsets of nodes that have the same amount of memory, the HPC Job Scheduler Service uses the number of cores to break the tie, and sorts the nodes that have the same amount of memory from the fewest number of cores to the most. The primary order and secondary order must refer to different types of resources. For example, memory, -cores is a valid combination of primary and secondary sort orders. Combinations such as memory, -memory and -cores,-cores are not valid. The default order that the HPC Job Scheduler Service uses to allocate nodes to a job is cores,memory. |
||||||||||||
/parentjobids:<jobID_list> |
Specifies the list of job IDs that the job will depend on in a format of <jobID1>[,<jobID2>...]. The job IDs must already exist. The HPC Job Scheduler Service will schedule the job only when its parent jobs have completed and are all in a Finished state. If any parent job has not completed or has completed but is in a Canceled or Failed state, the job remains queued. Note This parameter was introduced in HPC Pack 2012 and is not supported in previous versions. |
||||||||||||
/priority:<priority> |
Specifies the priority for scheduling the job. Starting in Microsoft® HPC Pack 2008, the priority value can only be one of the following named values: Highest, AboveNormal, Normal, BelowNormal, or Lowest. Starting in HPC Pack 2008 R2, you can use any of the five named priority values that you could use in HPC Pack 2008. You can also use any number between 0 and 4000, with 0 as the lowest priority and 4000 as the highest. You can also specify the priority value as named_value+offset or named_value-offset. For the purpose of these final formats, the named priorities have the values in the following table, and the combination of the named value and offsets cannot be less than 0 or greater than 4000.
The job template that the job uses specifies permissions that affect who can specify elevated priorities. The HPC Job Scheduler Service places jobs with the same priority into the job queue in the order that users submit the jobs, unless a user requeues a job. If a user requeues a job, the HPC Job Scheduler Service places that job first among the jobs with the same priority. The default priority for a job is Normal or 2000. |
||||||||||||
/progress:<percent_progress> |
Specifies the percentage of the job that is complete. This value must be between 0 and 100. If you do not set the value of this property, the HPC Job Scheduler Service calculates the progress based on the percentage of tasks that are complete for the job. When you set this property for a job, the HPC Job Scheduler Service does not continue to update this property, so you must continue to update the property by using the job modify command. Note This parameter was introduced in HPC Pack 2008 R2 and is not supported in previous versions. |
||||||||||||
/progressmsg:<message> |
Specifies a custom status message that you want to display for the job. The maximum length for this string is 80 characters. To specify a status message that includes spaces, enclose the status message in quotation marks ("). Note This parameter was introduced in HPC Pack 2008 R2 and is not supported in previous versions. |
||||||||||||
/projectname:<name> |
Specifies a project name for the job that you can use for tracking jobs. The maximum length for the project name is 80 characters. |
||||||||||||
/requestednodes:<node_list> |
Specifies a list of names for the nodes on which the job can run in the format <node1_name>[,<node2_name>…]. These nodes are candidates for the job, but not all of the nodes will necessarily run the job if the available resources on these nodes exceed the resources that the job requires. The HPC Job Scheduler Service allocates the top nodes according to the value of the /orderby parameter until the allocated nodes meet the value that you specified with the /numcores, /numsockets, /numprocessors, or /numnodes parameter. If you do not specify the /requestednodes parameter, the HPC Job Scheduler Service considers all nodes as candidates that the HPC Job Scheduler Service can allocate to the job. If you specify values for the /requestednodes and the /nodegroups parameters, the job runs only on the nodes in the list of nodes for the /requestednodes parameter that also belong to the list of nodes defined with the /nodegroup and /nodegroupop parameters. |
||||||||||||
/runtime:{<time> | Infinite} |
Specifies the maximum amount of time that the job should run. After the job runs for this amount of time, the HPC Job Scheduler Service cancels the job. You specify the amount of time in the format [[<days>:]<hours>:]<minutes>. You can also specify Infinite to indicate that the job 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. |
||||||||||||
/rununtilcanceled[:{true|false}] |
Specifies whether the job continues to run and hold resources until the run-time limit expires or someone cancels the job. A value of True indicates that the job continues to run and hold resources until the run-time limit expires or someone cancels the job. If you specify a value of True, you must specify minimum and maximum values for the /numcores, /numnodes, or /numsockets parameter, or an error occurs when you submit the job. A value of False indicates that the job should stop and release its resources when all of the tasks in the job are complete. When you specify the /rununtilcanceled parameter without a value, the job new command behaves as if you specified a value of True. If you do not specify the /rununtilcanceled parameter, the job new command behaves as if you specified a value of False. |
||||||||||||
/scheduler:<name> |
Specifies the host name or IP address of the head node for the cluster on which you want to create the new job. 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. |
||||||||||||
/singlenode[:{true|false}] |
All resources will be allocated on one node. If /singlenode is declared but no value is set, True is assumed. If /singlenode is not declared, false is assumed. Note This parameter was introduced in HPC Pack 2012 and is not supported in previous versions. |
||||||||||||
/taskexecutionfailureretrylimit:<retry_limit> |
Specifies the maximum number of times a task in this job other than a node preparation or node release task will be automatically requeued after an application execution failure occurs. Note This parameter was introduced in HPC Pack 2012 R2 Update 1. It is not available in previous versions. |
||||||||||||
/validexitcodes:{int|intStart..intEnd{ [,{int|intStart..intEnd}]* |
Specifies the exit codes to be used for checking whether tasks in a job successfully exit. /validexitcodes must be specified by discrete integers and integer ranges separated by commas. The default value for this parameter is 0. min and max may be used on a range, representing the start or end. For example, 0..max represents nonnegative integers. This parameter can be overridden by declaring the /validexitcodes parameter specific to a task. All tasks that do not have this parameter explicitly declared will inherit the parameter from the job. If /validexitcodes is not defined, 0 is the default valid exit code. Note This parameter was introduced in HPC Pack 2012 and is not supported in previous versions. |
||||||||||||
/? |
Displays Help at the command prompt. |
||||||||||||
/help |
Displays Help at the command prompt. |
Remarks
Before the HPC Job Scheduler Service can run the new job, you need to add tasks to the job by using the job add command and submit the job by using the job submit command.
Examples
To create a new job, use the following command:
job new
To create a new job using the settings in the job file at C:\JobFiles\SampleJob1.xml, use the following command:
job new /jobfile:"C:\JobFiles\SampleJob1.xml"
To create a new job named Sample Job in the Cluster Testing project that uses the job template named MyJobTemplate, with a run-time limit of 30 minutes and priority of AboveNormal, use the following command:
job new /jobname:"Sample Job" /jobtemplate:MyJobTemplate
/projectname:"Cluster Testing" /runtime:0:0:30 /priority:AboveNormal
To create a new job with a priority of 2350 that sets the VAR1 environment variable to True and the VAR2 environment variable to 12 in the run-time environment of the job, use the following command:
job new /priority:2350 /jobenv:VAR1=true;VAR2=12
To create a new job with a priority of Highest-50 (3950) that unsets the VAR3 environment variable and sets the VAR4 environment variable to Yes in the run-time environment of the job, use the following command:
job new /priority:Highest-50 /jobenv:VAR3=;VAR4=yes
To create a new job with the progress percentage for the job set to 15 and with a status message of "This job has a status", and which also sets the VAR5 and VAR6 environment variables to No in the run-time environment of the job, use the following command:
job new /jobenv:VAR5=no /jobenv:VAR6=no /progress:15 /progressmsg:"This job has a status"
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
)