The <system.h> Header File

System routines (for accessing system timers, queues, etc.)

Functions

AB_getGateArrayVersion
Returns the hardware version of the calculator.
AB_prodid
Determines the product ID code.
AB_prodname
Determines the product name.
AB_serno
Determines the serial number.
ASM_call
Calls a subroutine located on absolute address, with saving/restoring all registers.
ASM_fastcall
Calls a subroutine located on absolute address.
CB_fetchTEXT
Fetches a text from the clipboard.
CB_replaceTEXT
Puts a text into the clipboard.
CU_restore
Restores the previous cursor state.
CU_start
Starts the cursor.
CU_stop
Stops the cursor.
enter_ghost_space
Transfers the execution into the "ghost address space".
EX_getBasecodeParmBlock
Gets a pointer to the base code parameter block.
EX_patch
Relocates an assembly program.
HelpKeys
Displays a keyboard help screen.
idle
Switches the calculator to "idle" state for a while.
kbd_queue
Returns a pointer to the keyboard queue.
LOC_formatDate
Formats a date into date according to format string.
LOC_getLocalDateFormat
Returns a pointer to the date format string specified by the current language mode setting.
LOC_localVersionDate
Formats release date of AMS Operating System according to current language setting.
NeedStack
Checks for space on the stack.
off
Turns the calculator off.
OSCheckBreak
Checks pressing of BREAK key.
OSClearBreak
Clears "BREAK key pressed" flag.
OSContrastAddress
Returns a pointer to the contrast value.
OSContrastDn
Decreases the contrast.
OSContrastUp
Increases the contrast.
OSdequeue
Removes an element from a queue.
OSDisableBreak
Disables the break key ('ON').
OSEnableBreak
Enables the break key ('ON').
OSenqueue
Insert a new element into a queue.
OSFreeTimer
Frees a notify (countdown) timer.
OSqclear
Clears a queue.
OSqhead
Gets an element from the head of a queue.
OSqinquire
Checks whether an element is waiting in a queue.
OSRegisterTimer
Registers a notify (countdown) timer.
OSReset
Resets the calculator.
OSSetSR
Sets the processor status register.
OSTimerCurVal
Determines a current value of a notify (countdown) timer.
OSTimerExpired
Determines whether a notify (countdown) timer expired.
OSTimerRestart
Restarts a notify (countdown) timer.
OSVFreeTimer
Frees an event (vectored) timer.
OSVRegisterTimer
Registers an event (vectored) timer.
QModeKey
Checks whether argument is code of a mode key.
QSysKey
Checks whether argument is code of a system key.
SumStoChkMem
Compares memory contents by making a checksum.
WordInList
Searches for a word in the list.
XR_stringPtr
Returns a pointer to a TIOS system message (XR string).

Global Variables

CTypeTable
A pointer to a table describing the types of the AMS characters.
CU_cursorState
Contains the current cursor state (on or off).
FiftyMsecTick
A counter incremented by the standard system auto-int 5 routine.
OSContrastValue
Byte containing the value of the current contrast.
OSOnBreak
System variable indicating that the ON key was pressed.
Used by OSCheckBreak, OSClearBreak, OSLinkClose between others.
ReleaseDate
A pointer to a string containing the release date of the AMS.
ReleaseVersion
A pointer to a string containing the AMS version.

Constants

KB_AUTOREPEAT
A constant defining the "auto-repeat" bit.

Predefined Types

BASECODE_PARM_BLOCK
A structure containing version information about the operating system.
Bool
An enumeration to describe true or false values.
DEF_QUEUE
A structure describing the header of a variable-sized queue.
HANDLE
Represents a handle associated with an allocated memory block.
QUEUE
A structure describing a queue with a buffer.
Timer_Callback_t
Describes a timer callback function.
Timers
An enumeration for describing timer ID numbers.

AB_getGateArrayVersion

AMS 2.00 or higher

unsigned long AB_getGateArrayVersion (void);

Returns the hardware version of the calculator.

AB_getGateArrayVersion returns the version number of the gate array, that is to say the hardware version of the calculator. Currently, there are two hardware versions: 1 and 2.

For an AMS-independent way of getting the hardware version, take a look at FL_getHardwareParmBlock.

See also: FL_getHardwareParmBlock


AB_prodid

void AB_prodid (char *buffer);

Determines the product ID code.

AB_prodid fills the buffer with the product ID code of the calculator. The ID string is in the form "p-h-r-b", where "p" is the product number (01 for TI-92 Plus, 03 for TI-89), "h" is the hardware revision level, "r" is the software revision level and "b" is the build number. All the above fields consist of hexadecimal digits. buffer must be at least 12 bytes long to accept the product ID string.


AB_prodname

void AB_prodname (char *buffer);

Determines the product name.

AB_prodname fills the buffer with the product name, i.e. the name of the operating system software running on the calculator. This is the same name that appears on the second line of the "About" window. Not very useful, because it seems that so far the product name is always "Advanced Mathematics Software". buffer must be at least 40 bytes long to accept the product name.


AB_serno

short AB_serno (char *buffer);

Determines the serial number.

