MAG Disk (Apr 1996) : Guru3.0 / TheGuru / Docs / Guru.guide

Main
@NEXT "disclaimer"
@PREV "notetonerds"
Table of Contents
This is the documentation of:

Program  : The Guru 3.02 (February 10, 1996)
Language : Assembly
Author   : Emiel Lensink


  Disclaimer              
  Distribution             (important !)
  Postware                 (very important...)

  About gurus              (what every amiga owner should know...)
  What is 'The Guru'      
  How to use it           
  System requirements     

  Customising             
  Language files          

  History                  (important historical events...)
  Bug reports              (no...)

  The future               (updates etc...)
  The source              

  Technical specification 
 
  Kickstart 1.3 users      (time to upgrade ?)

  CrashZero               
  SimErr                  
  Faults                  


CrashZero @NEXT "simerr" @PREV "notetonerds" Table of Contents CRASHZERO: This is a very small program which causes your computer to crash with a 'Division by zero' alert. It was used during the development of 'The Guru' for test purposes. Now that 'The Guru' is finished, this program is completely useless.
SimErr @NEXT "faults" @PREV "crashzero" Table of Contents SIMERR: This program generates a recovery alert. After this program has run, you can click the 'LAST' button in 'The Guru' to retrieve the number shown in the recovery alert. This program was made for test purposes only.
Faults @NEXT "Main" @PREV "simerr" Table of Contents FAULTS: This is a small cli-only program. It lists all the dos error codes in your rom. It was made to find any undocumented dos error numbers.
Disclaimer @NEXT "distribution" @PREV "main" Table of Contents DISCLAIMER: Although I (the author) have thoroughly tested 'The Guru' and have done everything possible to make the program reliable, you use it AT YOUR OWN RISK! This software comes 'as is'; no warranties whatsoever. I am not responsible for any damage caused by using this program, either direct or indirect. If this program spontaneously low level formats your computer, crashes your harddisk, blows your nose, or melts your neighbours, I AM NOT RESPONSIBLE !!!
Distribution @NEXT "postware" @PREV "disclaimer" Table of Contents DISTRIBUTION: 'The Guru' is freely redistributable. You may give it to your friends, your neighbours, to anybody you know and don't know. Spread the word AND the disk! 'The Guru' may be included in PD libraries, on coverdisks, on CD's etc. You may archive the files as long as they are unaltered after dearchieving. The only restriction I make is that the program MAY NOT BE SOLD FOR PROFIT, and that you keep all the files together. You should have the following files: TheGuru(.info) (drawer) Guru3.0(.info) Error.data(.info) Docs(.info) (drawer) Guru.guide(.info) Guru.doc(.info) Guru.iff(.info) General(.info) (drawer) SimErr(.info) Faults(.info) CrashZero(.info) MAGICons(.info) (drawer) Guru3.0.info Sources(.info) (drawer) Guru30.s(.info) Fault.s(.info) CrashZero.s(.info) SimErr.s(.info) Gadgets.i(.info) GuruLogo.i(.info) If your set is not complete I advise you not to use the program(s), because of the possibility of viruses etc.
Postware @NEXT "general" @PREV "distribution" Table of Contents POSTWARE: This program is postware. This means that if you like it and use the program you should send me a postcard of your hometown or country. My address is: Emiel Lensink Notengaarde 33 3992JR Houten Holland If you somehow can't afford a stamp or a postcard, I'm also reachable through e-mail. My address: emiell@odie.et.fnt.hvu.nl (preferred) 4923441@ibk.fnt.hvu.nl zamorra@dds.nl (guaranteed to stay for quite a while, but local (Holland) only!!)
General @NEXT "whatisit" @PREV "postware" Table of Contents GENERAL GURU KNOWLEDGE: Every amiga owner has seen a guru message or software error as they are called in kickstart 2.0 and above at least once in his/her life. That nasty red flashing box has a purpose; the two numbers in the box can tell you why your amiga crashed. The numbers take the following form: +----------------------------------------------------------------------+ | Software failure. Press left mouse button to continue. | | | | Error: 12345678 Task: 87654321 | +----------------------------------------------------------------------+ You see two numbers here, one behind error and one behind task. The one behind task is the address in memory where the crash occurred. You can use a monitor and/or dissassembler on that address to see the instruction(s) that caused the error. The number behind error is the real important one, it tells you precisely what error occurred. There are three basic types of guru-messages, both in recovery and deadend types. 1- PROCESSOR EXCEPTIONS: This is your 680x0 speaking to you. This occurs if the processor p.e. doesn't understand an instruction. 2- SPECIFIC ALERTS: These are error codes generated by a specific subsystem of the OS., for example dos.library or graphics.library. This is the most frequent occuring kind of error. Some programs generate their own GURU alerts, but those are of course not included in the guru (cos I don't have 'em). 3- GENERAL ALERTS: The number consists of 4 parts (see diagram below) which together form a longword. (32 bits) +-+-------+--------+-----------------+ |x|xxxxxxx|xxxxxxxx|xxxxxxxx xxxxxxxx| +-+-------+--------+-----------------+ | | | | | | | Bit(s): 31 30 24 23 16 15 0 The meaning of this number is as follows: Bit 31: This decides whether a number is a DEADEND or a RECOVERY alert. If bit 31 is not set, it's a RECOVERY alert, which means that you should be able to resume work after clicking the left mousebutton. This kind of alerts usually appears in an orange flashing box. If bit 31 is set, you have a DEADEND alert, which means that your computer will reboot and you lose all your unsaved work. This type of alerts usually shows up in a flashing red box. (Note: On kick 1.2/1.3 ALL alerts show up in a red box, and a recovery alert usually reboots your computer.) Bits 24-30: The amiga operating system is divided in diferrent subsystems like dos, intuition, graphics, etc.. Every subsystem has its own code. The number here tells you which part of the operating system caused the crash. Bits 16-23: This number indicates what the operating system couldn't do, causing it to crash. This usually indicates things like OpenLibrary, CreateLib etc... Bits 0-15 : This part tells you what couldn't be opened, loaded, checked etc... This indicates another subsystem. An example: dos.library couldn't open timer.device. The subsystem code for dos.library is $07000000, the errorcode for OpenDevice is $00040000, and the code for timer.device is $00008015. This is a rather serious error, so it'll probably a deadend alert, which means bit 31 will be set ($80000000). The final alert number will be: $80000000 ! $07000000 ! $00040000 ! $00008015 = $87048015. (ps: try TheGuru on this number, it really works !!)
What is 'The Guru' @NEXT "tutorial" @PREV "general" Table of Contents WHAT IS 'THE GURU': 'The Guru' is a simple database for guru numbers, and dos error numbers. It's mainly intended as a tool for (system friendly) programmers. WHY USE IT ?: Because it makes debugging your programs quite a lot easier, since after every crash the OS finds out what went wrong, and tries to tell you using a guru or software alert; just write down the number and enter it in 'The Guru' for a description of what went wrong. No more tedious searching in books or inconcise descriptions, 'The Guru' solves it all !! Beside that (and this is useful for EVERY amiga owner) 'The Guru' also offers help on dos error numbers. You'll probably have seen something like 'Couldn't load xxx, error 205'. Just enter this number in 'The Guru' and instantaneously you know that '205' means 'Object not found'. Happy bughunting!!
Tutorial @NEXT "sysreq" @PREV "whatisit" Table of Contents BIG DUMMIES GUIDE: BUTTONS: Here's a quick description of the various buttons and slider in the 'The Guru' window: LEFT 'SET' : Activate the guru display. You can now change it's contents. RIGHT 'SET' : Activate the dos display. You can now change it's contents LEFT/RIGHT '<' and '>' : Change the cursor position in the active display. (The cursor is the brightest digit.) 'GURU' : Find the description of the current guru number. 'LAST' : Fetches the last guru number from the system. 'DOS ' : Find the description of the current dos error number. 'DEFAULT' : Sets everything to zero and shows the logo. 'ABOUT' : Shows very important information about the program. 'QUIT' : Guess... KEYS: 'G' : Pressing the 'g' key is equivalent to clicking the 'GURU' button. 'O' : Equivalent to the 'DOS' button. '<' and ',' and '<-' : Equivalent to '<' for the active display. '>' and '.' and '->' : Equivalent to '>' for the active display. 'L' : Equivalent to the 'LAST' button. 'R' : Equivalent to the 'DEFAULT' button. 'U' : Equivalent to the 'ABOUT' button. 'Q' : Equivalent to the Quit button. '[TAB]' : Switches active displays '[1] to [9] and [A] to [F] : Same as the numeric buttons. '[RETURN]' : Gets the description for the active display. Just for an example try typing this string in 'The Guru' : 'r80000005'[ENTER]
Customising @NEXT "language" @PREV "sysreq" Table of Contents CUSTOMISING: 'The Guru' can be customized using tooltypes: AUTOMATIC : Intended for use in WBStartup; The Guru will only open a window if a 'last guru' number is set. If your computer did NOT crash before starting The Guru it's very likely that no window will open. Also it's advisable that you place the datafile and/or languagefile somewhere else than in WBStartup. You can specify their locations using the LANGUAGE and DATAFILE tooltypes. AUTOFRONT : The window pops to front as soon as it's activated. (can be useful if the window is obscured by some other windows) TOPAZ : The Guru is fully font sensitive, and uses the default screen font for text and buttons. If you don't like this you can specify this tooltype to force The Guru into using Topaz 8. PUBSCREEN=Screenname : The Guru can open it's window on any public screen LANGUAGE=Filename : Different languages are supported through language files. The exact format of a language file is specified in the language section. If this tooltype is not specified, the default language (english) will be used. DATAFILE=Filename : Specifies the exact filename and optional path of the data file. If this tooltype is not specified, the default will be used, namely the file Error.data in the same directory as the The Guru program.
Language files @NEXT "history" @PREV "customising" Table of Contents LANGUAGES: The Guru uses language files for languages other than english. If you want to make your own language file, here's how: A language file is just a simple ascii file in the following format: (line numbers are for clarity, NOT for inclusion in a language file) 1 : Short description of the file 2 : Who did it 3 : (not used) 4 : Text for 'SET' button 5 : Text for 'GURU' button 6 : Text for 'LAST' button 7 : Text for 'DEFAULT' button 8 : Text for 'DOS' button 9 : Text for 'ABOUT' button 10: Text for 'QUIT' button 11: (not used) 12: Text shown if data-file not found (1 line!) 13: Response text to 12 14: Text shown if data-file corrupt (1 line!) 15: Response text to 14 16: Key shortcut for 'GURU' button (1 character, no Amiga-X or so) 17: Key shortcut for 'LAST' button 18: Key shortcut for 'DEFAULT' button 19: Key shortcut for 'DOS' button 20: Key shortcut for 'ABOUT' button 21: Key shortcut for 'PRINT' button NOTES: Keep the text for buttons SHORT. WARNING: Do not make a language file any longer or shorter than the specs above; it may lead to corrupt text output!
System requirements @NEXT "customising" @PREV "tutorial" Table of Contents SYSTEM REQUIREMENTS: 'The Guru' should run on any amiga with at least kickstart 1.2 . It has been successfully tested on the following configurations: A3000 : 2 Mb CHIP, 4 Mb FAST, Kickstart 2.04 A3000 : 2 Mb CHIP, - Mb FAST, Kickstart 1.3 A3000 : 2 Mb CHIP,12 Mb FAST, Kickstart 3.1 A500+ : 2 Mb CHIP, - Mb FAST, Kickstart 2.04 A500+ : 2 Mb CHIP, - Mb FAST, Kickstart 1.3 A500 :0.5Mb CHIP,0.5Mb FAST, Kickstart 1.2 A1200 : 2 Mb CHIP, - Mb FAST, Kickstart 3.0 The program has also proven to be 100% enforcer and mungwall proof. (Note: 'The Guru' produces one enforcer hit when clicking the 'LAST' button. I don't know if there's a non system-private field to read for the last guru number; currently I just read a long from $100...)
History @NEXT "bugs" @PREV "language" Table of Contents GURU HISTORY: version 1.0 (July 28,1993) : - Real crap version with bugs... - Released at SHN version 1.1 (Aug. 1,1993) : - Fixed all bugs (I guess) - Never really released version 2.0 (Oct. 31,1993) : This is a complete recode... - Better user interface - Better descriptions version 2.1 (Dec. 25,1993) : - Added customization by tooltypes in icon version 2.2 (Jan. ?,1994) : Fixed a bug - opened a font but didn't free it - Added zoom gadget in window version 2.21 (Jan. 6,1994) : - Window is now NOCAREREFRESH (=300% faster) - Added RMBTRAP, just looks nicer version 2.3 (Feb. 3,1994) : A lot of changes on this one... - Looks at screen palette for correct 3d buttons. (The buttons looked inversed on a kick 1.3 machine with 2.0 color palette) - Changed the logo, looks nicer - Looks good on a 2-color workbench too ! (now all text is readable...) version 2.4 to 2.6 : - Miscellaneous fixes and changes version 2.7 (Apr. ?,1994) : - Added PUBSCREEN tooltype - Fixed a bug in window centering version 2.8 (Jul. 12,1994) : - Changed format of data files slightly - Improved searching routines somewhat version 2.9 (Sep. 22,1994) : - Changed gadget rendering (8 color Wb) - Fixed a bug in the data files - Second public release !! version 3.00 (Nov. 8,1994) : - Redesigned GUI - Fully font sensitive (even on 1.3) - Added a lot of new guru and dos errors and descriptions. - Localizable (?) (even on 1.3) - Loads of other little things version 3.01 (Jun. 25,1995) : - removed busy-loop in slider-handling (now uses IDCMP_MOUSEMOVE to detect movement) Version 3.02 (Feb. 10,1996) : - Changed some small bits in the code - Added AUTOMATIC tooltype (as requested by a lot of people)
Bugs @NEXT "future" @PREV "history" Table of Contents BUG REPORTS: If you find a bug in The Guru please let me know. Write down EXACTLY what you were doing at the time the bug showed up, your configuration, and anything else that might be relevant. Also I'd like to know if you know about any guru-numbers not yet included in The Guru. My address is: Emiel Lensink Notengaarde 33 3992 JR Houten Holland I will not reply to any mail unless you include a self-addressed envelope and (if you don't live in Holland) an 'international reply coupon'. These can be optained at your local post office.
Furure @NEXT "source" @PREV "bugs" Table of Contents THE FUTURE: In my opinion 'The Guru' is completely finished, and no further updates are planned. (except for some translated versions) If you have any suggestions however, I'll be glad to hear about them, and maybe they will eventually be implemented. (with your name in the docs, Oooooh) Feb 10, 1996: Okay... this definitely IS the last version. I'm planning to translate the current version to dutch, and that's about it. No further support from me on this one. Still all postcards and e-mail is welcome, as usual :) My address is in the 'bugs' section.
Source @NEXT "tech" @PREV "future" Table of Contents THE SOURCE: Yes, it's included. It's included for instructional purposes only, the only person allowed to release updates or new versions of 'The Guru' is me. It probably won't even assemble, because I make extensive use of macro's and custom includes.
Technical specifications @NEXT "notetonerds" @PREV "source" Table of Contents TECHNICAL SPECIFICATIONS: Program name : The Guru 3.01 Author : Emiel Lensink Language : 100% highspeed assembly Features : - 101% operating system friendly - runs on all amiga's - looks pretty nice - written by me - can be configured - fully font sensitive - localizable - smooth scrolling text window - fast - can open on any public screen - written for only the Amiga Add-ons : - multiple language files (to be released) 'The Guru' was developed using the following equipment & software: - A3000 , 2Mb CHIP, 12 Mb FAST, running kickstart 3.1 - CyberVision - Personal Paint - Hisoft Devpac 3.14 - The Ultimate Graphics convertor (my own product, never finished) - Enforcer & mungwall - 3M & TDK floppy disks :)
Kickstart 1.3 users @NEXT "crashzero" @PREV "tech" Table of Contents NOTE TO KICKSTART 1.3 USERS: 'The Guru' 3.00 is still 1.3 compatible, but this is merely a patch of some routines. Some features simply don't work, and I'm not going to fix it; you fix it: UPGRADE !! The features not available are: - Can't open on public screens (you don't even have them...) - No zoom button - Amigaguide docs may or may not work - No error requesters (you don't have EasyReqArgs...) - All tooltypes must end with '=' so 'AUTOFRONT' must be 'AUTOFRONT=' - Not very thoroughly tested Now don't write any complaining letters or so because I definitely have stopped coding for 1.3 machines! Why don't you realise that you are holding back AMIGA development; 1.3 compatible programs look crippled when compared to their 2.0 only counterparts! Don't say '... but 1.3 does everything I want it to do...'. Yeah, right... Be nice to your Amiga, UPGRADE. 2.0 roms are available for next to nothing nowadays. UPGRADE.