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 one 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.

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. (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)

Operation Notes

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 and keylocation parameters.

The key value in the record 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 B-6 “Reading a Record Located by Key Value with BKREADBYKEY” 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 B-13 “Writing to a KSAM File with BKWRITE”, the records in the file are identical including the keys and only the first record is read.

Figure B-6 Reading a Record Located by Key Value with BKREADBYKEY

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 REM 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

BKREADBYKEY

Technical documentation

» Table of Contents

» Index

Parameters

Operation Notes