DEBUG488 User's Guide Program and documentation copyrighted 1991 by Capital Equipment Corporation (CEC). All rights reserved. Copying or duplicating this product, except as described below, is a violation of law. Purchasers of this product may copy the program for backup purposes. Only one copy may be in use at a time. CEC warrants that the documentation and diskette(s) are free from defects in materials and workmanship for a period of 90 days from date of purchase. CEC's sole obligation under this warranty shall be, at CEC's option, to replace the defective part or to refund the purchase price. CEC makes no other warranty, express or implied, including any warranty as to the suitability of this product for any particular purpose. Capital Equipment Corporation 76 Blanchard Rd. Burlington, MA 01803 (617) 273-1818 CEC DEBUG488 User's Guide Part number 01000-90900 Manual v1.0 INTRODUCTION DEBUG488 is a tool for tracking the execution of IEEE-488 programs and finding errors. DEBUG488 lets you: * review the history of '488 subroutine calls * see all the '488 subroutine parameters, to find errors in calling the routines * stop on any desired '488 function * stop on a status return value, such as timeout * stop on a serial poll result value * single step to see each '488 call as it is executed ------------------------------ *** SYSTEM REQUIREMENTS *** Hardware Any PC compatible computer. At least 256K of RAM. PC<>488, PS<>488, 4x488, or 488EX interface card. *** 488 Library Version 3.0 or later (see disk label). (Any application program linked with this library version can be debugged with DEBUG488. Programs linked with an earlier version will not have their '488 calls stored by DEBUG488). *** Software DOS version 2.0 or later. *** INSTALLATION *** Hard Disk First, create a directory on your hard disk called DEBUG488. Then, copy the files from the DEBUG488 floppy to this disk directory: *** COMPUTERINSET = C> md \DEBUG488 C> cd \DEBUG488 C> copy A:*.* C:\DEBUG488 Add the DEBUG488 directory to your DOS PATH command, so you can run these programs from any directory. *** Floppy Disk If you have only floppy disks, just copy the .EXE files from the DEBUG488 floppy to your DOS system disk: *** COMPUTERINSET = A> copy B:*.EXE A: *** CHAPTER HEAD = USING DEBUG488 *** HOW TO RUN DEBUG488 DEBUG488 is a TSR (terminate and stay resident) program, which remains in memory while you run other programs. To load DEBUG488, type the command: *** COMPUTERINSET = C> DEBUG488 DEBUG488 will load into memory and display a message on the screen. Then it will return to the DOS prompt. Now you may execute the IEEE-488 application program you are trying to debug. If you would like to follow along with the manual, you can run the IEEE488 interactive utility program: *** COMPUTERINSET = C> IEEE488 This program presents you with a menu of '488 functions which you may execute from the keyboard. *** 1 = ACTIVATING DEBUG488 *** "Hotkey" To activate DEBUG488, hit the "hotkey" combination, which is normally the Alt key combined with the D key (Alt-D). This will cause DEBUG488 to display its screen over whatever is currently showing on the monitor. To exit DEBUG488 again, just use the ESC key. You may change the hotkey combination to Alt combined with any letter when loading DEBUG488. See the Reference section of this manual for a full list of DEBUG488 command line options. *** Beep If DEBUG488 just beeps when you try to activate it, it is indicating that DOS is busy and DEBUG488 cannot pop up right now. Just try the hotkey again. The DOS operating system is not designed for full multitasking. TSR programs like DEBUG488 are not allowed to interrupt certain parts of DOS. If DOS is executing one of these routines, DEBUG488 cannot pop up on the display, and must sound the beeper instead. *** Screen Modes DEBUG488 can pop up over any text mode screen. However, because of limitations in saving and restoring the screen contents, DEBUG488 cannot pop up when the screen is in graphics mode. It will beep to indicate that it cannot be activated. Note that DEBUG488 continues to correctly record the '488 call history regardless of the screen mode. *** 1 = HISTORY SCREEN When the hotkey combination is used to activate DEBUG488, it displays the history screen This screen shows a summary of the IEEE-488 subroutine calls that have occurred. Each line shows the function name, GPIB address, data string, and status. For those functions which do not have an address, data string, or status, those columns are left blank. History lines are numbered from 0, for the most recent '488 call, back to negative numbers for previous '488 calls. History line number 1 can also appear, when DEBUG488 stops the application program on entry into a '488 subroutine. Line number 1 will show a '488 routine which has been called, but has not executed yet. The PgUp and PgDn keys may be used to see the rest of the history. DEBUG488 stores up to 64 history entries by default. The history size can be changed when DEBUG488 is loaded (see the Reference section of this manual for command line options). The Home and End keys may also be used to jump to the earliest or latest '488 call in the history. ------------------------------ *** Function Keys At the bottom of the history screen are the available function keys. These keys allow you to select the various DEBUG488 operations. F1 is always available to display help screens. F2 switches between the history screen and the detail screen (to be described next). F3 does a '488 single-step operation: it exits DEBUG488 and lets the application program continue until the next '488 call. F4, labelled "Go", returns to the application program and lets it continue execution. F7 displays the "Set Traps" screen, which allows you to set conditions for DEBUG488 to stop the application program. F8 clears any existing trap settings. F9 saves the '488 call history to a disk file. F10 clears the history list. *** 1 = DETAIL SCREEN The detail screen appears when you hit F2 in the history screen. It shows all the information about the currently highlighted '488 call. For example, on an Enter call, the detail screen shows the GPIB address, the maximum length specified, the data received, the actual length, and the status result. *** Moving the Highlight The highlighted line in the history screen indicates which history entry is displayed in the detail window. You can move the highlight with the up- and down-arrow keys, or the PgUp, PgDn, Home, and End keys. For those functions which have data strings, the detail screen shows up to 16 bytes of data in ASCII and hex formats. *** 1 = SETTING TRAPS One of DEBUG488's most important features is its ability to "trap", or stop execution, of the application program on user-specified conditions. When the application stops on a trap, DEBUG488 automatically pops up (without the hotkey being pressed), and displays the detail screen for the trapped function. ------------------------------ The Set Traps screen is displayed by hitting the F7 key. This screen consists of a number of data entry fields, enclosed by square brackets. You can move the cursor from field to field with the Tab key or the arrow keys. You can exit the Set Traps screen with the ESC key or the F4 (Go) function key. *** Entry/ Exit The columns labelled Entry and Exit allow traps to be set upon entry to and exit from any of the '488 functions. Most often, you will want to set traps on exit, so that the results of the function execution will be available. In some cases, however, you may need to stop the program before a function executes, then single step it through the function to see what happens to the '488 devices. To set an entry or exit trap, move the cursor to the desired field and hit the "X" key. To clear such a trap, use the space key. *** Repeat Count When you set any entry or exit trap, you will see a repeat count of 0001 appear. If you want to stop on the first execution of the trapped function, just leave the count at that setting. However, if you want to wait until some number of executions have occurred, set the count to a larger number (1-9999). Just type over the value in the repeat count field. The repeat count will decrease each time the function executes. When it goes to zero, the trap will occur and DEBUG488 will pop up. After the trap occurs, the repeat count returns to 1. The trap will then occur on every subsequent function call. *** Status Mask You can trap on any desired status bit values by entering a status mask, in hexadecimal. For example, to stop on any timeout, enter a status mask of 8. *** Spoll Mask You can trap on any desired serial poll result bit values by entering an spoll mask, in hexadecimal. Any time the Spoll routine is called, the result value is AND'ed with this mask, and if the result is non-zero, a trap occurs. *** Clear Traps To clear all the traps, use the F8 function key. *** 1 = SINGLE STEPPING The F3 function key executes a '488 single step. This lets the application program execute through the next '488 call, then pops DEBUG488 back onto the screen and shows the details of this call. You can use single step to see every call made by a program by activating DEBUG488 before running the program and hitting F3. DEBUG488 will return to the DOS prompt and wait for a '488 call. When you run a program which makes a '488 call, DEBUG488 will pop up and show you the call. *** 1 = SAVING HISTORY TO DISK The F9 key stores the history data to a disk file. Enter the file name when prompted by DEBUG488. If the file already exists, you will be asked if you wish to replace it. The history file is a plain ASCII text file, one line per function. You can read it into a word processor or print it on your printer. *** 1 = HELP The F1 key brings up a help screen. Help is context-sensitive and will describe the current screen and the options available. Once the help screen is displayed, you can see other help topics. The topics are listed near the bottom of the help screen. Use the left- and right-arrow keys to select a topic, and hit Enter to go to the topic. Use the ESC key to exit help and return to the previous DEBUG488 screen. *** KEY NOTE TEXT = Help can also give specific advice on error conditions. If you are in the detail screen looking at a function which has unexpected or undesired results, try the Help key. In some cases, Help will be able to give specific advice. For example, if Enter times out, but some data is received, Help will suggest actions, such as changing the terminating character setting. *** CHAPTER HEAD = EXAMPLES *** INPUT TIMEOUT In this example, an IEEE-488 device control program written in QuickBASIC is not working. The program seems to pause for a long period (many seconds) at certain points, so a timeout is suspected. The first step is to load DEBUG488, then run QuickBASIC and load the troublesome program. Next, pop up DEBUG488 and set a trap on timeout status (value=8): ------------------------------ Run the QuickBASIC program. When the timeout occurs, DEBUG488 will stop the program and appear on the screen, showing the '488 call which caused the problem. In this case, the ENTER call timed out after receiving 9 characters, and the data looks like the right data. Hitting the F1 key for help provides an explanation: The device never sent the terminator ENTER is waiting for (a line feed). It also did not send an IEEE-488 EOI signal to mark the end of the data. Looking at the documentation for the device indicates that it was originally designed for RS232 operation and sends only a carriage return character as a terminator. Editing the program to add a call to SetInputEOS, setting the terminating character to carriage return (ASCII code 13), fixes the problem. Note that this same example would apply equally well to any programming language. ------------------------------ *** MULTIPLE DEVICES In some programs, the repeat count feature of DEBUG488's traps can help handle multiple '488 devices. In this example, 3 different devices are being controlled. However, the third device is not showing any signs of activity. Its front panel lights should show changes in mode settings as the program runs. By looking at the program source code, it is determined that the third call to the SEND routine refers to the troublesome device. A trap can be set on the third execution of SEND: ------------------------------ When the program is started, DEBUG488 waits for the third SEND call and then stops the program: The status of 8 indicates a timeout or no response from the device. Further investigation shows that the device address switches have been changed from the default settings, so the GPIB address in the program is wrong. ------------------------------ *** TROUBLE WITH THE LANGUAGE INTERFACE The programming language interface is a very common source of problems in IEEE-488 programming. Mistakes in declaring subroutines, variables, or calling the routines can cause errors in the program. DEBUG488 can help by showing the actual '488 routines called and the values passed to them. This example uses interpreted BASIC (BASICA). The program runs, but the SEND calls don't seem to be successful. The device never changes its settings. Looking at the source code doesn't make the problem clear: the device address is correct and the calls seem OK. *** COMPUTERINSET = 10 DEF SEG=0 ' get software address 20 IEEE=PEEK(&H182)+256*PEEK(&H183) 30 DEF SEG=IEEE 40 INITIALIZE=0 : SEND=9 : ENTER=21 50 My.Addr=21 : Level=0 60 CALL INITIALIZE (My.Addr,Level) 70 Address=9 80 S$="*RST" 90 CALL SEND (Address,S$,Status%) ... etc... ------------------------------ The solution is to use DEBUG488, run the program, then pop up DEBUG488 to review the calls. This detail screen shows that the SEND calls are getting a GPIB address of zero. The intended value was 9. Checking with the '488 manual indicates that the address parameter must be an integer variable. In BASIC, such variables have names ending in %. The mistake was to use a real number variable, ADDRESS, whose value was mis-interpreted by the SEND routine. Adding the % sign to the variable corrects the trouble. *** CHAPTER HEAD = DEBUG488 REFERENCE *** COMMAND LINE DEBUG488 can take a number of parameters on its command line: *** COMPUTERINSET = DEBUG488 [size] [-r] [-kX] [-h] The square brackets indicate an optional parameter (don't actually type the brackets on the command line). *** size The size parameter is a number between 32 and 1024, and indicates the desired length of the history storage. The default value is 64 if the size parameter is not given. Each history entry takes 32 bytes of memory. *** -r The -r parameter tells DEBUG488 to unload itself from memory. This parameter is used if DEBUG488 is already loaded, and you wish to unload it to make more DOS memory available for other programs. DEBUG488 takes about 37K of memory, with the default history length of 64. *** -kX The -k parameter specifies a different hotkey combination. This parameter can be used when you first load DEBUG488 to change the default hotkey of Alt-D to Alt and any other letter. Just specify -k followed by the desired letter (with no spaces in between). For example, -kX would make the hotkey Alt-X. This option can be useful if Alt-D is an important key for another program you wish to run. *** -h The -h parameter can be used when DEBUG488 is already loaded. If DEBUG488 is in memory and you run "DEBUG488 -h", DEBUG488 will pop up on the screen just as if you hit the hotkey combination. This is mainly useful if you have changed the hotkey and forgotten it. Note: the hotkey setting can be seen by choosing Help (F1), and selecting the "Keys" help topic. *** KEYS *** F1 Help *** F2 History/Detail. Switches between these two screens. Note that F2 is not available in the history screen if the history list is empty. *** F3 Single Step. Exits DEBUG488 and sets a trap for the end of the next '488 function call. *** F4 Go. Exits DEBUG488 and lets the application program continue until the hotkey is pressed or a trap occurs. *** F7 Set Traps. Displays the trap screen so trap conditions may be changed. *** F8 Clear Traps. *** F9 Save History. Saves the call history to disk. *** F10 Clear History. *** ESC Exit the current screen. If the current screen is the history screen, this is just the same as F4. *** PgUp/ PgDn Move through the history list. These keys are available in the history and the detail screens. *** Arrows The up- and down-arrows can be used to move through the history list. All the arrow keys are available in the Set Traps screen, to move around the data entry fields. *** Home/ End Move to the top or bottom of the history list. These keys are available in the history and detail screens. ------------------------------ *** ERROR MESSAGES "DEBUG488 already present. Use 'DEBUG488 -r' to remove it." *** BODY INSET = DEBUG488 has already been loaded into memory. It can only be loaded once. Use DEBUG488 -r to remove it, or just use the hotkey to access the existing copy. "DEBUG488 could not be removed from memory." *** BODY INSET = DEBUG488 -r was used, but the program could not be removed. This can occur if another TSR was loaded after DEBUG488. Any TSRs loaded after DEBUG488 should be unloaded before unloading DEBUG488. Common TSRs include: SideKick, the DOS PRINT command, and some versions of the DOS MODE command. "DEBUG488: no available software interrupts between 62H and 66H. Cannot load." *** BODY INSET = DEBUG488 requires an unused software interrupt between 62 hex and 66 hex. On most systems, none of these will be in use. If this message occurs, try removing some other TSRs or device drivers which may be using these interrupts. "DEBUG488: not enough memory. Cannot load." *** BODY INSET = DEBUG488 requires about 37K (with the default history size). This message will occur if part of DEBUG488 can load, but it cannot allocate enough memory for the history storage. You can try reducing the history size. *** CHAPTER HEAD = IEEE488 INTERACTIVE UTILITY The IEEE488.EXE program is a utility for interactively trying out '488 subroutines from the keyboard. It may be used to experiment with DEBUG488 or to try out instrument control commands without having to write and debug a program. *** Menus When you run IEEE488, it displays a list of '488 functions. Each is preceeded by a one or two letter code that may be used to select the function. The M selection displays another menu of functions. There are three function menus in all. The Q selection exits IEEE488 and returns to DOS. *** Executing a Function To execute a '488 function from IEEE488, type the menu code at the prompt, followed by Enter. IEEE488 will then prompt you for any additional parameters required. For example, the Send routine will ask you for the GPIB address of the device and the data string to be sent. When typing in a data string, you can use the backspace key to edit your response. Use the Enter key when the string is complete. Any other key, including non-standard character values like Ctrl-E (ASCII 5), can be entered into the string. When you have entered all the parameters, IEEE488 will execute the function and display any result values. Hit Enter to clear the display and return to the menu to select another function.