What the Class Is Used For

Use Chilkat.UnixCompress when an application needs to create or read UNIX compressed .Z files. The class can compress files, byte arrays, and strings; decompress .Z content back to files, byte arrays, or strings; and unpack .tar.Z archives without temporary files.

Compress to .Z Create UNIX compressed .Z files from files, memory, or strings.

Decompress .Z Restore original data from .Z files or in-memory .Z images.

Handle Text Encodings Compress and decompress strings using a specified character encoding.

Unpack .tar.Z Decompress and untar .tar.Z archives in streaming mode.

Important Format Note

UNIX .Z format: This class works with UNIX compressed files using the LZW (Lempel-Ziv-Welch) compression algorithm. The memory compression methods return an in-memory image of a .Z file, not just a raw application buffer.

Typical Workflow: Compress a File

Create a UnixCompress object.
Optionally set HeartbeatMs if the operation may be long-running and the application needs abort callbacks.
Call CompressFile with the input file path and the destination .Z file path.
Check the boolean return value.
If compression fails, inspect LastErrorText.

Typical Workflow: Decompress a File

Create a UnixCompress object.
Provide the path to the existing .Z file.
Call UncompressFile with the input .Z file path and the destination output file path.
Check the boolean return value.
If decompression fails, inspect LastErrorText.

Core Concepts

Concept	Meaning	Important Members
UNIX Compression	Creates .Z compressed content using the LZW compression algorithm.	CompressFile, CompressMemory, CompressString
UNIX Decompression	Restores original content from a .Z file or in-memory .Z image.	UncompressFile, UncompressMemory, UncompressString
String Encoding	Strings are converted to or from bytes using a specified charset.	CompressString, CompressStringToFile, UncompressString, UncompressFileToString
.tar.Z Archives	A tar archive compressed with UNIX compress.	UnTarZ
File Helpers	Convenience methods for reading and writing complete files as byte arrays.	ReadFile, WriteFile
Abort Support	Allows long-running operations to be cancelled.	AbortCurrent, HeartbeatMs

Properties

Property	Purpose	Guidance
AbortCurrent	Causes the currently running method to abort when set to true.	Useful for longer file operations. Both synchronous and asynchronous calls can be aborted. If no method is running, the property is automatically reset when the next method is called; after an abort occurs, it is reset to false.
HeartbeatMs	Interval in milliseconds between AbortCheck event callbacks.	Default is 0, meaning no AbortCheck callbacks are triggered. Set to a positive value when an application needs periodic opportunities to abort.
LastErrorText	Diagnostic information for the last method or property access.	Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Compression Methods

Method	Input	Output	Use When
CompressFile	File path	.Z file path	Compress a file directly to a UNIX compressed file.
CompressFileToMem	File path	Byte array containing a .Z file image	Compress a file and keep the compressed result in memory.
CompressMemory	Byte array	Byte array containing a .Z file image	Compress in-memory bytes to in-memory compressed bytes.
CompressMemToFile	Byte array	.Z file path	Compress in-memory bytes and write a .Z file.
CompressString	String plus charset	Byte array containing a .Z file image	Convert text to bytes using the specified charset, then compress to memory.
CompressStringToFile	String plus charset	.Z file path	Convert text to bytes using the specified charset, then compress to a file.

Decompression Methods

Method	Input	Output	Use When
UncompressFile	.Z file path	Destination file path	Decompress a .Z file directly to a file.
UncompressFileToMem	.Z file path	Byte array containing original uncompressed data	Decompress a file and keep the restored data in memory.
UncompressMemory	Byte array containing a .Z file image	Byte array containing original uncompressed data	Decompress in-memory .Z content to memory.
UncompressMemToFile	Byte array containing a .Z file image	Destination file path	Decompress in-memory .Z content to a file.
UncompressString	Byte array containing a .Z file image plus charset	String	Decompress to bytes, then interpret those bytes as text using the specified charset.
UncompressFileToString	.Z file path plus charset	String	Decompress a text file stored in .Z format and return the text.

Input and Output Patterns

Workflow	Compression Method	Decompression Method
File to file	CompressFile	UncompressFile
File to memory	CompressFileToMem	UncompressFileToMem
Memory to memory	CompressMemory	UncompressMemory
Memory to file	CompressMemToFile	UncompressMemToFile
String to memory	CompressString	UncompressString
String to file / file to string	CompressStringToFile	UncompressFileToString

String and Charset Handling

Method	Charset Role	Examples
CompressString CompressStringToFile	The input string is first converted to bytes using the specified charset, and those bytes are then compressed.	utf-8, iso-8859-1, Windows-1252, ucs-2
UncompressString UncompressFileToString	Decompressed bytes are interpreted as text using the specified charset.	utf-8, iso-8859-1, windows-1252, shift_JIS, big5

Encoding matters: For text workflows, use the charset that matches the original text bytes. The wrong charset can produce incorrect characters after decompression.

.tar.Z Archive Support

