READ DATASET - Read From a File

Basic form

READ DATASET dsn INTO f.

Extras:

1. ... MAXIMUM LENGTH maxlen

2. ...[ACTUAL] LENGTH actlen

In some cases, the syntax rules that apply to Unicode programs are different than those for non-Unicode programs. For more details, see the chapter File Interface.

Effect

Imports a record from a sequential file whose index and name are specified in dsn into the data object f. dsn can be a field or a literal, f a field, a string, a structure, or a flat structure. A syntax error is triggered if f is defined as a deep structure, table, or reference. Internal tables must therefore always be transferred line by line, for example, in a DO loop that is exited using EXIT.

The way in which the file was opened during the statement OPEN DATASET determines how records are read from it afterwards.

• If the file was opened in text mode (addition IN TEXT MODE or IN LEGACY TEXT MODE beim OPEN DATASET), the system assumes that the file is structured line by line. Accordingly, read commands always refer to one line. Line separators are viewed as structuring units and therefore automatically filtered. Length specifications always refer to the number of characters (although in non-unicode systems, multi-byte characters are counted in the length of their memory representation).
  
  
  
• If the file was opened in binary mode (addition IN BINARY MODE or IN LEGACY BINARY MODE with OPEN DATASET), the system expects an unstructured sequence of bytes. Length specifications accordingly refer to the number of bytes.
  

The number of characters or bytes read by calling READ DATASET depends, on the one hand, on the opening mode of the file, and, on the other hand, on the type of target field f:

• With text files, an entire line is always imported, and this is then transferred to the target field f. If this target field is shorter than the number of read characters, the excess characters are lost. Since fields of the type STRING have unlimited length, a STRING always gives a full line as target field. If the file was opened in TEXT MODE and if the character representation in the file is UTF-8, then only character-like fields (C, N, D, T), strings, and purely character-like structures are allowed for f. This check takes place at runtime.
  
  
  
• If the file was opened in binary mode, the size of the target field f determines how many bytes are to be imported. Since fields of the type XSTRING have unlimited length, importing to a XSTRING means that the entire file is imported. To prevent this, you can use the addition ... MAXIMUM LENGTH.
  

If data of a length less than the target field f is imported, the target field is filled with blanks in the case of files in text mode and, in the case of files in binary mode, with hexadecimal zeros. Less data can occur, for example, if the file end has been reached or if you have text files, and the current line is shorter than the target field.

The Return Code is set as follows:

SY-SUBRC = 0:

A record from the file was read.

SY-SUBRC = 4:

The end of the file has been reached.

Example

DATA: line     TYPE string,
      file(20) TYPE C value '/usr/test.dat'.

OPEN DATASET file IN TEXT MODE ENCODING DEFAULT FOR INPUT.
DO.
  READ DATASET file INTO line.
  IF sy-subrc <> 0.
    EXIT.
  ENDIF.
  WRITE: / line.
ENDDO.

The file test.dat is imported line by line and then output. As soon as the end of the file test.dat is reached, the system exits the DO loop. If the index specification is missing, the system writes to the index that is defined in the profile parameter DIR_HOME.

Notes

• Reading a text file that is available in a code page different than the system code triggers automatic conversion of the data into the system code page. Here conversion errors can arise. Using the additions REPLACEMENTCHARACTER and IGNORING CONVERSION ERRORS for OPEN DATASET you can control what is to happen in such cases. If you have a character that is not in the system code page or a character that is cut off at the end of the target field (in the case of multi-byte characters), these are replaced by the replacement character that was specified using REPLACEMENT CHARACTER. This then triggers an exception of the type CX_SY_CONVERSION_COPEPAGE, unless IGNORING CONVERSION ERRORS was specified. Both specifications can be changed using the command SET DATASET, even in the case of a file that was already opened.
  
  
  
• If the file was opened by the READ statement, the system automatically executes an authorization check. If no authorization exists, there is a runtime error. You can check beforehand whether authorization exists using the function module AUTHORITY_CHECK_DATASET.
  
  
  
• Using TRANSFER you can output records to a sequential file.
  
  
  
• The file name form depends greatly on the operating system. Portable programs can be reached using the function module FILE_GET_NAME. This function supplies the respective physical name for a specified logical file name.
  
  
  

