File contents

                                                         August 1985


		           LISP FOR A SERIES

		      REDUCE SYSTEM FOR A SERIES

The system provided has three REDUCE programs: LISP, REDUCE itself,
and INTEGRATOR which includes REDUCE as a subset.  It is assumed that
the reader has read:

     "REDUCE 2 USER'S MANUAL" (1) and

     "STANDARD LISP REPORT" (2)

both of which are available from the Higher Education Software Library
(and also from the Computer Science department at the University of
Utah).  This document describes (sketchily) what must be done to
compile and run REDUCE.  It also describes how to make changes in the
REDUCE symbolic, recreate the necessary ALGOL files and subsequently
recompile REDUCE.

(1), (2) See the "References" section at the end of this document.

1. SYSTEM ORGANIZATION OVERVIEW

The REDUCE system for the B7000/B6000 series consists of four parts:

The REDUCE algebraic processor itself, a LISP processor, a LISP
compiler which converts LISP programs to an intermediate language, and
an assembler which converts the intermediate language to Burroughs
ALGOL.  The INTEGRATOR has a fifth part which is the integrator
package.

The algebraic processor, the compiler, the assembler and the
integrator package are written in RLISP, a sort of LISP with
ALGOL‐like syntax.  The LISP processor is written partly in ALGOL and
partly in RLISP.  All these parts are combined into a single large
ALGOL program.  The parts written in RLISP must first be translated to
ALGOL.  The algebraic processor does this translation.

The algebraic processor was largely written by Anthony Hearn, the
compiler is the work of Anthony Hearn and Martin Griss, the assembler
was done by John Fitch, the part of the LISP processor written in
RLISP was done by John Fitch and Jed Marti.  The integration package
was developed at Cambridge by Arthur Norman, John Fitch, and Maryann
Moore.  The ALGOL portion of the LISP processor, originally an SDL
program for the B1700 that was written by Fitch and Marti, was
translated to ALGOL and subsequently modified by Dave Dahm.

2.  COMPILING  REDUCE

It is assumed that the ALGOL compiler was compiled with "compile time
facilities" included (dollar option CTPROC).  If this is not so,
DMALGOL can be used instead.  There is a file called
REDUCE2LISP/MAIN/REDUCE which has several ALGOL compile time options
and several INCLUDE statements.  Compiling this file will produce a
REDUCE system.  Similarly there is a file called INTEGRATOR.
Compiling this file will produce a REDUCE system which can do symbolic
integration.  Also there is a file called LISP.  Compiling this file
will produce a LISP system.

There is a file called REDUCE2LISP/COMP/REDUCE which will compile
REDUCE with proper control statements.  There are similar files for
Lisp and Integrator.

2.1 ALGOL COMPILE TIME OPTIONS

FASTLINK
If this option is set, REDUCE (LISP) procedures are tightly
bound at ALGOL compile time, and may not be redefined at run time.  If
the option is reset, REDUCE procedures are loosely bound and may be
redefined at any time.  REDUCE will be faster if this option is set.

SLOWSTACK
If this option is set, REDUCE (LISP) local variables will be
kept in an array.  If this option is reset, REDUCE local variables
will be kept in the machine stack.  REDUCE will be considerably faster
if this option is reset; however, use of this option requires the use
of the NEWP library.

COUNT
If this option is set, REDUCE will gather statistics about the
internal functioning of the system.  Ordinarily this option will be
reset.

2.2 RECOMMENDED OPTION SETTINGS

If the usual mode of use is algebraic processing:

   all options reset.

If speed is most important:

   FASTLINK

3. REBUILDING ALGOL FILES

Occasionally it will be desirable to recreate the ALGOL files which
were produced by the RLISP compilation process.  This section
describes how this is done.  There is a file called "MAKER".  When
this file is loaded by REDUCE, the system will create two ALGOL
symbolic files and a linkage file.  These three files are called
N/ALGOL, N/FORWARDS, and N/SPACE.  For example after typing

   RUN REDUCE
	 
one may type

   IN "REDUCE2LISP/TORECREATE/MAKER/REDUCE";

This will cause REDUCE to read the file MAKER and create the N‐files.

The files (N/ALGOL and N/FORWARDS) are not complete.  For example they
don‘t have sequence numbers, are not of type ALGOL, and need to have
some additional information appended.  Also a program called LINKER
needs to process N/QSPACE and create a special initialization file.
This process is most conveniently done by running a CANDE schedule
file called REDUCE2LISP/DO/REDUCE.  Basically it will take the
N‐files, and three files called TACKY, PROCS, and UNKNOWNS and create
new ALGOL files.  QSPACE file and INIT file.  It will also cause the
compilation of the new version of REDUCE.  Running
REDUCE2LISP/DO/REDUCE requires the presence of two ALGOL programs:
SEQUENCE and LINKER.

After the successful running of this, the N‐files may be discarded.

Similarly, new ALGOL files may be created for INTEGRATOR or LISP.

4. THE LISP SYSTEM

The version of LISP is "STANDARD" LISP as defined in (2).  Our
implementation has the following differences (this list is not
exhaustive).

a) Floating point has not been implemented

