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

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

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

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

    Some examples will help you understand the CONTAINING 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 CONTAINING( D, *, DEPTH=1 )
      2. FIND CONTAINING( C, *, DEPTH=1 )
      3. FIND CONTAINING( D, *, DEPTH=2 )

    The first query returns D (the containee), and C (the container).
    Similarly, the second query returns C and B. The third query
    returns D, C and B.

    Now consider the following 2 queries:

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

    Query four returns D (the containee), C (because it is on the
    path to A), B (because it is on the path) and A (which is the
    container being looked for). The fifth query does not return
    anything because A 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 CONTAINING function to determine nesting.

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

    CONTAINING( [ END=<containee> ],
                [ BEGIN=<container> ],
                [ 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 CONTAINING relationship, see the
    on-line help file SCACOMMANDS.