reduce-historical/r30/tops20.doc

               RUNNING REDUCE ON A DECSYSTEM 20 SERIES COMPUTER

                                 Version 3.0

                                      by

                               Anthony C. Hearn

                             The Rand Corporation
                          Santa Monica, CA 90406 USA

                                  April 1983












                                   ABSTRACT


This  document describes operating procedures specific to running REDUCE under
TOPS-20 on a DECSYSTEM 20 series computer.









                         Rand Publication CP81(4/83)

                   Copyright (c) 1983 The Rand Corporation




                              _T_A_B_L_E__O_F__C_O_N_T_E_N_T_S







1.  PRELIMINARY .........................................................    1

2.  FILE HANDLING .......................................................    1

3.  AN INTRODUCTION TO REDUCE ...........................................    2

4.  REDUCE DOCUMENTATION ................................................    2

5.  FILE EDITING CAPABILITIES ...........................................    2

6.  IMPLEMENTATION DEPENDENT PARAMETERS .................................    3
         6.1  Object sizes ..............................................    3
         6.2  Special characters and interrupts .........................    3
         6.3  Memory Requirements .......................................    4
         6.4  Miscellaneous .............................................    4

7.  IMPLEMENTATION DEPENDENT ERROR MESSAGES .............................    4

8.  FURTHER HELP ........................................................    4

Running REDUCE under TOPS-20                                            Page 1


1.  _P_R_E_L_I_M_I_N_A_R_Y

This document describes operating procedures for running  REDUCE  specific  to
the  DECSYSTEM  20  series  of  computers.   It  supplements the REDUCE User's
Manual, describing features, extension and limitations specific to this imple-
mentation of REDUCE.

REDUCE under TOPS-20 for a DECSYSTEM 20 series computer is stored as  an  exe-
cutable  binary  disk file.  The name of the directory that contains this file
is identified in this document as "<reduce>" .  Other REDUCE related files are
also stored in this directory.

Unless <reduce> is equivalent to sys: at your site, your command files  should
be  modified  to  include  <reduce> in your sys: search path.  An entry of the
form:

    def sys: <reduce>,sys:

is sufficient.

To run REDUCE, you then type (in upper or lower case)

    reduce

REDUCE will respond with a banner line and then prompt for the first  line  of
input:

     reduce 3.0, 15-Apr-83 ...

     1:

You can now begin entering commands.


2.  _F_I_L_E__H_A_N_D_L_I_N_G

The LISP interpreter currently in use with this version of REDUCE  was  origi-
nally written for a TOPS-10 system. As a result, its file names follow TOPS-10
conventions. In particular, the name and extension fields can be a maximum  of
six  and  three  characters long respectively. As a result, the filenames that
appear in IN, OUT and SHUT statements must follow this  convention.  Directory
names can be of three forms:

   An identifier followed by a colon, e.g., reduce:.

   An identifier enclosed in angle brackets, e.g., <reduce>. (Normally only
      used with TOPS-20.)

   A project, programmer pair, enclosed in square brackets, e.g., [22,304].
      (Normally only used with TOPS-10.)

The first two styles of directory name must precede the  file  name,  and  the
third follow it, as in

     "reduce:reduce.tst"

Running REDUCE under TOPS-20                                            Page 2


     "<reduce>reduce.tst"
or
     "reduce.tst[22,304]".

As a test of the system, you should try

     in "<reduce>reduce.tst";

which will load the standard REDUCE test file.


3.  _A_N__I_N_T_R_O_D_U_C_T_I_O_N__T_O__R_E_D_U_C_E

New users of REDUCE are advised to process the seven REDUCE Lessons  that  are
available as <reduce>lessi.  For example, to run Lesson 1, you would say:

     in "<reduce>less1";


4.  _R_E_D_U_C_E__D_O_C_U_M_E_N_T_A_T_I_O_N

REDUCE documents are also kept in the <reduce> directory, with  the  extension
doc. These include:

     instal.doc      Installation instructions

     reduce.doc      REDUCE User's Manual

     tops20.doc      TOPS-20 specific operation notes (i.e., this document).


5.  _F_I_L_E__E_D_I_T_I_N_G__C_A_P_A_B_I_L_I_T_I_E_S

The TOPS-20 version of REDUCE provides a link to the line-oriented system edi-
tor "EDIT".  There are two commands provided in this regard.

     EDIT <id>[,<integer>[,<integer>]]

If <id> is a valid file name, then this command will invoke the editor on this
file.   If  the optional integer arguments are omitted, then you will be posi-
tioned at the first line in the file.  On exiting from the editor, you will be
returned to REDUCE.  If the second argument is used, you will be positioned at
that line in the file.  If the third argument  is  used,  that  page  will  be
referenced rather than the default page 1.  For example,

     EDIT "foo.bah",100;

