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)

This document covers the following topics:

- READLOB Usage

- READLOB Restrictions

- READLOB Syntax Description

- System Variables Available with READLOB

- READLOB Functional Considerations

- READLOB Examples

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

Related Statements: `READ` | `FIND` | `GET` | `UPDATELOB`

Belongs to Function Group: Database Access and Update

## READLOB Usage

The `READLOB` statement is used on a single record, where the defined LOB field (Large OBject field) is read in fixed length segments during the loop processing. It is only applicable to read this LOB field.

At loop beginning, the offset inside the LOB field is set from where to get the first data. On the next loop iteration, the segment following the last segment is returned. If the LOB data end is reached, the loop terminates.

This statement causes a processing loop to be initiated. See also Loop Processing in the Programming Guide.

## READLOB Restrictions

The `READLOB` statement can only be used for access to Adabas databases.

## READLOB Syntax Description

Operand Definition Table:

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

* Format B of `operand1`, `operand4` and `operand5` may be used with a length of less than or equal to 4.

Syntax Element Description:

Syntax Element | Description
--- | ---
`operand1` | Number of LOB Segments to Be Read: The number of loop executions to be performed may be limited by specifying `operand1` (enclosed in parentheses, immediately after the keyword `READLOB`) - either as a numeric constant (`0` - `4294967295`) or as the name of a numeric variable. Example:
    READLOB (5) IN FILE VIEW01 ...
    #CNT := 10
    READLOB (#CNT) IN FILE VIEW01 ...
For this statement, the specified limit has priority over a limit set with a `LIMIT` statement. If a smaller limit is set with the profile or session parameter `LT`, the `LT` limit applies. Note `operand1` is evaluated when the `READLOB` is started. If the value of `operand1` is modified within the `READLOB` loop, this does not affect the number of loop iterations.
`ALL` | ALL Option: To emphasize that the LOB data is to be read until its end, you can optionally specify the keyword `ALL`. The `ALL` option is used by default if `operand1` and `ALL` are omitted.
`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 DDM with a fixed (non-dynamic) length (which represents the segment length of the LOB field).
`PASSWORD=operand2` `CIPHER=operand3` | 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.
`WITH ISN=operand4` | WITH ISN Option: This option is used to specify the ISN of the record which is accessed by the `READLOB` statement. During the complete loop execution, only this record is fetched. `operand4` must be provided either in the form of a numeric constant or as a user-defined variable, or via the Natural system variable `*ISN`. The field is not modified by the `READLOB` execution. Note `operand4` is evaluated when the `READLOB` is started. If the value of `operand4` is modified within the `READLOB` loop, this does not affect the record being fetched. If this option is omitted, the `*ISN` field of the last active database statement is used by default.
`STARTING AT OFFSET=operand5` | STARTING AT OFFSET Clause: Provides the start offset within the LOB field, where the first segment read begins. The first byte of the LOB field is offset zero (`0`). `operand5` 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 `READLOB` execution. If this clause is omitted, start offset (`0`) is assumed, which causes the LOB field to be read from the beginning. See also `*NUMBER` during the processing described in System Variables Available with READLOB below.
`END-READLOB` | End of READLOB Statement: In structured mode, the Natural reserved keyword `END-READLOB` must be used to end the `READLOB` statement. In reporting mode, the Natural statement `LOOP` is used to end the `READLOB` statement.
`LOOP`

## System Variables Available with READLOB

The Natural system variables `*ISN`, `*COUNTER` and `*NUMBER` are provided with the `READLOB` statement.

The format/length of these system variables is P10. This format/length cannot be changed.

The purpose of the Natural system variables, when used with the `READLOB` statement, is explained below:

System Variable | Explanation
--- | ---
`*ISN` | Contains the Adabas ISN of the record currently being processed. Since a `READLOB` statement always makes access to the same record, the `*ISN` value returned is the same over all loop iterations.
`*COUNTER` | Contains the number of times the processing loop has been passed through.
`*NUMBER` | Before the call: | It specifies the byte offset in the LOB field from which the segment is to be read. Value zero (`0`) represents the leftmost byte in the LOB field. This does not apply for the first loop iteration. In this case the read offset is determined by the `STARTING AT OFFSET` clause.
After the call: | If data was found (that is, the offset was less than the LOB field length), it receives the offset plus the segment length. This may lead to a `*NUMBER` value which is higher than the length of the entire LOB field. If no data was found (that is, the offset was higher or equal to the LOB field length), the value of `*NUMBER` remains unchanged.
If a consecutive read over a LOB field is requested, the `*NUMBER` value must not be modified within the `READLOB`, as it contains the offset to exactly continue with the next segment in the subsequent loop iteration. However, if a continuation at another place within the LOB field is desired (re-position), you may change the `*NUMBER` value to this offset. If `*NUMBER` is reset, this leads to the next segment coming from the LOB start. If `*NUMBER` is incremented by `(n)`, this number of bytes will be skipped in the LOB field processing.

## READLOB Functional Considerations

- The `READLOB` statement always reads the record without hold. In order to guarantee stability on the LOB data (that is, to prevent an update by other users) while the `READLOB` browses over the LOB field, the record can be set into hold with the database statement providing the ISN; either

  - into an exclusive hold, due to an `UPDATE` or `DELETE` referring to an outer `READ` or `FIND` statement or

  - into a shared hold with an explicit `IN SHARED HOLD` option applied in a `READ` or `FIND` statement. If the additional subparameter `MODE=Q` is used, the record is automatically released from hold if the next record is fetched in the read sequence.

- Since the `READLOB` statement always reads the record without hold, an `UPDATE`, `DELETE` or `GET SAME` statement must not refer to a `READLOB` statement.

## READLOB Examples

- Example 1 - Get Record Number from READ Loop

- Example 2 - Get Record Number by User-defined Value

- Example 3 - Get Record Number from READ Loop (with Exclusive Hold)

### Example 1 - Get Record Number from READ Loop

    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

### Example 2 - Get Record Number by User-defined Value

    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

### Example 3 - Get Record Number from READ Loop (with 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 from active record of READ.
                                /* LOB is read in segments with length 1000.
          STARTING AT OFFSET = 2000 /* Start to read 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

- READLOB Usage
- READLOB Restrictions
- READLOB Syntax Description
- System Variables Available with READLOB
- READLOB Functional Considerations
- READLOB Examples