ObjectStore Release 5 Windows VAR Kit
Chapter 4
SETUP.RUL Routines
This chapter provides overview and detailed information about the SETUP.RUL routines.
Overview of SETUP.50 (SETUP.RUL)
The paragraphs that follow describe each of the routines supplied in SETUP.50.
Two areas of that code (the main program, and the code that unzips files and updates the progress display) are complex. They are documented here in detail.
Main Program
The main program starts at the label start: following the keyword program. The code in the main program is somewhat complex because of the interactions between install and setup, and because it is serving as the main program for three different applications: install, setup, and uninstall.
The main program starts out with a call to the Initialize routine. Initialize performs a number of functions, such as loading DLLs, displaying bitmaps, and checking for a previous installation of ObjectStore. It also checks the command line arguments -install and -uninstall, which force those behaviors. After dealing with the possibility that ObjectStore might be running, the main program sets a RunningInstall flag, which is set to TRUE if no previous ObjectStore installation was detected or if the SETUP.EXE program was invoked with the -install command line argument.
Execution of the code starting at the Reinstall: is controlled by a number of Boolean variables:
If RunningInstall is set, execution proceeds directly to the installation welcome screen (the call to SdWelcome) and continues with the call to RunInstall. RunInstall returns a value indicating whether setup needs to be run, if the user selected Custom install. If the user selected Typical install, the AutoSetup flag is set if the DBMS server was installed and needs to be set up automatically.
The next block of code, starting with if (RunningSetup) then, takes different paths depending on the flag settings. The settings and their results are as follows:
After this block of code, and after the Terminate routine has been invoked, the code checks the BATCH_INSTALL flag that is set if a conflict was encountered when attempting to install Microsoft C++ run-time files. If so, the user can choose to reboot immediately or to reboot later.
Unzipping Files and Updating the Progress Display
The second complex section of code in SETUP.50 occurs in the routine DecompressFiles. This routine manages both decompressing (unzipping) files and updating the progress bar with percent complete and the name of the current file being decompressed.
DecompressFiles calls OS_GetInstallFlags, which returns a bit mask corresponding to the various types of files to be extracted. It then enters the outer loop and calls OS_GetZipFile, which returns the name of each available zip file, along with another mask corresponding to the types of files contained in that zip file. If there is a match between the two masks, DecompressFiles then calls OS_BuildUnzipList to initialize the list of files to be extracted from the current zip file, and enters an inner loop.
The inner loop processes one file at a time. It calls OS_GetNextUnzip to get the name and size of the next file to be decompressed. It then updates the progress display with the name of the file being unzipped. Note that the progress bar is not updated until the next time through the loop. This means that, at any given time, the display includes the name of the file being decompressed and the percent complete up to, but not including, that file. After the display is updated, the size of the current file is added to TotalCopied and the file is decompressed.
(TotalCopied * 100) / TotalSpace
TotalSpace is calculated in the Components routine and is based on the licensing and installation options.
SETUP.RUL Descriptions
The paragraphs that follow describe the SETUP.RUL routines.
function CheckOStoreRunning ()
Returns TRUE if it appears thatObjectStore is currently running, FALSE otherwise.
function CheckUpgrade ()
Determines if the installation is an upgrade and, if so, queries the user about checkpointing the Server. Returns TRUE if the installation should continue, FALSE if the installation should be terminated.
function Components ()
Builds and displays the component options dialog and sets flags, and space requirements, based on results. Note that the component options dialog is more complex than most since the options presented to the user depend on the licensing option selected.
function ConfirmInstall ()
Generates and displays the installation confirmation dialog, customized by all the user's selections. Returns either NEXT or BACK depending on the user's button selection.
function CopyFiles (szInstallFrom)
Calls various routines to copy individual files. Supplies estimated file size for each file being copied. This function deals with files (such as those used by the installation) that are distributed outside the zip files.
function CopyOneFile (szFile, nFileSize)
Copies a single nonzipped file while updating the progress display.
function CreateOSProgramFolder ()
Creates and/or updates a program manager folder for ObjectStore.
function CreateRegAndDirs ()
Updates registry information under the registration key. See "Registration data in the registry", Chapter 2, ObjectStore Windows Installation System, for details.
function DecompressFiles (szInstallFrom)
Main routine for decompressing zip files.
function DeleteFiles ()
Called if the user selected the delete before installing option. It deletes all subdirectories under the selected OS_ROOTDIR. (It does not delete any files that might reside in the OS_ROOTDIR itself.)
function DeleteProgramFolderItem (szItemName)
Deletes a single item from a program manager folder.
function DeleteOSFolder ()
Deletes various ObjectStore items from a program manager folder and then attempts to delete the folder itself. This code is not completely effective as there is a conflict between InstallShield and Windows NT 4.0 (and, perhaps, Windows 95).
function DirExistsOptions (szExistingDir)
Displays a dialog asking the user what to do about a previously existing OS_ROOTDIR (overwrite, rename, or delete). Returns either NEXT or BACK, depending on the user's button selection.
function DisplayCopyFile (szFileStr, nPercent)
Updates the progress display status window for files being copied.
function DisplayUnzipFile (szDestLower, szTargetStr, nPercent)
Updates the progress display status window for files being unzipped.
function FixDisplayPath (szPathStr, szFixedStr)
Utility routine used when updating the progress display. This routine converts forward slashes to back slashes and, if necessary, shortens the string being displayed so it will fit in the space available.
function GetOSLibDir (WhichButton)
Displays a dialog querying the user for an OS_LIBDIR. This function is used when you are installing a client-only development system because the various ObjectStore databases needed during development are not available on the local system. Returns either NEXT or BACK, depending on the user's button selection.
function GetRenamePathname (oldpath, newPath, szSeqNum)
Constructs a pathname used in the DirExistsOptions routine as the target if the user chooses to rename an existing OS_ROOTDIR.
function HandleUnzipError (nErrorCode, szFileName)
Displays error messages for problems encountered during unzip operations, and allows the user to do one of the following:
function Initialize ()
Performs common initialization tasks.
function InitializeAutoStart ()
Displays a dialog asking if the user wants the Server to start automatically. Note that this routine merely sets the DoStartup flag, which is then used later in the OSFinish routine.
function InitializeInstall ()
Performs basic initialization steps needed specifically for install.
function InitializeLog ()
Displays a dialog asking whether the user wants to initialize or reinitialize the Server log. If so, invokes the OS_SETUP.DLL routine to do the initialization. Returns either NEXT or BACK, depending on the user's button selection.
function InstallationOptions ()
Displays the installation options (typical or custom) dialog. Returns either NEXT or BACK, depending on the user's button selection.
function InstallFiles ()
Performs all file installations, which include
function LicenseOptions ()
Displays the license options dialog and sets flags based on user selection. Returns either NEXT or BACK, depending on the user's button selection.
function OSFinish ()
Checks to see whether to start the Server automatically (if the log file is OK) and calls OS_UpdateStartup, which asks the user if the Server should be started immediately. Also displays a dialog allowing the user to choose to view the README.TXT file. Always returns NEXT.
function OSSetup (bAllowBack)
Steps through the setup dialogs: Server Parameters, RAWFS Setup, Server Initialization, and AutoStart Initialization.
function OSUninstall ()
Asks the user for uninstall confirmation and then performs the sequence of steps needed to remove ObjectStore from the system.
function ProcessInstall ()
Calls other routines to perform the basic steps required to actually install ObjectStore.
function ProcessSpecialFiles (szBinDir)
Attempts to install the ObjectStore MFC Wizard file in the Microsoft MSDevDir hierarchy.
function ProgramFolder (WhichButton)
Displays a dialog allowing the user to select a program manager folder name for ObjectStore use. Returns either NEXT or BACK, depending on the user's button selection.
function QueryShutdownServices ()
Queries the user about shutting down currently running ObjectStore services. Returns TRUE if services should be shut down.
function RecheckInitializeLog ()
Checks to see if the Server log file needs to be initialized or reinitialized. If so, queries the user and, if necessary, invokes OS_SETUP.DLL to initialize the log.
function Registration ()
Displays the registration information dialog. Returns either NEXT or BACK, depending on the user's button selection.
function RunInstall ()
This is the main routine for install. Steps through the install-specific dialogs (obtaining registration data, license options, installation options, component options, and so on), displays a confirmation dialog, invokes ProcessInstall to install files, and updates environment settings.
function RunSetupOptions ()
Displays the initial setup dialog, allowing the user to choose between Install, Reinstall, Setup, and Uninstall. In case of Setup and Uninstall, invokes the relevant routines immediately. Returns TRUE if the user selects the Reinstall option, FALSE otherwise.
function SetServerParams ()
Displays a dialog asking whether the user wants to set Server parameters. If so, invokes the OS_SETUP.DLL routine to display the Server parameters dialog. Returns either NEXT or BACK, depending on the user's button selection.
function SetupRawfs ()
Displays a dialog asking whether the user wants to set up or modify the RAWFS configuration. If so, invokes the OS_SETUP.DLL routine to display the RAWFS dialog. Returns either NEXT or BACK, depending on the user's button selection.
function SourcePath ()
Attempts to find a usable installation source directory. install is usually invoked from a directory that contains the complete ObjectStore installation environment. But the user can select reinstall after invoking setup.exe in the OS_ROOTDIR. In this case files such as the .zip files are not immediately available. SourcePath looks in the registration data to see if there is an original source path. If there is, it verifies that the Sourcepath exists and contains .zip files.
function Terminate ()
Performs common termination tasks.
function UninstallSpecialFiles ()
Attempts to delete the ObjectStore MFC Wizard file, which might have been installed in the Microsoft C++ hierarchy.
function UpdateMSVCRT (szInstallFrom, szFileName)
Attempts to update MSVCRT.DLL and does so in such a way that a failure to update can be corrected at a subsequent system reboot.
[previous] [next]
Copyright © 1998 Object Design, Inc. All rights
reserved.
Updated: 03/26/98 21:58:11