---
product: Chilkat
product_version: 11.7.0
language: xbase
language_label: Xbase++
class: TaskChain
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/xbase_TaskChainRef.html
---
# Chilkat TaskChain — Xbase++ — v11.7.0

> Chilkat 11.7.0 · language=xbase · class=TaskChain
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/TaskChain.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/xbase/guide.md`.

## Purpose

**Run multiple asynchronous Chilkat tasks in a defined sequence.**

`Chilkat.TaskChain` manages a sequence of `Chilkat.Task` objects and runs them one after another. It is useful when multiple asynchronous Chilkat operations must execute in a predictable order while still allowing the entire chain to be started, monitored, waited on, canceled, or run synchronously. A task chain can stop when a task fails, or continue depending on the configured behavior.

**Sequential async workflow**

Append multiple `Task` objects and run them in order when one operation must finish before the next begins.

**Chain-level execution**

Start the entire chain, run it synchronously, wait for completion, or cancel the chain as a single coordinated operation.

**Monitor progress and status**

Inspect whether the chain is live, finished, inert, canceled, failed, or still running.

**Access individual tasks**

Retrieve tasks by index after execution to inspect each task's status, success flag, error text, and result.

**Stop-on-failure control**

Use `StopOnFailedTask` to control whether the chain stops at the first failed task or continues to later tasks.

**Diagnostics**

Use task and chain status information together with `LastErrorText` and each task's result details to troubleshoot ordered async workflows.

**Common pattern:** Create the individual async tasks, append them to a `TaskChain` in the required order, set `StopOnFailedTask` as appropriate, run the chain, wait for completion, then inspect each task's success status and result. Use `TaskChain` when operations must run sequentially; use individual `Task` objects when each async operation can be managed on its own.

For an extended overview, see [TaskChain Class Overview](https://www.chilkatsoft.com/taskchain_class_overview.asp).

## Object creation, unlocking and error handling

**Object Creation**

```xbase
LOCAL oTaskChain
oTaskChain := CreateObject("Chilkat.TaskChain")

// ... use oTaskChain ...

oTaskChain:destroy()
```

Xbase++ uses the Chilkat ActiveX through the automation object returned by `CreateObject()`; properties and methods are accessed with the send operator (`oHttp:ConnectTimeout := 30`, `oHttp:Download(cUrl, cPath)`), and `:destroy()` releases the object. Register the Chilkat ActiveX matching the bitness of your Xbase++ application. To bind to a specific major version of Chilkat, append the major version number to the ProgID, such as `CreateObject("Chilkat.TaskChain.11")` for Chilkat v11.\*.\*.

Boolean properties, arguments and return values are integers in the ActiveX: pass `1` or `0`, and test a method's success with `== 1`. A method that fails to return an object returns `NIL`. Objects returned by methods (such as an `HttpResponse` or `JsonObject`) are automation objects too and should likewise be released with `:destroy()`. Methods and properties that pass or return raw byte arrays are not shown on this page; use the `BinData`-based alternatives (methods ending in *Bd*) or the base64 / hex string-encoded variants instead.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Xbase++.

How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `oTaskChain:DebugLogFilePath // Character` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `oTaskChain:LastErrorHtml // Character (read-only)` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `oTaskChain:LastErrorText // Character (read-only)` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `oTaskChain:LastErrorXml // Character (read-only)` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `oTaskChain:LastMethodSuccess // Numeric` | read/write | Indicates the success or failure of the most recent method call: `1` means success, `0` means failure. |
| `LastStringResult` | `oTaskChain:LastStringResult // Character (read-only)` | read-only | In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. |
| `LastStringResultLen` | `oTaskChain:LastStringResultLen // Numeric (read-only)` | read-only | The length, in characters, of the string contained in the LastStringResult property. |
| `VerboseLogging` | `oTaskChain:VerboseLogging // Numeric` | read/write | If set to `1`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `oTaskChain:Version // Character (read-only)` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `Finished` | property, read-only | `oTaskChain:Finished // Numeric (read-only)` |
| `Inert` | property, read-only | `oTaskChain:Inert // Numeric (read-only)` |
| `Live` | property, read-only | `oTaskChain:Live // Numeric (read-only)` |
| `NumTasks` | property, read-only | `oTaskChain:NumTasks // Numeric (read-only)` |
| `Status` | property, read-only | `oTaskChain:Status // Character (read-only)` |
| `StatusInt` | property, read-only | `oTaskChain:StatusInt // Numeric (read-only)` |
| `StopOnFailedTask` | property, read/write | `oTaskChain:StopOnFailedTask // Numeric` |
| `Append` | method | `nSuccess := oTaskChain:Append(oTask) // returns Numeric (1/0)` |
| `Cancel` | method | `nSuccess := oTaskChain:Cancel() // returns Numeric (1/0)` |
| `GetTask` | method | `oTask := oTaskChain:GetTask(nIndex) // returns ChilkatTask` |
| `Run` | method | `nSuccess := oTaskChain:Run() // returns Numeric (1/0)` |
| `RunSynchronously` | method | `nSuccess := oTaskChain:RunSynchronously() // returns Numeric (1/0)` |
| `SleepMs` | method | `oTaskChain:SleepMs(nNumMs)` |
| `Wait` | method | `nSuccess := oTaskChain:Wait(nMaxWaitMs) // returns Numeric (1/0)` |

## Properties

### TaskChain.Finished

`Chilkat 11.7.0 · xbase · TaskChain · Finished · property · read-only · since 9.5.0.52`

```xbase
oTaskChain:Finished  // Numeric (read-only)
```

`1` if the task status is `canceled`, `aborted`, or `completed`. A task chain can only reach the `canceled` status if it was activated via the Run method, made it onto the internal thread pool thread's queue, was waiting for a pool thread to become available, and was then canceled prior to the task actually starting.

