MultiScript - File system functions

File and Folder Properties

GetFileTime Get the date/time of a file or folder.
SetFileTime Set the date/time of a file or folder.
IsFolder Check if a file item is a folder.
FileExists Check if a file (or folder) exists.
GetFileSize Get the size of a file.
GetFileProp Get a file property.
GetFSLinkType Get what link type a link is (Symbolic link, Shortcut, hardlink, Junction).
GetFSLinkTarget Get the target path of a file system link.
GetWinShortcutTarget Get the target path of a shortcut link (.lnk).

Filesystem Matching

FindFirstFile Return the first matching file.
FindFiles Return an array of all matching files.

File Attributes

GetFileAttributes Return the attributes of a file or folder.
AddFileAttributes Add an attribute(s) to a file or folder.
RemoveFileAttributes Remove attribute(s) from a file or folder.
SetFileAttributes Set attribute(s) of a file or folder (replace existing).
HasFileAttributes Check if a file or folder has specified attribute(s).

Filesystem Operations

CopyFile Copy a file.
MoveFile Move a file.
RenameFile Rename a file.
UnpackFile Unpack an archive (zip, 7z, rar, tar, tgz).
PackFile Pack file(s) into an archive (zip, 7z, tar, gz).
DeleteFile Delete a single file or folder.
DeleteFiles Delete multiple files or folders.
MakeDir Create a new folder.

Filesystem Filtering

FilterCreate Create a filter handle.
FilterAddRule Add a filter rule.
FilterLoad Load a filter from file.
FilterLoadById Load an existing advanced filer by id.
FilterSave Save a filter to file.
FilterIsMatch Test if a file is a match against a filter.

File Path Operations

PathGetPathPart Get the path part of a full filename path.
PathGetNamePart Get the name path of a full filename path.
PathGetFileExtPart Get the file extension of a full filename path.
PathGetParts Get an array of all file path parts.

File Path Conversion Operations

PathMakeRelativeMC Convert a path to be relative to where Multi Commander is started from.
PathMakeAbsoluteMC Convert a relative path to an absolute path.
PathTranslatePath Convert a relative path to absolute; also expand environment string.

Network File Operations

NetWGet Download web content to file.

GetFileTime

Get the date/time of a file or folder.

<num> GetFileTime( <str> path, [<num> utctime], [<num> filetimepart] );

Parameters

path
Path to the file/folder of interest
utctime
(Optional, default: 0)
0 = Return time in local time 1 = Return time in UTC
filetimepart
(Optional, default: 0)
0 = Last Write time
1 = Create time
2 = Last Access time

Return value

0 for failure, else the number of seconds since 1970-01-01 00:00:00

Example

// Change the time of the file item in focus to 1h previous ( 3600 sec )
@var $time = 0;
@var $file = GetSourceFocusPath();
if( StrLen( $file ) > 0 )
{
  $time = GetFileTime( $file );
  $time = $time - 3600;
  SetFileTime( $file, $time );
}

SetFileTime

Set the date/time of a file or folder.

<num> SetFileTime( <str> path, <num> time, [<num> utctime], [<num> filetimepart] );

Parameters

path
Path to the file/folder of interest
time
Time in seconds since 1970-01-01 00:00:00
utctime
(Optional, default: 0)
0 = Return time in local time
1 = Return time in UTC
filetimepart
(Optional, default: 0)
0 = Last Write time
1 = Create time
2 = Last Access time
4 = Last Write, Create and Last Access

Return value

1 for success, else 0

Example

// See GetFileTime

IsFolder

Return 1 if the specified path is a folder.

<num> IsFolder( <str> path );

Parameters

path
Path to a file or folder to be checked

Return value

1 if the path exists and is a folder, else 0

Example

@var $res = IsFolder( "C:\\temp" );

FileExists

Return a value > 0 if the specified file exists.

<num> FileExists( <str> path );

Parameters

path
Path to a file be checked

Return value

1 if the path exists and is a file, 2 if the path exists and is a folder, 0 if the path does not exist

Example

@var $res = FileExists( "C:\\temp\\MyFile.txt" );

