1 SCA The Source Code Analyzer for OpenVMS is an interactive, multilanguage, source code cross-reference and static analysis tool that is designed to aid developers in understanding the complexities of large-scale software systems. Format SCA [qualifiers] 2 Qualifiers /INTERFACE /INTERFACE=DECWINDOWS /INTERFACE=CHARACTER_CELL (D) Activates either the character-cell or DECwindows interface to SCA. The default is the character-cell interface. 2 @file-spec Executes Source Code Analyzer for OpenVMS commands contained in the specified file. Format @file-spec 3 Example $ SCA @TEST %SCA-S-VERSION, this is SCA version V4.7 %SCA-S-LIB, your SCA Library is SCA$ROOT:[EXAMPLE] $ This example executes the command file TEST.COM containing the commands SHOW VERSION and SHOW LIBRARY. 2 ANALYZE [SCA Command] Creates an analysis data file that describes a source file. Format ANALYZE file-spec[, . . .] 3 Qualifiers /DESIGN /DESIGN[=design-option] /NODESIGN (D) Indicates that the source file should be processed as a program design language. The design options are as follows: COMMENTS The ANALYZE command looks inside comments for design information. Information about comments is included in the analysis data file. Any errors detected are reported. NOCOMMENTS The ANALYZE command ignores comments. PLACEHOLDERS The ANALYZE command treats LSE placeholders as valid syntax. Placeholders are reported in the analysis data file. NOPLACEHOLDERS The ANALYZE command does not report placeholders in the .ANA file. It does not report errors if placeholders are encountered. If you specify the /DESIGN qualifier, the default is /DESIGN= (COMMENTS,PLACEHOLDERS). If you do not specify this qualifier, the default is /NODESIGN. /LANGUAGE /LANGUAGE=language Specifies the language of the source file. By default, the language is that which is specified by the file type of the source file. /LOG /LOG (D) /NOLOG Indicates whether each analyzed file is reported. /OUTPUT /OUTPUT[=file-spec] /OUTPUT=file-name.ANA (D) Specifies the analysis data file to be created. The default is /OUTPUT= filename.ANA, where file-name is the name of the first source file specified as the parameter to this command. 3 Parameter file-spec[, . . . ] Specifies the files to be analyzed. You can use wildcards with the file-spec parameter. Within LSE, the current buffer is analyzed by default. 2 CONVERT 3 LIBRARY [SCA Command] Converts the specified library from Version 2.0 or Version 3.1 format to Version 4.0 format. Format CONVERT LIBRARY directory-spec1 [directory-spec2] 4 Parameters directory-spec1 Specifies the directory specification of the Version 2.0 or 3.1 library to be converted. directory-spec2 Specifies the directory in which the Version 4.0 library is to be created. If this parameter is omitted, the new library is created in the directory specified by directory-spec1, and the old library is deleted. If this parameter is specified and is different from directory-spec1, the old library is not deleted. 2 CREATE 3 LIBRARY [SCA Command] Allocates and initializes OpenVMS library files in a specified directory. The new library then becomes an active SCA library. Format CREATE LIBRARY directory-spec[, . . . ] 4 Qualifiers /AFTER /AFTER=library-spec Instructs SCA to insert the new library or libraries into the list of active SCA libraries following the library you specify as the value of the qualifier. If you do not specify a value, SCA adds the library or libraries to the end of the list. /BEFORE /BEFORE=library-spec Instructs SCA to insert the new library or libraries into the list of active SCA libraries in front of the library you specify as the value of the qualifier. If you do not specify a value, SCA adds the library or libraries to the beginning of the list. /CREATE_DIRECTORY /CREATE_DIRECTORY /NOCREATE_DIRECTORY (D) Instructs SCA to create the specified directory if it does not exist. /LOG /LOG (D) /NOLOG Indicates whether SCA reports the successful creation of a library and the resulting list of active libraries. /MODULES /MODULES=module-count /MODULES=25 (D) Specifies an estimated number of modules in the library. /REPLACE /REPLACE /NOREPLACE (D) Indicates whether SCA replaces an existing library with a new (empty) library. /SIZE /SIZE=block-count /SIZE=1000 (D) Specifies an estimated size for a library. 4 Parameter directory-spec[, . . . ] Specifies one or more directories in which library files are to be allocated and initialized. 2 DELETE Deletes the effect of the item specified by the option word. Format DELETE option 3 LIBRARY [SCA Command] Deletes an SCA library from a OpenVMS directory. Format DELETE LIBRARY library-spec[,...] 4 Qualifiers /CONFIRM /CONFIRM /NOCONFIRM (D) Indicates whether the delete function will request a confirmation of the deletion of each library. To delete an SCA library, you must respond to the confirmation prompt by typing one or more characters of the word YES. Otherwise, the library is not deleted. /LOG /LOG /NOLOG (D) Indicates whether successful deletion of SCA libraries will be reported. 4 Parameter library-spec[,...] Specifies one or more libraries to be deleted. The library must be one of the current SCA libraries established by the SET LIBRARY command. You can use a library number in place of a library specification. For example, the primary library is library #1. You can also specify a wildcard name expression. 3 MODULE [SCA Command] Deletes specified modules of source analysis data from SCA libraries. Format DELETE MODULE module-name[, . . . ] 4 Qualifiers /CONFIRM /CONFIRM /NOCONFIRM (D) Tells SCA whether or not to prompt you to confirm each module deletion. To delete a module, you must respond to the confirmation prompt by typing Y, YE, or YES. If you specify N, NO, or press the Return key, SCA does not delete the module. SCA considers any other response to be ambiguous and reissues the confirmation prompt. /DECLARATION_CLASS /DECLARATION_CLASS=declaration-class Indicates the class of the module to be deleted. The following declaration classes are supported: PRIMARY- Module implementation ASSOCIATED-Module specification If you do not specify a declaration class, SCA deletes both classes, if they exist. /LIBRARY /LIBRARY[=library-spec] /LIBRARY=primary-library (D) Specifies an SCA library containing the module to be deleted. This library must be one of the current libraries (established by a SET LIBRARY command). If you do not specify a library, the primary SCA library is the default; that is, the module is deleted from the first of the current SCA libraries. /LOG /LOG (D) /NOLOG Indicates whether SCA reports successful deletion of a module. 4 Parameter module-name[, . . . ] Specifies the names of the modules to be deleted from the current library. You may specify a wildcard name expression. 3 QUERY [SCA Command] Deletes the indicated query. Format DELETE QUERY [query-name] 4 Parameter query-name Specifies the query to be deleted. If you omit the query name, the current query is deleted. You can specify wildcards. 2 EXIT [SCA Command] Ends an LSE editing session or SCA query session and returns control to the calling process or the OpenVMS command language interpreter. Format EXIT 3 Qualifier /LOG /LOG /NOLOG (D) [SCA] Indicates whether completion of an SCA session is reported. 2 EXTRACT Extracts the specified items for use in LSE commands or SCA libraries. Format EXTRACT item-type item-name 3 MODULE [SCA Command] Extracts specified modules of source analysis data from an SCA library. Format EXTRACT MODULE module-name-expr[, . . . ] 4 Qualifiers /DECLARATION_CLASS /DECLARATION_CLASS=declaration-class Indicates the class of the module to be copied. The following declaration classes are supported: PRIMARY-Module implementation ASSOCIATED-Module specification If you do not specify a declaration class, SCA extracts both classes, if they exist. /LIBRARY /LIBRARY=library-spec Specifies the SCA static library from which to extract the module. This library must be one of the current SCA libraries (established by a SET LIBRARY command). If you do not specify this qualifier, then SCA tries to extract the module from the primary library (the first of the current SCA libraries). /LOG /LOG /NOLOG (D) Indicates whether SCA reports the extraction of a module. /OUTPUT /OUTPUT=file-spec Specifies the file into which all modules of source analysis data will be written. The default is /OUTPUT=module-name.ANA, where the module name is the name of the file the compiler created. 4 Parameter module-name-expr[, . . . ] Specifies the modules to extract. If you specify more than one library, SCA extracts the module from the first library in which it occurs. 2 FIND [SCA Command] Locates occurrences described by the current SCA libraries. For information on the SCA query language, see SCA_Topics in online help. Format FIND query-expression 3 Qualifiers /DESCRIPTION /DESCRIPTION=string Specifies a single line of text that is displayed along with the query name when the query is displayed by issuing the SHOW QUERY command. /DISPLAY /DISPLAY[=(option, . . . )] /DISPLAY=DEFAULT (D) /NODISPLAY Indicates how much information SCA displays concerning query results. Use one or more of the following keywords to request specific information: NAME Symbol name CLASS Class of item LINE_NUMBER Compilation line number MODULE Module name containing a symbol occurrence FILE_SPEC File name and type containing a symbol occurrence FULL_FILE_SPEC Complete file specification containing a symbol occurrence RECORD_NUMBER Record number within a source file RELATIONSHIP Relationship type NUMBER Number of the display line OCCURRENCE_ Type of symbol occurrence (such as declaration, TYPE read, call) ALL All of the previous options DEFAULT Default settings of the display options NONE Nothing (equivalent to the /NODISPLAY qualifier) You can prefix any keyword (except ALL, DEFAULT, and NONE) with NO to request that the information be excluded. The initial default for each type of new query is as follows: DISPLAY=(NAME,CLASS,MODULE,LINE,OCCURRENCE,RELATIONSHIP) /LOG /LOG (D) /NOLOG Indicates whether the count of symbol occurrences will be reported. /MODIFY /MODIFY[=query-name] /NOMODIFY (D) Indicates that an existing query is to be modified. By default, each FIND command creates a new query. The /MODIFY=query-name qualifier indicates that the specified query should be modified according to the specification of the FIND command. The specified query must already exist. By default, the /MODIFY qualifier specifies the current query. /NAME /NAME[=query-name] Specifies the name of the query. If a query with the same name already exists, you must also specify the /REPLACE qualifier. If a query-name is not specified, then SCA assigns a unique name to the query. The query name can be a quoted string. /OUTPUT /OUTPUT[=file-spec] Specifies that command output is to go to a file rather than be displayed on your screen (or go to a batch log file). The default output file specification is SCA.LIS. /REPLACE /REPLACE /NOREPLACE (D) Indicates whether existing queries should be replaced by new queries. By default, a FIND command that creates a query with the same name as an already existing query will fail. /RESULT /RESULT=option /RESULT=DEFAULT (D) /NORESULT Indicates the type of query results displayed. You must specify one of the following keywords: SYMBOLS Only symbols are displayed. OCCURRENCES Symbols and occurrences are displayed. DEFAULT Either symbols or occurrences, or both are displayed. SCA chooses the result type that is most appropriate for the current query. The /NORESULT qualifier specifies that no results should be displayed. This means that no query evaluation is done. If a query result exists because you issued a FIND command, then specifying /NORESULT causes that result to be deleted. /SYNCHRONIZE /SYNCHRONIZE /NOSYNCHRONIZE (D) Indicates that the query result must be synchronized with the current state of the virtual library being queried. By default, /NOSYNCHRONIZE causes SCA to do as little processing as necessary to evaluate the query. This can lead to query results that reflect the state of the virtual library at the time of a previous query. The /SYNCHRONIZE qualifier specifies that the query result must be synchronized with the current virtual library. SCA attempts to minimize the amount of processing, but the result is still synchronized with the virtual library that was in effect at the time the query was evaluated. 3 Parameter query-expression Specifies the set of occurrences to be found. 2 GOTO Moves the cursor to the item specified by the option word. Format GOTO option 3 DECLARATION [SCA Required] Displays the declaration of the symbol indicated. LSE displays the source code containing the symbol declaration in another window and positions the cursor on the symbol declaration. Format GOTO DECLARATION [symbol-name] 4 Qualifiers /ASSOCIATED Indicates that you want to see the associated declaration for the symbol. An associated declaration is a related declaration that accompanies the primary declaration (such as an EXTERNAL declaration). /CONTEXT_DEPENDENT If you specify both the /CONTEXT_DEPENDENT and the /INDICATED qualifiers, then SCA determines which declaration to display by using the following criteria: o If the indicated occurrence of the symbol is a reference, LSE displays the declaration specified by the compiler as bound to that occurrence of the symbol. o If the indicated occurrence of the symbol is an associated declaration, LSE displays the primary declaration. o If the indicated occurrence of the symbol is a primary declaration, LSE displays the associated declaration. You cannot use the /CONTEXT_DEPENDENT qualifier without the /INDICATED qualifier. /INDICATED Instructs LSE to use the symbol name at the current cursor position, or the text within the currently active selected range, as the symbol name. To help SCA identify exactly which occurrence of the symbol name the cursor is positioned on, LSE passes both the current cursor position in the buffer and the file specification for the current buffer to SCA. If SCA has no information for the symbol name at the current cursor position (for example, if the line containing the symbol is a new line and the file has not been recompiled), then SCA uses whatever general information it has about that symbol as if you issued a GOTO DECLARATION command for the symbol name without the /INDICATED qualifier. If you specify the /INDICATED qualifier, you must not specify the symbol-name parameter. You cannot use the /INDICATED qualifier without the /CONTEXT_ DEPENDENT qualifier. /PRIMARY /PRIMARY (D) Indicates that you want to see the primary declaration for the symbol. A primary declaration is the declaration that SCA interprets as most significant for a symbol (such as a FUNCTION declaration). For example, the primary declaration of a routine describes the body of the routine. 4 Parameter symbol-name Specifies that the declaration associated with the named symbol is to be displayed. You must not specify a symbol name if you specify the /INDICATED qualifier. 3 QUERY [SCA Command] Moves the cursor to the specified SCA query session. Format GOTO QUERY [query-name] 4 Parameter query-name Specifies the name of the query session. 2 IMPORT [SCA Command] Creates analysis data files that describe the indicated XREF data files generated by a HP C++ compiler. Format IMPORT file-spec[, . . .] 3 Qualifiers /LOG /LOG (D) /NOLOG Indicates whether each imported file is reported. /OUTPUT /OUTPUT[=file-spec] /OUTPUT=file-name.ANA (D) Specifies the analysis data file to be created. If you do not specify a file specification, the default is the file name of the file being imported and the file type .ANA. 3 Parameter file-spec[, . . . ] Specifies one or more files of XREF data to be imported. You can use wildcards with the file-spec parameter. The default file type is .XREF, which is the default file type for XREF data files created by HP compilers. 2 INSPECT [SCA Command] Inspects the consistency between declarations or references for the same symbol. Format INSPECT query-expression 3 Qualifiers /CHARACTERISTICS /CHARACTERISTICS=(option[ . . . ]) /CHARACTERISTICS=ALL (D) Indicates which characteristics of the occurrences should be checked. You can use one or more of the following options to request specific information: IMPLICIT_ Checks that all symbols are explicitly DECLARATIONS declared. TYPE Checks that the types of all occurrences of each symbol match. UNIQUENESS Checks that multiple declarations of the same symbol have the same name. UNUSED_SYMBOLS Checks that all symbols are used. USAGE Looks for symbols that are read but never written, or written but never read. ALL Checks all of the preceding characteristics. Any of these options (except ALL) can have the prefix NO to indicate that the characteristic should not be checked. Each of the characteristic options takes a query-expression as an optional value. The characteristic-specific query expression specifies the set of occurrences for which that characteristic will be checked. If the prefix NO is present, then the query expression indicates occurrences for which that characteristic will not be checked. The default query expression for each characteristic option is to check all occurrences. /DESCRIPTION /DESCRIPTION=string Specifies a single line of text that is displayed along with the query name when the query is displayed by issuing the SHOW QUERY command. /DISPLAY /DISPLAY[=(option, . . . )] /DISPLAY=DEFAULT (D) /NODISPLAY Indicates how much information SCA displays concerning query results. Use one or more of the following keywords to request specific information: NAME Symbol name CLASS Class of item LINE_NUMBER Compilation line number FILE_NAME File name and type containing a symbol occurrence FULL_FILE_SPEC Complete file specification containing a symbol occurrence RECORD_NUMBER Record number within a source file OCCURRENCE_ Type of symbol occurrence (such as declaration, TYPE read, call) ALL All of the previous options DEFAULT Default settings of the display options NONE Nothing (equivalent to the /NODISPLAY qualifier) You can prefix any keyword (except ALL, DEFAULT, and NONE) with NO to request that information be excluded. The initial default for each type of new query is as follows: DISPLAY=(NAME,CLASS,MODULE,LINE,OCCURRENCE) /ERROR_LIMIT /ERROR_LIMIT=(global-limit[,symbol-limit]) /NOERROR_LIMIT (D) Specifies the maximum number of errors that the INSPECT command should report. This causes the INSPECT command to stop if the number of errors exceeds the maximum. The global-limit parameter specifies the maximum number of errors reported for all symbols before the INSPECT command stops. The symbol-limit parameter specifies the maximum number of errors reported for a particular symbol before the INSPECT command stops reporting errors for that symbol. /LOG /LOG (D) /NOLOG Indicates whether the count of symbol occurrences will be reported. /MODIFY /MODIFY[=query-name] /NOMODIFY (D) Indicates that an existing query is to be modified. By default, each INSPECT command creates a new query. The /MODIFY=query-name qualifier indicates that the specified query should be modified according to the specification of the INSPECT command. The specified query must already exist. By default, the /MODIFY qualifier specifies the current query. /NAME /NAME[=query-name] Specifies the name of the query. If a query with the same name already exists, you must also specify the /REPLACE qualifier. If a query name is not specified, then SCA assigns a unique name to the query. /OUTPUT /OUTPUT[=file-spec] Specifies that command output is to go to a file rather than be displayed on your screen (or go to a batch log file). The default output file specification is SCA.LIS. /REPLACE /REPLACE /NOREPLACE (D) Indicates whether existing queries should be replaced by new queries. By default, an INSPECT command that creates a query with the same name as an already existing query will fail. /RESULT /RESULT=option /RESULT=DEFAULT (D) /NORESULT Indicates the type of query results displayed. You must specify one of the following keywords: SYMBOLS Only symbols are displayed. OCCURRENCES Symbols and occurrences are displayed. DEFAULT Either symbols or occurrences, or both are displayed. SCA chooses the result type that is most appropriate for the current query. The /NORESULT qualifier specifies that no results should be displayed. This means that no query evaluation is done. If a query result exists because you issued an INSPECT command, then specifying /NORESULT causes that result to be deleted. /SEVERITY_LEVEL /SEVERITY_LEVEL=severity-level /SEVERITY=INFORMATIONAL (D) Indicates the lowest severity level for diagnostics to be reported, as follows: INFORMATIONAL WARNING ERROR FATAL_ERROR /SYNCHRONIZE /SYNCHRONIZE /NOSYNCHRONIZE (D) Indicates that the query result must be synchronized with the current state of the virtual library being queried. By default, /NOSYNCHRONIZE causes SCA to do as little processing as necessary to evaluate the query. This can lead to query results that reflect the state of the virtual library at the time of a previous query. The /SYNCHRONIZE qualifier specifies that the query result must be synchronized with the current virtual library. SCA attempts to minimize the amount of processing, but the result is still synchronized with the virtual library that was in effect at the time the query was evaluated. 3 Parameter query-expression Specifies the set of occurences to be inspected. 2 LOAD [SCA Command] Loads one or more files of compiler-generated source analysis data into an SCA library. Format LOAD file-spec[, . . . ] 3 Qualifiers /DELETE /DELETE /NODELETE (D) Deletes an analysis data file after it has been successfully loaded into an SCA library. /LIBRARY /LIBRARY=library-spec /LIBRARY=primary-library (D) Specifies an SCA physical library to update. This library must be one of the current SCA libraries, established by a SET LIBRARY command. If you do not specify this qualifier, SCA refers to the primary SCA library; that is, SCA updates the first of the current SCA physical libraries. /LOG /LOG (D) /NOLOG Indicates whether SCA reports successful updating of SCA libraries. /REPLACE /REPLACE (D) /NOREPLACE Indicates whether SCA replaces existing modules of source analysis data with new information. 3 Parameter file-spec[, . . . ] Specifies one or more files of source analysis data to be loaded into an SCA library. You may use a wildcard file specification. The default file type is .ANA, which is the default file type for source analysis data files created by compilers. 2 NEXT Moves the cursor to the next item specified by the option word. Format NEXT option 3 OCCURRENCE [SCA Required] Moves the cursor forward to the next occurrence of the current source symbol in the current query and highlights that next occurrence. Format NEXT OCCURRENCE 3 QUERY [SCA Command] Moves the cursor to the next SCA query session. Format NEXT QUERY 3 SYMBOL [SCA Required] Moves the cursor forward to the next source symbol in the current query and highlights that next symbol. Format NEXT SYMBOL 2 PREVIOUS Moves the cursor to the previous item specified by the option word. Format PREVIOUS option 3 OCCURRENCE [SCA REquired] Moves the cursor back to the previous occurrence of the current source symbol in the current query and highlights that occurrence. Format PREVIOUS OCCURRENCE 3 QUERY [SCA Command] Moves the cursor back to the previous SCA query session. Format PREVIOUS QUERY 3 SYMBOL [SCA Required] Moves the cursor back to the previous source symbol in the current query and highlights that source symbol. Format PREVIOUS SYMBOL 2 REORGANIZE [SCA Command] Optimizes the organization of the specified SCA libraries. Format REORGANIZE [library-spec[, . . . ]] 3 Qualifier /LOG /LOG (D) /NOLOG Indicates whether SCA reports a successful library reorganization. 3 Parameter library-spec[, . . . ] Specifies the SCA libraries to be reorganized. If you do not specify a library, LSE reorganizes the primary SCA library. 2 REPORT [SCA Command] Produces the specified report. Format REPORT report-name other-parms[ . . . ] 3 Qualifiers /DOMAIN /DOMAIN=query-name Specifies the name of the query to use as the domain for the report. The query should include occurrences of files that have been compiled. This value is converted to a VAXTPU value and assigned to the global VAXTPU variable SCA$REPORT_DOMAIN_QUERY. This procedure limits the report to objects that are contained, directly or indirectly, within at least one of the files in this query. The default value is the null string. By convention, VAXTPU report procedures interpret this as the entire SCA library. /FILL /FILL (D) /NOFILL Specifies that whenever a paragraph of commented text is inserted into a report, it is set up so that a text processor, such as RUNOFF or DOCUMENT performs the usual fill and justification operations on the paragraph. If you specify /NOFILL, then the report tool does not instruct the text processor to fill or justify the paragraph. For any individual paragraph, you can override the setting of this qualifier by including appropriate text-processor comments within the body of the comment. The value of this qualifier is used to set the value of the global VAXTPU variable SCA$REPORT_FILL as follows. If you specify the /FILL qualifier, or it is indicated by default, then SCA$REPORT_ FILL is 1; if you specify the /NOFILL qualifier, then SCA$REPORT_ FILL is 0. The /FILL qualifier is ignored if it is not meaningful for the target. In particular, it is ignored for LSE package definitions. /HELP_LIBRARY /HELP_LIBRARY=library_name Specifies the help library to use for PACKAGE reports. This qualifier is ignored for other reports. The PACKAGE report generates one or more DEFINE PACKAGE commands. The library_name specifies the value to use with the /HELP_LIBRARY qualifier for the generated DEFINE PACKAGE commands. If you omit this qualifier, the PACKAGE report omits the /HELP_ LIBRARY qualifier from the DEFINE PACKAGE commands it generates. /LANGUAGES /LANGUAGES=(language,[ . . . ]) Specifies the language to use for PACKAGE reports. This qualifier is ignored for other reports. The PACKAGE report generates one or more DEFINE PACKAGES commands. This qualifier specifies the languages to use as the values of the /LANGUAGE qualifier for the generated DEFINE PACKAGE commands. If you omit this qualifier, the PACKAGE report inserts the LSE placeholder {language_name} . . . as the value for the /LANGUAGE qualifier with the DEFINE PACKAGE commands. Before you can execute the DEFINE PACKAGE command, you must replace the placeholder manually with the names of the languages that are appropriate for the languages being defined. /OUTPUT /OUTPUT=file-name Specifies the output file to use for the report. This value is converted to a VAXTPU string and passed as the value for the global VAXTPU variable SCA$REPORT_OUTPUT. The default value takes the file name from the report-name parameter and the file type from the target-file-type parameter. The target-file-type is implied by the /TARGET qualifier. For example, if you specify DOCUMENT for the /TARGET qualifier, this implies a file type of .SDML. /TARGET /TARGET=target-file-type Specifies the type of target file to produce. This value is converted to a VAXTPU string value and assigned to the global VAXTPU variable SCA$REPORT_TARGET. You can specify one of the following keywords: Keyword Type of file TEXT, TXT Text file RUNOFF, DSR, RNO A file for processing by RUNOFF SDML, DOCUMENT A file for processing by VAX DOCUMENT LSEDIT, LSE A file for processing by LSE HLP, HELP A help file for processing by the Librarian OTHER=value Optional file type Note that the OTHER keyword can take an optional value. The default value is the null string, which by convention is interpreted by the VAXTPU procedures as TEXT. User supplied report procedures can ignore this convention and provide their own defaults. The default target file types are SDML for INTERNALS and 2167A_ DESIGN reports, HLP for HELP reports, and LSE for PACKAGE reports. 3 Parameters report-name Specifies the name of the report to produce. The report name should be the name of one of the HP supplied reports or the name of a user-written report. You can abbreviate the report name if the abbreviation is unique. The REPORT command uses the report-name parameter to find a corresponding VAXTPU procedure whose name starts with SCA_REPORT_ report-name. This VAXTPU procedure is invoked to produce the report. Because there is a VAXTPU restriction on the length of procedure names, a report name must not exceed 121 characters. HP has implemented the following reports: o HELP - A help file, suitable for processing by the OpenVMS Librarian into a help library. o PACKAGE - An LSE package definition, which can be processed by LSE and put into an environment file, to create templates for calling the procedures in your code. o INTERNALS - A comprehensive report on the software in your system, all of the information in comment headers, and a structural presentation of your code. o 2167A_DESIGN - The design section of the DOD-STD-2167A Software Design Document. other-parms[ . . . ] Specifies other parameters that are passed to the VAXTPU procedure. These parameters are collected into a single string, which is then assigned to the global VAXTPU variable SCA$_REPORT_ REST_OF_LINE. These SCA parameters are obtained from the command line from the $REST_OF_LINE type of the OpenVMS Command Definition Utility. 2 SAVE Saves information about the item specified by the option word. Format SAVE option 3 QUERY [SCA Command] Saves information about one or more current SCA query sessions. The information saved for a query session is a FIND command for the query session. The saved commands can be executed by SCA by means of the @file-spec command. Format SAVE QUERY [query-name,...] 4 Qualifiers /OUTPUT /OUTPUT[=file-spec] /OUTPUT=QUERY.COM (D) Specifies the save data file to be created. The default file type is .COM. /PREFIX /PREFIX=prefix Specifies the prefix to be applied to all query names in the saved information. /QUALIFIERS="qualifiers" Specifies the qualifiers to be applied to FIND commands in the saved information. Should not include /NAME or /DESCRIPTION. 4 Parameters query-name Specifies the name of the query to be displayed. If you specify a null query name (""), SCA assumes you mean the current query. If you omit this parameter, SCA assumes you have specified an asterisk (*). 4 Example $ SCA SCA> FIND/DESC=XYZ X* SCA> FIND/NAME=ABC @1 OR Y* SCA> SAVE QUERY/PREFIX=X_/QUALIFIERS="/NODISPLAY" Following the above file QUERY.COM will contain: find/name=X_1/desc=XYZ/NODISPLAY X* find/name=X_ABC/NODISPLAY @X_1 OR Y* 2 SET Enables the item specified by the option word. Format SET option 3 LIBRARY [SCA Command] Identifies the SCA physical libraries to be used for subsequent SCA functions. Format SET LIBRARY directory-spec[, . . . ] 4 Qualifiers /AFTER /AFTER[=library-spec] Instructs SCA to insert the new library or libraries into the list of active SCA libraries after the library you specify as the qualifier value. If you do not specify a value, SCA adds the library or libraries to the end of the list. /BEFORE /BEFORE[=library-spec] Instructs SCA to insert the new library or libraries into the list of active SCA libraries before the library you specify as the qualifier value. If you do not specify a value, SCA adds the library or libraries to the beginning of the list. /LOG /LOG (D) /NOLOG Indicates whether SCA reports the resulting list of active SCA libraries. 4 Parameter directory-spec[, . . . ] Specifies one or more directories, each of which comprises a separate SCA library. The list of libraries you specify replaces the current list of active libraries unless you specify an /AFTER or /BEFORE qualifier. 3 NOLIBRARY [SCA Command] Removes the specified SCA libraries from the current list of active libraries. Format SET NOLIBRARY [library-spec[, . . . ]] 4 Qualifier /LOG /LOG (D) /NOLOG Indicates whether LSE reports removal of the libraries from the active list. 4 Parameter library-spec[, . . . ] Specifies the libraries to be removed from the current active libraries list. If you omit this parameter, SCA removes all the active libraries from the list. 2 SHOW Displays information about the item specified by the option word. Format SHOW option 3 LIBRARY [SCA Command] Displays the directory specification for all active SCA libraries. Format SHOW LIBRARY 4 Qualifiers /BRIEF /BRIEF (D) Displays only the directory specification for all active libraries. /FULL Displays all information about all active SCA libraries. 3 MODULE [SCA Command] Displays information about SCA library modules. Format SHOW MODULE [module-name[, . . . ]] 4 Qualifiers /ALL Specifies that SCA display both hidden and visible modules. /BRIEF Indicates how much information you want displayed. The /BRIEF qualifier causes SCA to display selected information about each indicated module in tabular format. If you specify a wildcard expression for the parameter, or if SCA assumes one, /BRIEF is the default. /FULL Indicates how much information you want displayed. The /FULL qualifier causes SCA to list all information available about each indicated module. If you specify an explicit name for the parameter, /FULL is the default. /HIDDEN Specifies that SCA display only hidden modules. /LIBRARY /LIBRARY=library-spec /LIBRARY=* (D) Specifies an SCA library containing the module to be displayed. The library must be one of the current SCA libraries established by a SET LIBRARY command. If you do not specify the /LIBRARY qualifier, SCA assumes you have specified all current SCA libraries. /OUTPUT /OUTPUT[=file-spec] Directs command output to a file rather than to the $SHOW buffer. The default output file specification is SCA.LIS. /VISIBLE /VISIBLE (D) Specifies that SCA display only visible modules. 4 Parameter module-name[, . . . ] Specifies the modules to be displayed. If you omit this parameter, SCA displays all modules. You may specify wildcard module names. 3 QUERY [SCA Command] Displays information about one or more current SCA query sessions. Format SHOW QUERY [query-name,...] 4 Qualifiers /BRIEF /BRIEF (D) Indicates how much information you want to be displayed. The /BRIEF qualifier causes SCA to display (in tabular format) the query name, query expression, and description for the indicated query. /FULL Indicates how much information you want to be displayed. The /FULL qualifier causes SCA to display all information about the indicated query. 4 Parameter query-name Specifies the name of the query to be displayed. If you specify a null query name (""), SCA assumes you mean the current query. If you omit this parameter, SCA assumes you have specified an asterisk (*). 3 VERSION [SCA Command] Displays the current version of LSE and SCA. Format SHOW VERSION 2 SPAWN [SCA Command] Spawns a subprocess running the DCL command interpreter and suspends the editing session. NOTE This function is not available in DECwindows; any attempt to invoke it incurs an error. Format SPAWN [command] 3 Parameter command Specifies a command line to be executed by the spawned subprocess. If you specify this parameter, the subprocess ends and LSE regains control upon completion of the command. 2 VERIFY [SCA Command] Verifies that the specified SCA libraries are valid, and repairs any corrupted libraries. Format VERIFY [library-spec[, . . . ]] 3 Qualifiers /LOG /LOG (D) /NOLOG Indicates whether SCA reports the library verification or repair operation. /RECOVER /RECOVER /NORECOVER (D) Indicates whether SCA should repair a corrupted library. If the interrupted command was a LOAD command, SCA deletes from the library any module that had begun to load but that had not completed loading. Also, SCA cannot recover modules that were waiting to be processed for loading when the interruption occurred. To load interrupted and waiting modules, issue a subsequent LOAD command and include those modules. If the interrupted library operation was a DELETE MODULE command, the /RECOVER qualifier causes SCA to delete the incompletely deleted module. Any modules still waiting to be processed for deletion when the interruption occurred are excluded from the recovery operation; to delete them, you must respecify them in a subsequent DELETE MODULE command. 3 Parameter library-spec[, . . . ] Specifies the SCA libraries to be verified. If you do not specify a library, SCA assumes you have specified the primary library. 2 Release_Notes Release notes for SCA are contained in the file: SYS$HELP:SCAvvu.RELEASE_NOTES The product name is followed by the version number (vvu). For example, the following is the release notes file for Version 4.6 of SCA. SYS$HELP:SCA046.RELEASE_NOTES 2 SCA_Topics [SCA] 3 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. 3 Basic_Query_Concepts This section covers some of the basic concepts underlying SCA queries. You may want to have a hardcopy of this section. The directions for producing a hardcopy are as follows: 1. Place the contents of Basic_Query_Concepts in a printable file by typing the following command at the DCL command line: $ HELP/OUTPUT=BASIC_QUERY_CONCEPTS.TXT - _$ SCA SCA_Topics Basic_Query_Concepts 2. Print BASIC_QUERY_CONCEPTS.TXT from the DCL command line as follows: $ PRINT BASIC_QUERY_CONCEPTS.TXT What Queries Are An SCA library is a collection of information about your source code. This includes information, such as the names and locations of all variables in your code, all the places where routines are called and what their arguments are, and many other kinds of information. Issuing a query is the process of selecting some of this information from the library. By giving a query expression with the FIND command, you specify exactly what information you want to retrieve from the library. Occurrences An occurrence is any instance of an entity in your program. An entity can be any language construct, such as a variable, a routine, or a constant. To further clarify this, consider the following code fragment (not written in a particular language): 1 MODULE myprog; 2 3 VAR i,j; 4 5 ROUTINE foo() 6 BEGIN 7 i = 5; 8 j = i; 9 END; 10 END; The code contains four entities (myprog, foo, i, j). There is one occurrence each of the module myprog, and the routine foo. The variable i, however, has three occurrences, and the variable j has two. Attribute Selection Attribute selection is a query that selects occurrences based on certain attributes. For example, you can have SCA return all occurrences in which the name attribute is XYZ. The following sections list the attributes used for selection. NAME Attribute Generally, you think of entities in you program as having only a name. In fact, the name of an entity is only one of its attributes. What you are doing when you give the basic query FIND X, is asking for all occurrences in the library that have the name attribute X. (The query FIND X is equivalent to the query FIND NAME=X. NAME= is the default attribute, so it may be omitted.) SYMBOL_CLASS Attribute The symbol class attribute describes an occurrence in terms of language constructs. In the previous example, myprog is a MODULE, foo is a ROUTINE, and i and j are variables. Thus, you could ask SCA to find things based on the symbol class only. For example, you can find all the routines in the library by giving the following query: FIND SYMBOL_CLASS=ROUTINE Note that MODULE, ROUTINE, and VARIABLE are SCA keywords for symbol classes. Because different languages use different terminology, there is a need to understand how the SCA language- independent terms relate to the language-specific terms. We have provided tables to help you match the SCA terms to the specific language constructs for all the languages that support SCA. See the Getting_Started help subtopics for specific languages. OCCURRENCE Attribute The occurrence class attribute allows you to select occurrences based on attributes specific to the occurrence. In the previous example, on line 3 the occurrence of the variable i has an occurrence class of PRIMARY. On line 7, the occurrence has an occurrence class of WRITE, and on the following line, its occurrence class is READ. To find all entities that are declared in your system, specify the following query: FIND OCCURRENCE=PRIMARY Note that as with symbol classes, there is a need to understand the relationship between the SCA occurrence class keywords and the equivalent language terminology. See the Getting_Started help subtopics for specific languages. FILE_SPEC Attribute Another attribute of all occurrences is the name of the file in which they occur. If the previous example program was in a file called MYPROG.BAR, then the following query would return all the occurrences found in the file; in this case, all occurrences of myprog, foo, i, and j: FIND FILE_SPEC="MYPROG.BAR" SYMBOL DOMAIN Attribute The domain of an entity defines the scope within the source over which the entity is known. Variables or routines, for example, may be local to a particular module, or they might be known to all modules in a system. To find all occurrences of entities that are known throught your system, specify the following query: FIND DOMAIN=GLOBAL See the Getting_Started help subtopics for specific languages. Basic Queries You have already seen examples of the most basic type of query, that is a query based on the selection of just one attribute. These examples are: FIND X FIND SYMBOL=ROUTINE FIND OCCURRENCE=PRIMARY FIND DOMAIN=GLOBAL FIND FILE_SPEC="MYPROG.BAR" Each of these queries results in a set of occurrences. Often, the result of such a query contains more information than you really want. You can explicitly indicate the result you want by specifying multiple attributes and combining them by using set operations. For example, if you only want the ROUTINES named X (rather than all items named X or all routines), specify the following query expression: FIND X AND SYMBOL=ROUTINE In the previous example, the set operator AND was used to take the intersection of the two sets. The other set operators available are OR, XOR, and NOT. In this manner, you can combine attribute selection expressions using multiple set operators. For example: FIND (X OR Y ) AND SYMBOL=ROUTINE AND OCCURRENCE=CALL This query finds all call references to routines named X or Y. Relationship Queries You have already learned how to select occurrences based on their attributes. The following section describes how to select occurrences based on their relationship with other occurrences. Calls Relationship The most common of these relationships is the calls relationship. SCA provides two functions: CALLING and CALLED_BY. With these functions, you can display the call tree structure of your program. The most basic format of the query expression is as follows: FIND CALLED_BY FOO In this example, the result shows a structured display of all the routines that FOO directly calls. You can also display routines that call FOO as follows: FIND CALLING FOO The previous two queries answer the questions, "Who is called by FOO?" and, "Who is calling FOO?" respectively. The full syntax of the relationship functions is complex, and each relationship function is described in more detail under SCA_ Topics. Without explaining why the parentheses are necessary, and emphasizing that the order of parameters is important, the following examples shows one more useful feature of relationship functions. It is possible to get a call tree of arbitrary depth by giving the following query: FIND CALLED_BY (FOO, DEPTH=ALL ) This returns a display showing not only the routines called directly by FOO, but also the routines that they in turn call, for all levels. You can replace the keyword ALL with any positive integer to limit the depth of the call tree. Contains Relationship Another relationship available through SCA is the contains relationship, which is obtained through the CONTAINING and CONTAINED_BY functions. These functions have the same syntax as the calls functions. The CONTAINED_BY function returns all entities logically contained within the given parameter. For example, the query FIND CONTAINED FOO returns two occurrences of i and one occurrence of j, in the code fragment that follows: 1 MODULE myprog; 2 3 VAR i,j; 4 5 ROUTINE foo() 6 BEGIN 7 i = 5; 8 j = i; 9 END; 10 END; Similarly, the following query returns the occurrence of the module MYPROG: FIND CONTAINING FOO Types Relationship The types relationship consists of the two functions TYPING and TYPED_BY. These functions also have the same syntax as the previous functions. The TYPED_BY function returns type trees. This is useful if there are many user-defined types in your system, particularly if they are complex record structures. The TYPING function returns the type of its argument. For more information about all the relationship functions, see the help topic for each relationship. 3 Building_An_SCA_Library To create your own SCA library, you must first create a library directory for it. Using your personal directory, type the following command to create a subdirectory for a local SCA library: $ CREATE/DIRECTORY [.LIB1] Once you have a directory in which to create a library, enter the following command to SCA to create a library: $ SCA CREATE LIBRARY [.LIB1] You now have an empty SCA library. To add a module to the SCA library, you must first compile your source code. Add the /ANALYSIS_DATA qualifier when you use a supported compiler. For example: $ CC/ANALYSIS_DATA myfile.c This produces the file MYFILE.ANA that you can load into your SCA library either from LSE or standalone SCA. To load the .ANA file and show the new module, type the following commands: SCA> LOAD myfile.ANA SCA> SHOW MODULE You will see that the new module has been loaded into the library, and you will now be able to query that library. For more information, see the help topics for Libraries and Reducing_LOAD_Time. 3 Callable_Routines 4 SCA$ASYNCH_TERMINATE Sets a flag indicating that a CTRL-C has been issued. Format SCA$ASYNCH_TERMINATE command_context 5 Argument command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference SCA command context value. 5 Condition_Value_Returned SCA$_NORMAL Normal successful completion. 5 Description The SCA$ASYNCH_TERMINATE routine sets a flag indicating that a CTRL-C has been issued. 4 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 5 Argument command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context value. 5 Condition_Value_Returned SCA$_NORMAL The SCA callable command interface has been successfully shut down. 5 Description The SCA$CLEANUP routine shuts down the SCA callable command interface, freeing all dynamic memory associated with the interface routines and data structures. 4 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] 5 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. 5 Condition_Values_Returned All SCA condition values and many system values. 5 Description The SCA$DO_COMMAND routine parses an SCA subsystem command and invokes command processing if the command is syntactically correct. 4 SCA$GET_ATTRIBUTE Gets a handle to an attribute of an entity. Format SCA$GET_ATTRIBUTE entity, attribute_kind, attribute_handle, [,iteration_context] 5 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. 5 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. 5 Description The SCA$GET_ATTRIBUTE routine gets a handle to an attribute of an entity. If the iteration_context parameter is not specified, then this routine finds the first attribute of the specified kind (attribute_kind) and updates attribute_handle to describe that attribute. In general, several attributes can be associated with a particular entity. With this routine you can find all of those attributes by using the iteration_context parameter. 4 SCA$GET_ATTRI_KIND_T Gets an attribute kind. Format SCA$GET_ATTRI_KIND_T attribute_handle, attribute_kind 5 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. 5 Condition_Value_Returned SCA$_NORMAL An attribute kind has been successfully returned. 5 Description The SCA$GET_ATTRI_KIND_T routine returns the kind of any attribute as a character string. 4 SCA$GET_ATTRI_VALUE_T Gets an attribute value. Format SCA$GET_ATTRI_VALUE_T handle, attribute_value [,attribute_kind] 5 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. 5 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. 5 Description The SCA$GET_ATTRI_VALUE_T routine returns the value of any attribute as a character string. If the handle describes an attribute, then this routine returns the value of that attribute. In this case, the attribute_kind parameter must not be specified. If the handle describes an entity, then this routine returns the value of the first attribute of that entity that is of the kind specified by the attribute_kind parameter. In this case, the attribute_kind parameter must be specified. If you want to get more than one attribute value of a particular kind for an entity, you must use the routine SCA$GET_ATTRIBUTE. This applies only to the attribute kinds SCA$K_ATTRI_NAME and SCA$K_ATTRI_ALL. The value of any kind of attribute can be returned by this routine, except for SCA$K_ATTRI_ALL. This routine will convert to character string those attributes whose data type is not character string. This routine does not accept the attribute-kind SCA$K_ATTRI_ALL as the value of the attribute_kind parameter. It is not meaningful to get just the first attribute without regard to attribute-kind. 4 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 5 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. 5 Condition_Values_Returned SCA$_NORMAL The name of the current query has been successfully retrieved. 5 Description The SCA$GET_CURRENT_QUERY routine gets the name of the current query in the given command context. 4 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] 5 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. 5 Condition_Values_Returned SCA$_NORMAL An input line was returned. Failure completion code from LIB$GET_ INPUT. 5 Description The SCA$GET_INPUT routine gets one record of ASCII text from the current controlling input device specified by SYS$INPUT. 4 SCA$GET_OCCURRENCE Returns an occurrence from the query specified by the query_name argument. Format SCA$GET_OCCURRENCE command_context, query_name, occurrence 5 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. 5 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. 5 Description The SCA$GET_OCCURRENCE routine returns an occurrence from the query specified by the query_name argument. If the occurrence handle supplied is zero, the routine returns a handle to the first occurrence in the query represented by the argument query_name. If the occurrence handle supplied on input represents a valid occurrence, the routine returns a handle to the next occurrence in the query result. In order to be valid, the occurrence handle supplied on input must refer to an occurrence in the query represented by the argument query_name. The query name supplied is interpreted in the context of the command context identified by the argument command_context. Note that the order of retrieval of the occurrences is undefined. 4 SCA$INITIALIZE Initializes the SCA callable command interface. Format SCA$INITIALIZE command_context 5 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. 5 Condition_Value_Returned SCA$_NORMAL The SCA callable command interface has been successfully initialized. 5 Description The SCA$INITIALIZE routine initializes the SCA callable command interface. 4 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 5 Argument command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context. 5 Condition_Value_Returned SCA$_NORMAL The libraries have been successfully locked. 5 Description The SCA$LOCK_LIBRARY routine locks all the physical libraries in the current virtual library list so that they cannot be modified. 4 SCA$PUT_OUTPUT Writes a record to the current controlling output device specified by SYS$OUTPUT. Format SCA$PUT_OUTPUT string, user_argument 5 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. 5 Condition_Values_Returned SCA$_NORMAL The string was successfully written to SYS$OUTPUT. Failure completion from the RMS $PUT service. 5 Description The SCA$PUT_OUTPUT routine writes a record to the current controlling output device specified by SYS$OUTPUT. 4 SCA$QUERY_CLEANUP Cleans up an SCA query context, freeing all dynamic memory associated with the query. Format SCA$QUERY_CLEANUP query_context 5 Argument query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context to be cleaned up. 5 Condition_Value_Returned SCA$_NORMAL The query context has been successfully cleaned up. 5 Description The SCA$QUERY_CLEANUP routine cleans up an SCA query context, freeing all dynamic memory associated with the query. This routine will become obsolete in a future version of SCA. 4 SCA$QUERY_COPY Copies a query from SRC_QUERY_CONTEXT to DST_QUERY_CONTEXT. Format SCA$QUERY_COPY src_query_context, dst_query_context 5 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. 5 Condition_Value_Returned SCA$_NORMAL The query expression has been successfully copied. 5 Description The SCA$QUERY_COPY routine copies a query from SRC_QUERY_CONTEXT to DST_QUERY_CONTEXT. This will copy whatever is in SRC_QUERY_ CONTEXT, whether that is a question, or a question and a result. This routine will become obsolete in a future version of SCA. 4 SCA$QUERY_FIND Finds the occurrences that match the query expression specified by QUERY_CONTEXT. Format SCA$QUERY_FIND query_context 5 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. 5 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. 5 Description The SCA$QUERY_FIND routine finds the occurrences that match the query expression specified by QUERY_CONTEXT. This routine will become obsolete in a future version of SCA. 4 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] 5 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. 5 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. 5 Description The SCA$QUERY_GET_ATTRIBUTE routine gets a handle to an attribute of an entity. If the iteration_context parameter is not specified, then this routine finds the first attribute of the specified kind (attribute_kind) and updates attribute_handle to describe that attribute. In general, several attributes can be associated with a particular entity. With this routine you can find all of those attributes by using the iteration_context parameter. This routine will become obsolete in a future version of SCA. The SCA$GET_ATTRIBUTE routine supersedes this routine. 4 SCA$QUERY_GET_ATTRI_KIND_T Gets an attribute kind. Format SCA$QUERY_GET_ATTRI_KIND_T attribute_handle, attribute_kind 5 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. 5 Condition_Value_Returned SCA$_NORMAL An attribute kind has been successfully returned. 5 Description The SCA$QUERY_GET_ATTRI_KIND_T routine returns the kind of any attribute as a character string. This routine will become obsolete in a future version of SCA. The SCA$GET_ATTRI_KIND_T routine supersedes this routine. 4 SCA$QUERY_GET_ATTRI_VALUE_T Gets an attribute value. Format SCA$QUERY_GET_ATTRI_VALUE_T handle, attribute_value [,attribute_kind] 5 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. 5 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. 5 Description The SCA$QUERY_GET_ATTRI_VALUE_T routine returns the value of any attribute as a character string. If the handle describes an attribute, then this routine returns the value of that attribute. In this case, the attribute_kind parameter must not be specified. If the handle describes an entity, then this routine returns the value of the first attribute of that entity that is of the kind specified by the attribute_kind parameter. In this case, the attribute_kind parameter must be specified. If you want to get more than one attribute value of a particular kind for an entity, you must use the routine SCA$QUERY_GET_ ATTRIBUTE. This applies only to the attribute kinds SCA$K_ATTRI_ NAME and SCA$K_ATTRI_ALL. The value of any kind of attribute can be returned by this routine, except for SCA$K_ATTRI_ALL. This routine will convert to character string those attributes whose data type is not character string. This routine does not accept the attribute-kind SCA$K_ATTRI_ALL as the value of the attribute_kind parameter. It is not meaningful to get just the first attribute without regard to attribute-kind. This routine will become obsolete in a future version of SCA. The SCA$GET_ATTRI_VALUE_T routine supersedes this routine. 4 SCA$QUERY_GET_NAME Returns the name of a query. Format SCA$QUERY_GET_NAME query_context, query_name 5 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. 5 Condition_Value_Returned SCA$_NORMAL The query name has been successfully returned. 5 Description The SCA$QUERY_GET_NAME routine returns the name of a query. This routine will become obsolete in a future version of SCA. 4 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 5 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. 5 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. 5 Description The SCA$QUERY_GET_OCCURRENCE routine successively returns every occurrence in a query result. It provides one pass through all of the occurrences. This routine will become obsolete in a future version of SCA. The SCA$GET_OCCURRENCE routine supersedes this routine. 4 SCA$QUERY_INITIALIZE Initializes an SCA query context. Format SCA$QUERY_INITIALIZE command_context, query_context 5 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). 5 Condition_Value_Returned SCA$_NORMAL The query context has been successfully initialized. 5 Description The SCA$QUERY_INITIALIZE routine initializes an SCA query context. This routine must be called before any other SCA$QUERY_ routines. This routine will become obsolete in a future version of SCA. 4 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] 5 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. 5 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. 5 Description The SCA$QUERY_PARSE routine parses a query expression string and sets up a query context if the command is syntactically correct. This routine will become obsolete in a future version of SCA. 4 SCA$QUERY_SELECT_OCCURRENCE Creates a query expression that matches a specific entity. Format SCA$QUERY_SELECT_OCCURRENCE query_context, entity_handle 5 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. 5 Condition_Value_Returned SCA$_NORMAL A query expression has been successfully defined. 5 Description The SCA$QUERY_SELECT_OCCURRENCE routine creates a query expression that matches a specific entity. You use this routine to specify queries based on the results of previous queries. The entity_handle parameter is obtained by traversing the results of a previous query evaluation. Typically, the query context of the entity_handle parameter is not the same as the query_context parameter. However, they can be the same. If they are the same query context, then that previous query is replaced with the query defined by this routine and, as a result, entity_handle becomes invalid. This routine will become obsolete in a future version of SCA. The SCA$SELECT_OCCURRENCE routine supersedes this routine. 4 SCA$SELECT_OCCURRENCE Creates a query that matches a specific occurrence. Format SCA$SELECT_OCCURRENCE occurrence, query_name 5 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. 5 Condition_Values_Returned SCA$_NORMAL A query expression has been successfully defined. 5 Description You use this routine to create new queries based on the results of previous queries. The occurrence handle parameter is obtained by traversing the results of a previous query evaluation. 4 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 5 Argument command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context. 5 Condition_Value_Returned SCA$_NORMAL The libraries have been successfully unlocked. 5 Description The SCA$UNLOCK_LIBRARY routine unlocks all the physical libraries in the current virtual library list so that they can be modified. 3 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. 3 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. 3 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. 3 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 3 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. 3 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. 3 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. 3 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) 3 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. 3 Getting_Started SCA works with many languages. See the subtopics in this section for information about getting started with a specific language. 4 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. 4 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 4 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. 4 BASIC_Attributes_Table The following table lists the SCA symbol classes and their corresponding meanings in BASIC. SCA Symbol Classes and Equivalent BASIC Language Terminology SCA Term BASIC Term Explanation Argument Parameter Subprogram formal parameter Component, Record Field component Constant, Constant Literal Exception N/A File File A file used during a compilation Function, Program or For example, PROGRAM, SUB, FUNCTION, Procedure, subprogram DEF, PICTURE Program, Routine, Subroutine Generic N/A Keyword Keyword A PDF keyword Label Label A line number or statement label Macro N/A Module, N/A Package Placeholder Placeholder LSE placeholder Psect Psect MAP or COMMON block Tag Tag PDF tag Task N/A Type Type For example, word, double, decimal, and so forth Unbound N/A Variable Variable The following table lists the SCA occurrence classes and their corresponding meanings in BASIC. SCA Occurrence Classes and Equivalent BASIC Language Terminology SCA Term BASIC Term Explanation Primary Declaration For variables, where they are declared with, for example, DECLARE or MAP statements. For subprograms, where they are defined, that is, where the body of the subprogram is. Associated Declaration EXTERNAL declarations or DECLARE FUNCTION statements Declaration Declaration Either a PRIMARY or ASSOCIATED declaration Read, Fetch Read Write, Store Write Address, Address Actual parameter to LOC function Pointer reference Call Call Command_line Command line A file specified on the command line; For example, BASIC foo.bas Include Include A file specified in a %INCLUDE directive Precompiled N/A Reference Reference Any nondeclaration Explicit Explicit Any symbol declared by the user Implicit Implicit Any symbol declared by the compiler when it sees the first reference Visible Visible A symbol whose name is visible in the source Hidden Hidden A symbol not visible in the source; for example, function return values, implicit declarations Compilation_ For example, a PROGRAM, SUB, or unit FUNCTION The following table lists the SCA domain classes and their corresponding meanings in BASIC. SCA Domain Classes and Equivalent BASIC Language Terminology SCA Term BASIC Term Explanation Inheritable N/A Global Available across modules; for example, through EXTERNAL declarations Predefined Predefined Defined by the language; for example, DECIMAL, PI, CHR$, and so forth Multi_module Predefined, global, and inheritable Module_ Visible only within one module; for specific example, variables 4 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. 4 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 4 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. 4 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 4 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. 4 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 4 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. 4 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 4 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. 4 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 4 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. 4 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 4 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. 4 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. 4 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 3 Glossary 4 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. 4 analysis_data_module A module containing all the information used by SCA for one compilation unit. 4 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." 4 associated_declaration Any declaration which is not a primary declaration. Typically, associated declarations provide information needed by the compiler to refer to an object. 4 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. 4 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 4 call_graph Shows what procedures and functions are called from a subroutine, and all subsequent calls in the call graph. 4 CALLED_BY See the SCA_Topics CALLED_BY help topic. 4 CALLING See the SCA_Topics CALLING help topic. 4 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. 4 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. 4 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. 4 CONTAINED_BY See the SCA_Topics CONTAINED_BY help topic. 4 CONTAINING See the SCA_Topics CONTAINING help topic. 4 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. 4 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. 4 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. 4 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. 4 explicit See expression. 4 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 4 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. 4 hidden See both appearance and hidden modules. 4 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. 4 implicit See expression. 4 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. 4 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 4 library Generic term usually referring to a physical library. 4 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. 4 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. 4 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. 4 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. 4 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 4 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. 4 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. 4 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. 4 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. 4 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. 4 occurrence_selection_expression The expression containing the occurrence class for each occurrence you want to find. 4 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. 4 primary_declaration Any declaration which affects how a particular object, such as a routine or a variable, is implemented. 4 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. 4 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. 4 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. 4 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. 4 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. 4 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. 4 set The occurrences that result from each query. 4 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. 4 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. 4 structured_set A query result which has both occurrences and relationships between occurrences. These are produced by queries which involve relationship functions. 4 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. 4 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. 4 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". 4 symbol_class_selection_expression The expression containing the symbol class for each symbol you want to find. 4 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. 4 TYPED_BY See the SCA_Topics TYPED_BY help topic. 4 TYPING See the SCA_Topics TYPING help topic. 4 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 4 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. 4 visible See both appearance and visible modules. 4 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. 4 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 &*. 3 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. 3 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. 3 Language_Specific_Tables For information about SCA terms and corresponding language- specific terminology, see the tables under the Getting_Started help topic. 3 Libraries 4 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. 4 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. 3 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...]) 3 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. 3 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. 3 Reducing_LOAD_Time There are different means you can use to try to decrease LOAD time. Listed below are a few guidelines that may help you reduce LOAD time: o Loading an SCA library for a software system is a time consuming operation and should be done in batch. Loading more than one module at a time is more efficient than loading modules separately. Using LOAD *.ANA is a common method for loading multiple modules. You use LOAD/DELETE to clean up .ANA files after they are loaded successfully and to use a little less disk space during the load. o With large software systems, it is a good idea to use more than one SCA library and load them all simultaneously. This can lessen the elapsed LOAD time considerably. You should be able to load several libraries simultaneously on a single disk. Additionally, using more than one CPU to do your loads also helps, but SCA loading is mainly I/O intensive. For more information about how to use multiple libraries, see the help subtopics under Libraries. o Once your SCA library starts getting above 20K blocks, you should consider preallocating the library when you create it. SCA currently extends the library file by 1000 blocks at a time, so for large libraries it frequently extends the library. You can preallocate an SCA library by specifying CREATE LIBRARY /SIZE=xxx, where xxx is the size of the library in disk blocks. Use the size of the SCA$EVENT.DAT file in your current SCA library directory as the value to the /SIZE qualifier. o SCA uses a large number of I/Os during LOAD. Loading an SCA library on a heavily used or badly fragmented disk causes the load to be less efficient. You can tell how badly your SCA libraries are fragmented by using the following command: $ DUMP/HEADER/BLOCK=COUNT=0 - _$ DISK:[sca_library_directory]SCA$EVENT.DAT The interesting portion of the output is the Map area. Each retrieval pointer represents a contiguous section on the disk. Because SCA extends SCA libraries 1000 blocks at a time, having a lot of retrieval pointers smaller than this is a strong indication that some defragmentation is needed. 3 Quick_Reference_Card The following page contains a reference of the SCA query language. It is intended to be printed out and used as a Quick Reference Card. ATTRIBUTE SELECTIONS: |RELATIONSHIP FUNCTIONS: | Name Class: |Short form: ---------- |----------- |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: | [ ]...| 3 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. 3 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. 3 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. 3 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. 3 \_(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. 3 @_(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