48.17. $truncateFile

$truncateFile truncates the file f, if the device permits such an operation. It returns TRUE if the file is truncated, FALSE otherwise. An error occurs if f is not open for random output. fileSize is the requested size, in character units.

$truncateFile does not extend a file if the file's current length is less than fileSize; in this case, $truncateFile leaves the file unchanged and returns TRUE.

If the device or operating system does not support file truncation, then the file size is not changed, $truncateFile returns FALSE, and no error message is issued. If the operating system supports file truncation, then f is truncated so that its end-of-file position is as close to the requested size as possible and $truncateFile returns TRUE. The end-of-file position of f may be larger than the requested size, but never smaller.

An error occurs if f is a sequential file, if f is opened for input only, or if the operating system's file truncation procedure returns an error. In the first two cases, an error message is written to logFile regardless of the setting of the errorOK bit in ctrlBits.

The only valid ctrlBits is errorOK, which suppresses any operating system error message that might otherwise occur.

$truncateFile does not change the current MAINSAIL file position. If the current MAINSAIL file position is beyond the end-of-file position of the truncated file, then the file position is set as if a setPos beyond the end-of-file had been done. The end-of-file position is not changed until data are written beyond the end-of-file.