READLOB

#### Search Results

Search

# 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:

- Funktion

- Einschränkungen

- Syntax-Beschreibung

- Bei READLOB verfügbare Systemvariablen

- Funktionstechnische Überlegungen

- Beispiele

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 einer View (Datensicht) an, die entweder mit einem `DEFINE DATA`-Statement oder außerhalb des Programms in einer Global oder Local Data Area definiert worden sein muss. Die 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

- Beispiel 2 - Datensatznummer über benutzerdefinierte Variable holen

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

### 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

### On this page

- Funktion
- Einschränkungen
- Syntax-Beschreibung
- Bei READLOB verfügbare Systemvariablen
- Funktionstechnische Überlegungen
- Beispiele