DAY 19. User Variables


novice intermediate advanced expert

User variables are all those variables that you can create and delete. There are the real/complex variables A-Z, θ; lists, matrices, programs, etc.

Variable Names

Each variable has its own unique name. Variable names are built to be stored in the OP registers, so they can be at most nine bytes long. While each variable type has its own naming conventions, the general form is this:

OP1 +1 +2 +3 +4 +5 +6 +7 +8
TYPE Variable name
TYPE is a number specifying the object type. Each variable type has a unique number. Object types not listed are undefined or for internal useage only.

Value Equate Variable Type
$00 RealObj Real number
$01 ListObj List
$02 MatObj Matrix
$03 EquObj Equation
$04 StrngObj String
$05 ProgObj Program
$06 ProtProgObj Protected program
(Hidden from EDIT menu)
$07 PictObj Picture
$08 GDBObj Graph Database
$0B NewEquObj New Equation
$0C CplxObj Complex number
$0D CListObj Complex list
$15 AppVarObj AppVar
$16 TempProgObj Temporary program
The rest is the name, spelled with tokens.

Tokens

A token is a code that represents system commands, variables, etc. We use tokens to save space. For example, the command Disp is four letters and a space. This would normally be five bytes if stored as individual characters. By using a token, we save four bytes (which is a lot on a 64K machine). There are way too many tokens to list here; you can find them in the TI83PLUS.INC file (hint: they all begin with 't').

Two-Byte Tokens

There is no way in hell we could assign a one-byte token to every single command, so some tokens are defined with two bytes. Their format is token_class, token. The token class is the type of token wanted.

Token Value Class
tVarStrng String variables
tVarMat Matrix variables
tVarLst List variables
tVarEqu Equation variables
tVarPict Picture variables
tVarGDB Graph database variables
tVarOut Output-only variables
tVarSys System IO variables
t2ByteTok Extra general tokens
Anyway, the .INC file has all the token descriptions with ample comments. Just search for "2nd byte of".

Variable Name Formats

Real/Complex Numbers

Spelled with object type (RealObj or CplxObj) followed by one token (tA to tZ and tTheta), and two nulls.

OP1 +1 +2 +3 +4 +5 +6 +7 +8
RealObj tX t00 $00 ?? ?? ?? ?? ?? Real variable X
CplxObj tTheta $00 $00 ?? ?? ?? ?? ?? Complex variable θ

Lists

Spelled with object type (ListObj or CListObj), followed by token tVarLst, and either:
OP1 +1 +2 +3 +4 +5 +6 +7 +8
RealObj tVarLst tL1 $00 ?? ?? ?? ?? ?? List L1
CListObj tVarLst tD tI tS tT $00 ?? ?? Complex list LDIST

Matrices, Pictures, Strings

Spelled with appropriate object type (MatObj, PictObj, StrngObj), followed by corresponding token tVarMat, tVarPict, or tVarStrng, appropriate name token (tMatA to tMatJ, tPic0 to tPic9, tStr0 to tStr9), and a null.

OP1 +1 +2 +3 +4 +5 +6 +7 +8
MatObj tVarMat tMatC $00 ?? ?? ?? ?? ?? Matrix [C]
PictObj tVarPict tPic5 $00 ?? ?? ?? ?? ?? Picture Pic5
StrngObj tVarStrng tStr1 $00 ?? ?? ?? ?? ?? String Str1

Equation

