|
COPYRIGHT NOTICE
This software and manual are protected by United States copyright law.
You may not reproduce it other than for backup purposes in support of
your use of the software on a single computer.
No license or royalty is required for commercial programs developed
with GS16FORTH. Provide in writing, in your manual that the program is
based on GS16FORTH, copyright 1987 by GSF - San Jose, Ca.; Apple
Computer, Inc. requires you to obtain a license from Apple directly
for ProDOS16.
This software is provided "as is" without warranty as to its
merchantability or fitness of use of the software in any specific
application or purpose. GSF does not warrant that the operation of the
software will be uninterrupted or error free. The media the software
is provided on is warranted for 90 days from purchase, provided the
buyer has registered the purchase with GSF.
ProDOS 16 and System Loader are copyrighted programs of Apple Computer
Inc. licensed to GSF to distribute for use only in combination with
GS16FORTH. Apple software shall not be copied onto another diskette
(except for archive purposes) or into memory unless as part of
execution of GS16FORTH. When GS16FORTH has completed execution Apple
Software shall not be used by any other program.
Apple Computer, Inc. makes no warranties, either expressed or implied,
regarding the enclosed computer software package, it's merchantability
or its fitness for any particular purpose. The exclusion of implied
warranties is not permitted by some states. The above exclusion may
not apply to you. This warranty provides you with specific legal
rights. There may be other rights that you may have which vary from
state to state.
Apple II, Apple IIGS, ProDOS 16 and System Loader are registered
trademarks of Apple Computer, Inc.
TECHNICAL ASSISTANCE
Technical assistance is available for one year from date of purchase
by sending written questions only to:
GSF
1529 Torre Ct.
San Jose, Ca. 95120
This is available for registered owners only. Fill out the warranty
card and return. You will receive periodic notices of additional GS
Toolbox routines as they become available. The additional routines
will also be priced affordably.
The information in this manual is subject to change without notice. No
part of this manual may be reproduced in any form except by written
permission from GSF.
GS16FORTH VERSION 1.4 (October 1987)
WHAT'S NEW:
1. The boot and quit code (BYE) has been updated to follow Apple's
guidelines more accurately. No problems have been noted but future
toolbox and ProDOS releases may have been affected.
2. GS16FORTH now uses ProDOS16 prefix 3/ instead of 1/. Your
application can then use prefix 1/ to reference the current system
operating pathname at any time, regardless of your setting of the
GS16FORTH prefix.
3. The file RAMDEMO.SYS16 has been added to the standard package disk.
This is a stand alone application written using the standard calls
and part of the optional package number 1 that supports the RAM
toolbox. This entire program was written in only 2 weeks start to
finish. There's lots of error trapping but it's not guarenteed to
be bullet proof. RAMDEMO is relocatable code and requires 512K to
operate in. The actual code is only 9,500 bytes (decimal) beyond
the GS16FORTH extensions. Forth code is very compact. There is
still more than 32,000 bytes of programming space left in a single
GS bank.
Have fun with the game, make copies for your friends and co-workers
(the files MCMENU and MCHELP must also be copied to the same
directory) but remember, GS16FORTH and Apple's operating system
programs are copyrighted and should not be copied except for archival
purposes. Please respect this fact.
4. A screen file of utilities has been added. It is not documented in
the manual but contains directions in the source code. Included
are; Doer-Maker, DIRectory and DECOMPILE.
5. The optional package now supports relocatable code through the use
of bank alignment. The relocatable code requires 512K minimum
memory to operate. The code is included with the optional package
number 1 or separately for $8.00 (includes shipping and handling,
CA residents please include $0.56 sales tax.)
GS16FORTH TIPS
* Remember to work with a copy of GS16FORTH. In fact you must because
there are no free blocks on the system disk. Suggest you make a
working version by moving PRODOS and the SYSTEM subdirectory to a
new disk. Then copy GS16FORTH.SYS16, GS16ASM.SYS16, GS16EDIT.SYS16
and GS16TOOLS.SYS16 to the disk. Boot up the disk with
GS16EDIT.SYS16 and use the command MKDIR SCREENS {CR} to create a
screen subdirectory (or any other name you like). Then use the
command:
n CREATE.SCR {CR}
where n is the number of Forth screens in the file. DON'T FORGET n
OR YOU WILL ATTEMPT TO CREATE A FILE OF INDETERMINATE NUMBER OF
SCREENS.
* If you need to delete a file use the command:
SET.PNAME {CR}
and then supply the pathname. Then use the command:
DESTROY {CR}
which deletes the file. BE CAREFUL, DESTROY acts immediately without
recourse. If it's a screen file you need to delete use DESTROY.SCR,
which gives you a chance to abort.
* After making a new file, close it immediately and then reopen the
file. That way a power loss, crash or other accident will not affect
the file. If the file has never been closed since creation, all data
could be lost with a loss of power or reset. If it's been closed
once, all data should be safe that's been FLUSHed to the disk.
* Use GS16EDIT.SYS16 to create your program, then when it's debugged
compile with GS16FORTH.SYS16 or GS16ASM.SYS16 if it needs the
assembler. If your using the toolsets add the full-screen aditor to
GS16TOOLS.SYS16 and save to a new file name. When that program is
completed use GS16TOOLS.SYS16 to compile the final version.
* When you use the fullscreen editor the first time after booting you
are asked for a pathname to edit. Ater you have entered that file,
the next use of the word edit will immediately take you back to the
editing window. If you want to edit a different file, first
CLOSE.SCR {CR} the current file and the invoke EDIT again and it
will prompt you for a new file to edit.
* Once you enter the three letter ID for the fullscreen editor you may
press return the next time you enter the edit window and your
original input will be used. The ID will remain valid unless you
exit or reboot. If you compile the editor, you will be asked for the
ID during compilation. In the new version your default ID will be
valid right from startup.
* Forth gives you complete control of the IIGS. As such you will
probably encounter a time when you may "crash" the system most
likely by writing to memory somewhere you shouldn't have. In a crash
remember the following:
- If you are working in the Super Hires Screen and you crash (or think
you may have crashed) use (CONTROL-T) {CR}. If you are in the
monitor the text screen will be invoked automatically and you can
see the machine status.
- Remember in order to leave the monitor and return to Forth you must
check the mode flags. The correct values are: 0=X/0=m/0=e/1=B {CR}
(or B=current operating bank of GS16FORTH). Then use 01/08E4X {cr}
to return to Forth. If GS16FORTH does not restart most likely you
have corrupted the source code and you will have to reboot.
- If you crash and reset or are caught in a loop and want to reset
then you will have to reset twice. On the first attempt the Apple
ROM gives a fatal system error "Cannot reset Event Manager"
(remember GS16FORTH's keystrokes are coming from the event manager).
Pressing reset again should restart Forth and close all open files.
If you were using Quickdraw II, there may be some corruption with
the event manager. You are safest to close all files and reboot. If
you are not using QDII you can most likely continue working as
usual. The event manager is restarted for you and the Memory
Manager, Integer Math Set and the Misc Tools are active all the time
and do not require restarting. However after a reset you can no
longer quit back to the system loader, desktop or wherever you
booted from because the pointer has been lost. You will have to
reboot when you are done.
* To print, use the command n PR#, where n is the slot of your
printer. After printing use 3 PR# or if you're using the internal GS
interface, 9 EMIT 82 EMIT which returns you to the text screen. If
you have a printer that requires 7 bit ascii (HP Laserjet for
example) versus Apple 8 bit use:
HEX O OMASK O XC! 7F AMASK O XC! {CR}
to force 7 bit output. Restore to normal with:
HEX 80 OMASK O XC! FF AMASK O XC! {CR}.
If you don't restore you will get inverse text characters.
TABLE OF CONTENTS
INTRODUCTION
GS16 EXTENSIONS GLOSSARY
ProDOS 16 GLOSSARY
GS16FORTH 65816 ASSEMBLER
GS16FORTH FULLSCREEN EDITOR
GS16FORTH TOOLBOX GLOSSARY
GSCOMPILER
GENTOOLBOX
MEMORY MANAGER
EVENT MANAGER
QUICKDRAWII
GS16FORTH STANDARD GLOSSARY
DOUBLE NUMBER GLOSSARY
FIGURES AND TABLES
DISK DIRECTORY
FILE DESCRIPTIONS
GS16FORTH WORD STRUCTURE
GS16FORTH MEMORY MAP
GS16FORTH ERROR CODES
ProDOS 16 ERROR CODES
GS TOOLBOX ERROR CODES
GETTING STARTED
Welcome to Forth. Twelve to eighteen times faster than Basic,
structured programming, yet it offers the ease of direct keyboard
interpretation and the elegance of generating pure machine code easily
when required. If you are a newcomer to Forth, stop now, close the
manual and purchase a book that will introduce you to the language.
This manual could not do justice in providing you a satisfactory
indoctrination to the language. Like any other learning experience, it
will take time to become proficient in programming with Forth. The
book most recommended is, "Starting Forth". There are many other books
available. Search through them and find one whose style you feel
comfortable with. GS16FORTH is a fairly complete package. It includes
a full 65816 assembler, fullscreen editor and support for the four
major ROM toolbox sets. The interface to the programmer is the
standard Apple II 80 column screen. The use of graphics screens for
heavy editing tasks is not always desirable. The 80 column text screen
is fast and the graphics screens can be used for applications.
If you're an intermediate Forth programmer, read the section on
GS16FORTH extensions and examine the memory map. Specifically, you
must read the PRODOS extensions. Most FORTH systems treat a complete
disk as a batch of FORTH screens. The system reads and writes to disk
on a track/sector level and does not support any higher level PRODOS
routines.
With the increased capacity of micro-floppy disks (800K on the IIGS)
and the proliferation of hard disks, this brute force method creates
confusion by not allowing a directory seperation of Forth source code.
GS16FORTH can treat any file as a Forth screen file. By convention,
GS16FORTH adds the suffix .SCR to a filename in order to identify it
as a Forth source code file. A file may be any size up to 32,767
screens (32 megabytes) or the maximum storage allowed on the disk
device. GS16FORTH supports subdirectorys and many of the machine
language level PRODOS 16 system calls. These are described under
GS16EXTensions.
The first step is to use the system utilities or the desktop to make
one (two suggested) copies of GS16FORTH. Place the original and one
copy in safe areas. Work only with copies from now on. The intent of
the manual is to explain the differences and enhancements of
GS16FORTH. Very little pro- gramming is discussed. A good text and
the supplied source code will help you learn Forth. If you have
purchased the GS16FORTH package with the manual supplied as a text
file; this short introduction section is the only written
documentation you will receive. Review Figure 1-1 and Table 1-2 that
describe the contents of the GS16FORTH disk.
GS16FORTH DISK DIRECTORY
FIGURE 1-1
/GSF/---->/SYSTEM/
! /TOOLS/ /ATINIT
! /FONTS/ /ATLOAD.0
!
!
--->/SCREENS/
! ! /MISCTOOLS.SCR
! ! /EVENTMGR.SCR
! ! /MEMANAGER.SCR
! ! /QUICKDRAWII.SCR
!
! /ASM65816.SCR
! /FSEDIT.SCR
! /MAKEPERM.SCR
! /APPLICATION.SCR
! /DEMO.SCR
! /DNUMBER.SCR
!
!
--->/MANUAL/
! /GS16INTRO
! /GS16FORTH
! /GS16ASSEMBLER
! /GS16EDITOR
! /GS16EXT
--->/PRODOS /GS16TOOLS
! /GS16DNUMBERS
!
!
--->/GS16FORTH.SYS16
/GS16ASM.SYS16
/GS16EDIT.SYS16
/GS16TOOLS.SYS16
/GS256K.SYS16
/GS16DEMO.SYS16
FILES DECRIPTIONS
TABLE 1-2
I. /GSF/
1. PRODOS: An initialization file designed to load up PRODOS. The name
was kept as PRODOS to allow the same boot firmware.
2. GS16FORTH.SYS16: Forth core system. Includes standard code,
PRODOS16 16 extensions and some GS16 extensions.
3. GS16ASM.SYS16: The base code plus the 65816 assembler pre-compiled.
4. GS16EDIT.SYS16: The base code, the assembler and the full screen
editor pre-compiled.
5. GS16TOOLS.SYS16: The base code, assembler and all of the supplied
tools and double numbers pre-compiled.
6. GS256K.SYS16: Functionally equivalent to GS16FORTH but requests
slightly less memory ($1000 bytes) to allow it to run on standard
256K systems.
7. GS16DEMO.SYS16: A short demo program that displays the use of some
of the tool calls. The program only requires 1600 (decimal) bytes
beyond the code in /GS16TOOLS.SYS16.
II. /SYSTEM/
1. P16: This is the real PRODOS16.
2. P8: Prodos 8.
3. Other files and subdirectorys to support tool initialization and
loader activities.
III. /SCREENS/
1. GSCOMPILER.SCR: This is the actual source code for the core Forth
system. This allows Forth to make a copy of itself in memory and
create a new version.
2. ASM65816.SCR: Source code for the 65816 assembler.
3. FSEDIT.SCR: Source code for the fullscreen editor.
4. MAKEPERM.SCR: Source code to alter the boot literals and to create
the Object Module Format required by PRODOS16. Used to save an
extended version of Forth to disk.
5. APPLICATION.SCR: Similar to MAKEPERM.SCR except this code collapses
the disk buffer and user variable location to just
above the end of the current code. No further additions to code can be
made or a crash will occur. Used to create standalone applications
with minimum memory constraints.
6. DNUMBER.SCR: Source code for double number (32 bit) words.
7. DEMO.SCR: Source code for the demo program showing how to use the
toolbox routines.
IV. /SCREENS/TOOLBOX/
1. GENTOOLBOX.SCR: Reusable machine language routines that allow you
to code added toolbox calls in Forth only.
2. MEMMANAGER.SCR: Code for memory manager calls.
3. EVENTMGR.SCR: Code for event manager calls.
4. MISCTOOLS.SCR: Source code for most mouse calls not included in the
event manager. Also contains call to use old Apple II ROM routines.
5. QUICKDRAWII.SCR: Source code for the quickdraw toolbox.
Includes most standard graphic calls. Missing are the more exotic
region and poly commands.
V. /MANUAL/
1. PRINT.SCR: Forth source code to print the manual if you do not wish
to use a word processor.
2. GSINTRO: Text file of this section PLUS more. Print it if you did
not purchase a manual.
3. GS16FORTH: The standard Forth glossary.
4. GS16ASSEMBLER: How to use it but a glossary is not supplied. All
256 opcodes are supported.
5. GS16EDITOR: How to use, with a partial glossary.
6. GS16EXT: Glossary of PRODOS16 extensions and others.
7. GS16TOOLS: Partial glossary of the toolset supported calls.
You have two choices to access the manual files. You may use a
standard Word Processing package, such as Appleworks, to load the
files, browse and print as required. If you do not have access to a
word processor, there is Forth screen code to print it for you. The
manual is located on the GS16FORTH disk under the pathname
/GSF/MANUAL/.
To print one or any combination of files, type:
(Note: your typing is shown in capital letters, Forth's response in
lower case. Carriage returns are shown {CR}.)
/gsf/ CD MANUAL {CR}
/gsf/manual/ LOAD.SCR {CR} pathname? PRINT {CR}
The disk drive will spin and a print routine will be compiled and
automatically started. Answer the prompts, make sure your printer is
ready and start printing (standard Apple II firmware is used so there
should not be any compatability issues). The GS16FORTH manual is
nearly 100 pages, so be prepared to be there awhile. Print out the
introduction section also, it contains more important information
beyond these brief instructions.
256K USERS ONLY
If you only have a 256K (minimum Apple IIgs) than you will only be
able to load the GS256K version of GS16FORTH. This version leaves
$1000 bytes of space in bank 01 for the use of PRODOS16 and the system
loader. If you try to load one of the others you will get the message
0201, (can't allocate block). You will create your own version of
GS16ASM.SYS16, GS16EDIT.SYS16, etc. The instructions are listed at the
end of the introduction and the process takes about ten minutes.
Note: Manual, non-purchaser's receive printed matter to here only.
YOUR FIRST GS16FORTH PROGRAM
First make a copy of your GS16FORTH system disk. You should transfer
the following files to your working disk.
1.System subdirectory and all of the tools, fonts drivers, etc.
subdirectories and files in the system directory.
2.GS16FORTH.SYS16, GS16ASM.SYS16, GS16EDIT.SYS16 and GS16TOOLS.SYS16.
(256K versions of these if you only have a 256K machine)
3.The SCREENS subdirectory with MAKEPERM.SCR, APPLICATION.SCR and
DNUMBER.SCR.
4.The TOOLBOX subdirectory with GENTOOLBOX.SCR, EVENTMGR.SCR,
MEMMANAGER.SCR, MISCTOOLS.SCR and QUICKDRAWII.SCR.
It's suggested that if you have two disk drives that you format a data
disk that will hold your source code files (screen files). Format a
disk and name the volume /SCREENS/. If you only have one disk drive
we'll use the /SCREENS/ subdirectory on the working system disk. The
total pathname would be /GSF/SCREENS/.
Put the working copy of your GS16FORTH system disk in your boot drive
and power on the computer or reset the computer. When the system
loader dialog box appears choose GS16EDIT.SYS16 and open the file. The
program should boot and you will see the GSF header and the prompt
/GSF/. Now type: (Note: your typing will be shown in caps and the
system responses in the lower case)
/gsf/ CD /SCREENS/ {CR} [two drive example]
or
/gsf/ CD SCREENS {CR} [one drive example]
Note: from now on if you are using a one drive system your prompt will
be /GSF/SCREENS/ instead of /SCREENS/.
To create a screen file type:
/screens/ 5 CREATE.SCR {CR} pathname? TEST {CR}
The disk drive will start, the screen file will be created and
initialized. The screen file automatically has .SCR appended to create
the file named TEST.SCR.
[Note: The number of screens to create is placed before the operating
word. Forth is a postfix environment (like HP calculators) that uses a
parameter stack to pass values to routines. When your entry 5 is
interpreted it is recognized as a number, converted to binary and
placed onto a stack as a 16 bit number. CREATE.SCR expects to reach
into the stack and pull the top number as the quantity of screens to
create. The Forth glossary will typically display a stack picture
before and after execution of a Forth word. If you look up CREATE.SCR
in the manual you see:
CREATE.SCR n --
The n means that the word expects a 16 bit number on the stack prior
to execution. The -- represents the execution of the word CREATE.SCR
and the blank area after -- means that the value n was removed from
the stack. Of course any values on the stack below n are left
untouched. Refer to your Forth text for a more complete description of
the parameter stack.]
Now that the screen file has been created it has been left open for
you to work with. Type:
/screens/ EDIT {CR}
The text screen will clear and the cursor will jump to the home
position and ask you which screen to edit, enter 1 {CR} (Note there is
a logical screen 0 but you should never use screen 0 as it's contents
cannot be saved back to disk. The editor in general keeps you away
from screen 0 but standard Forth words such as LIST, LOAD, etc. will
call screen 0). You are then prompted to enter an ID. Enter your
initials (if less tha 3 characters then end with a {CR}). The editing
window should open and the cursor should be in the top left corner of
the window. Below the window is a summary of most of the editor
commands. On screen 1 line 0 enter:
\ Test Screen 1
Move down the window and enter the following lines:
Line 1: decimal
Line 2: : SQR \ n -- n*n
Line 3: DUP * ;
Line 4: : .SQR \ n --
Line 5: SQR . ;
Line 6: : DOSQRS \ n1 n2 --
Line 7: 1+ SWAP \INC INDEX AND SWAP POSITIONS
Line 8: DO I .SQR LOOP ; \COPY INDEX, CALC & PRINT
Line 9: ;S \STOP INTERPRETING SCREEN
The word Line, the number and colon are for reference. Do not enter
them on your computer. Also note on line 0 there must be a space
between \ and Test. \ is a Forth word and like any other word it must
have a space on each side to allow correct interpretation. Note: \ is
the Forth word to create a comment line, which is a pseudo-standard in
Forth.
The program is complete now so let's exit the editor by pressing
{esc}. Notice the disk drive was active as you exited. When you
changed the screen's contents you set a flag that the screen needed to
be saved to disk. Now enter:
/screens/ 1 LOAD {CR}
The code we just entered should be compiled and added to the Forth
dictionary. To check it let's try running the program. Enter:
/screens/ 1 10 DOSQRS {CR}
Hopefully, you're now looking at the squares of the numbers from 1 to
10. Let's assume we don't like the format of the output and we want to
go back and change the code. Enter:
/screens/ EDIT {CR}
The editor assumes you want to edit the screen file that you left open
(if you want to edit a different file use CLOSE.SCR then invoke EDIT.
You will be asked for a new pathname to edit). You are asked again to
enter your ID. This time you may just press {CR} and your original ID
will be defaulted to. Use the cursor keys to move down to line 5 of
screen 1. Press {open-apple} and E at the same time. The cursor will
switch to an underline. This is the insert cursor. Use the right arrow
key and move to the letter S; now type:
CR {space}
Line 5 should now read:
CR SQR . ;
Press {open-apple} E again to switch back to the overstrike cursor.
We'll add more functions on screen 2 but first we have to tell screen
1 that we want compilation to continue to screen 2. Still on screen 1
use the cursor keys and move to Line 9, placing the cursor over the ;.
Now Type:
-->
Line 9 should now read:
-->
When compiling, this word tells the interpreter to continue compiling
with screen 2. Press {open-apple} {up-cursor} to move to screen 2. On
screen 2, line 0 enter:
\Test Screen 2
Then enter the following:
Line 1: decimal
Line 2: : DOITALL \ --
Line 3: 12 EMIT \ CLEAR SCREEN
Line 4: ." PRINT SQUARES FROM 1-10" \PROMPT
Line 5: CR 1 10 DOSQRS ;
Line 6: ;S \ STOP INTER.
Now press {esc} to exit the editor. Then type:
/screens/ FORGET SQR {CR}
This erases the previous compilation from the dictionary. Now type:
/screens/ 1 LOAD {CR}
This time both screens should compile. Now let's execute the topmost
word of our program. Enter:
/screens/ DOITALL {CR}
The screen should clear, a prompt is printed followed by a column of
squares from 1 to 10. Now that we have a sucessful program let's
continue the exercise to save this custom version of Forth to disk.
Type:
/screens/ CLOSE.SCR {CR}
The disk should activate, the file is time and date stamped by
ProDOS16 and the file closed.
The typical working scenario is that you would boot the GS16EDIT.SYS16
program, create a screen file, enter the source code, compile and
debug the program; as we just did in the example. When the program is
complete you may run it at any time by recompiling it (Load it) and
invoking the Forth word or words. However, you may wish to save the
time of compiling and save a pre-compiled (custom) version to disk. If
you did not use the assembler most likely you would now boot
GS16FORTH.SYS16 and use that as the base to compile onto. [Note: if
you have used the assembler you would use GS16ASM.SYS16 as a base. If
you are saving an intermediate program that would still require
editing you can use the GS16EDIT.SYS16 as the Forth to compile onto.
Finally if you have included Toolbox calls in your program you would
use GS16TOOLS.SYS16]. The process of saving a custom version is: boot
your base Forth system (in this example GS16FORTH.SYS16), open your
screen (source) file and compile (load) the source code. Let's try it.
From the system loader dialog box open the GS16FORTH.SYS16 program.
After it boots then enter:
/gsf/ LOAD.SCR {CR} pathname? /SCREENS/TEST {CR}
Make sure your program disk (volume /SCREENS/) is still in one of your
disk drives. If you have one disk then you would enter SCREENS/TEST.
(If the pathname does not start with a / then the pathname you supply
is appended onto the system pathname /gsf/). The program should
complile and you should be greeted with the familar OK. Now type:
/gsf/ CLOSE.SCR {CR}
This will close your source code file. Now Enter:
/gsf/ LOAD.SCR {CR} pathname? SCREENS/MAKEPERM {CR}
This loads the source code from the screen file MAKEPERM.SCR located
on the /GSF/ volume. The file should open and screen #1 will load.
Screen #1 alters the boot-up variables to permanently set the
dictionary pointer and other user variables to their current values.
You are then prompted to load screen #2 if you wish to save to disk.
Type:
/gsf/ 2 LOAD {CR}
The disk will start and you will be prompted to enter the filename to
save to. By convention you should add .SYS16 as a filename suffix.
Enter:
enter pathname to save to: TEST.SYS16 {CR}
If the filename exists you will be prompted if you wish to overwrite
the file. In this example you should not get this prompt (unless you
are running the example for a second time). Then you will be asked if
this version of Forth is required to run on a 256K machine. Enter Y or
N as appropriate. If you aborted the save by answering N to the
overwrite prompt you can start the sequence again by invoking 2 LOAD
{CR} a second time. If a ProDOS error occurs during the save you
should correct the source of the error then type:
/gsf/ COLD {CR}
/gsf/ 2 LOAD {CR}
After you've entered all of the filenames and the prompts the disk
will continue to work and finally save the file to disk. To check our
custom version of Forth enter:
/gsf/ BYE {CR}
This will send you back to the system loader screen. You should see
our new file TEST.SYS16 in the directory. Open this file and the
program should boot-up. In order to check the version enter:
/gsf/ VLIST {CR}
The dictionary should begin to be listed on the screen. After a few
lines have been printed, press {esc} to stop the listing. You should
see the new Forth words listed at the top of the dictionary. Now
enter:
/gsf/ DOITALL {CR}
The program we created should run as before. It is now available as
part of your custom Forth. This is the same method that
APPLICATION.SCR uses to create a stand alone application, except that
after a save with APPLICATION.SCR you cannot add further source code
to the program. The manual and source code describes how to make an
application autostart.
UNDER THE HOOD
Let's discuss what GS16FORTH looks like and how it operates. Forth is
a threaded interpretive language. That is, the language is composed of
many small routines that you create as you program. There is a core of
Forth words that are standard. The most notable are FIG-FORTH and
Forth-79. GS16FORTH is based on the FIG-FORTH model but includes some
of the more important extensions available under Forth-79.
Applications can be converted between the two with only minor changes.
Another standard Forth-83 differs significantly from the first two in
the branching standards such as the word LEAVE. Conversion between
Forth-83 is possible but not as easy. The core of GS16FORTH is
described under the section Standard Glossary.
Forth routines are called words, not to be confused with the memory
term word (16 bits). Appropriately, Forth considers the words to be
compiled into a "Dictionary". The dictionary can even have seperate
vocabularies, the standard ones are Forth, Assembler and Editor. The
concept is the same as a verbal language. As we grow we learn new
words that we use. In Forth you program new words which become part of
"your vocabulary". Once you have programmed a word it is your's to use
in hundreds of applications yet to come. This can sound complicated
but it is really the opposite once you begin to understand the
concept. If your new to Forth you're probably very confused by now.
Make sure you purchase an appropriate text to help you learn the
language.
As words are compiled the dictionary grows upward in memory. Let's
take a look at the structure of a typical Forth word.
FORTH WORD STUCTURE
Low Memory Name Field of <----
Previous word !
!
!
Name Field Addr->! Length Byte !<
!
! C ! ! !
! M ! ! !
! O ! ! !
! V ! ! !
! E ! ! !
!
LFA->!Link Field Addr!---- !
!
PFA->!Param Field Adr! !
!
CFA->!Code Field Addr! !
!
! ! !
! ! !
! ! !
! Code Body ! !
! is here ! !
! ! !
! ! !
! ! !
!
! Code for Exit ! !
!
!
!
High Memory Link Field Addr
of next word
The actual code body consists of 2 byte pointers that are the CFA
(code field addr) of the Forth words that makeup this routine. You can
see why they call it a threaded language. A linking "thread" is the
Name Field Addresess. That's also why Forth can be used interpretively
and compiled. When text is taken from the keyboards, a search begins
along the thread until it finds the word or until the end of the
dictionary (Message #0 not found). When the word is found the CFA for
the word is then executed. When used interpretively, the search slows
down the execution. However during compilation of new words, the CFA
is compiled into a newly defined code body. When the new word is
executed there is no need for a search since the CFA is already known.
This is one of the best features of Forth. In traditional compilers
you must create a text editing file, save the file
to disk, run the compiler and then execute the program. If a
compilation or execution error is detected, you must begin the
sequence again. Forth on the other hand let's you compile as little as
a word at a time. That word can be debugged and proven before you
continue. The best philosophy in Forth is keep the words small and
easliy proven in. It speeds up development time.
Like any Forth system, the most primitive words are coded in machine
language and the higher level words build on the primitives. Once a
Forth word is compiled it is treated exactly like any other word, even
if it was coded with the 65816 assembler. Thus a program can be
written in high level Forth, proven in and then the time critical
areas coded in machine language. It's even possible to use the Forth
assembler to code time critical interrupts.
Most people will tell you that there's a right language for each
occasion, but many are satisifed using only Forth. The most notable
piece missing for newcomers is the lack of floating point. That is an
option with GS16FORTH and is built on the Apple SANE toolbox.
WHAT'S DIFFERENT IN GS16FORTH
GS16FORTH follows the above description. The difference is in the way
the primitives are coded in machine language. The Apple IIgs has the
65816 microprocessor that is capable of handling 16 bits at a time.
Most Forth's for the Apple II series are based on the 6502 or 65C02
microprocessors that were only 8 bit engines. GS16FORTH runs in true
native mode. That means that the accumulator, x register and y
register flags are all set to 0 and 16 bits wide. This makes GS16FORTH
about 20-30% faster than most 8 bit Forth's. In addition the data bank
register and program bank register are all active which means up to 8
MB of memory could be addressed in the IIgs. GS16FORTH can access this
data in a standard 65816 context, including the IIgs' extensive ROM
toolbox routines !
GS16FORTH is restricted to all code being within one bank and it is
fixed non-relocatable code (standard package). This differs from the
concept of relocatable code for the IIgs; but in Forth programming it
makes sense to have a large contiguous memory block available. There
is now a version of GS16FORTH that uses forced bank alignment to
create relocatable code. This would only be used for commercial
applications, it requires a minimum 512K IIGS and is included with the
purchase of the Optional Package #1 (RAM based tools). The fact that
the code is fixed is probably not important to the hobbiest but it is
notable for the software developer. Forth is one of the most memory
efficient languages around; you can write extremely compact programs
with a lot of efficiency. Almost all programs
written for the 65816 (of any language) are restricted to indivdual
modules written for one bank. With GS16FORTH there is a utility
provided that will minimize the memory block required when you have
finished an application. This makes it less restrictive to an end
user.
Do not be overly concerned when you begin to think about the size of
the IIgs toolbox and the amount of memory consumed. The routines
supplied are the workhorses. As you add higher level routines (ie,
window manager, menu manager, etc.) you will probably need less of the
lower level routines because the toolboxs call each other.
One big advantage with GS16FORTH is that the primitives and supplied
Forth words are written to be bank independant. If you have more than
the standard 256K, you can choose which bank of memory you wish to
load into. Only one byte on the Object Module Format header has to be
changed. A utility for converting GS16FORTH system files is found
under the APPLICATION screen file on screen number six. That means you
can write modular code and have 2,3 or more modules in memory and
switch between them at will. You could place a data manipulation
module in one bank and the graphing module next to it. Data could be
passed and much larger code emulated. It's important that you try and
keep GS16FORTH this way to allow the expanded or application versions
to remain bank independant. Just remember to never refer to the
current program bank directly; either use the high level word DB@
which leaves the CURRENT program bank register. In assembler use the
code:
phb, phb, pla, 00FF # and,
this will leave the current program bank in the accumulator. Also
maker sure you use the memory manager and handles when accessing any
memory outside of the GS16FORTH bank. The method of using the memory
manager is described under the section GS16TOOLS.
GS16FORTH MEMORY MAP
FIGURE 1-3
BANK 01 BANK 00
! ! ! !
!Lang. ! ! ! !P16!
! Card ! ! ! ! !
$D000
!SLOT I/O ! !SLOT I/O !
$C000
!User Var.! ! !
$BE80
!Disk Buf ! ! !
First $BA00
Top/TIB $B900
First 256K $AA00
Top 256K $A900
! ! !
! ! ! !
! ! ! !
! ! ! !
! ! ! !
! ! ! !
! ! ! !
--- --- --- ---
--- --- --- ---
! ! ! !
! ! ! !
GS16EDIT.SYS16 $4DEB--->!
!Edit Code! ! !
GS16ASM.SYS16 $380F--->!
!Asm Code ! ! !
GS16FORTH.SYS16 $2A5C -->!
! ! ! !
!Std Forth! ! !
!Code Body! !
Origin $08E0
$0800
! ! !
!
Dir.Page
THE GS16FORTH MEMORY MAP
A little explanation is required. Since the 65816 uses a 16 bit stack
pointer the stack can now be located anywhere in page zero and may be
larger than $0100 bytes. PRODOS16 now controls the location of the
stack with the use of the memory manager. It could be different each
time on booting. Usually it's at $0BFF; (The actual stack value is
stored at
$14 +origin). This helps complex programs avoid crashing due to stack
overflow. All 8 bit programs have only $100 bytes from $0100 to $0200.
GS16FORTH is allocated $400 bytes each time. At startup the location
of the stack is stored at $10 +origin in the boot up literals. The
direct page is also allowed to be moved anywhere in memory and
typically it's at the bottom of the $400 stack/direct page block. In
GS16FORTH the direct page has been kept at $0000 in order to make
access to the ROM text functions easily available. Also in the direct
page is the parameter stack for passing values. It starts at $00/009E
and grows downward. At $00/0100 to $00/0130 is a safe stack area used
when the word EMIT accesses the standard text ROM.
At $01/B900 is the terminal input buffer and at $01/0800 the entry
code to GS16FORTH. The actual Forth origin is at $01/08E0 for a cold
start and $01/08E4 for a warm start.
If you use the word MON to enter the Apple monitor, you must make sure
that all flags are set correctly before returning to GS16FORTH.
Remember, the x, m, and e registers must all be 0. If are in bank 01
then enter 8E4X to renter Forth. If the bank was changed use,
01/08E4X.
BOOT PROCESS
When GS16FORTH is booted it is loaded at $01/0800 (provided you have
not changed the bank). When it is loaded it "asks" for all of BANK 01.
(Note:Because memory is dynamically allocated by the memory manager,
the whole block must be allocated up front or you risk the memory
manager giving space away with code you've added as you expand the
dictionary (needless to say this would cause a system crash!). If you
have more than 256K, it will receive the memory block unless you have
other utilites installed. That's providing you do not have your RAM
disk set abnormally high. 256K users remember to initially load your
special version and save using the 256K option when creating new Forth
versions. If you ever experience loading problems (error code 0201),
check your RAM disk size or try a COLD BOOT to make sure there are no
"old" memory conflicts considered by the memory manager.
NOTE 256K USERS:
In a 256K system the disk buffer and the fence TOP are $1000 bytes
lower. That's not a significant limitation considering the compact
code of Forth.
If you wish you could always load into a totally open bank and achieve
almost a total $64K of programming space. However most people program
to fit minimum configuration machines when possible. If you need more
space the relocatable version allows almost an entire bank of
contiguous memory.
MAKING PERMANENT CHANGES OR FINISHED APPLICATIONS
As you add words to Forth you may want to save intermediate versions
that you use often or save a completed program either for your own or
commercial use. 256K users will have to do this immediately as the
supplied pre-compiled versions will not boot on their machines.
Use the LOAD.SCR {CR} command to load any of the supplied code, or
load individual screens of your code or the supplied code.
NOTE 256K USERS:
256K users need to load the ASM65816.SCR and FSEDIT.SCR source code.
After each of these files load, you will be asked if you wish to save
to disk. Follow the prompts, and save the new Assembler and new Editor
versions to disk. Remember to answer that you want to save a 256K
version.
Once your files are compiled (loaded), close the file with
/gsf/CLOSE.SCR {CR}.
Then Type:
/gsf/ CD SCREENS {CR}
/gsf/screens/ LOAD.SCR {CR} pathname? MAKEPERM {CR}
The disk drive will start and new boot up parameters will be stored at
the origin area. You will then be asked if you want to save the new
version to disk.
If you are ready type:
/gsf/2 LOAD {CR}
You will be prompted to supply a file name. If the file already exists
then you will be asked if you want to write over the file. The last
prompt asks if you want to save a 256K version. Then the save action
begins, some flags are set, a file header is coded as PRODOS16's new
Object Module Format. When complete the save routine closes both the
new file and the screen file all you need to do to test your new
version is type:
/gsf/ BYE {CR}
You will return to the system loader program and you may start up your
new Forth. The file should boot and you can use the command VLIST to
confirm that the new version is available.
To make standalone application files the process is the same except
use the code file, APPLICATION.SCR. This method unlike the MAKEPERM
save gives up all unused area of memory page 1. APPLICATION only
claims the area needed for the body, the disk buffer is moved down in
memory to be adjacent to the code and the user variable area is placed
right after that. You CANNOT add to a FORTH system saved with the
APPLICATION screen because new words would enter immediately into the
disk buffer. The constant Top is also lowered to disallow any
additions to the dictionary. If you want your Forth system to
autostart when booted use:
/gsf/' CCCC CFA ' (ABORT) ! {CR}
Where CCCC is the word you want executed immediately at startup. Look
at the source code for demo and see how this was done. Enter this just
before you load screen 2 of APPLICATION.SCR but after you have loaded
screen 1. Do not invoke the word COLD or (ABORT) until the application
is saved or the application will start up. In order to ensure a safe
startup the first commands of the startup word must be:
SP! EMPTY-BUFFERS
If you want the routine to autoexit then it must end with:
4 TSTAT IF QDSTOP ENDIF BYE
If you've added additional toolbox routines shutdown all of them at
this time. The word BYE automatically shuts down the EventMgr and
diposes of all memory blocks.
GS16FORTH ERROR CODES
Decimal Hex Message
0 0 Word not found after Search
1 1 Empty Parameter Stack
2 2 Dictionary Full
3 3 Incorrect Address Mode
4 4 Isn't Unique (duplicate name)
6 6 Disk Out of Range (Screen file
is smaller than request)
7 7 Full Parameter Stack
8 8 Disk Error.(In general
PRODOS16 errors are returned.)
17 11 Compilation only, use in def-
nition.
18 12 Execution only (look for
missing ;)
19 13 Conditionals not paired
20 14 Definition not finished
21 15 In protected dictionary
22 16 Use only when loading
24 18 CURRENT and CONTEXT
vocabularies don't match.
25 19 Ref# is not 1. If a file is
open cannot access. Use 0
CLOSE, 0 REF# ! to clean up.
GS16FORTH FULL SCREEN EDITOR
The full screen editor is made up of many smaller definitions. This is
the traditional method of building FORTH applications. The words exist
in the EDITOR vocabulary. The main entry word to the editor, EDIT
exists in the FORTH vocabulary and invokes the EDITOR vocabulary
automatically. This manual will only address the operation of the
editor commands and not the sub-words. You are invited to examine the
source code to find words that will be useful in other applications.
This includes words such as UTAB, HTAB, CLR, etc. The source code
gives a picture of the stack before and after execution. The name of
the word is usually descriptive enough to determine the action.
The FSEDIT.SCR file can be loaded or you may position the
GS16EDIT.SYSTEM file as the first system file on a disk. The system
file is the GS16FORTH base, the assembler and the fullscreen editor
already compiled and saved. This will cause the editor to be loaded
and available at boot time.
The editor consumes a relatively large amount of memory. However, once
a source file is fully debugged, it is compiled using only the base
FORTH system or base FORTH plus the ASSEMBLER System.
The operation of the editor is simple. From FORTH type EDIT. The
system will prompt you for a pathname of the screen file you wish to
edit. Enter the name and press return. The system will ask for an
I.D.. This is a three (3) letter abbreviation to identify the
programmer of the screen. If you have preset this during the loading
and saving of the editor system, the I.D. will default to that. Each
time a screen is edited, line 0 of the current screen is "stamped"
with the I.D., the time and date of the editing. This assumes that
line 0 is a comment line and the I.D. stamp is protected from being
interpreted either by \ or ( ; the backslash is recommended because (
requires a following ) that would have to be on line 1. After
entering the I.D. or return, a window of 16 lines by 64 characters
appears on the screen. This is the standard FORTH screen size. Below
the window is a summary of most of the editor commands. Editor
commands are invoked by pressing the open apple key and the
appropriate command key.
EDITOR COMMANDS
{any printable key} Changes the source code in the disk buffer and
marks the buffer as updated. Later use of word flush will save the new
contents back to disk.
{esc} Leave the fullscreen editor. If the current disk
block was updated then it is saved back to disk.
Flushes the disk buffer.
{cursor keys} Moves the cursor within the editing window; Up,
down, left or right.
{delete} Delete the current character at the cursor
position. Slides the remainder of the screen
line left but does not affect other screen
lines.
{tab} Tab right in increments of 10 spaces.
{return} Go to start of next screen line. If on last
line, go to start of last line.
{open apple} E Toggle between the overstrike cursor and the
insert cursor. Inserting only occurs on a per
line basis without wrap around.
{open apple}{up crsr} Jump to next higher screen. If current screen is
marked as updated then it is saved to disk. If
already at the highest numbered screen in the
file then no action is taken.
{open apple}{dn crsr} Opposite of up crsr. If at screen 1 then no
action is taken.
{open apple} I Insert line at current CRSR position. Current
line and all higher lines are pushed down one
line, the last line (15 of 0-15) is lost.
Inserted line is filled with blanks ($20).
{open apple} {delete} Clear from cursor position to the end of line.
Cleared area is filled with blanks ($20).
{open apple} {tab} Reverse tab. i.e. move left in increments of
10.
{open apple} J Jumps to another screen. Prompts for screen to
jump to. If an invalid response (i.e. key error)
is given, you must use the word Edit again to
renter fullscreen editor.
{open apple} C Cut lines and save at pad. Current cursor line
is highlighted. Use up and down CRSR keys to
create a block to be cut (full lines must be
cut). If the initial cursor location was wrong,
use {esc} to release the anchor and move to the
correct starting line; then press {period} to
reset the anchor. After the block is
highlighted, press {return} to cut the block.
{open apple} P Paste the most recent block cut onto the current
editing screen. You must highlight the area to
be pasted (as in cut). You can use {esc} and
{period} to move the anchor as in cut. After the
block is highlighted press {return} to paste the
block.
{open apple} U Undo. All editing since the last block save is
lost and the current block is read back from
disk.
One use is to copy partial screens. Use CUT to save lines to pad. Use
UNDO to forget the cut. Change screens and use PASTE to copy previous
code onto the new screen.
{open apple} A Abort current screen, throwing out all changes
since last save. Prompt asks for new screen to
jump to.
{open apple} D Used to copy the entire current screen to
another screen. Prompt asks "copy to screen #
?"; enter the screen number. The editor briefly
displays the target screen and asks if you want
to continue. If yes {Y or y} then screen is
copied and editor stays at the target screen. If
no, copy is not completed and you are returned
to the previous screen.
GS16FORTH EDITOR GLOSSARY
In addition to the direct commands there are additional GS16FORTH
EDITOR words available. This is a partial glossary only. You must
enter {esc} to exit the editor before using these words.
EDIT --
Enter the fullscreen editor. Prompt asks for ID, if none, uses default
and editing window is opened.
COPY n1 n2 --
Copy screen n1 to n2 within the same screen file.
COPY.SCRS n1 n2 n3 --
Copy from screen n1 to n2 inclusive, to another screen file starting
at destination screen n3. Only used to copy between separate screen
files. Prompts are given asking for the pathname of each screen file.
RAMEDIT --
Prompts for a screen file pathname, creates a duplicate file in the
RAMDISK (assumes Ramdisk is /RAM5) and then transfers editing to the
ramdisk file. Any PRODOS errors are returned as message numbers. (see
PRODOS error list). When exiting from Ramedit {esc} a warning is
issued to use SAVERAM in order to save changes to disk. This takes the
place of multiple screens buffers to reduce disk drive activity. If
you leave edit window with {esc} use the standard EDIT command to
renter the previous ramdisk file but use /RAM5 as prefix to the file
name.
SAVERAM --
Saves the recent RAMEDIT file back to disk. Will prompt if you wish to
overwrite disk file. If GS16FORTH is reset and
reloaded SAVERAM will not work as the file names are lost. The RAMDISK
file will still be correct and you should use COPY.SCRS to save if
required.
WHERE IN BLK --
If a compilation error occurs, the word ERROR leaves the values of IN
and BLK on the stack. The word WHERE uses these values and types the
screen number, the actual code at the affected screen line and marks
the word that the error ocurred at.
The standard FIG-FORTH line editor is not included. However, the
source code for the line editor is in the public domain and you are
welcome to create your own if desired. I have tried the standard
FIG-FORTH code and it works fine.
Again, there are a lot of useful FORTH words defined in the FSEDIT
editor. Some are MTEXT & NTEXT for mousetext characters, VTAB & HTAB
for screen output, VW & HW to set screen window limits, ASCII to
compile an ascii character value, GET# to get a 16 bit number from the
keyboard, READTIME to get current time and date in ascii output and
HLITE to inverse characters on the 80 col text screen. Feel free to
browse the source code to pick out words for your application.
THE GS16FORTH ASSEMBLER
The assembler generates pure machine code. A word or dictionary entry
that has been compiled using the assembler is then called exactly like
any other FORTH word. In most cases a programmer will write the
initial application in high level FORTH words. When complete, selected
time critical words may then be rewritten using the assembler. The
reconstructed words can then be dubugged interpretively before being
recompiled as part of the total application. FORTH is fast but when
refreshing a complete text screen or using advanced graphics on the
super hires screen, machine language will probably be required.
Another reason to use the assembler is that machine language is the
only interface to the Toolbox and to PRODOS 16. Many of these routines
are already included as part of GS16FORTH, but you may wish to add
more yourself. The source code is included so you have many examples
of these routines.
If you have used a 6502, 65C02 or 65816 assembler before, the use of
the GS16FORTH is not difficult. If you have not programmed in machine
language before then it is recommended that you purchase a text on the
65816 processor. The major difference in FORTH assemblers is the
syntax. If you are now comfortable with FORTH, the parameter stack and
reverse polish notation; the use of the assembler will be easy. In
standard assemblers, the opcode mnemonic is first followed by a
combination of addressing mode (if req.) and operand. The GS16FORTH
65816 assembler is exactly the opposite.
Standard Assembler GS16FORTH Assembler
LDA (FE),Y FE )Y LDA,
The more you know about FORTH the more obvious this becomes. When the
above example is compiled, $FE is a 16 bit number that is pushed onto
the parameter stack. )Y is a FORTH word in the assembler vocabulary.
It executes and sets the value of specified variables that will be
used to determine the correct opcode to compile. At this point nothing
has actually been compiled into the FORTH dictionary. LDA, is another
FORTH word in the assembler vocabulary. This word tests the variables
previously set by )Y, determines the correct opcode and compiles it,
recognizes the size of the operand required and pulls it from the
parameter stack and compiles it into the dictionary. This sounds
complicated but remember all of this work is done for you
automatically. All of the assembler commands operate in this way.
Conditionals such as IF,.....ELSE,.....ENDIF, leave address pointers
on the stack that are later picked up to compute the location to jump
back to, etc. However the stack must always be totally cleaned up
within a machine language definition. The compiler will check for this
and issue an error if the parameter stack does not have the same value
at the start
and end of a definition. This is how it checks to make sure all
conditionals are matched. That is every IF, has an ENDIF, etc.
The assembler will correctly decide on the opcodes used for absolute
addressing. If the operand is $FF or less than a zero (direct) page
opcode is used. If greater than $FF than an absolute (16 bit) opcode
is compiled. Because the 65816 has added an additional mode LONG, you
must tell the assembler if you are requiring this mode with the >L
mode setting word before the opcode is used. An Example:
01 2000 >L LDA,
bank---
This mode compiles an instruction to load the accumulator with the
value found in bank 1/ address 2000.
There is one last feature unique to the 65816 processor versus
programming the 6502. The 65816 has the ability to enter emulation
mode or to set certain flags to change the size of the accumulator and
the X/Y index registers. It is this feature that allows the APPLE IIgs
(tm) to run older APPLE II (tm) software. However this complicates
life for machine language assemblers. If immediate addressing is being
used such as:
$FFFF # LDA,
This would load the accumulator with the hex value $FFFF, as the 65816
can now accept 16 bit values. However if we were in 8 bit mode the
assembler would not understand that. As a programmer you are allowed
to switch modes at any time or mix modes. It is possible to have an 8
bit accumulator and 16 bit index registers. If the assembler is to
compile correctly it must have a way of being told the current status.
As a programmer the commands to change register size are:
$30 SEP, Sets m and x bits to 1 for an 8 bit accumulator and index
registers.
$10 SEP, Sets the x bit to 1 for 8 bit index registers. The size of
the accumulator is not affected.
$20 SEP, Sets m bit to 1 for an 8 bit accumulator. The size of the
index registers is not affected.
$20 REP, Sets m bit to 0 for a 16 bit accumulator. The size of the
index register is not affected.
$10 REP, Sets x bit to 1 for 16 bit index registers. The size of the
accumulator is not affected.
$30 REP, Sets x bit and m bit to 0. All registers are 16 bit.
SEC, XCE, Sets the emulation bit to 1. The processor is now operating
as a 6502 with all registers at 8 bits.
CLC, XCE, Sets the emulation bit to 0. The processor is now operating
as a native 65816. However it does not affect the m and x bits. That
must be done using the SEP, and REP, commands.
In order to communicate these various options, four words have been
defined:
LONGA LONGI ON OFF
These words and their use follow the 65816 convention. At the start of
an assembly word the programmer should declare:
LONGA ON LONGI ON
These words do not compile opcodes, flags are set to allow the
assembler to generate correct instructions. If the size of the
registers is being changed, the programmer should declare it
immediately to the assembler. Such as:
$30 SEP, \ Set X/Y and Accumulator to 8 bit
LONGA OFF LONGI OFF .......(more code).......
$30 REP, LONGA ON LONGI ON NEXT JMP, C;
The syntax is logical. LONGA stands for "Long Accumulator" (16 bits)
and LONGI stands for "Long Index Registers". The words ON and OFF
describe the current condition. In order to check your assembly, you
may want to use the APPLE IIgs (tm) monitor to disassemble your word
to insure it's correct. Type:
' cccc hex . {return}
Where cccc is the name of the word to disassemble. The pfa of the word
will be printed on the terminal. This is the address to examine in
memory. Type MON {return} and you will be deposited in the monitor.
Type the pfa followed by the letter L and your word will be
disassembled. The reason this is mentioned now is that the monitor
must also know the status of the m and x flags in order to perform a
correct disassembly. At the top of the disassembly the values of these
flags are printed out. You must alter these flags if they do not match
your code. (Note the flags will always be 0's if you use the word MON
because GS16FORTH runs in full native mode). You can change the state
of these flags from the monitor. An example:
0=m/0=x to clear the flags
1=m/1=x to set the flags
1=e to set emulation mode
0=e to set native mode
Remember to clear all flags BEFORE attempting to renter GS16FORTH.
Renter GS16FORTH with the monitor command:
01/08E0X (cold) or 01/08E4X (warm)
This is the origin of GS16FORTH providing you have not altered the
origin with the metacompiler.
HOW TO USE THE ASSEMBLER
An assembler word definition begins with:
CODE cccc
where cccc is the name of the new word. The definition must end with:
C;
All standard assembly definitions normally return to the location
NEXT. This is a pre-defined entry point for FORTH. The choices
available to end an assembly language definition are:
NEXT JMP, - jumps to location of next code.
PUT JMP, - replaces the value on the top of the parameter stack with
the value in the 16 bit accumulator, then continues to
NEXT.
PUSH JMP, - pushes the 16 bit value in the accumulator as a new entry
on the top of the parameter stack then continues to NEXT.
POP JMP, - drops the top value on the stack and jumps to NEXT.
POP2 JMP, - drops two values from the stack and jumps to NEXT.
RTS, - Used if the assembled code is a "free-standing" subroutine
called from another FORTH assembled word. This type of
definition cannot be called directly or the program will
crash.
In GS16FORTH the parameter stack is controlled by the value in the X
register. The value in X is a pointer into the direct page where the
parameter stack values are located. Dropping a value from the stack
does not change a memory location value, it merely moves the pointer
and the value is "lost". The parameter stack grows downward in memory
as items are added, therefore the code:
INX, INX,
causes the stack to drop a value. Conversely, the code :
DEX, DEX,
makes room for another stack item, but does not store a value at the
location. If an assembly routine has to remove three stack items then
you would use the following code:
CODE cccc ........assembly code........
INX, INX, POP2 JMP, C;
If the assembly routine itself needs to use the X register, you must
save the value and restore it before you renter FORTH. There are two
ways to do this:
1. CODE cccc XSAVE STX, ........assembly code......
XSAVE LDX, INX, INX, POP2 JMP, C;
2. CODE cccc PHX, ..........assembly code..........
PLX, INX, INX, POP2 JMP, C;
You must remember to restore the stack pointer before you take any
actions that will affect the stack. This includes dropping values,
adding values or changing contents of values. Also be aware that many
ROM routines use the X register, if your not sure save the X register.
The rest of this assembler section describes the available addressing
modes. A list and description of opcodes is beyond the scope of this
manual. However the GS16FORTH assembler supports all 256 available
opcodes of the 65816. The use of these opcodes will be explained in
any good text on the processor. The GS16FORTH disk is filled with many
examples of assembly code. All of the primitive FORTH words in the
COMPILER are written in assembler. Also the commands for TOOLBOX
routines and PRODOS 16 routines are written in assembly language. Open
one of the source code files and examine the use of the assembler.
ASSEMBLER MODES
FORTH WORD ADDRESSING MODE
# immediate
.A accumulator
X) indexed indirect with X
)Y indirect indexed with Y
,X indexed with X
,Y indexed with Y
) indirect
]Y indirect indexed long with Y
] indirect long
>L absolute long
>,X indexed long with X
SYMBOLS
To define symbols for use with the assembler, such as direct page
location, enter the assembler vocabulary with:
ASSEMBLER DEFINITIONS
Then define the symbol.
HEX 10 CONSTANT PTR
Where $10 is the storage location defined by the pointer. Make sure
you are in the correct number base when compiling.
GS16FORTH SYMBOLS
Some direct page locations have already been defined and are used as
part of the FORTH system.
SYMBOL VALUE DESCRIPTION
IP AE Interpretive pointer
W B1 Code field pointer
N A6 8 byte scratch pad
XSAVE B5 temporary X storage
UP B3 User pointer
BOT 00 Address of the low word (byte in 8 bit
mode) of the parameter stack with the ,X
mode preset. The X register provides the
offset to the current stack location.
Stack starts at $9E and grows downward.
SEC 02 address of the second word (3rd byte in
8 bit mode) of the parameter stack.
R $10000 address of the low word (byte
( 0 1 ) in 8 bit mode) of the return stack with
the >,X mode preset.
PUT, PUSH, POP, POP2, SETUP, and NEXT are all labels in the assembler
referring to direct page entry locations. Their use was described
previously. If you wish to load the accumulator with the top item of
the stack the code is:
.........BOT LDA,..........
The word bottom is used because the stack grows downward and the
lowest pointer value is the most recent item on the stack. Again you
must make sure that the X register has not been corrupted or you will
not be accessing the correct value. To load the third item on the
stack the code is:
........BOT 4 + LDA,.......
or
........SEC 2 + LDA,.......
BRANCHING AND CONDITIONALS
The assembler does not support labels, however well structured code
and the use of conditionals allows complex code to be written using
the same constructs as the high level FORTH routines. If you
understand the actions the conditionals are taking on the stack
values, a great deal of flexibility is possible.
THE CONDITIONALS
BEGIN,...............AGAIN,
BEGIN,...............UNTIL,
BEGIN,....WHILE,.....REPEAT,
IF,..................ENDIF,
IF,.......ELSE,......ENDIF,
A processor status word must always precede the words:
UNTIL, IF, or WHILE,
The eight status register words are:
WORD DESCRIPTION OPCODE USED
0= Zero equal BNE
0<> Zero not equal BEQ
0< Zero less than BPL
0> Zero greater than BMI
CS Carry set BCC
CC Carry clear BCS
VS Overflow set BVC
VC Overflow clear BVS
An example of branching and conditionals:
CODE EXAMPLE ( pointer count -- )
XSAVE STX, SEC LDA, N STA, BOT LDA, .A ASL, TAY,
BEGIN, N )Y LDA,
0= IF, 00FF # LDA, N )Y STA, ENDIF,
DEY, DEY,
0= UNTIL, XSAVE LDX, POP2 JMP, C;
This code takes a pointer and a word count and searches memory to see
if a word is equal to zero. If it is zero it then replaces the value
with $FF. The pointer is accessed with the SEC LDA, and then stored at
N ($A6). The count is accessed with BOT LDA, shifted left to multiply
by 2 and then transferred to the Y register. The beginning of a loop
is declared with BEGIN, N )Y LDA, indirectly accesses the value, 0=
IF, compares the zero flag and if the value is zero the value of 00FF
is loaded into the accumulator and stored at the memory location. The
Y register is then decremented and the code 0= UNTIL, examines the
zero flag. If the value is not zero, control is passed to the code
just after BEGIN, if the flag is zero, the X register is restored and
an exit occurs through POP2 JMP, which removes the values from the
stack. Notice in this case XSAVE STX, and XSAVE LDX, were not really
required and they could be eliminated to save memory and gain speed.
ASSEMBLY LANGUAGE SUBROUTINE
You may define code that can be called by another assembly level
routine. For example:
CODE EXAMPLE .....assembly code......RTS, C;
In order to use this subroutine from another FORTH definition:
CODE EXAMPLE2 .....' EXAMPLE JSR, ........C;
Trying to execute EXAMPLE directly from FORTH will cause a system
crash because it does not ultimately return to the code at NEXT.
PASSING VALUES
There are a number of ways to pass values in FORTH assembly language,
some of them such as BOT LDA, SEC LDA, etc. have already been
discussed. Another option is to use the setup routine. This subroutine
takes from 1 to 4 values (the number of items to move is loaded into
the accumulator before calling the subroutine) from the stack and
places them sequentially starting at hex location A6 and growing up in
memory. An example:
CODE TEST ( n1 n2 n3 -- )
3 # LDA, SETUP JSR, N LDA, ...REST OF CODE...C;
In this example all three stack items are moved to the scratch pad and
can be accessed with N LDA, N 2+ LDA, etc,. During the setup routine
the X register is incremented so that the values have been removed
from the stack. If you do not want the values removed, save the X
register before calling SETUP and then restore after. A third option
is to reference a FORTH variable. If the variable COUNT has been
previously defined you may use COUNT LDA, to reference the memory
location. A constant may also be referenced but the code is slightly
different, ' COUNT LDA,. The word ' (tick) must be used to find the
address before the assembler compiles the opcode.
The metacompiler, toolbox and other examples of source code are
provided with GS16FORTH. This can be very helpful in understanding how
the assembler is used.
By the way the commands RTS, RTL, BRA, and BRL, can allow you to write
relocatable code if desired. The conditionals compile branches instead
of jumps to help you in this. GS16FORTH requires a fixed location in
memory but subroutines could be useful as relocatable subroutines.
GS16FORTH STANDARD GLOSSARY
This glossary contains the word definitions in the base FORTH
vocabulary. The definitions are presented in the order of their ASCII
sort.
The first line of each entry is a description of the action of the
word on the parameter stack. The symbols indicate the order of the
input parameters required on the stack. Two dashes indicate the
execution of the word; the resulting parameters on the stack are then
listed. The top of the stack is to the right.
The symbols include:
addr memory address - in current program bank where GS16FORTH is
running
bank memory bank - 0 to FF in the IIgs
b 8 bit byte ( high 8 bits = 0 )
c 8 or 7 bit ascii character ( high 8 or 9 bits =
0 )
d 32 bit signed double integer with most significant
bit on top of stack.
f boolean flag. 0=false, 0<>=true
ff boolean false flag = 0
n 16 bit signed integer
u 16 bit unsigned integer
tf boolean true flag <> 0
The letters after the stack description list the word characteristics.
C Must be used within a colon definition. A digit
indicates number of memory addresses used ( if
other than 2 ).
E Execution only.
L0 Level Zero definition
L1 Level One definition
P Has precedence bit set. Executes when compiling.
See IMMEDIATE.
U User variable.
Unless otherwise noted, all references to numbers are for 16 bit
signed integers. The low byte of a number is first, followed by the
high byte, with the sign in the leftmost bit. For 32 bit signed double
numbers, the most significant word is on top. Arithmetic is 16 bit
signed integer math, without error and over/under-flow indication.
! n addr -- L0
Store 16 bits of n at address.
!CSP
Saves the stack position in CSP. Part of the compiler security.
# d1 -- d2 L0
Generate from a double number d1, the next ASCII character which is
placed in an output string. Result d2 is the quotient after division
by BASE. Used between <# and #>. See #S.
#> d -- addr count L0
Terminates numeric output conversion by dropping d, leaving the text
address and character count suitable for TYPE.
#S d1 -- d2 L0
Generates ASCII text in the text output buffer, until a zero double
number n2 results. Used between <# and #>.
' -- addr P,L0
Used in the form: ' cccc
pronounced "tick"
Leaves the parameter field address of dictionary word cccc. As a
compiler directive, it executes in a colon-definition to compile the
address as a literal. If the word is not found after a search of
CONTEXT and CURRENT, an appropriate error message is given.
( P,L0
Used in the form: ( cccc)
Ignore a comment that will be delimited by a right parenthesis. May
occur during execution or in a colon-definition. A blank after the
leading parenthesis is required.
(.") C+
The run-time procedure, compiled by ." which transmits the following
text to the output device.
(;CODE) C
The run time procedure compiled by ;CODE that rewrites the code field
of the most recently defined word to point to the following machine
language routine. See ;CODE
(+LOOP) n -- C4
The run-time proceedure compiled by +LOOP, increments the loop index
by n and tests for loop completion. See +LOOP.
(ABORT) --
Executes after an error when WARNING is -1. This word normally
executes ABORT, but may be altered to a user proceedure.
(DO) C
The run-time procedure compiled by DO which moves the loop control
parameters to the return stack. See DO.
(FIND) addr1 addr2 -- pfa b tf (found)
addr1 addr2 -- ff (not found)
Searches the dictionary starting at the name field address addr2
matching to the text at addr1. Returns parameter field address, length
byte of name field and boolean true if found. If no match is found,
only a boolean false is left.
(LINE) n1 n2 -- addr count
Convert the line number n1 and the screen n2 to the disk buffer
address containing the data. A count of 64 indicates the full text
line length.
(LOOP) -- C4
The run-time proceedure compiled by LOOP, increments the loop index
and tests for loop completion. See LOOP.
(NUMBER) d1 addr1 -- d2 addr2
Convert the ASCII text beginning at addr1 +1 with regard to BASE. The
new value is accumulated into double number d1, being left as d2.
Addr2 is the address of the first unconverted digit. Used by NUMBER.
* n1 n2 -- prod L0
Leave the signed product of two signed numbers.
*/ n1 n2 n3 -- n4 L0
Leave the ratio n4 = n1*n2/n3 where all are signed numbers. An
intermediate 31 bit product is used for greater accuracy than the
sequence: n1 n2 * n3 /
*/MOD n1 n2 n3 -- n4 n5 L0
Leave the quotient n5 and the remainder n4 of the operation n1*n2/n3.
A 31 bit intermediate product is used.
+ n1 n2 -- sum L0
Leave the sum of n1 + n2.
+! n addr -- L0
Add n to the value at the address.
+- n1 n2 -- n3
Apply the sign of n2 to n1, which is left as n3.
+LOOP n1 -- (run)
addr n2 -- (compile) P,C4,L0
Used in a colon-definition in the form:
DO ... n1 +LOOP
At run-time, +LOOP controls branching back to the corresponding DO
based on n1, the loop index and the loop limit. The signed increment
n1 is added to the index and the total compared to the limit. The
branch back to DO occurs until the new index is equal to or less than
the limit ( if n1<0 ). After exiting the loop, the parameters are
discarded and execution continues .
At compile time, +LOOP compiles the run-time word (+LOOP) and the
branch offset computed from HERE to the address left on the stack by
DO. n2 is used for error checking.
+ORIGIN n -- addr
Leave the memory address relative by n to the origin parameter area. n
is the byte offset from the origin. This definition is used to access
the boot-up parameters at the origin area.
, n -- L0
Store n into the next available dictionary memory cell, advancing the
dictionary pointer.
- n1 n2 -- diff L0
Leave the difference of n1-n2.
--> --
Continue interpretation with the next disk screen.
-DUP n1 -- n1 (if zero) L0
n1 -- n1 n1 (if non-zero)
Duplicate n1 only if it is non-zero. This is usually used to copy a
value just before IF. Eliminates the need for an ELSE part to drop n1.
-FIND -- pfa b tf (found)
-- ff (not found)
Accepts the next text word (delimited by blanks) in the input stream
to HERE. Searches the CONTEXT and then the CURRENT vocabularies for a
matching entry. If found, the dictionary entry's parameter field
address, its length byte, and a boolean true is left. Otherwise only a
boolean false is left.
-TRAILING addr n1 -- addr n2
Adjusts the character count n1 of a text string beginning at addr to
suppress the output of trailing blanks.
. n -- L0
Print a number from a signed 16 bit two's complement value, converted
according to the numeric BASE. A trailing blank follows.
." P,L0
Used in the form: ." cccc"
Compiles an in-line string cccc (delimited by the trailing ") with an
execution proceedure to transmit the text to the selected output
device. If executed outside a definition, ." will immediately print
the text. See (.").
.LINE n1 n2 --
Print on the terminal device, a line of text n1 from screen n2 from
the disk. Trailing blanks are suppressed.
.R n1 n2 --
Print the number n1 right aligned in a field whose width is n2. No
following blank is printed.
/ n1 n2 -- quot L0
Leave the signed quotient of n1/n2.
/MOD n1 n2 -- rem quot L0
Leave the remainder and signed quotient of n1/n2. The remainder has
the sign of the dividend.
0 1 2 3 -- n
These small numbers are defined by name in the dictionary as
constants. For execution speed and memory savings.
0< n -- f L0
Leave a true flag if the number is less than zero (negative),
otherwise leave a false flag.
0= n -- f L0
Leave a true flag if the number is equal to zero, otherwise leave a
false flag.
0BRANCH f --
The run-time procedure to conditionally branch. If f is false (zero),
the following in-line parameter is added to the interpretive pointer
to branch ahead or back. Compiled by IF, UNTIL, and WHILE.
1+ n1 -- n+1 L1
Increment n1 by 1.
2+ n1 -- n+2 L1
Increment n1 by 2.
: P,E,LO
Used in the form called a colon-definition:
: cccc ... ;
Creates a dictionary entry defining cccc as equivalent to the
following sequence of FORTH word definitions '...' until the next ';'
or ';CODE'. The compiling process is done by the text interpreter as
long as STATE is not zero.
; -- P,C,L0
Terminate a colon-definition and stop further compilation. Compiles
the run-time ;S.
;CODE P,C,L0
Used in the form:
: cccc .... ;CODE
....assembly mnemonics....c;
Stop compilation and terminate a new defining word cccc by compiling
(;CODE). Set the CONTEXT vocabulary to ASSEMBLER, assembling to
machine code the following mnemonics. Use c; to terminate the assembly
of the machine code. See the 65816 Assembler instructions.
When cccc later executes in the form:
cccc xxxx
the word xxxx will be created with its execution procedure given by
the machine code following cccc. That is, when xxxx is executed, it
does so by jumping to the code after cccc. An existing defining word
must exist in cccc prior to ;CODE.
;S -- P,L0
Stop interpretation of a screen. ;S is also the run-time work compiled
at the end of a colon-definition which returns execution to the
calling procedure.
< n1 n2 -- f L0
Leave a true flag if n1 is less than n2; otherwise leave a false flag.
<# L0
Setup for pictured numeric output formatting using the words:
<# # #S SIGN #>
The conversion is done on a double number producing text at PAD.
[ P,C
Used in a colon-definition in the form:
: xxx [ words ] more ;
Suspend compilation. The words after [ are executed, not compiled.
This allows calculation exceptions before resuming compilation with ].
See LITERAL,].
[COMPILE] -- P,C
Used in a colon-definition in the form:
: xxxx [COMPILE] FORTH ;
[COMPILE] will force the compilation of an IMMEDIATE definition, that
would otherwise execute during compilation. The above example will
select the FORTH vocabulary when xxxx executes, rather than at compile
time.
<BUILDS C,L0
Used within a colon-definition:
: cccc <BUILDS...DOES> ...;
Each time cccc is executed, <BUILDS defines a new word with a
high-level execution procedure. Executing cccc in the form:
cccc xxxx
uses <BUILDS to create a dictionary entry for xxxx with a call to the
DOES> part for xxxx. When xxxx is later executed, it has the address
of its parameter area on the stack and executes the words after DOES>
in cccc. <BUILDS and DOES> allow run-time procedures to be written in
high-level rather than in assembler code (as required by ;CODE).
= n1 n2 -- f L0
Leave a true flag if n1=n2; otherwise leave a false flag.
> n1 n2 -- f L0
Leave a true flag if n1 is greater than n2; otherwise a false flag.
] -- L1
Resume compilation to the completion of a colon-definition. See [.
>R n -- C,L0
Remove a number from the computation stack and place it as the most
accessable on the return stack. Use should be balanced with R> in the
same definition. In a definition, use should be confined to within any
loops that exist.
? addr -- L0
Print the value contained at the address according to the current
base.
?COMP
Issue error message if not compiling.
?CSP
Issue error message if the stack position differs from the value saved
in CSP.
?ERROR f n --
Issue an error message number n, if the boolean flag is true.
?EXEC
Issue an error message if not executing.
?LOADING
Issue an error message if not loading.
?PAIRS n1 n2 --
Issue an error message if n1 does not equal n2. The message indicates
that compiled conditionals do not match.
?STACK
Issue an error message if the stack is out of bounds.
?TERMINAL -- f
Perform a test of the terminal keyboard for actuation of the escape
key. A true flag indicates actuation.
@ addr -- n L0
Leave the 16 bit contents of addr.
ABORT -- L0
Clear the stacks and enter the execution state. Return control to the
operators terminal, printing the initialization heading and ending
with the word quit.
ABS n -- u L0
Leave the absolute value of n as u.
AGAIN addr n -- (compiling) P,C2,L0
Used in a colon-definition in the form:
BEGIN ... AGAIN
At run-time, AGAIN forces execution to return to corresponding BEGIN.
There is no effect on the stack. Execution cannot leave this loop
(unless R> DROP is executed one level below).
ALLOT n -- L0
Add the signed number to the dictionary pointer DP. May be used to
reserve dictionary space. n is the number of bytes to allot.
AND n1 n2 -- n3 L0
Leave the bitwise logical and of n1 and n2 as n3.
B/BUF -- n
This constant leaves the number of bytes per disk buffer, the byte
count read from disk by BLOCK. Default is 1024.
B/SCR -- n
This constant leaves the number of blocks per editing screen. By
convention, an editing screen is 1024 bytes, organized as 16 lines of
64 bytes.
BACK addr --
Calculate the backward branch offset from HERE to addr and compile
into the next available dictionary memory address.
BASE -- addr U,L0
A user variable containing the current number base used for input and
output conversion.
BEGIN -- addr n (compiling) P,L0
Occurs in a colon-definition in the form:
BEGIN ... UNTIL
BEGIN ... AGAIN
BEGIN ... WHILE ... REPEAT
At run-time, BEGIN marks the start of a sequence that may be
repetitively executed. It serves as a return point from the
corresponding UNTIL, AGAIN or REPEAT. When executing UNTIL, a return
to BEGIN will occur if the top of the stack is false; for AGAIN and
REPEAT a return to BEGIN always occurs.
At compile time BEGIN leaves its return addresss and n for compiler
error checking.
BL -- c
A constant that leaves the ASCII value for "blank".
BLANKS addr count --
Fill an area of memory beginning at addr with count quantity of
blanks.
BLK -- addr U,L0
A user variable containing the block number being interpreted. If
zero, input is being taken from the terminal input buffer.
BLOCK n -- addr L0
Leave the memory address of the block buffer containing block n. If
the block is not already in memory, it is transferred from disk to a
block buffer. If the block occupying that buffer has been marked as
updated, it is rewritten to disk before block n is read into the
buffer. See also BUFFER, R/W, UPDATE, and FLUSH.
BRANCH C4,L0
The run-time procedure to unconditionally branch. An in-line offset is
added to the interpretive pointer IP to branch ahead or back. BRANCH
is compiled by ELSE, AGAIN, REPEAT.
BUFFER n -- addr
Obtain the next memory buffer, assigning it to block n. If the
contents of the buffer is marked as updated, it is written to disk.
The block is then read from disk.The address left is the first cell
within the buffer for data storage.
C! b addr --
Store 8 bits of b into addr. Store occurs in the current data bank.
C, b --
Store 8 bits of b into the next available dictionary byte, advancing
the dictionary pointer.
C@ addr -- b
Leave the 8 bit contents of memory address.
C/L -- n
A constant that leaves the current characters per line in the standard
FORTH source screen.
CFA pfa -- cfa
Convert the parameter field address of a definition to its code field
address.
CLIT -- n C3,L0
Within a colon-definition, CLIT is automatically compiled before each
8 bit literal number encountered in the input text. Later execution
of CLIT causes the contents of the next dictionary byte to be pushed
on the stack.
CMOVE source destination count --
Move the specified quantity (count) of bytes beginning at source
address to destination address. CMOVE uses a IIgs toolbox routine and
is intelligent. The move will occur in the correct direction to
prevent bytes being overwritten. The move takes place in the current
data bank. See XCMOVE under GS16 extensions.
COLD -- emptystack
The cold start proceedure to adjust the dictionary pointer to the
minimum standard and restart via (ABORT). May be called from the
terminal to remove application programs and restart.
COMPILE -- C2
When the word containing COMPILE executes, the execution address of
the word following COMPILE is copied (compiled) into the dictionary.
This allows specific compilation situations to be handled in addition
to simply compiling an execution address (which the interpreter does).
CONSTANT n -- L0
A defining word used in the form:
n CONSTANT cccc
to create word cccc, with its parameter field containing n. When cccc
is later executed, it will push the value of n to the stack.
CONTEXT -- addr U,L0
A user variable containing a pointer to the vocabulary within which
dictionary searches will first begin.
COUNT addr1 -- addr2 n L0
Leave the byte address addr2 and byte count n of a message text
beginning a addr1. It is presumed that the first byte at addr1
contains the text byte count and the actual text starts with the
second byte. Typically COUNT is followed by TYPE.
CR -- L0
Transmit a carriage return to the selected output device.
CREATE
A defining word used in the form:
CREATE ccc
by such words as CODE and CONSTANT to create a dictionary header for a
FORTH definition. The code field contains the address of the words
parameter field. The new word is created in the CURRENT vocabulary.
CSP -- addr U
A user variable temporarily storing the stack pointer position, for
compilation error checking.
CURRENT -- addr
User variable containing a pointer in the vocabulary defining word
specifying the current vocabulary. That location contains a pointer to
the most recently defined word in that vocabulary.
D+ d1 d2 -- dsum
Leave the double number sum of two double numbers.
D+- d1 n -- d2
Apply the sign of n to the double number d1, leaving it as d2.
D. d -- L0
Print a signed double number from a 32 bit two's compliment value. The
high-order 16 bits are on top of the stack. Conversion is performed
according to the current BASE. A blank follows.
D.R d n --
Print a signed double number d, right aligned in a field n characters
wide.
DABS d -- ud
Leave the absolute value ud of a double number.
DECIMAL -- L0
Set the numeric conversion BASE for decimal input-output.
DEFINITIONS L1
Used in the form:
cccc DEFINITIONS
Set the CURRENT vocabulary to the CONTEXT vocabulary. In the example,
executing vocabulary name cccc made it the context vocabulary and
execution DEFINITIONS make both CONTEXT and CURRENT specify vocabulary
cccc.
DIGIT c n1 -- n2 tf (ok)
c n1 -- ff (bad)
Converts the ASCII character c (using base n1) to its binary
equivalent n2, accompanied by a true flag. If the conversion is
invalid, DIGIT leaves only a false flag.
DLITERAL -- d (executing) P
d -- (compiling)
If compiling, compile a stack double number into a literal. Later
exection of the definition containing the literal will push it to the
stack.
DMINUS d1 -- d2
Convert d1 to its double number two's complement.
DO n1 n2 -- (execute) P,C2,L0
addr n --(compile)
Occurs in a colon-definition in the form:
DO ... LOOP
DO ... +LOOP
At run time, DO begins a sequence with repetitive execution controlled
by a loop limit n1 and an index with inital value n2. DO removes
these from the stack. Upon reaching LOOP the index is incremented by
one. Until the new index equals or exceeds the limit, execution loops
back to just after DO; otherwise the loop parameters are discarded and
execution continues ahead. Both n1 and n2 are determined at run-time
and may be the result of other operations. Within a loop 'I' will copy
the current value of the index to the stack. See I, LOOP, +LOOP,
LEAVE. See J under GS16 extensions.
When compiling within the colon-definition, DO compiles (DO) and
leaves the following address addr and n for later error checking.
DOES> L0
A word which defines the run-time action within a high-level defining
work. DOES> alters the code field and first parameter of the new word
to execute the sequence of compiled word addresses following DOES>.
Use in combination with <BUILDS. When DOES> executes it begins with
the address of the first parameter of the new word on the stack. This
allows interpretation using this area or its contents. Typical uses
include arrays and compiler generation.
DP -- addr U
A user variable containing the current dictionary pointer.
DPL -- addr U,L
A user variable containing the number of digits to the right of the
decimal point on double integer input. It may also be used to hold the
output column location of a decimal point, in user generated
formating. The default value on single number input is -1.
DROP n -- L0
Drop the number from the stack.
DUP n -- n n L0
Duplicate the value on the stack.
ELSE addr1 n1 -- addr2 n2 (compiling) P,C2,L0
Occurs within a colon-definition in the form:
IF ... ELSE ... ENDIF
At run-time, ELSE executes after the true part following IF. ELSE
forces execution to skip over the following false part and resumes
execution after the ENDIF. It has no stack effect.
At compile-time ELSE replaces BRANCH reserving a branch offset, leaves
the address addr2 and n2 for error checking. ELSE also resolves the
pending forward branch from IF by calculating the offset from addr1 to
Here and storing at addr1.
EMIT c -- L0
Transmit ASCII character c to the selected output device. OUT is
incremented for each character output.
EMPTY-BUFFERS -- L0
Mark all block-buffers as empty, not necessarily affecting the
contents. Updated blocks are not written to the disk. This is also an
initialization procedure before first use of the disk.
ENCLOSE addr1 c -- addr1 n1 n2 n3
The text scanning primitive used by WORD. From the text address addr1
and an ASCII delimiting character c, is determined the byte offst of
the first non-delimiter character n1, the offset to the first
character not included. This proceedure will not process past an ASCII
'null', treating it as an unconditional delimiter.
ENDIF addr n -- (compile) P,CO,L0
Occurs in a colon-definition in the form:
IF ... ENDIF
IF ... ELSE ... ENDIF
At run-time, ENDIF serves only as the destination of a forward branch
from IF or ELSE. It marks the conclusion of the conditional structure.
ERASE addr n --
Clear n bytes to zero, beginning at addr. Bytes are cleared in the
current data bank.
ERROR n -- in blk
Execute error notification and reset parameter stack and return stack
pointer. WARNING is first examined. If WARNING = 0, n is printed as a
message number. If WARNING = -1, the definition (ABORT) is exected,
which executes the system
ABORT. The user may modify this execution by altering (ABORT).
GS16FORTH pushes the contents of IN and BLK onto the stack to assist
in determining the location of the error. Final action is execution of
QUIT.
EXECUTE addr --
Execute the definition whose code field address is on the stack. The
code field address is also called the compilation address.
EXPECT addr count -- L0
Transfer characters from the terminal to address, until a "return" or
the count of characters has been received. One or more nulls are added
at the end of the text.
FENCE -- addr U
A user variable containing an address below which FORGETing is
trapped.
FILL addr quan b --
FILL memory at the address with the specified quantity of bytes b.
FILLing occurs in the current data bank. See XFILL in the GS16
extensions.
FLD -- addr
User variable containing a value for output field formatting.
Presently unused.
FLUSH --
Write to disk the contents of all mass storage buffers which are
marked as updated.
FIRST -- n
A constant that leaves the address of the first block buffer.
FORGET E,L0
Executed in the form:
FORGET cccc
Deletes the definition named cccc from the dictionary with all entries
following it.
FORTH P,L1
The name of the primary vocabulary. Execution makes FORTH the context
vocabulary. FORTH is immediate, so it will execute during the
creation of a colon-definition.
HERE -- addr L0
Leave the address of the next available dictionary location. Equates
to DP @.
HEX -- L0
Set the numeric conversion base to sixteen (hexadecimal).
HLD -- addr L0
A user variable that holds the addresses of the latest character of
text during numeric output conversion.
HOLD c -- L0
Used between <# and #> to insert an ASCII character into a pictured
numeric output string. e.g. $2E HOLD will place a decimal point.
I -- n C,L0
Used within a DO-LOOP to copy the loop index to the stack. See R.
ID. nfa --
Print a definition's name from its name field address.
IF f -- (run-time) P,C2,L0
-- addr n (compile)
Occurs in a colon-definition in the form:
IF (tp) ... ENDIF
IF (tp) ... ELSE (fd) ... ENDIF
At run-time, IF selects execution based on a boolean flag. If f is
true (non-zero), execution continues ahead thru the true part. If f
is false (zero), execution skips till just after ELSE to execute the
false part. After either part, execution resumes after ENDIF. ELSE
and its false part are optional; if missing, false execution skips to
just after ENDIF.
At compile-time IF compiles 0BRANCH and reserves space for an offset
at addr.
IMMEDIATE --
Mark the most resently made definition so that when encountered at
compile time, it will be executed rather than being compiled. i.e.
the precedence bit in its header is set. This method allows
definitions to handle unusual compiling situations, rather than build
them into the fundamental compiler. The user may force compilation of
an immediate definition by preceeding it with [COMPILE].
IN -- addr L0
A user variable containing the byte offset within the current input
text buffer (terminal or disk) from which the next text will be
accepted. WORD uses and moves the value of IN.
INDEX start end --
Print the first line of each screen over the range start to end. This
is used to view the comment text (line 0) on disk screens.
INTERPRET --
The outer text interpreter which sequentially executes or compiles
text from the input stream (terminal or disk) depending on STATE. If
the word name cannot be found after a search of CONTEXT and then
CURRENT it is converted to a number according to the current base.
That also failing, an error message echoing the name with a "?" will
be given. Text input will be taken according to the convention for
WORD. If a decimal point is found as part of a number, a double number
value will be left. The decimal point has no other purpose than to
force this action. See NUMBER.
KEY -- c L0
Leave the ASCII value of the next terminal key struck.
LATEST -- addr
Leave the name field address of the topmost word in the CURRENT
vocabulary.
LEAVE C,L0
Force termination of a DO-LOOP at the next opportunity by setting the
loop limit equal to the current value of the index. The index itself
remains unchanged, and execution proceeds normally until LOOP or +LOOP
is encountered.
LFA pfa -- lfa
Convert the parameter field address of a dictionary definition to its
link field address.
LIMIT -- n
A constant leaving the address just above the highest memory available
for a disk buffer.
LIST n -- L0
Display the ASCII text of screen n on the selected output device. SCR
contains the screen number during and after this process.
LIT -- n C4,L0
Within a colon-definition, LIT is automatically compiled before each
16 bit literal number encountered in the input text. Later execution
of LIT causes the contents of the next dictionary address to be pushed
on the stack.
LITERAL n -- (compiling) P,C3/4,L0
If compiling, then compile the stack value n as a 16 bit literal. This
definition is immediate so that it will execute during a
colon-definition. The intended use is:
: xxxx [ calculate ] LITERAL ;
Compilation is suspended for the compile time calculation of a value.
Compilation is resumed and LITERAL compiles this value.
LOAD n -- L0
Begin interpretation of screen n. Loading will teminate at ;S or if a
null is found in the screen. See ;S and -->.
LOOP addr n -- (compiling) P,C4,L0
Occurs in a colon-definition in the form:
DO ... LOOP
At run-time, LOOP selectively controls branching back to the
corresponding DO based on the loop index and limit. The loop index is
incremented by one and compared to the limit. The branch back to DO
occurs until the index equals or exceeds the limit; at that time, the
parameters are discarded and execution continues ahead.
At compile-time, LOOP compiles (LOOP) and uses addr to calculate an
offset to DO. n is used for error testing.
M* n1 n2 -- d
A mixed magnitude math operation which leaves the double number signed
product of two signed 16 bit numbers.
M/ d n1 -- n2 n3
A mixed magnitude math operator which leaves the signed remainder n2
and signed quotient n3, from a double number dividend and divisor n1.
The remainder takes its sign from the dividend.
M/MOD ud1 u2 -- u3 ud4
An unsigned mixed magnitude math operation which leaves a double
quotient ud4 and remainder u3, from a double dividend ud1 and single
divisor u2.
MAX n1 n2 -- max L0
Leave the greater of two numbers.
MESSAGE n --
Print on the selected output device a warning message with n as the
message number.
MIN n1 n2 -- min L0
Leave the smaller of two numbers.
MINUS n1 -- n2 L0
Leave the two's complement of a number.
MOD n1 n2 -- mod L0
Leave the remainder of n1/n2, with the same sign as n1.
MON --
Exit to the APPLE IIgs monitor. Typical rentry is 0 +ORIGIN (cold) or
4 +ORIGIN (warm).
NEXT
This is the inner interpreter that uses the interpretive pointer IP to
execute compiled FORTH definitions. It is not
directly executed but is the return point for all code procedures. It
acts by fetching the address pointed to by IP, storing this value in
register W. It then performs an indirect jump to the value contained
in the address W. W points to a code field of a definition which
executes.
NFA pfa -- nfa
Convert the parameter field address of a definition to its name field
address.
NUMBER addr -- d
Convert a character string left at addr with a preceeding count, to a
signed double number, using the current numeric base. If a decimal
point is encountered in the text, its position will be given in DPL,
but no other effect occurs. If numeric conversion is not possible, an
error message will be given.
OFFSET -- addr U
A FIG-STANDARD user variable not used in GS16FORTH because of the use
of PRODOS (tm) pathnames rather than disk drive numbers. See GS16
PRODOS (tm) extensions.
OR n1 n2 -- or L0
Leave the bit-wise logical or of two 16 bit values.
OUT -- addr U
A user variable that contains a value incremented by EMIT. The user
may alter and examine OUT to control display formating.
OVER n1 n2 -- n1 n2 n1 L0
Copy the second stack value, placing it as the new top.
PAD -- addr L0
Leave the address of the text output buffer, which is a fixed offset
above HERE.
PFA nfa -- pfa
Convert the name field address of a compiled definition to its
parameter field address.
POP
The code sequence to remove a stack value and return to NEXT. POP is
not directly executable, but is a FORTH re-entry point after machine
code. See Assembler.
PUSH
This code sequence pushes the accumulator to the computation stack and
returns to NEXT. It is not directly executable, but is a FORTH
re-entry point after machine code. See Assembler.
PUT
This code sequence stores the accumulator over the topmost computation
stack value and returns to NEXT. It is not directly executable, but is
a FORTH re-entry point after machine code. See Assembler.
QUERY --
Input 80 characters of text (or until a "return") from the operators
terminal. Text is positioned at the address contained in TIB with IN
set to zero.
QUIT L0
Clear the return stack, stop compilation, and return control to the
operators terminal. No message given.
R -- n
Copy the top of the return stack to the computation stack.
R# -- addr
A user variable which may contain the location of an editing cursor,
or other file related function.
R/W addr blk f --
The Forth standard disk, read-write linkage. addr specifies the source
or destination block buffer, blk is the referenced block, and f is a
flag for write (f=0) or read (f=1). R/W determines the location on
mass storage, performs the read-write and performs error checking.
R> -- n L0
Remove the top value from the return stack and leave it on the
computation stack. See >R and R.
REPEAT addr n -- P,C2
Used within a colon-definition in the form:
BEGIN....WHILE....REPEAT
At run-time, REPEAT forces an unconditional branch back to just after
the corresponding begin.
ROT n1 n2 n3 -- n2 n3 n1 L0
Rotate the top three values on the stack, bringing the third value to
the top.
RP! --
Initializes the return stack pointer from the hidden user variable R0.
S->D n -- d
Sign extend a single number to form a double number.
SCR -- addr U
A user variable containing the screen number most recently referenced
by LIST.
SIGN n d -- d L0
Stores an ASCII "-" sign just before a converted numeric output string
in the text output buffer when n is negative. n is discarded, but
double number d is maintained. Must be used between <# and #>.
SMUDGE --
Used during word definition to toggle the "smudge bit" in a
definitions name field. This prevents an uncompleted definition from
being found during dictionary searches.
SP! --
Initializes the stack pointer from the hidden user variable S0.
SP@ -- n
Returns the value of the current stack pointer. The depth of the stack
can be found by { SP@ 18 +ORIGIN @ swap - 2 / }.
SPACE -- L0
Transmit an ASCII blank to the output device.
SPACES n -- L0
Transmit n ASCII blanks to the output device.
STATE -- addr L0,U
A user variable containing the compilation state. A non-zero value
indicates compilation.
SWAP n1 n2 -- n2 n1 L0
Exchange the top two values on the stack.
TIB -- addr U
A user variable containing the address of the terminal input buffer.
TOGGLE addr b --
Complement the contents of addr by the bit pattern b.
TRAVERSE addr1 n -- addr2
Move across the name field of a FORTH variable length name field.
addr1 is the address of either the length byte or the last letter. If
n=1, the motion is toward high memory; if n=-1, the motion is toward
low memory. The addr2 resulting is the address of the other end of the
name.
TRIAD scr --
Display on the selected output device the three screens which include
that numbered scr, beginning with a screen evenly divisible by three.
Used to document an application. Everytime a screen is updated TRIAD
is used to print a new page with three screens on it. Triad always
keeps the screens on the same page.
TYPE addr count -- L0
Transmit count characters from addr to the selected output device.
U* u1 u2 -- ud
Leave the unsigned double number product of two unsigned numbers.
U/ ud u1 -- u2 u3
Leave the unsigned remainder u2 and unsigned quotient u3 from the
unsigned double dividend ud and unsigned divisor u1.
UNTIL f -- (run-time) P,C2,L0
addr n -- (compile)
Occurs within a colon-definition in the form:
BEGIN ... UNTIL
At run-time, UNTIL controls the conditional branch back to the
corresponding BEGIN. If f is false, execution returns to just after
BEGIN; if true, execution continues ahead.
At compile time, UNTIL compiles (0BRANCH) and an offset from HERE to
addr. n is used for error checking.
UPDATE -- L0
Marks the most recently referenced block (pointed to by PREV) as
altered. The block will be transferred automatically to disk if it's
buffer is required.
USER n -- L0
A defining word used in the form:
n USER cccc
which creates a user variable cccc. The parameter field of cccc
contains n as a fixed offset relative to the user pointer register UP.
When cccc is later executed, it places the sum of its offset and the
user area base address on the stack as the storage address of that
variable.
VARIABLE n -- E,L0
A defining word used in the form:
n VARIABLE cccc
When VARIABLE is executed, it creates the definiton cccc with its
parameter field initialized to n. When cccc is later executed, the
address of its parameter field (containing n) is left on the stack, so
that a fetch or store may access this location.
VOC-LINK -- addr U
A user variable containing the address of a field in the definiton of
the most recently created vocabulary. All vocabulary names are linked
by these fields to allow control for FORGETing thru multiple
vocabularies.
VOCABULARY E,L0
A defining word used in the form:
VOCABULARY cccc
to create a vocabulary definition cccc. Subsequent use of cccc will
make it the CONTEXT vocabulary which is searched first by INTERPRET.
The sequence "cccc DEFINITION" will also make cccc the CURRENT
vocabulary into which new definitions are placed.
VLIST --
List the names of the definitions in the CONTEXT vocabulary. Any key
will terminate the listing.
WARNING -- addr U
A user variable containing a value controlling messages. In GS16FORTH
must be 0 or -1 to invoke (ABORT). GS16FORTH limits the disk buffers
to (1) to conserve memory space. Ramdisk use is possible for disk
intensive operations. See RAMEDIT, MESSAGE, ERROR.
WHILE f -- (run-time) P,C2
addr1 n1 -- addr1 n1 addr2 n2
Occurs in a colon-definition in the form:
BEGIN ... WHILE (tp) ... REPEAT
At run-time, WHILE selects conditional execution based on boolean flag
f. If f is true (non-zero), WHILE continues execution of the true part
thru to REPEAT, which then branches back to BEGIN. If f is false,
execution skips to just after REPEAT.
At compile time, WHILE replaces (0BRANCH) and leaves addr2 of the
reserved offset. The stack values will be resolved by REPEAT.
WIDTH -- addr U
A user variable containing the maximum number of letters saved in the
compilation of a definitions' name. It must be 1 thru 31, with a
default value of 31. The name, character count and it's characters are
saved, up to the value in WIDTH. The value may be changed within the
limits.
WORD c -- L0
Read the next text characters from the input stream being interpreted,
until a delimiter c is found, storing the packed character string
beginning at the dictionary buffer HERE. WORD leaves the character
count in the first byte, the characters, and ends with two or more
blanks. Leading occurances of c are ignored.
X
This is a pseudonym or dictionary entry for a name of one character of
ASCII "null". It is the execution proceedure to terminate
interpretation of a line of text from the terminal or disk buffer.
Both buffers have a null at the end.
XOR n1 n2 -- xor L1
Leave the bitwise logical exclusive-or of two value.
THE GS16FORTH TOOLBOX
GSCOMPILER
The GSCOMPILER is not one of the IIgs toolbox routines. The compiler
is the actual source code of GS16FORTH. Forth has the ability to
"recreate" itself as if it were any other application. There are three
main reasons why this may be desirable in GS16FORTH.
1. You wish to use the older Apple II double hires screen. In the
supplied versions there is a memory conflict (if you use memory
shadowing to access bank 1, if you access bank E1 directly there is
no conflict. With the compiler you can move Forth above $4000.
2. You wish to move Forth permanently to another bank (Don't move to
bank 0 !) and expand the available programming area.
3. You wish to create a commercial application with minimum memory and
you wish to modify or remove all words that are unneccesary.
The compiler requires that the assembler be present in the current
GS16FORTH and it must act within the same bank it is currently in. The
prompt you receive about bank location only refers to the creation of
the OMF header which is effective when booting. Therefore if you want
to move GS16FORTH to bank 2, addr $0400. You would LOAD.SCR the
GSCOMPILER file. Answer that you wish to move to memory page $60 for
example and want to run in bank 2. When the file is completed you will
receive prompts similar to the MAKEPERM screens. When you boot up your
"new" Forth you should be at $6000 and bank 2. You can check this with
DB@ which gives you the bank and 0 +origin which should respond $4E0.
The 65816 assembler in Forth GS16FORTH requires six labels to function
correctly. When you moved Forth, the labels are no longer valid.
Before you can compile the assembler on the new version you must
examine screen 83 of GSCOMPILER and transpose the new values needed to
screen 12 of the assembler, close and save the file. Load the
assembler and repeat the process to move back down to $0400. It takes
two steps because Forth would write over itself if the move occured
once.
To use the compiler, just load screen 1 and follow the prompts. All of
the actions are automatic. However, to get the most use of the
compiler you must understand the Forth language well. In all cases of
using or modifying the compiler, You are urged to understand the
process before you experiment. The creation of Forth is not a straight
line. The are many forward references to resolve and moving words or
slightly modifying words can make the patches ineffective
and cause crashes. It's a powerful tool, but it needs attention.
THE APPLE IIGS TOOLBOX
This section will be a mixture of descriptions and glossary. It's
important to understand that the toolbox is very complex. The words
provided will help you code applications, but adding to the toolbox
will require you to obtain the Apple IIGS Toolbox Reference Manual,
Volume I and II. When using the supplied routines keep your word
definitions short and debug thoroughly. Misplaced stack items in front
of a toolbox call can promptly crash the system.
The source code for the IIgs toolbox routines is heavily commented and
should also be used for reference.
GENTOOLBOX
As the name implies, these routines are not specific to any one
toolbox. Only a couple of words are straight toolbox calls. Stack
pictures may contain two lines. One a descriptive listing and the
second lists the size of the parameters to be passed. In many cases an
addr and a bank must be passed to a routine. The stack is listed this
way to remind you that this combination can be thought of as two
single numbers OR one double number.
TVER toolset -- version
n -- n
Given the toolset number returns the firmware version.
TSTAT toolset -- status
n -- n
Given the toolset number, returns status. 0 = off, 0<> = on.
TLERR a machine language subroutine called if the carry is set
when exiting the call. If called the error routine gets the
information to TERR which is a FORTH word for reporting the error. Was
done this way to allow an easy method of redirecting error trapping in
real applications. Replace the word TERR in this definition with your
own error handling word. The toolset and error code will be passed to
your routine as a single stack number.
TERR n --
Reports error n as high byte toolset and low byte error code.
The remainder of this file are general machine language routines that
are generic versions of toolbox calls. This
allows calls to be added with a significant memory savings and error
reduction.
0/0TOOL func.tool --
n --
Enter with a 16 bit number on the stack. The high byte has the
function requested and the low byte has the toolset. This routine
requires no inputs and does not return any.
N1/0TOOL n func.tool --
Requires a single number input and no output.
The rest of the generics are listed. Stack pictures are in the source
code. The name of each tool describes the I/O's required, Input
followed by output. The N signifies a single number. But remember a
double number is made up of two single numbers, just remember to SWAP
the values either on entry to the definition or exit depending if it
is an input or output. See the source code for examples.
N2/0TOOL
N3/0TOOL
0/N2TOOL
N1/N1TOOL
N2/N2TOOL
N4/0TOOL
Of the overall toolcalls supplied with GS16FORTH these cover 80%. The
rest are low enough counts that the overhead of a master routine was
not warranted.
MEMORY MANAGER
One of the most important toolsets because without it you cannot use
the others. Even standard data manipulation is dangerous without it,
because you don't know where PRODOS16 is placing it's I/O buffers.
The memory manager assigns memory blocks using handles. A handle is a
pointer to a pointer. That allows a fixed reference at all times
because the memory manager may move blocks on it's own during your
program execution. The only way you can keep reference to it is to use
the handle.
Forth has a unique concept to it; extending the compiler. That is you
can create new methods of defining words. In the memory manager use
there is a perfect application for that.
The memory manager returns the handle in response to the toolcall
NewHandle. The handle returned could be anywhere in memory.
Referencing the handle is done with the GS16FORTH extension X2@. This
returns the location of the datablock. In a real application we would
probably want to index into a database or an array. The word HANDLE
has been created for this.
As given it is used in the form: HANDLE cccc
which creates the word cccc. In this example let's use the form:
HANDLE DATABLOCK
When we call the memory manager with NEWHANDLE the handle is left as a
Forth double number on the stack so we use the command:
NEWHANDLE PUT DATABLOCK
In this case put is merely the constant 1 which is used by DATABLOCK
to determine that you want to store a new handle. To use the word:
GET DATABLOCK -- memory.location
DATABLOCK does more than return the handle it also performs the lookup
for us. In a real application we would probably maintain a pointer to
the memory cell we want. That function could be done seperate as:
GET DATABLOCK DATAPOINTER @ + -- indexd.memoryloc
Or that function could be built into DATABLOCK also. The most
effective use would be to combine the two functions in one word so the
use could be:
GET DATA -- n
All of the memory reference, indirection and indexing could be done
with a single defining word. In the memory manager source code, the
code for HANDLE is included in the first form described.
MEMORY MANAGER GLOSSARY
NEWHANDLE blocksize idnum memattrib memloc -- handle
d n n d -- d
The values of memattribute are listed in the source code. IDNUM is
referenced by IDNUM @.
HANDLE HANDLE cccc (comptime) ! 0 cccc -- blockloc
d 1 cccc --
Put and Get are defined constants to improve source code readability.
PUT -- 1
Leaves the number 1.
GET -- 0
Leaves the number 0.
DISPOSEHANDLE handle --
d --
Dispose of the block and the handle. Does so regardless of lock status
and purge level.
FINDHANDLE memloc -- handle ! nil
d -- d ! d
Returns the handle for that memory location or nil if none.
FREEMEM -- freebytes
-- d
Total assignable memory but it might be fragmented.
REALLOCHANDLE
blksize idnum memattr memloc handle --
d n n d d --
Reallocates purged block, uses new attributes to describe the block.
RESTOREHANDLE handle --
d --
Restores a purged block with same attributes as initially given. Block
must not have been fixed initially in order to restore.
GETHANDLESIZE handle -- size
d -- d
Returns the size of the memory block.
SETHANDLESIZE size handle --
d d --
Changes the size of the memory block to the new value d.
PURGEHANDLE handle --
d --
Purge the memory block from memory. The block must have been marked as
purgable.
PURGEALL idnum --
n --
Purges all memory owned by idnum. GS16FORTH owner id is located in
variable IDNUM.
MAXBLOCK -- maxblock.available
-- d
Returns largest contiguous block of memory that can be allocated.
TOTALMEM -- totalsysmem
-- d
Returns total memory in the system.
COMPACTMEM --
Clean up memory as much as possible. Moves blocks up into high memory.
HLOCK handle --
d --
Make the block unpurgable.
HLOCKALL idnum --
n --
Lock all memory blocks owned by idnum.
HUNLOCK handle --
d --
Makes a block purgable if it's original attributes called for a purge
level greater than zero.
HUNLOCKALL idnum --
n --
Makes all blocks purgable owned by idnum.
SETPURGE purgelevel handle --
n d --
Changes a blocks purge level. 0 = not purgable, 1 = least, 2 = next, 3
= most purgable.
SETPURGEALL idnum --
n --
Same as SETPURGE but it affects all blocks owned by idnum.
PTRTOHAND ptrsource handledest count --
d d d --
Moves a block of memory given a handle to a source pointer. Move is
intelligent and will be performed so no overwriting occurs.
HANDTOPTR handlesource pointerdest count --
d d d --
Moves from handle to pointer.
HANDTOHAND handlesource handledest count --
d d d --
Memory move using two handles for source and destination.
EVENT MANAGER
The event manager makes programming the mouse and superhires cursor
simple. GS16FORTH uses the event manager to get keystrokes in the word
KEY. Because of that, the event manager is on and active all the time
you are in GS16FORTH. The Event manager controls interrupts and must
be on to use many of the following QUICKDRAW routines.
EVENT MANAGER GLOSSARY
GETNEXTEVENT eventmask eventrecaddr eventrecbank -- f
n n n -- n
Polls the event queue and returns a flag 0 = no event, 0<> = event. If
an eveny occured it removes the event from the queue and places the
event description in memory at the passed location. See source code
for a description of the Event record format.
?WHAT -- eventcode
-- n
Fetches the event code from the event record.
?MSG -- messagecode
-- n
Fetches the message code from the record.
?WHERE -- X Y
-- n n
Fetches the mouse location from the event record.
NEXTEVENT -- f
Simplified version of GETNEXTEVENT. If f is <>0 then an event occured
and the info was placed in the event record which is a variable in the
core forth dictionary. Use ?what ?where and ?msg to retrieve the
information. NEXTEVENT is masked to only look for keyboard and mouse
events.
EVENTAVAIL eventmask eventrecaddr eventrecbank -- f
n n n -- n
Operates the same as GETNEXTEVENT but the event is not removed from
the queue. Used to poll the events to handle when appropriate.
NEXTAVAIL -- f
Same as NEXTEVENT but does not remove from queue. You can examine
event and decide whether or not to handle.
GETMOUSE mouserecaddr mouserecbank --
n n --
Places the mouse location into the passed location and bank.
READMOUSE --
Forces a read of mouse location into the event record. Then use ?WHERE
to access.
BUTTON button# -- f
n -- n
Checks the status of the pointing devices button. A choice was allowed
for hardware developers to make alternate pointing devices.
?MBUTTON -- f
Checks the status of the mouse button. Returns 0 for not down and 1
for down.
STILLDOWN button# -- f
n -- n
Checks to see if the mouse button is still down from the last event.
BUTTON does not.
WAITMOUSEUP button# -- f
n -- n
Used to determine if the user has released and then clicked again.
Useful for programming to detect double clicks.
TICKCOUNT -- tickcount
-- d
Returns the tickcount since machine startup. Tick is 1/60 second.
FLUSHEVENTS eventmask stopmask -- resultcode
n n -- n
If all events are flushed then 0 is returned. If not zero then event
code that stopped flush. All events that logically and with the event
mask are flushed. If they and with the stopcode the process is
stopped.
SETEVENTMASK systemeventmask --
n --
Sets a global event mask that overrules the individual masks. Not
suggested to use by an application. Used by other toolbox routines.
WAITMOUSEDOWN --
General routine that waits until mouse has been clicked before further
execution is allowed. You can use ?WHERE to check location upon exit.
MISCTOOLS
Many of these routines will not be used when the event manager is
active. All reading of the mouse should be done with event manager
calls. However these calls are used for setting the mouse clamp values
and positioning the mouse directly.
MISCTOOLS GLOSSARY
INITMOUSE --
Do not use. The mouse is active with the event manager on.
SETMOUSE mode --
n --
Not used. The event manager sets the mouse up for you.
READMMOUSE -- X Y status
-- n n n
Could be used but the event manager is suggested. Notice the extra M
in the definition to distinguish from the event manager routine.
SERVEMOUSE -- status
-- n
Returns the button and movement status of the mouse. Use the event
manager.
POSMOUSE X Y --
n n --
Position the mouse to coordinates X,Y.
HOMEMOUSE --
Moves the mouse to the upper left hand corner of the clamp window.
CLAMPMOUSE xmin xmax ymin ymax --
n n n n --
Sets the mouse clamping to the values passed.
GETMOUSECLAMP -- xmin xmax ymin ymax
Returns the current mouse clamp values. Using GETMOUSECLAMP you can
alter the values then reset with CLAMPMOUSE.
FWENTRY acc xreg yreg entrypoint -- status acc xreg yreg (all single
numbers)
Used to access the old Apple II ROM. Because the Apple II ROM must
operate in emulation mode, switching in and out is difficult. This
routine performs all of the necessary housekeeping.
QUICKDRAW II
The quickdraw II toolbox is by far the most interesting. Unless your a
MAC user, the ease of graphics manipulation is amazing. The only
drawback is that it is slower than many people would like. We have
used the 65816 assembler to code line drawing routines in straight
machine language without the toolbox overhead (which is significantly
faster). However, the ease of use especially in rectangle painting,
framing and inverting is invaluable and makes for short code
development time.
QUICKDRAW II GLOSSARY
QDSTART masterscb dpbuffer$300 --
n n --
Starts up quickdraw. You should get direct page memory from the memory
manager. There are more parameters used in the call but general
conditions are assumed so you only have to supply two parameters. The
word >QD is supplied that
performs all housekeeping for a standard entry into quickdraw II.
QDSTOP --
Must call this before exiting, if you turned QD on.
GRAFON --
Switches to the Super Hires Screen.
GRAFOFF --
Switches back to the text screen.
CLRSHR n --
Clear SHR screen to color n.
OPENPORT mempointer$170 --
d --
Initializes a grafport. Obtain the memory block from the memory
manager unless you assign space within GS16FORTH. This must be done
prior to drawing after QD is started.
CLOSEPORT grafportpointer --
d --
Used to shut down grafport and change over to a new one. QDSTOP does
this for you if you are exiting QD.
SLINE x y --
n n --
Draw line from current pen position to x y. Top left corner of screen
is 0,0. Pen must stay within signed single numbers. Clipping occurs
automatically if off screen.
SMOVE x y --
n n --
Move pen from current position to x,y. No drawing occurs.
SLINER dx dy --
n n --
Draw line from current pen position, delta x and delta y pixels.
SMOVER dx dy --
n n --
Moves relative to current pen position.
PENCLR n --
Set pen to color n. Bottom two bits used in 640 mode, four bits for
320.
SETCOLORENTRY table# color# colorval --
n n n --
The SHR screen supports 16 different color tables organized as 16
different color entries each. This routine is used to change them.
COLORBYTE blueval greenval redval -- n
Given the three primary color values, 0-15. Calculates a color value
for use in the color table. The higher the individual color value the
more prominent the color is.
ORDRAW --
Standard drawing mode were pixels paint on top of each other.
XORDRAW --
If pixel is painted on top of another the pixel is inverted. Used to
draw lines that can be erased by redrawing.
INITCOLORTABLE addr bank --
n n --
Places a copy of the standard color tables in memory at the location
passed.
GEMIT c --
Like standard Forth word, but prints a character on the SHR screen.
Character is printed at the current pen position. The pen position is
at the bottom left corner of the character. Automatically advances the
pen position to the right by the width of the character.
GTYPE addr count --
n n --
Type count characters at addr on the SHR screen.
XGTYPE addr bank count --
n n n --
Same as GTYPE but acts on extended memory locations.
CHARWIDTH c -- pixels
Returns width of character in pixels. No drawing occurs and pen is not
moved.
GTEXTWIDTH addr bank count -- stringwidth
Returns width of block of text. No drawing occurs and the pen is not
moved.
SETBACKCOLOR n --
Set character drawing background color to n.
SETFORECOLOR n --
Sets the characters color to color n.
GETPORT -- addr bank
-- n n
Returns a pointer to the current GrafPort record.
RECT -- addr
A quickdraw variable of 8 bytes within GS16FORTH for access by the
rectangle commands. Set to full screen size when first compiled.
SCROLLRECT dh dv --
n n --
Scrolls the current defined RECT by dh,dv pixels and the scrolled area
is filled with BACKCOLOR.
SETSOLIDBACK color --
n --
Sets a solid backcolor for characters.
GETMSTSCB -- scb
-- n
Returns a copy of the master scb that initialized QDII. Can be used to
check the current drawing mode.
XYLOC -- addr
A double number variable used to store the pen postion. Using XYLOC 2@
leaves x and y on the stack in that order.
GETPEN --
Puts pen position in XYLOC.
INITCRSR --
Initialize the SHR screen cursor.
HIDECRSR --
Decrements the cursor level, if less than zero than cursor is hidden.
SHOWCRSR --
Increments the cursor level, but not greater than zero. If zero the
cursor is visible.
OBSCURECRSR --
Hides the cursor until the next mousemovement.
SETSCB scanline scb --
n n --
An scb is a scanline control byte used to set drawing attributes on
the SHR screen. Each scan line has an individual scb.
GETSCB scanline -- scb
n -- n
Returns the respective scb.
SETALLSCB scb --
All scb's are altered.
SETPENSIZE width height --
Sets the pen to the size passed.
GETPENSIZE addr bank --
n n --
Places the current pen size at the address/bank passed.
SETRANDSEED seed --
d --
Initializes the random number generator.
RANDOM -- random#
Generates a random number. Same sequence is created for a given seed.
RANDOM# bitmask -- random#
Uses SETRANDSEED and RANDOM return a random number. The value of
TICKCOUNT is used as the seed. The returned number is anded with the
bitmask allow you to restrict the value within powers of 2.
FRAMERECT addr bank --
Draws a frame with the rectangle coordinates at the addr/bank passed.
Drawing occurs with the current pen color and size.
PAINTRECT addr bank --
Paints the rectangle solid with the current pen color.
ERASERECT addr bank --
Clears the specified rectangle to the backcolor set.
INVERTRECT addr bank --
Inverts all pixels within the rectangle at addr/bank.
The same rectangle commands are available for ovals (circles) and
rounded corner rectangles. They operate the same and a listing
follows:
FRAMEOVAL
PAINTOVAL
ERASEOVAL
INVERTOVAL
FRAMERRECT
PAINTRRECT
ERASERRECT
INVERTRRECT
SETCRSR addr bank --
n n --
Changes the cursor to the cursor shape and attributes located at the
record add/bank. See the IIgs toolbox reference if you want to change
cursor shapes.
GETCRSRADDR -- addr bank
Returns the current cursor record pointer.
SETRECT left top right bottom addr bank --
n n n n n n --
Sets the rectangle record at addr/bank to the four corner values
passed.
SETSTDRECT left top right bottom --
Uses SETRECT and acts on the predefined RECT in GS16FORTH.
SETORIGIN horiz vert --
Sets the origin of the portrect.
CLIPRECT rectaddr rectbank --
Sets the defined clipping area to the rectangle record located at
addr/bank.
SETPENPAT addr bank --
Sets the pen pattern to the bit pattern at addr/bank.
GETPENPAT addr bank --
Returns the current pen pattern location pointer at the location given
by addr bank.
SETPENMASK maskaddr maskbank --
Sets the pen mask to the mask at location addr/bank.
GETPENMASK maskaddr maskbank --
Places the current pen mask at the addr/bank location.
SETBACKPAT patternaddr patternbank --
n n --
Sets the background drawing mask to the mask at addr/bank.
GETBACKPAT patternaddr patternbank --
n n --
Places the current background drawing mask at addr/bank.
>QD f --
General entry into quickdraw II. If f = 0 then 320 mode will be used,
if 0<> then 640 mode will be initiated. Checks to see if QD is already
on and shuts down first if required. Gets DP space, opens the port,
clears the creen to white, sets black as the forecolor and the pen
color and moves to 0,0. The routine leaves you in the SHR screen.
GS TOOLBOX ERROR CODES
MEMORY MANAGER (Toolset # 2)
Code Description
$0000 No error
$0201 Unable to allocate block
$0202 Illegal operation on empty handle
$0203 Empty handle expected for call
$0204 Illegal call on locked or immovable block
$0205 Attempt to purge an unpurgable block
$0206 Invalid handle
$0207 Invalid user id
$0208 Call illegal on block attributes
MISC TOOLSET (Toolset # 3)
Code Description
$0000 No error
EVENT MANAGER (Toolset # 6)
Code Description
$0000 No error
$0601 Event manager already started, call ignored
$0602 Event manager reset error
$0603 Event manager not active
$0604 Event code is greater than 15
$0605 Button number not 0 or 1
$0606 Queue size > 3639
$0607 Insufficient memory available, event manager
not initialized
$0681 event queue damaged-fatal error
$0682 queue handle damaged-fatal error
QUICKDRAW II (Toolset # 4)
Code Description
$0000 No error
$0401 QD already started up
$0403 QD not initialized
$0410 Super Hires screen reserved
$0411 Bad rectangle
$0420 Chunkiness not equal
$0430 Region is already open
$0431 Region is not open
$0432 Region scan overflow
$0433 Region is full
$0440 Poly is already open
$0441 Poly is not open
$0442 Poly is too big
$0450 Bad table number
$0451 Bad color number
$0452 Bad scan line
SYSTEM TOOL ERRORS
Code Description
$0000 No error
$0001 ProDOS 16 unclaimed interrupt
$0004 Divide by zero
$000A ProDOS 16 Vol Control Block unusable
$000B ProDOS 16 File Control Block unusable
$000C ProDOS 16 Block zero allocated illegally
$000D ProDOS 16 Interrupt with I/O shadowing off
$0015 Segment Loader error
$0017-0024 Can't load a package
$0025 Out of memory
$0026 Segment loader error
$0027 File map trashed
$0028 Stack overflow error
$0030 Please insert disk (File manager alert)
$0032-0053 Memory manager error
$0100 Can't Mount system starup volume
DOUBLE NUMBER GLOSSARY
The double number words follow standard Forth conventions and should
match any text on their use. Double numbers are placed on the stack as
if they were two single numbers, low word first with high word on top.
Double numbers are defined as 31 bits of value and one bit of sign.
2@ addr -- d
Given an address in the current operating bank of GS16FORTH, leaves
the double number in the top two stack positions.
2! d addr --
Stores double number d at addr.
2CONSTANT d -- {at compilation} ! -- d {at runtime}
A defining word used in the form:
d 2CONSTANT cccc
which creates word cccc holding the value d. At runtime invoking cccc
will return the double number value d to the stack. You may use 2! to
alter the contents of cccc. Use the command: d ' cccc 2! to place new
value d in cccc.
2DROP d --
Similar to DROP but drops two numbers form stack. Equivalent to
dropping one double number but can be used in place of DROP DROP.
2DUP d -- d d
Similar to DUP but duplicates two top numbers in the correct order.
Equivalent to OVER OVER and may be used on single numbers.
2OVER d1 d2 -- d1 d2 d1
Copies the second double number to the top of the stack similar to
OVER but acts on both words (32 bits) of double number.
2ROT d1 d2 d3 -- d2 d3 d1
Functionally performs the same as ROT but both words of the double
number are affected.
2SWAP d1 d2 -- d2 d1
Like SWAP but acts on double numbers. Equivalent to 4 ROLL 4 ROLL.
2VARIABLE d -- {at compilation} ! -- addr {at runtime}
A defining word used in the form:
d 2VARIABLE cccc
which creates word cccc holding the value d. At runtime invoking cccc
will return the addr in the current GS16FORTH operating bank that
contains the value d. Use 2@ and 2! to alter or fetch the contents of
cccc.
D- d1 d2 -- d1-d2
Subtracts two signed double numbers. Leaves double number result on
the stack.
D0= d -- f
Performs a test if d is zero. 16 bit flag is returned 0=false,
0<>=true.
D= d1 d2 -- f
Tests if d1 = d2. 16 bit flag is returned 0=false, 0<>=true.
D0< d -- f
Tests if d is negative. 16 bit flag is returned 0=false, 0<>=true.
D< d1 d2 -- f
Tests if d1 is less than d2. 16 bit flag is returned 0=false,
0<>=true.
D> d1 d2 -- f
Tests if d1 is greater than d2. 16 bit flag is returned 0=false,
0<>=true.
M*/ d n u -- d
Performs the sequence d n * u / but uses a 48 bit intermediate to
allow more accuracy. Only d and n signs affect the result.
X2@ addr bank -- d
n n -- d
Fetches a double number value from any where in memory on the IIGS.
Very useful when using the memory manager and allocated blocks. Read
the section on using handles with the memory manager. Remember addr
and bank are in the correct order of a double number to allow pointer
storage in double number variables and constants.
X2! d addr bank --
Stores double number d at any location in memory. See the memory
manager and description of X2@.
GS16FORTH EXTENSIONS GLOSSARY
To save memory many of the possible extensions have been left out of
the pre-compiled version of GS16FORTH. However there are some "extra"
words in the base version that are not found in the standard FIG-FORTH
definitions. Some are there for convienence and some for necessity
because of the use of the PRODOS16 text file interface. Many of the
PRODOS16 words could have been "hidden" from the user but they will be
useful as you write new applications.
CONVIENANCE GLOSSARY
\ -- P
When encountered during execution it executes as an immediate word. It
changes the value of IN such that the remainder of the current line is
ignored. Used to add comments. Differs from ( in that no trailing
delimiter is required.
1- n -- n-1
Often used math function coded in assembler for speed.
2- n -- n-2
Like 1-.
AMASK -- pagezero/bankzero.addr
A system pointer. The ascii value used by EMIT is first logically
and'd with the contents of this page zero address. You must use:
n AMASK 0 XC!
to change the value to n. See OMASK.
DB@ -- n
Leaves the current active Data Bank (0-FF) on the stack. In GS16FORTH
the data bank must equal the program bank. Unless you are "inside" a
word coded in assembler. If you do not reset the data bank to equal
the program bank, Forth will crash. See the code for X@ in the
GSCOMPILER.
EVENTREC -- addr
Because the word KEY uses the event manager this is a block of memory
given to the manager to store information about the event. See a full
description in the source code for the EM.
J -- n
Leaves the outer loop value within nested DO....LOOP's. I leaves the
inner loop. Used to access both counters.
OMASK -- pagezero/bankzero.addr
A system pointer. The ascii value used by EMIT is first logically or'd
with the contents of this page zero address. You must use:
n OMASK 0 XC!
to change the value to n. See AMASK.
PICK n1 -- n2
Returns the n1th stack value not counting n1 itself. 1 PICK is
equivalent to DUP and 2 PICK is equivalent to OVER.
PR# n --
Changes the current output device to slot n. Uses the standard output
hook at $36.
ROLL n --
Extract the nth value to the top of the stack, not counting n itself,
and roll the remaining values downward to the vacated positions. 3
ROLL is equivalent to ROT. 1 ROLL has no effect.
TOP -- max.compilation.addr
A system constant used to define the highest point in memory that
compilation is allowed.
UPPER addr count --
Converts the text located at addr to upper case. Used by WORD so that
the interpreter is not sensitive to lower case.
X@ addr bank -- n
Fetch the word value located at bank/addr. BANK must be between 0 and
FF. The orienta- tion of bank and addr was chosen to accomodate a
standard FORTH double number which has the most significant word on
the top. Therefore a double number calculation or a double number
variable could be used as a direct pointer prior to using X@.
X! n addr bank --
Store word value n at bank/addr.
XC@ addr bank --
Fetch byte value at bank/addr.
XC! n addr bank --
Store byte value at bank/addr.
XCMOVE saddr sbank daddr dbank dcount --
Moves a block of memory from sbank/saddr to dbank/daddr. The count
value must be a double number value because more than 64K can be
moved. Uses the IIgs toolbox. XCMOVE is intelligent and will choose
the correct direction for the move so that no bytes are overwritten.
XFILL daddr dbank count n --
Fill memory at dbank/daddr with n byte value. The amount filled is
passed as count.
XTYPE addr bank count --
Type count characters at the current output device. Characters are
found starting at bank/addr.
PRODOS16 GLOSSARY
In order to use GS16FORTH you must learn a minimum of the PRODOS16
commands. They are OPEN.SCR, CLOSE.SCR and CREATE.SCR. Once a file is
opened the standard FORTH words will function correctly. You also need
to make sure you close a screen file when completed. Lastly you must
learn how to create new files. This is because GS16FORTH uses an
internal PRODOS16 field to store information, so a file-create command
outside of GS16FORTH will not function correctly. The GS16FORTH also
initially clears all screens within a file to blanks. If a screen
contains 0's or other non-printing ascii characters strange things
may, no WILL happen when the screen is compiled or printed to the
screen. This can happen because the full screen editor only affects
the byte at it's current location. Line editors tend to rewrite entire
lines at a time.
+PBLK! n1 n2 --
Store 16 bits of n1 in n2th byte of the PRODOS parameter block. Used
to set up the block prior to making the machine language call.
-DISC addr f --
Performs reading or writing to the disk block depending on the value
of f. If f = 0 then writing occurs, If f <> 0 then reading occurs. The
transferred bytes are either read from addr or written to addr. Used
by R/W.
.PFIX --
Prints the current application prefix on the current output device.
Follows standard FORTH convention of using . to signify printed info.
GS16FORTH will print the current PREFIX #1 used by the forth file
commands each time it returns to keyboard interpretation. If you do
not begin a pathname with a slash 1/ is added automatically.
?MATCH addr1 addr2 count -- f
Created as part of file routines, it looks for .scr suffix on a file.
Very useful for performing a byte by byte match of memory. Memory at
addr1 is compared to addr2 for count length of bytes. Leaves 0 on the
stack if no match and -1 if matched. Written in machine language for
speed.
?MAXSCRS --
Reads the highest available number from a screen file and stores in
the variable MAXSCR. Gets the number from the PRODOS aux field.
?PERROR n --
If n is not zero, prints a PRODOS error with message number n. Used
after returning from PRODOS machine language calls to determine if
there was an error. If error ?PERROR ends with quit.
AUTOLOAD -- addr
System variable that holds the value of the first screen that will be
loaded with a command LOAD.SCR. Default is 1 but a user may change if
required.
BYE --
Invokes the PRODOS quit command. Shuts down the event manager and
releases all memory owned before exiting. Leaves the FORTH language
and change to another application program.
CD --
Used in the form:
CD /cccc
Where /cccc is a new PRODOS prefix to be the system prefix. Stands
for; change directory. The system prompt will change to reflect the
new prefix. NOTE: Unlike Prodos8 PRODOS 16 does not return an error if
the pathname is invalid. You will only get an error when you try to
access the disk.
CLINE --
Clears screen display from cursor to end of active screen line.
CLOSE ref# --
PRODOS close file command. Enter with file ref# on stack or required
purge level. Using 0 CLOSE will close all open files. If invalid ref#
an error is returned.
CLOSE.SCR --
Close the open screen source file. REF# and MAXSCR are set to 0. Gives
confirmation that the file was closed. If no screen file is open, then
no action is taken.
CLRSCRS n1 n2 --
Clear (initialize to blanks) source screens from n1 to n2 inclusive.
Confirmation is given that the screens are being cleared. Used by
CREATE.SCR to initialize a new file.
CREATE.SCR n --
Create a new source screen file of n screens. The suffix .scr is
automatically added to the file name if you don't add it yourself.
Don't forget to declare n or you may create
a very large file by mistake. Any PRODOS16 errors are returned.
DESTROY --
Destroys (deletes) the PRODOS file whose name is stored at the
variable PNAME. The file name is stored at PNAME with a leading count
byte. Be careful with destroy. You are not given the chance to stop
the action once invoked.
DESTROY.SCR --
Prompts for a source screen file name and destroys that file. The .scr
suffix will be added if you do not include it. You are prompted to
declare you really want to do it.
FCREATE access filetype storagetype --
Creates a PRODOS16 file with the respective attributes from the stack.
Used by CREATE.SCR.
GET.EOF ref# -- d
Input the ref# of an open file and the current length of the file is
returned as a double number value.
GET.INFO --
Fills the variable PARMBLK with the file's PRODOS16 information. The
format of this info can be found in the PRODOS16 Technical Reference
Manual. The variable PNAME must already be set with the proper
filename with a leading count byte. PRODOS errors are returned.
GET.PFIX --
Places the current application prefix in the variable PFIX with a
leading count byte.
LENGTH.SCR --
A routine to change the the maximum number of screens in a file. A
file may be lengthened or shortened. When compressed the higher
screens are permanently lost ! The routine does not use the stack but
prompts you for the file name and size.
LOAD.SCR --
Automatically closes any open screen files and prompts for file to
load. It then begins loading the screen number stored in the variable
AUTOLOAD. Loading will continue if you use --> until a screen ends
with blank line(s) or a S;
MAXSCR --
A system variable that contains the highest available screen within
the current open screen file.
MKDIR used in the form: MKDIR cccc
Where cccc is the name of the new directory to make. The directory is
attached to the current system prefix.
SYSCALL n -- f
The actual machine language interface to PRODOS 16. Enter the word
with the command number on the stack. The parameter list must have
been set correctly before executing SYSCALL. After executing f
contains the PRODOS error number. A zero and clear carry flag indicate
no error. See PRODOS16 error list and the end of this section.
OPEN -- ref#
Opens the requested PRODOS file. The variable PNAME must already have
been set with a leading count byte. Returns the files ref# on the
stack. This number is used for further file commands.
OPEN.SCR --
Opens the requested screen source file. Prompts for the filename and
adds suffix .scr if you do not. The file ref# is stored in variable
REF# and the filename is stored in PNAME.
PARMBLK -- addr
A variable of $18 bytes used to pass parameters to the SYSCALL
command. SYSCALL is permanently pointed to PARMBLK.
PFIX -- addr
A variable of $41 bytes used to store PRODOS prefixs. The first byte
is a count byte followed by a maximum of 64 characters.
PNAME -- addr
A variable of $41 bytes similar to PFIX but used to store PRODOS
filenames.
READ dataaddr databank dcount ref# -- actualcount
Read count number of bytes into data location dataaddr at databank,
using the file with ref#. Note that it takes a combination of addr and
bank because PRODOS16 can access more than 64K. Likewise count must be
a double number because more than 64 K can be transferred at one time.
The orientation is the standard double number orientation. The actual
amount transferred is returned on the stack as a double number. The
file must have been previously opened and you should have set the file
pointer with the command SET.MARK.
REF# -- addr
A system variable used to store the ref# of the currently opened
screen file.
SET.EOF d ref# --
Sets the PRODOS logical screen file end to a length passed in d
(double number value). Do not use for screen files. Use LENGTH.SCR
which does all the work and initializes screens
if added. The file with ref# is affected and must have been opened
already.
SET.INFO --
Takes the values already stored at PARMBLK and makes them the new
values of the requested file. The filename must have been already set
in the variable PNAME with a leading count byte. Most common use is to
use GET.INFO alter one or two attributes and use SET.INFO to
permanently save the changes. This is how LENGTH.SCR changes the
maximum number of screens in a file.
SET.MARK d ref# --
Set the internal PRODOS pointer to d (double number). The file ref# is
affected. 0. ref# sets the pointer to the start of the file. Make sure
this is done before you save non-screen files.
SET.PNAME --
Prompts for a filename and places at variable PNAME. The input is
counted and the count is placed at the first byte. Input is limited to
64 characters. If the pathname is not started with a slash then 1/ is
added to the front of the pathname signifying the current Forth prefix
that is displayed. The commands PNAME COUNT TYPE will type the current
filename stored at PNAME.
WRITE dataaddr databank dcount ref# --
Writes count number of bytes at location dataaddr and databank to
disk. Count and Data areas are referenced as double numbers because
PRODOS16 can access more than 64K. The file with ref# is affected. The
file must have been opened first.
PRODOS ERROR CODES
General Errors
Code Error
$00 No Error
$01 Invalid Call Number
$07 PRODOS is busy
Device Call Errors
Code Error
$10 Device not Found
$11 Invalid Device Request
$25 Interrupt Vector Table Full
$27 I/O Error
$28 No Device Connected
$2B Write-Protected
$2D Invalid Block Address
$2E Disk Switched
$2F Device not on Line
File Call Errors
Code Error
$40 Invalid Pathname or Device Name Syntax
$42 FCB Table Full
$43 Invalid Reference Number
$44 Path Not Found
$45 Volume Not Found
$46 File Not Found
$47 Duplicate Pathname
$48 Volume Full
$49 Volume Directory Full
$4A Version Error
$4B Unsupported Storage Type
$4C End of File Encountered
$4D Position Out of Range
$4E Access Not Allowed
$50 File is Open
$51 Directory Structure Damaged
$52 Unsupported Volume Type
$53 Parameter Out of Range
$54 Out of Memory
$55 VCB Table Full
$57 Duplicate Volume
$58 Not a Block Device
$59 Invalid Level
$5A Block Number Out of Range
$5B Illegal Pathname Change
$5C Not an Executable File
$5D Operating System/File System Not
Available
$5E Cannot Deallocate Ram
$5F Return Stack Overflow
$60 Data Unavailable
Fatal Errors
Fatal errors signify a serious malfunction. Rebooting must occur
before you may continue.
Code Error
$01 Unclaimed Interrupt
$11 Wrong OS Version
$0A VCB Unusable
$0B FCB Unusable
$0C Block Zero Allocated Illegally
$0D Interupt Occured with I/O shadowing off
MC HELP
MYSTERY COLORS by Warren Stone
A Demonstration program for GS16FORTH, a powerful implementation
of the Forth language, exclusively for the Apple IIGS.
Standard Features: Native mode 65816 code, full 65816 Assembler,
fullscreen Editor and ROM toolbox support; including the Memory
Manager, Event Manager, Quickdraw II & Misc Tools.
Optional Features (requires std package): RAM toolbox support for
Window Manager, Menu Manager, Standard File Operations, Dialog
Manager and Control Manager.
See how easy programming the IIGS can be ! For more information
write: GSF 1529 Torre Ct. San Jose, CA. 95120
The object of the game is to decipher a color code created by the
computer. You alter the difficulty by picking the number of pos-
itions and available colors.
You guess by clicking on a color in the available color box. When
all positions are filled, the guess is scored. The computer will
tell you how many dots are of the correct color AND in the right
position. It will also tell you how many dots are of the correct
color BUT in the wrong position. A color dot will never be counted
twice, if it is scored "correct position & color" then it will not
be included in the correct color score.
The rest is up to you, start easy with a low count for colors
and positions. Remember, the available colors may be used more
than once in the code. A code of all the same color is legal !
MENU DESCRIPTIONS
New: Opens a new window and starts a new game. If window is
already open, then replays a game with same difficulty.
Open: Opens and loads a previously saved game. Game is re-
stored at the condition it was saved at.
Close: Stops current game and closes window.
Save: Save the document under the current windows name.
Save As: Saves the current game, you are prompted for a file
name to save with.
Undo: Used to "erase" a partial guess. You cannot erase a
scored guess.
Change Difficulty: Used to alter the number of positions and
colors. May not be used except when a game is complete.
| |