FILE Events

As a developer and object designer you define FILE Events to monitor file-related conditions. If the conditions are met, the FILE Event triggers the actions that you define. These actions are usually the execution of further objects. FILE Events are in Sleeping status as long as the frequency and time conditions are not met and change to Checking when they are.

FILE Events can monitor the size or number of files in a directory, the space used by files and the availability of space in certain target systems. For example, using a FILE Event you can monitor whether a specified number of files has been transferred via FTP into a directory, whether the size of a file has changed within a specific period of time, and so on.

You can use the following functions of the Automation Engine scripting language to retrieve relevant data for the Event object:

Important! Some Agents that do not support all options described here.

This page includes the following:

Defining FILE Event Objects

On the File Event page that is described here, you define what the FILE Event object should check.

On its Event Process Page, you define the actions that it will trigger if the conditions are met.

To Define File Event Objects

  1. In the File Event section specify the following:

    • Path

      Enter the drive, path or signature where the monitored file(s) are located. Depending on the target system, you can indicate files, drives, volumes, paths, Generation Data Groups, and so on.

      Allowed wildcard characters: *, ?

      Notes:

      • Since * and ? are used as wildcard characters, you cannot use them to specify files that include them in their names.

      • (Windows) The * and ? wildcard characters can be used for file names only and NOT for directories within the path.

      • (Windows) End path specifications with \*

        Example: C:\AUTOMIC\*

      • If you indicate one or more volumes, use the prefix VOL=

        Example: VOL=ALG*1 supplies information about all volumes that start with ALG and end with 1.

      • (z/OS) For Generation Data Groups, use the * wildcard character within brackets. For more information, see GDG Support.

      You can enter the path or use a variable. For more information, see Inserting Variables in Objects and Scripts.

    • Check Condition

      Select the what should be monitored. Your selection here determines which fields are displayed and available for entering data:

      • File size

        The Agent converts the file size and the specified value into bytes so that the two values can be compared.

      • Number of files

        Use this option to monitor file transfers, for example.

      • Used space

        For VMS, WINDOWS and UNIX Agents.

        To have the system calculate the used space in the entered path including the files in sub directories, activate the Include Sub-Directories checkbox.

        Activating this checkbox may impact your system performance.

      • Available space

        For BS2000 Agents

        Available memory or disk space.

      • Filesystem space

        For z/OS and Windows Agents

        Free space of volumes (z/OS) or of a drive (Windows).

    • File

      Available if you have selected File size or Number of files in Check Condition. Here you specify what should be monitored:

      • File changed

        The FILE Event checks when the file was created and its latest modification timestamp. If the file was created before the event started and the actual file size matches the value specified before, the action defined on the Process page is triggered.

      • File size stable

        The Agent checks if the file size has changed in the time frame that you define, regardless of when it was created. If the file size has not changed within that time frame, the Agent triggers the action.

      Important! If you select File changed or File size stable, the Time Parameters section is disabled; you cannot configure the frequency with which the Event will check the condition using the user interface. Instead, a mechanism available on the Agent determines the frequency. For more information, see FILE Event Delays During Event Execution.

    • Include Sub-Directories

      For VMS, UNIX and Windows Agents.

      Use wildcard characters or include sub-directories to find one file several times. Define whether One file must match or if All files must match with the specified conditions.

      Activating this checkbox may impact your system performance.

    • Comparator

      Select the operator to be used to evaluate the conditions.

    • Value

      Specify the value to which the selected check and operator refer.

    • Unit

      Select the unit with which the value will be measured. If the target system works with a different unit, it will be converted accordingly.

      Select Use Agent specific if the measuring unit that is specified in the target system (such as PAM pages in BS2000)  should be used.

      This list is only available if relevant.

  2. In the Time Parameters section, define the event monitoring parameters:

    • Frequency

      Specify how often the FILE Event object will be activated, that is, how often it will check the conditions you have defined.

      Short intervals guarantee faster execution but have an impact on the system performance.

    • Check Frequency

      If you have selected Frequency: Repeatedly or Repeat until first match, specify when the FILE Event object will be activated. Some of these settings can be read at runtime. Use script elements to access the attributes of this object.

    • First Check

      If you have selected Frequency: Repeatedly or Repeat until first match, configure when the intervals should begin:

      • Immediately means that the FILE Event object becomes active for the first time upon its activation, regardless of the specified time interval.

      • After the first interval means that the FILE Event object becomes active for the first time after the expiration of the first time interval.

    • If start time is later

      If you have selected Check Frequency: At, specify when the event should be activated:

      • Activate immediately means that if the FILE Event starts after the specified time, it becomes active immediately.

      • Wait for the next valid date means that if the FILE Event starts after the specified time, it becomes active with the next valid date considering the calendar and time conditions you specify in the Time and Date Conditions section.

  3. The FILE Event object always checks the time/date conditions that you specify in the Time and Date Conditions section section. The Event is only triggered if at least one of the conditions specified here are met or if no time/date condition has been defined.

    The current date and time are used as reference. The Time Zone assigned to the event is considered as well.

    Important! Time specifications are checked for full minutes. For example, an ending time defined as 23:59 hours lasts until 23:59:59. This means that the Event can also be triggered in the last 59 seconds.

  4. Switch to the Event Process Page.

    You can use the GET_FILESYSTEM function to read information about the file system.

Next Steps

FILE Event Delays During Event Execution

Extensive I/O and certain practices when configuring FILE Event objects can affect the speed of your system. For example:

To avoid a negative impact in your system in these situations, the Windows, Unix and BS2000 Agents have the following built-in protection mechanisms:

Adaptive Delay

FILE Events allow to scan directory trees and to monitor a large number of files recursively and frequently. Rather than checking at regular, static intervals, the Agent uses an adaptive delay between FILE Event executions. For this purpose, the Agent calculates when the Event will next execute. To calculate it, the Agent uses an algorithm that considers the latest execution time of the Event and the number of Events that were running concurrently at that time.

System administrators can set the minimum wait time between FILE Event executions in the EVENT_CHECKINTERVAL key in the UC_HOSTCHAR_DEFAULT variable. This means that EVENT_CHECKINTERVAL is not an interval but a delay.

For more information, see EVENT_CHECKINTERVAL.

Execution Duration Checks

The delay is calculated based on the value specified in the EVENT_CHECKINTERVAL key and on how long the latest execution of the FILE Event took:

However, the maximum delay is always 10 minutes.

Validity Time Checks

The Calendar that you assign to the FILE Event determines the Event validity times. If the Event fires outside those times, the checking delay is set to 10 minutes.

See also: