Share via

FilePut Function 

  • Article

Writes data from a variable to a disk file.

The My feature gives you greater productivity and performance in file I/O operations than FilePut. For more information, see My.Computer.FileSystem Object.

Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Short, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Integer, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Single, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Double, _
      RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Decimal, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Byte, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Boolean, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Date, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As System.Array, _
   Optional RecordNumber As Integer = -1, _
   Optional ArrayIsDynamic As Boolean = False _
)
' -or-
Public Overloads Sub FilePut (
      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 two-byte string length descriptor for the string to the file. The default is False.

Exceptions

Exception type Error number Condition

ArgumentException

63

RecordNumber < 1 and not equal to -1.

IOExceptio

52

FileNumber does not exist.

IOException

54

File mode is invalid.

See the "Error number" column if you are upgrading Visual Basic 6.0 applications that use unstructured error handling. (You can compare the error number against the Number Property (Err Object).) However, when possible, you should consider replacing such error control with Structured Exception Handling Overview for Visual Basic.

Remarks

FilePut is valid only in Random and Binary mode.

Data written with FilePut is usually read from a file with FileGet.

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, the next record or byte after the last FileGet or FilePut function or pointed to by the last Seek function is written.

The StringIsFixedLength argument controls whether the function interprets strings as variable or fixed length. FilePut does not write the length descriptor when the argument is True. If you use StringIsFixedLength = True with FilePut, you need to do the same with FileGet, and you need to make sure 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, FilePut 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 cannot be determined with any certainty, 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 will be thrown.

  • If the variable being written is a string, FilePut writes a two-byte descriptor containing the string length, and then writes the data that goes into the variable. Therefore, the record length specified by the RecordLength clause in the FileOpen function must be at least two bytes greater than the actual length of the string.

  • If the variable being written is an object containing a numeric type, FilePut writes two bytes identifying the VarType of the object and then writes the variable. For example, when writing an object containing an integer, FilePut 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, FilePut 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, then you have a choice as to whether or not to write a descriptor for the size and dimensions of the array. Visual Basic 6.0 and earlier versions write the file descriptor for a dynamic array but not for a fixed-size array. Visual Basic 2005 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 will be read; if it will be read with the descriptor, then 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: (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 example, the following array declaration requires 118 bytes when the array is written to disk.

    Dim MyArray(4,9) As Integer

  • If the variable being written is any other type of variable (not a variable-length string or an object), FilePut writes only the variable data. The record length specified by the RecordLength clause in the FileOpen function must be greater than or equal to the length of the data being written.

  • FilePut writes elements of structures as if each were written individually, except there is no padding between elements. The VBFixedString attribute can be applied to string fields in the structures to indicate the size of the string when written to disk.

    Note

    String fields that have more bytes than specified by the VBFixedString attribute are truncated when written to disk,

Binary Mode

For files opened in Binary mode, most of the Random mode rules apply, with a few exceptions. The following rules for files opened in Binary mode differ from the rules for Random mode:

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

  • For any array other than an array in a structure, FilePut writes only the data. No descriptor is written.

  • FilePut writes variable-length strings that are not elements of structures without the two-byte length descriptor. The number of bytes written equals the number of characters in the string. For example, the following statements write 11 bytes to file number 1:

    Dim hellow As String = "Hello World"
FilePut(1,hellow)

  • Writing to a file with the FilePut function requires Write access from the FileIOPermissionAccess enumeration.

Example

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

Structure Person 
   Public ID As Integer
   Public Name As String
End Structure

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

Smart Device Developer Notes

This function is not supported.

Requirements

Namespace: Microsoft.VisualBasic

Module: FileSystem

Assembly: Visual Basic Runtime Library (in Microsoft.VisualBasic.dll)

See Also

Reference

FileGet Function
FileOpen Function
Seek Function
FileGetObject Function
VBFixedStringAttribute Class
Len Function (Visual Basic)
ArgumentException
IOException

Other Resources

Writing to Files in Visual Basic