This section provides techniques that can be used to troubleshoot agents. As you know, agents can be written to utilize "Simple Actions," Formula Language, LotusScript, and a variety of other languages. Given this variety, numerous tools and approaches can be used to debug problems. The tools used to debug the agent will, in part, depend on the design and implementation of the agent. The following outlines approaches that will be covered:
Review the agent log
Use the Debugger for LotusScript agents
Incorporate message prompts
Monitor the Domino Server Log (requires special access)
Monitor the Domino Server Console (requires special access)
As with most application development, youll find theres no substitute for experience, and as you gain experience, youll find one technique to be preferred over others. Youll also find there is no easy method to troubleshoot agents that utilize "Simple Actions" or Formula Language.
The Domino Designer client includes a feature to test the agent. When utilized, the client performs a trial run of the agent and displays the Agent Log. The Agent Log is usually a good place to start when looking to test or troubleshoot an agent. The Agent Log contains information pertaining to the agent execution and can often help to diagnose common agent problems.
The Agent Log is produced by testing the agent. This is accomplished by selecting the agent in the Domino Designer client and choosing the Agent > Test menu options. The software subsequently returns the expected results along with potential errors in a dialog. Figure 21.7 illustrates a sample Agent Log.
In this example, statement 2 indicates that this is a scheduled agent that has been signed by "Mark Elliott". Statement 4 shows the agent name "Archive" and a timestamp when the trial run started. This is followed by the total number of documents as well as the number of documents affected by the agent. The log ends with a completion time for the agent test.
The Agent Log can only be displayed for specific types of agents. For instance, agents that are developed to parse or utilize the user interface cannot utilize the "Agent Test" function. In this scenario, the Designer client will display an error message as illustrated in Figure 21.8. If you encounter this message, consider running the LotusScript Debugger and tracing the agent as it is executed in the database from the Lotus Notes client.
For agents that utilize LotusScript, the debugger can be used to trace the code and review object values as the agent executes. As described earlier in the chapter, the debugger can step through the agent execution, halt execution, and display detailed information pertaining to all LotusScript objects. Unfortunately, this feature only applies to LotusScript. There is no comparable function that can be used to trace agents that are written in "Simple Actions" or Formula Language.
Message prompts can be used to display data values or status points in the execution of the agent from the user interface. This approach can be used for manually triggered agents. Using Formula Language commands (such as @Prompt) or LotusScript commands (like Print, Messagebox, and Prompt), you can periodically display information in the Lotus Notes client. The resulting information can sometimes identify problems with the agent.
Other avenues include the LotusScript NotesLog class, which can be incorporated into agents that utilize LotusScript. This class offers methods to log actions, events, and errors and determine agent properties including the number of errors, program name, total actions, and parent object name. Refer to the Domino Designer help for additional information pertaining to this class.
The Domino server log contains a running history of events and informational text messages associated with the servers operation. This database resides on the server and is updated as events occur. It also tracks messages issued by the LotusScript print statement for all agents run by the server. Its important to understand that this a restricted database. Based on the default ACL settings, you probably will not have access to this database. Consult your Domino server administrator to request "Read" access to the database.
After you have appropriate access, select the File > Database > Open menu options to open the server. Specify the Domino server name in the Server field and locate the database. The database will most likely be named "Server Log" (where "Server" represents the actual name of the Domino server). The log database contains a wide variety of information associated with the Domino servers operation. For debugging purposes, select the Miscellaneous Events view. The most current document containing server log information will be located at the bottom of the view (see Figure 21.9). Open this document and review the statements for potential clues to help diagnose the problem.
The Domino Server Console displays information pertaining to the operation of the server. This can include informational messages during agent execution, similar to those appended to the servers log file. Additionally, you can issue a variety of the commands to retrieve status information for a given agent. However, to run these commands, you must have access to the servers console window or the authority to establish a remote console connection using the Domino Administrator client. For many, these options will not be feasible. A summary of server commands has been included for those who manage both database development and server administration.
An Introduction to the Lotus Domino Tool Suite
Getting Started with Designer
Navigating the Domino Designer Workspace
Domino Design Elements
An Introduction to Formula Language
An Introduction to LotusScript
Fundamentals of a Notes Application
Reference Library Applications
Design Enhancements Using LotusScript
Design Enhancements Using Formula Language
Miscellaneous Enhancements and Tips for Domino Databases
Application Deployment and Maintenance
Appendix A. Online Project Files and Sample Applications
Appendix B. IBM® Lotus® Notes® and Domino®Whats Next?
Lotus Notes Developers Toolbox: Tips for Rapid and Successful Deployment
Authors: Mark Elliott
Similar book on Amazon
XPages Portable Command Guide: A Compact Resource to XPages Application Development and the XSP Language