53 replies to this topic

[Lee Stewart]

Vorticon, on Wed Feb 22, 2012 9:50 PM, said:

That would be great! Thanks

OK.  Here it is:  <see previous post>

...lee

PS: Sorry for the duplicate post! It should be possible to delete your own post; but, alas, that does not seem possible.

Edited by Lee Stewart, Thu Feb 23, 2012 1:52 PM.

[Vorticon]

Lee Stewart, on Thu Feb 23, 2012 1:38 PM, said:

Vorticon, on Wed Feb 22, 2012 9:50 PM, said:

That would be great! Thanks

OK.  Here it is:  

...lee

Much obliged

[Vorticon]

Lee, what are the major differences between your PDF manual and the original TI Forth manual? I have the latter.

[Lee Stewart]

Vorticon, on Fri Feb 24, 2012 1:37 PM, said:

Lee, what are the major differences between your PDF manual and the original TI Forth manual? I have the latter.

The following details all the major differences between the two from the point of view of my Edition:

• Better presentation IMHO.
  
  • Much more detailed Table of Contents (TOC), almost obviating the need for an Index (I still want to add one, however).
    
  • Addition of a titled, much more detailed Section structure to make possible the increased detail in the TOC.
• 1.1 Editor's Note [New section]
  
• 2.5 Control Structures
  
  • Explanation of CASE ... ENDCASE structure. Original had poor to none.
• 5.1.2 Extended Utilities GPLLNK , XMLLNK and DSRLNK
  
  • DSRLNK comments.
• 5.2 Disk Utilities [More information]
  
• 6.3 Color Changes
  
  • Better explanation of SCREEN
• 6.6.6 Distance and Coincidences between Sprites
  
  • More detail on the mathematics of SPRDIST and SPRDISTXY
• 6.8 Using Joysticks  [Better explanation of use of joysticks]
  
• 7 The Floating Point Support Package  [Somewhat better organization of material, especially "7.9 Interface to the Floating Point Routines"]
  
• 8 Access to File I/O Using TI-99/4A Device Service Routines
  
  • A few more details
    
  • A note that SCRTCH cannot be used
• 9 The TI Forth 9900 Assembler
  
  • A few corrections
    
  • Explanation of NEXT,
• 9.9 Handling Forth Stacks [New section]
  
  • Explains how to manage the Paramter and Return stacks in TI Forth Assembler
• 10.2 An Example of an Interrupt Service Routine [Corrected example]
  
• 11.1.1 Customizing How TI Forth Boots Up [Elaborated]
  
• 11.1.2 An Overlay System with BSAVE / BLOAD [New section]
  
• 11.1.3 An Easier Overlay System in Source Code [New section]
  
• 12 TI Forth Dictionary Entry Structure  [New Chapter]
  
• Appendix C Differences between Starting FORTH and TI Forth [A few corrections]
  
• Appendix D The TI Forth Glossary
  
  • New introductory Paragraph
    
  • Added a footer on every page that displays the ASCII collating sequence to aid the user in finding words that begin with non-alphanumeric characters
    
  • Better explanations of some words, notably
    
    • CASE
      
    • ENDCASE
      
    • OF
      
    • ENDOF
      
    • FENCE
      
    • FORGET
      
    • SIGN
      
    • STR.
      
    • TASK
      
    • USER
  • Re-ordered word entries because a few words were out of order
    
  • Added a missing word: ASSEMBLER
    
  • Corrected misspelled word: FORTH_LNK
• Appendix E User Variables in TI Forth
  
  • Corrected missing VDPMDE
• Appendix G Assemby Source for CODEd Words  [Added "Editor's Notes" that correct mistakes in this appendix]
  
• Appendix I Contents of the TI Forth Diskette [Corrected screens per "Appendix J" below]
  
• Appendix J TI Forth Bugs  [New Appendix]
  
• Appendix K Diskette Format Details  [New Appendix]
  
• Appendix L TI Forth System for Larger Disks  [New Appendix]

...lee

Edited by Lee Stewart, Sat May 12, 2012 9:18 AM.

[Lee Stewart]