b) Several LISP functions have been provided which are not specified
in (2).  Among these are:

   1) LENGTHC, the character length of an atom if printed by PRIN2.

   2) REVERSIP, the reversal in place of its argument using RPLACD

   3) LIST2, LIST3, LIST4, LIST5

   4) NCONS and XCONS

   5) FACTORIAL, the factorial of its argument

To use REDUCE as a LISP processor, run REDUCE and then type "END;".
This will cause LISP to be entered.  Typing "(BEGIN)" will cause RE‐
DUCE to be reentered.

5. MISCELLANEOUS OPERATIONAL CHARACTERISTICS

5.1 ?HI

     Typing ?HI will elicit a response giving some information about
     the present state of processing.  This should be expanded in the
     future.

5.2 ?HI 1

     This will cause the present computation to abort and return to
     REDUCE or LISP command level.

5.3 ?END

     Typing ?END will return you to the system in a controlled fashion
     and give some information about what happened during the run.

5.4 GCFLAG

     Typing "ON GCFLAG" will cause garbage collection to print
     statistics about garbage collection.  Typing "OFF GCFLAG" will
     shut off these messages.

5.5 SETTRACE

     Typing "ON SETTRACE" will cause a trace of all interpreted SET or
     SETQ function executions.  Typing "OFF SETTRACE" will turn off
     this trace.

5.6 PROGTRACE

     Typing "ON PROGTRACE" will cause a trace of all interpreted
     functions at the first level of PROG, PROGN, or COND.

5.7 CONTROLLING STORAGE ALLOCATION

The free storage pool is divided into 2 arrays, one array for CAR and
one array for CDR.  Each of these arrays is divided into 256 word
pages.  Therefore, a "page" of free space is 512 words ‐ 256 words for
CAR and 256 words for CDR.  The LISP processor uses the CORE es‐
timate to control the number of pages used.  This is set to 150 000
words at compile time, but the user may change this at run time.  The
formula used is:

     PAGES = (COREESTIMATE ‐ 50000)/512

For example:

     RUN REDUCE; CORE = 70000

will use 40 pages (each page being 512 words: 2 array rows of 256
words each).  The maximum number of pages allowed is 256.  This may be
increased by changing the DEFINE for PPAGEMAX in
REDUCE2LISP/INCLUDE/ALGOL.

5.8  INPUT/OUTPUT

The REDUCE IN statement may have as its parameter:

   1) an ID e.g. ‘MYFILE
   
   2) a STRING e.g.  "MYFILE" or "MY/FILE" or "MY/FILE ON THEPACK"

   3) a list e.g. ‘(MYFILE 100 900)

The action of the first two options are obvious.  The third option
reads the records of the file MYFILE between sequence numbers 100 and
900 only.

Similar options are available for the OPEN statement.

If the name of the file is PRINTER, the output will be directed to the
line printer.

REFERENCES

(1) A.C.  Hearn, REDUCE 2 USER'S MANUAL, University of Utah, March
1973. On the Higher Education Software Library, this documentation is
on the file REDUCE2LISP/DOC/REDUCE.

(2) J.B. Marti, A.C. Hearn, M.L.  Griss, C. Griss, STANDARD LISP
REPORT, University of Utah, January 1978.  On the Higher Education
Software Library, this document is on the file REDUCE2LISP/DOC/LISP.

APPENDIX

REDUCE2LISP/TORECREATE/ASSEMBLER (RLISP symbolic)
This code converts the intermediate language to ALGOL.

REDUCE2LISP/TORECREATE/B6700 (RLISP symbolic)
This code includes various machine specific changes to REDUCE.

REDUCE2LISP/TORECREATE/COMPILER (RLISP symbolic)
This code converts LISP to the intermediate form.

REDUCE2LISP/MAIN/INTEGRATOR (ALGOL symbolic)
This file contains option setting and INCLUDE statements to paste
together the various ALGOL files.  Compiling this file produces
OBJECT/INTEGRATOR.

REDUCE2LISP/DO/INTEGRATOR (CANDE schedule file)
This file converts N‐files to sequenced ALGOL files, creates an INIT
file, and does the ALGOL compilation for INTEGRATOR.  This is the
final pass of rebuilding INTEGRATOR.

REDUCE2LISP/GENERATED/INTEGRATOR/ALGOL (ALGOL symbolic)
This is the ALGOL translation of the integration package.

REDUCE2LISP/GENERATED/INTEGRATOR/FORWARDS (ALGOL symbolic)
This file contains the FORWARD declarations for the procedures in
REDUCE2LISP/GENERATED/INTEGRATOR/ALGOL.

