-Routine Analyzer: User's Guide'

Routine Analyzer: User's Guide


"

Digital Internal Use Only

K

Current Version Of This Document: V0.1-00 03-FEB-1995 (Incomplete)




Contents



Sample Routine Analysis

PA sample routine analysis exists. This is the?output of the Routine Analyzer run over its own source code.




<

Introduction: What Is The Routine Analyzer?


HThe Routine Analyzer is a static software source code analyzer. It readsIsoftware source code, analyzing the routine call structure, and generatesOreports and annotated source listings showing the analysis results. The purposePis to help software engineers learn and navigate the structure of large softwareOproducts. It also provides statistics that can be used for project planning andgauging software metrics.

PThe basic problem the Routine Analyzer is trying to solve is how to assimilate aJlarge software product that may consist of dozens, even hundreds of sourceOfiles, and hundreds of thousands of lines of source code. Where to begin? WhereOto go? How to identify the relationship between routines, such that an engineerGcan enhance or correct the product without introducing new problems?

OThe Routine Analyzer is just one of the tools an engineer can use in working onPa large software project. Several other tools provide similar capabilities, suchGas Source Code Analyzer under VMS, and cscope under Unix. Tools such asMcross-reference utilities and compiler and linker listings provide additionalHinformation. Each tool has its own benefits and limitations. The RoutineDAnalyzer is intended to supplement other tools, not replace them.

9The Routine Analyzer runs under VMS, Unix, and MS-DOS.



Reports

MThe Routine Analyzer produces the following reports from a software product'ssource code:



IA major feature of the analyzer is that these reports can be generated inHseveral different formats, suitable for hardcopy documentation or onlineGbrowsing. The online formats are especially useful because they provideOhypertext links to allow quick navigation through the information, for instancePtraversing a call tree and viewing the source code for particular routines. EachLreport includes various statistics about the size of files and routines, the number of times called, etc. SeeMInterpreting The Results for detailedNdescriptions of each of the reports. For HTML output, the alphabetical list ofOsource files acts as the home page for the entire set of reports; it contains aCtable of contents with hypertext links as well as the file list.



How It Works

LThe analysis process is very analogous to a software build, in which a buildOutility identifies the source file to compile, compiles them, and links them toOform the product image. The analyzer reads a list of source file locations fromMa product definition file, analyzes them, and produces the reports. ItIworks in two phases, an analysis phase, and a report generation phase.

PDuring the analysis phase, the analyzer identifies the source language of a filePbased on the file type or extension, matching the type to known file types or toLspecial types listed in a language definition file. It then selects aOparser for that language and parses the contents of the source file, similar toMthe way a compiler parses a source file (note, however, that the parsers usedLhere are much simpler than true compiler front ends, and ignore many detailsKthat are important to a compiler). The parser notes each routine definitionP(i.e. the actual routine contents) and each call to a routine that it encountersPin the source code, building cross-reference information and maintaining various counters.

PWhen it has parsed the contents of all the source files, the analyzer enters theMreport generation phase. First, it formats the lists of files and routines itKhas built. Then it trims duplicate references and identifies recursion, andNformats the cross references and call trees. Finally, it formats the annotatedsource listings.

EThe analyzer supports mixed-language programming since it selects theOappropriate parser on a file-by-file basis (though it does not recognized mixedLlanguages within a single file). It permits multiple definitions of the sameGroutine, for example to provide alternate implementations for differentOoperating systems. It can also be used on partial code sets, where a compile or'link might fail due to missing code.



Supported Languages

NCurrently, the analyzer supports three source languages: C, BLISS, and text. CKand BLISS are the primary high-level languages used in current and existingPDigital products. The text language is actually just a dummy parser that acceptsHall input without looking for routines, and can be used to capture filesKcontaining text or unsupported source languages in the analysis reports.

IFuture language support under consideration is for C++, PERL, and severalNassembly languages. Assembly languages present a special challenge in that theNbounds of a routine definition are not as clear as in high-level languages.



