Filemonitor

Use the filemonitor utility to check for file changes (files that were either created or modified). This could be useful when, for example, you want to make sure that a file exists before running a job that processes that file. By defining a job that runs the filemonitor utility, you can implement file dependency, that is, a relationship between a file and an operation in which specific activity on the file determines the start of the operation.

You can use the filemonitor utility as a stand-alone command, or you can set the filemonitor keywords as additional parameters for the start condition of a job stream, either in the Workload Designer or from the composer command line. For more information about the start condition, see Condition-based workload automation.

Run the filemonitor utility to monitor whether the specified files have been modified within a time interval. All product components must be at least at the Version 9.4, Fix Pack 1 level.

Syntax

filemonitor -V | -U

filemonitor {-path path_to_monitor | -epath path_to_monitor}
[-exitOnPathToMonitorNotFound]
-event {fileCreated | fileModified} [-modificationCompletedTime seconds]
[-repositoryName repository_name]
[-repositoryPath repository_path]
[-recursive]
[-outputFile output_filename]
[-scanInterval scan_interval]
[-maxEventsThreshold max_events]
[-minFileSize min_file_size]
[-timeout seconds | time_of_the_day]
[-preserveEventsOnDelete]

filemonitor -reset
[-repositoryName repository_name]
[-repositoryPath repository_path - generateEventsOnFirstScan]

Arguments

Note: If you set the same argument more than once, the last value specified is applied and no error message is reported.
-V
Displays the command version and exits.
-U
Displays command usage information and exits.
-path path_to_monitor

The path where the files to be processed are located. You can specify blank or special characters within double quotation marks. Wildcard characters are supported. To include more files in the monitoring process, store the files in a specific directory and specify the directory with the -path option.

The following syntax rules apply:
  • Paths containing blank or special characters must be specified within double quotation marks.
  • Wildcard characters question mark (?) and asterisk (*) are supported.
Universal Naming Convention (UNC) paths are also supported with the following syntax types:
  • \\server_name\share_name\directory_name\...
  • \\?\UNC\server_name\share_name\directory_name
  • \\?\path_name
where the question mark (? ) indicates extended-length paths.
-epath path_to_monitor
The path where the files to be processed are located, specified with slashes (/) as separators. Backslashes (\) are not allowed as separators, even if you are indicating a Windows path. To include more files in the monitoring process, store all the files in the directory set with the -epath argument.
The following syntax rules apply:
  • Paths containing blank or special characters must be specified within double quotation marks.
  • Supported wildcard characters: question mark (?) and asterisk (*).
  • Any character other than backslash (\), question mark (?), asterisk (*), square brackets ([ ]) or a backslash at the end of the value (\) is intended exactly as it is written. For example, MYpath is not equivalent to mypath.
  • Use the syntax [class description] to indicate a single character as follows:
    [range_of_characters]
    A range of characters separated by a minus sign (-). For example, A-B or 1-9.
    [list_of_characters]
    A string of characters. For example, ABC or 1aX.
  • The characters exclamation mark (!) and caret (^) are used to reverse the sense. For example, [!A-Z] matches a single character that is not equivalent to any letter from A to Z. [!F] matches any character that is not F.
For example:
  • -epath /mypath/myp?th/e[!1].txt
  • -epath /mypath/my[1-9]path/e[A-Z].txt
  • -epath c:/mypath/p?th/e[!1].txt
[-exitOnPathToMonitorNotFound]
Optionally, specify this argument to have the command exit if the specified path is not found.
-event {fileCreated | fileModified} [-modificationCompletedTime seconds]
The event type to be monitored. Supported types are fileCreated and fileModified. This argument is required when you specify -path. If you specify the fileCreated or the fileModified argument, you can optionally specify the -modificationCompletedTime option which is a time interval, in seconds that is used to determine when the event is sent.
-event fileCreated
As soon as the file is created , the event, FileCreated, is sent.
-event fileModified
As soon as the file is modified, the event, ModificationCompleted, is sent.
-event fileCreated -modificationCompletedTime <seconds>
When a file is created, the event is not sent immediately, but only after the interval of time specified by -modificationCompletedTime <seconds> has elapsed, and during which no subsequent changes were made to the file, which includes the file being deleted and recreated with the same name.
-event fileModified -modificationCompletedTime <seconds>
When a file is modified, the event is not sent immediately, but only after the interval of time specified by -modificationCompletedTime <seconds> has elapsed and during which no additional changes were made to the file.
-repositoryName repository_name

