OPEN DATASET

Basic form 1

OPEN DATASET dsn.

Extras:

1a. ... FOR INPUT

1b. ... FOR OUTPUT

1c. ... FOR APPENDING

1d. ... FOR UPDATE


2a. ... IN BINARY MODE

2b. ... IN TEXT MODE [ENCODING (DEFAULT|UTF-8|NON-UNICODE)]

2c. ... IN LEGACY BINARY MODE [(BIG|LITTLE) ENDIAN] [CODE PAGE cp]

2d. ... IN LEGACY TEXT MODE [(BIG|LITTLE) ENDIAN] [CODE PAGE cp]


3. ... REPLACEMENT CHARACTER rc

4. ... IGNORING CONVERSION ERRORS


5. ... AT POSITION p


6. ... TYPE c

7. ... MESSAGE m

8. ... FILTER f

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

Effect

Opens the specified file. If you do not specify a directory, the system uses the directory defined in the profile parameter DIR_HOME.

In programs without active Unicode check, the file is opened for reading in binary mode if you do not use any additions for OPENDATASET. To ensure downward compatibility with Releases <= 4.6, file names containing blanks are truncated at the position of the first blank.

In programs with active Unicode check, you must specify the access type (such as ... FOR INPUT, ... FOR OUTPUT, and so on) and the mode (such as ... IN TEXT MODE, ... IN BINARY MODE, and so on). If the file is opened using ... IN TEXT MODE, you must still use the addition ... ENCODING. If the Unicode check is enabled, it is possible to use file names containing blanks. Applying OPEN DATASET to a file already opened - in the same internal mode - triggers an exception of the type CX_SY_FILE_OPEN.

The Return Code is set as follows:

SY-SUBRC = 0:

The file was opened.

SY-SUBRC = 8:

The file could not be opened.

Example

DATA:
  dsn(20) TYPE C VALUE '/usr/test.dat',
  rec(80) TYPE C.

OPEN DATASET dsn FOR INPUT IN TEXT MODE ENCODING DEFAULT.
IF sy-subrc <> 0.
  EXIT.
ENDIF.

READ DATASET dsn INTO rec.
WHILE sy-subrc <> 0.
  WRITE / rec.   READ DATASET dsn INTO rec.
ENDWHILE.

CLOSE DATASET dsn.

The system opens the file test.dat in the directory usr of the application server and reads it line by line.

Notes

• The system must be able to reach the file from the current application server. You cannot edit files from the current presentation server. If you need to do this, use the function modules GUI_DOWNLOAD and GUI_UPLOAD.
  
• The form of the file name depends on the underlying operating system. To make your programs portable to different operating systems, use the function module FILE_GET_NAME, which returns the system-dependent name for an abstract file name. You can define file names using the transaction FILE.
  
• The system automatically performs an authorization check. If this check fails, a runtime error occurs. You can prevent this by checking the authorization in advance using the function module AUTHORITY_CHECK_DATASET.
  
  
  

Note

Access rights to files:
When you create a file, it is created under the user name used to start the SAP System. This is not usually the name of the current user. To allow the system to create files, you must assign write authorization to the user name of the SAP System in the relevant directory.

Addition 1a

... FOR INPUT

Effect

OPEN ... FOR INPUT opens the file in read mode.

If the file does not exist, OPEN ... FOR INPUT fails with Return Code SY-SUBRC = 8.

Note

If OPEN DATASET is not executed in a Unicode program and if the user has write authorization for the file, the file is opened in read and write mode. Otherwise, it is only opened in read mode.

Addition 1b

... FOR OUTPUT

Effect

OPEN ... FOR OUTPUT opens the file in write mode.

If the file already exists, its existing content is deleted. If the file does not exist, the system creates it.

Addition 1c

... FOR APPENDING

Effect

OPEN ... FOR APPENDING opens the file in append mode.

If the file already exists, its contents are retained, and the system moves to the end of the file. If the file does not exist, the system creates it. If the file was already open, the system moves to the end of the file.

Note

When you open a file using FOR APPENDING, READDATASET always returns Return Code SY-SUBRC = 4 which is used to display the end of the file.

Addition 1d

... FOR UPDATE

Effect

OPEN ... FOR UPDATE opens the file in read and write mode.

If the file does not exist, OPEN ... FOR UPDATE fails with Return Code SY-SUBRC = 8.

Addition 2a

... IN BINARY MODE

Effect

Data is read or written unchanged (as stored in the memory). (For details, see READ DATASET and TRANSFER.)
This file format is used if you do not specify a MODE addition.

Addition 2b

... IN TEXT MODE [ENCODING (DEFAULT|UTF-8|NON-UNICODE)]

Effect

Data is read or written line by line. (For details, see READ DATASET and TRANSFER.)

Note

on ENCODING (DEFAULT|UTF-8|NON-UNICODE)

This addition specifies the character representation in the file:

DEFAULT

Corresponds to UTF-8 in Unicode systems and to NON-UNICODE in non-Unicode systems.

UTF-8

Characters are represented in the file in the format UTF-8.

NON-UNICODE

Characters are represented in the file in the code page defined by the text environment current at the time a READ or TRANSFER command is executed (see SET LOCALE LANGUAGE).

Addition 2c

... IN LEGACY BINARY MODE [(BIG|LITTLE) ENDIAN] [CODE PAGE cp]

Effect

Data is read or written in a form which is compatible to BINARY MODE in Releases <= 4.6. This addition is primarily used to convert a file into the code page format specified already when it is opened. At runtime, the system uses the format of the system code page of the application server. The system saves the file then again in the code page specified. This procedure is important if data is exchanged between systems using different code pages. For more information, see READ DATASET and TRANSFER.

Addition 2d

... IN LEGACY TEXT MODE [(BIG|LITTLE) ENDIAN] [CODE PAGE cp]

Effect

Data is read or written in a form which is compatible to BINARY MODE in Releases <= 4.6. This addition is primarily used to convert a file into the code page format specified already when it is opened. At runtime, the system uses the format of the system code page of the application server. The system saves the file then again in the code page specified. This procedure is important if data is exchanged between systems using different code pages. For more information, see READ DATASET and TRANSFER.

Notes

on BIG ENDIAN, LITTLE ENDIAN

• These additions specify the byte sequence in which to store numbers (ABAP types I, F, and INT2) in the file.
  
• These additions may only be used in combination with the additions IN LEGACY BINARY MODE and IN LEGACY TEXT MODE. If these are not specified, the system assumes that the byte sequence determined by the hardware of the application server is used in the file.
  
• If the byte sequence specified differs from that determined by the hardware of the application server, READDATASET and TRANSFER make the corresponding conversions.
  
• These additions replace the language element TRANSLATE ... NUMBER FORMAT ... which must not be used in Unicode programs.
  

on CODE PAGE cp

• This addition specifies the code page which is used to represent texts in the file.
  
• This addition may only be used in combination with the additions IN LEGACY BINARY MODE and IN LEGACY TEXT MODE. If this addition is not specified, the system uses the code page defined by the text environment current at the time a READ or TRANSFER command is executed (see SET LOCALE LANGUAGE).
  
• This addition replaces the language element TRANSLATE ... CODE PAGE ... which must not be used in Unicode programs.
  
  
  
  
  

Addition 3

... REPLACEMENT CHARACTER rc

Effect

Specifies the replacement character which is used when a character cannot be converted during a character set conversion.

Note

This addition may only be used in combination with the additions IN TEXT MODE and IN LEGACY ... MODE. If the addition is not specified, "#" is used as the replacement character.

Addition 4

... IGNORING CONVERSION ERRORS

Effect

This addition ensures that no exception is triggered when an error occurs during character set conversion and a file is accessed in read or write mode. If you do not use this addition, the exception CX_SY_CONVERSION_CODEPAGE is triggered when a conversion error occurs. (For details see READ DATASET and TRANSFER.)

Addition 5

... AT POSITION p

Effect

Sets the read/write position in the file to p. p is interpreted as the byte offset from the beginning of the file.

Notes

• You can use the command GETDATASET POSITION to access the current read/write position. This value can be used as the parameter p for the AT POSITION addition.
  
• When you use the OPEN ... FOR OUTPUT AT POSITION ... variant, the file contents are destroyed if the file already existed. To prevent this from happening, use OPEN ... FOR UPDATE AT POSITION ... if you want to change an existing file at the position specified.
  
  
  
  
  

