Zum Hauptinhalt springen

C16_RecRead64

C16_RecRead64(const vPHANDLE aInstHdl, const vINT aFileNo, const vXLONG aKeyNo, const vFLAGS aFlags, const vXLONG aAddInfo) : vERROR​

Datensatz lesen

Details

Liest einen Datensatz und überträgt ihn in die Feldpuffer.

Im Parameter (aInstHdl) wird der von C16_InitInstance() bereitgestellte Instanz-Handle, der in der Funktion C16_OpenArea() zum Öffnen der Datenbank verwendet wurde, übergeben. Die Funktion führt einen Zugriff über den Schlüssel (aKeyNo) in die Datei (aFileNo) durch. Der Schlüssel wird aus den aktuellen Feldinhalten der Datei gebildet. Ist kein Datensatz mit dem entsprechenden Schlüssel vorhanden, so wird der Datensatz mit dem nächst größeren bzw. dem größten Schlüssel geladen. Nach dem erfolgreichen Aufruf der Funktion, steht der gelesene Datensatz in den Feldpuffern.

Soll auf eine Selektionsmenge zugegriffen werden, wird in dem Parameter (aKeyNo) der in Ganzzahlig gewandelte Selektionsdeskriptor übergeben. Der Selektionsdeskriptor muss zuvor mit C16_SelOpen() angelegt worden sein.

Die Zugriffsposition wird über den Parameter (aFlag) angegeben. Folgende symbolische Konstanten können angegeben werden:

  • 0: Ausgehend vom Inhalt der Feldpuffer wird genau der angegebene Datensatz gelesen. Der Rückgabewert des Befehls ist dann abhängig, ob über einen eindeutigen oder mehrdeutigen Schlüssel gelesen wurde _rOk oder _rMultiKey. Eine Satzsperre beeinflusst den Rückgabewert nicht. Konnte aus dem Inhalt der Schlüsselfelder kein vorhandener Schlüsselwert gebildet werden, wird der darauf folgende Datensatz gelesen. In diesem Fall gibt der Befehl den Wert _rNoKey zurück. Gibt es keinen nachfolgenden Datensatz, wird der letzte Datensatz gelesen. Zurückgegeben wird dann der Wert _rLastRec. Konnte kein Datensatz gelesen werden (d. h. die Datei ist leer), wird der Wert _rNoRec zurückgegeben.
  • _RecFirst: Der Satz mit dem kleinsten Schlüsselwert wird gelesen.
  • _RecLast: Der Satz mit dem größten Schlüsselwert wird gelesen.
  • _RecNext: Der Satz mit dem nächst größeren Schlüsselwert wird geladen. Sofern kein weiterer Satz vorhanden ist, wird als Resultat _rNoRec zurückgeliefert.
  • _RecPrev: Der Satz mit dem nächst kleineren Schlüsselwert wird geladen. Sofern kein weiterer Satz vorhanden ist, wird als Resultat _rNoRec zurückgeliefert.
  • _RecKeyReverse: Die Schlüsselreihenfolge in der mit _RecPrev, _RecNext und _RecPos zugegriffen wird, kann mit dieser Konstanten umgekehrt werden.
  • _RecID: Anstatt über einen Schlüssel wird der Datensatz über die Datensatz-ID gelesen. In (aKeyNo) darf kein Schlüssel oder Selektionsdeskriptor übergeben werden. Die Datensatz-ID kann zuvor mit der Anweisung C16_RecInfo64(..., _RecID) ermittelt. Im Parameter (aAddInfo) muss die zu lesende Datensatz-ID übergeben werden.
  • _RecPos: Anstatt über den aktuellen Schlüsselwert wird über die Schlüsselposition zugegriffen. Die Position wird in (aAddInfo) übergeben. Diese Position wird aus nur ungefähr berechnet, da eine genaue Positionierung zu lange dauern würde.
  • _RecUnlock: Der gelesene Satz wird entsperrt.
  • _RecLock: Der gelesene Satz wird gesperrt. Dies ist nur dann der Fall, wenn _rOk zurückgeliefert wird (eindeutiger Schlüssel). Ist der Satz durch einen anderen Benutzer gesperrt, so ist das Resultat _rLocked.
  • _RecSingleLock: Der gelesene Satz wird gesperrt. Dies ist nur dann der Fall, wenn _rOk zurückgeliefert wird (eindeutiger Schlüssel). Ist der Satz durch den eigenen oder einen anderen Benutzer gesperrt, ist das Resultat _rLocked. Das Sperren eines Datensatzes erfolgt über die Benutzer-ID. Mit _RecSingleLock wird der gleiche Datensatz für den gleichen Benutzer nur einmal gesperrt. Beim Versuch, denselben Satz ein zweites Mal zu sperren, wird das Resultat _rLocked zurückgeliefert.
  • _RecSharedLock: Der gelesene Datensatz wird gemeinsam mit anderen Benutzern gesperrt. Dies ist nur dann der Fall, wenn _rOk zurückgeliefert wird (eindeutiger Schlüssel). Ist der Satz durch einen anderen Benutzer gesperrt, ist das Resultat _rLocked. Im Gegensatz zur Option _RecLock können von anderen Benutzern weitere Sperren mit dieser Option eingerichtet werden. Ein mit _RecSharedLock gesperrter Datensatz kann von einem anderen Benutzer nicht mit der Option _RecLock zum Schreiben gesperrt werden, bis die letzte Sperre aufgehoben wurde. Der Benutzer, der die gemeinsame Sperre eingerichtet hat, kann den Datensatz nur dann mit _RecLock sperren, wenn in der Zwischenzeit kein anderer Benutzer eine gemeinsame Sperre eingerichtet hat. Mit dieser Option können mehrere Benutzer einen Datensatz vor Veränderung schützen. Der Datensatz kann mit dieser Sperre nicht zurückgeschrieben werden.
  • _RecForceLock: Der gelesene Satz wird gesperrt, ohne Rücksicht auf eine Sperre durch einen anderen Benutzer. Die Sperre ist nur dann erfolgt, wenn _rOk zurückgeliefert wird. Wenn ein anderer Benutzer den Satz gesperrt haben sollte, so kann dieser Benutzer den Satz nicht mehr zurückspeichern. Daher sollte _RecForceLock nur in den Fällen erfolgen, in denen ein Satz unbedingt und ohne Rücksicht auf andere Benutzer gesperrt werden muss. Die Sperre schlägt fehl, wenn der Datensatz durch andere Benutzer gemeinsam (_RecSharedLock) gesperrt ist oder der Datensatz in diesem Moment gerade geschrieben oder gelöscht wird. Wird _rLocked zurückgegeben, kann der Befehl nach kurzer Zeit erneut versucht werden. Fahrlässiger Umgang mit dieser Option kann zur Inkonsistenz des Datenbestandes führen.
  • _RecCheckLock: Der Sperrstatus des Satzes wird überprüft. Das Resultat ist _rLocked anstelle von _rOk, wenn ein anderer Benutzer den Satz gesperrt hat. Der Sperrstatus wird nicht verändert.
  • _RecTest: Hierbei erfolgt der Zugriff nur auf den Schlüssel. Es wird nicht auf den Datensatz zugegriffen, daher ist die Angabe einer Sperroption ohne Wirkung.
  • _RecNoLoad: Der gelesene Datensatz wird nicht in die Feldpuffer übertragen.

Der Parameter (aAddInfo) ist optional, er hat zwei verschiedene Bedeutungen. Bei der Benutzung der Option _RecPos wird hier die gewünschte Schlüsselposition übergeben. Bei der Option _RecID wird die ID des gewünschten Satzes übergeben. Die Optionen _RecTest und _RecPos sind dabei nicht möglich, da kein Schlüsselzugriff erfolgt. Dadurch gibt es auch die Resultate _rNoKey und _rMultiKey nicht. Ist der Satz mit der angegebenen ID nicht vorhanden, so wird _rNoRec zurückgeliefert und kein Satz geladen.

Soll der Datensatz aus einer Selektionsmenge gelesen werden, wird anstelle der Schlüsselnummer (aKeyNo) der Deskriptor des Selektionspuffers angegeben. Dabei muss ein Cast des Deskriptors auf vINT verwendet werden.

Der Erfolg der Datensatzoperation wird von der Funktion zurückgegeben. Bei der Überprüfung können folgende symbolische Konstanten verwendet werden:

  • 0: _rOK Datensatzoperation erfolgreich.
  • 1: _rLocked Datensatz ist vorhanden und von einem anderen Benutzer gesperrt. Der Satz wurde geladen, sofern die Option _RecNoLoad nicht angegeben wurde.
  • 2: _rMultiKey Der Schlüssel ist nicht eindeutig. In der Datei sind mehrere Sätze mit dem gewünschten Schlüsselwert vorhanden, der erste Satz wurde geladen.
  • 3: _rNoKey In der Datei ist kein Satz mit dem gewünschten Schlüsselwert vorhanden. Es wurde der Satz mit dem nächst größeren Schlüsselwert geladen.
  • 4: _rLastRec In der Datei ist weder ein Satz mit dem gewünschten Schlüsselwert noch ein Satz mit einem größeren Schlüsselwert vorhanden. Es wurde der Satz mit dem größten Schlüsselwert geladen.
  • 5: _rNoRec Es wurde kein Satz geladen, da entweder die Datei leer ist, oder kein vorhergehender bzw. nachfolgender Satz existiert.