Enscribe Programmer's Guide

When the data records of a relative file include one or more alternate-key fields, there are two
other values that are used for manipulating the pointers by way of alternatekey files:
Current key specifier
Identifies which alternate-key field is to be used for accessing records in the file. When the
current access path is by primary key, the current key specifier value is zero.
Current key value
Identifies the particular alternate-key value that is currently being used within the current access
path. When the current access path is by primary key, the current key value is the address of
the physical record that was most recently read from or written to.
When you open a relative file, both the current-record and next-record pointers point to the first
record in the file and the access path is by primary key.
You can change the access path from the primary-key field to an alternate-key field, from one
alternate-key field to another, or back to the primary-key field at any time by using the FILE_SETKEY_,
FILE_SETPOSITION_, KEYPOSITION, and POSITION system procedures. When the access path
is by primary key, successive calls to the FILE_READ64_, FILE_READLOCK64_, FILE_WRITE64_,
READ, READLOCK, and WRITE system procedures access successively higher physical records in
the file. You can change the content of the next-record pointer at any time to point to any specific
record in the file using the FILE_SETPOSITION_ system procedure. You can also use
FILE_SETPOSITION_ to change the content of the next-record pointer so that it points to the EOF
position (for appending records to the end of the file) or to the next available empty record
When the access path is by a particular alternate key, successive calls to the FILE_READ64_,
FILE_READLOCK64_, READ and READLOCK system procedures access successively higher logical
records that contain a specified value (or partial value) in that field. You can change the current
key-specifier and current key-value, and thereby the content of the next-record pointer, at any time
to point to the first record in the file that contains a particular value (or partial value) in any
alternate-key field using the FILE_SETKEY_ system procedure.
FILE_SETPOSITION_ always sets the access path to the primary key.
You can also change the access path from an alternate-key field back to the primary key
FILE_SETPOSITION_ once you do so, the next-record pointer points again to the first record in the
file (relative record number 0).
Creating Relative Files
You create Enscribe relative files by using the File Utility Program (FUP) or by calling either the
FILE_CREATE_ procedure or the FILE_CREATELIST_ procedure.
When you create a partitioned (multivolume) file, the file system automatically creates all of the
partitions of that file when the first partition is created.
If you are using a system procedure to create a relative file and the file contains alternate-key fields,
you must also create one or more alternate-key files. If you are using FUP to create the primary-key
file, however, FUP automatically creates any required alternate-key files.
When creating a relative file, you must consider the maximum logical record size, the data block
length, and disk extent sizes.
Logical Records
A logical record is the unit of information transferred between an application program and the file
system.
When creating a relative file, you must specify the maximum logical record length of that file. This
parameter defines the size of the fixed-length physical records on the disk.
The maximum record size that you choose when creating a file depends upon the requirements of
your application.
136 Relative Files