Clipper Support Bulletin #2 Clipper 5.0 installation procedure Copyright (c) 1991, 1992 Nantucket Corporation. All rights reserved. Version: Clipper 5.0, revisions 1.00 - 1.03 Date: 27th September, 1990 Revised: 21st May, 1992 Status: Active ================================================================================ This Support Bulletin covers the following topics: 1. The Clipper 5.0 Install Program 2. Installation Pitfalls 2.1 Missing files due to insufficient disk space on the target drive. 2.2 Insufficient memory to build utilities ("memory overbooked" messages). 2.3 System hangs while building utilities. 2.4 Problems installing in DOS 4.x environment. 2.5 Other Problems 3. Manual Installation 3.1 Default Directory Structure 3.2 How to Install a Single Archive File 3.3 Modifying your Environment Variables 3.4 Building Utilities Manually 3.5 Manually Creating the Base Prelinked Library. 3.6 Installing the Entire System Manually For information about the contents of the distribution disks and archive files, please refer to Clipper Support Bulletin #1 (S50001.TXT). ================================================================================ 1. The Clipper 5.0 Install Program Clipper 5.0 distribution files are supplied in the form of "self- expanding" archive files. Clipper 5.0 includes an automated install program (INSTALL.EXE) that expands the archive files into specified target locations, and optionally builds utilities and a base prelinked library (.PLL). INSTALL is driven by an installation script (INSTALL.INS) which describes the location of the archive files on the distribution disks and the default locations of the distribution files on the target drive. The basic sequence of operations for INSTALL is as follows: 1. Ask user for information regarding paths and installation options. 2. Create subdirectories on the target drive. 3. Extract distribution files from the archive files on the distribution disks. 4. Build base prelinked library (if requested). 5. Build utilities (if requested). 6. Create AUTOEXEC.CHG and CONFIG.CHG files that detail necessary changes to your AUTOEXEC.BAT and CONFIG.SYS files. INSTALL is designed so that it can be rerun to complete an interrupted installation or to install optional files at a later time. If problems occur during installation, INSTALL can be rerun to complete the installation after the problem has been resolved. When rerunning INSTALL, select the desired installation options as if you were installing for the first time. INSTALL will check the contents of the specified target drive and directory against the distribution disks and transfer or build any necessary files. ================================================================================ 2. Installation Pitfalls The following are some common problems that can occur during installation. ---------------------------------------------------------------------------- 2.1 Missing files due to insufficient disk space on the target drive. SOLUTION: Make more space available on the target drive and then rerun the install program. ---------------------------------------------------------------------------- 2.2 Insufficient memory to build utilities ("memory overbooked" messages). EXPLANATION: To build the utilities, INSTALL requires approximately 523K of free memory. SOLUTION: Make additional memory available by rebooting your computer without memory resident utilities or network software, then rerun INSTALL. ALTERNATE SOLUTION: Build the utility programs manually (see Building Utilities Manually below). ---------------------------------------------------------------------------- 2.3 System hangs while building utilities. EXPLANATION: INSTALL generates a batch file in order to build the utilities. This batch file includes a SET PATH command to add some necessary directories to the PATH environment variable. Under some versions of DOS, attempting to increase the length of the PATH environment variable beyond 128 bytes causes COMMAND.COM to hang. SOLUTION: Remove unnecessary entries from PATH and rerun INSTALL. ALTERNATE SOLUTION: Build the utility programs manually (see Building Utilities Manually below). ---------------------------------------------------------------------------- 2.4 Problems installing in DOS 4.x environment. EXPLANATION: When creating the batch files to build utilities, INSTALL may generate a SET PATH command which ends with a semicolon. Under DOS 4.x this causes COMMAND.COM to issue an error message. ALTERNATE SOLUTION: Build the utility programs manually (see Building Utilities Manually below). ---------------------------------------------------------------------------- 2.5 Other Problems If you experience an installation problem that is not listed here, please contact Nantucket Technical Support at (310) 390-7923, or via Compuserve NANFORUM (leave message for SYSOP). If possible, please include the following information about your environment: machine make and model, DOS version, memory available during installation, any memory-resident software you are using. ================================================================================ 3. Manual Installation As noted above, Clipper 5.0 distribution files are supplied in the form of "self-expanding" archive files. The archive files are executable (.EXE) files. Each archive file, when executed, creates one or more of the Clipper 5.0 distribution files. The archives are executed automatically by INSTALL. They may also be executed directly, allowing all or any part of Clipper 5.0 to be installed manually. ---------------------------------------------------------------------------- 3.1 Default Directory Structure Clipper 5.0 is designed to be installed in a directory structure (i.e. a directory and a series of subdirectories) on a hard disk. The distribution files are grouped into archives in such a way that each archive is associated with a particular subdirectory of the default directory structure. Shown below is the default directory structure and its relation to the archive files. For more information about the directory structure, refer to the "Getting Started Guide." For information about the contents of the distribution disks and the archive files, refer to Clipper Support Bulletin #1 (S50001.TXT). \CLIPPER5 \BIN containing files from archive file BIN.EXE \INCLUDE containing files from archive file INCLUDE.EXE \LIB containing files from archive files LIB1.EXE and LIB2.EXE \PLL containing file BASE50.LNK from archive file LIB2.EXE \SOURCE \DBU containing files from archive file DBU.EXE \PE containing files from archive file PE.EXE \RL containing files from archive file RL.EXE \SAMPLE containing files from archive file SAMPLE.EXE \NG containing files from archive files NG1.EXE and NG2.EXE ---------------------------------------------------------------------------- 3.2 How to Install a Single Archive File 1. Determine which archive file is required based on which part of Clipper 5.0 is to be installed (refer to Clipper Support Bulletin #1, S50001.TXT). 2. Place the appropriate distribution disk in a floppy drive. 3. Choose the target drive and directory to contain the distribution files. 4. If necessary, create the target directory on the target drive. 5. Select the target drive as the current drive and change directory to the target directory. 6. Execute the appropriate archive file from the floppy. The archive file will create the appropriate distribution files in the current drive and directory. For example, the steps for manually installing the DBU distribution files are as follows: 1. The archive file required is DBU.EXE. 2. Place the appropriate distribution disk in floppy drive A. For the 5-1/4 inch distribution disks, DBU.EXE is on disk #4. For the 3-1/2 inch distribution disks, DBU.EXE is on disk #2. 3. Choose the target drive and directory to contain the distribution files. Assuming that drive C is the target drive and that you wish to use the default directory structure, the DBU files should be installed in C:\CLIPPER5\SOURCE\DBU. 4. If necessary, create the target directory on the target drive. If the directory C:\CLIPPER5\SOURCE\DBU does not exist, create the missing directory or directories. For example: c: md \clipper5 md \clipper5\source md \clipper5\source\dbu (Note that the "md" commands will fail if the specified directory already exists--this is normal.) 5. Select the target drive as the current drive and change directory to the target directory. For example: c: cd \clipper5\source\dbu 6. Execute the appropriate archive file from the floppy. For example: a:dbu ---------------------------------------------------------------------------- 3.3 Modifying your Environment Variables Certain environment (SET command) variables should be set for Clipper 5.0. Generally, this is accomplished by modifying your AUTOEXEC.BAT file to automatically set the variables each time you boot your computer. The required settings are as follows: The PATH variable should include the directory where Clipper 5.0 executable files reside (example: C:\CLIPPER5\BIN). The LIB variable should include the directory where Clipper 5.0 library files reside (example: C:\CLIPPER5\LIB). The INCLUDE variable should include the directory where Clipper 5.0 include files reside (example: C:\CLIPPER5\INCLUDE). For example (placed at the end of AUTOEXEC.BAT): set path=c:\clipper5\bin;%path% set lib=c:\clipper5\lib set include=c:\clipper5\include You may also wish to set other environment variables. For more information, refer to the "Getting Started Guide" and the "Programming and Utilities Guide". For general information about the DOS environment and setting environment variables, refer to your DOS manual. ---------------------------------------------------------------------------- 3.4 Building Utilities Manually Certain Clipper 5.0 utility programs (DBU, PE, RL) are supplied in source code form. These utilities must be compiled and linked before they can be used. INSTALL will optionally install and build these utilities automatically. If you elected not to install or build the utilities, or if INSTALL failed to build them successfully, they may be built manually. IMPORTANT: before the utilities can be successfully built, the following requirements must be met: 1. The Clipper 5.0 executables, libraries, and include files (the files in C:\CLIPPER5\BIN, C:\CLIPPER5\LIB, and C:\CLIPPER5\INCLUDE, respectively) must be properly installed. 2. Your environment variables must be set correctly (see above). 3. The source files for the desired utility must be available. If the source files have not been transferred from the distribution disks, you can retrieve them using the INSTALL program or the manual procedure described above. Each utility includes a make file (a .RMK file used by RMAKE) which will compile and link the utility. To make a utility, simply go to the appropriate directory and execute RMAKE on the script (.RMK) file. For example, the following commands will build DBU: c: cd \clipper5\source\dbu rmake dbu NOTE: this example will create the DBU executable file (DBU.EXE) in the current directory (C:\CLIPPER5\SOURCE\DBU). You should copy the executable file into the \CLIPPER5\BIN directory so that it is accessible via SET PATH. ---------------------------------------------------------------------------- 3.5 Manually Creating the Base Prelinked Library. Prelinked libraries (.PLL files) allow faster linking and code sharing among different applications. The distribution disks contain a linker script file (BASE50.LNK) which will create a general purpose .PLL called BASE50.PLL (for information on building and using .PLL's, refer to the "Programming and Utilities Guide"). BASE50.PLL is optionally created by INSTALL during installation. If you elected not to create BASE50.PLL, or if INSTALL did not create it successfully, you can create it manually. IMPORTANT: before BASE50.PLL can be successfully created, the following requirements must be met: 1. The Clipper 5.0 executables and libraries (the files in C:\CLIPPER5\BIN and C:\CLIPPER5\LIB, respectively) must be properly installed. 2. Your environment variables must be set correctly (see above). 3. The PLL directory (\CLIPPER5\PLL) must have been created and the BASE50.LNK file must reside in it. To build the BASE50.PLL, change directory to the PLL directory and run .RTLink on the supplied script file (BASE50.LNK). For example: c: cd \clipper5\pll rtlink @base50 ---------------------------------------------------------------------------- 3.6 Installing the Entire System Manually If necesary, the entire Clipper 5.0 system can be installed manually using the techniques described above. To do this, manually install each archive file from the distribution disks (see How to Install a Single Archive File above). Then modify your environment variables (Modifying your Environment Variables above). Finally, if desired, the utilities and base prelinked library can be created. * * *