Bitchin100 DocGarden - User contributions [en]

Building VirtualT on Linux

2011-08-31T16:51:10Z

99.6.119.22: /* This Sounds Hard... Why All The Steps? */

== What is this "Linux" You Speak Of? ==

These instructions have been tested on

* Debian
* Ubuntu
* Slackware

Please add to the list if you have tested on another distribution.

== This Sounds Hard... Why All The Steps? ==

Because of the rich variety of Linux distros that grace our planet we need volunteer support to maintain good "packages" for each one. That's the best route... then no documentation is needed for install. Short of that, Linux users simply have to build VirtualT themselves. Of course the benefit of building it yourself is that you always have the latest and greatest features, and of course bugs... but that's what makes life exciting, right?.

A side benefit is that it increases the amount of people on the latest and greatest. That means more testers of new features. If you have a version that works well for you, keep that in mind before you
<code><pre>cvs update</pre></code>
to get latest and greatest.

== Download Latest VirtualT Source FOR THE FIRST TIME ==

Open a command prompt and type:

<code><pre>cvs -z3 -d:pserver:anonymous@virtualt.cvs.sourceforge.net:/cvsroot/virtualt co -P VirtualT
</pre></code>

== Download Packages FLTK Depends On ==

(a version of this command for RPM or source based distros would be nice)

Command to download FLTK dependencies on Debian:

sudo apt-get build-dep libfltk1.1

Command to download FLTK dependencies on Debian Lenny (stable):

sudo aptitude install libfltk1.1 libfltk1.1-dev libxext-dev build-essential

== Download, Build FLTK dependency ==

VirtualT depends on the FLTK library. FLTK is hosted at http://www.fltk.org/software.php . Download a version of fltk. These instructions were last tested with fltk-1.1.9 . Decompress the package.

Change directory into fltk-x.y.z

Configure and make fltk:

<code><pre>
./configure --enable-localjpeg --enable-localzlib --enable-localpng
make
</pre></code>

== Updating to Latest VirtualT ==

<code><pre>
cvs update
</pre></code>

== Building VirtualT ==

cd into VirtualT.

ls

If you see a folder named vt_client or vt_client_src, remove it

rmdir vt_client
or
rmdir vt_client_src

<code><pre>
export FLTKDIR=/where/is/fltk-x.y.z
make
</pre></code>

then make should work.

You should end up with a file titled 'virtualt' in your build directory. You can launch it by typing

<code><pre>
./virtualt
</pre></code>

ASCII Table One-Liner

2011-08-13T19:17:23Z

99.6.119.22: /* Listing */

This program displays the Model 100/102 printable character set.

<pre>
FORY=1TO7:FORX=0TO31:C=Y*32+X:IFC=127THENPRINT:NEXTY:ELSEPRINTCHR$(C);:NEXT:PRINT:NEXT:Z$=INPUT$(1):MENU
</pre>

== Output ==

[[Image:ASCII-OUT.gif]]

ASCII Table One-Liner

2011-08-13T19:16:59Z

99.6.119.22:

HTERM

2011-08-03T03:42:47Z

99.6.119.22:

== Purpose ==

HTERM is a "dumb terminal" program which implements hardware flow control and rudimentary handling of UTF-8 encoding and ANSI escapes.

== Source Code ==

Git repo: http://bitchin100.com/pub-git/hterm.git/

== Latest Build ==

(No released build with Unicode support yet)

=== M100/T102 ===

http://bitchin100.com/files/m10x/HTERM.CO

http://bitchin100.com/files/m10x/HTERM.lst

=== T200 ===

http://bitchin100.com/files/t200/HTERM.CO

http://bitchin100.com/files/t200/HTERM.lst

== Unicode Support ==

HTERM is primarily designed to interface with Linux systems, either directly connected or through a serial to network bridge. Login consoles on Linux generally use ANSI escapes and UTF-8 encoding.

UTF-8 is a Unicode "encoding." It is a way of representing Unicode characters in an 8-bit byte format. Unicode itself is an abstraction... characters in Unicode have a range of 32-bits, with no defined wire or in-memory structure. UTF-8 is one such format.

The Model T laptops also have a 8-bit character code. For characters in the range 0-127, the ASCII range, the characters are the same in UTF-8. For characters above 127, there is no defined correlation between Unicode and the Model T.

HTERM creates such a correlation. HTERM manages converting between UTF-8, an in-memory Unicode representation, and the Model T's displayable character set.

It turns out that most of the Model 100's character set maps to the 16-bit Unicode range. Given that, and the fact that the Model 100 can deal directly with 16-bit values, HTERM only supports mapping of Unicode characters in the 16-bit range. If it receives a character outside of that range, it will treat it as an unmapped character.

HTERM

2011-07-30T23:31:03Z

99.6.119.22: /* Unicode Support */

== Purpose ==

HTERM is a "dumb terminal" program which implements hardware flow control and rudimentary handling of UTF-8 encoding and ANSI escapes.

== Source Code ==

Git repo: http://bitchin100.com/pub-git/hterm.git/

== Unicode Support ==

HTERM is primarily designed to interface with Linux systems, either directly connected or through a serial to network bridge. Login consoles on Linux generally use ANSI escapes and UTF-8 encoding.

UTF-8 is a Unicode "encoding." It is a way of representing Unicode characters in an 8-bit byte format. Unicode itself is an abstraction... characters in Unicode have a range of 32-bits, with no defined wire or in-memory structure. UTF-8 is one such format.

