RENAME

ANSI

The RENAME instruction changes the name of a file on the disk. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

source

Required. A previously defined Character String Variable or Literal containing the current name of the file.

dest

Required. A previously defined Character String Variable or Literal containing the new name of the file.

Flags Affected: NONE

Note the following:

1. Both a {source} and {dest} file name must be specified. The first operand is the source file name and the second operand is the new destination file name. If a character string variable is specified for either, only the Logical String is used.

2. RENAME must be able to have exclusive access to the file being renamed, i.e., it must not be open in this or any another PL/B program or process. Otherwise, an I/O error occurs.

3. If the specified file cannot be found, an I/O error occurs.

4. The new file name must not conflict with any operating system rules regarding file names or any other file name already in use. Otherwise, an I/O error occurs.

5. File paths are supported, including moving the source file to a different destination subdirectory. However, it is not possible to move files across different drives or to use global/wildcard file naming conventions (i.e., using asterisks `*' or question marks `?').

6. Under PLBCMP, if a file name starts with a '$' character, it is scanned to the first non-alpha non-numeric character. The environment table is then searched for this entry. If a matching entry is found, the string associated with the entry is substituted within the file name. An entire file name may be substituted in this manner, or all or a portion of a file path may be specified in this manner.

7. If the {source} has a vertical bar (|) and an IP number or host name appended, the operation is redirected to the SUNDM data manager.

8. The RENAME instruction is not supported when using SQLIO.

9. A Datapoint style filename of `filename/ext:drv' is converted to a Sunbelt format as follows:

• If an extension is found, the '/' extension delimiter is now changed to a Sunbelt extension delimiter character defined in the screen definition file used by the runtimes. The default extension delimiter would replace the '/' delimiter with a period .

• The ':drv' specification in a Datapoint filename is changed to a substituted string defined by a UET keyword that must be defined by appending the Datapoint drive identification string to 'PLBVOL_'. In the above case the UET string must be defined as 'PLBVOL_DRV={path}' in the environment table or in the 'PLBWIN.INI' file. If the UET keyword is not found, the runtime attempts to open the file with no changes. However, if the UET keyword is found, the runtime changes the filename to '{path}\filename.ext'.
  
  Example: UET has environment entry defined as:
  PLBVOL_WORK1=c:\data1 and PLB_WORK2=c:\data2
  
  RENAME      "name1/txt:work1","name2/sav:work2"
  
  Actual file c:\data1\name1.txt renamed to c:\data2\name2.sav 

See Also: Example Code, ERASE, Disk I/O Instructions