REF TRACE                                      Andreas Schoter Sept 1991

        COPYRIGHT University of Sussex 1991. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<     REF TRACE FACILITIES    >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This REF file details the  syntax words, variables, and procedures  used
by the Poplog trace mechanism. For details on how to use these facilties
please see HELP * TRACE.

         CONTENTS - (Use <ENTER> g to access required sections)

  1   Syntax Words

  2   Variables

  3   Procedures

  4   Associated Documentation



---------------
1  Syntax Words
---------------

trace                                                           [syntax]
        This syntax word can be used in two ways:

            trace <names of procedures> ;
            trace;

        In  the  first  mode  it  enables  the  tracing  of  the   named
        procedures, and in the second mode it resumes trace printing for
        all traced procedures. The second mode is equivalent to 'true ->
        tracing'. See HELP * TRACE for more details.


untrace                                                         [syntax]
        This suspends trace  printing for all  traced procedures. It  is
        equivalent to  'false ->  tracing'.  See HELP * TRACE  for  more
        details.


untraceall                                                      [syntax]
        This untraces all currently traced procedures. See  HELP * TRACE
        for more details.




------------
2  Variables
------------

tracing                                                       [variable]
        This variable controls the trace printing of traced  procedures.
        When its value is true trace printing is enabled for all  traced
        procedures; when its value is false trace printing is  suspended
        for all traced procedures;  and when its value  is 1 tracing  of
        syntax procedures is  enabled. Its  default value  is true.  See
        HELP * TRACE for more details.


pop_chain_trace                                               [variable]
        If this variable is true (its default value) then abnormal exits
        that do not arise from process suspension from procedures  being
        traced are indicated  by printing  an `X'. If  this variable  is
        false  then  such  exits  are  supressed  from  the  trace.  See
        HELP * TRACE for more details.


pop_process_trace                                             [variable]
        If this variable is true (its default value) then exit and entry
        of traced procedures  due to process  suspension and  resumption
        are indicated  by printing  `S' and  `R' respectively.  If  this
        variable is false then  such procedure exit/entry are  supressed
        from the trace. See HELP * TRACE for more details.


poptraceindent                                                [variable]
        This global variable  is used to  control the number  of `!'  to
        print indicating the  depth of the  trace during recursion.  See
        HELP * TRACE for more details.


popmaxtraceindent                                             [variable]
        This variable controls how deep  in recursion the trace will  go
        before display of depth  is switched from a  string of `!'  to a
        numerical indicator. See HELP * TRACE for more details.




-------------
3  Procedures
-------------

systrace(p, word1, word2, bool)                              [procedure]
        This is the basic  tracing procedure. p  is the procedure  being
        traced; word1  is the  name of  that procedure;  word2,  usually
        "systrace_proc" is the name  of the procedure  to use for  trace
        printing; and  bool  is true  if  p  is an  updater,  and  false
        otherwise. Closures of systrace are used to control the  tracing
        of procedures. See HELP * TRACE for more details.


systrace_proc(p, word, bool)                                 [procedure]
        This procedure controls the actually  printing in a trace. p  is
        the procedure  being traced;  word  is the  name of  the  traced
        procedure; bool  is true  if that  procedure is  an updater  and
        false otherwise. See HELP * TRACE for more details.


systrace_pr(word, status, args, bool)                        [procedure]
        This procedure  is  called by  systrace_proc  to do  the  actual
        printing in a  trace. word is  the name of  the procedure  being
        traced; status is  an item indicating  the entry/exit status  of
        the procedure being traced, permissable status codes are:

            true   normal entry
            false  normal exit
            `>`    normal entry
            `<`    normal exit
            `X`    abnormal exit
            `R`    re-entry due to process resume
            `S`    exit due to process suspend

        args is a vector or list of arguments or results from the stack;
        bool is  true  if P  is  an  updater and  false  otherwise.  See
        HELP * TRACE for more details.




---------------------------
4  Associated Documentation
---------------------------

HELP * TRACE
    A  help  file  explaining  how  to  use  these  facilities.
HELP * DEBUGGER
    An interactive source code debugger.




--- C.all/ref/trace
--- Copyright University of Sussex 1991. All rights reserved.