Upgrading to HireTrack Eclipse 2.3

This document contains all the information you should need in order to be able to smoothly upgrade to HireTrack Eclipse 2.3; you are strongly advised to read through it before you attempt to upgrade, rather than diving straight in and reading it as you go. For details of what's new and what's been fixed in Eclipse 2.3 please visit www.navigator.co.uk/Eclipse_23_updates.htm. 

Before you Start

1. The upgrade can be downloaded from THIS link. However, before trying to run it be aware that only customer's with a current support contract are entitled to the upgrade free of charge, and as such the upgrade programme is password protected. If you have not received an email notifying you of the password please request one from support@navigator.co.uk.

2. If you are upgrading from Eclipse 2.0 or Eclipse 2.1 then you will need the latest version of Borland Database Engine (BDE). Eclipse 2.2 already uses this engine, so most users will not need to do anything further. You can check the major version of Eclipse from the Help | About menu. Although the upgrade programme offers a link to where you can get the BDE upgrade you would be wise to get it in advance and run it on all workstations before upgrading to Eclipse 2.2. You can get the BDE upgrade from ftp://ftpc.borland.com/pub/bde/devsupport/updates/bde511en.exe 

3. One of the issues that the Eclipse 2.3 upgrade resolves is the cause of a data corruption in the table Item.db. This corruption results in duplicate values in a field that is expected to contain only unique values. If the upgrade programme detects such a corruption then it will not be able to proceed until this has been fixed, and the only way to do this is to send support@navigator.co.uk a zipped file of all the Item.* files (Item.db, Item.px, etc) that you will find in your Eclipse DATA folder (see Note 1 below). We will attempt to fix this problem within as short a time frame as possible (less than 24 hours), but you can prepare in advance for this by downloading this ftp://ftp.navigator.co.uk/pub/eclipse/ValidateItems.zip utility. Extract it to a suitable folder and run to check if there are any duplicate IDs in your Item.db table. If there are, then send us your files (zipped up) for us to fix. NOTE. if you run Eclipse against multiple companies/databases then you will need to check each one; also, be aware that this table stores all your barcode definitions so no one should attempt to add new barcodes to the system, nor scan out items while we have copies of the files. Once you have received the repaired files back from us you can proceed with the upgrade.

4. After a database upgrade some reports (print-outs) may fail if the structure of any of the tables that they use has changed in a significant way. We have gone to extreme lengths to try and avoid breaking any reports, but for the sake of adding new features to Eclipse it has sometimes been unavoidable to make changes that could cause some reports to fail. However, there is no need to panic: reports can easily be fixed up with Crystal Reports or completely replaced with Eclipse 2.3 compatible reports that we have prepared for this release. Full details of reporting issues are listed in the Reporting section of this document (including a list of known reports with problems, and tips on how to fix up reports), but the basic principle for dealing with any problems is this: if your failing report has been customised then you have no choice but to fix it up with Crystal Reports; if it hasn't then its a simple case of downloading it's replacement. If you are unable or unwilling to fix up a customised report then we can do it for you, but you should be aware that this is a chargeable service, regardless of your support contract with us, and a fixed price of £30.00 per report will be made. Finally, you need to be aware that when a faulty report generates an error in Eclipse is it not always obvious and can be 'silent' at the time of running the report; the error may then surface when  you close Eclipse or one of it's modules, giving the impression that a bug in the programme is present. A typical error you might get that was caused by a report that needs fixing up is an "Error in NTDLL.dll". 

Note: if you are worried that very important reports (Quotes, etc)  may fail and leave you vulnerable in a hectic and pressured working situation, you may want to take a copy of your database (see THIS article for tips on how to do this) and only upgrade that database and one workstation. You can then test and fix up your reports at your leisure and when you are happy with them perform the actual upgrade safe in the knowledge that you will be able to 'hit the ground running'. This single workstation could still run Eclipse 2.2 if required: just copy a renamed Eclipse.exe file (called it Eclipse 22.exe) from another workstation or copy it up before you upgrade and rename it.

Upgrading the Programme Files

5. The process is quite straight forward. Run the upgrade on each machine (see Note 2). The programme will search for Eclipse and any other updatable programmes; when it finds a file you will be prompted to replace it. Most of the time this will be the correct file but if, for example, you have more than one Eclipse.exe on your hard drive (maybe a backup or old copy) then the upgrade programme may find the wrong one. In this case browse to where you know the correct file is and then OK the prompt to overwrite (the normal path for Eclipse installations is C:\Program Files\Navigator Systems\Eclipse)

