Guardian Programmer's Guide

Communicating With Disk Files
Guardian Programmer’s Guide — 421922-014
5 - 49
Positioning, Reading, and Writing With Key-
Sequenced Files
Positioning, Reading, and Writing With Key-Sequenced Files
Read and write operations on key-sequenced files are done using READ[X],
READUPDATE[X], WRITE[X], and WRITEUPDATE[X] procedure calls, as for any file.
However, what is unique about key-sequenced files is the way you position the current-
record and next-record pointers before reading, writing, or updating the file. The
KEYPOSITION procedure sets the pointers to the appropriate record using one of the
positioning modes: exact, approximate, or generic.
•
Exact positioning sets both pointers to the exact key value specified by the
KEYPOSITION call. If there is no record with the specified key, an error is
returned by the procedure that subsequently attempts to access the record. This
mode is used when updating a record to be sure that the user is accessing the
correct record.
Suppose you have a file of records sorted on social security number. You would
use a code fragment similar to the following to update a specific record. In this
case, the code updates the record with social security number 327-67-1120.
LITERAL EXACT = 2;
.
.
KEY^VALUE ':=' "327671120" -> @S^PTR;
KEY^LEN := @S^PTR '-' @KEY^VALUE;
CALL KEYPOSITION(KEY^FILE^NUM,
KEY^VALUE,
!key^specifier!,
KEY^LEN,
EXACT);
CALL READUPDATEX(KEY^FILE^NUM,
BUFFER,
$LEN(RECORD),
BYTES^READ);
IF <> THEN ...
.
.
CALL WRITEUPDATEX(KEY^FILE^NUM,
BUFFER,
$LEN(RECORD));
IF <> THEN ...
.
.
•
Approximate positioning sets both pointers to the record containing either the exact
key or the next greater key. This mode is often used for starting a sequential read
operation.
For example, a user may want to examine all records starting with those whose
primary key value begins with “C.” Here, you would use approximate positioning to
set the pointers to the first record that begins with “C.” This example assumes that
each key is made up entirely of alphabetic characters. It loops indefinitely, reading