TRANSFER

Short Reference

Syntax

TRANSFER dobj TO dset [LENGTH len]
                      [NO END OF LINE].

Extras:

1. ... LENGTH len

2. ... NO END OF LINE

Effect

This statement passes the content of data object dobj to the file specified in dset. For dobj, you can specify data objects with elementary data types and flat structures. In Unicode programs, dobj must be character-type if the file was opened as a text file (this restriction does not apply to legacy text files).

dset is expected to be a character-type data object that contains the platform-specific name of the file. The content is written to the file from the current file pointer. After the transfer, the file pointer is positioned after the data that was added. You can use addition LENGTH to restrict the number of characters or bytes transferred

In a Unicode program, the file for writing, appending, or changing must be open. Otherwise, a treatable exception occurs.

If the file was not yet opened in a non-Unicode programm, it is implicitly opened using the statement

OPEN DATASET dset FOR OUTPUT IN BINARY MODE.

as a binary file for writing. If the system accesses an invalid file, a treatable exception is raised.

The Influence of Access Type

The access type defined in statement OPEN DATASET has the following effect on the transfer:

A file opened for reading using FOR INPUT cannot be written in Unicode programs. In non-Unicode programs, TRANSFER writes in a file opened for reading using FOR INPUT in exactly the same way as a file openedfor changing using FOR UPDATE.

In a file opened for writing using FOROUTPUT, the system writes to the file from the current file pointer. If the file pointer is positioned after the current start of the file, the file is pre-filled with hexadecimal 0 from the start of the file to the file pointer.

1. In a file opened for appending using FOR APPENDING, the system writes to the file from the current file pointer, which is always at the end of the file.
   
   
2. In a file opened for changing using FOR UPDATE, the system writes to the file from the current file pointer. If the file pointer is positioned after the end of the file, the file is pre-filled with hexadecimal 0 between the end of the file and the file pointer position.
   
   
   

Note

Prior to release 6.10: If parts of a file were to be overwritten, it was only possible to write to a file opened for reading. This is not allowed in Unicode programs. As of release 6.10 and later, you can open a file for changing which is the recommended procedure also for non-Unicode programs.

The Influence of Storage Type

The transfer depends on the storage type used when the file is opened using the statement OPEN DATASET. If the specified storage type requires conversion, it is carried out before the write process.

If the file was opened as a text file or a legacy text file, the trailing blank characters are deleted for all data objects, except for those of data type string. The line end marker defined when the file was opened is then added to the remaining content of the data object or to the result of the conversion, and the final result is written byte-by-byte to the file.

As of release 6.40, the appending of the end of line separator can be prevented using NO END OF LINE.

If the file was opened as a binary file or a legacy binary file, the content of the data object or the result of the conversion is written byte-by-byte to the file.

Note

Only character-type data objects should be written to text files. Only byte-type data objects should be written to binary files. To store numerical data objects or mixed structures, we recommend that you assign them to character-type or byte-type typed field symbols using the CASTING addition of the statement ASSIGN and save these field symbols.

Addition 1

... LENGTH len

Effect

This addition determines how many characters or how many bytes of data object dobj are written to the file. len is expected to be a data object of type i that contains the number of characters or bytes. In text files, the content of len specifies the number of characters that are written from the storage. For binary files, legacy text file, and legacy binary files, len specifies the number of bytes that are written to the file. The first len characters or bytes are transferred and alignment gaps are included in the structures. If the addition LENGTH is not specified, all characters or bytes are transferred.

If the value of len is less than or equal to 0, no characters or bytes are transferred. If the file is opened as a (legacy) text file, however, a line end marker is inserted into the file by default. If the value of len is greater than the number of characters or bytes in dobj, hexadecimal 0 or blank characters are transferred to the file instead of the missing bytes or characters, depending on whether the file was opened as a (legacy) text file or a (legacy) binary file.

Addition 2

... NO END OF LINE

Effect

This addition has the effect that no end of line separator is appended to the data transferred in text files or legacy text files.

Example

The binary data from database table SPFLI is transferred to a binary file flights.dat. The structure of the table rows transferred contains both character-type and numerical fields. Since the type-specific storage of mixed structures in files is not possible, the binary content of the structure is directly accessed using a typed field symbol . To attain the same result, you can directly transfer the structure wa, the recommended procedure is to use the field symbol, however, because it explicitly transfers a binary data type to a binary file. This type of storage is only recommended for short-term storage within the same system, because the byte-type content depends on the byte sequence and the current system code page. For long-term storage or for exchanging between systems, the data should be converted to character-type containers and stored as a text file.

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

FIELD-SYMBOLS TYPE x.

OPEN DATASET file FOR OUTPUT IN BINARY MODE.

SELECT *
       FROM spfli
       INTO wa.
  ASSIGN wa TO CASTING.
  TRANSFER TO file.
ENDSELECT.

CLOSE DATASET file.

Exceptions

Catchable Exceptions

CX_SY_CODEPAGE_CONVERTER_INIT

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

CX_SY_CONVERSION_CODEPAGE

• Cause: Conversion is not possible.
  Runtime Error: CONVT_CODEPAGE (catchable)
  

CX_SY_FILE_AUTHORITY

• Cause: No authorization to access the file.
  Runtime Error: OPEN_DATASET_NO_AUTHORITY (catchable)
  

CX_SY_FILE_IO

• Cause: Error during writing to file.
  Runtime Error: DATASET_WRITE_ERROR (catchable)
  

CX_SY_FILE_OPEN

• Cause: File cannot be opened.
  Runtime Error: DATASET_CANT_OPEN (catchable)
  

CX_SY_FILE_OPEN_MODE

• Cause: The file was opened in a Unicode program using OPEN DATASET ... FOR INPUT. Therefore, it cannot be written. You should use the addition FOR UPDATE or FOR OUTPUT to open the file.
  Runtime Error: DATASET_READ_ONLY (catchable)
  
• CX_SY_PIPE_REOPEN
  
• Cause: The file was opened using the addition FILTER and since then a switch of the work process took place
  Runtime Error: DATASET_PIPE_CLOSED
  

CX_SY_TOO_MANY_FILES

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