C.D.Lane

                                                             Revised: July 1984

                                  GRAPHCALLS

GRAPHCALLS  is an extended graphical interface to the Interlisp CALLS function.
It is to CALLS what BROWSER is to SHOW PATHS in MASTERSCOPE.   It  allows  fast
graphing  of  the  calling  hierarchy  of  both  interpreted and compiled code,
whether or not the source is avaliable (see the CALLS function in the Interlisp
manual), allowing examination of both user and system functions.  The functions
do not have to be analyzed by MASTERSCOPE first.

Additionally, buttoning a function on the graph brings up a menu of  operations
that  can  be  done  with  the  function,  such as editing, inspecting, further
graphing etc.

(GRAPHCALLS function filter depth flags format)

Graphs the calling hierarchy of function.  Terminal nodes on the  graph  (those
who  call no other functions or are undefined) are printed in a bold version of
the graph's font indicating that they cannot be graphed further.

The filter argument is a function to apply to the functions when  building  the
graph  to test their eligibility to appear on the graph.  The filter can be any
defined function; the default is not to filter.  Interesting filters are:  

WHEREIS         Limits the tree to only functions the user as  has  loaded  and
                prunes  out  Interlisp  functions  and  SYSLOADed files.  Quite
                useful.

FGETD           Limits the tree to only functions that  are  actually  defined.
                Thus if you are perusing the tree for BITBLT and don't have and
                are  not interested in the color code, FGETD will remove all of
                the undefined color bitmap functions.

EXPRP           Limits the tree to interpreted functions.  Useful for  graphing
                functions in the development stage.

CCODEP          Limits the tree to compiled functions.

NO\             Keeps  low  level functions starting with \ (i.e. \OUTDATE) off
                of the graph.    Useful  for  getting  an  overview  of  system
                functions and when advising system functions (as \'ed functions
                probably should not be advised).

The  calling  hierarchy  is  graphed to depth grandchildren (defaults to 1).  A
depth of 2 would pick up greatgrandchildren etc.

The flags argument can be one or more of:  

INVERT          Sets up a dynamic graph to visually  track  a  running  program
                                       2


                (see Dynamic Graphing below).

COUNT           Sets  up  a  dynamic  graph  to count function calls in running
                program (see Dynamic Graphing below).

EDIT            Passes T to SHOWGRAPH's alloweditflg, allowing editing  of  the
                graph from a right button menu.

TOP             Passes T to SHOWGRAPH's topjustiflyflg.  

The  format  argument  is  passed  on  to LAYOUTGRAPH in GRAPHER and can be any
format specification (eg.  LATTICE, VERTICAL,  FAST,  REVERSE  etc.)    In  the
forest  format multiple instances of a function appear on the graph after every
calling function and a boxed node indicates the function appears  elsewhere  on
the  graph, possibly graphed further.  In the lattice format each function gets
placed on the graph only once (particularly useful for for the Dynamic Graphing
described below), and boxed nodes indicate recursive functions calls.


Graph Menus

The menu that pops up when you left button a function on the graph contains the
following items (NOTE: The subitems are implemented as menu  SUBITEMS  and  are
also avaliable by pressing the middle button over the item.):

?=              Print the arguments to the function, if avaliable.

FNTYP           Print the function's FNTYP.

WHERE           Do a WHEREIS on the function.

EDIT            Calls the editor on the function if avaliable for editing.

TYPEIN          BKSYSBUF's the name of the function into the typein buffer.

BREAK           Applies BREAK to the function. Its subitems are 

                BREAKIN         Breaks  the  function  only in the context of a
                                particular  calling  function.     In   lattice
                                format,  if  the  function  has  more  than one
                                function calling it on the graph, the  user  is
                                prompted  to  indicate  the  caller in which to
                                break the function.

                UNBREAKIN       Undoes BREAKIN.

                UNBREAK         Applies UNBREAK to the function.

                TRACE           Applies TRACE to the function.

                TRACEIN         Traces  the  function  only  when  called  from
                                inside  a  particular  function,  like  BREAKIN
                                       3


                                above.    Use UNBREAKIN to remove the trace, or
                                else UNBREAK on the window menu.

CCODE           Calls INSPECTCODE on the function if it is compiled code.

GRAPH           Calls GRAPHCALLS to make a new graph  starting  with  function,
                inherits the original graph's filter, flags and format.

FRAME           Inspect  the  local, free and global variables of the function.
                These are the last three lists of  the  CALLS  function  placed
                into INSPECT windows.  Its subitems are 

                >FRAME          Like  FRAME but for all of the functions on the
                                sub-tree starting at the selected node and only
                                for FREEVARS and GLOBALVARS.

                <FRAME          Like >FRAME but for all of the functions  above
                                the  function  in  the graph, i.e. the FREEVARS
                                and GLOBALVARS in the function's scope.

