FILE.EVENT

FILE.EVENT

Top  Previous  Next

 

The FILE.EVENT() function creates a file event monitoring variable (Windows only).

 

 

Format

 

FILE.EVENT(path, event)

 

where

 

pathis the pathname of the item to be monitored.

 

eventis the event to be trapped.

 

 

The FILE.EVENT() function allows a program to wait for a change within the Windows file system. It can be used, for example, to wait until a new file is created within a directory without needing to write a loop that periodically compares the directory content with a previously recorded list of items.

 

Path is the pathname of the directory to which the monitoring is to be applied. Event is any combination of the following additive tokens defined in the SYSCOM KEYS.H record:

FE$FILE.NAMEAny file name change in the watched directory or sub-tree. Changes include renaming, creating, or deleting a file name.
FE$DIR.NAMEAny directory-name change in the watched directory or sub-tree. Changes include creating or deleting a directory.
FE$ATTRIBUTESAny attribute change in the watched directory or sub-tree.
FE$SIZEAny file-size change in the watched directory or sub-tree. The operating system detects a change in file size only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FE$LAST.WRITEAny change to the last write time of files in the watched directory or sub-tree. The operating system detects a change to the last write-time only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FE$LAST.ACCESSAny change to the last  access time of files in the watched directory or sub-tree. The operating system detects a change to the last write-time only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FE$CREATIONAny change to the creation time of file in the watched directory or sub-tree.
FE$SECURITYAny security-descriptor change in the watched directory or subtree causes a change notification wait operation to return.
FE$SUBTREEApply monitoring to the specified directory and all sub-directories.

 

If the FILE.EVENT() function is successful, it returns a value that can be stored in a variable as a file event monitoring action for use with WAIT.FILE.EVENT() and STATUS() will be  zero. Use of the returned value in any other way will appear to be a number.

 

If the function is unsuccessful, it returns -1 and STATUS() will be ER$FAILED.

 

See WAIT.FILE.EVENT() for an example of use of this function.