Funzione FilePut

Articolo
09/12/2008

Aggiornamento: novembre 2007

Scrive dati da una variabile in un file su disco.

Nelle operazioni di I/O dei file la funzionalità My offre un più elevato livello di produttività e prestazioni rispetto a FilePut. Per ulteriori informazioni, vedere Oggetto 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
)

Parametri

FileNumber
Obbligatorio. Qualsiasi numero di file valido.
Value
Obbligatorio. Nome di variabile valido contenente dati scritti su disco.
RecordNumber
Facoltativo. Numero di record (file aperti in modalità Random) o di byte (file aperti in modalità Binary) da cui inizia la scrittura.
ArrayIsDynamic
Facoltativo. Valido solo per la scrittura di una matrice. Consente di specificare se la matrice è dinamica e se scrivere un descrittore di matrice per la stringa di definizione della lunghezza.
StringIsFixedLength
Facoltativo. Valido solo per la scrittura di una stringa. Consente di specificare se scrivere un descrittore a due byte della lunghezza della stringa per la stringa nel file. Il valore predefinito è False.

Eccezioni

Tipo di eccezione	Numero di errore	Condizione
ArgumentException	63	RecordNumber < 1 e diverso da -1.
IOException	52	FileNumber non esiste.
IOException	54	Modalità di accesso ai file non valida.

Se si esegue l'aggiornamento delle applicazioni Visual Basic 6.0 che utilizzano la gestione degli errori non strutturata, vedere la colonna "Numero di errore". È possibile confrontare il numero di errore con la Proprietà Number (oggetto Err). Se possibile, tuttavia, si consiglia di sostituire il controllo dell'errore con la procedura illustrata nella sezione Cenni preliminari sulla gestione strutturata delle eccezioni per Visual Basic.

Note

FilePut è valido solo in modalità Random e Binary.

Per leggere da un file i dati scritti mediante FilePut, viene in genere utilizzato FileGet.

Il primo record o byte di un file corrisponde alla posizione 1, il secondo alla posizione 2 e così via. Se RecordNumber viene omesso, verrà scritto il record o il byte successivo all'ultima funzione FileGet o FilePut oppure quello indicato dall'ultima funzione Seek.

L'argomento StringIsFixedLength controlla se la funzione interpreta le stringhe a lunghezza variabile o fissa. FilePut non scrive il descrittore della lunghezza quando l'argomento è True. Se si utilizza StringIsFixedLength = True con FilePut, è necessario seguire lo stesso procedimento con FileGet e assicurarsi che la stringa venga inizializzata alla lunghezza prevista.

Modalità Random

Per i file aperti in modalità Random vengono adottati i seguenti criteri:

Se la lunghezza dei dati scritti è inferiore alla lunghezza specificata nella clausola RecordLength della funzione FileOpen, i record successivi verranno comunque scritti da FilePut entro i limiti della lunghezza dei record. Lo spazio compreso tra la fine di un record e l'inizio del record successivo verrà occupato dal contenuto esistente del buffer del file. Dal momento che non è possibile stabilire con precisione la quantità dei dati di spaziatura interna, è in genere consigliabile verificare che la lunghezza del record corrisponda a quella dei dati da scrivere. Se la lunghezza dei dati da scrivere è maggiore di quanto specificato nella clausola RecordLength della funzione FileOpen, verrà generata un'eccezione.
Se la variabile da scrivere è una stringa, FilePut scriverà prima un descrittore a 2 byte contenente la lunghezza della stringa, quindi i dati da trasferire nella variabile. È pertanto necessario che la lunghezza del record specificata dalla clausola RecordLength della funzione FileOpen sia maggiore di almeno due byte rispetto alla lunghezza effettiva della stringa.
Se la variabile da scrivere è un oggetto contenente un tipo numerico, FilePut scriverà due byte che identificano il VarType dell'oggetto e quindi la variabile. Durante la scrittura di un oggetto contenente un valore integer, ad esempio, FilePut scrive sei byte: due byte che identificano l'oggetto come VarType(3) (Integer) e quattro byte contenenti i dati. La lunghezza del record specificata dal parametro RecordLength nella funzione FileOpen deve essere maggiore di almeno due byte rispetto al numero effettivo di byte necessari per archiviare la variabile.
Se la variabile da scrivere è un oggetto contenente una stringa, FilePut scriverà un descrittore a due byte che identifichi il VarType(8) dell'oggetto, un descrittore a due byte che indichi la lunghezza della stringa, quindi i dati della stringa. È quindi necessario che la lunghezza del record specificata dal parametro RecordLength della funzione FileOpen sia maggiore di almeno quattro byte rispetto alla lunghezza effettiva della stringa. Se si desidera inserire una stringa senza descrittore, è necessario passare True al parametro StringIsFixedLength. È inoltre necessario che la lunghezza della stringa letta sia corretta.
Se la variabile da scrivere è una matrice, è possibile scegliere se scrivere o meno un descrittore delle dimensioni della matrice. In Visual Basic 6.0 e nelle versioni precedenti era consentita la scrittura di un descrittore del file per una matrice dinamica ma non per una matrice di dimensioni fisse. L'impostazione predefinita di Visual Basic 2005 non consente la scrittura di un descrittore. Per scrivere il descrittore, impostare il parametro ArrayIsDynamic su True. Quando si scrive la matrice è necessario tenere conto delle relative modalità di lettura: se verrà letta con il descrittore, sarà necessario scriverlo. Il descrittore specifica il numero di indici della matrice, la dimensione e i limiti inferiori di ogni indice. La lunghezza è pari a 2 più 8 volte il numero delle dimensioni: (2 + 8 * NumberOfDimensions). È necessario che la lunghezza del record specificata nella clausola RecordLength della funzione FileOpen sia maggiore o uguale alla somma di tutti i byte richiesti per scrivere i dati e il descrittore della matrice. La scrittura su disco della matrice con la seguente dichiarazione richiede, ad esempio, 118 byte.
```
Dim MyArray(4,9) As Integer
```
Se la variabile scritta è di qualsiasi altro tipo, ovvero né una stringa di lunghezza variabile né un oggetto, FilePut scriverà solo i dati della variabile. È necessario che la lunghezza del record specificata nella clausola RecordLength della funzione FileOpen sia maggiore o uguale alla lunghezza dei dati da scrivere.
Gli elementi delle strutture vengono scritti mediante FilePut come se ciascuno di essi venisse scritto singolarmente, con la sola differenza che in questo caso non vi è spaziatura interna tra gli elementi. È possibile applicare l'attributo VBFixedString ai campi stringa nelle strutture per indicare le dimensioni della stringa in fase di scrittura su disco.

Nota:

I campi stringa contenenti un numero di byte superiore a quanto specificato nell'attributo VBFixedString vengono troncati in fase di scrittura su disco.

Nota:
I campi stringa contenenti un numero di byte superiore a quanto specificato nell'attributo VBFixedString vengono troncati in fase di scrittura su disco.

Modalità Binary

Nel caso dei file aperti in modalità Binary risulta valida la maggior parte delle regole della modalità Random, con qualche eccezione. Le regole relative ai file aperti in modalità Binary differiscono dalle regole relative alla modalità Random :

La clausola RecordLength nella funzione FileOpen non ha effetto. FilePut scrive tutte le variabili su disco in successione, ovvero senza spaziatura interna tra i record.
In caso di matrici non comprese in una struttura, FilePut scriverà solo i dati. Non viene scritto alcun descrittore.
Con la funzione FilePut vengono scritte stringhe di lunghezza variabile che non sono elementi di strutture, prive del descrittore di lunghezza a 2 byte. Il numero di byte scritti equivale al numero di caratteri della stringa. Le istruzioni seguenti, ad esempio, consentono di scrivere 11 byte nel file numero 1:
```
Dim hellow As String = "Hello World"
FilePut(1,hellow)
```
La scrittura in un file con la funzione FilePut richiede l'accesso Write dall'enumerazione FileIOPermissionAccess.

Esempio

Nell'esempio seguente la funzione FilePut viene utilizzata per scrivere i dati in un file. Nel file vengono scritti cinque record della struttura 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