1 SCA_Topics Help is available on the following SCA topics: 2 Advanced_Query_Examples The examples in this section use the supplied 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 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. 2 Basic_Query_Concepts This section covers some of the basic concepts underlying SCA queries. What Queries Are An SCA library is a collection of information about your source code. This includes information, such as the names and locations of all variables in your code, all the places where routines are called and what their arguments are, and many other kinds of information. Issuing a query is the process of selecting some of this information from the library. By giving a query expression with the FIND command, you specify exactly what information you want to retrieve from the library. Occurrences An occurrence is any instance of an entity in your program. An entity can be any language construct, such as a variable, a routine, or a constant. To further clarify this, consider the following code fragment (not written in a particular language): 1 MODULE myprog; 2 3 VAR i,j; 4 5 ROUTINE foo() 6 BEGIN 7 i = 5; 8 j = i; 9 END; 10 END; The code contains four entities (myprog, foo, i, j). There is one occurrence each of the module myprog, and the routine foo. The variable i, however, has three occurrences, and the variable j has two. Attribute Selection Attribute selection is a query that selects occurrences based on certain attributes. For example, you can have SCA return all occurrences in which the name attribute is XYZ. The following sections list the attributes used for selection. NAME Attribute Generally, you think of entities in you program as having only a name. In fact, the name of an entity is only one of its attributes. What you are doing when you give the basic query FIND X, is asking for all occurrences in the library that have the name attribute X. (The query FIND X is equivalent to the query FIND NAME=X. NAME= is the default attribute, so it may be omitted.) SYMBOL_CLASS Attribute The symbol class attribute describes an occurrence in terms of language constructs. In the previous example, myprog is a MODULE, foo is a ROUTINE, and i and j are variables. Thus, you could ask SCA to find things based on the symbol class only. For example, you can find all the routines in the library by giving the following query: FIND SYMBOL_CLASS=ROUTINE Note that MODULE, ROUTINE, and VARIABLE are SCA keywords for symbol classes. Because different languages use different terminology, there is a need to understand how the SCA language- independent terms relate to the language-specific terms. We have provided tables to help you match the SCA terms to the specific language constructs for all the languages that support SCA. See the Getting_Started help subtopics for specific languages. OCCURRENCE Attribute The occurrence class attribute allows you to select occurrences based on attributes specific to the occurrence. In the previous example, on line 3 the occurrence of the variable i has an occurrence class of PRIMARY. On line 7, the occurrence has an occurrence class of WRITE, and on the following line, its occurrence class is READ. To find all entities that are declared in your system, specify the following query: FIND OCCURRENCE=PRIMARY Note that as with symbol classes, there is a need to understand the relationship between the SCA occurrence class keywords and the equivalent language terminology. See the Getting_Started help subtopics for specific languages. FILE_SPEC Attribute Another attribute of all occurrences is the name of the file in which they occur. If the previous example program was in a file called MYPROG.BAR, then the following query would return all the occurrences found in the file; in this case, all occurrences of myprog, foo, i, and j: FIND FILE_SPEC="MYPROG.BAR" SYMBOL DOMAIN Attribute The domain of an entity defines the scope within the source over which the entity is known. Variables or routines, for example, may be local to a particular module, or they might be known to all modules in a system. To find all occurrences of entities that are known throught your system, specify the following query: FIND DOMAIN=GLOBAL See the Getting_Started help subtopics for specific languages. Basic Queries You have already seen examples of the most basic type of query, that is a query based on the selection of just one attribute. These examples are: FIND X FIND SYMBOL=ROUTINE FIND OCCURRENCE=PRIMARY FIND DOMAIN=GLOBAL FIND FILE_SPEC="MYPROG.BAR" Each of these queries results in a set of occurrences. Often, the result of such a query contains more information than you really want. You can explicitly indicate the result you want by specifying multiple attributes and combining them by using set operations. For example, if you only want the ROUTINES named X (rather than all items named X or all routines), specify the following query expression: FIND X AND SYMBOL=ROUTINE In the previous example, the set operator AND was used to take the intersection of the two sets. The other set operators available are OR, XOR, and NOT. In this manner, you can combine attribute selection expressions using multiple set operators. For example: FIND (X OR Y ) AND SYMBOL=ROUTINE AND OCCURRENCE=CALL This query finds all call references to routines named X or Y. Relationship Queries You have already learned how to select occurrences based on their attributes. The following section describes how to select occurrences based on their relationship with other occurrences. Calls Relationship The most common of these relationships is the calls relationship. SCA provides two functions: CALLING and CALLED_BY. With these functions, you can display the call tree structure of your program. The most basic format of the query expression is as follows: FIND CALLED_BY FOO In this example, the result shows a structured display of all the routines that FOO directly calls. You can also display routines that call FOO as follows: FIND CALLING FOO The previous two queries answer the questions, "Who is called by FOO?" and, "Who is calling FOO?" respectively. The full syntax of the relationship functions is complex, and each relationship function is described in more detail under SCA_ Topics. Without explaining why the parentheses are necessary, and emphasizing that the order of parameters is important, the following examples shows one more useful feature of relationship functions. It is possible to get a call tree of arbitrary depth by giving the following query: FIND CALLED_BY (FOO, DEPTH=ALL ) This returns a display showing not only the routines called directly by FOO, but also the routines that they in turn call, for all levels. You can replace the keyword ALL with any positive integer to limit the depth of the call tree. Contains Relationship Another relationship available through SCA is the contains relationship, which is obtained through the CONTAINING and CONTAINED_BY functions. These functions have the same syntax as the calls functions. The CONTAINED_BY function returns all entities logically contained within the given parameter. For example, the query FIND CONTAINED FOO returns two occurrences of i and one occurrence of j, in the code fragment that follows: 1 MODULE myprog; 2 3 VAR i,j; 4 5 ROUTINE foo() 6 BEGIN 7 i = 5; 8 j = i; 9 END; 10 END; Similarly, the following query returns the occurrence of the module MYPROG: FIND CONTAINING FOO Types Relationship The types relationship consists of the two functions TYPING and TYPED_BY. These functions also have the same syntax as the previous functions. The TYPED_BY function returns type trees. This is useful if there are many user-defined types in your system, particularly if they are complex record structures. The TYPING function returns the type of its argument. For more information about all the relationship functions, see the help topic for each relationship. 2 Building_An_SCA_Library To create your own SCA library, you must first create a library directory for it. Once you have a directory in which to create a library, create a library from inside SCA using the CREATE LIBRARY command. You now have an empty SCA library. To add a module to the SCA library, you must first compile your source code and generate an analysis_data (.ana) file. To load the analysis data file into your SCA library and show the new module, type the following SCA 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. 2 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( , , DEPTH={ | ALL} ) In this format, and can be any legal query expression, and 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= ], [ BEGIN= ], [ DEPTH={ | ALL} ], [ RESULT=RESULT_KEYWORD ], [ TRACE=query_expression ] ) In the previous format, and are any legal query expression, 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 LSE/SCA User Manual. 2 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( , , DEPTH={ | ALL} ) In this format, and can be any legal query expression and 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= ], [ BEGIN= ], [ DEPTH={ | ALL} ], [ RESULT=RESULT_KEYWORD ], [ TRACE=query_expression ] ) In the previous format, and are any legal query expression, 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 LSE/SCA User Manual. 2 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( , , DEPTH={ | ALL} ) In this format, and can be any legal query expression, and 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= ], [ BEGIN= ], [ DEPTH={ | ALL} ], [ RESULT=RESULT_KEYWORD ], [ TRACE=query_expression ] ) In the previous format, and is any legal query expression, 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 LSE/SCA User Manual. See also the help topic for the IN function, which is similar to the CONTAINED_BY relationship. 2 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( , , DEPTH={ | ALL} ) In this format, and can be any legal query expression, and 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= ], [ BEGIN= ], [ DEPTH={ | ALL} ], [ RESULT=RESULT_KEYWORD ], [ TRACE=query_expression ] ) In the previous format, and is any legal query expression, 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 LSE/SCA User Manual. 2 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 finds all global variables. 2 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) 2 FILE_SPEC FILE_SPEC is an attribute selection that specifies the name of the file. You identify a source file by its file name. If it contains a period (.), the file name should be enclosed in quotation marks. The format for the FILE_SPEC attribute is as follows: FILE_SPEC="filename.extension" An example using the FILE_SPEC attribute follows: FIND FILE_SPEC="MYPROG.FOR" This query finds all occurrences in the file MYPROG.FOR. 2 Getting_Started SCA works with many languages. See the subtopics in this section for information about getting started with a specific language. 3 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. 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. 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. 3 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 3 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. 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 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. 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. 3 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 3 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.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. 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. 3 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 3 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. 3 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 3 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. 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 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. 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. 3 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 2 Glossary 3 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. 3 analysis_data_module A module containing all the information used by SCA for one compilation unit. 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." 3 associated_declaration Any declaration which is not a primary declaration. Typically, associated declarations provide information needed by the compiler to refer to an object. 3 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. 3 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 3 call_graph Shows what procedures and functions are called from a subroutine, and all subsequent calls in the call graph. 3 CALLED_BY See the SCA_Topics CALLED_BY help topic. 3 CALLING See the SCA_Topics CALLING help topic. 3 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. 3 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. 3 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. 3 CONTAINED_BY See the SCA_Topics CONTAINED_BY help topic. 3 CONTAINING See the SCA_Topics CONTAINING help topic. 3 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. 3 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. 3 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. 3 explicit See expression. 3 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 3 hidden See both appearance and hidden modules. 3 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. 3 implicit See expression. 3 indicated This term is specific to using SCA with LSE. It refers to the symbol underneath the current cursor location within the editor, ie., the indicated symbol. 3 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 3 library Generic term usually referring to a physical library. 3 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. 3 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. 3 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. 3 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. Which characters are considered special characters is system dependent. See the system specific guide for further details. 3 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 3 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. 3 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. 3 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. 3 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. 3 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. 3 occurrence_selection_expression The expression containing the occurrence class for each occurrence you want to find. 3 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. 3 primary_declaration Any declaration which affects how a particular object, such as a routine or a variable, is implemented. 3 primary_library The first library in the library list. Commands which change the SCA library, such as LOAD and REORGANIZE, apply to the primary library, unless you use select a different library. 3 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. 3 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. 3 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. 3 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. 3 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. 3 set The occurrences that result from each query. 3 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, and some uses of the FIND command, to generate call graphs and type graphs. 3 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. 3 structured_set A query result which has both occurrences and relationships between occurrences. These are produced by queries which involve relationship functions. 3 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. 3 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. 3 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". 3 symbol_class_selection_expression The expression containing the symbol class for each symbol you want to find. 3 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. 3 TYPED_BY See the SCA_Topics TYPED_BY help topic. 3 TYPING See the SCA_Topics TYPING help topic. 3 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 3 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. 3 visible See both appearance and visible modules. 3 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. 3 wildcards Wildcards are used to match more than one name at once. What wildcards are available is system dependent. See the system specific guide for further details. 2 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( , ) In this format, and can be any legal query expression. The IN function returns all occurrences that match the 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 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=], [BEGIN=] ) In this format, and can be any legal query expression. 2 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. 2 Language_Specific_Tables For information about SCA terms and corresponding language- specific terminology, see the tables under the Getting_Started help topic. 2 Libraries 3 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 two different subsystems, each with its own SCA library. Each of the developers also has a personal SCA library in their personal directories. Paul, Mark and Joanna set up their SCA libraries using the SCA library command as follows: SCA> SET LIBRARY personal_lib,subsystem_1_lib,subsystem_2_lib When Paul changes a module in Subsystem 1, he compiles it and loads it into his personal library. For Paul, this hides the old version of the module in the project library for Subsystem 1, 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 the SCA library that Paul updated is not in their library list. They still see the old version of the module in the project library for Subsystem 1. Once Paul has completed his change, the nightly build updates everything for Subsystem 1, replacing the module in the project library. Now Mark and Joanna can both see the change. 3 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 can easily change the order of libraries in your virtual library list with the INSERT LIBRARY BEFORE, INSERT LIBRARY AFTER, INSERT LIBRARY FIRST, and INSERT LIBRARY LAST commands, eliminating the need to reenter a library list. Libraries may also be removed from the list with the CANCEL LIBRARY command. You can specify libraries in your library list using library numbers. For example, the command CANCEL LIBRARY 2 removes the second SCA library from the library list. 2 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. Which characters are considered special characters is system dependent. See the system specific guide for further details. You can use wildcards in the name expression. See the entry on WILDCARDS for further information. The format for NAME can be one of the following: name NAME=(name[,name...]) 2 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 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 Building_An_SCA_Library - Describes how to quickly create an SCA library. o Advanced_Query_Examples - Provides advanced examples using the supplied example library. o Glossary - Provides definitions of SCA terms. 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 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. 2 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. 2 Quick_Reference_Card ATTRIBUTE SELECTIONS: |RELATIONSHIP FUNCTIONS: | Name Class: |Short form: ---------- |----------- |CALLED_BY(,,) NAME= |CALLING(,,) NAME=(,...) | |CONTAINED_BY(,, Symbol Class: | ) ------------- |CONTAINING(,, SYMBOL= | ) SYMBOL=(,...) | |TYPED_BY(,,) Symbol Class keywords: |TYPING(,,) | Argument, Component, Constant, |Long form: Exception, File, Field, Function, |---------- Generic, Keyword, Label, Literal, |(END=, Macro, Module, Package, Placeholder, | BEGIN=, Procedure, Program, Psect, Routine, | DEPTH={ | ALL }, Subroutine, Tag ,Task, Type, Unbound, | RESULT=, Variable, Other, All, None | TRACE=) | Occurrence Class: |Result keywords: ----------------- | OCCURRENCE= |Begin, End, [No]Structure, Any_path OCCURRENCE=(,...) | |OTHER FUNCTIONS: Occurrence Class keywords: |---------- | Declaration, Primary, Associated, |IN (END=, Reference, Address, Call, | BEGIN=) Command_line, Fetch, Include, | Pointer, Precompiled, Read, Store, |EXPAND () Write, Other, All, None | |@() Domain Class: | ------------- |INDICATED() (NOTE: LSE required) DOMAIN= | DOMAIN=(,...) |NOT() | Domain Class keywords: | | Global, Inheritable, Module_specific, | Multi_module, Predefined, All, None | | File Class: | ---------- | FILE= | FILE=(,...) | | OPERATORS: | ---------- | AND, OR, XOR, Pathname (\ or \\) | | ATTRIBUTE SELECTION EXPRESSIONS: | [ ]...| 2 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. 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. LOAD -DELETE can be used 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 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. 2 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. 2 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( , , DEPTH={ | ALL} ) In this format, and can be any legal query expression, and 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= ], [ BEGIN= ], [ DEPTH={ | ALL} ], [ RESULT=RESULT_KEYWORD ], [ TRACE=query_expression ] ) In the previous format, and is any legal query expression, 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 LSE/SCA User Manual. 2 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( , , DEPTH={ | ALL} ) In this format, and can be any legal query expression, and 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= ], [ BEGIN= ], [ DEPTH={ | ALL} ], [ RESULT=RESULT_KEYWORD ], [ TRACE=query_expression ] ) In the previous format, and is any legal query expression, 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 LSE/SCA User Manual. 2 \_(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. 2 @_(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