The "xzip_report" Data Structure

Description

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:

Monitored Functions

  • xzip_add
  • xzip_delete
  • xzip_extract
  • xzip_move
  • xzip_set_readonly

These functions will return true or 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.

note

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 ds_list with ds_list_copy. Assigning 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.

Example

if (xzip_delete("C:\\archive.xz", "file1.txt", "file2.jpg") == false) {
if (ds_list_find_value(xzip_report, 0) == "archive.xz") {
//Archive not found
}
}

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.