Understanding the Update Process

(This applies to the CrimeStar Professional Version)

When a new version of the CrimeStar software is released it may periodically require that the Crimestar database be modified to add new database fields, modify existing fields or update stored procedures that exist within the database. If the database is not properly updated the program will likely experience errors as it attempts to access data fields or call upon stored procedures that do not exist. This version synchronization between the program EXE file and the database structure is critical to ensure the proper operation of the program. Many people try to shortcut the install process by simply copying the new EXE or program files.

The CrimeStar installation program and the CrimeStar program itself have been designed to try to automate and simplify this update process whenever possible. However if the automatic update process fails it may be necessary for you to manually ensure that the database is properly updated. The following is a description of the automatic process and what steps you must take to do the process manually.

Before you start.

Your database contains your most valuable asset (your data) you should take all precautions to protect it from being lost. Your best protection is a tested, systematic and regular backup of your database to tape or some other electronic storage media. See: Creating a Good Backup Strategy for more information of backups.

The Install Process

The CrimeStar software installation process will by default install the program and other necessary support files into a directory named "Crimestar" on your computers c: drive. During the install process you can specify a drive or directory other than the default, however for the sake of this discussion and the examples contained herein we will assume that the program was installed in the default location.

When an update is installed the existing files will be updated with the new files from the installation. In the case of program or EXE files each file has an imbedded version number. The installation process will check the version number of the existing file and will ONLY install the new EXE program file if the version number of the existing EXE program file is less than what the installation process is about to install. For this reason, if you attempt to revert back to a previous version of the program you MUST manually delete the EXE program files first before running the install process of the previous version release.

In addition to program and support files, each full install or update several subdirectories or "folders" will be created in the crimestar directory. These subdirectories are as follows:

\crimestar\data\

\crimestar\tables\

When the \data subdirectory is created there are 11 critical files installed in it. These files are identified as follows:

\crimestar\data\crmstr00.dbc

\crimestar\data\crmstr00.dct

\crimestar\data\crmstr00.dcx

\crimestar\data\coremeta.dbf

\crimestar\data\coremeta.cdx

\crimestar\data\coremeta.fpt

\crimestar\data\dbcxreg.dbf

\crimestar\data\dbcxreg.cdx

\crimestar\data\dbcxreg.fpt

\crimestar\data\sdtmeta.dbf

\crimestar\data\sdtmeta.cdx

These files are the core database files that are used to define how the database should be built and what its structure should look like. They contain stored procedures and definitions for database tables and the data fields those tables will/should contain. THESE FILES CONTAIN NO USER DATA, they are simply the "blueprint" for the construction of the database. This is important because if they contained user data then your data would be overwritten each time you did an update.

When installing Crimestar for the first time these files are used to build the database tables that will contain your data. Likewise after an update these files will contain the information necessary for your database to be updated or remodeled to the new database structure. While these files contain the blueprint information, this information must be acted upon in order to change or update the database. The mere presence of these files does not in itself mean that your database has been updated. To act upon these files and use their information to update your database a small program has been provided named "VALIDATE". The validate program will use the information in the 11 core database files to build or update the database. In the

case of an update, this process occurs while your data is in the files. An error at this point can be devastating, which is why we recommend that you perform a backup prior to any program update.

Normally when you run Crimestar for the first time after having installed it or performing an update, the Crimestar program will run the validate program to build or remodel the database. When the validate program is attempting to build or remodel the database it is absolutely critical that nobody else be accessing the database in any way. The validate program MUST have exclusive access to the database at all times during the construction/remodel process. If another user runs the Crimestar program or any other program that opened the Crimestar database the validate program will not be able to properly modify the database.

How does CrimeStar know it has been updated?

It may not seem obvious at first but we had to come up with a way for the crimestar.exe program file to know that it was either new to a computer or that it was an update to a previous version. To do this we use a very simple strategy known as semaphore files. A semaphore file who mere existence is used as a switch to indicate that something needs to happen. In the case of CrimeStar software installations or updates the file is named 'start.zzz' and it is placed into the \Crimestar directory by the installation program. When the Crimestar program is run it looks to see if this file exists. If the file exists Crimestar knows that some kind of install or update has recently been performed. Likewise it know that whenever that happens it is necessary to check the database to make sure that the structure of that database is correct. Therefore the crimestar program runs the validate program so that the database will be built or updated. Upon completion of the update process crimestar will delete the start.zzz file so the next time the program is run it will not attempt to perform the validate program.

In a network environment the installation process is run on each workstation. As such the start.zzz file is placed on each workstation and each workstation would normally attempt to update the database, resulting in the update process being run over and over again. To prevent this each time the database is updated it is marked with the program version ID. So when the subsequent workstations where the start.zzz file exist, crimestar first looks at the version ID stamp in the database. If the version ID stamp matches the version of the program that is running a small message stating "No database update necessary" will be displayed and the validate process will be skipped.

If in a network environment the database files are located somewhere other than in the \crimestar\data directory of the local machine the Crimestar program will copy the 11 core database files from the \crimestar\data directory to the location of the database as specified by the DATAPATH= statement in the crimestar.ini file.

How to do this manually

In some cases the automatic process may not work properly. In these cases it may be necessary to manually update the database. To manually ensure that the database structure has been updated to the proper structure, perform an install of the latest version update to ensure that the 11 core database files are on your computer. If necessary, move or copy these 11 files to the directory or machine where your database resides replacing the files of the same name. Then rename or delete the \data directory on the local machine so that a duplicate database will not be created. Then run the Validate.exe program file, to process the 11-core database files and updates your database accordingly.