A. Installation and Use

We describe here how to install and use Refal-5 on IBM AT or XT under MS-DOS. There is an adaptation of this system for the Apple Macintosh. Its description comes with the diskette for the Macintosh.

1. Installation

At present the distributives of executable modules are available at(http://www.botik.ru/pub/local/scp/refal5/ ) for a several operating systems: Windows-NT, Windows-95/98, a version of Linux, MS-DOS.

It is recommended to recompile the Refal-5 sources under your Linux system. The sources can be found on the same Web-site.

The binary disributive contains the following files:

  README
  REFC     EXE
  REFGO    EXE
  REFTR    EXE
  RDHELP   TXT
  TEST     REF
  E        REF
  MBPREP   REF
  REFLIB   REF

a.. Extention of the executable modules depends on your operating system.
b.. A version for MS-DOS additionaly contains the following files:
    a.. AUTOEXEC.BAT
    b.. REFALENV.BAT
    c.. CONFIG.SYS
    d.. GO32.EXE
    e.. README.DOS

A) Installation under Windows-NT, Windows-95/98, and a version of Linux:

  1. Create a directory; let it be REFAL.
  2. Copy all files into the REFAL directory.
  3. Copy the three executable modules into any subdirectory which is in the PATH environment variable or add the path to the REFAL directory in the environment variable.
  4. Switch to REFAL and execute:
      refc TEST
      refc E
      refc MBPREP
      refc REFLIB
    
    This will add the files TEST.RSL, E.RSL , MBPREP.RSL and REFLIB.RSL to REFAL .

  5. Put the path to the REFAL directory in the REF5RSL environment variable. This will enable you to load REFLIB.REF from any directory.
  6. Put the path to the RDHELP.TXT file including the file name in the RD_HELP environment variable. This will enable you to read a help file from the Refal Tracer.
  7. Create a directory to work; let it be REFAL-USER. Go to this directory.
  8. You are all set now. To check that things work as expected, run:
      refgo test
    
    This will start an interactive program for the translation of simple arithmetic expressions.

  9. Your are welcome to develope a Refal-5 program, compile and run it in any directory.

B) Installation under MS-DOS, intel-386 and later above, protected mode.

This version was compiled by a GNU-C compiler. GO32.EXE is the GNU-C software.

The GO32.EXE can conflict with some drivers on your MS-DOS system so we give a minimal AUTOEXEC.BAT and CONFIG.SYS to check that things work. It is your responsibility to install the Real-5 under your whole system's environment.

  1. Create directories:
       C:\> mkdir REFAL
       C:\> mkdir TMP
    
  2. Copy all files into the REFAL directory.
  3. Save your system's modules:
       C:\> copy autoexec.bat autoexec.sav
       C:\> copy config.sys config.sav
    
  4. Change the system's modules with the minimal variants.
       C:\> copy c:\REFAL\autoexec.bat c:\autoexec.bat
       C:\> copy c:\REFAL\config.sys c:\config.sys
    
    "autoexec.bat", "config.sys" and "refalenv.bat" are given in the distributive.

  5. Reboot your DOS system.
  6. Switch to REFAL and execute:
      cd REFAL
      refc TEST
      refc E
      refc MBPREP
      refc REFLIB
    
    This will add the files TEST.RSL, E.RSL , MBPREP.RSL and REFLIB.RSL to REFAL .

  7. You are all set now. To check that things work as expected, run:
      refgo test
    
    This will start an interactive program for the translation of simple arithmetic expressions.

  8. Try to fill your DOS-system environment.
  9. Copy the four executable modules into any subdirectory which is in the PATH environment variable or add the path to the REFAL directory in the environment variable.
  10. Do 5-9'th steps as they are discribed the A)-installation (see above).

2. Use

In the following XXX , YYY , etc. are some file names (without extensions). Using any editor, create a Refal program in XXX.REF .

2.a Compilation:

To compile, execute:

  refc XXX

If there are no errors, no message will be sent. The file XXX.RSL that contains the translation of the Refal program into the interpreted language RASL will be added to the current directory. If there is an error message, see file XXX.LIS for the listing of the Refal program with the descriptions of errors.

It is possible to compile the XXX.REF file from another directory. Let PATH be the path to a directory, then execute:

  refc PATH/XXX

The XXX.RSL or XXX.LIS file will be created in the directory from which the file XXX.REF was taken.

2.b Running:

To run the Refal program execute:

  refgo XXX

If you need functions defined in other modules: YYY , ZZZ , etc. compile YYY , ZZZ , etc. and run:

  refgo XXX+YYY+ZZZ  etc.

The evironment variable REF5RSL has as its value a list of directories (with their paths) as its value. If for some REFAL-module XXX there is no file XXX.RSL in the current directory where refgo is runnig, then the loader is looking for the file in directories which are indicated in the value of REF5RSL. The paths to the directories must be delimited with semicolon. The start value of the REF5RSL variable that is set in the installation allows to put REFLIB to the list to be loaded without a path to the directory where the Refal-5 system was installed.

In particular, do not forget to include the module REFLIB if you use some of the standard functions defined there.

The syntax of arguments for the Refal-5 loader allows to describe paths to RSL-modules using a left distributive rule: concatenation is used as multiplication and the subdirectory character is added on the end of each factor-path.

  An example for Linux system:

  refgo f1+path1(f2+path2(f3+f4))+path4(f5+f6)
    is equal to
  refgo f1+path1/f2+path1/path2/f3+path1/path2/f4+path4/f5+path4/f6
NOTE: Make sure there are no blanks between file names and pluses.

To run the program by the tracer, use REFTR instead of refgo :

  reftr XXX+YYY+ZZZ  etc.

(see Reference Section D for a description of the tracer).

  To run with arguments, execute:

  refgo XXX+YYY etc. Arg1 Arg2 etc.
  reftr XXX+YYY etc. Arg1 Arg2 etc.

An argument cannot start with - . To access the arguments from the Refal program, use (see Reference Section C).

To evaluate any function calls defined in some file XXX using the evaluator E (see Sec. 6.3), see that this file includes the line:

  $ENTRY Upd { e.X = ; }

Then enter:

  refgo e+XXX+...

or:

  reftr e+XXX+...

2.c Options in running:

You can specify options with refgo :

  refgo [options] XXX+YYY etc.

or:

  refgo XXX+YYY etc. [options]

  options    ::= -option | -option options
  option     ::=  n | v | k | s | a | i | lnnn | Code_Limit
  Code_Limit ::= cnnn | -code_limit=nnn

Semantics of the options is:

For example, if you call

  refgo XXX+YYY etc. -t -n

Then the number of steps and the execution time will be printed out at the end.

3. Return code:

The Refal-5 executable modules (refc, refgo and reftr) return ( to a current operating system ) either 0 if it has just stoped normally, or another integer in the next cases:

refc:

refgo, reftr: