**************** * Introduction * Sun Sep 1 15:43:22 1991 **************** PowerVisor V1.0 --------------- PowerVisor is a powerful debugger designed to do almost everything you can think of. Even if you can't think of it it will probably still be possible :-) What I meant to say with the above is that PowerVisor is rather complex to use. I recommend that you read the tutorial sections even if you think you can cope. Once you have mastered the program you will probably be able to debug your programs in a very short time. Read the tutor files and execute each command as mentioned there. All lines you have to type are preceded by a '<'. Some special keys are notated as . is used for the return key. All output from PowerVisor is preceded by a '>'. If you must press two keys together there is a '+' between them: +. All input and output in this tutorial is for the AmigaDOS 2.0 version. In most cases this does not matter. If there are differences between the two versions it is mentioned in the tutorial in the following form: (1.3 : .......) Shareware --------- PowerVisor is shareware. This means that you can copy it and give to everybody. If you like the program and/or use it, I'd appreciate it if you send me a contribution. If you send $25 US or more you automatically get the next major release when one is available. PLEASE send money by international money order, EuroCheck (in Belgian Francs (BF) !) or cash, because it's very difficult for me to cash in other checks ! If you want an update please state your current version. Note that PowerVisor may only be redestributed with ALL FILES PRESENT (especially this file). Below follows a list of all files in the PowerVisor distribution. NOTHING in the PowerVisor distribution may be redistributed seperatelly or used in any commercial product without prior permission from the author. Note that the quickhelp utilities ('MakeHelp', 'ArcFiles', 'Help', 'MakeHelp13', 'ArcFiles13' and 'Help13') are considered seperate from PowerVisor. You may redistribute the quickhelp utilities without the rest of PowerVisor if you really want to (read the 'Help.doc' and 'Help13.doc' files for possible restrictions). This is in fact a BETA VERSION. This means that there are still some bugs to be solved. If you use this program you are betatesting PowerVisor. Don't worry too much about this. I think PowerVisor is rather stable. I use it a lot and I have not yet crashed with the current version. I (THE AUTHOR) TAKE NO RESPONSIBILITY FOR DAMAGES INFLICTED BY POWERVISOR AND THE OTHER PROGRAMS IN THIS DISTRIBUTION. YOU ARE COMPLETELY RESPONSIBLE FOR ALL EFFECTS OF USING POWERVISOR AND ANY OF THE OTHER PROGRAMS. I'm sorry --------- I'm sorry for the bad English. I speak Dutch and English is only my second language. The tutorial files as they are in the current distribution are NOT corrected at all. I didn't even reread everything. I'd very much appreciate corrections of the online help and the tutorial files. Bugs ---- PowerVisor was programmed on an Amiga 3000 with AmigaDOS 2.0. I have tested the program on AmigaDOS 1.3 and everything seemed to work. I have not been able to test PowerVisor on any other Amiga configuration. PowerVisor is a big program. This means that bugs are unavoidable. If you find some bugs, or have some suggestions please write. I'd like PowerVisor to be as bug free as possible. In this distribution there is a file 'pv.bugs' describing all bugs in the current version. Consult this file if you discover some weird behaviour. Give the following information when you report a bug : - Hardware configurations you have used (if a bug occurs on one hardware configuration but not on another one, please give both hardware configurations) Hardware configurations includes : Processor (68000, 68010, 68020, 68030, 68040, ...) Coprocessor (68881, 68882, ...) MMU (68851, ...) Amiga model (500, 1000, 2000, 2500/20, 2500/30, 3000/16, 3000/25, 3000UX, 3000T, CDTV, ...) Available memory (chip ram, fast ram, other, ...) Harddisk information Other hardware expansions (graphics card, sound card, ...) - Software configuration you used Software configuration includes : Operating system (AmigaDOS 1.2, 1.3, 2.0) If you can run more than one operating system on your Amiga, test the bug in the different versions Version of KickStart and WorkBench (in Workbench about menu or with 'version' cli command) Other programs running while the bug occurs (screen blankers, popup programs, ...) - Describe the bug and the sequence of commands needed to get the bug All files --------- MakeIndex (dir) This subdirectory contains files needed to update the index file for the tutorial files. You only need any of these files if you want to add or remove some items from the index CancelDouble This program cancels all double lines in a file. This program is used by 'MakeGlobalIndex' CancelDouble.c The source for 'CancelDouble'. You should be able to compile this program on any C-compiler ExtractIndex.rexx This rexx script is used by 'MakeIndex' to construct the index file for one individual tutor file HowToMakeAnIndex A tutor file explaining how to make an index MakeGlobalIndex This script file combines all index files made by 'MakeIndex' to make the global index MakeIndex Make the index and contents file for one tutorial file PowerVisorLib (dir) This subdirectory contains files needed to use to powervisor.library in your programs pv_lib.fd fd-file containing function definitions for the powervisor.library functions pv_lib.h C header file containing pragmas for the powervisor.library functions. This file is written for Lattice C 5.0. If you use another compiler (like Aztec) you may need to rewrite this file. If you use a C compiler with no support for pragmas you must make stubs to call the library functions pv_lib.i Machinelanguage header file. c (dir) This subdirectory contains all executable files. All files ending with '13' are for AmigaDOS 1.3. ArcFiles The QuickHelp utilities for AmigaDOS 2.0 Help Read docs/help.doc for more info MakeHelp ArcFiles13 The QuickHelp utilities for AmigaDOS 1.3 Help13 Read docs/help13.doc for more info MakeHelp13 MStruct AmigaDOS 2.0 only program to convert pseudo include files to pvsd files. This program will be enhanced in future to support full include files. I apologize for the fact that this program is AmigaDOS 2.0 only. I have had no time to convert it to AmigaDOS 1.3. Maybe for the next release. pv AmigaDOS 2.0 version of PowerVisor pv13 AmigaDOS 1.3 version of PowerVisor libs (dir) All libraries needed by PowerVisor arp.library arp.library is only needed if you use AmigaDOS 1.3 powervisor.library This library is needed by PowerVisor docs (dir) All documents for PowerVisor GettingStarted Read this file if you are a first-time user Expressions All about expression evaluation in PowerVisor Screen Everything about screens and windows InstallingPowerVisor How to install PowerVisor Scripts Everything about scripts (ARexx, ...) LookingAtThings How to look at memory, disassemble, ... Debug How to debug programs CommandReference All PowerVisor commands explained Functions All PowerVisor functions explained Lists All lists TechnicalInfo Some technical information TheWizardCorner Only for VERY experienced users Global.index The index for all above files GettingStarted.idx The individual index files for all tutor Expressions.idx and reference files Screen.idx InstallingPowerVisor.idx Scripts.idx LookingAtThings.idx Debug.idx CommandReference.idx Functions.idx Lists.idx TechnicalInfo.idx TheWizardCorner.idx Screen.contents The contents files for all tutor files GettingStarted.contents Expressions.contents InstallingPowerVisor.contents Scripts.contents LookingAtThings.contents Debug.contents CommandReference.contents Functions.contents Lists.contents TechnicalInfo.contents TheWizardCorner.contents Help.doc Manual for QuickHelp Help13.doc Manual for QuickHelp 1.3 Source (dir) This subdirectory contains sources for various scripts and example programs included with PowerVisor FreeError.asm These two programs crash your Amiga, stackovf.asm except when PowerVisor is running (I hope) Executables for these files are in the 'Examples' subdirectory BuggyProgram.asm Example programs used in the 'debug' tutorial BuggyProgram2.asm file. Executables for these files are in the 'Examples' subdirectory CheckBrackets.c Program to check brackets. Executable file is in 's/pv'. Source is for Lattice C 5.0 only GetCode.c Program to compute the keycode for a named key. Executable file is in 's/pv'. Source is for Lattice C 5.0 only GetQual.c Program to compute the keyqualifier for a named qualifier. Executable file is in 's/pv'. Source is for Lattice C 5.0 only Exec.struct PowerVisor source for 'Exec' structure definitions. pvsd file is in 's/pv' intuition.struct PowerVisor source for 'Intuition' window structure definition. pvsd file is in 's/pv' mkeys.explained Same script file as 's/pv/mkeys' but with a lot of comments pptest.asm Program to test the powervisor.library. Use as an example. Executable file is in the 'Examples' subdirectory takeme.asm Program to test 'debug t' Executable file is in the 'Examples' subdirectory SearchHist.asm Source for history search program. Executable file is in 's/pv' s (dir) Online help and scripts PowerVisor-help Online help file. This file contains all online help and the templates. You can't use 'help' and 'why' when this file is not present. Note that the online help file is not the good place to start learning PowerVisor. Use the tutorial files in the 'docs' subdirectory for that purpose. PowerVisor-ctrl Online help control file. Use the QuickHelp utilities to update this file when you have changed something in the PowerVisor-help file. You need this file if you want online help PowerVisor-errors All error messages for PowerVisor. You need this file if you want to make errors :-) No, you need this file if you want to see a sensible error message. Each line in this file must be 70 bytes PowerVisor-startup The startup script for PowerVisor. This script installs various new commands and keys pv (dir) This subdirectory contains all scripts you can use db PowerVisor script to install the fullscreen debugger. This script also assigns some keys to useful debugging commands ExampleSetting PowerVisor script to show an other window configuration posibility. Use as an example for more useful settings fact PowerVisor script to install a new command to compute the facultaty. Use as an example for recursive aliases CheckBrackets ML script to check for brackets in the commandline. Source is in the 'Source' subdirectory. See the 's/Powervisor-startup' file for an example of how to install this feature GetCode ML script to compute the code of a named key. Source is in the 'Source' subdirectory. Note that if you have AmigaDOS 1.3 you can only use this script to compute the code of special keys (like 'enter' and 'esc') and not of normal keys (like 'a', '3', ...). This script is installed as a function in the 's/PowerVisor-startup' file GetQual ML script to compute the qualifier of a named qualifier. Source is in the 'Source' subdirectory. This script is installed as a function in the 's/PowerVisor-startup' file SearchHist ML script to search in the history buffer. Source is in the 'Source' subdirectory. This script is installed on a key in the 's/PowerVisor-startup' file ikey This PowerVisor script installs various special features mkeys PowerVisor script for a memory display utility PrintHist.pv ARexx script to print the contents of the current history buffer PrintMode.pv ARexx script to print the current mode setting in a readable format ShowAscii.pv ARexx script to show all ascii chars on the PowerVisor window intuition.pvsd pvsd file for the Window structure. Source is in the 'Source' subdirectory Exec.pvsd pvsd file for all Exec structures Source is in the 'Source' subdirectory Examples (dir) This subdirectory contains some example programs. Sources for most of these programs can be found in the 'Source' subdirectory BuggyProgram Programs used in the 'Debug' tutor file BuggyProgram2 crash3 Some crash programs crash4 crash5 crash8 crasha freeerror stackovf pptest powervisor.library test program takeme 'debug t' test program ReadThisFirst This file pv.bugs All bugs in the current version of Powervisor Tutor files ----------- Here are all the files in the prefered order to read them tutor files : GettingStarted Expressions Screen InstallingPowerVisor LookingAtThings Debug Scripts reference files : Lists CommandReference Functions TechnicalInfo for very experienced users : TheWizardCorner (only read if you are a PowerVisor wizard !!!!!) Authors ------- André Pelckmans for the disassembler Jorrit Tyberghein for the rest Address ------- Jorrit Tyberghein Hepmansbossen 31 2450 Meerhout BELGIUM Thanks to --------- André Pelckmans for his disassembler and for giving me all the the programming help I need. Without him I wouldn't have a computer in the first place (I think). Nico François for his debugging, his numerous remarks and suggestions. Without him PowerVisor would have looked COMPLETELY different :-) (and without him I would have to use two disks to backup the source of PowerVisor) Ives Aerts for his useful suggestions and criticism. Adam Hill, Christian Weber, Steven Reiz and Dominic Giampaolo for there bug reports and suggestions. Some extra thanks to Adam Hill for his efforts to arouse interrest in PowerVisor (in BIX for example). The software people at Commodore for their VERY USEFUL debugging tools (like 'Enforcer', 'MungWall', ...). And also for their presence on usenet. Also thanks to the Amiga computer for being an Amiga.