AB_serno tries to fill the buffer with the serial number of the calculator. The serial number is constructed from the string returned from cgetsn function (with one space inserted in the middle), and from the hexadecimal value returned from FL_getVerNum function. Note that these routines are very cryptic, and do some ugly things with the Flash memory, so this probably works only on real TI (at least, it does not work under VTI). AB_serno returns TRUE if determining the serial number was successful, else returns FALSE (this is a case on VTI, for example). The serial number has the form "pphnn nnnnn vvvv", where "pp" is the platform number (01 for TI-92 Plus, 03 for TI-89), "h" is hardware revision level, "nnnnnnn" is an ID number which is unique to each calculator, and "vvvv" is a verification number. All the above fields consist of hexadecimal digits. buffer must be at least 17 bytes long to accept the serial number.


ASM_call

void ASM_call (void *base_addr);

Calls a subroutine located on absolute address, with saving/restoring all registers.

ASM_call pushes all registers onto the stack, performs ASM_fastcall, then restores all saved registers from the stack. Use ASM_call whenever you are not sure about behaviour of called subroutine. If you are sure that the called subroutine will preserve all registers, you can use ASM_fastcall: it generates smaller and faster code.


ASM_fastcall

void ASM_fastcall (void *base_addr);

Calls a subroutine located on absolute address.

ASM_fastcall calls an assembly subroutine located at absolute address base_addr. As ASM_fastcall is a macro, not a function, base_addr need not to be a pointer. It can also be an unsigned (long) integer. In fact,

ASM_fastcall (base_addr);

is the same as

((void(*)(void))(base_addr)) ();

but much more readable. It performs just a "jsr" to base_addr; it does not perform any relocation of relocatable items (to do this, see EX_patch).

ASM_fastcall assumes that called subroutine will not destroy any registers. If this assumption is not valid, use ASM_call instead. In fact, if you are not very sure about behaviour of called subroutine, it is highly recommended to avoid ASM_fastcall and to use ASM_call. In releases of TIGCCLIB prior to 2.1, ASM_call does exactly what ASM_fastcall does in this release.

Note: This function should be used with great care, because on HW2 calculators a stupid protection device does not allow that the program counter may be on arbitrary place, except if some special precausions are performed. Anyway, this function is not designed for common use: it is intended for very experienced system programmers. Don't use it if you don't know very well what are you doing!


CB_fetchTEXT

short CB_fetchTEXT (HANDLE *hText, unsigned long *len);

Fetches a text from the clipboard.

CB_fetchTEXT stores in the variable pointed to by hText the handle of the text stored in the clipboard (use HeapDeref to get actual pointer to the text). It also stores the length of the text in the variable pointed to by len.

CB_fetchTEXT returns TRUE if the operation was successful, else returns FALSE (i.e. if the clipboard is empty or trashed).

AMS will only store text in the clipboard and will always assume that it contains text. However, programs may try to store non-text data in it, although it's not a good practice, since it might cause strange things to happen on the calculator...

The clipboard handle is not locked, so it can be moved during heap compression.

See also: CB_replaceTEXT


CB_replaceTEXT

short CB_replaceTEXT (char *text, unsigned long len, short strip_CR);

Puts a text into the clipboard.

CB_replaceTEXT puts len bytes starting from the address text to the clipboard. TIOS only uses clipboard for storing text, but it is capable to store other types too. strip_CR is Boolean parameter: if it is TRUE, each byte which follows immidiately after '\r' character (0xD) will not be stored in the clipboard (this in fact stripes out command characters in text editor: see textedit.h header file). CB_replaceTEXT returns TRUE if the operation was successful, else returns FALSE (e.g. no enough memory). This routine may cause heap compression.

See also: CB_fetchTEXT


CU_restore

void CU_restore (short State);

Restores the previous cursor state.

CU_restore restores the previous cursor state (active or inactive). Parameter State should be a value returned from CU_start or CU_stop function.


CU_start

short CU_start (void);

Starts the cursor.

CU_start restarts the cursor timer and sets an internal flag which tell that cursor is active. This does not mean that the cursor will be displayed on the screen immidiately. This mean only that if some routine wants to display cursor, it will be permitted. The main usage of this function is in conjuction with text editor functions (see textedit.h header file). CU_start returns TRUE or FALSE, depending of whether the cursor was enabled or disabled before calling this function.


CU_stop

short CU_stop (void);

Stops the cursor.

CU_stop resets an internal flag which tell that cursor is active, so after this function, displaying of the cursor will be denied. This function is called often from event driven and interrupt driven applications to stop the cursor blinking for a while. CU_stop returns TRUE or FALSE, depending of whether the cursor was enabled or disabled before calling this function.


enter_ghost_space

void enter_ghost_space (void);

Transfers the execution into the "ghost address space".

enter_ghost_space transfers the program control into the "ghost address space" (i.e. into the area above the address 0x40000, which does not exist physically on the calculator, but represents a shadow of the regular RAM space). This function is introduced to bypass some protections introduced in AMS 2: The protection device does not protect the "ghost space", so you have greater rights there. From the logical aspect of view, enter_ghost_space simply adds 0x40000 to the program counter. In practice, this is performed in a very awkward way, because some new protections in AMS 2 do not allow us to do this directly under all conditions. See the launcher FAQ entry for the only example where you should really use this function. You should not to know anything more about it.

