Internal: Error-Checking In iTools For Advanced IDL Developers [IDL 6.0]
Help Article Update 2
Anonym
Topic:
RSI is always trying to improve its error-catching and reporting routines. If you encounter a message in our first generation of iTools, which does not help you identify the source of the problem, you should submit to support@ittvis.com:
- a description of your scenario - with enough detail, so we can reproduce,
- the text of the error message in the IDL output log (or a screenshot of the error message box), and/or
- a picture of the faulty results as they are displayed by the iTool.
In the meantime, the experienced IDL developer might be able to track down the source of the problem by following one or both of the 2 troubleshooting approaches outlined in the Discussion below. The first approach gives you a view of all the most recent actions that iTools performed leading up to your error. The second approach helps developers produce a "stack trace" in their error output, whenever any error is triggered. It is a solution that can be turned on fairly quickly, and it is equally easy to turn off this error-reporting modification once a specific error scenario has been analyzed.
NOTE: The routines for error-checking evolved after IDL's first iTools version, so that some of the steps in this Tech Tip no longer apply to IDL versions 6.1 or later. Please consult the iTools documentation for current debugging recommendations.Discussion:
Approach 1: The iTools Log Files
iTools stores a history of all its recent actions in a subdirectory path below the current IDL user's home directory. (Note that on Windows, the "home directory" is typically defined as C:\Documents and Settings\[your user name]\.) The subdirectory path from there to iTools' log files is .idl\idl_6_0_[O.S. acronym]\itools\. Here, for example, is a typical complete Linux path: /home/janedoe/.idl/idl_6_0_linux_x86_m32_f64/itools/.
Inside this directory, the user may find up to 5 log files. The most recent log entries are in the file named 'itools_log.txt', and that is presumably the only file you would need to identify actions leading up to your most recent error. The other files, ones with numerical extensions like 'itools_log.0', 'itools_log.1', etc., store chronologically the output that has already flowed through 'itools_log.txt', with the more recent output in the files with lower-numbered extensions.
The log files are persistent storage for the messages that are also output on the 'Message Log' utility accessed through the 'Window->Console' menu on any iTool visualization. See iTool Common Tasks->Additional Operations->Recording a Message Log in 'itooluserguide.pdf' for more details on that menu item. The log files could potentially offer some extra final feedback unavailable on the Console when an action has crashed or frozen an iTool visualization. If you have difficulty interpreting the output in that log, you might still submit a copy of the critical output lines with your bug report to RSI's Technical Support (support@ittvis.com).
Approach 2: Forcing iTools To Produce A Stack Trace Of The Error Output
iTools are implemented solely in the IDL language, and their complete source code is available for modification in every distribution of full developer IDL. Furthermore, the modifications a customer makes execute automatically after any IDL session restart or reset. (Alternatively, users can avoid resetting IDL by .compile-ing the file(s) they modify during their current session.)
IDL's error-catching behavior is controlled very compactly by the file .../lib/itools/idlit_catch.pro. Here is practically the entire contents of that file:
;; Use:
;; To control the catch settings, just uncomment, comment the
;; below lines.
;;
;; Include file to turn on and off catch throughout the system.
;; Uncomment to turn on catch, comment to turn off
catch, iErr
;; Uncomment to turn off catch, comment to turn on
; iErr = 0
Let us explain the role of this file. The statement "@idlit_catch.pro" appears throughout the iTools source code files right before most, if not all, "catch, /cancel" statements. The "catch loops" in each local source code file are designed to catch and troubleshoot in a precise context the errors that occur near that catch statement. If a developer finds that that error handling is possibly misinterpreting its local "context", then that developer might be better off with a more general stack trace of all the IDL calls that led up to that error. That is what following the instructions in the file will accomplish.
By commenting the statement "catch, iErr" the user forces IDL's default error handler to become the error handler for the whole iTools system. That insures the output of a lengthy stack trace after every fatal error (every one that stays within IDL, that is). To complete the turn-off of the local error handler, the developer also has to turn on (through uncommenting) the statement "iErr = 0"; that is what will prevent IDL from entering the local error handler code block.
After you have finished your troubleshooting, you will want to undo the commenting modifications you made in this file. Otherwise, you lose access to the more sophisticated default iTools error handling.
Finally, we leave here a reminder to report to us any weaknesses you find in iTools error-handling. Your comments, with details as discussed in the Topic: section above, should be sent to support@ittvis.com. Thanks in advance for all feedback you provide.Solution:
[Edit this field in the IDL-based Tech Tip Editor, v62]