File utilities plug-in task reference

Edit online

The File Utilities tasks have arguments that you can specify.

Convert encoding

The Convert Encoding task changes the encoding of a text file. The result can be stored in a new file, or the source file can be overwritten.

Table 1. Task arguments for the Convert Encoding task
Argument Description
Source file Name of the source file to be re-encoded.
Source encoding The encoding of the source file.

The default value is Auto detect.
Target file Name of the target file to store the encoding in. Leave empty to overwrite the source file with the result.
Target encoding The encoding to use.

The default value is Unicode.

Checksum

The Checksum task calculates the checksum of a column in a file with the option of filtering out rows that are based on the content of another column.

Table 2. Task arguments for the Checksum task
Argument Description
File name Name of the file to calculate the checksum for.
Delimiter The delimiter that separates columns.

The default value is Comma ','
Column The column number to sum. The first column is number 1.

The default value is 1.
Column width The width of the column to select. Only used when the delimiter is fixed width.

The default value is 0.
Filter type The type of filter to apply. Leave as None to have no filter.

The default value is None
Filter column The column number to filter on. The first column is number 1.
Filter column width The width of the filter column to select. Only used when the delimiter is fixed width.

The default value is 0.
Filter expression A regular expression for the filter to match.
Filter expression syntax The syntax for the filter expression. It is one of
  • Exact finds exact matches.
  • Glob uses the ? wildcard to specify any character and * to specify a sequence of characters.
  • Regular expression uses standard regular expression syntax for finding matches.

The default value is Regular expression.
Ignore case If true, filter matching is case-insensitive.

The default value is True.

Copy

The Copy task copies files or directories on the server.

Table 3. Task arguments for the Copy task
Argument Description
Source The name of the files and directories to copy. Use the wildcard characters * and ? to specify multiple files or directories.
Destination The destination file or directory. When you copy multiple files, only a directory is allowed.
Overwrite If checked, overwrite existing files. If cleared, the task exits without overwriting existing files.

The default value is cleared.

Delete

The Delete task deletes files or directories.

Table 4. Task arguments for the Delete task
Argument Description
File name Name of the files and directories to delete. Use the wildcard characters * and ? to match multiple files or directories.
Recursive If checked, delete directories and their contents recursively. If cleared, the task fails to delete a non-empty directory.

The default value is cleared.
Force Force the deletion of the files. This option is similar to the "-f" option of the UNIX "rm" command.

The default value is cleared.

Delete directory

The Delete Directory task deletes empty directories.

Table 5. Task argument for the Delete Directory task
Argument Description
Path Name of the directories to delete. Use the wildcard characters * and ? to match multiple directories.

Delete less days

The Delete Less Days task deletes files in directories that have not been modified in the last n days.

Table 6. Task arguments for the Delete Less Days task
Argument Description
Path The path to delete. Wildcards are allowed.
Days Files that have not been modified within this number of days are deleted.
Recursive If checked, delete directories and their contents recursively. If cleared, the task fails to delete a non-empty directory.

The default value is cleared.
Force Force the deletion of the files. This option is similar to the "-f" option of the UNIX "rm" command.

Detect Unicode

The Detect Unicode task determines whether a file is using one of the Unicode encodings. Here is the list of Unicode encodings:
  • UTF-7
  • UTF-8
  • UTF-16
  • UTF-32

The task succeeds if the file is encoded in Unicode. Otherwise, the task returns the error Not Unicode.

Table 7. Task argument for the Detect Unicode task
Argument Description
File name Name of the file to determine the encoding of.

Extract List

The Extract List task extracts a list of values from a column-based file and optionally filters the result that is based on values in a filter column. The file can either have variable length columns that are delimited with a single character delimiter, or have fixed-length columns.

By capturing the output from this task in an extract list post task action, it is possible to iterate over this list when you run a subsequent Iterate over list task in Cognos® Command Center.

Table 8. Task arguments for the Extract List task
Argument Description
File name The name of the file to extract a list from.
Delimiter The column delimiter.

The default value is Tab.
Column The column to sum. The first column is numbered 1.

The default value is 1.
Column width The width of the column to select. Only used when the delimiter is fixed width.

The default value is 0.
Filter type Optional filter that specifies what rows to include or exclude from the sum.

The default value is None.
Filter column Optional filter column. First column is numbered 1. The value is ignored if the filter type is None.

The default value is 1.
Filter column width The width of the filter column to select. Only used when the delimiter is fixed width.