I am contemplating adding the original TMS9900 Assembler source code for TI Forth to my edited and expanded TI Forth Instruction Manual, along with instructions on creating a working TI Forth system from the source code and the original TI Forth system screens.  Any interest or ideas?

...lee

[Vorticon]

Lee, this would be nice to have for archival purposes, although personally it's very unlikely I will ever use it. Who knows though, someone may some day decide to port TI FORTH to another environment

[Lee Stewart]

I keep finding niggling little errors in my "First Edition" of the TI Forth Instruction Manual.  I will need to work on a 2nd Ed. ere long!  One erratum that perhaps I should correct here is on page 19 in the memory map of the CPU RAM Pad at 83C4h:  I have it labeled "Link to DSR Hook".  WRONG!  It should be "Link to ISR Hook".

...lee

[Lee Stewart]

While reviewing my first edition of the TI Forth Instruction Manual for corrections and possible expansion as well as trying to understand how defining words work in TI Forth, I discovered an error in the definition of ;CODE that renders it inoperable!  Its precedence bit must be set for it to function properly, i.e., its definition must be followed by IMMEDIATE , which is missing from the definition in Block #74 on the TI Forth system disk.  I have never seen this error described before, though surely somewhere someone must have documented it.  The explanation of ;CODE in the manual was not very satisfying, so I attempted to use the word.  All I succeeded in doing was to crash TI Forth.  I reviewed all the literature I could find on fig-Forth defining words (that create other defining words) like CREATE , CODE , ;CODE , (;CODE) , <BUILDS and DOES> .  The light went on when I realized that the precedence bit of ;CODE  was not set---this after reading in more than one place that ;CODE must execute during compilation of the word in which it was present.

One reason it took me so long to "get it" was the whole idea of creating Forth defining words is not easy to grasp.  Another reason was that, though TI created ;CODE to no doubt implement as much of fig-Forth as possible, nowhere did they ever use it!  If there had been just one example of its use on the TI Forth system disk, it would have helped my understanding much sooner.  The error would probably not have persisted, either.

Here is the corrected definition:

: ;CODE