The Model T laptops also have a 8-bit character code. For characters in the range 0-127, the ASCII range, the characters are the same in UTF-8. For characters above 127, there is no defined correlation between Unicode and the Model T.

HTERM creates such a correlation. HTERM manages converting between UTF-8, an in-memory Unicode representation, and the Model T's displayable character set.

It turns out that most of the Model 100's character set maps to the 16-bit Unicode range. Given that, and the fact that the Model 100 can deal directly with 16-bit values, HTERM only supports mapping of Unicode characters in the 16-bit range. If it receives a character outside of that range, it will treat it as an unmapped character.

HTERM

2011-07-28T22:24:25Z

99.6.119.22:

== Purpose ==

HTERM is a "dumb terminal" program which implements hardware flow control and rudimentary handling of UTF-8 encoding and ANSI escapes.

== Source Code ==

Git repo: http://bitchin100.com/pub-git/hterm.git/

== Unicode Support ==

HTERM is primarily designed to interface with Linux systems, either directly connected or through a serial to network bridge. Login consoles on Linux generally use ANSI escapes and UTF-8 encoding.

UTF-8 is a Unicode "encoding." It is a way of representing Unicode characters in an 8-bit byte format. Unicode itself is an abstraction... characters in Unicode have a range of 32-bits, with no defined wire or in-memory structure. UTF-8 is one such format.

The Model T laptops also have a 8-bit character code. For characters in the range 0-127, the ASCII range, the characters are the same in UTF-8. For characters above 127, there is no defined correlation between Unicode and the Model T.

HTERM creates such a correlation. HTERM manages converting between UTF-8, an in-memory Unicode representation, and the Model T's displayable character set.

Main ROM Management Feature

2011-07-20T00:25:39Z

99.6.119.22:

== Overview ==

Main ROM Management, supported in release 4.6, is feature in REX whereby the internal system ROM(s) may be replaced by specific blocks in REX. There are 4 blocks reserved for this - block 2 (2 and 3 for T200) for the "Primary" Main ROM, and block 4 (4 and 5 for T200) for the "Secondary". In the M100/T102, only 32k is required for the Main ROM, but in the T200, 64k is needed (occupying block 3 and 5 also).

== Why would you want this?? ==

Well, you get to apply updates to your system ROM.
* Y2K fix
* custom character sets
* Lomem modification
* fixs to other known bugs in the M100 rom
* Your own name replacing Microsoft
* you get the idea.

How I recommend approaching this, is to leave the default standard main ROM image in block 2, and the put any crazy new main roms in block 4. That way you always have a good system ROM to rely on.

The Primary main ROM (block 2) is the power up default for REX, and should be handled carefully.

== How it works ==

REX Manager always uses the Primary ROM to operate, but allows the selection of either Primary or Secondary when using the laptop and applications. (REXMGR needs the standard image routines).

When configured correctly, the user can identify which ROM image should be operational. At power up, REX defaults to operate from the Primary ROM, however as part of the autoconfiguration function, the user's preference of Primary or Secondary is detected and configured, so that the laptop is operating in it's prefered state.

'''NOTE - IF YOU PUT A BAD IMAGE IN PRIMARY AND USE IT, REX WILL BE NON FUNCTIONAL. YOU WILL HAVE TO PHYSICALLY REINSTALL YOUR MAIN ROM TO RECOVER.'''

'''NOTE - IF YOU PUT A BAD IMAGE IN SECONDARY AND SELECT IT, REX WILL BE NON FUNCTIONAL. YOU WILL HAVE TO COLD BOOT YOUR LAPTOP TO RECOVER.'''

You can use the checksum feature to confirm your loading of images.

To replace the system ROM you have to do a few things

* Prepare REX by inserting a specific default system ROM image in the Primary location.
* Disable your internal main ROM (remove it or otherwise)
* Connect the chip select line for the main ROM to TP1 on REX. This involves soldering.

== The Primary ROM Image ==

Turns out that REX cannot easily tell when it is providing the main ROM or not. But, since there is both a Primary and Secondary main ROM capability, REX needs to know if it is providing the function so that it can be managed correctly.

How we get around this limitation is that, for any Main ROM image in REX, we must embed a specific sequence in a specific location, to tell REX when it's main ROM images are active.

'''Any ROM image that is installed in REX for use in Main ROM Replacement must have a small signature included.'''

This signature is the chaning of the word "MENU" to the word "Menu" at offset 0003h in the standard binary image. When REX sees lower case characters, it "deduces" that the original internal ROM is no longer in use, and one of the REX based main ROM images is in use.

== Loading Primary and Secondary Images ==

Using REX Manager (4.6 or higher), tab to the SYS menu. In this menu you may load 32kb images from TPDD representing your desired ROM images into either the Primary or Secondary locations.

== Using Primary or Secondary Images ==

Once you have
* loaded at least the default Primary image FIRST, and
THEN
* opened up your laptop and
* disabled your main ROM(s)
* run and wire from /CS of the Main ROM to TP1 on REX
* if T200, then run a wire from /CS of the 2nd (8kb) Main ROM to TP2 on REX
then REX will be able to manage your main ROMs.

REX Manager always uses the Primary ROM, but allows the selection of either Primary or Secondary for laptop applications.

You can freely update your Secondary ROM as you wish to implement and try out other ROM images. So long as the Primary ROM remains intact you can always recover your REX from a nasty main ROM installation in the Secondary ROM.

