UPDATELOB

#### Search Results

Search

# UPDATELOB

`UPDATELOB` [`OF`] [`RECORD`] [(r)] [`IN`] [`FILE`] view-name
[`PASSWORD`=operand1]
[`CIPHER`=operand2]
[[`STARTING`] [`AT`] `OFFSET` [=] operand3]
| `TRUNCATE` |  | [`REMAINDER`] [`AT`] `OFFSET` |  |

Dieses Dokument behandelt folgende Themen:

- Funktion

- Einschränkungen

- Syntax-Beschreibung

- Bei UPDATELOB verfügbare Systemvariable

- Funktionstechnische Überlegungen

- Beispiele

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

Verwandte Statements: `READ` | `FIND` | `GET` | `READLOB` | `UPDATE`

Gehört zur Funktionsgruppe: Datenbankzugriffe und Datenbankänderungen

## Funktion

Das Statement `UPDATELOB` dient zum Aktualisieren eines Datensegments eines LOB-Feldes (LOB = Large OBject) in einem Datenbankdatensatz. Die Stelle, an der die Wertänderung ausgeführt wird, kann frei gewählt werden. Der zu aktualisierende Datensatz muss zuvor mit einem `FIND`-, `READ`-, `GET`-Statement ausgewählt oder mit einem `STORE`-Statement angelegt worden sein.

### Hold-Status

Die Verwendung des `UPDATELOB`-Statements bewirkt, dass jeder für die Verarbeitung im entsprechenden `FIND`-, `READ`-, `GET`-Statement gelesene Datensatz in exklusiven Hold gesetzt wird.

Weitere Informationen siehe Datensatz-Kontrolle während einer Transaktion (Hold-Logik) im Leitfaden zur Programmierung.

## Einschränkungen

Das `UPDATELOB`-Statement

- kann nur für den Zugriff auf Adabas-Datenbanken benutzt werden;

- darf nicht in der Zeile angegeben werden, in der das zur Auswahl des zu aktualisierenden Datensatzes benutzte Statement steht;

- ist nur für die Aktualisierung eines einzelnen LOB-Feldes verwendbar.

## Syntax-Beschreibung

Operanden-Definitionstabelle:

Operand | Mögliche Struktur | Mögliche Formate | Referenzierung erlaubt | Dynam. Definition
--- | --- | --- | --- | ---
`operand1` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  |  | yes | no
`operand2` | C | S |  |  |  |  |  | N |  |  |  |  |  |  |  |  |  |  | yes | no
`operand3` | C | S |  |  |  |  |  | N | P | I |  | B * |  |  |  |  |  |  | yes | no

* Format B von `operand3` kann mit einer Länge von kleiner gleich 4 benutzt werden.

Syntax-Element-Beschreibung:

Syntax-Element | Beschreibung
--- | ---
`(r)` | Statement-Referenzierung: Die Notation `(r)` können Sie benutzen, um das Statement anzugeben, in dem der Datensatz gelesen oder erstellt wurde. `r` kann als Statement-Label oder Quellcode-Zeilennummer angegeben werden. Sie können ein `FIND`-, `READ`-, `GET`- oder `STORE`-Statement referenzieren. Falls Sie keine Referenzierung angeben, bezieht sich das `UPDATELOB`-Statement auf die innerste aktive `READ`- bzw. `FIND`-Verarbeitungsschleife. Ist keine `READ`- oder `FIND`-Schleife aktiv, bezieht es sich auf das letzte vorhergehende `GET`-Statement. Um ein `STORE`-Statement zu referenzieren, müssen Sie immer `(r)`-Notation verwenden. Anmerkung Das `UPDATELOB`-Statement muss innerhalb der `READ`- bzw. `FIND`-Statementschleife stehen, auf die es sich bezieht.
`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 eindeutige Ausprägung angegeben sein; es ist keine Bereichsnotation zulässig. Das LOB-Feld muss in dem View mit einer festen (nicht dynamischen) Länge definiert sein.
`PASSWORD=operand1` `CIPHER=operand2` | PASSWORD-Klausel und CIPHER-Klausel: 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`.
`STARTING AT OFFSET=operand3` | STARTING AT OFFSET-Klausel: Dient zur Angabe des Startversatzes (Offset) innerhalb des LOB-Feldes, ab wo die Operation ausgeführt werden soll. Das höchstwertige Byte des LOB-Feldes hat den Offset Null (`0`). `operand3` muss entweder in Form einer numerischen Konstante oder als benutzerdefinierte Variable ohne Genauigkeitsziffern angegeben werden. Das Feld wird durch die Ausführung des `UPDATELOB`-Statements nicht verändert. Falls der Versatzwert größer als die LOB-Feldlänge ist, wird die Lücke mit Leerzeichen aufgefüllt. Das bedeutet, dass ein LOB-Feld an einer Stelle jenseits seiner Länge aktualisiert werden kann. Wird die Klausel nicht angegeben, dann wird Null (`0`) als Start-Offset angenommen.
`TRUNCATE REMAINDER` oder `TRUNCATE AT OFFSET` | TRUNCATE-Klausel: Wenn Sie `TRUNCATE REMAINDER` angeben, werden die restlichen LOB-Felddaten abgeschnitten, nachdem das neue Segment in das LOB-Feld geschrieben worden ist. Dadurch wird das Ende des eingefügten Segments zum Ende des LOB-Feldes gemacht. Wenn Sie `TRUNCATE AT OFFSET` angeben, werden die Daten nach dem angegebenen Startversatz abgeschnitten. Es erfolgt keine Segmenteinfügung in das LOB-Feld. Danach ist die LOB-Feldlänge gleich `operand3`. Wird die Klausel weggelassen, bleiben die Daten nach dem eingefügten Segment erhalten.

