HP 3000 Manuals HP 3000 Manuals
FCONTROL
INTRINSIC NUMBER 13
Performs control operations on a KSAM file.
IV IV L
FCONTROL(filenum,controlcode,param);
The FCONTROL intrinsic performs various control operations on a KSAM
file. When specified for a KSAM file, these control operations are
limited to the following:
* Complete input/output
* Rewind the file
PARAMETERS
filenum integer by value (required)
A word identifier supplying the file number of the file
for which the control operation is to be performed.
controlcode integer by value (required)
An integer identifying the operation to be performed:
2 = Complete Output. This insures that requested output
has been physically completed; that is, that the key
buffers, data buffers, and KSAM control information are
all written to disc.
When access is shared, you must lock the file with FLOCK
before calling FCONTROL with control code 2.
5 = Rewind File. This repositions the file at its
beginning, so that the next record read or written is
the first logical record in the file. When this code is
used for KSAM files, the file is not repositioned to the
first physical record but to the first logical record.
The first logical record is the record with the lowest
value in the current key (primary or alternate)
[***text removed at this point***]
param logical (required)
This parameter may be specified as any variable or word
identifier; it is needed by FCONTROL to satisfy internal
requirements of the intrinsic, but serves no other
purpose and is not modified by the instrinsic.
CONDITION CODES
CCE Request granted.
CCG Not returned by this intrinsic.
CCL Request denied because an error occurred. Returned if
any control code other than 2, 5, 6, or 7 is specified
for a KSAM file; or the file was opened for shared
access, but was not locked for control code 2 or 6.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FCONTROL
FCONTROL provides four control functions for KSAM files. These allow you
to write the key and data buffers and all KSAM control information to
disc; to position the logical record pointer to the first logical record
in the file; to write the buffers, KSAM control information, plus the MPE
endof-file and the latest extent bit map, to disc; and to clear all the
data buffers and the latest control information from disc.
The control functions that write the buffers to disc (2 and 6) require
that you lock the file before calling them in a shared access
environment.
USING CONTROL CODE 2. 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 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.
USING CONTROL CODE 5. 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
USING CONTROL CODE 6. 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.
USING CONTROL CODE 7. 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