IScheduler::SetClusterParameter method

  • Article

Sets a configuration parameter for the cluster.

Syntax

HRESULT SetClusterParameter(
  [in] BSTR Name,
  [in] BSTR Value
);

Parameters

  • Name [in]
    The name of the parameter. The names are case-insensitive.

  • Value [in]
    The value of the parameter.

Return value

If the method succeeds, the return value is S_OK. Otherwise, the return value is an error code.

Remarks

Only a user with administrator privileges can set the cluster's configuration parameters.

You can only update HPC configuration parameters; you cannot delete them. The method fails if the HPC parameter value is not valid.

To retrieve the current configuration values, access the IScheduler::ClusterParameters scheduler property.

The following are the supported configuration parameters.

Parameter Description

AffinityType

Specifies a processor affinity setting that controls the association between tasks and cores. The following list describes the possible values for this parameter:

AllJobs

Directs the HPC Node Manager Service to set the processor affinity for any task to which an entire node is not allocated. This setting is the best choice for jobs such as parameter sweeps and service-oriented architecture (SOA) jobs, for which multiple instances of the application can run per node and for which you want these instances to be isolated from each other. This setting corresponds to the affinity behavior in Windows HPC Server 2008.

NoJobs

Directs the HPC Node Manager Service to never set the processor affinity on any task. This setting is an excellent choice if you are running MPI tasks and you want to be sure that you can use the -affinity option for the mpiexec command, even when jobs share nodes. This setting is also useful for applications that set their own processor affinity. This setting corresponds to the affinity behavior in Windows Compute Cluster Server 2003.

NonExclusiveJobs

Directs the HPC Node Manager Service to not set affinity on jobs that are marked as exclusive. This setting is the ideal choice for jobs that contain only one task, because this setting enables that task to take advantage of all cores on the nodes to which the task is assigned. This setting provides new affinity setting behavior for Windows HPC Server 2008 with SP1, and it is the default setting for Windows HPC Server 2008 with SP1, Windows HPC Server 2008 with SP2, and Windows HPC Server 2008 R2, because this setting provides the generally preferred behavior for MPI tasks, which are most likely to be sensitive to affinity settings. When you use this setting, MPI tasks in exclusive jobs can take advantage of the -affinity option of the mpiexec command even if the task is not allocated an entire node.

This parameter is supported only for Windows HPC Server 2008 with SP1, Windows HPC Server 2008 with SP2, and Windows HPC Server 2008 R2.

AllowNewUserConnections

Specifies whether the HPC Job Scheduler Service should allow users to connect to the HPC Job Scheduler Service to create and submit new jobs and tasks.

A True value indicates that the HPC Job Scheduler Service should allow users to connect to the HPC Job Scheduler Service to create and submit new jobs and tasks. The HPC Job Scheduler Service places the jobs in a queue and runs them in the order that is defined by the scheduling policy for the HPC cluster.

A False value indicates that the HPC Job Scheduler Service should allow only cluster administrators and system services that are running on the head node of the HPC cluster to connect to the HPC Job Scheduler Service, and it should not allow users without administrative credentials to connect to the HPC Job Scheduler Service. Use a setting of False when you are doing maintenance work for the cluster and you need to prevent users from accessing the HPC Job Scheduler Service and its database. For example, you would use a setting of False while you are backing up and restoring the database. This setting does not prevent cluster administrators from creating and submitting jobs and tasks.

The default value of this parameter is True.

When you upgrade an HPC cluster from HPC Pack 2008 to HPC Pack 2008 R2, the AllowNewUserConnections property for the cluster is initially set to False, and it automatically resets to True when the upgrade is complete.

This parameter is supported only for HPC Pack 2008 R2.

ActivationFilterProgram

Specifies the path and file name of the activation filter program, if one exists. The activation filter program is called every time a job starts. You can use the activation filter program to delay the start of a job.

This application returns 0 if the job should be started and a nonzero value otherwise. It must accept a single command-line argument, which is an absolute path to an XML file that specifies the terms of the job. The job terms are the attributes of the Job element. The CustomProperties element contains the name/value pairs for application-defined extended job terms. For more information, see Job Schema.

This parameter has no default value.

ActivationFilterTimeout

Specifies the number of seconds that the activation filter program can run before the HPC Job Scheduler Service cancels the activation filter program and starts the job.

The range of valid values is from 1 through 120. The default value is 15 seconds.

AutomaticGrowthEnabled

Specifies whether to automatically add free resources to running jobs that still have additional tasks to run.

A value of True indicates that the HPC Job Scheduler Service should automatically add free resources to running jobs that still have additional tasks to run.

A value of False indicates that the HPC Job Scheduler Service should not automatically add free resources to running jobs that still have additional tasks to run.

The default value is True.

AutomaticShrinkEnabled

Specifies whether to automatically remove unneeded resources from running jobs that have no additional tasks to run.

A value of True indicates that the HPC Job Scheduler Service should automatically remove unneeded resources from running jobs that have no additional tasks to run. The HPC Job Scheduler Service does not shrink the resources beyond the minimum requested.

