FilePut (Función)

Artículo
10/07/2008

Actualización: noviembre 2007

Escribe datos de una variable en un archivo de disco.

La característica My proporciona mayor productividad y rendimiento en las operaciones de E/S del archivo que si se utiliza FilePut. Para obtener más información, vea My.Computer.FileSystem (Objeto).

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
Obligatorio. Cualquier número de archivo válido.
Value
Obligatorio. Nombre válido de variable que contiene los datos escritos en disco.
RecordNumber
Opcional. Número de registro (archivos en modo Random) o número de byte (archivos en modo Binary) en el que se comienza a escribir.
ArrayIsDynamic
Opcional. Sólo se aplica cuando se escribe una matriz. Especifica si se ha de tratar a la matriz como dinámica y si se ha de escribir un descriptor de matriz para la cadena que detalla la longitud.
StringIsFixedLength
Opcional. Sólo se aplica cuando se escribe una cadena. Especifica si se escribe en el archivo un descriptor de longitud de cadena de dos bytes para la cadena. El valor predeterminado es False.

Excepciones

Tipo de excepción	Número de error	Condición
ArgumentException	63	RecordNumber < 1 y distinto de -1.
IOExceptio	52	FileNumber no existe.
IOException	54	El modo de archivo no es válido.

Consulte la columna "Número de error" si está actualizando aplicaciones de Visual Basic 6.0 que utilizan el control de errores no estructurado. (Se puede comparar el número de error con respecto a Number (Propiedad, objeto Err)). Sin embargo, siempre que sea posible, debe considerarse la posibilidad de sustituir dicho control de errores por Información general sobre el control estructurado de excepciones de Visual Basic.

Comentarios

FilePut sólo es válido en los modos Random y Binary.

Los datos escritos con FilePut normalmente se leen desde un archivo con FileGet.

El primer registro o byte de un archivo se encuentra en la posición 1, el segundo en la posición 2 y así sucesivamente. Si se omite RecordNumber, se escribe el registro o byte que sigue a la última función FileGet o FilePut, o al que señale la última función Seek.

El argumento StringIsFixedLength controla si la función interpreta las cadenas como cadenas de longitud fija o variable. FilePut no escribe el descriptor de longitud cuando el argumento es True. Si se utiliza StringIsFixedLength = True con FilePut, deberá hacer lo mismo con FileGet y deberá comprobar también que la cadena se inicializa con la longitud esperada.

Modo Random

Con los archivos abiertos en modo Random, se aplican las siguientes reglas:

