contents   index   previous   next



It is possible to replace the ScriptEase debugger with a custom debugger. This section describes the protocol that the debugger is expected to understand.


Debugging occurs on TCP-IP sockets. The debugger must provide a port to receive debug requests on. If the debugger starts up an application to execute a script, it will give the host and port it is monitoring to the application via the command-line switch /debug=HOST:PORT. Applications can also run their scripts under a debugger at any time if they know a host and port combination a debugger is currently monitoring. This is especially useful to debug applications remotely. The ScriptEase debugger uses the port 0xdead so that all applications can find it. Custom debuggers can use whatever port they like or can mimic the standard debugger's port.


Each socket connection will be an application wishing to debug a script. It is up to the debugger writer if the debugger will allow multiple debug sessions simultaneously. If it does not, it should still accept the connection and use the DENIED response, described below, to refuse the debugging indicating that a debug session is currently processing.


Once a connection is established, the protocol consists of text messages sent back and forth between the debugger and the application as described below. The description of these messages specify the text in uppercase. This is done for clarity, as the commands are case-insensitive. However, on some systems filenames are case-sensitive so the debugger must preserve the case on all filenames. In the following description, parameters to the command are written in lowercase. The lowercase text is meant to describe the purpose of the parameter. The parameter is to be replaced by the appropriate value.


All text send by the application and the debugger to each other using this protocol is in ascii except for the specific exceptions mentioned below. All command lines are in ascii. Unicode can appear in only a specific few places. Two of the commands can optionally return unicode strings. When they do, they have a different response to indicate their return is unicode. The last place unicode can appear is in filenames. The filenames will be ascii strings, but unicode characters can be indicated by escaping them. In this case, the sequence \uXXXX is used where XXXX are exactly four hex characters indicating the value of the unicode character.


All command lines in this protocol are terminated by a \r\n\r\n marker. Data lines are always exactly what the data is, so they may have some combination of \r and \n in them. Data is always identified to be of a certain length by a preceeding header line before it is sent. That length is always exactly the number of bytes the data encompasses.