HP 3000 Manuals HP 3000 Manuals
BKREADBYKEY
Transfers record identified by particular key value from KSAM file to
BASIC program.
CALL BKREADBYKEY(filenum,status,keyvalue,keylocation,parameterlist)
A call to BKREADBYKEY locates and reads a record into a storage area
identified by a list of variables in the BASIC program. The record to be
read is located by matching the specified keyvalue with an identical
value stored in the record starting at keylocation. The record value and
the value specified in keyvalue must match exactly, or an error code is
returned to status. To use BKREADBYKEY, the file must be open in an
access mode that allows reading.
You cannot use BKREADBYKEY to locate a record by generic or approximate
key values. For this purpose you can call BKSTART followed by a call to
BKREAD. (Refer to the discussion of BKSTART.)
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
BKREADBYKEY was successful and if not, why not. The
first character is set to zero if the call succeeds, to
another value if not. (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 the record. The record pointer is
positioned to the first record with a key value at
keylocation that is exactly equal to the specified
keyvalue. In order to match exactly, the record value
and keyvalue must have the same logical length.
(Required parameter)
keylocation A numeric expression whose value indicates the starting
character position in each record of the key used to
locate the record to be read by BKREADBYKEY. The
characters in a record are counted starting with 1. If
the value of keylocation is zero, the primary key is
assumed. The primary key also may be specifically
indicated by its location in the record. (Required
parameter)
parameterlist A list of variables separated by commas into which the
data in the record is read. The contents of the record
are read into the variable (or variables) until the
physical length (or combined physical lengths) of
parameterlist is exhausted, or until the end of the
record is reached. (Required parameter)
USING BKREADBYKEY
After calling BKREADBYKEY, you should always check the status parameter
to determine whether the read was successful. Upon completion of
BKREADBYKEY, the variables specified in parameterlist contain data read
from the record located through the keyvalue andkeylocation parameters.
The key value in there cord to be read must exactly match the specified
keyvalue. Unlike BKSTART, the only relation between the value in the
record and the value in the call is that of equality. If duplicate key
values are allowed in the key being sought, then the first record with a
matching key value is read by BKREADBYKEY. To read the remaining records
with duplicate key values, you should use BKREAD.
NOTE Each variable in parameterlist is filled to its current physical
length before proceeding to the next variable.
The example in Figure 6-6 uses BKREADBYKEY to read the first record found
with the value "23" starting in byte 2. Since this is the file written
by BKWRITE in Figure 6-11, the records in the file are identical
including the keys and only the first record is read.
_______________________________________________________________________________________
| |
| 2220 REM ***************************************************** |
| 2230 REM * READ BY KEY FROM A KSAM FILE * |
| 2240 REM ***************************************************** |
| 2250 REM |
| 2260 REM F IS THE FILE NUMBER OF A KSAM FILE |
| 2270 REM OPENED BY A CALL TO BKOPEN |
| 2280 REM |
| 2290 REM AN ASSUMPTION HAS BEEN MADE THAT THE RECORD TO BE READ |
| 2300 REM CONTAINS THE SAME INFORMATION THAT WAS WRITTEN IN THE |
| 2310 REM WRITE EXAMPLE. |
| 2320 REM |
| 2330 REM AN ADDITIONAL ASSUMPTION IS THAT THE DESIRED KEY VALUE |
| 2340 REM STARTS AT CHARACTER 2 AND HAS THE VALUE "23". |
| 2350 REM |
| 2360 CALL BKREADBYKEY(F,S$,"23",2,B1$,B2$,A5[*],A3[*],A2[*]) |
| 2370 REM |
| 2380 PEM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED |
| 2390 REM |
| 2400 IF S$[1;1]<>"0" THEN DO |
| 2410 REM N$ CONTAINS THE NAME OF THE KSAM FILE |
| 2420 REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL |
| 2430 PRINT "UNABLE TO READBYKEY ";N$;" ERROR ";S$[1;1];" DETAIL "S$[ 2]|
| 2440 CALL BKERROR(S$,M$) |
| 2450 PRINT M$ |
| 2460 GOTO 3620 |
| 2470 DOEND |
| 2480 REM |
| 2490 REM THE CONTENTS OF B1$="1", OF B2$="23". |
| 2500 REM THE CONTENTS OF A5(1) THROUGH A5(5) ARE INTEGERS 1 THROUGH 5 |
| 2510 REM THE CONTENTS OF A3 AND A2 ARE UNKNOWN. |
| 2520 REM |
| 2530 REM ECHO WHAT WAS READ |
| 2540 REM |
| 2550 PRINT "RECORD READ = ";B1$,B2$ |
| 2560 MAT PRINT A5 |
| 2562 MAT PRINT A3,A2 |
| 2570 REM |
| 2580 REM THE PROGRAM CONTINUES |
_______________________________________________________________________________________
Figure 6-6. Reading a Record Located by Key Value with BKREADBYKEY