Otherware

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

/ Otherware / Otherware_1_SB_Development.iso / amiga / programm / programi / powervis.lzh / ReadThisFirst < prev next >

Wrap

Text File | 1992-02-14 | 58.1 KB | 1,214 lines

### ## # # #### ### # # ### ## ## ### # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #/»»»#»#»»»»»#»#»»»»#»»»#»#»»»»»#»»#»»#»»»»»#»»»\# # # # # # # # # # # # # # # # # # # # ### /# # # # ### ### # # # # # #\### # / # # # # # # # # # # # # # # # # / # # # # # # # # # # # # # #\ # # / # # # # # # # # # # # # # # # \ # #/ # # # # # # # # # # # # # # # \# # # # ## ## # # # # # # # # # # # # /# ## # # #### # # # ### ## ## # #\ / \ / \ / \ / \ / \ / \ |»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»| | Introduction and general information Fri Feb 14 10:12:50 1992 | |____________________________________________________________________________| PowerVisor V1.13▀ CopyRight ⌐ Jorrit Tyberghein (feb 92) ----------------- 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. Note that I TRY to make PowerVisor as user friendly as possible (look at the emphasis on the word 'try'). In this new version for example, menus have been added (at least for the AmigaDOS 2.0 version) and some of the errormessages are better. 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 <key>. <enter> 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: <alt>+<enter>. 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 and disclaimer ------------------------ 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 (I will also add you to the list of registered users). PLEASE send money by international money order, EuroCheck (in Belgian Francs (BEF) !) 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. Note that as long as PowerVisor is in beta state, it is better to delete the PowerVisor-config file for each new version you get. 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. USE AT YOUR OWN RISK ! 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. Compatibility with PowerVisor V1.10▀ to V1.12▀ ---------------------------------------------- PowerVisor is still in beta release. This means that big changes are unavoidable. Here follow all things that have changed. If you have made ARexx programs, scripts or ML-scripts you will probably have to change some things : - The 'ScreenBase' structure (see 'TheWizardCorner') has changed. You will probably have to change and recompile all scripts using 'ScreenBase' - The 'PowerVisor-config' file is not compatible Compatibility with PowerVisor V1.00▀ and V1.01▀ ----------------------------------------------- - 'refresh' ALWAYS expects two arguments. The second argument (command) is no longer optional - New 'pvcall 17' and other pvcall commands - New strong quote operator (╖) - The '#' operator is removed. Replace it with the '\' operator : #<var> ----> \(<var>,%s) - The 'eval' function expects a string pointer instead of a string - The 'libfunc' command expects a negative argument instead of a positive one - The <maximum number of functions> argument is removed from the 'loadfd' command - 'memory', 'view' and 'unasm' work differently when another number of bytes is used (see documentation) - All error numbers have changed because the obsolete error numbers are removed - The 'PVSD' fileformat ('loadtags', 'savetags') has changed. There is no way to convert. You need the original source (.struct file) - 'why' command is gone and is replaced with an alias in the standard PowerVisor-startup file - Many fields described in 'TheWizardCorner' have changed. Some pvcall functions have become obsolete and DO NOT work anymore. Some pvcall functions have been REPLACED with others - The PowerVisor expression evaluator is more strict. You MUST close ALL brackets (also {} brackets) - PowerVisor commands called from ARexx are not interruptable anymore with <esc> - Important change in the logical window system. (See the changes section for more details) - Major change in the history buffer mechanics. The history buffer list has changed (see 'TheWizardCorner') - The File format of s:PowerVisor-config has changed ! Please delete this file first before you start the new version of PowerVisor !!! - Commandline options for PowerVisor are removed since they were not very useful - 'scan' works differently. You don't need to free the string allocated with 'scan'. The pointer to the input string is NOT returned in 'rc' but in the predefined constant 'INPUT' - The number of pens in the pentable has changed from 16 to 24 The development cycle --------------------- I started development of PowerVisor (February 1989) on an Amiga 500 with two diskdrives and one megabyte of memory. (except for holidays, I only programmed in the weekends since I was at my university for the rest of the week) PowerVisor (at that time called 'PowerBase') was going to be a structure viewer. The 'list' and 'info' commands are in fact the most ancient commands in PowerVisor (except maybe the 'quit' command :-) At that time I did not think about writing a debugger. I could not even write one if I wanted to. After all, PowerVisor was only my second machinelanguage program on Amiga and I was still learning machinelanguage. (my first program in machinelanguage was a little program to blink the powerled, I made this program together with someone else :-) (In fact PowerVisor is also my last machinelanguage program, I normally program in C) I bought my first harddrive about five months later (30 megs). In September 1990 I bought my Amiga 3000/16/40! Needless to say this was a great development boost. I almost immediatelly expanded my Amiga to 4 megabytes of memory. In August 1991 I bought a second harddrive (52 megs) for my Amiga 3000. At this moment (February 1992) the PowerVisor source is approximatelly 34000 lines long and all other ascii files (help files, scripts, ...) are also approximatelly 34000 lines. Conclusion : If I were to start all over again, I would not use machinelanguage (or perhaps only for the exception handling and other special code). It is too much work. At this moment I don't regret my choice of machinelanguage, but this is only because I already have programmed all support routines and making some new PowerVisor command or other feature is simply a matter of calling the right routines (more or less). 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 (at least) 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 Describe all output (including flashing lights, strange sounds, noises, ...) History ------- V1.00 : - first release (on tapserv and ab20.larc.nasa.gov) V1.01 : - Bug fix : when 'mode fancy', 'mode nofancy', 'mode lace' or 'mode nolace' failed (for example, because there is a visitor window open on the PowerVisor screen) we didn't restore the current mode. This means that when you tried again later (after closing the visitor window) PowerVisor would ignore the command - Bug fix : when the 'mode' command failes because there is not enough memory, we first try again with the old mode settings before quitting PowerVisor - New feature : new 'stack' command and 'getstack' function to monitor stack usage for a specific task. 'stack' uses the timer.device for very fast respons - We removed an obsolete feature from 'refresh'. The optional command argument is no longer optional - The standard logical window commands have an extra optional argument. With this you can specify the number of lines for a logical window - The previous new feature is also included in the 'openlw' command - Bug fix :Logical windows are much more stable with big fonts and small visible sizes. No more crashes when the logical window is too small - Bug fix : parsing of [<x>] operator in alias strings was not completely correct. Because we did not ignore the operator if <x> was no digit we could not quote the operator. This is solved - New PowerVisor debug mode accessible with 'pvcall 17'. This debug mode is useful if you want to debug aliases, scripts, key attachements or other special things in PowerVisor. Every command is printed on the screen before it is executed - Bug fix : 'if' function now always correctly parses the arguments. Because of some very obscure bug it could happen that the 'if' function parsed to much characters from the string - Added strong quote operator in strings because I needed it in the 'salias' alias - The '#' operator is removed because the same functionality is already present in the quote operator '\'. Just use \(<x>,%s) instead of #<x> - Behaviour of the 'eval' function has changed ! 'eval' now expects a string pointer (or normal pointer) instead of a string. This turned out to be more useful - Limitation removed in 'colrow' and 'fit' commands. It is now possible to size the 'debug' logical window - Bug fix : The 'colrow' and 'fit' commands are now very stable. When an out of memory error occurs, they simply try again for the old values. If this also fails PowerVisor will quit (in the previous version a command like 'colrow 30000 30000' would crash your amiga) - Behaviour changed for 'libfunc' command : the offset argument must be negative and only the 16 least significant bits are used. Thus something like $ff30 is a valid offset (this is also the format given by the disassembler) - Bug fix : The 'loadfd' command now handles multiple ##bias statements in fd-files correctly. In V1.00 all functions where correctly loaded but not correctly counted. The effect of this was that 'info <fd node>' did not show all functions in the fd-file - Removed a completely useles feature from 'loadfd' : it is no longer possible to specify the maximum number of functions to load. 'loadfd' always loads the complete fd-file - Added workbench startup - Startup is cleaner. We don't crash anymore if the wrong PowerVisor is used on the wrong operating system. We are also a lot more stable in low memory conditions and other wierd environments - We didn't close dos.library - New 'Aliases' reference file explaining all aliases defined in s/PowerVisor-startup and s/pv/ExtraAliases - New aliases in s/PowerVisor-startup (salias and fdebug) - The 'db' script is better. Opens a fixed size logical window so you don't need to size it everytime you use the fullscreen debugger. 'db' also redefines 'fdebug' to clean up the fullscreen debugger - New 'ExtraAliases' script to define some extra aliases - Created flexible install script V1.10 : - Bug fix : PowerVisor no longer crashes when a logical window is made too small - Removed incorrect statement in 'CommandReference' about 'fit' and 'colrow' not suitable for the 'debug' logical window - Incorrect statement in 'Screen' removed. The 'debug' logical window is 90 columns instead of 82 - New function 'lastbytes'. This function returns the last number of bytes used with the 'memory' or 'view' command - New function 'lastlines'. This function returns the last number of lines used with the 'unasm' command - 'memory', 'view' and 'unasm' remember the number of bytes or lines viewed (see the previous functions) and will continue with this number at a later time - New aliases 'cm', 'cv' and 'cu' to continue 'memory', 'view' and 'unasm' respectivelly without setting a new address. You can set the number of bytes or lines though - Bug fix : we don't allow illegal variable names any more - Finally all obsolete errors are removed - Bug fix : 'LoadTags' and 'SaveTags' correctly handle structures. When you try to load previously saved tags, PowerVisor will check if the structure exists and will use this pointer instead of the old one. If the structure does not exist, PowerVisor will change the type of the tag to Long/Ascii and give a warning at the end of the loading - Behaviour changed : 'LoadTags' no longer clears the current tag list but adds the tags from the file to the current tag list - Note that the PVSD file format has changed (used for 'LoadTags' and 'SaveTags'). PowerVisor does NOT understand the format used by PowerVisor V1.00 and V1.01 - Install script is better. We check if the files exist before we try to copy them. If a file doesn't exist we ask another pathname to the user. This means that you can distribute PowerVisor on different disks (in fact you will have to distribute PowerVisor on different disks if you don't compress the files). The installation script won't give errors because of non existant files. Simply put the other disk in the drive - We print more information in the cli structure (with the 'info' command) - New glossary file for explaining some specific PowerVisor terminology - 'Why' command is gone. It is more efficient to define an alias for 'why' in s/PowerVisor-startup - Some optimizations, PowerVisor is a bit shorter. This has some effect on some internal fields. See the 'TheWizardCorner' file for more info about the format of the commands in the routine table - Because of the previous optimization there are no more commands working in ARexx but not in PowerVisor and vice versa. You can now use the 'front', 'hide', 'sync', ... commands in PowerVisor too. And the 'clip' and 'remclip' commands work in ARexx - Some new 'pvcall' functions for logical windows - Bug solved in 'salias' alias. This alias loosed memory everytime we runned it - The 'co' function (or 'GetCode' ML-script) will not crash anymore if used in AmigaDOS 1.3 with a non special key. The function will return 0 instead - A complete new directory 'PVDevelop' for the PowerVisor Wizards. This subdirectory contains include files and libraries useful to make ML-scripts in C or machinelanguage - New assign : 'pv' to the root of the PowerVisor subdirectory. This assign is only used by the develop files - 'openlw', 'openpw', 'xwin', 'rwin', 'owin', 'awin' and 'dwin' give an error when there is not enough memory. In the previous version, the memory failure was simply ignored - No more ugly flickering of the BUSY prompt when executing ARexx scripts - Bug solved in 'unasm' with very long instructions. The hexadecimal words would overwrite the instruction - New 'bin' alias in s/PowerVisor-startup to show the binary representation of a number - New 'asm' alias and s:pv/assem.pv ARexx program for a simple assembler. See s:pv/assem.pv for more info about the assembler - Two new 'pvcall' functions to disassemble one line of memory in a string (s:pv/assem.pv uses this) - The PowerVisor expression evaluator is more strict. You MUST always close all brackets. I have done this because there were some problems (especially in 'alias') if badly formed expressions are used - The same is true for the group operator - New 'cmd' alias and ARexx script to execute Cli commands from within PowerVisor - Bug solved in strong quote parsing - PowerVisor commands called from ARexx are not interruptable anymore with <esc> - Important change in the logical window system. Input is now local to a logical window. This means that when a command waits for input (either a line of input or a key (-MORE- for example)) all other logical windows will be locked. This means that accidently hitting a key will not have undesirable results. All input is redirected to the active logical window (the one with the full (blue) titlebar) - <esc> and <ralt>-<help only work for the output appearing on the 'ACTIVE' logical window, so you have to use <tab> to interrupt a command running on another logical window (also see the previous item) - Note that the stringgadget still behaves weird in AmigaDOS 1.3 If anyone out there knows a legal way to UNSELECT (UnActivate) a stringgadget I would appreciate it very much. In AmigaDOS 2.0 simply removing the gadget and adding it again is enough to unselect the gadget, but this does not seem true in AmigaDOS 1.3. - New 'event' command to add an input event to the main handler. This is useful for macros (key attachements) - The AmigaDOS 1.2/1.3 version of PowerVisor doesn't need arp.library anymore (I needed it only for the 32 bit multiply and divide. I have now put these two routines in pv13) - Fixed yet another bug in the structure viewing and the 'info' command. If the list item in a structure was a string, there would be some strange characters after the string - Many bugs and errors are corrected in the online help and tutor files - AT LAST ! Mstruct is converted to AmigaDOS 1.2/1.3 ! Now you can make your own structures and use them in PowerVisor even if you don't use AmigaDOS 2.0 - Major change in the history buffer mechanics. The history buffer now works like in the AmigaDOS 2.0 shell. It is no longer a circular list (how coud I ever have such a bad idea :-) This means of course that s:pv/PrintHist.pv, s:pv/SearchHist and Source/SearchHist.asm have changed a bit. I hope you had not written anything using the internal structure of the history buffer, because you will have to change your programs if you did - At last ! The autorepeat bug in the AmigaDOS 1.2/1.3 version of PowerVisor is solved. You can now scroll in the history buffer and in the logical windows with autorepeat - Although it was already possible to set a font for a logical window, this could not be done automatically and the stringgadget and logical window size bars remained in topaz 8. Now it is possible to set the default font for PowerVisor (with 'prefs font'). This font is used for all new logical windows (you can of course still change this font when the logical window is already open), for the stringgadget, for the logical window size bars and for the screen. - WARNING !!! The File format of s:PowerVisor-config has changed ! Please delete this file first before you start the new version of PowerVisor !!! - Commandline options for PowerVisor are removed since they were not very useful - All the 'prefs' commands have a more readable output. I use decimal output when decimal is more appropriate than hexadecimal - Some pvcall functions are removed because they were obsolete (Signal command and IDCMP command) - MAJOR ! The AmigaDOS 2.0 version of PowerVisor finally supports menus. You can make your own menus with your favorite commands in it. I'm very sorry, but this is only for the AmigaDOS 2.0 version - When 'reqtools.library' (⌐ Nico Franτois) is available, PowerVisor will use this library for requesters with the new commands : 'reqload', 'reqsave', 'request' and 'getstring' Otherwise, simple PowerVisor constructions are automatically used : 'scan', 'key()' - There is a new predefined constant 'input'. This constant contains the pointer to the last input string (with 'scan', 'getstring', 'reqload' and 'reqsave'). You don't have to worry anymore about freeing all the strings allocated with 'scan' - Bug fix in 'debug l' and 'debug n'. We did loose some memory when the loading failed or when 'debug n' was interrupted by the user - More predefined pens (24 instead of 16), 19 of these pens are used - Four new pens for the colours of the stringgadget (only AmigaDOS 2.0) - Bug fixed in 'symbol' command. PowerVisor sometimes said there were no symbols even if it previously loaded them. This bug was harmless but I fixed it anyway :-) V1.11 : - We look at PROGDIR: in AmigaDOS 2.0 to see where our files are This means that the following path is used for the PowerVisor-startup, PowerVisor-menus, PowerVisor-help, PowerVisor-ctrl and PowerVisor-errors files : First check PROGDIR: (only AmigaDOS 2.0) Check S: Check current directory In practice this means that you can keep this files together with PowerVisor - PowerVisor1.0.task is renamed to PowerVisor.task - intuition.struct is expanded to handle almost all Intuition structures - Bug fix in 'trace c' (conditional trace) command. This command only occasionally worked. In most cases this command would return an error. This is fixed - 'break c' is also fixed (the same bug as in 'trace c') V1.12 : - Some errors fixed in the include files. dbn_LoadedSegment is a BPTR and not an APTR - Bug in 'tags' command solved. This command was broken in V1.11 (and maybe earlier) - Bug in include files solved. We don't use absolute pathname anymore in the .i include files for the PVMemory.i include file. If you have any problems with this you should include this file first in your source before you include any of the other include files. This should solve all possible problems - ScreenBase.i and ScreenBase.h contained a double declaration of 'LockPrompt'. The second 'LockPrompt' has been changed to 'PtrLockPrompt' - Floating point debugging is fixed for AmigaDOS 2.04 (V37.175) - Primitive support for floating point debugging with the 'fregs' command. This command displays the 8 floating point registers for a task (only if the task uses floating point) in the internal format (the format used on the Exec stackframe). Wait for future releases for more and better floating point support - New 'debug u' command. Use this command instead of 'debug r' when you have used 'debug l'. If you have used 'debug n' it is often better to use the old 'debug r' - Little change in assembler (assem.pv). Addressing mode (4) will default to (4).l (for example) - PowerVisor uses the Exec CacheClearU function to clear the cache (after setting breakpoints for example) instead of own routines if AmigaDOS 2.0 is used V1.13 : - Bug solved in 'GeneralBase.h' - Bug solved in 'debug', 'break' and 'symbol' if no arguments were given to the command - You can now use the '@sr' register in register assignment and you can also use the value of '@sr' - '@a7' is now equivalent to '@sp' - Bug solved in the changing of the stackpointer '@sp=xxx' - New 'scratch' option for the 'addfunc' command. This option makes the scratch registers ('d1', 'a0' and 'a1') illegal - The 'mmuregs' command should work with an 68020/68851 (I hope) - New option added to the 'debug' command ('c'). With this option you can catch the next task in the system (not the next process like 'debug n') - Powerful new command to track the usage of resources for a task or process ('track'). Note that this command is not completely ready. In future I plan more extensive checking. There should also be a easy way to let a program run and stop it before it quits. That way you can better examine what went wrong - Symbols are correctly loaded in all cases (I hope). Previously PowerVisor would load incorrect symbols if there were hunks without symbols in the file. This is solved - Bug in the window system solved. Autoscale (-1,-1) did not work as described in the manual - Bug solved in 'prefs pens' command. It was not possible to set a pen number greater than 32 - Two new pens defined for hilighting. There is also support for hilighted text - Source level debugging implemented for 'Macro68'. New 'source' command. This source level debugging is still rather primitive. In future more features and easier ways to scroll will be added - Source level debugging implemented for SAS/C. Compile C program with '-d1' option (must be 1 !) to use - The fullscreen debugger also uses hilighting instead of the '|' character to indicate the program counter - The 'refresh' command does not require the 'Refresh' logical window to be open. If this window is not open, the output will be send to the current logical window - New 'Source' logical window (with corresponding 'swin' command) for the source level debugger. Note that this means that you have to delete the old 'PowerVisor-config' file before you run the new PowerVisor - There are more menus in the PowerVisor-menus file - The 'icopy' script and the 'CopyLogWin' and 'GetLogWin' programs have been recompiled because the internal 'ScreenBase' structure has changed - New arguments for 'mode' command: 'intui' and 'nointui'. When 'intui' is set all standard window command ('xwin', 'awin', 'dwin', ...) will open a new physical window (Intuition window) that contains the standard logical window - When a physical window opens, PowerVisor no longer activates this window - 's:pv/PrintMode.pv' has been changed to incorporate the new 'mode' variables - Bug solved in the handling of requesters with ReqTools. When you changed the PowerVisor screen, PowerVisor would sometimes prevent requesters from appearing. This is now solved - 'prefs startup' and 'prefs window' have been removed. 'SaveConfig' will automatically look at the current window size and position and use the information from that. This approach is much more userfriendly - You can scroll in the source with the mouse (source level debugging) - Source level debugging seems to work for Devpac3 too - Bug solved in the scroll routine (bug was not visible) - The MMU commands should work on a 68020/68851. Previously this was not the case - The 'mmuregs' command shows a 68851 only register: 'DRP' if you have a 68851. I have not been able to test this feature (I have a 68030) - 'mmuregs' will print '(na)' (not available) for all registers not available on your Amiga - The 'debug' command is MUCH better if you have AmigaDOS 2.0 (I'm sorry for all the 1.3 users). 'debug' does not loose any memory (as far as I have been able to test) and you can use 'debug u' with a program loaded with 'debug n'. I used the new 'CreateNewProc' function in AmigaDOS 2.0 to achieve these results - If you have AmigaDOS 2.0, 'debug l' will create a CLI structure for the process. Previously this was not the case, making it almost impossible to use 'debug l' on programs supporting the Workbench (The startup code would assume the program was started from Workbench because there was no CLI, and would wait in vain for the Workbench message) All files --------- 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 Program to convert pseudo include files to pvsd files. This program will be enhanced in future to support full include files. MStruct13 AmigaDOS 1.3 version of MStruct pv AmigaDOS 2.0 version of PowerVisor pv13 AmigaDOS 1.3 version of PowerVisor Input Little program needed for the installation script. 'Input' prints the first argument on the screen and waits for input. The input is put in the specified file (second argument). Syntax : Input <prompt line> <file name> DevName Little program needed for the installation script. 'DevName' reads the first line from a file and replaces the same file with another file containing only this first line altered in the following way : if the first line ends with a ':' nothing happens If the first line ends with a '/' nothing happens Otherwise a '/' is appended to the first line Syntax : DevName <file name> DirName Little program needed for the installation script. 'DirName' is equivalent to 'DevName'. 'DirName' removes the last character of the first line if it is a '/'. Syntax : DirName <file name> libs (dir) All libraries needed by PowerVisor 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 Aliases This file explains everything about the aliases defined in s/PowerVisor-startup and s/pv/ExtraAliases 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 Glossary The PowerVisor glossary, reading this file is a very good way to learn all (or most) PowerVisor terminology TechnicalInfo Some technical information TheWizardCorner Only for VERY experienced users. Using this file you can customize PowerVisor to enormous degrees. Look in the 'Source' directory for examples using information from this file. Also look at the 'PVDevelop' directory useful for making your own powerful scripts (and ML-scripts) Global.index The index for all above files GettingStarted.idx The individual index files for all tutor Expressions.idx and reference files Screen.idx Aliases.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 Aliases.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 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 ExtractIndexSE.rexx This rexx script is used by 'MakeIndex.se' to construct the index file for one individual tutor file 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. This version uses the 'egrep' (or 'gnugrep') command by 'Free Software Foundation, Inc.' This version is faster than 'MakeIndex.se' but you need 'egrep' of course ('egrep' is not distributed with PowerVisor) MakeIndex.se Make the index and contents file for one tutorial file. This version uses the standard AmigaDOS 'search' command, but it is slower 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' PVDevelop (dir) This subdirectory contains include files and libraries useful for PowerVisor Wizards. There are include files for C and machinelanguage include (dir) Subdirectory containing all include files for PowerVisor (except for the powervisor.library include files because these are in another subdirectory) PV (dir) The recomended place for the include files ARexxBase.h The ARexx Base structures ARexxBase.i DebugBase.h The Debug Base structures DebugBase.i EvalBase.h The Eval Base structures EvalBase.i FileBase.h The File Base structures FileBase.i GeneralBase.h The General Base structures GeneralBase.i ListBase.h The List Base structures ListBase.i MainBase.h The Main Base structures MainBase.i MemoryBase.h The Memory Base structures MemoryBase.i ScreenBase.h The Screen Base structures ScreenBase.i PVCallRoutines.h Protos for the PVCall routines PVCallTable.h Table with PVCall routine numbers PVCallTable.i PVMemory.h PowerVisor memory allocation structures PVMemory.i Lib (dir) All the C libraries (for SAS/C) to make calling PVCall functions from C easier PVCallStub.lib The library for small code PVCallStubNB.lib The library for large code Source (dir) The source for these libraries README A README explaining some things. If you 'execute' this file, the two libraries will be build again PVCallStub.i Include file needed for all functions makefile makefile used by 'README' PVCBeep.asm All sources for all PVCall functions PVCError.asm PVCAddAutoClear.asm PVCAddGlobalAutoClear.asm PVCAddStringToHist.asm PVCAdvanceHistory.asm PVCAllocPVBlock.asm PVCAppendString.asm PVCCallMLScript.asm PVCClosePVHandle.asm PVCCompareStrings.asm PVCComputeGadgetSignal.asm PVCConvertAlias.asm PVCCopyString.asm PVCCreateConstant.asm PVCCreateFunction.asm PVCErrorHandler.asm PVCEvaluate.asm PVCFreePVBlock.asm PVCGetARexxBase.asm PVCGetDebugBase.asm PVCGetEvalBase.asm PVCGetExecLevel.asm PVCGetFileBase.asm PVCGetGeneralBase.asm PVCGetHistoryLine.asm PVCGetListBase.asm PVCGetMainBase.asm PVCGetMemoryBase.asm PVCGetModeRoutines.asm PVCGetRexxList.asm PVCGetRoutines.asm PVCGetScreenBase.asm PVCGetSnapBuffer.asm PVCGetStringGadget.asm PVCGetStringGBuf.asm PVCGetStringInfo.asm PVCGetVarAddress.asm PVCInstallPostCmd.asm PVCInstallPreCmd.asm PVCInstallQuitCmd.asm PVCInstallSnapCmd.asm PVCLowerHistory.asm PVCParseString.asm PVCPrint.asm PVCPrintNum.asm PVCReAllocPVMemoryBlock.asm PVCReAllocPVQuickBlock.asm PVCRefreshLogWin.asm PVCRefreshStringG.asm PVCRemoveGlobalAutoClear.asm PVCRemVar.asm PVCSetCursorPos.asm PVCSetDebugMode.asm PVCSkipSpaces.asm PVCSnapWord.asm PVCDisassemble.asm PVCCmdDisassemble.asm PVCPutChar.asm s (dir) Online help and scripts PowerVisor-menus Only for the AmigaDOS 2.0 version. This file contains the description of the menus used in PowerVisor. The format is not difficult. You can change this file if you'd like other menus 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 ExtraAliases This file contains some extra useful aliases not defined in the s/PowerVisor-startup file icopy PowerVisor script to install a logical window copy feature. Press 'Shift-PrtSc' to store the active logical window in an internal buffer. Press 'PrtSc' to retrieve this buffer into another active logical window. This script uses 'GetLogWin' and 'CopyLogWin' 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 CopyLogWin ML script to copy the active logical window to a buffer. This script is used by 'icopy'. Source is in the 'Source' directory GetLogWin ML script to copy a buffer to the active logical window. This script is used by 'icopy'. Source is in the 'Source' directory 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 Assem.pv Little ARexx assembler. Use the 'asm' alias defined in s:PowerVisor-startup to call this script. See the script for more info about the script 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 Install Execute this file to install PowerVisor or click on icon from WorkBench Install.script Install script used by 'Install' (Don't execute this) Environment ----------- PowerVisor normally does not expect special assignments or such. s/PowerVisor-startup however does expect 'fd' to be assigned to the subdirectory containing fd-files (at least exec_lib.fd, dos_lib.fd, graphics_lib.fd and intuition_lib.fd). If you do not have these fd-files (note that you can find them on the AmigaDOS 1.3 Extras disk) you must remove four lines in s/PowerVisor-startup starting with '-lfd'. You will not be able to use the library functions defined in the fd-files if you do this (Note that PowerVisor makes very good use of these fd-files, so I recommend that you install them if you have a harddisk). s/PowerVisor-startup also expects the following files in the s:pv directory : db, CheckBrackets, GetCode, GetQual and SearchHist. You can of course adapt s:PowerVisor-startup to your own wishes. If you have reqtools.library (by Nico Franτois) PowerVisor will use it for requesters. In the next distribution of PowerVisor, reqtools will probably be included with all the other files. If you use AmigaDOS 1.2 or 1.3 I recommend that you use 'FastFonts' (FF) by C.Heath. This program greatly speeds up the PowerVisor display. This is not necessary in AmigaDOS 2.0 since Commodore did a good optimizing job. If you use AmigaDOS 1.2, 1.3 or 2.0 and you have a fast processor (68020 or higher) I recommend that you use 'CpuBlit' by Eddy Carroll. This program gives an even greater speed increase. Installation ------------ Installing PowerVisor should be easy. Simply execute 'Install' (with the current directory set to the root directory of the PowerVisor distribution) or double click on the icon. You will get an interactive install session. Note that the installation script has only been tested in WorkBench 2.0. I hope it works with WorkBench 1.3. The installation script does NOT work with WorkBench 1.2. I tried to make the script as simple as possible but I failed :-) (Note! It appears that the script does not work in 1.3, I will try to fix it) Note that the script needs the following cli commands : - setenv (builtin command in AmigaDOS 2.0) - if (builtin command in AmigaDOS 2.0) - else (builtin command in AmigaDOS 2.0) - endif (builtin command in AmigaDOS 2.0) - skip (builtin command in AmigaDOS 2.0) - lab (builtin command in AmigaDOS 2.0) - ask (builtin command in AmigaDOS 2.0) - echo (builtin command in AmigaDOS 2.0) - endcli (builtin command in AmigaDOS 2.0) - makedir - copy - version - delete - dir - input (included in the PowerVisor distribution) - devname (included in the PowerVisor distribution) - dirname (included in the PowerVisor distribution) Tutor files ----------- Here are all the files in the prefered order to read them tutor files : GettingStarted For the first time user Expressions Very important to read Screen InstallingPowerVisor LookingAtThings Debug Scripts reference files : CommandReference Very useful file Functions Aliases Lists TechnicalInfo if you want to look up a specific word : Glossary 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 B-2450 Meerhout BELGIUM Thanks to --------- AndrΘ Pelckmans for his disassembler and for giving me all 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) Nico Franτois for his WONDERFUL reqtools.library. If you want to use well designed, flexible and powerful requesters there is no better choice Ives Aerts for his useful suggestions and criticism. Adam Hill, Christian Weber, Steven Reiz and Dominic Giampaolo for their bug reports and suggestions. Some extra thanks to Adam Hill for his efforts to arouse interrest in PowerVisor (in BIX for example). Adriaan van den Brand for his good suggestions and information The software people at Commodore for their VERY USEFUL debugging tools (like 'Enforcer', 'MungWall', ...). And also for their presence on usenet. To my parents of course. Also thanks to the Amiga computer for being an Amiga. __ /// /// /// __ /// \\\ /// Amiga, the computer for the creative mind \\\ /// \\\/// \XX/