ICluster::ExecuteCommand method

Executes a task on a specified group of nodes in the cluster.


HRESULT ExecuteCommand(
  [in]           long               Id,
  [in]           ITask              *Task,
  [in]           BSTR               userName,
  [in]           BSTR               password,
  [in]           VARIANT_BOOL       isConsole,
  [in, optional] long               hwndParent,
  [out]          IClusterEnumerable **pRetVal


  • Id [in]
    The command identifier. To get this value, call the ICluster::GetNewCommandId method.

  • Task [in]
    An ITask interface of the task to execute. To create the task, call the ICluster::CreateTask method.

  • userName [in]
    The name of the RunAs user, in the form domain\user. The user name is limited to 80 Unicode characters.

    If userName is NULL, empty, or not valid, the cluster searches the calling user's credential cache for the credentials to use. If the cache contains only one credential, it is used. If the cache does not exist or contains multiple credentials, the user is prompted for the credentials.

  • password [in]
    The RunAs user's password. The password is limited to 127 Unicode characters. If this parameter is NULL or empty, the method uses the cached credentials. See ICluster::SetCachedCredentials. If the credentials are not cached, the current user is prompted for the credentials. If the isConsole parameter is VARIANT_TRUE, the user is prompted in the console window; otherwise, the standard credentials dialog box is used.

  • isConsole [in]
    Set the value to VARIANT_TRUE if the application is a console-mode application. Set the value to VARIANT_FALSE if the application is a GUI application.

  • hwndParent [in, optional]
    The handle to use as the parent window for the modal credentials dialog box. If 0, HWND_DESKTOP is used. The handle is ignored if the isConsole parameter is VARIANT_TRUE.

  • pRetVal [out]
    An IClusterEnumerable interface that contains an IExecutionResult interface for each instance of the task (one result for each node on which the task ran). When you enumerate the items in this collection, the items are returned as variants. The variant type is VT_DISPATCH. Query the pdispVal member for the IExecutionResult interface.

Return value

If the method succeeds, the return value is S_OK. Otherwise, the return value is an error code. To get a description of the error, call the ICluster::get_ErrorMessage method.


This method can be called only by a cluster administrator.

An instance of the task runs on the nodes specified in the ITask::put_RequiredNodes method. If no nodes are specified, the command runs on each node in the cluster. The task does not wait in the queue to be scheduled. Standard output and standard error are captured in the result. To get the output, call the IExecutionResult::get_Output method.

To cancel all instances, call the ICluster::EndCommand method.

If the task generates a lot of output and there are many nodes in the cluster, you should consider using the ICluster::ExecuteCommandWithPaging method to limit the amount of memory used for the output (the amount of memory used is the size of the output multiplied by the number of nodes in the cluster).


For an example that shows calling this method, see Executing a Command.



Compute Cluster Pack Client Utilities

Type library


See also