FREMOVE

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 FREADDI 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 Title not available 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 Title not available.

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 recordswith the zip code 90871 in bytes 75 through 79 of the record, assuming the same file as in Title not available:

 

   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.

Figure 4-11 FREMOVE Example

 



$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>> 

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, 



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