 |
SymFindFirst |
Function (ROM Call 0x6C) |
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