UPDATELOB

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

TRUNCATE

[REMAINDER]
[AT] OFFSET

This document covers the following topics:

For explanations of the symbols used in the syntax diagram, see Syntax Symbols.

Related Statements: READ | FIND | GET | READLOB | UPDATE

Belongs to Function Group: Database Access and Update

Function

The UPDATELOB statement is used to update a data segment of a LOB field (Large OBject field) in a database record. The position of the value modification is freely selectable. The record to be updated must have been previously selected with a FIND, READ or GET statement or created with a STORE statement.

Hold Status

The use of the UPDATELOB statement causes each record read for processing in the corresponding FIND, READ or GET statement to be placed in exclusive hold.

For further information, see Record Hold Logic in the Programming Guide.

Restrictions

The UPDATELOB statement

  • can only be used for access to Adabas databases;

  • must not be entered on the same line as the statement used to select the record to be updated;

  • is only applicable to update a single LOB field.

Syntax Description

Operand Definition Table:

Operand Possible Structure Possible Formats Referencing Permitted Dynamic Definition
operand1 C S       A                         yes no
operand2 C S           N                     yes no
operand3 C S           N P I   B *             yes no

* Format B of operand3 may be used with a length of less than or equal to 4.

Syntax Element Description:

Syntax Element Description
(r)
Statement Reference:

The notation (r) is used to indicate the statement in which the record to be modified was read or created. r may be specified as a source-code line number or as a statement label. You may reference a FIND, READ, GET or STORE statement.

If no reference is specified, the UPDATELOB statement will reference the innermost active READ or FIND processing loop. If no READ or FIND loop is active, it will reference the last preceding GET statement. To reference a STORE statement, you have always to provide the (r) notation.

Note:
The UPDATELOB statement must be placed within the READ or FIND loop it references.

view-name
View Name:

As view-name, you specify the name of a view, which must have been defined either within a DEFINE DATA statement or outside the program in a global or local data area.

  • The view has to contain just a single-valued LOB field, additional fields are not allowed.

  • If the LOB is a MU or PE field, a unique occurrence must be specified; a range notation is not allowed.

  • The LOB field must be defined in the view with a fixed (non-dynamic) length.

PASSWORD=operand1
CIPHER=operand2

PASSWORD and CIPHER Clauses:

The PASSWORD clause is used to provide a password when retrieving data from a file which is password-protected.

The CIPHER clause is used to provide a cipher key when retrieving data from a file which is enciphered.

See the statements FIND and PASSW for further information.

STARTING AT OFFSET=operand3
STARTING AT OFFSET Clause:

Provides the start offset within the LOB field, where the operation is executed. The leftmost byte of the LOB field is offset zero (0).

operand3 must be provided either in the form of a numeric constant or as a user-defined variable, without precision digits. The field is not modified by the UPDATELOB execution. If the offset value is greater than the LOB length, the gap is filled with blanks. This means a LOB field can be updated at a position which is beyond its length.

If this clause is omitted, start offset (0) is assumed.

TRUNCATE REMAINDER
or
TRUNCATE AT OFFSET

TRUNCATE Clause:

If TRUNCATE REMAINDER is specified, the remaining LOB field data is truncated after the new segment has been written into the LOB field. This makes the end of the inserted segment to the end of the LOB field.

If TRUNCATE AT OFFSET is specified, the data behind the specified starting offset is truncated. A segment insert into the LOB field is not performed. After this, the LOB length is equal to operand3.

If this clause is omitted, the data behind the inserted segment is preserved.

System Variable Available with UPDATELOB

The Natural system variable *NUMBER is provided with the UPDATELOB statement.

The format/length of this system variable is P10. This format/length cannot be changed.

System Variable Explanation
*NUMBER The system variable *NUMBER returns the sum of the start offset and the number of characters inserted. This value represents the starting offset for the next UPDATELOB, if a consecutive area of the LOB field is replaced with multiple calls.

The number of inserted characters is either the byte length of the LOB segment defined in the view or zero (0) if the TRUNCATE AT OFFSET clause was specified.

The *NUMBER field returned by the UPDATELOB statement must always be provided with a reference label or number (for example, *NUMBER(0430)) when used.

Functional Considerations

  • An UPDATELOB operates a record which was set into hold by an associated FIND, READ, GET or STORE statement. The link is either implicit via the current active reference or explicit with (r) notation.

  • The view used by the associated statement and the view used by the UPDATELOB have to access the same database and file number. This is automatically assured if the views are derived from the same data definition module (DDM).

  • If the insert position operand3 is greater than the LOB length, the gap is filled with blanks. This means you may update a LOB field at a position which is beyond its length.

  • You cannot replace m bytes with n bytes - or in other words, it is not admissible to substitute a LOB part with a data segment of different length.

  • The value returned with *NUMBER is the high-water mark indicating the position inside the LOB where the last insert has ended. If a number of consecutive update operations is demanded, this value should always be retained as STARTING AT value for the next UPDATELOB execution.

Examples

Example 1 - Store New Record and Fill LOB Segment

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 1 KB SEGMENT (LOBFIELD_SEGMENT)
                              /* IN LOB.                                
     STARTING AT OFFSET = 2048   
                   /* STORE DATA IN LOB RANGE 2049-3072.                
                   /* FIRST 2 KBS ARE AUTO-FILLED WITH BLANKS BY THE DB.
END TRANSACTION                                                         
END

Example 2 - Add LOB Data to Existent Record, Piece by Piece 

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

Example 3 - Truncate LOB Field

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 - Read LOB Data to Existent Record and Update LOB Segment 

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