Using the ADAPL Debugger: status information
Contents
On the three screen tabs in the right window pane of the ADAPL Debugger, you'll find all status information relevant to debugging. The status information always pertains to the current state of all variables up to the line where execution is paused. It is important to note that the line at which execution is paused, has not been executed yet. Ideally, it should be executed after leaving the line. Unfortunately, the relationship between the selected line of code and the actual line in the compiled code is somewhat fuzzy. The ADAPL Debugger does not interpret the code it presents, it relies completely on line numbers generated by the ADAPL compiler. However, this compiler has an irregular dependence on new-line characters to determine what to compile, making line numbers not as accurate as they should be for this particular purpose. It means that the results of the execution of a certain line of code will often only become present in the status information in the ADAPL Debugger two lines beneath the relevant line in the displayed file.
So, a simple assignment like i = 1 will only become visible in the status information, two lines after the assignment. This may of course be inconvenient during debugging. However, there is a workaround: once you know which lines of code need to be analysed further, edit them by either entering a semicolon at the end of those lines or by inserting two empty lines in between the relevant lines of code. By using the semicolon, the status information will be updated right after leaving the paused line. By using the empty lines, the status information will usually still be updated after stepping into the second empty line after the paused line, but since no other code is executed in the empty lines, you'll be able to observe exactly what line of code causes trouble.
Local variables
On the Variables tab you'll find an overview of all local variables declared in the adapl, with their data type and their current value. Click the + icon left of an item in the list, to display its sub-items.
Use this tab to check if values are always of the correct data type, and if variables used as counters for loops and such, contain the correct value at the various stages during adapl execution. Often occurring bugs include:
| • | the intended use of a value from a variable when no value has been assigned to it yet. Make it a habit to initialize variables after declaring them; |
| • | forgetting to increment counters in loops, or incrementing them at the wrong moment; |
| • | incorrect calculation of values; |
| • | forgetting to convert number values retrieved from tags, which are actually text values, to integer or numerical values. For counting and other calculations, you cannot use a number which is actually a string; |
| • | forgetting to convert a numerical to an integer. Some ADAPL functions result in a numerical value, some in an integer. Integers can be always be added to numericals or entered in a numerical variable, though; |
| • | forgetting to convert the retrieved value of an enumerative field to its default (language-independent) value. |
Reserved variables
On the Ampersands tab, you'll find an overview of all reserved, system variables. These are undeclared variables in which Adlib automatically keeps track of system processes, for example: &E contains the result code of FACS operations, indicating if a READ or WRITE action has been successful or not. The Axiell Designer Help has a complete overview of all reserved variables and their use. You can find this topic underneath Using ADAPL > Programming ADAPL > Variables.
Use this tab to check result codes and other system codes if conditional code is executed while it shouldn't, or the other way around. System variables are often used to control the execution path of ADAPL code. Often occurring bugs include:
| • | FACS READ statements not finding the correct record, because the wrong index or the wrong search key is used; |
| • | records locks are not handled correctly; |
| • | the adapl, or code in it, is executed at other moments than intended, for example because the &1 and &1[2] execution codes generated by Adlib are different from what you expected. |
Note that &H will only display up to ten command-line arguments, even though an unlimited number of arguments is supported by adeval.exe when running an adapl that way.
Database variables
On the Records tab you'll find all currently loaded database variables (tags). If the currently executed adapl is executed from within a record in detailed display mode, then _LOCAL will contain all filled in tags of that record. Other records you'll find in this overview, are denoted by the name of the FACS database from which they have been retrieved: such a record will appear when you READ or WRITE a record from and to a FACS database. You'll see the tag (repeated for all its occurrences, and possibly also repeated for all languages in which data may have been entered), its field name, and the data in it. Of data which consists of multiple lines of text (separated by line feeds: chr$(13) + chr$(10)), currently only the first line will be displayed in the relevant Data cell.
Often occurring bugs include:
| • | addressing the wrong occurrence of a field, especially when filling multiple occurrences of multiple fields in a loop. The first occurrence is indicated by 1, not 0; |
| • | assigning dates in the wrong date format; |
| • | handling of linked field values instead of their link references. |
