RENAME

Renames the existing file. RENAME takes two, three, or four USING parameters.

Usage

CALL "RENAME" 
    USING SOURCE-FILE, DEST-FILE, RENAME-STATUS, FILE-TYPE

Parameters

SOURCE-FILE PIC X(n) Contains the name of the file to rename.
DEST-FILE PIC X(n) Contains the new name for the file. The RENAME routine will remove the destination file if necessary.
RENAME-STATUS PIC 9(9) COMP-4 This parameter will be set to ZERO if the routine is successful, otherwise it will be set to the operating system's error number.
FILE-TYPE PIC X Indicates the file type. If the FILE-TYPE parameter is used, it must specify either an "S" for a sequential file, an "R" for a relative file, or an "I" for an indexed file. If FILE-TYPE is not used, it is assumed to be "S". This can be useful in cases where the file is held in more than one physical disk file (for example, C-ISAM indexed files are physically held in two separate files). If the FILE-TYPE parameter is omitted, then only the single physical file named in SOURCE-FILE is renamed.

Comments

The file being renamed should be closed. Note that the RENAME routine cannot rename a file across different drives under Windows, but it can change a file's directory. Under UNIX systems, the RENAME procedure will attempt to copy the file if the target name is on a different device. This may take some time if the file is large. If the copy is successful, the original file is removed.

Note: The behavior of this library routine is affected by the setting of the FILENAME_SPACES configuration variable that may or may not allow spaces in a file name. See the documentation on FILENAME_SPACES in Appendix H for information about the terminating character for path names.