sxt.doc

Graphically Assisted Programming Interface

        call  of a local label correctly.  CFT sometimes displays warning
        messages about 'return type mismatch' though this may be  correct
        in  that  special  case  because  the different types are earlier
        defined by a 'typedef' declaration. The reason is simply that CFT
        doesn't recognise these 'typedef's (but CST does!), it looks only
        for function names.

        An often requested feature for CST  is  the  integration  of  the
        calculation   of   structure/union   sizes   with   byte   offset
        informations for every structure/union member.  This  feature  is
        not  implemented  in CST although it would be possible to do this
        because all necessary informations are  present.  The  reason  is
        that  there  would  be  too  much  overhead  for CST to treat the
        various compiler implementations with their different basic  type
        sizes (sizeof(int),  sizeof(long double)) for different processor
        types (16 bit,  32 bit,  64 bit,  ...) and  data  type  alignment
        requirements  (by default and also controlled with #pragma's like
        'align' or 'pack').  It would be possible to do this for just one
        selected  compiler implementation or processor type but not for a
        great  number  of  them.   Especially  compilers   for   advanced
        architectures  like  RISC  processors  have very complicated type
        alignments rules depending on the data types,  alignment pragmas,
        compiler  switches,  type  sizes,  available  register number and
        register  sizes  and  resulting  structure/union/class  sizes  to
        generate  highly  optimised  code.   This  includes  usually  the
        insertion of 'fill' bytes inside a structure/union and  sometimes
        'padding  bytes' at the end of a structure/union to force aligned
        sizes on specific byte boundaries (For examples see the reference
        manual of the Intel 80960 C-Compiler iC960, release 3.0). Because
        of these reasons,  an integrated 'byte offset calculation' is not
        implemented in CST.  Instead,  you can generate a source file for
        selected  data  types  with  option  -O,   that  performs   these




                                     - 21 -


        calculations,  if  you  compile  the  generated  file with your C
        compiler. For further informations see the description for option
        -O.

        Option -z  in  combination  with  option  -I  produces  redundant
        results  with CFT,  CST and FFT if files with executable code (or
        something that can be interpreted as that,  e.g.  function calls,
        data  types  or  COMMON  blocks)  are  included directly inside a
        function or data type block. (Especially in FORTRAN this seems to
        be common practice to include COMMON  blocks  into  function  and
        subroutine  bodies.)  For  CFT and CST (but not for FFT) also the
        call tree references will be incomplete and therefore  incorrect.
        With option -P for CFT and CST everything works fine, because the
        preprocessor  works  more  precise  as  the simple file inclusion
        mechanism option -I uses.

        SUMMARY

        The above described limitations can lead in  some  situations  to
        misinterpretations  or loss of informations of the scanned source
        code. The only way to avoid these lacks would be the inclusion of
        parts of a 'real compiler' to handle the complete language syntax
        in any possible situation.  But this was not the  intention  when
        the  development  of  these  programs as 'little' and easy to use
        general purpose programming supporting tools  began.  Although  I
        hope  that  the  SXT  programs will in most cases be powerful and
        useful development and documentation tools!































                                     - 22 -


        7    IMPROVING EXECUTION SPEED

        CFT and CST are disk storage based programs  because  the  source
        and  include  files,  the  intermediate  precompiler file and the
        output file must be read from and  written  to  hard  disk.  This
        means that the execution speed of CFT and CST depends at first on
        the  speed  of  the physical storage medium and not (only) on the
        speed of the CPU.  There are several ways to improve the  program
        performance:

        -    install a RAM-disk and
             a)   start  CFT  and CST from there so that the intermediate
                  file and the resulting output file will be stored there
                  (but don't forget to copy the output file to  the  hard
                  disk before power-off), or
             b)   use  the  -v  option  to  redirect only the precompiler
                  output file (scanner input file) to the  RAM-disk  from
                  anywhere  the  program is started (the RAM-disk must be
                  large enough to hold  the  largest  possible  temporary
                  file, otherwise a disk-write error will occur),
        -    use a hard disk cache program like SmartDrive,  HyperDisk or
             PC-Cache,
        -    use a faster hard disk,
        -    and finally, of course, use a faster and more powerful CPU.

        The most effective combination is option -v with  a  RAM-disk  as
        destination  path and hard disk caching together with a fast hard
        disk drive. If the disk cache is large enough to hold most of the
        frequently called include files, the execution speed is about 2.5
        to 3 times faster than without.  This is a  significant  speed-up
        especially  for  projects  with  a large number of files and many
        included files in each source file.

        During program execution with preprocessing (option -P),  most of
        the time will be consumed to preprocess the given input files and
        the related include files and to generate the preprocessor output
        file.  The scanning for functions (CFT) or data types (CST) takes
        only a small amount of time. The function/data type relations are
        computed while the output is generated and written to disk, there
        is no precomputing necessary.

        The function  for  critical  call  path/nesting  level  detection
        depends  only on the number of functions or structures and not on
        the call/declaration nesting complexity. The execution time grows
        linear with the number of items (functions/structures) to process
        and is very fast!

        Be aware of the fact that the processing of  a  large  number  of
        files  can  take  quite  a  long time (from several minutes up to
        hours on lower performance machines!),  especially if  option  -P
        for preprocessing is enabled.

        The  generation  of  the output file and writing to disk can also
        take some time if the number of items to display is large and the
        nesting structure is complex or if there is  no  cross  reference
        option  enabled  (see -x and -r for further information).  If the


                                     - 23 -


        number of items is very large,  one of the  most  time  consuming
        options is the function/data type file reference (option -z). The
        writing  and  reading  of  the database files (options -G and -g)
        takes also some  time  due  to  the  large  number  of  different
        informations.

        Don't  panic  if  there  seems  to be no disk access for a longer
        time,  the reason is  just  that  there  may  be  time  consuming
        computations  and  that the output will be buffered internally to
        reduce the number of disk accesses and  therefore  speed  up  the
        output!

        For  more  detailed informations about the program efficiency see
        appendix 4.












































                                     - 24 -


        8    COMMAND LINE SYNTAX DESCRIPTION

        This section gives a complete overview about all SXT options  and
        their  syntax.  It  gives  also  remarks  for their use and shows
        several examples with  detailed  descriptions.  The  options  are
        case-sensitive!  There  are  no differences between the real mode
        and the other versions  of  the  SXT  programs.  In  the  Windows
        versions,  all  options can be set interactive by menu selections
        and dialog windows.  For every  option  the  SXT  programs  which
        support it are listed in parentheses.

        This  section of the documentation should be read very careful by
        all users to get a complete overview about all the features which
        are provided.

        THE OPTIONS ARE LISTED IN LEXICOGRAPHICAL ORDER.
        NONE OF THE OPTIONS IS SET BY DEFAULT.

        SYNTAX:   CFT [options [$cmdfile]] <[+]file> <@filelist>
                  CST [options [$cmdfile]] <[+]file> <@filelist>
                  DFT [options [$cmdfile]] <[+]file> <@filelist>
                  FFT [options [$cmdfile]] <[+]file> <@filelist>
                  LFT [options [$cmdfile]] <[+]file> <@filelist>


        OPTIONS:       (valid for program)

        -Bsizes        (CFT, CST)
        Redefine the basic type sizes and pointer type sizes (all  values
        must  be declared in bytes) for conditional preprocessor controls
        with the 'sizeof()' keyword like '#if  sizeof(int)  ==  4'.  This
        option is only valid with the -P option.

        The required format for this option is

             -Bv,c,s,i,l,f,d,ld*data,code
                               |
             (delimiter between data and pointer sizes is '*')

        with  the  following types and their respective default data size
        values in bytes (the pointer type sizes are model dependent):

        v    :    void (sizeof(void) is usually 0, but for GNU-C it is 1)
        c    :    char (1 byte)
        s    :    short (by definition 2 bytes, hardware independent)
        i    :    integer (hardware dependent, 2 or 4 bytes)
        l    :    long (4 bytes)
        f    :    float (4 bytes, IEEE format)
        d    :    double (8 bytes, IEEE format)
        ld   :    long double (10  bytes,  IEEE  format,  some  compilers
                  assume  long  double == double (= 8 bytes),  some CPU's
                  and their compilers have special alignment requirements
                  like the Intel 80960,  where sizeof(long double) is  16
                  bytes  due  to  register and memory access requirements
                  and structure alignment)



                                     - 25 -


        data :    data pointer (type pointers, 2 or 4 bytes, memory model
                  dependent)
        code :    code pointer (function pointers,  2 or 4 bytes,  memory
                  model dependent)

        The  sizes  of  signed and unsigned types of the same basic types
        are considered equal, this means that, for example, the following
        expression is true:

             sizeof(unsigned int) == sizeof(signed int) == sizeof(int)

        The sizes of type pointers to data and function pointers to  code
        are  also  considered equal,  this means that,  for example,  the
        following expressions are true:

             sizeof(int *) == sizeof(float *)
             sizeof(int (*)()) == sizeof(float (*)())

        A 64 bit (8 bytes) integer type like 'long long int' or  'bigint'
        (or  something  else)  is  currently  not supported although some
        (co-)processors and their assemblers are able to handle  it  (see
        Intel  80960  assembler manual for examples).  Also the DEC Alpha
        processor with its 64 bit architecture should support this.

        If the -B option is not set,  the default values for the  various
        memory  models  and  compiler types (as they are known to me