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

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

## Purpose

`Chilkat.Bz2` provides BZip2 compression and decompression for files, memory buffers, and BinData. It can create standard .bz2 file images, decompress .bz2 content back to its original bytes, and support abortable long-running operations.

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

## Object creation, unlocking and error handling

**Object Creation**

```xbase
LOCAL oBz2
oBz2 := CreateObject("Chilkat.Bz2")

// ... use oBz2 ...

oBz2: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.Bz2.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` | `oBz2: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` | `oBz2:LastErrorHtml // Character (read-only)` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `oBz2:LastErrorText // Character (read-only)` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `oBz2:LastErrorXml // Character (read-only)` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `oBz2:LastMethodSuccess // Numeric` | read/write | Indicates the success or failure of the most recent method call: `1` means success, `0` means failure. |
| `LastStringResult` | `oBz2: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` | `oBz2:LastStringResultLen // Numeric (read-only)` | read-only | The length, in characters, of the string contained in the LastStringResult property. |
| `VerboseLogging` | `oBz2:VerboseLogging // Numeric` | read/write | If set to `1`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `oBz2:Version // Character (read-only)` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `AbortCurrent` | property, read/write | `oBz2:AbortCurrent // Numeric` |
| `CompressBd` | method | `nSuccess := oBz2:CompressBd(oBd) // returns Numeric (1/0)` |
| `CompressFile` | method | `nSuccess := oBz2:CompressFile(cInFilename, cToPath) // returns Numeric (1/0)` |
| `LoadTaskCaller` | method | `nSuccess := oBz2:LoadTaskCaller(oTask) // returns Numeric (1/0)` |
| `UncompressBd` | method | `nSuccess := oBz2:UncompressBd(oBd) // returns Numeric (1/0)` |
| `UncompressFile` | method | `nSuccess := oBz2:UncompressFile(cInFilename, cToPath) // returns Numeric (1/0)` |

## Properties

### Bz2.AbortCurrent

`Chilkat 11.7.0 · xbase · Bz2 · AbortCurrent · property · read/write · since 9.5.0.58`

```xbase
oBz2:AbortCurrent  // Numeric
```

Set this property to `1` to request cancellation of the compression or decompression operation currently executing on this object. Long-running operations check the request periodically; an operation that finishes quickly may complete before the request is observed.

A synchronous call can be cancelled by setting this property from another thread. After cancellation is processed, Chilkat resets the property to `0`. If no operation is running, a previously set value is cleared when the next method begins.

**Cancellation is cooperative:** Setting this property requests an abort; it does not guarantee immediate termination. Check the method's return value and `LastErrorText` to determine the final outcome.

## Methods

### Bz2.CompressBd

`Chilkat 11.7.0 · xbase · Bz2 · CompressBd · method · since 11.0.0`

```xbase
nSuccess := oBz2:CompressBd(oBd)  // returns Numeric (1/0)
```

Compresses the current contents of `bd` in place. On success, the `BinData` no longer contains the original bytes; it contains the complete standard BZip2 stream that may be saved with a `.bz2` extension.

**In-place transformation:** Preserve a copy of the original data if it is still needed after this call. A BZip2 stream contains a stream header, one or more compressed blocks with integrity checks, and an end-of-stream marker. It does not contain archive filenames or directory entries.

Returns 1 for success, 0 for failure.

Async variant: `CompressBdAsync` — same arguments, returns a `Task` (see Async variants below).

### Bz2.CompressFile

`Chilkat 11.7.0 · xbase · Bz2 · CompressFile · method`

```xbase
nSuccess := oBz2:CompressFile(cInFilename, cToPath)  // returns Numeric (1/0)
```

Reads the file at `inFilename` and writes its compressed bytes as a standard BZip2 stream to the file at `toPath`. The output is conventionally given a `.bz2` extension.

Both arguments must identify files, not directories. They may be absolute or relative paths, for example `data/report.txt` and `data/report.txt.bz2`.

**BZip2 is a compressor, not an archive format:** A `.bz2` file represents one compressed byte stream. It does not store the original filename, directory path, timestamps, permissions, or multiple archive entries. Formats such as `.tar.bz2` first combine files in a TAR archive and then compress that TAR stream with BZip2.

Returns 1 for success, 0 for failure.

Async variant: `CompressFileAsync` — same arguments, returns a `Task` (see Async variants below).

### Bz2.LoadTaskCaller

`Chilkat 11.7.0 · xbase · Bz2 · LoadTaskCaller · method · since 9.5.0.80`

```xbase
nSuccess := oBz2:LoadTaskCaller(oTask)  // returns Numeric (1/0)
```

Loads this `Bz2` object with the caller state associated with the asynchronous operation represented by `task`.

**Advanced async infrastructure:** This method is used to recover the original caller object associated with a completed task. It is not normally needed by application code. Pass a `Task` created by a compatible `Bz2` asynchronous method; an unrelated task cannot be loaded.

Returns 1 for success, 0 for failure.

### Bz2.UncompressBd

`Chilkat 11.7.0 · xbase · Bz2 · UncompressBd · method · since 11.0.0`

```xbase
nSuccess := oBz2:UncompressBd(oBd)  // returns Numeric (1/0)
```

Decompresses the BZip2 stream currently contained in `bd` in place. On success, the `BinData` is replaced with the original uncompressed bytes.

**Input requirement:** `bd` must contain a complete, valid BZip2 stream, such as the bytes of a `.bz2` file or the output of `CompressBd`. This method operates on binary data and does not perform character-set conversion.

Returns 1 for success, 0 for failure.

Async variant: `UncompressBdAsync` — same arguments, returns a `Task` (see Async variants below).

### Bz2.UncompressFile

`Chilkat 11.7.0 · xbase · Bz2 · UncompressFile · method`

```xbase
nSuccess := oBz2:UncompressFile(cInFilename, cToPath)  // returns Numeric (1/0)
```

Reads the BZip2 stream from the file at `inFilename`, decompresses it, and writes the original uncompressed bytes to the file at `toPath`.

Both arguments must identify files, not directories. Chilkat does not derive the destination name from the `.bz2` filename because the BZip2 stream does not contain the original filename.

**Terminology:** This method decompresses BZip2 data; it does not “unzip” a ZIP archive. A `.bz2` file normally contains a single compressed byte stream rather than a collection of named files.

Returns 1 for success, 0 for failure.

Async variant: `UncompressFileAsync` — same arguments, returns a `Task` (see Async variants below).

## Events and callbacks

This binding has no event callbacks. For progress, percent-done or cancellation use the `*Async` variant of a method and poll the returned `Task` (`PercentDone`, `Finished`, `Cancel`).

## Async variants

Each returns a `Task` instead of the result and takes the same arguments as the synchronous method; run the task, wait for `Finished`, then read the result from the task. No new Async methods are added from 11.7.0 on.

```xbase
oTask := oBz2:CompressBdAsync(oBd)  // returns ChilkatTask
oTask := oBz2:CompressFileAsync(cInFilename, cToPath)  // returns ChilkatTask
oTask := oBz2:UncompressBdAsync(oBd)  // returns ChilkatTask
oTask := oBz2:UncompressFileAsync(cInFilename, cToPath)  // returns ChilkatTask
```

## Related classes

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

