VMS Help SCA, SCA Topics, CONTAINED_BY  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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.