Installing FairCom Products

Important - PAGE_SIZE Conversions

FairCom V13/V12 has a new default page size setting of 32K. In an effort to simplify the upgrade process for this new support, FairCom has implemented automatic conversions of its internal control files. This section describes this new support, and includes the recommended conversion process for converting application data.

Background

Operating systems have a default file block size they read and write data in. Most recent Linux and Windows operating systems are 4K. Other operating systems will vary. Setting the index page size to match the OS or multiples of OS file block size can improve I/O performance. FairCom Database Engine supports setting PAGE_SIZE from 512 bytes up to a maximum of 64K (65,536).

The PAGE_SIZE setting used by FairCom DB can have a dramatic effect on database performance. In most applications, a larger page size is a benefit, especially if index keys are relatively large (> 20 bytes or so), or there is a reasonable number of key values (consider 100K key values or greater).

You should set your c-tree server PAGE_SIZE to at least the OS file block size, nothing smaller. For example, if you set c-tree's PAGE_SIZE to 2K, then on Windows you are reading 4K at the OS level and throwing away 2K every time.

For most applications, 32K is a well performing value. If you are looking to fully optimize your application, and if your files are fairly large, you might gain performance by increasing this setting, in multiples of your operating system page size value. The best method for tuning this value is to try a few different sizes with exact application configurations and a copy of your data. For example, increase from 8K to 16K and if your performance increases, then continue and test with 32K. Once your performance starts dropping, then scale back in smaller increments looking for the sweet spot for your application. It’s possible your application sweet spot might be less than 32K.

For V13/V12, FairCom has increased the default PAGE_SIZE setting to 32K (V10 and V11 defaulted to 8K). There are two options for addressing this topic:

1. Staying with your current PAGE_SIZE setting is an option. You can set PAGE_SIZE X to your current value (where X is your current PAGE_SIZE). This will prevent the need to rebuild your application indexes.
2. Rebuild your application indexes to utilize either FairCom’s new 32K default (or a PAGE_SIZE better suited to your application) by following the testing procedure above.

Changing PAGE_SIZE

Upgrading FairCom Servers to a different page size is a maintenance task that should be done carefully after a full, reliable backup. Failure to perform the procedures (provided later in this section) will cause the system to be halted with a KSIZ_ERR, error 40.

In V12.0.1 and later, the server will automatically convert its internal superfiles to the server's current page size. However, you are responsible for converting your application index files and any superfiles created by your FairCom DB based application.

When the PAGE_SIZE server configuration option is changed, FairCom applies 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.

Changing Application PAGE_SIZE Manually

Changing the application index page size is a maintenance task that should be done carefully after a full, reliable backup. When making a PAGE_SIZE configuration change with existing indexes, those indexes must be rebuilt using the new node size before they can take advantage of the new configured size.

• ctrbldif.exe can be used to make this modification for fixed-length files
• ctcmpcif.exe must be used for variable-length files.

Existing indexes with nodes smaller than a configured PAGE_SIZE will display the following informational messages in CTSTATUS.FCS upon file open:

- User# 00027 Mismatched PAGE_SIZE is wasting 75% of Index cache used by .\ctreeSQL.dbs\admin_custmast.dat

This message appears because the smaller node size of the existing index fits into the larger page size value as allocated in the index buffer cache with the remainder of the cache page space wasted. Note that even though in this case the file will open successfully, you are wasting memory. Consider with the message above, if you are using an 8K PAGE_SIZE in the FairCom DB Server, and your application index file is set to 2K, then 6K of memory is wasted with each index page loaded into the Index Cache.

FairCom DB V13/V12 defaults to a larger page size configuration recommended for modern client-server applications. However, existing index files must be rebuilt to take advantage of this larger index node size. Opening existing indexes smaller than the configured server value results in a warning message logged to CTSTATUS.FCS about wasted memory usage.

For applications that have large numbers of files, or that frequently open and close files, this may result in large numbers of messages to CTSTATUS.FCS, and this logging is disabled after the first 20 occurrences.

The following command turns off all PAGE_SIZE warnings so no warnings are produced:

CTSTATUS_MASK WARNING_PAGESIZE

Setting this keyword disables the logging of warning messages like the one shown above.

For debugging, if it is necessary to see all warnings, you can use the following keyword to log all the warnings to CTSTATUS.FCS:

CTSTATUS_MASK WARNING_PAGESIZE_SEEALL

Note: Existing indexes with a larger page size than the configured PAGE_SIZE continue to result in an error KSIZ_ERR (40) on open.

Rebuilding Application Files

Recommendation: If you are considering changing your PAGE_SIZE setting, be sure to rebuild ALL of your index files.

If you are reducing your PAGE_SIZE setting, and you miss rebuilding an index, and its value is set larger than your current PAGE_SIZE setting, then you will get an error 40 (KSIZ_ERR, Index node size too large) when this file is opened and it will need to be rebuilt to resolve this error.

If your index file(s) have a PAGE_SIZE set less than your current PAGE_SIZE setting in ctsrvr.cfg, then you will be wasting memory. The file will open fine, because a smaller index PAGE_SIZE will fit in the larger PAGE_SIZE set in ctsrvr.cfg.

Recommendation: Experiment on copies of your data and server folder. When you are confident with the results, back up your source data and then change the live production files.

Compatibility

The page (node) size is a permanent attribute of an index when it is created. Index nodes remains that size until rebuilt or compacted with a different size. There are limitations with existing files using a new larger page size.

• c-tree can open existing indexes with a smaller page size than currently configured. There is a minor memory use trade off in doing so. As each index node maps to a single server cache page, and the server cache page is allocated as a page size, the unused space in the cache page is lost. This can be significant. If a server configured for a 32K page size index cache is at 100% capacity of 8K index nodes, up to 75% of cache memory is unused. For very large caches this is significant.

  It will be extremely beneficial to rebuild existing indexes and take full advantage of both increased index page size benefits as well as full cache memory usage.

  Opening indexes created with page sizes larger than currently configured results in error 40 (KSIZ_ERR).

• Superfiles can ONLY be opened with the same configured page size as they were originally created. This has important implications with critical c-tree housekeeping files:
  • FAIRCOM.FCS - This file maintains all user, group and password hash information.
  • ctdbdict.fsd - This file maintains the catalog of available databases (SQL and c-treeDB).
  • <database_name>.fdd - This file maintains the SQL database system tables (catalog or dictionary).

  Using these existing superfiles with a different page size will result in a server startup failure. Opening a superfile with a different page size also results in error 40 (KSIZ_ERR). You will find this message logged in CTSTATUS.FCS should the server make this failed attempt.

Rebuilding Existing Indexes

The following options are available for rebuilding indexes to take advantage of increased page size.

ALWAYS MAKE CLEAN BACKUP COPIES OF THESE FILES BEFORE YOU BEGIN THESE PROCEDURES

The index rebuild utility, ctrbldif, is the quickest easiest option for most indexes. Simply pass the new sect size.

Remember, each sect = 128 bytes. For 32768 your sect size will be 256.

> ctrbldif mytable.idx -256 ADMIN ADMIN FAIRCOMS

For superfiles, use the superfile compact utility, ctscmp.

> ctscmp ctdbdict.fsd Y 256

To make superfiles that can be opened by versions earlier than V12, use ctscmp with the -v11 option. This option forces the utility to avoid introducing V12-specific features to the resulting file. Usage: ctscmp filename [-v11] [sectors]

PAGE_SIZE Change Procedures

For procedures explaining how to rebuild files affected by a change of PAGE_SIZE, see Adjusting PAGE_SIZE in the FairCom Installation Guide.