You will be asked if you want to install the Database Upgrade programme each time you upgrade a workstation. You only need to install this on one machine since it only needs to run once.

Tip: rather than copying the upgrade programme to each workstation you can put it  on your server and browse to it from each PC to run it. 

Upgrading the Data files

6. Before doing anything with the database upgrade check that no-one is running Eclipse anywhere on the network. You should then backup your Eclipse data using the same method that you normally use. If you don't run regular backups then at least take a copy of your Eclipse data. If you don't know where this is then run the Eclipse Multi-Company Utility (Start | Programs | Navigator Systems) and the path to your data is displayed on the first tab. 

7. It is also advisable to run a check on the database before you upgrade it; otherwise you might get 75% through only to have it fail because of a minor database corruption that you were not aware of. You can do this with the HireTrack Eclipse Database Repair programme. You can run this at its quickest setting by selecting 'Don't Rebuild' in its 'Rebuild Scope' options. Then, if it finds any problems just tackle each table one at a time by re-setting to 'Rebuild Corrupted tables' and selecting the offending table.

 8. Go to the  PC where you installed the Database Upgrade programme. You will find a shortcut to this in your Navigator Systems programme group (Start | Programs | Navigator Systems). Run it and follow the on screen instructions.

Note: Some users are running interim beta releases of Eclipse 2.21 and running the complete upgrade will overwrite some database values such as the new locked jobs facility. In such cases you need to click the second upgrade button on the main upgrade screen and you will be prompted at the end of the upgrade with options to reset certain fields or not.

9. Once the upgrade is completed the Database Repair Utility will be run automatically (if found) in order to fix up a corrupted auto-increment field in Item.db, which is something to be expected. If the Database Repair Utility is not found you will be prompted to do this manually.

Reports

The first thing we need to mention before going into any detail is that Eclipse 2.3 now makes it very easy to identify the name and location of each report that is launched from the print menu: this is displayed as a hint/tool-tip when you leave your mouse cursor over a report menu entry. These will always show a path to your REPORTS folder on your server (see Note 1).

9.   Replacing Standard Reports

i) Replacements for the A4 size E8 and HTE6 suites of reports (see Note 3) can be downloaded from this link ftp://ftp.navigator.co.uk/pub/report/Eclipse_23_Reporting.zip Extract the zip file, ensuring that folder names are preserved, to a suitable place and you will end up with a folder structure thus:

ii) Each of the master folders (E8 fixes & HTE6 fixes) contains a Reports folder. These contain All and Known folders, the latter containing reports that we know are likely to fail after the 2.3 upgrade. E8 fixes folder also contains some additional folder called SS Single Site reports) and users who are not running a multi-site version of Eclipse might need to seek out some reports here (e.g the Prep Sheet report for single site users, E8s_PrepA4.rpt). 

iii) The Letter Size reports have been redesigned to incorporate a more contemporary design and more color in the reports. The file can be found at:

ftp://ftp.navigator.co.uk/pub/report/Eclipse238Letter.zip

These reports also take advantage of the new 2.3 features. Each report is prefixed with “238_” which indicates their compatibility with version 2.3 and the 8 indicates that they have been designed using Crystal Reports Version 8.5. The suffix “Lt” indicates they are in letter (8.5” x 11”) format. Upon extracting the zip file you will find 3 folders:

 

 

which indicate the location on your server where these files should be placed. As indicated above, if you have custom reports installed, you will NOT want to install the files into the data folder as these files will overwrite your existing reports database. To install any of the new reports, extract them to the reports folder. Then, using the configuration utility on the reports tab, change the file name to the report you want. (example: E8_PrepUS becomes 238_PrepLt). The template reports, which insert into Word will need to added by using the configuration utility on the reports tab, and then select the “word processor configuration” tab.

 

10. Fixing Customised Reports

Essentially all that needs to be done with a report that fails after a database upgrade is a Database Verification. In 95% of cases this is sufficient; however, sometimes Crystal will break existing links between tables in the reports and this needs to be fixed up manually. Always take backup copies of your reports before you start modifying them.