## Bei UPDATELOB verfügbare Systemvariable

Beim `UPDATELOB`-Statement steht die Natural-Systemvariable `*NUMBER` zur Verfügung.

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

Systemvariable | Erläuterung
--- | ---
`*NUMBER` | Die Systemvariable `*NUMBER` gibt die Summe aus Startversatz und Anzahl der eingefügten Zeichen zurück. Dieser Wert stellt den Startversatz für das nächste `UPDATELOB` dar, wenn ein darauffolgender Bereich des LOB-Feldes mittels mehrerer Aufrufe ersetzt wird. Die Anzahl der eingefügten Zeichen ist entweder die Byte-Länge des im View definierten LOB-Segments oder Null (`0`), falls die `TRUNCATE AT OFFSET`-Klausel angegeben wurde. Wenn es benutzt wird, muss das durch das `UPDATELOB`-Statement zurückgegebene `*NUMBER`-Feld immer mit einem Referenz-Label oder einer Referenzzeilennummer versehen sein, zum Beispiel `*NUMBER(0430)`.

## Funktionstechnische Überlegungen

- Ein `UPDATELOB` bearbeitet eine Datensatz, der durch ein zugehöriges `FIND`-, `READ`-, `GET`- oder `STORE`-Statement in den Hold-Zustand gesetzt worden ist. Die Verbindung ist entweder implizit über die zurzeit aktive Referenzierung oder explizit mit `(r)`-Notation.

- Der von dem zugehörigen Statement benutzte View und der vom `UPDATELOB`-Statement benutzte View müssen auf dieselbe Datenbank- und Dateinummer zugreifen. Dies ist automatisch sichergestellt, wenn die Views vom selben DDM abgeleitet werden.

- Falls der in `operand3` angegebene Wert für die Einfügeposition größer als die LOB-Länge ist, wird die Lücke mit Leerzeichen aufgefüllt. Das bedeutet, dass Sie ein LOB-Feld an einer Stelle aktualisieren können, die jenseits seiner Länge liegt.

- Sie können nicht m Bytes durch n Bytes ersetzen - oder anders ausgedrückt: Es ist nicht zulässig, einen LOB-Teil durch ein Datensegment zu ersetzen, das eine andere Länge hat.

- Der durch die Systemvariable `*NUMBER` zurückgelieferte Wert ist die höchste Zuordnungsmarke, welche die Position innerhalb des LOB angibt, an der die letzte Einfügung endete. Wenn eine Anzahl aufeinanderfolgender Aktualisierungen gefordert wird, sollte dieser Wert immer als `STARTING AT`-Wert für die nächste `UPDATELOB`-Ausführung beibehalten werden.

## Beispiele

- Beispiel 1 - Neuen Datensatz abspeichern und LOB-Segment auffüllen

- Beispiel 2 - LOB-Daten stückweise zu einem vorhandenen Datensatz hinzufügen

- Beispiel 3 - LOB-Feld abschneiden

- Example 4 - LOB-Daten in existenten Datensatz lesen und LOB-Segment aktualisieren

