Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎

RENAME

Keyword Abbreviation Token (hex) Version(s) Classification
RENAME RE{Shift+N} D8 4.x Command and Statement
TRON TR{Shift+O} D8 3.5, 7.0 Function
RENAME RE{Shift+N} F5 3.5, 7.0 Command and Statement

  Syntax   
RENAME oldName D fileDrive ] [ { , | ON } U unitNumber ] ... [ , ItwoChar ] [ , R ] ... TO newName [ { , | ON } U unitNumber ] ...
 
Parameters Type Legal Value(s) Default Value Note(s)
oldName  String  1 to 16 characters   Must not begin with @ 
fileDrive Integer 0 or 1 0 Non-literal must be enclosed in parentheses ()
newName String  1 to 16 characters   Must not begin with @ 
unitNumber Integer  8 ~ 11  Non-literal must be enclosed in parentheses () 
twoChar Char[2]  any    Must be two literal characters. 
 
 
  Purpose  
Media file manipulation.  Changes the name of an existing file.

 
  Remarks  
RENAME changes the name of an existing file, oldName, to newName.  The parameters oldName and newName are the filenames (of a single file) before and after RENAME, respectively.  They must be on the same drive (fileDrive) of the same device (unitNumber).
 
Both filenames are required.  If either filename has more than 16 characters then STRING TO LONG ERROR will be generated instead.  If either filename has zero characters then MISSING FILE NAME ERROR occurs.  If either filename begins with an @ character, BASIC generates SYNTAX ERROR (even though the device may allow this). 
 
Most devices will complain if either filename includes wild-card characters, like ? and *, but BASIC does not care.    Most devices will not allow the names to be in different directories (have different paths).  Due to the 16-character limitation of BASIC (and the way some devices specify a path) you probably can't include a path in either filename anyway.
 
Most devices allow oldName to refer to anything inside a directory; "real" PRG/REL/SEQ/USR files, or 1581-partitions, or CMD/FAT directories.  There is no standard way to rename the current directory (or "disk header" for disks with only one directory), although a device could conceivably allow this.
 
Assuming the Syntax is good, BASIC sends a command to the device (this updates ST) and reports no error unless the command transmission failed (for example, DEVICE NOT PRESENT).  However, if the oldName does not already exist, the device will normally generate an error "62, FILE NOT FOUND,00,00".  If the newName already exists, the device will usually generate "63, FILE EXISTS,00,00".  The device might generate an error in other cases (like write-protected file or media).  Be sure to check the device status with DS or DS$.
 
Although the Syntax allows unitNumber to be specified before or after the TO preposition (in fact, an unlimited number of times), only the last unitNumber given is used; the default is 8 if unitNumber is not given at all.
 
If a required parameter is omitted, or an expression (enclosed in parentheses) is not valid, or an expression is used without parentheses, SYNTAX ERROR occurs.  If any parameter is not the correct type (string or numeric) a TYPE MISMATCH ERROR will be generated.  Otherwise if a parameter is not a legal value (see table above), an ILLEGAL QUANTITY ERROR is generated.
  
Like all disk commands and statements, the Syntax is more flexible than shown above.  In particular, the parameters may be given in any order.  The general restrictions are: a comma (,) must not precede the first parameter, any non-literal value (a variable name or expression) must be enclosed in parentheses (), and do not supply the same parameter more than once.  Exceptions include the U and R parameters, which may used an unlimited number of times (R is ignored), and the twoChar parameter which must always be two literal characters (also ignored but may not be repeated). 
  
Like all disk-based commands, RENAME restricts the "drive/parittion" number (fileDrive) to be either 0 or 1 which often makes it unusable on a "disk" with multiple partitions.  On the other hand, many CBM drives (1541, 1551, 1571, 1581) only allow drive 0.
 
Like all disk-based commands, RENAME will reset DS$ and set the secret variable "DosFA" to the unitNumber.
 
Examples:
RENAME "BKUP" TO "NOW"    : REM change name of BKUP to NOW on drive 0, unit 8
RENAME "BKUP",D1 TO "NOW" : REM change name of BKUP to NOW on drive 1, unit 8
RENAME "BKUP" TO "NOW",U9 : REM change name of BKUP to NOW on drive 0, unit 9
RENAME (M$)TO(B$),U(U)    : REM using variables (on drive 0)
 
 
  Compare With  
 
  Contrast With  
  See Also  
DS, DS$, ONPRINT#ST, TO 
© H2Obsession, 2014
Comments