Enscribe Programmer's Guide

Read Reverse With Structured Files
You can read Enscribe structured files (key-sequenced, queue, entry-sequenced, and relative)
sequentially in descending key or record number order. You enable this feature by setting a bit in
the options parameter of FILE_SETKEY_ or the positioningmode parameter of the KEYPOSITION
procedure call.
Read Reverse and Position-to-Last Feature
Normally the KEYPOSITION procedure resets the file pointers so that they point to the first record
that satisfies the positioning criteria specified by the key-value, key-len, compare-len, and
positioning-mode parameters. When reading a file in reverse order, however, you probably want
to point to the last record in the file that satisfies the positioning criteria. You enable the
position-to-last feature by setting a second bit in the positioning-mode parameter of the KEYPOSITION
procedure call.
For example, consider the record sequence:
Key ValueRecord Number
AAA0
ABA1
ABB2
ABC3
Following an approximate KEYPOSITION to key-value AB with a specified key-length of 2 and
read-reverse enabled, a call to FILE_READ64_/READ would return record number 1 from the set
of records shown in the preceding example. The same call to KEYPOSITION, but with position-to-last
enabled by the positioning-mode parameter, would instead result in record number 3 being returned
by the FILE_READ64_/READ call.
For the primary key of entry-sequenced and relative files, the key value parameter to KEYPOSITION
is a 4-byte string containing a doubleword record number value. When using read reverse and
approximate positioning in conjunction with those types of files, initial positioning is performed to
the first record whose record number is equal to or less than the record number passed in key-value.
Records are then returned in descending record number order by successive calls to
FILE_READ64_/READ. The position-to-last option is ignored for KEYPOSITION operations to an
exact record number in an entry-sequenced or relative file.
Positioning to the last record in a file with KEYPOSITION is accomplished by specifying a key
length of 0 and specifying approximate positioning, read-reverse, and position-to-last in the
positioning-mode parameter. Following such a KEYPOSITION operation, the subsequent call to
FILE_READ64_/READ will return the last record in the file.
Read Reverse and SAVEPOSITION
Because of the read reverse feature, the SAVEPOSITION system procedure requires a 7-word
positioning buffer to save the current position in an entry-sequenced or relative file that has no
alternate keys.
Only four words of the positioning buffer are used when read forward positioning is in effect. Read
reverse has no impact on the required size of the positioning buffer for key-sequenced files, queue
files, entry-sequenced files with alternate keys, and relative files with alternate keys.
Read Reverse and the Record Pointers
For entry-sequenced and relative files, the state of the current-record and next-record file pointers
following a FILE_READ64_, READ, FILE_WRITE64_ or WRITE are:
Current-record pointer = record number or address of the last record read or written.
52 General File Creation and Access Information