47. Überblick UPDF-Dateien

updf (Uni-Plot-Data-Format) ist das Dateiformat von UniPlot 6.0. Es wird sowohl für UniPlot-Dokument-Dateien (ipw-Dateien) als auch als Ersatz für netCDF-Dateien (nc-Dateien) verwendet.

Mit dieser Version können noch keine updf-basierten ipw-Dateien bearbeitet werden sondern nur netCDF-up-Dateien.

47.1. Aufbau des Formats

updf-Dateien sind wie ein Dateisystem aufgebaut. Eine updf-Datei enthält Verzeichnisse. In den Verzeichnissen können sich wieder Verzeichnisse und Dateien befinden. Wie bei einem Dateisystem können Dateien zugefügt, gelöscht, umbenannt, verlängert oder verkürzt, verschoben werden.

Die Verzeichnisse und Dateien können Attribute enthalten. Dies sind unter einem Namen gespeicherte Werte. Bei den Werten können unterschiedliche Typen verwendet werden, z. B. Unicode-Zeichenketten oder 64-Bit Integer. Es können Einzelwerte, Vektoren von Werten und Matrizen von Werten gespeichert werden.

Um Verwechselungen zu vermeiden sollen im Folgenden die Vereichnisse als Storages, die Dateien als Streams und die Attribute als Properties bezeichnet werden. Properties bestehen aus einem Property-Namen und einem Property-Wert.

47.2. Vorteile der neuen Formate

• Das Schreiben von UniPlot 5.x -Dateien kann bei sehr großen Dateien mit mehreren Dutzend Seiten sehr langsam werden. Das Schreiben von updf-Dateien ist in fast linearer Zeit mit ihrer Größe möglich. Das heißt das Schreiben eines Dokuments mit 200 Diagramm-Seiten dauert nur ca. doppelt so lange wie das Schreiben eines Dokuments mit 100 Seiten.
• Die aktuellen ipw-Dateien und nc-Dateien verwenden keine Kompression. updf verwendet Kompression. Dadurch ergeben sich deutlich kompaktere Dateien.
• In den aktuellen nc-Dateien können 2 Giga-Bytes gespeichert werden. updf erlaubt die Speicherung von bis zu 8 Tera-Bytes pro Datei.
• netCDF-up-Dateien können in updf-ipw-Dateien eingebettet werden.
• nc-Dateien haben bei nachträglichen Änderungen Performance-Probleme. Wird beispielsweise ein globales Attribut zugefügt, muss die gesamte nc-Datei neu geschrieben werden. Dies ist bei netCDF-up-Dateien nicht der Fall.
• Bei netCDF-up-Dateien sind mit nc_sync und nc_abort/nc_close Transaktionen möglich.

47.3. Format-Grenzen

• Max. Größe einer updf-Datei: ca. 8 Terabytes (8000 GB). In der Praxis einige GigaBytes.
• Anzahl an Zeichen in Storage-, Stream- und Property-Namen: 255.
• Max. Größe eines Streams: 8 TB. In des Praxis einige GigaBytes.
• Max. Anzahl an Streams und Storages pro Storage: 2^31. In der Praxis einige 10000.
• Max. Größe eines einzelnen Property: Einige MB (muss komplett in den RAM-Speicher passen).
• Anzahl an Properties pro Stream oder Storage: 2^31. In der Praxis einige 100000.

47.4. Gültige Namen in Storages, Streams und Properties

Ein Name kann aus 1 bis 255 Unicode-Zeichen bestehen.

Folgende Zeichen sind nicht zulässig: Zeichen mit den Codes 0 bis 31 sowie die 9 Zeichen ‘/’, ‘’, ‘*’, ‘?’, ‘”’, ‘<’, ‘>’, ‘:’, ‘|’.

Es sollten normalerweise nur Namen verwendet werden, die auch bei Betriebssystem-Dateinamen gültig sind.

47.5. Logging

Normalerweise werden Fehler der updf-Funktionen in das Ereignisanzeige-Fenster von UniPlot geschrieben. Mit dem Befehl

log_set_active("updf", 0)

kann Logging ausgeschaltet werden.

47.6. Garbage collection

Für alle Pointer wird garbage collection verwendet. Nicht geschlossene Elemente werden bei Aufruf des garbage-collectors (gc) in der richtigen Reihenfolge geschlossen.

47.7. UniScript-Schnittstelle

	Verschiedenes
