TRANSFER - Writing to a File

Basic form

TRANSFER f TO dsn.

Addition:

... LENGTH len

In some cases, the syntax rules that apply to Unicode programs are different than those for non-Unicode programs.

For more details, refer to The File Interface.

Effect

Transfers the data object f to a sequential file whose path and name are specified in dsn. dsn can be a field or a literal. You must already have opened the file using OPEN DATASET. f can be a field, a string, or a structure. If f is a deep structure or a reference, a syntax error occurs. Because of this, you must always transfer internal tables line by line, for example, using a LOOP construction.

In the OPEN DATASET statement, the data object f is interpreted in lines if you use IN TEXT MODE. If you use the IN BINARY MODE addition, the line breaks are ignored. If the specified file is not already open, TRANSFER attempts to open the file FOR OUTPUT IN BINARY MODE. If this is not possible, a runtime error occurs.


If the file is opened in TEXT MODE and if the character representation is UTF-8, you can only use character-type fields (C,N, D, T), strings, and purely character-type structures. The system does not check the component types, however, until runtime.

Example

DATA rec(80).
TRANSFER rec TO '/usr/test.dat'.

This example transfers the field rec to the file test.dat in the usr directory on the application server. The data record is 80 bytes long. If you do not specify a directory, the file is written in the directory specified in the profile parameter DIR_HOME.

Notes

• You can read sequential datasets using the READ DATASET statement.
  
  
  
• If the file is opened implicitly by the TRANSFER statement, the system automatically performs an authorization check. If this fails, a runtime error occurs. To avoid this, you can check the authorization yourself using the function module AUTHORITY_CHECK_DATASET.
  
  
  
• There is no locking mechanism for statements that work with files. Consequently, competing access from more than one process to the same file can lead to unexpected results. If multiple access to files is necessary, you must program a synchronization in your application program.
  
  
  
• The forms of file names are operating system-specific. You can create portable file names using the function module FILE_GET_NAME, which generates an appropropriate file name for a particular operating system from a logical file name.
  
  
  
• If the data object is a structure containing fields with type F, I, P, or X, the fields are not converted. You cannot write structures of this kind in text mode, since the byte sequences in them can be interpreted as line breaks. Instead, you must move them into a structure consisting only of character fields before writing them.
  
  
  
• If you write structures containing binary data in binary mode, the result may be platform-specific.
  
  
  

Exceptions

Catchable Exceptions

CX_SY_CODEPAGE_CONVERTER_INIT

• Cause: This type of conversion is not supported - for example, the language specified by the SET LOCALE LANGUAGE addition may not be supported.
  Runtime Error: CONVT_CODEPAGE_INIT (catchable)
  

CX_SY_CONVERSION_CODEPAGE

• Cause: Conversion cannot be carried out. (see also the note below).
  Runtime Error: CONVT_CODEPAGE (catchable)
  

CX_SY_FILE_AUTHORITY

• Cause: You do not have the authorization to access a file.
  Runtime Error: OPEN_DATASET_NO_AUTHORITY (catchable)
  

CX_SY_FILE_IO

• Cause: An error occurred when writing to the file.
  Runtime Error: DATASET_WRITE_ERROR (catchable)
  

CX_SY_FILE_OPEN

• Cause: Cannot open the file.
  Runtime Error: DATASET_CANT_OPEN (catchable)
  

CX_SY_FILE_OPEN_MODE

• Cause: The system cannot write to the file, because it was opened in a Unicode program using the OPEN DATASET ... FOR INPUT addition. The file must be opened using the FOR UPDATE or FOR OUTPUT addition.
  Runtime Error: DATASET_READ_ONLY (catchable)
  

CX_SY_TOO_MANY_FILES

• Cause: You have exceeded the maximum number of files that can be open simultaneously.
  Runtime Error: DATASET_TOO_MANY_FILES (catchable)
  

A CONVT_CODEPAGE can occur in either of the following two situations:

• If an internal error occurs during conversion. In this case, all text data is invalid. Data of the types I, F and P are valid. (This is relevant if, for example, a structure with both text and numeric fields is read in LEGACY ... MODE).
  
• If a character cannot be represented using the specified codepage. In this case the character or characters causing the error are replaced by the character specified in the REPLACEMENT CHARACTER addition to the OPEN DATASET statement. You can prevent the runtime error CONVT_CODEPAGE from occurring by including the IGNORING CONVERSION ERRORS addition in the OPEN DATASET statement.
  
  
  

Addition

... LENGTH len

Effect

The length of the data object to be written is defined by len, where len can be either a constant or a variable. The length is specified in bytes if the file is opened in BINARY MODE or LEGACY MODE. Note that alignment bytes are included in the length, if the data object is a structure. If the file is opened in TEXT MODE, the length refers to the number of characters that are to be written.

If len is shorter than the data object f, the system truncates f on the right.

With type I or F fields, unexpected results may occur if len is shorter than the default length for the field type.

Related

OPEN DATASET, READ DATASET, CLOSE DATASET, GET DATASET, SET DATASET

Additional help

Writing Data to Files