### TaskChain.Inert

`Chilkat 11.7.0 · xbase · TaskChain · Inert · property · read-only · since 9.5.0.52`

```xbase
oTaskChain:Inert  // Numeric (read-only)
```

`1` if the task status is `empty` or `loaded`. When a task chain is inert, it has been loaded but is not scheduled to run yet.

### TaskChain.Live

`Chilkat 11.7.0 · xbase · TaskChain · Live · property · read-only · since 9.5.0.52`

```xbase
oTaskChain:Live  // Numeric (read-only)
```

`1` if the task status is `queued` or `running`. When a task chain is live, it is either already running, or is on the thread pool thread's queue waiting for a thread to become available.

### TaskChain.NumTasks

`Chilkat 11.7.0 · xbase · TaskChain · NumTasks · property · read-only · since 9.5.0.52`

```xbase
oTaskChain:NumTasks  // Numeric (read-only)
```

The number of tasks contained within the task chain.

### TaskChain.Status

`Chilkat 11.7.0 · xbase · TaskChain · Status · property · read-only · since 9.5.0.52`

```xbase
oTaskChain:Status  // Character (read-only)
```

The current status of the task chain. Possible values are:

- `empty` -- No tasks have yet been appended to the task chain.
- `loaded` -- The task chain has been loaded (appended) with one or more task objects.
- `queued` -- The task chain is in the thread pool's queue of tasks awaiting to be run.
- `running` -- The task chain is currently running.
- `canceled` -- The task chain was canceled before it entered the `running` state.
- `aborted` -- The task chain was canceled while it was in the running state.
- `completed` -- The task chain completed.

### TaskChain.StatusInt

`Chilkat 11.7.0 · xbase · TaskChain · StatusInt · property · read-only · since 9.5.0.52`

```xbase
oTaskChain:StatusInt  // Numeric (read-only)
```

The current status of the task as an integer value. Possible values are:

- **1** -- `empty` -- No tasks have yet been appended to the task chain.
- **2** -- `loaded` -- The task chain has been loaded (appended) with one or more task objects.
- **3** -- `queued` -- The task chain is in the thread pool's queue of tasks awaiting to be run.
- **4** -- `running` -- The task chain is currently running.
- **5** -- `canceled` -- The task chain was canceled before it entered the `running` state.
- **6** -- `aborted` -- The task chain was canceled while it was in the running state.
- **7** -- `completed` -- The task chain completed.

### TaskChain.StopOnFailedTask

`Chilkat 11.7.0 · xbase · TaskChain · StopOnFailedTask · property · read/write · since 9.5.0.52`

```xbase
oTaskChain:StopOnFailedTask  // Numeric
```

If `1` then stops execution of the task chain if any individual task fails. Task failure is defined by the standard LastMethodSuccess property. If `0`, then all of the tasks in the chain will be run even if some fail. The default value of this property is `1`.

## Methods

### TaskChain.Append

`Chilkat 11.7.0 · xbase · TaskChain · Append · method · since 9.5.0.52`

```xbase
nSuccess := oTaskChain:Append(oTask)  // returns Numeric (1/0)
```

Appends a task to the task chain. Can fail if the task is already part of another chain. (A task can only be part of a single chain.)

Returns 1 for success, 0 for failure.

### TaskChain.Cancel

`Chilkat 11.7.0 · xbase · TaskChain · Cancel · method · since 9.5.0.52`

```xbase
nSuccess := oTaskChain:Cancel()  // returns Numeric (1/0)
```

Cancels execution of the asynchronous task chain.

Returns 1 for success, 0 for failure.

### TaskChain.GetTask

`Chilkat 11.7.0 · xbase · TaskChain · GetTask · method · since 9.5.0.52`

```xbase
oTask := oTaskChain:GetTask(nIndex)  // returns ChilkatTask
```

Returns the Nth task in the chain. The 1st task is at index 0.

Returns `NIL` on failure

### TaskChain.Run

`Chilkat 11.7.0 · xbase · TaskChain · Run · method · since 9.5.0.52`

```xbase
nSuccess := oTaskChain:Run()  // returns Numeric (1/0)
```

Queues the task chain to run on the internal Chilkat thread pool. Each task in the chain will run, one after the other.

Returns 1 for success, 0 for failure.

### TaskChain.RunSynchronously

`Chilkat 11.7.0 · xbase · TaskChain · RunSynchronously · method · since 9.5.0.52`

```xbase
nSuccess := oTaskChain:RunSynchronously()  // returns Numeric (1/0)
```

Runs the task chain synchronously. Then this method returns after all the tasks in the chain have been run.

Returns 1 for success, 0 for failure.

### TaskChain.SleepMs

`Chilkat 11.7.0 · xbase · TaskChain · SleepMs · method · since 9.5.0.52`

```xbase
oTaskChain:SleepMs(nNumMs)
```

Convenience method to force the calling thread to sleep for a number of milliseconds.

### TaskChain.Wait

`Chilkat 11.7.0 · xbase · TaskChain · Wait · method · since 9.5.0.52`

```xbase
nSuccess := oTaskChain:Wait(nMaxWaitMs)  // returns Numeric (1/0)
```

Waits for the task chain to complete. Returns when all of the tasks in the chain have completed, or after `maxWaitMs` milliseconds have elapsed. (A `maxWaitMs` value of 0 is to wait indefinitely.) Returns (`0`) if the task chain has not yet been started by calling the Run method, or if the `maxWaitMs` expired. If the task chain completed, was already completed, was canceled, or aborted, then this method returns `1`.

Returns 1 for success, 0 for failure.

## Events and callbacks

This binding has no event callbacks.

## Related classes

[`Task`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/xbase/classes/Task.md)

