 |
MakeHSym |
Function (ROM Call 0x282) |
Makes a HSym structure.
MakeHSym is an internal function, used very often in other TIOS routines. It converts the
VAT symbol entry pointed to by SymPtr which belongs to the folder associated with
handle FldHandle to the HSym structure. As HSym-s are basically a
combination of the folder’s handle and the offset of a symbol into that
folder, they are valid until a symbol is added or removed from the folder
they belong to. Dereferencing them with DerefSym produces a direct
pointer to the symbol entry, but such pointer are not valid after a heap compression is done.
The main usage of MakeHSym is when you need to preserve a pointer to the symbol entry after
a heap compression, like in following example:
hsym = MakeHsym (FldHandle, SymPtr);
// Something that may cause heap compression...
SymPtr = DerefSym (hsym);
In this example, an eventual heap compression would cause the pointer to be invalid
since it is a direct pointer into memory. So the SymPtr is converted to a
HSym structure with MakeHsym (along with the handle of the folder that the
symbol belongs to). After the code that may cause heap compression is
executed, the HSym is converted back into a SYM_ENTRY pointer with
DerefSym.
Used by: AddSymToFolder, FindSymInFolder, SymAdd, SymAddMain, SymAddTwin, SymFind, SymFindHome, SymFindMain, VarRecall, VarStore
Deprecated alias: MakeHsym