📄 kfs.doc
字号:
an open KFS database using a partial key. If no records
match the partial key, the next record in sequence after
the key requested is returned in the user area and a code
of KFS_Key_Not_Found is returned in KFS_rc.
KFS_ReadGenNumeric
For databases with numeric keys only. Read a record from an
open KFS database. If the requested key is not found, the
next record in sequence after the key requested is returned
in the user area and a return code of KFS_Key_Not_Found is
returned in KFS_rc.
KFS_ReadNext
Reads the record in a KFS database that is the next record
after the key specified.
KFS_Replace
Replaces the record in a KFS database that has the same key
as the one specified. A record with this key must exist in
the database.
9
The File Information Structure
In order to use the Keyed File System routines, you must provide
the KFS functions with a File Information Structure for each
database you are going to use in your program. This is a control
structure (similar to the C "FILE" typedef) that includes such
information about the database as the database name, key length,
location of the key within the record, and a return code field
for checking the result of KFS operations, as well as control
fields used by the KFS functions themselves. Once the database
is opened, this structure should not be modified by the appli-
cation since this may damage the control information used by the
KFS functions and the integrity of the database may be compro-
mised. There is a C typedef named KFS_FILEINFO for this
structure defined in the KFS.H header file provided with the
system. Also present in this header file are the C prototypes
for the KFS functions and the definitions of the KFS return
codes.
To create a KFS database (using the KFS_Create operation), you
must provide several important pieces of information about the
database. This is done by placing the appropriate values in the
following fields in the File Information Structure defined for
the file:
KFS_filename
Required for KFS_Create or KFS_Open, this field must
contain the name of the database being created or
opened. This is a DOS or OS/2 file specification that
includes drive, path, and database name. As mentioned
before the Keyed File System actually creates (or
opens) two files for any KFS database and if these
files are moved, both must be move to the same loca-
tion (ie. subdirectory or floppy disk). The first file
will have the name you specify here, while the second
file will have the same base name as the database you
specified but a qualifier of .PTR.
KFS_keypos
KFS_Create only. This is the position of the key
within the record. This position is relative to 0.
That is, if the key begins in the first position of
the record, 0 is placed here by the programmer. If the
key begins in the 5th position of the record, 4 is put
here.
KFS_keylen
KFS_Create only. This is the length of the key in the
record. For example, if the key went from position 5
through position 10 (ie. 6 characters long) in the
data record, 6 would be placed here. For numeric keys,
this field is ignored.
10
KFS_recsize
KFS_Create only. Place the total size of each data
record, including the key in this field.
KFS_flags
KFS_Create only. These flags specify any special pro-
cessing required for the database. The options
available to you are normal pointer file, small
pointer file, numeric keys, and ignore case. These
options are discussed further in the section "Special
Processing".
Once a KFS database is created, it may be subsequently used by
simply specifying the name of the database in the KFS_filename
field of the File Information structure and using KFS_Open to
open the database. The remaining information about the database
(ie. KFS_keypos, KFS_keylen, KFS_recsize, and KFS_flags) is
stored with the database when it is created.
Upon the completion of a KFS operation, the success or failure
of the operation is determined by checking the return code pro-
vided in the database's KFS_FILEINFO field KFS_rc. The valid
return codes are defined in the KFS.H header file and are docu-
mented in Appendix A of this User's Guide.
11
Parameters to Keyed File System Functions
The are 11 application interfaces that can be called to perform
operations on databases with the Keyed File System. These
operations require 1, 2, or 3 parameters depending on the func-
tion desired.
The first parameter to all of the KFS functions is always the
address of the KFS File Information structure (KFS_FILEINFO) for
the desired database. As mentioned before, once a database is
created or opened this structure should not be changed by the
programmer since it is used by the database system to keep track
of current information about the database. It is also used to
provide feedback to the programmer about the requested opera-
tion.
The second parameter is necessary for the functions that will be
reading data from or writing data to a KFS database. This
parameter is the address of an area large enough to contain a
record from the database (that is, at least KFS_recsize in
length). When a key is required by a specific KFS operation, the
system expects the key to be in this area at the same relative
position, and with the same length, as the key in a record in
the database. For example, to read a record with the key "ABCDE"
for a database whose KFS_keypos = 3, KFS_keylen = 5, and
KFS_recsize = 80 means that the second parameter would be the
address of an area at least 80 bytes in length that contains
"ABCDE" in the 4th, 5th, 6th, 7th, and 8th bytes (ie.
...ABCDE..).
The third parameter is only required on the KFS_ReadGen function
and is the length of the portion of the key provided. This
parameter is discussed further in the discussion of KFS_ReadGen.
The following program segment illustrates how the above param-
eters would be specified for a typical KFS function call:
#include <kfs.h>
KFS_FILEINFO file1;
char recarea[100];
strcpy(file1.KFS_filename, "C:\\MYDIR\\MYFILE.DAT");
KFS_Open(&file1);
if (file1.KFS_rc != KFS_OK)
printf("Error opening file1\n");
strcpy(&recarea[file1.KFS_keypos], "A k");
KFS_ReadGen(&file1, (void *)recarea, 3);
For further examples, see the description of the individual KFS
functions and the KFSSAMP.C program provided as part of this
package.
12
Keyed File System Functions
In the description of the following functions the KFS_File_Error
is a general error caused by an "unknown error" returned from
the operating system and is possible for all functions.
KFS_Add(fs, area)
Add a data record to a database.
Parameters
KFS_FILEINFO *fs
A pointer to a KFS file structure.
void *area
A pointer to a data area containing the record to be
added. The key to be added must be at KFS_keypos of
this area before the operation is issued.
Description
Add a record to the database. Another record with this key
must not already exist in the database.
Required Fields
KFS_filename
Contains the name of an open database where the record
is to be added.
13
Example
/* Add a record to a KFS file */
#include <kfs.h>
KFS_FILEINFO file1;
typedef struct m {
int f1;
int f2;
char mykey[7];
char filler[89];
} MYSTRUCT;
MYSTRUCT inarea;
strcpy(file1.KFS_filename, "C:\\MYDIR\\NUMFILE.DAT");
KFS_Open(&file1);
if (file1.KFS_rc != KFS_OK)
printf("Error opening file1\n");
strcpy(&inarea.mykey, "Newkey");
inarea.f1 = 0; /* Just some data in record */
inarea.f2 = 15; /* Just some data in record */
KFS_Add(&file1, (void *)&inarea);
switch (file1.KFS_rc) {
case KFS_Key_Already_Exists :
printf("Key already in file");
case KFS_OK:
break;
default:
printf("Error adding record");
}
Possible KFS_rc Values
KFS_OK
The record was added successfully.
KFS_Key_Already_Exists
A record with the same key as the record being added
already exists in the database. The operation is
ignored.
KFS_File_Error
An unknown error occurred when attempting to add a
record to a KFS database.
KFS_No_Space_On_Disk
There was not enough space on the disk containing the
KFS file to contain another data and pointer record.
14
KFS_Close(fs)
Close a database.
Parameters
KFS_FILEINFO *fs
A pointer to a KFS file structure.
Description
Close a database. The database must then be opened before
further processing can occur.
Required Fields
KFS_filename
Contains the name of an opened database.
Example
/* Close a KFS file */
#include <kfs.h>
KFS_FILEINFO file1;
.
.
KFS_Close(&file1);
Possible KFS_rc Values
KFS_OK
The database was closed successfully.
15
KFS_Create(fs)
Create a new, empty database and open it.
Parameters
KFS_FILEINFO *fs
A pointer to a KFS file structure.
Description
Create an empty database from the information supplied in
the KFS_FILEINFO structure. At the conclusion of a suc-
cessful operation the database is opened and may be used
without the need to call the KFS_Open function. If a data-
base already exists with this name, an error is returned.
Required Fields
KFS_keypos
Contains the position of the key in the records of the
new database. This position is relative to 0.
KFS_keylen
Contains the length of the key.
KFS_recsize
Contains the size of each of the keyed records to be
built.
KFS_filename
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -