INVOKING THE DEBUGGER

To connect to the debugger, the application needs to know the host machine name and the port the debugger is running on. This information can be obtained in a number of ways such as by preferences settings for the application user. However, when an application is started by the debugger, it is always given a command-line switch to tell it this information. The switch is of the form:

/debug=<host>:<port>

The application should extract and use the provided host and port if this switch is passed to it. In addition, it should immediately connect to the debugger and execute the script passed on its command-line, as previously described. If there is no such switch, the application can debug at any time by connecting to an arbitrary debugger on any machine. The usual port for a ScriptEase debugger is SEDBG_STANDARD_PORT.

In any case, once the application has the host and port, it connects to the debugger using the following ScriptEase debug API call. The password is optional, needed if you want the debugger’s user to provide this password before debugging your application. Use NULL if you don’t want a password. The application_id is arbitrary text to identify your application.

   sebool

seDbgConnect(secontext se,

             seconstcharptr host,

             uint port,

             seconstcharptr application_id,

             seconstcharptr password);

The result is a boolean indicating success. If it is FALSE, then the debugging connection could not be established. To determine the reason for the failure, use this ScriptEase Debug API call:

   seconstcharptr

seDbgLastError(secontext se);

If a connection cannot be established, a text explanation of the failure can be retrieved using this call.

Once the debug session is begun, is must be terminated with this call:

   void

seDbgStop(secontext se);

Normally this call is used when the script finishes executing. However, it can be used while the script is executing to terminate debugging of the script. The script will continue as normal as this call only stops the debugger control of the application.

Between connecting and stopping, you execute a script using seEval. It is possible to leave the connection open and run multiple scripts. The debugger will handle them all. However, doing so may confuse the debugger user. It is usually better to use seDbgStop after the script is done and reconnect to the debugger if another script needs to be debugged.

INVOKING THE DEBUGGER ON AN ERROR