Copyright: ©2002 SoftVelocity Inc.


Contents
TopSpeed Database Recovery Utility

The TopSpeed file system is designed to automatically repair most errors. However, if a TopSpeed file is physically damaged during a system malfunction, the TopSpeed Database Recovery Utility can recover the undamaged portions of your data.

The TopSpeed Database Recovery Utility is an emergency repair tool and should not be used on a regular basis. Use it only when a file has been damaged.

The TopSpeed Database Recovery Utility reads the damaged file and writes the recovered records to a new file. It uses the information stored in the file's header and scans the file recovering undamaged portions.

Optionally, you can provide an example file containing the header information in the event the original header information is damaged. An example file is any file with a FILE declaration identical to the damaged file. You can create an example file by issuing a CREATE(file) command, then saving the resulting empty file to a new name.

The TopSpeed Database Recovery Utility is a distributable utility designed to help your end-users recover damaged files.

The Clarion license agreement applies to TPSFIX.EXE. You may distribute to your users, but they may not redistribute it.

The following DLLs, found in the Clarion BIN folder, also need to be distributed with TPSFIX.EXE:

C60RUNX
C60METX
C60TPSX

The recovery utility is designed to work either interactively or noninteractively with command line parameters. Interactively, you provide the parameters through two wizard dialogs. You can run TPSFIX noninteractively by supplying the command line parameters with the Clarion RUN() statement, Windows API calls, Windows 95 shortcuts, or Program Manager Icons.

ERRORCODE 90 and Corrupted Files

The TopSpeed driver posts an ERRORCODE of 90 for unexpected runtime errors. When an ERRORCODE of 90 occurs, the driver also posts a FILEERRORCODE (the former TPSBT error code) that helps us diagnose the problem.

An ERRORCODE of 90 usually indicates your TopSpeed file is corrupted. In most cases the corruption is a result of hardware failure. For example, one customer with a 50 machine network traced a near daily file corruption to bad network cards on 2 of the 50 machines. After replacing the bad cards, the corruptions disappeared.

However, should you receive an ERRORCODE of 90 from the TopSpeed driver, we want to know about it. Before you repair the file, please make a copy of the damaged file and send it to us along with the corresponding FILEERRORCODE value. We analyze all the corrupted files we receive for recognizable patterns that can help us improve the driver.


TopSpeed File Errors

Here is a list of the TopSpeed file errors returned by FILEERRORCODE , and a brief explanation:

231  - trying to append a record when the btree is marked read-only
232  - cannot get btree header when trying to append a record
256  - cannot get btree header when trying to get a record
300  - btree structure corrupt (discovered when deleting a record)
327  - btree structure corrupt (discovered when putting a record)
337  - trying to put a record when the btree is marked read-only
522  - invalid data size found while unpacking record (from disk)
530  - invalid repeat count found while unpacking record (from disk)
706  - btree structure corrupt (discovered when inserting a record)
780  - btree structure corrupt (discovered when removing a record)
824  - btree record size to big (on allocation)
1013 - cannot get btree header (while loading root page)
1043 - cannot get btree header (while packing a record to disk)
1163 - trying to create new record ID when the btree is marked read-only
1164 - cannot get btree header (while allocating new record ID)
1173 - maximum record ID reached on allocation (probably indicating file corruption)
1194 - trying to insert record when the btree is marked read-only
1203 - trying to remove record when the btree is marked read-only
1364 - btree structure corrupt (discovered while splitting a page)
1477 - btree page size (from header) does not match size stored on disk
1602 - btree unpacked page size (from header) does not match size loaded from disk
1659 - btree page size increased after packing
1678 - btree page size larger than maximum allowed
1735 - btree header corrupt (discovered when trying to calculate disk file size)
1781 - btree structure corrupt (discovered while shifting btree pages up)
1891 - btree structure corrupt (discovered while moving btree pages)
1894 - btree structure corrupt - invalid page parent level (discovered while moving btree pages)
2172 - reading of btree page from disk failed
2183 - too many files logged out
2272 - encryption block invalid size (discovered when reading page from disk)
2277 - ReadFile Win32 API function failed (when reading page from disk)
2286 - encryption block invalid size (discovered when writing a page to disk)
2328 - invalid internal btree locking mode (on lock)
2352 - invalid internal btree locking mode (on unlock)
2341 - SetFilePointer Win32 API function failed (when reading page from disk)


Using the TopSpeed Database Recovery Utility Interactively

1.	Start the utility by double-clicking on the TopSpeed Database Recovery Utility Icon In the Clarion Program Group.

The TopSpeed Database Recovery Utility dialog appears. The utility consists of two wizard dialogs.

2.	In the Source (file to recover) section, specify the file name or press the Browse button to select it from a standard file open dialog.

3.	If the file has a password, type it in the Password entry box.

If the database file contains multiple tables (data files), each table must have the same password.

4.	Optionally, in the Destination (result file) section, specify the file name for the target file or press the Browse button to select it from a standard file open dialog.

