HP 3000 Manuals HP 3000 Manuals
FREMOVE
INTRINSIC NUMBER 306
Marks the current record in KSAM file for deletion.
IV
FREMOVE(filenum);
The intrinsic FREMOVE effectively removes the current record from the
KSAM file. When executed, the first two characters of the current record
in the data file is set to all 1's, and all key entries pointing to this
record are deleted from the key file. Although the space required by the
record remains in the data file, it is no longer possible to access the
record through KSAM intrinsics.
In order to position the file to the record to be deleted, FREMOVE must
be preceded by one of the intrinsics that positions the logical record
pointer: FFINDN, FFINDBYKEY, FREADBYKEY, FREAD, FPOINT, or a previous
FREMOVE. Following execution of FREMOVE, the logical record pointer is
positioned at the next record in ascending key sequence.
FREMOVE checks only the logical record pointer, not the chronological
pointer, to locate the record to be deleted. Therefore, if you want to
delete a record located by its chronological position in the file,
precede the call to FREMOVE with a call to FPOINT. FPOINT locates the
record by its record number and sets the logical, as well as the
chronological pointer, to that record. If you try to locate a record for
FREMOVE by calling FREADDIR or FREADC, which only set the chronological
pointer, you will delete the wrong record.
When FREMOVE is executed, a check is made to make sure the record to be
deleted actually contains the key value to which the pointer is
positioned. If the record does not contain that value, then a condition
code (CCL, error=191) is issued and the record is not deleted.
If the file was opened for shared access (aoptions bits 8,9 = 11) then
you must call FLOCK before calling FREMOVE. Note that the file must also
have been opened with dynamic locking allowed (aoptions bit 10 = 1).
NOTE If you want to recover the data in deleted records through nonKSAM
access (using FCOPY with the NOKSAM option), do not place any data
in the first two bytes since these bytes are overwritten by
FREMOVE.
PARAMETERS
filenum integer by value (required)
A word identifier supplying the file number of the file
from which the record is to be deleted.
CONDITION CODES
CCE The current record is deleted.
CCG The logical end-of-data was encountered.
CCL An error was encountered or record does not contain
requested key value; the record is not deleted.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FREMOVE
When FREMOVE is executed, it sets the first word (bytes 1 and 2) of the
current record to all 1's. It does not physically delete the record from
the file. When the file is read by any of the KSAM read intrinsics, the
deleted records are skipped as if they were not there. Since all
references to them are deleted from the key file, the speed of execution
is not usually affected by the records physically remaining in the file.
However, they do take up space and if a great many records are deleted,
then you might want to build a new KSAM file and copy the old file to the
new file with FCOPY. Since FCOPY does not copy records marked for
deletion (except with the NOKSAM option), the new file will be shorter
and have no space used by deleted records. (Refer to section II for a
description of copying KSAM files with FCOPY.)
The example in Figure 4-11 deletes all records with a telephone number in
the alternate key field that is equal to or greater than "500-0000". The
FFINDBYKEY intrinsic positions the file to the record containing the
lowest alternate key value that is greater than or equal to "500-0000".
This record is then read and printed prior to being deleted by FREMOVE.
Following FREMOVE, the program loops back to read the next sequential
record, print it, and then delete it. When an end of data is reached,
the program terminates. In all, the program deletes three records. You
can check the deleted records against the list of records printed in
telephone number sequence by the program illustrating FREAD in Figure
4-7.
In practice, an FREAD prior to an FREMOVE is useful because it allows you
to test the record contents prior to deleting the record. For example,
you might want to delete only those records with the zip code 90871 in
bytes 75 through 79 of the record, assuming the same file as in Figure
4-11:
BYTE ARRAY INPUTB(*)=INPUT; <---- Equate the byte array INPUTB to INPUT
:
L1:
FREAD(FILNUM,INPUT,-72);
IF>
.
. <----- test for end of data
.
IF<
.
.<------ test for read error
.
IF INPUTB(75)="90871"
THEN BEGIN
FREMOVE(FILNUM);
IF<
.
. <----- test for delete error
.
END;
GO TO L1; <--------------- return for next record
SHARED ACCESS. In a shared environment, you must always lock the file
with a call to FLOCK before calling FREMOVE. Furthermore, since the
logical record pointer must be positioned before the call to FREMOVE, you
should lock the file before calling the procedure that positions the
pointer. This prevents other users from affecting the pointer position
by adding or deleting records between the time you position the pointer
and call FREMOVE. The following sequence of calls illustrates the correct
method for deleting a record in a shared environment:
FLOCK <------------- lock the file
FREADBYKEY <------------- position pointer and read record
FREMOVE <-- mark the record for deletion
FUNLOCK <-- unlock file to allow access to other users
Remember to open the file for shared access and allow dynamic locking
whenever you plan to delete records from a file in a shared environment.
______________________________________________________________________
| |
| $CONTROL MAIN=JEXAMPL7 |
| <<******************************************************>> |
| <<* EXAMPLE 7 *>> |
| <<* DELETE SELECTED RECORDS *>> |
| <<******************************************************>> |
| INTEGER FILNUM; |
| INTEGER LENGTH; |
| INTEGER ERRORCODE; |
| BYTE ARRAY FILNAME(0:9):="JEXAMFIL "; |
| ARRAY MESSAGE(0:35); |
| ARRAY INPUT(0:39); |
| ARRAY OUTPUT(*)=INPUT; |
| BYTE ARRAY KEYVALUE (0:7):="500-0000"; |
| INTEGER KEYLENGTH:=8; |
| INTEGER KEYLOCATION;=21; |
| INTEGER RELOP;=2; << GREATER THAN OR EQUAL TO >>|
| INTRINSIC FOPEN,FCLOSE,FREAD,FREMOVE,FFINDBYKEY, |
| READ,PRINT,TERMINATE,CHECK,FERRMSG; |
| <<************************>> |
| <<* OPEN THE KSAM FILE *>> |
| <<************************>> |
| FILNUM:=FOPEN(FILNAME,3,5); <<OPEN THE KSAM FILE FOR UPDATE>> |
| IF FILNUM=0 |
| THEN BEGIN <<CANNOT OPEN KSAM FILE>> |
| MOVE MESSAGE:="CANNOT OPEN KSAM FILE"; |
| PRINT(MESSAGE:=-21,0); |
| FCHECK(FILNUM,ERRORCODE); <<GET ERROR NUMBER>> |
| FERRMG(ERRORCODE,MESSAGE,LENGTH);<<CONVERT TO STRING>> |
| PRINT(MESSAGE,-LENGTH,0); <<PRINTOUT ERROR MESSAGE>> |
| TERMINATE; |
| END; |
| <<********************************************************>> |
| <<* POSITION KSAM FIL IN TELEPHONE # SEQUENCE *>> |
| <<********************************************************>> |
| FFINDBYKEY(FILNUM,KEYVALUE,LEYLOCATION,LEYLENGTH,RELOP); |
| MOVE MESSAGE:="DELETE FOLLOWING RECORDS:"; |
| PRINT(MESSAGE,-25,0); |
| <<**********************************>> |
| <<* READ RECORD BEFORE DELETING *>> |
| <<**********************************>> |
| L2: |
| FREAD(FILNUM,INPUT,-72); << READ RECORDS TO BE DELETED>> |
______________________________________________________________________
Figure 4-11. FREMOVE Example
_______________________________________________________________________________
| |
| IF > |
| THEN BEGIN <<END OF FILE>> |
| FCLOSE(FILNUM,0,0) <<CLOSE THE KSAM FILE>> |
| IF <> THEN |
| BEGIN <<CLOSE UNSUCCESSFUL>> |
| MOVE MESSAGE:="CANNOT CLOSE THE KASM FILE"; |
| PRINT(MESSAGE,-29,0); |
| FCHECK(FILNUM,ERRORCODE); <<GET ERROR NUMBER>> |
| FERRMSG(ERRORCODE,MESSAGE,LENGTH);<<CONVERT TO STRING>> |
| PRINT(MESSGE,-LENGTH,0); <<PRINTOUT ERROR MESSAGE>> |
| END; |
| TERMINATE; |
| END; |
| IF < |
| THEN BEGIN |
| MOVE MESSAGE:="ERROR OCCURRED WHILE READING INPUT"; |
| PRINT(MEEAGE,-34,0); |
| FCHECK(FILNUM,ERRORCODE); <<GET ERROR NUMBER>> |
| FERRMSG(ERRORCODE,MESSAGE,LENGTH);<<CONVERT TO STRING>>|
| PRINT(MESSAGE,-LENGTH,0); <<PRINTOUT ERROR MESSAGE>> |
| TERMINATE; |
| END; |
| <<***********************************************>> |
| <<* WRITE THE RECORD JUST READ FROM KSAM FILE *>> |
| <<***********************************************>> |
| PRINT(OUTPUT,-72,0); |
| <<*****************************************>> |
| <<* REMOVE RECORD JUST READ FROM FILE *>> |
| <<*****************************************>> |
| FREMOVE(FILNUM); <<DELETE RECORD>> |
| IF < |
| THEN BEGIN |
| MOVE MESSAGE:=ERORROR OCCURRED DURING DELETE"; |
| PRINT(MESSAGE,-28,0); |
| FCHECK(FILNUM,ERRORCODE); <<GET ERROR NUMBER>> |
| FERRMSG(ERRORCODE,MESSAGE,LENGTH);<<CONVERT TO STRING>>|
| PRINT(MESSAGE,-LENGTH,0); <<PRINTOUT ERROR MESSAGE>> |
| TERMINATE; |
| END; |
| <<************************************>> |
| <<* GO BACK TO GET ANOTHER RECORD *>> |
| <<************************************>> |
| GO TO L2; |
| END, |
_______________________________________________________________________________
Figure 4-11. FREMOVE Example (continued)
______________________________________________________________________
| |
| Output from Program Execution: |
| |
| DELETE FOLLOWING RECORDS: |
| CARDIN RICK 578-7018 11100 WOLFE ROAD CUPERTINO CA. 94053|
| NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087 |
| TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234|
| END 0F PROGRAM |
______________________________________________________________________
Figure 4-11. FREMOVE Example (continued)