[SCA]
1 – Advanced Query Examples
The examples in this section use the SCA$EXAMPLE library. You are
encouraged to try these queries using the example library.
1. FIND CALLED_BY( END=translit, DEPTH=ALL)
This query gives the full call tree for TRANSLIT.
2. FIND CALLED_BY( END=translit, BEGIN=signal_duplicate, DEPTH=ALL)
This query returns all the call paths emanating from translit that
end up calling SIGNAL_DUPLICATE.
3. FIND CALLED_BY( translit, DEPTH=ALL, TRACE=(NOT OPEN*))
This query gives the full call tree for TRANSLIT, but does not
show any calls from items named OPEN*. Calls to items named OPEN*
appear in the call tree; however, items which are called by OPEN*
do not appear. Try the query without the trace expression and
compare the results when the TRACE is given.
4. FIND CALLED_BY( END=translit,
BEGIN=(NOT DOMAIN=PREDEFINED and NOT lib$*),
DEPTH=ALL )
This example leaves predefined functions and functions named
LIB$* out of the call graph. Functions such as CHR and WRITELN
in Pascal, MAX in FORTRAN, a builtin like _ADAWI in C, and so
forth are predefined. These functions are defined by the language,
not the programmer.
5. FIND IN( build_table and occ=comp, max_code )
This example finds all occurrences of MAX_CODE in the module
BUILD_TABLE. In this case, module has the same meaning as it
does in SHOW MODULE. This is the fastest way to limit a query to
occurrences in a particular module. The first parameter to the IN
function tells SCA in what container to look. The "and occ=comp"
part of the query ensures that the BUILD_TABLE you are looking
in is one of the modules displayed by SHOW MODULE, rather than
something else.
The second parameter to the IN function tells SCA what to look
for. This is faster than specifying the following:
FIND IN( build_table and occ=comp ) and max_code
Both queries in this example produce the same result.
Routines Used in a Module But Declared Elsewhere
In this example, you find functions that are used in a given
module but have their primary declaration in some other module.
This example is a multistep process that makes use of previous
queries. Each query in this section is numbered so that you can
refer to a specific query. If you refer to a query, adjust the
query name (for example, where @1 is used) to refer to the query
name you have created.
1. FIND IN( translit and occurrence=compilation_unit, -
symbol=function and domain=(global,inheritable) )
This query finds all occurrences of functions, either declarations
or references, in the module TRANSLIT.
You use "domain=(global,inheritable)" to limit the query only
to occurrence in which you are interested. Only global and
inheritable symbols can be imported because module-specific
symbols are from the same module, and predefined symbols come
from the language. Next, you have to remove any functions that
have their primary declaration in the module.
2. FIND @1 AND NOT EXPAND( @1 and occurrence=primary )
This query removes any functions that have a primary declaration
in the module TRANSLIT. What remains are those global or
inheritable functions that do not have a primary declaration in
TRANSLIT.
The EXPAND function in this query can be evaluated efficiently
by SCA. The parameter to EXPAND, @1 and occurrence=primary, can
be evaluated by looking at the result of query 1, so SCA does not
have to use the SCA library. Because the overall query does @1 AND
..., everything in the result is present in the result of query 1.
All we are doing is removing occurrences. In this case, SCA can
evaluate the whole query expression by looking at the result of
query 1 and does not have to use the SCA library.
Items Declared In a Module But Not Used Anywhere In the Module
In this example, you find occurrences of functions or variables
that are declared in a module but are not used in the module. This
example is a multistep process that makes use of previous queries.
The numbers by each query are used to refer to it later. If you
refer to a query, adjust the query name (for example, where @1 is
used) to refer to the query names you have created.
1. FIND IN( translit and occurrence=compilation_unit, -
symbol=(function, variable) )
This query finds all occurrences of functions or variables, either
declarations or references, in the module TRANSLIT.
2. FIND @1 AND NOT EXPAND( @1 and occurrence=reference )
This query removes from our first query any functions or variables
that have a reference in the module TRANSLIT. What remains are
those functions or variables that are not used anywhere in the
module.
The EXPAND function in this query can be evaluated efficiently
by SCA. The parameter to EXPAND, @1 and occ=reference, can be
evaluated just by looking at the result of query 1, so SCA does
not have to use the SCA library. Because the overall query does
@1 AND ..., everything in the result is present in the result of
query 1. All we are doing is removing items. In this case, SCA can
evaluate the whole query expression by looking at the result of
query 1, and does not have to use the SCA library.
Finding Unused Functions
This example finds functions or subroutines that are never used.
It provides several ways of solving the problem. Some of these are
easy to understand, but can be very slow on larger SCA libraries.
The more complex ones are intended to improve performance on
larger SCA libraries. They do not have a significant impact on
smaller libraries.
The first example finds unused functions only. Note that instead
of saying "occurrence=call" to find functions that are called, you
specify "occurrence=reference" to find functions that are used at
all. The query is as follows:
FIND symbol=function AND occurrence=primary -
AND NOT EXPAND( symbol=function and occurrence=reference )
On the SCA$EXAMPLE library, this query works well because it is
a small library. On a larger library, it may be too slow. To
evaluate this query, SCA must first evaluate "symbol=function
and occurrence=primary." It must then evaluate "symbol=function
and occurrence=reference" before doing any additional processing.
In this case, SCA has to do twice what is essentially the same
work. Also, SCA does not discard information about functions that
are referenced until the end, so it uses a lot of memory.
Using Previous Query Results to Find Unused Functions Faster
The next example also finds unused functions. However, it uses
previous query results, so the work is done only once. For this
reason, it is faster than the previous example. It also uses
somewhat less memory, but still not enough to make a difference on
a large library.
FIND symbol=function and occurrence=(primary,reference)
In the previous query, we find all the occurrences that we want to
use. We ignore the associated declarations at this point because
they are not essential to the query.
Next, we must select those functions that are not used as in the
following query:
FIND @1 AND occurrence=primary -
AND NOT EXPAND( @1 AND occurrence=reference )
This query removes from the list of functions in our system any
that are referenced, leaving only unreferenced functions. Because
you are using a previous query with all the information in it,
SCA does not have to access the SCA library, and performance is
generally faster.
However, on a large library, this may still be slow. The reason
for this is that it ends up keeping a list of all the functions
and all their references in memory.
Using Iteration to Find Unused Functions Faster
This is the most complex example. It includes some repetitive
parts that the query language does not provide directly. You
can do these using the callable interface, or by writing a .COM
procedure, or you can do the repetitive parts manually. This is
also the fastest form of the example and uses less memory.
Basically, you are going to split up the work into smaller pieces
to avoid having to keep everything in memory at the same time. In
this example, you process one module at a time, so you need to get
a list of modules first. You can do this by entering the following
query:
1. FIND occurrence=compilation_unit
In the next step, you have to loop through each of the
occurrences found in step 1. This part cannot be done directly
using the query language. You can do this using one of the
following methods:
o Do this manually, stepping through the occurrences in the
query one by one, and using INDICATED() in the following
queries where module_name is specified.
o Use the /DISPLAY options to specify only the name of each
occurrence found, capture the result in a file, and write
a command procedure to loop over the names. In this case,
you use "module_name and occurrence=compilation_unit" in the
following queries where module_name is specified.
o Use the callable interface. By writing a small program
using the callable interface, you can do the loop relatively
easily, using SCA$GET_OCCURRENCE and SCA$SELECT_OCCURRENCE.
In any case, you repeat the following steps for each of the
modules found in step 1.
2. FIND IN( module_name, symbol=function and occurrence=primary )
This step finds primary declarations of functions in the
current module. You want only primary declarations at this
stage because there may be some calls in other modules. In the
next step, you find any references to those functions:
3. FIND EXPAND( @2 )
This finds everything you need. At this point, what you do is
very similar to what you did for the examples in the previous
section.
4. FIND @3 and occurrence=primary -
AND NOT EXPAND( @3 and occurrence=reference )
This finds those functions in a particular module that are not
referenced anywhere. Steps 2 through 4 must be repeated for
each module.
2 – Basic Query Concepts
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:
$ between occurrences. These are produced by queries which involve
relationship functions.
8.51 – symbol
Any object in a program. For example, a FUNCTION, a VARIABLE, a
CONSTANT, or any of the entities with which a programmer typically
deals.
A symbol has occurrences. For example, the declaration of
a variable is an occurrence, and uses of the variable are
occurrences. SCA determines which occurrences belong to which
symbols using the rules of the language you are using. For
example, you may have two different variables named INDEX in
separate subroutines. According to the rules of your language,
these are usually different variables, so they are different
symbols for SCA.
It does not matter whether all occurrences of a symbol are in
a single compilation unit, or spread over several compilation
units. All the occurrences still belong to the same symbol. For
example, you may have a subroutine SUB1 in one module, and calls
to that subroutine in several other modules. These all appear as
occurrences of the same symbol, named SUB1.
The programmer and SCA should have the same definition of what
constitutes a unique item. SCA's term for a unique item is symbol.
8.52 – symbol_checks
A check that INSPECT performs on all occurrences of a symbol.
For example, INSPECT can ensure that there are both read and
write references to a variable. In this type of check, no single
occurrence is either correct or incorrect. If there are problems,
the problems are with the symbol as a whole.
8.53 – SYMBOL_CLASS
An attribute selection that identifies the type of symbol. Tells
you whether the symbol is a variable, constant, or some other
class. You can use the FIND command to find only symbols with
a particular symbol class. For example, you can specify "FIND
symbol=argument." You can abbreviate both "symbol" and "argument".
8.54 – symbol_class_selection_expression
The expression containing the symbol class for each symbol you
want to find.
8.55 – type_graph
A set of occurrences and relationships that describes a complex
data type. For example, a declaration of a record consists of a
record and some record components. Each record component has a
type, which may be another record, a pointer to the same record,
a basic data type such as integer, and so forth. In SCA, the type
graph connects all these together, with relationships connecting
the record to its components and the components to their types.
8.56 – TYPED_BY
See the SCA_Topics TYPED_BY help topic.
8.57 – TYPING
See the SCA_Topics TYPING help topic.
8.58 – union
The operation performed by the OR operator, which indicates that
SCA will accept any occurrence that matches either X or Y as
follows:
FIND X OR Y
8.59 – virtual_library
A library that allows you to split your SCA library into pieces.
Each piece is called a physical library. SCA works the same way
whether your virtual library has only one physical library or
several physical libraries.
Some of the reasons for using more than one physical library are
as follows:
o Physical libraries can be placed on more than one disk, if
there is not enough room on a single disk.
o Analysis date files can be loaded into more than one physical
library at the same time, to make LOAD run faster.
o A small personal physical library can be used to keep track of
your personal changes without affecting other users.
o A separate physical library can be used for each major
component in your system.
A single virtual library is a list of one or more physical
libraries. The order is important. A module in one physical
library hides the same module in physical libraries later on in
the list. This list of physical libraries is called a library
list.
8.60 – visible
See both appearance and visible modules.
8.61 – visible_modules
Modules that SCA can examine when performing a FIND or INSPECT
command. The current library list tells you what modules are
visible. All modules in the first library in the library list
are visible. Modules in the second library which are not in the
first library are visible. Modules in the third library which are
not in the first or second libraries are visible. Any module which
is not visible is hidden.
8.62 – wildcards
Wildcards are used to match more than one name at once. There
are two wildcards in SCA: the asterisk (*) and percent (%). For
example, in the name expression A*, the wildcard * will match any
number of characters, so this would match A, AB, ABC, AXYZ, and
so forth. The * wildcard matches any number of characters, and %
wildcard matches just one character. If you do not want SCA to use
* or % as a wildcard, you use an ampersand (&) to quote it. For
example, to find the single name *, you would use &*.
9 – Language Specific Tables
For information about SCA terms and corresponding language-
specific terminology, see the tables under the Getting_Started
help topic.
10 – Libraries
10.1 – Project Libraries
There are many ways you can organize the SCA libraries for your
project. Usually, there is one library (or set of libraries)
for the whole project. Each developer has a personal library
containing modules that they have changed but have not yet made
available to the entire project. However, if there is only one
developer working on the project, it makes more sense to use a
single SCA library.
There are many ways you can organize your project libraries. You
can have one project SCA library if it is a reasonable size. You
can use several libraries, one for each subsystem. You may want to
organize your SCA libraries the way your development environment
is organized. For example, have one SCA library for each CMS
library. If your project is divided into different subsystems,
you may want one SCA library for each subsystem.
For information on creating your own SCA library, see the help
topic Building_An_SCA_Library.
Examples of Typical Libraries
Consider a project with three developers: Paul, Mark, and Joanna.
The project consists of five different subsystems. Each subsystem
has its own SCA library in the following directories:
DISK1:[PROJECT.SUBSYSTEM1.SCA]
DISK1:[PROJECT.SUBSYSTEM2.SCA]
DISK1:[PROJECT.SUBSYSTEM3.SCA]
DISK2:[PROJECT.SUBSYSTEM4.SCA]
DISK2:[PROJECT.SUBSYSTEM5.SCA]
Each of the developers also has a personal SCA library as follows:
DISK1:[PAUL.SCA]
DISK2:[MARK.SCA]
DISK1:[JOANNA.SCA]
Paul uses the following command to set up his SCA libraries:
LSE Command> SET LIBRARY disk1:[paul.sca], -
_LSE Command> disk1:[project.subsystem1.sca], -
_LSE Command> disk1:[project.subsystem2.sca], -
_LSE Command> disk1:[project.subsystem3.sca], -
_LSE Command> disk2:[project.subsystem4.sca], -
_LSE Command> disk2:[project.subsystem5.sca]
Mark and Joanna use the same command, but the first library in the
list is their own SCA library.
When Paul changes a module in Subsystem 1, he compiles it
and loads it into his personal library in DISK1:[PAUL.SCA].
For Paul, this hides the old version of the module in
DISK1:[PROJECT.SUBSYSTEM1.SCA], so his SCA library is up to date
and consistent with his changes.
Mark and Joanna do not see Paul's changes in their SCA libraries
because they are not using the SCA library (DISK1:[PAUL.SCA])
that Paul updated. They still see the old version of the module in
DISK1:[PROJECT.SUBSYSTEM1.SCA].
Once Paul has completed his change, the nightly build
updates everything for Subsystem 1, replacing the module in
DISK1:[PROJECT.SUBSYSTEM1.SCA]. Now Mark and Joanna can both see
the change.
10.2 – Virtual Libraries
SCA can use more than one SCA library at the same time when doing
queries using the FIND and INSPECT commands. The list of SCA
libraries used for this is called a virtual library. The order
of SCA libraries in the library list is important. A module in
the first library in the library list will hide the same module
in other libraries, further on in the library list. For example,
suppose PROJECT_LIB has modules A, B, C and library MYLIB has
modules A, and D. You can set the library as follows:
LSE Command> SET LIBRARY mylib,project_lib
The modules visible in the virtual library would be A (from
MYLIB), B, and C (both from PROJECT_LIB) and D (from MYLIB).
There are many reasons for using more than one physical library as
your virtual library:
o Using more than one library, you can improve LOAD performance
by loading multiple libraries simultaneously. See the help
topic Reducing_LOAD_Time.
o You can use virtual libraries to allow several developers to
maintain a consistent view of their changes to a project,
without affecting the other developers, and without having
to copy the entire SCA library for each developer.
o You can put your SCA libraries on different disks or on
different nodes (using the SCA server). This improves
performance or takes advantage of the available disk space.
o You use the SET LIBRARY and SET NOLIBRARY commands to maintain
your virtual library list. You can use the /BEFORE and /AFTER
qualifiers to insert and remove libraries without having to
reenter a library list. You can specify libraries in your
library list using library numbers. For example, the command
SET NOLIBRARY 2 removes the second SCA library from the library
list.
11 – New Users
The Source Code Analyzer for OpenVMS (SCA) is an interactive cross-
reference and static analysis tool that works with many languages.
It can help you understand the complexities of a large software
project. Because it allows you to analyze and understand an entire
system, SCA is extremely useful during the implementation and
maintenance phases of a project.
SCA is included in the DECset Software Engineering Tools Package.
SCA is tightly integrated with the Language-Sensitive Editor for
OpenVMS (LSE). When SCA is used with LSE, you can interactively
edit, compile, debug, navigate, and analyze source code during a
single development session.
For more information, see the following topics:
o Basic_Query_Concepts - Describes some of the basic concepts
underlying SCA queries.
o Getting_Started - Provides subtopics with information about
getting started with specific languages.
o SCA_Tutorial - Provides a sample session that allows you to get
started after completing the session.
o Building_An_SCA_Library - Describes how to quickly create an
SCA library.
o Advanced_Query_Examples - Provides advanced examples using the
SCA$EXAMPLE library.
o Glossary - Provides definitions of SCA terms.
o Command_Categories - Lists the different types of SCA commands.
o Callable_Routines - Provides a complete description of each SCA
callable routine.
o Callable_SCA - Provides guidelines for using the SCA callable
interface.
o Libraries - Provides subtopics with information about project
libraries and virtual libraries.
o Reducing_LOAD_Time - Provides guidelines for reducing your LOAD
time.
o Quick_Reference_Card - Provides a pointer to the release
notes, which contain a quick reference card for the SCA query
language.
Under SCA_Topics, there is help information for specific keywords.
These keywords include attributes, relationships, and functions.
For example, you can request help on SCA_Topics SYMBOL_CLASS to
get information about the SYMBOL_CLASS attribute.
12 – Reducing LOAD Time
Loading an SCA library is a time-consuming operation. Here are
suggestions for reducing LOAD time:
o Virtual I/O Cache facility
SCA uses a large number of I/Os during LOAD. Disk caching can
greatly reduce the number of I/Os, and improve performance.
Your system manager can enable disk caching by setting the
VBN_CACHE_S SYSGEN parameter. Use SHOW MEMORY/CACHE to see
whether disk caching is enabled.
o Batch loads
Loading more than one module at a time is more efficient than
loading modules separately. For example, use LOAD *.ANA.
o Multiple libraries
With large software systems, it is a good idea to use more
than one SCA library and load them all simultaneously. This
can decrease the elapsed LOAD time considerably, especially
if the libraries are on separate disks. Using more than one
CPU also helps, but not as dramatically, because SCA loading
is mainly I/O intensive. For more information about how to use
multiple libraries, see the help subtopics under Libraries.
o Choice of Disk
SCA uses a large number of I/Os during LOAD. Loading an SCA
library on a slow, heavily used, or badly fragmented disk
causes the load to be less efficient.
o File Fragmentation and File Preallocation
If your SCA library is larger than 20K blocks, you should
consider preallocating the library when you create it.
SCA extends the library file by 1000 blocks at a time, so for
large libraries it extends the library many times, and this
may cause your SCA library to be badly fragmented.
Preallocate an SCA library with CREATE LIBRARY/SIZE=xxx, where
xxx is the size of the library in disk blocks. Use the size of
the SCA$EVENT.DAT file in your current SCA library directory as
the value to the /SIZE qualifier.
You can tell how badly your SCA libraries are fragmented by
using the following command:
$ DUMP/HEADER/BLOCK=COUNT=0 -
_$ DISK:[sca_library_directory]SCA$EVENT.DAT
The interesting portion of the output is the Map area. Each
retrieval pointer represents a contiguous section on the disk.
Because SCA extends SCA libraries 1000 blocks at a time, having
a lot of retrieval pointers smaller than this is a strong
indication that some defragmentation is needed.
o Using less disk space
Use LOAD/DELETE to delete .ANA files after they are successfully
loaded. This doesn't reduce LOAD time, but uses less disk space.
13 – Quick Reference Card
The following page contains a reference of the SCA query language.
It is intended to be printed and used as a Quick Reference Card.
ATTRIBUTE SELECTIONS: |RELATIONSHIP FUNCTIONS:
|
Name Class: |Short form:
---------- |-----------
<name-expression> |CALLED_BY(<caller>,<callee>,<depth>)
NAME=<name-expression> |CALLING(<callee>,<caller>,<depth>)
NAME=(<name-expression>,...) |
|CONTAINED_BY(<container>,<containee>,
Symbol Class: | <depth>)
------------- |CONTAINING(<containee>,<container>,
SYMBOL=<symbol-class-keyword> | <depth>)
SYMBOL=(<symbol-class-keyword>,...) |
|TYPED_BY(<type>,<typee>,<depth>)
Symbol Class keywords: |TYPING(<typee>,<type>,<depth>)
|
Argument, Component, Constant, |Long form:
Exception, File, Field, Function, |----------
Generic, Keyword, Label, Literal, |<rel-func>(END=<query-expression>,
Macro, Module, Package, Placeholder, | BEGIN=<query-expression>,
Procedure, Program, Psect, Routine, | DEPTH={<number> | ALL },
Subroutine, Tag ,Task, Type, Unbound, | RESULT=<result-keyword>,
Variable, Other, All, None | TRACE=<query-expression>)
|
Occurrence Class: |Result keywords:
----------------- |
OCCURRENCE=<occ-class-keyword> |Begin, End, [No]Structure, Any_path
OCCURRENCE=(<occ-class-keyword>,...) |
|OTHER FUNCTIONS:
Occurrence Class keywords: |----------
|
Declaration, Primary, Associated, |IN (END=<query-expression>,
Reference, Address, Call, | BEGIN=<query-expression>)
Command_line, Fetch, Include, |
Pointer, Precompiled, Read, Store, |EXPAND (<query-expression>)
Write, Other, All, None |
|@(<query-name>)
Domain Class: |
------------- |INDICATED() (NOTE: LSE required)
DOMAIN=<domain-class-keyword> |
DOMAIN=(<domain-class-keyword>,...) |NOT(<query-expression>)
|
Domain Class keywords: |
|
Global, Inheritable, Module_specific, |
Multi_module, Predefined, All, None |
|
File Class: |
---------- |
FILE=<filename-expression> |
FILE=(<filename-expression>,...) |
|
OPERATORS: |
---------- |
AND, OR, XOR, Pathname (\ or \\) |
|
ATTRIBUTE SELECTION EXPRESSIONS: |
<attri-select> [<op> <attri-select>]...|
14 – SCA Tutorial
This tutorial is for character cell LSE and SCA on
the OpenVMS platform. For a tutorial on the
DECwindows interface, please see the DECset Guide to
Source Code Analyzer.
If you do not have DECwindows, you may want to have a hardcopy
of this tutorial to follow it along interactively. The directions
for producing a hardcopy are as follows:
1. Place the contents of SCA_Tutorial in a printable file
by typing the following command on the DCL command line:
$ 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.
20 – 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.
21 – DOMAIN
DOMAIN is an attribute of an occurrence that determines the scope
of the symbol defined. It is the range of source code in which a
symbol has the potential of being used.
For example, A BLISS OWN declaration creates a symbol that has
a module-specific symbol domain; it cannot be used outside that
module. On the other hand, a BLISS GLOBAL declaration creates a
symbol that has a multimodule symbol domain; it has the potential
of being used in more than one module.
The format for DOMAIN is as follows:
DOMAIN=(keyword[,keyword...])
The keyword can be one of the following:
o INHERITABLE - able to be inherited into other modules (for
example, through BLISS library, PASCAL environment, or Ada
compilation system mechanisms)
o GLOBAL - known to multiple modules via linker global symbol
definitions
o PREDEFINED - defined by the language (examples: BLISS ap,
FORTRAN sin, PASCAL writeln)
o MULTI_MODULE - domain spans more than one module (domain=multi_
module is equivalent to domain=(inheritable,global,predefined)
o MODULE_SPECIFIC - domain is limited to one module
The previous keywords are SCA terms. For information on
corresponding language-specific terms, request help for the
appropriate language table (for example, FORTRAN_ATTRIBUTES_TABLE)
under the Getting_Started help topic.
An example using the DOMAIN attribute follows:
FIND DOMAIN=GLOBAL AND SYMBOL=VARIABLE
This query find all global variables.
22 – EXPAND
The EXPAND function determines the symbol to which an occurrence
belongs and returns the full set of occurrences for the symbol.
For example, the following code fragments, written in a pseudo
language, declare and use the variable i in three files.
file 1 file 2 file 3
------ ------ ------
GLOBAL i (d) LOCAL i (d) EXTERNAL i (d)
i := 0 (wr) i := 5 (wr) IF i EQUALS 0 (rr)
(d) - declaration
(wr) - write reference
(rr) - read reference
The pseudo language defines variables, such that the variable i
in "file 1" and the variable i in "file 3" are the same variable.
The variable i in "file 2", however, is a different variable. SCA
treats these variables in the same manner by saying there are two
unique symbols which happen to have the same name.
The important point in the previous example is that what the
programmer considers unique items SCA also considers unique items.
In SCA terms, these items are symbols.
Given the previous code fragments, consider the follwoing query:
FIND SYMBOL_CLASS=VARIABLE AND OCCURRENCE=READ
This query returns one occurrence, which is the read reference in
"file 3." Now consider the next query:
FIND EXPAND( symbol_class=variable and occurrence=read )
This query returns two occurrences of "i" in "file 1" and the two
occurrences of "i" in "file 3." The EXPAND function uses the read
reference to determine the corresponding symbol and then returns
all the occurrences for that symbol. In this case the symbol was
the global variable "i".
Note that the two occurrences in "file 2" are not returned because
they belong to a different symbol. The programmer does not view
the i in "file 2" to be the same as the i in "file 1" and "file 3"
and SCA reflects that view.
When given more than one occurrence, the EXPAND function performs
this operation iteratively and removes any duplicate occurrences
from the result.
In the following example, you use the EXPAND function to find the
declarations of routines defined in the system, but which are not
used. To do this, specify the following query:
FIND (SYMBOL=ROUTINE AND OCCURRENCE=PRIMARY) AND NOT
EXPAND(SYMBOL=ROUTINE AND OCCURRENCE=REFERENCE)
23 – FILE_SPEC
FILE_SPEC is an attribute selection that specifies the name of the
file. You identify a source file by its OpenVMS file specification.
You should enclose the file specification in quotation marks
because it normally contains a period (.)
The format for the FILE_SPEC attribute is as follows:
FILE_SPEC="filename.filetype"
An example using the FILE_SPEC attribute follows:
FIND FILE_SPEC="MYPROG.FOR"
This query finds all occurrences in the file MYPROG.FOR.
24 – IN
The IN function searches for occurrences inside a container. The
IN function is a special case of the CONTAINED_BY function. In its
most common form, the function format is as follows:
IN( <container>, <containee> )
In this format, <container> and <containee> can be any legal query
expression. The IN function returns all occurrences that match the
<containee> expression as long as those occurrences are somewhere
inside the container.
Some examples will help you understand the IN function. The
following picture applies to the examples that follow.
A (module)
+-------------------------+
| |
| B (routine) |
| +-------------------+ |
| | | |
| | C (routine) | |
| | +-------------+ | |
| | | | | |
| | | D (variable)| | |
| | | | | |
| | | | | |
| | +-------------+ | |
| | | |
| +-------------------+ |
| |
| E (variable) |
| |
+-------------------------+
Consider the following queries:
1. FIND IN( A, *)
2. FIND IN( B, D)
3. FIND IN( A, SYMBOL_CLASS=ROUTINE and OCCURRENCE=DECLARATION)
The first query returns B (a containee), C (a containee), D (a
containee) and E (a containee). A is not returned because it is
the container.
The second query returns only D (the containee). C is not returned
because it does not match the <containee> expression. B is not
returned because it is the container.
The third query returns all routine declarations inside A. In this
case, B and C are returned.
The IN function is a convenient way to limit a query to a
particular container.
The full format of the In function is as follows:
IN( [END=<container>],
[BEGIN=<containee>] )
In this format, <container> and <containee> can be any legal query
expression.
25 – INDICATED
The INDICATED function is available only from within LSE. The
INDICATED function matches the occurrence on which the cursor is
positioned. The INDICATED function has no parameters. The format
is as follows:
INDICATED()
An example of using the INDICATED function is as follows:
FIND EXPAND( INDICATED() )
This query finds all occurrences of the item on which the cursor
is positioned in LSE.
26 – NAME
NAME is an attribute of an occurrence that is a string of ASCII
characters which identifies symbols in your source code. A
specific name can be associated with more than one symbol.
The language you are using defines the legal characters for
a name. Each name has zero or more characters. Any character
may appear in a name. Special characters that appear in a name
must be quoted using double quotes. You do not need to quote the
following: $, _, *, %, &, -, alphanumeric characters.
You can use wildcards (* and %) in the name expression. You can
override the wildcard characters by using the escape character
(&). For example, you can find the name consisting of a single
asterisk using the name expression &*. If you want an ampersand in
a string, you must use two successive ampersands.
The format for NAME can be one of the following:
name
NAME=(name[,name...])
27 – OCCURRENCE
The occurrence class is an attribute of an occurrence that
identifies the type of occurrence. The occurrence class indicates
if the occurrence is a declaration, a reference, or one of the
other classes in the list that follows. If the occurrence class is
a declaration or reference, the occurrence class indicates what
type of declaration or reference it is.
The format for the occurrence class attribute is as follows:
OCCURRENCE=(keyword[,keyword...])
The occurrence class can be one of the following keywords:
Declarations
o PRIMARY - most significant declaration
o ASSOCIATED - associated declaration
o DECLARATION - primary or associated
References
o READ, FETCH - fetch of a symbol value
o WRITE, STORE - assignment of a symbol value
o ADDRESS, POINTER - reference to the location of a symbol
o CALL - call to a routine or macro
o COMMAND_LINE - command line file reference
o INCLUDE - source file include referenece
o PRECOMPILED - precompiled file include referenece
o OTHER - any other kind of reference (such as a macro expansion
or use of a constant)
o REFERENCE - any of the preceding values
o BASE - Any base class of a C++ class
o FRIEND - Any friend of a C++ class
o MEMBER - Any member of a C++ class
o SPEPARATE - Any Ada package or sub-program unit defined
as SEPARATE
o WITH - Any WITH of an Ada package or sub-program unit
Other Occurrence Classes
o EXPLICIT - explicitly declared
o IMPLICIT - implicitly declared
o VISIBLE - occurrence appears in the source
o HIDDEN - occurrence does not appear in the source
o COMPILATION_UNIT - the declaration that contains all
occurrences in a particular compilation unit
o LIMITED - Any Ada limited private type
o PRIVATE - Any private C++ objects, or Ada private type
o PROTECTED - Any protected c++ object
o PUBLIC - Any public C++ object
o VIRTUAL - Any virtual C++ object
The previous keywords are SCA terms. For information on
corresponding language-specific terms, request help for the
appropriate language table (for example, FORTRAN_ATTRIBUTES_TABLE)
under the Getting_Started help topic.
An example using the occurrence class attribute follows:
FIND OCCURRENCE=PRIMARY
This query finds all PRIMARY occurrences of declarations.
28 – SYMBOL_CLASS
SYMBOL_CLASS is an attribute selection that identifies the type of
symbol. A symbol can be a variable, constant, or some other class.
The format for SYMBOL_CLASS is as follows:
SYMBOL_CLASS=(keyword[,keyword...])
The SYMBOL_CLASS can be one of the following keywords:
o ARGUMENT - formal argument (such as a routine argument or macro
argument)
o CLASS - Any C++ class object construct defined by the union,
structure or class statements
o COMPONENT,FIELD - component of a record
o CONSTANT,LITERAL - named compile-time constant value
o EXCEPTION - exception
o FILE - file
o FUNCTION,PROCEDURE, PROGRAM,ROUTINE, SUBROUTINE - callable
program function
o GENERIC - generic unit
o KEYWORD - keyword
o LABEL - user-specified label
o MACRO - macro
o MODULE, PACKAGE - collection of logically related elements
o PLACEHOLDER - marker where program text is needed
o PSECT - program section
o TAG - comment heading
o TASK - task
o TYPE - user-defined type
o UNBOUND - unbound name
o VARIABLE - program variable
o OTHER - any other class of symbol
The previous keywords are SCA terms. For information on
corresponding language-specific terms, request help for the
appropriate language table (for example, FORTRAN_ATTRIBUTES_TABLE)
under the Getting_Started help topic.
An example using the SYMBOL_CLASS attribute follows:
FIND X AND SYMBOL_CLASS=ROUTINE
This query finds all routines named X.
29 – TYPING
The TYPING function is a relationship function. It finds the type
of some occurrence. Occurrences related in this manner have a
TYPING relationship between them. For example, if INTEGER is
typing variable X, then these two occurrences are in a TYPING
relationship. In its most common form, the function format is as
follows:
TYPING( <typee>, <type>, DEPTH={<number> | ALL} )
In this format, <typee> and <type> can be any legal query
expression, and <number> is a positive integer. A typical use
of the function is to find the type of a variable. For example:
FIND TYPING( X, *, DEPTH=1)
This query finds the type of X, where X is some variable in the
SCA database.
The TYPING function also works on user-defined types. The defined
type can have many levels, in which case the user can specify a
depth as follows:
FIND TYPING( user_defined_type, *, DEPTH=ALL)
This query gives the full type tree for USER_DEFINED_TYPE.
The TYPING function provides the power to return the exact type
tree you want. The full format is as follows:
TYPING( [ END=<typee> ],
[ BEGIN=<type> ],
[ DEPTH={<number> | ALL} ],
[ RESULT=RESULT_KEYWORD ],
[ TRACE=query_expression ] )
In the previous format, <typee> and <type> 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 TYPING relationship, see the
on-line help file SCACOMMANDS.
30 – TYPED_BY
The TYPED_BY function is a relationship function. It finds
occurrences that have a TYPED_BY relationship between them.
For example, if variable X is typed by INTEGER, then these two
occurrences are in a TYPED_BY relationship. In its most common
form, the function format is as follows:
TYPED_BY( <type>, <typee>, DEPTH={<number> | ALL} )
In this format, <typee> and <type> can be any legal query
expression, and <number> is a positive integer. A typical use
of the function is to find what is being typed by INTEGER. For
example:
FIND TYPED_BY( INTEGER, *, DEPTH=1)
This query finds everything that is of type INTEGER. The TYPED_BY
function can also tell you the items that are in some way affected
by a given type. The type can be predefined by language elements
such as INTEGER, or can be user defined. For example:
FIND TYPED_BY( user_defined_type, *, DEPTH=ALL)
This query finds all the items that are directly or indirectly
affected by USER_DEFINED_TYPE.
The TYPED_BY function provides the power to return the exact type
tree you want. The full format is as follows:
TYPED_BY( [ END=<type> ],
[ BEGIN=<typee> ],
[ DEPTH={<number> | ALL} ],
[ RESULT=RESULT_KEYWORD ],
[ TRACE=query_expression ] )
In the previous format, <type> and <typee> 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 TYPED_BY relationship, see the
on-line help file SCACOMMANDS.