GEOS SDK TechDocs|
| 
3.2 Allocating and Freeing Groups | 
3.4 Accessing DB Items DBAlloc(), DBFree()
To allocate a DB item, call
DBAlloc()
. This routine takes three arguments: the handle of the VM file, the DB Group in which to allocate the item, and the size of the item (in bytes). The routine will allocate an item in one of that group's item blocks (allocating a new item block if necessary); it returns the new item's item-handle.
Remember that when you allocate a DB item, the DB manager allocates a chunk in an LMem heap (the item block). This can cause the item block to be compacted or resized; this will invalidate all pointers to items in that block. For this reason, you should not allocate items in a group while other items in that group are locked. Similarly, you should not allocate "ungrouped" items while any "ungrouped" items are locked. Instead, unlock the items, allocate the new one, and then lock the items again.
When you are done with an item, free it with
DBFree()
. This routine takes three arguments: the file handle, the group-handle, and the item-handle. It frees the item, making appropriate changes in the group block. If the item was the only one in its item block, that item block will be freed as well.
DBFree()
does not return anything. Note that you should never free a locked item since the item-block's reference-count will not be decremented (and the block will never be unlocked). Always unlock an item before freeing it. (You need not, however, unlock items before freeing their
group
; when a group is freed, all of its items are automatically freed, whether they are locked or not.)
GEOS SDK TechDocs|
| 3.2 Allocating and Freeing Groups | 3.4 Accessing DB Items