By default the .TPR extension is added to the source file name. This parameter is optional. If omitted, the original (source file) is overwritten and a backup file is created. The source file is renamed to filename.TPx, where x is automatically incremented from 1 to 9 each time a new file is created. If all nine numbers are used, any subsequent files created are given the extension .TP$ and are overwritten.

5.	If the result file is to have a different password, type it in the Password entry box. If omitted, the password is removed.

6.	Press the Next button.

The second wizard dialog for the TopSpeed Database Recovery Utility appears.

7.	Optionally, specify the Example File file name or press the Browse button to select it from a standard file open dialog.

The utility uses the Example File to determine table layouts and key definitions in the event those areas of the source file are damaged. The default extension is.TPE, but if you choose, you may use any valid DOS extension

Tip: 	We recommend shipping an example file when you deploy your application. This improves data recovery from a damaged file.

8.	If the example file has a password, type it in the Password entry box.

9.	If you want the utility to rebuild Keys, check the Build Keys box.

If omitted, the keys are rebuilt by the original application when it attempts to open it.

10.	If you want to use the Header Information in the source file, check the Use Header box.

Utilizing Header Information optimizes the utility's performance, but should not be used if the file header is corrupt. If omitted, the utility searches the entire data file and restores all undamaged pages.

11.	If the application uses a Locale (.ENV) File for an alternate collating sequence, specify the .ENV file or press the Browse button to select it from a standard file open dialog.

12.	If the file is using the OEM attribute to control the collating sequence, Check the Use OEM box.

This enables the OEMTOANSI and ANSITOOEM conversion.

13.	Press the Start button to begin the recovery process.

If the utility does not find any errors, a message appears informing you that "No Errors Detected in <fliename.ext>" and asks if you want to continue with recovery.


Command Line Parameters

The TPSFIX utility can accept command line parameters which lets you execute it from an application, from a Program Manager Icon, or from a Windows 95 Shortcut.

Here is the syntax for running TPSFIX noninteractively with command line parameters.

TPSFIX	sourcepath[?password] [destpath[?password]] [/A][/E:examplepath[?password]]
[/L:localepath] [/H] [/K] [/N] [/O] [/P] [/T:filename]

TPSFIX	The executable (TPSFIX.EXE).

sourcepath	The file name and path of the source (damaged) database file.

?password	The file's password.

destpath	The file name and path of the recovered database file. If omitted, the destpath is the same as the sourcepath and an example file is required.

/A	If specified, the user is not offered a backup prompt. The prompt suppressed, however a backup of the file is made.

/E:examplepath	The file name and path of the example database file. This parameter is required for any fix-in-place operation (that is, when sourcepath = destpath).

/H-	If specified, the utility uses the header information in the source file.

/K	If specified, the utility rebuilds all keys for the database.

/L:localepath	The file name and path of the Locale (.ENV) file used to specify an alternate collating sequence.

/N	If specified, the file will be checked for errors. No errors will be corrected.

/O	If specified, the file uses OEMTOANSI and ANSITOOEM to determine the collating sequence. See Internationalization in the Language Reference.

/P	If specified, the user is prompted for each parameter even if they are supplied on the command line.

/T:filename	If there are file errors, a log file with the supplied filename will be created.


Using the Utility in your Application

There are some issues to consider before allowing the utility to run.

The database file should NOT be open when running the utility. Ensure that the file is closed before allowing the user to start the utility.

To prevent access during the recovery process is completed, the utility locks the file automatically.

It is more efficient and safer to allow the application to rebuild the KEYs (by omitting the /K parameter in the recovery). It is also a good way to check the status of a recovery.


Running the TopSpeed Database Recovery Utility

There are basically two methods you can use from a RUN() statement: Using the first method, you omit the destpath parameter so the original (source) file is overwritten. This requires an Example file.

In the Application Generator:

1.	In the Actions dialog for a button or menu item, choose Run a Program from the drop down list.

2.	In the Program Name entry box, specify TPSFIX.EXE.

3.	In the parameters entry box, specify the parameters (see Command Line Parameters above).

For Example:

TPSFIX.EXE Datafile.TPS /E:Example.TPE /H

In Embedded Source Code:

RUN('TPSFIX.EXE Datafile.TPS /E:Example.TPE /H')

This recovers the "datafile.TPS" file using the "Example.TPE" file as an example for the table and key layouts, does not rebuild the keys, and uses the header information in the original file. The original file is saved to a backup file with an extension of TP1 through TP9. Each time the utility is executed, the numeric portion of the extension is incremented.

The second method requires two lines of embedded source code but gives you control over the renaming process. You insert the source code in the Accepted Embed point for the Menu Item or button.

For example:

COPY(datafilelabel, 'Datafile.OLD')	!  copies the original file
!  to Datafile.OLD

RUN(TPSFIX Datafile.OLD Datafile.tps /H)	!  Runs the utility using
!  renamed file as

!  the source and the original
!  name as the target

This copies the datafilelabel file to DATAFILE.OLD, recovers the file and writes it to DATAFILE.TPS using the header information in the original file.