A value of False indicates that the HPC Job Scheduler Service should not automatically remove unneeded resources from running jobs that have no additional tasks to run.

The default value is True.

BackfillLookahead

Specifies the number of jobs that the HPC Job Scheduler Service searches to find jobs that can backfill the jobs at the top of the job queue.

A value of 0 indicates that the HPC Job Scheduler Service should not backfill the jobs at the top of the job queue.

A negative value indicates that the HPC Job Scheduler Service should search though the entire job queue to find jobs that can backfill the jobs at the top of the job queue.

The default value is 1000.

BrokerTaskProgram

Specifies the command that the HPC Job Scheduler Service runs to start a broker task. By changing this value, you can replace the Windows Communication Foundation (WCF) Broker that Windows HPC Server 2008 includes with a custom WCF Broker.

The default value is %CCP_HOME%bin\HpcWcfBroker.exe.

This configuration parameter is supported only for Windows HPC Server 2008.

DefaultHoldDuration

Specifies the default amount of time in seconds before the HPC Job Scheduler Service reevaluates jobs that are placed on hold by an activation filter program.

The default value is 900 seconds, which equals 15 minutes.

This parameter is supported only for HPC Pack 2008 R2.

EmailFromAddress

Specifies the email address to use on the From line for email notifications.

This parameter has no default value.

This parameter is supported only for HPC Pack 2008 R2.

EmailNotificationEnabled

Specifies whether the HPC Job Scheduler Service should send email notifications about jobs when job owners specify that they want to receive such notifications.

A True value indicates that the HPC Job Scheduler Service should send email notifications about jobs. A False value indicates that the HPC Job Scheduler Service should not send email notifications about jobs.

The default value is False.

This parameter is supported only for HPC Pack 2008 R2.

EmailSmtpServer

Specifies the name or IP address of the Simple Mail Transfer Protocol (SMTP) server that the HPC Job Scheduler Service should use to send email notifications, if email notifications are enabled.

This parameter has no default value.

This parameter is supported only for HPC Pack 2008 R2

.

EmailUseSsl

Specifies whether the SMTP server that the HPC Job Scheduler Service uses to send email notifications requires a secure connection.

A True value indicates that the SMTP server requires a secure connection. A False value indicates that the SMTP server does not require a secure connection.

The default value is False.

This parameter is supported only for HPC Pack 2008 R2.

ExcludedNodesLimit

Specifies the maximum number of nodes that you can add to the list of nodes on which a job should not run. For SOA jobs, the broker cancels sessions that try to exclude a greater number of nodes than are specified by this setting. For other types of jobs, an error occurs if you try to add a greater number of nodes than are specified by this setting to the list of nodes on which a job should not run.

The default value is 10.

This parameter is supported only for HPC Pack 2008 R2.

HeartbeatInterval

Specifies how often the HPC Job Scheduler Service sends health probes to the HPC Node Manager Service to confirm that the nodes in the HPC cluster are still reachable. This interval is specified in seconds.

The default value is 30.

InactivityCount

Specifies the number of heartbeats a compute node can miss before the HPC Job Scheduler Service declares the node unreachable. A compute node misses a heartbeat if there is no reply from the health probes.

The default value is 3.

JobCleanupHour

Specifies the hour of the day in 24-hour time at which the HPC Job Scheduler Service should delete old job records from the database. For example, a value of 23 causes the HPC Job Scheduler Service to delete job records that are older than the number of days that the TTLCompletedJobs property specifies at 11:00 PM each day.

The possible values of this parameter are from 0 through 23.

The default value is 2.

JobRetryCount

Specifies the maximum number of times that the HPC Job Scheduler Service automatically tries to rerun a job when a system error rather than a job error occurs before marking the job as Failed.

The value range for this parameter is from 0 through 2,147,483,647. The default value is 3.

NodeReleaseTaskTimeout

Specifies the maximum run time in seconds for Node Release tasks.

Node Release tasks run even when a job is canceled. A cluster administrator or the job owner can force a job that is being canceled to skip the Node Release task.

The value for this parameter cannot be negative. The default value is 15.

This parameter is supported only for HPC Pack 2008 R2.

PreemptionType

Specifies the type of preemption that the HPC Job Scheduler Service applies. The following list describes the possible values for this parameter.

Graceful

Indicates that queued job will take resources away from lower priority jobs that are running as the tasks that are running for those jobs complete. This is the default.

Immediate

Indicates that the HPC Job Scheduler Service automatically cancels running jobs when a job with a higher priority is waiting in the queue.

None

Indicates that preemption is turned off. Jobs that are running will continue to run until they complete, and higher priority jobs in the queue must wait for the lower priority jobs to complete before they can begin to run.

To set the preemption policy for a job, use the ISchedulerJob::CanPreempt property.

PriorityBias

Specifies how additional resources are allocated to jobs when the SchedulingMode property is set to Balanced. In the Balanced scheduling mode, additional resources are the cluster resources that exceed the total minimum resources for all running jobs. In the Queued scheduling mode, the PriorityBias property has no effect.

