6. Überblick UPDF-Dateien¶
UPDF (Uni-Plot-Data-Format) ist das Dateiformat von UniPlot R2012. Es wird sowohl für UniPlot-Dokument-Dateien (IPZ-Dateien) als auch als Ersatz für netCDF-Dateien (NC2-Dateien) verwendet.
6.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 Verzeichnisse als Storages, die Dateien als Streams und die Attribute als Properties bezeichnet werden. Properties bestehen aus einem Property-Namen und einem Property-Wert.
6.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.
- 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 NC2-Dateien nicht der Fall.
- Bei NC2-Dateien sind mit nc_sync und nc_abort/nc_close Transaktionen möglich.
6.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.
6.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.
6.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.
6.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.
6.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_get_filetimes | updf_get_filetimes liefert Datum/Zeit der Erzeugung, des letzten Zugriffs und der letzten Änderung einer offenen UPDF-Datei. |
| updf_get_parent | updf_get_parent liefert den Parent-Storage eines Streams oder Storages. |
| 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. |
| updf_set_filetimes | updf_set_filetimes setzt die Dateizeiten einer offenen UPDF-Datei. |
| Storages und Streams | |
|---|---|
| updf_close_storage | updf_close_storage schließt einen Storage oder einen Sub-Storage. |
| updf_commit | updf_commit schreibt die Änderungen auf die Festplatte, falls ein Root-Storage angegeben wird. |
| 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_get_cmode | updf_get_cmode erfragt ob die Datei mit den Flags UPDF_REPACKING oder UPDF_ZLIB_COMPRESSION erzeugt wurde. |
| updf_get_free_pages | updf_get_free_pages liefert die Anzahl an freien Seiten einer UPDF-Datei. |
| updf_move_element | updf_move_element verschiebt einen Storage in einen anderen 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
id-824069