Transfers the next logical record from a KSAM file to a BASIC program.
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 pointe to an alternate key. The file must have been opened with an access mode that allows reading.
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 “Reading From a KSAM File with BKREAD” 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 “Opening KSAM File with BKOPEN”, the records read were written in the example in Figure 6-11 “Writing to a KSAM File with BKWRITE”.
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$.
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 “Positioning the Logical Record Pointer” 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
|
Figure 6-5 Reading From a KSAM File with BKREAD
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]
[vellip]
1310 REM ******************************************************
1320 REM * READ FROM A KSAM FILE * o
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
|
