Record buffers ¶

Contents

Record buffers

Every file that is declared in a program by the ![o]file command is automatically allocated a record buffer, with the same name as the file.

The record buffer is an area of memory with an identical record layout to that of the file. It can be thought of as temporary storage for a single record from the file, bearing the same field names but only existing in memory.

When a record is accessed from the file, the values for each field are read into the buffer. Operations on the file’s fields are actually performed on the buffer rather than on the actual file. When amendments are made to the fields, only the data in the buffer is altered. No change is made to the data in the file unless the write command is used to write the amendments back to the file.

Declaring additional record buffers ¶

Additional record buffers may be declared for a file by means of the !record declaration. This takes the form:

!record record_id = file_id

The record_id is the name of this record buffer. The file_id is the name of the file for which it is to be a buffer.

This enables the creation of a new temporary record structure which is identical to the record structure of the specified file. Records may be read into and written back from this buffer just as from the main file buffer, and the contents of one buffer copied to another. The field names for the buffer are distinguished by being prefixed by the buffer name. That is, a field called “prname” would be referred to as “record_id.prname”.

Usage with Sculptor commands ¶

File access and update commands, although targeted at a specific file, take as an argument the name of a record buffer rather than the name of the file itself. In many cases this makes no difference, as the only buffer in existence is the default buffer which bears the same name as the file. However, the use of additional buffers enables more than one record from a file at the same time to be accessed. Note however that the current Sculptor file system permits only one record from a file to be locked by any given program, unless the file is declared more than once using different file_ids.

The following summary shows how individual file commands work with record buffers:

find[u]; match[u]; next[u]; prev[u]; read[u]	When a file access command successfully reads a record the value of each field in the record is copied into the corresponding field in the record buffer specified.
nextkey; prevkey; readkey	A successful access by one of these commands causes the key fields only to be copied into the specified record buffer. The buffer’s data fields are unchanged. In the case of the readkey command, no update is necessary unless the key = clause was used, because the key fields in the buffer must already contain the exact key values if the readkey is to succeed.
testkey	This command, which is used to test for the existence of a key without affecting the file, leaves the buffer’s key fields untouched if the key = clause is used. If this clause is not used, the buffer already contains the key values, which are used as the key for the purposes of the command.
delete	Deletes the record currently stored in the named buffer. Note that Sculptor does not currently check which buffer the selected record was actually read into; it may be any buffer attached to the same file as record_id.
insert; write	These commands transfer to the file the data which currently resides in the buffer specified. In the case of the write command, a record must already have been read into this buffer by means of one of the file access commands.

Clearing and preserving record buffers ¶

The command clear, without any arguments (global clear), clears all record buffers in a program, reinitialising numeric fields to zero and alphanumeric fields to spaces.

The form clear record_id clears the named buffer only.

The command preserve record_id specifies that the named buffer is not to be cleared by the global clear command. It will not preserve a buffer from a specific clear (clear record_id). The command unpreserve record_id has the reverse effect, restoring a buffer to global clearing status.

Checking contents of record buffers ¶

The Sculptor command check record_id is used to determine whether or not a record buffer contains a selected record - one which is locked from other users and available for update. The write and delete commands fail unless a selected record is available. Note that currently Sculptor checks only that a record has been selected from the file for which record_id is a buffer, and does not check which buffer the record was read into.

Global data assignment between buffers ¶

The statement

record_id1 = record_id2

assigns the data in all fields in record_id2 to the identically named fields in record_id1. Fields in record_id1 with no matching name in record_id2 are unchanged. This enables a temporary copy of a file buffer to be made effortlessly.

All elements of subscripted fields are copied, regardless of the current values of the default subscript variables sys.Col, sys.Row, sys.Plane and sys.Dim4.