Opening and Attaching File

Having IXFile object created and initialized, we can open or attach file which we will operate on. To open file, either Open or OpenAdvanced method can be used depending on how much control over access mode is required. Open is used whenever file access and share mode can be solely determined by mode of operation of the object. Developer does not have to specify access mode and other file related parameters because these parameters result from mode of operation of the object specified during initialization. This means that you do not have direct control over file access mode. Such behaviour may not be, in some situations, appropriate. For example when file must be opened for shared access with manual locking only; in such case Open method opens file for exclusive access, because automatic file locking is disabled. Instead, OpenAdvanced should be used which gives you complete control over file access and sharing mode, creation disposition, attributes and flags. Keep in mind, however, that it is your responsibilty to specify correct parameters for proper operation.

Name of the file for both methods can be specified as either absolute or relative path; if relative path is used GetName method can be called to get fully qualified path. To obtain system handle of the opened file GetFile method should be called; handle can be passed to any Windows file access function that expects file handle as a parameter.

Attach method is typically used in situations when operation must be performed on file that is already opened by another code that return file handle. This handle must be valid system handle obtained from Windows functions. Please note that file should be opened in access mode compatible with mode of operation of the object in order to read/write operations perform correctly.

When file is no longer needed it should be closed to release resources. Files can be closed either automatically or manually. Automatic file closing occurs when object is initialized with autoclose feature enabled and is performed whenever new file is attached to the object or object is being destroyed. Close method can be used any time to unconditionally close file. In either case data buffers are flushed to the file and written to disk.

Examples

C++

// error handling is omitted for clarity


  int main(int, char**)
  {
   IFile ixf1;
   IXFile *ixf2, *ixf3;
   HANDLE h2;

   ixf2 = new IXFile();
   ixf3 = new IXFile();

   ixf1.SetLicenseKey("YOURLICENSEKEY");
   ixf2->SetLicenseKey("YOURLICENSEKEY");
   ixf3->SetLicenseKey("YOURLICENSEKEY");

// default initialization 
// read/write access, auto file closing, 16KB buffer

   ixf1.Initialize(); 

// initialize for read-only access with automatic locking

   ixf2->Initialize(IXF_MODE_READ | IXF_MODE_READLOCK); 

// initialize for read/write access, automatic file closing and 1KB buffer

   ixf3->Initialize(IXF_MODE_RDWR | IXF_MODE_CLOSE, 1024); 

// open first file
// mode of operation forces read/write access to the file
// and exclusive access; sharing is disabled because 
// there is no IXF_MODE_RDWRLOCK in ixf1
// file must exist and will be truncted to zero size

   ixf1.Open("test1.bin", FALSE, TRUE); 

// second file is attached by handle (assuming it is already opened)
// file must have read access (as ixf2 object) 
// and can be opened for shared read/write 
// because automatic locking is used

   ixf2->Attach(h2); 

// third file is opened for read/write access 
// file is shared for reading/writing
// if file does not exist it will be created with 'normal' attribute
// wait 10 seconds for file if used exclusively by another application
//
// OpenAdvanced() is used because automatic locking is disabled in ixf3
// and Open() would open file for exclusive access (not shared)
// manual locking should be used to avoid file data corruption 
// when accessed by multiple applications or threads

   ixf3->OpenAdvancedAttach("test3.bin", IXF_FILE_RDWR, IXF_FILE_SHARE_RDWR, IXF_FILE_OPEN_CREATE, IXF_FILE_NORMAL, 10);

    .
    .
    .

// open fourth file for read/write access and no sharing
// if file does not exist it will be created
//
// previously attached file 'test1.bin' is closed automatically

   ixf1.Open("test4.bin",TRUE,FALSE); 

// on object destruction second file is detached but not closed 
// autoclose feature is disabled in ixf2 object because external 
// file handle is used

   delete ixf2;

// third file must be closed manually before object destruction 
// autoclose feature is disabled in ixf3 object

   ixf3->Close(); 
   delete ixf3; 

// ixf1 object is destroyed by the system when function returns
// and file is closed automatically

   return(0);

  }

BASIC

' error handling is omitted for clarity


  Sub Main()

   Dim ixf1 As IXFile, ixf2 As IXFile, ixf3 As IXFile
   Dim h2 As Long

   Set ixf1 = New IXFile
   Set ixf2 = New IXFile
   Set ixf3 = New IXFile 

   ixf1.SetLicenseKey "YOURLICENSEKEY"
   ixf2.SetLicenseKey "YOURLICENSEKEY"
   ixf3.SetLicenseKey "YOURLICENSEKEY"

' default initialization 
' read/write access, auto file closing, 16KB buffer

   ixf1.Initialize 

' initialize for read-only access with automatic locking

   ixf2.Initialize IXF_MODE_READ Or IXF_MODE_READLOCK 

' initialize for read/write access, automatic file closing and 1KB buffer

   ixf3.Initialize IXF_MODE_RDWR Or IXF_MODE_CLOSE, 1024 

' open first file
' mode of operation forces read/write access to the file
' and exclusive access; sharing is disabled because 
' there is no IXF_MODE_RDWRLOCK in ixf1
' file must exist and will be truncted to zero size

   ixf1.Open "test1.bin", False, True 

' second file is attached by handle (assuming it is already opened)
' file must have read access (as ixf2 object) and can be opened for shared 
' read/write because automatic locking is used

   ixf2.Attach h2 

' third file is opened for read/write access 
' file is shared for reading/writing
' if file does not exist it will be created with 'normal' attribute
' wait 10 seconds for file if used exclusively by another application
'
' OpenAdvanced() is used because automatic locking is disabled in ixf3
' and Open() would open file for exclusive access (not shared)
' manual locking should be used to avoid file data corruption 
' when accessed by multiple applications or threads

   ixf3.OpenAdvancedAttach "test3.bin", IXF_FILE_RDWR, IXF_FILE_SHARE_RDWR, IXF_FILE_OPEN_CREATE, IXF_FILE_NORMAL, 10

    .
    .
    .

' open fourth file for read/write access and no sharing
' if file does not exist it will be created
'
' previously attached file 'test1.bin' will be closed automatically

   ixf1.Open "test4.bin", TRUE, FALSE

    .
    .
    .

' ixf1 file is closed automatically on object destruction
' by assigning object to Nothing immediate destruction
' of the object can be forced

   Set ixf1 = Nothing

' on object destruction second file is detached but not closed 
' autoclose feature is disabled in ixf2 object because external 
' file handle is used

' third file must be closed manually before object destruction 
' autoclose feature is disabled in ixf3 object

   ixf3.Close 

  End Sub

See Also

Open, OpenAdvanced, Attach, Detach, Close, GetName, GetFile, GetTimeStamp