Using KSAM/XL and KSAM 64 (32650-90886)
250 AppendixB
BASIC/V Intrinsics
BKREADBYKEY
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