Authors: Thomas Nussbaumer and Lionel Debroux / Version: v2.70 / Date: 25/02/2002

# HANDLE-Explorer v2.70 for the TI-89/TI-92p

## Contents

> (1) General Description
> (2) The Main View
> (3) The Details View
> (4) The Memory View
> (5) Credits and Contact

## (1) General Description

> The HANDLE-Explorer is a useful tool (at least for programmers) to explore the internals of your TI. Each used memory block within your calculator corresponds directly to a so-called HANDLE which is an unsigned 16-bit number (NOTE: in this document the phrase 'memory block' will always refer to a used memory block).

> Memory blocks can have two states in general:
> - (1) they are memory-locked
> - (2) they are movable
> If you wonder why I call the first state memory-locked: there exist two kinds of locking mechanisms within the AMS. One is related to memory blocks and the other is related to files. You can read more about this in section The Details View.
> Within the AMS there exists a mechanism called heap compression. If you copy or move files around or if you generate and delete variables the calculator's memory gets fragmented. The heap compression tries to move memory blocks around around to keep the number of "holes" between the blocks as small as possible. The two states above mentioned of the memory blocks hints this mechanism if a memory block can be moved around without any danger or if it is "locked", which means that it will NOT be moved around. Locked memory blocks are normally blocks which are currently in use, like the active program.
> Note that memory blocks which are located in the archive memory are also in memory-locked state (the mechanism for 'heap compression' of the archive memory, when it gets too fragmented, is called garbage collection).

## (2) The Main View

> Screenshot of Main View |

> When you start the HANDLE-Explorer the Main View will be displayed, it is a scollable list of all memory related handles on your calculator. Scrolling can be performed by using the cursor keys ([UP] and [DOWN]). To jump to the first page use [2nd][UP] or [DIAMOND][UP] and to jump to the last page use [2nd][DOWN] or [DIAMOND][DOWN].

> Starting from Version 2.00, you can view the memory content of your TI indepently from a handle by pressing the [APPS] key and entering a memory address between 0 and 0x3FFFF.

> NOTE: The hexcode viewer may display different things in the left and in the right part of the screen... This may occur if displaying in various areas of the memory, particularly:

> - both user and supervisor stacks, that is to say 0x400 - 0x4BFF.
> - the video memory (LCD_MEM, 0x4C00 - 0x5AFF).
> - 0x5B00 to the lowest byte of the heap, particularly 0x7000-0x7FFF area (due to system functions: they put debug information in this area).
> - the place where is located the backbuffer used...
> - maybe elsewhere I didn't think of, don't blame me... ;-)

> Infos displayed in the Header Line:

> The number displayed after the capital "S" is the whole number of memory related handles found on your calculator. The number displayed after the capital "L" displays the number of memory-locked handles (not movable memory blocks) and the number displayed after the capital "F" is the number of free handles available on your calculator. Note that handles which reference to blocks in the archive are always memory-locked (not movable).

> If you press [F1] when you are in the Main View a short help page will be displayed, which explains the possible keys and the displayed data. By pressing [ESC] or [F5] you can leave the program.

> Infos displayed in each Line

> Each line in the Main View corresponds to a memory related handle. The columns from left to right shows the following informations:

> Column 1

> If you see a capital "V" in this column it's a VAT entry (a file or folder). A capital "W" means that this handle is used for a saved screen area of a window. A capital "S" means that this handle is related to the EStack. A captial "E" means that this handle is an Event Hook. A capital "H" means that this handle is used by a commandline history entry and a capital "C" means that this handle is used by the Handle-Explorer itself as character set.

> Column 2 | The handle number.
> Column 3 | The memory address which corresponds to this handle.
> Column 4 | The length of the memory block in bytes.
> Column 5 | A capital "M" means that this block is movable, a capital "L" means that this block is memory-locked.
> Column 6 | Line number within page. If you see a "*" then this handle is the HANDLE-Explorer itself.