Optionally, specify a database where to log the status of the retrieved files.. By default, the name filemonitor.db is used if you do not specify any names.

-repositoryPath repository_path
The path to the filemonitor database. By default, the following path is used, if you do not specify any paths:
On Windows operating systems
TWA_Home\TWS\stdlist\JM\filemonitor
On UNIX operating systems
TWA_DATA_DIR/TWS/stdlist/JM/filemonitor
Paths containing spaces must be enclosed in double quotes. Wildcards are not supported.
-generateEventsOnFirstScan
All files retrieved during the first scan performed by filemonitor are considered as created or modified and can generate events. This argument is available only if you specify the repositoryPath argument.
-recursive
Include sub-folders when monitoring files. This is an optional parameter.
-outputFile output_filename
An output file where to store the retrieved events. Ensure that the directory where the output file is to be created is already existing. The command output is also printed to standard output and stored in the job properties, if you launch the filemonitor command from a job. Paths containing spaces must be enclosed in double quotes. Wildcards are not supported. This is an optional parameter.
-scanInterval scan_interval
A period of time in seconds between two consecutive checks on the files being created or modified. The default value is 300 seconds. The supported range is 1-3600 seconds. This is an optional parameter.
-maxEventsThreshold max_events
The maximum number of events to be returned. The default value is 1. If you specify all, all events are returned. This is an optional parameter.
-minFileSize min_file_size
The minimum size in bytes that files must reach to be included in the scan. The default value is 0.
-timeout seconds | hh:mm:ss
The maximum time, in seconds, that filemonitor runs or the time of the current day until which filemonitor runs. If you do not specify this parameter, filemonitor waits indefinitely. The time refers to the local time of the workstation where filemonitor is running. This is an optional parameter.
-preserveEventsOnDelete
Returns events on the specified file, also if the file was deleted in the meantime. If you do not specify this argument, when a file is deleted all events preceding the file deletion, if any, are discarded.
-reset
Resets the information collected. With this argument, you can optionally specify the -repositoryPath and -repositoryName arguments.

Configuring trace properties for filemonitor

To configure the trace properties, edit the [FileMonitor.Logging] section in the FileMonitor.ini file located in the following path:
On Windows operating systems
<TWAHome>\TWS\ITA\cpa\config/
On UNIX operating systems
TWA_DATA_DIR/TWS/ITA/cpa/config/
and restart the filemonitor utility.
The section containing the trace properties is named:
[FileMonitor.Logging.cclog]
FileMonitor.trhd.fileName
The name of the trace file.
FileMonitor.trhd.maxFileBytes
The maximum size that the trace file can reach. The default is 1024000 bytes.
FileMonitor.trhd.maxFiles
The maximum number of trace files that can be stored. The default is 3.
FileMonitor.trfl.level
Determines the type of trace messages that are logged. Change this value to trace more or fewer events, as appropriate, or on request from Software Support. Valid values are:
DEBUG_MAX
Maximum tracing. Every trace message in the code is written to the trace logs.
INFO
All informational, warning, error and critical trace messages are written to the trace. The default value.
WARNING
All warning, error and critical trace messages are written to the trace.
ERROR
All error and critical trace messages are written to the trace.
CRITICAL
Only messages which cause the agent to stop are written to the trace.

The output trace (by default, FileMonitor_trace.log) is provided in XML format, and is located in <TWA_Home>/TWS/stdlist/JM.

Return Codes

0
The operation completed successfully.
4
Filemonitor stopped running, because timeout expired. No results were returned.
8
Filemonitor cannot run because the timeout is set to a time that is already passed.
12

Filemonitor stopped running because the timeout expired without having ever successfully accessed the repository.

-1
An error occurred. Search the trace log (by default, FileMonitor_trace.log) for additional details.

Comments

Any parameters defined with this command override the default values internally set by HCL Workload Automation.

If one or more files have been created or modified in between subsequent invocations, the modifications are detected. However, files already detected in a previous run are not listed again in subsequent invocations. Wildcards are supported in both file names and directory names.

Examples

In the following example, the filemonitor command checks every 2 minutes for all files created in the C:\temp\logs path and having a minimum size greater than 1024 bytes. The check is performed on all sub folders and the results are stored in C:\backup\logs\reports.txt:
filemonitor  -path "C:\temp\logs" -event fileCreated -recursive  -outputFile "C:\backup\logs\reports.txt" -scanInterval 120 -maxEventsThreshold all  -minFileSize 1024