SCA$NEUTRAL_HELP.HLB  —  SCA Topics
    [SCA]

1  –  Advanced Query Examples

    The examples in this section use the SCA$EXAMPLE library. You are
    encouraged to try these queries using the example library.

    1.  FIND CALLED_BY( END=translit, DEPTH=ALL)

    This query gives the full call tree for TRANSLIT.

    2.  FIND CALLED_BY( END=translit, BEGIN=signal_duplicate, DEPTH=ALL)

    This query returns all the call paths emanating from translit that
    end up calling SIGNAL_DUPLICATE.

    3.  FIND CALLED_BY( translit, DEPTH=ALL, TRACE=(NOT OPEN*))

    This query gives the full call tree for TRANSLIT, but does not
    show any calls from items named OPEN*. Calls to items named OPEN*
    appear in the call tree; however, items which are called by OPEN*
    do not appear. Try the query without the trace expression and
    compare the results when the TRACE is given.

    4.  FIND CALLED_BY( END=translit,
                        BEGIN=(NOT DOMAIN=PREDEFINED and NOT lib$*),
                        DEPTH=ALL )

    This example leaves predefined functions and functions named
    LIB$* out of the call graph. Functions such as CHR and WRITELN
    in Pascal, MAX in FORTRAN, a builtin like _ADAWI in C, and so
    forth are predefined. These functions are defined by the language,
    not the programmer.

    5.  FIND IN( build_table and occ=comp, max_code )

    This example finds all occurrences of MAX_CODE in the module
    BUILD_TABLE. In this case, module has the same meaning as it
    does in SHOW MODULE. This is the fastest way to limit a query to
    occurrences in a particular module. The first parameter to the IN
    function tells SCA in what container to look. The "and occ=comp"
    part of the query ensures that the BUILD_TABLE you are looking
    in is one of the modules displayed by SHOW MODULE, rather than
    something else.

    The second parameter to the IN function tells SCA what to look
    for. This is faster than specifying the following:

          FIND IN( build_table and occ=comp ) and max_code

    Both queries in this example produce the same result.

    Routines Used in a Module But Declared Elsewhere

    In this example, you find functions that are used in a given
    module but have their primary declaration in some other module.
    This example is a multistep process that makes use of previous
    queries. Each query in this section is numbered so that you can
    refer to a specific query. If you refer to a query, adjust the
    query name (for example, where @1 is used) to refer to the query
    name you have created.

    1.  FIND IN( translit and occurrence=compilation_unit, -
             symbol=function and domain=(global,inheritable) )

    This query finds all occurrences of functions, either declarations
    or references, in the module TRANSLIT.

    You use "domain=(global,inheritable)" to limit the query only
    to occurrence in which you are interested. Only global and
    inheritable symbols can be imported because module-specific
    symbols are from the same module, and predefined symbols come
    from the language. Next, you have to remove any functions that
    have their primary declaration in the module.

    2.  FIND @1 AND NOT EXPAND( @1 and occurrence=primary )

    This query removes any functions that have a primary declaration
    in the module TRANSLIT. What remains are those global or
    inheritable functions that do not have a primary declaration in
    TRANSLIT.

    The EXPAND function in this query can be evaluated efficiently
    by SCA. The parameter to EXPAND, @1 and occurrence=primary, can
    be evaluated by looking at the result of query 1, so SCA does not
    have to use the SCA library. Because the overall query does @1 AND
    ..., everything in the result is present in the result of query 1.
    All we are doing is removing occurrences. In this case, SCA can
    evaluate the whole query expression by looking at the result of
    query 1 and does not have to use the SCA library.

    Items Declared In a Module But Not Used Anywhere In the Module

    In this example, you find occurrences of functions or variables
    that are declared in a module but are not used in the module. This
    example is a multistep process that makes use of previous queries.
    The numbers by each query are used to refer to it later. If you
    refer to a query, adjust the query name (for example, where @1 is
    used) to refer to the query names you have created.

    1.  FIND IN( translit and occurrence=compilation_unit, -
                 symbol=(function, variable) )

    This query finds all occurrences of functions or variables, either
    declarations or references, in the module TRANSLIT.

    2.  FIND @1 AND NOT EXPAND( @1 and occurrence=reference )

    This query removes from our first query any functions or variables
    that have a reference in the module TRANSLIT. What remains are
    those functions or variables that are not used anywhere in the
    module.

    The EXPAND function in this query can be evaluated efficiently
    by SCA. The parameter to EXPAND, @1 and occ=reference, can be
    evaluated just by looking at the result of query 1, so SCA does
    not have to use the SCA library. Because the overall query does
    @1 AND ..., everything in the result is present in the result of
    query 1. All we are doing is removing items. In this case, SCA can
    evaluate the whole query expression by looking at the result of
    query 1, and does not have to use the SCA library.

    Finding Unused Functions

    This example finds functions or subroutines that are never used.
    It provides several ways of solving the problem. Some of these are
    easy to understand, but can be very slow on larger SCA libraries.
    The more complex ones are intended to improve performance on
    larger SCA libraries. They do not have a significant impact on
    smaller libraries.

    The first example finds unused functions only. Note that instead
    of saying "occurrence=call" to find functions that are called, you
    specify "occurrence=reference" to find functions that are used at
    all. The query is as follows:

      FIND symbol=function AND occurrence=primary -
          AND NOT EXPAND( symbol=function and occurrence=reference )

    On the SCA$EXAMPLE library, this query works well because it is
    a small library. On a larger library, it may be too slow. To
    evaluate this query, SCA must first evaluate "symbol=function
    and occurrence=primary." It must then evaluate "symbol=function
    and occurrence=reference" before doing any additional processing.
    In this case, SCA has to do twice what is essentially the same
    work. Also, SCA does not discard information about functions that
    are referenced until the end, so it uses a lot of memory.

    Using Previous Query Results to Find Unused Functions Faster

    The next example also finds unused functions. However, it uses
    previous query results, so the work is done only once. For this
    reason, it is faster than the previous example. It also uses
    somewhat less memory, but still not enough to make a difference on
    a large library.

      FIND symbol=function and occurrence=(primary,reference)

    In the previous query, we find all the occurrences that we want to
    use. We ignore the associated declarations at this point because
    they are not essential to the query.

    Next, we must select those functions that are not used as in the
    following query:

      FIND @1 AND occurrence=primary -
           AND NOT EXPAND( @1 AND occurrence=reference )

    This query removes from the list of functions in our system any
    that are referenced, leaving only unreferenced functions. Because
    you are using a previous query with all the information in it,
    SCA does not have to access the SCA library, and performance is
    generally faster.

    However, on a large library, this may still be slow. The reason
    for this is that it ends up keeping a list of all the functions
    and all their references in memory.

    Using Iteration to Find Unused Functions Faster

    This is the most complex example. It includes some repetitive
    parts that the query language does not provide directly. You
    can do these using the callable interface, or by writing a .COM
    procedure, or you can do the repetitive parts manually. This is
    also the fastest form of the example and uses less memory.

    Basically, you are going to split up the work into smaller pieces
    to avoid having to keep everything in memory at the same time. In
    this example, you process one module at a time, so you need to get
    a list of modules first. You can do this by entering the following
    query:

    1. FIND occurrence=compilation_unit

       In the next step, you have to loop through each of the
       occurrences found in step 1. This part cannot be done directly
       using the query language. You can do this using one of the
       following methods:

       o  Do this manually, stepping through the occurrences in the
          query one by one, and using INDICATED() in the following
          queries where module_name is specified.

       o  Use the /DISPLAY options to specify only the name of each
          occurrence found, capture the result in a file, and write
          a command procedure to loop over the names. In this case,
          you use "module_name and occurrence=compilation_unit" in the
          following queries where module_name is specified.

       o  Use the callable interface. By writing a small program
          using the callable interface, you can do the loop relatively
          easily, using SCA$GET_OCCURRENCE and SCA$SELECT_OCCURRENCE.

       In any case, you repeat the following steps for each of the
       modules found in step 1.

    2. FIND IN( module_name, symbol=function and occurrence=primary )

       This step finds primary declarations of functions in the
       current module. You want only primary declarations at this
       stage because there may be some calls in other modules. In the
       next step, you find any references to those functions:

    3. FIND EXPAND( @2 )

       This finds everything you need. At this point, what you do is
       very similar to what you did for the examples in the previous
       section.

    4. FIND @3 and occurrence=primary -
            AND NOT EXPAND( @3 and occurrence=reference )

       This finds those functions in a particular module that are not
       referenced anywhere. Steps 2 through 4 must be repeated for
       each module.

2  –  Basic Query Concepts

    This section covers some of the basic concepts underlying SCA
    queries.

    You may want to have a hardcopy of this section. The directions
    for producing a hardcopy are as follows:

    1. Place the contents of Basic_Query_Concepts in a printable file
       by typing the following command at the DCL command line:

         $ HELP/OUTPUT=BASIC_QUERY_CONCEPTS.TXT -
         _$ SCA SCA_Topics Basic_Query_Concepts

    2. Print BASIC_QUERY_CONCEPTS.TXT from the DCL command line as
       follows:

         $ PRINT BASIC_QUERY_CONCEPTS.TXT

    What Queries Are

    An SCA library is a collection of information about your source
    code. This includes information, such as the names and locations
    of all variables in your code, all the places where routines
    are called and what their arguments are, and many other kinds
    of information.

    Issuing a query is the process of selecting some of this
    information from the library. By giving a query expression with
    the FIND command, you specify exactly what information you want to
    retrieve from the library.

    Occurrences

    An occurrence is any instance of an entity in your program. An
    entity can be any language construct, such as a variable, a
    routine, or a constant. To further clarify this, consider the
    following code fragment (not written in a particular language):

      1   MODULE myprog;
      2
      3   VAR i,j;
      4
      5   ROUTINE foo()
      6   BEGIN
      7       i = 5;
      8       j = i;
      9   END;
      10  END;

    The code contains four entities (myprog, foo, i, j). There is one
    occurrence each of the module myprog, and the routine foo. The
    variable i, however, has three occurrences, and the variable j has
    two.

    Attribute Selection

    Attribute selection is a query that selects occurrences based
    on certain attributes. For example, you can have SCA return all
    occurrences in which the name attribute is XYZ. The following
    sections list the attributes used for selection.

    NAME Attribute

    Generally, you think of entities in you program as having
    only a name. In fact, the name of an entity is only one of its
    attributes. What you are doing when you give the basic query FIND
    X, is asking for all occurrences in the library that have the name
    attribute X. (The query FIND X is equivalent to the query FIND
    NAME=X. NAME= is the default attribute, so it may be omitted.)

    SYMBOL_CLASS Attribute

    The symbol class attribute describes an occurrence in terms
    of language constructs. In the previous example, myprog is a
    MODULE, foo is a ROUTINE, and i and j are variables. Thus, you
    could ask SCA to find things based on the symbol class only. For
    example, you can find all the routines in the library by giving
    the following query: FIND SYMBOL_CLASS=ROUTINE

    Note that MODULE, ROUTINE, and VARIABLE are SCA keywords for
    symbol classes. Because different languages use different
    terminology, there is a need to understand how the SCA language-
    independent terms relate to the language-specific terms. We have
    provided tables to help you match the SCA terms to the specific
    language constructs for all the languages that support SCA. See
    the Getting_Started help subtopics for specific languages.

    OCCURRENCE Attribute

    The occurrence class attribute allows you to select occurrences
    based on attributes specific to the occurrence. In the previous
    example, on line 3 the occurrence of the variable i has an
    occurrence class of PRIMARY. On line 7, the occurrence has
    an occurrence class of WRITE, and on the following line, its
    occurrence class is READ. To find all entities that are declared
    in your system, specify the following query:

    FIND OCCURRENCE=PRIMARY

    Note that as with symbol classes, there is a need to understand
    the relationship between the SCA occurrence class keywords and
    the equivalent language terminology. See the Getting_Started help
    subtopics for specific languages.

    FILE_SPEC Attribute

    Another attribute of all occurrences is the name of the file in
    which they occur. If the previous example program was in a file
    called MYPROG.BAR, then the following query would return all the
    occurrences found in the file; in this case, all occurrences of
    myprog, foo, i, and j:

    FIND FILE_SPEC="MYPROG.BAR"

    SYMBOL DOMAIN Attribute

    The domain of an entity defines the scope within the source over
    which the entity is known. Variables or routines, for example,
    may be local to a particular module, or they might be known to all
    modules in a system. To find all occurrences of entities that are
    known throught your system, specify the following query:

    FIND DOMAIN=GLOBAL

    See the Getting_Started help subtopics for specific languages.

    Basic Queries

    You have already seen examples of the most basic type of query,
    that is a query based on the selection of just one attribute.
    These examples are:

    FIND X
    FIND SYMBOL=ROUTINE
    FIND OCCURRENCE=PRIMARY
    FIND DOMAIN=GLOBAL
    FIND FILE_SPEC="MYPROG.BAR"

    Each of these queries results in a set of occurrences. Often,
    the result of such a query contains more information than you
    really want. You can explicitly indicate the result you want by
    specifying multiple attributes and combining them by using set
    operations. For example, if you only want the ROUTINES named
    X (rather than all items named X or all routines), specify the
    following query expression:

    FIND X AND SYMBOL=ROUTINE

    In the previous example, the set operator AND was used to take the
    intersection of the two sets. The other set operators available
    are OR, XOR, and NOT. In this manner, you can combine attribute
    selection expressions using multiple set operators. For example:

    FIND (X OR Y ) AND SYMBOL=ROUTINE AND OCCURRENCE=CALL

    This query finds all call references to routines named X or Y.

    Relationship Queries

    You have already learned how to select occurrences based on
    their attributes. The following section describes how to select
    occurrences based on their relationship with other occurrences.

    Calls Relationship

    The most common of these relationships is the calls relationship.
    SCA provides two functions: CALLING and CALLED_BY. With these
    functions, you can display the call tree structure of your
    program. The most basic format of the query expression is as
    follows:

    FIND CALLED_BY FOO

    In this example, the result shows a structured display of all the
    routines that FOO directly calls. You can also display routines
    that call FOO as follows:

    FIND CALLING FOO

    The previous two queries answer the questions, "Who is called by
    FOO?" and, "Who is calling FOO?" respectively.

    The full syntax of the relationship functions is complex, and
    each relationship function is described in more detail under SCA_
    Topics. Without explaining why the parentheses are necessary,
    and emphasizing that the order of parameters is important, the
    following examples shows one more useful feature of relationship
    functions. It is possible to get a call tree of arbitrary depth by
    giving the following query:

    FIND CALLED_BY (FOO, DEPTH=ALL )

    This returns a display showing not only the routines called
    directly by FOO, but also the routines that they in turn call,
    for all levels. You can replace the keyword ALL with any positive
    integer to limit the depth of the call tree.

    Contains Relationship

    Another relationship available through SCA is the contains
    relationship, which is obtained through the CONTAINING and
    CONTAINED_BY functions. These functions have the same syntax as
    the calls functions.

    The CONTAINED_BY function returns all entities logically contained
    within the given parameter. For example, the query FIND CONTAINED
    FOO returns two occurrences of i and one occurrence of j, in the
    code fragment that follows:

      1   MODULE myprog;
      2
      3   VAR i,j;
      4
      5   ROUTINE foo()
      6   BEGIN
      7       i = 5;
      8       j = i;
      9   END;
      10  END;

    Similarly, the following query returns the occurrence of the
    module MYPROG:

    FIND CONTAINING FOO

    Types Relationship

    The types relationship consists of the two functions TYPING
    and TYPED_BY. These functions also have the same syntax as the
    previous functions. The TYPED_BY function returns type trees. This
    is useful if there are many user-defined types in your system,
    particularly if they are complex record structures. The TYPING
    function returns the type of its argument.

    For more information about all the relationship functions, see the
    help topic for each relationship.

3  –  Building An SCA Library

    To create your own SCA library, you must first create a library
    directory for it. Using your personal directory, type the
    following command to create a subdirectory for a local SCA
    library:

      $ CREATE/DIRECTORY [.LIB1]

    Once you have a directory in which to create a library, enter the
    following command to SCA to create a library:

      $ SCA CREATE LIBRARY [.LIB1]

    You now have an empty SCA library. To add a module to the SCA
    library, you must first compile your source code.

    Add the /ANALYSIS_DATA qualifier when you use a supported
    compiler. For example:

      $  CC/ANALYSIS_DATA myfile.c

    This produces the file MYFILE.ANA that you can load into your SCA
    library either from LSE or standalone SCA. To load the .ANA file
    and show the new module, type the following commands:

      SCA> LOAD myfile.ANA

      SCA> SHOW MODULE

    You will see that the new module has been loaded into the library,
    and you will now be able to query that library.

    For more information, see the help topics for Libraries and
    Reducing_LOAD_Time.

4  –  Callable Routines

4.1  –  SCA$ASYNCH_TERMINATE

    Sets a flag indicating that a CTRL-C has been issued.

    Format

      SCA$ASYNCH_TERMINATE  command_context

4.1.1  –  Argument

 command_context
    type:       $SCA_COMMAND_CONTEXT
    access:     read/write
    mechanism:  by reference

    SCA command context value.

4.1.2  –  Condition Value Returned

    SCA$_NORMAL           Normal successful completion.

4.1.3  –  Description

    The SCA$ASYNCH_TERMINATE routine sets a flag indicating that a
    CTRL-C has been issued.

4.2  –  SCA$CLEANUP

    Shuts down the SCA callable command interface, freeing all dynamic
    memory associated with the interface routines and data structures.

    Format

      SCA$CLEANUP  command_context

4.2.1  –  Argument

 command_context
    type:       $SCA_COMMAND_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA command context value.

4.2.2  –  Condition Value Returned

    SCA$_NORMAL           The SCA callable command interface has been
                          successfully shut down.

4.2.3  –  Description

    The SCA$CLEANUP routine shuts down the SCA callable command
    interface, freeing all dynamic memory associated with the
    interface routines and data structures.

4.3  –  SCA$DO_COMMAND

    Parses an SCA subsystem command and invokes command processing if
    the command is syntactically correct.

    Format

      SCA$DO_COMMAND  command_context,

                      command_string

                      [,parameter_routine]

                      [,continuation_routine]

                      [,continuation_prompt]

                      [,user_argument]

                      [,confirm_routine]

                      [,topic_routine]

                      [,display_routine]

4.3.1  –  Arguments

 command_context
    type:       $SCA_COMMAND_CONTEXT
    access:     read/write
    mechanism:  by reference

    SCA command context value.

 command_string
    type:       character string
    access:     read only
    mechanism:  by descriptor

    An SCA subsystem command.

 parameter_routine
    type:       procedure
    access:     read only
    mechanism:  by reference

    Routine that prompts for required parameters. You can specify
    LIB$GET_INPUT or a compatible routine. If a routine address of
    zero (0) is specified, commands with missing parameters fail and
    display a CLI error message.

 continuation_routine
    type:       procedure
    access:     read only
    mechanism:  by reference

    Routine that prompts for the remainder of a continued command
    (i.e., a command that ends with a hyphen). You can specify
    LIB$GET_INPUT or a compatible routine.

 continuation_prompt
    type:       character string
    access:     read only
    mechanism:  by descriptor

    Command continuation prompt string (e.g., SCA> ).

 user_argument
    type:       longword
    access:     read only
    mechanism:  by reference

    User-specified value to be passed to any action routine (other
    than CLI prompt routines) called by this routine.

 confirm_routine
    type:       procedure
    access:     read only
    mechanism:  by value

    Command confirmation prompt routine to be used by commands that
    support a /CONFIRM qualifier. You can specify SCA$GET_INPUT or
    a compatible routine. If this argument is omitted, the /CONFIRM
    qualifier is not supported.

 topic_routine
    type:       procedure
    access:     read only
    mechanism:  by value

    Help topic prompt routine. You can specify LIB$GET_INPUT or a
    compatible routine. If this routine returns an error, command
    processing is terminated. If this argument is omitted, no help
    prompting is performed.

 display_routine
    type:       procedure
    access:     read only
    mechanism:  by value

    Routine to be called to display one line of command output. You
    can specify SCA$PUT_OUTPUT or a compatible routine. If this
    routine returns an error, command processing is terminated. If
    this argument is omitted, no display routine is called.

