CXI-Basis-Programmierreferenz / Version 2 / Datenspeicherung / CxiTree / Ableitung CxiTreeFile /

CxiTreeFile(...) - CXI-Baum in Datei

CxiTreeFile :: CxiTreeFile ()
CxiTreeFile :: CxiTreeFile (const char *fname, CxiLong options = cxiOptNoCreate | cxiOptReadWrite, const char *keyword = 0)
CxiTreeFile :: CxiTreeFile (const char *fname, const char *optstr, const char *keyword = 0)
CxiHandle cxiCreateCxiTreeFile (const char *fname, const char *optstr, const char *keyword)

Erstellt einen dateigestützten CXI-Baum. Die Klasse CxiTreeFile implementiert verschiedene Varianten eines CXI-Baums, der zur Speicherung der Daten eine Datei benutzt. Der Standardkonstruktor ohne Parameter entspricht CxiTreeFile(0,"t",0).

fname:
Dateiname (bei Angabe der Option "t" kann hier der Pfad für die Datei bestimmt werden)

options:
Optionen als ODER-Verknüpfung

optstr:
Optionen als Zeichenkette

keyword:
Schlüssel für codierte Datei, NULL für uncodierte Datei

return:
Die C-Funktion liefert das Handle des neuen CXI-Objekts, NULL im Fehlerfall

Die Klasse CxiTreeFile besitzt neben diesem Konstruktor die speziellen Abfrage- und Cache-Funktionen, sie unterstützt Bor-Variablen. Alle weiteren Baum-Funktionen werden von CxiTree, alle anderen Zugriffsfunktionen - auch der Destruktor - von CxiNode geerbt. Ob der Konstruktor erfolgreich war, kann anschließend durch einen Aufruf von Status() abgefragt werden. Im Beispiel zu RegisterResource wird ein CxiTreeFile benutzt.

Wird ein Schlüsselwort angegeben, so werden alle Daten verschlüsselt abgelegt. Das Schlüsselwort ist eine beliebig lange Zeichenkette mit abschließendem Nullbyte, alle Zeichencodes außer Nullbyte können vorkommen. Existiert die Datei fname bereits, so muss das beim Erstellen der Datei vergebene Schlüsselwort beim Öffnen angegeben werden, sonst schlägt der Konstruktor fehl (siehe Status()). Dies gilt auch, wenn die Datei unverschlüsselt vorliegt, es ist dann nur keyword==NULL zulässig. Eine verschlüsselte Datei kann nicht mehr mit ReadBlockFromFile eingelesen werden.

Die folgenden Optionen sind verfügbar. Als Parameter optstr muss eine Zeichenkette angegeben werden, die einen Buchstaben für den Typ und beliebig viele Optionen enthalten kann. Abschließend kann der String eine Angabe zur Verschlüsselung enthalten.

Typbuchstabe:
"r": Öffnen einer bestehenden Datei, die nur gelesen werden kann
"u": Öffnen einer bestehenden Datei, die verändert werden kann
"a": Wie "u", Datei wird angelegt, wenn sie nicht existiert
"w": Erstellen einer neuen Datei, die verändert werden kann
"t": Erstellen einer temporären Datei, die verändert werden kann
"i": Öffnen einer bestehenden Datei (Kompatibilitätsmodus)
Fehlt die Typangabe, wird "u" angenommen. Bei mehreren Typangaben gilt nur die letzte.

Optionen:
"p": Gepackte Datei
"v": Datei zwischen Zugriffen schließen (siehe Anmerkung 1)
"b": Datei komplett puffern
"s": Dateiheader suchen
"d": Datei im Destruktor automatisch löschen
"k": Datei nicht automatisch löschen (siehe Anmerkung 2)
Nicht alle Kombinationen von Typ und Optionen sind sinnvoll (s.u.).

Verschlüsselung:
"-" oder keine Angabe: Unverschlüsselte Datei
"+": Verschlüsselte Datei ohne Schlüsselwort
"+...": Verschlüsselte Datei mit Schlüsselwort "..."
Ist der Parameter keyword angegeben, so wird die Angabe zur Verschlüsselung im Parameter optstr ignoriert.

Folgende Angaben für den Parameter options sind möglich, die ODER-Verknüpfung für den 'alten' Konstruktor ist ebenfalls angegeben:

"u": cxiOptNoCreate | cxiOptReadWrite
Eine bestehende Datei wird exklusiv geöffnet und kann verändert werden. Existiert die angegebene Datei nicht, wird der Fehlerstatus auf cxiErrorFileOpen gesetzt. Ist die Option "d" angegeben, wird die Datei vom Destruktor gelöscht; ansonsten bleibt sie bestehen, wenn das Objekt freigegeben wird. Eine auf diese Weise eröffnete Datei darf nicht mehrfach als CxiTreeFile geöffnet werden, da dies zur Zerstörung der internen Datenstruktur führt. Optional kann "uv" (oder "udv") angegeben werden, um File-Handles zu sparen, dies verlangsamt jedoch den Zugriff.

"a": cxiOptAutoCreate | cxiOptReadWrite
Eine Datei wird exklusiv geöffnet und kann verändert werden. Falls die angegebene Datei nicht gefunden wird, erstellt der Konstruktor eine leere CXI-Datei (d.h. einen CXI-Baum mit einem leeren Wurzelknoten). Ist die Option "d" angegeben, wird die Datei vom Destruktor gelöscht; ansonsten bleibt sie bestehen, wenn das Objekt freigegeben wird. Eine auf diese Weise eröffnete Datei darf nicht mehrfach als CxiTreeFile geöffnet werden, da dies zur Zerstörung der internen Datenstruktur führt. Optional kann "av" (oder "adv") angegeben werden, um File-Handles zu sparen, dies verlangsamt jedoch den Zugriff.

"w": cxiOptReplaceFile | cxiOptReadWrite
Die angegebene Datei wird neu erstellt und exklusiv geöffnet. Falls die angegebene Datei bereits existiert, geht der bisherige Inhalt der Datei verloren. Die neue CXI-Datei enthält noch keine Daten (d.h. nur einen leeren Wurzelknoten) und kann verändert werden. Ist die Option "d" angegeben, wird die Datei vom Destruktor gelöscht; ansonsten bleibt sie bestehen, wenn das Objekt freigegeben wird. Eine auf diese Weise eröffnete Datei darf nicht mehrfach als CxiTreeFile geöffnet werden, da dies zur Zerstörung der internen Datenstruktur führt. Optional kann "wv" (oder "wdv") angegeben werden, um File-Handles zu sparen, dies verlangsamt jedoch den Zugriff.

"wp": cxiOptReplaceFile | cxiOptReadWrite | cxiOptPacked
Die angegebene Datei wird neu erstellt und exklusiv geöffnet. Falls die angegebene Datei bereits existiert, geht der bisherige Inhalt der Datei verloren. Die neue CXI-Datei enthält noch keine Daten (d.h. nur einen leeren Wurzelknoten) und kann verändert werden. Eine mit "p" geöffnete Datei wird ohne Füllbytes geschrieben, jeder Datenblock erhält in der Datei nur den minimal benötigten Platz zugewiesen. Dies ergibt kleinere Dateien, die jedoch bei Updates unverhältnismäßig wachsen. Verwenden Sie also "p" nur, wenn die erstellte Datei später nur noch gelesen werden soll. Ist die Option "d" angegeben, wird die Datei vom Destruktor gelöscht; ansonsten bleibt sie bestehen, wenn das Objekt freigegeben wird. Eine auf diese Weise eröffnete Datei darf nicht mehrfach als CxiTreeFile geöffnet werden, da dies zur Zerstörung der internen Datenstruktur führt. Optional kann "wpv" angegeben werden, um File-Handles zu sparen, dies verlangsamt jedoch den Zugriff.

"t": cxiOptTempFile | cxiOptReadWrite
Eine temporäre Datei wird erstellt und exklusiv zum Lesen und Schreiben geöffnet. Der Parameter fname gibt den Pfad für die Datei an oder ist 0 für den Standardpfad. Der Name wird automatisch generiert, die Erweiterung kann mit SetTempFileExtension eingestellt werden. Der Konstruktor initialisiert die Datei als leeren CXI-Baum (d.h. einen CXI-Baum mit einem leeren Wurzelknoten). Der Destruktor löscht die Datei wieder, die Option "d" ist im Typ "t" automatisch enthalten. Auch hier kann (aus Datensicherheitsgründen) ein Schlüsselwort angegeben werden, um die Daten verschlüsselt in der Datei abzulegen. Optional kann "tv" angegeben werden, um File-Handles zu sparen, dies verlangsamt jedoch den Zugriff (siehe Abschnitt Portabilität). Geben Sie "tk" oder "tkv" an, um zu verhindern, dass die Datei automatisch gelöscht wird; dies ist für die Fehlersuche interessant.

