CXI-Basis-Programmierreferenz / Version 2 / Datenspeicherung / CxiNode / Statusabfragen /

Validate - Gültigkeitsüberprüfung

CxiError CxiNode :: Validate () const
CxiError cxiValidateHandle (CxiHandle self)
CxiError cxiValidateDataPtr (const CxiDataBlock *cxid, CxiLong psize)

Überprüfung der internen Struktur eines CXI-Knotens

self:
Zu überprüfender CXI-Knoten oder CXI-Baum

cxid:
Zu überprüfender Datenbereich als Zeiger auf CxiDataBlock

psize:
Größe des Speicherblocks, auf den cxid zeigt

return:
cxiNoError (=0), wenn der Block gültig ist;
cxiErrorValidate... bei ungültigem Block

STELLT DIESE FUNKTION EINEN FEHLER FEST, SO IST DIE STRUKTUR DES ANGEGEBENEN BLOCKS ZERSTÖRT. JEDER ANSCHLIESSENDE ZUGRIFF AUF DEN BLOCK KANN ZUM ABSTURZ DES ANWENDUNGSPROGRAMMS ODER DES GESAMTEN SYSTEMS FÜHREN!

Die Validate...-Funktionen führen eine ausführliche Überprüfung der Struktur des CXI-Knotens durch. Die gesamte interne Verzeigerung wird auf falsche Offsets geprüft, bei allen Zeichenketten die korrekte Terminierung mit einem Nullbyte getestet und vieles mehr. Da dies insgesamt sehr aufwendig ist, benutzt das CxiNode/CxiTree-System diese Funktion nicht automatisch (außer in der Leseroutine des CxiTreeFile), sie kann jedoch jederzeit zur Sicherstellung der Datenkonsistenz vom Anwendungsprogramm aufgerufen werden.

Da Validate den Block nicht verändert, bleibt dieser im Fehlerfall auch nach dem Aufruf ungülig. In dieser Situation ist es ratsam, sofort mit ZapNode eine konsistente Datenstruktur herzustellen und dann so bald wie möglich das Anwendungsprogramm mit einer Fehlermeldung zu beenden. ZapNode ist die einzige Funktion, die auf einen strukturell zerstörten Block angewendet werden darf, da sie den Datenbereich neu initialisiert, ohne ihn vorher auszulesen. Ist nicht der Datenbereich, sondern der Header oder die CxiTree-Struktur defekt, so kann auch ZapNode die Konsistenz nicht wiederherstellen.

Die C++-Funktion Validate ist die umfangreichste Variante dieser Testfunktion. Sie überprüft alle Komponenten des Objekts. Dazu wird neben der spezifischen Prüfung auch intern cxiValidateHandle aufgerufen. Ebenso greift cxiValidateHandle nach Durchführung der eigenen Tests unter anderem auf cxiValidateDataPtr zurück. Die Struktur CxiDataBlock ist die Basisstruktur zur Aufnahme der Daten eines CXI-Knotens; cxiValidateDataPtr wird in erster Linie für die interne Überprüfung der aus Datei gelesenen Daten im CxiTreeFile verwendet.

Um einen Anhaltspunkt für die Fehlerursache zu liefern, besitzt Validate einen großen eigenen Fehlernummernkreis, die Nummern liegen zwischen cxiErrorValidateBegin und cxiErrorValidateEnd.

Die meisten Konstanten sind in drei Varianten vorhanden:
cxiErrorValidate...: Fehler im Datenbereich des Blocks;
cxiErrorValidate...Arc: Fehler in Archivblöcken;
cxiErrorValidate...Init: Fehler in der CxiTree-Verwaltung.

Die drei Validate...-Funktionen können nicht alle Fehler eindeutig feststellen. Folgende Punkte sind zu beachten:

Vom CXI-System verwaltete Zeiger innerhalb der Struktur können lediglich auf NULL oder Segmentüberschreitung überprüft werden. Ein Zeiger, der auf einen im aktuellen Adressraum ungültigen Bereich zeigt, kann so nicht immer erkannt werden. Zeigervariablen (cxiTypePtr) werden grundsätzlich nicht überprüft.

Eventuell vorhandene registrierte Resourceblöcke werden von diesen Funktionen nicht berücksichtigt. Resource-Referenz-Variablen (cxiTypeRes) werden wie alle Variablen lediglich auf strukturelle Korrektheit überprüft, das Vorhandensein der entsprechenden Resource ist für Validate... irrelevant.

Ist der zu überprüfende Block Teil eines Baums, so wird nur dieses im Hauptspeicher befindliche Sichtfenster geprüft, nicht der gesamte CXI-Baum.

Mögliche Ursachen für cxiErrorValidate...-Fehler können sein:

Ein verschlüsselter Knoten eines CxiTreeFile konnte nicht korrekt entschlüsselt werden, wahrscheinlich ist das Schlüsselwort falsch. Die Lesefunktion des CxiTreeFile erkennt solche Fehler in der Regel automatisch und stellt eine konsistente Struktur wieder her, um unkontrollierbare Programmabstürze zu vermeiden.

Durch einen Zugriff über einen ungültigen Pointer innerhalb des Anwendungsprogramms wurde der Datenbereich des CXI-Knotens überschrieben. Dies stellt ein sehr schwer wiegendes Problem dar. Da es unwahrscheinlich ist, dass nur ein CXI-Knoten betroffen ist, sollte das Anwendungsprogramm unverzüglich alle Daten zwischensichern und sich beenden.

Validate ist kein Ersatz für IsValid und Status. IsValid()==0 besagt, dass ein schwerer Fehler aufgetreten ist und der INHALT des Blocks ungültig ist; dies heißt noch lange nicht, dass die STRUKTUR des Blocks zerstört ist. So kann bei IsValid()==0 ohne Probleme im Programm fortgefahren werden, während dies bei Validate()!=cxiNoError nicht empfehlenswert ist.

Portabilität:
Diese Funktion ist in allen unterstützten Systemen verfügbar.

Siehe auch:
CxiError - Fehlernummern

Beispiel:

#include <stdio.h>
#include "cxib.h"

int main ()
{
  CxiHandle cxi = cxiCreateCxiNodeStandard ();
  cxiSetStr (cxi, "EineVariable", "DerenWert");

  // Zerstörung der Blockstruktur
  // (Diese Zeile bitte nicht merken!)
  ((char *) cxiQueryDataPtr (cxi)) [10] = 0;

  // Überprüfung der Blockstruktur,
  // sollte cxiErrorValidateNameZero ergeben
  printf ("Validate = %d\n", cxiValidateHandle (cxi));

  // ... die empfohlene Fehlerbehandlung:
  cxiDeleteAllPrefix (cxi, 0);   // C-Version von ZapNode()

  cxiDeleteCxiNode (cxi);
  return 0;
}