C++ Builder - File Streaming

	VCL File Streaming

Introduction

The Visual Component Library (VCL) provides various built-in classes to perform file processing. Most of the features are provided through the TFileStream class. To perform file streaming using this class, first declare its instance using its constructor whose syntax is:

__fastcall TFileStream(const AnsiString FileName,
		       Word Mode);

The first argument of this constructor is the name (or path) of the file you are dealing with. If the file does not exist or it cannot be accessed (opened or saved) for any reason, the compiler would throw an error and stop the action.

The second action, Mode, specifies what you are trying to do with the file.

The TFileStream class is conceptually designed to deal with the contents of one or more controls. Therefore, instead of concerning yourself with the values of controls, TFileStream would consider the change that affect a control on behalf of the user, which mostly is its contents. When saving a file, TFileStream faithfully gets the contents of all controls as you wish and saves them in one file. If opening a file, TFileStream locates the content of each file and restores it. Based on this, TFileStream is appropriate for VCL objects and usually its files should not mixed with non-VCL controls.

Saving Controls Contents

In order to save the contents of controls, first declare a pointer to TFileStream using its constructor and specify where the file would be saved. You can specify this path directly in the constructor if you know exactly where the file should be located. This can be done if you are writing a program that stores the default file at a specific location and you know where the file should be saved. Otherwise, you can use the SaveDialog control to let the user specify where to save the file.

When saving a file, the Mode argument of the constructor can be passed as one of the following constants:

Write Mode	Description
fmCreate	If the user is saving a new file, this is used to save it as new
fmOpenWrite	This is used to save a file as new. If the file was previously saved and reopened, this mode would erase its previous contents and fill it with the new data
fmOpenReadWrite	If the file already existed, this can be used to save a file that has been modified. Otherwise it can be used to create a new file

When it is possible that other people or application would try accessing the same file at the same time, the following constants can be used to manage the sharing of files:

Share Mode	Description
fmShareExclusive	Only the current application can access the file
fmShareDenyWrite	The file can be opened by other applications but they cannot modify its contents
fmShareDenyRead	The file can be modified by other applications but they cannot open it
fmShareDenyNone	There is no restriction on what the other applications can do with the current file

To combine these two mode for the Mode argument, you use the bitwise OR operator |

Imagine you create a form equipped with a Memo and an Edit controls:

Here is an example of saving the contents of both controls to a file:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnSaveClick(TObject *Sender)
{
    // Decalre a pointer to TFileStream
    TFileStream *FStream;

    // Let the user call the Save Dialog
    if( SaveDialog1->Execute() )
    {
        // Use the constructor of the TFileStream to create a file
        try {
            FStream = new TFileStream(SaveDialog1->FileName, fmCreate);
            // In the pointer to FStream, add the contents of the Memo
            FStream->WriteComponent(Memo1);
            // and the content of the Edit controls
            FStream->WriteComponent(Edit1);
        }
        __finally
        {
            // Since the pointer was created, delete it,
            // whether it was used or not
            delete FStream;
        }
    }
}
//---------------------------------------------------------------------------

Loading Controls Contents

When saving the contents of controls using TFileStream, the file is arranged so the class can locate data for each object. Based on this, you can use TFileStream to open a file that was created with this class. To do this, once again, declare a pointer to TFileStream and initialize the file using the constructor. If you already know where the file is located, you can simply provide it to the constructor. Otherwise, you can use the Open dialog box and let the user select the file.

When opening a file, you can use one of the following modes as the Mode argument:

Read Mode	Description
fmOpenRead	This is used to open a file but the user cannot modify and then save it.
fmOpenReadWrite	This allows opening an existing file, modifying, and saving it.

You can combine this mode with one of the above share modes using the bitwise OR operator. Here is an example from the same above form design:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnOpenClick(TObject *Sender)
{
    TFileStream *FStream;

    if( OpenDialog1->Execute() )
    {
        try {
            FStream = new TFileStream(OpenDialog1->FileName,
                                      fmOpenRead | fmShareExclusive);
            FStream->ReadComponent(Memo1);
            FStream->ReadComponent(Edit1);
        }
        __finally
        {
            delete FStream;
        }
    }
}
//---------------------------------------------------------------------------