"r": cxiOptNoCreate | cxiOptReadOnly
Eine bestehende Datei wird geöffnet und kann nicht verändert werden. Jeder Änderungsversuch ergibt den Fehler cxiErrorFileProtect. Eine auf diese Weise eröffnete Datei kann beliebig oft als CxiTreeFile mit der Option "r" (cxiOptReadOnly) geöffnet werden. Optional kann "rv" angegeben werden, um File-Handles zu sparen, dies verlangsamt jedoch den Zugriff.

"rb": cxiOptNoCreate | cxiOptReadOnly | cxiOptShadowBuffer
Eine bestehende Datei wird geöffnet und vollständig in den Speicher eingelesen. Ist nicht genügend Speicher vorhanden, wird die Option "b" (cxiOptShadowBuffer) ignoriert. Eine auf diese Weise eröffnete Datei kann beliebig oft als CxiTreeFile mit der Option "r" (cxiOptReadOnly) geöffnet werden. Die Angabe von "rbv" ist normalerweise nutzlos, da nach der Initialisierung keine Dateizugriffe mehr notwendig sind. Falls jedoch nicht genügend Speicher für die Pufferung zur Verfügung steht, wird die Datei normal geöffnet und damit auch "v" (cxiOptVirtual) berücksichtigt.

"rs": cxiOptNoCreate | cxiOptReadOnly | cxiOptSearchHeader
Diese Einstellung entspricht "r" mit dem Unterschied, dass die CXI-Daten auch an eine Nicht-CXI-Datei angehängt sein können; diese Datei ist üblicherweise die eigene EXE-Datei. Beim Öffnen wird die CXI-Kennung gesucht, diese darf daher nicht im Nicht-CXI-Teil der Datei vorkommen. Eine auf diese Weise eröffnete Datei kann beliebig oft als CxiTreeFile mit der Option "r" (cxiOptReadOnly) geöffnet werden. Optional kann "rsv" angegeben werden, um File-Handles zu sparen, dies verlangsamt jedoch den Zugriff.

"i": cxiOptNoCreate | cxiOptReadOnly | cxiOptCompatibility
Eine bestehende Datei wird geöffnet und kann nicht verändert werden. Jeder Änderungsversuch ergibt den Fehler cxiErrorFileProtect. Im Unterschied zu "r" werden auch ältere CXI-Dateiformate erkannt und können ausgelesen werden. Das Schreiben älterer Formate ist grundsätzlich nicht möglich. Eine auf diese Weise eröffnete Datei kann beliebig oft als CxiTreeFile mit der Option "i" geöffnet werden. Der Typ "i" kann nicht mit "b" und "s" kombiniert werden. Optional kann "iv" angegeben werden, um File-Handles zu sparen, dies verlangsamt jedoch den Zugriff.

Anmerkung 1:
Wird die Option "v" (cxiOptVirtual) benutzt, so sollte auf jeden Fall der übergebene Dateiname einen vollständigen Pfad enthalten, bei temporären Dateien sollte ein absoluter Pfad angegeben werden. Ansonsten kann es passieren, dass nach einem Wechsel des Arbeitsverzeichnisses innerhalb des Programms nicht mehr auf die CXI-Datei zugegriffen werden kann. Beachten Sie außerdem, dass eine Verwendung der Option "v" den Zugriffsschutz des Betriebssystems außer Kraft setzt und dadurch parallele Schreibzugriffe oder mehrfach zum Schreiben geöffnete Dateien nicht mehr erkannt werden können (vgl. Reentranz unter DOS, Win16, Win32 und OS/2).

Anmerkung 2:
Wird die Option "d" (cxiOptAutoDeleteFile) angegeben, löscht der Destruktor die Datei, sofern das Betriebssystem dies zulässt (Parallelzugriff, R-Attribut, Schreibschutz, ...). Dies gilt unabhängig vom Zugriffsmodus, also auch für Dateien, die nur zum Lesen ("r") geöffnet werden. Der Typ "t" beinhaltet automatisch die Option "d". Mit der Option "k" kann die Wirkung von "d" aufgehoben werden, "k" hat in jedem Fall Vorrang vor "d".

Portabilität:
Diese Funktion ist in allen unterstützten Systemen verfügbar. Die C-Funktion ist als Makro implementiert. Die Option "d" wird ab Version 2.08 erkannt.

Siehe auch:
EnableFileCache - Aktivierung des Cache
DisableFileCache - Deaktivierung des Cache
QueryFileName - Abfrage des Dateinamens
QueryFileOptions - Abfrage der Optionen
SetTempFileExtension - Namenserweiterung für temporäre Dateien
DeleteCxiTree - Freigabe eines CxiHandle