STD.File.MonitorLogicalFileName( event, filename, [ , shotcount ] [ , espserverIPport ] )
dfuwuid := STD.File.fMonitorLogicalFileName( event, filename, [ , shotcount ] [ , espserverIPport ] );
| event | A null-terminated string containing the user-defined name of the event to fire when the filename appears. This value is used as the first parameter to the EVENT function. |
| filename | A null-terminated string containing the name of the logical file in the DFU to monitor. |
| shotcount | Optional. An integer value indicating the number of times to generate the event before the monitoring job completes. A negative one (-1) value indicates the monitoring job continues until manually aborted. If omitted, the default is 1. |
| espserverIPport | Optional. This should almost always be omitted, which then defaults to the value contained in the lib_system.ws_fs_server attribute. When not omitted, it should be a null-terminated string containing the protocol, IP, port, and directory, or the DNS equivalent, of the ESP server program. This is usually the same IP and port as ECL Watch, with "/FileSpray" appended. |
| dfuwuid | The attribute name to recieve the null-terminated string containing the DFU workunit ID (DFUWUID) generated for the monitoring job. |
| Return: | fMonitorLogicalFileName returns a null-terminated string containing the DFU workunit ID (DFUWUID). |
The MonitorLogicalFileName function creates a file monitor job in the DFU Server. Once the job is received it goes into a 'monitoring' mode (which can be seen in the eclwatch DFU Workunit display), which polls at a fixed interval (default 15 mins). If an appropriately named file arrives in this interval it will fire the event with the name of the triggering object as the event subtype (see the EVENT function).
This function does not support wildcard characters. To monitor physical files or directories using wildcards, use the MonitorFile function.
This process continues until either:
1) The shotcount number of events have been generated.
2) The user aborts the DFU workunit.
The STD.File.AbortDfuWorkunit and STD.File.WaitDfuWorkunit functions can be used to abort or wait for the DFU job by passing them the returned dfuwuid.
Note the following caveats and restrictions:
1) If a matching file already exists when the DFU Monitoring job is started, that file will not generate an event. It will only generate an event once the file has been deleted and recreated.
2) If a file is created and then deleted (or deleted then re-created) between polling intervals, it will not be seen by the monitor and will not trigger an event.
3) Events are only generated on the polling interval.
Example:
EventName := 'MyFileEvent';
FileName := 'test::myfile';
IF (STD.File.FileExists(FileName),
STD.File.DeleteLogicalFile(FileName));
STD.File.MonitorLogicalFileName(EventName,FileName);
OUTPUT('File Created') : WHEN(EVENT(EventName,'*'),COUNT(1));
rec := RECORD
STRING10 key;
STRING10 val;
END;
afile := DATASET([{ 'A', '0'}], rec);
OUTPUT(afile,,FileName);