|
Scripting can have a large impact on performance. Try to reduce the number of search results before the script is called, e.g. search only one drive, exclude folders, use a filename filter, etc. |
This section of the help file provides information about scripting support. Scripting allows for advanced filtering. A script is a set of instructions and is similar to the macro support in Microsoft Office, Java Script in web pages and plug-ins in other software. FindOnClick uses scripts written in Pascal and is the same syntax as in SyncBackPro.
The scripting feature let's you decide to include a file or folder if it has passed the existing search filters. For example, if your search filter specifies that only empty files are listed, then the script will only be called for -empty files. Non-empty files are filtered out before reaching the script.
Some example scripts are installed along with FindOnClick. See the Scripts sub-folder in the settings folder.
Script functions are called in this order (and all are optional, i.e they don't need to be defined in the script):
•BeginScript is called before each drive and/or path search. This means it may be called multiple times.
oInclude is called for each item found that has not already been filtered out by the search settings. So BeginScript is called before a drive/path is searched, it is then searched, and Include is then called for each item found, and not filtered out, on the drive/path.
•Once all the drives/paths have been searched and filtered, FindOnClick does post-processing. Post-processing is done after a list of files has been filtered and produced. Post-processing is when hash values are calculated and file contents are searched. As these are resource intensive they are only done once we have filtered out as many files as possible.
•Once file contents have been searched, and hashes calculated, PostIncludeEx is called. This lets the script tell FindOnClick which files to include based on their filename. This is done by giving a TFileList containing the filenames.
•If DoPostFiltering is defined, and returns TRUE, then PostInclude is called for each item that has not already been filtered, e.g. via PostIncludeEx, the search settings may be set to only include duplicate files, etc.
•EndScript is called once post-processing has completed and we now have the final list of files that is displayed to the user. It is only called once.
function Include(fname, DOSfname, fsize, fattrs, fcreate, faccess, fmod, fstreams, fhash, fver);
fname: Full filename, including drive and path.
DOSfname: DOS filename (empty if Windows search not being used)
fsize: File size (bytes)
fattrs: File attributes, e.g. FILE_ATTRIBUTE_DIRECTORY
fcreate: Creation date & time (local timezone)
faccess: Last access date & time, if supported and enabled on file system (local timezone)
fmod: Last modification date & time (local timezone)
fstreams: Number of streams (if it's a slow search then this will probably be zero)
fhash: Hash value (if calculating). This will probably be empty as it is not calculated until post-processing.
fver: File version (if displaying and applicable to file type), e.g. 5.4.3.2
Return value: Returns TRUE if the file/folder should be included in the search results, i.e. it is not filtered out.
The function Include is called for each file and/or folder that has not already been filtered out by the other search settings, e.g. the file is large enough, modified on the required dates, etc. It is called before any hashing or file contents searching, as that is a post-filtering process. See PostIncludeEx and PostInclude for post-processing.
function PostIncludeEx(var FileList);
FileList: Must be a TFileList object and the TFileList.Type (set when the object is created) must be EFLT_FullPath or EFLT_JustFilenames.
Return value: If FileList has been set to a TFileList object in the script, then return TRUE. Otherwise return FALSE so FileList will be ignored.
This function can be used to tell FindOnClick which files and/or folders to include by providing a list of them. If this function returns TRUE then FindOnClick will remove any item from the search results that doesn't match the filenames in the list.
It is considerably faster to use this function instead of PostInclude. This is because FindOnClick just needs to make one call to the script instead of a call for each file & folder in the search results.
function DoPostFiltering;
Return value: If you want PostInclude to be called then this function should return TRUE. If this function is not defined in your script then the result is assumed to be FALSE, i.e. PostInclude will not be called. Note that PostIncludeEx is not affected by this result and will always be called (if it has been included in the script).
function PostInclude(fname, DOSfname, fsize, fattrs, fcreate, faccess, fmod, fstreams, fhash, fver);
fname: Full filename, including drive and path.
DOSfname: DOS filename (empty if Windows search not being used)
fsize: File size (bytes)
fattrs: File attributes, e.g. FILE_ATTRIBUTE_DIRECTORY
fcreate: Creation date & time (local timezone)
faccess: Last access date & time, if supported and enabled on file system (local timezone)
fmod: Last modification date & time (local timezone)
fstreams: Number of streams (if it's a slow search then this will probably be zero)
fhash: Hash value (if calculating)
fver: File version (if displaying and applicable to file type), e.g. 5.4.3.2
Return value: Returns TRUE if the file/folder should be included in the search results, i.e. it is not filtered out.
PostInclude is only called if DoPostFiltering returns TRUE. The function PostInclude is called for each file and/or folder that has not already been filtered out by the other search settings or the Include script function. PostInclude is called after hashing and file contents are searched and after PostIncludeEx.
procedure SearchBegin(SearchPath, IsSlowSearch);
SearchPath: The path/drive being search, e.g. C:\
IsSlowSearch: TRUE if standard Windows searching is being used for this path. You can also retrieve this value using SS_SlowSearch
The procedure SearchBegin is called before the search starts for a path/drive. If multiple drives/paths are being searched then this will be called multiple times.
This procedure is useful for creating resources before the search begins. Those resources can be freed in SearchEnd.
procedure SearchEnd;
The procedure SearchEnd is called when the search ends for ALL paths/drives. This means it will only be called once, unlike SearchBegin. This procedure gives you a chance to clean-up and free any resources that were created.
<%SBCOPYRIGHT%>