1 SCA_Topics [SCA] 2 Advanced_Query_Examples The examples in this section use the SCA$EXAMPLE library. You are encouraged to try these queries using the example library. 1. FIND CALLED_BY( END=translit, DEPTH=ALL) This query gives the full call tree for TRANSLIT. 2. FIND CALLED_BY( END=translit, BEGIN=signal_duplicate, DEPTH=ALL) This query returns all the call paths emanating from translit that end up calling SIGNAL_DUPLICATE. 3. FIND CALLED_BY( translit, DEPTH=ALL, TRACE=(NOT OPEN*)) This query gives the full call tree for TRANSLIT, but does not show any calls from items named OPEN*. Calls to items named OPEN* appear in the call tree; however, items which are called by OPEN* do not appear. Try the query without the trace expression and compare the results when the TRACE is given. 4. FIND CALLED_BY( END=translit, BEGIN=(NOT DOMAIN=PREDEFINED and NOT lib$*), DEPTH=ALL ) This example leaves predefined functions and functions named LIB$* out of the call graph. Functions such as CHR and WRITELN in Pascal, MAX in FORTRAN, a builtin like _ADAWI in C, and so forth are predefined. These functions are defined by the language, not the programmer. 5. FIND IN( build_table and occ=comp, max_code ) This example finds all occurrences of MAX_CODE in the module BUILD_TABLE. In this case, module has the same meaning as it does in SHOW MODULE. This is the fastest way to limit a query to occurrences in a particular module. The first parameter to the IN function tells SCA in what container to look. The "and occ=comp" part of the query ensures that the BUILD_TABLE you are looking in is one of the modules displayed by SHOW MODULE, rather than something else. The second parameter to the IN function tells SCA what to look for. This is faster than specifying the following: FIND IN( build_table and occ=comp ) and max_code Both queries in this example produce the same result. Routines Used in a Module But Declared Elsewhere In this example, you find functions that are used in a given module but have their primary declaration in some other module. This example is a multistep process that makes use of previous queries. Each query in this section is numbered so that you can refer to a specific query. If you refer to a query, adjust the query name (for example, where @1 is used) to refer to the query name you have created. 1. FIND IN( translit and occurrence=compilation_unit, - symbol=function and domain=(global,inheritable) ) This query finds all occurrences of functions, either declarations or references, in the module TRANSLIT. You use "domain=(global,inheritable)" to limit the query only to occurrence in which you are interested. Only global and inheritable symbols can be imported because module-specific symbols are from the same module, and predefined symbols come from the language. Next, you have to remove any functions that have their primary declaration in the module. 2. FIND @1 AND NOT EXPAND( @1 and occurrence=primary ) This query removes any functions that have a primary declaration in the module TRANSLIT. What remains are those global or inheritable functions that do not have a primary declaration in TRANSLIT. The EXPAND function in this query can be evaluated efficiently by SCA. The parameter to EXPAND, @1 and occurrence=primary, can be evaluated by looking at the result of query 1, so SCA does not have to use the SCA library. Because the overall query does @1 AND ..., everything in the result is present in the result of query 1. All we are doing is removing occurrences. In this case, SCA can evaluate the whole query expression by looking at the result of query 1 and does not have to use the SCA library. Items Declared In a Module But Not Used Anywhere In the Module In this example, you find occurrences of functions or variables that are declared in a module but are not used in the module. This example is a multistep process that makes use of previous queries. The numbers by each query are used to refer to it later. If you refer to a query, adjust the query name (for example, where @1 is used) to refer to the query names you have created. 1. FIND IN( translit and occurrence=compilation_unit, - symbol=(function, variable) ) This query finds all occurrences of functions or variables, either declarations or references, in the module TRANSLIT. 2. FIND @1 AND NOT EXPAND( @1 and occurrence=reference ) This query removes from our first query any functions or variables that have a reference in the module TRANSLIT. What remains are those functions or variables that are not used anywhere in the module. The EXPAND function in this query can be evaluated efficiently by SCA. The parameter to EXPAND, @1 and occ=reference, can be evaluated just by looking at the result of query 1, so SCA does not have to use the SCA library. Because the overall query does @1 AND ..., everything in the result is present in the result of query 1. All we are doing is removing items. In this case, SCA can evaluate the whole query expression by looking at the result of query 1, and does not have to use the SCA library. Finding Unused Functions This example finds functions or subroutines that are never used. It provides several ways of solving the problem. Some of these are easy to understand, but can be very slow on larger SCA libraries. The more complex ones are intended to improve performance on larger SCA libraries. They do not have a significant impact on smaller libraries. The first example finds unused functions only. Note that instead of saying "occurrence=call" to find functions that are called, you specify "occurrence=reference" to find functions that are used at all. The query is as follows: FIND symbol=function AND occurrence=primary - AND NOT EXPAND( symbol=function and occurrence=reference ) On the SCA$EXAMPLE library, this query works well because it is a small library. On a larger library, it may be too slow. To evaluate this query, SCA must first evaluate "symbol=function and occurrence=primary." It must then evaluate "symbol=function and occurrence=reference" before doing any additional processing. In this case, SCA has to do twice what is essentially the same work. Also, SCA does not discard information about functions that are referenced until the end, so it uses a lot of memory. Using Previous Query Results to Find Unused Functions Faster The next example also finds unused functions. However, it uses previous query results, so the work is done only once. For this reason, it is faster than the previous example. It also uses somewhat less memory, but still not enough to make a difference on a large library. FIND symbol=function and occurrence=(primary,reference) In the previous query, we find all the occurrences that we want to use. We ignore the associated declarations at this point because they are not essential to the query. Next, we must select those functions that are not used as in the following query: FIND @1 AND occurrence=primary - AND NOT EXPAND( @1 AND occurrence=reference ) This query removes from the list of functions in our system any that are referenced, leaving only unreferenced functions. Because you are using a previous query with all the information in it, SCA does not have to access the SCA library, and performance is generally faster. However, on a large library, this may still be slow. The reason for this is that it ends up keeping a list of all the functions and all their references in memory. Using Iteration to Find Unused Functions Faster This is the most complex example. It includes some repetitive parts that the query language does not provide directly. You can do these using the callable interface, or by writing a .COM procedure, or you can do the repetitive parts manually. This is also the fastest form of the example and uses less memory. Basically, you are going to split up the work into smaller pieces to avoid having to keep everything in memory at the same time. In this example, you process one module at a time, so you need to get a list of modules first. You can do this by entering the following query: 1. FIND occurrence=compilation_unit In the next step, you have to loop through each of the occurrences found in step 1. This part cannot be done directly using the query language. You can do this using one of the following methods: o Do this manually, stepping through the occurrences in the query one by one, and using INDICATED() in the following queries where module_name is specified. o Use the /DISPLAY options to specify only the name of each occurrence found, capture the result in a file, and write a command procedure to loop over the names. In this case, you use "module_name and occurrence=compilation_unit" in the following queries where module_name is specified. o Use the callable interface. By writing a small program using the callable interface, you can do the loop relatively easily, using SCA$GET_OCCURRENCE and SCA$SELECT_OCCURRENCE. In any case, you repeat the following steps for each of the modules found in step 1. 2. FIND IN( module_name, symbol=function and occurrence=primary ) This step finds primary declarations of functions in the current module. You want only primary declarations at this stage because there may be some calls in other modules. In the next step, you find any references to those functions: 3. FIND EXPAND( @2 ) This finds everything you need. At this point, what you do is very similar to what you did for the examples in the previous section. 4. FIND @3 and occurrence=primary - AND NOT EXPAND( @3 and occurrence=reference ) This finds those functions in a particular module that are not referenced anywhere. Steps 2 through 4 must be repeated for each module. 2 Basic_Query_Concepts This section covers some of the basic concepts underlying SCA queries. You may want to have a hardcopy of this section. The directions for producing a hardcopy are as follows: 1. Place the contents of Basic_Query_Concepts in a printable file by typing the following command at the DCL command line: $ HELP/OUTPUT=BASIC_QUERY_CONCEPTS.TXT - _$ SCA SCA_Topics Basic_Query_Concepts 2. Print BASIC_QUERY_CONCEPTS.TXT from the DCL command line as follows: $ PRINT BASIC_QUERY_CONCEPTS.TXT What Queries Are An SCA library is a collection of information about your source code. This includes information, such as the names and locations of all variables in your code, all the places where routines are called and what their arguments are, and many other kinds of information. Issuing a query is the process of selecting some of this information from the library. By giving a query expression with the FIND command, you specify exactly what information you want to retrieve from the library. Occurrences An occurrence is any instance of an entity in your program. An entity can be any language construct, such as a variable, a routine, or a constant. To further clarify this, consider the following code fragment (not written in a particular language): 1 MODULE myprog; 2 3 VAR i,j; 4 5 ROUTINE foo() 6 BEGIN 7 i = 5; 8 j = i; 9 END; 10 END; The code contains four entities (myprog, foo, i, j). There is one occurrence each of the module myprog, and the routine foo. The variable i, however, has three occurrences, and the variable j has two. Attribute Selection Attribute selection is a query that selects occurrences based on certain attributes. For example, you can have SCA return all occurrences in which the name attribute is XYZ. The following sections list the attributes used for selection. NAME Attribute Generally, you think of entities in you program as having only a name. In fact, the name of an entity is only one of its attributes. What you are doing when you give the basic query FIND X, is asking for all occurrences in the library that have the name attribute X. (The query FIND X is equivalent to the query FIND NAME=X. NAME= is the default attribute, so it may be omitted.) SYMBOL_CLASS Attribute The symbol class attribute describes an occurrence in terms of language constructs. In the previous example, myprog is a MODULE, foo is a ROUTINE, and i and j are variables. Thus, you could ask SCA to find things based on the symbol class only. For example, you can find all the routines in the library by giving the following query: FIND SYMBOL_CLASS=ROUTINE Note that MODULE, ROUTINE, and VARIABLE are SCA keywords for symbol classes. Because different languages use different terminology, there is a need to understand how the SCA language- independent terms relate to the language-specific terms. We have provided tables to help you match the SCA terms to the specific language constructs for all the languages that support SCA. See the Getting_Started help subtopics for specific languages. OCCURRENCE Attribute The occurrence class attribute allows you to select occurrences based on attributes specific to the occurrence. In the previous example, on line 3 the occurrence of the variable i has an occurrence class of PRIMARY. On line 7, the occurrence has an occurrence class of WRITE, and on the following line, its occurrence class is READ. To find all entities that are declared in your system, specify the following query: FIND OCCURRENCE=PRIMARY Note that as with symbol classes, there is a need to understand the relationship between the SCA occurrence class keywords and the equivalent language terminology. See the Getting_Started help subtopics for specific languages. FILE_SPEC Attribute Another attribute of all occurrences is the name of the file in which they occur. If the previous example program was in a file called MYPROG.BAR, then the following query would return all the occurrences found in the file; in this case, all occurrences of myprog, foo, i, and j: FIND FILE_SPEC="MYPROG.BAR" SYMBOL DOMAIN Attribute The domain of an entity defines the scope within the source over which the entity is known. Variables or routines, for example, may be local to a particular module, or they might be known to all modules in a system. To find all occurrences of entities that are known throught your system, specify the following query: FIND DOMAIN=GLOBAL See the Getting_Started help subtopics for specific languages. Basic Queries You have already seen examples of the most basic type of query, that is a query based on the selection of just one attribute. These examples are: FIND X FIND SYMBOL=ROUTINE FIND OCCURRENCE=PRIMARY FIND DOMAIN=GLOBAL FIND FILE_SPEC="MYPROG.BAR" Each of these queries results in a set of occurrences. Often, the result of such a query contains more information than you really want. You can explicitly indicate the result you want by specifying multiple attributes and combining them by using set operations. For example, if you only want the ROUTINES named X (rather than all items named X or all routines), specify the following query expression: FIND X AND SYMBOL=ROUTINE In the previous example, the set operator AND was used to take the intersection of the two sets. The other set operators available are OR, XOR, and NOT. In this manner, you can combine attribute selection expressions using multiple set operators. For example: FIND (X OR Y ) AND SYMBOL=ROUTINE AND OCCURRENCE=CALL This query finds all call references to routines named X or Y. Relationship Queries You have already learned how to select occurrences based on their attributes. The following section describes how to select occurrences based on their relationship with other occurrences. Calls Relationship The most common of these relationships is the calls relationship. SCA provides two functions: CALLING and CALLED_BY. With these functions, you can display the call tree structure of your program. The most basic format of the query expression is as follows: FIND CALLED_BY FOO In this example, the result shows a structured display of all the routines that FOO directly calls. You can also display routines that call FOO as follows: FIND CALLING FOO The previous two queries answer the questions, "Who is called by FOO?" and, "Who is calling FOO?" respectively. The full syntax of the relationship functions is complex, and each relationship function is described in more detail under SCA_ Topics. Without explaining why the parentheses are necessary, and emphasizing that the order of parameters is important, the following examples shows one more useful feature of relationship functions. It is possible to get a call tree of arbitrary depth by giving the following query: FIND CALLED_BY (FOO, DEPTH=ALL ) This returns a display showing not only the routines called directly by FOO, but also the routines that they in turn call, for all levels. You can replace the keyword ALL with any positive integer to limit the depth of the call tree. Contains Relationship Another relationship available through SCA is the contains relationship, which is obtained through the CONTAINING and CONTAINED_BY functions. These functions have the same syntax as the calls functions. The CONTAINED_BY function returns all entities logically contained within the given parameter. For example, the query FIND CONTAINED FOO returns two occurrences of i and one occurrence of j, in the code fragment that follows: 1 MODULE myprog; 2 3 VAR i,j; 4 5 ROUTINE foo() 6 BEGIN 7 i = 5; 8 j = i; 9 END; 10 END; Similarly, the following query returns the occurrence of the module MYPROG: FIND CONTAINING FOO Types Relationship The types relationship consists of the two functions TYPING and TYPED_BY. These functions also have the same syntax as the previous functions. The TYPED_BY function returns type trees. This is useful if there are many user-defined types in your system, particularly if they are complex record structures. The TYPING function returns the type of its argument. For more information about all the relationship functions, see the help topic for each relationship. 2 Building_An_SCA_Library To create your own SCA library, you must first create a library directory for it. Using your personal directory, type the following command to create a subdirectory for a local SCA library: $ CREATE/DIRECTORY [.LIB1] Once you have a directory in which to create a library, enter the following command to SCA to create a library: $ SCA CREATE LIBRARY [.LIB1] You now have an empty SCA library. To add a module to the SCA library, you must first compile your source code. Add the /ANALYSIS_DATA qualifier when you use a supported compiler. For example: $ CC/ANALYSIS_DATA myfile.c This produces the file MYFILE.ANA that you can load into your SCA library either from LSE or standalone SCA. To load the .ANA file and show the new module, type the following commands: SCA> LOAD myfile.ANA SCA> SHOW MODULE You will see that the new module has been loaded into the library, and you will now be able to query that library. For more information, see the help topics for Libraries and Reducing_LOAD_Time. 2 Callable_Routines 3 SCA$ASYNCH_TERMINATE Sets a flag indicating that a CTRL-C has been issued. Format SCA$ASYNCH_TERMINATE command_context 4 Argument command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference SCA command context value. 4 Condition_Value_Returned SCA$_NORMAL Normal successful completion. 4 Description The SCA$ASYNCH_TERMINATE routine sets a flag indicating that a CTRL-C has been issued. 3 SCA$CLEANUP Shuts down the SCA callable command interface, freeing all dynamic memory associated with the interface routines and data structures. Format SCA$CLEANUP command_context 4 Argument command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context value. 4 Condition_Value_Returned SCA$_NORMAL The SCA callable command interface has been successfully shut down. 4 Description The SCA$CLEANUP routine shuts down the SCA callable command interface, freeing all dynamic memory associated with the interface routines and data structures. 3 SCA$DO_COMMAND Parses an SCA subsystem command and invokes command processing if the command is syntactically correct. Format SCA$DO_COMMAND command_context, command_string [,parameter_routine] [,continuation_routine] [,continuation_prompt] [,user_argument] [,confirm_routine] [,topic_routine] [,display_routine] 4 Arguments command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference SCA command context value. command_string type: character string access: read only mechanism: by descriptor An SCA subsystem command. parameter_routine type: procedure access: read only mechanism: by reference Routine that prompts for required parameters. You can specify LIB$GET_INPUT or a compatible routine. If a routine address of zero (0) is specified, commands with missing parameters fail and display a CLI error message. continuation_routine type: procedure access: read only mechanism: by reference Routine that prompts for the remainder of a continued command (i.e., a command that ends with a hyphen). You can specify LIB$GET_INPUT or a compatible routine. continuation_prompt type: character string access: read only mechanism: by descriptor Command continuation prompt string (e.g., SCA> ). user_argument type: longword access: read only mechanism: by reference User-specified value to be passed to any action routine (other than CLI prompt routines) called by this routine. confirm_routine type: procedure access: read only mechanism: by value Command confirmation prompt routine to be used by commands that support a /CONFIRM qualifier. You can specify SCA$GET_INPUT or a compatible routine. If this argument is omitted, the /CONFIRM qualifier is not supported. topic_routine type: procedure access: read only mechanism: by value Help topic prompt routine. You can specify LIB$GET_INPUT or a compatible routine. If this routine returns an error, command processing is terminated. If this argument is omitted, no help prompting is performed. display_routine type: procedure access: read only mechanism: by value Routine to be called to display one line of command output. You can specify SCA$PUT_OUTPUT or a compatible routine. If this routine returns an error, command processing is terminated. If this argument is omitted, no display routine is called. 4 Condition_Values_Returned All SCA condition values and many system values. 4 Description The SCA$DO_COMMAND routine parses an SCA subsystem command and invokes command processing if the command is syntactically correct. 3 SCA$GET_ATTRIBUTE Gets a handle to an attribute of an entity. Format SCA$GET_ATTRIBUTE entity, attribute_kind, attribute_handle, [,iteration_context] 4 Arguments entity type: $SCA_HANDLE access: read only mechanism: by reference An SCA entity handle describing the entity or relationship whose attributes are being obtained. attribute_kind type: $SCA_ATTRIBUTE_KIND access: read only mechanism: by reference The kind of attribute to be obtained. Any attribute-kind can be specified on this routine. attribute_handle type: $SCA_HANDLE access: write only mechanism: by reference An SCA attribute handle that is to describe the obtained attribute. iteration_context type: $SCA_ITERATION_CONTEXT access: read/write mechanism: by reference Optional. The iteration-context. This longword must contain zero on the first call to this routine for a particular iteration. This routine uses the longword to maintain the iteration context. The caller must not change the contents of the longword. 4 Condition_Values_Returned SCA$_NORMAL An attribute has been successfully returned. SCA$_NONE Warning. An attribute has not been returned. Either there are no such attributes at all in the entity or there are no more attributes. 4 Description The SCA$GET_ATTRIBUTE routine gets a handle to an attribute of an entity. If the iteration_context parameter is not specified, then this routine finds the first attribute of the specified kind (attribute_kind) and updates attribute_handle to describe that attribute. In general, several attributes can be associated with a particular entity. With this routine you can find all of those attributes by using the iteration_context parameter. 3 SCA$GET_ATTRI_KIND_T Gets an attribute kind. Format SCA$GET_ATTRI_KIND_T attribute_handle, attribute_kind 4 Arguments attribute_handle type: $SCA_HANDLE access: read only mechanism: by reference An SCA handle describing an attribute whose attribute-kind is to be obtained. attribute_kind type: character string access: write only mechanism: by descriptor The kind of the attribute. 4 Condition_Value_Returned SCA$_NORMAL An attribute kind has been successfully returned. 4 Description The SCA$GET_ATTRI_KIND_T routine returns the kind of any attribute as a character string. 3 SCA$GET_ATTRI_VALUE_T Gets an attribute value. Format SCA$GET_ATTRI_VALUE_T handle, attribute_value [,attribute_kind] 4 Arguments handle type: $SCA_HANDLE access: read/write mechanism: by reference An SCA attribute handle describing either an attribute or an entity whose value is to be obtained. attribute_value type: character string access: read/write mechanism: by descriptor The (string) value of the attribute being selected. attribute_kind type: $SCA_ATTRIBUTE_KIND access: read/write mechanism: by reference Optional. The kind of attribute to be obtained. 4 Condition_Values_Returned SCA$_NORMAL An attribute value has been successfully returned. SCA$_NONE Warning. An attibute-value has not been returned. There are no such attributes in the entity. This condition can be returned only if this routine is processing an entity. 4 Description The SCA$GET_ATTRI_VALUE_T routine returns the value of any attribute as a character string. If the handle describes an attribute, then this routine returns the value of that attribute. In this case, the attribute_kind parameter must not be specified. If the handle describes an entity, then this routine returns the value of the first attribute of that entity that is of the kind specified by the attribute_kind parameter. In this case, the attribute_kind parameter must be specified. If you want to get more than one attribute value of a particular kind for an entity, you must use the routine SCA$GET_ATTRIBUTE. This applies only to the attribute kinds SCA$K_ATTRI_NAME and SCA$K_ATTRI_ALL. The value of any kind of attribute can be returned by this routine, except for SCA$K_ATTRI_ALL. This routine will convert to character string those attributes whose data type is not character string. This routine does not accept the attribute-kind SCA$K_ATTRI_ALL as the value of the attribute_kind parameter. It is not meaningful to get just the first attribute without regard to attribute-kind. 3 SCA$GET_CURRENT_QUERY Gets the name of the current query in the given command context. Format SCA$GET_CURRENT_QUERY command_context, query_name 4 Arguments command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context. query_name type: character string access: write only mechanism: by descriptor The name of the current query in the context of the given command context. 4 Condition_Values_Returned SCA$_NORMAL The name of the current query has been successfully retrieved. 4 Description The SCA$GET_CURRENT_QUERY routine gets the name of the current query in the given command context. 3 SCA$GET_INPUT Gets one record of ASCII text from the current controlling input device specified by SYS$INPUT. Format SCA$GET_INPUT get_string, [,prompt_string] [,output_length] [,user_argument] 4 Arguments get_string type: character string access: write only mechanism: by descriptor Buffer to receive the line read from SYS$INPUT. The string is returned by a call to STR$COPY_DX. prompt_string type: character string access: read only mechanism: by descriptor Prompt message that is displayed on the controlling terminal. A valid prompt consists of text followed by a colon (:), a space, and no carriage-return/line-feed combination. The maximum size of the prompt message is 255 characters. If the controlling input device is not a terminal, this argument is ignored. output_length type: word access: write only mechanism: by reference Word to receive the actual length of the GET-STRING line, not counting any padding in the case of a fixed string. If the input line was truncated, this length reflects the truncated string. user_argument type: _UNSPECIFIED access: read only mechanism: by reference User-specified value that was passed to the routine that called this action routine. 4 Condition_Values_Returned SCA$_NORMAL An input line was returned. Failure completion code from LIB$GET_ INPUT. 4 Description The SCA$GET_INPUT routine gets one record of ASCII text from the current controlling input device specified by SYS$INPUT. 3 SCA$GET_OCCURRENCE Returns an occurrence from the query specified by the query_name argument. Format SCA$GET_OCCURRENCE command_context, query_name, occurrence 4 Arguments command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context. query_name type: character string access: read only mechanism: by descriptor The name of the query in the context of the command context. occurrence type: $SCA_HANDLE access: read/write mechanism: by reference An SCA occurrence handle that describes an occurrence. 4 Condition_Values_Returned SCA$_NORMAL An occurrence has been successfully returned. SCA$_NEWNAME An occurrence has been successfully returned. This occurrence has a different name from the occurrence that was returned by the previous call to this routine with this query context. This condition implies that this new occurrence is also of a different symbol. SCA$_NEWITEM An occurrence has been successfully returned. This new occurrence is of a different symbol from the occurrence that was returned by the previous call to this routine with this query context. SCA$_NOMORE Warning. An occurrence has not been returned. The traversal of the query result has been exhausted. 4 Description The SCA$GET_OCCURRENCE routine returns an occurrence from the query specified by the query_name argument. If the occurrence handle supplied is zero, the routine returns a handle to the first occurrence in the query represented by the argument query_name. If the occurrence handle supplied on input represents a valid occurrence, the routine returns a handle to the next occurrence in the query result. In order to be valid, the occurrence handle supplied on input must refer to an occurrence in the query represented by the argument query_name. The query name supplied is interpreted in the context of the command context identified by the argument command_context. Note that the order of retrieval of the occurrences is undefined. 3 SCA$INITIALIZE Initializes the SCA callable command interface. Format SCA$INITIALIZE command_context 4 Argument command_context type: $SCA_COMMAND_CONTEXT access: write only mechanism: by reference SCA command context value to be initialized. This value is passed as an argument to other SCA$xxx routines. 4 Condition_Value_Returned SCA$_NORMAL The SCA callable command interface has been successfully initialized. 4 Description The SCA$INITIALIZE routine initializes the SCA callable command interface. 3 SCA$LOCK_LIBRARY Locks all the physical libraries in the current virtual library list so that they cannot be modified. Format SCA$LOCK_LIBRARY command_context 4 Argument command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context. 4 Condition_Value_Returned SCA$_NORMAL The libraries have been successfully locked. 4 Description The SCA$LOCK_LIBRARY routine locks all the physical libraries in the current virtual library list so that they cannot be modified. 3 SCA$PUT_OUTPUT Writes a record to the current controlling output device specified by SYS$OUTPUT. Format SCA$PUT_OUTPUT string, user_argument 4 Arguments string type: character string access: read only mechanism: by descriptor String to be written to SYS$OUTPUT. You can concatenate one or more additional character strings with the primary string to form a single output record. You can specify a maximum of 20 strings. The maximum resulting record length is 255 characters. user_argument type: _UNSPECIFIED access: read only mechanism: by reference User-specified value that was passed to the routine that called this action routine. 4 Condition_Values_Returned SCA$_NORMAL The string was successfully written to SYS$OUTPUT. Failure completion from the RMS $PUT service. 4 Description The SCA$PUT_OUTPUT routine writes a record to the current controlling output device specified by SYS$OUTPUT. 3 SCA$QUERY_CLEANUP Cleans up an SCA query context, freeing all dynamic memory associated with the query. Format SCA$QUERY_CLEANUP query_context 4 Argument query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context to be cleaned up. 4 Condition_Value_Returned SCA$_NORMAL The query context has been successfully cleaned up. 4 Description The SCA$QUERY_CLEANUP routine cleans up an SCA query context, freeing all dynamic memory associated with the query. This routine will become obsolete in a future version of SCA. 3 SCA$QUERY_COPY Copies a query from SRC_QUERY_CONTEXT to DST_QUERY_CONTEXT. Format SCA$QUERY_COPY src_query_context, dst_query_context 4 Arguments src_query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context that describes the query to be copied. dst_query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context into which the query is to be copied. 4 Condition_Value_Returned SCA$_NORMAL The query expression has been successfully copied. 4 Description The SCA$QUERY_COPY routine copies a query from SRC_QUERY_CONTEXT to DST_QUERY_CONTEXT. This will copy whatever is in SRC_QUERY_ CONTEXT, whether that is a question, or a question and a result. This routine will become obsolete in a future version of SCA. 3 SCA$QUERY_FIND Finds the occurrences that match the query expression specified by QUERY_CONTEXT. Format SCA$QUERY_FIND query_context 4 Argument query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context that describes a query expression to be evaluated. 4 Condition_Values_Returned SCA$_NORMAL The query expression has been successfully evaluated. SCA$_NOOCCUR No occurrences match the query expression. SCA$_RESULTEXISTS The query already has a result prior to this call. 4 Description The SCA$QUERY_FIND routine finds the occurrences that match the query expression specified by QUERY_CONTEXT. This routine will become obsolete in a future version of SCA. 3 SCA$QUERY_GET_ATTRIBUTE Gets a handle to an attribute of an entity. Format SCA$QUERY_GET_ATTRIBUTE entity, attribute_kind, attribute_handle, [,iteration_context] 4 Arguments entity type: $SCA_HANDLE access: read only mechanism: by reference An SCA entity handle describing the entity or relationship whose attributes are being obtained. attribute_kind type: $SCA_ATTRIBUTE_KIND access: read only mechanism: by reference The kind of attribute to be obtained. Any attribute-kind can be specified on this routine. attribute_handle type: $SCA_HANDLE access: write only mechanism: by reference An SCA attribute handle that is to describe the obtained attribute. iteration_context type: $SCA_ITERATION_CONTEXT access: read/write mechanism: by reference Optional. The iteration-context. This longword must contain zero on the first call to this routine for a particular iteration. This routine uses the longword to maintain the iteration context. The caller must not change the contents of the longword. 4 Condition_Values_Returned SCA$_NORMAL An attribute has been successfully returned. SCA$_NONE Warning. An attribute has not been returned. Either there are no such attributes at all in the entity or there are no more attributes. 4 Description The SCA$QUERY_GET_ATTRIBUTE routine gets a handle to an attribute of an entity. If the iteration_context parameter is not specified, then this routine finds the first attribute of the specified kind (attribute_kind) and updates attribute_handle to describe that attribute. In general, several attributes can be associated with a particular entity. With this routine you can find all of those attributes by using the iteration_context parameter. This routine will become obsolete in a future version of SCA. The SCA$GET_ATTRIBUTE routine supersedes this routine. 3 SCA$QUERY_GET_ATTRI_KIND_T Gets an attribute kind. Format SCA$QUERY_GET_ATTRI_KIND_T attribute_handle, attribute_kind 4 Arguments attribute_handle type: $SCA_HANDLE access: read only mechanism: by reference An SCA handle describing an attribute whose attribute-kind is to be obtained. attribute_kind type: character string access: write only mechanism: by descriptor The kind of the attribute. 4 Condition_Value_Returned SCA$_NORMAL An attribute kind has been successfully returned. 4 Description The SCA$QUERY_GET_ATTRI_KIND_T routine returns the kind of any attribute as a character string. This routine will become obsolete in a future version of SCA. The SCA$GET_ATTRI_KIND_T routine supersedes this routine. 3 SCA$QUERY_GET_ATTRI_VALUE_T Gets an attribute value. Format SCA$QUERY_GET_ATTRI_VALUE_T handle, attribute_value [,attribute_kind] 4 Arguments handle type: $SCA_HANDLE access: read/write mechanism: by reference An SCA attribute handle describing either an attribute or an entity whose value is to be obtained. attribute_value type: character string access: read/write mechanism: by descriptor The (string) value of the attribute being selected. attribute_kind type: $SCA_ATTRIBUTE_KIND access: read/write mechanism: by reference Optional. The kind of attribute to be obtained. 4 Condition_Values_Returned SCA$_NORMAL An attribute value has been successfully returned. SCA$_NONE Warning. An attibute-value has not been returned. There are no such attributes in the entity. This condition can be returned only if this routine is processing an entity. 4 Description The SCA$QUERY_GET_ATTRI_VALUE_T routine returns the value of any attribute as a character string. If the handle describes an attribute, then this routine returns the value of that attribute. In this case, the attribute_kind parameter must not be specified. If the handle describes an entity, then this routine returns the value of the first attribute of that entity that is of the kind specified by the attribute_kind parameter. In this case, the attribute_kind parameter must be specified. If you want to get more than one attribute value of a particular kind for an entity, you must use the routine SCA$QUERY_GET_ ATTRIBUTE. This applies only to the attribute kinds SCA$K_ATTRI_ NAME and SCA$K_ATTRI_ALL. The value of any kind of attribute can be returned by this routine, except for SCA$K_ATTRI_ALL. This routine will convert to character string those attributes whose data type is not character string. This routine does not accept the attribute-kind SCA$K_ATTRI_ALL as the value of the attribute_kind parameter. It is not meaningful to get just the first attribute without regard to attribute-kind. This routine will become obsolete in a future version of SCA. The SCA$GET_ATTRI_VALUE_T routine supersedes this routine. 3 SCA$QUERY_GET_NAME Returns the name of a query. Format SCA$QUERY_GET_NAME query_context, query_name 4 Arguments query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context whose name is to be obtained. query_name type: character string access: write only mechanism: by descriptor The name of the query. 4 Condition_Value_Returned SCA$_NORMAL The query name has been successfully returned. 4 Description The SCA$QUERY_GET_NAME routine returns the name of a query. This routine will become obsolete in a future version of SCA. 3 SCA$QUERY_GET_OCCURRENCE Gets the next occurrence in the query result that is specified as a query_context argument. Format SCA$QUERY_GET_OCCURRENCE query_context, entity_handle 4 Arguments query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context whose occurrences are to be obtained. entity_handle type: $SCA_HANDLE access: read/write mechanism: by reference An SCA entity handle that describes an entity. 4 Condition_Values_Returned SCA$_NORMAL An occurrence has been successfully returned. SCA$_NEWSYMBOL An occurrence has been successfully returned. This new occurrence is of a different symbol than the occurrence that was returned by the previous call to this routine. SCA$_NOMORE Warning. An occurrence has not been returned. The traversal of the query result has been exhausted. 4 Description The SCA$QUERY_GET_OCCURRENCE routine successively returns every occurrence in a query result. It provides one pass through all of the occurrences. This routine will become obsolete in a future version of SCA. The SCA$GET_OCCURRENCE routine supersedes this routine. 3 SCA$QUERY_INITIALIZE Initializes an SCA query context. Format SCA$QUERY_INITIALIZE command_context, query_context 4 Arguments command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context. query_context type: $SCA_QUERY_CONTEXT access: write only mechanism: by reference An SCA query context to be initialized. This value is passed as an argument to other SCA query routines (SCA$QUERY_xxx). 4 Condition_Value_Returned SCA$_NORMAL The query context has been successfully initialized. 4 Description The SCA$QUERY_INITIALIZE routine initializes an SCA query context. This routine must be called before any other SCA$QUERY_ routines. This routine will become obsolete in a future version of SCA. 3 SCA$QUERY_PARSE Parses a query expression command string and sets up a query context if the command is syntactically correct. Format SCA$QUERY_PARSE query_context, query_expression_string [,query_expression_length] 4 Arguments query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context that is to describe the indicated query expression. query_expression_string type: character string access: read only mechanism: by descriptor A query expression string. query_expression_length type: longword access: write only mechanism: by reference Optional. Length of the query expression, returned from the parser. 4 Condition_Values_Returned SCA$_NORMAL The query expression string has been successfully parsed. SCA$_MORETEXT Warning. The query expression string has been successfully parsed, but the text following the query expression is not a legal part of the query expression. This condition is returned only if the query_ expression_length parameter is specified. If the query_expression_length parmeter is not specified, then this routine insists that the whole query_expression_string argument be a legal query expression; in this case all errors are signaled. 4 Description The SCA$QUERY_PARSE routine parses a query expression string and sets up a query context if the command is syntactically correct. This routine will become obsolete in a future version of SCA. 3 SCA$QUERY_SELECT_OCCURRENCE Creates a query expression that matches a specific entity. Format SCA$QUERY_SELECT_OCCURRENCE query_context, entity_handle 4 Arguments query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context that is to describe a specific entity. entity_handle type: $SCA_HANDLE access: read/write mechanism: by reference An SCA entity handle that describes the entity that the newly defined query context is to match. 4 Condition_Value_Returned SCA$_NORMAL A query expression has been successfully defined. 4 Description The SCA$QUERY_SELECT_OCCURRENCE routine creates a query expression that matches a specific entity. You use this routine to specify queries based on the results of previous queries. The entity_handle parameter is obtained by traversing the results of a previous query evaluation. Typically, the query context of the entity_handle parameter is not the same as the query_context parameter. However, they can be the same. If they are the same query context, then that previous query is replaced with the query defined by this routine and, as a result, entity_handle becomes invalid. This routine will become obsolete in a future version of SCA. The SCA$SELECT_OCCURRENCE routine supersedes this routine. 3 SCA$SELECT_OCCURRENCE Creates a query that matches a specific occurrence. Format SCA$SELECT_OCCURRENCE occurrence, query_name 4 Arguments occurrence type: $SCA_HANDLE access: read only mechanism: by reference An SCA occurrence handle which describes the occurrence that the newly created query is to match. query_name type: character string access: write only mechanism: by descriptor The name of the newly created query. This query is created in the context of the same command context as that in which the input occurrence handle is defined. 4 Condition_Values_Returned SCA$_NORMAL A query expression has been successfully defined. 4 Description You use this routine to create new queries based on the results of previous queries. The occurrence handle parameter is obtained by traversing the results of a previous query evaluation. 3 SCA$UNLOCK_LIBRARY Unlocks all the physical libraries in the current virtual library list so that they can be modified. Format SCA$UNLOCK_LIBRARY command_context 4 Argument command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context. 4 Condition_Value_Returned SCA$_NORMAL The libraries have been successfully unlocked. 4 Description The SCA$UNLOCK_LIBRARY routine unlocks all the physical libraries in the current virtual library list so that they can be modified. 2 Callable_SCA The SCA Callable Interface allows you to use SCA within independent application programs. This allows you to integrate SCA into alternative user-interfaces and lets you generate specialized reports based on SCA information. The SCA Callable Interface contains two components. The first is a set of routines termed Callable Command Routines, which comprise a high-level interface which must always be used, regardless of the type of application. This provides a very simple callable interface to SCA, which will be sufficient for most applications. Callable Command Interface Routines o SCA$ASYNCH_TERMINATE o SCA$CLEANUP o SCA$DO_COMMAND o SCA$GET_INPUT o SCA$INITIALIZE o SCA$LOCK_LIBRARY o SCA$PUT_OUTPUT o SCA$UNLOCK_LIBRARY The second component is a set of routines termed Callable Query Routines. The Callable Query Routines comprise a lower- level interface to the FIND command. Using this interface, an application has control over the specification of queries and the manipulation of query results. Callable Query Initialization/Cleanup Routines o SCA$QUERY_CLEANUP o SCA$QUERY_INITIALIZE Callable Query Question Building Routines o SCA$QUERY_PARSE o SCA$QUERY_SELECT_OCCURRENCE o SCA$SELECT_OCCURRENCE Callable Query Result Manipulation Routines o SCA$GET_ATTRIBUTE o SCA$GET_ATTRI_KIND_T o SCA$GET_ATTRI_VALUE_T o SCA$GET_OCCURRENCE o SCA$QUERY_GET_ATTRIBUTE o SCA$QUERY_GET_ATTRI_KIND_T o SCA$QUERY_GET_ATTRI_VALUE_T o SCA$QUERY_GET_OCCURRENCE Callable Query Miscellaneous Routines o SCA$GET_CURRENT_QUERY o SCA$QUERY_COPY o SCA$QUERY_FIND o SCA$QUERY_GET_NAME Message Handling The SCA callable interface handles all messages the same way: it signals them. If you want control over the display of such messages, you must establish a condition handler. Establishing a condition handler is optional. Rules for Calling SCA Routines o Most SCA routines are not AST-reentrant; therefore, you should not call an SCA routine (except SCA$ASYNCH_TERMINATE) from an AST routine that may currently be interrupting an SCA routine. o Your program must not disable ASTs. o If your program uses event flags, you must use the OpenVMS RTL routines (LIB$RESERVE_EF, LIB$GET_EF, and LIB$FREE_EF) in order to coordinate the use of event flags between your program and SCA. o Except for SCA$ASYNCH_TERMINATE, do not call SCA from within an SCA callback routine or from within a routine that is handling a condition signaled by SCA. o Your program must not unwind when handling a condition signaled by SCA. 2 Command_Categories This section lists the commands implemented by SCA. These commands can be issued from within LSE, at DCL level, or at the SCA subsystem level. See individual commands for definitions, descriptions, and examples of all SCA commands. Query Commands o DELETE QUERY o FIND o INSPECT o SHOW QUERY Navigation Commands o GOTO (DECLARATION, QUERY, SOURCE) o NEXT (OCCURRENCE, QUERY, STEP, SYMBOL) o PREVIOUS (OCCURRENCE, QUERY, STEP, SYMBOL) General Commands o EXIT o HELP o SHOW VERSION Library Commands o ANALYZE o CREATE LIBRARY o DELETE LIBRARY o DELETE MODULE o EXTRACT MODULE o LOAD o REORGANIZE o SET LIBRARY o SET NOLIBRARY o SHOW LIBRARY o SHOW MODULE o VERIFY o VERIFY/RECOVER 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. If you do not know how to create an SCA library, read the Building_An_SCA_Library help topic. The examples use generic variable names (such as 'i'). You will have to substitute variable names that exist in your code when trying the examples. The first example is the easiest query: It lets you find all the items in your SCA library named 'i', and shows you all the places where they appear (all occurrences of 'i'). FIND i You can search for any name in this manner, including using wildcard characters (for example, FIND i*). Suppose you are looking for an occurrence, and you know that it occurs in a particular file. The following query finds all occurrences of items that are named 'i' but will then limit them to those which happen to occur in the file named PROG.ADA. FIND i AND FILE_SPEC="PROG.ADA" Another typical question one might ask is, "Find all the places where this item is assigned to (or read from, called, declared, and so forth)." The next example finds all occurrences of items that are named 'i', but then limits them to only those occurrences where 'i' is assigned a value: FIND i AND OCCURRENCE=WRITE (SCA understands many occurrence classes other then WRITE. See the help subtopics under Getting_Started for tables containing all the SCA attributes and their corresponding meanings in Ada.) Often, you only want to know where (in what file or package) a particular function is, so that you can go to it and edit it. You can use the first query (where 'i' will be the name of the function) and then look through the output. The output will include all occurrences of the function, one of which would be its declaration, which you can then select. Or, you can ask SCA to limit the search for you by typing the following query: FIND i AND OCCURRENCE=PRIMARY In SCA terms, a primary declaration is the most significant declaration of an item. For an Ada function, this means the body of the function, or package, or generic, and so forth. This is in contrast to the specification, which is considered an associated declaration. Another problem you might have is that there are many different items in your system having a given name. Some may be variables; others may be functions, constants, tasks, and so forth. Suppose you want to find only the functions named i. Again, the query FIND i will give you what you want, but it will also give you much more. It is preferable to issue the following query: FIND i AND SYMBOL_CLASS=FUNCTION The previous four examples have selected information based on two attributes. The last example selected information based on a name attribute (in this case, i) and a symbol class attribute (in this case, FUNCTION). Note how the attributes are combined using the boolean operator AND. In general, you can select items out of your library based on any combination of attributes, using AND as well as the other logical operators OR, XOR, and NOT. The next example shows another primary feature of SCA - the ability to display relationships between items. This example shows the most common use of this feature. It finds the complete call tree (that is, all functions called directly and indirectly) of the function named i. FIND CALLED_BY (i, DEPTH=ALL) If you want to limit the depth of the call tree, replace the keyword ALL by any positive integer. The final part of this section describes how to go directly to the source code once you have issued a query. After issuing the query FIND i, for example, you can have an LSE query buffer containing something that looks like the following: I variable ADA_MODULE\60 object declaration ADA_MODULE\75 write reference ADA_MODULE\79 read reference ADA_MODULE\122 read reference ADA_MODULE\144 write reference ADA_MODULE\146 read, write reference ADA_MODULE\149 write reference ADA_MODULE\149 read reference ADA_MODULE\150 reference ADA_MODULE\166 read reference The first two lines of this display will be highlighted. The first line represents the item you looked for (i), and the rest of the lines represent the different places in the code where this item occurred (that is, the occurrences of i). By using the up and down arrows on your keyboard, or by clicking on an occurrence with your mouse, you can choose the occurrence you want to see. Then, all you have to do is type CTRL/G (the keyboard equivalent of the GOTO SOURCE command) and LSE will bring the source file into a buffer and position you at the occurrence you chose. To obtain help on the following topics, request help as indicated. o For help on query language, see the Basic_Query_Concepts help topic. o For help on libraries, see the Building_An_SCA_Library help topic. 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_BASIC This section contains some typical examples that illustrate what SCA can do to help you with your programs. The examples have very little explanation. If you want a more detailed explanation of the underlying concepts, see the Basic_Query_Concepts help topic. The remainder of this section is written in terms that are specific to BASIC programs. If you want to follow along and try the examples, you will need to have an SCA library available. If you do not know how to create an SCA library, read the Building_An_SCA_Library help topic. The examples use generic variable names (such as i). You will have to substitute variable names that actually exist in your code when trying the examples. The first example is the easiest query of all: It lets you find all the items in your SCA library named i, and shows you all the places where they appear (all occurrences of i). FIND i You can search for any name in this manner, including using wildcard characters (for example, FIND i*). Now let's say you are looking for an occurrence, and you know that it occurs in a particular file. The following query finds all occurrences of items that are named i but will then limit them to those which happen to occur in the file named 'PROG.BAS'. FIND i AND FILE_SPEC="PROG.BAS" Another typical question one might ask is "Find all the places where this item is assigned to (or read from, called, declared, and so forth)." The next example finds all occurrences of items that are named i, but then limits them to only those occurrences where i is assigned a value. FIND i AND OCCURRENCE=WRITE (SCA understands many occurrence classes other then WRITE. See the help subtopics under Getting_Started for tables containing all the SCA attributes and their corresponding meanings in BASIC.) Often, you only want to know where (in what file or module) a particular function is, so that you can go to it and edit it. You could use the first query (where i would be the name of the function) and then look through the output. The output would include all occurrences of the function, one of which would be its definition, which you could then select. Or, you could ask SCA to limit the search for you by typing the following query: FIND i AND OCCURRENCE=PRIMARY In SCA terms, a primary declaration is the most significant declaration of an item. For a BASIC function, this means the actual location of the function body. This is as opposed to an associated declaration, examples of which are EXTERNAL declarations, and DECLARE FUNCTION declarations. Another problem you might have is that there are many different items in your system having a given name. Some may be variables; others may be functions, constants, labels, and so forth. Suppose you want to find only the functions named i. Again, the query FIND i would give you what you wanted, but it would also give you much more. It is preferable to issue the following query: FIND i AND SYMBOL_CLASS=FUNCTION The last four examples have all selected information based on two attributes. The last example selected information based on a name attribute (in this case, i) and a symbol class attribute (in this case, FUNCTION). Note how the attributes are combined using the boolean operator AND. In general, you can select items out of your library based on any combination of attributes, using AND as well as the other logical operators OR, XOR and NOT. The next example shows another primary feature of SCA - the ability to display relationships between items. The example given here shows the most common use of this feature. It finds the complete call tree (that is, all functions called directly and indirectly), of the function named i. FIND CALLED_BY (I, DEPTH=ALL) If you want to limit the depth of the call tree, you can replace the keyword ALL by any positive integer. The final part of this section describes how to go directly to the source code once you have issued a query. After issuing the query FIND i, for example, you could have an LSE query buffer containing something that looks like the following: I variable BASIC_MODULE\60 variable declaration BASIC_MODULE\75 write reference BASIC_MODULE\79 read reference BASIC_MODULE\95 address reference BASIC_MODULE\122 read reference BASIC_MODULE\144 write reference BASIC_MODULE\146 read reference BASIC_MODULE\149 write reference BASIC_MODULE\149 read reference BASIC_MODULE\150 address reference BASIC_MODULE\166 read reference The first two lines of this display will be highlighted. The first line represents the item you looked for (I), and the rest of the lines represent the different places in the code where this item occurred (that is, the occurrences of I). By using the up and down arrows on your keyboard, or by clicking on an occurrence with your mouse, you can choose the occurrence you want to see. Then type CTRL/G (the keyboard equivalent of the GOTO SOURCE command), and LSE will bring the source file into a buffer and position you at the occurrence you chose. To obtain help on the following topics, request help as indicated. o For help on query language, see the Basic_Query_Concepts help topic. o For help on libraries, see the Building_An_SCA_Library help topic. 3 BASIC_Attributes_Table The following table lists the SCA symbol classes and their corresponding meanings in BASIC. SCA Symbol Classes and Equivalent BASIC Language Terminology SCA Term BASIC Term Explanation Argument Parameter Subprogram formal parameter Component, Record Field component Constant, Constant Literal Exception N/A File File A file used during a compilation Function, Program or For example, PROGRAM, SUB, FUNCTION, Procedure, subprogram DEF, PICTURE Program, Routine, Subroutine Generic N/A Keyword Keyword A PDF keyword Label Label A line number or statement label Macro N/A Module, N/A Package Placeholder Placeholder LSE placeholder Psect Psect MAP or COMMON block Tag Tag PDF tag Task N/A Type Type For example, word, double, decimal, and so forth Unbound N/A Variable Variable The following table lists the SCA occurrence classes and their corresponding meanings in BASIC. SCA Occurrence Classes and Equivalent BASIC Language Terminology SCA Term BASIC Term Explanation Primary Declaration For variables, where they are declared with, for example, DECLARE or MAP statements. For subprograms, where they are defined, that is, where the body of the subprogram is. Associated Declaration EXTERNAL declarations or DECLARE FUNCTION statements Declaration Declaration Either a PRIMARY or ASSOCIATED declaration Read, Fetch Read Write, Store Write Address, Address Actual parameter to LOC function Pointer reference Call Call Command_line Command line A file specified on the command line; For example, BASIC foo.bas Include Include A file specified in a %INCLUDE directive Precompiled N/A Reference Reference Any nondeclaration Explicit Explicit Any symbol declared by the user Implicit Implicit Any symbol declared by the compiler when it sees the first reference Visible Visible A symbol whose name is visible in the source Hidden Hidden A symbol not visible in the source; for example, function return values, implicit declarations Compilation_ For example, a PROGRAM, SUB, or unit FUNCTION The following table lists the SCA domain classes and their corresponding meanings in BASIC. SCA Domain Classes and Equivalent BASIC Language Terminology SCA Term BASIC Term Explanation Inheritable N/A Global Available across modules; for example, through EXTERNAL declarations Predefined Predefined Defined by the language; for example, DECIMAL, PI, CHR$, and so forth Multi_module Predefined, global, and inheritable Module_ Visible only within one module; for specific example, variables 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. If you do not know how to create an SCA library, read the Building_An_SCA_Library help topic. The examples use generic variable names (such as i). You will have to substitute variable names that actually exist in your code when trying the examples. The first example is the easiest query. It lets you find all the items in your SCA library named i, and shows you all the places where they appear (all occurrences of i): FIND i You can search for any name in this manner, including using wildcard characters (for example, FIND i*). Now suppose you are looking for an occurrence, and you know that it occurs in a particular file. The following query finds all occurrences of items that are named i, but will then limit them to those that happen to occur in the file named PROG.B32. FIND i AND FILE_SPEC="PROG.B32" Another typical question you might ask is, "Find all the places where this item is assigned to (or read from, called, declared and so forth)." The next example finds all occurrences of items that are named i, but then limits them to only those occurrences where i is assigned a value: FIND i AND OCCURRENCE=WRITE (SCA understands many occurrence classes other then WRITE. See the help subtopics under Getting_Started for tables containing all the SCA attributes and their corresponding meanings in BLISS.) Often, you only want to know where (in what file or module) a particular routine is, so that you can go to it and edit it. You can use the first query (where i will be the name of the routine) and then look through the output. The output will include all occurrences of the routine, one of which will be its declaration, which you can then select. Or, you can ask SCA to limit the search for you by typing the following query: FIND i AND OCCURRENCE=PRIMARY In SCA terms, a primary declaration is the most significant declaration of an item. For a BLISS routine, this means the place where the routine is actually implemented. This is in contrast to FORWARD or EXTERNAL declarations, which are associated declarations. Another problem you might have is that there are many different items in your system having a given name. Some may be variables; others may be routines, literals, macros, and so forth. Suppose you want to find only the routines named i. Again, the query FIND i will give you what you wanted, but it will also give you much more. It is preferable to issue the following query: FIND i AND SYMBOL_CLASS=ROUTINE The last four examples have all selected information based on two attributes. The last example selected information based on a name attribute (in this case, i) and a symbol_class attribute (in this case, ROUTINE). Note how the attributes are combined using the boolean operator AND. In general, you can select items out of your library based on any combination of attributes, using AND as well as the other logical operators OR, XOR, and NOT. The next example shows another primary feature of SCA - the ability to display relationships between items. This example shows the most common use of this feature. It finds the complete call tree (that is, all routines called directly and indirectly) of the routine named i. FIND CALLED_BY (i, DEPTH=ALL) If you want to limit the depth of the call tree, replace the keyword ALL by any positive integer. The final part of this section describes how to go directly to the source code once you have issued a query. After issuing the query FIND i, for example, you can have an LSE query buffer containing something that looks like the following: I variable BLISS_MODULE\60 LOCAL declaration BLISS_MODULE\75 write reference BLISS_MODULE\79 read reference BLISS_MODULE\122 read reference BLISS_MODULE\144 write reference BLISS_MODULE\146 read reference BLISS_MODULE\149 write reference BLISS_MODULE\149 read reference BLISS_MODULE\150 read reference BLISS_MODULE\166 read reference The first two lines of this display will be highlighted. The first line represents the item you looked for (i), and the rest of the lines represent the different places in the code where this item occurred (that is, the occurrences of i). By using the up and down arrows on your keyboard, or by clicking on an occurrence with your mouse, you can choose the occurrence you want to see. Then, type CTRL/G (the keyboard equivalent of the GOTO SOURCE command) and LSE will bring the source file into a buffer and position you at the occurrence you chose. To obtain help on the following topics, request help as indicated. o For help on query language, see the Basic_Query_Concepts help topic. o For help on libraries, see the Building_An_SCA_Library help topic. 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. If you do not know how to create an SCA library, read the Building_An_SCA_Library help topic. The examples use generic variable names (such as i). You will have to substitute variable names that actually exist in your code when trying the examples. The first example is the easiest query: It lets you find all the items in your SCA library named i, and shows you all the places where they appear (all occurrences of i). FIND i You can search for any name in this manner, including using wildcard characters (for example, FIND i*). Now let's say you are looking for an occurrence, and you know that it occurs in a particular file. The following query finds all occurrences of items that are named i but will then limit them to those which happen to occur in the file named 'PROG.C'. FIND i AND FILE_SPEC="PROG.C" Another typical question one might ask is "Find all the places where this item is assigned to (or read from, called, declared,and so forth)." The next example finds all occurrences of items that are named i, but then limits them to only those occurrences where i is assigned a value. FIND i AND OCCURRENCE=WRITE (SCA understands many occurrence classes other then WRITE. See the help subtopics under Getting_Started for tables containing all the SCA attributes and their corresponding meanings in C.) Often, you only want to know where (in what file or module) a particular function is, so that you can go to it and edit it. You could use the first query (where i would be the name of the function) and then look through the output. The output would include all occurrences of the function, one of which would be its definition, which you could then select. Or, you could ask SCA to limit the search for you by typing the following query: FIND i AND OCCURRENCE=PRIMARY In SCA terms, a primary declaration is the most significant declaration of an item. For a C function, this means the function definition. This is in contrast to a C function declaration (for example, extern i()), which in SCA terms is an associated declaration. Another problem you might have is that there are many different items in your system having a given name. Some may be variables; others may be functions, #define constants, macros, and so forth. Suppose you want to find only the functions named i. Again, the query FIND i would give you what you wanted, but it would also give you much more. It is preferable to issue the following query: FIND i AND SYMBOL_CLASS=FUNCTION The last four examples have all selected information based on two attributes. The last example selected information based on a name attribute (in this case, i) and a symbol class attribute (in this case, FUNCTION). Note how the attributes are combined using the boolean operator AND. In general, you can select items out of your library based on any combination of attributes, using AND as well as the other logical operators OR, XOR and NOT. The next example shows another primary feature of SCA - the ability to display relationships between items. The example given here shows the most common use of this feature. It finds the complete call tree (that is, all functions called directly and indirectly), of the function named i. FIND CALLED_BY (i, DEPTH=ALL) If you want to limit the depth of the call tree, you can replace the keyword ALL by any positive integer. The final part of this section describes how to go directly to the source code once you have issued a query. After issuing the query FIND i, for example, you can have an LSE query buffer containing something that looks like the following: i variable C_MODULE\60 variable definition declaration C_MODULE\75 write reference C_MODULE\79 read reference C_MODULE\95 read, write reference C_MODULE\122 read reference C_MODULE\144 write reference C_MODULE\146 read reference C_MODULE\149 write reference C_MODULE\149 read reference C_MODULE\150 read reference C_MODULE\166 read reference The first two lines of this display will be highlighted. The first line represents the item you looked for (i), and the rest of the lines represent the different places in the code where this item occurred (that is, the occurrences of i). By using the up and down arrows on your keyboard, or by clicking on an occurrence with your mouse, you can choose the occurrence you want to see. Then all you have to do is type CTRL/G (the keyboard equivalent of the GOTO SOURCE command), and LSE will bring the source file into a buffer and position you at the occurrence you chose. To obtain help on the following topics, request help as indicated. o For help on query language, see the Basic_Query_Concepts help topic. o For help on libraries, see the Building_An_SCA_Library help topic. 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_COBOL This section contains some basic examples that illustrate what SCA can do to help you with your programs. The examples have very little explanation. If you want a more detailed explanation of the underlying concepts, see the Basic_Query_Concepts help topic. The remainder of this section is written in terms that are specific to Cobol programs. If you want to follow along and try the examples, you will need to have an SCA library available. If you do not know how to create an SCA library, read the Building_An_SCA_Library help topic. The examples use generic variable names (such as i). You will have to substitute variable names that actually exist in your code when trying the examples. The first example is the easiest query: It lets you find all the items in your SCA library named i, and shows you all the places where they appear (all occurrences of i). FIND i You can search for any name in this manner, including using wildcard characters (for example, FIND i*). Now let's say you are looking for an occurrence, and you know that it occurs in a particular file. The following query finds all occurrences of items that are named i but will then limit them to those which happen to occur in the file named 'PROG.COB'. FIND i AND FILE_SPEC="PROG.COB" Another typical question one might ask is "Find all the places where this item is assigned to (or read from, called, declared, and so forth)." The next example finds all occurrences of items that are named i, but then limits them to only those occurrences where i is assigned a value. FIND i AND OCCURRENCE=WRITE (SCA understands many occurrence classes other then WRITE. See the help subtopics under Getting_Started for tables containing all the SCA attributes and their corresponding meanings in COBOL.) Often, you only want to know where (in what file ) a particular procedure is, so that you can go to it and edit it. You could use the first query (where i would be the program-id) and then look through the output. The output would include all occurrences of the program, one of which would be its definition, which you could then select. Or, you could ask SCA to limit the search for you by typing the following query: FIND i AND OCCURRENCE=PRIMARY In SCA terms, a primary declaration is the most significant declaration of an item. For a Cobol program, this is the program- id. This is in contrast to an associated declaration. Actually, in Cobol, associated declarations do not have much meaning. The compiler creates implicit associated declarations for a program the first time it is called. Another problem you might have is that there are many different items in your system having a given name. Some may be variables; others may be programs, paragraph names, files, and so forth. Suppose you want to find only the programs named i. Again, the query FIND i would give you what you wanted, but it would also give you much more. It is preferable to issue the following query: FIND i AND SYMBOL_CLASS=PROGRAM The last four examples have all selected information based on two attributes. The last example selected information based on a name attribute (in this case, i) and a symbol class attribute (in this case, PROGRAM). Note how the attributes are combined using the boolean operator AND. In general, you can select items out of your library based on any combination of attributes, using AND as well as the other logical operators OR, XOR and NOT. The next example shows another primary feature of SCA - the ability to display relationships between items. The example given here shows the most common use of this feature. It finds the complete call tree (that is, all programs called directly and indirectly), of the program named i. FIND CALLED_BY (I, DEPTH=ALL) If you want to limit the depth of the call tree, you can replace the keyword ALL by any positive integer. The final part of this section describes how to go directly to the source code once you have issued a query. After issuing the query FIND i, for example, you can have an LSE query buffer containing something that looks like the following: I variable COBOL_MODULE\60 data declaration COBOL_MODULE\75 write reference COBOL_MODULE\79 read reference COBOL_MODULE\122 read reference COBOL_MODULE\144 write reference COBOL_MODULE\146 read reference COBOL_MODULE\149 read reference COBOL_MODULE\166 read reference The first two lines of this display will be highlighted. The first line represents the item you looked for (I), and the rest of the lines represent the different places in the code where this item occurred (that is, the occurrences of I). By using the up and down arrows on your keyboard, or by clicking on an occurrence with your mouse, you can choose the occurrence you want to see. Then all you have to do is type CTRL/G (the keyboard equivalent of the GOTO SOURCE command), and LSE will bring the source file into a buffer and position you at the occurrence you chose. To obtain help on the following topics, request help as indicated. o For help on query language, see the Basic_Query_Concepts help topic. o For help on libraries, see the Building_An_SCA_Library help topic. 3 COBOL_Attributes_Table The following table lists the SCA symbol classes and their corresponding meanings in COBOL. SCA Symbol Classes and Equivalent COBOL Language Terminology SCA Term COBOL Term Explanation Argument Program argument Component, Group item Field Constant, A character string whose value is Literal specified by the ordered set of characters it contains, or a reserve word that is a figurative constant; for example, "1.234E7", ZERO Exception N/A File File A file used during the compilation Function, Program A program Procedure, Program, Routine, Subroutine Generic N/A Keyword Keyword A PDF keyword Label Paragraph- name or section-name Macro N/A Module, N/A Package Placeholder Placeholder An LSE placeholder Psect PSECT Tag Tag A PDF tag Task N/A Type Datatype Unbound Symbols in conditional compilation lines Variable Data item The following table lists the SCA occurrence classes and their corresponding meanings in COBOL. SCA Occurrence Classes and Equivalent COBOL Language Terminology SCA Term COBOL Term Explanation Primary Declaration Data declarations, program ids Associated Implicit declarations of called programs the first time they are seen Declaration Declaration Both primary and associated declarations Read, Fetch FETCH Write, Store STORE Address, N/A Pointer Call CALL Command_line A file specified on the command line, for example, COBOL foo.cob Include COPY Precompiled N/A Reference Reference Any nondeclaration Explicit A variable declared by the user Implicit A variable automatically defined by the compiler Visible Not hidden Hidden Hidden occurrences may be due to default conditions (for example, PIC 9(4) is given the DISPLAY TYPE) or within complex statement (for example, COMPUTE and hidden write references). Compilation_ SCP unit separately compiled unit The following table lists the SCA domain classes and their corresponding meanings in COBOL. SCA Domain Classes and Equivalent COBOL Language Terminology SCA Term COBOL Term Explanation Inheritable N/A Global EXTERNAL Predefined PREDEFINED For example, special registers Multi_module Global and predefined Module_ Not multi-module specific 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. If you do not know how to create an SCA library, read the Building_An_SCA_Library help topic. The examples use generic variable names (such as i). You will have to substitute variable names that actually exist in your code when trying the examples. The first example is the easiest query: It lets you find all the items in your SCA library named i, and shows you all the places where they appear (all occurrences of i). FIND i characters (for example, FIND i*). Now let's say you are looking for an occurrence, and you know that it occurs in a particular file. The following query finds all occurrences of items that are named i but will then limit them to those which happen to occur in the file named 'PROG.FOR'. FIND i AND FILE_SPEC="PROG.FOR" Another typical question one might ask is "Find all the places where this item is assigned to (or read from, called, declared, and so forth)." The next example finds all occurrences of items that are named i, but then limits them to only those occurrences where i is assigned a value. FIND i AND OCCURRENCE=WRITE (SCA understands many occurrence classes other then WRITE. See the help subtopics under Getting_Started for tables containing all the SCA attributes and their corresponding meanings in FORTRAN.) Often, you only want to know where (in what file or module) a particular subroutine is, so that you can go to it and edit it. You could use the first query (where i would be the name of the subroutine) and then look through the output. The output would include all occurrences of the subroutine, one of which would be its definition, which you could then select. Or, you could ask SCA to limit the search for you by typing the following query: FIND i AND OCCURRENCE=PRIMARY In SCA terms, a primary declaration is the most significant declaration of an item. For a FORTRAN subroutine, this is where the actual SUBROUTINE statement is. This is in contrast to a FORTRAN EXTERNAL declaration, which in SCA terms is an associated declaration. The FORTRAN compiler also creates implicit associated declarations for any undeclared functions. Another problem you might have is that there are many different items in your system having a given name. Some may be variables; others may be subroutines, PARAMETER constants, and so forth. Suppose you want to find only the subroutines named i. Again, the query FIND i would give you what you wanted, but it would also give you much more. It is preferable to issue the following query: FIND i AND SYMBOL_CLASS=SUBROUTINE The last four examples have all selected information based on two attributes. The last example selected information based on a name attribute (in this case, i) and a symbol class attribute (in this case, SUBROUTINE). Note how the attributes are combined using the boolean operator AND. In general, you can select items out of your library based on any combination of attributes, using AND as well as the other logical operators OR, XOR and NOT. The next example shows another primary feature of SCA - the ability to display relationships between items. The example given here shows the most common use of this feature. It finds the complete call tree (that is, all subroutines called directly and indirectly), of the subroutine named i. FIND CALLED_BY (I, DEPTH=ALL) If you want to limit the depth of the call tree, you can replace the keyword ALL by any positive integer. The final part of this section describes how to go directly to the source code once you have issued a query. After issuing the query FIND i, for example, you can have an LSE query buffer containing something that looks like the following: I variable FORTRAN_MODULE\60 variable declaration FORTRAN_MODULE\75 write reference FORTRAN_MODULE\79 read reference FORTRAN_MODULE\95 address reference FORTRAN_MODULE\122 read reference FORTRAN_MODULE\144 write reference FORTRAN_MODULE\146 read reference FORTRAN_MODULE\149 write reference FORTRAN_MODULE\149 read reference FORTRAN_MODULE\150 address reference FORTRAN_MODULE\166 read reference The first two lines of this display will be highlighted. The first line represents the item you looked for (I), and the rest of the lines represent the different places in the code where this item occurred (that is, the occurrences of I). By using the up and down arrows on your keyboard, or by clicking on an occurrence with your mouse, you can choose the occurrence you want to see. Then all you have to do is type CTRL/G (the keyboard equivalent of the GOTO SOURCE command), and LSE will bring the source file into a buffer and position you at the occurrence you chose. To obtain help on the following topics, request help as indicated. o For help on query language, see the Basic_Query_Concepts help topic. o For help on libraries, see the Building_An_SCA_Library help topic. 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 3 Using_Pascal This section contains some basic examples that illustrate what SCA can do to help you with your programs. The examples have very little explanation. If you want a more detailed explanation of the underlying concepts, see the Basic_Query_Concepts help topic. The remainder of this section is written in terms that are specific to Pascal programs. If you want to follow along and try the examples, you will need to have an SCA library available. The SCA$EXAMPLE library provided with SCA is based on Pascal, so you could use it. If you want to use your own library, but do not know how to create an SCA library, read the Building_An_SCA_Library help topic. The examples in this section use variables from the SCA$EXAMPLE library. If you use your own library, you will have to substitute variable names that actually exist in your code when trying the examples. The first example is the easiest query: It lets you find all the items in your SCA library named i, and shows you all the places where they appear (all occurrences of i). FIND i You can search for any name in this manner, including using wildcard characters (for example, FIND i*). Now let's say you are looking for an occurrence, and you know that it occurs in a particular file. The following query finds all occurrences of items that are named i but will then limit them to those which happen to occur in the file named 'BUILDTABLE.PAS'. FIND i AND FILE_SPEC="BUILDTABLE.PAS" Another typical question one might ask is "Find all the places where this item is assigned to (or read from, called, declared, and so forth)." The next example finds all occurrences of items that are named c, but then limits them to only those occurrences where c is assigned a value. FIND c AND OCCURRENCE=WRITE (SCA understands many occurrence classes other then WRITE. See the help subtopics under Getting_Started for tables containing all the SCA attributes and their corresponding meanings in Pascal.) Often, you only want to know where (in what file or module) a particular procedure is, so that you can go to it and edit it. You could use a query similar to the first (where i would be replaced by the name of the procedure) and then look through the output. The output would include all occurrences of the procedure, one of which would be its declaration, which you could then select. Or, you could ask SCA to limit the search for you by typing the following query: FIND build_table AND OCCURRENCE=PRIMARY In SCA terms, a primary declaration is the most significant declaration of an item. For a Pascal procedure, this means the place where the procedure is actually implemented. This is in contrast to FORWARD or EXTERNAL declarations, which are associated declarations. Another problem you might have is that there are many different items in your system having a given name. Some may be variables; others may be functions, constants, labels, and so forth. Suppose you want to find only the procedures named 'build_table'. Again, the query FIND build_table would give you what you wanted, but it would also give you much more. It is preferable to issue the following query: FIND build_table AND SYMBOL_CLASS=PROCEDURE The last four examples have all selected information based on two attributes. The last example selected information based on a name attribute (in this case, 'build_table') and a symbol class attribute (in this case, PROCEDURE). Note how the attributes are combined using the boolean operator AND. In general, you can select items out of your library based on any combination of attributes, using AND as well as the other logical operators OR, XOR and NOT. The next example shows another primary feature of SCA - the ability to display relationships between items. The example given here shows the most common use of this feature. It finds the complete call tree (that is, all procedures called directly and indirectly), of the procedure named 'build_table'. FIND CALLED_BY (build_table, DEPTH=ALL) If you want to limit the depth of the call tree, you can replace the keyword ALL by any positive integer. The final part of this section describes how to go directly to the source code once you have issued a query. After issuing the query FIND c, for example, you can have an LSE query buffer containing something that looks like the following: C variable EXPAND_STRING\60 VAR (variable) declaration EXPAND_STRING\75 write reference EXPAND_STRING\79 read reference EXPAND_STRING\95 read reference EXPAND_STRING\122 read reference EXPAND_STRING\144 write reference EXPAND_STRING\146 read reference EXPAND_STRING\149 write reference EXPAND_STRING\149 read reference EXPAND_STRING\150 read reference EXPAND_STRING\166 read reference The first two lines of this display will be highlighted. The first line represents the item you looked for (c), and the rest of the lines represent the different places in the code where this item occurred (that is, the occurrences of c). By using the up and down arrows on your keyboard, or by clicking on an occurrence with your mouse, you can choose the occurrence you want to see. Then all you have to do is type CTRL/G (the keyboard equivalent of the GOTO SOURCE command), and LSE will bring the source file into a buffer and position you at the occurrence you chose. To obtain help on the following topics, request help as indicated. o For help on query language, see the Basic_Query_Concepts help topic. o For help on libraries, see the Building_An_SCA_Library help topic. 3 Pascal_Attributes_Table The following table lists the SCA symbol classes and their corresponding meanings in Pascal. SCA Symbol Classes and Equivalent Pascal Language Terminology SCA Term Pascal Term Explanation Argument Formal parameter Component, Component, Components of array types, VARYING, Field String STRING; fields of records Constant, Constant CONSTants, predefined constants, Literal enumerated type constants Exception N/A File File A file used during compilation Function, Function, Procedure, procedure Program, Routine, Subroutine Generic N/A Keyword Keyword A PDF keyword Label Label Label declarations and uses Macro N/A Module, Program, Package module Placeholder Placeholder An LSE placeholder Psect Psect PSECT and COMMON attributes Tag Tag A PDF tag Task N/A Type Type For example, pointer, array, enumerated, subrange types Unbound N/A Variable Variable The following table lists the SCA occurrence classes and their corresponding meanings in Pascal. SCA Occurrence Classes and Equivalent Pascal Language Terminology SCA Term Pascal Term Explanation Primary Declaration For example, PROCEDURE XYZ; Associated FORWARD and For example, EXTERNAL PROCEDURE XYZ; EXTERNAL; declarations Declaration Declaration Both primary and associated declarations Read, Fetch Read Write, Store Write Address, Address Pointer Call Call Command_line Command line A file specified on the command line, for example, PASCAL foo.pas Include Include A file specified in an INCLUDE statement Precompiled Environment A file specified in an INHERIT clause Reference Reference Any nondeclaration Explicit Pascal has no implicit occurrences. Everything is explicit. Implicit N/A Visible Appears in the source Hidden Does not appear in the source, for example, VAR I : INTEGER VALUE 10 has a hidden write reference. Compilation_ Module, unit Program The following table lists the SCA domain classes and their corresponding meanings in Pascal. SCA Domain Classes and Equivalent Pascal Language Terminology SCA Term Pascal Term Explanation Inheritable Inherited or Items in an environment file and inheritable items inherited from an environment file Global GLOBAL Items declared with the GLOBAL attribute Predefined Predeclared For example, INTEGER, TRUE, WRITELN Multi_module Inheritable, Global, Predefined Module_ Items local to a compilation unit, specific and not in an environment file 3 EPascal_Attributes_Table The following table lists the SCA symbol classes and their corresponding meanings in EPascal. SCA Symbol Classes and Equivalent EPascal Language Terminology SCA Term EPascal Term Explanation Argument Formal parameter Component, Component, Components of array types, VARYING, Field String STRING; fields of records Constant, Constant CONSTants, predefined constants, Literal enumerated type constants Exception INTERRUPT_SERVICE Interrupt Service routine File File A file used during compilation Function, Function, Procedure, procedure Routine, Subroutine Generic N/A Keyword N/A Label Label Label declarations and uses Macro N/A Module, Program, Package module Placeholder N/A Program PROGRAM Psect Psect PSECT and COMMON attributes Tag N/A Task PROCESS_BLOCK Type Type For example, pointer, array, enumerated, subrange types Unbound Flexible type Variable Variable The following table lists the SCA occurrence classes and their corresponding meanings in EPascal. SCA Occurrence Classes and Equivalent EPascal Language Terminology SCA Term EPascal Term Explanation Primary Declaration For example, PROCEDURE XYZ; Associated FORWARD and For example, EXTERNAL PROCEDURE XYZ; EXTERNAL; declarations Declaration Declaration Both primary and associated declarations Read, Fetch Read Write, Store Write Address, Address Pointer Call Call Command_line Command line A file specified on the command line, for example, EPASCAL foo.pas Include %Include A file specified in a %INCLUDE statement Precompiled Include A file specified in an INCLUDE statement Reference Reference Any nondeclaration Explicit EPascal has no implicit occurrences. Everything is explicit. Implicit N/A Visible Appears in the source Hidden Does not appear in the source, for example, VAR I : INTEGER VALUE 10 has a hidden write reference. Compilation_ Module, unit Program The following table lists the SCA domain classes and their corresponding meanings in EPascal. SCA Domain Classes and Equivalent EPascal Language Terminology SCA Term EPascal Term Explanation Inheritable INCLUDEd Items in a precompiled file. Global GLOBAL Items declared with the GLOBAL attribute Predefined Predeclared For example, INTEGER, TRUE, WRITELN Multi_module Inheritable, Global, Predefined Module_ Items local to a compilation unit, specific and not in a precompiled file. 3 Using_SCAN This section contains some basic examples that illustrate what SCA can do to help you with your programs. The examples have very little explanation. If you want a more detailed explanation of the underlying concepts, see the Basic_Query_Concepts help topic. The remainder of this section is written in terms that are specific to SCAN programs. If you want to follow along and try the examples, you will need to have an SCA library available. If you do not know how to create an SCA library, read the Building_An_SCA_Library help topic. The examples use generic variable names (such as i). You will have to substitute variable names that actually exist in your code when trying the examples. The first example is the easiest query: It lets you find all the items in your SCA library named i, and shows you all the places where they appear (all occurrences of i). FIND i You can search for any name in this manner, including using wildcard characters (for example, FIND i*). Now let's say you are looking for an occurrence, and you know that it occurs in a particular file. The following query finds all occurrences of items that are named i but will then limit them to those which happen to occur in the file named 'PROG.SCN'. FIND i AND FILE_SPEC="PROG.SCN" Another typical question one might ask is "Find all the places where this item is assigned to (or read from, called, declared, and so forth)." The next example finds all occurrences of items that are named i, but then limits them to only those occurrences where i is assigned a value. FIND i AND OCCURRENCE=WRITE (SCA understands many occurrence classes other then WRITE. See the help subtopics under Getting_Started for tables containing all the SCA attributes and their corresponding meanings in SCAN.) Often, you only want to know where (in what file or module) a particular procedure is, so that you can go to it and edit it. You could use the first query (where i would be the name of the procedure) and then look through the output. The output would include all occurrences of the procedure, one of which would be its declaration, which you could then select. Or, you could ask SCA to limit the search for you by typing the following query: FIND i AND OCCURRENCE=PRIMARY In SCA terms, a primary declaration is the most significant declaration of an item. For a SCAN procedure, this means the place where the procedure is actually implemented, that is, the PROCEDURE declaration. This is in contrast to FORWARD or EXTERNAL declarations, which are associated declarations Another problem you might have is that there are many different items in your system having a given name. Some may be variables; others may be procedures, constants, labels, and so forth. Suppose you want to find only the procedures named i. Again, the query FIND i would give you what you wanted, but it would also give you much more. It is preferable to issue the following query: FIND i AND SYMBOL_CLASS=PROCEDURE The last four examples have all selected information based on two attributes. The last example selected information based on a name attribute (in this case, i) and a symbol class attribute (in this case, PROCEDURE). Note how the attributes are combined using the boolean operator AND. In general, you can select items out of your library based on any combination of attributes, using AND as well as the other logical operators OR, XOR and NOT. The next example shows another primary feature of SCA - the ability to display relationships between items. The example given here shows the most common use of this feature. It finds the complete call tree (that is, all procedures called directly and indirectly), of the procedure named i. FIND CALLED_BY (i, DEPTH=ALL) If you want to limit the depth of the call tree, you can replace the keyword ALL by any positive integer. The final part of this section describes how to go directly to the source code once you have issued a query. After issuing the query FIND i, for example, you can have an LSE query buffer containing something that looks like the following: I variable SCAN_MODULE\60 variable declaration SCAN_MODULE\75 write reference SCAN_MODULE\79 read reference SCAN_MODULE\122 read reference SCAN_MODULE\144 write reference SCAN_MODULE\146 read reference SCAN_MODULE\149 write reference SCAN_MODULE\149 read reference SCAN_MODULE\150 read reference SCAN_MODULE\166 read reference The first two lines of this display will be highlighted. The first line represents the item you looked for (i), and the rest of the lines represent the different places in the code where this item occurred (that is, the occurrences of i). By using the up and down arrows on your keyboard, or by clicking on an occurrence with your mouse, you can choose the occurrence you want to see. Then all you have to do is type CTRL/G (the keyboard equivalent of the GOTO SOURCE command), and LSE will bring the source file into a buffer and position you at the occurrence you chose. To obtain help on the following topics, request help as indicated. o For help on query language, see the Basic_Query_Concepts help topic. o For help on libraries, see the Building_An_SCA_Library help topic. 3 SCAN_Attributes_Table The following table lists the SCA symbol classes and their corresponding meanings in SCAN. SCA Symbol Classes and Equivalent SCAN Language Terminology SCA Term SCAN Term Explanation Argument Formal A routine or function formal parameter parameter Component, Leaf node A leaf node of a TREE variable Field Constant, Constant A CONSTANT definition Literal Exception N/A File File A file used during compilation Function, Procedure A Procedure Procedure, Program, Routine, Subroutine Generic N/A Keyword N/A Label Label A statement label Macro N/A Module, Module A module Package Placeholder N/A Psect Psect A psect name Tag N/A Task N/A Type Type Unbound N/A Variable Variable The following table lists the SCA occurrence classes and their corresponding meanings in SCAN. SCA Occurrence Classes and Equivalent SCAN Language Terminology SCA Term SCAN Term Explanation Primary Declaration Either a DECLARE or PROCEDURE declaration Associated Declaration Either a FORWARD or EXTERNAL declaration Declaration Declaration Either primary or associated Read, Fetch Reference The value of a variable is retrieved. Write, Store Assignment A variable is assigned a value. Address, Indirect Pointer reference Call Call Command_line Command line A file specified on the command line; for example, SCAN foo.scn. Include Include A file included with the INCLUDE statement Precompiled N/A Reference Reference Any nondeclaration Explicit Explicit A variable or procedure explicitly declared with DECLARE or PROCEDURE statement Implicit Implicit A variable declared by the compiler on first reference, for example, a picture variable Visible N/A Hidden N/A Compilation_ Module unit The following table lists the SCA domain classes and their corresponding meanings in SCAN. SCA Domain Classes and Equivalent SCAN Language Terminology SCA Term SCAN Term Explanation Inheritable N/A Global Global Declaration has GLOBAL attribute Predefined Predefined Multi_module Global or predefined Module_ Local to one module specific 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 display_line A line in the display resulting from a FIND or INSPECT command. SCA numbers these lines if you use /DISPLAY=NUMBER. This feature is most useful when you are saving the output in a file. 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 handle A data type used by the SCA callable interface. If you are using the callable interface, see the on-line SCA guide to platform specific information for more information. 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 Uses the current cursor position for the query, when used with a FIND or GOTO DECLARATION. If the cursor is in a query display, SCA uses whatever occurrence on which it is positioned. If the cursor is in a buffer, SCA uses the name on which the cursor is positioned and the file the cursor is in to guide the query. SCA relaxes the search criteria, if necessary, (for example, allowing different versions of the source file) to find the indicated occurrence. 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, and the command LOAD/LIBRARY=2 FOO.ANA loads the file FOO.ANA into the second library on 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. You do not need to quote the following: $, _, *, %, &, -, alphanumeric characters. 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 first library, unless you use the /LIBRARY qualifier to instruct SCA to use another 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, the REPORT command, that can generate reports about modules, imported and exported objects, and so forth, and some uses of the FIND command, to generate call graphs and type graphs. 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. There are two wildcards in SCA: the asterisk (*) and percent (%). For example, in the name expression A*, the wildcard * will match any number of characters, so this would match A, AB, ABC, AXYZ, and so forth. The * wildcard matches any number of characters, and % wildcard matches just one character. If you do not want SCA to use * or % as a wildcard, you use an ampersand (&) to quote it. For example, to find the single name *, you would use &*. 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 five different subsystems. Each subsystem has its own SCA library in the following directories: DISK1:[PROJECT.SUBSYSTEM1.SCA] DISK1:[PROJECT.SUBSYSTEM2.SCA] DISK1:[PROJECT.SUBSYSTEM3.SCA] DISK2:[PROJECT.SUBSYSTEM4.SCA] DISK2:[PROJECT.SUBSYSTEM5.SCA] Each of the developers also has a personal SCA library as follows: DISK1:[PAUL.SCA] DISK2:[MARK.SCA] DISK1:[JOANNA.SCA] Paul uses the following command to set up his SCA libraries: LSE Command> SET LIBRARY disk1:[paul.sca], - _LSE Command> disk1:[project.subsystem1.sca], - _LSE Command> disk1:[project.subsystem2.sca], - _LSE Command> disk1:[project.subsystem3.sca], - _LSE Command> disk2:[project.subsystem4.sca], - _LSE Command> disk2:[project.subsystem5.sca] Mark and Joanna use the same command, but the first library in the list is their own SCA library. When Paul changes a module in Subsystem 1, he compiles it and loads it into his personal library in DISK1:[PAUL.SCA]. For Paul, this hides the old version of the module in DISK1:[PROJECT.SUBSYSTEM1.SCA], so his SCA library is up to date and consistent with his changes. Mark and Joanna do not see Paul's changes in their SCA libraries because they are not using the SCA library (DISK1:[PAUL.SCA]) that Paul updated. They still see the old version of the module in DISK1:[PROJECT.SUBSYSTEM1.SCA]. Once Paul has completed his change, the nightly build updates everything for Subsystem 1, replacing the module in DISK1:[PROJECT.SUBSYSTEM1.SCA]. Now Mark and Joanna can both see the change. 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 use the SET LIBRARY and SET NOLIBRARY commands to maintain your virtual library list. You can use the /BEFORE and /AFTER qualifiers to insert and remove libraries without having to reenter a library list. You can specify libraries in your library list using library numbers. For example, the command SET NOLIBRARY 2 removes the second SCA library from the library list. 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 tightly integrated with the Language-Sensitive Editor for OpenVMS (LSE). When SCA is used with LSE, you can interactively edit, compile, debug, navigate, and analyze source code during a single development session. For more information, see the following topics: o Basic_Query_Concepts - Describes some of the basic concepts underlying SCA queries. o Getting_Started - Provides subtopics with information about getting started with specific languages. o SCA_Tutorial - Provides a sample session that allows you to get started after completing the session. o Building_An_SCA_Library - Describes how to quickly create an SCA library. o Advanced_Query_Examples - Provides advanced examples using the SCA$EXAMPLE library. o Glossary - Provides definitions of SCA terms. o Command_Categories - Lists the different types of SCA commands. o Callable_Routines - Provides a complete description of each SCA callable routine. o Callable_SCA - Provides guidelines for using the SCA callable interface. o Libraries - Provides subtopics with information about project libraries and virtual libraries. o Reducing_LOAD_Time - Provides guidelines for reducing your LOAD time. o Quick_Reference_Card - Provides a pointer to the release notes, which contain a quick reference card for the SCA query language. Under SCA_Topics, there is help information for specific keywords. These keywords include attributes, relationships, and functions. For example, you can request help on SCA_Topics SYMBOL_CLASS to get information about the SYMBOL_CLASS attribute. 2 Reducing_LOAD_Time Loading an SCA library is a time-consuming operation. Here are suggestions for reducing LOAD time: o Virtual I/O Cache facility SCA uses a large number of I/Os during LOAD. Disk caching can greatly reduce the number of I/Os, and improve performance. Your system manager can enable disk caching by setting the VBN_CACHE_S SYSGEN parameter. Use SHOW MEMORY/CACHE to see whether disk caching is enabled. o Batch loads Loading more than one module at a time is more efficient than loading modules separately. For example, use LOAD *.ANA. o Multiple libraries With large software systems, it is a good idea to use more than one SCA library and load them all simultaneously. This can decrease the elapsed LOAD time considerably, especially if the libraries are on separate disks. Using more than one CPU also helps, but not as dramatically, because SCA loading is mainly I/O intensive. For more information about how to use multiple libraries, see the help subtopics under Libraries. o Choice of Disk SCA uses a large number of I/Os during LOAD. Loading an SCA library on a slow, heavily used, or badly fragmented disk causes the load to be less efficient. o File Fragmentation and File Preallocation If your SCA library is larger than 20K blocks, you should consider preallocating the library when you create it. SCA extends the library file by 1000 blocks at a time, so for large libraries it extends the library many times, and this may cause your SCA library to be badly fragmented. Preallocate an SCA library with CREATE LIBRARY/SIZE=xxx, where xxx is the size of the library in disk blocks. Use the size of the SCA$EVENT.DAT file in your current SCA library directory as the value to the /SIZE qualifier. You can tell how badly your SCA libraries are fragmented by using the following command: $ DUMP/HEADER/BLOCK=COUNT=0 - _$ DISK:[sca_library_directory]SCA$EVENT.DAT The interesting portion of the output is the Map area. Each retrieval pointer represents a contiguous section on the disk. Because SCA extends SCA libraries 1000 blocks at a time, having a lot of retrieval pointers smaller than this is a strong indication that some defragmentation is needed. o Using less disk space Use LOAD/DELETE to delete .ANA files after they are successfully loaded. This doesn't reduce LOAD time, but uses less disk space. 2 Quick_Reference_Card The following page contains a reference of the SCA query language. It is intended to be printed and used as a Quick Reference Card. ATTRIBUTE SELECTIONS: |RELATIONSHIP FUNCTIONS: | Name Class: |Short form: ---------- |----------- |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 SCA_Tutorial This tutorial is for character cell LSE and SCA on the OpenVMS platform. For a tutorial on the DECwindows interface, please see the DECset Guide to Source Code Analyzer. If you do not have DECwindows, you may want to have a hardcopy of this tutorial to follow it along interactively. The directions for producing a hardcopy are as follows: 1. Place the contents of SCA_Tutorial in a printable file by typing the following command on the DCL command line: $ HELP/OUTPUT=SCA_TUTORIAL.TXT SCA SCA_Topics SCA_Tutorial 2. Print SCA_TUTORIAL.TXT from the DCL command line as follows: $ PRINT SCA_TUTORIAL.TXT SCA allows you to browse through a complex software system. In a large multimodule software system, you may not be familiar with all of the source code. It may have been written by different authors in a number of different programming languages. SCA can help you browse through the source code and give you important information about the program structure. If you are familiar with the source code, SCA will help you navigate directly to the source code you want, and give you valuable cross-reference information. This tutorial guides you through a sample SCA session to show how SCA can improve your software development productivity as you work on an unfamiliar software system. If you encounter terms that are unfamiliar, see the SCA online glossary for definitions. SCA's terminology for program structures is language independent. If you want to see how this terminology maps onto the programming language that you use most frequently, see the language tables under the Getting_Started help topic. This tutorial assumes that you use SCA while in LSE. You can still follow the tutorial if you are using SCA from the command line, but you will not be able to use the GOTO DECLARATION, GOTO SOURCE, EXPAND, or NEXT STEP commands. The way in which results are displayed also differ slightly between standalone SCA and SCA used from within LSE. Invoking SCA To invoke SCA through LSE, type the following from the DCL command line: $ LSEDIT Typing Commands Your cursor is now in an LSE buffer. Press the DO key or COMMAND key (PF1-KP7). This places you in LSE command mode. You will see the "LSE command>" prompt at the bottom of your LSE window. This means that you can now enter an SCA command. During this tutorial, when you see SCA commands following an LSE command> prompt, press the DO key before you try to type the command. Selecting a Library SCA gets its information from an SCA library, a database of information about your source code. You will be using the sample SCA library provided in this tutorial. To use the sample SCA library, type the following in LSE command mode: LSE command> SET LIBRARY SCA$EXAMPLE: Later in this tutorial, you will learn how to create your own SCA library using your own source code. Looking at Modules Because the components of the system are unfamiliar to you, the first thing you may want to do is determine which modules comprise the system loaded into the SCA library. The SHOW MODULE command gives you a synopsis of the contents of the library. To get information about the contents of an SCA library, type the following command at the LSE Command> prompt: LSE command> SHOW MODULE For each module, you will see the module name, the language in which the source code is written, and some other information. A module is a logical unit of source code, as determined by your compiler. In FORTRAN, a module may be a PROGRAM or SUBROUTINE. In C, it may consist of the source code within one file. If you are interested in how "module" and other SCA concepts map to different language specific constructs, see the language tables under the Getting_Started help topic. Press the Return key when you are finished looking at the list of modules. Creating a Query Suppose you are assigned the task of changing the output format for this software system. Because you are unfamiliar with the source code, you do not know where the system produces output. Using SCA, you can find out by looking for places where the program uses WRITELN. WRITELN is a built-in Pascal output function, similar to PUT_LINE in Ada, or PRINTF in C. To ask SCA to find all the occurrences of the symbol in the system with the name WRITELN, type the following command: LSE command> FIND WRITELN LSE/SCA creates the following display in your buffer: WRITELN procedure COPY_FILE\75 call reference COPY_FILE\84 call reference The first line tells you about the existence of a symbol whose name is WRITELN and whose symbol class is procedure. (A procedure in Pascal is like a subroutine in FORTRAN, or a function in C. See the language tables under the Getting_Started help topic. The subsequent indented lines give you information about where occurrences of the WRITELN symbol were found. For example, the first occurrence or use of the WRITELN symbol is in the module COPY_FILE on line 75, and the occurrence class (the way the symbol was used) is a call reference. Navigating the Query Display Once you have a list of occurrences of the symbol, you will want to look at the source code corresponding to those occurrences. You will see that the first two lines of the display are highlighted. This highlighting tells you which symbol and occurrence are selected. When an occurrence is selected, you can use the GOTO SOURCE command to see the corresponding source code. Press CTRL/G or type the GOTO SOURCE command at the LSE command> prompt. The file COPYFILE.PAS is read into a buffer by LSE, and your cursor will be positioned on the first occurrence of WRITELN. You may now be interested in looking at the source code for the next occurrence. Press CTRL/F or type the NEXT STEP command at the LSE command> prompt. (Note that there is a corresponding CTRL/B command for PREVIOUS STEP.) You will see that the second occurrence of WRITELN, on line 84, is highlighted. Press CTRL/G again to invoke the GOTO SOURCE command. Going to a Declaration Your cursor is again positioned on an occurrence of WRITELN. Looking at the source code, you see the following line: WRITELN (out_file, SUBSTR (out_line, 1, out_index)); You might be interested in finding out where the first argument, the variable OUT_FILE, is declared. Press the arrow keys to position your cursor on the word OUT_FILE in the source code. If you are using LSE with DECwindows, you can also point to the word OUT_FILE by pointing and clicking with the mouse. Press CTRL/D or type the GOTO DECLARATION/PRIMARY/INDICATED command at the LSE Command> prompt. Your cursor will now be placed on the declaration of OUT_FILE. Using SCA, you can navigate directly to the declaration of any symbol declared in your system by placing your cursor on the symbol, and pressing CTRL/D. If you are not positioned on a symbol, you can also go to the declaration of a symbol by typing the following command: LSE COMMAND> GOTO DECLARATION symbol-name Using Wildcards to Find Occurrences Because SCA allows wildcard expressions, it can help you navigate through the source code, even if you are not quite sure of the name of the symbols of interest. Suppose you know of a procedure in the system that you might use in some new code that you are writing. In order to see how this procedure has been used elsewhere, you want to look at the source code for calls to the procedure, but you do not remember its name. You may only remember that it begins with the letters BUILD. Type the following command: LSE command> FIND build* You will now see the following display: BUILDTABLE.PAS file BUILD_TABLE\1 PASCAL command reference BUILD_TABLE procedure BUILD_TABLE module SCA also gives you a message in the message buffer as follows: 5 occurrences found (3 symbols, 2 names) You can see that two names were found: BUILDTABLE.PAS and BUILD_ TABLE. The BUILDTABLE.PAS symbol has the symbol class "file." Two different BUILD_TABLE symbols were found. One of these is a procedure; the other is a module. You may notice that there are no occurrences displayed for either the BUILD_TABLE procedure or the BUILD_TABLE module. To prevent the display from being too cluttered, SCA/LSE displays only the occurrences of the first symbol. Because you are interested in seeing the occurrences of the BUILD_ TABLE procedure, you must expand the display as follows; 1. Press CTRL/F, or type the NEXT STEP command at the LSE Command> prompt, to select the BUILD_TABLE procedure symbol. 2. Press CTRL/E, or type the EXPAND command at the LSE command> prompt, to expand the display. In the following display, you will see that three occurrences of the BUILD_TABLE procedure are now visible: BUILDTABLE.PAS file BUILD_TABLE\1 PASCAL command reference BUILD_TABLE procedure BUILD_TABLE\41 PROCEDURE declaration TRANSLIT\61 FORWARD or EXTERNAL PROCEDURE declaration TRANSLIT\171 call reference BUILD_TABLE module You could now look at the corresponding source code if you desired. Note that there is a corresponding CTRL/\ key, or COLLAPSE command, that you can use to hide expanded occurrences. Attribute Selection To avoid finding more occurrences than you want, SCA lets you select occurrences based on attributes other than just the name of a symbol. In the previous example, you were looking for a procedure named BUILD_TABLE. However, the results included a file and a module, as well as the procedure you wanted. To get results that include only the BUILD_TABLE procedure with its corresponding occurrences, type the following query: LSE command> FIND NAME=BUILD* AND SYMBOL_CLASS=PROCEDURE Up to this point, you have selected only occurrences based on the name of the symbol. The name of a symbol is only one of its attributes. In fact, FIND BUILD_TABLE is an abbreviation for FIND NAME=BUILD_TABLE, where "NAME=" specifies which particular attribute we are using to select the occurrences found. FIND BUILD_TABLE without "NAME=" works for the following reason. If you don't specify the attribute, SCA assumes you are selecting occurrences based on a name because this is the most commonly used attribute. In this new query, you have specified that you want to see only symbols whose name is BUILD_TABLE, and whose symbol class is PROCEDURE. (Note that the symbol class PROCEDURE is synonymous with the classes FUNCTION, SUBROUTINE, ROUTINE, and PROGRAM.) Symbol classes indicate the type of symbols. Examples of other symbol classes that SCA understands are FIELD, CONSTANT, MACRO, TASK, TYPE, and VARIABLE. For more information and a complete list of these symbol classes, see the information under the SYMBOL_ CLASS help topic. In the previous example, you used two selection clauses to restrict the items found, NAME=BUILD* and SYMBOL_CLASS=PROCEDURE. Each of these clauses resulted in a set of occurrences. You combined the results of the two clauses by using the AND operator, which resulted in only those occurrences that were found in both sets of results. The set operators available in SCA are AND, OR, NOT, and XOR. You can use any number of set operators to combine attribute selection clauses (such as SYMBOL_CLASS=PROCEDURE) to specify your query. In the following display, which resulted from the previous query, there are two declarations of the BUILD_TABLE procedure and one call reference: BUILD_TABLE procedure BUILD_TABLE\41 PROCEDURE declaration TRANSLIT\61 FORWARD or EXTERNAL PROCEDURE declaration TRANSLIT\171 call reference In the previous example, remember that you are interested in seeing only call references to this procedure. You can further restrict your query by using the OCCURRENCE= attribute, which describes how a particular occurrence of a symbol is used. To do this, type the query as follows: LSE Command> FIND BUILD_TABLE AND SYMBOL_CLASS=PROCEDURE - _LSE Command> AND OCCURRENCE=CALL This command asks SCA to find the same results as the previous query, but to limit the results to those occurrences that are call references. In the resulting occurrence set, the declaration occurrences no longer appear. Because this is a very small example, it seems unnecessary to continue refining these queries because you could look at the source code for only the occurrences you want. However, if the system were larger, and thousands of occurrences were found for each query, it would be more important to give as detailed a query as possible to avoid extraneous information. The occurrence class attribute describes how an occurrence is used. Examples of other occurrence classes that are understood by SCA are READ, WRITE, POINTER, CALL, DECLARATION , EXPLICIT, HIDDEN, and REFERENCE. For a complete list and description of these occurrence classes, see the OCCURRENCE_CLASS help topic. There are two more attributes that you can use to restrict your queries. The first attribute, DOMAIN=, allows you to restrict the occurrences based on the range of source code in which the symbols might be used. Possible values for DOMAIN= are INHERITABLE, GLOBAL, PREDEFINED, MULTI-MODULE, and MODULE_SPECIFIC. The second attribute, FILE=, allows you to limit occurrences to those found within a particular file, such as COPYFILE.PAS. You could find all the global symbols (those symbols visible throughout the program) occurring in the file COPYFILE.PAS by entering the following query: LSE Command> FIND DOMAIN=GLOBAL AND FILE="COPYFILE.PAS" If you do not specify a name, as in the previous example, the default is NAME=*. In summary, there are five attributes that you can use to select occurrences: NAME=, SYMBOL_CLASS=, OCCURRENCE=, FILE=, and DOMAIN=. You can combine these selection clauses using the AND, OR, XOR, and NOT operators. For more information, request help for each attribute. Relationship Functions Up to this point, you have been navigating through source code by asking SCA to find occurrences of interesting symbols. SCA can also help you see the structure of your code. If you are debugging a routine, such as READ_COMMAND_LINE, you may want to know which system library routines might be invoked if you called READ_COMMAND_LINE. To get this information, type the following: LSE command> FIND CALLED_BY (READ_COMMAND_LINE) In this example, you are invoking the CALLED_BY function and sending it one argument, the name READ_COMMAND_LINE. The resulting display is as follows: READ_COMMAND_LINE procedure calls BUILD_TABLE procedure CLI$DCL_PARSE function CLI$GET_VALUE function CLI$PRESENT function EXPAND_STRING function IADDRESS function LENGTH function LIB$GET_FOREIGN function LIB$SIGNAL procedure ODD function OPEN_IN procedure OPEN_OUT procedure SUBSTR function The query that you just entered resulted in all the routines called by READ_COMMAND_LINE. However, assume you are interested in finding out only which system library routines are called by READ_COMMAND_LINE. You can also specify that only some of the routines called by READ_ COMMAND_LINE should be a part of the result. That is, SCA lets you specify both the caller and the callee in the "called_by" relationship, as in the following example: LSE command> FIND CALLED_BY (READ_COMMAND_LINE, LIB$*) You will then see the following results: READ_COMMAND_LINE procedure calls LIB$GET_FOREIGN function LIB$SIGNAL procedure The first argument to the CALLED_BY function specified the caller, and the second argument specified the callee. Both of these arguments can be general query expressions, such as SYMBOL=ROUTINE. You may notice that there is only one level of depth to the call trees we have seen. That is, LIB$SIGNAL and LIB$GET_FOREIGN are called directly by READ_COMMAND_LINE. You may be interested in looking at a complete call tree from READ_COMMAND_LINE to LIB$ routines, including calls through intervening routines. To specify the number of levels of the call tree you want to see, type the following command: LSE command> FIND CALLED_BY (READ_COMMAND_LINE, LIB$*, DEPTH=ALL) The result is as follows: READ_COMMAND_LINE procedure calls BUILD_TABLE procedure calls . LIB$SIGNAL procedure . SIGNAL_DUPLICATE procedure calls . LIB$SIGNAL procedure (See above) LIB$GET_FOREIGN function LIB$SIGNAL procedure (See above) In the previous example, the DEPTH= argument of the CALLED_BY relationship allowed you to specify the number of levels of the call tree. For the DEPTH= argument, you can either specify an integer value (the default is 1), or you can specify the keyword ALL. The CALLED_BY relationship is not the only function available in SCA. As with other relationship functions, the CALLED_BY function has an inverse, the CALLING function. To find those routines that call READ_COMMAND_LINE, type the following query: LSE command> FIND CALLING (READ_COMMAND_LINE, DEPTH=ALL) The result is as follows: TRANSLIT procedure calls READ_COMMAND_LINE procedure calls If you do not specify the second argument to a relationship function, it defaults to * (which means anything). This query translates to "find anything calling READ_COMMAND_LINE, at any depth." You will see that there is only one call to READ_COMMAND_ LINE from the TRANSLIT procedure. These relationship displays are like previous query displays in that you can expand, collapse, and navigate through them. SCA also has information about two other types of relationships. The TYPED_BY and TYPING relationship functions are useful for finding information about how things are typed. For example, you can learn the following: o FIND TYPING in_file - tells you the type of the variable in_file o FIND TYPED_BY integer - tells you what things are of type integer o FIND TYPING (table, depth=all) - tells you what components make up the aggregate structure table. SCA also understands the CONTAINED_BY and CONTAINING relationships. These functions tell you what symbols are contained within something else. For example, the following query tells you all the procedures that are within the signal_duplicate procedure: LSE Command> FIND CONTAINED_BY (SIGNAL_DUPLICATE, SYMBOL=PROCEDURE) For more information about the relationship functions, see the help topic for each relationship. Because you are debugging READ_COMMAND_LINE, you might be interested in occurrences of all the symbols contained directly or indirectly in READ_COMMAND_LINE. You can get this information by using the CONTAINED_BY function. However, you can use the IN function instead, which is less general but easier to use. The IN function lets you specify the container and the containee, and traces the relationship through all depths (including nested subroutines, for example). Type the following query to see all the occurrences of symbols used within the READ_COMMAND_LINE procedure: LSE command> FIND IN (READ_COMMAND_LINE) The results show that 178 occurrences of symbols were used within the READ_COMMAND_LINE procedure. Using Previous Queries As you continue to use SCA, you may be interested in looking at results from previous queries that you have issued. SCA keeps track of all your queries, and allows you to move back and forth between them. To see all your queries, type the following command: LSE command> SHOW QUERY You will see the following list: Name Query expression Description 1 WRITELN (none) 2 BUILD* (none) 3 NAME=BUILD* AND SYMBOL_CLASS=PROCEDURE (none) 4 BUILD_TABLE AND SYMBOL_CLASS=PROCEDURE AND OCCURRENCE=CALL (none) 5 CALLED_BY (READ_COMMAND_LINE) (none) 6 CALLED_BY (READ_COMMAND_LINE, LIB$*) (none) 7 CALLED_BY (READ_COMMAND_LINE, LIB$*,DEPTH=ALL) (none) 8 CALLING (READ_COMMAND_LINE, DEPTH=ALL) (none) (*) 9 IN (READ_COMMAND_LINE) (none) You can see that there is an asterisk (*), next to query 9, which was the last query you entered. This is called the current query. Because query 9 is the current query, you can navigate its display, and enter GOTO SOURCE commands for that query. SCA also lets you set the current query with the PREVIOUS QUERY, NEXT QUERY, and GOTO QUERY commands. Suppose you want to look at the results of the FIND NAME=BUILD* AND SYMBOL_CLASS=PROCEDURE query again. The name of the query is 3. To see the results of query 3 in a query buffer, type the following: LSE Command> GOTO QUERY 3 It is now the current query, and you will be able to navigate it, and see the source code corresponding to the found occurrences. You can navigate previously entered queries and use their results in new queries. Remember that after you entered query 3, NAME=BUILD* AND SYMBOL_CLASS=PROCEDURE, you wanted to refine that query to see only call occurrences. You then entered a new query as follows: LSE Command> FIND BUILD_TABLE AND SYMBOL_CLASS=PROCEDURE - _LSE Command> AND OCCURRENCE=CALL You could have entered the new query by typing the following: LSE Command> FIND @3 AND OCCURRENCE=CALL The previous command is the same as the following query: LSE Command> FIND NAME=BUILD* AND SYMBOL_CLASS=PROCEDURE - _LSE Command> AND OCCURRENCE=CALL Creating Your Own Library Now that you have seen how to use SCA, you can create an SCA library with information about your own source code. The following example contains the commands for creating a library at the DCL level. Remember that any SCA commands can also be entered from within LSE. In order to create your own SCA library, you must first create a library directory for it. Using your personal directory, type the following command to create a subdirectory for a local SCA library: $ CREATE/DIRECTORY [.LIB1] Once you have a directory in which to create a library, enter the following command to SCA to create a library: $ SCA CREATE LIBRARY [.LIB1] You now have an empty SCA library. To add a module to the SCA library, you must first compile your source code. If you have a Pascal compiler available, you can compile and load one of the SCA example files into your new library. First, copy the example file into your working directory by typing the following command: $ COPY SCA$EXAMPLE:TYPES.PAS [] Then, compile it with the /ANALYSIS_DATA qualifier. This creates the file TYPES.ANA, which can be loaded into your SCA library. To compile this file, use the following command: $ PASCAL/ANALYSIS_DATA TYPES.PAS If you do not have a Pascal compiler, try adding the /ANALYSIS_ DATA qualifier when you use any other supported compiler. For example: $ CC/ANALYSIS_DATA myfile.c Once you have a .ANA file, you can load it into your SCA library either from LSE or standalone SCA. To load the .ANA file and show the new module, type the following commands: SCA> LOAD myfile.ANA SCA> SHOW MODULE You will see that the new module has been loaded into the library, and you will now be able to query that library. 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 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 < caller> is any legal query expresion, is a positive integer, RESULT_KEYWORD can be STRUCTURE, NOSTRUCTURE, ANY_PATH, BEGIN, or END, and QUERY_ EXPRESSION is any legal query expression. For a full description of the CALLED_BY relationship, see the on-line help file SCACOMMANDS. 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 is any legal query expresion, is a positive integer, RESULT_KEYWORD can be STRUCTURE, ANY_PATH, BEGIN, or END, and QUERY_EXPRESSION is any legal query expression. For a full description of the CALLING relationship, see the on-line help file SCACOMMANDS. 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 on-line help file SCACOMMANDS. 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 on-line help file SCACOMMANDS. 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 find 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 OpenVMS file specification. You should enclose the file specification in quotation marks because it normally contains a period (.) The format for the FILE_SPEC attribute is as follows: FILE_SPEC="filename.filetype" An example using the FILE_SPEC attribute follows: FIND FILE_SPEC="MYPROG.FOR" This query finds all occurrences in the file MYPROG.FOR. 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 NAME NAME is an attribute of an occurrence that is a string of ASCII characters which identifies symbols in your source code. A specific name can be associated with more than one symbol. The language you are using defines the legal characters for a name. Each name has zero or more characters. Any character may appear in a name. Special characters that appear in a name must be quoted using double quotes. You do not need to quote the following: $, _, *, %, &, -, alphanumeric characters. You can use wildcards (* and %) in the name expression. You can override the wildcard characters by using the escape character (&). For example, you can find the name consisting of a single asterisk using the name expression &*. If you want an ampersand in a string, you must use two successive ampersands. The format for NAME can be one of the following: name NAME=(name[,name...]) 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 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 on-line help file SCACOMMANDS. 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 on-line help file SCACOMMANDS.