File Watcher (ctmfw)

The ctmfw (Control-M File Watcher) utility, enables you to detect when files are created, deleted, or successfully transferred. You can use this utility before you activate a job or perform a task, such as when you create 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. that depends on an existing file.

The ctmfw utility runs as a process on the Agent host, which waits for the creation or deletion of a user-defined 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 user-defined minimum size and does not increase in size for a user-defined period of time, ctmfw ends 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 size of a file if a wildcard is specified as part of its filename unless the mon_size_wildcard parameter is set to Y.

• File Deletion: Monitors for the deletion of a file after it is detected.

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 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 pathname is defined in the following file:

<Agent_Home>\DATA\ctmfw.cfg

To change one or more rules, you must change the contents of the rull.dat file, which is provided with Agent as a sample file. The ctmfw.cfg configuration file pathname must be defined in the following Windows registry key, which is automatically generated by the installation script:

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

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

The ctmfw.cfg configuration file must also contain the following line:

-input <ruleFileName>

where the <ruleFileName> parameter defines pathname of a rule file that contains the File Watcher rules.

The FileWatcher service that runs on the local system account cannot detect network resources (files that are located on remote systems). To enable FileWatcher to detect network resources, you must configure the FileWatcher service to run under a regular user account instead of the Local System Account.

When it runs as a service, ctmfw generates an execution log file, which is saved in the Agent proclog directory, as follows:

U_CTMFW_<process_id>.log

By default, proclog directory logs are retained for one 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. 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:s

   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 following table describes ctmfw utility return codes that appear after determining whether a file has been is created or deleted in the user-defined time frame.