i) Verifying the database in Crystal Reports requires that the report knows where the database tables that it uses are. The simplest way to do this is as follows. Open the report then save it to your Eclipse DATA folder (see Note 1) . From the Database Menu select Set Location, then in the popup form click the Same As Report button/option. This changes the search path of the currently selected table in the list of databases displayed in the Set Location Form to be wherever the report itself is located. If prompted to change the location of all other tables listed that originally had the same path as the first table in the list, choose YES. Now scroll through the other tables to check that only the table name is displayed and NOT a path to the table, e.g. Category.db, not H:\HireTackEclipse Database\Company1\Data\Category.db. If any tables listed do show a path then click the Same As Report button/option again for that table. Finally OK the Set Location Form and agree to set the locations of tables in sub-reports to the same place if prompted.

ii) Now Database Menu select Verify Database and agree to fix-up every table that has been found to have changed. If at any point you get an "IDAPI Error: No such table" message then the table referred to needs its database location setting correctly; do this then try Verify Database again. Now Save your report back to its original and correct location, namely the REPORTS or TEMPLATE folder (see Additional Notes1 below) and overwrite the existing one. You can delete all the reports in your DATA folder afterwards for the sake of good housekeeping if you want to.

iii) Broken Links. When you verify the database Crystal may break/lose the links between some tables in the report. The only table links we are aware of that might get broken are from tables that link to the Job_no field of the Eqlists.db table or Job_no field of the Crew.db table.  Crystal should prompt you if it breaks a link and requires you to manually correct them, but you will know if any table links have been broken because although the report may not generate an error when printing from Eclipse it may be blank or missing certain data areas. In such a case you will need to manually correct the problem using Crystal's Visual Linking Expert (see your Crystal Reports manual for use).  If you are not sure how unlinked tables should be linked (e.g. should you link Job.db => Eqlists.db or Eqlists.db =>Job.db) then open up the backup copy of your report and check the table links there. Be aware that links may have also been broken in any sub-reports and these will also need re-instating. 

NOTE: when more than one table is linked from from a single table (e.g Crew.db and Transport.db both link from Jobs.db in the Totals subreport of the Quick Quote report) then its is sometimes very important that the Options for a link (right click on it for the menu) are set correctly. For example, in order that summary functions add up correctly, the Option "When linking to to files from this file"  in older versions of the Quick Quote report need to be set to "Look up all of one, then all of the others". Check the link Options in your backup copy of your report to verify this.

11. Paying for Navigator Systems to fix broken reports

If you would like us to fix up your reports for you please prepare the following for us:

i) zip up all your files into a single attachment for sending to support@navigator.co.uk

ii) include in your zip file a document that tells us where each report prints from in Eclipse, and if possible, which version of Crystal Reports the report was customised with. Also let us know which version of Crystal Reports Runtime you currently use with Eclipse: you can find this out from the Help | Crystal Engine Version menu in Eclipse 2.3

iii) Include a purchase order number or credit card number in your email that sends the reports.

When we receive your reports we will let you know by return how long it will take to turn them around; we expect to be able to do this with 24 hours (subject to how many you send us). Finally, you will know your customised reports much better than we do and there is a small chance that there will still be a problem somewhere with it when we return it; for, example, maybe your reporting engineer included a tiny invisible sub-report that had a special job of performing advanced calculations: it might get overlooked in the fix-up, but in such a case we would endeavour to resolve this for you a.s.a.p.

12. Inserting reports in the in-built Word processor

Although the in-built word processor is deprecated in Eclipse 2.3 (MS Word is the preferred option), its is still available for users who have reports that have been customised for it. However, in order to work the Crystal Print engine must be Version 7 only. If you are running Version 6 then you will need to download this upgrade programme and run it on all workstations. NOTE: users with the the Version 8.5 print engine should NOT download and run this upgrade script.

13. Installing Warehouse Servicing reports

There is a new Servicing tab in the Warehouse Book and you might want to install the reports that you normally print from the Equipment Book. There is a quick way of doing this by running the Reports_Installer.exe programme that is in the Install  sub-folder of  suite of replacement reports (see 9i above). On running the programme browse to the appropriate IRT file that is also found in the same folder - note the Muti-Site/ Single-Site (MS/SS) distinction in the E8 versions of these installation files.

14. Eclipse Toolbox Reports

We are not aware of any malfunctions in the Eclipse Toolbox reports after the Eclipse 2.3 upgrade; however, for good measure we have upgraded them and they can be downloaded and replaced as per the instructions in section 9. above. You will see that in the folder listing there is a Toolbox fixes entry.

Auto-Update Server Service

