The following notes cover common problems encountered using C-Index. Additional information can be found in the readme.doc file supplied with the software release.

Compilation Issues

Required Compilation Definitions

C-Index/II uses compilation definitions to control which compiler specific header file to include when compiling your application. The following are examples of flags to specify which compiler and which operating system is being used:

For example, to compile for Borland C under MSDOS, insert the following two defines to the command line compilation statement in your make files:

To compile for Microsoft C version 6 and above under MSDOS, insert the following two defines to the command line compilation statement in your make files:

To compile for Borland C under MS Windows (linked in as a DLL), add the following two defines to the command line compilation statement in your make files:

For the complete command line for compiling an application, refer to the readme.doc file supplied with C-Index/II and study the example program make files for each compiler.

Code Size

The size of the C-Index code will vary depending on the memory model being used and the number of modules that are required by your application.

The code size for the large model is about 50K. Static memory usage is about 5K. Global memory used depends on the number of buffers allocated (default is 10) and the number of indexes accessed (about 250 bytes per index). Each file that is open uses a parameter structure which occupies about 700 bytes each.

Protecting Data

Always design a file backup procedure for your applications to protect data from being lost for any reason. This includes protecting against everything from fire and theft to power failures while running the program. The C-Index package includes many features to protect your data and to help recover information in the event of power and hardware failures. However, it is impossible for a generalized filing system such as C-Index to completely prevent loss of information.

Data integrity is a complex problem that goes well beyond what we can cover in this document. We do have several suggestions, however, that can make a significant difference in the event that you do have problems with your files:

1. Always make backups after major changes to your files.

2. Always use a rotating backup system (that is, never backup over your backup files). This will prevent the problems caused by system failure during backup (where you end up with two useless copies of information).

3. Keep archival copies of files at regular intervals so that you will never have to recreate an entire file system from scratch.

4. Close and then reopen files in your application whenever sensitive information has been added. This is slow, so you may only be able to do this at major stopping points, such as when returning to a menu after adding or updating a series of records. If you change the default data integrity level to a lower value, be sure the application flushes the buffers to disk as often as possible.

5. Advise the end user of your program on correct procedures for operating the computer. In particular make sure that they are aware that they must exit the program before turning the computer off (assuming you have files open). Also we have had problems with end users failing to observe and report serious hardware failures until their files were beyond recovery. End users must be advised the messages such as "Abort, retry, or ignore?" or "Parity Error" indicate very serious failures of the hardware.

6. Try to keep your file system design simple. The more interrelated files that depend on each other for completeness and accuracy, the greater chance that something may go wrong.

7. Create an archiving utility for your application that stores the data in an ordinary text file, and allows the recreation of the file from the text archive.

8. Utilize the PowerFail Protection features to protect the data from abnormal termination.

9. Incorporate recovery procedures into the application that end-users can invoke without special assistance. A variety of functions are provided in C-Index/II for recovering data. These must be combined with application specific recovery to create a complete solution. See Chapter 5, PowerFail Protection.

Example Database Application

To help you learn how C-Index can be used in applications, we have included the database application called "Example". This program simulates typical actions in a database oriented application and demonstrates operation of all the multi-key functions.

Studying the Example program in combination with reading the manual will make the process of learning C-Index faster and more enjoyable. Running the Example program allows you to interactively see on the screen how each multi-key function works.

PARMERR Using Multi-Key Routines

If you get a return code of PARMERR (-2) when using the multi-key routines, this may be caused by failing to allocate a large enough buffer for your records in the dbopen function. Refer to the discussion of this in the section "The Data Record Buffer" in Chapter 2. Be sure to leave at least enough room in the work buffer for your largest record to avoid errors.

Compatibility with Other Libraries

C-Index/II is compatible with a wide range of other third party C libraries. Some incompatibilities can arise for the following reasons:

• Some vendors of C libraries choose to compile the libraries with structure packing turned on (byte alignment), and some choose to compile with it turned off (word alignment). The supplied C-Index/II make files are set up to use the default setting for the compiler. For example, the default setting for Borland C/C++ is to pack structures (byte alignment). The default setting for Microsoft C/C++ running under MSDOS is to word align structures. Microsoft Windows requires structure packing turned on (byte alignment). If you are using another library that requires structures to be aligned in a different manner, you will have to either recompile C-Index or the other library to make the packages compatible when linked with your application. Refer to the compiler specific notes for instructions on recompiling the source code.
• Some libraries have been found to have a global variable name that is the same as C-Index/II. This will usually be detected by the compiler and reported as a duplicate symbol.
• Some libraries use define statements in their include files that conflict with those in C-Index/II. This will usually be detected by the compiler. The best solution is to keep your application code segmented in such a way that routines that need to include the C-Index/II headers will not also need to include headers from other libraries. If this is not possible, you can modify the code in C-Index/II or the conflicting library.

Datalist Problems

Probably the most common multi-key error is an invalid datalist definition. This is usually caused by omitting some part of a field's definition, or by giving an invalid type for some part of the datalist. To avoid errors, consult the reference section on the multi-key routines for all allowable types. In addition, be sure to define the last field in the datalist as ENDLIST, or C-Index/II will not know where the end occurs.

Another error can occur if the pointer to the field is incorrect. On dadd, C-Index/II performs some checks for valid data in the fields. If a string field points to memory containing a null terminated string (or random data) that is longer than the specified field length, an error BADFLDLEN (-26) will be returned. On dread, C-Index/II stores the found data in the areas pointed to by the datalist. If the pointers are wrong, memory can be corrupted and can cause very serious errors.

It is essential to check the return code of all C-Index operations to ensure that errors of this type are trapped by your program. In some cases, the nature of the problem with the datalist definition will not be obvious. The best approach to finding problems of this type is to print out the contents of the datalist and the fields the datalist points to, just prior to the C-Index function call that is indicating an error. With this information, you should be able to find the reason the datalist is not accepted by C-Index. If this approach does not reveal the problem, the next step is to use the debugger to locate the line in C-Index/II which returns the error, as described in the next section, "Unexplainable Error Conditions."

Unexplainable Error Conditions

On occasion it may be difficult to figure out why C-Index is indicating an error condition. If you do a thorough evaluation of your application and still are not able to find the answer, there is one more step to finding what the problem is. By recompiling the C-Index libraries with source code debugging information, it is relatively easy to locate the place in the C-Index code where the error is occurring.

To recompile the libraries with debugging information, modify the make file for your compiler to include the debugging flags. For example, with Microsoft C the required flags are -Zi and -Od. These are already in the supplied make files, but may be commented out on the distributed version. After modifying the make file, recompile the entire library following the instructions in the readme.doc file supplied with the source code.

Next, search the C-Index source code for occurrences of the error definition that is being returned by the program. The easiest way to search is with grep or fgrep utilities, but you can also use an editor. Be sure the source files in both the \ci2\src subdirectory and the compiler specific subdirectory (such as \ci2\msc for Microsoft C). Now that you know the line numbers of these occurrences, you can run your application with the debugger with breakpoints set at each occurrence. The program will break at the position in C-Index where it has found a problem with your application. By studying the comments around this part of the code, you should be able to figure out what is causing the error condition.

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.