Return to DBFORMAT.md CVS log

Up to [Coherent Logic Development] / freem / doc

Begin formatting overhaul and REUSE compliance

    1: # Copyright and License
    2: 
    3: This document is Copyright (C) 2025 Serena Willis
    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: ```