Syntax: PUT #Dateinummer, [Position], Daten [, Menge]
Typ: Anweisung/Funktion
Kategorie: Datei
PUT schreibt Daten in eine Datei, die im BINARY- oder RANDOM-Modus geöffnet wurde.
- 'Dateinummer' ist die Nummer, die beim Öffnen der Datei mit OPEN zugewiesen wurde.
- 'Position' ist die Position innerhalb der Datei, an die geschrieben werden soll. Für BINARY-Dateien ist es die Nummer des Bytes, für RANDOM-Dateien ist das die Nummer des Datensatzes. Wird dieser Parameter ausgelassen, schreibt FreeBASIC an die Position des Dateizeigers. Diese ist abhängig von den letzten Lese-/Schreibzugriffen auf die Datei und der SEEK-Anweisung. Zeigt die aktuelle Position innerhalb der Datei auf eine bereits beschriebene Position, so wird diese überschrieben. Direkt nach dem Öffnen zeigt der Dateizeiger immer auf die erste Stelle in der Datei.
- 'Daten' ist ein Wert, eine Variable oder ein Ausdruck. Auch Arrays und UDTs (user defined Types; siehe TYPE) können geschrieben werden.
- 'Menge' wird eingesetzt, sobald die Daten aus einem ALLOCATE-Puffer geschrieben werden sollen. Dadurch wird PUT mitgeteilt, wie viele Speicherstellen aus dem Puffer in die Datei geschrieben werden sollen. PUT schreibt Menge * SizeOf(Puffer_Datentyp) Bytes. Wird 'Menge' ausgelassen, nimmt FreeBASIC automatisch 1 an. PUT schreibt also eine einzelne Speicherstelle in die Datei (entspricht LEN(DatenPufferTyp) Bytes, also z.B. 4 Bytes bei einem INTEGER PTR). Bei anderen Datentypen als ALLOCATE-Datenpuffern wird der Parameter 'Menge' ignoriert.
- Wird PUT als Funktion eingesetzt, ist der Rückgabewert eine der FreeBASIC-Fehlernummern. In diesem Fall müssen die Parameter in Klammern gesetzt werden; die Syntax lautet also:
Variable = PUT(#Dateinummer, [Position], Daten [, Menge])
Der RANDOM-Modus wird nur noch selten verwendet; die Verwendung sequentieller Modi (INPUT, OUTPUT und APPEND) bzw. des BINARY-Modus hat sich als sinnvoller herausgestellt.
Es wird nicht garantiert, das FreeBASIC RANDOM-Daten im selben Umfang wie QB unterstützt.
Im BINARY-Modus richtet sich die Anzahl der zu schreibenden Bytes nach dem Datentyp der Variable, in die die Datei geschrieben wird:
- BYTE und UBYTE - 1 Byte (8 bit)
- SHORT und USHORT - 2 Byte (16 bit)
- INTEGER, UINTEGER, LONG und ULONG - 4 Bytes (32 bit)
- LONGINT und ULONGINT - 8 Bytes (64 bit)
- STRINGs (fester und variabler Länge) - lässt sich mit LEN ermitteln
- ZSTRINGs (fester Länge) - gelesen werden LEN(ZstringVariable) - 1 Bytes. Ein Byte wird als Terminierungs-Byte benötigt.
- ZSTRING PTR - werden wie ALLOCATE-Puffer behandelt (siehe unten).
- WSTRINGs (fester Länge) - gelesen werden wie bei ZSTRINGs LEN(WstringVariable) - 1 Bytes. Ein Byte wird als Terminierungs-Byte benötigt.
- ALLOCATE-Puffer - Der Parameter 'Menge' gibt an, wie viele Bytes gelesen werden. Achten Sie darauf, dass genügend Speicherplatz reserviert wurde!
- Arrays - Indexzahl * LEN(Datentyp)
- UDTs - Lässt sich mit LEN ermitteln
Beispiel 1:
Dim buffer AS String
Dim f AS Integer = Freefile
Open "file.ext" For Binary As #f
buffer = "hello world within a file."
Put #f, , buffer
Close #f
Um Arrays oder UDTs zu schreiben, muss der Bezeichner der entsprechenden Variable ohne Index- oder Recordangabe gegeben sein.
Beispiel 2:
Type UDT
a As Integer
b As Single
c As String * 5
END TYPE
Dim f AS Integer = Freefile
Open "file.ext" For Binary As #f
Dim outarray(5) As Integer
Dim outUDT As UDT
Put #f, , outarray()
Put #f, , outUDT
Close #f
Bei der Verwendung von Datenpuffern, deren Pointer angegeben ist, verwenden Sie die Ziel-des-Pointers-Syntax
*Pointer
oder
Pointer[index]
Außerdem müssen Sie angeben, wie viele Bytes geschrieben werden sollen. Dazu dient der Parameter 'Menge'.
Beispiel 3:
Dim f AS INTEGER = Freefile
Open "file.ext" For Binary As #f
Dim x As Byte Ptr
x = Allocate(8)
Put #f, 1, *x , 4
Put #f, 5, x[4], 4
DeAllocate x
Close #f
Achten Sie bei der Verwendung von PUT sehr genau auf die Datentypen!
Beispiel 4:
Dim v1 As Byte, v2 As String * 2
Dim f As integer
v1 = 33
v2 = "33"
f = FreeFile
Open "file.ext" For Binary As #f
Put #f, , v1
Put #f, , v2
Close #f
Open "file.ext" For Binary As #f
Get #f, , v2
Get #f, , v1
Close #f
Print v1, v2
Sleep
Ausgabe:
51 !3
Wie Sie sehen, wird in die Datei beim ersten Zugriff zuerst ein BYTE-Wert und anschließend ein 2-Byte-STRING geschrieben. Beim zweiten Zugriff wird zuerst ein 2-Byte-STRING und anschließend ein BYTE-Wert eingelesen. Ergebnis ist, dass nicht - wie anzunehmen - wieder zweimal die Ausgabe '33' erfolgt, sondern nur Datenmüll auf dem Bildschirm erscheint. Obwohl die Informationen fehlerfrei gelesen wurden, kann mit den Informationen nicht gearbeitet werden, da sie nach dem Lesen auf die falsche Art und Weise behandelt werden.
Werden beim Lesezugriff die beiden GET-Zeilen vertauscht, so erfolgt die korrekte Ausgabe:
33 33
Die Ursache hierfür liegt darin, dass im BINARY- und RANDOM-Modus (mit denen GET und PUT ja arbeiten) die Daten nicht in einem für Menschen lesbaren Format abgelegt werden, sondern binär behandelt werden, d.h. so geschrieben werden, wie sie vom Prozessor behandelt werden. Hierbei existieren Unterschiede zwischen der Behandlungsweise von Zeichenketten (des STRINGs) und Zahlen (des BYTE-Werts).
Unterschiede zu QB:
- PUT kann auch als Funktion eingesetzt werden.
- Ganze Arrays und UDTs können geschrieben werden.
- Die Verwendung von ALLLOCATE-Datenpuffern ist möglich.
Unterschiede zu früheren Versionen von FreeBASIC:
- PUT kann seit FreeBASIC v0.13 als Funktion eingesetzt werden.
- Seit FreeBASIC v0.10 können ganze Arrays gelesen werden.
Siehe auch:
PUT (Grafik), OPEN, BINARY, RANDOM, GET #, Dateien (Files)