B Application Programming Interface

B.1 The `Ozcar` Module

The Ozcar module, available at x-oz://system/Ozcar, exports the following features.

object: {Ozcar.object +Message}; provides the interface to the running debugger itself. It is described below.
open: {Ozcar.open}; is identical to {Ozcar.object on}.
close: {Ozcar.close}; is identical to {Ozcar.object off}.
breakpoint: {Ozcar.breakpoint}; sets a static breakpoint (see Section 5.3.1). Execution of {Ozcar.breakpoint} causes the current thread to be stopped and attached to the debugger if the debugger has been started, and is ignored otherwise.
startServer: {Ozcar.startServer ?Ticket}; starts a server to accept connections of remote debugging clients (see Chapter 8) and returns a ticket with which clients can connect. Once the server has been started, the expression {Ozcar.startServer} will always return the same ticket.

init: {Ozcar.object init()}; closes and recreates the internal Ozcar object, discarding all information about attached threads. Identical to the Destoy menu item described in Section A.1.1.
on: {Ozcar.object on()}; starts Ozcar, opening the Ozcar window, setting the virtual machine to debug mode, and configuring the OPI compiler to generate debug code.
off: {Ozcar.object off()}; by default, suspends Ozcar, closing its window, but keeping all information about attached threads. Restarting Ozcar (using on()) will resume a debugging session exactly where it has been left before. Can be reconfigured by closeAction (see below).
conf: {Ozcar.object conf(FeatureA: +ValueX ...)}; configures Ozcar parameters. The method must be a record where each feature FeatureA is a configuration parameter and the corresponding subtree ValueX the value to set the parameter to. See Section B.3 for a list of parameters.
bpAt: {Ozcar.object bpAt(+FileV +LineI +EnableB)}; sets or resets dynamic breakpoints. All step points in files with name FileV and in line LineI are affected. The flag EnableB specifies whether dynamic breakpoints at these step points should be enabled (true) or disabled (false). See Section 5.3.2 for more information on dynamic breakpoints.
lastClickedValue: {Ozcar.object lastClickedValue(X)}; returns the value that has last been clicked on in the user interface, causing it to be passed to the Inspector.

Feature	Type	Default	Description
`timeoutToSwitch`	integer	100	Timeout in milliseconds before a thread switch is performed, unless another thread switch is initiated before it.
`timeoutToUpdateEnv`	integer	200	Timeout in milliseconds before the Environment Views are updated, unless another environment has been requested before this.
`emacsInterface`	`false` or an object	The OPI	The object to talk to for source display and highlighting requests. Typically an instance of `Emacs.interface`.
`closeAction`	`unit` or a nullary procedure	`unit`	Configures how the `off()` method behaves - and thus, how the `Suspend` menu item and `Ozcar.close` API function behave. If the `closeAction` is `unit`, then Ozcar is suspended, else the specified procedure is invoked.

start: {OzcarClient.start +Ticket}; starts a local debug session, connecting to a remote debugger using Ticket. This sets the virtual machine to debug mode (if and only if the remote debugger is active) and sets up threads to forward debug events to the remote debugger and to locally execute control operations generated by the remote debugger. This should not be used with a local Ozcar runnning. See Chapter 8 for more information on remote debugging.