Report Formats

MCurrently, the analyzer produces reports in two formats: SDML, and HTML. SDMLN(Standard Digital Markup Language) is the input format for VAX Document, whichHcan produce ASCII text, PostScript, or Bookreader output. This format isMespecially suited to hardcopy documentation when producing PostScript output.HHTML (Hyper Text Markup Language) is the input format for World-Wide WebMbrowsers such as Mosaic. This format is especially suited to online browsing,Psince it includes hypertext links between related items in the reports for quicknavigation.

OSDML reports are created in a small set of files that can be used standalone orNincluded in other documents, either together or individually. HTML reports areFcreated in a somewhat larger set of files that are optimized for quick>browsing, and are intended to be used as an integrated set.

OFuture report formats under consideration are for ASCII text, Windows Rich Text,Format (RTF), Windows Help, and VMS Help.




/

Analyzing Software Source Code


lKAnalyzing source code with the Routine Analyzer is very simple. One control Mfile, the product definition file, is required. Two other files, the language>Kdefinition file and the options file, are optional. The analysis and report Ogeneration phases run quickly in a single pass, slightly faster than a compilerFproducing object code.

k"(

The Product Definition File

MThe Product Definition File is a required text listing the source files to beiOanalyzed. The first line of the file is the product identification line. It can Lcontain any text, which will be used to identify the product in the reports.KEach remaining line contains one source file pathname. The pathnames may beIcomplete, absolute pathnames, or they may be relative pathnames. RelativeiLpathnames are relative to the current working directory when the analyzer isOrun. Wildcards are not permitted, and Unix shell abbreviations, such as "~" fortOthe user's home directory, are not recognized. Remember that Unix filenames areo:case-sensitive, while VMS and MS-DOS filenames are not.

NFor example, the following are product definition files for Unix and VMS. TheyMare for a hypothetical mail utility that uses an X Windows interface. In both>Kcases, the source files are in several subdirectories under a master source=2directory, from which the analyzer will be run:



E+         Unix:                         VMS:/2   % cat myxmail.prd            $ type myxmail.prd5   X Windows Mail System        X Windows Mail Systeme1   send/finduser.c              [.send]finduser.cr1   send/sendmail.c              [.send]sendmail.c=/   rcv/getmail.c                [.rcv]getmail.co0   rcv/showmail.c               [.rcv]showmail.c1   file/savemail.c              [.file]savemail.ca3   file/importmail.c            [.file]importmail.cs1   file/movemail.c              [.file]movemail.cr2   gui/mainwindow.c             [.gui]mainwindow.c2   gui/sendwindow.c             [.gui]sendwindow.c1   gui/rcvwindow.c              [.gui]rcvwindow.c 
#t)

The Language Definition File

>LThe Language Definition File is an optional text file listing file types andJlanguages. This may be used to inform the analyzer which parser to use forHunknown file types, or to override the default language for a known filePtype. Each line is a language definition of the form type=language, whereNtype is a file type (excluding the leading period), and languageOis one of the keywords "C", "BLISS", or "TEXT". Trailing comments following "!"rare permitted.

oLFor example, the following is a language definition file valid for both UnixNand VMS. It shows the default file types for the supported languages, plus oneMdefinition for an unsupported assembly language. However, note that it is notENnecessary to include the default language definitions, and if all files listedJin the product definition file are types known to the analyzer, a language$definition file is not necessary.



r   % cat myxmail.lngB   ! The following are the default file type/language definitions.   !'   c=c         ! .c file type is C code>'   h=c         ! .h file type is C code-   bli=bliss   ! .bli file type is BLISS codee-   req=bliss   ! .req file type is BLISS code -   r32=bliss   ! .r32 file type is BLISS codes-   dat=text    ! .dat file type is plain texts-   txt=text    ! .txt file type is plain texte   !4   ! The following is a custom C language file type.   !)   myc=c       ! .myc file type is C coden   !C   ! The following tell the analyzer to treat assembly language andiA   ! options files as plain text so that they will be included iniD   ! the annotated source output, even though the analyzer is unable   ! to parse them.e   !6   asm=text    ! Treat assembly language as plain text1   opt=text    ! Treat options file as plain textf
i

