xHarbour Reference Documentation > Function Reference

FRename()

Renames a file.

Syntax

FRename( <cOldFile>, <cNewFile> ) --> nSuccess

Arguments

<cOldFile>

This is a character string holding the name of the file to rename. It must include path and file extension. The path can be omitted from <cOldFile> when the file resides in the current directory.

<cNewFile>

This is a character string with the new file name including file extension. Drive and/or path are optional.

Return

The function returns a numeric value. 0 indicates success and -1 is returned for failure. The cause of a failure can be determined using function FError()

Description

The FRename() function changes the name of a file. The file <cOldFile> is searched in the current directory only, unless a full qualified file name including drive and path is specified. Directories specified with SET DEFAULT and SET PATH are ignored by FRename().

If <cNewFile> is specified as a full qualified file name and its directory differs from the one of <cOldFile>, the source file is moved to the new directory and stored under the new file name.

When the new file either exists or is currently open, FRename() aborts the operation. Use the File() function to test for the existence of <cNewFile>.

A file must be closed before attempting to rename it.

Info

See also:	CLOSE, ERASE, FCReate(), FErase(), FError(), File(), RENAME
Category:	File functions , Low level file functions
Source:	rtl\philes.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example changes the name of an existing Log file
// for archival purposes and creates a new Log file

   PROCEDURE Main
      LOCAL nLogs, nHandle

      IF File( "Logfile.txt" )
         nLogs := 0
         DO WHILE File( "Logfile." + Padl( nLogs, 3, "0" ) )
            nLogs ++
            IF nLogs > 999
               nLogs := 0
               EXIT
            ENDIF
         ENDDO

         IF FRename( "Logfile.txt", ;
                     "Logfile." + Padl( nLogs, 3, "0" ) ) == -1
            ? "Error renaming file:", FError()
         ENDIF
      ENDIF

      nHandle := FCreate( "Logfile.txt" )
      IF FError() == 0
         FWrite( nHandle, "Created: " + DtoS(Date()), 17 )
         FClose( nHandle )
      ENDIF
   RETURN