Using SCODB on SCO OpenServer 5

Running SCODB

SCODB is included as an unconfigured pseudo-device driver in the SCO OpenServer kernel. To activate it:

Compile the driver or other kernel source module with the -DDEBUG option and install it in the kernel. If you will be using the source code line number feature), compile the source module with the -g option. Note that code compiled with the -g option may not be optimized.
If necessary, run the bin/modtunes command to modify the value of the SCODB tunable parameters. Specifically:
- If you are using source code line numbers, set LINETB to twice the number of lines of source code being recompiled with line numbers.
- If you are using a display other than an ANSI console, set SYSTTY to the number that corresponds to the display being used. See ``Setting up the display unit''.
- For large configurations, the value of SYMTB might need to be increased.
Configure the scodb driver into the kernel by modifying the sdevice(F) file and relinking the kernel. Be sure that the driver you are debugging is also linked into the kernel.
Reboot the system.
Invoke kernel-level SCODB by issuing the <Ctrl>x command on the console. Invoke user-level SCODB by issuing the scodb command at the shell prompt.
NOTE: Kernel-level SCODB is also invoked by the calldebug( ) function coded into the driver or other kernel code, and any time the kernel panics while the scodb driver is configured into the kernel.
The value used to invoke kernel-level SCODB is controlled by the DBKEY tunable parameter. This can be set to any key that is not commonly used for other purposes; see ``Modifying tunable parameters''.
Kernel-level SCODB can be run from other types of displays. See ``Setting up the display unit''.
The user-level scodb(ADM) command can be run without configuring the scodb driver into the kernel, but some additional setup steps are required. See ``Structure/union and variable definition files'' for information.
When kernel-level SCODB is awaiting input, it displays a prompt:
```
   debugn:m>
```
n
is a number indicating the entry level in the debugger. In general, the entry level will be 0; if SCODB is reentered or a panic occurs while in the debugger, the entry level will be incremented. The level is decremented when exiting the debugger.

m
is a number indicating the command number in the history.

The prompt for the user-level scodb(ADM) command is:
```
   scodbm>
```
If you prefer emacs-style editing to vi-style editing, issue the editmode command as discussed in ``Setting the edit mode''.
Issue SCODB commands for the functionality required.
SCODB has a history mechanism similar to that of ksh(C). Entering <Esc> puts the current input line into edit mode, where either vi- or emacs-style editing can be used. The vi and emacs modes have separate history files, so if you toggle between the two edit modes, the command history is not shared.
Note that the number of history lines remembered is a limited configurable parameter, and that the ``undo'' facility is quite limited.
Use the quit (q) or quitif command to exit SCODB:
```
   q [address]                                     /* Quit debugger */
   quitif expression                               /* If (expression) then quit */
```
The debugger is exited by using q. If address is given, execution resumes there, otherwise the debugger makes a normal function return back to its calling point.
The quitif form is very useful in breakpoint command lists. If the given expression evaluates to a non-zero value, control returns to the kernel as in q.

A good understanding of kernel internals is required to get full use of the SCODB debugger. Steve Pate's UNIX System Internals: A Practical Approach[1] (Addison-Wesley, 1996) gives a detailed explanation of the SCO OpenServer 5 kernel and is an excellent reference to use when running SCODB.

The following conventions are used throughout this document:

Examples use the following format. debug0:1 is system output (the SCODB prompt in this case); bp s5readi is user input.
```
   debug0:1> bp s5readi
```
<Del> denotes user input of ASCII DEL (octal 0177), or ``delete''.
<Esc> denotes user input of ASCII ESC (octal 033), or ``escape''.
<Space> denotes user input of ASCII SP (octal 040), or ``space''.
A quit character is any one of <Del>, q, or Q.