SymFindFirst.hsf 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119
  1. [Main]
  2. Name=SymFindFirst
  3. Type=Function
  4. Subtype=ROM Call
  5. Header Files=vat.h
  6. Definition=SYM_ENTRY *SymFindFirst (SYM_STR SymName, unsigned short Flags);
  7. See Also=SymFindNext, SymFindPrev, SymFindFolderName
  8. [ROM Call]
  9. Index=$6C
  10. [Description]
  11. Begins looping through the VAT.
  12. [Explanation]
  13. SymFindFirst searches for the first symbol entry in the variable allocation
  14. table which satisfies the requirements given by the parameters <I>Flags</I>
  15. and <I>SymName</I> (see <A HREF="$$LINK(SYMSTR)">SYMSTR</A> for information
  16. about symbol names), and sets some internal pointers so that
  17. <A HREF="$$LINK(SymFindNext)">SymFindNext</A> and
  18. <A HREF="$$LINK(SymFindPrev)">SymFindPrev</A> may be called to traverse the
  19. VAT. <I>SymName</I> is required only for some values of <I>Flags</I> (you
  20. can set it to <A HREF="$$LINK(alloc.h/NULL)">NULL</A> otherwise).
  21. <I>Flags</I> is a collection of binary flags defined in the enum
  22. <A HREF="$$LINK(FindOptions)">FindOptions</A>. These flags also determine how
  23. subsequent calls of <A HREF="$$LINK(SymFindNext)">SymFindNext</A> and
  24. <A HREF="$$LINK(SymFindPrev)">SymFindPrev</A> will be interpreted.
  25. <BR><BR>
  26. If <I>Flags</I> is 0 (i.e. no flags are given), SymFindFirst and subsequent
  27. calls to <A HREF="$$LINK(SymFindNext)">SymFindNext</A> and
  28. <A HREF="$$LINK(SymFindPrev)">SymFindPrev</A> loop only through the list of
  29. folders. In this case, <I>SymName</I> is ignored.
  30. <BR><BR>
  31. The following flags are defined:
  32. <BR><BR>
  33. <TABLE BORDER CELLPADDING="3">
  34. <TR>
  35. <TD VALIGN="TOP">FO_RECURSE</TD>
  36. <TD>Loop through all folders including their symbols. Naturally,
  37. <I>SymName</I> is still ignored. Subsequent calls to
  38. <A HREF="$$LINK(SymFindNext)">SymFindNext</A> will continue searching
  39. through the whole variable allocation table, including both the folder
  40. table and the variable tables associated with each folder. More
  41. precisely, after each folder, the complete variable table for this
  42. folder will be browsed before the next folder is reached.
  43. This flag can be used together with all other flags except
  44. FO_SINGLE_FOLDER and FO_RETURN_FOLDER.</TD>
  45. </TR>
  46. <TR>
  47. <TD VALIGN="TOP">FO_SKIP_TEMPS</TD>
  48. <TD>Skip temporary folders when looping through the folder table. See
  49. <A HREF="$$LINK(FolderAddTemp)">FolderAddTemp</A> for more information
  50. about temporary folders. This flag cannot be used together with
  51. FO_SINGLE_FOLDER, obviously.</TD>
  52. </TR>
  53. <TR>
  54. <TD VALIGN="TOP">FO_SKIP_COLLAPSE</TD>
  55. <TD>Skip variables in collapsed folders. Folders can be collapsed only
  56. since AMS 2.00; therefore this flag has no effect if the AMS version is
  57. lower than 2.00 (but it is still defined). This flag can only be used
  58. if FO_RECURSE is set as well.</TD>
  59. </TR>
  60. <TR>
  61. <TD VALIGN="TOP">FO_RETURN_TWINS</TD>
  62. <TD>Return the temporarily hidden equivalents of twin entries in the
  63. archive as well, which is normally not the case. See
  64. <A HREF="$$LINK(SymAddTwin)">SymAddTwin</A> for more information about
  65. twin entries. Of course, this does not have any effect if neither
  66. FO_RECURSE nor FO_SINGLE_FOLDER are included in <I>Flags</I> (i.e. if
  67. only folder names are returned).</TD>
  68. </TR>
  69. <TR>
  70. <TD VALIGN="TOP">FO_SINGLE_FOLDER</TD>
  71. <TD>Loop through all symbols in the folder identified by <I>SymName</I>,
  72. but do not return the folder name itself.
  73. This flag may be used together with FO_RETURN_FOLDER and FO_RETURN_TWINS,
  74. but not with any other flag.</TD>
  75. </TR>
  76. <TR>
  77. <TD VALIGN="TOP">FO_RETURN_FOLDER</TD>
  78. <TD>This flag can only be set if FO_SINGLE_FOLDER is set as well. It
  79. slightly alters the meaning of FO_SINGLE_FOLDER so that SymFindFirst
  80. returns the <A HREF="$$LINK(SYM_ENTRY)">SYM_ENTRY</A> structure of
  81. the folder identified by <I>SymName</I>, and subsequent calls to
  82. <A HREF="$$LINK(SymFindNext)">SymFindNext</A> will return all symbols
  83. in that folder.</TD>
  84. </TR>
  85. </TABLE>
  86. <BR>
  87. SymFindFirst returns the pointer to the symbol entry in the VAT, or
  88. <A HREF="$$LINK(alloc.h/NULL)">NULL</A> if there are no symbols which
  89. satisfy the given requirements. Here is an example how to (legally) create a
  90. list of all variable names in the main folder:
  91. <PRE>counter = 0;
  92. SymPtr = SymFindFirst (SYMSTR ("main"), FO_SINGLE_FOLDER);
  93. while (SymPtr)
  94. {
  95. strcpy (names[counter++], SymPtr-&gt;name);
  96. SymPtr = SymFindNext ();
  97. }
  98. </PRE>
  99. If you want to create a list of all folder names, simply change
  100. <PRE>SymPtr = SymFindFirst (SYMSTR ("main"), FO_SINGLE_FOLDER);
  101. </PRE>
  102. in the previous example to
  103. <PRE>SymPtr = SymFindFirst (NULL, 0);
  104. </PRE>
  105. <B>Note:</B> Since this routine and subsequent calls to
  106. <A HREF="$$LINK(SymFindNext)">SymFindNext</A> and
  107. <A HREF="$$LINK(SymFindPrev)">SymFindPrev</A> return direct pointers to the
  108. symbol table, heap compression will cause subsequent results to be invalid or
  109. may crash the system. In other words, heap compression will invalidate all
  110. pointers returned necessitating another call to SymFindFirst. Therefore
  111. locking the folder table (using <A HREF="$$LINK(FolderOp)">FolderOp</A>)
  112. during the complete operation is highly recommended.
  113. [References]
  114. In=FindProgramVar, FolderCur, ResetSymFlags, alloc.h/HeapWalk, dialogs.h/VarOpen, dll.h/LoadDLL, error.h/ERD_process, events.h/EV_defaultHandler, events.h/EV_eventLoop, events.h/handleVarLinkKey, files.h/TIOS_FFindFirst: FFindFirst, homescr.h/HomeExecute, link.h/LIO_Receive, link.h/OSLinkCmd, menus.h/VarCreateFolderPopup, unknown.h/gr_del_locals, unknown.h/Regraph, unknown.h/_ROM_CALL_40D
  115. Out=SymCmp, TokToStrN, string.h/strcmp, unknown.h/_mu16u16