Return to DBFORMAT.md CVS log

Up to [Coherent Logic Development] / freem / doc

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

1.1     ! snw         1: # Copyright and License
        !             2: 
        !             3: This document is Copyright (C) 2020 John P. 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: ```