Addition 6

... TYPE c

Effect

You can specify additional file attributes in the field c. The field contents are passed to the operating system without changes and without any checks for correctness. For more information on the correctness of the attributes specified, refer to the open system call documentation of the relevant operating system.

Note

If the application server runs under Windows NT and the file was opened using IN TEXT MODE or IN LEGACY TEXTMODE, the TYPE addition is interpreted as follows:

c = 'NT'

The end of the line is marked with "CRLF".

c = 'UNIX'

The end of the line is marked with "LF".

Other

The addition is ignored, and the end of the line is marked with the line end character possibly already used in the file (see the note at the end of this document).

Example

Generating the OS/400 file test.dat with the properties specified under TYPE. The following example specifies the record length, the block size, and the record format.

OPEN DATASET 'test.dat'
  TYPE 'lrecl=80, blksize=8000, recfm=FB'
  FOR OUTPUT IN TEXT MODE ENCODING DEFAULT.

Addition 7

... MESSAGE m

Effect

If an error occurs opening the file, the corresponding message of the operating system is stored in the field m.

Example

DATA: dsn(20) VALUE '/usr/test.dat',
      msg(100).

OPEN DATASET dsn FOR INPUT MESSAGE msg
                 IN TEXT MODE ENCODING DEFAULT.

IF sy-subrc <> 0.
  WRITE / msg.
  STOP.
ENDIF.

Addition 8

... FILTER f

Effect

If you are working under UNIX or Windows NT, you can specify an operating system command in the field f.

Example

Under UNIX, the following

DATA dsn(20) VALUE '/usr/test.dat'.

OPEN DATASET dsn FOR OUTPUT FILTER 'compress'

                 IN TEXT MODE ENCODING DEFAULT.

opens the file dsn and writes the data to the file in compressed form using the UNIX command compress.

OPEN DATASET dsn FOR INPUT FILTER 'uncompress'
                 IN TEXT MODE ENCODING DEFAULT.

reads the file again.

Exceptions

Catchable Exceptions

CX_SY_FILE_OPEN

• Cause: The file is already open (only in Unicode programs)
  Runtime Error: DATASET_REOPEN
  

CX_SY_CODEPAGE_CONVERTER_INIT

• Cause: The required conversion is not supported (because you specified an invalid code page or a language with SET LOCALE LANGUAGE not supported during conversion).
  Runtime Error: CONVT_CODEPAGE_INIT (catchable)
  

CX_SY_CONVERSION_CODEPAGE

• Cause: Internal conversion error
  Runtime Error: CONVT_CODEPAGE (catchable
  

CX_SY_FILE_AUTHORITY

• Cause: No authorization to access a file
  Runtime Error: OPEN_DATASET_NO_AUTHORITY (catchable)
  
• Cause: Authorization to access this file missing for OPEN DATASET with addition FILTER.
  Runtime Error: OPEN_PIPE_NO_AUTHORITY (catchable)
  

CX_SY_PIPES_NOT_SUPPORTED

• Cause: OPEN DATASET with addition FILTER is not supported on the current operating system.
  Runtime Error: DATASET_NO_PIPE (catchable)
  

CX_SY_TOO_MANY_FILES

• Cause: The maximum number of open files has been exceeded.
  Runtime Error: DATASET_TOO_MANY_FILES (catchable)
  
  
  

Non-Catchable Exceptions

• Cause: You attempted to open a pipe already open.
  Runtime Error: DATASET_PIPE_POSITION
  
  
  
  
  

Note

End of line marking under Windows NT
Since under Windows NT the line end in text files can be marked both with " CRLF" and with "LF", text files are handled in a special way on this operating system when opened using FOR OUTPUT or FOR APPENDING:

1. You can use the addition TYPE to specify the desired end of line marking.
   
2. If you do not specify an end of line marking using the addition TYPE, the system searches the file (if it exists already) for end of line markings. The first marking found is used for future search operations.
   
3. If the file does not already exist or if no marking is found, the format specified in the profile parameter "abap/NTfopen" is used.
   
4. If the profile parameter is not set, "CRLF" is used.
   
   
   
   
   

Related

READ DATASET, TRANSFER, CLOSE DATASET, GET DATASET POSITION, DELETE DATASET

Additional help

Opening Files