REDUCE2LISP/GENERATED/INTEGRATOR/INIT (Binary file ‐ internal LISP
representation.
Initialization file for INTEGRATOR.

REDUCE2LISP/GENERATED/INTEGRATOR/PROCS (ALGOL symbolic)
This file contains copies of the procedure declarations in INTEGRATOR.
It is used to produce TRACEBACK information.

REDUCE2LISP/GENERATED/INTEGRATOR/QSPACE (Legible file)
Input to LINKER (creates INIT file)

REDUCE2LISP/TORECREATE/MAKER/INTEGRATOR (RLISP symbolic)
This file, used as input to REDUCE, will rebuild the INTEGRATOR
N‐files.

REDUCE2LISP/INCLUDE/RLISP/INTEGRATOR (RLISP symbolic)
This code is the integration package.

REDUCE2LISP/MAIN/LINKER (ALGOL symbolic)
This is the symbolic for the LINKER program.  This program reads
QSPACE file (a legible file) and creates the INIT file (a binary
file).

REDUCE2LISP/MAIN/LISP (ALGOL symbolic)
This file contains option settings and INCLUDE statements to paste
together the various ALGOL files.  Compiling this procedure produces
OBJECT/LISP.

REDUCE2LISP/INCLUDE/ALGOL (ALGOL symbolic)
This is the symbolic for the ALGOL portion of the LISP processor.

REDUCE2LISP/DO/LISP (CANDE schedule file)
This file converts N‐files to sequenced ALGOL files, creates an INIT
file, and does the ALGOL compilation for LISP.  This is the final pass
of rebuilding LISP.

REDUCE2LISP/GENERATED/LISP/ALGOL (ALGOL symbolic)
This is the ALGOL translation of RDUCE2LISP/MAIN/RLISP/LISP

REDUCE2LISP/GENERATED/LISP/FORWARDS (ALGOL symbolic)
This file contains the FORWARD declarations for the procedure in
REDUCE2LISP/GENERATED/LISP/ALGOL.

REDUCE2LISP/GENERATED/LISP/INIT (Binary file ‐ internal LISP
representation/
initialization file for LISP.

REDUCE2LISP/GENERATED/LISP/PROCS (ALGOL symbolic)
This file contains copies of the procedure declarations in LISP.  It
is used to produce TRACEBACK information.

REDUCE2LISP/GENERATED/LISP/QSPACE (legible file)
Input to LINKER (creates INIT file)

REDUCE2LISP/TORECREATE/MAKER/LISP
This file, used as input to REDUCE, will rebuild the LISP N‐files.

REDUCE2LISP/INCLUDE/RLISP/LISP (RLISP symbolic)
This is the symbolic for the RLISP portion of the LISP processor.

REDUCE2LISP/TORECREATE/MACROS (RLISP symbolic)
The file is used by the LISP compiler during a rebuild.

REDUCE2LISP/TORECREATE/PROCS (ALGOL symbolic)
This file contains copies of the procedure declarations in LISP/ALGOL.
It is used by the schedule files to produce the PROCS files.

REDUCE2LISP/MAIN/REDUCE (ALGOL symbolic)
this file contains option settings and INCLUDE statements to paste
together the various ALGOL files.  Compiling this file produces
OBJECT/REDUCE.

REDUCE2LISP/DO/REDUCE (CANDE schedule file)
This file converts N‐files to sequenced ALGOL files, creates an INIT
file, and does the ALGOL compilation for REDUCE.  This is the final
pass of rebuilding REDUCE.

REDUCE2LISP/GENERATED/REDUCE/ALGOL (ALGOL symbolic)
This is the ALGOL translation of REDUCE.

REDUCE2LISP/GENERATED/REDUCE/FORWARDS (ALGOL symbolic)
This file contains the FORWARD declarations for the procedures in RE‐
DUCE2LISP/GENERATED/REDUCE/ALGOL.

REDUCE2LISP/GENERATED/REDUCE/INIT (Binary file ‐ internal LISP
representation)
Initialization file for REDUCE.

REDUCE2LISP/GENERATED/REDUCE/PROCS (ALGOL symbolic)
This file contains copies of the procedure declarations in REDUCE.  It
is used to produce TRACEBACK information.

REDUCE2LISP/GENERATED/REDUCE/QSPACE (Legible file)
Input to LINKER (creates INIT file).

REDUCE2LISP/TORECREATE/MAKER/REDUCE (RLISP symbolic)
This file, used as input to REDUCE, will rebuild the REDUCE N‐files.

REDUCE2LISP/INCLUDE/RLISP/REDUCE (RLISP symbolic)
This code is the algebraic processor.

REDUCE2LISP/TEST/REDUCE (REDUCE symbolic)
This is a test file.  If REDUCE correctly processes this file, things
are in pretty good shape.

REDUCE2LISP/MAIN/SEQUENCE (ALGOL symbolic)
This is the symbolic for the SEQUENCE program which sequences the
N‐files.  It is used while running a schedule file.

REDUCE2LISP/TORECREATE/STARTLISP (RLISP symbolic)
This file is used to REDUCE when doing an RLISP compilation.

REDUCE2LISP/TORECREATE/TACKY
This file is used by the schedule files to produce QSPACE files.

REDUCE2LISP/TEST/LISP (LISP symbolic)
This is a test file.  When using REDUCE as a LISP processor, this file
will test many LISP primitives.

REDUCE2LISP/TORECREATE/TRACE (RLISP symbolic)
This file contains RLISP procedures which will allow selective tracing
of interpreted routines.

REDUCE2LISP/TORECREATE/UNKNOWNS (ALGOL symbolic)
This file contains empty definitions of procedures which have not been
implemented.