isam2.c takes the sample that we started with in isam1.c and adds functionality. The two features added are the ability to list the contents of a file, and Sets.
We have added the function datalist() to sequentially list the records in key order. The first step is to ask if the user wants to enter a string to define a Set. This is discussed in the next section of this chapter. For now let us assume that the user just presses the Enter/Return key, which makes the program call the doall() function.
The process that we want to perform is to find the first key in the index, display the record that it represents, and find each successive key in turn. To start the process we use FirstRecord(). It finds the first key in the index specified. If passed the data file number as the parameter, it finds the record that is physically the first in the file. FirstRecord() reads the record associated with the key into the buffer specified.
After we display the record, we are ready to locate the next record in key sequence. We use NextRecord() for this, again passing the number of the index file. NextRecord() finds the next record in key order, in relation to the last record found. We continue in a loop until NextRecord() returns an error value of INOT_ERR (101), which signifies that we have reached the end of the file.
A Set is a group of records that have keys matching a certain target. For example, an index contains the following keys:
CASE DISKCASE DISKDRIVE DISKETTE KEY KEYBOARD KEYCAP
We could define a Set by the target DISK. This set would contain the values:
DISKCASE DISKDRIVE DISKETTE
In the function datalist() we ask the user for a string to define a Set. If the user enters nothing we list the entire file, as described above. If a string is entered we use this to define a Set and call the function doset(). This function is nearly identical to doall(). It finds the first key in the index, displays the record, then goes through the index sequentially. The difference is it starts with the first key beginning with the Set string and ends with the last key starting with the Set string.
Instead of starting with FirstRecord(), we use FirstInSet(). It performs the same function, but FirstInSet() asks for a target key, and the number of characters to match. In our example, the input value is passed through TransformKey() to make it a perfectly formed key. The length parameter is the length of the input target key. For example, if we had the keys that we show above, we could enter the target key DISK, with a length of 4. FirstInSet() finds DISKCASE as the first key of the set.
To go on to the next key we use NextInSet() instead of NextRecord(). It performs the same function, but stops when the last key that matches the Set is found. For example, it tells us we reached the end of the file (INOT_ERR) after DISKETTE.
Do not pass the Set target to NextInSet(). This information is stored by FairCom DB. It also means that you can only process one Set at a time. Get around this by switching from one set to another with ChangeSet().