 Routine Analyzer: User's Guide       Digital Internal Use Only   5 Current Version Of This Document: V0.1-00 03-FEB-1995  (Incomplete)       Contents  /    Introduction: What Is The Routine Analyzer?         Reports        How It Works         Supported Languages        Output Formats  "    Analyzing Software Source Code "       The Product Definition File #       The Language Definition File         The Options File         Performing The Analysis        Interpreting The Results  #          Source Files Alphabetical  "          Defined Routines By File '          Defined Routines Alphabetical  (          External Routines Alphabetical -          Caller Cross Reference Alphabetical            Annotated Source Code      Options Reference  #    Quick Tips On Mosaic Navigation  "    Known Problems and Limitations    Sample Routine Analysis   C A sample routine analysis exists. This is the output of the Routine & Analyzer run over its own source code.      + Introduction: What Is The Routine Analyzer?     H The Routine Analyzer is a static software source code analyzer. It readsI software source code, analyzing the routine call structure, and generates G reports and annotated source listings showing the analysis results. The I purpose is to help software engineers learn and navigate the structure of I large software products. It also provides statistics that can be used for . project planning and gauging software metrics.  C The basic problem the Routine Analyzer is trying to solve is how to D assimilate a large software product that may consist of dozens, evenF hundreds of source files, and hundreds of thousands of lines of sourceC code. Where to begin? Where to go? How to identify the relationship J between routines, such that an engineer can enhance or correct the product! without introducing new problems?   D The Routine Analyzer is just one of the tools an engineer can use inH working on a large software project. Several other tools provide similarF capabilities, such as Source Code Analyzer under VMS, and cscope underE Unix. Tools such as cross-reference utilities and compiler and linker K listings provide additional information. Each tool has its own benefits and H limitations. The Routine Analyzer is intended to supplement other tools, not replace them.   6 The Routine Analyzer runs under VMS, Unix, and MS-DOS.   Reports   C The Routine Analyzer produces the following reports from a software  product's source code:  %    Alphabetical list of source files  0    List of routines defined in each source file -    Alphabetical list of all routines defined  9    Alphabetical list of all external routines referenced  <    A complete set of caller cross-references and call trees     Annotated source code    I A major feature of the analyzer is that these reports can be generated in H several different formats, suitable for hardcopy documentation or onlineG browsing. The online formats are especially useful because they provide F hypertext links to allow quick navigation through the information, forJ instance traversing a call tree and viewing the source code for particularM routines. Each report includes various statistics about the size of files and K routines, the number of times called, etc. See Interpreting The Results for B detailed descriptions of each of the reports. For HTML output, theM alphabetical list of source files acts as the home page for the entire set of L reports; it contains a table of contents with hypertext links as well as the
 file list.   How It Works  F The analysis process is very analogous to a software build, in which aM build utility identifies the source file to compile, compiles them, and links H them to form the product image. The analyzer reads a list of source fileI locations from a product definition file, analyzes them, and produces the K reports. It works in two phases, an analysis phase, and a report generation  phase.  K During the analysis phase, the analyzer identifies the source language of a I file based on the file type or extension, matching the type to known file O types or to special types listed in a language definition file. It then selects F a parser for that language and parses the contents of the source file,K similar to the way a compiler parses a source file (note, however, that the E parsers used here are much simpler than true compiler front ends, and G ignore many details that are important to a compiler). The parser notes M each routine definition (i.e. the actual routine contents) and each call to a G routine that it encounters in the source code, building cross-reference - information and maintaining various counters.   L When it has parsed the contents of all the source files, the analyzer entersN the report generation phase. First, it formats the lists of files and routinesN it has built. Then it trims duplicate references and identifies recursion, andD formats the cross references and call trees. Finally, it formats the annotated source listings.  E The analyzer supports mixed-language programming since it selects the I appropriate parser on a file-by-file basis (though it does not recognized I mixed languages within a single file). It permits multiple definitions of F the same routine, for example to provide alternate implementations forL different operating systems. It can also be used on partial code sets, where1 a compile or link might fail due to missing code.    Supported Languages   F Currently, the analyzer supports three source languages: C, BLISS, andF text. C and BLISS are the primary high-level languages used in currentI and existing Digital products. The text language is actually just a dummy K parser that accepts all input without looking for routines, and can be used G to capture files containing text or unsupported source languages in the  analysis reports.   A Future language support under consideration is for C++, PERL, and @ several assembly languages. Assembly languages present a specialK challenge in that the bounds of a routine definition are not as clear as in  high-level languages.    Report Formats  B Currently, the analyzer produces reports in two formats: SDML, andA HTML. SDML (Standard Digital Markup Language) is the input format > for VAX Document, which can produce ASCII text, PostScript, or? Bookreader output. This format is especially suited to hardcopy @ documentation when producing PostScript output. HTML (Hyper Text@ Markup Language) is the input format for World-Wide Web browsersJ such as Mosaic. This format is especially suited to online browsing, sinceJ it includes hypertext links between related items in the reports for quick navigation.   A SDML reports are created in a small set of files that can be used K standalone or included in other documents, either together or individually. C HTML reports are created in a somewhat larger set of files that are J optimized for quick browsing, and are intended to be used as an integrated set.  E Future report formats under consideration are for ASCII text, Windows 3 Rich Text Format (RTF), Windows Help, and VMS Help.        Analyzing Software Source Code    C Analyzing source code with the Routine Analyzer is very simple. One L control file, the product definition file, is required. Two other files, theM language definition file and the options file, are optional. The analysis and M report generation phases run quickly in a single pass, slightly faster than a  compiler producing object code.    The Product Definition File   M The Product Definition File is a required text listing the source files to be O analyzed. The first line of the file is the product identification line. It can L contain any text, which will be used to identify the product in the reports.D Each remaining line contains one source file pathname. The pathnamesG may be complete, absolute pathnames, or they may be relative pathnames. I Relative pathnames are relative to the current working directory when the K analyzer is run. Wildcards are not permitted, and Unix shell abbreviations, G such as "~" for the user's home directory, are not recognized. Remember < that Unix filenames are case-sensitive, while VMS and MS-DOS filenames are not.  D For example, the following are product definition files for Unix andD VMS. They are for a hypothetical mail utility that uses an X WindowsN interface. In both cases, the source files are in several subdirectories under? a master source directory, from which the analyzer will be run:r  +          Unix:                         VMS:   2    % cat myxmail.prd            $ type myxmail.prd5    X Windows Mail System        X Windows Mail Systemi1    send/finduser.c              [.send]finduser.cl1    send/sendmail.c              [.send]sendmail.cf/    rcv/getmail.c                [.rcv]getmail.co0    rcv/showmail.c               [.rcv]showmail.c1    file/savemail.c              [.file]savemail.c 3    file/importmail.c            [.file]importmail.ci1    file/movemail.c              [.file]movemail.cp2    gui/mainwindow.c             [.gui]mainwindow.c2    gui/sendwindow.c             [.gui]sendwindow.c1    gui/rcvwindow.c              [.gui]rcvwindow.ch   The Language Definition File  L The Language Definition File is an optional text file listing file types andF languages. This may be used to inform the analyzer which parser to useG for unknown file types, or to override the default language for a known H file type. Each line is a language definition of the form type=language,I where type is a file type (excluding the leading period), and language is > one of the keywords "C", "BLISS", or "TEXT". Trailing comments following "!" are permitted.  G For example, the following is a language definition file valid for bothn? Unix and VMS. It shows the default file types for the supportedhD languages, plus one definition for an unsupported assembly language.F However, note that it is not necessary to include the default languageM definitions, and if all files listed in the product definition file are typesnC known to the analyzer, a language definition file is not necessary.n      % cat myxmail.lngB    ! The following are the default file type/language definitions.    !'    c=c         ! .c file type is C codex'    h=c         ! .h file type is C code -    bli=bliss   ! .bli file type is BLISS codet-    req=bliss   ! .req file type is BLISS codet-    r32=bliss   ! .r32 file type is BLISS codet-    dat=text    ! .dat file type is plain texth-    txt=text    ! .txt file type is plain texti    !4    ! The following is a custom C language file type.    !)    myc=c       ! .myc file type is C code     !C    ! The following tell the analyzer to treat assembly language and A    ! options files as plain text so that they will be included indD    ! the annotated source output, even though the analyzer is unable    ! to parse them.c    !6    asm=text    ! Treat assembly language as plain text1    opt=text    ! Treat options file as plain texts   The Options File  I The Options File is a text file containing analyzer command line options. D This may be used to save a set of options in one place for later useJ re-analyzing newer versions of the product. Each line of the file containsF one option (see Options Reference for descriptions of the command line8 options). Trailing comments following "!" are permitted.  H For example, the following are options files for Unix and VMS. Note thatF the option switch character for Unix and MS-DOS is "-", and for VMS is "/". s  +          Unix:                         VMS:u  2    % cat myxmail.opt            $ type myxmail.opt,    -format=html                 /format=html@    -outprefix=/devdocs/xmail_   /outprefix=dev$docs:xmail_      1    -lang=myxmail.lng            /lang=myxmail.lngb   Performing The Analysisl  > Assuming that a foreign command RANALYZER has been defined forA the program file (on VMS) or the program file ranalyzer is in theu= command path (Unix and MS-DOS), the analyzer command line is:e  /    ranalyzer product_definition_file  [options]e  O where product_definition_file is the product definition file, and [options] are,K any desired command options (see Options Reference for descriptions of the p command line options).  L All relative file pathnames in the product definition file are assumed to beE relative to the current directory from which the analyzer is run. AlloK reports are created in the current directory, unless the "outprefix" optioneI is used with a pathname. The reports use fixed filenames, as shown in themA following table; the "outprefix" option may be used to specify an ! additional prefix to these names:r  : Report                  File name       Continuation files: ----------------------  --------------  ------------------ Source file list:       filesm0 Routines by file list:  byfile          byfxxxxx Defined routines:       definedt  External routines:      undefind0 Cross references:       xref            xrfxxxxx  Annotated source code:  srcxxxxx  E where xxxxx is a decimal sequence number. The file type is ".sdml" or,: ".html" for Unix and VMS, and ".sdm" or ".htm" for MS-DOS.B Annotated source code is reported one report file per source file.I Continuation files are used only for HTML output. These are used to spliti@ large reports into smaller, more manageable HTML files to ensureB responsiveness while browsing (see the "htmlbyfile" and "htmlxref"5 options for changing the size of continuation files).o  I Progress messages are written to standard output. The "brief" or "silent",F options may be used to reduce the volume of messages. The "log" optionE may be used to redirect messages. For example, the following commandsCA run the analyzer under Unix and VMS. they will create HTML formatsJ reports, in the directory /devdoc (Unix) or dev$doc: (VMS); the additional@ prefix "myxmail_" will be prepended to the fixed file names. TheE analyzer program file is assumed to be /tools/bin/ranalyzer (Unix) orp sys$tools:ranalyzer.exe (VMS). n   Unix:p  #    % setenv PATH ${PATH}:/tools/bin C    % ranalyzer myxmail.prd -format=html -outprefix=/devdoc/myxmail_e      .      .      .    % ls /devdoc/myxmail_* @    /devdoc/myxmail_byfile.html     /devdoc/myxmail_src00006.html@    /devdoc/myxmail_defined.html    /devdoc/myxmail_src00007.html@    /devdoc/myxmail_files.html      /devdoc/myxmail_src00008.html@    /devdoc/myxmail_src00001.html   /devdoc/myxmail_src00009.html@    /devdoc/myxmail_src00002.html   /devdoc/myxmail_src00010.html@    /devdoc/myxmail_src00003.html   /devdoc/myxmail_undefind.html<    /devdoc/myxmail_src00004.html   /devdoc/myxmail_xref.html     /devdoc/myxmail_src00005.html     VMS:  ,    $ ranalyzer :== $ sys$tools:ranalyzer.exeC    $ ranalyzer myxmail.prd /format=html /outprefix=dev$doc:myxmail_e      .
      .          .    $ dir dev$doc:myxmail_*      Directory DEV$DSK:[DOC]  3    MYXMAIL_BYFILE.HTML;1     MYXMAIL_DEFINED.HTML;1i4    MYXMAIL_FILES.HTML;1      MYXMAIL_SRC00001.HTML;14    MYXMAIL_SRC00002.HTML;1   MYXMAIL_SRC00003.HTML;14    MYXMAIL_SRC00004.HTML;1   MYXMAIL_SRC00005.HTML;14    MYXMAIL_SRC00006.HTML;1   MYXMAIL_SRC00007.HTML;14    MYXMAIL_SRC00008.HTML;1   MYXMAIL_SRC00009.HTML;14    MYXMAIL_SRC00010.HTML;1   MYXMAIL_UNDEFIND.HTML;1    MYXMAIL_XREF.HTML;1      Total of 15 files.    Interpreting The Results  H With the exception of the annotated source code, the reports produced byK the analyzer consist of tables and figures. They are organized primarily ineG alphabetical order for quick reference. The HTML format reports containrE many hypertext links to facilitate rapid automatic navigation betweeng related information.  M The best way to use the reports is to start with either the alphabetical listgE of source files or the alphabetical list of defined routines. In HTMLrJ format, the list of source files acts as the home page for the report set.? From these you can go to the source code or the cross references; information, rapidly traversing the code paths of interest.s  H The reports have the same general appearance regardless of actual outputI format, using the formatting directives available. For instance, SDML hascE formatting directives that directly support multi-column tables. HTML E does not; instead, tables are formed from pre-formatted text. All thee= samples below are taken from HTML-formatted reports, based onoJ analysis of the analyzer's own source code; hypertext links are not shown, but are described in the text. m   Source Files Alphabeticaln  N The alphabetical list of source files report shows high level statistics about< the source code. The following is a sample source file list:  O -------------------------------------------------------------------------------   N                                 +- Link to annotated source code for the file.                                 /L                               /                       +- Link to routines byK Source Files                 /                       /   file for the file.c5                             v                       vvO ===============================================================================cK                                  Com-    State-   Rou-              Avg   #iO File                      Lines  mented    ment   tines  Length     Len   Calls O -------------------------------------------------------------------------------nO BLIPARSE.C                  739     154     577       5     520     104     102eO CMDOPT.C                    525     290     222       9     473      53      45vO CMDOPT.H                     78      47      33       9       9       1       0nO CPARSER.C                   703     161     526       7     568      81     101gO GLOBDB.H                    259      96     179      99      99       1      18 O LIST.C                      316     168     140       5     281      56      45eO LIST.H                      108      57      39      26      26       1      15oO LISTFILE.C                  330     114     175      11     286      26     125uO OBJALLOC.C                  232     102      98       6     195      33      43iO OBJALLOC.H                   37      26      10       0       0       0       0 O OBJECTS.C                   767     323     372      21     697      33     156lO OBJECTS.H                   283     143     138      63      63       1      26 O PARSER.H                     44      21      20      13      13       1      19 O RANALYZER.C                1199     389     720      23    1124      49     237sO RANALYZER.H                 139      62      69       1       1       1       3aO REPORTS.C                  1741     563    1175     112    1417      13     391 O REPORTS.H                    75      33      45      19      19       1       8 O RPTHTML.C                  1747     539    1024      45    1600      36     507yO RPTSDML.C                   593     204     306      21     528      25     158dO RPTTEXT.C                   404     152     190      15     352      23      82aO -------------------------------------------------------------------------------tO TOTAL:      20 files      10319    3644    6058     510    8271      16    2081eO ===============================================================================a  O -------------------------------------------------------------------------------p   The columns in this table are:  A    File: The name of the source file as it appears in the productnG    definition file (see The Product Definition File for a description).xE    The table entries are sorted by this column. The sort includes any F    pathname information in the file name. If the files are spread overH    multiple directories, all the files in each directory will be grouped
    together. yG    Lines: The total number of lines in the file, including blank lines.i=    In the HTML format, this column is a hypertext link to them'    annotated source code for the file.  ;    Commented: The total number of lines that contain source C    language comments. These lines may consist of only comment text,r4    or both comments and source language statements. D    Statement: The total number of lines that contain source languageB    statements. These lines may consist of only statements, or both?    statements and comments. Since lines containing both will be ?    counted in both the Commented and Statement columns, the sumt5    of these two columns may exceed the Lines column. f@    Routines: The total number of routines defined in the file. A=    routine definition means the body of a routine, not just aeH    declaration of the routine interface. Macros are treated as routines,E    since they are an executable block of code defined separately fromt<    where they are used. In the HTML format, this column is aA    hypertext link to the list of routines by file for this file. oF    Length: The total number of lines contained in routine definitions,A    including blank lines and comments. Lines appearing outside ofeF    routine definitions, such as external declarations, global variable>    declarations, and lines between routines are not included. D    Avg Len: The average length of each routine defined in the file. H    # Calls: The total number of calls to any routines made in the file.   H These values can be used to gauge the overall size and complexity of theK source code, as well as hint at its maintainability. For instance, does the A code have a high proportion of comments, suggesting good internallD documentation, or a low (or non-existent) proportion? Is the averageG routine length large, suggesting very large, complex routines, or is itgE small, suggesting compact, easily-comprehended routines? The relative G complexity of different portions of code may be gauged by comparing theaM values for different files. Note that in interpreting these values, differentnE people will judge them differently, based on their own experience andh skills.r   Defined Routines By File  I The list of defined routines by files report shows, for each source file, Q statistics for the routines in that file. The routines are listed in the order in D which they occur in the file. The following is a sample for the file- containing the analyzer's C language parser: t  F ----------------------------------------------------------------------  D                                  +- Link to annotated source for the,                                 /   routine.F                                /                      +- Link to crossF CPARSER.C Routines            /                      /   reference forE                              v                      v    the routine.07 =======================================================a6                                           #      Times7 Routine                    Line  Length   Calls  Called 7 ------------------------------------------------------- 7 trace_parser                124      17       4       3c7 trace_parser_int            143      22       4       2m7 trace_parser_state          167      22       4       1L7 new_source_line             191      37       5       1M7 iskeyword                   230      24       1       1L7 get_token                   256     260      10       1 7 c_parser                    518     186      13       0X7 -------------------------------------------------------L+ TOTAL:     7 ROUTINES                81 AVG 7 =======================================================t  F ----------------------------------------------------------------------   The columns in this table are:  3    Routine: The routine name as found in the file. sA    Line: The line at which the routine definition started. In thef>    HTML format, this column is a hypertext link to the routine,    definition in the annotated source code. E    Length: The total length of the routine, including blank lines and 
    comments.  D    # Calls: The total number of routine calls made by this routine. C    Times Called: The total number of times this routine was called.mE    A value of 0 may indicate that this routine is not used, or it may E    mean the routine is available for other code, not included in this D    analysis, to call. In the HTML format, this column is a hypertext<    link to the cross reference information for the routine.    Defined Routines Alphabeticalo  J The alphabetical list of defined routines report shows statistics for eachE individual routine. This is the same information shown in the defined L routines by file report, just organized differently. All routines defined inP all of the source files are listed in a single table, in alphabetical order. TheJ following is an abbreviated sample of the analyzer's defined routine list:  H ------------------------------------------------------------------------  D                                           Link to cross reference -+E Defined Routines Alphabetical                     for the routine   \ F                                                                      vH ========================================================================G                                                            #      TimesfH Routine                                     Line  Length   Calls  CalledH ------------------------------------------------------------------------H add_caller - OBJECTS.H                       231       1       1       2H add_def - GLOBDB.H                           244       1       1       1H add_file - GLOBDB.H                          243       1       1       1H add_lang - OBJECTS.H                          99       1       2       6H add_ref - OBJECTS.H                          228       1       1       2H add_srcref - OBJECTS.H                       163       1       1       1H analyze_file - RANALYZER.C                   101     144      41       1H analyze_product - RANALYZER.C                247     114      57       1H append_list_entry - LIST.H                    53       1       2       4H assign_byfilefiles - RPTHTML.C                97      25       6       1H assign_xreffiles - RPTHTML.C                  70      25       7       1H bliss_parser - BLIPARSE.C                    561     178      38       0H block_level_dec - PARSER.H                    41       1       1       4H block_level_inc - PARSER.H                    40       1       1       2H block_level_zero - PARSER.H                   39       1       1       3H byfile_link_prefix - RPTHTML.C               413      29       3       1H byfile_link_suffix - RPTHTML.C                28       1       1       1H c_parser - CPARSER.C                         518     186      43       0   .    .    . H tree_link - RPTHTML.C                        152       1       1       0H tree_size - REPORTS.C                        364      39      11       0H url_prefix - GLOBDB.H                        140       1       0       2H ustrcpy - BLIPARSE.C                         282      25       1       5H ustrncmp - CMDOPT.C                           36      36       4       8H xref_link - RPTHTML.C                        382      29       4       4H xref_link_prefix - RPTHTML.C                 340      40       7       8H xref_link_suffix - RPTHTML.C                  27       1       1       8I -------------------------------------------------------------------------6 TOTAL: 510 routines I ==========================================================================  I --------------------------------------------------------------------------  C    Routine: The routine name, including the file name. If there are:@    multiple definitions for the same routine name, the name willD    appear once for each definition, showing a different file or line    number each time. s;    Line: The line at which the routine definition started. oE    Length: The total length of the routine, including blank lines ande
    comments. eD    # Calls: The total number of routine calls made by this routine. C    Times Called: The total number of times this routine was called.hE    A value of 0 may indicate that this routine is not used, or it mayuE    mean the routine is available for other code, not included in thiscD    analysis, to call. In the HTML format, this column is a hypertext<    link to the cross reference information for the routine.    External Routines Alphabetical  L The alphabetical list of external routines reports shows the routines calledF by the source code which are not defined in the source. These are alsoJ referred to as undefined routines. They generally are defined in source orK object libraries which are included by the source or linked with its objectuD code. They may also be routines which have not yet been written, areL defined in files that were not excluded from the analysis, or are written inJ a language for which the analyzer does not have a parser. The following is1 a sample of the analyzer's external routine list:e  > --------------------------------------------------------------  >                                               +- Link to cross> Undefined Routines Alphabetical              /   reference for=                                             v    the routine.o0 ================================================/                                           Timesn0 Routine                                   Called0 ------------------------------------------------0 atoi                                           30 calloc                                         10 def_treefile                                   40 fclose                                        220 fgetc                                          90 fgets                                          90 fopen                                         170 fprintf                                      1610 fputc                                          30 fputs                                        1470 free                                           10 freopen                                        10 fseek                                          10 isalnum                                        60 isalpha                                        30 isdigit                                        40 isspace                                        60 malloc                                         20 printf                                       1290 puts                                          160 sprintf                                       200 strcat                                         20 strcmp                                         90 strcpy                                        200 strlen                                        290 strncpy                                        10 toupper                                        50 ungetc                                        150 ------------------------------------------------ TOTAL: 28 routines0 ================================================  > --------------------------------------------------------------   The columns in this table are:      Routine: The routine name. C    Times Called: The total number of times this routine was called. C    In the HTML format, this column is a hypertext link to the cross *    reference information for the routine.   # Caller Cross Reference Alphabetical   L The caller cross reference report shows the callers of each routine, and theE call tree for each defined routine. In the HMTL format, the file name N portion of the header line for each entry is a hypertext link to the routine's( definition in the annotated source code.  D The following are example cross reference entries for three routinesI illustrating three different situations. Routine product_name is a simple-K routine (actually a macro) that does not call any others. Routine puts is a:H standard C library routine. Routine remove_lang is a routine with a call tree three routines deep.n  A -----------------------------------------------------------------n  A                      +- Link to annotated source for the routine.n                     /f                    v product_name - GLOBDB.Hm                               8 Callers                       Link to cross reference -+9                                       for the routine   \ L 3 callers                                                v                  <      + list_product_begin - LISTFILE.C                  Goto<      + rpt_html_section_hdr - RPTHTML.C                 Goto<      + rpt_html_section_title - RPTHTML.C               Goto   Call Tree: No callso  A -----------------------------------------------------------------o   puts - External    Callersn  	 7 callersi<      + bliss_parser - BLIPARSE.C                        Goto<      + cmdopt_fmt_kwhandler - RANALYZER.C               Goto<      + main - RANALYZER.C                               Goto<      + new_def - OBJECTS.C                              Goto<      + report_source - REPORTS.C                        Goto<      + report_tree - REPORTS.C                          Goto<      + show_help - RANALYZER.C                          Goto  A -----------------------------------------------------------------n   remove_lang - OBJECTS.H    Callers    1 caller<      + get_parser - RANALYZER.C                         Goto  	 Call Tree=   remove_lang= |   dequeue_entry Goto |   |   remove_list_entry Goto |   |   |   isfirst_entry Goto  |   |   |   +   entry_blink Goto |   |   |   set_list_first Gotod |   |   |   entry_flink Goto  |   |   |   set_entry_flink Goto( |   |   |   entry_blink (Duplicate) Goto |   |   |   islast_entry Goto , |   |   |   +   entry_flink (Duplicate) Goto |   |   |   set_list_last Goto  |   |   |   set_entry_blink Goto! |   |   +   dec_list_entries Goto  |   +   list_first GotoJ +   global_langlist Goto END OF TREE   A -----------------------------------------------------------------    The items in these figures are:-  E    Callers: The list of routines which call this one, including theireD    file names. In the HTML format, the word "Goto" at the end of theG    line is a hypertext link to the cross reference information for thatl    caller. IG    Call Tree: The call tree of routines called by this one. IndentationRC    and "|" markers reflect the call level in the tree. A "+" marker-I    means that the rotuine is the last one called at that level. The wordsAA    "External", "Separate", or "Duplicate" enclosed in parenthesiseH    indicate that the called routine is external, is expanded only in itsK    own separate call tree (not inline in this tree), or is a duplicate call-G    already expanded in this tree. For brevity, a given routine is shownxF    only once at any level of the tree, regardless of how many calls toD    it a routine contains. In the HTML format, the word "Goto" at the=    end of the line is a hypertext link to the cross reference (    information for that called routine.   M Note that a call tree illustrates the general structure and potential flow of H control, but does not show exact execution flow. This is because it doesK not show control structures such as if-then branches or loops. While a call J tree may list several called routines in a row, you cannot assume they areI called in that order, because there may be conditional logic altering the  flow of execution. 4   Annotated Source Codex  @ The annotated source code report shows, for each source file, anM alphabetical index of the routines defined in the file, and the actual source-A code, with line numbers. The begin and end points of each routine5J definition are clearly labeled. The following is an abbreviated example ofF the annotated source code from the analyzer's main module, showing the, beginning and end of the annotated listing:   P --------------------------------------------------------------------------------   RANALYZER.C Source Code   $ Routines In This File (Alphabetical)  
  Line Name
 ----- ----   101 analyze_file   247 analyze_productn  1037 cmdopt_authore    .    .    .    31 get_parser
  1121 main  1052 show_helpe   BEGINNING OF FILEe  V      1: /****************************************************************************/V      2: /*                                                                          */V      3: /*  FACILITY:   Routine Analyzer                                            */V      4: /*                                                                          */V      5: /*  MODULE:     Main Module                                                 */V      6: /*                                                                          */V      7: /*  AUTHOR:     Steve Branam, Network Product Support Group, Digital        */V      8: /*              Equipment Corporation, Littleton, MA, USA.                  */V      9: /*                                                                          */V     10: /*  DESCRIPTION: This is the main module for Routine Analyzer. It contains  */V     11: /*  the main routine, command option handlers, and the main application     */V     12: /*  routines for processing product and source files.                       */V     13: /*                                                                          */V     14: /*  REVISION HISTORY:                                                       */V     15: /*                                                                          */V     16: /*  V0.1-00 24-AUG-1994 Steve Branam                                        */V     17: /*                                                                          */V     18: /*      Original version.                                                   */V     19: /*                                                                          */V     20: /****************************************************************************/     21: V     22: #define MAIN_MODULE                         /* This is the main module.     */     23: #include       24: #include "ranalyzer.h"     25:      26: +     27: extern language_element c_parser(); /     28: extern language_element bliss_parser();      29: V     30: /*************************************************************************++*/     ROUTINE get_parser.        31: PARSER get_parser(V     32: /* Returns the parser function appropriate for the source language, based   */V     33: /* on the file name extension.                                              */     34: !     35:     char    *aSourceName, V     36:             /* (READ, BY ADDR):                                             */V     37:             /* Source file name string.                                     */     38: !     39:     char    **aParserName V     40:             /* (WRITE, BY ADDR):                                            */V     41:             /* Parser name string ptr, set to parser name string.           */     42: V     43: )       /* Returns ptr to parser function.                                  */V     44:         /*****************************************************************--*/     45: 	     46: {=V     47:     KEYWORD_DEFINITION                      /* Current keyword definition.  */     48:             *curkwdef;V     49:     LANGUAGE_TRANSLATION                    /* Current language trans.      */     50:             *curtrans;V     51:     char    *extstr;                        /* File extension ptr.          */     52: -     53:     if (global_langtable() == NULL) { @     54:         set_lang_table(list_entries(global_langlist()));3     55:         for (curkwdef = global_langtable();e7     56:             (curtrans = remove_lang()) != NULL;f!     57:             curkwdef++) {oE     58:             set_kwdef_keyword(curkwdef, lang_fext(curtrans));nL     59:             set_kwdef_minlen(curkwdef, strlen(lang_fext(curtrans)));B     60:             set_kwdef_code(curkwdef, lang_code(curtrans));(     61:             free_lang(curtrans);     62:         } 
     63:     }l     64:      65: V     66:     /*+                                                                     */V     67:     /*  Scan back from end of file name string for file extension. If not   */V     68:     /*  found, can't identify parser. Otherwise, locate end of extension    */V     69:     /*  string and compare it to known file extensions.                     */V     70:     /*-                                                                     */     71: <     72:     for (extstr = &aSourceName[strlen(aSourceName)];G     73:         extstr >= aSourceName && *extstr != FILE_EXT_SEPARATOR;m     74:         extstr--);'     75:     if (extstr < aSourceName) {oX     76:         printf("ERROR: No file extension specified for file %s\n", aSourceName);     77:         return NULL;
     78:     }      79:     else {     80:         extstr++; H     81:         switch (translate_keyword(extstr, global_langtable())) {V     82:         case LANGUAGE_UNKNOWN:              /* No matches on file type.     */     83:             printf(wN     84:             "ERROR: Unable to identify source language for file %s\n",%     85:                 aSourceName);+      86:             return NULL;     87:             break;      88:         case LANGUAGE_C:'     89:             *aParserName = "C";-$     90:             return c_parser;     91:             break;$     92:         case LANGUAGE_BLISS:+     93:             *aParserName = "BLISS"; (     94:             return bliss_parser;     95:             break;     96:         }n
     97:     } 	     98: }s   END get_parser.    .    .n   .l ROUTINE main.   
   1121: main(rV   1122: /* Program main routine.                                                    */   1123:    1124:     int     vArgc,V   1125:             /* (READ, BY VAL):                                              */V   1126:             /* Number of program argument strings in aArgv.                 */   1127:    1128:     char    *aArgv[]V   1129:             /* (READ, BY ADDR):                                             */V   1130:             /* List of program argument strings.                            */   1131: V   1132: )       /* Returns system success code.                                     */V   1133:         /*****************************************************************--*/   1134: 	   1135: {eV   1136:                                             /* Main program command line    */V   1137:                                             /* argument options dispatch    */V   1138:                                             /* table.                       */3   1139:     static KEYWORD_DEFINITION options[] = {a9   1140:         {"options",     3, process_options_file},t1   1141:         {"trace",       3, cmdopt_trace},n4   1142:         {"log",         3, cmdopt_log},     4   1143:         {"list",        3, cmdopt_list},    E   1144:         {"silent",      3, cmdopt_set,  LOG_SILENT_ENABLE},   E   1145:         {"brief",       3, cmdopt_set,  LOG_BRIEF_ENABLE},    5   1146:         {"outprefix",   3, cmdopt_outprefix}, 2   1147:         {"format",      3, cmdopt_format},7   1148:         {"description", 3, cmdopt_description},a@   1149:         {"definition",  3, cmdopt_set,  LOG_DEF_ENABLE},@   1150:         {"reference",   3, cmdopt_set,  LOG_REF_ENABLE},4   1151:         {"separate",    3, cmdopt_separate},4   1152:         {"language",    3, cmdopt_language},E   1153:         {"noinline",    3, cmdopt_set,  TREE_INLINE_DISABLE},r5   1154:         {"urlprefix",   3, cmdopt_urlprefix}, 3   1155:         {"callers",     3, cmdopt_callers},n2   1156:         {"report",      3, cmdopt_report},4   1157:         {"noreport",    3, cmdopt_noreport},6   1158:         {"htmlbyfile",  5, cmdopt_htmlbyfile},4   1159:         {"htmlxref",    5, cmdopt_htmlxref},2   1160:         {"author",      3, cmdopt_author},V   1161:         {NULL,          0, NULL}            /* End of table.                */   1162:     };   1163: V   1164:     /*+                                                                     */V   1165:     /*  Make sure enough reqired arguments were specified, then process the */V   1166:     /*  optional arguments and analyze the product files.                   */V   1167:     /*-                                                                     */   1168:        1169:     if (vArgc < 3) {D   1170:         if (vArgc > 1 && *aArgv[1] == CMDLINE_HELP_SWITCH) {    1171:             show_help();   1172:         }    1173:         else {)   1174:             puts(PROGRAM_PARAMS); '   1175:             puts(PROGRAM_HELP);U   1176:         } 
   1177:     }    1178:     else {V   1179:                                             /* Disable these reports by     */V   1180:                                             /* default.                     */B   1181:         set_option(RPT_CALLS_DISABLE | RPT_TREES_DISABLE);   1182:         1   1183:         set_max_callers(DEF_MAX_CALLERS); 9   1184:         set_max_html_byfile(DEF_MAX_HTML_BYFILE);05   1185:         set_max_html_xref(DEF_MAX_HTML_XREF);A@   1186:         if (process_options(vArgc, aArgv, 2, options)) {8   1187:             add_lang(new_lang("C", LANGUAGE_C));8   1188:             add_lang(new_lang("H", LANGUAGE_C));>   1189:             add_lang(new_lang("BLI", LANGUAGE_BLISS));>   1190:             add_lang(new_lang("REQ", LANGUAGE_BLISS));>   1191:             add_lang(new_lang("R32", LANGUAGE_BLISS));.   1192:             analyze_product(aArgv[1]);)   1193:             if (list_enabled()) { ,   1194:                 fclose(list_file());   1195:             }    1196:         } 
   1197:     } 	   1198: }   
 END main.      1199:    END OF FILE   ! TOTAL: 23 routines, 49 Avg Lengthn  P --------------------------------------------------------------------------------   The columns in this table are:      :      :      :      : /    : 0       Quick Tips On Mosaic Navigation*    G Because Routine Analyzer produces a set of hyperlinked HTML files, hereL? are some quick tips on navigation to help browse them with NCSA G Mosaic, beyong simple scrolling and hyperlink jumps (other browsers may7? or may not have the same capabilities and interface controls): l  ?    Go to end of HTML file: Click mouse button 1 below the thumb*;    in the vertical scroll bar while pressing the CTRL key. T?    Go to beginning of HTML file: Click mouse button 1 above thesA    thumb in the vertical scroll bar while pressing the CTRL key. /A    Go to specific region of HTML file: Click mouse button 2 (or 3 H    on a 3-button mouse) at the relative point in the vertical scroll barD    where you want to go (remember that the scroll bar represents theB    entire length of the file, and the thumb represents the portion<    currently displayed in the view window); the file will be9    positioned to that relative point in the view window.  ?    Follow hyperlink using a new window, leaving original window*@    unchanged: Click mouse button 2 (or 3 on a 3-button mouse) onA    the hyperlink. A new browser window will be created containing A    the linked information; the window you linked from will remain*F    unchanged. This allows you to treat a window as a table of contents7    or map from which you can spawn new windows to otherrD    locations; the hyperlinks in the Routine Analyzer HTML files haveG    been organized to facilitate this usage. Just be careful of creating /    too many windows for your system to handle!        *extstr;                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  