xHarbour Reference Documentation > Command Reference

RENAME

Changes the name of a file.

Syntax

RENAME <cOldFile> TO <cNewFile>

Arguments

<cOldFile>

This is name of the file to rename. It must include path and file extension and can be specified as a literal file name or as a character expression enclosed in parentheses. The path can be omitted from <cOldFile> when the file resides in the current directory.

TO <cNewFile>

This is the new file name including file extension. Drive and/or path are optional. <cNewFile> can be specified either as a literal string or as a character expression enclosed in parentheses.

Description

The RENAME command 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 RENAME.

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, RENAME aborts the operation. Use the File() function to test for the existence of <cNewFile>.

A file must be closed before attempting to rename it.

Important:  Database files with memo fields have accompanying memo files. Memo files must be renamed along with their database files.

Info

See also:	COPY FILE, CurDir(), ERASE, FErase(), FError(), File(), FRename()
Category:	File commands
Source:	rtl\philes.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example shows a user defined function that renames a database file
// along with its memo file.

   PROCEDURE Main

      ? File( "Customer.dbf" )      // result: .T.
      ? File( "Customer.fpt" )      // result: .T.

      ? File( "Cust2005.dbf" )      // result: .F.
      ? File( "Cust2005.fpt" )      // result: .F.

      DbRename( "Customer.dbf", "Cust2005.dbf" )

      ? File( "Customer.dbf" )      // result: .F.
      ? File( "Customer.fpt" )      // result: .F.

      ? File( "Cust2005.dbf" )      // result: .T.
      ? File( "Cust2005.fpt" )      // result: .T.

   RETURN

   FUNCTION DbRename( cOldFile, cNewFile )
      LOCAL cOldName := SubStr( cOldFile, 1, Rat( ".", cOldFile ) )
      LOCAL cNewName := SubStr( cNewFile, 1, Rat( ".", cNewFile ) )
      LOCAL cMemoExt, n
      LOCAL aMemoExt := { "DBT", "FPT", "SMT" }

      IF ! File( cOldFile ) .OR. File( cNewFile )
         RETURN .F.
      ENDIF

      FOR n:=1 TO 3
         IF File( cOldName + aMemoExt[n] )
            cMemoExt := aMemoExt[n]
            EXIT
         ENDIF
      NEXT

      RENAME (cOldFile) TO (cNewFile)

      IF ! Empty(cMemoExt) .AND. File( cOldName+cMemoExt )
         RENAME (cOldName+cMemoExt) TO (cNewName+cMemoExt)
      ENDIF
   RETURN .T.