MakeHSym Function (ROM Call 0x282)

vat.h

HSym MakeHSym (HANDLE FldHandle, const SYM_ENTRY *SymPtr);

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