Positioning File

File position specifies offset in file to read or write data at. It is always specified in bytes (regardless of type of data accessed) and can have values within range 0 (beginning of file) to file length (end of file; one byte beyond last byte in file). On usual file activity, its position is adjusted automatically whenever data is read or written; on each Get and Put operation it is moved forward by the number of bytes actually read or written.

Developers have several ways for changing file position to access data at. The easiest is to specify position as an argument in Get and Put; all of these methods have such parameter which is used to automatically position file before accessing data. If you wish to use current position just specify value of -1, which is also default; see Reading and Writing Data for more information on reading and writing data.

Automatic positioning is not always the best solution and therefore manual positioning is supported. To set absolute position use SetPosition method which allows changing position to be located anywhere in the file or at the end of file. On the contrary Skip methods allows relative positioning by moving file position forwards or backwards by specified number of bytes. In both cases unsaved data present in internal buffer is flushed to the file prior to changing its position.

To retrieve current file position use GetPosition method. Please note that file position set or returned with IXFile methods specifies offset in file for accessing data with IXFile methods only. Physical position of the file pointer can be different (and almost always is) and is changed internally only when needed.

Examples

C++

// error handling is omitted for clarity


  int main(int, char**)
  {
   IFile ixf;
   long lng1, lng2, lng3;
   long position;

   ixf.SetLicenseKey("YOURLICENSEKEY");

// initialize object for reading/writing
// and open data file

   ixf.Initialize(); 
   ixf.Open("test.bin"); 

// read long integer at position 100
// on completion file position is 104

   ixf.GetLong(&lng1, 1, 100);

// write the same value at current position (104)

   ixf.PutLong(&lng1, 1);

// save position which is 108

   position = ixf.GetPosition();

// go back to position of first long integer

   ixf.SetPosition(100);

// and read it once again

   ixf.GetLong(&lng2, 1);

// restore position to 108

   ixf.SetPosition(position);

// skip back by size of long integer

   ixf.Skip(-4);   

// and read second long integer once again
// on completion position is 108
// and lng1 == lng2 == lng3

   ixf.GetLong(&lng3, 1);

    .
    .
    .

   return(0);

  }

BASIC

' error handling is omitted for clarity


  Sub Main()

   Dim ixf As IXFile
   Dim lng1 As Long, lng2 As Long, lng3 As Long
   Dim position As Long

   Set ixf = New IXFile
   ixf.SetLicenseKey "YOURLICENSEKEY"

' initialize object for reading/writing
' and open data file

   ixf.Initialize 
   ixf.Open "test.bin"

' read long integer at position 100
' on completion position is 104

   ixf.GetLong lng1, 1, 100

' write the same value at current position (104)

   ixf.PutLong lng1

' save position which is 108

   position = ixf.GetPosition()

' go back to position of first long integer

   ixf.SetPosition 100

' and read it once again

   ixf.GetLong lng2

' restore position to 108

   ixf.SetPosition position

' skip back by size of long integer

   ixf.Skip -4

' and read second long integer once again
' on completion position is 108
' and lng1 = lng2 = lng3

   ixf.GetLong lng3

    .
    .
    .

  End Sub

See Also

SetPosition, GetPosition, Skip, Reading and Writing Data