xzip_report is not a function, but rather a macro for a built-in
ds_list that tracks errors in Xzip functions which work with multiple files simultaneously. This includes:
These functions will return
false to indicate whether all file operations completed successfully. In the event of errors, any problematic file names will be recorded in
xzip_report, as it is otherwise difficult to tell which files caused the errors to occur.
Any time a monitored function returns
false, it is a good idea to parse
xzip_report to take appropriate action in response. This is helpful not just in debugging, but also for handling errors gracefully in compiled applications.
For simplicity, only file names are recorded, not file paths. Paths for each file are already known by virtue of the fact they were input as arguments to a script; using file names only makes
xzip_report easier to parse.
Keep in mind that
xzip_report is refreshed each time a new monitored function is run. To store the contents of a report for future usage, it should be copied to a secondary
xzip_report to another variable with
= will not work. However, this kind of assignment will allow using
ds_list accessors, which are incompatible with the
xzip_report macro itself.
This will check if an error occurs during a file deletion process, and if so, the first entry in
xzip_report will be queried to determine if the archive itself is the problem.