Checking for file changes with filemonitor
- The filemonitor utility is available on the z-centric agents with HCL Workload Automation V9.4, Fix Pack 1 installed.
- To issue filemonitor from the command line, ensure that you set up the environment with
the following command from
<TWA_home>
:- Windows
-
twa_env.cmd
- UNIX and Linux
-
../twa_env.sh
- To issue filemonitor from a job, use the command
filemonitorlauncher
. The same arguments valid for filemonitor apply tofilemonitorlauncher
.
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 seconds]
filemonitor -reset
[-repositoryName repository_name]
[-repositoryPath repository_path - generateEventsOnFirstScan]
Arguments
- -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. To include more files in the monitoring
process, store all the files in the directory set with the -path argument.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
- -epath path_to_monitor
- The path where the files to be processed are located, always 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.
- Wildcard characters question mark (?) and asterisk (*) are supported.
- 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 tomypath
. - 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
or1-9
. [list_of_characters]
- A string of characters. For example,
ABC
or1aX
.
- 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. This argument is required when you specify -path.
Supported types are fileCreated and fileModified. For both types, you can set the -modificationCompletedTime, which is the 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 -modificationCompletedTimeseconds 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 -modificationCompletedTimeseconds has elapsed, and during which no subsequent changes were made to the file.
- -repositoryName repository_name
-
Optionally, specify a database where to log the status of the retrieved files. The default is
filemonitor.db
. - -repositoryPath repository_path
- The path to the filemonitor database. The default is:
- Windows
- <TWA_home>\TWS\stdlist\JM\filemonitor
- UNIX and Linux
- <TWA_DATA_DIR>/TWS/stdlist/JM/filemonitor
- -generateEventsOnFirstScan
- All the 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
- Optional. The monitoring process includes subdirectories.
- -outputFile output_filename
- Optional. 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. Wildcard characters are not allowed.
- -scanInterval scan_interval
- Optional. 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.
- -maxEventsThreshold max_events
- Optional. The maximum number of events to be returned. The default value is 1. If you specify all, all events are returned.
- -minFileSize min_file_size
- Optional. 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
- Optional. You can specify the maximum period, in seconds, that filemonitor runs or set
the time of the current day until which filemonitor runs. The time refers to the local time
of the workstation where filemonitor is running.
If you do not specify this parameter, filemonitor runs indefinitely.
- -preserveEventsOnDelete
- Optional. 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 a -repositoryName and -repositoryPath.
Configuring trace properties for filemonitor
FileMonitor.ini
file located in the following path, and restart the
filemonitor utility. - Windows
<TWA_Home>\TWS\ITA\cpa\config
- UNIX and Linux
<TWA_DATA_DIR>\TWS\ITA\cpa\config
[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 being able to access to the repository.
- -1
- An error occurred. Search the trace log (by default,
FileMonitor_trace.log
) for additional details.
Comments
If one or more files were 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. Wildcard characters are supported in both file names and directory names.
Example
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