tscan$ (6) --- traverse subtree of the file system       09/10/84


          | _C_a_l_l_i_n_g _I_n_f_o_r_m_a_t_i_o_n

                 integer function tscan$ (path, buf, clev, nlev, action)
                 character path (MAXPATH)
          |      integer buf (MAXDIRENTRY), clev, nlev, action

                 Library:  vswtlb  (standard Subsystem library)


            _F_u_n_c_t_i_o_n

                 'Tscan$'  is  used  to traverse a subtree of the file system
                 rooted at 'path'.  Each time 'tscan$' is called, it  returns
                 the  entry  of  the  next  file  (or directory) in 'buf', as
                 controlled by 'action' (discussed  below).   'Clev'  is  the
                 current  level  of  descent  into  the  subtree;  it must be
                 initialized to zero before calling 'tscan$'.  'Nlev' is  the
                 maximum level of descent into the subtree; 'clev' will never
                 be  greater  than  'nlev'.   The function return is OK if an
                 entry was successfully fetched, ERR if the fetch was  unsuc-
                 cessful,  EOF  when  the entire subtree has been scanned, or
                 EOD if a directory has been completely scanned and the  EOD-
                 PAUSE action has been specified (see below).

                 The  argument  'action' is a bit mask composed of the sum of
                 several action codes.   The  codes  POSTORDER  and  PREORDER
                 control  the  visitation of directories.  If POSTORDER is in
                 effect, each directory entry will be returned after all  the
                 files in the directory have been visited.  If PREORDER is in
                 effect,  each directory entry will be returned before any of
                 the files in the directory have  been  visited.   The  first
                 element  of 'buf' is set to 0 or 1 to indicate a preorder or
                 postorder encounter, respectively.  Note that both  PREORDER
                 and POSTORDER may be specified; in this case, each directory
                 in  the  subtree is visited twice.  The code EODPAUSE causes
                 'tscan$' to return the code EOD when it completes  the  scan
                 of  a directory.  Finally, the code REATTACH causes 'tscan$'
                 to insure that the user is always attached to the  directory
                 currently  being scanned.  (Maintaining the attach point can
                 be expensive, so it has been made optional.)


            _I_m_p_l_e_m_e_n_t_a_t_i_o_n

                 Various pieces of state information are retained in the com-
                 mon block 'c$tscn'.  'Tscan$' changes state as it scans  the
                 subtree,  deciding  when  to ascend, descend, pause, get the
                 next entry, etc.  The algorithm is a simple tree  traversal,
                 complicated mainly by the difficulties of error handling and
                 maintaining the attach point.


            _A_r_g_u_m_e_n_t_s _M_o_d_i_f_i_e_d

                 buf, clev, path



            tscan$ (6)                    - 1 -                    tscan$ (6)




            tscan$ (6) --- traverse subtree of the file system       09/10/84


            _C_a_l_l_s

          |      at$swt,  ctoc,  error, expand, equal, follow, move$, upkfn$,
          |      Primos at$hom, Primos dir$rd, Primos gpas$$, Primos  srch$$,
          |      Primos texto$


            _B_u_g_s

                 No  more  than  one  instance of 'tscan$' may be active at a
                 given time.


            _S_e_e _A_l_s_o

          |      Primos dir$rd lf (1), del (1), chat (1), cp (1), follow (2)










































            tscan$ (6)                    - 2 -                    tscan$ (6)