File Watcher (ctmfw)

The ctmfw (Control-M File Watcher) utility, enables you to detect the successful completion of a file transfer activity or a file creation or file deletion. You can use it before activating a job or before performing a task, such as adding or deleting eventsAn entity that creates a sequence relationship between jobs by enabling the successor job to execute after the predecessor job has executed, which is dependent upon a created file.

The ctmfw utility runs as a process on the Agent host computer. The process waits for the creation or deletion of a specified file. The ctmfw utility does the following:

• File transfer activity: When the file is detected, the job continues to monitor the size of the file. When the file reaches a specified 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 DO action. DO actions can consist of adding or deleting events or executing a command.

• File creation: The file size is ignored if a wildcard is specified as part of the file name unless the mon_size_wildcard parameter is set to Y.

• File deletion: ctmfw must first detect the existence of the file before it can detect its deletion.

The ctmfw utility runs from the command line to detect a single file or multiple files. For more information, see 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 path name is specified in <Agent>\data\ctmfw.cfg. For more information, see Usage as a Service.

• Running as a utility: ctmfw is invoked from the command line. Rules can be provided in the command line or by a rule file. You can watch a single or multiple files. For more information, see Watching a Single File or 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 Control-M/Agent utilities as other users. For details about ctmfw processing and return codes issued after detecting if a file is created or deleted 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 Control-M/Agent is a sample file and must be changed to reflect your requirements. The full path name 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

By default, logs in the proclog directory are retained for 1 day. 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. From a command line, type the following:

   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 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.