BaseCLX supports several ways of working with files. The previous section, “Using streams,” states that you can use specialized streams to read from or write to files. In addition to using file streams, there are several runtime library routines for performing file I/O. In addition to input/output operations, you may want to manipulate files on disk.

There are several approaches you can take when reading from and writing to files:

• The recommended approach for working with files is to use file streams. File streams are instances of the TFileStream class used to access information in disk files.

File streams are a portable and high-level approach to file I/O. Because file streams make the file handle available, this approach can be combined with the next one.

• You can work with files using a handle-based approach. File handles are provided by the operating system when you create or open a file to work with its contents. The SysUtils unit defines a number of file-handling routines that work with files using file handles.

On Windows, these are typically wrappers around Windows API functions. Because the BaseCLX functions can use the Delphi language syntax, and occasionally provide default parameter values, they are a convenient interface to the Windows API.

Furthermore, there are corresponding versions on Linux, so you can use these routines in cross-platform applications. To use a handle-based approach, you first open a file using the FileOpen function or create a new file using the FileCreate function. Once you have the handle, use handle-based routines to work with its contents (write a line, read text, and so on).

• The System unit defines a number of file I/O routines that work with file variables, usually of the format "F: Text:" or "F: File:" File variables can have one of three types: typed, text, and untyped. A number of file-handling routines, such as AssignPrn and writeln, use them.

The use of file variables is deprecated, and these file types are supported only for backward compatibility. They are incompatible with Windows file handles.

Using file streams

The TFileStream class enables applications to read from and write to a file on disk. Because TFileStream is a stream object, it shares the common stream methods. You can use these methods to read from or write to the file, copy data to or from other stream classes, and read or write components values.

In addition, file streams give you access to the file handle, so that you can use them with global file handling routines that require the file handle. To create or open a file and get access to its handle, you simply instantiate a TFileStream. This opens or creates a specified file and provides methods to read from or write to it.

If the file cannot be opened, the TFileStream constructor raises an exception.

constructor Create(const filename: string; Mode: Word);

The Mode parameter specifies how the file should be opened when creating the file stream. The Mode parameter consists of an open mode and a share mode OR’ed together. The open mode must be one of the following values:

• fmCreate - TFileStream a file with the given name. If a file with the given name exists, open the file in write mode.
• fmOpenRead - Open the file for reading only.
• fmOpenWrite - Open the file for writing only. Writing to the file completely replaces the current contents.
• fmOpenReadWrite - Open the file to modify the current contents rather than replace them.

The share mode can be one of the following values with the restrictions listed below:

• fmShareCompat - Sharing is compatible with the way FCBs are opened (VCL applications only).
• fmShareExclusive - Other applications can not open the file for any reason.
• fmShareDenyWrite - Other applications can open the file for reading but not for writing.
• fmShareDenyRead - Other applications can open the file for writing but not for reading (VCL applications only).
• fmShareDenyNone - No attempt is made to prevent other applications from reading from or writing to the file.

Note that which share mode you can use depends on which open mode you used. The following table shows shared modes that are available for each open mode.

Using the file handle

When you instantiate TFileStream you get access to the file handle. The file handle is contained in the Handle property. On Windows, Handle is a Windows file handle. On Linux versions of CLX, it is a Linux file handle. Handle is read-only and reflects the mode in which the file was opened.

If you want to change the attributes of the file Handle, you must create a new file stream object. Some file manipulation routines take a file handle as a parameter. Once you have a file stream, you can use the Handle property in any situation in which you would use a file handle.

Be aware that, unlike handle streams, file streams close file handles when the object is destroyed.