However, be sure to call enter_ghost_space only from the _main function. Once you have called it, you may not call any functions from the TIGCC library or from your program without explicitly adding 0x40000 to their address. This does not affect macros like ASM_call or ROM calls.

Moreover, enter_ghost_space doesn't work on HW3 (the TI-89 Titanium).

Note: Because of these limitations, enter_ghost_space is deprecated. You can use the newer EXECUTE_IN_GHOST_SPACE directive instead. EXECUTE_IN_GHOST_SPACE will handle the TI-89 Titanium appropriately.


EX_getBasecodeParmBlock

AMS 2.04 or higher

const void *EX_getBasecodeParmBlock (void);

Gets a pointer to the base code parameter block.

EX_getBasecodeParmBlock gets a pointer to a BASECODE_PARM_BLOCK structure. The base code parameter block contains version information about the AMS: the major and minor version number and the date the OS was built.

See also: BASECODE_PARM_BLOCK


EX_patch

void EX_patch (void *base_addr, void *tag_ptr);

Relocates an assembly program.

EX_patch relocates relocatable items in the assembly program (.89z or .9xz file), where tag_ptr points to the "PROGRAM" signature (tag) byte (byte 0xF3), and base_addr is the address from where the assembly program will be started. So, if handle is a handle of an .89z (or .9xz) file, you can execute it using

len = *(unsigned short*)(base_ptr = HLock (handle));
EX_patch (base_ptr + 2, base_ptr + len + 1);
ASM_call (base_ptr + 2);
HeapUnlock (handle);

In practice, some protection devices in HW2 calculators make the whole thing much more complicated (see the launcher FAQ entry for more info).

Note that the relocation table ends just below the tag byte.

Note: If base_addr is in the ghost space, tag_ptr has to be in the ghost space, too!

See also: enter_ghost_space, EXECUTE_IN_GHOST_SPACE


HelpKeys

void HelpKeys (void);

Displays a keyboard help screen.

HelpKeys displays a keyboard help on the screen (the help screen which may be called by pressing Diamond+EE on TI-89), waits for a keypress, then restores the screen to the previous state.


idle

void idle (void);

Switches the calculator to "idle" state for a while.

While idle is running, the calculator rests. idle turns the calculator in "low power" state until the next interrupt occurs (then "low power" state will be disabled, and idle returns).

While calculator is in "idle" state, the power consumption decreases significantly. TIOS very often calls idle, whenever it is in a kind of "idle loop". So it is very useful to be used in programs which waits in a loop for something (waiting for specific keypress, timer expiring, etc.). Many programs should use idle to save the batteries (editors, reflexive games, explorers, debuggers etc.). Thanks to Julien Muchembled for this info.

Note: Thomas Nussbaumer informed me that idle interferes with grayscale graphics, so the use of idle while grayscale mode is active is not recommended.


kbd_queue

void *kbd_queue (void);

Returns a pointer to the keyboard queue.

kbd_queue returns a pointer to the queue used in TIOS for keyboard handling. It may be used as an argument to other queue-related functions. The main purpose of accessing to keyboard queue is to make a fast replacement for ngetchx and kbhit functions. This may be achieved using OSdequeue function. For example, suppose that you have the following declarations:

void *kbq = kbd_queue ();
unsigned short key;

Then, statements like

if (kbhit ())
{
  key = ngetchx ();
  // Do something with key
}

may be replaced with the much faster equivalent:

if (!OSdequeue (&key, kbq))
{
  // Do something with key
}

