@style(spread +1 line)
@flushright(C.D.Lane)
@flushright(Revised: July 1984)

@b(@center[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 @p(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 @p(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.


(@b[GRAPHCALLS] @i[function filter depth flags format])

Graphs the calling hierarchy of @i(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 @i(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:
@description{

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

@b(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.

@b(EXPRP) @\Limits the tree to interpreted functions.  Useful for
graphing functions in the development stage.

@b(CCODEP) @\Limits the tree to compiled functions.

@b(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 @i(depth) grandchildren (defaults
to 1).  A @i(depth) of 2 would pick up greatgrandchildren etc.

The flags argument can be one or more of:
@description{

@b(INVERT) @\Sets up a dynamic graph to visually track a running program
(see Dynamic Graphing below).

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

@b(EDIT) @\Passes T to SHOWGRAPH's @i(alloweditflg), allowing editing
of the graph from a right button menu.

@b(TOP) @\Passes T to SHOWGRAPH's @i(topjustiflyflg).
}

The @i(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.

@blankspace(1 line)
@flushleft(@b[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.):

@description{

@b(?=) @\Print the arguments to the function, if avaliable.

@b(FNTYP) @\Print the function's FNTYP.

@b(WHERE) @\Do a WHEREIS on the function.

@b(EDIT) @\Calls the editor on the function if avaliable for editing.

@b(TYPEIN) @\BKSYSBUF's the name of the function into the typein buffer.

@b(BREAK) @\Applies BREAK to the function. Its subitems are
@description[

@b(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.

@b(UNBREAKIN) @\Undoes BREAKIN.

@b(UNBREAK) @\Applies UNBREAK to the function.

@b(TRACE) @\Applies TRACE to the function.

@b(TRACEIN) @\Traces the function only when called from inside a particular
function, like BREAKIN above.  Use UNBREAKIN to remove the trace, or
else UNBREAK on the window menu.

]

@b(CCODE) @\Calls INSPECTCODE on the function if it is compiled code.

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

@b(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
@description[

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

@b(<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:
@description{

@b(HardCopy) @\Does a HARDCOPYW on the window with the graph.

@b(UNBREAK) @\Does an (UNBREAK), unbreaking all broken functions.

@b(RESET) @\Resets the counters for the COUNT option and redisplays graph.

}

@blankspace(1 line)
@flushleft(@b[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.

@b(CAVEAT PROGRAMMER!)  This feature @p(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.

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.

@blankspace(1 line)
@flushleft{@b[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:
@description{

@b(Function) @\Sets the current function which the command graphs by
prompting for a name in the prompt window.

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

@b(Exclude) @\Adds files of functions to the list of items disallowed
on the graph, see the Include/Exclude algorithm below.

@b(Clear) @\Clears all of the settings on the command window to the
defaults.  Also clears the Include/Exclude lists.

@b(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

@enumerate{

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.

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

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.

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.

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:
@description{

@b(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.

@blankspace(1 line)
@flushleft(@b[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.