Export (0) Print
Expand All

Add-HpcTask

Applies To: Windows HPC Server 2008

Creates a new task and adds it to the specified job.

Syntax

Add-HpcTask [-CommandLine <string>] [-Depend <string[]>] [-End <int>] [-Env <string[]>] [-Exclusive <Boolean>] [-Increment <int>] [-JobId <int>] [-Name <string>] [-NumCores <string>] [-NumNodes <string>] [-NumSockets <string>] [-Parametric] [-RequiredNodes <string[]>] [-Rerunnable <Boolean>] [-RunTime <string>] [-Scheduler <string>] [-Start <int>] [-Stderr <string>] [-Stdin <string>] [-Stdout <string>] [-TaskFile <string>] [-WorkDir <string>] [<CommonParameters>]

Add-HpcTask [-CommandLine <string>] [-Depend <string[]>] [-End <int>] [-Env <string[]>] [-Exclusive <Boolean>] [-Increment <int>] [-Job <HpcJob>] [-Name <string>] [-NumCores <string>] [-NumNodes <string>] [-NumSockets <string>] [-Parametric] [-RequiredNodes <string[]>] [-Rerunnable <Boolean>] [-RunTime <string>] [-Scheduler <string>] [-Start <int>] [-Stderr <string>] [-Stdin <string>] [-Stdout <string>] [-TaskFile <string>] [-WorkDir <string>] [<CommonParameters>]

Detailed Description

Creates a new task and adds it to the specified job on an HPC cluster. You can use the Add-HpcTask cmdlet on jobs that you have not yet submitted, jobs that you submitted and that are currently waiting in the queue, or jobs that are already running. You cannot add tasks to a job that has finished. When the resources that the job scheduler allocated to the job are available, the task begins to run.

Parameters

-CommandLine <string>

Specifies the command line for the task, including the command or application name and any necessary arguments. You must either specify the CommandLine parameter, or specify a task XML file for the TaskFile parameter that includes a value for the CommandLine attribute.

 

Required?

false

Position?

named

Default Value

no default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Depend <string[]>

Specifies a list of names for the tasks in the specified job on which the new task depends. The new task does not start until all the tasks in the list finish running.

 

Required?

false

Position?

named

Default Value

no default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-End <int>

Specifies the ending index for a parametric task. The ending index must be larger than the starting index. A parametric task runs the command that the CommandLine parameter specifies multiple times, substituting the current index value for any asterisks (*) in the command line. The current index starts at the starting index that the Start parameter specifies, and increases by the value that the Increment parameter specifies each subsequent time the command runs. When the current index exceeds the ending index, the task stops running the command.

 

Required?

false

Position?

named

Default Value

100

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Env <string[]>

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[,...]]. To unset an environment variable, do not specify a value. For example, "variable_to_unset_name=".

 

Required?

false

Position?

named

Default Value

no default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Exclusive <Boolean>

Specifies whether the job scheduler should ensure that no other task runs on the same node as this task while this task runs.

A non-zero value or $true indicates that the job scheduler should ensure that no other task runs on the same node as this task while this task runs. If you specify a non-zero value or $true value for the Exclusive parameter for the task, you must also have specified a non-zero value or $true value for the Exclusive parameter for the job to which you are adding the task, or else the task fails on submission.

A value of 0 or $false indicates that this task can share compute nodes with other tasks.

 

Required?

false

Position?

named

Default Value

$false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Increment <int>

Specifies the value to use when incrementing the index for a parametric task. This value must be a positive integer. A parametric task runs the command that the CommandLine parameter specifies multiple times, substituting the current index value for any asterisks (*) in the command line. The current index starts at the starting index that the Start parameter specifies, and increases by the value that the Increment parameter specifies each subsequent time the command runs. When the current index exceeds the ending index that the End parameter specifies, the task stops running the command.

 

Required?

false

Position?

named

Default Value

1

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Job <HpcJob>

Specifies an HpcJob object that corresponds to the job to which you want to add the new task. Use the Get-HpcJob cmdlet to get an HpcJob object for a job. You cannot use the Job parameter together with the JobId parameter.

 

Required?

false

Position?

named

Default Value

no default

Accept Pipeline Input?

true (ByValue)

Accept Wildcard Characters?

false

-JobId <int>

Specifies the job identifier of the job to which you want to add the new task. Use the Get-HpcJob cmdlet to get a list of jobs and their identifiers. You cannot use the JobId parameter together with the Job parameter.

 

Required?

false

Position?

named

Default Value

no default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Name <string>

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.

 

Required?

false

Position?

named

Default Value

no default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-NumCores <string>

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 cmdlet 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 task or the job that contains the task.

The minimum and maximum values can only be positive integers.

You cannot specify the NumCores parameter if you also specify the NumNodes or NumSockets parameter.

 

Required?

false

Position?

named

Default Value

1-1

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-NumNodes <string>

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 cmdlet 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.

You cannot specify the NumNodes parameter if you also specify the NumCores or NumSockets parameter.

 

Required?

false

Position?

named

Default Value

1-1

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-NumSockets <string>

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 cmdlet 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.

You cannot specify the NumSockets parameter if you also specify the NumCores or NumNodes parameter.

 

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Parametric

Indicates that the new task is a parametric task. A parametric task runs the command that the CommandLine parameter specifies multiple times, substituting the current index value for any asterisks (*) in the command line. If you specify this parameter, you should also specify values for the Start, End, and Increment values if you do not want to use the default values for these parameters that define the index values for the parametric task.

 

Required?

false

Position?

named

Default Value

not applicable

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-RequiredNodes <string[]>

Specifies a list of nodes on which the task must run. The job scheduler exclusively allocates all of the nodes in this list to run the task.

 

Required?

false

Position?

named

Default Value

no default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Rerunnable <Boolean>

Specifies whether the job scheduler attempts to rerun the task if the task runs and fails.

A non-zero value or $true indicates that the job scheduler should attempt to rerun the task if the task runs and fails.

A value of 0 or $false indicates that the job scheduler should not attempt to rerun the task if the task runs and fails, but should move the task to the failed state immediately.

The cluster administrator can configure the number of times that the job scheduler tries to rerun a rerunnable task before moving the task to the failed state.

 

Required?

false

Position?

named

Default Value

$false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-RunTime <string>

Specifies the maximum amount of time the task should run. After the task runs for this amount of time, the job scheduler 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 cmdlet 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.

 

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Scheduler <string>

Specifies the host name or IP address of the head node for the cluster that includes 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 cmdlet uses the scheduler on the head node that the CCP_SCHEDULER environment variable specifies. To set this environment variable, run the following cmdlet:

Set-Content Env:CCP_SCHEDULER <head_node_name>

 

Required?

false

Position?

named

Default Value

%CCP_SCHEDULER%

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Start <int>

Specifies the starting index for a parametric task. The starting index must be less than the ending index. A parametric task runs the command that the CommandLine parameter specifies multiple times, substituting the current index value for any asterisks (*) in the command line. The current index starts at the starting index, and increases by the value that the Increment parameter specifies each subsequent time the command runs. When the current index exceeds the ending index that the End parameter specifies, the task stops running the command.

 

Required?

false

Position?

named

Default Value

1

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Stderr <string>

Specifies the name for the file to which the task should redirect the standard error stream, including the full path or path 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 job scheduler database 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.

 

Required?

false

Position?

named

Default Value

see the parameter description

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Stdin <string>

Specifies the name for the file from which the task should receive standard input, including the full path or path 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.

 

Required?

false

Position?

named

Default Value

no default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Stdout <string>

Specifies the name for the file to which the task should redirect standard output, including the full path or path 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 job scheduler database 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.

 

Required?

false

Position?

named

Default Value

see the parameter description

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-TaskFile <string>

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 can create a task XML file for another task by running the Export-HpcTask cmdlet, and then specify that XML file for this parameter to apply the settings for that task to the new task. You must either specify a task XML file for the TaskFile parameter that includes a value for the CommandLine attribute, or specify the CommandLine parameter.

 

Required?

false

Position?

named

Default Value

no default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-WorkDir <string>

Specifies the working directory under which the task should run. The maximum length of value for this parameter is 160 characters.

 

Required?

false

Position?

named

Default Value

%USER_PROFILE%

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters.

Input and Return Types

The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet emits.

 

Input Type

The HpcJob object to which the cmdlet should add the task.

Return Type

The modified HpcJob object.

Example 1

C:\PS>$j = New-HpcJob -name "Sample"
$j | Add-HpcTask -name "Basic Task" -command "hostname.exe" -workdir "\\headnode\output share" -stdout "hostname.out"

Creates a job named Sample that includes a single task named Basic Task. This task runs the hostname command on a single core. The task saves the output of the command to a file stored on a share on the head node of the HPC cluster.

Example 2

C:\PS>$j = New-HpcJob -name "Sample"
$j | Add-HpcTask -name "Sweep Task" -Parametric -Start 10 -End 100 -Increment 2 -command "Echo *" -stdout "\\headnode\output share\sweepstep*.out"

Creates a job named Sample that contains a parametric sweep task named Sweep Task. This task runs 45 times with a set of values from 10 to 100, where each value is greater than the previous value by two.In other words, the task runs each of the following command lines independently:

Echo 10

Echo 12

Echo 14

...

Echo 98

Echo 100

This sweep creates the following files in the \\headnode\output share

directory:

sweepstep10.out

sweepstep12.out

...

sweepstep100.out

The sweep creates 45 files in all, each of which contains its index number.

See Also

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft