9. Arbeit mit Dateien

^

9.1 Überblick zur Dateiarbeit

Für R-BASIC ist jede Datei zunächst eine einfache Abfolge von Bytes. Um auf die Daten in einer Datei zugreifen zu können, müssen Sie sie zuerst "öffnen" und nach Gebrauch wieder "schließen". Während die Datei geöffnet ist, erfolgt der Zugriff auf eine Datei über eine Variablen vom Typ FILE, die von FileOpen bzw. FileCreate geliefert wird. GEOS verwaltet außerdem einen "Dateizeiger", der die Position bestimmt, an der Daten gelesen oder geschrieben werden.

R-BASIC verfügt dabei über einige Möglichkeiten, die den meisten Programmiersprachen fehlen, wie z.B. das direkte Einfügen von Daten, ohne die darauf folgenden Daten zu überschreiben.

Hier finden Sie eine Übersicht über die Befehle zum Lesen aus und Schreiben von Daten in Dateien, die in diesem Kapitel behandelt werden.


Dateiattribute (Abschnitt 9.2)

DOS-Attribute

FileGetAttrs, FileSetAttrs : Lesen und setzen die "Standard-Attribute"
wie Archiv, schreibgeschützt usw.

FileGetTime, FileSetTime : Lesen und setzen das Datum der letzten Änderung.

FileSize liefert die aktuelle Dateigröße.

GEOS-Attribute

Zusätzlich zu den DOS-Attributen haben GEOS-Dateien weitere Attribute. R-BASIC unterstützt die folgenden Attribute:
Token : Dieses Attribut bestimmt das "Icon",
dass im GeoManager für diese Datei angezeigt wird.

Befehle: FileSetToken, FileGetToken

Creator : Erzeuger. Dieses Attribut enthält das Token des Programms,
das die Datei angelegt hat.

Befehle: FileSetCreator, FileGetCreator

Token und Creator werden jeweils in einer GeodeToken Struktur gespeichert.

CreationTime : Datum und Zeit, zu der die Datei angelegt wurde.

Befehle: FileSetCreationTime, FileGetCreationTime

Usernotes : Die Benutzer-Notizen. Ein String mit bis zu 99 Zeichen.

Befehle: FileSetUsernotes, FileGetUsernotes

Release : Dieses Attribut entspricht der Versionsnummer der Datei.
R-BASIC und auch der Uni-Installer entscheiden darüber, ob eine Datei neuer ist als eine andere gleichen namens.

Befehle: FileSetRelease, FileGetRelease

Protocol : Dieses Attribut beschreibt intern die "Fähigkeiten" einer Datei.

Befehle: FileSetProtocol, FileGetProtocol


Anlegen, Öffnen und Schließen von Dateien (Abschnitt 9.3)

FileOpen : Öffnet eine vorhandene Datei

FileCreate : Legt eine neu Datei an oder öffnet eine vorhandene

FileClose : Schließt eine Datei


Lesen und Schreiben von Daten - Binärdateien (Abschnitt 9.4)

FileRead, FileWrite und FileInsert sind Universalroutinen. Sie arbeiten mit allen Dateien und allen Typen von Variablen, einschließlich Strings und Strukturen zusammen. Für die Arbeit mit Textdateien (lesen und schreiben von Textzeilen) gibt es zusätzlich dazu spezialisierte Routinen (Abschnitt 9.5).

FileRead : Liest eine bestimmte Anzahl von Bytes aus einer Datei.

FileWrite : Schreibt eine bestimmte Anzahl von Bytes in eine Datei,
indem vorhandene Daten überschrieben werden. Bei Bedarf werden die Daten angehängt, d.h. die Datei wird verlängert.

FileInsert : Fügt eine bestimmte Anzahl von Bytes in eine Datei ein,
ohne das vorhandene Daten überschrieben werden. Die Datei wird dadurch automatisch verlängert. Dieser Befehl ist eine Besonderheit von R-BASIC, die meisten Programmiersprachen kennen ihn nicht.


Lesen und Schreiben von Daten - Textdateien (Abschnitt 9.5)

Diese Routinen sind auf Textzeilen, die durch ein Zeilenendezeichen abgeschlossen sind, spezialisiert. Das trifft für normale Textdateien zu. Zeilenendezeichen sind die ASCII-Codes 13 (Wagenrücklauf, Carriage return, CR) bzw. 10 (Zeilenvorschub, LineFeed, LF) oder eine Kombination davon, üblicherweise die Folge 13, 10 (CRLF).

FileReadLine$ : Liest eine Textzeile aus einer Datei.

FileWriteLine : Schreibt eine Textzeile, indem vorhandene Daten überschrieben werden.
Bei Bedarf wird die Textzeile angehängt, d.h. die Datei wird verlängert.

FileInsertLine : Schiebt eine Textzeile in die Datei ein. Die Datei wird dadurch verlängert.

FileReplaceLine : Ersetzt eine Textzeile in einer Datei durch eine andere.


Sonstige Funktionen (Abschnitt 9.6)

FileGetPos : Liest den aktuellen Dateizeiger.

FileSetPos : Setzt den Dateizeiger.

FileResize : Ändert die Größe einer Datei, indem Daten eingefügt oder gelöscht werden.

FileTruncate : Schneidet die Datei ab.

FileCommit : Stellt sicher, dass eventuell vom System gepufferte Daten sofort, d.h.
schon vor einem FileClose auf die Platte geschrieben werden.

^

9.2 Dateiattribute

Neben dem Namen besitzt jede Datei eine eine Reihe von zusätzlichen Eigenschaften, die sogenannten "Attribute". Es gibt zwei Gruppen von Attributen, die "Standard-Attribute", einschließlich Dateigröße und dem Datum der letzten Änderung, die bereits aus alten DOS-Tagen stammen, und die "GEOS-Attribute", die nur für GEOS-Dateien vorhanden sind.

Die meisten der in diesem Kapitel besprochenen Funktionen können sowohl mit offenen Dateien (referenziert über eine FILE-Variable) als auch mit geschlossenen Dateien (referenziert über ihren Namen) umgehen.

Die Standard-Attribute

Die Standardattribute existieren für JEDE Datei und sind als einzelne Bits in einem Byte definiert. Sie können mit FileGetAttrs gelesen und mit FileSetAttrs gesetzt werden. Es sind die folgenden Attribute definiert, die Zahlen in der ersten Spalte sind die Bit-Nummer und der dazugehörige Wert.

Tabelle

FileGetAttrs

Liefert die DOS-Standardattribute einer Datei. Die Attribute sind einzelne Bits und können mit AND bzw. OR - Verknüpfungen abgefragt werden.
Syntax: <numVar> = FileGetAttrs (fileName$)

oder:<numVar> = FileGetAttrs (<fh>)

fileName$: Name der Datei. Pfadangaben im Namen sind zulässig.

<fh>: Variable (oder Funktion) vom Typ FILE. Bezeichnet die Datei.

Die Systemvariable fileError wird gesetzt oder gelöscht.

Beispiel: 

DIM attrs AS word
attrs = FileGetAttrs ("info.txt")
IF attrs AND FA_READ_ONLY THEN Print "schreibgeschützt"

FileSetAttrs

Setzt die DOS-Standardattribute einer Datei. Die Attribute sind einzelne Bits und können mit AND bzw. OR verknüpft werden.
Syntax: FileSetAttrs fileName$ , attrs

fileName$: Name der Datei. Pfadangaben im Namen sind zulässig.

attrs: Neue Attribute

Die Systemvariable fileError wird gesetzt oder gelöscht. FileSetAttrs kann nicht mit einer offenen Datei verwendet werden.

Beispiele: 

! Setzen von FA_SYSTEM, löschen aller anderen Attribute
FileSetAttrs "liste.txt" , FA_SYSTEM

! Setzen von FA_SYSTEM unter Beibehaltung der anderen Attribute
DIM attrs
attrs = FileGetAttrs ( "liste.txt" )
FileSetAttrs  "liste.txt" , attrs OR FA_SYSTEM

FileGetTime

Liefert das Datum und die Uhrzeit der letzten Änderung einer Datei. Das Betriebssystem setzt diesen Wert jedes Mal, wenn der Dateiinhalt geändert wird.
Syntax: <time> = FileGetTime ( fileName$ )

oder: <time> = FileGetTime ( <fh> )

fileName$: Name der Datei. Pfadangaben im Namen sind zulässig.

<fh>: Variable (oder Funktion) vom Typ FILE. Bezeichnet die Datei.

<time>: Eine Variable vom Typ DateAndTime

Die Systemvariable fileError wird gesetzt oder gelöscht.

Beispiel: 

DIM time AS DateAndTime
  time  = FileGetTime  "info.txt"
  Print "Geändert am: "; FormatDate$(time);
  Print "um: "; FormatTime$(time)

FileSetTime

Verändert das Datum und die Uhrzeit der letzen Änderung einer Datei.

Achtung! Sie überschreiben hiermit den Wert, den das Betriebssystem automatisch vergibt. Wird die Datei anschließend nochmals geändert, überschreibt das Betriebssystem den Wert erneut.

Syntax: FileSetTime fileName$ , <time>

oder: FileSetTime <fh> , <time>

fileName$: Name der Datei. Pfadangaben im Namen sind zulässig.

<fh>: Variable (oder Funktion) vom Typ FILE. Bezeichnet die Datei.

<time>: Eine Variable vom Typ DateAndTime

Fehlerbedingung: Die Systemvariable fileError wird gesetzt oder gelöscht.

Beispiel: 

DIM time AS DateAndTime
time = FileGetTime ("info.txt")
time.year = 2001
FileSetTime "info.txt", time

FileSize

Liefert die aktuelle Größe der Datei in Bytes. Der zurückgegebene Wert liegt im Bereich von 0 bis 4294967295, da Dateien maximal 4 GByte groß werden können.
Syntax: <numVar> = FileSize (fileName$)

oder: <numVar> = FileSize (<fh>)

fileName$: Name der Datei. Pfadangaben im Namen sind zulässig.

<fh>: Variable (oder Funktion) vom Typ FILE. Bezeichnet die Datei.

Die Systemvariable fileError wird gesetzt oder gelöscht.

GEOS-Attribute

Zusätzlich zu den Standardattributen haben GEOS-Dateien weitere Attribute. R-BASIC unterstützt die wichtigen Attribute: Token (Anzeige-Icon), Creator (Icon des zugehörigen Programms), CreationTime (Datum der Dateierstellung), UserNotes (Benutzernotizen), Release (Versionsnummer) und Protocol. Diese werden im Dateikopf, den ersten 256 Byte der Datei gespeichert. Bei Verzeichnissen befinden sich diese Attribute in der @dirname.000 - Datei.

CreationTime wird ein einer DateAndTime Struktur gespeichert. 

STRUCT DateAndTime
  year AS WORD     ' Jahr (z.B. 2014)
  month AS WORD    ' Monat (1...12)
  day AS WORD      ' Tag (1 ... 31)
  hour AS WORD     ' Stunde (0 ... 23)
  minute AS WORD   ' Minute (0 ... 59)
  second AS WORD   ' Sekunde (0 ... 59)
END STRUCT
UserNotes ist ein String mit bis zu 99 Zeichen.

Token und Creator werden in einer Struktur gespeichert, die GeodeToken heißt und folgendermaßen definiert ist. Das Bild dazu befindet sich in der TokenDB-Datei. 

STRUCT GeodeToken
  manufid AS WORD  ' Manufacturer ID (Hersteller-Identifikation)
  tokenChars AS STRING(4)
END  STRUCT
Eine fehlerhafte Belegung der Werte für Token oder Creator kann die Arbeit mit der Datei unmöglich machen. Setzen Sie in diesem Fall einfach wieder den korrekten Wert.

Release und Protocol werden in einer Struktur gespeichert die ReleaseNumber heißt und folgendermaßen definiert ist. R-BASIC verwendet die ersten beiden Felder dieser Struktur auch für die Protokollnummer. 

STRUCT ReleaseNumber     ' Bedeutung der Felder:
  rnMajor as WORD        ' große, meist inkompatible Neuerungen
  rnMinor as WORD        ' kleinere, kompatible Neuerungen
  rnChange AS WORD       ' interne Änderungen
  rnEngineering as WORD  ' kleine interne Änderungen
End STRUCT
Tritt ein Fehler auf, z.B. weil die Datei nicht gefunden wird oder weil das Attribut nicht unterstützt wird, (weil es eine DOS-Datei ist), wird die Systemvariable fileError gesetzt. Im Erfolgsfall wird die fileError-Variable zurückgesetzt (d.h. mit Null belegt)

Die Bedeutung der Parameter der folgenden Übersicht und Beispiele sind weiter unten zu finden.

FileGetToken, FileSetToken

Liest bzw. setzt das "Token" der Datei.
Syntax: <token> = FileGetToken (ffileName$) ' Auslesen des Token
oder: <token> = FileGetToken (<fh>)

Syntax: FileSetToken fileName$, <token> ' Setzen des Token
oder: FileSetToken fh, <token>


FileGetCreator, FileSetCreator

Liest (FileGetCreator) oder setzt (FileSetCreator) das Creator-Token.
Syntax: <token> = FileGetCreator (fileName$) ' Auslesen des Creator-Token
oder: <token> = FileGetCreator (<fh>)

Syntax: FileSetCreator fileName$, <token> ' Setzen des Creator-Token
oder: FileSetCreator <fh> , <token>


FileGetCreationTime, FileSetCreationTime

Liest oder verändert das Datum, an dem die Datei angelegt wurde.
Syntax: <time> = FileGetCreationTime (fileName$) ' Auslesen der Erstellungszeit
oder: <time> = FileGetCreationTime (<fh>)

Syntax: FileSetCreationTime fileName$, <time> ' Setzen der Erstellungszeit
oder: FileSetCreationTime <fh> , <time>


FileGetUsernotes, FileSetUsernotes

