Tar Task

Properties   Config Settings  

The Tar task implements a tar archive utility, compatible with the UNIX tar and untar utilities.

Remarks

The Tar task is used when compressing or decompressing data in the form of files. The task also implements gzip and bzip2 compression and can be used to create or decompress .tar.gz or tar.bz archives.

Tar Assembler Task

The Assembler takes a group of files as input which contains raw data, and generates a Tar archive file as output.

Tar Disassembler Task

The Disassembler takes a Tar file as input, and generates a group of decompressed files as output.

Assembler Property List


The following is the full list of the properties of the assembler task with short descriptions. Click on the links for further details.

AppendAppend files to the specified archive.
ArchiveFileThe name of the tar archive.
ExcludedFilesA list of files to exclude.
IncludedFilesSpecifies which files the component should include when compressing.
LogFileThe file to write logging information to at runtime.
LogModeWhat information gets logged during component execution.
OtherDefines a set of configuration settings to be used by the task.
RecurseSubdirectoriesWhether or not to recurse into subdirectories.
RuntimeLicenseSpecifies the component runtime license key.
UseBzip2CompressionSpecifies whether or not to use bzip2 compression.
UseGzipCompressionWhether or not to use gzip compression.

Disassembler Property List


The following is the full list of the properties of the disassembler task with short descriptions. Click on the links for further details.

ArchiveFileThe name of the tar archive.
ExcludedFilesA list of files to exclude.
ExtractToPathA base path to decompress to.
FileListString denoting the name of the variable which contains the last file listing entries.
FileMaskSpecifies which files the component should include when extracting.
LogFileThe file to write logging information to at runtime.
LogModeWhat information gets logged during component execution.
OperationThe operation which will be executed by the Tar task.
OtherDefines a set of configuration settings to be used by the task.
OverwriteFilesWhether or not to overwrite files.
RecurseSubdirectoriesWhether or not to recurse into subdirectories.
RuntimeLicenseSpecifies the component runtime license key.
UseBzip2CompressionSpecifies whether or not to use bzip2 compression.
UseGzipCompressionWhether or not to use gzip compression.

Config Settings


The following is a list of config settings for the task with short descriptions. Click on the links for further details.

ExtractFilesOnlyWhether to only extract the files contained within the archive.
ExtraNullBytesExtra null bytes to append to the end of the file.

Append Property (Tar Task)

Append files to the specified archive.

Data Type

Boolean

Default Value

false


Remarks

During compression, the files specified by the IncludedFiles property will be appended to the ArchiveFile.

This property is not available in the Disassembler/Decoder.

ArchiveFile Property (Tar Task)

The name of the tar archive.

Data Type

String

Default Value

""


Remarks

This property specifies the name of the archive to be read or written. This property is required when compressing or extracting files.

If scanning or extracting, the file specified by ArchiveFile will be opened for read. If the file does not exist, a trappable error will be generated.

During compression, the file named by ArchiveFile will be written; if a file of this name already exists, the file will be overwritten.

The filename may be specified with or without a path. Paths may be relative or absolute, and should be specified in the format native to the host operating system. The filename should be specified with the appropriate extension (such as "tar"); an extension will not automatically be appended by the task.

If the file cannot be read, or written, as appropriate, a trappable error will be generated.

ExcludedFiles Property (Tar Task)

A list of files to exclude.

Data Type

String

Default Value

""


Remarks

This property specifies files that should be excluded when compressing or extracting a file. When either compression or extraction occurs, each file will be compared to ExcludedFiles, and each file that matches will be excluded.

This property may be set to one or more file names. These file names may be specified with or without a path, and with or without wildcards. If a path is specified, files in the indicated extraction directory will be excluded. If no path is specified but wildcards are, matching files in all directories will be excluded. If a single file name without a path is specified, it must correspond exactly to the appropriate value of a valid file name.

