|
|||
| |CI2 Home|Literature|Support|Documentation|Y2K|Order|License| | |||
 |
Chapter 1 C-Index/II General Information
This chapter is a general guide to installing and using C-Index/II. It covers basic ISAM concepts and specific terminology that will be used throughout the manual. It provides a basis for learning and using all the functions of C-Index/II. We have tried to make C-Index documentation as complete as possible. Before you start working with C-Index, please read the following:
This will save you many hours of effort learning how C-Index works.
Registered C-Index users are entitled to consulting support as detailed in the enclosed information, "C-Index Support Policy and Registration Card". To ensure that you receive assistance from the Trio Systems technical support staff, be sure to return the Registration Card immediately.
Before installing, review the readme.doc file on the distribution disk. It will detail any changes to the installation procedure that may have occurred since this manual was printed. To install C-Index/II under MSDOS, run the "install.bat" batch file supplied on the Source Code Disk. You must run the Install batch file from the disk drive where you want the files installed. For example, to load the entire system onto your C drive (in the \ci2 directory) from the B: floppy drive, you would enter the following:
C>a:install a:
To load onto the C drive from the B: floppy drive, you would enter the following:
C>b:install b:
This will install the C-Index/II source code for all computer systems that are supported. If you do not want to install for all systems, edit the install batch file before running it. Files have been compressed into files using the PKZip format. The PKUnzip program is supplied on disk (under license from PKWare, Inc.). This program can only be run from MSDOS. To complete installation, compile the desired libraries, utility programs and example programs and run the test utilities to verify that the installation was successful. For details on compiling C-Index/II, refer to the section in the readme.doc file for the compiler you are using. You should keep the sources organized in the same subdirectories as on the diskettes in order to take advantage of the make files that are supplied. To create libraries you must install at least the \ci2\src subdirectory and the compiler specific subdirectory that works with your compiler and operating system (for example, the \ci2\msc subdirectory for Microsoft C running under MSDOS). Other subdirectories of interest for all environments are \ci2\util and \ci2\example. If the software was supplied on media for a specific non-MSDOS platform, follow the supplied instructions. Otherwise, to use C-Index/II with an operating system other than MSDOS, you must first install the source code under MSDOS and then transfer the files you need over to the new machine. Refer to the readme.doc file for more details. Indexed Sequential Access Method (ISAM) has become very popular for use in many business systems. It allows information to be retrieved randomly by data value (indexed) and in sorted order (sequential) using just one index file. This dual ability distinguishes ISAM from other methods, such as Hashing. An ISAM file is a file composed of individual pieces of information called "keys". A key is an ASCII string, numeric value, or binary information representing some value in a data record. The index is arranged in such a way that keys can be retrieved both randomly and sequentially, together with their associated data record numbers. This manual assumes that the programmer is familiar with data management techniques. If you are not familiar with this subject, we suggest that your consult the following references in addition to this manual:
The C-Index/II package is written in the C language and is designed to function as a library containing data management functions callable from an application program. Source code is supplied to users for documentation and customization purposes. For instructions on compiling the source code refer to the readme.doc file supplied on disk with the version of C-Index/II you are using.
C-Index/II is a library of C language functions that are linked with the application program. There are no requirements for loading memory resident software in advance of running any application that uses C-Index/II. The required portions of the C-Index/II system are incorporated in the application program by the linking processing. The following sections describe the steps necessary for calling C-Index/II functions. Specifying Compiler and Operating System C-Index/II is designed to work with a wide variety of popular compilers and can be ported to new environments as well. Your application must indicate to C-Index/II which compiler and operating system you are using so that the correct compiler specific header file will be included. For example, the compile line for an application compiled using Microsoft C to run under MSDOS would have the following defines:
-DMSC -DDOS
Alternatively, the application can define these flags before including the cndx.h header file:
#define MSC #define DOS #include "cndx.h"
Refer to the readme.doc file supplied with the source code to determine the correct definitions for the compiler and operating system you are using.
Every program that calls C-Index/II must #include the C-Index/II header file cndx.h:
#include "cndx.h"
This header file includes definitions of all the functions and structures used by your application. Depending on which types of compiler and operating system have been specified, an additional compiler specific header file is included by the cndx.h file. For example, the compiler specific header file for Microsoft C 6.0 under MSDOS is the file \ci2\msc8\cndxmsc.h. Both cndx.h and the compiler specific header file must be accessible to the compiler by moving them to the application directory or adding an include file directory command to the application module. Normally C-Index/II compiler specific header files (for example, CNDXMSC.H for Microsoft C) include additional header files for that compiler (like STDLIB.H, STRING.H, etc). If you want to prevent these from being included in your application, define the label NO_INCLUDES before including CNDX.H. This will suppress the inclusion of compiler header files. C-Index/II consists of a set of functions that are linked into the application program. The functions can open, close, or create a file, and add, delete, and find entries in a file, in addition to other operations. All function calls to C-Index/II must supply a pointer to a structure of type CFILE (called a parameter structure pointer) which holds important information about the file on which the function is operating. On opening or creating a file, a pointer is passed to a structure of type CFILE, and subsequent operations on that open file will also supply the same pointer. For instance the statement:
CFILE datafile;
creates a parameter structure called datafile that can be subsequently used for communication with C-Index/II. For more detail regarding how the psp must be used, consult the C-Index/II Reference Guide. C-Index/II does not compile correctly as C++ code. If you are using it with a C++ application you will link it in as C a language library. To correctly link any C library with C++ code you need to tell the compiler that the routines are C and not C++. This prevents the compiler from "mangling" the library function names. To do this for C-Index/II you would specify the include statement as follows:
extern "C" { #include "cndx.h" };
If your C++ compiler automatically defines __cplusplus (as required by C++ standards), the cndx.h header file inserts the above syntax. Linking C-Index/II with Applications Included in the C-Index/II package are libraries containing all the functions discussed in this manual. C-Index/II is linked in the same way as any library. For example, if you use the Microsoft C compiler, large model, for a program called "myprog.c", linking would look something like this:
link myprog,,,cindexml;
This statement tells the linker to use the C-Index/II library file, cindexml.lib, which was created with the Microsoft large model option. Study the compiler specific make files for the supplied test programs to learn more about how to compile and link for the environment that you are using. A file must be opened for access before any functions can be called. The functions for creating a new file will also leave it open for access. There are various open and create functions. For more detail, consult the individual manual sections describing these functions. The C-Index/II Reference Guide contains descriptions of each function, including information about function usage, calling parameters and likely return codes that the program needs to check. Functions may also return general error codes that are listed in the Appendix of the Reference Guide. The application program must always check the C-Index return code. In any file system, there are a number of problems that can occur such as disk error, out of disk space, etc. C-Index/II internally handles all these problems correctly, but if a program ignores return codes which are reporting errors, serious problems can occur. As stated earlier, a file must be opened before it can be accessed. It is just as important to close the file before exiting the program to insure file integrity. C-Index/II does as much as possible to protect the file, even if it is left open, however, there is no substitute for closing a file properly. Many problems may be encountered with files that have not been closed by the application. For more details, refer to Chapter 5, "PowerFail Protection". C-Index/II has two distinct groups of function calls: multi-key and single-key functions. Each group has its respective characteristics and advantages. The choice of which group to use is best determined by the nature of your application. For example, a typical application will need to manage information in the form of records. Each record will contain several fields with two or more fields acting as "key" fields for retrieving the record. For this type of application, multi-key functions will automatically handle the complex processes of addition, update and deletion of records. Other types of applications may have a requirement for managing information that is not oriented around records. For example, it would be possible to use C-Index/II in an application to store and retrieve the definitions of words in a dictionary. The single-key routines provide a simple and fast way to access information based on one key value. The multi-key functions are a "record" based set of functions. They fully automate the process of managing multi-keyed data records. The application program specifies the definition of the record and key structure. C-Index/II then does all the work of storing and retrieving these records. The method for defining the record structure has been designed to be as flexible as possible. For the majority of applications, the multi-key functions are the best choice. It is suggested that you first examine the multi-key functions to see if they satisfy your needs. The single-key functions operate on objects called "entries". Each entry contains a variable length key, a record number, and variable length data of any format. This set of functions is a more universal data storage scheme that allows the storage, by keyed value, of variable length data up to 30,000 bytes of any format. The multi-key functions were built entirely by using single-key functions. The single-key functions may be seen as flexible building blocks which can be combined and built upon to make any kind of storage system desired. They are also very useful for storing such pieces of information as access codes, system information, and other types of information that are typically used in system development. Single-key functions also are useful when performance optimization is important, such as real-time data acquisition, indexing very large data files and CDROM data retrieval. If the multi-key functions do not offer enough flexibility, the single-key functions should be used. And again, because the single-key functions are the building blocks of the C-Index/II system, it is helpful to be familiar with their general usage. An advanced usage of C-Index/II might include the use of the multi-key functions for record storage and the single-key functions for all else. For more information, see Chapter 7, "Advanced Usage of C-Index/II."
C-Index/II Home Pagewww.triosystems.com © Copyright 1996 - 1999 Trio Systems LLC |