HP 3000 Manuals HP 3000 Manuals
BKSTART
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 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.
PARAMETERS
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 can succeeds, to another value
when it fails. (Refer to the Status Parameter
discussion earlier in this section.) (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 hey 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 1. 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)
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.
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 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.
____________________________________________________________________________
| |
| 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 |
____________________________________________________________________________
Figure 6-8. Positioning Pointer to Least-Valued Record with BKSTART
The example in Figure 6-9 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."
__________________________________________________________________________
| |
| 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 |
__________________________________________________________________________
Figure 6-9. Positioning Pointer to Particular Record with BKSTART