Tar Task
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.
| Append | Append files to the specified archive. |
| ArchiveFile | The name of the tar archive. |
| ExcludedFiles | A list of files to exclude. |
| IncludedFiles | Specifies which files the component should include when compressing. |
| LogFile | The file to write logging information to at runtime. |
| LogMode | What information gets logged during component execution. |
| Other | Defines a set of configuration settings to be used by the task. |
| RecurseSubdirectories | Whether or not to recurse into subdirectories. |
| RuntimeLicense | Specifies the component runtime license key. |
| UseBzip2Compression | Specifies whether or not to use bzip2 compression. |
| UseGzipCompression | Whether 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.
| ArchiveFile | The name of the tar archive. |
| ExcludedFiles | A list of files to exclude. |
| ExtractToPath | A base path to decompress to. |
| FileList | String denoting the name of the variable which contains the last file listing entries. |
| FileMask | Specifies which files the component should include when extracting. |
| LogFile | The file to write logging information to at runtime. |
| LogMode | What information gets logged during component execution. |
| Operation | The operation which will be executed by the Tar task. |
| Other | Defines a set of configuration settings to be used by the task. |
| OverwriteFiles | Whether or not to overwrite files. |
| RecurseSubdirectories | Whether or not to recurse into subdirectories. |
| RuntimeLicense | Specifies the component runtime license key. |
| UseBzip2Compression | Specifies whether or not to use bzip2 compression. |
| UseGzipCompression | Whether 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.
| ExtractFilesOnly | Whether to only extract the files contained within the archive. |
| ExtraNullBytes | Extra 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) CompressedDate | The last modified date of the file, as stored within the archive (it does not generally correspond to when the file was compressed). |
| (1) CompressedName | The entry name, as stored within the archive. |
| (2) CompressedSize | The size of the compressed data, as compressed within the archive. Headers, footers, etc., are not included in the size. |
| (3) DecompressedName | The name of the file in the archive, as stored on the file system, outside the archive. |
| (4) DecompressedSize | The size of the file, as decompressed outside 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:
| Verbose | The task will report all information regarding the transport. |
| Info | The task will report all major operations, as well as all warnings and errors. |
| Warning | The task will report any conditions that could result in unpredictable behavior as well as errors. |
| Error | The task will report all errors that prevent normal operations from completing. |
| Fatal | The 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.