SymAdd Function (ROM Call 0x5C)

vat.h

HSym SymAdd (SYM_STR SymName);

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