Installing FairCom Products

Adjusting PAGE_SIZE

Adjusting page size is a complex topic. To learn more details about it, see Important - PAGE_SIZE Conversions.

Warning: Changing the PAGE_SIZE is a maintenance task that should be done carefully and with a full reliable backup. Practice on a copy of your data and other folders until you are confident with the results. FairCom DB V12 has a default PAGE_SIZE 32K (V11 defaulted to 8K) and it will automatically attempt to convert the FairCom Internal files (FAIRCOM.FCS, *.FSD, *.FDD) during the initial startup. The automatic conversion requires the file ctscmp.exe (ctscmp on Linux/Unix) to be present in the working directory where the FairCom Server binary (faircom.exe for V12) is located (the \server directory for V12).

Notice that a file created with a larger PAGE_SIZE cannot be opened by a system with a smaller PAGE_SIZE.

Follow these procedures to rebuild the affected files:

1. Shut down the FairCom Database Engine, start it again, then shut it down again to be sure all logs are flushed and a clean final checkpoint has been written.
2. Make a good backup of your databases and your server folder.

   Move this copy to a different machine from your live system. Keep a clean copy in case you need to start over.

3. Edit ctsrvr.cfg and add the PAGE_SIZE keyword if it is not already there:

   PAGE_SIZE 32768

   • The size should be a power of 2. The maximum page size is 64k (65536).
   • The current default in V12 and later is 32768.
4. Go to the FairCom data directory.
5. Delete all log and start files (i.e., all files that start with "L00…", "S00…", "D00…"). With a clean shutdown you should not have any "I00…" files in the directory.
6. For V12.0.2 and greater, FairCom DB attempts to convert its internal control files to the larger PAGE_SIZE specified in ctsrvr.cfg, if needed. See FairCom Internal File Conversion below for important details.

   For V12.0.1 and earlier, rebuild the three superfiles used by the FairCom Database Engine using the ctscmp utility including the -sect parameter:

   • Remember that the sect size is the page size/128. For example, if your page size is 32768, use a sect size of 256.

      ctscmp.exe <server directory>\data\ctdbdict.fsd 256

      ctscmp.exe <server directory>\data\ctreeSQL.dbs\SQL_SYS\ctreeSQL.fdd 256

      ctscmp.exe <server directory>\data\FAIRCOM.FCS 256

7. Delete the current index files for your data files.
8. Change the indexes for your data files using the ctcmpcif or ctcmpcif.standalone utility including the -sect parameter (which is -256 in the example below):

   ./ctcmpcif (server directory)/data/ctreeSQL.dbs/MyData.dat ADMIN ADMIN FAIRCOMS -256

   ./ctcmpcif.standalone (server directory)/data/ctreeSQL.dbs/MyData.dat -256

   If using ctcmpcif, restart the server first.

9. Fixed-length files: Rebuild the indexes for your fixed-length data files using the ctrbldif utility including the -sect parameter (which is -256 in the example below):

   ./ctrbldif (server directory)/data/ctreeSQL.dbs/MyData.dat -256

   Variable-length files: Rebuild the indexes using ctcmpcif.exe as follows:

   ctcmpcif.exe <your application data directory>\your_file.dat 256

   Note: It is acceptable to use ctcmpcif.exe to rebuild both fixed and variable-length files. The ctcmpcif.exe utility creates a new copy of the data file by copying all the active records into a new file, and then calling ctrbldif.exe to generate a new index. This step is required to ensure the deleted space management index is properly built within the variable length data file. Fixed-length files don’t have any internal indexes, therefore calling ctrlbdif.exe is sufficient.

10. Restart the server and verify no errors were logged in <faircom>/data/CTSTATUS.FCS.
11. Connect to your data files and verify no errors were returned.

FairCom Internal File Conversion

When the PAGE_SIZE server configuration option is changed, FairCom V12.0.2 and later attempts to apply this change to all FairCom server-controlled files. At server startup we check the page size of the following FairCom files:

• ctdbdict.fsd
• Database dictionaries
• FAIRCOM.FCS
• SEQUENCEDT.FCS
• DFRKSTATEDT.FCS
• SYSLOGDT.FCS
• REPLFFCHGDT.FCS
• REPLOGDT.FCS
• REPLOGSHIPDT.FCS
• REPLSTATEDT.FCS
• REPLSYNCDT1.FCS
• REPLSYNCDT2.FCS

If any do not match the newly specified PAGE_SIZE, a backup copy of the existing file is made with an .FCB extension. The server process then attempts to invoke the FairCom ctscmp.exe (ctscmp on Linux/Unix) superfile rebuild utility with the new configured PAGE_SIZE.

Superfiles require that the PAGE_SIZE at open matches the PAGE_SIZE at file creation time, or a KSIZ_ERR (40) or SPAG_ERR (417) error occurs at file open. For FAIRCOM.FCS, this prevents the server from starting when operating with a different configured PAGE_SIZE setting.

A new configuration keyword has been added to control the automatic page size conversion at startup:

PAGE_SIZE_CONVERSION {YES|NO}

Default: YES

Limitations:

1. We expect ctscmp.exe (ctscmp on Linux/Unix) to exist in the process working directory and have permission to be executable by the server process. If this utility does not exist, the server fails to start with the following messages likely logged to CTSTATUS.FCS:

   - User# 00001 Wrong PAGESIZE for FAIRCOM.FCS, attempting to convert file from PAGESIZE 8192 to 32768

   - User# 00001 Did not find ctscmp in working directory for Superfile conversion: 2

   - User# 00001 Could not process User/Group Information in FAIRCOM.FCS: 417

   - User# 00001 Could not initialize server. Error: 417

   - User# 00001 O1 M0 L74 F417 P0x (recur #1) (uerr_cod=417

2. The LOCAL_DIRECTORY keyword must be set and must be different from the working directory. Otherwise, ctscmp.exe will encounter a TCOL_ERR (537) and fail.
3. Superfile conversion occurs only after auto-recovery. Recovery is likely to fail if run with a different PAGE_SIZE setting. We expect any needed recovery should occur before making a major configuration impacting the physical attributes of critical operational files such as authentication information and SQL database dictionaries (system tables).
4. NO FURTHER ATTEMPT IS MADE to convert any other existing indexes. All other application created indexes will require manual rebuilding to convert to a new page size. See the steps below for the best practice procedures.

   The following messages may be found logged to CTSTATUS.FCS after a successful conversion:

   - User# 00001 Wrong PAGESIZE for FAIRCOM.FCS, attempting to convert file from PAGESIZE 8192 to 32768

   - User# 00001 Backup created ../data/\FAIRCOM.FCS => ../data/\FAIRCOM.FCS.1621883226.FCB

   - User# 00001 Superfile conversion successful

   - User# 00001 Wrong PAGESIZE for ctdbdict.fsd, attempting to convert file from PAGESIZE 8192 to 32768

   - User# 00001 Backup created ../data/\ctdbdict.fsd => ../data/\ctdbdict.fsd.1621883232.FCB

   - User# 00001 Superfile conversion successful

   - User# 00001 Wrong PAGESIZE for .\ctreeSQL.dbs\SQL_SYS\ctreeSQL.fdd, attempting to convert file from PAGESIZE 8192 to 32768

   - User# 00001 Backup created ../data/\.\ctreeSQL.dbs\SQL_SYS\ctreeSQL.fdd => ../data/\.\ctreeSQL.dbs\SQL_SYS\ctreeSQL.fdd.1621883237.FCB

   - User# 00001 Superfile conversion successful

Once correct server operations are confirmed after conversion, the *.FCB files can be removed and deleted.