File position¶
When a Sculptor program is running, every keyed file opened by the program has, at any given moment, a current file position. The file is sequenced from the lowest possible key value up to the highest, and may at any time be positioned at the key value of an existing record, between two existing records, at the very beginning of the file (before the first record) or at the very end (after the last record). The file position is crucial to commands such as next and prev, which select the next or previous record, counting from the current file position.
The lowest possible key value is where all key fields are null (numeric fields are zero and alphanumeric fields blank). The null key corresponds to the beginning of the file. It is recommended that the creation of null-keyed records be avoided.
The file position is crucial to commands such as next[u] and prev[u], which select the next or previous record, counting from the current file position.
Any successful file access (with the exception of testkey) positions the file at the record which was found by the file access command.
When the program loads, or when a file is first opened, the file is positioned at the beginning, or null key position, before the first non-null-key record. The next[u] command therefore selects the first record in the file (unless it has a completely null key, in which case it is skipped). Successive next[u] commands move the file position along in ascending key order of the records existing in the file, until the end of the file is reached. The prev[u] command can then be used to reverse the process.
Sculptor commands¶
These file access commands move the file position to that of the key provided whether or not a record is found. If the command is successful, the file is now positioned at the key value of the record found by the command. If it is unsuccessful, it is positioned where the desired record would have been had it existed: between the records with the next higher key and the next lower key from that specified in the command (or at the beginning or end of the file, as appropriate). |
|
These file access commands, if successful, move the file position to the record that was found by the command. If unsuccessful, they leave the file position unchanged. |
|
This file access command leaves the file position unchanged whether or not it is successful. |
|
After a record is deleted, the file remains positioned at the key value of the deleted record, even though the actual record no longer exists. |
|
If a record is successfully inserted into a file, the file is positioned at the key value of the new record. However, if the insert command fails because a record with an identical key already exists, the file position is not changed. |
|
When a record is written back without any changes to its key, the file is positioned at the key value of the record. However, if amendments were made to the key, the file remains positioned at the key value of the old key. |
|
This command is for the purpose of repositioning a specified file (or secondary index) at its start (i.e. at the null key position). |
|
This command positions a specified file (or secondary index) at its end (i.e. after the last record). |
|
Synchronises the current file position of all secondary indexes for a specified file or files to the current main index file position. |
Secondary index position¶
A secondary index to a file maintains its own independent file position, which is set in the same way as the main file position: by the file access commands listed above, or by the rewind and wind commands. All these commands have an optional index = clause, which allows a secondary index to be selected.
The sync_indexes command synchronises the file position of all secondary indexes to the current main file position.
RELATED TOPICS |