TI-86 Program Variables 12-8-1999 Cassady Roop croop@oregontrail.net This file contains useful information on TI86 program variable format and program types with examples. Although this information is already available from several sources across the internet, I have found it to be spread out instead of being in a nice, compact, program variable-specific bundle of information; I hope to help solve that problem... CONTENTS -------- 1.0 Program Variable Format 2.0 Program Types .1 BASIC programs .2 Edit-Locked BASIC programs .3 Uncompiled Assembly (ASMprgm) programs .4 Compiled Assembly (ASM) programs .5 Program-type Tokens List 3.0 Assembly Program Shell Info 4.0 VAT entries In this document, I list several examples. To make these examples easier to understand, I include both byte-string and interpreted versions of example programs. These programs are all short, but should illustrate the point I'm trying to make. The byte-string examples are the actual program as it resides in memory. The interpreted examples show what the byte-string means: byte-string: 05 00 48 45 4C 4C 4F interpreted: [0005]"HELLO" The interpreted examples convey information using the following conventions: [xxxx] represents a 16-bit program length "xxxx" represents a string of ASCII characters or represents a one- or two- byte token {xxx} represents an assembly instruction 1.0 Program Variable Format --------------------------- Programs and strings share the same file format, so what works with a program will likewise work with a string. The first two bytes of the variable are the length header, stored with the least-significant byte first. Immediately after that comes the variable data. The length header represents the length of the data only, it does not include itself. This string would be five bytes long, and hold the text "HELLO": 05 00 48 45 4C 4C 4F [0005]"HELLO" | | | | | | | [0005] H E L L O <---data----> Due to the limiting factor of a 16-bit length header, the maximum possible program length is $FFFF, or 65535 bytes, regardless of what Texas Instruments says about 'unlimited program size.' Assembly programs are further limited by the size of the memory area that is used to execute assembly code, which is about 8 kilobytes. Programs much larger than this must be subdivided into separate program modules. 2.0 Program Types ----------------- There are three primary kinds of programs: TI-BASIC programs, which you create and edit through the Program Editor; compiled assembly (ASM) programs, which you create and compile on a computer, and then send to the calculator; and uncompiled assembly (ASMprgm) programs, which are run as assembly programs but are edited in ASCII format through the program editor. The program type can be determined by examining the first two data bytes of the program variable: 03 00 8E 28 C9 [0003]<8E 28>{ret} The above program is three bytes long, as shown in the length bytes <03 00>. Keep in mind that the length bytes are stored 'backwards.' The first two data bytes are <8E 28>. These two bytes tell the calculator what kind of program this is, but their positions are not reserved for that purpose alone. The first two bytes are only 'type bytes' if they are certain representative values, or tokens, that mean a certain thing when interpreted by the calculator. Otherwise they are normal program data for a BASIC program. Each type has its own rules, so I will cover each of them separately... 2.1 BASIC Programs ------------------ BASIC programs are the 'normal' or 'default' programs on a TI-86. If the first data bytes are not specific values that identify the program as some other type, then it is a BASIC program. BASIC programs exist in two forms: plain text and tokenized. Plain text programs contain the text you see when you edit the program in the program editor. Tokenized programs are programs that have been converted to a kind of 'shorthand' by the calculator, consisting of one- or two-byte tokens that represent all the available commands on the calculator. Tokenized programs are more compact than plain text programs, and every time you run a plain text program that has just been edited, the calc tokenizes it. Tokenized and untokenized BASIC programs have different formats. If the program is tokenized, then the first couple data bytes are just program data. A program is a tokenized BASIC program if the first two data bytes are not any one of the other program-type tokens <8E 29>, <8E 28>, <8E 27>, <00 xx>, or <00 00>. An untokenized BASIC program starts with the token <00 xx>, which is one byte long, because xx means the next byte can be anything. This next byte is the start of program text. A tokenized BASIC program (E2 = PAUSE, E3 = STOP, in case you wondered): 02 00 E2 E3 [0002] Untokenized BASIC program: 05 00 00 53 54 4F 4E [0005]<00 xx>"STOP" 2.2 Edit-Locked BASIC Programs ------------------------------ Another kind of BASIC program is the edit-locked program. These programs cannot be edited in the program editor once locked. They are identified by a <00 00> token if they are plain-text, and a <8E 29> if they are tokenized. An untokenized BASIC program that is edit-locked: 06 00 00 00 53 54 4F 4E [0006]<00 00>"STOP" A tokenized BASIC program that is edit-locked: 04 00 8E 29 E2 E3 [0004]<8E 29> 2.3 Uncompiled Assembly Programs -------------------------------- Often called 'ASMprgm' programs because to write them on the calc, the first command must be ASMprgm. These are ASCII text files that the calculator interprets as assembly code in hexadecimal. Before they are run the first time and tokenized, these programs are indistinguishable from plain-text BASIC programs in that they start with <00 xx>. Once they have been run once, the calc should change it so it starts with <8E 27>. Tokenized uncompiled assembly (ASMprgm) program: 04 00 8E 27 43 39 [0004]<8E 27>"C9" 2.4 Compiled Assembly Programs ------------------------------ These are programs compiled on a computer and sent to the calc. They are uneditable. Assembly programs don't have tokenized and untokenized variants because the calculator doesn't interpret them like it does BASIC programs, it runs them directly. Assembly programs give total control of the calc to the programmer. They start with the token <8E 28>. Compiled assembly program: 06 00 8E 28 CD 01 41 C9 [0006]<8E 28>{call $4101}{ret} 2.5 Tokens Denoting Program Type -------------------------------- 00xx Untokenized BASIC (plaintext) 0000 Edit-locked Untokenized BASIC 8E29 Edit-locked Tokenized BASIC 8E28 Compiled Assembly 8E27 Uncompiled Assembly 3.0 Shell Info for Assembly Programs ------------------------------------ Many shells display not only the variable name of a program, but also a longer name or description that is stored in the program. This information is displayed only if the program follows a certain format at the beginning of its code. The following is the standard shell-info format supported by several shells and added as a template to programs generated by Assembly Studio 86. The assembly program should start like this: ------------- nop jp ProgStart .dw 0 .dw ShellTitle ShellTitle: .db "New Assembly Program",0 ProgStart: ...program code begins here... ------------- Replace the text at ShellTitle with the name or description of your program. This will be displayed by compatible shells when your program is selected. Your program code comes after ProgStart. The NOP instruction at the very beginning identifies your program as a shell-info compliant program when the shell inspects the variable. When run, the NOP has no effect, and the JP ProgStart jumps directly to your code. 4.0 VAT Entries --------------- Variables are kept track of in a table called the Variable Allocation Table, or VAT. The VAT is analogous to the File Allocation Table (FAT) on a computer. It stores the name and address of every variable on the calc. Although a variable's data could exist in memory, if its VAT entry were destroyed, it would be effectively deleted, because it would be 'lost'. Without a record of its existence, TI-OS would overwrite it with other data. This makes it rather important to not screw up the VAT. A good, safe rule is to not make any writes to the VAT, although it is ok if you know exactly what you are doing. ROM calls should always be used for changing the variable structure on the calc, never try to do it yourself through the VAT! You can read from the VAT to get information on a variable's type and location. Find the VAT entry either with a custom search routine, or use _findsym, which loads the VAT RAM page and points the HL register to the VAT entry. The VAT extends downward through memory, so entries appear to be backwards. Here is the format: Item Length Description Type 1 Code that identifies the variable's type. Programs are $12. Location 3 Absolute address of variable data. Flag byte? 1 A byte that is apparently unused. Some shells use it to store folder info. Name length 1 Length of variable name. Value = 0