4.3.2  –  Condition Values Returned

    All SCA condition
    values and many
    system values.

4.3.3  –  Description

    The SCA$DO_COMMAND routine parses an SCA subsystem command
    and invokes command processing if the command is syntactically
    correct.

4.4  –  SCA$GET_ATTRIBUTE

    Gets a handle to an attribute of an entity.

    Format

      SCA$GET_ATTRIBUTE  entity,

                         attribute_kind,

                         attribute_handle,

                         [,iteration_context]

4.4.1  –  Arguments

 entity
    type:       $SCA_HANDLE
    access:     read only
    mechanism:  by reference

    An SCA entity handle describing the entity or relationship whose
    attributes are being obtained.

 attribute_kind
    type:       $SCA_ATTRIBUTE_KIND
    access:     read only
    mechanism:  by reference

    The kind of attribute to be obtained.

    Any attribute-kind can be specified on this routine.

 attribute_handle
    type:       $SCA_HANDLE
    access:     write only
    mechanism:  by reference

    An SCA attribute handle that is to describe the obtained
    attribute.

 iteration_context
    type:       $SCA_ITERATION_CONTEXT
    access:     read/write
    mechanism:  by reference

    Optional. The iteration-context. This longword must contain zero
    on the first call to this routine for a particular iteration. This
    routine uses the longword to maintain the iteration context. The
    caller must not change the contents of the longword.

4.4.2  –  Condition Values Returned

    SCA$_NORMAL           An attribute has been successfully returned.

    SCA$_NONE             Warning. An attribute has not been returned.
                          Either there are no such attributes at
                          all in the entity or there are no more
                          attributes.

4.4.3  –  Description

    The SCA$GET_ATTRIBUTE routine gets a handle to an attribute of an
    entity.

    If the iteration_context parameter is not specified, then
    this routine finds the first attribute of the specified kind
    (attribute_kind) and updates attribute_handle to describe that
    attribute.

    In general, several attributes can be associated with a particular
    entity. With this routine you can find all of those attributes by
    using the iteration_context parameter.

4.5  –  SCA$GET_ATTRI_KIND_T

    Gets an attribute kind.

    Format

      SCA$GET_ATTRI_KIND_T  attribute_handle,

                            attribute_kind

4.5.1  –  Arguments

 attribute_handle
    type:       $SCA_HANDLE
    access:     read only
    mechanism:  by reference

    An SCA handle describing an attribute whose attribute-kind is to
    be obtained.

 attribute_kind
    type:       character string
    access:     write only
    mechanism:  by descriptor

    The kind of the attribute.

4.5.2  –  Condition Value Returned

    SCA$_NORMAL           An attribute kind has been successfully
                          returned.

4.5.3  –  Description

    The SCA$GET_ATTRI_KIND_T routine returns the kind of any attribute
    as a character string.

4.6  –  SCA$GET_ATTRI_VALUE_T

    Gets an attribute value.

    Format

      SCA$GET_ATTRI_VALUE_T  handle, attribute_value

                             [,attribute_kind]

4.6.1  –  Arguments

 handle
    type:       $SCA_HANDLE
    access:     read/write
    mechanism:  by reference

    An SCA attribute handle describing either an attribute or an
    entity whose value is to be obtained.

 attribute_value
    type:       character string
    access:     read/write
    mechanism:  by descriptor

    The (string) value of the attribute being selected.

 attribute_kind
    type:       $SCA_ATTRIBUTE_KIND
    access:     read/write
    mechanism:  by reference

    Optional. The kind of attribute to be obtained.

4.6.2  –  Condition Values Returned

    SCA$_NORMAL           An attribute value has been successfully
                          returned.

    SCA$_NONE             Warning. An attibute-value has not been
                          returned. There are no such attributes in
                          the entity. This condition can be returned
                          only if this routine is processing an
                          entity.

4.6.3  –  Description

    The SCA$GET_ATTRI_VALUE_T routine returns the value of any
    attribute as a character string.

    If the handle describes an attribute, then this routine returns
    the value of that attribute. In this case, the attribute_kind
    parameter must not be specified.

    If the handle describes an entity, then this routine returns the
    value of the first attribute of that entity that is of the kind
    specified by the attribute_kind  parameter. In this case, the
    attribute_kind parameter must be specified.

    If you want to get more than one attribute value of a particular
    kind for an entity, you must use the routine SCA$GET_ATTRIBUTE.
    This applies only to the attribute kinds SCA$K_ATTRI_NAME and
    SCA$K_ATTRI_ALL.

    The value of any kind of attribute can be returned by this
    routine, except for SCA$K_ATTRI_ALL. This routine will convert to
    character string those attributes whose data type is not character
    string.

    This routine does not accept the attribute-kind SCA$K_ATTRI_ALL as
    the value of the attribute_kind parameter. It is not meaningful to
    get just the first attribute without regard to attribute-kind.

4.7  –  SCA$GET_CURRENT_QUERY

    Gets the name of the current query in the given command context.

    Format

      SCA$GET_CURRENT_QUERY  command_context,

                             query_name

4.7.1  –  Arguments

 command_context
    type:       $SCA_COMMAND_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA command context.

 query_name
    type:       character string
    access:     write only
    mechanism:  by descriptor

    The name of the current query in the context of the given command
    context.

4.7.2  –  Condition Values Returned

    SCA$_NORMAL           The name of the current query has been
                          successfully retrieved.

4.7.3  –  Description

    The SCA$GET_CURRENT_QUERY routine gets the name of the current
    query in the given command context.

4.8  –  SCA$GET_INPUT

    Gets one record of ASCII text from the current controlling input
    device specified by SYS$INPUT.

    Format

      SCA$GET_INPUT  get_string,

                     [,prompt_string]

                     [,output_length]

                     [,user_argument]

4.8.1  –  Arguments

 get_string
    type:       character string
    access:     write only
    mechanism:  by descriptor

    Buffer to receive the line read from SYS$INPUT. The string is
    returned by a call to STR$COPY_DX.

 prompt_string
    type:       character string
    access:     read only
    mechanism:  by descriptor

    Prompt message that is displayed on the controlling terminal. A
    valid prompt consists of text followed by a colon (:), a space,
    and no carriage-return/line-feed combination. The maximum size
    of the prompt message is 255 characters. If the controlling input
    device is not a terminal, this argument is ignored.

 output_length
    type:       word
    access:     write only
    mechanism:  by reference

    Word to receive the actual length of the GET-STRING line, not
    counting any padding in the case of a fixed string. If the input
    line was truncated, this length reflects the truncated string.

 user_argument
    type:       _UNSPECIFIED
    access:     read only
    mechanism:  by reference

    User-specified value that was passed to the routine that called
    this action routine.

4.8.2  –  Condition Values Returned

    SCA$_NORMAL           An input line was returned.

    Failure completion
    code from LIB$GET_
    INPUT.

4.8.3  –  Description

    The SCA$GET_INPUT routine gets one record of ASCII text from the
    current controlling input device specified by SYS$INPUT.

4.9  –  SCA$GET_OCCURRENCE

    Returns an occurrence from the query specified by the query_name
    argument.

    Format

      SCA$GET_OCCURRENCE  command_context,

                          query_name,

                          occurrence

4.9.1  –  Arguments

 command_context
    type:       $SCA_COMMAND_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA command context.

 query_name
    type:       character string
    access:     read only
    mechanism:  by descriptor

    The name of the query in the context of the command context.

 occurrence
    type:       $SCA_HANDLE
    access:     read/write
    mechanism:  by reference

    An SCA occurrence handle that describes an occurrence.

4.9.2  –  Condition Values Returned

    SCA$_NORMAL           An occurrence has been successfully
                          returned.

    SCA$_NEWNAME          An occurrence has been successfully
                          returned. This occurrence has a different
                          name from the occurrence that was returned
                          by the previous call to this routine with
                          this query context. This condition implies
                          that this new occurrence is also of a
                          different symbol.

    SCA$_NEWITEM          An occurrence has been successfully
                          returned. This new occurrence is of a
                          different symbol from the occurrence that
                          was returned by the previous call to this
                          routine with this query context.

    SCA$_NOMORE           Warning. An occurrence has not been
                          returned. The traversal of the query result
                          has been exhausted.

4.9.3  –  Description

    The SCA$GET_OCCURRENCE routine returns an occurrence from the
    query specified by the query_name argument.

    If the occurrence handle supplied is zero, the routine returns
    a handle to the first occurrence in the query represented by the
    argument query_name. If the occurrence handle supplied on input
    represents a valid occurrence, the routine returns a handle to
    the next occurrence in the query result. In order to be valid, the
    occurrence handle supplied on input must refer to an occurrence in
    the query represented by the argument query_name.

    The query name supplied is interpreted in the context of the
    command context identified by the argument command_context.

    Note that the order of retrieval of the occurrences is undefined.

4.10  –  SCA$INITIALIZE

    Initializes the SCA callable command interface.

    Format

      SCA$INITIALIZE  command_context

4.10.1  –  Argument

 command_context
    type:       $SCA_COMMAND_CONTEXT
    access:     write only
    mechanism:  by reference

    SCA command context value to be initialized. This value is passed
    as an argument to other SCA$xxx routines.

4.10.2  –  Condition Value Returned

    SCA$_NORMAL           The SCA callable command interface has been
                          successfully initialized.

4.10.3  –  Description

    The SCA$INITIALIZE routine initializes the SCA callable command
    interface.

4.11  –  SCA$LOCK_LIBRARY

    Locks all the physical libraries in the current virtual library
    list so that they cannot be modified.

    Format

      SCA$LOCK_LIBRARY  command_context

4.11.1  –  Argument

 command_context
    type:       $SCA_COMMAND_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA command context.

4.11.2  –  Condition Value Returned

    SCA$_NORMAL           The libraries have been successfully locked.

4.11.3  –  Description

    The SCA$LOCK_LIBRARY routine locks all the physical libraries in
    the current virtual library list so that they cannot be modified.

4.12  –  SCA$PUT_OUTPUT

    Writes a record to the current controlling output device specified
    by SYS$OUTPUT.

    Format

      SCA$PUT_OUTPUT  string,

                      user_argument

4.12.1  –  Arguments

 string
    type:       character string
    access:     read only
    mechanism:  by descriptor

    String to be written to SYS$OUTPUT. You can concatenate one or
    more additional character strings with the primary string to form
    a single output record. You can specify a maximum of 20 strings.
    The maximum resulting record length is 255 characters.

 user_argument
    type:       _UNSPECIFIED
    access:     read only
    mechanism:  by reference

    User-specified value that was passed to the routine that called
    this action routine.

4.12.2  –  Condition Values Returned

    SCA$_NORMAL           The string was successfully written to
                          SYS$OUTPUT.

    Failure completion
    from the RMS
    $PUT service.

4.12.3  –  Description

    The SCA$PUT_OUTPUT routine writes a record to the current
    controlling output device specified by SYS$OUTPUT.

4.13  –  SCA$QUERY_CLEANUP

    Cleans up an SCA query context, freeing all dynamic memory
    associated with the query.

    Format

      SCA$QUERY_CLEANUP  query_context

4.13.1  –  Argument

 query_context
    type:       $SCA_QUERY_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA query context to be cleaned up.

4.13.2  –  Condition Value Returned

    SCA$_NORMAL           The query context has been successfully
                          cleaned up.

4.13.3  –  Description

    The SCA$QUERY_CLEANUP routine cleans up an SCA query context,
    freeing all dynamic memory associated with the query.

    This routine will become obsolete in a future version of SCA.

4.14  –  SCA$QUERY_COPY

    Copies a query from SRC_QUERY_CONTEXT to DST_QUERY_CONTEXT.

    Format

      SCA$QUERY_COPY  src_query_context,

                      dst_query_context

4.14.1  –  Arguments

 src_query_context
    type:       $SCA_QUERY_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA query context that describes the query to be copied.

 dst_query_context
    type:       $SCA_QUERY_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA query context into which the query is to be copied.

4.14.2  –  Condition Value Returned

    SCA$_NORMAL           The query expression has been successfully
                          copied.

4.14.3  –  Description

    The SCA$QUERY_COPY routine copies a query from SRC_QUERY_CONTEXT
    to DST_QUERY_CONTEXT. This will copy whatever is in SRC_QUERY_
    CONTEXT, whether that is a question, or a question and a result.

    This routine will become obsolete in a future version of SCA.

4.15  –  SCA$QUERY_FIND

    Finds the occurrences that match the query expression specified by
    QUERY_CONTEXT.

    Format

      SCA$QUERY_FIND  query_context

4.15.1  –  Argument

 query_context
    type:       $SCA_QUERY_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA query context that describes a query expression to be
    evaluated.

4.15.2  –  Condition Values Returned

    SCA$_NORMAL           The query expression has been successfully
                          evaluated.

    SCA$_NOOCCUR          No occurrences match the query expression.

    SCA$_RESULTEXISTS     The query already has a result prior to this
                          call.

4.15.3  –  Description

    The SCA$QUERY_FIND routine finds the occurrences that match the
    query expression specified by QUERY_CONTEXT.

    This routine will become obsolete in a future version of SCA.

4.16  –  SCA$QUERY_GET_ATTRIBUTE

    Gets a handle to an attribute of an entity.

    Format

      SCA$QUERY_GET_ATTRIBUTE  entity,

                               attribute_kind,

                               attribute_handle,

                               [,iteration_context]

4.16.1  –  Arguments

 entity
    type:       $SCA_HANDLE
    access:     read only
    mechanism:  by reference

    An SCA entity handle describing the entity or relationship whose
    attributes are being obtained.

 attribute_kind
    type:       $SCA_ATTRIBUTE_KIND
    access:     read only
    mechanism:  by reference

    The kind of attribute to be obtained.

    Any attribute-kind can be specified on this routine.

 attribute_handle
    type:       $SCA_HANDLE
    access:     write only
    mechanism:  by reference

    An SCA attribute handle that is to describe the obtained
    attribute.

 iteration_context
    type:       $SCA_ITERATION_CONTEXT
    access:     read/write
    mechanism:  by reference

    Optional. The iteration-context. This longword must contain zero
    on the first call to this routine for a particular iteration. This
    routine uses the longword to maintain the iteration context. The
    caller must not change the contents of the longword.

4.16.2  –  Condition Values Returned

    SCA$_NORMAL           An attribute has been successfully returned.

    SCA$_NONE             Warning. An attribute has not been returned.
                          Either there are no such attributes at
                          all in the entity or there are no more
                          attributes.

4.16.3  –  Description

    The SCA$QUERY_GET_ATTRIBUTE routine gets a handle to an attribute
    of an entity.

    If the iteration_context parameter is not specified, then
    this routine finds the first attribute of the specified kind
    (attribute_kind) and updates attribute_handle to describe that
    attribute.

    In general, several attributes can be associated with a particular
    entity. With this routine you can find all of those attributes by
    using the iteration_context parameter.

    This routine will become obsolete in a future version of SCA. The
    SCA$GET_ATTRIBUTE routine supersedes this routine.

4.17  –  SCA$QUERY_GET_ATTRI_KIND_T

    Gets an attribute kind.

    Format

      SCA$QUERY_GET_ATTRI_KIND_T  attribute_handle,

                                  attribute_kind

4.17.1  –  Arguments

 attribute_handle
    type:       $SCA_HANDLE
    access:     read only
    mechanism:  by reference

    An SCA handle describing an attribute whose attribute-kind is to
    be obtained.

 attribute_kind
    type:       character string
    access:     write only
    mechanism:  by descriptor

    The kind of the attribute.

4.17.2  –  Condition Value Returned

    SCA$_NORMAL           An attribute kind has been successfully
                          returned.

4.17.3  –  Description

    The SCA$QUERY_GET_ATTRI_KIND_T routine returns the kind of any
    attribute as a character string.

    This routine will become obsolete in a future version of SCA. The
    SCA$GET_ATTRI_KIND_T routine supersedes this routine.

4.18  –  SCA$QUERY_GET_ATTRI_VALUE_T

    Gets an attribute value.

    Format

      SCA$QUERY_GET_ATTRI_VALUE_T  handle, attribute_value

                                   [,attribute_kind]

4.18.1  –  Arguments

 handle
    type:       $SCA_HANDLE
    access:     read/write
    mechanism:  by reference

    An SCA attribute handle describing either an attribute or an
    entity whose value is to be obtained.

 attribute_value
    type:       character string
    access:     read/write
    mechanism:  by descriptor

    The (string) value of the attribute being selected.

 attribute_kind
    type:       $SCA_ATTRIBUTE_KIND
    access:     read/write
    mechanism:  by reference

    Optional. The kind of attribute to be obtained.

4.18.2  –  Condition Values Returned

    SCA$_NORMAL           An attribute value has been successfully
                          returned.

    SCA$_NONE             Warning. An attibute-value has not been
                          returned. There are no such attributes in
                          the entity. This condition can be returned
                          only if this routine is processing an
                          entity.

4.18.3  –  Description

    The SCA$QUERY_GET_ATTRI_VALUE_T routine returns the value of any
    attribute as a character string.

    If the handle describes an attribute, then this routine returns
    the value of that attribute. In this case, the attribute_kind
    parameter must not be specified.

    If the handle describes an entity, then this routine returns the
    value of the first attribute of that entity that is of the kind
    specified by the attribute_kind  parameter. In this case, the
    attribute_kind parameter must be specified.

    If you want to get more than one attribute value of a particular
    kind for an entity, you must use the routine SCA$QUERY_GET_
    ATTRIBUTE. This applies only to the attribute kinds SCA$K_ATTRI_
    NAME and SCA$K_ATTRI_ALL.

    The value of any kind of attribute can be returned by this
    routine, except for SCA$K_ATTRI_ALL. This routine will convert to
    character string those attributes whose data type is not character
    string.

    This routine does not accept the attribute-kind SCA$K_ATTRI_ALL as
    the value of the attribute_kind parameter. It is not meaningful to
    get just the first attribute without regard to attribute-kind.

    This routine will become obsolete in a future version of SCA. The
    SCA$GET_ATTRI_VALUE_T routine supersedes this routine.

4.19  –  SCA$QUERY_GET_NAME

    Returns the name of a query.

    Format

      SCA$QUERY_GET_NAME  query_context,

                          query_name

4.19.1  –  Arguments

 query_context
    type:       $SCA_QUERY_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA query context whose name is to be obtained.

 query_name
    type:       character string
    access:     write only
    mechanism:  by descriptor

    The name of the query.

4.19.2  –  Condition Value Returned

    SCA$_NORMAL           The query name has been successfully
                          returned.

4.19.3  –  Description

    The SCA$QUERY_GET_NAME routine returns the name of a query.

    This routine will become obsolete in a future version of SCA.

4.20  –  SCA$QUERY_GET_OCCURRENCE

    Gets the next occurrence in the query result that is specified as
    a query_context argument.

    Format

      SCA$QUERY_GET_OCCURRENCE  query_context,

                                entity_handle

4.20.1  –  Arguments

 query_context
    type:       $SCA_QUERY_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA query context whose occurrences are to be obtained.

 entity_handle
    type:       $SCA_HANDLE
    access:     read/write
    mechanism:  by reference

    An SCA entity handle that describes an entity.

4.20.2  –  Condition Values Returned

    SCA$_NORMAL           An occurrence has been successfully
                          returned.

    SCA$_NEWSYMBOL        An occurrence has been successfully
                          returned. This new occurrence is of a
                          different symbol than the occurrence that
                          was returned by the previous call to this
                          routine.

    SCA$_NOMORE           Warning. An occurrence has not been
                          returned. The traversal of the query result
                          has been exhausted.

4.20.3  –  Description

    The SCA$QUERY_GET_OCCURRENCE routine successively returns every
    occurrence in a query result. It provides one pass through all of
    the occurrences.

    This routine will become obsolete in a future version of SCA. The
    SCA$GET_OCCURRENCE routine supersedes this routine.

4.21  –  SCA$QUERY_INITIALIZE

    Initializes an SCA query context.

    Format

      SCA$QUERY_INITIALIZE  command_context,

                            query_context

