Datenbankformat

Datenbankformat (DBF/CDX) aus Nutzersicht

Diese Seite beschreibt, wie libopenschichtplaner5 mit dem Original-Datenbestand von Schichtplaner5 umgeht: welche Dateien gelesen und geschrieben werden, welche Kodierung gilt, wie das -L-Änderungsjournal und die .CDX-Indizes behandelt werden — und wo die Grenzen der Koexistenz mit einem laufenden Original-Client liegen.

---

Das Datenverzeichnis

Schichtplaner5 speichert alle Daten als FoxPro/dBASE-Tabellen in einem Verzeichnis (üblicherweise Daten), eine Datei je Tabelle (5EMPL.DBF, 5SHIFT.DBF, …), dazu .CDX-Indexdateien und -L-Begleittabellen. Die Bibliothek arbeitet direkt auf diesen Originaldateien — die DBF-Dateien bleiben die führende Datenquelle (Source of Truth), auch wenn parallel der optionale SQL-Spiegel genutzt wird (ORM-und-Sync).

Die SP5Database-Fassade nutzt 30 Tabellen:

Tabelle	Inhalt
5EMPL	Mitarbeiter (Stammdaten und Rechenparameter)
5GROUP	Gruppen (hierarchisch)
5GRASG	Gruppen-Zuordnungen (Mitarbeiter ↔ Gruppe)
5MAGRP	weitere Mitarbeiter↔Gruppen-Zuordnung (von Auswertungen genutzt)
5SHIFT	Schichtarten (Zeiten/Dauern je Wochentag und Feiertag)
5LEAVT	Abwesenheitsarten (inkl. Anrechnungsregeln)
5WOPL	Arbeitsplätze
5MASHI	Dienstplan-Einträge (manuell zugewiesene Schichten)
5SPSHI	Sonderschichten (ersetzen am betreffenden Tag reguläre Dienste)
5ABSEN	Abwesenheiten
5HOLID	Feiertage (inkl. halbe/wiederkehrende)
5PERIO	Abrechnungs-/Planungsperioden
5BOOK	Kontobuchungen (Zeitkonto: Ist/Soll/Überstunden)
5OVER	Überstunden-Einträge
5LEAEN	Urlaubsansprüche (je Jahr und Abwesenheitsart)
5SHDEM	Besetzungsbedarf je Schicht und Wochentag (Min/Max)
5SPDEM	datumsbezogener Sonderbedarf
5DADEM	tagesbezogener Gesamtbedarf
5CYCLE	Zyklen/Schichtmodelle
5CYENT	Zyklus-Einträge (Tagesfolge eines Modells)
5CYASS	Zyklus-Zuweisungen (Modell → Mitarbeiter ab Startdatum)
5CYEXC	Zyklus-Ausnahmen (Abweichungen vom Modell an einzelnen Tagen)
5RESTR	Restriktionen (Mitarbeiter ↔ Schicht)
5HOBAN	Urlaubssperren
5XCHAR	Zeitzuschläge (Zuschlagsfenster)
5NOTE	Notizen
5USER	Benutzerkonten und Rechte
5USETT	globale Einstellungen
5EMACC	Zugriffsrechte je Mitarbeiter
5GRACC	Zugriffsrechte je Gruppe

Daneben liest das CLI (sp5lib info) bei Vorhandensein die Tabelle 5BUILD.DBF aus, um den Schichtplaner5-Build des Datenbestands anzuzeigen.

---

Kodierung und Feldtypen

Der Leser (sp5lib.dbf_reader) und der Schreiber (sp5lib.dbf_writer) bilden das Encoding der Originaldateien exakt nach; geschriebene Dateien sind byte-kompatibel zum Original-Format (per Tests abgesichert).

• Textfelder (C): UTF-16-LE mit Null-Terminator. Die Erkennung erfolgt automatisch per Heuristik und funktioniert auch für nicht-lateinische Schriften (z. B. Griechisch, Kyrillisch, Hebräisch, Arabisch). Bestimmte Datenfelder (WORKDAYS, VALIDDAYS, DAILYDEM, STARTEND* u. a.) sind reine ASCII-/cp1252-Felder und werden entsprechend behandelt.
• Binärfelder: Die C-Felder DIGEST, CREATIME und UUID enthalten Rohbytes und werden unverändert als Python-bytes geliefert (im CLI-dump als Hex-String).
• Datumsfelder (D): YYYYMMDD, beim Lesen mit echter Kalendervalidierung — unmögliche Daten (z. B. 20230231) ergeben None statt fehlerhafter Werte.
• Zahlen (N/F) und Logikfelder (L): werden zu int/float bzw. bool dekodiert; leere oder defekte Werte ergeben 0.
• Memo-Felder (M) werden nicht unterstützt: zugehörige .DBT-Dateien werden weder gelesen noch geschrieben; Memo-Werte sind beim Lesen immer None, beim Schreiben bleiben sie leer.
• Gelöschte Records: dBASE-typisch nur per Lösch-Flag markiert (Soft-Delete). Der Leser überspringt sie; physisch entfernt werden sie erst durch ein PACK (SP5Database.compact_database() bzw. dbf_writer.pack_table()).
• Fehlertoleranz: Fehlende, abgeschnittene oder korrupte Dateien führen beim Lesen zu einer leeren Ergebnisliste statt zu einer Exception.

