 |
SymAdd |
Function (ROM Call 0x5C) |
Adds a symbol.
SymAdd creates a new entry in the variable allocation table (VAT) for a symbol called
SymName, and returns the same type of result as the SymFind
function. If the symbol SymName already exists, SymAdd deletes the old
symbol before creating a new one (except if SymName is a folder name;
this case is considered an error). In case of an error, SymAdd returns HS_NULL.
This function may throw an error if the symbol already exists and it is locked.
See SymFind and DerefSym for more info.
SymName may also contain a folder name together with the symbol name
(separated by "\"). In this case, the symbol will be added in the given folder.
If the given folder does not exist, a dialog will appear which asks the user whether
a new folder will be created. If the answer is "NO", a "Folder" error will be thrown
(beware that opening a dialog may change the system font, so the use of
SaveScrState and RestoreScrState
is highly recommended in all cases when you expect that a folder creation dialog might appear).
If SymName does not contain a folder name, the symbol entry will be created
in the current active folder. This routine does not check for reserved symbol names,
so caution must be used when using this routine.
Note that SymAdd adds only an entry in the VAT with an empty handle; it does not allocate
any space for the actual variable. To actually create a variable named "example", do
the following (assuming that there were no errors in intermediate steps):
HSym hsym = SymAdd (SYMSTR ("example"));
// HeapAlloc must be executed before DerefSym
// because of possible garbage collection.
HANDLE handle = HeapAlloc (100);
SYM_ENTRY *SymPtr = (DerefSym (hsym));
MULTI_EXPR *VarPtr = HeapDeref (SymPtr->handle = handle);
Now, 100 bytes of space for the variable (together with the valid handle in the VAT entry) is
created, and VarPtr points to it (see HeapAlloc and
HeapDeref for more info). It does not mean that the actual
length of the variable must be 100 bytes: it is only the allocated amount of memory.
To create a concrete
variable, you must fill the space pointed to by VarPtr with valid data which depends on
the wanted type of the variable. The format of some variable types (STR, PIC, TEXT etc.) may
be found on doors.ticalc.org. For example, to create a
one-character long string variable with content "A", do the following:
VarPtr->Size = 4; // length of the variable data
VarPtr->Expr[0] = 0; // zero marks the beginning of the actual variable data
VarPtr->Expr[1] = 'A'; // actual data
VarPtr->Expr[2] = 0; // end-of-string marker
VarPtr->Expr[3] = STR_TAG; // the last byte is the type (see STR_TAG)
Note: It is very dangerous to add a new entry in the VAT without allocating a memory
space, and without assigning the handle in the entry. I didn't check whether a real
TI-89 crashes after this, but the debugger in VTI crashes!? Rusty, this is a bug...
Uses: MakeHSym, ROM Call 0x439
Used by: cmd_blddata, fopen
See also: SymAddMain, FolderAdd, MULTI_EXPR