BKREAD
MPE documents | |
 Complete PDF | |
| Table of Contents | |
| Index | |
| E0300 Edition 4 ♥ | |
| E0394 Edition 3 |
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. (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.
Operation Notes
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 plan to only 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 to 3. If you want to rewrite or update as well as read records, you must set access to 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)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")
 |
NOTE: Each variable in the parameterlist is filled to its current physical length before proceeding to the next variable. |
210 CALL BKREAD(F,S$) 220 CALL BKREAD(F,S$)The records skipped 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. The example in Figure B-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 B-4 "Opening KSAM File with BKOPEN" the records read were written in the example in Figure B-13 "Writing to a KSAM File with BKWRITE" Each record contains five integers followed by five undefined words 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
BKOPEN <---- open file for read-only, shared, allow locking BKLOCK <---- lock file BKSTART <---- position pointer BKREAD loop <- read file in sequence from original pointer position BKUNLOCK <---- unlock file when last record readFigure B-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] . . . 1310 REM ****************************************************** 1320 REM * READ FROM A KSAM FILE * o 1330 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] 1500 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
|
BKOPEN |
BKREADBYKEY |