This section covers some of the basic concepts underlying SCA
queries.
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.