³ The Silicon Frog, Inc. ³ ³ John Hancock 3.0 ³ ³ Installation and INSTALL Program ³ ³ Version 1.0 ³ ³ (c) 1992 The Silicon Frog, Inc. All Rights Reserved Table of contents Introduction...............................................1 Installing and viewing the JH3 shows.......................1 JH3 Files and Directories..................................2 Visual JH3 Summary.....................................3 Preliminary tasks..........................................3 Registered JH2 Users.......................................4 The INSTALL Program........................................4 Starting INSTALL.......................................5 The Tag Directory......................................5 Video Adapter Type.....................................5 Configuration File.....................................6 Erasing Distribution Files.............................6 The JH3 Environment Variable...........................6 I don't like to clutter my PATH........................8 Installing Documentation Files.............................8 Adding Titles to your Tagfiles.............................9 Mail Reader Installation..................................10 Sparkware's DeLuxeý...................................10 MegaReader............................................11 Speed Read v1.0 and later.............................11 Jabber 1.0 and later..................................12 EZ-Reader v1.2x and later.............................12 SLMR v2.xx and OLX v2.xx..............................13 Method #1.........................................13 Method #2.........................................13 KingQWK v1.00 and later...............................14 JH3 Installation 1 Introduction Installing John Hancock release 3.0 is a simple task which should only have to be performed once - although there are exceptions to this rule: 1. You experienced some severe hardware problem (e.g., a disk crash, with no backup). 2. Your hardware configuration (esp. video) has changed and you need a new JH30.CFG file. 2. You are an unregistered user and JH3 started nagging after you used the program 30 days and more than 250 times, and you would like to continue to use JH3 another 30 days and 250 times without any nagging. This alternative is much less honorable than registering John Hancock. 3. You are an unregistered user, you tried to defeat JH3's nagware logic, JH3 found out about it, and it started nagging you unmercifully. Installing and viewing the JH3 shows The JH3 show files are in the JH3-4OF4.ZIP distribution file. You should install the shows and view the JH3 Installation show *BEFORE* you install JH3 on your system: 1. Create a temporary JH3SHOW directory on your hard disk. 2. unZIP the JH3-3OF4.ZIP file to that directory. 3. Type SHOW2 at the DOS prompt. 4. Select the JH3 Installation show from the show selection menu. Once you have installed JH3 successfully, you may view the JH3 and BONUS shows to familiarize yourself with John Hancock as well as the FANTASTIC!!! bonuses you get when you register it. Once you have viewed the shows, feel free to erase all the files in the JH3SHOWS directory and remove the directory from the drive. The shows' special effects' timing is based on the speed of your computer. On very fast machines (e.g., 386/486) with fast video adapters, some of the screen transition effects may be difficult to notice. One way to address this problem is to slow down your processor's clock. Most recent machines feature a "Turbo" switch or a keyboard command (e.g., Ctl-Alt-+ or Ctl-Alt-Minus) which lets you toggle JH3 Installation 2 between low and high processor speeds. Switching to the lower speed may slow down the show program enough to let you enjoy these wonderful and often spectacular effects, if I say so myself. JH3 Files and Directories JH3 requires a number of files to operate. Configuration and program files are kept in the main JH3 directory. User- modifiable data files (tagfiles, tune files, and frame files) are kept in the tagfile directory. The main JH3 directory is pointed to by the JH3 DOS environment variable, which you will add to your AUTOEXEC.BAT file (do NOT do it now!). In turn, the JH30.CFG configuration stored in the main JH3 directory points to the tagfile directory. Note that your JH3 directory and your tagfile directory may be one and the same - many existing JH users keep their tagfiles in a separate directory; JH3 was designed to accommodate such an existing setup. The JH3 and tagfile directories may have any name you wish, but we recommend using the name "JH3" since it will make following the installation steps that much easier. However, you could install JH3 in a directory called LOTUS, and the data files in another called DBASE, just to fool innocent bystanders such as your boss or your 10-year-old son who know that LOTUS and DBASE are no fun at all (Heaven forbid your 10-year-old gets his/her hands on the JH3CFG program and starts playing with your JH3 color and cosmetic configuration). JH3 Installation 3 Visual JH3 Summary The following diagram shows the relationship between system components (the DOS PATH and JH3 environment variable), and the various JH3 files and directories: SET PATH=C:\JH3 >ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ SET JH3=C:\JH3 ³ ÄÄÄÂÄÄ ³ ³ Ú ÄÄÄÄÄÄÁÄÄÄÄÄ ÀÄ>C:\JH3³JH3 Program files ³JH3.KEY registered user key file ³Colorset files (???SET.???) ³JH30.CFG ÄÄÄ> C:\TAGFILES À ÄÄÄÄÄÂÄÄÄÄÄ ³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ ³ Ú ³ ³Tagfiles (.TAG) ÀÄ>C:\TAGFILES³Tune Files (.TUN) ³Frame Files (.FRM) À Preliminary tasks 1. Create a JH3 subdirectory on your hard disk, and unZIP the JH3-1OF4.ZIP file into the JH3 directory. For example, if your hard drive is C:, and you have JH3-1OF4.ZIP on a diskette in your A: drive, get into the root directory of C: and issue the following commands: C:\>MD JH3 C:\>CD JH3 C:\JH3>PKUNZIP A:JH3-1OF4 At this point, all of JH3's distribution files are in the JH3 directory. 2. If you already have tagfiles (.TAG) which you used with previous versions of JH, make sure they are all in the same directory (this does not have to be the JH3 directory you just created). We'll assume that your tagfiles are in the directory called C:\TAGFILES. If you are installing JH for the first time, skip this step; you'll keep your tagfiles in the JH3 directory (you may copy them elsewhere later if you so desire). 3. If you already have tagfiles in a different directory, unZIP the TAGDIR.ZIP file to that directory. TAGDIR, which is stored within JH3-1OF4.ZIP, contains the JH.TAG, JH3 Installation 4 JH3.TUN and JH3.FRM files necessary for proper JH3 operation. You may then delete the TAGDIR.ZIP file. C:\JH3>PKUNZIP TAGDIR C:\TAGFILES C:\JH3>ERASE TAGDIR.ZIP Registered JH2 Users If you are a registered JH2 user, you should run the JH3KEY program at this time. JH3KEY requires that you have your original JH2 Bonus Diskette; when you run the program it will create your own customized JH3.KEY file which will prevent JH3 from operating in unregistered mode (i.e., issuing registration reminder messages). For additional information on the JH3KEY program, see JH3KEY.TXT. Of course, if you are NOT a registered user, you don't have a JH2 Bonus Diskette from which to create a key file. For your very own JH3 Bonus Diskette, which includes your personalized .KEY file, see REGISTER.TXT. Once you have created your JH3.KEY file, you must define the JH3 environment variable - INSTALL will look for it. The combination JH3 environment variable/JH3.KEY file tells INSTALL that you are a registered user (INSTALL does not behave the same way with registered and unregistered users). To define the JH3 environment variable temporarily, type the following command at the DOS prompt: C:\JH3>SET JH3=C:\JH3 Note: The JH3 environment variable you created will be lost next time you boot your computer. To make the variable permanent, you must add the same SET command to your AUTOEXEC.BAT file. For additional information, or if you have problems when issuing the SET command above, see "The JH3 Environment Variable" later in this document. At this point, you are ready to run the INSTALL program. Make sure you are in the JH3 directory when you start INSTALL. The INSTALL Program If you are a registered user, INSTALL will run very quickly and will re-install only what's required. Make sure your JH3.KEY file is in the JH3 directory. JH3 Installation 5 If you are not a registered user, you must remove all of JH3 from your system (except for the .TAG, .TUN, and .FRM files in your TAGFILES directory) in order for the INSTALL program to operate. This includes: 1. The JH3 environment variable 2. The JH30.CFG file 3. The JH3D&U.DAT file In all cases, the distribution configuration files (CGA.ZIP, EGA.ZIP, MDA.ZIP, and VGA.ZIP) must be in the JH3 directory when INSTALL is run. If necessary, fresh copies of these files may be unZIPped from the JH3-1OF4.ZIP distribution file. Starting INSTALL To start INSTALL, type the program name at the DOS prompt and press : C:\JH3>INSTALL If you are an unregistered user and INSTALL detects JH3 configuration files (.CFG, .DAT) or a JH3 environment variable, the program will terminate with an error message - erase these files and remove the JH3 environment variable before running INSTALL again. This is a purposeful inconvenience, since unregistered users are likely to run INSTALL only to defeat the registration reminder messages. The Tag Directory INSTALL will then prompt you for the tagfile directory. Type the complete drive and path name and press , or press to cancel INSTALL (like, wow, man, I forgot to unZIP TAGDIR like the instructions said). Video Adapter Type Next, INSTALL will determine your video adapter type and request your confirmation. If you have an oddball video setup, you should set it up to emulate an accepted IBM adapter type: MDA, CGA, EGA, or VGA/MCGA. Press to confirm the INSTALL selection, or to terminate install and return to DOS in the event your adapter was not properly recognized. INSTALL will correctly identify all standard IBM and 100% compatible video JH3 Installation 6 adapters; if it cannot recognize your adapter type, it will produce an appropriate message and terminate. Note that JH3 uses standard methods to identify video hardware - if it cannot recognize your setup, chances are most other programs cannot either, unless they use dedicated video drivers. A number of special-purpose video adapters (e.g., displays used for DTP or CAD purposes) can be set to emulate standard IBM adapters; the hardware manufacturer usually provides a utility to switch to a different video mode. Use this utility program to switch your adapter to a JH3-supported mode. Configuration File Once your video adapter has been properly identified, INSTALL will unZIP the video-specific configuration file (CGA.ZIP, EGA.ZIP, MDA.ZIP, or VGA.ZIP) into the JH3 directory. This file contains a number of pre-defined color setup (ColorSet) or "Gallery" files used by the JH3 configuration program, as well as a default configuration file. INSTALL will then customize the default configuration file to reflect your environment. For unregistered users, INSTALL also creates a JH3D&U.DAT file to keep track of your use of the program. Erasing Distribution Files Before it terminates, INSTALL displays a prompt which gives you the option to erase unneeded distribution files. To delete the files, press ; to keep the distribution files, press . If programs that delete *anything* without your express knowledge make you nervous, reply and manually delete the files later. To manually delete the distribution files, issue the DOS ERASE command with the following file specifications: *.ZIP, *.DOC, *.CGA, *.EGA, *.MDA, *.VGA, *.DIZ The JH3 Environment Variable As mentioned earlier, JH3 requires a DOS environment variable which points to the main JH3 directory where your JH30.CFG and JH3.KEY (registered users only) files are located. If you are a registered JH2 user, you created this variable before running INSTALL. JH3 Installation 7 The easiest way to define the JH3 variable is to add a SET command to your AUTOEXEC.BAT file as follows: SET JH3=C:\JH3 Of course, use your own drive:\path if you did not install JH3 in C:\JH3. Note: In order to use JH3 immediately after installation without rebooting the computer, issue the same SET JH3= command directly from the DOS prompt after the installation is complete.. In some rare cases, there may not be sufficient environment space to add the JH3 variable. If DOS issues an error message to that effect, you should increase the environment to accommodate the new variable. With DOS 3.3 and later releases, add the following command to your CONFIG.SYS file: SHELL=C:\COMMAND.COM /P /E:xxxx Where xxx is the size of the DOS environment. If you do not have a SHELL command in CONFIG.SYS, then your environment is 160 bytes, and the xxxx value should be equal to 165 plus the length of the JH3 directory path (a value of 220 should accommodate just about any JH3 directory specification). If you already have a SHELL statement in CONFIG.SYS, increase it by the length of the JH3 directory path. You must reboot your computer for changes to AUTOEXEC and CONFIG.SYS to go into effect. The DOS PATH For your reader to find the JH3 program, JH3.EXE must be in the default directory (e.g., your reader's directory), or it must be in a directory defined in your DOS PATH - by far the preferred method. To add the JH3 directory to your DOS PATH, add the following statement to your AUTOEXEC.BAT file: SET PATH=C:\JH3 Where C:\JH3 is the same directory you used in the SET JH3= command earlier. If you already have a SET PATH command, add a semicolon at the end of it, followed by the JH3 directory path, as follows: SET PATH=C:\PATH1;C:\PATH2;........;C:\PATHX;C:\JH3 ------ JH3 Installation 8 The DOS PATH length is artificially limited to the maximum length of a DOS command. If you do not have enough room to add the JH3 directory to your PATH, and if you run DOS 3.0 or above, you may use the SETPATH.COM Silicon Frog utility, which is included with JH3 and which will completely eliminate your PATH size limitation problems. See SETPATH.TXT for additional information. Note that the DOS PATH is a special environment variable; increasing its size may also cause you to run out of environment space. If this is the case, increase your environment size as described in the "JH3 Environment Variable" section. I don't like to clutter my PATH You are not alone. I have a couple of beta testers who don't like PATHs and environment variables either. There is one whose unending quest is to have 655360 bytes of free DOS memory - a tough challenge even with DOS 5.0 and QEMM. If you don't *want* to add to your DOS PATH, then use a fully qualified command in your hot key (or whatever scheme your reader uses) JH3 definition: C:\JH3\JH3.EXE Of course, you must use the same method for all other programs in the JH3 directory. Installing Documentation Files JH3's documentation files are distributed in the JH3-2OF4.ZIP file. These files are formatted text and they can be copied directly to your printer. I strongly recommend that you print the documentation; although many of you like to 'wing it', there are important JH3 features that you just won't be able to guess. In order not to clutter your JH3 directory, I recommend unZIPping the documentation files to their own directory -- it will be that much easier to delete them once you are done printing them. In addition, they will also be easier to find if you decide to read them with a file viewer program. Once you have unZIPped the documentation files, use the DOS COPY command to print them: C:\JH3DOCS>COPY JH3.TXT PRN JH3 Installation 9 NOTE: Your printer must understand the FormFeed command used in these files to advance the paper to the top of the next page -- all recent printers do, including the HP LaserJet, DeskJet, and compatibles). Adding Titles to your Tagfiles JH3 and JH3MAINT require that all of your tagfiles be "titled". By definition, the first line in a tagfile is its title. The file's title, rather than its name, is displayed in these programs' file selection screens. In addition to the title, the first line also defines the file's "Hot Key" - the single character which can be used to load that file quickly. The Hot Key, by definition, is preceded by a percent sign (%) in the title line. For example: My Favorite %JH Taglines defines "My Favorite Taglines" as the file's title, and the letter J as its hot key. Use a text editor to add title lines to your tagfiles. Unless you have a very large number of tagfiles, try to use unique hot keys - JH3 and JH3MAINT always start at the top and stop once they match the hot key you pressed, so duplicates are definitely not encouraged. JH3 Installation 10 Mail Reader Installation In order to use JH3, you will have to customize your mail reader program. Unfortunately, there is no "standard" installation procedure; each program uses a different method to define JH3 and "Hot Key" to it when you want to select a tagline. Also, some readers have rather sketchy instructions regarding JH3 installation. Following are basic instructions on how to install and/or use JH3 with all the mail readers that supported it as of March 1992. Note: reader installation procedures were current as of March 1992. Verify these procedures in your reader's documentation. New readers not documented here may also support JH3 - see the reader documentation or contact the reader's author for additional information on JH3 support. Sparkware's DeLuxeý To define JH3 to DeLuxeý, start the reader and select the (C)onfigure DeLuxeý main menu option, then select the Function (K)ey option. Select an available function key, and type "JH3" in the key field. Escape, save the configuration, and you are done. If you do NOT have any free function keys and you do not wish to give one up, use Plan B: Start the reader, select the (C)onfigure DeLuxeý option, then select the (T)aglines option. Pick a free tagline (the top one is best) and type DOS:JH3 in the tagline field. Escape, save the configuration, and you are done. To call JH3 from DeLuxeý, press the selected Hot Key (preferably after you have entered your message), and control will be passed to JH3. DeLuxeý will add the tagline you selected to the bottom of your message. If you do NOT have a hot key, select the DOS:JH3 tagline when DeLuxeý prompts you for one, and control will be passed to JH3. The reader will pick up the JH3-generated tagline automatically. For best performance, you should configure JH3 to operate in DeLuxeý mode (Preflight Checklist, DeLuxeý API switch). For additional information, see JH3CFG.TXT. With all other mail readers, JH3 must operate in JH2 Compatibility Mode. JH3 Installation 11 Note that you may use the same procedure to assign hot keys to the JH3CFG and JH3MAINT programs, so that they too can be conveniently called from DeLuxeý. MegaReader Release 2.10 of MegaReader is required to run JH3. To define JH3 hotkeys, use the following procedure: 1. From anywhere within the program, press to define hotkeys. A box will appear with a listing of existing hotkeys. 2. Press . The following prompt will appear: Trigger Keystroke: (None) (Press new trigger Key or (enter) to keep) 3. Press the key combination you want to use. For example, . The following prompt will appear at the bottom of the screen: DOS Command: Type the desired line, in this case "C:\JH3\JH3.EXE". You may prefix the command with an asterisk to cause MegaReader to swap itself to EMS memory (if your system has it). 4. Press to save the new hotkey command. 5. Repeat the above procedure for the JH3CFG and JH3MAINT programs if desired. You may now invoke JH3 at any time by pressing the hotkey you just defined. MegaReader will automatically use the JH3-generated tagline until you select a new one via JH3 or use the internal taglines by pressing followed by . Pressing / clears the JH3-generated tagline and tells MegaReader to use its internal taglines instead. Speed Read v1.0 and later 1. Start SR.EXE and press . Choose "General Setup". Under "External Programs", the following fields apply to JH3: EXTERNAL PROGRAMS JH3 Installation 12 Tagline Mgr: C:\JH3\JH3.EXE Tag. Ret.File: JH?.REP 2. Make sure you use the fully qualified path and filename of JH3.EXE in the "Tagline Mgr." field. 3. Type "JH?.REP" in the "Tag. Ret. File" field, or leave the field blank (either method works fine). Use to save changes and exit. 4. From the message window, press to invoke JH3. This command key is hard-coded into the program and cannot be changed. The cursor need not be on the tagline field to invoke JH3; the command can be issued from anywhere in the message window. Jabber 1.0 and later 1. Edit JABBER.CFG. Under the heading "External programs to process reply after editing", there is a {POSTPROCESS} entry. Put the fully qualified name of JH3.EXE between the = sign and } (right brace). Ensure that you have the TAGLINES= entry set to YES - the entries should look like: {POSTPROCESS=C:\JH3\JH3.EXE} {TAGLINES=YES} 2. Save JABBER.CFG and exit. 3. Upon exiting from the editor (internal or external), Jabber will automatically invoke JH3. EZ-Reader v1.2x and later 1. Run CONFIG.EXE, either from the DOS prompt or by pressing F2 from within EZ-Reader. 2. Select "Hot Keys" from the menu. 3. Select the hotkey combination you will use to invoke JH3. For this example, we'll use . Press to get to the window containing the "Alt" keystrokes. 4. In the F10 field, type the fully qualified path of JH3.EXE. Preface the command with an exclamation mark JH3 Installation 13 (!) if you want EZ-Reader to swap to EMS or disk upon shelling. Your field should look like: F10 !C:\JH3\JH3.EXE 5. Press , cursor down to "Save", press , and reply "Yes" to the "Save changes" prompt. 6. From within the message window, press to invoke JH3. When you return to EZ-Reader from JH3, the tagline field in the message window will NOT show the JH3-generated tagline, but the reader will use it. SLMR v2.xx and OLX v2.xx SLMR (Silly Little Mail Reader, a.k.a. "Slimer") and its commercial version OLX (On-Line Express) feature the same two methods for invoking JH3 (note that the unregistered OLX Test Drive version, OLXTD, operates the same way as the registered OLX program). All these programs will be generically referred to as 'SLMR'. Method #1 1. SLMR automatically detects JH3-generated taglines and does not require any special setup. 2. SLMR invokes the program "JH.EXE", and expects it to be in the SLMR directory - this name is hard-coded into the program. You must therefore copy JH3.EXE to the SLMR directory and rename it JH.EXE (this prevents you from using two different versions of JH). 3. SLMR expects a JH.TAG file in its directory - this is also hard-coded into the program. This does NOT have to be the *real* JH.TAG file - a JH.TAG file with a single tagline is all that's required. As long as you have a JH3 environment variable and a JH30.CFG file, JH3 will find its *real* tagfiles, wherever they are. 4. To invoke JH3 (a.k.a. JH.EXE) from SLMR, press . The JH-generated tagline will appear in the tagline field when you return to SLMR. Method #2 1. Edit the TAGLINES.MR (or TAGLINES.OLX) files and type "JH" (without quotes) as the ONLY tagline entry if you JH3 Installation 14 want to use JH for all your taglines. If "JH" is not the only internal tagline, then you must select the "JH" tagline for SLMR to invoke JH. 2. Similarly, typing "JH" manually in the tagline window will invoke JH. 3. SLMR/OLX still expects the JH program to be named JH.EXE, and there must be a JH.TAG file in the SLMR/OLX directory (see item 3 in method #1 above). KingQWK v1.00 and later 1. Bring up the KingCFG menu by pressing while in the reader, or run KINGCFG.EXE from the DOS prompt. 2. Select the "Default Flags" option. 3. Enter a "J" in the Taglines field to activate KingQWK's automatic JH interface. Return to the KingCFG menu. 4. Select the "Utilities" option. In the "JH Command Line:" field, type the fully qualified name of the JH3 program (e.g., C:\JH3\JH3.EXE). Save the configuration. 4. KingQWK will invoke JH automatically with every reply.