SymFindFirst Function (ROM Call 0x6C)

vat.h

SYM_ENTRY *SymFindFirst (SYM_STR SymName, unsigned short Flags);

Begins looping through the VAT.

SymFindFirst searches for the first symbol entry in the variable allocation table which satisfies the requirements given by the parameters Flags and SymName (see SYMSTR for information about symbol names), and sets some internal pointers so that SymFindNext and SymFindPrev may be called to traverse the VAT. SymName is required only for some values of Flags (you can set it to NULL otherwise). Flags is a collection of binary flags defined in the enum FindOptions. These flags also determine how subsequent calls of SymFindNext and SymFindPrev will be interpreted.

If Flags is 0 (i.e. no flags are given), SymFindFirst and subsequent calls to SymFindNext and SymFindPrev loop only through the list of folders. In this case, SymName is ignored.

The following flags are defined:

FO_RECURSE Loop through all folders including their symbols. Naturally, SymName is still ignored. Subsequent calls to SymFindNext will continue searching through the whole variable allocation table, including both the folder table and the variable tables associated with each folder. More precisely, after each folder, the complete variable table for this folder will be browsed before the next folder is reached. This flag can be used together with all other flags except FO_SINGLE_FOLDER and FO_RETURN_FOLDER.
FO_SKIP_TEMPS Skip temporary folders when looping through the folder table. See FolderAddTemp for more information about temporary folders. This flag cannot be used together with FO_SINGLE_FOLDER, obviously.
FO_SKIP_COLLAPSE Skip variables in collapsed folders. Folders can be collapsed only since AMS 2.00; therefore this flag has no effect if the AMS version is lower than 2.00 (but it is still defined). This flag can only be used if FO_RECURSE is set as well.
FO_RETURN_TWINS Return the temporarily hidden equivalents of twin entries in the archive as well, which is normally not the case. See SymAddTwin for more information about twin entries. Of course, this does not have any effect if neither FO_RECURSE nor FO_SINGLE_FOLDER are included in Flags (i.e. if only folder names are returned).
FO_SINGLE_FOLDER Loop through all symbols in the folder identified by SymName, but do not return the folder name itself. This flag may be used together with FO_RETURN_FOLDER and FO_SKIP_TWINS, but not with any other flag.
FO_RETURN_FOLDER This flag can only be set if FO_SINGLE_FOLDER is set as well. It slightly alters the meaning of FO_SINGLE_FOLDER so that SymFindFirst returns the SYM_ENTRY structure of the folder identified by SymName, and subsequent calls to SymFindNext will return all symbols in that folder.

SymFindFirst returns the pointer to the symbol entry in the VAT, or NULL if there are no symbols which satisfy the given requirements. Here is an example how to (legally) create a list of all variable names in the main folder:

counter = 0;
SymPtr = SymFindFirst (SYMSTR ("main"), FO_SINGLE_FOLDER);
while (SymPtr)
{
  strcpy (names[counter++], SymPtr->name);
  SymPtr = SymFindNext ();
}
If you want to create a list of all folder names, simply change
SymPtr = SymFindFirst (SYMSTR ("main"), FO_SINGLE_FOLDER);
in the previous example to
SymPtr = SymFindFirst (NULL, 0);
Note: Since this routine and subsequent calls to SymFindNext and SymFindPrev return direct pointers to the symbol table, heap compression will cause subsequent results to be invalid or may crash the system. In other words, heap compression will invalidate all pointers returned necessitating another call to SymFindFirst. Therefore locking the folder table (using FolderOp) during the complete operation is highly recommended.


Uses: SymCmp, TokToStrN, strcmp, _mu16u16
Used by: FindProgramVar, FolderCur, ResetSymFlags, HeapWalk, VarOpen, LoadDLL, ERD_process, EV_defaultHandler, EV_eventLoop, handleVarLinkKey, FFindFirst, HomeExecute, LIO_Receive, OSLinkCmd, VarCreateFolderPopup, gr_del_locals, Regraph, ROM Call 0x40D


See also: SymFindNext, SymFindPrev, SymFindFolderName