4.21.1  –  Arguments

 command_context
    type:       $SCA_COMMAND_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA command context.

 query_context
    type:       $SCA_QUERY_CONTEXT
    access:     write only
    mechanism:  by reference

    An SCA query context to be initialized. This value is passed as an
    argument to other SCA query routines (SCA$QUERY_xxx).

4.21.2  –  Condition Value Returned

    SCA$_NORMAL           The query context has been successfully
                          initialized.

4.21.3  –  Description

    The SCA$QUERY_INITIALIZE routine initializes an SCA query context.
    This routine must be called before any other SCA$QUERY_ routines.

    This routine will become obsolete in a future version of SCA.

4.22  –  SCA$QUERY_PARSE

    Parses a query expression command string and sets up a query
    context if the command is syntactically correct.

    Format

      SCA$QUERY_PARSE  query_context, query_expression_string

                       [,query_expression_length]

4.22.1  –  Arguments

 query_context
    type:       $SCA_QUERY_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA query context that is to describe the indicated query
    expression.

 query_expression_string
    type:       character string
    access:     read only
    mechanism:  by descriptor

    A query expression string.

 query_expression_length
    type:       longword
    access:     write only
    mechanism:  by reference

    Optional. Length of the query expression, returned from the
    parser.

4.22.2  –  Condition Values Returned

    SCA$_NORMAL           The query expression string has been
                          successfully parsed.

    SCA$_MORETEXT         Warning. The query expression string has
                          been successfully parsed, but the text
                          following the query expression is not a
                          legal part of the query expression. This
                          condition is returned only if the query_
                          expression_length parameter is specified. If
                          the query_expression_length parmeter is not
                          specified, then this routine insists that
                          the whole query_expression_string argument
                          be a legal query expression; in this case
                          all errors are signaled.

4.22.3  –  Description

    The SCA$QUERY_PARSE routine parses a query expression string and
    sets up a query context if the command is syntactically correct.

    This routine will become obsolete in a future version of SCA.

4.23  –  SCA$QUERY_SELECT_OCCURRENCE

    Creates a query expression that matches a specific entity.

    Format

      SCA$QUERY_SELECT_OCCURRENCE  query_context,

                                   entity_handle

4.23.1  –  Arguments

 query_context
    type:       $SCA_QUERY_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA query context that is to describe a specific entity.

 entity_handle
    type:       $SCA_HANDLE
    access:     read/write
    mechanism:  by reference

    An SCA entity handle that describes the entity that the newly
    defined query context is to match.

4.23.2  –  Condition Value Returned

    SCA$_NORMAL           A query expression has been successfully
                          defined.

4.23.3  –  Description

    The SCA$QUERY_SELECT_OCCURRENCE routine creates a query expression
    that matches a specific entity.

    You use this routine to specify queries based on the results
    of previous queries. The entity_handle parameter is obtained by
    traversing the results of a previous query evaluation.

    Typically, the query context of the entity_handle parameter is
    not the same as the query_context parameter. However, they can be
    the same. If they are the same query context, then that previous
    query is replaced with the query defined by this routine and, as a
    result, entity_handle becomes invalid.

    This routine will become obsolete in a future version of SCA. The
    SCA$SELECT_OCCURRENCE routine supersedes this routine.

4.24  –  SCA$SELECT_OCCURRENCE

    Creates a query that matches a specific occurrence.

    Format

      SCA$SELECT_OCCURRENCE  occurrence,

                             query_name

4.24.1  –  Arguments

 occurrence
    type:       $SCA_HANDLE
    access:     read only
    mechanism:  by reference

    An SCA occurrence handle which describes the occurrence that the
    newly created query is to match.

 query_name
    type:       character string
    access:     write only
    mechanism:  by descriptor

    The name of the newly created query. This query is created in the
    context of the same command context as that in which the input
    occurrence handle is defined.

4.24.2  –  Condition Values Returned

    SCA$_NORMAL           A query expression has been successfully
                          defined.

4.24.3  –  Description

    You use this routine to create new queries based on the results of
    previous queries. The occurrence handle parameter is obtained by
    traversing the results of a previous query evaluation.

4.25  –  SCA$UNLOCK_LIBRARY

    Unlocks all the physical libraries in the current virtual library
    list so that they can be modified.

    Format

      SCA$UNLOCK_LIBRARY  command_context

4.25.1  –  Argument

 command_context
    type:       $SCA_COMMAND_CONTEXT
    access:     read/write
    mechanism:  by reference

    An SCA command context.

4.25.2  –  Condition Value Returned

    SCA$_NORMAL           The libraries have been successfully
                          unlocked.

4.25.3  –  Description

    The SCA$UNLOCK_LIBRARY routine unlocks all the physical libraries
    in the current virtual library list so that they can be modified.

5  –  Callable SCA

    The SCA Callable Interface allows you to use SCA within
    independent application programs. This allows you to integrate SCA
    into alternative user-interfaces and lets you generate specialized
    reports based on SCA information.

    The SCA Callable Interface contains two components. The first is a
    set of routines termed Callable Command Routines, which comprise
    a high-level interface which must always be used, regardless of
    the type of application. This provides a very simple callable
    interface to SCA, which will be sufficient for most applications.

    Callable Command Interface Routines

    o  SCA$ASYNCH_TERMINATE

    o  SCA$CLEANUP

    o  SCA$DO_COMMAND

    o  SCA$GET_INPUT

    o  SCA$INITIALIZE

    o  SCA$LOCK_LIBRARY

    o  SCA$PUT_OUTPUT

    o  SCA$UNLOCK_LIBRARY

    The second component is a set of routines termed Callable
    Query Routines. The Callable Query Routines comprise a lower-
    level interface to the FIND command. Using this interface, an
    application has control over the specification of queries and the
    manipulation of query results.

    Callable Query Initialization/Cleanup Routines

    o  SCA$QUERY_CLEANUP

    o  SCA$QUERY_INITIALIZE

    Callable Query Question Building Routines

    o  SCA$QUERY_PARSE

    o  SCA$QUERY_SELECT_OCCURRENCE

    o  SCA$SELECT_OCCURRENCE

    Callable Query Result Manipulation Routines

    o  SCA$GET_ATTRIBUTE

    o  SCA$GET_ATTRI_KIND_T

    o  SCA$GET_ATTRI_VALUE_T

    o  SCA$GET_OCCURRENCE

    o  SCA$QUERY_GET_ATTRIBUTE

    o  SCA$QUERY_GET_ATTRI_KIND_T

    o  SCA$QUERY_GET_ATTRI_VALUE_T

    o  SCA$QUERY_GET_OCCURRENCE

    Callable Query Miscellaneous Routines

    o  SCA$GET_CURRENT_QUERY

    o  SCA$QUERY_COPY

    o  SCA$QUERY_FIND

    o  SCA$QUERY_GET_NAME

    Message Handling

    The SCA callable interface handles all messages the same way:
    it signals them. If you want control over the display of such
    messages, you must establish a condition handler. Establishing a
    condition handler is optional.

    Rules for Calling SCA Routines

    o  Most SCA routines are not AST-reentrant; therefore, you should
       not call an SCA routine (except SCA$ASYNCH_TERMINATE) from an
       AST routine that may currently be interrupting an SCA routine.

    o  Your program must not disable ASTs.

    o  If your program uses event flags, you must use the OpenVMS RTL
       routines (LIB$RESERVE_EF, LIB$GET_EF, and LIB$FREE_EF) in order
       to coordinate the use of event flags between your program and
       SCA.

    o  Except for SCA$ASYNCH_TERMINATE, do not call SCA from within an
       SCA callback routine or from within a routine that is handling
       a condition signaled by SCA.

    o  Your program must not unwind when handling a condition signaled
       by SCA.

6  –  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

7  –  Getting Started

    SCA works with many languages. See the subtopics in this section
    for information about getting started with a specific language.

7.1  –  Using Ada

    This section contains some basic examples that show what SCA can
    do to help you with your programs. The examples have very little
    explanation. For a more detailed explanation of the underlying
    concepts, see the Basic_Query_Concepts help topic. The remainder
    of this section is written in terms that are specific to Ada
    programs.

    If you want to follow along and try the examples, you will need to
    have an SCA library available. If you do not know how to create
    an SCA library, read the Building_An_SCA_Library help topic. The
    examples use generic variable names (such as 'i'). You will have
    to substitute variable names that exist in your code when trying
    the examples.

    The first example is the easiest query: It lets you find all the
    items in your SCA library named 'i', and shows you all the places
    where they appear (all occurrences  of 'i').

    FIND i

    You can search for any name in this manner, including using
    wildcard characters (for example, FIND i*).

    Suppose you are looking for an occurrence, and you know that
    it occurs in a particular file. The following query finds all
    occurrences of items that are named 'i' but will then limit them
    to those which happen to occur in the file named PROG.ADA.

    FIND i AND FILE_SPEC="PROG.ADA"

    Another typical question one might ask is, "Find all the places
    where this item is assigned to (or read from, called, declared,
    and so forth)." The next example finds all occurrences of items
    that are named 'i', but then limits them to only those occurrences
    where 'i' is assigned a value:

    FIND i AND OCCURRENCE=WRITE

    (SCA understands many occurrence classes other then WRITE. See the
    help subtopics under Getting_Started for tables containing all the
    SCA attributes and their corresponding meanings in Ada.)

    Often, you only want to know where (in what file or package) a
    particular function is, so that you can go to it and edit it.
    You can use the first query (where 'i' will be the name of the
    function) and then look through the output. The output will
    include all occurrences of the function, one of which would be
    its declaration, which you can then select. Or, you can ask SCA to
    limit the search for you by typing the following query:

    FIND i AND OCCURRENCE=PRIMARY

    In SCA terms, a primary declaration is the most significant
    declaration of an item. For an Ada function, this means the body
    of the function, or package, or generic, and so forth. This is in
    contrast to the specification, which is considered an associated
    declaration.

    Another problem you might have is that there are many different
    items in your system having a given name. Some may be variables;
    others may be functions, constants, tasks, and so forth. Suppose
    you want to find only the functions named i. Again, the query
    FIND i will give you what you want, but it will also give you much
    more. It is preferable to issue the following query:

    FIND i AND SYMBOL_CLASS=FUNCTION

    The previous four examples have selected information based on two
    attributes. The last example selected information based on a name
    attribute (in this case, i) and a symbol class attribute (in this
    case, FUNCTION). Note how the attributes are combined using the
    boolean operator AND. In general, you can select items out of your
    library based on any combination of attributes, using AND as well
    as the other logical operators OR, XOR, and NOT.

    The next example shows another primary feature of SCA - the
    ability to display relationships between items. This example shows
    the most common use of this feature. It finds the complete call
    tree (that is, all functions called directly and indirectly) of
    the function named i.

    FIND CALLED_BY (i, DEPTH=ALL)

    If you want to limit the depth of the call tree, replace the
    keyword ALL by any positive integer.

    The final part of this section describes how to go directly to the
    source code once you have issued a query. After issuing the query
    FIND i, for example, you can have an LSE query buffer containing
    something that looks like the following:

      I variable
          ADA_MODULE\60     object declaration
          ADA_MODULE\75     write reference
          ADA_MODULE\79     read reference
          ADA_MODULE\122    read reference
          ADA_MODULE\144    write reference
          ADA_MODULE\146    read, write reference
          ADA_MODULE\149    write reference
          ADA_MODULE\149    read reference
          ADA_MODULE\150    reference
          ADA_MODULE\166    read reference

    The first two lines of this display will be highlighted. The first
    line represents the item you looked for (i), and the rest of the
    lines represent the different places in the code where this item
    occurred (that is, the occurrences of i). By using the up and down
    arrows on your keyboard, or by clicking on an occurrence with your
    mouse, you can choose the occurrence you want to see. Then, all
    you have to do is type CTRL/G (the keyboard equivalent of the GOTO
    SOURCE command) and LSE will bring the source file into a buffer
    and position you at the occurrence you chose.

    To obtain help on the following topics, request help as indicated.

    o  For help on query language, see the Basic_Query_Concepts help
       topic.

    o  For help on libraries, see the Building_An_SCA_Library help
       topic.

7.2  –  Ada Attributes Table

    The following table lists the SCA symbol classes and their
    corresponding meanings in Ada.

    SCA Symbol Classes and Equivalent Ada Language Terminology

    SCA Term       Ada Term       Explanation

    Argument       Formal         A subprogram formal parameter
                   parameter

    Component,     Component      Record components and discriminants
    Field

    Constant,      Constant
    Literal

    Exception      Exception

    File           File           A file used during compilation

    Function,      All
    Procedure,     subprograms,
    Program,       entries,
    Routine,       and ACCEPT
    Subroutine     statements

    Generic        Generic        Generic subprograms or generic
                                  packages

    Keyword        Keyword        PDF keyword tag

    Label          Labels
                   and loop
                   identifiers

    Macro          N/A

    Module,        Packages
    Package

    Placeholder    Placeholder    LSE placeholder

    Psect          N/A

    Tag            Tag            PDF tag

    Task           Task           Task objects

    Type           Type

    Unbound        Unbound        Pragmas and attributes

    Variable       Object

    The following table lists the SCA occurrence classes and their
    corresponding meanings in Ada.

    SCA Occurrence Classes and Equivalent Ada Language Terminology

    SCA Term       Ada Term       Explanation

    Primary        Body           For example, package body

    Associated     Specification  For example, package specification

    Declaration    Declaration    Any declaration, either primary or
                                  associated

    Reference      Reference      Any nondeclaration

    Read, Fetch    Read

    Write, Store   Write

    Address,       N/A
    Pointer

    Call           Call

    Command_line   Command line   A file referred to on the command
                                  line; for example, ADA foo.ada

    Include        N/A

    Precompiled    N/A

    Separate       Separate       Any Ada package or sub-program unit
                                  defined as SEPARATE

    With           With           Any WITH of an Ada package or sub-program
                                  unit

    Explicit       Explicit       An entity that is explicitly
                                  declared. For example,
                                  declarations resulting from generic
                                  instantiations.

    Implicit       Implicit       Any symbol declared by the compiler,
                                  for example a loop name

    Visible        Visible        A symbol whose name is visible in
                                  the source

    Hidden         Hidden         A symbol whose name is not visible
                                  in the source; for example,
                                  anonymous types

    Compilation_   Compilation    Subprogram declaration or body,
    unit           unit           package declaration or body, and so
                                  forth

    Limited        Limited        Any Ada limited private type

    Private        Private        Any Ada private type

    The following table lists the SCA domain classes and their
    corresponding meanings in ADA.

    SCA Domain Classes and Equivalent Ada Language Terminology

    SCA Term       Ada Term       Explanation

    Inheritable                   Objects declared in a package
                                  specification

    Global         N/A

    Predefined     N/A

    Multi_module                  Inheritable, Global and Predefined

    Module_        Module         Objects known to only one module
    specific       specific

7.3  –  Using BASIC

    This section contains some typical examples that illustrate what
    SCA can do to help you with your programs. The examples have very
    little explanation. If you want a more detailed explanation of the
    underlying concepts, see the Basic_Query_Concepts help topic. The
    remainder of this section is written in terms that are specific to
    BASIC programs.

    If you want to follow along and try the examples, you will need to
    have an SCA library available. If you do not know how to create
    an SCA library, read the Building_An_SCA_Library help topic. The
    examples use generic variable names (such as i). You will have to
    substitute variable names that actually exist in your code when
    trying the examples.

    The first example is the easiest query of all: It lets you find
    all the items in your SCA library named i, and shows you all the
    places where they appear (all occurrences of i).

    FIND i

    You can search for any name in this manner, including using
    wildcard characters (for example, FIND i*).

    Now let's say you are looking for an occurrence, and you know
    that it occurs in a particular file. The following query finds all
    occurrences of items that are named i but will then limit them to
    those which happen to occur in the file named 'PROG.BAS'.

    FIND i AND FILE_SPEC="PROG.BAS"

    Another typical question one might ask is "Find all the places
    where this item is assigned to (or read from, called, declared,
    and so forth)." The next example finds all occurrences of items
    that are named i, but then limits them to only those occurrences
    where i is assigned a value.

    FIND i AND OCCURRENCE=WRITE

    (SCA understands many occurrence classes other then WRITE. See the
    help subtopics under Getting_Started for tables containing all the
    SCA attributes and their corresponding meanings in BASIC.)

    Often, you only want to know where (in what file or module) a
    particular function is, so that you can go to it and edit it.
    You could use the first query (where i would be the name of the
    function) and then look through the output. The output would
    include all occurrences of the function, one of which would be
    its definition, which you could then select. Or, you could ask SCA
    to limit the search for you by typing the following query:

    FIND i AND OCCURRENCE=PRIMARY

    In SCA terms, a primary declaration is the most significant
    declaration of an item. For a BASIC function, this means the
    actual location of the function body. This is as opposed to
    an associated declaration, examples of which are EXTERNAL
    declarations, and DECLARE FUNCTION declarations.

    Another problem you might have is that there are many different
    items in your system having a given name. Some may be variables;
    others may be functions, constants, labels, and so forth. Suppose
    you want to find only the functions named i. Again, the query
    FIND i would give you what you wanted, but it would also give you
    much more. It is preferable to issue the following query:

    FIND i AND SYMBOL_CLASS=FUNCTION

    The last four examples have all selected information based on two
    attributes. The last example selected information based on a name
    attribute (in this case, i) and a symbol class attribute (in this
    case, FUNCTION). Note how the attributes are combined using the
    boolean operator AND. In general, you can select items out of your
    library based on any combination of attributes, using AND as well
    as the other logical operators OR, XOR and NOT.

    The next example shows another primary feature of SCA - the
    ability to display relationships between items. The example
    given here shows the most common use of this feature. It finds
    the complete call tree (that is, all functions called directly and
    indirectly), of the function named i.

    FIND CALLED_BY (I, DEPTH=ALL)

    If you want to limit the depth of the call tree, you can replace
    the keyword ALL by any positive integer.

    The final part of this section describes how to go directly to the
    source code once you have issued a query. After issuing the query
    FIND i, for example, you could have an LSE query buffer containing
    something that looks like the following:

      I variable
          BASIC_MODULE\60     variable declaration
          BASIC_MODULE\75     write reference
          BASIC_MODULE\79     read reference
          BASIC_MODULE\95     address reference
          BASIC_MODULE\122    read reference
          BASIC_MODULE\144    write reference
          BASIC_MODULE\146    read reference
          BASIC_MODULE\149    write reference
          BASIC_MODULE\149    read reference
          BASIC_MODULE\150    address reference
          BASIC_MODULE\166    read reference

    The first two lines of this display will be highlighted. The first
    line represents the item you looked for (I), and the rest of the
    lines represent the different places in the code where this item
    occurred (that is, the occurrences of I). By using the up and down
    arrows on your keyboard, or by clicking on an occurrence with your
    mouse, you can choose the occurrence you want to see. Then type
    CTRL/G (the keyboard equivalent of the GOTO SOURCE command), and
    LSE will bring the source file into a buffer and position you at
    the occurrence you chose.

    To obtain help on the following topics, request help as indicated.

    o  For help on query language, see the Basic_Query_Concepts help
       topic.

    o  For help on libraries, see the Building_An_SCA_Library help
       topic.

7.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