One of the features listed in the www.navigator.co.uk/Eclipse_23_updates.htm document is the ability Eclipse and other programmes like the Configuration Utility to check for new versions and auto-update. By default Eclipse will check our FTP for site new versions, but this is slow(ish) and inefficient, especially for large scale installations. As an alternative you can toggle a setting in the Configuration Utility | Rules to tell all auto-updates to check a location on your server and have a special service programme supplied by us to have the job of checking the FTP site and downloading upgrades (once instead of for each workstation). You can download this programme from this link: ftp://ftp.navigator.co.uk/pub/eclipse/autoupdate_service.exe 

How to set up the Auto-Update Service

  1. Run Configuration Utility and in the Miscellaneous section of the Rules tab set the following: Eclipse Updates Notification to "Autoupdate from central location on your server"
  2. Set the New Version Location to a folder on the server that will run the auto-update service that all Eclipse users have access to. You may want to create a dedicated folder for this purpose.
  3. Fill in all the email details so that when an update is download the administrator for Eclipse can be notified. This is primarily designed for Terminal Server installations (see tips below) where Eclipse cannot auto-update if anyone else is running, but its your Eclipse administrator will probably want to know when everyone is going to get a new version anyway. who are not 
  4. Run the autoupdate_service.exe installation on your Eclipse server. You will be given the option to let it search for the directory used by the BDE Administrator's NETDIR path on all your workstations, or you can opt to specify this yourself if you already know where it is. You will then have to tell this installation where the downloaded file updates should be saved; this must be the same folder as specified in the Configuration Utility.

Tips on the Auto-Update Service

  1. The auto-update service does its first check for new files 1 minute after it is started. Thereafter it checks every 12 hours. So you have a back-door to scheduling when it checks by being able to start it at a particular time. See you Windows Help for information on how to start and stop services.
  2. Make sure you have set up the Configuration Book for this option before you start the service
  3. Terminal Server users. Since Eclipse cannot auto-update while anyone else is running Eclipse on the server the administrator needs to get everyone out of Eclipse before s/he manually opens the CAB files in the downloads folder and extracts them to the Eclipse folder. For this reason its probably best not to bother notifying users of a new version of the programme on start-up to in the Configuration Utility, so simply set Eclipse Updates Notification to No Notification of Updates.
  4. The Auto-Update Service itself does not "auto-update". If you are notified be email of any updates to this programme you will need to manual stop the service, upgrade and then re-start it in order to update it.
  5. The  Auto-Update Service can only run on Windows NT4, XP, 2000 or 2003.

Custom Utilities

Over the years some users have commissioned add-on utilities from to supplement Eclipse in special tasks and functions. We know of no good reason why any of these utilities should not continue to function correctly after the Eclipse 2.3 upgrade; however, if you do encounter a problem, and it is determined that a programme we have written for you needs updating to make it Eclipse 2.3 compatible, then this work will be chargeable. In such cases contact  support@navigator.co.uk and we will provide you will as estimate of costs.

Additional Notes

Note 1 -  you can find your Eclipse DATA, REPORTS and TEMPLATE folders by running the Eclipse Multi-company Utility from your Navigator Systems programme group. It will display a path to the master database folder on your server and the DATA, REPORTS and TEMPLATE folders are inside this.

Note 2 - Note: the Eclipse installer is built using Wise Solutions' InstallMaker. During installation, it may attempt to use a Windows DLL file called CTL3D32.DLL. If you have an incompatible version installed on your computer, it may report an error. You can safely ignore the error by clicking "OK" in the dialog that appears - the installation will then proceed properly. If you have Windows XP, Windows may ask you to insert your XP CD so that it can repair the problem. We recommend that you have your XP CD to hand for this eventuality.

Note 3 - If you have any E7 reports then you can replace then with are-named E8 equivalent.

Note 4 - You may find that you are unable to run more than one HireTrack Eclipse add-on program at once or unable to run Eclipse and any add-on 
(most common error message BDE security message $251E).
The following should fix this issue;

In the BDE Administrator, under Configuration/System/INIT set the following:

MAXBUFSIZE = 16384
MAXFILEHANDLES = 100

For W2K
SHAREDMEMLOCATION = 5BDE
SHAREDMEMSIZE = 4096

For XP
SHAREDMEMLOCATION = 6BDE
SHAREDMEMSIZE = 4096


These settings will improve memory management of the BDE under these operating systems and the speed of file access over a network


Navigator Systems Ltd, March 2005