The Options File

#NThe Options File is a text file containing analyzer command line options. ThisLmay be used to save a set of options in one place for later use re-analyzingPnewer versions of the product. Each line of the file contains one option (see Options Reference for descriptions of the command line;options). Trailing comments following "!" are permitted.

sZFor example, the following are options files for Unix and VMS. Note that the option switch9character for Unix and MS-DOS is "-", and for VMS is "/".u

 +         Unix:                         VMS:t2   % cat myxmail.opt            $ type myxmail.opt,   -format=html                 /format=html@   -outprefix=/devdocs/xmail_   /outprefix=dev$docs:xmail_      1   -lang=myxmail.lng            /lang=myxmail.lngi
"$

Performing The Analysis

OAssuming that a foreign command RANALYZER has been defined for the program filelP(on VMS) or the program file ranalyzer is in the command path (Unix and MS-DOS), the analyzer command line is:



r.   ranalyzer product_definition_file [options]
Awhere product_definition_file is the product definition file, and 1[options] are any desired command options (see Options Reference for descriptions of the command line options).

LAll relative file pathnames in the product definition file are assumed to beMrelative to the current directory from which the analyzer is run. All reportstPare created in the current directory, unless the "outprefix" option is used withMa pathname. The reports use fixed filenames, as shown in the following table;iKthe "outprefix" option may be used to specify an additional prefix to thesea names:

e

y%Report			File name	Continuation filesi:----------------------  --------------  ------------------Source file list:       filesi(Routines by file list:  byfile		byfxxxxxDefined routines:       definedaExternal routines:	undefind. Cross references:	xref		xrfxxxxx Annotated source code:  srcxxxxx
Mwhere xxxxx is a decimal sequence number. The file type is ".sdml" or ".html"dKfor Unix and VMS, and ".sdm" or ".htm" for MS-DOS. Annotated source code isdNreported one report file per source file. Continuation files are used only forPHTML output. These are used to split large reports into smaller, more manageableLHTML files to ensure responsiveness while browsing (see the "htmlbyfile" andC"htmlxref" options for changing the size of continuation files).

aIProgress messages are written to standard output. The "brief" or "silent"lMoptions may be used to reduce the volume of messages. The "log" option may beused to redirect messages.MFor example, the following commands run the analyzer under Unix and VMS. theylLwill create HTML format reports, in the directory /devdoc (Unix) or dev$doc:K(VMS); the additional prefix "myxmail_" will be prepended to the fixed file"Pnames. The analyzer program file is assumed to be /tools/bin/ranalyzer (Unix) orsys$tools:ranalyzer.exe (VMS).

rUnix:a#   % setenv PATH ${PATH}:/tools/binfC   % ranalyzer myxmail.prd -format=html -outprefix=/devdoc/myxmail_a     .     .     .   % ls /devdoc/myxmail_*r@   /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.htmlVMS:,   $ ranalyzer :== $ sys$tools:ranalyzer.exeC   $ ranalyzer myxmail.prd /format=html /outprefix=dev$doc:myxmail_p     .
     .         .   $ dir dev$doc:myxmail_*   Directory DEV$DSK:[DOC]3   MYXMAIL_BYFILE.HTML;1     MYXMAIL_DEFINED.HTML;1y4   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.e
#t%

Interpreting The Results

iLWith the exception of the annotated source code, the reports produced by theGanalyzer consist of tables and figures. They are organized primarily incLalphabetical order for quick reference. The HTML format reports contain manyHhypertext links to facilitate rapid automatic navigation between relatedinformation.

pPThe best way to use the reports is to start with either the alphabetical list ofNsource files or the alphabetical list of defined routines. In HTML format, theMlist of source files acts as the home page for the report set. From these you Pcan go to the source code or the cross reference information, rapidly traversingthe code paths of interest.

PThe reports have the same general appearance regardless of actual output format,Lusing the formatting directives available. For instance, SDML has formattingMdirectives that directly support multi-column tables. HTML does not; instead,bOtables are formed from pre-formatted text. All the samples below are taken fromnLHTML-formatted reports, based on analysis of the analyzer's own source code;=hypertext links are not shown, but are described in the text. e&

Source Files Alphabetical

NThe alphabetical list of source files report shows high level statistics about?the source code. The following is a sample source file list:



wO------------------------------------------------------------------------------- N                                +- Link to annotated source code for the file.                                /L                              /                       +- Link to routines byKSource Files                 /                       /   file for the file.i5                            v                       vaO===============================================================================dK                                 Com-    State-   Rou-              Avg   #OFile                      Lines  mented    ment   tines  Length     Len   CallsaO-------------------------------------------------------------------------------!The columns in this table are:



    K
  • File: The name of the source file as it appears in theKproduct definition file (see The Product LDefinition File for a description). The table entries are sorted by thisKcolumn. The sort includes any pathname information in the file name. If theaPfiles are spread over multiple directories, all the files in each directory willbe grouped together.L
  • Lines: The total number of lines in the file, includingGblank lines. In the HTML format, this column is a hypertext link to them#annotated source code for the file.lM
  • Commented: The total number of lines that contain source]Hlanguage comments. These lines may consist of only comment text, or both(comments and source language statements.M
  • Statement: The total number of lines that contain sourcemHlanguage statements. These lines may consist of only statements, or bothPstatements and comments. Since lines containing both will be counted in both theLCommented and Statement columns, the sum of these two columns may exceed the Lines column.oP
  • Routines: The total number of routines defined in the file.OA routine definition means the body of a routine, not just a declaration of the Oroutine interface. Macros are treated as routines, since they are an executable-Nblock of code defined separately from where they are used. In the HTML format,Nthis column is a hypertext link to the list of routines by file for this file.K
  • Length: The total number of lines contained in routinedKdefinitions, including blank lines and comments. Lines appearing outside ofpCroutine definitions, such as external declarations, global variableM:declarations, and lines between routines are not included.O
  • Avg Len: The average length of each routine defined in theofile. O
  • # Calls: The total number of calls to any routines made inl the file.(
OThese values can be used to gauge the overall size and complexity of the sourcepPcode, as well as hint at its maintainability. For instance, does the code have aMhigh proportion of comments, suggesting good internal documentation, or a lowM(or non-existent) proportion? Is the average routine length large, suggestingzAvery large, complex routines, or is it small, suggesting compact,hNeasily-comprehended routines? The relative complexity of different portions ofLcode may be gauged by comparing the values for different files. Note that inNinterpreting these values, different people will judge them differently, based&on their own experience and skills.

x%

Defined Routines By File

cIThe list of defined routines by files report shows, for each source file,xNstatistics for the routines in that file. The routines are listed in the orderGin which they occur in the file. The following is a sample for the file/,containing the analyzer's C language parser:
0F----------------------------------------------------------------------D                                 +- Link to annotated source for the,                                /   routine.F                               /                      +- Link to crossFCPARSER.C Routines            /                      /   reference forE                             v                      v    the routine. 7=======================================================o6                                          #      Times7Routine                    Line  Length   Calls  CalledC7-------------------------------------------------------07trace_parser                124      17       4       3T7trace_parser_int            143      22       4       217trace_parser_state          167      22       4       1 7new_source_line             191      37       5       1X7iskeyword                   230      24       1       1A7get_token                   256     260      10       1R7c_parser                    518     186      13       0o7-------------------------------------------------------o+TOTAL:     7 ROUTINES                81 AVGa7=======================================================LF----------------------------------------------------------------------
!The columns in this table are:



    D
  • Routine: The routine name as found in the file.L
  • Line: The line at which the routine definition started.PIn the HTML format, this column is a hypertext link to the routine definition inthe annotated source code.M
  • Length: The total length of the routine, including blankelines and comments. L
  • # Calls: The total number of routine calls made by thisroutine.M
  • Times Called: The total number of times this routine wasyOcalled. A value of 0 may indicate that this routine is not used, or it may meanePthe routine is available for other code, not included in this analysis, to call.JIn the HTML format, this column is a hypertext link to the cross referenceinformation for the routine.
h*

Defined Routines Alphabetical

JThe alphabetical list of defined routines report shows statistics for eachNindividual routine. This is the same information shown in the defined routinesNby file report, just organized differently. All routines defined in all of theOsource files are listed in a single table, in alphabetical order. The following Cis an abbreviated sample of the analyzer's defined routine list:



 H------------------------------------------------------------------------D                                          Link to cross reference -+EDefined Routines Alphabetical                     for the routine   \=F                                                                     vH========================================================================G                                                           #      Times-HRoutine                                     Line  Length   Calls  CalledH------------------------------------------------------------------------Hadd_caller - OBJECTS.H                       231       1       1       2Hadd_def - GLOBDB.H                           244       1       1       1Hadd_file - GLOBDB.H                          243       1       1       1Hadd_lang - OBJECTS.H                          99       1       2       6Hadd_ref - OBJECTS.H                          228       1       1       2Hadd_srcref - OBJECTS.H                       163       1       1       1Hanalyze_file - RANALYZER.C                   101     144      41       1Hanalyze_product - RANALYZER.C                247     114      57       1Happend_list_entry - LIST.H                    53       1       2       4Hassign_byfilefiles - RPTHTML.C                97      25       6       1Hassign_xreffiles - RPTHTML.C                  70      25       7       1Hbliss_parser - BLIPARSE.C                    561     178      38       0Hblock_level_dec - PARSER.H                    41       1       1       4Hblock_level_inc - PARSER.H                    40       1       1       2Hblock_level_zero - PARSER.H                   39       1       1       3Hbyfile_link_prefix - RPTHTML.C               413      29       3       1Hbyfile_link_suffix - RPTHTML.C                28       1       1       1Hc_parser - CPARSER.C                         518     186      43       0  .1  .   . Htree_link - RPTHTML.C                        152       1       1       0Htree_size - REPORTS.C                        364      39      11       0Hurl_prefix - GLOBDB.H                        140       1       0       2Hustrcpy - BLIPARSE.C                         282      25       1       5Hustrncmp - CMDOPT.C                           36      36       4       8Hxref_link - RPTHTML.C                        382      29       4       4Hxref_link_prefix - RPTHTML.C                 340      40       7       8Hxref_link_suffix - RPTHTML.C                  27       1       1       8I-------------------------------------------------------------------------iTOTAL: 510 routines"I=========================================================================oI-------------------------------------------------------------------------a

    K
  • Routine: The routine name, including the file name. If Nthere are multiple definitions for the same routine name, the name will appearLonce for each definition, showing a different file or line number each time.L
  • Line: The line at which the routine definition started.M
  • Length: The total length of the routine, including blankulines and comments.tL
  • # Calls: The total number of routine calls made by thisroutine.M
  • Times Called: The total number of times this routine wasnOcalled. A value of 0 may indicate that this routine is not used, or it may meanhPthe routine is available for other code, not included in this analysis, to call.JIn the HTML format, this column is a hypertext link to the cross referenceinformation for the routine.
t+

External Routines Alphabetical

OThe alphabetical list of external routines reports shows the routines called bynOthe source code which are not defined in the source. These are also referred tocOas undefined routines. They generally are defined in source or object libraries Nwhich are included by the source or linked with its object code. They may alsoFbe routines which have not yet been written, are defined in files thatOwere not excluded from the analysis, or are written in a language for which the Lanalyzer does not have a parser. The following is a sample of the analyzer'sexternal routine list:

e

u>-------------------------------------------------------------->                                              +- Link to cross>Undefined Routines Alphabetical              /   reference for=                                            v    the routine.d0================================================/                                          Timesd0Routine                                   Called0------------------------------------------------0atoi                                           30calloc                                         10def_treefile                                   40fclose                                        220fgetc                                          90fgets                                          90fopen                                         170fprintf                                      1610fputc                                          30fputs                                        1470free                                           10freopen                                        10fseek                                          10isalnum                                        60isalpha                                        30isdigit                                        40isspace                                        60malloc                                         20printf                                       1290puts                                          160sprintf                                       200strcat                                         20strcmp                                         90strcpy                                        200strlen                                        290strncpy                                        10toupper                                        50ungetc                                        150------------------------------------------------TOTAL: 28 routines0================================================>--------------------------------------------------------------
!The columns in this table are:



    /
  • Routine: The routine name. M
  • Times Called: The total number of times this routine was Hcalled. In the HTML format, this column is a hypertext link to the cross&reference information for the routine.
0

Caller Cross Reference Alphabetical

LThe caller cross reference report shows the callers of each routine, and thePcall tree for each defined routine. In the HMTL format, the file name portion ofNthe header line for each entry is a hypertext link to the routine's definition in the annotated source code.

DThe following are example cross reference entries for three routines0illustrating three different situations. RoutineMproduct_name is a simple routine (actually a macro) that does not calleHany others. Routine puts is a standard C library routine. Routine?remove_lang is a routine with a call tree three routinesddeep.



lA-----------------------------------------------------------------tA                     +- Link to annotated source for the routine.l                    /t                   vproduct_name - GLOBDB.HM                              8Callers                       Link to cross reference -+9                                      for the routine   \oL3 callers                                                v                  <     + list_product_begin - LISTFILE.C                  Goto<     + rpt_html_section_hdr - RPTHTML.C                 Goto<     + rpt_html_section_title - RPTHTML.C               GotoCall Tree: No callssA-----------------------------------------------------------------bputs - External Callersr	7 callersu<     + 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                          GotoA----------------------------------------------------------------- remove_lang - OBJECTS.HaCallers-1 caller<     + get_parser - RANALYZER.C                         Goto	Call TreeSremove_lang |   dequeue_entry Goto|   |   remove_list_entry Goto|   |   |   isfirst_entry Goto |   |   |   +   entry_blink Goto|   |   |   set_list_first Goto |   |   |   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 Goto +   global_langlist GotoEND OF TREEEA-----------------------------------------------------------------I
"The items in these figures are:



    G
  • Callers: The list of routines which call this one,sMincluding their file names. In the HTML format, the word "Goto" at the end ofaPthe line is a hypertext link to the cross reference information for that caller.M
  • Call Tree: The call tree of routines called by this one.RLIndentation and "|" markers reflect the call level in the tree. A "+" markerFmeans that the rotuine is the last one called at that level. The wordsP"External", "Separate", or "Duplicate" enclosed in parenthesis indicate that theOcalled routine is external, is expanded only in its own separate call tree (not Oinline in this tree), or is a duplicate call already expanded in this tree. For Pbrevity, a given routine is shown only once at any level of the tree, regardlessOof how many calls to it a routine contains. In the HTML format, the word "Goto"0Mat the end of the line is a hypertext link to the cross reference information for that called routine.
DLNote that a call tree illustrates the general structure and potentialOflow of control, but does not show exact execution flow. This is becauseCNit does not show control structures such as if-then branches or loops. While aOcall tree may list several called routines in a row, you cannot assume they are-Ncalled in that order, because there may be conditional logic altering the flow of execution.="

Annotated Source Code

MThe annotated source code report shows, for each source file, an alphabeticaloFindex of the routines defined in the file, and the actual source code,Jwith line numbers. The begin and end points of each routine definition arePclearly labeled. The following is an abbreviated example of the annotated sourceJcode from the analyzer's main module, showing the beginning and end of theannotated listing:
eP--------------------------------------------------------------------------------RANALYZER.C Source Codea$Routines In This File (Alphabetical)
 Line Name
----- ----  101 analyze_file  247 analyze_productm 1037 cmdopt_author   .   .   .   31 get_parser
 1121 main 1052 show_helpoBEGINNING OF FILEoV     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: {SV    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) {e@    54:         set_lang_table(list_entries(global_langlist()));3    55:         for (curkwdef = global_langtable();i7    56:             (curtrans = remove_lang()) != NULL; !    57:             curkwdef++) { E    58:             set_kwdef_keyword(curkwdef, lang_fext(curtrans));iL    59:             set_kwdef_minlen(curkwdef, strlen(lang_fext(curtrans)));B    60:             set_kwdef_code(curkwdef, lang_code(curtrans));(    61:             free_lang(curtrans);    62:         }r
    63:     }<    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;     74:         extstr--);'    75:     if (extstr < aSourceName) {-X    76:         printf("ERROR: No file extension specified for file %s\n", aSourceName);    77:         return NULL;
    78:     }     79:     else {    80:         extstr++;wH    81:         switch (translate_keyword(extstr, global_langtable())) {V    82:         case LANGUAGE_UNKNOWN:              /* No matches on file type.     */    83:             printf(PN    84:             "ERROR: Unable to identify source language for file %s\n",%    85:                 aSourceName);N     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";e(    94:             return bliss_parser;    95:             break;    96:         } 
    97:     }i	    98: }tEND get_parser.   .n  .o  . ROUTINE main. 
  1121: main( V  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: {V  1136:                                             /* Main program command line    */V  1137:                                             /* argument options dispatch    */V  1138:                                             /* table.                       */3  1139:     static KEYWORD_DEFINITION options[] = {i9  1140:         {"options",     3, process_options_file},n1  1141:         {"trace",       3, cmdopt_trace}, 4  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},   t5  1146:         {"outprefix",   3, cmdopt_outprefix},i2  1147:         {"format",      3, cmdopt_format},7  1148:         {"description", 3, cmdopt_description}, @  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},h5  1154:         {"urlprefix",   3, cmdopt_urlprefix},i3  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);   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);E5  1185:         set_max_html_xref(DEF_MAX_HTML_XREF);.@  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 LengthiP--------------------------------------------------------------------------------
