HP 3000 Manuals HP 3000 Manuals
BKREAD
Transfers the next logical record from a KSAM file to a BASIC program.
CALL BKREAD(filenum,status[,parameterlist])
A call to BKREAD transfers the contents of a record from a KSAM file to a
storage area defined by a list of variables in a BASIC program. The
record read is that at which the logical record pointer is currently
positioned. In a series of calls to BKREAD, records are read in
ascending order by key value. The primary key is used unless a previous
call to BKSTART or BKREADBYKEY has positioned the pointer to an alternate
key. The file must have been opened with an access mode that allows
reading.
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 by 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 BKREAD
was successful and if not, why not. The first character
is set to zero when the call succeeds, to another value
if not. (Refer to the Status Parameter discussion
earlier in this section.) (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 the end of the record is
reached. (Optional parameter) Default: If omitted, the
logical record pointer is positioned to the beginning of
the next record in key sequence.
USING BKREAD
After calling BKREAD, you should always check the status parameter to
determine whether the read was successful. Upon successful completion of
BKREAD, the variables specified in parameterlist contain data read from
the record at which the record pointer was positioned when BKREAD was
called. Note that if parameterlist is omitted, the record pointer is
positioned to the beginning of the next logical record, effectively
skipping the current record.
In order to use BKREAD, the file must be opened for input. The BKOPEN
access parameter should be zero if you only plan to read or position a
record. To both read from and write to the same open file, you either
omit the access parameter or set it = 3. If you want to rewrite or
update as well as read records, you must set access = 4.
Values are read from the current record into the variables specified in
parameterlist according to the type and length of the variable. For
example, consider the following code:
10 DIM G$(3),H$(3),S$(4)
20 INTEGER L,F
30 CALL BKREAD (F,S$,G$,H$,L)
/ | \-----/
/ | |
filenum | parameterlist
|
status
If the record being read contains only the word SCRABBLE, this word is
read into the specified variables as if they were assigned by the
statements:
100 G$="SCR"
110 H$="ABB"
120 L=NUM("LE") <------------ assigns numeric equivalent of string "LE" to L
NOTE Each variable in the parameterlist is filled to its current
physical length before proceeding to the next variable.
The following calls omit the parameterlist in order to skip forward two
records:
210 CALL BKREAD(F,S$) <-----------------------------------\
--skip two records
220 CALL BKREAD(F,S$) <-----------------------------------/
The records shipped are not the next records physically placed on the
file, but are the next two in logical sequence according to the value of
the current key. The particular key used for the read sequence can be
selected with a call to BKSTART or BKREADBYKEY. BKSTART can also be used
to position the file to the beginning of the record with the lowest key
value in the selected key (Refer to BKSTART following BKREAD discussion.)
The example in Figure 6-5 assumes that the record pointer has been
positioned to the beginning of the first record in primary key sequence.
Assume that the file being read was opened in the example in Figure 6-4,
the records read were written in the example in Figure 6-11.
Each record contains five integers followed by five undefined words
(garbage) followed by a string of three characters. The record is read
into
A5 a 5-word integer array
A2 a 2-word integer array
A3 a 3-word integer array
B1$ a 1-character string
B2$ a 2-character string
The five integers that were written to the beginning of each record are
read into array A5. The next two arrays A2 and A3 receive the undefined
values that filled the next five words of the record. The first string
character is read into B1$, the next two into B2$.
Shared Access. If you open the file for read-only access (access=0), and
the exclusive parameter is allowed to default to zero, then more than one
user can share read access to the file. In this case, or if you
specifically indicate shared access, you should also allow dynamic
locking in order to read records from the file in key sequence. This is
necessary because BKREAD depends on the current position of the logical
record pointer. (Refer to Table 6-3 for a list of the pointer-dependent
procedures.)
For example, if you plan to read the file sequentially starting from a
particular key value, use the following sequence of calls:
BKOPEN <-------- open file for read-only, shared access, allow dynamic locking
BKLOCK <-------- lock file
BKSTART <-------- position pointer
BKREAD loop <-------- read file in sequence from original pointer position
BKUNLOCK <-------- unlock file when last record read
_________________________________________________________________________
| |
| 10 DIM S$[4] |
| 20 DIM N$[26] |
| 30 DIM M$[72] |
| 40 INTEGER A[10] |
| 50 DIM B$[12] |
| 55 INTEGER J |
| 60 DIM B1$[1] |
| 65 DIM B2$[2] |
| 70 INTEGER A2[2],A3[3],A5[5] |
| : |
| 1310 REM ****************************************************** |
| 1320 REM * READ FROM A KSAM FILE * |
| 1330 REM ****************************************************** |
| 1340 REM |
| 1350 REM F IS THE FILE NUMBER OF A KSAM FILE |
| 1360 REM OPENED BY A CALL TO BKOPEN |
| 1370 REM |
| 1380 REM AN ASSUMPTION HAS BEEN MADE THAT THE RECORD TO BE READ |
| 1390 REM CONTAINS THE SAME INFORMATION THAT WAS WRITTEN TO |
| 1400 REM THE FILE BY THE EXAMPLE TO WRITE A KSAM FILE |
| 1410 REM |
| 1420 CALL BKREAD(F,S$,B1$,B2$,A5[*],A3[*],A2[*]) |
| 1430 REM |
| 1440 REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED |
| 1450 REM |
| 1460 IF S$(1;1]<>"0" THEN DO |
| 1470 REM N$ CONTAINS THE NAME OF THE KSAM FILE |
| 1480 REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL |
| 1490 PRINT "UNABLE TO READ ";N$;" ERROR ";S$[1;1];" DETAIL ";S$[2]|
| l500 CALL BKERROR(S$,M$) |
| 1510 PRINT M$ |
| 1520 REM |
| 1530 REM TEST FOR END OF FILE |
| 1540 REM AND POSITION TO LEAST VALUED PRIMARY KEY |
| 1550 IF S$[1;1]="1" THEN 1080 |
| 1560 GOTO 3620 |
| 1570 DOEND |
| 1580 REM |
| 1590 REM ECHO WHAT WAS READ |
| 1600 REM |
| 1610 PRINT "RECORD CONTAINS";B1$,B2$ |
| 1620 MAT PRINT A5 |
| 1622 MAT PRINT A3,A2 |
| 1630 REM |
| 1650 REM THE CONTENTS OF B1$="1", OF B2$="23" |
| 1660 REM THE CONTENTS OF A5(1) THROUGH A5(5) ARE 1 THROUGH 5. |
| 1670 REM THE CONTENTS OF A3 AND A2 ARE UNKNOWN. |
| 1680 REM |
| 1690 REM THE PROGRAM CONTINUES |
_________________________________________________________________________
Figure 6-5. Reading From a KSAM File with BKREAD