Liest oder verändert die Benutzernotizen der Datei.
Syntax: notes$ = FileGetUsernotes (fileName$) ' Auslesen der Benutzernotizen
oder: notes$ = FileGetUsernotes (<fh>)

Syntax: FileSetUsernotes fileName$, notes$ ' Setzen der Benutzernotizen
oder: FileSetUsernotes <fh>, notes$


FileGetRelease, FileSetRelease

Liest oder verändert die Releasenummer der Datei. Das GEOS System verwendet die Releasenummer zum Versionscheck und zu Informationszwecken. R-BASIC und der Uni-Installer verwenden die Releasenummer um zu entscheiden ob eine Datei neuer ist als eine andere Datei mit gleichem Namen. Der R-BASIC Compiler setzt die ersten drei Felder der Releasenummer von Launcher und BIN-Datei entsprechend der Versionsnummer des Programms bzw. der Library (siehe Befehl Version$).

Bei R-BASIC Libraries wird die Releasenummer (und damit die Versionsnummer der Library) verwendet um zu entscheiden, ob ein BASIC Programm mit dieser Library zusammenarbeiten kann.

Um zu entscheiden, ob die R-BASIC IDE die Datei öffnen und bearbeiten kann, wird die Protokollnummer, nicht die Releasenummer, benutzt.

Syntax: <release> = FileGetRelease (fileName$)
oder: <release> = FileGetRelease (<fh>) ' Auslesen der Release-Nummer

Syntax: FileSetRelease fileName$, <release>
oder: FileSetRelease <fh> , <release> ' Setzen der Release-Nummer


FileGetProtocol, FileSetProtocol

Liest oder verändert dieProtokollnummer der Datei. Das GEOS System verwendet die Protocollnummer um zu prüfen, ob Programme, Dateien und Libraries kompatibel zueinander sind. R-BASIC definiert keine eigene Struktur für die Protokollnummer sondern verwendet die Felder rnMajor und rnMinor der ReleaseNumber Struktur.

Vorsicht! Änderungen der Protokollnummer können dazu führen, dass Programme nicht mehr funktionieren oder Dateien nicht mehr gelesen werden können.

Syntax: <protocol> = FileGetProtocol (fileName$)
oder: <protocol> = FileGetProtocol (<fh>) ' Auslesen der Protocol-Nummer

Syntax: FileSetProtocol fileName$, <protocol>
oder: FileSetProtocol <fh> , <protocol> ' Setzen der Protocol-Nummer

Angaben zu den Parametern und Rückgabewerten:
<token> : Eine Variable vom Typ "GeodeToken".
Die Set-Routinen akzeptieren auch Funktionen, die eine GeodeToken-Struktur zurückgeben

fileName$ : Name der Datei.
Stringausdrücke, auch mit Pfadangaben im Namen, sind zulässig.

<fh> : Variable (oder Funktion) vom Typ FILE. Bezeichnet die Datei.

<time> : Eine Variable vom Typ "DateAndTime".

Die Set- Routinen akzeptieren auch Funktionen, die eine DateAndTime-Struktur zurückgeben.

notes$ : Ein String mit bis zu 99 Zeichen.
Für FileSetUsernotes sind Stringausdrücke zulässig. Ist der String zu lang tritt ein Laufzeitfehler auf und das Programm wird beendet.

<release>
<protocol> : Eine Variable vom Typ "ReleaseNumber".
Für die "Protocol"-Funktionen werden nur die Felder rnMajor und rnMinor verwendet. Die Set- Routinen akzeptieren auch Funktionen, die eine ReleaseNumber-Struktur zurückgeben.
Beispiel: 
DIM token AS GeodeToken
DIM time AS DateAndTime
DIM release AS ReleaseNumber
DIM text$

  SetStandardPath SP_SYSTEM

  token = FileGetToken "geos.geo"
  Print "Token: \"";token.tokenchars;"\","; token.manufid
  ' manufid = Manufacturer ID

  token = FileGetCreator "geos.geo"
  Print "Creator: \"";token.tokenchars;"\","; token.manufid

  time = FileGetCreationTime "geos.geo"
  Print "Datum: "; FormatDate$(time)
  Print "Zeit: "; FormatTime$(time)

  release = FileGetRelease "geos.geo"
  text$ = "Version: "+ Trim$(Str$(release.rnMajor))
  text$ = text$ + "."+ Trim$(Str$(release.rnMinor))
  text$ = text$ + "  "+ Trim$(Str$(release.rnChange))
  text$ = text$ + "-"+ Trim$(Str$(release.rnEngineering))
  Print text$

  release = FileGetProtocol "geos.geo"
  text$ = "Protocol: "+ Trim$(Str$(release.rnMajor))
  text$ = text$ + "."+ Trim$(Str$(release.rnMinor))
  Print text$

^

Weiter...