READ WORK FILE

#### Search Results

Search

# READ WORK FILE

This document covers the following topics:

- Function

- Syntax 1 - READ WORK FILE with Processing Loop

- Syntax 2 - READ WORK FILE without Processing Loop

- Syntax Description

- Field Lengths

- Variable Index Range

- Handling of Dynamic Variables

- Handling of X-Arrays

- Examples

Related Statements: `CLOSE WORK FILE` | `DEFINE WORK FILE` | `WRITE WORK FILE`

Belongs to Function Group: Control of Work Files / PC Files

## Function

The `READ WORK FILE` statement is used to read data from a non-Adabas physical sequential work file. The data is read sequentially from the work file. How it is read is independent of how it was written to the work file.

This statement can only be used within a program to be executed under Com-plete, CICS, or TSO, or in batch mode. Appropriate JCL or system commands must be executed to allocate the work file. For further information, see the Operations documentation. For information on work file assignments, see profile parameter `WORK` in the Parameter Reference.

`READ WORK FILE` initiates and executes a processing loop for reading of all records on the work file. Automatic break processing may be performed within a `READ WORK FILE` loop.

Notes:

1. When an end-of-file condition occurs during the execution of a `READ WORK FILE` statement, Natural automatically closes the work file.
2. For Entire Connection: If an Entire Connection work file is read, no I/O statement may be placed within the `READ WORK FILE` processing loop.
3. For Unicode and code page support, see Work Files and Print Files on Mainframe Platforms in the Unicode and Code Page Support documentation.

## Syntax 1 - READ WORK FILE with Processing Loop

`READ` `WORK` [`FILE`] work-file-number
| `RECORD` operand1 |  |  |
[`AND`] [`SELECT`] |  |  |  | `OFFSET` n `FILLER` n `X` |  |  | operand2 |  |  |  |  |
|  | `OFFSET` n `FILLER` n `X` |  |  | operand2 |  |  |  |  | `OFFSET` n `FILLER` n `X` |  |  | operand4 [`AND`] `ADJUST` [`OCCURRENCES`]
[`GIVING LENGTH` operand3]
statement
`END-WORK` | (structured mode only)
`LOOP` | (reporting mode only)

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

## Syntax 2 - READ WORK FILE without Processing Loop

`READ` `WORK` [`FILE`] work-file-number `ONCE`
| `RECORD` operand1 |  |  |
[`AND`] [`SELECT`] |  |  |  | `OFFSET` n `FILLER` n `X` |  |  | operand2 |  |  |  |
|  | `OFFSET` n `FILLER` n `X` |  |  | operand2 |  |  |  | `OFFSET` n `FILLER` n `X` |  |  | operand4 [`AND`] `ADJUST` [`OCCURRENCES`]
[`GIVING LENGTH` operand3]
`[AT` [`END`] [`OF`] [`FILE`] statement `END-ENDFILE]` (structured mode only)
| `AT` [`END`] [`OF`] [`FILE`] |  | statement `DO` statement `DOEND` |  |  | (reporting mode only)

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

