TSE II: The Task Switching Enviroment (second edition)
Version 1.0
By Michael Vincent & Robin Kay
All rights reserved worldwide.

WEB: http://www.radicalsoft.org/tse
EMAIL: michael@radicalsoft.org
       dekiii@crosswinds.net
ICQ: 67435453 (Michael Vincent)

DISCLAMER
I or anybody else that has any connection with this program takes no responsibility for anything this program does or does not do. Any damages to you, your property or your TI-83+ programmable graphing calculator that are acquired by using this program are not mine or anyone else's fault or responsibility. This program is to be distributed as freeware, no money may be charged for this program including any form of distribution fee. I cannot guarantee the accuracy of any of the information in this document.

** INSTALLING TSE AND UTOPIA

Included this archive are the following programs:-
TSE.8XG      A       - Basic program used to start TSE
             LOADTSE - Loads the TSE kernel and start the shell
             TSEKRNL - TSE Kernel
             TSELIBS - TSE Libraries
UTOPIA.8XG   UTOPIA  - Utopia shell
             CHSHUT  - Configures Kernel to start Utopia
IONEMU.8XG   IONEMU  - ION Emulation Shell
             CHSHIE  - Configures Kernel to start IONEmu
HELLO.8XP    HELLO   - Sample Hello World program

        The following instructions are for installing TSE II and Utopia, if you wish to use another shell, consult its instructions. Also, TSE is only for the TI-83+, not 83.
        Send TSE.8XG and UTOPIA.8XG to your calculator with the link program of your choice. You may then delete CHSHUT as it not needed for normal operation. That is all you need to do to use TSE, however you may want to keep the kernel in the archive due to its size. To do this press [2nd] [+] [5] [PRGM] and then select TSEKRNL from the menu and press enter. You may repeat this process with TSELIBS, and if you archive both vars then you will reduce the amount of RAM used. When archived the contents of the these variables are streamed directly from Flash-ROM so you don't need to worry about wearing out the archive.
        If you already have ION installed then sending TSE will overwrite the prgmA that ION creates. You can rerun the ION install prgram to recreate ION's prgmA, but either way you'll a problem starting ION or TSE. You can run ION manually with Asm(prgm0ION (The 0 is actually supposed to be theta but that isn't in the ASCII charset), or TSE with Asm(prgmLOADTSE. Probably the best thing to do would be to write a menu program in BASIC so you can choose whether to load ION or TSE.

** INSTALLING AND USING IONEMU (ION Emulation Shell)

        You can run some of your old ION programs with IONEMU, the ION Emulation Shell. IONEMU is an alternative to Utopia, so you don't need Utopia on your calculator if you're using IONEMU. To install IONEMU, first send the IONEMU.8XG group file to your caculator. Then you need to run the kernel configuration program, to do this enter Asm(prgmCHSHIE at the prompt and press enter. Note that TSEKRNL must be unarchived for this to work. Once you have configured the kernel you may delete CHSHIE as it is no longer needed. IONEmu operates almost exactly like Utopia except that you can also run ION programs. Note that you cannot multi-task ION programs. The ION emulator has not yet been perfected however, and some programs may cause problems. Below is a list of imperfections in the emulation:

1) You need more free RAM than the program's size
2) Programs will cause serious problems if they use saferam2

             
** USING UTOPIA (TSE II Menu Shell)

        Utopia is the default user interface for TSE II. It resembles the Ion shell in appearance, but is much improved.

Up/Down    - Scroll through the menu
Left/Right - Change screens if more than 8 programs
2nd/Enter  - Start or Resume a program
Alpha      - End a program
X,T,0,n    - Archive or Unarchive a program
On         - Power down the calculator
Mode       - Quit Utopia
Prgm       - Display program toolbar (see utopia.txt)

	From within a program you should be able to press the Stat key at any point during its execution to switch back to the shell.

** USING CHSHUT (CHange SHell UTopia)

	This prgram is used to configure the kernel to start Utopia if it has been previously configured to start another shell. Simply type Asm(prgmCHSHUT and press enter. Note that TSEKRNL must be unarchived for this to work.

Frequently Asked Questions (FAQ)

Q: After running a program a star (Asterisk) apears before its name in Utopia, what does this mean?
A: It just means that the program is running and its state is being preserved, if you don't want to be able to resume it later then press [Alpha] to end task.

Q: Why does <A> apear in front of a programs name in Utopia?
A: The program is archived. If you run it, it will be unarchived and ran. However, Utopia doesn't automatically rearchive it after it has ended task. You can manually archive/unarchive programs by pressing the X,T,0,n (graphvar) key.

Q: Why does TSE II quit when I try to archive or unarchive a program?
A: If RAM is full when you unarchive, or Flash-ROM is full when you archive then TI-OS throws a memory error, but Utopia traps it. Try freeing up some RAM, or Flash-ROM if you've actually filled it!

Q1: Why does nothing happen when I try to start TSE II?
Q2: Why does nothing happen when I try to start a program?
A: Check to see how much free memory you have, you may not have enough free memory to allocate the program's or Utopia's task-block. Try deleting or archiving some variables, or ending the tasks of some other programs.

Q: Why won't TSE II switch tasks?
A: This can manifest itself within Utopia, you see a star appear by a program but the program won't start. Or worse, within a program and you can't switch back to Utopia. This is also caused by low memory, when TSE II has enough memory to create the task block but no enough memory to switch tasks (the task switcher requires 256 bytes of RAM to use as a buffer). If this happens while a program is running, then your only solution is to remove the batteries, but fortunately this can only happen if the program is allocating memory and this isn't very common.

Q: Why does TSE II crash?
A: I don't know! If this happens while you are starting, resuming, exiting, or running a third party program then you should contact the author of the program first to see it's a bug in that. However, I'm still very open to the possiblity that TSE II or Utopia have bugs in them. If you think it's a bug in TSE II then e-mail me at michael@radicalsoft.org with the exact details of what caused the crash. You can also e-mail dekiii@crosswinds.net.

** HISTORY OF TSE (and TSE II)

prv0 Internal Release
     No functionality
     Integrated UI

prv1 Internal Release
     UI seperated from kernal
     Crashed if program in RAM page 1

prv2 Internal Release
     Now uses swapping instead of relocation
     Much more stable

v1.0 First public release!
     Much more stable

v1.1 Kernel error handler removed
     Pressing ON no longer causes error on exit
     Power down within MShell now supported

v1.2 Partial ION emulation added
     _tseGetPixel was not working correctly

v1.3 ION emulation improved
     IONEmu Shell added
     MShell made smaller

v1.4
     MShell replaced with Utopia
     Password protection added
     Interrupt speed changing added
     Archived programs can now be run without unarchiving first
     Teacher-friendly homescreen upon exit
     Better ION emulation

v1.4a
     Minor bug fix

v1.5
     Ion emulation now supports external levels
     Ion emulation shell UI improved
v1.6
     IONEmu shell UI improved
     Utopia made smaller

prv3 Internal Release (equivalent to TSE v1.7)
     Major optimizations for size
     Password protection in Utopia removed
     Turbo feature removed

TSE II v1.0
     TSE changed to TSE II; version numbers restarted
     More optimizations (size, speed)
     Program hiding added
     Program display order changing added
     IONEmu bug fix

** CREDITS

Joe Wingbermuehle - For generously allowing Robin Kay to use code from ZLIB and ZGFXL.
Robin Kay - For allowing me to take over working on TSE after he quit. Also, for initially creating TSE.
Dan Englender - Pointed out one instance of an unoptimized line of code in TSE which caused me to optimize the whole shell so he couldn't find anymore unoptimized spots. :) Also, for providing me with a VAT entry swapping routine.
Scott Dial - For writing the routine which Dan E. sent me