Cluster-wide and Task Environment Variables in Windows HPC Server 2008

  • Article

Applies To: Windows HPC Server 2008

Windows® HPC Server 2008 uses a variety of environment variables and supports their use as aliases for recurring values or sets of values in HPC Cluster Manager and HPC Job Manager, a Command Prompt window, HPC PowerShell, or scripts and batch files.

For example, you can use environment variables to specify the path for a job’s output file:

job submit /stdout:%USERPROFILE%\%CCP_JOBID%.txt myapp.exe

This topic includes the following sections:

  • New environment variables in Windows HPC Server 2008

  • Environment variable hierarchy

  • Adding cluster-wide environment variables

  • System environment variables that are set by HPC Pack

  • Built-in cluster-wide environment variables

  • Built-in task environment variables

New environment variables in Windows HPC Server 2008

The table below describes the built-in cluster-wide and task environment variables that are new in Windows HPC Server 2008.

Environment variable Description

WCF_NETWORKPREFIX

The prefix for the network that the Windows Communication Foundation (WCF) broker and WCF service use for internal traffic. This is a cluster-wide variable.

HPC_ATTACHTOCONSOLE

Allows a job to be started in a console session. A console session is necessary if the task requires a Graphics Processing Unit (GPU) for acceleration. In Windows HPC Server 2008, the video driver is only loaded in the console session, so programs which rely on access to the video driver must run in the console session.

With a value of True, the HPC Job Scheduler service will attempt to start the job in the console session. If a console session that has the same owner as the user who submitted the job exists, then the job will start. If there is no console session that is owned by the job owner, then the job will fail. You can run qwinsta.exe at a command prompt to see a list of sessions that are currently active on your server.

With a value of Try, the job will run even if it cannot be attached to a console session.

HPC_ATTACHTOSESSION

Allows a job to be started in a terminal server session. This is helpful if you have an interactive program that you would like to have connected to the session and be able to remotely view the program while it is running.

With a value of True, the HPC Job Scheduler service will attempt to start the job in a terminal server session. If a terminal server session that has the same owner as the user who submitted the job exists, then the job will start. If there is no terminal server session that is owned by the job owner, then the job will fail. You can run qwinsta.exe at a command prompt to see a list of sessions that are currently active on your server.

With a value of Try, the job will run even if it cannot be attached to a terminal server session.

CCP_TASKINSTANCEID

The numeric ID of a parametric subtask. The HPC Job Scheduler service assigns this number when the task is created.

noteNote
In Windows HPC Server 2008, all subtasks of a parametric task have the same TaskID.

Environment variable hierarchy

Sometimes the same environment variable can be set at different levels. If different values are set for the same environment variable, the environment variable hierarchy determines which value is used in the run-time environment of a task.

The environment variable hierarchy used for tasks that are running on the cluster is as follows:

  1. Task

  2. Cluster-wide

  3. User

  4. System

For example, if %TMP% is set at the task level and at the user level, the task level setting takes precedence in the run-time environment of that task.

Adding cluster-wide environment variables

Cluster-wide environment variables are defined by the cluster administrator and are set in the run-time environment of all tasks that are running on the cluster. An administrator can create and set cluster-wide environment variables to provide default values for tasks. A job owner can override the cluster-wide default by setting the same variable name with a different value at the task level. Job owners can set the environment variable property for a task when they create or modify a task.

Note

Built-in HPC Server environment variables begin with CCP. To avoid potential naming conflicts, do not start your variable names with CCP.

You can use the following commands to view or set (that is, create or change) cluster-wide environment variable name and value pairs:

Interface View Set

Command Prompt window

cluscfg listenvs

cluscfg setenvs

HPC PowerShell

Get-HpcClusterProperty

Set-HpcClusterProperty

System environment variables that are set by HPC Pack

The following system environment variables are set on the head node when you install Microsoft® HPC Pack 2008:

Environment variable Description

CCP_DATA

The location of the Microsoft HPC Pack Data folder.

CCP_HOME

The location of the Microsoft HPC Pack folder.

CCP_JOBTEMPLATE

The job template to use for submitting jobs to the cluster if none is specified by the job owner. By default, this is the Default job template. For more information, see “The Default job template” section in Job Templates.

CCP_SCHEDULER

The name of the head node.

Built-in cluster-wide environment variables

Cluster-wide environment variables are defined by the cluster administrator, and they are set in the environment of all tasks that are running on the cluster.

There are three built-in cluster-wide environment variables. These environment variables are set during system deployment, and they are rarely changed manually or used in commands.

Environment variable Description

CCP_CLUSTER_NAME

The name of the cluster, which is the same name as the computer that serves as the head node.

CCP_MPI_NETMASK

The network mask for the network interface that the Message Passing Interface (MPI) process uses. This environment variable can be temporarily changed to move application traffic from the application network to a different HPC network (for example, the private network). Performing this change might be useful when troubleshooting your application network.

For example, if you want to move the application traffic to the private network, and the current configuration of the private network has IP addresses in the 10.0.x.x range, with subnet mask 255.255.0.0, the following setting changes the application traffic to run on that network:

