/*
     How to call:
       GetRootsOfFilterMatches(Convert.ToInt64("9"));
     */ 
public HierarchySupportList GetRootsOfFilterMatches(long reqID)
{
  /*
    Get requirements that match or have descendants that match a filter
     Determine if a member of the list matches the filter


    ###############################################################
     This example shows the use of the IHierarchyFilter to determine
     which sub-trees under a specific requirement contain at least
     one requirement that matches the filter.

     The example runs on a requirement tree with the requirements below.
     Each requirement has as ParentID the ID of the requirement one step
     above according to the numbers that are part of the name.
     For example, the ParentID of Grandson 1.1.1 is the ID of Child 1.1,
     and the ParentID of Grandson 1.4.1.1 is the ID of Son 1.4.1

     The first item, Req1, is the root of the search tree. The
     ReqID argument to this example is Req1.ID

     The filter is:
        Requirement.Name = "*Son* OR SubNode*" AND
        Requirement.Product = "Emma OR Mansfield Park"
     The items that match the filter in the example are marked with
     an asterisk.
    ----------------------------------------------------------------------------
        Name               | Description              | Priority     | Product
    ----------------------------------------------------------------------------
        Req1               | Root of search tree      | 2-Medium     | Persuasion
        Child 1.1          | Child 1 of Req1          | 5-Urgent     | Persuasion
     *  Grandson 1.1.1     | GrandSon of Req1 1.1.1   | 2-Medium     | Emma
     *  Grandson 1.1.2     | GrandSon of Req1 1.1.2   | 2-Medium     | Emma

        Child 1.2          | Child 2 of Req1          | 4-Very High  | Mansfield Park
     *  Grandson 1.2.1     | GrandSon of Req1 1.2.1   | 5-Urgent     | Emma

        Child 1.3          | Child 3 of Req1          | 3-High      | Persuasion
        Child 1.3.1        | Grandchild of Req1 1.3.1 | 2-Medium    | Emma
        Child 1.3.1.1      | GreatGrandChild of Req1 1.3.1.1
                                                      | 2-Medium    | Mansfield Park
     *  GGGrndSon1.3.1.1.1 | Has Son in name          | 2-Medium    | Mansfield Park

        Child 1.4          | Child 4 of Req1          | 2-Medium    | Northanger Abbey
        Son 1.4.1          | GrandChild Req1          | 3-High      | Persuasion
        Grandson 1.4.1.1   | Grandson of Req 1.4      | 5-Urgent    | Persuasion
        Son 1.4.2          | Son 2 of Req 1.4         | 5-Urgent    | Persuasion

     *  Son 1.5            |Child 5 of Req1           | 3-High      |Emma
   */
  try
  {     
    HierarchyFilter hierFilter;
    HierarchySupportList reqHierL;
    Req rq;
    List reqL;

    ReqFactory reqF = (ReqFactory)tdConnection.ReqFactory;
    String tempStr = String.Empty;

    hierFilter = reqF.Filter;
    /*
      Get the parent nodes by setting KeepHierarchical = True.
      Note that this setting is required to get
      a HierarchySupportList. If KeepHierarchical
      is False or not set, HierarchyFilter.NewList
      returns a List, not a HierarchySupportList.
     */
    hierFilter.KeepHierarchical = true;
    /*
       Set a filter on RQ_FATHER_ID.
       The subtree with that node as its root
       is searched. The returned requirements are
       the direct children of the RQ_FATHER_ID node
       that either match the filter, or have descendants
       that match the  filter.
       Search in the subtree starting at the node passed
       as a parameter to this routine.
     */
    hierFilter["RQ_FATHER_ID"] = reqID.ToString();
    
    //Name filter matches "Son", "GrandSon", and "SubNode."
    hierFilter["RQ_REQ_NAME"] = "*Son* OR SubNode";
    
    //Set the product condition to a condition that matches some requirements.
    hierFilter["RQ_REQ_PRODUCT"] = "Emma OR 'Mansfield Park'";
    
    //Set the order of the results.
    hierFilter.Order["RQ_REQ_PRODUCT"] = 1;
    hierFilter.Order["RQ_REQ_PRIORITY"] = 2;

    reqHierL = (HierarchySupportList)hierFilter.NewList();
    tempStr = String.Format("Number of records found is {0}", reqHierL.Count);
    Debug.Print(tempStr);

    /*
      Number of records found is 4
    
       Note that there are 5 requirements that match the filter.
       The 4 that are returned are the direct children of the searched
       root node that have at least one match in the sub-tree of which they
       are the root. The number of matching descendants does not affect the result.
    
       Son 1.5 has no descendants that match the filter, but Son 1.5
       itself matches the filter. Since Son 1.5 matches the filter, IsInFilter is True.
     */
    for (int i = 1; i < reqHierL.Count; i++)
    {
      rq = reqHierL[i];
      tempStr = String.Format("{0} is in list = {1}   {2},  {3},  {4}", rq.Name, reqHierL.IsInFilter[i], rq.Product,
                              rq.Comment, rq.Priority);
      Debug.WriteLine(tempStr);
    }
    return reqHierL;

  }
  catch (Exception)
  {
    return null;
  }
}