Функция FilePut

Статья
11/05/2008

Обновлен: Ноябрь 2007

Записывает значения переменных в файл на диске.

Функция 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 указывает функции, как интерпретировать строки: в виде переменной или фиксированной длины. Функция FilePut не записывает дескриптор длины, когда аргумент принимает значение True. При использовании StringIsFixedLength = True с FilePut, необходимо сделать то же самое с FileGet, и необходимо убедиться, что строка инициализируется для ожидаемой длины.

Режим Random

Для файлов, открытых в режиме Random, применяются следующие правила:

Если длина записываемых данных меньше длины, указанной в выражении RecordLength функции FileOpen, границы последующих записей, выполняемых функцией FilePut, определяются данным параметром. Пространство между концом данных одной записи и началом следующей записи заполняется существующим содержимым буфера файла. Поскольку объем данных заполнения не может быть определен с достаточной точностью, как правило, рекомендуется, чтобы длина записи соответствовала длине записываемых данных. Если длина выводимых данных больше длины записи, указанной в предложении RecordLength функции FileOpen, будет создано исключение.
Если переменная записывается как строка, FilePut записывает двухбайтовый дескриптор, содержащий длину строки, а затем записывает данные, хранящиеся в переменной. Поэтому длина записи, указываемая в предложении RecordLength функции FileOpen, должна быть как минимум на два байта больше, чем действительная длина строки.
Если записываемая переменная является объектом, содержащим числовой тип, FilePut записывает двухбайтовый идентификатор переменной VarType объекта, а затем записывает переменную. Например, если записывается объект, содержащий целое число, функция FilePut записывает шесть байтов: два байта, идентифицирующие объект как VarType(3) (Integer), и четыре байта, содержащие данные. Длина записи, указанная в параметре RecordLength функции FileOpen, должна быть как минимум на два байта больше, чем действительное число байтов, необходимых для хранения переменной.
Если записываемая переменная является объектом, содержащим строку, функция FilePut записывает двухбайтовый идентификатор объекта VarType(8), двухбайтовый дескриптор, задающий длину строки, а затем сами данные. Поэтому длина строки, указанная в параметре RecordLength функции FileOpen, должна быть как минимум на четыре байта больше, чем действительная длина строки. Если требуется прочитать строку без дескриптора, необходимо установить значение True для параметра StringIsFixedLength, а строка, в которую считываются данные, должна быть строкой правильной длины.
Если записываемая переменная является массивом, можно выбрать, записывать дескриптор с указанием размера и размерности массива, или нет. В Visual Basic 6.0 и более ранних версиях дескриптор записывается для динамического массива и не записывается для массива фиксированной длины. В Visual Basic 2005 по умолчанию дескриптор не записывается. Чтобы записать дескриптор, присвоить параметру ArrayIsDynamic значение True. Способ записи массива должен соответствовать способу чтения — если массив будет читаться с дескриптором, он должен и записываться с дескриптором. Дескриптор определяет ранг массива, его размер и нижнюю границу для каждого ранга. Его длина равна 2 плюс 8, умноженное на число измерений: (2 + 8 * NumberOfDimensions). Длина записи, заданная в выражении RecordLength функции FileOpen, должна быть больше или равна суммарному количеству байтов, необходимых для записи данных массива и его дескриптора. Например, для записи на диск объявляемого далее массива требуется 118 байтов.
```
Dim MyArray(4,9) As Integer
```
Если записываемая переменная относится к какому-либо другому типу (не является строкой переменной длины или объектом), FilePut записывает только данные переменной. Длина записи, заданная предложением RecordLength функции FileOpen, должна быть не меньше длины записываемых данных.

FilePut записывает элементы структуры, как если бы каждый элемент был независим от других, с тем исключением, что между элементами не пишутся данные-заполнители. Чтобы указать размер строки при записи на диск, к строковым полям в структурах может быть применен атрибут VBFixedString.

Примечание.
Поля строки, имеющие больше байт, чем указано в атрибуте VBFixedString усекаются при записи на диск

Двоичный режим

Для файлов, открытых в режиме Binary применима большая часть правил режима Random, с некоторыми исключениями. Следующие правила для файлов, открытых в режиме Binary, отличаются от правил для режима Random :

Условие RecordLength в функции FileOpen не обрабатывается. Функция FilePut записывает все переменные на диск рядом, без заполнения между записями.
Для любого массива, кроме массива в структуре, FilePut записывает только данные. Дескриптор не записывается.
FilePut записывает строки переменной длины, которые не являются частью структуры, без двухбайтного дескриптора. Число записанных байтов равно числу знаков в строке. Например, следующие операторы записывают 11 байтов в файл номер 1:
```
Dim hellow As String = "Hello World"
FilePut(1,hellow)
```
Запись в файл с помощью функции FilePut требует доступ из перечисления WriteFileIOPermissionAccess.

Пример

В этом примере функция 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