Using the Remote Debugger

About this task

You can use the remote debugger to step through and debug LotusScript agents running on the server. The agent you want to debug must be running at the time that you start the remote debugging tool.

More than one user can attach to and debug the same agent. However, only one user has control to debug it at any given time. A second user may get control by attaching to the same agent. This capability is useful, for instance, if you want help from a coworker in debugging an agent. You can ask the coworker to attach to and debug the server agent and that coworker can do so without having to be in the same physical location as you. Note that if you attempt to continue debugging the server agent after your coworker has attached to and begun to debug it, you will get the error, "Another user has attached to the agent and taken control. Please try to reconnect for further debugging."

Complete these steps before using the remote debugger:

Procedure

Enable remote debugging on the server.
Enable remote debugging in the agent.
Start the remote debugger.

Results

"To debug a scheduled LotusScript agent remotely" defines how to use the remote debugger once the server and agent are set up to allow for remote debugging.

Note: Remote debugging is new with Release 6.

To enable remote debugging on the server

Procedure

Before starting the server, in the server's notes.ini file, add the following value to the ServerTasks= list:
```
Rdebug
```
If the server is already running, to begin the remote debugging task enter the following at the server console:
```
load rdebug
```
From the Server Tasks tab of the server document, select the tab entitled Remote Debug Manager. Set Allow remote debugging on this server to "Enabled."

Tip: You must have administrative access to the server to edit this field.
Enter a time limit for running the rdebug task on the server in the Turnoff Server Debug after setting.

Tip: If you set this value to -1, the task can 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. (Recommended.)
Check the Ports - Internet Ports - Remote Debug Manager tab, to ensure that the TCP/IP port status property is set to "Enabled."
Make sure you are listed on the server's Security tab as having permission to run agents.
Save and Close the server document.

To enable remote debugging in the agent

Procedure

On the Basics tab of the Agent Properties box, select the On schedule Trigger radio button. Click Schedule.

The Agent Schedule dialog box displays.
Select the server from the "Run on" list box.
Add a Stop statement to the beginning of the Initialize event code in the agent. The Stop statement works as follows:
- If the remote debugger task is not running on the server or if it is not enabled, this statement does nothing. Performance of the agent is not affected.
- If the remote debugger is running and enabled, it pauses the execution of the agent code for the time specified in the "Agent Wait at Start Time" field if you specified one in the Server Tasks tab - Remote Debug Manager tab of the server document. This gives you time to attach to the agent in the Remote Debugger window before it begins executing.
- If the Remote Debugger window is open and you have attached to the agent, the Stop statement acts like a break point and stops execution.
  Tip: You can also add the following statement to the start of the agent code to broadcast to the console that the agent is preparing to run.
```
Print "AgentName is about to start running****************"
```
On the Security tab of the Agent Properties box, select Allow remote debugging.

To start the Remote Debugger

Procedure

To run a specific agent you want to debug, either:
- Increase the run frequency of the agent by clicking the Schedule button on the Basics tab of the Agent Properties box. In the Agent Schedule dialog box, change the hour value of "Run agent every" to zero and the minutes value to 5.
- Enter the following command on the server console:
```
tell amgr run databaseName.nsf 'agentName'
```
While the agent you want to debug is running on the server, select File - Tools - Remote Debugger from the menu.

Tip: You know an agent is running if you added print and stop statements at the beginning of its Initialize event. The print statement cause the agent to print to the console when it is starting and the stop statement delays its execution.

The Domino Debugger 6 welcome page opens.
Select File - Select Debug Target from the menu.

The Select Debug Target dialog box displays.
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 you want to debug is currently running, it appears in the Debug Target box.
Select the agent you want to debug from the Debug Target list and click Open.

The Script Debugger window opens, displaying the (Options) event.

To debug a scheduled LotusScript agent remotely

Procedure

To display the agent code you want to debug in the Script pane, select the agent or script library name from the Object list box and the name of the event that triggers it or the subroutine from the Event list box on the Debug pane.

The code displays in the Script pane. If the script has already begun executing, a yellow arrow points to the line of code that is the next to be executed.

Select the mode with which you want to debug the code using one of the following action buttons:

Note: To set a breakpoint, highlight the line you want to break before executing and choose File - Set/Clear Breakpoint or F9.


Action Button	Description
Break	Breaks execution of the agent code on whichever line is currently executing, including lines within loops. Does not close the debugger. You can click Continue to resume execution.
Continue	Runs the code in the Script pane and stops only when it encounters a breakpoint. Otherwise, runs until the agent code is complete.
Step Exit	If the debugger is executing code within a subprogram, exits the subprogram and returns to the statement that called it. If no statement in the current agent code called the subprogram, continues executing until it reaches the next breakpoint or the end of the agent code.
Step Into	Steps through the code one line at a time and drops into subroutines or functions. Note: Use this button repeatedly to step through each line of the script one line at a time.
Step Over	Steps through the code one line at a time and does not drop into subroutines or functions, though the sub or function code is executed.
Stop	Disconnects the remote debugging server task; the agent code stops executing.

As the code executes, the debugging results display in the Utility pane. The Utility pane contains the following tabbed sections:


Tab	Description
Breakpoints	Lists the locations of breakpoints you have added to the code.
Calls	Identifies what is currently being executed in the agent and displays all subprograms currently on the execution stack. For example, folderDocs:INITIALIZE 5 indicates that the fifth line of the Initialize event in the folderDocs agent is the next line to execute.
Output	Displays the server console output. Any print statements in the code or error messages appear here.
Variables	Lists the variables created and their values as values are applied to them in the code. You can use the edit box at the end of the pane to change the value of the selected variable.