### Beispiel 1 - Neuen Datensatz abspeichern und LOB-Segment auffüllen

    DEFINE DATA LOCAL
    1 V1 VIEW OF ..
      2 PERSONNEL-ID
      2 NAME
    1 V2 VIEW OF ..
      2 LOBFIELD_SEGMENT  /* LOB field defined in DDM with (A1024).
    END-DEFINE
    *
    **===================================================
    ** Store new record
    **===================================================
    V1.PERSONNEL-ID := '12345678'
    V1.NAME         := 'Smith'
    LAB1.
    STORE V1   /* Store new record with 2 fixed length fields.
    *
    MOVE ALL 'X' TO LOBFIELD_SEGMENT
    **===================================================
    ** Update LOB field
    **===================================================
    UPDATELOB (LAB1.) IN FILE V2    /* Insert segment of 1KB (LOBFIELD_SEGMENT) in LOB.
         STARTING AT OFFSET = 2048  /* Store data in LOB range 2049-3072.
                                    /* The first 2KB are auto filled with blanks by the database.
    END TRANSACTION
    END

### Beispiel 2 - LOB-Daten stückweise zu einem vorhandenen Datensatz hinzufügen

    DEFINE DATA LOCAL
    1 V1 VIEW OF EMPLOYEES-V2009
      2 PERSONNEL-ID
      2 NAME
      2 L@PICTURE
    1 V2 VIEW OF EMPLOYEES-V2009
      2 PICTURE_SEGMENT  /* LOB field defined in DDM with (A1024).
      2 REDEFINE PICTURE
        3 PICTURE_B (B1024)
    1 #OFF   (I4)
    END-DEFINE
    *
    **===================================================
    ** Read record to be updated
    **===================================================
    LAB1.
    READ (1) V1 BY PERSONNEL-ID = '60008339' /* Read record and set into exclusive hold.
      RESET #OFF                  /* Start to overwrite LOB field from the beginning.
      /*===================================================
      /* Read data from work file and put into LOB field
      /*===================================================
      READ WORK FILE 7 PICTURE_B  /* Start to read picture data (.jpg) from work file.
    LAB2.
        UPDATELOB (LAB1.) IN FILE V2
                  STARTING AT OFFSET #OFF
        #OFF := *NUMBER(LAB2.)    /* Keep next position to append.
      END-WORK
    END-READ
    **===================================================
    END TRANSACTION
    END

### Beispiel 3 - LOB-Feld abschneiden

    DEFINE DATA LOCAL
    1 V1 VIEW OF EMPLOYEES-V2009
      2 PERSONNEL-ID
      2 NAME
      2 L@PICTURE
    1 V2 VIEW OF EMPLOYEES-V2009
    1 V3 VIEW OF EMPLOYEES-V2009
      2 PICTURE_SEGMENT   /* LOB field defined in DDM with (A1024).
    END-DEFINE
    *
    **===================================================
    ** Read record to be updated
    **===================================================
    LAB1.
    READ V1 BY PERSONNEL-ID        /* Read records.
      IF L@PICTURE > 10240 THEN    /* Check if LOB length is too high.
    LAB2.
        GET V2 RECORD *ISN(LAB1.)  /* Set record to be updated into exclusive hold.
        UPDATELOB (LAB2.) IN FILE V3
                  STARTING AT OFFSET 10240
                  TRUNCATE AT OFFSET         /* Truncate LOB data beyond 10KB.
        END TRANSACTION
      END-IF
    END-READ
    END

### Example 4 - LOB-Daten in existenten Datensatz lesen und LOB-Segment aktualisieren

    DEFINE DATA LOCAL
    1 V1 VIEW OF ..
      2 NAME
    1 V2 VIEW OF ..
      2 DOCUMENT_SEGMENT      /* LOB field defined in DDM with (A100).
    1 #ISN    (I4)
    1 #POS    (I4)
    1 #LENGTH (I4) INIT <100>
    END-DEFINE
    *
    **===================================================
    ** Read record to be updated
    **===================================================
    INPUT (AD=T)
      / ' Read record (ISN):' #ISN
    *
    G1.
    GET V1 RECORD #ISN           /* Get record with ISN and set into exclusive hold.
    *
    **===================================================
    ** Read LOB data and update segment of LOB field
    **===================================================
    R1.
    READLOB V2 WITH ISN = #ISN
         STARTING AT OFFSET = 3000
       ..
       #POS := *NUMBER(R1.) - #LENGTH
       ..
       IF ..
         DOCUMENT_SEGMENT := ..
         UPDATELOB (G1.) IN FILE V2        /* Update current segment in LOB field.
                   STARTING AT OFFSET #POS
       END-IF
       ..
    END-READLOB
    *
    END TRANSACTION
    END

### On this page

- Funktion
- Einschränkungen
- Syntax-Beschreibung
- Bei UPDATELOB verfügbare Systemvariable
- Funktionstechnische Überlegungen
- Beispiele