Method	Purpose	Important Details
UnTarZ	Unpacks a .tar.Z file.	Decompression and untar occur in streaming mode. No temporary files are created, and the memory footprint remains constant and small while untarring. The bNoAbsolute argument controls absolute path handling during extraction.

Efficient extraction: UnTarZ streams both decompression and tar extraction, which avoids temporary intermediate files.

File Helper Methods

Method	Purpose	Use When
ReadFile	Reads an entire file and returns its contents as a byte array.	Use when a file should be loaded into memory before compression or other processing.
WriteFile	Writes the contents of a byte array to a file.	Use when decompressed or generated bytes should be saved to disk.

Abort and Heartbeat Behavior

Member	Behavior	Use When
AbortCurrent	When set to true, causes the currently running operation to abort. Both synchronous and asynchronous method calls can be aborted.	Use from another thread or event callback when a long-running operation should stop.
HeartbeatMs	Sets the interval between AbortCheck event callbacks.	Use when an application wants periodic opportunities to cancel a long-running operation.

Quick methods: Methods that always finish quickly are not affected by AbortCurrent.

Async Result Support

Method	Purpose	Use When
LoadTaskCaller	Loads the caller of the task’s async method.	Use in asynchronous workflows after a task completes and the original caller object needs to be loaded.

Method Summary by Category

Category	Methods / Properties	Purpose
Compress files and memory	CompressFile, CompressFileToMem, CompressMemory, CompressMemToFile	Create .Z content from files or byte arrays.
Compress strings	CompressString, CompressStringToFile	Convert text to bytes using a charset and compress to memory or file.
Decompress files and memory	UncompressFile, UncompressFileToMem, UncompressMemory, UncompressMemToFile	Restore bytes from .Z files or in-memory .Z images.
Decompress strings	UncompressString, UncompressFileToString	Restore text by interpreting decompressed bytes using a specified charset.
Unpack archives	UnTarZ	Stream-decompress and untar .tar.Z archives.
File helpers	ReadFile, WriteFile	Read or write complete files as byte arrays.
Abort control	AbortCurrent, HeartbeatMs	Provide cancellation support for longer-running operations.
Async workflow	LoadTaskCaller	Load the original caller from a completed async task.
Diagnostics	LastErrorText	Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
File compression fails	CompressFile, LastErrorText	Confirm the input file exists, the destination path is writable, and inspect diagnostics for file access or compression details.
Memory decompression fails	UncompressMemory	Confirm the input byte array contains an in-memory image of a .Z file.
String output has incorrect characters	UncompressString, UncompressFileToString	Verify that the specified charset matches the encoding of the original text file.
.tar.Z extraction fails	UnTarZ	Confirm the input is a valid .tar.Z archive and that the destination directory can be written.
Abort is not occurring	AbortCurrent, HeartbeatMs	Confirm the operation is long-running enough to be abortable and that heartbeat callbacks are configured when needed.
Need operation details after failure	LastErrorText	Check diagnostic text after failed or unexpected compression, decompression, archive extraction, file helper, async, or abort behavior.

Common Pitfalls

Pitfall	Better Approach
Confusing .Z with ZIP, gzip, or bzip2 formats.	Use this class for UNIX compress .Z content using LZW compression.
Passing ordinary uncompressed bytes to UncompressMemory.	Pass bytes that contain an in-memory image of a .Z file.
Using the wrong charset when compressing or decompressing strings.	Use the charset that matches the intended byte representation of the text.
Expecting UnTarZ to create temporary intermediate files.	UnTarZ performs decompression and untar in streaming mode without temporary files.
Expecting very quick operations to be affected by AbortCurrent.	AbortCurrent applies to operations that can run long enough to be aborted.
Ignoring diagnostics after failed compression or decompression.	Check LastErrorText for details.

Best Practices

Recommendation	Reason
Choose the method that matches the source and destination.	The class provides file, memory, and string variants for both compression and decompression.
Use string methods only when the compressed data represents text.	String methods require a charset to convert between bytes and text.
Use byte-array methods for binary content.	Binary data should usually be compressed and decompressed without character encoding conversion.
Use UnTarZ for .tar.Z archives.	It streams decompression and tar extraction without temporary files and with a small constant memory footprint.
Set HeartbeatMs for long-running operations that may need cancellation.	It enables periodic abort checks.
Check LastErrorText after failures.	It provides useful diagnostic detail for failed or unexpected compression, decompression, archive extraction, and file operations.

Summary

Chilkat.UnixCompress is the Chilkat class for UNIX compress format. It creates and reads .Z files using LZW compression, supports file, memory, and string workflows, provides helper methods for reading and writing raw files, and can unpack .tar.Z archives in streaming mode.

The most important practical guidance is to use this class specifically for .Z content, choose file, memory, or string methods based on the data source and destination, specify the correct charset for text workflows, use UnTarZ for .tar.Z archives, and inspect LastErrorText whenever an operation fails.

Chilkat.UnixCompress Class Overview