---

Schreibzugriffe: Sicherheitseigenschaften

Jeder Schreibzugriff der Bibliothek (append_record, update_record, delete_record, pack_table) ist gegen typische Fehlerquellen abgesichert:

• Exklusives Datei-Lock (POSIX flock) für die Dauer des Schreibzugriffs; der Record-Zähler wird innerhalb des Locks neu gelesen, damit kein parallel geschriebener Record verloren geht.
• Rollback bei Teilschreibern: schlägt der Schreibvorgang fehl, wird die Datei auf den Stand vor dem Zugriff zurückgesetzt.
• Integritäts-Guards: Records mit falscher Größe und numerische Überläufe werden abgewiesen statt still abgeschnitten; gekürzte Strings werden als Warnung geloggt.
• Der EOF-Marker und das Header-Änderungsdatum werden wie vom Original erwartet gepflegt.

Plattform-Hinweis: Der Schreibpfad nutzt fcntl.flock und steht damit nur unter Linux/macOS zur Verfügung (siehe Installation).

---

Das -L-Änderungsjournal

Zu jeder Datentabelle existiert eine -L-Begleittabelle (z. B. 5EMPL-L.DBF), über die laufende Schichtplaner5-Clients externe Änderungen einlesen. Die Bibliothek pflegt dieses Journal automatisch:

• Nach jedem erfolgreichen Schreibzugriff wird ein Journal-Eintrag angehängt — mit fortlaufender Nummer, dem tabellenspezifischen zusammengesetzten Schlüssel des geänderten Records und der Änderungsart (Anlegen/Ändern bzw. Löschen). Ein laufender Original-Client übernimmt die Änderung dadurch in seine Ansicht.
• Ein fehlendes oder defektes -L-File führt nur zu einer Warnung im Log — der eigentliche Datenschreibzugriff wird dadurch nie blockiert.
• PACK (compact_database / pack_table) entfernt gelöschte Records physisch und setzt das Journal dabei zurück; Original-Clients laden den Bestand daraufhin vollständig neu.

---

CDX-Indizes: Verhalten beim Schreiben

Die .CDX-Indexdateien des Originals werden von der Bibliothek nicht fortgeschrieben. Stattdessen gilt die Strategie:

• Nach jedem erfolgreichen Schreibzugriff werden die veralteten .CDX-Dateien der geänderten Tabelle gelöscht. Der Original-Client baut den Index beim nächsten Öffnen der Tabelle automatisch neu auf, statt mit einem nicht mehr passenden Index zu arbeiten.

• Wer das nicht möchte, kann die Invalidierung global abschalten:

  import sp5lib.dbf_writer as dbf_writer
  dbf_writer.INVALIDATE_CDX = False

.CDX-Dateien sollten generell nicht manuell bearbeitet werden — sie sind reine Hilfsstrukturen und jederzeit aus den .DBF-Daten rekonstruierbar.

---

Koexistenz mit dem Original-Client — und ihre Grenzen

Die Bibliothek ist darauf ausgelegt, denselben Datenbestand wie das originale Windows-Programm zu verwenden. Dabei gilt:

Szenario	Status
Lesen, während der Original-Client läuft	unkritisch
Schreiben, während der Original-Client geschlossen ist (sequenzielle Koexistenz)	sicher und getestet
Schreiben, während der Original-Client die Daten ebenfalls schreibend offen hat	nicht sicher

Warum gleichzeitiges Schreiben nicht sicher ist: Der Original-Client sperrt einzelne Datensatzbereiche innerhalb der Dateien, die Bibliothek sperrt ganze Dateien per POSIX-flock — die beiden Locking-Verfahren nehmen einander nicht wahr. Zudem sind Daten- und Journal-Schreibzugriff der Bibliothek kein atomares Paar. Empfohlenes Muster: Schreibzugriffe der Bibliothek (bzw. der darauf aufbauenden Web-Anwendung) durchführen, während kein Original-Client schreibt; laufende Clients übernehmen die Änderungen anschließend über das -L-Journal.

Externe Änderungen erkennen: SP5Database hält einen threadsicheren Lese-Cache, der über die Datei-Änderungszeit (mtime) validiert wird — ändert der Original-Client eine Tabelle, liest die Bibliothek sie beim nächsten Zugriff automatisch neu ein.

---

Weiterführend

• Rechenregeln über diesen Tabellen: Berechnungen
• SQL-Spiegel des Datenbestands: ORM-und-Sync
• Datenbestand prüfen und exportieren: CLI
• Sicht der Web-Anwendung auf das Format: Datenbankformat im App-Wiki