|
The FILE.EVENT() function creates a file event monitoring variable (Windows only).
Format
FILE.EVENT(path, event)
where
| path | is the pathname of the item to be monitored. |
| event | is 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.NAME | Any file name change in the watched directory or sub-tree. Changes include renaming, creating, or deleting a file name. |
| FE$DIR.NAME | Any directory-name change in the watched directory or sub-tree. Changes include creating or deleting a directory. |
| FE$ATTRIBUTES | Any attribute change in the watched directory or sub-tree. |
| FE$SIZE | Any 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.WRITE | Any 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.ACCESS | Any 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$CREATION | Any change to the creation time of file in the watched directory or sub-tree. |
| FE$SECURITY | Any security-descriptor change in the watched directory or subtree causes a change notification wait operation to return. |
| FE$SUBTREE | Apply 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 abort with a data type error.
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.
| 