The default value is 0.
Filter expression Optional filter expression. Rows are included or excluded from the list that is based on a match with this expression.
Filter expression syntax The syntax for the filter expression. It is one of
  • Exact finds exact matches.
  • Glob uses the ? wildcard to specify any character and * to specify a sequence of characters.
  • Regular expression uses standard regular expression syntax for finding matches.

The default value is Regular expression.
Suppress duplicates If true, duplicate elements are removed from the list.

The default value is False.
Sort mode Specifies how the extracted list elements are sorted.

The default value is No sorting.
Ignore case If true, filter matching and record sorting are case-insensitive.

Filter by time

The Filter by Time task scans log files that are based on a time stamp. The task receives a time stamp and information about how to identify time stamps on each log line. It then skips lines from the file until it meets a line with a date that is later or equal to the supplied time stamp. This line and all remaining lines are then copied into a destination file, creating a log snippet that can then be further inspected for error messages.

Table 9. Task arguments for the Filter by Time task
Argument Description
Input file The name of the file to scan.
Output file The name of the output file.
Allow overwrite If true, an existing output file is overwritten.

The default value is False.
Time This parameter is the cutoff time and only files that follow the first line with a date that is later or equal to this time are included in the output.
The time parameter can be given in one of the following formats:
  • MM/dd/yyyy hh:mm:ss tt. For example 5/23/2012 02:23:0 AM
  • MM/dd/yyyy hh:mm tt. For example 5/23/2012 02:23 AM
  • MM/dd/yyyy HH:mm:ss. For example 5/23/2012 14:23:00
  • MM/dd/yyyy HH:mm. For example 5/23/2012 14:23

For more information about these formats, see the description of the Timestamp format argument.

Typically, the $(Date) system variable is used. For example, $(Date{MM/dd/yy HH:mm})

The default value is $(Process [last].Start {MM/dd/yy HH:mm}).
Prefix expression An optional regular expression (using the standard Java™ regular expression syntax) for the string preceding the time stamp on each log line.
Prefix expression syntax The syntax for the prefix expression. It is one of
  • Exact finds exact matches.
  • Glob uses the ? wildcard to specify any character and * to specify a sequence of characters.
  • Regular expression uses standard regular expression syntax for finding matches.

The default value is Regular expression.
Ignore case If false, ignores the case of characters when you search for the prefix pattern.

The default value is True.
Timestamp format The format of the time stamp on the log lines. The format is specified by using a date and time pattern string.
  • y - Year (2 or 4 digits).
  • M - Month in year (1-12).
  • MM - Month in year (01-12).
  • MMM - Abbreviated month in year (Jan-Dec).
  • MMMM - Month in year (January-December).
  • d - Day in month (1-31).
  • dd - Day in month (01-31).
  • ddd - Abbreviated day in month (Mon-Sun).
  • dddd - Day in month (Monday-Sunday).
  • tt - AM/PM marker (AM, PM).
  • H - 24 hour clock (0-23).
  • HH - 24 hour clock (00-23).
  • h - 12 hour clock (1-12).
  • hh - 12 hour clock (01-12).
  • m - Minute in hour (1-59).
  • mm - Minute in hour (01-59).
  • s - Second in minute (1-59).
  • ss - Second in minute (01-59).
  • zzz - Minutes and seconds offset from GMT (- 07:00).
  • K - Time zone information (PST).

The format is a combination of pattern characters and separators like / - : . and space. For example, ddd MMM dd HH:mm:ss yyyy matches Mon Sep 7 04:45:12 2012.
Timestamp offset An optional time zone offset that can be added to the time stamps before comparison with the supplied time. This is useful if the time stamps in the file are in a local time without any time zone information.

The default value is 0.
Context length The number of lines that precede the first matching line that are to be included in the output.

For example, assume that the first matching line is the <time> element.

<log>
	<severity>debug</severity>
	<time>2012-07-21 23:12:01</time>
	<message>Processed 'backup.scr'</message>
</log>

In this case, setting the context length to 2 causes the <log> and <severity> elements to be included in the output.

The default value is 0.

Find

The Find task searches for a text string in a file or in a set of files.

Table 10. Task arguments for the Find task
Argument Description
Files Specifies the file or set of files to search.
Pattern The text string to find.
Pattern syntax The syntax for the pattern.
  • Exact finds exact matches.
  • Glob uses the ? wildcard to specify any character and * to specify a sequence of characters.
  • Regex uses standard regular expression syntax for finding matches.

