Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

Transaction High-Water Marks

The FairCom Server and the single-user standalone operational model with transaction processing use a system of transaction number high-water marks to maintain consistency between transaction-controlled index files and the transaction log files. When log files are erased, the high-water marks maintained in the index headers permit the new log files to begin with transaction numbers that are consistent with the index files.

With FairCom Server, if a transaction high-water mark exceeds 0x3ffffff0 (1,073,741,808) for version 7.x servers and earlier or 3ffffffffff0 (70,368,744,177,648) for version 8.x servers and later, then the transaction numbers will overflow causing problems with index files. On file open, an error MTRN_ERR (533) is returned if an index file’s high-water mark exceeds this limit. If a new transaction causes the system’s next transaction number to exceed this limit, the transaction will fail with an OTRN_ERR (534).

This should be an unusual occurrence except on systems that are continuously processing significant volumes of transactions.

Before these errors occur, the FairCom Server issues warnings when the transaction numbers approach the transaction limit. These warnings are issued periodically to the system monitor and the CTSTATUS.FCS file.

To aid in debugging if spurious MTRN_ERRs occur, the server configuration keyword TRAN_HIGH_MARK takes a long integer as its argument and specifies a warning threshold. If an index file’s header contains a high-water mark in excess of this threshold, the file’s name is listed in CTSTATUS.FCS.

Use the CleanIndexXtd() function or the ctclntrn utility to reset index file high-water marks to zero. This permits new logs to start over with small transaction numbers. To fully reset the high transaction number requires the following steps:

  1. Shut down the FairCom Server cleanly, restart the server so it can do automatic recovery with no clients attached, and then shut it down cleanly a second time. Performing two shutdowns in a row ensures the application files are up-to-date and there are no pending recovery items so all *.FCS files except the FAIRCOM.FCS file can safely be removed. Be sure not to overlook the CTSYSCAT.FCS file (used for ODBC) and the SYSLOGDT.FCS and SYSLOGIX.FCS files. If you are using the SERVER_DIRECTORY (which is now deprecated), LOCAL_DIRECTORY, LOG_EVEN, LOG_ODD, START_EVEN, START_ODD or similar keywords that take a directory path, be sure to check that path for any *.FCS files that should be removed or data and index files that should be cleaned.
  2. Use the CleanIndexXtd() function or the ctclntrn utility to clean all indexes used by the FairCom Server, including your application index files, superfiles and variable-length data files. Executing ‘ctclntrn FAIRCOM.FCS’ will clean all the member indexes in this system superfile and the same is true of any application superfiles as well.
  3. If you wish to verify the cleanup process, you can use the cthghtrn utility in the server utils directory to verify that the transaction high-water mark in the files you cleaned is zero or a reasonably low number.
  4. After completing the cleaning process, verify that there are no *.FCS files other than the cleaned FAIRCOM.FCS (which has been verified clean as described above) in the server directory. If you are using SERVER_DIRECTORY (now deprecated), LOCAL_DIRECTORY, LOG_EVEN, LOG_ODD, START_EVEN, START_ODD, or a similar keyword in your ctsrvr.cfg file that takes a directory, be sure to check that path for any existing *.FCS files and remove them.
  5. When you are satisfied that you have completely cleaned all files, restart the c tree Server. As soon as the server is up and operational, cat or type the CTSTATUS.FCS file prior to attaching any clients and be sure there are no “Pending TRANSACTION # overflow” messages indicating that you have missed cleaning or removing a system (*.FCS) file.
  6. You can easily monitor the current transaction value in your application by checking the return of the Begin() function and verifying it against the 0x3ffffff0 or 3ffffffffff0 threshold. This will ensure that you know well in advance about any impending transaction number overflow issues and will allow you to prevent any unexpected server shutdown.

Note: If you perform the high-water transaction clean operation to reset your high-water mark and then perform a restore that has unclean files or transaction logs, you will need to perform the clean operation again.