Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

                                             ◄Up► ◄Contents► ◄Index► ◄Back►
─────PWB Extensions─────────────────────────────────────────────────────────
 
  Syntax:  PCMD GetListHandle( char *ListName, flagType fCreate );
 
  Returns: Handle for the list; NULL if the list could not be found or
           was not created.
 
  See:    AddStrToList, ClearList, ForFile, GetListEntry, NameToFunc,
          ScanList, SelectFiles, ◄PWB Mgreplist Macro►
 
     GetListHandle finds an existing list macro and creates new lists.
 
     A PWB list is any text macro consisting of multiple space-
     delimited tokens. Mgreplist is a special list macro that PWB uses
     for searching multiple files.
 
     For example, the following TOOLS.INI statements define a nested
     list:
 
          Headers := "*.H  *.INC"
          Objects := "*.OBJ
          All     := "*.CPP *.C *.ASM" headers objects
 
     In the All list, "*.CPP" is element 0, "*.C" is element 1, and so
     on. Lists can contain other previously defined lists, such as the
     Headers and Objects lists. The Headers list is element 3 of the All
     list. You can access list entries by index number with the
     GetListEntry function.
 
     To process a list, you must first get its handle by passing its
     name to GetListHandle. If <fCreate> is TRUE, the list is
     created if it does not already exist; otherwise, GetListHandle
     returns NULL if the list doesn't exist.
 
     The handle (PCMD type) value of the list can then be passed to
     GetListEntry or ScanList for processing.
 
     Lists can be created based on user input with SelectFiles or by
     using AddStrToList. You can also define a list macro using fExecute
     and the PWB Assign function. For example:
 
     fExecute("Arg \"Files:=\\\"*.TXT *.DAT MASTER.LST\\\"\" Assign");
 
     defines a macro list named Files with the definition "*.TXT *.DAT
     MASTER.LST".
                                    -♦-