DP Tool Club 8

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

/ DP Tool Club 8 / CDASC08.ISO / VRAC / UNST13.ZIP / INSTALL.DOC < prev next >

Wrap

Text File | 1993-08-16 | 70.4 KB | 2,273 lines

Universal === = = == === === = = | |\ | | | | | | | | | \| \\ | |=| | | === = = === | = = === === Universal INSTALL Software Installation Utility version 1.3 SHAREWARE KIT DOCUMENTATION (39 Pages) More information available by running README.EXE! Produced by The GoodSoft Co. 1630 30th Street, Suite 235 Boulder, Colorado 80301 USA CompuServe Mail ID 72073,225 FAX Number: (303) 430-7943 <ASP> Member Page 1 CONTENTS ============= About Universal Install/The GoodSoft Co...........4 ASP Ombudsman Statement...........................4 Purchasing Universal INSTALL......................5 Foreign language versions of INSTALL..............6 What is a script file?............................7 How to create a script file.......................7 The script file format............................7 SCRIPT FILE COMMANDS (BY CATEGORY) Creating and Using Windows Creating a window section.......................8 Border..........................................8 BottomTitle.....................................8 CloseWindow.....................................9 ColumnMargin....................................9 PopUp...........................................9 RowMargin.......................................9 ShadowColor.....................................10 ShadowType......................................10 StartColumn.....................................10 StartRow........................................11 Text............................................11 TopTitle........................................11 WindowColor.....................................12 General Screen Commands BackPlane.......................................13 BottomBar.......................................13 ClearPlane......................................13 ClearScreen.....................................14 Text............................................14 TopBar..........................................14 General System Commands CheckDiskSpace..................................15 ColdBoot........................................15 DiskSpaceReq....................................15 DOSVersion......................................16 FindDisk........................................16 FindBootDrive...................................16 Jump............................................17 KeepLogFile.....................................17 RunProgram......................................18 SystemDelay.....................................18 Wait............................................19 WarmBoot........................................19 Getting Keyboard Input From the User Creating a user-input section...................20 Action..........................................20 Page 2 Default.........................................20 StartColumn.....................................21 StartRow........................................21 TextColor.......................................21 Width...........................................22 Using Script Variables Script variables................................23 Using Buttons Creating a buttons section......................24 ButtonOffColor..................................24 ButtonOnColor...................................24 ColumnMargin....................................25 RowMargin.......................................25 Distance........................................25 Message.........................................26 Result..........................................26 GoButton........................................26 StartColumn.....................................27 StartRow........................................28 Travel..........................................28 Copying Files Creating a copy files section...................29 DestPath........................................29 DiskLabel.......................................29 CopyFile........................................30 SourceDisk......................................30 SourcePath......................................31 StatusLineBG....................................31 StatusLineFG....................................31 StatusColumn....................................31 StatusRow.......................................32 Modifying CONFIG.SYS Creating a modify config section................33 AddLine.........................................33 FindString......................................33 Adding Parameters...............................34 RemarkString....................................34 SaveOriginal....................................35 Modifying AUTOEXEC.BAT Creating a modify autoexec section..............36 AddLine.........................................36 AddPath.........................................36 SaveOriginal....................................37 Using the "Un-Install" Feature How "un-install" works..........................38 Creating an installation log file...............38 Using the REMOVE utility........................38 The REMOVE utility data file....................38 Tips on using REMOVE............................39 Page 3 ABOUT UNIVERSAL INSTALL =========================== Universal INSTALL is a product of The GoodSoft Co., a contract software development firm based in Boulder, Colorado. The GoodSoft Co. was established in 1988 through consulting and custom programming contracts. We have been developing commercial software for others for many years, and Universal INSTALL originally began as a project for us to simplify the installation of the software we created for our clients. Universal INSTALL is being offered through the shareware concept, e.g. try it before you buy it. While copyright laws apply to shareware in the same manner as with commercial software, you are encouraged to pass this SHAREWARE KIT (with all files included and un-modified) around freely, so long as you don't charge more than a reasonable fee for actual distribution costs. If you use Universal INSTALL on a basis past an "evaluation period", or expect to distribute your INSTALL programs with your software, you are expected to pay for the product. (Please see "Registering..." below). _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER ASP OMBUDSMAN STATEMENT =========================== " The GoodSoft Co. is a member of the ASP (Association of Shareware Professionals). ASP wants to make sure that the shareware concept works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at: 545 Grover Road, Muskegon, MI 49442-9247 USA. ASP ombudsman FAX #: (616) 788-2765. Or, send a CompuServe message via CompuServe Mail to 70007,3536. " Page 4 PURCHASING UNIVERSAL INSTALL ================================== Because the shareware concept is based on trust, if you use Universal INSTALL beyond a reasonable evaluation period, you need to purchase the product. This is known as "registering" or becoming a registered user. Becoming a registered Universal INSTALL user has many advantages, as described in README.EXE and listed below... - Script generator package registered to your company. - Your choice of a script file distribution filename (instead of the SHAREWRE.VER filename used in this kit), also registered in our database for your company's exclusive use. - Winster, a "screen painting" tool that creates script files for you. - Published developer documentation and script file tips. - Viewer, a utility that allows your user's to view a text file in a manner similar to our README.EXE. - DiskMake, a great time-saving media build utility. We use it to create our distribution disks. - Remove, a utility to allow your users to "undo" an installation. - Access to non-English versions of INSTALL. - An extra set of pre-written scripts - adapt them for your use. - Access to the latest news about Universal INSTALL. - Participation in developing future releases and features. - The next upgrade...free! To order: Registered user package...........$36.00 (US), $40.00 (Outside U.S.) Shareware kit.....................$ 1.00 (US), $ 3.00 (Outside U.S.) Send a company/personal check or money order (in U.S. funds) to: The GoodSoft Co. 1630 30th Street - Suite 235 Boulder, Colorado 80301 U.S.A. CompuServe Mail 72073,225 Inquiries only: FAX: (303) 430-7943 If you prefer to pay via credit card, the following organizations will accept orders for Universal INSTALL: CompuServe (GO SWREG, database ID# 907) Software Excitement! 1-800-444-5457 Page 5 NON-ENGLISH LANGUAGE VERSIONS OF UNIVERSAL INSTALL ====================================================== The great part about using script files for your installation process is that you have complete control over what is shown to your users. This means that creating an installation that uses a language other than English is rather simple - just create a script file that displays text in the language desired. The one aspect of INSTALL that is not under script file control is the error messages displayed if something unexpected happens. These error messages are built into INSTALL on purpose: (1) to have them always available to the program, and (2) to avoid having to mess with more files during the installation process. This keeps INSTALL as self-contained and fast as possible! Since many of our customers are using Universal INSTALL in non English-language countries, we've decided to offer foreign language versions of INSTALL. Although only a German-language version is currently available (as of 8/16/93), we are looking to offer more languages immediately. Our standard practice is to offer a free Universal INSTALL package to the first developer willing to translate a few lines of text. We then build the translated text into a new language version of INSTALL. So, if you're interested in a non-English version, please ask us for the current availablity of different languages. And if you would like to offer us your translation skills, drop us a line for more information. Page 6 WHAT IS A SCRIPT FILE? ========================== A script file is just our name for a special text file that SCRIPT.EXE, the Universal INSTALL script generator, can understand. Script files contain special keywords that tell Universal INSTALL what colors to use, the size of your windows, etc. The advantage of using a script file is that you get total control over how your installation will look and operate. Rather than answer a few questions and create a "canned"-looking install utility, YOU control every aspect of the installation process. In fact, Universal INSTALL makes it easy for you to MATCH the look and feel of your own software! HOW TO CREATE A SCRIPT FILE =============================== Script files may be written with your favorite text editor or with a word processor that can save files in a text (ASCII) format. Included with this Universal INSTALL shareware kit is a sample set of pre-written script files that are easy to modify for your product. Try writing a simple script file or modifying one of the sample script files included in this shareware kit. Keep in mind that registered users get our Winster utility, which allows you to "paint" your screens, text, windows, etc. and let Winster write the script for you. Once you've written a script file, you'll run it through the script generator (SCRIPT.EXE). This utility will compress your script file and put your instructions into the binary format INSTALL.EXE understands. For this shareware kit, the script generator creates an output file called "SHAREWRE.VER". Registered users pick the name that their script generator creates. THE SCRIPT FILE FORMAT ========================== Script file commands may be capitalized in any way you desire. A quick glance through our GOODSOFT or SIMPLE script files included in this kit will give you a good idea of the proper format for a script file. The format is really not as strict as it looks. When you run your script through the script generator, the utility will tell you if it doesn't understand something you have written. The entire process is much like using a language compiler, but much, much simpler! Page 7 C R E A T I N G A N D U S I N G W I N D O W S Creating a "BuildWindow" Section ==================================== To create a window, start a section in your script file as follows. This type of section uses all the script file commands that are relevant to windows... BUILDWINDOW WindowColor =White Border =Blue StartRow =Center StartColumn =Center ColumnMargin =1 RowMargin =8 PopUp =No ShadowType =Big TopTitle =Welcome! BottomTitle =Press ENTER to continue... ENDWINDOW BORDER Command ================== What it does....determines a border and border color for a window. See also........ShadowColor Usage...........Border =<Blue, Gray, etc...> Example.........Border =Blue If this command is used, it tells INSTALL to put a border around the window in the specified color. The default situation for windows is no border, so if you want a bordered window, use this command. Otherwise, leave it out of your window section. BOTTOMTITLE Command ======================= What it does...puts a message on the bottom border of a window. See also.......TopTitle Usage..........BottomTitle =<text message> Example........BottomTitle =Press ENTER to continue The default for a window is no bottom or top titles, so you must use these commands if you want some messages on the window borders. Note that the message will be centered on the bottom border. This is a short-cut to using the Text command for putting some text on the window border. The text will be displayed with white characters on the border color background. Page 8 CLOSEWINDOW Command ======================= What it does....removes a "pop up" window and restores the screen to its original appearance. See also........PopUp Usage...........CloseWindow Example.........CloseWindow This command restores the screen to its original display before the pop up window was put on the screen. COLUMNMARGIN Command ======================== What it does....leaves X number of columns as space between a window border and the interior text. See also........RowMargin Usage...........ColumnMargin =<number of columns> Examples........ColumnMargin =7 This command is useful for keeping the window text from being crammed up against the border of a window and helps you create a balanced look for your windows. POPUP Command ================= What it does....determines whether a window is a "pop up" window Usage...........PopUp =<Yes or No> Example.........PopUp =Yes A "pop up" window does not overwrite the screen below it, so that when you restore a window with the CloseWindow command, your screen will look unchanged. This is useful for error messages or help windows. The default type of window is not a pop up, so if you want this feature, you must use the PopUp command. ROWMARGIN Command ===================== What it does....leaves X number of rows as space between a window border and the interior text. See also........ColumnMargin Usage...........RowMargin =<number of rows> Example.........RowMargin =1 This command is useful for keeping the window text from being crammed up against the border of a window and helps you create a balanced look for your windows. Page 9 SHADOWCOLOR Command ======================= What it does....determines the color of a window. See also........ShadowType, Border Usage...........ShadowColor =<White, Blue, etc...> Example.........ShadowColor =Gray This command can give different looks for windows placed within other windows. Experiment with different colors to find an interesting look. SHADOWTYPE Command ====================== What it does....determines the type of shadow to use for a window. See also........ShadowColor, Border Usage...........ShadowType =<None, Big, Small> Examples........ShadowType =None ShadowType =Small The ShadowType command determines the type of shadow to use for the window. A shadow creates a minor 3-D effect for the window. A Big shadow uses the backplane characters to create the shadow. This type looks best for windows displayed directly on the backplane. A Small shadow type looks best for windows placed within other windows. The default type for a window is Big. STARTCOLUMN Command ======================= What it does....specifies the column on which to start the left edge of the window. See also........StartRow Usage...........StartColumn =<col #> or <Center> or <Window + <col #>> Examples........StartColumn =5 StartColumn =Center StartColumn =Window+1 The first example is used when you want to start the window on a specific column. The second example is a short-cut and tells the script generator to automatically center the window on the screen. The third example is useful for placing windows within another window. The example will start the new window on the previous window's StartColumn plus one more column. You can see how this will place the window within the previous window. See the GOODSOFT script for more examples. Page 10 STARTROW Command ==================== What it does....specifies the row on which to start the top edge of the window. See also........StartColumn Usage...........StartRow =<row #> or <Center> or <Window + <row #>> Examples........StartRow =2 StartRow =Center StartRow =Window+2 The first example is used when you want to start the window on a specific row. The second example is a short-cut and tells the script generator to automatically center the window on the screen. The third example is useful for placing windows within another window. The example will start the new window on the previous window's StartRow plus two more rows. See the GOODSOFT script for more examples. TEXT Command ================ What it does....draws text on the screen. Usage...........Text <color> on <color> <column> <row> = <text> Example.........Text white on blue 10,15 =Sample text string! The Text command allows you to place a text string on the screen in a specified color. This is useful for updating the text of a window after the window has already been drawn, for example. Note that the row and column coordinates are based on the top left corner of the screen being (1,1) and the lower right corner being (80,25). This command may also be used within a window section. If it is used in this way, the column and row coordinates will be based on the top, left corner of the window, instead of this screen. This allows you to move the window around without having to update your text coordinates. TOPTITLE Command ==================== What it does....puts a text message on the top border of a window. See also........BottomTitle Usage...........TopTitle = <text message> Example.........TopTitle =Sample Installation Program The message will be centered in the window and be displayed with white characters on the border color background. Also see the BottomTitle command. Page 11 WINDOWCOLOR Command ======================= What it does....specifies the color of a window. See also........ShadowColor, Border Usage...........WindowColor =<Blue, White, Gray, etc...> Example.........WindowColor =Gray This command determines that color of a window. See the Border command to determine the border color for the window and the ShadowColor command to specify the shadow color for a window. Page 12 G E N E R A L S C R E E N C O M M A N D S BACKPLANE Command ===================== What it does....defines the color and character used for the screen background. See also........ClearPlane, ClearScreen Usage...........BackPlane <custom color> = <ASCII character> BackPlane <color> on <color> = <ASCII character> Examples........BackPlane teal =▒ BackPlane blue on gray =A The backplane can be used to create a colorful "workspace" for your installation program. It is not required - if you desire a standard black background, see the ClearScreen command. Custom colors are color combinations we have come up with to save you some time (and you might not have tried)! ASCII characters 176-178 look especially good as backplane characters. Possible custom colors are: Royal (dark blue) Teal (greenish blue) Purple (purple) Orange (orange) Mint (pastel green) Sky (bright light blue) Steel (dark gray blue) Slate (gray) BOTTOMBAR Command ===================== What it does...puts a "status line" on the bottom of the screen. See also.......TopBar Usage..........BottomBar <color> on <color> = <text> Example........BottomBar blue on white =This is a sample line! A bottom status line may be useful for displaying the names of files that are being copied, keeping a message such as "Press ESC to quit" constantly visable, or just to put a border around your screen. The "=" is optional, and if left out, indicates you don't want any text displayed on the line (i.e. blank status bar). CLEARPLANE Command ====================== What it does....clears the backplane. See also........ClearScreen, BackPlane, TopBar, BottomBar Usage...........ClearPlane Example.........ClearPlane Page 13 ClearPlane will redraw the backplane. This is very useful for getting rid of windows and text in preparation for the next window. Note that this command will leave any top or bottom status bars intact. If you want to erase everything on the screen, use the ClearScreen command. CLEARSCREEN Command ======================= What it does....clears the entire screen. See also........ClearPlane Usage...........ClearScreen Example.........ClearScreen ClearScreen creates an entirely black screen. This is very useful as the first and last commands in your script. TEXT Command ================ What it does....draws text on the screen. Usage...........Text <color> on <color> <column> <row> = <text> Example.........Text white on blue 10,15 =Sample text string! The Text command allows you to place a text string on the screen in a specified color. This is useful for updating the text of a window after the window has already been drawn, for example. Note that the row and column coordinates are based on the top left corner of the screen being (1,1) and the lower right corner being (80,25). This command may also be used within a window section. If it is used in this way, the column and row coordinates will be based on the top, left corner of the window, instead of this screen. This allows you to move the window around without having to update your text coordinates. TOPBAR Command ================== What it does....puts a "status line" at the top of the screen. See also........BottomBar Usage...........TopBar <color> on <color> = <text> Example.........TopBar white on red =Sample Installation Program A top status line can be very useful for displaying the name of your product or the name of the installation program. The "=" is optional, and if left out, indicates you don't want any text displayed on the line (i.e. blank status bar). Page 14 G E N E R A L S Y S T E M C O M M A N D S CHECKDISKSPACE Command ========================== What it does....Asks INSTALL to make sure there is enough available space on a disk for the installed software. Usage...........CheckDiskSpace =[drive letter designation] Example.........CheckDiskSpace =C:\ Sometimes it is useful to make sure that a user has enough disk space available to install your software, BEFORE getting deep into the install process! The CheckDiskSpace command is used for this purpose. When INSTALL checks for available space and there is not enough space available, it will display a pop-up error message and recommend that the user free up some disk space before installing. INSTALL does not do anything special if there is enough room for the installation. COLDBOOT Command ==================== What it does....initiates a "cold" reboot of the user's computer. See also........WarmBoot Usage...........ColdBoot Example.........ColdBoot A "cold" reboot is the same as if the user had just turned on his/her computer. Most computers check the system memory at this point. For most installations, a warm reboot will be sufficient, however. It is probably a good idea to allow the user to decide if they want to reboot the computer. DISKSPACEREQ Command ====================== What it does....specifies required disk free space for installation. Usage...........DiskSpaceReq =<amount expressed in K / 1000> Examples........DiskSpaceReq =2000 DiskSpaceReq =600 This command is used in conjunction with the CheckDiskSpace command to tell INSTALL the total amount of disk space required for the installation of your software. The amount of free space specified is multiplied by 1K (1000 bytes) by INSTALL. So, the first example above specifies a requirement for 2MB worth of free space. The second example states that 600K free space is required. See the CheckDiskSpace command for more information. Due to memory limitations, INSTALL can only check for free space of 60MB or less. Page 15 DOSVERSION Command ====================== What it does....checks the user's DOS for a minimum acceptable version. Usage...........DOSVersion =<version number> Examples........DOSVersion =5.0 If your product requires a minimum DOS version to run correctly (i.e. DOS > 3.2), this allows you to stop the installation process and warn the user before your software has been installed. This command would usually be one of the first commands in your script file. If INSTALL determines that the user's DOS is LOWER than the version you specifiy, the following message will be displayed and INSTALL will halt.... " Sorry, the minimum DOS version required for this product is X.XX Please contact your service representative or dealer for help. " Note: Don't use this command unless DOS versions are important to you. INSTALL doesn't do any checking unless this command is in your script file. FINDDISK Command ==================== What it does....searches all the user's disk drives for a disk with the specified volume label. Usage...........FindDisk =<Volume Label (a.k.a. Volume ID)> Example.........FindDisk =INSTALL When this command is used, INSTALL will search all the user's disk drives until it finds a disk with the same volume label. If a match is found, INSTALL returns the drive letter in the $FINDRESULT script variable. Otherwise, $FINDRESULT is blank. This command is useful when you want to locate one of your old product software disks for an update or just want to locate the drive that your distribution disk is in. FINDBOOTDRIVE Command ========================= What it does....locates the user's boot drive and returns the drive specification in the script variable, $BOOTDRIVE. Usage...........FindBootDrive Example.........FindBootDrive This command will return a string such as "C:\" in the script variable $BOOTDRIVE. You may then use the result of this command for setting up the default answer to questions such as... Page 16 what directory to install to? C:\DEMO In the example above, $BOOTDRIVE is used in place of the usual text string. Like all script variables, you may use $BOOTDRIVE anywhere regular text strings are used in a command. JUMP Command ================ What it does....skips file execution to the specified procedure name. Usage...........Jump =<Procedure Name> or On <Key> Jump =<Procedure Name> Examples........Jump =Quit to DOS On ESC Jump =Quit to DOS On ENTER Jump =Start Installation Jump is used to branch to different sections of the script file based on something the user has done. For example, if the user presses ESC to quit, you might want to jump to a procedure explaining what has been installed so far. Think of Jump as a GOTO statement. If you use the On..Jump format of the command, INSTALL will only jump to the procedure if the user has pressed the specified key. This is most useful after a Wait command, so that you can branch somewhere if the user presses ESC and somewhere else if the user presses ENTER. Note that the procedure name should be capitalized exactly the same as you capitalized it for the procedure. We did this to make sure that procedures were not confused with each other. Procedure names follow the format: [XXXXXX], where XXXXXX is the procedure name. See our example scripts for more guidance. KEEPLOGFILE Command ======================= What it does....tells INSTALL to maintain an installation log file. Usage...........KeepLogFile =<path and filename> Example.........KeepLogFile =c:\install.log This command is used when you want to distribute the REMOVE utility to your users. By using this command and the REMOVE utility, you are providing the ability for end-users to "undo" an installation, either immediately or sometime in the future. Many users seem to really appreciate the ability to un-install software that they no longer need. Please see the section on the "Using the Un-install Feature" for more information. Page 17 RUNPROGRAM Command ====================== What it does....run a program outside of INSTALL. Usage...........RunProgram =<program command line> Example.........RunProgram =pkunzip test.zip RunProgram =!DOS!chkdsk c: This command causes INSTALL to run a DOS process and execute the specified command line, just as if it was typed at the DOS prompt. INSTALL loses control of the screen at this point, so it's important for you to make sure that the screen looks the way you want. - INSTALL will handle any DOS errors that occur when trying to run the program (such as "File not found"), but it is up to the external program to handle errors once it has control. This is especially important to note, because running external programs require a large amount of memory. Since INSTALL loses control to the external program, out of memory errors may be ugly (depending on the program, of course!). We recommend using this feature for smaller-sized programs. - To run a DOS command, imbed "!DOS!" in your command line string (example 2 above). - You must specify the exact path and FULL filename of the program. You may use the $CURRENTPATH variable to your advantage here. For example, running the readme program on the install disk: $CURRENTPATH\readme.exe. - If the external program is one of your own programs, it is possible to match the installation look to the external program, so that the user will see a "seamless" installation. SYSTEMDELAY Command ======================= What it does....Pauses operation for X seconds. Usage...........SystemDelay =# of seconds Example.........SystemDelay =2 Useful for opening screens or slowing down copy file status messages so the user can see them. The number of seconds is approximate, and will vary slightly for faster/slower machines. Page 18 WAIT Command ================ What it does....waits for the user to press a specified set of keys. Usage...........Wait =<key>, <key>,.... Examples........Wait = Enter, Esc The wait command is useful when you want a user to "press ENTER to continue...". The INSTALL program will wait for the user to press one of the keys you specify. See the Jump command for branching to a different section of the script file based on which key the user presses. Possible script file keywords are: Esc (escape key) Enter (enter or return key) Space (space bar) BackSp (backspace key) Tab (tab key) PageUp (PgUp key) PageDn (PgDn key) F1 F2 F3 F4 F5 (function keys) F6 F7 F8 F9 F10 (function keys) WARMBOOT Command ==================== What it does....initiates a "warm" reboot of the user's computer. See also........ColdBoot Usage...........WarmBoot Example.........WarmBoot A "warm" reboot is the same as if the user had pressed the Ctrl+Alt+Del keys. For products such as device drivers, this command can allow you to install your product automatically without having to instruct the user to reboot their computer. It is probably a good idea to allow the user to decide to reboot, however. If you want to do a memory check during the reboot, see the ColdBoot command. Page 19 G E T T I N G K E Y B O A R D I N P U T F R O M T H E U S E R Creating an INPUT section ============================= This section allows you to get string input from your user. This is useful for verifying the destination drive or directory with your user, for example. The format of the input section follows... INPUT StartRow = window+9 StartColumn =window+30 Action =Enter, Esc TextColor =White on Blue Default =$BOOTDRIVEDEMO Width =15 ENDINPUT ACTION Command ================== What it does....specifies what keys the user may press during data entry. Usage...........Action =<key keyword>, <key keyword>, etc... Example.........Action =ESC, F1 Other than the standard insert, delete, and arrow movement commands, INSTALL needs to know what other keys you want to allow the user to press. When you define extra keys with this command, the jump command may be used to branch to different sections of the script depending on which key the user presses. This could be useful for providing on-line help during data entry when the user presses F1, for example. See our GOODSOFT script for a real example. DEFAULT Command =================== What it does....the default text string for an Input section. Usage...........Default =<text string> Example.........Default =C:\DEMO If this command is used, INSTALL will display the specified string as the initial string in the data entry field. The user may simply press the ENTER key to accept the default choice. Or, the user may modify the default string. Use this command for presenting the user with your preferred choice. If this command is not used in the Input section, INSTALL will simply display a blank field. Page 20 STARTCOLUMN Command ======================= What it does....specifies the column on which to start the left edge of the window. See also........StartRow Usage...........StartColumn =<col #> or <Center> or <Window + <col #>> Examples........StartColumn =5 StartColumn =Center StartColumn =Window+1 The first example is used when you want to start the window on a specific column. The second example is a short-cut and tells the script generator to automatically center the window on the screen. The third example is useful for placing windows within another window. This example will start the new window on the previous window's StartColumn plus one more column. You can see how this will place the window within the previous window. See the GOODSOFT script for more examples. STARTROW Command ==================== What it does....specifies the row on which to start the top edge of the window. See also........StartColumn Usage...........StartRow =<row #> or <Center> or <Window + <row #>> Examples........StartRow =2 StartRow =Center StartRow =Window+2 The first example is used when you want to start the window on a specific row. The second example is a short-cut and tells the script generator to automatically center the window on the screen. The third example is useful for placing windows within another window. This example will start the new window on the previous window's StartRow plus two more rows. See the GOODSOFT script for more examples. TEXTCOLOR Command ===================== What it does....specifies input field foreground and background colors. Usage...........TextColor =[color] ON [color] Example.........StartRow =White on Blue This command determines what colors INSTALL uses for displaying the input field. Page 21 WIDTH Command ================= What it does....specifies the width of data entry for an Input section. Usage...........Width =<# of columns> Example.........Width =10 The width of the user's data entry will determine the maximum amount of characters the user may enter. For example, if you were asking the user for a filename, you would probably want to keep the width at 12, the DOS limit for filenames. Page 22 U S I N G S C R I P T F I L E V A R I A B L E S SCRIPT VARIABLES ==================== Script variables may be used in a script file in place or in conjunction with any command that uses a text string. When INSTALL is running, it will keep the variables updated on current operations such as the current directory, the user's boot disk, etc. This can be very useful for adding some "smarts" to your installation. Instead of asking the user to type in his/her boot drive letter, you could have INSTALL automatically provide a default response, for example. $AUTOEXECRESULT - The first line added to AUTOEXEC.BAT as a result of a ModifyAutoExec section. $BOOTDRIVE - The user's boot drive and path (i.e. "C:\"). $BUTTONRESULT - The result (as specified with the Result command) of the button selected by the user. $CONFIGRESULT - The first line added to CONFIG.SYS as a result of a ModifyConfig section. $CURRENTDIR - The current directory name/path. $CURRENTDRIVE - The current disk drive letter. $CURRENTPATH - The current disk drive and directory path. $INPUTRESULT - Result of an input section. $FINDRESULT - Drive letter of the most recent disk found with the FindDisk command. Page 23 U S I N G B U T T O N S Creating a BUTTONS Section ============================== Buttons provide another means of getting input from the user. Rather than having the user type in information, you can present him/her with several choices. The user then just selects a choice. We like to use buttons to get such information as "install package A" or "package B"? Defining a button is much like defining a window, as follows... BUTTONS RowMargin =1 ColumnMargin =4 StartRow =window+7 StartCol =window+9 ButtonOnColor =White on Blue ButtonOffColor =Black on Gray Travel =Horizontal Distance =8 Message =A: Result =A:\ GoButton =Drive A Message =B: Result =B:\ GoButton =Drive B ENDBUTTONS BUTTONOFFCOLOR Command ========================== What it does...Foreground and background color of a button when it is not highlighted. See also.......ButtonOnColor Usage..........ButtonOffColor =<color> on <color> Example........ButtonOffColor =Gray on Blue This command determines how a button will look when it is not currently highlighted by the user. When a button is highlighted, the ButtonOnColor command determines how it will look. Run the sample installation for a real example. BUTTONONCOLOR Command ========================= What it does...Foreground and background color of a button when it is highlighted. See also.......ButtonOffColor Usage..........ButtonOnColor =<color> on <color> Example........ButtonOnColor =White on Blue Page 24 This command determines how a button will look when it is currently highlighted by the user. When a button is highlighted and the user presses the ENTER key, the user is "choosing" the highlighted button. COLUMNMARGIN Command ======================== What it does....leaves X number of columns as space between a button border and the interior text. See also........RowMargin Usage...........ColumnMargin =<number of columns> Examples........ColumnMargin =7 This command is useful for keeping the button text from being crammed up against the border of the button. ROWMARGIN Command ===================== What it does....leaves X number of rows as space between a button border and the interior text. See also........ColumnMargin Usage...........RowMargin =<number of rows> Example.........RowMargin =1 This command is useful for keeping the button text from being crammed up against the border of the button. DISTANCE Command ==================== What it does....tells INSTALL how much space to leave between buttons See also........Travel Usage...........Distance =<# of columns> or <# of rows> Example.........Distance =10 This command is interrelated with the Travel command. If you specify Vertical travel, INSTALL assumes that the Distance you give is in rows. Conversely, Horizontal travel means that the distance between buttons will be in columns. In either case, this is the amount of space INSTALL puts between buttons when it displays them on-screen. Page 25 MESSAGE Command =================== What it does....defines the text displayed on a button. See also........Result Usage...........Message =<text message> Example.........Message =Choose me! The message of a button is what will be shown as a choice for the user. When the user actually chooses a button, the value specified with the Result command will be used by INSTALL. We did this to allow you to use more descriptive text for your buttons, while still getting the information you need from the user. For example... Message =Disk Drive A Result =A:\ Each time you use a Message command in a button section, you are creating a new button # that can have a corresponding Result command following it. RESULT Command ================== What it does....specifies the result of a button. See also........Message Usage...........Result =<text string> Examples........Result =A:\ Result =B:\ This command is used to determine what value will be returned by INSTALL when the user chooses a button. You may use the a string in your script that corresponds to which button is selected. The button result is returned by INSTALL in the $BUTTONRESULT script variable. You may use this variable anywhere you would use a normal text string. This command is optional. GOBUTTON Command ================== What it does....jumps to a procedure if the button is selected. Usage...........GoButton =<procedure name> Examples........GoButton =Quit This command is useful when you want to branch to a different dection of your script depending on which button your user selects. An example would be asking the user which package to install, and then JUMPing to the appropriate file copy section. The GoButton command should be used in the format shown in the Button section example. As shown in the example, the first GoButton command happens if the first button is selected, the second GoButton command happens if the second button is selected, and so on. This command is optional. Page 26 STARTCOLUMN Command ======================= What it does....specifies the column on which to start the left edge of the button. See also........StartRow Usage...........StartColumn =<col #> or <Center> or <Window + <col #>> Examples........StartColumn =5 StartColumn =Center StartColumn =Window+1 The first example is used when you want to start the button on a specific column. The second example is a short-cut and tells the script generator to automatically center the button on the screen. The third example is useful for placing buttons within another window. This example will start the button on the previous window's StartColumn plus one more column. You can see how this will place the button within the previous window. See the GOODSOFT script for a working example. Page 27 STARTROW Command ==================== What it does....specifies the row on which to start the top edge of the button. See also........StartColumn Usage...........StartRow =<row #> or <Center> or <Window + <row #>> Examples........StartRow =2 StartRow =Center StartRow =Window+2 The first example is used when you want to start the button on a specific row. The second example is a short-cut and tells the script generator to automatically center the button on the screen. The third example is useful for placing buttons within another window. This example will start the button on the previous window's StartRow plus two more rows. See the GOODSOFT script for more examples. TRAVEL Command ================== What it does....tells INSTALL what keys the user may press to move through the button choices. See also........Distance Usage...........Travel = <Horizontal> OR <Vertical> Examples........Travel =Horizontal Travel =Vertical This command is used by the script generator to determine what keys the user will be allowed to press to highlight the different button choices. For example, if you specify Vertical travel INSTALL assumes that the buttons are arranged vertically, and lets the user press the UP and DOWN arrow keys to choose. Alternatively, Horizontal travel indicates that the buttons are arranged horizontally and INSTALL lets the user press the left and right arrow keys. There is no default, so you must use this command. Page 28 C O P Y I N G F I L E S Creating a STARTCOPY Section ================================ The StartCopy command is used to begin a file copying section of a script file. This section is necessary before you use the DiskLabel, SourceDisk, DestDisk, DestDirectory, etc. copying commands. Every StartCopy command must eventually be followed by an EndCopy command, as in the example below... STARTCOPY DiskLabel =SAMPLE SourceDisk =$BUTTONRESULT DestDisk =$BOOTDRIVE DestDirecoty =DEMO File =DEMO.EXE File =DEMO.DAT ENDCOPY Note that there are several tricks to keep in mind when using the file copying script commands. One: each copy section can only copy a maximum of 40 files at one time. If you need to copy more, just start another copy section. Two: If you have multiple distribution disks, just prompt the user to insert the next disk and then start a new copy section for that disk. DESTPATH Command ==================== What it does....specifies which disk and directory to copy files to. See also........DiskLabel, SourceDisk, SourcePath, CopyFile, StatusRow, StatusColumn, StatusLineFG, StatusLineBG Usage...........DestPath =<drive letter and directory name> Example.........DestPath =C:\DEMO This command will tell INSTALL where to copy your files to. If the destination disk does not have a directory name as specified, INSTALL will create a new directory. You may have only one directory level specified with the DestDirectory command, but copying files to a multiple directory structure is easy - just use more copy sections. (A script example is included with the full Universal INSTALL package). DISKLABEL Command ===================== What it does....checks for the expected disk during the file copying process. Usage...........DiskLabel =<DOS volume ID> Examples........DiskLabel =DEMODISK Page 29 DiskLabel is used to make sure that the disk the user has inserted into the disk drive is the disk that contains the files you are about to copy. Think of this as "verifying" that the correct distribution disk has been inserted. This command is especially useful if the user has multiple distribution disks to choose from. If INSTALL does not find a match between the disk the user has inserted and the disk specified by this command, an error message will be displayed and INSTALL will instruct the user to "try again" or quit the installation process. - This command is not required, but is recommended to avoid confusion for the user during multiple disk installations. - A volume ID consists of up to 11 characters. - You can set the volume ID of your disks using the DOS LABEL command. COPYFILE Command ==================== What it does....specifies a file for INSTALL to copy. See also........DestDisk, DestDirectory, SourceDisk Usage...........CopyFile <path and name of file> Example.........CopyFile =FILE.EXE This command is used to tell INSTALL what files you want copied from your distribution disk. To copy a bunch of files, just use a CopyFile command for each one. Each file name and path should be no longer than 40 characters and you can only copy up to 40 files with each copy section. If you need to copy more than 40 files, just use another copy section. SOURCEDISK Command ====================== What it does....specifies where to locate files for a copy. See also........DiskLabel, DestDisk, DestDirectory, File, StatusRow, StatusColumn, StatusLineFG, StatusLineBG Usage...........SourceDisk =<Drive letter> Examples........SourceDisk =A:\ SourceDisk =$BUTTONRESULT SourceDisk is used to tell INSTALL where to find files that you want to copy somewhere. Note that instead of directly specifying the drive letter, you can use a script variable such as $BOOTDRIVE or $BUTTONRESULT. This is useful for allowing your user to choose the drive where your software disks are located. Page 30 SOURCEPATH Command ====================== What it does....specifies where to locate files for a copy. See also........DiskLabel, SourceDisk Usage...........SourcePath =<directory\directory\...> Examples........SourcePath =DEMO\EXAMPLES SourcePath =DEMO SourcePath is used to tell INSTALL where to find files that you want to copy somewhere. Use this command along with the SourceDisk command to tell INSTALL where to find files on your distribution disk. STATUSLINEBG Command ======================== What it does....specifies the background color for a copying status message. See also........DiskLabel, SourceDisk, DestDisk, DestDirectory, StatusRow, StatusColumn, StatusLineFG, File Usage...........StatusLineBG =<Blue, Gray, White, etc...> Example.........StatusLineBG =Blue Please see the StatusLineFG command for a more detailed description. STATUSLINEFG Command ======================== What it does....specifies the foreground color for a copying status message. See also........DiskLabel, SourceDisk, DestDisk, DestDirectory, EndCopy, StatusRow, StatusColumn, StatusLineBG, File Usage...........StatusLineFG =<Blue, Gray, White, etc...> Example.........StatusLineFG =White This command will determine the forground color of a copying status message that INSTALL displays. Specifying the colors of the message allow you to match any existing windows or text you have on the screen. STATUSCOLUMN Command ======================== What it does....column (or X) coordinate for a "now copying file: " type of status message. See also........DiskLabel, SourceDisk, DestDisk, DestDirectory, StatusRow, StatusLineFG, StatusLineBG, File Usage...........StatusColumn =<Screen column number> Example.........StatusRolumn =10 Please see the StatusRow command for a more detailed description. Page 31 STATUSROW Command ===================== What it does....row (or Y) coordinate for a "now copying file: " type of status message. See also........DiskLabel, SourceDisk, DestDisk, StatusColumn, StatusLineFG, StatusLineBG, File Usage...........StatusRow =<Screen row number> Example.........StatusRow =10 The StatusRow command, when used with the other StatusXXX commands, allows you to keep your user up to date about which file is currently being copied. INSTALL needs to know the row and column coordinate, as well as the colors you wish to use for the message. The message itself consists of the filename (with extension) in capital letters. You should plan for a maximum of 40 characters to be displayed if you use the copy status message feature. Page 32 M O D I F Y I N G C O N F I G . S Y S Creating a MODIFYCONFIG Section =================================== This section tells INSTALL how you want to change the user's CONFIG.SYS file. You can add a line to the file, REM (comment out) a line, and add a line with CPU-dependent parameters. The format for this section follows... MODIFYCONFIG SaveOriginal =config.old AddLine =REM device=sample.sys FindString =device Parameters 8088 = /PC-XT 80286 = /PC-AT 80386 = /80386 80486 = /80486 EndParameters ENDCONFIG ADDLINE Command =================== What it does....adds a line to the user's CONFIG.SYS or AUTOEXEC.BAT file. Usage...........AddLine =<text string> Example.........AddLine =echo Have a nice day! This command will add a line to the CONFIG.SYS file when it is located in a ModifyConfig script section, or add a line to the AUTOEXEC.BAT file when placed within a ModifyAutoExec section. For CONFIG.SYS: The point in the file where the new line is inserted depends on if you use a FindString command. See the FindString command for more information. For AUTOEXEC.BAT: AddLine always adds lines to the end of the file. - Note that you may use more than one AddLine command to add multiple lines to the user's file. FINDSTRING Command ====================== What it does....inserts an AddLine line at the point in the CONFIG.SYS file where the specified string is found. Usage...........FindString =<text string> Example.........FindString =device Page 33 In the example above, FindString will search the user's CONFIG.SYS file for any lines containing "device". If a match is found, lines added with the AddLine command will be inserted at the point where a FindString match was made. This is useful for ensuring that your product is the first device driver in the file, as our example would do. If no match is found, INSTALL will insert all lin+es at the end of the file. See our GOODSOFT script for a real example. PARAMETERS Command ====================== What it does....lets you add product command line switches to any added CONFIG.SYS lines based on the user's CPU type. Usage...........See below Example.........See Below The format for the Parameters command follows... PARAMETERS 8088 = /PC-XT 80286 = /PC-AT 80386 = /80386 80486 = /80486 ENDPARAMETERS This example tells INSTALL to run a system check and determine what type of CPU the user's computer has. If the user has an 8088/86 CPU, INSTALL will append "/PC-XT" to any lines added to CONFIG.SYS with the AddLine command. If the user has a '286 type of CPU, INSTALL will append "/PC-AT" to any AddLines (and so on). This feature is primarily useful for device driver products, where the device driver needs software switches to run at different speeds or with different features. REMARKSTRING Command ======================== What it does...."comments out" a line in CONFIG.SYS. Usage...........RemarkString =<search text> Example.........RemarkString =Old product When used in a ModifyConfig section, this command allows you to disable lines in the user's CONFIG.SYS that might conflict with your product without actually removing the lines. Examples might be REMarking a "Files=10" statement and adding a "Files=20" line, or disabling a reference to an older version of your product. Page 34 SAVEORIGINAL Command ======================== What it does....allows you to save a copy of the user's CONFIG.SYS or AUTOEXEC.BAT file before you make any modifications. Usage...........SaveOriginal =<file name> Example.........SaveOriginal =CONFIG.OLD This command tells INSTALL to make a copy of the user's CONFIG.SYS or AUTOEXEC.BAT file before any changes are made. This can help you assure the customer that any changes to their setup can be reversed. Page 35 M O D I F Y I N G A U T O E X E C . B A T Creating a MODIFYAUTOEXEC Section ===================================== This section tells INSTALL how you want to modify the user's AUTOEXEC.BAT file. The format for this section is as follows... MODIFYAUTOEXEC SaveOriginal =autoexec.old AddLine =echo Have a nice day from The GoodSoft Co! AddPath =c:\demo ENDAUTOEXEC ADDLINE Command =================== What it does....adds a line to the user's CONFIG.SYS or AUTOEXEC.BAT file. Usage...........AddLine =<text string> Example.........AddLine =echo Have a nice day! This command will add a line to the CONFIG.SYS file when it is located in a ModifyConfig script section, or add a line to the AUTOEXEC.BAT file when placed within a ModifyAutoExec section. For CONFIG.SYS: The point in the file where the new line is inserted depends on if you use a FindString command. See the FindString command for more information. For AUTOEXEC.BAT: AddLine always adds lines to the end of the file. - Note that you may use more than one AddLine command to add multiple lines to the user's file. ADDPATH Command =================== What it does....updates, modifies, or adds to the user's PATH statement in AUTOEXEC.BAT. Usage...........AddPath =<text string> Example.........AddPath =c:\demo When you use this command, INSTALL will search the existing path for a similar or matching path in AUTOEXEC.BAT. A "similar" path is one where only the drive letter is different. A matching path is the exact same string as you specified. If a similar path is found, INSTALL will update the drive letter. If a matching path is found, INSTALL will not make any modifications. If NO path or no matching path is found, INSTALL will add a PATH statement or add your path to the end of the existing PATH statement. Page 36 SAVEORIGINAL Command ======================== What it does....allows you to save a copy of the user's CONFIG.SYS or AUTOEXEC.BAT file before you make any modifications. Usage...........SaveOriginal =<file name> Example.........SaveOriginal =CONFIG.OLD SaveOriginal =AUTOEXEC.OLD This command tells INSTALL to make a copy of the user's CONFIG.SYS or AUTOEXEC.BAT file before any changes are made. This can help you assure the customer that any changes to their setup can be reversed. Page 37 U T I L I Z I N G T H E U N - I N S T A L L F E A T U R E How "un-install" works ========================== Universal INSTALL has a useful feature that many end-users really appreciate: the ability to "undo" an installation. During an installation, INSTALL can be instructed to maintain an installation "log file". This file contains all the crucial operations performed by INSTALL, such as creating directories, copying files, and modifying CONFIG/AUTOEXEC. Once this log file is created, the installation process may be "undone" by the user through running the REMOVE.EXE utility. This program simply reads the installation log file and reverses the process. Creating an installation log file ===================================== Use the KEEPLOGFILE command (described under General System Commands) to instruct INSTALL to maintain a log of the installation. For example, the following command would tell INSTALL to create an INSTALL.LOG file in the current directory... KeepLogFile =INSTALL.LOG Using the REMOVE Utility ============================ To "undo" an install, all your user has to do is type the following: REMOVE [install log filename] to match KeepLogFile example above: REMOVE install.log "REMOVE" is just what we called the program. You are free to rename the file anything you want. If you do rename the file, you'll probably want to rename REMOVE's data file as well. This can be accomplished via programs that let you edit an .EXE file, such as The Norton Utilities. Simply search for "REMOVE .DAT" and replace the text. NOTE: Editing .EXE files is NOT recommended, and The GoodSoft Co. assumes absolutely NO responsibility for any consequences of doing this. REMOVE Utility Data File (REMOVE.DAT) ========================================= The remove utility's on-screen messages may be customized through the program's data file, REMOVE.DAT. This file contains the text messages REMOVE displays before beginning the un-install process. To customize REMOVE, simply edit this file to your liking. Note: Only the first 11 lines of text contained in this file are used by REMOVE, and text lines will be truncated to 78 characters, so plan accordingly! Page 38 Tips on Using REMOVE ========================= - REMOVE will only "undo" something that was done in the log file. This means that if your users have created new files in your directories, these files will NOT be removed. If there are still files in a directory that are not yours, the directory will not be removed either. We do recommend that you warn your users that any configuration changes made to your software (e.g. color changes, etc.) will, of course, be lost. - Be sure to specify in your documentation what filename the user needs to specify when running REMOVE. Also, if the file is created in a place other than the install disk, you might want to tell the user how to look for the file. - Keep in mind that if you are using an installation log file, INSTALL will be accessing this file throughout the installation. For installs spanning several disks, you will not want INSTALL to create the log file on the first disk, for example! If you do this, and INSTALL is unable to update the file when it needs to, the program will stop trying. While you'll end up with only a partial log file, at least your user won't see a bunch of error messages. This outcome seemed to be the least obtrusive method during our testing with end-users. Page 39