## Syntax Description

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` |  | S | A | G |  | A | U | N | P | I | F | B | D | T | L | C |  |  | yes | yes
`operand2` |  | S | A | G |  | A | U | N | P | I | F | B | D | T | L | C |  |  | yes | yes
`operand3` |  | S |  |  |  |  |  |  |  | I |  |  |  |  |  |  |  |  | yes | yes
`operand4` |  |  | A |  |  | A | U | N | P | I | F | B | D | T | L | C |  |  | no | no

Format C is not valid for Natural Connection.

See also Field Lengths.

Syntax Element Description:

Syntax Element | Description
--- | ---
`work-file-number` | Work File Number: The work file number (as defined to Natural) to be used. The work file number is either a numeric constant in the value range 1:32 or a numeric variable of type B/N/P/I defined with a CONST clause which assigns a value in range 1:32. Precision digits for type (N/P) are not allowed.
`ONCE` | ONCE Option: `ONCE` is used to indicate that only one record is to be read. No processing loop is initiated (and therefore the loop-closing keyword `END-WORK` or `LOOP` must not be specified). If `ONCE` is specified, the `AT END OF FILE` clause should also be used. If a `READ WORK FILE` statement specified with the `ONCE` option is controlled by a user-initiated processing loop, an end-of-file condition may be detected on the work file before the loop ends. All fields read from the work file still contain the values from the last record read. The work file is then repositioned to the first record which will be read upon the next execution of `READ WORK FILE ONCE`.
`RECORD` `operand1` `FILLER nX` | RECORD Option: In reporting mode, an operand list (`operand1`) corresponding to the layout of the record must be provided. Specify `FILLER nX` if the total length of the operands is less that the work file record length. In structured mode, or if the record to be used is defined using a `DEFINE DATA` statement, only one field (or group) may be specified, and `FILLER` is not permitted. The field (or group) must be long enough to receive the entire work file record. No checking and no conversion is performed by Natural on the data contained in the record. It is the user's responsibility to describe the record layout correctly in order to avoid program abends caused by non-numeric data in numeric fields. Because no checking is performed by Natural, this option is the fastest way to process records from a sequential file. The record area defined by `operand1` is filled with blanks before the record is read. Thus, an end-of-file condition will return a cleared area. Short records will have blanks appended. The `RECORD` option cannot be used: If an Entire Connection work file is read. If any dynamic variables are used.
`SELECT` |
SELECT Option (Default): If `SELECT` is specified, only the fields specified in the operand list (`operand2`) will be made available. The position of the field in the input record may be indicated with an `OFFSET` and/or `FILLER` specification.
`OFFSET n` | `OFFSET 0` indicates the first byte of the record. `OFFSET` cannot be specified for work files defined as `TYPE UNFORMATTED`.
`FILLER nX` | Indicates that n bytes are to be skipped in the input record.
Natural will assign the selected values to the individual fields and check that numeric fields as selected from the record actually contain valid numeric data according to their definition. Because checking of selected fields is performed by Natural, this option results in more overhead for the processing of a sequential file. If a record does not fill all fields specified in the `SELECT` option, the following applies: For a field which is only partially filled, the section which has not been filled is reset to blanks or zeros. Fields which are not filled at all still have the contents they had before.
`operand4 AND ADJUST OCCURRENCES` | ADJUST Clause: Specify a one-dimensional X-array with complete range (*). The X-array is expanded or reduced to the number of occurrences needed to receive all data read. See Handling of X-Arrays below. Note This feature is not supported by Entire Connection.
`GIVING LENGTH operand3` | GIVING LENGTH Clause This clause can be used to retrieve the actual length of the record being read. The length (number of bytes) is returned in `operand3`. `operand3` must be defined with format/length I4. If the work file is defined as `TYPE UNFORMATTED`, the length returned indicates the number of bytes read from the byte-stream, including bytes skipped using the `FILLER` operand.
`AT END OF FILE` | AT END OF FILE Clause This clause can only be used in conjunction with the `ONCE` option. If the `ONCE` option is used, this clause is specified to indicate the action to be taken when an end-of-file condition is detected. If the `ONCE` option is not used, an end-of-file condition is handled like a normal processing loop termination.
`END-WORK` | End of READ WORK FILE Statement: In structured mode with processing loop, the Natural reserved word `END-WORK` must be used to end the `READ WORK FILE` statement.
`LOOP` | End of READ WORK FILE Statement: In reporting mode with processing loop, the Natural statement `LOOP` must be used to end the `READ WORK FILE` statement.

## Field Lengths

The field lengths in the Operand Definition Table are determined as follows:

Format | Length
--- | ---
A, B, I, F | The number of bytes in the input record is the same as the internal length definition.
N | The number of bytes in the input record is the sum of internal positions before and after the decimal point. The decimal point and sign do not occupy a byte position in the input record.
P, D, T | The number of bytes in the input record is the sum of positions before and after the decimal point plus 1 for the sign, divided by 2 rounded upwards.
L | 1 byte is used. For C format fields, 2 bytes are used.

#### Examples of Field Lengths:

Field Definition | Input Record
--- | ---
`#FIELD1 (A10)` | 10 bytes
`#FIELD2 (B15)` | 15 bytes
`#FIELD3 (N1.3)` | 4 bytes
`#FIELD4 (N0.7)` | 7 bytes
`#FIELD5 (P1.2)` | 2 bytes
`#FIELD6 (P6.0)` | 4 bytes

See also Format and Length of User-Defined Variables in the Programming Guide.

## Variable Index Range

When reading an array from a work file, you can specify a variable index range for the array. For example:

    READ WORK FILE work-file-number #ARRAY (I:J)

## Handling of Dynamic Variables