7.5  –  Using BLISS

    This section contains some basic examples that show what SCA can
    do to help you with your programs. The examples have very little
    explanation. For a more detailed explanation of the underlying
    concepts, see the Basic_Query_Concepts help topic. The remainder
    of this section is written in terms that are specific to BLISS
    programs.

    If you want to follow along and try the examples, you will need to
    have an SCA library available. If you do not know how to create
    an SCA library, read the Building_An_SCA_Library help topic. The
    examples use generic variable names (such as i). You will have to
    substitute variable names that actually exist in your code when
    trying the examples.

    The first example is the easiest query. It lets you find all the
    items in your SCA library named i, and shows you all the places
    where they appear (all occurrences of i):

    FIND i

    You can search for any name in this manner, including using
    wildcard characters (for example, FIND i*).

    Now suppose you are looking for an occurrence, and you know that
    it occurs in a particular file. The following query finds all
    occurrences of items that are named i, but will then limit them to
    those that happen to occur in the file named PROG.B32.

    FIND i AND FILE_SPEC="PROG.B32"

    Another typical question you might ask is, "Find all the places
    where this item is assigned to (or read from, called, declared and
    so forth)." The next example finds all occurrences of items that
    are named i, but then limits them to only those occurrences where
    i is assigned a value:

    FIND i AND OCCURRENCE=WRITE

    (SCA understands many occurrence classes other then WRITE. See the
    help subtopics under Getting_Started for tables containing all the
    SCA attributes and their corresponding meanings in BLISS.)

    Often, you only want to know where (in what file or module) a
    particular routine is, so that you can go to it and edit it. You
    can use the first query (where i will be the name of the routine)
    and then look through the output. The output will include all
    occurrences of the routine, one of which will be its declaration,
    which you can then select. Or, you can ask SCA to limit the search
    for you by typing the following query:

    FIND i AND OCCURRENCE=PRIMARY

    In SCA terms, a primary declaration is the most significant
    declaration of an item. For a BLISS routine, this means the
    place where the routine is actually implemented. This is in
    contrast to FORWARD or EXTERNAL declarations, which are associated
    declarations.

    Another problem you might have is that there are many different
    items in your system having a given name. Some may be variables;
    others may be routines, literals, macros, and so forth. Suppose
    you want to find only the routines named i. Again, the query
    FIND i will give you what you wanted, but it will also give you
    much more. It is preferable to issue the following query:

    FIND i AND SYMBOL_CLASS=ROUTINE

    The last four examples have all selected information based on two
    attributes. The last example selected information based on a name
    attribute (in this case, i) and a symbol_class attribute (in this
    case, ROUTINE). Note how the attributes are combined using the
    boolean operator AND. In general, you can select items out of your
    library based on any combination of attributes, using AND as well
    as the other logical operators OR, XOR, and NOT.

    The next example shows another primary feature of SCA - the
    ability to display relationships between items. This example shows
    the most common use of this feature. It finds the complete call
    tree (that is, all routines called directly and indirectly) of the
    routine named i.

    FIND CALLED_BY (i, DEPTH=ALL)

    If you want to limit the depth of the call tree, replace the
    keyword ALL by any positive integer.

    The final part of this section describes how to go directly to the
    source code once you have issued a query. After issuing the query
    FIND i, for example, you can have an LSE query buffer containing
    something that looks like the following:

      I variable
          BLISS_MODULE\60     LOCAL declaration
          BLISS_MODULE\75     write reference
          BLISS_MODULE\79     read reference
          BLISS_MODULE\122    read reference
          BLISS_MODULE\144    write reference
          BLISS_MODULE\146    read reference
          BLISS_MODULE\149    write reference
          BLISS_MODULE\149    read reference
          BLISS_MODULE\150    read reference
          BLISS_MODULE\166    read reference

    The first two lines of this display will be highlighted. The first
    line represents the item you looked for (i), and the rest of the
    lines represent the different places in the code where this item
    occurred (that is, the occurrences of i). By using the up and down
    arrows on your keyboard, or by clicking on an occurrence with your
    mouse, you can choose the occurrence you want to see. Then, type
    CTRL/G (the keyboard equivalent of the GOTO SOURCE command) and
    LSE will bring the source file into a buffer and position you at
    the occurrence you chose.

    To obtain help on the following topics, request help as indicated.

    o  For help on query language, see the Basic_Query_Concepts help
       topic.

    o  For help on libraries, see the Building_An_SCA_Library help
       topic.

7.6  –  BLISS Attributes Table

    The following table lists the SCA symbol classes and their
    corresponding meanings in BLISS.

    SCA Symbol Classes and Equivalent BLISS Language Terminology

    SCA Term       BLISS Term     Explanation

    Argument       Parameter      Routine formal parameter

    Component,     Field          Subpart of a BLOCK or BLOCKVECTOR
    Field                         structure

    Constant,      Literal        A literal
    Literal

    Exception      N/A

    File           file           A file used during compilation

    Function,      routine        A routine
    Procedure,
    Program,
    Routine,
    Subroutine

    Generic        N/A

    Keyword        Keyword        PDF keyword tag

    Label          Label          A label identifier

    Macro          Macro          A macro

    Module,        Module         A compilation unit
    Package

    Placeholder    Placeholder    An LSE placeholder

    Psect          Psect          A psect

    Tag            Tag            A PDF tag

    Task           N/A

    Type           Type           For example, fieldset

    Unbound        Unbound        A name the compiler does not know
                                  the purpose of. This is common when
                                  macros are used.

    Variable       Variable       A program variable

    The following table lists the SCA occurrence classes and their
    corresponding meanings in BLISS.

    SCA Occurrence Classes and Equivalent BLISS Language Terminology

    SCA Term       BLISS Term     Explanation

    Primary        Declaration    The declaration containing the
                                  actual implementation

    Associated     Declaration    A FORWARD or EXTERNAL declaration

    Declaration    Declaration    Either a PRIMARY or ASSOCIATED
                                  declaration

    Read, Fetch    Fetch

    Write, Store   Store

    Address,       Address
    Pointer

    Call           call

    Command_line   Input file     A file specified on the command
                   specification  line; for example, BLISS foo.b32

    Include        Require        A file specified in a REQUIRE or
                                  %REQUIRE statement

    Precompiled    Library        A file specified in a LIBRARY
                                  statement

    Reference      Reference      Any nondeclaration

    Explicit       Explicit       Any symbol declared by the user

    Implicit       Implicit       Any symbol declared by the compiler;
                                  for example, a loop variable

    Visible        Visible        A symbol whose name is visible in
                                  the source

    Hidden         Hidden         A symbol whose name is not visible
                                  in the source; for example,
                                  contained inside a macro

    Compilation_   Module         A module
    unit           declaration

    The following table lists the SCA domain classes and their
    corresponding meanings in BLISS.

    SCA Domain Classes and Equivalent BLISS Language Terminology

    SCA Term       BLISS Term     Explanation

    Inheritable    Inheritable    A symbol declared in a library file,
                                  and used elsewhere

    Global         GLOBAL

    Predefined     Defined by     For example, CH$FILL, BLOCKVECTOR,
                   the language   and so forth

    Multi_module                  GLOBAL, Predefined, or Inheritable

    Module_        LOCAL or OWN
    specific

7.7  –  Using C

    This section contains some basic examples that illustrate what
    SCA can do to help you with your programs. The examples have very
    little explanation. If you want a more detailed explanation of the
    underlying concepts, see the Basic_Query_Concepts help topic. The
    remainder of this section is written in terms that are specific to
    C programs.

    If you want to follow along and try the examples, you will need to
    have an SCA library available. If you do not know how to create
    an SCA library, read the Building_An_SCA_Library help topic. The
    examples use generic variable names (such as i). You will have to
    substitute variable names that actually exist in your code when
    trying the examples.

    The first example is the easiest query: It lets you find all the
    items in your SCA library named i, and shows you all the places
    where they appear (all occurrences of i).

    FIND i

    You can search for any name in this manner, including using
    wildcard characters (for example, FIND i*).

    Now let's say you are looking for an occurrence, and you know
    that it occurs in a particular file. The following query finds all
    occurrences of items that are named i but will then limit them to
    those which happen to occur in the file named 'PROG.C'.

    FIND i AND FILE_SPEC="PROG.C"

    Another typical question one might ask is "Find all the places
    where this item is assigned to (or read from, called, declared,and
    so forth)." The next example finds all occurrences of items that
    are named i, but then limits them to only those occurrences where
    i is assigned a value.

    FIND i AND OCCURRENCE=WRITE

    (SCA understands many occurrence classes other then WRITE. See the
    help subtopics under Getting_Started for tables containing all the
    SCA attributes and their corresponding meanings in C.)

    Often, you only want to know where (in what file or module) a
    particular function is, so that you can go to it and edit it.
    You could use the first query (where i would be the name of the
    function) and then look through the output. The output would
    include all occurrences of the function, one of which would be
    its definition, which you could then select. Or, you could ask SCA
    to limit the search for you by typing the following query:

    FIND i AND OCCURRENCE=PRIMARY

    In SCA terms, a primary declaration is the most significant
    declaration of an item. For a C function, this means the function
    definition. This is in contrast to a C function declaration
    (for example, extern i()), which in SCA terms is an associated
    declaration.

    Another problem you might have is that there are many different
    items in your system having a given name. Some may be variables;
    others may be functions, #define  constants, macros, and so forth.
    Suppose you want to find only the functions named i. Again, the
    query FIND i would give you what you wanted, but it would also
    give you much more. It is preferable to issue the following query:

    FIND i AND SYMBOL_CLASS=FUNCTION

    The last four examples have all selected information based on two
    attributes. The last example selected information based on a name
    attribute (in this case, i) and a symbol class attribute (in this
    case, FUNCTION). Note how the attributes are combined using the
    boolean operator AND. In general, you can select items out of your
    library based on any combination of attributes, using AND as well
    as the other logical operators OR, XOR and NOT.

    The next example shows another primary feature of SCA - the
    ability to display relationships between items. The example
    given here shows the most common use of this feature. It finds
    the complete call tree (that is, all functions called directly and
    indirectly), of the function named i.

    FIND CALLED_BY (i, DEPTH=ALL)

    If you want to limit the depth of the call tree, you can replace
    the keyword ALL by any positive integer.

    The final part of this section describes how to go directly to the
    source code once you have issued a query. After issuing the query
    FIND i, for example, you can have an LSE query buffer containing
    something that looks like the following:

      i variable
          C_MODULE\60     variable definition declaration
          C_MODULE\75     write reference
          C_MODULE\79     read reference
          C_MODULE\95     read, write reference
          C_MODULE\122    read reference
          C_MODULE\144    write reference
          C_MODULE\146    read reference
          C_MODULE\149    write reference
          C_MODULE\149    read reference
          C_MODULE\150    read reference
          C_MODULE\166    read reference

    The first two lines of this display will be highlighted. The first
    line represents the item you looked for (i), and the rest of the
    lines represent the different places in the code where this item
    occurred (that is, the occurrences of i). By using the up and down
    arrows on your keyboard, or by clicking on an occurrence with your
    mouse, you can choose the occurrence you want to see. Then all
    you have to do is type CTRL/G (the keyboard equivalent of the GOTO
    SOURCE command), and LSE will bring the source file into a buffer
    and position you at the occurrence you chose.

    To obtain help on the following topics, request help as indicated.

    o  For help on query language, see the Basic_Query_Concepts help
       topic.

    o  For help on libraries, see the Building_An_SCA_Library help
       topic.

7.8  –  C Attributes Table

    The following table lists the SCA symbol classes and their
    corresponding meanings in C.

    SCA Symbol Classes and Equivalent C Language Terminology

    SCA Term       C Term         Explanation

    Argument       Formal         The variable named in a function
                   Parameter      definition

    Component,     Member         A member of a structure or union
    Field

    Constant,      Constant       A defined value that does not change
    Literal

    Exception      N/A

    File           File           A file used during compilation

    Function,      Function       Any function ( such as 'main' )
    Procedure,
    Program,
    Routine,
    Subroutine

    Generic        N/A

    Keyword        Keyword        PDF keyword tag

    Label          Label          A label identifier

    Macro          Macro          A Macro created by #define

    Module,        Module         Each .c source file represents a
    Package                       module

    Placeholder    Placeholder    An LSE placeholder

    Psect          N/A

    Tag            Tag            A PDF tag

    Task           N/A

    Type           Type           int, float, struct {...}, typedef,
                                  and so forth

    Unbound        N/A

    Variable       Variable       Program variable

    The following table lists the SCA occurrence classes and their
    corresponding meanings in C.

    SCA Occurrence Classes and Equivalent C Language Terminology

    SCA Term       C Term         Explanation

    Primary        Declaration    Most significant declaration; for
                   or definition  example, a variable declaration, or
                                  a function definition

    Associated     Declaration    Other declarations; for example,
                                  function declarations or EXTERN
                                  declarations

    Declaration    Definition or  Any declaration, either primary or
                   Declaration    associated

    Read, Fetch    Read           The act of retrieving an Rvalue

    Write, Store   Write          Changing the contents of an Lvalue

    Address,       Address        The use of the & operator
    Pointer

    Call           Call           A function call

    Command_line   Command_line   A file specified on the command
                                  line, for example, CC foo.c

    Include        Include        A file specified in a #include
                                  preprocessor directive

    Precompiled    N/A

    Reference      Reference      Any nondeclaration

    Explicit       Explicit       An entity that is explicitly
                                  declared

    Implicit       Implicit       An entity that is implicitly
                                  declared by the compiler; for
                                  example, a function with no type
                                  is implicitly declared as INT

    Visible        Visible        Occurrence appears in source

    Hidden         Hidden         Occurrence does not appear in
                                  source; for example, it appears
                                  only in the expansion of a macro

    Compilation_   Module         A module
    unit

    The following table lists the SCA domain classes and their
    corresponding meanings in C.

    SCA Domain Classes and Equivalent C Language Terminology

    SCA Term       C Term         Explanation

    Inheritable    N/A

    Global         Globally       For example, extern, globaldef,
                   visible        globalref, globalvalue

    Predefined     Defined by     For example, int, float, char
                   the language

    Multi_module                  Predefined and global

    Module_        Local to one   For example, static, auto, register
    specific       module

7.9  –  Using C++

    This section contains some basic examples that illustrate what
    SCA can do to help you with your programs. The examples have very
    little explanation. If you want a more detailed explanation of the
    underlying concepts, see the Basic_Query_Concepts help topic. The
    remainder of this section is written in terms that are specific to
    C++ programs.

    If you want to follow along and try the examples, you will need to
    have an SCA library available. The examples use generic variable
    names (such as 'i'). You will have to substitute variable names that
    exist in your code when trying the examples.

    The first example is the easiest query: It lets you find all the
    items in your SCA library named i, and shows you all the places
    where they appear (all occurrences of i).

    FIND i

    You can search for any name in this manner, including using
    wildcard characters (for example, FIND i*).

    Now let's say you are looking for an occurrence, and you know
    that it occurs in a particular file. The following query finds all
    occurrences of items that are named i but will then limit them to
    those which happen to occur in the file named 'PROG.CXX'.

    FIND i AND FILE_SPEC="PROG.CXX"

    Another typical question one might ask is "Find all the places
    where this item is assigned to (or read from, called, declared,and
    so forth)." The next example finds all occurrences of items that
    are named i, but then limits them to only those occurrences where
    i is assigned a value.

    FIND i AND OCCURRENCE=WRITE

    (SCA understands many occurrence classes other then WRITE. See the
    help subtopics under Getting_Started for tables containing all the
    SCA attributes and their corresponding meanings in C++.)

    Often, you only want to know where (in what file or module) a
    particular function is, so that you can go to it and edit it.
    You could use the first query (where i would be the name of the
    function) and then look through the output. The output would
    include all occurrences of the function, one of which would be
    its definition, which you could then select. Or, you could ask SCA
    to limit the search for you by typing the following query:

    FIND i AND OCCURRENCE=PRIMARY

    In SCA terms, a primary declaration is the most significant
    declaration of an item. For a C++ function, this means the function
    definition. This is in contrast to a C++ function declaration (for
    example, extern i()), which in SCA terms is an associated declaration.

    Another problem you might have is that there are many different
    items in your system having a given name. Some may be variables;
    others may be functions, #define  constants, macros, and so forth.
    Suppose you want to find only the functions named i. Again, the
    query FIND i would give you what you wanted, but it would also
    give you much more. It is preferable to issue the following query:

    FIND i AND SYMBOL_CLASS=FUNCTION

    The last four examples have all selected information based on two
    attributes. The last example selected information based on a name
    attribute (in this case, i) and a symbol class attribute (in this
    case, FUNCTION). Note how the attributes are combined using the
    boolean operator AND. In general, you can select items out of your
    library based on any combination of attributes, using AND as well
    as the other logical operators OR, XOR and NOT.

    The next example shows another primary feature of SCA - the
    ability to display relationships between items. The example
    given here shows the most common use of this feature. It finds
    the complete call tree (that is, all functions called directly and
    indirectly), of the function named i.

    FIND CALLED_BY (i, DEPTH=ALL)

    If you want to limit the depth of the call tree, you can replace
    the keyword ALL by any positive integer.

    To obtain help on the following topics, request help as indicated.

    o  For help on query language, see the Basic_Query_Concepts help
       topic.

    o  For help on libraries, see the Building_An_SCA_Library help
       topic.

7.10  –  C++ Attributes Table

    The following table lists the SCA symbol classes and their
    corresponding meanings in C++.

    SCA Symbol Classes and Equivalent C++ Language Terminology

    SCA Term       C++ Term         Explanation

    Argument       Formal           Formal arguement such as a routine
                   Parameter        or macro argument

    Class          Class            Any C++ class object defined by class,
                                    structure or union

    Component,     Class, structure A component of a class, structure
    Field          or union member  or union

    Constant,      Constant         Named compile-time constants
    Literal

    Exception      Exception        A program exception specified by
                                    the catch, throw and try statements

    File           File             A file used during compilation

    Function,      Function         Callable routines defined by function
    Procedure,                      statements
    Program,
    Routine,
    Subroutine

    Generic        Template         Generic object defined by template
                                    objects

    Keyword        Keyword          PDF keyword tag

    Label          Function Label   User-specified label

    Macro          Macro            A Macro created by #define

    Module,        Module           Any logical program unit typically
    Package                         each .cxx source file represents a
                                    module

    Placeholder    Placeholder      An LSE placeholder

    Psect          N/A

    Tag            Tag              A PDF tag

    Task           N/A

    Type           Type             int, float, struct {...}, typedef,
                                    and so forth

    Unbound        N/A

    Variable       Variable         Program variable

    The following table lists the SCA occurrence classes and their
    corresponding meanings in C++.

    SCA Occurrence Classes and Equivalent C++ Language Terminology

    SCA Term       C++ Term         Explanation

    Primary        Declaration    Most significant declaration; for
                   or definition  example, a variable declaration, or
                                  a function definition

    Associated     Declaration    Other declarations; for example,
                                  function declarations or EXTERN
                                  declarations

    Declaration    Definition or  Any declaration, either primary or
                   Declaration    associated

    Read, Fetch    Read           The act of retrieving an Rvalue

    Write, Store   Write          Changing the contents of an Lvalue

    Address,       Address        The use of the & operator
    Pointer

    Call           Call           A function call

    Command_line   Command_line   A file specified on the command
                                  line, for example, Cxx foo.c

    Include        Include        A file specified in a #include
                                  preprocessor directive

    Precompiled    N/A

    Base           Base           Any base class of a class

    Friend         Friend         Any friend of a class

    Member         Member         Any member of a class

    Reference      Reference      Any nondeclaration

    Explicit       Explicit       An entity that is explicitly
                                  declared

    Implicit       Implicit       An entity that is implicitly
                                  declared by the compiler; for
                                  example, a function with no type
                                  is implicitly declared as INT

    Visible        Visible        Occurrence appears in source

    Hidden         Hidden         Occurrence does not appear in
                                  source; for example, it appears
                                  only in the expansion of a macro

    Compilation_   Module         A module
    unit

    Private        Private        Any private object

    Protected      Protected      Any protected object

    Public         Public         Any public object

    Virtual        Virtual        Any virtual object

    The following table lists the SCA domain classes and their
    corresponding meanings in C++.

    SCA Domain Classes and Equivalent C++ Language Terminology

    SCA Term       C++ Term         Explanation

    Inheritable    N/A

    Global         Globally       For example, extern, globaldef,
                   visible        globalref, globalvalue

    Predefined     Defined by     For example, int, float, char
                   the language

    Multi_module                  Predefined and global

    Module_        Local to one   For example, static, auto, register
    specific       module

