📄 kfs.doc
字号:
KEYED FILE SYSTEM - User's Guide
Version 2.0 (DOS and OS/2 1.x)
(c) 1993 APT Computer Solutions, Inc.
Table of Contents
Introduction 1
System Components and Requirements 2
System Requirements 2
Keyed File System Components 2
Keyed File System Restrictions 2
Including KFS Routines in Your Program 4
What Are Keyed Files 5
Keyed File System Functions 7
The File Information Structure 8
Parameters to Keyed File System Functions 10
Keyed File System Functions 11
KFS_Add 11
KFS_Close 13
KFS_Create 14
KFS_Delete 16
KFS_Open 18
KFS_Read 19
KFS_ReadFirst 20
KFS_ReadGen 21
KFS_ReadGenNumeric 23
KFS_ReadNext 25
KFS_Replace 27
Interdependencies of the KFS operations 29
Special Processing 30
KFS_Small_PTR 30
KFS_Numeric_Key 30
KFS_Ignore_Case 31
Programming Hints and Tips 32
Data Recovery 34
Appendix A - Keyed File System Return Codes 35
Appendix B - File Recovery Example 37
3
Introduction
The Keyed File System is a set of routines that allow you to
write programs in C to build and maintain databases on a PC that
are logically organized by a user defined key. Records can be
read or written directly using an alphabetic or numeric key. An
alphabetic key can be a string consisting of any combination of
ASCII characters up to 32,767 characters in length. You may also
have 4 byte signed numeric keys contained in the normal Intel
80x86 long integer format. Note that a database may have alpha-
betic keys or numeric keys but not both (however, see
"Programming Hints & Tips" for hints about combining keys).
The Keyed File System uses normal DOS and OS/2 functions to
create and maintain its databases. Therefore, records may be of
any length supported by the DOS or OS/2 operating systems and
can be created using the FAT or HPFS (OS/2 only) file systems.
Files may be created on floppy or hard disks, although, as might
be expected, hard disk files will provide better performance.
KFS databases may be moved or copied using normal DOS or OS/2
commands (such as COPY) as long as both file components are
moved together (see "Copying Files"). Additionally, databases
built using the KFS functions on one operating system are com-
patible with databases built using the KFS functions on the
other operating system. Thus, databases built by programs run-
ning under DOS may be subsequently used by programs running
under OS/2.
The Keyed File System supports most operations normally associ-
ated with keyed files:
* Direct reading and writing of records by key.
* Sequential reading of records in key sequence.
* Deleting of records by key.
* Reading records using a partial key.
4
System Components and Requirements
System Requirements
The minimum system required to run programs that use the
Keyed File System are:
* OS/2 1.2 or higher, or DOS 3.3 or higher.
* Approx. 180K of disk space including sample programs and
utilities.
* Microsoft C compiler and libraries, version 6.0 (OS/2 and
DOS) or 7.0 (DOS only).
Keyed File System Components
KFS.H - The header file for use in C programs that
want to use KFS functions.
KFSMSC6O.LIB - A lib used at linkedit time to include the
KFS functions when building OS/2 programs
written in Microsoft C Version 6.0.
KFSMSC6D.LIB - A lib used at linkedit time to include the
KFS functions when building DOS programs
written in Microsoft C Version 6.0.
KFSMSC7.LIB - A lib used at linkedit time to include the
KFS functions when building DOS programs
written in Microsoft C Version 7.0.
KFSSAMP.C - A sample program that builds a KFS database
from a sequential file and then uses most of
the functions available in KFS.
KFSSAMP.DAT - The sequential input file to the KFSSAMP
program.
KFSSAMP.MAK - A sample make file for KFSSAMP.C.
Keyed File System Restrictions
The following restrictions apply to KFS databases:
* Databases must contain fixed length records.
* Each record must be at least 5 bytes in length.
* Numeric keys must be 4 bytes in length but alphabetic keys
may be up to 32767 characters in length.
* Duplicate keys are not allowed (see "Programming Tips and
Techniques").
* The path and file name specified during KFS_Create or
KFS_Open for a KFS database cannot be longer than 63 bytes.
5
* Files cannot be created using KFS_Open, you must use
KFS_Create to create a new file and KFS_Open after a file
exists.
* Two databases with the same "base" name cannot exist in the
same directory even if the file extensions are different.
That is KFS databases with the base names of MYFILE.001 and
MYFILE.002 cannot exist in the same directory, but the
names MYFILE1.XXX and MYFILE2.XXX are OK. This is explained
further in the section "What Are Keyed Files".
* You cannot name a KFS database using the extension of .PTR.
Thus MYFILE.PTR is invalid. This is also explained in the
"What Are Keyed Files" section.
6
Including KFS Routines in Your Program
To include the KFS routines in your C program requires three
steps:
1. Include the KFS.H header file at the beginning of your
program source. For example:
#include <KFS.H>
2. Define any keyed files using the KFS_FILEINFO typedef. For
example:
KFS_FILEINFO keyedfile;
3. Include the appropriate KFS---.LIB file when linking your
program. For example, to link a DOS program compiled with
MS/C version 6.0 would be:
LINK myprog,,,KFSMSC6D;
For a complete example of a program using some KFS functions,
look at the KFSSAMP.C file included with this package.
7
What Are Keyed Files
Keyed File System databases are actually composed of two files,
an index file and a data file. These two files work together to
provide you with direct access of a record by key while keeping
the records in a logical keyed sequence. The name of the data
file is the same as the name of the database and is specified by
the programmer when the KFS database is created (using the
KFS_Create function). This may be any valid DOS or OS/2 file
name. The index file is automatically given the same base name
you specified for the database but with an extension of .PTR.
For example, specifying a name of CUSTOMER.DAT for a database
automatically causes the creation of an index file with the name
of CUSTOMER.PTR. This leads to two restrictions in the Keyed
File System:
1) You cannot name a database using an extension of .PTR.
2) You cannot have two databases in the same directory with
the same base name since this would result in an attempt by
KFS to create duplicate .PTR files. For example, MYFILE.001
and MYFILE.002 would both result in KFS attempting to cre-
ate an index file named MYFILE.PTR.
Because these two files work together they must remain physi-
cally in the same directory. Therefore, if the Keyed File System
database is moved, both the data and index files must be moved
together.
The format and content of the index file is determined by the
Keyed File System, while the format and content of the data file
is determined by you when the database is created. When you
create a Keyed File System database you must tell the Keyed File
System how large each record in the database will be
(KFS_recsize), where the key begins in the record (KFS_keypos),
and how long the key is (KFS_keylen). Note that the Keyed File
System only supports fixed length records (ie. each record in
the database is the same length).
The Keyed File System requires that databases are either created
or opened before they are used, and that they are closed before
the program terminates. With any file system, if a program ter-
minates abnormally without closing files (such as a system crash
because of a power failure) and file buffering is being used
(such as is available with HPFS or DOS lazy writing), data that
has been "written" by the program but waiting in an output
buffer to be physically written to disk may be lost. The Keyed
File System makes every attempt to minimize the impact of such a
system failure, but since it does utilize two files working
together, there are rare times this loss of data may result in
the database becoming unusable. Thus special care should be
taken by your application user to properly back up the data and
index files making up each KFS database. Also, see the section
on "Data Recovery" for an example of how to recover a damaged
KFS database.
8
Keyed File System Functions
The Keyed File System is a set of 11 routines that provide you
with the basic functions required for keyed record access on the
PC. These functions are:
KFS_Add
Adds a new record to a KFS database. The key of the record
being added must not already exist in the database.
KFS_Close
Close an open KFS database.
KFS_Create
Create and open a new KFS database. The database must not
already exist.
KFS_Delete
Deletes the record from a KFS database that has the key
specified.
KFS_Open
Open an existing KFS database.
KFS_Read
Read a record from an open KFS database by key.
KFS_ReadFirst
Reads the first logical record in a KFS database.
KFS_ReadGen
For databases with alphabetic keys only. Read a record from
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -