Writes data from a variable to a disk file.

Public Sub FilePutObject( _
   FileNumber As Integer, _
   Value As Object, _
   RecordNumber As Integer = -1 _
)

-or-

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

-or-

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

-or-

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

-or-

Overloads Public Sub FilePutObject( _
   FileNumber As Integer, _
   Value As Double, _
   RecordNumber As Integer = -1 _
)

-or-

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

-or-

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

-or-

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

-or-

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

-or-

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

-or-

Overloads Public Sub FilePutObject( _
   FileNumber As Integer, _
   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 containing data written to disk.

RecordNumber

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

ArrayIsDynamic

Optional. Applies only when writing an array. Specifies whether the array is to be treated as dynamic, and whether to write an array descriptor for the string describing the length.

StringIsFixedLength

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

Remarks

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

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

FilePutObject is only valid in Random and Binary mode.

Data written with FilePutObject is usually read from a file with FileGetObject.

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, FilePutObject writes the next record or byte after the last FileGetObject or FilePutObject function (or the record or byte pointed to by the last Seek function).

The StringIsFixedLength argument controls whether the function interprets strings as variable or fixed length. FilePutObject does not write the length descriptor when the argument is True. If you use StringIsFixedLength = True with FilePutObject, you need to do the same with FileGetObject, and must also make sure that the string is initialized to the length expected.

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

• If the length of the data being written is less than the length specified in the RecordLength clause of the FileOpen function, FilePutObject writes 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 generally a good idea to have the record length match the length of the data being written. If the length of the data being written is greater than the length specified in the RecordLength clause of the FileOpen function, an exception is thrown.
• If the variable being written is an object containing a numeric type, FilePutObject writes two bytes identifying the VarType of the object and then writes the variable. For example, when writing an object containing an integer, FilePutObject writes six bytes: two bytes identifying the object as VarType(3) (Integer) and four bytes containing the data. The record length specified by the RecordLength parameter in the FileOpen function must be at least two bytes greater than the actual number of bytes required to store the variable.
• If the variable being written is an object containing a string, FilePutObject writes a two-byte descriptor identifying the VarType(8) of the object, a two-byte descriptor indicating the length of the string, and then writes the string data. The record length specified by the RecordLength parameter in the FileOpen function must be at least four bytes greater than the actual length of the string. If you wish to put a string without the descriptor, then you should pass True to the StringIsFixedLength parameter, and the string you read into should be the correct length.
• If the variable being written is an array, you can choose to write a descriptor for the size and dimensions of the array. Visual Basic 6 and earlier versions would write the file descriptor for a dynamic array, but not for a fixed-size array; Visual Basic .NET defaults to not writing the descriptor. To write the descriptor, set the ArrayIsDynamic parameter to True. When writing the array, you need to match the way the array is read; if it is read with the descriptor, you need to write the descriptor. 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 clause 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 files opened in Binary mode, all of the Random mode rules apply, except:

• The RecordLength clause in the FileOpen function has no effect. FilePutObject writes all variables to disk contiguously, that is, with no padding between records.

Example

This example uses the FilePutObject function to write data to a file. Five records of the structure Person are written to the file.

    Sub WriteData()
        Dim Person As String
        Dim recordNumber As Integer
        '    Open file for random access.
        FileOpen(1, "C:\TESTFILE.txt", OpenMode.Binary)
        For recordNumber = 1 To 5   ' Loop 5 times.
            Person = "My Name" & recordNumber   ' Create a string.
            FilePutObject(1, Person)   ' Write record to file.
        Next recordNumber
        FileClose(1)
    End Sub

See Also

FileGet Function | FileOpen Function | Seek Function | File Access with Visual Basic Run-Time Functions | FilePut Function