The default value is Exact.
Case sensitive If false, ignores the case of characters when you search for the pattern.

The default value is False.
Output format Sets the output format. Brief outputs the number of occurrences. Verbose outputs the matching lines.

List directory

The List Directory task lists the content of a directory on the server.

Table 11. Task arguments for the List Directory task
Argument Description
Directory The directory for which to list the contents.
Output format Format of the task output.
  • Full includes header and summary information.
  • Brief outputs only the matching file or directory names.

The default value is Full.

List file content

The List File Content task lists the contents of a file.

Table 12. Task argument for the List File Content task
Argument Description
Computing resource The host computing resource.
File name The file to list the contents of.

Make directory

The Make Directory task creates a directory on the server.

Table 13. Task argument for the Make Directory task
Argument Description
Directory The name of the directory to create.

Move

The Move task moves files and directories on the server.

Table 14. Task arguments for the Move task
Argument Description
Source Name of the files or directories to move. Use the wildcard characters * and ? to match multiple files or directories.
Destination The new location of the files or directories. When you move multiple items, the destination must be a directory on the server.
Overwrite If checked, overwrite existing files. When cleared, the task exits without overwriting existing files.

The default value is cleared.

Move less days

The Move less days task moves files or directories that have not been modified in the last n days.

Table 15. Task arguments for the Move less days task
Argument Description
Source Name of the files or directories to move. Use the wildcard characters * and ? to match multiple files or directories.
Destination The new location of the files or directories. When you move multiple items, the destination must be a directory on the server where the agent is installed.
Overwrite If checked, overwrite existing files. When cleared, the task exits without overwriting existing files.

The default value is cleared.
Days Files that have not been modified within this number of days are moved.

Replace

The Replace task searches for and replaces text in a file.

The result of the search and replace operation is either written to a new destination file, or the task can perform an in-file replacement that overwrites the source file with the result.

You can search for and replace text in multiple files within a single task by using wildcards. In this case, the task supports only in-file replacement, and the destination file argument must be left empty.

Table 16. Task arguments for the Replace task
Argument Description
Source The name of the file to search. Use wildcards to specify multiple files.
Destination The name of the destination file. The task fails if the file exists.

Leave empty to perform an in-file replacement, overwriting the source file.
Allow overwrite If true, an existing destination file is overwritten.

The default value is False.
Find The text string to find.
Replace The text string to insert at the matching locations.
Find syntax The syntax for the find pattern.
  • Exact finds exact matches.
  • Glob uses the ? wildcard to specify any character and * to specify a sequence of characters.
  • Regex uses standard regular expression syntax for finding matches.

The default value is Exact.
Case sensitive If false, ignores the case of characters when you search for the pattern.

The default value is False.

Tar

The Tar task creates a tar archive.

Table 17. Task arguments for the Tar task
Argument Description
Output archive Name of the archive to create. If necessary, a ".tar" extension is added to the name.
Source files Name of files or directories to add to the tar archive. Use semicolons or wildcards to specify multiple files or directories.
Overwrite If true, an existing archive is overwritten by this task.

The default value is False.

Unzip

The Unzip task extracts a .zip or .gzip archive.

Table 18. Task arguments for the Unzip task
Argument Description
Archive The name of the archive to extract.
Destination directory The name of the directory to extract the archive to. The directory is created if it does not exist.
Compression The compression format for the archive.
  • Auto detect determines the compression format that is based on the extension.
  • Gzip forces the format to .gzip regardless of the file extension.
  • Zip forces the format to .zip regardless of the file extension.

The default value is Auto detect.
Overwrite If true, existing files are overwritten when you extract the archive.

The default value is False.

Untar

The Untar task extracts a tar archive.

Table 19. Task arguments for the Untar task
Argument Description
Archive The name of the tar archive to extract.
Destination directory The name of the directory to extract the archive to. The directory is created if it does not exist.
Overwrite If true, existing files are overwritten when you extract the archive.

The default value is False.

Zip

The Zip task creates an archive. The compression format is derived from the extension of the output archive.

Table 20. Task arguments for the Zip task
Argument Description
Output archive The name of the archive to create. The archive format is derived from the file extension.
  • gzip, .gz creates a .gzip archive.
  • .zip,.z creates a .zip archive.
  • .tgz creates a gzipped tar archive.
Source files The name of files or directories to add to the .zip file. Use semicolons or wildcards to specify multiple files or directories.
Overwrite If true, an existing archive is overwritten by this task.

The default value is False.