GEOS SDK TechDocs
|
| 
4.1 Structure of a VM Chain
| 
5 Huge Arrays
VMChainHandle, VMFreeVMChain(), VMCompareVMChains(), VMCopyVMChain(), VMCHAIN_IS_DBITEM(), VMCHAIN_GET_VM_BLOCK(), VMCHAIN_MAKE_FROM_VM_BLOCK()
Several utilities are provided for working with VM chains. They allow you to compare, free, or copy entire VM chains with a single command.
For convenience, all of these routines can work on either a VM chain or a database item. This is useful, because sometimes you will want to use the utility on a data structure without knowing in advance how large it will be. This way, if there is a small amount of data, you can store it in a DB item; if there is a lot, you can store it in a VM chain of any length. Whichever way you store the data, you can use the same chain utilities to manipulate it.
The routines all take, as an argument, a
VMChain
which is simply a dword. If the low word is null, the
VMChain
contains the VM block handle to a VM chain. If the low word is not null, the
VMChain
contains a
DBGroupAndItem
. Note that none of the blocks in the VM chain need be locked when the routine is called; the routine will lock the blocks as necessary, and unlock them when finished. Similarly, a DB item need not be locked before being passed to one of these routines. However, the VM file containing the structure must be open.
If you want to free an entire VM chain at once, call the routine
VMFreeVMChain()
. This routine takes two arguments, namely the VM file handle and a
VMChain
. It frees every block in the VM chain, and returns nothing.
You can compare two different VM chains, whether in the same or in different files, by calling
VMCompareVMChains()
. This Boolean routine takes four arguments, namely the handles of the two files (which may be the same) and the
VMChain
s (
i.e.
, the block handles to the two chains). The geode must have both files open when it calls this routine. The routine returns
true
(
i.e.
, non-zero) if the two chains are identical (
i.e.
, the trees have the same structures and all data bytes are identical). Note that if the chains contain tree blocks which are identical except in the order of their links, the chains will not be considered identical and the routine will return
false
(
i.e.
, zero).
You can make a copy of a VM chain with the routine
VMCopyVMChain()
. This routine copies the entire chain to a specified file, which may be the same as the source file. The blocks in the duplicate chain will have the same user ID numbers as the corresponding original blocks. The routine takes three arguments: the handle of the source file, the
VMChain
of the source chain or item, and the handle of the destination file. It copies the chain or item and returns the
VMChain
of the duplicate structure. As noted, if the low word of the
VMChain
is null, the high word will be the VM handle of the head of the chain. The geode must have both files open when it calls this routine.
Several utilities are provided for working with
VMChain
types. They are implemented as preprocessor macros, so they are very fast. The macro VMCHAIN_IS_DBITEM()
is passed a
VMChain
and returns non-zero if the VMChain identifies a DB item (
i.e.
, if the low word is non-zero) or zero if the VMChain identifies a VM chain. The macro VMCHAIN_GET_VM_BLOCK
() is passed a
VMChain
containing the block handle to a VM chain. It returns the high word,
i.e.,
the chain's VM block handle.
Finally, the macro VMCHAIN_MAKE_FROM_VM_BLOCK() takes a
VMBlockHandle
value and casts it to type
VMChain
.
GEOS SDK TechDocs
|
| 4.1 Structure of a VM Chain
| 5 Huge Arrays