[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:
$ 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.
3 – Building An SCA Library
To create your own SCA library, you must first create a library
directory for it. Using your personal directory, type the
following command to create a subdirectory for a local SCA
library:
$ CREATE/DIRECTORY [.LIB1]
Once you have a directory in which to create a library, enter the
following command to SCA to create a library:
$ SCA CREATE LIBRARY [.LIB1]
You now have an empty SCA library. To add a module to the SCA
library, you must first compile your source code.
Add the /ANALYSIS_DATA qualifier when you use a supported
compiler. For example:
$ CC/ANALYSIS_DATA myfile.c
This produces the file MYFILE.ANA that you can load into your SCA
library either from LSE or standalone SCA. To load the .ANA file
and show the new module, type the following commands:
SCA> LOAD myfile.ANA
SCA> SHOW MODULE
You will see that the new module has been loaded into the library,
and you will now be able to query that library.
For more information, see the help topics for Libraries and
Reducing_LOAD_Time.
4 – Callable Routines
4.1 – SCA$ASYNCH_TERMINATE
Sets a flag indicating that a CTRL-C has been issued.
Format
SCA$ASYNCH_TERMINATE command_context
4.1.1 – Argument
command_context
type: $SCA_COMMAND_CONTEXT
access: read/write
mechanism: by reference
SCA command context value.
4.1.2 – Condition Value Returned
SCA$_NORMAL Normal successful completion.
4.1.3 – Description
The SCA$ASYNCH_TERMINATE routine sets a flag indicating that a
CTRL-C has been issued.
4.2 – SCA$CLEANUP
Shuts down the SCA callable command interface, freeing all dynamic
memory associated with the interface routines and data structures.
Format
SCA$CLEANUP command_context
4.2.1 – Argument
command_context
type: $SCA_COMMAND_CONTEXT
access: read/write
mechanism: by reference
An SCA command context value.
4.2.2 – Condition Value Returned
SCA$_NORMAL The SCA callable command interface has been
successfully shut down.
4.2.3 – Description
The SCA$CLEANUP routine shuts down the SCA callable command
interface, freeing all dynamic memory associated with the
interface routines and data structures.
4.3 – SCA$DO_COMMAND
Parses an SCA subsystem command and invokes command processing if
the command is syntactically correct.
Format
SCA$DO_COMMAND command_context,
command_string
[,parameter_routine]
[,continuation_routine]
[,continuation_prompt]
[,user_argument]
[,confirm_routine]
[,topic_routine]
[,display_routine]
4.3.1 – Arguments
command_context
type: $SCA_COMMAND_CONTEXT
access: read/write
mechanism: by reference
SCA command context value.
command_string
type: character string
access: read only
mechanism: by descriptor
An SCA subsystem command.
parameter_routine
type: procedure
access: read only
mechanism: by reference
Routine that prompts for required parameters. You can specify
LIB$GET_INPUT or a compatible routine. If a routine address of
zero (0) is specified, commands with missing parameters fail and
display a CLI error message.
continuation_routine
type: procedure
access: read only
mechanism: by reference
Routine that prompts for the remainder of a continued command
(i.e., a command that ends with a hyphen). You can specify
LIB$GET_INPUT or a compatible routine.
continuation_prompt
type: character string
access: read only
mechanism: by descriptor
Command continuation prompt string (e.g., SCA> ).
user_argument
type: longword
access: read only
mechanism: by reference
User-specified value to be passed to any action routine (other
than CLI prompt routines) called by this routine.
confirm_routine
type: procedure
access: read only
mechanism: by value
Command confirmation prompt routine to be used by commands that
support a /CONFIRM qualifier. You can specify SCA$GET_INPUT or
a compatible routine. If this argument is omitted, the /CONFIRM
qualifier is not supported.
topic_routine
type: procedure
access: read only
mechanism: by value
Help topic prompt routine. You can specify LIB$GET_INPUT or a
compatible routine. If this routine returns an error, command
processing is terminated. If this argument is omitted, no help
prompting is performed.
display_routine
type: procedure
access: read only
mechanism: by value
Routine to be called to display one line of command output. You
can specify SCA$PUT_OUTPUT or a compatible routine. If this
routine returns an error, command processing is terminated. If
this argument is omitted, no display routine is called.
4.3.2 – Condition Values Returned
All SCA condition
values and many
system values.
4.3.3 – Description
The SCA$DO_COMMAND routine parses an SCA subsystem command
and invokes command processing if the command is syntactically
correct.
4.4 – SCA$GET_ATTRIBUTE
Gets a handle to an attribute of an entity.
Format
SCA$GET_ATTRIBUTE entity,
attribute_kind,
attribute_handle,
[,iteration_context]
4.4.1 – Arguments
entity
type: $SCA_HANDLE
access: read only
mechanism: by reference
An SCA entity handle describing the entity or relationship whose
attributes are being obtained.
attribute_kind
type: $SCA_ATTRIBUTE_KIND
access: read only
mechanism: by reference
The kind of attribute to be obtained.
Any attribute-kind can be specified on this routine.
attribute_handle
type: $SCA_HANDLE
access: write only
mechanism: by reference
An SCA attribute handle that is to describe the obtained
attribute.
iteration_context
type: $SCA_ITERATION_CONTEXT
access: read/write
mechanism: by reference
Optional. The iteration-context. This longword must contain zero
on the first call to this routine for a particular iteration. This
routine uses the longword to maintain the iteration context. The
caller must not change the contents of the longword.
4.4.2 – Condition Values Returned
SCA$_NORMAL An attribute has been successfully returned.
SCA$_NONE Warning. An attribute has not been returned.
Either there are no such attributes at
all in the entity or there are no more
attributes.
4.4.3 – Description
The SCA$GET_ATTRIBUTE routine gets a handle to an attribute of an
entity.
If the iteration_context parameter is not specified, then
this routine finds the first attribute of the specified kind
(attribute_kind) and updates attribute_handle to describe that
attribute.
In general, several attributes can be associated with a particular
entity. With this routine you can find all of those attributes by
using the iteration_context parameter.
4.5 – SCA$GET_ATTRI_KIND_T
Gets an attribute kind.
Format
SCA$GET_ATTRI_KIND_T attribute_handle,
attribute_kind
4.5.1 – Arguments
attribute_handle
type: $SCA_HANDLE
access: read only
mechanism: by reference
An SCA handle describing an attribute whose attribute-kind is to
be obtained.
attribute_kind
type: character string
access: write only
mechanism: by descriptor
The kind of the attribute.
4.5.2 – Condition Value Returned
SCA$_NORMAL An attribute kind has been successfully
returned.
4.5.3 – Description
The SCA$GET_ATTRI_KIND_T routine returns the kind of any attribute
as a character string.
4.6 – SCA$GET_ATTRI_VALUE_T
Gets an attribute value.
Format
SCA$GET_ATTRI_VALUE_T handle, attribute_value
[,attribute_kind]
4.6.1 – Arguments
handle
type: $SCA_HANDLE
access: read/write
mechanism: by reference
An SCA attribute handle describing either an attribute or an
entity whose value is to be obtained.
attribute_value
type: character string
access: read/write
mechanism: by descriptor
The (string) value of the attribute being selected.
attribute_kind
type: $SCA_ATTRIBUTE_KIND
access: read/write
mechanism: by reference
Optional. The kind of attribute to be obtained.
4.6.2 – Condition Values Returned
SCA$_NORMAL An attribute value has been successfully
returned.
SCA$_NONE Warning. An attibute-value has not been
returned. There are no such attributes in
the entity. This condition can be returned
only if this routine is processing an
entity.
4.6.3 – Description
The SCA$GET_ATTRI_VALUE_T routine returns the value of any
attribute as a character string.
If the handle describes an attribute, then this routine returns
the value of that attribute. In this case, the attribute_kind
parameter must not be specified.
If the handle describes an entity, then this routine returns the
value of the first attribute of that entity that is of the kind
specified by the attribute_kind parameter. In this case, the
attribute_kind parameter must be specified.
If you want to get more than one attribute value of a particular
kind for an entity, you must use the routine SCA$GET_ATTRIBUTE.
This applies only to the attribute kinds SCA$K_ATTRI_NAME and
SCA$K_ATTRI_ALL.
The value of any kind of attribute can be returned by this
routine, except for SCA$K_ATTRI_ALL. This routine will convert to
character string those attributes whose data type is not character
string.
This routine does not accept the attribute-kind SCA$K_ATTRI_ALL as
the value of the attribute_kind parameter. It is not meaningful to
get just the first attribute without regard to attribute-kind.
4.7 – SCA$GET_CURRENT_QUERY
Gets the name of the current query in the given command context.
Format
SCA$GET_CURRENT_QUERY command_context,
query_name
4.7.1 – Arguments
command_context
type: $SCA_COMMAND_CONTEXT
access: read/write
mechanism: by reference
An SCA command context.
query_name
type: character string
access: write only
mechanism: by descriptor
The name of the current query in the context of the given command
context.
4.7.2 – Condition Values Returned
SCA$_NORMAL The name of the current query has been
successfully retrieved.
4.7.3 – Description
The SCA$GET_CURRENT_QUERY routine gets the name of the current
query in the given command context.
4.8 – SCA$GET_INPUT
Gets one record of ASCII text from the current controlling input
device specified by SYS$INPUT.
Format
SCA$GET_INPUT get_string,
[,prompt_string]
[,output_length]
[,user_argument]
4.8.1 – Arguments
get_string
type: character string
access: write only
mechanism: by descriptor
Buffer to receive the line read from SYS$INPUT. The string is
returned by a call to STR$COPY_DX.
prompt_string
type: character string
access: read only
mechanism: by descriptor
Prompt message that is displayed on the controlling terminal. A
valid prompt consists of text followed by a colon (:), a space,
and no carriage-return/line-feed combination. The maximum size
of the prompt message is 255 characters. If the controlling input
device is not a terminal, this argument is ignored.
output_length
type: word
access: write only
mechanism: by reference
Word to receive the actual length of the GET-STRING line, not
counting any padding in the case of a fixed string. If the input
line was truncated, this length reflects the truncated string.
user_argument
type: _UNSPECIFIED
access: read only
mechanism: by reference
User-specified value that was passed to the routine that called
this action routine.
4.8.2 – Condition Values Returned
SCA$_NORMAL An input line was returned.
Failure completion
code from LIB$GET_
INPUT.
4.8.3 – Description
The SCA$GET_INPUT routine gets one record of ASCII text from the
current controlling input device specified by SYS$INPUT.
4.9 – SCA$GET_OCCURRENCE
Returns an occurrence from the query specified by the query_name
argument.
Format
SCA$GET_OCCURRENCE command_context,
query_name,
occurrence
4.9.1 – Arguments
command_context
type: $SCA_COMMAND_CONTEXT
access: read/write
mechanism: by reference
An SCA command context.
query_name
type: character string
access: read only
mechanism: by descriptor
The name of the query in the context of the command context.
occurrence
type: $SCA_HANDLE
access: read/write
mechanism: by reference
An SCA occurrence handle that describes an occurrence.
4.9.2 – Condition Values Returned
SCA$_NORMAL An occurrence has been successfully
returned.
SCA$_NEWNAME An occurrence has been successfully
returned. This occurrence has a different
name from the occurrence that was returned
by the previous call to this routine with
this query context. This condition implies
that this new occurrence is also of a
different symbol.
SCA$_NEWITEM An occurrence has been successfully
returned. This new occurrence is of a
different symbol from the occurrence that
was returned by the previous call to this
routine with this query context.
SCA$_NOMORE Warning. An occurrence has not been
returned. The traversal of the query result
has been exhausted.
4.9.3 – Description
The SCA$GET_OCCURRENCE routine returns an occurrence from the
query specified by the query_name argument.
If the occurrence handle supplied is zero, the routine returns
a handle to the first occurrence in the query represented by the
argument query_name. If the occurrence handle supplied on input
represents a valid occurrence, the routine returns a handle to
the next occurrence in the query result. In order to be valid, the
occurrence handle supplied on input must refer to an occurrence in
the query represented by the argument query_name.
The query name supplied is interpreted in the context of the
command context identified by the argument command_context.
Note that the order of retrieval of the occurrences is undefined.
4.10 – SCA$INITIALIZE
Initializes the SCA callable command interface.
Format
SCA$INITIALIZE command_context
4.10.1 – Argument
command_context
type: $SCA_COMMAND_CONTEXT
access: write only
mechanism: by reference
SCA command context value to be initialized. This value is passed
as an argument to other SCA$xxx routines.
4.10.2 – Condition Value Returned
SCA$_NORMAL The SCA callable command interface has been
successfully initialized.
4.10.3 – Description
The SCA$INITIALIZE routine initializes the SCA callable command
interface.
4.11 – SCA$LOCK_LIBRARY
Locks all the physical libraries in the current virtual library
list so that they cannot be modified.
Format
SCA$LOCK_LIBRARY command_context
4.11.1 – Argument
command_context
type: $SCA_COMMAND_CONTEXT
access: read/write
mechanism: by reference
An SCA command context.
4.11.2 – Condition Value Returned
SCA$_NORMAL The libraries have been successfully locked.
4.11.3 – Description
The SCA$LOCK_LIBRARY routine locks all the physical libraries in
the current virtual library list so that they cannot be modified.
4.12 – SCA$PUT_OUTPUT
Writes a record to the current controlling output device specified
by SYS$OUTPUT.
Format
SCA$PUT_OUTPUT string,
user_argument
4.12.1 – Arguments
string
type: character string
access: read only
mechanism: by descriptor
String to be written to SYS$OUTPUT. You can concatenate one or
more additional character strings with the primary string to form
a single output record. You can specify a maximum of 20 strings.
The maximum resulting record length is 255 characters.
user_argument
type: _UNSPECIFIED
access: read only
mechanism: by reference
User-specified value that was passed to the routine that called
this action routine.
4.12.2 – Condition Values Returned
SCA$_NORMAL The string was successfully written to
SYS$OUTPUT.
Failure completion
from the RMS
$PUT service.
4.12.3 – Description
The SCA$PUT_OUTPUT routine writes a record to the current
controlling output device specified by SYS$OUTPUT.
4.13 – SCA$QUERY_CLEANUP
Cleans up an SCA query context, freeing all dynamic memory
associated with the query.
Format
SCA$QUERY_CLEANUP query_context
4.13.1 – Argument
query_context
type: $SCA_QUERY_CONTEXT
access: read/write
mechanism: by reference
An SCA query context to be cleaned up.
4.13.2 – Condition Value Returned
SCA$_NORMAL The query context has been successfully
cleaned up.
4.13.3 – Description
The SCA$QUERY_CLEANUP routine cleans up an SCA query context,
freeing all dynamic memory associated with the query.
This routine will become obsolete in a future version of SCA.
4.14 – SCA$QUERY_COPY
Copies a query from SRC_QUERY_CONTEXT to DST_QUERY_CONTEXT.
Format
SCA$QUERY_COPY src_query_context,
dst_query_context
4.14.1 – Arguments
src_query_context
type: $SCA_QUERY_CONTEXT
access: read/write
mechanism: by reference
An SCA query context that describes the query to be copied.
dst_query_context
type: $SCA_QUERY_CONTEXT
access: read/write
mechanism: by reference
An SCA query context into which the query is to be copied.
4.14.2 – Condition Value Returned
SCA$_NORMAL The query expression has been successfully
copied.
4.14.3 – Description
The SCA$QUERY_COPY routine copies a query from SRC_QUERY_CONTEXT
to DST_QUERY_CONTEXT. This will copy whatever is in SRC_QUERY_
CONTEXT, whether that is a question, or a question and a result.
This routine will become obsolete in a future version of SCA.
4.15 – SCA$QUERY_FIND
Finds the occurrences that match the query expression specified by
QUERY_CONTEXT.
Format
SCA$QUERY_FIND query_context
4.15.1 – Argument
query_context
type: $SCA_QUERY_CONTEXT
access: read/write
mechanism: by reference
An SCA query context that describes a query expression to be
evaluated.
4.15.2 – Condition Values Returned
SCA$_NORMAL The query expression has been successfully
evaluated.
SCA$_NOOCCUR No occurrences match the query expression.
SCA$_RESULTEXISTS The query already has a result prior to this
call.
4.15.3 – Description
The SCA$QUERY_FIND routine finds the occurrences that match the
query expression specified by QUERY_CONTEXT.
This routine will become obsolete in a future version of SCA.
4.16 – SCA$QUERY_GET_ATTRIBUTE
Gets a handle to an attribute of an entity.
Format
SCA$QUERY_GET_ATTRIBUTE entity,
attribute_kind,
attribute_handle,
[,iteration_context]
4.16.1 – Arguments
entity
type: $SCA_HANDLE
access: read only
mechanism: by reference
An SCA entity handle describing the entity or relationship whose
attributes are being obtained.
attribute_kind
type: $SCA_ATTRIBUTE_KIND
access: read only
mechanism: by reference
The kind of attribute to be obtained.
Any attribute-kind can be specified on this routine.
attribute_handle
type: $SCA_HANDLE
access: write only
mechanism: by reference
An SCA attribute handle that is to describe the obtained
attribute.
iteration_context
type: $SCA_ITERATION_CONTEXT
access: read/write
mechanism: by reference
Optional. The iteration-context. This longword must contain zero
on the first call to this routine for a particular iteration. This
routine uses the longword to maintain the iteration context. The
caller must not change the contents of the longword.
4.16.2 – Condition Values Returned
SCA$_NORMAL An attribute has been successfully returned.
SCA$_NONE Warning. An attribute has not been returned.
Either there are no such attributes at
all in the entity or there are no more
attributes.
4.16.3 – Description
The SCA$QUERY_GET_ATTRIBUTE routine gets a handle to an attribute
of an entity.
If the iteration_context parameter is not specified, then
this routine finds the first attribute of the specified kind
(attribute_kind) and updates attribute_handle to describe that
attribute.
In general, several attributes can be associated with a particular
entity. With this routine you can find all of those attributes by
using the iteration_context parameter.
This routine will become obsolete in a future version of SCA. The
SCA$GET_ATTRIBUTE routine supersedes this routine.
4.17 – SCA$QUERY_GET_ATTRI_KIND_T
Gets an attribute kind.
Format
SCA$QUERY_GET_ATTRI_KIND_T attribute_handle,
attribute_kind
4.17.1 – Arguments
attribute_handle
type: $SCA_HANDLE
access: read only
mechanism: by reference
An SCA handle describing an attribute whose attribute-kind is to
be obtained.
attribute_kind
type: character string
access: write only
mechanism: by descriptor
The kind of the attribute.
4.17.2 – Condition Value Returned
SCA$_NORMAL An attribute kind has been successfully
returned.
4.17.3 – Description
The SCA$QUERY_GET_ATTRI_KIND_T routine returns the kind of any
attribute as a character string.
This routine will become obsolete in a future version of SCA. The
SCA$GET_ATTRI_KIND_T routine supersedes this routine.
4.18 – SCA$QUERY_GET_ATTRI_VALUE_T
Gets an attribute value.
Format
SCA$QUERY_GET_ATTRI_VALUE_T handle, attribute_value
[,attribute_kind]
4.18.1 – Arguments
handle
type: $SCA_HANDLE
access: read/write
mechanism: by reference
An SCA attribute handle describing either an attribute or an
entity whose value is to be obtained.
attribute_value
type: character string
access: read/write
mechanism: by descriptor
The (string) value of the attribute being selected.
attribute_kind
type: $SCA_ATTRIBUTE_KIND
access: read/write
mechanism: by reference
Optional. The kind of attribute to be obtained.
4.18.2 – Condition Values Returned
SCA$_NORMAL An attribute value has been successfully
returned.
SCA$_NONE Warning. An attibute-value has not been
returned. There are no such attributes in
the entity. This condition can be returned
only if this routine is processing an
entity.
4.18.3 – Description
The SCA$QUERY_GET_ATTRI_VALUE_T routine returns the value of any
attribute as a character string.
If the handle describes an attribute, then this routine returns
the value of that attribute. In this case, the attribute_kind
parameter must not be specified.
If the handle describes an entity, then this routine returns the
value of the first attribute of that entity that is of the kind
specified by the attribute_kind parameter. In this case, the
attribute_kind parameter must be specified.
If you want to get more than one attribute value of a particular
kind for an entity, you must use the routine SCA$QUERY_GET_
ATTRIBUTE. This applies only to the attribute kinds SCA$K_ATTRI_
NAME and SCA$K_ATTRI_ALL.
The value of any kind of attribute can be returned by this
routine, except for SCA$K_ATTRI_ALL. This routine will convert to
character string those attributes whose data type is not character
string.
This routine does not accept the attribute-kind SCA$K_ATTRI_ALL as
the value of the attribute_kind parameter. It is not meaningful to
get just the first attribute without regard to attribute-kind.
This routine will become obsolete in a future version of SCA. The
SCA$GET_ATTRI_VALUE_T routine supersedes this routine.
4.19 – SCA$QUERY_GET_NAME
Returns the name of a query.
Format
SCA$QUERY_GET_NAME query_context,
query_name
4.19.1 – Arguments
query_context
type: $SCA_QUERY_CONTEXT
access: read/write
mechanism: by reference
An SCA query context whose name is to be obtained.
query_name
type: character string
access: write only
mechanism: by descriptor
The name of the query.
4.19.2 – Condition Value Returned
SCA$_NORMAL The query name has been successfully
returned.
4.19.3 – Description
The SCA$QUERY_GET_NAME routine returns the name of a query.
This routine will become obsolete in a future version of SCA.
4.20 – SCA$QUERY_GET_OCCURRENCE
Gets the next occurrence in the query result that is specified as
a query_context argument.
Format
SCA$QUERY_GET_OCCURRENCE query_context,
entity_handle
4.20.1 – Arguments
query_context
type: $SCA_QUERY_CONTEXT
access: read/write
mechanism: by reference
An SCA query context whose occurrences are to be obtained.
entity_handle
type: $SCA_HANDLE
access: read/write
mechanism: by reference
An SCA entity handle that describes an entity.
4.20.2 – Condition Values Returned
SCA$_NORMAL An occurrence has been successfully
returned.
SCA$_NEWSYMBOL An occurrence has been successfully
returned. This new occurrence is of a
different symbol than the occurrence that
was returned by the previous call to this
routine.
SCA$_NOMORE Warning. An occurrence has not been
returned. The traversal of the query result
has been exhausted.
4.20.3 – Description
The SCA$QUERY_GET_OCCURRENCE routine successively returns every
occurrence in a query result. It provides one pass through all of
the occurrences.
This routine will become obsolete in a future version of SCA. The
SCA$GET_OCCURRENCE routine supersedes this routine.
4.21 – SCA$QUERY_INITIALIZE
Initializes an SCA query context.
Format
SCA$QUERY_INITIALIZE command_context,
query_context
4.21.1 – Arguments
command_context
type: $SCA_COMMAND_CONTEXT
access: read/write
mechanism: by reference
An SCA command context.
query_context
type: $SCA_QUERY_CONTEXT
access: write only
mechanism: by reference
An SCA query context to be initialized. This value is passed as an
argument to other SCA query routines (SCA$QUERY_xxx).
4.21.2 – Condition Value Returned
SCA$_NORMAL The query context has been successfully
initialized.
4.21.3 – Description
The SCA$QUERY_INITIALIZE routine initializes an SCA query context.
This routine must be called before any other SCA$QUERY_ routines.
This routine will become obsolete in a future version of SCA.
4.22 – SCA$QUERY_PARSE
Parses a query expression command string and sets up a query
context if the command is syntactically correct.
Format
SCA$QUERY_PARSE query_context, query_expression_string
[,query_expression_length]
4.22.1 – Arguments
query_context
type: $SCA_QUERY_CONTEXT
access: read/write
mechanism: by reference
An SCA query context that is to describe the indicated query
expression.
query_expression_string
type: character string
access: read only
mechanism: by descriptor
A query expression string.
query_expression_length
type: longword
access: write only
mechanism: by reference
Optional. Length of the query expression, returned from the
parser.
4.22.2 – Condition Values Returned
SCA$_NORMAL The query expression string has been
successfully parsed.
SCA$_MORETEXT Warning. The query expression string has
been successfully parsed, but the text
following the query expression is not a
legal part of the query expression. This
condition is returned only if the query_
expression_length parameter is specified. If
the query_expression_length parmeter is not
specified, then this routine insists that
the whole query_expression_string argument
be a legal query expression; in this case
all errors are signaled.
4.22.3 – Description
The SCA$QUERY_PARSE routine parses a query expression string and
sets up a query context if the command is syntactically correct.
This routine will become obsolete in a future version of SCA.
4.23 – SCA$QUERY_SELECT_OCCURRENCE
Creates a query expression that matches a specific entity.
Format
SCA$QUERY_SELECT_OCCURRENCE query_context,
entity_handle
4.23.1 – Arguments
query_context
type: $SCA_QUERY_CONTEXT
access: read/write
mechanism: by reference
An SCA query context that is to describe a specific entity.
entity_handle
type: $SCA_HANDLE
access: read/write
mechanism: by reference
An SCA entity handle that describes the entity that the newly
defined query context is to match.
4.23.2 – Condition Value Returned
SCA$_NORMAL A query expression has been successfully
defined.
4.23.3 – Description
The SCA$QUERY_SELECT_OCCURRENCE routine creates a query expression
that matches a specific entity.
You use this routine to specify queries based on the results
of previous queries. The entity_handle parameter is obtained by
traversing the results of a previous query evaluation.
Typically, the query context of the entity_handle parameter is
not the same as the query_context parameter. However, they can be
the same. If they are the same query context, then that previous
query is replaced with the query defined by this routine and, as a
result, entity_handle becomes invalid.
This routine will become obsolete in a future version of SCA. The
SCA$SELECT_OCCURRENCE routine supersedes this routine.
4.24 – SCA$SELECT_OCCURRENCE
Creates a query that matches a specific occurrence.
Format
SCA$SELECT_OCCURRENCE occurrence,
query_name
4.24.1 – Arguments
occurrence
type: $SCA_HANDLE
access: read only
mechanism: by reference
An SCA occurrence handle which describes the occurrence that the
newly created query is to match.
query_name
type: character string
access: write only
mechanism: by descriptor
The name of the newly created query. This query is created in the
context of the same command context as that in which the input
occurrence handle is defined.
4.24.2 – Condition Values Returned
SCA$_NORMAL A query expression has been successfully
defined.
4.24.3 – Description
You use this routine to create new queries based on the results of
previous queries. The occurrence handle parameter is obtained by
traversing the results of a previous query evaluation.
4.25 – SCA$UNLOCK_LIBRARY
Unlocks all the physical libraries in the current virtual library
list so that they can be modified.
Format
SCA$UNLOCK_LIBRARY command_context
4.25.1 – Argument
command_context
type: $SCA_COMMAND_CONTEXT
access: read/write
mechanism: by reference
An SCA command context.
4.25.2 – Condition Value Returned
SCA$_NORMAL The libraries have been successfully
unlocked.
4.25.3 – Description
The SCA$UNLOCK_LIBRARY routine unlocks all the physical libraries
in the current virtual library list so that they can be modified.
5 – Callable SCA
The SCA Callable Interface allows you to use SCA within
independent application programs. This allows you to integrate SCA
into alternative user-interfaces and lets you generate specialized
reports based on SCA information.
The SCA Callable Interface contains two components. The first is a
set of routines termed Callable Command Routines, which comprise
a high-level interface which must always be used, regardless of
the type of application. This provides a very simple callable
interface to SCA, which will be sufficient for most applications.
Callable Command Interface Routines
o SCA$ASYNCH_TERMINATE
o SCA$CLEANUP
o SCA$DO_COMMAND
o SCA$GET_INPUT
o SCA$INITIALIZE
o SCA$LOCK_LIBRARY
o SCA$PUT_OUTPUT
o SCA$UNLOCK_LIBRARY
The second component is a set of routines termed Callable
Query Routines. The Callable Query Routines comprise a lower-
level interface to the FIND command. Using this interface, an
application has control over the specification of queries and the
manipulation of query results.
Callable Query Initialization/Cleanup Routines
o SCA$QUERY_CLEANUP
o SCA$QUERY_INITIALIZE
Callable Query Question Building Routines
o SCA$QUERY_PARSE
o SCA$QUERY_SELECT_OCCURRENCE
o SCA$SELECT_OCCURRENCE
Callable Query Result Manipulation Routines
o SCA$GET_ATTRIBUTE
o SCA$GET_ATTRI_KIND_T
o SCA$GET_ATTRI_VALUE_T
o SCA$GET_OCCURRENCE
o SCA$QUERY_GET_ATTRIBUTE
o SCA$QUERY_GET_ATTRI_KIND_T
o SCA$QUERY_GET_ATTRI_VALUE_T
o SCA$QUERY_GET_OCCURRENCE
Callable Query Miscellaneous Routines
o SCA$GET_CURRENT_QUERY
o SCA$QUERY_COPY
o SCA$QUERY_FIND
o SCA$QUERY_GET_NAME
Message Handling
The SCA callable interface handles all messages the same way:
it signals them. If you want control over the display of such
messages, you must establish a condition handler. Establishing a
condition handler is optional.
Rules for Calling SCA Routines
o Most SCA routines are not AST-reentrant; therefore, you should
not call an SCA routine (except SCA$ASYNCH_TERMINATE) from an
AST routine that may currently be interrupting an SCA routine.
o Your program must not disable ASTs.
o If your program uses event flags, you must use the OpenVMS RTL
routines (LIB$RESERVE_EF, LIB$GET_EF, and LIB$FREE_EF) in order
to coordinate the use of event flags between your program and
SCA.
o Except for SCA$ASYNCH_TERMINATE, do not call SCA from within an
SCA callback routine or from within a routine that is handling
a condition signaled by SCA.
o Your program must not unwind when handling a condition signaled
by SCA.
6 – CALLED_BY
The CALLED_BY function is a relationship function. It finds
occurrences that have a CALLED_BY relationship between them.
For example, if routine B is called by routine A, then these two
occurrences are in a CALLED_BY relationship. In its most common
form, the function format is as follows:
CALLED_BY( <caller>, <callee>, DEPTH={<number> | ALL} )
In this format, <caller> and <callee> can be any legal query
expression, and <number> is a positive integer. A typical use
of the function is to find those routines which are called by some
specified routine. For example:
FIND CALLED_BY( xyz, *, DEPTH=ALL )
This query finds the full call tree below XYZ, where XYZ is some
routine in the SCA database. In other words, this query finds all
routines which are either directly or indirectly called by XYZ.
The CALLED_BY function provides the power to return the exact call
tree you want. The full format is as follows:
CALLED_BY( [ END=<caller> ],
[ BEGIN=<callee> ],
[ DEPTH={<number> | ALL} ],
[ RESULT=RESULT_KEYWORD ],
[ TRACE=query_expression ] )
In the previous format, <callee> and < caller> is any legal query
expresion, <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 CALLED_BY relationship, see the
on-line help file SCACOMMANDS.
7 – CALLING
The CALLING function is a relationship function. It finds
occurrences with the CALLING relationship between them. For
example, if routine A is calling routine B, then these two
occurrences are in a CALLING relationship. In its most common
form, the function format is as follows:
CALLING( <callee>, <caller>, DEPTH={<number> | ALL} )
In this format, <callee> and <caller> can be any legal query
expression and <number> is a positive integer. A typical use of
the function is to find those routines which are calling some
specified routine call. For example,
FIND CALLING( abc, *, DEPTH=ALL )
This query finds the full call tree above ABC, where ABC is some
routine in the SCA database. In other words, find all the routines
that are directly or indirectly calling ABC.
The CALLING function provides the power to return the exact call
tree of interest. The full format is:
CALLING ( [ END=<callee> ],
[ BEGIN=<caller> ],
[ DEPTH={<number> | ALL} ],
[ RESULT=RESULT_KEYWORD ],
[ TRACE=query_expression ] )
In the previous format, <callee> and <caller> is any legal query
expresion, <number> is a positive integer, RESULT_KEYWORD can be
STRUCTURE, ANY_PATH, BEGIN, or END, and QUERY_EXPRESSION is any
legal query expression.
For a full description of the CALLING relationship, see the
on-line help file SCACOMMANDS.
8 – Command Categories
This section lists the commands implemented by SCA. These
commands can be issued from within LSE, at DCL level, or at the
SCA subsystem level. See individual commands for definitions,
descriptions, and examples of all SCA commands.
Query Commands
o DELETE QUERY
o FIND
o INSPECT
o SHOW QUERY
Navigation Commands
o GOTO (DECLARATION, QUERY, SOURCE)
o NEXT (OCCURRENCE, QUERY, STEP, SYMBOL)
o PREVIOUS (OCCURRENCE, QUERY, STEP, SYMBOL)
General Commands
o EXIT
o HELP
o SHOW VERSION
Library Commands
o ANALYZE
o CREATE LIBRARY
o DELETE LIBRARY
o DELETE MODULE
o EXTRACT MODULE
o LOAD
o REORGANIZE
o SET LIBRARY
o SET NOLIBRARY
o SHOW LIBRARY
o SHOW MODULE
o VERIFY
o VERIFY/RECOVER
9 – CONTAINED_BY
The CONTAINED_BY function is a relationship function. It finds
occurrences that have a CONTAINED_BY relationship between them. In
its most common form, the function format is as follows:
CONTAINED_BY( <container>, <containee>, DEPTH={<number> | ALL} )
In this format, <container> and <containee> can be any legal query
expression, and <number> is a positive integer.
Some examples will help you understand this 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 CONTAINED_BY( A, *, DEPTH=1 )
2. FIND CONTAINED_BY( C, *, DEPTH=1 )
3. FIND CONTAINED_BY( A, *, DEPTH=2 )
The first query returns A (the container), B (a containee), and
E (a containee). Similarly, the second query returns C and D.
The third query returns A, B, and C and E. The D variable is NOT
included because it is not reachable at a depth of two.
Now consider the following two queries:
4. FIND CONTAINED_BY( A, D, DEPTH=ALL )
5. FIND CONTAINED_BY( A, D, DEPTH=2 )
Query four returns A (the container), B (because it is on the path
to D), C (becasue it is on the path) and D (which is the containee
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.
10 – 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.
11 – 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.
12 – 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)
13 – 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.
14 – Getting Started
SCA works with many languages. See the subtopics in this section
for information about getting started with a specific language.
14.1 – Using Ada
This section contains some basic examples that show what SCA can
do to help you with your programs. The examples have very little
explanation. For a more detailed explanation of the underlying
concepts, see the Basic_Query_Concepts help topic. The remainder
of this section is written in terms that are specific to Ada
programs.
If you want to follow along and try the examples, you will need to
have an SCA library available. If you do not know how to create
an SCA library, read the Building_An_SCA_Library help topic. The
examples use generic variable names (such as 'i'). You will have
to substitute variable names that exist in your code when trying
the examples.
The first example is the easiest query: It lets you find all the
items in your SCA library named 'i', and shows you all the places
where they appear (all occurrences of 'i').
FIND i
You can search for any name in this manner, including using
wildcard characters (for example, FIND i*).
Suppose you are looking for an occurrence, and you know that
it occurs in a particular file. The following query finds all
occurrences of items that are named 'i' but will then limit them
to those which happen to occur in the file named PROG.ADA.
FIND i AND FILE_SPEC="PROG.ADA"
Another typical question one might ask is, "Find all the places
where this item is assigned to (or read from, called, declared,
and so forth)." The next example finds all occurrences of items
that are named 'i', but then limits them to only those occurrences
where 'i' is assigned a value:
FIND i AND OCCURRENCE=WRITE
(SCA understands many occurrence classes other then WRITE. See the
help subtopics under Getting_Started for tables containing all the
SCA attributes and their corresponding meanings in Ada.)
Often, you only want to know where (in what file or package) a
particular function is, so that you can go to it and edit it.
You can use the first query (where 'i' will be the name of the
function) and then look through the output. The output will
include all occurrences of the function, one of which would be
its declaration, which you can then select. Or, you can ask SCA to
limit the search for you by typing the following query:
FIND i AND OCCURRENCE=PRIMARY
In SCA terms, a primary declaration is the most significant
declaration of an item. For an Ada function, this means the body
of the function, or package, or generic, and so forth. This is in
contrast to the specification, which is considered an associated
declaration.
Another problem you might have is that there are many different
items in your system having a given name. Some may be variables;
others may be functions, constants, tasks, and so forth. Suppose
you want to find only the functions named i. Again, the query
FIND i will give you what you want, but it will also give you much
more. It is preferable to issue the following query:
FIND i AND SYMBOL_CLASS=FUNCTION
The previous four examples have selected information based on two
attributes. The last example selected information based on a name
attribute (in this case, i) and a symbol class attribute (in this
case, FUNCTION). Note how the attributes are combined using the
boolean operator AND. In general, you can select items out of your
library based on any combination of attributes, using AND as well
as the other logical operators OR, XOR, and NOT.
The next example shows another primary feature of SCA - the
ability to display relationships between items. This example shows
the most common use of this feature. It finds the complete call
tree (that is, all functions called directly and indirectly) of
the function named i.
FIND CALLED_BY (i, DEPTH=ALL)
If you want to limit the depth of the call tree, replace the
keyword ALL by any positive integer.
The final part of this section describes how to go directly to the
source code once you have issued a query. After issuing the query
FIND i, for example, you can have an LSE query buffer containing
something that looks like the following:
I variable
ADA_MODULE\60 object declaration
ADA_MODULE\75 write reference
ADA_MODULE\79 read reference
ADA_MODULE\122 read reference
ADA_MODULE\144 write reference
ADA_MODULE\146 read, write reference
ADA_MODULE\149 write reference
ADA_MODULE\149 read reference
ADA_MODULE\150 reference
ADA_MODULE\166 read reference
The first two lines of this display will be highlighted. The first
line represents the item you looked for (i), and the rest of the
lines represent the different places in the code where this item
occurred (that is, the occurrences of i). By using the up and down
arrows on your keyboard, or by clicking on an occurrence with your
mouse, you can choose the occurrence you want to see. Then, all
you have to do is type CTRL/G (the keyboard equivalent of the GOTO
SOURCE command) and LSE will bring the source file into a buffer
and position you at the occurrence you chose.
To obtain help on the following topics, request help as indicated.
o For help on query language, see the Basic_Query_Concepts help
topic.
o For help on libraries, see the Building_An_SCA_Library help
topic.
14.2 – Ada Attributes Table
The following table lists the SCA symbol classes and their
corresponding meanings in Ada.
SCA Symbol Classes and Equivalent Ada Language Terminology
SCA Term Ada Term Explanation
Argument Formal A subprogram formal parameter
parameter
Component, Component Record components and discriminants
Field
Constant, Constant
Literal
Exception Exception
File File A file used during compilation
Function, All
Procedure, subprograms,
Program, entries,
Routine, and ACCEPT
Subroutine statements
Generic Generic Generic subprograms or generic
packages
Keyword Keyword PDF keyword tag
Label Labels
and loop
identifiers
Macro N/A
Module, Packages
Package
Placeholder Placeholder LSE placeholder
Psect N/A
Tag Tag PDF tag
Task Task Task objects
Type Type
Unbound Unbound Pragmas and attributes
Variable Object
The following table lists the SCA occurrence classes and their
corresponding meanings in Ada.
SCA Occurrence Classes and Equivalent Ada Language Terminology
SCA Term Ada Term Explanation
Primary Body For example, package body
Associated Specification For example, package specification
Declaration Declaration Any declaration, either primary or
associated
Reference Reference Any nondeclaration
Read, Fetch Read
Write, Store Write
Address, N/A
Pointer
Call Call
Command_line Command line A file referred to on the command
line; for example, ADA foo.ada
Include N/A
Precompiled N/A
Separate Separate Any Ada package or sub-program unit
defined as SEPARATE
With With Any WITH of an Ada package or sub-program
unit
Explicit Explicit An entity that is explicitly
declared. For example,
declarations resulting from generic
instantiations.
Implicit Implicit Any symbol declared by the compiler,
for example a loop name
Visible Visible A symbol whose name is visible in
the source
Hidden Hidden A symbol whose name is not visible
in the source; for example,
anonymous types
Compilation_ Compilation Subprogram declaration or body,
unit unit package declaration or body, and so
forth
Limited Limited Any Ada limited private type
Private Private Any Ada private type
The following table lists the SCA domain classes and their
corresponding meanings in ADA.
SCA Domain Classes and Equivalent Ada Language Terminology
SCA Term Ada Term Explanation
Inheritable Objects declared in a package
specification
Global N/A
Predefined N/A
Multi_module Inheritable, Global and Predefined
Module_ Module Objects known to only one module
specific specific
14.3 – Using BASIC
This section contains some typical examples that illustrate what
SCA can do to help you with your programs. The examples have very
little explanation. If you want a more detailed explanation of the
underlying concepts, see the Basic_Query_Concepts help topic. The
remainder of this section is written in terms that are specific to
BASIC programs.
If you want to follow along and try the examples, you will need to
have an SCA library available. If you do not know how to create
an SCA library, read the Building_An_SCA_Library help topic. The
examples use generic variable names (such as i). You will have to
substitute variable names that actually exist in your code when
trying the examples.
The first example is the easiest query of all: It lets you find
all the items in your SCA library named i, and shows you all the
places where they appear (all occurrences of i).
FIND i
You can search for any name in this manner, including using
wildcard characters (for example, FIND i*).
Now let's say you are looking for an occurrence, and you know
that it occurs in a particular file. The following query finds all
occurrences of items that are named i but will then limit them to
those which happen to occur in the file named 'PROG.BAS'.
FIND i AND FILE_SPEC="PROG.BAS"
Another typical question one might ask is "Find all the places
where this item is assigned to (or read from, called, declared,
and so forth)." The next example finds all occurrences of items
that are named i, but then limits them to only those occurrences
where i is assigned a value.
FIND i AND OCCURRENCE=WRITE
(SCA understands many occurrence classes other then WRITE. See the
help subtopics under Getting_Started for tables containing all the
SCA attributes and their corresponding meanings in BASIC.)
Often, you only want to know where (in what file or module) a
particular function is, so that you can go to it and edit it.
You could use the first query (where i would be the name of the
function) and then look through the output. The output would
include all occurrences of the function, one of which would be
its definition, which you could then select. Or, you could ask SCA
to limit the search for you by typing the following query:
FIND i AND OCCURRENCE=PRIMARY
In SCA terms, a primary declaration is the most significant
declaration of an item. For a BASIC function, this means the
actual location of the function body. This is as opposed to
an associated declaration, examples of which are EXTERNAL
declarations, and DECLARE FUNCTION declarations.
Another problem you might have is that there are many different
items in your system having a given name. Some may be variables;
others may be functions, constants, labels, and so forth. Suppose
you want to find only the functions named i. Again, the query
FIND i would give you what you wanted, but it would also give you
much more. It is preferable to issue the following query:
FIND i AND SYMBOL_CLASS=FUNCTION
The last four examples have all selected information based on two
attributes. The last example selected information based on a name
attribute (in this case, i) and a symbol class attribute (in this
case, FUNCTION). Note how the attributes are combined using the
boolean operator AND. In general, you can select items out of your
library based on any combination of attributes, using AND as well
as the other logical operators OR, XOR and NOT.
The next example shows another primary feature of SCA - the
ability to display relationships between items. The example
given here shows the most common use of this feature. It finds
the complete call tree (that is, all functions called directly and
indirectly), of the function named i.
FIND CALLED_BY (I, DEPTH=ALL)
If you want to limit the depth of the call tree, you can replace
the keyword ALL by any positive integer.
The final part of this section describes how to go directly to the
source code once you have issued a query. After issuing the query
FIND i, for example, you could have an LSE query buffer containing
something that looks like the following:
I variable
BASIC_MODULE\60 variable declaration
BASIC_MODULE\75 write reference
BASIC_MODULE\79 read reference
BASIC_MODULE\95 address reference
BASIC_MODULE\122 read reference
BASIC_MODULE\144 write reference
BASIC_MODULE\146 read reference
BASIC_MODULE\149 write reference
BASIC_MODULE\149 read reference
BASIC_MODULE\150 address reference
BASIC_MODULE\166 read reference
The first two lines of this display will be highlighted. The first
line represents the item you looked for (I), and the rest of the
lines represent the different places in the code where this item
occurred (that is, the occurrences of I). By using the up and down
arrows on your keyboard, or by clicking on an occurrence with your
mouse, you can choose the occurrence you want to see. Then type
CTRL/G (the keyboard equivalent of the GOTO SOURCE command), and
LSE will bring the source file into a buffer and position you at
the occurrence you chose.
To obtain help on the following topics, request help as indicated.
o For help on query language, see the Basic_Query_Concepts help
topic.
o For help on libraries, see the Building_An_SCA_Library help
topic.
14.4 – BASIC Attributes Table
The following table lists the SCA symbol classes and their
corresponding meanings in BASIC.
SCA Symbol Classes and Equivalent BASIC Language Terminology
SCA Term BASIC Term Explanation
Argument Parameter Subprogram formal parameter
Component, Record
Field component
Constant, Constant
Literal
Exception N/A
File File A file used during a compilation
Function, Program or For example, PROGRAM, SUB, FUNCTION,
Procedure, subprogram DEF, PICTURE
Program,
Routine,
Subroutine
Generic N/A
Keyword Keyword A PDF keyword
Label Label A line number or statement label
Macro N/A
Module, N/A
Package
Placeholder Placeholder LSE placeholder
Psect Psect MAP or COMMON block
Tag Tag PDF tag
Task N/A
Type Type For example, word, double, decimal,
and so forth
Unbound N/A
Variable Variable
The following table lists the SCA occurrence classes and their
corresponding meanings in BASIC.
SCA Occurrence Classes and Equivalent BASIC Language Terminology
SCA Term BASIC Term Explanation
Primary Declaration For variables, where they are
declared with, for example, DECLARE
or MAP statements. For subprograms,
where they are defined, that is,
where the body of the subprogram is.
Associated Declaration EXTERNAL declarations or DECLARE
FUNCTION statements
Declaration Declaration Either a PRIMARY or ASSOCIATED
declaration
Read, Fetch Read
Write, Store Write
Address, Address Actual parameter to LOC function
Pointer reference
Call Call
Command_line Command line A file specified on the command
line; For example, BASIC foo.bas
Include Include A file specified in a %INCLUDE
directive
Precompiled N/A
Reference Reference Any nondeclaration
Explicit Explicit Any symbol declared by the user
Implicit Implicit Any symbol declared by the compiler
when it sees the first reference
Visible Visible A symbol whose name is visible in
the source
Hidden Hidden A symbol not visible in the source;
for example, function return values,
implicit declarations
Compilation_ For example, a PROGRAM, SUB, or
unit FUNCTION
The following table lists the SCA domain classes and their
corresponding meanings in BASIC.
SCA Domain Classes and Equivalent BASIC Language Terminology
SCA Term BASIC Term Explanation
Inheritable N/A
Global Available across modules; for
example, through EXTERNAL
declarations
Predefined Predefined Defined by the language; for
example, DECIMAL, PI, CHR$, and
so forth
Multi_module Predefined, global, and inheritable
Module_ Visible only within one module; for
specific example, variables
14.5 – Using BLISS
This section contains some basic examples that show what SCA can
do to help you with your programs. The examples have very little
explanation. For a more detailed explanation of the underlying
concepts, see the Basic_Query_Concepts help topic. The remainder
of this section is written in terms that are specific to BLISS
programs.
If you want to follow along and try the examples, you will need to
have an SCA library available. If you do not know how to create
an SCA library, read the Building_An_SCA_Library help topic. The
examples use generic variable names (such as i). You will have to
substitute variable names that actually exist in your code when
trying the examples.
The first example is the easiest query. It lets you find all the
items in your SCA library named i, and shows you all the places
where they appear (all occurrences of i):
FIND i
You can search for any name in this manner, including using
wildcard characters (for example, FIND i*).
Now suppose you are looking for an occurrence, and you know that
it occurs in a particular file. The following query finds all
occurrences of items that are named i, but will then limit them to
those that happen to occur in the file named PROG.B32.
FIND i AND FILE_SPEC="PROG.B32"
Another typical question you might ask is, "Find all the places
where this item is assigned to (or read from, called, declared and
so forth)." The next example finds all occurrences of items that
are named i, but then limits them to only those occurrences where
i is assigned a value:
FIND i AND OCCURRENCE=WRITE
(SCA understands many occurrence classes other then WRITE. See the
help subtopics under Getting_Started for tables containing all the
SCA attributes and their corresponding meanings in BLISS.)
Often, you only want to know where (in what file or module) a
particular routine is, so that you can go to it and edit it. You
can use the first query (where i will be the name of the routine)
and then look through the output. The output will include all
occurrences of the routine, one of which will be its declaration,
which you can then select. Or, you can ask SCA to limit the search
for you by typing the following query:
FIND i AND OCCURRENCE=PRIMARY
In SCA terms, a primary declaration is the most significant
declaration of an item. For a BLISS routine, this means the
place where the routine is actually implemented. This is in
contrast to FORWARD or EXTERNAL declarations, which are associated
declarations.
Another problem you might have is that there are many different
items in your system having a given name. Some may be variables;
others may be routines, literals, macros, and so forth. Suppose
you want to find only the routines named i. Again, the query
FIND i will give you what you wanted, but it will also give you
much more. It is preferable to issue the following query:
FIND i AND SYMBOL_CLASS=ROUTINE
The last four examples have all selected information based on two
attributes. The last example selected information based on a name
attribute (in this case, i) and a symbol_class attribute (in this
case, ROUTINE). Note how the attributes are combined using the
boolean operator AND. In general, you can select items out of your
library based on any combination of attributes, using AND as well
as the other logical operators OR, XOR, and NOT.
The next example shows another primary feature of SCA - the
ability to display relationships between items. This example shows
the most common use of this feature. It finds the complete call
tree (that is, all routines called directly and indirectly) of the
routine named i.
FIND CALLED_BY (i, DEPTH=ALL)
If you want to limit the depth of the call tree, replace the
keyword ALL by any positive integer.
The final part of this section describes how to go directly to the
source code once you have issued a query. After issuing the query
FIND i, for example, you can have an LSE query buffer containing
something that looks like the following:
I variable
BLISS_MODULE\60 LOCAL declaration
BLISS_MODULE\75 write reference
BLISS_MODULE\79 read reference
BLISS_MODULE\122 read reference
BLISS_MODULE\144 write reference
BLISS_MODULE\146 read reference
BLISS_MODULE\149 write reference
BLISS_MODULE\149 read reference
BLISS_MODULE\150 read reference
BLISS_MODULE\166 read reference
The first two lines of this display will be highlighted. The first
line represents the item you looked for (i), and the rest of the
lines represent the different places in the code where this item
occurred (that is, the occurrences of i). By using the up and down
arrows on your keyboard, or by clicking on an occurrence with your
mouse, you can choose the occurrence you want to see. Then, type
CTRL/G (the keyboard equivalent of the GOTO SOURCE command) and
LSE will bring the source file into a buffer and position you at
the occurrence you chose.
To obtain help on the following topics, request help as indicated.
o For help on query language, see the Basic_Query_Concepts help
topic.
o For help on libraries, see the Building_An_SCA_Library help
topic.
14.6 – BLISS Attributes Table
The following table lists the SCA symbol classes and their
corresponding meanings in BLISS.
SCA Symbol Classes and Equivalent BLISS Language Terminology
SCA Term BLISS Term Explanation
Argument Parameter Routine formal parameter
Component, Field Subpart of a BLOCK or BLOCKVECTOR
Field structure
Constant, Literal A literal
Literal
Exception N/A
File file A file used during compilation
Function, routine A routine
Procedure,
Program,
Routine,
Subroutine
Generic N/A
Keyword Keyword PDF keyword tag
Label Label A label identifier
Macro Macro A macro
Module, Module A compilation unit
Package
Placeholder Placeholder An LSE placeholder
Psect Psect A psect
Tag Tag A PDF tag
Task N/A
Type Type For example, fieldset
Unbound Unbound A name the compiler does not know
the purpose of. This is common when
macros are used.
Variable Variable A program variable
The following table lists the SCA occurrence classes and their
corresponding meanings in BLISS.
SCA Occurrence Classes and Equivalent BLISS Language Terminology
SCA Term BLISS Term Explanation
Primary Declaration The declaration containing the
actual implementation
Associated Declaration A FORWARD or EXTERNAL declaration
Declaration Declaration Either a PRIMARY or ASSOCIATED
declaration
Read, Fetch Fetch
Write, Store Store
Address, Address
Pointer
Call call
Command_line Input file A file specified on the command
specification line; for example, BLISS foo.b32
Include Require A file specified in a REQUIRE or
%REQUIRE statement
Precompiled Library A file specified in a LIBRARY
statement
Reference Reference Any nondeclaration
Explicit Explicit Any symbol declared by the user
Implicit Implicit Any symbol declared by the compiler;
for example, a loop variable
Visible Visible A symbol whose name is visible in
the source
Hidden Hidden A symbol whose name is not visible
in the source; for example,
contained inside a macro
Compilation_ Module A module
unit declaration
The following table lists the SCA domain classes and their
corresponding meanings in BLISS.
SCA Domain Classes and Equivalent BLISS Language Terminology
SCA Term BLISS Term Explanation
Inheritable Inheritable A symbol declared in a library file,
and used elsewhere
Global GLOBAL
Predefined Defined by For example, CH$FILL, BLOCKVECTOR,
the language and so forth
Multi_module GLOBAL, Predefined, or Inheritable
Module_ LOCAL or OWN
specific
14.7 – Using C
This section contains some basic examples that illustrate what
SCA can do to help you with your programs. The examples have very
little explanation. If you want a more detailed explanation of the
underlying concepts, see the Basic_Query_Concepts help topic. The
remainder of this section is written in terms that are specific to
C programs.
If you want to follow along and try the examples, you will need to
have an SCA library available. If you do not know how to create
an SCA library, read the Building_An_SCA_Library help topic. The
examples use generic variable names (such as i). You will have to
substitute variable names that actually exist in your code when
trying the examples.
The first example is the easiest query: It lets you find all the
items in your SCA library named i, and shows you all the places
where they appear (all occurrences of i).
FIND i
You can search for any name in this manner, including using
wildcard characters (for example, FIND i*).
Now let's say you are looking for an occurrence, and you know
that it occurs in a particular file. The following query finds all
occurrences of items that are named i but will then limit them to
those which happen to occur in the file named 'PROG.C'.
FIND i AND FILE_SPEC="PROG.C"
Another typical question one might ask is "Find all the places
where this item is assigned to (or read from, called, declared,and
so forth)." The next example finds all occurrences of items that
are named i, but then limits them to only those occurrences where
i is assigned a value.
FIND i AND OCCURRENCE=WRITE
(SCA understands many occurrence classes other then WRITE. See the
help subtopics under Getting_Started for tables containing all the
SCA attributes and their corresponding meanings in C.)
Often, you only want to know where (in what file or module) a
particular function is, so that you can go to it and edit it.
You could use the first query (where i would be the name of the
function) and then look through the output. The output would
include all occurrences of the function, one of which would be
its definition, which you could then select. Or, you could ask SCA
to limit the search for you by typing the following query:
FIND i AND OCCURRENCE=PRIMARY
In SCA terms, a primary declaration is the most significant
declaration of an item. For a C function, this means the function
definition. This is in contrast to a C function declaration
(for example, extern i()), which in SCA terms is an associated
declaration.
Another problem you might have is that there are many different
items in your system having a given name. Some may be variables;
others may be functions, #define constants, macros, and so forth.
Suppose you want to find only the functions named i. Again, the
query FIND i would give you what you wanted, but it would also
give you much more. It is preferable to issue the following query:
FIND i AND SYMBOL_CLASS=FUNCTION
The last four examples have all selected information based on two
attributes. The last example selected information based on a name
attribute (in this case, i) and a symbol class attribute (in this
case, FUNCTION). Note how the attributes are combined using the
boolean operator AND. In general, you can select items out of your
library based on any combination of attributes, using AND as well
as the other logical operators OR, XOR and NOT.
The next example shows another primary feature of SCA - the
ability to display relationships between items. The example
given here shows the most common use of this feature. It finds
the complete call tree (that is, all functions called directly and
indirectly), of the function named i.
FIND CALLED_BY (i, DEPTH=ALL)
If you want to limit the depth of the call tree, you can replace
the keyword ALL by any positive integer.
The final part of this section describes how to go directly to the
source code once you have issued a query. After issuing the query
FIND i, for example, you can have an LSE query buffer containing
something that looks like the following:
i variable
C_MODULE\60 variable definition declaration
C_MODULE\75 write reference
C_MODULE\79 read reference
C_MODULE\95 read, write reference
C_MODULE\122 read reference
C_MODULE\144 write reference
C_MODULE\146 read reference
C_MODULE\149 write reference
C_MODULE\149 read reference
C_MODULE\150 read reference
C_MODULE\166 read reference
The first two lines of this display will be highlighted. The first
line represents the item you looked for (i), and the rest of the
lines represent the different places in the code where this item
occurred (that is, the occurrences of i). By using the up and down
arrows on your keyboard, or by clicking on an occurrence with your
mouse, you can choose the occurrence you want to see. Then all
you have to do is type CTRL/G (the keyboard equivalent of the GOTO
SOURCE command), and LSE will bring the source file into a buffer
and position you at the occurrence you chose.
To obtain help on the following topics, request help as indicated.
o For help on query language, see the Basic_Query_Concepts help
topic.
o For help on libraries, see the Building_An_SCA_Library help
topic.
14.8 – C Attributes Table
The following table lists the SCA symbol classes and their
corresponding meanings in C.
SCA Symbol Classes and Equivalent C Language Terminology
SCA Term C Term Explanation
Argument Formal The variable named in a function
Parameter definition
Component, Member A member of a structure or union
Field
Constant, Constant A defined value that does not change
Literal
Exception N/A
File File A file used during compilation
Function, Function Any function ( such as 'main' )
Procedure,
Program,
Routine,
Subroutine
Generic N/A
Keyword Keyword PDF keyword tag
Label Label A label identifier
Macro Macro A Macro created by #define
Module, Module Each .c source file represents a
Package module
Placeholder Placeholder An LSE placeholder
Psect N/A
Tag Tag A PDF tag
Task N/A
Type Type int, float, struct {...}, typedef,
and so forth
Unbound N/A
Variable Variable Program variable
The following table lists the SCA occurrence classes and their
corresponding meanings in C.
SCA Occurrence Classes and Equivalent C Language Terminology
SCA Term C Term Explanation
Primary Declaration Most significant declaration; for
or definition example, a variable declaration, or
a function definition
Associated Declaration Other declarations; for example,
function declarations or EXTERN
declarations
Declaration Definition or Any declaration, either primary or
Declaration associated
Read, Fetch Read The act of retrieving an Rvalue
Write, Store Write Changing the contents of an Lvalue
Address, Address The use of the & operator
Pointer
Call Call A function call
Command_line Command_line A file specified on the command
line, for example, CC foo.c
Include Include A file specified in a #include
preprocessor directive
Precompiled N/A
Reference Reference Any nondeclaration
Explicit Explicit An entity that is explicitly
declared
Implicit Implicit An entity that is implicitly
declared by the compiler; for
example, a function with no type
is implicitly declared as INT
Visible Visible Occurrence appears in source
Hidden Hidden Occurrence does not appear in
source; for example, it appears
only in the expansion of a macro
Compilation_ Module A module
unit
The following table lists the SCA domain classes and their
corresponding meanings in C.
SCA Domain Classes and Equivalent C Language Terminology
SCA Term C Term Explanation
Inheritable N/A
Global Globally For example, extern, globaldef,
visible globalref, globalvalue
Predefined Defined by For example, int, float, char
the language
Multi_module Predefined and global
Module_ Local to one For example, static, auto, register
specific module
14.9 – Using C++
This section contains some basic examples that illustrate what
SCA can do to help you with your programs. The examples have very
little explanation. If you want a more detailed explanation of the
underlying concepts, see the Basic_Query_Concepts help topic. The
remainder of this section is written in terms that are specific to
C++ programs.
If you want to follow along and try the examples, you will need to
have an SCA library available. The examples use generic variable
names (such as 'i'). You will have to substitute variable names that
exist in your code when trying the examples.
The first example is the easiest query: It lets you find all the
items in your SCA library named i, and shows you all the places
where they appear (all occurrences of i).
FIND i
You can search for any name in this manner, including using
wildcard characters (for example, FIND i*).
Now let's say you are looking for an occurrence, and you know
that it occurs in a particular file. The following query finds all
occurrences of items that are named i but will then limit them to
those which happen to occur in the file named 'PROG.CXX'.
FIND i AND FILE_SPEC="PROG.CXX"
Another typical question one might ask is "Find all the places
where this item is assigned to (or read from, called, declared,and
so forth)." The next example finds all occurrences of items that
are named i, but then limits them to only those occurrences where
i is assigned a value.
FIND i AND OCCURRENCE=WRITE
(SCA understands many occurrence classes other then WRITE. See the
help subtopics under Getting_Started for tables containing all the
SCA attributes and their corresponding meanings in C++.)
Often, you only want to know where (in what file or module) a
particular function is, so that you can go to it and edit it.
You could use the first query (where i would be the name of the
function) and then look through the output. The output would
include all occurrences of the function, one of which would be
its definition, which you could then select. Or, you could ask SCA
to limit the search for you by typing the following query:
FIND i AND OCCURRENCE=PRIMARY
In SCA terms, a primary declaration is the most significant
declaration of an item. For a C++ function, this means the function
definition. This is in contrast to a C++ function declaration (for
example, extern i()), which in SCA terms is an associated declaration.
Another problem you might have is that there are many different
items in your system having a given name. Some may be variables;
others may be functions, #define constants, macros, and so forth.
Suppose you want to find only the functions named i. Again, the
query FIND i would give you what you wanted, but it would also
give you much more. It is preferable to issue the following query:
FIND i AND SYMBOL_CLASS=FUNCTION
The last four examples have all selected information based on two
attributes. The last example selected information based on a name
attribute (in this case, i) and a symbol class attribute (in this
case, FUNCTION). Note how the attributes are combined using the
boolean operator AND. In general, you can select items out of your
library based on any combination of attributes, using AND as well
as the other logical operators OR, XOR and NOT.
The next example shows another primary feature of SCA - the
ability to display relationships between items. The example
given here shows the most common use of this feature. It finds
the complete call tree (that is, all functions called directly and
indirectly), of the function named i.
FIND CALLED_BY (i, DEPTH=ALL)
If you want to limit the depth of the call tree, you can replace
the keyword ALL by any positive integer.
To obtain help on the following topics, request help as indicated.
o For help on query language, see the Basic_Query_Concepts help
topic.
o For help on libraries, see the Building_An_SCA_Library help
topic.
14.10 – C++ Attributes Table
The following table lists the SCA symbol classes and their
corresponding meanings in C++.
SCA Symbol Classes and Equivalent C++ Language Terminology
SCA Term C++ Term Explanation
Argument Formal Formal arguement such as a routine
Parameter or macro argument
Class Class Any C++ class object defined by class,
structure or union
Component, Class, structure A component of a class, structure
Field or union member or union
Constant, Constant Named compile-time constants
Literal
Exception Exception A program exception specified by
the catch, throw and try statements
File File A file used during compilation
Function, Function Callable routines defined by function
Procedure, statements
Program,
Routine,
Subroutine
Generic Template Generic object defined by template
objects
Keyword Keyword PDF keyword tag
Label Function Label User-specified label
Macro Macro A Macro created by #define
Module, Module Any logical program unit typically
Package each .cxx source file represents a
module
Placeholder Placeholder An LSE placeholder
Psect N/A
Tag Tag A PDF tag
Task N/A
Type Type int, float, struct {...}, typedef,
and so forth
Unbound N/A
Variable Variable Program variable
The following table lists the SCA occurrence classes and their
corresponding meanings in C++.
SCA Occurrence Classes and Equivalent C++ Language Terminology
SCA Term C++ Term Explanation
Primary Declaration Most significant declaration; for
or definition example, a variable declaration, or
a function definition
Associated Declaration Other declarations; for example,
function declarations or EXTERN
declarations
Declaration Definition or Any declaration, either primary or
Declaration associated
Read, Fetch Read The act of retrieving an Rvalue
Write, Store Write Changing the contents of an Lvalue
Address, Address The use of the & operator
Pointer
Call Call A function call
Command_line Command_line A file specified on the command
line, for example, Cxx foo.c
Include Include A file specified in a #include
preprocessor directive
Precompiled N/A
Base Base Any base class of a class
Friend Friend Any friend of a class
Member Member Any member of a class
Reference Reference Any nondeclaration
Explicit Explicit An entity that is explicitly
declared
Implicit Implicit An entity that is implicitly
declared by the compiler; for
example, a function with no type
is implicitly declared as INT
Visible Visible Occurrence appears in source
Hidden Hidden Occurrence does not appear in
source; for example, it appears
only in the expansion of a macro
Compilation_ Module A module
unit
Private Private Any private object
Protected Protected Any protected object
Public Public Any public object
Virtual Virtual Any virtual object
The following table lists the SCA domain classes and their
corresponding meanings in C++.
SCA Domain Classes and Equivalent C++ Language Terminology
SCA Term C++ Term Explanation
Inheritable N/A
Global Globally For example, extern, globaldef,
visible globalref, globalvalue
Predefined Defined by For example, int, float, char
the language
Multi_module Predefined and global
Module_ Local to one For example, static, auto, register
specific module
14.11 – Using COBOL
This section contains some basic examples that illustrate what
SCA can do to help you with your programs. The examples have very
little explanation. If you want a more detailed explanation of the
underlying concepts, see the Basic_Query_Concepts help topic. The
remainder of this section is written in terms that are specific to
Cobol programs.
If you want to follow along and try the examples, you will need to
have an SCA library available. If you do not know how to create
an SCA library, read the Building_An_SCA_Library help topic. The
examples use generic variable names (such as i). You will have to
substitute variable names that actually exist in your code when
trying the examples.
The first example is the easiest query: It lets you find all the
items in your SCA library named i, and shows you all the places
where they appear (all occurrences of i).
FIND i
You can search for any name in this manner, including using
wildcard characters (for example, FIND i*).
Now let's say you are looking for an occurrence, and you know
that it occurs in a particular file. The following query finds all
occurrences of items that are named i but will then limit them to
those which happen to occur in the file named 'PROG.COB'.
FIND i AND FILE_SPEC="PROG.COB"
Another typical question one might ask is "Find all the places
where this item is assigned to (or read from, called, declared,
and so forth)." The next example finds all occurrences of items
that are named i, but then limits them to only those occurrences
where i is assigned a value.
FIND i AND OCCURRENCE=WRITE
(SCA understands many occurrence classes other then WRITE. See the
help subtopics under Getting_Started for tables containing all the
SCA attributes and their corresponding meanings in COBOL.)
Often, you only want to know where (in what file ) a particular
procedure is, so that you can go to it and edit it. You could use
the first query (where i would be the program-id) and then look
through the output. The output would include all occurrences of
the program, one of which would be its definition, which you could
then select. Or, you could ask SCA to limit the search for you by
typing the following query:
FIND i AND OCCURRENCE=PRIMARY
In SCA terms, a primary declaration is the most significant
declaration of an item. For a Cobol program, this is the program-
id. This is in contrast to an associated declaration. Actually,
in Cobol, associated declarations do not have much meaning. The
compiler creates implicit associated declarations for a program
the first time it is called.
Another problem you might have is that there are many different
items in your system having a given name. Some may be variables;
others may be programs, paragraph names, files, and so forth.
Suppose you want to find only the programs named i. Again, the
query FIND i would give you what you wanted, but it would also
give you much more. It is preferable to issue the following query:
FIND i AND SYMBOL_CLASS=PROGRAM
The last four examples have all selected information based on two
attributes. The last example selected information based on a name
attribute (in this case, i) and a symbol class attribute (in this
case, PROGRAM). Note how the attributes are combined using the
boolean operator AND. In general, you can select items out of your
library based on any combination of attributes, using AND as well
as the other logical operators OR, XOR and NOT.
The next example shows another primary feature of SCA - the
ability to display relationships between items. The example
given here shows the most common use of this feature. It finds
the complete call tree (that is, all programs called directly and
indirectly), of the program named i.
FIND CALLED_BY (I, DEPTH=ALL)
If you want to limit the depth of the call tree, you can replace
the keyword ALL by any positive integer.
The final part of this section describes how to go directly to the
source code once you have issued a query. After issuing the query
FIND i, for example, you can have an LSE query buffer containing
something that looks like the following:
I variable
COBOL_MODULE\60 data declaration
COBOL_MODULE\75 write reference
COBOL_MODULE\79 read reference
COBOL_MODULE\122 read reference
COBOL_MODULE\144 write reference
COBOL_MODULE\146 read reference
COBOL_MODULE\149 read reference
COBOL_MODULE\166 read reference
The first two lines of this display will be highlighted. The first
line represents the item you looked for (I), and the rest of the
lines represent the different places in the code where this item
occurred (that is, the occurrences of I). By using the up and down
arrows on your keyboard, or by clicking on an occurrence with your
mouse, you can choose the occurrence you want to see. Then all
you have to do is type CTRL/G (the keyboard equivalent of the GOTO
SOURCE command), and LSE will bring the source file into a buffer
and position you at the occurrence you chose.
To obtain help on the following topics, request help as indicated.
o For help on query language, see the Basic_Query_Concepts help
topic.
o For help on libraries, see the Building_An_SCA_Library help
topic.
14.12 – COBOL Attributes Table
The following table lists the SCA symbol classes and their
corresponding meanings in COBOL.
SCA Symbol Classes and Equivalent COBOL Language Terminology
SCA Term COBOL Term Explanation
Argument Program
argument
Component, Group item
Field
Constant, A character string whose value is
Literal specified by the ordered set of
characters it contains, or a reserve
word that is a figurative constant;
for example, "1.234E7", ZERO
Exception N/A
File File A file used during the compilation
Function, Program A program
Procedure,
Program,
Routine,
Subroutine
Generic N/A
Keyword Keyword A PDF keyword
Label Paragraph-
name or
section-name
Macro N/A
Module, N/A
Package
Placeholder Placeholder An LSE placeholder
Psect PSECT
Tag Tag A PDF tag
Task N/A
Type Datatype
Unbound Symbols in conditional compilation
lines
Variable Data item
The following table lists the SCA occurrence classes and their
corresponding meanings in COBOL.
SCA Occurrence Classes and Equivalent COBOL Language Terminology
SCA Term COBOL Term Explanation
Primary Declaration Data declarations, program ids
Associated Implicit declarations of called
programs the first time they are
seen
Declaration Declaration Both primary and associated
declarations
Read, Fetch FETCH
Write, Store STORE
Address, N/A
Pointer
Call CALL
Command_line A file specified on the command
line, for example, COBOL foo.cob
Include COPY
Precompiled N/A
Reference Reference Any nondeclaration
Explicit A variable declared by the user
Implicit A variable automatically defined by
the compiler
Visible Not hidden
Hidden Hidden occurrences may be due to
default conditions (for example,
PIC 9(4) is given the DISPLAY TYPE)
or within complex statement (for
example, COMPUTE and hidden write
references).
Compilation_ SCP
unit separately
compiled unit
The following table lists the SCA domain classes and their
corresponding meanings in COBOL.
SCA Domain Classes and Equivalent COBOL Language Terminology
SCA Term COBOL Term Explanation
Inheritable N/A
Global EXTERNAL
Predefined PREDEFINED For example, special registers
Multi_module Global and predefined
Module_ Not multi-module
specific
14.13 – Using FORTRAN
This section contains some basic examples that illustrate what
SCA can do to help you with your programs. The examples have very
little explanation. If you want a more detailed explanation of the
underlying concepts, see the Basic_Query_Concepts help topic. The
remainder of this section is written in terms that are specific to
FORTRAN programs.
If you want to follow along and try the examples, you will need to
have an SCA library available. If you do not know how to create
an SCA library, read the Building_An_SCA_Library help topic. The
examples use generic variable names (such as i). You will have to
substitute variable names that actually exist in your code when
trying the examples.
The first example is the easiest query: It lets you find all the
items in your SCA library named i, and shows you all the places
where they appear (all occurrences of i).
FIND i
characters (for example, FIND i*).
Now let's say you are looking for an occurrence, and you know
that it occurs in a particular file. The following query finds all
occurrences of items that are named i but will then limit them to
those which happen to occur in the file named 'PROG.FOR'.
FIND i AND FILE_SPEC="PROG.FOR"
Another typical question one might ask is "Find all the places
where this item is assigned to (or read from, called, declared,
and so forth)." The next example finds all occurrences of items
that are named i, but then limits them to only those occurrences
where i is assigned a value.
FIND i AND OCCURRENCE=WRITE
(SCA understands many occurrence classes other then WRITE. See the
help subtopics under Getting_Started for tables containing all the
SCA attributes and their corresponding meanings in FORTRAN.)
Often, you only want to know where (in what file or module) a
particular subroutine is, so that you can go to it and edit it.
You could use the first query (where i would be the name of the
subroutine) and then look through the output. The output would
include all occurrences of the subroutine, one of which would be
its definition, which you could then select. Or, you could ask SCA
to limit the search for you by typing the following query:
FIND i AND OCCURRENCE=PRIMARY
In SCA terms, a primary declaration is the most significant
declaration of an item. For a FORTRAN subroutine, this is where
the actual SUBROUTINE statement is. This is in contrast to a
FORTRAN EXTERNAL declaration, which in SCA terms is an associated
declaration. The FORTRAN compiler also creates implicit associated
declarations for any undeclared functions.
Another problem you might have is that there are many different
items in your system having a given name. Some may be variables;
others may be subroutines, PARAMETER constants, and so forth.
Suppose you want to find only the subroutines named i. Again, the
query FIND i would give you what you wanted, but it would also
give you much more. It is preferable to issue the following query:
FIND i AND SYMBOL_CLASS=SUBROUTINE
The last four examples have all selected information based on two
attributes. The last example selected information based on a name
attribute (in this case, i) and a symbol class attribute (in this
case, SUBROUTINE). Note how the attributes are combined using the
boolean operator AND. In general, you can select items out of your
library based on any combination of attributes, using AND as well
as the other logical operators OR, XOR and NOT.
The next example shows another primary feature of SCA - the
ability to display relationships between items. The example
given here shows the most common use of this feature. It finds
the complete call tree (that is, all subroutines called directly
and indirectly), of the subroutine named i.
FIND CALLED_BY (I, DEPTH=ALL)
If you want to limit the depth of the call tree, you can replace
the keyword ALL by any positive integer.
The final part of this section describes how to go directly to the
source code once you have issued a query. After issuing the query
FIND i, for example, you can have an LSE query buffer containing
something that looks like the following:
I variable
FORTRAN_MODULE\60 variable declaration
FORTRAN_MODULE\75 write reference
FORTRAN_MODULE\79 read reference
FORTRAN_MODULE\95 address reference
FORTRAN_MODULE\122 read reference
FORTRAN_MODULE\144 write reference
FORTRAN_MODULE\146 read reference
FORTRAN_MODULE\149 write reference
FORTRAN_MODULE\149 read reference
FORTRAN_MODULE\150 address reference
FORTRAN_MODULE\166 read reference
The first two lines of this display will be highlighted. The first
line represents the item you looked for (I), and the rest of the
lines represent the different places in the code where this item
occurred (that is, the occurrences of I). By using the up and down
arrows on your keyboard, or by clicking on an occurrence with your
mouse, you can choose the occurrence you want to see. Then all
you have to do is type CTRL/G (the keyboard equivalent of the GOTO
SOURCE command), and LSE will bring the source file into a buffer
and position you at the occurrence you chose.
To obtain help on the following topics, request help as indicated.
o For help on query language, see the Basic_Query_Concepts help
topic.
o For help on libraries, see the Building_An_SCA_Library help
topic.
14.14 – FORTRAN Attributes Table
The following table lists the SCA symbol classes and their
corresponding meanings in FORTRAN.
SCA Symbol Classes and Equivalent FORTRAN Language Terminology
SCA Term FORTRAN Term Explanation
Argument Dummy The variable named in a function
argument declaration
Component, record
Field component
Constant, PARAMETER
Literal
Exception N/A
File File A file used during compilation
Function, SUBROUTINE or A SUBROUTINE, FUNCTION, or main
Procedure, FUNCTION program
Program,
Routine,
Subroutine
Generic N/A
Keyword Keyword A PDF keyword
Label Label A statement label
Macro N/A
Module, BLOCK DATA,
Package SUBROUTINE
Placeholder Placeholder An LSE placeholder
Psect COMMON block
Tag tag A PDF tag
Task N/A
Type Type For example, INTEGER, REAL, COMPLEX
and so forth
Unbound N/A
Variable Variable
The following table lists the SCA occurrence classes and their
corresponding meanings in FORTRAN.
SCA Occurrence Classes and Equivalent FORTRAN Language Terminology
SCA Term FORTRAN Term Explanation
Primary Declaration The declaration containing the
actual implementation
Associated Declaration An EXTERNAL declaration
Declaration Declaration Any declaration, either primary or
associated
Read, Fetch Read
Write, Store Write
Address, Address %LOC, actual arguments
Pointer
Call Call For example, a CALL statement
Command_line Command line A file specified on the command
line; for example, FORTRAN foo.for
Include INCLUDE A file specified in an INCLUDE
statement
Precompiled N/A
Reference Reference Any nondeclaration
Explicit Explicit Any symbol declared by the user
Implicit Implicit Any symbol declared by the compiler
when it sees the first reference
Visible Visible A symbol whose name is visible in
the source
Hidden Hidden A symbol whose name is not visible
in the source
Compilation_ Program unit A SUBROUTINE, FUNCTION, PROGRAM,
unit BLOCK DATE, and so forth
The following table lists the SCA domain classes and their
corresponding meanings in FORTRAN.
SCA Domain Classes and Equivalent FORTRAN Language Terminology
SCA Term FORTRAN Term Explanation
Inheritable N/A
Global A SUBROUTINE, FUNCTION, or COMMON
block
Predefined Defined by For example, INTEGER, REAL*4, and so
the language forth
Multi_module GLOBAL,
predefined,
and
inheritable
Module_ Only known within a SUBROUTINE,
specific FUNCTION, and so forth
14.15 – Using Pascal
This section contains some basic examples that illustrate what
SCA can do to help you with your programs. The examples have very
little explanation. If you want a more detailed explanation of the
underlying concepts, see the Basic_Query_Concepts help topic. The
remainder of this section is written in terms that are specific to
Pascal programs.
If you want to follow along and try the examples, you will need to
have an SCA library available. The SCA$EXAMPLE library provided
with SCA is based on Pascal, so you could use it. If you want
to use your own library, but do not know how to create an SCA
library, read the Building_An_SCA_Library help topic. The examples
in this section use variables from the SCA$EXAMPLE library. If you
use your own library, you will have to substitute variable names
that actually exist in your code when trying the examples.
The first example is the easiest query: It lets you find all the
items in your SCA library named i, and shows you all the places
where they appear (all occurrences of i).
FIND i
You can search for any name in this manner, including using
wildcard characters (for example, FIND i*).
Now let's say you are looking for an occurrence, and you know
that it occurs in a particular file. The following query finds all
occurrences of items that are named i but will then limit them to
those which happen to occur in the file named 'BUILDTABLE.PAS'.
FIND i AND FILE_SPEC="BUILDTABLE.PAS"
Another typical question one might ask is "Find all the places
where this item is assigned to (or read from, called, declared,
and so forth)." The next example finds all occurrences of items
that are named c, but then limits them to only those occurrences
where c is assigned a value.
FIND c AND OCCURRENCE=WRITE
(SCA understands many occurrence classes other then WRITE. See the
help subtopics under Getting_Started for tables containing all the
SCA attributes and their corresponding meanings in Pascal.)
Often, you only want to know where (in what file or module) a
particular procedure is, so that you can go to it and edit it. You
could use a query similar to the first (where i would be replaced
by the name of the procedure) and then look through the output.
The output would include all occurrences of the procedure, one
of which would be its declaration, which you could then select.
Or, you could ask SCA to limit the search for you by typing the
following query:
FIND build_table AND OCCURRENCE=PRIMARY
In SCA terms, a primary declaration is the most significant
declaration of an item. For a Pascal procedure, this means the
place where the procedure is actually implemented. This is in
contrast to FORWARD or EXTERNAL declarations, which are associated
declarations.
Another problem you might have is that there are many different
items in your system having a given name. Some may be variables;
others may be functions, constants, labels, and so forth. Suppose
you want to find only the procedures named 'build_table'. Again,
the query FIND build_table would give you what you wanted, but
it would also give you much more. It is preferable to issue the
following query:
FIND build_table AND SYMBOL_CLASS=PROCEDURE
The last four examples have all selected information based on
two attributes. The last example selected information based on a
name attribute (in this case, 'build_table') and a symbol class
attribute (in this case, PROCEDURE). Note how the attributes
are combined using the boolean operator AND. In general, you
can select items out of your library based on any combination
of attributes, using AND as well as the other logical operators
OR, XOR and NOT.
The next example shows another primary feature of SCA - the
ability to display relationships between items. The example
given here shows the most common use of this feature. It finds
the complete call tree (that is, all procedures called directly
and indirectly), of the procedure named 'build_table'.
FIND CALLED_BY (build_table, DEPTH=ALL)
If you want to limit the depth of the call tree, you can replace
the keyword ALL by any positive integer.
The final part of this section describes how to go directly to the
source code once you have issued a query. After issuing the query
FIND c, for example, you can have an LSE query buffer containing
something that looks like the following:
C variable
EXPAND_STRING\60 VAR (variable) declaration
EXPAND_STRING\75 write reference
EXPAND_STRING\79 read reference
EXPAND_STRING\95 read reference
EXPAND_STRING\122 read reference
EXPAND_STRING\144 write reference
EXPAND_STRING\146 read reference
EXPAND_STRING\149 write reference
EXPAND_STRING\149 read reference
EXPAND_STRING\150 read reference
EXPAND_STRING\166 read reference
The first two lines of this display will be highlighted. The first
line represents the item you looked for (c), and the rest of the
lines represent the different places in the code where this item
occurred (that is, the occurrences of c). By using the up and down
arrows on your keyboard, or by clicking on an occurrence with your
mouse, you can choose the occurrence you want to see. Then all
you have to do is type CTRL/G (the keyboard equivalent of the GOTO
SOURCE command), and LSE will bring the source file into a buffer
and position you at the occurrence you chose.
To obtain help on the following topics, request help as indicated.
o For help on query language, see the Basic_Query_Concepts help
topic.
o For help on libraries, see the Building_An_SCA_Library help
topic.
14.16 – Pascal Attributes Table
The following table lists the SCA symbol classes and their
corresponding meanings in Pascal.
SCA Symbol Classes and Equivalent Pascal Language Terminology
SCA Term Pascal Term Explanation
Argument Formal
parameter
Component, Component, Components of array types, VARYING,
Field String STRING; fields of records
Constant, Constant CONSTants, predefined constants,
Literal enumerated type constants
Exception N/A
File File A file used during compilation
Function, Function,
Procedure, procedure
Program,
Routine,
Subroutine
Generic N/A
Keyword Keyword A PDF keyword
Label Label Label declarations and uses
Macro N/A
Module, Program,
Package module
Placeholder Placeholder An LSE placeholder
Psect Psect PSECT and COMMON attributes
Tag Tag A PDF tag
Task N/A
Type Type For example, pointer, array,
enumerated, subrange types
Unbound N/A
Variable Variable
The following table lists the SCA occurrence classes and their
corresponding meanings in Pascal.
SCA Occurrence Classes and Equivalent Pascal Language Terminology
SCA Term Pascal Term Explanation
Primary Declaration For example, PROCEDURE XYZ;
Associated FORWARD and For example,
EXTERNAL PROCEDURE XYZ; EXTERNAL;
declarations
Declaration Declaration Both primary and associated
declarations
Read, Fetch Read
Write, Store Write
Address, Address
Pointer
Call Call
Command_line Command line A file specified on the command
line, for example, PASCAL foo.pas
Include Include A file specified in an INCLUDE
statement
Precompiled Environment A file specified in an INHERIT
clause
Reference Reference Any nondeclaration
Explicit Pascal has no implicit occurrences.
Everything is explicit.
Implicit N/A
Visible Appears in the source
Hidden Does not appear in the source, for
example,
VAR I : INTEGER VALUE 10 has a
hidden write reference.
Compilation_ Module,
unit Program
The following table lists the SCA domain classes and their
corresponding meanings in Pascal.
SCA Domain Classes and Equivalent Pascal Language Terminology
SCA Term Pascal Term Explanation
Inheritable Inherited or Items in an environment file and
inheritable items inherited from an environment
file
Global GLOBAL Items declared with the GLOBAL
attribute
Predefined Predeclared For example, INTEGER, TRUE, WRITELN
Multi_module Inheritable, Global, Predefined
Module_ Items local to a compilation unit,
specific and not in an environment file
14.17 – EPascal Attributes Table
The following table lists the SCA symbol classes and their
corresponding meanings in EPascal.
SCA Symbol Classes and Equivalent EPascal Language Terminology
SCA Term EPascal Term Explanation
Argument Formal
parameter
Component, Component, Components of array types, VARYING,
Field String STRING; fields of records
Constant, Constant CONSTants, predefined constants,
Literal enumerated type constants
Exception INTERRUPT_SERVICE Interrupt Service routine
File File A file used during compilation
Function, Function,
Procedure, procedure
Routine,
Subroutine
Generic N/A
Keyword N/A
Label Label Label declarations and uses
Macro N/A
Module, Program,
Package module
Placeholder N/A
Program PROGRAM
Psect Psect PSECT and COMMON attributes
Tag N/A
Task PROCESS_BLOCK
Type Type For example, pointer, array,
enumerated, subrange types
Unbound Flexible type
Variable Variable
The following table lists the SCA occurrence classes and their
corresponding meanings in EPascal.
SCA Occurrence Classes and Equivalent EPascal Language Terminology
SCA Term EPascal Term Explanation
Primary Declaration For example, PROCEDURE XYZ;
Associated FORWARD and For example,
EXTERNAL PROCEDURE XYZ; EXTERNAL;
declarations
Declaration Declaration Both primary and associated
declarations
Read, Fetch Read
Write, Store Write
Address, Address
Pointer
Call Call
Command_line Command line A file specified on the command
line, for example, EPASCAL foo.pas
Include %Include A file specified in a %INCLUDE
statement
Precompiled Include A file specified in an INCLUDE
statement
Reference Reference Any nondeclaration
Explicit EPascal has no implicit occurrences.
Everything is explicit.
Implicit N/A
Visible Appears in the source
Hidden Does not appear in the source, for
example,
VAR I : INTEGER VALUE 10 has a
hidden write reference.
Compilation_ Module,
unit Program
The following table lists the SCA domain classes and their
corresponding meanings in EPascal.
SCA Domain Classes and Equivalent EPascal Language Terminology
SCA Term EPascal Term Explanation
Inheritable INCLUDEd Items in a precompiled file.
Global GLOBAL Items declared with the GLOBAL
attribute
Predefined Predeclared For example, INTEGER, TRUE, WRITELN
Multi_module Inheritable, Global, Predefined
Module_ Items local to a compilation unit,
specific and not in a precompiled file.
14.18 – Using SCAN
This section contains some basic examples that illustrate what
SCA can do to help you with your programs. The examples have very
little explanation. If you want a more detailed explanation of the
underlying concepts, see the Basic_Query_Concepts help topic. The
remainder of this section is written in terms that are specific to
SCAN programs.
If you want to follow along and try the examples, you will need to
have an SCA library available. If you do not know how to create
an SCA library, read the Building_An_SCA_Library help topic. The
examples use generic variable names (such as i). You will have to
substitute variable names that actually exist in your code when
trying the examples.
The first example is the easiest query: It lets you find all the
items in your SCA library named i, and shows you all the places
where they appear (all occurrences of i).
FIND i
You can search for any name in this manner, including using
wildcard characters (for example, FIND i*).
Now let's say you are looking for an occurrence, and you know
that it occurs in a particular file. The following query finds all
occurrences of items that are named i but will then limit them to
those which happen to occur in the file named 'PROG.SCN'.
FIND i AND FILE_SPEC="PROG.SCN"
Another typical question one might ask is "Find all the places
where this item is assigned to (or read from, called, declared,
and so forth)." The next example finds all occurrences of items
that are named i, but then limits them to only those occurrences
where i is assigned a value.
FIND i AND OCCURRENCE=WRITE
(SCA understands many occurrence classes other then WRITE. See the
help subtopics under Getting_Started for tables containing all the
SCA attributes and their corresponding meanings in SCAN.)
Often, you only want to know where (in what file or module) a
particular procedure is, so that you can go to it and edit it.
You could use the first query (where i would be the name of the
procedure) and then look through the output. The output would
include all occurrences of the procedure, one of which would be
its declaration, which you could then select. Or, you could ask
SCA to limit the search for you by typing the following query:
FIND i AND OCCURRENCE=PRIMARY
In SCA terms, a primary declaration is the most significant
declaration of an item. For a SCAN procedure, this means the
place where the procedure is actually implemented, that is, the
PROCEDURE declaration. This is in contrast to FORWARD or EXTERNAL
declarations, which are associated declarations
Another problem you might have is that there are many different
items in your system having a given name. Some may be variables;
others may be procedures, constants, labels, and so forth. Suppose
you want to find only the procedures named i. Again, the query
FIND i would give you what you wanted, but it would also give you
much more. It is preferable to issue the following query:
FIND i AND SYMBOL_CLASS=PROCEDURE
The last four examples have all selected information based on two
attributes. The last example selected information based on a name
attribute (in this case, i) and a symbol class attribute (in this
case, PROCEDURE). Note how the attributes are combined using the
boolean operator AND. In general, you can select items out of your
library based on any combination of attributes, using AND as well
as the other logical operators OR, XOR and NOT.
The next example shows another primary feature of SCA - the
ability to display relationships between items. The example
given here shows the most common use of this feature. It finds
the complete call tree (that is, all procedures called directly
and indirectly), of the procedure named i.
FIND CALLED_BY (i, DEPTH=ALL)
If you want to limit the depth of the call tree, you can replace
the keyword ALL by any positive integer.
The final part of this section describes how to go directly to the
source code once you have issued a query. After issuing the query
FIND i, for example, you can have an LSE query buffer containing
something that looks like the following:
I variable
SCAN_MODULE\60 variable declaration
SCAN_MODULE\75 write reference
SCAN_MODULE\79 read reference
SCAN_MODULE\122 read reference
SCAN_MODULE\144 write reference
SCAN_MODULE\146 read reference
SCAN_MODULE\149 write reference
SCAN_MODULE\149 read reference
SCAN_MODULE\150 read reference
SCAN_MODULE\166 read reference
The first two lines of this display will be highlighted. The first
line represents the item you looked for (i), and the rest of the
lines represent the different places in the code where this item
occurred (that is, the occurrences of i). By using the up and down
arrows on your keyboard, or by clicking on an occurrence with your
mouse, you can choose the occurrence you want to see. Then all
you have to do is type CTRL/G (the keyboard equivalent of the GOTO
SOURCE command), and LSE will bring the source file into a buffer
and position you at the occurrence you chose.
To obtain help on the following topics, request help as indicated.
o For help on query language, see the Basic_Query_Concepts help
topic.
o For help on libraries, see the Building_An_SCA_Library help
topic.
14.19 – SCAN Attributes Table
The following table lists the SCA symbol classes and their
corresponding meanings in SCAN.
SCA Symbol Classes and Equivalent SCAN Language Terminology
SCA Term SCAN Term Explanation
Argument Formal A routine or function formal
parameter parameter
Component, Leaf node A leaf node of a TREE variable
Field
Constant, Constant A CONSTANT definition
Literal
Exception N/A
File File A file used during compilation
Function, Procedure A Procedure
Procedure,
Program,
Routine,
Subroutine
Generic N/A
Keyword N/A
Label Label A statement label
Macro N/A
Module, Module A module
Package
Placeholder N/A
Psect Psect A psect name
Tag N/A
Task N/A
Type Type
Unbound N/A
Variable Variable
The following table lists the SCA occurrence classes and their
corresponding meanings in SCAN.
SCA Occurrence Classes and Equivalent SCAN Language Terminology
SCA Term SCAN Term Explanation
Primary Declaration Either a DECLARE or PROCEDURE
declaration
Associated Declaration Either a FORWARD or EXTERNAL
declaration
Declaration Declaration Either primary or associated
Read, Fetch Reference The value of a variable is
retrieved.
Write, Store Assignment A variable is assigned a value.
Address, Indirect
Pointer reference
Call Call
Command_line Command line A file specified on the command
line; for example, SCAN foo.scn.
Include Include A file included with the INCLUDE
statement
Precompiled N/A
Reference Reference Any nondeclaration
Explicit Explicit A variable or procedure explicitly
declared with DECLARE or PROCEDURE
statement
Implicit Implicit A variable declared by the compiler
on first reference, for example, a
picture variable
Visible N/A
Hidden N/A
Compilation_ Module
unit
The following table lists the SCA domain classes and their
corresponding meanings in SCAN.
SCA Domain Classes and Equivalent SCAN Language Terminology
SCA Term SCAN Term Explanation
Inheritable N/A
Global Global Declaration has GLOBAL attribute
Predefined Predefined
Multi_module Global or
predefined
Module_ Local to one module
specific
15 – Glossary
15.1 – analysis_data_file
A file produced by a compiler which contains information that
describes the source code to SCA. It may contain one or more
analysis data modules.
15.2 – analysis_data_module
A module containing all the information used by SCA for one
compilation unit.
15.3 – appearance
One of the attributes of an occurrence. It tells you whether the
name of the occurrence is visible or hidden. You can instruct SCA
to show only occurrences with a particular appearance by using the
"occurrence=" attribute selection. For example, you can ask for
hidden occurrences by specifying "occurrence=hidden."
15.4 – associated_declaration
Any declaration which is not a primary declaration. Typically,
associated declarations provide information needed by the compiler
to refer to an object.
15.5 – attribute_selection
A way of limiting a result of a query to those occurrences which
match certain characteristics. You can select the following
attributes: NAME, SYMBOL_CLASS, OCCURRENCE, DOMAIN, or FILE_SPEC
attributes. In the query language, you use phrases like name=foo,
symbol=argument, occurrence=declaration, domain=module_specific,
and file="foo.c" to specify which attributes you want. You combine
these phrases with AND, OR and NOT operators.
15.6 – attribute_selection_expression
A query question which combines one or more attribute selections
(such as name=foo, symbol=routine) using AND, OR, NOT, and XOR.
Some examples are:
name=foo and symbol=routine and occurrence=primary
name=foo_module and occurrence=compilation_unit
15.7 – call_graph
Shows what procedures and functions are called from a subroutine,
and all subsequent calls in the call graph.
15.8 – CALLED_BY
See the SCA_Topics CALLED_BY help topic.
15.9 – CALLING
See the SCA_Topics CALLING help topic.
15.10 – compilation_line_number
A line number generated by the compiler which starts at 1 for
the first file used during the compile and goes up by one for
each line read. If there is an include file, the compilation line
number is increased by one for each line in the include file. By
default, the line numbers in the query display produced by the
FIND or INSPECT commands are compilation line numbers.
15.11 – compilation_unit
A compilation unit is the smallest piece of source code that
can be separately compiled. For example, in FORTRAN, this is
a subroutine or function; in C, this is a single file. Some
languages allow you to compile more than one compilation unit
at once. Even if you compile more than one unit at a time, SCA
considers the units to be separate.
15.12 – consistency_checks
A check that INSPECT makes in which all occurrences of a symbol
are checked for consistency. For example, you can ensure that
all calls to a routine have the correct number and type of
arguments. In this type of check, each occurrence is compared
with a single occurrence selected by INSPECT to be the standard
against which all occurrences are checked. In this type of check,
each particular occurrence is either correct or incorrect.
15.13 – CONTAINED_BY
See the SCA_Topics CONTAINED_BY help topic.
15.14 – CONTAINING
See the SCA_Topics CONTAINING help topic.
15.15 – declaration
Tells the compiler about an object before the compiler uses it.
This can make the compiler create the object, or it can tell the
compiler about an object that was created elsewhere. A declaration
has a position in the source code with both a start and an end,
and can contain other declarations or references. A declaration
can be either a primary declaration or an associated declaration.
15.16 – declaration_class
Tells you what symbol class a declaration is (subroutine,
function, variable). For example, both procedures and functions
(in Pascal terms) belong to the routine symbol class, but their
declaration classes are different. The declaration class tells
the user whether a declaration is a primary declaration or
an associated declaration. SCA uses the declaration class to
decide what to display as the occurrence class in the result of a
FIND command. The user can find the declaration class using the
callable interface.
15.17 – diagnostic_error_messages
The error messages that INSPECT produces. The query result from
an INSPECT command is like that of a FIND command, but with error
messages attached to each occurrence.
15.18 – display_line
A line in the display resulting from a FIND or INSPECT command.
SCA numbers these lines if you use /DISPLAY=NUMBER. This feature
is most useful when you are saving the output in a file.
15.19 – explicit
See expression.
15.20 – expression
One of the attributes of an occurrence. The expression attribute
tells you whether the occurrence is one that you the user placed
in the source code, or is one which the compiler created for
the user. An occurrence can be either explicit or implicit.
Explicit occurrences are those placed by the user in the source
code; implicit occurrences are those created by the compiler on
behalf of the user. For example, in the following FORTRAN program,
there are three references to i which are explicit. There is one
implicit declaration of i which is created by the FORTRAN compiler
when it sees the first reference to i.
program test
i = 0
i = i + 1
end
15.21 – handle
A data type used by the SCA callable interface. If you are using
the callable interface, see the on-line SCA guide to
platform specific information for more information.
15.22 – hidden
See both appearance and hidden modules.
15.23 – hidden_modules
A module in one of the libraries in the current library list which
is also present in a library which is earlier in the library list.
The module in the earlier library is visible. The same module in
any later library is a hidden module, hidden by the first module.
15.24 – implicit
See expression.
15.25 – indicated
Uses the current cursor position for the query, when used with
a FIND or GOTO DECLARATION. If the cursor is in a query display,
SCA uses whatever occurrence on which it is positioned. If the
cursor is in a buffer, SCA uses the name on which the cursor is
positioned and the file the cursor is in to guide the query. SCA
relaxes the search criteria, if necessary, (for example, allowing
different versions of the source file) to find the indicated
occurrence.
15.26 – intersection
The operation performed by the AND operator, which indicates
that SCA will accept any occurrence that matches both X and Y
as follows:
FIND X AND Y
15.27 – library
Generic term usually referring to a physical library.
15.28 – library_list
A list of one or more physical libraries which compose the virtual
library. The order of the physical libraries is important. A
module found in one physical library in the library list hides
the same module in other physical libraries that come later in the
library list.
For example, suppose you have three libraries. Library 1 contains
module A. Library 2 contains modules A, B, and C. Library 3
contains modules C and D. SCA uses module A from Library 1,
modules B and C from library 2, and module D from library 3.
15.29 – library_number
Refers to the position of a single physical library in a library
list. This can be used with any command that refers to a library
already in the library list. For example, the command SET
NOLIBRARY 1 removes the first library from the library list, and
the command LOAD/LIBRARY=2 FOO.ANA loads the file FOO.ANA into the
second library on the library list.
15.30 – module
Represents a single compilation unit. You can list the modules
with the SHOW MODULE command. Each module shown represents a
single compilation unit - the smallest piece of source that can
be separately compiled. Even if several of these are compiled at
once (which is common in languages such as FORTRAN and BASIC),
each compilation unit appears separately.
In the query language, SYMBOL=MODULE specifies a certain type
of symbol. This is not the same as a compilation unit. You can
have modules which are not compilation units, and compilation
units which are not modules. How a module is defined varies from
language to language.
15.31 – name
A string of characters used to identify symbols in your source
code. Legal characters for a name are defined by whatever language
you use. 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.
15.32 – name_selection_expression
Selects occurrences with a particular name. For example, you can
specify the following:
FIND name=xyz
You can use wildcards in the name expression. Unlike other
atttributes, you can omit "name=" from the expression and only
specify the following:
FIND xyz
15.33 – nonstructured_relationship_expression
A relationship query (such as CONTAINED_BY, CALLED_BY, CALLING)
which requests that structure information be excluded. You can
specify RESULT=NOSTRUCTURE, RESULT=BEGIN, or RESULT=END as one
of the parameters to the relationship function. If you specify
RESULT=BEGIN or RESULT=END, this is displayed like any query
which does not have a relationship function. If you specify
RESULT=NOSTRUCTURE, this is displayed like any query which does
not have a relationship function, but has all the occurrences that
would be present if the structure were present.
15.34 – nonstructured_set
A query result that contains occurrences, but does not contain any
relationships between occurrences. These are produced by queries
that do not involve relationship functions, or queries that do
involve relationship functions but specify RESULT=NOSTRUCTURE,
RESULT=BEGIN, or RESULT=END.
15.35 – occurrence
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.
15.36 – occurrence_checks
A check that INSPECT performs on a single occurrence. For example,
INSPECT can check whether an occurrence is an implicit declaration
of a variable without having to look at any other occurrences.
15.37 – occurrence_class
One of the attributes of an occurrence that tells you what kind of
occurrence it is. The occurrence class indicates if an occurrence
is a declaration, a reference, or another class. It also indicates
what kind of declaration or reference it is. You can instruct SCA
to show you only occurrences with a particular occurrence class
using the OCCURRENCE= attribute selection. For example, you can
ask for write references using OCCURRENCE=WRITE.
15.38 – occurrence_selection_expression
The expression containing the occurrence class for each occurrence
you want to find.
15.39 – physical_library
A single directory containing an SCA database. The directory
should not contain anything else. SCA always locks an entire
physical library when it accesses it. When you are reading a
physical library (for example, with a FIND command), other users
are not allowed to write to the physical library, but other users
are allowed to read the physical library. When you are writing
to a physical library (for example, using LOAD), no other user is
allowed to read or write to the physical library.
15.40 – primary_declaration
Any declaration which affects how a particular object, such as a
routine or a variable, is implemented.
15.41 – primary_library
The first library in the library list. Commands which change the
SCA library, such as LOAD and REORGANIZE, apply to the first
library, unless you use the /LIBRARY qualifier to instruct SCA
to use another library.
15.42 – query
The question you ask SCA together with the information you receive
from SCA. The question uses the SCA query language with the FIND
or INSPECT commands. The answer is called a query result. You use
the FIND or INSPECT commands to display the query result. You can
also use the query result as part of the question for a subsequent
query.
15.43 – query_result
A query result is the information you get when you evaluate a
query, using the FIND or INSPECT commands. It consists of a set of
occurrences, and relationships between occurrences.
15.44 – reference
The use of some object in the source code. For example: X = X + 1
In this example, there are two references to the variable X. One
(to the left of the =) is a write reference; the other is a read
reference. A reference has a position in the source code, but it
is a single point and cannot contain anything.
15.45 – relationship
An association between two different occurrences. For example, the
CALLED_BY relationship in SCA associates a primary declaration of
a procedure with call references to other procedures and functions
in that procedure. A relationship has both a source and a target.
A relationship also has a relationship type. Relationships go in
both directions. For example, the CALLED_BY relationship is the
inverse of the CALLING relationship.
15.46 – relationship_type
The kind of relationship between two occurrences. For example, a
CALLED_BY relationship between a declaration of a routine FOO and
a reference to a routine BAR shows that routine FOO calls routine
BAR. The relationship types that are valid for SCA are: CALLED_BY,
CALLING, CONTAINED_BY, CONTAINING, TYPED_BY, and TYPING.
15.47 – set
The occurrences that result from each query.
15.48 – static_analysis
The analysis of a software system performed by looking at the
source code. This is in contrast to dynamic analysis, which is
analysis of the software while it is running.
SCA has some commands which do static analysis. These commands are
the INSPECT command, which does consistency checking, the REPORT
command, that can generate reports about modules, imported and
exported objects, and so forth, and some uses of the FIND command,
to generate call graphs and type graphs.
15.49 – structured_relationship_expression
A query that uses a relationship function (such as CONTAINED_
BY, CALLED_BY, or TYPED) which asks for structure information.
Structure information shows the relationships between occurrences
found as well as the occurrences found. Structure information is
provided by default.
15.50 – structured_set
A query result which has both occurrences and relationships
between occurrences. These are produced by queries which involve
relationship functions.
15.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.
15.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.
15.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".
15.54 – symbol_class_selection_expression
The expression containing the symbol class for each symbol you
want to find.
15.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.
15.56 – TYPED_BY
See the SCA_Topics TYPED_BY help topic.
15.57 – TYPING
See the SCA_Topics TYPING help topic.
15.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
15.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.
15.60 – visible
See both appearance and visible modules.
15.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.
15.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 &*.
16 – 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.
17 – 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.
18 – Language Specific Tables
For information about SCA terms and corresponding language-
specific terminology, see the tables under the Getting_Started
help topic.
19 – Libraries
19.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.
19.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.
20 – 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...])
21 – 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.
22 – 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.
23 – Reducing LOAD Time
There are different means you can use to try to decrease LOAD
time. Listed below are a few guidelines that may help you reduce
LOAD time:
o Loading an SCA library for a software system is a time
consuming operation and should be done in batch. Loading
more than one module at a time is more efficient than loading
modules separately. Using LOAD *.ANA is a common method for
loading multiple modules. You use LOAD/DELETE to clean up .ANA
files after they are loaded successfully and to use a little
less disk space during the load.
o With large software systems, it is a good idea to use more
than one SCA library and load them all simultaneously. This
can lessen the elapsed LOAD time considerably. You should be
able to load several libraries simultaneously on a single
disk. Additionally, using more than one CPU to do your loads
also helps, but SCA loading is mainly I/O intensive. For more
information about how to use multiple libraries, see the help
subtopics under Libraries.
o Once your SCA library starts getting above 20K blocks, you
should consider preallocating the library when you create it.
SCA currently extends the library file by 1000 blocks at a
time, so for large libraries it frequently extends the library.
You can preallocate an SCA library by specifying 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.
o SCA uses a large number of I/Os during LOAD. Loading an SCA
library on a heavily used or badly fragmented disk causes the
load to be less efficient.
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.
24 – Quick Reference Card
The following page contains a reference of the SCA query language. It
is intended to be printed out 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>]...|
25 – 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:
$ HELP/OUTPUT=SCA_TUTORIAL.TXT SCA SCA_Topics SCA_Tutorial
2. Print SCA_TUTORIAL.TXT from the DCL command line as follows:
$ PRINT SCA_TUTORIAL.TXT
SCA allows you to browse through a complex software system. In a
large multimodule software system, you may not be familiar with
all of the source code. It may have been written by different
authors in a number of different programming languages. SCA can
help you browse through the source code and give you important
information about the program structure. If you are familiar with
the source code, SCA will help you navigate directly to the source
code you want, and give you valuable cross-reference information.
This tutorial guides you through a sample SCA session to show how
SCA can improve your software development productivity as you work
on an unfamiliar software system.
If you encounter terms that are unfamiliar, see the SCA online
glossary for definitions. SCA's terminology for program structures
is language independent. If you want to see how this terminology
maps onto the programming language that you use most frequently,
see the language tables under the Getting_Started help topic.
This tutorial assumes that you use SCA while in LSE. You can
still follow the tutorial if you are using SCA from the command
line, but you will not be able to use the GOTO DECLARATION, GOTO
SOURCE, EXPAND, or NEXT STEP commands. The way in which results
are displayed also differ slightly between standalone SCA and SCA
used from within LSE.
Invoking SCA
To invoke SCA through LSE, type the following from the DCL command
line:
$ LSEDIT
Typing Commands
Your cursor is now in an LSE buffer.
Press the DO key or COMMAND key (PF1-KP7). This places you in LSE
command mode.
You will see the "LSE command>" prompt at the bottom of your LSE
window. This means that you can now enter an SCA command. During
this tutorial, when you see SCA commands following an LSE command>
prompt, press the DO key before you try to type the command.
Selecting a Library
SCA gets its information from an SCA library, a database of
information about your source code. You will be using the sample
SCA library provided in this tutorial.
To use the sample SCA library, type the following in LSE command
mode:
LSE command> SET LIBRARY SCA$EXAMPLE:
Later in this tutorial, you will learn how to create your own SCA
library using your own source code.
Looking at Modules
Because the components of the system are unfamiliar to you, the
first thing you may want to do is determine which modules comprise
the system loaded into the SCA library. The SHOW MODULE command
gives you a synopsis of the contents of the library.
To get information about the contents of an SCA library, type the
following command at the LSE Command> prompt:
LSE command> SHOW MODULE
For each module, you will see the module name, the language in
which the source code is written, and some other information. A
module is a logical unit of source code, as determined by your
compiler. In FORTRAN, a module may be a PROGRAM or SUBROUTINE. In
C, it may consist of the source code within one file. If you are
interested in how "module" and other SCA concepts map to different
language specific constructs, see the language tables under the
Getting_Started help topic.
Press the Return key when you are finished looking at the list of
modules.
Creating a Query
Suppose you are assigned the task of changing the output format
for this software system. Because you are unfamiliar with the
source code, you do not know where the system produces output.
Using SCA, you can find out by looking for places where the
program uses WRITELN. WRITELN is a built-in Pascal output
function, similar to PUT_LINE in Ada, or PRINTF in C.
To ask SCA to find all the occurrences of the symbol in the system
with the name WRITELN, type the following command:
LSE command> FIND WRITELN
LSE/SCA creates the following display in your buffer:
WRITELN procedure
COPY_FILE\75 call reference
COPY_FILE\84 call reference
The first line tells you about the existence of a symbol whose
name is WRITELN and whose symbol class is procedure. (A procedure
in Pascal is like a subroutine in FORTRAN, or a function in C. See
the language tables under the Getting_Started help topic.
The subsequent indented lines give you information about where
occurrences of the WRITELN symbol were found. For example, the
first occurrence or use of the WRITELN symbol is in the module
COPY_FILE on line 75, and the occurrence class (the way the symbol
was used) is a call reference.
Navigating the Query Display
Once you have a list of occurrences of the symbol, you will want
to look at the source code corresponding to those occurrences.
You will see that the first two lines of the display are
highlighted. This highlighting tells you which symbol and
occurrence are selected. When an occurrence is selected, you can
use the GOTO SOURCE command to see the corresponding source code.
Press CTRL/G or type the GOTO SOURCE command at the LSE command>
prompt. The file COPYFILE.PAS is read into a buffer by LSE, and
your cursor will be positioned on the first occurrence of WRITELN.
You may now be interested in looking at the source code for the
next occurrence.
Press CTRL/F or type the NEXT STEP command at the LSE command>
prompt. (Note that there is a corresponding CTRL/B command for
PREVIOUS STEP.)
You will see that the second occurrence of WRITELN, on line 84, is
highlighted.
Press CTRL/G again to invoke the GOTO SOURCE command.
Going to a Declaration
Your cursor is again positioned on an occurrence of WRITELN.
Looking at the source code, you see the following line:
WRITELN (out_file, SUBSTR (out_line, 1, out_index));
You might be interested in finding out where the first argument,
the variable OUT_FILE, is declared.
Press the arrow keys to position your cursor on the word OUT_FILE
in the source code. If you are using LSE with DECwindows, you can
also point to the word OUT_FILE by pointing and clicking with the
mouse.
Press CTRL/D or type the GOTO DECLARATION/PRIMARY/INDICATED
command at the LSE Command> prompt.
Your cursor will now be placed on the declaration of OUT_FILE.
Using SCA, you can navigate directly to the declaration of any
symbol declared in your system by placing your cursor on the
symbol, and pressing CTRL/D. If you are not positioned on a
symbol, you can also go to the declaration of a symbol by typing
the following command:
LSE COMMAND> GOTO DECLARATION symbol-name
Using Wildcards to Find Occurrences
Because SCA allows wildcard expressions, it can help you navigate
through the source code, even if you are not quite sure of the
name of the symbols of interest.
Suppose you know of a procedure in the system that you might use
in some new code that you are writing. In order to see how this
procedure has been used elsewhere, you want to look at the source
code for calls to the procedure, but you do not remember its name.
You may only remember that it begins with the letters BUILD. Type
the following command:
LSE command> FIND build*
You will now see the following display:
BUILDTABLE.PAS file
BUILD_TABLE\1 PASCAL command reference
BUILD_TABLE procedure
BUILD_TABLE module
SCA also gives you a message in the message buffer as follows:
5 occurrences found (3 symbols, 2 names)
You can see that two names were found: BUILDTABLE.PAS and BUILD_
TABLE. The BUILDTABLE.PAS symbol has the symbol class "file."
Two different BUILD_TABLE symbols were found. One of these is a
procedure; the other is a module.
You may notice that there are no occurrences displayed for either
the BUILD_TABLE procedure or the BUILD_TABLE module. To prevent
the display from being too cluttered, SCA/LSE displays only the
occurrences of the first symbol.
Because you are interested in seeing the occurrences of the BUILD_
TABLE procedure, you must expand the display as follows;
1. Press CTRL/F, or type the NEXT STEP command at the LSE Command>
prompt, to select the BUILD_TABLE procedure symbol.
2. Press CTRL/E, or type the EXPAND command at the LSE command>
prompt, to expand the display.
In the following display, you will see that three occurrences of
the BUILD_TABLE procedure are now visible:
BUILDTABLE.PAS file
BUILD_TABLE\1 PASCAL command reference
BUILD_TABLE procedure
BUILD_TABLE\41 PROCEDURE declaration
TRANSLIT\61 FORWARD or EXTERNAL PROCEDURE declaration
TRANSLIT\171 call reference
BUILD_TABLE module
You could now look at the corresponding source code if you
desired. Note that there is a corresponding CTRL/\ key, or
COLLAPSE command, that you can use to hide expanded occurrences.
Attribute Selection
To avoid finding more occurrences than you want, SCA lets you
select occurrences based on attributes other than just the name
of a symbol. In the previous example, you were looking for a
procedure named BUILD_TABLE. However, the results included a file
and a module, as well as the procedure you wanted.
To get results that include only the BUILD_TABLE procedure with
its corresponding occurrences, type the following query:
LSE command> FIND NAME=BUILD* AND SYMBOL_CLASS=PROCEDURE
Up to this point, you have selected only occurrences based on
the name of the symbol. The name of a symbol is only one of its
attributes. In fact, FIND BUILD_TABLE is an abbreviation for
FIND NAME=BUILD_TABLE, where "NAME=" specifies which particular
attribute we are using to select the occurrences found. FIND
BUILD_TABLE without "NAME=" works for the following reason. If
you don't specify the attribute, SCA assumes you are selecting
occurrences based on a name because this is the most commonly used
attribute.
In this new query, you have specified that you want to see only
symbols whose name is BUILD_TABLE, and whose symbol class is
PROCEDURE. (Note that the symbol class PROCEDURE is synonymous
with the classes FUNCTION, SUBROUTINE, ROUTINE, and PROGRAM.)
Symbol classes indicate the type of symbols. Examples of other
symbol classes that SCA understands are FIELD, CONSTANT, MACRO,
TASK, TYPE, and VARIABLE. For more information and a complete list
of these symbol classes, see the information under the SYMBOL_
CLASS help topic.
In the previous example, you used two selection clauses to
restrict the items found, NAME=BUILD* and SYMBOL_CLASS=PROCEDURE.
Each of these clauses resulted in a set of occurrences. You
combined the results of the two clauses by using the AND operator,
which resulted in only those occurrences that were found in both
sets of results.
The set operators available in SCA are AND, OR, NOT, and XOR. You
can use any number of set operators to combine attribute selection
clauses (such as SYMBOL_CLASS=PROCEDURE) to specify your query.
In the following display, which resulted from the previous query,
there are two declarations of the BUILD_TABLE procedure and one
call reference:
BUILD_TABLE procedure
BUILD_TABLE\41 PROCEDURE declaration
TRANSLIT\61 FORWARD or EXTERNAL PROCEDURE declaration
TRANSLIT\171 call reference
In the previous example, remember that you are interested in
seeing only call references to this procedure. You can further
restrict your query by using the OCCURRENCE= attribute, which
describes how a particular occurrence of a symbol is used. To do
this, type the query as follows:
LSE Command> FIND BUILD_TABLE AND SYMBOL_CLASS=PROCEDURE -
_LSE Command> AND OCCURRENCE=CALL
This command asks SCA to find the same results as the previous
query, but to limit the results to those occurrences that are
call references. In the resulting occurrence set, the declaration
occurrences no longer appear.
Because this is a very small example, it seems unnecessary to
continue refining these queries because you could look at the
source code for only the occurrences you want. However, if the
system were larger, and thousands of occurrences were found for
each query, it would be more important to give as detailed a query
as possible to avoid extraneous information.
The occurrence class attribute describes how an occurrence is
used. Examples of other occurrence classes that are understood
by SCA are READ, WRITE, POINTER, CALL, DECLARATION , EXPLICIT,
HIDDEN, and REFERENCE. For a complete list and description of
these occurrence classes, see the OCCURRENCE_CLASS help topic.
There are two more attributes that you can use to restrict your
queries. The first attribute, DOMAIN=, allows you to restrict the
occurrences based on the range of source code in which the symbols
might be used. Possible values for DOMAIN= are INHERITABLE,
GLOBAL, PREDEFINED, MULTI-MODULE, and MODULE_SPECIFIC.
The second attribute, FILE=, allows you to limit occurrences to
those found within a particular file, such as COPYFILE.PAS.
You could find all the global symbols (those symbols visible
throughout the program) occurring in the file COPYFILE.PAS by
entering the following query:
LSE Command> FIND DOMAIN=GLOBAL AND FILE="COPYFILE.PAS"
If you do not specify a name, as in the previous example, the
default is NAME=*.
In summary, there are five attributes that you can use to select
occurrences: NAME=, SYMBOL_CLASS=, OCCURRENCE=, FILE=, and
DOMAIN=. You can combine these selection clauses using the AND,
OR, XOR, and NOT operators. For more information, request help for
each attribute.
Relationship Functions
Up to this point, you have been navigating through source code
by asking SCA to find occurrences of interesting symbols. SCA
can also help you see the structure of your code. If you are
debugging a routine, such as READ_COMMAND_LINE, you may want to
know which system library routines might be invoked if you called
READ_COMMAND_LINE. To get this information, type the following:
LSE command> FIND CALLED_BY (READ_COMMAND_LINE)
In this example, you are invoking the CALLED_BY function and
sending it one argument, the name READ_COMMAND_LINE. The resulting
display is as follows:
READ_COMMAND_LINE procedure calls
BUILD_TABLE procedure
CLI$DCL_PARSE function
CLI$GET_VALUE function
CLI$PRESENT function
EXPAND_STRING function
IADDRESS function
LENGTH function
LIB$GET_FOREIGN function
LIB$SIGNAL procedure
ODD function
OPEN_IN procedure
OPEN_OUT procedure
SUBSTR function
The query that you just entered resulted in all the routines
called by READ_COMMAND_LINE.
However, assume you are interested in finding out only which
system library routines are called by READ_COMMAND_LINE. You
can also specify that only some of the routines called by READ_
COMMAND_LINE should be a part of the result. That is, SCA lets
you specify both the caller and the callee in the "called_by"
relationship, as in the following example:
LSE command> FIND CALLED_BY (READ_COMMAND_LINE, LIB$*)
You will then see the following results:
READ_COMMAND_LINE procedure calls
LIB$GET_FOREIGN function
LIB$SIGNAL procedure
The first argument to the CALLED_BY function specified the
caller, and the second argument specified the callee. Both
of these arguments can be general query expressions, such as
SYMBOL=ROUTINE.
You may notice that there is only one level of depth to the call
trees we have seen. That is, LIB$SIGNAL and LIB$GET_FOREIGN are
called directly by READ_COMMAND_LINE. You may be interested in
looking at a complete call tree from READ_COMMAND_LINE to LIB$
routines, including calls through intervening routines.
To specify the number of levels of the call tree you want to see,
type the following command:
LSE command> FIND CALLED_BY (READ_COMMAND_LINE, LIB$*, DEPTH=ALL)
The result is as follows:
READ_COMMAND_LINE procedure calls
BUILD_TABLE procedure calls
. LIB$SIGNAL procedure
. SIGNAL_DUPLICATE procedure calls
. LIB$SIGNAL procedure (See above)
LIB$GET_FOREIGN function
LIB$SIGNAL procedure (See above)
In the previous example, the DEPTH= argument of the CALLED_BY
relationship allowed you to specify the number of levels of the
call tree. For the DEPTH= argument, you can either specify an
integer value (the default is 1), or you can specify the keyword
ALL.
The CALLED_BY relationship is not the only function available in
SCA. As with other relationship functions, the CALLED_BY function
has an inverse, the CALLING function. To find those routines that
call READ_COMMAND_LINE, type the following query:
LSE command> FIND CALLING (READ_COMMAND_LINE, DEPTH=ALL)
The result is as follows:
TRANSLIT procedure calls
READ_COMMAND_LINE procedure calls
If you do not specify the second argument to a relationship
function, it defaults to * (which means anything). This query
translates to "find anything calling READ_COMMAND_LINE, at any
depth." You will see that there is only one call to READ_COMMAND_
LINE from the TRANSLIT procedure.
These relationship displays are like previous query displays in
that you can expand, collapse, and navigate through them.
SCA also has information about two other types of relationships.
The TYPED_BY and TYPING relationship functions are useful for
finding information about how things are typed. For example, you
can learn the following:
o FIND TYPING in_file - tells you the type of the variable in_file
o FIND TYPED_BY integer - tells you what things are of type integer
o FIND TYPING (table, depth=all) - tells you what components make
up the aggregate structure table.
SCA also understands the CONTAINED_BY and CONTAINING
relationships. These functions tell you what symbols are contained
within something else. For example, the following query tells you
all the procedures that are within the signal_duplicate procedure:
LSE Command> FIND CONTAINED_BY (SIGNAL_DUPLICATE, SYMBOL=PROCEDURE)
For more information about the relationship functions, see the
help topic for each relationship.
Because you are debugging READ_COMMAND_LINE, you might be
interested in occurrences of all the symbols contained directly
or indirectly in READ_COMMAND_LINE. You can get this information
by using the CONTAINED_BY function. However, you can use the IN
function instead, which is less general but easier to use. The
IN function lets you specify the container and the containee,
and traces the relationship through all depths (including nested
subroutines, for example).
Type the following query to see all the occurrences of symbols
used within the READ_COMMAND_LINE procedure:
LSE command> FIND IN (READ_COMMAND_LINE)
The results show that 178 occurrences of symbols were used within
the READ_COMMAND_LINE procedure.
Using Previous Queries
As you continue to use SCA, you may be interested in looking at
results from previous queries that you have issued. SCA keeps
track of all your queries, and allows you to move back and forth
between them. To see all your queries, type the following command:
LSE command> SHOW QUERY
You will see the following list:
Name Query expression Description
1 WRITELN (none)
2 BUILD* (none)
3 NAME=BUILD* AND SYMBOL_CLASS=PROCEDURE
(none)
4 BUILD_TABLE AND SYMBOL_CLASS=PROCEDURE AND OCCURRENCE=CALL
(none)
5 CALLED_BY (READ_COMMAND_LINE)
(none)
6 CALLED_BY (READ_COMMAND_LINE, LIB$*)
(none)
7 CALLED_BY (READ_COMMAND_LINE, LIB$*,DEPTH=ALL)
(none)
8 CALLING (READ_COMMAND_LINE, DEPTH=ALL)
(none)
(*) 9 IN (READ_COMMAND_LINE) (none)
You can see that there is an asterisk (*), next to query 9,
which was the last query you entered. This is called the current
query. Because query 9 is the current query, you can navigate its
display, and enter GOTO SOURCE commands for that query.
SCA also lets you set the current query with the PREVIOUS QUERY,
NEXT QUERY, and GOTO QUERY commands.
Suppose you want to look at the results of the FIND NAME=BUILD*
AND SYMBOL_CLASS=PROCEDURE query again. The name of the query
is 3. To see the results of query 3 in a query buffer, type the
following:
LSE Command> GOTO QUERY 3
It is now the current query, and you will be able to navigate it,
and see the source code corresponding to the found occurrences.
You can navigate previously entered queries and use their
results in new queries. Remember that after you entered query
3, NAME=BUILD* AND SYMBOL_CLASS=PROCEDURE, you wanted to refine
that query to see only call occurrences. You then entered a new
query as follows:
LSE Command> FIND BUILD_TABLE AND SYMBOL_CLASS=PROCEDURE -
_LSE Command> AND OCCURRENCE=CALL
You could have entered the new query by typing the following:
LSE Command> FIND @3 AND OCCURRENCE=CALL
The previous command is the same as the following query:
LSE Command> FIND NAME=BUILD* AND SYMBOL_CLASS=PROCEDURE -
_LSE Command> AND OCCURRENCE=CALL
Creating Your Own Library
Now that you have seen how to use SCA, you can create an SCA
library with information about your own source code. The following
example contains the commands for creating a library at the DCL
level. Remember that any SCA commands can also be entered from
within LSE.
In order to create your own SCA library, you must first create
a library directory for it. Using your personal directory, type
the following command to create a subdirectory for a local SCA
library:
$ CREATE/DIRECTORY [.LIB1]
Once you have a directory in which to create a library, enter the
following command to SCA to create a library:
$ SCA CREATE LIBRARY [.LIB1]
You now have an empty SCA library. To add a module to the SCA
library, you must first compile your source code.
If you have a Pascal compiler available, you can compile and load
one of the SCA example files into your new library.
First, copy the example file into your working directory by typing
the following command:
$ COPY SCA$EXAMPLE:TYPES.PAS []
Then, compile it with the /ANALYSIS_DATA qualifier. This creates
the file TYPES.ANA, which can be loaded into your SCA library. To
compile this file, use the following command:
$ PASCAL/ANALYSIS_DATA TYPES.PAS
If you do not have a Pascal compiler, try adding the /ANALYSIS_
DATA qualifier when you use any other supported compiler. For
example:
$ CC/ANALYSIS_DATA myfile.c
Once you have a .ANA file, you can load it into your SCA library
either from LSE or standalone SCA. To load the .ANA file and show
the new module, type the following commands:
SCA> LOAD myfile.ANA
SCA> SHOW MODULE
You will see that the new module has been loaded into the library,
and you will now be able to query that library.
26 – 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.
27 – 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.
28 – 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.
29 – \ (Pathname)
The path name expression allows you to identify specific symbols
based on the path of the expression. This is similar to the
debugger pathname notation. The format of this expression is as
follows:
query_expression\query_expression[\query_expression...]
Typically, you use this expression to identify a particular
variable in a routine when you may have declared a variable of the
same name in more than one routine. For example, RETURN_STATUS may
be a common variable in multiple routines. Some typical queries
are as follows:
1. FIND MYROUTINE\RETURN_STATUS
2. FIND MYMODULE\MYROUTINE\RETURN_STATUS
3. FIND MYMODULE\SYMBOL_CLASS=ROUTINE
The first query returns all occurrences of the RETURN_STATUS
variable that are declared inside MYROUTINE. The second example
returns all occurrences of the RETURN_STATUS variable which are
declared inside MYROUTINE, where MYROUTINE is declared inside
MYMODULE. The third example returns all occurrences of routines
which are declared inside MYMODULE.
You may also use the pathname when the exact path is not known.
For example, assume that you know the module name and that XYZ is
declared somewhere inside the MYMODULE, but you do not know the
exact pathname. You can then use the following query:
FIND MYMODULE\\XYZ
This query locates the XYZ variable that is declared somewhere
inside MYMODULE and returns all occurrences of XYZ.
30 – @ (Query Usage)
A query usage function incorporates the results of previous
queries into query expressions. The function has the following
form:
@( query_name )
The value of this expression is that of the expression that is
specified as query_name. The default query name is the current
query, SCA$CURRENT_QUERY.
You can see an example of its use in the following sequence of
queries:
FIND X
FIND @(SCA$CURRENT_QUERY) AND SYMBOL=ROUTINE
The advantage of using this notation is that the results of the
previous query are not reevaluated. Thus the second query will be
faster than the query:
FIND X AND SYMBOL=ROUTINE