Work File Type | Handling
--- | ---
`UNFORMATTED` | Reading a dynamic variable from an `UNFORMATTED` work file puts the complete rest of the file into the variable (from the current position). If the file exceeds 1073741824 bytes, then a maximum of 1073741824 bytes is placed into the variable.
`FORMATTED` | Reading a dynamic variable from a `FORMATTED` work file puts the rest of the work file record into the variable. Thus, for work files with variable record length, the dynamic variable is resized in each execution of the `READ WORK FILE` statement to match the exact length of the record being read.

## Handling of X-Arrays

When the `ADJUST` clause is not used, X-arrays are treated the same as regular arrays; that is, their existing occurrences are filled.

When the `ADJUST` clause is used, a one-dimensional X-array specified with complete range (*) is expanded to receive all data from the rest of the record for a work file of type `FORMATTED`, or to receive all data from the rest of the file for a work file of type `UNFORMATTED.`

## Examples

- Example 1 - READ WORK FILE

- Example 2 - READ WORK FILE Formatted with Dynamic Variable

- Example 3 - READ WORK FILE Unformatted with Dynamic Variable

- Example 4 - READ WORK FILE Formatted with X-array and ADJUST its Occurrences

- Example 5 - READ WORK FILE Unformatted with X-array and ADJUST its Occurrences

- Example 6 - READ WORK FILE with Numeric CONST Variable as Work File Number

### Example 1 - READ WORK FILE

    ** Example 'RWFEX1': READ WORK FILE
    ************************************************************************
    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 PERSONNEL-ID
      2 NAME
    *
    1 #RECORD
      2 #PERS-ID (A8)
      2 #NAME    (A20)
    END-DEFINE
    *
    FIND EMPLOY-VIEW WITH CITY = 'STUTTGART'
      WRITE WORK FILE 1
            PERSONNEL-ID NAME
    END-FIND
    *
    * ...
    *
    READ WORK FILE 1 RECORD #RECORD
      DISPLAY NOTITLE #PERS-ID #NAME
    END-WORK
    *
    END

#### Output of Program RWFEX1:

    #PERS-ID        #NAME
    -------- --------------------

    11100328 BERGHAUS
    11100329 BARTHEL
    11300313 AECKERLE
    11300316 KANTE
    11500304 KLUGE
    11500308 DIETRICH
    11500318 GASSNER
    11500343 ROEHM
    11600303 BERGER
    11600320 BLAETTEL
    11500336 JASPER
    11100330 BUSH
    11500328 EGGERT