Once REX is providing the main ROM, users cannot update, change or delete the Primary image on REX using REX Manager.

== The Hardware Mod ==

There are lots of ways to this. It is much easier on T200 and M100 than T102, since the ROM in T102 is soldered.

The minimum job is to disable the internal ROM(s) and hardwire REX to the /CS lines. A more clever thing to do is to make a little switch circuit that allows the main rom chips to be selected or deselected manually. That is possible but more work.

For now I will say consult the schematics for detailed information, and roll your own.

For M100/T200, I would it is as easy as removing the main ROM chip(s) and running a single wire to REX from the /CS pin on the ROM socket to TP1 (TP1 and TP2 on T200).

For T102, you have to disable the main ROM, either by snipping /CS and soldering the chip pin to +5V, or by removing the chip completely.

On T200, the first Main ROM (32kb) is M15 and /CS is on pin 20. Also, the 2nd Main ROM (8kb) is M13 and /CS is on pin 22.

== Main ROM Image files ==

The following files are default base image files which have been modified for use with Main ROM Management. They have MENU converted to Menu at 0003h. These files also have the Y2K patch applied.

Using the T102 image in the M100 is a nice way to get the fixes for a number of small ROM bugs in the original operating system.

<table border="1">
<tr><td>Model</td><td>Description</td><td>File</td><td>Checksum</td><td>Submitter / Date</td></tr>
<tr><td>M100</td><td>Default Image</td><td>[[Media:R_M100.BR|R_M100.BR]]</td><td>A32C</td><td>[[User:Sadolph|Sadolph]] 08:59, 18 October 2010 (PDT)</td></tr>
<tr><td>T102</td><td>Default Image</td><td>[[Media:R_T102.BR|R_T102.BR]]</td><td>A922</td><td>[[User:Sadolph|Sadolph]] 08:59, 18 October 2010 (PDT)</td></tr>
<tr><td>T200</td><td>Default Image for 32k Main ROM</td><td>[[Media:RT2001.BR|RT2001.BR]]</td><td>E168</td><td>[[User:Sadolph|Sadolph]] 04:02, 14 February 2011 (PST)</td></tr>
<tr><td>T200</td><td>Default Image for 8k Main ROM</td><td>[[Media:RT2002.BR|RT2002.BR]]</td><td>AD06</td><td>[[User:Sadolph|Sadolph]] 04:02, 14 February 2011 (PST)</td></tr>
</table>

2010-05-28T04:10:42Z

99.6.119.22:

OPTROM Switching

2010-05-28T04:10:21Z

99.6.119.22:

== Overview ==

Some time was spent in developing an improved method to call main ROM from option ROM, and to handle interrupts from within the optrom. This code was developed by John Hogerhius and Steve Adolph, inspired by work done by Mo Budlong.

The goal was to
* use only the stack
* minimize code size
* reduce execution time

== Option ROM Code Template ==

<code><pre>

OPON: .EQU 0FAA4H

;-----------------------------------------------------------------------
; ROM start
;-----------------------------------------------------------------------
.org 0000h

RST0: di
JMP program ; standard entry
.DB 0,0,0,0
RST1: RET
.DB 0,0,0,0,0,0,0
RST2: RET ;Not used
.DB 0,0,0,0,0,0,0
RST3: RET ;Not Used
.DB 0,0,0,0,0,0,0
RST4: RET ;Not Used
.DB 0,0,0
TRAP: DI
CALL INTCALL
RST5: RET ;Not Used
.DB 0,0,0
RST55: DI
CALL INTCALL
RST6: JMP STDCALL ;RST 6 used as short call to a Standard ROM routine.
.DB 0
RST65: DI ;Replaces the 6.5 interrupt and sets up a call to 6.5 in Standard ROM
CALL INTCALL
RST7: RET ;Not Used
.DB 0,0,0
RST75: DI ;Replaces the 7.5 interrupt and sets up a call to 7.5 in Standard ROM
CALL INTCALL

.org 0040h

OPON_img: ; auto copied on power up
; 8 bytes
PUSH PSW ; temp store psw
mvi a,01h
OUT 0E8H
pop psw
ret

.db 00h

.org 0048h

;---------------------------------------------------------
;The STDCALL routine allows a program running in the
;the Option ROM to call and return to an address in the
;Option ROM.
;Syntax is to use a RST 6 plus the address to be called.
;
; RST 6
; rvect--> DW 04B44H (cvect)
; pvect-->
;
;---------------------------------------------------------

STDCALL: ; 23 bytes
; stack = rvect
xthl
inx h
inx h
xthl ; fix up first stack entry
; stack = pvect
; hl=hl'

push h
lxi h, OPON
xthl ; stack = pvect, OPON
; hl=hl'

push h
push d ; stack = pvect, OPON, hl', de'

ldsi 06h ; point de to stack location of return vector

lhlx ; hl=pvect
dcx h
dcx h ; point hl=pvect-2
xchg ; de=pvect-2
lhlx ; hl=cvect

pop d ; de=de'
xthl ; hl=hl', stack= pvect, OPON, cvect

jmp STDON

;---------------------------------------------------------
;Routine for the hardware traps.
;return address on entry is related to which interrupt occured.
;
; after interrupt occurs
; ivect DI
; call INTCALL
; rvect -->
; so stack = pvect, rvect
;---------------------------------------------------------