The following list describes the possible values for this parameter.

HighBias

Specifies that a job receives ten times the share of the additional resources as a job that is a full priority range below. A full priority range is a difference of 1000 in the priority values for the jobs. For jobs that have priorities that differ by less than a full priority range, the difference in the share of additional resources allocated to the jobs is scaled appropriately.

MediumBias

Specifies that a job receives twice the additional resources as a job that is a full priority range below. A full priority range is a difference of 1000 in the priority values for the jobs. For jobs that have priorities that differ by less than a full priority range, the difference in the share of additional resources allocated to the jobs is scaled appropriately.

LowBias

Specifies that the additional resources are allocated equally across the job queue.

The default value is MediumBias.

This parameter is supported only for HPC Pack 2008 R2.

RebalancingInterval

Specifies the amount time in seconds between successive operations that the HPC Job Scheduler Service performs to rebalance the allocation of resources in the Balanced scheduling mode. The HPC Job Scheduler Service adds or removes resources from job during these operations to start new jobs, fill available resources, and balance resource allocation based on the setting of the PriorityBias property.

The default value is 10.

This parameter is supported only for HPC Pack 2008 R2.

SchedulingMode

Specifies how to optimize resource allocation for large batch and Message Passing Interface (MPI) workloads or for service workloads.

The following list describes the possible values for this parameter:

Balanced

Specifies that the HPC Job Scheduler Service should attempt to start all incoming jobs as soon as possible at their minimum resource requirements. After all the jobs in the queue have their minimum resources, the HPC Job Scheduler Service should allocate additional cluster resources to jobs based on their priority. The HPC Job Scheduler Service periodically rebalances resource allocation to fill idle resources, start new jobs, and adjust allocation according the PriorityBias setting.

In the Balanced scheduling mode, the PreemptionType, AutomaticGrowthEnabled, and AutomaticShrinkEnabled settings have no effect.

Queued

Specifies that the HPC Job Scheduler Service should start jobs in queue order, and attempt to allocate the maximum requested resources to running jobs.

In the Queued scheduling mode, the PriorityBias and RebalancingInterval settings have no effect.

The default value is Queued.

This parameter is supported only for HPC Pack 2008 R2.

ServiceTaskProgram

Specifies the command that the HPC Job Scheduler Service runs to start a Windows Communication Foundation (WCF) service task on the compute nodes. By changing this value, you can replace the WCF service host that the Windows HPC Server 2008 includes with a custom WCF service host.

The default value is %CCP_HOME%bin\HpcWcfServiceHost.exe.

This configuration parameter is supported only for Windows HPC Server 2008.

SpoolDir

The directory in which the clusrun command temporarily stored output for Microsoft Compute Cluster Pack. The clusrun command in Microsoft HPC Pack 2008 and Microsoft HPC Pack 2008 R2 no longer uses the SpoolDir parameter.

The default value is \\<head_node>\CcpSpoolDir.

SubmissionFilterProgram

Specifies the file name and path for the submission filter program, if one exists. The submission filter program runs every time a job is submitted. You can use the submission filter program to reject or change jobs that users submit to the job scheduler.

This application returns 0 if the job should be submitted and a nonzero value otherwise. It must accept a single command-line argument, which is an absolute path to an XML file that specifies the terms of the job. The job terms are an attribute of the Job element. The ExtendedTerms element contains the name/value pairs for application-defined extended job terms. For more information, see Job Schema.

This parameter has no default value.

SubmissionFilterTimeout

Specifies the number of seconds that the submission filter program can run before the HPC Job Scheduler Service cancels the submission filter program and rejects the job.

The range of valid values is from 1 through 120. The default value is 15.

TaskCancelGracePeriod

Specifies the amount of time in seconds that the HPC Node Manager Service should allow applications to use to exit gracefully.

In HPC Pack 2008 R2, the HPC Node Manager Service stops a running task by sending a CTRL+BREAK signal to the application. To make use of the grace period for task cancelation, the application must include code to handle the CTRL+BREAK event. If the application does not respond to the CTRL+BREAK event, it exits immediately. For an SOA service to use the grace period, it must respond to the ServiceContext.OnExiting event.

The default value is 15.

This parameter is supported only for HPC Pack 2008 R2.

TaskRetryCount

Specifies the maximum number of times that the HPC Job Scheduler Service automatically tries to rerun a task when a system error rather than a task error occurs before marking the task as Failed.

The default value is 3.

TTLCompletedJobs

Specifies the number of days that the records for completed jobs will remain in the SQL database before the HPC Job Scheduler Service deletes the records. A completed job is a job in the Finished, Failed, or Canceled state.

The default value is 5.

 

Requirements

Product

HPC Pack 2008 R2 Client Utilities, HPC Pack 2008 Client Utilities

Type library

 Microsoft.Hpc.Scheduler.tlb

See also

IScheduler

IScheduler::ClusterParameters