Testing and Debugging Agents, the Agent Log, and Agent Properties

Just as you can test views and forms, you can test agents by highlighting the agent in the Agent folder and then choosing Actions, Test from the menu. Figure 11.19 shows the menu. This agent doesn't actually perform any actions; it merely selects the documents. The Agent Log window reports on statistics such as the number of documents meeting the criteria, the number of documents modified, and start and stop times.

Figure 11.19. Testing agents is done from the Actions menu.

The results of a test run of an agent to select documents based on a condition show that the agent ran with no problems (see Figure 11.20).

Figure 11.20. Logging agents can done from the Actions menu.

The log is also available from the Agent menu that appears when you are in the Agent folder. From this menu, there are two options: Agent Properties and Log. Choosing Log presents the Agent Log window containing statistics for the last time the agent ran. If the agent has never run before, a Prompt window appears stating that fact.

Debugging Agents on the Server

This feature is new to Domino 6 and allows a designer to debug an agent at the server. To use this feature, you must turn on the Remote Debugging feature in the agent by placing a check mark in the box provided on the Security tab of the Agent InfoBox. Debugging must also be enabled on the server by engaging the following settings:

• Add Rdebug to the ServerTasks= line in the server's notes.ini file, as in ServerTasks=Replica,Router,Rdebug,Update... .
• Enter load rdebug at the server console or restart the server.
• On the Basics tab of the Server document, change the Remote Debug Manager task setting to Enabled. Note: You must have administrative access to the server to edit this field.
• From the Server Tasks tab of the Server document, select the far-right tab entitled Remote Debug Manager. Enter a time limit for running the rdebug task on the server in the Turnoff Server Debug After setting. Note: If you set this value to -1 , the task will run forever.
• Enter a time interval in the Agent Wait at Start Time field if you want to force the agent to pause before running, giving you time to attach the remote debugger to the target agent.
• Make sure you are listed on the server's Security tab as having permission to run agents.

To run and debug a specific agent, you can either increase the run frequency of the agent by clicking the Schedule button on the Basics tab of the Agent properties box or, in the Agent Schedule dialog box, change the hour value of Run Agent Every to 0 and change the minutes value to five or less.

Engaging the Remote Debugger

Enter the following command on the server console:

tell amgr run yourpathdatabasename.nsf 'agentName'

While the agent being debugged is running on the server, select File, Tools, Remote Debugger from the menu, as shown in Figure 11.21.

Figure 11.21. Accessing the Domino Debugger.

The Domino Debugger 6 welcome page opens. Select File, Select Debug Target from the menu. The Select Debug Target dialog box displays, as shown in Figure 11.22.

Figure 11.22. The Domino Debugger. Choose the server that is running the agent from the Server list box, and click Open .

A list of the databases on the server displays. Select the database that contains the agent, and click Open.

If the agent that you want to debug is currently running, it will appear in the Debug Target box. If not, select the agent that you want to debug from the Debug Target list and click Open.

The Script Debugger window opens, displaying the (Options) event of the current agent. You are now able to debug your agent.