FileSystem.FilePutObject(Int32, Object, Int64) Method

Reference

Definition

Namespace:: Microsoft.VisualBasic

Assembly:: Microsoft.VisualBasic.Core.dll

Assembly:: Microsoft.VisualBasic.dll

Source:: FileSystem.vb

Source:: FileSystem.vb

Source:: FileSystem.vb

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Writes data from a variable to a disk file. The My feature gives you better productivity and performance in file I/O operations than FilePutObject. For more information, see FileSystem.

public static void FilePutObject (int FileNumber, object Value, long RecordNumber = -1);

static member FilePutObject : int * obj * int64 -> unit

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

Parameters

FileNumber: Int32

Required. Any valid file number.

Value: Object

Required. Valid variable name that contains data written to disk.

RecordNumber: Int64

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

Examples

This example uses the FilePutObject function to write a string to a file.

Sub WriteData()
    Dim text As String = "test"
    FileOpen(1, "test.bin", OpenMode.Binary)
    FilePutObject(1, text)
    FileClose(1)
End Sub

Remarks

The FilePutObject function is used instead of FilePut to avoid ambiguities at compile time if type Object is passed instead of 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, we recommend that you always use FilePutObject and FileGetObject.

FilePutObject is valid only in Random and Binary mode.

Data written with FilePutObject is usually read from a file by using 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 have to do the same with FileGetObject, and you must also make sure that the string is initialized to the length expected.

Random Mode

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 start of the next record is padded with the existing contents of the file buffer. Because the amount of padding data cannot 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 that contains a numeric type, FilePutObject writes two bytes identifying the VarType of the object and then writes the variable. For example, when writing an object that contains an integer, FilePutObject writes six bytes: two bytes that identify the object as VarType(3) (Integer) and four bytes that contain 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 that contains 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 want to put 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 written is an array, then 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. 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: (2 + 8 * NumberOfDimensions).

Binary Mode

For files opened in Binary mode, all 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, without padding between records.

Applies to

Jaa