Programmer's ROM - The Computer Language Library

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

/ Programmer's ROM - The Computer Language Library / programmersrom.iso / ada / debug / sd.man < prev next >

Wrap

Text File | 1988-05-03 | 263.2 KB | 9,043 lines

Ada* Symbolic Debugger ( WIS_DEBUG ) Version 1.0 User's Guide ####### ####### ####### # # # # ####### # # # # ####### ####### ####### ####### ####### ####### ####### # # # # ####### # # # # ####### ####### ####### ####### ####### ####### ####### ####### # # # # ####### # # # # ####### ####### ####### ####### Intermetrics, Inc. 5312 Bolsa Avenue Huntington Beach, CA 92649 January 26, 1986 * Ada is a trademark of the U.S. Department of Defense (AJPO) Ada Symbolic Debugger User's Guide Page: i PREFACE Developed by: Intermetrics, Inc. 5312 Bolsa Avenue Huntington Beach, CA 92649 For: Naval Ocean Systems Center 271 Catalina Boulevard San Diego, CA 92152 Contract: N66001-85-C-0032 CDRL Item: 001AA Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: ii CONTENTS Chapter Page 1 INTRODUCTION ...................................... 1-1 1.1 TOOL OVERVIEW ................................... 1-1 1.2 CAPABILITIES .................................... 1-2 1.3 GENERAL LIMITATIONS ............................. 1-4 2 HOW TO USE THIS MANUAL ............................ 2-1 3 THE SYMBOLIC DEBUGGER PROGRAM LIBRARY ............. 3-1 3.1 THE BASE PROGRAM LIBRARY ........................ 3-1 3.2 THE CURRENT PROGRAM LIBRARY ..................... 3-1 4 USING THE WIS_DEBUG SHELL ......................... 4-1 4.1 THE "?" COMMAND (HELP) .......................... 4-2 4.2 THE SET_LIBRARY COMMAND ......................... 4-3 4.3 THE DELETE COMMAND .............................. 4-3 4.4 THE SOURCE INSTRUMENT COMMAND ................... 4-4 4.5 THE COMPILE COMMAND ............................. 4-8 4.6 THE LINK COMMAND ................................ 4-9 4.7 THE RUN COMMAND ................................. 4-9 4.8 THE SYSTEM COMMAND .............................. 4-10 4.9 THE HELP COMMAND ................................ 4-11 4.10 THE QUIT AND EXIT COMMANDS ...................... 4-13 4.11 SAMPLE SESSION WITH WIS_DEBUG ................... 4-14 Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: iii Chapter Page 5 EXECUTING THE DEBUGGER WITH AN INSTRUMENTED PROGRAM ................... 5-1 5.1 CREATING A LOG FILE ............................. 5-1 5.2 SETTING THE PROGRAM LIBRARY ..................... 5-3 6 DEBUGGING AN ADA PROGRAM .......................... 6-1 6.1 UNDERSTANDING BREAKPOINTS ....................... 6-1 6.2 SPECIAL DEBUGGER FEATURES AND COMMANDS .......... 6-2 Command Conventions ........................... 6-3 Keyboard Definitions .......................... 6-4 The Terminal Capabilities File ................ 6-4 The HELP Command .............................. 6-5 The CANFILE Command ........................... 6-7 The DEFINE Command ............................ 6-8 The SHOW_DEFINE Command ....................... 6-9 The SET_LIBRARY Command ....................... 6-10 6.3 CONTROLLING TERMINAL OUTPUT ..................... 6-10 The SCREEN Command ............................ 6-11 The SET_SOURCE Command ........................ 6-12 The SET_OUTPUT Command ........................ 6-13 The SCROLL_UP Command ......................... 6-14 The SCROLL_DOWN Command ....................... 6-14 The RESHOW Command ............................ 6-15 The RECREATE Command .......................... 6-15 6.4 DISPLAYING PROGRAM AND DEBUGGER STATUS .......... 6-16 The SILENT Command ............................ 6-16 The ANNOUNCE Command .......................... 6-17 The SHOW_BREAKPOINT Command ................... 6-17 The SHOW_HISTORY Command ...................... 6-18 The DISPLAY_UNITS Command ..................... 6-19 6.5 CONTROLLING PROGRAM EXECUTION ................... 6-20 The SET_BREAKPOINT Command .................... 6-20 The CLEAR_BREAKPOINT Command .................. 6-21 The GO Command ................................ 6-23 The STEP Command .............................. 6-23 The QUIT and EXIT Commands .................... 6-24 6.6 EXAMINING AND MODIFYING PROGRAM VARIABLES ....... 6-25 The PUT_VARIABLE Command ...................... 6-26 The SET_VARIABLE Command ...................... 6-27 Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: iv APPENDIX A - ALPHABETICAL COMMAND SUMMARY .............. A-1 APPENDIX B - DIAGNOSTIC MESSAGES ...................... B -1 B.1 WIS_DEBUG Shell Diagnostics ......... B1-1 B.1 Source Instrumenter Diagnostics ..... B2-1 B.2 Symbolic Debugger Diagnostics ....... B3-1 APPENDIX C - SPECIFIC WIS_DEBUG LIMITATIONS ............ C-1 APPENDIX D - REHOSTING INFORMATION ..................... D-1 APPENDIX E - TERMINAL CAPABILITIES FILE FORMAT ......... E-1 APPENDIX F - HELP FILE FORMAT .......................... F-1 APPENDIX G - GLOSSARY OF TERMS AND DEFINITIONS ......... G-1 APPENDIX H - COMMAND INDEX AND QUICK REFERENCE ......... H-1 Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 1 - 1 CHAPTER 1 INTRODUCTION WIS_DEBUG is a symbolic debugger for computer programs implemented in the Ada programming language. Its purpose is to enable the user to locate errors in program logic by providing a "window" into the program's execution through which the user can monitor, and to a certain extent alter, the status and flow of control of the Ada program under test. This manual describes the initial implementation of WIS_DEBUG on the DEC VAX under VMS 4.1 using the VAX Ada Compiler System (ACS) Version 1.0. 1.1 TOOL OVERVIEW WIS_DEBUG is one of several tools developed by Intermetrics, Inc. that provide testing and analysis aids for the development of computer programs implemented in the Ada programming language. It consists of: 1) A source instrumenter that parses the target Ada program and inserts "hooks" that transfer control to the symbolic debugger upon entry to and exit from each instrumented Ada program unit and at each breakpoint. Not every program unit in the Ada program must be instrumented by the source instrumenter. However, the main program unit and each Ada program unit which is to be visible to the debugger must be instrumented prior to compilation. 2) A Symbolic Debugger that gains control upon entry to or exit from each instrumented Ada program unit and breakpoint. The debugger contains a user interface that enables the user to control the execution of the program under test and to examine and modify program variables at the Ada Language level without regard for such things as absolute computer memory locations, program counters and status registers, or internal data representations. 3) A user friendly shell that enables the user to access the Source Instrumenter, the Symbolic Debugger, the Ada compiler and linker being used for program development, and to manage the WIS_DEBUG Program Library. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 1 - 2 WIS_DEBUG is implemented entirely in Ada and, in the spirit of Ada, has been designed to be highly portable. To the fullest extent possible WIS_DEBUG is both compiler independent and host computer independent. The source instrumenter is based on the front end of an Ada compiler that supports the full Ada Language. All symbolic information and statement "hooks" required by the debugger at runtime are inserted into a copy of the original Ada source program by the instrumenter. This unique feature eliminates the traditional reliance of "symbolic" debuggers on symbol information generated by the compiler and linker being used for program development, thereby enabling the tool to be readily ported to other host Ada environments and computers. 1.2 CAPABILITIES WIS_DEBUG contains extensive capabilities for controlling the execution of the target Ada program, examining and modifying program variables, and monitoring program status. The features and capabilities that make it both a powerful and flexible software development tool are: 1. It is symbolic. It enables the user to step through and analyze the execution of an Ada program at the Ada language level and using the same program unit names and variable names as the original source program. 2. It is interactive. The user may set breakpoints to suspend program execution at a specified point. When the breakpoint is reached control is returned to the user allowing him to examine and modify program variables, examine the status of all program units, set other breakpoints, and resume execution. 3. It supports both SCREEN mode and NON SCREEN mode. In the SCREEN mode WIS_DEBUG divides the screen into three independently scrolled regions: * an OUTPUT region for input of debugger commands and output of debugger messages and diagnostics. * a USER region for input and output by the user's program. * a SOURCE region for displaying a source listing of the currently executing compilation unit. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 1 - 3 4. It has a powerful yet simple User Interface Command Language that supports: * Setting and resetting of breakpoints at user specified locations to suspend program execution. * Single step program execution. * Examination and modification of program variables. * Examination of program status, such as statement execution history and status of active program units, including tasks. * User defined "keyboard macros". * "Canned" input command files. * An extensive on-line help facility. 5. It is extensible: * User defined macros and canned input command files enable the user to extend and customize the command language. * Help files can be modified or extended to provide additional on-line help for "standard" user defined macros and canned command files or to provide project or system specific information. * Runtime terminal configuration with the ability to add support for virtually any type of SCREEN mode or NON SCREEN mode terminal Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 1 - 4 1.3 GENERAL LIMITATIONS WIS_DEBUG is a full-featured symbolic debugger and should contain all of the features you will need to debug your Ada programs. However, certain trade-offs have been made in order to avoid host and compiler dependencies and achieve the original design goal of portability. Many WIS_DEBUG limitations result from limitations and restrictions imposed by the Ada Language. All interfaces between the user's program and the Symbolic Debugger are accompilished through source instrumentation. As a result, the Symbolic Debugger actually becomes a part of the user's program when it is executed. Thus, it is subject to the same restrictions, limitations, and constraints as the user's program. For example, constants may be examined but they may not be modified. On the other hand, OUT mode parameters in subprograms may be modified but they may not be examined. Other Ada imposed limitations include such things as: variables may only be assigned values within the legal range constraints for the declared type; private types and limited private types are only visible within the body of the package in which they are declared. Limitations on the size of the user's program may or may not exist depending the system being used, the amount of memory available, and whether the system utilizes a virtual memory management scheme. Source instrumentation can cause the instrumented program to become very large. The amount of instrumentation inserted into the user's program is a function of many factors such as the number of type declarations, the number of objects declared, and the number of program units. In general, a large program with relatively few subprograms, type declarations, and variables will result in only a small percentage increase in size due to instrumentation. In contrast, a very small program with many small subprograms and many type and object declarations may increase several times in size. A complete list of all known limitations is presented in Appendix C. However, it uses terminology that may be unfamiliar to you until after you have read Chapters 3, 4, 5, and 6. Therefore, it is suggested that you read these chapters first to become familiar with each of various features of the debugger before reviewing the specific limitations presented in Appendix C. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 2 - 1 CHAPTER 2 HOW TO USE THIS MANUAL This User's Guide is intended to serve not only as a reference manual, but also as a tutorial. It is organized in the following manner. Chapters 3 through 6 present a step by step tutorial on the operation and use of WIS_DEBUG. As a first time user you should read each of these chapters thoroughly. Each feature of WIS_DEBUG is described in full detail in much the same order as you will use them in a typical debugging session. Numerous examples are used throughout to demonstrate the use of each command and feature. * Chapter 3 describes the Program Library, how to create it, and its importance to the operation of WIS_DEBUG. * Chapter 4 introduces you to the WIS_DEBUG Shell. In this chapter you will learn how to use the shell to instrument, compile, and link your Ada source programs. In addition, you will learn how use the shell to manage your Program Library. * Chapter 5 will show you how to execute the Symbolic Debugger with your instrumented program. It explains how to set the program library to enable the debugger to find the the files it will need during execution. It also explains how to create a log file to record information about the execution of your program. * Chapter 6 presents a detailed discussion of the Symbolic Debugger and each of its many commands and features. You will learn how to step through the execution of your program, monitor the status of active tasks and other program units, and examine and modify program variables to alter the flow of control. Appendices A, B and C are intended to serve as a reference manual. They provide valuable reference information that is organized in such a manner as to enable you to quickly locate and use each WIS_DEBUG feature. * Appendix A presents an alphabetical summary of each WIS_DEBUG Shell and Symbolic Debugger command. * Appendix B presents a summary of all diagnostic messages with information about how you should respond to each message. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 2 - 2 * Appendix C contains specific information about WIS_DEBUG limitations. Appendices D, E, and F provide valuable information pertinent to rehosting WIS_DEBUG to other systems or extending its capabilities. * Appendix D contains information about all known system and implementation dependencies. * Appendix E describes the Terminal Capabilities File and provides information necessary to add support for additional SCREEN type terminals. * Appendix F describes the format of the help files and provides information necessary to add and modify help topics. Appendix G contains a glossary of terms and their definitions within the context of this user's guide. Appendix H is an index and quick reference to all WIS_DEBUG commands. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 3 - 1 CHAPTER 3 THE SYMBOLIC DEBUGGER PROGRAM LIBRARY WIS_DEBUG uses the concept of a Program Library. Before using WIS_DEBUG it will be necessary to set up the Program Library as it will be used on your system. Depending on the Ada compiler system you are using, the WIS_DEBUG Program Library may or may not be common with other Ada program libraries being used by your compiler and linker. The WIS_DEBUG Program Library consists of two libraries, or directories: * the BASE Program Library * the CURRENT Program Library 3.1 THE BASE PROGRAM LIBRARY The Base Program Library is set up at the time WIS_DEBUG is installed. Instructions for creating the Base Program Library are contained in the Installation Guide included with this manual. The WIS_DEBUG Base Program Library contains certain static non-transient files that are common to all users of the debugger. * Help files used during execution * The Terminal Capabilities File that describes the attributes of each different type of terminal to be used in SCREEN mode with the debugger. 3.2 THE CURRENT PROGRAM LIBRARY The WIS_DEBUG Current Program Library contains dynamic information that is created and/or used by the Source Instrumenter and Symbolic Debugger during execution. Although it is not generally considered to be a good idea due to its dynamic nature, a Current Program Library may be shared by two or more users working on the same project. A single user may also work with more than one Current Program Library, at different times, for different projects. However, in general, you will have a single Current Program Library that is used only by you. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 3 - 2 WIS_DEBUG contains a built in Program Library Manager that creates and maintains numerous files in the Current Program Library during the instrumentation and debugging process. In addition, it maintains a catalog of all files created by WIS_DEBUG to enable it to locate information needed during execution. The Current Program Library, depending on the system you are using, will normally be a directory and must be created prior to using the debugger. It is highly recommended that the Current Program Library be created as a subdirectory of the directory in which your Ada source code will be located. It is also important that each user of the library have Read, Write, Execute and Delete access privileges. The following example shows how this might be done under DEC VAX VMS 4.1. -------------------------------------------------- EXAMPLE: -------------------------------------------------- $ CREATE/DIRECTORY DRA0:[USER.NOSC.CPL] <cr> $ SET PROTECTION=O:RWED DRA0:[USER.NOSC]CPL.DIR <cr> -------------------------------------------------- In the above example, it is assumed that the Ada source files to be instrumented and debugged will be located in the directory DRA0:[USER.NOSC]. The Current Program Library created is "DRA0:[USER.NOSC.CPL]". The name of your Current Program Library may be whatever you choose within the limitations of your system and the access privileges provided to you. When the Current Program Library has been created you may begin using it for program development and testing with WIS_DEBUG. Prior to each session with the debugger you should set your default working directory to the directory that contains your Ada source files to be instrumented and debugged. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 1 CHAPTER 4 USING THE WIS_DEBUG SHELL The WIS_DEBUG Shell is a "friendly" interface that enables you to instrument and debug your Ada programs with relative ease. Its primary functions include: 1. Program Library Management 2. Source Instrumentation 3. Compilation and linking 4. Execution of the Symbolic Debugger WIS_DEBUG contains an extensive on-line HELP facility to guide you through each of the various functions. In addition, it contains a SYSTEM interface that enables you to execute system commands and other programs, such as editors, without leaving the shell. Prior to invoking WIS_DEBUG you must set your working directory to the directory that contains the Ada source programs and subprograms to be instrumented and debugged. The method of invoking WIS_DEBUG will vary depending on the system being used. Examples presented here assume that the system is a DEC VAX running VMS 4.0 or later. WIS_DEBUG is invoked as follows: -------------------------------------------------- EXAMPLE: -------------------------------------------------- $ SET DEFAULT dddd:[working_directory] <cr> $ RUN WIS_DEBUG <cr> where dddd: is the logical device (e.g., DRA0) working_directory is the full path name of the directory that contains the Ada source programs to be instrumented and debugged -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 2 WIS_DEBUG will begin execution by announcing the program version number and a request for command input. -------------------------------------------------- EXAMPLE: -------------------------------------------------- $ RUN WIS_DEBUG <cr> SYMBOLIC DEBUGGER - VERSION 1.0 SOURCE INSTRUMENTER AND PROGRAM LIBRARY MANAGEMENT please enter desired option enter ? for a list of options available -------------------------------------------------- 4.1 THE "?" COMMAND (Show Command Options) Any time that the WIS_DEBUG Shell is at the command level you may list the available command options by entering a "?" followed by a carriage return. WIS_DEBUG command options will be displayed in the order that they will normally be executed. Thus, it can be used much as you would use a roadmap. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option ? <cr> WIS_DEBUG Options are: Library Management SEt_library(PROGRAM_LIBRARY); --> Set program library Delete(UNIT_NAME); --> Delete unit from pgm lib Execution Control SOurce_instrument; --> Instrument Ada source file Compile(SOURCE_FILE); --> Compile instrumented unit LINk(COMPILATION_UNIT); --> Link instrumented program Run(COMPILATION_UNIT); --> Run Debugger with instr pgm Quit; --> or Exit; --> Quit WIS_DBUG and Exit SYstem_command(COMMAND); --> Execute a system command Help --> Help for commands & features please enter desired option -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 3 4.2 THE SET_LIBRARY COMMAND If the current directory is not the WIS_DEBUG Program Library then the name of the program library must be entered prior to using the SOURCE_INSTRUMENT or DELETE commands. The name of the program library will be appended to the front of all file names by the source instrumenter. Therefore, it must be entered EXACTLY as required for the system you are using. An example of a valid program library name for the DEC VAX under VMS 4.0 is shown below. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option SET_LIBRARY( [.PGMLIB] ); <cr> lib = [.PGMLIB] please enter desired option -------------------------------------------------- 4.3 THE DELETE COMMAND The Program Library Manager that is built into the Source Instrumenter automatically adds newly instrumented units to the Program Library Catalog and updates the catalog when previously instrumented units are reinstrumented. However, instrumented compilation units that are no longer needed should be purged from the catalog using the WIS_DEBUG DELETE option. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option DELETE(OLD_PROGRAM); <cr> please enter desired option Where OLD_PROGRAM is the name of a compilation unit (WITHOUT EXTENSION) that is no longer needed. -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 4 4.4 THE SOURCE_INSTRUMENT COMMAND The Source Instrumenter inserts "action" routines and calls to the Symbolic Debugger into a copy of the user's original source program. Calls to the Symbolic Debugger are called breakpoints. Breakpoints provide information about the program as it runs and pass certain user requests back to the action routines for processing. The Source Instrumenter adds calls to inform the Symbolic Debugger: * of the names and types of units in the program. * when each unit is entered and exited. * when a statement in the source program has executed. * the value of program variables and constants Only the main program unit and program units that will be debugged must be instrumented. This includes package specifications that declare data types or objects that you want to be visible to the debugger. Compilation units should be instrumented in compilation order. To invoke the Source Instrumenter the user may enter a procedure call to the tool in Ada format including parameters. The procedure specification for the Source Instrumenter is as follows: procedure SOURCE_INSTRUMENT( INPUT_FILE : in FILE_NAME; SOURCE_LISTING_FILE : in FILE_NAME; INSTRUMENTED_SOURCE_FILE : in FILE_NAME ); where: INPUT_FILE is the user's Ada source file. SOURCE_LISTING_FILE is a pretty printed version of the user's source with breakpoints listed. INSTRUMENTED_SOURCE_FILE is the file containing the instrumented source. FILE_NAME is a string. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 5 -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option source_instrument(test.ada, test.lis, test.si); <cr> source_file = TEST.ADA source_listing = TEST.LIS instrumented_source = TEST.SI Do you wish to compile the instrumented source (Y/N)? Y <cr> please enter desired option -------------------------------------------------- As shown in the previous example, when instrumentation is completed the Source Instrumenter will ask you if you want to compile the instrumented source. If you respond with a "Y" then the Ada compiler will be invoked and execution of the shell will be suspended. When compilation is completed execution of the shell will be resumed. If you respond with "N" then the instrumented source will not be compiled. If you choose not to compile the unit after instrumentation then you may compile it at a later time using the COMPILE command. If the Source Instrumenter is invoked in Ada format, named association of parameters may be used as well as positional parameters. Standard Ada rules for postional and named association of parameters are used. Another method of invoking the Source Instrumenter is to enter the tool name and be prompted for each of the input parameters. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option SOURCE_INSTRUMENT; <cr> Enter Source_File => TEST.ADA <cr> Enter Source_Listing_File => TEST.LIS <cr> Enter Instrumented_Source_File => TEST.SI <cr> source_file = TEST.ADA source_listing = TEST.LIS instrumented_source = TEST.SI -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 6 The name ot the source file must always be entered. However, default file names may be used for the listing file and instrumented source file by entering a carriage return when prompted for their names. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option SOURCE_INSTRUMENT; <cr> Enter Source_File => TEST.ADA <cr> Enter Source_Listing_File => <cr> Enter Instrumented_Source_File => <cr> source_file = TEST.ADA source_listing = SD_TEMP.OUT instrumented_source = TEST.INS -------------------------------------------------- Instrumenting Package Specifications In order to trace variables declared in a package specification or variables whose type is defined in a package specification, the package specification must be instrumented. When a package specification is instrumented, several files will be created in the program library that contain the information the Symbolic Debugger will need from the package specification. When a unit is instrumented that "withs" a package, the tracing information for the package (contained in files created by the souce instrumenter) will be used to construct tracing routines for the variables and types contained in the package specification. Therefore, compilation units should be instrumented in compilation order to insure that all tracing information is available. A library unit package specification MUST be instrumented if ANY of the following conditions is TRUE: 1. It contains type definitions used in any other units that will be instrumented, or 2. It contains a generic specification whose body will be instrumented, or 3. It declares objects that you want to have visible during debugging. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 7 If the package is not generic and if it does not have any generic declarations in it, instrumenting will NOT alter the package specification, therefore you may not need to recompile it. You will be given the option of whether to include the package specification in the instrumented source file. If you do, when you compile the instrumented source file, you will also compile your package specification. YOU WILL HAVE TO RECOMPILE THE CORRESPONDING PACKAGE BODY AND ALL DEPENDENT UNITS. If you do not include the package specifiction in the source file, the package specification must be compiled before compiling the instrumented source file. If you do include it, you can compile both your package specification and the instrumented source file at the same time. If the package is a generic package declaration, its specification will be altered. You will not be given the option not to include the package specification in the instrumented source file. YOU WILL HAVE TO RECOMPILE THE CORRESPONDING PACKAGE BODY AND ALL DEPENDENT UNITS. If the package specification contains a generic declaration whose body you want to instrument, you must include the package specification in the instrumented source file when given the option. Your package specification will be altered, and YOU WILL HAVE TO RECOMPILE THE CORRESPONDING PACKAGE BODY AND ALL DEPENDENT UNITS. If the Ada source file you are instrumenting contains a package specification then the Source Instrumenter will ask you whether or not you want the package specification included in the instrumented source. -------------------------------------------------- EXAMPLE: -------------------------------------------------- Instrumenting the package specification for TEST Do you want this package specification included in the instrumented source? Y/N/H or ? for Help -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 8 If you respond with "H" or "?" then a short tutorial will be displayed to help you decide whether or not you should include the package specification in your instrumented source. If you respond with "Y" for YES then the package specification will be included with your instrumented source. If you respond with "N" for NO then it will not be included with your instrumented source. 4.5 THE COMPILE COMMAND After a unit has been instrumented by the Source Instrumenter it must be compiled using your Ada compiler. If you did not select the automatic compilation option after source instrumentation then you may use the COMPILE command to avoid exiting the shell. The format of the COMPILE command is: COMPILE(SOURCE_FILE); where SOURCE_FILE is the INSTRUMENTED_SOURCE_FILE created by the Source Instrumenter. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option COMPILE(TEST.INS); <cr> please enter desired option -------------------------------------------------- Execution of the WIS_DEBUG shell will be suspended until the compilation is complete. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 9 4.6 THE LINK COMMAND When all instrumented and uninstrumented compilation units have been compiled, you must link the main program with the run time Symbolic Debugger. This may be done without exiting the WIS_DEBUG shell by using the LINK command. The executeable load module will be created in the current working directory. The format of the command is: LINK(COMPILATION_UNIT); where COMPILATION_UNIT is the name of the main program unit. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option LINK(TEST); <cr> %ACS-I-CL_LINKING, Invoking the VAX/VMS Linker please enter desired option -------------------------------------------------- 4.7 THE RUN COMMAND When all program units that are to be debugged have been instrumented and compiled and the main program has been linked, you are ready to begin debugging. The RUN command enables you to execute the Symbolic Debugger with your instrumented program. The format of the RUN command is: RUN(COMPILATION_UNIT); where COMPILATION_UNIT is the name of the main program unit. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option RUN(TEST); <cr> -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 10 The WIS_DEBUG shell will be suspended during execution of the Symbolic Debugger . When the debugger terminates, execution of the shell will be resumed. A detailed discussion on using the Symbolic Debugger with your instrumented program is presented in Chapters 5 and 6. 4.8 THE SYSTEM_COMMAND COMMAND You may frequently find it necessary to execute a system command or another program during a session with WIS_DEBUG. SYSTEM_COMMAND enables you to do this without having to exit the shell. This feature can be quite useful for such things as editing your source programs, file management, submitting jobs to a batch stream, or printing Source Instrumenter listings for use during the debugging session. The format of the SYSTEM command is: SYSTEM_COMMAND(COMMAND); where COMMAND is any valid command that you may enter at your system command level. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option SYSTEM_COMMAND(DIR); <cr> Directory USER$DEVICE:[USER.NOSC.TEST] PGMLIB.DIR;1 PKG1.PKG;2 SP.ADA;4 TEST.ADA;16 TEST.EXE;2 TEST.EXE;1 WP1.ADA;3 WP1.ADA;2 WP1.ADA;1 Total of 9 files. -------------------------------------------------- However, you should be aware that it may have certain limitations depending on the system you are using. For example, under VAX VMS a new process is "spawned" to execute the command. When the spawned process is completed, any changes that have been made to the environment will be restored to their state prior to execution of the SYSTEM command. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 11 -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option SY(SET DEFAULT ^ <cr> please enter desired option -------------------------------------------------- In the previous VAX VMS example, the default working directory is changed to the parent of the current default working directory. But, when the process that is spawned to execute the SET DEFAULT command has been completed, the default working directory is restored to its state prior to execution of the SYSTEM command. Therefore, the command SY(SET_DEFAULT ^ has no effect. 4.9 THE HELP COMMAND The WIS_DEBUG Shell contains an extensive on-line help facility to assist you with each of the many Shell commands and special features. The format of the HELP command is as follows: HELP; HELP(topic); The HELP command may be used to obtain assistance at any time WIS_DEBUG is at the command level. Information about Shell commands and features is extracted from the file WISDEBUG.HLP that must be located in the Base Program Library. Refer to Chapter 3 for information about setting up a program library. If no topic or an invalid topic is specified a menu of all available HELP topics will be displayed. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 12 -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option HELP; <cr> Topics available are: COMPILE DELETE EXIT HELP LINK OPTIONS PROGRAM_LIBRARY QUIT RUN SOURCE_INSTRUMENT SET_LIBRARY SYSTEM_COMMANDS Enter "HELP(topic);" for more information please enter desired option -------------------------------------------------- If an ambiguous topic is specified then an error message will be issued and a list of possible topics and their minimum acceptable abbreviations will be displayed. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option HELP(S <cr> The topic S is ambiguous. Possiblities are: Topic: SET_LIBRARY Abbreviation: SE Topic: SOURCE_INSTRUMENT Abbreviation: SO Topic: SYSTEM Abbreviation: SY Enter "HELP(topic);" for more information please enter desired option -------------------------------------------------- If a valid topic is specified then information about that topic will be displayed. Information about each topic is displayed in segments. At the end of each segment the user is given the opportunity to terminate HELP and return to the debugger command level by entering "Q", or to continue displaying more information about the topic by entering a carriage return until all information has been displayed. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 13 -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option HELP(COMPILE); <cr> Command: COMPILE - Compile an instrumented Ada compilation unit Abbreviation: C Format: COMPILE(SOURCE_FILE) where SOURCE_FILE is the name of of the source file to be compiled Enter RETURN for more information or "Q" to quit: >> <cr> Invokes the Ada compiler from within the WIS_DEBUG Shell. The COMPILE command may be used to compile an instrumented Ada source file without exiting the shell. Enter RETURN for examples or "Q" to quit: >> <cr> EXAMPLES: 1) COMPILE(MY_SOURCE.INS); 2) COMPILE(MY_SOURCE.INS 3) C(MY_SOURCE.INS please enter desired option -------------------------------------------------- 4.10 THE QUIT AND EXIT COMMANDS The QUIT and EXIT commands have the same meaning. When either command is entered, execution of the WIS_DEBUG shell is terminated and control is returned to the system command level. A minimum abbreviation of two characters are required to reduce the possibility of accidental termination. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) QUIT; <cr> 2) EXIT; <cr> 3) QU <cr> 4) EX <cr> -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 14 4.11 SAMPLE SESSION WITH WIS_DEBUG Following is a sample session with the WIS_DEBUG shell. $ SET DEFAULT [USER.NOSC.TEST] <cr> $ RUN WIS_DEBUG <cr> SYMBOLIC DEBUGGER - VERSION 1.0 SOURCE INSTRUMENTER AND PROGRAM LIBRARY MANAGEMENT please enter desired option enter ? for a list of options available ? <cr> WIS_DEBUG Options are: Library Management SEt_library(PROGRAM_LIBRARY); --> Set program library Delete(UNIT_NAME); --> Delete unit from pgm lib Execution Control SOurce_instrument; --> Instrument Ada source file Compile(SOURCE_FILE); --> Compile instrumented unit LINk(COMPILATION_UNIT); --> Link instrumented program Run(COMPILATION_UNIT); --> Run Debugger with instr pgm QUit; --> or EXit; --> Quit WIS_DBUG and Exit SYstem_command(COMMAND); --> Execute a system command Help --> Help for commands & features please enter desired option SET_LIBRARY( [.PGMLIB] ); <cr> lib = [.PGMLIB] please enter desired option DELETE(OLD_PROGRAM); <cr> please enter desired option SYSTEM_COMMAND(DIR); <cr> Directory USER$DEVICE:[USER.NOSC.TEST] PGMLIB.DIR;1 PKG1.PKG;2 SP.ADA;4 TEST.ADA;16 TEST.EXE;2 TEST.EXE;1 WP1.ADA;3 WP1.ADA;2 WP1.ADA;1 Total of 9 files. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 4 - 15 SAMPLE WIS_DEBUG SESSION (Continued) please enter desired option source_instrument(test.ada, test.lis, test.si); <cr> source_file = TEST.ADA source_listing = TEST.LIS instrumented_source = TEST.SI Do you wish to compile the instrumented source (Y/N)? Y <cr> please enter desired option LINK(TEST); <cr> %ACS-I-CL_LINKING, Invoking the VAX/VMS Linker please enter desired option SYSTEM_COMMAND(PRINT TEST.LIS); <cr> please enter desired option RUN(TEST); <cr> ------------------------------------------------ | The instrumented program is executed | | with the Symbolic Debugger here. | ------------------------------------------------ Please enter desired option: QUIT; <cr> $ Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 5 - 1 CHAPTER 5 EXECUTING THE DEBUGGER WITH AN INSTRUMENTED PROGRAM The compilation and linking process combines the Symbolic Debugger with the instrumented program. When linking is completed, the target Ada program is ready to be executed and debugged. The user interface and method of executing the target program is not altered by the instrumentation process. Therefore, you may either follow the normal procedures for executing the target program on the host computer system being used for program development or you may execute it directly from the WIS_DEBUG shell as discussed in chapter 4. -------------------------------------------------- EXAMPLE: -------------------------------------------------- please enter desired option run(test); <cr> SYMBOLIC DEBUGGER VERSION 1.0 -------------------------------------------------- When the first program unit is entered, the Symbolic Debugger will suspend execution of the target program and prompt you for the certain information about options that will be used during the debugging session. 5.1 CREATING A LOG FILE If you desire, the Symbolic Debugger will create a log file and record certain information about the execution of the target Ada program. After the debugging session has ended the log file may be processed with the Ada Path Analyzer to generate a statement by statement trace of the target program's execution or to obtain a summary report of all paths within the target program that were executed. When the target program begins execution, you will be prompted as to whether or not you want to create a log file of the debugging session. The default is no log file. If no log file is desired then you may respond with a carriage return to accept the default or with an "N" followed by a carriage return. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 5 - 2 Note that in the following examples the Symbolic Debugger always precedes the prompt ">>" with the default response shown in brackets "[ ]". The default may be accepted by entering a carriage return. -------------------------------------------------- EXAMPLE: -------------------------------------------------- SYMBOLIC DEBUGGER VERSION 1.0 Create a log file (Y or N)? [N] >> <cr> -------------------------------------------------- If a log file is desired then you should respond with "Y". If "Y" is entered the Symbolic debugger will prompt you for a log file name and a unique test id to be recorded in the log file. The default log file name is SYMDEBUG.LOG. The default Test ID is "SYMBOLIC DEBUGGER ANALYSIS". If you wish to use another log file name then you should respond with a legal file name for the computer you are using. The log file will be created in the current working directory. If you want the log file to be created in another directory then you must enter the full pathname of the file. If you wish to specify a Test ID that is different from the default Test ID then you should respond with a new test ID when prompted. -------------------------------------------------- EXAMPLE: -------------------------------------------------- SYMBOLIC DEBUGGER VERSION 1.0 Create a log file (Y or N)? [N] >> y <cr> Enter log file name or RETURN for default [SYMDEBUG.LOG] >> test.log <cr> Enter a Test ID or RETURN for default [SYMBOLIC DEBUGGER ANALYSIS] >> Test 1234 <cr> -------------------------------------------------- If the file already exists, then you will be asked if you want to enter a new filename or overwrite the existing file. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 5 - 3 5.2 SETTING THE PROGRAM LIBRARY During execution it will be necessary for the symbolic debugger to locate certain files files created by the Source Instrumenter. These files are maintained in the Symbolic Debugger Current Program Library. If the instrumented program is executed from the WIS_DEBUG Shell then the name of the Current Program Library will be passed to the debugger. However, if the instrumented program is not executed from the WIS_DEBUG Shell or if the debugger cannot find the files it will need during execution, a warning message will be issued and you will be prompted to enter a new Current Program Library Name. You should respond with a complete directory name that is valid for the computer and operating system you are using for program development. The Symbolic Debugger will continue prompting until a valid Program Library name has been entered. When a valid Program Library name has been entered, the Symbolic Debugger will respond by displaying the breakpoint at which execution has been suspended followed by the debugger command prompt ">>". -------------------------------------------------- EXAMPLE: -------------------------------------------------- Program library catalog not found! Enter a new program library name or RETURN to continue [Current Directory] >> [user.nosc.pgmlib] <cr> Program library catalog not found! Enter a new program library name or RETURN to continue [USER.NOSC.PGMLIB] >> [user.nosc.test.pgmlib] <cr> Begin execution at procedure TEST << 23 >> >> -------------------------------------------------- You may continue execution of the debugging session without specifying a valid program library. However, if you do so the Symbolic Debugger will be unable to locate and display program listings in the LISTING region of the terminal if you use the SCREEN mode capability. You are now ready to begin debugging your Ada program. Chapter 6 contains a detailed discussion of using each of the Symbolic Debugger's commands and features you will need during the debugging session. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 1 CHAPTER 6 DEBUGGING AN ADA PROGRAM The User Interface Command Language is comprised of five categories of commands: 1. Special debugger commands 2. Terminal control commands 3. Program status commands 4. Execution control commands 5. Program variable commands This chapter describes the use of each of the Symbolic Debugger features and commands. 6.1 UNDERSTANDING BREAKPOINTS Before discussing the many Symbolic Debugger commands and features, it is important that you have a good understanding of the term "breakpoint" as used within the context of this user's guide. When the Source_Instrumenter processes your Ada source program, it inserts "hooks" at various points that transfer control at runtime to the Symbolic Debugger. These "hooks" are called "breakpoints". When a breakpoint is encountered it is executed whether it is "on" or "off". If the breakpoint is "off" then control is returned to the instrumented program to execute the statement with which the breakpoint is associated. If the breakpoint is "on" then execution of the program is temporarily suspended and control is passed to a user interface module where you will be able to enter any of the many commands described in this chapter. When you are ready to resume execution, control will be returned to your program and the statement with which the breakpoint is associated will be executed. In general, a breakpoint is inserted: 1) after entry to each program unit 2) before each executeable statement 3) before each exit from a program unit Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 2 There are a few exceptions to this where it is not allowed by the syntax of the Ada language. For example, the DELAY statement in a delay alternative of a SELECT statement may not be preceded by any other statements. In this situation, the breakpoint is inserted immediately "after" the delay statement. Breakpoint numbers are assigned by the Source Instrumenter in ascending order beginning with 1 for each compilation unit. One of the outputs created by the Source Instrumenter is a "pretty printed" version of your original source program with all breakpoint numbers listed. Numerous Symbolic Debugger commands deal with breakpoints. During execution of your instrumented program with the Symbolic Debugger it will be necessary for you to know the breakpoint numbers assigned to statements at which you wish to suspend the program's execution. If you are debugging in SCREEN mode using a screen type terminal that is supported by the Symbolic Debugger then the listing files for the currently executing compilation unit will be displayed for you at your terminal. However, if you are using a tty type terminal or will need to set breakpoints in instrumented compilation units other than the one that is currently executing then you may find it necessary to obtain a printed listing of the SOURCE_LISTING_FILE produced by the Source Instrumenter prior to beginning a session with the debugger. 6.2 SPECIAL DEBUGGER FEATURES AND COMMANDS The Ada Symbolic Debugger contains numerous special features and commands that are designed to make the tool simple and easy to use. This section presents information about each of these special features and commands. The topics that are discussed in this section are: Command Conventions Keyboard Definitions The Terminal Capabilities File The HELP Command The CANFILE Command The DEFINE Command The SHOW_DEFINE Command The SET_LIBRARY Command Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 3 6.2.1 Command Conventions The User Interface Command Language supports both full Ada syntax and an abbreviated form of each command. In general, each command has one of the following formats: COMMAND; COMMAND(ARGUMENT); COMMAND(ARGUMENT, ARGUMENT); An exception to this format is the SET_VARIABLE command discussed in section 6.6.2. Syntax Rules 1. Commands may be entered using full Ada syntax rules. Named parameter association is allowed but, once used, must be used for all subsequent parameters in the same command. If you use named parameter association then you must use the parameter names given in the "pseudo" package specification for debugger commands presented in Appendix A. 2. Case is not significant. 3. Blanks at the beginning and end of commands and arguments and at the end of the command line are ignored. Blanks embedded within commands and arguments are not allowed. 4. Only one command per command line is allowed. 5. Semicolons and trailing parentheses are optional. 6. Commands may be abbreviated to the fewest number of characters that uniquely identify them. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 4 6.2.2 Keyboard Definitions The Symbolic Debugger has predefined keyboard macros to simplify the use of some frequently used commands and features. Predefined keyboard macros are only available when the debugger is in SCREEN mode. These macros are: KEY DEFINITION ------- ------------------------------------------ <PF1> Toggles INSERT mode ON/OFF <PF2> SCROLL_UP; <cr> <PF3> SCROLL_DOWN; <cr> <PF4> Erase end of line <ENTER> STEP; <cr> <UP ARROW> Recalls previous commands. The last 10 <DN ARROW> commands are saved and may be edited prior to being executed. 6.2.3 The Terminal Capabilities File The Symbolic Debugger supports both TTY and full screen type terminals. If you are using a full screen type terminal and the attributes of the terminal have been defined in the Terminal Capabilities File (TCF.DAT), then you may use the SCREEN mode debugging feature of the Symbolic Debugger. If you are using a screen type terminal but it is not currently defined in the Terminal Capabilities File then you must add the attributes of the terminal to TCF.DAT if you desire to use the terminal in the screen mode. The Terminal Capabilities File must be located in your Base Program Library in order for the Symbolic Debugger to be able to locate and use it. Refer to Chapter 3 of this user's guide for information on setting up a program library. The format of the Terminal Capabilities File and information about adding support for additional terminals can be found in Appendix E. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 5 6.2.4 The HELP Command The Symbolic Debugger contains an extensive on-line help facility to assist the user with the many debugger commands and special features. It is identical to the WIS_DEBUG Shell HELP command with the exception that it provides help for debugger commands and features rather than Shell commands and features. The format of the HELP command is as follows: HELP; HELP(topic); The HELP command can be entered at any time the debugger is at the command level to obtain assistance. Information about debugger commands and features is extracted from the file SYMDEBUG.HLP that must be located in the Base Program Library. Refer to Chapter 3 for information about setting up a program library. If no topic or an invalid topic is specified, a menu of all available HELP topics will be displayed. -------------------------------------------------- EXAMPLE: -------------------------------------------------- >> HELP; <cr> Topics available are: ANNOUNCE CANFILE CLEAR_BREAKPOINT DEFINE DISPLAY_UNITS GO HELP KEYPAD PUT_VARIABLE QUIT RECREATE RESHOW SCREEN SCROLL_DOWN SCROLL_UP SET_BREAKPOINT SET_OUTPUT SET_SOURCE SET_VARIABLE SHOW_BREAKPOINTS SHOW_HISTORY SILENT STEP TERMINALS Enter "HELP(topic);" for more information >> -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 6 If an ambiguous topic is specified, an error message will be issued and a list of possible topics and their minimum acceptable abbreviations will be displayed. -------------------------------------------------- EXAMPLE: -------------------------------------------------- >> HELP(SCR); <cr> The topic SCR is ambiguous. Possiblities are: Topic: SCREEN Abbreviation: SCRE Topic: SCROLL_DOWN Abbreviation: SCROLL_D Topic: SCROLL_UP Abbreviation: SCROLL_U Enter "HELP(topic);" for more information >> -------------------------------------------------- If a valid topic is specified then information about that topic will be displayed. Information about each topic is displayed in segments. At the end of each segment you will be given the opportunity to terminate HELP and return to the debugger command level by entering "Q", or to continue displaying more information about the topic by entering a carriage return until all information has been displayed. If the topic is a User Interface Command Language command then the information displayed will include the minimum acceptable abbreviation for the command and the applicable keyboard macro, if any. -------------------------------------------------- EXAMPLE: -------------------------------------------------- >> HELP(A); <cr> Command: ANNOUNCE - Announce messages at breakpoints and step points Abbreviation: A Keyboard Macro: None Enter RETURN for more information or "Q" to quit: >> <cr> Syntax: ANNOUNCE; --> or A ANNOUNCE(BREAK); --> or A(BREAK ANNOUNCE(STEP); --> or A(STEP Enter RETURN for examples or "Q" to quit: >> <cr> EXAMPLES: 1) >> ANNOUNCE(STEP); --> Turns on STEP messages 2) >> A(BREAK --> Turns on BREAKPOINT messages 3) >> A; --> Turns on both STEP & BREAKPOINT messages >> -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 7 Information about special debugger features is displayed in a similar manner except that there is no applicable command abbreviation or keyboard macro. -------------------------------------------------- EXAMPLE: -------------------------------------------------- >> HELP(TERMINALS); <cr> The following display terminals are supported in SCREEN mode: TV970 VI50 VT52 VT100 Refer to the Symbolic Debugger User's Guide for information about adding support for new terminals. >> -------------------------------------------------- 6.2.5 The CANFILE Command A useful feature of the Symbolic Debugger is its ability to accept input commands from a "Canned Command File" (CANFILE). A CANFILE is a text file that contains Symbolic Debugger commands in exactly the same format as they would be entered through the keyboard at the command prompt. When all commands in the CANFILE have been executed, control will be returned to the user's console. The following example shows a typical CANFILE that may be used to perform an initial setup sequence. -------------------------------------------------- EXAMPLE: Sample CANFILE -------------------------------------------------- DEFINE( &1, SET_BREAKPOINT( ); DEFINE( &2, SHOW_HISTORY; ); DEFINE( &3, SHOW_BREAKPOINTS ); DEFINE( &9, DEFINE( ); SILENT(STEP); SCREEN(VT100); DISPLAY_UNITS; -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 8 There is no limit to the number of commands that can be included in a CANFILE. However, CANFILES may not be nested (i.e., one CANFILE may not invoke another CANFILE). A CANFILE may be invoked at any time the debugger is at the command prompt ">>" by entering CANFILE command and the name of the command file. -------------------------------------------------- EXAMPLE: -------------------------------------------------- >> CANFILE(SETUP.CAN); <cr> -------------------------------------------------- 6.2.6 The DEFINE Command A useful feature of the Symbolic Debugger is the ability to define and execute user defined command strings. New commands may be created in the form of keyboard macros to simplify the use of frequently used commands, lengthy program unit names, or tailor it to your own personal likes and dislikes. The DEFINE command is used to define new keyboard macros. Up to 9 new keyboard macros may be defined. The format of the DEFINE command is as follows: DEFINE( &n, SOME_STRING ); where: n is an integer in the range 1 .. 9 SOME_STRING is a string of characters. Imbedded blanks are allowed. Leading and trailing blanks are ignored. Quote characters (") should not be used to delimit the string. They are allowed but will be interpreted as part of the string. The value of SOME_STRING is assigned to the macro "&n". -------------------------------------------------- EXAMPLES: -------------------------------------------------- >> DEFINE( &1, SET_BREAKPOINT( ); <cr> >> DEFINE( &2, SHOW_HISTORY; ); <cr> >> DEFINE( &4, LONG_PACKAGE_NAME.LONG_PROC_NAME ); <cr> >> DEFINE( &5, LONG_FUNCTION_NAME ); <cr> -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 9 Once a keyboard macro has been defined it may be used anywhere on the command line when the debugger is in the command mode. It may be used to execute an entire command, or it may be embedded within a command. -------------------------------------------------- EXAMPLES: -------------------------------------------------- Using the DEFINEs given in the previous example: >> &2 <cr> will execute the SHOW_HISTORY command >> &1&4.&5 <cr> will set the first breakpoint in the program unit LONG_PACKAGE_NAME.LONG_PROC_NAME.LONG_FUNCTION_NAME >> C(&4 <cr> will clear all breakpoints in the procedure LONG_PACKAGE_NAME.LONG_PROC_NAME -------------------------------------------------- Keyboard macros defined by the DEFINE command may be redefined at any time. If you find that you are defining the same keyboard macros during each debugging session you may find it useful to store the definitions in a CANFILE, such as KEYDEFS.CAN, that you execute upon start up. Refer to section 6.2.3 for information about creating and executing a CANFILE. 6.2.7 The SHOW_DEFINE Command If you use the DEFINE command to define new keyboard macros, their definitions may be displayed at any time by using the SHOW_DEFINE command. Only keys that have been defined will be displayed. -------------------------------------------------- EXAMPLE: -------------------------------------------------- >> SHOW_DEFINE; <cr> &1 = SET_BREAKPOINT( &2 = SHOW_HISTORY; &4 = LONG_PACKAGE_NAME.LONG_PROC_NAME &5 = LONG_FUNCTION_NAME >> -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 10 6.2.7 The SET_LIBRARY Command The SET_LIBRARY command is identical to the SET_LIBRARY command in the WIS_DEBUG shell. It is used to set or change the Current Program Library being used by the debugger. If you should find that you incorrectly specified the wrong Program Library name to the WIS_DEBUG shell or during debugger initialization, then you may specify a new Program Library name at any time the debugger is at the command prompt. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> SET_LIBRARY( DRAO:[USER.NOSC.PGMLIB] ); <cr> Logical device (DRA0:) is required if not on default logical device 2) >> SET_LIBRARY( [USER.NOSC.PGMLIB] ) <cr> Full directory path name required if not in current default working directory 3) >> SET_L( [.PGMLIB] <cr> Program Library is set to the PGMLIB subdirectory of the current default working directory -------------------------------------------------- 6.3 CONTROLLING TERMINAL OUTPUT If you are using a screen type terminal and the attributes of the terminal have been defined in the Terminal Capabilities File (TCF.DAT), then you may use the SCREEN mode debugging capabilities of the Symbolic Debugger. If you are using a screen type terminal that is not supported by the Terminal Capabilities File refer to Appendix E for information about how to add support for additional terminals. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 11 Terminal Control Commands are used to control the format of debugger and program input and output to the user's terminal while in the screen mode. Commands in this category are: SCREEN SET_SOURCE SET_OUTPUT SCROLL_UP SCROLL_DOWN RESHOW RECREATE This section describes the use of each of the symbolic debugger's Terminal Control Commands. 6.3.1 The SCREEN Command The SCREEN command changes the debugger from NON SCREEN mode (tty) to SCREEN mode. The terminal specified must be a previously defined screen mode terminal in the Terminal Capabilities File (TCF.DAT). The format of the command is: SCREEN(term_type); -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> SCREEN(VT100); <cr> 2) >> SCREEN(TV970) <cr> 3) >> SCREEN(VT52 <cr> 4) >> SCR(VI50 <cr> -------------------------------------------------- IMPORTANT NOTE: Once you have entered SCREEN mode, you may not return to NON SCREEN mode or redefine the terminal attributes for a different terminal. All attributes will be reset to TTY mode upon normal termination of the debugger. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 12 6.3.2 The SET_SOURCE Command When the Symbolic Debugger is in SCREEN mode the terminal display is divided into three regions: SOURCE, OUTPUT, and USER. The SOURCE region of the terminal display is used to display the current location of the debugger in the user's source listing when execution is suspended at a breakpoint. The default size of the SOURCE region is 8 lines. The SET_SOURCE command can be used to change the size of the SOURCE region. The format of the SET_SOURCE command is: SET_SOURCE(size); where "size" is some positive integer. When setting the size of the SOURCE region the user should take the following into account: 1) The total number of lines that the terminal can display is defined in the Terminal Capabilities File. 2) Both the SOURCE and OUTPUT regions may be set by the SET_SOURCE and SET_OUTPUT commands, respectively. The USER region gets whatever is left over and cannot be less than 1 line. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> SET_SOURCE(10); <cr> Sets the SOURCE display region to 10 lines 2) >> SET_S(9 <cr> Sets the SOURCE display region to 9 lines -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 13 6.3.3 The SET_OUTPUT Command When the Symbolic Debugger is in SCREEN mode the terminal display is divided into three regions: SOURCE, OUTPUT, and USER. The OUTPUT region of the terminal display is used for input of debugger commands and output of debugger messages and diagnostics. The default size of the OUTPUT region is 6 lines. The SET_OUTPUT command can be used to change the size of the OUTPUT region. The format of the SET_OUTPUT command is: SET_OUTPUT(size); where "size" is some positive integer. When setting the size of the OUTPUT region the user should take the following into account: 1) The total number of lines that the terminal can display is defined in the Terminal Capabilities File. 2) Both the SOURCE and OUTPUT regions may be set by the SET_SOURCE and SET_OUTPUT commands, respectively. The USER region gets whatever is left over and cannot be less than 1 line. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> SET_OUTPUT(10); <cr> Sets the OUTPUT display region to 10 lines 2) >> SET_O(5 <cr> Sets the OUTPUT display region to 5 lines -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 14 6.3.4 The SCROLL_UP Command When the Symbolic debugger is in SCREEN mode, the SCROLL_UP command scrolls the SOURCE display region "window" up one "page" in the current listing file. A "page" is equal to the current size of the SOURCE display region. The default size of the SOURCE display region is 8 lines but may be changed by the SET_SOURCE command. The predefined keyboard macro PF2 (function key 2) may be used to execute the SCROLL_UP command if it is supported by the terminal you are using. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> SCROLL_UP; <cr> --> Scrolls up 1 page 2) >> SCROLL_UP <cr> --> Scrolls up 1 page 3) >> SCROLL_U; <cr> --> Scrolls up 1 page 4) >> SCROLL_U <cr> --> Scrolls up 1 page 5) >> <PF2> --> Scrolls up 1 page -------------------------------------------------- 6.3.5 The SCROLL_DOWN Command When the Symbolic debugger is in SCREEN mode, the SCROLL_DOWN command scrolls the SOURCE display region "window" down one "page" in the current listing file. A "page" is equal to the current size of the SOURCE display region. The default size of the SOURCE display region is 8 lines but may be changed by the SET_SOURCE command. The predefined keyboard macro PF3 (function key 3) may be used to execute the SCROLL_DOWN command if it is supported by the terminal being used. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> SCROLL_DOWN; <cr> --> Scrolls down 1 page 2) >> SCROLL_DO <cr> --> Scrolls down 1 page 3) >> SCROLL_D; <cr> --> Scrolls down 1 page 4) >> SCROLL_D <cr> --> Scrolls down 1 page 5) >> <PF3> --> Scrolls down 1 page -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 15 6.3.6 The RESHOW Command The RESHOW command rewrites the terminal display when the debugger is in screen mode. In a multi-user time sharing environment situations may occur that affect the display when in screen mode such as messages from other users, batch job completion messages from the system, etc. It is not within the capability of the debugger to inhibit such situations. However, when this happens the screen display can normally be regenerated using the RESHOW command with no loss of information. If the situation cannot be corrected by using the RESHOW command, then the RECREATE command may be used. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> RESHOW; <cr> 2) >> RESH; <cr> 3) >> RES <cr> -------------------------------------------------- 6.3.7 The RECREATE Command The RECREATE command recreates the terminal display when the debugger is in screen mode. Each display region (OUTPUT, SOURCE, USER) is recreated separately. The RECREATE command must be used when certain extreme situations occur that directly affect the screen mode of the terminal, such as user output sending a control or escape sequence to the terminal that takes it out of screen mode. Situations such as this may require that the terminal be placed into a "local" mode, reset, and then placed back "on- line". The screen display must then be recreated using the RECREATE command. The OUTPUT region of the display will be restored to the most recent command, the SOURCE region will be restored to the current listing file and breakpoint, and the USER region will be cleared to avoid duplication of the condition that caused the problem. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> RECREATE; <cr> 2) >> RECRE; <cr> 3) >> REC <cr> -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 16 6.4 DISPLAYING PROGRAM AND DEBUGGER STATUS Status Commands display information about the state of the program under test and the debugger. Commands in this category are: SILENT ANNOUNCE SHOW_BREAKPOINT SHOW_HISTORY DISPLAY_UNITS This section describes the use of each of the symbolic debugger's Status Commands. 6.4.1 The SILENT Command The Symbolic Debugger displays messages at the user's console whenever program execution is suspended at a step or breakpoint. The SILENT command turns off Symbolic Debugger messages at breakpoints and at step points. Breakpoint messages and step messages are of the following form: Break at: PGM_UNIT_NAME << BKPT_NUMBER >> Step to: PGM_UNIT_NAME << BKPT_NUMBER >> The default for BREAK messages and STEP messages is "on". If messages are turned "off" by the SILENT command, they may be turned back "on" by using the ANNOUNCE command. The format of the SILENT command is: SILENT; SILENT(BREAK); SILENT(STEP); -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> SILENT(STEP); <cr> Silences STEP messages 2) >> SILENT(BREAK) <cr> Silences BREAK messages 3) >> SI <cr> Silences both STEP and BREAK messages -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 17 6.4.2 The ANNOUNCE Command The Symbolic Debugger displays messages at the user's console whenever program execution is suspended at a step or breakpoint. The ANNOUNCE command turns on Symbolic Debugger messages at breakpoints and at step points. Breakpoint messages and step messages are of the following form: Break at: PGM_UNIT_NAME << BKPT_NUMBER >> Step to: PGM_UNIT_NAME << BKPT_NUMBER >> The default for BREAK messages and STEP messages is "on". If messages are turned "off" by the SILENT command, they may be turned back "on" by using the ANNOUNCE command. The format of the ANNOUNCE command is: ANNOUNCE; ANNOUNCE(BREAK); ANNOUNCE(STEP); -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> ANNOUNCE(STEP); <cr> Turns on STEP messages 2) >> ANNOUNCE(BREAK) <cr> Turns on BREAK messages 3) >> SI <cr> Turns on both STEP and BREAK messages -------------------------------------------------- 6.4.3 The SHOW_BREAKPOINTS Command The SHOW_BREAKPOINTS command displays breakpoints that have been set to "on" at the user's console. If no compilation unit name is specified then all breakpoints in all compilation units are displayed. If a compilation unit name is specified then only breakpoints in the specified compilation unit are displayed. The format of the SHOW_BREAKPOINTS command is: SHOW_BREAKPOINTS; SHOW_BREAKPOINTS(comp_unit); Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 18 -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> SHOW_BREAKPOINTS; <cr> Will display all active breakpoints in all compilation units 2) >> SHOW_BREAKPOINTS(SCHEDULER); <cr> Will display all active breakpoints in the compilation unit SCHEDULER 3) >> SHOW_BREAK(MAILBOX <cr> Will display all active breakpoints in the compilation unit MAILBOX 4) >> SHOW_B <cr> Will display all active breakpoints in all compilation units -------------------------------------------------- 6.4.4 The SHOW_HISTORY Command The SHOW_HISTORY command displays a history of the most recently executed breakpoints at the user's console. The maximum number of breakpoints that can be displayed is 10. The format of the SHOW_HISTORY command is: SHOW_HISTORY; SHOW_HISTORY(n); where "n" is a positive integer in the range 1..10. If the parameter "n" is not specified then the default value is 1. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> SHOW_HISTORY(5); <cr> Will show the last 5 breakpoints executed 2) >> SHOW_HISTORY(4) <cr> Will show the last 4 breakpoints executed 3) >> SHOW_HIST(6 <cr> Will show the last 6 breakpoints executed 4) >> SHOW_H Will show the last breakpoint executed -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 19 6.4.5 The DISPLAY_UNITS Command In an Ada tasking environment it is often difficult to determine the status of program units at a given point in the execution of the program. The DISPLAY_UNITS command can be used to display the status of all active program units, including tasks. Program units are displayed in the order that they have been activated with the most recently activated program unit shown first. Tasks are qualified by their task type activation number to differentiate between different objects of the same task type. -------------------------------------------------- EXAMPLE: -------------------------------------------------- >> display_units; <cr> UNIT TYPE PROGRAM UNIT --------- ------------ TASK READ_MAIL [4] => TASK READ_MAIL [2] TASK READ_MAIL [1] FUNCTION MAILMAN.PROCESS_MAIL.NEXT_LETTER TASK SEND_MAIL [2] PROCEDURE MAILMAN.PROCESS_MAIL PROCEDURE MAILMAN >> -------------------------------------------------- The currently executing program unit at the time the DISPLAY_UNITS command is entered is flagged by "=>". Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 20 6.5 CONTROLLING PROGRAM EXECUTION Execution Control Commands control the execution of the Ada program under test. Commands in this category are: SET_BREAKPOINT CLEAR_BREAKPOINT GO STEP EXIT QUIT This section describes the use of each of the symbolic debugger's Execution Control Commands. 6.5.1 The SET_BREAKPOINT Command The initial default state of all breakpoints is "off". The SET_BREAKPOINT command sets one or more specified breakpoints "on". Breakpoints that have been set to "on" may be cleared by the CLEAR_BREAKPOINT command. The format of the SET_BREAKPOINT command is: SET_BREAKPOINT(n); SET_BREAKPOINT(comp_unit, n); SET_BREAKPOINT(pgm_unit); SET_BREAKPOINT(STANDARD.pgm_unit); where: n = breakpoint number comp_unit = compilation unit name pgm_unit = program unit name If only "n" is specified then breakpoint "n" in the current compilation unit is set. If "comp_unit" is specified then breakpoint "n" in compilation unit "comp_unit" is set. The parameter "pgm_unit" may be either unqualified or fully qualified. If "pgm_unit" is unqualified then the first breakpoint in each program unit of the current compilation unit with the program unit name "pgm_unit" is set. If "pgm_unit" is qualified then the first breakpoint of each program unit in all compilation units with the program unit name "pgm_unit" is set. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 21 -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> SET_BREAKPOINT(10); <cr> Sets breakpoint number 10 in the current compilation unit to "on". 2) >> SET_B(A,37 <cr> Sets breakpoint number 37 in compilation unit A to "on". 3) >> SET_BREAKPOINT(XYZ <cr> Sets the first breakpoint of each program unit in the current compilation unit with the program unit name XYZ to "on". 4) >> SET_BRE(A.B.C.XYZ) <cr> Sets the first breakpoint of each program unit in all compilation units with the fully qualified program unit name A.B.C.XYZ to "on". -------------------------------------------------- 6.5.2 The CLEAR_BREAKPOINT Command The default state for all breakpoints is "off". Breakpoints that have been set to "on" by the SET_BREAKPOINT command may be reset to "off" by using the CLEAR_BREAKPOINT command. The format of the command is: CLEAR_BREAKPOINT(n); CLEAR_BREAKPOINT(comp_unit); CLEAR_BREAKPOINT(comp_unit, n); CLEAR_BREAKPOINT(pgm_unit); CLEAR_BREAKPOINT(STANDARD.pgm_unit); CLEAR_BREAKPOINT; where n = breakpoint number comp_unit = compilation unit name pgm_unit = program unit name Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 22 If only "n" is specified then breakpoint "n" in the current compilation unit is cleared. If only "comp_unit" is specified then all breakpoints in compilation unit "comp_unit" are cleared. If both "comp_unit" and "n" are specified then breakpoint "n" in compilation unit "comp_unit" is cleared. The parameter "pgm_unit" may be either unqualified or fully qualified. If "pgm_unit" is unqualified then all breakpoints in each program unit of the current compilation unit with the program unit name "pgm_unit" are cleared. If "pgm_unit" is qualified then all breakpoints in each program unit of all compilation units with the program unit name "pgm_unit" are cleared. If neither a program unit name nor a breakpoint number is specified then all breakpoints in all compilation units are cleared. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> CLEAR_BREAKPOINT(10); <cr> Sets breakpoint number 10 in the current compilation unit to "off". 2) >> CLEAR_B(A,37 <cr> Sets breakpoint number 37 in compilation unit A to "off". 3) >> CLEAR_BREAKPOINT(XYZ <cr> Sets all breakpoints in each program unit of the current compilation unit with the program unit name XYZ to "off". 4) >> CLEAR_BRE(A.B.C.XYZ) <cr> Sets all breakpoints in each program unit of all compilation units with the fully qualified program unit name A.B.C.XYZ to "off". 5) >> C <cr> Sets all breakpoints in all program units of all compilation units to "off". -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 23 6.5.3 The GO Command The GO command resumes execution of the suspended program. Execution will continue until one or more of the following conditions occurs: 1) An active, or set, breakpoint is encountered. 2) A previously entered STEP count is exhausted. 3) Program termination due to an unhandled exception. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> GO; <cr> 2) >> GO <cr> 3) >> G; <cr> 4) >> G <cr> -------------------------------------------------- 6.5.4 The STEP Command The STEP command resumes execution of the suspended program for a specified number of breakpoints. Execution will continue until one or more of the following conditions occurs: 1) The STEP count is exhausted. 2) An active, or set, breakpoint is encountered. 3) Program termination due to an unhandled exception. The format of the STEP command is: STEP; STEP(step_count); where step_count is the number of breakpoints to be executed. If a step_count is not specified then the default value of 1 is used. If a SET breakpoint is encountered while in step mode before the step count is exhausted, then the step count will be resumed when execution is continued with the next GO command. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 24 The predefined keyboard macro <ENTER> may be used to execute the STEP command for 1 breakpoint. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> STEP; <cr> Will resume execution for 1 breakpoint. 2) >> ST(5) <cr> Will resume execution for 5 breakpoints 3) >> ST(2 <cr> Will resume execution for 2 breakpoints 3) >> <cr> Will resume execution for 1 breakpoint -------------------------------------------------- 6.5.5 The QUIT and EXIT Commands The QUIT and EXIT commands terminate the debugging session and and cause an orderly shutdown of the program under test. Minimum 2 character abbreviations for these commands are required to reduce the possibility of accidental premature program termination. If the instrumented program was invoked from the WIS_DEBUG Shell then execution of the shell will be resumed. If the program was invoked directly from the system then you will be returned to the system command level. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> QUIT; <cr> 2) >> QU <cr> 3) >> EXIT; <cr> 4) >> EX <cr> -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 25 6.6 EXAMINING AND MODIFYING PROGRAM VARIABLES Program Variable Commands are used to examine and modify variable data items declared in the Ada program under test. Commands in this category are: PUT_VARIABLE SET_VARIABLE Normal Ada scoping rules and constraints apply: 1) Only program variables that are visible within the scope of the breakpoint at which execution has been suspended may be examined or modified. 2) Constants may not be modified. 3) Range checking is performed. Constraint errors will be handled by the debugger and result in an error message. The variable to be set or displayed may be any legal Ada program variable name that is visible within the scope of the current breakpoint and may include indexed and selected components. The variable name may be prefixed by any portion of the current scope name. Correct syntax is required for array indices and record components, although trailing right parentheses and semicolons are optional. Array indices must be literal values. The debugger does not evaluate the index expression, but compares the string image of the next index in the array with the user input. If it matches, that element is set or displayed. In the case of a slice, once the lower bound is matched, all elements are set or displayed until the upper bound is matched. If no index is given, the whole array is set or displayed. 6.6.1 The PUT_VARIABLE Command The PUT_VARIABLE command displays the value of Ada program variables at the user's console. The format of the command is: PUT_VARIABLE(var_name); Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 26 The parameter var_name may be any legal Ada program variable name that is visible within the scope of the current breakpoint and may include subscripts and qualifiers. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> PUT_VARIABLE(COLOR); <cr> 2) >> PUT_VAR(ACCOUNT_NO.SMITH); <cr> 3) >> PUT_V(RECEIVABLES(ACCOUNT_NO.SMITH).BALANCE <cr> 4) >> PUT_V( KIND(3) ) <cr> -------------------------------------------------- The debugger will display the fully qualified name of the variable, followed by its value. Components are displayed one per line. If the current scope is an unnamed for-loop or a declare block, the source instrumenter will create a name for it. This name will be displayed as part of the fully qualified name of varibles in the scope. The names added by the source instrumenter begin with "SI2AFSD_1861_". * Named numbers are all displayed as floating point values, even if their type is universal_integer. * OUT mode formal parameters cannot be displayed. * Variables of type task type cannot be displayed. * Variables whose type is private or limited private cannot be displayed. However, if a variable is declared in the same package that declares the private type, it may be displayed from breakpoints within the package body. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 27 6.6.2 The SET_VARIABLE Command The SET_VARIABLE command has the same format and syntax as an Ada assignment statement. It is used to set the value of an Ada program variable. The format is VARIABLE := NEW_VALUE; where: VARIABLE is an Ada program variable that is visible within the scope of the breakpoint at which the assignment is made. NEW_VALUE is a literal value of the same basic type as VARIABLE -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> DRINKING_AGE := 21; <cr> 2) >> MY_STRING := "A String of Characters"; <cr> 3) >> COLORS(5,3) := ROOT_BEER_BROWN; <cr> 4) >> EMPLOYEE.SEX := FEMALE; <cr> -------------------------------------------------- The new value must have only literal values such that TEXT_IO can get a value of the expected type as the next item in the new value input string. This value is then assigned to the variable. New values are assigned in the order they are encountered. Named associations are not supported. If an error occurs, further execution of the assignment command is abandoned, however all components assigned before the point of the error will have the new value. * Record discriminants cannot be changed, even in a whole record assignment. * IN mode formal parameters, constants, access values and task types cannot be changed. An object designated by an access value maybe set according to the rules for its type. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: 6 - 28 * The debugger does not support setting OUT mode parameters of user defined types. * Only OUT mode formal parameters of the following types may be set: FLOAT LONG_FLOAT SHORT_FLOAT INTEGER LONG_INTEGER SHORT_INTEGER NATURAL POSITIVE BOOLEAN CHARACTER STRING * Variables whose type is private or limited private cannot be changed. If the variable is declared in the same package that declares the private type, it may be set from breakpoints within the package body according to the rules for its type. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 1 APPENDIX A ALPHABETICAL COMMAND SUMMARY This appendix contains an alphabetical summary of all commands in the Ada Symbolic Debugger User Interface Command Language (UICL). An index and quick reference to each command is included in Appendix H. The following pages contain a detailed description of each command, syntax, command arguments, predefined keyboard macros (if any), and examples of use. Command Formats COMMAND; COMMAND(ARGUMENT); COMMAND(ARGUMENT, ARGUMENT); Syntax Rules 1. Commands may be entered using full Ada syntax rules. Named parameter association is allowed but, once used, must be used for all subsequent parameters in the same command. 2. Case is not significant. 3. Blanks at the beginning and end of commands and arguments and at the end of the command line are ignored. Blanks embedded within commands and arguments are not allowed. 4. Only one command per command line is allowed. 5. Semicolons and trailing parentheses are optional. 6. Commands and discrete arguments may be abbreviated to the fewest number of characters that uniquely identify them. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 2 ---------------------- package SHELL_COMMANDS is --| for Named Parameter Assoc ---------------------- --| This is a "pseudo" package specification for WIS_DEBUG --| Shell commands. If named parameter association is used --| for commands, the parameter names given in the following --| procedure specifications must be used. ----------------- procedure COMPILE(SOURCE_FILE : STRING); ---------------- procedure DELETE(UNIT_NAME : STRING); -------------- procedure EXIT; -------------- procedure HELP; ----------------- procedure LIBRARY(PROGRAM_LIBRARY); -------------- procedure LINK(COMPILATION_UNIT : STRING); -------------- procedure QUIT; ------------- procedure RUN(COMPILATION_UNIT : STRING); --------------------- procedure SET_LIBRARY(PROGRAM_LIBRARY); --------------------------- procedure SOURCE_INSTRUMENT; procedure SOURCE_INSTRUMENT( SOURCE_FILE : STRING; SOURCE_LISTING_FILE : STRING; INSTRUMENTED_SOURCE_FILE : STRING); ------------------------ procedure SYSTEM_COMMAND(COMMAND : STRING); end SHELL_COMMANDS; Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 3 ------------------------- package DEBUGGER_COMMANDS is --| for Named Parameter Assoc ------------------------- --| This is a "pseudo" package specification for WIS_DEBUG --| Debugger commands. If named parameter association is --| used for commands, the parameter names given in the --| following procedure specifications must be used. type MESSAGE_TYPES is (BREAK, STEP); type TERMINAL_TYPES is (VT100, VT52, VI50, TV950); type MACROS is (&1, &2, &3, &4, &5, &6, &7, &8, &9); -- We know, we know... its not legal ------------------ procedure ANNOUNCE(WHICH_MESSAGE : MESSAGE_TYPES); procedure ANNOUNCE; ----------------- procedure CANFILE(CANFILE_NAME); -------------------------- procedure CLEAR_BREAKPOINT; procedure CLEAR_BREAKPOINT(UNIT_NAME : STRING); procedure CLEAR_BREAKPOINT(BREAKPOINT_NUMBER : POSITIVE); procedure CLEAR_BREAKPOINT(UNIT_NAME : STRING; BREAKPOINT_NUMBER : POSITIVE); ---------------- procedure DEFINE(MACRO : MACROS; VALUE : STRING); ----------------------- procedure DISPLAY_UNITS; -------------- procedure EXIT; ------------ procedure GO; -------------- procedure HELP; procedure HELP(TOPIC : STRING); ---------------------- procedure PUT_VARIABLE(VARIABLE_NAME : STRING); -------------- procedure QUIT; ------------------ procedure RECREATE; Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 4 ---------------- procedure RESHOW; ---------------- procedure SCREEN(TERMINAL_TYPE : TERMINAL_TYPES); --------------------- procedure SCROLL_DOWN; ------------------- procedure SCROLL_UP; ------------------------ procedure SET_BREAKPOINT(BREAKPOINT NUMBER : POSITIVE); procedure SET_BREAKPOINT(UNIT_NAME : STRING); procedure SET_BREAKPOINT(UNIT_NAME : STRING; BREAKPOINT NUMBER : POSITIVE); --------------------- procedure SET_LIBRARY(LIBRARY_NAME : STRING); -------------------- procedure SET_OUTPUT(NUMBER_OF_LINES : POSITIVE); -------------------- procedure SET_SOURCE(NUMBER_OF_LINES : POSITIVE); -------------------------- procedure SHOW_BREAKPOINTS(UNIT_NAME : STRING); --------------------- procedure SHOW_DEFINE; ---------------------- procedure SHOW_HISTORY(NUMBER_TO_DISPLAY : range 1..10 := 1); ---------------- procedure SILENT(WHICH_MESSAGE : MESSAGE_TYPES); procedure SILENT; -------------- procedure STEP(LINES : range 1..10 := 1); end DEBUGGER_COMMANDS; Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 5 ------------------------------------------------------------ ANNOUNCE Command ------------------------------------------------------------ Command Type: Debug Command Category: Status Full Ada Format: ANNOUNCE; ANNOUNCE(BREAK); ANNOUNCE(STEP); Minimum Abbreviation: A A(BREAK A(STEP Keyboard Macro: None Command Description: Turns on Symbolic Debugger messages at breakpoints and step points. Breakpoint messages and step messages are of the following form: Break at: PGM_UNIT_NAME << BKPT_NUMBER >> Step to: PGM_UNIT_NAME << BKPT_NUMBER >> The default for BREAK messages and STEP messages is "on". However, they may be turned "off" by the SILENT command. Examples: 1) >> ANNOUNCE(STEP); <cr> Turns on STEP messages 2) >> ANNOUNCE(BREAK) <cr> Turns on BREAKpoint messages 3) >> A <cr> Turns on both STEP and BREAKpoint messages Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 6 ------------------------------------------------------------ CANFILE Command ------------------------------------------------------------ Command Type: Debug Command Category: Special Command Full Ada Format: CANFILE(command_file_name); Minimum Abbreviation: CA(command_file_name Keyboard Macro: None Command Description: Execute Symbolic Debugger commands from a canned input command file. When all commands in the canned input command file have been executed control will be returned to the user's console. Examples: 1) >> CANFILE(SETUP.CAN); <cr> 2) >> CAN(KEY.DEF) <cr> 3) >> CA(BREAKS.CAN <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 7 ------------------------------------------------------------ COMPILE Command ------------------------------------------------------------ Command Type: Shell Command Category: Execution Control Format: COMPILE(SOURCE_FILE); Minimum Abbreviation: C(SOURCE_FILE Keyboard Macro: None Command Description: Invokes the Ada Compiler to compile the specified Ada source file from within the WIS_DEBUG Shell. After a unit has been instrumented by the Source Instrumenter it must be compiled using your Ada compiler. If you did not select the automatic compilation option after source instrumentation then you may use the COMPILE command to avoid exiting the shell. Examples: 1) COMPILE(TEST.INS); <cr> 2) COMPILE(TEST.INS <cr> 3) C(TEST.INS <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 8 ------------------------------------------------------------ CLEAR_BREAKPOINT Command ------------------------------------------------------------ Command Type: Debug Command Category: Execution Control Full Ada Format: CLEAR_BREAKPOINT(n); CLEAR_BREAKPOINT(comp_unit); CLEAR_BREAKPOINT(comp_unit, n); CLEAR_BREAKPOINT(pgm_unit); CLEAR_BREAKPOINT(STANDARD.pgm_unit); CLEAR_BREAKPOINT; Minimum Abbreviation: CL(n CL(comp_unit CL(comp_unit, n CL(pgm_unit CL(STANDARD.pgm_unit CL n = breakpoint number comp_unit = compilation unit name pgm_unit = program unit name Keyboard Macro: None Command Description: Sets the specified breakpoint "off". If only "n" is specified then breakpoint "n" in the current compilation unit is cleared. If only "comp_unit" is specified then all breakpoints in compilation unit "comp_unit" are cleared. If both "comp_unit" and "n" are specified then breakpoint "n" in compilation unit "comp_unit" is cleared. The parameter "pgm_unit" may be either unqualified or fully qualified. If "pgm_unit" is unqualified then all breakpoints in each program unit of the current compilation unit with the program unit name "pgm_unit" are cleared. If "pgm_unit" is qualified then all breakpoints in each program unit of all compilation units with the program unit name "pgm_unit" are cleared. The default state for all breakpoints is "off". They may be set to "on" by the SET_BREAKPOINT command. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 9 ------------------------------------------------------------ CLEAR_BREAKPOINT Command (Continued) ------------------------------------------------------------ Examples: 1) >> CLEAR_BREAKPOINT(10); <cr> Sets breakpoint number 10 in the current compilation unit to "off". 2) >> CLEAR_B(A,37 <cr> Sets breakpoint number 37 in compilation unit A to "off". 3) >> CLEAR_BREAKPOINT(XYZ <cr> Sets all breakpoints in each program unit of the current compilation unit with the program unit name XYZ to "off". 4) >> CLEAR_BRE(A.B.C.XYZ) <cr> Sets all breakpoints in each program unit of all compilation units with the fully qualified program unit name A.B.C.XYZ to "off". 5) >> CL <cr> Sets all breakpoints in all program units of all compilation units to "off". Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 10 ------------------------------------------------------------ DEFINE Command ------------------------------------------------------------ Command Type: Debug Command Category: Special Commands Full Ada Format: DEFINE( &n, SOME_STRING ); Minimum Abbreviation: DE( &n, SOME_STRING where n : integer range 1 .. 9; SOME_STRING : string; Keyboard Macro: None Command Description: The DEFINE command is used to define new keyboard macros. Up to 9 new keyboard macros may be defined. Imbedded blanks are allowed. Leading and trailing blanks are ignored. Quote characters (") should not be used to delimit the string. They are allowed but will be interpreted as part of the string. Once a keyboard macro has been defined it may be used anywhere on the command line when the debugger is in the command mode. It may be used to execute an entire command, or it may be embedded within a command. Examples - Given the following definitions: >> DEFINE( &1, SET_BREAKPOINT( ); <cr> >> DEFINE( &2, SHOW_HISTORY; ); <cr> >> DEFINE( &3, SHOW_BREAKPOINTS ); <cr> >> DEFINE( &4, LONG_PACKAGE_NAME.LONG_PROC_NAME ); <cr> >> DEFINE( &5, LONG_FUNCTION_NAME ); <cr> Then >> &2 <cr> will execute the SHOW_HISTORY command >> &1&4.&5 <cr> will set the first breakpoint in the program unit LONG_PACKAGE_NAME.LONG_PROC_NAME.LONG_FUNCTION_NAME >> C(&4 <cr> will clear all breakpoints in the procedure LONG_PACKAGE_NAME.LONG_PROC_NAME Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 11 ------------------------------------------------------------ DELETE Command ------------------------------------------------------------ Command Type: Shell Command Category: Library Management Format: DELETE(UNIT_NAME); Minimum Abbreviation: D(UNIT_NAME Keyboard Macro: None Command Description: Deletes the specified program unit from the Current Program Library. No file extension should be specified. Multiple files are deleted. However, Only files that are created by the Source Instrumenter are deleted. Examples: 1) DELETE(OLD_PROGRAM); <cr> 2) DEL(OLD_PROGRAM) <cr> 3) D(OLD_PROGRAM <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 12 ------------------------------------------------------------ DISPLAY_UNITS Command ------------------------------------------------------------ Command Type: Debug Command Category: Status Full Ada Format: DISPLAY_UNITS; Minimum Abbreviation: DI Keyboard Macro: None Command Description: Displays the status of all active program units. Units are displayed in the order that they have been activated with the most recently activated program unit shown first. Tasks are qualified by their task type activation number to differentiate between different objects of the same task type. The currently executing program unit at the time the DISPLAY_UNITS command is entered is flagged by "=>". Example: >> display_units; <cr> UNIT TYPE PROGRAM UNIT --------- ------------ TASK READ_MAIL [4] => TASK READ_MAIL [2] TASK READ_MAIL [1] FUNCTION MAILMAN.PROCESS_MAIL.NEXT_LETTER TASK SEND_MAIL [2] PROCEDURE MAILMAN.PROCESS_MAIL PROCEDURE MAILMAN >> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 13 ------------------------------------------------------------ EXIT Command ------------------------------------------------------------ Command Type: Shell and Debug Command Category: Execution Control Full Ada Format: EXIT; Minimum Abbreviation: EX Keyboard Macro: None Command Description: If the EXIT command is entered while in the debugger then the debugging session is terminated in an orderly manner and control is returned to the WIS_DEBUG shell. If the EXIT command is entered while in the WIS_DEBUG shell then execution of the shell is terminated in an orderly manner and control is returned to the system. The EXIT command performs the identical function as the QUIT command. Some users prefer EXIT, some prefer QUIT. The two commands may be used interchangeably. Examples: 1) >> EXIT; <cr> 2) >> EXIT <cr> 3) >> EXI; <cr> 4) >> EXI <cr> 5) >> EX; <cr> 6) >> EX <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 14 ------------------------------------------------------------ GO Command ------------------------------------------------------------ Command Type: Debug Command Category: Execution Control Full Ada Format: GO; Minimum Abbreviation: G Keyboard Macro: None Command Description: Resumes execution of the suspended program. Execution will continue until one or more of the following conditions occurs: 1) An active, or set, breakpoint is encountered. 2) A previously entered STEP count is exhausted. 3) Program termination due to an unhandled exception. Examples: 1) >> GO; <cr> 2) >> GO <cr> 3) >> G; <cr> 4) >> G <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 15 ------------------------------------------------------------ HELP Command ------------------------------------------------------------ Command Type: Shell and Debug Command Category: Special Commands Full Ada Format: HELP; HELP(topic); Minimum Abbreviation: H H(topic Keyboard Macro: None Command Description: Displays information about the WIS_DEBUG Shell and Symbolic Debugger commands and features. The HELP command may be entered at any time the shell or debugger is in "command" mode. "Topic" may be abbreviated. If no "topic" is specified or if an invalid "topic" is specified then a menu of all available HELP topics is displayed. If "topic" is ambiguous then a list possible intended topics and their minimum abbreviations is displayed. Examples: 1) >> HELP; <cr> Will display a menu of all available HELP topics 2) >> HELP(ANNOUNCE); <cr> Will display information about the ANNOUNCE command 3) >> H(DEFINE <cr> Will display information about the DEFINE command 4) >> H(T <cr> If only one topic begins with "T" then information about that topic will be displayed. If more than one topic begins with "T" then a list of those topics and their minimum abbreviations will be displayed. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 16 ------------------------------------------------------------ LIBRARY Command ------------------------------------------------------------ Command Type: Shell Command Category: Library Management Format: LIBRARY(PROGRAM_LIBRARY); Minimum Abbreviation: LIB(PROGRAM_LIBRARY Keyboard Macro: None Command Description: Sets the name of the default program library to be used by the WIS_DEBUG Shell. This command is functionally equivalent to the SET_LIBRARY command. The Source Instrumenter creates numerous files that are used by the Symbolic Debugger during execution. The name of the program library will be appended to the front of all file names by the source instrumenter. Therefore, it must be entered EXACTLY as will be required for the system you are using. Examples of valid program library names for the DEC VAX under VMS 4.0 are shown below. Examples: 1) LIBRARY( [.PGMLIB] ); <cr> 2) LIBRARY( [USER.NOSC.TEST.PGMLIB] <cr> 3) LIBR( DRC0:[USER.NOSC.TEST.PGMLIB] <cr> 4) LIB( [.PGMLIB] ); <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 17 ------------------------------------------------------------ LINK Command ------------------------------------------------------------ Command Type: Shell Command Category: Execution Control Format: LINK(COMPILATION_UNIT); Minimum Abbreviation: LIN(COMPILATION_UNIT Keyboard Macro: None Command Description: Invokes the LINKER to link the instrumented compilation unit from within the WIS_DEBUG Shell. The executeable load module is created in the current working directory. Examples: 1) LINK(TEST); <cr> 2) LINK(TEST <cr> 3) LIN(TEST <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 18 ------------------------------------------------------------ PUT_VARIABLE Command ------------------------------------------------------------ Command Type: Debug Command Category: Program Variable Full Ada Format: PUT_VARIABLE(var_name); Minimum Abbreviation: P(var_name P(var_name(subscript)) Keyboard Macro: None Command Description: Puts (or displays) the value of the specified variable at the user's console. The parameter var_name may be any legal Ada program variable name that is visible within the scope of the current breakpoint and may include subscripts and qualifiers. Trailing parentheses and the semicolon are optional. Examples: 1) >> PUT_VARIABLE(COLOR); <cr> 2) >> PUT_VAR(ACCOUNT_NUMBER.SMITH); <cr> 3) >> PUT_V(RECEIVABLES(ACCOUNT_NO.SMITH).BALANCE <cr> 4) >> PUT_V( KIND(3) ) <cr> Note that in examples 1 and 2 above the closing parentheses are optional while in example 4 the closing parentheses are required. In example 3, the closing parenthesis for the subscript is embedded and is, therefore, required. However, since the variable name does not END with a closing parenthesis, the closing parenthesis and semicolon for the procedure call are optional. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 19 ------------------------------------------------------------ QUIT Command ------------------------------------------------------------ Command Type: Shell and Debug Command Category: Execution Control Full Ada Format: QUIT; Minimum Abbreviation: QU Keyboard Macro: None Command Description: If the QUIT command is entered while in the debugger then the debugging session is terminated in an orderly manner and control is returned to the WIS_DEBUG shell. If the QUIT command is entered while in the WIS_DEBUG shell then execution of the shell is terminated in an orderly manner and control is returned to the system. The QUIT command performs the identical function as the EXIT command. Some users prefer QUIT, some prefer EXIT. The two commands may be used interchangeably. Examples: 1) >> QUIT; <cr> 2) >> QUIT <cr> 3) >> QUI; <cr> 4) >> QUI <cr> 5) >> QU; <cr> 6) >> QU <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 20 ------------------------------------------------------------ RECREATE Command ------------------------------------------------------------ Command Type: Debug Command Category: Terminal Control Full Ada Format: RECREATE; Minimum Abbreviation: REC Keyboard Macro: None Command Description: Recreates the terminal display in screen mode. Each display region (OUTPUT, SOURCE, USER) is recreated separately. In a multi-user time sharing environment situations may occur that affect the display when in screen mode such as messages from other users, batch job completion messages from the system, etc. It is not within the capability of the debugger to inhibit such situations. However, when this happens the screen display can normally be regenerated using the RESHOW command with no loss of information. The RECREATE command must used be when certain more extreme situations occur that directly affect the screen mode of the terminal, such as user output sending a control or escape sequence to the terminal that takes it out of screen mode. Situations such as this may require that the terminal be placed into a "local" mode, reset, and then placed back "on-line". The screen display must then be recreated using the RECREATE command. The OUTPUT region of the display will be restored to the most recent command, the SOURCE region will be restored to the current listing file and breakpoint, and the USER region will be cleared to avoid duplication of the condition that caused the problem. Examples: 1) >> RECREATE; <cr> 2) >> RECREATE <cr> 3) >> RECRE; <cr> 4) >> REC <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 21 ------------------------------------------------------------ RESHOW Command ------------------------------------------------------------ Command Type: Debug Command Category: Terminal Control Full Ada Format: RESHOW; Minimum Abbreviation: RES Keyboard Macro: None Command Description: Regenerates the terminal display in screen mode. In a multi-user time sharing environment situations may occur that affect the display when in screen mode such as messages from other users, batch job completion messages from the system, etc. It is not within the capability of the debugger to inhibit such situations. However, when this happens the screen display can normally be regenerated using the RESHOW command with no loss of information. If the situation cannot be corrected by using the RESHOW command, then the RECREATE command may be used. Examples: 1) >> RESHOW; <cr> 2) >> RESHOW <cr> 3) >> RESH; <cr> 4) >> RES <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 22 ------------------------------------------------------------ RUN Command ------------------------------------------------------------ Command Type: Shell Command Category: Execution Control Format: RUN(COMPILATION_UNIT); Minimum Abbreviation: R(COMPILATION_UNIT Keyboard Macro: None Command Description: Executes an instrumented program from within the WIS_DEBUG Shell. COMPILATION_UNIT must have already been compiled and linked. Examples: 1) RUN(TEST); <cr> 2) RUN(TEST <cr> 3) R(TEST <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 23 ------------------------------------------------------------ SCREEN Command ------------------------------------------------------------ Command Type: Debug Command Category: Terminal Control Full Ada Format: SCREEN(term_type); Minimum Abbreviation: SCRE(term_type Keyboard Macro: None Command Description: Changes the debugger from NON SCREEN mode (tty) to SCREEN mode. "term_type" must be a previously defined screen mode terminal in the Terminal Control File (TCF.DAT). Examples: 1) >> SCREEN(VT100); <cr> 2) >> SCREEN(TV970) <cr> 3) >> SCREEN(VT52 <cr> 4) >> SCRE(VI50 <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 24 ------------------------------------------------------------ SCROLL_DOWN Command ------------------------------------------------------------ Command Type: Debug Command Category: Terminal Control Full Ada Format: SCROLL_DOWN; Minimum Abbreviation: SCROLL_D Keyboard Macro: <PF3> Command Description: Scrolls the SOURCE display region "window" down one "page" in the current listing file. A "page" is equal to the current size of the SOURCE display region. The default size of the SOURCE display region is 8 lines but may be changed by the SET_SOURCE command. Examples: 1) >> SCROLL_DOWN; <cr> 2) >> SCROLL_DOWN <cr> 3) >> SCROLL_DO; <cr> 4) >> SCROLL_D <cr> 5) >> <PF3> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 25 ------------------------------------------------------------ SCROLL_UP Command ------------------------------------------------------------ Command Type: Debug Command Category: Terminal Control Full Ada Format: SCROLL_UP; Minimum Abbreviation: SCROLL_U Keyboard Macro: <PF2> Command Description: Scrolls the SOURCE display region "window" up one "page" in the current listing file. A "page" is equal to the current size of the SOURCE display region. The default size of the SOURCE display region is 8 lines but may be changed by the SET_SOURCE command. Examples: 1) >> SCROLL_UP; <cr> 2) >> SCROLL_UP <cr> 3) >> SCROLL_U; <cr> 4) >> SCROLL_U <cr> 5) >> <PF2> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 26 ------------------------------------------------------------ SET_BREAKPOINT Command ------------------------------------------------------------ Command Type: Debug Command Category: Execution Control Full Ada Format: SET_BREAKPOINT(n); SET_BREAKPOINT(comp_unit, n); SET_BREAKPOINT(pgm_unit); SET_BREAKPOINT(STANDARD.pgm_unit); Minimum Abbreviation: SET_B(n SET_B(comp_unit, n SET_B(pgm_unit SET_B(STANDARD.pgm_unit n = breakpoint number comp_unit = compilation unit name pgm_unit = program unit name Keyboard Macro: None Command Description: Sets the specified breakpoint "on". If only "n" is specified then breakpoint "n" in the current compilation unit is set. If "comp_unit" is specified then breakpoint "n" in compilation unit "comp_unit" is set. "pgm_unit" may be either unqualified or fully qualified. If "pgm_unit" is unqualified then the first breakpoint in each program unit of the current compilation unit with the program unit name "pgm_unit" is set. If "pgm_unit" is qualified then the first breakpoint of each program unit in all compilation units with the program unit name "pgm_unit" is set. The initial default state of all breakpoints is "off". Breakpoints that have been set to "on" may be cleared by the CLEAR_BREAKPOINT command. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 27 ------------------------------------------------------------ SET_BREAKPOINT Command (Continued) ------------------------------------------------------------ Examples: 1) >> SET_BREAKPOINT(10); <cr> Sets breakpoint number 10 in the current compilation unit to "on". 2) >> SET_B(A,37 <cr> Sets breakpoint number 37 in compilation unit A to "on". 3) >> SET_BREAKPOINT(XYZ <cr> Sets the first breakpoint of each program unit in the current compilation unit with the program unit name XYZ. 4) >> SET_BRE(A.B.C.XYZ) <cr> Sets the first breakpoint of each program unit in all compilation units with the fully qualified program unit name A.B.C.XYZ. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 28 ------------------------------------------------------------ SET_LIBRARY Command ------------------------------------------------------------ Command Type: Shell and Debug Command Category: Library Management Format: SET_LIBRARY(PROGRAM_LIBRARY); Minimum Abbreviation: Shell: SE(PROGRAM_LIBRARY Debug: SET_L(PROGRAM_LIBRARY Keyboard Macro: None Command Description: Sets the name of the default program library to be used by the WIS_DEBUG Shell and the Symbolic Debugger to PROGRAM_LIBRARY. The Source Instrumenter creates numerous files that are used by the Symbolic Debugger during execution. The name of the program library will be appended to the front of all file names by the source instrumenter. Therefore, it must be entered EXACTLY as will be required for the system you are using. Examples of valid program library names for the DEC VAX under VMS 4.0 are shown below. Examples: 1) SET_LIBRARY( [.PGMLIB] ); <cr> 2) SET_LIBRARY( [USER.NOSC.TEST.PGMLIB] <cr> 3) SET_L( DRC0:[USER.NOSC.TEST.PGMLIB] <cr> 4) SE( [.PGMLIB] ); <cr> --> Valid only in SHELL Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 29 ------------------------------------------------------------ SET_OUTPUT Command ------------------------------------------------------------ Command Type: Debug Command Category: Terminal Control Full Ada Format: SET_OUTPUT(size); Minimum Abbreviation: SET_O(size Keyboard Macro: None Command Description: Sets the size of the OUTPUT region of the terminal display in screen mode to "size" lines. The default OUTPUT display region is 6 lines. Examples: 1) >> SET_OUTPUT(10); <cr> Sets the OUTPUT display region to 10 lines 2) >> SET_O(8 <cr> Sets the OUTPUT display region to 8 lines Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 30 ------------------------------------------------------------ SET_SOURCE Command ------------------------------------------------------------ Command Type: Debug Command Category: Terminal Control Full Ada Format: SET_SOURCE(size); Minimum Abbreviation: SET_S(size Keyboard Macro: None Command Description: Sets the size of the SOURCE region of the terminal display in screen mode to "size" lines. The default SOURCE display region is 8 lines. Examples: 1) >> SET_SOURCE(10); <cr> Sets the SOURCE display region to 10 lines 2) >> SET_S(9 <cr> Sets the SOURCE display region to 9 lines Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 31 ------------------------------------------------------------ SET_VARIABLE Command ------------------------------------------------------------ Command Type: Debug Command Category: Program Variable Full Ada Format: VARIABLE_NAME := VALUE; Minimum Abbreviation: VARIABLE_NAME := VALUE Keyboard Macro: None Command Description: The SET_VARIABLE command has the same format and syntax as an Ada assignment statement. It is used to set the value of an Ada program variable. The format is A := SOME_CONSTANT; where: A is an Ada program variable that is visible within the scope of the breakpoint at which the assignment is made. SOME_CONSTANT is a constant value of the same basic type as A. Examples: 1) >> A := 10; <cr> 2) >> MY_STRING := "A String of Characters"; <cr> 3) >> COLOR_ARRAY(5,3) := INTERMETRICS_BLUE; <cr> 4) >> AUTOMOBILE.MAKE := STUDEBAKER; <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 32 ------------------------------------------------------------ SHOW_BREAKPOINTS Command ------------------------------------------------------------ Command Type: Debug Command Category: Status Full Ada Format: SHOW_BREAKPOINTS; SHOW_BREAKPOINTS(comp_unit); Minimum Abbreviation: SHOW_B SHOW_B(comp_unit Keyboard Macro: None Command Description: Displays breakpoints that have been set to "on" at the user's console. If no compilation unit name is specified then all breakpoints in all compilation units are displayed. If a compilation unit name is specified then only breakpoints in the specified compilation unit are displayed. Examples: 1) >> SHOW_BREAKPOINTS; <cr> Will display all active breakpoints in all compilation units 2) >> SHOW_BREAKPOINTS(SCHEDULER); <cr> Will display all active breakpoints in compilation unit SCHEDULER 3) >> SHOW_BREAK(MAILBOX <cr> Will display all active breakpoints in compilation unit MAILBOX 4) >> SHOW_B <cr> Will display all active breakpoints in all compilation units Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 33 ------------------------------------------------------------ SHOW_DEFINE Command ------------------------------------------------------------ Command Type: Debug Command Category: Special Commands Full Ada Format: SHOW_DEFINE; Minimum Abbreviation: SHOW_D Keyboard Macro: None Command Description: Displays the definitions of user defined keyboard macros at the user's console. Keyboard macros may be defined by using the DEFINE command. Only macros that have been defined are displayed. Example: >> DEFINE( &1, SET_BREAKPOINT( ); <cr> >> DEFINE( &2, LONG_PACKAGE_NAME. ); <cr> >> DEFINE( &3, LONG_PROCEDURE_NAME ); <cr> >> DEFINE( &4, LONG_FUNCTION_NAME ); <cr> >> SHOW_DEFINE; &1 = SET_BREAKPOINT( &2 = LONG_PACKAGE_NAME. &3 = LONG_PROCEDURE_NAME &4 = LONG_FUNCTION_NAME >> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 34 ------------------------------------------------------------ SHOW_HISTORY Command ------------------------------------------------------------ Command Type: Debug Command Category: Status Full Ada Format: SHOW_HISTORY; SHOW_HISTORY(n); Minimum Abbreviation: SHOW_H SHOW_H(n where n : integer range 1..10 := 1; Keyboard Macro: None Command Description: Displays the last 10 breakpoints executed at the user's console. If the parameter "n" is not specified then the default value is 1. Examples: 1) >> SHOW_HISTORY(5); <cr> Will show the last 5 breakpoints executed 2) >> SHOW_HISTORY(4) <cr> Will show the last 4 breakpoints executed 3) >> SHOW_HIST(6 <cr> Will show the last 6 breakpoints executed 4) >> SHOW_H <cr> Will show the last breakpoint executed Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 35 ------------------------------------------------------------ SILENT Command ------------------------------------------------------------ Command Type: Debug Command Category: Status Full Ada Format: SILENT; SILENT(BREAK); SILENT(STEP); Minimum Abbreviation: SI SI(BREAK SI(STEP Keyboard Macro: None Command Description: Turns off Symbolic Debugger messages at breakpoints and step points. Breakpoint messages and step messages are of the following form: Break at: PGM_UNIT_NAME << BKPT_NUMBER >> Step to: PGM_UNIT_NAME << BKPT_NUMBER >> The default for BREAK messages and STEP messages is "on". If messages are turned "off" by the SILENT command, they may be turned back "on" by using the ANNOUNCE command. Examples: 1) >> SILENT(STEP); <cr> Silences STEP messages 2) >> SILENT(BREAK) <cr> Silences BREAK messages 3) >> SI <cr> Silences both STEP and BREAK messages Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 36 ------------------------------------------------------------ SOURCE_INSTRUMENT Command ------------------------------------------------------------ Command Type: Shell Command Category: Execution Control Format: SOURCE_INSTRUMENT; SOURCE_INSTRUMENT(INPUT_FILE, SOURCE_LISTING_FILE, INSTRUMENTED_SOURCE_FILE ); Minimum Abbreviation: SO SO(INPUT_FILE, SOURCE_LISTING_FILE, INSTRUMENTED_SOURCE_FILE where: INPUT_FILE is the user's Ada source file. SOURCE_LISTING_FILE is a pretty printed version of the user's source with breakpoints listed. INSTRUMENTED_SOURCE_FILE is the file containing the instrumented source. Keyboard Macro: None Command Description: Instruments the user's Ada source program to insert "hooks" to the Symbolic Debugger. Only the main program unit and program units that will be debugged must be instrumented. This includes package specifications that declare data types or objects that you want to be visible to the debugger. Compilation units should be instrumented in compilation order. If input and output file names are not specified then the user will be prompted by the Source Instrumenter. The source_file must always be entered. However, default file names may be used for the listing file (null) and instrumented source file (.INS) by entering a carriage return when prompted for their names. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 37 ------------------------------------------------------------ SOURCE_INSTRUMENT Command (Continued) ------------------------------------------------------------ Examples: 1) source_instrument(test.ada, test.lis, test.si); <cr> source_file = TEST.ADA source_listing = TEST.LIS instrumented_source = TEST.SI 2) source_instrument <cr> Enter Source_File => test.ada <cr> Enter Source_Listing_File => test.lis<cr> Enter Instrumented_Source_File => test.si<cr> source_file = TEST.ADA source_listing = TEST.LIS instrumented_source = TEST.SI 3) so <cr> Enter Source_File => test.ada <cr> Enter Source_Listing_File => <cr> Enter Instrumented_Source_File => <cr> source_file = TEST.ADA source_listing = instrumented_source = TEST.INS Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 38 ------------------------------------------------------------ STEP Command ------------------------------------------------------------ Command Type: Debug Command Category: Execution Control Full Ada Format: STEP; STEP(step_count); Minimum Abbreviation: ST ST(step_count step_count = the number of break points to be executed Keyboard Macro: Enter (Carriage Return) Command Description: Resumes execution of the suspended program for "step_count" breakpoints. If "step_count" is not specified then the default value of 1 is used. Execution will continue until one or more of the following conditions occurs: 1) The STEP count is exhausted. 2) An active, or set, breakpoint is encountered. 3) Program termination due to an unhandled exception. Examples: 1) >> STEP; <cr> Will resume execution for 1 breakpoint. 2) >> ST(5) <cr> Will resume execution for 5 breakpoints 3) >> ST(2 <cr> Will resume execution for 2 breakpoints Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 39 ------------------------------------------------------------ SYSTEM_COMMAND Command ------------------------------------------------------------ Command Type: Shell Command Category: Execution Control Format: SYSTEM_COMMAND(COMMAND); Minimum Abbreviation: SY(COMMAND Keyboard Macro: None Command Description: Executes a system command or another program from within the WIS_DEBUG Shell. May be used for editing your source programs, file management, submitting jobs to a batch stream, printing Source Instrumenter listings for use during the debugging session, etc. When the spawned process is completed, any changes that have been made to the system's environment will be restored to their state prior to execution of SYSTEM_COMMAND. Examples: 1) SYSTEM_COMMAND( DIR/DATE); <cr> 2) SYSTEM_COMMAND( EDIT TEST.ADA <cr> 3) SY( PRINT TEST.LST <cr> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: A - 40 ------------------------------------------------------------ "?" Command ------------------------------------------------------------ Command Type: Shell Command Category: Help Format: ? Minimum Abbreviation: ? Keyboard Macro: None Command Description: At any time that WIS_DEBUG shell is at the command level you may list the available command options by entering a "?" followed by a carriage return. Commands are displayed in the order that they will normally be used. Example: please enter desired option ? <cr> WIS_DEBUG Options are: Library Management SEt_library(PROGRAM_LIBRARY); --> Set program library Delete(UNIT_NAME); --> Delete unit from pgm lib Execution Control SOurce_instrument; --> Instrument Ada source file Compile(SOURCE_FILE); --> Compile instrumented unit LINk(COMPILATION_UNIT); --> Link instrumented program Run(COMPILATION_UNIT); --> Run Debugger with instr pgm QUit; --> or EXit; --> Quit WIS_DBUG and Exit SYstem_commands(COMMAND); --> Execute a system command Help --> Help for commands & features please enter desired option Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B - 1 APPENDIX B DIAGNOSTIC MESSAGES This appendix is organized into three sections: B.1 WIS_DEBUG Shell Diagnostics B.2 Source Instrumenter Diagnostics B.3 Symbolic Debugger Diagnostics All diagnostic messages generated by WIS_DEBUG are in English and should, in most situations, be readily understood without reference to this manual, even by a casual user of the tool. Diagnostic messages for each section are organized in alphabetical order for easy reference. Each message includes an explanation of what may have caused the diagnostic to be generated. Other diagnostics may be generated by your Ada compiler system, your Ada run time system or your operating system. You must refer to the appropriate documentation that accompanies your system for interpretation of these types of diagnostic messages. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B1 - 1 B.1 WIS_DEBUG Shell Diagnostics This section discusses diagnostic messages generated by the WIS_DEBUG Shell. B.1.1 DEFINE requires an ampersand, digit, comma and value Meaning: The DEFINE command was entered incorrectly. Either an argument is missing or the digit specified is not in the range 1..9. The syntax is: DEFINE( &n, value ); B.1.2 DELETE requires a parameter, UNIT_NAME Meaning: The UNIT_NAME to be deleted from the program library was not specified. The syntax is: DELETE(UNIT_NAME); B.1.3 LIBRARY requires a parameter, CURRENT_PROGRAM_LIBRARY Meaning: The name of the CURRENT_PROGRAM_LIBRARY was not specified for the LIBRARY command. B.1.4 SET_LIBRARY requires a parameter, CURRENT_PROGRAM_LIBRARY Meaning: The name of the CURRENT_PROGRAM_LIBRARY was not specified for the SET_LIBRARY command. B.1.5 The topic XXXXX is ambiguous. Possibilities are: : : Enter"HELP(topic);" for more information Meaning: The abbreviation specified for a HELP topic matches more than one topic. More characters are required. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B1 - 2 B.1.6 The topic XXXXX is not found. Topics available are: : : Enter"HELP(topic);" for more information Meaning: No HELP information is found in WISDEBUG.HLP or SYMDEBUG.HLP for the specified topic. Refer to Appendix F for information on adding new help topics. B.1.7 unrecognized command Meaning: The command entered at the command prompt is not recognized. Check your spelling and make sure you have not used less than the minimum abbreviation for the command. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B2 - 1 B.2 Source Instrumenter Diagnostics This section discusses diagnostic messages generated by the Source Instrumenter. B.2.1 ERROR: Invalid compilation unit name. Meaning: The name of the compilation unit is not a legal Ada name (i.e., it contains a special character, has two or more underscores in a row, an underscore at the end of the name, etc.). Refer to your Ada Language Specification for legal Ada compilation unit names. B.2.2 ERROR: Invalid instrumented source file name. Meaning: The filename specified for the instrumented source file is not a valid filename. Check your spelling and be sure that the filename conforms to file naming conventions for your system. B.2.3 ERROR: Invalid listing file name. Meaning: The filename specified for the listing file is not a valid filename. Check your spelling and be sure that the filename conforms to file naming conventions for your system. B.2.4 ERROR: Source file has invalid name or does not exist. Meaning: The filename specified for the Ada source file to be instrumented cannot be found. The file must be located in your current default working directory. Check your spelling and be sure that the filename conforms to file naming conventions for your system. B.2.5 Syntax Error in Source: Line: LL Column: CC Meaning: The Ada source file being instrumented contains a syntax error on line "LL" in column "CC". The Source Instrumenter requires that the program you are instrumenting is syntactically correct. Correct the syntax error and reinstrument. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B3 - 1 B.3 Symbolic Debugger Diagnostics This section discusses all diagnostic messages that are generated by the Symbolic Debugger. When an error occurs in setting or displaying a variable, further processing of the current command is abandoned and an error message is displayed. The user request is shown, and arrows point to the current positions in the variable name and/or the new value input string where processing stopped. -------------------------------------------------- EXAMPLES: -------------------------------------------------- 1) >> x := 27 X := 27 ^ ^ Variable not found Interpretation: The variable X is either does not exist or is not visible within the current scope. 2) >> MY_CAR.LENGTH := 88; MY_CAR.LENGTH := 88 ^ ^ Variable not found Interpretation: The variable MY_CAR has been located. However, it is either not a record type or LENGTH is not a valid component of the record. 3) >> MY_CAR.COLOR := PINK; MY_CAR.COLOR := PINK ^ ^ PINK not recognized as an enumeration value Interpretation: The variable MY_CAR has been located and it is a record with a component COLOR which is an enumeration type. However the value PINK is not a valid enumeration value for the enumeration type. -------------------------------------------------- Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B3 - 2 B.3.1 Access values cannot be set Meaning: An access value cannot be changed. However, an object designated by an access value can be set and displayed according to the rules for its type. B.3.2 Character literal not found in input string Meaning: A non character value was specified for a variable of type CHARACTER. B.3.3 Constants or IN parameters cannot be set Meaning: The variable name specified is a constant or a formal IN parameter for a subprogram. Constants or IN parameters cannot be modified. B.3.4 Constraint_Error raised Meaning: The attempted assignment caused a constraint error to be raised. Either the new value is out of range, or TEXT_IO.GET could not interpret the next value in the new value input string correctly. B.3.5 Discriminants may not be set Meaning: Record discriminants cannot be changed, even in a whole record assignment. B.3.6 Enumeration value out of range Meaning: An enumeration type variable is probably uninitialized at the time of a put_var request. B.3.7 Extra or remaining input ignored Meaning: There were values left in the variable name and/or the new value input string when processing the current command was completed. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B3 - 3 B.3.8 FILE NOT FOUND Meaning: The file name specified to be used as a canned input command file (CANFILE) either does not exist in the current working directory or is an invalid file name. Check your spelling. If the CANFILE is not in your current working directory then a full path name for the file may be required. B.3.9 File SYMDEBUG.LOG already exists! Enter a new log file name or RETURN to overwrite Meaning: The file name specified to be used as a log file already exists. You may enter overwite the existing file by entering a carraiage return or enter a new file name. B.3.10 Fixed point value not found in input string Meaning: A non fixed point value was specified for a fixed point variable. B.3.11 Floating point value not found in input string Meaning: A non floating point value was specified for a variable of type FLOAT. B.3.12 Integer value not found in input string Meaning: A non integer value was specified for a variable of type INTEGER. B.3.13 Invalid array index Missing '(' ')' expected next Meaning: Invalid syntax was found when tracing indexed components. B.3.14 Invalid index expression Meaning: The array or slice index was not recognized. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B3 - 4 B.3.15 Invalid index or lower bound Meaning: The array index or the lower bound of a slice was not recognized. B.3.16 Invalid record specification Meaning: Invalid syntax was found when tracing a record type variable. B.3.17 Invalid upper bound Meaning: The upper bound of a slice was not recognized. Note that all array elements from the lower bound through the end of the array will have been displayed before it is known that the upper bound was not recognized. B.3.18 Invalid upper bound. Some elements may have been changed. Meaning: The upper bound of a slice was not recognized. Note that all array elements from the lower bound through the end of the array will have been set before it is known that the upper bound was not recognized, assuming no other errors occurred. B.3.19 Loop parameters cannot be set Meaning: The variable name specified is a loop variable. Loop variables cannot be modified. B.3.20 NAME AND OR NUMBER MUST BE SPECIFIED Meaning: Neither a unit name nor a breakpoint number was specified for a SET_BREAKPOINT command. Allowable formats are: SET_BREAKPOINT(BREAKPOINT); SET_BREAKPOINT(COMPILATION_UNIT, BREAKPOINT); SET_BREAKPOINT(PROGRAM_UNIT); Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B3 - 5 B.3.21 <user_input_value> not recognized as an enumeration value Meaning: The variable name specified was located and is an enumeration type. The value specified is not a valid enumeration value for the type. B.3.22 Null array slice or invalid lower bound Meaning: The upper bound of a slice was recognized before the lower bound was recognized. B.3.23 Null record Meaning: The record type variable to set or put has no fields. B.3.24 Numeric value not found in input string Meaning: Attempted to assign a non-numeric value to a numeric type. B.3.25 OUT parameters cannot be displayed Meaning: The variable name specified is an OUT mode parameter in a subprogram. Formal OUT mode parameters may not be displayed. B.3.26 Program library catalog not found! Enter a new program library name or RETURN to continue Meaning: The WIS_DEBUG program library catalog cannot be found in the specified Program Library. Either the program library name has not been entered correctly or the catalog file PKGFILES.CAT has been deleted from the Program Library. If you continue without specifying a new Program Library name then the Symbolic Debugger will not be able to display your listing files for you in SCREEN mode. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B3 - 6 B.3.27 SET_LIBRARY requires a parameter, CURRENT_PROGRAM_LIBRARY Meaning: The name of the CURRENT_PROGRAM_LIBRARY was not specified for the SET_LIBRARY command. B.3.28 SET_OUTPUT requires Number_Of_Lines Meaning: The argument Number_Of_Lines is required to specify the size of the OUTPUT display region when in SCREEN mode. B.3.29 SET_SOURCE requires Number_Of_Lines Meaning: The argument Number_Of_Lines is required to specify the size of the SOURCE display region when in SCREEN mode. B.3.30 Setting OUT parameters of user defined types is unimplemented Meaning: Only OUT mode parameters of the following types may be modified; FLOAT LONG_FLOAT SHORT_FLOAT INTEGER LONG_INTEGER SHORT_INTEGER NATURAL POSITIVE CHARACTER STRING BOOLEAN B.3.31 Terminal type is not currently supported Meaning: An unsupported terminal type was specified for the SCREEN command. Check your spelling and use the HELP command to determine what terminal types are supported. Refer to Appendix E for information about adding support for new screen type terminals. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B3 - 7 B.3.32 The topic XXXXX is ambiguous. Possibilities are: : : Enter"HELP(topic);" for more information Meaning: The abbreviation specified for a HELP topic matches more than one topic. More characters are required. B.3.33 The topic XXXXX is not found. Topics available are: : : Enter"HELP(topic);" for more information Meaning: No HELP information is found in the file SYMDEBUG.HLP for the specified topic. Refer to Appendix F for information on adding new help topics. B.3.34 Unit name not found in library Meaning: The compilation unit name specified cannot be found in the Current Program Library. Be sure your program library has been correctly set during initialization or with the SET_LIBRARY command. B.3.35 Unexpected end of input Meaning: There were no more values left in the new value input string. B.3.36 unrecognized command Meaning: The command entered at the command prompt is not recognized. Check your spelling or use the HELP command for information about debugger commands. B.3.37 Variable cannot be set or displayed Meaning: The variable is a task type, private or limited privated type. It cannot be set or displayed. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: B3 - 8 B.3.38 Variable not found Meaning: The variable is not directly visible in the specified scope, or in the scope of the current breakpoint. B.3.39 0 BREAKPOINTS SET Meaning: No breakpoints were set after using the SET_BREAKPOINT command. The specified program unit was not found. Check your spelling and review the rules for specifying program unit names for the SET_BREAKPOINT command. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: C - 1 APPENDIX C SPECIFIC WIS_DEBUG LIMITATIONS This appendix identifies all known limitations of the Ada Symbolic Debugger, WIS_DEBUG. Limitations fall into three categories. 1. Restrictions due to Ada Language constraints. 2. Limitations intentionally imposed to reduce the amount of instrumentation added to the user's source program. 3. Other limitations and unimplemented features. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: C - 2 C.1 Restrictions Due to Ada Language Constraints 1. Constants, loop parameters, and IN mode parameters may be examined but they may not be set. 2. OUT mode parameters in subprograms may be set but they may not be examined. 3. Variables may only be assigned values within the legal range constraints for the declared type. 4. Private types and limited private types are only traceable (visible) within the body of the package in which they are declared, even if the variable whose type is private is declared outside the package. 5. Variables of type TASK cannot be set or displayed. C.2 Limitations Imposed to Reduce Instrumentation 1. Real values are limited to 80 characters. 2. All named numbers are displayed as floating point values, even if their type is universal_integer. 3. No form of named associations are implemented for the PUT_VARIABLE and SET_VARIABLE commands. C.3 Other Limitations 1. The main program unit must be instrumented. 2. The main program unit may not contain a task. If your main program unit declares a task then you must instrument, compile, and link a driver that calls your program. A typical driver would look something like the following: with MY_PROGRAM; procedure MY_DRIVER is begin MY_PROGRAM; end MY_DRIVER; Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: C - 3 3. Only program units that have been instrumented by the source instrumenter are visible to the Symbolic Debugger. 4. Regardless of whether or not the Ada compiler system being used for program development provides an interface to programming languages other than Ada, only Ada program units may be instrumented. 5. The Symbolic Debugger imposes a certain amount of overhead on the execution time of each instrumented Ada program unit. This overhead will vary from system to system. Therfore, an instrumented program will execute slower than the same program uninstrumented. In a tasking environment if the execution of some program units is time dependent then the additional overhead imposed by the Symbolic Debugger may alter the normal flow of control of the program. 6. Variables can only be set to literal values ( i.e., values that TEXT_IO can extract from a string. 7. When assigning objects with multiple components, each component is assigned strictly in the order it is encountered. The assignment request is not evaluated entirely until the assignment is has been completed. If an error occurs, everything up to that point will have been already assigned. 8. Record discriminants can not be set, even in a whole record assignment. 9. Only the following types of OUT mode parameters can be set: INTEGER LONG_INTEGER SHORT_INTEGER FLOAT LONG_FLOAT SHORT_FLOAT NATURAL POSITIVE CHARACTER STRING BOOLEAN 10. Renaming is not implemented. 11. Variables of type ACCESS cannot be set. 12. Context clauses for subprogram declarations are not saved. Therefore, if the subprogram needs instrumented information for these units, they must be given (again) in the context clause for the subprogram body. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: C - 4 13. Generic objects are not traced. 14. Generic program units must be traced by their generic names, not their instantiated names. 15. Objects of task types must be traced by the name of the type and not the name of the object. For example, if TT is a task type and A, B, and C are all task objects of type TT, then references to tasks A, B, and C must use the program unit name TT. WIS_DEBUG will automatically assign a task type activation number to each object of a task type in the order that it is activated. 16. Limitations on the size of the user's program may or may not exist depending the system being used, the amount of memory available, and whether the system utilizes a virtual memory management scheme. Source instrumentation can cause the instrumented program to become very large. The amount of instrumentation inserted into the user's program is a function of many factors such as the number of type declarations, the number of objects declared, and the number of program units. In general, a large program with relatively few subprograms, type declarations, and variables will result in only a small percentage increase in size due to instrumentation. In contrast, a very small program with many small subprograms and many type and object declarations may increase several times in size. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: D - 1 APPENDIX D REHOSTING INFORMATION WIS_DEBUG is implemented entirely in Ada and has been designed to be highly portable. Compiler independence has been achieved through the use of a Source Instrumenter to provide symbolic information to to the debugger that is traditionally obtained from external symbol structures generated by the compiler. Portability has been achieved by isolating unavoidable system dependencies to a small number of packages that can easily be reconfigured for new targets. This appendix identifies all known compiler and system dependencies and provides information that will be needed if the tool is rehosted for use with other Ada compilers and systems. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: D - 2 All known system dependencies have been isolated to three packages and a procedure. Rehosting or retargeting the Symbolic Debugger should involve changes to only these compilation units: SYSDEP, SYSDEP2, SYSTEM_PARAMETERS, and CONVERT_ADDRESS_TO_STRING. The following sections describe dependencies contained in these units. SYSDEP The SYSDEP package contains system dependent procedures and type definitions. There are three types of procedures contained in SYSDEP: procedures used by the Virtual Terminal package, a procedure used by the parser, and procedures used by the WIS_DEBUG shell. The Virtual Terminal procedures provide an interface between the Virtual Terminal and the actual terminal. These procedures perform the system calls necesary to write to and read from a terminal. When the Symbolic Debugger is rehosted to a new machine, procedure bodies will need to be put in the SYSDEP package body. The procedure used by the parser is used to perform processing of tab characters. It is dependent on how tabs are handled in the new host machine. A body for this procedure also needs to be provided in the SYSDEP package body. The procedures used by the WIS_DEBUG shell are used to perform system commands such as compile, link, and run. If system commands cannot be performed from Ada on the new host machine then the package bodies for these procedures need only contain a message that the particular function is not supported. The type definitions contained in SYSDEP define those data types that are optional in Ada but that the Symbolic Debugger assumes exist. In Ada, SHORT_INTEGER, LONG_INTEGER, SHORT_FLOAT, and LONG_FLOAT are optional. If any of these types are not defined in the target system, then they should be defined in SYSDEP. For example, in DEC Ada LONG_INTEGER and SHORT_FLOAT are not provided. So in the Dec Ada version of the Symbolic Debugger, SYSDEP contains definitions for these two types. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: D - 3 SYSDEP2 SYSDEP2 contains two additional procedures used by the Virtual Terminal package. These procedures are SETTERMINFO and RESETTERMINFO, and are written in DEC Macro. These procedures are in their own package since DEC Ada allows assembly procedures to be entered into the program library only as the body for a compilation unit. The package specification for SYSDEP2 is a normal Ada package that defines the two procedures. The Macro routines are then entered into the program library as the pacakge body. SYSTEM_PARAMETERS The SYSTEM_PARAMETERS package contains declartions of system dependent items, and declarations of items that allow users to tailor the tool to meet their needs. The system dependent items mainly concern file names. They include the limit on the length of filenames, and the default names and extensions for files that the Symbolic Debugger creates. The items for tailoring provide some options for pretty printing, such as number of spaces for indentation and whether the extended or basic character set it used. CONVERT_ADDRESS_TO_STRING CONVERT_ADDRESS_TO_STRING is a procedure which uses unchecked type conversion to display an address. This may need to be tailored to each particular system. It needs to be defined, but it is up to the user to decide how to display addresses. If you do not wish the debugger to display addresses, then this procedure can can be modified to display a message that addresses can not be displayed. MISCELLANEOUS NOTES 1. Naming Conventions Instrumenting adds procedures and variables to the user source. To avoid naming conflicts, names added for variable tracing are built around the SD_PREFIX ("SI2AFSD_1861_"). This is a constant string, declared in SYSTEM_PAREMETERS. This prefix is "hard coded" in SD_GENERICS, and SDTPT. Other names added (for other than variable tracing) use the prefix "SD_". Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: D - 4 2. Predefined Types The file SDTPT.SPC will show which predefined types are implemented. Long/Short Float/Integer are included here, and are assumed to be defined either by the compiler or in SYSDEP. 3. File Names SDFNAMES.MAP and PKGFILES.CAT are external files used for keeping track of files created by the Source Instrumenter. The filenames, extensions, and the number of characters for forming filenames are declared in SYSTEM_PARAMETERS. 4. Source Generation MAX_SOURCE_LINE_LENGTH (declared in SYSTEM_PARAMETERS) is a constant which tells how long a source line can be. It is currently set to 80 characters. Any source generated by instrumenting is guaranteed not to exceed this size (accomplished by SD_SOURCE_BUFFERING). Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: E - 1 APPENDIX E THE TERMINAL CAPABILITIES FILE FORMAT ------------------------------------------------ The Ada Symbolic Debugger, WIS_DEBUG, uses an ANSI X3.64 Compatible Virtual Terminal package developed for NOSC by Texas Instruments under Contract No. N66001-84-R-0030. This Appendix contains information extracted WORD FOR WORD from CDRL Item No. 0028 (User Manual) necessary to add support for additional terminals. ------------------------------------------------ Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: E - 2 E.1 INTRODUCTION The Terminal Capabilities File is a variation of the TERMCAP developed in the Berkeley extensions to the UNIX operating system. The TCF is a data base describing terminals. Terminals are described in the TCF by giving a set of capabilities which they have, and by describing how operations are performed. Padding requirements and initialization sequences are included in the TCF. Entries in the TCF consist of a number of ":" separated fields. The first entry for each terminal gives the names which are known for the terminal, separated by "|" characters. The first name is always 2 characters long and is used by older UNIX systems which store the terminal type in a 16 bit word in a systemwide data base. The second name given is the most common abbreviation for the terminal, and the last name given should be a long name fully identifying the terminal. This second name is the one that is matched against the VMS logical name "TERM". The second name should contain no blanks; the last name may well contain blanks for readability. This virtual terminal uses the second name as a match against the user supplied terminal name. E.2 CAPABILITIES (P) indicates padding may be specified. Padding is an amount of time to be waited after the command is executed. Name Type Description al str Add new blank line be str Bell cd str Clear to end of display co num Number of columns in a line ce str Clear to end of line cm str Cursor motion dc str Delete character dl str Delete line ei str End insert mode im str Enter insert character mode is str Terminal initialization string k1 str Sent by terminal function key 1 k2 str Sent by terminal function key 2 k3 str Sent by terminal function key 3 k4 str Sent by terminal function key 4 Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: E - 3 k5 str Sent by terminal function key 5 k6 str Sent by terminal function key 6 k7 str Sent by terminal function key 7 k8 str Sent by terminal function key 8 k9 str Sent by terminal function key 9 l1 str Label on function key 1 l2 str Label on function key 2 l3 str Label on function key 3 l4 str Label on function key 4 l5 str Label on function key 5 l6 str Label on function key 6 l7 str Label on function key 7 l8 str Label on function key 8 l9 str Label on function key 9 kd str Sent by terminal down arrow key kl str Sent by terminal left arrow key kr str Sent by terminal right arrow key ku str Sent by terminal up arrow key li num Number of lines on screen or page nl str Newline character (default \n) se str End stand out mode sf str Scroll forwards so str Begin stand out mode sr str Scroll reverse (backwards) su bool Scrolls up at bottom of screen wr bool Wraps at end of line x0 str Sent by terminal function key 10 x1 str Sent by terminal function key 11 x2 str Sent by terminal function key 12 x3 str Sent by terminal function key 13 x4 str Sent by terminal function key 14 x5 str Sent by terminal function key 15 x6 str Sent by terminal function key 16 x7 str Sent by terminal function key 17 x8 str Sent by terminal function key 18 x9 str Sent by terminal function key 19 g0 str Sent by terminal function key 20 g1 str Sent by terminal function key 21 g2 str Sent by terminal function key 22 g3 str Sent by terminal function key 23 g4 str Sent by terminal function key 24 g5 str Sent by terminal function key 25 g6 str Sent by terminal function key 26 g7 str Sent by terminal function key 27 g8 str Sent by terminal function key 28 g9 str Sent by terminal function key 29 t0 str Sent by terminal function key 30 t1 str Sent by terminal function key 31 t2 str Sent by terminal function key 32 y0 str Label on function key 10 Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: E - 4 y1 str Label on function key 11 y2 str Label on function key 12 y3 str Label on function key 13 y4 str Label on function key 14 y5 str Label on function key 15 y6 str Label on function key 16 y7 str Label on function key 17 y8 str Label on function key 18 y9 str Label on function key 19 h0 str Label on function key 20 h1 str Label on function key 21 h2 str Label on function key 22 h3 str Label on function key 23 h4 str Label on function key 24 h5 str Label on function key 25 h6 str Label on function key 26 h7 str Label on function key 27 h8 str Label on function key 28 h9 str Label on function key 29 v0 str Label on function key 30 v1 str Label on function key 31 v2 str Label on function key 32 an str Ansi terminal vt str VT terminal ca str Clear all of line cl str Clear screen ds str De-initialization string The following entry describes the Televideo-970, among the more complex entries in the TCF file as of this writing. t1|tv970|tv-970|televideo 970:\ :al=1*\E[1L:am:bs:cd=\E[J:ce=\E[K:cl=\E[2J:cm=\E[%i%2;%2H:co#80:\ :dc=\E[1P:dl=1*\E[1M:dn=\E[1B:ei=\E[4l:ho=\E[H:im=\E[4h:li#24:mi:\ :nd=\E[1C:as=\E[10m:ae=\E[11m:ms:pt:se=\E[0m:so=\E[7m:up=\E[1A:\ :vs=\E[>4h:ve=\E[>4l:kb=^h:ku=\E[A:kd=\E[B:kl=\E[D:kr=\E[C:\ :kh=\E[H:kn#8:k1=\EOS:k2=\EOT:k3=\EOU:k4=\EOV:k5=\EOW:l6=blue:\ :sr=\EM:is=\E<\E[2J:\ :ca=\E[2K:ds=\E[?2l:\ :l1=F1:l2=F2:l3=F3:l4=F4:l5=F5:l6=F6:l7=F7:l8=F8:l9=F9:y0=F10:\ :y1=F11:y2=F12:y3=F13:y4=F14:y5=F15:y6=F16:\ :y7=Shift F1:y8=Shift F2:y9=Shift F3:h0=Shift F4:h1=Shift F5:\ :h2=Shift F6:h3=Shift F7:h4=Shift F8:h5=Shift F9:h6=Shift F10:\ :h7=Shift F11:h8=Shift F12:h9=Shift F13:v0=Shift F14:v1=Shift F15:\ :v2=Shift F16:an:\ :k1=\E?a:k2=\E?b::k3=\E?c:k4=\E?d:k5=\E?e:k6=\E?f:k7=\E?g:k8=\E?h:\ :k9=\E?i:x0=\E?j:x1=\E?k:x2=\E?l:x3=\E?m:x4=\E?n:x5=\E?o:x6=\E?p:\ :x7=\E?A:x8=\E?B:x9=\E?C:g0=\E?D:g1=\E?E:g2=\E?F:g3=\E?G:g4=\E?H:\ :g5=\E?I:g6=\E?J:g7=\E?K:g8=\E?L:g9=\E?M:t0=\E?N:t1=\E?O:t2=\E?P:\ :ku=\E[A:kd=\E[B:kr=\E[C:kl=\E[D: Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: E - 5 Note that entries may continue onto multiple lines by giving a \ as the last character of a line, and that empty fields may be included for readability (here between the last field on a line and the first field on the next). Capabilities in TCF are of three types: Boolean capabilities which indicate that the terminal has some particular feature, numeric capabilities giving the size of the terminal or the size of particular delays, and string capabilities, which give a sequence which can be used to perform particular terminal operations. All capabilities have two letter codes. Numeric capabilities are followed by the character "#" and then the value. Thus "co" which indicates the number of columns the terminal has gives the value "80" for the Televideo-970. String valued capabilities, such as "ce" (clear to end of line sequence) are given by the two character code, an "=", and then a string ending at the next following ":". A delay in milliseconds may appear after the "=" in such a capability. The delay must be an integer, e.g. "20". A number of escape sequences are provided in the string valued capabilities for easy encoding of characters there. A "\E" maps to an ESCAPE character, "^x" maps to a control-x for any appropriate x, and the sequences "\n" "\r" "\t" "\b" "\f" give a newline, return, tab, backspace and formfeed. Finally, characters may be given as three octal digits after a "\", and the characters "^" and "\" may be given as "\^" and "\\". If it is necessary to place a ":" in a capability it must be escaped in octal as "\072". We now outline how to prepare descriptions of terminals. The most effective way to prepare a terminal description is by imitating the description of a similar terminal in TCF. Be aware that a very unusual terminal may expose deficiencies in the ability of the TCF file to describe it or bugs in the virtual terminal. To easily test a new terminal description, you can set the environment variable TCF to a pathname of a file containing the description you are working on and the virtual terminal will look there rather than the standard location. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: E - 6 E.2.1 Basic Capabilities The number of columns on each line for the terminal is given by the "co" numeric capability. If the terminal is a CRT, then the number of lines on the screen is given by the "li" capability. If the terminal scrolls at the right edge of the screen, use ":wr:" to signal this. If the terminal scrolls up at the bottom of the screen, use ":su:" to signal this. These capabilities suffice to describe hardcopy and "glass-tty" terminals. Thus the model 33 teletype is described as t3|33|tty33:co#72 while the Lear Siegler ADM-3 is described as cl|adm3|3|lsi:\ adm3:wr:li#24:co#80 E.2.2 Cursor Addressing Cursor addressing in the terminal is described by a "cm" string capability. These substitute to encodings of the current line or column position, while other characters are passed through unchanged. If the "cm" string is thought of as being a function, then its arguments are the line and then the column to which motion is desired, and the "%" encodings have the following meanings: %d use as many digits as necessary %2 use 2 digits %3 use 3 digits %. encode binary value into a character (7 bits) %+x adds x to value, then %. %<xy if value < x adds y; then in any case %. %r reverses order of line and column, no output %i increments line/column (for 1 origin) %% gives a single % Consider the HP2645, which, to get to row 3 and column 12, needs to be sent "\E&a12c03Y" padded for 6 milliseconds. Note that the order of the rows and columns is inverted here, and that the row and column are printed as two digits. Thus its "cm" capability is "cm=6\E&%r%2c%2Y". The Microterm ACT-IV needs the current row and column sent preceded by a "^T", with the row and column simply encoded in binary, "cm=^T%.%.". Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: E - 7 A final example is the LSI ADM-3a, which uses row and column offset by a blank character, thus "cm=\E=%+ %+ ". E.2.3 Area Clears If the terminal can clear from the current position to the end of the line, leaving the cursor where it is, this should be given as "ce". If the terminal can clear from the current position to the end of the display, then this should be given as "cd". If the terminal can clear an entire line regardless of cursor location on the line, this should be given as "ca". If the terminal can clear an entire display then this should be given as "cl". E.2.4 Insert/Delete Line If the terminal can open a new blank line before the line where the cursor is, this should be given as "al"; this is done only from the first position of a line. The cursor must then appear on the newly blank line. If the terminal can delete the line which the cursor is on, then this should be given as "dl"; this is done only from the first position on the line to be deleted. E.2.5 Insert/Delete Character There are two basic kinds of intelligent terminals with respect to insert/delete character which can be described using the TCF. The most common insert/delete character operations affect only the characters on the current line and shift characters off the end of the line rigidly. Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make a distinction between typed and untyped blanks on the screen, shifting upon an insert or delete only to an untyped blank on the screen which is either eliminated, or expanded to two untyped blanks. You can find out which kind of terminal you have by clearing the screen and then typing text separated by cursor motions. Type "abc def" using local cursor motions (not spaces) between the "abc" and the "def". Then position the cursor before the "abc" and put the terminal in insert mode. If typing characters causes the rest of the line to shift rigidly and characters to fall off the end, then your terminal does not distinguish between blanks and untyped positions. If the "abc" shifts over to the "def" which then move together around the end of the Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: E - 8 current line and onto the next as you insert, you have the second type of terminal. If you have this second type of terminal, you will get no support from the virtual terminal. This may be changed in further versions. Give as "im" the sequence to get into insert character mode. Give as "ei" the sequence to leave insert mode. E.2.6 Highlighting, Underlining, And Visible Bells If your terminal has sequences to enter and exit standout mode these can be given as "so" and "se" respectively. If there are several flavors of standout mode (such as inverse video, blinking, or underlining - half bright is not considered "standout") the prefered mode is inverse video by itself. If the terminal has a way of flashing the screen to indicate an error quietly (a bell replacement) then this can be given as "be"; it must not move the cursor. E.2.7 Function Keys If the terminal has function keys that transmits codes when the keys are pressed, this information can be given. Note that it is not possible to handle terminals where the keypad only works in local (this applies, for example, to the unshifted HP 2621 keys). The codes sent by the left arrow, right arrow, up arrow, down arrow keys can be given as "kl", "kr", "ku", and "kd" respectively. If there are function keys such as "f1", "f2", ..., "f9", the codes they send can be given as "k1", "k2", ..., "k9", "x0", "x1", ..., "x6" If these keys have labels, the labels can be given as "l1", ..., "l9", "y0", "y1", ..., "y6". E.2.8 Initialization An initialization string can be specified to setup the characteristics of a terminal. If the terminal must have its function keys defined or turn on the keypad mode this can be done with is. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: E - 9 Using the Televideo-970 example again: t1|tv970|tv-970|televideo 970:\ :al=1*\E[1L:am:bs:cd=\E[J:ce=\E[K:cl=\E[2J:cm=\E[%i%2;%2H:co#80:\ :dc=\E[1P:dl=1*\E[1M:dn=\E[1B:ei=\E[4l:ho=\E[H:im=\E[4h:li#24:mi:\ :nd=\E[1C:as=\E[10m:ae=\E[11m:ms:pt:se=\E[0m:so=\E[7m:up=\E[1A:\ :vs=\E[>4h:ve=\E[>4l:kb=^h:ku=\E[A:kd=\E[B:kl=\E[D:kr=\E[C:\ :kh=\E[H:kn#8:k1=\EOS:k2=\EOT:k3=\EOU:k4=\EOV:k5=\EOW:l6=blue:\ :sr=\EM:is=\E<\E[2J:\ :ca=\E[2K:ds=\E[?2l:\ :l1=F1:l2=F2:l3=F3:l4=F4:l5=F5:l6=F6:l7=F7:l8=F8:l9=F9:y0=F10:\ :y1=F11:y2=F12:y3=F13:y4=F14:y5=F15:y6=F16:\ :y7=Shift F1:y8=Shift F2:y9=Shift F3:h0=Shift F4:h1=Shift F5:\ :h2=Shift F6:h3=Shift F7:h4=Shift F8:h5=Shift F9:h6=Shift F10:\ :h7=Shift F11:h8=Shift F12:h9=Shift F13:v0=Shift F14:v1=Shift F15:\ :v2=Shift F16:an:\ :k1=\E?a:k2=\E?b::k3=\E?c:k4=\E?d:k5=\E?e:k6=\E?f:k7=\E?g:k8=\E?h:\ :k9=\E?i:x0=\E?j:x1=\E?k:x2=\E?l:x3=\E?m:x4=\E?n:x5=\E?o:x6=\E?p:\ :x7=\E?A:x8=\E?B:x9=\E?C:g0=\E?D:g1=\E?E:g2=\E?F:g3=\E?G:g4=\E?H:\ :g5=\E?I:g6=\E?J:g7=\E?K:g8=\E?L:g9=\E?M:t0=\E?N:t1=\E?O:t2=\E?P:\ :ku=\E[A:kd=\E[B:kr=\E[C:kl=\E[D: The initialization string is ":is=\E<\E[2J". This string will be sent to the terminal when the virtual terminal is initialized. The de-initialization string, ds, sends a string of escape sequences that changes the terminal upon exiting the program. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: F - 1 APPENDIX F HELP FILE FORMAT The WIS_DEBUG Help Files are in a format that enable the user to easily extend them to add additional topics about project or system specific information. If WIS_DEBUG is rehosted, it may also be necessary to tailor the examples for commands that deal directly with the system, such as SYSTEM_COMMAND or the SET_LIBRARY command. Two separate Help Files are used by WIS_DEBUG. The file WISDEBUG.HLP contains information used by the WIS_DEBUG Shell. The file SYMDEBUG.HLP contains information used by the Symbolic Debugger. Both are ASCII text files. The format of the Help Files is described on the following pages. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: F - 2 HELP FILE FORMAT 1) The first character of each line is a control character. Control characters have the following meaning: # designates a Menu Item. Menu Items are displayed when the HELP command is entered without a "topic". \ indicates help for a COMMAND. The format of a COMMAND line is: \COMMAND\MIN_ABBREV\KBD_MACRO\COMMAND_DESCRIPTION COMMAND is the full unabbreviated command. MIN_ABBREV is the minimum abbreviation that will be accepted for the command. KBD_MACRO is a keyboard macro that may be used to execute the command. COMMAND_DESCRIPTION is a one line description of the command. $ indicates help for a TOPIC. The format of a TOPIC line is: \TOPIC\MIN_ABBREV\KBD_MACRO\TOPIC_DESCRIPTION TOPIC is the full unabbreviated command. MIN_ABBREV is the minimum abbreviation that will be accepted for the topic. KBD_MACRO is not applicable to topics and should contain something appropriate such as "N/A" or "None". TOPIC_DESCRIPTION is a one line description of the topic. ? causes the following prompt to be printed: Enter RETURN for more information or "Q" to quit: If "Q" or "q" is entered then HELP is terminated. If anything other than "Q" or "q" is entered then the remainder of the line is displayed. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: F - 3 HELP FILE FORMAT (Continued) E causes the following prompt to be printed: Enter RETURN for examples or "Q" to quit: If "Q" or "q" is entered then HELP is terminated. If anything other than "Q" or "q" is entered then the remainder of the line is displayed. + causes the remainder of the line to be displayed. 2) All Menu Items must be placed at the beginning of the file. 3) Help topics must be in alphabetical order. 4) Blank lines are not allowed. 5) All lines beginning with a character other than a control character are ignored but will terminate HELP for the topic that is currently being displayed. Therefore, comments may be inserted into the help file that are not printed by using any non-control character in the first character position. 6) Help file text lines are limited to a maximum of 80 characters. An example Help File is shown on the following page. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: F - 4 EXAMPLE HELP FILE If we wanted to add information about a new command HACF and a new topic FIRES, the help file might be modified to contain the following: # FIRES HACF * * Last Modified 7/3/86 JEE * $FIRES\F\None\What to do in case of a fire: + + 1) Notify Security + 2) Power down the computer + 3) Yell "FIRE" three times ? Evacuate the building!! * \HACF\HA\<PF5> - Function Key 5\Halt And Catch Fire + +A new system command has been added in honor of the 4th of +July. It is now available through the WIS_DEBUG Shell via +the SYSTEM_COMMAND option. ? +The format of the HACF command is: + + SYSTEM_COMMAND( HACF ); + SYSTEM_COMMAND( HACF/DEVICE=name ); + SYSTEM_COMMAND( HACF/DELAY=seconds ); + SYSTEM_COMMAND( HACF/DEVICE=name/DELAY=seconds ); + + where: name is the device name. Allowable devices are + COMPUTER, PRINTER, and TERMINAL. + + seconds is the number of seconds to delay before + catching fire (0..86400). ? + If no DEVICE is specified then all devices will catch + fire. If no DELAY is specified then the specified + device will catch fire immediately. E 1) SYSTEM_COMMAND( HACF/DEVICE=PRINTER/DELAY=8 ); + Will set the printer on fire in 8 seconds + + 2) SYSTEM_COMMAND( HACF/DEVICE=TERMINAL ); + Will immediately set the terminal on fire + + 3) SYSTEM_COMMAND( HACF/DELAY=86400 ); + Will set the computer, printer and terminal on fire in + 24 hours ? For more information enter HELP(FIRES);.pa Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: G - 1 APPENDIX G GLOSSARY OF TERMS AND ABBREVIATIONS This appendix contains definitions of many terms as used within the context of this manual. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: G - 2 Base Program Library A directory containing certain static non-transient files that are common to all users of the debugger. It must be set up at the time WIS_DEBUG is installed. Breakpoint A breakpoint is a transfer of control from the user's program to the Symbolic Debugger. Each breakpoint within a compilation unit is assigned a unique breakpoint number by the Source Instrumenter. In general, breakpoints are inserted after entry to each program unit, before each executeable statement, and before each exit from a program unit. CANFILE A text file that contains Symbolic Debugger commands in exactly the same format as they would be entered through the keyboard at the command prompt. CANFILES may be executed any time the Symbolic Debugger is at the command prompt ">>" by entering the CANFILE command followed by the name of the CANFILE to be executed. Current Program Library A directory used to hold dynamic information that is created and/or used by the Source Instrumenter and Symbolic Debugger during execution. In general, you will have a single Current Program Library that is used only by you. Keyboard Macros Macros that extend the User Interface Command Language and simplify the use of frequently used commands. There are two types of keyboard macros: 1. Predefined Keyboard Macros that are only available when the Symbolic Debugger is in SCREEN mode. 2. User Defined Keyboard Macros that may be defined by the user via the DEFINE command. Log File A sequential file created by the Symbolic Debugger during execution of an instrumented Ada program. The Log File is used to record information about the execution of the Ada program. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: G - 3 Overhead Additional execution time imposed on the program under test by the Symbolic Debugger. Program Library The WIS_DEBUG Program Library consists of two libraries, or directories: 1. the BASE Program Library 2. the CURRENT Program Library Program Unit Ada programs may contain four different types of program units: procedures, functions, tasks and generics. However, the Ada language also provides the ability to include executeable code within a package body that is not included within any of the program units contained in that package. This code is executed during initialization when the package is elaborated. The WIS_DEBUG Source Instrumenter and Symbolic Debugger treat package "initialization" code the same as other Ada program units. Screen Mode WIS_DEBUG supports both SCREEN mode and NON SCREEN (TTY) type terminals. When using the SCREEN mode WIS_DEBUG divides the screen into three independently scrolled regions: 1. An OUTPUT region for input of debugger commands and output of debugger messages and diagnostics. 2. A USER region for input and output by the user's program. 3. A SOURCE region for displaying a source listing of the currently executing compilation unit. Shell The Shell is the primary interface to WIS_DEBUG that enables the user to access each of the WIS_DEBUG features. Its principal functions include program library management, source instrumentation, compilation and linking, and execution of the Symbolic Debugger. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: G - 4 Source Instrumenter An Ada program that parses the target Ada program and inserts "hooks" that transfer control to the Symbolic Debugger upon entry to and exit from each instrumented Ada program unit and at each breakpoint. Each Ada program unit which is to be visible to the Symbolic Debugger must be instrumented by the Source Instrumenter prior to compilation. Terminal Capabilities File A file containing the attributes of each terminal supported by WIS_DEBUG. The Terminal Capabilities File (TCF.DAT) must be located in the Base Program Library. Test ID A unique test identification specified by the user when the program under test is executed. The Test ID is stored in the log file by the Symbolic Debugger. User Interface Command Language (UICL) The set of commands used to specify user requests to the Symbolic Debugger. Working Directory A directory containing the Ada source programs to be instrumented and debugged. Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649 Ada Symbolic Debugger User's Guide Page: H - 1 APPENDIX H COMMAND INDEX AND QUICK REFERENCE COMMAND MIN CMD ABBREV TYPE KBD MACRO PAGE ---------------- -------------- ----- --------- ------ ANNOUNCE A Debug None A - 5 CANFILE CA Debug None A - 6 COMPILE C Shell None A - 7 CLEAR_BREAKPOINT CL Debug None A - 8 DEFINE DE Debug None A - 10 DELETE D Shell None A - 11 DISPLAY_UNITS DI Debug None A - 12 EXIT EX BOTH None A - 13 GO G Debug None A - 14 HELP H BOTH None A - 15 LIBRARY LIB Shell None A - 16 LINK LIN Shell None A - 17 PUT_VARIABLE P Debug None A - 18 QUIT QU BOTH None A - 19 RECREATE REC Debug None A - 20 RESHOW RES Debug None A - 21 RUN R Shell None A - 22 SCREEN SCRE Debug None A - 23 SCROLL_DOWN SCROLL_D Debug <PF3> A - 24 SCROLL_UP SCROLL_U Debug <PF2> A - 25 SET_BREAKPOINT SET_B Debug None A - 26 SET_LIBRARY SET_L BOTH None A - 28 SET_OUTPUT SET_O Debug None A - 29 SET_SOURCE SET_S Debug None A - 30 SET_VARIABLE Var := Value Debug None A - 31 SHOW_BREAKPOINTS SHOW_B Debug None A - 32 SHOW_DEFINE SHOW_D Debug None A - 33 SHOW_HISTORY SHOW_H Debug None A - 34 SILENT SI Debug None A - 35 SOURCE_INSTRUMENT SO Shell None A - 36 STEP ST Debug <ENTER> A - 38 SYSTEM_COMMAND SY Shell None A - 39 ? ? Shell None A - 40 (insert mode toggle) Debug <PF1> (erase end of line) Debug <PF4> (recall previous commands) Debug <UP ARROW> <DN ARROW> Intermetrics Inc 5312 Bolsa Ave Huntington Beach, CA 92649