Function FRename() | Xbase++

Changes the name of a file.

FRename( <cOldName>, <cNewName> ) --> nSuccess

<cOldName> is a character string containing the name of a file to rename, including the drive and path if necessary.

<cNewName> is a character string containing the new name for the file, including the drive and path if necessary.

When the file was successfully renamed by FRename(), the function returns the value 0. If the operation fails, the return value is -1 and FError() can be used to retrieve the error code.

The low level file function FRename() renames a file. The file is renamed only if <cOldFile> and <cNewFile> have valid file names. A successful operation is identified by the return value 0. If the operation fails, the return value is -1 and FError() can be used to determine the file error that occurred.

Low level file functions do not use either the path set with SET PATH or specified with SET DEFAULT. Therefore <cOldName> and <cNewName> must be complete file names with drive and path specified. When the file names contain no drive or path, the current directory is searched for <cOldName>.

If the target path is different from the initial path, the file is moved to the target path. If a file already exists with the name <cNewName>, the operation is terminated and FRename() returns the value -1.

Before a file is renamed with FRename(), it must be closed with FClose() if it is open. When a DBF file which has memo fields is renamed, the DBT file must also be renamed since otherwise the renamed DBF file cannot be opened with USE again.

Rename a DBF file with FRename()


// The example shows a function that renames a DBF file 
// along with its memo file if it exists. 

PROCEDURE Test 

   ? DbfRename( "Address.dbf", "Customer.dbf" ) 

RETURN 

FUNCTION DbfRename( cOldName, cNewName ) 

   cOldName := Upper( cOldName ) 
   cOldName := StrTran( cOldName, ".DBF", "" ) 

   cNewName := Upper( cNewName ) 
   cNewName := StrTran( cNewName, ".DBF", "" ) 

   IF FRename( cOldName+".DBF", cNewName+".DBF" ) == -1 
      ? "File error with DBF file:", FError() 

   ELSEIF File( cOldName+".DBT" ) .AND. ; 
          FRename( cOldName+".DBT", cNewName+".DBT" ) == -1 

      ? "File error with memo file:", FError() 
   ENDIF 

RETURN FError()

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function FRename() Foundation