ISchedulerJob::CancelTask_3 method

Cancels the specified task with the option to specify that you want to cancel the task immediately without using the grace period for canceling a task, and provides the specified message to the user to explain the why task was canceled.

Syntax

HRESULT CancelTask_3(
  [in] ITaskId      *TaskId,
  [in] BSTR         Message,
  [in] VARIANT_BOOL isForce
);

Parameters

• TaskId [in]
  A ITaskId interface for the task that you want to cancel.

• Message [in]
  A string that specifies the message that you want to provide to the user to explain why the task was canceled.

• isForce [in]
  A VARIANT_BOOL that specifies whether to stop the task immediately without using the grace period for canceling a task.

  Set this parameter to VARIANT_TRUE to indicate that the method should stop the task immediately without using the grace period for canceling a task. Set it to VARIANT_FALSE to indicate that the method should use the grace period for canceling a task.

Return value

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

Remarks

To cancel a task, the state of the task must be Configuring, Submitted, Queued, or Running. If a task is running when it is canceled, the task ends and the state of the task changes to Failed. If you cancel a task with a state of Configuring or Queued, the state of the task changes to Canceled.

If you cancel a parametric task, the state of the parametric master task always changes to Canceled, and all of the individual subtasks are canceled. If the subtask is running when you cancel the parametric task, the state of the subtask changes to Failed. If the subtask is in a state other than Running, the state of the subtask changes to Canceled.

To determine the state of a task, use the ISchedulerTask::State property.

You can call the ISchedulerJob::RequeueTask method to queue the task again.

An application must respond to the CTRL+BREAK key combination to use the grace period for tasks.

To cancel a task without providing a message to the user that explains the reason you canceled the task, use the ISchedulerJob::CancelTask method.

Calling the ISchedulerJob::CancelTask_2 method is equivalent to calling the ISchedulerJob::CancelTask_3 method with the isForce parameter set to VARIANT_FALSE. For better performance, call the ISchedulerJob::CancelTask_3 method with the isForce parameter set to VARIANT_FALSE instead of calling ISchedulerJob::CancelTask_2.

Requirements

See also

ISchedulerJob

ISchedulerJob::CancelTask

ISchedulerJob::CancelTask_2

ISchedulerJob::AddTask

ISchedulerJob::CreateTask

ISchedulerJob::SubmitTask