Debugging adapls for Axiell Collections
Contents
From Collections 1.7.19249.1, executed adapls that have been compiled in debug mode (with the -d command-line argument), leave a log file with an execution trace in the \adapls folder, for post-execution debugging. This is the most comprehensive way to debug any adapl executed by Axiell Collections.
So all that’s required is that the relevant adapl has been compiled in debug mode, either in Axiell Designer or from a DOS command-line. Once the adapl has been executed, e.g. after a record has been saved or after the relevant task has been executed, an XML with the logged data will have been created in the \adapls folder (the folder holding the .bin file of the adapl actually) of the application. The name of this file is a concatenation of the adapl file name (including extension, e.g. thesaustor.bin), the translated execution code of the adapl (taken from the &1 reserved variable, e.g. BeforeEdit) and the date and time of execution (e.g. 2019_09_09__11_38_44).
You can open the file in any text editor (Notepad++ for example) or Visual Studio. For each executed line of code – commented out lines and empty lines are skipped – the XML file contains a <snapshot> node with all data that could possibly be relevant to debugging:
| • | the current line number (which has not yet been executed yet) and the associated line of code; |
| • | the content of the currently processed record (in the adlib_lite FACS buffer) and the contents of all other currently opened FACS records, before the current line of code was executed; |
| • | per field, its field tag, the occurrence number, any data language and the data itself: note that some characters in the data might have been XML escaped, like > for the > character for example; |
| • | a list of reserved variables (like &1, &I, &E etc.) and their values, before the current line of code was executed. For example &E, occurrence 1 with data NoError would equal &E = 0. |
| • | a list of declared variables (text, integer and numeric types) and their values, before the current line of code was executed. |
The log file can become quite large (up to a few MB per record), so we recommend making sure that the adapl is executed for just one or two records only. That is usually enough for debugging. A good way to use the file is to search on the line number where you expect things might go wrong. Or search repeatedly on a tag or variable name to find out in which line of code it changes to an unexpected value.
The execution trace isn’t perfect though: normally, with multiple consecutive assignments, the assigned values appear in the log only with a delay of one or more lines of code. The only way to prevent that from happening is to end each line of code (at least the lines that you’d like to examine) with a semi-colon.
After debugging, remember to recompile your adapl without the -d argument.
Alternative methods
Instead of the above and without having to compile the adapl in debug mode, you can also temporarily just add strategically placed errorm statements in the adapl, displaying the current value of some variables that you are interested in.
Or you can have the adapl write values of the variables that you are interested in to some unused Notes field in a record and check those records later. Of course you can only do this in a test environment with test data.
After debugging, remember to delete the extra errorm's or field assignments and recompile your adapl without the -d argument.