Directories should end with a slash ("/" or "\", as appropriate.) If a directory is specified, all files and subdirectories in the specified directory will be excluded during extraction.

A pipe character ("|") should be used to separate multiple file or directory names.

If the property is set to the empty string, no files will be excluded.

ExtractToPath Property (Tar Task)

A base path to decompress to.

Data Type

String

Default Value

""


Remarks

Setting the ExtractToPath property affects the opExtract Operation. Setting this property to a nonempty string will cause all decompressed files to be written to the specified path. If pathnames are given in the values of decompressed names, they will be regarded as relative to ExtractToPath.

If the specified directory does not exist, it will be created when extraction is done.

ExtractToPath should always be specified in the format native to the host operating system, and with a trailing slash or backslash. If the path is specified otherwise, it will be immediately converted and stored in the converted format. For example, "/temp" would be immediately converted to "\temp\" on a Windows system.

This property is not available in the Assembler/Encoder.

FileList Property (Tar Task)

String denoting the name of the variable which contains the last file listing entries.

Data Type

String

Default Value

"<none>"


Remarks

This property denotes a variable name which contains the collection of file listings returned from the task when the Operation property has been set to opScan. The collection is made up of entries for each listing in the current archive, specified by the ArchiveFile property.

The variable is in the form of a datatable. The table's rows represent a file listing, and the columns represent a different property of the listing. The columns of the datatable are listed below:

(0) CompressedDateThe last modified date of the file, as stored within the archive (it does not generally correspond to when the file was compressed).
(1) CompressedNameThe entry name, as stored within the archive.
(2) CompressedSizeThe size of the compressed data, as compressed within the archive. Headers, footers, etc., are not included in the size.
(3) DecompressedNameThe name of the file in the archive, as stored on the file system, outside the archive.
(4) DecompressedSizeThe size of the file, as decompressed outside the archive.
NOTE: If this property is set to a valid ADO object when the Operation property is set to opExtract, the task will populate this table with a file listing of all the files matching the IncludedFiles in the archive.

This property is read-only.

This property is not available in the Assembler/Encoder.

FileMask Property (Tar Task)

Specifies which files the component should include when extracting.

Data Type

String

Default Value

"*"


Remarks

FileMask may be used when extracting to specify which files will be extracted from the ArchiveFile property.

The value should be a pipe ("|") -delimited sequence of one or more filenames. The filenames should be specified with paths if necessary, so that the files may be found on the local file system.

Filenames may include the wildcards '?', '*', and '< .. >'. '?' will match any single character, and '*' will match an arbitrary sequence of characters. '< .. >' may be used to match any of the characters inside, or a range, such as '<a-z>'.

During extraction, FileMask may be set to one or more filenames or directory names. Files may be specified with or without a path, and with or without wildcards.

Subdirectories will be recursed into if RecurseSubdirectories is set to true.

The ExcludedFiles may be used to limit the files to be extracted.

This property is not available in the Assembler/Encoder.

IncludedFiles Property (Tar Task)

Specifies which files the component should include when compressing.

Data Type

String

Default Value

""


Remarks

IncludedFiles may be used when compressing to specify the files to be compressed.

The value should be a pipe ("|") -delimited sequence of one or more filenames. The filenames should be specified with paths if necessary, so that the files may be found on the local file system.

Filenames may include the wildcards '?', '*', and '< .. >'. '?' will match any single character, and '*' will match an arbitrary sequence of characters. '< .. >' may be used to match any of the characters inside, or a range, such as '<a-z>'.

If wildcards are specified, the file system will be scanned and all files matching the specified mask will be added to the list of files to compress.

Subdirectories will be recursed into if RecurseSubdirectories is set to true.

The ExcludedFiles may be used to limit the files to be compressed.

This property may also be set to a macro with the variable name that contains the contents of the data to be compressed. The macro must start and end with the '%' character. The compressed filename will be the variable name. The following example shows how to specify a variable name:

Example

Control.IncludedFiles = "%User::MyVariable%"

This property is not available in the Disassembler/Decoder.

LogFile Property (Tar Task)

The file to write logging information to at runtime.

Data Type

String

Default Value

""


Remarks

To write logging information to a file instead of using the task's logging API, set this property to a valid file on disk.

When set, any logging information is appended to the specified file and not written to the task's logging API.

LogMode Property (Tar Task)

What information gets logged during component execution.

Data Type

Enumeration

Possible Values

Verbose (0)
Info (1)
Warning (2)
Error (3)
Fatal (4)


Default Value

3


Remarks

This property controls what information the task logs. The possible values have the following affect on the task's behavior:

VerboseThe task will report all information regarding the transport.
InfoThe task will report all major operations, as well as all warnings and errors.
WarningThe task will report any conditions that could result in unpredictable behavior as well as errors.
ErrorThe task will report all errors that prevent normal operations from completing.
FatalThe task will report only serious errors that cause the task to completely stop functioning.

Operation Property (Tar Task)

The operation which will be executed by the Tar task.

Data Type

Enumeration

Possible Values

Extract (0)
Scan (1)


Default Value

0


Remarks

There are two different operations that the Tar Disassemble task may perform. It may extract files, or perform a scan on the entire archive specified by ArchiveFile.

The default for this property is to extract files.

This property is not available in the Assembler/Encoder.

Other Property (Tar Task)

Defines a set of configuration settings to be used by the task.

Data Type

String

Default Value

""


Remarks

The task accepts one or more configuration settings. These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the task, access to these internal properties is provided through the Other property.

The Other property may be set to one or more configuration settings (name/value pairs). Set one setting per line. For example: configname1=value1 configname2=value2

OverwriteFiles Property (Tar Task)

Whether or not to overwrite files.

Data Type

Boolean

Default Value

true


Remarks

If this property is set to true, existing files will be overwritten when decompressing. When extracting, each file specified by the FileMask will be checked for existence. If a file exists, the files will be overwritten if OverwriteFiles is set to true.

This property is not available in the Assembler/Encoder.

RecurseSubdirectories Property (Tar Task)

Whether or not to recurse into subdirectories.

Data Type

Boolean

Default Value

true


Remarks

This property affects the behavior of the IncludedFiles and FileMask properties and the meaning of ExcludedFiles property. If this property is set to true, the IncludedFiles and FileMask properties will recurse into all subdirectories whenever it performs a search on the file system.

RuntimeLicense Property (Tar Task)

Specifies the component runtime license key.

Data Type

String

Default Value

""


Remarks

You can use the RuntimeLicense property to set the runtime key for the task license.

UseBzip2Compression Property (Tar Task)

Specifies whether or not to use bzip2 compression.

Data Type

Boolean

Default Value

false


Remarks

By default this value is false. If set to true, the task will use bzip2 compression when creating the archive. This is similar to the UseGzipCompression property in behavior.

UseGzipCompression Property (Tar Task)

Whether or not to use gzip compression.

Data Type

Boolean

Default Value

false


Remarks

If this property is set to true, the task will operate on tar archives that have been compressed with gzip. The interface of the task remains the same. During compression, the data will be streamed through a gzip compressor as it is written to the file. During decompression, the task will unzip the data to a temporary tar archive, and then automatically decompress the tar archive.

The creation of the temporary tar file will occur when the task is invoked.

The temporary file will automatically be deleted by the task after it is no longer needed. To extract the tar file itself (rather than its contents), the Gzip task should be used.

If this property is set to false, the task will create and read ordinary, uncompressed tar archives.

Config Settings (Tar Task)

The task accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the task, access to these internal properties is provided through the Other property.

Zip Config Settings

ExtractFilesOnly:   Whether to only extract the files contained within the archive.

If true, only the files contained within the ArchiveFile are extracted directly to the specified ExtractToPath. Folders contained within the ArchiveFile will not be created within the ExtractToPath.

ExtraNullBytes:   Extra null bytes to append to the end of the file.

If ExtraNullBytes is set to a nonzero value, the task will write the specified number of null bytes whenever it creates a tar file or appends to an existing one. Setting this property to 1024 (or higher) may be necessary to prevent compatibility problems with certain versions of untar.