CONTAINED_BY

   The CONTAINED_BY function is a relationship function. It finds
   occurrences that have a CONTAINED_BY relationship between them. In
   its most common form, the function format is as follows:

   CONTAINED_BY( <container>, <containee>, DEPTH={<number> | ALL} )

   In this format, <container> and <containee> can be any legal query
   expression, and <number> is a positive integer.

   Some examples will help you understand this function. The diagram
   that follows applies to these examples.



             A (module)
             +-------------------------+
             |                         |
             |  B (routine)            |
             |  +-------------------+  |
             |  |                   |  |
             |  |  C (routine)      |  |
             |  |  +-------------+  |  |
             |  |  |             |  |  |
             |  |  | D (variable)|  |  |
             |  |  |             |  |  |
             |  |  |             |  |  |
             |  |  +-------------+  |  |
             |  |                   |  |
             |  +-------------------+  |
             |                         |
             | E (variable)            |
             |                         |
             +-------------------------+

   Consider the following queries:

     1. FIND CONTAINED_BY( A, *, DEPTH=1 )
     2. FIND CONTAINED_BY( C, *, DEPTH=1 )
     3. FIND CONTAINED_BY( A, *, DEPTH=2 )

   The first query returns A (the container), B (a containee), and
   E (a containee). Similarly, the second query returns C and D.
   The third query returns A, B, and C and E. The D variable is NOT
   included because it is not reachable at a depth of two.

   Now consider the following two queries:

     4. FIND CONTAINED_BY( A, D, DEPTH=ALL )
     5. FIND CONTAINED_BY( A, D, DEPTH=2 )

   Query four returns A (the container), B (because it is on the path
   to D), C (becasue it is on the path) and D (which is the containee
   being searched for). The fifth query does not return anything
   because the D variable cannot be reached at a depth of two.

   Where a container begins and ends is determined by the language
   syntax. These boundaries are reported to SCA by the compiler and
   used by the CONTAINED_BY function to determine nesting.

   The CONTAINED_BY function provides the power to return the exact
   nesting structure you want. The full format is as follows:

   CONTAINED_BY( [ END=<container> ],
                 [ BEGIN=<containee> ],
                 [ DEPTH={<number> | ALL} ],
                 [ RESULT=RESULT_KEYWORD ],
                 [ TRACE=query_expression ] )

   In the previous format, <containee> and <container> is any legal
   query expression, <number> is a positive integer, RESULT_KEYWORD
   can be STRUCTURE, NOSTRUCTURE, ANY_PATH, BEGIN, or END, and QUERY_
   EXPRESSION is any legal query expression.

   For a full description of the CONTAINED_BY relationship, see the
   on-line help file SCACOMMANDS. See also the help topic for the IN function,
   which is similar to the CONTAINED_BY relationship.