An object type of EquObj or NewEquObj (no, I can't tell you the difference). Followed by token tVarEqu, one of the equation variable names from the below table, and a null.

tY0 to tY9 Function equations Y0 to Y9
tX1T to tX6T Parametric equations X1T to X6T
tY1T to tY6T Parametric equations Y1T to Y6T
tR1 to tR6 Polar equations r1 to r6
tun Sequence u(n)
tvn Sequence v(n)
twn Sequence w(n)

OP1 +1 +2 +3 +4 +5 +6 +7 +8
EquObj tVarEqu tY1 $00 ?? ?? ?? ?? ?? Equation Y1

Programs/AppVars

Spelled with object type (tProgObj, tProtProgObj, or tAppVarObj), followed by up to eight tokens. If less than eight, then followed by a null.

OP1 +1 +2 +3 +4 +5 +6 +7 +8
ProgObj tP tR tO tG tR tA tM t1 Program PROGRAM1
ProtProgObj tN tO tE tD tI tT $00 ?? Protected program NOEDIT
AppVarObj tL tA tS tT tU tS tE tR AppVar LASTUSER

Creating Variables

Now we'll actually create variables. There are some rules to follow to prevent problems. To check if a variable exists
_FindSym Finds variables that aren't programs, AppVars, or groups.
INPUT OP1 Variable name. Not necessary to have the object type set.
OUTPUT F Carry set if not found, reset if exists.
A Object type. Bits 5-7 are basically garbage, so if you want to use it, do AND $1F.
B Archive status. 0 if in RAM
DE Address of first byte of data
HL Address of symbol table entry
DESTROYS If variable is found, then C. If variable is not found, then All.

_ChkFindSym Finds any variable.
INPUT OP1 Variable name.
OUTPUT See _FindSym

To delete a variable
_DelVar Deletes a variable if it's in RAM.
INPUT HL Pointer to start of symbol table entry.
DE Pointer to start of variable's data storage.
B 0 if variable resides in RAM. Otherwise the Flash ROM page it is archived on.
DESTROYS All
Remarks System error if the variable is archived. Use _DelVarArc to delete any variable. Notice that the inputs to this routine are the same as the outputs of _FindSym.

The routines to create variables are
Routine Variable Input HL
_CreateCList Complex list Number of elements (<1000)
_CreateCplx Complex number None
_CreateEqu Equation Number of bytes
_CreatePict Picture None
_CreateProg Program Number of bytes
_CreateProtProg Protected program Number of bytes
_CreateReal Real Number None
_CreateRList Real list Number of elements (<1000)
_CreateRMat Matrix H = rows (<100)
L = columns (<100)
_CreateStrng String Number of bytes

For these routines, HL is the dimensions of the variable (see the table) and OP1 holds the variable name. They output HL as a pointer to the VAT entry (more info later), DE as a pointer to the data, and OP4 holding a copy of the name.

When creating a parametric equation, you have to create both X and Y parts or you'll get a crash.

Initializing Variables

Variables must be initialized before the program ends or a freeze is very likely. Each variable has a different structure for its data.

Real

9 bytes in FP-number format.
$00 $80 $31 $41 $59 $26 $53 $57 $00
3.14159265357

Complex

18 bytes in complex FP-number format.
$0C $83 $52 $18 $86 $00 $00 $00 $00
$8C $7F $18 $21 $00 $00 $00 $00 $00
5219.86 - 0.1821i

List

Two bytes with the number of elements. Followed by n × 9 bytes, where n is the number of elements. Each element is an FP-number.
$03 $00
$80 $82 $23 $45 $00 $00 $00 $00 $00
$00 $7E $10 $00 $57 $12 $00 $00 $00
$00 $80 $50 $00 $00 $00 $00 $00 $00
{-234.5, 0.01005712, 5}

Complex List

Two bytes with the number of elements. Followed by 18 × n bytes, where n is the number of elements. Each element is a complex FP-number.
$02 $00
$0C $80 $10 $00 $00 $00 $00 $00 $00
$0C $80 $20 $00 $00 $00 $00 $00 $00
$8C $80 $40 $00 $00 $00 $00 $00 $00
$0C $80 $80 $00 $00 $00 $00 $00 $00
{1+2i, -4+8i}

Matrix

One byte with the number of columns, one byte with the number of rows. Followed by r × c × 9 bytes, each of which is a real FP-number. Matrices are organized in row-major order.
$03 $02
$00 $81 $14 $95 $72 $75 $75 $00 $00
$80 $82 $83 $67 $57 $54 $74 $00 $00
$80 $81 $33 $57 $61 $43 $96 $00 $00
$00 $80 $48 $48 $78 $16 $76 $24 $00
$80 $81 $85 $56 $56 $72 $78 $00 $00
$00 $80 $86 $56 $01 $97 $47 $00 $00
[ [14.95727575, -836.7575474, -33.57614396]
  [4.878167624, -85.56567278, 8.656019747 ] ]

Picture

Two bytes with the number of bytes, which is a complete waste of RAM since it's always $02F4. Followed by a 96×63 bitmap (the bottom row of pixels is not recorded) — 12 bytes to one row of pixels. The format of a picture variable is explained on Day 24.

If you think for one second that I'm gonna give a full example, then you've just gotta be high.

Equation, Program, AppVar, String

Two bytes with the number of bytes. Followed by a bunch of tokens or a mass of arbitrary data.
$09 $00
tC tA tS tI tO tSpace tS tU tX
Probably string "CASIO SUX"


This is part of Learn TI-83 Plus Assembly In 28 Days
Copyright (c) 2002, 2003, 2004 Sean McLaughlin
See the file gfdl.html for copying conditions