The debugging services provided by the operating system are accessed using the DosDebug() function. Debugging services are obtained by repeated calls to DosDebug(), thereby simplifying the interface and increasing portability.
This function replaces the DosPTrace() function implemented in previous versions of OS/2. However, the DosPTrace() function is still available under OS/2 Version 2.0 as a 16-bit entry point, thus allowing debugging tools written for previous versions of OS/2 to be used to debug 16-bit applications.
The typical application programmer is unlikely to use the DosDebug() function. It is intended to be used by developers of high-level application debugging tools.
The syntax of DosDebug call is shown in Figure "DosDebug Function".
The DbgBuf parameter is a pointer to a data structure, which contains values used to control the execution of the DosDebug() function. One of the fields within the structure is used to hold a command word. On return, the same field contains a notification code. Commands may result in the reading or writing of memory, single stepping through the program, changing values in registers or the setting of watchpoints. The notifiers indicate events such as the loading of a DLL, encountering a breakpoint during program execution and watchpoint hits. The command to be executed is placed in the DbgBuf structure together with the necessary additional information for that specific command. The structure contains fields for all registers present in the system. There are other fields in the structure which are command specific. There are also fields for the process ID and the thread ID which identify the target for the debug command.
The DosDebug() function, its commands, parameters and return codes are described in detail in the IBM OS/2 Version 2.0 Control Program Reference.
The DosDebug() function executes synchronously; that is, the debugging process executing the call must wait for the function to complete and return control before it may continue execution.
The result of the DosDebug() call is a return code and an update of the command field with a notification code. See Figure "Sample DosDebug Function Call".
If this is the first DBG_C_Go command to be issued, a typical return code is RC = 0, and the notifier placed in the command field is set = DBG_N_ModuleLoad. This return implies that the application has just loaded an executable module and will always occur at program start. A notification is generated for each module loaded. Because there may be several DLLs loaded when the program is started, there will be several notifications pending. Only a single notification is returned on each DosDebug call. The debugger must issue DBG_C_Stop commands to retrieve all the outstanding DBG_N_ModuleLoad notifications.