Guardian Procedure Calls Reference Manual

Returned Value
INT
A file-system error code that indicates the outcome of the call.
Considerations
• Purge access for FILE_RENAME_
The caller must have purge access to the file for the rename operation to be successful;
otherwise, FILE_RENAME_ returns error 48 (security violation).
• Volume specification for newname
The disk volume designated in newname (explicitly or implicitly) must be the same as the
volume specified when opening the file. Neither the volume name nor the system name can
be changed by FILE_RENAME_.
• System specification for newname
If a system is specified as part of newname, it must be the same as the system name used
when the file was opened.
• Partitioned files
When the primary partition of a partitioned file is renamed, the file system automatically
renames all other partitions located anywhere in the network.
• Renaming a file audited by the Transaction Management Facility (TMF) subsystem
The file to be renamed cannot be a file audited by the TMF subsystem. An attempt to rename
such a file fails with error 80 (invalid operation attempted on audited file or nonaudited disk
volume).
• Structured files with alternate keys
If the primary-key file is renamed, it remains linked with the alternate-key file. If you rename
the alternate-key file and then try to access the primary-key file, an error 4 (failure to open an
alternate-key file) occurs because the primary-key file is still linked with the old name for the
alternate-key file. You can use the File Utility Program (FUP) ALTER command to correct this
problem.
• SQL/MX Objects
FILE_RENAME_ cannot be used with SQL/MX objects. If a SQL/MX object is specified,
file-system error 2 is returned.
• Support for key-sequenced files with increased limits
FILE_RENAME_ can be used to change the names of open format 2 legacy key-sequenced
files with increased limits and enhanced key-sequenced files with increased limits in
H06.28/J06.17 RVUs with specific SPRs and later RVUs; the behavior of the API is unchanged.
(For a list of the required H06.28/J06.17 SPRs, see SPR Requirements for Increased Enscribe
Limits for the H06.28/J06.17 Release (page 31).)
Safeguard Considerations
For information on files protected by Safeguard, see the Safeguard Reference Manual.
OSS Considerations
Error 564 (operation not supported on this file type) is returned if you attempt to rename an OSS
file using the FILE_RENAME_ procedure.
FILE_RENAME_ Procedure 497