Si la longitud de los datos que se estén escribiendo es menor que la especificada en la cláusula RecordLength de la función FileOpen, FilePut escribirá los registros posteriores en los límites de longitud de registro. El espacio comprendido entre el final de un registro y el principio del siguiente se rellena con el contenido existente del búfer del archivo. Como no se puede determinar con seguridad la cantidad de datos de relleno, suele ser una buena idea hacer que la longitud del registro coincida con la de los datos que se estén escribiendo. Si la longitud de los datos que se escriben es mayor que la especificada en la cláusula RecordLength de la función FileOpen, se producirá una excepción.
Si la variable que se está escribiendo es una cadena, FilePut escribirá un descriptor de 2 bytes con la longitud de la cadena y, a continuación, escribirá los datos de la variable. Por tanto, la longitud de registro especificada por la cláusula RecordLength en la función FileOpen debe ser, como mínimo, 2 bytes mayor que la longitud real de la cadena.
Si la variable que se está escribiendo es un objeto que contiene un tipo numérico, FilePut escribirá dos bytes para identificar el VarType del objeto y, a continuación, escribirá la variable. Por ejemplo, al escribir un objeto con un entero, FilePut escribe seis bytes: dos bytes identifican el objeto como VarType(3) (Integer) y los otros cuatro bytes contienen los datos. La longitud de registro especificada por el parámetro RecordLength en la función FileOpen debe ser, como mínimo, 2 bytes mayor que el número real de bytes necesario para almacenar la variable.
Si la variable que se está escribiendo es un objeto que contiene una cadena, FilePut escribirá un descriptor de dos bytes para identificar el VarType(8) del objeto, un descriptor de dos bytes para indicar la longitud de la cadena y, por último, escribirá los datos de la cadena. La longitud de registro especificada por el parámetro RecordLength en la función FileOpen debe ser, como mínimo, cuatro bytes mayor que la longitud real de la cadena. Si desea escribir una cadena sin el descriptor, debe pasar un valor True al parámetro StringIsFixedLength y la cadena que lea debe tener la longitud correcta.
Si la variable que se esté escribiendo es una matriz, podrá elegir si desea escribir o no un descriptor con el tamaño y dimensiones de la matriz. Visual Basic 6.0 y otras versiones anteriores escribían el descriptor de archivos de las matrices dinámicas, pero no el de las matrices de tamaño fijo. De manera predeterminada, Visual Basic 2005 no escribe el descriptor. Para escribirlo, establezca el parámetro ArrayIsDynamic en True. Al escribir la matriz, deberá detallar la forma en que se efectuará su lectura: si va a leerse con el descriptor, entonces deberá escribirlo. El descriptor especifica tanto el rango de la matriz, como el tamaño y los límites inferiores de cada rango. Su longitud es igual a 2 más 8 veces el número de dimensiones: (2 + 8 * NumberOfDimensions). La longitud de registro especificada por la cláusula RecordLength en la función FileOpen debe ser mayor o igual que la suma de todos los bytes necesarios para escribir los datos y el descriptor de la matriz. Por ejemplo, la siguiente declaración de matriz requiere 118 bytes cuando la matriz se escribe en disco:
```
Dim MyArray(4,9) As Integer
```
Si la variable que se esté escribiendo es de cualquier otro tipo (no una cadena de longitud variable ni un objeto), FilePut sólo escribirá los datos de la variable. La longitud de registro especificada por la cláusula RecordLength en la función FileOpen debe ser mayor o igual que la longitud de los datos que se estén escribiendo.
FilePut escribe elementos de estructuras como si cada uno de ellos estuviese escrito por separado, con la excepción de que no existe relleno entre ellos. El atributo VBFixedString puede aplicarse a campos de cadena de las estructuras para indicar el tamaño de la cadena cuando se escribe en disco.

Nota:

Los campos de cadena que tienen más bytes de lo especificado por el atributo VBFixedString se trunca cuando se escribe en el disco.

Nota:
Los campos de cadena que tienen más bytes de lo especificado por el atributo VBFixedString se trunca cuando se escribe en el disco.

Modo Binary

La mayor parte de las reglas de modo Random se aplican a los archivos abiertos en modo Binary, con contadas excepciones. Las reglas siguientes para los archivos abiertos en modo Binary difieren de las reglas de modo Random :

La cláusula RecordLength de la función FileOpen no tiene ningún efecto. FilePut escribe todas las variables en el disco una detrás de otra, es decir, sin dejar relleno entre los registros.
En el caso de matrices no asociadas a estructuras, FilePut escribirá únicamente los datos. No se escribirá ningún descriptor.
FilePut escribe las cadenas de longitud variable que no sean elementos de estructuras sin el descriptor de longitud de dos bytes. El número de bytes escrito es igual al número de caracteres de la cadena. Por ejemplo, en las siguientes instrucciones se escribe 11 bytes en el archivo número 1:
```
Dim hellow As String = "Hello World"
FilePut(1,hellow)
```
Para escribir en un archivo con la función FilePut, es necesario tener acceso de tipo Write desde la enumeración FileIOPermissionAccess.

Ejemplo

En este ejemplo se utiliza la función FilePut para escribir datos en un archivo. En el archivo se escriben cinco registros de la estructura 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