READ WORK FILE

This document covers the following topics:

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.

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 Windows and Linux Platforms in the Unicode and Code Page Support documentation.

If an ASCII work file is read, it is possible that an empty record is returned as the last record after the last physical record. This is due to the fact that Natural does not read individual records, but reads larger blocks of the work file in order to optimize file-access performance.

Syntax 1 - READ WORK FILE with Processing Loop

READ WORK [FILE] work-file-number

RECORD operand1    

[AND] [SELECT]

OFFSET n
FILLER nX

  operand2 ../graphics/cbc2.gif      

 
       

OFFSET n
FILLER nX

  operand2

   

OFFSET n
FILLER nX

operand4 [AND] ADJUST [OCCURRENCES]

../graphics/dot3.gif

  
[GIVING LENGTH operand3]
statement
END-WORK (structured mode only)
LOOP (reporting mode only)

For explanations 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 nX

  operand2 ../graphics/cbc2.gif      

../graphics/dot3.gif

../graphics/dot3.gif

  
     

OFFSET n
FILLER nX

  operand2

 

OFFSET n
FILLER nX

  operand4 [AND] ADJUST [OCCURRENCES]

../graphics/dot3.gif

../graphics/dot3.gif

../graphics/dot3.gif
[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 explanations 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

See also Field Lengths.

Syntax Element Description:

Syntax Element Description
work-file-number
Work File Number:

The number of the work file (as defined to Natural) to be read.

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.

See Overview of RECORD Option Usage.

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

If the file type CSV is read, the OFFSET option is ignored.

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.

Note:
This feature is not supported by Entire Connection and work file type PORTABLE.

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.

If the GIVING LENGTH clause is used with work file type CSV, the operand specified with GIVING LENGTH returns the number of fields in the record (not the length of the record).

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.

Overview of RECORD Option Usage

RECORD option is used with rejected at compile time rejected at runtime RECORD option is ignored, processing switches to SELECT mode
work file type ENTIRECONNECTION   x  
dynamic variables x    
work file type CSV     x
work file type PORTABLE     x
work file types ASCII, ASCII-COMPRESSED, CSV, UNFORMATTED, code page is specified in Configuration Utility (conversion is necessary) or at least one Unicode field is specified (operand of format U, conversion is necessary)     x

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 Large and Dynamic Variables

Work File Type Handling

ASCII
ASCII-COMPRESSED

The work file types ASCII, ASCII-COMPRESSED can handle dynamic and large variables with a maximum field/record length of 32766 bytes.

Reading a dynamic variable from an ASCII or ASCII-COMPRESSED work file puts the rest of the work file record into the variable. Thus, for work files with these types, the dynamic variable is resized in each execution of the READ WORK FILE statement to match the exact length of the remaining part of the record.

SAG (binary)

The work file type SAG (binary) cannot handle dynamic variables and will produce an error. It can, however, handle large variables with a maximum field/record length of 32766 bytes.

ENTIRECONNECTION

The work file type ENTIRECONNECTION cannot handle dynamic variables. It can, however, handle large variables with a maximum field/record length of 107341824 bytes.

The RECORD option is not allowed if any dynamic variables are used.

PORTABLE
UNFORMATTED

Large and dynamic variables can be written into work files or read from work files using the two work file types PORTABLE and UNFORMATTED. For these types, there is no size restriction for dynamic variables. However, large variables may not exceed a maximum field/record length of 32766 bytes.

Reading a dynamic variable from a PORTABLE work file leads to resizing to the stored length.

CSV

The maximum field/record length is 32766 bytes for dynamic and large variables. Dynamic variables are supported. X-arrays are not allowed and will result in an error message.

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 processed as shown in the table:

Work File Type Handling

ASCII
ASCII-COMPRESSED
SAG (binary)
CSV

A one-dimensional X-array specified with complete range (*) is expanded to receive all data from the rest of the record.

UNFORMATTED

A one-dimensional X-array specified with complete range (*) is expanded to receive all data from the rest of the file.

PORTABLE
ENTIRECONNECTION

X-arrays are not supported.

Examples

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 ASCII with Dynamic Variable 

** Example 'RWFEX2': READ WORK FILE - ASCII with dynamic variable   
********************************************************************
DEFINE DATA LOCAL                                                       
  1 #DYNA (A) DYNAMIC                                                   
END-DEFINE                                                              
*                                                                       
DEFINE WORK FILE 1 TYPE 'ASCII'                                     
*                                                                       
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 'UNFORMATTED'                                     
*                                                                       
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 ASCII with X-array and ADJUST its Occurrences 

** Example 'RWFEX4': READ WORK FILE - ASCII with X-array            
**                                    and ADJUST its occurrences        
********************************************************************
DEFINE DATA LOCAL                                                       
  1 #ARR (A6/1:*)                                                       
  1 #OCC (I4)                                                           
END-DEFINE                                                              
*                                                                       
DEFINE WORK FILE 1 TYPE 'ASCII'                                     
*                                                                       
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 'UNFORMATTED'                                     
*                                                                       
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