MoveFolder
MoveFolder [/D /I[=i]/M=messageStr /O/P=pathName /S=saveMessageStr /Z[=z ] ] [srcFolderStr ] [ as destFolderStr ]
The MoveFolder operation moves or renames a folder on disk. A folder is renamed by "moving" it into the same folder it is already in, but with a different name.
The MoveFolder command can destroy data by overwriting another folder and contents!
If you overwrite an existing folder on disk, MoveFolder will do so only if permission is granted by the user. The default behavior is to display a dialog asking for permission. The user can alter this behavior via the Miscellaneous Settings dialog's Misc category.
If permission is denied, the folder will not be moved and V_Flag will return 1088 (Command is disabled) or 1275 (You denied permission to overwrite a folder). Command execution will cease unless the /Z flag is specified.
Parameters
srcFolderStr can be a full path to the folder to be moved or renamed (in which case /P is not needed), a partial path relative to the folder associated with pathName, or the name of a folder within the folder associated with pathName.
If Igor cannot determine the location of the source folder from srcFolderStr and pathName, it displays a Select Folder dialog allowing you to specify the source.
If /P=pathName is given, but srcFolderStr is not, then the folder associated with pathName is moved or renamed.
destFolderStr specifies the final location of the folder or, if /D is used, the parent of the final location of the folder.
destFolderStr can be a full path to the output (destination) folder (in which case /P is not needed), or a partial path relative to the folder associated with pathName.
If Igor cannot determine the location of the destination folder from destFolderStr and pathName, it displays a Save Folder dialog allowing you to specify the destination.
If you use a full or partial path for either file, see Path Separators for details on forming the path.
Flags
| /D | destFolderStr is interpreted as the name of (or path to) an existing folder (or "directory") to move the source folder into. Without /D, destFolderStr is interpreted as the name of (or path to) the moved folder. | ||||||||
| If destFolderStr is not a full path to a folder, it is relative to the source folder. | |||||||||
| /I [=i ] |
| ||||||||
| /M=messageStr | Specifies the prompt message in the Open File dialog. If /S is not specified, then messageStr will be used for both Open File and for Save File dialogs. | ||||||||
| /O | Overwrite existing destination folder, if any. This deletes the existing destination folder. When /O is specified, the source folder can't be moved into an existing folder without specifying the name of the moved folder in destFolderStr. | ||||||||
| /P=pathName | pathName is the name of an existing symbolic path. | ||||||||
| Specifies the folder for relative paths in srcFolderStr and destFolderStr. If srcFolderStr is omitted, the folder associated with pathName is moved. If destFolderStr is omitted, the source folder is moved into the folder associated with pathName. | |||||||||
| Using /P means that srcFolderStr (if specified) and destFolderStr must be either simple folder names or paths relative to the folder specified by pathName. | |||||||||
| /S=saveMessageStr | Specifies the prompt message in the Save File dialog. | ||||||||
| /Z[=z ] | Prevents procedure execution from aborting if it attempts to move a folder that does not exist. Use /Z if you want to handle this case in your procedures rather than having execution abort. | ||||||||
| |||||||||
Variables
The MoveFolder operation returns information in the following variables:
| V_flag | Set to zero if the file was moved, to -1 if the user cancelled either the Open File or Save File dialogs, and to some nonzero value if an error occurred, such as the specified file does not exist. | |
| S_fileName | Stores the full path to the folder that was moved, with a trailing colon. If an error occurred or if the user cancelled, it is set to an empty string. | |
| S_path | Stores the full path of the moved folder, with a trailing colon. If an error occurred or if the user cancelled, it is set to an empty string. | |
Details
You can use /P=pathName alone (omitting srcFolderStr) to specify the source folder to be moved.
A folder may not be moved into one of its own subfolders.
Conversely, the command:
MoveFolder/O/P=myPath "afolder"
which attempts to overwrite the folder associated with myPath with a folder that is inside it (namely "afolder") is not allowed. Instead, use:
MoveFolder/O/P=myPath "::afolder"
On Windows, renaming or moving a folder never updates the value of any Igor Symbolic Paths that point to a moved folder:
// Create a folder
NewPath/O/C myPath "C:\\My Data\\My Work"
// Move the folder
MoveFolder/P=myPath as "C:\\My Data\\Moved"
// Display the path's value
PathInfo myPath // (or use the Path Status dialog)
Print S_Path
C:My Data:My Work
You can use PathInfo to determine if a folder referred to by an Igor symbolic path exists and where it is on the disk. Use NewPath/O to reset the path's value.
Moving the folder to a different volume actually creates a new folder with new volume refnum and directory IDs, and symbolic paths pointing to or into the moved folder aren't updated. They will be pointing at a deleted folder (they're probably invalid).
Examples
// Rename a folder ("move" it to the same folder)
MoveFolder "C:Users:jim:Documents:Subfolder" as "C:Users:jim:Documents:Subfolder Renamed"
// Rename a folder referred to by only a path name (myPath).
// Create the symbolic path name for full path to my Documents\Subfolder
String docs = SpecialDirPath("Documents", 0, 0, 0) // has trailing ":", Macintosh format
String pathToFolder = docs+"Subfolder" // no trailing ":"
NewPath/O/Q myPath, pathToFolder
MoveFolder/P=myPath as "::Subfolder Renamed"
// Move a folder from one volume to another, renaming the moved folder
// This moves F:\:Test Data inside my Documents\Subfolder folder.
// Without /D the destFolderStr is the name of the moved folder.
MoveFolder "F:\\Test Data" as "C:\\Users\\jim\\Documents\\Subfolder\\Moved Test Data"
// Move a folder from one volume to another.
// This moves F:\:Test Data inside my Documents\Subfolder folder.
// The /D flag is used to move Test Data without renaming the moved folder.
MoveFolder/D "F:\\Test Data" as "C:\\Users\\jim\\Documents\\Subfolder"
// Move a folder's contents from one volume to another.
// On Windows, /O MERGES the contents of F:\Test Data with an existing Moved Text Data folder.
// On Macintosh /O REPLACES the entire Moved Test Data folder (if it existed) with the moved Test Data and contents.
// Before overwriting (whether merging or replacing), the user is prompted for permission unless disabled in Misc Settings.
MoveFolder/O "F:\\Test Data" as "C:\\Users\\jim\\Documents\\Subfolder\\Moved Test Data"
// Move user-selected folder in any folder as "Renamed Folder"
// into a user-selected folder (possibly the same one)
MoveFolder as "Renamed Folder"
// Move user-selected file in any folder as "Moved Folder"
// in any folder
MoveFolder/I=3 as "Moved Folder"
See Also
MoveFile, CopyFolder, DeleteFolder, IndexedDir, Symbolic Paths, PathInfo, RemoveEnding, Path Separators