FilePut-Funktion

Artikel
09/02/2008

Aktualisiert: November 2007

Schreibt Daten aus einer Variablen in eine Datei auf einem Datenträger.

Das My-Feature ermöglicht bei Datei-E/A-Vorgängen höhere Produktivität und Leistung als FilePut. Weitere Informationen hierzu finden Sie unter My.Computer.FileSystem-Objekt.

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
)

Parameter

FileNumber
Erforderlich. Beliebige gültige Dateinummer.
Value
Erforderlich. Gültiger Variablenname, der auf den Datenträger geschriebene Daten enthält.
RecordNumber
Optional. Datensatznummer (für Dateien im Random-Modus) oder Bytenummer (für Dateien im Binary-Modus), an der der Schreibvorgang beginnt.
ArrayIsDynamic
Optional. Gilt nur beim Schreiben eines Arrays. Gibt an, ob das Array als dynamisches Array betrachtet werden soll und ob für die Zeichenfolge ein Arraydeskriptor mit Längenbeschreibung geschrieben wird.
StringIsFixedLength
Optional. Gilt nur beim Schreiben einer Zeichenfolge. Gibt an, ob ein 2-Byte-Längendeskriptor für die Zeichenfolge in die Datei geschrieben werden soll. Die Standardeinstellung ist False.

Ausnahmen

Ausnahmetyp	Fehlernummer	Bedingung
ArgumentException	63	RecordNumber < 1 und nicht gleich -1.
IOException	52	FileNumber ist nicht vorhanden.
IOException	54	Dateimodus ist ungültig.

Beachten Sie die Spalte "Fehlernummer", wenn Sie Visual Basic 6.0-Anwendungen aktualisieren, die eine unstrukturierte Fehlerbehandlung verwenden. (Sie können die Fehlernummer mit der Number-Eigenschaft (Err-Objekt) vergleichen.) Wenn möglich, sollten Sie jedoch erwägen, eine solche Fehlersteuerung durch eine Übersicht über die strukturierte Ausnahmebehandlung für Visual Basic zu ersetzen.

Hinweise

FilePut ist nur im Random-Modus und im Binary-Modus gültig.

Daten, die mit FilePut geschrieben worden sind, werden normalerweise mit FileGet-aus der Datei gelesen.

Der erste Datensatz oder das erste Byte einer Datei hat die Position 1, der zweite Datensatz bzw. das zweite Byte die Position 2 usw. Wenn Sie RecordNumber nicht angeben, wird der Datensatz bzw. das Byte geschrieben, der bzw. das auf die letzte FileGet-Funktion oder FilePut-Funktion folgt oder auf den bzw. das die letzte Seek-Funktion zeigt.

Das StringIsFixedLength-Argument steuert, ob die Funktion Zeichenfolgen als Zeichenfolgen mit variabler oder mit fester Länge interpretiert. FilePut schreibt den Längendeskriptor nicht, wenn das Argument True ist. Wenn Sie für FilePut das StringIsFixedLength-Argument mit dem Wert True verwenden, müssen Sie dasselbe Argument für FileGet verwenden und sicherstellen, dass die Zeichenfolge mit der erwarteten Länge initialisiert wird.

Random-Modus

Für Dateien, die im Random-Modus geöffnet werden, gelten die folgenden Regeln:

Unterschreitet die Länge der geschriebenen Daten die in der RecordLength-Klausel der FileOpen-Funktion festgelegte Länge, so beginnen mit FilePut geschriebene nachfolgende Datensätze trotzdem immer an der durch die Datensatzlänge festgelegten Grenze. Der freie Raum zwischen dem Ende eines Datensatzes und dem Anfang des nächsten Datensatzes wird mit dem bestehenden Inhalt des Dateipuffers aufgefüllt. Da die Länge der Fülldaten nicht mit Sicherheit bestimmt werden kann, sollte die Datensatzlänge mit der Länge der geschriebenen Daten immer genau übereinstimmen. Wenn die Länge der geschriebenen Daten die in der RecordLength-Klausel der FileOpen-Funktion festgelegte Länge überschreitet, wird eine Ausnahme ausgelöst.
Wenn es sich bei der geschriebenen Variablen um eine Zeichenfolge handelt, so schreibt FilePut zunächst einen 2-Byte-Deskriptor mit der Länge der Zeichenfolge und dann den eigentlichen Inhalt der Variablen. Daher muss die in der RecordLength-Klausel der FileOpen-Funktion festgelegte Datensatzlänge mindestens 2 Bytes größer sein als die tatsächliche Länge der Zeichenfolge.
Wenn es sich bei der geschriebenen Variablen um ein Objekt mit einem numerischen Typ handelt, werden von FilePut zwei Bytes, die den VarType des Objekts identifizieren, und anschließend die Variable geschrieben. Beispiel: Bei einem Objekt, das eine ganze Zahl enthält, schreibt FilePut sechs Bytes: zwei Bytes zur Identifizierung des Objekts als VarType(3) (Integer) und vier Bytes mit den Daten. Die im RecordLength-Parameter der FileOpen-Funktion angegebene Datensatzlänge muss also mindestens zwei Bytes größer sein als die tatsächlich zum Speichern der Variablen benötigte Anzahl von Bytes.
Wenn es sich bei der geschriebenen Variablen um ein Objekt mit einer Zeichenfolge handelt, schreibt FilePut einen 2-Byte-Deskriptor, der den VarType(8) des Objekts identifiziert, einen 2-Byte-Deskriptor mit der Längenangabe der Zeichenfolge und anschließend die Zeichenfolgendaten. Daher muss die im RecordLength-Parameter der FileOpen-Funktion festgelegte Datensatzlänge mindestens 4 Bytes größer sein als die tatsächliche Länge der Zeichenfolge. Wenn Sie eine Zeichenfolge ohne Deskriptor einlesen möchten, sollten Sie True an den StringIsFixedLength-Parameter übergeben, und die Zeichenfolge, in die Sie einlesen, sollte die richtige Länge aufweisen.
Wenn es sich bei der geschriebenen Variablen um ein Array handelt, haben Sie die Möglichkeit, einen Deskriptor mit Größe und Dimensionen des Arrays zu schreiben. In Visual Basic 6.0 und früheren Versionen wurde ein Dateideskriptor nur für dynamische Arrays und nicht für Arrays mit festgelegter Größe geschrieben. In Visual Basic 2005 wird der Deskriptor standardmäßig nicht geschrieben. Zum Schreiben des Deskriptors legen Sie für den ArrayIsDynamic-Parameter True fest. Beim Schreiben des Arrays muss festgelegt werden, wie es gelesen wird. Für Arrays, die mit Deskriptor gelesen werden, muss ein Deskriptor geschrieben werden. Der Deskriptor gibt den Rang des Arrays, die Größe und die Untergrenze jedes Ranges an. Seine Länge entspricht 2 plus 8 Mal die Anzahl von Dimensionen: (2 + 8 * NumberOfDimensions). Die durch die RecordLength-Klausel der FileOpen-Funktion angegebene Datensatzlänge muss größer oder gleich der Summe aller Bytes sein, die erforderlich sind, um die Daten des Arrays und den Arraydeskriptor zu schreiben. Die folgende Arraydeklaration erfordert z. B. 118 Bytes, wenn das Array auf einen Datenträger geschrieben wird.
```
Dim MyArray(4,9) As Integer
```
Wenn die geschriebene Variable einen anderen Typ, d. h. weder Zeichenfolge variabler Länge noch Objekt, hat, schreibt FilePut nur die eigentlichen Daten der Variablen. Die in der RecordLength-Klausel der FileOpen-Funktion angegebene Datensatzlänge muss also mindestens so groß sein wie die Länge der geschriebenen Daten.
FilePut schreibt die Elemente von Strukturen so, als ob sie einzeln angelegt würden, jedoch ohne Fülldaten zwischen den Elementen. Zeichenfolgenfelder in den Strukturen können mit dem VBFixedString-Attribut versehen werden, das die Größe der Zeichenfolge beim Schreiben auf den Datenträger angibt.

Hinweis:

Zeichenfolgenfelder, die mehr Bytes enthalten als durch das VBFixedString-Attribut angegeben, werden beim Schreiben auf den Datenträger abgeschnitten.

Hinweis:
Zeichenfolgenfelder, die mehr Bytes enthalten als durch das VBFixedString-Attribut angegeben, werden beim Schreiben auf den Datenträger abgeschnitten.

Binary-Modus

Für Dateien, die im Binary-Modus geöffnet wurden, gelten bis auf wenige Ausnahmen die meisten der Random-Modusregeln. Die folgenden Regeln für Dateien, die im Binary-Modus geöffnet werden, unterscheiden sich von den Regeln für den Random -Modus:

Die RecordLength-Klausel der FileOpen-Funktion hat keine Wirkung. FilePut schreibt alle Variablen nacheinander auf den Datenträger, also ohne Zwischenräume zwischen Datensätzen aufzufüllen.
Bei jedem Array, das kein Array in einer Struktur ist, schreibt FilePut nur die Daten. Es wird kein Deskriptor geschrieben.
FilePut schreibt Zeichenfolgen variabler Länge, die keine Elemente in Strukturen sind, ohne den 2 Bytes großen Längendeskriptor. Daher entspricht die Anzahl geschriebener Bytes der Zeichenanzahl in der Zeichenfolge. Die folgenden Anweisungen schreiben z. B. 11 Bytes in die Datei mit der Dateinummer 1:
```
Dim hellow As String = "Hello World"
FilePut(1,hellow)
```
Um mit der FilePut-Funktion in eine Datei schreiben zu können, ist Write-Zugriff von der FileIOPermissionAccess-Enumeration erforderlich.

Beispiel

In diesem Beispiel werden mit der FilePut-Funktion Daten in eine Datei geschrieben. Insgesamt werden fünf Datensätze der Struktur Person in die Datei geschrieben.

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