The WAIT.FILE.EVENT() function waits for a file monitoring event (Windows only).
The WAIT.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.
The event(s) to be monitored are established using the FILE.EVENT() function. Where only a single event is to be monitored, the value returned by this function can be stored in a simple scalar variable. If multiple events are to be monitored, the returned values should be stored in a dimensioned array. The WAIT.FILE.EVENT() function will ignore any elements of the array that are not file monitoring event values. See FILE.EVENT() for a list of the events that can be trapped.
The WAIT.FILE.EVENT() function uses an efficient event waiting mechanism within the Windows operating system. When a monitored event occurs, the function returns the index of the associated element of the event array or, if this was a scalar variable, 1. If the function returns because the timeout has expired, it returns zero.
When using an array of events, an event can be removed from the list by overwriting the relevant element of the event array with any other type of data. Because use of a file event monitoring variable in any other way returns a non-negative number, setting the element to a negative value or a null string provides a reliable way to recognise unused entries. If the array contains no file event monitoring variables, the WAIT.FILE.EVENT() function simply sleeps for the given timeout period.
Beware that when the SAFEDIR configuration parameter is set to 1, if this function is used to monitor a directory into which items are written using QM, two file notification events will occur for each write.
EVT = FILE.EVENT("C:\IMPORT", FE$FILE.NAME)
IF WAIT.FILE.EVENT(EVT, 10) > 0 THEN
The above program fragment creates a file monitoring event to trap changes to the C:\IMPORT directory as a result of creating, deleting or renaming a file. The WAIT.FILE.EVENT() function waits for an event to occur and then executes some processing code before waiting for the next event. In this example, the wait includes a ten second timeout to allow the program to perform some other periodic tasks.
EVT(1) = FILE.EVENT("C:\IMPORT", FE$FILE.NAME + FE$SUBTREE)
EVT(2) = FILE.EVENT("C:\EXPORT", FE$FILE.NAME + FE$SUBTREE)
IF WAIT.FILE.EVENT(EVT, 0) > 0 THEN
In this example, two directories and their sub-directories are monitored. Note that the EVT array has been dimensioned as three elements but only two are used. The WAIT.FILE.EVENT() function will ignore the unused element. Monitoring of either directory could be temporarily disabled in the processing code by setting the EVT array element to -1. Similarly, the processing code could add a new monitored event in EVT(3).