updf_dump	updf_dump kopiert die Streams, Storages und Properties der Streams und Storages einer updf-Datei in ein Directory.
updf_fileversion	updf_fileversion liefert die Versions-Nummer der updf-Datei.
updf_gen	updf_gen kopiert die Dateien eines Verzeichnisses und der Unterverzeichnisse in eine updf-Datei.
updf_get_error_string	updf_get_error_string liefert die Fehlermeldung des Fehlercodes der Funktion updf_is_error.
updf_is_error	updf_is_error prüft ob ein fataler Fehler aufgetreten ist.
updf_libversion	updf_libversion liefert die Versionsnummer und das Erstellungsdatum der updf-Library als Zeichenkette.

	Storages und Streams
updf_close_storage	updf_close_storage schließt einen Storage oder einen Sub-Storage.
updf_commit	Falls ein Root-Storage angegeben wird, werden die Änderungen auf die Festplatte geschrieben.
updf_copy_to	updf_copy_to kopiert die Streams, Storages und Properties eines Storages rekursiv in einen anderen Storage.
updf_create_file	updf_create_file erzeugt eine neue updf-Datei.
updf_create_storage	updf_create_storage erzeugt einen Storage in einem Storage.
updf_create_stream	updf_create_stream erzeugt einen Stream in einem Storage.
updf_destroy_element	updf_destroy_element löscht einen Stream oder Storage in einem Storage.
updf_open_file	updf_open_file öffnet eine vorhandene updf-Datei.
updf_open_storage	updf_open_storage öffnet einen Storage in einer updf-Datei.
updf_open_stream	updf_open_stream öffnet einen vorhandenen Stream in einer updf-Datei.
updf_rename_element	updf_rename_element benennt einen Stream oder Storage um.
updf_revert	updf_revert macht die Änderungen nach dem letzten Öffnen bzw. Commit (updf_commit) der Datei rückgängig.

	Streams
updf_create_stream	updf_create_stream erzeugt einen Stream in einem Storage.
updf_file_close	updf_file_close schließt einen updf-Stream.
updf_file_copy_to	updf_file_copy_to kopiert den Inhalt eines Streams in einen anderen Stream.
updf_open_stream	updf_open_stream öffnet einen vorhandenen Stream in einer updf-Datei.

Streams werden mit den normalen Datei-Funktionen, wie fprintf, fread, etc. bearbeitet, siehe Überblick Binär- und Text-Dateien.

	Iteration über Storages und Streams
updf_enum_begin	updf_enum_begin dient in Verbindung mit updf_enum_next dazu über alle Streams und Storages eines Storage-Objekts zu iterieren.
updf_enum_close	updf_enum_close schließt das von updf_enum_begin erzeugte enum-Objekt.
updf_enum_next	updf_enum_next dient in Verbindung mit updf_enum_begin dazu über alle Streams und Storages in einem Storage zu iterieren.
updf_stat_get_len	updf_stat_get_len liefert die Länge des Streams.
updf_stat_get_name	updf_stat_get_name liefert den Namen des Storages oder Streams.
updf_stat_get_type	updf_stat_get_type liefert den Typ des Elements.

	Properties
updf_prop_close	updf_prop_close schliesst die Properties eines Storages oder Streams.
updf_prop_copy_to	updf_prop_copy_to kopiert die Properties eines Elements in ein anderes Element.
updf_prop_count	updf_prop_count liefert die Anzahl an Properties.
updf_prop_delete	updf_prop_delete löscht ein Property-Value-Pärchen.
updf_prop_enum	Mit updf_prop_enum kann über alle Properties eines Streams oder Storages iteriert werden.
updf_prop_enum_close	updf_prop_enum_close schließt das propEnum-Objekt.
updf_prop_enum_next	updf_prop_enum_next dient in Verbindung mit updf_prop_enum dazu über alle Properties eines Streams oder Storages zu iterieren.
updf_prop_get_at	updf_prop_get_at liefert ein Property-Objekt.
updf_prop_has_key	updf_prop_has_key prüft ob ein Property (Key/Value-Paar) existiert.
updf_prop_open	updf_prop_open öffnet die Properties eines Storages oder Streams.
updf_prop_set_at	updf_prop_set_at schreibt ein Property.

	Property-Werte
updf_propval_get	updf_propval_get liefert den Wert eines Property-Objekts.
updf_propval_get_info	updf_propval_get_info liefert Informationen über ein Property-Objekt.
updf_propval_new	updf_propval_new erzeugt einen Property-Wert.

Siehe auch

Funktionen eingeteilt in Kategorien

_id-824069