Return to DBFORMAT.md CVS log

Up to [Coherent Logic Development] / freem / doc

Annotation of freem/doc/DBFORMAT.md, revision 1.2

1.1       snw         1: # Copyright and License
                      2: 
1.2     ! snw         3: This document is Copyright (C) 2025 Serena Willis
1.1       snw         4: 
                      5: Permission is granted to copy, distribute and/or modify this document under the 
                      6: terms of the GNU Free Documentation License, Version 1.3 or any later version 
                      7: published by the Free Software Foundation; with no Invariant Sections, with no 
                      8: Front-Cover texts, and with no Back-Cover Texts.
                      9: 
                     10: 
                     11: # Global Handler
                     12: 
                     13: The database is organized in a B* tree structure in disk files, each file directly
                     14: corresponding to a single M global.
                     15: 
                     16: On-disk, the arrangement is `/var/local/freem/<namespace-name>/<global-name>`, 
                     17: where `<global-name>` would be something like `^DD`.
                     18: 
                     19: Percent globals (`^%...`) conventionally reside in the `SYSTEM` namespace.
                     20: 
                     21: Non-percent globals (`^...`) reside in other namespaces, or the `USER` namespace
                     22: by default.
                     23: 
                     24: ## Blocks
                     25: 
                     26: Blocks are `BLOCKLEN` bytes long (1024 in the current implementation).
                     27: 
                     28: ## Relevant Source Files
                     29: 
                     30: * global.c (see especially the function `global()`)
                     31: 
                     32: ## Relevant Constants
                     33: 
                     34: ### Block Offsets
                     35: 
                     36: Each of the following constants describe a byte offset to a particular type of 
                     37: data within a single block.
                     38: 
                     39: ```
                     40: | CONSTANT | DESCRIPTION                                    | BLOCK TYPE       |
                     41: +----------+------------------------------------------------+------------------+
                     42: | LLPTR    | Left-Link Pointer                              | DATA, PTR, BPTR  |
                     43: | RLPTR    | Right-Link Pointer                             | DATA, PTR, BPTR  |
                     44: | NRBLK    | Number of Blocks                               | ROOT             |
                     45: | COLLA    | Collation (1: numeric, 2: alphabetical)        | ROOT             |
                     46: | FREE     | Free Block Count                               | ROOT             |
                     47: | BTYP     | Block Type (2: PTR, 6: BPTR, 8: DATA)          | ALL              |
                     48: | OFFS     | Offset to Unused Portion of Data Area          | ALL              |
                     49: ```
                     50: 
                     51: ### Other Constants
                     52: 
                     53: ```
                     54: | CONSTANT | DESCRIPTION                                    |
                     55: +----------+------------------------------------------------+
                     56: | DATALIM  | Length of block data area (offsets 0-1013)     |
                     57: | BLOCKLEN | Length of block (currently 1024)               |
                     58: ```
                     59: 
                     60: ## Root Block Format
                     61: 
                     62: ```
                     63: | STARTING OFFSET   | ENDING OFFSET    | DESCRIPTION                         |
                     64: +-------------------+------------------+-------------------------------------+
                     65: | 0                 | 1013 (DATALIM)   | Block Data Area                     |
                     66: | 1014 (NRBLK)      | 1016             | Number of Blocks                    |
                     67: | 1017 (COLLA)      | 1017             | Collation (0 numeric, 1 alpha)      |
                     68: | 1018 (FREE)       | 1020             | Free Block Count                    |
                     69: | 1021 (BTYP)       | 1021             | Block Type (2 PTR 6 BPTR 8 DATA)    |
                     70: | 1022 (OFFS)       | 1023             | Ptr to free part of block data area | 
                     71: ```
                     72: 
                     73: ## Data Block Format
                     74: 
                     75: ```
                     76: | STARTING OFFSET   | ENDING OFFSET    | DESCRIPTION                          |
                     77: +-------------------+------------------+--------------------------------------+
                     78: | 0                 | 0                | Length of Key - Offset to Prev. Key  |
                     79: | 1                 | 1                | Offset to Prev. Key                  |
                     80: | 2                 | < DATALIM        | Compressed Key                       |
                     81: | <VARIES>          | < DATALIM        | Length of Global Data (2 bytes)      |
                     82: | <VARIES>          | < DATALIM        | Global Data                          |
                     83: | 1014 (LLPTR)      | 1016             | Left-Link Pointer                    |
                     84: | 1017              | 1017             | <RESERVED>                           |
                     85: | 1018 (RLPTR)      | 1020             | Right-Link Pointer                   |
                     86: | 1021 (BTYP)       | 1021             | Block Type (2: PTR, 6: BPTR, 8: DATA)| 
                     87: | 1022 (OFFS)       | 1023             | Ptr to free part of block data area  |
                     88: ```
                     89: 
                     90: ## Pointer Block Format
                     91: 
                     92: ```
                     93: | STARTING OFFSET   | ENDING OFFSET    | DESCRIPTION                          |
                     94: +-------------------+------------------+--------------------------------------+
                     95: | 0                 | 0                | Length of Key - Offset to Prev. Key  |
                     96: | 1                 | 1                | Offset to Prev. Key                  |
                     97: | 2                 | < DATALIM        | Compressed Key                       |
                     98: | <VARIES>          | (2 Bytes)        | Forward Pointer (to ptr or data blk) |
                     99: | 1017              | 1017             | <RESERVED>                           |
                    100: | 1021 (BTYP)       | 1021             | Block Type (2 or 6)                  | 
                    101: | 1022 (OFFS)       | 1023             | Ptr to free part of block data area  |
                    102: ```