Install-Pro User's Guide and Reference Manual Copyright 1991-1993 DB/Soft Publishing. All rights reserved. Printed in the U.S.A. Version 3.00, first printing Copyright This software is protected under United States Copyright Law and International Treaty provisions. DB/Soft Publishing reserves all rights to Install-Pro except for the following: A limited license is hereby granted allowing you use and evaluate Install-Pro for up to 30 days. You may also distribute unregis- tered copies of Install-Pro in its entirety to any parties interested provided no modification of the files in the Install- Pro archive occurs. The maximum transaction related to selling media containing unregistered copies of Install-Pro (eg Shareware vendors) may not exceed $10.00. Conversion to a more convenient archive format is allowed. All other uses of Install-Pro violate this license and are hereby expressly disallowed. Copyright 1991-1993, by DB/Soft Publishing, All Rights Reserved. 3200 Truxel Rd #199, Sacramento, CA 95833 USA Telephone: (916) 927-6951 BBS: (916) 927-2349 Limited Warranty DB/Soft Publishing grants no warranties, express or implied, by statute or otherwise, regarding this software and its related materials, their fitness for any purpose, their quality, or their merchantability. In no way shall DB/Soft Publishing be liable for any special, consequential, other damages for breach of warranty. This Statement shall be construed, interpreted and governed by the laws of the State of California. This warranty will be replaced by a limited 90-day warranty that covers the diskette, software and documentation upon registration of Install-Pro. Further, the limited license will be replaced with a license that allows royalty-free distribution of Install- Pro with your applications. Registering Install-Pro Install-Pro is an example of software marketed under the Share- ware concept. The premise is simple: you may evaluate Install- Pro for a reasonable period of time (30 days maximum) during which you decide if it is a program worth owning and using for installing your applications. If so, you must register Install- Pro, using order.doc for ordering information. If, after a reasonable evaluation period, you decide not to register Install- Pro, you then must discontinue its use. This provides me with a way to market software with very low advertising overhead, which results in a price savings passed directly on to you. And, it provides you with a chance to 'play' with my product and decide if it meets your needs. As an incentive to speed the registration process, a minor modification to Install-Pro processing occurs in the Shareware version. Prior to displaying your opening screen(s), an order information notice is displayed. Other than this single modifi- cation, all features that are included in the registered version of Install-Pro are available here. Getting Help_____________________________________________________ There are several ways of contacting the author, Jeff Dunlop, for technical assistance if you get stuck. From cheapest and slowest to most expensive and fastest: - Fidonet's SHAREWRE echo - ILink's Shareware conference - Fidonet netmail at 1:203/16 - Compuserve mail at 72147,3055 - Internet at 72147.3055@compuserve.com - The DB/Soft Online at (916) 927-2349 The best method of contacting the author depends on the type of assistance you need. If it's a rather complicated problem, you will probably be far better served if you prepare a message in advance and upload it with the script in question to the DB/Soft Online. We can then test it and offer suggestions. If it's just a question or suggestion about Install-Pro capabilities, the ILink or Fidonet conferences will work best. Fidonet netmail privileges can be difficult to get, but offer excellent timeli- ness at very low connect time. Check your local Fidonet BBS if interested. Table of Contents Chapter 1 Introduction .................................. 7 Features ........................................... 7 Requirements ....................................... 9 Getting Started .................................... 10 Install-Pro Scripts ................................ 10 Documentation Conventions .......................... 11 Chapter 2 Creating the screens .......................... 13 BANNER ............................................. 13 HELLO .............................................. 14 HELLOBREAK ......................................... 14 GOODBYE ............................................ 14 GOODBYEBREAK ....................................... 15 COLORS ............................................. 15 Chapter 3 Building the entry forms ...................... 17 USER ............................................... 17 DESCRIBE ........................................... 20 Chapter 4 Transferring files ............................ 21 SUBDIR ............................................. 21 FILE ............................................... 22 Splitting Files .................................... 24 UNZIP .............................................. 25 ATTRIBSAVE ......................................... 27 Chapter 5 Changing Disks and Terminating ................ 28 FIRSTDISK .......................................... 28 DISK ............................................... 28 END ................................................ 28 CHAIN .............................................. 29 Chapter 6 Verifying the target environment .............. 30 SPACE .............................................. 30 CPU ................................................ 30 FPU ................................................ 30 RAM ................................................ 30 EMS ................................................ 31 VCPI ............................................... 31 DPMI ............................................... 31 XMS ................................................ 31 VER ................................................ 32 CONFIGFILES ........................................ 32 5 PATH ............................................... 33 SET ................................................ 33 Chapter 7 Running external programs and viewing files ... 34 RUN ................................................ 34 PRERUN ............................................. 36 RUNERRNOTIFY ....................................... 37 VIEW ............................................... 37 Chapter 8 Customizing Install-Pro ....................... 38 ONERROR ............................................ 38 Linking external text .............................. 38 Chapter 9 Miscellaneous ................................. 40 System Variables ................................... 40 Command Line Switches .............................. 41 Error Messages ..................................... 40 Critical Errors .................................... 46 6 Chapter 1 Introduction_____________________________________________________ Install-Pro is the flexible and affordable solution to the common problem of transferring an application or information base from distribution media to its destination directories. Typically, the options have been to write a batch file, to write a custom program or to shell out hundreds of dollars for an anemic instal- lation utility. Until Install-Pro. Install-Pro is a script driven professional installation program that will automate the installation process while providing your customers with a crisp, easy-to-use interface. Unlike other script-driven installation utilities, Install-Pro is heavy on features, intelligent in its operation, and light on resource requirements. Any application can be ready to install to multi- ple directories from multiple disks in a matter of minutes. A brief list of features includes: - Professional look and feel for a better first impres- sion. - You customize multiple welcome screens and good-bye screens to your own needs. - Up to 999 installation disks and unlimited installation files. - Comprehensive environment detection, including minimum CPU, floating point processor, installed RAM, MS-Dos version, EMS, XMS, VCPI and DPMI. - Powerful system variables for CPU, math coprocessor and video adapter that allow your installation to behave differently depending on the target hardware. - Display your readme files at the end of the installa- tion in a nifty file viewer. - Intelligent FILES=, PATH and SET VAR= update for Config.sys and Autoexec.bat. - All Install-Pro text strings may be optionally rede- fined via an external file. - Files may be split into up to 9 pieces for huge files spanning multiple disks. 7 Chapter 1, Introduction _________________________________________________________________ - Files in the .zip format may be extracted. All direc- tories stored in a .zip file are automatically created. There is an .arj version of Install-Pro available on the DB/Soft Online for registered users. - You define the directory prompts and default destina- tion directories that the user sees. - You optionally define the installation disk names (such as "Utilities Disk" or "Install Disk") - You optionally specify the disk space requirements associated with all portions of the installation, including optional portions. (The user is given the option to try to continue with installation if short on disk space.) - Up to 8 user-defined destination directories. - Unlimited programmer-defined directories child to user- defined directories. - Each destination directory may either be optionally locked or the user may be allowed to change it. - "Run" commands allow your installation to include custom auxiliary programs or batch files to complete special tasks. The installation diskette directory(s), any of the user-defined directories, and any other arguments you choose can be specified anywhere on the command line. - Portions of an installation may be specified as option- al, prompting the user whether the optional portion should be installed. - Multi-Module installations handled seamlessly. - Files may be automatically overwritten, prompted before overwriting a newer file, prompted before overwriting any file or protected completely from overwrite. - Supports VGA/EGA 50/43 line text modes if detected. 8 Chapter 1, Introduction _________________________________________________________________ - Robust error handling, including a custom critical error handler that won't scare the dickens out of your users, and including descriptive fatal error messages (no "error 14 at xxxx:yyyy" found in this program!) Requirements_____________________________________________________ Install-Pro runs under PC-DOS and MS-DOS versions 3.0 and above. A minimum of 220K of RAM is required. More memory is desirable if external programs are run from Install-Pro, or if large scripts are processed. There is virtually no limit to the size of script files. Script preparation will require a text editor that does not insert formatting codes into the text. 9 Chapter 1, Introduction _________________________________________________________________ Getting Started__________________________________________________ Before you can really build an installation script, you need an application that needs to be installed. Gather enough disks to hold your installation, format them if needed, and copy the application files over to the disks. Record what files are on which disks for later reference, and while you're at it, record the order that the disks are to be installed. Included on your Install-Pro disk are two files to aid you in recording this information. They are named MASTER.DOC and DISKWKS.DOC. For each installation you should print out one copy of MASTER.DOC, and a copy of DISKWKS.DOC for every disk in your installation. If you'll be installing your application from compressed files, then you want to compress your files before transferring them to diskettes. If you have huge files that will need to be split onto multiple disks, you may want to take a peek at the separate documentation for split.exe. All that you really need to know is that split will split filename.ext into filename.ex1, filename.ex2, etc., and that filename.ex1 must not be copied to a higher-numbered disk than filename.ex2. Once you have a good idea of what files need to be transferred, then you're ready to start planning your installation. Install-Pro Scripts______________________________________________ Install-Pro is script-driven. That is to say, it looks onto your distribution disks for instructions about how you want your installation to behave. The required instructions are found in script files, one to a disk. The script file on Disk One is named INSTALL.001; the script file on the next disk is named INSTALL.002, and so on. Install-Pro is also largely global in nature. That is, it reads the entire script on the current distribution diskette before doing any processing. Because of this, there are very few restrictions on the location of most commands. The major excep- tion is that USER commands must appear before any command that references a label defined in that USER command. However, Install-Pro's execution is very strictly defined and can be described as follows: Disk 1 ------ 10 Equipment checks are performed. The opening screen(s) are displayed. The optional segments form is displayed. The main user entry form is displayed. PRERUN commands. FILE commands. UNZIP commands. VIEW commands. RUN commands. Disk 2 through Disk n - 1 (n = number of disks in installation) --------------------------------------------------------------- PRERUN commands. FILE commands. UNZIP commands. VIEW commands. RUN commands. Last Disk --------- PRERUN commands. FILE commands. UNZIP commands. VIEW commands. RUN commands. The closing screen(s) are displayed. Install-Pro either chains to a new copy of Install-Pro or ends. Because of this strict order of operations, USER, HELLO, HELLOBREAK and Equipment commands are legal but meaningless on any disk other than the first disk. GOODBYEBREAK commands are legal on any disk, but not processed until the end of the instal- lation. Documentation conventions________________________________________ In general, command parameters appear in three forms. If a paremeter appears in square brackets ( [] ), that parameter is optional. If it appears in angle brackets ( <> ), it is re- quired. If it appears in quotes ( "" ), it is both required and must be surrounded by quotation marks. The text that appears in brackets may either be a sub-command or a variable parameter. The proper use of the parameter is determined by looking up the documentation for that particular parameter below the main heading for the command. Throughout the text, commands appear as all capital letters. This is to remove any ambiguity as to whether a particular word is the name of a command or is being used in some other context. 11 However, Install-Pro is not case sensitive. Commands, labels and directory paths can appear in any combination of upper and lower case. 12 Chapter 2 Creating the Opening and Closing screens_________________________ All commands that define the opening screen(s), BANNER, HELLO and HELLOBREAK, must appear in a file named INSTALL.001 on the first diskette of your installation set. These commands usually appear at the top of INSTALL.001. The format of the opening screen is similar to the following: ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿±±±±±±±±± ±±±±±±±±±³Welcome to the Install-Pro Installation Program ³±±±±±±±±± ±±±±±±±±±ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿± ±³ This program is going to transfer the Install-Pro files from ³± ±³ the installation diskette to the directory(s) that you enter ³± ±³ on the screen to follow. ³± ±³ ³± ±³ Press a key to continue. ³± ±ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± The top message that you see is created with the BANNER command. The bottom message is created with a series of HELLO commands. If multiple HELLO screens are defined, then each keypress will display the following screen until all have been shown. BANNER___________________________________________________________ Syntax: BANNER "Any text enclosed in quotes" The BANNER command identifies the line of text to be shown to the user as the program name on the opening screen. Up to 71 charac- ters are allowed, and a box surrounding the text auto-sizes for a neat appearance. If the particular text used creates unbalanced sides, insert an extra space on the errant side to even things out. If quotes are omitted, only the first word after BANNER will be detected. If no text is detected after BANNER, Install-Pro will abort with an error message. The BANNER command must be defined in install.001 to have any effect. 13 Chapter 2, Creating the screens _________________________________________________________________ HELLO____________________________________________________________ Syntax: HELLO "Any text enclosed in quotes" The HELLO command identifies a line of text to be shown to the user on the welcome screen. Each line may have a maximum length of 71 characters. Characters in excess of 71 are ignored (trun- cated.) All of the HELLO text lines are displayed in the order detected in a single window, which automatically sizes itself to the length and height of the combined HELLO display. If you want empty lines included, indicate this with a set of empty quotes (""). Up to 13 HELLO lines will fit on a single screen. If more than 13 HELLO lines are defined without any intervening HELLOBREAK commands (described below), the subsequent lines will be dis- played on the next screen. Any number of HELLO screens (each autosizing, with a capacity of up to 13 lines) can be defined within the confines of available memory. HELLOBREAK_______________________________________________________ Syntax: HELLOBREAK This command signifies that the following HELLO command is to be displayed on a new screen. Use this if you have special format- ting needs that require fewer than 13 lines to a screen. The format of the closing screen is similar to the following: ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿± ±³ The installation has completed normally. ³± ±³ ³± ±³ Press a key to exit... ³± ±ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± This message that you see here is created with a series of GOODBYE commands. If multiple-screen messages are necessary, they can be separated if needed with GOODBYEBREAK commands. GOODBYE__________________________________________________________ Syntax: GOODBYE "So-long text goes here" 14 Chapter 2, Creating the screens _________________________________________________________________ This command is used to build an end-of-install message to display to your users after successful completion of installa- tion. It can be up to 71 characters long, and like the HELLO lines, the GOODBYE text is displayed in an auto-sizing window. If you want to specify an empty line, use GOODBYE "". Somewhere near the bottom of the GOODBYE text, you should include something to the effect that a keypress will exit the program. Any number of GOODBYE lines can be defined, anywhere in the script file(s). After 14 GOODBYE lines have been encountered without an intervening GOODBYEBREAK command (described below), a page break is automatically inserted by Install-Pro. When an install.??? file is processed that is terminated with an END command, after all transfers have taken place, the GOODBYE messages are displayed, after which the program terminates. There are two events that can occur that will cause the closing screen to not be displayed. One is if you choose to terminate with a CHAIN command, which would load a new installation. In this instance, the closing screen defined with the last installa- tion processed would be the one displayed. The other is if an unrecoverable error occurs. In this instance the error is described to the extent possible, and Install-Pro terminates (see Chapters 8 and 9 for details). GOODBYEBREAK_____________________________________________________ Syntax: GOODBYEBREAK This command tells Install-Pro that the next GOODBYE line defined in the script is to appear at the top of a new page. New with version 3.00 COLORS___________________________________________________________ Syntax: COLORS The COLORS command requires exactly twelve hexadecimal digits, from 0 to F, where 0 through F represent the following colors: BLACK 0 BLUE 1 GREEN 2 CYAN 3 15 RED 4 MAGENTA 5 BROWN 6 LIGHTGREY 7 DARKGREY 8 LIGHTBLUE 9 LIGHTGREEN A LIGHTCYAN B LIGHTRED C LIGHTMAGENTA D YELLOW E WHITE F The default COLORS setting for Install-Pro is COLORS 7 1 7 4 0 7 9 7 8 0 7 1 and is interpreted as: Regular Windows, Light Grey on Blue Error Windows, Light Grey on Red Entry Fields, Black on Light Grey Bottom Line, Light Blue on Light Grey Shadows, Dark Grey on Black Background, Light Grey on Blue Each background color (that is, each second number in the COLORS command) must be in the range of 0 through 7. This is a limita- tion in IBM PC video architecture. 16 Chapter 3 Building the Entry Forms_________________________________________ ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿± ±³ Optional Installation Selection ³± ±ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿± ±³Please press your spacebar to check any of these optional ³± ±³installation segments that you wish to include. ³± ±³ ³± ±³ ( ) Sample Files ³± ±³ ³± ±ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±³ Destination Directory Entry ³±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ±ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿± ±³ ³± ±³Program Files C:\INSTPRO\ ³± ±³Document Files C:\INSTPRO\ ³± ±³Sample Files C:\INSTPRO\SAMPLE\ ³± ±³ ³± ±ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ± ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± The USER command, which is used to build the Destination Directo- ry Entry form (and its accompanying Optional Selection form) must appear in Install.001 on the first diskette of your instal- lation set. USER_____________________________________________________________ Syntax: [OPTION or ATTACH] USER