home *** CD-ROM | disk | FTP | other *** search
/ Megazine / Megazine-1.iso / PROGRAMA / C / CXTW106 / SXT.DOC < prev    next >
Text File  |  1996-12-01  |  221KB  |  5,125 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                   SXT (TM) SOFTWARE EXPLORATION TOOLS
  11.  
  12.  
  13.  
  14.                   CXT (TM) C EXPLORATION TOOLS
  15.  
  16.                     * CFT (TM) C FUNCTION TREE GENERATOR
  17.                     * CST (TM) C STRUCTURE TREE GENERATOR
  18.  
  19.  
  20.                   DXT (TM) DBASE EXPLORATION TOOLS
  21.  
  22.                     * DFT (TM) DBASE FUNCTION TREE GENERATOR
  23.  
  24.  
  25.                   FXT (TM) FORTRAN EXPLORATION TOOLS
  26.  
  27.                     * FFT (TM) FORTRAN FUNCTION TREE GENERATOR
  28.  
  29.  
  30.                   LXT (TM) LISP EXPLORATION TOOLS
  31.  
  32.                     * LFT (TM) LISP FUNCTION TREE GENERATOR
  33.  
  34.  
  35.  
  36.  
  37.                   SXT command-line versions
  38.                   SXTWIN Windows versions
  39.  
  40.  
  41.  
  42.                   April 1995
  43.  
  44.                   Copyright (C) Juergen Mueller (J.M.) 1988-1995.
  45.                   All Rights Reserved World-Wide.
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                                       - 1 -
  62.  
  63.  
  64.                              DISCLAIMER OF WARRANTY
  65.  
  66.         THIS  SOFTWARE  AND  ACCOMPANYING  WRITTEN  MATERIAL   (INCLUDING
  67.         INSTRUCTIONS  FOR  USE) IS PROVIDED "AS IS" WITH NO WARRANTIES OF
  68.         ANY  KIND,   EITHER  EXPRESS  OR  IMPLIED,   INCLUDING,   WITHOUT
  69.         LIMITATION, THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS
  70.         FOR  A  PARTICULAR  PURPOSE,  NONINFRINGEMENT,  OR ARISING FROM A
  71.         COURSE OF DEALING, USAGE OR TRADE PRACTICE. THE ENTIRE RISK AS TO
  72.         THE RESULTS AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
  73.  
  74.         THE AUTHOR AND COPYRIGHT HOLDER  SHALL  HAVE  NO  LIABILITY  WITH
  75.         RESPECT  TO THE INFRINGEMENT OF COPYRIGHTS,  TRADE SECRETS OR ANY
  76.         PATENTS BY THIS SOFTWARE OR ANY PART THEREOF.
  77.  
  78.         IN NO EVENT WILL THE AUTHOR AND COPYRIGHT HOLDER  BE  LIABLE  FOR
  79.         DAMAGES,  INCLUDING  ANY  LOST  PROFITS,  LOST  MONIES,  OR OTHER
  80.         DIRECT,  INDIRECT,  GENERAL,  SPECIAL,  INCIDENTAL,  EXEMPLARY OR
  81.         CONSEQUENTIAL  DAMAGES  ARISING  IN  ANY  WAY  OUT  OF THE USE OR
  82.         INABILITY TO USE THIS PROGRAM (INCLUDING,  BUT  NOT  LIMITED  TO,
  83.         PROCUREMENT   OF   SUBSTITUTE   GOODS   OR   SERVICES,   BUSINESS
  84.         INTERRUPTION,  LOSS OF DATA OR DATA BEING RENDERED INACCURATE  OR
  85.         LOSSES  SUSTAINED  BY  YOU  OR  THIRD PARTIES OR A FAILURE OF THE
  86.         PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) AND ON ANY THEORY  OF
  87.         LIABILITY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR
  88.         FOR ANY CLAIM BY ANY OTHER PARTY.
  89.  
  90.  
  91.                                  ACKNOWLEDGEMENT
  92.  
  93.         BY  USING  THIS  SOFTWARE YOU ACKNOWLEDGE THAT YOU HAVE READ THIS
  94.         LIMITED WARRANTY AND ACCOMPANYING  REMARKS,  UNDERSTAND  IT,  AND
  95.         AGREE  TO  BE  BOUND BY ITS TERMS AND CONDITIONS.  YOU ALSO AGREE
  96.         THAT THIS IS THE COMPLETE AND EXCLUSIVE  STATEMENT  OF  AGREEMENT
  97.         BETWEEN   THE  PARTIES  AND  SUPERSEDE  ALL  PROPOSALS  OR  PRIOR
  98.         AGREEMENTS, ORAL OR WRITTEN, AND ANY OTHER COMMUNICATIONS BETWEEN
  99.         THE PARTIES  RELATING  TO  THE  SUBJECT  MATTER  OF  THE  LIMITED
  100.         WARRANTY. YOU AGREE THAT THIS NOTICE APPLIES TO ALL FILES IN THIS
  101.         SOFTWARE DISTRIBUTION.
  102.  
  103.  
  104.         You  are expressly prohibited from selling this software or parts
  105.         of it in any form,  circulate it in any  incomplete  or  modified
  106.         form, distribute it with another product (except as Shareware) or
  107.         removing  this  notice.  No  one  may  modify or patch any of the
  108.         executable files in any  way,  including,  but  not  limited  to,
  109.         decompiling,  disassembling or otherwise reverse engineering this
  110.         software in whole or part.
  111.  
  112.         The documentation may be distributed verbatim,  but  changing  is
  113.         not allowed.  The information and specifications in this document
  114.         are subject to change without notice.
  115.  
  116.         THIS  VERSION  OF  THE  DOCUMENTATION,   SOFTWARE  AND  COPYRIGHT
  117.         SUPERSEDES  ALL PREVIOUS VERSIONS.  THIS SOFTWARE AND ITS RELATED
  118.         DOCUMENTATION MAY CHANGE WITHOUT NOTICE.
  119.  
  120.  
  121.  
  122.                                       - 2 -
  123.  
  124.  
  125.         This software and documentation is Copyright (C) 1988-1995 by
  126.  
  127.                   Juergen Mueller
  128.                   Aldingerstrasse 22
  129.                   D-70806 Kornwestheim
  130.                   GERMANY
  131.  
  132.                   Email address: juergen.mueller@isw.uni-stuttgart.de
  133.  
  134.  
  135.         THERE ARE NO RELATIONS BETWEEN THE AUTHORS PROFESSIONAL WORK  AND
  136.         THE  SXT  DEVELOPMENT.  THE  SXT  PROJECT IS AND HAS EVER BEEN AN
  137.         INDEPENDENT PRIVATE PROJECT OF THE  AUTHOR  AND  IS  WRITTEN  AND
  138.         MAINTAINED IN HIS FREE TIME.
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.                                       - 3 -
  184.  
  185.  
  186.                                      LICENSE
  187.  
  188.         This software is not public domain or free software, but is being
  189.         distributed  as  shareware.  It  is  protected  by  copyright and
  190.         distributed under this licence restricting its use.
  191.  
  192.         Non-registered users of  this  software  are  granted  a  limited
  193.         license  for  a 30-day evaluation period starting from the day of
  194.         the first use to make an evaluation copy for trial  use  for  the
  195.         express  purpose of determining whether this software is suitable
  196.         for their needs.  At the end of  this  trial  period  you  should
  197.         either register your copy or discontinue using this software. The
  198.         use  of  unregistered  copies  of  this software,  outside of the
  199.         initial 30-day  trial,  by  any  person,  business,  corporation,
  200.         government agency or any other entity is strictly prohibited.
  201.  
  202.         This means that if you use this software, then you should pay for
  203.         your  copy.   This  software  is  not  free,  but  you  have  the
  204.         opportunity to try it before you buy it.  Either pay for  it,  or
  205.         quit  using  it.  A registration entitles you to use your copy of
  206.         this software on any and all computers available to you. If other
  207.         people  have  access  to  this  software  or  may  use  it,  then
  208.         additional copies or a site license should be purchased.
  209.  
  210.         All  users  are  granted  a limited license to copy this software
  211.         only for the trial  use  of  others  and  subject  to  the  above
  212.         limitations.  This license does not include distribution, selling
  213.         or copying of this software package in connection with any  other
  214.         product  or  service  or  for  distribution  in any incomplete or
  215.         modified form. Operators of electronic bulletin board systems and
  216.         software servers (like Internet FTP-Servers)  are  encouraged  to
  217.         post this software for downloading by their users, as long as the
  218.         above conditions are met.
  219.  
  220.         This package is expected to be distributed as shareware,  but the
  221.         fees paid for "distribution" costs (disk,  CD-ROM)  are  strictly
  222.         exchanged  between  the  distributor  and the recipient,  and the
  223.         author makes no express or implied warranties about  the  quality
  224.         or integrity of such indirectly acquired copies. Distributors and
  225.         users  may  obtain  the  package  directly  from  the  author  by
  226.         following the ordering procedures in the REGISTER files.
  227.  
  228.  
  229.                               REGISTRATION REMINDER
  230.  
  231.         Unregistered copies of this software are 100% fully functional. I
  232.         make them this way so that you can have a real look at them,  and
  233.         then decide whether they fit your needs or not. This work depends
  234.         on your honesty.  If you use it, I expect you to pay for it. When
  235.         you pay for the shareware you like,  you  are  voting  with  your
  236.         pocketbook,  and will encourage me and other shareware authors to
  237.         develop more of these kinds of products.
  238.  
  239.  
  240.                  THANK YOU FOR SUPPORTING THE SHAREWARE CONCEPT
  241.  
  242.  
  243.  
  244.                                       - 4 -
  245.  
  246.  
  247.                   TABLE OF CONTENTS
  248.  
  249.                   1    THE SXT SOFTWARE EXPLORATION TOOLS
  250.                   2    GENERAL INTRODUCTION
  251.                   3    PROGRAM DESCRIPTION
  252.                   4    LANGUAGE IMPLEMENTATIONS
  253.                   4.1  C-LANGUAGE IMPLEMENTATION AND C-PREPROCESSOR
  254.                   4.2  C++ LANGUAGE IMPLEMENTATION
  255.                   4.3  DBASE SOURCE CODE
  256.                   4.4  FORTRAN SOURCE CODE
  257.                   4.5  LISP SOURCE CODE
  258.                   4.6  ASSEMBLER SOURCE CODE
  259.                   5    DATABASE GENERATION
  260.                   6    PROGRAM LIMITATIONS
  261.                   7    SXT OPTIONS
  262.                   8    OUTPUT DESCRIPTION AND INTERPRETATION
  263.                   9    INTEGRATION INTO PROGRAM DEVELOPMENT ENVIRONMENTS
  264.                   10   TOOLS FOR DATABASE PROCESSING
  265.                   11   IMPROVING EXECUTION SPEED
  266.                   12   TROUBLE SHOOTING
  267.                   13   FREQUENTLY ASKED QUESTIONS
  268.                   14   REFERENCES
  269.                   15   TRADEMARKS
  270.  
  271.                   APPENDIX 1: C/C++ PRECOMPILER DEFINES
  272.                   APPENDIX 2: RESERVED C/C++ KEYWORDS
  273.                   APPENDIX 3: RESERVED FORTRAN KEYWORDS
  274.                   APPENDIX 4: EFFICIENCY
  275.                   APPENDIX 5: REVIEWS
  276.                   APPENDIX 6: SYSTEM REQUIREMENTS
  277.                   APPENDIX 7: INSTALLATION
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.                                       - 5 -
  306.  
  307.  
  308.         1    THE SXT SOFTWARE EXPLORATION TOOLS
  309.  
  310.         The SXT Software Exploration Tools are a collection  of  software
  311.         analysis  tools  providing  a similar functionality for different
  312.         programming languages.
  313.  
  314.         The following packages are currently available:
  315.  
  316.         * CXT - C Exploration Tools:
  317.           CFT - C Function Tree Generator
  318.              Tool to analyse and display the function call  relationships
  319.              within the source code of C/C++ programs.
  320.           CST - C Structure Tree Generator
  321.              Tool    to   analyse   and   display   the   structure/class
  322.              relationships within the source code of C/C++ programs.
  323.  
  324.         * DXT - DBASE Exploration Tools:
  325.           DFT - DBASE Function Tree Generator
  326.              Tool to analyse and display the function call  relationships
  327.              within the source code of DBASE,  CLIPPER, FOXBASE and other
  328.              XBASE-like programs.
  329.  
  330.         * FXT - FORTRAN Exploration Tools:
  331.           FFT - FORTRAN Function Tree Generator
  332.              Tool to analyse and display the function call  relationships
  333.              within the source code of FORTRAN programs.
  334.  
  335.         * LXT - LISP Exploration Tools:
  336.           LFT - LISP Function Tree Generator
  337.              Tool  to analyse and display the function call relationships
  338.              within the source code of LISP and SCHEME programs.
  339.  
  340.         Each  of  these  packages  consists  of  the   analysis   program
  341.         ("Analyser")  and  a recall program ("Navigator") to retrieve the
  342.         analysis  results  which  can  be  stored  in  a  database,  plus
  343.         documentation and additional macros to integrate these tools into
  344.         popular editors like BRIEF, QEDIT or MicroEMACS.
  345.  
  346.         Each of these packages is available for the following systems:
  347.  
  348.              * DOS real mode               (shareware release)
  349.              * DOS 386 protected mode      (registered users only)
  350.              * WINDOWS NT text mode        (registered users only)
  351.              * OS/2 text mode              (registered users only)
  352.              * Windows 3.1                 (shareware release)
  353.              * Windows 32 bit (Win32s)     (registered users only)
  354.  
  355.         There  are  no  differences  in  the  functionality  between  the
  356.         versions for the different systems.
  357.  
  358.         There are no plans to port the SXT programs to other platforms or
  359.         operating systems like Apple MacIntosh, UNIX (SCO, Solaris,  AIX,
  360.         HP-UX,  Linux,  ...),  Atari or Amiga. The source code of the SXT
  361.         programs is not available.
  362.  
  363.  
  364.  
  365.  
  366.                                       - 6 -
  367.  
  368.  
  369.         IMPORTANT NOTICE ABOUT THIS DOCUMENT
  370.  
  371.         Although this document is mainly based on the description for the
  372.         CXT programs CFT and CST (which were up to version 2.13 the  only
  373.         public  available SXT programs) and therefore very C/C++ related,
  374.         the description  applies  in  the  same  way  to  all  other  SXT
  375.         packages.  The  names  CXT/CXTWIN  resp.  CFT/CST,  CFTN/CSTN and
  376.         CFTWIN/CSTWIN can  be  simply  exchanged  by  the  similar  other
  377.         product names DXT/DFT,  FXT/FFT or LXT/LFT.  Where necessary, the
  378.         specific  differences  of  the  SXT   packages   are   described,
  379.         especially in the chapter describing the options.  I have done it
  380.         this way to ensure an overall consistency,  to keep  all  related
  381.         things  together  and  to  reduce  the  efforts  for  writing and
  382.         maintaining this document.
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.                                       - 7 -
  428.  
  429.  
  430.         2    GENERAL INTRODUCTION
  431.  
  432.         The SXT programs are powerful  program  development,  maintenance
  433.         and   documentation  tools.   They  are  primarily  intended  for
  434.         analysing  large  programs,   where  it  is  difficult,   if  not
  435.         impossible, for the programmer to find the structure of the whole
  436.         program.   They   allow  the  analysis  of  the  source  code  of
  437.         applications,  no matter how big or complex  they  are.  The  SXT
  438.         programs  are also very useful to explore unknown source code and
  439.         to get  complete  overview  about  its  internal  structure.  The
  440.         re-engineering  of  old  and/or  undocumented source code becomes
  441.         much easier with these programs. The tools help the programmer to
  442.         analyse,  identify,  locate and  access  all  parts  of  a  large
  443.         software  system.  They  are  designed to support software reuse,
  444.         maintenance and reliability.
  445.  
  446.         By preprocessing,  scanning  and  analysing  the  entire  program
  447.         source  code  as a single unit,  these programs build an internal
  448.         representation of the function call  hierarchy  (CFT,  DFT,  FFT,
  449.         LFT)  and  of  the data structure relations (CST).  The resulting
  450.         output shows from a global perspective the interdependencies  and
  451.         hierarchical structure between the functions or data types of the
  452.         whole, multi file, software project. Several features and options
  453.         allow  the  user  to  customise  the generated hierarchy calltree
  454.         output and to get a large set of  useful  information  about  the
  455.         source code. The hierarchy structure is always up-to-date because
  456.         it  relies  on  the original source code as the primary source of
  457.         information.  Written software documentation often  differs  from
  458.         that what really has been coded, so the source code itself is the
  459.         ultimate documentation.
  460.  
  461.         An  important  feature is the database generation.  It allows the
  462.         recalling of information without reprocessing  the  source  code.
  463.         The  database  can  again  be  read  in by CFT and CST to produce
  464.         different outputs or to add new files to  the  database.  Special
  465.         recall  programs  called  CFTN  and CSTN allow fast searching for
  466.         items in the database.  These programs can  be  used  within  any
  467.         environment,  for  example on the DOS command line or from inside
  468.         editors like BRIEF,  QEDIT or MicroEMACS (DOS  and  WINDOWS),  to
  469.         provide  a full software project management system with access to
  470.         all functions  and  data  types  with  just  a  keystroke.  These
  471.         features  make  a  comfortable "hypertext source code browser and
  472.         locator" system out of  your  editor.  A  project  consisting  of
  473.         several   files  appears  to  the  developer  as  if  it  were  a
  474.         'whole-part' of software. The developer can walk through programs
  475.         and trace the logic without having to  memorize  the  directories
  476.         and  files  where functions or data types are defined and called.
  477.         The SXT windows versions provide  a  similar  functionality  with
  478.         DLL's for database access from other programs.
  479.  
  480.         Displaying   and  printing  a  graphical  representation  of  the
  481.         analysis results as a call graph is not  directly  supported  bye
  482.         the SXT programs.  However,  owners of RATIONAL ROSE,  a powerful
  483.         software   development   case   tool   supporting    the    Booch
  484.         Object-Oriented Analysis and Design (OOAD) method,  can (mis-)use
  485.  
  486.  
  487.  
  488.                                       - 8 -
  489.  
  490.  
  491.         this tool for  such  purposes.  The  SXT  programs  can  generate
  492.         compatible  output  which  can be imported by Rational Rose.  See
  493.         option -RATIONAL for a detailed description.
  494.  
  495.         The SXT programs can generate the  calltree  in  HTML  (HyperText
  496.         Markup  Language)  format  which  can be viewed by any WWW (World
  497.         Wide Web) Browser like NCSA Mosaic or Netscape. The HTML document
  498.         contains hypertext links and allows  jumps  to  item  definitions
  499.         within the document. See option -HTML for more information.
  500.  
  501.         Every  SXT  program  can  generate the calltree also in RTF (Rich
  502.         Text Format) format which can be imported by word processors. The
  503.         RTF output can be used to  compile  Windows  helpfiles  with  the
  504.         Windows  Help Compiler which can be viewed with WINHELP.  The RTF
  505.         document contains  hypertext  links  and  allows  jumps  to  item
  506.         definitions  within  the  document.  See  option  -RTF  for  more
  507.         information.
  508.  
  509.         Listings of all functions/data types and source files can also be
  510.         written as formatted ASCII text files and can be  used  as  input
  511.         for   other   programs   like   word  processors  or  spreadsheet
  512.         calculators.
  513.  
  514.         A useful option of CST is the possibility to  generate  a  source
  515.         file   with   which   size   and  byte  offset  calculations  for
  516.         structures/unions and their members can be performed. This option
  517.         is useful especially to support any kind of  error  searching  or
  518.         hardware  debugging,  for example with an ICE (Integrated Circuit
  519.         Emulator),  or if data structures have to  be  exchanged  between
  520.         different hardware platforms with different data alignment.
  521.  
  522.         CFT  can  also  be used to analyse "C"-like languages as they are
  523.         used  by  several  commercial  programs.  The  macro  programming
  524.         languages of the BRIEF, EPSILON and ME editors are such languages
  525.         and can be handled by CFT.
  526.  
  527.         The  resulting output files can be used for various purposes like
  528.         development or documentation.  For registered users there are  no
  529.         restriction limits in using them for their own work.
  530.  
  531.         CFT  and  CST  have  been  used  and tested since 1989 in several
  532.         projects with applications ranging from single source files  over
  533.         medium  sized  projects  (like  CFT,  CST and the other SXT tools
  534.         themselves) up to very large software projects with  hundreds  of
  535.         source and include files (mixed C and assembler code),  more than
  536.         6 MB of source code,  more than 210000 lines,  2300 functions and
  537.         700 data types.
  538.  
  539.         A lot of public available C/C++ sources (e.g. GNU-C/C++ compiler,
  540.         GNU-C library,  GNU-EMACS,  MicroEMACS, NCSA TCP/IP communication
  541.         software package, SUIT - The Simple User Interface Toolkit, NIHCL
  542.         - The  National  Institute  of  Health  C++  class  library,  F2C
  543.         Fortran-to-C translator, several projects from Dr. Dobbs Journal,
  544.         Microsoft  sample  code  (MFC))  were  processed  (with sometimes
  545.         surprising results!) during the development and have been used to
  546.  
  547.  
  548.  
  549.                                       - 9 -
  550.  
  551.  
  552.         test  and  improve  the   features,   reliability,   correctness,
  553.         robustness  and  execution  speed  of CFT,  CST and their related
  554.         utilities.
  555.  
  556.         Although the other SXT packages are much newer than CFT and  CST,
  557.         they  all  are closely related.  The CXT programs are used as the
  558.         common base for all other packages.
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.                                      - 10 -
  611.  
  612.  
  613.         3    PROGRAM DESCRIPTION
  614.  
  615.         CFT builds a hierarchy calltree of every function with the called
  616.         functions in it's own function block.  These functions are  again
  617.         used as a starting point for subsequent function blocks. Starting
  618.         the  calltree  with  the  "main"-function  it  will  display  the
  619.         complete  function  flow  chart  and   the   function   hierarchy
  620.         dependency  of  the  whole  application  with  all  user  defined
  621.         functions and the called library functions.  Prototyped but never
  622.         defined or called functions are also detected. Recursive calls of
  623.         functions  are  recognised and displayed,  even over several call
  624.         levels.  Repeated calls of previously displayed functions in  the
  625.         output  calltree  are detected and a message will be given with a
  626.         reference to their first appearance.  This prevents the output of
  627.         complete subtrees displayed earlier. Overloaded C++ functions and
  628.         operators  are  recognised  and  displayed  with  the  number  of
  629.         overloadings.
  630.  
  631.         CST acts similar to CFT but it works on  data  types  like  basic
  632.         types,  structures,  unions,  enumerations  and C++ classes.  CST
  633.         builds a hierarchy calltree of every  structure  and  union  data
  634.         type  with  their internal elements and their related data types.
  635.         If these data types are again structures, unions or classes,  the
  636.         substructures will again be displayed.  CST recognises data types
  637.         defined by 'typedef' and derived from other data types.  The type
  638.         names  corresponding  to the same basic type are displayed in the
  639.         output file as 'alias' names for their  common  basic  data  type
  640.         name.  Every  feature  of  CFT  like  the  detection of recursive
  641.         declared  structures  and  unions,   references   to   previously
  642.         displayed data types and others are available and act similar.
  643.  
  644.         Every  function  (CFT)  and data type (CST) can be displayed with
  645.         the name of the source file and  the  line  number  where  it  is
  646.         defined.  The  output can be customised to display the tree chart
  647.         as a call-tree ("CALLER-CALLEE"-relation: "WHO CALLS WHOM") or as
  648.         a  caller-tree  ("CALLEE-CALLER"-relation:  "WHO  IS  CALLED   BY
  649.         WHOM"). This feature allows the user to determine which functions
  650.         are  called  from  a  specific  function  or  which functions are
  651.         callers of a specific function.
  652.  
  653.         The function and data type extraction from  the  source  code  is
  654.         done  by scanning and parsing the source.  There is absolutely no
  655.         need for the programmer  to  mark  functions  or  data  types  of
  656.         interest,   for  example  with  special  keywords,  starting  the
  657.         definitions at the  beginning  of  a  line  or  to  use  comments
  658.         containing  special  marks,  as  it is necessary for other source
  659.         code analysers and browsers. CFT,  CST and the other SXT programs
  660.         do not need these work-arounds,  any source code can be processed
  661.         without previous work.  These tools are also compiler independent
  662.         because they can be customised to support any kind of compiler.
  663.  
  664.         Since  the  SXT  programs  always  make  a static analysis of the
  665.         program source code,  they are not able to detect references  due
  666.         to  the expansion of a macro definition during runtime.  This has
  667.         to be considered for DBASE and LISP  programs  which  allow  such
  668.         dynamic features.  The same restrictions apply also to the use of
  669.  
  670.  
  671.                                      - 11 -
  672.  
  673.  
  674.         function  pointers  for  C/C++  and  function  names  as   formal
  675.         parameters  in  FORTRAN  which  cannot be resolved for call graph
  676.         generation.
  677.  
  678.         Several  useful  information  and  software  metrics  about   the
  679.         processed  source  code  and  the included files can be generated
  680.         like
  681.  
  682.         -    file size and comment size in bytes for every file,
  683.         -    number of source code lines for every file,
  684.         -    number of included files for every source file,
  685.         -    total effective number of scanned bytes and lines for  every
  686.              source  file  and its included files,  if files are included
  687.              multiple times, this will influence the calculations,
  688.         -    for every defined function the number of lines, the code and
  689.              comment size in bytes,  the number of bytes  per  line,  the
  690.              number  of  functions  called,  the  number  of flow control
  691.              statements (if,  else,  for,  while,  case,  default,  goto,
  692.              return,  exit),  the  maximum brace nesting level and if the
  693.              function is used only inside the file,
  694.         -    for  every  defined  structure/union  the  total  number  of
  695.              elements  and  the  number  of elements which are themselves
  696.              structures/unions,
  697.         -    file function or data type reference list for every file,
  698.         -    total number of displayed,  defined,  undefined or  multiple
  699.              defined functions and data types,
  700.         -    location of all multiple defined functions and data types,
  701.         -    location of all overloaded C++ functions,
  702.         -    source  file  -  include  file dependencies for every source
  703.              file (MAKE-dependencies),
  704.         -    source file - include  file  hierarchy  tree  (include  file
  705.              relations),
  706.         -    final statistical summary for all files,
  707.         -    cross  reference  of  every occurrence for every function or
  708.              data type,
  709.         -    parent/children relationship for  every  function  and  data
  710.              type,
  711.         -    critical  function  call path/structure nesting with deepest
  712.              non-recursive nesting level (unlimited tree depth),
  713.         -    C++ class inheritance tree,
  714.         -    support for C structure/union byte offset calculation,
  715.         -    FORTRAN subroutine CALLs,
  716.         -    FORTRAN COMMON blocks,
  717.         -    generation of description files for  call/inheritance  graph
  718.              visualisation with the RATIONAL ROSE CASE tool,
  719.         -    generation  of  HTML-output  for calltree visualisation with
  720.              WWW Browsers like NCSA Mosaic,
  721.         -    generation of RTF-output for import to word  processors  and
  722.              for compiling Windows Helpfiles from it
  723.  
  724.         The resulting hierarchy structure chart is another representation
  725.         for  a  directed  call  graph.  A directed call graph consists of
  726.         nodes (functions or data types) and connections (call  relations)
  727.         between  these  nodes.  The number of nodes and connections which
  728.  
  729.  
  730.  
  731.  
  732.                                      - 12 -
  733.  
  734.  
  735.         are necessary to transform the hierarchy structure chart  into  a
  736.         directed  call  graph  will  also  be calculated as an additional
  737.         information about the system complexity.
  738.  
  739.         A large number of options to control the  program  execution  and
  740.         the  output  generation  are  available and can be defined on the
  741.         command line,  with interactive dialog windows (applies  only  to
  742.         Windows  versions),  by  command  files or by defining them in an
  743.         environment variable used by the program.
  744.  
  745.         CFT,  CST and the other SXT programs can be directly invoked from
  746.         inside  editors  or  integrated development environments like the
  747.         Borland C++ IDE.  Detailed examples for the integration  together
  748.         with  necessary  macro or batch files are given.  The SXT windows
  749.         versions provide DLL's (Dynamic Link  Libraries)  to  access  the
  750.         generated databases and to retrieve information.  These DLL's can
  751.         be used with user developed programs e.g.  written in  C/C++  and
  752.         Visual Basic, or from other Windows applications like MS-Word for
  753.         Windows, MS-Excel, MS-Access and others.
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.                                      - 13 -
  794.  
  795.  
  796.         4    LANGUAGE IMPLEMENTATIONS
  797.  
  798.         4.1  C-LANGUAGE IMPLEMENTATION AND C-PREPROCESSOR
  799.  
  800.         The  ISO/ANSI  C  language  standard  ISO/IEC 9899:1990 (E) resp.
  801.         X3.159-1989-ANSI C  as  described  in  several  books  about  the
  802.         C-language  (see references) was used as a development base.  The
  803.         reserved keywords being recognised  are  not  only  the  original
  804.         ISO/ANSI  C  keywords  but  were also taken from several compiler
  805.         implementations like Microsoft,  Borland or  GNU  and  their  own
  806.         special  language  extensions.  The  books  "The  C++ Programming
  807.         Language" and "The Annotated C++ Reference Manual" (ARM) together
  808.         with information about the work of the ANSI C++  committee  X3J16
  809.         resp.  the  ISO/IEC working group SC22 WG21 were used for the C++
  810.         keywords.  Another major source was the  AT&T  C++  release  2.1.
  811.         Compiler   specific  extensions  especially  from  GNU  are  also
  812.         recognised.  Proposed extensions to C  and  C++  like  additional
  813.         keywords (e.g.  wchar_t,  bool, namespace, using, ...) and the so
  814.         called 'digraphs' will be supported if they are  introduced  into
  815.         the language standard.
  816.  
  817.         A  complete  list of all reserved keywords is show in appendix 2.
  818.         The large set of keywords may lead to  some  slight  problems  in
  819.         situations  where  a  keyword  is  not  used  as itself but as an
  820.         identifier name,  for example a C++ keyword used as an identifier
  821.         in C.
  822.  
  823.         During a normal file scan,  precompiler defines are, if possible,
  824.         handled as if a real precompiler would be present,  but this  can
  825.         cause  some  trouble  with '#if',  '#ifdef' and other precompiler
  826.         controls which are not evaluated.  Also the block nesting  level,
  827.         which will be monitored by the source code scanner, may not be at
  828.         level  0  at  the  end  of  the  file because of such precompiler
  829.         controls. To avoid such things,  a built-in C-preprocessor allows
  830.         the  complete  preprocessing of the source code and include files
  831.         for several compiler types as an additional option (-P).
  832.  
  833.         Preprocessing or not is a little bit controversial because it can
  834.         either result in a loss of information  if  macros  are  used  to
  835.         change the program behaviour and hide function calls, it can lead
  836.         to  errors during file scanning or it can change the function and
  837.         data type information  obtained  from  the  code  which  may  not
  838.         exactly correspond to the visible source code.  Preprocessing can
  839.         be an advantage or not, so the user has to decide whether he does
  840.         it or not (see options -P, -I, -E for more information).
  841.  
  842.         The  preprocessor  handles  the  defines  for  Microsoft  C  5.1,
  843.         Microsoft  C/C++  7.0,  Microsoft  Visual  C++  1.5 professional,
  844.         Microsoft Visual C++ 1.1 for Windows NT,  Turbo C++ 1.0,  Borland
  845.         C++  2.0,  Borland C++ 3.1,  Borland C++ 1.0 for OS/2,  GNU-C and
  846.         Intel 80960 C compiler iC960  3.0  and  all  memory  models  (not
  847.         necessary  for GNU-C and I960) or CPU architectures for the Intel
  848.         80960 32 bit RISC processor (KA,  KB,  SA,  SB,  MC,  CA).  Other
  849.         compiler  types  can  be customised with the -B and the -D and -U
  850.         options.  The default ISO/ANSI C  predefined  macros  '__FILE__',
  851.         '__LINE__',    '__DATE__',    '__TIME__'    are   generated   for
  852.  
  853.  
  854.                                      - 14 -
  855.  
  856.  
  857.         preprocessing.   The  macro  '__STDC__'  is  NOT  defined   (some
  858.         compilers  test  with  '#ifndef __STDC__'),  so that non standard
  859.         ISO/ANSI C extensions in the processed code are allowed. Defining
  860.         '-D__STDC__=1' forces ISO/ANSI C conforming output  (if  used  by
  861.         the  scanned  source  code,  of  course!).  Additional  supported
  862.         precompiler  defines  are  '__TIMESTAMP__',  '__BASE_FILE__'  and
  863.         '__INCLUDE_LEVEL__'.   A  list  of  the  predefined  preprocessor
  864.         defines for the supported compiler types is shown in  appendix  1
  865.         together  with  tips  for  the  adaptation  of  other  compilers.
  866.         Features like the replacing of trigraphs and the  recognition  of
  867.         C++ comments '//...' are also treated by the preprocessor.
  868.  
  869.         The precompiler recognises several errors or possible sources for
  870.         problems like
  871.  
  872.         -    the use of undefined variables in precompiler controls,
  873.         -    misbalanced  '#if...'  control  block(s) including the exact
  874.              location (file, line) where the failing block started,
  875.         -    recursive called include files,
  876.         -    nested include files,
  877.         -    wrong number of macro arguments
  878.  
  879.         and displays diagnostic messages with an exact description of the
  880.         error or warning reason and its location in the source file.
  881.  
  882.  
  883.         4.2  C++ LANGUAGE IMPLEMENTATION
  884.  
  885.         For the description of the related  C++  language  standards  and
  886.         other   literature   see   the   chapter  about  the  C  language
  887.         implementation.
  888.  
  889.         Although CFT and CST were initially not developed to process  C++
  890.         code  it  is  possible  to  do so.  In that case,  however,  some
  891.         restrictions and limitations should be considered.
  892.  
  893.         Data type modifiers like  'far'  may  confuse  the  CST  analysis
  894.         process. The recognition of C++ classes by CST is limited because
  895.         the handling of the internal class structure items (variables and
  896.         functions)  is too complex to fit in the CST program.  So classes
  897.         are only referenced by name but their internal structure will not
  898.         be scanned and displayed. The C++ class inheritance relationships
  899.         are recognised and shown  in  a  class  hierarchy  graph  listing
  900.         (option  -b).  Structures in C++ with function names as structure
  901.         members will not be processed correctly, function bodies inside a
  902.         structure  definition  may  cause  errors.   Templates  are   not
  903.         supported and will not be recognised.
  904.  
  905.         Calling  member functions will not be recognised correctly due to
  906.         missing class name and namescope resolving, this leads also to an
  907.         incomplete call tree and a lot of warnings during  analysis.  The
  908.         use  of  overloaded  functions  with  equal  names  but different
  909.         parameters  in  C++  programs  may  lead  to  incorrect   calling
  910.         relationships.  A variable initialization with parameters will be
  911.         misinterpreted as a function call.  A correct handling  of  these
  912.  
  913.  
  914.  
  915.                                      - 15 -
  916.  
  917.  
  918.         and  other  C++  features  requires  a  complete  C++ source code
  919.         analyser to keep track of the class functions belong to  and  the
  920.         different calling parameters.
  921.  
  922.         If  precise information about C++ code is needed,  utilities like
  923.         'class hierarchy browsers' or 'class viewers',  which are usually
  924.         part of C++ compiler environments, should be used instead.
  925.  
  926.         Because of the above described reasons, some care should be taken
  927.         if C++ code is processed and displayed.
  928.  
  929.  
  930.         4.3  DBASE SOURCE CODE
  931.  
  932.         DFT  can  process  source code which is based on the DBASE III/IV
  933.         programming language. This means that also source code written in
  934.         DBASE derivatives like CLIPPER (Summer '87)  or  FOXBASE  can  be
  935.         analysed.  The  source  code  analyser  tries to be as correct as
  936.         possible to build a reliable hierarchy tree. A function/procedure
  937.         declaration  is  recognised  by  the  FUNCTION  resp.   PROCEDURE
  938.         keyword. A function/procedure call is recognised by the following
  939.         statements:
  940.  
  941.              function()
  942.              CALL function
  943.              CALL function WITH parameters
  944.              DO function
  945.              DO function WITH parameters
  946.  
  947.         If  a  file  contains  no  function/procedure  declaration,   the
  948.         filename itself is taken as procedure name.  The  recognition  of
  949.         builtin functions/procedures can be ignored (see option -E).  All
  950.         tokens  are  assumed  case-insensitive  and  are   converted   to
  951.         upper-case  characters.  System  builtin  functions/macros can be
  952.         specified by option -E. Include files (e.g. with CLIPPER) are not
  953.         processed.
  954.  
  955.  
  956.         4.4  FORTRAN SOURCE CODE
  957.  
  958.         FFT can process source which is based on the FORTRAN 77 standard.
  959.         Each FORTRAN  line  is  divided  into  fields  for  the  required
  960.         information, each column represents a single character.
  961.  
  962.              COLUMN    FIELD
  963.                   1    comment indicator (C,c,*,!)
  964.                 1-5    label
  965.                   6    indicator for line continuation
  966.                7-72    statement field (standard is 72, extended to 132)
  967.  
  968.         FFT can process lines up to 132 columns,  however,  if characters
  969.         are found beyond column 72  a  warning  will  be  given  (can  be
  970.         disabled  with -NOWARN72).  Continuation lines  are merged before
  971.         they are analysed.  The number of continuation  lines  is  19  by
  972.         default  and can be varied between 0 and 99 (option -qn).  Inline
  973.         comments in the statement field start with '!',  the  text  until
  974.  
  975.  
  976.                                      - 16 -
  977.  
  978.  
  979.         end  of  line  is  ignored.  The standard intrinsic functions and
  980.         additionally  VAX-FORTRAN  intrinsic  functions  are  recognised.
  981.         Statement  functions  (comparable  to C preprocssor function-like
  982.         macros) are not recognised and may lead to 'undefined functions'.
  983.         Hollerith constants are not recognised and  handled.  All  tokens
  984.         are  assumed  case-insensitive  and  are  converted to upper-case
  985.         characters. Blanks are not significant and are not handled,  they
  986.         will  be removed (except inside character strings).  If option -I
  987.         is set,  INCLUDE statements are recognised    and  processed.  To
  988.         handle  this implementation dependent feature,  several different
  989.         types of include statements are accepted:
  990.  
  991.         C FORTRAN-LIKE SYNTAX, INCLUDE STATEMENT STARTS IN COLUMN 7
  992.               include-statement include-filename
  993.  
  994.         C C-LIKE SYNTAX, INCLUDE STATEMENT STARTS IN COLUMN 1
  995.         include-statement include-filename
  996.  
  997.         where include-statement is one of INCLUDE, #INCLUDE,  $INCLUDE or
  998.         %INCLUDE  and include-filename is one of 'filename',  "filename",
  999.         <filename> or  filename  (without  surrounding  characters).  See
  1000.         option   -I   and  the  chapter  about  PROGRAM  LIMITATIONS  for
  1001.         additional informations about file inclusion.
  1002.  
  1003.         The resulting function call graph may be  incorrect  due  to  the
  1004.         ENTRY  capability  of  FORTRAN  which  allows direct jumps into a
  1005.         function or subroutine body from the outside.  This may result in
  1006.         incorrect   relationships   for   the  ENTRY  statement  and  the
  1007.         surrounding function/subroutine.  The indirect call of  functions
  1008.         which  are given as formal parameters to subroutines or functions
  1009.         (comparable to pointers to functions  in  C)  are  not  correctly
  1010.         referenced.  Implicit  typing  for  function  definitions without
  1011.         return  type  will  not  be  recognised,  the  function  will  be
  1012.         displayed without a return type.
  1013.  
  1014.  
  1015.         4.5  LISP SOURCE CODE
  1016.  
  1017.         LFT  can process LISP and SCHEME source code.  The development of
  1018.         LFT was mainly based on the GNU-EMACS LISP dialect as it is  used
  1019.         in  the  GNU-EMACS macro extension language and its functionality
  1020.         was tested mainly with these macro files.  LISP  functions/macros
  1021.         are  recognised  by  the  DEFUN  and  DEFMACRO  keywords.  SCHEME
  1022.         functions are recognised by the DEFINE keyword, SCHEME processing
  1023.         is enabled by option -XSCHEME.  Unnamed functions  declared  with
  1024.         the   LAMBDA   keyword   can  be  recognised  optionally  (option
  1025.         -XLAMBDA).  Tokens  are  assumed  case-sensitive.   Comments  are
  1026.         recognised for ';' until end-of-line and between '#|' and '|#' as
  1027.         multi line comment blocks.
  1028.  
  1029.         The  source  code  analysis is performed in two passes: The first
  1030.         pass detects function/macro  declarations  and  the  second  pass
  1031.         analyses  the relationships.  Function calls via (funcall <fcn>),
  1032.         (function  <fcn>),  (apply  <fcn>),   (mapc  <fcn>)  and  similar
  1033.         constructs   may   not   be  correctly  evaluated  if  fcn  is  a
  1034.  
  1035.  
  1036.  
  1037.                                      - 17 -
  1038.  
  1039.  
  1040.         function-symbol (e.g.  given as a function parameter) and  not  a
  1041.         valid  function  name.  System  builtin  functions/macros  can be
  1042.         specified by option -E.
  1043.  
  1044.         LFT was designed to work with different types of LISP source code
  1045.         (as there are XLISP,  CLOS,  GNU-EMACS LISP,  ...),  although the
  1046.         large number of dialects may lead sometimes to problems.
  1047.  
  1048.  
  1049.         4.6  ASSEMBLER SOURCE CODE
  1050.  
  1051.         As  an  additional  feature,  CFT  and  FFT can process assembler
  1052.         source code for the Intel 80x86 processors (MASM 5.1,  TASM)  and
  1053.         for the Intel 80960 RISC processors (or any other "AT&T UNIX-like
  1054.         assembler"   like   GNU)   to  get  information  about  assembler
  1055.         procedures and functions being called from the  assembler  source
  1056.         files. This feature is useful for mixed language programming. The
  1057.         assembler  source  code scanner also detects and handles calls of
  1058.         include files.  The processing of assembler macros,  however,  is
  1059.         not  supported,  the  preprocessing  option  (-P) works only on C
  1060.         source code.  Assembler source files are recognised by their file
  1061.         extensions '.ASM' and '.S', there is no other way to force a file
  1062.         being processed as an assembler file.
  1063.  
  1064.         The  following  naming  convention  is used: For '.ASM' assembler
  1065.         files (MASM,  TASM) all identifiers are treated  case-insensitive
  1066.         and  will  be  transformed to lower (CFT) resp.  upper (FFT) case
  1067.         characters,  but identifiers in '.S' (GNU,  I960) assembler files
  1068.         are  treated  case-sensitive.   This  means,  that  an  assembler
  1069.         function 'func1' defined in an '.ASM' file can be called from the
  1070.         source by 'func1', 'FUNC1',  'Func1' or any other lower and upper
  1071.         case  character  combination.  If  'func1'  is defined in an '.S'
  1072.         file,  the name must match exactly.  The first leading underscore
  1073.         of  a  function name will be removed to get exact naming matches.
  1074.         Type modifiers in C source code like 'cdecl' or 'pascal' will not
  1075.         be considered.  Remember these  conventions  when  processing  C,
  1076.         FORTRAN and assembler files.
  1077.  
  1078.         Assembler code statements (inline code) inside C source code will
  1079.         not be processed and will be skipped, because it is too difficult
  1080.         to  handle  the several kinds of syntax being used for this  like
  1081.         'asm ...',  'asm "..."' or 'asm(...)' and the different  keywords
  1082.         ('asm', '_asm', '__asm', '__asm__', ...) used by various compiler
  1083.         implementations.
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.                                      - 18 -
  1099.  
  1100.  
  1101.         5    DATABASE GENERATION
  1102.  
  1103.         One  of  the  most  important features is the database generation
  1104.         which can be enabled with the -G option.  It is  performed  after
  1105.         writing  the  output  file  to  save  all  information  about the
  1106.         processed files in a  set  of  dBASE  compatible  database  files
  1107.         (extension  '.DBF')  for later use.  These database files contain
  1108.         all necessary information like function or data type  names,  the
  1109.         location   where   they   are   defined,    their   caller/callee
  1110.         relationship,  all  scanned  files  with  statistic  information,
  1111.         include files and so on. It was tried to store the information in
  1112.         the  most  compact  and effective database structure to save disk
  1113.         space.  Note that if  the  contents  of  the  database  files  is
  1114.         manipulated  by external tools like dBASE or something else,  the
  1115.         internal consistency will be corrupted and  wrong  or  unexpected
  1116.         results will happen!
  1117.  
  1118.         The  database  can be used to recall information,  for example to
  1119.         find out,  if and in which file and  on  which  line  a  specific
  1120.         function or data type is defined. A previously generated database
  1121.         can  be  read into CFT and CST (option -g) to add new files to it
  1122.         and/or to produce another  output  file  with  new  configuration
  1123.         options,  for  example  with the reverse call tree or only with a
  1124.         special selected item  of  interest  to  be  displayed.  Such  an
  1125.         incremental  database generation is also useful if large projects
  1126.         can be divided into a set of  commonly  used  files  and  project
  1127.         specific  files.  A  good example for this is the GNU C compiler,
  1128.         which consists of a set of language independent files  and  three
  1129.         language  dependent  file  sets  for C,  C++ and Objective-C.  To
  1130.         analyse this software with CFT or CST,  the language  independent
  1131.         part  can be stored into a database which is later reused for the
  1132.         language  dependent  parts  to  build   the   complete   set   of
  1133.         information.
  1134.  
  1135.         The  ability  to  retrieve information about the sources from the
  1136.         database is quite useful in  many  cases.  Recalling  information
  1137.         from  a  database  is much faster than processing all the sources
  1138.         again to find a specific item of interest.  The documentation and
  1139.         maintenance of large software projects is much more effective and
  1140.         easier  to do if the developer has a tool to navigate through the
  1141.         source code and that  helps  him  in  his  comprehension  of  the
  1142.         program and its internal structure. It is also useful for reverse
  1143.         engineering  of  source  code  to get an overview of the internal
  1144.         program structure.  Together with user programmable editors it is
  1145.         possible to offer the user a source code browser with a hypertext
  1146.         like feeling by integrating database recalling functions into the
  1147.         editors.
  1148.  
  1149.         Additional  utility  programs,  called CFTN and CSTN (for CFT and
  1150.         CST),  which can be used to retrieve information from  databases,
  1151.         are  available  with supporting macros for their integration into
  1152.         the BRIEF,  QEDIT or MicroEMACS editor,  which are  described  in
  1153.         another  section  later in this manual.  The SXT windows versions
  1154.         provide an interface to the databases with DLL's.
  1155.  
  1156.  
  1157.  
  1158.  
  1159.                                      - 19 -
  1160.  
  1161.  
  1162.         6    PROGRAM LIMITATIONS
  1163.  
  1164.         First of all,  CFT and CST (and the other  SXT  programs)  cannot
  1165.         replace a compiler or a syntax checker like 'LINT' (for C/C++) to
  1166.         detect  errors  in the source code.  This means that it should be
  1167.         possible to compile the source code without fatal  errors  before
  1168.         it  is  possible to analyse it,  otherwise the processing results
  1169.         may be incorrect (and may be the system crashes ...).
  1170.  
  1171.         However,  there are some situations where  CFT  and  CST  can  be
  1172.         useful to detect bugs and inconsistencies in the source code like
  1173.  
  1174.         -    multiple definitions of functions or data types,
  1175.         -    different function return types,
  1176.         -    implicit declared functions with no prototype,
  1177.         -    function definitions used as prototype,
  1178.         -    recursive,  nested,  hidden  and  frequent  calls of include
  1179.              files,
  1180.         -    unterminated strings or character constants,
  1181.         -    nested comments,
  1182.         -    unterminated comments at end of file,
  1183.         -    misbalanced braces,
  1184.         -    unexpected end-of-file characters inside files,
  1185.         -    illegal characters in the source code,
  1186.         -    wrong number of macro arguments,
  1187.         -    missing macro arguments,
  1188.         -    misbalanced '#if...' control blocks.
  1189.  
  1190.         These  code  checks  are  done  on  multiple  files  in  multiple
  1191.         directories  so  that inconsistencies between different files can
  1192.         be found and displayed.  This is a capability which  conventional
  1193.         compilers  working only on a single file at a time cannot provide
  1194.         and will miss therefore (maybe the linker will find some of these
  1195.         inconsistencies).
  1196.  
  1197.         Some statistical information about the source  code  may  not  be
  1198.         correct  if  preprocessing  is  enabled  (-P).  This  affects all
  1199.         options which do statistics like the -p or -s option. The size of
  1200.         the 'pure' source code may not be correct due to macro  expansion
  1201.         or  removing  of  unnecessary blanks.  However,  the file size is
  1202.         always correct because it will be taken from the source file.
  1203.  
  1204.         Most of  the  program  limitations  are  caused  by  the  limited
  1205.         available  memory.  This  means  that  the more conventional main
  1206.         memory you have, the better it is.  The real mode versions of CFT
  1207.         and CST do not use expanded or extended memory, no virtual memory
  1208.         management  or  disk  file  swapping,  so  keep your conventional
  1209.         memory free of memory consuming TSR programs and other  utilities
  1210.         if  you  want  to  process  a  large number of files.  The use of
  1211.         operating systems like MS-DOS 6.0  and/or  memory  managers  like
  1212.         EMM386,  QEMM  or 386MAX to get more free conventional memory may
  1213.         help to handle big applications with a large number of files.  If
  1214.         memory  problems still occur during processing,  there is an easy
  1215.         way to break the memory limits: use the  32  bit  protected  mode
  1216.         versions of CFT and CST, called CFT386 and CST386. These programs
  1217.         are  running  in  protected  mode  and  so  they  have  no memory
  1218.  
  1219.  
  1220.                                      - 20 -
  1221.  
  1222.  
  1223.         limitations and are faster than the real mode versions.  You  can
  1224.         also  use the Windows 3.1,  Win32s,  Windows-NT and OS/2 versions
  1225.         which have also no memory limitations.
  1226.  
  1227.         The number and the sizes of  files  to  be  processed  is  nearly
  1228.         unlimited  with  2^14  files  and 2^31 bytes maximum file length.
  1229.         Each file can have 2^16 lines.  The number of functions and  data
  1230.         types  being  handled is limited to 2^14.  These values are given
  1231.         for the real mode versions,  the protected mode versions  usually
  1232.         exceed  them.  These  limitations  should  be enough even for the
  1233.         biggest project that could be mentioned.
  1234.  
  1235.         The ISO/ANSI C minimum requirement for include file nesting is  8
  1236.         levels,  this  will  be  fulfilled  by  CFT and CST.  The maximum
  1237.         include file nesting level is limited  by  the  number  of  files
  1238.         (streams) which can be opened simultaneously by one program. This
  1239.         is  a  compiler  specific  limit  usually coming from the library
  1240.         startup code.  The number of open files (streams) is  defined  by
  1241.         the  macro  FOPEN_MAX  in  the  include  file  'stdio.h'.  During
  1242.         preprocessing the number of nested files  is  usually  less  than
  1243.         FOPEN_MAX  because  several  streams  are  already  used  for the
  1244.         default I/O (stdin, stdout,  stderr,  stdaux,  stdprn).  Also the
  1245.         preprocessor  needs  additional  streams  besides  those  for the
  1246.         source and include files: One stream  for  the  temporary  output
  1247.         file,  one  for  a  log-file  (if option -L is set) and one for a
  1248.         filelist file (if this is declared on the command line  with  @).
  1249.         The  maximum  number of files being opened simultaneously differs
  1250.         for the various SXT program versions due to the  built-in  limits
  1251.         of the different compilers used to produce them. All SXT programs
  1252.         which  process  include files (CFT,  CST,  FFT) should be able to
  1253.         handle at least 10 nesting levels.  The message for  the  include
  1254.         file open error is 'too many open files'.
  1255.  
  1256.         The  integrated C-preprocessor limits the size of expanded macros
  1257.         to 6 Kbytes.  The number  of  macros  simultaneously  defined  is
  1258.         unlimited  (ISO/ANSI:  1024)  and  only affected by the available
  1259.         memory.   The  number  of  macro  parameters  is  limited  to  31
  1260.         (ISO/ANSI:  31)  and  there  are  up to 31 significant characters
  1261.         (ISO/ANSI: 31) recognised.  The conditional  compilation  nesting
  1262.         levels  of  '#if  ...  #endif'  control  blocks  is limited to 32
  1263.         (ISO/ANSI: 8).
  1264.  
  1265.         The line length is unlimited (ISO/ANSI: logical (?)  line  length
  1266.         is  509  characters).  The  number  of  characters  in  a  string
  1267.         (including '\0') is 2048 (ISO/ANSI: 509).  The number of  members
  1268.         in  one structure/union is unlimited (ISO/ANSI: 127),  the number
  1269.         of structure/union nesting levels is unlimited (ISO/ANSI: 15).
  1270.  
  1271.         The recognition of C/C++ identifiers like function  and  variable
  1272.         names follows the standard rules: an identifier consists of upper
  1273.         and  lower  case  letters (A-Z,  a-z),  underscore (_) and digits
  1274.         (0-9),  additionally  the  dollar  sign  ($)  will  be  accepted.
  1275.         National character set extensions as they are usual for languages
  1276.         in  european  countries  like  Germany,  Denmark or Sweden can be
  1277.         defined with option -J.
  1278.  
  1279.  
  1280.  
  1281.                                      - 21 -
  1282.  
  1283.  
  1284.         C++ comments '//...' are usually only recognised if  option  -C++
  1285.         is  set.  However,  to  accept the non-standard extension of some
  1286.         compilers which allow such comments also in C source code, option
  1287.         -// can be used therefore.  Nested C style comments '/*...*/' are
  1288.         not allowed and will always produce warnings.
  1289.  
  1290.         CFT  and  CST  may  produce  warnings  with wrong line numbers if
  1291.         preprocessing is enabled (option -P) and if  the  warning  occurs
  1292.         inside a comment.  The reason is that line number synchronisation
  1293.         with '#line ...' is only guaranteed for executable source but not
  1294.         for comments.  In such a situation  the  source  code  should  be
  1295.         processed  without  -P  to  get  the  correct  line  number (such
  1296.         warnings are usually related to unexpected characters).
  1297.  
  1298.         The calculation depth of  the  critical  function  call  path  or
  1299.         structure  nesting  level  is  unlimited.  The  calculation is an
  1300.         extremely  recursive function and was successfully tested  up  to
  1301.         more than 100 nesting levels.  It is not known from which nesting
  1302.         level on a stack overflow will happen.
  1303.  
  1304.         CFT cannot recognise and reference a function if it is used  with
  1305.         its  pure  name  without parentheses.  This happens if a function
  1306.         name is assigned to a function pointer  variable  or  used  as  a
  1307.         function pointer argument in a function call. Indirect calls to a
  1308.         function  via  a  function pointer cannot be resolved.  A similar
  1309.         case with FFT is the use of function names as  formal  parameters
  1310.         and their use within subroutines or functions.
  1311.  
  1312.         CFT will be confused in some rare cases by extensive type-casting
  1313.         operations  like  'void __based(void) * __cdecl ...  ()' and will
  1314.         display unexpected messages.  A  function  prototype  declaration
  1315.         inside  a  function  block  ('function  given scope') will not be
  1316.         recognised by CFT as a prototype declaration,  instead it will be
  1317.         misunderstanded  as  a  function call.  In assembler source code,
  1318.         some definitions of local variables seem to look like a  function
  1319.         or  a  label definition and are treated by CFT like that although
  1320.         this may be wrong in some cases.  It is also not always  possible
  1321.         to  detect  a  call  of  a  local label correctly.  CFT sometimes
  1322.         displays warning messages about  'return  type  mismatch'  though
  1323.         this  may  be  correct in that special case because the different
  1324.         types are earlier defined by a 'typedef' declaration.  The reason
  1325.         is  simply  that  CFT doesn't recognise these 'typedef's (but CST
  1326.         does!), it looks only for function names.
  1327.  
  1328.         An often requested feature for CST  is  the  integration  of  the
  1329.         calculation of structure/union sizes with byte offset information
  1330.         for every structure/union member. This feature is not implemented
  1331.         in  CST  although  it  would  be  possible to do this because all
  1332.         necessary information are present. The reason is that there would
  1333.         be too much overhead  for  CST  to  treat  the  various  compiler
  1334.         implementations   with   their   different   basic   type   sizes
  1335.         (sizeof(int),  sizeof(long double)) for different processor types
  1336.         (16  bit,   32  bit,   64  bit,  ...)  and  data  type  alignment
  1337.         requirements (by default and also controlled with #pragma's  like
  1338.         'align' or 'pack').  It would be possible to do this for just one
  1339.         selected compiler implementation or processor type but not for  a
  1340.  
  1341.  
  1342.                                      - 22 -
  1343.  
  1344.  
  1345.         great   number   of  them.   Especially  compilers  for  advanced
  1346.         architectures like RISC processors  have  very  complicated  type
  1347.         alignments rules depending on the data types,  alignment pragmas,
  1348.         compiler switches,  type sizes,  available  register  number  and
  1349.         register  sizes  and  resulting  structure/union/class  sizes  to
  1350.         generate  highly  optimised  code.   This  includes  usually  the
  1351.         insertion  of 'fill' bytes inside a structure/union and sometimes
  1352.         'padding bytes' at the end of a structure/union to force  aligned
  1353.         sizes on specific byte boundaries (For examples see the reference
  1354.         manual of the Intel 80960 C-Compiler iC960, release 3.0). Because
  1355.         of these reasons,  an integrated 'byte offset calculation' is not
  1356.         implemented in CST.  Instead,  you can generate a source file for
  1357.         selected   data  types  with  option  -O,   that  performs  these
  1358.         calculations,  if you compile the  generated  file  with  your  C
  1359.         compiler.  For further information see the description for option
  1360.         -O.
  1361.  
  1362.         Option -z  in  combination  with  option  -I  produces  redundant
  1363.         results  with CFT,  CST and FFT if files with executable code (or
  1364.         something that can be interpreted as that,  e.g.  function calls,
  1365.         data  types  or  COMMON  blocks)  are  included directly inside a
  1366.         function or data type block. (Especially in FORTRAN this seems to
  1367.         be common practice to include COMMON  blocks  into  function  and
  1368.         subroutine  bodies.)  For  CFT and CST (but not for FFT) also the
  1369.         call tree references will be incomplete and therefore  incorrect.
  1370.         With option -P for CFT and CST everything works fine, because the
  1371.         preprocessor  works  more  precise  as  the simple file inclusion
  1372.         mechanism option -I uses.
  1373.  
  1374.         SUMMARY
  1375.  
  1376.         The above described limitations can lead in  some  situations  to
  1377.         misinterpretations  or  loss of information of the scanned source
  1378.         code. The only way to avoid these lacks would be the inclusion of
  1379.         parts of a 'real compiler' to handle the complete language syntax
  1380.         in any possible situation.  But this was not the  intention  when
  1381.         the  development  of  these  programs as 'little' and easy to use
  1382.         general purpose programming supporting tools  began.  Although  I
  1383.         hope  that  the  SXT  programs will in most cases be powerful and
  1384.         useful development and documentation tools!
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.                                      - 23 -
  1404.  
  1405.  
  1406.         7    SXT OPTIONS
  1407.  
  1408.         This section gives a complete overview about all SXT options  and
  1409.         their  syntax.  It  gives  also  remarks  for their use and shows
  1410.         several examples with  detailed  descriptions.  The  options  are
  1411.         case-sensitive!  There  are  no differences between the real mode
  1412.         and the other versions  of  the  SXT  programs.  In  the  Windows
  1413.         versions,  all options can be set both on the command line and by
  1414.         menu selections and dialog windows.  For  every  option  the  SXT
  1415.         programs which support it are listed in parentheses.
  1416.  
  1417.         This  section of the documentation should be read very careful by
  1418.         all users to get a complete overview about all the features which
  1419.         are provided.
  1420.  
  1421.         THE OPTIONS ARE LISTED IN LEXICOGRAPHICAL ORDER.
  1422.         NONE OF THE OPTIONS IS SET BY DEFAULT.
  1423.  
  1424.         SYNTAX:   CFT [options [$cmdfile]] <[+]file> <@filelist>
  1425.                   CST [options [$cmdfile]] <[+]file> <@filelist>
  1426.                   DFT [options [$cmdfile]] <[+]file> <@filelist>
  1427.                   FFT [options [$cmdfile]] <[+]file> <@filelist>
  1428.                   LFT [options [$cmdfile]] <[+]file> <@filelist>
  1429.  
  1430.  
  1431.         OPTIONS:       (valid for SXT program)
  1432.  
  1433.  
  1434.         -Bsizes        (CFT, CST)
  1435.         Redefine the basic type sizes and pointer type sizes (all  values
  1436.         must  be declared in bytes) for conditional preprocessor controls
  1437.         with the 'sizeof()' keyword like '#if  sizeof(int)  ==  4'.  This
  1438.         option is only valid with the -P option.
  1439.  
  1440.         The required format for this option is
  1441.  
  1442.              -Bv,c,s,i,l,f,d,ld*data,code
  1443.                                |
  1444.              (delimiter between data and pointer sizes is '*')
  1445.  
  1446.         with  the  following types and their respective default data size
  1447.         values in bytes (the pointer type sizes are model dependent):
  1448.  
  1449.         v    :    void (sizeof(void) is usually 0, but for GNU-C it is 1)
  1450.         c    :    char (1 byte)
  1451.         s    :    short (by definition 2 bytes, hardware independent)
  1452.         i    :    integer (hardware dependent, 2 or 4 bytes)
  1453.         l    :    long (4 bytes)
  1454.         f    :    float (4 bytes, IEEE format)
  1455.         d    :    double (8 bytes, IEEE format)
  1456.         ld   :    long double (10  bytes,  IEEE  format,  some  compilers
  1457.                   assume  long  double == double (= 8 bytes),  some CPU's
  1458.                   and their compilers have special alignment requirements
  1459.                   like the Intel 80960,  where sizeof(long double) is  16
  1460.                   bytes  due  to  register and memory access requirements
  1461.                   and structure alignment)
  1462.  
  1463.  
  1464.                                      - 24 -
  1465.  
  1466.  
  1467.         data :    data pointer (type pointers, 2 or 4 bytes, memory model
  1468.                   dependent)
  1469.         code :    code pointer (function pointers,  2 or 4 bytes,  memory
  1470.                   model dependent)
  1471.  
  1472.         The  sizes  of  signed and unsigned types of the same basic types
  1473.         are considered equal, this means that, for example, the following
  1474.         expression is true:
  1475.  
  1476.              sizeof(unsigned int) == sizeof(signed int) == sizeof(int)
  1477.  
  1478.         The sizes of type pointers to data and function pointers to  code
  1479.         are  also  considered equal,  this means that,  for example,  the
  1480.         following expressions are true:
  1481.  
  1482.              sizeof(int *) == sizeof(float *)
  1483.              sizeof(int (*)()) == sizeof(float (*)())
  1484.  
  1485.         A 64 bit (8 bytes) integer type like 'long long int' or  'bigint'
  1486.         (or  something  else)  is  currently  not supported although some
  1487.         (co-)processors and their assemblers are able to handle  it  (see
  1488.         Intel  80960  assembler manual for examples).  Also the DEC Alpha
  1489.         processor with its 64 bit architecture should support this.
  1490.  
  1491.         If the -B option is not set,  the default values for the  various
  1492.         memory  models  and  compiler types (as they are known to me) are
  1493.         used,   the  assumed  target  hardware   has   an   Intel   80x86
  1494.         microprocessor.  Note that during preprocessing type modificators
  1495.         like "near" or "far" are not recognised.
  1496.  
  1497.         If the -B and the -T options are  not  set,  the  sizes  of  data
  1498.         pointers and code pointers are always considered equal:
  1499.  
  1500.              sizeof(int *) == sizeof(int (*)())      (= 4, large model)
  1501.  
  1502.         For   example,   -B0,1,2,2,4,4,8,10*4,4   would  be  the  correct
  1503.         declaration for MS-C  7.0,  large/huge  memory  model,  with  the
  1504.         values for data types (void = 0,  char = 1,  short = 2,  int = 2,
  1505.         long = 4, float = 4,  double = 8 and  long double = 10 bytes) and
  1506.         pointers  to  data  types  and  function  pointers  (all values 4
  1507.         bytes).  These values are set automatically by defining -TMSC70,L
  1508.         (or  -TMSC70,H) as compiler type and memory model description for
  1509.         preprocessing.
  1510.  
  1511.  
  1512.         -BATCH[inifile]     (SXT WINDOWS VERSIONS ONLY)
  1513.         This command line option can be used with the SXTWIN programs. It
  1514.         allows to start a SXTWIN program in batch  mode  via  the  'File'
  1515.         'Run' menu.  The SXTWIN program is started, executes the commands
  1516.         (from the command line and INI-file) and is closed  automatically
  1517.         after  having finished its job.  The optional parameter 'inifile'
  1518.         specifies the complete name (drive:/dir/filename) of the INI-file
  1519.         that should be used for analysis.
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.                                      - 25 -
  1526.  
  1527.  
  1528.         -C++           (CFT, CST)
  1529.         Enable C++ source code processing.  This includes the handling of
  1530.         C++  comments  '//...',  the  recognition of C++ keywords and the
  1531.         definition of the macro name '__cplusplus' for preprocessing.  If
  1532.         a   supported   compiler  defines  additional  macro  names  like
  1533.         '__TCPLUSPLUS__' for Turbo-C they will  also  be  defined  before
  1534.         preprocessing.  Option  -C++  is strictly required to process C++
  1535.         code correct.
  1536.  
  1537.  
  1538.         -CALL          (FFT)
  1539.         Recognise and display only subroutine 'CALL ...' statements in  a
  1540.         function  or  subroutine  body.  In some cases this option can be
  1541.         useful if the source code scanner gets confused by indexed  array
  1542.         accesses  which  might be misinterpreted as function calls.  With
  1543.         this option only the 'CALL ...' statements are detected.
  1544.  
  1545.  
  1546.         -CLIPPER       (DFT)
  1547.         Handle CLIPPER specific extensions: comments '//' and '/* ... */'
  1548.         and extended charactere set ':{}'. By default, the dBASE comments
  1549.         indicated by '*',  'NOTE' and '&&' are handled and ':{}' are  not
  1550.         recognized as valid characters.
  1551.  
  1552.  
  1553.         -COMMON        (FFT)
  1554.         Recognize  and  display  COMMON  block  names.  The block name is
  1555.         surrounded by '/' like /name/,  a blank COMMON block is named //.
  1556.         In the output file,  COMMON block names are handled like function
  1557.         names,  e.g.  the call statistics says '# calls'.  Note that  the
  1558.         BRIEF  and  MicroEMACS macros cannot handle block names correctly
  1559.         since they do not accept the '/' character.
  1560.  
  1561.  
  1562.         -CTAGS[x]      (CFT)
  1563.         This option generates a CTAGS file with information  for  VI-like
  1564.         tagging of defined identifiers. The CTAGS file is named "TAGS" by
  1565.         default  unless  the  optional  extension 'x' is used to specifiy
  1566.         another filename. Each entry in the TAGS file has the format
  1567.  
  1568.              identifier<tab>file<tab>vi-search-pattern
  1569.  
  1570.         where 'vi-search-pattern' is a regular  expression  matching  the
  1571.         line   where  'identifier'  is  defined.   This  is  the  default
  1572.         implementation for CTAGS.  Note  that  this  option  cannot  work
  1573.         together with option -P (preprocessing). The generated TAGS files
  1574.         were  successful  tested  with  the  MSDOS  versions  of VI (from
  1575.         Mortice Kern Systems Inc.) and the public domain VI-clone  ELVIS,
  1576.         but  should  also  work  with other VI versions.  See also option
  1577.         -TAGS for additional information.
  1578.  
  1579.  
  1580.         -C[s]          (CFT, CST, DFT, FFT, LFT)
  1581.         List the function/data type contents for  every  processed  file,
  1582.         's' sorts by line numbers (DEFAULT ORDER: lexicographical). There
  1583.         are additional information possible with the option -s.  A remark
  1584.  
  1585.  
  1586.                                      - 26 -
  1587.  
  1588.  
  1589.         is given if none of the functions defined in  a  file  is  called
  1590.         from  functions  defined in other files (internal versus external
  1591.         linkage). Functions for which no external caller outside the file
  1592.         is found will be marked [INTERNAL], such functions are candidates
  1593.         for defining them as 'static'. Attention: Calling a function by a
  1594.         function pointer won't be noticed!  This information is useful to
  1595.         find  out  whether  the contents of a file is unnecessary for the
  1596.         project so that the file must not be linked.  This  option  gives
  1597.         useful  information  about  source code metrics for every defined
  1598.         function.   Most  of  the  values  are  given   in   the   format
  1599.         "average [minimum ...  maximum]". Almost the same information are
  1600.         provided for data types with CST.
  1601.  
  1602.  
  1603.         -D[..]         (CFT, CST, DFT, FFT, LFT)
  1604.         Specifies macro name(s) (-Dname or -Dname1=name2)  or  file  with
  1605.         macro names (-D@namelist) of functions/data types which should be
  1606.         predefined and linked together,  also used as preprocessor define
  1607.         if the integrated preprocessor is called (-P).  The defined names
  1608.         are case sensitive and trigraph translation is performed on them.
  1609.         For preprocessing, the -D option has lower precedence than the -U
  1610.         option. That is, if the same name is used in both a -U option and
  1611.         a  -D option,  the name will be undefined regardless of the order
  1612.         of the options.
  1613.  
  1614.         The definition of a string as replacement for  a  macro  name  is
  1615.         different  on the command line and inside a macro definition file
  1616.         or command file (marked with  '$').  On  the  command  line,  the
  1617.         double  quotation  marks must be 'escaped' and the string must be
  1618.         quoted like '-DXYZ="\"123\""' (similar  to  C  strings)  to  work
  1619.         correctly,  the  reason  is  the  DOS  wildcard  expansion of the
  1620.         command line.  Inside a macro definition  or  command  file,  the
  1621.         double  quotation marks need not be 'escaped',  so the definition
  1622.         can be written like '-DXYZ="123"'.  This option cannot be used in
  1623.         environment  defines  if  the equal sign '=' is used because this
  1624.         produces a syntax error for DOS when trying to store a  'SET=...'
  1625.         command  with  a second equal sign in one line.  If a define item
  1626.         consists  of  two  words  see  the  notes  at  option  -S  for  a
  1627.         description.  Keep  these  differences  and exceptions in mind to
  1628.         avoid unexpected results using the -D option.
  1629.  
  1630.  
  1631.         -Ename         (CFT, CST, FFT)
  1632.         Almost the same as -I, but the path for the include files will be
  1633.         taken from the  environment  variable  'name'.  Typing  -EINCLUDE
  1634.         would produce the same results as -I alone.
  1635.  
  1636.  
  1637.         -E[..]         (DFT, LFT)
  1638.         Specifies  name(s)  (-Ename)  or file with names (-E@namelist) of
  1639.         external or builtin functions. For LISP, this option is useful if
  1640.         GNU-Emacs Lisp source code is scanned to  reduce  the  number  of
  1641.         undefined  functions  listed  in  the  output  file.  A  list  of
  1642.         GNU-EMACS (version 18.59) builtin functions  is  given  with  the
  1643.  
  1644.  
  1645.  
  1646.  
  1647.                                      - 27 -
  1648.  
  1649.  
  1650.         file  GNULISP.FCT.  For DBASE,  CLIPPER and FOXBASE,  this option
  1651.         prevents output of builtin functions/keywords.  An  example  file
  1652.         with DBASE functions/procedures is provided with DBASE.FCT.
  1653.  
  1654.  
  1655.         -F             (CFT, CST, DFT, FFT, LFT)
  1656.         Use  only ASCII characters for the calltree output instead of the
  1657.         DEFAULT semigraphic characters.  This option  is  useful  if  the
  1658.         generated  output  file should be printed on a printer which does
  1659.         not support semigraphic characters like they are defined  in  the
  1660.         IBM character set. It can also be used to prepare the output file
  1661.         for  use  in a WINDOWS application like MicroEMACS if there is no
  1662.         font with semigraphics available.
  1663.  
  1664.  
  1665.         -G[name]       (CFT, CST, DFT, FFT, LFT)
  1666.         Generate a database with the complete set  of  information  about
  1667.         the processed sources.  The additional parameter 'name' (path and
  1668.         filename) is used as an unique base name for the set of  database
  1669.         files  (up  to  6  significant characters),  the DEFAULT SXT NAME
  1670.         ('CXT',  'DXT',  ...) is used if no name is specified.  If 'name'
  1671.         ends with a (back-)slash, it is used as a pathname. The generated
  1672.         database files (extension '.DBF') are dBASE compatible. There are
  1673.         two  additional files created,  one with the command line options
  1674.         (extension '.CMD') and one  with  a  list  of  the  source  files
  1675.         (extension '.SRC') being use for database generation. They can be
  1676.         used as command line definition files with '$' (command list) and
  1677.         '@' (file list).
  1678.  
  1679.         As  a result of the database generation you will find files named
  1680.         'CXTxy.ext' (or other SXT names) respectively 'namexy.ext'  (user
  1681.         defined 'name'),  where 'x' will be 'F' (function) for CFT,  DFT,
  1682.         FFT and LFT or 'S' (structure) for CST,  'y' is  replaced  by  an
  1683.         internally  used  character  to mark the different database files
  1684.         and their contents.
  1685.  
  1686.  
  1687.         -H[elp]        (CFT, CST, DFT, FFT, LFT)
  1688.         See option -?.
  1689.  
  1690.  
  1691.         -HTML[x]       (CFT, CST, DFT, FFT, LFT)
  1692.         This  option  generates  a  HTML  (HyperText   Markup   Language)
  1693.         compatible  calltree  output  file which can be viewed with a WWW
  1694.         (World Wide Web) Browser like NCSA Mosaic or Netscape.  The  HTML
  1695.         output  is  done in parallel with the '.LST' output file,  so all
  1696.         calltree options like -r -R -a and others (see -N) influence also
  1697.         the HTML output.  The HTML output file is named "prog.HTM" (where
  1698.         'prog' is one of CFT, CST, DFT, FFT or LFT) by default unless the
  1699.         optional  extension 'x' is used to specifiy another filename.  If
  1700.         you have access to NCSA Mosaic  or  Netscape  you  can  view  the
  1701.         generated  HTML  output file with the builtin preview option as a
  1702.         local file  and  use  the  hyperlinks  to  explore  the  calltree
  1703.         relationships  of  the  analysed source code (For best results in
  1704.         viewing the calltree with a WWW client,  select a fixed-size font
  1705.         e.g.  Courier).  The SXT-HTML feature was tested with NCSA Mosaic
  1706.  
  1707.  
  1708.                                      - 28 -
  1709.  
  1710.  
  1711.         for MS-Windows v2.0 beta 3 and  Netscape  1.0.  A  copy  of  NCSA
  1712.         Mosaic  can  be  downloaded  with  FTP  from 'ftp.ncsa.uiuc.edu',
  1713.         Netscape can be found at 'ftp.mcom.com'.
  1714.  
  1715.  
  1716.         -I[path]       (CFT, CST, FFT)
  1717.         This option enables the scanning of include files  declared  with
  1718.         '#include "..."' or '#include <...>' or with a similar syntax for
  1719.         FORTRAN.  The  required  path for the include files is taken from
  1720.         the INCLUDE environment variable (DEFAULT BEHAVIOUR)  or  can  be
  1721.         user  defined  by 'path'.  Paths defined with -I will be searched
  1722.         before any other paths taken from environment variables specified
  1723.         by -E or -P,  so care should be taken with that  option.  Include
  1724.         paths  can be given either absolute or relative.  A relative path
  1725.         is always considered relative to the directory of the source file
  1726.         it is used with,  not to the directory the  analysis  is  started
  1727.         from  or  the  analysis  program  is  located.  For preprocessing
  1728.         (option -P) declaring -I* ignores missing include files or errors
  1729.         with files which could not  be  opened  due  to  compiler  limits
  1730.         (message 'too many open files', see chapter PROGRAM LIMITATIONS).
  1731.         This  is  a  'quick  and  dirty'  approach,  but can sometimes be
  1732.         useful,  if include file locations are unknown  or  inaccessible.
  1733.         However, the results will not be absolutely correct.
  1734.  
  1735.         Using  the  -I or -E option without -P allows the scanning of the
  1736.         source file and the included files without preprocessing. In that
  1737.         case an include file is handled as if  it  were  a  complete  new
  1738.         file,  this  can  lead to errors if a file inclusion is specified
  1739.         within a function or structure.  Also preprocessor controls  like
  1740.         '#if  ...'  are not evaluated and can lead to unexpected results.
  1741.         Remember this especially if you place  special  comment  sections
  1742.         enclosed in '#if 0 ... #endif' blocks.
  1743.  
  1744.  
  1745.         -Jcharset      (CFT, CST, DFT, FFT, LFT)
  1746.         Extend  the  DEFAULT  character for identifier recognition with a
  1747.         user defined character set  'charset'.  All  characters  must  be
  1748.         specified within one -J option.  The following default identifier
  1749.         character sets are used:
  1750.  
  1751.              C/C++     a-z A-Z 0-9 _$
  1752.              DBASE     a-z A-Z 0-9 _
  1753.              FORTRAN   a-z A-Z 0-9 _
  1754.                        a-z A-Z 0-9 _$                (with option -$)
  1755.              LISP      a-z A-Z 0-9 +-.*/<=>!?:$%_&~^
  1756.  
  1757.         This option allows the programmer to use national character  sets
  1758.         as they are common in Germany, Denmark, Sweden and other european
  1759.         countries.
  1760.  
  1761.  
  1762.         -L[L][+]       (CFT, CST, DFT, FFT, LFT)
  1763.         Redirect  the  screen  output  to a file,  called 'CFT.LOG' resp.
  1764.         'CST.LOG'.  If '+' is set,  the output is both written to  screen
  1765.         and  redirected  to  the log file so that the output messages can
  1766.         both be viewed as they appear and later  analysed.  Finally,  -LL
  1767.  
  1768.  
  1769.                                      - 29 -
  1770.  
  1771.  
  1772.         resp.  -LL+ appends the output to an existing log-file,  this can
  1773.         be useful if CFT and CST are run from a batch-file to  catch  all
  1774.         output.
  1775.  
  1776.  
  1777.         -LIB[..]       (CFT)
  1778.         Specifies  name(s)  (-LIBname) or file with names (-LIB@namelist)
  1779.         of  library  functions.  Library  functions  are  not  listed  as
  1780.         undefined  functions  in  the  output  file.  Lists  of C-library
  1781.         functions are given with the files MSVC15.FCT (MS Visual C++ 1.5)
  1782.         and GCC233.FCT (GNU-C 2.3.3).
  1783.  
  1784.  
  1785.         -M             (CFT, CST, FFT)
  1786.         This option generates a source file/include file dependency table
  1787.         for every processed file.  This table shows the dependent include
  1788.         files  of  a  source file and can be used for a MAKE file.  It is
  1789.         also useful to check if the included files  are  taken  from  the
  1790.         correct  directories.  If a file is included more than once,  the
  1791.         number of inclusions will be displayed.  Note  that  this  option
  1792.         will only work correctly if options -P or -I are used, but not on
  1793.         preprocessed  files.  There  may  also  be  problems  with  files
  1794.         produced by source code generators like LEX/FLEX or YACC/BISON.
  1795.  
  1796.  
  1797.         -N             (CFT, CST, DFT, FFT, LFT)
  1798.         Disable the writing of an output file.  This option can be useful
  1799.         if,  for example, only a database (option -G) should be generated
  1800.         with CFT or CST and no output file is required.  In that case the
  1801.         sometimes  very  time consuming process of output file writing is
  1802.         skipped.  Note that for CST the writing of the byte  offset  file
  1803.         "CST_OFFS.C" will not be affected by this option.
  1804.  
  1805.  
  1806.         -NOINTR        (FFT)
  1807.         Do  not  recognise  and  display  INTRINSIC  functions  in output
  1808.         calltree.  Only subroutines and functions defined in  the  source
  1809.         code are displayed.
  1810.  
  1811.  
  1812.         -NOLIB         (CFT)
  1813.         Do  not  display  library  functions  defined with option -LIB in
  1814.         output calltree.
  1815.  
  1816.  
  1817.         -NOUNSAFE      (CFT, CST)
  1818.         This  option  warns  in  case  of  errors  with  'unsafe'   macro
  1819.         expansions  of  the  integrated  preprocessor  (option  -P) which
  1820.         otherwise  would  abort  execution   with   fatal   errors   (see
  1821.         PROBLEMS.DOC).  This  is  only  a  'work-around' that can lead to
  1822.         following errors.
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.                                      - 30 -
  1831.  
  1832.  
  1833.         -NOWARN72      (FFT)
  1834.         Do not warn if characters are found beyond  column  72.  FFT  can
  1835.         process  lines up to 132 columns length.  By default a warning is
  1836.         given if characters are found  beyond  column  72.  This  can  be
  1837.         disabled with this option.
  1838.  
  1839.  
  1840.         -O[..]         (CST)
  1841.         Specifies  name(s)  (-Oname)  or file with names (-O@namelist) of
  1842.         data types for which the  calculation  of  structure/union  sizes
  1843.         with byte offset information for every data type member should be
  1844.         performed.  Additionally  specifying  -O+  sets  a  flag  for the
  1845.         recursive collection of sub-structures during expansion which are
  1846.         displayed without specifying them by -O.  This means  that  if  a
  1847.         structure/union  consists of members which are also structures or
  1848.         unions (and so on), it is not necessary to specify all these data
  1849.         type names with -O to enable them for  byte  offset  calculation.
  1850.         Instead,  you  have  to  specify only the top most data type with
  1851.         -Oname and additionally -O+ to force CST to  select  all  related
  1852.         sub-types  for  displaying.  If  -O+  is  set  but  NO  names are
  1853.         specified, ALL structures and unions will be used for byte offset
  1854.         calculations (the resulting file can be very big)!
  1855.  
  1856.         As the result of this option,  CST generates  a  C  source  file,
  1857.         called  'CST_OFFS.C'.  This file needs some additional editing to
  1858.         declare necessary include files,  data types,  defines or pragmas
  1859.         before  it can be compiled with the C compiler for which the file
  1860.         was generated (be sure to use the same includes!).  The resulting
  1861.         executable  prints  for  every  structure/union  member  the byte
  1862.         offset relative to the beginning of the structure/union  (decimal
  1863.         and  hexadecimal)  and  the  size  of each member,  the resulting
  1864.         structure/union   size   and   also   information    whether    a
  1865.         structure/union  member  has  been  aligned (= compiler dependent
  1866.         insertion  of  fill  bytes  before  that  member)   or   if   the
  1867.         structure/union  was  padded  with fill bytes at the end of it to
  1868.         align the size to a specific length.
  1869.  
  1870.         To  get  these  information  and   to   perform   the   necessary
  1871.         calculations  therefore,  the source file 'CST_OFFS.C' can become
  1872.         very large and makes use of the C macro programming capabilities,
  1873.         which  may  lead  in  some  rare  cases  to  errors  during   the
  1874.         compilation due to the internal limitations of some C compilers.
  1875.  
  1876.         The  -O  option  is  very useful if you need detailed information
  1877.         about structures/unions in case of error searching and debugging,
  1878.         especially for hardware debugging with an ICE.  It is also useful
  1879.         for  finding  out  the  differences  in  the internal layout of a
  1880.         structure/union in the case of  porting  C  source  code  between
  1881.         different   compilers   and/or   operating  systems  or  if  data
  1882.         structures are exchanged between  different  hardware  platforms,
  1883.         for  example  with  data  communication.  You  can  verify if the
  1884.         expected structure/union layout and size is  really  produced  by
  1885.         the target compiler.
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.                                      - 31 -
  1892.  
  1893.  
  1894.         -P[name]       (CFT, CST)
  1895.         Run  the integrated C preprocessor before the file scan.  In this
  1896.         case the include path  is  taken  from  the  INCLUDE  environment
  1897.         variable  (DEFAULT  BEHAVIOUR),  from  the  user  defined  'name'
  1898.         environment and additional paths from -I and -E option are  used.
  1899.         If  special  paths  should  be searched before the default paths,
  1900.         they must be specified by the  -I  path  or  the  -E  environment
  1901.         option  and they must be placed on the command line before the -P
  1902.         option to be processed first. The -D, -U preprocessor defines and
  1903.         -T type and memory model and -B size  infos  are  also  used,  if
  1904.         defined.  The  path  for  the  preprocessor  output  file  can be
  1905.         specified  by  the  -v  option,  otherwise  the  current  working
  1906.         directory  will be used (DEFAULT BEHAVIOUR).  The comments in the
  1907.         source and included files will remain  until  -q  is  defined  to
  1908.         remove them. The comments are used for statistics with option -p.
  1909.         If option -C++ is set, the macro '__cplusplus' will be predefined
  1910.         before  preprocessing  to  enable  C++  macros  and  C++  comment
  1911.         recognition.
  1912.  
  1913.         If a fatal error occurs during preprocessing, the analysis of the
  1914.         file will be aborted and the next  file  in  the  queue  will  be
  1915.         processed  (if  'out  of  memory' occurs the complete analysis is
  1916.         aborted!). For a description of the error format see option -W.
  1917.  
  1918.         If you are using a compiler which is not supported by CFT and CST
  1919.         or the build-in preprocessing doesn't satisfy your needs  because
  1920.         the results seem to be different from your preprocessor,  you can
  1921.         preprocess  the  files  you  want  to  analyse  with   your   own
  1922.         preprocessor  and  use  these files as input for CFT and CST.  To
  1923.         ensure that the filename and line  number  references  are  valid
  1924.         your preprocessor must insert #line directives into the source.
  1925.  
  1926.         Preprocessing  with another compiler can also be necessary if the
  1927.         integrated preprocessor  has  problems  with  your  source,  e.g.
  1928.         because  the  nesting  level  for  include files is too high (see
  1929.         section PROGRAM LIMITATIONS) or it aborts during macro expansions
  1930.         (see PROBLEMS.DOC).
  1931.  
  1932.  
  1933.         -R             (CFT, CST, DFT, FFT, LFT)
  1934.         By default,  CFT and CST generate the hierarchy tree chart of the
  1935.         called function/data type ("CALLER:CALLEE relation",  "WHO CALLES
  1936.         WHOM").  The -R option produces an inverted listing  showing  the
  1937.         callers/users of each function/data type. It generates the output
  1938.         as  the  function/data  type  hierarchy member list tree chart in
  1939.         reverse order as a list of calling items of the referenced  basic
  1940.         item  ("CALLEE:CALLER relation",  "WHO IS CALLED BY WHOM").  This
  1941.         option is useful to  get  the  relations  between  functions/data
  1942.         types and their callers/users.
  1943.  
  1944.  
  1945.         -RATIONAL      (CFT, CST, DFT, FFT, LFT)
  1946.         This  option  generates so called 'Petal' files for Rational Rose
  1947.         (Windows),  a  CASE-tool  supporting  the  Booch  Object-Oriented
  1948.         Analysis and Design (OOAD) method. The generated output files can
  1949.         be  imported by Rational Rose to use the builtin capabilities for
  1950.  
  1951.  
  1952.                                      - 32 -
  1953.  
  1954.  
  1955.         visualisation,  but in the case of the SXT programs (mis-)used to
  1956.         graphically  visualize  the  calling  relationships  of functions
  1957.         resp. data types.   The -RATIONAL option is a work-around for the
  1958.         missing  graphical layout capabilities of the SXT programs (which
  1959.         some users have requested in  the  past)  by  using  an  external
  1960.         program for doing the missing features.
  1961.  
  1962.         Two  different types of description files are generated,  one for
  1963.         class diagrams and one for finite state machine  (FSM)  diagrams.
  1964.         The class diagram files are named 'sxtprog.PTL' and the FSM files
  1965.         'sxtprog_FSM.PTL'  with  'sxtprog' as the name of the SXT program
  1966.         being  used.   CST   generates   two   additional   files   named
  1967.         'CSTCLASS.PTL'    and   'CSTCLFSM.PTL'   describing   the   class
  1968.         inheritance relationships in the same way. In the class diagrams,
  1969.         for functions (CFT, DFT, FFT, LFT) the USES-relationship was used
  1970.         to display the calling relationsships (the classes are misused as
  1971.         functions),    whereas   for   data   types   and   classes   the
  1972.         INHERITANCE-relationsship is used.
  1973.  
  1974.         If  you  have  Rational  Rose,  you have to perform the following
  1975.         steps to get impressive results: Start Rational  Rose,  select  a
  1976.         new  model ('File' - 'New') and import the generated file ('File'
  1977.         - 'Import...').  If you  imported  a  FSM  description,  a  class
  1978.         diagram  with  one  class symbol named 'CallGraph' (FSM) appears.
  1979.         Click on that symbol and choose 'Browse' - 'State  Diagram'.  Now
  1980.         select  'Tools'  -  'Layout'  to  start  the  layout optimization
  1981.         function.  As the result the graphical call tree  of  the  source
  1982.         code  analysis is displayed with each function/data type shown as
  1983.         a circle ('state') and the call relationship shown  as  an  arrow
  1984.         ('transaction') from the calling to the called item,  for classes
  1985.         from the superclass to  the  subclass.  You  can  zoom  into  the
  1986.         diagram,  print the results or incorporate the diagrams into your
  1987.         program documentation via Clipboard, e.g. into Word for Windows.
  1988.  
  1989.         In case of a class description file,  a class category  with  one
  1990.         category named 'Program' appears after file import.  Double click
  1991.         on that symbol to open the associated class diagram and  activate
  1992.         the layout function. As the result the graphical call tree of the
  1993.         source  code  analysis is displayed with each function shown as a
  1994.         class and the call relationship shown as a double line  from  the
  1995.         calling (circle) to the called function.
  1996.  
  1997.         NOTE:  The  SXT  programs cannot generate input for Rational Rose
  1998.         comparable to that generated by  the  C++  analyzer  of  Rational
  1999.         Rose, SXT just uses Rational Rose's printing capabilities!
  2000.  
  2001.         The -RATIONAL option was tested with the Beta version of Rational
  2002.         Rose/C++  (Windows)  2.0.  If  you get warnings reading the files
  2003.         with an earlier (later) version of Rational Rose  edit  the  file
  2004.         and reduce (increase) this value.  The SXT programs currently set
  2005.         this value 35 for version 2.5. Note that Rational Rose needs even
  2006.         for small and medium sized projects some time to import the  file
  2007.         and  process the diagram layout.  There is no guarantee that this
  2008.         will always be successful.
  2009.  
  2010.  
  2011.  
  2012.  
  2013.                                      - 33 -
  2014.  
  2015.  
  2016.         Rational Rose is  a  commercial  product,  for  more  information
  2017.         contact Rational directly at
  2018.  
  2019.              Rational,   2800  San  Tomas  Expressway,  Santa  Clara,  CA
  2020.              95051-0951, U.S.A.
  2021.  
  2022.              Rational GmbH, Rosenstr. 7, Grosshesselohe,  D-82049 Pullach
  2023.              im Isartal, Germany
  2024.  
  2025.  
  2026.         -RTF[x]        (CFT, CST, DFT, FFT, LFT)
  2027.         This  option  generates  a  RTF  (Rich  Text  Format)  compatible
  2028.         calltree output file.  The RTF output file  is  named  "prog.RTF"
  2029.         (where  'prog' is one of CFT,  CST,  DFT,  FFT or LFT) by default
  2030.         unless the optional extension 'x' is  used  to  specifiy  another
  2031.         filename.  The  RTF file can be imported by word processors which
  2032.         can handle RTF (e.g.  Word  for  Windows).  Another  very  useful
  2033.         feature is the possibilty to generate a Windows Helpfile from the
  2034.         RTF output.  This can be done by using the Microsoft Windows Help
  2035.         Compiler HC31.EXE which compiles the .RTF file into a  .HLP  file
  2036.         (e.g.  'hc31  cft.rtf'  generates  cft.hlp).  The helpfile can be
  2037.         viewed with WINHELP.EXE.  It contains a searchable sorted list of
  2038.         all  items  (functions,  types).  Similar  to  the  HTML  output,
  2039.         hypertext  links  are  embedded  which  allow  jumps  within  the
  2040.         helpfile to item definitions.
  2041.  
  2042.  
  2043.         -S[..]         (CFT, CST, DFT, FFT, LFT)
  2044.         Specify  name  (-Sname)  or  file  with  names  (-S@namelist)  of
  2045.         functions/data types to search for and to dump if present,  names
  2046.         are  case  sensitive.  These items are listed first in the output
  2047.         calltree file.  By using -S on the command line,  it is necessary
  2048.         to  surround  a  data  type  name that consists of two words with
  2049.         double quotation marks like "struct _iobuf" to  connect  the  two
  2050.         words.  This is not necessary inside a list file, but there every
  2051.         search name must be on a separate line.
  2052.  
  2053.  
  2054.         -TAGS[x]       (CFT, CST, DFT, FFT, LFT)
  2055.         This option generates a TAGS file with  information  for  VI-like
  2056.         tagging of defined identifiers.  The TAGS file is named "TAGS" by
  2057.         default unless the optional extension 'x'  is  used  to  specifiy
  2058.         another filename. Each entry in the TAGS file has the format
  2059.  
  2060.              identifier<tab>file<tab>vi-search-pattern
  2061.  
  2062.         where  'vi-search-pattern'  is  the  line  number in 'file' where
  2063.         'identifier' is defined.  As using the line  number  is  a  usual
  2064.         practice if 'typedef' definitions are included into the TAGS file
  2065.         this  should  be  no  problem.  The  generated  TAGS  files  were
  2066.         successful tested with the MSDOS versions  of  VI  (from  Mortice
  2067.         Kern  Systems  Inc.)  and  the public domain VI-clone ELVIS,  but
  2068.         should also work with other VI versions.  See also option  -CTAGS
  2069.         for additional information.
  2070.  
  2071.  
  2072.  
  2073.  
  2074.                                      - 34 -
  2075.  
  2076.  
  2077.         -Tn            (FFT)
  2078.         Set the tabulator expansion size to 'n' (DEFAULT: 8 characters).
  2079.  
  2080.  
  2081.         -Ttype,m       (CFT, CST)
  2082.         Use  this  option  to  set  the  compiler  type  for  source code
  2083.         preprocessing to one of the following types:
  2084.  
  2085.              MSC51     Microsoft C 5.1
  2086.              MSC70     Microsoft C/C++ 7.0
  2087.              MSVC15    Microsoft Visual C++ 1.5
  2088.              MSVCWNT   Microsoft Visual C++ 1.1 for Windows NT
  2089.              TC10      Borland Turbo C++ 1.0
  2090.              BC20      Borland C++ 2.0
  2091.              BC31      Borland C++ 3.1
  2092.              BC10OS2   Borland C++ 1.0 for OS/2
  2093.              GNU       GNU-C
  2094.              I960      Intel 80960 iC960 3.0
  2095.  
  2096.         The supported memory models are T(iny)  (valid  only  for  MSC70,
  2097.         MSVC15, TC10, BC20, BC31), S(mall), M(edium), C(ompact), L(arge),
  2098.         H(uge),  'L'  is assumed as default if no model is specified.  MS
  2099.         Visual C++ for Windows NT, Borland C++ for OS/2,  GNU-C and Intel
  2100.         iC960  do  not need a memory model because they compile really 32
  2101.         bit code. The Intel iC960 compiler requires the definition of the
  2102.         80960 RISC processor architecture which is one of KA, KB, SA, SB,
  2103.         MC, CA (default is KB).
  2104.  
  2105.         This option causes several compiler dependent preprocessor macros
  2106.         (if they  were  known  to  me,  however)  to  be  defined  before
  2107.         preprocessing  starts.  This  option can only be used with the -P
  2108.         option, otherwise it has no effect.
  2109.  
  2110.         If your compiler is not supported,  you can perform the following
  2111.         steps: Find out which preprocessor defines are necessary (manual,
  2112.         help  file)  and  declare  them  with  option  -D,  then declare,
  2113.         depending on the selected memory model or processor architecture,
  2114.         the type sizes with option -B.
  2115.  
  2116.  
  2117.         -U[..]         (CFT, CST)
  2118.         Specifies  a  predefined  macro  name  (-Dname)  or   file   with
  2119.         predefined   macro   names  (-U@namelist)  to  be  undefined  for
  2120.         preprocessing.  Note that  the  default  predefined  macro  names
  2121.         '__FILE__',   '__LINE__',   '__DATE__',   '__TIME__'   cannot  be
  2122.         undefined.  All other predefined names for the  various  compiler
  2123.         types  can  be undefined.  Like for -D,  the names are considered
  2124.         case-sensitive, but trigraph translation is not performed because
  2125.         the internal representation cannot contain trigraphs.
  2126.  
  2127.  
  2128.         -V             (CFT)
  2129.         List prototyped functions which are neither  called  nor  defined
  2130.         (option -a and -u). This option is useful to find unused function
  2131.         prototypes which could be probably removed from the source code.
  2132.  
  2133.  
  2134.  
  2135.                                      - 35 -
  2136.  
  2137.  
  2138.  
  2139.         -Wlevel        (CFT, CST, DFT, FFT, LFT)
  2140.         Set  error  and  warning  message  level.  Higher  warning levels
  2141.         include lower ones.  The DEFAULT  level  is  always  the  highest
  2142.         supported warning level, possible levels are:
  2143.  
  2144.         0 :  all  error  and warning messages are suppressed except fatal
  2145.              errors,
  2146.         1 :  display serious errors or warnings,
  2147.         2 :  includes level 1 plus additional errors and warnings,
  2148.         3 :  includes level 2 plus errors/warnings/remarks,
  2149.         4 :  includes level  3  plus  warnings  about  implicit  declared
  2150.              functions and lacks of type or storage class.
  2151.  
  2152.         The following levels affect only preprocessing (CFT and CST):
  2153.  
  2154.         5 :  includes   level   4   plus   warnings   and  errors  during
  2155.              preprocessing  (non-fatal   errors   and   warnings   during
  2156.              preprocessing  are otherwise not displayed,  preprocessor is
  2157.              running in 'silent mode'),
  2158.         6 :  includes  level  5  plus  remarks/slight   warnings   during
  2159.              preprocessing.
  2160.  
  2161.         The output format for messages during file scan is
  2162.  
  2163.              filename(line): error: description
  2164.              filename(line): warning: description
  2165.  
  2166.         and during preprocessing (warning levels 5 and 6)
  2167.  
  2168.              preprocessor: filename(line): error: description
  2169.                   source line
  2170.              preprocessor: filename(line): warning: description
  2171.                   source line
  2172.  
  2173.  
  2174.         -X             (CFT, CST, DFT, FFT, LFT)
  2175.         Assume  a  UNIX-style  text  file:  no CR,  only LF.  The DEFAULT
  2176.         ASSUMPTION is  a  DOS-style  text  file  with  CR+LF.  Any  other
  2177.         combination like CR in UNIX-files,  CR without following LF or LF
  2178.         without preceding CR in DOS-files will cause a  warning  message.
  2179.         This  option  is  useful  to  detect  possible  conversion errors
  2180.         between  different  operating   systems   or   incorrect   editor
  2181.         configuration settings.
  2182.  
  2183.  
  2184.         -XLAMBDA       (LFT)
  2185.         Recognise  the  LISP  resp.  SCHEME  keyword 'lambda' for unnamed
  2186.         function declarations.  By DEFAULT,  'lambda'  is  treated  as  a
  2187.         simple identifier.
  2188.  
  2189.  
  2190.         -XSCHEME       (LFT)
  2191.         Assume  SCHEME source code instead of LISP source code (DEFAULT).
  2192.         This means that functions are recognised by the  'define'  SCHEME
  2193.         keyword instead of the 'defun' resp. 'defmacro' LISP keywords.
  2194.  
  2195.  
  2196.                                      - 36 -
  2197.  
  2198.  
  2199.  
  2200.  
  2201.         -Y             (CFT, CST, DFT, FFT, LFT)
  2202.         Ignore  CR+LF  checks.  This option disables all checks which are
  2203.         done for unexpected CR+LF combinations in DOS or UNIX  files.  If
  2204.         option -Y is set,  option -X will be ignored.  This option can be
  2205.         useful if there would be too many messages concerning that  error
  2206.         or if this message would be of no interest for the user.
  2207.  
  2208.  
  2209.         -Z[s]          (CFT, CST, DFT, FFT, LFT)
  2210.         Display every caller and member for each function/data type,  's'
  2211.         sorts by the number of calls  (DEFAULT  ORDER:  lexicographical),
  2212.         this  is  an  extension  of the -c option.  This option shows the
  2213.         relations in the following form:
  2214.  
  2215.              List of parent functions/data types:
  2216.              1. caller (reference #) <# of calls from>
  2217.              ...
  2218.              n. caller ...
  2219.         function/data type (reference #) <# of calls from parents,  #  of
  2220.         calls to children>
  2221.              List of child functions/data types:
  2222.              1. called member (reference #) <# of calls to>
  2223.              ...
  2224.              m. called member ...
  2225.  
  2226.         This  compact  form lists all callers and members with the number
  2227.         of their calls, recursions are detected and displayed.  Note that
  2228.         this  option  can  be  extremely  time consuming if the number of
  2229.         source files is very large!
  2230.  
  2231.  
  2232.         -a             (CFT, CST, DFT, FFT, LFT)
  2233.         List  every  function/data  type,   also  previously   referenced
  2234.         functions/data  types.  This  generates  a complete list of every
  2235.         function/data type in lexicographical order  with  references  to
  2236.         their first location.
  2237.  
  2238.  
  2239.         -b             (CST)
  2240.         Display  the  C++  class  inheritance relationships.  This option
  2241.         generates two listings.  The first one displays the complete  C++
  2242.         class  hierarchy  graph(s).  The  second one shows for each class
  2243.         first the superclasses from which  the  class  inherits  and  the
  2244.         access restrictions (public,  protected, virtual, ...) and second
  2245.         the subclasses which inherit from  the  given  class,  also  with
  2246.         access  restrictions.  This  option  is useful to find out things
  2247.         like the class dependencies or multiple inheritance.
  2248.  
  2249.  
  2250.         -charwarn      (CFT, CST, DFT, FFT, LFT)
  2251.         Warning if unknown/illegal characters are  found  in  the  source
  2252.         code during analysis.  By default, there is no now no longer such
  2253.         a warning.
  2254.  
  2255.  
  2256.  
  2257.                                      - 37 -
  2258.  
  2259.  
  2260.  
  2261.         -cmdline       (CFT, CST, DFT, FFT, LFT)
  2262.         Print the command line options at the  beginning  of  the  output
  2263.         file  as  a remark for the generation rules for that output file.
  2264.         All options and files specified  on  the  command  line,  in  the
  2265.         environment variable,  the commandlist and the filelist files are
  2266.         listed.
  2267.  
  2268.  
  2269.         -c[s]          (CFT, CST, DFT, FFT, LFT)
  2270.         Display the number of calls to each function/data type, 's' sorts
  2271.         by the number of calls (DEFAULT ORDER:  lexicographical).  Useful
  2272.         to  find  out  which  functions/data  types are never called/used
  2273.         (maybe unnecessary and deletable) and which  ones  are  the  most
  2274.         frequently  called/used (together with profiler results a subject
  2275.         for  further  optimization  efforts).   For  FFT  see  also   the
  2276.         description for option -CALL.
  2277.  
  2278.  
  2279.         -defmacro      (LFT)
  2280.         Recognise the 'defmacro' keyword in SCHEME source code.
  2281.  
  2282.  
  2283.         -dn            (CFT, CST, DFT, FFT, LFT)
  2284.         Set the maximum function/structure/union nesting level for output
  2285.         generation  to  'n' (DEFAULT: maximum value n = 999).  This means
  2286.         that the request for displaying a deeper level will  be  rejected
  2287.         and the output calltree will be truncated at the given level.
  2288.  
  2289.  
  2290.         -e[char]       (CFT, CST, DFT, FFT, LFT)
  2291.         Generate  formatted ASCII text files with function/data type list
  2292.         and file list.  All entries are separated by the optional  'char'
  2293.         character,  if 'char ' is not defined, the tabulator character is
  2294.         used as DEFAULT SEPARATOR.  If spaces are  wanted  as  separating
  2295.         characters,  you have to write -e" ".  Such prepared files can be
  2296.         used directly as input to other  programs  like  word  processors
  2297.         (e.g.  MS-WORD  for  WINDOWS)  or  spreadsheet  calculators (e.g.
  2298.         MS-EXCEL), for example for documentation purposes.  The following
  2299.         files are created:
  2300.  
  2301.         CFTITEMS.TXT:
  2302.         Contents: function name,  return type,  filename, line #, total #
  2303.         of function bytes,  # of function comment bytes,  #  of  function
  2304.         lines, # of control statements, # of brace levels
  2305.  
  2306.         CSTITEMS.TXT:
  2307.         Contents: data type name, filename line #
  2308.  
  2309.         CFTFILES.TXT and CSTFILES.TXT:
  2310.         Contents: filename,  # of lines, file size in bytes, # of comment
  2311.         bytes, # of functions/data types
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.                                      - 38 -
  2319.  
  2320.  
  2321.         -f             (CFT, CST, DFT, FFT, LFT)
  2322.         Generate  an  output  list  in  short   form,   only   with   the
  2323.         function/data type names,  no further description of the internal
  2324.         function/data type elements.
  2325.  
  2326.  
  2327.         -filetree      (CFT, CST, FFT)
  2328.         This option displays the file hierarchy  tree  for  every  source
  2329.         file.  The  look  of  the  file  hierarchy tree is similar to the
  2330.         function hierarchy tree.  Unless option -M  displays  the  'flat'
  2331.         source vs. include file relationsship, this option shows the real
  2332.         nested  source  file include file hierarchy tree.  This option is
  2333.         useful to see how the files are related  and  nested.  Note  that
  2334.         this  option  will  only  work  correctly if options -P or -I are
  2335.         used,  but not on preprocessed files.  There may also be problems
  2336.         with  files  produced  by source code generators like LEX/FLEX or
  2337.         YACC/BISON.
  2338.  
  2339.  
  2340.         -g[name]       (CFT, CST, DFT, FFT, LFT)
  2341.         Read  a  previously  generated  database  (see  option  -G).  The
  2342.         additional  parameter  'name'  (path  and filename) is used as an
  2343.         unique base  name  for  the  set  of  database  files  (up  to  6
  2344.         significant  characters),  the  DEFAULT  NAME 'CXT' is used if no
  2345.         name is specified. If 'name' ends with a (back-)slash, it is used
  2346.         as a pathname.  Every source file will be tested for  changes  of
  2347.         file  creation  time  and file size and a warning message will be
  2348.         given to inform the user.
  2349.  
  2350.  
  2351.         -h[elp]        (CFT, CST, DFT, FFT, LFT)
  2352.         See option -?.
  2353.  
  2354.  
  2355.         -iname         (CFT, DFT, FFT, LFT)
  2356.         Ignore function member 'name' in output calltree.  It will not be
  2357.         displayed  and  will  be  skipped  instead if found as a function
  2358.         member. This option can be useful if, for example,  functions are
  2359.         used  only  for  test purposes and are of no further interest for
  2360.         the user and should be ignored in the output calltree. It is also
  2361.         possible  to  specifiy  library  functions  so  that  the  output
  2362.         calltree contains only user defined functions.
  2363.  
  2364.  
  2365.         -l             (CFT, DFT, FFT, LFT)
  2366.         List  a  function only once in case of repeated consecutive calls
  2367.         (DEFAULT: display every occurrence). If a function is called more
  2368.         than one time  inside  a  function  without  any  other  call  in
  2369.         between,  there  will be only one reference of that function call
  2370.         in the output calltree.  This option results  in  shorter  output
  2371.         files.
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.                                      - 39 -
  2380.  
  2381.  
  2382.         -mtype         (CST)
  2383.         Start  the  data  type tree chart with data type 'type' (-mtype).
  2384.         If -m+ is specified,  the output starts  with  the  topmost  data
  2385.         type,  this is the data type which is in the highest level of the
  2386.         hierarchy tree chart.  The default output is  in  lexicographical
  2387.         order  of  the  displayed  data  types.   Useful  if  a  selected
  2388.         structure/union should be  displayed  at  the  beginning  of  the
  2389.         output file.
  2390.  
  2391.  
  2392.         -m[name]       (CFT, FFT)
  2393.         -mname         (DFT, LFT)
  2394.         Start  the  function calltree dump with function 'main' (CFT -m),
  2395.         'PROGRAM' (FFT -m) or 'name' (-mname), name is case sensitive. If
  2396.         -m+ is specified,  the output starts with the  topmost  function,
  2397.         this  is  the  function  which  is  in  the  highest level of the
  2398.         hierarchy calltree.  If this option is not set,  the  default  is
  2399.         lexicographical order of the displayed functions.
  2400.  
  2401.         Usually,  the  complete  function  calltree should start with the
  2402.         'main' function so that every subfunction is  a  (sub-)member  of
  2403.         'main'.  This  option is useful for windows programs to start the
  2404.         output with the initial 'WinMain' function (-mWinMain) instead of
  2405.         'main'.  It can also be used to start the output with the initial
  2406.         assembler start-up code being executed before the 'main'-function
  2407.         is called.
  2408.  
  2409.  
  2410.         -n[a]          (CFT, CST, DFT, FFT, LFT)
  2411.         Display the most critical function call path respectively display
  2412.         the  data  structure/union  with  the maximum nesting level.  The
  2413.         modificator 'a' is used to display every function/structure  with
  2414.         its users/callers (DEFAULT: display only deepest call path). This
  2415.         option   helps  to  determine  the  complexity  of  the  function
  2416.         call/data structure hierarchy and finds recursions  over  several
  2417.         call/nesting  levels.  Note  that  for functions the maximum call
  2418.         path being displayed is the result  of  the  static  source  code
  2419.         analysis.  During  program  execution  the  call path can be even
  2420.         deeper if functions are called indirectly with function  pointers
  2421.         or similar mechanisms.
  2422.  
  2423.  
  2424.         -noundef       (CFT, DFT, FFT, LFT)
  2425.         Ignore   undefined  items  (functions,   subroutines)  in  output
  2426.         calltree.  Display only those which are  really  defined  in  the
  2427.         analysed source code.
  2428.  
  2429.  
  2430.         -ofile         (CFT, CST, DFT, FFT, LFT)
  2431.         Write  the  generated  analysis  results to file 'file'.  DEFAULT
  2432.         BEHAVIOUR: The filenames are 'CFT.LST' for CFT and 'CST.LST'  for
  2433.         CST.  Possible  overwriting  of  an existing output file with the
  2434.         same name other  than  the  default  one  will  be  detected  and
  2435.         prompted  for user reconfirming.  The resulting output file is an
  2436.         ASCII text file  with  no  formatting  characters  which  can  be
  2437.  
  2438.  
  2439.  
  2440.                                      - 40 -
  2441.  
  2442.  
  2443.         printed with every printer,  viewed and/or edited with every text
  2444.         editor and taken as input to word  processors,  for  example  for
  2445.         documentation purposes.
  2446.  
  2447.  
  2448.         -p             (CFT, CST, DFT, FFT, LFT)
  2449.         Calculate  the  program  code/file  size ratio for every file and
  2450.         make a final summary.  This option gives a short  overview  about
  2451.         the 'real' file contents versus complexity. The computed value is
  2452.         in  the  range from 0.000 (only comment,  no code) to 1.000 (only
  2453.         code, no comment). Used together with -P,  the results may not be
  2454.         absolutely correct because of the macro expanding and removing of
  2455.         parts  of  the  source  code  by  '#if...'  control  blocks.   If
  2456.         preprocessing -P is enabled, comment byte count in included files
  2457.         will not be performed. If option -q is set, -p will not calculate
  2458.         values related with comments.
  2459.  
  2460.  
  2461.         -q             (CFT, CST)
  2462.         Remove comments from preprocessed files, default is don't remove.
  2463.         This option is only valid with option -P,  it also affects the -p
  2464.         option because counting comments is not possible and calculations
  2465.         on them cannot be done.
  2466.  
  2467.  
  2468.         -qn            (FFT)
  2469.         Set  the number of continuation lines to 'n' (DEFAULT: 19 lines).
  2470.         The number must be in the range from 0 to 99.
  2471.  
  2472.  
  2473.         -r             (CFT, CST, DFT, FFT, LFT)
  2474.         This is almost the same as option  -x,  but  an  additional  file
  2475.         reference   with   the  filename  and  the  line  number  of  the
  2476.         declaration will be given (includes -x).
  2477.  
  2478.         The -r or the -x option is STRICTLY  RECOMMENDED  and  should  be
  2479.         used as a default option, because without it, every function/data
  2480.         type  will  be  completely redisplayed,  including the underlying
  2481.         subtree of functions or data types,  whenever it  occurs  in  the
  2482.         output  tree  chart  and  so  the resulting output file will grow
  2483.         immense,  up to several megabytes,  if there is enough disk space
  2484.         to write the output file.
  2485.  
  2486.  
  2487.         -s             (CFT, CST, FFT, LFT)
  2488.         Used with -C,  this option gives additional information.  For CFT
  2489.         for every function: the number of lines for  the  function  body,
  2490.         the  maximum  brace levels,  the number of bytes for the function
  2491.         body and the number of comment bytes inside  the  function  body.
  2492.         The  average  values  for  every  source  file  are  computed and
  2493.         displayed.  For CST for every data type: number of type elements,
  2494.         number of subelements (nested structures/unions).
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.                                      - 41 -
  2502.  
  2503.  
  2504.         -time          (CFT, CST, DFT, FFT, LFT)
  2505.         Print  runtime  information  about  the times consumed for source
  2506.         analysis,  preprocessing,  output  dump,   database  reading  and
  2507.         writing and for other miscellaneous jobs plus the total time. The
  2508.         results are given in the format MINUTE:SECOND.MILLISECOND.
  2509.  
  2510.  
  2511.         -touch         (CFT, CST, DFT, FFT, LFT)
  2512.         If  the  file  information in a database concerning the file date
  2513.         and the file size is out-of-date,  it  will  be  updated  if  the
  2514.         database is read (option -g) and option -touch is set.  Useful to
  2515.         avoid the warnings e.g.  with the  BRIEF  macros.  However,  this
  2516.         option  should only be used if the contents of the related source
  2517.         files has not changed. This option does not reprocess and analyse
  2518.         the related sources!
  2519.  
  2520.  
  2521.         -u             (CFT, DFT, FFT, LFT)
  2522.         List undefined functions.  These functions are  probably  library
  2523.         functions,  defined in other files which have not been scanned or
  2524.         are unresolved externals found by the linker.
  2525.  
  2526.  
  2527.         -vpath         (CFT, CST, FFT)
  2528.         Set a specific path for the intermediate precompiler output file.
  2529.         'path' can be a pathname or a drive letter  with  pathname,  e.g.
  2530.         'c:\tmp' or 'g:\' (not 'g:' without '\',  this is an error). This
  2531.         option  is  useful  to  speed  up  execution   speed   when   the
  2532.         intermediate file can be stored on a RAM-disk so that file access
  2533.         to  the  precompiled  file  is  much  faster than on a hard disk.
  2534.         Environment variables like 'TMP' or 'TEMP' to set  the  path  for
  2535.         temporary files are not evaluated.
  2536.  
  2537.  
  2538.         -x             (CFT, CST, DFT, FFT, LFT)
  2539.         Cross reference in case of multiple use.  Every function and data
  2540.         type  will  be  given  a  unique  reference  number  which   will
  2541.         furthermore  be  used  as an identifying reference number for the
  2542.         function or data type if it is again displayed.  See also  option
  2543.         -r for further descriptions.
  2544.  
  2545.  
  2546.         -y             (CFT, CST, DFT, FFT, LFT)
  2547.         Display  cross  link  list of files which contain referencing and
  2548.         referenced functions/data types  of  functions/data  types  of  a
  2549.         specific  file.  This option shows the relations in the following
  2550.         form:
  2551.  
  2552.              1. referencing file
  2553.              ...
  2554.              n. referencing file
  2555.         file
  2556.              1. referenced file
  2557.              ...
  2558.              m. referenced file
  2559.  
  2560.  
  2561.  
  2562.                                      - 42 -
  2563.  
  2564.  
  2565.         This  option  is  useful  if  you  want  to  find  out  the  file
  2566.         relationships.  This  information can be used to isolate specific
  2567.         files from a project,  e.g.  library files.  It is also useful if
  2568.         you  want  to  separate  a  function and want to know which other
  2569.         files are needed because they contain called functions. Note that
  2570.         there  may  be  problems  with  files  produced  by  source  code
  2571.         generators like LEX/FLEX or YACC/BISON.
  2572.  
  2573.  
  2574.         -z             (CFT, CST, DFT, FFT, LFT)
  2575.         Generate  a  function/data  type call cross reference table.  For
  2576.         every function/data type the location of  its  definition  (file,
  2577.         line)  and  a  complete  list of its calls/references,  sorted by
  2578.         files and line numbers is given in the following form:
  2579.  
  2580.         1. function/data type (reference #) [file #], line #
  2581.              [file #]: line #, ...
  2582.              ...
  2583.  
  2584.         2. ...
  2585.              ...
  2586.  
  2587.         The functions/data types are displayed in lexicographical  order.
  2588.         At the end of the section is the cross reference file list.  Note
  2589.         that this option can be extremely time consuming if the number of
  2590.         source files is very large!
  2591.  
  2592.  
  2593.         -$             (FFT)
  2594.         Recognise $ as identifier character, not as delimiter. Useful for
  2595.         source code written for VAX (VMS)- or IBM (MVS)-Fortran.
  2596.  
  2597.  
  2598.         -//            (CFT, CST)
  2599.         Accept C++ comments '//...' in C source code.  This option can be
  2600.         used  to  ensure  compatibility  with  C compilers which can also
  2601.         recognise C++ comments within C source code (like  Microsoft  and
  2602.         Borland).
  2603.  
  2604.  
  2605.         -?             (CFT, CST, DFT, FFT, LFT)
  2606.         Shows  the  command  line syntax and gives a short,  but complete
  2607.         help information about the accepted commands and their syntax.
  2608.  
  2609.  
  2610.  
  2611.         COMMAND LINE FILES
  2612.  
  2613.         cmdfile        (CFT, CST, DFT, FFT, LFT)
  2614.         Specifies a file with (additional)  command  line  options.  This
  2615.         might  be useful if the command line would be too long because of
  2616.         the number of options and files declared or if  you  are  usually
  2617.         using  the  same  options  which  can then be stored in a command
  2618.         file.  The initial '$'-character is required to  mark  a  command
  2619.         file.
  2620.  
  2621.  
  2622.  
  2623.                                      - 43 -
  2624.  
  2625.  
  2626.         filelist       (CFT, CST, DFT, FFT, LFT)
  2627.         A  file with a list of source file(s) to be processed,  wildcards
  2628.         are accepted.  The list file should have every file on  a  single
  2629.         line.  The  rules  for  files  containing assembler code and path
  2630.         translation are described above.  The  initial  '@'-character  is
  2631.         required  to mark a filelist file.  The '+' sign for subdirectory
  2632.         processing is also possible inside the filelist file.
  2633.  
  2634.         [+]file        (CFT, CST, DFT, FFT, LFT)
  2635.         The name of a source file to be processed. More than one file can
  2636.         be specified on the command line.  The default assumption for the
  2637.         given files is that they contain C source code.  Assembler source
  2638.         files are only recognised by the  file  extension  '.ASM'  (80x86
  2639.         MASM/TASM) and '.S' (Intel 80960, GNU).
  2640.  
  2641.         The  '+' sign indicates that,  starting from the given directory,
  2642.         all subdirectories should be searched recursively for  the  given
  2643.         filename  search  pattern.  This  addition  is  useful if a large
  2644.         software project is divided into several  modules  with  separate
  2645.         subdirectories  for  each module.  In that case only the starting
  2646.         (root-)directory with the requested filename search pattern  must
  2647.         be   specified   to   search   the   current  directory  and  all
  2648.         subdirectories.
  2649.  
  2650.         If the filename or the include file specification inside  a  file
  2651.         contains a relative path ('./',  '.\', '../' or '..\') it will be
  2652.         translated into  an  absolute  path  starting  from  the  current
  2653.         working directory respectively in case of include files depending
  2654.         on  the  path of the parent file.  Command line wildcards '*' and
  2655.         '?' are possible and will be accepted.
  2656.  
  2657.  
  2658.         REMARKS ON USING OPTIONS
  2659.  
  2660.         NONE OF THE DESCRIBED OPTIONS IS PREDEFINED SO  IT'S  UP  TO  THE
  2661.         USER  HIMSELF TO CUSTOMIZE HIS PREFERRED PROCESSING BEHAVIOUR AND
  2662.         OUTPUT STYLE BY ADDING CONTROL OPTIONS NEEDED THEREFORE.
  2663.         This assumption seems to be the best way to give  the  users  the
  2664.         freedom  of  making  their  own decisions about the features they
  2665.         really need for doing their work.
  2666.  
  2667.         However,  some of the options should  be  regarded  and  used  as
  2668.         'DEFAULT'  options  to  generate a readable,  complete and useful
  2669.         output file without  unexpected  side  effects.  So  the  minimum
  2670.         default command lines look like
  2671.  
  2672.              CFT -m -r <files>
  2673.              CST -r <files>
  2674.  
  2675.         Both  command  sets  generate  a  complete listing containing all
  2676.         defined items with  filename  and  line  reference  and  a  cross
  2677.         reference id for repeated use (options -r). The option -m for CFT
  2678.         forces  the  output to start with the 'main' function (if found).
  2679.         The precompile option -P is not  strictly  necessary  though  for
  2680.         exact  results it should also be set together with the -T option.
  2681.         The standard default command line might be
  2682.  
  2683.  
  2684.                                      - 44 -
  2685.  
  2686.  
  2687.  
  2688.              CFT -m -ruspMP -T<type> -cs -Cs -n -Zs -G <file[s]>
  2689.              CST -rpMP -T<type> -cs -Cs -n -Zs -G <file[s]>
  2690.  
  2691.         If you start using CFT and CST for your own business,  take these
  2692.         options as a basic set and try other options to get a feeling for
  2693.         what they are useful and how they affect the output.
  2694.  
  2695.         The  large  number  of options may be confusing for beginners but
  2696.         this is the only way to give users the flexibility of customising
  2697.         their own output.  Therefore,  take some time to learn about  CFT
  2698.         and  CST and their features,  read this manual carefully and make
  2699.         your own experiences with this software.
  2700.  
  2701.         It is possible to declare more than one source file, command file
  2702.         and list file on the command line.  In that  case  they  will  be
  2703.         processed  in  the  order  they appear.  Files and options can be
  2704.         placed  in  mixed  order  on  the  command  line,   there  is  no
  2705.         recommended order for them because all options (also those inside
  2706.         command  files!)  will  be  processed before any source files are
  2707.         scanned.
  2708.  
  2709.         The maximum command line length for DOS  is  127  characters,  so
  2710.         this  is  a  system dependent 'natural' limit for the options and
  2711.         filenames being declared.  If you have  more  items  to  declare,
  2712.         place them into command list files and file list files,  which do
  2713.         not have such limitations.
  2714.  
  2715.         Options can also be defined by the environment variables CFT  and
  2716.         CST like
  2717.  
  2718.              SET CFT=...
  2719.              SET CST=...
  2720.  
  2721.         To separate single options in the environment string,  spaces are
  2722.         required.  See also the description for the -D option for remarks
  2723.         on environment variable definitions.
  2724.  
  2725.         The rules for the interpretation of options is
  2726.  
  2727.         1.   if  defined,  all  options  in the environment variables CFT
  2728.              (for CFT) or CST (for CST) will be taken,
  2729.         2.   the command line  options  and  the  option  files  will  be
  2730.              interpreted in the order they appear.
  2731.  
  2732.         If  an  option is declared different more than once then previous
  2733.         declarations will be overwritten by the newer one.
  2734.  
  2735.         If  options  are  represented  by  a  single  character  with  no
  2736.         additional  optional  values possible like -r or -a,  they can be
  2737.         grouped together with a single leading '-' in front like '-rasM',
  2738.         which is the same as '-r -a -s -M'. The last option however,  can
  2739.         have   additions,   for  example  '-rasMmWinMain'  which  can  be
  2740.         evaluated to '-r -a -s -M -mWinMain'.  If an option can  have  an
  2741.  
  2742.  
  2743.  
  2744.  
  2745.                                      - 45 -
  2746.  
  2747.  
  2748.         additional  parameter,  the parameter must be specified without a
  2749.         space between the option character. Leaving this space means that
  2750.         no additional parameter is given for this option.
  2751.  
  2752.         Filenames  being  composed  of  drive  letter,   directory  name,
  2753.         filename and file extension,  in the following referred simply as
  2754.         'pathname',  are treated by some special procedures  to  force  a
  2755.         unique style of their internal representation:
  2756.  
  2757.         -    path  names  are  always  considered not case sensitive,  so
  2758.              there is no difference in upper case,  lower case and  mixed
  2759.              case  path  names  (the reason is that DOS does not make any
  2760.              difference),
  2761.         -    path names containing './', '.\', '../' and '..\' (so called
  2762.              'relative paths') are expanded and transformed into absolute
  2763.              paths,
  2764.         -    the recommended directory delimiter is '/' (UNIX-style),  if
  2765.              a  '\' (DOS-style) is recognised in a path name,  it will be
  2766.              replaced by '/',
  2767.         -    path names are always  expanded  and  transformed  into  the
  2768.              default style
  2769.  
  2770.                   <DRIVE LETTER>:<DIRECTORY PATH>/<FILENAME>
  2771.  
  2772.              to  get a unique representation for every filename that must
  2773.              be handled during processing,
  2774.         -    filenames have a DOS like maximum length of  12  characters:
  2775.              '<8 characters name>.<3 characters extension>', this is also
  2776.              true  for  the  Windows  NT  and  OS/2  versions  of the SXT
  2777.              programs.
  2778.  
  2779.         These  actions  are  done  with  every  path  name  during   file
  2780.         processing.   Filenames  given  on  the  command  line  are  also
  2781.         transformed.
  2782.  
  2783.         If you want  to  perform  database  generation  (option  -G)  for
  2784.         different  projects,  you  are  responsible  to separate them and
  2785.         avoid overwriting of existing databases.  This can be done either
  2786.         by  giving  the  databases  different  names so that the database
  2787.         files can be placed all in the same directory,  or every database
  2788.         must be written into its own directory. If you want to access the
  2789.         databases  be  sure  to  use  the correct name and/or path,  also
  2790.         within the BRIEF or MicroEMACS editors.
  2791.  
  2792.  
  2793.  
  2794.  
  2795.  
  2796.  
  2797.  
  2798.  
  2799.  
  2800.  
  2801.  
  2802.  
  2803.  
  2804.  
  2805.  
  2806.                                      - 46 -
  2807.  
  2808.  
  2809.         COMMAND LINE EXAMPLES
  2810.  
  2811.         1.   CFT -m -rau *.c
  2812.         This program invocation of  CFT  processes  all  files  with  the
  2813.         extension  ".c"  in the current directory and generates an output
  2814.         file starting with the "main"-function (option -m) for the output
  2815.         tree.  Every function will be displayed with file and line number
  2816.         reference and a cross reference number (option -r). All functions
  2817.         will be shown in lexicographical order (-a),  also undefined ones
  2818.         (-u).
  2819.  
  2820.         2.   CFT -mWinMain -rausMP -TMSC70,L -Id: -cs -Cs -na -ve:\  -C++
  2821.              *.c ..\*.c *.cpp
  2822.         This  invocation  is similar to the one described above with some
  2823.         extensions.  The source files from the current (*.c,  *.cpp)  and
  2824.         from  the  parent  (..\*.c) directory,  they will be preprocessed
  2825.         (-P) with MS-C 7.0 defines for large  memory  model  (-TMSC70,L),
  2826.         the include file path will be taken from the environment variable
  2827.         "INCLUDE"  (default for -P) and the path "d:" (-Id:) will also be
  2828.         searched for.  The precompiler output  is  stored  in  path  "e:"
  2829.         (-ve:\).  C++  extensions and keywords will be recognised if they
  2830.         occur (-C++).  The output will start with the  "WinMain"-function
  2831.         (-mWinMain).  There  will  be a sorted call statistic (-cs) and a
  2832.         function summary for every scanned  file  (-Cs)  with  additional
  2833.         information  for every function (-s).  The critical function call
  2834.         path for all functions will be calculated and displayed (-na) and
  2835.         the included files of every source file will be shown (-M).
  2836.  
  2837.         3.   CST -S"struct _test" -r *.h -W2 -C++
  2838.         Start CST to  scan  all  files  in  the  current  directory  with
  2839.         extension  ".h"  for  data  types.  They  will  be displayed with
  2840.         filename and line number reference  and  cross  reference  number
  2841.         (-r).  The output should be done for the data type 'struct _test'
  2842.         (-S"struct _test"). The warning level is set to "2" (-W2).
  2843.  
  2844.         4.   CFT y.c -R -Dmain=main_entry z.c -P x.c
  2845.         Start CFT to produce a reverse calling tree (-R) of the functions
  2846.         found in  the  files  "x.c",  "y.c"  and  "z.c"  in  the  current
  2847.         directory.  The files will be preprocessed (-P) before file scan,
  2848.         the  name  "main"  will  be  replaced  by   "main_entry"   during
  2849.         preprocessing (-Dmain=main_entry).
  2850.  
  2851.         5.   CST $cst1.cmd $cst2.cmd -ve:\tmp @cstfiles +*.h -olist.v1a
  2852.         This  invocation  of  CST  receives  its options from the command
  2853.         files "cst1.cmd"  and  "cst2.cmd"  and  stores  the  preprocessor
  2854.         output in path "e:\tmp" (-ve:\tmp). The files being processed are
  2855.         defined  in  the  source  list file "cstfiles" and on the command
  2856.         line by  "+*.h".  The  "+*.h"  file  specification  searches  the
  2857.         current  directory  and  all  subdirectories  for  files with the
  2858.         extension  ".h".   The  output  file  will  be  named  "list.v1a"
  2859.         (-olist.v1a).
  2860.  
  2861.  
  2862.  
  2863.  
  2864.  
  2865.  
  2866.  
  2867.                                      - 47 -
  2868.  
  2869.  
  2870.         6.   CFT -ra -PGNUINC -TGNU -M c:\gnu\src\*.c c:\gnu\src\*.s -d10
  2871.         CFT scans all files with extension ".c" and ".s" in the directory
  2872.         "c:\gnu\src". They will be preprocessed with an include file path
  2873.         defined  in environment variable "GNUINC" (-PGNUINC) for compiler
  2874.         type "GNU" (-TGNU).  The output contains all functions (-a)  with
  2875.         complete  reference  information  (-r) and a list of all included
  2876.         files for every  source  file  (-M).  The  output  tree  will  be
  2877.         truncated if the nesting level is higher than 10 (-d10).
  2878.  
  2879.         7.   CST *.c
  2880.         CST  processes  all  files  with  extension  ".c"  in the current
  2881.         working directory.  There are no options specified,  so only  the
  2882.         options set by the environment variable 'CST',  if present,  will
  2883.         be used to customise the program execution.  As  an  example  the
  2884.         command  line  options  used  in  example  6.  can  be defined as
  2885.         environment variable CST by 'SET CST=-raMKPGNUINC -TGNU -d10'.
  2886.  
  2887.         8.   CFT -ra -PI960INC -TI960,KB *.c *.s
  2888.         CFT scans all files with extension ".c" and ".s" in  the  current
  2889.         directory.  They  will  be preprocessed with an include file path
  2890.         defined  in  environment  variable  "I960INC"   (-PI960INC)   for
  2891.         compiler type "I960",  'KB' architecture (-TI960,KB).  The output
  2892.         contains all functions (-a) with complete  reference  information
  2893.         (-r).
  2894.  
  2895.         9.   CFT -rR -M -gproj40 -Gproj41
  2896.         CFT reads the database named 'proj40' (-g) and produces as output
  2897.         the  reverse  function  call  tree  (-R)  with complete reference
  2898.         information (-r), the (include) file interdependencies (-M) and a
  2899.         new database named 'proj41'.
  2900.  
  2901.         10.  CST -g -Gnew -N
  2902.         CST reads the  default  database  (-g)  and  produces  as  output
  2903.         another  database  named  'new' (-Gnew).  No other output file is
  2904.         generated (-N).
  2905.  
  2906.         11.  CST -N -OTEST -O+ test.h
  2907.         CST reads the file "test.h", generates no output file (-N), but a
  2908.         byte offset calculation file for data type  'TEST'  (-OTEST)  and
  2909.         its enclosed type members (-O+).
  2910.  
  2911.  
  2912.  
  2913.  
  2914.  
  2915.  
  2916.  
  2917.  
  2918.  
  2919.  
  2920.  
  2921.  
  2922.  
  2923.  
  2924.  
  2925.  
  2926.  
  2927.  
  2928.                                      - 48 -
  2929.  
  2930.  
  2931.         8    OUTPUT DESCRIPTION AND INTERPRETATION
  2932.  
  2933.         This section gives an overview about the files being generated by
  2934.         CFT  and  CST  and  the interpretation of the results.  Different
  2935.         files are produced as output depending on the options  being  set
  2936.         by  the  user.  Usually,  if  -N is not set,  all information are
  2937.         written to the default output file CFT.LST or CST.LST or  to  the
  2938.         file specified by the -o option.  The internal structure of these
  2939.         files  and  their  meanings  are  described  below.  If  database
  2940.         generation is enabled with option -G, several files are produced.
  2941.         They  all  have a common database name to identify the files that
  2942.         are related with a project.  The file extension '.DBF' marks  the
  2943.         dBASE  compatible  database  files,  the  file with the extension
  2944.         '.CMD' contains the command line options and the  file  with  the
  2945.         extension  '.SRC'  contains all source files that were processed.
  2946.         For further information refer to the corresponding section in the
  2947.         syntax description.
  2948.  
  2949.  
  2950.         CFT OUTPUT
  2951.  
  2952.         The output file is divided into several  sections.  Some  of  the
  2953.         sections listed are generated by default (-), others are optional
  2954.         (o)  and  only  displayed  if  they are enabled by a command line
  2955.         option.  Also,  the default sections can be customised to produce
  2956.         the  desired  output.  The sections generated for CFT are (in the
  2957.         order they appear):
  2958.  
  2959.         -    file header
  2960.         -    function calltree/called-by hierarchy listing (-r,  -R,  -x,
  2961.              -a, -m, -f, -dn, -V, -l)
  2962.         -    function summary
  2963.         -    multiple  defined  functions  and  their  location  (only if
  2964.              detected)
  2965.         -    overloaded functions and their location (only if detected)
  2966.         o    undefined functions (-u)
  2967.         o    function call statistics (-c[s])
  2968.         o    function caller/member relations (-Z[s])
  2969.         o    function call cross reference table (-z)
  2970.         o    critical function call path (-n[a])
  2971.         o    source file - include file dependency (-M)
  2972.         o    function tables for source files (-C[s], -s, -q)
  2973.         -    file information summary (-p, -q)
  2974.  
  2975.         Each function is displayed like:
  2976.  
  2977.              int test()  (1) <DMPCA> <TEST.C, 100>
  2978.  
  2979.         with the following meanings
  2980.  
  2981.              - int          : function return type
  2982.              - test()       : function name
  2983.              - (1)          : function reference number
  2984.  
  2985.  
  2986.  
  2987.  
  2988.  
  2989.                                      - 49 -
  2990.  
  2991.  
  2992.              - <DMPCA>      : found as (one or more of)
  2993.                                  D = definition,
  2994.                                  M = macro,
  2995.                                  P = prototype,
  2996.                                  C = function call,
  2997.                                  A = assembler function
  2998.              - <TEST.C, 100>: filename, line number
  2999.  
  3000.         The line number is the line where the function  definition  block
  3001.         starts  with  its initial '{' and not the line where the function
  3002.         name resides.  I think that this is the best solution because  it
  3003.         is  the point where we go really inside the function block.  This
  3004.         convention is also used by source level debuggers which point  on
  3005.         the line with the opening brace on function entry.
  3006.  
  3007.  
  3008.         CST OUTPUT
  3009.  
  3010.         The  output  file  is divided into several sections.  Some of the
  3011.         sections listed are generated by default (-), others are optional
  3012.         (o) and only displayed if they are  enabled  by  a  command  line
  3013.         option.  Also,  the default sections can be customised to produce
  3014.         the desired output.  The sections generated for CST are  (in  the
  3015.         order they appear):
  3016.  
  3017.         -    file header
  3018.         -    data structure calltree/called-by hierarchy listing (-r, -R,
  3019.              -x, -a, -m, -f, -dn)
  3020.         -    data type summary
  3021.         -    multiple  defined  data  types  and  their location (only if
  3022.              detected)
  3023.         o    data type call statistics (-c[s])
  3024.         o    data type caller/member relations (-Z[s])
  3025.         o    data type call cross reference table (-z)
  3026.         o    maximum data type nesting (-n[a])
  3027.         o    source file - include file dependency (-M)
  3028.         o    data type tables for source files (-C[s], -s, -q)
  3029.         -    file information summary (-p, -q)
  3030.  
  3031.         Each data type is displayed like:
  3032.  
  3033.              struct _test  (1) <BSUCE> <TEST.C, 90> <TEST.C, 60>
  3034.  
  3035.         with the following meanings
  3036.  
  3037.              - struct _test : type specifier
  3038.              - (1)          : reference number
  3039.              - <BSUCE>      : data type (one/none of):
  3040.                                  B = basic type (void, char, int, ...),
  3041.                                  S = struct,
  3042.                                  U = union,
  3043.                                  C = class,
  3044.                                  E = enum
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.                                      - 50 -
  3051.  
  3052.  
  3053.              - <TEST.C, 90> : filename, line number of type definition
  3054.                               (only printed if necessary)
  3055.              - <TEST.C, 60> : filename, line number of basic type
  3056.                               definition
  3057.  
  3058.         The two locations for the data type can occur if the data type is
  3059.         first defined and later assigned via 'typedef'  or  by  '#define'
  3060.         (if -P is not set) to another data type name:
  3061.  
  3062.         test.c:   ...
  3063.         line 60:  struct xyz {...};
  3064.                   ...
  3065.         line 90:  typedef struct xyz struct _test;
  3066.                   ...
  3067.  
  3068.         Their  definition  is on different lines but both data type names
  3069.         refer to the same data structure.
  3070.  
  3071.         Like the convention used for functions,  the line number  is  the
  3072.         line  where  the  structure,  union,  enumeration  or  class type
  3073.         definition block starts with its initial '{'  and  not  the  line
  3074.         where the type name resides.
  3075.  
  3076.         For  an  example  session and more detailed information about the
  3077.         generated output of CFT and CST see the file EXAMPLE.DOC.
  3078.  
  3079.  
  3080.         OUTPUT INTERPRETATION
  3081.  
  3082.         Besides the hierarchical structure chart of the function and data
  3083.         type relationships,  the resulting output contains several useful
  3084.         information about the program which can be used for optimization,
  3085.         reuse  or  maintenance purposes.  Identifying the most frequently
  3086.         called functions is a good way to  find  candidates  for  further
  3087.         optimization. Low-level functions with many callers but no called
  3088.         subfunctions  are ideal for reuse.  Functions with no callers may
  3089.         be obsolete if the function  is  also  not  called  via  function
  3090.         pointers,  and  can  be  discarded therefore.  The chance to find
  3091.         errors in complex functions with many lines of source code,  many
  3092.         called  functions  and a lot of control statements is much bigger
  3093.         than in simple functions.
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.                                      - 51 -
  3112.  
  3113.  
  3114.         9    INTEGRATION INTO PROGRAM DEVELOPMENT ENVIRONMENTS
  3115.  
  3116.         Invoking CFT and CST directly from inside editors  or  integrated
  3117.         programming  environments (IDE) and displaying the results can be
  3118.         a very useful feature during program development.  With  advanced
  3119.         IDE's  like  that of Borland C++ or Microsoft PWB this is an easy
  3120.         task.
  3121.  
  3122.         The Borland IDE has in its system menu a section  with  'transfer
  3123.         items.  It  contains programs that can be invoked from inside the
  3124.         IDE like TASM or GREP. To add CFT and CST as new entries you have
  3125.         to go to the OPTIONS menu and open 'TRANSFERS...'.  Choose a free
  3126.         entry  in  the  table and select EDIT.  A window will open with 3
  3127.         edit lines.  In first line called 'Program Title' you must  write
  3128.         'C~FT'  resp.  'C~ST' as the name being displayed in the transfer
  3129.         section. The '~' prepends the hot-keys 'F' and 'S'. In the second
  3130.         line  called  'Program  Path'  you  must  write  'CFTIDE'   resp.
  3131.         'CSTIDE',  maybe with the complete path,  if necessary.  'CFTIDE'
  3132.         and 'CSTIDE' are batch files which perform the invocation of  CFT
  3133.         resp.  CST together with the necessary options. These batch files
  3134.         are part of the CXT package,  you can change the options  defined
  3135.         there  if you need other ones.  In the third line called 'Command
  3136.         Line' you must write the macro  commands  '$EDNAME  $NOSWAP  $CAP
  3137.         EDIT'.  These  macros  transfer  the filename in the current edit
  3138.         window ($EDNAME) to the  batch  file,  suppress  window  swapping
  3139.         ($NOSWAP)  and  capture  the  processing  results  in an own edit
  3140.         window ($CAP EDIT). The last step is to save these entries,  then
  3141.         the  integration  is  completed and CFT and CST can be used as if
  3142.         they were built-in functions. The processing results are shown in
  3143.         an edit window which can be scrolled, resized or moved. By adding
  3144.         CFT and CST to the IDE it is much easier for  the  programmer  to
  3145.         use these tools.
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.                                      - 52 -
  3173.  
  3174.  
  3175.         10   TOOLS FOR DATABASE PROCESSING
  3176.  
  3177.         To  access  information  stored  in  a  database,  the  following
  3178.         utilities are available for the SXT programs:
  3179.  
  3180.              CFTN      C Function Tree Navigator
  3181.              CSTN      C Structure Tree Navigator
  3182.              DFTN      DBASE Function Tree Navigator
  3183.              FFTN      FORTRAN Function Tree Navigator
  3184.              LFTN      LISP Function Tree Navigator
  3185.  
  3186.         They can be used to recall the filename  and  line  number  of  a
  3187.         specific  item (function or data type) from the database.  If the
  3188.         requested item is found in the database,  it  will  be  displayed
  3189.         with  its  location  where it is defined or where it is found for
  3190.         the  first  time  if  there  was  no  definition   found   during
  3191.         processing.
  3192.  
  3193.         As an additional feature editors like BRIEF 3.0, QEDIT 2.1/3.0 or
  3194.         MicroEMACS  3.11  can be invoked directly with the information to
  3195.         open the target file and to move the cursor to the line where the
  3196.         searched item is located.  For BRIEF  there  are  several  macros
  3197.         available  to  perform  searching  inside the editor.  A new edit
  3198.         window with the file at the location of the requested  item  will
  3199.         be  opened  if  the  search was successful.  Also both MicroEMACS
  3200.         editor versions for DOS and WINDOWS are supported.  Some of these
  3201.         actions are also possible for QEDIT,  with slight limitations due
  3202.         to the macro programming capabilities.
  3203.  
  3204.         Other user programmable editors which should be able to work with
  3205.         CFTN  and  CSTN  are  e.g.   CRISP  and  Codewright  (both  BRIEF
  3206.         compatible), EPSILON, ME, KEDIT, Multi-Edit, JED, GNU-EMACS ports
  3207.         like  DEMACS  or  OEMACS,  the  Microsoft  editor M or integrated
  3208.         development environments like Borland IDE or Microsoft PWB  (this
  3209.         list may not be complete). You can try to integrate CFTN and CSTN
  3210.         into these systems by using the BRIEF,  QEDIT or MicroEMACS macro
  3211.         files as examples for your own integration development.
  3212.  
  3213.         The version numbers for the  editors  mentioned  in  this  manual
  3214.         indicate those versions for which the described capabilities have
  3215.         been tested.
  3216.  
  3217.         PRECOMPILED SOURCE FILES
  3218.  
  3219.         Sometimes,  if  the  precompile option -P was used to process the
  3220.         C/C++ source files related with  the  database,  the  results  of
  3221.         searches  seem  to be wrong.  This can happen if an identifier in
  3222.         the source code is in fact  defined  as  a  macro  and  has  been
  3223.         exchanged  during  preprocessing  so  that  the  resulting source
  3224.         processed by the analyser is different from the  original  source
  3225.         and  the cursor will point to an obviously  wrong location or the
  3226.         search will fail.  An identifier which is in fact a macro name is
  3227.         unknown  and  not  accessible  after  precompiling.  It  is  also
  3228.         possible that a function being used in the original source  could
  3229.         not be found in the database.  The reason is that the function is
  3230.         in  fact  a  'function  like'  macro  and  was  replaced   during
  3231.  
  3232.  
  3233.                                      - 53 -
  3234.  
  3235.  
  3236.         preprocessing.  If  different  named macros are defined equal,  a
  3237.         search for an  item  may  point  to  another  location  than  the
  3238.         requested.  If  the -P option is not set,  the same item can have
  3239.         several 'alias'- names due to macro defining.  If the source code
  3240.         contains  explicit  #line numbers,  searching for a specific line
  3241.         may also fail.  Keep these  exceptions  in  mind  for  a  correct
  3242.         interpretation the results when using the database.
  3243.  
  3244.         IMPORTANT NOTICE
  3245.  
  3246.         Recalling information from the database may not be valid if files
  3247.         being  processed  were  edited  and  changed  after  the database
  3248.         generation has been performed. Errors can result like pointing to
  3249.         wrong files and/or lines if source lines  have  been  deleted  or
  3250.         inserted,  failed  searches  if  names  have  changed  or  failed
  3251.         accesses to files which may have been renamed,  moved or deleted.
  3252.         To avoid these errors,  a consistency check for the file creation
  3253.         date/time and file size will be performed by the recall programs.
  3254.         If inconsistencies are recognised, the user will be informed that
  3255.         the  database  is  not  up-to-date  and  should  be  updated   by
  3256.         processing the source files again.
  3257.  
  3258.  
  3259.         IMPORTANT  NOTICE TO DEVELOPERS USING THE DATABASE FROM THEIR OWN
  3260.         PROGRAMS
  3261.  
  3262.         There is absolutely  no  guarantee  that  the  internal  database
  3263.         structure will remain unchanged.  The internal database structure
  3264.         may change without notice.
  3265.  
  3266.  
  3267.         COMMAND LINE SYNTAX DESCRIPTION
  3268.  
  3269.         SYNTAX:   CFTN [options] pattern
  3270.                   CSTN [options] pattern
  3271.                   DFTN [options] pattern
  3272.                   FFTN [options] pattern
  3273.                   LFTN [options] pattern
  3274.  
  3275.         OPTIONS
  3276.  
  3277.         -Eeditor
  3278.         Specifies the editor command line for option -e,  overwrites  the
  3279.         default  and  the  environment  values.  See  the  section  about
  3280.         environment variables for further information about the  required
  3281.         format.
  3282.  
  3283.         -F
  3284.         Print  all  filenames  which are related with the database.  This
  3285.         option is useful to get a complete overview about  all  files  of
  3286.         the project.
  3287.  
  3288.         -a
  3289.         Print all function/data type names.  Useful to generate a list of
  3290.         items, for example as input to other programs.
  3291.  
  3292.  
  3293.  
  3294.                                      - 54 -
  3295.  
  3296.  
  3297.         -B
  3298.         Same as -a,  but prints additionally the internal database record
  3299.         number. Used by BRIEF macros.
  3300.  
  3301.         -bform
  3302.         Run search in batch-mode,  this means that, if the requested item
  3303.         was found,  the location will be displayed on a  single  line  as
  3304.         "file name line number" (DEFAULT STYLE),  otherwise there will be
  3305.         no output that the search failed. The output style can be changed
  3306.         by specifying 'form' to overwrite the  default  style.  Like  for
  3307.         option  -E you can specify the exact locations where the filename
  3308.         and line number should be inserted by defining  a  format  string
  3309.         with   %s   and  %d  (See  also  the  section  about  environment
  3310.         variables).  For example,  the format to generate a command  line
  3311.         for invoking BRIEF, QEDIT or MicroEMACS would look like
  3312.  
  3313.              cstn -b"b -m\"goto_line %d\" %s" ...         (BRIEF)
  3314.              cstn -b"q %s -n%d" ...                       (QEDIT)
  3315.              cstn -b"me -G%d %s"                          (MicroEMACS)
  3316.  
  3317.         This option gives you a great flexibility in generating an output
  3318.         for  your own purposes,  for example to write a batch file or for
  3319.         further use in other programs.
  3320.  
  3321.         -e
  3322.         If the requested item is found,  an editor  will  be  invoked  to
  3323.         display  the file containing the requested item.  There are three
  3324.         different ways to specify the editor command line  (evaluated  in
  3325.         that order):
  3326.  
  3327.         1)   use option -E,
  3328.         2)   define  the  environment  variables  CFTNEDIT,  CSTNEDIT  or
  3329.              CXTNEDIT,
  3330.         3)   if nothing is specified,  BRIEF as the  default  editor  (if
  3331.              present)  will  be invoked with the filename and line number
  3332.              of the item to move the cursor to its location.  Ensure that
  3333.              the  PATH  environment variable is set correctly,  including
  3334.              the path for the BRIEF directory.
  3335.  
  3336.         -fname
  3337.         Use 'name' as base name (path and filename) for  database  files.
  3338.         It  is  also  possible  to  use  environment variables (CFTNBASE,
  3339.         CSTNBASE, CXTNBASE) for the definition of the database names.  If
  3340.         -f and environment variables are not set,  a DEFAULT NAME will be
  3341.         used (see also option -G from CFT and  CST  syntax  description).
  3342.         This  allows  the  use  of  different  databases,   for  example,
  3343.         generated for different projects.  See  also  the  section  about
  3344.         environment variables for further information.
  3345.  
  3346.         -r#
  3347.         This option prints the location for a selected item with matching
  3348.         pattern  and  record number #.  This option requires -b.  Used by
  3349.         BRIEF macros.
  3350.  
  3351.  
  3352.  
  3353.  
  3354.  
  3355.                                      - 55 -
  3356.  
  3357.  
  3358.         -Ritem
  3359.         Print a cross reference list of every occurrence of  'item'  with
  3360.         complete filename and line number.
  3361.  
  3362.         -Dfile
  3363.         Print a list with the contents of 'file'.
  3364.  
  3365.         -o[name]
  3366.         Print output to file 'name'.  If 'name' is not specified, DEFAULT
  3367.         NAMES are used: CFTN.OUT resp. CSTN.OUT.
  3368.  
  3369.         pattern
  3370.         The item to search for in the database.  This  can  either  be  a
  3371.         function name (CFTN) or a data type name (CSTN).  There are three
  3372.         different ways of searching depending how 'pattern' is given:
  3373.  
  3374.         pattern        exact search,
  3375.         pattern*       the beginning of the item must match with pattern
  3376.         *pattern       a substring must match with pattern
  3377.  
  3378.         If the item  to  search  for  consists  of  more  than  one  word
  3379.         (contains  spaces),  the  search  pattern  must  be 'quoted' like
  3380.         "struct _iobuf" to ensure that these  words  are  interpreted  as
  3381.         single pattern.
  3382.  
  3383.  
  3384.         RETURN VALUES
  3385.  
  3386.         The  following  values are returned to DOS or the calling program
  3387.         to report the result of the database search:
  3388.  
  3389.         -    100  searched item not found,
  3390.         -    101  searched item found,
  3391.         -    102  searched item found,  but the source file may have been
  3392.                   changed  (creation date and/or file size are not equal)
  3393.                   since the creation of the  database  (database  is  not
  3394.                   up-to-date).
  3395.  
  3396.         The  returned  value  can be used to decide what action should be
  3397.         done for different results,  for example,  if the database is not
  3398.         up-to-date.
  3399.  
  3400.  
  3401.         ENVIRONMENT VARIABLES
  3402.  
  3403.         CFTNEDIT, CSTNEDIT, CXTNEDIT:
  3404.         The  editor  to  invoke  can be defined either by option -e or by
  3405.         defining the environment variables CFTNEDIT (for CFTN),  CSTNEDIT
  3406.         (for  CSTN) or the commonly used variable CXTNEDIT (for both CFTN
  3407.         and CSTN) with the format string of the editor  of  your  choice.
  3408.         The  format  string  can  be  used to specify the place where the
  3409.         filename  and  the  line  number  should  be  inserted  to   give
  3410.         additional information to the editor. Use %s for the filename and
  3411.         %d  for  the  line  number.  For  example,  the invocation of the
  3412.         default editor BRIEF could be defined like
  3413.  
  3414.  
  3415.  
  3416.                                      - 56 -
  3417.  
  3418.  
  3419.              SET CFTNEDIT=b -m"goto_line %d" %s
  3420.              SET CSTNEDIT=b -m"goto_line %d" %s
  3421.              SET CXTNEDIT=b -m"goto_line %d" %s
  3422.  
  3423.         where 'b' is the BRIEF editor,  '-m' specifies  the  macro  being
  3424.         invoked  when BRIEF starts,  the macro name 'goto_line' with '%d'
  3425.         as the place to insert the line number and '%s' as the place  for
  3426.         the  filename.  Note  that  this  example  cannot  be used on the
  3427.         command line with -E option because of the quotes. It is possible
  3428.         to change the order of %d and %s if another editor is used.
  3429.  
  3430.         Here are additional  configuration  examples  for  other  popular
  3431.         editors (examples are given for CFTN, similar for CSTN):
  3432.  
  3433.         EDIT (MS-DOS 5.0):  SET CFTNEDIT=edit %s  or  -E"edit %s"   or
  3434.                             SET CFTNEDIT=edit     or  -Eedit
  3435.  
  3436.         VDE 1.62:           SET CFTNEDIT=vde %s   or  -E"vde %s"    or
  3437.                             SET CFTNEDIT=vde      or  -Evde
  3438.  
  3439.         QEDIT 2.1/3.0:      SET CFTNEDIT=q %s -n%d   or   -E"q %s -n%d"
  3440.  
  3441.         MicroEMACS 3.11:    SET CFTNEDIT=me -G%d %s  or   -E"me -G%d %s"
  3442.  
  3443.         The described notation allows the user to customise CFTN and CSTN
  3444.         with  his  preferred  editor  and  to  perform additional actions
  3445.         during invocation. If your editor supports macro programming like
  3446.         BRIEF you are free to write your own macros to do similar  things
  3447.         like  the CXT.CM macro given for BRIEF 3.0 does.  I think this is
  3448.         the most flexible way to give users control about this option and
  3449.         to help them working with their preferred programming environment
  3450.         and development tools.
  3451.  
  3452.         CFTNBASE, CSTNBASE, CXTNBASE:
  3453.         These environment variables can be used to specify  the  name  of
  3454.         the  database.  Similar  to  the  editor  environment  variables,
  3455.         CFTNBASE and CSTNBASE are related to CFTN and CSTN  and  CXTNBASE
  3456.         is  used for both.  For example,  to specify the database 'proj1'
  3457.         located in directory 'd:\develop\projects' type
  3458.  
  3459.              SET CFTNBASE=d:\develop\projects\proj1
  3460.              SET CSTNBASE=d:\develop\projects\proj1
  3461.  
  3462.         for a separate definition or
  3463.  
  3464.              SET CXTNBASE=d:\develop\projects\proj1
  3465.  
  3466.         for a common definition of the database name.
  3467.  
  3468.  
  3469.         COMMAND LINE EXAMPLES
  3470.  
  3471.  
  3472.  
  3473.  
  3474.  
  3475.  
  3476.  
  3477.                                      - 57 -
  3478.  
  3479.  
  3480.         1)   CFTN *
  3481.         Displays all functions in lexicographical order with their return
  3482.         types,  filenames and line numbers.  Gives a short overview about
  3483.         all functions being found.
  3484.  
  3485.         2)   CSTN -e *
  3486.         Edit  all data types in lexicographical order,  use default or by
  3487.         environment variable CSTNEDIT or CXTNEDIT defined editor.
  3488.  
  3489.         3)   CFTN -fproject1 -Evde -e main
  3490.         Search database named 'project1' for  function  'main'  and  edit
  3491.         with editor 'vde'.
  3492.  
  3493.         4)   CSTN -b "union REGS"
  3494.         Search  for  data  type 'union REGS' and display,  if found,  the
  3495.         filename and line number
  3496.  
  3497.         5)   CSTN -e -E"q %s -n%d" -fcft tmbuf
  3498.         Search database 'cft' for data type 'tmbuf' and invoke, if found,
  3499.         the editor 'q' (QEDIT 2.1/3.0) with the filename and line number
  3500.  
  3501.  
  3502.         SEARCHING INSIDE BRIEF (Version 3.0)
  3503.  
  3504.         This feature is one of the most  powerful  enhancements  for  the
  3505.         BRIEF  editor  and offers the user full control over the complete
  3506.         source code of software projects no matter how big they  are  and
  3507.         how  many  files  they include.  It extends the BRIEF editor to a
  3508.         comfortable hypertext source code browser and locator system. The
  3509.         browser allows its  user  to  find  and  read  various  important
  3510.         program constructs like functions and data types in several files
  3511.         simultaneously and moving between them. The complete project with
  3512.         several  source  and  include  files  appears  as  if  it  were a
  3513.         'whole-part'. The browser helps the programmer to learn about the
  3514.         existing program structures and supports him  in  developing  new
  3515.         and  maintaining  existing  code.  The  programmer  can  use  the
  3516.         generated output files CFT.LST or CST.LST (or the one he  created
  3517.         with the -o option) to walk along the hierarchy tree chart and to
  3518.         select  from  there  the  function  or  data  type that should be
  3519.         displayed in detail.
  3520.  
  3521.         The following features are implemented as macros:
  3522.  
  3523.         -    searching for a specific item, tagged or marked
  3524.         -    building menus of all defined items
  3525.         -    building menus of all references to a specific item
  3526.         -    building menus of all processed files
  3527.         -    building menus of all items defined in the current file
  3528.         -    searching for a specific item cross reference number
  3529.         -    changing the database name
  3530.  
  3531.         Every function  and  data  type  can  be  accessed  with  just  a
  3532.         keystroke  by moving the cursor on it ("tagging") and executing a
  3533.         macro to locate the item and zoom  into  the  file  where  it  is
  3534.         defined.  The  user does no longer have to remember the filenames
  3535.  
  3536.  
  3537.  
  3538.                                      - 58 -
  3539.  
  3540.  
  3541.         and locations where the functions and data types are defined  nor
  3542.         does  he  have  to  change  the files,  directories and drives to
  3543.         access the files manually.
  3544.  
  3545.         It is  possible  to  build  interactive  dialog  menus  with  all
  3546.         functions or data types in lexicographical order and to select an
  3547.         item  to  display.  This  is  very useful to get a quick overview
  3548.         about all accessible  functions  and  data  types  of  the  whole
  3549.         project.  It is also possible to build an interactive dialog menu
  3550.         with all filenames in lexicographical order which are  stored  in
  3551.         the database and to select one file to open for edit. Other menus
  3552.         are  available for file contents lists and item cross references.
  3553.         All information to  perform  these  actions  are  stored  in  the
  3554.         databases  generated  by  processing  the  files related with the
  3555.         project.
  3556.  
  3557.         To invoke CFTN and CSTN inside BRIEF,  the macro file CXT.CM must
  3558.         be loaded (with <F9> CXT.CM),  which makes the implemented macros
  3559.         available. These macros are
  3560.  
  3561.              MACRO NAME          KEY ASSIGNMENT (defined in CXTKEYS.CM)
  3562.  
  3563.              cft                 Shift F1
  3564.              cftmenu             Shift F2
  3565.              cftxrefmenu         Shift F3
  3566.              cftxrefmenuagain    Shift F4
  3567.              cftdefmenu          Shift F7
  3568.              cftfilemenu         Shift F8
  3569.              cftfind             Shift F11
  3570.              cftbase             Shift F12
  3571.  
  3572.              cst                 Ctrl F1
  3573.              cstmenu             Ctrl F2
  3574.              cstxrefmenu         Ctrl F3
  3575.              cstxrefmenuagain    Ctrl F4
  3576.              cstdefmenu          Ctrl F7
  3577.              cstfilemenu         Ctrl F8
  3578.              cstfind             Ctrl F11
  3579.              cstbase             Ctrl F12
  3580.  
  3581.              cxtbase             Alt Tab
  3582.              cxtsearchxref       Ctrl Tab
  3583.              cxthelp             <unassigned>
  3584.  
  3585.         This macro key assignment list is also available within BRIEF  as
  3586.         a  help  screen which can be invoked by the macro 'cxthelp'.  The
  3587.         CXT help information is not part of the BRIEF help system because
  3588.         this would need modifications of the original BRIEF help files.
  3589.  
  3590.         Instead of loading the file CXT.CM and  typing  the  macro  names
  3591.         manually,  you  can load the macro file CXTKEYS.CM which performs
  3592.         automatic loading of the CXT.CM file if any of the  above  listed
  3593.         macros  is invoked with a hot-key.  To simplify working with this
  3594.         package,  the CXTKEYS.CM macro file also contains key assignments
  3595.         for  the  macros.  These  hot-keys  offer  a  "point  and  shoot"
  3596.         hypertext like feeling. The macro source file CXTKEYS.CB contains
  3597.  
  3598.  
  3599.                                      - 59 -
  3600.  
  3601.  
  3602.         the source code for CXTKEYS.CM so  that  you  are  able  to  make
  3603.         changes  like  the  key assignments for your personal needs or to
  3604.         move the initialization function to the BRIEF start-up macro file
  3605.         (For  further  information  about  BRIEF  macros  see  the  BRIEF
  3606.         manuals).  To  load  these  macros  and to execute CFTN and CSTN,
  3607.         which are invoked from inside BRIEF, be sure to set the directory
  3608.         path correctly. It is also necessary to allow access to the macro
  3609.         file DIALOG.CM which  contains  the  functions  for  dialog  menu
  3610.         building and processing.
  3611.  
  3612.         A  search  can be started by simply moving the cursor on the item
  3613.         to search for or by marking a block with the item  (necessary  if
  3614.         search pattern contains more than one word like 'struct xyz') and
  3615.         then running one of the following macros (or press hot-keys):
  3616.  
  3617.              <F10> cft                     (function search)
  3618.              <F10> cst                     (data type search)
  3619.  
  3620.         It  is  also  possible to type the name of the item to search for
  3621.         manually. To do this you must run one of the following macros:
  3622.  
  3623.              <F10> cftfind <item>          (function search)
  3624.              <F10> cstfind <item>          (data type search)
  3625.  
  3626.         If the  search  was  successful,  a  new  window  with  the  file
  3627.         containing  the item will be opened and the cursor will be placed
  3628.         at the line where the item is located.  If  inconsistencies  have
  3629.         been detected,  the user will be informed.  If the requested item
  3630.         or the source file containing the item is not  found,  a  message
  3631.         will be given. The macros for building the function and data type
  3632.         dialog menu are
  3633.  
  3634.              <F10> cftmenu                 (function menu)
  3635.              <F10> cstmenu                 (data type menu)
  3636.  
  3637.         You  can  scroll  through  the  entries  and select an item which
  3638.         should be displayed.  To access databases other than the  default
  3639.         ones, there are two ways to change the base names:
  3640.  
  3641.         1)   Set the environment variables CFTNBASE, CSTNBASE or CXTNBASE
  3642.              (see  description  above).  By loading the macro file CXT.CM
  3643.              these variables will be used for initialization.
  3644.  
  3645.         2)   To change the base names from inside BRIEF,  there are three
  3646.              macros  to do this.  They overwrite the initial values given
  3647.              by the environment variables:
  3648.  
  3649.              <F10> cftbase     change base name for function search
  3650.              <F10> cstbase     change base name for data type search
  3651.              <F10> cxtbase     change both CFT and CST base name
  3652.  
  3653.         With these features it is possible to set default values for  the
  3654.         database  files  or to change between different databases without
  3655.         leaving BRIEF which gives the user a maximum of flexibility.  You
  3656.         can  display  a menu list with all source files being scanned for
  3657.         the database by typing
  3658.  
  3659.  
  3660.                                      - 60 -
  3661.  
  3662.  
  3663.  
  3664.              <F10> cftfilemenu             (CFT file menu)
  3665.              <F10> cstfilemenu             (CST file menu)
  3666.  
  3667.         With this feature you can get a quick overview  about  all  files
  3668.         related with the database.  Other menu driven options concern the
  3669.         displaying of all cross references to a specific item (see  macro
  3670.         'cst' for information about marking) with the macros
  3671.  
  3672.              <F10> cftxrefmenu             (CFT cross reference menu)
  3673.              <F10> cftxrefmenuagain        (show previous menu again)
  3674.              <F10> cstxrefmenu             (CST cross reference menu)
  3675.              <F10> cstxrefmenuagain        (show previous menu again)
  3676.  
  3677.         and  the displaying of a file contents list for the actual source
  3678.         file with the macros
  3679.  
  3680.              <F10> cftdefmenu              (CFT file menu)
  3681.              <F10> cstdefmenu              (CST file menu)
  3682.  
  3683.         To search for the first appearance of a specific cross  reference
  3684.         number like '(123)' in a CFT or CST output listing file, move the
  3685.         cursor to the reference number and type
  3686.  
  3687.              <F10> cxtsearchxref           (search cross reference)
  3688.  
  3689.         The macro extracts the complete number and searches for its first
  3690.         occurrence  by  starting  from  the beginning of the output file.
  3691.         With this macro you can move quickly from any  reference  to  its
  3692.         initial description.
  3693.  
  3694.         All  the above described macro functions are defined in the BRIEF
  3695.         macro file CXT.CB. These macros make extensive use of the several
  3696.         options of CFTN  resp.  CSTN,  which  are  described  earlier  in
  3697.         detail.
  3698.  
  3699.  
  3700.         SEARCHING INSIDE QEDIT (2.1 and 3.0)
  3701.  
  3702.         The  popular  shareware  editor  QEDIT with its macro programming
  3703.         capabilities allows,  like the BRIEF  editor,  the  searching  of
  3704.         functions  and  data types from inside the editor.  The following
  3705.         examples for QEDIT macros act, with slight limitations,  like the
  3706.         BRIEF macros 'cft' and 'cst':
  3707.  
  3708.         CFT function searching, assigned to <SHIFT F9>:
  3709.  
  3710.         #f9  MacroBegin  MarkWord Copy Dos 'cftn -b ' Paste '>tmp' Return
  3711.              Return  EditFile  'tmp'  Return  AltWordSet  MarkWord   Copy
  3712.              DefaultWordSet  EditFile  Paste Return EditFile 'tmp' Return
  3713.              EndLine CursorLeft  MarkWord  Copy  Quit  NextFile  GotoLine
  3714.              Paste Return
  3715.  
  3716.  
  3717.  
  3718.  
  3719.  
  3720.  
  3721.                                      - 61 -
  3722.  
  3723.  
  3724.         CST data type searching, assigned to <SHIFT F10>:
  3725.  
  3726.         #f10 MacroBegin  MarkWord Copy Dos 'cstn -b ' Paste '>tmp' Return
  3727.              Return  EditFile  'tmp'  Return  AltWordSet  MarkWord   Copy
  3728.              DefaultWordSet  EditFile  Paste Return EditFile 'tmp' Return
  3729.              EndLine CursorLeft  MarkWord  Copy  Quit  NextFile  GotoLine
  3730.              Paste Return
  3731.  
  3732.         These   QEDIT   macro   definitions   can   be  placed  into  the
  3733.         'qconfig.dat' configuration file and added to  'q.exe'  with  the
  3734.         'qconfig.exe' configuration utility (For additional details about
  3735.         QEDIT  macro  programming  see the QEDIT documentation).  The two
  3736.         macros perform the following  actions:  mark  the  current  word,
  3737.         execute  the CFTN or CSTN database search for the marked word via
  3738.         dos and redirect the output to file 'tmp',  read target  filename
  3739.         from 'tmp' and open target file,  read line number from 'tmp' and
  3740.         go to the selected line.
  3741.  
  3742.         These macros are working almost similar to those used from BRIEF,
  3743.         but they have some limitations in their functionality due to  the
  3744.         limited capabilities of the QEDIT macro programming language:
  3745.  
  3746.         -    there is no error check for a correct cursor location,
  3747.         -    the  searched  item must always be a single word like 'main'
  3748.              or 'size_t',  a combined pattern like 'struct iobuf'  cannot
  3749.              be searched,
  3750.         -    there  is  no  error  check  if the search was successful or
  3751.              failed or the database is not up-to-date,
  3752.         -    if the target file is the same as that from which the search
  3753.              started and other additional files are also open (QEDIT ring
  3754.              buffer), probably a wrong file will be accessed,
  3755.         -    the name of the database cannot be changed, the searches are
  3756.              performed either with the default database or those  defined
  3757.              by the environment variables.
  3758.  
  3759.  
  3760.         SEARCHING INSIDE MicroEMACS (Version 3.11, DOS & WINDOWS)
  3761.  
  3762.         The latest editor which is now supported with macros for database
  3763.         access is MicroEMACS 3.11. The macro file is named CXT_ME.CMD and
  3764.         should  be  place  in  the MircoEMACS directory.  This macro file
  3765.         works with the DOS and the WINDOWS version of MicroEMACS 3.11.
  3766.  
  3767.         The following macros are available:
  3768.  
  3769.         -    cft       function search for tagged item
  3770.         -    cst       data type search for tagged item
  3771.         -    cftmark   function search for marked item
  3772.         -    cstmark   data type search for marked item
  3773.         -    cftfind   function search for user defined item
  3774.         -    cstfind   data type search for user defined item
  3775.         -    cftfile   list of all CFT files
  3776.         -    cstfile   list of all CST files
  3777.         -    cftbase   set CFT database name
  3778.         -    cstbase   set CST database name
  3779.         -    cxtbase   set both CFT and CST database name
  3780.  
  3781.  
  3782.                                      - 62 -
  3783.  
  3784.  
  3785.  
  3786.         They can be invoked by loading the macro file CXT_ME.CMD with
  3787.  
  3788.              ESC CTRL+S CXT_ME.CMD
  3789.  
  3790.         and running the macro with
  3791.  
  3792.              ESC CTRL+E <macro name>
  3793.  
  3794.         If the macros are used with the MicroEMACS WINDOWS  version,  you
  3795.         may  have  to  change the DOSEXEC.PIF file,  which is part of the
  3796.         MicroEMACS  3.11  distribution  package.  During  the  CXT  macro
  3797.         execution,  the  shell command may stop after execution and waits
  3798.         for  the  <return>  key  pressed  to  continue.   To  avoid  this
  3799.         interruption,  you  can  enable  it  by  editing the PIF file and
  3800.         select "Close window after execution".  The environment variables
  3801.         CFTNBASE,  CSTNBASE  and  CXTNBASE are used in the same way as in
  3802.         the BRIEF version.  Key-assignments to macro procedure names  are
  3803.         not  performed,  if you prefer hot-keys,  you are free to do this
  3804.         for yourself.
  3805.  
  3806.         In the MicroEMACS WINDOWS version,  however,  the user accessible
  3807.         macros  can be integrated into the "Miscellaneous" pull-down menu
  3808.         (thanks to  the  incredible  macro  programming  capabilities  of
  3809.         MicroEMACS!).   To  view  the  generated  output  file  with  its
  3810.         semigraphic frames,  change the font type and select for  example
  3811.         the  'TERMINAL'  font  from  the  OEM  font  list  which supports
  3812.         semigraphic characters.
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.  
  3836.  
  3837.  
  3838.  
  3839.  
  3840.  
  3841.  
  3842.  
  3843.                                      - 63 -
  3844.  
  3845.  
  3846.         11   IMPROVING EXECUTION SPEED
  3847.  
  3848.         CFT and CST are disk storage based programs  because  the  source
  3849.         and  include  files,  the  intermediate  precompiler file and the
  3850.         output file must be read from and  written  to  hard  disk.  This
  3851.         means that the execution speed of CFT and CST depends at first on
  3852.         the  speed  of  the physical storage medium and not (only) on the
  3853.         speed of the CPU.  There are several ways to improve the  program
  3854.         performance:
  3855.  
  3856.         -    install a RAM-disk and
  3857.              a)   start  CFT  and CST from there so that the intermediate
  3858.                   file and the resulting output file will be stored there
  3859.                   (but don't forget to copy the output file to  the  hard
  3860.                   disk before power-off), or
  3861.              b)   use  the  -v  option  to  redirect only the precompiler
  3862.                   output file (scanner input file) to the  RAM-disk  from
  3863.                   anywhere  the  program is started (the RAM-disk must be
  3864.                   large enough to hold  the  largest  possible  temporary
  3865.                   file, otherwise a disk-write error will occur),
  3866.         -    use a hard disk cache program like SmartDrive,  HyperDisk or
  3867.              PC-Cache,
  3868.         -    use a faster hard disk,
  3869.         -    and finally, of course, use a faster and more powerful CPU.
  3870.  
  3871.         The most effective combination is option -v with  a  RAM-disk  as
  3872.         destination  path and hard disk caching together with a fast hard
  3873.         disk drive. If the disk cache is large enough to hold most of the
  3874.         frequently called include files, the execution speed is about 2.5
  3875.         to 3 times faster than without.  This is a  significant  speed-up
  3876.         especially  for  projects  with  a large number of files and many
  3877.         included files in each source file.
  3878.  
  3879.         During program execution with preprocessing (option -P),  most of
  3880.         the time will be consumed to preprocess the given input files and
  3881.         the related include files and to generate the preprocessor output
  3882.         file.  The scanning for functions (CFT) or data types (CST) takes
  3883.         only a small amount of time. The function/data type relations are
  3884.         computed while the output is generated and written to disk, there
  3885.         is no precomputing necessary.
  3886.  
  3887.         The function  for  critical  call  path/nesting  level  detection
  3888.         depends  only on the number of functions or structures and not on
  3889.         the call/declaration nesting complexity. The execution time grows
  3890.         linear with the number of items (functions/structures) to process
  3891.         and is very fast!
  3892.  
  3893.         Be aware of the fact that the processing of  a  large  number  of
  3894.         files  can  take  quite  a  long time (from several minutes up to
  3895.         hours on lower performance machines!),  especially if  option  -P
  3896.         for preprocessing is enabled.
  3897.  
  3898.         The  generation  of  the output file and writing to disk can also
  3899.         take some time if the number of items to display is large and the
  3900.         nesting structure is complex or if there is  no  cross  reference
  3901.         option  enabled  (see -x and -r for further information).  If the
  3902.  
  3903.  
  3904.                                      - 64 -
  3905.  
  3906.  
  3907.         number of items and source files is very large,  one of the  most
  3908.         time  consuming  options is the function/data type file reference
  3909.         (option -z).  The writing  and  reading  of  the  database  files
  3910.         (options  -G and -g) takes also some time due to the large number
  3911.         of different information.
  3912.  
  3913.         Don't panic if there seems to be no  disk  access  for  a  longer
  3914.         time,  the  reason  is  just  that  there  may  be time consuming
  3915.         computations and that the output will be buffered  internally  to
  3916.         reduce  the  number  of  disk accesses and therefore speed up the
  3917.         output!
  3918.  
  3919.         For more detailed information about the  program  efficiency  see
  3920.         appendix 4.
  3921.  
  3922.  
  3923.  
  3924.  
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.  
  3933.  
  3934.  
  3935.  
  3936.  
  3937.  
  3938.  
  3939.  
  3940.  
  3941.  
  3942.  
  3943.  
  3944.  
  3945.  
  3946.  
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.  
  3954.  
  3955.  
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.                                      - 65 -
  3966.  
  3967.  
  3968.         12   TROUBLE SHOOTING
  3969.  
  3970.         This  section contains information about problems and the reasons
  3971.         which may occur during the use of SXT programs.  It  is  strictly
  3972.         recommended  that users should read the complete documentation to
  3973.         have an overview about the features before they start  using  the
  3974.         programs  and  run  into  any  unexpected troubles.  See also the
  3975.         chapter   about   'PROGRAM   LIMITATIONS'   and   the    document
  3976.         'PROBLEMS.DOC'.
  3977.  
  3978.         UNEXPECTED  RESULTS  WHILE RUNNING THE SXT TEXT MODE COMMAND LINE
  3979.         VERSIONS UNDER WINDOWS 3.1
  3980.         The 386 versions cannot run under Windows 3.1, they are using the
  3981.         CPU exclusive and can therefore not co-exist with  Windows,  only
  3982.         the real mode versions can. In Windows enhanced mode (virtual 386
  3983.         mode),  the  real  mode  versions  cannot  run  simultaneously in
  3984.         several independent DOS-windows if they are working in  the  same
  3985.         directory  or  use  the  same  temporary  directory,  because the
  3986.         temporary intermediate files may have the  same  names  and  will
  3987.         conflict  due  to multiple concurrent accesses to them.  This may
  3988.         also happen if the same files are scanned or included. The use of
  3989.         SHARE.EXE  is  highly  recommended  to  catch  such  file  access
  3990.         conflicts,   see  your  DOS  manual  for  information  about  the
  3991.         installation of SHARE.
  3992.  
  3993.         MICROEMACS FOR WINDOWS SEEMS TO HANG DURING DATABASE  ACCESS  AND
  3994.         DOES NOT RETURN
  3995.         The reason is usually quite simple: The shell call to DOS through
  3996.         DOSEXEC.PIF  waits  for  a keystroke to continue execution and to
  3997.         return to WINDOWS.  You may change this behaviour by editing  the
  3998.         DOSEXEC.PIF    file   (see   MicroEMACS   section   for   further
  3999.         information).
  4000.  
  4001.         A PROGRAM CANNOT BE EXECUTED
  4002.         The program path is not specified  in  the  environment  variable
  4003.         PATH,  the  programs  are  not  yet  installed  in  the specified
  4004.         directory,  attempt to start a 386 protected mode  version  on  a
  4005.         80286 (or lower) computer.
  4006.  
  4007.         EXECUTION STOPPED WITH MESSAGE "OUT OF MEMORY"
  4008.         An  attempt  to  allocate  memory  has  failed.   Try  to  remove
  4009.         unnecessary memory resident TSR programs and/or use the protected
  4010.         mode versions if you have an 386/486. If this message happens for
  4011.         the protected mode versions,  there is not enough free disk space
  4012.         for the swap file.  Set the temporary directory, defined by 'TMP'
  4013.         resp.  'TEMP'  environment  variables,   to  another  drive,   if
  4014.         possible.
  4015.  
  4016.         WRITING THE OUTPUT FILE TAKES A LONG TIME
  4017.         A large number of information must be handled, option -x or -r is
  4018.         not set and so the output calltree is very large, slow CPU and/or
  4019.         harddisk.  Use  option  -v  to  redirect  intermediate files to a
  4020.         faster RAM-disk (if such is present).
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.                                      - 66 -
  4027.  
  4028.  
  4029.         THE RESULTING OUTPUT IS DEEPLY NESTED AND EXCEEDS THE SCREEN SIZE
  4030.         Two reasons: Use the -r or -x option if not already specified  or
  4031.         the source code/data types are indeed deeply nested.
  4032.  
  4033.         THE BRIEF MACROS CANNOT BE EXECUTED
  4034.         The macro file is not loaded, other macros with the same names or
  4035.         assigned keys already exist.
  4036.  
  4037.         THE BRIEF OR MICROEMACS MACROS CANNOT BE LOADED
  4038.         The  path  to  the  macro  file  location  must be specified when
  4039.         loading the macros,  if they are not in the default directory for
  4040.         the editor.
  4041.  
  4042.         THE BRIEF MACROS DO NOT FIND ANY FUNCTIONS OR DATA TYPES
  4043.         There is no access to CFTN,  CSTN,  DFTN (...),  due to incorrect
  4044.         path specification,  no database is  present,  the  path  to  the
  4045.         database files is incorrect, the database name is incorrect.
  4046.  
  4047.         THE BYTE OFFSET CALCULATION FILE "CST_OFFS.C" CANNOT BE COMPILED
  4048.         Several  reasons:  Necessary  data types or include files are not
  4049.         specified or the CST processing was done with include files other
  4050.         than those being used for compiling.  If the number of data  type
  4051.         information is too large, some compilers cannot compile the large
  4052.         number of statements in a single file generated from CST ('out of
  4053.         heap  space',  'code  segment  too  large' or other messages like
  4054.         that).  In that case you may have to split the file into  several
  4055.         smaller files or reduce the number of data types to display.
  4056.  
  4057.         LOCATING ITEMS IN THE BRIEF EDITOR POINTS TO WRONG PLACES
  4058.         Searching  items  from  within  the  BRIEF editor points to wrong
  4059.         lines,  the requested item is not present there or the file seems
  4060.         to  be corrupted.  This can have several reasons: The file is not
  4061.         up-to-date and has been changed since the database generation  so
  4062.         that the line references are no longer valid.  Another reason can
  4063.         be that the source file has explicit #line numbers as it is usual
  4064.         for files produced by source code generators like  YACC/BISON  or
  4065.         LEX/FLEX.  A  third  reason  may  be  that  the  source  file was
  4066.         generated on an UNIX system and has therefore only LF instead  of
  4067.         CR+LF  as  end-of-line delimiter so that BRIEF cannot display the
  4068.         file correctly, the file seems to be written in a single line. If
  4069.         possible convert such files to DOS text format with  UNIX2DOS  or
  4070.         other utilities.
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.                                      - 67 -
  4088.  
  4089.  
  4090.         13   FREQUENTLY ASKED QUESTIONS (FAQ)
  4091.  
  4092.         ARE THERE ANY RESTRICTIONS IN THE USE OF THE ANALYSIS RESULTS?
  4093.         No  restrictions  for REGISTERED users,  they can use the results
  4094.         for all purposes like program documentation, customer information
  4095.         or debugging as long as a notice about the name and copyright  of
  4096.         the used SXT program is given.
  4097.  
  4098.         WHY  IS  NO  OS/2  IPF  SOURCE  CODE  FOR  OS/2 INFORMATION FILES
  4099.         GENERATED?
  4100.         The OS/2 IPF functionality,  comparable with the MS-Windows  Help
  4101.         system,   has  limitations  which  are  not  acceptable  for  SXT
  4102.         programs.  According to the OS/2 3.0 online help information,  it
  4103.         is  not possible to generate a single IPF source file larger than
  4104.         64K  and  a  single  source  line  cannot  have  more  than   255
  4105.         characters.  Both  limits  are  regularly  exceeded  by  the  SXT
  4106.         programs.
  4107.  
  4108.         WHY ARE SEVERAL DATABASE FILES FOR EVERY PROJECT GENERATED?
  4109.         Separating  the  analysis  items  (identifier  names,  filenames,
  4110.         relationships,  ...)  of one project into several closely related
  4111.         database files  is  the  best  way  to  achieve  minimum  storage
  4112.         requirements and to optimise disk usage.  This way of storage has
  4113.         no redundancies compared to storage in a single database file.
  4114.  
  4115.         WHY IS THERE NO CROSS REFERENCE FOR VARIABLES INCLUDED?
  4116.         This would  need  much  additional  memory  and  slows  down  the
  4117.         analysis  process.  There would also be a lot of multiple defined
  4118.         names in different contexts to be managed if  several  files  are
  4119.         analysed. A lot of tools exist which perform this task quite good
  4120.         e.g.  the  integrated  compiler environments or other source code
  4121.         analysers.
  4122.  
  4123.         WHY ARE CFT AND CST NOT COMBINED IN ONE PROGRAM?
  4124.         Historical and practical reasons: the CFT development was started
  4125.         before CST and both programs are optimised for their own  special
  4126.         purposes.  Combining them would complicate them and slow down the
  4127.         analysis process. Also the memory requirements would grow.
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.  
  4142.  
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.                                      - 68 -
  4149.  
  4150.  
  4151.         14   REFERENCES
  4152.  
  4153.         Brian  W.  Kernighan,  Dennis  M.  Ritchie:  "The  C  Programming
  4154.         Language", Prentice Hall, Englewood Cliffs, Second Edition 1988
  4155.  
  4156.         Samuel P.  Harbison,  Guy L. Steele Jr.: "C: A Reference Manual",
  4157.         Prentice Hall, Englewood Cliffs, Third Edition 1991
  4158.  
  4159.         Bjarne    Stroustrup:    "The    C++    Programming    Language",
  4160.         Addison-Wesley, Second Edition 1992
  4161.  
  4162.         Bjarne   Stroustrup:   "The   Design   and   Evolution  of  C++",
  4163.         Addison-Wesley, 1994
  4164.  
  4165.         Margaret  A.   Ellis,   Bjarne  Stroustrup:  "The  Annotated  C++
  4166.         Reference Manual" (ARM), Addison-Wesley, Second Edition 1991
  4167.  
  4168.         "Rationale for American National Standard for Information Systems
  4169.         - Programming Language C" (can be obtained via anonymous FTP from
  4170.         ftp.uu.net in '/doc/standards/ansi/X3.159-1989/ratinale.PS.Z')
  4171.  
  4172.         "Working  Paper  for  Draft  Proposed  International Standard for
  4173.         Information Systems  -  Programming  Language  C++",  AT&T,  ANSI
  4174.         committee X3J16, ISO working group WG21, January 28, 1993
  4175.  
  4176.         Bjarne Stroustrup, Keith Gorlen, Phil Brown, Dennis Mancl, Andrew
  4177.         Koenig: "UNIX System V - AT&T C++ Language System,  Release 2.1 -
  4178.         Selected Readings", AT&T, 1989
  4179.  
  4180.         Goldberg,  A.: "Programmer as Reader",  IEEE Software,  September
  4181.         1987
  4182.  
  4183.         L.W.  Cannon,  R.A.  Elliot,  L.W.  Kirchhoff,  J.H. Miller, J.M.
  4184.         Milner, R.W. Mitze, E.P. Schan, N.O. Whittington, H. Spencer,  D.
  4185.         Keppel,  M.  Brader:  "Recommended C Style and Coding Standards",
  4186.         Technical Report, in the Public Domain,  Revision 6.0,  July 1991
  4187.         (revised  and  updated  version  of  the  'AT&T Indian Hill style
  4188.         guide',  can be obtained via anonymous FTP from cs.washington.edu
  4189.         in '~ftp/pub/cstyle.tar.Z')
  4190.  
  4191.         A.  Dolenc,  A. Lemmke, D. Keppel, G.V. Reilly: "Notes on Writing
  4192.         Portable Programs in C", Technical Report,  in the Public Domain,
  4193.         Revision 8, November 1990 (can be obtained via anonymous FTP from
  4194.         cs.washington.edu in '~ftp/pub/cport.tar.Z')
  4195.  
  4196.         M.   Henricson,  E.  Nyquist:  "Programming  in  C++,  Rules  and
  4197.         Recommendations",   Technical  Report,   in  the  Public  Domain,
  4198.         Ellemtel  Telecommunication Systems Laboratories,  Alvsjo/Sweden,
  4199.         Document No. M 90 0118 Uen, Rev. C (can be obtained via anonymous
  4200.         FTP from various sites as 'rules.ps.Z' or 'c++rules.ps.Z')
  4201.  
  4202.         H. Wehnes: "FORTRAN 77", 3. Auflage, Carl Hanser Verlag, 1984
  4203.  
  4204.         H.   Sigl:  "dBase/Foxbase/Clipper  -  Globalreferenz",   Addison
  4205.         Wesley, 1989
  4206.  
  4207.  
  4208.  
  4209.                                      - 69 -
  4210.  
  4211.  
  4212.         "A  Beginner's  Guide  to  HTML",  electronically  available from
  4213.         'http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html'
  4214.  
  4215.  
  4216.         Compiler reference manuals and related  documentations  (language
  4217.         references, language implementations and extensions):
  4218.  
  4219.         -    Microsoft C 5.1
  4220.         -    Microsoft C 6.0
  4221.         -    Microsoft C/C++ 7.0
  4222.         -    Microsoft Visual C++ 1.5 Professional
  4223.         -    Microsoft C/C++ for Windows NT (Beta Release 3/93)
  4224.         -    Microsoft Visual C++ 1.0 for Windows NT (Beta Release 6/93)
  4225.         -    Microsoft Visual C++ 1.1 for Windows NT
  4226.         -    Microsoft C for SCO UNIX System V Rel. 3.2
  4227.         -    Microsoft Macro Assembler MASM 5.1
  4228.         -    Borland Turbo C++ 1.0
  4229.         -    Borland C++ 2.0
  4230.         -    Borland C++ 3.1
  4231.         -    Borland C++ 1.0 for OS/2
  4232.         -    Borland Turbo Assembler TASM 2.0
  4233.         -    Intel 80860 Metaware High C i860 APX (UNIX-hosted)
  4234.         -    Intel 80960 C-Compiler (ic960, ec960)
  4235.         -    Intel 80960 Assembler (asm960)
  4236.         -    Watcom C/C++ 10.0a
  4237.         -    GNU-960 Tools (UNIX-hosted)
  4238.         -    GNU-C   Compiler   2.2.2/  2.4.5/  2.5.7/  2.6.3  (C,   C++,
  4239.              Objective-C), GNU-C DOS and OS/2 ports (DJGPP, EMX)
  4240.         -    GNU Assembler
  4241.         -    AT&T C++ 2.1 CFRONT (C++  to  C  translator)  for  SCO  UNIX
  4242.              System V Rel. 3.2
  4243.         -    IBM  C-Compilers  (CC,  XLC)  for IBM RS 6000 RISC stations,
  4244.              AIX 3.15
  4245.         -    HP C-Compilers (CC,  C89) for HP Apollo 9000 RISC  stations,
  4246.              HP-UX 9.0
  4247.         -    SUN SunOS 4.1 C-Compiler
  4248.         -    Digital Equipment Corporation (DEC) VAX C
  4249.         -    Digital Equipment Corporation (DEC) VAX FORTRAN
  4250.         -    Ashton Tate dBase III plus
  4251.  
  4252.  
  4253.  
  4254.  
  4255.  
  4256.  
  4257.  
  4258.  
  4259.  
  4260.  
  4261.  
  4262.  
  4263.  
  4264.  
  4265.  
  4266.  
  4267.  
  4268.  
  4269.  
  4270.                                      - 70 -
  4271.  
  4272.  
  4273.         15   TRADEMARKS
  4274.  
  4275.         All  brand  or  product  names  are trademarks (TM) or registered
  4276.         trademarks (R) of their respective owners.
  4277.  
  4278.         The following  products  and  names  are  Copyright  (C)  Juergen
  4279.         Mueller (J.M.), all rights reserved world-wide:
  4280.  
  4281.              CXT (TM) C EXPLORATION TOOLS
  4282.              CFT (TM) C FUNCTION TREE GENERATOR
  4283.              CFTN (TM) C FUNCTION TREE NAVIGATOR
  4284.              CST (TM) C STRUCTURE TREE GENERATOR
  4285.              CSTN (TM) C STRUCTURE TREE NAVIGATOR
  4286.  
  4287.              CXTWIN (TM) C EXPLORATION TOOLS for Windows
  4288.              CFTWIN (TM) C FUNCTION TREE GENERATOR for Winfows
  4289.              CSTWIN (TM) C STRUCTURE TREE GENERATOR for Windows
  4290.  
  4291.              DXT (TM) DBASE EXPLORATION TOOLS
  4292.              DFT (TM) DBASE FUNCTION TREE GENERATOR
  4293.              DFTN (TM) DBASE FUNCTION TREE NAVIGATOR
  4294.  
  4295.              DXTWIN (TM) DBASE EXPLORATION TOOLS for Windows
  4296.              DFTWIN (TM) DBASE FUNCTION TREE GENERATOR for Windows
  4297.  
  4298.              FXT (TM) FORTRAN EXPLORATION TOOLS
  4299.              FFT (TM) FORTRAN FUNCTION TREE GENERATOR
  4300.              FFTN (TM) FORTRAN FUNCTION TREE NAVIGATOR
  4301.  
  4302.              FXTWIN (TM) FORTRAN EXPLORATION TOOLS for Windows
  4303.              FFTWIN (TM) FORTRAN FUNCTION TREE GENERATOR for Windows
  4304.  
  4305.              LXT (TM) LISP EXPLORATION TOOLS
  4306.              LFT (TM) LISP FUNCTION TREE GENERATOR
  4307.              LFTN (TM) LISP FUNCTION TREE NAVIGATOR
  4308.  
  4309.              LXTWIN (TM) LISP EXPLORATION TOOLS for Windows
  4310.              LFTWIN (TM) LISP FUNCTION TREE GENERATOR for Windows
  4311.  
  4312.         These packages are part of
  4313.  
  4314.              SXT (TM) SOFTWARE EXPLORATION TOOLS
  4315.              SXTWIN (TM) SOFTWARE EXPLORATION TOOLS for Windows
  4316.  
  4317.         which  provide  a  similar  set of functionalities for the source
  4318.         code analysis of different programming languages.
  4319.  
  4320.         See PRODUCT.DOC for a complete overview of the SXT  packages  and
  4321.         the different supported platforms.
  4322.  
  4323.  
  4324.  
  4325.  
  4326.  
  4327.  
  4328.  
  4329.  
  4330.  
  4331.                                      - 71 -
  4332.  
  4333.  
  4334.         APPENDIX 1: C/C++ PRECOMPILER DEFINES
  4335.  
  4336.         The  following list shows the builtin precompiler defines for the
  4337.         supported compiler types (option -T).  It  contains  the  default
  4338.         defines and the optional memory model and architecture defines.
  4339.  
  4340.         Other default compiler defines which are usually declared by some
  4341.         of  the compilers are not automatically defined by the -T option.
  4342.         These are defines  for  compilation  like  WINDOWS,  __WINDOWS__,
  4343.         _Windows,  DLL or __DLL__,  for optimization like __OPTIMIZE__ or
  4344.         __FASTCALL__ or  others  like  those  about  target  (operating-)
  4345.         systems like NT,  MIPS,  UNIX,  unix,  __unix__,  i386, __i386__,
  4346.         GNUDOS, BSD, VMS, USG,  DGUX or hpux.  Other sometimes predefined
  4347.         macros  are  __STRICT_ANSI__ or __CHAR_UNSIGNED__.  If necessary,
  4348.         they can be user defined on the command line with the -D option.
  4349.  
  4350.         The macro name __cplusplus will be defined if  the  command  line
  4351.         option '-C++' is set to enable C++ processing.
  4352.  
  4353.         1. MSC51 (Microsoft C 5.1):
  4354.         Default defines:         MSDOS, M_I86
  4355.         C++ specific defines:    (none)
  4356.         Memory model defines:    M_I86SM, M_I86MM, M_I86CM, M_I86LM,
  4357.                                  M_I86HM
  4358.  
  4359.         2. MSC70 (Microsoft C/C++ 7.0):
  4360.         Default defines:         MSDOS, M_I86, _MSC_VER (= 700)
  4361.         C++ specific defines:    (none)
  4362.         Memory model defines:    M_I86TM, M_I86SM, M_I86MM, M_I86CM,
  4363.                                  M_I86LM, M_I86HM
  4364.  
  4365.         3. MSVC15 (Microsoft Visual C++ 1.5):
  4366.         Default defines:         MSDOS, M_I86, _MSC_VER (= 800)
  4367.         C++ specific defines:    (none)
  4368.         Memory model defines:    M_I86TM, M_I86SM, M_I86MM, M_I86CM,
  4369.                                  M_I86LM, M_I86HM
  4370.  
  4371.         4. MSVCWNT (Microsoft Visual C++ 1.1 for Windows NT):
  4372.         Default defines:         MSDOS, M_I86, _MSC_VER (= 800),
  4373.                                  _M_IX86 (= 300)
  4374.         C++ specific defines:    (none)
  4375.         Memory model defines:    (not necessary)
  4376.  
  4377.         5. TC10 (Borland Turbo C++ 1.0):
  4378.         Default defines:         __MSDOS__, __TURBOC__
  4379.         C++ specific defines:    __TCPLUSPLUS
  4380.         Memory model defines:    __TINY__, __SMALL__, __MEDIUM__,
  4381.                                  __COMPACT_, __LARGE__, __HUGE__
  4382.  
  4383.         6. BC20 (Borland C++ 2.0):
  4384.         Default defines:         __MSDOS__, __BORLANDC__ (= 0x0200),
  4385.                                  __TURBOC__ (= 0x0297)
  4386.         C++ specific defines:    __BCPLUSPLUS__ (= 0x0200),
  4387.                                  __TCPLUSPLUS__ (= 0x0200)
  4388.         Memory model defines:    __TINY__, __SMALL__, __MEDIUM__,
  4389.                                  __COMPACT_, __LARGE__, __HUGE__
  4390.  
  4391.  
  4392.                                      - 72 -
  4393.  
  4394.  
  4395.  
  4396.         7. BC31 (Borland C++ 3.1):
  4397.         Default defines:         __MSDOS__, __BORLANDC__ (= 0x0410),
  4398.                                  __TURBOC__ (= 0x0410)
  4399.         C++ specific defines:    __BCPLUSPLUS__ (= 0x0310),
  4400.                                  __TCPLUSPLUS__ (= 0x0310)
  4401.         Memory model defines:    __TINY__, __SMALL__, __MEDIUM__,
  4402.                                  __COMPACT_, __LARGE__, __HUGE__
  4403.  
  4404.         8. BC10OS2 (Borland C++ 1.0 for OS/2):
  4405.         Default defines:         __OS2__, __BORLANDC__ (= 0x0400),
  4406.                                  __TURBOC__ (= 0x0400)
  4407.         C++ specific defines:    __BCPLUSPLUS__ (= 0x0320),
  4408.                                  __TCPLUSPLUS__ (= 0x0320),
  4409.                                  __TEMPLATES__
  4410.         Memory model defines:    (not necessary)
  4411.  
  4412.         9. GNU (GNU C 2.2.2):
  4413.         Default defines:         __GNUC__ (= 2)
  4414.         C++ specific defines:    __GNUG__ (= 2)
  4415.         Memory model defines:    (not necessary)
  4416.  
  4417.         10. I960 (Intel iC960 3.0):
  4418.         Default defines:         __i960
  4419.         C++ specific defines:    (none)
  4420.         Memory model defines:    (not necessary)
  4421.         Architecture defines:    __i960KA, __i960KB, __i960SA, __i960SB,
  4422.                                  __i960MC, __i960CA
  4423.  
  4424.  
  4425.         USER DEFINED ADAPTATION OF CFT AND CST TO OTHER COMPILERS
  4426.  
  4427.         The  adaptation  of  CFT  and CST to other C/C++ compilers can be
  4428.         done with the -D,  -U and -B options.  First you have to find out
  4429.         which precompiler defines the compiler uses by default or related
  4430.         to   command   line  options.   For  these  information  see  the
  4431.         documentation and help-files for  your  compiler.  The  necessary
  4432.         precompiler defines have to be specified for CFT and CST with -D.
  4433.         Additionally it may be necessary to specify undefines with -U and
  4434.         to declare the basic type size with -B.  The following line shows
  4435.         as an example the necessary options for the  MS  Visual  C++  1.5
  4436.         compiler (large model):
  4437.  
  4438.         -DMSDOS -DM_I86 -DMSC_VER=800 -DM_I86LM -B0,1,2,2,4,4,8,10*4,4
  4439.  
  4440.  
  4441.  
  4442.  
  4443.  
  4444.  
  4445.  
  4446.  
  4447.  
  4448.  
  4449.  
  4450.  
  4451.  
  4452.  
  4453.                                      - 73 -
  4454.  
  4455.  
  4456.         APPENDIX 2: RESERVED C/C++ KEYWORDS
  4457.  
  4458.         The following list shows the keywords being recognised by CFT and
  4459.         CST,   the  standard  C  keywords,   the  C++  keywords  and  the
  4460.         non-standard keywords which are compiler dependent extensions  to
  4461.         the C or C++ language. Standard C keywords are also C++ keywords,
  4462.         always!  The C++ keywords are recognised only if option '-C++' is
  4463.         set, otherwise they are treated as identifiers. This list may not
  4464.         be complete or correct  due  to  upcoming  new  releases  of  the
  4465.         supported  compilers  with  new  extensions  or extensions to the
  4466.         language standard.  C++,  for which till now no  'real'  language
  4467.         standard  exists  (except the de-facto standard,  the AT&T CFRONT
  4468.         implementation),    differs   among   several    implementations,
  4469.         especially for the new introduced exception and template concepts
  4470.         (try,   catch,  throw,  template).  Extensions  to  the  language
  4471.         especially  in  GNU  C  (e.g.  __alignof,  __classof,  interface,
  4472.         signature,  __FUNCTION__,  ...)  or undocumentd features e.g.  in
  4473.         Microsoft C/C++ 7.0 are ignored (even if they are  listed  here).
  4474.         This list may not be complete or correct.
  4475.  
  4476.         KEYWORDS       Standard       MSC TC/BC GNU C
  4477.                        C    C++       7.0 3.0   2.2.2
  4478.  
  4479.         asm            x
  4480.         auto           x
  4481.         break          x
  4482.         case           x
  4483.         catch               x         (x)       x
  4484.         cdecl                         x    x
  4485.         char           x
  4486.         class               x
  4487.         classof                                 x
  4488.         const          x
  4489.         continue       x
  4490.         default        x
  4491.         delete              x
  4492.         do             x
  4493.         double         x
  4494.         dynamic                                 x
  4495.         else           x
  4496.         enum           x
  4497.         except                                  x
  4498.         exception                               x
  4499.         extern         x
  4500.         far                           x    x
  4501.         float          x
  4502.         for            x
  4503.         fortran                       x    x
  4504.         friend              x
  4505.         goto           x
  4506.         huge                          x    x
  4507.         if             x
  4508.         inline              x
  4509.         int            x
  4510.         interrupt                     x    x
  4511.         long           x
  4512.  
  4513.  
  4514.                                      - 74 -
  4515.  
  4516.  
  4517.         near                          x    x
  4518.         new                 x
  4519.         operator            x
  4520.         overload                           x    x
  4521.         pascal                        x    x
  4522.         private             x
  4523.         protected           x
  4524.         public              x
  4525.         register       x
  4526.         return         x
  4527.         short          x
  4528.         signed         x
  4529.         sizeof         x
  4530.         static         x
  4531.         struct         x
  4532.         switch         x
  4533.         template            x
  4534.         this                x
  4535.         throw               x
  4536.         try                 x         (x)       x
  4537.         typedef        x
  4538.         typeof                                  x
  4539.         union          x
  4540.         unsigned       x
  4541.         virtual             x
  4542.         void           x
  4543.         volatile       x
  4544.         while          x
  4545.         __alignof                               x
  4546.         __alignof__                             x
  4547.         __asm                         x         x
  4548.         __asm__                                 x
  4549.         __attribute                             x
  4550.         __attribute__                           x
  4551.         __based                       x
  4552.         __cdecl                       x
  4553.         __classof                               x
  4554.         __classof__                             x
  4555.         __const                       x         x
  4556.         __const__                               x
  4557.         __emit                        x
  4558.         __except                      x
  4559.         __export                      x
  4560.         __extension__                           x
  4561.         __far                         x
  4562.         __fastcall                    x
  4563.         __finally                     x
  4564.         __fortran                     x
  4565.         __headof                                x
  4566.         __headof__                              x
  4567.         __huge                        x
  4568.         __inline                                x
  4569.         __inline__                              x
  4570.         __interrupt                   x
  4571.         __label__                               x
  4572.         __loadds                      x
  4573.  
  4574.  
  4575.                                      - 75 -
  4576.  
  4577.  
  4578.         __near                        x
  4579.         __saveregs                    x
  4580.         __segment                     x
  4581.         __segname                     x
  4582.         __self                        x
  4583.         __signed                                x
  4584.         __signed__                              x
  4585.         __stdcall                     x
  4586.         __syscall                     x
  4587.         __try                         x
  4588.         __typeof                                x
  4589.         __typeof__                              x
  4590.         __volatile                              x
  4591.         __volatile__                            x
  4592.         _asm                          x
  4593.         _based                        x
  4594.         _cdecl                        x
  4595.         _emit                         x
  4596.         _export                       x    x
  4597.         _far                          x
  4598.         _fastcall                     x
  4599.         _fortran                      x
  4600.         _huge                         x
  4601.         _interrupt                    x
  4602.         _loadds                       x    x
  4603.         _near                         x
  4604.         _pascal                       x
  4605.         _saveregs                     x    x
  4606.         _seg                               x
  4607.         _segment                      x
  4608.         _segname                      x
  4609.         _self                         x
  4610.  
  4611.  
  4612.  
  4613.  
  4614.  
  4615.  
  4616.  
  4617.  
  4618.  
  4619.  
  4620.  
  4621.  
  4622.  
  4623.  
  4624.  
  4625.  
  4626.  
  4627.  
  4628.  
  4629.  
  4630.  
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.                                      - 76 -
  4637.  
  4638.  
  4639.         APPENDIX 3: RESERVED FORTRAN KEYWORDS
  4640.  
  4641.         The  following  lists  show  the keywords and intrinsic functions
  4642.         from FORTRAN 77 and non-standard extensions (VAX, CDC, AIX, UNIX,
  4643.         ...) recognised by FFT. This list may not be complete or correct.
  4644.  
  4645.         Keywords  (standard  &  non-standard):  ACCEPT,  ASSERT,  ASSIGN,
  4646.         AUTOMATIC,   BACKSPACE,   BLOCKDATA,  BLOCK,  BYTE,  CALL,  CASE,
  4647.         CHARACTER,  CLOSE,  COMMON,  COMPLEX,  CONTINUE,  DATA,   DELETE,
  4648.         DICTIONARY,  DIMENSION,  DOUBLECOMPLEX,  DOUBLEPRECISION, DOUBLE,
  4649.         DOWHILE,  DO,  ELSEIF,  ELSE,  ENDDO,  ENDFILE,  ENDIF,   ENDMAP,
  4650.         ENDSELECT,   ENDSTRUCTURE,   ENDUNION,   ENDWHILE,   END,  ENTRY,
  4651.         EQUIVALENCE, EXTERNAL, FILE,  FORMAT,  FUNCTION,  GOTO,  GO,  IF,
  4652.         IMPLICITNONE,  IMPLICIT,  INCLUDE,  INQUIRE,  INTEGER, INTRINSIC,
  4653.         LOGICAL,  NAMELIST,  NONE,  OPEN,  PARAMETER,   PAUSE,   POINTER,
  4654.         PRECISION,  PRINT,  PROGRAM,  PUNCH,  READ, REAL, RECORD, RETURN,
  4655.         REWIND,  REWRITE,  SAVE,  SELECT,   SELECTCASE,   STATIC,   STOP,
  4656.         STRUCTURE,  SUBROUTINE,  THEN, TO, TYPE, UNION, UNLOCK, VOLATILE,
  4657.         WHILE, WRITE, $INCLUDE
  4658.  
  4659.         Intrinsic functions: ABS, ACHAR, ACOS, AIMAG, AINT, ALOG10, ALOG,
  4660.         AMAX0, AMAX1, AMIN0, AMIN1, AMOD, AND, ANINT, ASIN, ATAN2,  ATAN,
  4661.         CABS,  CCOS,  CEXP,  CHAR,  CLOG,  CMPLX, CONJG, COSH, COS, CSIN,
  4662.         CSQRT, DABS, DACOS, DASIN, DATAN2, DATAN, DBLE,  DCMPLX,  DCONJG,
  4663.         DCOSH,  DCOS, DDIM, DEXP, DFLOAT, DIMAG, DIM, DINT, DLOG10, DLOG,
  4664.         DMAX1, DMIN1, DMOD, DNINT,  DPROD,  DSIGN,  DSINH,  DSIN,  DSQRT,
  4665.         DTANH,  DTAN,  EPBASE,  EPEMAX,  EPEMIN,  EPHUGE, EPMRSP, EPPREC,
  4666.         EPTINY, EXP,  FLOAT,  FPABSP,  FPEXPN,  FPFRAC,  FPMAKE,  FPRRSP,
  4667.         FPSCAL,  IABS,  IACHAR,  ICHAR,  IDIM, IDINT, IDNINT, IFIX, IMAG,
  4668.         INDEX, INT, ISIGN, LEN, LGE, LGT, LLE, LLT, LOG10,  LOG,  LSHIFT,
  4669.         MAX0,  MAX1,  MAX,  MIN0,  MIN1,  MIN,  MOD, NINT, NOT, OR, REAL,
  4670.         RSHIFT, SIGN, SINH, SIN, SNGL, SQRT, TANH, TAN, XOR, ZABS,  ZCOS,
  4671.         ZEXP, ZLOG, ZSIN, ZSQRT,
  4672.  
  4673.         Non-standard intrinsic functions: ABORT,  ACOSD,  ASIND,  ATAN2D,
  4674.         ATAND, BTEST, CABS1, CAMAX, CAMIN, CASUM,  CAXPY,  CCOPY,  CDABS,
  4675.         CDCOS,  CDEXP,  CDLOG,  CDOTC,  CDOTU, CDSIN, CDSQRT, CMAX, CMIN,
  4676.         CNORM2, CNRM2, CNRSQ, COSD, CROTG,  CROT,  CSCAL,  CSET,  CSIGN1,
  4677.         CSIGN,  CSUM,  CSWAP,  CVCAL,  CZAXPY, DAMAX, DAMIN, DASUM, DATE,
  4678.         DAXPY, DCOPY, DDOT, DMAX,  DMIN,  DNORM2,  DNRM2,  DNRSQ,  DREAL,
  4679.         DROTG,  DROT,  DSCAL,  DSET,  DSUM, DSWAP, DVCAL, DZAXPY, ERRSNS,
  4680.         EXIT, GETARG, GETENV,  GMTIME,  HFIX,  I,  IARGC,  IAND,  IBCHNG,
  4681.         IBCLR,  IBITS,  IBSET,  ICAMAX,  ICAMIN,  ICMAX,  ICMIN,  IDAMAX,
  4682.         IDAMIN, IDATE, IDMAX, IDMIN, IEOR,  IOR,  IQINT,  IQNINT,  IRAND,
  4683.         ISAMAX,  ISAMIN, ISHA, ISHC, ISHFT, ISHFTC, ISMAX, ISMIN, IZAMAX,
  4684.         IZAMIN,  IZMAX,  IZMIN,  JFIX,  LTIME,  MVBITS,  NWORKERS,  QEXT,
  4685.         QFLOAT,  RAN,  RAND,  SAMAX,  SAMIN,  SASUM,  SAXPY, SCOPY, SDOT,
  4686.         SECNDS, SIND, SIZEOF, SMAX, SMIN, SNORM2,  SNRM2,  SNRSQ,  SRAND,
  4687.         SROTG,  SROT,  SSCAL,  SSET,  SSUM, SSWAP, SVCAL, SYSTEM, SZAXPY,
  4688.         TAND, TIME, ZAMAX, ZAMIN,  ZASUM,  ZAXPY,  ZCOPY,  ZDOTC,  ZDOTU,
  4689.         ZEXT, ZMAX, ZMIN, ZNORM2, ZNRM2, ZNRSQ, ZROTG, ZROT, ZSCAL, ZSET,
  4690.         ZSUM, ZSWAP, ZVCAL, ZZAXPY
  4691.  
  4692.         VAX specific built-in functions: %DESCR, %LOC, %REF, %VAL
  4693.  
  4694.  
  4695.  
  4696.  
  4697.                                      - 77 -
  4698.  
  4699.  
  4700.         APPENDIX 4: EFFICIENCY
  4701.  
  4702.         To  provide some values about the speed and the efficiency of the
  4703.         programs, tests were performed with CFT386 and CST386.
  4704.  
  4705.         One test with CFT386 (v2.21) was done with the source code of the
  4706.         C++ part of the GNU-C compiler  (version  2.2.2),  which  is  the
  4707.         largest of the three compiler parts (C,  C++,  Objective-C).  The
  4708.         test was made on a 33 MHz 80486,  8 MB RAM,  256 KB cache,  12 ms
  4709.         hard  disk,  2.5  MB  RAM-disk.  The command line options were -m
  4710.         -rauspPC_INCLUDE_PATH -TGNU -cs -Cs -n -W5 -G  -vn:\  -L+  -time.
  4711.         The following results have been found:
  4712.  
  4713.         -    137  files  (71 source files and 66 include files) have been
  4714.              scanned
  4715.         -    a total number of 2318 functions has been found  from  which
  4716.              2236 functions were defined in the 69 source files
  4717.         -    the  directed  call  graph  would  have 2302 nodes and 10276
  4718.              connections
  4719.         -    the critical function call path has a maximum nesting  level
  4720.              of 115
  4721.         -    the  total  size  of  the  137 files is 6.538 MB with 208900
  4722.              lines (about  31  bytes/line),  source  code/filesize  ratio
  4723.              0.712, average function size is 1956 bytes resp. 63 lines
  4724.         -    the  effective  size  of the preprocessed and scanned source
  4725.              code (source files and their included files)  is  20.990  MB
  4726.              with 602300 lines
  4727.         -    the resulting output file has about 3.921 MB and 36000 lines
  4728.         -    the resulting 6 database files have a size of 870 KB (source
  4729.              code/database ratio is about 7.5 : 1)
  4730.         -    inside  BRIEF,  a  database  search  for  the  location of a
  4731.              function is performed in less than 4 seconds
  4732.         -    the total time  for  the  complete  processing  was  21'57''
  4733.              minutes  (11'03''  for preprocessing,  8'13'' for analysing,
  4734.              1'00'' for output file writing, 1'32'' for database writing)
  4735.         -    the average speed for  this  source  code  was  about  1.080
  4736.              MB/min. respectively 31000 lines/min.
  4737.  
  4738.         Another test with CFT386 (v2.21) was done with a large commercial
  4739.         project.  The test was made on a 33 MHz 80486,  8 MB RAM,  256 KB
  4740.         cache,  12 ms hard disk,  no RAM-disk.  The command line  options
  4741.         were  -m+  -rausp -cs -Cs -n -time -cmdline -M -G -TMSC70,L -P -L
  4742.         -W5. The results:
  4743.  
  4744.         -    291 files (194 source files and 97 include files) have  been
  4745.              scanned
  4746.         -    a  total  number of 1955 functions has been found from which
  4747.              1866 functions were defined in the source files
  4748.         -    the total size of the 291 files is  15.719  MB  with  387600
  4749.              lines,  source  code/filesize ratio 0.531,  average function
  4750.              size is 2800 bytes resp. 100 lines
  4751.         -    the effective size of the preprocessed  and  scanned  source
  4752.              code  (source  files and their included files) is 220.685 MB
  4753.              with 2861000 lines
  4754.  
  4755.  
  4756.  
  4757.  
  4758.                                      - 78 -
  4759.  
  4760.  
  4761.         -    the total time for  the  complete  processing  was  161'02''
  4762.              minutes (139'43'' for preprocessing,  19'21'' for analysing,
  4763.              0'56'' for output file writing, 0'58'' for database writing)
  4764.         -    the average speed for  this  source  code  was  about  1.388
  4765.              MB/min. respectively 17990 lines/min.
  4766.  
  4767.         To  get  some  efficiency values for CST386 (v2.21),  the include
  4768.         files from another commercial  project  were  analysed  for  data
  4769.         types.  The  test  was made on a 33 MHz 80486,  8 MB RAM,  256 KB
  4770.         cache, 12 ms hard disk, no RAM-disk:
  4771.  
  4772.         -    52 include files have been scanned
  4773.         -    a total number of 605 data types have been found from  which
  4774.              567  structures/unions  were defined in 42 of the 54 include
  4775.              files
  4776.         -    the directed call  graph  would  have  588  nodes  and  1787
  4777.              connections
  4778.         -    the  total size of the 52 files is 1.384 MB with 25410 lines
  4779.              (about 54 bytes/line), source code/filesize ratio 0.342
  4780.         -    the resulting output file (options -rasp  -cs  -Cs  -n)  has
  4781.              about 378 KB and 8760 lines
  4782.         -    the resulting 6 database files have a size of 315 KB (source
  4783.              code/database ratio is about 4.4 : 1)
  4784.         -    the  total  time  for  the  complete  processing  was 0'43''
  4785.              minutes (0'17'' for analysis, 0'05'' for output file writing
  4786.              and 0'20'' for database writing)
  4787.         -    the average speed for  this  source  code  was  about  4.885
  4788.              MB/min.  respectively  89700  lines/min  (only analysis,  no
  4789.              preprocessing performed).
  4790.  
  4791.         Another test with CST386 (v2.21) was done  with  the  C++  source
  4792.         code  of  the Microsoft Foundation Class (MFC) 2.0.  The test was
  4793.         made on a 33 MHz 80486, 8 MB RAM, 256 KB cache,  12 ms hard disk,
  4794.         2.5   MB   RAM-disk.   The   command   line  options  were  -rasp
  4795.         -I\msvc\mfc\include -I\msvc\include -P -TMSVCWNT -C++  -D_WINDOWS
  4796.         -D_X86_  -Cs -n -b -W5 -time -G -vn:\ -L+.  The following results
  4797.         have been found:
  4798.  
  4799.         -    170 files (95 source files and 75 include files)  have  been
  4800.              scanned
  4801.         -    a  total number of 890 data types have been found from which
  4802.              701 were defined in the source and include files
  4803.         -    the directed call  graph  would  have  755  nodes  and  1402
  4804.              connections
  4805.         -    the  total size of the 170 files is 2.42 MB with 87500 lines
  4806.              (about 28 bytes/line), source code/filesize ratio 0.779
  4807.         -    the effective size of the preprocessed  and  scanned  source
  4808.              code  (source  files  and their included files) is 157.28 MB
  4809.              with 5580100 lines
  4810.         -    the total time for  the  complete  processing  was  106'20''
  4811.              minutes  (72'07''  for preprocessing,  33'14'' for analysis,
  4812.              0'12'' for output file writing, 0'44'' for database writing)
  4813.         -    the average speed  for  this  source  code  was  about  1.49
  4814.              MB/min. respectively 53000 lines/min.
  4815.  
  4816.  
  4817.  
  4818.  
  4819.                                      - 79 -
  4820.  
  4821.  
  4822.         The  calculated  average values for the analysis speed differ due
  4823.         to the effective size of the  'really'  present  source  code  in
  4824.         relation  to  the  size  of the comments which can be seen by the
  4825.         code/filesize ratio.  The speed values do not consider  that,  if
  4826.         the  preprocessing  option  -P  is set,  the source code is first
  4827.         preprocessed to a temporary file and then analysed  in  a  second
  4828.         step  so  that  large  parts  of  the  source code are read twice
  4829.         (original and preprocessed code) and written  once  (intermediate
  4830.         preprocessor output).
  4831.  
  4832.         With these facts in mind, the analysis speed of CFT and CST seems
  4833.         to be quite acceptable!
  4834.  
  4835.  
  4836.  
  4837.  
  4838.  
  4839.  
  4840.  
  4841.  
  4842.  
  4843.  
  4844.  
  4845.  
  4846.  
  4847.  
  4848.  
  4849.  
  4850.  
  4851.  
  4852.  
  4853.  
  4854.  
  4855.  
  4856.  
  4857.  
  4858.  
  4859.  
  4860.  
  4861.  
  4862.  
  4863.  
  4864.  
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880.                                      - 80 -
  4881.  
  4882.  
  4883.         APPENDIX 5: SYSTEM REQUIREMENTS
  4884.  
  4885.         DOS real mode versions:
  4886.         -    IBM-AT or 100% compatible with Intel 80286 or higher, 640 KB
  4887.              RAM, hard-disk, MS-DOS 5.0 or higher
  4888.  
  4889.         DOS protected mode versions:
  4890.         -    IBM-AT  or 100% compatible with Intel 80386/80387 or higher,
  4891.              8 MB RAM, hard-disk, MS-DOS 5.0 or higher
  4892.              (NOTE: it is currently  not  known  if  the  protected  mode
  4893.              version will run in the DOS-box of Windows 95 (MS-DOS 7.0))
  4894.  
  4895.         Windows 16 bit versions:
  4896.         -    IBM-AT  or 100% compatible with Intel 80386 or higher,  8 MB
  4897.              RAM, hard-disk, MS-DOS 5.0 or higher, Windows 3.1 or Windows
  4898.              for Workgroups 3.11 (enhanced mode),
  4899.              VBRUN300.DLL (Visual Basic Run-Time library installed in the
  4900.              \windows\system  directory,   required  by  the  DLL  sample
  4901.              application SXTNVIEW)
  4902.  
  4903.         Windows 32 bit (Win32s) versions:
  4904.         -    IBM-AT  or 100% compatible with Intel 80386 or higher,  8 MB
  4905.              RAM, hard-disk,  Windows NT 3.1,  Windows 95,  MS-DOS 5.0 or
  4906.              higher  with  Windows 3.1 or Windows for Workgroups 3.11 and
  4907.              Win32s subsystem (v1.25)
  4908.  
  4909.  
  4910.  
  4911.         APPENDIX 6: INSTALLATION
  4912.  
  4913.         See  the  appropriate  documentation  (INSTALL.DOC,  INSTALL.W32,
  4914.         INSTALL.NT,   PROBLEMS.DOC,   ...)   for  information  about  the
  4915.         installation of the SXT programs.
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.  
  4923.  
  4924.  
  4925.  
  4926.  
  4927.  
  4928.  
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.  
  4939.  
  4940.  
  4941.                                      - 81 -
  4942.  
  4943.  
  4944.         APPENDIX 7: REVIEWS
  4945.  
  4946.         -    The C Users Journal (Volume  12,  Number  1,  January  1994)
  4947.              (CXT)
  4948.  
  4949.         -    Professionelle Shareware 1/1993 (Computer Solutions Software
  4950.              GmbH) (CXT)
  4951.  
  4952.         -    Professionelle Shareware 3/1994 (Computer Solutions Software
  4953.              GmbH) (DXT, FXT, LXT)
  4954.  
  4955.         -    Shareware Professionell 11/1994 (Computer Solutions Software
  4956.              GmbH) (CXTWIN, DXTWIN, FXTWIN, LXTWIN)
  4957.  
  4958.  
  4959.  
  4960.  
  4961.  
  4962.  
  4963.  
  4964.  
  4965.  
  4966.  
  4967.  
  4968.  
  4969.  
  4970.  
  4971.  
  4972.  
  4973.  
  4974.  
  4975.  
  4976.  
  4977.  
  4978.  
  4979.  
  4980.  
  4981.  
  4982.  
  4983.  
  4984.  
  4985.  
  4986.  
  4987.  
  4988.  
  4989.  
  4990.  
  4991.  
  4992.  
  4993.  
  4994.  
  4995.  
  4996.  
  4997.  
  4998.  
  4999.  
  5000.  
  5001.  
  5002.                                      - 82 -
  5003.  
  5004.  
  5005.         APPENDIX 8: AVAILABILITY
  5006.  
  5007.         The  SHAREWARE  versions of the SXT programs can be obtained from
  5008.         various shareware vendors,  downloaded from  a  lot  of  Internet
  5009.         FTP-sites  and  mailboxes  or  found  on several CD-ROM shareware
  5010.         collections.  The following list is not complete,  only the known
  5011.         vendors,  FTP-sites  (only  primary  sites  where the software is
  5012.         uploaded by the author) or CD-ROM's are shown.
  5013.  
  5014.         VENDORS:
  5015.  
  5016.         -    Computer  Solutions  Software  (CSL)  GmbH,  Postfach  1180,
  5017.              D-85561 Grafing, GERMANY
  5018.  
  5019.         -    PEARL Agency, Am Kalischacht 4, D-79426 Buggingen, GERMANY
  5020.  
  5021.         -    EMS  Professional Software,  4505 Buckhurst Ct.,  Olney,  MD
  5022.              20832-1830, U.S.A.
  5023.  
  5024.         -    The C-Users' Group (CUG),  1601  W.  23rd  St.,  Suite  200,
  5025.              Lawrence, KS 66046, U.S.A. (CXT: CUG Library Disk # 391)
  5026.  
  5027.         -    Public Brand Software / Ziff-Davies Interactive,  Cambridge,
  5028.              MA 02141, U.S.A. (distributes through Public Brand Software,
  5029.              ZiffNet on CompuServe, ZiffNet on Prodigy, and Interchange)
  5030.  
  5031.         FTP:
  5032.  
  5033.         -    SIMTEL: oak.oakland.edu
  5034.              (directories: CXT: SimTel/msdos/c, DXT: SimTel/msdos/dbase,
  5035.              FXT:   SimTel/msdos/fortran,   LXT:   SimTel/msdos/misclang,
  5036.              CXTWIN/   FXTWIN/   LXTWIN:  SimTel/win3/pgmtools,   DXTWIN:
  5037.              SimTel/win3/database)
  5038.  
  5039.         -    CICA: ftp.cica.indiana.edu
  5040.              (directory for SXT Windows versions: pub/pc/win3/programr)
  5041.  
  5042.         -    GARBO: garbo.uwasa.fi
  5043.              (directories: CXT: pc/c-lang,  DXT/FXT/LXT:  pc/programming,
  5044.              SXT Windows versions: /windows/programming)
  5045.  
  5046.         CD-ROM:
  5047.  
  5048.         -    The C-Users' Group (CUG) Library on CD-ROM
  5049.              (The  C-Users'  Group (CUG),  1601 W.  23rd St.,  Suite 200,
  5050.              Lawrence, KS 66046, U.S.A.)
  5051.  
  5052.         -    CSL-MEGA CD Vol. 6
  5053.              (Computer Solutions  Software  (CSL)  GmbH,  Postfach  1180,
  5054.              D-85561 Grafing, GERMANY)
  5055.  
  5056.         -    Algorithmen fuer C und C++
  5057.              (Addison-Wesley)
  5058.  
  5059.  
  5060.  
  5061.  
  5062.  
  5063.                                      - 83 -
  5064.  
  5065.  
  5066.         There  are also several CD-ROMs available containing the complete
  5067.         collection of files from the SIMTEL,  CICA  and  GARBO  FTP-sites
  5068.         which may also include some or all of the SXT programs.
  5069.  
  5070.  
  5071.  
  5072.                           (THIS DOCUMENT HAS 84 PAGES)
  5073.  
  5074.  
  5075.  
  5076.  
  5077.  
  5078.  
  5079.  
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.  
  5087.  
  5088.  
  5089.  
  5090.  
  5091.  
  5092.  
  5093.  
  5094.  
  5095.  
  5096.  
  5097.  
  5098.  
  5099.  
  5100.  
  5101.  
  5102.  
  5103.  
  5104.  
  5105.  
  5106.  
  5107.  
  5108.  
  5109.  
  5110.  
  5111.  
  5112.  
  5113.  
  5114.  
  5115.  
  5116.  
  5117.  
  5118.  
  5119.  
  5120.  
  5121.  
  5122.  
  5123.  
  5124.                                      - 84 -
  5125.