HELP CLOCK                                Mark Rubinstein, February 1985

There are several POPLOG system and library procedures which make use of
the system clock.  This HELP file is only intended to be a brief summary
of them. Most of the procedures have a HELP or REF file associated with
them which will provide more detail.

Not all of the following procedures are independent of each other.  For
example, CHARIN_TIMEOUT makes use of POP_TIMEOUT.  This means that a the
setting of the POP_TIMEOUT and POP_TIMEOUT_SECS will be overidden, while
CHARIN_TIMEOUT is running.  Currently UNIX systems only provide one
access to the clock so none of procedures which use a timer will be
independant of each other.


--- CHARIN_TIMEOUT -----------------------------------------------------

    charin_timeout(<integer>)-> <integer> or <false>

This procedure takes an integer N and waits until N hundredths of a
second have elapsed, or a  character has been pressed at the terminal.
If a character  is pressed, then it returns the character.  If not, it
returns FALSE.  See HELP * CHARIN_TIMEOUT.  (Uses POP_TIMEOUT and
POP_TIMEOUT_SECS).


--- POP_TIMEOUT and POP_TIMEOUT_SECS -----------------------------------

If POP_TIMEOUT_SECS is an integer then if any read operation waits for
any longer than that number of seconds the procedure POP_TIMEOUT is
called. Examples of reads are calls of CHARIN, RAWCHARIN and SYSREAD).

POP_TIMEOUT is a procedure variable which is applied if a read
"times-out" (as set by POP_TIMEOUT_SECS).  Default is *IDENTFN.  See
HELP * POP_TIMEOUT.

POP_TIMEOUT_SECS is a variable which if an integer specifies how many
seconds after which a read should time out.  If POP_TIMEOUT_SECS is
FALSE then reads will not "time-out".  Default is *FALSE.
See SHOWLIB * CHARIN_TIMEOUT for an example of its use.


--- POPGCTIME ----------------------------------------------------------

POPGCTIME is a variable showing total CPU time spent doing automatic
garbage collections since the system start (measured in 1/100ths of a
second).  See HELP *POPGCTIME for further references.


--- SYS_CONVERT_DATE -- [UNIX ONLY] ------------------------------------

    sys_convert_date(<time>, <local>) -> <string>

Given a time in seconds since 00:00 GMT 1 Jan 1970 (as returned by
SYS_REAL_TIME q.v., or a file date returned by *SYS_FILE_STAT etc),
returns a date string as produced by the Unix "date" command, in the
form:

    'nnn mmm dd hh:mm:ss <timezone> yyyy'

where nnn is the day name.  If LOCAL is TRUE then the local time is
returned, otherwise GMT.  See REF * TIMES /sys_convert_date.


--- SYS_REAL_TIME ------------------------------------------------------

    sys_real_time() -> <integer>

A procedure returning the number of seconds since 00:00 GMT on 1 January
1970.  On Unix machines, can be turned into a date string using
SYS_CONVERT_DATE q.v.


--- SYSCANTIMER --------------------------------------------------------

    syscantimer()

Cancels the current timer interrupt as set by *SYSSETTIMER.


--- SYSDAYTIME ---------------------------------------------------------

    sysdaytime() -> <string>

A procedure which returns a date string with the current date and time.
See HELP * SYSDAYTIME.


--- SYSSETTIMER --------------------------------------------------------

    syssettimer(<integer>)
or
    syssettimer(<integer>, <procedure>)

A procedure which takes an integer representing a time in 100ths of a
second.  The user assignable procedure TIMER_INTERRUPT (q.v.) will be
called when the specified time interval has elapsed.  SYSSETTIMER can be
called with a second argument - a procedure which is assigned to be the
value of TIMER_INTERRUPT.  See HELP * SYSSETTIMER.

The timer can be cancelled using SYSCANTIMER q.v..


--- SYSTIME ------------------------------------------------------------

    systime() -> <integer>

This procedure returns the accumulated CPU time for the current run of
the POP-11 system in hundredths of a second.  See HELP * SYSTIME.


--- LIB TIME -----------------------------------------------------------

    time

TIME is a macro, made available by doing LIB TIME, which can be used to
give a command to POP-11 and have the CPU time and garbage collection
time printed out.  See HELP * TIME.


--- TIMEDIFF -----------------------------------------------------------

    timediff() -> <integer>

This procedure returns the CPU time in seconds since its previous use.
The first time it is called the result is meaningless.  Use it before
and after some operation in order to test the time take it takes.  See
HELP * TIMEDIFF.


--- TIMER_INTERRUPT ----------------------------------------------------

TIMER_INTERRUPT is a user-assignable procedure variable which holds the
value of the procedure which is applied when SYSSETTIMER (q.v.)
times-out. See REF * TIMES.


--- C.all/help/clock
--- Copyright University of Sussex 1989. All rights reserved. ----------
