C-Index/II is transportable to any ANSI C compiler. The code depends on a few of the library routines normally provided with C compilers. For functions that vary between compilers, the source files must be changed for each compiler to accommodate the differences.

While the C language affords a large degree of source code portability, there are many small differences between compilers. These differences include variance in the specification of library functions, bugs in library functions, and bugs in the compilers themselves. For this reason, caution is advised when transporting C-Index to new compiler environments. Every effort has been made to make this as simple as possible. A file dump utility and index testing utilities are provided to verify that the program has been transported successfully (see the Chapter "C-Index/II Utility Programs").

Installing Source Files

Install the complete C-Index/II package using the supplied installation batch file. Choose one of the supplied compiler sources as the starting point for converting to a new compiler and/or operating system. The Microsoft C/C++ MSDOS files (in the \ci2\msc6 subdirectory) and Unix files (in \ci2\unix5) contain the most extensive comments, however other versions may be helpful.

Copy all the files for the supported compiler into a new subdirectory. Then modify the source code and make files to be compatible with the new system.

The files "cndxXXXX.c" and "cndxXXXX.h" (where XXXX is specific to the compiler) contain the compiler dependent source code. For example, cndxtc.c and cndxtc.h are for the Borland C compiler and cndxmsc.c and cndxmsc.h are for the Microsoft C compiler.

File I/O Library Usage

Most ports of C-Index/II are supplied using the Unix style I/O library routines:

It is possible to modify the file I/O functions to use other types of operating system functions, however, the file functions must allow the processing of blocks of records (nodes) in "non-translated mode". That is to say, the file functions do not make any modifications to the stored or retrieved information, treating it as binary information.

Multi-User Considerations

Most ports of C-Index/II depend of the operating system supporting Unix style byte level record locking. Availability of this operating system feature will significantly simplify porting C-Index/II. If the operating system does not support record locking and the application will be operating in EXCL (single-user) mode, the C-Index multi-user code can simply be disabled. An example of this would be the IBM370 port.

Compiler Specific Additions

It is possible in the process of porting the code that some functions we rely on from the compiler library will either be missing, or operate other than expected. For example, some compilers do not support the stricmp (case insensitive string compare). If you find that your compiler is missing any of these functions, you can add the missing functions or modify the compiler specific code to conform with the compiler library.

Making a Single-User Version

If your compiler does not support byte level record locking, then you may choose to port C-Index as a single user library. The compiler specific C code requires two changes to accomplish this. First, change the mtstos function to return FAIL. This tells C-Index that the operating system cannot perform multi-user processing. Then comment out all source lines referring to the locking or lockf functions. These functions will never be called, since the system knows that it cannot do locking. Do not remove the functions which contain the locking or lockf functions, such as the lockbyte function, since these will be needed to resolve external references from other parts of the C-Index code that you will not be modifying.

Batch Files

The following batch files are supplied for the Microsoft C/C++ compiler. Similar files are supplied for the other compilers and operating systems.

Each batch file contains a batch script to compile the source files for that compiler. It may require changes for differences in make utilities and operating system shells.

Make Files

The following make files are supplied for the Microsoft C/C++ compiler. Similar files are supplied for the other compilers and operating systems.

These are make files referenced in the above mentioned batch files and may require changes for differing make utilities. Systems which support a Unix style make utility are supplied with a single make file, named "makefile".

C-Index/II Application Header File

The \CI2\SRC\CNDX.H file contains the definitions required to compile application modules. CNDX.H includes a compiler specific header file, such as CNDXMSC.H for Microsoft C running under MSDOS.

NOTE: This differs from C-Index/Plus and C-Index/PC where the CINDEX.H header file includes a CINDEXSB.H header file and compiler specific header files are not needed.

The compiler specific header file to include is determined by two #define statements in the application module (or the application module make file). The defines must be specified for both the type of compiler and the operating system. Some examples:

When creating a new compiler library, CNDX.H will need to be modified to include the new compiler header file based on new compiler defines.

Compiler Specific Header and Source Code Files

These files are supplied for all the supported compilers. The Microsoft C files contain the most extensive set of options and comments:

The compiler specific header file contains all the information for compiling both the compiler interface code and the rest of the C-Index/II library. The compiler specific source code file contains the functions required to interface with a specific compiler/operating system library.

All functions in the compiler specific code include the parameter structure pointer (psp) as a parameter to the function. In the parameter structure is a special pointer variable, portinfo, which can be used to point to compiler specific information needed between function calls. Using information pointed to by portinfo allows for more flexibility in accommodating unusual compiler or operating system requirements. Also, there is a customizable variable called portlong in the psp. This feature will continue to be supported in all future releases. We recommend that you use the portinfo and portlong variables instead of modifying the psp itself to make updating to future C-Index releases easier.

Testing Procedures

The following source files contain the test programs needed to verify correct operation of C-Index after porting to a new system or compiler. These routines display each test step as it is being run. Since error messages are interspersed with information about the current step, it is a good practice to redirect the output of these tests to a temporary file for review after the test has completed.

Test1 is the most basic test of the system. It uses single-key routines to add, find and delete small fixed length records.

Test2 tests the multi-key routines. Each record contains the basic data types and multiple indexes.

Test3 is a single-key test that uses larger variable length records.

Test4 is the same as Test2, except that it is designed to be run by multiple processes at once to test correct operation of the network or multi-user operating system.

Test5 simulates the addition of key values to an index in sequential order using the single-key routines. The keys are null strings with the long record number supplied as an incrementing value.

Test6 is similar to Test1 except that the key values being generated are using all of the built-in key types, binary, integer, floating point, etc.

Test7 is similar to Test2 except that all the new key types are tested. Run it on a single process.

Additional tests may be included on the distribution disk, however they are not intended for use in porting C-Index and can be ignored if they are not documented here.

The make files supplied for creating C-Index tests append the model name to the end of the test name during linking to simplify testing with multiple model libraries. For example, Test1 is linked as TEST1L.EXE.

After compiling and linking these tests, run Test1, Test2, Test3, Test5, Test6 and Test7 as single-user tasks. Then run Test4 on many tasks at once (from a common directory so that they will all share the same test.fle file).

If these tests pass without displaying errors, the new libraries are working correctly. Always be sure to re-run the tests after recreating the C-Index libraries.

Tailoring the Source Code

It is also possible to modify the compiler independent parts of C-Index/II to add features not supplied in the standard system. The source code is well commented, and with careful study, you can learn in detail how the system works. However, there are many interlocking parts to the program, and changing the source should only be done with great care and by programmers who have extensive C programming experience. If any changes are made, the test programs should be recompiled and run to insure the system is operating properly.

Only the shipped version of the source code is supported by Trio Systems. However, if you are creating a custom version of C-Index, Trio Systems may be able to assist you on a consulting basis.

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.