READ DATASET

Short Reference

Syntax

READ DATASET dset INTO dobj [MAXIMUM LENGTH mlen]
                             [[ACTUAL] LENGTH alen].

Extras:

1. ... MAXIMUM LENGTH mlen

2. ... [ACTUAL] LENGTH alen

Effect

This statement exports data from the file specified in dset into the data object dobj. For dobj, variables with elementary data types and flat structures can be specified. In Unicode programs, dobj must be character-type if the file was opened as a text file.

For dset, a character-type data object is expected - that is, an object that contains the platform-specific name of the file. The content is read from the file starting from the current file pointer. After the data transfer, the file pointer is positioned after the section that was read. Using the MAXIMUM LENGTH addition, the number of characters or bytes to be read from the file can be limited. Using ACTUAL LENGTH, the number of characters or bytes actually used can be determined.

In a Unicode program, the file must be opened with an arbitrary access type; otherwise, an exception that cannot be handled will be triggered.

If the file has not yet been opened in anon-Unicode program, it will be implicitly opened as a binary file for read access using the statement
OPEN DATASET dset FOR INPUT IN BINARY MODE.
. If a non-existing file is accessed, an exception that can be handled can be triggered.

Influence of Access Type

Files can be read independently of the access type. Whether data can be read or not depends solely on the position of the file pointer. If the latter is at the end of the file or after the file, no data can be read and sy-subrc will be set to 4.

Influence of the Storage Type

The import function will take place irrespective of the storage type in which the file was opened with the statement OPEN DATASET.

If the file was opened as a text file or as a legacy text file, the data is normally read from the current position of the file pointer to the next end-of-line marking, and the file pointer is positioned after the end-of-line marking. If the data object dobj is too short for the number of read characters, the superfluous characters and bytes are cut off. If it is longer, it will be filled with blanks to the right.

If the specified storage type makes conversion necessary, this is executed before the assignment to the data object dobj. Afterwards, the read data is placed, byte by byte, into the data object.

System Fields

Note

The data from the text files should be imported solely into character-type data objects and data from binary files should be imported solely into byte-type data objects. To evaluate imported data as numeric data objects or mixed structures, it is recommended that you export these into binary containers and then assign these using the CASTING addition to the ASSIGN statement in accrodance with the typed field symbols. If the file is opened as a legacy-text file when such data is being imported, there is the danger that an end-of-line marking is contained in the binary representation of a number and that the numbe can therefore not be read.

Example

Importing the binary file flights.dat written from the example of the TRANSFER statement The data is written binary into a byte-type , typed field symbol <( <)>. Through the assignment of the structured data area wa to the field symbol, this adopts the length of the data area and a corresponding number of bytes for the loop process are imported. It would be possible to import directly into the structure wa with the same result, but the use of the field symbol is the recommended procedure. The reason is that in this way data is explicitly transferred from a binary file into a binary data type.

DATA: file TYPE string VALUE `flights.dat`,
      wa TYPE spfli.

FIELD-SYMBOLS <hex_container> TYPE x.

OPEN DATASET file FOR INPUT IN BINARY MODE.

ASSIGN wa TO <hex_container> CASTING.

DO.
  READ DATASET file INTO <hex_container>.
  IF sy-subrc = 0.
    WRITE: / wa-carrid,
             wa-connid,
             wa-countryfr,
             wa-cityfrom,
             wa-cityto,
             wa-fltime,
             wa-distance.
  ELSE.
    EXIT.
  ENDIF.
ENDDO.

CLOSE DATASET file.

Addition 1

... MAXIMUM LENGTH mlen

Effect

This addition determines how many characters or how many bytes maximum are read from the file. For mlen, a data object of the type i is expected. It contains the number of characters or bytes. In the case of text files, the content of mlen determines how many characters are read from the file. In the case of binary, legacy-text, and legacy-binary files, mlen determines how many bytes are read from the file.

The first mlen characters or bytes are read from the current position of the file pointer and the file pointer is positioned after the read file. If the file is opened as a (legacy) text file and there isan end-of-line marking within the specified length, data is read only upto this position and the file pointer is positioned after the end-of-line marking.

If the value of mlen is the same as 0, no data is read. If the value of mlen is negative, the addition will be ignored and importing takes place in the same way as described for Influence of Storage Type.

Note

In case of text files, the number of bytes read depends on the character presentation specified using ENCODING when opening the file.

Example

This program section has the same functions as the previous example. Here data is imported - not into a byte-type field symbol, but into a byte-type data object hex_container. The number of bytes to be imported is determined by the typed field symbol <spfli>. This symbol is used in each loop process to access the imported data component by component.

DATA: file          TYPE string VALUE `flights.dat`,
      hex_container TYPE x LENGTH 1000,
      len           TYPE i.

FIELD-SYMBOLS <spfli> TYPE spfli.

DESCRIBE FIELD <spfli> LENGTH len IN BYTE MODE.

OPEN DATASET file FOR INPUT IN BINARY MODE.

ASSIGN hex_container TO <spfli> CASTING.

DO.
  READ DATASET file INTO hex_container MAXIMUM LENGTH len.
  IF sy-subrc = 0.
    WRITE: / <spfli>-carrid,
             <spfli>-connid,
             <spfli>-countryfr,
             <spfli>-cityfrom,
             <spfli>-cityto,
             <spfli>-fltime,
             <spfli>-distance.
  ELSE.
    EXIT.
  ENDIF.
ENDDO.

CLOSE DATASET file.

Addition 2

... [ACTUAL] LENGTH alen

Effect

This addition assigns the number of characters or bytes to be read from the file to the data object alen.

For alen, a variable of the type i is expected. For textfiles, the system determines how many characters were written to the memory area. With binary, legacy-text, and legacy-binary files, the system determines how many bytes were read from the file.

Note

Regardless of the length of the target field, the number of characters or bytes actually read from the file is always returned.

• The optional addition ACTUAL was introduced for Release 6.10 in order to be better able to distinguish the addition LENGTH - which was also available in Releases prior to 6.10 - from the addition MAXIMUM LENGTH. As of Release 6.10, the addition ACTUAL should always be used.
  
  
  

Exceptions

Catchable Exceptions

• Cause: The required conversion is not supported (for example, due to specification of a language, using SET LOCALE LANGUAGE, that is not supported during conversion).
  Runtime Error: CONVT_CODEPAGE_INIT (catchable)
  
• 
  

• Cause: Conversion is not possible. The data is read as far as possible. Text data where the conversion has failed is undefined (see also note below).
  Runtime Error: CONVT_CODEPAGE (catchable)
  

CX_SY_FILE_AUTHORITY

• Cause: No authorization for access to a file
  Runtime Error: OPEN_DATASET_NO_AUTHORITY (catchable)
  

CX_SY_FILE_IO

• Cause: When reading the file, an error occurred.
  Runtime Error: DATASET_READ_ERROR (catchable)
  

CX_SY_FILE_OPEN

• Cause: The file could not be opened.
  Runtime Error: DATASET_CANT_OPEN (catchable)
  

CX_SY_PIPE_REOPEN

• Cause: The file was opened using the addition FILTER and, since opening, a change in the work process has taken place.
  Runtime Error: DATASET_PIPE_CLOSED