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:

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

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