Note: On the first look, it seems that the key repetition feature does not work with OSdequeue. But, Marcos Lopez informed me that this is not exactly true. Key repetition feature works even with OSdequeue, but it will not return the keycode itself for the repeated key, but add the KB_AUTOREPEAT "auto-repeat" bit to the keycode (more exactly, KB_AUTOREPEAT is OR'd with the keycode), so value becomes value + 0x800. If you use the standard ngetchx function, this additional bit is masked out and your program will get the keycodes it expects. But, it is very simple to mask out this bit manually and make the key repetition feature work even with OSdequeue.

See also: OSdequeue, kbd.h


LOC_formatDate

AMS 2.02 or higher

void LOC_formatDate (const char *format, short y, short m, short d, char *date);

Formats a date into date according to format string.

format: string containing date specifiers:
D : One- or two-digit day of month.
DD : Two-digit day of month (leading zero if necessary).
M : One- or two-digit month.
MM : Two-digit month (leading zero if necessary).
YY : Two-digit year (year without century).
YYYY : Four-digit year.
Any other characters are copied to output.

y : Year.
m : Month.
d : Day of month.

Examples:

char date[16];
short y = 2000, m = 6, d = 9;
LOC_formatDate("M/D/YYYY", y, m, d, date);   // 6/9/2000
LOC_formatDate("MM/DD/YYYY", y, m, d, date); // 06/09/2000
LOC_formatDate("YYYY.MM.DD", y, m, d, date); // 2000.06.09
LOC_formatDate("D-M-YY", y, m, d, date);     // 9-6-00
LOC_formatDate("MM/YYYY", y, m, d, date);    // 06/2000

The ROM_CALL LOC_formatDate is available only on AMS 2.02 and higher.

Note: LOC_formatDate doesn't check the parameters, as you'll see if you try:

LOC_formatDate("MM/DD/YYYY",32767,32767,32767,buffer);

if buffer is large enough.

See also: LOC_getLocalDateFormat, LOC_localVersionDate


LOC_getLocalDateFormat

AMS 2.02 or higher

const char *LOC_getLocalDateFormat (void);

Returns a pointer to the date format string specified by the current language mode setting.

Example:

char date[16];
short y = 2000, m = 6, d = 9;
// Format date according to current language.
LOC_formatDate(LOC_getLocalDateFormat(), y, m, d, date);

See also: LOC_formatDate, LOC_localVersionDate


LOC_localVersionDate

AMS 2.02 or higher

char *LOC_localVersionDate (char datebuf[]);

Formats release date of AMS Operating System according to current language setting.

The Home screen About dialog calls this routine to display the release date of the built-in calculator software.

Example:

char date[16];
// Format OS release date according to current language.
LOC_localVersionDate(date);

See also: LOC_formatDate, LOC_getLocalDateFormat


NeedStack

void NeedStack (short Size);

Checks for space on the stack.

NeedStack throws a memory error if there is no enough space on the processor stack for Size bytes (the hardware stack is 16K in size; when a function calls another function the system will throw an error if there is not enough hardware stack to make the call). Although this routine is used mainly internally in TIOS, sometimes it may be useful even in user programs. For example, a function may have a complex set of operations that may not be easily undone in a ONERR block. The function may also require that all of the operations do not fail due to a lack of hardware stack. In this case, the function can be started with a call to NeedStack to at least guarantee that the hardware stack will not overflow during the critical section of the function. Critical operations may be, say, direct modifying elements of the VAT table. So, if the function calls NeedStack first, this insures that none of the critical operations are partially completed due to a lack of hardware stack thus leaving the VAT table (for example) in an undefined state. The TI-Basic interpreter uses the hardware stack to make recursive calls and so all TI-Basic commands and functions cannot rely on the hardware stack being at any particular level.


off

void off (void);

Turns the calculator off.

off turns the calculator off. asm("trap #4") does exactly same thing, but calling this routine is more official.


OSCheckBreak

short OSCheckBreak (void);

Checks pressing of BREAK key.

OSCheckBreak returns TRUE if BREAK key was pressed (for this, BREAK must be enabled using OSEnableBreak), else returns FALSE. Note that OSCheckBreak will remain true until explicite call of OSClearBreak.


OSClearBreak

void OSClearBreak (void);

Clears "BREAK key pressed" flag.

OSClearBreak clears "BREAK key pressed" flag. See OSCheckBreak for more info.


OSContrastAddress

unsigned char *OSContrastAddress;

Returns a pointer to the contrast value.

It is the address of the byte containing the current contrast (OSContrastValue).
See OSContrastValue for more information.

See also: OSContrastUp, OSContrastDn, OSContrastValue


OSContrastDn

void OSContrastDn (void);

Decreases the contrast.

OSContrastDn decreases the display contrast. It is actually a library function calling the real TIOS function called OSContrastDn, because the TIOS function destroys the content of a register which needs to be preserved.

See also: OSContrastUp, OSContrastAddress, OSContrastValue


OSContrastUp

void OSContrastUp (void);

Increases the contrast.

OSContrastUp increases the display contrast. It is actually a library function calling the real TIOS function called OSContrastUp, because the TIOS function destroys the content of a register which needs to be preserved.

See also: OSContrastDn, OSContrastAddress, OSContrastValue


OSdequeue

AMS 1.01 or higher

short OSdequeue (unsigned short *dest, void *Queue);

Removes an element from a queue.

OSdequeue removes an element from a queue structure pointed to by Queue and stores them in the variable pointed to by dest. As queue is a FIFO structure, first removed element is the first element inserted in the queue; the next removed element is the second element inserted in the queue, etc. OSdequeue returns TRUE if the queue was empty, else returns FALSE.

Note: This function may be used for fast keyboard reading: see kbd_queue.

See also: OSenqueue, kbd_queue


OSDisableBreak

void OSDisableBreak (void);

Disables the break key ('ON').

OSDisableBreak disables the break key.

Note: Although the break (i.e. 'ON') key is disabled during the execution of assembly programs, the execution of some TIOS functions may be breaked by pressing 'ON' (usually functions which execute some internal loops with long or undeterminate duration, like various high-level linking functions, etc.). The use of OSDisableBreak will disable the break key even in such cases.

See also: OSEnableBreak


OSEnableBreak

void OSEnableBreak (void);

Enables the break key ('ON').

OSEnableBreak enables the break key (of course, not during execution of assembly programs). The break key may be read from assembly programs using OSCheckBreak.

See also: OSDisableBreak


OSenqueue

AMS 1.01 or higher

short OSenqueue (unsigned short data, void *Queue);

Insert a new element into a queue.

OSenqueue inserts the element data in a queue (FIFO - First In First Out) structure pointed to by Queue. Queue is usually a pointer to the structure of the type QUEUE or DEF_QUEUE. OSenqueue returns TRUE if the operation was sucessful, else return FALSE (for example, if the queue is full). See destription of queue types QUEUE and DEF_QUEUE for an example of usage.

See also: OSdequeue


OSFreeTimer

short OSFreeTimer (short timer_no);

Frees a notify (countdown) timer.

OSFreeTimer deactivates and frees the notify (countdown) timer timer_no. OSFreeTimer must be called before registering a timer using OSRegisterTimer if the timer was already in use. Returns FALSE in a case of error, else returns TRUE.


OSqclear

AMS 1.01 or higher

void OSqclear (void *Queue);

Clears a queue.

OSqclear empties and resets the queue structure pointed to by Queue. More precise, it resets the structure to {0, 0, 2, 0}.

See also: OSenqueue


OSqhead

AMS 1.01 or higher

unsigned short OSqhead (unsigned short *dummy, void *Queue);

Gets an element from the head of a queue.

OSqhead returns an element from the head of a queue structure pointed to by Queue without removing it from the queue (the head element is the last element inserted in the queue, not the first one). dummy is the dummy parameter: it is not used in the routine.

See also: OSenqueue


OSqinquire

AMS 1.01 or higher

short OSqinquire (unsigned short *dest, void *Queue);

Checks whether an element is waiting in a queue.

OSqinquire returns TRUE if the queue pointed to by Queue is not empty (i.e. if there is an element waiting in it), else returns FALSE. If the queue is not empty, OSqinquire also stores the first element which will be removed from the queue in the variable pointed to by dest, but in opposite to OSdequeue the element itself will not be removed from the queue.

See also: OSenqueue


OSRegisterTimer

short OSRegisterTimer (short timer_no, unsigned long T);

Registers a notify (countdown) timer.

TIOS has several notify (countdown) timers. The number of timers is not the same on all AMS versions:
All AMS versions up to 2.03 6 timers (1 to 6)
AMS 2.04 and 2.05 7 timers (1 to 7)
AMS 2.07, 2.08 and 2.09 8 timers (1 to 8)

OSRegisterTimer initializes the timer which ID number is timer_no, and sets its initial value to T. Every time the Auto-Int 5 is triggered (approximatively 20 times per second if you didn't change the programable rate generator), the current value of the timer is decremented by 1. When the current value reaches zero, nothing special happens, but a flag is set which indicates that the timer is expired. This flag may be check using function OSTimerExpired.

OSRegisterTimer returns timer_no if the registration was successful, else returns zero. This happens if you give wrong parameters, or if the timer timer_no is already in use. So, you must first free the timer using OSFreeTimer.

Usual use of the timers:

Legal timer numbers (like APD_TIMER) are defined in enum Timers, to make a program more readable. See also other timer functions for more info.

See also: FiftyMsecTick, OSFreeTimer, OSTimerCurVal, OSTimerExpired, OSTimerRestart


OSReset

void OSReset (void);

Resets the calculator.

OSReset resets the calculator without any warnings.


OSSetSR

short OSSetSR (short SR);

Sets the processor status register.

OSSetSR sets the processor status register to SR. Supervisor and trace bits cannot be set up using this routine. For example, use

OSSetSR (0x0700);

to disable all interrupts, and

OSSetSR (0x0000);

to enable them again. Note that any call to keyboard input routines like ngetchx etc. will enable interrupts again.

OSSetSR returns the previous contents of the status register.

Note: Disabling Auto-Int 1 is often used for making the status line indicators not visible on the screen so that the status indicators do not mess up your graphics (status line indicators are updated from this interrupt). In this case, you need to read the keyboard using _rowread function, because functions like ngetchx are based on Auto-Int 1. However, if you disable interrupts, the grayscale will not work, because the grayscale is also based on Auto-Int 1. To solve this problem, instead of disabling Auto-Int 1, you may redirect it to nothing. See DUMMY_HANDLER from intr.h for more info.


OSTimerCurVal

unsigned long OSTimerCurVal (short timer_no);

Determines a current value of a notify (countdown) timer.

OSTimerCurVal returns a current value of the timer timer_no.


OSTimerExpired

short OSTimerExpired (short timer_no);

Determines whether a notify (countdown) timer expired.

OSTimerExpired returns TRUE if the notify (countdown) timer timer_no expired, else returns FALSE. See OSRegisterTimer for more info. For example, a legal way to make a 5-second delay is:

OSFreeTimer (USER_TIMER);
OSRegisterTimer (USER_TIMER, 5*20);
while (!OSTimerExpired (USER_TIMER));

OSTimerExpired also resets flag which tells that the timer was expired, so the calling this function again will return FALSE.


OSTimerRestart

unsigned long OSTimerRestart (short timer_no);

Restarts a notify (countdown) timer.

OSTimerRestart resets the timer timer_no to its initial value, and returns the current value of the timer as was before reseting.


OSVFreeTimer

short OSVFreeTimer (short timer_no);

Frees an event (vectored) timer.

OSVFreeTimer deactivates and frees the event (vectored) timer timer_no. OSVFreeTimer must be called before registering a timer using OSVRegisterTimer if the timer was already in use. Returns FALSE in a case of error, else returns TRUE.

Note: Don't forget to free an event timer which was registered before exiting the program; else very bad things may happen later. I expect that you know why...


OSVRegisterTimer

short OSVRegisterTimer (short timer_no, unsigned long T, Timer_Callback_t Action);

Registers an event (vectored) timer.

Before release 2.04 of the AMS, TIOS also had two event (vectored) timers numbered as 1 and 2 (in addition to 6 notify timers which may be registered using OSRegisterTimer). In AMS 2.04, Texas Instruments decided for some strange reasons to remove these vectored timers from the TIOS. I was very angry due to this decision, so I decided to reimplement these timers independently of the TIOS, to make them work on any AMS version. Well, now you have it. More precise, you now have two event (vectored) timers which are numbered as 1 and 2, which work on any AMS release (TIOS based implementation as implemented in TIGCCLIB releases prior to 2.2 did not work on AMS 2.04 and AMS 2.05).

OSVRegisterTimer initializes the event timer which ID number is timer_no, and sets its initial value to T. Every time the Auto-Int 5 is triggered (20 times per second if you didn't change the programable rate generator), the current value of the timer is decremented by 1. When the current value reaches zero, a procedure specified by user will be called, then the timer starts counting again from its initial value. The parameter Action is the pointer to the procedure which will be triggered every time the timer reaches zero. So, the procedure Action will be called periodically, with a period determined by T.

Action need not to be an assembly language procedure; it may be any user-defined function written in C. Its body will be executed in the supervisor CPU mode and with disabled interrupts (th information is probably not important from the user point of view).

If the function Action changes any global variable in the program, such global variable must be declared as "volatile" to inform the compiler that its value may be changed asynchronously, i.e. in a way which is unexpected for the normal program flow.

OSVRegisterTimer returns a nonzero value if the registration was successful, else returns zero. This happens if you give wrong parameters, or if the timer timer_no is already in use. So, you must first free the timer using OSVFreeTimer (as I completely rewrote these routines, I also corrected some bugs in them which were presented in TIOS routines; you know about them if you read the documentation about OSVRegisterTimer in earlier releases of TIGCCLIB). As event timers now work indepentently of TIOS timers, both event timers (1 and 2) are free for use. Here is a simple example of a program which installs both event timers (called "Timers"):

// Install two timers with counter variables

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define MIN_AMS 100           // Compile for AMS 1.00 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

#include <tigcclib.h>         // Include All Header Files

CALLBACK void Action1(void)
{
  static int Counter = 0;
  printf_xy (50, 50, "Counter1 = %d  ", ++Counter);
}

CALLBACK void Action2(void)
{
  static int Counter = 0;
  printf_xy (70, 70, "Counter2 = %d  ", ++Counter);
}

void _main(void)
{
  OSVRegisterTimer (1, 3, Action1);
  OSVRegisterTimer (2, 10, Action2);
  ngetchx ();
  OSVFreeTimer (1);
  OSVFreeTimer (2);
}

In this implementation of OSVRegisterTimer, it is not necessary to free timers using OSVFreeTimer before first usage of them, because they are free by default at the begining. However, nothing wrong will happen if you try to free them explicitely (which was necessary in previous releases of TIGCCLIB).

Note: As already mentioned above, all TIOS bugs in timer routines (dependence between notify and event timers, etc.) are now removed, because these routines are rewritten to be independent of the TIOS.


QModeKey

short QModeKey (short code);

Checks whether argument is code of a mode key.

QModeKey returns TRUE if code is code of a mode key, else returns FALSE. It assumes that code is code as the function ngetchx for reading the keyboard returns. Mode keys are keys which may cause change of the current application or the configuration of the calculator. The following keys are mode keys on the TI-89: HOME, APPS, MODE, VAR-LINK, SWITCH (2nd+APPS), MEM, QUIT, Y=, WINDOW, GRAPH, TblSet, TABLE and OFF (codes 277, 265, 266, 4141, 4361, 4150, 4360, 16652, 16653, 16654, 16655, 16656 and 4363). Note that codes returned by ngetchx are mostly equal like codes returned by BASIC command GetKey, but codes of arrow keys, and keys pressed together with Diamond keys are different. See ngetchx for more info.


QSysKey

short QSysKey (short code);

Checks whether argument is code of a system key.

QSysKey returns TRUE if code is code of a system key, else returns FALSE. It assumes that code is code as the function ngetchx for reading the keyboard returns. System keys are keys which opens menus, which may have as the result inserting characters or tokens in the editor. The following keys are system keys on the TI-89: MATH, CATALOG, CHAR and CUSTOM (codes 4149, 278, 4139 and 4373).


SumStoChkMem

short SumStoChkMem (void);

Compares memory contents by making a checksum.

SumStoChkMem calculates a checksum of the user portion of the RAM memory (more precisely, from address 0x400 to 0xFFF (on AMS 1.xx) or to 0xF7F (on AMS 2.xx) and from the bottom of the heap to the end of the RAM), and stores the calculated value in an internal system variable. It returns TRUE if the calculated checksum is equal to the previous value of this system variable, else returns FALSE. So, SumStoChkMem may be used to check whether the contents of the memory were changed since the last call of SumStoChkMem (i.e. between two calls of SumStoChkMem).


WordInList

short WordInList (unsigned short Word, unsigned short *List);

Searches for a word in the list.

WordInList is a useful short routine which returns TRUE if the word Word is a member of the list (i.e. array) of words pointed to by List, otherwise returns FALSE. The list of words is terminated by the word 0.


XR_stringPtr

const char *XR_stringPtr (long XR_string_no);

Returns a pointer to a TIOS system message (XR string).

XR_stringPtr returns a pointer to the TIOS system message whose number is given in XR_string_no. IDs are not consistent across AMS versions, but since AMS 2.00 they have stayed the same and probably will in the future. They are often used internally, for example dialog structures and EV_sendString use them. All tokens (like "sin" etc.) are also XR strings.


CTypeTable

const unsigned char *CTypeTable;

A pointer to a table describing the types of the AMS characters.

This table contains 256 elements, one for each character.
There are nine different values in this table:
0x00 (0b00000000): characters 0x00-0x0A and 0x0C-0x0D. These characters are not supposed to occur in any string returned by the system, they are not part of the char menu either.

0x40 (0b01000000): characters 0x0B, 0x0E, 0x0F, 0x10-0x2F (system characters + some of the operators), 0x3A-0x3F (colon, semicolon...), 0x40 (at sign), 0x5B-0x5E (brackets...), 0x60, 0x7B-0x7F (braces...), 0x95-0xB4 (maths symbols...), 0xB6-0xBF (maths symbols...), 0xD7, 0xF7. These symbols are used by the pretty print, or available in the char menu (some are incorrect in expressions)...

0x48 (0b01001000): character 0x5F (question mark).

0x4C (0b01001100): characters 0x30-0x39, i.e. numerals.

0x58 (0b01011000): characters 0xDF and 0xFF (�and ).

0x59 (0b01011001): characters 0x61-0x7B, 0xE0-0xEF, 0xF0-0xF6, 0xF8-0xFE. These characters are lowercase letters, accentuated or not.

0x5A (0b01011010): characters 0x41-0x5B, 0xC0-0xCF, 0xD0-0xD6, 0xD8-0xDE. These characters are uppercase letters, accentuated or not.

0x60 (0b01100000): character 0x8C (pi).

0x78 (0b01111000): characters 0x80-0x8B, 0x8D-0x8F, 0x90-0x94, 0xB5 (). These characters are all greek letters (no meaning for the system), without pi (0x60).


To sum up:
bit 0 set means: 'character is a lowercase letter' (type 0x59).

bit 1 set means: 'character is a uppercase letter' (type 0x5A).

(bits 0 and 1 are mutually exclusive).
bit 2 set means: 'character is a numeral' (type 0x4C).

bit 3 set means: 'character is valid in a symbol name' (types 0x00, 0x40 and 0x60 are invalid in symbol names).

bit 4 set means: 'character is valid as starting character for a symbol name' (types 0x48 and 0x4C are invalid as first character in symbol names).

bit 5 set means: 'character is a greek letter' (types 0x60 and 0x78).

bit 6 set means: 'character is printable' (all types except 0x00).

bit 7 is currently unused.


Credits go to Zeljko Juric for the trick used to retrieve the address of that table. This wrapper implements ROM_CALL 442 on any AMS version.


CU_cursorState

AMS 2.00 or higher

signed short CU_cursorState;

Contains the current cursor state (on or off).

CU_cursorState contains TRUE if the cursor is on, otherwise it contains FALSE.
If it is on, this does not mean that it is displayed, but that it is allowed to be displayed.

See also: CU_restore, CU_start, CU_stop


FiftyMsecTick

AMS 2.00 or higher

volatile unsigned long FiftyMsecTick;

A counter incremented by the standard system auto-int 5 routine.

FiftyMsecTick represents the number of times the standard system AUTO_INT_5 routine was executed since the last reset, if FiftyMsecTick was not modified. Indeed, this variable is changed only by a routine called at reset, and by the system routine for auto-int 5.

This variable is a way to measure a delay, without using a system timer with OSFreeTimer, OSRegisterTimer, OSTimerCurVal, OSTimerExpired, and OSTimerRestart.

Note also that unlike all the other system timers, FiftyMsecTick is a countup timer.

Partially emulating FiftyMSecTick on AMS 1.xx is easy with the functions from intr.h. However, to fully emulate the functionality, a memory-resident (TSR) program has to be installed.


OSContrastValue

unsigned char OSContrastValue;

Byte containing the value of the current contrast.

Note that if you change this byte (valid values are 0-15 on HW1 and 0-31 on HW2), the contrast will not be changed. You have to use OSContrastUp and OSContrastDn to actually change the contrast.

See also: OSContrastUp, OSContrastDn, OSContrastAddress


OSOnBreak

AMS 2.00 or higher

unsigned char OSOnBreak;

System variable indicating that the ON key was pressed.
Used by OSCheckBreak, OSClearBreak, OSLinkClose between others.

See also: OSCheckBreak, OSClearBreak


ReleaseDate

const char *const ReleaseDate;

A pointer to a string containing the release date of the AMS.

You might use it in order to determine the AMS version (ReleaseVersion and TIOS_entries are much more interesting in order to do that, though).

See also: ReleaseVersion


ReleaseVersion

const char *const ReleaseVersion;

A pointer to a string containing the AMS version.

You can use it in order to determine the AMS version more precisely than with TIOS_entries (distinguish between AMS 1.01 and 1.05, 2.02 and 2.03, or 2.07, 2.08 and 2.09), because these versions have the same number of ROM_CALLs.

See also: ReleaseDate


BASECODE_PARM_BLOCK

AMS 2.04 or higher

typedef struct {
unsigned short len; /* length of parameter block */
unsigned char releaseVersionMajor; /* Major AMS version */
unsigned char releaseVersionMinor; /* Minor AMS version */
unsigned short releaseDateYear;
unsigned char releaseDateMonth;
unsigned char releaseDateDay;
} BASECODE_PARM_BLOCK;

A structure containing version information about the operating system.

The base code parameter block contains version information about the AMS: the major and minor version number and the date the OS was built.

You can get this information with the following program:

// Return the basecode parameter block as a list.
// Works only on AMS 2.04 and later (returns with an error message on AMS 2.03 and older).

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define SAVE_SCREEN           // Save/Restore LCD Contents
#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 204           // Compile for AMS 2.04 or higher
#define RETURN_VALUE          // Return Pushed Expression

#define NO_CALC_DETECT
#define NO_EXIT_SUPPORT

#include <tigcclib.h>         // Include All Header Files

// Main Function
void _main(void)
{
  const BASECODE_PARM_BLOCK *bpb = EX_getBasecodeParmBlock ();

  push_END_TAG ();

  push_quantum (bpb->releaseDateDay);
  push_quantum (1);
  push_quantum (POSINT_TAG);

  push_quantum (bpb->releaseDateMonth);
  push_quantum (1);
  push_quantum (POSINT_TAG);

  push_quantum (bpb->releaseDateYear);
  push_quantum ((bpb->releaseDateYear)>>8);
  push_quantum (2);
  push_quantum (POSINT_TAG);

  push_quantum (bpb->releaseVersionMinor);
  push_quantum (1);
  push_quantum (POSINT_TAG);

  push_quantum (bpb->releaseVersionMajor);
  push_quantum (1);
  push_quantum (POSINT_TAG);

  push_quantum (bpb->len);
  push_quantum (1);
  push_quantum (POSINT_TAG);
  push_LIST_TAG ();
}

See also: EX_getBasecodeParmBlock, ReleaseDate, ReleaseVersion, LOC_localVersionDate


DEF_QUEUE

typedef struct {
unsigned short Head; /* Offset to the head of the queue */
unsigned short Tail; /* Offset to the tail of the queue */
unsigned short Size; /* Max number of entries in the queue */
unsigned short Used; /* Actual number of entries in the queue */
unsigned short Buffer[];
} DEF_QUEUE;

A structure describing the header of a variable-sized queue.

Note that Buffer[] is a GNU C extension for variable-sized arrays (TIGCC is GNU C). The main usage of DEF_QUEUE structure is when you want to allocate a queue dynamically on the heap (using malloc). The operator sizeof treats variable-sized arrays as zero-length arrays (this is a sense of zero in square brackets). So, the following example ilustrates correct allocating of a queue with 100-byte long buffer on the heap (note that 100-byte long buffer can store 50 entries, because each int entry is 2 bytes long):

DEF_QUEUE *qptr = malloc (sizeof (DEF_QUEUE) + 100);
OSqclear (qptr);
qptr->Size = 50;
OSenqueue (some_data, qptr);

From this example you can see that you need to fill field Size of the queue structure manually.


QUEUE

#define QUEUE(n) struct {unsigned short Head, Tail, Size, Used, Buffer[n/2];}

A structure describing a queue with a buffer.

QUEUE(n) is a structure which describes a queue with an n-byte long buffer. Strictly speaking, QUEUE(n) is not a type but a macro, although it works exactly as a type, so you can treat it as a type. It is useful for definining a queue without dynamic allocation (i.e. without calling malloc), like in the following example:

QUEUE(100) q;
OSqclear (&q);
q.Size = 50;
OSenqueue (some_data, &q);

Note that QUEUE(n) works exactly like a type, so it can be used anywhere where a type name is expected, for example in pointer declarations, and even as the argument of sizeof etc. This is illustrated in the following example:

QUEUE(100) *qptr = malloc (sizeof (QUEUE(100)));
OSqclear (qptr);
qptr->Size = 50;
OSenqueue (some_data, qptr);

See also: DEF_QUEUE


Timer_Callback_t

typedef CALLBACK void (*Timer_Callback_t) (void);

Describes a timer callback function.

Timer_Callback_t describes a timer callback function for OSVRegisterTimer.


Timers

enum Timers {USER1_TIMER = 1, BATT_TIMER = 1, APD_TIMER = 2, LIO_TIMER = 3, CURSOR_TIMER = 4, MISC_TIMER = 5, USER_TIMER = 6, BATTERY_TIMER = 7, BP_TIMER = 8};

An enumeration for describing timer ID numbers.

BATT_TIMER is deprecated, use USER1_TIMER instead.

See the timer functions (OSRegisterTimer etc.) for more info.


Return to the main index