STD.File.MonitorFile( event, [ ip ] , filename, [ ,subdirs ] [ ,shotcount ] [ ,espserverIPport ] )
dfuwuid := STD.File.fMonitorFile( event, [ ip ] , filename, [ ,subdirs ] [ ,shotcount ] [ ,espserverIPport ] );
| event | A null-terminated string containing the user-defined name of the event to fire when the filenameappears. This value is used as the first parameter to the EVENT function. |
| ip | Optional. A null-terminated string containing the ip address for the file to monitor. This is typically a landing zone. This may be omitted only if the filenameparameter contains a complete URL. |
| filename | A null-terminated string containing the full path to the file to monitor. This may contain wildcard characters (* and ?). |
| subdirs | Optional. A boolean value indicating whether to include files in sub-directories that match the wildcard mask when the filename contains wildcards. If omitted, the default is false. |
| 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: | fMonitorFile returns a null-terminated string containing the DFU workunit ID (DFUWUID). |
The MonitorFile 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 ECL Watch DFU Workunit display), which polls at a fixed interval. This interval is specified in the DFU Server's monitorinterval configuration setting. The default interval is 900 seconds (15 minutes). 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 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) Events are only generated when the monitor job starts or subsequently on the polling interval.
2) Note that the event is generated if the file has been created since the last polling interval. Therefore, the event may occur before the file is closed and the data all written. To ensure the file is not subsequently read before it is complete you should use a technique that will preclude this possibility, such as using a separate 'flag' file instead of the file, itself or renaming the file once it has been created and completely written.
3) The EVENT function's subtype parameter (its 2nd parameter) when monitoring physical files is the full URL of the file, with an absolute IP rather than DNS/netbios name of the file. This parameter cannot be retrieved but can only be used for matching a particular value.
Example:
EventName := 'MyFileEvent';
FileName := 'c:\\test\\myfile';
LZ := '10.150.50.14';
STD.File.MonitorFile(EventName,LZ,FileName);
OUTPUT('File Found') : WHEN(EVENT(EventName,'*'),COUNT(1));