Allows you to restore and apply filter settings saved by the corresponding SaveFilter. The process is very similar to running the FILTER command in a macro in the sense that it just applies the filter settings to your current database, and if zero records match then the filter is cleared. $_FilterCount is still updated, but because this function also returns the number of records returned by running the restore you can use it instead of $_FilterCount. For example:
If RestoreFilter($SavedFilter,True) = 0
Pause Msg="No records match your restored filter. Filter has been cancelled"
EndIf
Notice the RestoreFilter has a second boolean token bSearch. This token will enable you to also apply any name or code searches that were currently in place when the filter was saved. So, to fully restore the exact subset criteria, this token should always be set to True. However, there may be times when you only want to restore the underlying filter and not have the search boxes applied.
Just like setting any filter, also be aware that using the RestoreFilter function will not necessarily give you the same subset of records as when the corresponding filter was saved. This is because any number of records could have changed from the time you did the save until the time you do the restore.
You are not limited to saving filters to the same variable. You can save filters to different variables, then restore them at different places in a macro. You may even want to save the variable to a file and then later restore by reading from that file (the format of the saved information is just plain text)