User guide

76 CHAPTER 3. THE LIBRARY
sys(Sys
tally, val) CIN:y, POS:y, NAT:n
This call provides a profiling facility that uses a globally accessible tall y vector to
hold frequency counts of Cintcode instructions executed. When val is TRUE the tally
vector is cleared and tallying i s enabled. When val is FALSE tallying is disabled . When
tallying is active, the i
th
element of the tally vector is incremented every time the
instruction at location i of the Cintcode memory is executed. The size of the tally
vector can be specified by the -t command line ar gume nt (see Section 12.2) when the
interpreter is entered. The default size being typically 80000 words. The tally vector
is held in rootnode!rtn tallyv with the upper bound stored in its zeroth element. It
can thus be inspected by any program.
Statistics of program ex e cut i on is normally gathered and analysed using the CLI
command stats (see Section 4.3).
pos := sys(Sys tell, fd) CIN:y, POS:y, NAT:y
This returns the cu r re nt file position pointer of the ope ne d file whose descriptor is
fd. The file descriptor is normally in the scb
fd field of the stream control block for
that file. See Section 3.4 for more information about random access files.
sys(Sys
tracing, val) CIN:y, POS:y, NAT:n
This sets the Cintcode tracing mode to val. When the tracing mode is TRUE, the
Cintcode interpreter outputs a one line trace of every Cintcode instruction executed.
sys(Sys
trpush, val) CIN:y, POS:y, NAT:n
There is a low level circular trace buffer that can hold 4096 values, and a pri-
vate variable trcount that holds the number of values currently pushed into this
buffer. If trcount<0, low level tracing is disabled, but otherwise trpush pushes
val into the buffer at position trcount MOD 4096 and increments trcount. The call
sys(Sys
settrcount, count) sets trcount to the specified value (possibly disabling
tracing) and returns its previous setting. The call sys(Sys
gettrval, count) gets
the value in the trace buffer at position trcount MOD 4096. Normally this function is
only called when tracing is disabled. Under both Cintsys and Cintpos, trpush can also
be called from the parts of the system implemented in C.
This tracing mechanism is availabl e both to th e BCPL user and parts of the s y st em
such as cintpos.c, cinterp.c and devices.c. Under Cintpos these low le vel tracing
functions use a mutex to control access to trcount and the circular buffer. It is thus
thread safe and so can be used to help debug subtle timing problems in the system
software. For an example of the use of this tracing me chanism see the command
com/testtr.b.
res := sys(Sys
unloadseg, seg) CIN:y, POS:y, NAT:y
This unloads the the loaded module given by seg. If seg is zero it does nothing.
Unloading a module just returns the space it occupied to freestore.
sys(Sys
unlockirq) CIN:n, POS:y, NAT:n
Under cintpos, this call enables interrupts.