?CSP COMPILE (;CODE) SMUDGE
[COMPILE] [ [COMPILE] ASSEMBLER

; IMMEDIATE

I will post an example of its use later.

...lee

[Lee Stewart]

Before giving an example of defining a TI Forth defining word with ;CODE , I should explain why you might want to use it in the first place.  

The defining words that are part of the TI Forth kernel are : (paired with ; ), VARIABLE , CONSTANT , USER , VOCABULARY , <BUILDS (paired with DOES> or ;CODE [not in kernel]) and CREATE .  The defining words CODE and ;CODE are defined on the system disk and must be loaded with -CODE to be used.  Most words you would ever need to define can be created with the first three ( : , VARIABLE and CONSTANT ).  However, you too can use <BUILDS and CREATE , the same words used for defining most of the above, for the eventuality that these do not suffice.

In fig-Forth and TI Forth, it is not useful to use CREATE on the command line unless you really know what you are doing because it creates a dictionary header in which the smudge bit is set and the code field points at the parameter field with no storage allotted for it.  This means that the parameter field must be allotted with executable code (or the code field changed to point to some) and the smudge bit must be reset so a dictionary search can find the word.  The same discussion obtains for <BUILDS except for the smudge bit because <BUILDS is defined as

: <BUILDS CREATE SMUDGE ;   ( SMUDGE toggles the smudge bit.)

This situation is made easier by using <BUILDS , DOES> and ;CODE within colon definitions as

: NEW_DEFINING_WORD <BUILDS ... DOES> ... ;

or

: NEW_DEFINING_WORD <BUILDS ... ;CODE ...

You simply replace the first "..." with words you want to execute when NEW_DEFINING_WORD is compiling a new word, e.g., to reserve space for and store a value in the first cell of the parameter field using , .  You then replace the second "..." with code to be executed  when the new word actually executes.  It will be this code to which the code field of the new word will point.

Here is an example of the use of ;CODE in the definition of a defining word, i.e., a word that creates new words:

CONSTANT is a TI Forth word that defines a word, the value of which is pushed to the stack when the word is executed.

9 CONSTANT XXX

defines the word XXX with 9 in its parameter field and the address of the execution code of CONSTANT in its code field.  TI Forth defines CONSTANT in high-level Forth essentially as

: CONSTANT <BUILDS , DOES> @ ;

Using ;CODE and after loading the TI Forth Assembler with -ASSEMBLER , it could also be defined with Assembler code as

: CONSTANT <BUILDS , ;CODE SP DECT, *W *SP MOV, NEXT,

which, once you know the machine code, can be coded without the Assembler loaded as

HEX

: CONSTANT <BUILDS , ;CODE 0649 , C65A , 045F ,

For CONSTANT , the first definition is easier to understand.  They are both the same length.  They both create words of the same length.  However, there may come a time when only Assembler will do your bidding and ;CODE offers that facility.


...lee

[CantStopClicking]

Wow, thanks for all the hard work!  I'm allergic to documentation, so I can totally appreciate what you've provided here!

[Lee Stewart]

CantStopClicking, on Sat Mar 9, 2013 12:01 AM, said:

Wow, thanks for all the hard work!  I'm allergic to documentation, so I can totally appreciate what you've provided here!

Thanks.  I enjoy it.  It certainly can get tedious at times, however.  I hope to get my second edition of the TI Forth Instruction Manual out within the next several weeks.  I want to get on with converting TI Forth to using files for blocks (screens) instead of sector I/O.  Then I can think about hoisting TI Forth into cartridge space!

...lee

[Lee Stewart]

I got sidetracked a bit...

I've been looking at how I might consolidate the code for the two editors (64- and 40-column) in TI Forth with an eye to putting it/them into the kernel that will one day find its way into cartridge space (I hope) when I discovered a couple of bugs.  I plan to include this information in the second edition of the TI Forth Instruction Manual.

The first one is not really a bug, just a leftover word that must have been abandoned and then forgotten.  It is the word BCK in Block #22 of the 64-column editor on the system disk.  This word is defined and actually used in the 40-column editor.

The second one is a bug, though not a serious one.  The 40-column editor defines BOX in Block #34 to write a box outline pattern to the VDP location of the text cursor (ASCII 1Eh), which is a solid rectangle when TI Forth boots up.  The word is executed only once when the editor word VED is executed.  The bug occurs upon exiting the 40-column editor by virtue of the editor's failure to restore the solid text cursor.  It can be fixed in a couple of ways.  I chose the following, which minimally redefines BOX , BCK and VED (additions shown in red and deletions as red):

: BOX  ( byte --- )  8F7 8F1 DO 84 DUP I VSBW LOOP DROP ;  ( Block #34 )

: BCK  ( --- )  0 L/SCR 2+ GOTOXY -1 BOX QUIT ;  ( Block #35 )

: VED  ( block offset --- )  84 BOX SWAP ... ;  ( Block #38 )

[Note:  The definition of VED above is actually much longer, the shortening indicated by the ellipsis.]

BOX now expects a byte value on the stack.  That byte gets written to the 2^nd--7^th bytes of the character pattern (starts at 8F0h) for the text cursor in the pattern descriptor table, leaving the 1^st and 8^th bytes alone.  The value 84h (bit pattern: 10000100) in those positions hollows out the interior of the cursor and the value -1 (bit pattern: 11111111) restores the solid cursor.  Because the rightmost two bits are not rendered in text mode, the 84h could just as easily be 85h, 86h or 87h; the decimal -1 could also be -2, -3 or -4.

Another way to fix the bug is to save the incoming cursor pattern and restore it upon exit.  This would require a few more bytes, but would allow for a user-defined cursor that would get properly restored instead of clobbered by the above code.

...lee

[funkheld]

Hello, good day.
Why startet the TI-Forth from the Disk in the Winn99a-Emu ?

Thanks you
Greeting
peter

[Lee Stewart]

funkheld, on Fri Mar 29, 2013 4:03 AM, said:

Hello, good day.
Why startet the TI-Forth from the Disk in the Winn99a-Emu ?

Thanks you
Greeting
peter

You need a TI Forth system disk with a "TIDisk" extension:  TI-Forth.TIDisk is the one in the Disks.zip file available on the download page for Win994A at www.99er.net.  There are variations I have posted on this forum as DSK images (V9T9 format).  If you have it as a V9T9 DSK file (TI-Forth.DSK, for example), you can rename it to TI-Forth.TIDisk.

You also need the Editor/Assembler (E/A) cartridge file.  It is part of the Cartridges.zip file also available on the Win994A download page at www.99er.net.

The TI Forth system disk needs to be mounted as DSK1 and is started from E/A option 3 with "DSK1.FORTH" as the filename.

You should have at least one work disk mounted in DSK2 and try to avoid writing to the system disk in DSK1.  Be sure to make a backup of the system disk before you start TI Forth because it is easy to destroy it as you learn the system.

Let me know if you need anything else.

...lee

[funkheld]

Hello, thanks.
Why is the "started from E/A option 3" ?

Thanks you

[Lee Stewart]

funkheld, on Fri Mar 29, 2013 9:52 AM, said:

Hello, thanks.
What is the "started from E/A option 3" ?

Thanks you

E/A is short for Editor/Assembler and option 3 is "Load and Run".  Below is an animated GIF that might help to explain.  The delay is 3 seconds between frames.  If you would like me to change the frame delay, let me know.

 TI-Forth_Win994a.gif   170.56K   18 downloads

...lee

[Lee Stewart]

Before I finish my second edition of the manual, I am going to indulge a little in improving TI Forth to use file-based block I/O instead of sector I/O.  One reason for doing this is that these side trips (like the one a couple of posts back regarding editor consolidation) have helped me to learn more about the innards of TI Forth as well as to uncover bugs, all of which helps in updating the manual.  Another reason is that editing the manual gets a little boring at times!

Anyway, I will shortly start another thread to discuss adding file-based block I/O to the current TI Forth because that project will require a different manual to accommodate the extensive changes in the system that will result.  In fact, I should probably call the system something different from "TI Forth" to prevent confusion.  I think I'll entitle the discussion thread "TI Forth with File-based Block I/O".  I can always change it later if I change the name of my "new" TI Forth.

...lee

[Opry99er]

Hey Lee, did you ever see that series I found on "Hacking Forth" by Mike McCaan?  

I think it's been digitized since I donated it... Found it in an old binder in an airport hangar in Indiana.  =)  Pretty interesting stuff in there, IIRC.

[Lee Stewart]

Opry99er, on Fri Apr 12, 2013 12:30 AM, said:

Hey Lee, did you ever see that series I found on "Hacking Forth" by Mike McCaan?  

I think it's been digitized since I donated it... Found it in an old binder in an airport hangar in Indiana.  =)  Pretty interesting stuff in there, IIRC.

Can't say that I have.  I went looking for it and couldn't find it.  Some message traffic from you on one of the Yahoo groups said it was on Planet99, but it's not there as far as I can tell.

...lee

[Opry99er]

I think I sent Bill Gaskill the originals... If you can get ahold of him, he would still have them.  =)

[Opry99er]

I think if you go to the site, you can find it here..

.

>Documents
>PDF Documents
>Forth
>1985-mccan_hacking_forth.Zip

Owen

[Opry99er]

I just looked and they seem to be gone.....  Hmmmmmm........

[Opry99er]

This is what Bill posted when he uploaded them.

Quote

My thanks to Owen Brand. Here are 26 pages of irreplaceable history that would have been lost in the shuffle of time but for his efforts.

Go to the Downloads drop down menu at the top right portion of the Planet-99 home page and them drill down to the document as follows:

>Documents
>PDF Documents
>Forth
>1985-mccan_hacking_forth.Zip

BillG

[Lee Stewart]

OK...I am almost done with my second edition of the TI Forth Instruction Manual.  I should be posting it in a day or two, I think.  Then I can get on with modifying TI Forth with File-based Block I/O.

...lee

[Lee Stewart]

I guess I should re-mention that my first edition of the manual is in the TI-99/4A development resources sticky thread on this forum here:  TI Forth Instruction Manual "1st Edition 2012", so you have a reference for the corrections and expansion I will be posting.

...lee