System routines (for accessing system timers, queues, etc.)
| 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
| 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.
| 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.
| 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.
| 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.
| 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!
| 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
| 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
| 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.
| 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.
| 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.
| 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 GCC4TI 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.
| 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
| 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
| 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.
| 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.
| 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.
| 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
| 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
| 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
| 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.
| 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.
| 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.
| void OSClearBreak (void); |
Clears "BREAK key pressed" flag.
OSClearBreak clears "BREAK key pressed" flag. See OSCheckBreak for more info.
| 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
| 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
| 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
| 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
| 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
| 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
| 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
| 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.
| 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
| 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
| 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
| 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) |
Timer 1 seems to be free for use on all AMS versions.
Timer 2 is used for automatic power-down (APD) counting, so this is an official method to change APD rate to, for example, 100 seconds:
OSFreeTimer (APD_TIMER); OSRegisterTimer (APD_TIMER, 100*20);
Timer 3 is used for link communication.
Timer 4 is used for cursor blinking.
Timer 5 is sometimes used for measuring time in some TI-Basic functions like CyclePic.
Timer 6 seems to be free for use on all AMS versions.
Timer 7 is used on AMS 2.04 and above by the standard AUTO_INT_5 routine to launch battery level checking routine every 20 ticks. You shouldn't use it...
Timer 8 is used on AMS 2.07 and above in particular by the functions related to TI-Navigator.
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
| void OSReset (void); |
Resets the calculator.
OSReset resets the calculator without any warnings.
| 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.
| 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.
| 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.
| 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.
| 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...
See also: TIOS_OSVFreeTimer
| 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 precisely, 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). 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 beginning. However, nothing wrong will happen if you try to free
them explicitly (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.
See also: TIOS_OSVRegisterTimer
| 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.
| 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).
| 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).
| short TIOS_OSVFreeTimer (short timer_no); |
Frees an event (vectored) timer.
You really should use OSVFreeTimer, unless
you know what you, and your users, are doing.
This is the direct system call, which will usually take less space in your program than the
library routine for OSVRegisterTimer,
OSVFreeTimer and the corresponding interrupt handler.
If you use it on AMS 1.00-2.03, you'll experience the bugs in TI's implementation (dependence
between notify and event timers, etc.). If you use it on patched versions of AMS embedding an
implementation based on the TIGCC/GCC4TI one, you won't.
See also: OSVFreeTimer
| short TIOS_OSVRegisterTimer (short timer_no, unsigned long T, Timer_Callback_t Action); |
Registers an event (vectored) timer.
You really should use OSVRegisterTimer, unless
you know what you, and your users, are doing.
This is the direct system call, which will usually take less space in your program than the
library routine for OSVRegisterTimer,
OSVFreeTimer and the corresponding interrupt handler.
If you use it on AMS 1.00-2.03, you'll experience the bugs in TI's implementation (dependence
between notify and event timers, etc.). If you use it on patched versions of AMS embedding an
implementation based on the TIGCC/GCC4TI one, you won't.
See also: OSVRegisterTimer
| 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.
| 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.
| 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.
| 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
| 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.
| 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
| unsigned char OSOnBreak; |
System variable indicating that the ON key was pressed.
Used by OSCheckBreak,
OSClearBreak,
OSLinkClose between others.
See also: OSCheckBreak, OSClearBreak
| 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
| 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
typedef struct {
|
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
typedef struct {
|
A structure describing the header of a variable-sized queue.
Note that Buffer[] is a GNU C extension for variable-sized arrays (GCC4TI 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.
| #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
| typedef CALLBACK void (*Timer_Callback_t) (void); |
Describes a timer callback function.
Timer_Callback_t describes a timer callback function for OSVRegisterTimer.
| 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.