READLOB

READLOB

ALL
(operand1)

[IN] [FILE] view-name
  [PASSWORD=operand2]
  [CIPHER=operand3]
  [[WITH] ISN [=] operand4]
  [[STARTING] [AT] OFFSET [=] operand5]
  statement
END-READLOB (structured mode only)
LOOP (reporting mode only)

Dieses Dokument behandelt folgende Themen:

Eine Erläuterung der in dem Syntax-Diagramm verwendeten Symbole entnehmen Sie dem Abschnitt Syntax-Symbole.

Verwandte Statements: READ | FIND | GET

Gehört zur Funktionsgruppe: Datenbankzugriffe und Datenbankänderungen

Funktion

Das Statement READLOB wird bei einem einzelnen Datensatz verwendet, bei dem das definierte LOB-Feld (LOB = Large OBject) während der Schleifenausführung in festgelegten Segmenten gelesen wird.

Zu Beginn der Schleife wird der Versatz (Offset) innerhalb des LOB-Feldes gesetzt, ab dem die ersten Daten gelesen werden sollen. Bei der nächsten Schleifen-Iteration wird das Segment zurückgegeben, das auf das zuletzt gelesene Segment folgt. Wenn das Ende der LOB-Daten erreicht ist, wird die Schleife beendet.

Dieses Statement leitet eine Verarbeitungsschleife ein. Siehe auch Schleifenverarbeitung im Leitfaden zur Programmierung.

Einschränkungen

Das Statement READLOB kann nur für den Zugriff auf Adabas-Datenbanken benutzt werden.

Syntax-Beschreibung

Operanden-Definitionstabelle:

Operand Mögliche Struktur Mögliche Formate Referenzierung erlaubt Dynam. Definition
operand1 C S           N P I B *               ja nein
operand2 C S       A                         ja nein
operand3 C S           N                     ja nein
operand4 C S           N P I B *               ja nein
operand5 C S           N P I B *               ja nein

* Format B von operand1, operand4 und operand5 kann mit einer Länge von kleiner gleich 4 benutzt werden.

Syntax-Element-Beschreibung:

Syntax-Element Beschreibung
operand1
Anzahl der zu lesen LOB-Segmente:

Die Anzahl der durchzuführenden Schleifenverarbeitungen kann durch Angabe von operand1 (in Klammern, unmittelbar nach dem Schlüsselwort READLOB eingeschränkt werden., und zwar entweder als numerische Konstante (0 - 4294967295) oder als Name einer numerischen Variable.

Beispiel:

READLOB (5) IN FILE VIEW01 ...
#CNT := 10
READLOB (#CNT) IN FILE VIEW01 ...

Für dieses Statement hat das hier angegebene Limit Vorrang vor einem Limit, welches mit dem LIMIT-Statement gesetzt wurde. Falls mit dem Profil- oder Session-Parameter LT ein kleineres Limit gesetzt ist, gilt das LT-Limit.

Anmerkung:
Die Auswertung von operand1 erfolgt beim Start des READLOB-Statements. Wird der Wert von operand1 während der READLOB-Schleife geändert, hat dies keine Auswirkung auf die Anzahl der Schleifenausführungen.

ALL
ALL-Option:

Sie können wahlweise das Schlüsselwort ALL angeben, um zu verdeutlichen, dass die Daten des LOB-Feldes bis zum Ende gelesen werden sollen.

Wenn Sie operand1 und ALL weglassen, wird die ALL-Option standardmäßig verwendet.

view-name
View-Name:

Als view-name geben Sie den Namen eines View an, der entweder mit einem DEFINE DATA-Statement oder außerhalb des Programms in einer Global oder Local Data Area definiert worden sein muss.

  • Der View darf nur ein LOB-Feld mit einem einzigen Wert enthalten, zusätzliche Felder sind nicht zulässig.

  • Falls das LOB-Feld ein MU- oder PE-Feld ist, muss eine einzige Ausprägung angegeben sein; es ist keine Bereichsnotation zulässig.

  • Das LOB-Feld muss in dem DDM mit einer festen (nicht dynamischen) Länge definiert sein, welche die Segmentlänge des LOB-Feldes darstellt..

PASSWORD=operand2
CIPHER=operand3

PASSWORD- und CIPHER-Klauseln:

Die PASSWORD-Klausel dient zur Angabe eines Passwortes, wenn Daten aus einer passwortgeschützten Datei gelesen werden sollen.

Die CIPHER-Klausel dient zur Angabe eines Chiffrierschlüssels, wenn Daten aus einer verschlüsselten Datei gelesen werden sollen.

Weitere Informationen siehe Statements FIND und PASSW.

WITH ISN=operand4
WITH ISN-Option:

Diese Option dient zur Angabe der internen Folgenummer (ISN) des Datensatzes, auf den das READLOB-Statement zugreifen soll. Während der gesamten Schleifenausführung wird nur dieser Datensatz gelesen.

operand4 muss entweder in Form einer numerischen Konstante oder als eine benutzerdefinierte Variable oder über die Natural-Systemvariable *ISN angegeben werden. Das Feld wird durch die Ausführung des READLOB-Statements nicht verändert.

Anmerkung:
Die Auswertung von operand4 erfolgt beim Start des READLOB-Statements. Wird der Wert von operand4 innerhalb der READLOB-Schleife geändert, hat das keine Auswirkung auf den zurzeit gelesenen Datensatz.

Wird diese Option nicht angegeben, dann wird standardmäßig das *ISN-Feld des zuletzt aktiven Datenbank-Statements verwendet.

STARTING AT OFFSET=operand5
STARTING AT OFFSET-Klausel:

Dient zur Angabe des Start-Offset innerhalb des LOB-Feldes, d.h., ab wo das Lesen des ersten Segments beginnen soll. Das erste Byte des LOB-Feldes hat den Versatz Null (0).

operand5 muss entweder in Form einer numerischen Konstante oder als benutzerdefinierte Variable ohne Dezimalstellen angegeben werden. Das Feld wird durch die Ausführung des READLOB-Statements nicht verändert.

Wird die Klausel nicht angegeben, dann wird Null (0) als Start-Versatz angenommen, was zur Folge hat, dass das LOB-Feld ab dem Feldanfang gelesen wird.

Siehe auch *NUMBER während der Schleifenverarbeitung, die im Abschnitt Bei READLOB vorhandene Systemvariablen weiter unten beschrieben wird.

END-READLOB
Ende des READLOB-Statements:

Im Structured Mode muss das für Natural reservierte Schlüsselwort END-READLOB zum Beenden des READLOB-Statements benutzt werden.

Im Reporting Mode wird das Natural-Statement LOOP zum Beenden des READLOB-Statements benutzt.

LOOP

Bei READLOB verfügbare Systemvariablen

Beim READLOB-Statement stehen die Natural-Systemvariablen *ISN, *COUNTER und *NUMBER zur Verfügung.

Format/Länge dieser Systemvariablen ist P10. Die Format/Länge-Werte können nicht geändert werden.

In der folgenden Tabelle wird die Verwendung dieser Natural-Systemvariablen in Verbindung mit dem READLOB-Statement erläutert:

Systemvariable Erläuterung
*ISN Enthält die Adabas-interne Folgenummer (ISN) des Datensatzes, der zurzeit verarbeitet wird. Das mit einem READLOB-Statement immer auf denselben Datensatz zugreift, bleibt der von der Systemvariablen über alle Schleifen-Iterationen zurückgegebene Wert immer derselbe.
*COUNTER Enthält die Anzahl der durchlaufenen Verarbeitungsschleifen.
*NUMBER Diese Systemvariable wird zweifach verwendet:
Vor dem Aufruf: Die Systemvariable gibt den Byte-Offset im LOB-Feld an, ab dem das Segment gelesen werden soll. Der Wert Null (0) stellt das Byte am linken Rand des LOB-Feldes dar.

Dies gilt nicht bei der ersten Schleifen-Iteration. In diesem Fall wird der Lese-Offset durch die STARTING AT OFFSET-Klausel bestimmt.

Nach dem Aufruf: Wenn die Daten gefunden wurden (d.h., der Offset war kleiner als die Länge des LOB-Feldes), erhält die Systemvariable den Offset-Wert plus die Segmentlänge. Das kann zu einem *NUMBER-Wert führen, der größer ist als die Länge des gesamten LOB-Feldes.

Falls keine Daten gefunden wurden (d.h., der Offset war größer als die oder gleich der Länge des LOB-Feldes), bleibt der Wert der Systemvariablen *NUMBER unverändert.

Falls ein konsekutives Lesen über ein LOB-Feld angefordert wird, darf der *NUMBER-Wert innerhalb des READLOB-Statements nicht geändert werden, da *NUMBER den Offset für die exakte Fortsetzung mit dem nächsten Segment in der darauffolgenden Schleifen-Iteration enthält. Falls jedoch eine Fortsetzung an einer anderen Stelle innerhalb des LOB-Feldes (Neupositionierung) gewünscht wird, können Sie den *NUMBER-Wert auf diesen Offset ändern. Wird *NUMBER zurückgesetzt, hat dies zur Folge, dass das nächste Segment vom LOB-Anfang kommt. Wird *NUMBER um (n) erhöht, wird die entsprechende Anzahl Bytes bei der LOB-Feldverarbeitung übersprungen.

Funktionstechnische Überlegungen

  • Das READLOB-Statement liest den Datensatz immer ohne Hold (Sperre). Um die Stabilität der LOB-Daten während der Durchsuchung des Feldes durch das READLOB-Statement sicherzustellen (d.h. zur Vermeidung einer Aktualisierung durch andere Benutzer), kann der Datensatz mit dem Datenbank-Statement, welches den ISN-Wert liefert, in den Hold-Status gesetzt werden, und zwar

    • in einen Exclusive Hold bedingt durch ein UPDATE- oder DELETE-Statement, welches sich auf ein äußeres READ- oder FIND-Statement bezieht, oder

    • in einen Shared Hold mit einer IN SHARED HOLD-Option, die in einem READ- oder FIND-Statement angewendet wird.

  • Da das READLOB-Statement den Datensatz immer ohne Hold (Sperre) liest, darf sich ein UPDATE-, DELETE- oder GET SAME-Statement nicht auf ein READLOB-Statement beziehen.

Beispiele

Beispiel 1 - Datensatznummer aus der READ-Schleife holen

DEFINE DATA LOCAL
1 VIEW01 VIEW OF ..
  2 NAME 
  2 L@LOBFIELD
1 VIEW02 VIEW OF ..
  2 LOBFIELD_SEGMENT                /* LOB field defined in DDM with (A1000).
END-DEFINE
*
READ VIEW01 BY NAME = 'SMITH'       /* Outer statement reads all demanded record 
                                    /* fields, except the LOB field.
     IN SHARED HOLD MODE=Q          /* Set record into shared hold to enforce LOB 
                                    /* data stability during READLOB.
  DISPLAY NAME 'Total-length LOB-field' L@LOBFIELD 
  READLOB VIEW02                    /* Record number used from active record of 
                                    /* READ statement.
                                    /* LOB is read in segments with length 1000. 
      STARTING AT OFFSET = 2000     /* Start to read the LOB field at byte 2000.
    WRITE 'Loop counter:' *COUNTER  10X ' Next offset:' *NUMBER
    PRINT VIEW02.LOBFIELD_SEGMENT  
  END-READLOB
END-READ   
END

Beispiel 2 - Datensatznummer über benutzerdefinierte Variable holen 

DEFINE DATA LOCAL
1 #ISN  (I4)
1 #CNT  (I4)
1 #OFF  (I4)
1 VIEW02 VIEW OF ..
  2 LOBFIELD_SEGMENT            /* LOB field defined in DDM with (A1000).
END-DEFINE
*
INPUT (AD=T)
  / ' Read record (ISN):' #ISN
  / 'Number of segments:' #CNT
  / '   Start at offset:' #OFF
* 
READLOB (#CNT) VIEW02           /* Read max. (#CNT) segments with length 1000.
    WITH ISN = #ISN             /* Record number provided by user.
                                /* Record is not in hold.
    STARTING AT OFFSET = #OFF   /* Start to read the LOB field at byte (#OFF).
  WRITE 'Loop counter:' *COUNTER  10X ' Next offset:' *NUMBER
  PRINT VIEW02.LOBFIELD_SEGMENT  
END-READLOB
END

Beispiel 3 - Datensatznummer aus der READ-Schleife holen/ mit Exclusive Hold) 

DEFINE DATA LOCAL
1 VIEW01 VIEW OF ..
  2 NAME 
1 VIEW02 VIEW OF ..
  2 LOBFIELD_SEGMENT                 /* LOB field defined in DDM with (A1000).
END-DEFINE
*
R1. READ VIEW01 BY NAME = 'SMITH'    /* Outer statement reads all demanded record fields, 
                                     /* except the LOB field.
  DISPLAY NAME 
  READLOB VIEW02                     /* Record number used from active record of READ stmt. 
                                     /* LOB is read in segments with length 1000. 
      STARTING AT OFFSET = 2000      /* Start to read the LOB field at byte 2000. 
    WRITE 'Loop counter:' *COUNTER  10X ' Next offset:' *NUMBER
    PRINT VIEW02.LOBFIELD_SEGMENT  
  END-READLOB
  ...
  UPDATE (R1.)                       /* Set record into exclusive hold that enforces LOB 
                                     /* data stability during READLOB.
  END OF TRANSACTION
END-READ   
END