GetFileSize

Return the size of the file.

<num> GetFileSize( <str> path );

Parameters

path
Path to a file or folder to be checked

Return value

The file size in bytes, or 0 if the item is not a file or does not exist

Example

@var $res = GetFileSize( "C:\\temp\\MyFile.txt" );

GetFileProp

Return a file property of a file.

<num> GetFileProp( <str> path, <str> fileProp );

Parameters

path
Path to the file or folder of interest
fileProp
File property name (eg. "MCAudioProp.genre")

Return value

A string containing the file property

Example

@var $res = GetFileProp( "C:\\temp\\MyPopSong.mp3", "MCAudioProp.genre" );
// res == "pop"

Notes

See the File Property List for a list of all the available file properties.
(These are the same file properties as are used by the MultiRename tool.)

GetFSLinkType

Get what link type a link is.

<num> GetFSLinkType( <str> path);

Parameters

path
Path to the file or folder of interest

Return value

0 - Not a link
1 - Junction
2 - Symlink
3 - MountPoint

Example

@var $res = GetFSLinkType( 'C:\\Documents and Settings' );
// res == 1 // Junction

GetFSLinkTarget

Get the target path of a file system link..

<str> GetFSLinkTarget( <str> path);

Parameters

path
Path to the file or folder of interest

Return value

The path of the linktarget.

Example

@var $res = GetLinkTarget( 'C:\\Documents and Settings' );
// res == "C:\\Users"

GetWinShortcutTarget

Get the target path of a shortcut (.lnk).

<str> GetWinShortcutTarget( <str> path);

Parameters

path
Path to the file or folder of interest

Return value

The path of the shortcut.

Example

@var $res = GetWinShortcutTarget( 'C:\\MyFolder\\MyShortcut.lnk' );
// res == "C:\\Users"

FindFirstFile

Return the first matching file name (this function also exists as "_findfirstfile" ).

<str> FindFirstFile( <str> path, [<num> nameOnly], [<num> dbgInfo] );

Parameters

path
Path with filter. eg. "c:\\myfolder\\*.txt"
nameOnly
Optional. If 1, return only the name and extension; no path
dbgInfo (Optional)
If 1, output extra debugging information to the log window

Return value

Full file path to the first matching file

Example

@var $file = FindFirstFile( "C:\\temp\\Co*.txt" );

FindFiles

Return array of matching files (this function also exists as "_findfiles" ).

<arr> FindFiles( <str> path, [<num> namesOnly], [<num> dbgInfo] );

Parameters

path
Path with filter. eg. "c:\\myfolder\\*.txt"
namesOnly
Optional. If 1, return only the names and extensions; no paths
dbgInfo
Optional. If 1, output extra debugging information to the log window

Return value

An array of full file paths of matching files

Example

@var $files = FindFiles( "C:\\temp\\*.txt" );

GetFileAttributes

Return a string of file attributes.

<str> GetFileAttributes( <str> path );

Parameters

path
Path of the file or folder to get attributes for

Return value

A string containing the attribute characters for the file or folder.
A - Archive
R - Read only
S - System
H - Hidden

Example

$attributes = GetFileAttributes( $path );

AddFileAttributes

Set an attribute for a file or folder.

<str> AddFileAttributes( <str> path, <str> attributes );

Parameters

path
Path of the file or folder to get attributes for
attributes
A string containing the attributes to add. Valid attributes are: a, r, s, h

Return value

1 if attributes was set, else 0.

Example

// Add Read Only attribute
AddFileAttributes( $path, "r" );

RemoveFileAttributes

Remove attributes from a file or folder.

<num> RemoveFileAttributes( <str> path, <str> attributes );

Parameters

path
File or Folder to remove attribute from
attributes
A string containing the attributes to remove. Valid attributes are: a, r, s, h

Return value

1 if attributes was set, else 0.

Example

// Remove the Read Only attribute
RemoveFileAttributes( $path, "r" );

SetFileAttributes

Set attributes for a file or folder, replacing existing attributes.

<num> SetFileAttributes( <str> path, <str> attributes );