7.11  –  Using COBOL

    This section contains some basic examples that illustrate what
    SCA can do to help you with your programs. The examples have very
    little explanation. If you want a more detailed explanation of the
    underlying concepts, see the Basic_Query_Concepts help topic. The
    remainder of this section is written in terms that are specific to
    Cobol programs.

    If you want to follow along and try the examples, you will need to
    have an SCA library available. If you do not know how to create
    an SCA library, read the Building_An_SCA_Library help topic. The
    examples use generic variable names (such as i). You will have to
    substitute variable names that actually exist in your code when
    trying the examples.

    The first example is the easiest query: It lets you find all the
    items in your SCA library named i, and shows you all the places
    where they appear (all occurrences of i).

    FIND i

    You can search for any name in this manner, including using
    wildcard characters (for example, FIND i*).

    Now let's say you are looking for an occurrence, and you know
    that it occurs in a particular file. The following query finds all
    occurrences of items that are named i but will then limit them to
    those which happen to occur in the file named 'PROG.COB'.

    FIND i AND FILE_SPEC="PROG.COB"

    Another typical question one might ask is "Find all the places
    where this item is assigned to (or read from, called, declared,
    and so forth)." The next example finds all occurrences of items
    that are named i, but then limits them to only those occurrences
    where i is assigned a value.

    FIND i AND OCCURRENCE=WRITE

    (SCA understands many occurrence classes other then WRITE. See the
    help subtopics under Getting_Started for tables containing all the
    SCA attributes and their corresponding meanings in COBOL.)

    Often, you only want to know where (in what file ) a particular
    procedure is, so that you can go to it and edit it. You could use
    the first query (where i would be the program-id) and then look
    through the output. The output would include all occurrences of
    the program, one of which would be its definition, which you could
    then select. Or, you could ask SCA to limit the search for you by
    typing the following query:

    FIND i AND OCCURRENCE=PRIMARY

    In SCA terms, a primary declaration is the most significant
    declaration of an item. For a Cobol program, this is the program-
    id. This is in contrast to an associated declaration. Actually,
    in Cobol, associated declarations do not have much meaning. The
    compiler creates implicit associated declarations for a program
    the first time it is called.

    Another problem you might have is that there are many different
    items in your system having a given name. Some may be variables;
    others may be programs, paragraph names, files, and so forth.
    Suppose you want to find only the programs named i. Again, the
    query FIND i would give you what you wanted, but it would also
    give you much more. It is preferable to issue the following query:

    FIND i AND SYMBOL_CLASS=PROGRAM

    The last four examples have all selected information based on two
    attributes. The last example selected information based on a name
    attribute (in this case, i) and a symbol class attribute (in this
    case, PROGRAM). Note how the attributes are combined using the
    boolean operator AND. In general, you can select items out of your
    library based on any combination of attributes, using AND as well
    as the other logical operators OR, XOR and NOT.

    The next example shows another primary feature of SCA - the
    ability to display relationships between items. The example
    given here shows the most common use of this feature. It finds
    the complete call tree (that is, all programs called directly and
    indirectly), of the program named i.

    FIND CALLED_BY (I, DEPTH=ALL)

    If you want to limit the depth of the call tree, you can replace
    the keyword ALL by any positive integer.

    The final part of this section describes how to go directly to the
    source code once you have issued a query. After issuing the query
    FIND i, for example, you can have an LSE query buffer containing
    something that looks like the following:

      I variable
          COBOL_MODULE\60     data declaration
          COBOL_MODULE\75     write reference
          COBOL_MODULE\79     read reference
          COBOL_MODULE\122    read reference
          COBOL_MODULE\144    write reference
          COBOL_MODULE\146    read reference
          COBOL_MODULE\149    read reference
          COBOL_MODULE\166    read reference

    The first two lines of this display will be highlighted. The first
    line represents the item you looked for (I), and the rest of the
    lines represent the different places in the code where this item
    occurred (that is, the occurrences of I). By using the up and down
    arrows on your keyboard, or by clicking on an occurrence with your
    mouse, you can choose the occurrence you want to see. Then all
    you have to do is type CTRL/G (the keyboard equivalent of the GOTO
    SOURCE command), and LSE will bring the source file into a buffer
    and position you at the occurrence you chose.

    To obtain help on the following topics, request help as indicated.

    o  For help on query language, see the Basic_Query_Concepts help
       topic.

    o  For help on libraries, see the Building_An_SCA_Library help
       topic.

7.12  –  COBOL Attributes Table

    The following table lists the SCA symbol classes and their
    corresponding meanings in COBOL.

    SCA Symbol Classes and Equivalent COBOL Language Terminology

    SCA Term       COBOL Term     Explanation

    Argument       Program
                   argument

    Component,     Group item
    Field

    Constant,                     A character string whose value is
    Literal                       specified by the ordered set of
                                  characters it contains, or a reserve
                                  word that is a figurative constant;
                                  for example, "1.234E7", ZERO

    Exception      N/A

    File           File           A file used during the compilation

    Function,      Program        A program
    Procedure,
    Program,
    Routine,
    Subroutine

    Generic        N/A

    Keyword        Keyword        A PDF keyword

    Label          Paragraph-
                   name or
                   section-name

    Macro          N/A

    Module,        N/A
    Package

    Placeholder    Placeholder    An LSE placeholder

    Psect          PSECT

    Tag            Tag            A PDF tag

    Task           N/A

    Type           Datatype

    Unbound                       Symbols in conditional compilation
                                  lines

    Variable       Data item

    The following table lists the SCA occurrence classes and their
    corresponding meanings in COBOL.

    SCA Occurrence Classes and Equivalent COBOL Language Terminology

    SCA Term       COBOL Term     Explanation

    Primary        Declaration    Data declarations, program ids

    Associated                    Implicit declarations of called
                                  programs the first time they are
                                  seen

    Declaration    Declaration    Both primary and associated
                                  declarations

    Read, Fetch    FETCH

    Write, Store   STORE

    Address,       N/A
    Pointer

    Call           CALL

    Command_line                  A file specified on the command
                                  line, for example, COBOL foo.cob

    Include        COPY

    Precompiled    N/A

    Reference      Reference      Any nondeclaration

    Explicit                      A variable declared by the user

    Implicit                      A variable automatically defined by
                                  the compiler

    Visible                       Not hidden

    Hidden                        Hidden occurrences may be due to
                                  default conditions (for example,
                                  PIC 9(4) is given the DISPLAY TYPE)
                                  or within complex statement (for
                                  example, COMPUTE and hidden write
                                  references).

    Compilation_   SCP
    unit           separately
                   compiled unit

    The following table lists the SCA domain classes and their
    corresponding meanings in COBOL.

    SCA Domain Classes and Equivalent COBOL Language Terminology

    SCA Term       COBOL Term     Explanation

    Inheritable    N/A

    Global         EXTERNAL

    Predefined     PREDEFINED     For example, special registers

    Multi_module                  Global and predefined

    Module_                       Not multi-module
    specific

7.13  –  Using FORTRAN

    This section contains some basic examples that illustrate what
    SCA can do to help you with your programs. The examples have very
    little explanation. If you want a more detailed explanation of the
    underlying concepts, see the Basic_Query_Concepts help topic. The
    remainder of this section is written in terms that are specific to
    FORTRAN programs.

    If you want to follow along and try the examples, you will need to
    have an SCA library available. If you do not know how to create
    an SCA library, read the Building_An_SCA_Library help topic. The
    examples use generic variable names (such as i). You will have to
    substitute variable names that actually exist in your code when
    trying the examples.

    The first example is the easiest query: It lets you find all the
    items in your SCA library named i, and shows you all the places
    where they appear (all occurrences of i).

    FIND i

    characters (for example, FIND i*).

    Now let's say you are looking for an occurrence, and you know
    that it occurs in a particular file. The following query finds all
    occurrences of items that are named i but will then limit them to
    those which happen to occur in the file named 'PROG.FOR'.

    FIND i AND FILE_SPEC="PROG.FOR"

    Another typical question one might ask is "Find all the places
    where this item is assigned to (or read from, called, declared,
    and so forth)." The next example finds all occurrences of items
    that are named i, but then limits them to only those occurrences
    where i is assigned a value.

    FIND i AND OCCURRENCE=WRITE

    (SCA understands many occurrence classes other then WRITE. See the
    help subtopics under Getting_Started for tables containing all the
    SCA attributes and their corresponding meanings in FORTRAN.)

    Often, you only want to know where (in what file or module) a
    particular subroutine is, so that you can go to it and edit it.
    You could use the first query (where i would be the name of the
    subroutine) and then look through the output. The output would
    include all occurrences of the subroutine, one of which would be
    its definition, which you could then select. Or, you could ask SCA
    to limit the search for you by typing the following query:

    FIND i AND OCCURRENCE=PRIMARY

    In SCA terms, a primary declaration is the most significant
    declaration of an item. For a FORTRAN subroutine, this is where
    the actual SUBROUTINE statement is. This is in contrast to a
    FORTRAN EXTERNAL declaration, which in SCA terms is an associated
    declaration. The FORTRAN compiler also creates implicit associated
    declarations for any undeclared functions.

    Another problem you might have is that there are many different
    items in your system having a given name. Some may be variables;
    others may be subroutines, PARAMETER constants, and so forth.
    Suppose you want to find only the subroutines named i. Again, the
    query FIND i would give you what you wanted, but it would also
    give you much more. It is preferable to issue the following query:

    FIND i AND SYMBOL_CLASS=SUBROUTINE

    The last four examples have all selected information based on two
    attributes. The last example selected information based on a name
    attribute (in this case, i) and a symbol class attribute (in this
    case, SUBROUTINE). Note how the attributes are combined using the
    boolean operator AND. In general, you can select items out of your
    library based on any combination of attributes, using AND as well
    as the other logical operators OR, XOR and NOT.

    The next example shows another primary feature of SCA - the
    ability to display relationships between items. The example
    given here shows the most common use of this feature. It finds
    the complete call tree (that is, all subroutines called directly
    and indirectly), of the subroutine named i.

    FIND CALLED_BY (I, DEPTH=ALL)

    If you want to limit the depth of the call tree, you can replace
    the keyword ALL by any positive integer.

    The final part of this section describes how to go directly to the
    source code once you have issued a query. After issuing the query
    FIND i, for example, you can have an LSE query buffer containing
    something that looks like the following:

      I variable
          FORTRAN_MODULE\60     variable declaration
          FORTRAN_MODULE\75     write reference
          FORTRAN_MODULE\79     read reference
          FORTRAN_MODULE\95     address reference
          FORTRAN_MODULE\122    read reference
          FORTRAN_MODULE\144    write reference
          FORTRAN_MODULE\146    read reference
          FORTRAN_MODULE\149    write reference
          FORTRAN_MODULE\149    read reference
          FORTRAN_MODULE\150    address reference
          FORTRAN_MODULE\166    read reference

    The first two lines of this display will be highlighted. The first
    line represents the item you looked for (I), and the rest of the
    lines represent the different places in the code where this item
    occurred (that is, the occurrences of I). By using the up and down
    arrows on your keyboard, or by clicking on an occurrence with your
    mouse, you can choose the occurrence you want to see. Then all
    you have to do is type CTRL/G (the keyboard equivalent of the GOTO
    SOURCE command), and LSE will bring the source file into a buffer
    and position you at the occurrence you chose.

    To obtain help on the following topics, request help as indicated.

    o  For help on query language, see the Basic_Query_Concepts help
       topic.

    o  For help on libraries, see the Building_An_SCA_Library help
       topic.

7.14  –  FORTRAN Attributes Table

    The following table lists the SCA symbol classes and their
    corresponding meanings in FORTRAN.

    SCA Symbol Classes and Equivalent FORTRAN Language Terminology

    SCA Term       FORTRAN Term   Explanation

    Argument       Dummy          The variable named in a function
                   argument       declaration

    Component,     record
    Field          component

    Constant,      PARAMETER
    Literal

    Exception      N/A

    File           File           A file used during compilation

    Function,      SUBROUTINE or  A SUBROUTINE, FUNCTION, or main
    Procedure,     FUNCTION       program
    Program,
    Routine,
    Subroutine

    Generic        N/A

    Keyword        Keyword        A PDF keyword

    Label          Label          A statement label

    Macro          N/A

    Module,        BLOCK DATA,
    Package        SUBROUTINE

    Placeholder    Placeholder    An LSE placeholder

    Psect          COMMON block

    Tag            tag            A PDF tag

    Task           N/A

    Type           Type           For example, INTEGER, REAL, COMPLEX
                                  and so forth

    Unbound        N/A

    Variable       Variable

    The following table lists the SCA occurrence classes and their
    corresponding meanings in FORTRAN.

    SCA Occurrence Classes and Equivalent FORTRAN Language Terminology

    SCA Term       FORTRAN Term   Explanation

    Primary        Declaration    The declaration containing the
                                  actual implementation

    Associated     Declaration    An EXTERNAL declaration

    Declaration    Declaration    Any declaration, either primary or
                                  associated

    Read, Fetch    Read

    Write, Store   Write

    Address,       Address        %LOC, actual arguments
    Pointer

    Call           Call           For example, a CALL statement

    Command_line   Command line   A file specified on the command
                                  line; for example, FORTRAN foo.for

    Include        INCLUDE        A file specified in an INCLUDE
                                  statement

    Precompiled    N/A

    Reference      Reference      Any nondeclaration

    Explicit       Explicit       Any symbol declared by the user

    Implicit       Implicit       Any symbol declared by the compiler
                                  when it sees the first reference

    Visible        Visible        A symbol whose name is visible in
                                  the source

    Hidden         Hidden         A symbol whose name is not visible
                                  in the source

    Compilation_   Program unit   A SUBROUTINE, FUNCTION, PROGRAM,
    unit                          BLOCK DATE, and so forth

    The following table lists the SCA domain classes and their
    corresponding meanings in FORTRAN.

    SCA Domain Classes and Equivalent FORTRAN Language Terminology

    SCA Term       FORTRAN Term   Explanation

    Inheritable    N/A

    Global                        A SUBROUTINE, FUNCTION, or COMMON
                                  block

    Predefined     Defined by     For example, INTEGER, REAL*4, and so
                   the language   forth

    Multi_module   GLOBAL,
                   predefined,
                   and
                   inheritable

    Module_                       Only known within a SUBROUTINE,
    specific                      FUNCTION, and so forth

7.15  –  Using Pascal

    This section contains some basic examples that illustrate what
    SCA can do to help you with your programs. The examples have very
    little explanation. If you want a more detailed explanation of the
    underlying concepts, see the Basic_Query_Concepts help topic. The
    remainder of this section is written in terms that are specific to
    Pascal programs.

    If you want to follow along and try the examples, you will need to
    have an SCA library available. The SCA$EXAMPLE library provided
    with SCA is based on Pascal, so you could use it. If you want
    to use your own library, but do not know how to create an SCA
    library, read the Building_An_SCA_Library help topic. The examples
    in this section use variables from the SCA$EXAMPLE library. If you
    use your own library, you will have to substitute variable names
    that actually exist in your code when trying the examples.

    The first example is the easiest query: It lets you find all the
    items in your SCA library named i, and shows you all the places
    where they appear (all occurrences of i).

    FIND i

    You can search for any name in this manner, including using
    wildcard characters (for example, FIND i*).

    Now let's say you are looking for an occurrence, and you know
    that it occurs in a particular file. The following query finds all
    occurrences of items that are named i but will then limit them to
    those which happen to occur in the file named 'BUILDTABLE.PAS'.

    FIND i AND FILE_SPEC="BUILDTABLE.PAS"

    Another typical question one might ask is "Find all the places
    where this item is assigned to (or read from, called, declared,
    and so forth)." The next example finds all occurrences of items
    that are named c, but then limits them to only those occurrences
    where c is assigned a value.

    FIND c AND OCCURRENCE=WRITE

    (SCA understands many occurrence classes other then WRITE. See the
    help subtopics under Getting_Started for tables containing all the
    SCA attributes and their corresponding meanings in Pascal.)

    Often, you only want to know where (in what file or module) a
    particular procedure is, so that you can go to it and edit it. You
    could use a query similar to the first (where i would be replaced
    by the name of the procedure) and then look through the output.
    The output would include all occurrences of the procedure, one
    of which would be its declaration, which you could then select.
    Or, you could ask SCA to limit the search for you by typing the
    following query:

    FIND build_table AND OCCURRENCE=PRIMARY

    In SCA terms, a primary declaration is the most significant
    declaration of an item. For a Pascal procedure, this means the
    place where the procedure is actually implemented. This is in
    contrast to FORWARD or EXTERNAL declarations, which are associated
    declarations.

    Another problem you might have is that there are many different
    items in your system having a given name. Some may be variables;
    others may be functions, constants, labels, and so forth. Suppose
    you want to find only the procedures named 'build_table'. Again,
    the query FIND build_table would give you what you wanted, but
    it would also give you much more. It is preferable to issue the
    following query:

    FIND build_table AND SYMBOL_CLASS=PROCEDURE

    The last four examples have all selected information based on
    two attributes. The last example selected information based on a
    name attribute (in this case, 'build_table') and a symbol class
    attribute (in this case, PROCEDURE). Note how the attributes
    are combined using the boolean operator AND. In general, you
    can select items out of your library based on any combination
    of attributes, using AND as well as the other logical operators
    OR, XOR and NOT.

    The next example shows another primary feature of SCA - the
    ability to display relationships between items. The example
    given here shows the most common use of this feature. It finds
    the complete call tree (that is, all procedures called directly
    and indirectly), of the procedure named 'build_table'.

    FIND CALLED_BY (build_table, DEPTH=ALL)

    If you want to limit the depth of the call tree, you can replace
    the keyword ALL by any positive integer.

    The final part of this section describes how to go directly to the
    source code once you have issued a query. After issuing the query
    FIND c, for example, you can have an LSE query buffer containing
    something that looks like the following:

      C variable
          EXPAND_STRING\60     VAR (variable) declaration
          EXPAND_STRING\75     write reference
          EXPAND_STRING\79     read reference
          EXPAND_STRING\95     read reference
          EXPAND_STRING\122    read reference
          EXPAND_STRING\144    write reference
          EXPAND_STRING\146    read reference
          EXPAND_STRING\149    write reference
          EXPAND_STRING\149    read reference
          EXPAND_STRING\150    read reference
          EXPAND_STRING\166    read reference

    The first two lines of this display will be highlighted. The first
    line represents the item you looked for (c), and the rest of the
    lines represent the different places in the code where this item
    occurred (that is, the occurrences of c). By using the up and down
    arrows on your keyboard, or by clicking on an occurrence with your
    mouse, you can choose the occurrence you want to see. Then all
    you have to do is type CTRL/G (the keyboard equivalent of the GOTO
    SOURCE command), and LSE will bring the source file into a buffer
    and position you at the occurrence you chose.

    To obtain help on the following topics, request help as indicated.

    o  For help on query language, see the Basic_Query_Concepts help
       topic.

    o  For help on libraries, see the Building_An_SCA_Library help
       topic.

7.16  –  Pascal Attributes Table

    The following table lists the SCA symbol classes and their
    corresponding meanings in Pascal.

    SCA Symbol Classes and Equivalent Pascal Language Terminology

    SCA Term       Pascal Term    Explanation

    Argument       Formal
                   parameter

    Component,     Component,     Components of array types, VARYING,
    Field          String         STRING; fields of records

    Constant,      Constant       CONSTants, predefined constants,
    Literal                       enumerated type constants

    Exception      N/A

    File           File           A file used during compilation

    Function,      Function,
    Procedure,     procedure
    Program,
    Routine,
    Subroutine

    Generic        N/A

    Keyword        Keyword        A PDF keyword

    Label          Label          Label declarations and uses

    Macro          N/A

    Module,        Program,
    Package        module

    Placeholder    Placeholder    An LSE placeholder

    Psect          Psect          PSECT and COMMON attributes

    Tag            Tag            A PDF tag

    Task           N/A

    Type           Type           For example, pointer, array,
                                  enumerated, subrange types

    Unbound        N/A

    Variable       Variable

    The following table lists the SCA occurrence classes and their
    corresponding meanings in Pascal.

    SCA Occurrence Classes and Equivalent Pascal Language Terminology

    SCA Term       Pascal Term    Explanation

    Primary        Declaration    For example, PROCEDURE XYZ;

    Associated     FORWARD and    For example,
                   EXTERNAL       PROCEDURE XYZ; EXTERNAL;
                   declarations

    Declaration    Declaration    Both primary and associated
                                  declarations

    Read, Fetch    Read

    Write, Store   Write

    Address,       Address
    Pointer

    Call           Call

    Command_line   Command line   A file specified on the command
                                  line, for example, PASCAL foo.pas

    Include        Include        A file specified in an INCLUDE
                                  statement

    Precompiled    Environment    A file specified in an INHERIT
                                  clause

    Reference      Reference      Any nondeclaration

    Explicit                      Pascal has no implicit occurrences.
                                  Everything is explicit.

    Implicit       N/A

    Visible                       Appears in the source

    Hidden                        Does not appear in the source, for
                                  example,
                                  VAR I : INTEGER VALUE 10 has a
                                  hidden write reference.

    Compilation_   Module,
    unit           Program

    The following table lists the SCA domain classes and their
    corresponding meanings in Pascal.

    SCA Domain Classes and Equivalent Pascal Language Terminology

    SCA Term       Pascal Term    Explanation

    Inheritable    Inherited or   Items in an environment file and
                   inheritable    items inherited from an environment
                                  file

    Global         GLOBAL         Items declared with the GLOBAL
                                  attribute

    Predefined     Predeclared    For example, INTEGER, TRUE, WRITELN

    Multi_module                  Inheritable, Global, Predefined

    Module_                       Items local to a compilation unit,
    specific                      and not in an environment file