### Example 2 - READ WORK FILE Formatted with Dynamic Variable

    ** Example 'RWFEX2': READ WORK FILE - Formatted with dynamic variable
    ************************************************************************
    DEFINE DATA LOCAL
      1 #DYNA (A) DYNAMIC
    END-DEFINE
    *
    DEFINE WORK FILE 1 TYPE 'FORMATTED'
    *
    WRITE WORK FILE 1 VARIABLE 'text1 text2 text3 '
    WRITE WORK FILE 1 VARIABLE 'text4 text5'
    *
    READ WORK FILE 1 AND SELECT #DYNA
      DISPLAY *LENGTH(#DYNA) #DYNA (AL=40)
      /*
      /* Length: 18  Dyn.Var: 'text1 text2 text3'
      /* Length: 11  Dyn.Var: 'text4 text5'
    END-WORK
    *
    END

#### Output of Program RWFEX2:

    Page      1                                                  11-07-15  09:21:09

      LENGTH                     #DYNA
    ----------- ----------------------------------------

             18 text1 text2 text3
             11 text4 text5

### Example 3 - READ WORK FILE Unformatted with Dynamic Variable

    ** Example 'RWFEX3': READ WORK FILE - Unformatted with dynamic variable
    ************************************************************************
    DEFINE DATA LOCAL
      1 #DYNA (A) DYNAMIC
    END-DEFINE
    *
    DEFINE WORK FILE 1 TYPE 'FORMATTED'
    *
    WRITE WORK FILE 1 VARIABLE 'text1 text2 text3 '
    WRITE WORK FILE 1 VARIABLE 'text4 text5'
    *
    DEFINE WORK FILE 1 TYPE 'UNFORMATTED'
    *
    READ WORK FILE 1 AND SELECT #DYNA
      DISPLAY *LENGTH(#DYNA) #DYNA (AL=40)
      /*
      /* Length: 29  Dyn.Var: 'text1 text2 text3 text4 text5'
    END-WORK
    *
    END

#### Output of Program RWFEX3:

    Page      1                                                  11-07-15  09:31:04

      LENGTH                     #DYNA
    ----------- ----------------------------------------

             29 text1 text2 text3 text4 text5

### Example 4 - READ WORK FILE Formatted with X-array and ADJUST its Occurrences

    ** Example 'RWFEX4': READ WORK FILE - Formatted with X-array
    **                                    and ADJUST its occurrences
    ************************************************************************
    DEFINE DATA LOCAL
      1 #ARR (A6/1:*)
      1 #OCC (I4)
    END-DEFINE
    *
    DEFINE WORK FILE 1 TYPE 'FORMATTED'
    *
    WRITE WORK FILE 1 VARIABLE 'text1 text2 text3 '
    WRITE WORK FILE 1 VARIABLE 'text4 text5'
    *
    READ WORK FILE 1 AND SELECT #ARR(*) AND ADJUST OCCURRENCES
      #OCC := *OCCURRENCE(#ARR)
      DISPLAY #OCC #ARR(1:#OCC)
      /*
      /* Occurrences: 3 Array(*): 'text1', 'text2', 'text3'
      /* Occurrences: 2 Array(*): 'text4', 'text5'
    END-WORK
    *
    END

#### Output of Program RWFEX4:

    Page      1                                                  11-07-15  09:36:13

       #OCC      #ARR
    ----------- ------

              3 text1
                text2
                text3
              2 text4
                text5

### Example 5 - READ WORK FILE Unformatted with X-array and ADJUST its Occurrences

    ** Example 'RWFEX5': READ WORK FILE - Unformatted with X-array
    **                                    and ADJUST its occurrences
    ************************************************************************
    DEFINE DATA LOCAL
      1 #ARR (A6/1:*)
      1 #OCC (I4)
    END-DEFINE
    *
    DEFINE WORK FILE 1 TYPE 'FORMATTED'
    *
    WRITE WORK FILE 1 VARIABLE 'text1 text2 text3 '
    WRITE WORK FILE 1 VARIABLE 'text4 text5'
    *
    DEFINE WORK FILE 1 TYPE 'UNFORMATTED'
    *
    READ WORK FILE 1 AND SELECT #ARR(*) AND ADJUST OCCURRENCES
      #OCC := *OCCURRENCE(#ARR)
      DISPLAY #OCC #ARR(1:#OCC)
      /*
      /*Occurrences: 5 Array(*): 'text1', 'text2', 'text3', 'text4', 'text5'
    END-WORK
    *
    END

#### Output of Program RWFEX5:

    Page      1                                                  11-07-15  09:41:25

       #OCC      #ARR
    ----------- ------

              5 text1
                text2
                text3
                text4
                text5

### Example 6 - READ WORK FILE with Numeric CONST Variable as Work File Number

    ** Example 'RWFEX6': READ WORK FILE - with numeric CONST variable as
    **                                    work file number
    ** see similar example RWFEX5 with numeric constant
    ************************************************************************
    DEFINE DATA LOCAL
      1 #ARR    (A6/1:*)
      1 #OCC    (I4)
      1 #WF-1   (N4) CONST<1>
    END-DEFINE
    *
    DEFINE WORK FILE #WF-1 TYPE 'FORMATTED'
    *
    WRITE WORK FILE  #WF-1 VARIABLE 'text1 text2 text3 '
    WRITE WORK FILE  #WF-1 VARIABLE 'text4 text5'
    *
    DEFINE WORK FILE #WF-1 TYPE 'UNFORMATTED'
    *
    READ WORK FILE #WF-1 AND SELECT #ARR(*) AND ADJUST OCCURRENCES
      #OCC := *OCCURRENCE(#ARR)
      DISPLAY #OCC #ARR(1:#OCC)
      /*
      /*Occurrences: 5 Array(*): 'text1', 'text2', 'text3', 'text4', 'text5'
    END-WORK
    *
    END

#### Output of Program RWFEX6:

    Page      1                                                  21-12-20  17:42:43

       #OCC      #ARR
    ----------- ------

              5 text1
                text2
                text3
                text4
                text5

### On this page

- Function
- Syntax 1 - READ WORK FILE with Processing Loop
- Syntax 2 - READ WORK FILE without Processing Loop
- Syntax Description
- Field Lengths
- Variable Index Range
- Handling of Dynamic Variables
- Handling of X-Arrays
- Examples