Reads data from an open disk file into a variable.

Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Object, _
   Optional RecordNumber As Integer = -1 _
)

-or-

Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Short, _
   Optional RecordNumber As Integer = -1 _
)

-or-

Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Integer, _
   Optional RecordNumber As Integer = -1 _
)

-or-

Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Single, _
   Optional RecordNumber As Integer = -1 _
)

-or-

Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Double, _
   Optional RecordNumber As Integer = -1 _
)

-or-

Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Decimal, _
   Optional RecordNumber As Integer = -1 _
)

-or-

Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Byte, _
   Optional RecordNumber As Integer = -1 _
)

-or-

Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Boolean, _
   Optional RecordNumber As Integer = -1 _
)

-or-

Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Date, _
   Optional RecordNumber As Integer = -1 _
)

-or-

Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As System.Array, _
   Optional RecordNumber As Integer = -1, _
   Optional ArrayIsDynamic as Boolean = False _
)

-or-

Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As String, _
   Optional RecordNumber As Integer = -1, _
   Optional StringIsFixedLength as Boolean = False _
)

Parameters

FileNumber

Required. Any valid file number.

Value

Required. Valid variable name into which data is read.

RecordNumber

Optional. Record number (Random mode files) or byte number (Binary mode files) at which reading begins.

ArrayIsDynamic

Optional. Applies only when writing an array. Specifies whether the array is to be treated as dynamic and so whether to write an array descriptor describing the size and bounds of the array.

StringIsFixedLength

Optional. Applies only when writing a string. Specifies whether to write a two-byte descriptor for the string describing the length. The default is False.

Remarks

The FileGetObject function is used in place of FileGet to avoid ambiguities at compile time if type Object is returned rather than another type, such as Integer, Long, Short, and so forth.

If you intend to write out the Variant type, FileGetObject is required. When in doubt, if you are using an object for the second parameter, it is always safer to use FilePutObject and FileGetObject.

FileGetObject is only valid in Random and Binary mode.

Data read with FileGetObject is usually written with FilePutObject.

The first record or byte in a file is at position 1, the second record or byte is at position 2, and so on. If you omit RecordNumber, FileGetObject reads the record or byte after the last FileGetObject or FilePutObject function (or pointed to by the last Seek function).

For files opened in Random mode, the following rules apply:

• If the length of the data being read is less than the length specified in the RecordLength clause of the FileOpen function, FileGetObject reads subsequent records on record-length boundaries. The space between the end of one record and the beginning of the next record is padded with the existing contents of the file buffer. Because the amount of padding data can't be precisely determined, it is a good idea to have the record length match the length of the data being read.
• If the variable being read into is a string, by default FileGetObject reads a two-byte descriptor containing the string length and then reads the data that goes into the variable. Therefore, the record length specified by the RecordLength clause of the FileOpen function must be at least two bytes greater than the actual length of the string. Visual Basic 6 and earlier versions supported fixed-length strings and when read to a file, the length descriptor would not be written. If you wish to read a string without the descriptor, you should pass True to the StringIsFixedLength parameter, and the string you read into should be the correct length.
• If the variable being read into is an array, then you can choose to read a descriptor for the size and dimension of the array. To read the descriptor, set the ArrayIsDynamic parameter to True. When reading the array, you need to match the way the array was written. If it was written with the descriptor, you need to read the descriptor. If the descriptor is not used, the size and bounds of the array passed into FileGetObject is used to determine what to read.

  The descriptor specifies the rank of the array, the size, and the lower bounds for each rank. Its length equals 2 plus 8 times the number of dimensions, that is, 2 + 8 * NumberOfDimensions. The record length specified by the RecordLength parameter in the FileOpen function must be greater than or equal to the sum of all the bytes required to write the array data and the array descriptor. For example, the following array declaration requires 118 bytes when the array is written to disk:

  Dim MyArray(4,9) As Integer

  The 118 bytes are distributed as follows: 18 bytes for the descriptor (2 + 8 * 2), and 100 bytes for the data (5 * 10 * 2).

• FileGetObject reads elements of structures as if each were being read individually, except that there is no padding between elements. On disk, a dynamic array in a user-defined type (written with FilePutObject) is prefixed by a descriptor whose length equals 2 plus 8 times the number of dimensions, that is, 2 + 8 * NumberOfDimensions. The record length specified by the RecordLength clause in the FileOpen function must be greater than or equal to the sum of all the bytes required to read the individual elements, including any arrays and their descriptors. The VBFixedString attribute can be applied to string fields in the structures to indicate the size of string when written to disk.

For files opened in Binary mode, all of the Random rules apply, except:

• The RecordLength clause in the FileOpen function has no effect. FileGetObject reads all variables from disk contiguously; that is, with no padding between records.
• For any array other than an array in a structure, FileGetObject reads only the data. No descriptor is read.

FileGetObject reads variable-length strings that aren't elements of structures without expecting the two-byte length descriptor. The number of bytes read equals the number of characters already in the string.

Example

The following example reads a record into a test file and then retrieves it.

Dim c As String
FileSystem.FileOpen(1, "test.dat", OpenMode.Binary)
FileSystem.FilePutObject(1, "ABCDEF")
FileSystem.Seek(1, 1)
FileSystem.FileGetObject(1, c)
System.Console.WriteLine(c)
FileSystem.FileClose(1)

See Also

FilePut Function | FileOpen Function | Seek Function | File Access Types, Functions, and Statements | FileGet Function