Enscribe Programmer's Guide

Key Specifier
To identify a particular data field as an alternate-key access path, you must differentiate it from
other fields by assigning it a 2-byte key specifier (such as OH for the on-hand field). You supply
the 2-byte key specifier when you create the primary file.
Key Offset
For each alternate key you must specify its offset from the start of the record (where the alternate-key
field begins) when creating or altering characteristics of the primary file.
Consider these when choosing the offset of an alternate-key field:
• An alternate-key field can begin at any offset in the record.
• Alternate-key fields can overlap.
• Alternate-key fields are fixed-length but need not contain a data value (that is, they can contain
a null value) when inserting or updating a record.
• If any part of a given alternate-key field is present when inserting or updating a record, the
entire field must be present.
• If the key field is to be treated as a data type other than STRING, the specified offset must be
such that the field begins on a word boundary.
Automatic Maintenance of All Keys
When a new record is added to a file or a value in an alternate-key field is changed, the Enscribe
software automatically updates the indexes to the record (the value of a record's primary key
cannot be changed). This operation is entirely transparent to the application program.
If more key fields are later added to a file, but existing fields in that file are not relocated, existing
programs that access the file need not be rewritten or recompiled.
Null Value
You can assign a null value to any alternate key. You can choose any character as the null value;
the most commonly used are ASCII blank (%40) and binary zero.
If a record is inserted and one of its alternate-key fields contains only bytes of the null value, an
alternate-key reference is not added to the alternate-key file. If a record is updated and one of its
alternate-key fields is changed to contain only bytes of the null value, the associated alternate-key
reference is deleted from the alternate-key file.
If a structured file is read sequentially by alternate key, any records containing the null value in
that field are skipped. Instead, the next record returned (if any) is the next one not having the null
value in that alternate-key field. A null value is a byte value that, when encountered in all positions
of the indicated key field during a record insertion, causes the alternate-key file entry for the field
to be omitted.
Unique Alternate Key
An alternate-key field can be specified to require a unique value in each record. If you try to insert
a record that duplicates an existing record's value in a unique key field, the insertion is rejected
with an error 10 (“record already exists”). When using nonunique alternate keys, such
an insertion would be permitted. If a file has one or more unique alternate keys, remember that:
• For each alternate-key field having a unique key-length, you must create a separate alternate-key
file.
• More than one unique alternate key of the same key-length can be referred to by the same
alternate-key file; this is illustrated by the sample alternate-key file following Figure 9 (page 32)
Alternate Keys 33