C-Index/II is supplied with a set of utility programs for assisting in program development and file maintenance. These may be distributed with the application in the same manner as the C-Index/II library itself. Full source code is supplied in the \ci2\util subdirectory. You may choose to incorporate portions of this code directly into your application to make the user interfaces compatible with your other application code.

The Compact, and Rebuild utilities will not work with files that have been created with non-string or segmented keys. This is because these utilities need to know something about the keys being processed. They work correctly when the index uses only string keys. If your application needs any of these utilities for files which include non-string and/or segmented keys, you will need to modify the code to work with the types of keys being used. The Goodbad Utility supplied with earlier versions of C-Index has been superseded with the Bcheck Utility.

Rebuild

A rebuild utility is supplied for rebuilding files that have been corrupted in some way. This routine can reclaim most of the data in a file. You will have to determine how to ensure the total integrity of the file after reclamation, but at least this will make the data in the file accessible to your application. The format of the command line is as follows:

rebuild source_file destination_file error_file

The source file is the corrupted file you wish to rebuild. The destination file is the new clean file that is produced. The error file is a C-Index file containing any incomplete entries that are found. Incomplete entries are not added to the destination file. You can manually review error information using the Dump utility. The error_file parameter is optional. If left blank, errors are discarded.

The rebuild file will not skip over unreadable portions of a file. You must create a clean copy of the file using copy (doing an ignore for unreadable parts) or diskcopy (for files on a floppy).

The REBUILD utility uses the bbuild function and _ccheck functions and assumes the following about files to be rebuilt:

If you need to rebuild other types of indexes, REBUILD will need to be modified.

Dump

The Dump Utility allows you to display the full contents of an index file in hex and ASCII. The purpose of this utility is to help identify what is actually in your data file for purposes of debugging your program. It will work only on files that are not seriously damaged.

The format of the command line is as follows:

dump <index file> [MANUAL | SEQ | ALL | TRANS | IMAGE]

where "<index file>" is the name of the file to dump. The optional keywords modify how the information is displayed:

When used in interactive mode (MANUAL) in a multi-user environment, the lock and unlock command allows the entire file to be locked, preventing processes attempting to access the file from making modifications while you are looking at data. Using interactive mode requires understanding C-Index/II internal structures as described in the C-Index/II Reference Guide and general B+Tree concepts.

When used in non-interactive mode (SEQ, ALL or TRANS) the information is output to standard out (stdout) which can be redirected for your convenience to a file, printer, or another program (such as "more"). This may be useful where you do not have a working knowledge of C-Index/II internal processing.

For example, the SEQ option would be useful to determine whether a particular key or record value is being written or read correctly by an application. By redirecting the SEQ dump to a text file, you would be able to view the sequentially ordered key information from your editor, which allows the convenience of being able to search and scroll through the information without understanding how C-Index/II works.

Compact

The Compact Utility will compact the data in an existing index file for the most efficient space usage. The typical size reduction is 25-50%. This utility copies the original file to a new file, writing incomplete records to an error file.

Format of the command line is as follows:

compact source_file new_file error_file

There must be sufficient space on the disk for two copies of the data, or you will need to compact to another disk drive with enough space for the new file.

If the Compact program detects a record number in any index entry that is larger than the next record number in the header, it will reset the header to one larger than the largest found and will issue a warning message:

WARNING: next record number in output file set to XXXX

If you are using the multi-key routines, the number XXXX is the correct number to have in the header and no manual changes are needed to the output file. However, if you are using the single key routines csetrec or cnextrec, you will need to check and see if the value set by the compact utility is correct for your application.

Bcheck

In the event of power failure while C-Index files are open, it is possible for files to become corrupted. One particular type of corruption is caused by the header record not being written to disk by the operating system (even when C-Index does the write operation). In this event, the file may contain node pointers that are incorrect. The side effects are not usually evident until long after the corruption occurs, and there are many different ways that these effects will be seen. The most common reports will be of files that are "out of order" (sequential information is not alphabetic), or records that appear to be lost (even though they may actually still be in the file).

The Bcheck Utility is designed to test for this specific problem. In the event that a problem is reported by the BCHECK program, you can use the Rebuild utility (or bbuild and ccheck functions) to reconstruct the data to a usable condition. For more information about protecting data, refer to the notes in Chapter 5, "PowerFail Protection."

The format of the command line for BCHECK is as follows:

BCHECK <filename>

The program will either report that the file is good, or will display the nodes that are in error, and report that the file is bad.

Another check utility, the Goodbad Utility, is no longer supplied. It has been completely replaced by BCHECK.

Bclear

The Bclear Utility clears the write interrupt flag, which is set when an operation is interrupted by abnormal termination.

The format of the command line for BCLEAR is as follows:

BCLEAR <filename>

Clearing the write interrupt flag does not correct any corruption which may have occurred in the file.

Convert

The Convert Utility reads files in C-Index/Plus and C-Index/PC format and writes them to a new file in C-Index/II format. The command line invocation is as follows:

CONVERT sourcefile newfile errfile

The error file will contain any records that do not pass the ccheck step of the conversion (the same usage as in the Rebuild Utility). See notes below regarding the header conversion utility for incompatible headers.

Header Convert

C-Index/PC and C-Index/Plus create files that are incompatible with the C-Index/II conversion utility if they have been recompiled without the -Zp flag (structure packing). If you have files that were created using previous versions of C-Index that were recompiled without the -Zp option, you will need to run the Header Conversion Utility before running the file conversion utility. HDRCONV changes the incompatible header format to the standard format in the specified file:

HDRCONV filename

C-Index/II Home Page

www.triosystems.com © Copyright 1996 - 1999 Trio Systems LLC

C-Index/II User Guide © Copyright 1983-1997 Trio Systems LLC

User Guide Revision Date: 5/2/96

All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Trio Systems LLC.

Trio Systems is a registered trademark of Trio Systems LLC. C-Index, C-Index/II, SpeedRead, ReadShare and PowerFail Protection are exclusive trademarks of Trio Systems LLC.