/sys$common/syshlp/helplib.hlb SCA, SCA Topics, Basic Query Concepts  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    This section covers some of the basic concepts underlying SCA
    queries.

    You may want to have a hardcopy of this section. The directions
    for producing a hardcopy are as follows:

    1. Place the contents of Basic_Query_Concepts in a printable file
       by typing the following command at the DCL command line:

         $ HELP/OUTPUT=BASIC_QUERY_CONCEPTS.TXT -
         _$ SCA SCA_Topics Basic_Query_Concepts

    2. Print BASIC_QUERY_CONCEPTS.TXT from the DCL command line as
       follows:

         $ PRINT BASIC_QUERY_CONCEPTS.TXT

    What Queries Are

    An SCA library is a collection of information about your source
    code. This includes information, such as the names and locations
    of all variables in your code, all the places where routines
    are called and what their arguments are, and many other kinds
    of information.

    Issuing a query is the process of selecting some of this
    information from the library. By giving a query expression with
    the FIND command, you specify exactly what information you want to
    retrieve from the library.

    Occurrences

    An occurrence is any instance of an entity in your program. An
    entity can be any language construct, such as a variable, a
    routine, or a constant. To further clarify this, consider the
    following code fragment (not written in a particular language):

      1   MODULE myprog;
      2
      3   VAR i,j;
      4
      5   ROUTINE foo()
      6   BEGIN
      7       i = 5;
      8       j = i;
      9   END;
      10  END;

    The code contains four entities (myprog, foo, i, j). There is one
    occurrence each of the module myprog, and the routine foo. The
    variable i, however, has three occurrences, and the variable j has
    two.

    Attribute Selection

    Attribute selection is a query that selects occurrences based
    on certain attributes. For example, you can have SCA return all
    occurrences in which the name attribute is XYZ. The following
    sections list the attributes used for selection.

    NAME Attribute

    Generally, you think of entities in you program as having
    only a name. In fact, the name of an entity is only one of its
    attributes. What you are doing when you give the basic query FIND
    X, is asking for all occurrences in the library that have the name
    attribute X. (The query FIND X is equivalent to the query FIND
    NAME=X. NAME= is the default attribute, so it may be omitted.)

    SYMBOL_CLASS Attribute

    The symbol class attribute describes an occurrence in terms
    of language constructs. In the previous example, myprog is a
    MODULE, foo is a ROUTINE, and i and j are variables. Thus, you
    could ask SCA to find things based on the symbol class only. For
    example, you can find all the routines in the library by giving
    the following query: FIND SYMBOL_CLASS=ROUTINE

    Note that MODULE, ROUTINE, and VARIABLE are SCA keywords for
    symbol classes. Because different languages use different
    terminology, there is a need to understand how the SCA language-
    independent terms relate to the language-specific terms. We have
    provided tables to help you match the SCA terms to the specific
    language constructs for all the languages that support SCA. See
    the Getting_Started help subtopics for specific languages.

    OCCURRENCE Attribute

    The occurrence class attribute allows you to select occurrences
    based on attributes specific to the occurrence. In the previous
    example, on line 3 the occurrence of the variable i has an
    occurrence class of PRIMARY. On line 7, the occurrence has
    an occurrence class of WRITE, and on the following line, its
    occurrence class is READ. To find all entities that are declared
    in your system, specify the following query:

    FIND OCCURRENCE=PRIMARY

    Note that as with symbol classes, there is a need to understand
    the relationship between the SCA occurrence class keywords and
    the equivalent language terminology. See the Getting_Started help
    subtopics for specific languages.

    FILE_SPEC Attribute

    Another attribute of all occurrences is the name of the file in
    which they occur. If the previous example program was in a file
    called MYPROG.BAR, then the following query would return all the
    occurrences found in the file; in this case, all occurrences of
    myprog, foo, i, and j:

    FIND FILE_SPEC="MYPROG.BAR"

    SYMBOL DOMAIN Attribute

    The domain of an entity defines the scope within the source over
    which the entity is known. Variables or routines, for example,
    may be local to a particular module, or they might be known to all
    modules in a system. To find all occurrences of entities that are
    known throught your system, specify the following query:

    FIND DOMAIN=GLOBAL

    See the Getting_Started help subtopics for specific languages.

    Basic Queries

    You have already seen examples of the most basic type of query,
    that is a query based on the selection of just one attribute.
    These examples are:

    FIND X
    FIND SYMBOL=ROUTINE
    FIND OCCURRENCE=PRIMARY
    FIND DOMAIN=GLOBAL
    FIND FILE_SPEC="MYPROG.BAR"

    Each of these queries results in a set of occurrences. Often,
    the result of such a query contains more information than you
    really want. You can explicitly indicate the result you want by
    specifying multiple attributes and combining them by using set
    operations. For example, if you only want the ROUTINES named
    X (rather than all items named X or all routines), specify the
    following query expression:

    FIND X AND SYMBOL=ROUTINE

    In the previous example, the set operator AND was used to take the
    intersection of the two sets. The other set operators available
    are OR, XOR, and NOT. In this manner, you can combine attribute
    selection expressions using multiple set operators. For example:

    FIND (X OR Y ) AND SYMBOL=ROUTINE AND OCCURRENCE=CALL

    This query finds all call references to routines named X or Y.

    Relationship Queries

    You have already learned how to select occurrences based on
    their attributes. The following section describes how to select
    occurrences based on their relationship with other occurrences.

    Calls Relationship

    The most common of these relationships is the calls relationship.
    SCA provides two functions: CALLING and CALLED_BY. With these
    functions, you can display the call tree structure of your
    program. The most basic format of the query expression is as
    follows:

    FIND CALLED_BY FOO

    In this example, the result shows a structured display of all the
    routines that FOO directly calls. You can also display routines
    that call FOO as follows:

    FIND CALLING FOO

    The previous two queries answer the questions, "Who is called by
    FOO?" and, "Who is calling FOO?" respectively.

    The full syntax of the relationship functions is complex, and
    each relationship function is described in more detail under SCA_
    Topics. Without explaining why the parentheses are necessary,
    and emphasizing that the order of parameters is important, the
    following examples shows one more useful feature of relationship
    functions. It is possible to get a call tree of arbitrary depth by
    giving the following query:

    FIND CALLED_BY (FOO, DEPTH=ALL )

    This returns a display showing not only the routines called
    directly by FOO, but also the routines that they in turn call,
    for all levels. You can replace the keyword ALL with any positive
    integer to limit the depth of the call tree.

    Contains Relationship

    Another relationship available through SCA is the contains
    relationship, which is obtained through the CONTAINING and
    CONTAINED_BY functions. These functions have the same syntax as
    the calls functions.

    The CONTAINED_BY function returns all entities logically contained
    within the given parameter. For example, the query FIND CONTAINED
    FOO returns two occurrences of i and one occurrence of j, in the
    code fragment that follows:

      1   MODULE myprog;
      2
      3   VAR i,j;
      4
      5   ROUTINE foo()
      6   BEGIN
      7       i = 5;
      8       j = i;
      9   END;
      10  END;

    Similarly, the following query returns the occurrence of the
    module MYPROG:

    FIND CONTAINING FOO

    Types Relationship

    The types relationship consists of the two functions TYPING
    and TYPED_BY. These functions also have the same syntax as the
    previous functions. The TYPED_BY function returns type trees. This
    is useful if there are many user-defined types in your system,
    particularly if they are complex record structures. The TYPING
    function returns the type of its argument.

    For more information about all the relationship functions, see the
    help topic for each relationship.