Brief Index      Full Index      Events Index      I.M. Reference

Show_Original_Key

Functions

HC_KEY Show_Original_Key (HC_KEY key)

Function Documentation

HC_KEY Show_Original_Key ( HC_KEY  key)

Returns the original (non-renumbered) version of a key.

Parameters:
key- Unique (possibly renumbered) numeric identifier, pointing to an object in the database.
Returns:
key - Unique numeric identifier pointing to an object in the database. The return value will always be negative.

DETAILS

Renumbered keys are always non-negative, whereas non-renumbered keys are always negative (numbers based on arithmetic on HOOPS' internal memory pointer). Locally renumbered keys are invalid except when their owning segment is open, and can thus be inconvenient to deal with. The "original key" as returned by this function is guaranteed to be globally unique throughout the entire system. It can be a useful way of referring to database entities since the original key does not require opening a segment to get into the proper context.

NOTES

As always, if the input key is locally renumbered, the containing segment must be open. If the input was not renumbered to begin with, the output will be equal to the input.

The return value with be -1 if the input was renumbered and invalid. Behavior is undefined if input was non-renumbered and invalid.

Non-renumbered original keys change if an entity is deleted and reinserted. They cannot be effectively used as persistent identifiers between program executions.

See also:
Renumber_Key, Show_Key_Status, Show_Selection_Original_Key

Brief Index      Full Index      Events Index      I.M. Reference