[Note: These instructions were for the commercial version of JForth. Please refer to the instructions that came with the Freeware archive for the latest information.]
For the optimal use of JForth we recommend having at least 1 Megabyte of memory and either two floppy drives, or one floppy and a hard drive. It is possible to use some parts of JForth with only 512K of RAM or one disk drive, but limitations are quickly encountered. We will describe later in this chapter how to do that.
We also recommend that you be familiar with the general use of the Amiga and the AmigaDOS operating system. Specifically, you should be familiar with performing the following tasks:
1) Making backup copies of floppy disks,
2) Opening a CLI or Shell window,
3) Using the CLI commands ASSIGN, COPY, DIR, EXECUTE, RENAME and RUN.
If you are not familiar with these, please review the Amiga User Manual and other documentation because an explanation of these is beyond the scope of this manual. You should be comfortable with the operation of the Amiga before attempting any programming. Once you are familiar with Amiga operation, the use of JForth should be quite straight forward.
We recommend that you work from a CLI window or a Shell window. You can also work from the Workbench but this is a less powerful environment for programming.
To open a Shell window in Amiga DOS, open the Workbench or your hard disk icon and double click on the "Shell" icon.
JForth Professional comes on three disks. The "Extras" disk and the "JTools" disk are specifically labeled as such; the remaining disk is simply called "JForth".
The first thing is to make working copies of your disks. You should then keep the original copies as backups. JForth is not copy protected so you can use DISKCOPY from the CLI. If you use the Workbench to make your copies, you will need to relabel the new disks because the Workbench prepends "Copy of" to the disk label. Remove that so that the copies have the same names as the originals. It is probably a good idea to write protect your original disks before starting to make the backups to avoid accidental erasure.
It is also very important to frequently make backup copies of the programs you write. Making backups is important even if you are the kind of person who never makes mistakes. If the power goes out, or some other error occurs, while you are writing to a disk, then you will probably lose at least one file. It is usually the file you are working on. As long as you make frequent backups of your work, you can minimize your loss.
The steps you take now depend on the configuration of your Amiga system.
If you have a Hard Disk, proceed with the section on Hard Disk Installation.
If you only have One Floppy Disk Drive and NO hard disk, skip to the section on running with 1 drive, (or buy another disk drive).
If you have two floppy disk drives and at least 1 Meg of RAM, skip to the section on running JForth from Floppies.
We have provided a script file to help users install JForth on a hard drive. It will create a directory called WORK:JFORTH_DIR on your hard disk. It will then copy the three JForth disks into separate directories in the new directory. If you would like to specify a different name for this directory, you can pass a directory name as a parameter to the script.
Note: If you have a previous version of JForth installed, you will need to UN-ASSIGN the JFORTH:, and EXTRAS: logical volumes. Otherwise the system will confuse the JFORTH: on your hard disk with the JFORTH: floppy disk. The best way to UN-ASSIGN these is to remove the ASSIGNs in your startup sequence in the S: directory, then reboot the Amiga. You do not need to remove the old version itself but you may want to rename the directory it is in to avoid naming conflicts with the new version.
To install JForth on a hard disk, put the JTOOLS: disk in a floppy drive then enter in the shell:
CD RAM: COPY JTOOLS:INSTALL_JFORTH RAM:
You now have a choice to make. To put JForth in the directory WORK:JFORTH_DIR, enter:
EXECUTE INSTALL_JFORTH
or, to use a different, directory, enter:
EXECUTE INSTALL_JFORTH other_directory_name
You will then be asked to insert the three JForth disks, one at a time. It will take several minutes for the files to copy.
You should now modify your startup sequence based on the instructions printed when the script finishes. These modifications will assign logical names to the JForth directories so that JForth will know where to look for its files. Finally reboot the computer so that the ASSIGNs will be executed. To run JForth you can now enter:
RUN COM:JFORTH
If you would like to perform a quick test of JForth, wait for JForth to start, then enter in JForth:
INCLUDE JD:DEMO_BOXES
After compilation is complete, enter:
BOXES
You should now see a window with random boxes being drawn. Click in the closebox (upper-left) to stop the demo.
To quit from JForth, enter:
BYE
Put your working copy of the "JForth" disk in the external drive and enter:
EXECUTE JForth:ASSIGNS
This sets up logical volumes in the Amiga that will help it keep track of where files are located. Put your JTools disk in the external drive and enter:
EXECUTE JTools:ASSIGNS
Now put your working copy of the "Extras" disk in the external drive and enter:
EXECUTE Extras:ASSIGNS
Now, let's run JForth itself. Enter:
RUN COM:JFORTH
This will load JForth. You will eventually see a new window pop up that has the Delta Research copyright. If you hit a carriage return, you will see an OK message appear. This is your sign that JForth is working.
You can now move on to the tutorials. When you are eventually ready to leave JForth, enter:
BYE
This will close the JForth window and terminate execution of JForth.
Insert your "JForth" disk in any drive. Double click on the disk icon to open it. Now double click on the "Assignments" icon.
This will run the ASSIGNS command file.
Repeat the above procedure for the "JTools" and "Extras" disks.
Now open the COM drawer on the Extras disk and double click on the JForth icon.
This will load JForth. You will eventually see a new window pop up that has the Delta Research copyright. If you hit a carriage return, you will see an OK message appear. This is your sign that JForth is working.
You can now move on to the tutorials. When you are eventually ready to leave JForth, enter:
BYE
This will close the JForth window and terminate execution of JForth.
We recommend having at least 1 Megabyte of memory. The operation of the Amiga is greatly improved by the addition of extra memory. You can use recoverable RAM disks and add extra disk buffers to speed up disk access. With enough memory and AmigaDOS 1.3 you can even reboot from RAM.
If you have an Amiga with 512K of RAM you will be able to run JForth but will not have much memory to spare. To give yourself room for JForth AND a text editor you may have to take some steps to reduce your memory consumption. Here is a list of some things you can do to give yourself more room. You probably do not need to do all of these things. Just pick what you want to try.
If you have been running your Amiga awhile, your memory can become fragmented. This is not as bad as it sounds. It just means that the free memory in your system is arranged in many small pieces instead of a few large pieces. JForth needs a large piece to fit in. By rebooting, you can reorganize the free memory on your system into larger pieces. I recommend getting a copy of the program AVAIL which will tell you how much memory you have and how big the largest piece is.
Rebooting will also clear out any fonts or libraries that other programs opened and left laying around in memory.
Before rebooting first make sure that all your applications have stopped because anything in RAM will be lost. To reboot, hold down the <CTRL> key and the two <AMIGA> keys simultaneously.
Another way to save memory, about 13K, is to give up using icons. You can prevent Workbench from loading by modifying your startup sequence to open a Shell instead of the Workbench.
Edit the file S:STARTUP-SEQUENCE. Change the following text at the end of the file:
LOADWB
to be:
; LOADWB NEWSHELL
Adding a semicolon will comment out a line.
The original JForth comes with 64K of free dictionary. If you don't need this much you can reduce the size of your JForth image by changing #K and using SAVE-FORTH. Use a BACKUP copy of JForth for this exercise. Enter in the CLI:
EXECUTE EXTRAS:ASSIGNS RUN COM:JFORTH
Now enter in JForth:
#K @ . \ print how much #K @ 20 - #K ! \ subtract 20K SAVE-FORTH COM:JForth BYE
Now enter in the CLI:
RUN COM:JFORTH
The new image will use about 20K less memory. Some large programs may not load in this smaller dictionary space. Please see SAVE-FORTH in the glossary for more information about this technique.
The Amiga operates best with 2 floppy disk drives or 1 floppy and a hard disk. Cost is a limiting factor for many people, however, so we have made provisions for running from 1 drive.
The most important thing to do when running from 1 drive is to limit the number of disk swaps you have to make. The Amiga will ask for the Workbench disk when it needs to load a command from the C: directory. You can avoid many of the requests for the Workbench disk by placing the necessary commands in RAM. The Amiga will be able to load these commands from RAM and not need the Workbench disk as often. (Please note that since these commands will take up RAM space so you might have problems if you only have 512K of memory.)
The commands that should be in RAM:, or made RESIDENT, are CD, DIR, RUN, EXECUTE, ASSIGN, LIST and COPY.