Addition 1

... MAXIMUM LENGTH maxlen

Effect

The data to be read can be specified using maxlen. Depending on whether the file was opened in text mode or binary mode, maxlen refers to the number in characters or bytes that are to be read.

In binary mode, maxlen bytes are read from the file (if the file end has not already been reached), and these are transferred afterwards to the target field f. If the target field is shorter, excess data is lost; if it is longer, it is filled with hexadecimal zeros.

In text mode, maxlen characters are read from the file if the current line contains that many characters at all. Under no circumstances does the system read beyond the end of the line. The characters are then transferred to the target field. If this is shorter that the characters that were read, excessive characters are lost; if it is longer, it is filled with blanks. As long as maxlen is not longer than the length of the line, a subsequent READ DATASET reads from the same line.

Example

DATA:
   text1(30) TYPE c VALUE 'Beethoven',
   text2(3) TYPE c,
   file(30)  TYPE c VALUE '/usr/test.dat'.

OPEN DATASET file IN TEXT MODE FOR OUTPUT ENCODING DEFAULT.
TRANSFER text1 TO file.
CLOSE DATASET file.
OPEN DATASET file IN TEXT MODE FOR INPUT ENCODING DEFAULT.
READ DATASET file INTO text1 MAXIMUM LENGTH 4.
READ DATASET file INTO text2.
CLOSE DATASET file.
WRITE: / text1, / text2.

In the field text1 you have 'Beet', in the fieldtext2 you have 'hov'. The second READ commands reads the entire remainder of the line since it does not use any MAXIMUM LENGTH addition. Since the target field text2 is too long, the 'en' part is lost.

Addition 2

... [ACTUAL] LENGTH actlen

Effect

The length of the data that was actually read from the file is returned in the variable actlen. The length specification in this case is in characters for a text file and in bytes for a binary file. Decisive, however, is the number of units distance from the data stream, not the number transferred into the target field. In non-unicode systems, make sure that the length of multi-byte characters is counted in the length of their memory representation.

To be able to distinguish this better from the addition MAXIMUM LENGTH, you should use the addition in its full ACTUAL LENGTH. For reasons of backward compatibility, however, the shortened LENGTH is also allowed.

Example

DATA:
  len       TYPE i,
  text1(30) TYPE c VALUE 'Beethoven',
  text2(4)  TYPE c,
  file(30)  TYPE c VALUE '/usr/test.dat'.

OPEN DATASET file IN TEXT MODE FOR OUTPUT ENCODING DEFAULT.
TRANSFER text1 TO file.
CLOSE DATASET file.
OPEN DATASET  file IN TEXT MODE FOR INPUT ENCODING DEFAULT.
READ DATASET file INTO text2 ACTUAL LENGTH len.
CLOSE DATASET file.
WRITE: / text2, len.

Now the field len contains the value 9 (although text2 only contains the characters 'Beet'), since with specification of the addition MAXIMUM LENGTH the system will read a complete line.

Exceptions

Catchable Exceptions

CX_SY_CODEPAGE_CONVERTER_INIT

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

CX_SY_CONVERSION_CODEPAGE

• Cause: Conversion is not possible. The data is read as far as possible; text data for which the conversion did not take place 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: Error occurred during file read.
  Runtime Error: DATASET_READ_ERROR (catchable)
  

CX_SY_FILE_OPEN

• Cause: It was not possible to open the file.
  Runtime Error: DATASET_CANT_OPEN (catchable)
  
  
  

Note

There are two situations in which the error CONVT_CODEPAGE can occur.

• If an internal error occurs during conversion. In this case, all the text data is invalid. Data of the type I, F, or P is valid. (This is relevant, for example, if a structure with text fields and number fields is read in LEGACY ... MODE.)
  
• If characters cannot be represented in the desired code page. In this case, the faulty characters are replaced by the replacement character that can be specified using the addition REPLACEMENT CHARACTER from OPEN DATASET. The runtime error CONVT_CODEPAGE does not occur in this case if the addition IGNORING CONVERSION ERRORS from OPEN DATASET was specified.
  
  
  

Related

OPEN DATASET, TRANSFER, CLOSE DATASET, SET DATASET, GET DATASET

Additional help

Read Data From Files