!The columns in this table are:



    
  • :
  • :
  • :
  • :
  • :

s,

Quick Tips On Mosaic Navigation


PBecause Routine Analyzer produces a set of hyperlinked HTML files, here are someLquick tips on navigation to help browse them with NCSA Mosaic, beyong simpleJscrolling and hyperlink jumps (other browsers may or may not have the same%capabilities and interface controls): 
    a
  • Go to end of HTML file: Click mouse button 1 below the thumb in the vertical 'scroll bar while pressing the CTRL key.x^
  • Go to beginning of HTML file: Click mouse button 1 above the thumb in the0vertical scroll bar while pressing the CTRL key.X
  • Go to specific region of HTML file: Click mouse button 2 (or 3 on aP3-button mouse) at the relative point in the vertical scroll bar where you wantMto go (remember that the scroll bar represents the entire length of the file, Mand the thumb represents the portion currently displayed in the view window);tFthe file will be positioned to that relative point in the view window.H
  • Follow hyperlink using a new window, leaving original windowJunchanged: Click mouse button 2 (or 3 on a 3-button mouse) on theEhyperlink. A new browser window will be created containing the linkedoNinformation; the window you linked from will remain unchanged. This allows youLto treat a window as a table of contents or map from which you can spawn newMwindows to other locations; the hyperlinks in the Routine Analyzer HTML filessMhave been organized to facilitate this usage. Just be careful of creating too'many windows for your system to handle!e
l