GEOS SDK TechDocs|
| 
3.7 Routines for Ungrouped Items
DBCopyDBItem(), DBCopyDBItemUngrouped(), DBGroupFromGroupAndItem(), DBItemFromGroupAndItem(), DBCombineGroupAndItem()
You can duplicate a DB item with the routine
DBCopyDBItem()
. This routine takes five arguments: the handle of the source file, the source item's group-handle, the source item's item-handle, the handle of the destination file (which may be the same as the source file), and the handle of the destination group. The routine will allocate a new item in the specified file and group. It will then lock both items and copy the data from the source item to the destination. Finally, it will unlock both items and return the item-handle of the duplicate item.
The routine
DBCopyDBItemUngrouped()
is the same as
DBCopyDBItem()
, except that it allocates an ungrouped item in the specified file. It is passed the source file handle, the
DBGroupAndItem
value for the source item, and the destination file handle. It allocates an ungrouped item and returns its
DBGroupAndItem
value.
Remember, if you are allocating the duplicate in the same group as the source, you should only call this routine when the source item is unlocked (since its item-block may be compacted when the new item is allocated). If the destination is in another block, the source item may be locked or unlocked at your preference. If it is locked when you call
DBCopyDBItem()
, it will be locked when the routine returns.
All of the VM chain utilities work on DB items as well as VM chains. The routines are described in the VM chapter. To use a VM chain routine, pass the item's DBGroupAndItem value. For example,
VMCopyVMChain()
will allocate an "ungrouped" duplicate item in the specified file and return its
DBGroupAndItem
value.
To build a
DBGroupAndItem
value from the group-handle and item-handle, use the macro
DBCombineGroupAndItem()
. This macro takes the two handles and returns a
DBGroupAndItem
value. To extract the component handles from a
DBGroupAndItem
value, use the macros
DBGroupFromGroupAndItem()
and
DBItemFromGroupAndItem()
. These macros are passed a
DBGroupAndItem
value and return the appropriate component.
GEOS SDK TechDocs|
| 3.7 Routines for Ungrouped Items