File Structure

When you create a file on a Reality database you select the initial modulo for that file, as described in Creating Files. The modulo determines the disk space initially allocated to the file and the way it is used by Reality.

Groups

The primary disk space of a file comprises a number of groups, known as the modulo. For example, a file with a modulo of seven has seven groups, each group comprising, initially, a single block of disk space called a 'frame' (see Frame Size for more details).

Reality items are read from and written to a file using a hashing algorithm which determines the group in which an item is stored, based on the item-id. This hashing technique minimises item retrieval time by minimising the number of frames that may need to be read from disk. To retrieve an item the algorithm quickly determines the group in which the item is stored, and then Reality searches that group sequentially to find the item.

Data can be stored 'in-group' (direct items) or 'out-of-group' (indirect items). Small character-oriented items are stored 'in-group'. Item data (excluding item-id) that is larger than half the frame size is stored out-of-group in one or more additional frames; the in-group part contains a pointer to the data in the out-of-group part.

The hashing technique provides an efficient method of accessing items, both direct and indirect. However, it is important that the file has a modulo that is large enough to minimise the 'overflow' frames used (additional frames linked to the initial single frame assigned to each group). If there are overflow frames, the search time may be increased since Reality starts at the beginning of each group and searches through any linked frames until it finds the item required, possibly resulting in a large number of disk reads if the file is 'badly sized' (has an inappropriate modulo). For this reason, it is recommended that you configure files for automatic file sizing. Alternatively, for static files, you can use a fixed modulo - refer to the topic Selecting the Modulo for a File for a procedure for determining the best modulo.

Frame Size

By default, each frame is 1 kilobyte in size, but you can change this to 2, 4 or 8 kilobytes if required (refer to the description of the FrameSize configuration parameter for details), or specify the frame size when you create or rebuild a database (see mkdbase).

The OPTIMUM-FRAME-SIZE command can be used to help you decide the optimum frame size for an existing database. You can then reconfigure your database as follows:

1. Use the OPTIMUM-MODULO command to calculate the optimum modulo for one or more files, based on the frame size you have chosen; the resizing parameters for those files will be set to the calculated values.
2. Save the database using the FILE-SAVE command.
3. Rebuild the database by using mkdbase with the -r and -F options. The -F option allows you to specify the new frame size.
4. If you want the restored files to be automatically sized, ensure that the AutoFileSize database configuration parameter is set to 1. Alternatively, run the AFS-SET command.
5. Restore the saved data with ACCOUNT-RESTORE.