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

This document covers the following topics:

- Function

- Restrictions

- Syntax Description

- System Variable Available with UPDATELOB

- Functional Considerations

- Examples

For an explanation 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

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

- Example 3 - Truncate LOB Field

- Example 4 - Read LOB Data to Existent Record and Update LOB Segment

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

### On this page

- Function
- Restrictions
- Syntax Description
- System Variable Available with UPDATELOB
- Functional Considerations
- Examples