FairCom ISAM for C

ctrbldif - IFIL-based Rebuild Utility

A rebuild utility using the IFIL definitions stored in the header of a file:

Operational Model:

• Client
• Standalone

Usage:

ctrbldif DataFileName [<UserId> [<Password> [<ServerName>]]] <options>

Description

ctrbldif reads the IFIL structure from DataFileName and calls RebuildIFileXtd() to rebuild DataFileName and its associated indexes.

The following switches can be added in the location specified by <options> above:

• -callback - In V11.5 and later: When used with a FairCom DB Server this will provide additional feedback on the rebuild progress.
• -idxseg=<M>@<S> - If creating index, use M automatic segments of size S. Size is specified in megabytes, or you can specify MB or GB as a suffix. For example: -idxseg=10@1GB
• -local - causes the utility to use a standalone (local side) connection instead of a client connection when linked with a LOCLIB library.
• -oldsec - Use prev10.3 security attribute behavior.
• -online - In V13 and later: Rebuild the index while it remains available to other users.
• -purge - Purge duplicate records.
• -repairdata - Attempt repair if damaged data records are detected.
• -skipdatascan - In V11.5 and later, if you know your datafile is in a good state, you can use this option to skip the initial datafile validity scan for faster rebuilds.
• -sortmem=<N> - Use N KB of memory for sorting. This option can be used to increase the rebuild speed for large files.
• -updifil - Update the IFIL resource within the data file.
• -x8 - Use extended create blocks read from data and index files.

  FairCom DB Standalone Options

• -temppath= - directory path, <temporary_path>, to create temporary sort and purged record files. (This standalone option is the equivalent of the TMP_PATH server configuration option.) The default location is the current directory.
• -<sectors> - sector size, <sectors>. (in multiples of 128). The sector parameter is especially useful if you need to adjust a file’s PAGE_SIZE (index node size) to match the FairCom Server. FairCom DB standalone models default to 16 sectors (2048 byte node size) while the FairCom Server defaults to 64 sectors (8192 bytes).

  FairCom Server Options (Must be passed before any optional switches)

• <UserID> : client user name to logon to a FairCom Server.
• <UserPassword> : client user password to authenticate to a FairCom Server.
• <ServerName> : FairCom Server name for a client to connect.

Environment Variable to Enable Advanced Encryption

In V11.5 and later, c-tree supports enabling advanced encryption at run time using an environment variable. Set the environment variable CTREE_ADVANCED_ENCRYPTION to YES to enable advanced encryption if it is supported. This environment variable can be used to allow c-tree utilities to enable advanced encryption even if they haven't been updated yet to automatically enable advanced encryption when needed. Examples include the rebuild and compact utilities, ctrbldif and ctcmpcif.

Note: If c-tree does not support advanced encryption and this environment variable is set, the c-tree initialization will fail.

Considerations

• Even without the -x8 option, some extended create block settings such as the huge file, extended header, and 6-byte transaction number options, are always applied to new files.
• This option requires all associated index files that are referenced in the data file's IFIL structure to exist, as the utilities use OpenIFile() to open the data file and all associated index files to read the extended create block values.
• When an application calls the standalone version of the Xtd8 file compact or rebuild functions (for example, CMPIFILX8() or RBLIFILX8()), index files created by the compact or rebuild no longer have the 6-byte transaction number attribute enabled if the specified extended create block's x8mode field has the ctNO6BTRAN bit set.
• A rebuild or compact will fail with the new error code TFLN_ERR (943) when a client library that supports the new rebuild or compact option format attempts to use this feature with a FairCom Server that does not support this new format.

See Also:

• Preventing Possible Data Loss with Compact & Rebuild Operations

Option to set index's automatic segment attributes

If a segmented index file was deleted and rebuilt using the ctrbldif utility or the rebuild API function, the new index file was not segmented. The index file's segment attributes, which are stored in the index file, were lost when the index file was deleted.

Beginning with V10.3, an option is provided with the rebuild and compact utilities that causes index files that are created by the utilities to be created using automatic segments of the specified size and maximum. The option is:

-idxseg=M@S

where M is the maximum number of segments and S is the segment size. S is interpreted as megabytes by default. Two suffixes, MB and GB, are also supported. MB indicates that the value is in megabytes and GB indicates that the value is in gigabytes.

Examples:

50 segments of 10 MB each:

ctrbldif test.dat -idxseg=50@10
 

100 segments of 300 MB each:

ctrbldif test.dat -idxseg=100@300MB
 

20 segments of 3 GB each:

ctrbldif test.dat -idxseg=20@3GB
 

Note: If the index files exist, the -idxseg option has no effect. It is only when the rebuild or compact utility creates new index files because the old index files do not exist that the -idxseg option affects the automatic segment properties of the index files.

-oldsec - Updates in handling of security attributes

In V10.3 and later, the ctrbldif utility assigns data file owner/group/permissions to index files and ctcmpcif assigns original data file owner/group/permissions to compacted data/index files.

The rebuild and compact utilities now read the permission mask, owner, and group settings from the original data file and after the rebuild or compact is completed, the utilities assign these same attributes to the new files.

A command-line option has been added to the utilities to restore the previous security attribute behavior. Use the -oldsec option to cause the rebuild and compact utilities to set the security attributes as they did before this revision. For example:

ctrbldif mark.dat -oldsec ADMIN ADMIN FAIRCOMS

The -oldsec option can be used if rebuild and compact are failing with error 455 (user does not belong to group) if you delete an index then run the rebuild or compact utility on the data file using a user account that does not belong to the group that is assigned to the data file.

Note: These changes only apply to the client and server versions of these utilities. Setting the security attributes is not supported in standalone mode, so the standalone rebuild and compact utilities behave as follows:

1) When the standalone mode rebuild utility creates new index files instead of reusing the new index files (for example if the original index files have been deleted before running the rebuild utility), the new index files are assigned a permission mask of zero (no restrictions on permissions), and the owner and group are unassigned (empty).

2) The standalone mode compact utility always preserves the security attributes of the data file. If the index files do not exist, the newly-created index files are assigned the same values as the standalone rebuild does when it creates new index files.