|
|
Using KSAM XL: 900 Series HP 3000 Computer Systems > Appendix B BASIC/V IntrinsicsBKSTART |
|
Positions a KSAM file to a particular record based on a key value.
By calling BKSTART, you can position the record pointer to any record in the file based on the value of a key in that record. The key can be the primary key or any alternate key, since BKSTART also allows you to select the key for positioning and for subsequent sequential reads. If you want to read all the keys in a key sequence, you can use BKSTART to position the pointer to the record with the lowest key value in the selected key.
After calling BKSTART, you should check the status parameter to determine if the procedure was executed successfully. If successful, the record pointer is positioned at the beginning of the first record with a value at keylocation that has the relation specified in relation to the value specified in keyvalue. If default values are assumed for all three optional parameters, the pointer is positioned to the record with the lowest value for its type in the primary key location. If the relation specified is equality (relation = 0), then a record must be located that has the same key value as that specified in the BKSTART call. When the record is found, the pointer is positioned to it. If duplicate values are allowed for the key, then the pointer is positioned at the first record with the particular key value. When the specified relation is greater than (relation = 1), the file is searched until a record is found with a key value greater than the specified key value. The search passes over any record with a key value equal to the specified value. This relation allows you to retrieve items by an approximate key. Thus, if you specify a key value of "R", a call to BKSTART will position the pointer to the first record with a key value that starts with the letter R. A subsequent series of calls to BKREAD allows you to read the remaining records in the file or, by including a test, to read only the records beginning with R. When the specified relation is greater than or equal to (relation = 2), BKSTART looks for a record containing a value equal to the specified value. If found, it positions the pointer to that record. If not found, it continues looking and positions the pointer to the first record that is greater than the specified value. This type of search can be used to locate records by generic key. A generic, or partial, key is a value that matches characters at the beginning of the key, but not necessarily the end. Whenever a record cannot be found with a key that satisfies the relation and value specified, the value 23 for invalid key is returned to status. BKSTART allows you to specify a key other than the primary key assumed by BKREAD. Called prior to a series of calls to BKREAD, it prepares for a sequential read of the file in alternate key order. For example, assuming a file with an alternate key in location 21, the following call positions the pointer to the first record in that key sequence:
The default for relation is 2 (greater than or equal to) and need not be specified except for documentation purposes. Figure B-10 “Positioning Pointer to Least-Valued Record with BKSTART” illustrates the use of BKSTART with default values for all optional parameters. Specified in this minimal form, it positions to the least valued primary key. Figure B-10 Positioning Pointer to Least-Valued Record with BKSTART
The example in Figure B-11 “Positioning Pointer to Particular Record with BKSTART” positions the record pointer to a record containing a specific key value. The value is 23; it is located starting in the second character of each record. The value for relation is zero indicating that the key must contain exactly the value 23, not a value larger than 23. Figure B-11 Positioning Pointer to Particular Record with BKSTART
|
|