CONTAINING

   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.