FilePut 函数

项目
08/18/2008

更新：2007 年 11 月

将数据从变量写入磁盘文件。

在文件 I/O 操作中，My 功能具有比 FilePut 更高的效率和更好的性能。有关更多信息，请参见 My.Computer.FileSystem 对象。

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
)

参数

FileNumber
必需。任何有效文件号。
Value
必需。有效的变量名称，包含要写入磁盘的数据。
RecordNumber
可选。开始写入处的记录号（Random 模式文件）或字节号（Binary 模式文件）。
ArrayIsDynamic
可选。仅应用于写数组时。指定是否将数组视为动态的，以及是否为描述长度的字符串写入一个数组说明符。
StringIsFixedLength
可选。仅适用于写入字符串时。指定是否将字符串的双字节字符串长度说明符写入文件中。默认值为 False。

异常

异常类型	错误号	条件
ArgumentException	63	RecordNumber < 1 且不等于 -1。
IOExceptio	52	FileNumber 不存在。
IOException	54	文件模式无效。

如果正在升级使用非结构化错误处理方式的 Visual Basic 6.0 应用程序，请参见“错误号”一列。（您可以根据 Number 属性（Err 对象）比较错误号。）然而，如果可能，应当考虑用 Visual Basic 的结构化异常处理概述替换这种错误控制。

备注

FilePut 只在 Random 和 Binary 模式中有效。

用 FilePut 写入的数据通常由 FileGet 从文件中读取。

文件的第一个记录或字节在位置 1，第二个记录或字节在位置 2，依此类推。如果省略 RecordNumber，则将写入上一个 FileGet 或 FilePut 函数后面或上一个 Seek 函数指向的下一个记录或字节。

StringIsFixedLength 参数控制函数将字符串解释为变长还是固定长度。在参数为 True 时，FilePut 不会写入说明符。如果将 StringIsFixedLength = True 与 FilePut 一起使用，则同样需要将其与 FileGet 一起使用，而且还必须确保字符串初始化为所需长度。

随机模式

对于以 Random 模式打开的文件，适用下列规则：

如果写入的数据长度小于 FileOpen 函数的 RecordLength 子句中指定的长度，则 FilePut 将在记录长度边界的范围内写入后面的记录。一个记录的结尾与下一个记录开头之间的空白由文件缓冲区内的现有内容填充。由于无法确定填充的数据量，一般情况下，最好设法使记录的长度与写入的数据长度一致。如果写入的数据长度大于 FileOpen 函数的 RecordLength 子句中指定的长度，将引发异常。
如果写入的变量是字符串，则 FilePut 将写入一个包含该字符串长度的双字节说明符，然后写入放入变量的数据。因此，由 FileOpen 函数中的 RecordLength 子句指定的记录长度必须至少比字符串的实际长度多两个字节。
如果写入的变量是包含 Numeric 类型的对象，则 FilePut 将写入两个字节来标识对象的 VarType，然后再写入该变量。例如，当写入包含整数的对象时，FilePut 将写入六个字节：两个字节将该对象标识为 VarType(3) (Integer)，四个字节包含数据。由 FileOpen 函数中的 RecordLength 参数指定的记录长度必须比存储变量所需的实际字节数至少多两个字节。
如果所写入变量是包含字符串的对象，则 FilePut 先写入一个双字节说明符标识该对象的 VarType(8)，再写入一个双字节说明符指示字符串长度，然后写入字符串数据。由 FileOpen 函数中的 RecordLength 参数指定的记录长度必须至少比字符串实际长度多四个字节。如果想放置字符串而不带说明符，那么应向 StringIsFixedLength 参数传递 True，并且要读入的字符串长度应正确。
如果写入的变量是数组，则可以选择是否写入该数组大小和维度的说明符。Visual Basic 6.0 及较早版本写入动态数组（而不是固定大小数组）的文件说明符。在默认情况下，Visual Basic 2005 不写入说明符。若要写入说明符，请将 ArrayIsDynamic 参数设置为 True。写入数组的方法应与读取数组的方法一致；如果将使用说明符读取数组，则需要写入说明符。说明符指定数组的秩、大小和每个秩的下限。其长度等于 2 加上 8 与维数的乘积：(2 + 8 * NumberOfDimensions)。由 FileOpen 函数中的 RecordLength 子句指定的记录长度必须大于或等于写入数组数据和数组说明符所需的全部字节数的总和。例如，在将数组写入磁盘时，下列数组声明要求 118 字节的空间。
```
Dim MyArray(4,9) As Integer
```
如果写入的变量是任何其他类型的变量（不是变长字符串或对象），则 FilePut 只写入变量数据。由 FileOpen 函数的 RecordLength 子句所指定的记录长度必须大于或等于所写入的数据长度。
FilePut 象分别写入每个元素一样写入结构的元素，元素之间没有空白的情况除外。VBFixedString 属性可应用于结构中的字符串字段，以指示字符串写入磁盘时的大小。

说明：

字节数多于 VBFixedString 属性指定的字节数的字符串字段在写入到磁盘时将被截断，

说明：
字节数多于 VBFixedString 属性指定的字节数的字符串字段在写入到磁盘时将被截断，

二进制模式

以 Binary 模式打开的文件适用大多数的 Random 模式规则，只有少数例外。适用于以 Binary 模式打开的文件的以下规则不同于适用于 Random 模式的规则：

FileOpen 函数中的 RecordLength 子句不会产生任何影响。FilePut 连续向磁盘中写入所有变量，也就是说，记录之间没有空白。
对于结构中的数组以外的任何数组，FilePut 只写入数据。不写入说明符。
FilePut 写入的变长字符串不是没有双字节长度说明符的结构元素。写入的字节数等于字符串所包含的字符数。例如，下列语句将 11 个字节写入文件号为 1 的文件：
```
Dim hellow As String = "Hello World"
FilePut(1,hellow)
```
使用 FilePut 函数写入文件时，要求具备 FileIOPermissionAccess 枚举指定的 Write 访问权限。

示例

本示例用 FilePut 函数将数据写入文件。向文件写入结构 Person 的五个记录。

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