> To enter the Details View of one of the displayed handle lines, just press the key related to the value displayed in the last line. If you see a "*" you have to guess the value by your own, but this shouldn't be too hard ;-)

> NOTE: The displayed sizes are the sizes which are really allocated for a memory block. Allocated blocks have always an even number of bytes. If you allocate a block with an odd size the AMS will round up the size automatically !!!

> From the TIGCCLIB documentation:

> Also note that because of locked blocks, it is possible (rare) that a heap block will actually be bumped up a few words by the HeapCompress routine. So never assume that the value returned by HeapSize is the true number of bytes used by the data stored in the heap block.

## (3) The Details View

> Screenshot of Details View |

> The Details View shows you (nomen-omen-est) details about one handle. The header line contains the same data as the corresponding line in the Main View. If a handle cannot be found within the VAT this screen will only show a small note.
> If the handle corresponds to a VAT entry its complete name (foldername+filename) will be displayed as well as a list of its file flags. You will also see a flag called "locked". This flag has nothing to do with the memory-locks. These lock only a logical lock which is used by the AMS when you lock a file using the Var-Link screen.
> You can use the cursor keys ([LEFT] and [RIGHT]) to jump to view details of the previous or the next handle. If you press [ESC] you will go back to the Main View. By pressing [F5] you will exit the HANDLE-Explorer immediately.
> To view the content of the memory block which corresponds to the active handle press [ENTER].

## (4) The Memory View (of a Handle)

> Screenshot of Memory View |

> This view shows you the content of the memory block which is related to a handle. The header line displays again the corresponding line from the main view.

> The display is arranged in 3 parts. To the most left you can see a list of offsets within the memory block (4 digit hexvalue), in the middle the following 6 bytes (on 89) and 10 bytes (on 92p) at this offset are displayed and to the most right the corresponding character values of these bytes are displayed.
> To scroll through the memory block use [UP] and [DOWN].
> To jump to the first page use [DIAMOND][UP].
> To jump to the last page use [DIAMOND][DOWN].
> To jump 256 (on 89) or 512 (on 92+) bytes up use [2nd][UP].
> To jump 256 (on 89) or 512 (on 92+) bytes down use [2nd][DOWN].
> To jump to the previous or the next memory block press [LEFT] or [RIGHT].
> To jump to a place of the block press [MODE].
> To change the delay after displaying a page (in order to be able to see what's on the page, because drawing is very fast), use [(] and [)].
> [ESC] will bring you back to the details view, [F5] will immediately exit the HANDLE-Explorer.

> In Version 2.00 search functionalities were integrated. Press F6, F7 or F8 to search for a byte, a word or a dword. Press F2 to find the previous occurence of the entered value and F3 to find the next occurence of it.

> NOTE: The finders may return irrelevant results if searching in various areas of the memory, particularly (these areas are just the same as the areas where the memory dump may display different things in the left part and in the right part):

> - both user and supervisor stacks, that is to say 0x400 - 0x4BFF.
> - the video memory (LCD_MEM, 0x4C00 - 0x5AFF).
> - 0x5B00 to the lowest byte of the heap, particularly 0x7000-0x7FFF area (due to system functions: they put debug information in this area).
> - the place where is located the backbuffer used...
> - maybe elsewhere I didn't think of, don't blame me... ;-)

## (5) Credits and Contact

> And the credits go to:
> - Zeljko Juric - for providing me informations how to retrieve the start of the handle table in HW and AMS version independant manner.
> - Samuel Stearley - pointing me out how to access the history pairs and for the tip to traverse the window list.
> - Kevin Kofler - for reported me the problem with the displayed sizes in previous versions.
> - Lionel Debroux - for all improvements since version 2.00 (searching etc.)
> - ... and, of course, myself (Thomas Nussbaumer) for the rest.

> I prefer that you use our MessageBoard at http://pub26.ezboard.com/btichessteamhq to post suggestions and bug reports.

Thomas Nussbaumer, Graz/Austria 25/02/2002 - Visit the TICT-HQ at http://tict.ticalc.org