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 altemate 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 to the record with the lowest key value in the selected key.
USING BKSTART |
 |
After calling BKSTART, you should check the status parameter to determine if the procedure was executed successfully. If successfully executed, 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 exact same key value as that specified in the BKSTART call. When found, the pointer is positioned to that record. 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. For example, in a key containing a date in the form yymmdd, by specifying only the first two characters as keyvalue and a relation = 2, you can position to the first record with a key for that year; by specifying the first four characters, you can position to the first record for a particular year and month.
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:
100 DIM A$(10),S$(4)
150 A$=" " <------------------- assign null string to keyvalue
160 L=21 <--------------------------- alternate key location to keylocation
170 CALL BKSTART(F,S$,A$,21)
|
The default for relation is 2 (greater than or equal to) and need not be specified except for documentation purposes.
Figure 6-8 “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 6-8 Positioning Pointer to Least-Valued Record with BKSTART
1080 REM *******************************************************
1090 REM * POSITION TO LEAST VALUED PRIMARY KEY *
1100 REM *******************************************************
1110 REM
1120 REM F IS THE FILE NUMBER OF A KSAM FILE
1130 REM OPENED BY A CALL TO BKOPEN
1140 REM
1150 CALL BKSTART(F,S$)
1160 REM
1170 REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED
1180 REM
1190 IF S$[1;1]<>"0" THEN DO
1200 REM N$ CONTAINS THE NAME OF THE KSAM FILE
1210 REM S$ CONTAINS THE STATUS CODE RETURNED BY THE PRECEDING CALL
1230 PRINT "ERROR ";S$[1;1]," DETAIL";S$[2]
1240 CALL BKERROR,(S$,M$)
1250 PRINT M$
1260 GOTO 3620
1270 DOEND
1280 REM
1290 REM THE PROGRAM CONTINUES
1300 REM
|
The example in Figure 6-9 “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 6-9 Positioning Pointer to Particular Record with BKSTART
1920 REM
1930 REM ***************************************
1940 REM * POSITION A KSAM FILE *
1950 REM ***************************************
1960 REM
1970 REM F IS THE FILE NUMBER OF A KSAM FILE
1989 REM OPENED BY A CALL TO BKOPEN
1990 REM
2000 REM AN ASSUMPTION HAS BEEN MADE THAT THE POSITIONING TO BE
2010 REM DONE IS TO THE RECORD WRITTEN IN THE WRITE EXAMPLE,
2020 REM AND THAT THE DESIRED KEY STARTS AT CHARACTER 2.
2060 REM
2070 CALL BKSTART(F,S$,"23",2,0)
2080 REM
2090 REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED
2100 REM
2110 IF S$[1;1]<>"0" THEN DO
2120 REM N$ CONTAINS THE NAME OF THE KSAM FILE
2130 REM S$ CONTAINS THE STATUS CODE RETURNED BY THE PRECEDING CALL
2140 PRINT "UNABLE TO START ";N$;" ERROR ";S$[1;1];" DETAIL ";S$[2]
2150 CALL BKERROR(S$,M$)
2160 PRINT M$
2170 GOTO 3620
2180 DOEND
2190 REM
2200 REM THE PROGRAM CONTINUES
2210 REM
|
