FCONTROL

When you use control code 2, the data block and key block buffers and the KSAM control information (including the KSAM end-of-file) are written to disc. (The data written is that contained in the Extra Data Segment for the open file -- refer to Figure B-11 “KSAM Extra Data Segment” for details.) This control code is particularly useful to make sure the KSAM file reflects current changes. Suppose, for instance, that you open a KSAM file exclusively for a long period of time and that your data buffer holds many records. In this case, you can call FCONTROL with code 2 after writing or updating a certain number of records to insure that no more than that number of records will be lost in case of a system failure.

For example, you could call FCONTROL every 10 records:

 

    IF COUNT = 10 <------counter set by each FWRITE or FUPDATE 

    THEN BEGIN 

         FCONTROL(FILNUM,2,DUMMY); 

       END; 

	NOTE: Note that the parameter DUMMY has no function. It is supplied because all FCONTROL parameters are required. It should be declared in the program as a word variable: LOGICAL DUMMY;

As a result of the call shown above, you can never lose more than 10 records in case of a system failure. When a system failure occurs with a KSAM file open, you must run the KSAMUTIL command KEYINFO to allow the file to be reopened. KEYINFO also sets the MPE end-of-file to the current position of the KSAM end-of-file. Control code 2 of FCONTROL makes sure that the KSAM end-of-file follows the last record written to your file.

In a shared environment, be sure to lock your file before calling FCONTROL with control code 2. Otherwise, the call will fail.

This control code repositions the file to the first logical record, that is, the record with the lowest key value. The key that determines this position can be the primary key or an alternate key, depending on which key was accessed last. Suppose you want to read the KSAM file in sequence starting with the record containing the lowest primary key value, you can position to this record using FCONTROL as follows:

 

   FCONTROL(FILNUM,5,DUMMY);<-----positions to 1st record in primary key sequence

This control code performs the same functions as control code 2, except that it also writes the MPE end-of-files for the KSAM files and the latest extent bit map to disc. Because it must access the MPE control blocks as well as the KSAM control block, this code takes more time than code 2. Also, since the MPE end-of-files and the extent bit map are written to disc automatically whenever a new extent is allocated, this code is useful primarily when a series of updates changes the buffers but does not cause new extents to be allocated, and when access to the file is exclusive. If access is shared, you must lock the file before using control code 6.

This control code clears the buffers so that the next call to a read instrinsic must get the record from disc rather than from the buffers. It also forces the latest control information to be read from disc to the buffers. Note that a call to FLOCK will also clear the buffers. The advantage of FCONTROL with code 7 over FLOCK is that it saves time -- the buffers are cleared without locking and then unlocking the file. Thus, you can call FCONTROL with code 7 immediately before calling a read instrinsic in a shared environment in order to get the latest information from disc. However, this does not guarantee that this latest information is not changed (modified or deleted) by other users while you are calling FCONTROL. The only complete safeguard is to lock the file before the read. In any case, if you are making modifications, you should lock the file. For example:

 

   FCONTROL(FILNUM,7,DUMMY); <-----------clear buffers

   FREAD(FILNUM,DATA,-72); <-------------read record from file

   .

   .

   .

   FLOCK(FILNUM,TRUE); <-----------------lock file

   FREAD(FILNUM,DATA,-72); 

   FUPDATE(FILNUM,DATA,-72); <-----------rewrite record just read

   FUNLOCK(FILNUM); <--------------------unlock file