TI-92 Link Protocol Guide - Variable formats

##

Variable Formats

A TI-92 variable has two parts: a header and a data section. While the header may be different, the format of the data section never changes whether the variable is in a file, in a transfer packet, or in the calculator's memory. This section describes the format of the data section for most types of variables. The format for the header is described in the packet format and the file format section.

Often certain variable types such as functions or lists are included in other larger variables. When such nesting occurs, it will be noted by referencing the type of subvariable rather than expanding its components. For example, a list contained in a GDB will be referenced as a list, not as the individual fields that make up a list.

Important note: All 2- and 4-byte values in this section are big-endian (MSB first) unless specified otherwise.

#### Variable Types

There are several types of variables that the TI-92 uses.

Expressions are basic algebraic expressions like the ones entered on the home screen.
Lists are sequences of real or complex numbers used in statistical calculations.
Matrices are two-dimensional matrices with real or complex components.
Data variables are spreadsheets containing values in some cells.
Text variables are files of readable text.
Strings are sequences of text characters.
Graphics Databases (GDB's) are stored sets of graphing functions.
Figures are objects created in the geometry application.
Pictures are stored bitmaps of the graph screen.
Programs are sequences of commands.
Functions are sequences of commands that evaluate based on the values of one or more variables.
Macros are stored command sequences for the geometry application.

#### Expressions

TI-92 expressions are tokenized and in Reverse Polish Notation (RPN). In RPN, each operand and each operator is a "symbol," which can be pushed onto a first-in-first-out (FIFO) "stack." A stack is a data structure that works like a stack of trays: new trays can be pushed onto the stack at any time, and trays on the stack can be popped off at any time, but they always come off in the reverse order than that in which they were pushed.

Operations are read from left to right. Whenever an operand is encountered, it is pushed onto the stack. Whenever an operator is encountered, it pops one or more operands off of the stack, uses them to compute the result, then pushes the result back onto the stack. The final value is the only operand left in the stack after all operations are complete. With this method, storing parenthesis is unnecessary because there are never any ambiguities as to the order of evaluation.

Click here for a list of tokens.

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this expression minus two for this field.
2 | n bytes | Expression operands and operators, tokenized and in RPN.

Example - expression (a+b)*c:
`00 05 0B 0C 8B 0D 8F
a b + c *`

#### Lists

A list is represented as an expression beginning with token E5h and ending with token D9h. The format of a list can be simplified as follows:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this list minus two for this field
2 | 1 byte | This byte always contains E5h.
3 | n bytes | Element values, one by one, last to first. Each element value is a NUMBER (a group of tokens, in Reverse Polish Notation, representing a single value).
3+n | 1 byte | This byte always contains D9h.

#### Matrices

A matrix is represented as a list of row lists. The format can be simplified as follows:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this list minus two for this field
1 | 1 byte | This byte always contains E5h.
3 | n bytes | Rows, one by one, last to first. Each row is a List without the first two bytes.
3+n | 1 byte | This byte always contains D9h.

#### Data variables

Data variables consist of a number of lists, functions and strings. They have the following format:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this data variable minus two for this field
2 | 1 byte | The number of rows in the longest column
3 | 1 byte | The number of columns
4 | n bytes | Column definitions, one by one, first to last. See format below.
4+n | 1 byte | The number of column calculations
5+n | m bytes | Column calculation definitions, one by one, first to last. See format below.
5+n+m | 1 byte | The number of column titles
6+n+m | x bytes | Column calculation definitions, one by one, first to last. See format below.
6+n+m+x | 1 byte | This byte always contains DDh.

Each column definition follows this format:

Offset | Length | Description
--- | --- | ---
0 | 1 byte | The column number (1-based)
1 | y bytes | A List representing the column

Each column calculation definition follows this format:

Offset | Length | Description
--- | --- | ---
0 | 1 byte | The column number (1-based)
1 | y bytes | An Expression representing the calculation function

Each column title definition follows this format:

Offset | Length | Description
--- | --- | ---
0 | 1 byte | The column number (1-based)
1 | y bytes | A String representing the column title

#### Text variables

Text variables have the following format:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this text variable minus two for this field
2 | 2 bytes | Offset, in characters, to the cursor position.
4 | n bytes | Text lines (see format below)
4+n | 1 byte | This byte always has a value of E0h.

Each line of text has this format:

Offset | Length | Description
--- | --- | ---
0 | 1 byte | Line type: 0Ch=page break, 20h=normal, 43h=Command, 50h=PrintObj
1 | m bytes | Characters, first to last. The string is not zero-terminated.
1+m | 1 byte | Line delimiter: 0Dh=line break, 00h=end of file

#### Strings

Strings are represented as follows:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this string minus two for this field
2 | 1 byte | This byte always has a value of 0.
3 | n bytes | Characters, first to last. The string is zero-terminated.
3+n | 1 byte | This byte always has a value of 2Dh.

#### Graphics Databases (GDB's)

GDB's for each graphing mode are different, but they all consist of a window setup portion and a function library portion.

All GDB have the following overall format:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this GDB minus two for this field.
2 | 1 byte | Number of graphs (1 or 2)
3 | 1 byte | Angle mode: 01h=Radians, 02h=Degrees
4 | 1 byte | Complex number mode: 01=Real, 02=Rectangular, 03=Polar
5 | 1 byte | Graph mode: 01h=Function, 02h=Polar, 03h=Parametric, 04h=Sequence, 05h=3D
6 | 1 byte | Active graph number (0 or 1) - Not present when #graphs=1
7 | 1 byte | Graph 2 mode (same possible values as offset 3) - Not present when #graphs=1
8 | 1 byte | Split Screen mode: 01h=Full, 02h=Top/Bottom, 03h=Left/Right - Not present when #graphs=1
9 | 1 byte | Split Screen ratio: 01h=1:1, 02h=1:2, 03h=2:1 - Not present when #graphs=1
6 or 10 (Ah) | n bytes | One or two graphs back to back (see various graph formats below).
6+n or 10 (Ah)+n | 1 byte | This byte always contains DEh.

Note: When two graphs of the same graph mode are included in one GDB, the second graph does not contain any function definitions.

A function-mode graph has this format:

Offset | Length | Description
--- | --- | ---
0 | 10 bytes | A REAL: xmin (see REAL format, below)
10 (Ah) | 10 bytes | A REAL: xmax
20 (14h) | 10 bytes | A REAL: xscl
30 (1Eh) | 10 bytes | A REAL: ymin
40 (28h) | 10 bytes | A REAL: ymax
50 (32h) | 10 bytes | A REAL: yscl
60 (3Ch) | 10 bytes | A REAL: x
70 (46h) | 10 bytes | A REAL: y
80 (50h) | 10 bytes | A REAL: xres
90 (5Ah) | 2 bytes | Graphing format flags (see graph format flags, below)
92 (5Ch) | 2 bytes | Reserved; these bytes always have a value of 0h
94 (5Eh) | 1 byte | The number of functions in this graph
95 (5Fh) | n bytes | Function definitions, one after another (see function definition format, below).
95 (5Fh)+n | 1 byte | This byte always has a value of 0.
96 (60h)+n | 1 byte | Table setup flags (see table setup flags, below).
97 (61h)+n | 10 bytes | A REAL: tblStart
107 (6Bh)+n | 10 bytes | A REAL: tbl
117 (75h)+n | x bytes | A List: tblInput

A polar-mode graph has the following format:

Offset | Length | Description
--- | --- | ---
0 | 10 bytes | A REAL: xmin (see REAL format, below)
10 (Ah) | 10 bytes | A REAL: xmax
20 (14h) | 10 bytes | A REAL: xscl
30 (1Eh) | 10 bytes | A REAL: ymin
40 (28h) | 10 bytes | A REAL: ymax
50 (32h) | 10 bytes | A REAL: yscl
60 (3Ch) | 10 bytes | A REAL: x
70 (46h) | 10 bytes | A REAL: y
80 (50h) | 10 bytes | A REAL: min
90 (5Ah) | 10 bytes | A REAL: max
100 (64h) | 10 bytes | A REAL: step
110 (6Eh) | 2 bytes | Graphing format flags (see graph format flags, below)
112 (70h) | 2 bytes | Reserved; these bytes always have a value of 0h
114 (72h) | 1 byte | The number of functions in this graph
115 (73h) | n bytes | Function definitions, one after another (see function definition format, below).
115 (73h)+n | 1 byte | This byte always has a value of 0.
116 (74h)+n | 1 byte | Table setup flags (see table setup flags, below).
117 (75h)+n | 10 bytes | A REAL: tblStart
127 (7Fh)+n | 10 bytes | A REAL: tbl
137 (89h)+n | x bytes | A List: tblInput

A parametric-mode graph has the following format:

Offset | Length | Description
--- | --- | ---
0 | 10 bytes | A REAL: xmin (see REAL format, below)
10 (Ah) | 10 bytes | A REAL: xmax
20 (14h) | 10 bytes | A REAL: xscl
30 (1Eh) | 10 bytes | A REAL: ymin
40 (28h) | 10 bytes | A REAL: ymax
50 (32h) | 10 bytes | A REAL: yscl
60 (3Ch) | 10 bytes | A REAL: x
70 (46h) | 10 bytes | A REAL: y
80 (50h) | 10 bytes | A REAL: tmin
90 (5Ah) | 10 bytes | A REAL: tmax
100 (64h) | 10 bytes | A REAL: tstep
110 (6Eh) | 2 bytes | Graphing format flags (see graph format flags, below)
112 (70h) | 2 bytes | Reserved; these bytes always have a value of 0h
114 (72h) | 1 byte | The number of functions in this graph
115 (73h) | n bytes | Function definitions, one after another (see parametric function definition format, below).
115 (73h)+n | 1 byte | This byte always has a value of 0.
116 (74h)+n | 1 byte | Table setup flags (see table setup flags, below).
117 (75h)+n | 10 bytes | A REAL: tblStart
127 (7Fh)+n | 10 bytes | A REAL: tbl
137 (89h)+n | x bytes | A List: tblInput

A sequence-mode graph has the following format:

Offset | Length | Description
--- | --- | ---
0 | 10 bytes | A REAL: xmin (see REAL format, below)
10 (Ah) | 10 bytes | A REAL: xmax
20 (14h) | 10 bytes | A REAL: xscl
30 (1Eh) | 10 bytes | A REAL: ymin
40 (28h) | 10 bytes | A REAL: ymax
50 (32h) | 10 bytes | A REAL: yscl
60 (3Ch) | 10 bytes | A REAL: x
70 (46h) | 10 bytes | A REAL: y
80 (50h) | 10 bytes | A REAL: nmin
90 (5Ah) | 10 bytes | A REAL: nmax
100 (64h) | 10 bytes | A REAL: plotstrt
110 (6Eh) | 10 bytes | A REAL: plotstep
120 (78h) | 2 bytes | Graphing format flags (see graph format flags, below)
122 (7Ah) | 1 byte | X Axis: FFh = n, 00h = u, otherwise i = ui(n).
123 (7Ah) | 1 byte | Y Axis: FFh = n, 00h = u, otherwise i = ui(n).
124 (7Ch) | 1 byte | The number of functions in this graph
125 (7Dh) | n bytes | Function definitions, one after another (see function definition format, below).
125 (7Dh)+n | 1 byte | The number of initial values in this graph
126 (7Eh)+n | m bytes | Initial value definitions, one after another (see initial value definition fromat, below).
126 (7Eh)+n+m | 1 byte | Table setup flags (see table setup flags, below).
127 (7Fh)+n+m | 10 bytes | A REAL: tblStart
137 (89h)+n+m | 10 bytes | A REAL: tbl
147 (93h)+n+m | x bytes | A List: tblInput

A 3D-mode graph has this format:

Offset | Length | Description
--- | --- | ---
0 | 10 bytes | A REAL: xmin (see REAL format, below)
10 (Ah) | 10 bytes | A REAL: xmax
20 (14h) | 10 bytes | A REAL: xgrid
30 (1Eh) | 10 bytes | A REAL: ymin
40 (28h) | 10 bytes | A REAL: ymax
50 (32h) | 10 bytes | A REAL: ygrid
60 (3Ch) | 10 bytes | A REAL: x
70 (46h) | 10 bytes | A REAL: y
80 (50h) | 10 bytes | A REAL: zmin
90 (5Ah) | 10 bytes | A REAL: zmax
100 (64h) | 10 bytes | A REAL: zscl
110 (6Eh) | 10 bytes | A REAL: eye°
120 (78h) | 10 bytes | A REAL: eye°
130 (82h) | 10 bytes | A REAL: An unnamed value dependent on eye° and the screen width
140 (8Ch) | 10 bytes | A REAL: An unnamed value dependent on eye°, eye° and the screen height
150 (96h) | 2 bytes | Graphing format flags (see graph format flags, below)
152 (98h) | 2 bytes | Reserved; these bytes always contain 0.
154 (9Ah) | 1 byte | The number of functions in this graph
155 (9Bh) | n bytes | Function definitions, one after another (see function definition format, below).
155 (9Bh)+n | 1 byte | This byte is always 0.

The graph format flags word has the following format:

Bit (Mask) | Mode if set (1) | Mode if clear (0)
--- | --- | ---
0 (0001h) | Coordinates: POLAR | Coordinates: RECT
1 (0002h) | Leading Cursor: ON | Leading Cursor: OFF
2 (0004h) | Labels: ON | Labels: OFF
3 (0008h) | Axes: BOX | Axes: AXES
4 (0010h) | Axes: OFF | Axes: ON
5 (0020h) | Grid: ON | Grid: OFF
6 (0040h) | Graph Order: SIMUL | Graph Order: SEQ
7 (0080h) | Coordinates: OFF | Coordinates: ON
8 (0100h) | Style: WIRE FRAME | Style: HIDDEN SURFACE
13 (2000h) | Build Web: AUTO | Build Web: TRACE
14 (4000h) | Axes: WEB | Axes: TIME or CUSTOM
15 (8000h) | Axes: TIME | Axes: WEB or CUSTOM

The table setup flags byte has the following format:

Bit (Mask) | Mode if set (1) | Mode if clear (0)
--- | --- | ---
6 (0040h) | Independent: ASK | Independent: AUTO
7 (0080h) | Graph <-> Table: ON | Graph <-> Table: OFF

Function, polar, sequence and 3D-mode function definitions have the following format:

Offset | Length | Description
--- | --- | ---
0 | 1 byte | Function ID (the number of the function).
1 | n bytes | A Function yi(x), ri(), ui(n), or zi(x,y)

Parametric-mode function definitions have the following format:

Offset | Length | Description
--- | --- | ---
0 | 1 byte | Function ID (the number of the function) with bit 7 clear.
1 | n bytes | A Function xti(t)
1+n | 1 byte | Function ID (the number of the function) with bit 7 set.
2+n | m bytes | A Function yti(t)

REAL values referred to in the above GDB format definitions are represented by a sign bit, a 15-bit binary number containing the base-10 exponent, and a binary-coded-decimal (4 bits per decimal digit) 16-digit mantissa:

Offset | Length | Description
--- | --- | ---
0 | 1 byte | Sign bit (bit 7) and upper 7 bits of exponent (bits 0-6)
1 | 1 byte | Lower 8 bitts of exponent
2 | 8 bytes | BCD mantissa

#### Figures

There is no information available about this data type at this time.

#### Pictures

Pictures are 128x63-pixel bitmaps. They have the following format:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this picture minus two for this field
2 | 2 bytes | Height, in pixels, of the picture.
4 | 2 bytes | Width, in pixels, of the picture.
6 | n bytes | Monochrome (1 bpp) bitmap. (n = height * ceiling[width/8] )
6+n | 1 byte | This byte always has a value of DFh.

The following figure demonstrates byte ordering of the pixels if the bitmap for a 128x63 picture is in a 1008-element array data[]:

#### Programs

Programs are represented as a series of tokens in Reverse Polish Notation enclosed in the Prgm and EndPrgm tokens. They can be either tokenized or untokenized.

Untokenized programs have this format:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this program minus two for this field
2 | n bytes | Zero-terminated ASCII text starting with the "(" character in the program name. Line breaks are represented as 0Dh bytes. The colon (":") characters after the line breaks are not stored.
2+n | 2 bytes | Offset, in characters, of the cursor from the beginning of the program
4+n | 3 bytes | These three bytes always contain {19h, E4h, E5h} (Endprgm and '}' tokens).
7+n | 4 bytes | These four bytes always contain {00h, 00h, 08h, DCh}.

Tokenized programs have this format:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this program minus two for this field
2 | n bytes | Program tokens to be pushed onto the stack, then executed once complete.
2+n | 4 bytes | These four bytes always contain {00h, 00h, 40h, DCh}.

The program tokens are generally in reverse order of execution, following the Reverse Polish Notation method that the TI-92 uses. The first tokens in execution order specify the arguments for the program. The next token is always E5h, followed by the "Prgm" token (E4h+19h), then the program statements. Following the program statements is the "EndPrgm" token (E4h+12h), then the E9h token. Each statement is separated by a 00h byte, and line breaks are represented as E8h tokens. Statements on the same line are separated by E7h tokens.

Click here for a table of token definitions.

#### Functions

The format for functions is similar to the format for programs. Functions can be but are not required to be enclosed in Func and Endfunc tokens. Functions, like programs, can be tokenized or untokenized.

Untokenized functions have this format:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this function minus two for this field
2 | n bytes | Zero-terminated ASCII text starting with the "(" character in the function name. Line breaks are represented as 0Dh bytes. The colon (":") characters after the line breaks are not stored.
2+n | 2 bytes | Offset, in characters, of the cursor from the beginning of the function
4+n | 3 bytes | These three bytes always contain {17h, E4h, E5h} (Endfunc and '}' tokens).
7+n | 2 bytes | These two bytes always have a value of 0.
9+n | 1 byte | Flags (see format below).
10 (Ah)+n | 1 byte | This byte always contains DCh.

Tokenized functions have this format:

Offset | Length | Description
--- | --- | ---
0 | 2 bytes | Number of bytes in this program minus two for this field
2 | n bytes | Program tokens
7+n | 2 bytes | These two bytes always have a value of 0.
9+n | 1 byte | Flags (see format below).
10 (Ah)+n | 1 byte | This byte always contains DCh.

The flags byte has the following format:

Bit (Mask) | Mode if set (1) | Mode if clear (0)
--- | --- | ---
0 (01h) | Graph style: 000=line, 001=dot, 010=thick line, 011=animate, 100=path, 101=shade above, 110=shade below, 111=square
1 (02h)
2 (04h)
3 (08h) | Untokenized | Tokenized
4 (10h) | Unknown
5 (20h) | Unknown
6 (40h) | Graph 1 plot on | Graph 1 plot off
7 (80h) | Graph 2 plot on | Graph 2 plot off

#### Macros

There is no information available about this data type at this time.

Backups | Table of Contents | File Formats

Site maintained by Romain Liévin (roms@lpg.ticalc.org) and Tim Singer (tsinger@gladstone.uoregon.edu)