7.17  –  EPascal Attributes Table

    The following table lists the SCA symbol classes and their
    corresponding meanings in EPascal.

    SCA Symbol Classes and Equivalent EPascal Language Terminology

    SCA Term       EPascal Term   Explanation

    Argument       Formal
 		  parameter

    Component,     Component,     Components of array types, VARYING,

    Field          String         STRING; fields of records

    Constant,      Constant       CONSTants, predefined constants,
    Literal                       enumerated type constants

    Exception      INTERRUPT_SERVICE  Interrupt Service routine

    File           File           A file used during compilation

    Function,      Function,
    Procedure,     procedure
    Routine,
    Subroutine

    Generic        N/A

    Keyword        N/A

    Label          Label          Label declarations and uses

    Macro          N/A

    Module,        Program,
    Package        module

    Placeholder    N/A

    Program        PROGRAM

    Psect          Psect          PSECT and COMMON attributes

    Tag            N/A

    Task           PROCESS_BLOCK

    Type           Type           For example, pointer, array,
 				 enumerated, subrange types

    Unbound        Flexible type

    Variable       Variable

    The following table lists the SCA occurrence classes and their
    corresponding meanings in EPascal.

    SCA Occurrence Classes and Equivalent EPascal Language Terminology

    SCA Term       EPascal Term   Explanation

    Primary        Declaration    For example, PROCEDURE XYZ;

    Associated     FORWARD and    For example,
 		  EXTERNAL       PROCEDURE XYZ; EXTERNAL;
 		  declarations

    Declaration    Declaration    Both primary and associated
 				 declarations

    Read, Fetch    Read

    Write, Store   Write

    Address,       Address
    Pointer

    Call           Call

    Command_line   Command line   A file specified on the command
 				 line, for example, EPASCAL foo.pas

    Include        %Include       A file specified in a %INCLUDE
 				 statement

    Precompiled    Include        A file specified in an INCLUDE
 				 statement

    Reference      Reference      Any nondeclaration

    Explicit                      EPascal has no implicit occurrences.
 				 Everything is explicit.

    Implicit       N/A

    Visible                       Appears in the source

    Hidden                        Does not appear in the source, for
 				 example,
 				 VAR I : INTEGER VALUE 10 has a
 				 hidden write reference.

    Compilation_   Module,
    unit           Program

    The following table lists the SCA domain classes and their
    corresponding meanings in EPascal.

    SCA Domain Classes and Equivalent EPascal Language Terminology

    SCA Term       EPascal Term   Explanation

    Inheritable    INCLUDEd       Items in a precompiled file.

    Global         GLOBAL         Items declared with the GLOBAL
 				 attribute

    Predefined     Predeclared    For example, INTEGER, TRUE, WRITELN

    Multi_module                  Inheritable, Global, Predefined

    Module_                       Items local to a compilation unit,
    specific                      and not in a precompiled file.

7.18  –  Using SCAN

    This section contains some basic examples that illustrate what
    SCA can do to help you with your programs. The examples have very
    little explanation. If you want a more detailed explanation of the
    underlying concepts, see the Basic_Query_Concepts help topic. The
    remainder of this section is written in terms that are specific to
    SCAN programs.

    If you want to follow along and try the examples, you will need to
    have an SCA library available. If you do not know how to create
    an SCA library, read the Building_An_SCA_Library help topic. The
    examples use generic variable names (such as i). You will have to
    substitute variable names that actually exist in your code when
    trying the examples.

    The first example is the easiest query: It lets you find all the
    items in your SCA library named i, and shows you all the places
    where they appear (all occurrences of i).

    FIND i

    You can search for any name in this manner, including using
    wildcard characters (for example, FIND i*).

    Now let's say you are looking for an occurrence, and you know
    that it occurs in a particular file. The following query finds all
    occurrences of items that are named i but will then limit them to
    those which happen to occur in the file named 'PROG.SCN'.

    FIND i AND FILE_SPEC="PROG.SCN"

    Another typical question one might ask is "Find all the places
    where this item is assigned to (or read from, called, declared,
    and so forth)." The next example finds all occurrences of items
    that are named i, but then limits them to only those occurrences
    where i is assigned a value.

    FIND i AND OCCURRENCE=WRITE

    (SCA understands many occurrence classes other then WRITE. See the
    help subtopics under Getting_Started for tables containing all the
    SCA attributes and their corresponding meanings in SCAN.)

    Often, you only want to know where (in what file or module) a
    particular procedure is, so that you can go to it and edit it.
    You could use the first query (where i would be the name of the
    procedure) and then look through the output. The output would
    include all occurrences of the procedure, one of which would be
    its declaration, which you could then select. Or, you could ask
    SCA to limit the search for you by typing the following query:

    FIND i AND OCCURRENCE=PRIMARY

    In SCA terms, a primary declaration is the most significant
    declaration of an item. For a SCAN procedure, this means the
    place where the procedure is actually implemented, that is, the
    PROCEDURE declaration. This is in contrast to FORWARD or EXTERNAL
    declarations, which are associated declarations

    Another problem you might have is that there are many different
    items in your system having a given name. Some may be variables;
    others may be procedures, constants, labels, and so forth. Suppose
    you want to find only the procedures named i. Again, the query
    FIND i would give you what you wanted, but it would also give you
    much more. It is preferable to issue the following query:

    FIND i AND SYMBOL_CLASS=PROCEDURE

    The last four examples have all selected information based on two
    attributes. The last example selected information based on a name
    attribute (in this case, i) and a symbol class attribute (in this
    case, PROCEDURE). Note how the attributes are combined using the
    boolean operator AND. In general, you can select items out of your
    library based on any combination of attributes, using AND as well
    as the other logical operators OR, XOR and NOT.

    The next example shows another primary feature of SCA - the
    ability to display relationships between items. The example
    given here shows the most common use of this feature. It finds
    the complete call tree (that is, all procedures called directly
    and indirectly), of the procedure named i.

    FIND CALLED_BY (i, DEPTH=ALL)

    If you want to limit the depth of the call tree, you can replace
    the keyword ALL by any positive integer.

    The final part of this section describes how to go directly to the
    source code once you have issued a query. After issuing the query
    FIND i, for example, you can have an LSE query buffer containing
    something that looks like the following:

      I variable
          SCAN_MODULE\60     variable declaration
          SCAN_MODULE\75     write reference
          SCAN_MODULE\79     read reference
          SCAN_MODULE\122    read reference
          SCAN_MODULE\144    write reference
          SCAN_MODULE\146    read reference
          SCAN_MODULE\149    write reference
          SCAN_MODULE\149    read reference
          SCAN_MODULE\150    read reference
          SCAN_MODULE\166    read reference

    The first two lines of this display will be highlighted. The first
    line represents the item you looked for (i), and the rest of the
    lines represent the different places in the code where this item
    occurred (that is, the occurrences of i). By using the up and down
    arrows on your keyboard, or by clicking on an occurrence with your
    mouse, you can choose the occurrence you want to see. Then all
    you have to do is type CTRL/G (the keyboard equivalent of the GOTO
    SOURCE command), and LSE will bring the source file into a buffer
    and position you at the occurrence you chose.

    To obtain help on the following topics, request help as indicated.

    o  For help on query language, see the Basic_Query_Concepts help
       topic.

    o  For help on libraries, see the Building_An_SCA_Library help
       topic.

7.19  –  SCAN Attributes Table

    The following table lists the SCA symbol classes and their
    corresponding meanings in SCAN.

    SCA Symbol Classes and Equivalent SCAN Language Terminology

    SCA Term       SCAN Term      Explanation

    Argument       Formal         A routine or function formal
                   parameter      parameter

    Component,     Leaf node      A leaf node of a TREE variable
    Field

    Constant,      Constant       A CONSTANT definition
    Literal

    Exception      N/A

    File           File           A file used during compilation

    Function,      Procedure      A Procedure
    Procedure,
    Program,
    Routine,
    Subroutine

    Generic        N/A

    Keyword        N/A

    Label          Label          A statement label

    Macro          N/A

    Module,        Module         A module
    Package

    Placeholder    N/A

    Psect          Psect          A psect name

    Tag            N/A

    Task           N/A

    Type           Type

    Unbound        N/A

    Variable       Variable

    The following table lists the SCA occurrence classes and their
    corresponding meanings in SCAN.

    SCA Occurrence Classes and Equivalent SCAN Language Terminology

    SCA Term       SCAN Term      Explanation

    Primary        Declaration    Either a DECLARE or PROCEDURE
                                  declaration

    Associated     Declaration    Either a FORWARD or EXTERNAL
                                  declaration

    Declaration    Declaration    Either primary or associated

    Read, Fetch    Reference      The value of a variable is
                                  retrieved.

    Write, Store   Assignment     A variable is assigned a value.

    Address,       Indirect
    Pointer        reference

    Call           Call

    Command_line   Command line   A file specified on the command
                                  line; for example, SCAN foo.scn.

    Include        Include        A file included with the INCLUDE
                                  statement

    Precompiled    N/A

    Reference      Reference      Any nondeclaration

    Explicit       Explicit       A variable or procedure explicitly
                                  declared with DECLARE or PROCEDURE
                                  statement

    Implicit       Implicit       A variable declared by the compiler
                                  on first reference, for example, a
                                  picture variable

    Visible        N/A

    Hidden         N/A

    Compilation_   Module
    unit

    The following table lists the SCA domain classes and their
    corresponding meanings in SCAN.

    SCA Domain Classes and Equivalent SCAN Language Terminology

    SCA Term       SCAN Term      Explanation

    Inheritable    N/A

    Global         Global         Declaration has GLOBAL attribute

    Predefined     Predefined

    Multi_module   Global or
                   predefined

    Module_                       Local to one module
    specific

8  –  Glossary

8.1  –  analysis_data_file

    A file produced by a compiler which contains information that
    describes the source code to SCA. It may contain one or more
    analysis data modules.

8.2  –  analysis_data_module

    A module containing all the information used by SCA for one
    compilation unit.

8.3  –  appearance

    One of the attributes of an occurrence. It tells you whether the
    name of the occurrence is visible or hidden. You can instruct SCA
    to show only occurrences with a particular appearance by using the
    "occurrence=" attribute selection. For example, you can ask for
    hidden occurrences by specifying "occurrence=hidden."

8.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.

8.5  –  attribute_selection

    A way of limiting a result of a query to those occurrences which
    match certain characteristics. You can select the following
    attributes: NAME, SYMBOL_CLASS, OCCURRENCE, DOMAIN, or FILE_SPEC
    attributes. In the query language, you use phrases like name=foo,
    symbol=argument, occurrence=declaration, domain=module_specific,
    and file="foo.c" to specify which attributes you want. You combine
    these phrases with AND, OR and NOT operators.

8.6  –  attribute_selection_expression

    A query question which combines one or more attribute selections
    (such as name=foo, symbol=routine) using AND, OR, NOT, and XOR.
    Some examples are:

      name=foo and symbol=routine and occurrence=primary
      name=foo_module and occurrence=compilation_unit

8.7  –  call_graph

    Shows what procedures and functions are called from a subroutine,
    and all subsequent calls in the call graph.

8.8  –  CALLED_BY

    See the SCA_Topics CALLED_BY help topic.

8.9  –  CALLING

    See the SCA_Topics CALLING help topic.

8.10  –  compilation_line_number

    A line number generated by the compiler which starts at 1 for
    the first file used during the compile and goes up by one for
    each line read. If there is an include file, the compilation line
    number is increased by one for each line in the include file. By
    default, the line numbers in the query display produced by the
    FIND or INSPECT commands are compilation line numbers.

8.11  –  compilation_unit

    A compilation unit is the smallest piece of source code that
    can be separately compiled. For example, in FORTRAN, this is
    a subroutine or function; in C, this is a single file. Some
    languages allow you to compile more than one compilation unit
    at once. Even if you compile more than one unit at a time, SCA
    considers the units to be separate.

8.12  –  consistency_checks

    A check that INSPECT makes in which all occurrences of a symbol
    are checked for consistency. For example, you can ensure that
    all calls to a routine have the correct number and type of
    arguments. In this type of check, each occurrence is compared
    with a single occurrence selected by INSPECT to be the standard
    against which all occurrences are checked. In this type of check,
    each particular occurrence is either correct or incorrect.

8.13  –  CONTAINED_BY

    See the SCA_Topics CONTAINED_BY help topic.

8.14  –  CONTAINING

    See the SCA_Topics CONTAINING help topic.

8.15  –  declaration

    Tells the compiler about an object before the compiler uses it.
    This can make the compiler create the object, or it can tell the
    compiler about an object that was created elsewhere. A declaration
    has a position in the source code with both a start and an end,
    and can contain other declarations or references. A declaration
    can be either a primary declaration or an associated declaration.

8.16  –  declaration_class

    Tells you what symbol class a declaration is (subroutine,
    function, variable). For example, both procedures and functions
    (in Pascal terms) belong to the routine symbol class, but their
    declaration classes are different. The declaration class tells
    the user whether a declaration is a primary declaration or
    an associated declaration. SCA uses the declaration class to
    decide what to display as the occurrence class in the result of a
    FIND command. The user can find the declaration class using the
    callable interface.

8.17  –  diagnostic_error_messages

    The error messages that INSPECT produces. The query result from
    an INSPECT command is like that of a FIND command, but with error
    messages attached to each occurrence.

8.18  –  display_line

    A line in the display resulting from a FIND or INSPECT command.
    SCA numbers these lines if you use /DISPLAY=NUMBER. This feature
    is most useful when you are saving the output in a file.

8.19  –  explicit

    See expression.

8.20  –  expression

    One of the attributes of an occurrence. The expression attribute
    tells you whether the occurrence is one that you the user placed
    in the source code, or is one which the compiler created for
    the user. An occurrence can be either explicit or implicit.
    Explicit occurrences are those placed by the user in the source
    code; implicit occurrences are those created by the compiler on
    behalf of the user. For example, in the following FORTRAN program,
    there are three references to i which are explicit. There is one
    implicit declaration of i which is created by the FORTRAN compiler
    when it sees the first reference to i.

      program test
      i = 0
      i = i + 1
      end

8.21  –  handle

    A data type used by the SCA callable interface. If you are using
    the callable interface, see the on-line SCA guide to
    platform specific information for more information.

8.22  –  hidden

    See both appearance and hidden modules.

8.23  –  hidden_modules

    A module in one of the libraries in the current library list which
    is also present in a library which is earlier in the library list.
    The module in the earlier library is visible. The same module in
    any later library is a hidden module, hidden by the first module.

8.24  –  implicit

    See expression.

8.25  –  indicated

    Uses the current cursor position for the query, when used with
    a FIND or GOTO DECLARATION. If the cursor is in a query display,
    SCA uses whatever occurrence on which it is positioned. If the
    cursor is in a buffer, SCA uses the name on which the cursor is
    positioned and the file the cursor is in to guide the query. SCA
    relaxes the search criteria, if necessary, (for example, allowing
    different versions of the source file) to find the indicated
    occurrence.

8.26  –  intersection

    The operation performed by the AND operator, which indicates
    that SCA will accept any occurrence that matches both X and Y
    as follows:

      FIND X AND Y

8.27  –  library

    Generic term usually referring to a physical library.

8.28  –  library_list

    A list of one or more physical libraries which compose the virtual
    library. The order of the physical libraries is important. A
    module found in one physical library in the library list hides
    the same module in other physical libraries that come later in the
    library list.

    For example, suppose you have three libraries. Library 1 contains
    module A. Library 2 contains modules A, B, and C. Library 3
    contains modules C and D. SCA uses module A from Library 1,
    modules B and C from library 2, and module D from library 3.

8.29  –  library_number

    Refers to the position of a single physical library in a library
    list. This can be used with any command that refers to a library
    already in the library list. For example, the command SET
    NOLIBRARY 1 removes the first library from the library list, and
    the command LOAD/LIBRARY=2 FOO.ANA loads the file FOO.ANA into the
    second library on the library list.

8.30  –  module

    Represents a single compilation unit. You can list the modules
    with the SHOW MODULE command. Each module shown represents a
    single compilation unit - the smallest piece of source that can
    be separately compiled. Even if several of these are compiled at
    once (which is common in languages such as FORTRAN and BASIC),
    each compilation unit appears separately.

    In the query language, SYMBOL=MODULE specifies a certain type
    of symbol. This is not the same as a compilation unit. You can
    have modules which are not compilation units, and compilation
    units which are not modules. How a module is defined varies from
    language to language.

8.31  –  name

    A string of characters used to identify symbols in your source
    code. Legal characters for a name are defined by whatever language
    you use. Each name has zero or more characters. Any character
    may appear in a name. Special characters that appear in a name
    must be quoted using double quotes. You do not need to quote the
    following: $, _, *, %, &, -, alphanumeric characters.

8.32  –  name_selection_expression

    Selects occurrences with a particular name. For example, you can
    specify the following:

      FIND name=xyz

    You can use wildcards in the name expression. Unlike other
    atttributes, you can omit "name=" from the expression and only
    specify the following:

      FIND xyz

8.33  –  nonstructured_relationship_expression

    A relationship query (such as CONTAINED_BY, CALLED_BY, CALLING)
    which requests that structure information be excluded. You can
    specify RESULT=NOSTRUCTURE, RESULT=BEGIN, or RESULT=END as one
    of the parameters to the relationship function. If you specify
    RESULT=BEGIN or RESULT=END, this is displayed like any query
    which does not have a relationship function. If you specify
    RESULT=NOSTRUCTURE, this is displayed like any query which does
    not have a relationship function, but has all the occurrences that
    would be present if the structure were present.

8.34  –  nonstructured_set

    A query result that contains occurrences, but does not contain any
    relationships between occurrences. These are produced by queries
    that do not involve relationship functions, or queries that do
    involve relationship functions but specify RESULT=NOSTRUCTURE,
    RESULT=BEGIN, or RESULT=END.

8.35  –  occurrence

    An occurrence is any instance of an entity in your program. An
    entity can be any language construct, such as a variable, a
    routine, or a constant. To further clarify this, consider the
    following code fragment (not written in a particular language):

      1   MODULE myprog;
      2
      3   VAR i,j;
      4
      5   ROUTINE foo()
      6   BEGIN
      7       i = 5;
      8       j = i;
      9   END;
      10  END;

    The code contains four entities: myprog, foo, i, j. There is one
    occurrence each of the module myprog, and the routine foo. The
    variable i, however, has three occurrences, and the variable j has
    two.

8.36  –  occurrence_checks

    A check that INSPECT performs on a single occurrence. For example,
    INSPECT can check whether an occurrence is an implicit declaration
    of a variable without having to look at any other occurrences.

8.37  –  occurrence_class

    One of the attributes of an occurrence that tells you what kind of
    occurrence it is. The occurrence class indicates if an occurrence
    is a declaration, a reference, or another class. It also indicates
    what kind of declaration or reference it is. You can instruct SCA
    to show you only occurrences with a particular occurrence class
    using the OCCURRENCE= attribute selection. For example, you can
    ask for write references using OCCURRENCE=WRITE.

8.38  –  occurrence_selection_expression

    The expression containing the occurrence class for each occurrence
    you want to find.