will position the editor at line 100 on page 1 of the file "foo.bah".

If the second or optional third arguments are specified, on exiting  from  the
editor REDUCE will first load the command that starts at the line specified in
the EDIT command before returning control to the user.

If <id> is not a file name, but is the name of a function that has been loaded
by  the user from a file, then the editor will be positioned at the first line

Running REDUCE under TOPS-20                                            Page 3


of that function.

Thirdly, if <id> is the name of a function that has been defined at the termi-
nal,  EDIT  will edit that function by a call to EDITDEF. In other words, EDIT
and EDITDEF are equivalent in this case.

If none of these conditions is satisfied, EDIT will abort with the error  that
<id> is not defined.

There are two cautions to be observed  in  using  this  command  to  reference
files.  First, you must not renumber the file or save it without line numbers,
since REDUCE  depends  on  the  explicit  line  numbers  for  its  references.
Secondly,  if you do not position the editor at the beginning of a command for
the second use of EDIT, then an error will obviously occur when  REDUCE  tries
to read the expression. The same cautions apply to CMD defined below.

     CMD <id><integer>[,<integer>]

This command causes the command defined at the line  <integer1>  in  the  file
<id> to be loaded. <integer2> can be used to specify an optional page.


6.  _I_M_P_L_E_M_E_N_T_A_T_I_O_N__D_E_P_E_N_D_E_N_T__P_A_R_A_M_E_T_E_R_S

6.1  _O_b_j_e_c_t__s_i_z_e_s

The maximum string and identifier lengths are limited only by the  total  size
of  the  memory partition for the names of such objects in the underlying LISP
interpreter.  This is usually several thousand characters  long.  However,  we
recommend  that  such  names  be limited to twenty-four characters or less for
compatibility with other versions of REDUCE.

Floating point numbers are printed with eight digit precision in either  fixed
notation  or  in  a scientific notation with a two digit exponent depending on
the size of the number.

Arbitrary precision integer and real arithmetic is supported.

Times (as reported by ON TIME or SHOWTIME)  are  given  in  milliseconds,  and
measure execution time including garbage collection time.  They do not include
operating system overhead (e.g., swapping time).

6.2  _S_p_e_c_i_a_l__c_h_a_r_a_c_t_e_r_s__a_n_d__i_n_t_e_r_r_u_p_t_s

Lower case input is permitted.

The end-of-file character is <control>Z.

<del> deletes a single character from terminal  input,  <control>U  the  whole
line.

A command may be terminated by <escape> instead  of  $.  This  has  the  added
advantage  that a Return is then not needed to evaluate the line.  <escape> is
also used to terminate strings in the REDUCE interactive editor.

Running REDUCE under TOPS-20                                            Page 4


^ may be used instead of ** to represent exponentiation.

6.3  _M_e_m_o_r_y__R_e_q_u_i_r_e_m_e_n_t_s

The distributed version of REDUCE requires a minimum of 193 pages of memory to
run.   This  size  will  increase  as  additional facilities are automatically
loaded by user actions.  A default expression workspace of approximately 26000
cells  is also provided, which may prove to be insufficient for some problems.
A command CORE is available to increase the size of the workspace.  This  com-
mand MUST be given at the top level and not from a file since it reinitializes
all file buffers.  CORE takes an integer as argument, representing  the  basic
REDUCE  program  size  in  K words (exclusive of operating system increments).
The minimum value is 60 (the default) and the maximum 124.   For  example,  to
increase the user workspace by 10K words, one would say:

     CORE 70;

at the top level.

6.4  _M_i_s_c_e_l_l_a_n_e_o_u_s

The internal ordering on alphabetic characters is from A through Z followed by
a through z.

To exit REDUCE use either "bye;" or "quit;".  These  are  equivalent.   If  no
non-ephemeral  processes  have been invoked after this, such a job may be res-
tarted by the operating system command CONTINUE.


7.  _I_M_P_L_E_M_E_N_T_A_T_I_O_N__D_E_P_E_N_D_E_N_T__E_R_R_O_R__M_E_S_S_A_G_E_S

A number of error messages from the underlying LISP system may  be  seen  from
time to time.  These include:

NO FREE STG LEFT
        Your problem is too large in its present form for the available
        workspace; either change your problem formulation or increase the
        amount of workspace by the CORE command

REG PUSHDOWN CAPACITY EXCEEDED
        Your program probably contains a non-terminating loop that exhausts
        the system's space for recursive references.  If you think your
        program is correct, ask your site consultant to build you a system
        with a bigger pushdown stack.

For further details, the Manual for Standard  LISP  on  DECSYSTEM  10  and  20
should be consulted.


8.  _F_U_R_T_H_E_R__H_E_L_P

For further help with REDUCE, please contact

     <list your site consultant here>