|
|
Positions a KSAM file to a particular record based on a key value.
CALL BKSTART(filenum,status[,keyvalue[,keylocation [,relation ]]])
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.
- filenum
A numeric variable containing the file number that identifies the
file. This number was returned by the last call to BKOPEN. It
should not be altered unless the file is closed with a successful call
to BKCLOSE. (Required parameter)
- status
A four-character string variable to which is returned a code that
indicates whether or not the call to BKSTART was successful and
if not, why not. The first character is set to zero when the call
succeeds, to another value when it fails.
(Required parameter)
- keyvalue
A string or numeric expression whose value is compared to a key value
in this record. The record pointer is positioned to the first record with
a key value that bears the relation specified by relation
to the value in keyvalue. If the value is a string, its
logical length is used for the comparison; otherwise, the physical or
dimensioned length is used. The length of this value must be less than or
equal to the length of the key as specified when the file was created.
If keyvalue is a null string (""), the file is positioned
to the beginning of the first logical record according to the value of
the key in keylocation.
(Optional Parameter)
Default: If omitted, the value assumed for keyvalue is the lowest value
for the specified key type.
- keylocation
A numeric expression whose value indicates the starting character
location in each record of the key used for positioning by
BKSTART. The characters in a record are counted starting with
one. If set to zero, the primary key is assumed.
(Optional parameter)
Default: If omitted, the primary key is assumed.
- 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.
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:
100 DIM A$(10),S$(4)
149 REM <-------- assign null string to keyvalue
150 A$=" "
159 REM <-------- assign alternate key location to keylocation
160 L=21
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 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
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
1220 PRINT "UNABLE TO POSITION FILE TO LEAST VALUED PRIMARY KEY"
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 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
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
|