HPlogo Using KSAM XL and KSAM 64 > Appendix B BASIC/V Intrinsics

BKREWRITE

MPE documents

Complete PDF
Table of Contents
Index

E0300 Edition 4 ♥
E0394 Edition 3

Changes the contents of a record in a KSAM file. 

  CALL BKREWRITE (filenum, status, parameterlist)
A call to BKREWRITE replaces the contents of an existing record with new values. The record to be rewritten is the last record accessed by a call to BKREAD, BKREADBYKEY, or BKSTART. To use BKREWRITE, the file must be open in the access mode that allows update. If access is shared, it must also be opened with dynamic locking allowed, and the file must be locked by BKLOCK before records are rewritten.

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 BKREWRITE 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)

parameterlist

A list of variables or constants, separated by commas, that contains the data to be written to the file replacing the last record read or written. The total length of the new record is derived from the total number, data type, and length in characters of each item in parameterlist. Although this length need not be the same as the record it replaces, it should be long enough to contain all the keys, but not exceed the defined record length. (Required parameter)

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

[BKREAD values]

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

Figure B-8 After BKREWRITE

[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.

Figure B-9 Rewriting Record in KSAM File with BKREWRITE 

 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
 2651 REM   BKOPEN
 2660 REM NOTE THAT FOR BKREWRITE,BKOPEN ACCESS MODE MUST=4 FOR
 2661 REM   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,,
 2701 REM              |------------------ 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
 3010 A3[3]=3
 3012 REM              |------------- parameterlist
 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



BKREADBYKEY

BKSTART