INTCALL: ; final stack must be opon, introutine
; interrupts are off
; enter with return location on stack, indicating int routine
; stack = pvect, rvect
; 20 bytes
push h
push d ; stack = pvect, rvect, hl', de'

ldsi 04h

lhlx ; hl= rvect

dcx h
dcx h
dcx h
dcx h ; hl = ivect

push h ; stack = pvect, rvect, hl', de', ivect

lxi h,OPON
shlx ; stack = pvect, OPON, hl', de', ivect

pop h ; hl=ivect
pop d ; de=de'

xthl ; stack = pvect, OPON, ivect
; hl=hl', de=de'

jmp STDON

;---------------------------------------------------------
;OPEXIT/STDON: Turns off the Option ROM (or turns on Standard ROM)
;---------------------------------------------------------
.org 0085h

STDON:
PUSH PSW
PUSH H ; 26C8, F1 C9 POP PSW, RET
LXI H,26C8H ; it returns to this location --> pop psw; ret
XTHL

OPEXIT: ; return to location pushed on stack
xra a
OUT 0E8H
RET ; RET can be found at 008EH in stdrom
; in both M100 and T200

EXIT:
.org 00094H
pop h
lxi h,0000h
xthl ; restart

jmp OPEXIT

</pre></code>

[[Media:demo.zip|Demo program for an option rom]]

Note that in some instances one might need to use the data stored in FF45 to preseve the state of thinks like the cassette relay. In that case, it is relatively simple to extend this to cover FF45 support properly.

[[Category:Model T Developer Reference]]

2009-11-09T21:04:00Z

99.6.119.22: /* INSIDE ''TextStar'' */

From: PORTABLE 100, March 1989, pgs 8–13.

<big>''Get ''WordStar'' cursor control for ''TEXT.</big>

'''By Stan Wong'''

'''Republication, bugfixes, and extensions by John R. Hogerhuis'''

I'm a WordStar addict. There is nothing flashy about the program. It's not even sexy. But I love ''WordStar'' and its arcane cursor movement and control commands. It was, and still is, one of the few word processing programs supported across many different machines and operating systems. I use it on a DEC Rainbow and a 386 PC at work. I use it on my IBM PC/XT. And I bought an NEC 8500 CP/M laptop because it had ''WordStar'' built in.

My fingers get cramps every time I use my trusty Model 100, and trying to remember the different cursor movement and editing commands drives me batty.

Well, no more!

== A Diamond in the Rough ==

The Model 100 TEXT program already implements the famous WordStar cursor control-character "diamond" – ''^S'', ''^E'', ''^D'', ''^X'', where the caret (^) signifies holding down the ''CTRL'' key, as ''WordStar'' users know – but it doesn't go far enough.

So I've polished up the diamond a bit. I've written a small machine language program called ''TextStar'' (or ''Text*'' to its friends), which implements most of the ''WordStar'' cursor movement commands as well as some text deletion and other miscellaneous commands.

''TextStar'' is not a complete program by itself. Instead, it enhances the operation of ''TEXT''. Although ''TextStar'''s cursor control looks and feels like ''WordStar'', it still retains a ''TEXT''-like flavor. See the sidebar "Inside ''TextStar''" for technical information on how it performs its magic.

''TextStar'' extends the operation of ''TEXT'' by redefining the meaning of the control keys, where possible, to match those of ''WordStar'' (See Table 1). Even multiple-keystroke commands such as ''^QD'', are supported. Control keys that have not been redefined still retain their ''TEXT'' meanings. For instance, ''^B'' still moves the cursor to the bottom of the screen. ''^T'' will not, however move you to the top of the screen but will delete a word instead.

A simple change to ''TextStar'' could have made it ignore the ''TEXT'' control keys, but I felt it would be better to leave them in. The program owes its small size (381 bytes) to its method; it traps keyboard input and translates only ''WordStar'' control codes into their ''TEXT'' equivalents, passing all other keystrokes directly to ''TEXT'' for normal processing.

== Vive La Difference ==

However, ''TextStar'' does not perform exactly like ''WordStar''. Because it enhances the ''TEXT'' program, it is bound by certain ''TEXT'' conventions.

For instance, when moving up and down a line, ''WordStar'' moves the cursor to the end of a line if the destination line is shorter. But ''TextStar'', like ''TEXT'', leaves the cursor in the same column regardless of the destination line's length.

As a bonus, the text deletion commands ''^T'' and ''^Y'' store the deleted text in the paste buffer. So if you make a mistake you can recover the text by pressing the ''PASTE'' key. This gives you a simple ''UNDO'' facility.

== A Star Is Born ==

Listing 1 is a relocating ''BASIC'' loader. It creates a machine language program, ''TXTSTR.CO'', to run anywhere you specify in high memory, or it will default to loading just under the current ''HIMEM''. It can thus coexist with your other ''.CO'' programs. (Thanks to Phil Wheeler for his ''BASBLD.PW3'' program, which I used to create the loader.)

Listing 2 is the assembly language source code for ''TextStar''. I used the ''ADSM'' assembler by James Yi, which you can find on the CompuServe Model 100 Forum. Minor syntax changes to the source code will also make it compatible with the ''ROM2'' assembler from Traveling Software, which I used to do the initial program development.

You have no need to use the assembly language listing, however, other than to understand what ''TextStar'' is doing and how it does it.

== A Rising Star ==

To run ''TextStar'', place the widebar cursor over ''TXTSTR.CO'' on the main menu and press ''ENTER''. You should then see ''TEXT'''s familiar ''File to edit?'' prompt. Specify the ''.DO'' file to edit, and you're on your way.

If the program doesn't start, go into BASIC and type ''CLEAR 0, nnnm'' (where ''nnnm'' is the load point) and then try again. If you don't know the load point, type ''LOADM "TXTSTR"'' and use the ''Top'' address returned by the ''LOADM'' command as the load point (''nnnm'') for the ''CLEAR'' statement above.

== Where To Get TextStar ==

''TextStar'' is also available on the ''P100-To-Go'' disk and on the ''Portable BBS'' (603-924-9770) as ''TXTSTR.100''. If you need the program and listings on a cassette tape, send $6 to me at P.O. Box 28181, Santa Ana, CA 92799. You can also contact me via CompuServe user ID 70346,1267. I support the program on the M100SIG of CompuServe.

Those cramps in my fingers are finally starting to disappear. Happy typing!

== INSIDE ''TextStar'' ==

The key to ''TextStar'''s operation is its ability to intercept keystrokes before ''TEXT'' sees them, by using a programming mechanism known as a ''RAM hook''. Before I describe how ''TextStar'' uses RAM hooks, let's take a look at what ''TEXT'' does with your keystrokes.

The ''TEXT'' program is constructed as one big loop starting at ROM address 5DEEH. ''TEXT' waits for your keystroke, gets it, and takes the appropriate action.

It's interesting to note that near the beginning of ''TEXT'', the program pushes the address of the top-of-the-''TEXT'' loop onto the stack.

Normal loops end with a ''JMP nnnn'' instruction, where ''nnnn'' is the address of the top of the loop. But by pushing the top-of-the-loop address on the stack, the program can instead simply execute a ''RET'' instruction from anywhere to get back to the start.

This has two advantages. First, it saves memory for each loop return point. It needs only one byte for the ''RET'' instruction versus three for the ''JMP''. Second, the code can be more easily relocated. If the code is, for some reason, changed and shifted in memory, then all the ''JMP'' instructions do not have to be recoded with the new top-of-the-loop address.

=== Give 'em the Hook, the Hook ===

''TEXT'' uses a ROM routine known as ''CHGET'' (located at 12CBH) to wait for your next keystroke. The ''TEXT'' call to this "Tandy-documented" routine is at address 63F1H.

''CHGET'' makes use of a RAM hook. What's a RAM hook? Is it related to Captain Hook? Not really.

A RAM hook is a programming mechanism by which the system designer provides a way for users to modify or replace certain system routines. RAM hooks are commonly provided for ROM routines, since code in ROM is fixed and cannot be changed.

Specifically, some ROM routines incorporate an ''RST 7'' instruction to give users access to hooks, allowing them an opportunity to "splice in" their own code instead. It works like this.

At address FADAH is a "hook table," each table entry being a two-byte address. In effect, the ''RST 7'' instruction in a ''CALL'' to one of these addresses. It finds the appropriate entry by adding an offset byte (which follows the ''RST 7'' instruction in the ROM routine) to the start of the table, and then ''CALL'''s the address stored there.

For example, the ''CHGET'' routine incorporates an ''RST 7'' instruction at the beginning of the routine. The value of the offset byte is 4. This means that the RAM hook at FADEH (FADAH + 4) is used for ''CHGET''.

Since most entries in the hook table point to a RET instruction in ROM (at 7FF3H), the ''RST 7'' normally ''CALL'''s 7FF3H, which simply returns back to the ROM routine, chewing up a few machine cycles and nothing more.

But since the hook table is in RAM, the user may change an entry to point to his own routine, in which case the ''RST 7'' performs a ''CALL'' to the user's routine.

Once ''RST 7'' locates the two-byte address in the table, it executes the routine located at that stored address. For routines like ''TextStar'' that use these hooks, ''RST 7'' effectively ''CALL'''s ''TextStar'', which does its business on a keystroke and then returns to ''CHGET''.

Thus, a hook gives us a chance to sneak in and peek at a keystroke before it is processed and returned to ''TEXT''.

=== Can You Direct Me To... ? ===

Okay, so now that we know what a RAM hook is, how do we use it? The first thing to do is save the original contents of the RAM hook at FADEH. Typically it is just a pointer to ''RET'' (address 7FF3H), but someone else might be using it, so we'll politely save it and restore it when we're done.

