sxt.doc

Graphically Assisted Programming Interface

        -    number of included files for every source file,
        -    total  effective number of scanned bytes and lines for every
             source file and its included files,  if files  are  included
             multiple times, this will influence the calculations,
        -    for every defined function the number of lines, the code and
             comment  size  in bytes,  the number of bytes per line,  the
             number of functions  called,  the  number  of  flow  control
             statements (if,  else,  for,  while,  case,  default,  goto,
             return,  exit),  the maximum brace nesting level and if  the
             function is used only inside the file,
        -    for  every  defined  structure/union  the  total  number  of
             elements and the number of  elements  which  are  themselves
             structures/unions,
        -    file function or data type reference list for every file,
        -    total  number of displayed,  defined,  undefined or multiple
             defined functions and data types,
        -    location of all multiple defined functions and data types,
        -    location of all overloaded C++ functions,
        -    source file - include file  dependencies  for  every  source
             file (MAKE-dependencies),
        -    final statistical summary for all files,
        -    cross  reference  of  every occurrence for every function or
             data type,
        -    parent/children relationship for  every  function  and  data
             type,
        -    critical  function  call path/structure nesting with deepest
             non-recursive nesting level (unlimited tree depth),
        -    C++ class inheritance graph,
        -    FORTRAN subroutine CALLs,
        -    FORTRAN COMMON blocks,
        -    generation of description file  for  call/inheritance  graph
             visualisation with the RATIONAL ROSE CASE tool
             ...

        The resulting hierarchy structure chart is another representation
        for  a  directed  call  graph.  A directed call graph consists of
        nodes (functions or data types) and connections (call  relations)
        between  these  nodes.  The number of nodes and connections which
        are necessary to transform the hierarchy structure chart  into  a
        directed  call  graph  will  also  be calculated as an additional
        information about the system complexity.







                                     - 11 -


        A large number of options to control the  program  execution  and
        the  output  generation  are  available and can be defined on the
        command line,  with interactive dialog windows (applies  only  to
        Windows  versions),  by  command  files or by defining them in an
        environment variable used by the program.

        CFT,  CST and the other SXT programs can be directly invoked from
        inside  editors  or  integrated development environments like the
        Borland C++ IDE.  Detailed examples for the integration  together
        with necessary macro or batch files are given.
















































                                     - 12 -


        3    LANGUAGE IMPLEMENTATIONS

        3.1  C-LANGUAGE IMPLEMENTATION AND C-PREPROCESSOR

        The  ISO/ANSI  C  language  standard  ISO/IEC 9899:1990 (E) resp.
        X3.159-1989-ANSI C  as  described  in  several  books  about  the
        C-language  (see references) was used as a development base.  The
        reserved keywords being recognised  are  not  only  the  original
        ISO/ANSI  C  keywords  but  were also taken from several compiler
        implementations like Microsoft,  Borland or  GNU  and  their  own
        special  language  extensions.  The  books  "The  C++ Programming
        Language" and "The Annotated C++ Reference Manual" (ARM) together
        with informations about the work of the ANSI C++ committee  X3J16
        resp.  the  ISO/IEC working group SC22 WG21 were used for the C++
        keywords.  Another major source was the  AT&T  C++  release  2.1.
        Compiler   specific  extensions  especially  from  GNU  are  also
        recognised.  Proposed extensions to C  and  C++  like  additional
        keywords (e.g.  wchar_t,  bool, namespace, using, ...) and the so
        called 'digraphs' will be supported if they are  introduced  into
        the language standard.

        A  complete  list of all reserved keywords is show in appendix 2.
        The large set of keywords may lead to  some  slight  problems  in
        situations  where  a  keyword  is  not  used  as itself but as an
        identifier name,  for example a C++ keyword used as an identifier
        in C.

        During a normal file scan,  precompiler defines are, if possible,
        handled as if a real precompiler would be present,  but this  can
        cause  some  trouble  with '#if',  '#ifdef' and other precompiler
        controls which are not evaluated.  Also the block nesting  level,
        which will be monitored by the source code scanner, may not be at
        level  0  at  the  end  of  the  file because of such precompiler
        controls. To avoid such things,  a built-in C-preprocessor allows
        the  complete  preprocessing of the source code and include files
        for several compiler types as an additional option (-P).

        Preprocessing or not is a little bit controversial because it can
        either result in a loss of information  if  macros  are  used  to
        change the program behaviour and hide function calls, it can lead
        to  errors during file scanning or it can change the function and
        data type informations obtained  from  the  code  which  may  not
        exactly correspond to the visible source code.  Preprocessing can
        be an advantage or not, so the user has to decide whether he does
        it or not (see options -P, -I, -E for more informations).

        The  preprocessor  handles  the  defines  for  Microsoft  C  5.1,
        Microsoft  C/C++  7.0,  Microsoft  VC++  1.0 for Windows NT (Beta
        Release June 1993), Turbo C++ 1.0,  Borland C++ 2.0,  Borland C++
        3.1,  GNU-C  and  Intel 80960 C compiler iC960 3.0 and all memory
        models (not necessary for GNU-C and I960)  or  CPU  architectures
        for the Intel 80960 32 bit RISC processor (KA,  KB,  SA,  SB, MC,
        CA).  Other compiler types can be customised with the -B and  the
        -D options.  The default ISO/ANSI C predefined macros '__FILE__',
        '__LINE__',    '__DATE__',    '__TIME__'   are   generated    for
        preprocessing.   The   macro  '__STDC__'  is  NOT  defined  (some


                                     - 13 -


        compilers test with '#ifndef __STDC__'),  so  that  non  standard
        ISO/ANSI C extensions in the processed code are allowed. Defining
        '-D__STDC__=1'  forces  ISO/ANSI  C conforming output (if used by
        the  scanned  source  code,  of  course!).  Additional  supported
        precompiler  defines  are  '__TIMESTAMP__',  '__BASE_FILE__'  and
        '__INCLUDE_LEVEL__'.   A  list  of  the  predefined  preprocessor
        defines  for the supported compiler types is shown in appendix 1.
        Features like the replacing of trigraphs and the  recognition  of
        C++ comments '//...' are also treated by the preprocessor.

        The precompiler recognises several errors or possible sources for
        problems like

        -    the use of undefined variables in precompiler controls,
        -    misbalanced  '#if...'  control  block(s) including the exact
             location (file, line) where the failing block started,
        -    recursive called include files,
        -    nested include files,
        -    wrong number of macro arguments (missing ones or too many)

        and displays diagnostic messages with an exact description of the
        error or warning reason and its location in the source file.


        3.2  C++ LANGUGAE IMPLEMENTATION

        For the description of the related  C++  language  standards  and
        other   literature   see   the   chapter  about  the  C  language
        implementation.

        Although CFT and CST were initially not developed to process  C++
        code  it  is  possible  to  do so.  In that case,  however,  some
        restrictions and limitations should be considered.

        The recognition of C++ classes by  CST  is  limited  because  the
        handling  of  the  internal  class structure items (variables and
        functions) is too complex to fit in the CST program.  So  classes
        are only referenced by name but their internal structure will not
        be scanned and displayed. The C++ class inheritance relationships
        are  recognised  and  shown  in  a  class hierarchy graph listing
        (option -b).  Structures in C++ with function names as  structure
        members  will  not  be  processed  correctly.  Templates  are not
        supported and will not be recognised.

        Calling member functions will not be recognised correctly due  to
        missing  class  name,  this leads also to an incomplete call tree
        and a lot of warnings during  analysis.  The  use  of  overloaded
        functions  with  equal  names  but  different  parameters  in C++
        programs may lead to incorrect calling relationships.  A variable
        initialization  with  parameters  will  be  misinterpreted  as  a
        function call. A correct handling of these and other C++ features
        requires a complete C++ source code analyser to keep track of the
        class functions belong to and the different calling parameters.





                                     - 14 -


        If precise informations about C++ code are needed, utilities like
        'class hierarchy browsers' or 'class viewers',  which are usually
        (or should be) part of C++ compiler environments,  should be used
        instead.

        Because of the above described reasons, some care should be taken
        if C++ code is processed and displayed.


        3.3  DBASE SOURCE CODE

        DFT can process source code which is based on  the  DBASE  III/IV
        programming language. This means that also source code written in
        DBASE  derivatives  like  CLIPPER  (Summer '87) or FOXBASE can be
        analysed.  The source code analyser tries to  be  as  correct  as
        possible to build a reliable hierarchy tree. A function/procedure
        declaration  is  recognised  by  the  FUNCTION  resp.   PROCEDURE
        keyword. A function/procedure call is recognised by the following
        statements:

             function()
             CALL function
             CALL function WITH parameters
             DO function
             DO function WITH parameters

        If  a  file  contains  no  function/procedure  declaration,   the
        filename  itself  is taken as procedure name.  The recognition of
        builtin functions/procedures can be ignored (see option -E).  All
        tokens   are   assumed  case-insensitive  and  are  converted  to
        upper-case characters. Include files (e.g.  with CLIPPER) are not
        processed.


        3.4  FORTRAN SOURCE CODE

        FFT can process source which is based on the FORTRAN 77 standard.
        Each  FORTRAN  line  is  divided  into  fields  for  the required
        information, each column represents a single character.

             COLUMN    FIELD
                  1    comment indicator (C,c,*,!)
                1-5    label
                  6    indicator for line continuation
               7-72    statement field

        Continuation lines  are merged  before  they  are  analysed.  The
        number  of  continuation lines is 19 by default and can be varied
        between 0 and 99 (option -qn).  Inline comments in the  statement
        field start with '!',  the text until end of line is ignored. The
        standard  intrinsic  functions   and   additionally   VAX-FORTRAN
        intrinsic  functions are recognised.  Hollerith constants are not
        recognised and handled.  All tokens are assumed  case-insensitive
        and  are  converted  to  upper-case  characters.  Blanks  are not
        significant and are not handled,  they  will  be  removed  except
        inside character strings. If option -I is set, INCLUDE statements


                                     - 15 -


        are  recognised    and  processed.  To handle this implementation
        dependent feature,  two different types of include statements are
        accepted:

        C FORTRAN-LIKE SYNTAX, INCLUDE STATEMENT STARTS IN COLUMN 7
              INCLUDE 'FILENAME'           ! SINGLE QUOTATION MARKS
              INCLUDE FILENAME             ! WITHOUT QUOTATION MARKS

        C C-LIKE SYNTAX, INCLUDE STATEMENT STARTS IN COLUMN 1 WITH #
        #INCLUDE "FILENAME"                ! DOUBLE QUOTATION MARKS
        #INCLUDE FILENAME                  ! WITHOUT QUOTATION MARKS

        The  resulting  function  call  graph may be incorrect due to the
        ENTRY capability of FORTRAN which  allows  direct  jumps  into  a
        function  or  subroutine  body.  This  may  result  in  incorrect
        relationships  for  the  ENTRY  statement  and  the   surrounding