RENAME Routine

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 MS-DOS, 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. See the documentation in Appendix H, Configuration File Entries, for information about the terminating character for path names.