ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / UTILITY / FILE / IPRO121.ZIP / INSTPRO.MAN < prev next >

Wrap

Text File | 1991-08-01 | 56.4 KB | 1,490 lines

The Install-Pro Reference Manual Version 1.21 August 1, 1991 Copyright 1991 DB/Soft Publishing Co. All Rights Reserved DB/Soft Publishing Co. 3200 Truxel Rd. #199 Sacramento, CA 95833 Sole Proprietor: Jeff Dunlop Voice: (916) 927-6951 Data: (916) 927-2349 Fidonet Address: 1:203/38.6 Table of Contents Introduction ..................................... 1 Program Requirements (Programmer) ................ 2 Program Requirements (User) ...................... 3 Distribution Files ............................... 3 Registration ..................................... 3 Shareware License ................................ 3 Shareware Warranty ............................... 4 Registered License ............................... 4 Registered Warranty .............................. 4 Registered Support ............................... 4 Frankness Clause ................................. 5 Disclaimer ....................................... 5 About Config.sys and Autoexec.bat ................ 5 Contacting the Author ............................ 5 The Future ....................................... 6 About the User's Guide ........................... 6 Script Syntax .................................... 6 Script Tokens .................................... 8 BANNER ....................................... 8 HELLO ........................................ 9 USER ......................................... 10 SUBDIR ....................................... 10 FILE ......................................... 11 Splitting Files ...................... 13 RUN .......................................... 14 GOODBYE ...................................... 16 DISK ......................................... 16 END .......................................... 18 AUTHORIZATION ................................ 18 Script Debugging ................................. 18 Error Messages ................................... 18 Critical Errors .................................. 20 Registration Keys ................................ 21 Virus Protection ................................. 21 Introduction ------------ Install-Pro is a script driven professional installation program that you as a programmer can use to install your applications on your customers' computers. My personal goal with this program was to never write an installation again (heaven forbid a batch file!) which meant that the entire installation procedure HAD to be configurable quickly and easily. Any application can be ready to install to multiple directories from multiple disks in a matter of minutes. A brief list of features includes: - Professional look and feel for a better first impression. - You customize the welcome screen and good-bye screen to your own needs. (Welcome screen - registered version only) - Up to 999 installation disks. - Unlimited installation files. - Files may be split into up to 9 pieces for huge files spanning multiple disks. - You define the directory prompts that the user sees. - You define the default destination directories that the user sees. - Up to 13 user-defined destination directories. - Unlimited programmer-defined directories child to user-defined directories. - "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. - Supports VGA/EGA 50/43 line text modes if detected. - 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!) Install-Pro Reference Manual - 1 - Program Requirements (Programmer) --------------------------------- 1. Text editor for creating and modifying the script file(s). This text editor must not insert tab characters into your screen definition lines. 2. MSDos 3.0 or higher. 3. IBM PC bios compatible MS-Dos computer with at least 110k free ram. 4. Standard CGA or Hercules compatible video subsystem. Install-Pro Reference Manual - 2 - Program Requirements (User) --------------------------- 1. MS-DOS 3.0 or higher. 2. IBM PC bios-compatible MS-DOS computer with 110k free ram (more ram needed for RUN commands) 3. Standard CGA or Hercules compatible video subsystem. Distribution Files ------------------ Install-Pro comes distributes with the following files: instpro.exe - the executable instpro.man - this reference manual instpro.usr - the user's guide install.001 - sample script file #1 order.doc - order form read.me - quick hello example.001 - script examples to get you started If any of these files were missing, feel free to download the latest version from the DB/Soft Online. Also, when you distribute Install-Pro with your applications, feel encouraged to rename it 'install.exe.' I refrained from naming the executable that way to avoid accidentally having it write over one of the other install.exe's you may have lying around. Also, feel encouraged to modify the user's guide or include part of it in your documentation - that's what it's for. Just please remember not to distribute modified copies (or registered copies with the key) of Install-Pro. Registration ------------ Upon receipt of the registration price of $27.50 (U.S. funds only) you will be sent a disk with the most current version that will enable you to display your application's name instead of my shareware notice. Use the file "order.doc" to order. Sorry, MC/Visa not accepted. Shareware License ----------------- You are free to distribute shareware copies of Install-Pro provided that none of the included files are modified or removed, and provided that no additional files are included in the archive. Modifying the archive format (from .zip to some other format perhaps more convenient) is permitted. Install-Pro Reference Manual - 3 - Shareware Warranty ------------------ The shareware version of Install-Pro is guaranteed to take up disk space. The author of this product is more than happy to hear about any bugs or unexpected behavior through non-voice channels (netmail, US Postal Service, or logging on to the DB/Soft BBS), but will not guarantee that immediate bug fixes will be forthcoming. Registered License ------------------ You are free to make unlimited backup copies of this program for archival purposes. You may not distribute copies of this program except under the following provisions: You may at your choosing give away or sell your program with its accompanying key to ONE party, provided you destroy all copies of the software in your possession after the time of the transaction. The copies of the program that are used to install your applications MUST NOT be distributed with the key that enables script modifications. Each key is unique to the purchaser, and I will hold each purchaser responsible to the confidentiality of his/her key. Registered Warranty ------------------- The registered version is warranted to meet in all key aspects its defined behavior as listed in the documentation. Key aspects are those features without which the program will fail in some gross manner to transfer an application. Minor specifications (such as prompt lengths, etc. are subject to change without notice. The final arbiter as to the interpretation of the documentation shall be the author of the program. The sole remedy available to the purchaser of Install-Pro shall be bug fixes or a refund, as determined by the author. Work-arounds for the purposes of warranty consideration will be considered acceptable if they make possible the same task that any bug renders impossible. If verified bugs are not corrected within 30 days of notification, and if the purchaser is working in good faith to keep in contact with the author, the purchaser at his option is entitled to a refund. Verified bugs are those which the author is able to duplicate on machines that fall within the equipment requirements list. Registered Support ------------------ The registered version entitles the purchaser to unlimited support via netmail, the DB/Soft BBS or via US Mail. I am unable, however, to provide telephone support. Install-Pro Reference Manual - 4 - Frankness Clause ---------------- As you well know, it's darned difficult to get a publisher to stand behind his product. He usually guarantees the diskette (what a joke) and hangs you out to dry. If there is an error in the program, I will do anything possible to correct it in a timely fashion. I am also very interested in any ambiguities or errors in this documentation. Whatever problems you do find, I would appreciate a note. Disclaimer ---------- While every effort has been made by the author to ensure the fitness of use and integrity of Install-Pro, the author cannot and will not accept responsibility for any damage, physical or otherwise, to any equipment owned by the purchaser. The author habitually recommends that all customers back up their data regularly and frequently; that recommendation applies here as well. The maximum remedy available to the purchaser in the event of any type of dispute is the purchase cost of the software. About Config.sys and Autoexec.bat --------------------------------- This is ever a controversial subject if I've ever seen one. I have seen opinions ranging from "My users are too stupid to know about these things" to "No programmer had better touch it!" I worried about this for a long time before concluding that I choose to leave it up to the programmer (literally). If you want to write a routine modifying system files, have at it, and run it with the RUN command, described later. Given the multiple locations for FILES commands (either autoexec.bat, config.sys, 4dstart.bat or heavens knows where) as well as the loadhi complications of DOS 5, DR DOS and Quarterdeck products, the installer is likely to cause more damage trying to change them through an install process than to increase the chance of an application running successfully. It is naive for a programmer to believe that he is going to improve a machine setup, especially since that machine is quite likely running applications even more sophisticated - perhaps Quattro Pro or Windows 3.0. Since all system configurations must be determined at run-time anyway, just document system requirements and leave the system files be. One idea that can be quite easily handled is to offer to load the file(s) in a text editor to give the user the opportunity to make changes immediately. Install-Pro Reference Manual - 5 - Contacting the Author --------------------- If you have access to Fidonet netmail, contacting me at 1:203/38.6 will get the fastest response. The DB/Soft Online is available 24 hours a day if netmail is not available to you - just leave a comment to the sysop when logging off. If you leave a netmail or snail-mail return address, you won't have to call back for a response, I'll be happy to drop the price of postage or a crash netmail message. Failing that, mailing me at 3200 Truxel Rd. #199 Sacramento CA 95833 will get a prompt response, but will take about a week for the two-ended delivery. My voice number has been included on page one, but should only be used by those interested in ordering the software. The Future ---------- I am currently working on a VIEW command that will allow you to specify a file to be scrolled through by the user. This would remove the current necessity of you providing your own viewer and accessing it with a RUN command. This will be included in Install-Pro 1.21. Also in the works is multiple-page Hello and Good-Bye screens. Any lines in excess of the maximum would be shown on a subsequent screen, with new-page codes being allowed. The number of pages allowed will only be limited by available ram. Finally, I am planning an optional SIZE command that will specify the total disk space that the files assigned to each label will occupy. At installation time, if insufficient disk space is detected, the user will be given the opportunity to abort. About the User's Guide ---------------------- The file instpro.usr contains a user's guide for Install-Pro from the user's point of view. That is, it discusses the screens he is going to see, what actions are expected of him, etc. Feel free to modify and print this file in any way you see fit to help your users out during installation. In most cases this won't be necessary, but just in case, it's available. Script Syntax ------------- When install.exe is executed, the first file it looks for is install.001 in the root directory of the drive that install.exe is located on. If install.001 is not available, the program terminates. If install.001 is processed successfully, and an additional installation disk is specified, then the user will be prompted for the correct disk to insert to continue. Install-Pro Reference Manual - 6 - Before beginning immediately with the syntax proper, an explanation of how Install-Pro functions is in order. The concept of Install-Pro centers around what I call a label name. A label name is simply an arbitrary name that you give to the characteristics of a single installation directory. These characteristics include the prompt that user is going to see when asked where to put this directory, the default that the user is going to see when prompted, the subdirectories that are going to be created child to this directory, and the files that are going to be transferred to this directory or one of its children. Since you the programmer don't know what a user is going to name his installation directory, a label name provides you with an alias to refer to it by. Before you can refer to a label name, it must first exist. The USER token, discussed below, is the token that creates space for a label name and all of its associated characteristics. FILE, SUBDIR and RUN tokens that refer to a label must come after the USER token that defines it. It's that simple. The following is a brief overview of the syntax needed for install.001: BANNER "Banner goes here" HELLO "Welcome text goes here" (additional HELLO lines) USER <label name> "User prompt" [Default Destination] (additional USER lines) SUBDIR <label name> <child subdirectory> (additional SUBDIR lines) FILE <label name> <filename> (additional FILE lines) RUN "command line" (additional RUN commands) GOODBYE "So-long text goes here" (additional GOODBYE lines) DISK 2 -or- END AUTHORIZATION <nnnnn> The omission of the last line (disk <disk number>) indicates that no more installation disks need to be processed. The syntax for install.002 through install.999 is slightly different, as follows: FILE <label name> <filename> (additional FILE lines) RUN "command line" (additional RUN commands) GOODBYE "So-long text goes here" (additional GOODBYE lines) DISK n -or- END In both of these examples, the order that the tokens appear is the most logical, but is not strictly required. The following is a list Install-Pro Reference Manual - 7 - of token order requirements: 1. HELLO and BANNER tokens must appear before the first DISK token (if any) in install.001. 2. RUN commands are executed BEFORE disk swaps, but after all other processing. This means that the files on the current installation diskette are guaranteed to exist for the current RUN commands. Furthermore, this guarantees that directories created with SUBDIR, files transferred with FILE and directories created by the user with USER tokens will exist at the time of any RUN commands. Essentially, the final state of a particular installation disk exists for the RUN command. 3. AUTHORIZATION must occupy the last line of install.001 (Registered versions only.) 4. DISK must occupy the line directly before AUTHORIZATION on install.001, or the last line on all other installation disks. In effect, DISK flushes the accumulated tokens into actual processing, and is followed by a disk swap. 5. FILE, SUBDIR and RUN lines MUST come AFTER the USER line that defines any label names used for these commands. 6. Lines with a preceding semi-colon, or empty lines are ignored by Install-Pro. An empty line is a line with all whitespace, with no tokens detected by the parser. 7. FILE tokens transfer files on the CURRENT installation diskette when END or DISK is encountered. The filename specified with FILE must be on the same installation diskette as the FILE token. Script Tokens ------------- BANNER ------ Syntax: BANNER "Any text enclosed in quotes" The BANNER token identifies the line of text to be shown to the user as the program name on the opening screen. Up to 71 characters 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. Install-Pro Reference Manual - 8 - BANNER overwrites any previous BANNER definitions. BANNER is recognized only in install.001, on any line previous to DISK 2 (or AUTHORIZATION on single-disk installations.) If BANNER appears in install.002+, it will be ignored. If DISK or End-of-file are reached in install.001 and no BANNER has been found, a very small message-less box will be formed - harmless but unattractive. Shareware note: Although the BANNER token will be recognized and parsed, it is ignored in unregistered versions of Install-Pro. It makes no difference if it is included or not. HELLO ----- Syntax: HELLO "Any text enclosed in quotes" The HELLO token identifies a line of text to be shown to the user on the welcome screen. Up to 13 HELLO lines can be scripted, with each line having a maximum length of 71 characters. Characters in excess of 71 are ignored (truncated.) 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 (""). If quotes are omitted, only the first word after HELLO will be detected. If no text is detected after HELLO ("" DOES qualify as text) then Install-Pro will abort with a message. Up to 13 HELLO lines are allowed - subsequent HELLO lines over-write the most recent HELLO line. HELLO is recognized in install.001, on any line previous to DISK 2 (or AUTHORIZATION on single-disk installations.) If HELLO appears in install.002+, it will be ignored. If DISK or End-of-file are reached in install.001 and no HELLO has been found, a very small message-less box will be formed - harmless but unattractive. Shareware note: Although HELLO tokens will be recognized and parsed, they are not displayed in unregistered versions of Install-Pro. It makes no difference if it is included or not. Install-Pro Reference Manual - 9 - USER ---- Syntax: USER <label_name> "prompt" [default directory] This token is used to assign a prompt and a default destination to a label that is specified by the programmer. When the user inputs his destination directory it will be associated with this label name. This token also creates the space needed for FILE, RUN and SUBDIR tokens to function. label_name: The label name can be any single word of up to 40 characters, although less than ten characters is usually more than enough. A typical label name might be prog_files, data_files, etc. prompt: The user prompt can be up to 23 characters. Examples of typical prompts are "Help Files:", or "Data Files:". The quotes are required if more than one word is in the prompt. default directory: A default directory is optional. If specified, the directory must be in the form of a fully qualified DOS path, complete with drive and semi-colon. Keep in mind your default will not be checked for validity until it is accepted by the user. Up to 14 USER lines may be specified. Any additional USER lines cause the least recent line to be ignored. If no labelname or user prompt are detected, Install-Pro will abort with an error message. Only the default destination is optional. USER lines may occur anywhere in install.001 prior to DISK or End-of-file (in the absence of DISK.) SUBDIR ------ Syntax: SUBDIR <label_name> <dirname> This OPTIONAL token defines any directories that the programmer wishes created as children to the user-specified directories. The specified label name must match one of the label names defined under the USER token, described above. Any number of SUBDIR lines may be used in the script. label_name: Install-Pro Reference Manual - 10 - The label name specified here MUST have been previously defined with a USER token. dirname: The directory structure is not required to start with a leading backslash, but it may be less confusing if it does. Either way, the directory will be created as a child as expected. SUBDIR lines may exist anywhere in any install.??? file, but must precede the first use of its created directory or the program will error out with a Subdirectory Error. SUBDIR must also come after the USER line that defines the label name to which SUBDIR refers. For example, assume the following partial script: USER label_1 "Data Files" C:\MYAPP\DATA SUBDIR label_1 \MOREDATA If the user accepted the default, the C:\MYAPP\DATA directory would be created. Also, as a result of the SUBDIR line, the C:\MYAPP\DATA\MOREDATA directory would be created. Furthermore, if the SUBDIR line had instead read: SUBDIR label_1 \MOREDATA\DATADATA all directories parent to DATADATA will created as well as DATADATA. That is to say, you don't have to specify explicitly all directories that you want created, just the entire chain that you want to be ensured exists. In a more extreme example to illustrate this point, assume: USER, label_1, "Data Files", "C:\DATA" ENDUSER SUBDIR, label_1, "\MORE\DATA\DATA\DATA" ENDSUBS All five of the specified directories would be created. CAUTION: The DOS limit for subdirectory length is 65 characters, including drive and colon. Keep in mind the maximum user-entered directory is up to 40 characters, leaving you up to 24 characters with any margin of safety. If the total exceeds 65 characters, DOS returns a directory creation error. FILE ---- Syntax: FILE <label_name> <filename> Install-Pro Reference Manual - 11 - This token defines the files that are to be transferred from the current installation diskette. The word following the FILE token must be a label defined on one of the USER lines. label_name: The label name specified here MUST already have been created with a USER token. filename: The filespec can take one of two forms. First, it can be a regular dos filename, in which case it would be transferred to the directory associated with the specified label. Or second, it can include an optional directory chain child to the directory associated with the specified label, in which case it would be transferred to that child directory. For that child directory to exist, it would be necessary to previously create it with a SUBDIR line, described previously. Any number of FILE lines can be specified. Two examples follow: Assume the following partial script: USER label_1 "Data Files" C:\DATA FILE label_1 main.exe FILE label_1 main2.exe This script would transfer main.exe and main2.exe from the root directory of the current installation diskette to the directory that the user entered when prompted with "Data Files", perhaps the default directory presented to him, "C:\DATA". Now, consider this more advanced example: USER label_1 "Data Files" C:\DATA SUBDIR label_1 \HELP FILE label_1 main.exe FILE label_1 main2.exe FILE label_1 help\help.dat Assuming that the user accepts the default C:\DATA, this script would transfer main.exe and main2.exe from the root directory of the current installation diskette to the directory that the user entered when prompted with "Data Files", just as in the previous example. Also, as child to the user-entered directory would be created a help directory, to which would be transferred help.dat. The final structure if all defaults were accepted by the user would be: C:\DATA\MAIN.EXE C:\DATA\MAIN2.EXE C:\DATA\HELP\HELP.DAT Install-Pro Reference Manual - 12 - If no label or filename are detected, Install-Pro will abort with an error message. Splitting Files --------------- If you have files that just cannot fit onto a distribution diskette, Install-Pro has the ability to handle split files. First an example of how to accomplish this: FILE label_1 main.ex1e FILE label_1 main.ex2e These two file lines would create a file called main.exe in the label_1 directory, from TWO files main.ex1 and main.ex2. What Install-Pro does is looks to see if an extra character has been added to a filename. If there is an extra character: 1. The source filename is assigned an extension of the first three characters of the filename's extension. This file should exist on the current distribution floppy. 2. The destination filename has the third character replaced with the fourth, and the fourth character removed. Please note that: 1. main.ex1e and main.ex2f would not cause an append to occur. The filenames (with the exception of the third character of a four-character extension) MUST match. In this case, main.exe would be created from main.ex1, but main.exf would NOT be created. 2. The files MUST have the same label name assigned to each of them. If main.ex1e and main.ex2e were assigned different labels, \directory1\main.exe would be created, but \directory2\main.exe would NOT. 3. I strongly urge that multiple split files of the SAME name NOT be installed. For example, if you had two huge, but different, files called main.dat, and wanted them both split using main.da1t and main.da2t for each of them, but assigning different labels to them, the user COULD still assign both labels to the same directory, with unpredictable results. This is an extreme example that I don't thing you will run into. The append/create decision is resolved as follows: 1. If third character of the extension is a '1' and the fourth character exists, the file is CREATED. Install-Pro Reference Manual - 13 - 2. If the third character is greater than a '1' and the fourth character exists, the file is APPENDED. Note that trying to append to to a file that does not yet exist will cause DOS to return a 'file not found' error, and is used to prevent accidentally append filename.ex2t on top of an existing file. The practical limit to the number of splits is up to 9. 3. If the third character is a number, but no fourth character exists, no split-file decision occurs - the file will be created. 4. Note that main.0011, for example, is perfectly legal. What it specifies is that main.001 is to be created, and that it's the first file of a split file. Main.0021 would be appended to main.0011. This type of file transfer can be especially touchy if the order of files transferred and then appended is incorrect. If you split files, I strongly recommend that you debug your script carefully and compare the created file with the original (using the DOS program 'COMP' to be sure that they are identical to before releasing your application. RUN --- Syntax: RUN <command line> This token defines the command lines to be built to execute any special programs or batch files that are needed to customize an installation. One use for this might be to run a config.exe program that will bring the user straight into configuring the application he is installing. Another use might be to create application menu definition files that couldn't be built at install-time otherwise. Run works by one of two methods. If the command specified on the command line has the extension ".EXE" or ".COM", the program is executed directly by Install-Pro. If no .EXE or .COM extension is specified, your command is run by invoking a command processor shell and passing it the command line that you specify. There must be enough memory to load both your program or command shell in addition to that used by Install-Pro - about 112k. Run command lines of longer than one word must be enclosed in quotes. Any number of RUN command lines can be defined. Further, the directory(s) that the user enters at runtime are available on the RUN command lines. Simply specify any label with a Install-Pro Reference Manual - 14 - preceding exclamation point (!) and the user-entered directory will be directly substituted for that portion of the text. The directory is inserted without any leading or trailing spaces, but the spaces on the RUN command line are UNTOUCHED. That means that the following RUN commands would work: RUN dir !label_1 RUN !label_1\myprog RUN copy !label_1\this.fil !label_2 RUN anydir\anyprog Finally, a special sequence, !home, signifies that you wish to specify the root directory of the installation disk. For obvious reasons, don't create any labels called 'home' with the USER command, or the !home sequence will no longer point at the home directory, but rather at the directory entered by the user for this labelname. RUN !home\myprog would execute myprog from the root directory of the installation disk. When a RUN command is executed, the screen is saved and cleared first. After it has completed, the screen is restored. If the command shell attempt fails, the user will be notified of the reason (usually memory) but the INSTALLATION WILL NOT ABORT. If there is a critical part of your installation occuring with a RUN command, be sure to document it in your manual installation instructions for the user. A few points to keep in mind: 1. The error trapping is much more solid if Install-Pro directly executes your program. This is due to the fact that if the command shell is used instead, success constitutes the shell having successfully loaded. Whether enough ram existed for your program or your program was found is not detectable by Install-Pro. Whats worse, in the case of the alternative command processor 4dos, the command shell load process occurs in two parts. The first part of 4dos can load successfully but fail to load the rest of itself and still return success to Install-Pro. 2. Memory requirements for command shell RUN commands can be significantly higher, especially if COMMAND.COM is the target of COMSPEC (about 27k). 3. A single RUN command in .EXE mode is allowed up to 9 arguments. Additional arguments are ignored. In command shell mode, there is no limit to the number of arguments allowed. 4. A single RUN command in .EXE mode is allowed a length of Install-Pro Reference Manual - 15 - up to 256 characters. The length of any single argument is restricted to 128 characters. If argument zero (the directory, path and filename of the executing program) is longer than 128 characters, DOS will return an error message back to Install-Pro. If any other argument is longer than 128 characters, the argument will be truncated (undesirable, indeed.) 5. A single RUN command in command shell mode is allowed a total length of up to 256 characters, but keep in mind that the widely-used command interpreter COMMAND.COM will only allow 128 characters total. 4dos, among others, allows up to 256 characters. 6. I gave consideration to errorlevels from executed programs (they are not available from shelled commands), but considering the fact that the only recourse is to report the errorlevel to the user as a 'possible error' or alternatively to abort the installation, I abstained. Registered users with special errorlevel needs are free to contact me for a custom version of Install-Pro that will handle errorlevels in one of these two fashions. GOODBYE ------- Syntax: GOODBYE "So-long text goes here" This token is used to build an end-of-install message to display to your users after successful completion of installation. 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 "". The lack of any GOODBYE lines would cause a small, empty box to appear, harmless but silly looking. Somewhere near the bottom of the GOODBYE text, you should include something to the effect that a keypress will exit the program. Up to 14 GOODBYE lines can be defined, anywhere in the script file(s). GOODBYE lines after the 14th are ignored. When an install.??? file is processed that does not have a DISK token, after all transfers have taken place, the GOODBYE messages are displayed, after which the program terminates. DISK ---- Syntax: DISK This token specifies that the user is to be prompted to insert the Install-Pro Reference Manual - 16 - next numbered disk. If the disk being processed is disk 1 with install.001, specifying DISK would cause the user to be prompted to insert disk #2. If the user presses enter and the disk in the drive in which install.exe exists does not have install.002 in the root directory, the user will be instructed to try again. This loop repeats until the user inserts the correct disk (if you've ensured that the user received it) or until the user presses Escape, which would terminate the program. DISK MUST come before AUTHORIZATION in install.001 Install-Pro Reference Manual - 17 - END --- Syntax: END This token indicates that the end of the last installation script has been reached. Just like DISK, END forces all information stored in all labels to be processed. However, unlike DISK, when this processing is completed, the program displays the GOODBYE messages and exits. This token is mutually exclusive of the DISK token. Whichever is encountered first will dictate the processing that will occur, and the other will be ignored. END MUST come before AUTHORIZATION in install.001. AUTHORIZATION ------------- Syntax: AUTHORIZATION 00000 This token is only required on the last line of install.001. Its function is solely to create a space for Install-Pro to write an authorization code. After you have run Install-Pro with your key on the command line, this line will be updated with the appropriate authorization code for the current script. If you are evaluating an unregistered copy of Install-Pro, you need not worry about this line. The authorization concept is used purely to ensure the integrity of registered versions. Script Debugging ---------------- Before you send your latest sale to your customers, you are going to want to make sure that the installation as you envision it is actually going to happen. I have made a great effort to make all error messages as descriptive as possible. In the cases of DOS returning an error, the error message is given verbatim back to you. I have taken great lengths to make the parser as smart as possible; however, it is possible to make any parser look stupid with intentional or lucky entries (just leave a terminating curly bracket off a c function if you need proof.) If you follow the syntax closely, the parser will make both Install-Pro and your application look great. If you feel that your syntax is correct, or should be, but the parser seems to disagree with you, leave me a note through the channels described in "Contacting the Author." Install-Pro Reference Manual - 18 - Error Messages -------------- The following are the standard error messages built into Install-Pro. The nature of these errors is such that Install-Pro cannot continue, so these error messages can probably be classified as Fatal Errors. Of course, the message the user sees doesn't include the word 'Fatal' for obvious reasons. The message the user sees is similar to the one that follows: ┌───────────────────────────────────────────────────────────┐ │ The following unrecoverable error has occurred: │ │ │ │ Error opening install.001 │ │ │ │ Please refer to your documenation for manual installation │ │ instructions if the problem cannot be corrected. │ │ │ │ Press a key to terminate... │ └───────────────────────────────────────────────────────────┘ Any application should be distributed with manual installation instructions to help alleviate the unexpected, hence the wordage of the error message. The documentation that you provide your users should include a telephone number in case of installation difficulties, or in case manual procedures also didn't succeed. DOS version 3.0 or higher required A DOS version prior to 3.0 was detected. Install-Pro requires MS-DOS 3.0 or later. Error opening install.001 INSTALL.001 was not found in the root directory of the disk that Install-Pro is located on. Error parsing installation script: line nn A token was expected but not found on the indicated line. This usually means that one or more words is missing on this line. Memory allocation error A request for more memory was denied. This is extremely unlikely to occur, as Install-Pro requires only about 112k of free RAM. Error transferring xxxxx to yyyyy DOS returned an error while trying to transfer the indicated file to the indicated destination. Install-Pro Reference Manual - 19 - Error creating directory: zzzzz DOS returned an error while trying to create the indicated directory. The most likely cause is if the user tries to install the application to a directory that is the same name as an existing file. Authorization Error (registered versions only) Install-Pro detected an authorization code that did not match the accompanying script file (install.001). Run Install-Pro again with your key to authorize your script. Executable integrity Error - bad executable Install-Pro detected internal errors in its executable file. This may mean that the file has become corrupted or infected by a creepy-crawly. Restore an original from your backup and retry. Label not found: xxxxx, line nn The token in the <label name> position on the specified line does not correspond to a previously defined label name created with a USER line. Unexpected EOF - AUTHORIZATION, END or DISK expected If Install-Pro parses to the end of a script without finding some indication of how to terminate, it returns this error. Critical Errors --------------- Should a disk door be left open (or any other critical error trapped by DOS, for that matter) a Critical Error handler built into Install-Pro will take control and provide the user with a menu similar to this one: ╔════════════════════[ CRITICAL ERROR ]═════════════════════╗ ║ ║ ║ Error Code : Device not ready ║ ║ Class of Error : Hardware failure ║ ║ Location : Unknown source ║ ║ Read error on drive C: DOS error ║ ║ Recommended Action : Retry after correcting error ║ ║─────────────────────────────────────────────────────────── ║ Retry Abort Ignore Fail ║ ╚═══════════════════════════════════════════════════════════╝ If the user accepts the default (Retry after correcting error), he will be in most cases safe. Of course, if his computer picked the exact moment that he's installing your application to crash its hard Install-Pro Reference Manual - 20 - drive, no Critical Error handler is going to recover very gracefully. Registration Keys ----------------- This section deals only with registered copies of Install-Pro. Shareware versions have no distribution protection built in whatsoever. With your registered Install-Pro diskette you received a key in the form of a series of characters. This key protects copies of Install-Pro that are released with your applications from being used with scripts other than the one you defined. This key is utilized simply by you the programmer including it with absolutely no accompanying punctuation whatsoever as the only argument on the install.exe command line. The result is that the script is processed normally, with an authorization code created on the AUTHORIZATION line. Observing this procedure ensures that your scripts never cause Install-Pro to abort with an Authorization Error message. For development purposes, just create a batch file to save repeatedly typing in your key. Then, when you release your product, the script has the latest AUTHORIZATION (see above) encoded in your script, enabling install.exe to only to work with the unmodified script. This protects my product, as well as protects your installation from unwanted tampering. Warning: Each purchaser of Install-Pro receives an exclusive key. Your conscience may not be the only person that will know if you distribute it - my personal key will tell me the original purchaser of any copy of Install-Pro. PLEASE do not give your key to anyone, including purchasers of your own software. To do so is unethical, immoral, violates your License Agreement (meaning illegal) and causes baggy, shiftless eyes. (If you'd never dream of it, your heart is all programmer and I sincerely thank you!) Virus Protection ---------------- In consideration of the large number of creepy-crawlies that can infect programs, I have installed multiple internal checks to verify the integrity of Install-Pro. If you run across the error message: "Executable Integrity Error", a discrepancy has been discovered in the executable. However, viruses are not the only possible cause; Pklite or Lzexe, if used on Install-Pro, will trigger this error. If you have major space considerations, and were considering making Install-Pro smaller, remember that you can put the largest of the files on diskettes 002 and higher, where install.exe does not need to exist. Another possible cause of this error message could be good old-fashioned file corruption. In any case, restore the executable from the original distribution floppy or .zip file and you should be Install-Pro Reference Manual - 21 - fine. If you come across an original copy of Install-Pro, shareware or otherwise, that has an Integrity Error message, I'd appreciate you letting me know its source and/or circumstances. Install-Pro Reference Manual - 22 -