Enscribe Programmer's Guide

By using alternate-key values, you can process a subset of records that all contain the same value
in a particular data field. For example, using Figure 4 (page 27) again, the REGION field is
defined as an alternate key and the value CENTRAL provides you with access to two records.
Figure 4 Using Key Values to Locate Records
In a key-sequenced file, only one record can
have the primary-key value JONES, J.A.
Two or more records, however, can have the value
CENTRAL in their region alternate-key fields
SMITH, S.A.
JONES, J.A. DAYTON, OHIO CENTRAL
MOORE, Q.A. LOS ANGELES, CALIFORNIA WESTERN
CHICAGO, ILLINOIS CENTRAL
Access Paths
Each key in a structured file provides a separate access path through the records in that file. Records
in any given path are accessed by ascending key values. In the case of duplicate alternate-key
values, the records containing the same key value are accessed within that path in the order in
which they appear in the alternate-key file.
Normally, duplicate alternate-key records are stored in the alternate-key file in ascending order
by their associated primary-key values. When you create an alternate-key file, however, you can
specify (by way of the alternate-key-params array) that duplicate alternate-key records be stored
in the order in which they are added to the file.
Note that all alternate-key files for any given primary database file must use the same ordering
convention for records with duplicate keys. That is, if one alternate-key file for a particular primary
file contains insertion-ordered duplicate key records, then all the alternate-key files for that primary
file must do so.
When you perform a read or write operation that uses or creates an insertion-ordered duplicate
alternate-key record, the file system returns an advisory error code (CCL with a code of 551) upon
completion of the particular system procedure call.
Current Key Specifier and Current Access Path
A 2-byte key specifier uniquely identifies each key field as an access path for positioning. The key
specifier for primary keys is defined as binary zero (ASCII nullnull). Key specifiers for alternate-key
fields are defined by the application and are assigned when the file is created. Figure 6 (page 29)
shows a typical record structure with a primary key and three alternate keys.
The current key specifier defines the current access path, which affects the order of the records of
the file (see Figure 5 (page 28)). The current access path is implicitly set to the file's primary key
when a file is opened; for entry-sequenced and relative files, the current access path is also set to
the primary key of the file when a call is made to the POSITION procedure. The access path is set
explicitly by calling the KEYPOSITION procedure.
Access Paths 27