CCP_MPI_NETMASK = 10.0.0.0/255.255.0.0

noteNote
A user can set or change the network that a specific job uses for MPI traffic by including the MPICH_NETMASK environment variable in the mpiexec arguments, for example: mpiexec -env MPICH_NETMASK 157.59.0.0/255.255.0.0 myApp.exe

WCF_NETWORKPREFIX

The prefix for the network that the Windows Communication Foundation (WCF) broker and WCF service use for internal traffic.

Built-in task environment variables

Task environment variables apply only to a task, and most task environment variables are set automatically by the HPC Node Manager service of the compute node that is performing the task. This is the means by which the standard task options are communicated to the process or processes. Task environment variables can be useful as aliases in commands because they are dynamic, and they contain information that is not necessarily known beforehand.

There are two task environment variables that are not set automatically: HPC_ATTACHCONSOLE and HPC_ATTACHSESSION. You can set these variables to get special handling for your task. You can set the environment variable property for a task when you create or modify a task.

Environment Variable Description

HPC_ATTACHTOCONSOLE

Allows a job to be started in a console session. A console session is necessary if the task requires a graphics processing unit (GPU) for acceleration. In Windows HPC Server 2008, the video driver is only loaded in the console session, so programs that rely on access to the video driver must run in the console session.

With a value of True, the HPC Job Scheduler service attempts to start the job in the console session. If a console session exists that has the same owner as the user who submitted the job, then the job starts. If there is no console session that is owned by the job owner, then the job fails. You can run qwinsta.exe at a command prompt to see a list of sessions that are currently active on your server.

With a value of Try, the task will run even if it cannot be attached to a console session.

HPC_ATTACHTOSESSION

Allows a job to be started in a remote desktop session. This is helpful if you have an interactive program that you would like to connect to the session and be able to remotely view the program while it is running.

With a value of True, the HPC Job Scheduler service attempts to start the job in a remote desktop session. If a remote desktop connection exists that has the same owner as the user who submitted the job, then the job starts. If there is no remote desktop session that is owned by the job owner, then the job fails. You can run qwinsta.exe at a command prompt to see a list of sessions that are currently active on your server.

With a value of Try, the job runs even if it cannot be attached to a remote desktop session.

CCP_NODES

The nodes that are allocated to the task, and the number of processes to run on each node.

CCP_ CLUSTER_NAME

The name of the head node.

CCP_ MPI_NETMASK

The network mask for the network interface that the Message Passing Interface (MPI) process uses. By default, the value set by the cluster-wide CCP_MPI_NETMASK environment variable is used.

This environment variable can be temporarily changed to move application traffic from the application network to a different HPC network (for example, the private network). You can set or change the network that a specific job uses for MPI traffic by including the MPICH_NETMASK environment variable in the mpiexec arguments. For example:

mpiexec -env MPICH_NETMASK 157.59.0.0/255.255.0.0 myApp.exe

CCP_TASKINSTANCEID

The numeric ID of a parametric subtask. The HPC Job Scheduler service assigns this number when the task is created.

noteNote
In Windows HPC Server 2008, all subtasks of a parametric task have the same TaskID.

CCP_RUNTIME

The amount of time that the task is allowed to run. (The job run time overrides the task run time.)

CCP_TASKSYSTEMID

The globally unique identifier for this task. This internal identifier is unique across all tasks in the cluster.

CCP_TASKCONTEXT

The context of the task that is used by MPI or other applications to communicate with the cluster.

CCP_WORKDIR

The working directory for input, output, and standard error files to be used while the task runs. The default is %USERPROFILE%.

CCP_MPI_WORKDIR

The working directory for input, output, and standard error files to be used while the task runs. The default is %USERPROFILE%.

CCP_RERUNNABLE

If the task runs and fails due to cluster problems (such as a node becoming unreachable) and this variable is True, the HPC Job Scheduler service attempts to rerun the task. If it is False, the task fails after the first run attempt fails.

CCP_NUMCPUS

The number of resources assigned to the task.

CCP_ENVLIST

The environment variables that were set for this task by the person who created the task.

CCP_EXCLUSIVE

With a value of True, no other tasks can be run on a compute node at the same time as the task.

CCP_JOBNAME

The name of the job to which the task belongs.

WCF_NETWORKPREFIX

The prefix for the network that the Windows Communication Foundation (WCF) broker and WCF service use for internal traffic.

CCP_TASKID

The numeric ID of the task. The HPC Job Scheduler service assigns this number when the task is created.

Note

In Windows HPC Server 2008, all subtasks of a parametric task have the same TaskID. Parametric subtasks are further identified by the task environment variable CCP_TASKINSTANCEID.

CCP_JOBID

The numeric ID of the job to which the task belongs. The HPC Job Scheduler service assigns this number when the job is created.

CCP_STDIN

The redirect target for the stdin file.

CCP_STDOUT

The redirect target for the stdout file.

CCP_STDERR

The redirect target for the stderr file.

Additional references