File Watcher (ctmfw)

The ctmfw (Control-M File Watcher) utility, enables you to detect file creation, file deletion, or the successful completion of a file transfer activity. You can use this utility before you activate a job or perform a task, such as the creation of an event An conditional entity that creates a sequential relationship between jobs by enabling the successor job to execute after the predecessor job has executed., which depends on a created file.

The ctmfw utility runs as a process on the Agent computer, which waits for the creation or deletion of a specified file.

The ctmfw utility does the following:

• File Transfer Activity: Monitors the size of a file after it is detected. When the file reaches a predefined minimum size and does not increase in size for a specified period of time, the File Watcher utility either finishes with a status of OK or executes a specified If-Action, such as the creation or deletion of an event or a command execution.

• File Creation: Ignores the file size if a wildcard is specified as part of the filename unless the mon_size_wildcard parameter is set to Y.

• File Deletion: Monitors for the deletion of a file after detection.

The ctmfw utility runs from the CLI and can detect one or more files, as described in Watching a Single File and Watching Multiple Files.

There are two usages for this utility:

• Service: (Windows only) As a service, ctmfw takes its parameters (rules) during startup from the rull.dat file, whose full pathname is specified in <Agent>\data\ctmfw.cfg. For more information, see Usage as a Service.

• Running as a Utility: ctmfw is invoked from the CLI. Rules can be provided in the command line or by a rule file. You can watch for one or more files, as described in Watching a Single File and Watching Multiple Files.

  To allow other users to run ctmfw, they must have write permissions to $CONTROLM, and the CONTROLM environment variable must be set. For more information, see Running Agent Utilities as Other Users on UNIX. For details about ctmfw processing and return codes that are issued after the utility detects the creation or deletion of a file in the specified time frame, see ctmfw Utility Processing and Return Codes.

Usage as a Service

As a service, ctmfw takes its parameters (rules) during startup from the rull.dat file whose full path name is specified in <Agent>\data\ctmfw.cfg on Windows.

To change one or more rules, change the contents of the rull.dat file. The rull.dat file provided with Agent is a sample file and must be changed to reflect your requirements. The full pathname to the ctmfw.cfg configuration file must be specified under the following Windows registry key that is generated automatically by the installation script:

HKEY_LOCAL_MACHINE\SOFTWARE\BMC Software\CONTROL-M/FileWatcher\SYSPRM\File Watcher Configuration File

The default value for this key is <CONTROL-M/Agent_install_directory>\DATA\ctmfw.cfg

You need administrative permissions to update the registry key. It is recommended that this default value not be changed.

The configuration file must contain the following line:

-input <ruleFileName>

The variable <ruleFileName> is the full path name of a rule file containing the File Watcher rules.

The FileWatcher service running under the local system account cannot detect network resources (files located on remote systems). If you want the FileWatcher to detect network resources, configure the FileWatcher service to run under a regular user account instead of Local System Account.

When running as a service, ctmfw generates an execution log file. This file is saves in the Agent proclog directory under the following name:

U_CTMFW_<process_id>.log

Logs in the proclog directory are retained for one day, by default. If the maximum days to retain output files parameter is set to a number higher than 1, logs are retained for the number of days specified in that parameter.

Watching a Single File

This procedure describes how to watch a single file with the ctmfw File Watcher utility. Rules can be provided in the command line or by a Rule file.

Begin

1. Run the following command:

   ctmfw FILE (absolute path)

2. Enter the required parameters.

   Copy

   < mode (CREATE|DELETE)> Default: CREATE
   < minimum detected size <number>
   [' '|Bytes(B)|Kilo(K)|Mega(M)|Giga(G)] >Default:0
   < interval between file search (seconds) > Default: 60sec
   < interval between filesize comparison iterations (seconds) > Default: 10sec
   < number of iterations while the size is static > Default: 3 iterations
   < time limit for the process (minutes).> Default: 0 (no time limit)
   Effective while the file does not exists or,
   the file size is static and the minimum size
   was not reached >
   < monitor file size , minimal and maximal age, when wildcard is used > Default: N
   < starting time for detecting files (HHMM or YYYYMMDDHHMM > Default: NOW
   < absolute stop time (HHMM or YYYYMMDDHHMM > Default: +0000 ( No stop time )
   < minimal age of file (modified time)
   format:xxxxYxxxxMxxxxDxxxxHxxxxMin > Default: NO_MIN_AGE
   < maximal age of file ( timestamp monitoring )
   format:xxxxYxxxxMxxxxDxxxxHxxxxMin > Default: NO_MAX_AGE

   All parameters must be assigned a value, even if that value is zero. If only six values are specified, the default value for mon_size_wildcard is used. If five parameters are specified, default values for wait_time and mon_size_wildcard are used.

   ctmfw /home/watchedfile.txt CREATE 100 10

   is resolved by using default values for mon_int, min_detect, wait_time, and mon_size_wildcard as follows:

   ctmfw /home/samplefile.txt CREATE 100 10 10 3 0 N

ctmfw Parameters

The following table lists the ctmfw utility rule file parameters:

Watching Multiple Files

This procedure describes how to watch multiple files with the ctmfw File Watcher utility.

Begin

• Type the following command to invoke the ctmfw utility for multiple files:

  ctmfw -input <ruleFileName>

  The variable <ruleFileName> is the complete path name of the file containing the definitions for each file to be detected. The .Rule file contains the following sections:

  • Global parameters, whose default values apply to all the files in the rule file. For more information, see ctmfw Rule File Global Parameters.

  • ON_FILEWATCH statements identifying which files to detect, specific criteria for each file, and the action to take upon detection or non-detection. Any number of ON_FILEWATCH statements can appear in a Rule file. For more information about ON_FILEWATCH parameters, see File Watcher (ctmfw).

  If any mandatory parameter is omitted from a Rule file, the default value for that parameter is used. Parameters entered for ON_FILEWATCH statements override the default values.

ctmfw Rule File Global Parameters

The following table lists the ctmfw Rule file global parameters:

ctmfw Utility Processing

If the file is detected and the file size remains static within the time frame (CREATE) or the file has been deleted (DELETE), the DO commands in the THEN block are executed. If the file is not detected/deleted within the time frame, the statements following the ELSE block are executed.

CTMFW terminates when either all the files in the Rule file have been processed or a DO_OK/DO-NOTOK action is executed. If any ON_FILEWATCH statement contains a cyclic_interval, CTMFW only terminates on a DO_OK/DO-NOTOK action. If the cyclic_interval Global parameter is specified and not 0, CTMFW only terminates on a DO_OK/DO-NOTOK action or when the STOP_TIME was reached.

#******************************************************************
INTERVAL 10
ON_FILEWATCH ~<controlm_owner>\ctm_server\datafile.txt CREATE
THEN
DO_CMD move \ctm\datafile.txt \ctm\workfile.txt
ELSE
DO_CMD "FILE WAS NOT CREATED"
END_ON
ON_FILEWATCH \ctm\tempfile.txt DELETE
THEN
DO_CMD "FILE WAS DELETED"
END_ON
#*******************************************************************

Valid Actions

The following table lists the ctmfw valid actions:

Return Codes

The return codes listed in the following table are issued by the ctmfw utility after detecting if a file is created or deleted in the specified time frame.