8.39  –  physical_library

    A single directory containing an SCA database. The directory
    should not contain anything else. SCA always locks an entire
    physical library when it accesses it. When you are reading a
    physical library (for example, with a FIND command), other users
    are not allowed to write to the physical library, but other users
    are allowed to read the physical library. When you are writing
    to a physical library (for example, using LOAD), no other user is
    allowed to read or write to the physical library.

8.40  –  primary_declaration

    Any declaration which affects how a particular object, such as a
    routine or a variable, is implemented.

8.41  –  primary_library

    The first library in the library list. Commands which change the
    SCA library, such as LOAD and REORGANIZE, apply to the first
    library, unless you use the /LIBRARY qualifier to instruct SCA
    to use another library.

8.42  –  query

    The question you ask SCA together with the information you receive
    from SCA. The question uses the SCA query language with the FIND
    or INSPECT commands. The answer is called a query result. You use
    the FIND or INSPECT commands to display the query result. You can
    also use the query result as part of the question for a subsequent
    query.

8.43  –  query_result

    A query result is the information you get when you evaluate a
    query, using the FIND or INSPECT commands. It consists of a set of
    occurrences, and relationships between occurrences.

8.44  –  reference

    The use of some object in the source code. For example: X = X + 1
    In this example, there are two references to the variable X. One
    (to the left of the =) is a write reference; the other is a read
    reference. A reference has a position in the source code, but it
    is a single point and cannot contain anything.

8.45  –  relationship

    An association between two different occurrences. For example, the
    CALLED_BY relationship in SCA associates a primary declaration of
    a procedure with call references to other procedures and functions
    in that procedure. A relationship has both a source and a target.
    A relationship also has a relationship type. Relationships go in
    both directions. For example, the CALLED_BY relationship is the
    inverse of the CALLING relationship.

8.46  –  relationship_type

    The kind of relationship between two occurrences. For example, a
    CALLED_BY relationship between a declaration of a routine FOO and
    a reference to a routine BAR shows that routine FOO calls routine
    BAR. The relationship types that are valid for SCA are: CALLED_BY,
    CALLING, CONTAINED_BY, CONTAINING, TYPED_BY, and TYPING.

8.47  –  set

    The occurrences that result from each query.

8.48  –  static_analysis

    The analysis of a software system performed by looking at the
    source code. This is in contrast to dynamic analysis, which is
    analysis of the software while it is running.

    SCA has some commands which do static analysis. These commands are
    the INSPECT command, which does consistency checking, the REPORT
    command, that can generate reports about modules, imported and
    exported objects, and so forth, and some uses of the FIND command,
    to generate call graphs and type graphs.

8.49  –  structured_relationship_expression

    A query that uses a relationship function (such as CONTAINED_
    BY, CALLED_BY, or TYPED) which asks for structure information.
    Structure information shows the relationships between occurrences
    found as well as the occurrences found. Structure information is
    provided by default.

8.50  –  structured_set

    A query result which has both occurrences and relationships
    between occurrences. These are produced by queries which involve
    relationship functions.

8.51  –  symbol

    Any object in a program. For example, a FUNCTION, a VARIABLE, a
    CONSTANT, or any of the entities with which a programmer typically
    deals.

    A symbol has occurrences. For example, the declaration of
    a variable is an occurrence, and uses of the variable are
    occurrences. SCA determines which occurrences belong to which
    symbols using the rules of the language you are using. For
    example, you may have two different variables named INDEX in
    separate subroutines. According to the rules of your language,
    these are usually different variables, so they are different
    symbols for SCA.

    It does not matter whether all occurrences of a symbol are in
    a single compilation unit, or spread over several compilation
    units. All the occurrences still belong to the same symbol. For
    example, you may have a subroutine SUB1 in one module, and calls
    to that subroutine in several other modules. These all appear as
    occurrences of the same symbol, named SUB1.

    The programmer and SCA should have the same definition of what
    constitutes a unique item. SCA's term for a unique item is symbol.

8.52  –  symbol_checks

    A check that INSPECT performs on all occurrences of a symbol.
    For example, INSPECT can ensure that there are both read and
    write references to a variable. In this type of check, no single
    occurrence is either correct or incorrect. If there are problems,
    the problems are with the symbol as a whole.

8.53  –  SYMBOL_CLASS

    An attribute selection that identifies the type of symbol. Tells
    you whether the symbol is a variable, constant, or some other
    class. You can use the FIND command to find only symbols with
    a particular symbol class. For example, you can specify "FIND
    symbol=argument." You can abbreviate both "symbol" and "argument".

8.54  –  symbol_class_selection_expression

    The expression containing the symbol class for each symbol you
    want to find.

8.55  –  type_graph

    A set of occurrences and relationships that describes a complex
    data type. For example, a declaration of a record consists of a
    record and some record components. Each record component has a
    type, which may be another record, a pointer to the same record,
    a basic data type such as integer, and so forth. In SCA, the type
    graph connects all these together, with relationships connecting
    the record to its components and the components to their types.

8.56  –  TYPED_BY

    See the SCA_Topics TYPED_BY help topic.

8.57  –  TYPING

    See the SCA_Topics TYPING help topic.

8.58  –  union

    The operation performed by the OR operator, which indicates that
    SCA will accept any occurrence that matches either X or Y as
    follows:

      FIND X OR Y

8.59  –  virtual_library

    A library that allows you to split your SCA library into pieces.
    Each piece is called a physical library. SCA works the same way
    whether your virtual library has only one physical library or
    several physical libraries.

    Some of the reasons for using more than one physical library are
    as follows:

    o  Physical libraries can be placed on more than one disk, if
       there is not enough room on a single disk.

    o  Analysis date files can be loaded into more than one physical
       library at the same time, to make LOAD run faster.

    o  A small personal physical library can be used to keep track of
       your personal changes without affecting other users.

    o  A separate physical library can be used for each major
       component in your system.

    A single virtual library is a list of one or more physical
    libraries. The order is important. A module in one physical
    library hides the same module in physical libraries later on in
    the list. This list of physical libraries is called a library
    list.

8.60  –  visible

    See both appearance and visible modules.

8.61  –  visible_modules

    Modules that SCA can examine when performing a FIND or INSPECT
    command. The current library list tells you what modules are
    visible. All modules in the first library in the library list
    are visible. Modules in the second library which are not in the
    first library are visible. Modules in the third library which are
    not in the first or second libraries are visible. Any module which
    is not visible is hidden.

8.62  –  wildcards

    Wildcards are used to match more than one name at once. There
    are two wildcards in SCA: the asterisk (*) and percent (%). For
    example, in the name expression A*, the wildcard * will match any
    number of characters, so this would match A, AB, ABC, AXYZ, and
    so forth. The * wildcard matches any number of characters, and %
    wildcard matches just one character. If you do not want SCA to use
    * or % as a wildcard, you use an ampersand (&) to quote it. For
    example, to find the single name *, you would use &*.

9  –  Language Specific Tables

    For information about SCA terms and corresponding language-
    specific terminology, see the tables under the Getting_Started
    help topic.

10  –  Libraries

10.1  –  Project Libraries

    There are many ways you can organize the SCA libraries for your
    project. Usually, there is one library (or set of libraries)
    for the whole project. Each developer has a personal library
    containing modules that they have changed but have not yet made
    available to the entire project. However, if there is only one
    developer working on the project, it makes more sense to use a
    single SCA library.

    There are many ways you can organize your project libraries. You
    can have one project SCA library if it is a reasonable size. You
    can use several libraries, one for each subsystem. You may want to
    organize your SCA libraries the way your development environment
    is organized. For example, have one SCA library for each CMS
    library. If your project is divided into different subsystems,
    you may want one SCA library for each subsystem.

    For information on creating your own SCA library, see the help
    topic Building_An_SCA_Library.

    Examples of Typical Libraries

    Consider a project with three developers: Paul, Mark, and Joanna.
    The project consists of five different subsystems. Each subsystem
    has its own SCA library in the following directories:

       DISK1:[PROJECT.SUBSYSTEM1.SCA]
       DISK1:[PROJECT.SUBSYSTEM2.SCA]
       DISK1:[PROJECT.SUBSYSTEM3.SCA]
       DISK2:[PROJECT.SUBSYSTEM4.SCA]
       DISK2:[PROJECT.SUBSYSTEM5.SCA]

    Each of the developers also has a personal SCA library as follows:

       DISK1:[PAUL.SCA]
       DISK2:[MARK.SCA]
       DISK1:[JOANNA.SCA]

    Paul uses the following command to set up his SCA libraries:

      LSE Command> SET LIBRARY disk1:[paul.sca], -
      _LSE Command> disk1:[project.subsystem1.sca], -
      _LSE Command> disk1:[project.subsystem2.sca], -
      _LSE Command> disk1:[project.subsystem3.sca], -
      _LSE Command> disk2:[project.subsystem4.sca], -
      _LSE Command> disk2:[project.subsystem5.sca]

    Mark and Joanna use the same command, but the first library in the
    list is their own SCA library.

    When Paul changes a module in Subsystem 1, he compiles it
    and loads it into his personal library in DISK1:[PAUL.SCA].
    For Paul, this hides the old version of the module in
    DISK1:[PROJECT.SUBSYSTEM1.SCA], so his SCA library is up to date
    and consistent with his changes.

    Mark and Joanna do not see Paul's changes in their SCA libraries
    because they are not using the SCA library (DISK1:[PAUL.SCA])
    that Paul updated. They still see the old version of the module in
    DISK1:[PROJECT.SUBSYSTEM1.SCA].

    Once Paul has completed his change, the nightly build
    updates everything for Subsystem 1, replacing the module in
    DISK1:[PROJECT.SUBSYSTEM1.SCA]. Now Mark and Joanna can both see
    the change.

10.2  –  Virtual Libraries

    SCA can use more than one SCA library at the same time when doing
    queries using the FIND and INSPECT commands. The list of SCA
    libraries used for this is called a virtual library. The order
    of SCA libraries in the library list is important. A module in
    the first library in the library list will hide the same module
    in other libraries, further on in the library list. For example,
    suppose PROJECT_LIB has modules A, B, C and library MYLIB has
    modules A, and D. You can set the library as follows:

      LSE Command> SET LIBRARY mylib,project_lib

    The modules visible in the virtual library would be A (from
    MYLIB), B, and C (both from PROJECT_LIB) and D (from MYLIB).

    There are many reasons for using more than one physical library as
    your virtual library:

    o  Using more than one library, you can improve LOAD performance
       by loading multiple libraries simultaneously. See the help
       topic Reducing_LOAD_Time.

    o  You can use virtual libraries to allow several developers to
       maintain a consistent view of their changes to a project,
       without affecting the other developers, and without having
       to copy the entire SCA library for each developer.

    o  You can put your SCA libraries on different disks or on
       different nodes (using the SCA server). This improves
       performance or takes advantage of the available disk space.

    o  You use the SET LIBRARY and SET NOLIBRARY commands to maintain
       your virtual library list. You can use the /BEFORE and /AFTER
       qualifiers to insert and remove libraries without having to
       reenter a library list. You can specify libraries in your
       library list using library numbers. For example, the command
       SET NOLIBRARY 2 removes the second SCA library from the library
       list.

11  –  New Users

    The Source Code Analyzer for OpenVMS (SCA) is an interactive cross-
    reference and static analysis tool that works with many languages.
    It can help you understand the complexities of a large software
    project. Because it allows you to analyze and understand an entire
    system, SCA is extremely useful during the implementation and
    maintenance phases of a project.

    SCA is included in the DECset Software Engineering Tools Package.
    SCA is tightly integrated with the Language-Sensitive Editor for
    OpenVMS (LSE). When SCA is used with LSE, you can interactively
    edit, compile, debug, navigate, and analyze source code during a
    single development session.

    For more information, see the following topics:

    o  Basic_Query_Concepts - Describes some of the basic concepts
       underlying SCA queries.

    o  Getting_Started - Provides subtopics with information about
       getting started with specific languages.

    o  SCA_Tutorial - Provides a sample session that allows you to get
       started after completing the session.

    o  Building_An_SCA_Library - Describes how to quickly create an
       SCA library.

    o  Advanced_Query_Examples - Provides advanced examples using the
       SCA$EXAMPLE library.

    o  Glossary - Provides definitions of SCA terms.

    o  Command_Categories - Lists the different types of SCA commands.

    o  Callable_Routines - Provides a complete description of each SCA
       callable routine.

    o  Callable_SCA - Provides guidelines for using the SCA callable
       interface.

    o  Libraries - Provides subtopics with information about project
       libraries and virtual libraries.

    o  Reducing_LOAD_Time - Provides guidelines for reducing your LOAD
       time.

    o  Quick_Reference_Card - Provides a pointer to the release
       notes, which contain a quick reference card for the SCA query
       language.

    Under SCA_Topics, there is help information for specific keywords.
    These keywords include attributes, relationships, and functions.
    For example, you can request help on SCA_Topics SYMBOL_CLASS to
    get information about the SYMBOL_CLASS attribute.

12  –  Reducing LOAD Time

    Loading an SCA library is a time-consuming operation. Here are
    suggestions for reducing LOAD time:

    o  Virtual I/O Cache facility

       SCA uses a large number of I/Os during LOAD. Disk caching can
       greatly reduce the number of I/Os, and improve performance.
       Your system manager can enable disk caching by setting the
       VBN_CACHE_S SYSGEN parameter.  Use SHOW MEMORY/CACHE to see
       whether disk caching is enabled.

    o  Batch loads

       Loading more than one module at a time is more efficient than
       loading modules separately. For example, use LOAD *.ANA.

    o  Multiple libraries

       With large software systems, it is a good idea to use more
       than one SCA library and load them all simultaneously. This
       can decrease the elapsed LOAD time considerably, especially
       if the libraries are on separate disks.  Using more than one
       CPU also helps, but not as dramatically, because SCA loading
       is mainly I/O intensive. For more information about how to use
       multiple libraries, see the help subtopics under Libraries.

    o  Choice of Disk

       SCA uses a large number of I/Os during LOAD. Loading an SCA
       library on a slow, heavily used, or badly fragmented disk
       causes the load to be less efficient.

    o  File Fragmentation and File Preallocation

       If your SCA library is larger than 20K blocks, you should
       consider preallocating the library when you create it.
       SCA extends the library file by 1000 blocks at a time, so for
       large libraries it extends the library many times, and this
       may cause your SCA library to be badly fragmented.

       Preallocate an SCA library with CREATE LIBRARY/SIZE=xxx, where
       xxx is the size of the library in disk blocks. Use the size of
       the SCA$EVENT.DAT file in your current SCA library directory as
       the value to the /SIZE qualifier.

       You can tell how badly your SCA libraries are fragmented by
       using the following command:

         $ DUMP/HEADER/BLOCK=COUNT=0 -
         _$ DISK:[sca_library_directory]SCA$EVENT.DAT

       The interesting portion of the output is the Map area. Each
       retrieval pointer represents a contiguous section on the disk.
       Because SCA extends SCA libraries 1000 blocks at a time, having
       a lot of retrieval pointers smaller than this is a strong
       indication that some defragmentation is needed.

    o  Using less disk space

       Use LOAD/DELETE to delete .ANA files after they are successfully
       loaded. This doesn't reduce LOAD time, but uses less disk space.

13  –  Quick Reference Card

       The following page contains a reference of the SCA query language.
       It is intended to be printed and used as a Quick Reference Card.

       ATTRIBUTE SELECTIONS:                  |RELATIONSHIP FUNCTIONS:
                                              |
       Name Class:                            |Short form:
       ----------                             |-----------
       <name-expression>                      |CALLED_BY(<caller>,<callee>,<depth>)
       NAME=<name-expression>                 |CALLING(<callee>,<caller>,<depth>)
       NAME=(<name-expression>,...)           |
                                              |CONTAINED_BY(<container>,<containee>,
       Symbol Class:                          |             <depth>)
       -------------                          |CONTAINING(<containee>,<container>,
       SYMBOL=<symbol-class-keyword>          |           <depth>)
       SYMBOL=(<symbol-class-keyword>,...)    |
                                              |TYPED_BY(<type>,<typee>,<depth>)
       Symbol Class keywords:                 |TYPING(<typee>,<type>,<depth>)
                                              |
       Argument, Component, Constant,         |Long form:
       Exception, File, Field, Function,      |----------
       Generic, Keyword, Label, Literal,      |<rel-func>(END=<query-expression>,
       Macro, Module, Package, Placeholder,   |           BEGIN=<query-expression>,
       Procedure, Program, Psect, Routine,    |           DEPTH={<number> | ALL },
       Subroutine, Tag ,Task, Type, Unbound,  |           RESULT=<result-keyword>,
       Variable, Other, All, None             |           TRACE=<query-expression>)
                                              |
       Occurrence Class:                      |Result keywords:
       -----------------                      |
       OCCURRENCE=<occ-class-keyword>         |Begin, End, [No]Structure, Any_path
       OCCURRENCE=(<occ-class-keyword>,...)   |
                                              |OTHER FUNCTIONS:
       Occurrence Class keywords:             |----------
                                              |
       Declaration, Primary, Associated,      |IN (END=<query-expression>,
       Reference, Address, Call,              |    BEGIN=<query-expression>)
       Command_line, Fetch, Include,          |
       Pointer, Precompiled, Read, Store,     |EXPAND (<query-expression>)
       Write, Other, All, None                |
                                              |@(<query-name>)
       Domain Class:                          |
       -------------                          |INDICATED()    (NOTE: LSE required)
       DOMAIN=<domain-class-keyword>          |
       DOMAIN=(<domain-class-keyword>,...)    |NOT(<query-expression>)
                                              |
       Domain Class keywords:                 |
                                              |
       Global, Inheritable, Module_specific,  |
       Multi_module, Predefined, All, None    |
                                              |
       File Class:                            |
       ----------                             |
       FILE=<filename-expression>             |
       FILE=(<filename-expression>,...)       |
                                              |
       OPERATORS:                             |
       ----------                             |
       AND, OR, XOR, Pathname (\ or \\)       |
                                              |
       ATTRIBUTE SELECTION EXPRESSIONS:       |
       <attri-select> [<op> <attri-select>]...|

14  –  SCA Tutorial

    This tutorial is for character cell LSE and SCA on
    the OpenVMS platform.  For a tutorial on the
    DECwindows interface, please see the DECset Guide to
    Source Code Analyzer.

    If you do not have DECwindows, you may want to have a hardcopy
    of this tutorial to follow it along interactively.  The directions
    for producing a hardcopy are as follows:

    1. Place the contents of SCA_Tutorial in a printable file
       by typing the following command on the DCL command line:

         $ 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.

