Delete Files or Directories Functions
The following functions allow deleting a file or a directory in a predefined folder. The file system location allowed to delete files or directories is the folder shared\scripting of the current project (for example, [Installation Drive]:\[Installation Folder]\[Project Name]\shared\scripting). Such functions can be run synchronously or asynchronously, and in the last case, it is necessary to provide a callback method that will be executed when the delete operation is completed.
fileRemoveSync
The fileRemoveSync function allows deleting the file or folder specified by <relativePath> in the predefined folder. If a folder is addressed, the parameter <recursive> allows specifying whether each file and directory contained in <relativePath> must be deleted recursively.
fileRemove
The fileRemove function allows deleting asynchronously the file or folder specified by <relativePath> in the predefined folder. If a folder is addressed, the parameter <recursive> allows specifying to delete recursively every file and directory contained in <relativePath>.
Then it calls the <callback> with the operation result.
Syntax
(Synchronous remove)
var result = fileRemoveSync(<relativePath>, <recursive>)
(Asynchronous remove. The result is provided in the callback method.)
fileRemove(<relativePath>, <callback>, <recursive>)
Parameters Usage
Parameter | Type | Default | Use | Annotation |
relativePath | String | - | Mandatory | Relative path of the file or directory to delete in the shared\scripting folder of the current project. |
callback | Function | - | Mandatory for asynchronous calls | Object that identifies the callback function invoked to provide the result of the operation. |
recursive | Boolean | False | Optional | This parameter is meaningful only when deleting folders:
|
The callback function is declared as follows:
function fileRemoveCallback(<FileRemoveResult>)
{
//... Do callback stuff here ...
}
Where <FileRemoveResult> is the result object.
If <recursive> is False and the directory is not empty, the operation fails. If <relativePath> specifies a file, this parameter is ignored.
Result
The functions fileRemoveSync and fileRemoveCallback return the FileRemoveResult object.
Error Handling
Errors can occur in case:
- The specified
<relativePath>: - Is missing, null, empty or white space
- Is not a string
- Is invalid (such as, path containing a root directory, wrong absolute path, path outside of the predefined folder, path or file name containing invalid characters, files or directories that have too long path). Note that invalid characters and the path length depend on the operating system.
- Represents the predefined folder: The error message can be:
'Unable to delete the predefined folder.' - Represents a read-only file: The error message can be: '
Access to the path [Installation Drive]:\[Installation Folder]\[Project Name]\shared\scripting\readonlyFile.txt is denied.' - Represents a folder that contains a read-only file. The error message can be:
'The directory '[Installation Drive]:\[Installation Folder]\[Project Name]\shared\scripting\MyFolder' contains a read only file.' - Does not exist. The error message can be:
'File '[Installation Drive]:\[Installation Folder]\[Project Name]\shared\scripting\xyz.txt not found.' <recursive>is invalid. For example, the error message can be:'The value of the Recursive flag is not valid.'
- The callback is missing, invalid, null, or empty (for asynchronous function only).
- The related error is logged only in the Trace Viewer.
Examples of Use
How to delete an existing file
var result = fileRemoveSync("MyFolder\MyFile.txt")
console("Error = '{0}'", result.error)
If "MyFile.txt" exists, the code in the example prints to the Console expander the following:
Error = ''
and deletes the specified file.
How to delete an existing folder, only if it is empty
var result = fileRemoveSync("MyFolder")
console("Error = '{0}'", result.error)
If "MyFolder" contains one or multiple files or directories, since the parameter <Recursive> is False by default, the code in the example does not delete "MyFolder" and prints to the Console expander the following:
Error = 'The directory '[Installation Drive]:\[Installation Folder]\[Project Name]\shared\scripting\MyFolder' is not empty.'
If "MyFolder" is empty, it is deleted without errors while the Console expander contains:
Error = ''
How to delete an existing folder, regardless of whether it is empty
The code in the following example deletes “MyFolder”, its subdirectories, and any files:
var result = fileRemoveSync("MyFolder", true)