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.

WHERE

In File Event > Path you define where the file(s) to be monitored are stored
WHAT

In File Event > Check Condition and File you define what should be monitored
WHEN

In Time Parameters you define how often those conditions should be checked. This section is disabled if you want to monitor File changed or File size stable. This topic explains why.
Additional time conditions

In Time and Date Conditions you fine-tune the time conditions

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

To Define File Event Objects

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.
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.
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.
Switch to the Event Process Page.

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

Next Steps

On the Event Process Page, define the actions that the Event will trigger.
Execute the Event object to activate it.

The execution of an Event object triggers the execution of other objects, which in turn trigger the execution of further tasks. The tasks resulting from these executions are displayed in the Process Monitoring perspective on the various lists of Executions related to the Event object. They are children of the Event task and are flagged with a special tag type called !EVNT. The tag lets you check which executions were triggered by a specific Event. For more information, see Monitoring Events and Execution Data.

Execute Event objects in the following ways:
- Include Event objects in Schedules (JSCH) to execute them automatically at predefined times and/or intervals.
- Insert Event objects in Workflows (see Designing Workflows (JOBP)).
- Manually execute, restart or stop Event objects. For more information, see Executing Events.
To check the number of times the system checked the Event, go to the Check count section in the Details of the object. For more information, see Viewing Object and Task Details.
Monitor the Event.

Immediately after executing the object, you can start monitoring the Event. Right-click the object and select Monitoring, Show in Process Monitoring and open the pre-filtered list of tasks to display the task. Follow the progress of the task and access reports and statistical information in the Process Monitoring perspective.

You can stop active Events in the following ways:
- cancel the Event
  Status: Abend/manually canceled
- Quit the Event
  Status: Ended_OK
- Suspend the Event
  Event remains active, but temporarily disabled
For more information, see Working with Tasks, particularly Stopping and Interrupting.

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:

Starting a FILE Event every minute when executing that Event takes nearly a minute. In this situation, the Agent would occupy the hard disk I/O.
Checking an Event every minute when executing that Event takes longer than a minute. In this situation, the Event executions would overlap.
FILE Event executions depend on the number of files, which may vary, and on the speed of the file system. Therefore, Event execution times may vary and cannot be anticipated.

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
Execution duration checks
Validity time checks

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:

If the execution took less than the value specified in the key, then the next checking delay is the value defined in the key
If the execution took longer, then the delay is a multiple of the value in the EVENT_CHECKINTERVAL key. The value that the execution used for the latest execution is multiplied by the number of concurrent Events at that time.

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.