BKREWRITE

Operation Notes

After calling BKREWRITE, you should always check the status parameter to make sure that the rewrite was successful. Upon successful completion of BKREWRITE, new values replace the data in the last record read to or written from the BASIC program. The new data may change every value in the previously read record including the primary key value.

If you want to replace a record with a particular key value, you should locate and read the record with BKREADBYKEY or BKSTART. To rewrite a series of records you should read the records with BKREAD.

When the data in the parameterlist of BKREWRITE is shorter in total length than the data in the record being rewritten, there is less total data in the rewritten record. In order to maintain the key sequence of all keys, defined values should be written to the location of all keys, both the primary key and any alternate keys.

	NOTE: Items written to a KSAM file with the BKREWRITE procedure are concatenated; rounding to halfword boundaries does not occur.

The example in Figure B-9 “Rewriting Record in KSAM File with BKREWRITE” writes new values to a record originally written in Figure B-13 “Writing to a KSAM File with BKWRITE” and read in Figure B-5 “Reading From a KSAM File with BKREAD” The new values fill an array that had undefined values in the last five elements, now defined as two arrays A3 and A2 by the BKREAD call. The primary key value 23 in location 2 is unchanged.

The record read by BKREAD contained the following values:

Figure B-7 BKREAD values

After being rewritten by BKREWRITE, it contains the following values:

Figure B-8 After BKREWRITE

When access is shared, the call to BKREAD, BKREADBYKEY, or BKSTART that locates the record to be rewritten should be included in the same pair of BKLOCK/BKUNLOCK calls as the call to BKREWRITE. This ensures that no other user alters the record pointer between the call that locates the record and the call that rewrites it.

If you want to sequentially rewrite all records in a chain of records with duplicate keys, locate the first record in the chain with BKREADBYKEY. Then call BKREWRITE to modify this record. If no key value (the selected key or any other) is modified, subsequent calls to BKREWRITE will modify the next sequential records in the chain of duplicate keys. If, however, any key has been changed, the modified key is written to the end of the chain and the next sequential record is one with the next higher key value. In this case, to rewrite all records with duplicate keys, precede each call to BKREWRITE by a call to BKREADBYKEY.

2600 REM 
2610 REM ********************************************************* 
2620 REM * REVISE THE CONTENTS OF A RECORD READ FROM A KSAM FILE * 
2630 REM ********************************************************** 
2640 REM 
2650 REM F IS THE FILE NUMBER OF A KSAM FILE OPENED BY A CALL TO BKOPEN 
2660 REM NOTE THAT FOR BKREWRITE,BKOPEN ACCESS MODE MUST=4 FOR UPDATE. 
2670 REM 
2680 REM AN ASSUMPTION HAS BEEN MADE THAT THE RECORD TO BE READ 
2690 REM CONTAINS THE SAME INFORMATION THAT WAS WRITTEN TO THE 
2700 REM KSAM FILE IN THE BKWRITE EXAMPLE,, 
                 |------------------ parameterlist 
2710 REM /------------------------\ 
2720 CALL BKREAD(F,S$,B1$,B2$,A5[*],A3[*],A2[*]) 
2730 REM 
2740 REM NOW DETERMINE WHETHER THE CALL HAS SUCCEEDED. 
2750 REM 
2760 IF S$[1;1]<>"0" THEN DO 
2770 REM N$ CONTAINS THE NAME OF THE KSAM FILE 
2780 REM S$ CONTAINS THE STATUS CALL SET BY THE PRECEDING CALL 
2790 PRINT "UNABLE TO READ ";N$;" ERROR ";S$[1;1]" DETAIL ";S$[2] 
2800 CALL BKERROR(S$,M$) 
2810 PRINT M$ 
2820 GOTO 3620 
2830 DOEND 
2900 REM THE CONTENTS OF B1=1", OF B2$="23" 
2910 REM THE CONTENTS OF A5(1) THROUGH A5(5) ARE 1 THROUGH 5 
2920 REM THE CONTENTS OF A3 AND A2 ARE UNKNOWN 
2930 REM 
2940 REM STORE VALUES 1 THROUGH 3 INTO A3(1) THROUGH A3(3) 
2950 REM STORE VALUES 1 AND 2 INTO A2(1) AND A2(2). 
2960 REM 
2970 FOR I=1 TO 2 
2980 A2[I]=I 
2990 A3[I]=I 
3000 NEXT I parameterlist 
3010 A3[3]=3 | 
3020 REM /------------------------\ 
3030 CALL BKREWRITE(F,S$,B1$,B2$,A5[*],A3[*],A2[*]) 
3040 REM 
3050 REM NOW DETERMINE WHETHER THE CALL HAS SUCCEEDED 
3060 REM 
3070 IF S$[1;1]<>"0 THEN DO 
3080 REM N$ CONTAINS THE NAME OF THE KSAM FILE 
3090 REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL 
3100 PRINT "UNABLE TO REWRITE ";N$;" ERROR ";S$[1;1];" DETAIL ";S$[2] 
3110 CALL BKERROR(S$,M$) 
3120 PRINT M$ 
3130 GOTO 3620 
3140 DOEND 
3150 REM 
3160 REM ECHO WHAT WAS UPDATED 
3170 REM 
3180 PRINT "REWRITTEN RECORD = ";B1;B2 
3190 MAT PRINT A5,A3,A2 
3200 REM 
3210 REM THE PROGRAM CONTINUES