Enscribe Programmer's Guide

Reading the buffered data does not use the disk process until:
• The block has been traversed, at which time the disk process fetches another block.
• An intervening FILE_SETPOSITION_, FILE_SETKEY_, POSITION, or KEYPOSITION is performed.
In this case, the next READ request causes a new block to be fetched.
• A disallowed request (such as FILE_READUPDATELOCK64_, FILE_READLOCK64_,
FILE_READUPDATE64_, READUPDATELOCK, READLOCK, READUPDATE, FILE_LOCKREC64_,
LOCKREC, or a write request)
Considerations
Note that sequential block buffering is meaningful only for sequential reading of multiple records
of a structured file. Neither random reading nor any writing can take advantage of the sequential
buffer. In fact, because they always involve the disk process, write operations automatically clear
the buffer.
Sequential block buffering ignores any record locks that are currently in effect for the records in
the block. Sequential block buffering does not, however, bypass a file lock when the block is first
retrieved from the disk process.
To change a record that has been read from a block buffer, you should first perform intervening
FILE_SETPOSITION_, FILE_SETKEY_, POSITION, KEYPOSITION, FILE_READLOCK64_,
FILE_READUPDATELOCK64_, READLOCK, or READUPDATELOCK operations to fetch the record.
Doing so:
• Ensures that the record has not been altered or deleted by another user since the block was
read.
• Ensures that the record is not currently locked by another process.
• Locks out other processes from the record to be updated.
FILE_OPEN_ Parameters
The FILE_OPEN_ procedure's sequential-block-buffer and buffer-length parameters govern creation
of the buffer.
The sequential-block-buffer parameter serves only as a numeric buffer identifier, because the file
system allocates the buffer space from the PFS. This parameter can be omitted if buffer space is
not to be shared.
The buffer-length parameter is the more significant parameter because:
• If it is zero, absent, or longer than the space available in the PFS, the open operation succeeds
but returns an indication with warning 5 (failure to provide sequential buffering) and block
buffering is not used.
• If it is greater than the file's block size, the buffer will be created with the specified size.
• If it is nonzero but not greater than the file's block size, the buffer size will equal the block
size. For example, if a file with block size 4096 is opened with a buffer-length parameter of
128, the buffer will be created for a block size of 4096.
Alternate-Key Files
If you want to use an alternate-key access path and the alternate-key file's block size is larger than
that of the primary file, open the primary file with the larger buffer-length parameter.
If access to a primary file uses sequential block buffering, access to all associated alternate-key
records also uses it.
After FILE_SETKEY_ or KEYPOSITION with a nonzero key specifier, the first FILE_READ64_/READ
request causes the disk process to fetch a data block from the alternate-key file into the buffer area.
The disk process then fetches a single record from the primary data file by using the alternate-key
56 General File Creation and Access Information