DEV Community

Peter + AI
Peter + AI

Posted on

📁 Renaming Files in Uniface: A Complete Guide to the filerename Statement

#uniface #fileoperations #programming #database

Working with file operations in Uniface? The filerename statement is your go-to tool for renaming files within the same directory. Let me walk you through everything you need to know about this useful function! 🚀

This article is based on the Uniface Documentation 10.4 and was created with the assistance of AI to provide you with a comprehensive overview.

🔧 Basic Syntax

The filerename statement follows a simple syntax:

filerename FilePath, NewFileName
Enter fullscreen mode Exit fullscreen mode

Here's a quick example:

filerename "sub1dir/test.txt", "tested.txt"
Enter fullscreen mode Exit fullscreen mode

📋 Parameters Breakdown

Parameter Data Type Description
FilePath String File name with optional path. Must not end with directory separator
NewFileName String New file name only. No path included, no directory separator at end

✅ Return Values

  • 0: Success! 🎉
  • -13 (UIOSERR_OS_COMMAND): OS command error occurred 🚨

Pro tip: Set /pri=64 to display the exact error message in the message frame when troubleshooting! 💡

🎯 Key Features

📂 File Location Flexibility

  • Works with any file redirections in the assignment file
  • Supports renaming files within ZIP archives
  • Can be used in all component types

🛣️ Path Specifications

You can specify file names using:

  • String literals
  • Field references (direct or indirect)
  • Variables
  • Functions that evaluate to strings

Important: Path length must not exceed 255 bytes! 📏

⚠️ Common Pitfalls

The operation will fail if:

🔒 Source File Issues

  • File doesn't exist
  • Path points to a directory, not a file
  • File is currently in use (locked)
  • Insufficient authorization level
  • Invalid syntax

🎯 Target File Issues

  • New filename already exists
  • Invalid syntax in new filename
  • Attempting to use $RES path for NewFileName

💼 Practical Examples

Standard Usage 

filerename "sub1dir/test.txt", "tested.txt"
Enter fullscreen mode Exit fullscreen mode

Alternative Syntax 

filerename "[.sub1dir]test.txt;5", "tested.txt"
Enter fullscreen mode Exit fullscreen mode

Using with Resources Deployment Path ($RES) 

filerename "$RES:sub1dir/test.txt", "tested.txt"
Enter fullscreen mode Exit fullscreen mode

⚠️ Important: Only use $RES with FilePath, never with NewFileName!

🖥️ Platform-Specific Notes

iSeries Considerations

On iSeries systems, changing a file's extension implies moving a member to a different file. For example:

filerename "lib/aaa.ext1", "bbb.ext2"
Enter fullscreen mode Exit fullscreen mode

This moves member aaa from file ext1 to file ext2 and renames it to bbb. The target file must already exist with appropriate access rights! 🔐

🎉 Conclusion

The filerename statement is a powerful and straightforward tool for file management in Uniface. Remember the key points:

  • Only renames within the same directory
  • NewFileName should not include path information
  • Always check return values for error handling
  • Be mindful of platform-specific behaviors

Happy coding! 💻✨

Top comments (0)