The Unsorted BBS Collection

home *** CD-ROM | disk | FTP | other *** search

/ The Unsorted BBS Collection / thegreatunsorted.tar / thegreatunsorted / programming / misc_programming / pcwatch.doc < prev next >

Wrap

Text File | 1985-07-01 | 114KB | 2,687 lines

PCWATCH Topics What is PCWATCH? .......................................1 Before You Begin .......................................1 "Do-It-Yourself" PCWATCH Demo ..........................2 The PCWATCH Command ....................................6 PCWATCH Categories and Specific Events ...............7 PCWATCH Categories ...................................9 BIOS ...............................................9 Communications .....................................9 Disk/Diskette ......................................9 DOS ................................................9 External ...........................................9 File System ........................................9 Keyboard ...........................................9 Noise ..............................................9 Printer ............................................9 Timer ..............................................9 User Defined 1, 2, and 3 ..........................10 Video .............................................10 Disabled Entry ....................................10 Exit with Carry ...................................10 PCWATCH Options .....................................11 Monochrome Display ................................11 Graphics Display ..................................12 Split Screen Mode .................................12 Top to line [xx] ..................................12 Bottom from [xx] ..................................12 Printer [LPTx] ....................................13 Max Output [xxxx] .................................13 Wait for Keystroke ................................14 Start by Rebooting ................................14 Exit to Debugger ..................................15 Register Display ..................................16 Input Registers ...................................16 Output Registers ..................................16 Control Blocks ....................................17 Nested Events .....................................17 The PCWATCH Tables ....................................18 The PCWATCH.TBL File ................................19 Names for PCWATCH Key Selections ..................21 Attributes ........................................22 Formatting Options ................................23 A Sample PCWATCH.TBL File .........................24 The PCWTBLB Command .................................25 The PCWATCH.SYS Device Driver .........................26 Limitations ...........................................27 Questions and Answers .................................29 Using PCWATCH with TopView ............................32 PCWATCH Program Information for TopView .............32 Restrictions on PCWATCH in the TopView Environment ..34 Messages ..............................................35 PCWATCH Messages ....................................35 PCWTBLB Messages ....................................40 Appendix A: Control Block Descriptions ...............45 ASCIIZ Strings ......................................45 Diskette Parameters .................................45 Disk Status .........................................46 FCB (File Control Block) ............................46 NCB (Network Control Block) .........................47 Appendix B: Changing Display Attributes ..............48 Appendix C: Specify PCWATCH Parameters Keys ..........49 End of Topics 1 What is PCWATCH?~ ---------------- PCWATCH is a powerful problem determination tool that lets you "watch" what is happening while your computer is running. It lists interrupts as they occur so you can trace the order in which they happen. PCWATCH monitors your computer's activity at the system interface level, not at the machine language instruction level. It permits you to deal with the same functional abstractions that are used by your programs when interacting with DOS or BIOS. PCWATCH lets you focus your attention on selected activities so that only those that are of interest to you are presented. It allows you to determine the precise sequence of events leading up to your problem so you can concentrate your efforts on fixing it, not finding it. Before You Begin~ ---------------- It is important to make a backup copy of your PCWATCH diskette in case your original is lost or damaged. Use the DOS DISKCOPY command to make a copy of your diskette. Then label the diskette "PCWATCH Backup." Store the original in a safe place and use the copy as you work. You might want to put PCWATCH on a utilities diskette. The files you need to copy are: PCWATCH.COM PCWATCH.TBL PCWATCH.SYS PCWTBLB.EXE NOTE: A fifth file, PCWATCH.PRO, may have been created if you have already used PCWATCH. You will want to copy it, too, if it exists. 2 "Do-It-Yourself" PCWATCH Demo~ ----------------------------- ------------------------------------------ | You will find it easier to follow this | | demonstration if you have a printed | | copy. If you have a printer, switch it | | on and align the paper. When you are on | | the Topics screen, select "'Do-It- | | Yourself' PCWATCH Demo." Press F2 then | | F4. | ------------------------------------------ The best way to preview the capabilities of PCWATCH is to run a short demonstration. To start the demo, follow the instructions described in this section. Explanations of the various PCWATCH options and advice for using PCWATCH in a variety of circumstances are given in later sections. 1. Return to DOS and set your default drive to A. 2. Insert your PCWATCH program diskette in drive A. 3. Start the program by entering: PCWATCH The PCWATCH logo screen appears. After a few seconds, the Specify PCWATCH Parameters screen (shown below) appears with the large block cursor on the top line in the box labeled "Categories." ---------------------------------------------------------------------------- Specify PCWATCH Parameters ----Categories----- -------Options-------- --Specific Events-- | BIOS | | Monochrome Display | | Int00 DivByZero | | COMMUNICATIONS | | Graphics Display | | Int01 SinglStep | | DISK/DISKETTE | | Split Screen Mode | | Int03 BreakPt | | DOS | | Top to line [13] | | Int04 Overflow | | EXTERNAL | | Bottom from [13] | | Int05 PrtSc | | FILE SYSTEM | | Printer [LPT1] | | Int06 InvalidOp | | KEYBOARD | | Max Output [9999] | | Int08 IRQ0-time | | NOISE | | Wait for Keystroke | | Int09 IRQ1-keyb | | PRINTER | | Start by Rebooting | | Int0A IRQ2-slav | | TIMER | | Exit to Debugger | | Int0B IRQ3-com2 | | USER DEFINED 1 | | Register Display | | Int0C IRQ4-com1 | | USER DEFINED 2 | | Input Registers | | Int0D IRQ5-fdsk | | USER DEFINED 3 | | Output Registers | | Int0E IRQ6-dskt | | VIDEO | | Control Blocks | | Int0F IRQ7-prtr | | Disabled Entry | | Nested Events | | Int10 Set mode | | Exit with Carry | | | | Int10 Curs type | ------------------- ---------------------- ---PgDn for More--- F1 Include/Select F2 Exclude F3 Quit F4 Start PCWATCH F5 Save Setup F6 Recall Setup F7 EGA 43 Lines F8 Show Keys ---------------------------------------------------------------------------- 3 4. Use the Cursor Down key to move the cursor to the line "DOS." 5. Press F1 (Include/Select). The word "DOS" becomes highlighted and the designation "Include" appears to its right. NOTE: If you make a mistake anywhere in the next few steps, press F3 (Quit) and return to step 3. 6. Move the cursor down to "NOISE." 7. Press F2 (Exclude). "Exclude" appears to the right of "NOISE" and to the left of one of the events listed in the Specific Events box at the far right. 8. Press PgDn three or four times to see other events that are included in the Noise category. 9. Move the cursor to the center box labeled "Options." 10. Do one of the following: o If you have a one-display system, go to step 11. o If you have a two-display system, move the cursor to the type of display PCWATCH is not running on and press F1. (For example, if the Specify PCWATCH Parameters screen is now on your monochrome display, select "Graphics Display.") 11. Move the cursor to the "Output Registers" line. 12. Press F1 (Include/Select). 13. Press F4 (Start PCWATCH). You have just requested that PCWATCH monitor all DOS services as they occur, showing the registers' contents both on entry into and exit from the interrupt routine for each occurrence. By excluding the category Noise, you requested that no services that occur when the machine is in an idle state (waiting for input) should be shown. 4 If you have a one-display system, the screen clears, PCWATCH lists the interrupts that are occurring in the top half, and the DOS prompt appears in the bottom half. This is referred to as "Split Screen mode." Half of your display is being used by PCWATCH and the other half by DOS. The solid line dividing the two sections indicates that Split Screen mode is active. If you have a two-display system, one display fills with output from PCWATCH while the DOS prompt appears at the top of the other. Regardless of the number of displays you have, when the DOS prompt appears, the output generated by PCWATCH stops. In the PCWATCH output, a special line called "the marker" is highlighted. This line traverses the PCWATCH screen while PCWATCH is active and serves the following purposes: o It tracks where the next output line generated by PCWATCH will appear. The line immediately above the marker is always the most recent event that PCWATCH has displayed. When the marker reaches the bottom of the PCWATCH screen (or PCWATCH partition if you are using the Split Screen mode), it returns to the top and starts over, overwriting the oldest output line from PCWATCH. This way, only the most recent events are kept on the display. o It labels the various fields shown on each line of PCWATCH output. The leftmost field is the CS IP field. This has the Code Segment and Instruction Pointer addresses that the service returns to when it has completed. The name of the service immediately follows the CS IP field. This is the name as it appears in the PCWATCH tables. You can supply your own names for system services by customizing PCWATCH with the PCWTBLB program. (See "The PCWATCH Tables" for more information.) If the CS and IP registers are separated by a colon (:), the remaining values shown on the line are the registers on entry to the service. If the separator character is a slash (/), the values shown are the contents of the registers when the service completed. Any changes to the registers that occurred as a result of invoking the service function are highlighted. o It serves as a counter to keep track of the number of events that PCWATCH has displayed. The event count appears after the word "Service" in the marker. 5 For certain services, additional output lines will also appear. These lines are used to display common arguments such as ASCIIZ strings, File Control Blocks (FCBs), diskette parameters, and other information used by system functions. These lines are labeled at the left and indented slightly so that they can be readily distinguished from the register information. Continue the PCWATCH demo on your own. Try running some common DOS commands, such as DIR and TYPE, and see what happens while they run. Press the Enter key a couple of times, also. You may notice that PCWATCH slows your system down slightly. This is due to the overhead of intercepting and displaying the services. PCWATCH is currently running in "real time" mode. Sometimes the services will go by so fast that you will not be able to read them unless you use Ctrl-Num Lock to freeze the system's operation. Even then, it would be hard to stop the output at the right times. However, PCWATCH also has a "slow-motion" mode of operation, allowing an entire screen or partition to fill with PCWATCH output and then causing the computer to halt until you press a key. This mode of operation is selected from the Specify PCWATCH Parameters screen by including the Wait for Keystroke option. Since PCWATCH passes these keystrokes through to DOS or the program you are running, press the left or right Shift key rather than a character. (See the section "Wait for Keystroke for more information.) You can temporarily deactivate the output from PCWATCH by pressing Alt-S. This suspends the appearance of PCWATCH output, but all of the normal monitoring that you selected continues to be in effect so that you can resume it at a later time. To resume the PCWATCH output, press Alt-R. PCWATCH can be suspended and later resumed any number of times. To return your system to normal operation, press Alt-T to terminate PCWATCH. Once you have terminated PCWATCH, it can no longer be resumed. To restart PCWATCH, enter the PCWATCH command again. The PCWATCH Suspend, Resume, and Terminate keys can be used at any time while PCWATCH is active, even while programs are running. Although these functions are assigned by default to Alt-S, Alt-R, and Alt-T, you can associate them with keys of your preference using the PCWTBLB program. (See "The PCWATCH Tables" for more information.) 6 The PCWATCH Command~ ------------------- The PCWATCH command is completely interactive because PCWATCH is intended to be used solely as an interactive tool. There are no command arguments; all inputs and options are indicated using the Specify PCWATCH Parameters screen. Start PCWATCH by entering: d:PCWATCH at the DOS prompt, where "d" is the letter of the drive where your file PCWATCH.COM is located (if it is not in your current directory). If the resident portion of PCWATCH is not already installed in your system, you see the PCWATCH logo screen. PCWATCH removes the logo screen after a few seconds or as soon as you press a key. The Specify PCWATCH Parameters screen appears next. Normally, your approach to this screen should be to move the cursor to the appropriate categories or specific events that you want to include or exclude and select them using F1 (Include/Select) or F2 (Exclude). After you have finished indicating the types of services you want to watch, move the cursor to the Options window and select from these options. Briefly review your selections (all included and excluded items will be highlighted) and, if they are correct, activate PCWATCH by pressing F4. If you make a mistake and include something you want to exclude, move the cursor back to that item and press F2. If you change your mind completely and decide not to start PCWATCH after all, press F3 to exit. Once you press F4 to start PCWATCH, the PCWATCH program is installed and begins intercepting all the appropriate services. Those that meet the selection criteria you've specified cause PCWATCH to produce output on the display or printer you selected. PCWATCH continues to operate in this manner until you enter the PCWATCH command again or press either the Suspend key or the Terminate key. If you think you might want to run PCWATCH again with a similar or identical set of events and options, you can use the F5 key to save your current specifications for later use. When you press F5, PCWATCH first attempts to save your setup specifications in a file called PCWATCH.PRO in the current directory of the default drive. If PCWATCH is unable to create a file (because the drive is not ready, the diskette is write-protected, or there is no space available), it saves the current setup information in memory, from which it can later be recalled. 7 Use F6 to recall a saved setup specification. Like the save function, a recall first looks for a PCWATCH.PRO file in the current directory of the default drive. If none can be found, PCWATCH then looks to see if a saved set of specifications is available in memory. Failing that, PCWATCH recalls the specifications that were used the last time PCWATCH was started. An informational message at the bottom of the screen indicates the type of setup information that was recalled. If you have an IBM Enhanced Graphics Adapter (EGA) attached to a monochrome or an IBM Enhanced Color Display, you can use the F7 key to toggle between the 25- and 43-line fonts. The 43-line font permits you to display more PCWATCH output at one time than the 25-line font. Also, the 43-line font permits you to specify that output from PCWATCH should appear only in lines 26 through 43, giving you the use of a full 25 by 80 screen for your applications without the need of two displays. See "PCWATCH Options" for more information on how to set up this kind of split screen operation. PCWATCH Categories and Specific Events~ The left window on the Specify PCWATCH Parameters screen is labeled "Categories" and the right window is labeled "Specific Events." These windows are related in that either may be used to indicate services that you want to watch or not watch. However, the items listed in the Categories window refer to groups of individual services listed in the Specific Events window. The Specific Events window can be paged forward or backward using the PgDn and PgUp keys. Using Ctrl-PgDn takes you to the end of the list; using Ctrl-PgUp returns you to the beginning. One line appears in this window for each service (or event) that has been defined in the PCWATCH tables. You can add or delete items in this list, or modify existing items, by updating the PCWATCH tables directly. (See "The PCWATCH Tables" for more information.) The PCWATCH tables also determine which services in this list belong to which category on the left. To include an entire category of services, move the cursor to the appropriate category in the left window and press F1. You can see which services have been selected by paging backward and forward through the Specific Events window and noting the services that have been designated with the "Include" indicator. If you want to exclude one or more of the services in a category, move the cursor to the specific service in the Specific Events window and press F2. 8 Some of the events on the right are classified as belonging to several categories. For example, the category Keyboard includes some events from the BIOS category as well as some from the DOS category. Consequently, when you exclude a category, you may end up excluding some events from other categories as well. The most commonly excluded category is Noise. Noise is essentially defined here to mean any service or event which occurs while the computer is in an idle state. Examples of services in the Noise category are interrupt 08 (Time of Day) and interrupt 1C (Timer Tick), both of which occur 18 times a second, and interrupt 16, AH=1 (Test for Key), which DOS uses constantly to poll the keyboard to determine if there is anything to do yet. Generally speaking, because services in this category are used so heavily and so frequently even when nothing is going on, they are almost never of interest. Some liberties have been taken with this definition and some additional services have been included which do not actually occur in the idle state but are otherwise heavily used and usually uninteresting. One of these, for example, is the DOS service interrupt 3E (Close a File Handle). DOS issues 15 of these each time a program exits, whether they are needed or not. You might enjoy watching the Noise category of events just to see why "noise" events are usually excluded. The inclusion of one or more categories makes groups of events eligible to appear in PCWATCH's output. What actually appears in the output are included events that have not been excluded. (Remember that some categories overlap, so that some services may be both included and excluded.) The rule is that "exclude" overrides "include," except that including a specific event directly overrides excluding it via a category. In practice, therefore, if you mark a particular service for exclusion in the right-hand window, it will definitely be excluded and you will never see it. If you mark a particular service in the right-hand window as included, it will definitely be included and you will see it if it occurs, even if it is a member of a category that you later excluded. Two final points on this topic: 1. You can always change your mind. For instance, if you have excluded something that you meant to include, just move the cursor back to it and press the include key. 2. Your include/exclude specifications remain in effect only until you terminate PCWATCH or run the PCWATCH command again. 9 PCWATCH Categories~ PCWATCH's categories are described in the sections below. BIOS~ The basic input/output (BIOS) routines described in your machine's Technical Reference manual. Communications~ All BIOS and DOS services that pertain to the use of the RS-232 ports, PC Cluster, or the PC Network. Disk/Diskette~ All BIOS and DOS services that pertain directly to physical operations on diskettes or fixed disks. DOS~ Services described in the DOS Technical Reference (or Appendix D of the earlier DOS manuals). External~ External interrupts that occur as a result of IRQ signals on the IBM PC bus. File System~ DOS services that pertain to operations on files. Keyboard~ BIOS and DOS services in support of the keyboard. Noise~ Essentially, services or events that occur regularly while the PC is in an idle state. Printer~ BIOS and DOS services in support of printers. Timer~ BIOS services that relate to the time-of-day clock and the use of the internal timer. 10 User Defined 1, 2, and 3~ You can define the meaning of these categories any way you want by modifying the PCWATCH tables. Video~ BIOS and DOS services in support of displays. Disabled Entry~ This category is somewhat different from those above in that it does not refer directly to any specific events. Instead, when you include Disabled Entry, PCWATCH monitors every interrupt defined in the PCWATCH.TBL file to see if it is issued while the machine is in a disabled state. Since most of the services represented by interrupts immediately re-enable the machine for additional interrupts, an occurrence of this condition may be indicative of a software error. Errors of this sort can be particularly elusive to find using normal debugging tools but can be readily discerned with PCWATCH. Exit with Carry~ This category also does not refer to any group of specific events but causes PCWATCH to report any service which returns to its caller with the carry flag set. Since this convention is used by many DOS services and some BIOS services to represent the occurrence of an error, it can frequently be of interest when debugging a problem. 11 PCWATCH Options~ The center window of the Specify PCWATCH Parameters screen displays the options of the PCWATCH program. To select an option, move the cursor until it covers the desired option and press F1. PCWATCH highlights the option to indicate that it has been selected. Default options are already highlighted when you start PCWATCH. To deselect an option, move the cursor to it and press F2. PCWATCH removes the highlighting to indicate that the option is no longer selected. Some of the options in the list are related. For instance, the Printer [LPTx] option and the display options are mutually exclusive. Selecting the Printer [LPTx] option automatically deselects all of the display options. Similarly, if you deselect the Register Display option, all of its subordinate options (Input Registers, Output Registers, Control Blocks, and Nested Events) are automatically deselected because Register Display is a prerequisite for the others. You will find it difficult to make a mistake because PCWATCH will not let you select a conflicting set of options or omit one that is needed for another. Most of the options you select remain selected as defaults the next time you run PCWATCH, provided you have not rebooted or powered off your computer since then. As a convenience, certain specialty options (such as Start by Rebooting and Exit to Debugger) are never automatically selected when PCWATCH is started. Descriptions of the options are given below. Monochrome Display~ If you are using your monochrome display when you start PCWATCH, this option will always be selected by default, even if you have a two-display system. This is primarily because PCWATCH cannot tell whether or not your other display is on. If you have a two-display system, the monochrome display is usually your best choice for PCWATCH output because it can be updated more rapidly than your graphics display. The exception to this rule is if your graphics display is attached to an IBM Enhanced Graphics Adapter, in which case it is faster. 12 Graphics Display~ This option directs PCWATCH to place its output on the display attached to your IBM Color/Graphics Monitor Adapter. You should be aware, however, that PCWATCH always operates the graphics adapter in text mode, never in graphics mode. Because the standard graphics adapter is slower than the monochrome adapter, it is possible to overrun it if you include too much output from PCWATCH. You can avoid this condition by always excluding services in the Noise or Timer categories. Split Screen Mode~ If you have a one-display system, PCWATCH will insist on operating in Split Screen mode. In this mode, PCWATCH uses either the upper or lower portion of your display to show your output, while DOS and programs running under DOS use the other portion. You can specify which part of the screen should be used for PCWATCH's output with one of the next two options (Top to line [xx] and Bottom from [xx]). In either case, the split line may be as small as three or as large as three less than the maximum number of lines on your display. Displays attached to an IBM Enhanced Graphics Adapter can have as many as 58 lines on the screen, depending on the active font. The F7 key may be used as a toggle to select either a 25- or 43-line font if you have a monochrome or IBM Enhanced Color Display attached to an EGA card. Top to line [xx]~ When you select this option, the cursor narrows to bring your attention to the number in brackets just to the right of the words "Top to line." This is the number of the line where the split should occur; PCWATCH uses only the portion of the screen above this line. The default value is 13. Press Enter to accept the default or enter a new value. Bottom from [xx]~ When you select this option, the cursor narrows to bring your attention to the number in brackets just to the right of the words "Bottom from." This is the number of the line where the split should occur; PCWATCH will use only the portion of the screen below this line. Ordinarily the default value is 13, but if you use the F7 key to select the EGA 43-line mode, the default value is 26. Press Enter to accept the default or enter a new value. NOTE: Using the Split Screen mode with "Bottom from [26]" is the ideal way to use PCWATCH whenever you are using the EGA 43-line font. This permits you to run full screen applications in the top 25 lines and still generate a useful amount of PCWATCH output on a single display. 13 Printer [LPTx]~ This option directs PCWATCH to route all of its output to a parallel printer of your choice. This can be used to obtain a permanent record of services monitored by PCWATCH. When you select the Printer [LPTx] option, the cursor narrows until it covers only the number following the letters "LPT" just to the right of "Printer." Either enter the number of your printer (1, 2, or 3), or press Enter to accept the default (1). The cursor then resumes its normal length. Because PCWATCH output is produced while your programs are running, the use of the printer slows down your system considerably. It is a good idea whenever you use the Printer [LPTx] option to be as specific as possible when including events to watch. Since the system may run very slowly if many services have been included, it could take several seconds for PCWATCH to even respond to the Terminate or Suspend key. Max Output [xxxx]~ This option is primarily intended for use in conjunction with the Exit to Debugger option. When you select this option, you indicate the maximum number of services for which PCWATCH should produce output. When this number has been reached, PCWATCH deactivates itself automatically. If used with the Exit to Debugger option, this deactivation causes PCWATCH to exit to your resident debugging program as if a call to it had occurred immediately following the final service monitored by PCWATCH. (See "Exit to Debugger" for more information.) When you select the Max Output [xxxx] option, the cursor narrows to cover the maximum number of events. Enter the value you want. The cursor then returns to its normal size. 14 Wait for Keystroke~ This option causes PCWATCH to operate in "slow motion" so that each output line can be closely inspected. When operating in this mode, PCWATCH allows the computer to run until its screen or partition has filled. Then PCWATCH halts the computer until you press a key so you can review the output. Although PCWATCH waits until you press a key, it does not consume the key itself. That is, any key you press will be allowed to go into the system's internal keyboard buffer. This permits you to continue to interact with programs that require keyboard input. You will understand better what we mean when you have to enter a command to DOS while PCWATCH is still in Wait for Keystroke mode. It is recommended that you press a Shift key to signal that PCWATCH should continue so that no unintended characters enter the keyboard buffer. If you are watching a large number of events, you must be quick and light on the Shift keys or the screen will fill and continue before you've had a chance to study it. Start by Rebooting~ This option instructs PCWATCH to relocate itself to the upper portion of memory and simulate a boot sequence while remaining active. This permits you to watch stand-alone programs and DOS device drivers while they are being installed. PCWATCH requires the use of the upper 48KB of memory when this option is selected. To monitor the use of DOS services during the reboot process, you should first make certain that PCWATCH.SYS has been added to your CONFIG.SYS file. (See "The PCWATCH.SYS Device Driver" for further information.) 15 Exit to Debugger~ This option tells PCWATCH to start your resident debugging program when the number of services specified by the Max Output [xxxx] option have occurred. It is a powerful way to give control to your debugger at a precise point without inserting special traps or debugging code into existing programs. A resident debugging program is one which has already been installed prior to running PCWATCH and can respond to an interrupt, such as interrupt 01 (Single Step), interrupt 02 (Nonmaskable), or interrupt 03 (Breakpoint). A good example of a resident debugger is provided by the Resident Debug Tool (RDT) in IBM's Professional Debug Facility. PCWATCH comes with tables preconfigured to invoke RDT using the nonmaskable interrupt. In most circumstances, this feature can also be used with the standard DOS 3.0 (or later) DEBUG program using interrupt 01 (Single Step). To use PCWATCH with DEBUG: 1. Modify your PCWATCH.TBL file to use interrupt 01 as the debug interrupt. (See "The PCWATCH Tables" for more information.) 2. Run the PCWTBLB program to install the new tables into PCWATCH. 3. From DOS, enter the command: DEBUG COMMAND.COM 4. In response to the prompt from DEBUG, enter: G (for "GO"). COMMAND.COM displays its usual startup message and returns to the DOS prompt. DEBUG is now installed and ready to use with PCWATCH. You must exercise some caution when using the Exit to Debugger option with DEBUG because DEBUG uses DOS services for console input and output. You should avoid causing the Exit to Debugger option to occur during any DOS console services (interrupt 21 services 01 thru 0C). Exactly when the entry to your debugger occurs depends upon whether or not you have selected the Output Registers or Nested Events option. If you have chosen either, PCWATCH calls your debugger immediately following the completion of the selected service but before returning. The CS:IP value upon entry to the debugger points to the instruction where the service routine would have returned. If you have not selected Output Registers or Nested Events, PCWATCH enters your debugger with the CS and IP registers pointing to the first instruction of the selected service. 16 One exception you should be aware of is when the service that triggers the Exit to Debugger has the Oneway attribute in the PCWATCH tables. In this case, the debugger is entered prior to the start of the service regardless of the selected output options. (See "The PCWATCH Tables" for more information on the Oneway attribute.) Register Display~ This option helps you designate what PCWATCH should include in its output. You can specify exactly what you want to see with the four options indented below "Register Display." If you deselect the Register Display option, PCWATCH produces an "event display." This is a trace of each event giving only its return address (CS:IP values) and name, not the contents of its registers. It is a quick way to scan a large number of services to see the sequence in which they occur. For an event display, PCWATCH places up to three events on each line and uses a short marker to keep its place across the line. The event marker moves from left to right and from top to bottom. Input Registers~ This option governs whether or not PCWATCH displays the contents of the registers upon entry into each service. The marker is used to label the registers. Output Registers~ This option governs whether or not PCWATCH displays the contents of the registers upon exit from a service. As with the Input Registers option, the marker is used to label the registers. Any changes in the registers' contents as a result of the service are highlighted. Note that output registers cannot be displayed for any services in the PCWATCH tables that have the Oneway attribute. Output registers are not meaningful for Oneway services. 17 Control Blocks~ This option controls the formatting and display of information other than the contents of the registers. If selected, it allows you to see ASCIIZ strings and FCBs used with DOS services, diskette parameters, disk status information, and, for some services, 32 bytes of unformatted information pointed to by DS:BX, DS:DX, DS:SI, ES:BX, or ES:DI. Whether or not control blocks apply to particular services is indicated by information in the PCWATCH tables and can be assigned as appropriate based on your specifications. See Appendix A for explanations of the individual control block types PCWATCH can display. Nested Events~ This option provides a "how does it work?" capability. When an included event or service occurs, all subsequent services which occur between the time that the included event starts and the time it returns to its invoker are automatically included and presented as PCWATCH output. This allows you to see just what goes on internally within a particular service. Note that the rule about excluded services still applies, and any services you have explicitly excluded (either by category or specific event) will not be shown. In this way, Noise services can still be filtered out. 18 The PCWATCH Tables~ ------------------ Because PCWATCH is completely table-driven, it can be readily customized. All of the default customizations and table entries are provided with PCWATCH in a file named PCWATCH.TBL. So that modifying the table information can be as easy as possible, all entries are stored as ASCII text. Consequently, you can view or print the tables with standard DOS commands and modify them with a text editor that operates on ASCII files. However, the ASCII table format is not the most efficient representation for PCWATCH to use during its operation. Therefore, the PCWATCH Table Builder program (PCWTBLB) is provided to "compile" the table information directly into the PCWATCH program itself. To modify, add, or delete table entries: 1. Edit the PCWATCH.TBL file as desired. 2. Run PCWTBLB to update the PCWATCH program with the revised table information. This effectively produces a new version of the PCWATCH program, customized specifically for your use. When you edit your PCWATCH.TBL file, it is recommended that you "comment out" entries that do not apply to your system configuration rather than delete them entirely. To remove an entry, just convert it to a comment by placing a semicolon (;) before it. To restore an entry, remove the semicolon. The table file supplied with PCWATCH has definitions for most interrupts used by DOS 3.1 and earlier and many that are specific to certain models or device adapters of the IBM PC family. These are labeled with appropriate comments in PCWATCH.TBL. 19 The PCWATCH.TBL File~ You can make four types of definitions in the PCWATCH.TBL file: o Terminate, Suspend, and Resume keys You can define which keys will terminate, suspend, or resume PCWATCH output. The format of these lines is "terminate key = ", "suspend key = ", or "resume key = " followed by the name of the key. (See "Names for PCWATCH Key Selections" for a list of the valid key names.) o Exit to Debugger method This definition allows you to indicate which method should be used to call your debugger when using the Exit to Debugger option. The format of this line is "debug int = " followed by a hexadecimal number between 0 and FF. The most common values used are interrupt 01 (Single Step), interrupt 02 (Nonmaskable), and interrupt 03 (Breakpoint). Consult the documentation for your debugger to determine the method that will work for you. o Interrupts These lines allow you to define which specific events you will have the opportunity to select from the Specify PCWATCH Parameters screen. Their format is: INT=xx "name" [attr,form] where: xx is the interrupt number (in hexadecimal format). name is the name for the interrupt that you want to appear in PCWATCH's output. It can be up to 15 characters long and must be enclosed in double quotation marks. attr,form are any attributes and formatting options you want to apply to the interrupt (see "Attributes" and "Formatting Options" below). Codes should be separated by commas, and the entire list should be enclosed in square brackets. This field is optional; you do not have to give attributes and/or formatting options for every interrupt. 20 o Interrupt subfunctions These lines allow you to define the special cases of an interrupt so PCWATCH will recognize them. Their format is the same as general interrupts, except that the "INT" is replaced by either "AH" or "AL." In general, subfunctions can be specified as based on AH or AL, and within either of these the other (AL or AH) can also be used to specify further subfunctions. For example, INT=21 is used for DOS services, and within this interrupt AH is used to designate the particular DOS service. For AH=44 (the DOS IOCTL function), AL further indicates the type of IOCTL function to be performed. You can add comments to the end of any of the definition lines by starting the comment with a semicolon (;). (An entire line can be a comment if its first character is a semicolon.) Each of the definitions must fit on one line. All entries must be given in ascending order by interrupt number, and within interrupts, by subfunction number. If you want to modify the PCWATCH tables, be careful not to define any INT entries where BIOS, DOS, or other system components expect to find anchors or pointers to tables. If PCWATCH were to install intercept routines over those locations, it could result in a hung system. Make certain you understand what a particular interrupt is used for before you define it for PCWATCH. Most presently known uses of interrupts as table anchors are currently noted via comments in the PCWATCH.TBL file. 21 Names for PCWATCH Key Selections~ This is a list of all of the keys that can be specified in the PCWATCH.TBL file for assignment as the PCWATCH Resume, Suspend, or Terminate keys. In general, keys may be specified using the designation that appears on the key tops. Names have been assigned to keys with only graphic designators. Note that C can be used for Ctrl, S for Shift, and A for Alt. Also, PCWTBLB accepts key names in either upper or lower case, with or without hyphens or spaces. Up Down Left Ctrl-Left Right Ctrl-Right PgUp Ctrl-PgUp PgDn Ctrl-PgDn Home Ctrl-Home End Ctrl-End Esc Tab Shift-Tab Backspace Ctrl-Backspace Enter (or Return) Ctrl-Enter (or Ctrl-Return) Ins Del Alt-A through Alt-Z Alt-0 through Alt-9 F1 through F10 Ctrl-F1 through Ctrl-F10 Shift-F1 through Shift-F10 Alt-F1 through Alt-F10 Keypad-Plus (or Keypad +) Keypad-Minus (or Keypad -) PrtSc-* (or PrtSc or *) Ctrl-PrtSc 22 Attributes~ The attribute field is used to group the specific events into the categories that can be selected from the Specify PCWATCH Parameters screen. An interrupt can belong to more than one category. The attributes that can be specified are: Attribute Code Category --------- -------------- B BIOS C Communications D DOS E External F File System K Keyboard N Noise O Oneway P Printer S Disk/Diskette T Timer V Video 1 User Defined 1 2 User Defined 2 3 User Defined 3 NOTE: Any services which do not (or might not) return to the invoker of the service must be defined to have the Oneway attribute listed above. Omission of this attribute where it is needed could result in a hung system. 23 Formatting Options~ The formatting options allow you to specify additional information you want displayed for an interrupt when you select the Control Blocks option. If you want the same formatting option to apply on both entry to and exit from a service, choose the code from the list below and add it to the list of attributes. You may only choose one formatting option per service. However, if you want PCWATCH to display some information on entry to the service and/or different information on its return, you can choose two options. Follow the option for entry with an "I" (for input) and the option for exit with an "O" (for output). The formatting options are: Format Code Function ----------- ---------------------------------------- A Format the data at DS:[DX] as a DOS ASCIIZ string. G Format the data at DS:[DX] as a DOS FCB. H Format the current BIOS diskette parameters. L Format up to 13 words from the stack. M Format the status bytes from the disk or diskette controller. Q Format the data at ES:[BX] as a PC Network Control Block (NCB). U Format the 32 bytes at DS:[BX]. W Format the 32 bytes at DS:[SI]. X Format the 32 bytes at DS:[DX]. Y Format the 32 bytes at ES:[BX]. Z Format the 32 bytes at ES:[DI]. For more information, see Appendix A. 24 A Sample PCWATCH.TBL File~ ; This is a very short sample of a PCWATCH.TBL file. ; To see a long, detailed example, print out a copy of the PCWATCH.TBL ; file that came with PCWATCH. ; terminate key = Alt-T ;For immediate PCWATCH termination suspend key = Alt-S ;To suspend all PCWATCH output temporarily resume key = Alt-R ;To resume suspended PCWATCH output ; debug int = 2 ;Use nonmaskable interrupt to ; trigger debugger ;---------------------------------------------------------------------------- ; Interrupt Service Attributes Comments ; Number Name & Formatting ;---------------------------------------------------------------------------- ; INT=04 "Int04 Overflow" [O] ;Fixed overflow INT=05 "Int05 PrtSc" [B,P] ;Print screen ; INT=13 "Int13 Disk/ette" [B,S,HI,MO] ;Disk/diskette services AH=00 "Int13 DiskReset" [B,S,HI] ; Reset disk(ette) system AH=02 "Int13 Read secs" [B,S,HI,MO] ; Read sectors AH=03 "Int13 WriteSecs" [B,S,HI,MO] ; Write sectors ; INT=21 "Int21 Dos Svc" [D] ;DOS services AH=01 "Dos01 Key input" [D,K] ; Keyboard Input AH=06 "Dos06 Con I/O" [D,K] ; Direct console I/O AH=44 "Dos44 IOCTL" [D,F] ; I/O control for devices AL=00 "Dos44 Get info" [D,F] ; Get device information AL=01 "Dos44 Set info" [D,F] ; Set device information AL=06 "Dos44 InputStat" [D,F] ; Get input status AL=07 "Dos44 OutptStat" [D,F] ; Get output status AL=0A "Dos44 HRedirect" [D,F] ; Handle redirected? AH=45 "Dos45 DupHandle" [D,F] ; Duplicate file handle AH=47 "Dos47 Cur dir" [D,F,AO] ; Get current directory AH=48 "Dos48 Alloc mem" [D] ; Allocate memory AH=49 "Dos49 Free mem" [D] ; Free allocated memory AH=4A "Dos4A Set block" [D] ; Modify alloc memory block AH=4B "Dos4B Load/Exec" [D,A] ; Load or execute a program AL=00 "Dos4B Execute" [D,A] ; Execute a program AL=03 "Dos4B Load ovly" [D,A] ; Load a program AH=4C "Dos4C Exit" [D,O] ; Terminate a process (EXIT) AH=4E "Dos4E Find 1st" [D,F,A] ; Find first matching file AH=4F "Dos4F Find next" [D,F] ; Find next matching file ; ; INT=60 "Int60 User" [1] These three ; INT=61 "Int61 User" [1] interrupts are ; INT=62 "Int62 User" [1] "commented out." 25 The PCWTBLB Command~ PCWTBLB takes the definitions you have stored in your PCWATCH.TBL file and modifies PCWATCH.COM so it can use these definitions. PCWTBLB reads and compiles the information in the table file into a format suitable for insertion into the PCWATCH program. If PCWTBLB detects any errors, it produces diagnostic messages to help you isolate and correct them and the PCWATCH program file is not updated. If no errors are detected, PCWTBLB creates a backup of the old PCWATCH program file (named PCWATCH.BAK) and produces a new version of the program file (using the name you specified) with the updated table information. The syntax of the PCWTBLB command is: PCWTBLB table-filename program-filename or PCWTBLB table-filename,program-filename "Table-filename" is the name of the file containing all your definitions. The table file included with the program is PCWATCH.TBL, but you can give your table files any names you want. "Program-filename" is usually PCWATCH.COM, unless you have changed it for some reason. Either of these filenames can include a drive specification and, if you are using DOS 2.0 or later, a path specification. If you omit the operands, PCWTBLB prompts you for them. You will not be able to use the new generation of the PCWATCH program to recall any saved setup specifications created by a prior generation. This is because PCWTBLB rebuilds the internal PCWATCH tables and invalidates specifications that refer to the former level. You should be aware that if you add additional entries to the PCWATCH tables, you will increase the size of the PCWATCH program, in turn increasing the minimum storage required to run PCWATCH. Each additional INT, AH, or AL entry requires approximately 28 bytes. 26 The PCWATCH.SYS Device Driver~ ----------------------------- If you are using PCWATCH with DOS 2.0 or later, you can use the PCWATCH.SYS device driver in conjunction with the Start by Rebooting option to monitor the use of DOS services during system initialization. System initialization includes the loading and initialization of device drivers and the DOS shell program COMMAND.COM. Without PCWATCH.SYS, only BIOS services and external interrupts can be monitored during this period. To make use of this capability, supply the following statement as the first line in your CONFIG.SYS file: DEVICE=path\PCWATCH.SYS where "path\" is the path specification for the subdirectory where PCWATCH.SYS is located. ("Path\" is optional if PCWATCH.SYS is in your root directory.) Note that the CONFIG.SYS file is required to reside in the root directory on your boot device. (See your DOS manual for more information about the CONFIG.SYS file and its uses.) In general, the DEVICE=PCWATCH.SYS statement should appear before any other DEVICE= statements. No monitoring of DOS services during system initialization will occur until PCWATCH.SYS has been loaded. There is one exception you should be aware of: if you use the DOS ANSI.SYS device driver, you should place it first and PCWATCH.SYS second. To monitor DOS services during system initialization, run PCWATCH and select the Start by Rebooting option. You can ask to see all DOS services by including the DOS category or by including specific DOS services. Then press F4 and your system will reboot with PCWATCH keeping track of the requested activities. 27 Limitations~ ----------- PCWATCH is a powerful tool for discovering the inner workings of the IBM PC, but it is possible to misuse it. This section discusses some of the areas where you should exercise care when using PCWATCH. Some of these points are mentioned elsewhere, but are repeated here as a reminder. PCWATCH performs its monitoring functions by installing intercept routines for each of the interrupts that are defined in the PCWATCH.TBL file. The intercept routines are installed only once (the first time you press the F4 key from the Specify PCWATCH Parameters screen). Once installed, these intercepts can be activated or deactivated by suspending, resuming, terminating, or restarting PCWATCH, but they remain in place (unless overwritten by subsequent programs) until you reboot your computer. In general, you will have the most success watching interrupts that are handled by programs installed before PCWATCH. Software in this category includes BIOS, DOS, device drivers, and numerous DOS extensions that provide the principal services used in most application programs. PCWATCH is not able to trap interrupts for programs that install their own temporary interrupt handlers after PCWATCH has been installed unless they "reflect" events to the normal interrupt handlers by branching to the normal handlers when they have completed their task. Interrupts most likely to be handled by applications without reflection include the DOS Control Break and Critical Error interrupts (23H and 24H), interrupts with no assigned BIOS functions, and some external interrupts that have no direct BIOS support. Application programs that install permanent interrupt handlers should be started before PCWATCH whenever possible. Remember that PCWATCH does not process interrupts on its own; it simply intercepts and displays them when appropriate. If an error in a program causes your computer to lock up, PCWATCH does not prevent this from occurring. Instead, it enables you to monitor the events that lead up to it while you recreate the condition. The main differences you will experience as a result of running PCWATCH are that you will have a bit less storage available and the computer will operate somewhat slower than normal. This, in turn, may affect the operation of any program that is severely constrained by storage space or has critical dependencies on execution time. 28 If your system has two displays, you probably use the DOS MODE command to switch from one display to another. While PCWATCH is active, your ability to do this successfully will be restricted. The Specify PCWATCH Parameters panel has been designed to give you flexibility in selecting how your displays will be used. If you need to switch displays after starting PCWATCH: terminate PCWATCH, use the MODE command, restart PCWATCH, then respecify your display selection. Using the MODE command while PCWATCH is active can produce strange results. Don't try to watch everything all of the time. Hundreds of interrupts occur every second, and it is possible to cause a condition called "overrun." Overrun occurs when PCWATCH is so busy displaying output that it falls behind just trying to keep up. When this happens, you may find that the keyboard does not respond and the only recourse you have is to switch off the machine. Overrun is most likely to occur when you are using a printer or the IBM Color/Graphics Monitor Adapter because they are relatively slow output devices. One step you can take toward avoiding overrun is to exclude events in the NOISE category whenever you are monitoring a large number of interrupts. For PCWATCH to intercept and display output registers or nested events, it must be able to correlate the exit from an interrupt routine with the state of the machine when the interrupt was entered. The use of multitasking dispatchers or context switching software can interfere with the "natural" sequence of events to the extent that PCWATCH may not be able to perform its task reliably. If you use such software in conjunction with PCWATCH, it is recommended that you not include the Output Registers or Nested Events options. Finally, remember that PCWATCH relies heavily on the accuracy of the information supplied in the PCWATCH.TBL file. In particular, look for the following when adding entries: o Do not define (except as comment lines) interrupt vectors that are used only as anchors for tables and control blocks. o Be certain to include the Oneway attribute with any interrupt that may not return to its caller under all circumstances. o Specify the Noise attribute for all services that are executed while the machine is idle (waiting for input). The PCWATCH Table Builder program checks for proper syntax on all entries, but it has no way to verify that the information you provide is correct. 29 Questions and Answers~ --------------------- Q. Can I redirect PCWATCH output to a file? A. No. Because PCWATCH produces its output without interfering with the state of the computer, it cannot use any of the DOS file services. However, you can ask PCWATCH to direct its output to LPT1, LPT2, or LPT3 if you have a printer attached to a parallel adapter. Q. Why is PCWATCH not able to protect its split screen partition when running some full-screen applications? A. Because of the nature of PCWATCH (it runs while your program is also running), it cannot save and restore the contents of the display screen. If you need to watch a full-screen application that writes directly into the display buffer, try one of the following approaches: o For a two-display system, allow the application to use one display while PCWATCH uses the other. o For a system with an IBM Enhanced Graphics Adapter and a monochrome or IBM Enhanced Color Display, use the 43-line mode with PCWATCH output on lines 26 through 43. o Use a printer for PCWATCH output instead of a display. o As a last resort, a careful selection of top or bottom Split Screen modes may enable you to keep PCWATCH output away from the most active portions of the application's display screen and keep interference to a minimum. Q. How can I cause PCWATCH to exit to my debugger when the particular instance of the service I'm interested in occurs? A. First, run PCWATCH using the Wait for Keystroke option. When the instance of the service that you want to trap occurs, you can determine its number using the PCWATCH event marker. Then, rerun PCWATCH and specify this value as the Max Output [xxxx] parameter in conjunction with the Exit to Debugger option. When you rerun your program, be careful to use the same sequence of commands you used the first time. 30 Q. Why can I monitor only BIOS services and External events when watching a stand-alone program? A. These are the only services available in the machine for the use of stand-alone programs. Q. Why will some stand-alone programs not work with PCWATCH? A. Certain copy protect schemes do not allow the coexistence of the PCWATCH Facility. Q. Is it normal for the PC's time-of-day clock to run slow when PCWATCH is active? A. Not if you have an IBM Personal Computer AT or if you are just watching a small number of services; otherwise, yes. The additional disabled path length imposed by PCWATCH in order to intercept system services will slow down your clock somewhat. This is particularly dramatic if you are sending PCWATCH output to a printer. In this case (and depending heavily on exactly which categories you have selected to watch), your whole system may run in such "slow motion" that long pauses may appear between each output character. Shutting off PCWATCH returns your system to normal operating speed, but you may need to correct the time of day by using the DOS TIME command. Q. Is there a way to get the BASIC interpreter to cooperate with PCWATCH's Split Screen mode so it does not attempt to use the PCWATCH partition? A. Yes, there is a very simple way. Start PCWATCH normally (indicating a Split Screen mode) and remember the number of the line where you indicated the split should occur (13 or 26 is the default). This value is represented as "n" in the commands shown below. Then start BASIC or BASICA. If necessary, use the Cursor Down key to move the cursor out of the PCWATCH partition into BASIC's portion of the screen. Then do one of the following: o If the PCWATCH partition is at the top of the screen, enter: DEF SEG:POKE 91,n+1 o If the PCWATCH partition is at the bottom of the screen, enter: DEF SEG:POKE 92,n-1 BASIC now confines its operation to the portion of the screen not used by PCWATCH. 31 Q. Is it possible to single step through an interrupt when using PCWATCH with RDT (IBM's Resident Debug Tool)? A. Yes, if some care is exercised. Because PCWATCH intercepts most interrupts and handles them serially while the computer is disabled, single stepping during this process could be disastrous if the use of interrupts by RDT itself caused an unexpected reentry into PCWATCH. If you think you may need to do this, edit the PCWATCH.TBL file and comment out the entries for interrupts 01, 03, 08, and 09. Then run PCWTBLB to create an updated version of PCWATCH. As a further precaution, when using RDT, issue the RDT command: UM FD This sets the RDT user mask to prohibit external interrupts from occurring while the RDT display is active. This will prevent background activity from reentering PCWATCH while you are stepping through it. Q. Is there a way to watch programs that produce graphics output? A. Since PCWATCH requires that any display you select for its output operate in text mode, you should take one of the following approaches when you plan to monitor a graphics program: o If your system has both a graphics and monochrome display, you can direct all PCWATCH output to the monochrome display while your graphics program uses the other display. o If you have only a one-display system, you can designate a printer as the PCWATCH output device so PCWATCH will not interfere with the graphics display. o If your program operates in graphics mode only part of the time, PCWATCH can share the display, provided that you suspend its output during the time that graphics mode is needed. When you revert to text mode, you can resume the output from PCWATCH. 32 Using PCWATCH with TopView~ -------------------------- You can use PCWATCH with the IBM TopView program if you follow the guidelines described in this section. Because the TopView Window Manager requires the use of a full 25-row by 80-column display, you will need to use one of the following as a PCWATCH output device: o A second display o A parallel printer o An IBM Monochrome or Enhanced Color Display attached to an EGA card Since TopView provides a local copy of interrupt vectors for most tasks, you must install PCWATCH (using F4 on the Specify PCWATCH Parameters screen) prior to starting TopView. This ensures that TopView tasks will inherit the interrupt vectors that are modified by PCWATCH. If you are using a single EGA display for both TopView and PCWATCH output, you must use the F7 key to place the EGA adapter in 43-line mode, select the Bottom from [26] option, then start TopView while PCWATCH is still active. Since you may later completely respecify the events to be included or excluded, your initial selection is essentially arbitrary. Once TopView is running, the PCWATCH command can be executed from a TopView window to select different events or output options. Each time you use the PCWATCH F3 or F4 key, the PCWATCH command task will terminate (and release its window). PCWATCH output, however, will appear at the appropriate time on the selected device. PCWATCH Program Information for TopView~ Add PCWATCH to the TopView Start A Program menu as you would for any new program and then select "Change Program Information" to specify additional information about PCWATCH. Fill in the program information fields, as follows: o Program Title: Whatever you like, but "PC Watch" is a good choice. o Program Pathname: Type the name of the drive and directory where the file PCWATCH.COM can be found. o Program Parameters: Leave this blank. PCWATCH does not take any command line parameters. 33 o Data Files Location: Type the name of the drive and directory that PCWATCH should use when saving or recalling setup information. o Memory: Set both the minimum and maximum fields to the same value, which should be the size of the PCWATCH.COM file divided by 1024 and rounded up to the next integer. Let the system field retain the default value assigned by TopView. o Screen Type: This should be D, unless you want to designate that PCWATCH should run only in mode 2 (black and white), mode 3 (color), or mode 7 (monochrome). This value affects only the Specify PCWATCH Parameters screen, not the output generated by PCWATCH. o Pages: 1 o Window Size: Twenty-five (25) rows by eighty (80) columns. o Offsets: Both should be 0. o Shared Program Pathname: Leave this field blank. o Shared Program Data: Leave this field blank. o Range of Software Interrupt Vectors Swapped: Erase the existing values in both the low and high fields. o Program writes directly to screen: N o Program accesses system keyboard buffer: N o Program runs only in the foreground: Y o Program uses math coprocessor: N If you supply the values given above, PCWATCH will run as a well-behaved TopView application. You can both size and move the PCWATCH window, but remember that the window is used only for the Specify PCWATCH Parameters screen, not the actual PCWATCH output. 34 Restrictions on PCWATCH in the TopView Environment~ Most of the PCWATCH options function in the TopView environment as they do for DOS. However, there are some considerations: o Output Registers option The Output Registers option should not be used with TopView. PCWATCH must correlate conditions upon entry to an interrupt with those in effect when the corresponding exit finally occurs. A context switch imposed by TopView's multitasking dispatcher can easily upset this process, leading to unpredictable results. o Nested Events option The Nested Events option should not be used with TopView for the same reason given for the Output Registers option. o Start by Rebooting option The Start by Rebooting option should be avoided as it requires you to increase the memory used for PCWATCH by an additional 48KB. Also, since TopView loads programs into well-defined regions of memory, PCWATCH will be unable to relocate itself to the high end of your system's memory. o Exit to Debugger If you select the Exit to Debugger option, remember that the only debugger recommended for use with TopView is the IBM Resident Debug Tool. o Selecting your output device Choose the PCWATCH output device carefully. If you have a two-display system, select the display not currently in use by TopView. If TopView and PCWATCH are sharing an EGA in 43-line mode, always select Bottom from [26]. o The F7 (EGA xx Lines) key The PCWATCH F7 key is not supported by TopView. If you press this key, TopView automatically suspends PCWATCH. However, if you have already established the EGA 43-line mode and PCWATCH is active, TopView operates with the upper 25 lines of the display, unaware of the lines below it. If you suspend or terminate PCWATCH output, TopView or an application program will be at liberty to restore the display to 25-line mode. As long as you intend for the 43-line mode to continue, only terminate PCWATCH while respecifying your choice of included or excluded events. 35 Messages~ -------- PCWATCH Messages~ The messages listed here are produced by PCWATCH in response to inputs entered on the Specify PCWATCH Parameters screen. Messages always appear at the bottom of the screen. Some messages are informational only; others indicate that you have made an error. These are easy to distinguish between because PCWATCH produces two short beeps when it displays an error message. Current setup information saved This message appears at the bottom of the PCWATCH screen when you press the F5 key if a PCWATCH.PRO file was successfully created in the current directory of the default drive. EGA adapter not installed The F7 key will not work unless you have the IBM Enhanced Graphics Adapter installed. Enter a number or press <--' This message appears at the bottom of the PCWATCH screen if PCWATCH was expecting a number and you enter something else. Either supply a number or press Enter to accept the currently displayed default. Inappropriate use of Include/Exclude You pressed either F1 (the Include key) or F2 (the Exclude key) when the cursor was not on a selectable item. Only blank entries in the Specific Events window are not selectable. Insufficient memory for reboot option The Start by Rebooting option requires an additional 48KB of unused storage after DOS and all resident programs are loaded. No display selected The F7 key will not work if a printer has been selected for PCWATCH output. 36 No saved setup available PCWATCH could not find any of the following: o A PCWATCH.PRO file in the current directory on the default drive o A saved setup specification in memory o The setup used the last time PCWATCH was started The last condition fails only if you have not yet started PCWATCH since you last switched on your machine or if you have just created a new level of PCWATCH using the PCWTBLB program. No saved setup; previous setup recalled PCWATCH could not find either PCWATCH.PRO in the current directory on the default drive or a saved setup specification in memory. Instead, PCWATCH has recalled the setup information you specified the last time PCWATCH was started. No such printer attached The printer number you specified for PCWATCH output is not recognized by BIOS as a valid printer. Enter a different number or deselect the printer option by pressing F2. Only 100 specific event includes/excludes allowed A limit of 100 specific events can be included or excluded and you have designated more than 100. Events included or excluded as a result of selecting a category do not count against this limit. Reboot for new tables to take effect PCWATCH is already resident in your system because of earlier use, but there is not a sufficient amount of free storage set aside to hold the additions you have made to the PCWATCH tables. Reboot your system and run PCWATCH again to set aside space for your new table entries. Reboot option is not available on this machine model The Start by Rebooting option is available only on an IBM PC, IBM PC XT, IBM Portable Personal Computer, or IBM Personal Computer AT. 37 Saved setup information recalled PCWATCH successfully recalled the setup information you saved in the PCWATCH.PRO file in the current directory on the default drive. Saved setup not recalled - tables have been changed The PCWATCH.PRO file found in the current directory on the default drive was saved by an older generation of the PCWATCH program and is not usable by the current generation. To create a new setup specification file, indicate the setup manually using the F1 and F2 keys and save it again by pressing the F5 key. Note that each time you create a new generation of PCWATCH using the PCWTBLB program, the formerly saved setup files are invalidated. Saved setup recalled from memory PCWATCH was not able to locate a PCWATCH.PRO file in the current directory on the default drive, but it did find saved setup information in memory. Selected display adapter not functioning The adapter for the display option you selected does not respond. However, the currently highlighted output selections remain in effect until you change them. Selected display is not on an EGA The F7 key will not work unless the display you selected for PCWATCH output is attached to an IBM Enhanced Graphics Adapter. Specify Max Output before selecting this option The Exit to Debugger option works in conjunction with the Max Output [xxxx] option. Specify a Max Output value to determine when the exit to your debugger should occur, then reselect the Exit to Debugger option. Supply new value or press <--' to accept default This message appears at the bottom of the PCWATCH screen when you include any of the options that take a numeric argument. It is there to remind you that you can supply a new value if you want. Either supply a new number or press Enter to accept the currently displayed default. 38 Unable to write setup file; setup saved in memory PCWATCH tried to create a PCWATCH.PRO file in the current directory on the default drive and failed. The failure was probably due to a lack of available space, a write-protect tab on a diskette, or a drive not ready condition. The current setup information was saved in memory instead. It can be subsequently recalled from memory until another setup specification is saved or the computer is rebooted. Value may range from 3 through X Select a value between 3 and X as the line where the screen split should occur. If you are using the 25-line mode, X will be 22. If you have an EGA and are using the 43-line mode, X will be 40. Value must be greater than 0 You may not specify a Max Output [xxxx] value of zero. Either press F2 to deselect the option or enter a nonzero value. Wait for Keystroke option not available on this machine model The Wait for Keystroke option is available only on an IBM PC, IBM PC XT, IBM Portable Personal Computer, or IBM Personal Computer AT. Warning: Press F2 or F3 if your debugger is not already resident! The Exit to Debugger option requires that your debugger be resident in memory prior to the time that you start PCWATCH. If this is not the case, press F2 to deselect this option or press F3 to quit PCWATCH so that you may start your debugger program. Warning: Setup saved in memory will be lost! Press F3 to quit anyway The current setup information was saved in memory the last time you pressed F5. However, PCWATCH has not yet been installed and the saved specification will be lost unless you start PCWATCH using F4. Press F3 again if you really want to quit PCWATCH (and lose the saved setup information). 39 Warning: PCWATCH does not support this machine model. Continue anyway? [Y or N]: PCWATCH is only supported on an IBM PC, IBM PC XT, IBM Portable Personal Computer, or IBM Personal Computer AT. This message appears if PCWATCH is run on any other model. If you type Y, PCWATCH attempts to run but may fail during execution. You must include at least 1 category or specific event This message appears if you press the F4 key without requesting any PCWATCH output. Either select some category or specific event for inclusion using the F1 key (and then press F4) or press F3 to quit the PCWATCH program. 43 lines requires monochrome or enhanced color display The F7 key cannot establish a 43-line mode unless you have a monochrome display or an IBM Enhanced Color Display attached to the IBM Enhanced Graphics Adapter. 40 PCWTBLB Messages~ The messages PCWTBLB generates while processing entries in the table file frequently refer to a specific line number where the error was discovered. Sometimes additional characters are shown in the message to help you determine what portion of a line was found to be in error. In this section, X represents the line number and Y represents some part of text from the line that is incorrect. Because PCWTBLB compresses each line before processing it, Y generally has all spaces, and sometimes punctuation characters, removed. AH without preceding INT while processing line X. A line beginning with the keyword "AH =" was encountered in the table file before any interrupt definition line ("INT =") was processed. The definition of a service based on AH values is only allowed for interrupts. Correct the table file and run PCWTBLB again. AL without preceding INT while processing line X. A line beginning with the keyword "AL =" was encountered in the table file before any interrupt definition line ("INT =") was processed. The definition of a service based on AL values is only allowed for interrupts. Correct the table file and run PCWTBLB again. Error in line X: expecting '[' for start of attribute list, found Y. The only syntactic element allowed to follow the name of a service is an attribute list. Attribute lists should always be enclosed in brackets ([]). You may have intended Y to be a comment; if so, separate it from the rest of the line by preceding it with a semicolon (;) and run the PCWTBLB program again. Error in line X: expecting attribute, found Y. Only the attribute characters B, C, D, E, F, K, N, O, P, S, T, V, 1, 2, and 3, and the formatting options A, G, H, L, M, Q, U, W, X, Y, and Z, are allowed to appear inside an attribute list. Make certain that you remembered to end the attribute list with a right bracket (]). Correct the table file and run PCWTBLB again. 41 Error in line X: expecting end of literal service name, found Y. Service name literals must be enclosed in double quotation marks at each end. For example: INT=14 "Int14 RS232" [B,C] ;Serial communications Correct the entry and run the PCWTBLB program again. Error in line X: expecting hex value, found Y. A one- or two-digit hexadecimal number is expected to follow the key words "INT =," "AH =," or "AL =." Correct the table file and run PCWTBLB again. Error in line X: expecting name of resume key, found Y. Y was not recognized as the name of a valid key to be assigned to the PCWATCH resume function. You can choose from any of the keys named in "Names for PCWATCH Key Selections." Correct the table file and run PCWTBLB again. Error in line X: expecting name of suspend key, found Y. Y was not recognized as the name of a valid key to be assigned to the PCWATCH suspend function. You can choose from any of the keys named in "Names for PCWATCH Key Selections." Correct the table file and run PCWTBLB again. Error in line X: expecting name of terminate key, found Y. Y was not recognized as the name of a valid key to be assigned to the PCWATCH terminate function. You can choose from any of the keys named in "Names for PCWATCH Key Selections." Correct the table file and run PCWTBLB again. Error in line X: expecting start of comment, found Y. Remember to start any comments with a semicolon (;). Correct the entry and run PCWTBLB again. Error in line X: expecting start of literal service name, found Y. Service name literals must be enclosed in double quotation marks. For example: INT=14 "Int14 RS232" [B,C] ;Serial communications Correct the entry and run the PCWTBLB program again. 42 Error in line X: Multiple format options specified. Only one formatting option may be specified to be applied at both input and output to a service. Correct the entry and run PCWTBLB again. Error in line X: Multiple input format options specified. Only one input formatting option may be specified for any particular service. Correct the entry and run PCWTBLB again. Error in line X: Multiple output format options specified. Only one output formatting option may be specified for any particular service. Correct the entry and run PCWTBLB again. Error in line X: out of sequence. All interrupts must be defined in ascending sequence by their hexadecimal numbers. Within an interrupt definition, all AH or AL definitions of subservices must also appear in ascending order. Correct the offending sequence and run PCWTBLB again. Improper signature in program file. The file you designated as being the PCWATCH program file does not contain the proper internal identification. Rerun the PCWTBLB program specifying the correct name for the PCWATCH program. (Unless you have renamed it, the file is called PCWATCH.COM.) Incompatible version of PCWATCH program file encountered. The PCWATCH program file you specified is at a later release level than the PCWTBLB program. Only use the new release of PCWTBLB to generate tables for the new release of PCWATCH.COM. Invalid line type while processing line X. PCWTBLB encountered an unrecognized entry in the table file. Valid entries start with the keywords "INT =", AH =", "AL =", "resume key =", "suspend key =", "terminate key =", "debug int =", or a semicolon (;). Correct the table file and run PCWTBLB again. 43 Literal service name on line X truncated to 15 characters. This message is for your information only. No action is necessary unless you want to use a shorter service name. PCWTBLB has automatically truncated the name you supplied to 15 characters (its maximum length). New tables stored in Y. This message is for your information only. PCWTBLB has completed successfully and updated the table information in the program file Y. If you execute Y, you will find that your new customizations are now in effect. Program filename [PCWATCH.COM]: PCWTBLB prompts you to enter the name of the PCWATCH program file. The default name is PCWATCH.COM. If you have renamed the program, you may supply the new name instead. If the program is not in the current directory or is on another drive, specify the fully qualified name. Otherwise, just press Enter to accept the default. Table filename [PCWATCH.TBL]: PCWTBLB prompts you to enter the name of the PCWATCH table file. The default name is PCWATCH.TBL. If you have renamed the file, you may supply the new name instead. If the file is not in the current directory or is on another drive, specify the fully qualified name. Otherwise, just press Enter to accept the default. Table overflow while processing line X. There was insufficient storage available for the operation of the PCWTBLB program. If your system is memory constrained, try booting from your DOS master diskette and running PCWTBLB without the use of any DOS extension programs. For DOS 2.0 or later versions, you may also be able to increase the amount of available storage by removing the "BUFFERS =" and "DEVICE =" entries from your DOS CONFIG.SYS file. Unable to create output file. Probable causes for this failure are that the output file was directed to a write-protected diskette, or that there was insufficient space on the disk or in the directory to create another file. 44 Unable to open Y. PCWTBLB is unable to open the filename (indicated by Y) that you supplied. Make certain that you have provided the correct name and run the PCWTBLB program again. Usage: PCWTBLB table-filename,program-filename If you supply too many arguments when running PCWTBLB, or if you type "PCWTBLB ?", this message is used to remind you of the correct syntax. You may also run PCWTBLB by typing "PCWTBLB" and letting it prompt you for the arguments it requires. PCWATCH tables not updated due to errors. Errors noted by earlier messages have prevented PCWTBLB from updating the tables in the PCWATCH.COM program file. Correct all of the errors and run PCWTBLB again. 45 Appendix A: Control Block Descriptions~ --------------------------------------- For some system services, PCWATCH will format prominent fields found in DOS or BIOS control blocks. This section briefly describes these fields and points you to the principal sources for additional information. ASCIIZ Strings~ An ASCIIZ string is one whose last byte is 00H. Many DOS services relating to file system operations require or return the specification of a path or filename in this form. PCWATCH displays this information in uninterpreted form. ASCIIZ names are described in the DOS Technical Reference manual and Appendix D of the older DOS manuals. Diskette Parameters~ Diskette parameters are used by BIOS to format diskettes and control the operation of the diskette adapter. This block is described in the Technical Reference manual for your PC model. Offset Shown as Description ------ ----------- ------------------------------- 0-2 XXXXXX Used for adapter initialization 3 size=XX Bytes per sector 00 = 128 01 = 256 02 = 512 03 = 1024 4 eot=XX End of track (number of sectors per track) 5 gapl=XX Gap length 6 dtl=XX Data length 7 gapf=XX Gap 3 length (used with format operations) 8 fill=XX Fill byte 9-10 delays=XXXX Head settle time XX.. Motor start time ..XX 46 Disk Status~ Disk status information is returned from the diskette or fixed disk controller at the completion of each physical I/O operation handled by the adapter. PCWATCH displays the seven status bytes as they are returned from the controller and kept at location 40:42 of the BIOS data area. Consult the Technical Reference manual for your PC model and the appropriate sections of the Options and Adapters Technical Reference manual for additional information. FCB (File Control Block)~ The File Control Block (FCB) is used for file operations with DOS services AH=0F through AH=29. It is described in the DOS Technical Reference manual (or Appendix E of older DOS manuals). Offset Shown as Description ------ ----------------- -------------------------------- 0-11 fn=X:XXXXXXXX.XXX File drive, name, and extension (-1) attr=XX File attributes (shown only if an FCB extension is present) 17-27 fn2=XXXXXXXX.XXX New filename. Present only in an FCB used for a rename operation 12-13 blk=XXXX Current block number 14-15 rs=XXXX Logical record size 32 cr=XX Current record number within the current block 33-36 rrn=XXXXXXXX Random record number 47 NCB (Network Control Block)~ Network Control Blocks (NCB) are used by the IBM PC Network Adapter BIOS to control the flow of information to and from the PC Network. These blocks are described in the IBM PC Network Technical Reference manual. Offset Shown as Description ------ ---------------- -------------------------- 0 XX Command code 1 XX Return code 2 XX Local session number 3 XX NCB number 4-7 XXXX:XXXX Segment and offset address of message buffer 8 XXXX Buffer length 10-25 XXXXXXXXXXXXXXXX Destination adapter name 26-41 XXXXXXXXXXXXXXXX Source adapter name 42 XX Receive time-out period 43 XX Send time-out period 44-47 XXXX:XXXX Segment and offset address of POST routine 48 XX Local adapter number 49 XX Command status 48 Appendix B: Changing Display Attributes~ ---------------------------------------- You can change the display attributes PCWATCH uses by modifying the attribute table near the beginning of the PCWATCH.COM file. The table begins immediately following the phrase "Attribute Tables:". The attribute table consists of 3 rows of 12 entries each. Each row corresponds to a particular type of display mode that you can specify using the DOS MODE command. The rows are assigned as follows: o Row 1: MODE MONO o Row 2: MODE CO80 o Row 3: MODE BW80 Within each row, there are 12 attribute bytes governing the appearance of a variety of elements. The bytes and their uses are: Row Offset Uses on Specify Uses in Other in Table PCWATCH Parameters Screen Places in PCWATCH ---------- ------------------------- ----------------- 0 Selectable categories, Register data, options, and events event data 1 Non-selectable items Register marker 2 Block cursor, function Event marker key labels 3 >>> <<< around messages [not used] 4 [not used] Modified registers 5 <-- Exclude --> [not used] 6 <-- Include --> [not used] 7 Error message text [not used] 8 Selected item when under [not used] block cursor 9 Excluded categories and [not used] events 10 Included categories and [not used] events, selected options 11 [not used] Text on logo screen Refer to the reference manuals for your computer and/or display type for information on what values to use for different attributes. 49 Appendix C: Specify PCWATCH Parameters Keys~ -------------------------------------------- A list of all of the keys that may be used while interacting with the PCWATCH program from the Specify PCWATCH Parameters screen follows: o Cursor movement Up, Down, Left, Right These keys move the block cursor in the indicated direction. The movement wraps around to the other end when the cursor can go no further in the indicated direction. Backspace Equivalent to Left End Moves the block cursor to the bottom of the current box (Categories, Options, or Specific Events). Home Moves the block cursor to the top of the current box (Categories, Options, or Specific Events). Enter Moves the block cursor to the left box (Categories) and down one row. Shift-Tab Equivalent to Left Tab Equivalent to Right o Data Entry Data entry keys function when an option requiring an additional input parameter has been selected using F1. The large block cursor narrows to focus on the particular input item. Backspace Undoes the effect of the last data key. Enter Ends data entry by restoring the large block cursor and accepting the currently displayed input value. Up, Down, Left, and Right As a convenience these are equivalent to Enter. 50 o Function keys Ctrl-PgDn Scrolls the items in the Specific Event box to the last page. Ctrl-PgUp Scrolls the items in the Specific Event box to the first page. F1 Includes the Category or Specific Event under the cursor, or selects the Option under the cursor. F2 Excludes the Category or Specific Event under the cursor, or deselects the Option under the cursor. F3 Exits the PCWATCH program and returns to DOS without starting PCWATCH. F4 Exits the PCWATCH program and returns to DOS while starting PCWATCH. The first time you start PCWATCH, it installs itself as a resident DOS extension. F5 Saves the current setup information. This includes all include/exclude specifications and selected options. F6 Recalls saved setup information. The screen is updated to reflect the recalled conditions. F7 Toggles between the 25- and 43-line modes for an IBM Enhanced Graphics Adapter with a monochrome or IBM Enhanced Color Display. F8 Shows the current key assignments for the PCWATCH suspend, resume, and terminate functions. PgDn Scrolls the items in the Specific Events box one page forward. PgUp Scrolls the items in the Specific Events box one page backward.