Buttoning the graph outside a node give you a menu with these options:  

HardCopy        Does a HARDCOPYW on the window with the graph.

UNBREAK         Does an (UNBREAK), unbreaking all broken functions.

RESET           Resets the counters for the COUNT option and redisplays graph.



Dynamic Graphing

When the INVERT or COUNT flags are given, GRAPHCALLS will  advise  all  of  the
functions  on  the  graph  (in  the  context  of  their parent) to invert their
corresponding node on the graph (as well as delay some to allow it to be  seen)
and/or  follow each function name by a count of the number of times it has been
executed.  In invert mode, a node remains inverted as long as control is inside
its corresponding function and it  returns  to  normal  when  the  function  is
exited.  The lattice format is best when using the invert feature.  Closing the
graph window UNADVISEs the functions on the graph.

A  simple  example  of  this  is  (GRAPHCALLS  'DATE  NIL NIL 'INVERT) and then
evaluate (DATE).

GRAPHCALLS will not graph or advise any function in the list  NOADVISEFNS  when
an  advise  flag is used.  Functions which are unsafe to advise should be added
to this list.

CAVEAT PROGRAMMER! This feature must be used with caution.    As  a  rule,  one
should  not  do  this  to system (Interlisp) functions, but only one's own, use
WHEREIS as a filter for this.    Advising  system  code  indiscriminately  will
probably crash the machine unrecoverablely.
                                       4


You  can,  at  some  risk, interactively BREAK and EDIT etc.  a function on the
graph while the code is executing.  Also, creating subgraphs of advised  graphs
will  show the generated advice functions not the original functions called, as
will creating new graphs of functions  in  advised  graphs.    You  can  create
advised graphs of functions already graphed normally on the screen.


Command Window

The  function  (GRAPHCALLSW)  puts  up  a  command  window with menus that will
interactively set up calls to GRAPHCALLS.  The menus let you  set  the  Invert,
Count  and Edit flags as well as select from common filters and formats as well
as set the depth of the graph.  You can also change the amount of delay used in
the advised functions when doing Dynamic Graphing.  If you specify  an  advised
graph  (Invert  or Count) and don't specify a WHEREIS filter, you will be asked
to confirm with the mouse for your own protection.

More than one item on the filter and flags menus can be  selected  at  a  time.
Buttoning a selected item on these menus unselects it.

The command menu contains the following:  

Function        Sets the current function which the command graphs by prompting
                for a name in the prompt window.

Include         Adds  files  or  functions to the list of items to allow on the
                graph, see the Include/Exclude algorithm below.

Exclude         Adds files of functions to the list of items disallowed on  the
                graph, see the Include/Exclude algorithm below.

Clear           Clears  all  of  the  settings  on  the  command  window to the
                defaults.  Also clears the Include/Exclude lists.

GRAPH           Graphs the function by calling  GRAPHCALLS  with  the  selected
                options.  

Include  and Exclude allow fine tuning of the filter function.  If the function
passes the filter, then the following are tried until one determines whether or
not the function will be on the graph

   1. If a set of functions has been explicitly excluded, and the function
      is a member of this set, it will NOT appear on the graph.

   2. If a set of functions has been explicitly included, and the function
      is a member of this set, it WILL appear on the graph.

   3. If a set of files has been explicitly excluded, and the function  is
      in one of those files, it will NOT appear on the graph.

   4. If  a set of files has been explicitly included, and the function is
      not in one of those files, it will NOT appear on the graph.
                                       5


   5. The function WILL appear on the graph.

When  the  command  window  is  open, middle buttoning a node on any GRAPHCALLS
graph will bring up a menu of commands relating to command window  and  graphs.
The menu contains:  

EXCLUDE         Adds  the function to the exclude functions list of the command
                window.  This is the only way to exclude system functions which
                get added to the SYSTEM file exclusion list.  

The command window can also be obtained via the background menu.


Notes:

Function call graphs are constructed using breadth  first  search  but  GRAPHER
lays  out  graphs  using a depth first approach so that in some cases functions
are expanded in a different place on the graph than one would expect.

GRAPHCALLS sysloads GRAPHER if it is not already loaded.

In  dynamic  graphs,  variables  caused  by  advising  show  up  in  the  frame
inspections.

Subgraphs  made  from  graphs  created from the Command Window will inherit the
current graph filter, which may be for a completely different context.

The font for the graph (initially GACHA 8) can be changed by setting the global
CALLSFONT.

The delay in advised graphs can be changed by setting CALLSDELAY which is reset
by the command window when using the delay menu.