************************************** * * * Captain Hook 1.0 * * by John Eidsvoog * * Copyright 1991 John Eidsvoog * * * ************************************** Release date: Friday, December 6, 1991 > Captain Hook is shareware and may be distributed freely as long as > this text file is included, but may not be sold commercially or > included with a commercial product without written permission from > John Eidsvoog. Captain Hook is free to legitimate owners of MIDI > Spy. All other users of Captain Hook are expected to register their > copy by sending a shareware payment to the address listed below. What it is ---------- Captain Hook "unhooks" other resident programs and accessories in order to eliminate conflicts with the programs you use. This is especially useful with MIDI programs that seem to get overflow problems or simply don't work when some resident software is installed. Captain Hook's usefulness is not limited to MIDI programs, though. It can be used to solve almost any program conflict. For instance, if you find that a program doesn't work with a screen accelerator installed, you can probably make it work by listing that program in your CAPTHOOK.DAT file with a "2" to unhook trap 2. The operation of Captain Hook, by its very nature, may be a bit difficult to understand. I fully realize that this program is going to cause a lot of confusion for those who try to use it. Help and tips on using Captain Hook will be provided on the GEnie on-line service, in the Atari ST Roundtable's CodeHead Category 32 in the Captain Hook topic. I will try to explain the operation of Captain Hook in this document in a way that everyone can understand it. Even though this description is quite technical, please try to read it in its entirety to understand how Captain Hook works. How to set it up ---------------- Although Captain Hook can be installed from the desktop, it is intended to be run from your AUTO folder. If you do not already have an AUTO folder, you should create one using the desktop or a file maintenance tool such as MaxiFile. Copy CAPTHOOK.PRG into your AUTO folder. The programs in your AUTO folder run when you boot up your computer. The order in which AUTO programs are executed may be important, depending on the program. This execution order is determined by the order in which they are internally stored in your AUTO folder directory and may not have any correlation between their alphabetical order or even the order in which you copy them into the AUTO folder (dependent upon whether some programs have been deleted). Although CAPTHOOK.PRG can be placed at any execution point in your AUTO folder, its placement will affect how it interacts with your programs. This is explained in more detail below (AUTO folder placement), but in general it's best for Captain Hook to run before any other programs which grab vectors. Upon copying CAPTHOOK.PRG into your AUTO folder, it will probably become the last program in the execution order. The easiest way to rearrange the order of your AUTO programs is with the Auto Organizer program in the CodeHead Utilities package. If you don't have Auto Organizer or any other method of changing the execution order, you should copy all of your AUTO programs to another location (or simply rename AUTO and create another AUTO folder if you have that capability) and copy the other programs back into your AUTO folder in the order you want them to run. After installing CAPTHOOK.PRG in your AUTO folder, you'll need to create and install a CAPTHOOK.DAT file. This is explained below (The Captain Hook DAT File). CAPTHOOK.DAT must be located in the root directory of your boot drive. This will usually be drive C if you use a hard drive or drive A if you are a floppy disk user. NOTE: If you are going to be installing Captain Hook from anywhere other than the AUTO folder, CAPTHOOK.DAT should be in the _same_ directory as CAPTHOOK.PRG. How it works ------------ Captain Hook deals with the Atari's system vectors. When you install a resident program or accessory in your system, it may intercept one or more system vectors. A vector is something that points to another location. This pointing allows programs to redirect the flow of control in your computer and jump in at the appropriate time to provide some (hopefully) useful function. Many system vectors are also referred to as interrupts since it is their function to interrupt the operation of the computer for various tasks. For an example, let's examine CodeKeys, the Macro Tool from CodeHead Software. CodeKeys examines the keys that you press to determine whether it should intercede with a macro. When you press a key on your keyboard an electrical pulse is sent to the master controller of operations in your computer (the Central Processing Unit, or CPU). This causes the CPU to "hold everything" and go see what the keyboard wants and it does this by looking at the keyboard vector. This is a location in memory containing an address. The address tells the CPU where to go to find the one in charge of handling the keyboard stuff. If nothing is installed in your computer, this address will point into the ROMs and the CPU will go "knocking on the door" at that address. Returning to our CodeKeys example, CodeKeys runs in the AUTO folder and installs itself in the keyboard vector. It does this by saving the address that is currently in the vector and replacing it with its own address. Now when a key (for example, Control-A) is pressed, the CPU goes knocking on CodeKeys' door and says, "I have a letter here for Control-A. Will you sign?". CodeKeys looks in its notebook, determines whether it should handle it and either says, "Yes, I'll take it", or "No, that should be forwarded to:" (supplying the address that was previously in the keyboard interrupt). I know this is getting complicated but we're almost done. As other programs also install themselves in the keyboard interrupt, each one saves the address that is there and replaces it with its own. This causes the flow of control to pass through each program whenever a key is pressed. When the CPU comes knocking, it may have to go to a number of different doors where nobody wants to sign for the letter before finding someone who'll take the responsibility. In fact, on the Atari, the same interrupt is used for keyboard, mouse, MIDI, and joystick. This creates a real bottleneck when a lot of programs are installed, or even just one program that takes a lot of time to decide he doesn't want the letter or is simply very slow signing his name. This is why many MIDI programs have a hard time living with resident programs. MIDI data enter the MIDI IN port at a high rate of speed. Each byte of data that comes in must be handled before the next one arrives or it will be lost. Each time a byte arrives at the MIDI IN port, an interrupt is generated and the CPU "goes knocking". If the CPU can't arrive at the door of the guy who's handling the MIDI data and get back to the main station before another MIDI byte comes in, that data will be lost. This is where Captain Hook comes in. When it installs, it takes note of all of the important vector addresses as they currently exist and saves them in its notebook. This is why the order of execution is important because Captain Hook will be saving the currently installed vectors and will not be able to bypass any resident programs which are already installed. The Captain Hook DAT file ------------------------- Once installed, Captain Hook waits for you to run programs. Every time you run one of the programs listed in your CAPTHOOK.DAT file, it will replace any of the vectors you've listed for that program with the vectors it has stored from its initialization. This allows you to effectively bypass or cut-out any programs which have intercepted those vectors between the time Captain Hook was installed and the time you run a program listed in CAPTHOOK.DAT. CAPTHOOK.DAT is simply an ASCII text file. You can use any text editor or most any word processor to create it. The requirements are as follows: 1. The first four characters of the file must be "HOOK". 2. It cannot be longer than 4096 bytes. 3. Up to 32 programs can be listed. 4. Each program must be at the beginning of its own line, followed by one or more spaces and the vector codes for that program. 6. Vector codes (listed below) are single characters denoting vectors to be restored by Captain Hook. 5. Comments may be placed in lines beginning with a semi-colon (;). 6. Lines must end with a carriage return (ASCII 13). 7. Blank lines are allowed and are ignored. Vector codes: A = line A Rarely used F = line F Almost never used 1 = trap #1 Used by GEMDOS 2 = trap #2 Used by GEM, GDOS, alternate file selectors, screen accelerators 3 = trap #13 Used by BIOS, spoolers 4 = trap #14 Used by XBIOS T = 200Hz interrupt Various uses including Spectrum 512 K = kb/MIDI interrupt Used by some programs providing "hot keys", such as CodeKeys m = TOS mouse vec Almost never used I = ikbdsys vec Used by many programs with "hot keys" such as HotWire, PinHead, PopIt, HotSaver, and Funk Alert V = vbl (plus queue list) Used by many and varied programs M = GEM mouse vector Used by mouse accelerators and other programs such as Little Green Selector and HotSaver S = MIDI in/err/sys Used by MIDI programs B = remainder of KBDVBAS (KBerr/KBstat/clk_pack/joy_pack) May be used (?) Example CAPTHOOK.DAT file: ------------------------------ HOOK BBS.TOS A3K CAL.PRG 2 SMPTETRK.PRG KIS ------------------------------ A sample CAPTHOOK.DAT file is included with this package, containing commented lines with all of the vector codes listed above. This eliminates the need for you to remember all of the codes when you are making changes to your DAT file. Here are some of the popular resident programs and the interrupts they use. This does not mean that you have to "hook" all of their vectors, but it might give you a better idea how they might be interacting with your programs. PINHED18.PRG 1,V,I POOLFIX4.PRG 1 CODE_RAM.PRG I (only if piggy-backed or print spooler installed) CODEKEYS.PRG 1,4,V,T,K REGACC.PRG 1,2,3,I G+PLUS.PRG 1,2 HOTSAVER.PRG 2,3,4,V,T,I,M LGSELECT.PRG 1,2,3 HOTWIRE.PRG 1,2,3,4,V,T,I FUNKALRT.PRG 2,3,I SENTINEL.PRG 1 TOS14FIX.PRG 4,F Hooking trap #2 will bypass any alternate file selectors you have installed. NOTE: If you are "hooking" trap #2, it is sometimes a good idea to also hook the keyboard interrupt (I and/or K) or you may may get a crash. One example is PopIt, which will crash if you've hooked '2' without 'I' and you type a PopIt hot key. AUTO Folder Placement --------------------- As mentioned earlier, Captain Hook will interact differently with your resident programs depending on where it is installed in your AUTO folder. Any program that intercepts vectors BEFORE Captain Hook runs will be unaffected by Captain Hook's operation. Let's say that you're using the SMPTE Track sequencer and you've found that you can use it just fine with one or two programs installed in the keyboard interrupt but you get MIDI overflow errors if you've installed too many. You've decided that you can get along without PopIt (which doesn't work in SMPTE Track anyway due to the way SMPTE Track handles accessories), Funk Alert, and the HotWire keyboard interrupts (for turning the clock on/off) but you couldn't live without CodeKeys. You should arrange the order of execution of your AUTO programs like this: CODEKEYS.PRG CAPTHOOK.PRG FUNKALRT.PRG HOTWIRE.PRG REGACC.PRG (for PopIt) Now if you've got an entry for SMPTETRK.PRG in your CAPTHOOK.DAT file like that shown in the example above, Captain Hook will cut out all of those programs except CodeKeys (which installed before Captain Hook took its "snapshot" of system vectors) when you run SMPTE Track and you'll have the use of CodeKeys with no MIDI overflow errors. Once you understand this concept, a little experimentation will allow you to tune up your system to make optimum use of your resources with the least amount of interference and program conflict. Using Captain Hook with MIDI Spy -------------------------------- I've built some special communications with Captain Hook directly into MIDI Spy, CodeHead's background MIDI recorder. If you run MIDI Spy as a program, you should _not_ list it in your CAPTHOOK.DAT file. Since MIDI Spy will normally be used as an accessory and you might be recording MIDI data at any time due to its background ability, it requires a special technique to allow you to use all of your resident programs but still have no MIDI overflow problems. To accomplish this, MIDI Spy talks directly to Captain Hook. If it finds the Captain, MIDI Spy goes directly into the Captain's back door and grabs its vectors as soon as any MIDI information comes in the MIDI ports. If more than a second goes by with no MIDI data coming in, MIDI Spy restores the current vectors. This process will generally have no ill effects on your system, but it _is_ possible for some irregularities to result. As long as you are not doing anything at your computer keyboard within one second of playing MIDI data, it shouldn't matter. But if you are playing your MIDI keyboard while someone else is operating the computer, strange things may happen. For instance, the right mouse button selection of files in Little Green Selector might not work. If you find that the interaction between Captain Hook and MIDI Spy is getting in the way with the normal operation of your computer, you'll have to remove Captain Hook and get along without it. If Captain Hook is not installed, MIDI Spy will not attempt any vector manipulation. Copyright stuff --------------- CAPTHOOK.PRG, and this document are Copyright 1991 John Eidsvoog. Captain Hook is free to all MIDI Spy owners. If you do not own MIDI Spy, then Captain Hook is a shareware program. The idea of shareware is that you may distribute Captain Hook freely to anyone (please, as much as possible). This method of distribution saves money for you the user and me the developer by eliminating marketing, manufacturing, and production costs. If you make use of Captain Hook and did not purchase MIDI Spy, you are expected to register yourself as a Captain Hook owner by sending a payment of $15 to: John Eidsvoog P.O. Box 74090 Los Angeles, CA 90004 This will register you as an owner of Captain Hook. Please specify Captain Hook in your correspondence, and if you would like to receive acknowledgment of your registration, include a self-addressed stamped envelope. Those who have registered Captain Hook for $15 will be eligible for a $15 discount on a later purchase of MIDI Spy. Please note that Captain Hook is not a CodeHead Software product, although it is provided free with a CodeHead product, MIDI Spy. All CodeHead Software products are commercial programs which must be purchased through normal commercial channels. CodeHead Software has never and will never release any shareware programs. Neither this document file (CAPTHOOK.TXT) nor the program file (CAPTHOOK.PRG) may be altered in any way. Copies of these files may not be sold, and this document may not be reprinted, without the express written permission of John Eidsvoog. I've tried to make Captain Hook as bug-free as possible. Nevertheless, I cannot be responsible for any damages which may occur as a result of the use (or misuse) of Captain Hook. Thank you for your support. John Eidsvoog ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Version numbers and suggested retail prices for CodeHead Software products as of Friday, December 6, 1991 are: Product Version Price ------- ------- ----- CodeKeys.............. 1.3 .......$39.95 G+Plus................ 1.5 ....... 34.95 MultiDesk Deluxe...... 3.3 ....... 49.95 LookIt & PopIt........ 1.2/1.1 ... 39.95 MaxiFile.............. 3.0 ....... 44.95 HotWire............... 3.0 ....... 44.95 HotWire Plus...................... 69.95 MIDI Spy.............. 1.0 ....... 79.95 MIDIMAX............... 1.3 ....... 49.95 CodeHead Utilities.... Rel 4 ..... 34.95 CodeHead GT Graphic Tools: Avant Vector (EPS)..................$545 Avant Plot.......................... 895 MegaPaint Professional........... .. 175 Genus Font Editor................... 175