job modify
Applies To: Microsoft HPC Pack 2012, Microsoft HPC Pack 2012 R2
Sets the properties of the specified job.
For examples of how to use this command, see Examples.
Syntax
job modify <jobID> {[/addexcludednodes:<node_list>] |
[/clearexcludednodes] | [/removeexcludednodes:<node_list>]}
[/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>]] [/parentjobids:<jobID_list>]
[/password:<password>] [/priority:<priority>]
[/progress:<percent_progress>][/progressmsg:<message>]
[/projectname:<name>] [/removeexcludednodes:nodename{,nodename}*]
[/requestednodes:<node_list>] [/runtime:{<time>|Infinite}
[/rununtilcanceled[:{true|false}]] [/scheduler:<name>]
[/singlenode [:{true|false}]] [/taskexecutionfailureretrylimit:<retry_limit>]
[/user:[<domain>\]<user_name>] [/validexitcodes {:int|intStart..intEnd}[,{int|intStart..intEnd}]*]
job modify [{/? | /help}]
Parameters
Parameter |
Description |
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
jobID |
Specifies the job identifier of the job for which you want to change the properties. |
||||||||||||
/addexcludednodes:<node_list> |
Specifies the names of the nodes that you want to add to the list of nodes on which the job should not run in a format of <node1_name>[,<node2_name>…]. If you add a node to the list of nodes that should not be used for the job while the job is running on that node, the tasks in the job that are running on the node are canceled and then requeued if the IsRerunnable property for the task is True. If a node is specified in the RequiredNodes property for any of the tasks in the job, an error occurs when you submit the job if you also specify that node in the /addexcludednodes parameter. If you specify a set of nodes in the /addexcludednodes parameter that would cause the set of available resources to become smaller than the minimum number of resources that the job requires, an exception occurs when you submit the job. For example, if you have an HPC cluster than consists of three nodes and you include two of them in the /addexcludednodes parameter, that action makes only one node available, and an exception occurs when you submit the job if the job requires a minimum of two nodes. If you specify the name of a node that does not currently belong to the HPC cluster, an error occurs. If you add the same node twice to the list of nodes that should not be used for the job, the second time that you add the node has no effect. You cannot specify the /addexcludednodes parameter if you also specify the /clearexcludednodes or /removeexcludednodes parameter. Note This parameter was introduced in HPC Pack 2008 R2 and is not supported in previous versions. |
||||||||||||
/clearexcludednodes |
Removes all of the nodes in the list of nodes that should not be used for the job from that list. To remove a specific node from the list of nodes that should not be used for the job, use the /removeexcludednodes parameter. You cannot specify the /clearexcludednodes parameter if you also specify the /addexcludednodes or /removeexcludednodes parameter. Note This parameter was introduced in HPC Pack 2008 R2 and is not supported in previous versions. |
||||||||||||
/removeexcludednodes:<node_list> |
Specifies the names of the nodes that you want to remove from the list of nodes on which the job should not run in a format of <node1_name>[,<node2_name>…]. To remove all of the nodes on the list of nodes that should not be used for the job from that list, use the /clearexcludednodes parameter. If you specify a node that does not currently belong to the HPC cluster or a node that is part of the HPC cluster but is not part of the current list of nodes that should not be used for the job, the /removeexcludednodes parameter has no effect and no error occurs. You cannot specify the /removeexcludednodes parameter if you also specify the /addexcludednodes or /clearexcludednodes parameter. Note This parameter was introduced in HPC Pack 2008 R2 and is not supported in previous versions. |
||||||||||||
/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. |
||||||||||||
/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 modify command behaves as if you specified a value of True. If you do not specify the /exclusive parameter, the job modify 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 /faildependenttasks is declared without a value, True is assumed. If /faildependenttasks is not declared, False 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 modify command behaves as if you specified a value of True. If you do not specify the /failontaskfailure parameter, the job modify 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 a minutes value is used, it must be an integer. The minutes to hold are converted to UTC at the time job modify is applied. If the value for /holduntil is empty, any current /holduntil value is erased and the job is no longer 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 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. Note This parameter was introduced in HPC Pack 2008 R2 and is not supported in previous versions. |
||||||||||||
/jobfile:<path>\<file_name> |
Deprecated. Use the other parameters for this command to change the settings for the job instead. |
||||||||||||
/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. |
||||||||||||
/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. |
||||||||||||
/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 both the /nodegroups and /requestednodes 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. 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. Note This parameter was introduced in HPC Pack 2008 R2 and is not supported in previous 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 previous 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. |
||||||||||||
/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 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. |
||||||||||||
/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 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. |
||||||||||||
/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 by 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. |
||||||||||||
/password:<password> |
Specifies the password for the account under which the job should run. If you specify the /user parameter but not the /password parameter, the job modify command prompts you for the password and whether to store the password. |
||||||||||||
/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. For 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. 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 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 a format of [[<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 modify command behaves as if you specified a value of True. If you do not specify the /rununtilcanceled parameter, the job modify 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 that contains the job that you want to modify. 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}] |
Specifies that all resources will be allocated on one node. If /singlenode is declared without value, 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_number> |
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. The default value is 0. Note This parameter was introduced in HPC Pack 2012 R2 Update 1. It is not available in previous versions. |
||||||||||||
/user:[<domain>\]<user_name>] |
Specifies the user name and, optionally, the domain of the account under which the job should run. If you do not specify this parameter, the job runs under the account that is used to submit the job. |
||||||||||||
/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. min or max can be used as the start or end of an integer range. For example, 0..max represents all 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
You cannot change the properties of a job in the finished state.
For jobs in the running state, you can only change the following properties:
Name
Project
RunTime
RunUntilCanceled
Priority
AddExcludedNodes
ClearExcludedNodes
RemoveExcludedNodes
NotifyOnCompletion
Progress
ProgressMessage
JobEnv
Starting in HPC Pack 2008, you can end a job that is set to run until it is canceled by using the job modify command to set the RunUntilCanceled property to False. For more information about how to end a job that it set to run until it is canceled, see "End a Run Until Canceled Job as Finished" in the Operations section (https://go.microsoft.com/fwlink/?LinkId=120726) of the Windows HPC Server 2008 Technical Library.
Starting in HPC Pack 2008 R2, you can end a job that is set to run until it is canceled and set the state of that job to Finished by using the job finish command.
Examples
To set the project for the job with a job identifier of 47 to Cluster Testing, the job template for the job to MyJobTemplate, the run-time limit of the job to 30 minutes, and the priority of the job to AboveNormal, use the following command:
job modify 47 /jobtemplate:MyJobTemplate /projectname:"Cluster Testing" /runtime:0:0:30 /priority:AboveNormal
To specify that the job with an identifier of 98 should not start to run before 10:00 pm local time of the current day, to set the progress of the job to 0, to set the status message of the job to "on hold", and to specify that you want to receive email notification when the job completes, use the following command:
job modify 98 /holduntil:"10:00 pm" /progress:0 /progressmsg:"on hold" /notifyoncompletion:true