Day 19

User Variables

Difficulty:
novice · intermediate · advanced · expert


· Previous · Lesson Index · Next ·

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
ListObj 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

_CreateCList

Complex list

INPUT
HL
Number of elements (<1000)
_CreateCplx

Complex number

INPUT
None
_CreateEqu

Equation

INPUT
HL
Number of bytes
_CreatePict

Picture

INPUT
None
_CreateProg

Program

INPUT
HL
Number of bytes
_CreateProtProg

Protected program

INPUT
HL
Number of bytes
_CreateReal

Real Number

INPUT
None
_CreateRList

Real list

INPUT
HL
Number of elements (<1000)
_CreateRMat

Matrix

INPUT
HL
H = rows (<100)
L = columns (<100)
_CreateStrng

String

INPUT
HL
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.

3.14159265357
|------|------|------|------|------|------|------|------|------| | $00 | $80 | $31 | $41 | $59 | $26 | $53 | $57 | $00 |

Complex

18 bytes in complex FP-number format.

5219.86 - 0.1821i
|------|------|------|------|------|------|------|------|------| | $0C | $83 | $52 | $18 | $86 | $00 | $00 | $00 | $00 | | $8C | $7F | $18 | $21 | $00 | $00 | $00 | $00 | $00 |

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.

{-234.5, 0.01005712, 5}
$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

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.

{1+2i, -4+8i}
$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

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.

[ [14.95727575, -836.7575474, -33.57614396]
[4.878167624, -85.56567278, 8.656019747 ] ]
$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

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.

String "CASIO SUX"
$09 $00
tC tA tS tI tO tSpace tS tU tX