Função FilePut

Artigo
08/25/2010

Grava dados de uma variável para um arquivo do disco.

O recurso My dá a você maior produtividade e desempenho em operações de E/S de arquivos que FilePut.Para obter mais informações, consulte Objeto 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
)

Parâmetros

FileNumber
Obrigatório.Qualquer número de arquivo válido.
Value
Obrigatório.Nome de variável válido que contenha os dados gravados no disco.
RecordNumber
Opcional.Gravar número (arquivos de modo Random) ou número de byte (arquivos de modo Binary) no qual a leitura começa.
ArrayIsDynamic
Opcional.Aplica-se somente quando se escreve uma matriz.Especifica se a matriz deve ser tratada como dinâmica, e se deve gravar um descritor de matriz para a sequência de caracteres que descreve o comprimento.
StringIsFixedLength
Opcional.Aplica-se somente quando se grava uma sequência de caracteres.Especifica se deve gravar um descritor com comprimento de dois bytes para a sequência de caracteres para o arquivo.O padrão é False.

Exceções

Tipo de exceção	Número de erro	Condição
ArgumentException	63	RecordNumber < 1 e não igual a -1.
IOExceptio	52	FileNumber não existe.
IOException	54	Modo de arquivo é inválido.

Ver a coluna " número de erro " se você estiver atualizando aplicativos Visual Basic 6.0 que usam manipulação de erros não estruturada.(Você pode comparar o número do erro com a Propriedade do Número (Erro de objeto).) Entretanto, quando for possivel, você pode considerar substituir tal controle de erro por Visão Geral sobre a Manipulação Estruturada de Exceções para o Visual Basic.

Comentários

FilePut é válido somente nos modos Random e Binary.

Dados escritos com FilePut são normalmente lidos a partir de um arquivo com FileGet.

O primeiro registro ou byte em um arquivo está na posição 1, o segundo registro ou de byte está na posição 2 e assim por diante.Se você omitir RecordNumber, o próximo registro ou byte após a última função FileGet ou FilePut ou apontado pela última função Seek será escrito.

The StringIsFixedLength argumento controla se a função interpreta sistema autônomo seqüências de caracteres sistema autônomo comprimento fixo ou variável. FilePut não gravar quando o argumento é o descritor de comprimento True. Se você usar StringIsFixedLength = True com FilePut,você precisa fazer o mesmo com FileGet,e você precisa certificar-se de que a sequência de caracteres é inicializada com o tamanho esperado.

Modo Aleatório

Para arquivos abertos no modo Random as seguintes regras se aplicam:

Se o comprimento dos dados que estão sendo escritos for menor do que o comprimento especificado na cláusula RecordLength da função FileOpen,FilePut escreverá registros subsequentes nos limites de comprimento de registro.O espaço entre o final de um registro e o início do próximo registro é preenchido com o conteúdo existente no buffer de arquivo.Porque a quantidade de dados a serem preenchidos não pode ser determinada com certeza, ela é geralmente uma boa ideia para que o comprimento do registro coincida com o tamanho dos dados que estão sendo gravados.Se o comprimento dos dados que estão sendo gravados for maior do que o comprimento especificado na cláusula RecordLength da função FileOpen, uma exceção será lançada.
Se a variável que está sendo gravada for uma sequência de caracteres, FilePut grava um descritor de dois bytes que contém o comprimento da sequência de caracteres e em seguida, grava os dados que vão para a variável.Portanto, o comprimento do registro especificado pela cláusula RecordLengthou função FileOpen deve ser pelo menos dois bytes maior do que o comprimento real da sequência de caracteres.
Se a variável que está sendo gravada for um objeto que contém um tipo numérico, FilePut grava dois bytes que identificam o VarType do objeto e, em seguida, grava a variável.Por exemplo, ao escrever um objeto que contém um número inteiro, FilePut grava seis bytes: dois bytes, identificando o objeto sistema autônomo VarType(3) (Integer) e quatro bytes que contém sistema autônomo dados. O comprimento do registro especificado pelo parâmetro RecordLength na função FileOpen deve ser pelo menos dois bytes maior do que o número real de bytes requeridos para armazenar a variável.
Se a variável que está sendo gravada for um objeto contendo uma sequência de caracteres, FilePut grava um descritor de dois bytes que identifica o VarType(8 ) do objeto, um descritor de dois bytes indicando o comprimento da sequência de caracteres e em seguida, grava o dados de sequência.O comprimento do registro especificado pelo parâmetro RecordLength na função FileOpen deve ser pelo menos quatro bytes maior do que o comprimento real da sequência de caracteres.Se você desejar ler uma sequência de caracteres sem o descritor, você deve passar True para o parâmetro StringIsFixedLength, e a sequência de caracteres que você ler deve ser do tamanho correto.
Se a variável que está sendo gravada for uma matriz, então você pode escolher se escreve ou não um descritor para o tamanho e dimensões da matriz.Visual Basic 6.0 e versões anteriores gravam o descritor de arquivo para uma matriz dinâmica, mas não para uma matriz de tamanho fixo.Visual Basic 2005 tem como padrão não gravar o descritor.Para gravar o descritor, defina o parâmetro ArrayIsDynamic como True.Ao escrever a matriz, você precisa corresponder a maneira segundo a qual a matriz será lida; se ela será ser lida com o descritor, então você precisará escrever o descritor.O descritor especifica a classificação de matriz, o tamanho e os limites inferiores para cada posição.Seu comprimento é 2, além de 8 vezes igual ao número de dimensões: (2 + 8 * NumberOfDimensions).O comprimento do registro especificado pela cláusula RecordLength na função FileOpen deve ser maior ou igual à soma de todos os bytes necessários para gravar os dados da matriz e o descritor da matriz.Por exemplo, a seguinte declaração de matriz necessitará de 118 bytes quando a matriz for gravada no disco:
```
Dim MyArray(4,9) As Integer
```
Se a variável que está sendo gravada for qualquer outro tipo de variável (não uma a sequência de caracteres de comprimento variável ou um objeto), FilePut grava somente os dados da variável.O comprimento do registro especificado pela cláusula RecordLength na função FileOpen deve ser maior ou igual ao comprimento dos dados que estão sendo gravados.
FilePut grava os elementos de estruturas como se cada um fosse escrito individualmente, exceto se não há nenhum preenchimento entre elementos.O atributo VBFixedString pode ser aplicado a campos de sequência de caracteres nas estruturas para indicar o tamanho da sequência de caracteres quando gravadas em disco.

Observação:

String campos que tenham mais bytes do que o especificado pela VBFixedString atributo são truncados quando gravados em disco,

Observação:
String campos que tenham mais bytes do que o especificado pela VBFixedString atributo são truncados quando gravados em disco,

Modo Binário

Para arquivos abertos no modo Binary, a maioria das regras de modo Random se aplicam, com algumas exceções.As seguintes regras para arquivos abertos no modo Binary diferem das regras do modo Random :

The RecordLength cláusula de FileOpen função não tem efeito. FilePut grava todas as variáveis de disco de forma contígua, ou seja, com nenhum preenchimento entre registros.
Para qualquer matriz que não seja uma matriz em uma estrutura, FilePut escreve apenas os dados.Nenhum descritor é escrito.
FilePut escreve sequências de caracteres de comprimento variável que não são elementos das estruturas sem o descritor de comprimento dois bytes.O número de bytes escritos é igual ao número de caracteres na sequência.Por exemplo, as instruções a seguir gravam 11 bytes no arquivo número 1:
```
Dim hellow As String = "Hello World"
FilePut(1,hellow)
```
Escrever em um arquivo com a função FilePut requer acesso Write da enumeração FileIOPermissionAccess.

Exemplo

Este exemplo usa a função FilePut para gravar dados em um arquivo.Cinco registros da estrutura Person são gravados no arquivo.

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