Using KSAM/XL and KSAM 64 (32650-90886)

256 AppendixB
BASIC/V Intrinsics
BKSTART
relation A numeric expression whose value specifies the relation between the
specified
keyvalue and the value of the key at keylocation . The record
pointer is positioned to the first record with a key value satisfying this
relation:
0 The value of the record key is equal to
keyvalue
1 The value of the record key is greater than keyvalue
2 The value of the record key is greater than or equal to
keyvalue ( default ).
>2 Any value greater than 2 is treated as if it were 2.
(
Optional parameter )
Default If omitted, the relation is assumed to be 2,
record key is
greater than or equal to the
keyvalue .
Operation Notes
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: