Flush

(Engine-Level Function)

Description:	Pushes the data in all software caches associated with a FileStream directly to the physical media.
Returns:	Nothing (see parameters)
Usage:	Script Only.
Function Groups:	Stream and Socket
Related to:	Diff \| CloseStream
Threaded:	Yes
Format:	Flush(Stream, CompletionCounter, Success);
Parameters:

Stream

Required FileStream. Any expression that resolves to the stream that is to be persisted to the physical media.

This must be a FileStream. Other stream types do nothing in response to a Flush call.

CompletionCounter

Required numeric. Any expression that resolves to a variable containing a numeric value or Invalid. If a numeric variable, the value will be incremented at the instant that Flush is called. It will then be decremented after the stream has been flushed. The same variable can be used to monitor any number of simultaneous, asynchronous Flush operations.
If this parameter is set to Invalid then the Flush operation will be performed synchronously and the function won't return until the stream is flushed.

Success

Required Boolean. Any expression that resolves to a variable containing a numeric value or Invalid. If a numeric value, that value will be set after the stream has been flushed to indicate the success of the operation. A value of TRUE (1) indicates success while FALSE (0) indicates failure. If set to invalid then the success of the operation is not reported.

Comments:

The operation is bound to the speed of the physical media and can be slow.

This function is used to ensure that all preceding operations on a FileStream have been completed on the physical media before the operation completes. All file operations in VTScada are subject to the mediation of the file cache (a part of the Operating System that serves to speed up file access) which can have a reliability cost when the cache or the media are disrupted.
This function allows the caller to momentarily opt out of the file cache, ensuring that a file is in the expected state while exposing the caller to the performance limitations of the physical device. As this can be a very slow operation it is performed asynchronously, with the caller being informed after the operation completes. Note that an asynchronous flush can be prevented by the CloseStream function if that results in the file being closed before the flush completes.

There are two types of asynchronous operation available, depending upon whether the CompletionCounter value has been set to a variable containing a valid or invalid value. If invalid, the thread upon which the call was made is blocked until the operation completes, but other threads are allowed to run.
CompletionCounter should not be set invalid if Flush is called in a CriticalSection as this will cause all threads to await the flush operation.
If CompletionCounter is set to a valid numeric value then the flush operation will occur independently of the calling thread, which will continue executing immediately. This mechanism is identical to that used by the Diff function, and the CompletionCounter parameters of the two operations can be shared.

If the Success parameter is provided and has not been set to 1 by the time the operation completes then it should be assumed that the file has not been persisted, and in fact may not be persist-able. This can happen if there is something wrong with the Stream parameter, or if either the OS file cache or the physical media are damaged. Flushing a file that has nothing to write will set this parameter to TRUE (1).

Example:

...
    IfThen(GetStreamLength(FStream) > 0 && True(Flushing),
           Flush(FStream, Invalid, Invalid);
    );