Next, we put the address of our own code (we'll use the address ''TS1'') into the hook. Now every time ''TEXT'' gets a keystroke, we get a peek at it first.

=== Relax and Unwind ===

Now that we can get a peek at a keystroke before ''TEXT'' does, what next?

Other programs use the ''CHGET'' routine too. So we have to make sure that ''CHGET'' was invoked by ''TEXT'' and not another program. ''TEXT'' calls ''CHGET'' at address 5FEDH. (Actually it's called at 63F1H, from within a routine called by 5FEDH.) This means that there will be a ''RET''urn to 5FF0H somewhere on the stack.

When we get control via the FADEH RAM hook, the return address to ''TEXT'', if it was called by ''TEXT'', is 10 levels (20 bytes) down in the stack.

So we have to unwind the stack 10 levels and see if the address 5FF0H is there. If it is, then ''CHGET'' was called from ''TEXT'' and this keystroke is for us. If not, then we must put everything back the way it was.

How can a kestroke in ''TEXT'' not be for us? There are functions within ''TEXT'', such as ''F1'' (''Find'') function, that require keyboard input separate form the main ''TEXT'' processing loop.

The stack unwinding code is liberally borrowed from the ''TXT-OV.ASM'' program by James Yi and Paul Globman. The code uses an undocumented 8085 instruction that subtracts BC from HL and stores the result in HL.

''HL ← HL - BC''

The mnemonic for this instruction is ''HLMBC'' in the ''ROM2'' assembler syntax and ''DSUB'' in the ''ADSM'' assembler. If defined instead as ''DB 8'', as in Listing 1, all assemblers will support it.

Sixteen-bit arithmetic on the 8085 is quite limited. This, and several other undocumented instructions, can save many instructions and make for easier programming.

=== What A Character! ===

At label ''WSTXT'', we examine the keystroke. If the character is a control character, then we have to look for "our"" control characters. Otherwise, we pass control to ROM location 6005H for control characters and location 608AH for "normal" characters and process the keystrokes as if we had never been there.

When we do find our control character, we simulate the commands that will implement the ''WordStar'' function. Look at the code for the ''^Y'' function (delete line) as an example.

Multiple keystroke sequences, such as ''^KD'', pose a more difficult problem. When a ''^K'' is typed, we can't act until we know what the next keystroke is. The solution is to set a flag indicating that the ''^K'' has been typed. On every kestroke we have to check the flag to see if a ^K is in effect.

On a ''^KD'' ( or ''F8'') exit command, we must restore RAM hooks to their original values and exit to the main menu by ''JMP''ing to location 5797H. Failure to do so may result in a machine that feels very cool to the touch (i.e., COLD START!).

(IN PROGRESS)

TextStar

2009-11-09T20:57:02Z

99.6.119.22: /* INSIDE ''TextStar'' */

From: PORTABLE 100, March 1989, pgs 8–13.

<big>''Get ''WordStar'' cursor control for ''TEXT.</big>

'''By Stan Wong'''

'''Republication, bugfixes, and extensions by John R. Hogerhuis'''

I'm a WordStar addict. There is nothing flashy about the program. It's not even sexy. But I love ''WordStar'' and its arcane cursor movement and control commands. It was, and still is, one of the few word processing programs supported across many different machines and operating systems. I use it on a DEC Rainbow and a 386 PC at work. I use it on my IBM PC/XT. And I bought an NEC 8500 CP/M laptop because it had ''WordStar'' built in.

My fingers get cramps every time I use my trusty Model 100, and trying to remember the different cursor movement and editing commands drives me batty.

Well, no more!

== A Diamond in the Rough ==

The Model 100 TEXT program already implements the famous WordStar cursor control-character "diamond" – ''^S'', ''^E'', ''^D'', ''^X'', where the caret (^) signifies holding down the ''CTRL'' key, as ''WordStar'' users know – but it doesn't go far enough.

So I've polished up the diamond a bit. I've written a small machine language program called ''TextStar'' (or ''Text*'' to its friends), which implements most of the ''WordStar'' cursor movement commands as well as some text deletion and other miscellaneous commands.

''TextStar'' is not a complete program by itself. Instead, it enhances the operation of ''TEXT''. Although ''TextStar'''s cursor control looks and feels like ''WordStar'', it still retains a ''TEXT''-like flavor. See the sidebar "Inside ''TextStar''" for technical information on how it performs its magic.

''TextStar'' extends the operation of ''TEXT'' by redefining the meaning of the control keys, where possible, to match those of ''WordStar'' (See Table 1). Even multiple-keystroke commands such as ''^QD'', are supported. Control keys that have not been redefined still retain their ''TEXT'' meanings. For instance, ''^B'' still moves the cursor to the bottom of the screen. ''^T'' will not, however move you to the top of the screen but will delete a word instead.

A simple change to ''TextStar'' could have made it ignore the ''TEXT'' control keys, but I felt it would be better to leave them in. The program owes its small size (381 bytes) to its method; it traps keyboard input and translates only ''WordStar'' control codes into their ''TEXT'' equivalents, passing all other keystrokes directly to ''TEXT'' for normal processing.

== Vive La Difference ==

However, ''TextStar'' does not perform exactly like ''WordStar''. Because it enhances the ''TEXT'' program, it is bound by certain ''TEXT'' conventions.

For instance, when moving up and down a line, ''WordStar'' moves the cursor to the end of a line if the destination line is shorter. But ''TextStar'', like ''TEXT'', leaves the cursor in the same column regardless of the destination line's length.

As a bonus, the text deletion commands ''^T'' and ''^Y'' store the deleted text in the paste buffer. So if you make a mistake you can recover the text by pressing the ''PASTE'' key. This gives you a simple ''UNDO'' facility.

== A Star Is Born ==

Listing 1 is a relocating ''BASIC'' loader. It creates a machine language program, ''TXTSTR.CO'', to run anywhere you specify in high memory, or it will default to loading just under the current ''HIMEM''. It can thus coexist with your other ''.CO'' programs. (Thanks to Phil Wheeler for his ''BASBLD.PW3'' program, which I used to create the loader.)

Listing 2 is the assembly language source code for ''TextStar''. I used the ''ADSM'' assembler by James Yi, which you can find on the CompuServe Model 100 Forum. Minor syntax changes to the source code will also make it compatible with the ''ROM2'' assembler from Traveling Software, which I used to do the initial program development.

You have no need to use the assembly language listing, however, other than to understand what ''TextStar'' is doing and how it does it.

== A Rising Star ==

To run ''TextStar'', place the widebar cursor over ''TXTSTR.CO'' on the main menu and press ''ENTER''. You should then see ''TEXT'''s familiar ''File to edit?'' prompt. Specify the ''.DO'' file to edit, and you're on your way.

If the program doesn't start, go into BASIC and type ''CLEAR 0, nnnm'' (where ''nnnm'' is the load point) and then try again. If you don't know the load point, type ''LOADM "TXTSTR"'' and use the ''Top'' address returned by the ''LOADM'' command as the load point (''nnnm'') for the ''CLEAR'' statement above.

== Where To Get TextStar ==

''TextStar'' is also available on the ''P100-To-Go'' disk and on the ''Portable BBS'' (603-924-9770) as ''TXTSTR.100''. If you need the program and listings on a cassette tape, send $6 to me at P.O. Box 28181, Santa Ana, CA 92799. You can also contact me via CompuServe user ID 70346,1267. I support the program on the M100SIG of CompuServe.

Those cramps in my fingers are finally starting to disappear. Happy typing!

== INSIDE ''TextStar'' ==

The key to ''TextStar'''s operation is its ability to intercept keystrokes before ''TEXT'' sees them, by using a programming mechanism known as a ''RAM hook''. Before I describe how ''TextStar'' uses RAM hooks, let's take a look at what ''TEXT'' does with your keystrokes.

The ''TEXT'' program is constructed as one big loop starting at ROM address 5DEEH. ''TEXT' waits for your keystroke, gets it, and takes the appropriate action.

It's interesting to note that near the beginning of ''TEXT'', the program pushes the address of the top-of-the-''TEXT'' loop onto the stack.

Normal loops end with a ''JMP nnnn'' instruction, where ''nnnn'' is the address of the top of the loop. But by pushing the top-of-the-loop address on the stack, the program can instead simply execute a ''RET'' instruction from anywhere to get back to the start.

This has two advantages. First, it saves memory for each loop return point. It needs only one byte for the ''RET'' instruction versus three for the ''JMP''. Second, the code can be more easily relocated. If the code is, for some reason, changed and shifted in memory, then all the ''JMP'' instructions do not have to be recoded with the new top-of-the-loop address.

=== Give 'em the Hook, the Hook ===

''TEXT'' uses a ROM routine known as ''CHGET'' (located at 12CBH) to wait for your next keystroke. The ''TEXT'' call to this "Tandy-documented" routine is at address 63F1H.

''CHGET'' makes use of a RAM hook. What's a RAM hook? Is it related to Captain Hook? Not really.

A RAM hook is a programming mechanism by which the system designer provides a way for users to modify or replace certain system routines. RAM hooks are commonly provided for ROM routines, since code in ROM is fixed and cannot be changed.

Specifically, some ROM routines incorporate an ''RST 7'' instruction to give users access to hooks, allowing them an opportunity to "splice in" their own code instead. It works like this.

At address FADAH is a "hook table," each table entry being a two-byte address. In effect, the ''RST 7'' instruction in a ''CALL'' to one of these addresses. It finds the appropriate entry by adding an offset byte (which follows the ''RST 7'' instruction in the ROM routine) to the start of the table, and then ''CALL'''s the address stored there.

For example, the ''CHGET'' routine incorporates an ''RST 7'' instruction at the beginning of the routine. The value of the offset byte is 4. This means that the RAM hook at FADEH (FADAH + 4) is used for ''CHGET''.

Since most entries in the hook table point to a RET instruction in ROM (at 7FF3H), the ''RST 7'' normally ''CALL'''s 7FF3H, which simply returns back to the ROM routine, chewing up a few machine cycles and nothing more.

But since the hook table is in RAM, the user may change an entry to point to his own routine, in which case the ''RST 7'' performs a ''CALL'' to the user's routine.

Once ''RST 7'' locates the two-byte address in the table, it executes the routine located at that stored address. For routines like ''TextStar'' that use these hooks, ''RST 7'' effectively ''CALL'''s ''TextStar'', which does its business on a keystroke and then returns to ''CHGET''.

Thus, a hook gives us a chance to sneak in and peek at a keystroke before it is processed and returned to ''TEXT''.

=== Can You Direct Me To... ? ===

Okay, so now that we know what a RAM hook is, how do we use it? The first thing to do is save the original contents of the RAM hook at FADEH. Typically it is just a pointer to ''RET'' (address 7FF3H), but someone else might be using it, so we'll politely save it and restore it when we're done.

Next, we put the address of our own code (we'll use the address ''TS1'') into the hook. Now every time ''TEXT'' gets a keystroke, we get a peek at it first.

=== Relax and Unwind ===

Now that we can get a peek at a keystroke before ''TEXT'' does, what next?

Other programs use the ''CHGET'' routine too. So we have to make sure that ''CHGET'' was invoked by ''TEXT'' and not another program. ''TEXT'' calls ''CHGET'' at address 5FEDH. (Actually it's called at 63F1H, from within a routine called by 5FEDH.) This means that there will be a ''RET''urn to 5FF0H somewhere on the stack.

When we get control via the FADEH RAM hook, the return address to ''TEXT'', if it was called by ''TEXT'', is 10 levels (20 bytes) down in the stack.

So we have to unwind the stack 10 levels and see if the address 5FF0H is there. If it is, then ''CHGET'' was called from ''TEXT'' and this keystroke is for us. If not, then we must put everything back the way it was.

How can a kestroke in ''TEXT'' not be for us? There are functions within ''TEXT'', such as ''F1'' (''Find'') function, that require keyboard input separate form the main ''TEXT'' processing loop.

The stack unwinding code is liberally borrowed from the ''TXT-OV.ASM'' program by James Yi and Paul Globman. The code uses an undocumented 8085 instruction that subtracts BC from HL and stores the result in HL.

''HL ← HL - BC''

(IN PROGRESS)

TextStar

2009-11-09T17:55:19Z

99.6.119.22:

TextStar

2009-11-09T17:37:52Z

99.6.119.22:

TextStar

2009-11-08T23:50:09Z

99.6.119.22:

From: PORTABLE 100, March 1989, pgs 8–13.

<big>''Get ''WordStar'' cursor control for ''TEXT.</big>

'''By Stan Wong'''

'''Repub and bugfixes, extensions by John R. Hogerhuis'''

I'm a WordStar addict. There is nothing flashy about the program. It's not even sexy. But I love ''WordStar'' and its arcane cursor movement and control commands. It was, and still is, one of the few word processing programs supported across many different machines and operating systems. I use it on a DEC Rainbow and a 386 PC at work. I use it on my IBM PC/XT. And I bought an NEC 8500 CP/M laptop because it had ''WordStar'' built in.

My fingers get cramps every time I use my trusty Model 100, and trying to remember the different cursor movement and editing commands drives me batty.

Well, no more!

== A Diamond in the Rough ==

The Model 100 TEXT program already implements the famous WordStar cursor control-character "diamond" – ''^S'', ''^E'', ''^D'', ''^X'', where the caret (^) signifies holding down the ''CTRL'' key, as ''WordStar'' users know – but it doesn't go far enough.

So I've polished up the diamond a bit. I've written a small machine language program called ''TextStar'' (or ''Text*'' to its friends), which implements most of the ''WordStar'' cursor movement commands as well as some text deletion and other miscellaneous commands.

''TextStar'' is not a complete program by itself. Instead, it enhances the operation of ''TEXT''. Although ''TextStar'''s cursor control looks and feels like ''WordStar'', it still retains a ''TEXT''-like flavor. See the sidebar "Inside ''TextStar''" for technical information on how it performs its magic.

''TextStar'' extends the operation of ''TEXT'' by redefining the meaning of the control keys, where possible, to match those of ''WordStar'' (See Table 1). Even multiple-keystroke commands such as ''^QD'', are supported. Control keys that have not been redefined still retain their ''TEXT'' meanings. For instance, ''^B'' still moves the cursor to the bottom of the screen. ''^T'' will not, however move you to the top of the screen but will delete a word instead.

A simple change to ''TextStar'' could have made it ignore the ''TEXT'' control keys, but I felt it would be better to leave them in. The program owes its small size (381 bytes) to its method; it traps keyboard input and translates only ''WordStar'' control codes into their ''TEXT'' equivalents, passing all other keystrokes directly to ''TEXT'' for normal processing.

== Vive La Difference ==

However, ''TextStar'' does not perform exactly like ''WordStar''. Because it enhances the ''TEXT'' program, it is bound by certain ''TEXT'' conventions.

For instance, when moving up and down a line, ''WordStar'' moves the cursor to the end of a line if the destination line is shorter. But ''TextStar'', like ''TEXT'', leaves the cursor in the same column regardless of the destination line's length.

As a bonus, the text deletion commands ''^T'' and ''^Y'' store the deleted text in the paste buffer. So if you make a mistake you can recover the text by pressing the ''PASTE'' key. This gives you a simple ''UNDO'' facility.

== A Star Is Born ==

Listing 1 is a relocating ''BASIC'' loader. It creates a machine language program, ''TXTSTR.CO'', to run anywhere you specify in high memory, or it will default to loading just under the current ''HIMEM''. It can thus coexist with your other ''.CO'' programs. (Thanks to Phil Wheeler for his ''BASBLD.PW3'' program, which I used to create the loader.)

Listing 2 is the assembly language source code for ''TextStar''. I used the ''ADSM'' assembler by James Yi, which you can find on the CompuServe Model 100 Forum. Minor syntax changes to the source code will also make it compatible with the ''ROM2'' assembler from Traveling Software, which I used to do the initial program development.

You have no need to use the assembly language listing, however, other than to understand what ''TextStar'' is doing and how it does it.

== A Rising Star ==

To run ''TextStar'', place the widebar cursor over ''TXTSTR.CO'' on the main menu and press ''ENTER''. You should then see ''TEXT'''s familiar ''File to edit?'' prompt. Specify the ''.DO'' file to edit, and you're on your way.

If the program doesn't start, go into BASIC and type ''CLEAR 0, nnnm'' (where ''nnnm'' is the load point) and then try again. If you don't know the load point, type ''LOADM "TXTSTR"'' and use the ''Top'' address returned by the ''LOADM'' command as the load point (''nnnm'') for the ''CLEAR'' statement above.

== Where To Get TextStar ==

''TextStar'' is also available on the ''P100-To-Go'' disk and on the ''Portable BBS'' (603-924-9770) as ''TXTSTR.100''. If you need the program and listings on a cassette tape, send $6 to me at P.O. Box 28181, Santa Ana, CA 92799. You can also contact me via CompuServe user ID 70346,1267. I support the program on the M100SIG of CompuServe.

Those cramps in my fingers are finally starting to disappear. Happy typing!

(IN PROGRESS)