Does this site look plain?

This site uses advanced css techniques

Evolution Logo

When iSystems releases new Evolution software, the SYSTEM database must be restored into the database servers, and though there are tools that do this now, we've found that we can perform this with essentially one click by integrating the process into Windows Explorer.

Table of Contents

For instance, an installation with two database servers (LIVE for production and TEST for testing), would associate these two reload processes on the right-click menu as:

[right-click properties]

This arrangement takes just a few minutes to set up, and it makes it much easier for even untrained staff to perform an Evolution update safely and reliably.

Adding Firebird to the system command-search path

Our program uses the gbak command to perform the heavy lifting, and this is part of the Firebird database installation. In order for our program to work, the gbak command must be in the system PATH.

First, let's find out if it's already in the PATH, obviating these steps. Click Start, then Run, then cmd plus RETURN. This opens a traditional command window. Type gbak, and see if the command is found or not.

command not found: must update PATH
C> gbak
'gbak' is not recognized as an internal or external command,
operable program or batch file.
command is found, no need to update PATH
C> gbak
gbak: ERROR: requires both input and output filenames
gbak: Exiting before completion due to errors

NOTE: Even though both of them look like error messages, the second is a usage message from gbak itself, so the command has been located properly.

If the command is not found, the system %PATH% must be updated so gbak can be found by our script. This is done from the desktop with these steps:

Installation of clickrestore

The batch file - clickrestore.cmd -- is very simple: its purpose is to run a database operation from the SYSTEM.gbk file on the Windows machine and restore it across the network to the target Linux machine's SYSTEM.gdb file. Though there is also housekeeping and error checking code, the heart of this program is: 

gbak -rep -user EUSER -pas password -page_size 8192 SYSTEM.gbk computer:/db/evolution/SYSTEM.gdb

clickrestore.cmd should be installed at a fixed place (we usually park it in the c:\bin\ directory), because it will be referred to later by name in the File Association work that follows.

The file itself is located here, and should be downloaded by right-clicking the link and performing Save As... to the hard drive (again, usually saved into C:\bin\

Once the file has been saved, use Notepad or other editor to add the proper Firebird EUSER password. 

...
set SOURCE=SYSTEM.gbk
set CREDS=-user EUSER -pas *SET-PASSWORD-HERE*      « set password

if "%TARGET%"=="" (
...

This is typically the same for all Evolution installations, but we're not going to publish that password on a public document on the internet. One can contact the author, the Evolution-Tech mailing list, or iSystems support for this password.

Making file associations

Windows Explorer supports "file associations", which allow an action to be associated with a file's extension. For instance, double-clicking a .doc file brings up Microsoft Word, and doing the same on an .xls file brings up Excel. Furthermore, those who have installed the WinZip program see evidence of this associations on many right-click property menus - we're going to do the same for .gbk.

There are two steps required here - create the association with .gbk, and then associate actions - but we have encapsulated these into a small .reg -- registry update -- file which can be saved to the same place as the associated clickrestore.cmd often C:\bin

Remember to Save As...!

Important - The file must be customized to reflect the name and number of local computers that might be updated -- a production system, certainly, and perhaps one for test -- and this can be done by editing the file in Notepad or other editor.

[.reg file contents]

Lines 6-7 provide the "live system" update, while lines 9-10 do the same thing for the test system - delete the "TEST" lines if not appropriate for your environment. Though the right-click menu action names can be anything you like, the computer names on the actual command lines must be correct.

Once this file has been modified, it should be executed by double-clicking the file's icon from Windows Explorer. It will ask Are you sure you want to add the information in setup-clickrestore.reg to the registry? - click "Yes".

Now, the file associations and action commands have been entered into the registry, and we're ready to go.

Running it

To actually restore a SYSTEM database, navigate with Windows Explorer to the folder that holds the SYSTEM.gbk file downloaded from iSystems. When found, right-click on the file and select Evolution: update LIVE or whichever other option is desired.

This will open a command window, and show the details of what's going to be restore: the source database (including directory), and the target machine and directory. If the parameters look correct, press RETURN, otherwise type control-C to abandon this process without performing an update:

[Clickrestore at work]

The process can take a minute or two - there is no progress indicator - and when finished, it invites you to press RETURN to close the window.

It's not possible to restore a SYSTEM database if it's in use, but thankfully gbak detects this for us: 

gbak: ERROR: could not drop database dblinux:/db/evolution/SYSTEM.gdb
    (database might be in use)
gbak: Exiting before completion due to errors

Should this happen, check that all Package Servers connected to that database server have exited completely and try again.

First published: 2005/01/02