PATFIX ReadMe Document - 08/09/1998

PLEASE, PLEASE, PLEASE read this entire document before running PATFIX.  It may just save your job someday.


What is PATFIX?

PATFIX is a program which allows a knowledgeable user to swap the active FCR and PAT pages in an existing Btrieve file with their shadowed equivilent.


Why would I need PATFIX?

There is a problem with the 32-bit (Win95/WinNT) Btrieve engines (both the Windows 95/NT Workstation engine AND the Windows NT Server engine) prior to Btrieve 6.15.451 in which it does not update PAT pages the same way that all other engines do.  As such, there is a rather large window in which files can become corrupted after a workstation crash.  If the engine crashes, the Btrieve data file can be left in an unreadable state.  The usual symptom of this is a Status 2 being reported by an application, and a BUTIL -RECOVER being able to only recover a fraction of the records in the database, if any at all.  (Many times, BUTIL recovers 0 records.)

In actuality, the PAT page usage counter has become damaged, and the backup copy, which was never maintained by the 32-bit engine, becomes active.  Unfortunately, this backup copy does not point to any of the valid data, or it points to (at most) one valid data page.

PATFIX may be useful in other corruption cases.  User beware.


How does PATFIX work?

PATFIX displays pairs of pages (the FCR and each PAT) to the user, indicating the currently active page on the screen.  The user has the option to change the active page or go on to the next pair.  When all pairs have been reviewed, the program automatically exits.


Who made PATFIX?

PATFIX was created by Goldstar Software Inc., a company which specializes in providing installation, troubleshooting, training, and ongoing support for Btrieve and Scalable SQL databases.  They can be reached at:
	Goldstar Software Inc.
	3007 Carmel Drive
	Flossmoor, IL 60422-2262
	Web: www.goldstarsoftware.com


How much does PATFIX cost?

PATFIX is shareware; so in essence, nothing.  However, to obtain additional technical support and updates on PATFIX, as well as E-mail support on Btrieve and/or Scalable SQL, you should register the product by sending $10 US to the above address.  If you wish to obtain source code or a low-cost distribution license, contact Goldstar Software for details.


Is PATFIX certified or warranteed in any way?

Heck NO!  Pervasive Software is aware of the utility, but never recommends any direct access to any of their database files.  PATFIX is simple, but it can also destroy a properly working file.  As such, there are no warranties, expressed or implied, that the software works or does anything of value, and guarantees are available that ANY data will be valid after using it.  More importantly, anyone using PATFIX against a Btrieve file may not be able to obtain support from Pervasive Software on the corruption.  So, USE AT YOUR OWN RISK.

Of course, if this is the only tool you have to recover your mission critical database, sometimes you just have to throw caution to the wind and try it!


How do I run PATFIX?

Simply typing PATFIX at the DOS command line will display the usage syntax.  To actually run PATFIX against a file, type:
	PATFIX <filename>
Where <filename> is the name of the Btrieve file you wish to access.  

IMPORTANT NOTE: ALL USERS MUST BE OUT OF THE FILE BEFORE RUNNING PATFIX!
IMPORTANT NOTE: YOU SHOULD ALWAYS HAVE A BACKUP OF THE FILE BEFORE RUNNING PATFIX!
IMPORTANT NOTE: SEE SECTION IMMEDIATELY ABOVE REGARDING CERTIFICATION!
IMPORTANT NOTE: YES, THESE ARE REALLY IMPORTANT NOTES!

When you run PATFIX, if you have the SHAREWARE release, it will display a short registration message.  Press any key to start processing the file.

The next screen you will see is the FCR screen.  On the screen will be two columns of data.  The left half of the screen is the first FCR page, the right half is the second FCR page.  The arrows (< or >) down the center indicate the currently active page, which can be validated by checking the Usage Counters, which are displayed in parentheses on line 3.  Also on line three, you will see "(1 of x)".  Since each screen can only show 256 bytes, and since Btrieve pages can be up to 4096 bytes, the <PageUp> and <PageDown> keys can be used to view the various sections of the page.

If the FCR page is still intact, press <SpaceBar> or <Enter> to go to the first PAT page.  If you want to switch to the other FCR page, press <C>, and the other FCR page will be activated, and you will see the first PAT page.

The next screen will be the first PAT pair, displayed in the same manner.  For the PAT pages, though, the columns to the right of each page displayed will contain letters like "D", "I", and "V".  These letters indicate the type of page shown by that PAT entry.  (Header bytes show as "?".) If a space is shown (" "), then the page is a free page, available for use by the engine, or an unallocated page.

Again, press <C> to alter the active PAT page, or just press <Space> to go to the next PAT pair.  When all PAT pairs have been processed, the program will exit.

VERY IMPORTANT NOTE: AFTER RUNNING PATFIX, IMMEDIATELY REBUILD THE FILE USING TRADITIONAL MEANS BEFORE DOING *ANYTHING* ELSE.  IT MAY BE ABLE TO RECOVER MOST DATA, BUT MAY ALSO INCLUDE ADDITIONAL RECORDS, AND THE FILE INDICES WILL LIKELY BE CORRUPTED, CAUSING ADDITIONAL FILE CORRUPTION PROBLEMS.


What does the 32-bit workstation engine corrruption look like?

Most corruption has been identical.  The second FCR page is usually still intact and active. It will be obvious if you have been running the 32-bit engine, since the first page (left hand side of the screen) will have a usage count of 00000001.  Then, for the PAT pages which were active at the time of the crash, the left PAT page will have a usage count of 00000001 and will usually only have a single Data page and one or more Index pages indicated, while the right hand page will have a usage count of 00000000, but will contain otherwise valid data.

Other PAT's after the first may show different numbers on the left side, but these are the valid usage counters (from the right side) at the time the PAT was created.


Gee, couldn't you automate the PATFIX process?

Probably, but this was not done for a few reasons.
1. The 32-bit Engine corruption problem has been reproduced by Pervasive, and they have resolved it in 6.15.451.  Why spend time on automating PATFIX when the reason it was created will be eliminated?
2. This type of file modification is NOT recommended for end-users.  The data file should be completely shut down, and subsequently rebuilt after running PATFIX.  Automating the process only makes it easy for end users to ignore these extra steps.
3. PATFIX may also be useful for other problems, or just for people trying to learn about Btrieve files.


Where can I find more information?

The information used to create PATFIX was gleened in part from Jim Kyle's book, BTRIEVE COMPLETE, published by Addison-Wesley.  Buy the book -- it's well worth it!

Additionally, Goldstar Software Inc. can provide on-site training and troubleshooting assistance for a myriad of problems, including networking, Btrieve, Scalable SQL, and more.  Contact the address given above for more information.


Version History:
1.2: First released revision
1.3: Fixed problem dealing with 4K Entended PAT Bitmap at PAT pair 31.
1.6: Removed Extended Bitmap code for 7.x Files (which don't use it).