Parameters

path
File or Folder to set attribute for
attributes
A string containing the attributes to add. Valid attributes are: a, r, s, h

Return value

1 if attributes was set, else 0.

Example

// Set the Read Only and Hidden attribute
SetFileAttributes( $path, "rh" );

HasFileAttributes

Check if a file or folder has particular attributes.

<num> HasFileAttributes( <str> path, <str> attributes );

Parameters

path
File or Folder to check attributes for
attributes
A string containing the attributes to check for. Valid attributes are: a, r, s, h

Return value

1 if the file or folder has the requested attributes, else 0. -1 for error

Example

// Check if a file has a Read Only attribute
$isReadonly = HasFileAttributes( $path, "r" );

CopyFile

Copy a single file or folder.

<num> CopyFile( <str> targetPath, <str> sourceFile, <str> options );

Parameters

targetPath
Target Path to where the file/folder should be copied
sourceFile
Source Path of the file/folder to copy
options
Optional parameter (case-sensitive). Separate multiple options with commas.
"NOWAIT" - Script will continue directly. Will not wait until copy is completed
"NOPROGRESS" - Show no progress window. No error dialog will be shown. It will always skip files on error
"NODIALOG" - Show no confirmation dialog
"OVERWRITE_ALL" - If a file already exists on the target path, overwrite it without asking
"SILENT" - Silent. Do not ask what to do: skip on errors and continue
"NEWQUEUE" - If a file operation already exists. Start a new queue (override default setting)
"USEEXISTINGQUEUE" - If a queued file operation already exists then use its queue (override default setting)

Return value

0 for failure, 1 for success

Example

