Utilities - Low Level

The tools listed in the section are low-level utilities.

ctalgn - Change Alignment

The ctalgn utility is used to change the creation alignment characteristic of a file by updating the file's header.

Usage:

ctalgn <file name> <alignment constant: 1,2,4,8> [<# sectors>]

ctcnfg - System Configuration Example

This sample demonstrates the SystemConfiguration() function. Upon running the utility, you will see the main menu with the following choices:

SYSCFG: SystemConfiguration example

        1. Dynamic system resources

        2. Static system resources

        3. FairCom Server only resources

        4. Client and Server side resources

        5. Pre-initialization resources
 

Enter the number of your choice to see a display of the current configuration. For example, if you type the number 2 and then press the Enter key, you will see a display similar to the following:

Static system resources

-----------------------

Maximum c-tree Plus FCBs system wide :   14

Maximum indexes per data file        :   32

Maximum key segments per index       :   12
 

Press the Enter key to return to the main menu.

To exit from the utility, type q at the main menu and then press the Enter key.

ctcv43 - Convert V4.3 Data File to FairCom DB Format

ctcv43 <V4.3 data file name> <FairCom DB file name>

This utility converts a data file from c-tree V4.1F-V4.3C to FairCom DB format. It supports the conversion of files with up to 4 GB in size. Both fixed and variable-length files are supported.

If the new data file does not exist, it will be created. ctcv43 is designed to run in single user mode.

After converting the data files, you may use the function, RebuildIFile(), to construct the associated index files. If you have stand-alone indexes to convert, use ctin43 to first create a flat key file, and then use ctindx to build the new index file.

Note: ctin43, provided with FairCom DB, must be linked with your c-tree V4.3 application library.

ctcv67 - Extended File Conversion Utility

ctcv67 <old file name> <new path> [<option> <argument> ...]

The first two arguments are required. The new path is prepended to the old file name or the files in the parameter file. The options are listed in the table later in this topic.

ctcv67 performs various conversions, including:

• Converting data and index files from Standard FairCom DB format to Extended c‑tree format (HUGE or non-HUGE) using Incremental ISAM (IFIL) or parameter files.
• Adding huge file support to a non-huge file.
• Adding, removing, or changing segment support.
• Automatically compacting the output file.

Note: ctcv67 must be built by FairCom. An executable version is included in the FairCom Server installation for each platform, in the Utils folder.

If the original file has an extended header, the new file inherits the extended header attributes. This utility does not convert a huge file to a non-huge file. If a superfile host is specified, ctcv67 converts all member data files and their associated indexes. When a mirrored file is specified, the conversion does NOT produce the mirrors, but maintains the mirrored names in IFIL structures. Copy the converted master files to produce the mirror files.

Unless a parameter file is used, a data file must have an embedded IFIL definition for its associated indexes to be converted. A data file will have an embedded IFIL definition if it was created with one of the CreateIFile() routines or PutIFile() was called for the file.

If an index file is specified by the <old file name> parameter, then a new index file with an extended header will be created, all the resources will be transferred to the new index, its key length will be increased if HUGE is specified and the key supports duplicates, but no key values will be transferred to the new file. In essence, it will be an empty index file.

The following options are available:
 

Example:

ctcv67 vcusti new H no G new\vcusti.ndx 10 S e:\vc.s01 10 S f:\vc.s02 0

where:

• vcusti is the existing file name.
• new is the new path.
• H no creates a normal file rather than a huge file.
• G new\vcusti.ndx 10 sets the new segment host file name to new\vcusti.ndx and the host segment size to 10 MB.
• S e:\vc.s01 10 S f:\vc.s02 0 creates the following segments:

e:\vc.s01 with a size of 10 MB.

f:\vc.s02 with a size of 0 MB.

Ordinarily, the new path name is simply prepended to the original file name. If both have absolute names, the new (absolute) path replaces the absolute portion of the original name. If only the original file is absolute, the new (relative) path is inserted immediately after the absolute portion of the original file name. Otherwise, the new path (relative or absolute) is prepended to the original (relative) file name.

For example, to convert the data file C:\DATA\SAMPLE.DAT and its associated index, C:\DATA\SAMPLE.IDX, into huge files with three segments of 2000 MB each, use the following command line:

ctcv67 C:\DATA\SAMPLE.DAT C:\HUGEDATA\ H yes

G C:\HUGEDATA\DATA\SAMPLE.DAT 2000 S D:\HUGEDATA\SAMPLE.SG1 2000 S E:\HUGEDATA\SAMPLE.SG2 2000 G C:\HUGEDATA\DATA\SAMPLE.IDX 2000 S D:\HUGEDATA\SAMPLE.IS1 2000 S E:\HUGEDATA\SAMPLE.IS2 2000

Even if the original file is segmented, the new file will not be segmented unless a new segment definition is specified using the ‘G’ and ‘S’ options.

The associated indexes are recreated based on the IFIL resource embedded in the data file or based on the parameter file information. If the associated data file becomes huge, index files allowing duplicate records will have their key lengths automatically increased by 4 bytes to accommodate the longer associated position information used to break the tie. If you recall, when allowing duplicate key values in an index, you must add 4 bytes to the key length. For huge files, you must add a total of 8 bytes. In addition, the index file names in the IFIL definition will reflect the new path name.

ctcv67 creates (or appends to) a text file named CV67.REP, which reports on the actions and progress of the utility program.

ctdidx - Create flat key file

ctdidx <index file name> <index member #> <flat key file name>

This utility will run either in single user mode or with the FairCom Server. The FairCom Server or single-user transaction processing mode is necessary to dump the keys from an index which supports transaction processing. ctdidx creates a flat file containing each key value at full, uncompressed length followed by the associated record position in long integer, 4-byte, form. ctdidx reads each key in order from the index member designated, 0 for the host index, 1 for the first member, etc., and places the keys in the flat file it creates.

ctdmpidx - Index Dump Utility

ctdmpidx is available to dump an index. This utility is useful for viewing index header details, viewing nodes and key values. The syntax is shown below:

ctdmpidx [-<page size>] [-listkeys] [-full] <filename> <member #> [<rflg>]

• The optional parameter -page size equals sector size * 128 (third parameter in InitCtree()). If page size is not entered, a default value of 16 will be used. filename specifies the index file targeted for analysis.
• The member # refers to the index member number. A physical index file can contain one or more indexes. Each index has a member number (0, 1, 2, 3, etc.). For example, the sample index file custordr.idx provided with the FairCom ODBC Driver contains a total of two indexes. Depending on whether you specify 0 or 1 you will be looking at either the order number index or the customer number index.
• rflg represents an optional recovery flag switch and is only applicable when compiled with TRANPROC. Any character will enable rflg, which will result in c-tree skipping automatic recovery.
• If this utility detects the index file is using advanced encryption, it turns on c-tree's advanced encryption support and prompts for the master encryption password.
• The -listkeys, option is available in V10.3 and later. It lists all the key values and their associated record offsets in an index.
• The -full option causes ctdmpidx to display all keys when reading an index node. Otherwise, only the first few keys are displayed.
• filename specifies the index file targeted for analysis.

As of V12, ctdmpidx also checks for a transaction mark whose position in the node precedes the first mark position recorded in the node header. It also checks if the number of marks in the node differs from the mark count in the node header. In these cases, it outputs these messages:

ERROR: Found mark at element <n> but expected first mark at element <m>

ERROR: Found <n> marks but expected <m> marks

Example

Below is an example of launching ctdmpidx along with output showing the header and prompt for an index node address.

# ctdmpidx -2048 custmast.idx 0

header info for file #0  [custmast.idx]:

    configuration version:     81x                 index root ptr: 1000x

                node size:   2048          superfile last member#: 0

       data record length:      0                extend file size: 0

  max bytes per leaf node:   1348          max bytes per non-leaf: 2030

                file mode:  16392                      key length: 4

                file type:      1         # of additional members: 0

              update flag:      0x            index member number: 0

                 key type:      0                  file id number: 0

           duplicate flag:      0                server id number: 0

      # of active entries:      4                current node ptr: 0x

         delete stack ptr:      0x       index high transaction #: 0

           last byte used:   1800x                  serial number: 0x

       last physical byte:   1800x                    delete type: 0

permanent file mode flags:      0                  superfile type: 0

          leaf anchor ptr:   1000x             superfile member #: 0

              file flavor:      2                  file alignment: 8

         key padding byte:     20x            maximum name length: 255

        header record ptr:      0x            resource header ptr: 800x

Enter node address in hex: 1000

NODE: 1000x

            trans active: no

        predecessor node: 0x

          successor node: 0x

            # of entries: 4

              # of bytes: 32

               leaf flag: 1 (0 => non-leaf / 1 => leaf)

                member #: 0

         element  offset     key value

            1      101fx     31303030

                              1 0 0 0

            2      105ex     31303031

                              1 0 0 1

            3      1099x     31303032

                              1 0 0 2

            4      10d9x     31303033

                              1 0 0 3

ctflat - Create FairCom DB file from a flat file

Usage

ctflat <flat file> <new file> <record length> [<file mode> <ext size>]

Description

ctflat creates a FairCom DB fixed-length data file from an existing flat file with the specified record length. Optionally, you can specify the file mode to use when creating the file. For example, to enable transaction processing and the file size extension parameter.

ctflat assumes that the flat file begins at offset zero and has the record length indicated on the command line. You can modify the source to make it more appropriate for your specific circumstances.

ctflvrfy - Index Verify Utility

Usage

ctflvrfy <filename.idx>

Description

The Index Verify utility, ctflvrfy, takes the index name as the parameter and calls the ctVERIFY() and chkidx() functions to allow the user to verify the index, and optionally inspect it at a low-level.

>ctflvrfy custmaster.idx

Verifying file [custmaster.idx]

Retrying open with sect of [8]

Retrying open with sect of [12]

Retrying open with sect of [16]

Retrying open with sect of [20]

Retrying open with sect of [24]

Retrying open with sect of [28]

Retrying open with sect of [32]

Retrying open with sect of [36]

Retrying open with sect of [40]

Retrying open with sect of [44]

Retrying open with sect of [48]

Retrying open with sect of [52]

Retrying open with sect of [56]

Retrying open with sect of [60]

Retrying open with sect of [64]

Verifying the host index

Verifying index delete stack...

Verifying index links...

Verifying index leaf nodes...

Index page scan finds entries=75  header=75

Index nodes per level of tree structure - [0: 1]

( 2 resource pages )

Internal Index Verify: SUCCESSFUL

The return of ctVERIFY = 0,  75 KEYS FOUND

Verifying member index #1

Verifying index delete stack...

Verifying index links...

Verifying index leaf nodes...

Index page scan finds entries=75  header=75

Index nodes per level of tree structure - [0: 1]

( 2 resource pages )

Internal Index Verify: SUCCESSFUL

The return of ctVERIFY = 0,  75 KEYS FOUND

Verifying member index #2

Verifying index delete stack...

Verifying index links...

Verifying index leaf nodes...

Index page scan finds entries=75  header=75

Index nodes per level of tree structure - [0: 1]

( 2 resource pages )

Internal Index Verify: SUCCESSFUL

The return of ctVERIFY = 0,  75 KEYS FOUND

Verifying member index #3

Verifying index delete stack...

Verifying index links...

Verifying index leaf nodes...

Index page scan finds entries=75  header=75

Index nodes per level of tree structure - [0: 1]

( 2 resource pages )

Internal Index Verify: SUCCESSFUL

The return of ctVERIFY = 0,  75 KEYS FOUND

Verifying member index #4

Verifying index delete stack...

Verifying index links...

Verifying index leaf nodes...

Index page scan finds entries=75  header=75

Index nodes per level of tree structure - [0: 1]

( 2 resource pages )

Internal Index Verify: SUCCESSFUL

The return of ctVERIFY = 0,  75 KEYS FOUND

Verifying member index #5

Verifying index delete stack...

Verifying index links...

Verifying index leaf nodes...

Index page scan finds entries=38  header=38

Index nodes per level of tree structure - [0: 1]

( 2 resource pages )

Internal Index Verify: SUCCESSFUL

The return of ctVERIFY = 0,  38 KEYS FOUND

Verifying member index #6

Internal Index Verify: no tree structure

The return of ctVERIFY = 0,  0 KEYS FOUND

Verifying member index #7

Verifying index delete stack...

Verifying index links...

Verifying index leaf nodes...

Index page scan finds entries=75  header=75

Index nodes per level of tree structure - [0: 1]

( 2 resource pages )

Internal Index Verify: SUCCESSFUL

The return of ctVERIFY = 0,  75 KEYS FOUND

Verifying member index #8

Verifying index delete stack...

Verifying index links...

Verifying index leaf nodes...

Index page scan finds entries=16  header=16

Index nodes per level of tree structure - [0: 1]

( 2 resource pages )

Internal Index Verify: SUCCESSFUL

The return of ctVERIFY = 0,  16 KEYS FOUND

Verifying member index #9

Verifying index delete stack...

Verifying index links...

Verifying index leaf nodes...

Index page scan finds entries=75  header=75

Index nodes per level of tree structure - [0: 1]

( 2 resource pages )

Internal Index Verify: SUCCESSFUL

The return of ctVERIFY = 0,  75 KEYS FOUND

Verifying member index #10

Verifying index delete stack...

Verifying index links...

Verifying index leaf nodes...

Index page scan finds entries=75  header=75

Index nodes per level of tree structure - [0: 1]

( 2 resource pages )

Internal Index Verify: SUCCESSFUL

The return of ctVERIFY = 0,  75 KEYS FOUND

Verify complete......

Do you wish to perform a low-level tree walk? (Y/N):  n

ctheader - Header Update Utiilty

Operational Model

• Client (ctheader.exe)
• Standalone (ctheader.standalone.exe)

Description

Updates various header fields, allowing for operations such as enabling/disabling particular file features or repairing files with damaged headers.

WARNING: Improper use of this utility can render your file unusable. It should be used rarely and carefully.

Usage

ctheader [-s server] [-u uid][-p pwd] -f filename -m mode -v val

-s: server name (default: FAIRCOMS)

-u: username (default: admin)

-p: password (default: ADMIN)

-f: filename

-m: mode (string). One of the following names:

• ctSERNUMhdr - Set serial number to the specified value
• ctTSTAMPhdr - Set timestamp to the specified value
• ctNUMENThdr - Set number of entries in file to the specified value
• ctTIMEIDhdr - Set creation time stamp used as part of unique ID to the specified value
• ctLOGEOFhdr - Set logical end of file to the specified value
• ctPHYEOFhdr - Set physical end of file to the specified value
• ctDELSTKhdr - Set delete stack pointer to the specified value
• ctUNIQIDhdr - Set unique file ID to the specified value
• ctALIGNhdr - Set file alignment to the specified value
• ctFLAVORhdr - Set file byte ordering to the specified value
• ctXFLSEThdr - Set extended file mode to the lower-order two bytes of the value parameter
• ctXFL_ONhdr - Turn on the lower-order two bytes of value in the extended file mode
• ctXFLOFFhdr - Turn off the lower-order two bytes of value in the extended file mode
• ctEXTSIZhdr - Set file extension size to the specified value
• ctSUSSRLSEGhdr - Suspend the serial segment handling for data file (YES or NO)
• ctREPLICATEhdr - Enable replication for this file (YES or NO)
• ctMAXPARTMBRhdr - Set maximum partitions for this host to the specified value and auto purge as needed
• ctIFIL3hdr - Turn On / Off DEF_MASK_IFIL3 - IFIL resource format change
• ctMXFILZhdr - Set maximum file size to the specified value
• ctLXTSIZhdr - Set large file extent size to the specified value
• ctGUIxIDXENThdr - Turn on/off DEF_MASK_PRTENT (YES/NO)
• ctInsertOnlyhdr - Turn on/off ctInsertOnly (YES/NO)
• ctAugmentedFxdhdr - Turn on/off ctAugmentedFxd (YES/NO)
• ctADD2ENDhdr - Turn on/off ctADD2END (YES/NO)

-v: Update header value (integer in decimal format)

Example

Enable replication:

ctheader -f myfile.dat -m ctREPLICATEhdr -v 1

ctindx - Create index file from flat key file

Usage

ctindx <flat key file> <index file> <index member> [<transformation file>]

Description

This utility runs in single user mode. It supports indexes requiring transaction processing. The index file must already exist, and the index member (0 for the host index, 1 for the first additional index member, etc.) must be empty. The key length of the index member is used to deduce the key length of the flat file. You can optionally specify a transformation file specifying how to transform each key value before entry into the index file.

The optional transformation file is a text file similar to an ISAM parameter file formed as follows:

<# of segments>

<offset> <length> <mode>

... repeated for each segment ...

An offset of zero corresponds to the first byte of the key value stored in the flat key file. The length dictates how many bytes are affected by the transformation. The mode is interpreted as shown in Key Segment Modes in the FairCom DB Programmer's Reference Guide.

ctpkey - Print key utility

Usage

ctpkey <parameter file name> [<# of entries>]

Description

ctpkey prints out 1 or more key value(s), up to the optional # of entries, from each index file in the parameter file, showing how each key segment is defined. The keys are displayed in hex and ASCII. This utility will run in all modes of operation. It is useful if you are having trouble retrieving data. ctpkey will allow you to see how a key value is constructed from the data.

By changing a #define, ctpkey.c can be changed from a main line program to the callable function ctpkey(), with the same parameters as OpenIFileXtd().

ctpotp - Parameter to OTP conversion

Usage

ctpotp <parameter file name> [<user profile bitmask>]

Description

This utility takes a parameter file and produces the corresponding OTP file(s) used by the FairCom Drivers. If no record schema (DODA) is present, a dummy schema is created.

ctptoi - Parameter to IFIL conversion

Usage

ctptoi <parameter file name> [<user profile bitmask>]

Description

This utility opens the parameter file whose name is specified as a command-line argument and writes an IFIL (based upon the parameter file definitions) to each data file referenced in the parameter file. ctptoi is designed for use as a standalone non-server utility.

Note: Before running ctptoi, be sure your files have been created and are in the proper path location as specified in the parameter file being passed into the ctptoi utility.

ctsfil - Superfile contents

Usage

ctsfil <superfile name>

Description

ctsfil lists the members of the superfile, indicating whether each member is an index file, fixed-length data file, or variable-length data file.

Page Size

Default PAGE_SIZE settings are now considered in superfile compact and export utilities, ctsfil and ctsfex. In V11.9.5 and later, this size is 32768 (sect = 256). Prior to V11.9.5, it was 8192 (sect = 64). Server and standalone of these utilities have been updated to use the new default page size. ctsfex supports a parameter for use with superfiles created with different page sizes.

ctunf1 - File Reformatting Utility

Usage

ctunf1 <file name> <new alignment> <new flavor> <confirm> <binflag> [<files>]

Description

ctunf1 reformats a file IN PLACE provided the new alignment restriction does not cause the data record contents to become misaligned. Therefore, FairCom strongly encourages ctunf1 be used only on a copy of your data. ctunf1 takes the place of the UNIFRMAT compile time option; plus it handles data record contents if record definitions have been provided (DODA). ctunf1 is used to port data between different machine architectures.

ctunf1 uses record definitions, if present, to convert the contents of the data records. A record definition is stored as a resource in a data file using the PutDODA() function. In general, the contents of resource records will NOT be converted. Therefore, if you intend to port your files, take care with the resources you directly maintain yourself to ensure they are system independent. However, the resources pertaining to file and record definitions and index alternative collating sequences maintained by FairCom will have their contents automatically converted by ctunf1.

<file name> requires the file extension. For example, to convert a file named cust.dat from Intel to a SPARC platform, issue the following:

ctunf1 cust.dat 4 m
 

files is the optional maximum number of files to open. ctunf1 defaults to 32 files, which should be sufficient for most purposes.

ctunf1 runs in single user mode only. It supports data files, index files and superfiles, and must be executed before the file is moved to the target machine.

In V11, a case was added for handling FCRES_ATTR resource type. Prior to that release, the ctunf1 utility failed with DCNV_ERR (439) error on FAIRCOM.FCS.

ctupdpad - Update the c-treeDB Pad Resource Utility

When importing an ISAM data file into a c-treeSQL database, the c-treeSQL import utility, ctsqlimp, allows specifying the padding and delimiter characters used to pad string fields in a data file. The c-tree Update Pad Resource Utility, ctupdpad, provides a way to change the padding and delimiter characters in the c-treeDB padding resource.

Syntax

The usage of this utility is as follows:

ctupdpad [options] table-name pad-char delimiter-char

Options are any combination of the following:

-s server-name [Default: FAIRCOMS]

-u user-name [Default: ADMIN]

-p password [Default: ADMIN]

The pad-char and delimiter-char values are specified with their corresponding ASCII code values.

Examples

• To set the pad char to space and delimiter to space:

ctupdpad table.dat 32 32

• To set the pad char to space and delimiter to nul:

ctupdpad table.dat 32 0

• To set the pad char to nul and delimiter to nul:

ctupdpad table.dat 0 0

ctvfyidx - Index Verify Utility

The ctvfyidx utility uses the ctVERIFYidx() function to check the integrity of an index file. The client version of the ctvfyidx utility supports the command-line options listed below.

Usage

ctvfyidx [<option> ...] [-u <userid>] [-p <password>] [-s <servername] <file name> [<member #>]

where <option> is one or more of the following:

• -excl - Open the file in exclusive mode1
• -delstk - Check delete stack (on by default)
• -link - Check links (on by default)
• -leaf - Check leaf nodes (on by default)
• -local - causes the utility to use a standalone (local side) connection instead of a client connection when linked with a LOCLIB library.
• -chkkey - Check keys in leaf nodes

1Exclusive mode prevents other users from accessing the file. This is only necessary when a server is being used. If you get an error from ctvfyidx referring to a locking issue (or stating that exclusive mode is needed), re-run ctvfyidx with -excl enabled.

The optional parameter -page size equals sector size * 128 (third parameter in InitCtree()). If page size is not entered, a default value of 16 will be used. filename specifies the index file targeted for analysis. The member # refers to the index member number. A physical index file can contain one or more indexes. Each index has a member number (0, 1, 2, 3, etc.). For example, the sample index file custordr.idx provided with the FairCom ODBC Driver contains a total of two indexes. Depending on whether you specify 0 or 1 you will be looking at either the order number index or the customer number index. rflg represents an optional recovery flag switch and is only applicable when compiled with TRANPROC. Any character will enable rflg, which will result in c-tree skipping automatic recovery.

The ctvfyidx utility defaults to ctREADFIL. It uses ctEXCLUSIVE when the ‑excl option is specified. A ctREADFIL open will fail with error 12 and sysiocod ‑8 if any connection has the file open for write access.

Example

Below is an example of launching ctvfyidx along with output showing the results of the index verification.

# ctvfyidx -2048 custmast.idx 0

Index page scan finds entries=4  header=4

Index nodes per level of tree structure - [0: 1]

Internal Index Verify: SUCCESSFUL

ctvfyidx - Prior to V10.3.1

In versions prior to V10.3.1, ctvfyidx will only work with the ‑excl option when connecting to newer servers. Without the ‑excl option, older versions of ctvfyidx will fail with LERR_ERR.

ctvfyfil - File Verify Utility

The ctvfyfil utility calls the ctVerifyFile() function. (See function for details.) The utility can be run in standalone and in client/server mode.

Usage

ctvfyfil [<option> ...] <file name>

where <option> is one or more of the following:

• <page size> - Use the specified page size
• -chkdat - Read data file only (default)
• -chkdatkeys - Read data file and check keys in index
• -chkdeletedspace - Check deleted space
• -chkidx - Read index file
• -chkidxrec - Read index file and check records in data file
• -chkidxint - Additional index checks
• -excl - Open the file in exclusive mode1
• -int - Interactive mode: stop on each error
• -index=<N> - Check only the Nth index (N=1,2,...)
• -local - causes the utility to use a standalone (local side) connection instead of a client connection when linked with a LOCLIB library.

1Exclusive mode prevents other users from accessing the file. This is only necessary when a server is being used. If you get an error from ctvfyfil referring to a locking issue (or stating that exclusive mode is needed), re-run ctvfyfil with -excl enabled.

The example below shows the utility run on a file called mark.dat with the page size set to 8192:

ctvfyfil -8192 mark.dat