TSE: The Task Switching Enviroment
Version 1.5
By Michael Vincent & Robin Kay
All rights reserved worldwide.

WEB: http://radical.calc.org/tse.htm
     http://tse83p.cjb.net (old)
EMAIL: michael@calc.org
       dekiii@crosswinds.net
ICQ: 67435453 (Michael Vincent)
AIM: Top Of The Shoe (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 prgram 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 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 becuase of its size, you may want to consider keeping the kernel in the archive. 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 pgrmA that ION creates. You can rerun the ION install prgram to recreate ION's pgrmA, but either way you'll a problem starting ION or TSE. You can run ION manually with Asm(pgrm0ION (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(CHSHIE 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 execept 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 write to saferam2
             
** USING UTOPIA (TSE Menu Shell)

        Utopia is the default user interface for TSE. 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        - Start or Resume a program
Enter      - Start or Resume a program
Alpha      - End a program
X,T,0,n    - Archive or Unarchive a program
Clear      - Power down the calculator
Apps       - Lockdown the calculator (pass. prot. , see utopia.txt)
Prgm       - Change password (see utopia.txt)
Mode       - Quit Utopia
Y=,WINDOW,ZOOM,TRACE - Change calculator speed (see utopia.txt)

        From within a program you should be able to press the Stat key at any point during it's 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(pgrmCHSHUT 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 progams 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 key.

Q: Why does TSE 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 managed to fill it!

Q1: Why does nothing happen when I try to start TSE?
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 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 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 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 or Utopia have bugs in them. If you think it's a bug in TSE then email me at michael@calc.org with the exact details of what caused the crash. You can also e-mail dekiii@crosswinds.net.

Q: I sent TSE to my friend's calculator from mine, why can't he/she change his/her password?
A: The password is stored in TSE, therefore if you have TSE on your calculator and a password set, that password is transferred to your friend's calculator along with TSE.

** HISTORY

prv0 Internal Release
     No functionality
     Intergrated 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
     Not yet released, will have improved IONEMU UI

** CREDITS

Joe Wingbermuehle - For generously allowing Robin Kay to use code from ZLIB and ZGFXL. Also, for allowing me to include his excellent ionDetect routine in TSE.
Robin Kay - For allowing me to take over working on TSE after he quit.
Whoever invented the Z80 cpu - without it I wouldn't have a life. :-)