15  –  \ (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.

16  –  @ (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

17  –  CALLED_BY

    The CALLED_BY function is a relationship function. It finds
    occurrences that have a CALLED_BY relationship between them.
    For example, if routine B is called by routine A, then these two
    occurrences are in a CALLED_BY relationship. In its most common
    form, the function format is as follows:

    CALLED_BY( <caller>, <callee>, DEPTH={<number> | ALL} )

    In this format, <caller> and <callee> can be any legal query
    expression, and <number> is a positive integer. A typical use
    of the function is to find those routines which are called by some
    specified routine. For example:

      FIND CALLED_BY( xyz, *, DEPTH=ALL )

    This query finds the full call tree below XYZ, where XYZ is some
    routine in the SCA database. In other words, this query finds all
    routines which are either directly or indirectly called by XYZ.

    The CALLED_BY function provides the power to return the exact call
    tree you want. The full format is as follows:

    CALLED_BY( [ END=<caller> ],
               [ BEGIN=<callee> ],
               [ DEPTH={<number> | ALL} ],
               [ RESULT=RESULT_KEYWORD ],
               [ TRACE=query_expression ] )

    In the previous format, <callee> and < caller> is any legal query
    expresion, <number> is a positive integer, RESULT_KEYWORD can
    be STRUCTURE, NOSTRUCTURE, ANY_PATH, BEGIN, or END, and QUERY_
    EXPRESSION is any legal query expression.

    For a full description of the CALLED_BY relationship, see the
    on-line help file SCACOMMANDS.

18  –  CALLING

    The CALLING function is a relationship function. It finds
    occurrences with the CALLING relationship between them. For
    example, if routine A is calling routine B, then these two
    occurrences are in a CALLING relationship. In its most common
    form, the function format is as follows:

    CALLING( <callee>, <caller>, DEPTH={<number> | ALL} )

    In this format, <callee> and <caller> can be any legal query
    expression and <number> is a positive integer. A typical use of
    the function is to find those routines which are calling some
    specified routine call. For example,

      FIND CALLING( abc, *, DEPTH=ALL )

    This query finds the full call tree above ABC, where ABC is some
    routine in the SCA database. In other words, find all the routines
    that are directly or indirectly calling ABC.

    The CALLING function provides the power to return the exact call
    tree of interest. The full format is:

    CALLING ( [ END=<callee> ],
              [ BEGIN=<caller> ],
              [ DEPTH={<number> | ALL} ],
              [ RESULT=RESULT_KEYWORD ],
              [ TRACE=query_expression ] )

    In the previous format, <callee> and <caller> is any legal query
    expresion, <number> is a positive integer, RESULT_KEYWORD can be
    STRUCTURE, ANY_PATH, BEGIN, or END, and QUERY_EXPRESSION is any
    legal query expression.

    For a full description of the CALLING relationship, see the
    on-line help file SCACOMMANDS.

19  –  CONTAINED_BY

    The CONTAINED_BY function is a relationship function. It finds
    occurrences that have a CONTAINED_BY relationship between them. In
    its most common form, the function format is as follows:

    CONTAINED_BY( <container>, <containee>, DEPTH={<number> | ALL} )

    In this format, <container> and <containee> can be any legal query
    expression, and <number> is a positive integer.

    Some examples will help you understand this function. The diagram
    that follows applies to these examples.

              A (module)
              +-------------------------+
              |                         |
              |  B (routine)            |
              |  +-------------------+  |
              |  |                   |  |
              |  |  C (routine)      |  |
              |  |  +-------------+  |  |
              |  |  |             |  |  |
              |  |  | D (variable)|  |  |
              |  |  |             |  |  |
              |  |  |             |  |  |
              |  |  +-------------+  |  |
              |  |                   |  |
              |  +-------------------+  |
              |                         |
              | E (variable)            |
              |                         |
              +-------------------------+

    Consider the following queries:

      1. FIND CONTAINED_BY( A, *, DEPTH=1 )
      2. FIND CONTAINED_BY( C, *, DEPTH=1 )
      3. FIND CONTAINED_BY( A, *, DEPTH=2 )

    The first query returns A (the container), B (a containee), and
    E (a containee). Similarly, the second query returns C and D.
    The third query returns A, B, and C and E. The D variable is NOT
    included because it is not reachable at a depth of two.

    Now consider the following two queries:

      4. FIND CONTAINED_BY( A, D, DEPTH=ALL )
      5. FIND CONTAINED_BY( A, D, DEPTH=2 )

    Query four returns A (the container), B (because it is on the path
    to D), C (becasue it is on the path) and D (which is the containee
    being searched for). The fifth query does not return anything
    because the D variable cannot be reached at a depth of two.

    Where a container begins and ends is determined by the language
    syntax. These boundaries are reported to SCA by the compiler and
    used by the CONTAINED_BY function to determine nesting.

    The CONTAINED_BY function provides the power to return the exact
    nesting structure you want. The full format is as follows:

    CONTAINED_BY( [ END=<container> ],
                  [ BEGIN=<containee> ],
                  [ DEPTH={<number> | ALL} ],
                  [ RESULT=RESULT_KEYWORD ],
                  [ TRACE=query_expression ] )

    In the previous format, <containee> and <container> is any legal
    query expression, <number> is a positive integer, RESULT_KEYWORD
    can be STRUCTURE, NOSTRUCTURE, ANY_PATH, BEGIN, or END, and QUERY_
    EXPRESSION is any legal query expression.

    For a full description of the CONTAINED_BY relationship, see the
    on-line help file SCACOMMANDS. See also the help topic for the IN function,
    which is similar to the CONTAINED_BY relationship.

20  –  CONTAINING

    The CONTAINING function is a relationship function. It finds
    occurrences that have a CONTAINING relationship between them.
    In its most common form, the function format is as follows:

    CONTAINING( <containee>, <container>, DEPTH={<number> | ALL} )

    In this format, <containee> and <container> can be any legal query
    expression, and <number> is a positive integer.

    Some examples will help you understand the CONTAINING function.
    The diagram that follows applies to these examples.

              A (module)
              +-------------------------+
              |                         |
              |  B (routine)            |
              |  +-------------------+  |
              |  |                   |  |
              |  |  C (routine)      |  |
              |  |  +-------------+  |  |
              |  |  |             |  |  |
              |  |  | D (variable)|  |  |
              |  |  |             |  |  |
              |  |  |             |  |  |
              |  |  +-------------+  |  |
              |  |                   |  |
              |  +-------------------+  |
              |                         |
              | E (variable)            |
              |                         |
              +-------------------------+

    Consider the following queries:

      1. FIND CONTAINING( D, *, DEPTH=1 )
      2. FIND CONTAINING( C, *, DEPTH=1 )
      3. FIND CONTAINING( D, *, DEPTH=2 )

    The first query returns D (the containee), and C (the container).
    Similarly, the second query returns C and B. The third query
    returns D, C and B.

    Now consider the following 2 queries:

      4. FIND CONTAINING( D, A, DEPTH=ALL )
      5. FIND CONTAINING( D, A, DEPTH=2 )

    Query four returns D (the containee), C (because it is on the
    path to A), B (because it is on the path) and A (which is the
    container being looked for). The fifth query does not return
    anything because A cannot be reached at a depth of two.

    Where a container begins and ends is determined by the language
    syntax. These boundaries are reported to SCA by the compiler and
    used by the CONTAINING function to determine nesting.

    The CONTAINING function provides the power to return the exact
    nesting structure you want. The full format is as follows:

    CONTAINING( [ END=<containee> ],
                [ BEGIN=<container> ],
                [ DEPTH={<number> | ALL} ],
                [ RESULT=RESULT_KEYWORD ],
                [ TRACE=query_expression ] )

    In the previous format, <containee> and <container> is any legal
    query expression, <number> is a positive integer, RESULT_KEYWORD
    can be STRUCTURE, NOSTRUCTURE, ANY_PATH, BEGIN, or END, and QUERY_
    EXPRESSION is any legal query expression.

    For a full description of the CONTAINING relationship, see the
    on-line help file SCACOMMANDS.

21  –  DOMAIN

    DOMAIN is an attribute of an occurrence that determines the scope
    of the symbol defined. It is the range of source code in which a
    symbol has the potential of being used.

    For example, A BLISS OWN declaration creates a symbol that has
    a module-specific symbol domain; it cannot be used outside that
    module. On the other hand, a BLISS GLOBAL declaration creates a
    symbol that has a multimodule symbol domain; it has the potential
    of being used in more than one module.

    The format for DOMAIN is as follows:

    DOMAIN=(keyword[,keyword...])

    The keyword can be one of the following:

    o  INHERITABLE - able to be inherited into other modules (for
       example, through BLISS library, PASCAL environment, or Ada
       compilation system mechanisms)

    o  GLOBAL - known to multiple modules via linker global symbol
       definitions

    o  PREDEFINED - defined by the language (examples: BLISS ap,
       FORTRAN sin, PASCAL writeln)

    o  MULTI_MODULE - domain spans more than one module (domain=multi_
       module is equivalent to domain=(inheritable,global,predefined)

    o  MODULE_SPECIFIC - domain is limited to one module

    The previous keywords are SCA terms. For information on
    corresponding language-specific terms, request help for the
    appropriate language table (for example, FORTRAN_ATTRIBUTES_TABLE)
    under the Getting_Started help topic.

    An example using the DOMAIN attribute follows:

      FIND DOMAIN=GLOBAL AND SYMBOL=VARIABLE

    This query find all global variables.

22  –  EXPAND

    The EXPAND function determines the symbol to which an occurrence
    belongs and returns the full set of occurrences for the symbol.

    For example, the following code fragments, written in a pseudo
    language, declare and use the variable i in three files.

      file 1          file 2          file 3
      ------          ------          ------

      GLOBAL i (d)    LOCAL i (d)     EXTERNAL i (d)

      i := 0 (wr)     i := 5 (wr)     IF i EQUALS 0 (rr)

      (d)  - declaration
      (wr) - write reference
      (rr) - read reference

    The pseudo language defines variables, such that the variable i
    in "file 1" and the variable i in "file 3" are the same variable.
    The variable i in "file 2", however, is a different variable. SCA
    treats these variables in the same manner by saying there are two
    unique symbols which happen to have the same name.

    The important point in the previous example is that what the
    programmer considers unique items SCA also considers unique items.
    In SCA terms, these items are symbols.

    Given the previous code fragments, consider the follwoing query:

      FIND SYMBOL_CLASS=VARIABLE AND OCCURRENCE=READ

    This query returns one occurrence, which is the read reference in
    "file 3." Now consider the next query:

      FIND EXPAND( symbol_class=variable and occurrence=read )

    This query returns two occurrences of "i" in "file 1" and the two
    occurrences of "i" in "file 3." The EXPAND function uses the read
    reference to determine the corresponding symbol and then returns
    all the occurrences for that symbol. In this case the symbol was
    the global variable "i".

    Note that the two occurrences in "file 2" are not returned because
    they belong to a different symbol. The programmer does not view
    the i in "file 2" to be the same as the i in "file 1" and "file 3"
    and SCA reflects that view.

    When given more than one occurrence, the EXPAND function performs
    this operation iteratively and removes any duplicate occurrences
    from the result.

    In the following example, you use the EXPAND function to find the
    declarations of routines defined in the system, but which are not
    used. To do this, specify the following query:

      FIND (SYMBOL=ROUTINE AND OCCURRENCE=PRIMARY) AND NOT
      EXPAND(SYMBOL=ROUTINE AND OCCURRENCE=REFERENCE)

23  –  FILE_SPEC

    FILE_SPEC is an attribute selection that specifies the name of the
    file. You identify a source file by its OpenVMS file specification.
    You should enclose the file specification in quotation marks
    because it normally contains a period (.)

    The format for the FILE_SPEC attribute is as follows:

    FILE_SPEC="filename.filetype"

    An example using the FILE_SPEC attribute follows:

      FIND FILE_SPEC="MYPROG.FOR"

    This query finds all occurrences in the file MYPROG.FOR.

24  –  IN

    The IN function searches for occurrences inside a container. The
    IN function is a special case of the CONTAINED_BY function. In its
    most common form, the function format is as follows:

    IN( <container>, <containee> )

    In this format, <container> and <containee> can be any legal query
    expression. The IN function returns all occurrences that match the
    <containee> expression as long as those occurrences are somewhere
    inside the container.

    Some examples will help you understand the IN function. The
    following picture applies to the examples that follow.

              A (module)
              +-------------------------+
              |                         |
              |  B (routine)            |
              |  +-------------------+  |
              |  |                   |  |
              |  |  C (routine)      |  |
              |  |  +-------------+  |  |
              |  |  |             |  |  |
              |  |  | D (variable)|  |  |
              |  |  |             |  |  |
              |  |  |             |  |  |
              |  |  +-------------+  |  |
              |  |                   |  |
              |  +-------------------+  |
              |                         |
              | E (variable)            |
              |                         |
              +-------------------------+

    Consider the following queries:

      1. FIND IN( A, *)
      2. FIND IN( B, D)
      3. FIND IN( A, SYMBOL_CLASS=ROUTINE and OCCURRENCE=DECLARATION)

    The first query returns B (a containee), C (a containee), D (a
    containee) and E (a containee). A is not returned because it is
    the container.

    The second query returns only D (the containee). C is not returned
    because it does not match the <containee> expression. B is not
    returned because it is the container.

    The third query returns all routine declarations inside A. In this
    case, B and C are returned.

    The IN function is a convenient way to limit a query to a
    particular container.

    The full format of the In function is as follows:

    IN( [END=<container>],
        [BEGIN=<containee>] )

    In this format, <container> and <containee> can be any legal query
    expression.

25  –  INDICATED

    The INDICATED function is available only from within LSE. The
    INDICATED function matches the occurrence on which the cursor is
    positioned. The INDICATED function has no parameters. The format
    is as follows:

    INDICATED()

    An example of using the INDICATED function is as follows:

      FIND EXPAND( INDICATED() )

    This query finds all occurrences of the item on which the cursor
    is positioned in LSE.

26  –  NAME

    NAME is an attribute of an occurrence that is a string of ASCII
    characters which identifies symbols in your source code. A
    specific name can be associated with more than one symbol.

    The language you are using defines the legal characters for
    a name. Each name has zero or more characters. Any character
    may appear in a name. Special characters that appear in a name
    must be quoted using double quotes. You do not need to quote the
    following: $, _, *, %, &, -, alphanumeric characters.

    You can use wildcards (* and %) in the name expression. You can
    override the wildcard characters by using the escape character
    (&). For example, you can find the name consisting of a single
    asterisk using the name expression &*. If you want an ampersand in
    a string, you must use two successive ampersands.

    The format for NAME can be one of the following:

    name
    NAME=(name[,name...])

27  –  OCCURRENCE

    The occurrence class is an attribute of an occurrence that
    identifies the type of occurrence. The occurrence class indicates
    if the occurrence is a declaration, a reference, or one of the
    other classes in the list that follows. If the occurrence class is
    a declaration or reference, the occurrence class indicates what
    type of declaration or reference it is.

    The format for the occurrence class attribute is as follows:

    OCCURRENCE=(keyword[,keyword...])

    The occurrence class can be one of the following keywords:

    Declarations

    o  PRIMARY - most significant declaration

    o  ASSOCIATED - associated declaration

    o  DECLARATION - primary or associated

    References

    o  READ, FETCH - fetch of a symbol value

    o  WRITE, STORE - assignment of a symbol value

    o  ADDRESS, POINTER - reference to the location of a symbol

    o  CALL - call to a routine or macro

    o  COMMAND_LINE - command line file reference

    o  INCLUDE - source file include referenece

    o  PRECOMPILED - precompiled file include referenece

    o  OTHER - any other kind of reference (such as a macro expansion
       or use of a constant)

    o  REFERENCE - any of the preceding values

    o  BASE - Any base class of a C++ class

    o  FRIEND - Any friend of a C++ class

    o  MEMBER - Any member of a C++ class

    o  SPEPARATE - Any Ada package or sub-program unit defined
       as SEPARATE

    o  WITH - Any WITH of an Ada package or sub-program unit

    Other Occurrence Classes

    o  EXPLICIT - explicitly declared

    o  IMPLICIT - implicitly declared

    o  VISIBLE - occurrence appears in the source

    o  HIDDEN - occurrence does not appear in the source

    o  COMPILATION_UNIT - the declaration that contains all
       occurrences in a particular compilation unit

    o  LIMITED - Any Ada limited private type

    o  PRIVATE - Any private C++ objects, or Ada private type

    o  PROTECTED - Any protected c++ object

    o  PUBLIC - Any public C++ object

    o  VIRTUAL - Any virtual C++ object

    The previous keywords are SCA terms. For information on
    corresponding language-specific terms, request help for the
    appropriate language table (for example, FORTRAN_ATTRIBUTES_TABLE)
    under the Getting_Started help topic.

    An example using the occurrence class attribute follows:

      FIND OCCURRENCE=PRIMARY

    This query finds all PRIMARY occurrences of declarations.

28  –  SYMBOL_CLASS

    SYMBOL_CLASS is an attribute selection that identifies the type of
    symbol. A symbol can be a variable, constant, or some other class.

    The format for SYMBOL_CLASS is as follows:

    SYMBOL_CLASS=(keyword[,keyword...])

    The SYMBOL_CLASS can be one of the following keywords:

    o  ARGUMENT - formal argument (such as a routine argument or macro
       argument)

    o  CLASS - Any C++ class object construct defined by the union,
       structure or class statements

    o  COMPONENT,FIELD - component of a record

    o  CONSTANT,LITERAL - named compile-time constant value

    o  EXCEPTION - exception

    o  FILE - file

    o  FUNCTION,PROCEDURE, PROGRAM,ROUTINE, SUBROUTINE - callable
       program function

    o  GENERIC - generic unit

    o  KEYWORD - keyword

    o  LABEL - user-specified label

    o  MACRO - macro

    o  MODULE, PACKAGE - collection of logically related elements

    o  PLACEHOLDER - marker where program text is needed

    o  PSECT - program section

    o  TAG - comment heading

    o  TASK - task

    o  TYPE - user-defined type

    o  UNBOUND - unbound name

    o  VARIABLE - program variable

    o  OTHER - any other class of symbol

    The previous keywords are SCA terms. For information on
    corresponding language-specific terms, request help for the
    appropriate language table (for example, FORTRAN_ATTRIBUTES_TABLE)
    under the Getting_Started help topic.

    An example using the SYMBOL_CLASS attribute follows:

      FIND X AND SYMBOL_CLASS=ROUTINE

    This query finds all routines named X.

29  –  TYPING

    The TYPING function is a relationship function. It finds the type
    of some occurrence. Occurrences related in this manner have a
    TYPING relationship between them. For example, if INTEGER is
    typing variable X, then these two occurrences are in a TYPING
    relationship. In its most common form, the function format is as
    follows:

    TYPING( <typee>, <type>, DEPTH={<number> | ALL} )

    In this format, <typee> and <type> can be any legal query
    expression, and <number> is a positive integer. A typical use
    of the function is to find the type of a variable. For example:

      FIND TYPING( X, *, DEPTH=1)

    This query finds the type of X, where X is some variable in the
    SCA database.

    The TYPING function also works on user-defined types. The defined
    type can have many levels, in which case the user can specify a
    depth as follows:

      FIND TYPING( user_defined_type, *, DEPTH=ALL)

    This query gives the full type tree for USER_DEFINED_TYPE.

    The TYPING function provides the power to return the exact type
    tree you want. The full format is as follows:

    TYPING( [ END=<typee> ],
            [ BEGIN=<type> ],
            [ DEPTH={<number> | ALL} ],
            [ RESULT=RESULT_KEYWORD ],
            [ TRACE=query_expression ] )

    In the previous format, <typee> and <type> is any legal query
    expression, <number> is a positive integer, RESULT_KEYWORD can
    be STRUCTURE, NOSTRUCTURE, ANY_PATH, BEGIN, or END, and QUERY_
    EXPRESSION is any legal query expression.

    For a full description of the TYPING relationship, see the
    on-line help file SCACOMMANDS.

30  –  TYPED_BY

    The TYPED_BY function is a relationship function. It finds
    occurrences that have a TYPED_BY relationship between them.
    For example, if variable X is typed by INTEGER, then these two
    occurrences are in a TYPED_BY relationship. In its most common
    form, the function format is as follows:

    TYPED_BY( <type>, <typee>, DEPTH={<number> | ALL} )

    In this format, <typee> and <type> can be any legal query
    expression, and <number> is a positive integer. A typical use
    of the function is to find what is being typed by INTEGER. For
    example:

      FIND TYPED_BY( INTEGER, *, DEPTH=1)

    This query finds everything that is of type INTEGER. The TYPED_BY
    function can also tell you the items that are in some way affected
    by a given type. The type can be predefined by language elements
    such as INTEGER, or can be user defined. For example:

      FIND TYPED_BY( user_defined_type, *, DEPTH=ALL)

    This query finds all the items that are directly or indirectly
    affected by USER_DEFINED_TYPE.

    The TYPED_BY function provides the power to return the exact type
    tree you want. The full format is as follows:

    TYPED_BY( [ END=<type> ],
              [ BEGIN=<typee> ],
              [ DEPTH={<number> | ALL} ],
              [ RESULT=RESULT_KEYWORD ],
              [ TRACE=query_expression ] )

    In the previous format, <type> and <typee> is any legal query
    expression, <number> is a positive integer, RESULT_KEYWORD can
    be STRUCTURE, NOSTRUCTURE, ANY_PATH, BEGIN, or END, and QUERY_
    EXPRESSION is any legal query expression.

    For a full description of the TYPED_BY relationship, see the
    on-line help file SCACOMMANDS.
Close Help