CopyFile( $targetPath, $sourceFile, "NODIALOG, OVERWRITE_ALL" );
CopyFile( 'D:\Temp\', 'R:\MyFile\File.txt', "NODIALOG, OVERWRITE_ALL" );

MoveFile

Move a single file or folder.

<num> MoveFile( <str> targetPath, <str> sourceFile, <str> options );

Parameters

targetPath
Target Path to where the file/folder should be moved
sourceFile
Source Path of the file/folder to move
options
Optional parameter (case-sensitive). Separate multiple options with commas.
"NOWAIT" - Script will continue directly. Will not wait until copy is completed
"NOPROGRESS" - Show no progress window. No error dialog will be shown. It will always skip files on error
"NODIALOG" - Show no confirmation dialog
"OVERWRITE_ALL" - If a file already exists on the target path, overwrite it without asking
"SILENT" - Silent. Do not ask what to do: skip on errors and continue
"NEWQUEUE" - If a file operation already exists. Start a new queue (override default setting)
"USEEXISTINGQUEUE" - If a queued file operation already exists then use its queue (override default setting)

Return value

0 for failure, 1 for success

Example

MoveFile( $targetPath, $sourceFile, "NODIALOG, OVERWRITE_ALL" );
MoveFile( 'D:\Temp\', 'R:\MyFile\File.txt', "NODIALOG, OVERWRITE_ALL" );

RenameFile

Rename a file or folder using the Multi Commander virtual filesystem.

<num> RenameFile( <str> filepath, <str> newName, <str> options );

Parameters

filepath
Full path of the file to rename (eg. "C:\\temp\\myfile.txt")
Newname
The new file name. ONLY THE NAME. No path parts may be included
Options
Optional parameter (case-sensitive). Separate multiple options with commas.
"SILENT" - Show no error dialog. If any error occurs then abort and return then error code
"RENAME_RO" - Allow renaming of a file with readonly attribute (as long as the file system allows it)
"RENAMNE_OVR" - If a file with the new name already exists, overwrite it

Return value

1 if rename succeeded, else error code.

Example

@var $filename = "C:\\temp\\MyFile.txt";
@var $newname = "MyNewName.txt";

RenameFile( $filename, $newname, "SILENT, RENAME_OVR" );

UnpackFile

Unpack an archive using the file operations in Multi Commander.

<num> UnpackFile( <str> fileToUnpack, <str> targetFolder, <str> filter, <str> options, <str> password );

Parameters

fileToUnpack
Full path to the file you want to unpack (eg. "C:\\temp\\myfile.zip")
targetFolder
Path to where you want the files to be unpack into (eg. "C:\\temp\\")
filter
Wildcard filter used to match files to unpack. Empty or *.* to unpack all
options
Optional parameter (case-sensitive). Separate multiple options with commas.
"SILENT" - Show no error dialog. If any error occurs then abort and return then error code
"NOWAIT" - Script will continue directly. Will not wait until copy is completed
"NOPROGRESS" - Show no progress window. No error dialog will be shown. It will always skip files on error
"OVERWRITEALL" - If a file already exists on the target path, overwrite it without asking
"NOQUEUE" - If a file operation already exists. Start a new queue (override default setting)
"USEEXISTINGQUEUE" - If a queued file operation already exists then use its queue (override default setting)
Password
Optional parameter. Sets the password needed to unpack the archive, if archive is password protected

Return value

1 if unpacking succeeded, else error code

Example

@var $filename = "C:\\temp\\MyFile.zip";
@var $target = "C:\\temp\\Up\\";

UnpackFile( $filename, $target, "*.*", "NOWAIT, OVERWRITEALL", "password123" );

PackFile

Pack files and/or folders into a archive (zip,7z,..) using the Multi Commander file operations.

<num> PackFile( <str> targetFile, <str> sourceFile, <str> filter, <str> method, <str> options, <str> password );

Parameters

targetFile
Full path to the file to create (eg. "C:\\temp\\myfile.zip")
sourceFile
Full path to file or folder to pack
filter
Wildcard filter to use when adding files to archive
method
compression profile to use or default method for that type (eg. "zip" )
options
Optional parameter (case-sensitive). Separate multiple options with commas.
"SILENT" - Show no error dialog. If any error occurs then abort and return then error code
"NOWAIT" - Script will continue directly. Will not wait until copy is completed
"NOPROGRESS" - Show no progress window. No error dialog will be shown. It will always skip files on error
"OVERWRITEALL" - If a file already exists on the target path, overwrite it without asking
"NOQUEUE" - If a file operation already exists. Start a new queue (override default setting)
"USEEXISTINGQUEUE" - If a file operation already exists then use it (override default setting)
Password
Optional parameter. Password you want to set for the archive if you want to protect it

Return value

1 if packing succeeded, else error code

Example

@var $filename = "C:\\temp\\MyFile.zip";
@var $folderToPack = "C:\\temp\\MyFiles\\";

PackFile( $filename, $folderToPack, "*.*", "zip", "NOWAIT" );
// or
PackFile( $filename, $folderToPack, "*.txt", "Internal Zip (Max)", "NOWAIT", "MyPassword" );

DeleteFile

Delete a single file using the Multi Commander virtual filesystem.

<num> DeleteFile( <str> filename, <arr> options );

Parameters

filename
file or folder to delete
options
Optional parameter (case-sensitive). Separate multiple options with commas.
"RECYLE" - Delete to recycle bin
"NOPROGRESS" - Show no progress window
"NODIALOG" - Show no confirmation dialog
"SILENT" - Show no error dialog if delete fails

Return value

0 for failure, 1 for success

Example

@var $options[] = {"NODIALOG", "SILENT", "RECYLE"};
DeleteFile( $filename, $options );

DeleteFiles

Delete multiple files using the Multi Commander virtual filesystem.

<num> DeleteFiles( <arr> filenames, <arr> options );

Parameters

filenames
array of files or folders to delete
options
Optional parameter (case-sensitive). Separate multiple options with commas.
"RECYLE" - Delete to recycle bin
"NOPROGRESS" - Show no progress window
"NODIALOG" - Show no confirmation dialog
"SILENT" - Show no error dialog if delete fails

Return value

0 for failure, 1 for success

Example

@var $filenames[] = {'e:\file1.txt', 'e:\file2.txt', 'e:\Folder1'};
@var $options[] = {"NODIALOG", "SILENT", "RECYLE"};
DeleteFile( $filenames, $options );

MakeDir

Create a new folder using the Multi Commanders virtual filesystem.

<num> MakeDir( <str> path, <str> options );

Parameters

filename
Full path to folder to create. Can also be any virtual path like WPD:\ REG:\ FTP:\ or inside zips or 7z
options
Optional parameter (case-sensitive). Separate multiple options with commas.
"LOCAL" - Hint to the virtual filesystem that the path is a normal local path
"RECURSIVE" - Create folders recursively. Only work if LOCAL also is specified

Return value

0 for success, else error code

Example

MakeDir( "C:\\Temp\NewFolder\\SubFolder\\", "LOCAL,RECURSIVE" );
MakeDir( "WPD:\\MyPhone\\SubFolder\\", "" );
MakeDir( "C:\\Temp\\MyFiles.zip\\Folder", "" );

FilterCreate

Create a handle to a filter. This handle will reference all filter rules added with FilterAddRule (see below).

<handle> FilterCreate();

Parameters

None

Return value

Return a handle to a filter

Example

@var $filter = FilterCreate();

FilterAddRule

Add a Rule to filter.

<str> FilterAddRule( <handle> filter, <str> matchType, <str> value, [<num> invert] );

Parameters

filter
Handle to a filter created by FilterCreate()
field to match
The field to do the match against:
fullname
ext
namepart
size
date
attribute
filecontent
extendedproperty
Match Type
The type of matching the rule should attempt.
is (if field is a text or number, eg. filename or size)
lessthan (if field is number, eg. size)
morethan (if field is number, eg. size)
wildcard (if field is of text type)
contains (if field is of text type)
beginwith (if field is of text typ )
endwith (if field is of text type)
before (if field is of date type)
after (if field is of date type)
has (if field is of attribute type)
hasnot (if field is of attribute type)
regex (if field is of text type)
hex (if field is of filecontent type)
Value
The value that the filter should match against
Invert
Optional parameter. If set to 1 the result will be inverted

Return value

1 if filter rule was added, else 0

Example

@var $filter = FilterCreate();
FilterAddRule( $filter, "Fullname", "Contains", "Frog" );
FilterAddRule( $filter, "ext", "Wildcard", "*.txt" );
FilterAddRule( $filter, "date", "before", "2016-05-01" );

FilterLoad

Load a filter from a file.

<handle> FilterLoad( <str> filename );

Parameters

filename
Full path to the file with a filter

Return value

Handle to a filter

Example

@var $filter = FilterLoad( "D:\\MyFilter.xml" );
@var $isMatch = IsFilterMatch( $filter, $file );

FilterLoadById

Load a filter from an existing advanced filter.

<handle> FilterLoadById( <str> FilterID );

Parameters

FilterID
GUID of a existing filter id

Return value

Handle to a filter

Example

@var $filter = FilterLoad( "3790d1abd9e849dba01de220375bb196" );
@var $isMatch = IsFilterMatch( $filter, $file );

FilterSave

Save a filter to a file.

<num> FilterSave( <str> filename );

Parameters

filename
Full file path to the file to save

Return value

1 if successful else 0

Example

@var $filter = FilterCreate();
FilterAddRule( $filter, "Fullname", "Contains", "Frog" );
FilterAddRule( $filter, "ext", "Wildcard", "*.txt" );
FilterAddRule( $filter, "date", "before", "2016-05-01" );

FilterSave( $filter, "C:\\MyFilter.xml" );

FilterIsMatch

Check if a file is a match against a filter.

<num> FilterSave( <handle> filter, <str> filepath );

Parameters

filter
Handle to a filter
filepath
Full path of a file to check the filter against

Return value

1 if file is a match, else 0

Example

@var $filter = FilterCreate();
FilterAddRule( $filter, "Fullname", "Contains", "Frog" );
FilterAddRule( $filter, "ext", "Wildcard", "*.txt" );
FilterAddRule( $filter, "date", "before", "2016-05-01" );

@var $isMatch = FilterIsMatch( $filter, "C:\\Temp\\MyFrog.txt" );

PathGetPathPart

Get the path part of a full filename path.

<str> PathGetPathPart( <str> path, [<num> stripEndingSlash] );

Parameters

path
Full file/folder path
stripEndingSlash
Optional parameter. If 1, then the trailing backslash of the path will be removed

Return value

The path part of a full file/folder path

Example

@var $path = PathGetPartPath( "C:\\temp\\MyPopSong.mp3" );
// res == "C:\\temp\\"

PathGetNamePart

Get the name path of a filename path.

<str> PathGetNamePart( <str> path, [<num> stripExtension] );

Parameters

path
Full file/folder path
stripExtension
Optional parameter. If 1, the file extension will be removed

Return value

The name part of a full file/folder path

Example

@var $nameA = PathGetPartPath( "C:\\temp\\MyPopSong.mp3" );
// nameA == "MyPopSong.mp3"
@var $nameB = PathGetPartPath( "C:\\temp\\MyPopSong.mp3", 1 );
// nameB == "MyPopSong"

PathGetFileExtPart

Get the file extension from a filename path.

<str> PathGetFileExtPart( <str> path, [<num> stripDot] );

Parameters

path
Full file/folder path
stripDot
Optional parameter. If 1, the dot in the file extension will be removed

Return value

The file extension of a filename path

Example

@var $nameA = PathGetFileExtPart( "C:\\temp\\MyPopSong.mp3" );
// nameA == ".mp3"
@var $nameB = PathGetFileExtPart( "C:\\temp\\MyPopSong.mp3", 1 );
// nameB == "mp3"

PathGetParts

Get an array of all the file path parts.

<arr> PathGetParts( <str> path );

Parameters

path
Full file/folder path

Return value

Return an array of all the filename part.
Array item 0 = Device
Array item 1 = Path
Array item 2 = Filename

Example

@var $arr = PathGetParts( "C:\\temp\\MyPopSong.mp3" );
// $arr[0] == C:\
// $arr[1] == C:\temp\
// $arr[2] == MyPopSong.mp3

PathMakeRelativeMC

Convert a path to be relative to where Multi Commander is started from.

<str> PathMakeRelativeMC( <str> path );

Parameters

path
Path to convert

Return value

The converted path

Example

// MC is installed in "C:\Program\MultiCommander"
@var $path = PathMakeRelativeMC( "C:\\temp\\MyFile.txt" );
// $path == "..\Temp\MyFile.txt"

PathMakeAbsoluteMC

Convert a relative path to absolute (relative to where Multi Commander is started from).

<str> PathMakeAbsoluteMC( <str> path );

Parameters

path
Path to convert

Return value

The converted path

Example

// MC is installed in "C:\Program\MultiCommander"
@var $path = PathMakeAbsoluteMC( "..\\temp\\MyFile.txt" );
// $path == "C:\Temp\MyFile.txt"

PathTranslatePath

Convert a relative path to absolute and also convert environmental tags.

<str> PathTranslatePath( <str> path );

Parameters

path
Path to convert

Return value

The converted path

Example

// MC in installed in "C:\Program\MultiCommander" and ENVVAR is "MyFile.txt"
@var $path = PathTranslatePath( "..\\temp\\%ENVVAR%" );
// $path == "C:\Temp\MyFile.txt"

@var $path = PathTranslatePath( "%WINDIR%\\calc.exe" );
// $path == "C:\Windows\calc.exe"

NetWGet

Download web content and save it as a file.

<str> NetWGet( <str> SaveAsPath,<str> Url, <str> options, <arr> Header );

Parameters

SaveAsPath
Full path to where the file should be saved
Url
URL of the web content to save
options
Optional parameter (case-sensitive). Separate multiple options with commas.
OVERWRITE - Overwrite target file if it already exists
VERIFY_SSLCERT - Require valid SSL Certificate
Headers
An array of "Key=Value" strings that should be added to the Http Request header

Return value

Number of bytes downloaded and written to the file SaveAsPath

Example

@var $bw = NetWGet( "C:\\Temp\\MFile.zip", "http://www.example.com/file.zip", "OVERWRITE,VERIFY_SSLCERT" );