GCC4TI Documentation

GCC4TI v0.96 Beta 11 (Library v2.73)

Contents

  • General Information about GCC4TI
  • GCC4TI Library Header Files
  • C Language Keywords
  • C Language Operators and Punctuators
  • GNU C Language Extensions
  • GCC Command Line Options
  • The C Preprocessor
  • The GNU Assembler
  • The A68k Assembler
  • The GCC4TI Linker
  • The GCC4TI Integrated Environment
  • Information for Assembly Programmers
  • Contact Information
  • Copyright Notes
  • History of the Library

How to...

  • How to make a TIGCC/GCC4TI program
  • How to use floating point variables and functions
  • How to make a program returning a value
  • How to use symbolic mathematics and calculus
  • How to break the 64KB limit using a DLL
  • Frequently Asked Questions
  • TICT & TIGCC/GCC4TI Programming Message Board
  • GCC4TI Message Board

Warning: This documentation, although quite complete, is not really a full C tutorial: it is assumed that you already know basic programing in C on any standard computer (PC, Mac, etc.).

This documentation and the library were written by Zeljko Juric and various team members and contributors.


General Information about GCC4TI

GCC4TI is a C/ASM cross compiler for the TI-89, TI-89 Titanium, TI-92 Plus and V200, derived from TIGCC. It is a complex project created by an international team currently led by Patrick Pélissier (PpHd), Lionel Debroux and Manoel Trapier (Godzil). We can contacted by various communication means listed on the GCC4TI website: the GCC4TI mailing list, a forum, tickets (bug reports / feature requests), and an IRC chan.

  • Release Information
  • About GCC4TI
  • Reporting Bugs
  • Documenting Unknown Functions
  • Credits
  • History
  • Disclaimer


Release Information
General Information about GCC4TI Next

  • GCC4TI v0.96 Beta 11 based on the GNU Compiler Collection v4.1.2 and GNU Binutils v2.16.1 compiled under MinGW32 by Lionel Debroux
  • A68k v2.71.F3w by Charlie Gibbs, David Ellsworth, Kevin Kofler, Julien Muchembled, and Paul Froissart
  • ld-tigcc v1.09 by Sebastian Reichelt and Kevin Kofler
  • GCC4TI Library v2.73 by Zeljko Juric and contributors
  • GCC4TI IDE v2.96 and Windows Command Line Executable by Sebastian Reichelt
  • Parameter passing by register Copyright (C) 1998-2003 Fred Fish from Geek Gadgets; converted to GCC 3.0-4.1 by Kevin Kofler
  • Parts from the TI-68k Developer utilities (formerly TIGCC Tools Suite) by the TI-Chess Team (i.e. Thomas Nussbaumer) as well as his grayscale support have been used.
    TIGCC Tools Suite Copyright (C) 2000-2004 Thomas Nussbaumer
  • A slightly more advanced GCC patch was originally made by François Revol (mmu_man).
Get additional files and updates at the Official GCC4TI Site.


About GCC4TI
Previous General Information about GCC4TI Next

The GCC4TI project builds on the TIGCC foundation. We have started the huge task of bugfixing and improving the stagnating and unmaintained TIGCC in various areas.

TIGCC is our attempt to make it possible to program in C for the TI-89 and TI-92 Plus. To do this, we originally recompiled a version of GCC-M68k (which was found here) to make it work with the C calling convention used by TI's compiler. Then we wrote a linker to make it produce .89z or .9xz files. And since we also wanted to allow the use of assembly, we programmed it so that you can use the .asm files and compile them with the A68k assembler. Finally we wrote tigcc, a program which will automatically call the necessary programs to compile everything you specify in the command line. This was the first public release of TIGCC.

At that time, Zeljko Juric (i.e. me, because I am writing this documentation) was quite new in TI community (he bought his TI-89 in July 1999). Although he was a good ASM programmer (in Z80 and 80x86 assembler), he found ASM programming on TI calculators a bit unconfortable, so he started searching for a high-level language compiler for TI-89 (TI-Basic was too slow and somewhat limited). Some compilers were written, but they were quite primitive (one of them was usable anyway: Fargo Pascal, which is transformed later in Ultra Pascal). Then he found a first release of TIGCC...

Some testing proved that it produced quite usable code. But there was a complete lack of library functions. There was just one header file named romcalls.h which was partially usable only for "Doors" programming. Implemented romcalls were possible to use only under the "DoorsOS" kernel. As Zeljko was not a follower nor a lover of the "kernel" concept, he started to think how to use romcalls without any kernels. After a bit of researching, he suceeded to construct a rom-calling macro which worked independently of any kernel, by calling TIOS functions directly.

In the meantime, Xavier stopped the development of the still buggy linker for a while; that was why Niklas Brunlid corrected some of the bugs because he needed TIGCC for his project (Prosit). During this period, Zeljko started to research the (almost completely undocumented) TIOS entry points. He discovered that TIOS itself contains many very useful routines which were usually implemented in various external libraries for kernel-based programming. So the natural decision was to make a library of routines, based exclusively on TIOS entries, which would be usable for both kernel-less and kernel-based programming (and to document everything what was found, of course). This was how the TIGCC Library was founded in the beginning of 2000.

After the release of the TIGCC Library, Xavier started to continue developing TIGCC, so integrating the library as an integral part of TIGCC was the next step. This way Zeljko became a member of TIGCC team. He continued to research the dark, deep, and (previously) unknown parts of the operating system to be able to upgrade the library with new routines. So, at the end of March, version 1.5 of the library was released, with a lot of new functions, and also with floating point support (although it had a few bugs at first).

For a long time, TIGCC was just a command line compiler. Sebastian Reichelt started developing a window-based Integrated Environment for TIGCC in April. First versions of it were quite simple, but later some more advanced options were added to it. In the meantime, Zeljko continued researching and developing. Many people pointed out that the lack of "standard" ANSI C library routines like "fopen" etc. was a big disadvantage of TIGCC, so Zeljko decided to implement them in the TIGCC library. The main problem was the impossibility of creating external archives of library routines (the linker did not support them). Then he discovered a black art of cast constructors which allowed implementing these routines in a quite efficient way, using extremely dirty hacks. The main goal was that the routines which were not used in the program would not be part of the final executable in any way, but if the routines were used, they were supposed to be included only once. This behaviour was implemented successfully, so version 2.0 was released. This release included about 300 new functions compared to the previous release!

Finally, Xavier, Sebastian and Zeljko decided to put everything together and stop distributing various part of TIGCC (compiler, linker, library and environment) independently. Instead, starting from release 0.7, TIGCC contained everything packed in one file. The included library was now release 2.2 (which had stable floating point support, established in release 2.1).

The most important recent change was a complete recompilation of GCC using the sources from the official Cygwin site. This recompilation made it possible to work on the compiler again, which was impossible before because the sources were lost. Native floating point support was implemented by Sebastian in November and December, while Zeljko created the appropriate library functions for this.

When Sebastian Reichelt and Kevin Kofler found and patched a working AmigaOS to COFF converter at the Geek Gadgets site, the linker was not needed as a true linker any more, but rather as a converter from the COFF to the TI executable format. Therefore Julien Muchembled contributed a converter of his own, which was much better than the previous link.

For TIGCC 0.95, Sebastian wrote a new linker, ld-tigcc, which, with Kevin's help, changed TIGCC a lot for the better, allowing to optimize any references between object files at link time, and even to merge constants and reorder sections. It also finally made BSS sections in nostub programs possible. More interesting features are still continuously being added to the linker.

After the TIGCC 0.95 release, the last thing missing from TIGCC was a C debugger. This prompted Kevin to work on integrating GDB into Romain Liévin's TiEmu emulator and adding support for it to TIGCC. The most powerful debugging information format supported by GCC and GDB, DWARF 2, was selected for the debugger.

Although the version you are using now has evolved from a lot of different little updates, it is more or less a complete, working product. Changes are still being made on GCC4TI, though.


Reporting Bugs
Previous General Information about GCC4TI Next

There may still be some bugs in the linker, in tigcc, and in the IDE. If you encounter a bug, please use the ticket system of the Official GCC4TI Site, or send all the information that is needed to the GCC4TI mailing listr.


Documenting Unknown Functions
Previous General Information about GCC4TI Next

The GCC4TI Library still contains a lot of unknown functions. They are defined in unknown.h. For some of them, prototypes are already available; some are even partially documented. Others are completely unknown.

If you have information about one of these functions (also from TI's documentation, but you may not simply copy the information there for copyright reasons), please take the time to document it. The way to do this is rather simple, and you will be doing everyone using this library a big favor.

At first, you need the GCC4TI source code, available from the GCC4TI Website. Set up the documentation system according to the Readme and HelpSystem.ini files, and check whether you can update at least the header files by running UpdateInclude.exe.

To document a file, or to change the file's prototype, you simply need to edit the appropriate .hsf file in the unknown.h subfolder of the help system. If you have enough documentation to move it to another header file, simply move the .hsf file to the appropriate folder, and update all links from and to the file. (For links from other files to this one, you will probably want to use a string replacement program to make the conversion automatically.) Then run UpdateInclude.exe on both the new folder and on unknown.h (if it used to be in unknown.h). Now you will be able to view your documentation in a web browser, and test the function with its new prototype.

When you are finished, please simply send the resulting .hsf file to the GCC4TI mailing list. We prefer compressed files because mail systems sometimes mess up attached text files, but it doesn't really matter a lot.

NOTE: in order to reduce hazards of work duplication, you should first contact us on the ML to inform people that you'd like to work on such or such area ;-)


Credits
Previous General Information about GCC4TI Next

These are the people we would like to thank for their contributions to TIGCC and GCC4TI:

  • Thomas Nussbaumer (website), for his grayscale 'port' from Universal OS, and for the TI-68k Developer Utilities (formerly TIGCC Tools Suite), available on tict.ticalc.org
  • François Revol, for his help on GCC-related issues
  • John David Ratliff (website), for his tutorials and for the CGI script for the bug report form
  • Peter J. Rowe, for correcting grammar and spelling mistakes in a large part of the documentation
  • Gereon Kindler, for the title and wizard images and the new icons in the IDE
  • Jocelyn Berrendonner, for his immense work on menus.h, dialogs.h and files.h, and for some other TIGCCLIB updates
  • Romain Liévin (website), for the Linux port, the (now outdated) document about the internals of TIGCC, and work on the documentation
  • Lionel Debroux (website), for documenting AMS 2.xx functions from unknown.h and multiple optimizations
  • Samuel Stearley, for most of the home screen functions defined in homescr.h
  • Olivier Armand, for an improved internal Line 1111 emulator
  • Greg Dietsche, for a lot of updates to stdio.h
  • Joel Thompson, for extracting the examples from the documentation, and for some other updates (e.g. to gdraw.h and vat.h)
  • Daniel De Graaf, for updates to gdraw.h and estack.h
  • Ephyx, for the IDE code completion patches and other IDE improvements
  • Sébastien Leurent, for his improvements to Wazabbe's dialogs.h
  • Patrick Pélissier, for linker-related patches, bug reports and multiple other improvements (build system, etc.)
  • Manoel Trapier, for providing project management infrastructure, a68k MacOS X binaries portability, etc.
  • Martial Demolins, for multiple optimizations and bug reports
  • Joseph (Joey) Adams, for improving the existing sprite routines, creating new ones and creating a strong test program


History
Previous General Information about GCC4TI Next

Note: Click here for the history of the library, or here for the history of the IDE.

?? ??, ??: GCC4TI v0.96 Beta 11, ld-tigcc v1.09, Library v2.73, IDE v2.96

  • Added: documentation: merged several long-standing contributions, added brand-new ones.
  • Added: imported dasm-tigcc to a public repository, fixed a bug and upgraded some files. dasm-tigcc is a GPL'ed improved replacement of ttdasm, which uses the GDB disassembler and modified chunks of code from libti* & TIEmu. Creator: Kevin Kofler.
  • Bugfix: tigcclib: fix bsearch() while making it smaller.
  • Improved: tigcclib: make qsort() faster, especially for large arrays, and significantly smaller.
  • Added: testcases: new area for complex tests, with a test for sorting routines.
  • Bugfix: tigcclib: switch sprite routines to explicit register parameters.
  • Added: tigcclib: generic clipped sprite 8/16/32 routines.
June 27, 2009: GCC4TI v0.96 Beta 10, ld-tigcc v1.09, Library v2.72, IDE v2.96
  • Bugfix: IDEs: add more instructions to the default lists used for syntax coloring.
  • Added: import most of the TI-68k Developer Utilities' "pctools" (formerly TIGCC Tools Suite) where they belong.
  • Added: documentation: merged several long-standing contributions.
  • Updated: pstarter: removed the essentially unused shrnklib support; optimized the ttunpack-fast code by applying the same calling convention changes as those applied in the ttunpack code (saves about 34 bytes, i.e. > 2%).
  • Improved: tprbuilder: return a nonzero exit code if a command run by tprbuilder returned a nonzero exit code.
  • Bugfix: examples: fix an example whose build has failed since an untested modification performed in 2005...
  • Added: examples: scripts to check buildability (with tprbuilder) of the examples.
  • Bugfix: gcc: fix a 64-bit compatibility problem in the AMS float support (patch applied on top of GCC), which triggered harmless warnings in the generated assembly code.
  • Greatly improved: build scripts ("canadian cross"-compilation support, more traces, better portability, improved packaging, etc.). Most improvements were developed by Lionel Debroux and Patrick Pélissier.
  • Bugfix: tigcc: fix the build of the Custom DLL example by adding "-n" when invoking ld-tigcc to generate the decompressor+launcher.
  • Bugfix: examples: rename a number of examples to avoid on-calc name clashes.
  • Updated: a number of size optimizations in TIGCCLIB, one of which touches the very commonly used SAVE_SCREEN startup code. Most optimizations were developed by Martial Demolins.
  • Updated: history files and READMEs.
January 3, 2009: GCC4TI v0.96 Beta 9, ld-tigcc v1.08, Library v2.71, IDE v2.95
  • Bugfix: IDEs: add various instructions and macros to the default lists used for syntax coloring.
  • Bugfix: Fix gcc.exe for Vista (GCC 4.1.2-tigcc-pre10).
  • Updated: Patched GCC 4.1.2 (release) and GNU as 2.16.1 with the TIGCC patch.
  • Bugfix: ld-tigcc: fix warning and runtime abort with _FORTIFY_SOURCE.
  • Bugfix: ld-tigcc: adjust TargetDistance after return optimization (fixes bra.s +0 in SIDE).
  • Bugfix: tprbuilder: fix buffer overflow in MIN_AMS handling.
  • Bugfix: documentation: various tweaks and fixes.
  • Bugfix: include & library: various tweaks and fixes.
  • Added: ld-tigcc: integrate PuCrunch compression, add --pack switch.
  • Added: ld-tigcc: implement --output-data-var switch (allows specifying the on-computer file name for the data variable).
  • Added: ld-tigcc: better handling of on-calc variable names.
  • Bugfix: ld-tigcc: ignore "relative reloc to symbol in different section" error in the ".deleted" section. This fixes --remove-unused with debugging information and -freg-relative-an.
  • Bugfix: ld-tigcc: seek back to the end after FlashOS relocation so the dummy signature ends up at the end and not the place of the last relocation in the standalone version.
  • Updated: documentation tools: replace Delphi DumpSections with equivalent shell script, Port ConvertTexi from Delphi to C++ with Qt 4.
  • Bugfix: ld-tigcc: fix "relative reloc at `0xnnn' to `foo' in different section" errors when using --remove-unused with debugging information and relocated ROM_CALLs, RAM_CALLs or library calls.
  • Added: start the GCC4TI fork of TIGCC, with a different decision scheme.
  • Added: ld-tigcc: support for Flash OS timestamps.
  • Added: tigcclib: Flash OS library (flashos.a).
  • Added: includes: stdint.h and a partial inttypes.h (the platform's vcbprintf doesn't support 64-bit integers anyway).
  • Added: ld-tigcc: add implementation and documentation of special __ld_bss_even_end symbol.
  • Updated: Delphi IDE: restore VTI support in addition to TIEmu support, as requested by multiple experienced TI-68k programmers for two years.
  • Bugfix: ld-tigcc: compilation fix.
October 31, 2006: TIGCC v0.96 Beta 8, ld-tigcc v1.07, Library v2.7, IDE v2.94
  • Added: A new installer for the Win32 release, based on NSIS.
  • Updated: Many documentation and library updates, see the TIGCCLIB history for details.
  • Added: A completely new ExePack (PPG) launcher, with an almost halved size.
  • Added: Support for reordering of startup sections (sharing the same startup number) in the linker.
  • Added: Support for Mlink-format relocs (MLINK_FORMAT_RELOCS, MLINK_FORMAT_BSS, MLINK_FORMAT_ROM_CALLS, MLINK_FORMAT_DATA_VAR).
  • Added: Support for debugging information in DWARF 2 format (to be used with a GDB-enabled TiEmu), including some toolchain bugfixes required to support this feature.
  • Added: Support for the new _nostub comment specification 1.01 and its new COMMENT_AUTHORS entry.
  • Updated: Patched GCC 4.1.2 (prerelease) and GNU as 2.16.1 with the TIGCC patch.
  • Bugfix: References in assembly code with an explicitly-coded size are now marked unoptimizable in order to make the linker honor the explicit size as well, not just the assembler.
  • Bugfix: tprbuilder doesn't crash on long tigcc.exe command lines under Windows 9x/Me anymore.
  • Bugfix: ld-tigcc doesn't try to range-cut in files compiled without range-cutting support (in programs containing files compiled both with and without range-cutting support) anymore.
  • Bugfix: Removing unused sections in ld-tigcc now really removes all unused sections.
  • Bugfix: Uninitialized static or global variables are now always emitted to the expected section by GCC.
  • Updated: Bugfixes and improvements to external data variable support.
  • Bugfix: Fixed a segfault during constant-merging in ld-tigcc.
  • Bugfix: Fixed invalid kernel ROM_CALL or RAM_CALL tables emitted by ld-tigcc when unused section removal optimized all ROM or RAM_CALLs away.
  • Bugfix: A68k doesn't crash on EQUs doing arithmetic with other EQUs which do arithmetic with undefined symbols anymore, this invalid code now gives a proper error message.
  • Bugfix: Fixed -v and -v0 being limited to 255 characters in the Windows command-line compiler.
  • Added: The command-line compiler now supports -isystem properly.
  • Bugfix: Fixed compilation problems on *BSD and Mac OS X.
  • Added: The standalone version of ld-tigcc supports a new --outputbin-main-only switch to be used by KTIGCC.
  • Updated: ExePack compression support is now Free Software.
  • Updated: On Windows, MSVCRT.DLL is now required. This DLL comes with all Windows versions since Windows 95 OSR 2. For the original Windows 95, it is usually installed by Internet Explorer or Microsoft Office.
  • Bugfix: Fixed *nix install script not to attempt symlinking os.h to OS.h on case-insensitive file systems.
  • Bugfix: Fixed external data variable support for compressed programs in the *nix command-line compiler.
  • Bugfix: Fixed multiple uses of -Wa or -WA in the *nix command-line compiler.
  • Updated: The IDE now supports TiEmu (20061030 or later) instead of VTI for debugging/testing.
October 24, 2004: TIGCC v0.95, ld-tigcc v1.06, Library v2.6, IDE v2.92
  • Added: An entirely new linker, as a basis for all other improvements (see Advanced Options of TIGCC).
  • Added: Support for dynamic BSS sections in nostub mode.
  • Added: Linker-side code optimization.
  • Added: Support for data variables.
  • Added: Support for contructors and destructors.
  • Added: Experimental optional Fargo II support.
  • Updated: Patched GCC 3.3.1 with the TIGCC patch.
  • Updated: Updated PPG launcher created by the TI-Chess Team.
  • Added: Basic TI-89 Titanium support.
January 24, 2003: TIGCC v0.94 SP4, Obj2TI v1.01e, Library v2.5 SP4, IDE v2.91
  • Bugfix: Fixed ER_throw bug with 4-digit error numbers.
  • Bugfix: Fixed bug in ENABLE_ERROR_RETURN with MIN_AMS values of 200 or higher.
  • Bugfix: Removed the rejection of a minimum AMS version of 2.07.
January 13, 2003: TIGCC v0.94 SP3, Obj2TI v1.01e, Library v2.5 SP3, IDE v2.91
  • Bugfix: Incorporated a fix for fclose.
January 12, 2003: TIGCC v0.94 SP2, Obj2TI v1.01e, Library v2.5 SP2, IDE v2.91
  • Bugfix: Important bugfixes for fopen, fread and fwrite.
  • Bugfix: Changed import_binary to export the symbol, and changed the IDE to make it work with it.
December 30, 2002: TIGCC v0.94 SP1, Obj2TI v1.01e, Library v2.5 SP1, IDE v2.91
  • Bugfix: Fixed SET_FILE_IN_USE_BIT.
  • Bugfix: Fixed the prototype of MD5Update.
December 21, 2002: TIGCC v0.94, Obj2TI v1.01e, Library v2.5, IDE v2.91
  • Updated: Patched GCC 3.2.1 with the TIGCC patch, with a lot of modifications.
  • Updated: Greatly changed the internal structure of the library.
  • Added: Applied a patch for argument passing through registers.
  • Added: Implemented F-Line ROM Calls.
  • Added: Implemented support for PreOS libraries in obj2ti.
  • Bugfix: Repaired the '-freg-relative-reg' option.
  • Updated: Created an option to ignore system folders in the setup program.
  • Added: Finally wrote a program to update the version numbers in all places.
  • Updated: Enhanced the help file tools to generate the header files as well.
  • Added: Added tools to edit the help system files.
  • Added: Implemented HTML checking for help system files.
  • Added: Added a switch to tigcc to create archives.
  • Updated: Made tigcc look for archives in the 'Lib' subfolder of the installation.
  • Updated: Repaired some bugs to support debugging switches like '-ggdb'.
  • Updated: Recompiled all programs under MinGW32, thereby removing the need to use Cygwin.
  • Updated: Compressed setup program using UPX.
  • Added: Added "See Also" links to the help system.
  • Added: Extracted all examples from the documentation, with a lot of help from Joel Thompson.
  • Added: Added support for nostub libraries.
  • Added: Added missing long long operator support.
February 3, 2002: TIGCC v0.93, Obj2TI v1.01, Library v2.41, IDE v2.9
  • Updated: A lot of updates in the IDE.
  • Updated: Completely redesigned the documentation.
  • Updated: Peter J. Rowe corrected grammar and spelling mistakes in a large part of the doc.
  • Added: Allowed the use of paths for files compiled with tigcc.
  • Bugfix: Fixed a problem with linking multiple A68k files.
  • Added: Added the '-WA,...' option to pass switches to a68k.
  • Bugfix: Cleaned up the whole patch code, including the support for exit and atexit. Fixes were developed by Patrick Pélissier, Kevin Kofler, and Stephan Effelsberg.
  • Bugfix: Used an updated version of the ExePack launcher by Thomas Nussbaumer, with fixes contributed by Olivier Armand and Kevin Kofler.
  • Bugfix: Small fixes in the GNU and A68k assemblers.
  • Updated: Changed the setup program to only overwrite the files that were really changed.
November 25, 2001: TIGCC v0.92 SP2, Obj2TI v1.01, Library v2.4 SP1, IDE v2.8 SP4
  • Updated: Applied the TIGCC patch to GCC 3.0.2.
  • Bugfix: Fixed a bug which made uninitialized global variables slower and larger.
  • Added: Automated the setup creation process to shorten release cycles.
  • Updated: Detected Windows NT in setup.
November 9, 2001: TIGCC v0.92 SP1, Obj2TI v1.01, Library v2.4 SP1, IDE v2.8 SP3
  • Bugfix: Fixed the problem in obj2ti with uninitialized global variables in kernel mode.
  • Bugfix: Fixed the A68k integration problem (in objcopy) which prevented RAM calls from being used in 16-bit addressing mode.
  • Bugfix: Fixed the IDE bug which made closing large files really slow.
  • Added: In the IDE, it is now possible to switch between files quickly using Ctrl+Tab.
  • Updated: The program decompressor is stored as an object file now, instead of an assembly file; this removes the need to run the assembler for compression.
  • Updated: Greatly updated the setup program to prevent legal problems.
September 29, 2001: TIGCC v0.92, Obj2TI v1.0, Library v2.4 SP1, IDE v2.8 SP2
  • Updated: Applied the TIGCC patch to GCC 3.0, which introduces some optimizations and more warnings.
  • Updated: Replaced Xavier's linker with new obj2ti by Julien Muchembled.
  • Added: Added an AmigaOS to COFF converter for A68k programs. This allows for seamless A68k integration in TIGCC.
  • Updated: Included new 32-bit version of A68k by Kevin Kofler.
  • Updated: Implemented floating point constant folding. The floating point system can now be used the same way as on any other machine.
  • Added: The '-Wl,...' and '-Wa,...' options are now available in the command line compiler. This means that you can pass options to the GNU assembler and GNU linker.
May 1, 2001: TIGCC v0.91 SP1, Link v1.2, Library v2.4 SP1, IDE v2.8 SP1
  • Bugfix: Kernel support is fixed.
  • Bugfix: Support for exit and atexit is clean now. Thanks to Julien Muchembled for the information.
  • Added: A short credits list is now included in the documentation.
  • Updated: Little maintainance updates in the IDE had to be made.
  • Updated: A few minor bugfixes were also necessary.
March 24, 2001: TIGCC v0.91, Link v1.2, Library v2.4, IDE v2.8
  • Added: Support for multiple files is now stable since the GNU linker is used.
  • Added: Archives (extension .a) are now supported. A file tigcc.a has been created, which is included automatically in all projects.
  • Added: Important debug information is now included in the .s file(s) if a program is compiled with the '-g' switch or with the corresponding option in the IDE.
  • Added: Support for binary values (0b...) has been implemented, but its use is strongly deprecated for portability reasons.
  • Updated: Various updates in the IDE have been made.
December 18, 2000: TIGCC v0.9, Link v1.2, Library v2.3, IDE v2.71
  • Updated: Fixed various bugs in the compiler.
  • Added: Implemented native floating point support.
  • Updated: The IDE and tigcc now include the necessary patches automatically.
  • Bugfix: GCC now works around the uninitialized data bug if the '-mmlink' switch is not used. This makes programs larger, but it is possible not to initialize data and still compile the program correctly until the bug is fixed.
  • Added: The compiler now accepts the switches '-mpcrel', '-mlong', '-mno-tios', and '-mmlink'.
  • Updated: tigcc now accepts the '-bsr' switch for using bsr code where possible, the '-pack' switch for compression, and 'v' as well as '-v0'.
  • Updated: Made some additions and fixes in the IDE and the library.
  • Updated: Changed the directory structure again, since the previous one didn't really make sense any more.
October 11, 2000: TIGCC v0.8, Link v1.2, Library v2.22, IDE v2.7
  • Updated: Recompiled GCC using the latest tools and sources.
  • Updated: Included latest versions of the IDE and the Library.
June 26, 2000: TIGCC v0.7, Link v1.2, Library v2.0, IDE v2.6
  • Updated: The linker now supports EXTRA_RAM_TABLE symbols.
  • Updated: The linker accepts a new switch: '-outputbin' will make it output the raw executable file as it is on the calculator. Of course this '.bin' file can not be transferred to the calculator.
  • Updated: The linker will display the compiled file size even with the quiet switch '-q' enabled.
  • Updated: Included library is TIGCCLIB 2.0.
  • Added: Included TIGCC IDE by Sebastian Reichelt.
  • Updated: The directory structure has been completely changed and is now clearer.
  • Updated: The installation is a lot easier thanks to Sebastian Reichelt's setup program.
April 6, 2000: TIGCC v0.65, Link v1.1, Library v1.5
  • Bugfix: sometimes some weird characters were appended to the file name and it wasn't compiled.
  • Updated: TIGCCLIB is now version 1.5.
Februar 5, 2000: TIGCC v0.6, Link v1.1, Library v1.1
  • Added: The library tigcclib by Zeljko Juric is added in the package.
  • The source of tigccins (the installation program) is included in the distribution.
  • Bugfix: Libraries are now compiled correctly (there was a strange bug before).
  • Bugfix: Linking multiple object files now seems to work perfectly (mail Xavier Vassor if you find a bug).
  • link, tigcc, tigccins are now 32-bit console programs (instead of 16-bit DOS programs)
September 26, 1999: TIGCC v0.51, Link v1.01
  • Bugfix: C symbols that where exported out-of-order by GCC (i.e. library@0000, library@0002, library@0001...) are now inserted properly in the .89z/.9xz file. This will make it possibe to write libraries in C the way it should be done.
  • Bugfix: The _comment symbol is now properly recognized in both C and assembly programs. Added: Both tigcc and link now have the '-q' option for quiet assembling or compilation. Does not affect warnings and errors.
  • The source of link and tigcc is included in the distribution.
July 16, 1999: TIGCC v0.5, Link v1.0
  • Initial release.


Disclaimer
Previous General Information about GCC4TI

Original files Copyright (C) 1999-2005 Xavier Vassor, Niklas Brunlid, and Jean Canazzi
ld-tigcc Copyright (C) 2002-2008 Sebastian Reichelt and Kevin Kofler
Library & Documentation Copyright (C) 2000-2007 Zeljko Juric and contributors
IDE Copyright (C) 2000-2007 Sebastian Reichelt and contributors
TI-68k Developer Utilities (formerly TIGCC Tools Suite) Copyright (C) 2000-2009 Thomas Nussbaumer (TI-Chess Team)

Included programs with different licenses:
A68k Copyright (C) 1987-2005 Charlie Gibbs, David Ellsworth, Kevin Kofler, Julien Muchembled, and Paul Froissart

Some parts of the GCC4TI package are parts of the GNU C compiler package. Like the rest of GCC4TI, these parts are free software; you can redistribute them and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.


C Language Keywords

Standard ANSI C recognizes the following keywords:

auto
break
case
char
const
continue
default
do
double
else
enum
extern
float
for
goto
if
int
long
register
return
short
signed
sizeof
static
struct
switch
typedef
union
unsigned
void
volatile
while

In addition to these standard keywords, GCC4TI recognizes some extended keywords which do not exist in ANSI C, like asm, typeof, inline, etc., which are described in details in the section GNU C language extensions. This section also describes extensions to standard keywords, not only new ones.

Note: If square brackets '[...]' are used in syntax descriptions, they mean optional arguments (as usual in syntax-describing languages), not square brackets as literals.


auto

auto Keyword
Keyword Index

Defines a local variable as having a local lifetime.

Keyword auto uses the following syntax:

[auto] data-definition;
As the local lifetime is the default for local variables, auto keyword is extremely rarely used.

Note: GNU C extends auto keyword to allow forward declaration of nested functions.


break

break Keyword
Keyword Index

Passes control out of the compound statement.

The break statement causes control to pass to the statement following the innermost enclosing while, do, for, or switch statement. The syntax is simply

break;


switch, case, default

switch, case, default Keywords
Keyword Index

Branches control.

switch causes control to branch to one of a list of possible statements in the block of statements. The syntax is

switch (expression) statement
The statement statement is typically a compound statement (i.e. a block of statements enclosed in braces). The branched-to statement is determined by evaluating expression, which must return an integral type. The list of possible branch points within statement is determined by preceding substatements with
case constant-expression :
where constant-expression must be an int and must be unique.

Once a value is computed for expression, the list of possible constant-expression values determined from all case statements is searched for a match. If a match is found, execution continues after the matching case statement and continues until a break statement is encountered or the end of statement is reached. If a match is not found and this statement prefix is found within statement,
default :
execution continues at this point. Otherwise, statement is skipped entirely. For example,
switch (operand)
  {
    case MULTIPLY:
      x *= y; break;
    case DIVIDE:
      x /= y; break;
    case ADD:
      x += y; break;
    case SUBTRACT:
      x -= y; break;
    case INCREMENT2:
      x++;
    case INCREMENT1:
      x++; break;
    case EXPONENT:
    case ROOT:
    case MOD:
      printf ("Not implemented!\n");
      break;
    default:
      printf("Bug!\n");
      exit(1);
  }
See also break.

Note: GNU C extends the case keyword to allow case ranges.


int, char

int, char Keywords
Keyword Index

Basic data types (integer and character).

Variables of type int are one machine-type word in length. They can be signed (default) or unsigned, which means that in this configuration of the compiler they have by default a range of -32768 to 32767 and 0 to 65535 respectively, but this default may be changed if the compiler option '-mnoshort' is given. In this case, the range of type int is -2147483648 to 2147483647 for signed case, or 0 to 4294967295 for unsigned case. See also short and long type modifiers.

Variables of type char are 1 byte in length. They can be signed (this is the default, unless you use the compiler option '-funsigned-char') or unsigned, which means they have a range of -128 to 127 and 0 to 255, respectively.

All data types may be used for defining variables, specifying return types of functions, and specifying types of function arguments. For example,

int a, b, c;                       // 'a', 'b', 'c' are integer variables
int func ();                       // 'func' is a function returning int
char crypt (int key, char value);  // 'crypt' is a function returning char with
                                   // two args: 'key' is int and 'value' is char
When function return type is omitted, int is assumed.

All data type keywords may be used in combination with asterisks, brackets and parentheses, for making complex data types, like pointer types, array types, function types, or combinations of them, which in the C language may have an arbitrary level of complexity (see asterisk for more info).


const

const Keyword
Keyword Index

Makes variable value or pointer parameter unmodifiable.

When const is used with a variable, it uses the following syntax:

const variable-name [ = value];
In this case, the const modifier allows you to assign an initial value to a variable that cannot later be changed by the program. For example,
const my_age = 32;
Any assignments to 'my_age' will result in a compiler error. However, such declaration is quite different than using
#define my_age 32
In the first case, the compiler allocates a memory for 'my_age' and stores the initial value 32 there, but it will not allow any later assignment to this variable. But, in the second case, all occurences of 'my_age' are simply replaced with 32 by the preprocessor, and no memory will be allocated for it.

Warning: a const variable can be indirectly modified by a pointer, as in the following example:
*(int*)&my_age = 35;
When the const modifier is used with a pointer parameter in a function's parameter list, it uses the following syntax:
function-name (const type *var-name)
Then, the function cannot modify the variable that the pointer points to. For example,
int printf (const char *format, ...);
Here the printf function is prevented from modifying the format string.


continue

continue Keyword
Keyword Index

Passes control to the begining of the loop.

continue causes control to pass to the end of the innermost enclosing while, do, or for statement, at which point the loop continuation condition is re-evaluated. The syntax is simply

continue;
For example,
for (i = 0; i < 20; i++)
  {
    if (array[i] == 0)
      continue;
    array[i] = 1/array[i];
  }
This example changes each element in the array with its reciprocal, but skips elements which are equal to zero.


do

do Keyword
Keyword Index

Do-while loop.

Keyword do is usually used together with while to make another form of repeating statement. Such form of the loop uses the following syntax:

do statement while (expression)
statement, which is usually a compound statement, is executed repeatedly as long as the value of expression remains non-zero. The test takes place after each execution of the statement. For example,
i = 1; n = 1;
do
  {
    n *= i;
    i++;
  } while (i <= factorial);


float, double

float, double Keywords
Keyword Index

Floating point data types.

The keyword float usually represents a single precision floating point data type, and double represents a double precision floating point data type. In GCC4TI, both float and double (and even long double) are the same. The TI-68k calculators running AMS or compatible use a non-IEEE floating point format called SMAP II BCD for floating point values.

These values have a range from 1e-999 to 9.999999999999999e999 in magnitude, with a precision of exactly 16 significant digits. Principally, the exponent range may be as high as 16383, but most math routines do not accept exponents greater than 999.


if, else

if, else Keywords
Keyword Index

Conditional statement.

Keyword if is used for conditional execution. The basic form of if uses the following syntax:

if (expression)
   statement1
Alternatively, if may be used together with else, using the following syntax:
if (expression)
   statement1
else
   statement2
If expression is nonzero when evaluated, then statement1 is executed. In the second case, statement2 is executed if the expression is 0.

An optional else can follow an if statement, but no statements can come between an if statement and an else. Of course, both statement1 and statement2 may be compound statements (i.e. a sequence of statements enclosed in braces). Here will be given some legal examples:
if (count < 50) count++;

if (x < y) z = x;
else z = y;

if (x < y)
  {
    printf ("x is smaller");
    return x;
  }
else
  {
    printf ("x is greater")
    return y;
  }
The #if and #else preprocessor statements look similar to the if and else statements, but have very different effects. They control which source file lines are compiled and which are ignored.


enum

enum Keyword
Keyword Index

Defines a set of constants of type int.

The syntax for defining constants using enum is

enum [tag] {name [=value], ...};
The set can optionally be given a type tag name with tag. name is the name of a constant that can optionally be assigned the (constant) value of value, etc. For example,
enum Numbers {One = 1, Two = 2, Three = 3, Four = 4, Five = 5};
If value is missing, then a value is assumed to be the value of the previous constant in the list + 1. If this is the first constant in the list, the default value is 0.

If you give a type tag name, then you can declare variables of enumerated type using
enum tag variable-names;
For example,
enum Numbers x, y, z;
declares three variables x, y and z, all of type Numbers (they are, in fact, integer variables). More precise, 'enum tag' becomes a new type which is equal in rights with any built-in type.


extern

extern Keyword
Keyword Index

Indicates that an identifier is defined elsewhere.

Keyword extern indicates that the actual storage and initial value of a variable, or body of a function, is defined elsewhere, usually in a separate source code module. So, it may be applied to data definitions and function prototypes:

extern data-definition;
extern function-prototype;
For example,
extern int _fmode;
extern void Factorial (int n);
The keyword extern is optional (i.e. default) for a function prototype.


for

for Keyword
Keyword Index

For loop.

For-loop is yet another kind of loop. It uses for keyword, with the following syntax:

for ([expr1]; [expr2]; [expr3]) statement
statement is executed repeatedly until the value of expr2 is 0. Before the first iteration, expr1 is evaluated. This is usually used to initialize variables for the loop. After each iteration of the loop, expr3 is evaluated. This is usually used to increment a loop counter. In fact, the for-loop is absolutely equivalent to the following sequence of statements:
expr1;
while (expr2)
  {
    statement;
    expr3;
  }
That's why expr1 and expr3 must contain side effects, else they are useless. For example,
for (i=0; i<100; i++) sum += x[i];

for (i=0, t=string; i<40 && *t; i++, t++) putch(*t);
putch('\n');

for (i=0, sum=0, sumsq=0, i<100; i++)
  {
    sum += i; sumsq += i*i;
  }
All the expressions are optional. If expr2 is left out, it is assumed to be 1. statement may be a compound statement as well.


goto

goto Keyword
Keyword Index

Unconditionally transfer control.

goto may be used for transfering control from one place to another. The syntax is:

goto identifier;
Control is unconditionally transferred to the location of a local label specified by identifier. For example,
Again:
  ...
  goto Again;
Jumping out of scope (for example out of the body of the for loop) is legal, but jumping into a scope (for example from one function to another) is not allowed.

Note: The GNU C extends the usage of goto keyword to allow computed goto. Also, it supports local labels, useful in macro definitions.


short, long, signed, unsigned

short, long, signed, unsigned Keywords
Keyword Index

Type modifiers.

A type modifier alters the meaning of the base type to yield a new type. Each of these type modifiers can be applied to the base type int. The modifiers signed and unsigned can be applied to the base type char. In addition, long can be applied to double.

When the base type is omitted from a declaration, int is assumed. For example,

long x;                 // 'int' is implied
unsigned char ch;
signed int i;           // 'signed' is default
unsigned long int l;    // 'int' is accepted, but not needed
In this implementation of the compiler, the valid range of valid data types is as listed in the following table:
short int              -32768 to 32767
long int               -2147483648 to 2147483647
signed char            -128 to 127
signed int             -32768 to 32767 (signed is default)
                       [or -2147483648 to 2147483647 if '-mnoshort' is given]
signed short int       -32768 to 32767
signed long int        -2147483648 to 2147483647
unsigned char          0 to 255
unsigned int           0 to 65535
                       [or 0 to 4294967295 if '-mnoshort' is given]
unsigned short int     0 to 65535
unsigned long int      0 to 4294967295
Note: GNU C extends the long keyword to allow double-long integers (64-bit integers in this implementation), so they have range from -9223372036854775808 to 9223372036854775807 if signed, or from 0 to 18446744073709551615 if unsigned.


register

register Keyword
Keyword Index

Tells the compiler to store the variable being declared in a CPU register.

In standard C dialects, keyword auto uses the following syntax:

register data-definition;
The register type modifier tells the compiler to store the variable being declared in a CPU register (if possible), to optimize access. For example,
register int i;
Note that GCC4TI will automatically store often used variables in CPU registers when the optimization is turned on, but the keyword register will force storing in registers even if the optimization is turned off. However, the request for storing data in registers may be denied, if the compiler concludes that there is not enough free registers for use at this place.

Note: The GNU C extends the usage of register keyword to allow explicitely choosing of used registers.


return

return Keyword
Keyword Index

Exits the function.

return exits immediately from the currently executing function to the calling routine, optionally returning a value. The syntax is:

return [expression];
For example,
int sqr (int x)
{
  return (x*x);
}


sizeof

sizeof Keyword
Keyword Index

Returns the size of the expression or type.

Keyword sizeof is, in fact, an operator. It returns the size, in bytes, of the given expression or type (as type size_t). Its argument may be an expression of a type name:

sizeof expression
sizeof (type)
For example,
workspace = calloc (100, sizeof (int));
memset(buff, 0, sizeof buff);
nitems = sizeof (table) / sizeof (table[0]);
Note that type may be an anonymous type (see asterisk for more info about anonymous types).


static

static Keyword
Keyword Index

Preserves variable value to survive after its scope ends.

Keyword static may be applied to both data and function definitions:

static data-definition;
static function-definition;
For example,
static int i = 10;
static void PrintCR (void) { putc ('\n'); }
static tells that a function or data element is only known within the scope of the current compile. In addition, if you use the static keyword with a variable that is local to a function, it allows the last value of the variable to be preserved between successive calls to that function.

Note that the initialization of automatic and static variables is quite different. Automatic variables (local variables are automatic by default, except you explicitely use static keyword) are initialized during the run-time, so the initialization will be executed whenever it is encountered in the program. Static (and global) variables are initialized during the compile-time, so the initial values will simply be embeded in the executable file itself. If you change them, they will retain changed in the file. By default, the C language proposes that all uninitialized static variables are initialized to zero.

The fact that global and static variables are initialized in compile-time and kept in the executable file itself has one serious consequence, which is not present on "standard" computers like PC, Mac, etc. Namely, these computers always reload the executable on each start from an external memory device (disk), but this is not the case on TI. So, if you have the following global (or static) variable
int a = 10;
and if you change its value somewhere in the program to 20 (for example), its initial value will be 20 (not 10) on the next program start! Note that this is true only for global and static variables. To force reinitializing, you must put explicitely something like
a = 10;
at the begining of the main program!

Note, however, that if the program is archived, the initial values will be restored each time you run the program, because archived programs are reloaded from the archive memory to the RAM on each start, similarly like the programs are reloaded from disks on "standard" computers each time when you start them.


struct

struct Keyword
Keyword Index

Groups variables into a single record.

The syntax for defining records is:

struct [struct-type-name]
  {
    [type variable-names] ;
    ...
  } [structure-variables] ;
A struct, like an union, groups variables into a single record. The struct-type-name is an optional tag name that refers to the structure type. The structure-variables are the data definitions, and are also optional. Though both are optional, one of the two must appear.

Elements in the record are defined by naming a type, followed by variable-names separated by commas. Different variable types can be separated by a semicolon. For example,
struct my_struct
  {
    char name[80], phone_number[80];
    int age, height;
  } my_friend;
declares a record variable my_friend containing two strings (name and phone_number) and two integers (age and height). To declare additional variables of the same type, you use the keyword struct followed by the struct-type-name, followed by the variable names. For example,
struct my_struct my_friends[100];
declares an array named my_friends which components are records. In fact, 'struct my_struct' becomes a new type which is equal in rights with any built-in type.

To access elements in a structure, you use a record selector ('.'). For example,
strcpy (my_friend.name, "Mr. Wizard");
A bit field is an element of a structure that is defined in terms of bits. Using a special type of struct definition, you can declare a structure element that can range from 1 to 16 bits in length. For example,
struct bit_field
  {
    int bit_1 : 1;
    int bits_2_to_5 : 4;
    int bit_6 : 1;
    int bits_7_to_16 : 10;
  } bit_var;


typedef

typedef Keyword
Keyword Index

Creates a new type.

The syntax for defining a new type is

typedef type-definition identifier;
This statement assigns the symbol name identifier to the data type definition type-definition. For example,
typedef unsigned char byte;
typedef char str40[41];
typedef struct {float re, im;} complex;
typedef char *byteptr;
typedef int (*fncptr)(int);
After these definition, you can declare
byte m, n;
str40 myStr;
complex z1, z2;
byteptr p;
fncptr myFunc;
with the same meaning as you declare
unsigned char m, n;
char myStr[41];
struct {float re, im;} z1, z2;
char *p;
int (*myFunc)(int);
User defined types may be used at any place where the built-in types may be used.


union

union Keyword
Keyword Index

Groups variables which share the same storage space.

A union is similar to a struct, except it allows you to define variables that share storage space. The syntax for defining unions is:

union [union-type-name]
  {
    type variable-names;
    ...
  } [union-variables] ;
For example,
union short_or_long
  {
    short i;
    long l;
  } a_number;
The compiler will allocate enough storage in a number to accommodate the largest element in the union. Elements of a union are accessed in the same manner as a struct.

Unlike a struct, the variables 'a_number.i' and 'a_number.l' occupy the same location in memory. Thus, writing into one will overwrite the other.


void

void Keyword
Keyword Index

Empty data type.

When used as a function return type, void means that the function does not return a value. For example,

void hello (char *name)
{
  printf("Hello, %s.", name);
}
When found in a function heading, void means the function does not take any parameters. For example,
int init (void)
{
  return 1;
}
This is not the same as defining
int init ()
{
  return 1;
}
because in the second case the compiler will not check whether the function is really called with no arguments at all; instead, a function call with arbitrary number of arguments will be accepted without any warnings (this is implemented only for the compatibility with the old-style function definition syntax).

Pointers can also be declared as void. They can't be dereferenced without explicit casting. This is because the compiler can't determine the size of the object the pointer points to. For example,
int x;
float f;
void *p = &x;    // p points to x
*(int*)p = 2;
p = &r;          // p points to r
*(float*)p = 1.1;


volatile

volatile Keyword
Keyword Index

Indicates that a variable can be changed by a background routine.

Keyword volatile is an extreme opposite of const. It indicates that a variable may be changed in a way which is absolutely unpredictable by analysing the normal program flow (for example, a variable which may be changed by an interrupt handler). This keyword uses the following syntax:

volatile data-definition;
Every reference to the variable will reload the contents from memory rather than take advantage of situations where a copy can be in a register.


while

while Keyword
Keyword Index

Repeats execution while the condition is true.

Keyword while is the most general loop statemens. It uses the following syntax:

while (expression) statement
statement is executed repeatedly as long as the value of expression remains nonzero. The test takes place before each execution of the statement. For example,
while (*p == ' ') p++;
Of course, statement may be a compound statement as well.


Operators and Punctuators
  • List of Operators and Punctuators
  • Categories of Operators and Punctuators
  • Precedence of Operators
  • Lvalues and Rvalues


List of Operators and Punctuators
Operators and Punctuators Next

The standard C language provides the following operators and punctuators:

{ }

[ ]

( )

(type)

.

->

++

--

&

*

+

-

~

!

sizeof

/

%

<<

>>

<

>

<=

>=

==

!=

^

|

&&

||

? :

=

*=

/=

%=

+=

-=

<<=

>>=

&=

^=

|=

,

#

##

;

:

" "

...

In addition, GNU C also knows the typeof operator, and extends some existing operators.


Categories of Operators and Punctuators
Previous Operators and Punctuators Next
  • Unary operators
  • Binary operators
  • Ternary operators
  • Punctuators

The operators # and ## are used only by the preprocessor.

Depending on context, the same operator can have more than one meaning. For example, the ampersand ('&') can be interpreted as

  • a bitwise AND (A & B);
  • an address operator (&A);
In the first case, the '&' is a unary operator; in the second, the '&' is a binary operator. Similarly, the comma ',' may act as an operator and as a punctuator, etc.


Unary operators
Categories of Operators and Punctuators Next
  • Referencing operator ('&')
  • Dereferencing operator ('*')
  • Unary plus and minus operators ('+' and '-')
  • Increment operator ('++')
  • Decrement operator ('--')
  • Logical negation operator ('!')
  • Bitwise complement operator ('~')

Note: In GNU C the operator '&&' may also be used as unary operator for taking addresses of labels.


Referencing operator ('&')
Unary operators Next

In the expression

& expr
which means "take the address of the expr", the expr operand must be one of the following:
  • a function designator;
  • an lvalue designating an object that is not a bit field and is not declared with the register storage class specifier.
If the operand is of type type, the result is of type "pointer to type".

The '&' symbol is also used in C as a binary bitwise AND operator.


Dereferencing operator ('*')
Previous Unary operators Next

In the expression

* expr
which means "the object pointed to by expr", the expr must have type "pointer to type," where type is any data type. The result of the indirection is of type type.

If the operand is of type "pointer to function", the result is a function designator. If the operand is a pointer to an object, the result is an lvalue designating that object.

In the following situations, the result of indirection is undefined:
  1. The expr is a null pointer.
  2. The expr is the address of an automatic (local) variable and execution of its block has terminated.
You can also use the asterisk as an operator to dereference a pointer, or as the multiplication operator. Asterisk may be used also as a punctuator for creating pointer types.


Unary plus and minus operators ('+' and '-')
Previous Unary operators Next

In these unary + - expressions

+ expr
- expr
the expr operand must be of arithmetic type. The result is the value of the operand after any required integral promotions for the unary plus ('+') operator, or negative of the value of the operand after any required integral promotions for the unary minus ('-') operator. Floating point negation is internally executed using the fneg function.

Note that both '+' and '-' operators also have a binary form.


Increment operator ('++')
Previous Unary operators Next

The increment operator may be used as a postincrement or preincrement operator:

expr ++           (postincrement)
++ expr           (preincrement)
The expression is called the operand; it must be of scalar type (arithmetic or pointer types) and must be a modifiable lvalue.

When postincrement operator form is used, the value of the whole expression is the value of the postfix expression before the increment is applied. After the postfix expression is evaluated, the operand is incremented by 1.

When preincrement operator form is used, the operand is incremented by 1 before the expression is evaluated; the value of the whole expression is the incremented value of the operand.

The increment value is appropriate to the type of the operand. Pointer types follow the rules for pointer arithmetic. In other words, the actual address on which a pointer points to is incremented by the size of the pointed object (not by 1, except if the pointed object is one byte long), so after the incrementing, the pointer points to the next object in a sequence (e.g. to a next element in an array, etc.).

Note: GNU C extends the pointer arithmetic to be valid even on void pointers and pointers to functions (see extended pointer arithmetic for more info).


Decrement operator ('--')
Previous Unary operators Next

The decrement operator may be used as a postdecrement or predecrement operator:

expr --           (postdecrement)
-- expr           (predecrement)
The decrement operator follows the same rules as the increment operator, except that the operand is decremented by 1 after or before the whole expression is evaluated.


Logical negation operator ('!')
Previous Unary operators Next

In the expression

! expr
the expr operand must be of scalar type (i.e. not an array, a structure or an union). The result is of type int and is the logical negation of the operand:
  • 0 if the operand is nonzero;
  • 1 if the operand is 0.
The expression '!expr' is equivalent to '(0 == expr)'.


Bitwise complement operator ('~')
Previous Unary operators

In the expression

~ expr
the expr operand must be of integral type. The result is the bitwise complement of the operand after any required integral promotions. Each 0 bit in the operand is set to 1, and each 1 bit in the operand is set to 0.


Binary operators
Previous Categories of Operators and Punctuators Next
  • Binary plus and minus operators ('+' and '-')
  • Multiplicative operators ('*', '/' and '%')
  • Bitwise shift operators ('<<' and '>>')
  • Logical and bitwise operators ('&', '^', '|', '&&' and '||')
  • Assignment operators ('=' etc.)
  • Relational operators ('<', '>', '<=' and '>=')
  • Equality operators ('==' and '!=')
  • Selection (structure-access) operators ('.' and '->')


Binary plus and minus operators ('+' and '-')
Binary operators Next

Both '+' and '-' uses the same syntax:

expr1 + expr2
expr1 - expr2
Note that both '+' and '-' operators also have an unary form.

Legal operand types for expr1 + expr2 are:
  1. Both expr1 and expr2 are of arithmetic type;
  2. expr1 is of pointer to object type, and expr2 is of integral type.
  3. expr1 is of integral type, and expr2 is of pointer to object type;
In case 1, the operands are subjected to the standard arithmetical conversions (for example, chars are promoted to ints), and the result is the arithmetical sum of the operands.

In cases 2 and 3, the rules of pointer arithmetic apply. When expr1 is of pointer type (case 2), the actual address on which a pointer points to is incremented by expr2 multiplied by the size of the pointed object (not just by expr2, except if the pointed object is one byte long). For example, if expr1 points to an array, expr1 + 5 points to a fifth element of the array, no matter how long are the particular elements of the array. The same rules are valid for the case 3. Assuming that ptr is a pointer to type and that N is an integer, and assuming that the CPU uses linear addressing (this is true on Motorola 68000, but not on Intel 8086 for example), expression
ptr + N
is equal to
(type *) ((long) ptr + N * sizeof (type))
Legal operand types for expr1 - expr2 are:
  1. Both expr1 and expr2 are of arithmetic type;
  2. expr1 is of pointer to object type, and expr2 is integral type;
  3. Both expr1 and expr2 are pointers to compatible object types;
In case 1, the operands are subjected to the standard arithmetic conversions, and the result is the arithmetic difference of the operands.

In cases 2 and 3, the rules of pointer arithmetic apply. When expr1 is pointer and expr2 is integral type (case 2), the actual address on which a pointer points to is decremented by expr2 multiplied by the size of the pointed object (not just by expr2, except if the pointed object is one byte long). For example, if expr1 points to the fifth element of an array, expr1 - 2 points to a third element of the array, no matter how long are the particular elements of the array. When both expr1 and expr2 are pointers, the result of the substraction is the difference of actual addresses divided by the common size of pointed objects. For example, if expr1 and expr2 point to two elements of the same array, then expr2 - expr1 will be equal to the difference of actual indices of pointed elements.

The unqualified type 'type' is considered to be compatible with the qualified types 'const type', 'volatile type', and 'const volatile type'.

Floating point addition and substraction are internally executed using the fadd and fsub functions.

Note: GNU C extends the pointer arithmetic to be valid even on void pointers and pointers to functions (see extended pointer arithmetic for more info).


Multiplicative operators ('*', '/' and '%')
Previous Binary operators Next

There are three multiplicative operators in C:

* (multiplication: the product of the two operands)
/ (division: the quotient of the first operand divided by the second operand)
% (modulus: the remainder of the first operand divided by the second operand)
They use the following syntax:
expr1 * expr2
expr1 / expr2
expr1 % expr2
Note that '*' operator also has an unary form, and may be also used as a punctuator for creating pointer types.

Operands for '*' and '/' are of arithmetical type, and operands of '%' are of integral type. The usual arithmetic conversions are made on the operands. For '/' and '%', expr2 must be nonzero; expr2 == 0 results in an error (you can't divide by zero).

When expr1 and expr2 are integers and the quotient is not an integer:
  1. If expr1 and expr2 have the same sign, expr1 / expr2 is the largest integer less than the true quotient, and expr1 % expr2 has the sign of expr1.
  2. If expr1 and expr2 have opposite signs, expr1 / expr2 is the smallest integer greater than the true quotient, and expr1 % expr1 has the sign of expr1.
Note: Rounding is always toward zero.

Floating point multiplication and division are internally executed using the fmul and fdiv functions; more detailed info about rules of these operation is given with the description of these functions.


Bitwise shift operators ('<<' and '>>')
Previous Binary operators Next

Bitwise shift operators in C use the following syntax:

expr1 << expr2
expr1 >> expr2
In the expressions expr1 << expr2 and expr1 >> expr2, the operands expr1 and expr2 must be of integral type. The normal integral promotions are performed on expr1 and expr2, and the type of the result is the type of the promoted expr1. If expr2 is negative or is greater than or equal to the width in bits of expr1, the operation is undefined.

The result of the operation expr1 << expr2 is the value of expr1 left-shifted by expr2 bit positions, zero-filled from the right if necessary. The result of the operation expr1 >> expr2 is the value of expr1 right-shifted by expr2 bit positions.


Logical and bitwise operators ('&', '^', '|', '&&' and '||')
Previous Binary operators Next

The C language offers these bitwise and logical operators:

&  (bitwise AND)
^  (bitwise exclusive OR)
|  (bitwise inclusive OR)

&& (logical AND)
|| (logical OR)
They use the following syntax:
expr1 & expr2
expr1 ^ expr2
expr1 | expr2
expr1 && expr2
expr1 || expr2
In first three expressions, both operands must be of integral type. In fourth and fifth expressions, both operands must be of scalar type. The usual arithmetical conversions are performed on expr1 and expr2.

For the bitwise operators, each bit in the result is:

Bit value |  | Results of
in expr1 | in expr2 | expr1 & expr2 | expr1 ^ expr2 | expr1 | expr2
0 | 0 | 0 | 0 | 0
1 | 0 | 0 | 1 | 1
0 | 1 | 0 | 1 | 1
1 | 1 | 1 | 0 | 1

Unlike the bitwise operators, '&&' and '||' guarantee left-to-right evaluation. expr1 is evaluated first; if it is zero, expr1 && expr2 gives 0 (false), and expr2 is not evaluated at all. With expr1 || expr2, if expr1 is nonzero, expr1 || expr2 gives 1 (true), and expr2 is not evaluated at all.

Note: In GNU C the operator '&&' may be also used as unary operator for taking addresses of labels.


Assignment operators ('=' etc.)
Previous Binary operators Next

There are 11 assignment operators in C language. The '=' operator is the simple assignment operator; the other 10 ('*=', '/=', '%=', '+=', '-=', '<<=', '>>=', '&=', '^=' and '|=') are known as compound assignment operators. All of them use the following syntax:

expr1 assignment-operator expr2
In the expression expr1 = expr2, expr1 must be a modifiable lvalue. The value of expr2, after conversion to the type of expr1, is stored in the object designated by expr1 (replacing expr1's previous value). The value of the assignment expression is the value of expr1 after the assignment. That's why multiple assignments like
x = y = z = 10;
a = b + 2 * (c = d - 1);
are possible. Note that the assignment expression is not itself an lvalue.

For both simple and compound assignment, the operands expr1 and expr2 must obey one of the following sets of rules:
  1. expr1 is of qualified or unqualified arithmetic type and expr2 is of arithmetic type.
  2. expr1 has a qualified or unqualified version of a structure or union type compatible with the type of expr2.
  3. expr1 and expr2 are pointers to qualified or unqualified versions of compatible types, and the type pointed to by the left has all the qualifiers of the type pointed to by the right.
  4. One of expr1 or expr1 is a pointer to an object or incomplete type and the other is a pointer to a qualified or unqualified version of void. The type pointed to by the left has all the qualifiers of the type pointed to by the right.
  5. expr1 is a pointer and expr2 is a null pointer constant.
The compound assignments are 'op=', where op can be any one of the ten operator symbols '*', '/', '%', '+', '-', '<<', '>>', '&', '^' or '|'. The expression
expr1 op= expr2
has the same effect as
expr1 = expr1 op expr2
except that the lvalue expr1 is evaluated only once. For example, expr1 += expr2 is the same as expr1 = expr1 + expr2.


Relational operators ('<', '>', '<=' and '>=')
Previous Binary operators Next

The relational operators are used to compare relative values. They use the following syntax:

expr1 < expr2
expr1 > expr2
expr1 <= expr2
expr1 >= expr2
In all relational expressions, the operands must conform to one of the following sets of conditions:
  1. Both expr1 and expr2 are of arithmetic type. In this case, the usual arithmetic conversions are performed and the result is of type int.
  2. Both expr1 and expr1 are pointers to qualified or unqualified versions of compatible object types.
When the operands are of arithmetic type:
  • expr1 < expr2 gives 1 (true) if the value of expr1 is less than value of expr2; otherwise, the result is 0 (false).
  • expr1 <= expr2 gives 1 (true) if the value of expr1 is less than or equal to the value of expr2; otherwise, the result is 0 (false).
  • expr1 > expr2 gives 1 (true) if the value of expr1 is greater than the value of expr2; otherwise, the result is 0 (false).
  • expr1 >= expr2 gives 1 (true) if the value of expr1 is greater than or equal to the value of expr2; otherwise, the result is 0 (false).
When the operands are of compatible pointer types, the result depends on the relative addresses of the two objects being pointed at.

Floating point comparisons are internally executed using the fcmp function. See the description of this function for more info about rules of comparisons for floating point values.


Equality operators ('==' and '!=')
Previous Binary operators Next

The operators '==' and '!=' are used to test for equality or inequality between arithmetic or pointer values, following rules similar to those for the relational operators. However, the equality operators have lower precedence than the relational operators, and you can also compare certain pointer types not allowed with relational operations.

In the expressions expr1 == expr2 and expr1 != expr2, the operands must conform to one of the following sets of conditions:

  1. Both expr1 and expr2 are of arithmetic type.
  2. Both expr1 and expr2 are pointers to qualified or unqualified versions of compatible types.
  3. One of expr1 and expr2 is a pointer to an object, and the other is a pointer to a qualified or unqualified version of void. In this case, the pointer to an object is converted to the type of the other operand (a void pointer).
  4. One of expr1 or expr2 is a pointer and the other is a null pointer constant.
If expr1 and expr2 have types that are valid operand types for a relational operator, the same comparison rules as for the relational operators apply.

If expr1 and expr2 are pointers to function types, expr1 == expr2 gives 1 (true) if they are both null or if they both point to the same function. Conversely, if expr1 == expr2 gives 1 (true), then either expr1 and expr2 point to the same function, or they are both null.

The expression expr1 != expr2 follows the same rules, except that the result is 1 (true) if the operands are unequal, and 0 (false) if the operands are equal.

Floating point comparisons are internally executed using the fcmp function. See the description of this function for more info about rules of comparisons for floating point values.


Selection (structure-access) operators ('.' and '->')
Previous Binary operators

The C language supports two selection operators:

.  (direct member selector)
-> (indirect, or pointer, member selector)
You use the selection operators '.' and '->' to access structure and union members. Suppose that the object s is of struct type S and sptr is a pointer to s. Then, if m is a member identifier of type M declared in S, these expressions:
s.m
sptr->m
are of type M, and both represent the member object m in s.

The expression
sptr->m
is a convenient synonym for (*sptr).m.

The direct member selector ('.') uses the following syntax:
expresssion . identifier
The expr must be of type union or structure. The identifier must be the name of a member of that structure or union type.

The indirect member operator ('->') uses the following syntax:
expr -> identifier
The expr must be of type pointer to structure or pointer to union. The identifier must be the name of a member of that structure or union type.

The expression with selection operators designates a member of a structure or union object. The value of the selection expression is the value of the selected member; it will be an lvalue if and only if the expr is an lvalue. For example,
struct mystruct
  {
    int i;
    char str[21];
    long d;
  } s, *sptr=&s;

...

s.i = 3;              // assign to the 'i' member of mystruct 's'
sptr->d = 12345678;   // assign to the 'd' member of mystruct 's'
The expression 's.m' is an lvalue, provided that 's' is an lvalue and 'm' is not an array type. The expression 'sptr->m' is an lvalue unless 'm' is an array type.

If structure B contains a field whose type is structure A, the members of A can be accessed by two applications of the member selectors.


Ternary operators
Previous Categories of Operators and Punctuators Next
  • Conditional operator ('? :')


Conditional operator ('? :')
Ternary operators

The conditional operator '?:' is, in fact, a ternary operator. It uses the following syntax:

expr1 ? expr2 : expr3
In the expression expr1 ? expr2 : Expr3, the operand expr1 must be of scalar type. The operands expr2 and Expr3 must obey one of the following sets of rules:
  1. Both of arithmetic type. In this case, both expr2 and Expr3 are subject to the usual arithmetic conversions, and the type of the result is the common type resulting from these conversions.
  2. Both of compatible structure or union types. In this case, the type of the result is the structure or union type of expr2 and expr3.
  3. Both of void type. In this case, the result is of type void.
  4. Both of type pointer to qualified or unqualified versions of compatible types. In this case, the type of the result is pointer to a type qualified with all the type qualifiers of the types pointed to by both operands.
  5. One operand of pointer type, the other a null pointer constant In this case, the type of the result is pointer to a type qualified with all the type qualifiers of the types pointed to by both operands.
  6. One operand of type pointer to an object, the other of type pointer to a qualified or unqualified version of void. In this case, the type of the result is that of the non-pointer-to-void operand.
In all cases, expr1 is evaluated first. If its value is nonzero (true), then expr2 is evaluated and expr3 is ignored (not evaluated at all). If expr1 evaluates to zero (false), then expr3 is evaluated and expr2 is ignored. The result of expr1 ? expr2 : expr3 will be the value of whichever of expr2 and expr3 is evaluated.

Note: GNU C extends the usage of the conditional operator to allow omitting the middle operand, so it may be used as a binary operator too.


Punctuators
Previous Categories of Operators and Punctuators
  • Array subscript operator ('[...]')
  • Parentheses operators ('(...)')
  • Braces ('{...}')
  • Equal sign ('=')
  • Comma operator and punctuator (',')
  • Semicolon (';')
  • Colon (':')
  • Asterisk ('*')
  • Quotes ('"..."')
  • Ellipsis ('...')
  • Typecast ('(type)')

Most of these punctuators also function as operators.


Array subscript operator ('[...]')
Punctuators Next

Brackets indicate single and multidimensional array subscripts. When used as an operator, the expression

expr1[expr2]
is defined exactly as
*((expr1) + (expr2))
where either expr1 is a pointer and expr2 is an integer, or expr1 is an integer and expr2 is a pointer. Of course, the addition is performed in according to the pointer arithmetic rules (see binary plus for more info).

Note that every array name, if used alone (without the array subscript operator), is automatically interpreted as a pointer to the first element of the array.

When used as a punctuator, brackets are used for creating array types (see asterisk for more info).

Note: The GNU C extends the usage of square brackets to allow labeling elements in initializers.


Parentheses operators ('(...)')
Previous Punctuators Next

Parentheses operators do the following:

  • group expressions (when necessary to change precedence);
  • isolate conditional expressions;
  • indicate function calls and function parameters.
Note that parentheses are also the part of the TypeCast operator.

When used as function-call operators, parentheses use the following syntax:
expr (arg-expression-list)
This is a call to the function given by the expr, which can be either the function name, or an expression which evaluates to a pointer-to-function type. In the second case, the function call is in fact translated to
(* expr) (arg-expression-list)
arg-expression-list is a comma-delimited list of expressions of any type representing the actual (or real) function arguments. The value of the function call expression, if it has a value, is determined by the return statement in the function definition.

arg-expression-list may even be empty, which is necessary when you need to call an argument-less function:
expr ()
Note that every function name, if used alone (without the parentheses operator), is automatically interpreted as a pointer to the function.

When used as a punctuator, parentheses are used for creating function types (see asterisk for more info).


Braces ('{...}')
Previous Punctuators Next

The { } braces indicate the start and end of a compound statement. Each sequence of statements (terminated by semicolons) is treated as a single statement, called compound statement. Compound statements may have its own local variables as well.

Braces are also used in declaration of enumerations, structures and unions, as well as for function definitions. For example:

int square (int x);               // This is a function prototype
int square (int x) {return x*x;}  // This is a function definition
Note: The GNU C extends the usage of braces (together with parentheses) to allow making statement expressions. They are also used in cast constructors, which are yet another GNU C extension.


Equal sign ('=')
Previous Punctuators Next

The '=' (equal sign) used as a punctuator separates variable declarations from initialization lists. For example,

int array[5] = { 1, 2, 3, 4, 5 };
char *name = "Fred";
int x = 12;
In a C function, no code can precede any variable declarations. Note that the GNU C, in opposite to other C dialects, allow non-constant initializers (like in C++).

The equal sign is also used in enumerations:
enum colors {Blue = 1, Red = 2, Green = 4, Light = 8};
It is also used as the assignment operator in expressions:
a = b + c;
or even:
a = b + 2 * (c = d - 1);
Note: The GNU C extends the usage of equal sign (as a punctuator) to allow labeling elements in initializers.


Comma operator and punctuator (',')
Previous Punctuators Next

The comma, used as a punctuator, separates the elements of a function argument list, the elements in array or struct initializers, or the variables in a data declaration. The comma is also used as an operator in comma expressions. Mixing the two uses of comma is legal, but you must use parentheses to distinguish them.

When used as an operator, the comma operator uses the following syntax:

expr1, expr2
The left operand expr1 is evaluated as a void expression (i.e. it is ignored if not contain side effects), then expr2 is evaluated to give the result and type of the comma expression. So, the result is just expr2. By recursion, the expression
expr1, expr2, ..., ExprN
results in the left-to-right evaluation of each Expr-i, with the value and type of ExprN giving the result of the whole expression. Comma operator is usually used in for-loops for multiple initializations. For example,
for (i = 0, j = 1024; i + j < 5; i++, j /= 2) ...
It also may be used to avoid making compound statements in simple conditional statements. For example,
if (x > 10) i = 1, j = 2, k = 3;
have the same effect as
if (x > 10)
  {
    i = 1; j = 2; k = 3;
  }
To avoid ambiguity with the commas used in function argument and initializer lists, parentheses must be used. For example,
func(i, (j = 1, j + 4), k);
calls 'func' with three arguments, not four. The arguments are 'i', '5', and 'k'.


Semicolon (';')
Previous Punctuators Next

The semicolon is a statement terminator. It is also used to separate three expressions which are parts of a for-loop.

Any legal C expression (including the empty expression) followed by ; is interpreted as a statement, known as an expression statement. The expression is evaluated and its value is discarded. If the expression statement has no side effects, it will be simply ignored.

Semicolons are often used to create an empty statement. For example, the body of the following for-loop (which searches for a first non-zero element in the array) is an empty statement:

for (i = 0; i < max || !a[i]; i++);


Colon (':')
Previous Punctuators Next

Use the colon (':') to indicate a labeled statement:

start:
  x=0;
  ...
  goto start;
Special case of labels are case-labels, which are used in multiple selection statements, for example,
switch (a)
  {
    case 1:
      puts("One");
      break;
    case 2:
      puts("Two");
      break;
    ...
    default:
      puts("None of the above!");
  }
Note: The GNU C allows creating of local labels, which are useful in macro definitions.


Asterisk ('*')
Previous Punctuators Next

The asterisk ('*') in a variable expression creates a pointer to a type. For example,

int a, *b;
In this example 'a' is an integer, but 'b' is a pointer to an integer.

Punctuators asterisk, brackets and parentheses may be mixed together to create very complex data types (which are sometimes very hard to understand). When mixed together, parentheses have the greatest precedence, then brackets, and finally, asterisks. This will be illustrated with a set of examples, which are given in the following table:

int x;
 A simple integer
int x[5];
 An array (with 5 elements) of integers
int x[5][6];
 An array (with 5 elements) of arrays (with 6 elements) of integers; such "array of arrays" may be interpreted as a 5x6 matrix
int *x;
 A pointer to an integer
int *x[5];
 An array of pointers to integers
int x();
 A function (more precise, a prototype of a function) which returns an integer
int x(int a);
 A function which accepts one integer argument, and which returns an integer
int x(int a,int *b);
 A function which accepts two arguments, the first one is an integer, and second one is a pointer to an integer, and which returns an integer
int x(int,int*);
 The same as above, but actual names of arguments may be omitted in function prototypes (but not in function definitions)
int *x();
 A function which returns a pointer to an integer
int *x(int);
 A function which accepts one integer argument, and which returns a pointer to an integer
int **x;
 A pointer to a pointer to an integer (this declaration is logically equivalent with the next one)
int *x[];
 An array of unknown size of pointers to integers (this declaration is logically equivalent with the previous one)
int (*x)[5];
 A pointer to an array (with 5 elements) of integers
int (*x)();
 A pointer to a function which returns an integer
int (*x)(int,int);
 A pointer to a function which accepts two integer arguments and which returns an integer
int (*x[5])();
 An array of pointers to a function which returns an integer
int (*x(*x())[5])();
 A function which returns a pointer to an array of pointers to a function which returns an integer
int (*x(*x(int))[5])(int*);
 A function which accepts one argument which is a pointer to an integer, and which returns a pointer to an array of pointers to a function which accepts one integer argument and which returns an integer
int (*(*x[5])())[6];
 An array (with 6 elements) of pointers to a function which returns a pointer to an array (with 5 elements) of integers

Confused? Yes, it's C!

If you simply omit the actual variable name, you will get an anonymous type. Such anonymous types may be used with sizeof or typecast operators, or in lists of arguments in function prototypes. For example, 'int*' is anonymous pointer to an integer, 'int(*)()' is anonymous pointer to a function which returns an integer, and 'int(*[])(int*)' is anonymous array (of unknown size) of pointers to a function which returns an integer and which accepts one argument which is a pointer to an integer.

Note: The GNU C extends the usage of asterisk to allow computed goto.


Quotes ('"..."')
Previous Punctuators Next

Quotes are used for defining string constants. In the compile-time, the sequence of characters between qoutes are stored somewhere in the executable file. In the run time, the "result" of quotes is a pointer (of type 'char*') which points to the place where the sequence of characters is stored. This interpretation of quotes differs significantly from the interpretation of strings in other languages. That's why there is nothing wrong with the following C code (it stores the address where the text "Hello" is stored, interpreted as an integer, in a):

int a;
a = (int)"Hello";
Such constructs are usually impossible in other languages. Note that sequences of characters between quotes behave similarly like arrays declared with the static keyword, i.e. they can survive the end of a function or program if they are changed somewhere in the program (anyway, it is very bad idea to change the content of a string constant). For example, the following code
for (i = 0; i < 2; i++)
  {
    char *str;
    str = "xyz";
    printf (str);
    *str = 'a';
  }
will display "xyzayz", although it seems that "xyzxyz" would be displayed. Such strange behaviour is caused by the fact that "xyz" is initialized in the compile-time. Now, if you understand the correct interpretation of what the quote punctuator does, you can explain this behaviour easily. To learn: strings in C behave quite differently than in most other languages!

Note: These two statements are very different, although most books say that they are nearly the same:
char str[] = "Hello";
char *str = "Hello";
Suppose that str is declared in the body of the function (i.e. it is an automatic local variable). In both cases, the text "Hello" is stored somewhere in memory, and the "result" of "Hello" is the address where it is stored (we will call this address addr). In the first case, str is a local array (i.e. it is created on the stack at run time, and there will be 6 bytes reserved for it), whose content is initialized at run-time (because it does not exist at compile-time) with the sequence of bytes located at addr. In other words, it is the same as you wrote:
char str[6];
strcpy (str, "Hello");
The consequence is that if you change the content of str (note that this is not the same as changing bytes pointed to by addr), it will be reinitialized each time when this statement is encountered again. But, in the second case, str is a local pointer, whose content is initialized (at run-time) with addr! So, if the contents of the string "Hello" are changed, this change will be permanent, because when this statement is encountered again, str will simply be reinitialized (if changed) to addr but bytes pointed to by it are not restored! Confused? See the following code:
for (i = 0; i < 2; i++)
  {
    char str[] = "Hello";
    printf (str);
    str[0] = 'a';
  }
This program will work as expected (it will display "Hello" twice). But, if you change 'str[]' to '*str', it will not work as expected (it will display "Hello" and then "aello").

Generally, it is a very bad idea to change strings which are the result of quotes. The reason is that usually equal strings are stored only once in the program. This means that you can get unexpected results if you modify them.

If the '\' character is found inside a string literal, it is threated as the start of an escape code. Here is an incomplete list of possible escape codes:

\\ | Represents one '\' character.
\" | Represents one '"' character. Needed in strings to represent this character, because an unescaped '"' would end the string.
\n | Newline; for ASCII this is octal code 012.
\b | Backspace; for ASCII this is octal code 010.
\f | FormFeed; for ASCII this is octal code 014.
\r | Carriage-Return; for ASCII this is octal code 015.
\t | Horizontal Tab; for ASCII this is octal code 011.
\ddd | An octal character code. The numeric code is 3 octal digits.
\x dd... | A hex character code. All trailing hex digits are combined.


Ellipsis ('...')
Previous Punctuators Next

An ellipsis ('...') consists of three successive periods with no whitespace intervening. You can use an ellipsis in the formal argument lists of function prototypes to indicate a variable number of arguments, or arguments with varying types. For example,

void func (int n, char ch, ...);
This declaration indicates that func will be defined in such a way that calls must have at least two arguments, an int and a char, but can also have any number of additional arguments.

Note: The GNU C extends the usage of ellipsis for making case ranges and for labeling elements in initializers.


Typecast ('(type)')
Previous Punctuators

The typecast operator forces an expression to behave as an object of a given type. It uses the following syntax:

(type) expr
The expression expr will be interpreted as having type type. It may be any simple type (modified or unmodified), enumeration, structure, union, user defined type created using typedef, void type, or an anonymous type (see asterisk for more information about anonymous types). Here is an example list of valid typecast operators:
(int)
(unsigned long int)
(signed)
(enum foo)
(struct foo)
(mytype)             assuming that 'mytype' is defined with 'typedef'
(void)
(char *)
(void *)
(struct foo *)
(void (*)(int))
(int (*[])(char*))
Typecast operator is very powerful in C, and may be used for conversion nearly everything to anything. For example, it is legal to convert an integer value to a pointer, so you can perform direct access to the memory (don't do this if you don't know exactly what are you doing). For example, '(char*)19456' converts integer 19456 to a char pointer, which may be dereferenced further using the dereference operator. So,
* (char*)19456 = 255;
stores 255 in the memory at the absolute address 19456 (this is the first byte of the LCD memory on TI-89 and TI-92+). The more drastic example is
((void(*)())10000)();
which calls the subroutine located at absolute address 10000 (first, the typecast operator '(void(*)())' converts 10000 to the pointer to the function, then the parentheses operator '()' is used to call the function). Note that nearly the whole GCC4TI library, when used in "nostub" mode, is implemented using the typecast operator which converts TIOS jump table entries to pointers to functions. For example, ClrScr is defined as '(*(void(**)(void))(*(long*)0xC8+0x678))', which is nothing other than a complex typecast. So, when you do
ClrScr ();
in your program, the preprocessor replaces it with
(*(void(**)(void))(*(long*)0xC8+0x678))();
However, typecast operator cannot be used to convert a scalar type to a structure or union (and vice versa), or to convert one non-scalar type into an incompatible non-scalar type. That's why casting to structures and unions are rarely valid.

Casting to a void means that you want to discard the result of the expression.

Casting to or from a floating point type are internally executed using the flt and trunc functions. See the description of these functions for more info.

Note: GNU C extends the usage of typecast operator to allow making cast constructors, which are probably the most powerful GNU C extensions. It also allows much more flexibility in casting to an union types.


Precedence of Operators
Previous Operators and Punctuators Next

In the following table of operator precedence, the C operators are divided into 15 categories. The #1 category has the highest precedence; category #2 (Unary operators) takes second precedence, and so on to the Comma operator, which has lowest precedence. The operators within each category have equal precedence.

The Unary (category #2), Conditional (category #13), and Assignment (category #14) operators associate right-to-left; all other operators associate left-to-right.

Category | Operator | What it is (or does)
1. Highest | [ ] ( ) -> . | Array subscript Function call Indirect component selector Direct component selector
2. Unary | ! ~ + - ++ -- & * sizeof (type) | Logical negation (NOT) Bitwise (1's) complement Unary plus Unary minus Preincrement or postincrement Predecrement or postdecrement Address Indirection Size of operand, in bytes TypeCast
3. Multiplicative | * / % | Multiply Divide Remainder (modulus)
4. Aditive | + - | Binary plus Binary minus
5. Shift | << >> | Shift left Shift right
6. Relational | < <= > >= | Less than Less than or equal to Greater than Greater than or equal to
7. Equality | == != | Equal to Not equal to
8. | & | Bitwise AND
9. | ^ | Bitwise XOR
10. | | | Bitwise OR
11. | && | Logical AND
12. | || | Logical OR
13. Conditional | ? : | "a ? x : y" means "if a then x, else y"
14. Assignment | = *= /= %= += -= &= ^= |= <<= >>= | Simple assignment Assign product Assign quotient Assign remainder (modulus) Assign sum Assign difference Assign bitwise AND Assign bitwise XOR Assign bitwise OR Assign left shift Assign right shift
15. Comma | , | Evaluate


Lvalues and Rvalues
Previous Operators and Punctuators

All expressions in C language may be classified to lvalues and rvalues.

An lvalue is an object locator: an expression that designates an object. Any variable is an lvalue for example. Another example of an lvalue expression is '*P', where P is any expression evaluating to a non-null pointer. See dereference operator for more information.

A modifiable lvalue is an identifier or expression that relates to an object that can be accessed and legally changed in memory. A const pointer to a constant, for example, is not a modifiable lvalue. A pointer to a constant can be changed (but its dereferenced value cannot).

Historically, the "l" stood for "left", meaning that an lvalue could legally stand on the left (the receiving end) of an assignment statement. Now, only modifiable lvalues can legally stand on the left of an assignment statement. For example, if 'a' and 'b' are nonconstant integer identifiers with properly allocated memory storage, they are both modifiable lvalues, and assignments such as

a = 1;
b = a + b;
are legal. From the other side, the expression
a + b
is not an lvalue: 'a + b = a' is illegal because the expression on the left is not related to an object. Such expressions are often called rvalues (short for "right values").

Note: In GNU C, the class of lvalue expressions is wider than in other C dialects; see section Generalized Lvalues for more info.


GNU C Language Extensions

This part of the documentation is a modified version of the C Extensions section of the GCC Manual. Therefore it is licensed under the GNU Free Documentation License.

GCC4TI (like all GNU C compilers) provides several language features not found in ISO standard C. To test for the availability of these features in conditional compilation, check for a predefined macro __GNUC__, which is always defined under GCC.

Some features that are in ISO C99 but not C89 are also, as extensions, accepted by GCC in C89 mode.

  • Statements and Declarations in Expressions
  • Locally Declared Labels
  • Labels as Values
  • Nested Functions
  • Constructing Function Calls
  • Referring to a Type with 'typeof'
  • Generalized Lvalues
  • Conditionals with Omitted Operands
  • Double-Word Integers
  • Complex Numbers
  • Hex Floats
  • Binary Numbers
  • Structures With No Members
  • Arrays of Length Zero
  • Arrays of Variable Length
  • Macros with a Variable Number of Arguments
  • Non-Lvalue Arrays May Have Subscripts
  • Arithmetic on void and Function Pointers
  • Non-Constant Initializers
  • Compound Literals (Cast Constructors)
  • Designated Initializers
  • Cast to a Union Type
  • Case Ranges
  • Specifying Attributes of Functions
  • Specifying Attributes of Variables
  • Specifying Attributes of Types
  • Attribute Syntax
  • Prototypes and Old-Style Function Definitions
  • C++ Style Comments
  • Dollar Signs in Identifier Names
  • Escape Character in Constants
  • Inquiring on Alignment of Types or Variables
  • Inline Functions
  • Inline Assembler
  • Controlling Names Used in Assembler Code
  • Variables in Specified Registers
  • Alternate Keywords
  • Incomplete 'enum' Types
  • Function Names as Strings
  • Getting the Return or Frame Address of a Function
  • Other built-in functions provided by GCC
  • Slightly Looser Rules for Escaped Newlines
  • String Literals with Embedded Newlines
  • Mixed Declarations and Code
  • Unnamed struct/union Fields within structs/unions
  • Definite Access of Volatile Objects
  • History
  • GNU General Public License
  • GNU Free Documentation License
  • Funding Free Software

Original author: Free Software Foundation, Inc.
Authors of the modifications: Zeljko Juric, Sebastian Reichelt, and Kevin Kofler
Published by the TIGCC Team, and now the GCC4TI project.
See the History section for details and copyright information.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License" and "Funding Free Software", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the section entitled "GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.


Statements and Declarations in Expressions
GNU C Language Extensions Next

A compound statement enclosed in parentheses may appear as an expression in GNU C. This allows you to use loops, switches, and local variables within an expression.

Recall that a compound statement is a sequence of statements surrounded by braces; in this construct, parentheses go around the braces. For example:

({ int y = foo (); int z;
   if (y > 0) z = y;
   else z = - y;
   z; })
is a valid (though slightly more complex than necessary) expression for the absolute value of foo ().

The last thing in the compound statement should be an expression followed by a semicolon; the value of this subexpression serves as the value of the entire construct. (If you use some other kind of statement last within the braces, the construct has type void, and thus effectively no value.)

This feature is especially useful in making macro definitions "safe" (so that they evaluate each operand exactly once). For example, the "maximum" function is commonly defined as a macro in standard C as follows:
#define max(a,b) ((a) > (b) ? (a) : (b))
But this definition computes either a or b twice, with bad results if the operand has side effects. In GNU C, if you know the type of the operands (here let's assume int), you can define the macro safely as follows:
#define maxint(a,b) \
  ({int _a = (a), _b = (b); _a > _b ? _a : _b; })
Embedded statements are not allowed in constant expressions, such as the value of an enumeration constant, the width of a bit-field, or the initial value of a static variable.

If you don't know the type of the operand, you can still do this, but you must use typeof.


Locally Declared Labels
Previous GNU C Language Extensions Next

Each statement expression is a scope in which local labels can be declared. A local label is simply an identifier; you can jump to it with an ordinary goto statement, but only from within the statement expression it belongs to.

A local label declaration looks like this:

__label__ label;
or
__label__ label1, label2, /* ... */;
Local label declarations must come at the beginning of the statement expression, right after the ({, before any ordinary declarations.

The label declaration defines the label name, but does not define the label itself. You must do this in the usual way, with label:, within the statements of the statement expression.

The local label feature is useful because statement expressions are often used in macros. If the macro contains nested loops, a goto can be useful for breaking out of them. However, an ordinary label whose scope is the whole function cannot be used: if the macro can be expanded several times in one function, the label will be multiply defined in that function. A local label avoids this problem. For example:
#define SEARCH(array, target)                     \
({                                                \
  __label__ found;                                \
  typeof (target) _SEARCH_target = (target);      \
  typeof (*(array)) *_SEARCH_array = (array);     \
  int i, j;                                       \
  int value;                                      \
  for (i = 0; i < max; i++)                       \
    for (j = 0; j < max; j++)                     \
      if (_SEARCH_array[i][j] == _SEARCH_target)  \
        { value = i; goto found; }                \
  value = -1;                                     \
 found:                                           \
  value;                                          \
})


Labels as Values
Previous GNU C Language Extensions Next

You can get the address of a label defined in the current function (or a containing function) with the unary operator &&. The + value has type void*. This value is a constant and can be used wherever a constant of that type is valid. For example:

void *ptr;
/* ... */
ptr = &&foo;
To use these values, you need to be able to jump to one. This is done with the computed goto statement, goto *exp;. For example,
goto *ptr;
Any expression of type void* is allowed.

One way of using these constants is in initializing a static array that will serve as a jump table:
static void *array[] = { &&foo, &&bar, &&hack };
Then you can select a label with indexing, like this:
goto *array[i];
Note that this does not check whether the subscript is in bounds - array indexing in C never does that.

Such an array of label values serves a purpose much like that of the switch statement. The switch statement is cleaner, so use that rather than an array unless the problem does not fit a switch statement very well.

You may not use this mechanism to jump to code in a different function. If you do that, totally unpredictable things will happen. The best way to avoid this is to store the label address only in automatic variables and never pass it as an argument.

An alternate way to write the above example is
static const int array[] = { &&foo - &&foo, &&bar - &&foo,
                             &&hack - &&foo };
goto *(&&foo + array[i]);
This is more friendly to code living in shared libraries (DLLs), as it reduces the number of dynamic relocations that are needed (and, by consequence, would allow the data to be read-only).


Nested Functions
Previous GNU C Language Extensions Next

A nested function is a function defined inside another function. The nested function's name is local to the block where it is defined. For example, here we define a nested function named square, and call it twice:

double square_sum (double a, double b)
{
  double square (double z)
  {
    return z * z;
  }

  return square (a) + square (b);
}
The nested function can access all the variables of the containing function that are visible at the point of its definition. This is called lexical scoping. For example, here we show a nested function which uses an inherited variable named offset:
int foo (int *array, int offset, int size)
{
  int access (int *array, int index)
  {
    return array[index + offset];
  }

  int i;
  /* ... */
  for (i = 0; i < size; i++)
    /* ... */ access (array, i) /* ... */
}
Nested function definitions are permitted within functions in the places where variable definitions are allowed; that is, in any block, before the first statement in the block.

It is possible to call the nested function from outside the scope of its name by storing its address or passing the address to another function:
int hack (int *array, int size)
{
  void store (int index, int value)
  {
    array[index] = value;
  }

  intermediate (store, size);
}
Here, the function intermediate receives the address of store as an argument. If intermediate calls store, the arguments given to store are used to store into array. But this technique works only so long as the containing function (hack, in this example) does not exit.

If you try to call the nested function through its address after the containing function has exited, all hell will break loose. If you try to call it after a containing scope level has exited, and if it refers to some of the variables that are no longer in scope, you may be lucky, but it's not wise to take the risk. If, however, the nested function does not refer to anything that has gone out of scope, you should be safe.

GCC implements taking the address of a nested function using a technique called trampolines. A paper describing them is available at http://people.debian.org/~aaronl/Usenix88-lexic.pdf. Note that trampolines are currently broken in GCC4TI; they create code on the stack, which can make HW2 calculators crash.

A nested function can jump to a label inherited from a containing function, provided the label was explicitly declared in the containing function (see Local Labels). Such a jump returns instantly to the containing function, exiting the nested function which did the goto and any intermediate functions as well. Here is an example:
int bar (int *array, int offset, int size)
{
  __label__ failure;
  int access (int *array, int index)
    {
      if (index > size)
        goto failure;
      return array[index + offset];
    }
  int i;
  /* ... */
  for (i = 0; i < size; i++)
    /* ... */ access (array, i) /* ... */
  /* ... */
  return 0;

 /* Control comes here from 'access'
    if it detects an error.  */
 failure:
  return -1;
}
A nested function always has internal linkage. Declaring one with extern is erroneous. If you need to declare the nested function before its definition, use auto (which is otherwise meaningless for function declarations).
int bar (int *array, int offset, int size)
{
  __label__ failure;
  auto int access (int *, int);
  /* ... */
  int access (int *array, int index)
    {
      if (index > size)
        goto failure;
      return array[index + offset];
    }
  /* ... */
}


Constructing Function Calls
Previous GNU C Language Extensions Next

Using the built-in functions described below, you can record the arguments a function received, and call another function with the same arguments, without knowing the number or types of the arguments.

You can also record the return value of that function call, and later return that value, without knowing what data type the function tried to return (as long as your caller expects that data type).

  • __builtin_apply_args
  • __builtin_apply
  • __builtin_return


__builtin_apply_args
Constructing Function Calls Next

void *__builtin_apply_args (void);

This built-in function returns a pointer to data describing how to perform a call with the same arguments as were passed to the current function.

The function saves the arg pointer register, structure value address, and all registers that might be used to pass arguments to a function into a block of memory allocated on the stack. Then it returns the address of that block.


__builtin_apply
Previous Constructing Function Calls Next

void *__builtin_apply (void (*fnc)(), void *args, int size);

This built-in function invokes function with a copy of the parameters described by arguments and size.

The value of arguments should be the value returned by __builtin_apply_args. The argument size specifies the size of the stack argument data, in bytes.

This function returns a pointer to data describing how to return whatever value was returned by function. The data is saved in a block of memory allocated on the stack.

It is not always simple to compute the proper value for size. The value is used by __builtin_apply to compute the amount of data that should be pushed on the stack and copied from the incoming argument area.


__builtin_return
Previous Constructing Function Calls

void __builtin_return (void *result);

This built-in function returns the value described by result from the containing function. You should specify, for result, a value returned by __builtin_apply.


Referring to a Type with 'typeof'
Previous GNU C Language Extensions Next

Another way to refer to the type of an expression is with typeof. The syntax of using of this keyword looks like sizeof, but the construct acts semantically like a type name defined with typedef.

There are two ways of writing the argument to typeof: with an expression or with a type. Here is an example with an expression:

typeof (x[0](1))
This assumes that x is an array of pointers to functions; the type described is that of the values of the functions.

Here is an example with a typename as the argument:
typeof (int *)
Here the type described is that of pointers to int.

An alternate keyword for typeof is __typeof__. See Alternate Keywords.

A typeof-construct can be used anywhere a typedef name could be used. For example, you can use it in a declaration, in a cast, or inside of sizeof or typeof.

typeof is often useful in conjunction with the statements-within-expressions feature. Here is how the two together can be used to define a safe "maximum" macro that operates on any arithmetic type and evaluates each of its arguments exactly once:
#define max(a,b) \
  ({ typeof (a) _a = (a); \
      typeof (b) _b = (b); \
    _a > _b ? _a : _b; })
The reason for using names that start with underscores for the local variables is to avoid conflicts with variable names that occur within the expressions that are substituted for a and b. Eventually we hope to design a new form of declaration syntax that allows you to declare variables whose scopes start only after their initializers; this will be a more reliable way to prevent such conflicts.

Some more examples of the use of typeof:
  • This declares y with the type of what x points to.
    typeof (*x) y;
  • This declares y as an array of such values.
    typeof (*x) y[4];
  • This declares y as an array of pointers to characters:
    typeof (typeof (char *)[4]) y;
    It is equivalent to the following traditional C declaration:
    char *y[4];
    To see the meaning of the declaration using typeof, and why it might be a useful way to write, let's rewrite it with these macros:
    #define pointer(T) typeof(T *)
#define array(T, N) typeof(T [N])
    Now the declaration can be rewritten this way:
    array (pointer (char), 4) y;
    Thus, array (pointer (char), 4) is the type of arrays of 4 pointers to char.
Compatibility Note: In addition to typeof, GCC 2 supported a more limited extension which permitted one to write
typedef T = expr;
with the effect of declaring T to have the type of the expression expr. This extension does not work with GCC 3 (versions between 3.0 and 3.2 will crash; 3.2.1 and later give an error). Code which relies on it should be rewritten to use typeof:
typedef typeof(expr) T;
This will work with all versions of GCC.


Generalized Lvalues
Previous GNU C Language Extensions Next

Compound expressions, conditional expressions and casts are allowed as lvalues provided their operands are lvalues. This means that you can take their addresses or store values into them.

For example, a compound expression can be assigned, provided the last expression in the sequence is an lvalue. These two expressions are equivalent:

(a, b) += 5
a, (b += 5)
Similarly, the address of the compound expression can be taken. These two expressions are equivalent:
&(a, b)
a, &b
A conditional expression is a valid lvalue if its type is not void and the true and false branches are both valid lvalues. For example, these two expressions are equivalent:
(a ? b : c) = 5
(a ? b = 5 : (c = 5))
A cast is a valid lvalue if its operand is an lvalue. A simple assignment whose left-hand side is a cast works by converting the right-hand side first to the specified type, then to the type of the inner left-hand side expression. After this is stored, the value is converted back to the specified type to become the value of the assignment. Thus, if a has type char*, the following two expressions are equivalent:
(int)a = 5
(int)(a = (char *)(int)5)
An assignment-with-arithmetic operation such as += applied to a cast performs the arithmetic using the type resulting from the cast, and then continues as in the previous case. Therefore, these two expressions are equivalent:
(int)a += 5
(int)(a = (char *)(int) ((int)a + 5))
You cannot take the address of an lvalue cast, because the use of its address would not work out coherently. Suppose that &(int)f were permitted, where f has type float. Then the following statement would try to store an integer bit-pattern where a floating point number belongs:
*&(int)f = 1;
This is quite different from what (int)f = 1 would do - that would convert 1 to floating point and store it. Rather than cause this inconsistency, the GNU team thinks it is better to prohibit use of & on a cast.

If you really do want an int* pointer with the address of f, you can simply write (int*)&f.


Conditionals with Omitted Operands
Previous GNU C Language Extensions Next

The middle operand in a conditional expression may be omitted. Then if the first operand is nonzero, its value is the value of the conditional expression.

Therefore, the expression

x ? : y
has the value of x if that is nonzero; otherwise, the value of y.

This example is perfectly equivalent to
x ? x : y
In this simple case, the ability to omit the middle operand is not especially useful. When it becomes useful is when the first operand does, or may (if it is a macro argument), contain a side effect. Then repeating the operand in the middle would perform the side effect twice. Omitting the middle operand uses the value already computed without the undesirable effects of recomputing it.


Double-Word Integers
Previous GNU C Language Extensions Next

ISO C99 supports data types for integers that are at least 64 bits wide, and as an extension GCC supports them in C89 mode. Simply write long long int for a signed integer, or unsigned long long int for an unsigned integer. To make an integer constant of type long long int, add the suffix LL to the integer. To make an integer constant of type unsigned long long int, add the suffix ULL to the integer.

You can use these types in arithmetic like any other integer types. Addition, subtraction, and bitwise boolean operations on these types are open-coded on all types of machines, as well as shifts with a constant value. Multiplication, division and shifts are not open-coded and use special library routines.

There may be pitfalls when you use long long types for function arguments, unless you declare function prototypes. If a function expects type int for its argument, and you pass a value of type long long int, confusion will result because the caller and the subroutine will disagree about the number of bytes for the argument. Likewise, if the function expects long long int and you pass int. The best way to avoid such problems is to use prototypes.


Complex Numbers
Previous GNU C Language Extensions Next

ISO C99 supports complex floating data types, and as an extension GCC supports them in C89 mode, and supports complex integer data types which are not part of ISO C99. You can declare complex types using the keyword _Complex. As an extension, the older GNU keyword __complex__ is also supported.

For example, _Complex double x; declares x as a variable whose real part and imaginary part are both of type double. _Complex short int y; declares y to have real and imaginary parts of type short int; this is not likely to be useful, but it shows that the set of complex types is complete.

To write a constant with a complex data type, use the suffix i or j (either one; they are equivalent). For example, 2.5fi has type _Complex float and 3i has type _Complex int. Such a constant always has a pure imaginary value, but you can form any complex value you like by adding one to a real constant. This is a GNU extension; once GCC4TI supports this, you should include <complex.h> and use the macros I or _Complex_I instead.

To extract the real part of a complex-valued expression exp, write __real__ exp. Likewise, use __imag__ to extract the imaginary part. This is a GNU extension; for values of floating type, you should use the ISO C99 functions crealf, creal, creall, cimagf, cimag and cimagl, declared in <complex.h> (not yet available in GCC4TI) and also provided as built-in functions by GCC.

The operator ~ performs complex conjugation when used on a value with a complex type. This is a GNU extension; for values of floating type, you should use the ISO C99 functions conjf, conj and conjl, declared in <complex.h> and also provided as built-in functions by GCC.

GCC can allocate complex automatic variables in a noncontiguous fashion; it's even possible for the real part to be in a register while the imaginary part is on the stack (or vice-versa).


Hex Floats
Previous GNU C Language Extensions Next

ISO C99 supports floating-point numbers written not only in the usual decimal notation, such as 1.55e1, but also numbers such as 0x1.fp3 written in hexadecimal format. As a GNU extension, GCC supports this in C89 mode (except in some cases when strictly conforming). In that format the 0x hex introducer and the p or P exponent field are mandatory. The exponent is a decimal number that indicates the power of 2 by which the significant part will be multiplied. Thus 0x1.f is 1 15/16, p3 multiplies it by 8, and the value of 0x1.fp3 is the same as 1.55e1.

Unlike for floating-point numbers in the decimal notation the exponent is always required in the hexadecimal notation. Otherwise the compiler would not be able to resolve the ambiguity of, e.g., 0x1.f. This could mean 1.0f or 1.9375 since f is also the extension for floating-point constants of type float.


Binary Numbers
Previous GNU C Language Extensions Next

GCC4TI allows you to specify binary numbers by using a 0b prefix. This can be handy in many occasions, such as when trying to declare sprites in a way which actually allows you to see the picture. For example, the following declaration defines a simple black and white 8x8 diagonal cross:

unsigned char cross[8] =
 {0b10000001,
  0b01000010,
  0b00100100,
  0b00011000,
  0b00011000,
  0b00100100,
  0b01000010,
  0b10000001};


Structures With No Members
Previous GNU C Language Extensions Next

GCC permits a C structure to have no members:

struct empty {
};
The structure will have size zero. In C++, empty structures are part of the language, and the language standard says they have size 1.


Arrays of Length Zero
Previous GNU C Language Extensions Next

Zero-length arrays are allowed in GNU C. They are very useful as the last element of a structure which is really a header for a variable-length object:

struct line {
  int length;
  char contents[0];
};

struct line *thisline = (struct line *)
  malloc (sizeof (struct line) + this_length);
thisline->length = this_length;
In ISO C90, you would have to give contents a length of 1, which means either you waste space or complicate the argument to malloc.

In ISO C99, you would use a flexible array member, which is slightly different in syntax and semantics:
  • Flexible array members are written as contents[] without the 0.

  • Flexible array members have incomplete type, and so the sizeof operator may not be applied. As a quirk of the original implementation of zero-length arrays, sizeof evaluates to zero.

  • Flexible array members may only appear as the last member of a struct that is otherwise non-empty.

  • A structure containing a flexible array member, or a union containing such a structure (possibly recursively), may not be a member of a structure or an element of an array. (However, these uses are permitted by GCC as extensions.)
GCC versions before 3.0 allowed zero-length arrays to be statically initialized, as if they were flexible arrays. In addition to those cases that were useful, it also allowed initializations in situations that would corrupt later data. Non-empty initialization of zero-length arrays is now treated like any case where there are more initializer elements than the array holds, in that a suitable warning about "excess elements in array" is given, and the excess elements (all of them, in this case) are ignored.

Instead GCC allows static initialization of flexible array members. This is equivalent to defining a new structure containing the original structure followed by an array of sufficient size to contain the data. I.e. in the following, f1 is constructed as if it were declared like f2.
struct f1 {
  int x; int y[];
} f1 = { 1, { 2, 3, 4 } };

struct f2 {
  struct f1 f1; int data[3];
} f2 = { { 1 }, { 2, 3, 4 } };
The convenience of this extension is that f1 has the desired type, eliminating the need to consistently refer to f2.f1.

This has symmetry with normal static arrays, in that an array of unknown size is also written with [].

Of course, this extension only makes sense if the extra data comes at the end of a top-level object, as otherwise we would be overwriting data at subsequent offsets. To avoid undue complication and confusion with initialization of deeply nested arrays, we simply disallow any non-empty initialization except when the structure is the top-level object. For example:
struct foo { int x; int y[]; };
struct bar { struct foo z; };

struct foo a = { 1, { 2, 3, 4 } };        // Valid.
struct bar b = { { 1, { 2, 3, 4 } } };    // Invalid.
struct bar c = { { 1, { } } };            // Valid.
struct foo d[1] = { { 1, { 2, 3, 4 } } }; // Invalid.


Arrays of Variable Length
Previous GNU C Language Extensions Next

Variable-length automatic arrays are allowed in ISO C99, and as an extension GCC accepts them in C89 mode. (However, GCC's implementation of variable-length arrays does not yet conform in detail to the ISO C99 standard.) These arrays are declared like any other automatic arrays, but with a length that is not a constant expression. The storage is allocated at the point of declaration and deallocated when the brace-level is exited. For example:

FILE *concat_fopen (const char *s1, const char *s2, const char *mode)
{
  char str[strlen (s1) + strlen (s2) + 1];
  strcpy (str, s1);
  strcat (str, s2);
  return fopen (str, mode);
}
Jumping or breaking out of the scope of the array name deallocates the storage. Jumping into the scope is not allowed; you get an error message for it.

You can use the function alloca to get an effect much like variable-length arrays. The function alloca is available in many other C implementations (but not in all). On the other hand, variable-length arrays are more elegant.

There are other differences between these two methods. Space allocated with alloca exists until the containing function returns. The space for a variable-length array is deallocated as soon as the array name's scope ends. (If you use both variable-length arrays and alloca in the same function, deallocation of a variable-length array will also deallocate anything more recently allocated with alloca.)

You can also use variable-length arrays as arguments to functions:
struct entry
tester (int len, char data[len][len])
{
  /* ... */
}
The length of an array is computed once when the storage is allocated and is remembered for the scope of the array in case you access it with sizeof.

If you want to pass the array first and the length afterward, you can use a forward declaration in the parameter list - another GNU extension.
struct entry
tester (int len; char data[len][len], int len)
{
  /* ... */
}
The int len before the semicolon is a parameter forward declaration, and it serves the purpose of making the name len known when the declaration of data is parsed.

You can write any number of such parameter forward declarations in the parameter list. They can be separated by commas or semicolons, but the last one must end with a semicolon, which is followed by the "real" parameter declarations. Each forward declaration must match a "real" declaration in parameter name and data type. ISO C99 does not support parameter forward declarations.


Macros with a Variable Number of Arguments
Previous GNU C Language Extensions Next

In the ISO C standard of 1999, a macro can be declared to accept a variable number of arguments much as a function can. The syntax for defining the macro is similar to that of a function. Here is an example:

#define lprintf(format, ...) fprintf (log, format, __VA_ARGS__)
Here ... is a variable argument. In the invocation of such a macro, it represents the zero or more tokens until the closing parenthesis that ends the invocation, including any commas. This set of tokens replaces the identifier __VA_ARGS__ in the macro body wherever it appears. For more information, see Variadic Macros.

GCC has long supported variadic macros, and used a different syntax that allowed you to give a name to the variable arguments just like any other argument. Here is an example:
#define lprintf(format, args...) fprintf (stderr, format, args)
This is in all ways equivalent to the ISO C example above, but arguably more readable and descriptive.

GNU CPP has two further variadic macro extensions, and permits them to be used with either of the above forms of macro definition.

In standard C, you are not allowed to leave the variable argument out entirely; but you are allowed to pass an empty argument. For example, this invocation is invalid in ISO C, because there is no comma after the string:
lprintf ("A message");
GNU CPP permits you to completely omit the variable arguments in this way. In the above examples, the compiler would complain, though since the expansion of the macro still has the extra comma after the format string.

To help solve this problem, CPP behaves specially for variable arguments used with the token paste operator, ##. If instead you write
#define lprintf(format, ...) fprintf (log, format, ## __VA_ARGS__)
and if the variable arguments are omitted or empty, the ## operator causes the preprocessor to remove the comma before it. If you do provide some variable arguments in your macro invocation, GNU CPP does not complain about the paste operation and instead places the variable arguments after the comma. Just like any other pasted macro argument, these arguments are not macro expanded.


Non-Lvalue Arrays May Have Subscripts
Previous GNU C Language Extensions Next

In ISO C99, arrays that are not lvalues still decay to pointers, and may be subscripted, although they may not be modified or used after the next sequence point and the unary & operator may not be applied to them. As an extension, GCC allows such arrays to be subscripted in C89 mode, though otherwise they do not decay to pointers outside C99 mode. For example, this is valid in GNU C though not valid in C89:

struct foo {int a[4];};

struct foo f();

bar (int index)
{
  return f().a[index];
}


Arithmetic on void and Function Pointers
Previous GNU C Language Extensions Next

In GNU C, addition and subtraction operations are supported on pointers to void and on pointers to functions. This is done by treating the size of a void or of a function as 1.

A consequence of this is that sizeof is also allowed on void and on function types, and returns 1.

The option '-Wpointer-arith' requests a warning if these extensions are used.


Non-Constant Initializers
Previous GNU C Language Extensions Next

As in standard C++ and ISO C99, the elements of an aggregate initializer for an automatic variable are not required to be constant expressions in GNU C. Here is an example of an initializer with run-time varying elements:

void foo (float f, float g)
{
  float beat_freqs[2] = { f-g, f+g };
  /* ... */
}


Compound Literals (Cast Constructors)
Previous GNU C Language Extensions Next

ISO C99 supports compound literals. A compound literal looks like a cast containing an initializer. Its value is an object of the type specified in the cast, containing the elements specified in the initializer; it is an lvalue. As an extension, GCC supports compound literals in C89 mode and in C++.

Usually, the specified type is a structure. Assume that struct foo and structure are declared as shown:

struct foo {int a; char b[2];} structure;
Here is an example of constructing a struct foo with a compound literal:
structure = ((struct foo) {x + y, 'a', 0});
This is equivalent to writing the following:
{
  struct foo temp = {x + y, 'a', 0};
  structure = temp;
}
You can also construct an array. If all the elements of the compound literal are (made up of) simple constant expressions, suitable for use in initializers of objects of static storage duration, then the compound literal can be coerced to a pointer to its first element and used in such an initializer, as shown here:
char **foo = (char *[]) { "x", "y", "z" };
Compound literals for scalar types and union types are also allowed, but then the compound literal is equivalent to a cast.

As a GNU extension, GCC allows initialization of objects with static storage duration by compound literals (which is not possible in ISO C99, because the initializer is not a constant). It is handled as if the object was initialized only with the bracket enclosed list if compound literal's and object types match. The initializer list of the compound literal must be constant. If the object being initialized has array type of unknown size, the size is determined by compound literal size.
static struct foo x = (struct foo) {1, 'a', 'b'};
static int y[] = (int []) {1, 2, 3};
static int z[] = (int [3]) {1};
The above lines are equivalent to the following:
static struct foo x = {1, 'a', 'b'};
static int y[] = {1, 2, 3};
static int z[] = {1, 0, 0};


Designated Initializers
Previous GNU C Language Extensions Next

Standard C89 requires the elements of an initializer to appear in a fixed order, the same as the order of the elements in the array or structure being initialized.

In ISO C99 you can give the elements in any order, specifying the array indices or structure field names they apply to, and GNU C allows this as an extension in C89 mode as well.

To specify an array index, write [index] = before the element value. For example,

int a[6] = { [4] = 29, [2] = 15 };
is equivalent to
int a[6] = { 0, 0, 15, 0, 29, 0 };
The index values must be constant expressions, even if the array being initialized is automatic.

An alternative syntax for this which has been obsolete since GCC 2.5 but GCC still accepts is to write [index] before the element value, with no =.

To initialize a range of elements to the same value, write [first ... last] = value. This is a GNU extension. For example,
int widths[] = { [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 };
If the value in it has side-effects, the side-effects will happen only once, not for each initialized field by the range initializer.

Note that the length of the array is the highest value specified plus one.

In a structure initializer, specify the name of a field to initialize with .fieldname = before the element value. For example, given the following structure,
struct point { int x, y; };
the following initialization
struct point p = { .y = yvalue, .x = xvalue };
is equivalent to
struct point p = { xvalue, yvalue };
Another syntax which has the same meaning, obsolete since GCC 2.5, is fieldname:, as shown here:
struct point p = { y: yvalue, x: xvalue };
The [index] or .fieldname is known as a designator. You can also use a designator (or the obsolete colon syntax) when initializing a union, to specify which element of the union should be used. For example,
union foo { int i; double d; };

union foo f = { .d = 4 };
will convert 4 to a double to store it in the union using the second element. By contrast, casting 4 to type union foo would store it into the union as the integer i, since it is an integer (see Cast to Union).

You can combine this technique of naming elements with ordinary C initialization of successive elements. Each initializer element that does not have a designator applies to the next consecutive element of the array or structure. For example,
int a[6] = { [1] = v1, v2, [4] = v4 };
is equivalent to
int a[6] = { 0, v1, v2, 0, v4, 0 };
Labeling the elements of an array initializer is especially useful when the indices are characters or belong to an enum type. For example:
int whitespace[256]
  = { [' '] = 1, ['\t'] = 1, ['\h'] = 1,
      ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 };
You can also write a series of .fieldname and [index] designators before an = to specify a nested subobject to initialize; the list is taken relative to the subobject corresponding to the closest surrounding brace pair. For example, with the struct point declaration above:
struct point ptarray[10] = { [2].y = yv2, [2].x = xv2, [0].x = xv0 };
If the same field is initialized multiple times, it will have value from the last initialization. If any such overridden initialization has side-effect, it is unspecified whether the side-effect happens or not. Currently, GCC will discard them and issue a warning.


Cast to a Union Type
Previous GNU C Language Extensions Next

A cast to union type is similar to other casts, except that the type specified is a union type. You can specify the type either with union tag or with a typedef name. A cast to union is actually a constructor though, not a cast, and hence does not yield an lvalue like normal casts (see Compound Literals).

The types that may be cast to the union type are those of the members of the union. Thus, given the following union and variables:

union foo { int i; double d; };
int x;
double y;
both x and y can be cast to type union foo.

Using the cast as the right-hand side of an assignment to a variable of union type is equivalent to storing in a member of the union:
union foo u;
/* ... */
u = (union foo) x  <=>  u.i = x
u = (union foo) y  <=>  u.d = y
You can also use the union cast as a function argument:
void hack (union foo);
/* ... */
hack ((union foo) x);


Case Ranges
Previous GNU C Language Extensions Next

You can specify a range of consecutive values in a single case label, like this:

case low ... high:
This has the same effect as the proper number of individual case labels, one for each integer value from low to high, inclusive.

This feature is especially useful for ranges of ASCII character codes:
case 'A' ... 'Z':
Note: Always write spaces around the ..., for otherwise it may be parsed wrong when you use it with integer values. For example, write this:
case 1 ... 5:
rather than this:
case 1...5:


Specifying Attributes of Functions
Previous GNU C Language Extensions Next

In GNU C, you declare certain things about functions called in your program which help the compiler optimize function calls and check your code more carefully.

The keyword __attribute__ allows you to specify special attributes when making a declaration. This keyword is followed by an attribute specification inside double parentheses. The following attributes are currently defined for functions:

  • noreturn
  • pure
  • const
  • format
  • format_arg
  • no_instrument_function
  • section
  • constructor, destructor
  • unused
  • used
  • malloc
  • alias
  • always_inline
  • noinline
  • deprecated
  • regparm, stkparm
  • nonnull
  • nothrow

Other attributes are supported for variable declarations (see Variable Attributes) and for types (see Type Attributes).

GCC4TI also defines the macros CALLBACK, __ATTR_TIOS__, __ATTR_TIOS_NORETURN__, __ATTR_TIOS_CALLBACK__, __ATTR_GCC__, __ATTR_LIB_C__, __ATTR_LIB_ASM__, __ATTR_LIB_ASM_NORETURN__, __ATTR_LIB_CALLBACK_C__, and __ATTR_LIB_CALLBACK_ASM__. They are useful for specifying default attributes for a specific class of functions. You only need to use them when you define a callback function. For example, the callback function type compare_t needs the attributes specified by __ATTR_LIB_CALLBACK_C__, i.e. the attributes required by a callback function for a library function written in C. Since this is too inconvenient for the user, all three callback attributes have been made equal, and we have defined a single CALLBACK macro.

You may also specify attributes with __ preceding and following each keyword. This allows you to use them in header files without being concerned about a possible macro of the same name. For example, you may use __noreturn__ instead of noreturn. For example, as malloc is defined as a macro in the GCC4TI Library, always use __malloc__ instead of malloc.

See Attribute Syntax for details of the exact syntax for using attributes.

You can specify multiple attributes in a declaration by separating them by commas within the double parentheses or by immediately following an attribute declaration with another attribute declaration.

Some people object to the __attribute__ feature, suggesting that ISO C's #pragma should be used instead. At the time __attribute__ was designed, there were two reasons for not doing this.

  1. It is impossible to generate #pragma commands from a macro.

  2. There is no telling what the same #pragma might mean in another compiler.
These two reasons applied to almost any application that might have been proposed for #pragma. It was basically a mistake to use #pragma for anything.

The ISO C99 standard includes _Pragma, which now allows pragmas to be generated from macros. In addition, a #pragma GCC namespace is now in use for GCC-specific pragmas. However, it has been found convenient to use __attribute__ to achieve a natural attachment of attributes to their corresponding declarations, whereas #pragma GCC is of use for constructs that do not naturally form part of the grammar.


noreturn
Specifying Attributes of Functions Next

A few standard library functions, such as abort and exit, cannot return. Some programs define their own functions that never return. You can declare them noreturn to tell the compiler this fact. For example:

void fatal () __attribute__ ((noreturn));

void
fatal (/* ... */)
{
  /* ... */ /* Print error message. */ /* ... */
  exit (1);
}
The noreturn keyword tells the compiler to assume that fatal cannot return. It can then optimize without regard to what would happen if fatal ever did return. This makes slightly better code. More importantly, it helps avoid spurious warnings of uninitialized variables.

Do not assume that registers saved by the calling function are restored before calling the noreturn function.

It does not make sense for a noreturn function to have a return type other than void.


pure
Previous Specifying Attributes of Functions Next

Many functions have no effects except the return value and their return value depends only on the parameters and/or global variables. Such a function can be subject to common subexpression elimination and loop optimization just as an arithmetic operator would be. These functions should be declared with the attribute pure. For example,

int square (int) __attribute__ ((pure));
says that the hypothetical function square is safe to call fewer times than the program says.

Some common examples of pure functions are strlen or memcmp. Interesting non-pure functions are functions with infinite loops or those depending on volatile memory or other system resource, that may change between two consecutive calls.

See also: const


const
Previous Specifying Attributes of Functions Next

Many functions do not examine any values except their arguments, and have no effects except the return value. Basically this is just slightly more strict class than the pure attribute, since the function is not allowed to read global memory.

Note that a function that has pointer arguments and examines the data pointed to must not be declared const. Likewise, a function that calls a non-const function usually must not be const. It does not make sense for a const function to return void.

See also: pure


format
Previous Specifying Attributes of Functions Next

Syntax: format (archetype, string-index, first-to-check)

The format attribute specifies that a function takes printf style arguments which should be type-checked against a format string. For example, the declaration:

extern int
my_printf (void *my_object, const char *my_format, ...)
      __attribute__ ((format (printf, 2, 3)));
causes the compiler to check the arguments in calls to my_printf for consistency with the printf style format string argument my_format.

The parameter archetype determines how the format string is interpreted, and should be printf, scanf, strftime or strfmon (note that only the function printf is implemented in the GCC4TI Library). (You can also use __printf__, __scanf__, __strftime__ or __strfmon__.) The parameter string-index specifies which argument is the format string argument (starting from 1), while first-to-check is the number of the first argument to check against the format string. For functions where the arguments are not available to be checked (such as vprintf), specify the third parameter as zero. In this case the compiler only checks the format string for consistency. For strftime formats, the third parameter is required to be zero.

In the example above, the format string (my_format) is the second argument of the function my_print, and the arguments to check start with the third argument, so the correct parameters for the format attribute are 2 and 3.

The format attribute allows you to identify your own functions which take format strings as arguments, so that GCC can check the calls to these functions for errors. The compiler always (unless '-ffreestanding' is used) checks formats for the standard library functions. See Options Controlling C Dialect.


format_arg
Previous Specifying Attributes of Functions Next

Syntax: format_arg (string-index)

The format_arg attribute specifies that a function takes a format string for a printf style function and modifies it (for example, to translate it into another language), so the result can be passed to a printf style function (with the remaining arguments to the format function the same as they would have been for the unmodified string). For example, the declaration

extern char *
my_dgettext (char *my_domain, const char *my_format)
      __attribute__ ((format_arg (2)));
causes the compiler to check the arguments in calls to a printf type function, whose format string argument is the result of a call to the my_dgettext function, for consistency with the format string argument my_format. If the format_arg attribute had not been specified, all the compiler could tell in such calls to format functions would be that the format string argument is not constant; this would generate a warning when '-Wformat-nonliteral' is used, but the calls could not be checked without the attribute.

The parameter string-index specifies which argument is the format string argument (starting from 1).

The format-arg attribute allows you to identify your own functions which modify format strings, so that GCC can check the calls to printf type functions whose operands are calls to one of your own functions. (The compiler always treats gettext, dgettext, and dcgettext in this manner except when strict ISO C support is requested by '-ansi' or an appropriate '-std' option, or '-ffreestanding' is used. See Options Controlling C Dialect.)


no_instrument_function
Previous Specifying Attributes of Functions Next

If '-finstrument-functions' is given, profiling function calls will be generated at entry and exit of most user-compiled functions. Functions with this attribute will not be so instrumented.


section
Previous Specifying Attributes of Functions Next

Syntax: section ("section-name")

Normally, the compiler places all code and data it generates in the .data section. Sometimes, however, you need additional sections, or you need certain particular functions to appear in special sections. The section attribute specifies that a function lives in a particular section. For example, the declaration:

extern void foobar (void) __attribute__ ((section ("bar")));
puts the function foobar in the bar section.

The use of this attribute is limited in GCC4TI, because its linker supports only a few types of sections.

The section attribute can also be used for variables.


constructor, destructor
Previous Specifying Attributes of Functions Next

The constructor attribute causes the function to be called automatically before execution enters _main. Similarly, the destructor attribute causes the function to be called automatically after _main has completed or exit has been called. Functions with these attributes are useful for initializing data that will be used implicitly during the execution of the program.


unused
Previous Specifying Attributes of Functions Next

This attribute, attached to a function, means that the function is meant to be possibly unused. GCC will not produce a warning for this function.

The unused attribute can also be used for variables and types.


used
Previous Specifying Attributes of Functions Next

This attribute, attached to a function, means that code must be emitted for the function even if it appears that the function is not referenced. This is useful, for example, when the function is referenced only in inline assembly.


malloc
Previous Specifying Attributes of Functions Next

The malloc attribute is used to tell the compiler that a function may be treated as if it were the malloc function. The compiler assumes that calls to malloc result in a pointers that cannot alias anything. This will often improve optimization.


alias
Previous Specifying Attributes of Functions Next

Syntax: alias ("target")

The alias attribute causes the declaration to be emitted as an alias for another symbol, which must be specified. For instance,

void __f () { /* Do something. */; }
void f () __attribute__ ((weak, alias ("__f")));
declares f to be a weak alias for __f.

Not all target machines support this attribute. We haven't tested yet whether it is supported for the Motorola 68000.


always_inline
Previous Specifying Attributes of Functions Next

Generally, functions are not inlined unless optimization is specified. For functions declared inline, this attribute inlines the function even if no optimization level was specified.


noinline
Previous Specifying Attributes of Functions Next

This function attribute prevents a function from being considered for inlining.


deprecated
Previous Specifying Attributes of Functions Next

The deprecated attribute results in a warning if the function is used anywhere in the source file. This is useful when identifying functions that are expected to be removed in a future version of a program. The warning also includes the location of the declaration of the deprecated function, to enable users to easily find further information about why the function is deprecated, or what they should do instead. Note that the warnings only occurs for uses:

int old_fn () __attribute__ ((deprecated));
int old_fn ();
int (*fn_ptr)() = old_fn;
results in a warning on line 3 but not line 2.

The deprecated attribute can also be used for variables and types.


regparm, stkparm
Previous Specifying Attributes of Functions Next

Syntax: regparm [(regcount)] / stkparm

The regparm attribute causes the function to use regcount data registers and regcount address registers for parameters. stkparm means the exact opposite, i.e. all parameters are passed on the stack. The '-mregparm' switch specifies which one is the default, and the default for regcount.

See also: Specifying Registers for Function Parameters


nonnull
Previous Specifying Attributes of Functions Next

Syntax: nonnull [(param1[, param2[, ...]])]

The nonnull attribute specifies that some function parameters should be non-null pointers. For instance, the declaration:

extern void *
my_memcpy (void *dest, const void *src, size_t len)
    __attribute__((nonnull (1, 2)));
causes the compiler to check that, in calls to my_memcpy, arguments dest and src are non-null. If the compiler determines that a null pointer is passed in an argument slot marked as non-null, and the '-Wnonnull' option is enabled, a warning is issued. The compiler may also choose to make optimizations based on the knowledge that certain function arguments will not be null.

If no argument index list is given to the nonnull attribute, all pointer arguments are marked as non-null. To illustrate, the following declaration is equivalent to the previous example:
extern void *
my_memcpy (void *dest, const void *src, size_t len)
    __attribute__((nonnull));


nothrow
Previous Specifying Attributes of Functions

The nothrow attribute is used to inform the compiler that a function cannot throw an exception. This is probably useless in GCC4TI, as it implements its own error-handling mechanism.


Specifying Attributes of Variables
Previous GNU C Language Extensions Next

The keyword __attribute__ allows you to specify special attributes of variables or structure fields. This keyword is followed by an attribute specification inside double parentheses. The following attributes are currently defined for variables:

  • aligned
  • mode
  • nocommon
  • packed
  • section
  • transparent_union
  • cleanup
  • unused
  • deprecated

Other attributes are available for functions (see Function Attributes) and for types (see Type Attributes).

You may also specify attributes with __ preceding and following each keyword. This allows you to use them in header files without being concerned about a possible macro of the same name. For example, you may use __aligned__ instead of aligned.

See Attribute Syntax for details of the exact syntax for using attributes.

To specify multiple attributes, separate them by commas within the double parentheses: for example, __attribute__ ((aligned (16), packed)).


aligned
Specifying Attributes of Variables Next

Syntax: aligned [(alignment)]

This attribute specifies a minimum alignment for the variable or structure field, measured in bytes. For example, the declaration:

int x __attribute__ ((aligned (4))) = 0;
causes the compiler to allocate the global variable x on a 4-byte boundary.

You can also specify the alignment of structure fields. For example, to create a 4-byte aligned int pair, you could write:
struct foo { int x[2] __attribute__ ((aligned (4))); };
As in the preceding examples, you can explicitly specify the alignment (in bytes) that you wish the compiler to use for a given variable or structure field. Alternatively, you can leave out the alignment factor and just ask the compiler to align a variable or field to the maximum useful alignment for the target machine you are compiling for. For example, you could write:
short array[3] __attribute__ ((aligned));
Whenever you leave out the alignment factor in an aligned attribute specification, the compiler automatically sets the alignment for the declared variable or field to the largest alignment which is ever used for any data type on the target machine you are compiling for (useless in GCC4TI, since everything is already aligned well enough with the default 2-byte alignment).

The aligned attribute can only increase the alignment; but you can decrease it by specifying packed as well.


mode
Previous Specifying Attributes of Variables Next

Syntax: mode (mode)

This attribute specifies the data type for the declaration - whichever type corresponds to the mode mode. This in effect lets you request an integer or floating point type according to its width.

You may also specify a mode of byte or __byte__ to indicate the mode corresponding to a one-byte integer, word or __word__ for the mode of a one-word integer, and pointer or __pointer__ for the mode used to represent pointers.


nocommon
Previous Specifying Attributes of Variables Next

This attribute requests GCC not to place a variable "common" but instead to allocate space for it directly. If you specify the '-fno-common' flag, GCC will do this for all variables.

Specifying the nocommon attribute for a variable provides an initialization of zeros. A variable may only be initialized in one source file.


packed
Previous Specifying Attributes of Variables Next

The packed attribute specifies that a variable or structure field should have the smallest possible alignment - one byte for a variable, and one bit for a field, unless you specify a larger value with the aligned attribute.

Here is a structure in which the field x is packed, so that it immediately follows a:

struct foo
{
  char a;
  int x[2] __attribute__ ((packed));
};


section
Previous Specifying Attributes of Variables Next

Syntax: section ("section-name")

Normally, the compiler places the objects it generates in sections like .data and .bss. Sometimes, however, you need additional sections, or you need certain particular variables to appear in special sections, for example to map to special hardware. The section attribute specifies that a variable (or function) lives in a particular section. The use of this attribute is limited in GCC4TI, because its linker supports only a few types of sections, but this may be improved in the future. For example, this small hypothetical program uses several specific section names:

struct duart a __attribute__ ((section ("DUART_A"))) = { 0 };
struct duart b __attribute__ ((section ("DUART_B"))) = { 0 };
char stack[10000] __attribute__ ((section ("STACK"))) = { 0 };
int init_data __attribute__ ((section ("INITDATA"))) = 0;

main()
{
  /* Initialize stack pointer */
  init_sp (stack + sizeof (stack));

  /* Initialize initialized data */
  memcpy (&init_data, &data, &edata - &data);

  /* Turn on the serial ports */
  init_duart (&a);
  init_duart (&b);
}
Use the section attribute with an initialized definition of a global variable, as shown in the example. GCC issues a warning and otherwise ignores the section attribute in uninitialized variable declarations.

You may only use the section attribute with a fully initialized global definition because of the way linkers work. The linker requires each object be defined once, with the exception that uninitialized variables tentatively go in the .bss section and can be multiply "defined". You can force a variable to be initialized with the '-fno-common' flag or the nocommon attribute.

The section attribute can also be used for functions.


transparent_union
Previous Specifying Attributes of Variables Next

This attribute, attached to a function parameter which is a union, means that the corresponding argument may have the type of any union member, but the argument is passed as if its type were that of the first union member. For more details, see the transparent_union type attribute. You can also use this attribute on a typedef for a union data type; then it applies to all function parameters with that type.


cleanup
Previous Specifying Attributes of Variables Next

The cleanup attribute runs a function when the variable goes out of scope. This attribute can only be applied to auto function scope variables; it may not be applied to parameters or variables with static storage duration. The function must take one parameter, a pointer to a type compatible with the variable. The return value of the function (if any) is ignored.

If '-fexceptions' is enabled, then cleanup_function will be run during the stack unwinding that happens during the processing of the exception. Note that the cleanup attribute does not allow the exception to be caught, only to perform an action. Note that GCC4TI defines its own error handling mechanism, so this attribute will not work if used in this way. It is undefined what happens if cleanup_function does not return normally.


unused
Previous Specifying Attributes of Variables Next

This attribute, attached to a variable, means that the variable is meant to be possibly unused. GCC will not produce a warning for this variable.

The unused attribute can also be used for functions and types.


deprecated
Previous Specifying Attributes of Variables

The deprecated attribute results in a warning if the variable is used anywhere in the source file. This is useful when identifying variables that are expected to be removed in a future version of a program. The warning also includes the location of the declaration of the deprecated variable, to enable users to easily find further information about why the variable is deprecated, or what they should do instead. Note that the warnings only occurs for uses:

extern int old_var __attribute__ ((deprecated));
extern int old_var;
int new_fn () { return old_var; }
results in a warning on line 3 but not line 2.

The deprecated attribute can also be used for functions and types.


Specifying Attributes of Types
Previous GNU C Language Extensions Next

The keyword __attribute__ allows you to specify special attributes of struct and union types when you define such types. This keyword is followed by an attribute specification inside double parentheses. The following attributes are currently defined for types:

  • aligned
  • packed
  • transparent_union
  • may_alias
  • unused
  • deprecated

Other attributes are defined for functions (see Function Attributes) and for variables (see Variable Attributes).

You may also specify any one of these attributes with __ preceding and following its keyword. This allows you to use these attributes in header files without being concerned about a possible macro of the same name. For example, you may use __aligned__ instead of aligned.

You may specify the aligned and transparent_union attributes either in a typedef declaration or just past the closing curly brace of a complete enum, struct or union type definition and the packed attribute only past the closing brace of a definition.

You may also specify attributes between the enum, struct or union tag and the name of the type rather than after the closing brace.

See Attribute Syntax for details of the exact syntax for using attributes.

To specify multiple attributes, separate them by commas within the double parentheses: for example, __attribute__ ((aligned (16), packed)).


aligned
Specifying Attributes of Types Next

Syntax: aligned [(alignment)]

This attribute specifies a minimum alignment (in bytes) for variables of the specified type. For example, the declarations:

struct S { short f[3]; } __attribute__ ((aligned (8)));
typedef int more_aligned_int __attribute__ ((aligned (8)));
force the compiler to insure (as far as it can) that each variable whose type is struct S or more_aligned_int will be allocated and aligned at least on a 8-byte boundary.

Note that the alignment of any given struct or union type is required by the ISO C standard to be at least a perfect multiple of the lowest common multiple of the alignments of all of the members of the struct or union in question. This means that you can effectively adjust the alignment of a struct or union type by attaching an aligned attribute to any one of the members of such a type, but the notation illustrated in the example above is a more obvious, intuitive, and readable way to request the compiler to adjust the alignment of an entire struct or union type.

As in the preceding example, you can explicitly specify the alignment (in bytes) that you wish the compiler to use for a given struct or union type. Alternatively, you can leave out the alignment factor and just ask the compiler to align a type to the maximum useful alignment for the target machine you are compiling for. For example, you could write:
struct S { short f[3]; } __attribute__ ((aligned));
Whenever you leave out the alignment factor in an aligned attribute specification, the compiler automatically sets the alignment for the type to the largest alignment which is ever used for any data type on the target machine you are compiling for (useless in GCC4TI, since everything is already aligned well enough with the default 2-byte alignment).

The aligned attribute can only increase the alignment; but you can decrease it by specifying packed as well.


packed
Previous Specifying Attributes of Types Next

This attribute, attached to an enum, struct, or union type definition, specified that the minimum required memory be used to represent the type.

Specifying this attribute for struct and union types is equivalent to specifying the packed attribute on each of the structure or union members. Specifying the '-fshort-enums' flag on the line is equivalent to specifying the packed attribute on all enum definitions.

You may only specify this attribute after a closing curly brace on an enum definition, not in a typedef declaration, unless that declaration also contains the definition of the enum.


transparent_union
Previous Specifying Attributes of Types Next

This attribute, attached to a union type definition, indicates that any function parameter having that union type causes calls to that function to be treated in a special way.

First, the argument corresponding to a transparent union type can be of any type in the union; no cast is required. Also, if the union contains a pointer type, the corresponding argument can be a null pointer constant or a void pointer expression; and if the union contains a void pointer type, the corresponding argument can be any pointer expression. If the union member type is a pointer, qualifiers like const on the referenced type must be respected, just as with normal pointer conversions.

Second, the argument is passed to the function using the calling conventions of first member of the transparent union, not the calling conventions of the union itself. All members of the union must have the same machine representation; this is necessary for this argument passing to work properly.

Transparent unions are designed for library functions that have multiple interfaces for compatibility reasons, but they may be used for various different purposes.


may_alias
Previous Specifying Attributes of Types Next

Accesses to objects with types with this attribute are not subjected to type-based alias analysis, but are instead assumed to be able to alias any other type of objects, just like the char type. See '-fstrict-aliasing' for more information on aliasing issues.

Example of use:

typedef short __attribute__((__may_alias__)) short_a;

void _main (void)
{
  long a = 0x12345678;
  short_a *b = (short_a *) &a;

  b[1] = 0;

  if (a == 0x12345678)
    abort();

  /* ... */
}
If you replaced short_a with short in the variable declaration, the above program would abort when compiled with '-fstrict-aliasing', which is on by default at '-O2' or above in recent GCC versions.


unused
Previous Specifying Attributes of Types Next

When attached to a type (including a union or a struct), this attribute means that variables of that type are meant to appear possibly unused. GCC will not produce a warning for any variables of that type, even if the variable appears to do nothing.

The unused attribute can also be used for functions and variables.


deprecated
Previous Specifying Attributes of Types

The deprecated attribute results in a warning if the type is used anywhere in the source file. This is useful when identifying types that are expected to be removed in a future version of a program. If possible, the warning also includes the location of the declaration of the deprecated type, to enable users to easily find further information about why the type is deprecated, or what they should do instead. Note that the warnings only occur for uses and then only if the type is being applied to an identifier that itself is not being declared as deprecated.

typedef int T1 __attribute__ ((deprecated));
T1 x;
typedef T1 T2;
T2 y;
typedef T1 T3 __attribute__ ((deprecated));
T3 z __attribute__ ((deprecated));
results in a warning on line 2 and 3 but not lines 4, 5, or 6. No warning is issued for line 4 because T2 is not explicitly deprecated. Line 5 has no warning because T3 is explicitly deprecated. Similarly for line 6.

The deprecated attribute can also be used for functions and variables.


Attribute Syntax
Previous GNU C Language Extensions Next

This section describes the syntax with which __attribute__ may be used, and the constructs to which attribute specifiers bind, for the C language. Because of infelicities in the grammar for attributes, some forms described here may not be successfully parsed in all cases.

See Function Attributes for details of the semantics of attributes applying to functions. See Variable Attributes for details of the semantics of attributes applying to variables. See Type Attributes for details of the semantics of attributes applying to structure, union and enumerated types.

An attribute specifier is of the form __attribute__ ((attribute-list)). An attribute list is a possibly empty comma-separated sequence of attributes, where each attribute is one of the following:

  • Empty. Empty attributes are ignored.

  • A word (which may be an identifier such as unused, or a reserved word such as const).

  • A word, followed by, in parentheses, parameters for the attribute. These parameters take one of the following forms:
    • An identifier. For example, mode attributes use this form.

    • An identifier followed by a comma and a non-empty comma-separated list of expressions. For example, format attributes use this form.

    • A possibly empty comma-separated list of expressions. For example, format_arg attributes use this form with the list being a single integer constant expression, and alias attributes use this form with the list being a single string constant.
An attribute specifier list is a sequence of one or more attribute specifiers, not separated by any other tokens.

An attribute specifier list may appear after the colon following a label, other than a case or default label. The only attribute it makes sense to use after a label is unused. This feature is intended for code generated by programs which contains labels that may be unused but which is compiled with '-Wall'. It would not normally be appropriate to use in it human-written code, though it could be useful in cases where the code that jumps to the label is contained within an #ifdef conditional.

An attribute specifier list may appear as part of a struct, union or enum specifier. It may go either immediately after the struct, union or enum keyword, or after the closing brace. It is ignored if the content of the structure, union or enumerated type is not defined in the specifier in which the attribute specifier list is used - that is, in usages such as struct __attribute__((foo)) bar with no following opening brace. Where attribute specifiers follow the closing brace, they are considered to relate to the structure, union or enumerated type defined, not to any enclosing declaration the type specifier appears in, and the type defined is not complete until after the attribute specifiers.

Otherwise, an attribute specifier appears as part of a declaration, counting declarations of unnamed parameters and type names, and relates to that declaration (which may be nested in another declaration, for example in the case of a parameter declaration), or to a particular declarator within a declaration. Where an attribute specifier is applied to a parameter declared as a function or an array, it should apply to the function or array rather than the pointer to which the parameter is implicitly converted, but this is not yet correctly implemented.

Any list of specifiers and qualifiers at the start of a declaration may contain attribute specifiers, whether or not such a list may in that context contain storage class specifiers. (Some attributes, however, are essentially in the nature of storage class specifiers, and only make sense where storage class specifiers may be used; for example, section.) There is one necessary limitation to this syntax: the first old-style parameter declaration in a function definition cannot begin with an attribute specifier, because such an attribute applies to the function instead by syntax described below (which, however, is not yet implemented in this case). In some other cases, attribute specifiers are permitted by this grammar but not yet supported by the compiler. All attribute specifiers in this place relate to the declaration as a whole. In the obsolescent usage where a type of int is implied by the absence of type specifiers, such a list of specifiers and qualifiers may be an attribute specifier list with no other specifiers or qualifiers.

An attribute specifier list may appear immediately before a declarator (other than the first) in a comma-separated list of declarators in a declaration of more than one identifier using a single list of specifiers and qualifiers. Such attribute specifiers apply only to the identifier before whose declarator they appear. For example, in
__attribute__((noreturn)) void d0 (void),
    __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
     d2 (void)
the noreturn attribute applies to all the functions declared; the format attribute only applies to d1.

An attribute specifier list may appear immediately before the comma, = or semicolon terminating the declaration of an identifier other than a function definition. At present, such attribute specifiers apply to the declared object or function, but in future they may attach to the outermost adjacent declarator. In simple cases there is no difference, but, for example, in
void (****f)(void) __attribute__((noreturn));
at present the noreturn attribute applies to f, which causes a warning since f is not a function, but in future it may apply to the function ****f. The precise semantics of what attributes in such cases will apply to are not yet specified. Where an assembler name for an object or function is specified (see Asm Labels), at present the attribute must follow the asm specification; in future, attributes before the asm specification may apply to the adjacent declarator, and those after it to the declared object or function.

An attribute specifier list may, in future, be permitted to appear after the declarator in a function definition (before any old-style parameter declarations or the function body).

Attribute specifiers may be mixed with type qualifiers appearing inside the [] of a parameter array declarator, in the C99 construct by which such qualifiers are applied to the pointer to which the array is implicitly converted. Such attribute specifiers apply to the pointer, not to the array, but at present this is not implemented and they are ignored.

An attribute specifier list may appear at the start of a nested declarator. At present, there are some limitations in this usage: the attributes correctly apply to the declarator, but for most individual attributes the semantics this implies are not implemented. When attribute specifiers follow the * of a pointer declarator, they may be mixed with any type qualifiers present. The following describes the formal semantics of this syntax. It will make the most sense if you are familiar with the formal specification of declarators in the ISO C standard.

Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration T D1, where T contains declaration specifiers that specify a type Type (such as int) and D1 is a declarator that contains an identifier ident. The type specified for ident for derived declarators whose type does not include an attribute specifier is as in the ISO C standard.

If D1 has the form ( attribute-specifier-list D ), and the declaration T D specifies the type "derived-declarator-type-list Type" for ident, then T D1 specifies the type "derived-declarator-type-list attribute-specifier-list Type" for ident.

If D1 has the form * type-qualifier-and-attribute-specifier-list D, and the declaration T D specifies the type "derived-declarator-type-list Type" for ident, then T D1 specifies the type "derived-declarator-type-list type-qualifier-and-attribute-specifier-list Type" for ident.

For example,
void (__attribute__((noreturn)) ****f) (void);
specifies the type "pointer to pointer to pointer to pointer to non-returning function returning void". As another example,
char *__attribute__((aligned(8))) *f;
specifies the type "pointer to 8-byte-aligned pointer to char". Note again that this does not work with most attributes; for example, the usage of aligned and noreturn attributes given above is not yet supported.

For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes. If an attribute that only applies to types is applied to a declaration, it will be treated as applying to the type of that declaration. If an attribute that only applies to declarations is applied to the type of a declaration, it will be treated as applying to that declaration; and, for compatibility with code placing the attributes immediately before the identifier declared, such an attribute applied to a function return type will be treated as applying to the function type, and such an attribute applied to an array element type will be treated as applying to the array type. If an attribute that only applies to function types is applied to a pointer-to-function type, it will be treated as applying to the pointer target type; if such an attribute is applied to a function return type that is not a pointer-to-function type, it will be treated as applying to the function type.


Prototypes and Old-Style Function Definitions
Previous GNU C Language Extensions Next

GNU C extends ISO C to allow a function prototype to override a later old-style non-prototype definition. Consider the following example:

/* Use prototypes unless the compiler is old-fashioned.  */
#ifdef __STDC__
#define P(x) x
#else
#define P(x) ()
#endif

/* Prototype function declaration.  */
int isroot P((uid_t));

/* Old-style function definition.  */
int
isroot (x)   /* ??? lossage here ??? */
     uid_t x;
{
  return x == 0;
}
Suppose the type uid_t happens to be char. ISO C does not allow this example, because subword arguments in old-style non-prototype definitions are promoted. Therefore in this example the function definition's argument is really an int, which does not match the prototype argument type of char.

This restriction of ISO C makes it hard to write code that is portable to traditional C compilers, because the programmer does not know whether the uid_t type is short, int, or long. Therefore, in cases like these GNU C allows a prototype to override a later old-style definition. More precisely, in GNU C, a function prototype argument type overrides the argument type specified by a later old-style definition if the former type is the same as the latter type before promotion. Thus in GNU C the above example is equivalent to the following:
int isroot (uid_t);

int
isroot (uid_t x)
{
  return x == 0;
}


C++ Style Comments
Previous GNU C Language Extensions Next

In GNU C, you may use C++ style comments, which start with // and continue until the end of the line. Many other C implementations allow such comments, and they are included in the 1999 C standard. However, C++ style comments are not recognized if you specify an '-std' option specifying a version of ISO C before C99, or '-ansi' (equivalent to '-std=c89').


Dollar Signs in Identifier Names
Previous GNU C Language Extensions Next

In GNU C, you may normally use dollar signs in identifier names. This is because many traditional C implementations allow such identifiers.


Escape Character in Constants
Previous GNU C Language Extensions Next

You can use the sequence \e in a string or character constant to stand for the ASCII character ESC (\x1B).


Inquiring on Alignment of Types or Variables
Previous GNU C Language Extensions Next

The keyword __alignof__ allows you to inquire about how an object is aligned, or the minimum alignment usually required by a type. Its syntax is just like sizeof.

In GCC4TI, __alignof__ (anything) is always 2, except for char variables.

If the operand of __alignof__ is an lvalue rather than a type, its value is the required alignment for its type, taking into account any minimum alignment specified with GCC's aligned attribute. For example, after this declaration:

struct foo { int x; char y; } foo1;
the value of __alignof__ (foo1.y) is 1, even though its actual alignment is 2, the same as __alignof__ (int).

It is an error to ask for the alignment of an incomplete type.


Inline Functions
Previous GNU C Language Extensions Next

By declaring a function inline, you can direct GCC to integrate that function's code into the code for its callers. This makes execution faster by eliminating the function-call overhead; in addition, if any of the actual argument values are constant, their known values may permit simplifications at compile time so that not all of the inline function's code needs to be included. The effect on code size is less predictable; object code may be larger or smaller with function inlining, depending on the particular case. Inlining of functions is an optimization and it really "works" only in optimizing compilation. If you don't use '-O', no function is really inline.

Inline functions are included in the ISO C99 standard, but there are currently substantial differences between what GCC implements and what the ISO C99 standard requires.

To declare a function inline, use the inline keyword in its declaration, like this:

inline int
inc (int *a)
{
  (*a)++;
}
(If you are writing a header file to be included in ISO C programs, write __inline__ instead of inline. See Alternate Keywords.) You can also make all "simple enough" functions inline with the option '-finline-functions'.

Note that certain usages in a function definition can make it unsuitable for inline substitution. Among these usages are: use of a variable number of arguments, use of alloca, use of variable sized data types (see Variable Length Arrays), use of computed goto (see Labels as Values), use of nonlocal goto, and nested functions (see Nested Functions). Using '-Winline' will warn when a function marked inline could not be substituted, and will give the reason for the failure.

Note that in C (unlike C++), the inline keyword does not affect the linkage of the function.

When a function is both inline and static, if all calls to the function are integrated into the caller, and the function's address is never used, then the function's own assembler code is never referenced. In this case, GCC does not actually output assembler code for the function, unless you specify the option '-fkeep-inline-functions'. Some calls cannot be integrated for various reasons (in particular, calls that precede the function's definition cannot be integrated, and neither can recursive calls within the definition). If there is a nonintegrated call, then the function is compiled to assembler code as usual. The function must also be compiled as usual if the program refers to its address, because that can't be inlined.

When an inline function is not static, then the compiler must assume that there may be calls from other source files; since a global symbol can be defined only once in any program, the function must not be defined in the other source files, so the calls therein cannot be integrated. Therefore, a non-static inline function is always compiled on its own in the usual fashion.

If you specify both inline and extern in the function definition, then the definition is used only for inlining. In no case is the function compiled on its own, not even if you refer to its address explicitly. Such an address becomes an external reference, as if you had only declared the function, and had not defined it.

This combination of inline and extern has almost the effect of a macro. The way to use it is to put a function definition in a header file with these keywords, and put another copy of the definition (lacking inline and extern) in a library file. The definition in the header file will cause most calls to the function to be inlined. If any uses of the function remain, they will refer to the single copy in the library.

For future compatibility with when GCC implements ISO C99 semantics for inline functions, it is best to use static inline only. (The existing semantics will remain available when '-std=gnu89' is specified, but eventually the default will be '-std=gnu99' and that will implement the C99 semantics, though it does not do so yet.)

GCC does not inline any functions when not optimizing unless you specify the always_inline attribute for the function, like this:
/* Prototype.  */
inline void foo (const char*) __attribute__((always_inline));


Inline Assembler
Previous GNU C Language Extensions Next

GCC introduces a special asm keyword to support assembler instructions within C code. Roughly, its syntax is:

asm ("instructions" [:output:input]);
The asm keyword may appear between usual lines of code or at the top level, outside of any function body. instructions may contain labels and references to global C symbols; in fact, the contents of the string are copied directly into the output file.
  • Simple Inline Assembler Instructions
  • Assembler Instructions with C Expression Operands
  • Operand Constraints

If you are writing a header file that should be includable in programs compiled in GCC's strict ISO C mode, write __asm__ instead of asm. See Alternate Keywords.


Simple Inline Assembler Instructions
Inline Assembler Next

The simplest form the asm keyword is:

asm ("instructions");
where instructions contains one or more assembler instructions separated by semicolons or newlines.

In GCC4TI, all register names must be preceded by a percent sign, to avoid confusion with C variables named like one of the CPU registers. For example:
asm ("move.l 0xC8,%a0; move.l (%a0,1656),%a0; jsr (%a0)");
Hexadecimal constants must be written according to C syntax (like 0xC8), not using the notation $C8 which is common in various assemblers.

Note that something like
asm ("move.l 0xC8,a0");
will be interpreted quite differently: a0 will be regarded as a C language variable, not a register! Read the documentation about the GNU Assembler for more information about the exact syntax and directives which it accepts; since inline assembler instructions are copied directly into the output of the compiler, exactly the same features are available.

Newlines as separators are also accepted in instructions, so the following code is valid as well:
asm ("   move.l 0xC8,%a0
         move.l (%a0,1656),%a0
         jsr (%a0)");
See Multi-line Strings for more information.


Assembler Instructions with C Expression Operands
Previous Inline Assembler Next

In an assembler instruction using asm, you can specify the operands of the instruction using C expressions. This means you need not guess which registers or memory locations will contain the data you want to use.

You must specify an assembler instruction template much like what appears in a machine description, plus an operand constraint string for each operand.

For the beginning, you will be given here a very illustrative example on how to use the 68881's fsinx instruction (note that this example is not applicable to TI calculators, because the MC68000 processor which is built into the TI-89 and TI-92+ does not have this instruction, but the example is illustrative anyway):

asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
Here angle is the C expression for the input operand while result is that of the output operand. Each has "f" as its operand constraint, saying that a floating point register is required. The = in =f indicates that the operand is an output; all output operands' constraints must use =. The constraints use the same language used in the machine description (see the section Operand Constraints). In this example, the compiler will convert this instruction into a sequence of assembly instructions which will ensure that the evaluated expression angle is really stored in one of the 68881's floating point registers, and which will store the result of the fsinx (which is in some other floating point register) into the expression result (note that result need not be a variable; it can be any lvalue expression, for example a dereferenced pointer).

Each operand is described by an operand-constraint string followed by the C expression in parentheses. A colon separates the assembler template from the first output operand and another separates the last output operand from the first input, if any. Commas separate the operands within each group. The total number of operands is currently limited to 30; this limitation may be lifted in some future version of GCC.

If there are no output operands but there are input operands, you must place two consecutive colons surrounding the place where the output operands would go.

As of GCC version 3.1, it is also possible to specify input and output operands using symbolic names which can be referenced within the assembler code. These names are specified inside square brackets preceding the constraint string, and can be referenced inside the assembler code using %[name] instead of a percentage sign followed by the operand number. Using named operands the above example could look like:
asm ("fsinx %[angle],%[output]"
     : [output] "=f" (result)
     : [angle] "f" (angle));
Note that the symbolic operand names have no relation whatsoever to other C identifiers. You may use any name you like, even those of existing C symbols, but must ensure that no two operands within the same assembler construct use the same symbolic name.

Output operand expressions must be lvalues; the compiler can check this. The input operands need not be lvalues. The compiler cannot check whether the operands have data types that are reasonable for the instruction being executed. It does not parse the assembler instruction template and does not know what it means or even whether it is valid assembler input. The extended asm feature is most often used for machine instructions the compiler itself does not know exist. If the output expression cannot be directly addressed (for example, it is a bit-field), your constraint must allow a register. In that case, GCC will use the register as the output of the asm, and then store that register into the output.

Here is an another example, which is applicable to GCC4TI. Suppose that we want to rotate the value of the expression input one bit to the left, and to store the result into the expression output (which is an lvalue). We can write the following code:
asm ("move.l %1,%%d0; rol #1,%%d0; move.l %%d0,%0" : "=g" (output) : "g" (input));
Note that when extended asm constructions are used, the percent sign before the register names must be doubled. It is important to say that in the above example input and output may be any valid expressions; in the simple case when both of them are just global variables, a simple asm construction like
asm ("move.l input,%d0; rol #1,%d0; move.l %d0,output");
would be quite enough. Extended asm constructions allow encapsulating them in macros which look like functions, like in the following example, which defines a macro 'rotate' which acts like a void function:
#define rotate(input, output) \
({ asm ("move.l %1,%%d0; rol #1,%%d0; move.l %%d0,%0" \
: "=g" (output) : "g" (input)); })
The ordinary output operands must be write-only; GCC will assume that the values in these operands before the instruction are dead and need not be generated. That's why the following version of 'rotate' macro which accepts just one argument (and which rotates it one bit to the left) is quite unreliable:
#define rotate(inout) ({ asm ("rol #1,%0" : "=d" (inout)); })
To solve such difficulties, extended asm supports input-output or read-write operands. Use the constraint character + to indicate such an operand and list it with the output operands.

When the constraints for the read-write operand (or the operand in which only some of the bits are to be changed) allows a register, you may, as an alternative, logically split its function into two separate operands, one input operand and one write-only output operand. The connection between them is expressed by constraints which say they need to be in the same location when the instruction executes. You can use the same C expression for both operands, or different expressions. For example, here we write the (fictitious) combine instruction with bar as its read-only source operand and foo as its read-write destination:
asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
The constraint "0" for operand 1 says that it must occupy the same location as operand 0. A number in constraint is allowed only in an input operand and it must refer to an output operand.

Only a number in the constraint can guarantee that one operand will be in the same place as another. The mere fact that foo is the value of both operands is not enough to guarantee that they will be in the same place in the generated assembler code. The following would not work reliably:
asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
Various optimizations or reloading could cause operands 0 and 1 to be in different registers; GCC knows no reason not to do so. For example, the compiler might find a copy of the value of foo in one register and use it for operand 1, but generate the output operand 0 in a different register (copying it afterward to foo's own address). Of course, since the register for operand 1 is not even mentioned in the assembler code, the result will not work, but GCC can't tell that.

As of GCC version 3.1, one may write [name] instead of the operand number for a matching constraint. For example:
asm ("cmoveq %1,%2,%[result]"
     : [result] "=r"(result)
     : "r" (test), "r"(new), "[result]"(old));
All the examples given above have a serious drawback: they clobber the register 'd0'. If the compiler keeps something important in it (which is very likely), this may cause lots of trouble. Of course, you can save it on the stack at the beginning and restore it at the end, but there is a much better solution which will save clobbered registers only when necessary. To describe clobbered registers, write a third colon after the input operands, followed by the names of the clobbered registers (given as strings), separated by commas:
#define rotate(input, output) \
({ asm ("move.l %1,%%d0; rol #1,%%d0; move.l %%d0,%0" \
: "=g" (output) : "g" (input) : "d0"); })
You may not write a clobber description in a way that overlaps with an input or output operand. For example, you may not have an operand describing a register class with one member if you mention that register in the clobber list. Variables declared to live in specific registers (see Explicit Reg Vars), and used as asm input or output operands must have no part mentioned in the clobber description. There is no way for you to specify that an input operand is modified without also specifying it as an output operand. Note that if all the output operands you specify are for this purpose (and hence unused), you will then also need to specify volatile for the asm construct, as described below, to prevent GCC from deleting the asm statement as unused.

Whenever you refer to a particular hardware register from the assembler code, you will probably have to list the register after the third colon to tell the compiler the register's value is modified. Alternatively, you can force the compiler to use any data register instead of 'd0', using the following trick:
#define rotate(input, output) \
({ register long __temp; \
asm ("move.l %1,%2; rol #1,%2; move.l %2,%0" \
: "=g" (output) : "g" (input), "d" (__temp)); })
Here, the "d" constraint ensures that '__temp' will be stored in the data register (note that rol is applicable only to data registers). In fact, there is no need for a temporary register if we forced the output to be in a data register, which can be implemented as in the following example:
#define rotate(input, output) \
({ asm ("move.l %1,%0; rol #1,%0" : "=d" (output) : "g" (input)); })
If your assembler instruction can alter the condition code register, add cc to the list of clobbered registers. GCC on some machines represents the condition codes as a specific hardware register; cc serves to name this register. On other machines, the condition code is handled differently, and specifying cc has no effect. But it is valid no matter what the machine.

If your assembler instruction modifies memory in an unpredictable fashion, add memory to the list of clobbered registers. This will cause GCC to not keep memory values cached in registers across the assembler instruction. You will also want to add the volatile keyword if the memory affected is not listed in the inputs or outputs of the asm, as the memory clobber does not count as a side-effect of the asm.

As already mentioned above, you can put multiple assembler instructions together in a single asm template, separated either with newlines or with semicolons (the GNU assembler allows semicolons as a line-breaking character). The input operands are guaranteed not to use any of the clobbered registers, and neither will the output operands' addresses, so you can read and write the clobbered registers as many times as you like. Here is an example of multiple instructions in a template; it assumes the subroutine _foo accepts arguments in registers a0 and a1:
asm ("move.l %0,%%a0; move.l %1,%%a1; jsr _foo"
: /* no outputs */
: "g" (from), "g" (to)
: "a0", "a1");
Unless an output operand has the '&' constraint modifier, GCC may allocate it in the same register as an unrelated input operand, on the assumption the inputs are consumed before the outputs are produced. This assumption may be false if the assembler code actually consists of more than one instruction. In such a case, use '&' for each output operand that may not overlap an input. See the section Constraint Modifier Characters.

If you want to test the condition code produced by an assembler instruction, you must include a branch and a label in the asm construct, as follows:
asm ("clr.l %0; test.l %1; beq 0f; moveq #1,%0; 0:"
: "g" (result) : "g" (input));
This assumes your assembler supports local labels, which is true for the GNU Assembler (it uses the suffix 'f' for forward and 'b' for backward local labels; see the section about Local Symbol Names).

Speaking of labels, jumps from one asm to another are not supported. The compiler's optimizers do not know about these jumps, and therefore they cannot take account of them when deciding how to optimize.

As already mentioned, usually the most convenient way to use these asm instructions is to encapsulate them in macros that look like functions. Here is an example of how to define a function-looking macro with a non-void return type:
#define rotate(x) \
({ unsigned long __result, __arg=(x);   \
asm ("move.l %1,%0; rol #1,%0": "=d" (__result): "g" (__arg));  \
__result; })
This macro acts nearly exactly like a function which takes one unsigned long argument, and which returns an unsigned long result. Here the variable __arg is used to make sure that the instruction operates on a proper unsigned long value, and to accept only those arguments x which can convert automatically to an unsigned long.

Another way to make sure the instruction operates on the correct data type is to use a cast in the asm. This is different from using a variable __arg in that it converts more different types. For example, if the desired type were int, casting the argument to int would accept a pointer with no complaint, while assigning the argument to an int variable named __arg would warn about using a pointer unless the caller explicitly casts it.

If an asm has output operands, GCC assumes for optimization purposes the instruction has no side effects except to change the output operands. This does not mean instructions with a side effect cannot be used, but you must be careful, because the compiler may eliminate them if the output operands aren't used, or move them out of loops, or replace two with one if they constitute a common subexpression. Also, if your instruction does have a side effect on a variable that otherwise appears not to change, the old value of the variable may be reused later if it happens to be found in a register.

If you are not happy with this behavior, you can prevent an asm instruction from being deleted, moved significantly, or combined, by writing the keyword volatile after the asm. For example:
#define get_and_set_priority(new)              \
({ int __old;                                  \
   asm volatile ("get_and_set_priority %0, %1" \
                 : "=g" (__old) : "g" (new));  \
   __old; })
If you write an asm instruction with no outputs, GCC will know the instruction has side-effects and will not delete the instruction or move it outside of loops.

The volatile keyword indicates that the instruction has important side-effects. GCC will not delete a volatile asm if it is reachable. (The instruction can still be deleted if GCC can prove that control-flow will never reach the location of the instruction.) In addition, GCC will not reschedule instructions across a volatile asm instruction. For example:
#define inline_rowread(x) \
  ({*(short*)0x600018=(short)(x); \
  asm volatile("nop;nop;nop;nop;nop;nop;nop;nop;nop;nop;nop;nop":::"memory"); \
  ~(*(unsigned char*)0x60001b);})
Here, we can read the keyboard port at 0x60001b only 12 nops after setting the keyboard mask at 0x600018. Therefore, we need to make sure that the nops get scheduled between the write to 0x600018 and the read to 0x60001b. The volatile keyword makes sure that the instructions get ordered in the correct way.

Note that even a volatile asm instruction can be moved in ways that appear insignificant to the compiler, such as across jump instructions. You can't expect a sequence of volatile asm instructions to remain perfectly consecutive. If you want consecutive output, use a single asm. Also, GCC will perform some optimizations across a volatile asm instruction; GCC does not "forget everything" when it encounters a volatile asm instruction the way some other compilers do.

An asm instruction without any operands or clobbers (an "old style" asm) will be treated identically to a volatile asm instruction.

It is a natural idea to look for a way to give access to the condition code left by the assembler instruction. However, when we attempted to implement this, we found no way to make it work reliably. The problem is that output operands might need reloading, which would result in additional following "store" instructions. On most machines, these instructions would alter the condition code before there was time to test it. This problem doesn't arise for ordinary "test" and "compare" instructions because they don't have any output operands.

For reasons similar to those described above, it is not possible to give an assembler instruction access to the condition code left by previous instructions.

You can write write __asm__ instead of asm. See section Alternate Keywords.


Operand Constraints
Previous Inline Assembler

Each match operand in an instruction pattern can specify a constraint for the type of operands allowed. Constraints can say whether an operand may be in a register, and which kinds of register; whether the operand can be a memory reference, and which kinds of address; whether the operand may be an immediate constant, and which possible values it may have. Constraints can also require two operands to match. Here, only those operand constraints which are valid for the Motorola 68000 processor and the built-in inline assembly will be described (i.e. those which are applicable to GCC4TI).

  • Simple Constraints
  • Constraint Modifier Characters


Simple Constraints
Operand Constraints Next

The simplest kind of constraint is a string full of letters, each of which describes one kind of operand that is permitted. These are the letters that are allowed:

m
A memory operand is allowed, with any kind of address that the machine supports in general.

o
A memory operand is allowed, but only if the address is offsettable. This means that adding a small integer (actually, the width in bytes of the operand, as determined by its machine mode) may be added to the address and the result is also a valid memory address. For example, an address which is constant is offsettable; so is an address that is the sum of a register and a constant (as long as a slightly larger constant is also within the range of address-offsets supported by the machine); but an autoincrement or autodecrement address is not offsettable. More complicated indirect/indexed addresses may or may not be offsettable depending on the other addressing modes that the machine supports.

Note that in an output operand which can be matched by another operand, the constraint letter o is valid only when accompanied by both < (if the target machine has predecrement addressing) and > (if the target machine has preincrement addressing).

V
A memory operand that is not offsettable. In other words, anything that would fit the m constraint but not the o constraint.

<
A memory operand with autodecrement addressing is allowed.

>
A memory operand with autoincrement addressing is allowed.

r
A register operand is allowed provided that it is in a general register.

d
A data register is allowed. This is a Motorola-specific constraint.

a
An address register is allowed. This is a Motorola-specific constraint.

f
A 68881 floating-point register is allowed, if available (of course, it is not available on the TI-89 and TI-92 Plus). This is a Motorola-specific constraint.

i
An immediate integer operand (one with constant value) is allowed. This includes symbolic constants whose values will be known only at assembly time.

n
An immediate integer operand with a known numeric value is allowed. Many systems cannot support assembly-time constants for operands less than a word wide. Constraints for these operands should use n rather than i.

I
An integer in the range 1 to 8 is allowed. This is a Motorola-specific constraint, and this is for example the range permitted as a shift count in the shift instructions.

J
A 16 bit signed number is allowed. This is a Motorola-specific constraint.

K
A signed number whose magnitude is greater than 0x80 is allowed. This is a Motorola-specific constraint.

L
An integer in the range -8 to -1 is allowed. This is a Motorola-specific constraint.

M
A signed number whose magnitude is greater than 0x100 is allowed. This is a Motorola-specific constraint.

s
An immediate integer operand whose value is not an explicit integer is allowed.

This might appear strange; if an instruction allows a constant operand with a value not known at compile time, it certainly must allow any known value. So why use s instead of i? Sometimes it allows better code to be generated. For example, on the 68000 in a fullword instruction it is possible to use an immediate operand; but if the immediate value is between -128 and 127, better code results from loading the value into a register and using the register. This is because the load into the register can be done with a 'moveq' instruction. The GNU team arranges for this to happen by defining the letter K to mean "any integer outside the range -128 to 127", and then specifying Ks in the operand constraints. (This constraint is very unlikely to be useful for inline assembly, since you cannot use constraints to make GCC choose between 2 different inline assembly statements.)

g
Any register, memory or immediate integer operand is allowed, except for registers that are not general registers.

X
Any operand whatsoever is allowed, even if it does not satisfy general_operand. This is normally used in the constraint of a match_scratch when certain alternatives will not actually require a scratch register.

0, 1, 2, ... 9
An operand that matches the specified operand number is allowed. If a digit is used together with letters within the same alternative, the digit should come last. This is called a matching constraint and what it really means is that the assembler has only a single operand that fills two roles considered separate. More precisely, the two operands that match must include one input-only operand and one output-only operand. Moreover, the digit must be a smaller number than the number of the operand that uses it in the constraint.

p
An operand that is a valid memory address is allowed.
In order to have valid assembler code, each operand must satisfy its constraint. But a failure to do so does not prevent the pattern from applying to an instruction pattern. Instead, it directs the compiler to modify the code so that the constraint will be satisfied. Usually this is done by copying an operand into a register.


Constraint Modifier Characters
Previous Operand Constraints

These are the constraint modifier characters which are meaningful for GCC4TI:

=
Means that this operand is write-only for this instruction: the previous value is discarded and replaced by output data.

+
Means that this operand is both read and written by the instruction.

When the compiler fixes up the operands to satisfy the constraints, it needs to know which operands are inputs to the instruction and which are outputs from it. = identifies an output; + identifies an operand that is both input and output; all other operands are assumed to be input only.

If you specify = or + in a constraint, you put it in the first character of the constraint string.

&
Means (in a particular alternative) that this operand is an earlyclobber operand, which is modified before the instruction is finished using the input operands. Therefore, this operand may not lie in a register that is used as an input operand or as part of any memory address. & does not obviate the need to write =.


Controlling Names Used in Assembler Code
Previous GNU C Language Extensions Next

You can specify the name to be used in the assembler code for a C function or variable by writing the asm (or __asm__) keyword after the declarator as follows:

int foo asm ("myfoo") = 2;
This specifies that the name to be used for the variable foo in the assembler code should be myfoo rather than the usual foo.

On systems where an underscore is normally prepended to the name of a C function or variable, this feature allows you to define names for the linker that do not start with an underscore.

It does not make sense to use this feature with a non-static local variable since such variables do not have assembler names. If you are trying to put the variable in a particular register, see Explicit Reg Vars. GCC presently accepts such code with a warning, but will probably be changed to issue an error, rather than a warning, in the future.

You cannot use asm in this way in a function definition; but you can get the same effect by writing a declaration for the function before its definition and putting asm there, like this:
extern func () asm ("FUNC");

func (int x, int y)
/* ... */
It is up to you to make sure that the assembler names you choose do not conflict with any other assembler symbols. Also, you must not use a register name; that would produce completely invalid assembler code. GCC does not as yet have the ability to store static variables in registers. Perhaps that will be added.


Variables in Specified Registers
Previous GNU C Language Extensions Next

GNU C allows you to put a few global variables into specified hardware registers. You can also specify the register in which an ordinary register variable should be allocated. GCC4TI also allows you to specify an explicit register for function parameters.

  • Defining Global Register Variables

    Global register variables reserve registers throughout the program. This may be useful in programs such as programming language interpreters which have a couple of global variables that are accessed very often.

  • Specifying Registers for Local Variables

    Local register variables in specific registers do not reserve the registers. The compiler's data flow analysis is capable of determining where the specified registers contain live values, and where they are available for other uses. Stores into local register variables may be deleted when they appear to be dead according to dataflow analysis. References to local register variables may be deleted or moved or simplified.

  • Specifying Registers for Function Parameters

    In GCC4TI, it is possible to specify explictly where the parameters to a function a stored, in a syntax similar to global and local register variables.


Defining Global Register Variables
Variables in Specified Registers Next

Global register variables reserve registers throughout the program. This may be useful in programs such as programming language interpreters which have a couple of global variables that are accessed very often.

You can define a global register variable in GNU C like this:

register int *foo asm ("a3");
Here a3 is the name of the register which should be used. Choose a register which is normally saved and restored by function calls on your machine, so that library routines will not clobber it.

Naturally the register name is cpu-dependent, so you would need to conditionalize your program according to cpu type. The register a3 would be a good choice on a 68000 for a variable of pointer type. On machines with register windows, be sure to choose a "global" register that is not affected magically by the function call mechanism.

In addition, operating systems on one type of cpu may differ in how they name the registers; then you would need additional conditionals. For example, some 68000 operating systems call this register %a3.

Eventually there may be a way of asking the compiler to choose a register automatically, but first we need to figure out how it should choose and how to enable you to guide the choice. No solution is evident.

Defining a global register variable in a certain register reserves that register entirely for this use, at least within the current compilation. The register will not be allocated for any other purpose in the functions in the current compilation. The register will not be saved and restored by these functions. Stores into this register are never deleted even if they would appear to be dead, but references may be deleted or moved or simplified.

It is not safe to access the global register variables from interrupt handlers, because the system library routines may temporarily use the register for other things (unless you recompile them specially for the task at hand).

It is not safe for one function that uses a global register variable to call another such function foo by way of a third function lose that was compiled without knowledge of this variable (i.e. in a different source file in which the variable wasn't declared). This is because lose might save the register and put some other value there. For example, you can't expect a global register variable to be available in the comparison-function that you pass to qsort, since it might have put something else in that register. (If you are prepared to recompile it with the same global register variable, you can solve this problem.)

If you want to recompile qsort or other source files which do not actually use your global register variable, so that they will not use that register for any other purpose, then it suffices to specify the compiler option '-ffixed-reg'. You need not actually add a global register declaration to their source code.

A function which can alter the value of a global register variable cannot safely be called from a function compiled without this variable, because it could clobber the value the caller expects to find there on return. Therefore, the function which is the entry point into the part of the program that uses the global register variable must explicitly save and restore the value which belongs to its caller.

Be careful if you use longjmp with global register variables, because it will restore to each global register variable the value it had at the time of the setjmp.

All global register variable declarations must precede all function definitions. If such a declaration could appear after function definitions, the declaration would be too late to prevent the register from being used for other purposes in the preceding functions.

Global register variables may not have initial values, because an executable file has no means to supply initial contents for a register.

On the Motorola 68000, a2 ... a5 should be suitable for global register variables, as should d3 ... d7. Of course, it will not do to use more than a few of those. Note that a5 is used by OPTIMIZE_ROM_CALLS.


Specifying Registers for Local Variables
Previous Variables in Specified Registers Next

Local register variables in specific registers do not reserve the registers. The compiler's data flow analysis is capable of determining where the specified registers contain live values, and where they are available for other uses. Stores into local register variables may be deleted when they appear to be dead according to dataflow analysis. References to local register variables may be deleted or moved or simplified.

These local variables are sometimes convenient for use with the extended asm feature (see the section Assembler Instructions with C Expression Operands), if you want to write one output of the assembler instruction directly into a particular register (this will work provided the register you specify fits the constraints specified for that operand in the asm block).

You can define a local register variable with a specified register like this:

register int *foo asm ("a5");
Here a5 is the name of the register which should be used. Note that this is the same syntax used for defining global register variables, but for a local variable it would appear within a function.

Naturally the register name is cpu-dependent, but this is not a problem, since specific registers are most often useful with explicit assembler instructions (see the section Assembler Instructions with C Expression Operands), which is CPU-specific as well, and since GCC4TI only supports exactly one CPU (the Motorola 68000) anyway.

In addition, operating systems on one type of cpu may differ in how they name the registers; then you would need additional conditionals. For example, some 68000 operating systems call this register %a5.

Defining such a register variable does not reserve the register; it remains available for other uses in places where flow control determines the variable's value is not live. However, these registers are made unavailable for use in the reload pass; excessive use of this feature leaves the compiler too few available registers to compile certain functions.

This option does not guarantee that GCC will generate code that has this variable in the register you specify at all times. You may not code an explicit reference to this register in an asm statement and assume it will always refer to this variable.

Stores into local register variables may be deleted when they appear to be dead according to dataflow analysis. References to local register variables may be deleted or moved or simplified.


Specifying Registers for Function Parameters
Previous Variables in Specified Registers

In GCC4TI, it is possible to specify explictly where the parameters to a function a stored, in a syntax similar to global and local register variables.

GCC4TI can pass function parameters either on the stack or through registers. You can use the regparm attribute or the '-mregparm' compiler switch to let the compiler automatically choose registers for the parameters, but you can also tell GCC4TI to put a parameter into a specific register. This can be very handy when interfacing with assembly code. For example, the following assembly function expects its 2 parameters in the d1 and d2 registers:

asm(".globl add
add:
     move.l %d2,%d0
     add.l %d1,%d0
     rts");
Therefore, its prototype would be:
unsigned long add (unsigned long a asm("d1"), unsigned long b asm("d2"));
Explicit register specifications for function parameters are also supported in function headers (not only in prototypes). Therefore, the assembly function above could be replaced by the following C equivalent:
unsigned long add (unsigned long a asm("d1"), unsigned long b asm("d2"))
{
  return a + b;
}
to pass a register parameter. The registers do not necessarily need to be call-clobbered. You can also use a2-a5/d3-d7 to pass a register parameter. But note that the called function still has to save and restore those registers, even if they are used as arguments! In C code, GCC4TI takes care of that automatically for you, but in assembly code, it is something you need to remember.

See also: regparm


Alternate Keywords
Previous GNU C Language Extensions Next

'-ansi' and the various '-std' options disable certain keywords. This causes trouble when you want to use GNU C extensions, or a general-purpose header file that should be usable by all programs, including ISO C programs. The keywords asm, typeof and inline are not available in programs compiled with '-ansi' or '-std' (although inline can be used in a program compiled with '-std=c99'). The ISO C99 keyword restrict is only available when '-std=gnu99' (which will eventually be the default) or '-std=c99' (or the equivalent '-std=iso9899:1999') is used.

The way to solve these problems is to put __ at the beginning and end of each problematical keyword. For example, use __asm__ instead of asm, and __inline__ instead of inline.

Other C compilers won't accept these alternative keywords; if you want to compile with another compiler, you can define the alternate keywords as macros to replace them with the customary keywords. It looks like this:

#ifndef __GNUC__
#define __asm__ asm
#endif
'-pedantic' and other options cause warnings for many GNU C extensions. You can prevent such warnings within one expression by writing __extension__ before the expression. __extension__ has no effect aside from this.


Incomplete 'enum' Types
Previous GNU C Language Extensions Next

You can define an enum tag without specifying its possible values. This results in an incomplete type, much like what you get if you write struct foo without describing the elements. A later declaration which does specify the possible values completes the type.

You can't allocate variables or storage using the type while it is incomplete. However, you can work with pointers to that type.

This extension may not be very useful, but it makes the handling of enum more consistent with the way struct and union are handled.


Function Names as Strings
Previous GNU C Language Extensions Next

GCC predefines two magic identifiers to hold the name of the current function. The identifier __FUNCTION__ holds the name of the function as it appears in the source. The identifier __PRETTY_FUNCTION__ holds the name of the function pretty printed in a language specific fashion. (These names are always the same in a C function, but in a C++ function they may be different; don't care about this, because GCC4TI is not a C++ compiler.)

The compiler automatically replaces the identifiers with a string literal containing the appropriate name. Thus, they are neither preprocessor macros, like __FILE__ and __LINE__, nor variables. This means that they catenate with other string literals, and that they can be used to initialize char arrays. For example

char here[] = "Function " __FUNCTION__ " in " __FILE__;
On the other hand, #ifdef __FUNCTION__ does not have any special meaning inside a function, since the preprocessor does not do anything special with the identifier __FUNCTION__.

Note that these semantics are deprecated, and that GCC 3.2 will handle __FUNCTION__ and __PRETTY_FUNCTION__ the same way as __func__. __func__ is defined by the ISO standard C99:

The identifier __func__ is implicitly declared by the translator as if, immediately following the opening brace of each function definition, the declaration
static const char __func__[] = "function-name";
appeared, where function-name is the name of the lexically-enclosing function. This name is the unadorned name of the function.

By this definition, __func__ is a variable, not a string literal. In particular, __func__ does not catenate with other string literals.


Getting the Return or Frame Address of a Function
Previous GNU C Language Extensions Next

These functions may be used to get information about the callers of a function.

  • __builtin_return_address
  • __builtin_frame_address


__builtin_return_address
Getting the Return or Frame Address of a Function Next

void *__builtin_return_address (int level);

This function returns the return address of the current function, or of one of its callers. The level argument is number of frames to scan up the call stack. A value of 0 yields the return address of the current function, a value of 1 yields the return address of the caller of the current function, and so forth. When inlining the expected behavior is that the function will return the address of the function that will be returned to. To work around this behavior use the noinline function attribute.

The level argument must be a constant integer.

Sometimes (especially without a frame pointer) it may be impossible to determine the return address of any function other than the current one; in such cases, or when the top of the stack has been reached, this function will return a random value. In addition, __builtin_frame_address may be used to determine if the top of the stack has been reached.

This function should be used with a nonzero argument only for debugging purposes.


__builtin_frame_address
Previous Getting the Return or Frame Address of a Function

void *__builtin_frame_address (int level);

This function is similar to __builtin_return_address, but it returns the address of the function frame rather than the return address of the function. Calling __builtin_frame_address with a value of 0 yields the frame address of the current function, a value of 1 yields the frame address of the caller of the current function, and so forth.

The frame is the area on the stack which holds local variables and saved registers. The frame address is normally the address of the first word pushed on to the stack by the function. However, the exact definition depends upon the processor and the calling convention. On the Motorola 68000, if the function has a frame, then __builtin_frame_address will return the value of the frame pointer register a6 if level is 0.

This function should be used with a nonzero argument only for debugging purposes.


Other built-in functions provided by GCC
Previous GNU C Language Extensions Next

GCC provides a large number of built-in functions. Some of these are for internal use in the processing of exceptions or variable-length argument lists and will not be documented here because they may change from time to time; we do not recommend general use of these functions.

The remaining functions are provided for optimization purposes.

  • __builtin_constant_p
  • __builtin_types_compatible_p
  • __builtin_choose_expr
  • __builtin_expect
  • __builtin_prefetch

GCC includes built-in versions of many of the functions in the standard C library. The versions prefixed with __builtin_ will always be treated as having the same meaning as the C library function even if you specify the '-fno-builtin' option (see C Dialect Options). Many of these functions are only optimized in certain cases; if they are not optimized in a particular case, a call to the library function will be emitted (but this does not make sense in GCC4TI, as the standard C library is not provided with it).

The functions abort, exit, _Exit and _exit are recognized and presumed not to return, but otherwise are not built in (GCC4TI defines them as macros anyway). _exit is not recognized in strict ISO C mode ('-ansi', '-std=c89' or '-std=c99'). _Exit is not recognized in strict C89 mode ('-ansi' or '-std=c89'). All these functions have corresponding versions prefixed with __builtin_, which may be used even in strict C89 mode.

Outside strict ISO C mode, the functions alloca, bcmp, bzero, index, rindex, ffs, fputs_unlocked, printf_unlocked and fprintf_unlocked may be handled as built-in functions. All these functions have corresponding versions prefixed with __builtin_, which may be used even in strict C89 mode (in GCC4TI, alloca is built-in; other than that only __builtin_bzero might be useful).

The ISO C99 functions conj, conjf, conjl, creal, crealf, creall, cimag, cimagf, cimagl, imaxabs, llabs, snprintf, vscanf, vsnprintf and vsscanf are handled as built-in functions except in strict ISO C90 mode. There are also built-in versions of the ISO C99 functions cosf, cosl, expf, expl, fabsf, fabsl, logf, logl, sinf, sinl, sqrtf, and sqrtl, that are recognized in any mode since ISO C90 reserves these names for the purpose to which ISO C99 puts them. All these functions have corresponding versions prefixed with __builtin_ (again, none of these are implemented in GCC4TI).

The ISO C90 functions abs, cos, exp, fabs, fprintf, fputs, labs, log, memcmp, memcpy, memset, printf, putchar, puts, scanf, sin, snprintf, sprintf, sqrt, sscanf, strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat, strncmp, strncpy, strpbrk, strrchr, strspn, strstr, vprintf and vsprintf are all recognized as built-in functions unless '-fno-builtin' is specified (or '-fno-builtin-function' is specified for an individual function). All of these functions have corresponding versions prefixed with __builtin_ (but most of these are defined as macros in GCC4TI).

GCC provides built-in versions of the ISO C99 floating point comparison macros that avoid raising exceptions for unordered operands. They have the same names as the standard macros (isgreater, isgreaterequal, isless, islessequal, islessgreater, and isunordered), with __builtin_ prefixed. The GNU team intends for a library implementor to be able to simply #define each standard macro to its built-in equivalent.


__builtin_constant_p
Other built-in functions provided by GCC Next

int __builtin_constant_p (exp);

You can use the built-in function __builtin_constant_p to determine if a value is known to be constant at compile-time and hence that GCC can perform constant-folding on expressions involving that value. The argument of the function is the value to test. The function returns the integer 1 if the argument is known to be a compile-time constant and 0 if it is not known to be a compile-time constant. A return of 0 does not indicate that the value is not a constant, but merely that GCC cannot prove it is a constant with the specified value of the '-O' option.

If you have some complex calculation, you may want it to be folded if it involves constants, but need to call a function if it does not. For example:

#define Scale_Value(X)      \
  (__builtin_constant_p (X) \
  ? ((X) * SCALE + OFFSET) : Scale (X))
You may use this built-in function in either a macro or an inline function. However, if you use it in an inlined function and pass an argument of the function as the argument to the built-in, GCC will never return 1 when you call the inline function with a string constant or compound literal (see Compound Literals) and will not return 1 when you pass a constant numeric value to the inline function unless you specify the '-O' option.

You may also use __builtin_constant_p in initializers for static data. For instance, you can write
static const int table[] = {
   __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
   /* ... */
};
This is an acceptable initializer even if EXPRESSION is not a constant expression. GCC must be more conservative about evaluating the built-in in this case, because it has no opportunity to perform optimization.

Previous versions of GCC did not accept this built-in in data initializers. The earliest version where it is completely safe is 3.0.1.


__builtin_types_compatible_p
Previous Other built-in functions provided by GCC Next

int __builtin_types_compatible_p (type1, type2);

You can use the built-in function __builtin_types_compatible_p to determine whether two types are the same.

This built-in function returns 1 if the unqualified versions of the types type1 and type2 (which are types, not expressions) are compatible, 0 otherwise. The result of this built-in function can be used in integer constant expressions.

This built-in function ignores top level qualifiers (const, volatile, etc.). For example, int is equivalent to const int.

The type int[] and int[5] are compatible. On the other hand, long int and char* are not compatible, although their sizes are the same. Also, the amount of pointer indirection is taken into account when determining similarity. Consequently, short* is not similar to short**. Furthermore, two types that are typedefed are considered compatible if their underlying types are compatible.

An enum type is considered to be compatible with another enum type. For example, enum {foo, bar} is similar to enum {hot, dog}.

You would typically use this function in code whose execution varies depending on the arguments' types. For example:

#define foo(x)                                                  \
  ({                                                            \
    typeof (x) tmp;                                             \
    if (__builtin_types_compatible_p (typeof (x), long double)) \
      tmp = foo_long_double (tmp);                              \
    else if (__builtin_types_compatible_p (typeof (x), double)) \
      tmp = foo_double (tmp);                                   \
    else if (__builtin_types_compatible_p (typeof (x), float))  \
      tmp = foo_float (tmp);                                    \
    else                                                        \
      abort ();                                                 \
    tmp;                                                        \
  })


__builtin_choose_expr
Previous Other built-in functions provided by GCC Next

type __builtin_choose_expr (const_exp, exp1, exp2);

You can use the built-in function __builtin_choose_expr to evaluate code depending on the value of a constant expression. This built-in function returns exp1 if const_exp, which is a constant expression that must be able to be determined at compile time, is nonzero. Otherwise it returns 0.

This built-in function is analogous to the ? : operator in C, except that the expression returned has its type unaltered by promotion rules. Also, the built-in function does not evaluate the expression that was not chosen. For example, if const_exp evaluates to true, exp2 is not evaluated even if it has side-effects.

This built-in function can return an lvalue if the chosen argument is an lvalue.

If exp1 is returned, the return type is the same as exp1's type. Similarly, if exp2 is returned, its return type is the same as exp2.

Example:

#define foo(x)                                                    \
  __builtin_choose_expr (                                         \
    __builtin_types_compatible_p (typeof (x), double),            \
    foo_double (x),                                               \
    __builtin_choose_expr (                                       \
      __builtin_types_compatible_p (typeof (x), float),           \
      foo_float (x),                                              \
      /* The void expression results in a compile-time error  \
         when assigning the result to something.  */          \
      (void)0))
Note: The unused expression (exp1 or exp2 depending on the value of const_exp) may still generate syntax errors. This may change in future revisions.


__builtin_expect
Previous Other built-in functions provided by GCC Next

long __builtin_expect (long exp, long c);

You may use __builtin_expect to provide the compiler with branch prediction information.

The return value is the value of exp, which should be an integral expression. The value of c must be a compile-time constant. The semantics of the built-in are that it is expected that exp == c. For example:

if (__builtin_expect (x, 0))
  foo ();
would indicate that we do not expect to call foo, since we expect x to be zero. Since you are limited to integral expressions for exp, you should use constructions such as
if (__builtin_expect (ptr != NULL, 1))
  error ();
when testing pointer or floating-point values.


__builtin_prefetch
Previous Other built-in functions provided by GCC

void __builtin_prefetch (const void *addr, ...);

This function is used to minimize cache-miss latency by moving data into a cache before it is accessed. As the Motorola 68000 processor does not have any data prefetch instruction, this function is not useful in GCC4TI.


Slightly Looser Rules for Escaped Newlines
Previous GNU C Language Extensions Next

Recently, the preprocessor has relaxed its treatment of escaped newlines. Previously, the newline had to immediately follow a backslash. The current implementation allows whitespace in the form of spaces, horizontal and vertical tabs, and form feeds between the backslash and the subsequent newline. The preprocessor issues a warning, but treats it as a valid escaped newline and combines the two lines to form a single logical line. This works within comments and tokens, including multi-line strings, as well as between tokens. Comments are not treated as whitespace for the purposes of this relaxation, since they have not yet been replaced with spaces.


String Literals with Embedded Newlines
Previous GNU C Language Extensions Next

As an extension, GNU CPP permits string literals to cross multiple lines without escaping the embedded newlines. Each embedded newline is replaced with a single \n character in the resulting string literal, regardless of what form the newline took originally.

CPP currently allows such strings in directives as well (other than the #include family).


Mixed Declarations and Code
Previous GNU C Language Extensions Next

ISO C99 and ISO C++ allow declarations and code to be freely mixed within compound statements. As an extension, GCC also allows this in C89 mode. For example, you could do:

int i;
/* ... */
i++;
int j = i + 2;
Each identifier is visible from where it is declared until the end of the enclosing block.


Unnamed struct/union Fields within structs/unions
Previous GNU C Language Extensions Next

For compatibility with other compilers, GCC allows you to define a structure or union that contains, as fields, structures and unions without names. For example:

struct {
  int a;
  union {
    int b;
    float c;
  };
  int d;
} foo;
In this example, the user would be able to access members of the unnamed union with code like foo.b. Note that only unnamed structs and unions are allowed, you may not have, for example, an unnamed int.

You must never create such structures that cause ambiguous field definitions. For example, this structure:
struct {
  int a;
  struct {
    int a;
  };
} foo;
It is ambiguous which a is being referred to with foo.a. Such constructs are not supported and must be avoided. In the future, such constructs may be detected and treated as compilation errors.


Definite Access of Volatile Objects
Previous GNU C Language Extensions Next

Both the C and C++ standard have the concept of volatile objects. These are normally accessed by pointers and used for accessing hardware. The standards encourage compilers to refrain from optimizations concerning accesses to volatile objects that it might perform on non-volatile objects. The C standard leaves it implementation defined as to what constitutes a volatile access. The C++ standard omits to specify this, except to say that C++ should behave in a similar manner to C with respect to volatiles, where possible. The minimum either standard specifies is that at a sequence point all previous accesses to volatile objects have stabilized and no subsequent accesses have occurred. Thus an implementation is free to reorder and combine volatile accesses which occur between sequence points, but cannot do so for accesses across a sequence point. The use of volatiles does not allow you to violate the restriction on updating objects multiple times within a sequence point.

In most expressions, it is intuitively obvious what is a read and what is a write. For instance

volatile int *dst = somevalue;
volatile int *src = someothervalue;
*dst = *src;
will cause a read of the volatile object pointed to by src and stores the value into the volatile object pointed to by dst. There is no guarantee that these reads and writes are atomic, especially for objects larger than int.

Less obvious expressions are where something which looks like an access is used in a void context. An example would be,
volatile int *src = somevalue;
*src;
With C, such expressions are rvalues, and as rvalues cause a read of the object, GCC interprets this as a read of the volatile being pointed to.


History
Previous GNU C Language Extensions

  • Original Version: Extensions to the C Language Family

    Published by the Free Software Foundation
    59 Temple Place - Suite 330
    Boston, MA 02111-1307 USA

    Copyright © 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.

  • Modifications for TIGCC: GNU C Language Extensions

    Published by the TIGCC Team

    Copyright © 2000, 2001, 2002 Zeljko Juric, Sebastian Reichelt, Kevin Kofler
  • Modifications for GCC4TI: GNU C Language Extensions

    Published by the GCC4TI Project

    Copyright © 2009, 2010 Lionel Debroux


GCC Command-Line Options

This part of the documentation is a modified version of the Command-Line Options section of the GCC Manual. Therefore it is licensed under the GNU Free Documentation License.

This section describes the options supported by gcc, the driver program of the GNU Compiler Collection, whose C compiler and assembler are used here. This program is called either by tigcc or by the IDE. tigcc simulates some of these options itself, namely '-E', '-S', and '-c', and it also has some additional ones. In the IDE, there is an item in the project settings where you can set the options described here, with some exceptions, including the switches mentioned above.

GCC4TI normally does preprocessing, compilation, assembly and linking all in one step, and finally produces a file which is executable on the calculator. The "overall options" allow you to stop this process at an intermediate stage. For example, the '-c' option says not to run the linker. Then the output consists of object files output by the assembler.

Other options are passed on to one stage of processing. Some options control the preprocessor and others the compiler itself. Yet other options control the assembler and linker; most of these are not documented here, since you rarely need to use any of them. In fact, only those options which may be more or less useful with GCC4TI are mentioned here (although we didn't check whether all of them are really usable in GCC4TI). For more info about standard options that are recognized by the compiler, read the official manual.

We suggest that you use the '-O2' switch in all of your compilations; it increases speed and decreases the program size at the cost of compilation time.

tigcc accepts options and file names as operands. Many options have multi-letter names; therefore multiple single-letter options may not be grouped: '-dr' is very different from '-d -r'.

You can mix options and other arguments. For the most part, the order you use doesn't matter. Order does matter when you use several options of the same kind; for example, if you specify '-L' more than once, the directories are searched in the order specified.

Many options have long names starting with '-f' or with '-W' - for example, '-fforce-mem', '-fstrength-reduce', '-Wformat' and so on. Most of these have both positive and negative forms; the negative form of '-ffoo' would be '-fno-foo'. This manual documents only one of these two forms, whichever one is not the default.

  • Options Available in the Command Line Compiler
  • Options Controlling the Kind of Output
  • Options Controlling C Dialect
  • Options to Request or Suppress Warnings
  • Options for Debugging Your Program
  • Options That Control Optimization
  • Options Controlling the Preprocessor
  • Passing Options to the Assembler and Linker
  • Options for Directory Search
  • GCC Spec Strings
  • M680x0 Target Options
  • Options for Code Generation Conventions
  • Environment Variables Affecting GCC
  • History
  • GNU General Public License
  • GNU Free Documentation License
  • Funding Free Software

Original author: Free Software Foundation, Inc.
Authors of the modifications: Zeljko Juric, Sebastian Reichelt, and Kevin Kofler.
Published by the TIGCC Team, and now the GCC4TI project.
See the History section for details and copyright information.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License" and "Funding Free Software", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the section entitled "GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.


Options Available in the Command Line Compiler
GCC Command-Line Options Next

These options apply only to the command line compiler. If you want to use the IDE instead, you do not need to worry about these topics.

tigcc has an important difference to the standard program gcc: tigcc always overwrites assembly or object files. For example, if a file test.c is compiled, the files test.s and test.o will be created and overwritten if necessary, but they will automatically be deleted again if neither '-c' nor '-S' are specified.

Another important difference is that tigcc always looks for libraries in the 'Lib' subfolder of the installation.

-pack varname
Compress the file generated during compilation. varname is the name of the on-calc packed variable. Although varname cannot have an extension, the variable on the calculator will always have the extension ppg. varname cannot be the same as the on-calc name of the program itself. When you use this switch, two files will be created; one with the extension .89y or .9xy, and one .89z or .9xz file.

This option comes from Thomas Nussbaumer's TI-68k Developer Utilities (now built in GCC4TI), where this feature is called "ExePack Technology." You can read about it on the official TI-Chess Team site.

-q
Keep as quiet as possible while assembling and linking. This option is not needed by the compiler because it is always quiet, but the linker and especially the assembler output some information.

-v0
This switch is an addition to the '-v' switch. It tells GCC4TI to output only the commands that are run directly. This was the default in some previous releases.

-g
The '-g' switch in GCC turns on debugging information in the preferred format for the target. In GCC4TI, this is DWARF 2, which can be used with a GDB-enabled TiEmu.

-standalone
Do not link against tigcc.a. All of GCC's internal functions are implemented in this library, as well as all non-TIOS functions. Using one of these will result in an error from the linker.

-ar
Create an archive (a static library) instead of a program. The resulting file will have an .a ending.

-bsr
This option is ignored for compatibility.
In addition to these options, the tigcc program also accepts most of the linker options.


Options Controlling the Kind of Output
Previous GCC Command-Line Options Next

Compilation can involve up to four stages: preprocessing, compilation proper, assembly and linking, always in that order. The first three stages apply to an individual source file, and end by producing an object file; linking combines all the object files (those newly compiled, and those specified as input) into an executable file.

For any given input file, the file name suffix determines what kind of compilation is done (some of these apply only to TIGCC/GCC4TI):

file.c
C source code which must be preprocessed.

file.s
GNU Assembler code.

file.S
GNU Assembler code which must be preprocessed.

file.asm
A68k Assembler code.

file.o
COFF object file to be linked using ld.

file.a
Static library (function archive) to be linked using ld.
You can specify the input language explicitly with the '-x' option:
-x language
Specify explicitly the language for the following input files (rather than letting the compiler choose a default based on the file name suffix). This option applies to all following input files until the next '-x' option. Possible values for language are:
c c-header cpp-output c++ c++-cpp-output objective-c objc-cpp-output assembler assembler-with-cpp ada f77 f77-cpp-input ratfor java treelang
-x none
Turn off any specification of a language, so that subsequent files are handled according to their file name suffixes (as they are if '-x' has not been used at all).

-pass-exit-codes
Normally the gcc program will exit with the code of 1 if any phase of the compiler returns a non-success return code. If you specify '-pass-exit-codes', the gcc program will instead return with numerically highest error produced by any phase that returned an error indication.
If you only want some of the stages of compilation, you can use '-x' (or filename suffixes) to tell gcc where to start, and one of the options '-c', '-S', or '-E' to say where gcc is to stop. Note that some combinations (for example, '-x cpp-output -E') instruct gcc to do nothing at all.
-c
Compile or assemble the source files, but do not link. The linking stage simply is not done. The ultimate output is in the form of an object file for each source file.

By default, the object file name for a source file is made by replacing the suffix .c, .i, .s, etc., with .o.

Unrecognized input files, not requiring compilation or assembly, are ignored.

-S
Stop after the stage of compilation proper; do not assemble. The output is in the form of an assembler code file for each non-assembler input file specified.

By default, the assembler file name for a source file is made by replacing the suffix .c, .i, etc., with .s.

Input files that don't require compilation are ignored.

-E
Stop after the preprocessing stage; do not run the compiler proper. The output is in the form of preprocessed source code, which is sent to the standard output.

Input files which don't require preprocessing are ignored.

-o file
Place output in file file. This applies regardless to whatever sort of output is being produced, whether it be an executable file, an object file, an assembler file or preprocessed C code.

Since only one output file can be specified, it does not make sense to use '-o' when compiling more than one input file, unless you are producing an executable file as output.

If '-o' is not specified, the default is to put an executable file in a.out, the object file for source.suffix in source.o, its assembler file in source.s, and all preprocessed C source on standard output.

-v
Print (on standard error output) the commands executed to run the stages of compilation. Also print the version number of the compiler driver program and of the preprocessor and the compiler proper.

-###
Like '-v' except the commands are not executed and all command arguments are quoted. This is useful for shell scripts to capture the driver-generated command lines.

-pipe
Use pipes rather than temporary files for communication between the various stages of compilation. This fails to work on some systems where the assembler is unable to read from a pipe; but the GNU assembler has no trouble.

--help
Print (on the standard output) a description of the command line options understood by gcc. If the '-v' option is also specified then '--help' will also be passed on to the various processes invoked by gcc, so that they can display the command line options they accept. If the '-W' option is also specified then command line options which have no documentation associated with them will also be displayed.

--target-help
Print (on the standard output) a description of target specific command line options for each tool.

--version
Display the version number and copyrights of the invoked GCC.


Options Controlling C Dialect
Previous GCC Command-Line Options Next

The following options control the dialect of C that the compiler accepts:

-ansi
Support all ISO C89 programs. This turns off certain features of GCC that are incompatible with ISO C89, such as the asm and typeof keywords, and some predefined macros that identify the type of system you are using. It also enables the undesirable and rarely used ISO trigraph feature, and disables recognition of C++ style // comments as well as the inline keyword.

The alternate keywords __asm__, __extension__, __inline__ and __typeof__ continue to work despite '-ansi'. You would not want to use them in an ISO C program, of course, but it is useful to put them in header files that might be included in compilations done with '-ansi'. Alternate predefined macros such as __unix__ are also available, with or without '-ansi'.

The '-ansi' option does not cause non-ISO programs to be rejected gratuitously. For that, '-pedantic' is required in addition to '-ansi'. See Warning Options.

The macro __STRICT_ANSI__ is predefined when the '-ansi' option is used. Some header files may notice this macro and refrain from declaring certain functions or defining certain macros that the ISO standard doesn't call for; this is to avoid interfering with any programs that might use these names for other things.

Functions which would normally be built in but do not have semantics defined by ISO C (such as alloca) are not built-in functions with '-ansi' is used. See Other built-in functions provided by GCC for details of the functions affected.

Note: At the moment, the GCC4TI library depends heavily on GNU C extensions, so you cannot use the '-ansi' switch in GCC4TI.

-std=standard
Determine the language standard. A value for standard must be provided; provided; possible values are

c89
iso9899:1990
ISO C90 (same as '-ansi').

iso9899:199409
ISO C90 as modified in amendment 1.

c99
c9x
iso9899:1999
iso9899:199x
ISO C99. Note that this standard is not yet fully supported; see http://gcc.gnu.org/gcc-3.3/c99status.html for more information. The names c9x and iso9899:199x are deprecated.

gnu89
Default, ISO C90 plus GNU extensions (including some C99 features).

gnu99
gnu9x
ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC, this will become the default. The name gnu9x is deprecated.

Even when this option is not specified, you can still use some of the features of newer standards in so far as they do not conflict with previous C standards. For example, you may use __restrict__ even when '-std=c99' is not specified.

The '-std' options specifying some version of ISO C have the same effects as '-ansi', except that features that were not in ISO C90 but are in the specified version (for example, // comments and the inline keyword in ISO C99) are not disabled.

-aux-info filename
Output to the given filename prototyped declarations for all functions declared and/or defined in a translation unit, including those in header files. This option is silently ignored in any language other than C.

Besides declarations, the file indicates, in comments, the origin of each declaration (source file and line), whether the declaration was implicit, prototyped or unprototyped (I, N for new or O for old, respectively, in the first character after the line number and the colon), and whether it came from a declaration or a definition (C or F, respectively, in the following character). In the case of function definitions, a K&R-style list of arguments followed by their declarations is also provided, inside comments, after the declaration.

-fno-asm
Do not recognize asm, inline or typeof as a keyword, so that code can use these words as identifiers. You can use the keywords __asm__, __inline__ and __typeof__ instead. '-ansi' implies '-fno-asm'.

-fno-builtin
-fno-builtin-function
Don't recognize built-in functions that do not begin with __builtin_ as prefix. See Other built-in functions provided by GCC for details of the functions affected, including those which are not built-in functions when '-ansi' or '-std' options for strict ISO C conformance are used because they do not have an ISO standard meaning.

GCC normally generates special code to handle certain built-in functions more efficiently; for instance, calls to alloca may become single instructions that adjust the stack directly. The resulting code is often both smaller and faster, but since the function calls no longer appear as such, you cannot set a breakpoint on those calls, nor can you change the behavior of the functions by linking with a different library.

With the '-fno-builtin-function' option, only the built-in function function is disabled. function must not begin with __builtin_. If a function is named this is not built-in in this version of GCC, this option is ignored. There is no corresponding '-fbuiltin-function' option; if you wish to enable built-in functions selectively when using '-fno-builtin' or '-ffreestanding', you may define macros such as:
#define abs(n)          __builtin_abs ((n))
#define strcpy(d, s)    __builtin_strcpy ((d), (s))
-fhosted
Assert that compilation takes place in a hosted environment. This implies '-fbuiltin'. A hosted environment is one in which the entire standard library is available, and in which main has a return type of int. Examples are nearly everything except a kernel. This is equivalent to '-fno-freestanding'.

Although TI calculators are not really hosted environments, '-fhosted' is kept as the default.

-ffreestanding
Assert that compilation takes place in a freestanding environment. This implies '-fno-builtin'. A freestanding environment is one in which the standard library may not exist, and program startup may not necessarily be at main. The most obvious example is an OS kernel. This is equivalent to '-fno-hosted'.

-fms-extensions
Accept some non-standard constructs used in Microsoft header files.

-trigraphs
Support ISO C trigraphs. The '-ansi' option (and '-std' options for strict ISO C conformance) implies '-trigraphs'. See Options Controlling the Preprocessor for more information.

-no-integrated-cpp
Performs a compilation in two passes: preprocessing and compiling. This option allows a user supplied "cc1" via the '-B' option. The user supplied compilation step can then add in an additional preprocessing step after normal preprocessing but before compiling. The default is to use the integrated preprocessor.

The semantics of this option will change if "cc1", "cc1plus", and "cc1obj" are merged.

-traditional
-traditional-cpp
Formerly, these options caused GCC to attempt to emulate a pre-standard C compiler. They are now only supported with the '-E' switch. The preprocessor continues to support a pre-standard mode.

-fcond-mismatch
Allow conditional expressions with mismatched types in the second and third arguments. The value of such an expression is void.

-funsigned-char
Let the type char be unsigned, like unsigned char. In GCC4TI, the default is signed char.

Ideally, a portable program should always use signed char or unsigned char when it depends on the signedness of an object. But many programs have been written to use plain char and expect it to be signed, or expect it to be unsigned, depending on the machines they were written for. This option, and its inverse, let you make such a program work with the opposite default.

The type char is always a distinct type from each of signed char or unsigned char, even though its behavior is always just like one of those two.

-fsigned-char
Let the type char be signed, like signed char.

Note that this is equivalent to '-fno-unsigned-char', which is the negative form of '-funsigned-char'. Likewise, the option '-fno-signed-char' is equivalent to '-funsigned-char'.

-fsigned-bitfields
-funsigned-bitfields
-fno-signed-bitfields
-fno-unsigned-bitfields
These options control whether a bit-field is signed or unsigned, when the declaration does not use either signed or unsigned. By default, such a bit-field is signed, because this is consistent: the basic integer types such as int are signed types.

-fwritable-strings
Store string constants in the writable data segment and don't uniquize them. This is for compatibility with old programs which assume they can write into string constants.

Writing into string constants is a very bad idea; "constants" should be constant.


Options to Request or Suppress Warnings
Previous GCC Command-Line Options Next

Warnings are diagnostic messages that report constructions which are not inherently erroneous but which are risky or suggest there may have been an error.

You can request many specific warnings with options beginning '-W', for example '-Wimplicit' to request warnings on implicit declarations. Each of these specific warning options also has a negative form beginning '-Wno-' to turn off warnings; for example, '-Wno-implicit'. This manual lists only one of the two forms, whichever is not the default.

The following options control the amount and kinds of warnings produced by GCC.

-fsyntax-only
Check the code for syntax errors, but don't do anything beyond that.

-pedantic
Issue all the warnings demanded by strict ISO C; reject all programs that use forbidden extensions, and some other programs that do not follow ISO C. This option follows the version of the ISO C standard specified by any '-std' option used.

Valid ISO C programs should compile properly with or without this option (though a rare few will require '-ansi' or a '-std' option specifying the required version of ISO C). However, without this option, certain GNU extensions and traditional C features are supported as well. With this option, they are rejected.

'-pedantic' does not cause warning messages for use of the alternate keywords whose names begin and end with __. Pedantic warnings are also disabled in the expression that follows __extension__. However, only system header files should use these escape routes; application programs should avoid them. See Alternate Keywords.

Some users try to use '-pedantic' to check programs for strict ISO C conformance. They soon find that it does not do quite what they want: it finds some non-ISO practices, but not all - only those for which ISO C requires a diagnostic, and some others for which diagnostics have been added.

A feature to report any failure to conform to ISO C might be useful in some instances, but would require considerable additional work and would be quite different from '-pedantic'. The GNU team doesn't have plans to support such a feature in the near future.

Where the standard specified with '-std' represents a GNU extended dialect of C, such as gnu89 or gnu99, there is a corresponding base standard, the version of ISO C on which the GNU extended dialect is based. Warnings from '-pedantic' are given where they are required by the base standard. (It would not make sense for such warnings to be given only for features not in the specified GNU C dialect, since by definition the GNU dialects of C include all features the compiler supports with the given option, and there would be nothing to warn about.)

-pedantic-errors
Like '-pedantic', except that errors are produced rather than warnings.

-w
Inhibit all warning messages.

-Wno-import
Inhibit warning messages about the use of #import.

-Wchar-subscripts
Warn if an array subscript has type char. This is a common cause of error, as programmers often forget that this type is signed on some machines.

-Wcomment
Warn whenever a comment-start sequence /* appears in a /* comment, or whenever a Backslash-Newline appears in a // comment.

-Wformat
Check calls to printf and scanf, etc., to make sure that the arguments supplied have types appropriate to the format string specified, and that the conversions specified in the format string make sense. This includes standard functions, and others specified by format attributes (see format).

Since '-Wformat' also checks for null format arguments for several functions, '-Wformat' also implies '-Wnonnull'.

'-Wformat' is included in '-Wall'. For more control over some aspects of format checking, the options '-Wno-format-extra-args', '-Wno-format-zero-length', '-Wformat-nonliteral', '-Wformat-security', and '-Wformat=2' are available, but are not included in '-Wall'.

-Wno-format-extra-args
If '-Wformat' is specified, do not warn about excess arguments to a printf or scanf format function. The C standard specifies that such arguments are ignored.

-Wno-format-zero-length
If '-Wformat' is specified, do not warn about zero-length formats. The C standard specifies that zero-length formats are allowed.

-Wformat-nonliteral
If '-Wformat' is specified, also warn if the format string is not a string literal and so cannot be checked, unless the format function takes its format arguments as a va_list.

-Wformat-security
If '-Wformat' is specified, also warn about uses of format functions that represent possible security problems. At present, this warns about calls to printf and scanf functions where the format string is not a string literal and there are no format arguments, as in printf (foo);. This may be a security hole if the format string came from untrusted input and contains %n. (This is currently a subset of what '-Wformat-nonliteral' warns about, but in future warnings may be added to '-Wformat-security' that are not included in '-Wformat-nonliteral'.)

-Wformat=2
Enable '-Wformat' plus format checks not included in '-Wformat'. Currently equivalent to '-Wformat -Wformat-nonliteral -Wformat-security'.

-Wnonnull
Enable warning about passing a null pointer for arguments marked as requiring a non-null value by the nonnull function attribute.

'-Wnonnull' is included in '-Wall' and '-Wformat'. It can be disabled with the '-Wno-nonnull' option.

-Wimplicit-int
Warn when a declaration does not specify a type.

-Wimplicit-function-declaration
-Werror-implicit-function-declaration
Give a warning (or error) whenever a function is used before being declared.

-Wimplicit
Same as '-Wimplicit-int -Wimplicit-function-declaration'.

-Wmissing-braces
Warn if an aggregate or union initializer is not fully bracketed. In the following example, the initializer for a is not fully bracketed, but that for b is fully bracketed.
int a[2][2] = { 0, 1, 2, 3 };
int b[2][2] = { { 0, 1 }, { 2, 3 } };
-Wparentheses
Warn if parentheses are omitted in certain contexts, such as when there is an assignment in a context where a truth value is expected, or when operators are nested whose precedence people often get confused about.

Also warn about constructions where there may be confusion to which if statement an else branch belongs. Here is an example of such a case:
{
  if (a)
    if (b)
      foo ();
  else
    bar ();
}
In C, every else branch belongs to the innermost possible if statement, which in this example is if (b). This is often not what the programmer expected, as illustrated in the above example by the indentation the programmer chose. When there is the potential for this confusion, GCC will issue a warning when this flag is specified. To eliminate the warning, add explicit braces around the innermost if statement so there is no way the else could belong to the enclosing if. The resulting code would look like this:
{
  if (a)
    {
      if (b)
        foo ();
      else
        bar ();
    }
}
-Wsequence-point
Warn about code that may have undefined semantics because of violations of sequence point rules in the C standard.

The C standard defines the order in which expressions in a C program are evaluated in terms of sequence points, which represent a partial ordering between the execution of parts of the program: those executed before the sequence point, and those executed after it. These occur after the evaluation of a full expression (one which is not part of a larger expression), after the evaluation of the first operand of a &&, ||, ? : or , (comma) operator, before a function is called (but after the evaluation of its arguments and the expression denoting the called function), and in certain other places. Other than as expressed by the sequence point rules, the order of evaluation of subexpressions of an expression is not specified. All these rules describe only a partial order rather than a total order, since, for example, if two functions are called within one expression with no sequence point between them, the order in which the functions are called is not specified. However, the standards committee have ruled that function calls do not overlap.

It is not specified when between sequence points modifications to the values of objects take effect. Programs whose behavior depends on this have undefined behavior; the C standard specifies that "Between the previous and next sequence point an object shall have its stored value modified at most once by the evaluation of an expression. Furthermore, the prior value shall be read only to determine the value to be stored.". If a program breaks these rules, the results on any particular implementation are entirely unpredictable.

Examples of code with undefined behavior are a = a++;, a[n] = b[n++] and a[i++] = i;. Some more complicated cases are not diagnosed by this option, and it may give an occasional false positive result, but in general it has been found fairly effective at detecting this sort of problem in programs.

The C standard is worded confusingly, therefore there is some debate over the precise meaning of the sequence point rules in subtle cases. Links to discussions of the problem, including proposed formal definitions, may be found on the GCC readings page, at http://gcc.gnu.org/readings.html.

-Wreturn-type
Warn whenever a function is defined with a return-type that defaults to int. Also warn about any return statement with no return-value in a function whose return-type is not void.

-Wswitch
Warn whenever a switch statement has an index of enumeral type and lacks a case for one or more of the named codes of that enumeration. (The presence of a default label prevents this warning.) case labels outside the enumeration range also provoke warnings when this option is used.

-Wswitch-default
Warn whenever a switch statement does not have a default case.

-Wswitch-enum
Warn whenever a switch statement has an index of enumeral type and lacks a case for one or more of the named codes of that enumeration. case labels outside the enumeration range also provoke warnings when this option is used.

-Wtrigraphs
Warn if any trigraphs are encountered that might change the meaning of the program (trigraphs within comments are not warned about). For more information about trigraphs, see Options Controlling the Preprocessor.

-Wunused-function
Warn whenever a static function is declared but not defined or a non\-inline static function is unused.

To suppress this warning, use the unused attribute.

-Wunused-label
Warn whenever a label is declared but not used.

To suppress this warning, use the unused attribute.

-Wunused-parameter
Warn whenever a function parameter is unused aside from its declaration.

To suppress this warning, use the unused attribute.

-Wunused-variable
Warn whenever a local variable or non-constant static variable is unused aside from its declaration

To suppress this warning, use the unused attribute.

-Wunused-value
Warn whenever a statement computes a result that is explicitly not used.

To suppress this warning, cast the expression to void.

-Wunused
All the above '-Wunused' options combined.

In order to get a warning about an unused function parameter, you must either specify '-W -Wunused' or separately specify '-Wunused-parameter'.

-Wuninitialized
Warn if an automatic variable is used without first being initialized or if a variable may be clobbered by a setjmp call (I am not sure whether setjmp problems may be detected in GCC4TI).

These warnings are possible only in optimizing compilation, because they require data flow information that is computed only when optimizing. If you don't specify '-O', you simply won't get these warnings.

These warnings occur only for variables that are candidates for register allocation. Therefore, they do not occur for a variable that is declared volatile, or whose address is taken, or whose size is other than 1, 2, 4 or 8 bytes. Also, they do not occur for structures, unions or arrays, even when they are in registers.

Note that there may be no warning about a variable that is used only to compute a value that itself is never used, because such computations may be deleted by data flow analysis before the warnings are printed.

These warnings are made optional because GCC is not smart enough to see all the reasons why the code might be correct despite appearing to have an error. Here is one example of how this can happen:
{
  int x;
  switch (y)
    {
    case 1: x = 1;
      break;
    case 2: x = 4;
      break;
    case 3: x = 5;
    }
  foo (x);
}
If the value of y is always 1, 2 or 3, then x is always initialized, but GCC doesn't know this. Here is another common case:
{
  int save_y;
  if (change_y) save_y = y, y = new_y;
  ...
  if (change_y) y = save_y;
}
This has no bug because save_y is used only if it is set.

This option also warns when a non-volatile automatic variable might be changed by a call to longjmp. These warnings as well are possible only in optimizing compilation (although I am not sure whether they can be caught at all in GCC4TI).

The compiler sees only the calls to setjmp. It cannot know where longjmp will be called; in fact, an interrupt handler could call it at any point in the code. As a result, you may get a warning even when there is in fact no problem because longjmp cannot in fact be called at the place which would cause a problem.

Some spurious warnings can be avoided if you declare all the functions you use that never return as noreturn.

-Wunknown-pragmas
Warn when a #pragma directive is encountered which is not understood by GCC. If this command line option is used, warnings will even be issued for unknown pragmas in system header files. This is not the case if the warnings were only enabled by the '-Wall' command line option.

-Wstrict-aliasing
This option is only active when '-fstrict-aliasing' is active. It warns about code which might break the strict aliasing rules that the compiler is using for optimization. The warning does not catch all cases, but does attempt to catch the more common pitfalls. It is included in '-Wall'.

-Wall
All of the above '-W' options combined. This enables all the warnings about constructions that some users consider questionable, and that are easy to avoid (or modify to prevent the warning), even in conjunction with macros.
The following '-W...' options are not implied by '-Wall'. Some of them warn about constructions that users generally do not consider questionable, but which occasionally you might wish to check for; others warn about constructions that are necessary or hard to avoid in some cases, and there is no simple way to modify the code to suppress the warning.
-W
Print extra warning messages for these events:
  • A function can return either with or without a value. (Falling off the end of the function body is considered returning without a value.) For example, this function would evoke such a warning:
    foo (a)
{
  if (a > 0)
    return a;
}
  • An expression-statement or the left-hand side of a comma expression contains no side effects. To suppress the warning, cast the unused expression to void. For example, an expression such as x[i,j] will cause a warning, but x[(void)i,j] will not.

  • An unsigned value is compared against zero with < or <=.

  • A comparison like x<=y<=z appears; this is equivalent to (x<=y ? 1 : 0) <= z, which is a different interpretation from that of ordinary mathematical notation.

  • Storage-class specifiers like static are not the first things in a declaration. According to the C Standard, this usage is obsolescent.

  • The return type of a function has a type qualifier such as const. Such a type qualifier has no effect, since the value returned by a function is not an lvalue. (But don't warn about the GNU extension of volatile void return types. That extension will be warned about if '-pedantic' is specified.)

  • If '-Wall' or '-Wunused' is also specified, warn about unused arguments.

  • A comparison between signed and unsigned values could produce an incorrect result when the signed value is converted to unsigned. (But don't warn if '-Wno-sign-compare' is also specified.)

  • An aggregate has a partly bracketed initializer. For example, the following code would evoke such a warning, because braces are missing around the initializer for x.h:
    struct s { int f, g; };
struct t { struct s h; int i; };
struct t x = { 1, 2, 3 };
  • An aggregate has an initializer which does not initialize all members. For example, the following code would cause such a warning, because x.h would be implicitly initialized to zero:
    struct s { int f, g, h; };
struct s x = { 3, 4 };
-Wno-div-by-zero
Do not warn about compile-time integer division by zero. Floating point division by zero is not warned about, as it can be a legitimate way of obtaining infinities and NaNs.

-Wsystem-headers
Print warning messages for constructs found in system header files. Warnings from system headers are normally suppressed, on the assumption that they usually do not indicate real problems and would only make the compiler output harder to read. Using this command line option tells GCC to emit warnings from system headers as if they occurred in user code. However, note that using '-Wall' in conjunction with this option will not warn about unknown pragmas in system headers - for that, '-Wunknown-pragmas' must also be used.

Note that the GCC4TI Library header files are not included as system header files.

-Wfloat-equal
Warn if floating point values are used in equality comparisons.

The idea behind this is that sometimes it is convenient (for the programmer) to consider floating-point values as approximations to infinitely precise real numbers. If you are doing this, then you need to compute (by analyzing the code, or in some other way) the maximum or likely maximum error that the computation introduces, and allow for it when performing comparisons (and when producing output, but that's a different problem). In particular, instead of testing for equality, you would check to see whether the two values have ranges that overlap; and this is done with the relational operators, so equality comparisons are probably mistaken.

-Wtraditional
Warn about certain constructs that behave differently in traditional and ISO C. Also warn about ISO C constructs that have no traditional C equivalent, and/or problematic constructs which should be avoided.
  • Macro parameters that appear within string literals in the macro body. In traditional C macro replacement takes place within string literals, but does not in ISO C.

  • In traditional C, some preprocessor directives did not exist. Traditional preprocessors would only consider a line to be a directive if the # appeared in column 1 on the line. Therefore '-Wtraditional' warns about directives that traditional C understands but would ignore because the # does not appear as the first character on the line. It also suggests you hide directives like #pragma not understood by traditional C by indenting them. Some traditional implementations would not recognize #elif, so it suggests avoiding it altogether.

  • A function-like macro that appears without arguments.

  • The unary plus operator.

  • The U integer constant suffix, or the F or L floating point constant suffixes. (Traditional C does support the L suffix on integer constants.) Note, these suffixes appear in macros defined in limits.h, for example.

  • A function declared external in one block and then used after the end of the block.

  • A switch statement has an operand of type long.

  • A non-static function declaration follows a static one. This construct is not accepted by some traditional C compilers.

  • The ISO type of an integer constant has a different width or signedness from its traditional type. This warning is only issued if the base of the constant is 10, i.e. hexadecimal or octal values, which typically represent bit patterns, are not warned about.

  • Usage of ISO string concatenation is detected.

  • Initialization of automatic aggregates.

  • Identifier conflicts with labels. Traditional C lacks a separate namespace for labels.

  • Initialization of unions. If the initializer is zero, the warning is omitted. This is done under the assumption that the zero initializer in user code appears conditioned on e.g. __STDC__ to avoid missing initializer warnings and relies on default initialization to zero in the traditional C case.

  • Conversions by prototypes between fixed/floating point values and vice versa. The absence of these prototypes when compiling with traditional C would cause serious problems. This is a subset of the possible conversion warnings, for the full set use '-Wconversion'.

  • Use of ISO C style function definitions. This warning intentionally is not issued for prototype declarations or variadic functions because these ISO C features will appear in your code when using libiberty's traditional C compatibility macros, PARAMS and VPARAMS. This warning is also bypassed for nested functions because that feature is already a gcc extension and thus not relevant to traditional C compatibility.
-Wundef
Warn if an undefined identifier is evaluated in an #if directive.

-Wendif-labels
Warn whenever an #else or an #endif are followed by text.

-Wshadow
Warn whenever a local variable shadows another local variable, parameter or global variable or whenever a built-in function is shadowed.

-Wlarger-than-len
Warn whenever an object of larger than len bytes is defined.

-Wpointer-arith
Warn about anything that depends on the "size of" a function type or of void. GNU C assigns these types a size of 1, for convenience in calculations with void* pointers and pointers to functions.

-Wbad-function-cast
Warn whenever a function call is cast to a non-matching type. For example, warn if int malloc() is cast to anything *.

-Wcast-qual
Warn whenever a pointer is cast so as to remove a type qualifier from the target type. For example, warn if a const char * is cast to an ordinary char *.

-Wcast-align
Warn whenever a pointer is cast such that the required alignment of the target is increased. For example, warn if a char * is cast to an int * on machines where integers can only be accessed at two- or four-byte boundaries.

-Wwrite-strings
When compiling C, give string constants the type const char[length] so that copying the address of one into a non-const char * pointer will get a warning; when compiling C++, warn about the deprecated conversion from string constants to char *. These warnings will help you find at compile time code that can try to write into a string constant, but only if you have been very careful about using const in declarations and prototypes. Otherwise, it will just be a nuisance; this is why we did not make '-Wall' request these warnings.

-Wconversion
Warn if a prototype causes a type conversion that is different from what would happen to the same argument in the absence of a prototype. This includes conversions of fixed point to floating and vice versa, and conversions changing the width or signedness of a fixed point argument except when the same as the default promotion.

Also, warn if a negative integer constant expression is implicitly converted to an unsigned type. For example, warn about the assignment x = -1 if x is unsigned. But do not warn about explicit casts like (unsigned) -1.

-Wsign-compare
Warn when a comparison between signed and unsigned values could produce an incorrect result when the signed value is converted to unsigned. This warning is enabled by '-W', and by '-Wall' in C++ only.

-Waggregate-return
Warn if any functions that return structures or unions are defined or called.

-Wstrict-prototypes
Warn if a function is declared or defined without specifying the argument types. (An old-style function definition is permitted without a warning if preceded by a declaration which specifies the argument types.)

-Wmissing-prototypes
Warn if a global function is defined without a previous prototype declaration. This warning is issued even if the definition itself provides a prototype. The aim is to detect global functions that fail to be declared in header files.

-Wmissing-declarations (C only)
Warn if a global function is defined without a previous declaration. Do so even if the definition itself provides a prototype. Use this option to detect global functions that are not declared in header files.

-Wmissing-noreturn
Warn about functions which might be candidates for attribute noreturn. Note these are only possible candidates, not absolute ones. Care should be taken to manually verify functions actually do not ever return before adding the noreturn attribute, otherwise subtle code generation bugs could be introduced.

-Wmissing-format-attribute
If '-Wformat' is enabled, also warn about functions which might be candidates for format attributes. Note these are only possible candidates, not absolute ones. GCC will guess that format attributes might be appropriate for any function that calls a function like vprintf or vscanf, but this might not always be the case, and some functions for which format attributes are appropriate may not be detected. This option has no effect unless '-Wformat' is enabled (possibly by '-Wall').

-Wno-multichar
Do not warn if a multicharacter constant ('FOOF') is used. Usually they indicate a typo in the user's code, as they have implementation-defined values, and should not be used in portable code.

-Wno-deprecated-declarations
Do not warn about uses of functions, variables, and types marked as deprecated by using the deprecated attribute.

-Wpacked
Warn if a structure is given the packed attribute, but the packed attribute has no effect on the layout or size of the structure. Such structures may be mis-aligned for little benefit. For instance, in this code, the variable f.x in struct bar will be misaligned even though struct bar does not itself have the packed attribute:
struct foo {
  int x;
  char a, b, c, d;
} __attribute__((packed));
struct bar {
  char z;
  struct foo f;
};
-Wpadded
Warn if padding is included in a structure, either to align an element of the structure or to align the whole structure. Sometimes when this happens it is possible to rearrange the fields of the structure to reduce the padding and so make the structure smaller.

-Wredundant-decls
Warn if anything is declared more than once in the same scope, even in cases where multiple declaration is valid and changes nothing.

-Wnested-externs
Warn if an extern declaration is encountered within a function.

-Wunreachable-code
Warn if the compiler detects that code will never be executed.

This option is intended to warn when the compiler detects that at least a whole line of source code will never be executed, because some condition is never satisfied or because it is after a procedure that never returns.

It is possible for this option to produce a warning even though there are circumstances under which part of the affected line can be executed, so care should be taken when removing apparently-unreachable code.

For instance, when a function is inlined, a warning may mean that the line is unreachable in only one inlined copy of the function.

This option is not made part of '-Wall' because in a debugging version of a program there is often substantial code which checks correct functioning of the program and is, hopefully, unreachable because the program does work. Another common use of unreachable code is to provide behavior which is selectable at compile-time.

-Winline
Warn if a function can not be inlined and it was declared as inline. Even with this option, the compiler will not warn about failures to inline functions declared in system headers.

The compiler uses a variety of heuristics to determine whether or not to inline a function. For example, the compiler takes into account the size of the function being inlined and the the amount of inlining that has already been done in the current function. Therefore, seemingly insignificant changes in the source program can cause the warnings produced by '-Winline' to appear or disappear.

-Wlong-long
Warn if long long type is used. This is default. To inhibit the warning messages, use '-Wno-long-long'. Flags '-Wlong-long' and '-Wno-long-long' are taken into account only when '-pedantic' flag is used.

-Wdisabled-optimization
Warn if a requested optimization pass is disabled. This warning does not generally indicate that there is anything wrong with your code; it merely indicates that GCC's optimizers were unable to handle the code effectively. Often, the problem is that your code is too big or too complex; GCC will refuse to optimize programs when the optimization itself is likely to take inordinate amounts of time.

-Werror
Make all warnings into errors.


Options for Debugging Your Program
Previous GCC Command-Line Options Next

GCC has various special options that are used for debugging either your program or GCC. However, this manual is not meant to explain anything about the internals of GCC, so you will have to go to the official version of this page on the internet if you want to debug GCC itself.

In order to debug GCC4TI C programs at a source level, you need a GDB-enabled version of the TiEmu emulator.

-g
Produce debugging information in the operating system's native format (stabs is the default for the MC68000). GDB can work with this debugging information. Note that the tigcc frontend defaults to DWARF 2 debugging information instead, see Options Available in the Command Line Compiler.

Unlike most other C compilers, GCC allows you to use '-g' with '-O'. The shortcuts taken by optimized code may occasionally produce surprising results: some variables you declared may not exist at all; flow of control may briefly move where you did not expect it; some statements may not be executed because they compute constant results or their values were already at hand; some statements may execute in different places because they were moved out of loops.

Nevertheless it proves possible to debug optimized output. This makes it reasonable to use the optimizer for programs that might have bugs.

The following options are useful when GCC is generated with the capability for more than one debugging format.

-ggdb
Produce debugging information for use by GDB. This means to use the most expressive format available, including GDB extensions if at all possible.

-gstabs
Produce debugging information in stabs format.

-gstabs+
Produce debugging information in stabs format, using GNU extensions understood only by the GNU debugger (GDB).

-gcoff
Produce debugging information in COFF format.

-glevel
-ggdblevel
-gstabslevel
-gcofflevel
Request debugging information and also use level to specify how much information. The default level is 2.

Level 1 produces minimal information, enough for making backtraces in parts of the program that you don't plan to debug. This includes descriptions of functions and external variables, but no information about local variables and no line numbers.

Level 3 includes extra information, such as all the macro definitions present in the program. Some debuggers support macro expansion when you use '-g3'.

-p
Generate extra code to write profile information suitable for the analysis program prof. You must use this option when compiling the source files you want data about, and you must also use it when linking. This option is probably useless in GCC4TI.

-pg
Generate extra code to write profile information suitable for the analysis program gprof. You must use this option when compiling the source files you want data about, and you must also use it when linking. This option is probably useless in GCC4TI.

-Q
Makes the compiler print out each function name as it is compiled, and print some statistics about each pass when it finishes.

-save-temps
Store the usual "temporary" intermediate files permanently; place them in the current directory and name them based on the source file. Thus, compiling foo.c with '-c -save-temps' would produce files foo.i and foo.s, as well as foo.o. This creates a preprocessed foo.i output file even though the compiler now normally uses an integrated preprocessor.


Options That Control Optimization
Previous GCC Command-Line Options Next

These options control various sorts of optimizations.

Without any optimization option, the compiler's goal is to reduce the cost of compilation and to make debugging produce the expected results. Statements are independent: if you stop the program with a breakpoint between statements, you can then assign a new value to any variable or change the program counter to any other statement in the function and get exactly the results you would expect from the source code.

Turning on optimization flags makes the compiler attempt to improve the performance and/or code size at the expense of compilation time and possibly the ability to debug the program.

Not all optimizations are controlled directly by a flag. Only optimizations that have a flag are listed.

-O
-O1
Optimize. Optimizing compilation takes somewhat more time, and a lot more memory for a large function.

With '-O', the compiler tries to reduce code size and execution time, without performing any optimizations that take a great deal of compilation time.

'-O' turns on the following optimization flags: -fdefer-pop -fmerge-constants -fthread-jumps -floop-optimize -fcrossjumping -fif-conversion -fif-conversion2 -fdelayed-branch -fguess-branch-probability -fcprop-registers

'-O' also turns on '-fomit-frame-pointer' on machines where doing so does not interfere with debugging.

-O2
Optimize even more. GCC performs nearly all supported optimizations that do not involve a space-speed tradeoff. The compiler does not perform loop unrolling or function inlining when you specify '-O2'. As compared to '-O', this option increases both compilation time and the performance of the generated code.

'-O2' turns on all optimization flags specified by '-O'. It also turns on the following optimization flags:
-fforce-mem -foptimize-sibling-calls -fstrength-reduce -fcse-follow-jumps -fcse-skip-blocks -frerun-cse-after-loop -frerun-loop-opt -fgcse -fgcse-lm -fgcse-sm -fdelete-null-pointer-checks -fexpensive-optimizations -fregmove -fschedule-insns -fschedule-insns2 -fsched-interblock -fsched-spec -fcaller-saves -fpeephole2 -freorder-blocks -freorder-functions -fstrict-aliasing -falign-functions -falign-jumps -falign-loops -falign-labels

Please note the warning under '-fgcse' about invoking '-O2' on programs that use computed gotos.

-O3
Optimize yet more. '-O3' turns on all optimizations specified by '-O2' and also turns on the '-finline-functions' and '-frename-registers' options.

-O0
Do not optimize. This is the default.

-Os
Optimize for size. '-Os' enables all '-O2' optimizations that do not typically increase code size. It also performs further optimizations designed to reduce code size.

'-Os' disables the following optimization flags: -falign-functions -falign-jumps -falign-loops -falign-labels -freorder-blocks -fprefetch-loop-arrays

If you use multiple '-O' options, with or without level numbers, the last such option is the one that is effective.
Options of the form '-fflag' specify machine-independent flags. Most flags have both positive and negative forms; the negative form of '-ffoo' would be '-fno-foo'. In the table below, only one of the forms is listed: the one you typically will use. You can figure out the other form by either removing 'no-' or adding it.

The following options control specific optimizations. They are either activated by '-O' options or are related to ones that are. You can use the following flags in the rare cases when "fine-tuning" of optimizations to be performed is desired.
-fno-defer-pop
Always pop the arguments to each function call as soon as that function returns. For machines which must pop arguments after a function call, the compiler normally lets arguments accumulate on the stack for several function calls and pops them all at once.

Disabled at levels '-O', '-O2', '-O3', '-Os'.

-fforce-mem
Force memory operands to be copied into registers before doing arithmetic on them. This produces better code by making all memory references potential common subexpressions. When they are not common subexpressions, instruction combination should eliminate the separate register-load.

Enabled at levels '-O2', '-O3', '-Os'.

-fforce-addr
Force memory address constants to be copied into registers before doing arithmetic on them. This may produce better code just as '-fforce-mem' may.

-fomit-frame-pointer
Don't keep the frame pointer in a register for functions that don't need one. This avoids the instructions to save, set up and restore frame pointers; it also makes an extra register available in many functions. It also makes debugging impossible on some machines (not on GCC4TI though, thanks to unwinding tables).

This option now works with floating point arithmetic.

Enabled at levels '-O', '-O2', '-O3', '-Os'.

-foptimize-sibling-calls
Optimize sibling and tail recursive calls.

Enabled at levels '-O2', '-O3', '-Os'.

-fno-inline
Don't pay attention to the inline keyword. Normally this option is used to keep the compiler from expanding any functions inline. Note that if you are not optimizing, no functions can be expanded inline.

-finline-functions
Integrate all simple functions into their callers. The compiler heuristically decides which functions are simple enough to be worth integrating in this way.

If all calls to a given function are integrated, and the function is declared static, then the function is normally not output as assembler code in its own right.

Enabled at level '-O3'.

-finline-limit=n
By default, gcc limits the size of functions that can be inlined. This flag allows the control of this limit for functions that are explicitly marked as inline (i.e., marked with the inline keyword). n is the size of functions that can be inlined in number of pseudo instructions (not counting parameter handling). The default value of n is 600. Increasing this value can result in more inlined code at the cost of compilation time and memory consumption. Decreasing usually makes the compilation faster and less code will be inlined (which presumably means slower programs). This option is particularly useful for programs that use inlining heavily.

Inlining is actually controlled by a number of parameters, which may be specified individually by using '--param name=value'. The '-finline-limit=n' option sets some of these parameters as follows:

max-inline-insns
is set to n.
max-inline-insns-single
is set to n/2.
max-inline-insns-auto
is set to n/2.
min-inline-insns
is set to 130 or n/4, whichever is smaller.
max-inline-insns-rtl
is set to n.

Using '-finline-limit=600' thus results in the default settings for these parameters. See below for a documentation of the individual parameters controlling inlining.

Note: pseudo instruction represents, in this particular context, an abstract measurement of function's size. In no way, it represents a count of assembly instructions and as such its exact meaning might change from one release to an another.

-fkeep-inline-functions
Even if all calls to a given function are integrated, and the function is declared static, nevertheless output a separate run-time callable version of the function. This switch does not affect extern inline functions.

-fkeep-static-consts
Emit variables declared static const when optimization isn't turned on, even if the variables aren't referenced.

GCC enables this option by default. If you want to force the compiler to check if the variable was referenced, regardless of whether or not optimization is turned on, use the '-fno-keep-static-consts' option.

-fmerge-constants
Attempt to merge identical constants (string constants and floating point constants) across compilation units.

This option is the default for optimized compilation if the assembler and linker support it. Use '-fno-merge-constants' to inhibit this behavior.

Enabled at levels '-O', '-O2', '-O3', '-Os'.

-fmerge-all-constants
Attempt to merge identical constants and identical variables.

This option implies '-fmerge-constants'. In addition to '-fmerge-constants' this considers e.g. even constant initialized arrays or initialized constant variables with integral or floating point types. C requires each non-automatic variable to have a distinct location, so using this option will result in non-conforming behavior.

-fno-branch-count-reg
Do not use "decrement and branch" instructions on a count register, but instead generate a sequence of instructions that decrement a register, compare it against zero, then branch based upon the result. This option is only meaningful on architectures that support such instructions, which include x86, PowerPC, IA-64 and S/390.

The default is '-fbranch-count-reg', enabled when '-fstrength-reduce' is enabled.

-fno-function-cse
Do not put function addresses in registers; make each instruction that calls a constant function contain the function's address explicitly.

This option results in less efficient code, but some strange hacks that alter the assembler output may be confused by the optimizations performed when this option is not used.

The default is '-ffunction-cse'

-fno-zero-initialized-in-bss
If the target supports a BSS section (which is always the case for GCC4TI now), GCC by default puts variables that are initialized to zero into BSS. This can save space in the resulting code.

This option turns off this behavior because some programs explicitly rely on variables going to the data section. E.g., so that the resulting executable can find the beginning of that section and/or make assumptions based on that.

The default is '-fzero-initialized-in-bss'.

-fstrength-reduce
Perform the optimizations of loop strength reduction and elimination of iteration variables.

Enabled at levels '-O2', '-O3', '-Os'.

-fthread-jumps
Perform optimizations where we check to see if a jump branches to a location where another comparison subsumed by the first is found. If so, the first branch is redirected to either the destination of the second branch or a point immediately following it, depending on whether the condition is known to be true or false.

Enabled at levels '-O', '-O2', '-O3', '-Os'.

-fcse-follow-jumps
In common subexpression elimination, scan through jump instructions when the target of the jump is not reached by any other path. For example, when CSE encounters an if statement with an else clause, CSE will follow the jump when the condition tested is false.

Enabled at levels '-O2', '-O3', '-Os'.

-fcse-skip-blocks
This is similar to '-fcse-follow-jumps', but causes CSE to follow jumps which conditionally skip over blocks. When CSE encounters a simple if statement with no else clause, '-fcse-skip-blocks' causes CSE to follow the jump around the body of the if.

Enabled at levels '-O2', '-O3', '-Os'.

-frerun-cse-after-loop
Re-run common subexpression elimination after loop optimizations have been performed.

Enabled at levels '-O2', '-O3', '-Os'.

-frerun-loop-opt
Run the loop optimizer twice.

Enabled at levels '-O2', '-O3', '-Os'.

-fgcse
Perform a global common subexpression elimination pass. This pass also performs global constant and copy propagation.

Note: When compiling a program using computed gotos, a GCC extension, you may get better runtime performance if you disable the global common subexpression elimination pass by adding '-fno-gcse' to the command line.

Enabled at levels '-O2', '-O3', '-Os'.

-fgcse-lm
When '-fgcse-lm' is enabled, global common subexpression elimination will attempt to move loads which are only killed by stores into themselves. This allows a loop containing a load/store sequence to be changed to a load outside the loop, and a copy/store within the loop.

Enabled by default when gcse is enabled.

-fgcse-sm
When '-fgcse-sm' is enabled, A store motion pass is run after global common subexpression elimination. This pass will attempt to move stores out of loops. When used in conjunction with '-fgcse-lm', loops containing a load/store sequence can be changed to a load before the loop and a store after the loop.

Enabled by default when gcse is enabled.

-floop-optimize
Perform loop optimizations: move constant expressions out of loops, simplify exit test conditions and optionally do strength-reduction and loop unrolling as well.

Enabled at levels '-O', '-O2', '-O3', '-Os'.

-fcrossjumping
Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The resulting code may or may not perform better than without cross-jumping.

Enabled at levels '-O', '-O2', '-O3', '-Os'.

-fif-conversion
Attempt to transform conditional jumps into branch-less equivalents. This include use of conditional moves, min, max, set flags and abs instructions, and some tricks doable by standard arithmetics. The use of conditional execution on chips where it is available is controlled by if-conversion2.

Enabled at levels '-O', '-O2', '-O3', '-Os'.

-fif-conversion2
Use conditional execution (where available) to transform conditional jumps into branch-less equivalents.

Enabled at levels '-O', '-O2', '-O3', '-Os'.

-fdelete-null-pointer-checks
Use global dataflow analysis to identify and eliminate useless checks for null pointers. The compiler assumes that dereferencing a null pointer would have halted the program. If a pointer is checked after it has already been dereferenced, it cannot be null.

In some environments, this assumption is not true, and programs can safely dereference null pointers. Use '-fno-delete-null-pointer-checks' to disable this optimization for programs which depend on that behavior.

Enabled at levels '-O2', '-O3', '-Os'.

-fexpensive-optimizations
Perform a number of minor optimizations that are relatively expensive.

Enabled at levels '-O2', '-O3', '-Os'.

-foptimize-register-move
-fregmove
Attempt to reassign register numbers in move instructions and as operands of other simple instructions in order to maximize the amount of register tying. This is especially helpful on machines with two-operand instructions.

Note '-fregmove' and '-foptimize-register-move' are the same optimization.

Enabled at levels '-O2', '-O3', '-Os'.

-fdelayed-branch
If supported for the target machine, attempt to reorder instructions to exploit instruction slots available after delayed branch instructions.

Enabled at levels '-O', '-O2', '-O3', '-Os'.

-fschedule-insns
If supported for the target machine, attempt to reorder instructions to eliminate execution stalls due to required data being unavailable. This helps machines that have slow floating point or memory load instructions by allowing other instructions to be issued until the result of the load or floating point instruction is required.

Enabled at levels '-O2', '-O3', '-Os'.

-fschedule-insns2
Similar to '-fschedule-insns', but requests an additional pass of instruction scheduling after register allocation has been done. This is especially useful on machines with a relatively small number of registers and where memory load instructions take more than one cycle.

Enabled at levels '-O2', '-O3', '-Os'.

-fno-sched-interblock
Don't schedule instructions across basic blocks. This is normally enabled by default when scheduling before register allocation, i.e. with '-fschedule-insns' or at '-O2' or higher.

-fno-sched-spec
Don't allow speculative motion of non-load instructions. This is normally enabled by default when scheduling before register allocation, i.e. with '-fschedule-insns' or at '-O2' or higher.

-fsched-spec-load
Allow speculative motion of some load instructions. This only makes sense when scheduling before register allocation, i.e. with '-fschedule-insns' or at '-O2' or higher.

-fsched-spec-load-dangerous
Allow speculative motion of more load instructions. This only makes sense when scheduling before register allocation, i.e. with '-fschedule-insns' or at '-O2' or higher.

-fcaller-saves
Enable values to be allocated in registers that will be clobbered by function calls, by emitting extra instructions to save and restore the registers around such calls. Such allocation is done only when it seems to result in better code than would otherwise be produced.

This option is always enabled by default on certain machines, usually those which have no call-preserved registers to use instead.

Enabled at levels '-O2', '-O3', '-Os'.

-fmove-all-movables
Forces all invariant computations in loops to be moved outside the loop.

-freduce-all-givs
Forces all general-induction variables in loops to be strength-reduced.

These options may generate better or worse code; results are highly dependent on the structure of loops within the source code.

These two options are intended to be removed someday, once they have helped determine the efficacy of various approaches to improving loop optimizations.

-fno-peephole
-fno-peephole2
Disable any machine-specific peephole optimizations. The difference between '-fno-peephole' and '-fno-peephole2' is in how they are implemented in the compiler; some targets use one, some use the other, a few use both.

'-fpeephole' is enabled by default. '-fpeephole2' enabled at levels '-O2', '-O3', '-Os'.

-fbranch-probabilities
-fno-guess-branch-probability
Do not guess branch probabilities using a randomized model.

Sometimes gcc will opt to use a randomized model to guess branch probabilities, when none are available from either profiling feedback ('-fprofile-arcs') or __builtin_expect. This means that different runs of the compiler on the same program may produce different object code.

In a hard real-time system, people don't want different runs of the compiler to produce code that has different behavior; minimizing non-determinism is of paramount importance. This switch allows users to reduce non-determinism, possibly at the expense of inferior optimization.

The default is '-fguess-branch-probability' at levels '-O', '-O2', '-O3', '-Os'.

-freorder-blocks
Reorder basic blocks in the compiled function in order to reduce number of taken branches and improve code locality.

Enabled at levels '-O2', '-O3'.

-freorder-functions
Reorder basic blocks in the compiled function in order to reduce number of taken branches and improve code locality. This is implemented by using special subsections text.hot for most frequently executed functions and text.unlikely for unlikely executed functions. Reordering is done by the linker so object file format must support named sections and linker must place them in a reasonable way.

Also profile feedback must be available in to make this option effective. See '-fprofile-arcs' for details.

Enabled at levels '-O2', '-O3', '-Os'.

-fstrict-aliasing
Allows the compiler to assume the strictest aliasing rules applicable to the language being compiled. For C, this activates optimizations based on the type of expressions. In particular, an object of one type is assumed never to reside at the same address as an object of a different type, unless the types are almost the same. For example, an unsigned int can alias an int, but not a void* or a double. A character type may alias any other type.

Pay special attention to code like this:
union a_union {
  int i;
  double d;
};

int f() {
  a_union t;
  t.d = 3.0;
  return t.i;
}
The practice of reading from a different union member than the one most recently written to (called "type-punning") is common. Even with '-fstrict-aliasing', type-punning is allowed, provided the memory is accessed through the union type. So, the code above will work as expected. However, this code might not:
int f() {
  a_union t;
  int* ip;
  t.d = 3.0;
  ip = &t.i;
  return *ip;
}
Enabled at levels '-O2', '-O3', '-Os'.

-falign-functions
-falign-functions=n
Align the start of functions to the next power-of-two greater than n, skipping up to n bytes. For instance, '-falign-functions=32' aligns functions to the next 32-byte boundary, but '-falign-functions=24' would align to the next 32-byte boundary only if this can be done by skipping 23 bytes or less.

'-fno-align-functions' and '-falign-functions=1' are equivalent and mean that functions will not be aligned.

Some assemblers only support this flag when n is a power of two; in that case, it is rounded up.

If n is not specified, use a machine-dependent default.

Enabled at levels '-O2', '-O3'.

-falign-labels
-falign-labels=n
Align all branch targets to a power-of-two boundary, skipping up to n bytes like '-falign-functions'. This option can easily make code slower, because it must insert dummy operations for when the branch target is reached in the usual flow of the code.

If '-falign-loops' or '-falign-jumps' are applicable and are greater than this value, then their values are used instead.

If n is not specified, use a machine-dependent default which is very likely to be 1, meaning no alignment.

Enabled at levels '-O2', '-O3'.

-falign-loops
-falign-loops=n
Align loops to a power-of-two boundary, skipping up to n bytes like '-falign-functions'. The hope is that the loop will be executed many times, which will make up for any execution of the dummy operations.

If n is not specified, use a machine-dependent default.

Enabled at levels '-O2', '-O3'.

-falign-jumps
-falign-jumps=n
Align branch targets to a power-of-two boundary, for branch targets where the targets can only be reached by jumping, skipping up to n bytes like '-falign-functions'. In this case, no dummy operations need be executed.

If n is not specified, use a machine-dependent default.

Enabled at levels '-O2', '-O3'.

-frename-registers
Attempt to avoid false dependencies in scheduled code by making use of registers left over after register allocation. This optimization will most benefit processors with lots of registers. It can, however, make debugging impossible, since variables will no longer stay in a "home register".

Enabled at levels '-O3'.

-fno-cprop-registers
After register allocation and post-register allocation instruction splitting, we perform a copy-propagation pass to try to reduce scheduling dependencies and occasionally eliminate the copy.

Disabled at levels '-O', '-O2', '-O3', '-Os'.
The following options control compiler behavior regarding floating point arithmetic. These options trade off between speed and correctness. All must be specifically enabled.
-ffloat-store
Do not store floating point variables in registers, and inhibit other options that might change whether a floating point value is taken from a register or memory.

This option prevents undesirable excess precision on machines such as the 68000 where the floating registers (of the 68881) keep more precision than a double is supposed to have. Similarly for the x86 architecture. For most programs, the excess precision does only good, but a few programs rely on the precise definition of IEEE floating point. Use '-ffloat-store' for such programs, after modifying them to store all pertinent intermediate computations into variables.

This option is probably useless in GCC4TI, except as a workaround for floating point arithmetic errors.

-ffast-math
Sets '-fno-math-errno', '-funsafe-math-optimizations', '-fno-trapping-math', '-ffinite-math-only' and '-fno-signaling-nans'.

This option causes the preprocessor macro __FAST_MATH__ to be defined.

This option should never be turned on by any '-O' option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions.

This option is probably useless in GCC4TI.

-fno-math-errno
Do not set ERRNO after calling math functions that are executed with a single instruction, e.g., sqrt. A program that relies on IEEE exceptions for math error handling may want to use this flag for speed while maintaining IEEE arithmetic compatibility.

This option should never be turned on by any '-O' option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions.

This option is probably useless in GCC4TI.

The default is '-fmath-errno'.

-funsafe-math-optimizations
Allow optimizations for floating-point arithmetic that (a) assume that arguments and results are valid and (b) may violate IEEE or ANSI standards. When used at link-time, it may include libraries or startup files that change the default FPU control word or other similar optimizations.

This option should never be turned on by any '-O' option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions.

This option is probably useless in GCC4TI.

The default is '-fno-unsafe-math-optimizations'.

-ffinite-math-only
Allow optimizations for floating-point arithmetic that assume that arguments and results are not NaNs or +-Infs.

This option should never be turned on by any '-O' option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications.

The default is '-fno-finite-math-only'.

-fno-trapping-math
Compile code assuming that floating-point operations cannot generate user-visible traps. These traps include division by zero, overflow, underflow, inexact result and invalid operation. This option implies '-fno-signaling-nans'. Setting this option may allow faster code if one relies on "non-stop" IEEE arithmetic, for example.

This option should never be turned on by any '-O' option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions.

This option is probably useless in GCC4TI.

The default is '-ftrapping-math'.

-fsignaling-nans
Compile code assuming that IEEE signaling NaNs may generate user-visible traps during floating-point operations. Setting this option disables optimizations that may change the number of exceptions visible with signaling NaNs. This option implies '-ftrapping-math'.

This option causes the preprocessor macro __SUPPORT_SNAN__ to be defined.

The default is '-fno-signaling-nans'.

This option is experimental and does not currently guarantee to disable all GCC optimizations that affect signaling NaN behavior.

-fsingle-precision-constant
Treat floating point constant as single precision constant instead of implicitly converting it to double precision constant.
The following options control optimizations that may improve performance, but are not enabled by any '-O' options. This section includes experimental options that may produce broken code.
-fbranch-probabilities
After running a program compiled with '-fprofile-arcs' (see Options for Debugging Your Program or GCC), you can compile it a second time using '-fbranch-probabilities', to improve optimizations based on the number of times each branch was taken. When the program compiled with '-fprofile-arcs' exits, it saves arc execution counts to a file called sourcename.da for each source file. The information in this data file is very dependent on the structure of the generated code, so you must use the same source code and the same optimization options for both compilations.

With '-fbranch-probabilities', GCC puts a REG_BR_PROB note on each JUMP_INSN and CALL_INSN. These can be used to improve optimization. Currently, they are only used in one place: in reorg.c, instead of guessing which path a branch is mostly to take, the REG_BR_PROB values are used to exactly determine which path is taken more often.

-fnew-ra
Use a graph coloring register allocator. Currently this option is meant for testing, so we are interested to hear about miscompilations with '-fnew-ra'.

-ftracer
Perform tail duplication to enlarge superblock size. This transformation simplifies the control flow of the function allowing other optimizations to do better job.

-funroll-loops
Unroll loops whose number of iterations can be determined at compile time or upon entry to the loop. '-funroll-loops' implies both '-fstrength-reduce' and '-frerun-cse-after-loop'. This option makes code larger, and may or may not make it run faster.

-funroll-all-loops
Unroll all loops, even if their number of iterations is uncertain when the loop is entered. This usually makes programs run more slowly. '-funroll-all-loops' implies the same options as '-funroll-loops',

-fprefetch-loop-arrays
If supported by the target machine, generate instructions to prefetch memory to improve the performance of loops that access large arrays.

Disabled at level '-Os'.

-ffunction-sections
-fdata-sections
Place each function or data item into its own section in the output file if the target supports arbitrary sections. The name of the function or the name of the data item determines the section's name in the output file.

Use these options on systems where the linker can perform optimizations to improve locality of reference in the instruction space. Most systems using the ELF object format and SPARC processors running Solaris 2 have linkers with such optimizations. AIX may have these optimizations in the future.

Only use these options when there are significant benefits from doing so. When you specify these options, the assembler and linker will create larger object and executable files and will also be slower. You will not be able to use gprof on all systems if you specify this option and you may have problems with debugging if you specify both this option and '-g'.

-fssa
Perform optimizations in static single assignment form. Each function's flow graph is translated into SSA form, optimizations are performed, and the flow graph is translated back from SSA form. Users should not specify this option, since it is not yet ready for production use.

-fssa-ccp
Perform Sparse Conditional Constant Propagation in SSA form. Requires '-fssa'. Like '-fssa', this is an experimental feature.

-fssa-dce
Perform aggressive dead-code elimination in SSA form. Requires '-fssa'. Like '-fssa', this is an experimental feature.

--param name=value
In some places, GCC uses various constants to control the amount of optimization that is done. For example, GCC will not inline functions that contain more that a certain number of instructions. You can control some of these constants on the command-line using the '--param' option.

In each case, the value is an integer. The allowable choices for name are given in the following table:

max-crossjump-edges
The maximum number of incoming edges to consider for crossjumping. The algorithm used by '-fcrossjumping' is O(N^2) in the number of edges incoming to each block. Increasing values mean more aggressive optimization, making the compile time increase with probably small improvement in executable size.

max-delay-slot-insn-search
The maximum number of instructions to consider when looking for an instruction to fill a delay slot. If more than this arbitrary number of instructions is searched, the time savings from filling the delay slot will be minimal so stop searching. Increasing values mean more aggressive optimization, making the compile time increase with probably small improvement in executable run time.

max-delay-slot-live-search
When trying to fill delay slots, the maximum number of instructions to consider when searching for a block with valid live register information. Increasing this arbitrarily chosen value means more aggressive optimization, increasing the compile time. This parameter should be removed when the delay slot code is rewritten to maintain the control-flow graph.

max-gcse-memory
The approximate maximum amount of memory that will be allocated in order to perform the global common subexpression elimination optimization. If more memory than specified is required, the optimization will not be done.

max-gcse-passes
The maximum number of passes of GCSE to run.

max-pending-list-length
The maximum number of pending dependencies scheduling will allow before flushing the current state and starting over. Large functions with few branches or calls can create excessively large lists which needlessly consume memory and resources.

max-inline-insns-single
Several parameters control the tree inliner used in gcc. This number sets the maximum number of instructions (counted in gcc's internal representation) in a single function that the tree inliner will consider for inlining. This only affects functions declared inline. The default value is 300.

max-inline-insns-auto
When you use '-finline-functions' (included in '-O3'), a lot of functions that would otherwise not be considered for inlining by the compiler will be investigated. To those functions, a different (more restrictive) limit compared to functions declared inline can be applied. The default value is 300.

max-inline-insns
The tree inliner does decrease the allowable size for single functions to be inlined after we already inlined the number of instructions given here by repeated inlining. This number should be a factor of two or more larger than the single function limit. Higher numbers result in better runtime performance, but incur higher compile-time resource (CPU time, memory) requirements and result in larger binaries. Very high values are not advisable, as too large binaries may adversely affect runtime performance. The default value is 600.

max-inline-slope
After exceeding the maximum number of inlined instructions by repeated inlining, a linear function is used to decrease the allowable size for single functions. The slope of that function is the negative reciprocal of the number specified here. The default value is 32.

min-inline-insns
The repeated inlining is throttled more and more by the linear function after exceeding the limit. To avoid too much throttling, a minimum for this function is specified here to allow repeated inlining for very small functions even when a lot of repeated inlining already has been done. The default value is 130.

max-inline-insns-rtl
For languages that use the RTL inliner (this happens at a later stage than tree inlining), you can set the maximum allowable size (counted in RTL instructions) for the RTL inliner with this parameter. The default value is 600.

max-unrolled-insns
The maximum number of instructions that a loop should have if that loop is unrolled, and if the loop is unrolled, it determines how many times the loop code is unrolled.

hot-bb-count-fraction
Select fraction of the maximal count of repetitions of basic block in program given basic block needs to have to be considered hot.

hot-bb-frequency-fraction
Select fraction of the maximal frequency of executions of basic block in function given basic block needs to have to be considered hot

tracer-dynamic-coverage
tracer-dynamic-coverage-feedback
This value is used to limit superblock formation once the given percentage of executed instructions is covered. This limits unnecessary code size expansion.

The 'tracer-dynamic-coverage-feedback' is used only when profile feedback is available. The real profiles (as opposed to statically estimated ones) are much less balanced allowing the threshold to be larger value.

tracer-max-code-growth
Stop tail duplication once code growth has reached given percentage. This is rather hokey argument, as most of the duplicates will be eliminated later in cross jumping, so it may be set to much higher values than is the desired code growth.

tracer-min-branch-ratio
Stop reverse growth when the reverse probability of best edge is less than this threshold (in percent).

tracer-min-branch-ratio
tracer-min-branch-ratio-feedback
Stop forward growth if the best edge do have probability lower than this threshold.

Similarly to 'tracer-dynamic-coverage' two values are present, one for compilation for profile feedback and one for compilation without. The value for compilation with profile feedback needs to be more conservative (higher) in order to make tracer effective.

ggc-min-expand
GCC uses a garbage collector to manage its own memory allocation. This parameter specifies the minimum percentage by which the garbage collector's heap should be allowed to expand between collections. Tuning this may improve compilation speed; it has no effect on code generation.

The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when RAM >= 1GB. If getrlimit is available, the notion of "RAM" is the smallest of actual RAM, RLIMIT_RSS, RLIMIT_DATA and RLIMIT_AS. If GCC is not able to calculate RAM on a particular platform, the lower bound of 30% is used. Setting this parameter and 'ggc-min-heapsize' to zero causes a full collection to occur at every opportunity. This is extremely slow, but can be useful for debugging.

ggc-min-heapsize
Minimum size of the garbage collector's heap before it begins bothering to collect garbage. The first collection occurs after the heap expands by 'ggc-min-expand'% beyond 'ggc-min-heapsize'. Again, tuning this may improve compilation speed, and has no effect on code generation.

The default is RAM/8, with a lower bound of 4096 (four megabytes) and an upper bound of 131072 (128 megabytes). If getrlimit is available, the notion of "RAM" is the smallest of actual RAM, RLIMIT_RSS, RLIMIT_DATA and RLIMIT_AS. If GCC is not able to calculate RAM on a particular platform, the lower bound is used. Setting this parameter very large effectively disables garbage collection. Setting this parameter and 'ggc-min-expand' to zero causes a full collection to occur at every opportunity.


Options Controlling the Preprocessor
Previous GCC Command-Line Options Next

These options control the C preprocessor, which is run on each C source file before actual compilation.

If you use the '-E' option, nothing is done except preprocessing. Some of these options make sense only together with '-E' because they cause the preprocessor output to be unsuitable for actual compilation.

You can use '-Wp,option' to bypass the compiler driver and pass option directly through to the preprocessor. If option contains commas, it is split into multiple options at the commas. However, many options are modified, translated or interpreted by the compiler driver before being passed to the preprocessor, and '-Wp' forcibly bypasses this phase. The preprocessor's direct interface is undocumented and subject to change, so whenever possible you should avoid using '-Wp' and let the driver handle the options instead.

-D name
Predefine name as a macro, with definition 1.

-D name=definition
Predefine name as a macro, with definition definition. There are no restrictions on the contents of definition, but if you are invoking the preprocessor from a shell or shell-like program you may need to use the shell's quoting syntax to protect characters such as spaces that have a meaning in the shell syntax.

If you wish to define a function-like macro on the command line, write its argument list with surrounding parentheses before the equals sign (if any). Parentheses are meaningful to most shells, so you will need to quote the option. With sh and csh, '-D'name(args...)=definition'' works.

'-D' and '-U' options are processed in the order they are given on the command line. All '-imacros file' and '-include file' options are processed after all '-D' and '-U' options.

-U name
Cancel any previous definition of name, either built in or provided with a '-D' option.

-undef
Do not predefine any system-specific macros. The common predefined macros remain defined.

-I dir
Add the directory dir to the list of directories to be searched for header files. Directories named by '-I' are searched before the standard system include directories. If the directory dir is a standard system include directory, the option is ignored to ensure that the default search order for system directories and the special treatment of system headers are not defeated (see System Headers).

-o file
Write output to file. This is the same as specifying file as the second non-option argument to cpp. gcc has a different interpretation of a second non-option argument, so you must use '-o' to specify the output file.

-Wall
Turns on all optional warnings which are desirable for normal code. At present this is '-Wcomment' and '-Wtrigraphs'. Note that many of the preprocessor's warnings are on by default and have no options to control them.

-Wcomment
-Wcomments
Warn whenever a comment-start sequence /* appears in a /* comment, or whenever a backslash-newline appears in a // comment. (Both forms have the same effect.)

-Wtrigraphs
Warn if any trigraphs are encountered. This option used to take effect only if '-trigraphs' was also specified, but now works independently. Warnings are not given for trigraphs within comments, as they do not affect the meaning of the program.

-Wtraditional
Warn about certain constructs that behave differently in traditional and ISO C. Also warn about ISO C constructs that have no traditional C equivalent, and problematic constructs which should be avoided. See Traditional Mode.

-Wimport
Warn the first time #import is used.

-Wundef
Warn whenever an identifier which is not a macro is encountered in an #if directive, outside of defined. Such identifiers are replaced with zero.

-Wunused-macros
Warn about macros defined in the main file that are unused. A macro is used if it is expanded or tested for existence at least once. The preprocessor will also warn if the macro has not been used at the time it is redefined or undefined.

Built-in macros, macros defined on the command line, and macros defined in include files are not warned about.

Note: If a macro is actually used, but only used in skipped conditional blocks, then CPP will report it as unused. To avoid the warning in such a case, you might improve the scope of the macro's definition by, for example, moving it into the first skipped block. Alternatively, you could provide a dummy use with something like:
#if defined the_macro_causing_the_warning
#endif
-Wendif-labels
Warn whenever an #else or an #endif are followed by text. This usually happens in code of the form
#if FOO
...
#else FOO
...
#endif FOO
The second and third FOO should be in comments, but often are not in older programs. This warning is on by default.

-Werror
Make all warnings into hard errors. Source code which triggers warnings will be rejected.

-Wsystem-headers
Issue warnings for code in system headers. These are normally unhelpful in finding bugs in your own code, therefore suppressed. If you are responsible for the system library, you may want to see them.

-w
Suppress all warnings, including those which GNU CPP issues by default.

-pedantic
Issue all the mandatory diagnostics listed in the C standard. Some of them are left out by default, since they trigger frequently on harmless code.

-pedantic-errors
Issue all the mandatory diagnostics, and make all mandatory diagnostics into errors. This includes mandatory diagnostics that GCC issues without '-pedantic' but treats as warnings.

-M
Instead of outputting the result of preprocessing, output a rule suitable for make describing the dependencies of the main source file. The preprocessor outputs one make rule containing the object file name for that source file, a colon, and the names of all the included files, including those coming from '-include' or '-imacros' command line options.

Unless specified explicitly (with '-MT' or '-MQ'), the object file name consists of the basename of the source file with any suffix replaced with object file suffix. If there are many included files then the rule is split into several lines using \-newline. The rule has no commands.

This option does not suppress the preprocessor's debug output, such as '-dM'. To avoid mixing such debug output with the dependency rules you should explicitly specify the dependency output file with '-MF', or use an environment variable like DEPENDENCIES_OUTPUT (see Environment Variables). Debug output will still be sent to the regular output stream as normal.

Passing '-M' to the driver implies '-E', and suppresses warnings with an implicit '-w'.

-MM
Like '-M' but do not mention header files that are found in system header directories, nor header files that are included, directly or indirectly, from such a header.

This implies that the choice of angle brackets or double quotes in an #include directive does not in itself determine whether that header will appear in '-MM' dependency output. This is a slight change in semantics from GCC versions 3.0 and earlier.

-MF file
When used with '-M' or '-MM', specifies a file to write the dependencies to. If no '-MF' switch is given the preprocessor sends the rules to the same place it would have sent preprocessed output.

When used with the driver options '-MD' or '-MMD', '-MF' overrides the default dependency output file.

-MG
In conjunction with an option such as '-M' requesting dependency generation, '-MG' assumes missing header files are generated files and adds them to the dependency list without raising an error. The dependency filename is taken directly from the #include directive without prepending any path. '-MG' also suppresses preprocessed output, as a missing header file renders this useless.

This feature is used in automatic updating of makefiles.

-MP
This option instructs CPP to add a phony target for each dependency other than the main file, causing each to depend on nothing. These dummy rules work around errors make gives if you remove header files without updating the Makefile to match.

This is typical output:
test.o: test.c test.h

test.h:
-MT target
Change the target of the rule emitted by dependency generation. By default CPP takes the name of the main input file, including any path, deletes any file suffix such as .c, and appends the platform's usual object suffix. The result is the target.

An '-MT' option will set the target to be exactly the string you specify. If you want multiple targets, you can specify them as a single argument to '-MT', or use multiple '-MT' options.

For example, '-MT '$(objpfx)foo.o'' might give
$(objpfx)foo.o: foo.c
-MQ target
Same as '-MT', but it quotes any characters which are special to Make. The default target is automatically quoted, as if it were given with '-MQ'.

-MD
'-MD' is equivalent to '-M -MF file', except that '-E' is not implied. The driver determines file based on whether an '-o' option is given. If it is, the driver uses its argument but with a suffix of .d, otherwise it take the basename of the input file and applies a .d suffix.

If '-MD' is used in conjunction with '-E', any '-o' switch is understood to specify the dependency output file, but if used without '-E', each '-o' is understood to specify a target object file.

Since '-E' is not implied, '-MD' can be used to generate a dependency output file as a side-effect of the compilation process.

-MMD
Like '-MD' except mention only user header files, not system -header files.

-x c
-x c++
-x objective-c
-x assembler-with-cpp
Specify the source language: C, C++, Objective-C, or assembly. This has nothing to do with standards conformance or extensions; it merely selects which base syntax to expect. If you give none of these options, cpp will deduce the language from the extension of the source file: .c, .cc, .m, or .S. Some other common extensions for C++ and assembly are also recognized. If cpp does not recognize the extension, it will treat the file as C; this is the most generic mode. Note that C++ and Objective-C are not supported in GCC4TI.

Note: Previous versions of cpp accepted a '-lang' option which selected both the language and the standards conformance level. This option has been removed, because it conflicts with the '-l' option.

-std=standard
-ansi
Specify the standard to which the code should conform. Currently CPP knows about C and C++ standards; others may be added in the future (although it will not be important for GCC4TI).

standard may be one of:

iso9899:1990
c89
The ISO C standard from 1990. c89 is the customary shorthand for this version of the standard.

The '-ansi' option is equivalent to '-std=c89'.

iso9899:199409
The 1990 C standard, as amended in 1994.

iso9899:1999
c99
iso9899:199x
c9x
The revised ISO C standard, published in December 1999. Before publication, this was known as C9X.

gnu89
The 1990 C standard plus GNU extensions. This is the default.

gnu99
gnu9x
The 1999 C standard plus GNU extensions.

c++98
The 1998 ISO C++ standard plus amendments.

gnu++98
The same as '-std=c++98' plus GNU extensions. This is the default for C++ code.

-I-
Split the include path. Any directories specified with '-I' options before '-I-' are searched only for headers requested with #include "file"; they are not searched for #include <file>. If additional directories are specified with '-I' options after the '-I-', those directories are searched for all #include directives.

In addition, '-I-' inhibits the use of the directory of the current file directory as the first search directory for #include "file".

-nostdinc
Do not search the standard system directories for header files. Only the directories you have specified with '-I' options (and the directory of the current file, if appropriate) are searched.

-nostdinc++
Do not search for header files in the C++-specific standard directories, but do still search the other standard directories (not applicable to GCC4TI, because it does not support C++).

-include file
Process file as if #include "file" appeared as the first line of the primary source file. However, the first directory searched for file is the preprocessor's working directory instead of the directory containing the main source file. If not found there, it is searched for in the remainder of the #include "..." search chain as normal.

If multiple '-include' options are given, the files are included in the order they appear on the command line.

-imacros file
Exactly like '-include', except that any output produced by scanning file is thrown away. Macros it defines remain defined. This allows you to acquire all the macros from a header without also processing its declarations.

All files specified by '-imacros' are processed before all files specified by '-include'.

-idirafter dir
Search dir for header files, but do it after all directories specified with '-I' and the standard system directories have been exhausted. dir is treated as a system include directory.

-iprefix prefix
Specify prefix as the prefix for subsequent '-iwithprefix' options. If the prefix represents a directory, you should include the final /.

-iwithprefix dir
-iwithprefixbefore dir
Append dir to the prefix specified previously with '-iprefix', and add the resulting directory to the include search path. '-iwithprefixbefore' puts it in the same place '-I' would; '-iwithprefix' puts it where '-idirafter' would.

Use of these options is discouraged.

-isystem dir
Search dir for header files, after all directories specified by '-I' but before the standard system directories. Mark it as a system directory, so that it gets the same special treatment as is applied to the standard system directories. See System Headers.

-fpreprocessed
Indicate to the preprocessor that the input file has already been preprocessed. This suppresses things like macro expansion, trigraph conversion, escaped newline splicing, and processing of most directives. The preprocessor still recognizes and removes comments, so that you can pass a file preprocessed with '-C' to the compiler without problems. In this mode the integrated preprocessor is little more than a tokenizer for the front ends.

'-fpreprocessed' is implicit if the input file has one of the extensions .i, .ii or .mi. These are the extensions that GCC uses for preprocessed files created by '-save-temps'.

-ftabstop=width
Set the distance between tab stops. This helps the preprocessor report correct column numbers in warnings or errors, even if tabs appear on the line. If the value is less than 1 or greater than 100, the option is ignored. The default is 8.

-fno-show-column
Do not print column numbers in diagnostics. This may be necessary if diagnostics are being scanned by a program that does not understand the column numbers, such as dejagnu.

-A predicate=answer
Make an assertion with the predicate predicate and answer answer. This form is preferred to the older form '-A predicate(answer)', which is still supported, because it does not use shell special characters. See Assertions.
-A -predicate=answer
Cancel an assertion with the predicate predicate and answer answer.

-dCHARS
CHARS is a sequence of one or more of the following characters, and must not be preceded by a space. Other characters are interpreted by the compiler proper, or reserved for future versions of GCC, and so are silently ignored. If you specify characters whose behavior conflicts, the result is undefined.

M
Instead of the normal output, generate a list of #define directives for all the macros defined during the execution of the preprocessor, including predefined macros. This gives you a way of finding out what is predefined in your version of the preprocessor. Assuming you have no file foo.h, the command
touch foo.h; cpp -dM foo.h
will show all the predefined macros.

D
Like M except in two respects: it does not include the predefined macros, and it outputs both the #define directives and the result of preprocessing. Both kinds of output go to the standard output file.

N
Like D, but emit only the macro names, not their expansions.

I
Output #include directives in addition to the result of preprocessing.

-P
Inhibit generation of linemarkers in the output from the preprocessor. This might be useful when running the preprocessor on something that is not C code, and will be sent to a program which might be confused by the linemarkers. See Preprocessor Output.

-C
Do not discard comments. All comments are passed through to the output file, except for comments in processed directives, which are deleted along with the directive.

You should be prepared for side effects when using '-C'; it causes the preprocessor to treat comments as tokens in their own right. For example, comments appearing at the start of what would be a directive line have the effect of turning that line into an ordinary source line, since the first token on the line is no longer a #.

-CC
Do not discard comments, including during macro expansion. This is like '-C', except that comments contained within macros are also passed through to the output file where the macro is expanded.

In addition to the side-effects of the '-C' option, the '-CC' option causes all C++-style comments inside a macro to be converted to C-style comments. This is to prevent later use of that macro from inadvertently commenting out the remainder of the source line.

The '-CC' option is generally used to support lint comments.

-gcc
Define the macros __GNUC__, __GNUC_MINOR__ and __GNUC_PATCHLEVEL__. These are defined automatically when you use gcc -E; you can turn them off in that case with '-no-gcc'.

-traditional-cpp
Try to imitate the behavior of old-fashioned C preprocessors, as opposed to ISO C preprocessors. See Traditional Mode.

-trigraphs
Process trigraph sequences. See Initial processing. These are three-character sequences, all starting with ??, that are defined by ISO C to stand for single characters. For example, ??/ stands for \, so '??/n' is a character constant for a newline. By default, GCC ignores trigraphs, but in standard-conforming modes it converts them. See the '-std' and '-ansi' options.

The nine trigraphs and their replacements are
Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
Replacement:      [    ]    {    }    #    \    ^    |    ~
-remap
Enable special code to work around file systems which only permit very short file names, such as MS-DOS.

--help
--target-help
Print text describing all the command line options instead of preprocessing anything.

-v
Verbose mode. Print out GNU CPP's version number at the beginning of execution, and report the final form of the include path.

-H
Print the name of each header file used, in addition to other normal activities. Each name is indented to show how deep in the #include stack it is.

-version
--version
Print out GNU CPP's version number. With one dash, proceed to preprocess as normal. With two dashes, exit immediately.


Passing Options to the Assembler and Linker
Previous GCC Command-Line Options Next

You can pass options to the GNU assembler, to the A68k assembler, and to the GNU linker.

However, this is only possible this way if you are using the command line compiler. In the IDE, you have to use the appropriate edit boxes in the project options.

-Wa,option
Pass option as an option to the GNU assembler. If option contains commas, it is split into multiple options at the commas.

-WA,option
Pass option as an option to the A68k assembler. If option contains commas, it is split into multiple options at the commas. This is a TIGCC/GCC4TI-only switch.

-Wl,option
Pass option as an option to the GNU linker. If option contains commas, it is split into multiple options at the commas.


Options for Directory Search
Previous GCC Command-Line Options Next

These options specify directories to search for header files, for libraries and for parts of the compiler:

-Idir
Add the directory dir to the head of the list of directories to be searched for header files. This can be used to override a system header file, substituting your own version, since these directories are searched before the system header file directories. However, you should not use this option to add directories that contain vendor-supplied system header files (use '-isystem' for that). If you use more than one '-I' option, the directories are scanned in left-to-right order; the standard system directories come after.

If a standard system include directory, or a directory specified with '-isystem', is also specified with '-I', the '-I' option will be ignored. The directory will still be searched but as a system directory at its normal position in the system include chain. This is to ensure that GCC's procedure to fix buggy system headers and the ordering for the include_next directive are not inadvertently changed. If you really need to change the search order for system directories, use the '-nostdinc' and/or '-isystem' options.

-I-
Any directories you specify with '-I' options before the '-I-' option are searched only for the case of #include "file"; they are not searched for #include <file>.

If additional directories are specified with '-I' options after the '-I-', these directories are searched for all #include directives. (Ordinarily all '-I' directories are used this way.)

In addition, the '-I-' option inhibits the use of the current directory (where the current input file came from) as the first search directory for #include "file". There is no way to override this effect of '-I-'. With '-I.' you can specify searching the directory which was current when the compiler was invoked. That is not exactly the same as what the preprocessor does by default, but it is often satisfactory.

'-I-' does not inhibit the use of the standard system directories for header files. Thus, '-I-' and '-nostdinc' are independent.

-Ldir
Add directory dir to the list of directories to be searched for '-l'.

-Bprefix
This option specifies where to find the executables, libraries, include files, and data files of the compiler itself.

The compiler will check to see if the path provided by the '-B' refers to a directory, and if necessary it will add a directory separator character at the end of the path.

Another way to specify a prefix much like the '-B' prefix is to use the environment variable GCC_EXEC_PREFIX. See Environment Variables.

-specs=file
Process file after the compiler reads in the standard specs file, in order to override the defaults that the gcc driver program uses when determining what switches to pass to the individual programs. This does not work in GCC4TI.


GCC Spec Strings
Previous GCC Command-Line Options Next

gcc is a driver program. It performs its job by invoking a sequence of other programs to do the work of compiling, assembling and linking. GCC interprets its command-line parameters and uses these to deduce which programs it should invoke, and which command-line options it ought to place on their command lines. This behavior is controlled by spec strings. In most cases there is one spec string for each program that GCC can invoke, but a few programs have multiple spec strings to control their behavior. The spec strings built into GCC can be overridden by using the '-specs=' command-line switch to specify a spec file.

Spec files are plaintext files that are used to construct spec strings. They consist of a sequence of directives separated by blank lines.

Since gcc only performs a small part of the tasks in GCC4TI, spec strings are more or less irrelevant. For details on specs, see the original documentation on the net.


M680x0 Target Options
Previous GCC Command-Line Options Next

The GCC compiler used in GCC4TI is configured for just one target family: the Motorola M680x0 (M68k) family. In the TI-89, TI-92+, and V200 calculators, an MC68000 processor is used, therefore GCC4TI creates code for such a processor by default. However, switches specifying the processor model, such as '-m68020', still exist, although they are not useful. However, there are also options that control the code that is generated specifically for TI calculators; they also start with '-m':

-mno-bss
Output all uninitialized global or static variables as normal data with zero content. Note that this leads to different semantics if the program is not compressed or archived: The variables will keep their values even after program termination, instead of being initialized to zero every time the program is run. For a better alternative, see MERGE_BSS.

-mlong
Consider type int to be 32 bits wide, like long int. The '-mshort' option is enabled by default in GCC4TI; the negative is actually '-mnoshort', but '-mno-short' and '-mlong' have been added as aliases. Constants such as INT_MAX are set to the appropriate values, and __INT_SHORT__ will be defined if short integers are used (i.e. if this switch is not used). This option may be useful if you need to port code from a system which uses long integers.

-mno-tios
Again, this is the negative form of a switch called '-mtios', which changes the convention for returning pointers from functions, and which also implies '-fcall-used-d2'. This is necessary to make GCC work with the TIOS calling conventions, therefore '-mno-tios' may only be used if no interaction with the operating system is required. Since library calls also use the TIOS calling convention, they cannot be used either; you should disable linking against tigcc.a. Only use this option if you know exactly what you are doing.

-mmlink
Assume that uninitialized global variables can be handled smartly through BSS blocks even in kernel-less mode.

-mpcrel
Use the pc-relative addressing mode of the 68000 directly, instead of using a global offset table (also known as the relocation table). Therefore, this option produces position-independent code.

-mregparm[=regcount]
Use register passing for all user-defined functions. regcount data registers plus regcount address registers are used to pass arguments to functions. If regcount is not specified, a default value of 2 is used. You should not specify a value higher than 6, or 5 if you use OPTIMIZE_ROM_CALLS. Note that you have to be careful with callback functions if you use this switch, although you will be warned about incompatiblities.

-mbitfield
Use bit-field instructions.

-malign-int
Aligns int, long, long long, float, double, and long double variables on a 32-bit boundary.

-mno-strict-align
-mstrict-align
Do not or do assume that unaligned memory references will be handled by the system.

-mno-merge-sections
Do not merge the .text and .data sections, as GCC4TI normally does (to save space used by relocation).

-mmerge-to-data
When merging sections, merge to .data rather than to .text.

-mrodata-to-text
When not merging sections, put read-only data into .text rather than .data.


Options for Code Generation Conventions
Previous GCC Command-Line Options Next

These machine-independent options control the interface conventions used in code generation.

Most of them have both positive and negative forms; the negative form of '-ffoo' would be '-fno-foo'. In the table below, only one of the forms is listed: the one which is not the default. You can figure out the other form by either removing 'no-' or adding it.

-fbounds-check
For front-ends that support it, generate additional code to check that indices used to access arrays are within the declared range. This is currently only supported by the Java and Fortran 77 front-ends, where this option defaults to true and false respectively.

-ftrapv
This option generates traps for signed overflow on addition, subtraction, multiplication operations.

-fexceptions
Enable exception handling. Generates extra code needed to propagate exceptions. In principle, you may need to enable this option when compiling C code that needs to interoperate properly with exception handlers, but this is useless in GCC4TI, as the standard OS uses its own exception handling mechanism (see error.h).

-fnon-call-exceptions
Generate code that allows trapping instructions to throw exceptions. Probably useless in GCC4TI.

-funwind-tables
Similar to '-fexceptions', except that it will just generate any needed static data, but will not affect the generated code in any other way. Probably useless in GCC4TI.

-fasynchronous-unwind-tables
Generate unwind table in dwarf2 format, if supported by target machine. The table is exact at each instruction boundary, so it can be used for stack unwinding from asynchronous events (such as debugger or garbage collector).

-fpcc-struct-return
Return "short" struct and union values in memory like longer ones, rather than in registers. This convention is less efficient, but it has the advantage of allowing intercallability between GCC-compiled files and files compiled with other compilers, particularly the Portable C Compiler (pcc).

The precise convention for returning structures in memory depends on the target configuration macros.

Short structures and unions are those whose size and alignment match that of some integer type.

Warning: code compiled with the '-fpcc-struct-return' switch is not binary compatible with code compiled with the '-freg-struct-return' switch. Use it to conform to a non-default application binary interface.

-freg-struct-return
Return struct and union values in registers when possible. This is more efficient for small structures than '-fpcc-struct-return'.

If you specify neither '-fpcc-struct-return' nor '-freg-struct-return', GCC4TI defaults to '-freg-struct-return'.

Warning: code compiled with the '-freg-struct-return' switch is not binary compatible with code compiled with the '-fpcc-struct-return' switch. Use it to conform to a non-default application binary interface.

-fshort-enums
Allocate to an enum type only as many bytes as it needs for the declared range of possible values. Specifically, the enum type will be equivalent to the smallest integer type which has enough room.

Warning: the '-fshort-enums' switch causes GCC to generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface.

-fshort-double
Use the same size for double as for float. This is always true in GCC4TI, regardless of this switch.

Warning: the '-fshort-double' switch causes GCC to generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface.

-fshort-wchar
Override the underlying type for wchar_t to be short unsigned int instead of the default for the target. This option is useful for building programs to run under WINE.

Warning: the '-fshort-wchar' switch causes GCC to generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface.

-fshared-data
Requests that the data and non-const variables of this compilation be shared data rather than private data. The distinction makes sense only on certain operating systems, where shared data is shared between processes running the same program, while private data exists in one copy per process.

-fno-common
Allocate even uninitialized global variables in the data section of the object file, rather than generating them as common blocks. This has the effect that if the same variable is declared (without extern) in two different compilations, you will get an error when you link them. The only reason this might be useful is if you wish to verify that the program will work on other systems which always work this way. Currently, GCC4TI does not support this option, since it needs common symbols to communicate with the linker.

-fno-ident
Ignore the #ident directive.

-fno-gnu-linker
Do not output global initializations in the form used by the GNU linker Useless in GCC4TI, because global initializations are not implemented.

-finhibit-size-directive
Don't output a .size assembler directive, or anything else that would cause trouble if the function is split in the middle, and the two halves are placed at locations far apart in memory. This option is used when compiling crtstuff.c; you should not need to use it for anything else.

-fverbose-asm
Put extra commentary information in the generated assembly code to make it more readable. This option is generally only of use to those who actually need to read the generated assembly code (perhaps while debugging the compiler itself).

'-fno-verbose-asm', the default, causes the extra information to be omitted and is useful when comparing two assembler files.

-fvolatile
Consider all memory references through pointers to be volatile.

-fvolatile-global
Consider all memory references to extern and global data items to be volatile. GCC does not consider static data items to be volatile because of this switch.

-fvolatile-static
Consider all memory references to static data to be volatile.

-fpic
Generate position-independent code (PIC) suitable for use in a shared library. However, it requires special support of the operating system (like dynamic loaders, etc.). So forget it with the TIOS; maybe some future ASM shells will support this. At the moment, forget this nice option.

-fPIC
If supported for the target machine, emit position-independent code, suitable for dynamic linking and avoiding any limit on the size of the global offset table.

-ffixed-reg
Treat the register named reg as a fixed register; generated code should never refer to it (except perhaps as a stack pointer, frame pointer or in some other fixed role).

This flag does not have a negative form, because it specifies a three-way choice.

-fcall-used-reg
Treat the register named reg as an allocable register that is clobbered by function calls. It may be allocated for temporaries or variables that do not live across a call. Functions compiled this way will not save and restore the register reg.

It is an error to used this flag with the frame pointer or stack pointer. Use of this flag for other registers that have fixed pervasive roles in the machine's execution model will produce disastrous results.

This flag does not have a negative form, because it specifies a three-way choice.

-fcall-saved-reg
Treat the register named reg as an allocable register saved by functions. It may be allocated even for temporaries or variables that live across a call. Functions compiled this way will save and restore the register reg if they use it.

It is an error to used this flag with the frame pointer or stack pointer. Use of this flag for other registers that have fixed pervasive roles in the machine's execution model will produce disastrous results.

A different sort of disaster will result from the use of this flag for a register in which function values may be returned.

This flag does not have a negative form, because it specifies a three-way choice.

-freg-relative-reg
Refer to all labels only in relation to the register specified in reg. This can make the code somewhat smaller, but you should use this option with care as it is not fully supported. This option is implemented only in TIGCC/GCC4TI.

-fpack-struct
Pack all structure members together without holes.

Warning: the '-fpack-struct' switch causes GCC to generate code that is not binary compatible with code generated without that switch. Additionally, it makes the code suboptimal. Use it to conform to a non-default application binary interface.

-finstrument-functions
Generate instrumentation calls for entry and exit to functions. Just after function entry and just before function exit, the following profiling functions will be called with the address of the current function and its call site. (On some platforms, __builtin_return_address does not work beyond the current function, so the call site information may not be available to the profiling functions otherwise.)
void __cyg_profile_func_enter (void *this_fn,
                               void *call_site);
void __cyg_profile_func_exit  (void *this_fn,
                               void *call_site);
The first argument is the address of the start of the current function, which may be looked up exactly in the symbol table.

This instrumentation is also done for functions expanded inline in other functions. The profiling calls will indicate where, conceptually, the inline function is entered and exited. This means that addressable versions of such functions must be available. If all your uses of a function are expanded inline, this may mean an additional expansion of code size. If you use extern inline in your C code, an addressable version of such functions must be provided. (This is normally the case anyways, but if you get lucky and the optimizer always expands the functions inline, you might have gotten away without providing static copies.)

A function may be given the attribute no_instrument_function, in which case this instrumentation will not be done. This can be used, for example, for the profiling functions listed above, high-priority interrupt routines, and any functions from which the profiling functions cannot safely be called (perhaps signal handlers, if the profiling routines generate output or allocate memory).

-fstack-check
Generate code to verify that you do not go beyond the boundary of the stack. As this requires support from the operating system, it probably does not work in GCC4TI.

-fstack-limit-register=reg
-fstack-limit-symbol=sym
-fno-stack-limit
Generate code to ensure that the stack does not grow beyond a certain value, either the value of a register or the address of a symbol. If the stack would grow beyond the value, a signal is raised. For most targets, the signal is raised before the stack overruns the boundary, so it is possible to catch the signal without taking special precautions.

For instance, if the stack starts at absolute address 0x80000000 and grows downwards, you can use the flags '-fstack-limit-symbol=__stack_limit' and '-Wl,--defsym,__stack_limit=0x7ffe0000' to enforce a stack limit of 128KB. Note that this may only work with the GNU linker.

-fargument-alias
-fargument-noalias
-fargument-noalias-global
Specify the possible relationships among parameters and between parameters and global data.
  • '-fargument-alias' specifies that arguments (parameters) may alias each other and may alias global storage.
  • '-fargument-noalias' specifies that arguments do not alias each other, but may alias global storage.
  • '-fargument-noalias-global' specifies that arguments do not alias each other and do not alias global storage.
Each language will automatically use whatever option is required by the language standard. You should not need to use these options yourself.

-fleading-underscore
This option and its counterpart, '-fno-leading-underscore', forcibly change the way C symbols are represented in the object file. One use is to help link with legacy assembly code.

Warning: the '-fleading-underscore' switch causes GCC to generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface.

-ftls-model=model
Alter the thread-local storage model to be used. The model argument should be one of global-dynamic, local-dynamic, initial-exec or local-exec.

The default without '-fpic' is initial-exec; with '-fpic' the default is global-dynamic.

Useless in TIGCC/GCC4TI, as threads are not supported.


Environment Variables Affecting GCC
Previous GCC Command-Line Options Next

This section describes several environment variables that affect how GCC operates. Some of them work by specifying directories or prefixes to use when searching for various kinds of files. Some are used to specify other aspects of the compilation environment.

Note that you can also specify places to search using options such as '-B', '-I' and '-L' (see Options for Directory Search).

LANG
LC_CTYPE
LC_MESSAGES
LC_ALL
These environment variables control the way that GCC uses localization information that allow GCC to work with different national conventions. GCC inspects the locale categories LC_CTYPE and LC_MESSAGES if it has been configured to do so. These locale categories can be set to any value supported by your installation. A typical value is en_UK for English in the United Kingdom.

The LC_CTYPE environment variable specifies character classification. GCC uses it to determine the character boundaries in a string; this is needed for some multibyte encodings that contain quote and escape characters that would otherwise be interpreted as a string end or escape.

The LC_MESSAGES environment variable specifies the language to use in diagnostic messages.

If the LC_ALL environment variable is set, it overrides the value of LC_CTYPE and LC_MESSAGES; otherwise, LC_CTYPE and LC_MESSAGES default to the value of the LANG environment variable. If none of these variables are set, GCC defaults to traditional C English behavior.

TMPDIR
If TMPDIR is set, it specifies the directory to use for temporary files. GCC uses temporary files to hold the output of one stage of compilation which is to be used as input to the next stage: for example, the output of the preprocessor, which is the input to the compiler proper.

GCC_EXEC_PREFIX
If GCC_EXEC_PREFIX is set, it specifies a prefix to use in the names of the subprograms executed by the compiler. No slash is added when this prefix is combined with the name of a subprogram, but you can specify a prefix that ends with a slash if you wish.

If GCC_EXEC_PREFIX is not set, GCC will attempt to figure out an appropriate prefix to use based on the pathname it was invoked with.

If GCC cannot find the subprogram using the specified prefix, it tries looking in the usual places for the subprogram.

The default value of GCC_EXEC_PREFIX is prefix/lib/gcc-lib/ where prefix is the value of prefix when you ran the configure script.

Other prefixes specified with '-B' take precedence over this prefix.

In addition, the prefix is used in an unusual way in finding the directories to search for header files. For each of the standard directories whose name normally begins with /usr/local/lib/gcc-lib (more precisely, with the value of GCC_INCLUDE_DIR), GCC tries replacing that beginning with the specified prefix to produce an alternate directory name. Thus, with '-Bfoo/', GCC will search foo/bar where it would normally search /usr/local/lib/bar. These alternate directories are searched first; the standard directories come next.

COMPILER_PATH
The value of COMPILER_PATH is a colon-separated list of directories, much like PATH. GCC tries the directories thus specified when searching for subprograms, if it can't find the subprograms using GCC_EXEC_PREFIX.

LIBRARY_PATH
The value of LIBRARY_PATH is a colon-separated list of directories, much like PATH. When configured as a native compiler (which GCC4TI is not), GCC tries the directories thus specified when searching for special linker files, if it can't find them using GCC_EXEC_PREFIX. Linking using GCC also uses these directories when searching for ordinary libraries for the '-l' option (but directories specified with '-L' come first).

LANG
This variable is used to pass locale information to the compiler. One way in which this information is used is to determine the character set to be used when character literals, string literals and comments are parsed. When the compiler is configured to allow multibyte characters, the following values for LANG are recognized:

C-JIS
Recognize JIS characters.

C-SJIS
Recognize SJIS characters.

C-EUCJP
Recognize EUCJP characters.

If LANG is not defined, or if it has some other value, then the compiler will use mblen and mbtowc as defined by the default locale to recognize and translate multibyte characters.
Some additional environments variables affect the behavior of the preprocessor.
CPATH
C_INCLUDE_PATH
Each variable's value is a list of directories separated by a special character, much like PATH, in which to look for header files. The special character, PATH_SEPARATOR, is target-dependent and determined at GCC build time. For Windows-based targets it is a semicolon, and for almost all other targets it is a colon.

CPATH specifies a list of directories to be searched as if specified with '-I', but after any paths given with '-I' options on the command line.

C_INCLUDE_PATH specifies a list of directories to be searched as if specified with '-isystem', but after any paths given with '-isystem' options on the command line.

In all these variables, an empty element instructs the compiler to search its current working directory. Empty elements can appear at the beginning or end of a path. For instance, if the value of CPATH is :/special/include, that has the same effect as -I. -I/special/include.

DEPENDENCIES_OUTPUT
If this variable is set, its value specifies how to output dependencies for Make based on the non-system header files processed by the compiler. System header files are ignored in the dependency output.

The value of DEPENDENCIES_OUTPUT can be just a file name, in which case the Make rules are written to that file, guessing the target name from the source file name. Or the value can have the form file target, in which case the rules are written to file file using target as the target name.

In other words, this environment variable is equivalent to combining the options '-MM' and '-MF' (see Options Controlling the Preprocessor), with an optional '-MT' switch, too.

SUNPRO_DEPENDENCIES
This variable is the same as DEPENDENCIES_OUTPUT (see above), except that system header files are not ignored, so it implies '-M' rather than '-MM' (see Options Controlling the Preprocessor). However, the dependence on the main input file is omitted.


History
Previous GCC Command-Line Options

  • Original Version: GCC Command Options

    Published by the Free Software Foundation
    59 Temple Place - Suite 330
    Boston, MA 02111-1307 USA

    Copyright © 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.

  • Modifications for TIGCC: GCC Command-Line Options

    Published by the TIGCC Team

    Copyright © 2000, 2001, 2002 Zeljko Juric, Sebastian Reichelt, Kevin Kofler
  • Modifications for GCC4TI: GCC Command-Line Options

    Published by the GCC4TI Project

    Copyright © 2009, 2010, 2011 Lionel Debroux


The GNU C Preprocessor

This part of the documentation is a modified version of the GNU CPP Manual. Therefore it is licensed under the GNU Free Documentation License.

The C preprocessor is a macro processor that is used automatically by the C compiler to transform your program before actual compilation. It is called a macro processor because it allows you to define macros, which are brief abbreviations for longer constructs.

  • Preprocessor Overview
  • Header Files
  • Macros
  • Conditionals
  • Pragmas
  • Other Directives
  • User-defined Diagnostics
  • Line Control
  • Preprocessor Output
  • C Preprocessor Command-Line Options
  • Traditional Mode
  • Implementation Details
  • History
  • GNU General Public License
  • GNU Free Documentation License
  • Funding Free Software

Original author: Free Software Foundation, Inc.
Authors of the modifications: Zeljko Juric, Sebastian Reichelt, and Kevin Kofler
Published by the TIGCC Team, and now the GCC4TI project.
See the History section for details and copyright information.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation. A copy of the license is included in the section entitled "GNU Free Documentation License".

This manual contains no Invariant Sections. The Front-Cover Texts are (a) (see below), and the Back-Cover Texts are (b) (see below).

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.


Preprocessor Overview
The GNU C Preprocessor Next

The C preprocessor, often known as cpp, is a macro processor that is used automatically by the C compiler to transform your program before compilation. It is called a macro processor because it allows you to define macros, which are brief abbreviations for longer constructs.

The C preprocessor is intended to be used only with C, C++, and Objective-C source code. In the past, it has been abused as a general text processor. It will choke on input which does not obey C's lexical rules. For example, apostrophes will be interpreted as the beginning of character constants, and cause errors. Also, you cannot rely on it preserving characteristics of the input which are not significant to C-family languages. If a Makefile is preprocessed, all the hard tabs will be removed, and the Makefile will not work.

Having said that, you can often get away with using cpp on things which are not C. Other Algol-ish programming languages are often safe (Pascal, Ada, etc.) So is assembly, with caution. '-traditional-cpp' mode preserves more white space, and is otherwise more permissive. Many of the problems can be avoided by writing C or C++ style comments instead of native language comments, and keeping macros simple.

Wherever possible, you should use a preprocessor geared to the language you are writing in. Modern versions of the GNU assembler have macro facilities. Most high level programming languages have their own conditional compilation and inclusion mechanism. If all else fails, try a true general text processor, such as GNU M4.

C preprocessors vary in some details. This manual discusses the GNU C preprocessor, which provides a small superset of the features of ISO Standard C. In its default mode, the GNU C preprocessor does not do a few things required by the standard. These are features which are rarely, if ever, used, and may cause surprising changes to the meaning of a program which does not expect them. To get strict ISO Standard C, you should use the '-std=c89' or '-std=c99' options, depending on which version of the standard you want. To get all the mandatory diagnostics, you must also use '-pedantic'. See Invocation.

This manual describes the behavior of the ISO preprocessor. To minimize gratuitous differences, where the ISO preprocessor's behavior does not conflict with traditional semantics, the traditional preprocessor should behave the same way. The various differences that do exist are detailed in the section Traditional Mode.

For clarity, unless noted otherwise, references to CPP in this manual refer to GNU CPP.

  • Initial processing
  • Tokenization
  • The preprocessing language


Initial processing
Preprocessor Overview Next

The preprocessor performs a series of textual transformations on its input. These happen before all other processing. Conceptually, they happen in a rigid order, and the entire file is run through each transformation before the next one begins. CPP actually does them all at once, for performance reasons. These transformations correspond roughly to the first three "phases of translation" described in the C standard.

  1. The input file is read into memory and broken into lines.

    CPP expects its input to be a text file, that is, an unstructured stream of ASCII characters, with some characters indicating the end of a line of text. Extended ASCII character sets, such as ISO Latin-1 or Unicode encoded in UTF-8, are also acceptable. Character sets that are not strict supersets of seven-bit ASCII will not work. We plan to add complete support for international character sets in a future release.

    Different systems use different conventions to indicate the end of a line. GCC accepts the ASCII control sequences LF, CR LF, CR, and LF CR as end-of-line markers. The first three are the canonical sequences used by Unix, DOS and VMS, and the classic Mac OS (before OSX) respectively. You may therefore safely copy source code written on any of those systems to a different one and use it without conversion. (GCC may lose track of the current line number if a file doesn't consistently use one convention, as sometimes happens when it is edited on computers with different conventions that share a network file system.) LF CR is included because it has been reported as an end-of-line marker under exotic conditions.

    If the last line of any input file lacks an end-of-line marker, the end of the file is considered to implicitly supply one. The C standard says that this condition provokes undefined behavior, so GCC will emit a warning message.

  2. If trigraphs are enabled, they are replaced by their corresponding single characters. By default GCC ignores trigraphs, but if you request a strictly conforming mode with the '-std' option, or you specify the '-trigraphs' option, then it converts them.

    These are nine three-character sequences, all starting with ??, that are defined by ISO C to stand for single characters. They permit obsolete systems that lack some of C's punctuation to use C. For example, ??/ stands for \, so '??/n' is a character constant for a newline.

    Trigraphs are not popular and many compilers implement them incorrectly. Portable code should not rely on trigraphs being either converted or ignored. If you use the '-Wall' or '-Wtrigraphs' options, GCC will warn you when a trigraph would change the meaning of your program if it were converted.

    In a string constant, you can prevent a sequence of question marks from being confused with a trigraph by inserting a backslash between the question marks. "(??\?)" is the string (???), not (?]. Traditional C compilers do not recognize this idiom.

    The nine trigraphs and their replacements are
    Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
Replacement:      [    ]    {    }    #    \    ^    |    ~
  3. Continued lines are merged into one long line.

    A continued line is a line which ends with a backslash, \. The backslash is removed and the following line is joined with the current one. No space is inserted, so you may split a line anywhere, even in the middle of a word. (It is generally more readable to split lines only at white space.)

    The trailing backslash on a continued line is commonly referred to as a backslash-newline.

    If there is white space between a backslash and the end of a line, that is still a continued line. However, as this is usually the result of an editing mistake, and many compilers will not accept it as a continued line, GCC will warn you about it.

  4. All comments are replaced with single spaces.

    There are two kinds of comments. Block comments begin with /* and continue until the next */. Block comments do not nest:
    /* this is /* one comment */ text outside comment
    Line comments begin with // and continue to the end of the current line. Line comments do not nest either, but it does not matter, because they would end in the same place anyway.
    // this is // one comment
text outside comment
It is safe to put line comments inside block comments, or vice versa.
/* block comment
   // contains line comment
   yet more comment
 */ outside comment

// line comment /* contains block comment */
But beware of commenting out one end of a block comment with a line comment.
 // l.c.  /* block comment begins
    oops! this isn't a comment anymore */
Comments are not recognized within string literals. "/* blah */" is the string constant /* blah */, not an empty string.

Line comments are not in the 1989 edition of the C standard, but they are recognized by GCC as an extension. In C++ and in the 1999 edition of the C standard, they are an official part of the language.

Since these transformations happen before all other processing, you can split a line mechanically with backslash-newline anywhere. You can comment out the end of a line. You can continue a line comment onto the next line with backslash-newline. You can even split /*, */, and // onto multiple lines with backslash-newline. For example:
/\
*
*/ # /*
*/ defi\
ne FO\
O 10\
20
is equivalent to #define FOO 1020. All these tricks are extremely confusing and should not be used in code intended to be readable.

There is no way to prevent a backslash at the end of a line from being interpreted as a backslash-newline. This cannot affect any correct program, however.


Tokenization
Previous Preprocessor Overview Next

After the textual transformations are finished, the input file is converted into a sequence of preprocessing tokens. These mostly correspond to the syntactic tokens used by the C compiler, but there are a few differences. White space separates tokens; it is not itself a token of any kind. Tokens do not have to be separated by white space, but it is often necessary to avoid ambiguities.

When faced with a sequence of characters that has more than one possible tokenization, the preprocessor is greedy. It always makes each token, starting from the left, as big as possible before moving on to the next token. For instance, a+++++b is interpreted as a ++ ++ + b, not as a ++ + ++ b, even though the latter tokenization could be part of a valid C program and the former could not.

Once the input file is broken into tokens, the token boundaries never change, except when the ## preprocessing operator is used to paste tokens together. See Concatenation. For example,

#define foo() bar
foo()baz
expands to bar baz, not barbaz.

The compiler does not re-tokenize the preprocessor's output. Each preprocessing token becomes one compiler token.

Preprocessing tokens fall into five broad classes: identifiers, preprocessing numbers, string literals, punctuators, and other. An identifier is the same as an identifier in C: any sequence of letters, digits, or underscores, which begins with a letter or underscore. Keywords of C have no significance to the preprocessor; they are ordinary identifiers. You can define a macro whose name is a keyword, for instance. The only identifier which can be considered a preprocessing keyword is defined.

In the 1999 C standard, identifiers may contain letters which are not part of the "basic source character set," at the implementation's discretion (such as accented Latin letters, Greek letters, or Chinese ideograms). This may be done with an extended character set, or the \u and \U escape sequences. GCC does not presently implement either feature in the preprocessor or the compiler.

As an extension, GCC treats $ as a letter. This is for compatibility with some systems, such as VMS, where $ is commonly used in system-defined function and object names. $ is not a letter in strictly conforming mode, or if you specify the '-$' option. See Invocation.

A preprocessing number has a rather bizarre definition. The category includes all the normal integer and floating point constants one expects of C, but also a number of other things one might not initially recognize as a number. Formally, preprocessing numbers begin with an optional period, a required decimal digit, and then continue with any sequence of letters, digits, underscores, periods, and exponents. Exponents are the two-character sequences e+, e-, E+, E-, p+, p-, P+, and P-. (The exponents that begin with p or P are new to C99. They are used for hexadecimal floating-point constants.)

The purpose of this unusual definition is to isolate the preprocessor from the full complexity of numeric constants. It does not have to distinguish between lexically valid and invalid floating-point numbers, which is complicated. The definition also permits you to split an identifier at any position and get exactly two tokens, which can then be pasted back together with the ## operator.

It's possible for preprocessing numbers to cause programs to be misinterpreted. For example, 0xE+12 is a preprocessing number which does not translate to any valid numeric constant, therefore a syntax error. It does not mean 0xE + 12, which is what you might have intended.

String literals are string constants, character constants, and header file names (the argument of #include). The C standard uses the term string literal to refer only to what we are calling string constants. String constants and character constants are straightforward: "..." or '...'. In either case embedded quotes should be escaped with a backslash: '\'' is the character constant for '. There is no limit on the length of a character constant, but the value of a character constant that contains more than one character is implementation-defined. See Implementation Details.

Header file names either look like string constants, "...", or are written with angle brackets instead, <...>. In either case, backslash is an ordinary character. There is no way to escape the closing quote or angle bracket. The preprocessor looks for the header file in different places depending on which form you use. See Include Operation.

In standard C, no string literal may extend past the end of a line. GNU CPP accepts multi-line string constants, but not multi-line character constants or header file names. To write standards-compliant code, you may use continued lines instead, or string constant concatenation. See Differences from previous versions.

Punctuators are all the usual bits of punctuation which are meaningful to C and C++. All but three of the punctuation characters in ASCII are C punctuators. The exceptions are @, $, and '. In addition, all the two- and three-character operators are punctuators. There are also six digraphs, which the C++ standard calls alternative tokens, which are merely alternate ways to spell other punctuators. This is a second attempt to work around missing punctuation in obsolete systems. It has no negative side effects, unlike trigraphs, but does not cover as much ground. The digraphs and their corresponding normal punctuators are:
Digraph:        <%  %>  <:  :>  %:  %:%:
Punctuator:      {   }   [   ]   #    ##
Any other single character is considered "other." It is passed on to the preprocessor's output unmolested. The C compiler will almost certainly reject source code containing "other" tokens. In ASCII, the only other characters are @, $, ', and control characters other than NUL (all bits zero). (Note that $ is normally considered a letter.) All characters with the high bit set (numeric range 0x7F--0xFF) are also "other" in the present implementation. This will change when proper support for international character sets is added to GCC.

NUL is a special case because of the high probability that its appearance is accidental, and because it may be invisible to the user (many terminals do not display NUL at all). Within comments, NULs are silently ignored, just as any other character would be. In running text, NUL is considered white space. For example, these two directives have the same meaning.
#define X^@1
#define X 1
(where ^@ is ASCII NUL). Within string or character constants, NULs are preserved. In the latter two cases the preprocessor emits a warning message.


The preprocessing language
Previous Preprocessor Overview

After tokenization, the stream of tokens may simply be passed straight to the compiler's parser. However, if it contains any operations in the preprocessing language, it will be transformed first. This stage corresponds roughly to the standard's "translation phase 4" and is what most people think of as the preprocessor's job.

The preprocessing language consists of directives to be executed and macros to be expanded. Its primary capabilities are:

  • Inclusion of header files. These are files of declarations that can be substituted into your program.

  • Macro expansion. You can define macros, which are abbreviations for arbitrary fragments of C code. The preprocessor will replace the macros with their definitions throughout the program. Some macros are automatically defined for you.

  • Conditional compilation. You can include or exclude parts of the program according to various conditions.

  • Line control. If you use a program to combine or rearrange source files into an intermediate file which is then compiled, you can use line control to inform the compiler where each source line originally came from.

  • Diagnostics. You can detect problems at compile time and issue errors or warnings.
There are a few more, less useful, features.

Except for expansion of predefined macros, all these operations are triggered with preprocessing directives. Preprocessing directives are lines in your program that start with #. Whitespace is allowed before and after the #. The # is followed by an identifier, the directive name. It specifies the operation to perform. Directives are commonly referred to as #name where name is the directive name. For example, #define is the directive that defines a macro.

The # which begins a directive cannot come from a macro expansion. Also, the directive name is not macro expanded. Thus, if foo is defined as a macro expanding to define, that does not make #foo a valid preprocessing directive.

The set of valid directive names is fixed. Programs cannot define new preprocessing directives.

Some directives require arguments; these make up the rest of the directive line and must be separated from the directive name by whitespace. For example, #define must be followed by a macro name and the intended expansion of the macro.

A preprocessing directive cannot cover more than one line. The line may, however, be continued with backslash-newline, or by a block comment which extends past the end of the line. In either case, when the directive is processed, the continuations have already been merged with the first line to make one long line.


Header Files
Previous The GNU C Preprocessor Next

A header file is a file containing C declarations and macro definitions (see Macros) to be shared between several source files. You request the use of a header file in your program by including it, with the C preprocessing directive #include.

Header files serve two purposes.

  • System header files declare the interfaces to parts of the operating system. You include them in your program to supply the definitions and declarations you need to invoke system calls and libraries.

  • Your own header files contain declarations for interfaces between the source files of your program. Each time you have a group of related declarations and macro definitions all or most of which are needed in several different source files, it is a good idea to create a header file for them.
Including a header file produces the same results as copying the header file into each source file that needs it. Such copying would be time-consuming and error-prone. With a header file, the related declarations appear in only one place. If they need to be changed, they can be changed in one place, and programs that include the header file will automatically use the new version when next recompiled. The header file eliminates the labor of finding and changing all the copies as well as the risk that a failure to find one copy will result in inconsistencies within a program.

In C, the usual convention is to give header files names that end with .h. It is most portable to use only letters, digits, dashes, and underscores in header file names, and at most one dot.
  • Include Syntax
  • Include Operation
  • Once-Only Headers
  • Computed Includes
  • Wrapper Headers
  • System Headers


Include Syntax
Header Files Next

Both user and system header files are included using the preprocessing directive #include. It has two variants:

#include <file>
This variant is used for system header files. It searches for a file named file in a standard list of system directories. You can prepend directories to this list with the '-I' option (see Invocation).

#include "file"
This variant is used for header files of your own program. It searches for a file named file first in the directory containing the current file, then in the same directories used for <file>.
The argument of #include, whether delimited with quote marks or angle brackets, behaves like a string constant in that comments are not recognized, and macro names are not expanded. Thus, #include <x/*y> specifies inclusion of a system header file named x/*y.

However, if backslashes occur within file, they are considered ordinary text characters, not escape characters. None of the character escape sequences appropriate to string constants in C are processed. Thus, #include "x\n\\y" specifies a filename containing three backslashes. (Some systems interpret \ as a pathname separator. All of these also interpret / the same way. It is most portable to use only /.)

It is an error if there is anything (other than comments) on the line after the file name.


Include Operation
Previous Header Files Next

The #include directive works by directing the C preprocessor to scan the specified file as input before continuing with the rest of the current file. The output from the preprocessor contains the output already generated, followed by the output resulting from the included file, followed by the output that comes from the text after the #include directive. For example, if you have a header file header.h as follows,

char *test (void);
and a main program called program.c that uses the header file, like this,
int x;
#include "header.h"

int
main (void)
{
  puts (test ());
}
the compiler will see the same token stream as it would if program.c read
int x;
char *test (void);

int
main (void)
{
  puts (test ());
}
Included files are not limited to declarations and macro definitions; those are merely the typical uses. Any fragment of a C program can be included from another file. The include file could even contain the beginning of a statement that is concluded in the containing file, or the end of a statement that was started in the including file. However, an included file must consist of complete tokens. Comments and string literals which have not been closed by the end of an included file are invalid. For error recovery, they are considered to end at the end of the file.

To avoid confusion, it is best if header files contain only complete syntactic units - function declarations or definitions, type declarations, etc.

The line following the #include directive is always treated as a separate line by the C preprocessor, even if the included file lacks a final newline.


Once-Only Headers
Previous Header Files Next

If a header file happens to be included twice, the compiler will process its contents twice. This is very likely to cause an error, e.g. when the compiler sees the same structure definition twice. Even if it does not, it will certainly waste time.

The standard way to prevent this is to enclose the entire real contents of the file in a conditional, like this:

/* File foo.  */
#ifndef FILE_FOO_SEEN
#define FILE_FOO_SEEN

the entire file

#endif /* !FILE_FOO_SEEN */
This construct is commonly known as a wrapper #ifndef. When the header is included again, the conditional will be false, because FILE_FOO_SEEN is defined. The preprocessor will skip over the entire contents of the file, and the compiler will not see it twice.

CPP optimizes even further. It remembers when a header file has a wrapper #ifndef. If a subsequent #include specifies that header, and the macro in the #ifndef is still defined, it does not bother to rescan the file at all.

You can put comments outside the wrapper. They will not interfere with this optimization.

The macro FILE_FOO_SEEN is called the controlling macro or guard macro. In a user header file, the macro name should not begin with _. In a system header file, it should begin with __ to avoid conflicts with user programs. In any kind of header file, the macro name should contain the name of the file and some additional text, to avoid conflicts with other header files.


Computed Includes
Previous Header Files Next

Sometimes it is necessary to select one of several different header files to be included into your program. They might specify configuration parameters to be used on different sorts of operating systems, for instance. You could do this with a series of conditionals,

#if SYSTEM_1
# include "system_1.h"
#elif SYSTEM_2
# include "system_2.h"
#elif SYSTEM_3
...
#endif
That rapidly becomes tedious. Instead, the preprocessor offers the ability to use a macro for the header name. This is called a computed include. Instead of writing a header name as the direct argument of #include, you simply put a macro name there instead:
#define SYSTEM_H "system_1.h"
...
#include SYSTEM_H
SYSTEM_H will be expanded, and the preprocessor will look for system_1.h as if the #include had been written that way originally. SYSTEM_H could be defined by your Makefile with a '-D' option.

You must be careful when you define the macro. #define saves tokens, not text. The preprocessor has no way of knowing that the macro will be used as the argument of #include, so it generates ordinary tokens, not a header name. This is unlikely to cause problems if you use double-quote includes, which are close enough to string constants. If you use angle brackets, however, you may have trouble.

The syntax of a computed include is actually a bit more general than the above. If the first non-whitespace character after #include is not " or <, then the entire line is macro-expanded like running text would be.

If the line expands to a single string constant, the contents of that string constant are the file to be included. CPP does not re-examine the string for embedded quotes, but neither does it process backslash escapes in the string. Therefore
#define HEADER "a\"b"
#include HEADER
looks for a file named a\"b. CPP searches for the file according to the rules for double-quoted includes.

If the line expands to a token stream beginning with a < token and including a > token, then the tokens between the < and the first > are combined to form the filename to be included. Any whitespace between tokens is reduced to a single space; then any space after the initial < is retained, but a trailing space before the closing > is ignored. CPP searches for the file according to the rules for angle-bracket includes.

In either case, if there are any tokens on the line after the file name, an error occurs and the directive is not processed. It is also an error if the result of expansion does not match either of the two expected forms.

These rules are implementation-defined behavior according to the C standard. To minimize the risk of different compilers interpreting your computed includes differently, we recommend you use only a single object-like macro which expands to a string constant. This will also minimize confusion for people reading your program.


Wrapper Headers
Previous Header Files Next

Sometimes it is necessary to adjust the contents of a system-provided header file without editing it directly (although it is not very likely that this feature will ever be used in GCC4TI). GCC's fixincludes operation does this, for example. One way to do that would be to create a new header file with the same name and insert it in the search path before the original header. That works fine as long as you're willing to replace the old header entirely. But what if you want to refer to the old header from the new one?

You cannot simply include the old header with #include. That will start from the beginning, and find your new header again. If your header is not protected from multiple inclusion (see Once-Only Headers), it will recurse infinitely and cause a fatal error.

You could include the old header with an absolute pathname:

#include "/usr/include/old-header.h"
This works, but is not clean; should the system headers ever move, you would have to edit the new headers to match.

There is no way to solve this problem within the C standard, but you can use the GNU extension #include_next. It means, "Include the next file with this name." This directive works like #include except in searching for the specified file: it starts searching the list of header file directories after the directory in which the current file was found.

Suppose you specify '-I /usr/local/include', and the list of directories to search also includes /usr/include; and suppose both directories contain signal.h. Ordinary #include <signal.h> finds the file under /usr/local/include. If that file contains #include_next <signal.h>, it starts searching after that directory, and finds the file in /usr/include.

#include_next does not distinguish between <file> and "file" inclusion, nor does it check that the file you specify has the same name as the current file. It simply looks for the file named, starting with the directory in the search path after the one where the current file was found.

The use of #include_next can lead to great confusion. We recommend it be used only when there is no other alternative. In particular, it should not be used in the headers belonging to a specific program; it should be used only to make global corrections along the lines of fixincludes.


System Headers
Previous Header Files

The header files declaring interfaces to the operating system and runtime libraries often cannot be written in strictly conforming C. Therefore, GCC gives code found in system headers special treatment. All warnings, other than those generated by #warning (see Diagnostics), are suppressed while GCC is processing a system header. Macros defined in a system header are immune to a few warnings wherever they are expanded. This immunity is granted on an ad-hoc basis, when we find that a warning generates lots of false positives because of code in macros defined in system headers.

Normally, only the headers found in specific directories are considered system headers. These directories are determined when GCC is compiled. There are, however, two ways to make normal headers into system headers.

The '-isystem' command line option adds its argument to the list of directories to search for headers, just like '-I'. Any headers found in that directory will be considered system headers.

All directories named by '-isystem' are searched after all directories named by '-I', no matter what their order was on the command line. If the same directory is named by both '-I' and '-isystem', the '-I' option is ignored. GCC provides an informative message when this occurs if '-v' is used.

There is also a directive, #pragma GCC system_header, which tells GCC to consider the rest of the current include file a system header, no matter where it was found. Code that comes before the #pragma in the file will not be affected. #pragma GCC system_header has no effect in the primary source file.

On very old systems, some of the pre-defined system header directories get even more special treatment. GNU C++ considers code in headers found in those directories to be surrounded by an extern "C" block. There is no way to request this behavior with a #pragma, or from the command line.


Macros
Previous The GNU C Preprocessor Next

A macro is a fragment of code which has been given a name. Whenever the name is used, it is replaced by the contents of the macro. There are two kinds of macros. They differ mostly in what they look like when they are used. Object-like macros resemble data objects when used, function-like macros resemble function calls.

You may define any valid identifier as a macro, even if it is a C keyword. The preprocessor does not know anything about keywords. This can be useful if you wish to hide a keyword such as const from an older compiler that does not understand it. However, the preprocessor operator defined can never be defined as a macro.

  • Object-like Macros
  • Function-like Macros
  • Stringification
  • Concatenation
  • Undefining and Redefining Macros
  • Predefined Macros
  • Directives Within Macro Arguments
  • Macro Pitfalls


Object-like Macros
Macros Next

An object-like macro is a simple identifier which will be replaced by a code fragment. It is called object-like because it looks like a data object in code that uses it. They are most commonly used to give symbolic names to numeric constants.

You create macros with the #define directive. #define is followed by the name of the macro and then the token sequence it should be an abbreviation for, which is variously referred to as the macro's body, expansion or replacement list. For example,

#define BUFFER_SIZE 1024
defines a macro named BUFFER_SIZE as an abbreviation for the token 1024. If somewhere after this #define directive there comes a C statement of the form
foo = (char *) malloc (BUFFER_SIZE);
then the C preprocessor will recognize and expand the macro BUFFER_SIZE. The C compiler will see the same tokens as it would if you had written
foo = (char *) malloc (1024);
By convention, macro names are written in upper case. Programs are easier to read when it is possible to tell at a glance which names are macros.

The macro's body ends at the end of the #define line. You may continue the definition onto multiple lines, if necessary, using backslash-newline. When the macro is expanded, however, it will all come out on one line. For example,
#define NUMBERS 1, \
                2, \
                3
int x[] = { NUMBERS };
     expands to int x[] = { 1, 2, 3 };
The most common visible consequence of this is surprising line numbers in error messages.

There is no restriction on what can go in a macro body provided it decomposes into valid preprocessing tokens. Parentheses need not balance, and the body need not resemble valid C code. (If it does not, you may get error messages from the C compiler when you use the macro.)

The C preprocessor scans your program sequentially. Macro definitions take effect at the place you write them. Therefore, the following input to the C preprocessor
foo = X;
#define X 4
bar = X;
produces
foo = X;
bar = 4;
When the preprocessor expands a macro name, the macro's expansion replaces the macro invocation, then the expansion is examined for more macros to expand. For example,
#define TABLESIZE BUFSIZE
#define BUFSIZE 1024
TABLESIZE
     expands to BUFSIZE
     expands to 1024
TABLESIZE is expanded first to produce BUFSIZE, then that macro is expanded to produce the final result, 1024.

Notice that BUFSIZE was not defined when TABLESIZE was defined. The #define for TABLESIZE uses exactly the expansion you specify - in this case, BUFSIZE - and does not check to see whether it too contains macro names. Only when you use TABLESIZE is the result of its expansion scanned for more macro names.

This makes a difference if you change the definition of BUFSIZE at some point in the source file. TABLESIZE, defined as shown, will always expand using the definition of BUFSIZE that is currently in effect:
#define BUFSIZE 1020
#define TABLESIZE BUFSIZE
#undef BUFSIZE
#define BUFSIZE 37
Now TABLESIZE expands (in two stages) to 37.

If the expansion of a macro contains its own name, either directly or via intermediate macros, it is not expanded again when the expansion is examined for more macros. This prevents infinite recursion. See Self-Referential Macros for the precise details.


Function-like Macros
Previous Macros Next

You can also define macros whose use looks like a function call. These are called function-like macros. To define a function-like macro, you use the same #define directive, but you put a pair of parentheses immediately after the macro name. For example,

#define lang_init()  c_init()
lang_init()
     expands to c_init()
A function-like macro is only expanded if its name appears with a pair of parentheses after it. If you write just the name, it is left alone. This can be useful when you have a function and a macro of the same name, and you wish to use the function sometimes.
extern void foo(void);
#define foo() /* optimized inline version */
...
  foo();
  funcptr = foo;
Here the call to foo() will use the macro, but the function pointer will get the address of the real function. If the macro were to be expanded, it would cause a syntax error.

If you put spaces between the macro name and the parentheses in the macro definition, that does not define a function-like macro, it defines an object-like macro whose expansion happens to begin with a pair of parentheses.
#define lang_init ()    c_init()
lang_init()
     expands to () c_init()()
The first two pairs of parentheses in this expansion come from the macro. The third is the pair that was originally after the macro invocation. Since lang_init is an object-like macro, it does not consume those parentheses.
  • Macro Arguments
  • Variadic Macros


Macro Arguments
Function-like Macros Next

Function-like macros can take arguments, just like true functions. To define a macro that uses arguments, you insert parameters between the pair of parentheses in the macro definition that make the macro function-like. The parameters must be valid C identifiers, separated by commas and optionally whitespace.

To invoke a macro that takes arguments, you write the name of the macro followed by a list of actual arguments in parentheses, separated by commas. The invocation of the macro need not be restricted to a single logical line - it can cross as many lines in the source file as you wish. The number of arguments you give must match the number of parameters in the macro definition. When the macro is expanded, each use of a parameter in its body is replaced by the tokens of the corresponding argument. (You need not use all of the parameters in the macro body.)

As an example, here is a macro that computes the minimum of two numeric values, as it is defined in many C programs, and some uses.

#define min(X, Y)  ((X) < (Y) ? (X) : (Y))
  x = min(a, b);          expands to  x = ((a) < (b) ? (a) : (b));
  y = min(1, 2);          expands to  y = ((1) < (2) ? (1) : (2));
  z = min(a + 28, *p);    expands to  z = ((a + 28) < (*p) ? (a + 28) : (*p));
(In this small example you can already see several of the dangers of macro arguments. See Macro Pitfalls for detailed explanations.)

Leading and trailing whitespace in each argument is dropped, and all whitespace between the tokens of an argument is reduced to a single space. Parentheses within each argument must balance; a comma within such parentheses does not end the argument. However, there is no requirement for square brackets or braces to balance, and they do not prevent a comma from separating arguments. Thus,
macro (array[x = y, x + 1])
passes two arguments to macro: array[x = y and x + 1]. If you want to supply array[x = y, x + 1] as an argument, you can write it as array[(x = y, x + 1)], which is equivalent C code.

All arguments to a macro are completely macro-expanded before they are substituted into the macro body. After substitution, the complete text is scanned again for macros to expand, including the arguments. This rule may seem strange, but it is carefully designed so you need not worry about whether any function call is actually a macro invocation. You can run into trouble if you try to be too clever, though. See Argument Prescan for detailed discussion.

For example, min (min (a, b), c) is first expanded to
  min (((a) < (b) ? (a) : (b)), (c))
and then to
((((a) < (b) ? (a) : (b))) < (c)
 ? (((a) < (b) ? (a) : (b)))
 : (c))
(Line breaks shown here for clarity would not actually be generated.)

You can leave macro arguments empty; this is not an error to the preprocessor (but many macros will then expand to invalid code). You cannot leave out arguments entirely; if a macro takes two arguments, there must be exactly one comma at the top level of its argument list. Here are some silly examples using min:
min(, b)        expands to ((   ) < (b) ? (   ) : (b))
min(a, )        expands to ((a  ) < ( ) ? (a  ) : ( ))
min(,)          expands to ((   ) < ( ) ? (   ) : ( ))
min((,),)       expands to (((,)) < ( ) ? ((,)) : ( ))

min()      Error: macro "min" requires 2 arguments, but only 1 given
min(,,)    Error: macro "min" passed 3 arguments, but takes just 2
Whitespace is not a preprocessing token, so if a macro foo takes one argument, foo () and foo ( ) both supply it an empty argument. Previous GNU preprocessor implementations and documentation were incorrect on this point, insisting that a function-like macro that takes a single argument be passed a space if an empty argument was required.

Macro parameters appearing inside string literals are not replaced by their corresponding actual arguments.
#define foo(x) x, "x"
foo(bar)        expands to bar, "x"


Variadic Macros
Previous Function-like Macros

A macro can be declared to accept a variable number of arguments much as a function can. The syntax for defining the macro is similar to that of a function. Here is an example:

#define lprintf(...) fprintf (log, __VA_ARGS__)
This kind of macro is called variadic. When the macro is invoked, all the tokens in its argument list after the last named argument (this macro has none), including any commas, become the variable argument. This sequence of tokens replaces the identifier __VA_ARGS__ in the macro body wherever it appears. Thus, we have this expansion:
lprintf ("%s:%d: ", input_file, lineno);
  --> fprintf (log, "%s:%d: ", input_file, lineno);
The variable argument is completely macro-expanded before it is inserted into the macro expansion, just like an ordinary argument. You may use the # and ## operators to stringify the variable argument or to paste its leading or trailing token with another token. (But see below for an important special case for ##.)

If your macro is complicated, you may want a more descriptive name for the variable argument than __VA_ARGS__. CPP permits this, as an extension. You may write an argument name immediately before the ...; that name is used for the variable argument. The lprintf macro above could be written
#define lprintf(args...) fprintf (log, args)
using this extension. You cannot use __VA_ARGS__ and this extension in the same macro.

You can have named arguments as well as variable arguments in a variadic macro. We could define lprintf like this, instead:
#define lprintf(format, ...) fprintf (log, format, __VA_ARGS__)
This formulation looks more descriptive, but unfortunately it is less flexible: you must now supply at least one argument after the format string. In standard C, you cannot omit the comma separating the named argument from the variable arguments. Furthermore, if you leave the variable argument empty, you will get a syntax error, because there will be an extra comma after the format string.
lprintf ("success!\n", );
  --> fprintf (log, "success!\n", );
GNU CPP has a pair of extensions which deal with this problem. First, you are allowed to leave the variable argument out entirely:
lprintf ("success!\n");
  --> fprintf (log, "success!\n", );
Second, the ## token paste operator has a special meaning when placed between a comma and a variable argument. If you write
#define lprintf(format, ...) fprintf (log, format, ##__VA_ARGS__)
and the variable argument is left out when the lprintf macro is used, then the comma before the ## will be deleted. This does not happen if you pass an empty argument, nor does it happen if the token preceding ## is anything other than a comma.
lprintf ("success!\n")
  --> fprintf (log, "success!\n");
The above explanation is ambiguous about the case where the only macro parameter is a variable arguments parameter, as it is meaningless to try to distinguish whether no argument at all is an empty argument or a missing argument. In this case the C99 standard is clear that the comma must remain, however the existing GCC extension used to swallow the comma. So CPP retains the comma when conforming to a specific C standard, and drops it otherwise.

C99 mandates that the only place the identifier __VA_ARGS__ can appear is in the replacement list of a variadic macro. It may not be used as a macro name, macro argument name, or within a different type of macro. It may also be forbidden in open text; the standard is ambiguous. We recommend you avoid using it except for its defined purpose.

Variadic macros are a new feature in C99. GNU CPP has supported them for a long time, but only with a named variable argument (args..., not ... and __VA_ARGS__). If you are concerned with portability to previous versions of GCC, you should use only named variable arguments. On the other hand, if you are concerned with portability to other conforming implementations of C99, you should use only __VA_ARGS__.

Previous versions of CPP implemented the comma-deletion extension much more generally. We have restricted it in this release to minimize the differences from C99. To get the same effect with both this and previous versions of GCC, the token preceding the special ## must be a comma, and there must be white space between that comma and whatever comes immediately before it:
#define lprintf(format, args...) fprintf (log, format , ##args)
See Differences from Previous Versions for the gory details.


Stringification
Previous Macros Next

Sometimes you may want to convert a macro argument into a string constant. Parameters are not replaced inside string constants, but you can use the # preprocessing operator instead. When a macro parameter is used with a leading #, the preprocessor replaces it with the literal text of the actual argument, converted to a string constant. Unlike normal parameter replacement, the argument is not macro-expanded first. This is called stringification.

There is no way to combine an argument with surrounding text and stringify it all together. Instead, you can write a series of adjacent string constants and stringified arguments. The preprocessor will replace the stringified arguments with string constants. The C compiler will then combine all the adjacent string constants into one long string.

Here is an example of a macro definition that uses stringification:

#define WARN_IF(EXP) \
do { if (EXP) \
        fprintf (stderr, "Warning: " #EXP "\n"); } \
while (0)
WARN_IF (x == 0);
     expands to do { if (x == 0)
           fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0);
The argument for EXP is substituted once, as-is, into the if statement, and once, stringified, into the argument to fprintf. If x were a macro, it would be expanded in the if statement, but not in the string.

The do and while (0) are a kludge to make it possible to write WARN_IF (arg);, which the resemblance of WARN_IF to a function would make C programmers want to do; see Swallowing the Semicolon.

Stringification in C involves more than putting double-quote characters around the fragment. The preprocessor backslash-escapes the quotes surrounding embedded string constants, and all backslashes within string and character constants, in order to get a valid C string constant with the proper contents. Thus, stringifying p = "foo\n"; results in "p = \"foo\\n\";". However, backslashes that are not inside string or character constants are not duplicated: \n by itself stringifies to "\n".

All leading and trailing whitespace in text being stringified is ignored. Any sequence of whitespace in the middle of the text is converted to a single space in the stringified result. Comments are replaced by whitespace long before stringification happens, so they never appear in stringified text.

There is no way to convert a macro argument into a character constant.

If you want to stringify the result of expansion of a macro argument, you have to use two levels of macros.
#define xstr(s) str(s)
#define str(s) #s
#define foo 4
str (foo)
     expands to "foo"
xstr (foo)
     expands to xstr (4)
     expands to str (4)
     expands to "4"
s is stringified when it is used in str, so it is not macro-expanded first. But s is an ordinary argument to xstr, so it is completely macro-expanded before xstr itself is expanded (see Argument Prescan). Therefore, by the time str gets to its argument, it has already been macro-expanded.


Concatenation
Previous Macros Next

It is often useful to merge two tokens into one while expanding macros. This is called token pasting or token concatenation. The ## preprocessing operator performs token pasting. When a macro is expanded, the two tokens on either side of each ## operator are combined into a single token, which then replaces the ## and the two original tokens in the macro expansion. Usually both will be identifiers, or one will be an identifier and the other a preprocessing number. When pasted, they make a longer identifier. This isn't the only valid case. It is also possible to concatenate two numbers (or a number and a name, such as 1.5 and e3) into a number. Also, multi-character operators such as += can be formed by token pasting.

However, two tokens that don't together form a valid token cannot be pasted together. For example, you cannot concatenate x with + in either order. If you try, the preprocessor issues a warning and emits the two tokens. Whether it puts white space between the tokens is undefined. It is common to find unnecessary uses of ## in complex macros. If you get this warning, it is likely that you can simply remove the ##.

Both the tokens combined by ## could come from the macro body, but you could just as well write them as one token in the first place. Token pasting is most useful when one or both of the tokens comes from a macro argument. If either of the tokens next to an ## is a parameter name, it is replaced by its actual argument before ## executes. As with stringification, the actual argument is not macro-expanded first. If the argument is empty, that ## has no effect.

Keep in mind that the C preprocessor converts comments to whitespace before macros are even considered. Therefore, you cannot create a comment by concatenating / and *. You can put as much whitespace between ## and its operands as you like, including comments, and you can put comments in arguments that will be concatenated. However, it is an error if ## appears at either end of a macro body.

Consider a C program that interprets named commands. There probably needs to be a table of commands, perhaps an array of structures declared as follows:

struct command
{
  char *name;
  void (*function) (void);
};

struct command commands[] =
{
  { "quit", quit_command },
  { "help", help_command },
  ...
};
It would be cleaner not to have to give each command name twice, once in the string constant and once in the function name. A macro which takes the name of a command as an argument can make this unnecessary. The string constant can be created with stringification, and the function name by concatenating the argument with _command. Here is how it is done:
#define COMMAND(NAME)  { #NAME, NAME ## _command }

struct command commands[] =
{
  COMMAND (quit),
  COMMAND (help),
  ...
};


Undefining and Redefining Macros
Previous Macros Next

If a macro ceases to be useful, it may be undefined with the #undef directive. #undef takes a single argument, the name of the macro to undefine. You use the bare macro name, even if the macro is function-like. It is an error if anything appears on the line after the macro name. #undef has no effect if the name is not a macro.

#define FOO 4
x = FOO;        expands to x = 4;
#undef FOO
x = FOO;        expands to x = FOO;
Once a macro has been undefined, that identifier may be redefined as a macro by a subsequent #define directive. The new definition need not have any resemblance to the old definition.

However, if an identifier which is currently a macro is redefined, then the new definition must be effectively the same as the old one. Two macro definitions are effectively the same if:
  • Both are the same type of macro (object- or function-like).

  • All the tokens of the replacement list are the same.

  • If there are any parameters, they are the same.

  • Whitespace appears in the same places in both. It need not be exactly the same amount of whitespace, though. Remember that comments count as whitespace.
These definitions are effectively the same:
#define FOUR (2 + 2)
#define FOUR         (2    +    2)
#define FOUR (2 /* two */ + 2)
but these are not:
#define FOUR (2 + 2)
#define FOUR ( 2+2 )
#define FOUR (2 * 2)
#define FOUR(score,and,seven,years,ago) (2 + 2)
If a macro is redefined with a definition that is not effectively the same as the old one, the preprocessor issues a warning and changes the macro to use the new definition. If the new definition is effectively the same, the redefinition is silently ignored. This allows, for instance, two different headers to define a common macro. The preprocessor will only complain if the definitions do not match.


Predefined Macros
Previous Macros Next

Several object-like macros are predefined; you use them without supplying their definitions. They fall into three classes: standard, common, and system-specific.

In C++, there is a fourth category, the named operators. They act like predefined macros, but you cannot undefine them.

  • Standard Predefined Macros
  • Common Predefined Macros
  • System-specific Predefined Macros


Standard Predefined Macros
Predefined Macros Next

The standard predefined macros are specified by the C and/or C++ language standards, so they are available with all compilers that implement those standards. Older compilers may not provide all of them. Their names all start with double underscores.

  • __FILE__
  • __LINE__
  • __DATE__
  • __TIME__
  • __STDC__
  • __STDC_VERSION__
  • __STDC_HOSTED__


__FILE__
Standard Predefined Macros Next

This macro expands to the name of the current input file, in the form of a C string constant. This is the path by which the preprocessor opened the file, not the short name specified in #include or as the input file name argument. For example, "/usr/local/include/myheader.h" is a possible expansion of this macro.


__LINE__
Previous Standard Predefined Macros Next

This macro expands to the current input line number, in the form of a decimal integer constant. While we call it a predefined macro, it's a pretty strange macro, since its "definition" changes with each new line of source code.

__FILE__ and __LINE__ are useful in generating an error message to report an inconsistency detected by the program; the message can state the source line at which the inconsistency was detected. For example,

fprintf (stderr, "Internal error: "
                 "negative string length "
                 "%d at %s, line %d.",
         length, __FILE__, __LINE__);
An #include directive changes the expansions of __FILE__ and __LINE__ to correspond to the included file. At the end of that file, when processing resumes on the input file that contained the #include directive, the expansions of __FILE__ and __LINE__ revert to the values they had before the #include (but __LINE__ is then incremented by one as processing moves to the line after the #include).

A #line directive changes __LINE__, and may change __FILE__ as well. See Line Control.

C99 introduces __func__, and GCC has provided __FUNCTION__ for a long time. Both of these are strings containing the name of the current function (there are slight semantic differences; see Function Names as Strings). Neither of them is a macro; the preprocessor does not know the name of the current function. They tend to be useful in conjunction with __FILE__ and __LINE__, though.


__DATE__
Previous Standard Predefined Macros Next

This macro expands to a string constant that describes the date on which the preprocessor is being run. The string constant contains eleven characters and looks like "Feb 12 1996". If the day of the month is less than 10, it is padded with a space on the left.

If GCC cannot determine the current date, it will emit a warning message (once per compilation) and __DATE__ will expand to "??? ?? ????".


__TIME__
Previous Standard Predefined Macros Next

This macro expands to a string constant that describes the time at which the preprocessor is being run. The string constant contains eight characters and looks like "23:59:01".

If GCC cannot determine the current time, it will emit a warning message (once per compilation) and __TIME__ will expand to "??:??:??".


__STDC__
Previous Standard Predefined Macros Next

In normal operation, this macro expands to the constant 1, to signify that this compiler conforms to ISO Standard C. If GNU CPP is used with a compiler other than GCC, this is not necessarily true; however, the preprocessor always conforms to the standard unless the '-traditional-cpp' option is used.

This macro is not defined if the '-traditional-cpp' option is used.


__STDC_VERSION__
Previous Standard Predefined Macros Next

This macro expands to the C Standard's version number, a long integer constant of the form yyyymmL where yyyy and mm are the year and month of the Standard version. This signifies which version of the C Standard the compiler conforms to.

The value 199409L signifies the 1989 C standard as amended in 1994, which is the current default; the value 199901L signifies the 1999 revision of the C standard. Support for the 1999 revision is not yet complete.

This macro is not defined if the '-traditional-cpp' option is used.


__STDC_HOSTED__
Previous Standard Predefined Macros

This macro is defined, with value 1, if the compiler's target is a hosted environment. A hosted environment has the complete facilities of the standard C library available.


Common Predefined Macros
Previous Predefined Macros Next

The common predefined macros are GNU C extensions. They are available with the same meanings regardless of the machine or operating system on which you are using GNU C. Their names all start with double underscores.

  • __GNUC__
  • __GNUC_MINOR__
  • __GNUC_PATCHLEVEL__
  • __VERSION__
  • __STRICT_ANSI__
  • __BASE_FILE__
  • __INCLUDE_LEVEL__
  • __OPTIMIZE__
  • __OPTIMIZE_SIZE__
  • __NO_INLINE__
  • __CHAR_UNSIGNED__
  • __CHAR_BIT__
  • __INT_SHORT__
  • __SCHAR_MAX__, __SHRT_MAX__, __INT_MAX__, __LONG_MAX__, __LONG_LONG_MAX__
  • __REGISTER_PREFIX__
  • __USER_LABEL_PREFIX__


__GNUC__
Common Predefined Macros Next

This macro is always defined in GCC. The value identifies the GCC major version number (currently '3').

If all you need to know is whether or not your program is being compiled by GCC, you can simply test __GNUC__. If you need to write code which depends on a specific version, you must be more careful. Each time the minor version is increased, the patch level is reset to zero; each time the major version is increased (which happens rarely), the minor version and patch level are reset. If you wish to use the predefined macros directly in the conditional, you will need to write it like this:

/* Test for GCC > 3.2.0 */
#if __GNUC__ > 3 || \
    (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \
                       (__GNUC_MINOR__ == 2 && \
                        __GNUC_PATCHLEVEL__ > 0))
Another approach is to use the predefined macros to calculate a single number, then compare that against a threshold:
#define GCC_VERSION (__GNUC__ * 10000 \
                     + __GNUC_MINOR__ * 100 \
                     + __GNUC_PATCHLEVEL__)
...
/* Test for GCC > 3.2.0 */
#if GCC_VERSION > 30200
Many people find this form easier to understand.

See also: __GNUC_MINOR__, __GNUC_PATCHLEVEL__


__GNUC_MINOR__
Previous Common Predefined Macros Next

The macro contains the minor version number of the compiler. This can be used to work around differences between different releases of the compiler. It must always be used together with __GNUC__.


__GNUC_PATCHLEVEL__
Previous Common Predefined Macros Next

The macro contains the bugfix version number of the compiler. This can be used to work around differences between different releases of the compiler. It must always be used together with __GNUC__ and __GNUC_MINOR__.

__GNUC_PATCHLEVEL__ is new to GCC 3.0; it is also present in the widely-used development snapshots leading up to 3.0 (which identify themselves as GCC 2.96 or 2.97, depending on which snapshot you have).


__VERSION__
Previous Common Predefined Macros Next

This macro expands to a string constant which describes the version of the compiler in use. You should not rely on its contents having any particular form, but it can be counted on to contain at least the release number.


__STRICT_ANSI__
Previous Common Predefined Macros Next

GCC defines this macro if and only if the '-ansi' switch, or a '-std' switch specifying strict conformance to some version of ISO C, was specified when GCC was invoked. It is defined to 1. This macro exists primarily to direct GNU libc's header files to restrict their definitions to the minimal set found in the 1989 C standard.


__BASE_FILE__
Previous Common Predefined Macros Next

This macro expands to the name of the main input file, in the form of a C string constant. This is the source file that was specified on the command line of the preprocessor or C compiler.


__INCLUDE_LEVEL__
Previous Common Predefined Macros Next

This macro expands to a decimal integer constant that represents the depth of nesting in include files. The value of this macro is incremented on every #include directive and decremented at the end of every included file. It starts out at 0, its value within the base file specified on the command line.


__OPTIMIZE__
Previous Common Predefined Macros Next

GNU CC defines this macro in optimizing compilations. Along with __OPTIMIZE_SIZE__ and __NO_INLINE__, it allows certain header files to define alternative macro definitions for some system library functions. You should not refer to or test the definition of this macro unless you make very sure that programs will execute with the same effect regardless. If it is defined, its value is 1.

See also: __OPTIMIZE_SIZE__, __NO_INLINE__


__OPTIMIZE_SIZE__
Previous Common Predefined Macros Next

This macro is defined in addition to __OPTIMIZE__ if the compiler is optimizing for size, not speed.


__NO_INLINE__
Previous Common Predefined Macros Next

This macro is defined if no functions will be inlined into their callers (when not optimizing, or when inlining has been specifically disabled by '-fno-inline').


__CHAR_UNSIGNED__
Previous Common Predefined Macros Next

This macro is defined if and only if the data type char is unsigned. Note that this is not true on GCC4TI by default, but it may be changed using some compiler command switches. It exists to cause the standard header file limits.h to work correctly. You should not refer to this macro yourself; instead, refer to the standard macros defined in limits.h.


__CHAR_BIT__
Previous Common Predefined Macros Next

Defined to the number of bits used in the representation of the char data type. It exists to make the standard header given numerical limits work correctly. You should not use this macro directly; instead, include the appropriate headers.


__INT_SHORT__
Previous Common Predefined Macros Next

GCC4TI defines this macro if and only if the data type int represents a short integer (short). Note that this is always true in GCC4TI by default, but it may be changed using some compiler command line switches. It exists to cause the standard header file limits.h to work correctly. You should not refer to this macro yourself; instead, refer to the standard macros defined in limits.h.


__SCHAR_MAX__, __SHRT_MAX__, __INT_MAX__, __LONG_MAX__, __LONG_LONG_MAX__
Previous Common Predefined Macros Next

Defined to the maximum value of the signed char, signed short, signed int, signed long, and signed long long types, respectively. They exist to make the standard header given numerical limits work correctly. You should not use these macros directly; instead, include the appropriate headers.


__REGISTER_PREFIX__
Previous Common Predefined Macros Next

This macro expands to a single token (not a string constant) which is the prefix applied to CPU register names in assembly language for this target. You can use it to write assembly that is usable in multiple environments. For example, in the m68k-aout environment it expands to nothing, but in the m68k-coff environment (as GCC4TI is) it expands to a single %.


__USER_LABEL_PREFIX__
Previous Common Predefined Macros

This macro expands to a single token which is the prefix applied to user labels (symbols visible to C code) in assembly. For example, in the m68k-aout environment it expands to an _, but in the m68k-coff environment (as GCC4TI is) it expands to nothing.

This macro will have the correct definition even if '-f(no-)underscores' is in use, but it will not be correct if target-specific options that adjust this prefix are used (e.g. the OSF/rose '-mno-underscores' option).


System-specific Predefined Macros
Previous Predefined Macros

The C preprocessor normally predefines several macros that indicate what type of system and machine is in use. They are obviously different on each target supported by GCC. GCC4TI currently defines only two such macros: mc68000 (predefined on most computers whose CPU is a Motorola 68000, 68010 or 68020) and __embedded__. You can use cpp -dM to see all macros defined (see Invocation). All system-specific predefined macros expand to the constant 1, so you can test them with either #ifdef or #if.

The C standard requires that all system-specific macros be part of the reserved namespace. All names which begin with two underscores, or an underscore and a capital letter, are reserved for the compiler and library to use as they wish. However, historically system-specific macros have had names with no special prefix; for instance, it is common to find unix defined on Unix systems. For all such macros, GCC provides a parallel macro with two underscores added at the beginning and the end. If unix is defined, __unix__ will be defined too. There will never be more than two underscores; the parallel of _mips is __mips__.

When the '-ansi' option, or any '-std' option that requests strict conformance, is given to the compiler, all the system-specific predefined macros outside the reserved namespace are suppressed. The parallel macros, inside the reserved namespace, remain defined.

We are slowly phasing out all predefined macros which are outside the reserved namespace. You should never use them in new programs, and we encourage you to correct older code to use the parallel macros whenever you find it. We don't recommend you use the system-specific macros that are in the reserved namespace, either. It is better in the long run to check specifically for features you need, using a tool such as autoconf.


Directives Within Macro Arguments
Previous Macros Next

Occasionally it is convenient to use preprocessor directives within the arguments of a macro. The C and C++ standards declare that behavior in these cases is undefined.

Versions of CPP prior to 3.2 would reject such constructs with an error message. This was the only syntactic difference between normal functions and function-like macros, so it seemed attractive to remove this limitation, and people would often be surprised that they could not use macros in this way. Moreover, sometimes people would use conditional compilation in the argument list to a normal library function like printf, only to find that after a library upgrade printf had changed to be a function-like macro, and their code would no longer compile. So from version 3.2 we changed CPP to successfully process arbitrary directives within macro arguments in exactly the same way as it would have processed the directive were the function-like macro invocation not present.

If, within a macro invocation, that macro is redefined, then the new definition takes effect in time for argument pre-expansion, but the original definition is still used for argument replacement. Here is a pathological example:

#define f(x) x x
f (1
#undef f
#define f 2
f)
which expands to
1 2 1 2
with the semantics described above.


Macro Pitfalls
Previous Macros

In this section, we describe some special rules that apply to macros and macro expansion, and point out certain cases in which the rules have counter-intuitive consequences that you must watch out for.

  • Misnesting
  • Operator Precedence Problems
  • Swallowing the Semicolon
  • Duplication of Side Effects
  • Self-Referential Macros
  • Argument Prescan
  • Newlines in Arguments


Misnesting
Macro Pitfalls Next

When a macro is called with arguments, the arguments are substituted into the macro body and the result is checked, together with the rest of the input file, for more macro calls. It is possible to piece together a macro call coming partially from the macro body and partially from the arguments. For example,

#define twice(x) (2*(x))
#define call_with_1(x) x(1)
call_with_1 (twice)
     expands to twice(1)
     expands to (2*(1))
Macro definitions do not have to have balanced parentheses. By writing an unbalanced open parenthesis in a macro body, it is possible to create a macro call that begins inside the macro body but ends outside of it. For example,
#define strange(file) fprintf (file, "%s %d",
...
strange(stderr) p, 35)
     expands to fprintf (stderr, "%s %d", p, 35)
The ability to piece together a macro call can be useful, but the use of unbalanced open parentheses in a macro body is just confusing, and should be avoided.


Operator Precedence Problems
Previous Macro Pitfalls Next

You may have noticed that in most of the macro definition examples shown above, each occurrence of a macro argument name had parentheses around it. In addition, another pair of parentheses usually surround the entire macro definition. Here is why it is best to write macros that way.

Suppose you define a macro as follows,

#define ceil_div(x, y) (x + y - 1) / y
whose purpose is to divide, rounding up. (One use for this operation is to compute how many int objects are needed to hold a certain number of char objects.) Then suppose it is used as follows:
a = ceil_div (b & c, sizeof (int));
     expands to a = (b & c + sizeof (int) - 1) / sizeof (int);
This does not do what is intended. The operator-precedence rules of C make it equivalent to this:
a = (b & (c + sizeof (int) - 1)) / sizeof (int);
What we want is this:
a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
Defining the macro as
#define ceil_div(x, y) ((x) + (y) - 1) / (y)
provides the desired result.

Unintended grouping can result in another way. Consider sizeof ceil_div(1, 2). That has the appearance of a C expression that would compute the size of the type of ceil_div (1, 2), but in fact it means something very different. Here is what it expands to:
sizeof ((1) + (2) - 1) / (2)
This would take the size of an integer and divide it by two. The precedence rules have put the division outside the sizeof when it was intended to be inside.

Parentheses around the entire macro definition prevent such problems. Here, then, is the recommended way to define ceil_div:
#define ceil_div(x, y) (((x) + (y) - 1) / (y))


Swallowing the Semicolon
Previous Macro Pitfalls Next

Often it is desirable to define a macro that expands into a compound statement. Consider, for example, the following macro, that advances a pointer (the argument p says where to find it) across whitespace characters:

#define SKIP_SPACES(p, limit)  \
{ char *lim = (limit);         \
  while (p < lim) {            \
    if (*p++ != ' ') {         \
      p--; break; }}}
Here backslash-newline is used to split the macro definition, which must be a single logical line, so that it resembles the way such code would be laid out if not part of a macro definition.

A call to this macro might be SKIP_SPACES (p, lim). Strictly speaking, the call expands to a compound statement, which is a complete statement with no need for a semicolon to end it. However, since it looks like a function call, it minimizes confusion if you can use it like a function call, writing a semicolon afterward, as in SKIP_SPACES (p, lim);

This can cause trouble before else statements, because the semicolon is actually a null statement. Suppose you write
if (*p != 0)
  SKIP_SPACES (p, lim);
else ...
The presence of two statements - the compound statement and a null statement - in between the if condition and the else makes invalid C code.

The definition of the macro SKIP_SPACES can be altered to solve this problem, using a do ... while statement. Here is how:
#define SKIP_SPACES(p, limit)     \
do { char *lim = (limit);         \
     while (p < lim) {            \
       if (*p++ != ' ') {         \
         p--; break; }}}          \
while (0)
Now SKIP_SPACES (p, lim); expands into
do {...} while (0);
which is one statement. The loop executes exactly once; most compilers generate no extra code for it.


Duplication of Side Effects
Previous Macro Pitfalls Next

Many C programs define a macro min, for "minimum", like this:

#define min(X, Y)  ((X) < (Y) ? (X) : (Y))
When you use this macro with an argument containing a side effect, as shown here,
next = min (x + y, foo (z));
it expands as follows:
next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
where x + y has been substituted for X and foo (z) for Y.

The function foo is used only once in the statement as it appears in the program, but the expression foo (z) has been substituted twice into the macro expansion. As a result, foo might be called two times when the statement is executed. If it has side effects or if it takes a long time to compute, the results might not be what you intended. We say that min is an unsafe macro.

The best solution to this problem is to define min in a way that computes the value of foo (z) only once. The C language offers no standard way to do this, but it can be done with GNU extensions as follows:
#define min(X, Y)                \
({ typeof (X) x_ = (X);          \
   typeof (Y) y_ = (Y);          \
   (x_ < y_) ? x_ : y_; })
The ({ ... }) notation produces a compound statement that acts as an expression. Its value is the value of its last statement. This permits us to define local variables and assign each argument to one. The local variables have underscores after their names to reduce the risk of conflict with an identifier of wider scope (it is impossible to avoid this entirely). Now each argument is evaluated exactly once.

If you do not wish to use GNU C extensions, the only solution is to be careful when using the macro min. For example, you can calculate the value of foo (z), save it in a variable, and use that variable in min:
#define min(X, Y)  ((X) < (Y) ? (X) : (Y))
...
{
  int tem = foo (z);
  next = min (x + y, tem);
}
(where we assume that foo returns type int).


Self-Referential Macros
Previous Macro Pitfalls Next

A self-referential macro is one whose name appears in its definition. Recall that all macro definitions are rescanned for more macros to replace. If the self-reference were considered a use of the macro, it would produce an infinitely large expansion. To prevent this, the self-reference is not considered a macro call. It is passed into the preprocessor output unchanged. Let's consider an example:

#define foo (4 + foo)
where foo is also a variable in your program.

Following the ordinary rules, each reference to foo will expand into (4 + foo); then this will be rescanned and will expand into (4 + (4 + foo)); and so on until the computer runs out of memory.

The self-reference rule cuts this process short after one step, at (4 + foo). Therefore, this macro definition has the possibly useful effect of causing the program to add 4 to the value of foo wherever foo is referred to.

In most cases, it is a bad idea to take advantage of this feature. A person reading the program who sees that foo is a variable will not expect that it is a macro as well. The reader will come across the identifier foo in the program and think its value should be that of the variable foo, whereas in fact the value is four greater.

One common, useful use of self-reference is to create a macro which expands to itself. If you write
#define EPERM EPERM
then the macro EPERM expands to EPERM. Effectively, it is left alone by the preprocessor whenever it's used in running text. You can tell that it's a macro with #ifdef. You might do this if you want to define numeric constants with an enum, but have #ifdef be true for each constant.

If a macro x expands to use a macro y, and the expansion of y refers to the macro x, that is an indirect self-reference of x. x is not expanded in this case either. Thus, if we have
#define x (4 + y)
#define y (2 * x)
then x and y expand as follows:
x    expands to (4 + y)
     expands to (4 + (2 * x))

y    expands to (2 * x)
     expands to (2 * (4 + y))
Each macro is expanded when it appears in the definition of the other macro, but not when it indirectly appears in its own definition.


Argument Prescan
Previous Macro Pitfalls Next

Macro arguments are completely macro-expanded before they are substituted into a macro body, unless they are stringified or pasted with other tokens. After substitution, the entire macro body, including the substituted arguments, is scanned again for macros to be expanded. The result is that the arguments are scanned twice to expand macro calls in them.

Most of the time, this has no effect. If the argument contained any macro calls, they are expanded during the first scan. The result therefore contains no macro calls, so the second scan does not change it. If the argument were substituted as given, with no prescan, the single remaining scan would find the same macro calls and produce the same results.

You might expect the double scan to change the results when a self-referential macro is used in an argument of another macro (see Self-Referential Macros): the self-referential macro would be expanded once in the first scan, and a second time in the second scan. However, this is not what happens. The self-references that do not expand in the first scan are marked so that they will not expand in the second scan either.

You might wonder, "Why mention the prescan, if it makes no difference? And why not skip it and make the preprocessor faster?" The answer is that the prescan does make a difference in three special cases:

  • Nested calls to a macro.

    We say that nested calls to a macro occur when a macro's argument contains a call to that very macro. For example, if f is a macro that expects one argument, f (f (1)) is a nested pair of calls to f. The desired expansion is made by expanding f (1) and substituting that into the definition of f. The prescan causes the expected result to happen. Without the prescan, f (1) itself would be substituted as an argument, and the inner use of f would appear during the main scan as an indirect self-reference and would not be expanded.

  • Macros that call other macros that stringify or concatenate.

    If an argument is stringified or concatenated, the prescan does not occur. If you want to expand a macro, then stringify or concatenate its expansion, you can do that by causing one macro to call another macro that does the stringification or concatenation. For instance, if you have
    #define AFTERX(x) X_ ## x
#define XAFTERX(x) AFTERX(x)
#define TABLESIZE 1024
#define BUFSIZE TABLESIZE
    then AFTERX(BUFSIZE) expands to X_BUFSIZE, and XAFTERX(BUFSIZE) expands to X_1024. (Not to X_TABLESIZE. Prescan always does a complete expansion.)

  • Macros used in arguments, whose expansions contain unshielded commas.

    This can cause a macro expanded on the second scan to be called with the wrong number of arguments. Here is an example:
    #define foo  a,b
#define bar(x) lose(x)
#define lose(x) (1 + (x))
    We would like bar(foo) to turn into (1 + (foo)), which would then turn into (1 + (a,b)). Instead, bar(foo) expands into lose(a,b), and you get an error because lose requires a single argument. In this case, the problem is easily solved by the same parentheses that ought to be used to prevent misnesting of arithmetic operations:
    #define foo (a,b)
or#define bar(x) lose((x))
    The extra pair of parentheses prevents the comma in foo's definition from being interpreted as an argument separator.


Newlines in Arguments
Previous Macro Pitfalls

The invocation of a function-like macro can extend over many logical lines. However, in the present implementation, the entire expansion comes out on one line. Thus line numbers emitted by the compiler or debugger refer to the line the invocation started on, which might be different to the line containing the argument causing the problem.

Here is an example illustrating this:

#define ignore_second_arg(a,b,c) a; c

ignore_second_arg (foo (),
                   ignored (),
                   syntax error);
The syntax error triggered by the tokens syntax error results in an error message citing line three - the line of ignore_second_arg - even though the problematic code comes from line five.

We consider this a bug, and intend to fix it in the near future.


Conditionals
Previous The GNU C Preprocessor Next

A conditional is a directive that instructs the preprocessor to select whether or not to include a chunk of code in the final token stream passed to the compiler. Preprocessor conditionals can test arithmetic expressions, or whether a name is defined as a macro, or both simultaneously using the special defined operator.

A conditional in the C preprocessor resembles in some ways an if statement in C, but it is important to understand the difference between them. The condition in an if statement is tested during the execution of your program. Its purpose is to allow your program to behave differently from run to run, depending on the data it is operating on. The condition in a preprocessing conditional directive is tested when your program is compiled. Its purpose is to allow different code to be included in the program depending on the situation at the time of compilation.

However, the distinction is becoming less clear. Modern compilers often do test if statements when a program is compiled, if their conditions are known not to vary at run time, and eliminate code which can never be executed. If you can count on your compiler to do this, you may find that your program is more readable if you use if statements with constant conditions (perhaps determined by macros). Of course, you can only use this to exclude code, not type definitions or other preprocessing directives, and you can only do it if the code remains syntactically valid when it is not to be used.

GCC version 3 eliminates this kind of never-executed code even when not optimizing. Older versions did it only when optimizing.

  • Conditional Uses
  • Conditional Syntax
  • Deleted Code


Conditional Uses
Conditionals Next

There are three general reasons to use a conditional.

  • A program may need to use different code depending on the machine or operating system it is to run on. In some cases the code for one operating system may be erroneous on another operating system; for example, it might refer to data types or constants that do not exist on the other system. When this happens, it is not enough to avoid executing the invalid code. Its mere presence will cause the compiler to reject the program. With a preprocessing conditional, the offending code can be effectively excised from the program when it is not valid.

  • You may want to be able to compile the same source file into two different programs. One version might make frequent time-consuming consistency checks on its intermediate data, or print the values of those data for debugging, and the other not.

  • A conditional whose condition is always false is one way to exclude code from the program but keep it as a sort of comment for future reference.
Simple programs that do not need system-specific logic or complex debugging hooks generally will not need to use preprocessing conditionals. In GCC4TI, conditionals are useful to select appropriate constants depending on which calculator and operating system the program is intended to run on, and to enable or disable certain features.


Conditional Syntax
Previous Conditionals Next

A conditional in the C preprocessor begins with a conditional directive: #if, #ifdef, or #ifndef.

  • #ifdef
  • #if
  • #else
  • #elif


#ifdef
Conditional Syntax Next

The simplest sort of conditional is

#ifdef MACRO

controlled text

#endif /* MACRO */
This block is called a conditional group. controlled text will be included in the output of the preprocessor if and only if MACRO is defined. We say that the conditional succeeds if MACRO is defined, fails if it is not.

The controlled text inside of a conditional can include preprocessing directives. They are executed only if the conditional succeeds. You can nest conditional groups inside other conditional groups, but they must be completely nested. In other words, #endif always matches the nearest #ifdef (or #ifndef, or #if). Also, you cannot start a conditional group in one file and end it in another.

Even if a conditional fails, the controlled text inside it is still run through initial transformations and tokenization. Therefore, it must all be lexically valid C. Normally the only way this matters is that all comments and string literals inside a failing conditional group must still be properly ended.

The comment following the #endif is not required, but it is a good practice if there is a lot of controlled text, because it helps people match the #endif to the corresponding #ifdef. Older programs sometimes put MACRO directly after the #endif without enclosing it in a comment. This is invalid code according to the C standard. CPP accepts it with a warning. It never affects which #ifndef the #endif matches.

Sometimes you wish to use some code if a macro is not defined. You can do this by writing #ifndef instead of #ifdef. One common use of #ifndef is to include code only the first time a header file is included. See Once-Only Headers.

Macro definitions can vary between compilations for several reasons. Here are some samples.
  • Some macros are predefined on each kind of machine (see System-specific Predefined Macros). This allows you to provide code specially tuned for a particular machine.

  • System header files define more macros, associated with the features they implement. You can test these macros with conditionals to avoid using a system feature on a machine where it is not implemented.

  • Macros can be defined or undefined with the '-D' and '-U' command line options when you compile the program. You can arrange to compile the same source file into two different programs by choosing a macro name to specify which program you want, writing conditionals to test whether or how this macro is defined, and then controlling the state of the macro with command line options, perhaps set in the Makefile. See Invocation.

  • Your program might have a special header file (often called config.h) that is adjusted when the program is compiled. It can define or not define macros depending on the features of the system and the desired capabilities of the program. The adjustment can be automated by a tool such as autoconf, or done by hand.


#if
Previous Conditional Syntax Next

The #if directive allows you to test the value of an arithmetic expression, rather than the mere existence of one macro. Its syntax is

#if expression

controlled text

#endif /* expression */
expression is a C expression of integer type, subject to stringent restrictions. It may contain
  • Integer constants.

  • Character constants, which are interpreted as they would be in normal code.

  • Arithmetic operators for addition, subtraction, multiplication, division, bitwise operations, shifts, comparisons, and logical operations (&& and ||). The latter two obey the usual short-circuiting rules of standard C.

  • Macros. All macros in the expression are expanded before actual computation of the expression's value begins.

  • Uses of the defined operator, which lets you check whether macros are defined in the middle of an #if.

  • Identifiers that are not macros, which are all considered to be the number zero. This allows you to write #if MACRO instead of #ifdef MACRO, if you know that MACRO, when defined, will always have a nonzero value. Function-like macros used without their function call parentheses are also treated as zero.

    In some contexts this shortcut is undesirable. The '-Wundef' option causes GCC to warn whenever it encounters an identifier which is not a macro in an #if.
The preprocessor does not know anything about types in the language. Therefore, sizeof operators are not recognized in #if, and neither are enum constants. They will be taken as identifiers which are not macros, and replaced by zero. In the case of sizeof, this is likely to cause the expression to be invalid.

The preprocessor calculates the value of expression. It carries out all calculations in the widest integer type known to the compiler; on most machines supported by GCC this is 64 bits. This is not the same rule as the compiler uses to calculate the value of a constant expression, and may give different results in some cases. If the value comes out to be nonzero, the #if succeeds and the controlled text is included; otherwise it is skipped.

If expression is not correctly formed, GCC issues an error and treats the conditional as having failed.
  • defined


defined
#if

The special operator defined is used in #if and #elif expressions to test whether a certain name is defined as a macro. defined name and defined (name) are both expressions whose value is 1 if name is defined as a macro at the current point in the program, and 0 otherwise. Thus, #if defined MACRO is precisely equivalent to #ifdef MACRO.

defined is useful when you wish to test more than one macro for existence at once. For example,

#if defined (__vax__) || defined (__ns16000__)
would succeed if either of the names __vax__ or __ns16000__ is defined as a macro.

Conditionals written like this:
#if defined BUFSIZE && BUFSIZE >= 1024
can generally be simplified to just #if BUFSIZE >= 1024, since if BUFSIZE is not defined, it will be interpreted as having the value zero.

If the defined operator appears as a result of a macro expansion, the C standard says the behavior is undefined. GNU cpp treats it as a genuine defined operator and evaluates it normally. It will warn wherever your code uses this feature if you use the command-line option '-pedantic', since other compilers may handle it differently.


#else
Previous Conditional Syntax Next

The #else directive can be added to a conditional to provide alternative text to be used if the condition fails. This is what it looks like:

#if expression
text-if-true
#else /* Not expression */
text-if-false
#endif /* Not expression */
If expression is nonzero, the text-if-true is included and the text-if-false is skipped. If expression is zero, the opposite happens.

You can use #else with #ifdef and #ifndef, too.


#elif
Previous Conditional Syntax

One common case of nested conditionals is used to check for more than two possible alternatives. For example, you might have

#if X == 1
...
#else /* X != 1 */
#if X == 2
...
#else /* X != 2 */
...
#endif /* X != 2 */
#endif /* X != 1 */
Another conditional directive, #elif, allows this to be abbreviated as follows:
#if X == 1
...
#elif X == 2
...
#else /* X != 2 and X != 1 */
...
#endif /* X != 2 and X != 1 */
#elif stands for "else if". Like #else, it goes in the middle of a conditional group and subdivides it; it does not require a matching #endif of its own. Like #if, the #elif directive includes an expression to be tested. The text following the #elif is processed only if the original #if-condition failed and the #elif condition succeeds.

More than one #elif can go in the same conditional group. Then the text after each #elif is processed only if the #elif condition succeeds after the original #if and all previous #elif directives within it have failed.

#else is allowed after any number of #elif directives, but #elif may not follow #else.


Deleted Code
Previous Conditionals

If you replace or delete a part of the program but want to keep the old code around for future reference, you often cannot simply comment it out. Block comments do not nest, so the first comment inside the old code will end the commenting-out. The probable result is a flood of syntax errors.

One way to avoid this problem is to use an always-false conditional instead. For instance, put #if 0 before the deleted code and #endif after it. This works even if the code being turned off contains conditionals, but they must be entire conditionals (balanced #if and #endif).

Some people use #ifdef notdef instead. This is risky, because notdef might be accidentally defined as a macro, and then the conditional would succeed. #if 0 can be counted on to fail.

Do not use #if 0 for comments which are not C code. Use a real comment, instead. The interior of #if 0 must consist of complete tokens; in particular, single-quote characters must balance. Comments often contain unbalanced single-quote characters (known in English as apostrophes). These confuse #if 0. They don't confuse /*.


Pragmas
Previous The GNU C Preprocessor Next

The #pragma directive is the method specified by the C standard for providing additional information to the compiler, beyond what is conveyed in the language itself. Three forms of this directive (commonly known as pragmas) are specified by the 1999 C standard. A C compiler is free to attach any meaning it likes to other pragmas.

GCC has historically preferred to use extensions to the syntax of the language, such as __attribute__, for this purpose. However, GCC does define a few pragmas of its own. These mostly have effects on the entire translation unit or source file.

In GCC version 3, all GNU-defined, supported pragmas have been given a GCC prefix. This is in line with the STDC prefix on all pragmas defined by C99. For backward compatibility, pragmas which were recognized by previous versions are still recognized without the GCC prefix, but that usage is deprecated. Some older pragmas are deprecated in their entirety. They are not recognized with the GCC prefix. See Obsolete Features.

C99 introduces the _Pragma operator. This feature addresses a major problem with #pragma: being a directive, it cannot be produced as the result of macro expansion. _Pragma is an operator, much like sizeof or defined, and can be embedded in a macro.

Its syntax is _Pragma (string-literal), where string-literal can be either a normal or wide-character string literal. It is destringized, by replacing all \\ with a single \ and all \" with a ". The result is then processed as if it had appeared as the right hand side of a #pragma directive. For example,

_Pragma ("GCC dependency \"parse.y\"")
has the same effect as #pragma GCC dependency "parse.y". The same effect could be achieved using macros, for example
#define DO_PRAGMA(x) _Pragma (#x)
DO_PRAGMA (GCC dependency "parse.y")
The standard is unclear on where a _Pragma operator can appear. The preprocessor does not accept it within a preprocessing conditional directive like #if. To be safe, you are probably best keeping it out of directives other than #define, and putting it on a line of its own.

This manual documents the pragmas which are meaningful to the preprocessor itself. Other pragmas are meaningful to the compiler. They are documented in the GCC manual.
#pragma GCC dependency
#pragma GCC dependency allows you to check the relative dates of the current file and another file. If the other file is more recent than the current file, a warning is issued. This is useful if the current file is derived from the other file, and should be regenerated. The other file is searched for using the normal include search path. Optional trailing text can be used to give more information in the warning message.
#pragma GCC dependency "parse.y"
#pragma GCC dependency "/usr/include/time.h" rerun fixincludes
#pragma GCC poison
Sometimes, there is an identifier that you want to remove completely from your program, and make sure that it never creeps back in. To enforce this, you can poison the identifier with this pragma. #pragma GCC poison is followed by a list of identifiers to poison. If any of those identifiers appears anywhere in the source after the directive, it is a hard error. For example,
#pragma GCC poison printf sprintf fprintf
sprintf(some_string, "hello");
will produce an error.

If a poisoned identifier appears as part of the expansion of a macro which was defined before the identifier was poisoned, it will not cause an error. This lets you poison an identifier without worrying about system headers defining macros that use it.

For example,
#define strrchr rindex
#pragma GCC poison rindex
strrchr(some_string, 'h');
will not produce an error.

#pragma GCC system_header
This pragma takes no arguments. It causes the rest of the code in the current file to be treated as if it came from a system header. See System Headers.


Other Directives
Previous The GNU C Preprocessor Next

The #ident directive takes one argument, a string constant. On some systems, that string constant is copied into a special segment of the object file. On other systems, the directive is ignored.

This directive is not part of the C standard, but it is not an official GNU extension either. We believe it came from System V.

The #sccs directive is recognized, because it appears in the header files of some systems. It is a very old, obscure, extension which we did not invent, and we have been unable to find any documentation of what it should do, so GCC simply ignores it.

The null directive consists of a # followed by a newline, with only whitespace (including comments) in between. A null directive is understood as a preprocessing directive but has no effect on the preprocessor output. The primary significance of the existence of the null directive is that an input line consisting of just a # will produce no output, rather than a line of output containing just a #. Supposedly some old C programs contain such lines.


User-defined Diagnostics
Previous The GNU C Preprocessor Next

The directive #error causes the preprocessor to report a fatal error. The tokens forming the rest of the line following #error are used as the error message.

You would use #error inside of a conditional that detects a combination of parameters which you know the program does not properly support. For example, if you know that the program will not run properly on a VAX, you might write

#ifdef __vax__
#error "Won't work on VAXen.  See comments at get_last_object."
#endif
If you have several configuration parameters that must be set up by the installation in a consistent way, you can use conditionals to detect an inconsistency and report it with #error. For example,
#if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO)
#error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP."
#endif
The directive #warning is like #error, but causes the preprocessor to issue a warning and continue preprocessing. The tokens following #warning are used as the warning message.

You might use #warning in obsolete header files, with a message directing the user to the header file which should be used instead.

Neither #error nor #warning macro-expands its argument. Internal whitespace sequences are each replaced with a single space. The line must consist of complete tokens. It is wisest to make the argument of these directives be a single string constant; this avoids problems with apostrophes and the like.


Line Control
Previous The GNU C Preprocessor Next

The C preprocessor informs the C compiler of the location in your source code where each token came from. Presently, this is just the file name and line number. All the tokens resulting from macro expansion are reported as having appeared on the line of the source file where the outermost macro was used. We intend to be more accurate in the future.

If you write a program which generates source code, such as the bison parser generator, you may want to adjust the preprocessor's notion of the current file name and line number by hand. Parts of the output from bison are generated from scratch, other parts come from a standard parser file. The rest are copied verbatim from bison's input. You would like compiler error messages and symbolic debuggers to be able to refer to bison's input file.

bison or any such program can arrange this by writing #line directives into the output file. #line is a directive that specifies the original line number and source file name for subsequent input in the current preprocessor input file. #line has three variants:

#line linenum
linenum is a non-negative decimal integer constant. It specifies the line number which should be reported for the following line of input. Subsequent lines are counted from linenum.

#line linenum filename
linenum is the same as for the first form, and has the same effect. In addition, filename is a string constant. The following line and all subsequent lines are reported to come from the file it specifies, until something else happens to change that. filename is interpreted according to the normal rules for a string constant: backslash escapes are interpreted. This is different from #include.

Previous versions of CPP did not interpret escapes in #line; we have changed it because the standard requires they be interpreted, and most other compilers do.

#line anything else
anything else is checked for macro calls, which are expanded. The result should match one of the above two forms.
#line directives alter the results of the __FILE__ and __LINE__ predefined macros from that point on. See Standard Predefined Macros. They do not have any effect on #include's idea of the directory containing the current file. This is a change from GCC 2.95. Previously, a file reading
#line 1 "../src/gram.y"
#include "gram.h"
would search for gram.h in ../src, then the '-I' chain; the directory containing the physical source file would not be searched. In GCC 3.0 and later, the #include is not affected by the presence of a #line referring to a different directory.

We made this change because the old behavior caused problems when generated source files were transported between machines. For instance, it is common practice to ship generated parsers with a source release, so that people building the distribution do not need to have yacc or Bison installed. These files frequently have #line directives referring to the directory tree of the system where the distribution was created. If GCC tries to search for headers in those directories, the build is likely to fail.

The new behavior can cause failures too, if the generated file is not in the same directory as its source and it attempts to include a header which would be visible searching from the directory containing the source file. However, this problem is easily solved with an additional '-I' switch on the command line. The failures caused by the old semantics could sometimes be corrected only by editing the generated files, which is difficult and error-prone.


Preprocessor Output
Previous The GNU C Preprocessor Next

When the C preprocessor is used with the C, C++, or Objective-C compilers, it is integrated into the compiler and communicates a stream of binary tokens directly to the compiler's parser. However, it can also be used in the more conventional standalone mode, where it produces textual output.

The output from the C preprocessor looks much like the input, except that all preprocessing directive lines have been replaced with blank lines and all comments with spaces. Long runs of blank lines are discarded.

The ISO standard specifies that it is implementation defined whether a preprocessor preserves whitespace between tokens, or replaces it with e.g. a single space. In GNU CPP, whitespace between tokens is collapsed to become a single space, with the exception that the first token on a non-directive line is preceded with sufficient spaces that it appears in the same column in the preprocessed output that it appeared in the original source file. This is so the output is easy to read. See Differences from previous versions. CPP does not insert any whitespace where there was none in the original source, except where necessary to prevent an accidental token paste.

Source file name and line number information is conveyed by lines of the form

# linenum filename flags
These are called linemarkers. They are inserted as needed into the output (but never within a string or character constant). They mean that the following line originated in file filename at line linenum. filename will never contain any non-printing characters; they are replaced with octal escape sequences.

After the file name comes zero or more flags, which are 1, 2, 3, or 4. If there are multiple flags, spaces separate them. Here is what the flags mean:
1
This indicates the start of a new file.

2
This indicates returning to a file (after having included another file).

3
This indicates that the following text comes from a system header file, so certain warnings should be suppressed.

4
This indicates that the following text should be treated as being wrapped in an implicit extern "C" block.
As an extension, the preprocessor accepts linemarkers in non-assembler input files. They are treated like the corresponding #line directive, (see Line Control), except that trailing flags are permitted, and are interpreted with the meanings described above. If multiple flags are given, they must be in ascending order.

Some directives may be duplicated in the output of the preprocessor. These are #ident (always), #pragma (only if the preprocessor does not handle the pragma itself), and #define and #undef (with certain debugging options). If this happens, the # of the directive will always be in the first column, and there will be no space between the # and the directive name. If macro expansion happens to generate tokens which might be mistaken for a duplicated directive, a space will be inserted between the # and the directive name.


C Preprocessor Command-Line Options
Previous The GNU C Preprocessor Next

Most often, when you use the C preprocessor, you will not have to invoke it explicitly: the C compiler will do so automatically. However, the preprocessor is sometimes useful on its own. All the options listed here are also acceptable to the C compiler and have the same meaning, except that the C compiler has different rules for specifying the output file.

Note: Whether you use the preprocessor by way of gcc or cpp, the compiler driver is run first. This program's purpose is to translate your command into invocations of the programs that do the actual work. Their command line interfaces are similar but not identical to the documented interface, and may change without notice.

The C preprocessor expects two file names as arguments, infile and outfile. The preprocessor reads infile together with any other files it specifies with #include. All the output generated by the combined input files is written in outfile.

Either infile or outfile may be '-', which as infile means to read from standard input and as outfile means to write to standard output. Also, if either file is omitted, it means the same as if '-' had been specified for that file.

Unless otherwise noted, or the option ends in =, all options which take an argument may have that argument appear either immediately after the option, or with a space between option and argument: '-Ifoo' and '-I foo' have the same effect.

Many options have multi-letter names; therefore multiple single-letter options may not be grouped: '-dM' is very different from '-d -M'.

For the actual command-line options, see GCC Options Controlling the Preprocessor.

  • Environment Variables Affecting CPP


Environment Variables Affecting CPP
C Preprocessor Command-Line Options

This section describes the environment variables that affect how CPP operates. You can use them to specify directories or prefixes to use when searching for include files, or to control dependency output.

Note that you can also specify places to search using options such as '-I', and control dependency output with options like '-M' (see Invocation). These take precedence over environment variables, which in turn take precedence over the configuration of GCC.

CPATH
C_INCLUDE_PATH
CPLUS_INCLUDE_PATH
OBJC_INCLUDE_PATH
Each variable's value is a list of directories separated by a special character, much like PATH, in which to look for header files. The special character, PATH_SEPARATOR, is target-dependent and determined at GCC build time. For Windows-based targets it is a semicolon, and for almost all other targets it is a colon.

CPATH specifies a list of directories to be searched as if specified with '-I', but after any paths given with '-I' options on the command line. This environment variable is used regardless of which language is being preprocessed.

The remaining environment variables apply only when preprocessing the particular language indicated. Each specifies a list of directories to be searched as if specified with '-isystem', but after any paths given with '-isystem' options on the command line.

In all these variables, an empty element instructs the compiler to search its current working directory. Empty elements can appear at the beginning or end of a path. For instance, if the value of CPATH is :/special/include, that has the same effect as -I. -I/special/include.

DEPENDENCIES_OUTPUT
If this variable is set, its value specifies how to output dependencies for Make based on the non-system header files processed by the compiler. System header files are ignored in the dependency output.

The value of DEPENDENCIES_OUTPUT can be just a file name, in which case the Make rules are written to that file, guessing the target name from the source file name. Or the value can have the form file target, in which case the rules are written to file file using target as the target name.

In other words, this environment variable is equivalent to combining the options '-MM' and '-MF' (see Invocation), with an optional '-MT' switch too.

SUNPRO_DEPENDENCIES
This variable is the same as DEPENDENCIES_OUTPUT (see above), except that system header files are not ignored, so it implies '-M' rather than '-MM'. However, the dependence on the main input file is omitted. See Invocation.


Traditional Mode
Previous The GNU C Preprocessor Next

Traditional (pre-standard) C preprocessing is rather different from the preprocessing specified by the standard. When GCC is given the '-traditional-cpp' option, it attempts to emulate a traditional preprocessor.

GCC versions 3.2 and later only support traditional mode semantics in the preprocessor, and not in the compiler front ends. This chapter outlines the traditional preprocessor semantics implemented by GNU. Note, however, that you cannot use traditional mode preprocessing if you include header files from the GCC4TI Library; this section is included only for reference, for people who want their programs to be compilable with traditional compilers.

The implementation does not correspond precisely to the behavior of earlier versions of GCC, nor to any true traditional preprocessor. After all, inconsistencies among traditional implementations were a major motivation for C standardization. However, we intend that it should be compatible with true traditional preprocessors in all ways that actually matter.

  • Traditional lexical analysis
  • Traditional macros
  • Traditional miscellany
  • Traditional warnings


Traditional lexical analysis
Traditional Mode Next

The traditional preprocessor does not decompose its input into tokens the same way a standards-conforming preprocessor does. The input is simply treated as a stream of text with minimal internal form.

This implementation does not treat trigraphs (see Initial Processing) specially since they were an invention of the standards committee. It handles arbitrarily-positioned escaped newlines properly and splices the lines as you would expect; many traditional preprocessors did not do this.

The form of horizontal whitespace in the input file is preserved in the output. In particular, hard tabs remain hard tabs. This can be useful if, for example, you are preprocessing a Makefile.

Traditional CPP only recognizes C-style block comments, and treats the /* sequence as introducing a comment only if it lies outside quoted text. Quoted text is introduced by the usual single and double quotes, and also by an initial < in a #include directive.

Traditionally, comments are completely removed and are not replaced with a space. Since a traditional compiler does its own tokenization of the output of the preprocessor, this means that comments can effectively be used as token paste operators. However, comments behave like separators for text handled by the preprocessor itself, since it doesn't re-lex its input. For example, in

#if foo/**/bar
foo and bar are distinct identifiers and expanded separately if they happen to be macros. In other words, this directive is equivalent to
#if foo bar
rather than
#if foobar
Generally speaking, in traditional mode an opening quote need not have a matching closing quote. In particular, a macro may be defined with replacement text that contains an unmatched quote. Of course, if you attempt to compile preprocessed output containing an unmatched quote you will get a syntax error.

However, all preprocessing directives other than #define require matching quotes. For example:
#define m This macro's fine and has an unmatched quote
"/* This is not a comment.  */
/* This is a comment.  The following #include directive
   is ill-formed.  */
#include <stdio.h
Just as for the ISO preprocessor, what would be a closing quote can be escaped with a backslash to prevent the quoted text from closing.


Traditional macros
Previous Traditional Mode Next

The major difference between traditional and ISO macros is that the former expand to text rather than to a token sequence. CPP removes all leading and trailing horizontal whitespace from a macro's replacement text before storing it, but preserves the form of internal whitespace.

One consequence is that it is legitimate for the replacement text to contain an unmatched quote (see Traditional lexical analysis). An unclosed string or character constant continues into the text following the macro call. Similarly, the text at the end of a macro's expansion can run together with the text after the macro invocation to produce a single token.

Normally comments are removed from the replacement text after the macro is expanded, but if the '-CC' option is passed on the command line comments are preserved. (In fact, the current implementation removes comments even before saving the macro replacement text, but it careful to do it in such a way that the observed effect is identical even in the function-like macro case.)

The ISO stringification operator # and token paste operator ## have no special meaning. As explained later, an effect similar to these operators can be obtained in a different way. Macro names that are embedded in quotes, either from the main file or after macro replacement, do not expand.

CPP replaces an unquoted object-like macro name with its replacement text, and then rescans it for further macros to replace. Unlike standard macro expansion, traditional macro expansion has no provision to prevent recursion. If an object-like macro appears unquoted in its replacement text, it will be replaced again during the rescan pass, and so on ad infinitum. GCC detects when it is expanding recursive macros, emits an error message, and continues after the offending macro invocation.

#define PLUS +
#define INC(x) PLUS+x
INC(foo);
     expands to ++foo;
Function-like macros are similar in form but quite different in behavior to their ISO counterparts. Their arguments are contained within parentheses, are comma-separated, and can cross physical lines. Commas within nested parentheses are not treated as argument separators. Similarly, a quote in an argument cannot be left unclosed; a following comma or parenthesis that comes before the closing quote is treated like any other character. There is no facility for handling variadic macros.

This implementation removes all comments from macro arguments, unless the '-C' option is given. The form of all other horizontal whitespace in arguments is preserved, including leading and trailing whitespace. In particular
f( )
is treated as an invocation of the macro f with a single argument consisting of a single space. If you want to invoke a function-like macro that takes no arguments, you must not leave any whitespace between the parentheses.

If a macro argument crosses a new line, the new line is replaced with a space when forming the argument. If the previous line contained an unterminated quote, the following line inherits the quoted state.

Traditional preprocessors replace parameters in the replacement text with their arguments regardless of whether the parameters are within quotes or not. This provides a way to stringize arguments. For example
#define str(x) "x"
str(/* A comment */some text )
     expands to "some text "
Note that the comment is removed, but that the trailing space is preserved. Here is an example of using a comment to effect token pasting.
#define suffix(x) foo_/**/x
suffix(bar)
     expands to foo_bar


Traditional miscellany
Previous Traditional Mode Next

Here are some things to be aware of when using the traditional preprocessor.

  • Preprocessing directives are recognized only when their leading # appears in the first column. There can be no whitespace between the beginning of the line and the #, but whitespace can follow the #.

  • A true traditional C preprocessor does not recognize #error or #pragma, and may not recognize #elif. CPP supports all the directives in traditional mode that it supports in ISO mode, including extensions, with the exception that the effects of #pragma GCC poison are undefined.

  • __STDC__ is not defined.

  • If you use digraphs the behavior is undefined.

  • If a line that looks like a directive appears within macro arguments, the behavior is undefined.


Traditional warnings
Previous Traditional Mode

You can request warnings about features that did not exist, or worked differently, in traditional C with the '-Wtraditional' option. GCC does not warn about features of ISO C which you must use when you are using a conforming compiler, such as the # and ## operators.

Presently '-Wtraditional' warns about:

  • Macro parameters that appear within string literals in the macro body. In traditional C macro replacement takes place within string literals, but does not in ISO C.

  • In traditional C, some preprocessor directives did not exist. Traditional preprocessors would only consider a line to be a directive if the # appeared in column 1 on the line. Therefore '-Wtraditional' warns about directives that traditional C understands but would ignore because the # does not appear as the first character on the line. It also suggests you hide directives like #pragma not understood by traditional C by indenting them. Some traditional implementations would not recognize #elif, so it suggests avoiding it altogether.

  • A function-like macro that appears without an argument list. In some traditional preprocessors this was an error. In ISO C it merely means that the macro is not expanded.

  • The unary plus operator. This did not exist in traditional C.

  • The U and LL integer constant suffixes, which were not available in traditional C. (Traditional C does support the L suffix for simple long integer constants.) You are not warned about uses of these suffixes in macros defined in system headers. For instance, UINT_MAX may well be defined as 4294967295U, but you will not be warned if you use UINT_MAX.

    You can usually avoid the warning, and the related warning about constants which are so large that they are unsigned, by writing the integer constant in question in hexadecimal, with no U suffix. Take care, though, because this gives the wrong result in exotic cases.


Implementation Details
Previous The GNU C Preprocessor Next

Here we document details of how the preprocessor's implementation affects its user-visible behavior. You should try to avoid undue reliance on behavior described here, as it is possible that it will change subtly in future implementations.

Also documented here are obsolete features and changes from previous versions of CPP.

  • Implementation-defined Behavior
  • Implementation Limits
  • Obsolete Features
  • Differences from Previous Versions


Implementation-defined Behavior
Implementation Details Next

This is how CPP behaves in all the cases which the C standard describes as implementation-defined. This term means that the implementation is free to do what it likes, but must document its choice and stick to it.

  • The mapping of physical source file multi-byte characters to the execution character set.

    Currently, GNU cpp only supports character sets that are strict supersets of ASCII, and performs no translation of characters.

  • Non-empty sequences of whitespace characters. In textual output, each whitespace sequence is collapsed to a single space. For aesthetic reasons, the first token on each non-directive line of output is preceded with sufficient spaces that it appears in the same column as it did in the original source file.

  • The numeric value of character constants in preprocessor expressions. The preprocessor and compiler interpret character constants in the same way; i.e. escape sequences such as \a are given the values they would have on the target machine.

    The compiler values a multi-character character constant a character at a time, shifting the previous value left by the number of bits per target character, and then or-ing in the bit-pattern of the new character truncated to the width of a target character. The final bit-pattern is given type int, and is therefore signed, regardless of whether single characters are signed or not (a slight change from versions 3.1 and earlier of GCC). If there are more characters in the constant than would fit in the target int the compiler issues a warning, and the excess leading characters are ignored.

    For example, 'ab' for a target with an 8-bit char would be interpreted as (int) ((unsigned char) 'a' * 256 + (unsigned char) 'b'), and '\234a' as (int) ((unsigned char) '\234' * 256 + (unsigned char) 'a').

  • Source file inclusion. For a discussion on how the preprocessor locates header files, see Include Operation.

  • Interpretation of the filename resulting from a macro-expanded #include directive.

    See Computed Includes.

  • Treatment of a #pragma directive that after macro-expansion results in a standard pragma.

    No macro expansion occurs on any #pragma directive line, so the question does not arise.

    Note that GCC does not yet implement any of the standard pragmas.


Implementation Limits
Previous Implementation Details Next

CPP has a small number of internal limits. This section lists the limits which the C standard requires to be no lower than some minimum, and all the others we are aware of. We intend there to be as few limits as possible. If you encounter an undocumented or inconvenient limit, please report that to us as a bug. (See the section on reporting bugs in the GCC manual.)

Where we say something is limited only by available memory, that means that internal data structures impose no intrinsic limit, and space is allocated with malloc or equivalent. The actual limit will therefore depend on many things, such as the size of other things allocated by the compiler at the same time, the amount of memory consumed by other processes on the same computer, etc.

  • Nesting levels of #include files. We impose an arbitrary limit of 200 levels, to avoid runaway recursion. The standard requires at least 15 levels.

  • Nesting levels of conditional inclusion. The C standard mandates this be at least 63. CPP is limited only by available memory.

  • Levels of parenthesized expressions within a full expression. The C standard requires this to be at least 63. In preprocessor conditional expressions, it is limited only by available memory.

  • Significant initial characters in an identifier or macro name. The preprocessor treats all characters as significant. The C standard requires only that the first 63 be significant.

  • Number of macros simultaneously defined in a single translation unit. The standard requires at least 4095 be possible. CPP is limited only by available memory.

  • Number of parameters in a macro definition and arguments in a macro call. We allow USHRT_MAX, which is no smaller than 65,535. The minimum required by the standard is 127.

  • Number of characters on a logical source line. The C standard requires a minimum of 4096 be permitted. CPP places no limits on this, but you may get incorrect column numbers reported in diagnostics for lines longer than 65,535 characters.

  • Maximum size of a source file. The standard does not specify any lower limit on the maximum size of a source file. GNU cpp maps files into memory, so it is limited by the available address space. This is generally at least two gigabytes. Depending on the operating system, the size of physical memory may or may not be a limitation.


Obsolete Features
Previous Implementation Details Next

CPP has a number of features which are present mainly for compatibility with older programs. We discourage their use in new code. In some cases, we plan to remove the feature in a future version of GCC.

  • Assertions
  • Obsolete Once-Only Headers
  • Miscellaneous Obsolete Features


Assertions
Obsolete Features Next

Assertions are a deprecated alternative to macros in writing conditionals to test what sort of computer or system the compiled program will run on. Assertions are usually predefined, but you can define them with preprocessing directives or command-line options.

Assertions were intended to provide a more systematic way to describe the compiler's target system. However, in practice they are just as unpredictable as the system-specific predefined macros. In addition, they are not part of any standard, and only a few compilers support them. Therefore, the use of assertions is less portable than the use of system-specific predefined macros. We recommend you do not use them at all.

An assertion looks like this:

#predicate (answer)
predicate must be a single identifier. answer can be any sequence of tokens; all characters are significant except for leading and trailing whitespace, and differences in internal whitespace sequences are ignored. (This is similar to the rules governing macro redefinition.) Thus, (x + y) is different from (x+y) but equivalent to ( x + y ). Parentheses do not nest inside an answer.

To test an assertion, you write it in an #if. For example, this conditional succeeds if either vax or ns16000 has been asserted as an answer for machine.
#if #machine (vax) || #machine (ns16000)
You can test whether any answer is asserted for a predicate by omitting the answer in the conditional:
#if #machine
Assertions are made with the #assert directive. Its sole argument is the assertion to make, without the leading # that identifies assertions in conditionals.
#assert predicate (answer)
You may make several assertions with the same predicate and different answers. Subsequent assertions do not override previous ones for the same predicate. All the answers for any given predicate are simultaneously true.

Assertions can be canceled with the #unassert directive. It has the same syntax as #assert. In that form it cancels only the answer which was specified on the #unassert line; other answers for that predicate remain true. You can cancel an entire predicate by leaving out the answer:
#unassert predicate
In either form, if no such assertion has been made, #unassert has no effect.

You can also make or cancel assertions using command line options. See Invocation.


Obsolete Once-Only Headers
Previous Obsolete Features Next

CPP supports two more ways of indicating that a header file should be read only once. Neither one is as portable as a wrapper #ifndef, and we recommend you do not use them in new programs.

In the Objective-C language, there is a variant of #include called #import which includes a file, but does so at most once. If you use #import instead of #include, then you don't need the conditionals inside the header file to prevent multiple inclusion of the contents. GCC permits the use of #import in C and C++ as well as Objective-C. However, it is not in standard C or C++ and should therefore not be used by portable programs.

#import is not a well designed feature. It requires the users of a header file to know that it should only be included once. It is much better for the header file's implementor to write the file so that users don't need to know this. Using a wrapper #ifndef accomplishes this goal.

In the present implementation, a single use of #import will prevent the file from ever being read again, by either #import or #include. You should not rely on this; do not use both #import and #include to refer to the same header file.

Another way to prevent a header file from being included more than once is with the #pragma once directive. If #pragma once is seen when scanning a header file, that file will never be read again, no matter what.

#pragma once does not have the problems that #import does, but it is not recognized by all preprocessors, so you cannot rely on it in a portable program.


Miscellaneous Obsolete Features
Previous Obsolete Features

Here are a few more obsolete features.

  • #pragma poison This is the same as #pragma GCC poison. The version without the GCC prefix is deprecated. See Pragmas.


Differences from Previous Versions
Previous Implementation Details

This section details behavior which has changed from previous versions of CPP. We do not plan to change it again in the near future, but we do not promise not to, either.

The "previous versions" discussed here are 2.95 and before. The behavior of GCC 3.0 is mostly the same as the behavior of the widely used 2.96 and 2.97 development snapshots. Where there are differences, they generally represent bugs in the snapshots.

  • Order of evaluation of # and ## operators: The standard does not specify the order of evaluation of a chain of ## operators, nor whether # is evaluated before, after, or at the same time as ##. You should therefore not write any code which depends on any specific ordering. It is possible to guarantee an ordering, if you need one, by suitable use of nested macros.

    An example of where this might matter is pasting the arguments 1, e and '-2'. This would be fine for left-to-right pasting, but right-to-left pasting would produce an invalid token e-2.

    GCC 3.0 evaluates # and ## at the same time and strictly left to right. Older versions evaluated all # operators first, then all ## operators, in an unreliable order.

  • The form of whitespace between tokens in preprocessor output: Preprocessor Output, for the current textual format. This is also the format used by stringification. Normally, the preprocessor communicates tokens directly to the compiler's parser, and whitespace does not come up at all.

    Older versions of GCC preserved all whitespace provided by the user and inserted lots more whitespace of their own, because they could not accurately predict when extra spaces were needed to prevent accidental token pasting.

  • Optional argument when invoking rest argument macros: As an extension, GCC permits you to omit the variable arguments entirely when you use a variable argument macro. This is forbidden by the 1999 C standard, and will provoke a pedantic warning with GCC 3.0. Previous versions accepted it silently.

  • ## swallowing preceding text in rest argument macros: Formerly, in a macro expansion, if ## appeared before a variable arguments parameter, and the set of tokens specified for that argument in the macro invocation was empty, previous versions of CPP would back up and remove the preceding sequence of non-whitespace characters (not the preceding token). This extension is in direct conflict with the 1999 C standard and has been drastically pared back.

    In the current version of the preprocessor, if ## appears between a comma and a variable arguments parameter, and the variable argument is omitted entirely, the comma will be removed from the expansion. If the variable argument is empty, or the token before ## is not a comma, then ## behaves as a normal token paste.

  • #line and #include: The #line directive used to change GCC's notion of the "directory containing the current file," used by #include with a double-quoted header file name. In 3.0 and later, it does not. See Line Control for further explanation.

  • Syntax of #line: In GCC 2.95 and previous, the string constant argument to #line was treated the same way as the argument to #include: backslash escapes were not honored, and the string ended at the second ". This is not compliant with the C standard. In GCC 3.0, an attempt was made to correct the behavior, so that the string was treated as a real string constant, but it turned out to be buggy. In 3.1, the bugs have been fixed. (We are not fixing the bugs in 3.0 because they affect relatively few people and the fix is quite invasive.)


History
Previous The GNU C Preprocessor

  • Original Version: The C Preprocessor

    Published by the Free Software Foundation
    59 Temple Place - Suite 330
    Boston, MA 02111-1307 USA

    Copyright © 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.

  • Modifications for TIGCC: The GNU C Preprocessor

    Published by the TIGCC Team

    Copyright © 2000, 2001, 2002 Zeljko Juric, Sebastian Reichelt, Kevin Kofler
  • Modifications for GCC4TI: The GNU C Preprocessor

    Published by the GCC4TI Project

    Copyright © 2009, 2010, 2011 Lionel Debroux


The GNU Assembler

This part of the documentation is a modified version of the GNU Assembler Manual. Therefore it is licensed under the GNU Free Documentation License.

The GNU assembler as is primarily intended to assemble the output of the GNU C compiler for use by the linker, so it may be regarded as an internal part of GCC4TI package. However, it may be called as a standalone program, and the GNU team tried to make as assemble everything correctly that other assemblers for the same machine would assemble. Any exceptions are documented explicitly. This doesn't mean as always uses the same syntax as other assemblers for the same architecture; for example, there exist several incompatible versions of the MC 68000 assembly language syntax, so the syntax used in the GNU assembler is not exactly the same as in some other assemblers (like the A68k Assembler, which is the most frequently used assembler for the TI-89 and TI-92+, and which is also included in the GCC4TI package as a standalone program).

This documentation will cover as features which are applicable to GCC4TI. The most frequent use of as is probably as an inline assembler, which allows mixing assembly statements with C code using the asm keyword.

This documentation is not intended as an introduction to programming in assembly language. In a similar vein, you will not find here details about machine architecture: here you can not expect detailed description of the instruction set, standard mnemonics, registers or addressing modes. You may want to consult the Motorola manufacturer's machine architecture manual for such information.

Note: It is possible to use source files for the GNU Assembler together with C source files in GCC4TI projects.

  • GNU Assembler Command Line
  • GNU Assembler Input and Output
  • GNU Assembler Syntax
  • Sections and Relocation
  • Assembler Symbols
  • Assembler Expressions
  • Assembler Directives
  • Acknowledgements
  • History
  • GNU General Public License
  • GNU Free Documentation License
  • Funding Free Software

Original author: Free Software Foundation, Inc.
Authors of the modifications: Zeljko Juric, Sebastian Reichelt, and Kevin Kofler
Published by the TIGCC Team, and now the GCC4TI project.
See the History section for details and copyright information.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".


GNU Assembler Command Line
The GNU Assembler Next

After the program name as, the command line may contain options and file names. Options may appear in any order, and may be before, after, or between file names. The order of file names is significant.

-- (two hyphens) by itself names the standard input file explicitly, as one of the files for as to assemble.

Except for -- any command line argument that begins with a hyphen (-) is an option. Each option changes the behavior of as. No option changes the way another option works. An option is a - followed by one or more letters; the case of the letter is important. All options are optional.

Some options expect exactly one file name to follow them. The file name may either immediately follow the option's letter (compatible with older assemblers) or it may be the next command argument (GNU standard). These two command lines are equivalent:

as -o my-object-file.o mumble.s
as -omy-object-file.o mumble.s
  • Invoking the GNU Assembler from GCC4TI
  • GNU Assembler Command-Line Options


Invoking the GNU Assembler from GCC4TI
GNU Assembler Command Line Next

If you are invoking as via tigcc, you can use the '-Wa' option to pass arguments through to the assembler. The assembler arguments must be separated from each other (and the '-Wa') by commas. For example:

tigcc -c -g -O -Wa,-alh,-L file.c
This passes two options to the assembler: '-alh' (emit a listing to standard output with high-level and assembly source) and '-L' (retain local symbols in the symbol table).

Usually you do not need to use this '-Wa' mechanism, since many compiler command-line options are automatically passed to the assembler by the compiler. (You can call the GNU compiler driver with the '-v' option to see precisely what options it passes to each compilation pass, including the assembler.)


GNU Assembler Command-Line Options
Previous GNU Assembler Command Line

Here is a brief summary of how to invoke as.

-a[cdhlmns]
Turn on listings, in any of a variety of ways:

-ac
omit false conditionals

-ad
omit debugging directives

-ah
include high-level source

-al
include assembly

-am
include macro expansions

-an
omit forms processing

-as
include symbols

=file
set the name of the listing file

You may combine these options; for example, use '-aln' for assembly listing without forms processing. The '=file' option, if used, must be the last one. By itself, '-a' defaults to '-ahls'.

For more information, see Enabling Listings.

--all-relocs
Output all references to non-absolute symbols in the assembled file as relocation items in the object file, even if the form of a reference would permit the assembler to resolve it. This especially affects pc-relative references to symbols defined in the same section, and certain calculations with symbols. For some calculations, this requires special GCC4TI-specific support for negative relocation items. If a calculation cannot be output without being resolved, an error message is generated. This option implies '--keep-locals'. The assembler also outputs a special symbol __ld_all_relocs to tell the linker that there are no implicit dependencies between different locations inside the sections.

-D
Ignored. This option is accepted for script compatibility with calls to other assemblers.

--defsym sym=value
Define the symbol sym to be value before assembling the input file. value must be an integer constant. As in C, a leading 0x indicates a hexadecimal value, and a leading 0 indicates an octal value.

-f
"fast" - skip whitespace and comment preprocessing (assume source is compiler output).

This option should only be used when assembling programs written by a (trusted) compiler. It stops the assembler from doing whitespace and comment preprocessing on the input file(s) before assembling them. See Preprocessing.

Warning: if you use '-f' when the files actually need to be preprocessed (if they contain comments, for example), as does not work correctly.

--gdwarf2
Generate DWARF 2 debugging information for each assembler line. This may help debugging assembler code, if the debugger can handle it.

--gstabs
Generate stabs debugging information for each assembler line. This may help debugging assembler code, if the debugger can handle it.

--help
Print a summary of the command line options and exit.

--target-help
Print a summary of all target specific options and exit.

-I dir
Add directory dir to the search list for .include directives.

-J
Don't warn about signed overflow.

-K
This option is accepted but has no effect on the 680x0 family.

-L
--keep-locals
Keep (in the symbol table) local symbols. On traditional a.out systems these start with L, but different systems have different local label prefixes. See Including Local Labels.

--listing-lhs-width=number
Set the maximum width, in words, of the output data column for an assembler listing to number.

For more information, see Configuring Listing Output.

--listing-lhs-width2=number
Set the maximum width, in words, of the output data column for continuation lines in an assembler listing to number.

--listing-rhs-width=number
Set the maximum width of an input source line, as displayed in a listing, to number bytes.

--listing-cont-lines=number
Set the maximum number of lines printed in a listing for a single line of input to number+1.

-M
--mri
Use MRI compatibility mode. See Assembling in MRI Compatibility Mode.

--MD depfile
Generate a dependency file. This file consists of a single rule suitable for make describing the dependencies of the main source file. The rule is written to the file named in its argument. This feature is used in the automatic updating of makefiles. It is not particulary useful for GCC4TI.

-o objfile
Name the object-file output from as objfile. See Naming the Output File.

-R
Fold the data section into the text section. See Joining the Data and Text Sections.

--statistics
Print the maximum space (in bytes) and total time (in seconds) used by assembly.

--strip-local-absolute
Remove local absolute symbols from the outgoing symbol table.

--traditional-format
Use a more traditional output format. See Traditional Assembler Output Format.

-v
-version
Print the as version.

--version
Print the as version and exit.

-W
--no-warn
Suppress warning messages.

See Controlling Warnings for more information about warning switches.

--fatal-warnings
Treat warnings as errors.

--warn
Don't suppress warning messages or treat them as errors.

-w
Ignored.

-x
Ignored.

-Z
Generate an object file even after errors.

-- | files
Standard input, or source files to assemble.
  • M680x0 Options
  • Enabling Listings
  • Naming the Object File
  • Controlling Warnings
  • Joining the Data and Text Sections
  • Including Local Labels
  • Traditional Assembler Output Format
  • Assembling in MRI Compatibility Mode


M680x0 Options
GNU Assembler Command-Line Options Next

The Motorola 680x0 version of as has a few machine dependent options:

-l
You can use the '-l' option to shorten the size of references to undefined symbols. If you do not use the '-l' option, references to undefined symbols are wide enough for a full long (32 bits). (Since as cannot know where these symbols end up, as can only allocate space for the linker to fill in later. Since as does not know how far away these symbols are, it allocates as much space as it can.) If you use this option, the references are only one word wide (16 bits). This may be useful if you want the object file to be as small as possible, and you know that the relevant symbols are always less 32 KB away. This option implies '--short-jumps'.

--short-jumps
The '--short-jumps' option shortens the size of branches to undefined symbols. Unlike '-l', other references to undefined symbols are kept wide enough for a full long (32 bits), unless an explicit size is specified. This enables you to optimize a modular program that is smaller than 32 KB as well as possible, while still being able to reference an external BSS or data section (since no jumps can point into these sections). Previously (and in non-TIGCC assemblers), the '-l' option acted like this, but the documentation did not say this.

--register-prefix-optional
Since the compiler as configured for GCC4TI does not prepend an underscore to the names of user variables, the assembler requires a % before any use of a register name. This is intended to let the assembler distinguish between C variables and functions named a0 through a7, and so on. The '--register-prefix-optional' option may be used to permit omitting the % even in GCC4TI. If this is done, it will generally be impossible to refer to C variables and functions with the same names as register names.

--bitwise-or
Normally the character | is treated as a comment character, which means that it can not be used in expressions. The '--bitwise-or' option turns | into a normal character. In this mode, you must either use C style comments, or start comments with a # character at the beginning of a line.

--base-size-default-16
--base-size-default-32
If you use an addressing mode with a base register without specifying the size, as will normally use the full 32 bit value. For example, the addressing mode %a0@(%d0) is equivalent to %a0@(%d0:l). You may use the '--base-size-default-16' option to tell as to default to using the 16 bit value. In this case, %a0@(%d0) is equivalent to %a0@(%d0:w). You may use the '--base-size-default-32' option to restore the default behaviour.

--disp-size-default-16
--disp-size-default-32
If you use an addressing mode with a displacement, and the value of the displacement is not known, as will normally assume that the value is 32 bits. For example, if the symbol disp has not been defined, as will assemble the addressing mode %a0@(disp,%d0) as though disp is a 32 bit value. You may use the '--disp-size-default-16' option to tell as to instead assume that the displacement is 16 bits. In this case, as will assemble %a0@(disp,%d0) as though disp is a 16 bit value. You may use the '--disp-size-default-32' option to restore the default behaviour.

--pcrel
Always keep branches PC-relative. In the M680x0 architecture all branches are defined as PC-relative. However, on some processors (including the M68000 used in calculators) they are limited to word displacements maximum. When as needs a long branch that is not available, it normally emits an absolute jump instead. This option disables this substitution. When this option is given and no long branches are available, only word branches will be emitted. An error message will be generated if a word branch cannot reach its target. See Branch Improvement.

-m680x0
as can assemble code for several different members of the Motorola 680x0 family. The default in GCC4TI is to assemble code for the 68000 microprocessor. The following options may be used to change the default. These options control which instructions and addressing modes are permitted. The members of the 680x0 family are very similar. For detailed information about the differences, see the Motorola manuals. (These options are not very useful for GCC4TI.)

-m68000
-m68ec000
-m68hc000
-m68hc001
-m68008
-m68302
-m68306
-m68307
-m68322
-m68356
Assemble for the 68000. '-m68008', '-m68302', and so on are synonyms for '-m68000', since the chips are the same from the point of view of the assembler.

-m68010
Assemble for the 68010.

-m68020
-m68ec020
Assemble for the 68020.

-m68030
-m68ec030
Assemble for the 68030.

-m68040
-m68ec040
Assemble for the 68040.

-m68060
-m68ec060
Assemble for the 68060.

-mcpu32
-m68330
-m68331
-m68332
-m68333
-m68334
-m68336
-m68340
-m68341
-m68349
-m68360
Assemble for the CPU32 family of chips.

-m5200
Assemble for the ColdFire family of chips.

-m68881
-m68882
Assemble 68881 floating point instructions. This is the default for the 68020, 68030, and the CPU32. The 68040 and 68060 always support floating point instructions.

-mno-68881
Do not assemble 68881 floating point instructions. This is the default for 68000 and the 68010. The 68040 and 68060 always support floating point instructions, even if this option is used.

-m68851
Assemble 68851 MMU instructions. This is the default for the 68020, 68030, and 68060. The 68040 accepts a somewhat different set of MMU instructions; '-m68851' and '-m68040' should not be used together.

-mno-68851
Do not assemble 68851 MMU instructions. This is the default for the 68000, 68010, and the CPU32. The 68040 accepts a somewhat different set of MMU instructions.


Enabling Listings
Previous GNU Assembler Command-Line Options Next

The options starting with '-a' enable listing output from the assembler. By itself, '-a' requests high-level, assembly, and symbols listing. You can use other letters to select specific options for the list: '-ah' requests a high-level language listing, '-al' requests an output-program assembly listing, and '-as' requests a symbol table listing. High-level listings require that a compiler debugging option like '-g' be used, and that assembly listings ('-al') be requested also.

Use the '-ac' option to omit false conditionals from a listing. Any lines which are not assembled because of a false .if (or .ifdef, or any other conditional), or a true .if followed by an .else, will be omitted from the listing.

Use the '-ad' option to omit debugging directives from the listing.

Once you have specified one of these options, you can further control listing output and its appearance using the directives .list, .nolist, .psize, .eject, .title, and .sbttl. The '-an' option turns off all forms processing. If you do not request listing output with one of the '-a' options, the listing-control directives have no effect.

The letters after '-a' may be combined into one option, e.g., '-aln'.

Note if the assembler source is coming from the standard input (e.g. because it is being created by gcc and the '-pipe' command line switch is being used) then the listing will not contain any comments or preprocessor directives. This is because the listing code buffers input source lines from stdin only after they have been preprocessed by the assembler. This reduces memory usage and makes the code more efficient.

  • Configuring Listing Output


Configuring Listing Output
Enabling Listings

The listing feature of the assembler can be enabled via the command line switch '-a' (see Enabling Listings). This feature combines the input source file(s) with a hex dump of the corresponding locations in the output object file, and displays them as a listing file. The format of this listing can be controlled by pseudo ops inside the assembler source (see Enabling Listings for details) and also by the following switches:

--listing-lhs-width=number
Sets the maximum width, in words, of the first line of the hex byte dump. This dump appears on the left hand side of the listing output.

--listing-lhs-width2=number
Sets the maximum width, in words, of any further lines of the hex byte dump for a given input source line. If this value is not specified, it defaults to being the same as the value specified for '--listing-lhs-width'. If neither switch is used the default is to one.

--listing-rhs-width=number
Sets the maximum width, in characters, of the source line that is displayed alongside the hex dump. The default value for this parameter is 100. The source line is displayed on the right hand side of the listing output.

--listing-cont-lines=number
Sets the maximum number of continuation lines of hex dump that will be displayed for a given single line of source input. The default value is 4.


Naming the Object File
Previous GNU Assembler Command-Line Options Next

There is always one object file output when you run as. By default it has the name a.out. You can use the '-o' option (which takes exactly one filename) to give the object file a different name.

Whatever the object file is called, as overwrites any existing file of the same name.


Controlling Warnings
Previous GNU Assembler Command-Line Options Next

as should never give a warning or error message when assembling compiler output. But programs written by people often cause as to give a warning that a particular assumption was made. All such warnings are directed to the standard error file.

If you use the '-W' and '--no-warn' options, no warnings are issued. This only affects the warning messages: it does not change any particular of how as assembles your file. Errors, which stop the assembly, are still reported.

If you use the '--fatal-warnings' option, as considers files that generate warnings to be in error.

You can switch these options off again by specifying '--warn', which causes warnings to be output as usual.


Joining the Data and Text Sections
Previous GNU Assembler Command-Line Options Next

The '-R' option tells as to write the object file as if all data-section data lives in the text section. This is only done at the very last moment: your binary data are the same, but data section parts are relocated differently. The data section part of your object file is zero bytes long because all its bytes are appended to the text section. (see Sections and Relocation).

When you specify '-R', it would be possible to generate shorter address displacements (because we do not have to cross between text and data section). We refrain from doing this simply for compatibility with older versions of as. In the future, '-R' may work this way.

When as is configured for COFF output (which is the case in GCC4TI), this option is only useful if you use sections named .text and .data.


Including Local Labels
Previous GNU Assembler Command-Line Options Next

Labels beginning with L (upper case only) are called local labels. See Symbol Names. Normally you do not see such labels when debugging, because they are intended for the use of programs (like compilers) that compose assembler programs, not for your notice. Normally both as and ld discard such labels, so you do not normally debug with them.

The '-L' option tells as to retain those L... symbols in the object file. Usually, if you do this, you also tell the linker ld to preserve symbols whose names begin with L.

By default, a local label is any label beginning with L, but each target is allowed to redefine the local label prefix.


Traditional Assembler Output Format
Previous GNU Assembler Command-Line Options Next

For some targets, the output of as is different in some ways from the output of some existing assembler. The '--traditional-format' switch requests as to use the traditional format instead.

For example, it disables the exception frame optimizations which as normally does by default on gcc output.


Assembling in MRI Compatibility Mode
Previous GNU Assembler Command-Line Options

The '-M' or '--mri' option selects MRI compatibility mode. This changes the syntax and pseudo-op handling of as to make it compatible with the ASM68K assembler from Microtec Research. The exact nature of the MRI syntax will not be documented here; see the MRI manuals for more information. Note in particular that the handling of macros and macro arguments is somewhat different. The purpose of this option is to permit assembling existing MRI assembler code using as.

The MRI compatibility is not complete. Certain operations of the MRI assembler depend upon its object file format, and can not be supported using other object file formats. Supporting these would require enhancing each object file format individually. These are:

  • global symbols in common section The m68k MRI assembler supports common sections which are merged by the linker. Other object file formats do not support this. as handles common sections by treating them as a single common symbol. It permits local symbols to be defined within a common section, but it can not support global symbols, since it has no way to describe them.

  • complex relocations The MRI assemblers support relocations against a negated section address, and relocations which combine the start addresses of two or more sections. These are not support by other object file formats.

  • END pseudo-op specifying start address The MRI END pseudo-op permits the specification of a start address. This is not supported by other object file formats. The start address may instead be specified using the '-e' option to the linker, or in a linker script.

  • IDNT, .ident and NAME pseudo-ops The MRI IDNT, .ident and NAME pseudo-ops assign a module name to the output file. This is not supported by other object file formats.

  • ORG pseudo-op The m68k MRI ORG pseudo-op begins an absolute section at a given address. This differs from the usual as .org pseudo-op, which changes the location within the current section. Absolute sections are not supported by other object file formats. The address of a section may be assigned within a linker script.
There are some other features of the MRI assembler which are not supported by as, typically either because they are difficult or because they seem of little consequence. Some of these may be supported in future releases.
  • EBCDIC strings EBCDIC strings are not supported.

  • packed binary coded decimal Packed binary coded decimal is not supported. This means that the DC.P and DCB.P pseudo-ops are not supported.

  • FEQU pseudo-op The m68k FEQU pseudo-op is not supported.

  • NOOBJ pseudo-op The m68k NOOBJ pseudo-op is not supported.

  • OPT branch control options The m68k OPT branch control options - B, BRS, BRB, BRL, and BRW - are ignored. as automatically relaxes all branches, whether forward or backward, to an appropriate size, so these options serve no purpose.

  • OPT list control options The following m68k OPT list control options are ignored: C, CEX, CL, CRE, E, G, I, M, MEX, MC, MD, X.

  • other OPT options The following m68k OPT options are ignored: NEST, O, OLD, OP, P, PCO, PCR, PCS, R.

  • OPT D option is default The m68k OPT D option is the default, unlike the MRI assembler. OPT NOD may be used to turn it off.

  • XREF pseudo-op. The m68k XREF pseudo-op is ignored.

  • .debug pseudo-op The i960 .debug pseudo-op is not supported.

  • .extended pseudo-op The i960 .extended pseudo-op is not supported.

  • .list pseudo-op. The various options of the i960 .list pseudo-op are not supported.

  • .optimize pseudo-op The i960 .optimize pseudo-op is not supported.

  • .output pseudo-op The i960 .output pseudo-op is not supported.

  • .setreal pseudo-op The i960 .setreal pseudo-op is not supported.


GNU Assembler Input and Output
Previous The GNU Assembler Next
  • Input Files
  • Output (Object) File
  • Assembler Error and Warning Messages


Input Files
GNU Assembler Input and Output Next

We use the phrase source program, abbreviated source, to describe the program input to one run of as. The program may be in one or more files; how the source is partitioned into files doesn't change the meaning of the source.

The source program is a concatenation of the text in all the files, in the order specified.

Each time you run as it assembles exactly one source program. The source program is made up of one or more files. (The standard input is also a file.)

You give as a command line that has zero or more input file names. The input files are read (from left file name to right). A command line argument (in any position) that has no special meaning is taken to be an input file name.

If you give as no file names it attempts to read one input file from the as standard input, which is normally your terminal. You may have to type Ctrl-D to tell as there is no more program to assemble.

Use -- if you need to explicitly name the standard input file in your command line.

If the source is empty, as produces a small, empty object file.

  • Assembler File Names and Line Numbers


Assembler File Names and Line Numbers
Input Files

There are two ways of locating a line in the input file (or files) and either may be used in reporting error messages. One way refers to a line number in a physical file; the other refers to a line number in a "logical" file. See Error and Warning Messages.

Physical files are those files named in the command line given to as.

Logical files are simply names declared explicitly by assembler directives; they bear no relation to physical files. Logical file names help error messages reflect the original source file, when as source is itself synthesized from other files. as understands the # directives emitted by the gcc preprocessor. See also .file.


Output (Object) File
Previous GNU Assembler Input and Output Next

Every time you run as, it produces an output file, which is your assembly language program translated into numbers. This file is the object file. Its default name is a.out. You can give it another name by using the '-o' option. Conventionally, object file names end with .o. The default name is used for historical reasons: older assemblers were capable of assembling self-contained programs directly into a runnable program. (For some formats, this isn't currently possible, but it can be done for the a.out format.)

The object file is meant for input to the linker ld. It contains assembled program code, information to help ld integrate the assembled program into a runnable file, and (optionally) symbolic information for the debugger.


Assembler Error and Warning Messages
Previous GNU Assembler Input and Output

as may write warnings and error messages to the standard error file (usually your terminal). This should not happen when a compiler runs as automatically. Warnings report an assumption made so that as could keep assembling a flawed program; errors report a grave problem that stops the assembly.

Warning messages have the format

file_name:NNN:Warning Message Text
(where NNN is a line number). If a logical file name has been given (see .file) it is used for the filename, otherwise the name of the current input file is used. If a logical line number was given (see .line) then it is used to calculate the number printed, otherwise the actual line in the current source file is printed. The message text is intended to be self explanatory (in the grand Unix tradition).

Error messages have the format
file_name:NNN:FATAL:Error Message Text
The file name and line number are derived as for warning messages. The actual message text may be rather less explanatory because many of them aren't supposed to happen.


GNU Assembler Syntax
Previous The GNU Assembler Next

The machine-independent syntax used by the GNU assembler is similar to what many other assemblers use; it is inspired by the BSD 4.2 assembler. Motorola-specific features are explained at the end of this chapter.

  • Preprocessing
  • Whitespace
  • Comments
  • Symbols
  • Statements
  • Constants
  • Motorola 680x0 Dependent Features


Preprocessing
GNU Assembler Syntax Next

The as internal preprocessor:

  • adjusts and removes extra whitespace. It leaves one space or tab before the keywords on a line, and turns any other whitespace on the line into a single space.

  • removes all comments, replacing them with a single space, or an appropriate number of newlines.

  • converts character constants into the appropriate numeric values.
It does not do macro processing, include file handling, or anything else you may get from your C compiler's preprocessor. You can do include file processing with the .include directive (see .include). You can use the GNU C compiler driver to get other "CPP" style preprocessing by giving the input file a .S suffix. See Options Controlling the Kind of Output, gcc.info, Using GNU CC.

Excess whitespace, comments, and character constants cannot be used in the portions of the input text that are not preprocessed.

If the first line of an input file is #NO_APP or if you use the '-f' option, whitespace and comments are not removed from the input file. Within an input file, you can ask for whitespace and comment removal in specific portions of the by putting a line that says #APP before the text that may contain whitespace or comments, and putting a line that says #NO_APP after this text. This feature is mainly intend to support asm statements in compilers whose output is otherwise free of comments and whitespace.


Whitespace
Previous GNU Assembler Syntax Next

Whitespace is one or more blanks or tabs, in any order. Whitespace is used to separate symbols, and to make programs neater for people to read. Unless within character constants (see Character Constants), any whitespace means the same as exactly one space.


Comments
Previous GNU Assembler Syntax Next

There are two ways of rendering comments to as. In both cases the comment is equivalent to one space.

Anything from /* through the next */ is a comment. This means you may not nest these comments.

/*
  The only way to include a newline ('\n') in a comment
  is to use this sort of comment.
*/

/* This sort of comment does not nest. */
Anything from the line comment character to the next newline is considered a comment and is ignored. The line comment character is | on the 680x0 family of processors.

To be compatible with past assemblers, lines that begin with # have a special interpretation. Following the # should be an absolute expression (see Expressions): the logical line number of the next line. Then a string (see Strings) is allowed: if present it is a new logical file name. The rest of the line, if any, should be whitespace.

If the first non-whitespace characters on the line are not numeric, the line is ignored. (Just like a comment.)
                          # This is an ordinary comment.
# 42-6 "new_file_name"    # New logical file name
                          # This is logical line # 36.
This feature is deprecated, and may disappear from future versions of as.


Symbols
Previous GNU Assembler Syntax Next

A symbol is one or more characters chosen from the set of all letters (both upper and lower case), digits and the three characters _.$. No symbol may begin with a digit. Case is significant. There is no length limit: all characters are significant. Symbols are delimited by characters not in that set, or by the beginning of a file (since the source program must end with a newline, the end of a file is not a possible symbol delimiter). See Symbols.


Statements
Previous GNU Assembler Syntax Next

A statement ends at a newline character (\n) or at a semicolon (;). The newline or semicolon is considered part of the preceding statement. Newlines and semicolons within character constants are an exception: they do not end statements.

It is an error to end any statement with end-of-file: the last character of any input file should be a newline. An empty statement is allowed, and may include whitespace. It is ignored.

A statement begins with zero or more labels, optionally followed by a key symbol which determines what kind of statement it is. The key symbol determines the syntax of the rest of the statement. If the symbol begins with a dot . then the statement is an assembler directive: typically valid for any computer. If the symbol begins with a letter the statement is an assembly language instruction: it assembles into a machine language instruction. A label is a symbol immediately followed by a colon (:). Whitespace before a label or after a colon is permitted, but you may not have whitespace between a label's symbol and its colon. See Labels.

label:     .directive    followed by something
another_label:           # This is an empty statement.
           instruction   operand_1, operand_2, ...


Constants
Previous GNU Assembler Syntax Next

A constant is a number, written so that its value is known by inspection, without knowing any context. Like this:

.byte  74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
.ascii "Ring the bell\7"                  # A string constant.
.octa  0x123456789abcdef0123456789ABCDEF0 # A bignum.
.float 0f-314159265358979323846264338327\
95028841971.693993751E-40                 # - pi, a flonum.
  • Character Constants
  • Number Constants


Character Constants
Constants Next

There are two kinds of character constants. A character stands for one character in one byte and its value may be used in numeric expressions. String constants (properly called string literals) are potentially many bytes and their values may not be used in arithmetic expressions.

  • Strings
  • Characters


Strings
Character Constants Next

A string is written between double-quotes. It may contain double-quotes or null characters. The way to get special characters into a string is to escape these characters: precede them with a backslash \ character. For example \\ represents one backslash: the first \ is an escape which tells as to interpret the second character literally as a backslash (which prevents as from recognizing the second \ as an escape character). The complete list of escapes follows.

\b
Mnemonic for backspace; for ASCII this is octal code 010.

\f
Mnemonic for FormFeed; for ASCII this is octal code 014.

\n
Mnemonic for newline; for ASCII this is octal code 012.

\r
Mnemonic for carriage-Return; for ASCII this is octal code 015.

\t
Mnemonic for horizontal Tab; for ASCII this is octal code 011.

\ digit digit digit
An octal character code. The numeric code is 3 octal digits. For compatibility with other Unix systems, 8 and 9 are accepted as digits: for example, \008 has the value 010, and \009 the value 011.

\x hex-digits...
A hex character code. All trailing hex digits are combined. Either upper or lower case x works.

\\
Represents one \ character.

\"
Represents one " character. Needed in strings to represent this character, because an unescaped " would end the string.

\ anything-else
Any other character when escaped by \ gives a warning, but assembles as if the \ was not present. The idea is that if you used an escape sequence you clearly didn't want the literal interpretation of the following character. However as has no other interpretation, so as knows it is giving you the wrong code and warns you of the fact.
Which characters are escapable, and what those escapes represent, varies widely among assemblers. The current set is what we think the BSD 4.2 assembler recognizes, and is a subset of what most C compilers recognize. If you are in doubt, do not use an escape sequence.


Characters
Previous Character Constants

A single character may be written as a single quote immediately followed by that character. The same escapes apply to characters as to strings. So if you want to write the character backslash, you must write '\\ where the first \ escapes the second \. As you can see, the quote is an acute accent, not a grave accent. A newline (or semicolon ;) immediately following an acute accent is taken as a literal character and does not count as the end of a statement. The value of a character constant in a numeric expression is the machine's byte-wide code for that character. as assumes your character code is ASCII: 'A means 65, 'B means 66, and so on.


Number Constants
Previous Constants

as distinguishes three kinds of numbers according to how they are stored in the target machine. Integers are numbers that would fit into an int in the C language. Bignums are integers, but they are stored in more than 32 bits. Flonums are floating point numbers, described below.

  • Integers
  • Bignums
  • Flonums


Integers
Number Constants Next

A binary integer is 0b or 0B followed by zero or more of the binary digits 01.

An octal integer is 0 followed by zero or more of the octal digits (01234567).

A decimal integer starts with a non-zero digit followed by zero or more digits (0123456789).

A hexadecimal integer is 0x or 0X followed by one or more hexadecimal digits chosen from 0123456789abcdefABCDEF.

Integers have the usual values. To denote a negative integer, use the prefix operator - discussed under expressions (see Prefix Operators).


Bignums
Previous Number Constants Next

A bignum has the same syntax and semantics as an integer except that the number (or its negative) takes more than 32 bits to represent in binary. The distinction is made because in some places integers are permitted while bignums are not.


Flonums
Previous Number Constants

A flonum represents a floating point number. The translation is indirect: a decimal floating point number from the text is converted by as to a generic binary floating point number of more than sufficient precision. This generic floating point number is converted to a particular computer's floating point format (or formats) by a portion of as specialized to that computer. The version of as used by GCC4TI does not use TI's SMAP II BCD format; it emits standard IEEE floating point numbers. It would be pointless to implement the correct behavior, since the appropriate numbers are easy to write, and converting between base 2 and 10 can decrease precision.

A flonum is written by writing (in order)

  • The digit 0.

  • A letter, to tell as the rest of the number is a flonum.

  • An optional sign: either + or -.

  • An optional integer part: zero or more decimal digits.

  • An optional fractional part: . followed by zero or more decimal digits.

  • An optional exponent, consisting of:
    • An E or e.

    • Optional sign: either + or -.

    • One or more decimal digits.
At least one of the integer part or the fractional part must be present. The floating point number has the usual base-10 value.

as does all processing using integers. Flonums are computed independently of any floating point hardware in the computer running as.


Motorola 680x0 Dependent Features
Previous GNU Assembler Syntax

In this configuration of as (which does not prepend an underscore to the names of user variables), the assembler requires a '%' before any use of a register name. This is intended to let the assembler distinguish between C variables and functions named 'a0' through 'a7', and so on.

Two different syntaxes for the Motorola 680x0 are widely used. The first one was developed at MIT. The second one is the standard Motorola syntax for this chip, and it differs from the MIT syntax. as can accept Motorola syntax for operands, even if MIT syntax is used for other operands in the same instruction. The two kinds of syntax are fully compatible.

  • MIT Syntax
  • Motorola Syntax
  • Branch Improvement
  • Special Characters


MIT Syntax
Motorola 680x0 Dependent Features Next

The MIT syntax uses instructions names and syntax compatible with the Sun assembler. Intervening periods are ignored; for example, movl is equivalent to mov.l.

In the following table, apc stands for any of the address registers (%a0 through %a7), the program counter (%pc), the zero-address relative to the program counter (%zpc), a suppressed address register (%za0 through %za7), or it may be omitted entirely. The use of size means one of w or l, and it may be omitted, along with the leading colon, unless a scale is also specified. The use of scale means one of 1, 2, 4, or 8, and it may always be omitted along with the leading colon.

The following addressing modes are understood (note that some of them are valid only on 68020 or later processors, not on the ordinary 68000 used in TI calculators):

Immediate
#number

Data Register
%d0 through %d7

Address Register
%a0 through %a7
%a7 is also known as %sp, i.e. the Stack Pointer. %a6 is also known as %fp, the Frame Pointer.

Address Register Indirect
%a0@ through %a7@

Address Register Postincrement
%a0@+ through %a7@+

Address Register Predecrement
%a0@- through %a7@-

Indirect Plus Offset
apc@(number)

Index
apc@(number,register:size:scale)

The number may be omitted.

Postindex
apc@(number)@(onumber,register:size:scale)

The onumber or the register, but not both, may be omitted.

Preindex
apc@(number,register:size:scale)@(onumber)

The number may be omitted. Omitting the register produces the Postindex addressing mode.

Absolute
symbol, or digits, optionally followed by :b, :w, or :l.


Motorola Syntax
Previous Motorola 680x0 Dependent Features Next

In the following table, apc stands for any of the address registers (%a0 through %a7), the program counter (%pc), the zero-address relative to the program counter (%zpc), or a suppressed address register (%za0 through %za7). The use of size means one of w or l, and it may always be omitted along with the leading dot. The use of scale means one of 1, 2, 4, or 8, and it may always be omitted along with the leading asterisk.

The following additional addressing modes are understood (note that some of them are valid only on 68020 or later processors, not on the ordinary 68000 used in TI calculators):

Address Register Indirect
(%a0) through (%a7)
%a7 is also known as %sp, i.e. the Stack Pointer. %a6 is also known as %fp, the Frame Pointer.

Address Register Postincrement
(%a0)+ through (%a7)+

Address Register Predecrement
-(%a0) through -(%a7)

Indirect Plus Offset
number(%a0) through number(%a7), or number(%pc).

The number may also appear within the parentheses, as in (number,%a0). When used with the pc, the number may be omitted (with an address register, omitting the number produces Address Register Indirect mode).

Index
number(apc,register.size*scale)

The number may be omitted, or it may appear within the parentheses. The apc may be omitted. The register and the apc may appear in either order. If both apc and register are address registers, and the size and scale are omitted, then the first register is taken as the base register, and the second as the index register.

Postindex
([number,apc],register.size*scale,onumber)

The onumber, or the register, or both, may be omitted. Either the number or the apc may be omitted, but not both.

Preindex
([number,apc,register.size*scale],onumber)

The number, or the apc, or the register, or any two of them, may be omitted. The onumber may be omitted. The register and the apc may appear in either order. If both apc and register are address registers, and the size and scale are omitted, then the first register is taken as the base register, and the second as the index register.


Branch Improvement
Previous Motorola 680x0 Dependent Features Next

Certain pseudo opcodes are permitted for branch instructions. They expand to the shortest branch instruction that reach the target. Generally these mnemonics are made by substituting j for b at the start of a Motorola mnemonic.

The following table summarizes the pseudo-operations for the 68000 processor; the 68020 has some more possibilites. Note that the 68000 LONG operations are always absolute and require runtime relocation. They will not be used if the '--pcrel' option is given. A (*) flags cases that are more fully described after the table:

 | Displacement
Pseudo-Op | BYTE | WORD | LONG
jbsr | bsr.s | bsr | jsr
jra | bra.s | bra | jmp
jXX (*) | bXX.s | bXX | bNX; jmp
dbXX (*) | dbXX | dbXX | dbXX; bra; jmp

XX: condition
NX: negative of condition XX

jbsr
jra
These are the simplest jump pseudo-operations; they always map to one particular machine instruction, depending on the displacement to the branch target. This instruction will be a byte or word branch if that is sufficient. Otherwise, if the '--pcrel' option is not given, an absolute long jump will be emitted. If the '--pcrel' option is given and a word branch cannot reach the target, an error message is generated.

In addition to standard branch operands, as allows these pseudo-operations to have all operands that are allowed for jsr and jmp, substituting these instructions if the operand given is not valid for a branch instruction.

jXX
Here, jXX stands for an entire family of pseudo-operations, where XX is a conditional branch or condition-code test. The full list of pseudo-ops in this family is:

jhi | jls | jcc | jcs | jne | jeq | jvc
jvs | jpl | jmi | jge | jlt | jgt | jle

Usually, each of these pseudo-operations expands to a single branch instruction. However, if a word branch is not sufficient and the '--pcrel' option is not given, as issues a longer code fragment in terms of NX, the opposite condition to XX. For example, under these conditions:
    jXX foo
gives
     bNXs oof
     jmp foo
oof:
dbXX
The full family of pseudo-operations covered here is:

dbhi | dbls | dbcc | dbcs | dbne | dbeq | dbvc
dbvs | dbpl | dbmi | dbge | dblt | dbgt | dble
dbf | dbra | dbt

Motorola dbXX instructions allow word displacements only. When a word displacement is sufficient, each of these pseudo-operations expands to the corresponding Motorola instruction. When a word displacement is not sufficient and long branches are available, when the source reads dbXX foo, as emits
     dbXX oo1
     bra.s oo2
oo1: jmp foo
oo2:


Special Characters
Previous Motorola 680x0 Dependent Features

The immediate character is # for Sun compatibility. The line-comment character is | (unless the '--bitwise-or' option is used). If a # appears at the beginning of a line, it is treated as a comment unless it looks like # line file, in which case it is treated normally.


Sections and Relocation
Previous The GNU Assembler Next

Roughly, a section is a range of addresses, with no gaps; all data "in" those addresses is treated the same for some particular purpose. For example there may be a "read only" section.

The linker ld reads many object files (partial programs) and combines their contents to form a runnable program. When as emits an object file, the partial program is assumed to start at address 0. ld assigns the final addresses for the partial program, so that different partial programs do not overlap. This is actually an oversimplification, but it suffices to explain how as uses sections.

ld moves blocks of bytes of your program to their run-time addresses. These blocks slide to their run-time addresses as rigid units; their length does not change and neither does the order of bytes within them. Such a rigid unit is called a section. Assigning run-time addresses to sections is called relocation. It includes the task of adjusting mentions of object-file addresses so they refer to the proper run-time addresses.

An object file written by as has at least three sections, any of which may be empty. These are named text, data and bss sections.

as can also generate whatever other named sections you specify using the .section directive. If you do not use any directives that place output in the .text or .data sections, these sections still exist, but are empty. Within the object file, the text section starts at address 0, the data section follows, and the bss section follows the data section.

To let ld know which data changes when the sections are relocated, and how to change that data, as also writes to the object file details of the relocation needed. To perform relocation ld must know, each time an address in the object file is mentioned:

  • Where in the object file is the beginning of this reference to an address?

  • How long (in bytes) is this reference?

  • Which section does the address refer to? What is the numeric value of (address) - (start-address of section)?

  • Is the reference to an address "Program-Counter relative"?
In fact, every address as ever uses is expressed as (section) + (offset into section)

Further, most expressions as computes have this section-relative nature. In this manual we use the notation {secname N} to mean "offset N into section secname."

Apart from text, data and bss sections you need to know about the absolute section. When ld mixes partial programs, addresses in the absolute section remain unchanged. For example, address {absolute 0} is "relocated" to run-time address 0 by ld. Although the linker never arranges two partial programs' data sections with overlapping addresses after linking, by definition their absolute sections must overlap. Address {absolute 239} in one part of a program is always the same address when the program is running as address {absolute 239} in any other part of the program.

The idea of sections is extended to the undefined section. Any address whose section is unknown at assembly time is by definition rendered {undefined U} - where U is filled in later. Since numbers are always defined, the only way to generate an undefined address is to mention an undefined symbol. A reference to a named common block would be such a symbol: its value is unknown at assembly time so it has section undefined.

By analogy the word section is used to describe groups of sections in the linked program. ld puts all partial programs' text sections in contiguous addresses in the linked program. It is customary to refer to the text section of a program, meaning all the addresses of all partial programs' text sections. Likewise for data and bss sections.

Some sections are manipulated by ld; others are invented for use of as and have no meaning except during assembly.
  • Linker Sections
  • Assembler Internal Sections
  • Sub-Sections
  • bss Section


Linker Sections
Sections and Relocation Next

ld deals with just four kinds of sections, summarized below.

These sections hold your program. as and ld treat them as separate but equal sections. Anything you can say of one section is true of another. When the program is running, however, it is customary for the text section to be unalterable. The text section is often shared among processes: it contains instructions, constants and the like. The data section of a running program is usually alterable: for example, C variables would be stored in the data section.
bss section
This section contains zeroed bytes when your program begins running. It is used to hold uninitialized variables or common storage. The length of each partial program's bss section is important, but because it starts out containing zeroed bytes there is no need to store explicit zero bytes in the object file. The bss section was invented to eliminate those explicit zeros from object files.

absolute section
Address 0 of this section is always "relocated" to runtime address 0. This is useful if you want to refer to an address that ld must not change when relocating. In this sense we speak of absolute addresses being "unrelocatable": they do not change during relocation.

undefined section
This "section" is a catch-all for address references to objects not in the preceding sections.
An idealized example of three relocatable sections follows. Memory addresses are on the horizontal axis.
                      + - --+ - -+--+
partial program # 1:  |ttttt|dddd|00|
                      + - --+ - -+--+

                      text  data bss
                      seg.  seg. seg.

                      + - + - + - +
partial program # 2:  |TTT|DDD|000|
                      + - + - + - +

                      +--+ - + - --+--+ - -+ - + - --+~~
linked program:       |  |TTT|ttttt|  |dddd|DDD|00000|
                      +--+ - + - --+--+ - -+ - + - --+~~

    addresses:        0 ...


Assembler Internal Sections
Previous Sections and Relocation Next

These sections are meant only for the internal use of as. They have no meaning at run-time. You do not really need to know about these sections for most purposes; but they can be mentioned in as warning messages, so it might be helpful to have an idea of their meanings to as. These sections are used to permit the value of every expression in your assembly language program to be a section-relative address.

ASSEMBLER-INTERNAL-LOGIC-ERROR!
An internal assembler logic error has been found. This means there is a bug in the assembler.

expr section
The assembler stores complex expression internally as combinations of symbols. When it needs to represent an expression as a symbol, it puts it in the expr section.


Sub-Sections
Previous Sections and Relocation Next

You may have separate groups of data in named sections that you want to end up near to each other in the object file, even though they are not contiguous in the assembler source. as allows you to use subsections for this purpose. Within each section, there can be numbered subsections with values from 0 to 8192. Objects assembled into the same subsection go into the object file together with other objects in the same subsection. For example, a compiler might want to store constants in the text section, but might not want to have them interspersed with the program being assembled. In this case, the compiler could issue a .text 0 before each section of code being output, and a .text 1 before each group of constants being output.

Subsections are optional. If you do not use subsections, everything goes in subsection number zero.

Subsections appear in your object file in numeric order, lowest numbered to highest. (All this to be compatible with other people's assemblers.) The object file contains no representation of subsections; ld and other programs that manipulate object files see no trace of them. They just see all your text subsections as a text section, and all your data subsections as a data section.

To specify which subsection you want subsequent statements assembled into, use a numeric argument to specify it, in a .text expression or a .data expression statement. You can also use an extra subsection argument with arbitrarily named sections: .section name, expression. Expression should be an absolute expression. (see Expressions.) If you just say .text then .text 0 is assumed. Likewise .data means .data 0. Assembly begins in text 0. For instance:

.text 0     # The default subsection is text 0 anyway.
.ascii "This lives in the first text subsection. *"
.text 1
.ascii "But this lives in the second text subsection."
.data 0
.ascii "This lives in the data section,"
.ascii "in the first data subsection."
.text 0
.ascii "This lives in the first text section,"
.ascii "immediately following the asterisk (*)."
Each section has a location counter incremented by one for every byte assembled into that section. Because subsections are merely a convenience restricted to as there is no concept of a subsection location counter. There is no way to directly manipulate a location counter - but the .align directive changes it, and any label definition captures its current value. The location counter of the section where statements are being assembled is said to be the active location counter.


bss Section
Previous Sections and Relocation

The bss section is used for local common variable storage. You may allocate address space in the bss section, but you may not dictate data to load into it before your program executes. When your program starts running, all the contents of the bss section are zeroed bytes.

The .lcomm pseudo-op defines a symbol in the bss section.

The .comm pseudo-op may be used to declare a common symbol, which is another form of uninitialized symbol.

You may switch into the .bss section and define symbols as usual (see .section). You may only assemble zero values into the section. Typically the section will only contain symbol definitions and .skip directives.


Assembler Symbols
Previous The GNU Assembler Next

Symbols are a central concept: the programmer uses symbols to name things, the linker uses symbols to link, and the debugger uses symbols to debug.

Note that as does not place symbols in the object file in the same order they were declared. This may break some debuggers.

  • Labels
  • Giving Symbols Other Values
  • Symbol Names
  • The Special Dot Symbol
  • Symbol Attributes


Labels
Assembler Symbols Next

A label is written as a symbol immediately followed by a colon :. The symbol then represents the current value of the active location counter, and is, for example, a suitable instruction operand. You are warned if you use the same symbol to represent two different locations: the first definition overrides any other definitions.


Giving Symbols Other Values
Previous Assembler Symbols Next

A symbol can be given an arbitrary value by writing a symbol, followed by an equals sign =, followed by an expression (see Expressions). This is equivalent to using the .set directive.


Symbol Names
Previous Assembler Symbols Next

Symbol names begin with a letter or with ., _, or $. That character may be followed by any string of digits, letters, dollar signs, and underscores. Case of letters is significant: foo is a different symbol name than Foo.

Each symbol has exactly one name. Each name in an assembly language program refers to exactly one symbol. You may use that symbol name any number of times in a program.

  • Local Symbol Names
  • Dollar Local Labels


Local Symbol Names
Symbol Names Next

Local symbols help compilers and programmers use names temporarily. They create symbols which are guaranteed to be unique over the entire scope of the input source code and which can be referred to by a simple notation. To define a local symbol, write a label of the form N: (where N represents any positive integer). To refer to the most recent previous definition of that symbol write Nb, using the same number as when you defined the label. To refer to the next definition of a local label, write Nf - The b stands for "backwards" and the f stands for "forwards".

There is no restriction on how you can use these labels, and you can reuse them as well. So it is possible to repeatedly define the same local label (using the same number N), although you can only refer to the most recently defined local label of that number (for a backwards reference) or the next definition of a specific local label for a forward reference. It is also worth noting that the first 10 local labels (0:...9:) are implemented in a slightly more efficient manner than the others.

Here is an example:

1:        jra 1f
2:        jra 1b
1:        jra 2f
2:        jra 1b
Which is the equivalent of:
label_1:  jra label_3
label_2:  jra label_1
label_3:  jra label_4
label_4:  jra label_3
Local symbol names are only a notational device. They are immediately transformed into more conventional symbol names before the assembler uses them. The symbol names stored in the symbol table, appearing in error messages and optionally emitted to the object file. The names are constructed using these parts:
L
All local labels begin with L. Normally both as and ld forget symbols that start with L. These labels are used for symbols you are never intended to see. If you use the '-L' option, as retains these symbols in the object file. If you also instruct ld to retain these symbols, you may use them in debugging.

N
This is the number that was used in the local label definition. So if the label is written 55:, the number is 55.

\002
This unusual character is included so you do not accidentally invent a symbol of the same name.

ordinal number
This is a serial number to keep the labels distinct. The first definition of 0: gets the number 1. The 15th definition of 0: gets the number 15, and so on. Likewise the first definition of 1: gets the number 1 and its 15th defintion gets 15 as well.


Dollar Local Labels
Previous Symbol Names

as also supports an even more local form of local labels called dollar labels. These labels go out of scope (i.e. they become undefined) as soon as a non-local label is defined. Thus they remain valid for only a small region of the input source code. Normal local labels, by contrast, remain in scope for the entire file, or until they are redefined by another occurrence of the same local label.

Dollar labels are defined in exactly the same way as ordinary local labels, except that instead of being terminated by a colon, they are terminated by a dollar sign (for example, 55$).

They can also be distinguished from ordinary local labels by their transformed name which uses ASCII character \001 (control-A) as the magic character to distinguish them from ordinary labels.


The Special Dot Symbol
Previous Assembler Symbols Next

The special symbol . refers to the current address that as is assembling into. Thus, the expression melvin: .long . defines melvin to contain its own address. Assigning a value to . is treated the same as a .org directive. Thus, the expression .=.+4 is the same as saying .space 4.


Symbol Attributes
Previous Assembler Symbols

Every symbol has, as well as its name, the attributes "Value" and "Type". Depending on output format, symbols can also have auxiliary attributes. If you use a symbol without defining it, as assumes zero for all these attributes, and probably won't warn you. This makes the symbol an externally defined symbol, which is generally what you would want.

  • Value
  • Type
  • Symbol Attributes for COFF


Value
Symbol Attributes Next

The value of a symbol is (usually) 32 bits. For a symbol which labels a location in the text, data, bss or absolute sections the value is the number of addresses from the start of that section to the label. Naturally for text, data and bss sections the value of a symbol changes as ld changes section base addresses during linking. Absolute symbols' values do not change during linking: that is why they are called absolute.

The value of an undefined symbol is treated in a special way. If it is 0 then the symbol is not defined in this assembler source file, and ld tries to determine its value from other files linked into the same program. You make this kind of symbol simply by mentioning a symbol name without defining it. A non-zero value represents a .comm common declaration. The value is how much common storage to reserve, in bytes (addresses). The symbol refers to the first address of the allocated storage.


Type
Previous Symbol Attributes Next

The type attribute of a symbol contains relocation (section) information, any flag settings indicating that a symbol is external, and (optionally), other information for linkers and debuggers. The exact format depends on the object-code output format in use.


Symbol Attributes for COFF
Previous Symbol Attributes

The COFF format supports a multitude of auxiliary symbol attributes; like the primary symbol attributes, they are set between .def and .endef directives.

  • Primary Attributes
  • Auxiliary Attributes


Primary Attributes
Symbol Attributes for COFF Next

The symbol name is set with .def; the value and type, respectively, with .val and .type.


Auxiliary Attributes
Previous Symbol Attributes for COFF

The as directives .dim, .line, .scl, .size, and .tag can generate auxiliary symbol table information for COFF.


Assembler Expressions
Previous The GNU Assembler Next

An expression specifies an address or numeric value. Whitespace may precede and/or follow an expression.

The result of an expression must be an absolute number, or else an offset into a particular section. If an expression is not absolute, and there is not enough information when as sees the expression to know its section, a second pass over the source program might be necessary to interpret the expression - but the second pass is currently not implemented. as aborts with an error message in this situation.

  • Empty Expressions
  • Integer Expressions


Empty Expressions
Assembler Expressions Next

An empty expression has no value: it is just whitespace or null. Wherever an absolute expression is required, you may omit the expression, and as assumes a value of (absolute) 0. This is compatible with other assemblers.


Integer Expressions
Previous Assembler Expressions

An integer expression is one or more arguments delimited by operators.

  • Arguments
  • Operators


Arguments
Integer Expressions Next

Arguments are symbols, numbers or subexpressions. In other contexts arguments are sometimes called "arithmetic operands". In this manual, to avoid confusing them with the "instruction operands" of the machine language, we use the term "argument" to refer to parts of expressions only, reserving the word "operand" to refer only to machine instruction operands.

Symbols are evaluated to yield {section NNN} where section is one of text, data, bss, absolute, or undefined. NNN is a signed, 2's complement 32 bit integer.

Numbers are usually integers. In principle, a number can be a flonum or bignum. In this case, you are warned that only the low order 32 bits are used, and as pretends these 32 bits are an integer. You may write integer-manipulating instructions that act on exotic constants, compatible with other assemblers.

Subexpressions are a left parenthesis ( followed by an integer expression, followed by a right parenthesis ); or a prefix operator followed by an argument.


Operators
Previous Integer Expressions

Operators are arithmetic functions, like + or %. Prefix operators are followed by an argument. Infix operators appear between their arguments. Operators may be preceded and/or followed by whitespace.

  • Prefix Operators
  • Infix Operators


Prefix Operators
Operators Next

as has the following prefix operators. They each take one argument, which must be absolute.

-
Negation. Two's complement negation.
~
Complementation. Bitwise NOT.


Infix Operators
Previous Operators

Infix operators take two arguments, one on either side. Operators have precedence, but operations with equal precedence are performed left to right. Apart from + or -, both arguments must be absolute, and the result is absolute.

  1. Highest Precedence

    *
    Multiplication.

    /
    Division. Truncation is the same as the C operator /.

    %
    Remainder.

    <
    <<
    Shift Left. Same as the C operator <<.

    >
    >>
    Shift Right. Same as the C operator >>.

  2. Intermediate precedence

    |
    Bitwise Inclusive OR.

    &
    Bitwise AND.

    ^
    Bitwise Exclusive OR.

    !
    Bitwise OR NOT.

  3. Low Precedence

    +
    Addition. If either argument is absolute, the result has the section of the other argument. You may not add together arguments from different sections.

    -
    Subtraction. If the right argument is absolute, the result has the section of the left argument. If both arguments are in the same section, the result is absolute. You may not subtract arguments from different sections.

    ==
    Is Equal To.
    <>
    Is Not Equal To.
    <
    Is Less Than.
    >
    Is Greater Than.
    >=
    Is Greater Than Or Equal To.
    <=
    Is Less Than Or Equal To.

    The comparison operators can be used as infix operators. A true results has a value of -1 whereas a false result has a value of 0. Note, these operators perform signed comparisons.

  4. &&
    Logical AND.

    ||
    Logical OR.

    These two logical operations can be used to combine the results of sub expressions. Note, unlike the comparison operators a true result returns a value of 1. Also note that the logical OR operator has a slightly lower precedence than logical AND.
In short, it's only meaningful to add or subtract the offsets in an address; you can only have a defined section in one of the two arguments.


Assembler Directives
Previous The GNU Assembler Next

All assembler directives have names that begin with a period (.). The rest of the name is letters, usually in lower case.

This chapter mostly discusses directives that are available regardless of the target machine configuration for the GNU assembler.

  • .abort
  • .align
  • .ascii
  • .asciz
  • .balign[wl]
  • .byte
  • .comm
  • .data
  • .def
  • .dim
  • .double
  • .eject
  • .else
  • .end
  • .elseif
  • .endef
  • .endfunc
  • .endif
  • .endm
  • .endr
  • .equ
  • .equiv
  • .err
  • .even
  • .exitm
  • .extern
  • .fail
  • .file
  • .fill
  • .float
  • .func
  • .global
  • .hword
  • .ident
  • .if
  • .include
  • .incbin
  • .int
  • .irp
  • .irpc
  • .lcomm
  • .lflags
  • .line
  • .ln
  • .list
  • .long
  • .macro
  • .mri
  • .nolist
  • .octa
  • .org
  • .p2align[wl]
  • .print
  • .psize
  • .purgem
  • .quad
  • .rept
  • .sbttl
  • .scl
  • .section
  • .set
  • .short
  • .single
  • .size
  • .sleb128
  • .skip
  • .space
  • .stabd
  • .stabn
  • .stabs
  • .string
  • .struct
  • .tag
  • .text
  • .title
  • .type
  • .uleb128
  • .val
  • .vtable_entry
  • .word


.abort
Assembler Directives Next

This directive stops the assembly immediately. It is for compatibility with other assemblers. The original idea was that the assembly language source would be piped into the assembler. If the sender of the source quit, it could use this directive to tell as to quit also. One day .abort will not be supported.

.ABORT is accepted as an alternate spelling of .abort.


.align
Previous Assembler Directives Next

Syntax: .align alignment[, [fill][, max]]

Pad the location counter (in the current subsection) to a particular storage boundary. alignment (which must be absolute) is the alignment required, as described below.

fill (also absolute) gives the fill value to be stored in the padding bytes. It (and the comma) may be omitted. If it is omitted, the padding bytes are normally zero. However, on some systems, if the section is marked as containing code and the fill value is omitted, the space is filled with no-op instructions (I didn't check whether this is the case in GCC4TI).

max is also absolute, and is also optional. If it is present, it is the maximum number of bytes that should be skipped by this alignment directive. If doing the alignment would require skipping more bytes than the specified maximum, then the alignment is not done at all. You can omit the fill value (the second argument) entirely by simply using two commas after the required alignment; this can be useful if you want the alignment to be filled with no-op instructions when appropriate.

The way the required alignment is specified varies from system to system. For the a29k, hppa, m68k, m88k, w65, sparc, Xtensa, and Renesas / SuperH SH, and i386 using ELF format, the first expression is the alignment request in bytes. For example .align 8 advances the location counter until it is a multiple of 8. If the location counter is already a multiple of 8, no change is needed.

For other systems, including the i386 using a.out format, and the arm and strongarm, it is the number of low-order zero bits the location counter must have after advancement. For example .align 3 advances the location counter until it a multiple of 8. If the location counter is already a multiple of 8, no change is needed.

This inconsistency is due to the different behaviors of the various native assemblers for these systems which as must emulate. as also provides .balign and .p2align directives, which have a consistent behavior across all architectures (but are specific to as).


.ascii
Previous Assembler Directives Next

Syntax: .ascii strings

.ascii expects zero or more string literals (see Strings) separated by commas. It assembles each string (with no automatic trailing zero byte) into consecutive addresses.

See also: .asciz, .string


.asciz
Previous Assembler Directives Next

Syntax: .asciz strings

.asciz is just like .ascii, but each string is followed by a zero byte. The "z" in .asciz stands for "zero".

See also: .ascii, .string


.balign[wl]
Previous Assembler Directives Next

Syntax: .balign[wl] alignment[, [fill][, max]]

Pad the location counter (in the current subsection) to a particular storage boundary. alignment (which must be absolute) is the alignment request in bytes. For example .balign 8 advances the location counter until it is a multiple of 8. If the location counter is already a multiple of 8, no change is needed.

fill (also absolute) gives the fill value to be stored in the padding bytes. It (and the comma) may be omitted. If it is omitted, the padding bytes are normally zero. However, on some systems, if the section is marked as containing code and the fill value is omitted, the space is filled with no-op instructions (I didn't check whether this is the case in GCC4TI).

max is also absolute, and is also optional. If it is present, it is the maximum number of bytes that should be skipped by this alignment directive. If doing the alignment would require skipping more bytes than the specified maximum, then the alignment is not done at all. You can omit the fill value (the second argument) entirely by simply using two commas after the required alignment; this can be useful if you want the alignment to be filled with no-op instructions when appropriate.

The .balignw and .balignl directives are variants of the .balign directive. The .balignw directive treats the fill pattern as a two byte word value. The .balignl directives treats the fill pattern as a four byte longword value. For example, .balignw 4,0x368d will align to a multiple of 4. If it skips two bytes, they will be filled in with the value 0x368d (the exact placement of the bytes depends upon the endianness of the processor). If it skips 1 or 3 bytes, the fill value is undefined.

See also: .p2align


.byte
Previous Assembler Directives Next

Syntax: .byte expressions

.byte expects zero or more expressions, separated by commas. Each expression is assembled into the next byte.


.comm
Previous Assembler Directives Next

Syntax: .comm symbol, length

.comm declares a common symbol named symbol. When linking, a common symbol in one object file may be merged with a defined or common symbol of the same name in another object file. If ld does not see a definition for the symbol - just one or more common symbols - then it will allocate length bytes of uninitialized memory. length must be an absolute expression. If ld sees multiple common symbols with the same name, and they do not all have the same size, it will allocate space using the largest size.

See also: .lcomm


.data
Previous Assembler Directives Next

Syntax: .data [subsection]

.data tells as to assemble the following statements onto the end of the data subsection numbered subsection (which is an absolute expression). If subsection is omitted, it defaults to zero.

In order to be compatible with the Sun assembler, the 680x0 assembler understands the directives .data1 and .data2 as alternatives to .data 1 and .data 2.

See also: .text


.def
Previous Assembler Directives Next

Syntax: .def name

Begin defining debugging information for a symbol name; the definition extends until the .endef directive is encountered.


.dim
Previous Assembler Directives Next

This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside .def/.endef pairs.


.double
Previous Assembler Directives Next

Syntax: .double flonums

.double expects zero or more flonums, separated by commas. It assembles floating point numbers.

See also: .single


.eject
Previous Assembler Directives Next

Force a page break at this point, when generating assembly listings.


.else
Previous Assembler Directives Next

.else is part of the as support for conditional assembly; see .if. It marks the beginning of a section of code to be assembled if the condition for the preceding .if was false.


.end
Previous Assembler Directives Next

.end marks the end of the assembly file. as does not process anything in the file past the .end directive.


.elseif
Previous Assembler Directives Next

.elseif is part of the as support for conditional assembly; see .if. It is shorthand for beginning a new .if block that would otherwise fill the entire .else section.


.endef
Previous Assembler Directives Next

This directive flags the end of a symbol definition begun with .def.


.endfunc
Previous Assembler Directives Next

.endfunc marks the end of a function specified with .func.


.endif
Previous Assembler Directives Next

.endif is part of the as support for conditional assembly; it marks the end of a block of code that is only assembled conditionally. See .if.


.endm
Previous Assembler Directives Next

.endm terminates a .macro directive.


.endr
Previous Assembler Directives Next

.endr can terminate either an .irp or an .irpc directive.


.equ
Previous Assembler Directives Next

Syntax: .equ symbol, expression

This directive sets the value of symbol to expression. It is synonymous with .set.

See also: .equiv


.equiv
Previous Assembler Directives Next

Syntax: .equiv symbol, expression

The .equiv directive is like .equ and .set, except that the assembler will signal an error if symbol is already defined. Note a symbol which has been referenced but not actually defined is considered to be undefined.

Except for the contents of the error message, this is roughly equivalent to

.ifdef SYM
.err
.endif
.equ SYM,VAL


.err
Previous Assembler Directives Next

If as assembles a .err directive, it will print an error message and, unless the '-Z' option was used, it will not generate an object file. This can be used to signal error an conditionally compiled code.


.even
Previous Assembler Directives Next

This directive is a special case of the .align directive; it aligns the output to an even byte boundary. It is 680x0-specific; introduced in order to be compatible with the Sun assembler.


.exitm
Previous Assembler Directives Next

Exit early from the current macro definition. See .macro.


.extern
Previous Assembler Directives Next

.extern is accepted in the source program - for compatibility with other assemblers - but it is ignored. as treats all undefined symbols as external.


.fail
Previous Assembler Directives Next

Generates an error or a warning. If the value of the expression is 500 or more, as will print a warning message. If the value is less than 500, as will print an error message. The message will include the value of expression. This can occasionally be useful inside complex nested macros or conditional assembly.


.file
Previous Assembler Directives Next

Syntax: .file string

.file tells as that we are about to start a new logical file. string is the new file name. In general, the filename is recognized whether or not it is surrounded by quotes ("); but if you wish to specify an empty file name, you must give the quotes "".


.fill
Previous Assembler Directives Next

Syntax: .fill repeat[, size[, value]]

repeat, size and value are absolute expressions. This emits repeat copies of size bytes. Repeat may be zero or more. Size may be zero or more, but if it is more than 8, then it is deemed to have the value 8, compatible with other people's assemblers. The contents of each repeat bytes is taken from an 8-byte number. The highest order 4 bytes are zero. The lowest order 4 bytes are value rendered in the byte-order of an integer on the computer as is assembling for (big-endian for 680x0). Each size bytes in a repetition is taken from the lowest order size bytes of this number. Again, this bizarre behavior is compatible with other people's assemblers.

size and value are optional. If the second comma and value are absent, value is assumed zero. If the first comma and following tokens are absent, size is assumed to be 1.


.float
Previous Assembler Directives Next

Syntax: .float flonums

This directive assembles zero or more flonums, separated by commas. It has the same effect as .single.


.func
Previous Assembler Directives Next

Syntax: .func name[, label]

.func emits debugging information to denote function name, and is ignored unless the file is assembled with debugging enabled. Only '--gstabs' is currently supported. label is the entry point of the function, and if omitted, name prepended with the leading character is used (no leading character in TIGCC/GCC4TI). All functions are currently defined to have void return type. The function must be terminated with .endfunc.


.global
Previous Assembler Directives Next

Syntax: .global symbol

.global makes the symbol visible to ld. If you define symbol in your partial program, its value is made available to other partial programs that are linked with it. Otherwise, symbol takes its attributes from a symbol of the same name from another file linked into the same program.

Both spellings (.globl and .global) are accepted, for compatibility with other assemblers. .xdef is also accepted as a synonym for .global.


.hword
Previous Assembler Directives Next

Syntax: .hword expressions

This expects zero or more expressions, and emits a 16 bit number for each.

On this target, this directive is a synonym for both .short and .word.


.ident
Previous Assembler Directives Next

This directive is used by some assemblers to place tags in object files. as simply accepts the directive for source-file compatibility with such assemblers, but does not actually emit anything for it.


.if
Previous Assembler Directives Next

Syntax: .if absolute expression

.if marks the beginning of a section of code which is only considered part of the source program being assembled if the argument (which must be an absolute expression) is non-zero. The end of the conditional section of code must be marked by .endif; optionally, you may include code for the alternative condition, flagged by .else. If you have several conditions to check, .elseif may be used to avoid nesting blocks if/else within each subsequent .else block.

The following variants of .if are also supported:

.ifdef symbol
Assembles the following section of code if the specified symbol has been defined. Note a symbol which has been referenced but not yet defined is considered to be undefined.

.ifc string1, string2
Assembles the following section of code if the two strings are the same. The strings may be optionally quoted with single quotes. If they are not quoted, the first string stops at the first comma, and the second string stops at the end of the line. Strings which contain whitespace should be quoted. The string comparison is case sensitive.

.ifeq absolute expression
Assembles the following section of code if the argument is zero.

.ifeqs string1, string2
Another form of .ifc. The strings must be quoted using double quotes.

.ifge absolute expression
Assembles the following section of code if the argument is greater than or equal to zero.

.ifgt absolute expression
Assembles the following section of code if the argument is greater than zero.

.ifle absolute expression
Assembles the following section of code if the argument is less than or equal to zero.

.iflt absolute expression
Assembles the following section of code if the argument is less than zero.

.ifnc string1, string2.
Like .ifc, but the sense of the test is reversed: this assembles the following section of code if the two strings are not the same.

.ifndef symbol
.ifnotdef symbol
Assembles the following section of code if the specified symbol has not been defined. Both spelling variants are equivalent. Note a symbol which has been referenced but not yet defined is considered to be undefined.

.ifne absolute expression
Assembles the following section of code if the argument is not equal to zero (in other words, this is equivalent to .if).

.ifnes string1, string2
Like .ifeqs, but the sense of the test is reversed: this assembles the following section of code if the two strings are not the same.


.include
Previous Assembler Directives Next

Syntax: .include "file"

This directive provides a way to include supporting files at specified points in your source program. The code from file is assembled as if it followed the point of the .include; when the end of the included file is reached, assembly of the original file continues. You can control the search paths used with the '-I' command-line option (see Command-Line Options). Quotation marks are required around file.


.incbin
Previous Assembler Directives Next

Syntax: .incbin "file"[, skip[, count]]

The incbin directive includes file verbatim at the current location. You can control the search paths used with the '-I' command-line option (see Command-Line Options). Quotation marks are required around file.

The skip argument skips a number of bytes from the start of the file. The count argument indicates the maximum number of bytes to read. Note that the data is not aligned in any way, so it is the user's responsibility to make sure that proper alignment is provided both before and after the incbin directive.


.int
Previous Assembler Directives Next

Syntax: .int expressions

Expect zero or more expressions, of any section, separated by commas. For each expression, emit a number that, at run time, is the value of that expression. The byte order and bit size of the number depends on what kind of target the assembly is for (big endian 32-bit for MC 68000; be aware that in GCC4TI, C language int variables occupy 16 bits by default).


.irp
Previous Assembler Directives Next

Syntax: .irp symbol[, value[, value][, ...]]

Evaluate a sequence of statements assigning different values to symbol. The sequence of statements starts at the .irp directive, and is terminated by an .endr directive. For each value, symbol is set to value, and the sequence of statements is assembled. If no value is listed, the sequence of statements is assembled once, with symbol set to the null string. To refer to symbol within the sequence of statements, use \symbol.

For example, assembling

        .irp   param,1,2,3
        move.l %d\param,-(%sp)
        .endr
is equivalent to assembling
        move    %d1,-(%sp)
        move.l %d2,-(%sp)
        move.l %d3,-(%sp)


.irpc
Previous Assembler Directives Next

Syntax: .irpc symbol[, value]

Evaluate a sequence of statements assigning different values to symbol. The sequence of statements starts at the .irpc directive, and is terminated by an .endr directive. For each character in value, symbol is set to the character, and the sequence of statements is assembled. If no value is listed, the sequence of statements is assembled once, with symbol set to the null string. To refer to symbol within the sequence of statements, use \symbol.

For example, assembling

        .irpc    param,123
        move.l  %d\param,-(%sp)
        .endr
is equivalent to assembling
        move.l %d1,-(%sp)
        move.l %d2,-(%sp)
        move.l %d3,-(%sp)


.lcomm
Previous Assembler Directives Next

Syntax: .lcomm symbol, length

Reserve length (an absolute expression) bytes for a local common denoted by symbol. The section and value of symbol are those of the new local common. The addresses are allocated in the bss section, so that at run-time the bytes start off zeroed. Symbol is not declared global (see .global), so is normally not visible to ld.

See also: .comm


.lflags
Previous Assembler Directives Next

as accepts this directive, for compatibility with other assemblers, but ignores it.


.line
Previous Assembler Directives Next

Syntax: .line line-number

Even though this is a directive associated with the a.out or b.out object-code formats, as still recognizes it when producing COFF output, and treats .line as though it were the COFF .ln if it is found outside a .def/.endef pair.

Inside a .def, .line is, instead, one of the directives used by compilers to generate auxiliary symbol information for debugging.


.ln
Previous Assembler Directives Next

Syntax: .ln line-number

Change the logical line number. line-number must be an absolute expression. The next line has that logical line number. Therefore any other statements on the current line (after a statement separator character) are reported as on logical line number line-number-1.

See also: .line


.list
Previous Assembler Directives Next

Control (in conjunction with the .nolist directive) whether or not assembly listings are generated. These two directives maintain an internal counter (which is zero initially). .list increments the counter, and .nolist decrements it. Assembly listings are generated whenever the counter is greater than zero.

By default, listings are disabled. When you enable them (with the '-a' command line option; see Command-Line Options), the initial value of the listing counter is one.


.long
Previous Assembler Directives Next

Syntax: .long expressions

On this target, .long is the same as .int.


.macro
Previous Assembler Directives Next

Syntax: .macro macname [macargs...]

The commands .macro and .endm allow you to define macros that generate assembly output. For example, this definition specifies a macro sum that puts a sequence of numbers into memory:

        .macro  sum from=0, to=5
        .long   \from
        .if     \to-\from
        sum     "(\from+1)",\to
        .endif
        .endm
With that (recursive) definition, SUM 0,5 is equivalent to this assembly input:
        .long   0
        .long   1
        .long   2
        .long   3
        .long   4
        .long   5
.macro macname
.macro macname macargs
Begin the definition of a macro called macname. If your macro definition requires arguments, specify their names after the macro name, separated by commas or spaces. You can supply a default value for any macro argument by following the name with =deflt. For example, these are all valid .macro statements:

.macro comm
Begin the definition of a macro called comm, which takes no arguments.

.macro plus1 p, p1
.macro plus1 p p1
Either statement begins the definition of a macro called plus1, which takes two arguments; within the macro definition, write \p or \p1 to evaluate the arguments.

.macro reserve_str p1=0 p2
Begin the definition of a macro called reserve_str, with two arguments. The first argument has a default value, but not the second. After the definition is complete, you can call the macro either as reserve_str a,b (with \p1 evaluating to a and \p2 evaluating to b), or as reserve_str ,b (with \p1 evaluating as the default, in this case 0, and \p2 evaluating to b).

When you call a macro, you can specify the argument values either by position, or by keyword. For example, sum 9,17 is equivalent to sum to=17, from=9.

.endm
Mark the end of a macro definition.

.exitm
Exit early from the current macro definition.

\
as maintains a counter of how many macros it has executed in this pseudo-variable; you can copy that number to your output with \@, but only within a macro definition.


.mri
Previous Assembler Directives Next

Syntax: .mri val

If val is non-zero, this tells as to enter MRI mode. If val is zero, this tells as to exit MRI mode. This change affects code assembled until the next .mri directive, or until the end of the file.

See also: MRI Mode


.nolist
Previous Assembler Directives Next

Control (in conjunction with the .list directive) whether or not assembly listings are generated. These two directives maintain an internal counter (which is zero initially). .list increments the counter, and .nolist decrements it. Assembly listings are generated whenever the counter is greater than zero.


.octa
Previous Assembler Directives Next

Syntax: .octa bignums

This directive expects zero or more bignums, separated by commas. For each bignum, it emits a 16-byte integer.

The term "octa" comes from contexts in which a "word" is two bytes; hence octa-word for 16 bytes.


.org
Previous Assembler Directives Next

Syntax: .org new-lc[, fill]

Advance the location counter of the current section to new-lc. new-lc is either an absolute expression or an expression with the same section as the current subsection. That is, you can't use .org to cross sections: if new-lc has the wrong section, the .org directive is ignored. To be compatible with former assemblers, if the section of new-lc is absolute, as issues a warning, then pretends the section of new-lc is the same as the current subsection.

.org may only increase the location counter, or leave it unchanged; you cannot use .org to move the location counter backwards.

Because as tries to assemble programs in one pass, new-lc may not be undefined. If you really detest this restriction we eagerly await a chance to share your improved assembler.

Beware that the origin is relative to the start of the section, not to the start of the subsection. This is compatible with other people's assemblers.

When the location counter (of the current subsection) is advanced, the intervening bytes are filled with fill which should be an absolute expression. If the comma and fill are omitted, fill defaults to zero.


.p2align[wl]
Previous Assembler Directives Next

Syntax: .p2align[wl] alignment[, [fill][, max]]

Pad the location counter (in the current subsection) to a particular storage boundary. alignment (which must be absolute) is the number of low-order zero bits the location counter must have after advancement. For example .p2align 3 advances the location counter until it a multiple of 8. If the location counter is already a multiple of 8, no change is needed.

fill (also absolute) gives the fill value to be stored in the padding bytes. It (and the comma) may be omitted. If it is omitted, the padding bytes are normally zero. However, on some systems, if the section is marked as containing code and the fill value is omitted, the space is filled with no-op instructions (I didn't check whether this is the case in GCC4TI).

max is also absolute, and is also optional. If it is present, it is the maximum number of bytes that should be skipped by this alignment directive. If doing the alignment would require skipping more bytes than the specified maximum, then the alignment is not done at all. You can omit the fill value (the second argument) entirely by simply using two commas after the required alignment; this can be useful if you want the alignment to be filled with no-op instructions when appropriate.

The .p2alignw and .p2alignl directives are variants of the .p2align directive. The .p2alignw directive treats the fill pattern as a two byte word value. The .p2alignl directives treats the fill pattern as a four byte longword value. For example, .p2alignw 2,0x368d will align to a multiple of 4. If it skips two bytes, they will be filled in with the value 0x368d (the exact placement of the bytes depends upon the endianness of the processor). If it skips 1 or 3 bytes, the fill value is undefined.

See also: .balign


.print
Previous Assembler Directives Next

Syntax: .print string

as will print string on the standard output during assembly. You must put string in double quotes.


.psize
Previous Assembler Directives Next

Syntax: .psize lines[, columns]

Use this directive to declare the number of lines - and, optionally, the number of columns - to use for each page, when generating listings.

If you do not use .psize, listings use a default line-count of 60. You may omit the comma and columns specification; the default width is 200 columns.

as generates formfeeds whenever the specified number of lines is exceeded (or whenever you explicitly request one, using .eject).

If you specify lines as 0, no formfeeds are generated save those explicitly specified with .eject.


.purgem
Previous Assembler Directives Next

Syntax: .purgem macname

Undefine the macro macname, so that later uses of the string will not be expanded.

See also: .macro


.quad
Previous Assembler Directives Next

Syntax: .quad bignums

.quad expects zero or more bignums, separated by commas. For each bignum, it emits an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a warning message; and just takes the lowest order 8 bytes of the bignum.

The term "quad" comes from contexts in which a "word" is two bytes; hence quad-word for 8 bytes.


.rept
Previous Assembler Directives Next

Syntax: .rept count

Repeat the sequence of lines between the .rept directive and the next .endr directive count times.

For example, assembling

        .rept   3
        .long   0
        .endr
is equivalent to assembling
        .long   0
        .long   0
        .long   0


.sbttl
Previous Assembler Directives Next

Syntax: .sbttl "subheading"

Use subheading as the title (third line, immediately after the title line) when generating assembly listings.

This directive affects subsequent pages, as well as the current page if it appears within ten lines of the top of a page.


.scl
Previous Assembler Directives Next

Syntax: .scl class

Set the storage-class value for a symbol. This directive may only be used inside a .def/.endef pair. Storage class may flag whether a symbol is static or external, or it may record further symbolic debugging information.


.section
Previous Assembler Directives Next

Syntax: .section name[, "flags"] or .section name[, subsegment]

Use the .section directive to assemble the following code into a section named name.

If the optional argument is quoted, it is taken as flags to use for the section. Each flag is a single character. The following flags are recognized:

b
bss section (uninitialized data)

n
section is not loaded

w
writable section

d
data section

r
read-only section

x
executable section

m
mergeable section (TIGCC/GCC4TI extension, symbols in the section are considered mergeable constants)

u
unaligned section (TIGCC/GCC4TI extension, the contents of the section need not be aligned)

s
shared section (meaningful for PE targets, useless for TIGCC/GCC4TI)

a
ignored (for compatibility with the ELF version)
If no flags are specified, the default flags depend upon the section name. If the section name is not recognized, the default will be for the section to be loaded and writable. Note the n and w flags remove attributes from the section, rather than adding them, so if they are used on their own it will be as if no flags had been specified at all.

If the optional argument to the .section directive is not quoted, it is taken as a subsegment number (see Sub-Sections).


.set
Previous Assembler Directives Next

Syntax: .set symbol, expression

Set the value of symbol to expression. This changes symbol's value and type to conform to expression. If symbol was flagged as external, it remains flagged (see Symbol Attributes).

You may .set a symbol many times in the same assembly.

If you .set a global symbol, the value stored in the object file is the last value stored into it.


.short
Previous Assembler Directives Next

Syntax: .short expressions

On this target, .short is the same as .word.


.single
Previous Assembler Directives Next

Syntax: .single flonums

This directive assembles zero or more flonums, separated by commas. It has the same effect as .float.

See also: .double


.size
Previous Assembler Directives Next

Syntax: .size expression

This directive, permitted only within .def/.endef pairs, is used to set the size associated with a symbol.


.sleb128
Previous Assembler Directives Next

Syntax: .sleb128 expressions

sleb128 stands for "signed little endian base 128." This is a compact, variable length representation of numbers used by the DWARF symbolic debugging format.

See also: .uleb128


.skip
Previous Assembler Directives Next

.skip is recognized on the 680x0 platform as a synonym for .space.


.space
Previous Assembler Directives Next

Syntax: .space size[, fill]

This directive emits size bytes, each of value fill. Both size and fill are absolute expressions. If the comma and fill are omitted, fill is assumed to be zero.


.stabd
Previous Assembler Directives Next

Syntax: .stabd type, other, desc

There are three directives that begin .stab. All emit symbols (see Symbols), for use by symbolic debuggers. The symbols are not entered in the as hash table: they cannot be referenced elsewhere in the source file. Up to five fields are required:

string
This is the symbol's name. It may contain any character except \000, so is more general than ordinary symbol names. Some debuggers used to code arbitrarily complex structures into symbol names using this field.

type
An absolute expression. The symbol's type is set to the low 8 bits of this expression. Any bit pattern is permitted, but ld and debuggers choke on silly bit patterns.

other
An absolute expression. The symbol's "other" attribute is set to the low 8 bits of this expression.

desc
An absolute expression. The symbol's descriptor is set to the low 16 bits of this expression.

value
An absolute expression which becomes the symbol's value.
If a warning is detected while reading a .stabd, .stabn, or .stabs statement, the symbol has probably already been created; you get a half-formed symbol in your object file. This is compatible with earlier assemblers!

If .stabd is used, the "name" of the symbol generated is not even an empty string. It is a null pointer, for compatibility. Older assemblers used a null pointer so they didn't waste space in object files with empty strings.

The symbol's value is set to the location counter, relocatably. When your program is linked, the value of this symbol is the address of the location counter when the .stabd was assembled. If .stabn is used, the name of the symbol is set to the empty string "". If .stabs is used, all five fields are required.

See also: .stabn, .stabs


.stabn
Previous Assembler Directives Next

Syntax: .stabn type, other, desc, value

See .stabd.


.stabs
Previous Assembler Directives Next

Syntax: .stabs string, type, other, desc, value

See .stabd.


.string
Previous Assembler Directives Next

Syntax: .string "str"

Copy the characters in str to the object file. You may specify more than one string to copy, separated by commas. The assembler marks the end of each string with a 0 byte. You can use any of the escape sequences described in Strings.

See also: .ascii, .asciz


.struct
Previous Assembler Directives Next

Syntax: .struct expression

Switch to the absolute section, and set the section offset to expression, which must be an absolute expression. You might use this as follows:

        .struct 0
field1:
        .struct field1 + 4
field2:
        .struct field2 + 4
field3:
This would define the symbol field1 to have the value 0, the symbol field2 to have the value 4, and the symbol field3 to have the value 8. Assembly would be left in the absolute section, and you would need to use a .section directive of some sort to change to some other section before further assembly.


.tag
Previous Assembler Directives Next

Syntax: .tag structname

This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside .def/.endef pairs. Tags are used to link structure definitions in the symbol table with instances of those structures.


.text
Previous Assembler Directives Next

Syntax: .text [subsection]

Tells as to assemble the following statements onto the end of the text subsection numbered subsection, which is an absolute expression. If subsection is omitted, subsection number zero is used.

See also: .data


.title
Previous Assembler Directives Next

Syntax: .title "heading"

Use heading as the title (second line, immediately after the source file name and pagenumber) when generating assembly listings.

This directive affects subsequent pages, as well as the current page if it appears within ten lines of the top of a page.


.type
Previous Assembler Directives Next

Syntax: .type int

This directive, permitted only within .def/.endef pairs, records the integer int as the type attribute of a symbol table entry.


.uleb128
Previous Assembler Directives Next

Syntax: .uleb128 expressions

uleb128 stands for "unsigned little endian base 128." This is a compact, variable length representation of numbers used by the DWARF symbolic debugging format.

See also: .sleb128


.val
Previous Assembler Directives Next

Syntax: .val addr

This directive, permitted only within .def/.endef pairs, records the address addr as the value attribute of a symbol table entry.


.vtable_entry
Previous Assembler Directives Next

Syntax: .vtable_entry table, offset

This directive finds or creates a symbol table and creates a VTABLE_ENTRY relocation for it with an addend of offset.


.word
Previous Assembler Directives

Syntax: .word expressions

This directive expects zero or more expressions, of any section, separated by commas. For each expression, as emits a 16-bit number for this target.


Acknowledgements
Previous The GNU Assembler Next

If you have contributed to as and your name isn't listed here, it is not meant as a slight. We just don't know about it. Send mail to the maintainer, and we'll correct the situation. Currently the maintainer is Ken Raeburn (email address raeburn@cygnus.com). (Note: Since this is a modified version of the manual, please check the original version as well before sending a mail.)

Dean Elsner wrote the original GNU assembler for the VAX. Any more details?

Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug information and the 68k series machines, most of the preprocessing pass, and extensive changes in messages.c, input-file.c, write.c.

K. Richard Pixley maintained GAS for a while, adding various enhancements and many bug fixes, including merging support for several processors, breaking GAS up to handle multiple object file format back ends (including heavy rewrite, testing, an integration of the coff and b.out back ends), adding configuration including heavy testing and verification of cross assemblers and file splits and renaming, converted GAS to strictly ANSI C including full prototypes, added support for m680[34]0 and cpu32, did considerable work on i960 including a COFF port (including considerable amounts of reverse engineering), a SPARC opcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated "know" assertions and made them work, much other reorganization, cleanup, and lint.

Ken Raeburn wrote the high-level BFD interface code to replace most of the code in format-specific I/O modules.

The original VMS support was contributed by David L. Kashtan. Eric Youngdale has done much work with it since.

The Intel 80386 machine description was written by Eliot Dresselhaus.

Minh Tran-Le at IntelliCorp contributed some AIX 386 support.

The Motorola 88k machine description was contributed by Devon Bowen of Buffalo University and Torbjorn Granlund of the Swedish Institute of Computer Science.

Keith Knowles at the Open Software Foundation wrote the original MIPS back end (tc-mips.c, tc-mips.h), and contributed Rose format support (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to support a.out format.

Support for the Zilog Z8k and Renesas H8/300 and H8/500 processors (tc-z8k, tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to use BFD for some low-level operations, for use with the H8/300 and AMD 29k targets.

John Gilmore built the AMD 29000 support, added .include support, and simplified the configuration of which versions accept which directives. He updated the 68k machine description so that Motorola's opcodes always produced fixed-size instructions (e.g., jsr), while synthetic instructions remained shrinkable (jbsr). John fixed many bugs, including true tested cross-compilation support, and one bug in relaxation that took a week and required the proverbial one-bit fix.

Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and PowerPC assembler, and made a few other minor patches.

Steve Chamberlain made as able to generate listings.

Hewlett-Packard contributed support for the HP9000/300.

Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) along with a fairly extensive HPPA testsuite (for both SOM and ELF object formats). This work was supported by both the Center for Software Science at the University of Utah and Cygnus Support.

Support for ELF format files has been worked on by Mark Eichin of Cygnus Support (original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc, and some initial 64-bit support).

Linas Vepstas added GAS support for the ESA/390 "IBM 370" architecture.

Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD support for openVMS/Alpha.

Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* flavors.

David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica, Inc. added support for Xtensa processors.

Several engineers at Cygnus Support have also provided many small bug fixes and configuration enhancements.

Many others have contributed large or small bugfixes and enhancements. If you have contributed significant work and are not mentioned on this list, and want to be, let us know. Some of the history has been lost; we are not intentionally leaving anyone out.


History
Previous The GNU Assembler

  • Original Version: Using as

    Published by the Free Software Foundation
    59 Temple Place - Suite 330
    Boston, MA 02111-1307 USA

    Copyright © 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.

  • Modifications for TIGCC: The GNU Assembler

    Published by the TIGCC Team

    Copyright © 2000, 2001, 2002, 2003 Zeljko Juric, Sebastian Reichelt, Kevin Kofler
  • Modifications for GCC4TI: The GNU Assembler

    Published by the GCC4TI Project

    Copyright © 2009, 2010 Lionel Debroux


The A68k Assembler

In addition to the GNU Assembler, the GCC4TI package also includes the A68k assembler by Charlie Gibbs (slightly modified Amiga version). Although GCC4TI also includes the GNU assembler used by GCC, A68k is included here because many old assembly programs for the TI-89 and TI-92+ are created with this assembler (so including it in the package allows compiling existing ASM programs as well), and because, while it is inferior to the GNU assembler in some aspects, it also has advantages, mainly easier syntax, but also support for binary include files for example. The A68k assembler was developed long before the TIGCC and GCC4TI projects were even started, so it is somewhat inconsistent with the rest of the project, though some effort has been made to integrate it into TIGCC/GCC4TI. For example, you can now call a function from a static library using a simple bsr or jsr instruction.

This assembler comes with its own set of header files. All of them are included mainly for compatibility reasons (note that some of them are deprecated, obsolete, inconsistent or even obscure), so they will not be described here. Information about them may be found in various ASM tutorials for TI-89 and TI-92+ (also deprecated, but note that nearly 95% of all ASM programs for TI-89 and TI-92+ are written using a now deprecated way, because a lot of information about the system was not available at the time when these programs were created). We recommend using only OS.h, which contains a list of equates for ROM_CALLs (but the ROM_CALL macros are not very optimized and should thus be avoided), and functions from TIGCCLIB, which need no header file at all (for example, bsr GrayOn is enough to call the GrayOn function). What will be presented here is the original A68k documentation, written by Charlie Gibbs himself. We have however annotated it in some places to reflect the changes made in recent versions, and we have added 2 chapters: the list of supported assembler directives, which was missing, and the history, which was kept in a separate file.

  • Introduction - About A68k
  • Restrictions
  • Extensions
  • A68k Assembler Directives
  • The Small Code/Data model
  • Files
  • File Names
  • A68k Command-Line Parameters (How to use A68k)
  • Technical Information
  • A68k Contact Information and Bug Reports
  • History of A68k


Introduction - About A68k
The A68k Assembler Next

A68k - a freely distributable assembler for the Amiga
by Charlie Gibbs
with special thanks to
Brian R. Anderson and Jeff Lydiatt
The current versions are now part of the GCC4TI project. As such, they will be aimed much more at development for the TI-89, TI-89T, TI-92+ and V200 calculators than at the Amiga. Modifications of this document are marked with (TIGCC/GCC4TI)
(Version 2.71.F3z - July 29, 2009)

Note: This program is Freely Distributable, as opposed to Public Domain. Permission is given to freely distribute this program provided no fee is charged, and this documentation file is included with the program.

This assembler is based on Brian R. Anderson's 68000 cross- assembler published in Dr. Dobb's Journal, April through June 1986. I have converted it to produce AmigaDOS-format object modules, and have made many enhancements, such as macros and INCLUDE files.

My first step was to convert the original Modula-2 code into C. I did this for two reasons. First, I had access to a C compiler, but not a Modula-2 compiler. Second, I like C better anyway.

The executable code generator code (GetObjectCode and MergeModes) is essentially the same as in the original article, aside from its translation into C. I have almost completely rewritten the remainder of the code, however, in order to remove restrictions, add enhancements, and adapt it to the AmigaDOS environment. Since the only reference book available to me was the AmigaDOS Developer's Manual (Bantam, February 1986), this document describes the assembler in terms of that book.


Restrictions
Previous The A68k Assembler Next

Let's get these out of the way first:

  • The verification file '-v' option is not supported. Diagnostic messages always appear on the console. They also appear in the listing file, however (see extensions below). You can produce an error file by redirecting console output to a file - the line number counter and final summary are displayed on stderr so you can still see what's happening.
    (TIGCC/GCC4TI) WARNING: The new -v switch introduced in v.2.71.F3c is NOT the same as this one!
  • The file names in the INCLUDE directory list '-i' must be separated by commas. The list may not be enclosed in quotes.
  • Labels assigned by EQUR and REG directives are case-sensitive.
  • Strange things will happen if your source code (including INCLUDE files and macro expansions) exceeds 32,766 lines. Tough darts. Break up your source file. Can you actually read that monster?
    (TIGCC/GCC4TI) The maximum has been increased from 32,766 to 2,147,483,646 for 32-bit operating systems starting from version 2.71.F3s.
  • Directives OFFSET, NOPAGE, LLEN, PLEN, NOOBJ, FAIL, FORMAT, NOFORMAT and MASK2 are not supported, and will be flagged as invalid op-codes. I feel that NOPAGE, LLEN, and PLEN should not be defined within a source module. It doesn't make sense to me to have to change your program just because you want to print your listings on different paper. The command-line switch '-p' (see below) can be used as a replacement for PLEN; setting it to a high value (like 32767) is a good substitute for NOPAGE. The effect of LLEN can be obtained by running the listing file through an appropriate filter.


Extensions
Previous The A68k Assembler Next

Now for the good stuff:

  • Labels can be any length that will fit onto one source line (currently 127 characters maximum). Since labels are stored on the heap, the number of labels that can be processed is limited only by available memory.
    (TIGCC/GCC4TI) The maximum has been increased from 127 to 256 (for Win32, starting from 2.71.F3a, for GNU/Linux, starting from 2.71.F3c, for all other platforms, starting from 2.71.F3s).
  • The first character of a label can be '@' if the next character is not numeric (this avoids confusion with octal constants). This provides compatibility with the Lattice C compiler.
  • Since section data and user macro definitions are stored in the symbol table (see above), they too are limited only by available memory (actually, there is a hard-coded limit of 32,767 sections, but I doubt anyone will run into that one).
  • The only values a label cannot take are the register names - A68k can distinguish between the same name used as a label, instruction name or directive, macro name, or section name.
  • Section and user macro names appear in the symbol table dump, and will also be cross-referenced. Their names can be the same as any label (see above); they will be listed separately.
  • INCLUDEs and macro calls can be nested indefinitely, limited only by available memory. The message "Secondary heap overflow - assembly terminated" will be displayed if memory is exhausted. You can increase the size of this heap using the '-w' switch (see below). Recursive macros are supported; recursive INCLUDEs will, of course, result in a loop that will be broken only when the heap overflows.
  • The EVEN directive forces alignment on a word (2-byte) boundary. It does the same thing as CNOP 0,2 (this one is left over from the original code).
  • Backward references to labels within the current CODE section will be converted to PC-relative addressing with displacement if this mode is legal for the instruction. This feature is disabled by the '-n' switch.
  • If a MOVEM instruction only specifies one register, it is converted to the corresponding MOVE instruction. Instructions such as MOVEM D0-D0,label will not be converted, however. This feature is disabled by the '-n' switch.
    (TIGCC/GCC4TI) Starting from v.2.71.F3c, this feature can now also be disabled by using the '-rm' switch.
  • ADD, SUB, and MOVE instructions will be converted to ADDQ, SUBQ, and MOVEQ respectively if possible. Instructions coded explicitly (e.g. ADDA or ADDI) will not be converted. This feature is disabled by the '-n' switch.
  • ADD, CMP, SUB, and MOVE to an address register are converted to ADDA, CMPA, SUBA, and MOVEA respectively, unless (for ADD, SUB, or MOVE) they have already been converted to quick form.
  • ADD, AND, CMP, EOR, OR, and SUB of an immediate value are converted to ADDI, ANDI, CMPI, EORI, ORI, and SUBI respectively (unless the address register or quick conversion above has already been done).

  • (TIGCC/GCC4TI) Starting from v.2.71.F3c, ADDA and SUBA (or ADD and SUB to an address register) will now be converted to LEA if possible. This feature can be disabled using the '-n' switch (disables all optimizations) or the '-ra' switch (disables just this single optimization).

  • (TIGCC/GCC4TI) Starting from v.2.71.F3c, LEA n(an),an will now be converted to ADDQ or SUBQ if possible. This feature can be disabled using the '-n' switch (disables all optimizations) or the '-rl' switch (disables just this single optimization).
  • If both operands of a CMP instruction are postincrement mode, the instruction is converted to CMPM.
  • Operands of the form '0(An)' will be treated as '(An)' except for the MOVEP instruction, which always requires a displacement. This feature is disabled by the '-n' switch.
  • The SECTION directive allows a third parameter. This can be specified as either CHIP or FAST (upper or lower case). If this parameter is present, the hunk will be written with the MEMF_CHIP or MEMF_FAST bit set. This allows you to produce "pre-ATOMized" object modules.
  • The synonyms DATA and BSS are accepted for SECTION directives starting data or BSS hunks. The CHIP and FAST options (see above) can also be used, e.g. BSS name,CHIP.
  • The following synonyms have been implemented for compatibility with the Aztec assembler:

    • CSEG is treated the same as CODE or SECTION name,CODE.
    • DSEG is treated the same as DATA or SECTION name,DATA.
    • PUBLIC is treated as either XDEF or XREF, depending on whether or not the symbol in question has been defined in the current source module. A single PUBLIC directive can name a mixture of internally- and externally-defined symbols.
  • The ability to produce Motorola S-records is retained from the original code. The '-s' switch causes the assembler to produce S-format instead of AmigaDOS format. Relocatable code cannot be produced in this format.
  • Error messages consist of three parts. The position of the offending line is given as a line number within the current module. If the line is within a macro expansion or INCLUDE file, the position of the macro call or INCLUDE statement in the outer module is given as well. This process is repeated until the outermost source module is reached. Next, the offending source line itself is listed. Finally, the errors for that line are displayed. A flag '^' is placed under the column where the error was detected.
  • Named local labels are supported. These work the same as the local labels supported by the Metacomco assembler (nnn$) but are formed in the same manner as normal labels, except that they must be preceded by a backslash ('\').
  • The following synonyms have been implemented for compatibility with the Assempro assembler:

    • ENDIF is treated the same as ENDC.
    • '=' is treated the same as EQU.
    • '|' is treated the same as '!' (logical OR).
  • Quotation marks (") can be used as string delimiters as well as apostrophes ('). Any given string must begin and end with the same delimiter. This allows such statements as the following:
         MOVEQ   "'",D0
     DC.B    "This is Charlie's assembler."
    Note that you can still define an apostrophe within a string delimited by apostrophes if you double it, e.g.
         MOVEQ   '''',D0
     DC.B    'This is Charlie''s assembler.'
  • If any errors are found in the assembly, the object code file will be scratched, unless you include the '-k' (keep) flag on the command line.
  • The symbols .A68K, .a68k, .a68K, and .A68k are automatically defined as SET symbols having absolute values of 1. This enables a source program to determine whether it is being assembled by this assembler, and is effectively insensitive as to whether or not it is checked in upper case.
  • A zeroth positional macro parameter '\0' is supported. It is replaced by the length of the macro call (B, W, or L, defaulting to W). For instance, given the macro:
    moov MACRO
     move.\0 \1,\2
     ENDM
    the macro call
         moov.l  d0,d1
    would be expanded as
         move.l  d0,d1
  • If an INCLUDE file doesn't generate any code and no listing file is required (including suppression of the listing using NOLIST), it won't be read again in pass 2. The statement numbers will be bumped to keep in proper alignment. This can really speed up assemblies that INCLUDE lots of EQUates.
  • The ORG directive is supported. It works like RORG, except that it takes the actual address to be jumped to, rather than an offset from the start of the current section. The given address must be in the current section. As far as A68k is concerned, the only real difference between ORG and RORG is that the ORG value must be relocatable, while the RORG value must be absolute.
  • Branch (Bcc, including BRA and BSR) instructions will be converted to short form if possible. Shortening a branch may bring other branches within range of shortening - this can set up a ripple effect, and A68k may not catch all branches that could theoretically be optimized. Any branches which A68k misses (there shouldn't be too many under normal circumstances) can be displayed by specifying the '-f' switch (see below). Branch optimization is disabled by the '-n' switch.
  • The INCBIN directive allows the contents of any file to be included in A68k's object code output. Its format is the same as the INCLUDE directive, but the file can contain any data at all, printable or not. Rather than being processed as source code by the assembler, the entire contents of the file is copied directly to the current position in the object code output file with no reformatting whatsoever. The effect is the same as if DC statements whose constants represent the file's contents were inserted in place of the INCBIN directive.
  • The opcode TTL is accepted as a synonym for TITLE.
  • A command-line option '-g' causes A68k to treat any undefined symbol as XREF.
  • The register list in a MOVEM instruction can be an immediate operand which specifies the actual mask bits.

  • (TIGCC/GCC4TI) The following synonyms are also supported:
    Starting from 2.71.F3a:
    • BLO = BCS
    • BHS = BCC
    • DBLO = DBCS
    • DBHS = DBCC
    • ROLX = ROXL
    • RORX = ROXR
    Starting from 2.71.F3c:
    • SLO = SCS
    • SHS = SCC


A68k Assembler Directives
Previous The A68k Assembler Next

Note: This section has been written entirely by the TIGCC Team. Part of the information comes from direct.txt by Mathieu Lacage, but the whole text is completely rewritten and contains more details. Also, some of the directives listed here are not documented in direct.txt.

The A68k assembler supports the following assembler directives:

arithmetic operators | Arithmetic operators can be used exactly like their C counterparts, except that spaces are not allowed in an expression. But ((1+2)>>3)/4 is a perfectly legitimate A68k expression. Of course, you can not use anything other than + or - on labels and you cannot use arithmetic on registers at all - you will have to use the corresponding assembly instructions.
INCLUDE "filename.h" | Includes the file given as a parameter at the current source position. The file is read in as assembly source code, as if it was part of the current assembly source.
INCBIN "filename.bin" | Includes the binary content of the file given as a parameter as-is at the current location in the object file output. The file will NOT be assembled, but included as binary data.
EVEN | Forces alignment on an even address. The next instruction will be guaranteed to be placed at an even address. This is especially important for dc.w or dc.l directives, since accessing a word or longword at an odd address causes an address error.
CNOP displacement,alignment | Forces alignment on an address which is the sum of displacement, which has to be even, and a multiple of alignment, which has to be a power of 2.
XDEF label | Exports the label given as an argument to other object files or to the linker. This also allows linker directives like xdef _nostub.
XREF label | Imports the label given as an argument. This allows to access variables from other object files even if the '-g' switch is not specified. Since GCC4TI specifies '-g' by default, there is no real need for this directive.
PUBLIC label | Imports or exports the label given as an argument, depending on whether it is part of the current source file or not. We recommend using XDEF or XREF instead when possible, since they clearly specify what is meant. But PUBLIC is useful when used in a common header file for multiple source files.
SECTION "sectname" | Sets the section the following code will be written to. This is especially useful to make A68k use the same section as GCC: .data, in order to make sure the linking order of GCC files first is respected. (Note: You can deliberately NOT specify SECTION ".data" if you want the A68k file to be the main file.)
BSS | Specifies the section the following code will be written to as a "BSS section", a section which will not be initialized at runtime, so it can contain only storage place which does not need to be initialized. Also, BSS sections are not allowed in _nostub mode.
CSEG | Creates a section called "CODE" where the code will be written to. This directive is not really useful in GCC4TI, since both code and data are written to the .data section by GCC and GNU as.
DSEG | Creates a section called "DATA" where the code will be written to. Do not use this directive in GCC4TI. Instead, specify SECTION .data, which is the section name used by GCC and GNU as for data sections.
END | Marks the end of the source file. This directive is now optional since v.2.71.F3c.
DC.{B|W|L} data1,data2,... | (Define Constant(s)) Will insert all the arguments as immediate data into the object file. For example, DC.L $12345678 will insert the bytes 0x12, 0x34, 0x56 and 0x78 into the resulting object file. DC.B 'Hello, World!',0 will insert the null-terminated string "Hello, World!" into the resulting object file.
DS.{B|W|L} n | (Define Storage) Will insert n bytes, words or longwords (depending on the size specified) of zeros (0, NOT '0') into the resulting object file.
DCB.{B|W|L} n,data | (Define Constant Block) Will act as n times the DC.B data instruction. It will insert the immediated data specified by data n times into the resulting object file.
macroName MACRO
 instructions
 ENDM 		This declares a macro so that macroName can be used as if it was an instruction, with the difference that unlike opcodes, macro names are case-sensitive. You can also pass arguments to a macro. Those are referenced by a macro as \n, where n is the number of the argument, starting from 1. \0 indicates the instruction size. \@ indicates the number of the current macro, which is useful to create unique labels of the form \@label or \\@localLbl. Therefore:
PUSH MACRO
     MOVE.\0 \1,-(a7)
     ENDM
(defined in "OS.h") allows you to use: PUSH.L #1 when in fact you mean: MOVE.L #1,-(a7).
<expression> | Makes sure expression will be treated as a single macro parameter, even if it contains separators like commas, semicolons or whitespace.
constant EQU value
OR: constant = value 		Defines a symbolic constant. Wherever constant is encountered in the code, it will be replaced by value. Note that value can also be an expression, not only a single number.
regAlias EQUR register | Defines an alias for a register. For example, if you are using a5 to hold the address of the jump table in your whole program, you can write jumpTbl EQUR a5, and then use jumpTbl wherever you would use a5.
regListAlias EQUR regList | Defines an alias for a list of registers, for use in the MOVEM instruction. The syntax of regList is the same as in the MOVEM instruction. For example, if you are frequently using MOVEM.L d0-d7/a0-a6,-(a7) and MOVEM.L (a7)+,d0-d7/a0-a6, you might define: all REG d0-d7/a0-a6, and then use all wherever you would use d0-d7/a0-a6.
variable SET value | Defines a symbolic variable. Wherever variable is encountered in the code, it will be replaced by value. But contrary to an EQU constant, a SET variable can be modified. It can therefore be used as a counter for example, as in: counter SET counter+1.
IFEQ value
instructions
ENDC 		The instructions in the block will be parsed and assembled if and only if value equals 0. You can also write ENDIF as a synonym for ENDC.
IFNE value
instructions
ENDC 		The instructions in the block will be parsed and assembled if and only if value does not equal 0. You can also write ENDIF as a synonym for ENDC.
IFGE value
instructions
ENDC 		The instructions in the block will be parsed and assembled if and only if value is greater than or equal to 0. You can also write ENDIF as a synonym for ENDC.
IFGT value
instructions
ENDC 		The instructions in the block will be parsed and assembled if and only if value is greater than 0. You can also write ENDIF as a synonym for ENDC.
IFLE value
instructions
ENDC 		The instructions in the block will be parsed and assembled if and only if value is less than or equal to 0. You can also write ENDIF as a synonym for ENDC.
IFLT value
instructions
ENDC 		The instructions in the block will be parsed and assembled if and only if value is less than 0. You can also write ENDIF as a synonym for ENDC.
IFC string1,string2
instructions
ENDC 		The instructions in the block will be parsed and assembled if and only if string1 and string2 are identical (after expansion of EQU constants). You can also write ENDIF as a synonym for ENDC.
IFNC string1,string2
instructions
ENDC 		The instructions in the block will be parsed and assembled if and only if string1 and string2 are different (after expansion of EQU constants). You can also write ENDIF as a synonym for ENDC.
IFD value
instructions
ENDC 		The instructions in the block will be parsed and assembled if and only if value is a defined symbol. You can also write ENDIF as a synonym for ENDC.
IFND value
instructions
ENDC 		The instructions in the block will be parsed and assembled if and only if value is not a defined symbol. You can also write ENDIF as a synonym for ENDC.
NEAR [register] | Enables the small code and data model.
FAR | Disables the small code and data model after a NEAR directive.
ORG expression | Places the code following the directive at the address specified by expression, which must be relocatable (that is, of the form label+number, where label is a backward reference, not a forward reference). If that address is located before the current position, the code previously generated there will be overwritten. If that adress is located after the current position, the space will be filled with zeros (0, NOT '0').
RORG offset | Places the code following the directive at the offset offset, which must be a number, from the beginning of the current object file section. If that address is located before the current position, the code previously generated there will be overwritten. If that adress is located after the current position, the space will be filled with zeros (0, NOT '0'). However, if RORG is specified before the first executable instruction and in the default section (before any SECTION, BSS, CSEG or DSEG directive), no spacing will be generated, so it has the effect of adding the number address to all absolute references, thereby pre-relocating the code to that fixed address. But such an use of this directive is not useful in GCC4TI, as assembly programs on the TI-89/92+ can be at any place in memory, and the linker always generates a relocation table which allows AMS to take care of the relocation automatically.
NOLIST | The code following this directive will not appear in the listing file created when the '-l' or '-x' switch is specified.
LIST | Reenables the listing of code after a NOLIST directive.
PAGE | Inserts a form feed into the listing file created when the '-l' or '-x' switch is specified.
SPC [n] | Skips n lines, or 1 line if n is omitted, in the listing file created when the '-l' or '-x' switch is specified.
TTL string
OR: TITLE string 		Sets the title on the pages of the listing file created when the '-l' or '-x' switch is specified to string. Also begins a new page when specified on the middle of a page.
IDNT "name" | Sets the program unit name in the S-record generated when the '-s' switch is specified, to name. The quotes can be omitted. This directive is not useful in GCC4TI, since GCC4TI does not use S-records.
\localLbl | Defines a local label, a label which can be accessed only in the space between the 2 global labels surrounding it. This mainly serves to avoid name conflicts: 2 or more local labels can have the same name as long as they are separated by a global label.
\localLbl@labelNum | Defines a local enumeration label, invented mainly for use in macros. The idea is that labelNum can be a variable name which can be expanded while keeping localLbl unchanged. But it is usually a better idea to use \@label or \\@localLbl instead, which will automatically generate unique labels.


The Small Code/Data model
Previous The A68k Assembler Next

Version 2.4 implements a rudimentary small code/data model. It consists of converting any data reference to one of the following three addressing modes:

  • address register indirect with displacement using a specified address register, defaulting to A4 (for references to the DATA or BSS section);
  • program counter indirect with displacement (for references to the CODE section);
  • absolute word (for absolute and 16-bit relocatable values).
These conversions do not take place unless a NEAR directive is encountered. The NEAR directive can take one operand, which must be either an address register or a symbol which has been equated (using EQUR) to an address register. Register A7 (SP) may not be used. If no register is given, A4 is assumed.

Conversion is done for all operands until a FAR directive is encountered. NEAR and FAR directives can occur any number of times, enabling conversion to be turned on and off at will.

Backward references which cannot be converted (e.g. external labels declared as XREF) will remain as absolute long addressing. All forward references are assumed to be convertible, since during pass 1 A68k has no way of telling whether conversion is possible. If conversion turns out to be impossible, invalid object code will be generated - an error message ("Invalid forward reference") will indicate when this occurs.

Although the small code/data model can greatly reduce the size of assembled programs, several restrictions apply:
  • Small code and small data models are active simultaneously. You can't have one without the other, since during pass 1 A68k doesn't know whether forward references are to CODE or to DATA/BSS.
  • Programs can consist of a maximum of two sections, one CODE, the other DATA or BSS. If you try to define a third section, the message "Too many SECTIONs" will be displayed. The NEAR directive is active only within the CODE section.
  • While the NEAR directive is active, external labels (XREF) must be declared before they are used, CODE section references must be with 32K of the current position (i.e. expressible as PC-relative), and DATA/BSS section references must be in the first 64K of the DATA/BSS section (i.e. expressible as address register indirect with displacement). Any instructions which do not satisfy these requirements cannot be detected in pass 1, so A68k has no choice but to display an error message in pass 2 ("Invalid forward reference") which in this case indicates that invalid code has been generated. To properly assemble such instructions, you can temporarily disable conversion with a FAR directive, then resume afterwards with another NEAR directive.
  • Conversion cannot be done for references between modules. All external references must be left as absolute long.
  • A68k assumes that the base register (normally A4) points to the start of the DATA/BSS section plus 32768 bytes (this assumed offset can be changed by the '-m' command-line parameter). The register must be preloaded with this value before executing any code converted by the NEAR directive. One way to do this is to code the instruction that loads the register prior to the NEAR directive. Another way is to use a MOVE.L with immediate mode, which is never converted. Here are examples of the two methods:
         LEA data+32768,a4                NEAR
     NEAR ;defaults to A4             MOVE.L #data+32768,a4
     <remainder of code>              <remainder of code>
     BSS                              BSS
data:                            data:
     <data areas>                     <data areas>
     END                              END
I'll be the first to admit that this is a very crude and ugly implementation. I hope to improve it in future versions.


Files
Previous The A68k Assembler Next

A68k uses the following files:

  • The source code file - this file contains the program to be assembled. This file is an ASCII text file whose last line must be an END statement.
    (TIGCC/GCC4TI) This END statement is no longer necessary starting from v.2.71.F3c.
    Moreover, the assembler will no longer accept an END statement in include files or macros, since it did never expect that and caused bugs.
  • The object code file - this file is created by A68k, replacing any previous version which may exist. If any errors are encountered during the assembly, this file will be scratched, unless the '-k' (keep) switch is specified (see below). Although this file is normally written in AmigaDOS format, the '-s' switch (see below) will cause it to be written in Motorola S-record format instead.
  • The listing file - this file is optionally created by A68k and contains a listing complete with page headings (including form feeds), generated object code, and error messages if any. It is suitable for feeding to a printer.
  • An equate file - this file is optionally created by A68k and consists of a leading comment line followed by EQU statements, one for each symbol encountered by A68k whose value is absolute. This file is only created if the '-e' command-line switch is specified (see below).
  • A header file - if requested, this file is read by A68k immediately prior to the source code file. It treated exactly as if it were requested by an INCLUDE statement at the front of the source file, but is selected only if the '-h' command-line switch is specified (see below).
  • Include files are selected by INCLUDE directives within the source file, and are inserted in the source code in place of the INCLUDE directive itself. A68k first searches the current directory for INCLUDE files; the '-i' command-line switch (see below) specifies additional directories which can be searched.


File Names
Previous The A68k Assembler Next

The names of the above files can be explicitly specified. However, A68k will generate default file names in the following cases:

  • If the '-o' switch is omitted, a default name will be assigned to the object code file.
  • If the '-e' switch is specified with no file name, a default name will be assigned to the equate file.
  • If the '-l' or '-x' switch is specified with no file name, a default name will be assigned to the listing file.
A default name is generated by deriving a stem name from the source code file name, and appending '.o' for an object code file name ('.s' if the '-s' switch is specified to produce Motorola S-records), '.equ' for an equate file name, or '.lst' for a listing file name. The stem name consists of all characters of the source file name up to the last period (or the entire source file name if it contains no period). Here are some examples of default names:

Source file | Object file | Equate file | Listing file
myprog.asm | myprog.o | myprog.equ | myprog.lst
myprog | myprog.o | myprog.equ | myprog.lst
new.prog.asm | new.prog.o | new.prog.equ | new.prog.lst


A68k Command-Line Parameters (How to use A68k)
Previous The A68k Assembler Next

The command-line syntax to run the assembler is as follows:

   a68k <source file name>
        [<object file name>]
        [<listing file name>]
(TIGCC/GCC4TI) [-a]
        [-d[[!]<prefix>]]
        [-e[<equate file name>]]
        [-f]
        [-g]
        [-h<header file name>]
        [-i<include directory list>]
        [-k]
        [-l[<listing file name>]]
        [-m<small data offset>]
        [-n]
        [-o<object file name>]
        [-p<page depth>]
        [-q[<quiet interval>]]
(TIGCC/GCC4TI) [-r[a][l][m]]
        [-s]
        [-t]
(TIGCC/GCC4TI) [-u]
(TIGCC/GCC4TI) [-v<name>[,<value>]
        [-w[<hash table size>][,<secondary heap size>]]
        [-x[<listing file name>]]
        [-y]
        [-z[<debug start line>][,<debug end line>]]
These options can be given in any order. Any parameter which is not a switch (denoted by a leading hyphen) is assumed to be a file name; up to three file names (assumed to be source, object, and listing file names respectively) can be given. A source file name is always required. If a switch is being given a value, that value must immediately follow the switch letter with no intervening spaces. For instance, to specify a page depth of 40 lines, the specification '-p40' should be used; '-p 40' will be rejected.

Switches perform the following actions:
-a
Causes all relocs to be emitted, even PC-relative relocs within a section. It also emits address differences in a special TIGCC/GCC4TI-specific format. This will allow more aggressive linker-side optimization.

-d
Causes symbol table entries (hunk_symbol) to be written to the object module for the use of symbolic debuggers. If the switch is followed by a string of characters, only those symbols beginning with that prefix string will be written. This can be used to suppress internal symbols generated by compilers. If the first character is an exclamation mark ('!'), only symbols which do not begin with the following characters are written out. Here are some examples:

-d | writes all symbols
-dabc    | writes only symbols beginning with "abc"
-d!x | writes symbols which do not begin with "x"

-e
Causes an equate file (see above) to be produced. A file name can be specified; otherwise a default name will be used.

-f
Causes any branches (Bcc, BRA, BSR) that could be converted to short form to be flagged. A68k will convert as many branches as possible to short form (unless the '-n' switch is is specified), but certain combinations of instructions may set up a ripple effect where shortening one branch brings another one into range. This switch will cause A68k to flag any branches that it may have missed; during pass 2 it is possible to tell this, although during pass 1 it might not be. If the '-n' switch (see below) is specified along with this switch (suppressing all optimization), no branches will be shortened, but all branches which could be shortened will be flagged.

-g
Causes any undefined symbols to be treated as if they were externally defined (XREF), rather than being flagged as errors.

-h
Causes a header file to be read prior to the source code file. A file name must be given. The action is the same as if the first statement of the source file were an INCLUDE statement naming the header file. To find the header file, the same directories will be searched as for INCLUDE files (see the '-i' switch below).

-i
Specifies directories to be searched for INCLUDE files in addition to the current directory. Several names, separated by commas, may be specified. No embedded blanks are allowed. For example, the specification
-imylib,df1:another.lib
will cause INCLUDE files to be searched for first in the current directory, then in "mylib", then in "df1:another.lib".

-k
Causes the object file to be kept even if any errors were found. Otherwise, it will be scratched if any errors occur.

-l
Causes a listing file to be produced. If you want the listing file to include a symbol table dump and cross-reference, use the '-x' switch instead (see below).

-m
Changes the assumed offset from the start of the DATA/BSS section to the base register used when the small code/data option is activated by the NEAR directive. If this parameter is not specified, the offset defaults to 32768.

-n
Causes all object code optimization (see above) to be disabled.

-o
Allows the default name for the object code file (see above) to be overridden.

-p
Causes the page depth to be set to the specified value. This takes the place of the PLEN directive in the Metacomco assembler. Page depth defaults to 60 lines ('-p60').

-q
Changes the interval at which A68k displays the line number it has reached in its progress through the assembly. The default is to display every 100 lines ('-q100'). Specifying larger values reduces console I/O, making assemblies run slightly faster.

If you specify a negative number (e.g. '-q-10'), line numbers will be displayed at an interval equal to the absolute value of the specified number, but will be given as positions within the current module (source, macro, or INCLUDE) rather than as a total statement count - the module name will also be displayed.

A special case is the value zero ('-q0' or just '-q') - this will cause all console output, except for error messages, to be suppressed.

(TIGCC/GCC4TI) -r
Allows to disable specific optimizations:
-rm Disable the MOVEM -> MOVE optimization
-ra Disable the ADD(A)/SUB(A) -> LEA optimization
-rl Disable the LEA -> ADDQ/SUBQ optimization
You might use more than one -r switch (as in "-rm -ra") or combine them into a single switch (as in "-rma").

-s
Causes the object file to be written in Motorola S-record format, rather than AmigaDOS format. The default name for an S-record file ends with '.s' rather than '.o; this can still be overridden with the '-o' switch, though.

-t
Allows tabs in the source file to be passed through to the listing file, rather than being expanded. In addition, tabs will be generated in the listing file to skip from the object code to the source statement, etc. This can greatly reduce the size of the listing file, as well as making it quicker to produce. Do not use this option if you will be displaying or listing the list file on a device which does not assume a tab stop at every 8th position.

(TIGCC/GCC4TI) -u
Disables automatic alignment of DC.W, DC.L, DCB.W, DCB.L, DS.W, DS.L and code.

(TIGCC/GCC4TI) -v
Allows to set a variable in the command line (like -d with GCC). The variable will be a SET, not EQU variable. Syntax: "-v<name>[,<value>]" (without spaces, and without the quotes). Note that <value> can only be a NUMBER at the moment. (We might support symbols as values in a future version.) The default value of <value> is 1.

-w
Specifies the sizes of fixed memory areas that A68k allocates for its own use. You should normally never have to specify this switch, but it may be useful for tuning.

The first parameter gives the number of entries that the hash table (used for searching the symbol table) will contain. The default value of 2047 should be enough for all but the very largest programs. The assembly will not fail if this value is too small, but may slow down if too many long hash chains must be searched. The hashing statistics displayed by the '-y' switch (see below) can be used to tune this parameter. I've heard that you should really specify a prime number for this parameter, but I haven't gone into hashing theory enough to know whether it's actually necessary.

The second parameter of the '-w' switch specifies the size (in bytes) of the secondary heap, which is used to store nested macro and INCLUDE file information (see below). It defaults to 1024, which should be enough unless you use very deeply nested macros and/or INCLUDE files with long path names.

(TIGCC/GCC4TI) The default sizes are 4095,2048 in the Win32 (since v.2.71.F3a) and GNU/Linux (since v.2.71.F3c) versions.

You can specify either or both parameters. For example:

-w4093 | secondary heap size remains at 1024 bytes
-w,2000 | hash table size remains at 2047 entries
-w4093,2000    | increases the size of both areas

If you're really tight for memory, and are assembling small modules, you can use this switch to shrink these areas below their default sizes. At the end of an assembly, a message will be displayed giving the sizes actually used, in the form of the '-w' command you would have to enter to allocate that much space. This is primarily useful to see how much secondary heap space was used.

Note: All other memory used by A68k (e.g. the actual symbol table) is allocated as required (currently in 8K chunks).

-x
Works the same as '-l' (see above), except that a symbol table dump, including cross-reference information, will be added to the end of the listing file.

-y
Causes hashing statistics to be displayed at the end of the assembly. First the number of symbols in the table is given, followed by a summary of hash chains by length. Chains with length zero denote unused hash table entries. Ideally (i.e. if there were no collisions) there should be as many chains with length 1 as there are symbols, and there should be no chains of length 2 or greater. I added this option to help me tune my hashing algorithm, but you can also use it to see whether you should allocate a larger hash table (using the first parameter of the '-w' switch, see above).

-z
This switch was provided to help debug A68k itself. It causes A68k to list a range of source lines, complete with line number and current location counter value, during both passes. Lines are listed immediately after they have been read from the source file, before any processing occurs. Here are some examples of the '-z' switch:

-z | lists all source lines
-z100,200    | lists lines 100 through 200
-z100 | lists all lines starting at 100
-z,100 | lists the first 100 lines


Technical Information
Previous The A68k Assembler Next

The actual symbol table entries (pointed to by the hash table, colliding entries are linked together) are stored in 8K chunks which are allocated as required. The first entry of each chunk is reserved as a link to the next chunk (or NULL in the last chunk) - this makes it easy to find all the chunks to free them when we're finished. All symbol table entries are stored in pass 1. During pass 2, cross- reference table entries are built in the same group of chunks, immediately following the last symbol table entry. Additional chunks will continue to be linked in if necessary.

Symbol names and macro text are stored in another series of linked chunks. These chunks consist of a link pointer followed by strings (terminated by nulls) laid end to end. Symbols are independent entries, linked from the corresponding symbol table entry. Macros are stored as consecutive strings, one per line - the end of the macro is indicated by an ENDM statement. If a macro spans two chunks, the last line in the original chunk is followed by a newline character to indicate that the macro is continued in the next chunk.

Relocation information is built during pass 2 in yet another series of linked chunks. If more than one chunk is needed to hold one section's relocation information, all additional chunks are released at the end of the section.

The secondary heap is built from both ends, and it grows and shrinks according to how many macros and INCLUDE files are currently open. At all times there will be at least one entry on the heap, for the original source code file. The expression parser also uses the secondary heap to store its working stacks - this space is freed as soon as an expression has been evaluated.

The bottom of the heap holds the names of the source code file and any macro or INCLUDE files that are currently open. The full path is given. A null string is stored for user macros. Macro arguments are stored by additional strings, one for each argument in the macro call line. All strings are stored in minimum space, similar to the labels and user macro text on the primary heap. File names are pointed to by the fixed table entries (see below) - macro arguments are accessed by stepping past the macro name to the desired argument, unless NARG would be exceeded.

The fixed portion of the heap is built down from the top. Each entry occupies 16 bytes. Enough information is stored to return to the proper position in the outer file once the current macro or INCLUDE file has been completely processed.

The diagram below illustrates the layout of the secondary heap.

Heap2 + maxheap2 ----------->  ___________________________
                              |                           |
                              |   Input file table        |
struct InFCtl *InF ---------> |___________________________|
                              |                           |
                              |   Parser operator stack   |
struct OpStack *Ops --------> |___________________________|
                              |                           |
                              |   (unused space)          |
struct TermStack *Term -----> |___________________________|
                              |                           |
                              |   Parser term stack       |
char *NextFNS --------------> |___________________________|
                              |                           |
                              |   Input file name stack   |
char *Heap2 ----------------> |___________________________|
The "high-water mark" for NextFNS is stored in char *High2, and the "low-water mark" (to stretch a metaphor) for InF is stored in struct InFCtl *LowInF. These figures are used only to determine the maximum heap usage.


A68k Contact Information and Bug Reports
Previous The A68k Assembler Next

And Finally...

Please send me any bug reports, flames, etc. I can be reached on Mind Link (604/533-2312), at any meeting of the Commodore Computer Club / Panorama (PAcific NORthwest AMiga Association), or via Jeff Lydiatt or Larry Phillips. I don't have the time or money to live on Compuserve or BIX, but my Usenet address is Charlie_Gibbs@mindlink.UUCP (...uunet!van-bc!rsoft!mindlink!a218).

Charlie Gibbs
2121 Rindall Avenue
Port Coquitlam, B.C.
Canada
V3C 1T9

(GCC4TI) Since, as far as we can tell, Charlie Gibbs is no longer maintaining A68k since 1991, you are better off filing a bug report to the GCC4TI project: http://trac.godzil.net/gcc4ti/


History of A68k
Previous The A68k Assembler

Note: This section has been added to the documentation by the TIGCC Team. It was in history.txt before.

Version 2.71.F3z (Lionel Debroux, July 29, 2009)

  • Bugfix: Fix moveq #$FFFFFFFE,dn on 64-bit platforms.
Version 2.71.F3y (Patrick Pelissier, June 27, 2009)
  • Improved: the maximum length of a line has been raised from 256 to 65536.
  • Bugfix: don't compile A68k statically, as it fails on multiple platforms in their out of the box configuration (Lionel Debroux).
Version 2.71.F3x (Manoel Trapier, December 23, 2008)
  • Added: OS X Makefile that generate an Universal Binary version.
Version 2.71.F3w (Kevin Kofler, July 27, 2006)
  • Bugfix: Fixed compilation on *BSD and recent versions of OS X.
Version 2.71.F3v (Kevin Kofler, July 31, 2005)
  • Bugfix: Don't crash on EQUs doing arithmetic with other EQUs which do arithmetic with undefined symbols, print an error instead.
Version 2.71.F3u (Kevin Kofler, February 2, 2005)
  • Bugfix: Fixed compilation with GCC 3.4.
Version 2.71.F3t (Kevin Kofler, January 31, 2005)
  • Added: NO_UNOPTIMIZABLE_RELOCS compile-time define (disabled by default) to allow generating AmigaOS-compatible object files again.
  • Improved: Branches explicitly coded as .w are now marked unoptimizable.
  • Improved: Label references explicitly coded as .l are now marked unoptimizable.
  • Bugfix: Emitting relocations for undefined symbols which are already in the symbol table due to the forward branch optimization code now works properly.
Version 2.71.F3s (Kevin Kofler, September 21, 2004)
  • Added: Support for the "unoptimizable reloc" flag, keeping the linker from corrupting some instructions when optimizing.
  • Improved: All platforms now use the same maximum line length and chunk sizes.
  • Improved: The line count limit has been raised from 32767 to INT_MAX.
Version 2.71.F3r (Kevin Kofler, July 19, 2004)
  • Bugfix: Fixed label(PC,Rn) addressing when "label" was in a different section (again) (reported by Julien Moutinho).
Version 2.71.F3q (Kevin Kofler, December 30, 2003)
  • Bugfix: Fixed label1-label2(an) in all-relocs mode (reported by hwti).
  • Added: (In all-relocs mode,) don't emit an address difference when the 2 labels are actually at the same address (or simply the same). This allows to keep optimizing label1-label1(an) into (an).
  • Bugfix: Fixed a bug when range-checking branches in all-relocs mode (reported by hwti).
  • Bugfix: Fixed a bug when range-checking short branches in all-relocs mode or to a different section (reported by hwti).
Version 2.71.F3p (Kevin Kofler, December 1, 2003)
  • Bugfix: Fixed label(PC,Rn) addressing in all-relocs mode or when "label" was in a different section (reported by Matthieu Gallet).
Version 2.71.F3o (Kevin Kofler, October 5, 2003)
  • Bugfix: Range checking now works correctly in all-relocs mode. (No more spurious out-of-range errors.)
Version 2.71.F3n (Kevin Kofler, September 28, 2003)
  • Bugfix: Local labels now work in all-relocs mode.
Version 2.71.F3m (Kevin Kofler, September 2, 2003)
  • Bugfix: PC-relative or indexed references to other sections didn't work.
  • Bugfix: x(PC,Dn) or x(PC,An) didn't work in all-relocs mode.
Version 2.71.F3l (Kevin Kofler, July 15, 2003)
  • Added: The -u switch now also allows unaligned code, which can be useful when the code will be copied somewhere else anyway.
  • Added: Short branches across hunks or object files are now allowed.
  • Added: -a (All relocs) switch, which tells A68k to emit all relocs, even PC-relative relocs within a section. It also emits address differences in a special TIGCC-specific format. This will allow more aggressive linker-side optimization.
Version 2.71.F3k (Kevin Kofler, May 17, 2003)
  • Bugfix: Increased the forward reference buffer in order to allow multiple labels at the same location, as used in PedroM.
  • Added: -u (Unaligned) switch, which disables automatic alignment of DC.W, DC.L, DCB.W, DCB.L, DS.W and DS.L.

Version 2.71.F3i (Kevin Kofler, February 1, 2002)
  • Bugfix: Local labels caused a "Pass 1 / Pass 2 phase error" when preceded by an include file which contained labels, but was skipped in pass 2 (such as OS.h).

Version 2.71.F3h (Kevin Kofler, January 23, 2002)
  • Bugfix: The TITLE (or TTL) directive did not work at all. It now works as it is supposed to.
  • Bugfix: No longer crashes when trying to generate a listing file with cross-references (using the -x switch).

Version 2.71.F3g (Kevin Kofler, January 22, 2002)
  • Bugfix: The RORG and PUBLIC directives are now recognized correctly even if the first letter is not capitalized. Thanks to Brandon Sterner for reporting the problem with the RORG directive.

Version 2.71.F3f (Kevin Kofler, January 8, 2002)
  • Now also accepts ";", and for the -v switch also "=", as separator in command line arguments (wherever "," is allowed), for compatibility with the "-WA," switch in tigcc.

Version 2.71.F3e (Kevin Kofler, August 3, 2001)
  • Bugfix: The SUB->LEA optimisation did not change the sign of the immediate value.

Version 2.71.F3d (Kevin Kofler, July 28, 2001)
  • Bugfix: The ADD(A)/SUB(A)->LEA and LEA->ADDQ/SUBQ optimizations caused "Pass 1 / Pass 2 phase errors" if an optimization was known to be possible only in pass 2 (i.e. if using forward references to labels in the instruction). A68k will not try to optimize those anymore. Maybe a future version will provide support for this kind of optimization, but it is very difficult to implement.
  • Bugfix: A68k did not compile correctly on Visual C++ because I had done a define in an incorrect way.

Version 2.71.F3c (Kevin Kofler, July 20, 2001)
  • Applied a few patches submitted by Paul Froissart:
    • A few more adaptations for compiling with Microsoft Visual C++. (Note that I still recommend using GCC for Mingw32.)
    • A new command line switch:
      -v
      Allows to set a variable in the command line (like -d with GCC). The variable will be a SET, not EQU variable. Syntax: "-v<name>[,<value>]" (without spaces, and without the quotes). Note that <value> can only be a NUMBER at the moment. (We might support symbols as values in a future version.) The default value of <value> is 1.
    • Improved the optimization:
      • made optional the optimization which changes MOVEM with a single register to MOVE
      • added an optional optimization which changes ADD(A) and SUB(A) to LEA when applicable
      • added an optional optimization which changes LEA to ADDQ or SUBQ when applicable
      • added a command line switch which allows you to selectively disable some optimizations:
        -r
        Allows to disable specific optimizations:
        -rm | Disable the MOVEM -> MOVE optimization
        -ra | Disable the ADD(A)/SUB(A) -> LEA optimization
        -rl | Disable the LEA -> ADDQ/SUBQ optimization
        You may use more than one -r switch (as in "-rm -ra") or combine them into a single switch (as in "-rma"). You can still use -n to disable ALL optimizations (even those not covered by -r).
    • Added 2 more synonyms:
      • SLO = SCS
      • SHS = SCC
    • The END directive is now optional. If you do not use it, the assembly will automatically end at the end of your source file.
  • Also fixed a bug found by Paul Froissart involving the reporting of invalid flags with the SECTION directive. (Not that anyone would use those flags anyway.)
  • Adapted and applied a very old patch by John Antonishek, which allows you to define a symbol as XDEF even if it has been declared as XREF before. This is especially useful when using a common include file for globals.
  • Moreover, END is not allowed in macros or include files anymore since that was causing a few bugs because A68k simply did not expect anyone to use it there. The quickest remedy is to simply remove the END instruction, since it is now optional anyway.

Version 2.71.F3b (Kevin Kofler, July 12, 2001)
  • Bugfix: Now raises an error if an undefined local label is used.
  • Bugfix: Branches coded with an explicit length (.W or .L) are not optimized (or flagged as optimizable) anymore.
    (In previous versions, .B or .S was not optimized, but .W or .L could be optimized to a short branch. Now, only branches without an explicit length will be optimized.)
  • Bugfix: Quoted strings can now be passed as macro arguments without the need for '<' and '>', even if they contain spaces or separators (',' or ';'). You can still use '<' and '>', for example in order to pass strings like <129,' version'> (which will appear as "� version" on a TI-89/92/92+).

Version 2.71.F3a (Kevin Kofler, July 9, 2001)
  • Win32 port for the TIGCC project, compiled with GCC for Mingw32.
    Even though we recommend Mingw32, A68k should also compile with Microsoft Visual C++, thanks to Paul Froissart. (Please do NOT ask me questions about compiling with Visual C++. I have just put in Paul Froissart's ifdefs.) It also compiles with Cygwin, but since the result is larger than the Mingw32 version, I do not see any benefit in using it.
  • Bugfix: My Win32 port of v.2.71.F3 did not support labels or variable names which contain accented characters.
  • Bugfix: Now detects all errors in include files. All include files will be treated in pass 2 if an error is detected.
  • Bugfix by Paul Froissart: fixed a random crash bug due to a missing initialization
  • Bugfix by Julien Muchembled: allow odd displacements for words and longwords if the resulting address might be even
  • The Win32 version is now less greedy with the memory, so its limitations are less annoying:
    • lines can now be 256 bytes long (Paul Froissart)
    • filenames (with path) can now be 259 bytes long (the Win32 maximum)
    • the default heap sizes have also been increased (Paul Froissart)
  • Added the following synonyms:
    • BLO = BCS
    • BHS = BCC
    • DBLO = DBCS
    • DBHS = DBCC
    • ROLX = ROXL
    • RORX = ROXR

Version 2.71.F3 (David Ellsworth, July 11, 2000)
  • Fixed a bug introduced by my modifications that prevented branches from being optimized in Global XRef mode.

Version 2.71.F2 (David Ellsworth, January 22, 1998)
  • Made A68k properly differentiate between PC-relative and absolute references to external symbols. Allowed branches to reference external labels in Global XRef (-g parameter) mode.

Version 2.71.F1 (David Ellsworth, January 7, 1998)
  • Made changes so that combinations of EQU, XREF, and XDEF directives work better together. These changes were made in order for Fargo II library linking to be easier to do.
  • The F1 stands for Fargo patchlevel 1.

Version 2.71 (Charlie Gibbs, April 16, 1991)

The following bugs in version 2.62 have been corrected:
  • Enforcer checks were being generated if command-line parameters that took a numeric value had no value or the value was invalid. CalcValue was attempting to look up a label in the symbol table, which having not been allocated yet was causing a null pointer to be dereferenced. (Patrick Quaid)
The following enhancements have been added:
  • Function prototyping has been added. All function prototypes are in a new include file, protos.h, which is included by A68kdef.h. Prototyping can be disabled (for compilers which do not support it) by defining the symbol __NOPROTO; in this case old-style function declarations are generated instead.

Version 2.70 (Charlie Gibbs, February 25, 1991)

The following bugs in version 2.62 have been corrected:
  • The definition of tempstr in WriteSymTab (24 bytes) was being overrun in some cases, causing A68k to hang. Its length has been increased to MAXLINE. (Paul Gittings, John Antonishek)
  • If A7 was in a list of registers in the source operand of a MOVEM instruction, all registers would be moved (i.e. the mask was set to 0xFFFF). (Risto Kaivola)
  • Octal or binary values that set bit 31 were being flagged as overflow errors. (Harvey Taylor)
  • ORGs were unnecessarily restricted when the -s flag was specified. Everything should be absolute when S-records are generated, and any absolute ORG should be allowed.
The following enhancements have been added:
  • A new INCBIN directive has been added. It takes a single operand, a file name whose contents are included as is at the current position in the object code file. (Julian Gold, Colin Fox)
  • The opcode TTL is now accepted as a synonym for TITLE.
  • The file mode in the creat() call in xopen() has been changed from 1 to 0644; this provides a reasonable file mode when compiled on a Unix system. (Paul Gittings)
  • A new command-line keyword (-g) has been added. It causes all undefined symbols to be treated as XREF. (Paul Gittings, Steve Hawtin (who provided the code))
  • All initialized fields in opcodes.c have been made global for compatibilty with more compilers. (Steve Hawtin)
  • The register list in a MOVEM instruction can now be an immediate operand which specifies the actual mask bits. (Paul Gittings, who provided the code)
  • The default value for the -q option has been changed from 10 to 100.

Version 2.62 (Charlie Gibbs, March 19, 1990)

The following enhancements have been added:
  • A new command-line keyword (-m) has been added. It must be immediately followed by a number which specifies the offset from the beginning of a small data section to the base register specified in the NEAR directive (defaulting to A4). If this parameter is omitted, the offset defaults to 32768 bytes. This parameter is meaningful only if the NEAR directive is used. (Colin Fox)

Version 2.61 (Charlie Gibbs, January 11, 1990)

The following bugs in version 2.6 have been corrected:
  • ORG and RORG at the beginning of the program were being processed incorrectly. (Jukka Jarvinen)
  • A branch instruction to its own label, e.g.
    lab	bra	lab
    would cause phase errors; the instruction was being shortened on pass 2 but not on pass 1. (Kevin Hoare)
The following enhancements have been added:
  • Labels may begin with '@' if the next character is not numeric (to avoid confusion with octal constants). (Colin Fox)
  • Write errors now cause A68k to terminate gracefully with an appropriate error message.

Version 2.6 (Charlie Gibbs, November 2, 1989)

The following bugs in version 2.5 have been corrected:
  • If a space is left between a file keyword and the file name (e.g. A68k -l foo.lst foo.asm) the source file was scratched. (E. Lenz)
  • All code using post-increment addressing in references to toupper() has been reworked to avoid post-increment. Such code does not work correctly if toupper() is a macro. (John K. Antonishek)
  • The spelling of the include files A68kdef.h and A68kglb.h has been made correct as to case. This simplifies porting to case-sensitive file systems. (John K. Antonishek)
  • If comments immediately follow the operands of an XDEF, XREF, or PUBLIC statement with no intervening white space (as in any of the following statements), A68k would hang:
        XDEF	foo;comments
    XREF	bar;comments
    PUBLIC	blah;comments
    (Bruce Dawson)
  • Numeric values (any radix) which do not fit into 32 bits were not being flagged. (E. Lenz)
  • DC statements with no operands were not being flagged. (E. Lenz)
  • The -f option was suggesting short branches where the displacement would be zero, which is illegal. (E. Lenz)
  • Branches outside the current section had the offset set to zero. (Matt Dillon, who provided a fix)
  • ADDI, ANDI, CMPI, EORI, ORI, and SUBI instructions whose source operand was not immediate were not being flagged. (E. Lenz)
  • Unary NOT of a byte or word immediate operand whose value was negative was being flagged as a size error. (John Aycock)
  • All forward branches were rejected when the NEAR directive was active. (Colin Fox)
The following enhancements have been added:
  • Single-byte immediate operands (e.g. MOVE.B #-1,(a0)) are now padded with a high-order byte of zero, rather than being sign-extended. (E. Lenz)
  • The message "Error in operand format." has been changed to "Addressing mode not allowed here." in places where the latter message is more appropriate.
  • If the -q option species a value of zero (or no value is given, defaulting to zero), all console output will be suppressed except for error messages, if any. (Matt Dillon)
  • The 128-byte restriction on constant length no longer applies to the entire code generated by a single DCB statement; statements such as
        DCB.L	64,0
    can now be handled. (Colin Fox)
  • Forward branches are now optimized. The occasional instruction may be missed due to ripple effects, but this shouldn't happen frequently. The -f switch will flag any such instructions.
  • The -d switch can now be followed by an optional prefix string (with or without a leading !) which specifies which symbols should or should not be included in the symbol table dump. (Lionel Hummel)

Version 2.5 (Charlie Gibbs, June 18, 1989)

The following bugs in version 2.42 have been corrected:
  • Upon normal termination, A68k occasionally crashed in quit_cleanup by trying to free the relocation table twice. (Jeff Lydiatt and D. McClelland, who worked out a fix)
  • MEMF_CHIP and MEMF_FAST bits were being set in the hunk length, rather than in the hunk type. (Richard Man)
  • BCHG.L, BCLR.L, BSET.L, and BTST.L were causing phase errors. The test to ignore the .L specification (added in version 1.21) was being skipped in pass 1 by an optimization added in version 2.4. (David Hankins)
  • PC-relative offset to a label was calculated as two bytes too great for MOVEM instructions. (Tony Parkhurst)
The following enhancements have been added:
  • If the length code on an opcode is not .B, .W, .L, .S, or omitted, it will be flagged as an error.
  • JMP.S and JSR.S are flagged as errors. (Jim Butterfield)
  • Operands of the form (xxxx).W and (xxxx).L are now supported. This enables absolute short or absolute long addressing to be explicitly specified.
  • All optimization can be disabled by the new -n switch. (David Hankins)
  • The NEAR directive can now take a single operand, which can be any address register (or equated symbol) except A7. If omitted, the register defaults to A4.
  • Instructions of the form BTST Dn,#nn are no longer flagged. This obscure variant is nonetheless legal.

Version 2.42 (Charlie Gibbs, January 10, 1989)

The following bugs in version 2.41 have been corrected:
  • Small code/data conversion was sometimes taking place when no NEAR directive was active. (Jeff Lydiatt)

Version 2.41 (Charlie Gibbs, January 6, 1989)

The following bugs in version 2.4 have been corrected:
  • The second operand of LINK instructions was being erroneously flagged.
  • If a macro was used before it was defined, it was being expanded during pass 2 but not during pass 1, causing severe phase errors. Attempts to use a macro before it is defined will now be flagged as invalid opcodes. (Colin Fox)

Version 2.4 (Charlie Gibbs, January 4, 1989)

The following bugs in version 2.31 have been corrected:
  • If comments immediately followed the operands of a DC statement with no intervening white space, A68k would hang. (Ulf Nordquist)
  • In the following command:
    a68k -w 15000 myprog.asm
    the space between the -w and 15000 would cause A68k to look for a source file called "15000", and to think that the object file is to be called "myprog.asm". When it can't find "15000" it would display an error message and scratch "myprog.asm". (Jeff Lydiatt)
  • If an INCLUDE file that is skipped on pass 2 contains a macro call, subsequent uses of \@ (macro sequence number are subsequently flagged. The macro counter must be bumped along with the line number when skipping an INCLUDE. (Colin Fox, Harvey Taylor)
The following enhancements have been added:
  • ORG and RORG are now fully implemented.
  • The SET symbols A68k, a68K, and a68k are defined in the same way as A68K, making it effectively case-insensitive. (Colin Fox)
  • MOVEM and REG now accept equated register names (EQUR) in register lists. (Bruce Dawson)
  • INCLUDE files will now be skipped on pass 2 even when a listing file is requested, if the listing has been turned off by a NOLIST directive before the INCLUDE, and is not turned on until after the end of the INCLUDE file has been reached. (Colin Fox)
  • A new switch (-f) causes forward branches (Bcc, BRA, BSR) that could be coded as short branches (Bcc.S etc.) to be flagged. This flag is not considered to be an error.
  • A limited small code / small data model has been provided. It is activated by a NEAR directive in the source code, and is de-activated by a FAR directive. External variables must be declared at the beginning of the program, which must consist of only two sections (CODE and DATA or BSS). All forward data references are assumed to be PC-relative if in the CODE section, A4-relative if in the DATA/BSS section, and absolute word if absolute values. Any forward references which cannot be resolved to one of these three in pass 2 will be flagged as errors, as will any attempt to define more than two sections. A4 is assumed to point to the start of the DATA/BSS section plus 32768 bytes, and must be loaded by a MOVE.L instruction using immediate mode unless this instruction is not enclosed within NEAR and FAR directives.
  • Miscellaneous optimizations, for speed, including: Most of the object code generator in pass 1 is bypassed. If GetValue gets a single term it takes a short cut. IsOperator now uses a table look-up. Instructions now only searches that portion of the opcode table whose opcodes start with the same letter as the OpCode being searched for.

Version 2.31 (Charlie Gibbs, November 30, 1988)

The following bugs in version 2.3 have been corrected:
  • Even though a macro definition was being skipped by IFxx/ENDC, its ENDM directive was still being detected, causing spurious diagnostics. (Harvey Taylor)
  • NOP was not being recognized. When moving all directives into the opcode table, NOL and NOLIST were placed after NOP, rather than before. (Colin Fox)
  • Symbols defined in the current module and declared as PUBLIC were not being written to the object code file when -d was specified. (Colin Fox)
  • Conversion of 0(An) to (An) (implemented in version 1.2) was causing errors in the MOVEP instruction, which requires a displacement even if it is zero. This conversion is now disabled for MOVEP instructions.
  • User macros containing invalid opcodes caused A68k to get lost when returning to the outer source file. (Colin Fox)
  • Large values of -w (over 6000 or so) would cause a visit from the Guru. The work field in HashIt was overflowing and going negative. Changing it to unsigned corrected the problem. (Colin Fox)
  • Although user macros are no longer displayed when -q is a negative number, the calling file's name was still being displayed at the end of the macro.

Version 2.3 (Charlie Gibbs, November 21, 1988)

The following enhancements have been added:
  • All file I/O has been rewritten to use level 1 I/O (open, creat, close, read, write, and lseek) instead of level 2 I/O. A68k now does its own buffering and unbuffering to reduce system overhead and increase speed. (Bruce Dawson)
  • All assembler directives have been incorporated into the opcode table. Since the opcode search now looks up directives as well, speed is increased.
  • Miscellaneous code optimization for additional speed.

Version 2.2 (Charlie Gibbs, November 4, 1988)

The following bugs in version 2.1 have been corrected:
  • Macro definitions within an INCLUDE file were disabling the test for skipping the file on pass 2.
  • Errors encountered in an INCLUDE file on pass 1 were not disabling the skip of the file on pass 2 - the pertinent error messages could not appear.
  • XDEF information and optional symbol table dumps were not being written to the object code file for any hunks that did not contain relocatable code or data. (Colin Fox)
The following enhancements have been added:
  • If the -q option is specified as a negative value, user macros are no longer included in line number displays, reducing clutter.
  • Some source code has been re-arranged to reduce size.

Version 2.1 (Charlie Gibbs, November 1, 1988)

The following bugs in version 2.00 have been corrected:
  • Macro definitions that span two chunks of memory were causing garbage and probably a crash when the macro was being expanded. Pointers were not being handled properly when linking the two chunks.
  • Statements such as EQU and SET were not being flagged as illegal forward references if referencing a label defined on the same line, e.g.
    LABEL	SET	LABEL+1
  • The position within macros and INCLUDE files was sometimes out by one line when reported in error messages (and the new feature of the -q switch).
The following enhancements have been added:
  • If the -q option is specified as a negative value, line numbers will be displayed as positions within the current module (whose name is also displayed), rather than a total statement count. (Bruce Dawson)
  • INCLUDE files can be skipped on pass 2 even if they contain SET statements - the values of all symbols SET in the INCLUDE file are stored (as at the end of the file) in a separate table and are patched when the INCLUDE file is skipped. (Bruce Dawson)

Version 2.00 (Charlie Gibbs, October 26, 1988)

The following bugs in version 1.24 have been corrected:
  • The last digit of the statement number display (lengthened in version 1.24) was not being erased before displaying error messages.
  • A68k would go into a loop if a user macro was missing an ENDC directive. This error is now flagged (see below).
The following enhancements have been added:
  • The highest statement number displayed at the end of each pass is now left on the screen. This means that, at the end of pass 1, you can always see how many lines A68k will have to process in pass 2, giving an idea of how how much longer you have to wait. (Colin Fox)
  • The symbol table is now built using a hashing algorithm. This eliminates the slowdown that occurs in pass 1 as the symbol table grows, due to the old insertion process. (Bruce Dawson)
  • If A68k terminates abnormally for any reason (such as insufficient memory) the object file is scratched (unless the -k option is set). (Bruce Dawson)
  • Any INCLUDE files which cannot be found are flagged as errors in pass 1, and the assembly is aborted at the end of pass 1. (Bruce Dawson)
  • Missing ENDC directives are flagged in macro expansions. Also, missing or unpaired ENDC directives in user macros are flagged.
  • If an INCLUDE file doesn't generate any code and no listing file is required, it won't be read again in pass 2. The statement numbers will be bumped to keep in proper alignment. This can really speed up assemblies that INCLUDE lots of equates. (Colin Fox)

Version 1.24 (Charlie Gibbs, October 11, 1988)

The following bugs in version 1.23 have been corrected:
  • MOVEA to a data register was not being flagged, even though all other invalid addressing modes were.
  • Attempts to ORG out of the current hunk (including to an absolute address) were not being flagged. (E. Lenz)
  • If the size of the bottom of the primary heap (symbols and macro text) exceeded 32K, any further macro definitions would expand as endless garbage. (Colin Fox)
  • If the size of the bottom of the primary heap (symbols and macro text) exceeded 64K, any further external symbols (XDEF) would be flagged as relocatability errors upon each reference. (Colin Fox)
The following enhancements have been added:
  • Where statement numbers are displayed as fixed-length fields, their maximum length has been increased from 4 digits to 5. (Colin Fox)
  • The PUBLIC directive has been implemented. As with the Aztec assembler, any labels defined as PUBLIC will be treated as XDEF if defined within the current module, and XREF otherwise. (Jeff Lydiatt)

Version 1.23 (Charlie Gibbs, September 20, 1988)

The following bugs in version 1.22 have been corrected:
  • The test for a third operand was producing erroneous error messages on instructions whose second operand was in immediate mode. The '#' was not being taken into account, since it is not copied to DestOp.

Version 1.22 (Charlie Gibbs, August 31, 1988)

The following bugs in version 1.21 have been corrected:
  • Expressions of the form R-A, where R is a relocatable term or expression and A is an absolute term or expression, were being flagged as relocation errors. This was due to a bug in the routine which should (but did not) flag expressions of the form A-R. (David Ashley)
  • Instructions with three operands were not being flagged as errors. This can be caused by an extra comma being typed in the instruction, as in:
        BTST #0,state+3,(a5)
    The second comma should not be present. (David Ashley)
The following enhancements have been added:
  • Excess spacing has been removed from the listing file. These changes are similar to those already made to the console output (probably at about version 1.05).
  • If the first statement in the source file is TTL or PAGE, an empty page is no longer produced at the start of the listing.

Version 1.21 (Charlie Gibbs, July 29, 1988)

The following bugs in version 1.2 have been corrected:
  • The instruction
        BTST.L	#8,D0
    had a long-word value generated for the bit number. This bug also applies to BSET, BCLR, and BCHG. The .L specification is now ignored. (Ulf Nordquist)

Version 1.2 (Charlie Gibbs, July 19, 1988)

The following bugs in version 1.12 have been corrected:
  • A reference to the label of the current instruction was being converted to PC-relative on pass 2 but not on pass 1. This was causing phase errors. The label hasn't been added to the symbol table at the time the instruction is processed. Conversion to PC-relative addressing will now not be attempted in this case, although references to * can and will be converted.
  • All string-type DC statements, regardless of length, were being treated as DC.B. For example, DC.L 'A' would generate only one byte of object code. (Gerald Hull)
  • DC.W and DC.B statements were not being checked to ensure that their values would fit into a word or a byte respectively.
  • If a comment line had white space preceding the asterisk, A68k would hang. Actually, it was interpreting the asterisk as an opcode and trying to open a macro file called "*". Since under AmigaDOS such a file is the console, A68k was actually waiting for console input.
  • If an instruction with no operands (such as RTS or NOP) followed MOVE.L #rel,D0 where "rel" was a relocatable symbol, the RTS (etc.) would have its nonexistent operands flagged as invalid.
  • SECTION names enclosed in quotes were not being handled correctly.
  • Source modules that did not generate any code, data, or BSS areas, but only defined symbols, such as
    label	equ	4
    xdef	label
    end
    were generating incomplete object modules.
The following enhancements have been added:
  • Jeff's experimental hunk code (prefixing hunk names with a sequence number before adding to the symbol table) has been permanently incorporated. It seems to work better with BLink on programs that have hunks continued farther on in the source code. (Jeff Lydiatt)
  • The macro parameter \0, which is replaced by the size specification in the macro call (B, W, or L, defaulting to W) is now supported. (Gerald Hull)
  • Operands of the form 0(An) will be treated as (An). (Bruce Dawson)

Version 1.12 (Charlie Gibbs, May 25, 1988)

The following bugs in version 1.11 have been corrected:
  • If an instruction with no operands (e.g. RTS) followed a MOVE.L #label,D0 the RTS would be flagged with a relocatability error. Src.Mode and Dest.Mode were not being cleared. (Colin Fox)

Version 1.11 (Charlie Gibbs, April 6, 1988)

The following bugs in version 1.10 have been corrected:
  • A68k would go into a loop while processing the arguments of a macro call, if these arguments are followed by comments separated from the arguments by one or more tab characters, and the -t switch is specified on the command line. All tests for blanks have been replaced by calls to isspace().
  • The operand alignment checks added in version 1.06 were erroneously testing the following instructions:
    • BCHG
    • BCLR
    • BSET
    • BTST
    • NBCD
    • Scc
    • TAS
    These instructions are now exempt from alignment checking.
The following enhancements have been added:
  • A listing file name can now be specified with the -x switch; it is no longer necessary to specify both the -l and -x switches to produce a cross- reference listing with a name other than the default.
  • DS statements with more than one operand are flagged and ignored (in case they should be DC).
  • A character string used as a numeric value is flagged and set to zero if it is more than four characters long.

Version 1.10 (Charlie Gibbs, March 20, 1988)

The following bugs in version 1.07 have been corrected:
  • BSS sections were not being written to the object code file except for a BSS section at the end of a program. This is due to a bug in the code added in version 1.05 to overwrite null sections.
  • If a source module contained a mixture of lengths (8, 16, or 32 bits) in external references (XREF) to the same label, all references were being treated as if they has the length of the first reference.
The following enhancements have been added:
  • DS operands that are either a forward references or relocatable are now flagged.
  • Short branches (Bcc.S, including BRA and BSR) to the next instruction (i.e. a displacement of zero) are illegal - the processor takes the displacement from the next word. Attempts to generate a short displacement of zero are now flagged.

Version 1.07 (Charlie Gibbs, March 11, 1988)

The following bugs in version 1.06 have been corrected:
  • Instructions that take no operands (such as RTS) were being flagged if they had comments that were not preceded by a semicolon.
The following enhancements have been added:
  • The following synonyms have been added:
    CSEG  for CODE (Aztec compatibility)
DSEG  for DATA    "          "
ENDIF for ENDC (Assempro compatibility)
=     for EQU      "           "
|     for !        "           "
  • Strings and character values may be delimited by either apostrophes (') or quotation marks ("). The character not used as a delimiter can be used within the string without doubling it. For example,
      DC.B	"This is Charlie's assembler"
    produces the same code as
      DC.B	'This is Charlie''s assembler';
  • The object code file will be scratched if any errors were found, unless the -k (keep) flag is set. (Bruce Dawson)
  • The symbol .A68K is automatically defined at the beginning of each assembly as a SET symbol with an absolute value of 1. This enables programs to check whether they're being assembled by this assembler. (Jeff Lydiatt)
  • The symbol table insertion routine has been greatly speeded up.

Version 1.06 (Charlie Gibbs, March 6, 1988)

The following bugs in version 1.05 have been corrected:
  • Lines skipped by IFxx/ENDC were not being counted in the line number given in error messages.
  • DATA and BSS sections may be unnamed, or have names the same as CODE sections. Honest, I thought section names had to be unique even across types.
  • CHIP and FAST options on the CODE, DATA, and BSS synonyms for the SECTION directive were not being handled correctly.
  • XDEF records and symbol table records (if desired) were not being produced for symbols defined ahead of the first object-code producing instruction.
The following enhancements have been added:
  • The CNOP instruction can now force alignment relative to any boundary up to 128 bytes. The second operand must still be a power of 2.
  • The -q switch has been added to change the frequency with which progress reports (current line number) are displayed on the console. The default remains at every 10 lines (-q10). If you specify -q (no interval) or -q0 the line number displays will be suppressed. This will make assemblies run slightly faster due to reduced console I/O. (Bill Henning)
  • The -t switch has been added to keep any tabs in the source file when producing the listing file, as well as generating tabs elsewhere whenever possible. This speeds up assemblies and gives smaller listing files, but such listing files cannot be displayed on devices that do not assume a tab stop in every 8th position. (Bruce Dawson)
  • Any single-operand instruction with two operands, and any no-operand instruction with any operands, will be flagged.
  • Relocatable 8- or 16-bit immediate operands will be flagged. They blow up BLink.
  • Named local labels are now supported. Their names are formed in the same way as normal labels, but are then preceded by a backslash. Their scope is the same as normal local labels (nnn$). (Colin Fox)
  • An alignment error will be flagged in the following cases:
    • Odd displacement on a LINK instruction
    • Bcc or DBcc to an odd address
    • In any word or long-word instruction, any operand using the following addressing modes:
      • Address register indirect with displacement
      • Address register indirect with index and displacement
      • Absolute short
      • Absolute long
      • Program counter indirect with displacement
      • Program counter indirect with index and displacement
    • LEA and PEA instructions are exempt from these tests.
  • If a section is found to contain no data, A68k will back up to its beginning and overwrite it with the next section. The result is that null sections will no longer appear in the object file.

Version 1.05 (Charlie Gibbs, October 30, 1987)

The following bugs in version 1.04 have been corrected:
  • If a section was continued later in the program, e.g.
        SECTION	prog,CODE
      <code>
    SECTION	variables,BSS
      <DS statements>
    SECTION	prog,CODE
      <more code>
    bad relocation information was being generated for the continuation of the SECTION. This bug was left over from version 1.03.
The following enhancements have been added:
  • All console output except for error messages is now sent to stderr - this enables stdout to be redirected, producing an error file.
  • Console (stderr) output has been modified to require fewer lines on the screen.
  • If an error occurs while expanding a macro or INCLUDE file, the position of the call in each outer file is given along with the position in the current (innermost) file. Tracing continues until the outermost file (i.e. the original source file) is reached.

Version 1.04 (Charlie Gibbs, October 21, 1987)

The following bugs in version 1.03 have been corrected:
  • MOVE was being converted to MOVEQ regardless of operand size - this conversion is legal only for longword MOVEs.
  • Modifications to version 1.03 caused bad relocatable entries to be generated.

Version 1.03 (Charlie Gibbs, October 14, 1987)

The following bugs in version 1.02 have been corrected:
  • The following situation was causing phase errors:
        xdef	label
    bra	label
     .
    <at least 128 bytes of object code>
     .
label:
    (The XDEF was fooling A68k into thinking that "label" was defined within 128 bytes of the BRA instruction on pass 1, although on pass 2 it knew better.
  • If the first operand of an two-operand executable instruction contained a character term containing a left or right parenthesis, it would generate error messages and be incorrectly evaluated.
  • Labels that don't begin in column 1 (denoted by a trailing colon) caused a Guru Meditation.
  • Certain ADD and SUB instructions using PC-relative addressing may cause phase errors. If the displacement is in the range 1 to 8 inclusive, the instruction was erroneously converted to ADDQ or SUBQ during pass 2.
The following enhancements have been added:
  • The -z option has been added to display the current source program line on stdout as it is read, optionally over a given range. This feature is provided for debugging purposes.
  • Bcc, BSR, and DBcc to labels in other than the current section is now supported. A 16-bit relocation entry will be generated for each such reference.
  • PC relative mode will be generated for backward references to labels within the current CODE section if legal for the current instruction. Forward references will not be converted, since there is no way of telling which section the label is in during pass 1.
  • The cumulative sizes of all sections by type (i.e. CODE, DATA, and BSS) will be displayed at the end of the listing file and the console display. (Bruce Dawson)
  • In the symbol table dump, section names will no longer be indicated just as SECTION, but rather as CODE, DATA, or BSS, depending on type.

Version 1.02 (Charlie Gibbs, September 9, 1987)

The following bugs in version 1.01 have been corrected:
  • Duplicate labels were not being flagged.
  • XDEF symbols were not being dumped to the object code file when the -d option was set.
The following enhancements have been added:
  • A header file is now supported. If the parameter -h<filespec> is included on the command line, the specified file will be included as if the source file's first line was " include <filespec>". The file specification may include a path name, although the include path names given by the -i parameter (if any) will also be searched.
  • An equate file can now be produced. If the parameter -e<filespec> is included on the command line, a file will be written containing EQU statements for any symbol whose value is absolute. If -e is specified without <filespec>, the name of the file will be formed in the same way as the list file, except with an extension of ".equ". (Bruce Dawson)
The following changes have been made to existing logic:
  • No symbol table dump will be produced unless the -x (cross-reference) switch is set. Formerly a symbol table dump was always produced, with only the cross-reference portion optional.

Version 1.01 (Charlie Gibbs, August 20, 1987)

The following bugs in version 1.00 have been corrected:
  • Long-word constants and storage areas were being aligned on a double-word boundary. The only place where double-word alignment is now forced is at a break between SECTIONs, since the length of an AmigaDOS hunk must be a multiple of 4 bytes. (CNOP 0,4 can still be used if double-word alignment is desired by the programmer.)
  • If a label on an END statement or the first statement of a SECTION was named in an XDEF statement, it would not be written to the object code file. The latter case includes both the label of a SECTION directive and the label of the first executable instruction in the absence of any SECTION directives (defaulting to an unnamed CODE section). In the final case (default unnamed CODE section), references to XREF symbols in the first statement would also not be written to the object code file.
  • If the last statement in the source file was not terminated with a newline character (premature EOF), it was being ignored altogether.
  • A register list as the source operand of a MOVE instruction was not being flagged as an error. (MOVE to a register list was being flagged, however.)
  • MOVE from USP was generating incorrect code. Also, MOVE from SR or CCR to an address register was generating incorrect code rather than being flagged.

Version 1.00 (Charlie Gibbs, June 18, 1987) - initial release


The GCC4TI Linker

This is the documentation of the GCC4TI linker, the tool that reads the compiled and assembled files and merges them into a single program. Most parts of this documentation only need to be read by experts; you may safely skip over all parts that you do not understand.

  • GCC4TI Linker Purpose and Operation
  • Invoking ld-tigcc and ar-tigcc
  • Linking Modes of the GCC4TI Linker
  • GCC4TI Linker File Formats
  • Symbols to Control the Linker
  • Startup Sections
  • Global Imports
  • Symbols Built into the GCC4TI Linker
  • Automatically Inserted Section Contents
  • GCC4TI Linker Binary Code Fixup
  • ld-tigcc Program Dumps
  • Recompiling ld-tigcc and ar-tigcc


GCC4TI Linker Purpose and Operation
The GCC4TI Linker Next

The purpose of a linker is to take executable code and data from different files and merge it into a single program. It must resolve dependencies between the files, and there are many architecture-dependent features linkers are required to support. The complicated part about linking is that binary code can be encapsulated in different formats; most linkers, including the GCC4TI linker, can import code from several formats and export it to yet another one (see GCC4TI Linker File Formats).

The GCC4TI linker can handle two kinds of files: object files and archive files. Object files are produced by the compiler or assembler. They contain the code and global variables of the program; all object files passed to the linker are processed and then included in the final output. Archive files, also known as static libraries, are collections of object files. An archive member is included only if this is requested by another file.

Files can reference each other via text strings called symbols. These symbols are usually labels in assembly code, or functions and global variables in C code. The most popular way of referencing symbols is to ask that the final address or offset of a specific symbol be inserted at or added to a specific location in the code. This is called relocation.

When the linker is executed, it first reads all object files passed to it and imports their contents into its internal data structures. Then it tries to resolve the references to symbols defined in another file. If a symbol cannot be resolved, it is looked up in the symbol tables of all archive files passed to the linker; if it is still not found, this is an error. Archive members are imported immediately if required, and they may reference symbols defined in other files as well. Some special actions are performed based on the contents of the imported files, code and data blocks (sections) are sorted and merged if required, and offsets between different locations in the code are inserted whereever the object files requested this. Finally, the program is exported to an executable file.


Invoking ld-tigcc and ar-tigcc
Previous The GCC4TI Linker Next

The GCC4TI linker is available in two forms: as a standalone command line program or as a dynamic link library (DLL). On Windows, GCC4TI uses the DLL version for improved speed, but experienced programmers probably want to use the command line version in some cases because it is a more advanced.

In the IDE, linker options can be set in the project settings. The tigcc command line compiler accepts most of the options of ld-tigcc and passes them to the linker.

  • ld-tigcc Command-Line Options
  • ar-tigcc Command-Line Options


ld-tigcc Command-Line Options
Invoking ld-tigcc and ar-tigcc Next

In ld-tigcc, options and input files may appear in any order in the command line. Input files may be either object or archive (static library) files. They are handled differently depending on the type of the file: Object files are read completely in the order they are supplied; archive file members are read only if the program references a symbol they export. If multiple archive files export the same symbol, ld-tigcc uses the archive that is supplied first.

Output file names and variable names are usually set according to the name of the first object file in the command line, but they may be changed using the '--output' and '--varname' options described below. The file extensions depend on the exact output format used; they are usually what the transferring software expects them to be.

ld-tigcc recognizes the following options:

-h
--help
Print a short description of all available options.

--version
Print the version number of the tool and a short copyright notice.

-v
--verbose
Print statistics about the linked program before terminating. These include the target calculators, program variable name and size, data variable size, BSS size (size of all uninitialized global variables), the total number of absolute relocs, the number of relocs which appear in the native format of the target OS, and optimization possibilities or results. In the IDE, these statistics are displayed automatically, unless this is turned off in the preferences or the program is run automatically after successful linking. If the linking process fails, no statistics are shown.

--dump
Display all dumps of the program contents during the entire linking process. For details about dumps, see ld-tigcc Program Dumps.

--dumpn
Display the n-th dump of the program contents. For details on the different linking stages and the associated dump numbers, see ld-tigcc Program Dumps.

--native
Use GCC4TI native mode by default. Without this option, the linker starts in kernel mode (for compatibility with existing programs), but this may be changed using special symbols (see Symbols to Control the Linker). For more information about modes, see GCC4TI Linker Modes.

--fargo
Use Fargo II mode and compile for the TI-92. This option is only available if Fargo support is compiled in. It exists for compatibility with existing Fargo II programs, which do not explicitly specify a mode and a target calculator.

--flash-os
Use Flash OS mode. This mode creates an unsigned Flash operating system upgrade for the TI-89, TI-89 Titanium, TI-92+ and Voyage 200 calculators. This option is only available if Flash OS support is compiled in.

--remove-unused
Remove unused sections. If a section is not referenced by another section, this option causes it to be removed. Startup sections are never removed; neither is the first section in Nostub mode. Note that in some cases, the linker cannot determine whether a section can be removed before merging it with another section; in this case, it is not removed even though it may not be referenced at all.

--optimize-relocs
Update the destination symbol of relocation entries to the nearest available symbol, thereby making the offset as small as possible. This improves the readability of dumps and some diagnostic messages, but should not have any other effect than this.

--optimize-code
Perform all code optimizations, including NOP, return, branch, move, test, and calculation optimization. Note that it is possible for code optimization to create invalid code or accidentally change data instead of code. The probability is not very high, so you should really enable code optimization at least partially, but if your program crashes for no apparent reason, try turning off code optimization. For more information about optimization, see GCC4TI Linker Binary Code Fixup.
--optimize-nops
Perform NOP instruction removal.

--optimize-returns
Perform return sequence optimization.

--optimize-branches
Perform branch optimization.

--optimize-moves
Perform move/load/push optimization.

--optimize-tests
Perform compare/test optimization.

--optimize-calcs
Perform calculation optimization.
--cut-ranges
Optimization has two effects: It can reduce the number of relocation entries, and it can make instructions smaller. Usually, the space gained from making the instructions smaller is filled with NOPs. If this option is used, the linker will attempt to cut out these ranges of code instead, making the size of the executable even smaller. This only works for input files that were assembled in all-relocs mode, but this is handled automatically if this option is used via the tigcc front-end or the GCC4TI IDE.

--reorder-sections
Reorder sections to make references shorter. The fixups (see above) can then fit those shorter references into smaller and faster addressing modes, so using this option can improve both size and speed. It can also allow the fixups to remove relocations or to turn F-Line jumps into faster branches. Since computing the optimal reordering is NP complete and very expensive in practical terms (the factorial of the number of sections is a huge factor), section reordering is implemented through heuristics. Therefore, the result is not guaranteed to be optimal. There are rare cases where section reordering can still take exponential time, these are due to hardcoded short references between sections rendering some reorderings impossible. In this case, the linker will emit warnings as impossible reorderings are encountered so you can follow the process, or stop it (and go fix your program, hardcoded short references between sections are not a good idea, that's what linker optimization is for!) if it takes too long. Startup sections can be reordered only with other startup sections with the same startup number. Non-startup sections can be reordered only with other non-startup sections. Sections which are emitted separately (e.g. a dynamically allocated BSS section or a data section in an external file) cannot be reordered at all.
--merge-constants
Merge identical constants (including strings) to avoid duplication. Constant merging works on all symbols (actually, the ranges included within 2 symbols, where symbols at the same position are considered the same symbol) in sections marked mergeable. Constants can be merged if they are identical or if one of them is a prefix of the other. This can be used by the compiler to avoid duplicating string literals (and, if desired by the user, other constants) in multiple object files. Unaligned and aligned sections are distinguished to keep the linker from accidentally breaking the alignment while merging aligned constants with unaligned ones which happen to contain them as a prefix.
--omit-bss-init
Skip the initialization of the BSS section, which holds uninitialized global variables. Old versions of TIGCC never initialized the BSS section, so many older programs do not rely on the initialization. If you use this option, you must be sure that there is really no code that relies on the initialization of global variables to zero (which means, among other things, that you have to use the compiler option '-fno-zero-initialized-in-bss'). For a safer alternative, try the __ld_omit_bss_init control symbol.

--outputbin
Instead of creating a wrapped calculator variable that includes a folder and variable name, a checksum, and some extra information, write only the raw contents of the variable to the file. The file extension is changed in a way that allows different files to be generated for each target calculator but prevents confusion between raw and wrapped data.

-o file
--output file
Write the output to the file named file.ext, where ext is the extension that fits the file type. file may include a path, but if it includes its own extension, ext will be appended anyway. This also sets the variable name to something that resembles file as closely as possible. Note that it does not do any error checking on the characters of the file parameter.

-n [folder\]name
--varname [folder\]name
Include the folder name folder (main if unspecified) and variable name name in the wrapper file. If the file is not wrapped (i.e. if '--outputbin' has been specified), this option has no effect.

-d [folder\]name
--data-var [folder\]name
Exclude all non-executable data (global variables) from the program and create an external variable for it. Note that you are absolutely required to make sure that no code is executed from the data section; otherwise it will crash depending on the calculator model: Newer calculators have a protection device that lets the operating system restrict the areas code can be executed from. name is the variable name to be assigned to the data variable. folder defines the folder of the variable; if it is not specified, the folder from the '--varname' option is used.

--data-var-copy=condition
Defines when to create a copy of the data variable in RAM. If condition is always, the program will always work on a copy in RAM, which means that you may rely on the data being the same on every start of the program. However, if the data variable is not archived, you may easily run out of available memory. archived causes a copy to be created only if the data variable is archived; this is the default. If the variable is not archived, the program will work on the actual contents of the variable, so the values of all global variables will be kept even after the program finishes. never tells the linker to work on the original variable unconditionally, but since you may not write to the archive memory, you have to make sure that you never modify the value of a global variable. If the '--data-var' option is not specified as well, this option has no effect.


ar-tigcc Command-Line Options
Previous Invoking ld-tigcc and ar-tigcc

The ar-tigcc tool can be used to create archives recognized by ld-tigcc. The output format is the format used by GNU ar, for which this tool is a replacement. This allows for maximum compatibility between archives and programs created with different versions of GCC4TI.

In ar-tigcc, options and input files may appear in any order in the command line. Input files can have any file format; they are simply written into the archive in the order specified in the command line. However, object files whose format is recognized are searched for exported symbols, so that ar-tigcc can create a symbol table for the archive.

If no output file name is specified, ar-tigcc uses the name of the first input file and appends a '.a' extension to it. It is highly recommended that you specify a different name with the '--output' option.

ar-tigcc recognizes the following options:

-h
--help
Print a short description of all available options.

--version
Print the version number of the tool and a short copyright notice.

--dump
Display a small dump of the archive file contents. This includes the members as well as the symbols they export.

-o file
--output file
-rc file
-qc file
Write the output to the file named file. Unlike ld-tigcc, ar-tigcc does not append a file extension to file. '-rc' and '-qc' are recognized for compatibility with GNU ar, so that certain command lines work with GNU ar as well as ar-tigcc.

--no-names
Omit the file names of the input files in the archive. The archive will only contain names of the form fln.o, where n is the index of the file starting at 1. Omitting file names may be a good idea, especially if you use long file names, since the traditional archive format imposes a maximum of 15 characters on the length of file names. Otherwise, if a file name exceeds this maximum, it will be cut off at the 16th character. The IDE and the tigcc command line compiler always use this option.


Linking Modes of the GCC4TI Linker
Previous The GCC4TI Linker Next

A linking mode defines how the linker treats the contents of the program after they have been read from the object files. The GCC4TI linker has several different modes; some of them are related to specific output file formats, and some of them are present only for historical reasons.

  • GCC4TI-Native Linking Mode
  • Nostub Linking Mode
  • Nostub DLL Linking Mode
  • Kernel Linking Mode
  • Fargo II Linking Mode
  • Flash OS Linking Mode

The recommended mode for normal GCC4TI programs is GCC4TI-native mode. It is the simplest mode; the program is basically an empty sheet of paper, which can be filled with code of all sorts. The default mode is actually kernel mode unless you set the appropriate command-line option, to make old existing programs work without modifications.


GCC4TI-Native Linking Mode
Linking Modes of the GCC4TI Linker Next

This mode (which can be enabled using the '--native' command-line option or the control symbol _tigcc_native) is the recommended mode for all new programs. When operating in this mode, the GCC4TI linker does not process the program in any special way, except that it requires the definition of at least one startup section. The idea is that stub code should not be handled by the linker itself but rather included manually by the program as needed. However, every program (regardless of the architecture and operating system) needs to have a prolog that either contains the location of the main entry point or is itself the startup code of the program. On the TI platforms with official assembly program support, execution always starts at the beginning of the program, so the prolog is actually the startup code.

Ideally, every program should be able to use this mode. However, at the moment, the output file format cannot be specified other than by switching to the appropriate mode. If you want to use a different output file format than the default TIOS format (i.e. Nostub DLL or Fargo II), you cannot use GCC4TI-native mode. At the moment, adding support for explicit selection of the output file format does not have any particular benefit, since it does not permit the removal of any of the other modes. However, as soon as the need for another output format (e.g. raw) arises, there should be a command-line option to select the format.


Nostub Linking Mode
Previous Linking Modes of the GCC4TI Linker Next

If this mode is activated using the _nostub control symbol, execution will start at the very beginning of the program. The exact entry point depends on the order of the object files as passed to the linker as well as the order of the sections inside an object file. Because of this insecurity, this mode should never be used in new programs. Programs written in assembly should define a small startup section including a jump to the actual main function and use GCC4TI-native mode instead. If the main function follows immediately, the jump can even be optimized away by the linker.

If a startup section is defined in nostub mode, the linker emits a warning and switches to GCC4TI-native mode. This ensures that nostub mode really means that no stub is added to the program.


Nostub DLL Linking Mode
Previous Linking Modes of the GCC4TI Linker Next

If the linker is told to use Nostub DLL mode using the __nostub_dll control symbol, it acts like in GCC4TI-native mode, except that it causes the linker to use the Nostub DLL output format instead of the default output format. Since the stub for nostub DLLs is defined as conventional C code rather than imported as a startup section, this mode does not require the definition of a startup section.


Kernel Linking Mode
Previous Linking Modes of the GCC4TI Linker Next

In this mode, which is enabled by default, the linker acts the same way as in GCC4TI-native mode, but it creates a global import asking for the appropriate kernel format header. See Automatically Created Global Imports for more information.


Fargo II Linking Mode
Previous Linking Modes of the GCC4TI Linker Next

This mode is used to create a program that can be run on a TI-92 with Fargo II installed. It can be turned on using the '--fargo' command-line option or the _fargo control symbol. It uses the Fargo II output format, which is binary data wrapped in an empty TI-BASIC program. It creates a global import asking for the appropriate Fargo II header (see Automatically Created Global Imports for more information). And it also causes the value of __ld_entry_point to be decreased by two, to point to the two size bytes in the TIOS file format rather than the beginning of the program data.

Note: Fargo support must be compiled in for this mode to be available.


Flash OS Linking Mode
Previous Linking Modes of the GCC4TI Linker

This mode creates an unsigned Flash operating system upgrade for the TI-89, TI-89 Titanium, TI-92+ and Voyage 200 calculators. It can be turned on using the '--flash-os' command-line option or the _flash_os control symbol. It currently supports only the raw TIB output format, which is enabled by the '--outputbin' option. Support for the current 89u/9xu/v2u format is planned and will be the default. It creates a global import asking for the appropriate Flash OS header (see Automatically Created Global Imports for more information). Since Flash operating systems are composed of 2 discontiguous parts, a small (24 KB) startup segment and a large (1944 KB for 2 MB FlashROMs, 3992 KB for 4 MB FlashROMs) main segment, startup sections are handled in a special way in this mode: Startup sections are placed into the startup segment, all other sections are merged into the main segment.

Note: Flash OS support must be compiled in for this mode to be available.


GCC4TI Linker File Formats
Previous The GCC4TI Linker Next

The GCC4TI linker recognizes several file formats. Currently, it can import COFF and AmigaOS files and export TIOS ASM files, Nostub DLL files (which are TIOS custom files with a special format), and Fargo II files (which are TIOS PRGM files with special hidden data). A small overview of the capabilities of each format is described in the following table:

Format | Sections | Relocations | Unresolved Relocations | Symbols | ROM Calls | RAM Calls | Library Calls | Library Exports | Debug Information | Version Number | Additional Information
COFF | Yes | Yes | Yes | Yes | Yes (through unresolved relocations) | Yes (through unresolved relocations) | Yes (through unresolved relocations) | Yes (through symbols) | Yes | Yes (through symbols) | Yes (through symbols)
AmigaOS | Yes | Yes (except 1-byte absolute) | Yes | Yes | Yes (through unresolved relocations) | Yes (through unresolved relocations) | Yes (through unresolved relocations) | Yes (through symbols) | Yes | Yes (through symbols) | Yes (through symbols)
TIOS ASM | No | 4-byte absolute only | No | No | No (but kernels exist that interpret a special header format) | No (but kernels exist that interpret a special header format) | No (but kernels exist that interpret a special header format) | No (but kernels exist that interpret a special header format) | No | No (but kernels exist that interpret a special header format) | No (but kernels exist that interpret a special header format with a comment, and a header for additional information may be inserted manually)
Nostub DLL | No | 4-byte absolute only | No | No | No | No | No | Yes (but required header is not inserted directly by the linker) | No | Yes (but required header is not inserted directly by the linker) | No
Fargo II | No | 4-byte absolute only (but required header is not inserted directly by the linker) | No | No | Yes (through library calls, but required header is not inserted directly by the linker) | Yes (through library calls, but required header is not inserted directly by the linker) | Yes (but required header is not inserted directly by the linker) | Yes (but required header is not inserted directly by the linker) | No | No | Single comment only (but required header is not inserted directly by the linker)
TI Flash OS (TIB, 89u/9xu/v2u) | 2 fixed sections (24 KB startup, 1944/3992 KB main) | No, runs from fixed address | No | No | No | No | No | No | No | Yes (but not yet supported by the linker) | Product name and date stamp only (but not yet supported by the linker)


Symbols to Control the Linker
Previous The GCC4TI Linker Next

In addition to options specified in the command line, the GCC4TI linker can be controlled using special symbol names. They should be used directly only in assembly programs; C programs should rely on the appropriate library facilities if they are available.

These are the symbols the linker treats as control symbols:

  • __ref_all_...
  • _tigcc_native
  • _nostub
  • _nostub_dll
  • _fargo
  • _flash_os
  • _library
  • _ti92, _ti89, _ti92plus, _v200
  • _flag_...
  • _version...
  • ...@version..., ...__version...
  • __ld_use_fline_jumps
  • __ld_use_4byte_fline_jumps
  • __ld_omit_bss_init
  • __ld_ignore_global_imports

Symbols can be created in a variety of ways; they can be:

  • labels;
  • undefined exported symbols;
  • imported (used but undefined) symbols;
  • common symbols.
Not all assemblers support all types of symbols; for example, the A68k assembler does not support exporting symbols which are not defined somewhere in the same file. This assembler is also somewhat special from the linker's point of view: It only outputs exported and imported symbols by default; local labels can be supplied in a symbol table, but since it is optional, the linker does not use it to receive control information.

If a symbol is detected as a control symbol, it is not imported into the internal data structures as usual. There are two reasons for this: First, if a user accidentally defines a control symbol somewhere (some traditional control symbol names are quite short), the resulting error can help detect this problem. Second, if common symbols are used, they would waste space in the executable otherwise.


__ref_all_...
Symbols to Control the Linker Next

Defining __ref_all_name creates a global import for all symbols named name. Importing the same symbol twice does not have any particular effect; however, sometimes this is necessary if you want a global import to succeed as early as possible.

If none of the archives supplied to the linker exports a symbol with this name (or a related name using conditional reaction), the linker outputs a warning.


_tigcc_native
Previous Symbols to Control the Linker Next

Defining this symbol switches to GCC4TI native mode. We recommend that you define this in all new programs, and then create or import startup sections.


_nostub
Previous Symbols to Control the Linker Next

Defining this symbol switches to NoStub mode. It can only be used in assembly files, since it is impossible to guarantee for some code to be at the beginning of the file.


_nostub_dll
Previous Symbols to Control the Linker Next

Defining this symbol switches to NoStub DLL mode and tells the linker to compile a library instead of a program. If NoStub DLL support is not compiled in, the symbol is not treated in a special way.


_fargo
Previous Symbols to Control the Linker Next

Defining this symbol switches to Fargo II mode. If Fargo support is not compiled in, the symbol is not treated in a special way.


_flash_os
Previous Symbols to Control the Linker Next

Defining this symbol switches to Flash OS mode. If Flash OS support is not compiled in, the symbol is not treated in a special way.


_library
Previous Symbols to Control the Linker Next

Defining this symbol causes a library to be created instead of a program. The linker will warn about program startup sections being included, and depending on the linking mode some different automatic global imports will be created.


_ti92, _ti89, _ti92plus, _v200
Previous Symbols to Control the Linker Next

You need to define one or more of these symbols to specify the calculator for which the program is to be linked. This only controls which output files are created; the linker does not check whether a file format really exists for a given calculator. Kernel compatibility flags (see _flag_...) are added according to the symbol:

_ti89 | Flag 0 (0x01)
_ti92plus | Flag 1 (0x02)
_v200 | Flag 5 (0x20)


_flag_...
Previous Symbols to Control the Linker Next

Defining _flag_n sets the n-th bit in the kernel compatibility flags. Some flags are reserved for calculator compatibility information (see here); the others can be used to pass additional information to the kernel. Note that the meaning of a particular flag may vary between kernels. Kernel flags occupy a single byte; therefore the range of n is 0 through 7.

See also: __ld_kernel_flags


_version...
Previous Symbols to Control the Linker Next

If you define the symbol _versionver, the program/library version number is set to ver, interpreted as a hexadecimal value. Note that the kernel format limits the reserved space for the version number to one byte; this means that kernels only accept two digits for ver.

See also: __ld_file_version


...@version..., ...__version...
Previous Symbols to Control the Linker Next

To specify a required minimum version number for a library used by the program, you can define lib@versionver or lib__versionver. lib is the name of the library (see Library Calls); ver is the minimum version number to be accepted, interpreted as a hexadecimal value (see _version...).

See also: Library Calls


__ld_use_fline_jumps
Previous Symbols to Control the Linker Next

Defining this symbol tells the linker to use relative F-Line branches for branches which would otherwise need to be absolute. These are supported by AMS 2.04 or higher and by various F-Line emulators, including GCC4TI's own emulator.

See also: __ld_use_4byte_fline_jumps


__ld_use_4byte_fline_jumps
Previous Symbols to Control the Linker Next

Defining this symbol tells the linker to use program-relative F-Line branches for branches which would otherwise need to be absolute. These branches are 4 bytes long, whereas normal relative F-Line branches have a size of 6 bytes. However, since they are relative to the program's entry point, the program must install its own emulator to handle them.

4 byte F-Line branches are useful only if range-cutting is enabled.

See also: __ld_use_fline_jumps


__ld_omit_bss_init
Previous Symbols to Control the Linker Next

Defining this symbol in a source file tells the linker that this file does not depend on the initialization of the BSS section to zero. The result is that all uninitialized global variables defined in that file may contain garbage at the beginning of the program. This does not guarantee that the initialization is skipped; in fact, if at least one file needs the initialization, it is easier to initialize even the variables that were declared to not need it.

For pointer-based object file formats (such as COFF, the format used by the GNU tools included in GCC4TI), this symbol really affects all variables in the file it is defined in. For sequential formats (such as the AmigaOS format used by the A68k assembler), it affects only the parts that follow the symbol. Since BSS data usually appears at the end of the object file, this restriction should not have any effect.

Note: If you define this symbol, you should use the compiler option '-fno-zero-initialized-in-bss'; otherwise even variables explicitly initialized to zero will contain garbage.


__ld_ignore_global_imports
Previous Symbols to Control the Linker

Defining this symbol in a source file tells the linker that from this file on, defining a __ref_all_... symbol has no effect. This should not be used except in very special circumstances.


Startup Sections
Previous The GCC4TI Linker Next

The concept of startup sections is unique to the GCC4TI linker. It only makes sense in low-resource environments like calculators. The idea is that a file that is imported should be able to specify that it needs certain code to be executed at the beginning of the program. Usually, there are two approaches to address this situation: constructors and main function wrappers.

If constructors are used to handle this, a lot of memory is wasted: A constructor table needs to be created with appropriate code to handle its contents; every item needs to save all registers except a few, and sharing data between two constructors requires global variables. Moreover, using constructors, it is not possible to specify the order in which startup code is to be called; however, parts of the startup code often need to rely on other parts to be executed first.

Main function wrappers appear in almost every environment. But since these wrappers are fixed, they need to handle all startup code that might possibly be needed, instead of letting each file choose its own startup code. For example, such fixed startup code would need to handle exceptions even if the program never generates them, or fill certain global variables that are never read.

Startup sections are actually a wrapper around the main function, but they can achieve even more flexibility than constructors: They are numbered and executed in the exact order specified by the numbers, and no extra code is executed between two consecutive startup sections, so registers can be used to pass data between two sections.

Startup sections can be used not only to insert code at the beginning of the program, but also to generate the required headers for certain file formats. Sometimes this is easier than writing the linker code to insert the required headers (see GCC4TI Linker File Formats).

Since libraries may need to contain a header, some stub code that is called when the user tries to execute the library, and possibly some startup code, they may also have startup sections. However, it does not really make sense to include a startup section designed for a program in a library. Therefore, there are library startup sections, which may appear in both libraries and programs, and program startup sections, which may appear only in programs. Library startup sections are always included before program startup sections.

Startup sections are detected based on their name. To declare a program startup section, name the section _stn, where n is a value from 1 to 99999 (higher values for n may be accepted if the object file format supports section names longer than 8 characters, but it is not recommended to use them). To declare a library startup section, name it _stln, where n is a value from 1 to 9999 (higher values are not permitted). Startup sections are included in ascending order; if two startup sections use the same index, their order is undefined.


Global Imports
Previous The GCC4TI Linker Next

Just like startup sections, the concept of global imports is unique to the GCC4TI linker. Global imports and startup sections are closely related to each other: It is best to keep startup sections in archive files, so they can be imported as needed, but the existing method of importing archive file members does not work. Usually, an archive file member is imported if a symbol it exports is referenced in a relocation entry. However, code that requires a specific startup section to be included does not necessarily reference any of the symbols in the corresponding archive member; it just needs the startup code to be there. A global import solves this problem by importing an archive member without inserting its address anywhere.

Actually, a global import imports all archive members that export the symbol referenced by the import (and even more, see Conditional Reaction to Global Imports). If no archive member exports this symbol, a warning is emitted. This way, it is very easy to create archive files that react to multiple imports; for example:

  • File 1 exports the symbols A and B.
  • File 2 exports the symbols B and C.
  • File 3 exports the symbols A and C.
A global import for A would cause the files 1 and 3 to be included in the program. If it could only import one file, 6 files would be needed to get the same result:
  • File 1 exports the symbol A and creates two global imports for File4 and File6.
  • File 2 exports the symbol B and creates two global imports for File4 and File5.
  • File 3 exports the symbol C and creates two global imports for File5 and File6.
  • File 4 exports the symbol File4.
  • File 5 exports the symbol File5.
  • File 6 exports the symbol File6.
Global import can be created using the __ref_all_... control symbol. Some global imports are also created automatically by the linker on certain conditions.
  • Conditional Reaction to Global Imports
  • Automatically Created Global Imports


Conditional Reaction to Global Imports
Global Imports Next

Sometimes, it is convenient for an archive member to react to a global import differently than just to be included whenever the import is created. For example, a startup section may be optimized better if a certain register already holds a certain value, otherwise it must compute the value by itself. The GCC4TI linker defines two symbol operators for this purpose:

  • ..._AND_...
  • NOT_...
To be included only if the global imports A and B are defined, a file must export the symbol A_AND_B. To be included only if the global import A is not defined, a file must export the symbol NOT_A. Symbol operators may be combined, i.e. a file exporting NOT_A_AND_B is included only if no global import A exists, and a global import B is defined.

There is a small quirk related to negated conditions: At some point, the linker needs to assume that no global imports A and B exist, and any file exporting the symbol NOT_A or NOT_B needs to be imported. However, the file which exported NOT_B may actually create a global import A after the file exporting NOT_A has been imported. The linker does not detect this, so you need to be careful not to create such situations. They are especially difficult to detect if a lot of combinations of AND and NOT operators are used, and if a lot of files that react to global imports create imports of their own.


Automatically Created Global Imports
Previous Global Imports

In addition to user-defined global imports, the GCC4TI linker also defines some global imports of its own, whenever special code is needed to handle a situation:

__kernel_program_header
This global import is created automatically if the linker is operating in kernel mode, and if the file is not declared as a library (see the _library control symbol).

__kernel_library_header
This global import is created automatically if the linker is operating in kernel mode, and if the file is declared as a library (see the _library control symbol).

__fargo_program_header
This global import is created automatically if the linker is operating in Fargo II mode, and if the file is not declared as a library (see the _library control symbol).

__fargo_library_header
This global import is created automatically if the linker is operating in Fargo II mode, and if the file is declared as a library (see the _library control symbol).

__flash_os_header
This global import is created automatically if the linker is operating in Flash OS mode.

__nostub_comment_header
This global import is created automatically if NoStub data (comment) exports are defined for the program. The file reacting to this import must use __ld_nostub_comment_count and __ld_insert_nostub_comments to insert the actual data exports into the header.

__handle_constructors
This global import is created automatically if constructors are defined for the program. The file which handles this import must query the constructor section using the __ld_constructors_start, __ld_constructors_end, __ld_constructors_size, and __ld_constructor_count symbols.

__handle_destructors
This global import is created automatically if destructors are defined for the program. The file which handles this import must query the destructor section using the __ld_destructors_start, __ld_destructors_end, __ld_destructors_size, and __ld_destructor_count symbols.

__handle_bss
This global import is created automatically if the program contains a BSS section (a section containing uninitialized global variables). No file needs to react to this import; if the BSS section is not created at run time (using __ld_bss_size, __ld_bss_ref_count, and an appropriate insertion for the relocation), it is simply passed on to the output file. If the output format does not support sections, the BSS section is merged with the other sections. However, if the program reacts to this import, it absolutely must handle the relocation entries pointing into the BSS section.

__initialize_bss
This global import is created automatically if the program contains a BSS section, and the program requires the contents of this section to be initialized to zero. The file reacting to this import must use __ld_bss_start, __ld_bss_end, and __ld_bss_size to query the location and size of the BSS section.

__handle_relocs
This global import is created automatically if the program contains absolute relocation entries. If no file reacts to this import, relocation entries have to be handled by the output format. The file reacting to this import must use __ld_reloc_count and an appropriate insertion to get information about the necessary relocation.

__handle_rom_calls
This global import is created automatically if the program contains ROM calls. If no file reacts to this import, ROM calls are handled by the output format. The file reacting to this import must use __ld_rom_call_count and an appropriate insertion to get information about the ROM calls.

__handle_ram_calls
This global import is created automatically if the program contains RAM calls. If no file reacts to this import, RAM calls are handled by the output format. The file reacting to this import must use __ld_ram_call_count and an appropriate insertion to get information about the RAM calls.

__handle_libraries
This global import is created automatically if the program references at least one library. If no file reacts to this import, library calls are handled by the output format. The file reacting to this import must use __ld_lib_count and an appropriate insertion to get information about the libraries.

__handle_data_var
This global import is created automatically if the data section of the program is not included in the program itself but in an external file. The file that handles this import must open this file and relocate the program accordingly. It must refer to __ld_data_var_name_end, __ld_data_size, and an appropriate insertion for the relocation.

__data_var_create_copy
This global import is created automatically if the data section of the program is not included in the program itself but in an external file, and this file needs to be copied into memory (either always or under certain circumstances).

__data_var_copy_if_archived
This global import is created automatically if the data section of the program is not included in the program itself but in an external file, and this file needs to be copied into memory only if it is archived. This import is created only in combination with __data_var_create_copy.


Symbols Built into the GCC4TI Linker
Previous The GCC4TI Linker Next

The GCC4TI linker is capable of resolving references to certain built-in symbols. These symbols act just like normal externally defined symbols; for example, it is possible to specify an offset to be added to the symbol in the reference. The symbols may resolve to numbers or addresses. The kind of symbol should be obvious for each individual symbol; for example, it does not make sense to jump to __ld_bss_size because it resolves to a number. All numbers have to be used as immediate values; if a symbol resolves to a number, treating it as an address and reading the value at this address will return garbage.

The following symbol names are treated as built-in symbol names, and resolved in a special way:

  • _ROM_CALL_...
  • tiamsapi_...
  • _RAM_CALL_...
  • _extraramaddr@..., _extraramaddr__...
  • ...@????, ...__????
  • __ld_calc_const_...
  • __ld_entry_point
  • __ld_entry_point_plus_0x8000
  • __ld_program_size
  • __ld_constructors_start
  • __ld_constructors_end
  • __ld_constructors_size
  • __ld_constructor_count
  • __ld_destructors_start
  • __ld_destructors_end
  • __ld_destructors_size
  • __ld_destructor_count
  • __ld_reloc_count
  • __ld_data_start
  • __ld_data_end
  • __ld_data_size
  • __ld_data_ref_count
  • __ld_bss_start
  • __ld_bss_end
  • __ld_bss_even_end
  • __ld_bss_size
  • __ld_bss_ref_count
  • __ld_rom_call_count
  • __ld_ram_call_count
  • __ld_lib_count
  • __ld_referenced_lib_count
  • __ld_export_count
  • __ld_nostub_comment_count
  • __ld_has_...
  • __ld_file_version
  • __ld_kernel_flags
  • __ld_kernel_bss_table
  • __ld_kernel_export_table
  • __ld_data_var_name_end
  • __ld_hardware_id
  • __ld_link_time_year
  • __ld_link_time_month
  • __ld_link_time_day
  • __ld_link_time_timestamp
  • _exit
  • _comment
  • _extraram
  • _library


_ROM_CALL_...
Symbols Built into the GCC4TI Linker Next

The symbol _ROM_CALL_index is resolved to the ROM call with the index index, interpreted as a hexadecimal value. The operating system translates references to such symbols in a way that they point to the specified ROM call. This is usually a function, but it can also be a variable.

See also: tiamsapi_..., _RAM_CALL_...


tiamsapi_...
Previous Symbols Built into the GCC4TI Linker Next

The symbol tiamsapi_index is resolved to the ROM call with the index index, interpreted as a decimal value. The operating system translates references to such symbols in a way that they point to the specified ROM call. This is usually a function, but it can also be a variable.

See also: _ROM_CALL_...


_RAM_CALL_...
Previous Symbols Built into the GCC4TI Linker Next

The symbol _RAM_CALL_index is resolved to the RAM call with the index index, interpreted as a hexadecimal value. If RAM calls are supported, the operating system translates references to such symbols in a way that they either point to a specific location in memory, or are replaced by a specific value.

See also: _ROM_CALL_..., Extra RAM Addresses


_extraramaddr@..., _extraramaddr__...
Previous Symbols Built into the GCC4TI Linker Next

_extraramaddr@index and _extraramaddr__index are treated as references to an extra RAM address with the index index interpreted as a hexadecimal value. index is an index into the extra RAM table defined by the program (using the _extraram symbol). The value which __extraramaddr... symbols are resolved to is either the TI-89 or the TI-92(+)/V200 value of the table row specified by index.

Internally, extra RAM addresses are stored as RAM calls and treated the same way. __ld_insert_kernel_ram_calls and __ld_insert_preos_compressed_tables output RAM calls and extra RAM addresses similarly to each other.

See also: _extraram, _RAM_CALL...


...@????, ...__????
Previous Symbols Built into the GCC4TI Linker Next

The symbol libname@index or libname__index is resolved to a call to the library libname with the index index, interpreted as a hexadecimal value. index must have exactly four hexadecimal digits; otherwise it will not be recognized. If library calls are supported, the operating system loads the specified libraries and translates references to such symbols in a way that they point to the appropriate exported symbol in the library.

Library symbols are exported in the same way they are imported, except that the first part of the symbol (the library name) is not checked. If an exported symbol in an object file has the form libname@index or libname__index, where index is a four-digit hexadecimal number and libname does not start with a dot or an underscore, it is automatically exported from the program or library. The reason for this somewhat ambiguous pattern is purely traditional.

See also: Minimum Library Versions, _ROM_CALL_..., _RAM_CALL_...


__ld_calc_const_...
Previous Symbols Built into the GCC4TI Linker Next

__ld_calc_const_constants, where constants is an underscore-separated list of positive integer values in decimal or hexadecimal notation (prefixed with 0x), resolves to one of the values in constants. The actual value depends on the calculator belonging to the file that is generated. This feature adds the possibility to compile a program for multiple calculators at once and still generate different files for each calculator.

The order of the calculator-specific values in constants is as follows:

  1. TI-92
  2. TI-89
  3. TI-92 Plus
  4. V200
Values for calculators which the linker is currently not generating any output file for may be omitted. If a significant value is omitted, the value is assumed to be zero, and a warning is emitted.


__ld_entry_point
Previous Symbols Built into the GCC4TI Linker Next

References to this symbol are resolved to the first address of the program that contains executable code. If startup sections are defined, this is the address of the first startup section. However, the exact meaning of the symbol is defined by the mode the linker is operating in, since startup sections do not necessarily need to contain code, and an "entry point" in the sense of this symbol does not exist in all types of files.

Note: In Fargo II mode, all references to this symbol are manually shifted by two bytes in the negative direction, since Fargo heavily uses the program variable's address as a base address, instead of the address of the Fargo header.


__ld_entry_point_plus_0x8000
Previous Symbols Built into the GCC4TI Linker Next

This symbol is the same as __ld_entry_point plus 0x8000 (32 KB).


__ld_program_size
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the size of the main section after all sections are merged into one. If all sections are merged into a single section, this is the size of the final linked program (without any headers or footers required by the output format). If an external data variable is used, this would be the size of the main executable only (but see the note about automatic insertion below).

Resolving of this symbol is delayed until the last pass of the linker in order to ensure the size isn't changed by later range-cutting. Currently, this is the same pass which also does automatic insertions, so insertions may or may not be counted.

This symbol is currently used by the Flash OS support to write the OS size into the header which is sent to the calculator. Flash operating systems do not use relocation, so the lack of support for automatic insertions is not a problem in this context.


__ld_constructors_start
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the beginning of the constructor section of the program. A constructor section contains an array of pointers to functions, all of which do not take any parameters. These functions are to be executed at program startup. If no constructors are used, an error is reported.

See also: __ld_constructors_end, __ld_constructors_size, __ld_constructor_count, __ld_destructors_start


__ld_constructors_end
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the end of the constructor section of the program. A constructor section contains an array of pointers to functions, all of which do not take any parameters. These functions are to be executed at program startup. If no constructors are used, an error is reported.

See also: __ld_constructors_start, __ld_constructors_size, __ld_constructor_count


__ld_constructors_size
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the size of the constructor section of the program. A constructor section contains an array of pointers to functions, all of which do not take any parameters. If no constructors are used, the symbol resolves to a value of 0. The value equals the value of __ld_constructor_count multiplied by the size of a pointer, which is 4.

See also: __ld_constructors_start, __ld_constructors_end, __ld_constructor_count


__ld_constructor_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the number of constructors the program uses. If no constructors are used, it resolves to a value of 0. The value equals the value of __ld_constructors_size divided by the size of a pointer, which is 4.

See also: __ld_constructors_start, __ld_constructors_end, __ld_constructors_size, __ld_destructor_count


__ld_destructors_start
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the beginning of the destructor section of the program. A destructor section contains an array of pointers to functions, all of which do not take any parameters. These functions are to be executed at program startup. If no destructors are used, an error is reported.

See also: __ld_destructors_end, __ld_destructors_size, __ld_destructor_count, __ld_constructors_start


__ld_destructors_end
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the end of the destructor section of the program. A destructor section contains an array of pointers to functions, all of which do not take any parameters. These functions are to be executed at program exit. If no destructors are used, an error is reported.

See also: __ld_destructors_start, __ld_destructors_size, __ld_destructor_count


__ld_destructors_size
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the size of the destructor section of the program. A destructor section contains an array of pointers to functions, all of which do not take any parameters. If no destructors are used, the symbol resolves to a value of 0. The value equals the value of __ld_destructor_count multiplied by the size of a pointer, which is 4.

See also: __ld_destructors_start, __ld_destructors_end, __ld_destructor_count


__ld_destructor_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the number of destructors the program uses. If no destructors are used, it resolves to a value of 0. The value equals the value of __ld_destructors_size divided by the size of a pointer, which is 4.

See also: __ld_destructors_start, __ld_destructors_end, __ld_destructors_size, __ld_constructor_count


__ld_reloc_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol resolves to the number of absolute relocation entries in this program/library, except relocation entries to sections which are handled separately. If the program contains an external BSS and/or data section, relocs to this section are not counted, since they cannot be handled in the same manner as relocs into the program code.

See also: __ld_insert_kernel_relocs, __ld_insert_mlink_relocs, __ld_insert_compressed_relocs, __ld_insert_fargo021_relocs, __ld_insert_preos_compressed_tables


__ld_data_start
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the starting address of the data section, if the program does not mix text and data (for example if the data is written into an external file). It points to the location behind the last item in the section. If the program does not contain an explicit data section, an error is reported.

See also: __ld_data_end, __ld_data_size


__ld_data_end
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the end of the data section, if the program does not mix text and data (for example if the data is written into an external file). It points to the location behind the last item in the section. If the program does not contain an explicit data section, an error is reported.

See also: __ld_data_start, __ld_data_size


__ld_data_size
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the size of the data section in bytes, if the program does not mix text and data (for example if the data is written into an external file). If the program does not contain a data section, the symbol resolves to the value 0.

See also: __ld_data_start, __ld_data_end


__ld_data_ref_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the number of references to the data section, if the program does not mix text and data (for example if the data is written into an external file). If the program does not contain an explicit data section, it resolves to the value 0. If the data section is merged with the other sections, the references counted by this symbol and the references counted by __ld_reloc_count will overlap.

See also: __ld_insert_kernel_data_refs, __ld_insert_mlink_data_refs, __ld_insert_compressed_data_refs


__ld_bss_start
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the starting address of the BSS section. If the program does not contain a BSS section, an error is reported.

See also: __ld_bss_end, __ld_bss_even_end, __ld_bss_size


__ld_bss_end
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the end of the BSS section. It points to the location behind the last item in the section. If the program does not contain a BSS section, an error is reported.

See also: __ld_bss_start, __ld_bss_size, __ld_bss_even_end


__ld_bss_even_end
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol points to the first even location behind the last item in the BSS section. In other words, it is equal to __ld_bss_end rounded up to the next multiple of 2. If the program does not contain a BSS section, an error is reported.

See also: __ld_bss_end, __ld_bss_start, __ld_bss_size


__ld_bss_size
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the size of the BSS section in bytes. If the program does not contain a BSS section, the symbol resolves to the value 0.

See also: __ld_bss_start, __ld_bss_end, __ld_bss_even_end


__ld_bss_ref_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the number of references to the BSS section. If the program does not contain a BSS section, it resolves to a value of 0. If the BSS section is merged with the other sections, the references counted by this symbol and the references counted by __ld_reloc_count will overlap.

See also: __ld_insert_kernel_bss_refs, __ld_insert_mlink_bss_refs, __ld_compressed_bss_refs, __ld_fargo021_bss_refs, __ld_insert_preos_compressed_tables


__ld_rom_call_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol resolves to the number of ROM calls in this program/library. If the program/library does not reference any ROM code exports, it resolves to a value of 0.

See also: __ld_insert_kernel_rom_calls, __ld_insert_mlink_rom_calls, __ld_insert_compressed_rom_calls, __ld_insert_preos_compressed_tables, ROM Calls


__ld_ram_call_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol resolves to the number of RAM calls in this program/library. If the program/library does not reference any RAM exports, it resolves to a value of 0. Extra RAM address references count as RAM calls as well. Note that RAM calls are handled purely by kernels, i.e. by middleware residing in the RAM.

See also: __ld_insert_kernel_ram_calls, __ld_insert_preos_compressed_tables, RAM Calls, Extra RAM Addresses


__ld_lib_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol resolves to the number of libraries needed by this program/library. The libraries do not actually need to be used; it is enough for a file to specify a required minimum version for a specific library (see Minimum Library Versions). The idea is that a program should be able to specify a minimum version for a library even if the library is only referenced indirectly via another one. See __ld_referenced_lib_count for a way to count only the libraries that are actually used.

See also: __ld_referenced_lib_count, __ld_insert_kernel_libs, __ld_insert_fargo020_libs, __ld_insert_fargo021_libs, __ld_insert_preos_compressed_tables, Library Calls, Minimum Library Versions


__ld_referenced_lib_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol acts like __ld_lib_count, except that it counts only the libraries that are actually used. If the program only specified a minimum version for a library, but did not use any of its exported symbols, this library is not counted.

See also: __ld_lib_count, __ld_insert_kernel_libs, __ld_insert_fargo020_libs, __ld_insert_fargo021_libs, __ld_insert_preos_compressed_tables, Library Calls, Minimum Library Versions


__ld_export_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol resolves to the number of exported items in the current program/library. This equals the highest export number present in the linked files (see Library Calls) plus 1. For example, defining a single exported entry named mylib@00FF causes the export table to be 0x100 functions long, and therefore this symbol to be resolved to a value of 0x100.

See also: __ld_insert_kernel_exports, Library Calls


__ld_nostub_comment_count
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol resolves to the number of NoStub data exports in the current program. Unlike for library exports, skipped indices are not counted.

See also: __ld_insert_nostub_comments


__ld_has_...
Previous Symbols Built into the GCC4TI Linker Next

The symbol __ld_has_items resolves to a nonzero value if __ld_item_count is greater than zero. Currently this value is -1, but do not rely on this!


__ld_file_version
Previous Symbols Built into the GCC4TI Linker Next

This symbol resolves to the version number of the current program, defined with _version.... If no version number has been defined, it resolves to a value of 0.

See also: _version...


__ld_kernel_flags
Previous Symbols Built into the GCC4TI Linker Next

This symbol resolves to the value of the kernel flags. Kernel flags may be specified with _flag_... and with calculator control symbols.

See also: _flag_...


__ld_kernel_bss_table
Previous Symbols Built into the GCC4TI Linker Next

Usually, this symbol is simply resolved to a user-defined symbol named __kernel_bss_table. However, if the program does not contain a BSS section, it is redirected to the entry point of the program. The effect is that constructs of the form

.word __ld_kernel_bss_table-entry_point
resolve to 0 if no BSS section is used.

Note: If a program/library defines __kernel_bss_table, it absolutely must handle the BSS section. See __ld_insert_kernel_bss_refs for a way to get information about references into the BSS section.


__ld_kernel_export_table
Previous Symbols Built into the GCC4TI Linker Next

Usually, this symbol is simply resolved to a user-defined symbol named __kernel_export_table. However, if the program does not contain any exported symbols, it is redirected to the entry point of the program. The effect is that constructs of the form

.word __ld_kernel_export_table-entry_point
resolve to 0 if no exports exist.


__ld_data_var_name_end
Previous Symbols Built into the GCC4TI Linker Next

This symbol is resolved to the address of the user-defined symbol __data_var_name_start, plus the length in bytes of the data variable name, plus 1 for the zero byte at the beginning. If no data variable is specified for the program, an error is reported. The symbol __data_var_name_start must be defined and exported by the program.


__ld_hardware_id
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol resolves to the hardware ID of the target calculator type, a number used in the Flash OS stub.


__ld_link_time_year
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the current year when starting the linking process. It is written in binary form, not in string form.


__ld_link_time_month
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the current month when starting the linking process. It is written in binary form, not in string form.


__ld_link_time_day
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the current day when starting the linking process. It is written in binary form, not in string form.


__ld_link_time_timestamp
Previous Symbols Built into the GCC4TI Linker Next

This built-in symbol represents the number of seconds elapsed between January 1st 1997, 00:00:00 UTC and the beginning of the linking process. It is written in binary form, not in string form.

This built-in is provided so that the Flash OS support library can define a meaningful value for the 0x900 subfield of the 0x320 certificate field contained in the Flash OS header, thus mimicking AMS and its FlashApps.


_exit
Previous Symbols Built into the GCC4TI Linker Next

Usually, this symbol is not handled in a special way. However, if it does not exist at all, it is redirected to the entry point of the program. The effect is that constructs of the form

.word _exit-entry_point
resolve to 0 if the symbol is undefined.

The kernel headers of the standard library reference this symbol as the program/library destructor. For kernel programs and libraries, it is called whenever the program exits or the library is unloaded.


_comment
Previous Symbols Built into the GCC4TI Linker Next

Usually, this symbol is not handled in a special way. However, if it does not exist at all, it is redirected to the entry point of the program. The effect is that constructs of the form

.word _comment-entry_point
resolve to 0 if the symbol is undefined.

The kernel headers reference this symbol as the comment string of the program. If it exists, it must be a zero-terminated ASCII string.


_extraram
Previous Symbols Built into the GCC4TI Linker Next

Usually, this symbol is not handled in a special way. However, if it does not exist at all, it is redirected to the entry point of the program. The effect is that constructs of the form

.word _extraram-entry_point
resolve to 0 if the symbol is undefined.

The kernel headers of the standard library reference this symbol as an extra RAM table. The table is organized in pairs of 16 bit values. Of each pair, the first value is relevant for the TI-89, and the second value is relevant for the TI-92(+)/V200 calculator family. In C, you would define an extra RAM table like this:
struct {
  short value89, value9x;
} _extraram[] = {{v1_89, v1_9x}, {v2_89, v2_9x}, ...};
However, extra RAM tables are barely usable in C: The compiler does not support using external symbols as immediate values, except if you take their address.

See also: Extra RAM Addresses


_library
Previous Symbols Built into the GCC4TI Linker

Usually, this symbol is not handled in a special way. However, if it does not exist at all, it is redirected to the entry point of the program. The effect is that constructs of the form

.word _library-entry_point
resolve to 0 if the symbol is undefined.

Note: _library is also a control symbol, which means that under normal circumstances, references to it are not allowed. However, in Fargo II mode, programs and libraries have special permission to use this symbol.


Automatically Inserted Section Contents
Previous The GCC4TI Linker Next

The GCC4TI linker can insert certain variable-length data into the contents of sections. If a symbol (i.e., a label) at the end of a section is recognized as an insertion point, then the linker appends the data specified by the symbol name. If the symbol is not at the end of a section, the insertion will fail without notice, since these contents may have been inserted automatically already.

You may refer to an insertion symbol even if you did not put a label at a specific place. In this case, the data is written to an arbitrary place (usually the end of the program, but do not rely on this). However, all object files and archives are searched for exported symbols with this name first, to avoid duplication of the data.

This method is only used if some program-related data cannot be expressed using simple built-in symbols. It should be used with care, as the inserted data may be invalid under certain circumstances. The format of the data is fixed and usually represents some already established data format, but new data formats may be developed on demand. The insertion symbols which are currently recognized are:

  • __ld_insert_kernel_relocs
  • __ld_insert_mlink_relocs
  • __ld_insert_compressed_relocs
  • __ld_insert_fargo021_relocs
  • __ld_insert_kernel_bss_refs
  • __ld_insert_mlink_bss_refs
  • __ld_insert_compressed_bss_refs
  • __ld_insert_fargo020_bss_refs
  • __ld_insert_fargo021_bss_refs
  • __ld_insert_kernel_data_refs
  • __ld_insert_mlink_data_refs
  • __ld_insert_compressed_data_refs
  • __ld_insert_kernel_rom_calls
  • __ld_insert_mlink_rom_calls
  • __ld_insert_compressed_rom_calls
  • __ld_insert_kernel_ram_calls
  • __ld_insert_kernel_libs
  • __ld_insert_fargo020_libs
  • __ld_insert_fargo021_libs
  • __ld_insert_kernel_exports
  • __ld_insert_fargo_exports
  • __ld_insert_preos_compressed_tables
  • __ld_insert_nostub_comments
  • __ld_insert_data_var_name


__ld_insert_kernel_relocs
Automatically Inserted Section Contents Next

Relocation entries indicate that the program needs to know some addresses which are only available at run time. In this case, the addresses referred to are locations inside the program code or data. Usually, all references to absolute addresses inside the program are inserted into the section if one of these two insertions is used; however, sections may be marked as being handled in another way, which prevents relocation entries to them from being output in this way. The data section is automatically marked as handled if it is externalized; the BSS section is marked as handled by referencing __ld_kernel_bss_table, by using __ld_insert_kernel_bss_refs before inserting the relocation entries, or by reacting to the __handle_bss global import.

__ld_insert_kernel_relocs uses the kernel format for storing relocation entries, which is used by kernels on the TI-89, TI-92 Plus, and V200, and by Fargo v0.2.0:

  • For each relocation entry...
    • 2 bytes: location (may not be 0)
  • 2 bytes: 0
If a program uses this insertion, it must process it as follows:
  • For each relocation entry...
    • Get the starting address of the program (via __ld_entry_point);
    • Add the location value;
    • Modify the 4-byte value (offset) at the resulting address:
      • Get the starting address of the program (relocation address);
      • Add the value of offset;
      • Write the resulting address to the 4-byte space covered by offset.
Before program termination, this process has to be reverted, so that it can be repeated the next time the program starts. Since programs may be moved in memory while they are not executed, they may not simply deactivate the relocation code. This would also prevent programs from being transferred between devices.

Note: Relocation entries may only be inserted at a single place in the program. The reason for this is that the linker may have to add new relocation entries after they have been written into the section. Instead of keeping track of which entries have already been processed, we thought it would be easier to remove them once they have been written into a section. Also, it is dangerous to use this insertion from anything other than a startup section.

See also: __ld_insert_kernel_bss_refs, __ld_insert_kernel_data_refs, __ld_insert_mlink_relocs, __ld_insert_compressed_relocs


__ld_insert_mlink_relocs
Previous Automatically Inserted Section Contents Next

__ld_insert_mlink_relocs inserts relocs in a compressed format known from mlink. For more information on inserting and processing relocs, see __ld_insert_kernel_relocs.

In the following format description, offset refers to the difference in words (half of the difference in bytes) between the start of this reloc and the start of the previous reloc. If there is no previous reloc (i.e. for the first reloc), offset is the distance in words between this reloc and the symbol __ld_mlink_relocs_ref. This symbol must be exported to be found. If it is not found, the entry point is used instead (see __ld_entry_point).

  • For each relocation entry...
    • Any of the following, whichever fits:
      • For 0 <= offset < 128: 1 byte: 0x80 + offset
      • For 128 <= offset < 16384: 2 bytes: offset / 128, 0x80 + (offset % 128)
      • For 16384 <= offset < 2097152: 3 bytes: offset / 16384, (offset % 16384) / 128, 0x80 + (offset % 128)
      • Anything higher isn't interesting for us because of the 64 KB file size limit.
  • 1 byte: 0
Note: The limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_mlink_bss_refs, __ld_insert_mlink_data_refs, __ld_insert_kernel_relocs


__ld_insert_compressed_relocs
Previous Automatically Inserted Section Contents Next

__ld_insert_compressed_relocs inserts relocs in a compressed format known from Fargo. For more information on inserting and processing relocs, see __ld_insert_kernel_relocs.

In the following format description, offset refers to the difference in words (half of the difference in bytes) between the start of this reloc and the end of the previous reloc. If there is no previous reloc (i.e. for the first reloc), offset is the distance in words between this reloc and the symbol __ld_compressed_relocs_ref. This symbol must be exported to be found. If it is not found, the entry point is used instead (see __ld_entry_point).

  • For each relocation entry...
    • If we are inside a nibble sequence (see below):
      • 1 nibble (1/2 byte): offset
    • Else: Any of the following, whichever fits:
      • 1 byte: offset + 1 (must be between 0x01 and 0x7F)
      • 1 byte:
        • 1st nibble: nibble_count / 2 + 0x6 (must be between 0x8 and 0xB)
        • 2nd nibble: offset
        A nibble sequence of nibble_count nibbles follows (see above).
      • 2 bytes: offset + 0xBF81 (must be between 0xC000 and 0xFFFE)
      • A variable-length sequence:
        • 2 bytes: 0xFFFF
        • Any of the four possibilities, with offset decreased by 0x407E
  • 1 byte: 0
Note: The limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_compressed_bss_refs, __ld_insert_compressed_data_refs, __ld_insert_kernel_relocs


__ld_insert_fargo021_relocs
Previous Automatically Inserted Section Contents Next

__ld_insert_fargo021_relocs inserts relocs in the compressed format used by Fargo 0.2.1. For more information on inserting and processing relocs, see __ld_insert_kernel_relocs.

This insertion is the same as __ld_insert_compressed_relocs, except that the the reference symbol used if there is no previous reloc (i.e. for the first reloc) is __ld_fargo021_relocs_ref. It is expected by Fargo to be at a fixed position: the position of the format flag in the Fargo header. This is currently handled by the definition of the Fargo header.

Fargo support must be compiled in for this insertion to be defined.

Note: The limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_compressed_relocs, __ld_insert_kernel_relocs


__ld_insert_kernel_bss_refs
Previous Automatically Inserted Section Contents Next

__ld_insert_kernel_bss_refs outputs references to the BSS section in the format defined in __ld_insert_kernel_relocs. The only difference is that the relocation address is not the entry point of the program but the beginning of the BSS section.

If you insert these references, the linker assumes that the BSS section is handled by you; that is, you have to allocate it dynamically using __ld_bss_size and use a pointer to it as the relocation address.

Note: The limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_kernel_data_refs, __ld_insert_kernel_relocs, __ld_insert_mlink_bss_refs, __ld_insert_compressed_bss_refs


__ld_insert_mlink_bss_refs
Previous Automatically Inserted Section Contents Next

__ld_insert_mlink_bss_refs inserts relocs in the format defined in __ld_insert_mlink_relocs. The only differences are that the relocation address is not the entry point of the program but the beginning of the BSS section and that the reference symbol used if there is no previous reloc (i.e. for the first reloc) is __ld_mlink_bss_refs_ref.

If you insert these references, the linker assumes that the BSS section is handled by you; that is, you have to allocate it dynamically using __ld_bss_size and use a pointer to it as the relocation address.

Note: The limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_mlink_data_refs, __ld_insert_mlink_relocs, __ld_insert_kernel_bss_refs


__ld_insert_compressed_bss_refs
Previous Automatically Inserted Section Contents Next

__ld_insert_compressed_bss_refs inserts relocs in the format defined in __ld_insert_compressed_relocs. The only differences are that the relocation address is not the entry point of the program but the beginning of the BSS section and that the reference symbol used if there is no previous reloc (i.e. for the first reloc) is __ld_compressed_bss_refs_ref.

If you insert these references, the linker assumes that the BSS section is handled by you; that is, you have to allocate it dynamically using __ld_bss_size and use a pointer to it as the relocation address.

Note: The limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_compressed_data_refs, __ld_insert_compressed_relocs, __ld_insert_kernel_bss_refs


__ld_insert_fargo020_bss_refs
Previous Automatically Inserted Section Contents Next

__ld_insert_fargo020_bss_refs acts like __ld_insert_kernel_bss_refs, except that it always outputs the two terminating zero bytes, even if no references into the BSS section exist.

Fargo support must be compiled in for this insertion to be defined.

See also: __ld_insert_kernel_bss_refs


__ld_insert_fargo021_bss_refs
Previous Automatically Inserted Section Contents Next

__ld_insert_fargo021_bss_refs inserts relocs in the compressed format used by Fargo 0.2.1. It acts like __ld_insert_compressed_bss_refs, except that the size of the BSS section is automatically output (as a 2-byte entry) in front of the actual relocation table, and that the reference symbol used if there is no previous reloc (i.e. for the first reloc) is __ld_fargo021_bss_refs_ref. It is expected by Fargo to be at a fixed position: the position of the format flag in the Fargo header. This is currently handled by the definition of the Fargo header.

For more information on inserting and processing relocs, see __ld_insert_kernel_relocs.

Fargo support must be compiled in for this insertion to be defined.

Note: The limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_fargo021_relocs, __ld_insert_kernel_relocs


__ld_insert_kernel_data_refs
Previous Automatically Inserted Section Contents Next

__ld_insert_kernel_data_refs outputs references to the data section in the format defined in __ld_insert_kernel_relocs. The only difference is that the relocation address is not the entry point of the program but the beginning of the data section.

If you read the data from an external variable (see __handle_data_var), you have to use the address of the variable (or a copy) as the relocation address.

Note: The limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_kernel_bss_refs, __ld_insert_kernel_relocs, __ld_insert_mlink_data_refs, __ld_insert_compressed_data_refs


__ld_insert_mlink_data_refs
Previous Automatically Inserted Section Contents Next

__ld_insert_mlink_data_refs outputs references to the data section in the format defined in __ld_insert_mlink_relocs. The only differences are that the relocation address is not the entry point of the program but the beginning of the data section and that the reference symbol used if there is no previous reloc (i.e. for the first reloc) is __ld_mlink_data_refs_ref.

If you read the data from an external variable (see __handle_data_var), you have to use the address of the variable (or a copy) as the relocation address.

Note: The limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_mlink_bss_refs, __ld_insert_mlink_relocs, __ld_insert_kernel_data_refs


__ld_insert_compressed_data_refs
Previous Automatically Inserted Section Contents Next

__ld_insert_compressed_data_refs outputs references to the data section in the format defined in __ld_insert_compressed_relocs. The only differences are that the relocation address is not the entry point of the program but the beginning of the data section and that the reference symbol used if there is no previous reloc (i.e. for the first reloc) is __ld_compressed_data_refs_ref.

If you read the data from an external variable (see __handle_data_var), you have to use the address of the variable (or a copy) as the relocation address.

Note: The limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_compressed_bss_refs, __ld_insert_compressed_relocs, __ld_insert_kernel_data_refs


__ld_insert_kernel_rom_calls
Previous Automatically Inserted Section Contents Next

__ld_insert_kernel_rom_calls can be used to handle ROM calls. It inserts references to ROM calls in the format used by kernels:

  • If the program uses at least one ROM call...
    • 2 bytes: the number of different ROM calls minus 1
    • For each ROM call...
      • 2 bytes: index of the ROM call
      • Relocation table for this ROM call:
        • For each reference...
          • 2 bytes: location (may not be 0)
        • 2 bytes: 0
If a program uses this insertion, it must process it as follows:
  • For each ROM call...
    • For each relocation entry...
      • Get the starting address of the program (via __ld_entry_point);
      • Add the location value;
      • Modify the 4-byte value (offset) at the resulting address:
        • Get the address of the ROM function/variable indexed by index;
        • Add the value of offset;
        • Write the resulting address to the 4-byte space covered by offset.
Before program termination, this process has to be reverted, so that it can be repeated the next time the program starts. Simply deactivating the relocation code would prevent programs from being transferred between devices.

See also: __ld_insert_mlink_rom_calls, __ld_insert_compressed_rom_calls


__ld_insert_mlink_rom_calls
Previous Automatically Inserted Section Contents Next

__ld_insert_mlink_rom_calls can be used to handle ROM calls. It inserts references to ROM calls in a compressed format known from mlink but specifically altered for GCC4TI:

  • If the program uses at least one ROM call...
    • For each ROM call...
      • Mlink-type index of the ROM call. The index is encoded as in __ld_insert_mlink_relocs, with offset being the index of the ROM call for the first entry, and the difference of the index of this ROM call and the index of the previous one for the following ones.
      • An mlink-type relocation table for this ROM call. See __ld_insert_mlink_relocs for the format used. The reference symbol used if there is no previous reloc (i.e. for the first reloc) is __ld_mlink_rom_calls_ref.
    • 1 byte: 0
For more information on processing ROM call relocation, see __ld_insert_kernel_rom_calls.

See also: __ld_insert_kernel_rom_calls


__ld_insert_compressed_rom_calls
Previous Automatically Inserted Section Contents Next

__ld_insert_compressed_rom_calls can be used to handle ROM calls. It inserts references to ROM calls in a compressed format known from Fargo but specifically altered for GCC4TI:

  • If the program uses at least one ROM call...
    • For each ROM call...
      • Compressed index of the ROM call. The index is encoded as in __ld_insert_compressed_relocs, with offset being the index of the ROM call for the first entry, and the difference of the index of this ROM call and the index of the previous one plus 1 for the following ones. The compressed index is considered part of the relocation table that follows, so nibble encoding can be used.
      • A compressed relocation table for this ROM call. See __ld_insert_compressed_relocs for the format used. The reference symbol used if there is no previous reloc (i.e. for the first reloc) is __ld_compressed_rom_calls_ref.
    • 1 byte: 0
For more information on processing ROM call relocation, see __ld_insert_kernel_rom_calls.

See also: __ld_insert_kernel_rom_calls


__ld_insert_kernel_ram_calls
Previous Automatically Inserted Section Contents Next

__ld_insert_kernel_ram_calls can be used to handle RAM calls. It inserts references to RAM calls in the format used by kernels:

  • If the program uses at least one RAM call...
    • 2 bytes: the number of different RAM calls minus 1
    • For each RAM call...
      • 2 bytes: RAM call information:
        • Bits 0 through 13: index
        • Bit 14: type (0: RAM call; 1: extra RAM address)
        • Bit 15: size (0: 4 bytes; 1: 2 bytes)
      • Relocation table for this RAM call:
        • For each reference...
          • 2 bytes: location (may not be 0)
        • 2 bytes: 0
If a program uses this insertion, it must process it as follows:
  • For each RAM call...
    • For each relocation entry...
      • Get the starting address of the program (via __ld_entry_point);
      • Add the location value;
      • Modify the value (offset) at the resulting address (2 or 4 bytes depending on size):
        • If type indicates an extra RAM address:
          • Determine the location of the extra RAM table row indexed by index (see _extraram);
          • Get the correct value for the current calculator from this row;
          Else:
          • Get the address/value of the RAM function/variable indexed by index;
        • Add the value of offset;
        • Write the resulting address/value to the space covered by offset.
Before program termination, this process has to be reverted, so that it can be repeated the next time the program starts. Simply deactivating the relocation code would prevent programs from being transferred between devices.


__ld_insert_kernel_libs
Previous Automatically Inserted Section Contents Next

__ld_insert_kernel_libs can be used to handle library calls. It inserts references to libraries in the format used by kernels:

  • For each referenced library...
    • 8 bytes: library variable name
    • 1 byte: 0
    • 1 byte: minimum version number (see Minimum Library Versions)
  • For each referenced library (again)...
    • 2 bytes: number of imported functions/variables minus 1
    • For each imported function/variable...
      • 2 bytes: index of the function/variable
      • Relocation table for this function/variable:
        • For each reference...
          • 2 bytes: location (may not be 0)
        • 2 bytes: 0
If a program uses this insertion, it must process it as follows:
  • For each library...
    • Do whatever is necessary to check the version and load it into the program's address space;
    • For each relocation entry...
      • Get the starting address of the program (via __ld_entry_point);
      • Add the location value;
      • Modify the 4-byte value (offset) at the resulting address:
        • Get the address of the library function/variable indexed by index;
        • Add the value of offset;
        • Write the resulting address to the 4-byte space covered by offset.
Before program termination, this process has to be reverted, so that it can be repeated the next time the program starts. Since programs and libraries may be moved in memory while they are not executed, they may not simply deactivate the relocation code. This would also prevent programs from being transferred between devices.

See also: __ld_insert_fargo020_libs, __ld_insert_fargo021_libs


__ld_insert_fargo020_libs
Previous Automatically Inserted Section Contents Next

__ld_insert_fargo020_libs can be used to handle library calls. It inserts references to libraries in the format used by Fargo v0.2.0:

  • For each referenced library...
    • 2 bytes: program-relative location of the library name
    • For each imported function/variable...
      • 2 bytes: index of the function/variable plus 1
      • Relocation table for this function/variable:
        • For each reference...
          • 2 bytes: location (may not be 0)
        • 2 bytes: 0
    • 2 bytes: 0
  • 2 bytes: 0
The libraries have to be processed using the method described in __ld_insert_kernel_libs, except that library versions are not implemented by this format.

Note: This insertion is available only if Fargo support is compiled in.

See also: __ld_insert_fargo021_libs, __ld_insert_kernel_libs


__ld_insert_fargo021_libs
Previous Automatically Inserted Section Contents Next

__ld_insert_fargo021_libs can be used to handle library calls. It inserts references to libraries in the format used by Fargo v0.2.1:

  • 2 bytes: number of referenced libraries
  • 2 bytes: program-relative location of the null-separated null-terminated library name list
  • For each referenced library...
    • For each imported function/variable...
      • Compressed index of the function/variable. The format is not the same as for the relocation table. It is encoded using one of the following formats:
        • 1 byte: offset (must be between 0x01 and 0x7F)
        • 2 bytes: offset + 0x8000 (must be between 0x8000 and 0xFFFF)
        where offset is the index plus 1 for the first index, and the difference between the index and the previous index for the following ones.
      • A compressed relocation table for this function/variable. See __ld_insert_compressed_relocs for the format used. The reference symbol used if there is no previous reloc (i.e. for the first reloc) is __ld_fargo021_libs_ref. It is expected by Fargo to be at a fixed position: the position of the format flag in the Fargo header. This is currently handled by the definition of the Fargo header.
    • 2 bytes: 0
  • 2 bytes: 0
The libraries have to be processed using the method described in __ld_insert_kernel_libs, except that library versions are not implemented by this format.

Note: This insertion is available only if Fargo support is compiled in.

See also: __ld_insert_fargo020_libs, __ld_insert_kernel_libs


__ld_insert_kernel_exports
Previous Automatically Inserted Section Contents Next

__ld_insert_kernel_exports can be used to export symbols from a library. It treats all symbols that are declared external and look like "libname@index" or "libname__index" as exported entries. index is a hexadecimal number which must have exactly 4 digits.

__ld_insert_kernel_exports inserts library exports in the format used by kernels:

  • For each exported item...
    • 2 bytes: location (offset from the beginning of the library; may be 0 if nothing was specified)
  • 2 bytes: 0
Note: Since exported entries are stored one after another, skipped entries will take up additional space in the export table. For example, if you only define one symbol called "libname@0010", then there will be 16*2=32 bytes of zeroes in the export table.

See also: __ld_insert_fargo_exports


__ld_insert_fargo_exports
Previous Automatically Inserted Section Contents Next

__ld_insert_fargo_exports can be used to export symbols from a library. It treats all symbols that are declared external and look like "libname@index" or "libname__index" as exported entries. index is a hexadecimal number which must have exactly 4 digits.

__ld_insert_fargo_exports inserts library exports in the format used by the Fargo II kernel:

  • For each exported item...
    • 2 bytes: location (offset from the beginning of the library; may be 0 if nothing was specified)
Note: Since exported entries are stored one after another, skipped entries will take up additional space in the export table. For example, if you only define one symbol called "libname@0010", then there will be 16*2=32 bytes of zeroes in the export table.

This insertion is available only if Fargo support is compiled in.

See also: __ld_insert_kernel_exports


__ld_insert_preos_compressed_tables
Previous Automatically Inserted Section Contents Next

__ld_insert_preos_compressed_tables is the most complex of the automatic insertions. It inserts all relocation-related tables in the compressed format expected by PreOs 0.68 or higher. PreOs expects those tables to be pointed to by the same pointer, so they need to be inserted all at once. The reference address expected by PreOs is the same for all relocation tables: 36 (0x24). It is defined as the end address of the smallest possible header/stub combination. (However, the smallest possible stub is not usable in practice because it does not emit any error messages. Therefore, the address does not correspond to any actual address in GCC4TILIB, so it is hard-coded in the linker.) The tables it inserts are, in order:

  • Library import table:
    • For each referenced library...
      • 8 bytes: library variable name
      • 1 byte: 0
      • 1 byte: minimum version number (see Minimum Library Versions)
    • For each referenced library (again)...
      • PreOs index (see below): number of imported functions/variables minus 1
      • For each imported function/variable...
        • PreOs index (see below): index of the function/variable (relative to the previous one)
        • Relocation table for this function/variable. See __ld_insert_compressed_relocs for the format used.
  • ROM call import table:
    • PreOs index (see below): the number of different ROM calls minus 1
    • For each ROM call...
      • PreOs index (see below): index of the ROM call (relative to the previous one)
      • A compressed relocation table for this ROM call. See __ld_insert_compressed_relocs for the format used.
  • RAM call import table, in the same format as the ROM call import table. The indices used are the indices after setting the size and type flags described under __ld_insert_kernel_ram_calls.
  • Relocation table: See __ld_insert_compressed_relocs for the format used.
  • BSS relocation table:
    • 2 bytes: BSS size / 4
    • A compressed relocation table. See __ld_insert_compressed_bss_refs for the format used.
PreOs uses a special format for the indices. It is not the same as for the relocation table. Instead, a PreOs index is encoded using one of the following formats:
  • 1 byte: offset (must be between 0x00 and 0xFD)
  • 2 bytes:
    • 1 byte: 0xFE
    • 1 byte: offset - 0xFE
  • 3 bytes:
    • 1 byte: 0xFF
    • 2 bytes: index (not offset!)
where index is the actual index, and offset is index + 1 for the first index and the difference between index and the previous index for the following ones.

Note: Since parts of this insertion are dealing with relocs, the limitations of __ld_insert_kernel_relocs also apply to this insertion.

See also: __ld_insert_compressed_relocs, __ld_insert_compressed_rom_calls, __ld_insert_kernel_ram_calls, __ld_insert_compressed_bss_refs


__ld_insert_nostub_comments
Previous Automatically Inserted Section Contents Next

__ld_insert_nostub_comments is used to export data symbols in the NoStub comment header. It treats all symbols that are declared external and look like "_nostub_data__index" as exported entries. index is a hexadecimal number which must have exactly 4 digits.

__ld_insert_nostub_comments inserts data exports in the format used by the NoStub comment specification:

  • For each exported item (in ascending ID order)...
    • 2 bytes: export ID (type index of the export, as specified after the double underscore)
    • 2 bytes: location (offset from the beginning of the program)


__ld_insert_data_var_name
Previous Automatically Inserted Section Contents

__ld_insert_data_var_name inserts an ANSI string containing the name of the data variable as specified during the invocation of the linker. A terminating zero byte is appended; however, the name does not automatically start with a zero byte.


GCC4TI Linker Binary Code Fixup
Previous The GCC4TI Linker Next

The GCC4TI linker can do many operations on binary code. If you want it to behave correctly in all cases, you need to make sure that no executable code is included in a data section, and no data is included in a code section. However, GCC4TI usually merges all data into the code section to optimize references to it, so in rare cases it is possible for the linker to generate incorrect code.

Binary code fixup is divided into several categories:

  • NOP Instruction Removal
  • Return Sequence Optimization
  • Branch Fixup and Optimization
  • Move/Load/Push Instruction Optimization
  • Compare/Test Instruction Optimization
  • Calculation Instruction Optimization


NOP Instruction Removal
GCC4TI Linker Binary Code Fixup Next

The GCC4TI linker features the removal of unnecessary NOP instructions. For file formats which may insert a NOP (No OPeration) instruction at the end of a section in order to align its size to a specific boundary, it can remove this instruction to save a little space. Currently only the AmigaOS format is known to do this (see GCC4TI Linker File Formats). If the section ends with more than one NOP instruction, all instructions are kept.


Return Sequence Optimization
Previous GCC4TI Linker Binary Code Fixup Next

The GCC4TI linker can optimize function return sequences. If a section ends with a subroutine branch followed by a simple return instruction, the subroutine branch is converted into a simple unconditional branch (jump), and the return instruction is removed. Note that this may fail easily if there is a branch to the return instruction somewhere; if the return instruction is removed, the branch will point to arbitrary code or data. You can make this less likely by telling the assembler to emit all local labels, so the linker knows it cannot optimize a return sequence because there is a label in front of the return instruction. With the GNU Assembler, this is done by using the '--keep-locals' option, which is included automatically if range-cutting is enabled. With the A68k Assembler, the '-d' switch does the job.


Branch Fixup and Optimization
Previous GCC4TI Linker Binary Code Fixup Next

On some architectures, certain branches are not permitted. For example, on the MC68000 processor, it is not possible to branch to the next instruction using a short branch. While the assembler usually detects such invalid situations, they may still occur if the branch target is in a different section or file. The GCC4TI linker detects such invalid situations and tries to resolve them as well as possible: If it is invalid for a branch at the end of a section to point to the beginning of the next section, it is removed unless it is a subroutine branch. For subroutine branches, a NOP instruction is inserted instead.

In addition to fixing invalid branches, the GCC4TI linker can optimize branch instructions to reduce the number of absolute relocations needed. If an absolute branch (jump or subroutine branch) can be converted to a relative branch, the operating system does not need to insert the destination address at run time; therefore this will save space. Moreover, if range-cutting is enabled, optimizing branches can reduce the size of the code.

  • F-Line Branch Optimization


F-Line Branch Optimization
Branch Fixup and Optimization

The linker can convert absolute branches (which would normally need a relocation entry) into special relative F-Line sequences. These sequences are handled by an interrupt handler. The fact that an interrupt is needed makes these branches significantly slower, but using them can save quite a bit of space in the program.

There are two types of F-Line branches: The default version can be activated using the __ld_use_fline_jumps control symbol. Each branch has a size of six bytes. They are relative to their own address, which means that they can be supported by the AMS, and in fact, the AMS implements an interrupt handler for these branches starting from version 2.04. The other version can be activated using the __ld_use_4byte_fline_jumps control symbol. As the name says, each branch has a size of four bytes. They are relative to the program's entry point, so only an emulator that is installed from the program can handle them. Since they use codes that are otherwise used for ROM calls, this might break applications that are called from the program, if any. However, this is very unlikely, as the two ROM calls used are not defined yet.


Move/Load/Push Instruction Optimization
Previous GCC4TI Linker Binary Code Fixup Next

If this type of optimization is turned on, then the GCC4TI linker optimizes all instructions that move data between two places. This includes instructions to move data between memory and registers or between two places in memory, instructions to load the address a of memory location into a register, and instructions to push the contents of a memory location on the stack. Note that due to the great variety of such instructions, this optimization is more likely to cause errors than others.

This optimization can reduce the number of absolute references to locations inside the program, and it can also decrease the size of the code if range-cutting is enabled.


Compare/Test Instruction Optimization
Previous GCC4TI Linker Binary Code Fixup Next

If this type of optimization is turned on, then the GCC4TI linker optimizes all instructions that compare the contents of a memory location with something. This includes operations that compare data and operations that test whether something is zero.

This optimization can reduce the number of absolute references to locations inside the program, and it can also decrease the size of the code if range-cutting is enabled.


Calculation Instruction Optimization
Previous GCC4TI Linker Binary Code Fixup

If this type of optimization is turned on, then the GCC4TI linker optimizes all instructions that perform calculations based on data stored in memory. This includes addition, subtraction, multiplication, division, and bitwise manipulation instructions.

This optimization can reduce the number of absolute references to locations inside the program, and it can also decrease the size of the code if range-cutting is enabled.


ld-tigcc Program Dumps
Previous The GCC4TI Linker Next

If you turn on dumps in ld-tigcc (using the '--dump[n]' option), ld-tigcc prints the contents of the internal data structures to standard output between various events during the linking stage. These places are numbered, so that you can turn on a specific dump by adding an index to the option. The following table shows the current location of the different dumps:

Dump 0
This dump is produced just after all object files have been imported. Relocation entries that refer to different files have not been resolved yet; neither have ROM/RAM/library call symbols been translated into actual ROM/RAM/library calls. Archive members have only been imported if this was specified by a global import.

Dump 1
Relocation entries have been resolved to the maximum extent possible. If they could not be resolved to existing symbols or had been treated as RAM/ROM/library calls, archive members have been imported for them.

Dump 2
All uninitialized and zero-data sections have been merged, as well as all data sections if this was necessary. Automatic global imports have been added.

Dump 3
All global imports have been processed; even the ones which contained negations.

Dump 4
Relocation entries from the archive members which were just imported by global imports have been resolved, possibly importing new archive members. If relocation optimization is enabled, another dump is appended with the same contents after relocation optimization. If removal of unused sections is enabled, a third dump is inserted after this removal.

Dump 5
All sections which are not externalized have been merged. Note that some parts of the code fixup need to be done just before the sections are merged, so there is also a lot of code fixup and optimization between dumps 4 and 5.

Dump 6
The remaining code fixup and optimization has been performed.

Dump 7
Certain built-in symbols whose value depends on the program contents have been resolved. Insertions that were requested to be added at an arbitrary place have been added to the end of the program.

Dump 8
Relative relocation entries have been replaced by the actual distances they had represented.
The program dumps are usually self-explaining; however, a few items require special attention:
<nB: target [- relation] [+/- offset]>
Indicates a relocation entry or ROM/RAM/library call. target and relation have the form symbol[+/-offset], which stands for the address of symbol, corrected by offset. n specifies the number of bytes reserved for the address/offset of the target.

<nB: ... (rel)>
Indicates that the relocation entry is relative to its own address.

<nB: symbol (?) ...>
Indicates a relocation entry which has not been resolved yet.

<nB: symbol (->) ...>
Indicates a relocation entry pointing into another section.

<nB: ...> (!)
Indicates that the section data at the place of the relocation entry is nonzero. This usually indicates a problem, but in rare cases, it is valid. For example, if you use ROM/RAM/library calls with an offset, this offset is usually emitted into the section contents, but the actual call still exists.

address: (!)
Indicates an internal inconsistency (for example an item outside of a section, overlapping items, or an internal ordering error).
Section offsets and data are always output in hexadecimal notation. Question marks indicate uninitialized data, which may have random content.


Recompiling ld-tigcc and ar-tigcc
Previous The GCC4TI Linker

Recompiling ld-tigcc and ar-tigcc (or the corresponding link DLL) from source may be useful if you want to make the linker as efficient as possible by disabling certain features. Recompilation requires GCC and GNU make. If you are using Linux, you may simply run make in the source code directory; the same is probably true for other Unix variants. If you are using Windows, you need to download MSYS or make some minor modifications to the makefile.

If you only want to disable some features, you can take a look at the definitions in the makefile (the file called Makefile). The DEFINES variable contains the general features to be included; EXE_DEFINES contains the features that should only be included in the executable files (not in the DLL). All available definitions are documented at the top of generic.h.

For example, if you want to disable support for the AmigaOS files generated by the A68k Assembler, you may simply remove the '-DAMIGAOS_SUPPORT' definition from the DEFINES variable. Note that some combinations are invalid; for example, if you disable support for all object file formats, you will get a "file format not recognized" error whenever you try to link some files.


The GCC4TI Integrated Environment

The GCC4TI IDE is a freely distributable Integrated Environment for GCC4TI, written by Sebastian Reichelt (retired years ago from TI-68k programming). It is easy to use, even for unexperienced programmers. This part of the documentation was written by Sebastian.

  • Configuring the IDE
  • Starting a New C Project
  • Starting a New Assembly Project
  • Adding Existing Files
  • Using Header Files
  • Saving and Renaming Source Files
  • Editor Features
  • Compiling and Running your Program
  • Special Features
  • Planned Features
  • Disclaimer
  • Feedback
  • Version History

Note: If you want to use the command-line compiler to compile .tpr files produced by the IDE, you can use the tprbuilder utility. It takes the name of a .tpr file as a single parameter. You may have to tweak your source files a little, as the IDE uses a different compilation scheme.


Configuring the IDE
The GCC4TI Integrated Environment Next

Click on 'File/Preferences'. In the 'Preferences' dialog box, you can customize the IDE with various options. Some options are very important, others are simply user interface settings.

If you want to be able to cancel compiling operations more quickly, you can choose to force-quit the application used for the process. This is not recommended, however, and can make your system unstable. If you do not choose this option, the IDE compilation window remains on the screen until process is finished. If you click on 'Stop' again, the process will finally be terminated. If you choose this option, you should also activate the 'Auto-Save' option.

If you want to be able to react to compilation errors more quickly, you can choose to stop compilation when the first file was not compiled successfully. Otherwise, the IDE compiles all files, displaying all errors in the error list.

When a program is compiled, usually assembly as well as object files are produced and stored in the project folder. You can have them deleted automatically after the program was linked successfully.

There is one extremely important option: the automatic splitting of source files into more lines. This is done in order to accurately find the position of errors in your code. It might, however, result in an error being reported when there is nothing wrong with the code. This is unlikely, though, since this option has been tested very thoroughly.

Another important option is the Template Wizard. It helps you to get started with a project when you add your first file. If you disable it, default options will automatically be used.

To be able to run your program directly from the IDE, you need to specify either to run on VTI, on TIEmu, or you need to select your link port and cable type. Do this in the 'Transfer' tab. You can switch between the two very quickly by pressing Shift+Ctrl+Alt+F9.

In the 'Syntax Highlighting' tab, you can set your own settings for both ASM and C files. If syntax highlighting takes up too much time when opening a project, you may want to disable it.

To customize syntax highlighting, you can specify your own colors and styles for different types of characters using the buttons provided. To set colors and styles for comments, strings, and compiler directives, use the tree at the bottom of the dialog. To edit such a 'custom style', double-click on it. You can also specify the exact beginning and end, using '#13' as substitute for the end of the line.

In this tree, you can also create your own custom set of words that are supposed to be highlighted some way. Only a list of reserved words is included by default, but you can add lists of your own if you want to.


Starting a New C Project
Previous The GCC4TI Integrated Environment Next

Click on 'File/New/Project'. If the project you had opened before has been modified, you are informed about it, and you have the choice to save your project first.

When you create a new project, it is best to save it first in order to give it a file name. Click on 'File/Save Project As...' and save your project. Note that the executable files (*.89z; *.9xz; *.v2z) are saved with the same name as your project file, even if it is a long file name. To specify the name your program gets when it is transferred to the calculator, click on the top item in the project tree twice in a row in order to rename it (optionally including a folder name). Of course, the same restrictions apply as to calculator variable names. For other options, look under 'Project/Options...', especially 'Program Options...' in the 'Compilation' tab.

After you did that, you need to create a new C file to start with. Click on 'File/New/C Source File'. A file template is displayed, where you can simply add your code at the position where it says:

// Place your code here.

Click on 'Help/Index' for a complete documentation of functions supported by the GCC4TI Library, and you can start programming.


Starting a New Assembly Project
Previous The GCC4TI Integrated Environment Next

To start a new Assembly project, you have to perform the same steps as for a C project; the only difference is that you have to click on 'New/GNU Assembly Source File' or 'New/A68k Assembly Source File' instead. Note that you can also have a mixed project with both file types. Assembly projects are not supported and tested as well as C projects.


Adding Existing Files
Previous The GCC4TI Integrated Environment Next

To add an existing file, click on 'Project/Add Files...' and select the files you want to add. These can be C or Assembly source files, header files, or object files. Generally you can include any file that belongs to your project, even text files, in order to edit them and to keep them together. Source files always have to be added to the project in order to be found.


Using Header Files
Previous The GCC4TI Integrated Environment Next

Header files can be either C or Assembly files. If you know enough about C, you can create C-style header files, create C source files implementing the functions defined in the header files, and export functions from them. Note that you always have to add the header and either the source or object files if you want to use them in another project. There is also a common include folder for general-purpose header files.

When you create a C-style header file, you can only include it in C source files. Similarly, if you create an Assembly-style header file, you can only use it in Assembly source files.

For tab width and syntax highlighting, it is necessary that you indicate what type of header file you are creating by using a comment at the beginning. If you enabled the Template Wizard, you can choose what type of header file you want to create.

Files included in A68k files with 'incbin' have to be in the 'other files' section.


Saving and Renaming Source Files
Previous The GCC4TI Integrated Environment Next

To rename a source file, simply rename it in the project tree. To save it with a different name, click on it with your right mouse button, and select 'Save As...' from the popup menu.

To save changes to a file, right-click on it and select 'Save'. You can also click on 'File/Save All' to save all files.


Editor Features
Previous The GCC4TI Integrated Environment Next

To print the current source file, click on 'Print...' from the menu or the toolbar. To find or replace text, use the 'Find' menu. There you will also find a menu item to jump to a function in the editor. Note that this can be done much quicker using the toolbar.

If you want to open a source file whose name is in the current source code, move your cursor to the file name and press Ctrl+Enter. If the file is not included in the project, it will be opened in a popup editor.

If the cursor is on an identifier, press F1 to display help on that identifier.

You can use Ctrl+Tab or Ctrl+G to switch between source files. Files in the project tree which are not visible at the moment are skipped.

Press Ctrl+Space or Ctrl+M to activate auto-completion for the current word. Press Ctrl+J to use a predefined template.


Compiling and Running your Program
Previous The GCC4TI Integrated Environment Next

To compile and run your program, press F9, or select 'Run' from the 'Debug' menu. Like 'Project/Make', this will perform all the steps necessary to create the executable file; then it will send the file to the device or program you specified in the preferences. If some files are not compiled, but they have been changed or need to be recompiled for some reason, click on 'Project/Build'.

You can also choose only to compile all files without creating an executable file by clicking on 'Compile'. A 'Compile' item is also available for each source file in the popup menu of the project tree.

If you need to change the link order of files, you can do this by dragging a file to another place in the same file group. You can use drag and drop also to move files between categories.

In the project options, you can specify how your program is built. This also includes automatic compression. If you use this feature, two files will be compiled: a small starter program and a compressed program file. The on-calc variable name that you specify cannot be the same as the on-calc variable name of your program (which will be the name of the starter program in this case).

In the same dialog, you can also enter the starting parameters for your program. These parameters are pasted into the command line between the parentheses.

If one or more errors were found when compiling, an 'Errors and Warnings' box is displayed at the bottom of the main window. If you click on an error, the IDE jumps to the position in the source file where the error occured, if the position is available.

The compiler stops at errors, but not at warnings. To turn warnings off, use the switches available in 'Project/Options...'. Click here for details about switches supported by the GCC compiler. Note: Not all of these switches can be used from the IDE.

If you are experienced in the use of GDB to track down runtime errors, the 'Debug Information' option may help you. If you set it, GCC4TI will generate a .dbg file which allows you to debug your program using a GDB-enabled version of the TiEmu emulator.


Special Features
Previous The GCC4TI Integrated Environment Next

Auto-Indenting:
If you press Enter in the editor, the cursor will be under the first non-whitespace character of the previous line.

Auto-Blocks:
If you press '{' on a new line, the corresponding '}' is created automatically, and all formatting with tabs is done automatically as well. You can disable this feature.

Error Tracking:
Even if you edit a source file, clicking on an error will still jump to the correct position. Optionally, error list entries are deleted when you delete the character that caused the error.

File Date Checking:
Files are compiled only if they were modified since the last compilation.

Keyword Search:
Pressing F1 on a GCC4TI Library function or a keyword will search the index for that function.

Code Auto-Completion:
The editor implements several features to make writing code using the predefined library calls easier.


Planned Features
Previous The GCC4TI Integrated Environment Next

  • A built-in debugger
  • A sprite editor producing C or ASM header files
  • Program context help


Disclaimer
Previous The GCC4TI Integrated Environment Next

I cannot be held responsible for any error or system failure caused by this program or any programs related to it. Use this program at your own risk.


Feedback
Previous The GCC4TI Integrated Environment Next

Feel free to contact us if you have any questions, comments, or bug reports. If you found a bug, please don't just think we will probably find it, because we probably won't. Instead, please use the ticket tracker at http://trac.godzil.net/gcc4ti/.


Version History
Previous The GCC4TI Integrated Environment

Version 2.96 (June 2009) - GCC4TI

  • Added more instructions and macros to the default lists used for syntax coloring.
Version 2.95 (January 2009) - GCC4TI
  • Added several instructions and macros to the default lists used for syntax coloring.
  • Restored VTI support in addition to TIEmu support, as requested by multiple experienced TI-68k programmers ever since it was removed from TIGCC.
Version 2.94 (October 2006) - TIGCC
  • Improved keyboard accelerators (added missing ones and fixed conflicting ones).
  • Added Only at beginning of line checkbox to the Edit Custom Style dialog.
  • Fixed inverted logic bug in approximate matching for prototype helps.
  • Fixed detection of '??=' in source file splitting.
  • Changed the Debug menu to use TiEmu (20061030 or later) instead of VTI as the emulator target.
Version 2.93 SP1 (July 2006)
  • Various minor bugfixes.
Version 2.93 (April 2005)
  • Added support for Mlink-format relocs.
  • Added support for Windows XP theming.
  • Added support for DWARF 2 debugging information.
  • Fixed multi-line strings in macros in the source splitter.
Version 2.92 (August 2004)
  • Added support for the new linker, which is now a DLL.
  • Added support for data variables.
  • Added support for on-calc folder names.
  • Removed the Template Wizard in favor of global program options.
  • Added a template for comment data.
  • Added support for virtual folders used when compiling programs.
  • Added an option not to jump to the first error.
  • Integrated the calculator linking code into the program.
  • Made project loading faster by not loading all files immediately.
  • Added ability to copy error messages to clipboard.
  • Added code completion patches by Ephyx.
  • Various minor fixes and additions.
Version 2.91 (November 2002)
  • Replaced the title and wizard images and the icons by new ones created by Gereon Kindler.
  • Implemented storing file names in relation to the project directory.
  • Added optional drag and drop text editing.
  • Speeded up source file splitting.
  • Implemented a "Remove Trailing Spaces" feature.
Version 2.9 (December 2001)
  • Added a recent files list.
  • Added a customizable tools menu.
  • Added the possibility to move files between categories.
  • Changed the search function to search through all files.
  • Added a window showing the complete output of the program called most recently.
  • Changed the print function to use the Windows driver instead of printing directly.
  • Added proxy support in the news download.
  • Changed the role of Tab and Shift+Tab to indent and unindent selected text, and enabled Shift+Backspace.
  • Added support for the 'incbin' A68k directive with 'other files'.
  • Added the possibility to specify a path for Virtual TI.
  • Added 'none' as a possible target to send the file to.
  • Fixed a bug with overwriting existing files.
  • Implemented selection by holding down Shift and clicking.
  • Fixed the editor to be able to display all fixed-width fonts.
  • Fixed the function list to be more reliable.
Version 2.8 SP3 (November 2001)
  • Fixed the bug which would make closing large files really slow.
  • Implemented a Ctrl+Tab shortcut to switch between files.
Version 2.8 SP2 (September 2001)
  • Introduced special mouse wheel support for people with wheel problems.
  • Added the possibility to run a batch file after building.
  • Added a detection to warn if a file was modified on the disk.
Version 2.8 SP1 (April 2001)
  • Fixed send to calc/VTI support for the TI-92 Plus.
  • Shift+Ctrl+Alt+F9 shortcut for calc/VTI switch.
Version 2.8 (March 2001)
  • Background compilation.
  • Support for linking multiple files through the GNU linker.
  • Support for creating and using archives.
  • Creation of debug information in the .s file.
  • Drag and drop support from the explorer.
  • Headline download (manually and automatically).
  • Send to calc/VTI support.
Version 2.71 (November 2000)
  • Support for GNU assembly files.
  • Fixed support for BSR calls.
  • Support for compressing files.
  • Automatic inclusion of patches.
  • Better automatic '{...}' blocks.
  • Support for viewing compiler output.
Version 2.7 (October 2000)
  • Completely self-written new editor with syntax highlighting.
  • Support for opening external files.
  • Support for version 2.2 of the TIGCC Library.
  • Support for the newly recompiled version of TIGCC.
  • Function menu.
  • Automatic '{...}' blocks.
  • Shortcuts for increasing and decreasing the indent.
  • Source file splitting to find error positions.
  • Complete error tracking and deletion.
Version 2.6 (June 2000)
  • Part of TIGCC package from now on.
  • Fixed a lot of bugs.
  • Included help file by Philipp Winkler.
  • Works with new folder structure.
  • Customizable link order.
  • Progress bar with stop button for syntax highlighting.
  • More preferences.
  • Compilation animation.
  • Floatable toolbar.
  • Startup screen.
Version 2.5 (May 2000)
  • Included ASM syntax highlighting.
  • Included support for version 2.0 of the TIGCC library.
  • Updated error list.
  • Fixed C/ASM bug in previous release.
Version 2.4 (May 2000)
  • Updated preferences dialog.
  • Customizable syntax highlighting.
Version 2.3 (May 2000)
  • Never officially released.
  • Syntax highlighting (no customization; C only).
Version 2.2 (May 2000)
  • Never officially released.
  • Bugfixes.
  • New compilation window.
  • Bringing VTI into foreground.
Version 2.11 (May 2000)
  • Editor bugfixes.
Version 2.1 (May 2000)
  • File date checking bugfix.
  • More IDE options.
  • Find and print functions.
  • TIGCC installer.
  • Ctrl+Enter shortcut.
  • Word wrap (now uses rich text edit control).
Version 2.0 (May 2000)
  • Never officially released (beta) (too many missing features and bugs).
  • File date checking.
  • Assembler bug workaround.
  • Stable force-quit operation.
  • Toolbar, status bar, icons in menus.
  • More editor options.
  • Header file error display.
Version 1.0 (April 2000)
  • Initial release.
  • Included all three programs.
  • Fully functional IDE.
  • Extraction of errors from all three programs.
  • Almost 100% accurate error tracking.
  • Use of projects.


Information for Assembly Programmers

TI's OS for TI-68k calculators, AMS, has a rich set of built-in functions, but unfortunately many of them are not yet documented by TI. However, some entry points are documented. As many functions which I defined in this library are just OS calls, the documentation of these functions is also the documentation of OS calls. This means that this document documents more than 600 OS calls, so it may be very valuable for assembly programers. When the function is nothing more than simple OS call, I give to it either the name used in TI's list of OS entry points, or a name invented by someone. So you can easily determine which functions are simple OS calls.

Of course, function parameters are listed using the C language calling convention, because this is a library for C programing. If you are an assembly programmer, you need to know the following:

  • Parameters are pushed onto the stack in reverse order.
  • "short" types occupy two bytes, and "long" types occupy four bytes. "int" types usually occupy two bytes, except if the user specifies the '-mlong' compiler switch; in such case "int" occupies four bytes. All pointer types occupy four bytes. A float type occupies ten bytes.
  • Although the "char" type occupies just one byte, it must be promoted to a word before pushing it on the stack.
  • To clean up after the function has been called, pop all the values that were pushed. This can be done by adding a value to SP; this value is calculated by summing the sizes of all the parameters that were pushed.
  • Assume that D0-D2/A0-A1 are destroyed by any given ROM function upon return.
  • Any function which returns any non-pointer type (char, short, int, long), including not-too-long structures (like HSym), keeps the result in the register D0.
  • Any function which returns a pointer type keeps the result in the register A0.
  • All OS functions which return a floating point value (like most functions from timath.h header file) expect that before calling A6 points to the byte after the end byte of 10-byte long buffer where the result will be stored (usually this is a preallocated space on the stack frame). Note that this is not the same as GCC convention for returning floating point values: GCC returns floats in a triplet [D0.l;D1.l;D2.w]. That's why implementing floating point routines was not so easy, especially because A6 is a very important register (used in GCC as the frame pointer).
Many users ask me for examples, especially about the usage of floating point functions in ASM programs. I expected that everything I wrote is so clear (for anybody who knows C syntax), but it seems that it is not. OK. I will give two examples (the second one deals with floats):

Example 1:

Look at the DrawClipEllipse function from the graph.h header file. It is declared as

void DrawClipEllipse (short x, short y, short a, short b, const ScrRect *clip, short Attr);

If you want to simulate the following call
DrawClipEllipse (100, 50, 30, 20, &(SCR_RECT){{0, 0, 159, 99)}, A_NORMAL);
in the ASM program, you should do the following code (kernel calling convention will be assumed, due to simplicity):
       move.w #1,-(sp)
       pea    clip(pc)
       move.w #20,-(sp)            ; Using move.l #$1E0014,-(sp) you can pack
       move.w #30,-(sp)            ;  these two ASM instructions into one
       move.w #50,-(sp)
       move.w #20,-(sp)
       jsr    tios::DrawClipEllipse
       lea    (sp,14),sp           ; The same as add.l #14,sp but shorter
       ...
clip:  dc.b   0,0,159,99           ; Components of SCR_RECT structure are bytes

Example 2:

This example will show to you how to use floats in ASM programs. Look at the functions log, fmul and trunc from the timath.h header file. They are declared as

float log (float x);
float fmul (float x, float y);
long trunc (float x);

Suppose that you want to calculate the integer part of 2.34*log(342.1178). First, you need to know that hexadecimal representations for 2.34 and 342.1178 are $40002340000000000000 and $40023421178000000000 (see bcd if you don't know why). Also, note that bcdmul and bcdlong are original OS names for functions aliased as fmul and trunc (don't be misleaded by the fact that the library defines fmul & trunc to work with native float type and bcdmul & bcdlong to work with bcd structures; at the fundamental ASM level they are exactly the same routines). Then, this calculation may be performed using the following ASM program:
       lea    after(pc),a6         ; Prepare a6 for storing results
       clr.l  -(sp)                ; Push 342.1178
       move.l #$34211780,-(sp)
       move.w #$4002,-(sp)
       jsr    tios::log            ; The result is now in "temp"
       move.l (a6,-4),-(sp)        ; Push the result
       move.l (a6,-8),-(sp)
       move.w (a6,-10),-(sp)
       clr.l  -(sp)                ; Push 2.34
       clr.w  -(sp)
       move.l #$40002340,-(sp)
       jsr    tios::bcdmul         ; The result is again in "temp"
       move.l (a6,-4),-(sp)        ; Push the result again
       move.l (a6,-8),-(sp)
       move.w (a6,-10),-(sp)
       jsr    tios::bcdlong        ; The final result is now in d0
       lea    (sp,40),sp           ; Clean up the stack
       ...
temp:  ds.b   10                   ; Ten-byte buffer
after: ...
This program may be much more optimized if you know how to use stack frames properly (this technic is so popular in high-level language compilers, but quite unpopular in ASM programs; this example shows that stack frames may be very useful). The optimized version of the same program follows:
       link   a6,#-10              ; Create 10-bytes long space on the stack
       clr.l  -(sp)                ; Push 342.1178
       move.l #$34211780,-(sp)
       move.w #$4002,-(sp)
       jsr    tios::log            ; The result is on the stack frame
       addq.l #6,sp                ; Adjust the stack pointer
       clr.l  (sp)                 ; Push 2.34
       clr.w  -(sp)
       move.l #$40002340,-(sp)
       jsr    tios::bcdmul         ; The result is again on the stack frame
       lea    (sp,10),sp           ; Adjust the stack pointer again
       jsr    tios:bcdlong         ; The final result is now in d0
       unlk   a6                   ; Remove the stack frame
Note: Some of the information about OS calls given by TI itself on their site is incomplete or even wrong. This document contains more precise information.


Contact Information

If you have any questions, suggestions, problems, corrections, bug reports, and especially if you have some information about OS routines not known to me, please contact us at

http://trac.godzil.net/gcc4ti/

Please, inform us about any noticed problem with the library and the documentation (including wrong links in the documentation). This will help us to correct the problem in a next release. However, please use the ticket tracker on http://trac.godzil.net/gcc4ti/ for all other problems.

If you have a general GCC4TI programming question, it is a good idea to see whether it is already answered on the TICT & GCC4TI/TIGCC programming message board, or the GCC4TI message board. If not, you can post your question there.

Note: Before asking a question, please check whether this question is already answered in the Frequently Asked Question list !


Copyright Notes

As GCC4TI, like TIGCC, is a complex team project, various parts of it have been made by different authors:

ld-tigcc Copyright (C) 2002-2009 Sebastian Reichelt and Kevin Kofler, licensed under the GPL
Library & Documentation Copyright (C) 2000-2010 Zeljko Juric and contributors, licensed under the GPL with libgcc exception
IDE Copyright (C) 2000-2009 Sebastian Reichelt and contributors, licensed under the GPL

Some parts of the GCC4TI package (cpp, gcc, as, ld, ar, objcopy) are modified parts from the GNU Compiler Collection and GNU BinUtils packages. These parts are free software; you can redistribute them and/or modify them under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Parameter passing by register Copyright (C) 1998-2003 Fred Fish from Geek Gadgets; converted to GCC 3.0 and higher by Kevin Kofler.

Thomas Nussbaumer holds the copyright for the TI-68k Developer Utilities, from which the compression feature was taken. The TI-68k Developer Utilities are licensed under the LGPL, and the "pctools"' upstream version has become GCC4TI.

a68k (also included in the package) is a freeware assembler by Charlie Gibbs (it is a somewhat modified Amiga version).

Special copyright notes about the documentation and the library:

All information presented in the documentation are strictly mine, not by Texas Instruments (except information about GNU products, which are based on the original GNU manuals). All of TIOS-specific information in this document are result of a hours of work with the debugger. But I need to give credits to Gareth James: his informational files, although extremely briefly, help me a lot to understand some particular TIOS secrets.

The GCC4TI library and documentation is absolutely free for any distribution if you don't change anything in this package. But, to give credit to my hard work, please do the following:
  • If you use any routine from this library in your program, put this fact in the documentation of your program;
  • If you use a routine in your assembly program which usage wasn't known to you before reading this documentation, put this fact in the documentation of your program.
I simply want that this documentation to become known to as many C and assembly programmers as possible.

Note that this is Zeljko's original license for the library. Zeljko has since approved its release under the GPL with the libgcc exception (allowing you to freely link the code with both GPLed and non-GPLed programs without restrictions). Still, we would appreciate being credited for our work.


History of the Library

Release 2.72 (27 VI 2009.) - GCC4TI

  • Added: Some contributions to bascmd.h, basop.h, estack.h and other files.
  • Bugfix: Several minor documentation mistakes fixed.
  • Updated: Removed the essentially unused shrnklib support from pstarter.
  • Updated: Optimized the ttunpack-fast code by applying the same calling convention changes as those applied in the ttunpack code (saves about 34 bytes, i.e. > 2%).
  • Updated: Optimized the SAVE_SCREEN startup code (Martial Demolins).
  • Updated: Optimized the internal F-Line emulator setup & cleanup code (Martial Demolins, Lionel Debroux).
  • Updated: Optimized the VTI detection in __hw_version (Lionel Debroux).
  • Updated: Optimized _rowread (Martial Demolins).
  • Updated: Optimized OSVFreeTimer & OSVRegisterTimer (Martial Demolins, Lionel Debroux).
  • Updated: Optimized Sprite8, Sprite16 & Sprite32 while adding support for the SPRT_RPLC mode (Joey Adams, Lionel Debroux).
Release 2.71 (3. I 2009.) - GCC4TI
  • Bugfix: Removed obsolete (wrong for current AMS) definition of doorsos::OSOnBreak which conflicts with the ROM_CALL.
  • Bugfix: Added missing format attribute from sprintf in printf_xy.
  • Bugfix: Set CESI and ESI as needed by the callback types using them.
  • Bugfix: Fixed sign comparison warning in _keytest_optimized with OPTIMIZE_CALC_CONSTS.
  • Bugfix: Fixed atan2 prototype.
  • Bugfix: Fixed typo in __fscanf_unget (move.l -> move.w).
  • Updated: In pstarter, moved handles in front of program name so the program name can be changed to a name with odd length.
  • Bugfix: Added missing earlyclobbers for ldiv, reported by Mike Kennedy.
  • Bugfix: Fixed reference to nonexistent flag FO_SKIP_TWINS (should be FO_RETURN_TWINS, reported by "hypersonic" Peter Fernandes).
  • Added (TIGCC, GCC4TI): C99 standard header stdint.h.
  • Added (GCC4TI): A subset of C99 standard header inttypes.h.
  • Bugfix (GCC4TI): Made it easy to move HSF files around, without having to rewrite a set of tools right now, by adding consistent explicit references to headers where they lack.
Release 2.7 (31. X 2006.) - TIGCC
  • Added: Contributions to dialogs.h, files.h (new), graphing.h (new), and other files.
  • Bugfix: Several minor documentation mistakes fixed.
  • Updated: GrayDBufToggleSync now works properly on HW1.
  • Bugfix: Fixed %[ conversion in scanf family routines.
  • Added: A few new examples contributed by Jocelyn Berrendonner, S�bastien Leurent and Lionel Debroux.
  • Bugfix: Fixed a fputc bug with large (>65390 bytes) files.
  • Added: Support for GCC 4.0 (legacy GCC 3 is no longer supported by TIGCCLIB)
  • Added: poke_bchg and pokeIO_bchg macros
  • Bugfix: Fixed support for external data variables using Fargo-style compressed relocs
  • Added: Support for Mlink-format relocs
  • Updated: Grayscale routine size-optimized by Lionel Debroux, Jesse Frey and Martial Demolins.
  • Bugfix: Added const for the sprite data in the sprite function prototypes.
  • Bugfix: Fixed a bug in in-use bit support affecting PedroM versions prior to 0.81.
  • Updated: Merged an optimization to the in-use bit setting code from the pstarter.
  • Bugfix: Fixed calling GrayOn twice not working (despite the documentation saying it works).
  • Bugfix: Fixed LIO_CTX structure (VarSize is an unsigned long, not an unsigned short).
  • Bugfix: Fixed an unoptimizable jsr into a jbsr in trampoline offset computation.
  • Bugfix: Fixed the formulas (wrong left side) in the documentation of catanh and ccos.
  • Updated: Optimized the address hack for OSFastArrows.
Release 2.6 (24. X 2004.)
  • Added: Many new optimization definitions.
  • Added: An implementation of scanf and related functions.
  • Added: Support for program comments.
  • Added: Support for incompatibility flags.
  • Added: Support for unofficial operating systems.
  • Added: A lot of startup code to handle BSS sections, constructors, etc.
  • Added: Automatic setting of the in-use bit.
  • Added: References between functions in the documentation.
  • Updated: Library functions coded in assembly now take register parameters.
  • Updated: Internal F-Line emulator is now mostly compliant with the AMS.
  • Added: Contributions to intr.h, estack.h, and other files.
Release 2.5 SP4 (24. I 2003.)
  • Bugfix: Fixed bug in ENABLE_ERROR_RETURN with MIN_AMS values of 200 or higher.
  • Bugfix: Removed the rejection of a minimum AMS version of 2.07.
Release 2.5 SP3 (13. I 2003.)
  • Bugfix: Incorporated a fix for fclose.
Release 2.5 SP2 (12. I 2003.)
  • Bugfix: Important bugfixes for fopen, fread and fwrite.
  • Bugfix: Changed import_binary to export the symbol, and changed the IDE to make it work with it.
Release 2.5 SP1 (30. XII 2002.)
  • Bugfix: Fixed SET_FILE_IN_USE_BIT.
  • Bugfix: Fixed the prototype of MD5Update.
Release 2.5 (21. XII 2002.)
  • Updated: Greatly changed the structure of the whole library, making it cleaner and easier to read.
  • Updated: Made some changes to support the new '-mregparm' switch/option.
  • Added: Implemented F-Line ROM Calls.
  • Added: Added beta version information to version.h.
  • Added: Implemented checking for a minimum AMS Version.
  • Added: Added types such as SYM_STR to differentiate between different uses of similar constructs.
  • Added: Added the ESTACK macro.
  • Added: Added a TRAP macro which acts like AUTO_INT.
  • Added: Added bitwise functions to peekpoke.h.
  • Added: Added a lot of new functions to unknown.h.
  • Added: Started documenting more functions from unknown.h, especially the high-level functions VarRecall and VarStore.
  • Updated: Made _rowread a library function.
  • Added: Added the _rowread_inverted, _rowread_internal, _keytest, and _keytest_optimized functions.
  • Added: Added missing interrupt vectors.
  • Updated: Integrated Jocelyn Berrendonner's vast updates to menus.h.
  • Added: Implemented calculator detection at startup.
  • Added: Implemented TRY...FINALLY...ENDFINAL blocks, and added appropriate functions to alloc.h.
  • Added: Implemented passing errors on to the AMS, added default error codes, and implemented ER_throw.
  • Added: Implemented nostub libraries.
  • Added: Finished bascmd.h, added basfunc.h and basop.h without further documentation.
  • Added: Added a homescr.h header file for Home Screen manipulation.
  • Added: Integrated a lot of new functions and updates contributed by other people (see Credits), including updates to system.h, statline.h, stdio.h, and string.h.
  • Added: Added a new EXECUTE_IN_GHOST_SPACE directive, replacing the enter_ghost_space function.
  • Updated: Included updated grayscale support from Thomas Nussbaumer, adding GraySetInt1Handler, GrayGetInt1Handler, and double-buffering functions.
  • Added: Added a stddef.h header file.
  • Added: Added import_binary macro.
  • Added: Added a SET_FILE_IN_USE_BIT directive.
Release 2.41 (20. I 2002.)
  • Updated: Made some changes that will hopefully enable support for the new V200 calculator. You can define USE_V200 to activate this.
  • Added: A new file version.h has been added to the library.
  • Updated: Updated fopen and fclose with new versions by Greg Dietsche.
Release 2.4 SP2 (27. XII 2001.)
  • Updated: The patch code has been cleaned up.
  • Updated: exit and atexit support have been reimplemented.
  • Added: A routine for 'long long' multiplication by Kevin Kofler has been integrated.
Release 2.4 SP1 (1. V 2001.)
  • Bugfix: exit and atexit support have been fixed.
  • A new directive, NO_EXIT_SUPPORT, has been added to optimize the program.
Release 2.4 (24. III 2001.)
  • Bugfix: Implemented variable-type arguments for pointers to short and long integers. This prevents warnings if you pass an int pointer to a short pointer argument, and fixes the problems introduced in release 2.31.
  • A standard library file has been added to work with multiple files.
  • New flickerless grayscale support implemented by Thomas Nussbaumer has been added.
  • GrayMode has been replaced by GrayOn and GrayOff.
Release 2.31 (24. XII 2000.)
  • Bugfix: Casting floats to integers and automatic trunctation floating point values now works correctly. In TIGCCLIB 2.3, casting to signed ints (including implicite truncation) produced incorrect values, and casting to unsigned ints produced 'Undefined reference' errors. This is fixed now.
  • Bugfix: Many programs created with library releases prior to 2.3 produce a lot of warnings (although they work correctly after the compilation) about incompatible pointer types. This is fixed now.
  • Bugfix: Functions OSContrastUp and OSContrastDn trashed some registers due to a bug in the TIOS. This is fixed now (thanks to Patrick Davidson).
  • Bugfix: Programs which still have directives USE_..._PATCH couldn't be compiled in "Doors" mode ('Duplicate identifier' errors) with TIGCCLIB 2.3, due to superfluous declarations of some symbols (bcopy etc.) in doors.h header file. This is now fixed.
  • Functions abs, min and max are now redefined to work with any numeric type, not only with short integers. Such behaviour is proposed in ANSI C.
  • Indentifiers AUTO_INT, AUTO_INT_COUNT, FIRST_AUTO_INT and LAST_AUTO_INT were introduced in TIGCCLIB 2.3, but I forgot to document them. This is now corrected.
  • As usual, there are some fixes in the documentation. Especially, thanks to Kevin Kofler for very important information about returning values to TI-Basic.
Release 2.3 (13. XII 2000.)
  • A lot of internal changes are made in the library to support new features introduced in release 0.9 of the compiler. That's why this release of the library will not work correctly with releases of TIGCC prior to 0.9.
  • The timath.h header file is completely rewritten, because the compiler now supports the native ANSI C floating point types and values (click here for more info). In addition to this, two new ANSI-compatible header files math.h and float.h are introduced too. These changes are performed on such way to retain about 95% compatibility with old programs which used floating point arithmetic using awkward indirect methods (i.e. the only possible methods before TIGCC 0.9). Click here for more info.
  • There is no more need for usage of directives like USE_..._PATCH. The new compiler apply patches automatically when necessary (such directives will be simply ignored now). In other words, you don't need to worry any more about patches. For this purpose, a new file called tipatch.lib is added to the library. The new compiler searches through this file to find appropriate patches which eventually should to be included (you should not edit or modify this file unless you know very well what are you doing).
  • Three new functions float_to_bcd, bcd_to_float and bcd_var are added to timath.h header file.
  • A very important function push_internal_simplify which is essential for symbolic mathematic is added to estack.h header file. Note that although this function is not officially introduced before AMS 2.xx, it is implemented here to work on any AMS version.
  • Four new functions peekIO, peekIO_w, poke and pokwIO_w are added to peekpoke.h header file, to allow reliable reading and writing to hardware memory-mapped I/O ports.
  • A new function EV_getAppID is added in events.h header file, which allows determining application ID numbers regardless of the AMS version. Note that although this function is not officially introduced before AMS 2.xx, it is implemented here to work on any AMS version.
  • A new function FolderClear is added in vat.h header file. The structure of SYM_ENTRY is slightly improved (without losing the compatibility).
  • Functions atof and fabs are now present in stdlib.h header file too, as proposed in ANSI C.
  • Bugfix: Changed definition of _rowread so it works correctly if used in a short loop with the new compiler.
  • Bugfix: The directive OPTIMIZE_ROM_CALLS now does not interfere witn an user-written interrupt handlers (thanks to Thomas Nussbaumer). Note however that it still may interfere with event handlers, and with callback functions used in OSVRegisterTimer, vcbprintf, etc.
  • Bugfix: Function exit now will not cause a warning if used in the body of a non-void function.
  • Bugfix: Function FolderDel now works as described (and reliably).
  • Bugfix: Some functions from ctype.h are rewritten to avoid spurious warnings if the warning-checking level is set too high.
  • Bugfix: Function hypot will not cause side effects anymore.
  • Bugfix: Function push_ANSI_string now works correctly in all cases.
  • Bugfix: Function LCD_save now does not cause spurious warnings if used in "Doors" mode.
  • Bugfix: Function XR_stringPtr is rewritten to work with all AMS versions (thanks to Romain Herault).
  • Bugfix: Enumeration StartTypes is rewritten to be compatible with all AMS versions.
  • The library is changed to replace all 'int's to 'short's where this was appropriate to support the '-mnoshort' command line option supported in the new version of the compiler.
  • The documentation is much updated (including correcting of some information which was wrong). The Frequently Asked Questions list is also slightly updated.
Release 2.22 (8. X 2000.)
  • Bugfix: A fatal bug which causes crash if enter_ghost_space function is used on AMS 2.03 is fixed.
Release 2.21 (2. X 2000.)
  • Release 2.21 is just a minor upgrade which includes the documentation in both .chm and .html format, because this was requested by non-Windows users. Other modifications includes slight fixes in the documentation, and much better organized Frequently Asked Questions list (thanks to James Darpinian for helping me to organize it).
Release 2.2 (29. IX 2000.)
  • The documentation for the release 2.2 is completely rearanged to make it much more readable. Moreover, the documentation now contains not only information about library functions, but about the whole TIGCC project, including the compiler options, a brief reference to C language keywords, operators and punctuators, description of GNU C language extensions, GNU Assember, and much more. The Frequently Asked Question list is full of new question/answer pairs. In general, the documentation is now thrice larger than in previous release, and it is now in .chm format (68 separate HTML files become too inpracticable; if someone is really interested in HTML originals, I can upload them separately). I hope that you will like the new look of the documentation (and the documentation itself, of course).
  • The header file all.h is renamed to tigcclib.h to be more consistent. The old name will still be accepted, due to compatibility reasons.
  • It is not necessary any more to include nostub.h header file explicitely to produce a "nostub" program: the library will do this automatically if you use any other file from the library, except if you define the global preprocessor symbol USE_KERNEL, or if you explicitely include doors.h header file at the begining of the program.
  • A new directive OPTIMIZE_ROM_CALLS is introduced, which optimizes ROM calls in "nostub" mode, which usually leads to shorter and faster programs (but not always).
  • Grayscale support on HW2 calculators is improved to be about 50% faster and more flickerless. A new function GrayAdjust is implemented, which allows fine tuning of grayscale quality, so it allows to reduce flickering as many as possible. Please, recompile your existing grayscale programs if you want to get advantage of introduced improvements.
  • It is not necessary any more to put USE_GRAY_PATCH in grayscale programs; the library will now conclude automatically when the grayscale support is necessary, and it will act accordingly.
  • Bugfix: trying to enable grayscale now will not cause the crash if the grayscale was already enabled.
  • A new function GrayCheckRunning and a new enumeration GrayPlanes are added in the gray.h header file.
  • Bugfix: A fatal bug into functions fwrite and fread which makes them unusuable is fixed. Also, a small bug in fseek (a wrong returned value) is fixed too.
  • Bugfix: Function fopen is now much more robust if something is going wrong (for example, not enough memory).
  • A new function enter_ghost_space is introduced, for bypassing some protections introduced in AMS 2.xx.
  • A new header file intr.h is introduced, which contains functions, language extensions, and data types for easy making of interrupt handlers, and for general manipulations with interrupts.
  • Very useful enumeration CommonKeys is introduced in kbd.h header file. It contains keycodes of some commonly used keys.
  • Bugfix: Function _rowread now works reliable on HW2 calculators (they needs more time for recovering the keyboard controlor).
  • The documentation now contains the keyboard matrix for usage of _rowread function.
  • Functions OSVRegisterTimer and OSVFreeTimer are rewriten to works independently of the TIOS, because they are removed from TIOS in AMS 2.04 and AMS 2.05. Now, they works on any AMS version (in other words: no more "Resident ROM routine not available" message). Please, recompile your program if you used these function, to make it compatible witn AMS 2.04/5.
  • A new function alloca is added into alloc.h and stdlib.h header files.
  • Bugfix: Function assert will not cause a crash anymore when used together with the SAVE_SCREEN directive.
  • Bugfix: Function assert now works properly if used inside if...else constructions.
  • Bugfix: Functions assert and ldiv will not trash line numbers anymore.
  • Bugfix: Functions GetFloatArg, ArgCount and RemainingArgCnt now works correctly in "Doors" mode.
  • Bugfix: Small corrections are made in functions poke, poke_w and poke_l, to prevent some unnecessary warnings.
  • Bugfix: Constants CHAR_MIN and CHAR_MAX in limits.h header file are now sensitive to the fact that the compiler may be forced to treat chars as unsigned.
  • Bugfix: Although I said that impossibility of making multi-module programs in "Doors" mode is solved in release 2.1, I forgot to do this. This is now really solved, however.
  • The library is now programmed on such way that the compiler will emit a warning if you try to return a value using the return keyword from the _main function, because you in fact can not do this.
Release 2.1 (25. VI 2000.)
  • The alphabetical list (with appropriate links) of all functions, macro constructors, language extensions, global variables, constants and predefined types is added to the documentation.
  • Bugfix: Sprite16 function from sprites.h header file now works correctly. In addition to this bugfix, a new function Sprite8 is added for easier working with small sprites.
  • Bugfix: floating point routines caused crash when they are nested deeply (read: very often). This problem is finally solved (after a lot of troubles). I hope that floating point support is now stable.
  • Bugfix: FLT macro from timath.h header file generated unnormalized numbers when they are smaller than 0.1. Many floating point routines were not happy with such numbers, and produced wrong results. This is now corrected.
  • Bugfix: I hope that I finally found a workarround for a stupid bug in GNU C preprocessor which causes STATUS_ACCESS_VIOLATION exception very often when FLT macro is used with just one argument. Now, it seems that this problem does not appear any more.
  • Programs which use floating point support now usually procuce a bit shorter code than earlier.
  • Bugfix: function div from stdlib.h header file now works correctly.
  • Bugfix: functions strcmp and memcmp were declared as long, although it seems that these functions leave an unpredictable results in higher half of D0; they are now declared as int (Sebastian Reichelt and Xavier Vassor informed me about strange behaviour of these two functions). It seems that these problems are solved after redeclaration.
  • Bugfix: function ASM_call from system.h header file assumed that called subroutine will preserve all registers, which caused a lot of problems when these assumptions are violated. ASM_call now saves all registers and restores them after the execution. In addition to this bugfix, a new function ASM_fastcall is added, for faster calling (when you are sure that a called subroutine will not destroy any registers).
  • Bugfix: in release 2.0, it was impossible in "Doors" mode to create programs splited in many modules which are linked separately, because symbol _main was unconditionally exported in doors.h header file. This is now corrected.
  • Bugfix: function GrayMode from gray.h header file now automatically selects dark plane just after switching on the grayscale mode. Such behaviour in previous releases of TIGCCLIB was guaranted only on HW1 calculators, but not on HW2 calculators. So, it was possible to produce (quite easily) grayscale programs which work correctly only on HW1 calculators, although grayscale support is planed to work always on both hardware versions. This is now fixed.
  • Some errors in the documentation are fixed, and the documentation is slightly updated (especially information about big number support in rsa.h header file). As usual, the Frequently Asked Questions list is updated with a lot of useful suggestions.
Release 2.0 (25. V 2000.)
  • Starting from this release, TIGCCLIB is much more compatible with ANSI C standard library. Nearly full implementation of stdio.h and stdlib.h is included (41 new functions in stdio.h and 23 new functions in stdlib.h, together with appropriate data structures and types). So, you can now use a lot of functions known from various C tutorials: printf, fopen, gets, atoi, qsort, bsearch, strtol...
  • Usage of patches "inits", "longmul", "longdiv" and "gray" is now much easier: instead of separate linking, it is enough to define some global preprocessor symbols (like USE_LONGMUL_PATCH etc.).
  • A directive SAVE_SCREEN is introduced, which allows automatically saving and restoring the content of the screen in "nostub" mode, without needness for calling LCD_save and LCD_restore manually.
  • Bugfix: very serious bug which sometimes cause crash in programs which use floating point numbers is corrected (note that this bugfix was released before, as a separate file called tcl15fix).
  • A lot of new mathematical functions (mainly for manipulations with symbolic expressions, lists and matrices, and for algebra and calculus applications), and functions for "pretty printing" expressions are added in estack.h header file (82 new functions). The list of expression tags is completed (more than 500 tags), and the documentation about usage of expression stack is much updated.
  • A new header file events.h is introduced, with 32 new functions for event driving programming, and calculator mode settings. Now you can simulate TIOS system events in your programs, and hook into the operating system and change its behavious partially (for example, you can redefine the keyboard, add new items in system menus, change behaviour of some commands, etc.). But note that these features require good knowledge of programming.
  • A new header file sprites.h is introduced, with 2 new fast and simple functions for sprite drawing (including masked sprites).
  • A new header file textedit.h with 16 new functions for accessing the text editor is introduced. As the text editor which is built-in into the TIOS is highly customizable, you can now write programs with high perfomance editing facilities!
  • Four language extension macros TRY, ONERR, ENDTRY and PASS are added in error.h header file, to allow error handling similarly like in TI-Basic or in modern programming languages like Delphi. Also, two new functions are added in error.h, the documentation about it is updated, and some wrong information are corrected.
  • A new header file flash.h is introduced, with 11 new functions for low-level access to the Flash ROM. 3 new functions for high-level access to the Flash ROM are added in vat.h header file.
  • Some new data structures are added in vat.h header file, various infos related to this header file are updated (especially about organization of VAT table entries), and one small bug in it is corrected (HS_NULL was wrongly defined).
  • A new header file cert.h with 17 functions for working for certificate files and other memory-mapped files (not necessary related to certificates) is introduced.
  • 15 new functions for high-level accessing to the link port are added in link.h header file. Also, some information about link.h are corrected.
  • A new header file rsa.h is introduced, with 8 new functions for working with very big integer numbers, message diggesting and RSA decryption.
  • 4 new functions are added in args.h header file, which allow more flexible getting of the arguments passed to the program. The list of argument tags is completed.
  • Two new header files limits.h and values.h are introduced. They contain various platform-dependent constants (proposed by ANSI). This helps porting programs from other platforms.
  • A new header file compat.h is introduced, which defines 18 pseudoconstants (i.e. macros which look and act like constants). These pseudoconstants have different values on TI-89 and TI-92 Plus, so they can help making compatibility between these two calculator models. Also some pseudoconstants have different values on AMS 1.xx and AMS 2.xx, so they can help solving some minor incompatibilities between AMS 1.xx and AMS 2.xx during usage of some functions (although 99% of implemented functions are AMS-independent).
  • Two very useful global variables are added in wingraph.h header file. Also, some information about this header file and graph.h header file are updated or corrected.
  • 12 new functions are added in system.h header file, mainly for manipulating with queue structures, the cursor and the clipboard. Many information about this header file are updated or corrected.
  • Information about kbd.h header file are much updated. A hint is added about how to avoid slow functions kbhit and ngetchx in high-perfomance keyboard reading applications, without using very low-level functions like _rowread.
  • A new header file bascmd.h with 35 new functions is introduced. At the moment, this header file is quite incomplete and a bit unconsistent. In the near future it will contain more than 150 new functions. This header file contains functions which executes particular TI-Basic statements or functions, so after completing this header file, nearly everything which may be done using just one TI-Basic statement/function would be possible using just one TIGCC function (but be aware: the performance will be like during executing of TI-Basic statement/function, so intensive usage of functions from this header file is not recommended in high-perfomance applications). I started to develop this header file, but the shortage of my free time forces me to stop developing for a while. I don't want to prolongue releasing of whole TIGCCLIB 2.0 only because this header file is not complete. Be patient, I will continue developing it as soon as possible...
  • 3 new functions are added in menus.h header file. A lot of information are updated, especially about the exact organization of the menu structure (this info allows making menus with more levels of submenus).
  • Function assert is improved, so now there is no any limitations about usage of this function in "nostub" mode.
  • Function realloc (proposed by ANSI) is added in alloc.h header file (it is also defined in stdlib.h), and calloc is improved to generate smaller code.
  • Information for assembly programmers are much updated (many people asked me about examples of using floats in ASM programs, so this info is added).
  • More than 200 TIOS functions are no more "unknown", so they are moved out of unknown.h header file.
  • The documentation generally and the Frequently Asked Questions list are updated.
Release 1.5 (29. III 2000.)
  • Floating point support is implemented. For this purpose, a new header file timath.h is introduced, with 86 new functions, 4 macro constructors and a lot of constants and predefined types.
  • Basic support for the symbolic calculations (including symbolic algebra and calculus) is also implemented. For this purpose, a new header file estack.h is introduced. It contains 26 functions for manipulations with the expression stack (in the near future, I planed about 50-100 new functions in this header file).
  • Bugfix: GraySetAMSPlane function from gray.h now works correctly in "Doors" mode.
  • Bugfix: grayscale support on Hardware Release 2 calculator is now stable. And, grayscale support now autodetects the hardware version!
  • Now you can make programs which return a result to the TI-Basic, i.e. which acts like TI-Basic functions. For this purpose, header files nostub.h and doors.h are slightly changed.
  • Two very useful functions are added in args.h header file: GetFloatArg and SkipArg. Also, documentation about args.h is much updated and some serious errors in the documentation are corrected.
  • 2 new functions (ASM_call and EX_patch) are added in system.h.
  • 94 TIOS functions are no more "unknown", so they are moved out of unknown.h header file.
  • Function NoCallBack is now implemented as cast constructor, so it will not be embeded in the program if not used.
  • _rowread function from kbd.h is now more reliable.
  • All arguments which represent a handle or functions which return a handle are now declared as HANDLE instead of unsigned int. Yes, this is exactly the same, but the documentation is now more clear.
  • Information about timers in system.h are updated.
  • Information for assembly programers are slightly updated.
  • Information about how to use floating point and symbolic arithmetic and information about how to return a value to TI-Basic are added in the documentation.
  • Frequently Asked Questions are added to the documentation.
Release 1.1 (4. II 2000.)
  • Bugfix: strncmp was incorrectly declared as long, although TIOS strncmp puts the garbage in higher half of D0; it is now declared as int.
  • Bugfix: type definition for HANDLE in wingraph.h and all.h had a syntax error, which is now fixed.
  • AMS 2.03 bugfix: NoCallBack is no more in the TIOS jump table, so this fact is now regarded. This fixed problems with usage of dialogs with AMS 2.03. If you used dialogs.h with previous release of the library, please recompile your program to become compatible with AMS 2.03!
  • Grayscale support implemented: a new header file gray.h and a new patch gray.o are introduced for this purpose.
  • Added support of passing arguments to the programs: for this purpose, a new header file args.h is introduced.
  • Header file assert.h is now included in all.h because I found an inteligent method how to implement assert on such way that it does not increase the program size if not used in the program (this is a tricky play with conditional assembling).
  • An information how to make a real stdio.h function printf is added into the documentation about printf.h.
  • Some additional notes and an example of usage are added for WinOpen function
  • Global variable top_estack is moved from unknown.h to args.h.
  • Some typo errors in the documentation are fixed.
Release 1.0 (11. I 2000.)
  • The first official release.


Making GCC4TI Programs
  • Making Kernel-Less (NoStub) Programs
  • Making Kernel-Based Programs
  • Advanced Options of GCC4TI
  • Program Comments
  • Incompatibility Information
  • Defining a Minimum AMS Version
  • Overcoming AMS Dependencies


Making Kernel-Less (NoStub) Programs
Making GCC4TI Programs Next

NoStub programs are programs which don't need any kernel like PreOS for execution. However, they work with a kernel installed. Starting from release 2.2 of TIGCCLIB, TIGCC (and therefore GCC4TI) produces so-called NoStub programs by default (there is no need to include nostub.h before including any other header files from this library as in releases of TIGCCLIB prior 2.2; this will be explained in more details below). As this release of the library is highly ANSI-compatible, the first example will be the classic Kernighan & Ritchie "Hello world" example (called "Hello World 1", slightly modified to include clearing the screen and waiting for the keypress):

#define SAVE_SCREEN         // this directive forces saving/restoring the screen

#define USE_TI89            // produce all types of files
#define USE_TI92PLUS
#define USE_V200

#include <stdio.h>          // standard ANSI C input/output support
#include <kbd.h>            // keyboard handling support, needed for ngetchx

void _main(void)            // main entry point is function _main
{
  clrscr ();                // clear the screen and reset print position
  printf ("Hello world!");  // do you know what this is?
  ngetchx ();               // wait for a keypress
}
Note that the main entry point is _main, not main as defined in Kernighan & Ritchie. The reason for it is the compatibility with kernels, which propose that the main program entry point is called _main. Also note that _main should be a function with return type void (not int as usual), because you can not return a status code to the operating system.

To compile this program, you can use the GCC4TI Integrated Environment, or you can type from the command line (if the file is named "hello.c"):

tigcc -O2 hello.c

Always include the switch '-O2'. It will turn on optimization (click here to see much more about compiler command line options).

As you can see, defining macros named USE_TI89, USE_TI92PLUS (or USE_TI92P), and USE_V200 will generate .89z (for the TI-89) or .9xz (for the TI-92 Plus and V200) executable files. Only the calculators which you define this way are supported; if you only define USE_TI89, then only the TI-89 will be supported. Defining only one calculator model may generate shorter and faster code. See compat.h for more info.

The old way of defining global variables called _ti89 and _ti92plus is still supported, but it is not recommended to use it any more, since no optimization of the above kind can be performed. In the IDE, you will find replacements for these macros in the project options.

The directive SAVE_SCREEN forces saving the screen contents before execution and restoring them after execution of the program.

Users which are familiar with very old releases of TIGCCLIB might ask what has happened to the nostub.h header file. Nowadays, the use of any header file from GCC4TILIB will automatically include the nostub.h header file, except if the global preprocessor symbol USE_KERNEL is defined, or if the doors.h is included at the beginning (see section How to make a kernel-based program for more info). This way you need to include nostub.h manually only if you don't include any other header file from GCC4TILIB, which is extremely unlikely. To retain compatibility with programs created with previous versions of the library, including nostub.h explicitly will not cause any damage.

The example given above works, but it is better to use TIOS-specific functions than ANSI C console functions. First, they are more flexible, and second, they are built-in in the OS, so using them will usually produce much shorter code. For example, the use of the printf function will increase the size of your program by about 200 bytes, because printf is an advanced high-level function (not present in the TIOS) which may do much more than writing "Hello world" on the screen (like formatted output, screen scrolling, etc.). So, to write just "Hello world" on the screen, it is a better idea to use particular TIOS functions like DrawStr to do the same thing: your program will be much shorter and more efficient (although less "standard"). This idea is illustrated in the following program ("Hello World 2"), which uses only TIOS functions, and which does the following:
  • saves the contents of the screen;
  • clears the screen;
  • displays the "Hello world!" message using the large font;
  • draws a border around the message;
  • waits for a keypress;
  • restores the original contents of the screen before returning.
#define SAVE_SCREEN

#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#include <graph.h>
#include <kbd.h>

void _main(void)
{
  static WIN_RECT rect = {0, 0, 100, 14};
  ClrScr ();
  FontSetSys (F_8x10);
  DrawStr (3, 3, "Hello world!", A_NORMAL);
  DrawClipRect (&rect, ScrRect, A_NORMAL);
  ngetchx ();
}
Note that SAVE_SCREEN is a new directive introduced in TIGCCLIB 2.0. In older releases of TIGCCLIB you had to save and restore the screen manually, like in the following example ("Hello World 3"):
#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#include <graph.h>
#include <kbd.h>

void _main(void)
{
  LCD_BUFFER buffer;
  static WIN_RECT rect = {0, 0, 100, 14};
  LCD_save (buffer);
  ClrScr ();
  FontSetSys (F_8x10);
  DrawStr (3, 3, "Hello world!", A_NORMAL);
  DrawClipRect (&rect, ScrRect, A_NORMAL);
  ngetchx ();
  LCD_restore (buffer);
}
See graph.h and kbd.h for detailed descriptions of the used functions and data types. Be aware of the slight difference between ClrScr defined in graph.h and clrscr defined in stdio.h.

The SAVE_SCREEN directive does exactly the same thing as in the previous example, but the task is automatized (i.e. you need not to explicitely declare the save buffer and to call functions for saving and restoring screen manually). If you are not happy with such allocation (the buffer is allocated on the stack, reducing its size by 3840 bytes), don't use SAVE_SCREEN directive and perform saving and restoring the screen using an other method (for example, using dynamic memory allocation). Note that the total stack size on TI is limited to 16384 bytes.

The disadvantage of NoStub programs is that they are somewhat longer than kernel programs if the program contains many ROM calls (but in the above example, the NoStub version is shorter than the kernel version), and they can not call routines from external files (often called "libraries") whithout special support code. Any other features supported with this library of header files work in both kernel and NoStub mode, so if the difference in the program size is not enormous, and if no external libraries are needed, NoStub mode is highly recommended. Note that routines defined in these header files contain most of routines which are seen in various external libraries, sometimes maybe with a different name and syntax. I think that making a program which is independent of external library files is a big advantage!

If you make a NoStub program, you must also know that the exit point defined by the function _exit has no meaning in NoStub programs.

See also: nostub.h


Making Kernel-Based Programs
Previous Making GCC4TI Programs Next

To produce a kernel-based program, i.e. a program which will need PreOS for executing, simply define the global preprocessor symbol USE_KERNEL at the begining of your program, before including any other header files from the library. Alternatively, the old method (including the doors.h header file before including any other header files from the library) still works. In fact, if USE_KERNEL is defined, including any header file from the library will include doors.h automatically (if it is not included explicitely before). So, explicitely including doors.h is really necessary only if your program does not include any other header file from the library (which is extremely unlikely).

Here is a Kernighan & Ritchie "Hello world" example (kernel version, called "Hello World 4"), which works exactly like the example given in the previous section (Making Kernel-Less Programs):

#define USE_KERNEL          // include kernel support

#define USE_TI89            // produce all types of files
#define USE_TI92PLUS
#define USE_V200

#include <stdio.h>          // standard ANSI C input/output support
#include <kbd.h>            // keyboard handling support, needed for ngetchx

void _main(void)            // main entry point is function _main
{
  clrscr ();                // clear the screen and reset print position
  printf ("Hello world!");  // do you know what this is?
  ngetchx ();               // wait for a keypress
}
Note that the directive SAVE_SCREEN is not included like in the NoStub version. PreOS saves and restores the screen content by default, so no extra intervention is necessary.

Of course, it is better again to use TIOS specific functions than ANSI C console functions, so an extended "Hello world" TI-specific example (kernel-based version), which does the same as in the NoStub case, follows (called "Hello World 5"):
#define USE_KERNEL

#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#include <graph.h>
#include <kbd.h>

void _main(void)
{
  static WIN_RECT rect = {0, 0, 100, 14};
  ClrScr ();
  FontSetSys (F_8x10);
  DrawStr (3, 3, "Hello world!", A_NORMAL);
  DrawClipRect (&rect, ScrRect, A_NORMAL);
  ngetchx ();
}
See graph.h and kbd.h for detailed descriptions of the used functions and data types. Be aware of the slight difference between ClrScr defined in graph.h and clrscr defined in stdio.h.

To compile this program, you can use the GCC4TI Integrated Environment, or you can type from the command line (if the file is named "hello.c"):

tigcc -O2 hello.c

Always include the '-O2' or '-Os' switch: it will turn on optimization (click here to see much more about compiler command line options). See also the notes given with the example in the previous section.

If you make programs spread in more than one file, you must define USE_KERNEL (or include doors.h) in each file!

The advantage of kernel-based programs lies in the fact that they are often (but not always) shorter than NoStub programs if the program contains a lot of ROM calls. Kernel-based programs can also call routines from external files (often called "libraries") without special library support inside the program. Any other features supported with this library of header files work in both kernel and NoStub mode, so if the difference in the program size is not too large, and if no external libraries are needed, NoStub mode is recommended. Note that routines defined in these header files contain most of the routines which are seen in various external libraries, sometimes maybe with different name and syntax.

Additionally, if you want to make your program even smaller but only want to support new versions of the PreOS kernel, you can define USE_PREOS_COMPRESSED_TABLES. This will create compressed versions of the relocation tables, which are not available in older kernels. If you try to run the program with an old kernel installed, you will get an error message.

If you make a kernel-based program, knowing the following facts may be useful:
  • You can produce an external library file by defining the global symbol _library, i.e. by putting int _library in your program. If the name of your library is for example MyLib, all symbols with names like MyLib__nnnn will be exported as public. To make life easier, use the #define directive. For example, if you want to export function named MyFunc, you can, for example, put the directive #define MyFunc MyLib__0005 at the beginning of your library. The same directive must be included in the program which wants to use the function MyFunc from the library MyLib. Also, the prototype of the imported function also needs to be defined.

  • Kernel-based programs may have an exit point. The function with name _exit will be executed if and only if the program is terminated in an abnormal way, for example if there was an error, or if the user pressed STO+ON.

See also: doors.h


Advanced Options of GCC4TI
Previous Making GCC4TI Programs Next

There are several ways to optimize programs further, and enable special support for some not so common situations:

  • SAVE_SCREEN
  • OPTIMIZE_ROM_CALLS
  • KERNEL_FORMAT_ROM_CALLS
  • MLINK_FORMAT_ROM_CALLS
  • COMPRESSED_FORMAT_ROM_CALLS
  • USE_FLINE_ROM_CALLS
  • USE_FLINE_JUMPS
  • USE_4_BYTE_FLINE_JUMPS
  • KERNEL_FORMAT_RELOCS
  • MLINK_FORMAT_RELOCS
  • COMPRESSED_FORMAT_RELOCS
  • MERGE_BSS
  • KERNEL_FORMAT_BSS
  • MLINK_FORMAT_BSS
  • COMPRESSED_FORMAT_BSS
  • OMIT_BSS_INIT
  • KERNEL_FORMAT_DATA_VAR
  • MLINK_FORMAT_DATA_VAR
  • COMPRESSED_FORMAT_DATA_VAR
  • OPTIMIZE_CALC_CONSTS
  • NO_CALC_DETECT
  • EXECUTE_IN_GHOST_SPACE
  • STRICT_POINTERS
  • SET_FILE_IN_USE_BIT
  • UNOFFICIAL_OS_SUPPORT
  • REJECT_UNOFFICIAL_OS
  • _GENERIC_ARCHIVE
  • Linker Optimization Facilities
  • GCC Optimization Switches
  • GNU Assembler Optimization Switches

See also: default.h, MIN_AMS, RETURN_VALUE, ENABLE_ERROR_RETURN


SAVE_SCREEN
Advanced Options of GCC4TI Next

If you put

#define SAVE_SCREEN
at the beginning of your program, the screen will be saved automatically at startup and restored when the program terminates. This takes LCD_SIZE bytes on the stack.

Note: Kernels always save the screen automatically, so this directive has no effect in kernel mode.


OPTIMIZE_ROM_CALLS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define OPTIMIZE_ROM_CALLS
at the beginning of the program, the compiler will reserve one processor register (a5) to keep the base address of TIOS jump table in it. This will make all calls to TIOS routines smaller and faster. The disadvantage of this method lies in the fact that the a5 register is fully reserved during the execution of the program, so the compiler will have one register less for internal manipulations. The consequence is that it sometimes can produce somewhat longer code when compiling a particular expression or statement. Generally, the use of OPTIMIZE_ROM_CALLS usually leads to shorter and faster code, but this does not always need to be true. It is best to try it and see how it performs in a particular program.

If you define OPTIMIZE_ROM_CALLS in one file, you must also define it in every file that uses a function from this file.

Note: Avoid OPTIMIZE_ROM_CALLS in a program which may change its flow asynchronously in an unpredictable way (an event-driven program, for example). Such programs are mainly all programs which use some kind of callback function (like programs which use OSVRegisterTimer, complex dialogs with callback functions, the function vcbprintf etc.). There may also be some problems with floating point arithmetic.


KERNEL_FORMAT_ROM_CALLS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define KERNEL_FORMAT_ROM_CALLS
at the beginning of the program, ROM calls will be stored and relocated in the same manner as kernel programs do it. This does not mean that your program will need a kernel to run. The kernel format for ROM calls is very efficient if the same ROM calls are used at many different places, but may waste space otherwise. You need to see for yourself whether using it makes the program smaller.

This feature uses the linker-specific symbol __ld_insert_kernel_rom_calls.

See also: MLINK_FORMAT_ROM_CALLS, COMPRESSED_FORMAT_ROM_CALLS


MLINK_FORMAT_ROM_CALLS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define MLINK_FORMAT_ROM_CALLS
at the beginning of the program, ROM calls will be stored in the program in a compressed format. This format for the relocation entries (first used in Johan Eilert's mlink linker) is designed to balance the size of the relocs against the size of the decompression routine. The relocation entries take only slightly more space than in the compressed format, but the decoding code is much smaller. Moreover, as for the compressed format, the decoding code only has to be inserted into the program once if multiple MLINK_FORMAT_... features are used. In most cases, this should be the optimal format to use for relocation entries, but for programs with very few or very many relocations, the kernel or compressed formats (respectively) are more efficient.

This feature uses the linker-specific symbol __ld_insert_mlink_rom_calls.

See also: KERNEL_FORMAT_ROM_CALLS, COMPRESSED_FORMAT_ROM_CALLS


COMPRESSED_FORMAT_ROM_CALLS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define COMPRESSED_FORMAT_ROM_CALLS
at the beginning of the program, ROM calls will be stored in the program in a compressed format. Relocation entries in this format take the smallest space that is reasonable. The relocation code for the compressed format is rather large, but part of it only has to be inserted into the program once if multiple COMPRESSED_FORMAT_... features are used.

This feature uses the linker-specific symbol __ld_insert_compressed_rom_calls.

See also: KERNEL_FORMAT_ROM_CALLS, MLINK_FORMAT_ROM_CALLS


USE_FLINE_ROM_CALLS
Previous Advanced Options of GCC4TI Next

AMS 2.04 and higher support a method of calling ROM calls in a way that is shorter than any other way, but very slow. If you want to use this method, write

#define USE_FLINE_ROM_CALLS
at the beginning of the program. However, you need to define a minimum AMS version for your program if you want to use this. You can bypass this, assuming that the user has installed an emulator for Line 1111 ROM calls, by defining USE_FLINE_EMULATOR. Alternatively, you can even define USE_INTERNAL_FLINE_EMULATOR to make the program install its own handler for Line 1111 ROM calls.

Note: The Line 1111 handler of the AMS does not support calling TIOS functions from interrupts. If you want to use your own interrupt handlers for something, you will have to define USE_INTERNAL_FLINE_EMULATOR.

See also: USE_FLINE_JUMPS


USE_FLINE_JUMPS
Previous Advanced Options of GCC4TI Next

AMS 2.04 and higher support a method of jumping to other places in the code in a way that is shorter than any other way, but very slow. If you want to use this method, write

#define USE_FLINE_JUMPS
at the beginning of the program. However, you need to define a minimum AMS version for your program if you want to use this. You can bypass this, assuming that the user has installed an emulator for Line 1111 jumps, by defining USE_FLINE_EMULATOR. Alternatively, you can even define USE_INTERNAL_FLINE_EMULATOR to make the program install its own handler for Line 1111 jumps.

Note: The Line 1111 handler of the AMS does not support Line 1111 jumps from interrupts. If you want to use your own interrupt handlers for something, you will have to define USE_INTERNAL_FLINE_EMULATOR, which includes special support for such jumps automatically if DEFINE_INT_HANDLER is used.

This feature uses the linker-specific symbol __ld_use_fline_jumps.

See also: USE_4_BYTE_FLINE_JUMPS, USE_FLINE_ROM_CALLS


USE_4_BYTE_FLINE_JUMPS
Previous Advanced Options of GCC4TI Next

Normal F-Line jumps take 6 bytes, but if they are not pc-relative but relative to the beginning of the program, they can fit into 4 bytes. To activate 4-byte F-Line jumps, put

#define USE_4_BYTE_FLINE_JUMPS
at the beginning of the program. However, only the internal F-Line emulator supports such jumps, so you need to define USE_INTERNAL_FLINE_EMULATOR as well, to make the program install its own handler for Line 1111 jumps.

Note: Since 4-byte F-Line jumps use codes that are otherwise used for ROM calls, this might break applications that are called from the program, if any. However, this is very unlikely, as the two ROM calls used are not defined yet.

This feature uses the linker-specific symbol __ld_use_4byte_fline_jumps.

See also: USE_FLINE_JUMPS, USE_FLINE_ROM_CALLS


KERNEL_FORMAT_RELOCS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define KERNEL_FORMAT_RELOCS
at the beginning of the program, relocation entries will be stored and relocated in the same manner as kernel programs do it. This does not mean that your program will need a kernel to run. The kernel format for relocation information is always smaller than the native TIOS format, but the relocation code will take up a few bytes. You need to see for yourself whether using it makes the program smaller.

This feature uses the linker-specific symbol __ld_insert_kernel_relocs.

See also: MLINK_FORMAT_RELOCS, COMPRESSED_FORMAT_RELOCS


MLINK_FORMAT_RELOCS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define MLINK_FORMAT_RELOCS
at the beginning of the program, relocation entries will be stored in the program in a compressed format. This format for the relocation entries (first used in Johan Eilert's mlink linker) is designed to balance the size of the relocs against the size of the decompression routine. The relocation entries take only slightly more space than in the compressed format, but the decoding code is much smaller. Moreover, as for the compressed format, the decoding code only has to be inserted into the program once if multiple MLINK_FORMAT_... features are used. In most cases, this should be the optimal format to use for relocation entries, but for programs with very few or very many relocations, the kernel or compressed formats (respectively) are more efficient.

This feature uses the linker-specific symbol __ld_insert_mlink_relocs.

See also: KERNEL_FORMAT_RELOCS, COMPRESSED_FORMAT_RELOCS


COMPRESSED_FORMAT_RELOCS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define COMPRESSED_FORMAT_RELOCS
at the beginning of the program, relocation entries will be stored in the program in a compressed format. Relocation entries in this format take the smallest space that is reasonable. The relocation code for the compressed format is rather large, but part of it only has to be inserted into the program once if multiple COMPRESSED_FORMAT_... features are used.

This feature uses the linker-specific symbol __ld_insert_compressed_relocs.

See also: KERNEL_FORMAT_RELOCS, MLINK_FORMAT_RELOCS


MERGE_BSS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you do not want the BSS section (which holds all uninitialized global variables) to be created dynamically, you can write

#define MERGE_BSS
at the beginning of all files. Unlike the '-mno-bss' compiler switch, this ensures that the variables are initialized to zero.

See also: KERNEL_FORMAT_BSS, MLINK_FORMAT_BSS, COMPRESSED_FORMAT_BSS


KERNEL_FORMAT_BSS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define KERNEL_FORMAT_BSS
at the beginning of the program, a BSS section will be created in the same manner as kernel programs do it. A BSS section holds uninitialized global variables. This does not mean that your program will need a kernel to run. Currently, this is the default.

This feature uses the linker-specific symbol __ld_insert_kernel_bss_refs.

See also: MLINK_FORMAT_BSS, COMPRESSED_FORMAT_BSS, MERGE_BSS


MLINK_FORMAT_BSS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define MLINK_FORMAT_BSS
at the beginning of the program, a BSS section will be created dynamically at run time, and the references into this section will be stored in the program in a compressed format. A BSS section holds uninitialized global variables. This format for the relocation entries (first used in Johan Eilert's mlink linker) is designed to balance the size of the relocs against the size of the decompression routine. The relocation entries take only slightly more space than in the compressed format, but the decoding code is much smaller. Moreover, as for the compressed format, the decoding code only has to be inserted into the program once if multiple MLINK_FORMAT_... features are used. In most cases, this should be the optimal format to use for relocation entries, but for programs with very few or very many relocations, the kernel or compressed formats (respectively) are more efficient.

This feature uses the linker-specific symbol __ld_insert_mlink_bss_refs.

See also: KERNEL_FORMAT_BSS, COMPRESSED_FORMAT_BSS, MERGE_BSS


COMPRESSED_FORMAT_BSS
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define COMPRESSED_FORMAT_BSS
at the beginning of the program, a BSS section will be created dynamically at run time, and the references into this section will be stored in the program in a compressed format. A BSS section holds uninitialized global variables. Relocation entries in this format take the smallest space that is reasonable. The relocation code for the compressed format is rather large, but part of it only has to be inserted into the program once if multiple COMPRESSED_FORMAT_... features are used.

This feature uses the linker-specific symbol __ld_insert_compressed_bss_refs.

See also: KERNEL_FORMAT_BSS, MLINK_FORMAT_BSS, MERGE_BSS


OMIT_BSS_INIT
Previous Advanced Options of GCC4TI Next

Writing

#define OMIT_BSS_INIT
at the beginning of a file specifies that uninitialized global variables defined in this file do not need to be set to zero at program startup. If this is done for all files, the BSS initialization is skipped.


KERNEL_FORMAT_DATA_VAR
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define KERNEL_FORMAT_DATA_VAR
at the beginning of the program, and the data section is put into an external data variable, references into the data variable will be stored in the same manner as kernel programs store references. This does not mean that your program will need a kernel to run. Currently, this is the default.

This feature uses the linker-specific symbol __ld_insert_kernel_data_refs.

See also: MLINK_FORMAT_DATA_VAR, COMPRESSED_FORMAT_DATA_VAR


MLINK_FORMAT_DATA_VAR
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define MLINK_FORMAT_DATA_VAR
at the beginning of the program, and the data section is put into an external data variable, references into the data variable will be stored in the program in a compressed format. This format for the relocation entries (first used in Johan Eilert's mlink linker) is designed to balance the size of the relocs against the size of the decompression routine. The relocation entries take only slightly more space than in the compressed format, but the decoding code is much smaller. Moreover, as for the compressed format, the decoding code only has to be inserted into the program once if multiple MLINK_FORMAT_... features are used. In most cases, this should be the optimal format to use for relocation entries, but for programs with very few or very many relocations, the kernel or compressed formats (respectively) are more efficient.

This feature uses the linker-specific symbol __ld_insert_mlink_data_refs.

See also: KERNEL_FORMAT_DATA_VAR, COMPRESSED_FORMAT_DATA_VAR


COMPRESSED_FORMAT_DATA_VAR
Previous Advanced Options of GCC4TI Next

In nostub mode, if you put

#define COMPRESSED_FORMAT_DATA_VAR
at the beginning of the program, and the data section is put into an external data variable, references into the data variable will be stored in the program in a compressed format. Relocation entries in this format take the smallest space that is reasonable. The relocation code for the compressed format is rather large, but part of it only has to be inserted into the program once if multiple COMPRESSED_FORMAT_... features are used.

This feature uses the linker-specific symbol __ld_insert_compressed_data_refs.

See also: KERNEL_FORMAT_DATA_VAR, MLINK_FORMAT_DATA_VAR


OPTIMIZE_CALC_CONSTS
Previous Advanced Options of GCC4TI Next

If you are compiling a program for more than one calculator, you can put

#define OPTIMIZE_CALC_CONSTS
at the beginning of the program to optimize code speed and size. This will affect PSEUDO_CONST_CALC and everything derived from it - mainly pseudo-constants from compat.h, but you can also define your own pseudo-constants very easily.

Defining this does have one drawback: Each of the executable files produced by the linker can only be run on the calculator it was linked for and cannot be transferred from one type of calculator to another. A check to make sure the program is not run on a wrong calculator is inserted automatically, unless NO_CALC_DETECT is defined.

This feature uses the linker-specific symbol __ld_calc_const_....


NO_CALC_DETECT
Previous Advanced Options of GCC4TI Next

By default, code to detect the calculator model is inserted at the start of the program. This is used mainly to optimize the pseudo-constants defined in compat.h if more than one calculator has to be supported. However, it is also used to prevent the program from being run on an unsupported calculator. You can turn this check off by writing

#define NO_CALC_DETECT
Note that the detection is turned off automatically if it is not needed.


EXECUTE_IN_GHOST_SPACE
Previous Advanced Options of GCC4TI Next

Sometimes, on hardware version 2, it is necessary to execute a program in the so-called "ghost space", which is the area of addresses above 0x40000. If you need to know more about this, read the launcher FAQ entry. If you put

#define EXECUTE_IN_GHOST_SPACE
at the beginning of your program, on hardware version 2 (and 1, for backwards compatibility reasons), the program will automatically be executed in the ghost space. This causes an overhead of about 200 bytes. More precisely, it will relocate itself in the ghost space (by applying EX_patch to itself with the start address increased by 0x40000) before entering the ghost space. Everything will be performed before anything else. Therefore, there are no limitations introduced by this directive on hardware versions 1 and 2, whereas the older enter_ghost_space function was very limited and hard to use.

EXECUTE_IN_GHOST_SPACE allows the user to simply call one program from another, without worrying about the AMS protections which usually prevent this.

Unfortunately, on hardware version 3 (TI-89 Titanium), it is not possible anymore to bypass the execution protection this way. EXECUTE_IN_GHOST_SPACE detects hardware version 3 and requires a FlashROM patch to be present, refusing the execution otherwise. The name might be changed in future versions of GCC4TI to reflect this. Therefore, you need to know that you should not blindly add 0x40000 to an address, because this does not work at all on the TI-89 Titanium. Instead, use HW_VERSION==2?0x40000:0 or HW_VERSION<=2?0x40000:0 as appropriate.


STRICT_POINTERS
Previous Advanced Options of GCC4TI Next

If functions from the GCC4TI Library take a pointer to an unsigned integer as an argument, you can usually pass a signed integer as well. However, this may not be desirable, as the function may write values to it which the turn out to be negative. The same is true the other way. To prevent this, use

#define STRICT_POINTERS


SET_FILE_IN_USE_BIT
Previous Advanced Options of GCC4TI Next

With this definition, the program's in use (a.k.a. hidden) bit is set while the program is running. Normally, this isn't necessary; however, the event dispatching loop deletes twin symbols unless their in-use bit is set. In many cases, programs which might be archived will not call the event dispatching loop directly. However, dialog boxes (including the catalog) do call the event dispatching loop. The result: If an archived program uses dialog boxes (including the catalog), then the program's twin symbol will get deleted. Thus, the area of memory the program occupies gets freed, and the program will almost certainly crash. Setting this bit is handled automatically now, but you can still set it manually by defining this at the beginning of a file:

#define SET_FILE_IN_USE_BIT


UNOFFICIAL_OS_SUPPORT
Previous Advanced Options of GCC4TI Next

Normally, programs written in GCC4TI are ensured to be compatible only with the "AMS" operating system that is installed on TI-89, TI-89T, TI-92 Plus or V200 calculators by default. Running them on unofficial operating systems might produce an error message or crash the calculator. If you write

#define UNOFFICIAL_OS_SUPPORT
at the top of each source file, most of the hacks that require the original "AMS" software to be installed are turned off, generating error messages at compile time instead. Defining a higher MIN_AMS value fixes the compile-time errors, but this might also prevent the program from being run on certain unofficial operating systems.

Of course, this definition does not guarantee that any particular unofficial operating system can run the program.

See also: REJECT_UNOFFICIAL_OS


REJECT_UNOFFICIAL_OS
Previous Advanced Options of GCC4TI Next

If your program uses a hack that is likely to fail in unofficial operating systems, you should write

#define REJECT_UNOFFICIAL_OS
at the top of at least one source file. This checks against all known unofficial operating systems (currently only a yet unreleased system called "PedroM"), before actually executing the program. However, do not abuse this feature to reject unofficial operating systems because you do not like the idea of unofficial operating systems, or because you know that your program does not work on a particular system. Valid uses of this feature are rare.

See also: UNOFFICIAL_OS_SUPPORT


_GENERIC_ARCHIVE
Previous Advanced Options of GCC4TI Next

If you are writing a function archive (also known as a static library), you will probably want to write:

#define _GENERIC_ARCHIVE
at the top of every C file that includes a header file from the GCC4TI Library. It tells the GCC4TI Library that you are creating a function archive (static library) which you want programs to be able to use no matter what their compiler, GCC4TILIB, linker and output format settings are. It disables all optimizations which rely on startup code, and it makes the library use a kernel-independent ROM call mechanism. It also disables outputting of any linker control symbols which force a specific output format.

All static libraries should use this option unless they are created for a very specific program (which implies you are probably better off linking the files directly into your project). However, some special features of the GCC4TI Library may not be available.


Linker Optimization Facilities
Previous Advanced Options of GCC4TI Next

The GCC4TI linker provides a lot of settings to control the optimization of binary code. When using the IDE, you can set these options in the "Linking" tab of the project settings. When using the command-line compiler, you can use the linker switches.

To make full use of section reordering, you should pass '-ffunction-sections' and '-fdata-sections' to the compiler.


GCC Optimization Switches
Previous Advanced Options of GCC4TI Next

The following GCC switches can possibly generate better code. However, some of them can also increase code size, decrease speed, or even produce invalid code if they are used incorrectly:

  • '-O1', '-O2', '-O3', '-Os'
  • '-fomit-frame-pointer'
  • '-mregparm'
  • '-freg-relative-reg'
  • '-fzero-initialized-in-bss'
  • '-mno-bss'


GNU Assembler Optimization Switches
Previous Advanced Options of GCC4TI

The following GNU assembler switches can possibly generate better code:

  • '-l'
  • '--short-jumps'


Program Comments
Previous Making GCC4TI Programs Next

Program comments are data supplied by the author of a program, to provide additional information for users. Some or all of the information may be ignored depending on the type of program or library you are creating. Currently only nostub programs can handle the full range of information; kernel programs are restricted to the simple comment string. For Nostub DLLs, the information is not ignored (so it will waste space in the DLL), although it should be.

  • COMMENT_STRING
  • COMMENT_PROGRAM_NAME
  • COMMENT_VERSION_STRING
  • COMMENT_VERSION_NUMBER
  • COMMENT_AUTHORS
  • COMMENT_BW_ICON
  • COMMENT_GRAY_ICON


COMMENT_STRING
Program Comments Next

To define a comment string, write

#define COMMENT_STRING "comments"
at the top of your source code. If supported by the target format, this will include the text inside the quotes as a comment string. It can be arbitrary text, but as a general rule, it should fit into the status line of a TI-89.


COMMENT_PROGRAM_NAME
Previous Program Comments Next

To define a name for your program, write

#define COMMENT_PROGRAM_NAME "name"
at the top of your source code. If supported by the target format, this will store the text inside the quotes as a program name. The name can be longer than eight characters, but it should not include any additional information such as a version number or author name(s).


COMMENT_VERSION_STRING
Previous Program Comments Next

To include user-visible version information in the program, write

#define COMMENT_VERSION_STRING "version"
at the top of your source code. If supported by the target format, this will include the text inside the quotes as a version string. It can have an arbitrary format, but it should be recognizable as a program version, for example major.minor.

See also: COMMENT_VERSION_NUMBER


COMMENT_VERSION_NUMBER
Previous Program Comments Next

To include structured version information in the program, write

#define COMMENT_VERSION_NUMBER major, minor, revision, subrevision
at the top of your source code. If supported by the target format, this will include some or all of the numbers (which must be between 0 and 255) inside the program. Structured version information enables other programs such as shells to do version comparison and checks.

See also: COMMENT_VERSION_STRING


COMMENT_AUTHORS
Previous Program Comments Next

To include the names of the author(s) of your program, write

#define COMMENT_AUTHORS "author(s)"
at the top of your source code. If supported by the target format, this will store the text inside the quotes as author information. The name can be arbitrarily long, but don't include any information other than the names of one or more authors, authoring teams or entities. You should also keep in mind that these names take up place in your program and that they are intended to be displayed by calculator shells with limited screen space, so consider using a team name rather than a long list of individuals.


COMMENT_BW_ICON
Previous Program Comments Next

You can include a 16x16 pixel icon in your program, for display in shells. To do this, write

#define COMMENT_BW_ICON {line0, line1, ..., line15}
at the top of your source code. Each of the lines is specified as a 16 bit number, with the most significant bit being the leftmost pixel. If you use binary numbers to define the numbers, you can easily see what the icon will look like. The icon is defined in the same format as an ICON structure.

See also: COMMENT_GRAY_ICON, ICON


COMMENT_GRAY_ICON
Previous Program Comments

If you have an icon in your program (see COMMENT_BW_ICON), you can enhance it using grayscale. To do this, write

#define COMMENT_GRAY_ICON dark, light
at the top of your source code, where dark and light are the dark and light plane parts of the icon as defined in COMMENT_BW_ICON. For the dark plane part, you might actually want to use COMMENT_BW_ICON.

See also: COMMENT_BW_ICON, gray.h


Incompatibility Information
Previous Making GCC4TI Programs Next

Incompatibility data can be used to specify that running the program outside of the usual calculator home screen environment may be problematic. Not all program formats permit storing incompatibility data; in particular, currently only the nostub format does. However, in a usual program, you will never have to set any of these incompatibility flags; most of them only apply to TSRs (programs that hook into the operating system and stay in memory after termination).

  • INCOMPAT_CREATES_HANDLES
  • INCOMPAT_USES_TRAPS
  • INCOMPAT_USES_VECTORS
  • INCOMPAT_USES_EV_HOOK
  • INCOMPAT_NEEDS_ALL_STACK


INCOMPAT_CREATES_HANDLES
Incompatibility Information Next

If your program allocates memory which may not be freed automatically after exiting the program, and which does not belong to a VAT symbol or home screen item, you should write

#define INCOMPAT_CREATES_HANDLES
at the top of at least one source file, before including any header file from the GCC4TI Library. This especially refers to TSRs that allocate memory. If a shell or another tool freed the memory, the calculator would crash sooner or later. This directive should prevent such tools from automatically freeing memory allocated by the program.


INCOMPAT_USES_TRAPS
Previous Incompatibility Information Next

If your program is a TSR that hooks a trap (see SetIntVec), you should write

#define INCOMPAT_USES_TRAPS
at the top of at least one source file, before including any header file from the GCC4TI Library. If this directive is not used, a shell might automatically restore the hooked trap, rendering the TSR useless. Or it might even just free other resources allocated by the program, causing a crash.

See also: INCOMPAT_USES_VECTORS


INCOMPAT_USES_VECTORS
Previous Incompatibility Information Next

If your program is a TSR that hooks an interrupt or exception (see SetIntVec) or makes any other change to the interrupt vector table other than traps, you should write

#define INCOMPAT_USES_VECTORS
at the top of at least one source file, before including any header file from the GCC4TI library. If this directive is not used, a shell might automatically restore the hooked interrupt, rendering the TSR useless. Or it might even just free other resources allocated by the program, causing a crash.

See also: INCOMPAT_USES_TRAPS


INCOMPAT_USES_EV_HOOK
Previous Incompatibility Information Next

If your program is a TSR that hooks events (see EV_hook), you should write

#define INCOMPAT_USES_EV_HOOK
at the top of at least one source file, before including any header file from the GCC4TI Library. If this directive is not used, a shell might automatically remove the event hook, rendering the TSR useless. Or it might even just free other resources allocated by the program, causing a crash.


INCOMPAT_NEEDS_ALL_STACK
Previous Incompatibility Information

If your program needs the entire stack (or almost the entire stack) to be free, you should write

#define INCOMPAT_NEEDS_ALL_STACK
at the top of at least one source file, before including any header file from the GCC4TI Library. This will prevent shells that fill up part of the stack from executing the program.


Defining a Minimum AMS Version
Previous Making GCC4TI Programs Next

In some cases it might be desirable to use features which are only present in the latest versions of the AMS. In this case, you need to define the minimum version the program will run under explicitly, like this:

#define MIN_AMS 200
MIN_AMS has to be a 3-digit decimal number, which is obtained by multiplying the AMS version with 100 (or omitting the dot, if the version has the format "x.xx").

If you do not specifiy a sufficient minimum AMS version, the functions and constants which are not available will not even be defined. Note that MIN_AMS defaults to 101, which means AMS 1.01 on the TI-92 Plus, and AMS 1.00 on the TI-89. These two versions are in fact the same.

You can bypass the AMS check which is performed at startup by defining NO_AMS_CHECK.

To find out about the different ways we try to overcome AMS dependencies, read the next section, Overcoming AMS Dependencies.


Overcoming AMS Dependencies
Previous Making GCC4TI Programs

Many AMS dependencies result from the unavailability of specific ROM calls in the operating system. The AMS maintains a table of pointers of functions, the jump table (see __jmp_tbl in default.h). In early AMS releases this jump table was very incomplete, and it even changed at some places. Nevertheless, we try to maintain compatibility as much as possible. There are five types of workarounds for AMS dependencies:

  • Manually Obtaining the Address of a ROM Function
  • Wrapping a ROM Function in tigcc.a
  • Wrapping a ROM Function with a Macro
  • Reimplementing a ROM Function in tigcc.a
  • Reimplementing a ROM Function as a Macro


Manually Obtaining the Address of a ROM Function
Overcoming AMS Dependencies Next

If a function is not in the jump table (at least in early versions of the AMS), there are often ways to obtain its address manually through some very dirty hacks. If possible, these hacks are really only used in those AMS releases where the jump table entry is missing, so the hacks are usually safe. The only exception is when the function is not listed in any jump table. If this is the case, the documentation will contain the type "Function (ROM Call)", but without an index.

If this is not the case, you can usually gain speed and decrease the program size by defining a suitable minimum AMS version.

See also: _rom_call_hack


Wrapping a ROM Function in tigcc.a
Previous Overcoming AMS Dependencies Next

Sometimes a ROM function exists as a normal ROM call in the jump table, but for some reason it is not usable in a direct way. This means that it has to be implemented either using macros or using a wrapper function in tigcc.a.

This does not have to be related to an AMS dependency; it may also be because of a bug in the AMS, or because of some missing feature.


Wrapping a ROM Function with a Macro
Previous Overcoming AMS Dependencies Next

Sometimes a ROM function exists as a normal ROM call in the jump table, but for some reason it is not usable in a direct way. This means that it has to be implemented either using macros or using a wrapper function in tigcc.a. Using a macro prevents you from taking the address of the function and therefore from using it as a callback function.

This does not have to be related to an AMS dependency, although it is in the special case of XR_stringPtr. In fact, all functions returning float values are implemented in this way, since the TIOS method of returning floats is strange to say the least.


Reimplementing a ROM Function in tigcc.a
Previous Overcoming AMS Dependencies Next

Sometimes it is hard or tedious to obtain the address of an AMS-dependent function in a nonstandard way. In this case, the function may be reimplemented in tigcc.a. Often the user-defined minimum AMS version is used to determine whether this implementation or the real ROM function should be used.


Reimplementing a ROM Function as a Macro
Previous Overcoming AMS Dependencies

Sometimes it is hard or tedious to obtain the address of an AMS-dependent function in a nonstandard way. In this case, the function may be implemented as a macro which works in all (or almost all) AMS versions. Often the user-defined minimum AMS version is used to determine whether this macro definition or the real ROM function should be used. Like every macro definition, this prevents you from taking the address of the function and therefore from using it as a callback function.


Using Floating Point Arithmetic

If you have used very old releases of TIGCC (prior to 0.9), you probably know that the use of floating point values and functions was possible, but only using some very awkward syntax, which caused a lot of headaches and nightmares. The TIGCC Team (mostly Sebastian Reichelt and Zeljko Juric) spent a lot of time and effort implementing native (ANSI) floats in TIGCC. And the results are now available: you can use regular floating point numbers and values now, as in all regular C compilers! This means that:

  • You can now use the standard ANSI types float, double and long double without any trouble (in fact, these three types are the same, there is no difference between them). The old-style type ti_float still exists due to compatibility reasons, but now it is the same as float.
  • You can now use "standard" floating point constants (like 2.854). So, the following is now valid:
    float a, b, c;
a = 2.854;
b = 7;
c = 1.5e-7;
    In other words, no more ugly FLT and FEXP macros! They still exist due to compatibility reasons, but their usage is very deprecated now.
  • You can now use standard arithmetic ('+', '-', '*', '/) and comparison ('<', '>', '<=', '>=', '==' and '!=') operators with floating point values. There is no need any more for the use of awkward functions like fadd, fcmp etc. So statements like these are now accepted:
    p = (q + 3.15) / (q - r);
x1 = (-b + sqrt (b * b - 4 * a * c)) / (2 * a);
if (p < 3.0) q += 1e-3;
    This feature is probably the best present for users...
  • You can use all floating point functions (like sqrt, sin etc.) as usual. In this release, a standard ANSI math library math.h is implemented, which contains nearly all functions proposed by ANSI C, with some extensions. The old timath.h library file still exists due to compatibility reasons, and it contains more functions than math.h, because it contains some functions for making compatibility with older programs, and some functions which are internally related to the TIOS. Anyway, you can do calculations like these:
    a = sin (b);
b = exp (1);
c = log (3.19);
a = sqrt (b + c) * sinh (a / 2.);
    As you can see from the second example, automatic promotion from integer constants to the floating point is also implemented.
  • Integer types are now automatically promoted to floating point values when necessary, as proposed in ANSI C. This means that the following constructions are valid, assuming that 'n' is a variable of integer (short, long, signed, unsigned) type:
    a = n;
b = sqrt (n);
c = b + n;
    You can also explicitely cast an integer value to a floating point one:
    a = (float)n;
    The function flt which performs the promotion explicitely still exists, due to compatibility reasons.
  • Floating point types are automatically truncated to integers when the program expects an integer value (for example, when a floating point variable is assigned to an integer variable), as proposed in ANSI C. This means that you can write
    n = a;
    where 'n' is an integer, and 'a' is a float, although it is better to express your wish more explicitely using type cast as
    n = (int)a;
    The function trunc which performs the truncation explicitely still exists due to compatibility reasons.
  • You can use printf and similar functions to print floating point values, using the format specifiers %f, %e and %g, as defined in ANSI C. So, the following is completely legal:
    printf ("sin(%f)=%f", a, sin(a));
printf ("%f", 3.14);
    Note that the second statement was not valid prior to release 0.9 of TIGCC!
  • To accept a floating point value from the keyboard, first accept it as a string (using gets, some user-written input routine, or functions from dialogs.h), then convert the string to a floating point value using the atof (ascii-to-float) function. To get a floating point argument passed from TI-Basic to the program, use the GetFloatArg function.
As you can see, the usage of floats is now essentially the same as in all other C compilers. See the description of the math.h and timath.h header files for more info. However, floating point support is not perfect yet. That's why there are still some limitations in the use of floating point values (fortunately, they are not serious):
  • The promotion of double long integers (long long types) to floating point values, and truncation of floating point values to longlongs are not implemented yet. If you try to do this (which is not very likely), you will get an "undefined reference" error during the linking stage.
As an example of usage of floating point values and functions, the program given below (called "Float Test") reads coefficients of a quadratic equation from the keyboard, then calculates and displays the solutions of the equation (including complex ones):
#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#define SAVE_SCREEN

#include <stdio.h>
#include <math.h>
#include <string.h>
#include <kbd.h>

void _main(void)
{
  float a, b, c, d;
  char buffer[200];
  clrscr ();
  puts ("a=");
  a = atof (gets (buffer));
  puts ("b=");
  b = atof (gets (buffer));
  puts ("c=");
  c = atof (gets (buffer));
  if (is_nan (a) || is_nan (b) || is_nan (c)) return;
  d = b * b - 4. * a * c;
  if (d >= 0.)
    {
      float x1, x2;
      x1 = (-b + sqrt (d)) / (2. * a);
      x2 = (-b - sqrt (d)) / (2. * a);
      printf ("\nx1=%f\nx2=%f", x1, x2);
    }
  else
    {
      float re, im;
      re = -b / (2. * a);
      im = fabs (sqrt (-d) / (2. * a));
      printf ("\nx1=%f-%f*i\nx2=%f+%f*i", re, im, re, im);
    }
  ngetchx();
}
See the description of the included header files for more info about the functions used.

As already mentioned above, the new floating point support is implemented while retaining good compatibility with programs written with releases of TIGCC before 0.9 (read below to see possible reasons of incompatibility). So, the quadratic equation solver given below, which is written using old methods, will still work with a new compiler. Compare this (old-style) code with the previous (new-style) one to see how much clearer the new-style code is...
#define SAVE_SCREEN

#include <stdio.h>
#include <timath.h>
#include <string.h>
#include <kbd.h>

int _ti89, _ti92plus;

void _main (void)
{
  ti_float a, b, c, d;
  char buffer[200];
  clrscr ();
  puts ("a=");
  a = atof (gets (buffer));
  puts ("b=");
  b = atof (gets (buffer));
  puts ("c=");
  c = atof (gets (buffer));
  if (is_nan (a) || is_nan (b) || is_nan (c)) return;
  d = fsub (fmul (b, b), fmul (FLT (4), fmul (a, c)));
  if (fcmp (d, ZERO) >= 0)
    {
      ti_float x1, x2;
      x1 = fdiv (fadd (fneg (b), sqrt (d)), fadd (a, a));
      x2 = fdiv (fsub (fneg (b), sqrt (d)), fadd (a, a));
      printf ("\nx1=%f\nx2=%f", x1, x2);
    }
  else
    {
      ti_float re, im;
      re = fdiv (fneg (b), fadd (a,a));
      im = fabs (fdiv (sqrt (fneg (d)), fadd(a, a)));
      printf ("\nx1=%f-%f*i\nx2=%f+%f*i", re, im, re, im);
    }
  ngetchx();
}
The possible reasons which may cause incompatibility (very unlikely) with programs written with very old versions of TIGCC (prior to 0.9) are:
  • The types ti_float and bcd are not the same any more. ti_float is now equal to ANSI type float, but bcd is still a structure. If your program uses the bcd type (not very likely), you should probably change it to float to make the program work, because functions which expect a float type will not accept a structured type. Two macros called float_to_bcd and bcd_to_float have been introduced to provide more general conversion if necessary.
  • Functions fadd, fsub, fmul, fdiv, fneg, fcmp, flt and trunc are not absolutely equal to functions bcdadd, bcdsub, bcdmul, bcddiv, bcdneg, bcdcmp, bcdbcd and bcdlong any more. The first group of functions now works with the ordinary float type (and they will continue to work with ti_float), but the second group now only works with bcd structures. So, if you used bcdadd etc. in your program (not very likely), you should probably change it to fadd etc. to make the program work.
  • Suppose that your old program uses the ti_float type with direct access to its internal fields (not very likely), like in the following example:
    ti_float a;
a.exponent = 0x4003;
a.mantissa = 0x3284300000000000;
    Then the program will not work with the new compiler, because ti_float is not a structure any more. Using a new macro bcd_var you can easily get your program to work. All you need to do is to re-express the above statements as
    ti_float a;
bcd_var(a).exponent = 0x4003;
bcd_var(a).mantissa = 0x3284300000000000;
    Note, however, that the bcd type is still a structure.


Returning Values
  • Returning Values Like TI-Basic Functions
  • Returning Values Through Variables
  • Returning TI-Basic Errors


Returning Values Like TI-Basic Functions
Returning Values Next

It is possible to write programs which return a value to the TI-Basic, i.e. which act like TI-Basic function (with some serious limitations; read below for more info). To do this, put the following statement at the begining of the program (or at the begining of the main module of your program):

#define RETURN_VALUE
This will work in both NoStub and kernel mode. Such statement will cause the last value pushed to the expression stack to become the "result" of the program. For pushing values on expression stack, use routines from the estack.h header file. For example, use push_shortint or push_longint to push integer values, push_Float to push floating point values, push_zstr to push strings, etc. Note that if you declared RETURN_VALUE, you must push something on the expression stack.

If you plan to write a function which returns a value to TI-Basic in either ASM or C, you should also clean up all arguments of the function from the expression stack before pushing the result including the END_TAG. If you neglect to do this, then using the function as an argument of another one will not work correctly. Also, you should leave exactly one value on the expression stack (i.e. you should delete all eventual temporary results from the expression stack). Here is a sample code how you can clean up function arguments from the expression stack:
while (GetArgType (top_estack) != END_TAG)
  top_estack = next_expression_index (top_estack);
top_estack--;
Here is a complete example (called "Add Arguments") of a very simple program which gets two arguments (assuming that they are small positive integers, without any checking), and returns their sum (see args.h for more info about getting the arguments):
// Add the first two integers passed to the program

#define RETURN_VALUE

#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#define MIN_AMS 101

#include <args.h>
#include <estack.h>

void _main(void)
{
  ESI argptr = top_estack;
  short a = GetIntArg (argptr);
  short b = GetIntArg (argptr);
  while (GetArgType (top_estack) != END_TAG)  // Clean up arguments
    top_estack = next_expression_index (top_estack);
  top_estack--;
  push_longint (a + b);
}
Test this program from TI-Basic by giving add(2,3) (assuming that you compiled it and gave the name "add.c" to it). Note that if you neglect cleaning up arguments from the expression stack, then something like add(add(3,5),add(4,7)) will not give the correct result!

You can even return lists as the result. To do this, push first End_Of_List marker (using push_END_TAG), then push elements of the list in the reverse order, and finnaly push List marker on the expression stack using push_LIST_TAG. The following program (called "Folder") returns the list of all variables in the folder which is given as the argument:
// Get the variables in a folder as a list

#define RETURN_VALUE

#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#define MIN_AMS 101

#include <args.h>
#include <estack.h>
#include <vat.h>

void _main(void)
{
  ESI argptr = top_estack;
  SYM_ENTRY *SymPtr = SymFindFirst (GetSymstrArg (argptr), 1);
  while (GetArgType (top_estack) != END_TAG)  // Clean up arguments
    top_estack = next_expression_index (top_estack);
  top_estack--;
  push_END_TAG ();
  while (SymPtr)
    {
      push_ANSI_string (SymPtr->name);
      SymPtr = SymFindNext ();
    }
  push_LIST_TAG ();
}
Give the name "folder.c" to it, compile it using

tigcc -O2 folder.c

then try, for example, folder("main") from the TI-Basic. Happy? Many users asked me how to make such a program!

Now about problems. Everything works fine in AMS 1.xx, but AMS 2.xx forbids the use of ASM programs in expressions. So, in the above example, 'add(2,3)' will work perfectly, but '5+add(2,3)' or even 'add(2,3)->a' will not. This stupidity makes returning values mostly useless. What to do? Unfortunately, I can't do nothing from GCC4TI itself, because an ASM program will not be executed at all if AMS 2.xx detects its presence in an expression. However, there is a solution: it is possible to make a resident program which will intercept such "stupid" behaviour of AMS 2.xx and to allow executing ASM programs in expressions. Such interception is already implemented in PreOS and KerNO. So, if you have installed a fresh release of PreOS or KerNO, everything will work OK even on AMS 2.xx. There is also a TSR called IPR which intercepts only this error and the "ASAP or Exec string too long" error available at Cyril Pascal's (Paxal's) web page for those who don't want to install a full-featured kernel. But for HW2 calculators, the HW2 AMS 2 TSR support (h220xTSR) needs to be installed before IPR. This does not mean that your program must be compiled in "kernel" mode: it may be a "nostub" program, but PreOs, KerNO or IPR must be present on the calculator (to intercept stupid behavior of AMS 2.xx). To conclude: if you have AMS 2.xx and if you want to use "returning a value" feature, you must have installed PreOs, KerNO or IPR. If you are a programmer, please note this fact in the documentation of any program which uses this feature!

As an alternative, you may use returning values through variables.


Returning Values Through Variables
Previous Returning Values Next

As mentioned in the previous section, returning a value from ASM program on a similar way like TI-Basic functions return values causes problems with AMS 2.xx. Therefore, another way for returning values (which works well unconditionally) was introduced. This method will be ilustrated using a concrete example. Look the following modified "Folder" program given in the previous section (called "Folder List"):

// Write the variables in a folder into a list variable

#define RETURN_VALUE dirlist

#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#include <args.h>
#include <estack.h>
#include <vat.h>

void _main(void)
{
  ESI argptr = top_estack;
  SYM_ENTRY *SymPtr = SymFindFirst (GetSymstrArg (argptr), 1);
  push_END_TAG ();
  while (SymPtr)
    {
      push_ANSI_string (SymPtr->name);
      SymPtr = SymFindNext ();
    }
  push_LIST_TAG ();
}
The only difference between this program and the program in the previous section is in the usage of the RETURN_VALUE directive: in this example, it is followed with a variable name (dirlist in this example). If RETURN_VALUE is followed with a variable name (which must be a legal TI-Basic variable name in lowercase), the last value pushed to the expression stack would be stored in the TI-Basic variable with the given name. So, in this example, after execution of the program, the result of the program (a folder list) will be stored in TI-Basic variable called dirlist (if such variable does not exist, it will be created). See the previous section for more info about this example. I hope that this explanation is clear enough, so more detailed explanation is not necessary.


Returning TI-Basic Errors
Previous Returning Values

Basically, you can return errors using ER_throw or ER_throwVar from error.h. Many functions from this library throw errors, which you can simply pass on to the operating system, possibly using TRY...FINALLY...ENDFINAL blocks.

However, for the system to operate normally after this, you need to write

#define ENABLE_ERROR_RETURN
at the beginning of your program. Otherwise, the screen will not be updated properly and other cleanup code (for example for USE_INTERNAL_FLINE_EMULATOR) is not executed. Most importantly, however, the program handle remains locked in AMS 1.xx because of a bug in the operating system. If you try to start the program again, you will get an "Invalid Program Reference" error.

Note: The workaround for this bug works only in kernel-less programs. For kernel-based programs, working around the bug is the kernel's responsibility. If you want to use this directive in kernel mode, you need to check which kernels perform such a workaround, and tell your users about this fact.

The following example (called "Memory Error") demonstrates how this directive may be used together with TRY...FINALLY...ENDFINAL blocks:
// Allocate memory as long as possible, then throw an error
// All allocated memory will be freed again!

#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 ENABLE_ERROR_RETURN   // Enable Returning Errors to TIOS

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

#define BLOCK_SIZE 1024

void AllocRecursively(void)
{
  void *ptr = malloc_throw (BLOCK_SIZE);
  TRY
    // Could do something with ptr here...
    AllocRecursively ();
    // Could still do something with ptr...
  FINALLY
    free (ptr);
  ENDFINAL
}

// Main Function
void _main(void)
{
  AllocRecursively ();
}


Using Symbolic Mathematics

Using this library you can use even complex calculations which include algebraic manipulations, calculus, etc. Everything you need is to build up the expression on the expression stack in RPN (Reverse Polish Notation) form using various functions from estack.h header file, then to evaluate the expression using functions NG_approxESI or NG_rationalESI. You need to know what is RPN (also known as Postfix Notation) to do this (see estack.h for a list of RPN tokens). Symbolic mathematics will be ilustrated through various examples. First example will be a simple program which takes two polynoms (or more general expressions) as arguments, multiplies them, then returns a new polynom as the result. In TI-Basic, you can perform such calculations using TI-Basic function

expand (arg1 * arg2)
where arg1 and arg2 are arguments. This may be represented in RPN form as
arg2  arg1  *  expand
So, here is a program (called "Multiply Polynoms"; note that arg2 and arg1 are already on the stack before entering the program):
// Multiply and expand the two polynoms passed to the program

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define RETURN_VALUE          // Return a value
#define ENABLE_ERROR_RETURN   // Enable returning errors
#define MIN_AMS 101           // Compile for AMS 1.01 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// Main Function
void _main(void)
{
  push_quantum_pair (MUL_TAG, EXPAND_TAG);
  NG_rationalESI (top_estack);
}
It is highly recommended to pass errors on to the AMS. After compiling this program (assuming that its name is "polymul.c") try this from TI-Basic:
polymul (x+y, x-y)
But note that returning values from ASM programs to TI-Basic is not without severe limitations. See the section about returning values to TI-Basic.

estack.h contains two very useful functions which convert ordinary algebraic expressions (given in a string) to tokenized RPN form and vice-versa, named push_parse_text and display_statements (although they are somewhat slow, so if you want fast calculations, force RPN as much as possible). They are very useful if you want to process algebraic data accepted from the keyboard, or to display algebraic data on the screen. Also, a function Print2DExpr is implemented, which "pretty prints" the expression in a window. Here is an example of a program (called "Pretty Print") which calculates the ingegral of 1/((x-3)(x^2+4)) with respect to x and "pretty prints" the result on the screen:
// Calculate an integral and pretty print it

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

#define MIN_AMS 101           // Compile for AMS 1.01 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// Main Function
void _main(void)
{
  TRY
    push_END_TAG ();
    push_quantum (VAR_X_TAG);
    push_parse_text ("1/((x-3)(x^2+4))");
    push_quantum (INTEGRATE_TAG);
    NG_rationalESI (top_estack);
    WinClr (DeskTop);
    Print2DExpr (Parse2DExpr (top_estack, FALSE), DeskTop, 0, 50);
  ONERR
    DrawStr (20, 20, "Error!", A_NORMAL);
  ENDTRY
  ngetchx ();
}
As already mentioned above, powerful applications should avoid push_parse_text as much as possible, and use RPN as much as possible. This will be ilustrated through an example. The expression
Integral (1/((x-3)(x^2+4)), x)
may be expressed in the RPN form (see estack.h) as shown below:
x  1  x  3  -  2  x  ^  4  +  *  /  Integral
According to this representation, the previous program may be rewritten as ("Static Expression"):
// Evaluate and print a static expression

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

// Main Function
void _main(void)
{
  static unsigned char rpn[] = {END_TAG, VAR_X_TAG, 1, 1, POSINT_TAG,
    VAR_X_TAG, 3, 1, POSINT_TAG, SUB_TAG, 2, 1, POSINT_TAG, VAR_X_TAG,
    POW_TAG, 4, 1, POSINT_TAG, ADD_TAG, MUL_TAG, DIV_TAG, INTEGRATE_TAG};
  NG_rationalESI (rpn + sizeof (rpn) - 1);
  WinClr (DeskTop);
  Print2DExpr (Parse2DExpr (top_estack, FALSE), DeskTop, 0, 50);
  ngetchx ();
}
Maybe you want to find an integral of the function which is passed as the argument of the program in respect to x, and to print the result using the ordinary printf function (i.e. without "pretty printing")? OK, why not? Here is an example (called "Integrate"):
// Integrate the argument with respect to x and display it

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 101           // Compile for AMS 1.00 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// Main Function
void _main(void)
{
  ESI argptr = top_estack;
  HANDLE h;
  clrscr ();
  TRY
    push_END_TAG ();
    push_quantum (VAR_X_TAG);
    push_expr_quantum (argptr, INTEGRATE_TAG);
    NG_rationalESI (top_estack);
    h = display_statements (top_estack, 1, FALSE);
    printf ("The integral is: %s", (const char*) (HeapDeref (h)));
    HeapFree (h);
  ONERR
    printf ("Error!");
  ENDTRY
  ngetchx();
}
A lot of extremely powerful math functions are implemented in the estack.h header file, which are never seen in TI-Basic: accessing various parts of expressions, extracting factors, terms, etc. Of course, don't try to make any program for symbolic math before studying the estack.h header file carefully. Anyway, bascmd.h, basfunc.h, and basop.h are useful for symbolic mathematics as well.

See also: estack.h, basfunc.h, basop.h, bascmd.h


Breaking the 64KB Limit Using a DLL

Breaking the 64 KB limit is an important topic, and because of the internal representation of files in the AMS as well as the size limit of memory blocks, it is possible only by breaking the program up into multiple files.

If you get close to this limit, the first thing to do is optimizing the program. Ways to do this are those described in Advanced Options of GCC4TI, using functions from the AMS instead of those from the GCC4TI Library, and, last but not least, hand-optimizing the code. If and only if you are still close to the limit, you should think about the possibility to use multiple files. At first, try storing as much data as possible (sprites, maps, etc.) in external files (using functions from vat.h). If this still does not help, the only possibility left is to split the code into multiple files.

This means that you need to use some form of dynamic link libraries. These are very well-known for kernel programs, but kernel-mode libraries are not something we want to encourage, seeing that they have led to a huge mess of versioning problems and incompatiblities. For information about how to create them, see the section How to make kernel-based programs. The necessary definitions for libraries for kernel-less programs can be found in the dll.h header file.

Now that we have explained why you might need to use external libraries, we specifically want to discourage their use for anything else. External (dynamic) libraries have been used quite often in the past to automate common tasks, like file access, graphics, compression, etc. This is not what we want to happen, otherwise there will be a different libraries for the same tasks, with a lot of incompatiblities between libraries and even between different versions of the same library. GCC4TI provides the possibility to use static libraries (also known as function archives) for this purpose. In the IDE, you need to select the creation of a function archive in the project options; when using the command line compiler, you need to use the '-ar' switch. When using function archives, only the files which are needed are really included in the final program.

There is an exception to the rule that you should not create a dynamic library to make it available to others: If the library itself is very large, and a program will typically use a lot of its functions at the same time, client programs are likely to exceed the file size limit if it is provided as a static library. In this case, using a dynamic library really is the only possibility. An example is the FAT Library by the TI-Chess Team.

Hopefully, we have talked you out of creating a dynamic library if there is any other reasonable option. Now we can explain how to create a dynamic library in nostub (kernel-less) mode. For detailed explanations of all directives, take a look at the dll.h header file. The "Custom DLL" example demonstrates the creation of a very small library (note that the library file must have the name "mydll" on the calculator):

// Custom DLL example; must be named "mydll"
// Note: You should not use DLLs under normal circumstances; see section
// "How to break the 64 KB limit using a DLL" for more information.

#define USE_TI89

#include <tigcclib.h>

DLL_INTERFACE

char MessageInDLL[]="Hello!\n";
long GlobalVarInDLL;
void HelloFromDLL(void);
int SumFromDLL(int,int);

DLL_ID 372377271
DLL_VERSION 2,12
DLL_EXPORTS HelloFromDLL,SumFromDLL,MessageInDLL,&GlobalVarInDLL

DLL_IMPLEMENTATION

void HelloFromDLL(void)
{
  printf ("Hello from DLL!\n");
  printf ("Global variable is %ld\n", GlobalVarInDLL);
}

int SumFromDLL(int a, int b)
{
  return (a + b);
}
The order of the definitions is very important; read more about this in DLL_INTERFACE. The exported symbols are HelloFromDLL, SumFromDLL, MessageInDLL, and GlobalVarInDLL; they are assigned index numbers from 0 to 3.

A client program which uses this DLL could look like the following example, called "Custom DLL Test":
#define USE_TI89

#include <tigcclib.h>

#define HelloFromDLL _DLL_call(void,(void),0)
#define SumFromDLL _DLL_call_attr(int,(int,int),__attribute__((stkparm)),1)
#define MessageInDLL _DLL_reference(const char,2)
#define GlobalVarInDLL _DLL_glbvar(long,3)

void _main(void)
{
  if (LoadDLL ("mydll", 372377271, 2, 11) != DLL_OK)
    {
      DlgMessage ("ERROR", "Error loading DLL!", BT_OK, BT_NONE);
      return;
    }
  clrscr ();
  GlobalVarInDLL = 1234567;
  HelloFromDLL ();
  printf ("Sum from DLL: 2+3=%d\n", SumFromDLL (2, 3));
  printf ("Message from DLL: %s\n", MessageInDLL);
  ngetchx ();
  UnloadDLL ();
}
This program simply demonstrates all possible ways to import symbols from the DLL. See LoadDLL and the corresponding identifiers for more information.

A program which wants to use DLLs has to be executing from the so-called "ghost address space". This means that the program either has to be started through an external launcher which calls enter_ghost_space (which is always the case if it is exe-packed), or EXECUTE_IN_GHOST_SPACE needs to be defined at the beginning of the program. You will will want to exepack the program anyway if it is large enough. In the IDE, this can be done through a check box in the project options; when using the command line compiler, you need to use the '-pack' switch.

Note that this example is an exception to the rules above. It breaks two rules: First, it does not even come close to the 64 KB limit. Second, there is a variable in the DLL that could be put in another file: MessageInDLL. This program should remain the only exception; it only exists because a small program is best to teach. Imagine trying to learn how to use a DLL from a program that pushed the 64 KB limit (several thousand lines of code)!

Certain pseudo-constants in compat.h depend on initialization code, which is not present at all in DLLs. Using definitions like NO_CALC_DETECT helps for calculator-dependent definitions, but not all parts of the GCC4TI Library are available (for example, defining RETURN_VALUE makes absolutely no sense).

Finally, we need to write a few sentences about DLL version information. The major version number needs to be changed if and only if two DLLs are incompatible with each other. Adding new functions does not make DLLs incompatible; rearranging them does, for example. Usually, you do not ever need to change the major version number. Increasing the minor version number means that the DLL is still compatible with existing programs; the client program can specify a minimum minor version number to indicate that it depends on the new functionality.

See also: dll.h


Frequently Asked Questions

The FAQ list is organized into several categories. In each category, you will see a list of commonly asked questions in short form. Please click on a question that interests you to get the full form of the question and the related answer. Note, however, that some questions/answers are related to each other, and some answers are logical consequences of previous ones. So, after reading the answer, it is recommended to browse through surrounding quesion/answer pairs too, to get some more information.

Also, please visit the TICT & TIGCC/GCC4TI Programming Message Board and the GCC4TI message board. A lot of interesting topics about TIGCC/GCC4TI programming are discussed there.

  • The C Language
  • TI-Basic and C
  • Graphics and Display
  • Assembly and C
  • Strings
  • Event-driven Programming, Menus, and Throwing Errors
  • TI Variables and the Variable Allocation Table (VAT)
  • Memory, C Variables, and Pointers
  • Input: Keyboard and Link
  • Miscellaneous


The C Language
Frequently Asked Questions Next
  • Where can I learn more about C?
  • Will you implement C++?
  • I get weird error messages where I don't see errors.
  • Why do I get "Undefined Reference to..." errors?
  • How can I make a floating point comparison function for use with qsort?
  • Why do I get the message "invalid lvalue in unary '&'"?
  • Can I use # (indirection) like in TI-Basic?
  • I need the C equivalent of the when() function from TI-Basic.
  • I tried to use sizeof to get the size of an object, but it returned zero!
  • Can I use sizeof to determine the exact size of functions?


Where can I learn more about C?
The C Language Next

Q: | Is there any examples available on the net from which it is possible to learn something more...
A: | The best solution would be if I wrote a tutorial. Unfortunately, I have not enough time to write tutorials, small examples, etc. Some examples come with TIGCC starting from release 0.6, but this is probably not enough. I know that some people work on making a tutorial, but as far as I know, all of them are in a very early state. I suggest first learning C language (not C++) on some big computer (PC, Mac, etc.). A very good list of generic C language tutorials may be found on the TI-Chess Team Home Page. After learning the basics of C, reading the documentation of GCC4TILIB will be enough to learn how to apply this to TI programming. In addition, try looking at my programs like creversi, cblaster and scott (scott is in the advint.zip archive); all of them are in the TI-89 assembly games directory on ticalc.org. Note that every day the number of TI programs written in C increases, so now there are lots of open-source C programs which can be found on ticalc.org.


Will you implement C++?
Previous The C Language Next

Q: I learn C++ in a school so it will be good if I can program my TI-89 in C++ (not in ordinary C). Do you plan to implement C++ on TI-89?
A: No. Although C++ is more powerful language than C, it is not a language which is good for TI calculators. It is not efficient enough to be good for a calculator. The code generated by C++ is less efficient than code generated by ordinary C, and it is too bloated. So, even if somebody made C++ compiler for TI, I don't recommend using any C++ extensions (like classes, and especially streaming), except if you like programs like
cout << "Hello world";
which produces 5 Kb long code...


I get weird error messages where I don't see errors.
Previous The C Language Next

Q: The compiler sometimes report strange error messages on places where I really can not see any errors. For example, the compiler reports the error
parse error before 'void'
but the statement on which the error is reported was
int cexp;
I am really confused. First, I don't see any errors here, and second, I can't see any 'void' keywords here!
A: Yes, such problems may really be the source of big frustrations. There is nothing wrong with above statement, but note that 'cexp' is a function defined in timath.h header file, and you can not use this name as a name of a variable. Now you can say why you got such strange error message? See, the most of functions in GCC4TILIB are translated by the preprocessor into constructions which perform indirect function calls through a TIOS jump table. In other words, 'cexp' will be replaced by the preprocessor into the indirect function call constructor whenever it is used. So, the innocent statement like
int cexp;
will be converted into
int (*(void(**)(float,float,float*,float*))(*(long*)0xC8+1316));
which is a syntax error. And the error is just before 'void'.

I can not do anything against such hidden errors. Whenever you encounter strange errors without obvious reasons, check whether you used reserved library name for your identifier. The chance of making such errors is much smaller if you include only the necessary header files than if you include the general header file tigcclib.h.


Why do I get "Undefined Reference to..." errors?
Previous The C Language Next

Q: When I tried to compile my program, the linker reports to me
Undefined reference to ...
although my program seems correct. What's a problem?
A: Either something is wrong with your program (more probably you used a function which is not defined elsewhere, maybe due to typing error), or you used something which is not yet implemented yet in GCC4TI (which is probably true if you got an undefined reference to a symbol which begins which the double underscore '__'). For example, although GCC4TI supports very long (64-bit) integers ('long long' type, which is a GNU C extension), the support for multiplying and dividing double longs is not supported yet. For example, if you try to divide two double-long numbers, you will get an undefined reference to '__udivdi3'. Sorry, there is no simple help for this. You must live without 64-bit division for now. It may be implemented in the future.


How can I make a floating point comparison function for use with qsort?
Previous The C Language Next

Q: How I can define a comparison function for sorting an array of floats using qsort function:
A: Here is a simple example (called "Sort Floats"):
// Sort a list of floating point values

#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

// Comparison Function
CALLBACK short flt_comp(const void *a, const void *b)
{
  return fcmp (*(const float*)a, *(const float*)b);
}

// Main Function
void _main(void)
{
  float list[5] = {2.5, 3.18, 1.42, 4.0, 3.25};
  int i;
  clrscr ();
  qsort (list, 5, sizeof (float), flt_comp);
  for (i = 0; i < 5; i++)
    printf ("%f\n", list[i]);
  ngetchx ();
}


Why do I get the message "invalid lvalue in unary '&'"?
Previous The C Language Next

Q: Well, I need to know more about lvalues and GNU C initializers and cast constructors. Especially, I need to know why I sometimes get an error message "invalid lvalue in unary '&'"...
A: Click here to see everything about GNU C extensions. But if you are lazy to read too much, I will be more concrete here. First, in GNU C (GCC4TI is GNU C), initializers may be non-constants. For example,
int a = 3, b = 4, c = 5, d = 6;
int array[4] = {a, b, c, d};
is quite legal. That's why
int a = 3, b = 4, c = 5, d = 6;
SCR_RECT myScr = {{b + a, b - a, d + c, d - c}};
is quite legal too. Second, GNU C has one very nice extension in addition to ordinary C: cast constructors. This is a method for constructing structures, arrays, unions etc. "on fly" by using a typecasting of an initializer to an appropriate data type, for example
(SCR_RECT){{10, 10, 50, 50}}
So, you can use
SCR_RECT myScr;
...
myScr = (SCR_RECT){{10, 10, 50, 50}};
which is impossible in ordinary C (ANSI C). You can even use
myScr = (SCR_RECT){{a, b, c, d}};
where a,b,c,d are expressions. Well, but what is now the problem? See, C has two type of objects: lvalues and non-lvalues. lvalues are objects which may appear on the left size of an assignment. For example, a variable is an lvalue and a constant is not an lvalue, because 'x=5' is legal and '5=x' (or '5=3') is not legal. Not only variables are lvalues; for example, dereferenced pointers are also lvalues, so this is legal for example (store 100 at address 0x4c00):
*(char*)0x4c00 = 100;
So, '*(char*)0x4c00' is an lvalue. Now, about the problem. In GNU C, cast constructors are lvalues only if the initializer is completely constant. I.e. '(SCR_RECT){{10,10,50,50}}' is an lvalue, but '(SCR_RECT){{a,b,c,d}}' is not. As C language accepts unary '&' operator (i.e. "address of") only on lvalue objects, this means that, for example,
&(SCR_RECT){{10, 10, 50, 50}}
is legal, but
&(SCR_RECT){{a, b, c, d}}
is not! This is the real cause of the problem!!!

What you can do if you need an address of non-constant cast constructor? You need to declare an auxilary variable. For example, declare one SCR_RECT variable, say myScr,
SCR_RECT myScr;
and instead of
ScrRectFill (&(SCR_RECT){{a, b, c, d}}, ScrRect, A_XOR);
use:
myScr = (SCR_RECT){{a, b, c, d}};
ScrRectFill (&myScr, ScrRect, A_XOR);
Note that '&myScr' is legal, because 'myScr' is an lvalue (it is an ordinary variable). I hope that this helps a lot understanding of cast constructors and lvalues.


Can I use # (indirection) like in TI-Basic?
Previous The C Language Next

Q: | I wonder how I can simulate the indirection operator ('#') from TI-Basic in C programs...
A: | Nothing equivalent to indirection ('#') exists in any compiling language (like C), since the variable names do not appear in the compiled program. You need to make up your mind to avoid this operator. For indirect references to variables in C, you can use pointers. However, usually you can re-express the code using multiple if-else statements or arrays. Don't be afraid, C will process it 1000 times faster than TI-Basic processes indirections.


I need the C equivalent of the when() function from TI-Basic.
Previous The C Language Next

Q: I need the C equivalent of the 'when()' function from TI-Basic.
A: This is simple:
when (condition, true_val, false_val)
is translated to C as
condition ? true_val : false_val
For example,
sign = x >= 0 ? 1 : -1;
Happy?


I tried to use sizeof to get the size of an object, but it returned zero!
Previous The C Language Next

Q: When I tried to use the sizeof operator to determine the exact size of some objects, I got zero as the result. What is wrong?
A: You probably tried something like
printf ("%d", sizeof (something));
The ANSI standard proposes that the sizeof operator returns a value of type size_t, which is in fact long integer in this implementation. So, the result is pushed on the stack as a long integer, but the format specifier "%d" expects an ordinary integer, so it pulls from the stack just one word, which is zero in this case. You need to write
printf ("%ld", sizeof (something));
Alternatively, you can use a typecast to convert the result to a short integer
printf ("%d", (short) sizeof (something));
assuming that no object would be longer that 32767 bytes.


Can I use sizeof to determine the exact size of functions?
Previous The C Language

Q: Is it possible to determine the size of the function using the sizeof operator?
A: No. In "normal" programs you should never know this information. ANSI C even does not propose what is 'sizeof(function)', and such construction will be rejected by the most of C compilers. GNU C (like GCC4TI is) uses extended pointer arithmetic on such way that 'sizeof(function)' is always 1. If you are a dirty hacker (as I am), and if you really need to determine the number of bytes occupied by function, I used the following method:
void MyFunction(void)
{
  // The function body...
}
void End_Marker(void);
asm("End_Marker:");
...
...
num_of_bytes = (char*)End_Marker - (char*)MyFunction;
Note however that this method is not absolutely reliable, because it depends of the ordering of functions in the program. But, the compiler is free to change the order of functions if such reorganization may lead to a better code.


TI-Basic and C
Previous Frequently Asked Questions Next
  • RETURN_VALUE doesn't work on AMS 2.xx!
  • How can I display a PIC variable created in TI-Basic?
  • How can I execute TI-Basic programs or statements from C?
  • Can I write a program that returns a value to TI-Basic?
  • Why is 'a=GetIntArg (top_estack);' wrong?
  • How can I get a value from a TI-Basic matrix element?
  • How can I make my C function return itself?


RETURN_VALUE doesn't work on AMS 2.xx!
TI-Basic and C Next

Q: | I have problems with programs which return values to the TI-Basic using RETURN_VALUE directive!
A: | Yes, this is a problem with AMS 2.xx. For some strange reasons AMS 2.xx does not allow ASM programs to be part of expressions any more, i.e. if 'xyz' is an ASM program, 'xyz(3,2)+5' or 'xyz(3,2)->a' is not legal in AMS 2.xx. Fortunately, there is a solution. Read what I wrote about this problem in the section How to return values to the TI-Basic.


How can I display a PIC variable created in TI-Basic?
Previous TI-Basic and C Next

Q: Is it hard to display a PIC variable created from TI-Basic in C programs?
A: No, it is easy. It is enough to locate the variable (using SymFind for example), and to display its content using BitmapPut (its contents are just as expected by BitmapPut function). To be more concrete, look at the following function:
short show_picvar (SYM_STR SymName, short x, short y, short Attr)
{
  SYM_ENTRY *sym_entry = SymFindPtr (SymName, 0);
  if (!sym_entry) return FALSE;
  if (peek (HToESI (sym_entry->handle)) != PIC_TAG) return FALSE;
  BitmapPut (x, y, HeapDeref (sym_entry->handle) + 2, ScrRect, Attr);
  return TRUE;
}
The usage of this function is straightforward, for example:
show_picvar (SYMSTR ("testpic"), 30, 30, A_NORMAL);
assuming that "testpic" is the name of the wanted PIC variable. This function returns TRUE if the operation was successful, else returns FALSE (i.e. the picvar does not exist, or it is not a PIC variable).


How can I execute TI-Basic programs or statements from C?
Previous TI-Basic and C Next

Q: Is there any way to execute a file (i.e. another ASM or TI-Basic program) from a C program?
A: There are a lot of methods for doing this. The most obvious method to do this is usage of a function like this one:
void progrun(const char *name)
{
  char fname[25];
  HANDLE h;
  strcpy (fname, name);
  strcat (fname, "()");
  push_parse_text (fname);
  h = HS_popEStack ();
  TRY
    NG_execute (h, FALSE);
  FINALLY
    HeapFree (h);
  ENDFINAL
}
The usage of it is straightforward, for example:
progrun ("testprog");
Note that the program you call may throw errors. If you understand this function, you can easily expand it to accept arguments, etc. Principally, using NG_execute you can execute any particular sequence of TI-Basic statements.

See also: How can I create a program that is bigger than 24K and works on AMS 2.xx?


Can I write a program that returns a value to TI-Basic?
Previous TI-Basic and C Next

Q: Is it possible to write a program which will return a value to TI-Basic, i.e. which acts like functions in TI-Basic?

This is easy, was implemented a long time ago, and is described on the starting page of the documentation.


Why is 'a=GetIntArg (top_estack);' wrong?
Previous TI-Basic and C Next

Q: What is wrong in doing
a = GetIntArg (top_estack);
It seems that it works fine, but you always use an auxilary variable...
A: It works fine sometimes, but not always. See, GetIntArg is a function-looking macro, with changes the value of its actual argument. So, if you write
a = GetIntArg (top_estack);
you will also change the value of TIOS system variable top_estack, and I am not sure that you really want this. So, I strictly recommend using an auxilary variable, like in the following example:
ESI argptr = top_estack;
...
a = GetIntArg (argptr);
Using this method, you will avoid unexpected changes of top_estack.


How can I get a value from a TI-Basic matrix element?
Previous TI-Basic and C Next

Q: I have a matrix on the top of the expression stack which is produced as a result of calculation, and I don't know how do I put a matrix element located at [i,j] into result (values of 'i' and 'j' may vary)? I have read infos about estack.h, but I couldn't find the answer...
A: There is a lot of methods. I suggest the following one:
ESI ptr;
int result;
int i = 1;                             // Just an example
int j = 2;
push_parse_text ("[[11,12][21,22]]");  // An example matrix
ptr = locate_element (i,j);
result = GetIntArg (ptr);              // (assumed that elements are ints)
where 'locate_element' is an user-written function, which may be implemented as follows:
ESI locate_element (short m, short n)
{
  short i;
  ESI ptr = top_estack-1;
  for (i = 0; i < m-1; i++) ptr = next_expression_index (ptr);
  ptr--;
  for (i = 0; i < n-1; i++) ptr = next_expression_index (ptr);
  return ptr;
}
You can use it as-is, but it will be much better if you can understand how it works.


How can I make my C function return itself?
Previous TI-Basic and C

Q: Suppose I'm writing an ASM function 'foo(n)' which accepts an argument (a string, for example). I want to make 'foo(n)' return 'foo(n)' (the call itself) when 'n' is of type "VAR" (i.e. if nothing has been assigned to 'n' yet)...
A: This is quite easy, if you know in advance the name of the program. Suppose, that your program name is "example". Here is the demo (called "Function Returning Itself") which will return 'example(n)' if you type 'example(n)' if 'n' is a variable, and which will return the string "blabla" (for example) if the argument is something else:
// A function returning itself

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

#define RETURN_VALUE          // Return pushed expression
#define MIN_AMS 101           // Compile for AMS 1.01 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// Main Function
void _main(void)
{
  ESI argptr = top_estack;
  if (GetArgType (argptr) <= VAR_Q_TAG)  // it means that arg is a variable
                                         // see Tags to see why...
    push_expr_quantum (SYMSTR ("example"), USERFUNC_TAG);
  else
    {
      while (ESTACK (top_estack) != END_TAG)
        top_estack = next_expression_index (top_estack);
      top_estack--;
      push_string (SYMSTR ("blabla"));
    }
}
Note that this solution is not ideal: if you rename the program name to something else, the function will still return 'example(n)'. It is possible to determine the real name of the program in the run time, but this is very awkward.


Graphics and Display
Previous Frequently Asked Questions Next
  • How can I display a number variable on the screen (like an int)?
  • Do you plan on implementing 7-level grayscale?
  • How can I use sprites?
  • I don't understand how to define sprites!
  • How do you use sprite functions from sprites.h with grayscale?
  • How does BitmapGet work?
  • How can I create a virtual screen?
  • How can I set up a SCR_RECT structure?
  • How can I make a WINDOW structure?
  • How do I use functions from the wingraph.h file?
  • How do you use DrawIcon?
  • I need a really fast line-drawing routine...
  • I can't reset printf to start at the top of the screen!
  • How can you disable the 2nd and alpha indicators at the bottom of the screen?
  • When I disable interrupts, grayscale doesn't work!
  • While I was fiddling with interrupt handlers...


How can I display a number variable on the screen (like an int)?
Graphics and Display Next

Q: How can I convert an integer or a float to a string?
A: It's easy. Use sprintf. For example:
char string1[50];
char string2[50];
short int var1;
float var2;
...
sprintf (string1, "%d", var1);
sprintf (string2, "%f", var2);
That's why there is no need for functions like itoa and ftoa in opposite to atoi and atof.


Do you plan on implementing 7-level grayscale?
Previous Graphics and Display Next

Q: | Do you plan to implement 7-level grayscale mode?
A: | So far no, because nobody yet implemented 7-level grayscale which works stable on both HW1 and HW2 calculators. I don't want to implement features which works only on HW1 calculators.


How can I use sprites?
Previous Graphics and Display Next

Q: | Do you know how I can use sprites with GCC4TI ?
A: | Another common question. The answer depends on the size of the sprite. If your sprite is not wider than 32 pixels (which is likely), then you can now use the sprites.h header file. This header file defines fast functions which work with sprites (including masked sprites). The only limitation is that the sprite must not be wider than 32 pixels (the height is not limited). What to do if you want sprites wider than 32 pixels, and don't want to use kernel-based programming? The answer depends on what the usage of this sprite will be. If you don't need fast action, the built-in function BitmapPut may be good enough. If you need a very fast sprite routine, you may be better off using the ExtGraph library by the TI-Chess Team.


I don't understand how to define sprites!
Previous Graphics and Display Next

Q: I can't understand how sprites are defined; I looked in many program sources, and every sprite definition looks for me as an array of random hex numbers!?
A: Well, suppose that you want to make a sprite which is a filled circle. Make a grid on the paper, and make a sprite shape by filling grid squares. Then, replace each filled square with 1 and each blank square with 0. In above example, it may look like:

00111000
01111100
11111110
11111110
01111100
00111000

Then, produce rows as a set of binary numbers, and convert them to hex. For example:

00111000 binary = 38 hex
01111100 binary = 7C hex

etc. These hex numbers describe the sprite, i.e. the sprite definition should be
unsigned char sprite [] = {0x38, 0x7C, ...};
assuming that Sprite8 will be used. That's all...

Note: GCC4TI also supports binary numbers (0b...).


How do you use sprite functions from sprites.h with grayscale?
Previous Graphics and Display Next

Q: I would like to know if it is possible to use the sprite functions in sprites.h with grayscale. I have tried using the Sprite16 function with grayscale, and none of the sprites I intended to be in grayscale appeared. I tried to use DrawIcon and the grayscale worked just fine. But DrawIcon is too slow... Can Sprite16 and Sprite32 handle grayscale sprites.
A: Very common question in a recent time. See, you probably tried to use GraySetAMSPlane. Sprite16 have a parameter for drawing plane, so it is not sensitive to GraySetAMSPlane: you need to give the plane as an explicite parameter. In fact, you need to have two different sprite planes and to draw a sprite twice, passing two different planes as a parameter. For example,
static unsigned short light_definition [] = {...};
static unsigned short dark_definition [] = {...};
...
Sprite16 (x, y, height, light_definition, GrayGetPlane (LIGHT_PLANE), A_XOR);
Sprite16 (x, y, height, dark_definition, GrayGetPlane (DARK_PLANE), A_XOR);
In other words, sprite routines can handle grayscale sprites, but not natively, meaning you have to take your grayscale sprite, split it into two layers, and draw each one separately on its own plane - the routine does not handle these by itself. As suggested by Scott Noveck, it is possible to make a function of your own to handle this. Assume that your grayscale sprites follow the "standard" format seen in the most of ASM games, with the dark plane data followed immediately by the light plane data. This routine will call Sprite16 twice - once for each plane:
void GraySprite16 (short x, short y, short h, unsigned short *spr, short mode)
{
  Sprite16 (x, y, h, *spr, GetPlane (LIGHT_PLANE), mode);
  Sprite16 (x, y, h, *spr + h, GetPlane (DARK_PLANE), mode);
}
Don't be afraid about calling GrayGetPlane each time: it is not a waste of time. Its implementation is smart: when the input is a constant, it will simply evaluate to a memory address that contains the pointer; when it is variable, it expands to a simple macro.


How does BitmapGet work?
Previous Graphics and Display Next

Q: Can you give me info on how BitmapGet works. I've tried everything that I know and I still get protected memory errors. The manual just doesn`t give anything solid to base a few lines of code on.
A: You probably didn't allocate enough space to store a bitmap. The simplest way to do so is given in this example (called "Bitmap Test"):
// Retrieve and store a bitmap

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization

#define MIN_AMS 100           // Compile for AMS 1.00 or higher

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

// Main Function
void _main(void)
{
  SCR_RECT full_screen = {{0, 0, LCD_WIDTH - 1, LCD_HEIGHT - 1}};
  char buffer [BITMAP_HDR_SIZE + LCD_WIDTH*LCD_HEIGHT/8]; // or 2004 for a TI-89 and 3844 for a TI-92+/V200 if you like it more
  BitmapGet (&full_screen, buffer);          // store screen in buffer
  clrscr ();
  printf ("Press any key to\nrestore screen...");
  ngetchx ();
  BitmapPut (0, 0, buffer, &full_screen, A_REPLACE);
  ngetchx ();
}
Note that this is just an example: for saving/restoring the whole screen, the functions LCD_save and LCD_restore are much more efficient! Moreover, buffer will probably be allocated using malloc in a more realictic example.


How can I create a virtual screen?
Previous Graphics and Display Next

Q: How I can change the port for the screen memory to draw to it, and then copy it back to the regular address?
A: Do this:
void *virtual = malloc (LCD_SIZE);  // Allocate the buffer
...
if (!virtual) ... // do some error handling - not enough memory!
PortSet (virtual, 239, 127); // redirect drawing routines to buffer
or, even simpler, virtual screen may be simply in any local variable which is enough long:
char virtual[3840];
...
PortSet (virtual, 239, 127);
Note that, in this case, virtual memory will be in fact somewhere on the stack. There is nothing bad in this, but keep in mind that the total amount of the stack is 16K, so don't put TOO MANY data (like big arrays etc.) on the stack (i.e. in local variables). If you really need to handle a lot of data, use malloc instead.

After this, do any drawing you want - it will be redirected to the virtual screen. To copy this to the regular screen (i.e. to display it) do this:
memcpy (LCD_MEM, virtual, LCD_SIZE);
or even simpler (this is the same):
LCD_restore (buffer);
And, don't forget to do PortRestore before end of the program, else TIOS will be fooled after returning to TI-Basic!


How can I set up a SCR_RECT structure?
Previous Graphics and Display Next

Q: How I can setup properly a SCR_RECT structure? For example, the FillTriangle function requires the parameter of SCR_RECT type. How to put coordinates into it, so that I can change the clipping area for the screen?
A: If all coordinates of clip area are known in advance (for example 5, 5, 90, 70), do this:
FillTriangle (10, 10, 10, 50, 50, 50, &(SCR_RECT){{5, 5, 90, 70}}, A_NORMAL);
or, using "standard" C (i.e. without GNU extensions):

SCR_RECT area = {{5, 5, 90, 70}};  // somewhere in the declaration part
...
FillTriangle (10, 10, 10, 50, 50, 50, &area, A_NORMAL);
Note that double braces are necessary because SCR_RECT is an union.

If coordinates are not known in advance, for examples if they are in integer variables a, b, c and d, you can do this:
SCR_RECT area;
...
area.xy.x0 = a;
area.xy.y0 = b;
area.xy.x1 = c;
area.xy.y1 = d;
FillTriangle (10, 10, 10, 50, 50, 50, &area, A_NORMAL);
or, much simpler, using GNU C extensions:
FillTriangle (10, 10, 10, 50, 50, 50, &(SCR_RECT){{a, b, c, d}}, A_NORMAL);


How can I make a WINDOW structure?
Previous Graphics and Display Next

Q: | I would like to make my own window but I don't understand the lot of fields in the WINDOW structure, like 'TaskID' and others!
A: | You do not need to fill up the WINDOW structure manually: function WinOpen will fill everything automatically. See the next question for examples of usage.


How do I use functions from the wingraph.h file?
Previous Graphics and Display Next

Q: I need some examples of how to use the functions in the wingraph.h header file. Especially, I am confused with static and/or dynamic data allocation. I tried to use alloc.h to create necessary structures, but something was wrong...
A: I will give five very similar examples how to do the same thing. From the first and fifth example you will see that you need not to use alloc.h at all, and in the second, third and fourth example, you will see what you need to do if you want to use dynamic allocation (i.e. alloc.h) anyway. Maybe this is not so obvious from my documnetation, but flags in WinOpen must be ORed, so they must be "separated" by "|", not by commas.

Example 1: Using wingraph.h without dynamic allocation (called "Window 1"):
#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

// Main Function
void _main(void)
{
  WINDOW wind;
  WIN_RECT winr = {20, 20, 80, 50};
  WinOpen (&wind, &winr, WF_SAVE_SCR | WF_TTY);
  WinActivate (&wind);
  WinFont (&wind, F_6x8);
  WinStr (&wind, "hello everyone");
  ngetchx ();
  WinClose (&wind);
}
Example 2: Window is allocated dynamically (called "Window 2"):
#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

// Main Function
void _main(void)
{
  WINDOW *wind = HeapAllocPtr (sizeof (WINDOW));
  WIN_RECT winr = {20, 20, 80, 50};
  WinOpen (wind, &winr, WF_SAVE_SCR | WF_TTY);
  WinActivate (wind);
  WinFont (wind, F_6x8);
  WinStr (wind, "hello everyone");
  ngetchx ();
  WinClose (wind);
  HeapFreePtr(wind);
}
Note that synonyms for HeapAllocPtr and HeapFreePtr are malloc and free (like in ANSI C).

Example 3: Both "window" and "rect" are allocated dynamically (called "Window 3"):
#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

// Main Function
void _main(void)
{
  WINDOW *wind = HeapAllocPtr (sizeof (WINDOW));
  WIN_RECT *winr = HeapAllocPtr (sizeof (WIN_RECT));
  winr->x0 = 20; winr->y0 = 20;
  winr->x1 = 80; winr->y1 = 50;
  WinOpen (wind, winr, WF_SAVE_SCR | WF_TTY);
  WinActivate (wind);
  WinFont (wind, F_6x8);
  WinStr (wind, "hello everyone");
  ngetchx ();
  WinClose (wind);
  HeapFreePtr (wind);
  HeapFreePtr (winr);
}
Example 4: How to use MakeWinRect to avoid "winr" (called "Window 4"):
#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

// Main Function
void _main(void)
{
  WINDOW *wind = HeapAllocPtr (sizeof (WINDOW));
  WinOpen (wind, MakeWinRect (20, 20, 80, 50), WF_SAVE_SCR | WF_TTY);
  WinActivate (wind);
  WinFont (wind, F_6x8);
  WinStr (wind, "hello everyone");
  ngetchx ();
  WinClose (wind);
  HeapFreePtr (wind);
}
Example 5: This is what I do in my programs (called "Window 5"):
#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 100           // Compile for AMS 100 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// Main Function
void _main(void)
{
  WINDOW wind;
  WinOpen (&wind, &(WIN_RECT) {20, 20, 80, 50}, WF_SAVE_SCR | WF_TTY);
  WinActivate (&wind);
  WinFont(&wind, F_6x8);
  WinStr (&wind, "hello everyone");
  ngetchx ();
  WinClose (&wind);
}
Don't forget to close a window before exiting. If you forget to do so, the TI may crash later, when window manager tries to refresh a still active window which ceased to exist due to end of the program!

In general, I prefer static allocation instead of dynamic. It is good if you know in advance how many open windows you have in the program (this is often a case on TI). Dynamic allocation is the only method if you don't know in advance how many open windows you need (then, you can keep them in linked list). I don't think that there is a lot of use for this on the TI. :-)


How do you use DrawIcon?
Previous Graphics and Display Next

Q: I don't understand how to use DrawIcon. Do I need to use pICON?
A: If you want to draw an icon at 50,50 for example, do:
ICON i = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16};
...
DrawIcon (50, 50, &i, A_NORMAL);
Of course, change 1, 2, 3... to the real definition of the icon.

pICON is necessary only for using with icons which are dynamically allocated (forget it if you are not familiar with dynamic structures in C), like in:
pICON p = malloc (32);
...
// Here is a code which fill up the icon structure
...
DrawIcon (50, 50, p, A_REPLACE);
Look operator "&" in first example, it is omitted in second example. In fact, "&" converts a variable of ICON type to pICON type (in general, it converts any type to corresponding pointer type).


I need a really fast line-drawing routine...
Previous Graphics and Display Next

Q: I want to make a program which draw a lot of lines (for example which does some kind of 3D graphic). But, it seems that DrawLine function is not too fast for my purposes. What I can do?
A: Yes, TIOS drawing routines are not championes in speed. Note that really fast line drawing function may be written only in ASM. But don't underestimate the power of C: even in pure C it is possible to make better (read: faster) line drawing routine than TIOS routine. As a programming exercise, I started with one trivial line drawing routine, and tried to optimize it. What I got is the routine which is in general 3-4 times faster than TIOS DrawLine routine. In some special cases, TIOS routine may be faster (for example, TIOS routine handles special cases when the line is horizontal or vertical), but in general case (slope lines) my routine is much better. Maybe (and probably) it may be speed-optimized yet; this is a challenge for you. Here is the routine (example "Draw Line"):
// Example of a fast line-drawing routine

#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

// Draws a line from (x1,y2) to (x2,y2).
void DrawLineFast(short x1, short y1, short x2, short y2)
{
  short x = x1, y = y1;
  short dx = abs (x2 - x1), dy = abs (y2 - y1);
  short ystep = (y1 < y2) ? 1 : -1, pystep = 30 * ystep;
  short mov = dx ? 0 : -1;
  unsigned char *ptr = (char*)LCD_MEM + 30 * y + (x >> 3);
  short mask = 1 << (~x & 7);
  if (x1 < x2)
    while (x != x2 || y != y2)
      {
        *ptr |= mask;
        if (mov < 0) y += ystep, ptr += pystep, mov += dx;
        else
          {
            mov -= dy;
            if (++x & 7) mask >>= 1;
            else ptr++, mask = 0x80;
          }
      }
  else
    while (x != x2 || y != y2)
      {
        *ptr |= mask;
        if (mov < 0) y += ystep, ptr += pystep, mov += dx;
        else
          {
            mov -= dy;
            if (x-- & 7) mask <<= 1;
            else ptr--, mask = 1;
          }
      }
}

// Main Function
void _main(void)
{
  DrawLineFast (10, 10, 60, 70);
  ngetchx ();
}
If you need a line erasing or line inverting routine, replace '*ptr |= mask' with '*ptr &= ~mask' or '*ptr ^= mask' respectively.


I can't reset printf to start at the top of the screen!
Previous Graphics and Display Next

Q: | When I'm using printf function, I'm not abble to reset the scrolling: after using this function, and after clearing the screen, the text is still displayed at the bottom of the screen, even if the calculator was turned off between two use of the program... How can I reset the scrolling?
A: | As I know, I warned in the documentation that ClrScr and clrscr are not the same: the second one resets the print position too, so you need to use it. Anyway, you can always use MoveTo to reset print position to (0,0) which effective resets the scrolling.


How can you disable the 2nd and alpha indicators at the bottom of the screen?
Previous Graphics and Display Next

Q: | How do you make that the status line is not visible on the screen so that the status indicators do not mess up your graphics?
A: | The most general method (I use this) is: disable auto-int 1 using OSSetSR function (status line indicators are updated from this interrupt). Note that in this case you need to read the keyboard using the _rowread function, because ngetchx etc. are based on auto-int 1. I used this method in my program cblaster (you can pick it from ticalc). Anyway, if you use _rowread, you should also disable auto-int 5 as well.


When I disable interrupts, grayscale doesn't work!
Previous Graphics and Display Next

Q: I'm writing a game in C, but I encountered the following problem: when I disable interrupts, the grayscale doesn't work...
A: Of course, because grayscale is based on interrupts. I.e. you must not disable them in grayscale programs. So, what to do? You probably want to disable auto-int 1 to avoid screwing up the status line. Instead of DISABLING auto-int 1, you may REDIRECT it to nothing. New header file intr.h provides very elegant methods for doing this. It is enough to do this:
INT_HANDLER save_int_1;
...
save_int_1 = GetIntVec (AUTO_INT_1);
SetIntVec (AUTO_INT_1, DUMMY_HANDLER);   // redirect auto-int 1 to "nothing"
// enable grayscale
// do your code
// disable grayscale
SetIntVec (AUTO_INT_1, save_int_1);


While I was fiddling with interrupt handlers...
Previous Graphics and Display

Q: I'm just fiddling around with interrupt handlers and don't understand why the following code won't work:
void myInterruptHandler(void)
{
  asm ("movem.l %d0-%d7/%a0-%a6,-(%sp)");
  // do something here...
  asm ("movem.l (%sp)+,%d0-%d7/%a0-%a6; rte");
}

A: There are two reasons for this. First, the sequence "do something here" surely uses some local variables. The compiler will put them in registers during the optimization, and it will generate code for saving them on the stack at the beginning of the procedure, before the execution of any statements in the function body. So, before executing
asm("movem.l %d0-%d7/%a0-%a6,-(%sp)");
something will be pushed on the stack. Read this as "open brace '{' is not only the marker, it also generates an entry procedure code". So, when "rte" is encountered, the return address on the stack is trashed. Second, even if the procedure does not use any local vars, the entry code for the procedure is usually
link #something,%a6
and the stack is again not suitable for executing "rte". Before release 2.2 of TIGCCLIB, the only universal and correct method for defining interrupt handlers was is to define a pure assembly auxilary procedure as follows:
void InterruptHandler(void);  // Just a prototype
asm ("myInterruptHandler:
      move.w #0x2700,%sr
      movem.l %d0-%d7/%a0-%a6,-(%sp)
      jbsr MainHandler
      movem.l (%sp)+,%d0-%d7/%a0-%a6
      rte");

void MainHandler(void)
{
  // Put everything you want here...
}
To make life easier, starting from release 2.2, I introduced a new language extension called DEFINE_INT_HANDLER in the intr.h header file. Now, it is enough to write
DEFINE_INT_HANDLER (myInterruptHandler)
{
  // Put everything you want here...
}


Assembly and C
Previous Frequently Asked Questions Next
  • How can I use a kernel-based libraries in C?
  • How can I communicate between ASM and C code?


How can I use a kernel-based libraries in C?
Assembly and C Next

Q: Is there any method to use a kernel-based library with GCC4TI (such as ZipLib) and how to call a routine that uses something other than the stack in the routine for arguments passing?
A: Good and common question. When an assembly routine uses register passing, the solution is not so obvious. I will give a concrete example. Look at ZipLib, function compress. Quoting from the PreOS documentation:
; compress ()
; Function: compress data
; Input: A0   = Pointer to uncompressed data
;        A1   = Pointer to where the compressed data
;               should be stored
;        D0.W = Length of datas which will be compressed
; ziplib::compress equ ziplib@0004
So, how to interface this with GCC4TI? There is a lot of solutions. One solution is to use an interface function which accepts parameters via stack then to use embeded assembler to call library function:
void compress (void *src, void *dest, unsigned short len)
{
  asm ("move.l (%a6,8),%a0
        move.l (%a6,12),%a1
        move.w (%a6,16),%d0
        jsr ziplib__0004");
}
This works, but maybe it is awkward to know where the parameters are stored on the stack. GNU C has some extensions for interfacing with assembler, so the following solution is more elegant:
void compress (void *src, void *dest, unsigned short len)
{
  asm ("move.l %0,%%a0" :: "g"(src));
  asm ("move.l %0,%%a1" :: "g"(dest));
  asm ("move.w %0,%%d0" :: "g"(len));
  asm ("jsr ziplib__0004");
}
If you don't understand this (which is probably the case if you are not familiar with GNU C extensions), accept this as as-is template.

Both solutions have two bad points: first, usage of stack is awkward if you want very fast calling. Second, this interface function will always be inserted in the code (even if not called in the program), so it is not suitable for making universal header files. As GNU C allows interfacing arbitrary C expressions with assembler, and allows building smart safe macros using so-called "statement expressions", the following solution avoids both the stack and "embedding" problem:
#define compress(src, dest, len) \
  ({ asm ("move.l %0,%%a0" :: "g"(src)); \
     asm ("move.l %0,%%a1" :: "g"(dest)); \
     asm ("move.w %0,%%d0" :: "g"(len)); \
     asm ("jsr ziplib__0004"); })
In any case, you can call function (or macro) "compress" using, for example,
compress (LCD_MEM, buffer, LCD_SIZE);
etc.

The third solution has one drawback: the impossibility of compile-time checking of parameters type. This can be solved using the following construction (don't be afraid by introducing extra variables; the compiler will remove them during the optimization, and it will produce the same code as in previous example, but with type-checking):
#define compress(src, dest, len) \
  ({ void *__src = (src), *__dest = (dest); \
     unsigned long __len = (len); \
     asm ("move.l %0,%%a0" :: "g"(__src)); \
     asm ("move.l %0,%%a1" :: "g"(__dest)); \
     asm ("move.w %0,%%d0" :: "g"(__len)); \
     asm ("jsr ziplib__0004"); })
There is also fifth, nearly "ideal" solution, using GNU cast constructors which constructs a function during the compilation (look how functions in stdio.h are implemented, etc.). But, I will not present this here, because you will not understand anything if you are not familiar with cast constructors.

Note: TIGCC v0.94 and later (which GCC4TI is) support explicit register specification.


How can I communicate between ASM and C code?
Previous Assembly and C

Q: | Maybe I am quite stupid, but I cannot catch anything about communicating information between the C code and the assembly code... I'm not really familiar with mixing high-level languages with assembly language; all I really know is that the asm keyword allows one to include assembly instructions in C source code. But how would would you write an assembly function that C code could utilize?
A: | This is explained in detail, see section about Extended Asm.


Strings
Previous Frequently Asked Questions Next
  • How do you use strcat properly?
  • How can I write an efficient number to string routine?
  • Why can't I use a backslash (e.g. "main\var") in my strings?


How do you use strcat properly?
Strings Next

Q: Whenever I used strcat in my program, it crashes!?
A: See, you probably want to ask what is wrong in the following code:
printf (strcat ("Hello ", "World!"));
strcat appends the second argument to the first argument and returns the augmented first argument, but it does not allocate any extra space for doing this task. So, if you do
strcat ("Hello ", "World!");
string "World!" will be copied over bytes which follows immidiately after bytes "Hello " in the memory (whatever is there), which will nearly surely cause a crash (because there is probably a part of code or other data there). So, strcat may be used only when the first argument is enough long buffer, like in:
char buffer[50];
strcpy (buffer, "Hello ");
strcat (buffer, "World!");
In other words, C language does not support dynamic string manipulations which is present in some other languages like Basic, Turbo Pascal, etc.


How can I write an efficient number to string routine?
Previous Strings Next

Q: I am just curious how I can write my own and efficient IntToStr routine...
A: Process the number starting from the end (i.e. from the least significant digit instead from the most significant digit), like in the following example, which is probably the most optimal code:
char *IntToStr (unsigned long an_integer)
{
  static char result [] = "          \0";    // 10 spaces and \0
  char *ptr = result + 10;
  while (an_integer)
    {
      *ptr-- = an_integer % 10 + '0';
      an_integer/=10;
    }
  return ptr;
}
Note that 'static' before char in the first line is essential: without it, the variable 'result' will be allocated of the stack, so it will not live too long after this function returns. Returning any pointers which points to structures allocated on the stack is extremely dangerous (it is not only dangerous; it is almost completely nonsense, except if you performs some really nasty and bizzare hacks). The another solution (but less elegant) is to make 'result' global (i.e. to define it out of the function).


Why can't I use a backslash (e.g. "main\var") in my strings?
Previous Strings

Q: | When I type "main\var", the compiler gives me an error. Help!
A: | This is a common problem among beginning programmers. The backslash (\) is used as an escape character in the C language. Because of this, you need to modify your string to read like this: "main\\var". Now, compiler will interpret the \\ as a single backslash, which is what you want. If you want to lean more about escape sequences, look at the information on strings.


Event-driven Programming, Menus, and Throwing Errors
Previous Frequently Asked Questions Next
  • If my program throws an error, I can't start it again!
  • Can dialogs have popup menus with submenus?
  • Why does calling the previous event handler in a user event handler result in a crash?
  • How can I use functions in textedit.h to edit a text variable?
  • I tried to create a new window for the text editor, but it didn't work...
  • Can you change the font in the text editor?
  • Why isn't it possible to create menus with more than one level of submenu with PopupAddText, and how can I do it anyway?
  • How can I use VTI to pick bytes from menu structures like you describe?


If my program throws an error, I can't start it again!
Event-driven Programming, Menus, and Throwing Errors Next

Q: | If my program stops execution by throwing an error, I cannot execute it again without retransmitting it from the computer or another calculator. Namely, when I try to execute it again, the calculator reports "Invalid program reference". Why, and what I can do to prevent such behaviour?
A: | See Returning Errors.


Can dialogs have popup menus with submenus?
Previous Event-driven Programming, Menus, and Throwing Errors Next

Q: | The popup menu given in the example for menus.h seems to work fine on its own, but not when used in a dialog: if you select anything after "Option 2" the text in the selector is the wrong one. Can't dialog popups handle sub-menus?
A: | I am afraid that popups in dialogs can't have sub-menus. I think so because I never see on TI-89 any system dialog which has such popups. Yes, it sucks, but this is not my guilt...


Why does calling the previous event handler in a user event handler result in a crash?
Previous Event-driven Programming, Menus, and Throwing Errors Next

Q: What is wrong in calling the previous installed event handler in a new one? Whenever I tried to do so, my only result is a crash...
A: Very probably you do
OldHandler = EV_captureEvents (NewHandler);
then you call OldHandler from NewHandler. There would be nothing wrong in doing so, but function EV_captureEvents returns NULL when there is no any user handlers previously installed, which is very common case. So, you can call OldHandler only if it is not null. In other words, it is illegal to call an event handler when it is not actually installed. From the other side, function EV_defaultHandler calls the TIOS handler which is used for default dispatching of some common events. It works independently of which handler is currently installed and whether it is installed at all. This is a function which you probably need to call in your event handler to process all unprocessed events.


How can I use functions in textedit.h to edit a text variable?
Previous Event-driven Programming, Menus, and Throwing Errors Next

Q: I don't understand how I can use functions from textedit.h header file to edit a text variable. When I tried to open a blank editor everything seems OK, but when I tried to edit an existing text variable, I got a crash...
A: I must admit that the problem is not so easy. The problem is, in fact, caused by severe error in my documentation in releases of TIGCCLIB prior to 2.2 (it is corrected now). Namely, I was wrong when I told that a handle passed as a parameter to TE_open function may be a handle of a text variable. In fact, text variables have another extra data at the begining (one word for the length, and one word for the cursor position). But, the editor expects a raw data. I inspected what TIOS does exactly during opening a text variable. Then I concluded: there is no any other solutions than striping out extra data (this is a little play with memmove). Of course, after the editing is finished, it is necessary to reconstruct again the proper structure of the text variable (this is possible using some informations presented in TEXT_EDIT structure after the editing is finished).

After this theoretical elaboration, I will be much more concrete. Here is a complete code example (called "Text Editor") which edits the text variable named "mytext". Due to simplicity, it is assumed that this variable really exists and that it is not archived:
// A simple text editor example

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

TEXT_EDIT te;

// Typical event handler for text editing
CALLBACK void EventHandler(EVENT *ev)
{
  if (ev->Type == CM_KEYPRESS && ev->extra.Key.Code == KEY_ESC)
    ER_throw (1);
  if (!TE_handleEvent (&te, ev))
    EV_defaultHandler (ev);
}

// Main Function
void _main(void)
{
  char *base_addr;
  SYM_ENTRY *sym = SymFindPtr (SYMSTR ("mytext"), 0);

  if (!sym) return;  // Exit if file not found...

  // First, you need to remove the garbage data at the begining of
  // the text variable, because the text editor expects raw data:

  base_addr = HeapDeref (sym->handle);
  memmove (base_addr, base_addr + 4, peek_w(base_addr));

  // Now, do the editing. This is straightforward...

  WinClr (DeskTop);
  TE_open (&te, DeskTop, MakeWinRect (0, 16, 159, 92), sym->handle, 1, 0, 7);
  CU_start ();
  EV_captureEvents (EventHandler);
  TRY
     EV_eventLoop ();
  ONERR
     EV_captureEvents (NULL);
  ENDTRY

  // Finally, you must transform raw editor data into the proper
  // format of the text variable. This is not so straightforward:

  base_addr = HeapDeref (HeapRealloc (sym->handle, te.CurSize + 10));
  memmove (base_addr + 4, base_addr, te.CurSize);
  poke_w (base_addr, te.CurSize + 4);
  poke_w (base_addr + 2, te.CursorOffset);
  poke (base_addr + te.CurSize + 4, 0);
  poke (base_addr + te.CurSize + 5, TEXT_TAG);
}
It is important to understand how this program works if you plan to do any serious application of text editing functions.


I tried to create a new window for the text editor, but it didn't work...
Previous Event-driven Programming, Menus, and Throwing Errors Next

Q: When I tried to create my own window to be used as a parent window for the text editor (instead of the DeskTop window), and when I passed the address of my window to TE_open, the editor went blank (it did not display the file contents on the screen, although the editing seemed to work). What is wrong?
A: I was also very surprised when I noticed this. After some investigations, I concluded that the window passed to TE_open must not be "dirty" (i.e. it must not have WF_DIRTY flag set), but windows created by WinOpen are "dirty" by default. So, you need to clear "dirty" flag manually before calling TE_open. This is straightforward. For example,
WIN_RECT myRect = {0, 16, 159, 92};
WINDOW myWin;
TEXT_EDIT te;
...
WinOpen (&myWin, &myRect, WF_NOBORDER);
myWin.Flags &= ~WF_DIRTY;
TE_open (&te, &myWin, &myRect, ...);
Anyway, there is no strong reasons to use any windows other than DeskTop as a parent window, except if you want to use the whole screen for the editing area (the desktop window is clipped in the toolbar area). But, note that using whole screen for editing is not so good idea. The editor expects that the menu is on the top. So, if you press F1 etc. while doing "full-screen" editing, your screen will be trashed, because the editor will open the menu, and it will expect that the toolbar is at the top, etc. etc. Try to see. The solution? Disable all keys like F1, etc. in the event handler (e.g. do not pass them to TE_handleEvent) if you really want to do full screen editing...


Can you change the font in the text editor?
Previous Event-driven Programming, Menus, and Throwing Errors Next

Q: Is it possible to use any other font except 6x8 font in the text editor?
A: Principally, you can change font using WinFont before calling TE_open. For example, you can do
WinFont (DeskTop, F_8x10);
However, the editor will work fine with both 6x8 and 8x10 fonts, but not with 4x6 font (try and see), because it is proportional, so the editor will be fooled (editors usually expects fixed-size fonts). This is a pity.


Why isn't it possible to create menus with more than one level of submenu with PopupAddText, and how can I do it anyway?
Previous Event-driven Programming, Menus, and Throwing Errors Next

Q: | The documentation about menus.h says (cite): "Although TIOS menu system allows menus with more than one level of submenus, it is not possible to create such menus using this command (PopupAddText)". What happens then? And how it is possible to make menus with more levels of submenus?
A: | The answer of the first part of the question is: just nothing. Options which are added on deeper levels are just ignored. When I dissassembled this routine, I found that this is really not implemented! About the second part of the question: this is answered in the documentation about menus.h header file.


How can I use VTI to pick bytes from menu structures like you describe?
Previous Event-driven Programming, Menus, and Throwing Errors

Q: The documentation about MenuPopup says that it is possible to make popup menus by picking up bytes with the VTI debugger to save the memory, but I don't know how to do this. Could you tell me how to do this, please?
A: Not so easy to explain if you are not an experienced user. Basically, after you define a menu using PopupNew, PopupAddText etc., you need to display its address instead of executing it. E.g. instead of doing
PopupDo (handle, ...)
you need to do something like:
printf_xy (0, 50, "Address=%lp", HeapDeref (handle));
ngetchx();
Then, while waiting for a keypress, open the VTI debugger and go to the displayed address. Take a pencil and write a sequence of bytes starting from this address. Tenth and eleventh byte in this sequence will tell to you how many bytes you need to pick. After this, put these bytes in the array, and pass such array as an argument to the MenuPopup function. As an exercise, try this on an example given in the documentation.


TI Variables and the Variable Allocation Table (VAT)
Previous Frequently Asked Questions Next
  • How can I get a list of all the variables/folders on the calculator?
  • How can I determine the type and size of a variable?
  • How can I copy a variable from one folder to another?
  • How can I create a List or Matrix variable to keep highscores or similar information?
  • Can I create a variable with a custom type (like HSC for highscores)?
  • I want to create a variable without using functions from stdio.h.
  • When I use functions from vat.h, the calculator crashes!


How can I get a list of all the variables/folders on the calculator?
TI Variables and the Variable Allocation Table (VAT) Next

Q: | Does any function exists to find out how many folders are on the calculator and what files are in them? In other words, is there a way to get an array of all the folders on the calculator or an array of all the files in a folder?
A: | This was very frequent question, but you can find the answer by reading carefully info about SymFindFirst and SymFindNext. And, look the example about returning values to TI-Basic given on the main page of this documentation. Mail me if still not clear...


How can I determine the type and size of a variable?
Previous TI Variables and the Variable Allocation Table (VAT) Next

Q: How I can determine the size of a symbol (i.e. TI-Basic variable) and the TIOS type of the variable?
A: Assume that you found a VAT symbol entry for a symbol (say symbol named "foo") which may be done for example using SymFindPtr:
SYM_ENTRY *sym;
...
sym = SymFindPtr (SYMSTR ("foo"), 0);
Then, do the following to find the size and type:
unsigned short size;
ESQ type;
...
size = ((MULTI_EXPR*) HeapDeref (sym->handle))->Size + 2;
type = *(HToESI (sym->handle));
After this, the variables 'size' and 'type' will contain exactly what do you want.


How can I copy a variable from one folder to another?
Previous TI Variables and the Variable Allocation Table (VAT) Next

Q: | I don't understand how to copy a symbol (TI-Basic variable) from one folder to another. As I can see, SymCpy doesn't copy the entire symbol, just the name!?
A: | Moving symbols is quite easy (using SymMove), but copying is not so straightforward. Principally, you need to create a new one, and to copy the content of the original one into a new one. Fortunately, it is possible to use cmd_copyvar from bascmd.h. As it is TI-Basic call, it is highly recommended to execute it under a TRY...ONERR...ENDTRY block.


How can I create a List or Matrix variable to keep highscores or similar information?
Previous TI Variables and the Variable Allocation Table (VAT) Next

Q: | Is there a way to use TI89's Lists or Matrix, so I will be able to keep information like high score or something else...
A: | Yes, more info about this can be found in this release of GCC4TILIB documentation (note that a matrix is a "list of lists"). However, using lists or matrices is somewhat complicated. It is much easier to keep information in a user-defined format. See the next question. A stdio.h header file is implemented, which supports ANSI C compatible file handling, so creating files is quite simplified. If you want to bypass stdio.h and use low-level TIOS routines (such an approach leads to smaller programs), see SymAdd.


Can I create a variable with a custom type (like HSC for highscores)?
Previous TI Variables and the Variable Allocation Table (VAT) Next

Q: Is it possible to create a file which will have a custom type (i.e. which does not appear in VAR-LINK as a stanard type like STR, PIC, PRGM etc.). For example, I want to create a highscore file which will appear in VAR-LINK as HSC type...
A: Christian Walther pointed to me that this is possible. Moreover, this is easy. All you need to do is to create a file of "other" type (i.e. which terminates with OTH_TAG). TIOS then expects that a real type name is stored just below OTH_TAG as a zero-started zero-terminated string of maximum 4 chars. Look the following code fragment as an example:
FILE *fp = fopen ("example", "wb");
// store anything you want in the file here
fputc (0, fp);
fputs ("HSC", fp);
fputc (0, fp);
fputc (OTH_TAG, fp);
fclose (fp);
After this, you will have a file named "example" with type "HSC": you will see it in the VAR-LINK dialog.


I want to create a variable without using functions from stdio.h.
Previous TI Variables and the Variable Allocation Table (VAT) Next

Q: I want to avoid standard ANSI C functions for file handling like fopen etc. and to use low-level functions from vat.h (to make my program shorter), but I am not very sure what I need exactly to do to create a new file, and how I can manipulate with it.
A: Basically, to create a file you need to do the following:
  1. Create a new VAT symbol using SymAdd;
  2. Allocate a space for the variable using HeapAlloc;
  3. Dereference the symbol to get a pointer to the VAT entry, then store the handle returned by HeapAlloc to it;
  4. Put the actual file length in first two bytes of allocated space.
To be more concrete, I will show here a simple demo program (called "Create Variable") which creates a string file (I use this internally), but it is easy to adapt to any file type:
// Create a variable using functions from vat.h

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

HANDLE CreateFile (const char *FileName)
// Returns a handle, H_NULL in case of error
{
  HANDLE h;
  SYM_ENTRY *sym_entry;
  char str[30], *sptr = str;
  *sptr = 0; while ((*++sptr = *FileName++));
  if (!(h = HeapAlloc (HeapMax ()))) return H_NULL;
  if (!(sym_entry = DerefSym (SymAdd (sptr))))
    {
      HeapFree (h);
      return H_NULL;
    }
  *(long*) HeapDeref (sym_entry->handle = h) = 0x00010000;
  return h;
}

void AppendCharToFile (HANDLE h, unsigned char c)
{
  char *base = HeapDeref(h);
  unsigned short len = *(unsigned short*)base;
  if (len > HeapSize(h) - 10) return;
  *(unsigned short*)base = len + 1;
  base[len+2] = c;
}

void AppendBlockToFile (HANDLE h, void *addr, unsigned short len)
{
  unsigned short i;
  for (i = len; i; i--) AppendCharToFile (h, *((char*)addr)++);
}

void CloseFile (HANDLE h)
{
  AppendCharToFile (h,0); AppendCharToFile (h,0x2D);
  HeapUnlock (h);
  HeapRealloc (h, *(unsigned short*)HeapDeref(h) + 3);
}

void _main(void)
{
  static char s[] = "Hello world!";
  HANDLE h;
  h = CreateFile ("example");
  AppendBlockToFile (h, s, 12);
  CloseFile (h);
}
Note that the used method is not the best: it initially allocates as much space as avaliable, then reallocates the space to the necessary size on closing, but it is worth to look at it. Note also that the CreateFile function may be even simpler if you want to use it like CreateFile(SYMSTR("example")) instead of CreateFile("example"), i.e. if you avoid the use of ANSI strings.


When I use functions from vat.h, the calculator crashes!
Previous TI Variables and the Variable Allocation Table (VAT)

Q: When I tried to use EM_moveSymToExtMem to archive a file, the calculator crashed!
A: You probably wrote something like
EM_moveSymToExtMem ("example", HS_NULL);
Instead, you need to write
EM_moveSymToExtMem (SYMSTR ("example"), HS_NULL);
This routine except SYM_STR type strings, not ordinary C strings. See SYMSTR from the vat.h header file for more info.


Memory, C Variables, and Pointers
Previous Frequently Asked Questions Next
  • I have trouble allocating memory, my program crashes on the second run.
  • I can't understand C matrices!
  • How do I store variables so they retain their values, like for highscores?
  • Global variables retain value?
  • How can you control where data is stored in memory and access it?
  • What is so horrible about global variables?
  • How can you store a number such as 0x4c00 in a pointer?
  • Is it possible to add one or two bytes to a longword pointer?
  • Why can't you assign values to dereferenced void pointers?
  • How can I have large global variables that don't take up space in my program file?
  • How can I create a dynamic two-dimensional array?
  • How can I create variable-size arrays?
  • Why do I get "Value computed is not used" when working with pointers?


I have trouble allocating memory, my program crashes on the second run.
Memory, C Variables, and Pointers Next

Q: I have problems with allocating memory. When I run my program the first time, it works just as expected, but the second (or sometimes the third) time I run it, it hangs. Typical memory allocation problem. But I just can't understand what the problem is.
A: The problem is very probably not related to the dynamic memory allocation, but to the usage of static variables. At the moment, all static vars need to be initialized, even to nothing. I.e, you need to use
static int a = 0, b = 0;
static char *ptr = NULL;
instead of
static int a, b;
static char *ptr;
I expect that this will solve your problems.


I can't understand C matrices!
Previous Memory, C Variables, and Pointers Next

Q: I can't understand matrices in C (not TI-Basic matrices, but matrices which are the part of the C language)!
A: Basically, to declare a matrix, you need to use:
type name[dimension1][dimension2];
for example:
int a[5][5];
And, to access element of the matrix, you need to use:
name[index1][index2];
for example:
a[2][3] = 10;
or
x = a[1][2];
But note that indices are not from 1 to dimension, but from 0 to dimension-1. So, in the above example, both indices are in range 0 to 4, not 1 to 5. For example to fill all matrix by zeroes, you can use this code:
int a[5][5], i, j;     // A 5x5 array of ints, and two single ints

for(i = 0; i < 5; i++)
  for (j = 0; j < 5; j++)
    a[i][j] = 0;
although the experienced C programmer will simply use
memset (a, 0, 5 * 5 * sizeof(int));
to make it faster.


How do I store variables so they retain their values, like for highscores?
Previous Memory, C Variables, and Pointers Next

Q: How do you store preferences, high scores, and suchlike so that they do not go away when you exit the program? I have absolutely no clue how to do this.
A: The simplest method is: if you stored preferences in an array, declare this array as "static". For example,
static int high_scores[10] = {};
In this case, such array will be kept in the program file itself (instead on the stack), so it will not go away after you exit the program. This method has only one drawback: preferences will not be kept if the program is archived.

Be aware of the initializer: static variables must be initialized in the "nostub" mode. An empty initializer in this example is equivalent to the
static int high_scores[10] = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0};
Don't be confused which such initialization. It seems that the array elements will be set back to 0 any time when you run the program. But, this is not true. The initialization of automatic and static variables is quite different. Automatic (local) variables are initialized during the run-time, so the initialization will be executed whenever it is encountered in the program. Static (and global) variables are initialized during the compile-time, so the initial values will simply be embeded in the executable file itself. If you change them, they will retain changed in the file.


Global variables retain value?
Previous Memory, C Variables, and Pointers Next

Q: If I understand correctly, if I have the following global variable in my program
int a = 10;
and if I change its value somewhere in the program to 20 (for example), its initial value will be 20 (not 10) when I run the program next time???
A: Exactly! Note that this is true only for global and static variables. To force reinitializing, you must put explicitely something like
a = 10;
at the begining of the main program!

Note, however, that if the program is archived, the initial values will be restored each time you run the program, because archived programs are reloaded from the archive memory to the RAM on each start, similarly to the programs are reloaded from disks on "standard" computers (PC, etc.) each time when you start them. The same is true for compressed programs (for obvious reasons) and if you use a data variable and have GCC4TI create a copy every time it is used.

See also: How do I store variables so they retain their values


How can you control where data is stored in memory and access it?
Previous Memory, C Variables, and Pointers Next

Q: | How can you control where a program data is stored in the calculator's memory, and then how to access the data? By looking at your programs (cblaster etc.), you simply use memcpy to write to the array, which seems so easy! Is the array kept in memory because it's declared as static?
A: | Yes. Every static and global data (i.e. data which are declared out of functions) are kept in the .89z/.9xz file itself (more precise, in the area of the memory allocated to .89z/.9xz file), so they will survive after the end of the program. Local data are stored on the stack (so they will be deleted after the end of the function in which they are declared).


What is so horrible about global variables?
Previous Memory, C Variables, and Pointers Next

Q: You quote very often in the documentation that we need to avoid global variables as much as possible. What is so wrong with them?
A: Of course, globals are sometimes very necessary, but they are also easy to overuse. The good programming practice is to keep the scope of each identifier as small as possible. But, in addition to conventional programming theory, there are some extra reasons against globals which are related particularly to programming on TI calculators. First, every global variable is translated to the absolute addressing mode. As this mode is non-relocatable, the compiler adds a 4-byte long entry into the relocation table for each apperance of the global variable. If global variable "a" is mentioned say 100 times in the program, this is extra 400 bytes. When I ported some programs from PC to TI, I suceeded to reduce program space from 20K to 16K just by eliminating globals. And 4K of space is quite worth on TI... Second, globals are kept in the .89z (or .9xz) file itself. Sometimes it is good (to keep permanent data which will survive after the program exits etc.), but very often it is a wasting of file space (as the file length is limited). Read questions given further in this document to see how to reduce a file size if you have a strong reasons for using global arrays. To learn: avoid extensive usage of globals as much as possible!


How can you store a number such as 0x4c00 in a pointer?
Previous Memory, C Variables, and Pointers Next

Q: According to what I have read, you cannot store an immediate value (or any non-pointer variable) to a pointer variable. You can only copy pointers of the same type and such. Now, the books may say this, but, is there a way to do this somehow? I want something like 'address=0x001fca;' where address is a pointer to a char. Is it necessary to use the assembler for this?
A: No. C is enough low-level language that nearly everything which can be done in ASM can be done in pure C too (of course, pure ASM code is usually faster). In your concrete example, using of typecasting is quite enough:
address = (char*)0x001fca;
This is really a classic usage of the typecast operator. It is extremely powerful in C language, so it may be used to convert nearly everything to anything. This sometimes may be really terrible. For example, in early TIGCCLIB implementation, I used strange typecasting to convert an array to a function. And, nearly all library functions are implemented using a typecast operator which constructs an indirect function call. For example, when you use something innocent like
DrawStr (0, 0, "Hello", A_NORMAL);
the preprocessor expands it into a really terrible typecast. See _rom_call for more info.


Is it possible to add one or two bytes to a longword pointer?
Previous Memory, C Variables, and Pointers Next

Q: Is it possible to add two bytes or even one byte to a longword pointer? I am using a longword pointer to write longwords to the screen, and I need to add 30 bytes to it to get to the next line. However, I can only add multiples of four bytes to it...
A: It is possible using typecasting:
ptr = (long*)((char*)ptr + 30);
Don't be afraid, the compiler will generate just addition: everything other is just to satisfy type checking conventions. Or alternatively, you can use even simpler form:
(char*)ptr += 30;
Although such form is not requested to work in ANSI C standard, the most of compilers (including GCC4TI) will accept this.


Why can't you assign values to dereferenced void pointers?
Previous Memory, C Variables, and Pointers Next

Q: Why doesn't this work?
void *screen_ptr = LCD_MEM;
*screen_ptr = 0xFF;
When I do this, I get the error "Invalid use of void expression" at the second line. Can't you assign a value to a dereferenced void pointer? If not, what good is a void pointer?
A: You can not dereference a void pointer, without an explicite typecasting, because the compiler can't know the size of an object pointed to by it. You can do an explicite typecast:
*(char*)screen = 0xFF;
Or better, if you need to dereference it often, then declare
unsigned char *screen = LCD_MEM;
i.e. avoid void pointers for this purpose (continue reading to see why such assignment is legal, i.e. assigning LCD_MEM which is a void pointer to a char pointer).

Void pointers are used mainly as arguments of functions which represents memory addresses, no matter what is the object located at that addresses. Then, any pointer type (including arrays, which are in fact pointers to the first element of the array) may be passed to such function without warnings and without needness for explicite typecasting. For example, memcpy is such function, and it is declared as:
void *memcpy (void *source, void *destination, unsigned long len);
Ignore returned type for a moment. So, you can do
memcpy (LCD_MEM, buffer, 3840);
but you also can do
memcpy (a, b, 10 * sizeof(long));
assuming that you have declared
long a[10], b[10];
somewhere in the program. Second, void pointers may be assigned to any other pointer type and vice versa without and warnings and without needness for explicite typecasting. They are usually returned as the result of functions which don't make any assumptions what will be purpose of returned pointer. For example, malloc is such function. It is declared as
void *malloc (unsigned long len);
So, assuming that you have declared
char *a;
int *b;
long *c;
you can do
a = malloc (100);
b = malloc (30 * sizeof(int));
c = malloc (50 * sizeof(long));
without any problems.


How can I have large global variables that don't take up space in my program file?
Previous Memory, C Variables, and Pointers Next

Q: I would like to have a global screen buffers which need to be allocated dynamically (to avoid wasting space in the program). The problem is that global variables must be initialized. In your programs, you define the buffer in the _main function, but then they are not available in the other functions. Is there a way to make "global" non-initialized screen buffers?
A: Declare a pointer initialized to NULL, then at the beginning allocate the buffer with malloc. For example, do this:
#include <tigcclib.h>
...
void *buff;  // Buffer pointer
...
void _main(void)
{
  ...
  buff = malloc (LCD_SIZE); // Alloc buffer, make "buff" point to it
  if (!buff) ...            // Do some error handling (no memory)
  LCD_save (buff);
  ...
  LCD_restore (buff);
  free (buff);
}
Simple?


How can I create a dynamic two-dimensional array?
Previous Memory, C Variables, and Pointers Next

Q: Your hints about dynamic creation of arrays work fine for one-dimensional arrays. But I need a global matrix. There is no problem if the matrix is small. But, if I simply put
int A[200][100] = {{}};
I will increase the size of my program by about 40K (200*100*sizeof(int)). This is really unacceptable. Obviously, I need to create a matrix dinamically. But I have no any idea how to do this.
A: Very good question. Solving this problem requires good knowledge about how arrays and pointers are related. As this question usually has unadequate answers in various C books, I will elaborate this topic (dynamic matrix) in more details.

One method, which is often recommended in books, is usage of array of pointers. Using this method, you need to allocate each row of the matrix separately. For example,
int *A[200] = {};   // An array of pointers
...
for (i = 0; i < 200; i++)
  A[i] = calloc (100, sizeof (int));
assuming that all memory allocations were sucessfull. Note that the initializer '{}' is not necessary if 'A' is not global (but we will assume that it is). Of course, you need to free allocated memory too at the end of the program. We will see a bit later why this method is not recommended on TI calculators.

Using this method, you will have a global array which is 800 bytes long (200*4, where 4 is the size of a pointer), which is much smaller than 40000 bytes. And, you need to know a number of rows in advance. Some books suggests a method which does not use any extra space in the executable file, and in which you need not to know any dimensions of the matrix in advance. This method uses a double pointer (pointer to pointer):
int **A = NULL;
...
A = calloc (200, sizeof (*A));
for (i = 0; i < 200; i++)
  A[i] = calloc (100, sizeof (int));
The major drawback of both methods is complicated memory management. In a real program, you need to be aware of a fact that each allocation may fail eventually, and you need to act accordingly if this happens. And, these methods are too expensive for TI calculators. As TIOS memory manager assigns a handle with each allocated block, reserving say 200 handles for just one matrix is too expensive, if even possible, because the total number of free handles is limited!

What to do? The best solution is so simple, but rarely documented in books. Instead of using an array of pointers, use a pointer to an array! Seems strange, but only what you need to do is:
int (*A)[100] = NULL;   // A pointer to an array
...
A = calloc (200, sizeof (*A));
So, everything is done with just one calloc! And, you can free the memory just with one call to free. Wonderful, isn't it? Of course, whatever method you used, you can access to the elements of a matrix using an usual syntax like 'A[i][j]'. Note however that the last ("ideal") method requires that you know the number of columns in advance. Try to understand how all three methods work: it will help you understanding nontrivial pointers, arrays and relations between them.

As many users ask me about creating dynamic matrix, I have made a complete demo program for newbies (called "Dynamic Matrix") which creates and prints elements of dynamically created matrix, using the third (the best in my opinion) method:
#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

#define M 10
#define N 5

int (*A)[N] = NULL;

void _main (void)
{
  int i,j;
  A = calloc (M, sizeof (*A));     // <I>allocation</I>
  for (i = 0; i < M; i++)
    for (j = 0; j < N; j++)
      A[i][j] = i*j;               // fill 'A' with the multiplication table
  clrscr ();
  for (i = 0; i < M; i++)
    {
      for (j = 0; j < N; j++)
        printf ("%2d ", A[i][j]);  // print out the matrix
      printf ("\n");
    }
  free (A);                        // free the memory
  ngetchx();
}
This method is really ideal if you know dimensions of the matrix in advance (which is usually true). It may be easily extended to create dinamically arrays with more than two dimensions. For example, to create dinamically array which behaves like
int A[M][N][P][Q];
where 'N', 'P' and 'Q' are known in compile-time, you can do:
int (*A)[N][P][Q];
...
A = calloc (M, sizeof (*A));
However, if you don't know any dimension of the matrix in advance, the second method is preferable.

See also: How can I create variable-size arrays?


How can I create variable-size arrays?
Previous Memory, C Variables, and Pointers Next

Q: I need variable-size arrays, i.e. arrays which size is not known in compile time...
A: In general, making variable-size arrays in C is extremely easy for one-dimensional arrays. Instead of
int a[n];  // where n is not known in compile-time
you can write:
int *a;
...
a = calloc (n, sizeof (int));
The same is not-so-easy for 2-dimensional arrays (see the previous question), and quite hard (although possible) for n-dimensional arrays where n>2. To do this, you need to have nasty plays with pointers. It is even possible to make a function named multi_dim which creates multidimensional variable-sized arrays. I once created such routine for some internal purposes (note that it is very tricky). Principally, its usage is like this: if you want to simulate
int a[n1][n2][n3][n4];
where n1, n2, n3 and n4 are not known apriori, you need to do:
int ****a;  // yes, quadruple pointer!!!
...
a = multi_dim (4, sizeof (int), n1, n2, n3, n4);
However, GCC4TI is GNU C, and it has some extensions in addition to "standard" C. For example, it allows variable-size arrays without any tricky plays with pointers!!! (Note that this particular extension, together with a few others, has been added to standard ISO C in 1999, so it is no longer non-standard.) Try this:
void _main(void)
{
  int m, n, p;
  m = random (5);
  n = random (5);
  p = random (5);
  {
    int a[m][n][p];
    // do something with a
  }
}
and you will see that it works!


Why do I get "Value computed is not used" when working with pointers?
Previous Memory, C Variables, and Pointers

Q: I have a variable and a pointer to it, for example,
int a, ptr_to_a = &a;
When I tried to modify the variable "a" indirectly using the pointer, like in
*ptr_to_a++;
the compiler reports to me "Value computed is not used". What is wrong here?
A: Note that although operators '++' and '*' have the same precedence, '++' will be evaluated first, so this expression will be evaluated as
*(ptr_to_a++);
i.e. it increases the pointer, then reads the value from it (which is not used for anything). This is not what do you want, of course. To perform what do you want (i.e. to increase the variable pointed to by the pointer), use parentheses to change the order of evaluation, i.e. use
(*ptr_to_a)++;
This will work as expected.


Input: Keyboard and Link
Previous Frequently Asked Questions Next
  • How can I get input from the keyboard?
  • I'm having trouble with the functions from link.h...
  • Do you have the function that gets called when you do InputStr in TI-Basic?
  • How can I make a keyboard input function that allows you to bring up the CHAR menu (or MATH, etc)?
  • I'm having trouble with the OSGetStatKey function.
  • How can I read the keyboard faster than ngetchx, but easier than _rowread?
  • How can I get the key repetition feature to work using the keyboard queue?
  • Why are ngetchx and kbhit so slow?
  • Is there a function like the idle_loop function?
  • How can I bring up the VAR-LINK dialog and get the name of the selected file?
  • I'm having troubles while reading I/O ports!


How can I get input from the keyboard?
Input: Keyboard and Link Next

Q: How I can get input from the keyboard?
A: There is a lot of method how you can make such routine. This is quite easy if you are a C programmer. The easiest but the worst method is to use gets function from stdio.h header file: gets does not do any buffer length checking. In old releases of TIGCCLIB, it did not even allow any editing facitilities (even backspace key would not work), but this is no longer the case. A better idea is to use getsn which does avoid buffer overflows. But if you want to control what exactly is done by the input routine (for example, you may or may not want to allow opening the CHAR menu), you'll have to make a custom keyboard input routine. For example, I usually used the following routine, which is good enough for many purposes (example "Input String"):
// Custom string input example

#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

// Custom String Input Function
void InputStr(char *buffer, unsigned short maxlen)
{
  SCR_STATE ss;
  short key;
  unsigned short i = 0;
  buffer[0] = 0;
  SaveScrState (&ss);
  do
    {
      MoveTo (ss.CurX, ss.CurY);
      printf ("%s_  ", buffer);
        // Note that two spaces are required only if the F_4x6 font is used
      key = ngetchx ();
      if (key >= ' ' && key <= '~' && i < maxlen)
        buffer[i++] = key;
      else if (key == KEY_BACKSPACE && i)
        i--;
      buffer[i] = 0;
    } while (key != KEY_ENTER);
}

// Main Function
void _main(void)
{
  char s[20];
  clrscr ();
  InputStr (s, 20);
  printf ("\n%s", s);
  ngetchx ();
}
Especially, if very good editing facitilities are required, the best idea is to use routines from the textedit.h header file. These routines are extremely powerful and fully customizable. Alternatively, you can also use routines from dialogs.h, especially DialogAddRequest.

See also: Do you have the function that gets called when you do InputStr in TI-Basic?, How can I make a keyboard input function that allows you to bring up a menu?, getsn


I'm having trouble with the functions from link.h...
Previous Input: Keyboard and Link Next

Q: | I have problems with making a program for communication between two calculators. For example, I can't seem to get data to consistantly transfer over the calc to calc link using calls from link.h. I wrote a simple program that just reads key presses and sends them as bytes while checking for bytes from the other calc. Strangely, it only gets about one byte for every 20 or so keypresses...
A: | Many people tells to me about various problems (smaller or greater) with link.h. See the answer about the question why the function ngetchx is slow. Maybe this will help you. I must tell that the linking is not so known topic for me... You must ask some link guru if you want to know more about this problematic...


Do you have the function that gets called when you do InputStr in TI-Basic?
Previous Input: Keyboard and Link Next

Q: | Did you find the keyboard input function that gets called when you do an InputStr in TI-Basic? I'm looking at GKeyIn as probably the main part of whatever this function is, but it also includes the ability to bring up the CHAR dialog, look up key equivalents, and lots of other nice stuff that I want to be able to use.
A: | The TIOS function cmd_inputstr just performs the InputStr command from TI-Basic, but this function is rather limited, so in practice it is better to create a similar function by yourself. I.e, it is possible to call it, but there is a lot of artefact in doing it.

See also: How can I get input from the keyboard?, How can I make a keyboard input function that allows you to bring up a menu?, getsn


How can I make a keyboard input function that allows you to bring up the CHAR menu (or MATH, etc)?
Previous Input: Keyboard and Link Next

Q: I really need a routine like InputStr given above, but which is able to bring up the CHAR dialog. However, I am not able to make such routine by myself...
A: I received a lot of such questions. These questions are usually asked by newbie programmers, but the answer is quite advanced. Although I don't like to present advanced routines as-is without a lot of necessary explanations, I am requested to do so. Well, here is a routine (example "Input String Advanced"):
// Custom string input example enabling the CHAR menu

#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

short captured;

CALLBACK void CaptureHandler(EVENT *ev)
{
  if (ev->Type == CM_STRING)
    captured = *(ev->extra.pasteText);
}

void InputStr(char *buffer, unsigned short maxlen)
{
  SCR_STATE ss;
  short key;
  unsigned short i = 0;
  buffer[0] = 0;
  SaveScrState (&ss);
  do
    {
      MoveTo (ss.CurX, ss.CurY);
      printf ("%s_  ", buffer);
        // Note that two spaces are required only if the F_4x6 font is used
      do
        {
          key = ngetchx ();
          if (key == KEY_CHAR && i < maxlen)
            {
              EVENT ev;
              captured = 0;
              ev.Type = CM_KEYPRESS;
              ev.extra.Key.Code = key;
              EV_captureEvents (CaptureHandler);
              EV_defaultHandler (&ev);
              EV_captureEvents (NULL);
            }
        } while (!captured);
      if (key == KEY_CHAR && i < maxlen)
        buffer[i++] = captured;
      if (key >= ' ' && key <= '~' && i < maxlen) buffer[i++] = key;
      if (key == KEY_BACKSPACE && i) i--;
      buffer[i] = 0;
    } while (key != KEY_ENTER);
}

// Main Function
void _main(void)
{
  char s[20];
  clrscr ();
  InputStr (s, 20);
  printf ("\n%s", s);
  ngetchx ();
}
It will be good if you can understand how it works (I recommend reading the documentation for the events.h header file).

See also: How can I get input from the keyboard?, Do you have the function that gets called when you do InputStr in TI-Basic?, getsn


I'm having trouble with the OSGetStatKey function.
Previous Input: Keyboard and Link Next

Q: | I have problems with OSGetStatKeys function.
A: | See what I wrote about this in the documentation about kbd.h header file. I recommend usage of pseudoconstants from compat.h header file instead.


How can I read the keyboard faster than ngetchx, but easier than _rowread?
Previous Input: Keyboard and Link Next

Q: | Is there any way for reading the keyboard faster than using ngetchx function, but without very low-level access using _rowread?
A: | Yes, there is a LEGAL method to pick keystrokes directly from the keyboard queue. See kbd_queue and other queuing functions from system.h header file.


How can I get the key repetition feature to work using the keyboard queue?
Previous Input: Keyboard and Link Next

Q: | Reading directly from the keyboard queue is a good idea, but the key repetition feature does not work...
A: | On the first look, it seems that the key repetition feature really 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 sets an additional bit in the keycode, so value becomes value + 0x800. If you use 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 working even with OSdequeue.


Why are ngetchx and kbhit so slow?
Previous Input: Keyboard and Link Next

Q: | Why functions ngetchx and kbhit are so slow?
A: | They also implements support for Silent Link feature (ability of automatic receiving programs when the calculator is in Home Screen). That's why they may also interfere with the link transfer!


Is there a function like the idle_loop function?
Previous Input: Keyboard and Link Next

Q: | What is the true equivalent for the idle_loop function known from kernels?
A: | GKeyIn (NULL, 0) is the most similar equivalent. ngetchx () is not so similar. Both functions are defined in kbd.h. Note that idle defined in system.h is NOT equivalent to idle_loop!


How can I bring up the VAR-LINK dialog and get the name of the selected file?
Previous Input: Keyboard and Link Next

Q: How do I bring up the VAR-LINK dialog from C code and then get the name of the file that was selected?
A: This is an advanced question. As the VAR-LINK dialog is an event-driven applet, you must use event-driven functions defined in the events.h header file. Bringing up the VAR-LINK dialog is quite easy:
EVENT ev;
ev.Type = CM_KEYPRESS;
ev.extra.Key.Code = KEY_VARLNK;
EV_defaultHandler (&ev);
but getting the name of the file that was selected is a bit harder. After executing the VAR-LINK dialog, the VAR-LINK applet will send the name of the selected file to the current application via the CM_HSTRING message. This message may be captured by a user event handler. Here is the demonstration program (called "Get File Name"):
// Open VAR-LINK dialog and let user select something

#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

char VarBuffer[20] = "";

CALLBACK void VarLinkHandler (EVENT *ev)
{
  if (ev->Type == CM_HSTRING)
    {
      strncpy (VarBuffer, HeapDeref (ev->extra.hPasteText), 19);
      VarBuffer [19] = 0;
    }
  EV_defaultHandler (ev);
}

void VarLinkDialog (void)
{
  EVENT ev;
  EVENT_HANDLER OldHandler = EV_captureEvents (VarLinkHandler);
  memset (&ev, sizeof (ev), 0);
  ev.Type = CM_KEYPRESS;
  ev.extra.Key.Code = KEY_VARLNK;
  EV_defaultHandler (&ev);
  EV_captureEvents (OldHandler);
}

void _main(void)
{
  VarLinkDialog ();
  printf_xy (0, 50, "You picked: %s", VarBuffer);
  ngetchx ();
}
Read more about the events.h header file: incredible miracles may be produced using event-passing techniques!


I'm having troubles while reading I/O ports!
Previous Input: Keyboard and Link

Q: I have a lot of troubles while reading I/O ports. I need a loop which will wait until the programable timer on the TI-89 reaches value 255. I know that I can read the value of the programable timer counter using address 0x600017, so I made the following loop:
while (*(unsigned char *)0x600017 != 255);
But, the calculator freezes. I tried to use peek macro, as in
while (peek (0x600017) != 255);
No fortune again (I know that this is, in fact, the same as above). What is wrong?
A: See, there is a problem when reading I/O ports in small loops. Look at the above loop for example. The compiler will notice that the same value is read again and again in the loop. As normal memory location can not be changed without explicitly writing to it, and there is nothing in the loop which changes the address 0x600017, the optimizer will move memory reading out of the loop to make the code more efficient. Such behavior is correct for ordinary memory locations. But, in our case, it will cause an infinity loop. The compiler does not know anything about the fact that 0x600017 is not an ordinary memory location but an I/O port, which may be changed unpredictably (purely by the hardware, without any program control). To prevent such behaviour, you should use the volatile keyword to make the address 'volatile', i.e. to say to the compiler that this address may be changed unpredictably. So, the correct code is
while (*(volatile unsigned char *)0x600017 != 255);
The peekIO macro makes life easier. You can do
while (peekIO (0x600017) != 255);
Basically, peekIO works exactly like peek, but prevents any unwanted optimizations generated by the compiler. Always use peekIO (or peekIO_w) for reading memory-mapped I/O ports, else you may have troubles. The _rowread function in TIGCCLIB releases prior to 2.3 also caused similar troubles, now this is corrected too.

peekIO may be used even for reading bytes into the memory, but peek will generate better code when working with memory. However, use peekIO to read any memory location which may change in a way which is unpredictable from the aspect of a normal program flow (for example, a memory location which is changed in the body of the interrupt handler).

Note: For sending bytes to I/O ports, the macros pokeIO and pokeIO_w are also introduced, which are more reliable for this purpose than poke and poke_w.


Miscellaneous
Previous Frequently Asked Questions
  • Some of your examples don't compile!
  • Why do you use -O2/-Os when -O3 performs better optimization?
  • I need to access the FLASH memory.
  • Some functions with no arguments (like 'off') don't work for me!
  • How can I detect the hardware version of the calculator?
  • How can I use very large integers like TIOS?
  • I need the gotoxy() function to port PC programs to the calculator...
  • How can I create a program that is bigger than 24K and works on AMS 2.xx?
  • What might be the reason for my program leaking a small amout of memory?
  • What is an "Address Error"?
  • Why does my program using dialog boxes crash?


Some of your examples don't compile!
Miscellaneous Next

Q: Some of your examples (like the example given in the documentation for rsa.h header file) don't compile!
A: No. They compile fine, if they are typed in absolutely correctly. But there is a hardly-visible problem with the space character. The space between the macro name and the argument list is strictly forbiden, else the macro will be treated as an argumentless macro. In other words, you must not type
#define GetBignumArg (ap, bn) \
instead of
#define GetBignumArg(ap, bn) \
Hardly visible, isn't it?


Why do you use -O2/-Os when -O3 performs better optimization?
Previous Miscellaneous Next

Q: | I wonder why you put '-Os' as a default optimization option in the compiler. '-O3' will perform better optimization...
A: | Yes, but '-O3' produces bigger output than '-Os', because it performs loop unrolling and inlining of "short-enough" functions...


I need to access the FLASH memory.
Previous Miscellaneous Next

Q: | I need access to the archive memory...
A: | This is implemented in this release. See flash.h header file.


Some functions with no arguments (like 'off') don't work for me!
Previous Miscellaneous Next

Q: When I try to turn the calculator off using off function from system.h, nothing happens. What is wrong?
A: Most probably, you wrote
off;
instead of
off ();
This is very common misinterpretation of usage of argument-less function. You may ask why the compiler did not display any errors? See, whenever you use the function name alone (without the parenthesis), it is automatically converted to a pointer to the function (this is very useful feature if used properly). So, 'off' alone is interpreted as a pointer, so you have an statement which consists of an effect-less expression, similarly as if you wrote
2 + 3;
This is not illegal in C, but it has no any effect (eventually, you will be warned by the compiler that the statement has no effect, if you enable enough strong warning checking). Such misinterpretations are very often with newbie users, so I will elaborate this in more details. Suppose that you wrote
key = ngetchx;
You probably want to call ngetchx function to get a keypress, but instead, you will assign the address of this function to the variable 'key', because the function name without parenthesis is automatically converted to a pointer (however, you will be warned by the compiler that it is very ugly to assign a pointer to an integer variable without an explicite typecast). Instead, you need to write
key = ngetchx ();
Sometimes, you will not get even a warning. Look the following example:
void *qptr = kbd_queue;
The intention was probably to put the address of the keyboard queue into the 'qptr' variable, but instead, the address of the function kbd_queue itself will be taken! As the function name is converted to a pointer to a function, and as you assign it to a void pointer (which is assign-compatible with all other pointer types), you will not get even a warning!


How can I detect the hardware version of the calculator?
Previous Miscellaneous Next

Q: | Does any method exists for detecting hardware release of the calculator?
A: | I can now recommend the use of FL_getHardwareParmBlock. However, if you ask it for detecting hardware version before using grayscale routines, you need not to do it because the GrayOn routine now performs an autodetection by itself.


How can I use very large integers like TIOS?
Previous Miscellaneous Next

Q: I need to know more about how the TIOS stores and references big integers. In other words, what would be the C structure that would be used to represent any arbitrarily-long binary integer? In addition, I am particularly interested about how two extermely long binary integers would be multiplied and divided. Does TIOS have its own binary multiplication routine somewhere in the ROM? Something that works similarly to BCD multiplication/division, I'm guessing?
A: TIOS stores all integers (both small and large) in the following format (looking from lower to higher addresses):
  1. Bytes of the integer in little endian (up to 255 bytes);
  2. The number of bytes occupied by integer (one byte);
  3. POSINT_TAG or NEGINT_TAG, depending on the sign.
These integers are kept on the expression stack, or in TI-Basic variables (of course, in TI-Basic variables, there are two extra bytes at the begining, which represents the length of a variable). In other words, integers are kept in a structure which is similar to the BN structure defined in the rsa.h header file, except the length byte is at the end, not at the begining (because data on the expression stack is always in RPN). So, such a structure can't be strictly represented using valid C syntax, because it requires something like
struct big_int
  {
    BYTE data[size];   // but 'size' is not known in advance
    BYTE size;
    BYTE tag;
  }
Routines for multiplying and dividing very long integers surely exist in the TIOS, but the strange fact is that such routines are not in the TIOS jump table (read: they are not usable). Anyway, you can always use general eveluating routines like NG_rationalESI and NG_approxESI. For example, to multiply two very-long-integers, you can use the following template:
push two very-long-ints on the estack
push_quantum (MULT_TAG);
NG_approxESI (top_estack);
However, two routines for working with long integers are in TIOS jump table: for calculating '(A*B)%N' and '(A^B)%N' where "%" is the "modulus" operation, and "^" is "raising to a power". These operations are used in the RSA cryptosystem. Both of them are defined in the rsa.h header file. They may be used for multiplying and raising to a power: you always can set N to very a big number, then (A*B)%N = A*B. Also, you can use them for calculating modulus (if you set B to 1). But, I am not sure how you can simulate division. I think that TI never uses integer division: everything like 'A/B' is kept as a fraction, except in approx mode; TIOS then uses NG_approxESI.


I need the gotoxy() function to port PC programs to the calculator...
Previous Miscellaneous Next

Q: In addition to functions from stdio.h header file, I need gotoxy function to allow porting some PC programs to TI...
A: All printing functions from stdio.h are sensitive to MoveTo command, so it is not hard to set print position to anywhere. If you need just gotoxy, it is impossible for 4x6 font, because it is proportional. But, for 6x8 and 8x10 fonts, it may be implemented trivially:
#define gotoxy(x,y) MoveTo (6*x-6,8*y-8)    // for 6x8 font
#define gotoxy(x,y) MoveTo (8*x-8,10*y-10)  // for 8x10 font
Here I assumed that top-left corner is (1,1) as on PC. Note that you MUST NOT put a space between gotoxy and left bracket (else the preprocessor will define an argument-less macro). You can also define an universal gotoxy macro which will work regardless of current font setting, using smart GNU C macros:
#define gotoxy(x,y) \
  ({short __f=2*FontGetSys(); MoveTo((4+__f)*(x-1),(6+__f)*(y-1));})
You will not be able to understand this if you are not familiar with GNU extensions.


How can I create a program that is bigger than 24K and works on AMS 2.xx?
Previous Miscellaneous Next

Q: How I can make a program which does not need any kernel, but which is greater than 8K and which works on AMS 2.03 as well (or greater than 24K and which works on AMS 2.04 and AMS 2.05 as well)?
A: In fact, you need to make a short program (a so-called "launcher") which will call the main program, bypassing the TIOS (to skip the software protection). If the main program is "example.c", I recommend the following "launcher":
// Launcher for program called "example"

#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#include <tigcclib.h>

#define fatal(s) ({ST_showHelp (s); return;})

void _main (void)
{
  char *fptr, *cptr;
  unsigned short plen;
  SYM_ENTRY *SymPtr = DerefSym (SymFind (SYMSTR ("example")));
  HANDLE h;
  if (!SymPtr) fatal ("Program not found");
  h = SymPtr->handle;
  if (HeapGetLock (h))
    {
      cptr = fptr = HeapDeref (h);
      h = 0;
    }
  else
    {
      cptr = fptr = HLock (h);
    }
  plen = *(short*)(cptr) + 3;
  if (SymPtr->flags.bits.archived)
    {
      if (!(cptr = malloc (plen)))
        {
          if (h) HeapUnlock (h);
          fatal ("Out of memory");
        }
      memcpy (cptr, fptr, plen);
    }
  enter_ghost_space ();
  EX_patch (cptr + 0x40002, cptr + plen + 0x3FFFE);
  ASM_call (cptr + 0x40002);
  if (h) HeapUnlock (h);
  if (cptr != fptr) free (cptr);
}
If you are not an expert, use this program as-is.

For anybody who wants to know more about the 8K limit: on HW1 calcs it is a pure software limit which can be broken by intercepting some error traps (used in PreOS), or by making a short launcher which relocates the called program and jumps to it bypassing the TIOS check. This is what I used. But, yet another problem must be solved: HW2. Namely, it has built-in a hardware device which does not allow that PC can be out of certain zone, so the launcher itself will not help. This device can't be turned off normally by software, but Julien Muchembled found a "hole" in the protection system which allows turning out this device (this is what his HW2 patch does): this is a very nasty method, and I don't want to explain this here. But, this protection device can be fooled in a simple way: it protects only the "normal" RAM address space (i.e. the first 256K of RAM). As RAM is partially decoded, address x and x+256K are the same for TI-89, but if you jump to x+256K instead of x, the protection will not be activated! Look at the launcher to see how it works, and you now can understand why I added 0x40000 (i.e. 256K) to the address in two places. First, I relocate the called program as it is located on x+256K instead of x, then I call the subroutine on x+256K instead of x.

AMS 2.04 and AMS 2.05 introduce yet another level of protection (which existed before, but caused problems very seldomly): on these AMS versions, even jumping to the "ghost address space" (above 256K) is not possible if the program counter is out of a certain area. (This caused the so-called "second launch crash"; if you have AMS 2.05 with any longer program like TI-Chess, you probably know what I am talking about.) That's why I introcuced a new function called enter_ghost_space: its only purpose is to smoothly bypass this new protection. Note that enter_ghost_space is deprecated now; you should use the EXECUTE_IN_GHOST_SPACE directive instead in most cases.


What might be the reason for my program leaking a small amout of memory?
Previous Miscellaneous Next

Q: | My program is leaking some small amount of memory (less than 100 bytes). Where could my leak possibly be?
A: | The reason is probably the home screen history. Press F1 and 8 before and after running your program, and if it is still leaking memory then you need to be concerned.


What is an "Address Error"?
Previous Miscellaneous Next

Q: | What kind of error in my program usually causes an "Address Error"?
A: | Well, writing over the boundaries of an array can usually cause all sorts of errors, since it usually destroys code or the return address of the function. However, an "Address Error" actually means that a short or long value is read or written at an odd address. So if you get an "Address Error" while you are dealing with pointers, check that you do not cast an odd address to a pointer to a short or long integer.


Why does my program using dialog boxes crash?
Previous Miscellaneous

Q: | What causes my archived program using dialog boxes and/or the catalog to crash?
A: | Many things can cause programs to crash. However, archived programs using dialog boxes often crash due to special problems. Defining SET_FILE_IN_USE_BIT may solve the problem.


Header File Index

TIGCC Library Header Files

GCC4TI uses a special library of header files, due to a very specific method of calling TIOS functions. This library is written in such a way that it can be used for producing both "nostub" programs (i.e. programs which does not need any kernel) or kernel-based programs. The user may select whether a "nostub" or "Doors" (after the name of a very old, long-superseded kernel) program will be created. All functions in this library are based only on legal TIOS calls (i.e. calls which have an entry in the TIOS jump table), so they will probably work with any version of the TIOS. And, in this release of the library a lot of "standard" functions defined in ANSI C are also implemented, so this release is highly "ANSI compatible" (in addition to lot of TI-specific functions).

Functions and data types are grouped in different header files, depending on their purpose (note that some functions and data types are defined in more than one header file). Click on a header file name for the description of all functions and data types defined in this header file.

alloc.h | Routines for dynamic memory allocation
args.h | Routines for retrieving arguments passed to the program
asmtypes.h | Common type definitions known to ASM programmers
assert.h | Assert routine for debugging purposes
bascmd.h | Routines for executing TI-Basic commands
basfunc.h | Routines for executing TI-Basic functions
basop.h | Routines for executing TI-Basic operators
cert.h | Routines for accessing certificates and other memory-mapped files
compat.h | Various calc-dependent and AMS-dependent pseudo-constants
ctype.h | Routines for checking and changing character types
default.h | Default header file which is always included
dialogs.h | Routines for creating dialogs
dll.h | Declarations for creating and using nostub libraries
doors.h | Basic header file for kernel-mode programming
error.h | Routines for error handling
estack.h | Routines for symbolic manipulation and expression handling
events.h | Routines for event-driven programming and for mode settings
files.h | Routines for accessing files (needs AMS 2.00 or later)
flash.h | Low-level routines for working with the Flash ROM
flashapp.h | Routines, variables and structures related to FlashApps.
float.h | Various platform-dependent floating point constants proposed by ANSI
gdraw.h | Routines for graph screen drawing
graph.h | Common (non-windowed) graphic routines
graphing.h | Routines, variables and structures related to graphing in general.
gray.h | Routines for grayscale graphics
homescr.h | Home Screen manipulation routines
intr.h | Routines for creating interrupt handlers
inttypes.h | C99 standard header file containing string constants usable in format arguments to printf-type and scanf-type functions, for printing and scanning the portable integer types defined in stdint.h.
iso646.h | ISO C99 definitions of alternative spellings for operators
kbd.h | Keyboard handling routines
limits.h | Various platform-dependent constants proposed by ANSI
link.h | Calc/calc and calc/computer link interface routines
math.h | ANSI-compatible routines for floating point arithmetic
mem.h | Routines for manipulation of memory blocks
menus.h | Routines for creating popup and toolbar menus
nostub.h | Basic header file for kernel-less programming
peekpoke.h | Routines for easier access to the memory and to I/O ports
printf.h | Printing routines (now deprecated, use stdio.h instead)
rsa.h | Routines for large number arithmetic, message digesting and RSA encryption
setjmp.h | ANSI-compatible routines for non-local jumps
sprites.h | Simple sprite routines
statline.h | Routines for manipulation of the status line
stats.h | Routines for working with statistics.
stdarg.h | ANSI routines for creating functions with variable numbers of arguments
stdbool.h | ISO C99 definitions of boolean type and values
stddef.h | ANSI definitions of default macros and types
stdint.h | C99-compatible integer types with a fixed size in bits
stdio.h | ANSI-compatible file and TTY input/output routines
stdlib.h | Some useful routines proposed by ANSI (sorting, searching, etc.)
string.h | ANSI-compatible string manipulation routines
system.h | System routines (for accessing system timers, queues, etc.)
textedit.h | Routines to access the text editor
tigcclib.h | Includes all other header files
timath.h | Routines for floating point arithmetic
unknown.h | Unknown routines
values.h | Various platform-dependent constants
vat.h | Routines for accessing the variable allocation table
version.h | Constants describing the version number of GCC4TI
wingraph.h | Routines for windowed graphics

Note: This library is not compatible with the romcalls.h header file which comes with extremely old versions of the TIGCC compiler. Include the tigcclib.h header file instead. Also, note that this library depends strongly on GNU C extensions, so it is not portable to other compilers. That's why this library cannot be used for compiling programs using the '-ansi' command switch, which disables the use of GNU extensions and allows only ANSI-proposed features (except if each extension is marked as such).


alloc.h

alloc.h Header File
Header File Index

Routines for dynamic memory allocation

Functions
alloca
Allocates memory on the local storage space.
calloc_throw
Performs calloc, and throws an error if not successful.
calloc
Allocates a memory block for a given number and size of items.
free
Frees an allocated block.
FreeHandles
Determines the number of free handles.
HeapAlloc
Allocates memory and returns a handle of allocated block.
HeapAllocESTACK
Like HeapAlloc, but reduces the size of the expression stack if necessary.
HeapAllocHigh
Allocates memory at the high end of the heap and returns the handle of the allocated block.
HeapAllocHighThrow
Performs HeapAllocHigh, and throws an error if not successful.
HeapAllocPtr
Allocates memory at the high end of the heap and returns a pointer to the allocated block.
HeapAllocPtrThrow
Performs HeapAllocPtr, and throws an error if not successful.
HeapAllocThrow
Performs HeapAlloc, and throws an error if not successful.
HeapAvail
Determines the size of the heap.
HeapCompress
Compresses the heap.
HeapDeref
Dereferences a handle.
HeapEnd
Determines the end of the heap.
HeapFree
Frees a heap block given its handle.
HeapFreeIndir
Frees a heap block given a pointer to it.
HeapFreePtr
Frees a block allocated using HeapAllocPtr.
HeapGetHandle
Gets the next available handle.
HeapGetLock
Determines whether a block is locked.
HeapLock
Locks a block.
HeapMax
Determines the size of the largest allocatable block.
HeapMoveHigh
Reallocates a block.
HeapPtrToHandle
Determines the handle associated with a block.
HeapRealloc
Reallocates a block to a new size.
HeapReallocThrow
Performs HeapRealloc, and throws an error if not successful.
HeapShuffle
Shuffles all unlocked blocks on the heap.
HeapSize
Determines the size of an allocated block.
HeapUnlock
Unlocks a block.
HeapWalk
Verifies and dumps the contents of the heap.
HLock
Locks and dereferences a handle.
hStrAppend
Appends a string to a handle that contains a string.
malloc_throw
Performs malloc, and throws an error if not successful.
malloc
Allocates a memory block.
PtrToHandle
Determines the handle associated with a block.
realloc_throw
Performs realloc, and throws an error if not successful.
realloc
Reallocates allocated memory.
Constants
H_NULL
A null-handle value.
NULL
A null-pointer value.
Predefined Types
Bool
An enumeration to describe true or false values.
HANDLE
Represents a handle associated with an allocated memory block.
HeapWalkCmds
An enumeration describing the valid parameters for HeapWalk.
size_t
A type to define sizes of strings and memory blocks.

See also: mem.h


alloca

alloca Function (Builtin)
alloc.h, stdlib.h

void *alloca (unsigned long Size);

Allocates memory on the local storage space.

alloca is a function which is not included in the ANSI C standard, but it exists in many C dialects (including GCC4TI). It allocates a block of Size bytes on the CPU stack (local storage space), in opposite to malloc which allocates memory on the memory heap. The space allocated with alloca exists until the containing function returns (i.e. it will be automatically deallocated at the end of the function). Be aware of the fact that the size of the hardware stack on TI calculators is limited to 16 kilobytes, so do not use alloca for allocating large blocks.

alloca is usually used for simulating automatic variable-sized one-dimensional arrays, which will be automatically deallocated when the function ends (like all automatic variables), so it is sometimes more preferable than malloc. For example, to simulate

int a[n];
where 'n' is not known in advance, you can use
int *a = alloca (n);
Note, however, that GNU C extensions allows variable-length arrays, which are more elegant than usage of alloca, and which may also be with more than one dimension (which is not possible with alloca).

Note: alloca is a built-in (open-coded) function in GNU C, which is translated to a single instruction which simply adjusts the stack. Some compiler command options (like '-ansi') prevent alloca from being an open-coded function. In this implementation of GCC4TI, you cannot use alloca with such options (however, it is very unlikely that you will ever have such problems).

Used by: SYMSTR


calloc_throw

calloc_throw Function* (tigcc.a)
alloc.h

void *calloc_throw (unsigned short NoOfItems, unsigned short SizeOfItems);

Performs calloc, and throws an error if not successful.

calloc_throw calls calloc and throws a memory error if there is not enough memory. Otherwise, it returns a pointer to the allocated block.

Uses: calloc


calloc

calloc Function* (tigcc.a)
alloc.h, stdlib.h

void *calloc (unsigned short NoOfItems, unsigned short SizeOfItems);

Allocates a memory block for a given number and size of items.

calloc allocates a block of NoOfItems x SizeOfItems bytes from the memory heap. On success, calloc returns a pointer to the newly allocated block of memory. If not enough space exists for the new block, it returns NULL. The allocated block will be cleared to zero content.

Note: In releases of TIGCCLIB prior to 2.0, calloc was implemented here as a macro, Now, it is a function. It first calls malloc with NoOfItems x SizeOfItems as the argument, then calls memset if the first call was successful.

Uses: HeapAllocPtr, memset
Used by: calloc_throw

See also: malloc, realloc, free, calloc_throw


free

free Function (ROM Call 0xA3)
alloc.h, stdlib.h

void free (void *Ptr);

Frees an allocated block.

free deallocates a memory block allocated by a previous call to malloc or calloc.

Note: free is in fact an ANSI C alias for a TIOS routine originally called HeapFreePtr.

Do not attempt to use free on a pointer which has changed after it was allocated with malloc, calloc, or realloc. For example, the following code will certainly crash the calculator:

char *ptr = malloc (2);
if (ptr)
  {
    *(ptr++) = 'A';  // pointer changed here
    *ptr = 0;
    ...
    free (ptr);
  }
Instead, preserve the original pointer and pass it to free.

Uses: HeapFree

See also: malloc, realloc, calloc


FreeHandles

FreeHandles Function (ROM Call 0x23B)
alloc.h

short FreeHandles (void);

Determines the number of free handles.

FreeHandles returns the number of free handles.


HeapAlloc

HeapAlloc Function (ROM Call 0x90)
alloc.h

HANDLE HeapAlloc (unsigned long Size);

Allocates memory and returns a handle of allocated block.

HeapAlloc allocates a block of heap memory of Size bytes (all odd sizes are rounded up to be even) and returns its handle. Allocated blocks are kept in a singly-linked list of blocks. Returns H_NULL if there is not enough memory. The maximum size of a single block is 65520 bytes, and the minimum size is 6 bytes. Use HeapDeref to dereference the handle and get a pointer to the actual memory. Note that an unlocked pointer to the heap is valid only as long as heap compression (i.e. garbage collection) is not done. This routine may cause garbage collection.

Uses: HeapCompress, HeapGetHandle, NeedStack
Used by: HeapAllocESTACK, HeapAllocHigh, HeapAllocThrow, HeapFree, HeapRealloc, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_newdata, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_stogdb, cmd_twovar, DialogNew, DlgMessage, ERD_dialog, display_statements, Parse1DExpr, EV_defaultHandler, handleRclKey, handleVarLinkKey, gdb_recall, HomeExecute, LIO_Get, LIO_Receive, MenuBegin, MenuLoad, MenuNew, PopupBegin, PopupClear, PopupNew, fopen, TE_open, EV_quit, GT_SaveAs, LIO_SendIdList, OO_New, PlotDup, PlotInit, SP_Define, store_data_var, time_loop, EM_moveSymFromExtMem, EM_twinSymFromExtMem, FolderAdd, VarStore, WinOpen, ROM Call 0x40C, ROM Call 0x424


HeapAllocESTACK

HeapAllocESTACK Function (ROM Call 0x91)
alloc.h

HANDLE HeapAllocESTACK (unsigned long Size);

Like HeapAlloc, but reduces the size of the expression stack if necessary.

HeapAllocESTACK works like HeapAlloc, but reduces the size of the expression stack if necessary (i.e. if there is not enough memory). Returns H_NULL if there is not enough memory even after reducing the size of the expression stack.

Note: The information about this routine in releases of TIGCCLIB prior to 2.0 was wrong!

Uses: HeapAlloc, HeapCompress, HeapGetHandle, ER_catch, ER_success, bottom_estack, reset_estack_size, top_estack, NeedStack, ROM Call 0x5C6
Used by: MenuKey, ROM Call 0x421


HeapAllocHigh

HeapAllocHigh Function (ROM Call 0x92)
alloc.h

HANDLE HeapAllocHigh (unsigned long Size);

Allocates memory at the high end of the heap and returns the handle of the allocated block.

HeapAllocHigh allocates a block of Size bytes of heap memory at the high end of the heap, locks it, and returns its handle. Returns H_NULL if there is not enough memory. The primary use of this routine is to allocate task local storage. It also compresses the heap first to (hopefully) move all used (unlocked) blocks of memory down. This routine will cause garbage collection.

Note: Blocks of memory that are locked for long periods of time should be moved high in memory so that they do not interfere as much with rest of the system. This routine ALWAYS compresses the heap before it tries to allocate the requested memory and so is much slower than the standard HeapAlloc routine. Locking memory may cause the system to run out of useable memory sooner than if memory is kept unlocked.

Uses: HeapAlloc, HeapCompress, HeapGetHandle, HeapLock, NeedStack
Used by: HeapAllocHighThrow, HeapAllocPtr, malloc, GrayOn, HS_popEStack

See also: HeapAlloc


HeapAllocHighThrow

HeapAllocHighThrow Function (ROM Call 0x94)
alloc.h

HANDLE HeapAllocHighThrow (unsigned long Size);

Performs HeapAllocHigh, and throws an error if not successful.

HeapAllocHighThrow calls HeapAllocHigh and throws a memory error if there is not enough memory. Otherwise, it returns the handle of the allocated block.

Uses: HeapAllocHigh
Used by: cmd_sinreg, cmd_sorta, cmd_sortd, push_determinant, push_red_row_ech, push_row_echelon, push_simult, push_sq_matrix_to_whole_number, ROM Call 0x494, ROM Call 0x495


HeapAllocPtr

HeapAllocPtr Function (ROM Call 0xA2)
alloc.h

void *HeapAllocPtr (unsigned long Size);

Allocates memory at the high end of the heap and returns a pointer to the allocated block.

HeapAllocPtr performs HeapAllocHigh, but instead of the handle, it returns a pointer to the allocated block (NULL in a case of error). It also gives a necessary information to the heap manager which is needed later for deallocating the memory using HeapFreePtr command. This routine is principally equivalent to ANSI C malloc function, so it is aliased here also as malloc.

Note: If somebody is interested in it, the handle of the allocated block is stored two bytes below the address returned by HeapAllocPtr.

Uses: HeapAllocHigh, NeedStack
Used by: calloc, HeapAllocPtrThrow, realloc, LoadDLL, fopen, scanf, vscanf, atexit


HeapAllocPtrThrow

HeapAllocPtrThrow Function* (tigcc.a)
alloc.h

void *HeapAllocPtrThrow (unsigned long Size);

Performs HeapAllocPtr, and throws an error if not successful.

HeapAllocPtrThrow calls HeapAllocPtr and throws a memory error if there is not enough memory. Otherwise, it returns the handle of the allocated block.

Uses: HeapAllocPtr


HeapAllocThrow

HeapAllocThrow Function (ROM Call 0x93)
alloc.h

HANDLE HeapAllocThrow (unsigned long Size);

Performs HeapAlloc, and throws an error if not successful.

HeapAllocThrow calls HeapAlloc and throws a memory error if there is not enough memory. Otherwise, it returns the handle of the allocated block.

Uses: HeapAlloc
Used by: cmd_blddata, cmd_custom, cmd_get, cmd_send, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_toolbar, GR3_paint3d, gdb_recall, HomeExecute, HomePushEStack, HS_newFIFONode, CreateEmptyList, de_initRes, de_loop, gr_execute_de, gr_execute_seq, GR3_addContours, GT_Trace, InitDEMem, Regraph, seqWebInit, SP_Define, statStart, NG_setup_graph_fun, ROM Call 0x438, ROM Call 0x45B, ROM Call 0x494, ROM Call 0x495, ROM Call 0x4CB


HeapAvail

HeapAvail Function (ROM Call 0x8F)
alloc.h

unsigned long HeapAvail (void);

Determines the size of the heap.

HeapAvail returns the total amount of free bytes in the heap (the sum of all of the individual blocks of memory).


HeapCompress

HeapCompress Function (ROM Call 0x95)
alloc.h

void HeapCompress (void);

Compresses the heap.

HeapCompress coalesces all used heap blocks, deleting any free blocks from the heap if possible. If there are any locked blocks, the heap may remain fragmented. This routine is called automatically by the system whenever it is needed and usually should not be called by applications.

Uses: memmove, NeedStack
Used by: HeapAlloc, HeapAllocESTACK, HeapAllocHigh, HeapMax, HeapMoveHigh, HeapRealloc, HeapShuffle, time_loop

See also: HeapShuffle


HeapDeref

HeapDeref Function (ROM Call 0x96)
alloc.h

void *HeapDeref (HANDLE Handle);

Dereferences a handle.

HeapDeref dereferences Handle and returns a pointer to the actual block of the memory defined by that Handle. Nearly all heap allocation routines return a "handle" which is an identifier for a block of memory allocated in the heap. In order to use that memory, the handle must be dereferenced. Once a handle is dereferenced, that pointer is valid as long as nothing else is done to cause the heap to be compressed. If the heap is compressed the handle can be re-dereferenced to make it valid again. If a handle is locked, then the pointer that references that block of memory is valid even after the heap is compressed (since locking a handle means the heap manager will never move the memory associated with that handle).

Note: HeapDeref returns garbage if Handle is H_NULL.

Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_twovar, LoadDLL, EV_defaultHandler, MO_modeDialog, GR3_paint3d, GR3_xyToWindow, GrayOn, HomeStorePair, FKeyI_H, de_loop, EV_quit, execute_graph_func, GR3_addContours, InitDEMem, InitTimeSeq, Regraph, run_one_seq, FindProgramVar, ROM Call 0x424


HeapEnd

HeapEnd Function (ROM Call 0xA1)
alloc.h

void *HeapEnd (void);

Determines the end of the heap.

HeapEnd returns a pointer to the end of the heap.


HeapFree

HeapFree Function (ROM Call 0x97)
alloc.h

void HeapFree (HANDLE Handle);

Frees a heap block given its handle.

HeapFree frees a heap block associated with handle Handle.

Uses: HeapAlloc, reset_estack_size, NeedStack
Used by: free, HeapFreeIndir, HeapFreePtr, HeapGetHandle, realloc, cmd_clrtable, cmd_cubicreg, cmd_delvar, cmd_dialog, cmd_disp, cmd_expreg, cmd_get, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_newdata, cmd_onevar, cmd_output, cmd_popup, cmd_powerreg, cmd_prompt, cmd_quadreg, cmd_quartreg, cmd_request, cmd_send, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_twovar, push_determinant, push_red_row_ech, push_row_echelon, push_simult, push_string, DlgMessage, VarNew, VarOpen, VarSaveAs, display_statements, Parse1DExpr, EV_defaultHandler, MO_modeDialog, GrayOff, HomeExecute, HomeStorePair, HS_freeFIFONode, LIO_Receive, OSLinkCmd, MenuEnd, MenuKey, VarCreateFolderPopup, TE_handleEvent, cleanup_seq_mem, freeIdList, GR3_freeDB, GT_PrintCursor, GT_SaveAs, OO_Destroy, PlotInit, push_sq_matrix_to_whole_number, Regraph, statFree, store_data_var, tokenize_if_TI_92_or_text, VarStoreLink, AddSymToFolder, EM_moveSymToExtMem, EM_twinSymFromExtMem, FolderAdd, FolderDel, HSymDel, SymDel, SymDelTwin, VarStore, ROM Call 0x421, ROM Call 0x438, ROM Call 0x439, WinRemove


HeapFreeIndir

HeapFreeIndir Function (ROM Call 0x98)
alloc.h

void HeapFreeIndir (HANDLE *HandlePtr);

Frees a heap block given a pointer to it.

HeapFreeIndir is like HeapFree except you pass the address of a variable which keeps the block handle instead of the handle itself. If the handle that HandlePtr points to is not H_NULL, then it frees that handle and sets the handle variable that is pointed to by HandlePtr to H_NULL.

Maybe this sounds a bit confusing to you. In fact, doing

HeapFreeIndir (&handle);    // The ampersand ('&') is important
works exactly the same as
if (handle) HeapFree (handle);
handle = H_NULL;
Note: In releases of TIGCCLIB prior to 2.2, the information about this routine was quite misleading or even wrong.

Uses: HeapFree
Used by: cmd_blddata, cmd_cubicreg, cmd_custom, cmd_dialog, cmd_disphome, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_newdata, cmd_onevar, cmd_pause, cmd_popup, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_request, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_stogdb, cmd_toolbar, cmd_twovar, DlgMessage, ERD_dialog, EV_clearPasteString, EV_defaultHandler, handleRclKey, MO_modeDialog, GR3_paint3d, gdb_recall, HomeExecute, HomePushEStack, HS_freeFIFONode, TE_close, cleanup_de_mem, cleanup_seq_mem, CustomFree, EV_quit, gr_delete_fldpic, GR3_addContours, GR3_freeDB, GT_Trace, Regraph, SetGraphMode, SP_Define, VarStoreLink, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x424, ROM Call 0x438, ROM Call 0x45B, ROM Call 0x486, ROM Call 0x494, ROM Call 0x495


HeapFreePtr

HeapFreePtr Function (ROM Call 0xA3)
alloc.h

void HeapFreePtr (void *Ptr);

Frees a block allocated using HeapAllocPtr.

HeapFreePtr frees a heap block pointed to by Ptr. The block must be a block which was allocated using the HeapAllocPtr command.

Do not attempt to use HeapFreePtr on a pointer which has changed after it was allocated with HeapAllocPtr. For example, the following code will certainly crash the calculator:

char *ptr = HeapAllocPtr (2);
if (ptr)
  {
    *(ptr++) = 'A';  // pointer changed here
    *ptr = 0;
    ...
    HeapFreePtr (ptr);
  }
Instead, preserve the original pointer and pass it to HeapFreePtr.

Uses: HeapFree
Used by: UnloadDLL, fopen, scanf, vscanf, atexit


HeapGetHandle

HeapGetHandle Function (ROM Call 0x239)
alloc.h

HANDLE HeapGetHandle (void);

Gets the next available handle.

HeapGetHandle returns the number of the first unallocated (free) handle, or H_NULL if there are no free handles. Used mainly for internal purposes.

Uses: HeapFree, memmove, memset
Used by: HeapAlloc, HeapAllocESTACK, HeapAllocHigh, time_loop


HeapGetLock

HeapGetLock Function (ROM Call 0x9B)
alloc.h

short HeapGetLock (HANDLE Handle);

Determines whether a block is locked.

Returns non-zero if the block given by Handle is locked, 0 if it is not (i.e. if that memory is free to move on the next heap compression).

Used by: Dialog, LoadDLL, NG_RPNToText, handleRclKey, push_user_func, ROM Call 0x438


HeapLock

HeapLock Function (ROM Call 0x9A)
alloc.h

HANDLE HeapLock (HANDLE Handle);

Locks a block.

HeapLock locks the block referenced by Handle so that it is not moved during garbage collection. Returns Handle if OK, else returns H_NULL.

Note: Locking memory may cause the system to run out of usable memory sooner than if memory is kept unlocked.

Used by: HeapAllocHigh, HLock, cmd_blddata, cmd_dialog, cmd_get, cmd_newdata, cmd_request, cmd_send, cmd_sinreg, cmd_sorta, cmd_sortd, push_determinant, push_red_row_ech, push_row_echelon, push_simult, Dialog, DialogDo, LoadDLL, display_statements, index_below_display_expression_aux, NG_execute, NG_RPNToText, Parse1DExpr, Parse2DMultiExpr, EV_defaultHandler, handleRclKey, GR3_paint3d, gdb_recall, HomeExecute, LIO_Get, LIO_Receive, MenuBegin, PopupBegin, PopupBeginDo, PopupDo, TE_handleEvent, de_initRes, de_loop, did_push_var_val, does_push_fetch, EV_quit, GetStatValue, gr_ck_solvergraph, InitTimeSeq, NG_setup_graph_fun, PlotDup, push_ans_entry, push_sq_matrix_to_whole_number, push_user_func, recall_data_var, seqWebInit, setup_more_graph_fun, SP_Define, tokenize_if_TI_92_or_text, VarStoreLink, FolderOp, VarStore, ROM Call 0x438, ROM Call 0x494, ROM Call 0x495


HeapMax

HeapMax Function (ROM Call 0x9C)
alloc.h

unsigned long HeapMax (void);

Determines the size of the largest allocatable block.

HeapMax returns the size of the largest block allocatable on the heap (it will be in the range of 0 through 65520). Note that this may not be equal to HeapAvail due to locked blocks, overhead, and maximum block size. This routine will (always) cause heap compression (garbage collection).

Uses: HeapCompress
Used by: scanf, vscanf


HeapMoveHigh

HeapMoveHigh Function (ROM Call 0xA0)
alloc.h

HANDLE HeapMoveHigh (HANDLE Handle);

Reallocates a block.

HeapMoveHigh tries to reallocate a block referenced by Handle as high in memory as possible. The block must not be locked. If successful, returns the handle passed; otherwise returns H_NULL (in this case, the block is still in the same place as before, so no memory is lost). This routine will cause heap compression (garbage collection).

Uses: HeapCompress, memmove, NeedStack
Used by: NG_execute, HomeExecute, TE_handleEvent, CustomBegin, push_user_func


HeapPtrToHandle

HeapPtrToHandle Function (ROM Call 0x23A)
alloc.h

HANDLE HeapPtrToHandle (void *Ptr);

Determines the handle associated with a block.

HeapPtrToHandle returns the handle associated to the block whose beginning is pointed to by Ptr (or H_NULL if Ptr does not point to the beginning of a block).
This routine works by searching the entire table of handles for the given pointer. It will return meaningful results only if the block of memory was not moved (e.g. by heap compression) since the pointer was originally obtained.
Note: PtrToHandle, implemented in the GCC4TI library, returns the handle associated to the block referenced by the pointer, even if the pointer does not point to the beginning of the block.

See also: PtrToHandle


HeapRealloc

HeapRealloc Function (ROM Call 0x9D)
alloc.h

HANDLE HeapRealloc (HANDLE Handle, unsigned long NewSize);

Reallocates a block to a new size.

If Handle is H_NULL, HeapRealloc calls HeapAlloc. Otherwise, it tries to reallocate the given heap block to a new size. Returns H_NULL if there is not enough memory (it will try to call HeapCompress) or if new size is invalid; otherwise returns Handle (but Handle will still be valid even if there was not enough memory). If the heap block is locked, then the block will not be moved in order to reallocate it. However, unlocked blocks above the heap block will be moved. The contents of the object will be unchanged up to the lesser of the new and old size. If the new size is larger, the value of the newly allocated portion of the block is indeterminate. This routine may cause garbage collection.

Note: Reallocating a locked block may fail very easily, especially if you have allocated and locked some blocks just shortly before. The reason is simple: If you allocate memory blocks in sequence, they are usually located close to each other. If you try to grow a locked block which lies directly in front of another locked block, the operation will fail because the second locked block cannot be moved. In general it is a good idea to unlock memory blocks before using HeapRealloc, and to lock them again afterwards if necessary. This way the probability to succeed is much higher.

Uses: HeapAlloc, HeapCompress, memmove, NeedStack
Used by: HeapReallocThrow, realloc, cmd_blddata, cmd_cubicreg, cmd_dialog, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_newdata, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_request, cmd_twovar, DialogAdd, check_estack_size, display_statements, index_below_display_expression_aux, Parse1DExpr, reset_estack_size, FClose, FPutC, HomeExecute, LIO_Receive, DynMenuAdd, DynMenuChange, fclose, fputc, CB_replaceTEXT, TE_checkSlack, TE_handleEvent, TE_pasteText, TE_shrinkWrap, convert_to_TI_92, delete_list_element, hStrAppend, OO_SetAttr, PlotDel, PlotPut, ReallocExprStruct, spike_geo_titles, spike_in_editor, spike_optionD, tokenize_if_TI_92_or_text, AddSymToFolder, FolderAdd, FolderDel, FolderRename, HSymDel, SymAddTwin, SymDel, SymDelTwin, VarStore, WinReOpen, ROM Call 0x439, ROM Call 0x4CB


HeapReallocThrow

HeapReallocThrow Function* (tigcc.a)
alloc.h

HANDLE HeapReallocThrow (HANDLE Handle, unsigned long NewSize);

Performs HeapRealloc, and throws an error if not successful.

HeapReallocThrow calls HeapRealloc and throws a memory error if there is not enough memory. Otherwise, it returns the handle of the allocated block.

Uses: HeapRealloc


HeapShuffle

HeapShuffle Function (ROM Call 0x474)
AMS 2.00 or higher alloc.h

void HeapShuffle (void);

Shuffles all unlocked blocks on the heap.

HeapShuffle shuffles all unlocked blocks on the heap. As a consequence, all dereferenced handles to unlocked blocks of memory in the heap may become invalid. This function is not the same as HeapCompress. It is used mainly for debugging the program.

Here is a test example (called "Heap Shuffle"):

// Call HeapShuffle and compare addresses

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 200           // Compile for AMS 2.00 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// Main Function
void _main(void)
{
  unsigned char *p1, *p2, *p3, *p4, *p5, *p6;
  HANDLE h1, h2, h3;
  short f = FontGetSys ();
  unsigned char b[50];

  h1 = HeapAlloc (0x1000);
  h2 = HeapAlloc (0x1000);
  h3 = HeapAlloc (0x1000);

  if (h1 && h2 && h3)
    {
      ClrScr ();

      p1 = HeapDeref (h1);
      p3 = HeapDeref (h2);
      p5 = HLock (h3);
      HeapShuffle ();
      p2 = HeapDeref (h1);
      p4 = HeapDeref (h2);
      p6 = HeapDeref (h3);

      FontSetSys (F_4x6);
      DrawStr (0, 0, "Before/after shuffle:", A_NORMAL);

      sprintf (b, "Block 1 (unlocked): %lp %lp", p1, p2);
      DrawStr (0, 10, b, A_NORMAL);

      sprintf (b, "Block 2 (unlocked): %lp %lp", p3, p4);
      DrawStr (0, 20, b, A_NORMAL);

      sprintf (b, "Block 3 (locked): %lp %lp", p5, p6);
      DrawStr (0, 30, b, A_NORMAL);

      FontSetSys (f); // Restore previous font
      GKeyIn (NULL, 0);
    }

  HeapFree (h3);
  HeapFree (h2);
  HeapFree (h1);
}

Uses: HeapCompress, memmove, EM_getArchiveMemoryBeginning

See also: HeapCompress, HeapWalk


HeapSize

HeapSize Function (ROM Call 0x9E)
alloc.h

unsigned long HeapSize (HANDLE Handle);

Determines the size of an allocated block.

HeapSize returns the number of bytes allocated for the heap block referenced by Handle. Due to word alignment and minimum block size, this may not be the amount it was allocated with. 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.

Used by: DialogAdd, FClose, FPutC, fopen, EM_moveSymFromExtMem, EM_moveSymToExtMem, EM_twinSymFromExtMem, FindProgramVar, ROM Call 0x438


HeapUnlock

HeapUnlock Function (ROM Call 0x9F)
alloc.h

HANDLE HeapUnlock (HANDLE Handle);

Unlocks a block.

HeapUnlock unlocks the block referenced by the Handle so that it can be moved during garbage collection. Returns Handle if OK, else returns H_NULL.

Uses: EM_getArchiveMemoryBeginning
Used by: realloc, cmd_dialog, cmd_get, cmd_newdata, cmd_sinreg, cmd_sorta, cmd_sortd, Dialog, DialogDo, LoadDLL, display_statements, index_below_display_expression_aux, NG_execute, NG_RPNToText, NG_tokenize, Parse1DExpr, Parse2DMultiExpr, EV_defaultHandler, handleRclKey, GR3_paint3d, gdb_recall, HomeExecute, HS_popEStack, LIO_Get, LIO_Receive, PopupBeginDo, PopupDo, fclose, fputc, TE_handleEvent, CustomBegin, CustomEnd, de_initRes, de_loop, did_push_var_val, does_push_fetch, EV_quit, GetStatValue, gr_ck_solvergraph, InitTimeSeq, NG_cleanup_graph_fun, NG_setup_graph_fun, PlotDup, push_ans_entry, push_user_func, recall_data_var, seqWebInit, SP_Define, tokenize_if_TI_92_or_text, unlock_more_graph_fun, VarStoreLink, FolderOp, ROM Call 0x438


HeapWalk

HeapWalk Function (ROM Call 0x12C)
AMS 2.00 or higher alloc.h

short HeapWalk (short function);

Verifies and dumps the contents of the heap.

HeapWall looks through the heap to verify it is valid. Then it prints the status of the heap, prints the size of each heap block and its handle, or prints the symbol table, according to the value of function. HeapWalk uses LIO_SendData to send the output through the link port.

The valid values for function, defined in the enum HeapWalkCmds, are:

H_WALK_VERIFY | The function just verifies the heap, and outputs nothing to the link port.
H_WALK_STATUS | The function outputs the total free space, maximum size of a free block, number of used and free blocks, and the number of locked blocks.
H_WALK_DUMP | The function outputs the heap status and the size of the heap block for each handle.
H_WALK_SYM | AMS 2.04 or higher: The function outputs the entire VAT.

HeapWalk called with function as H_WALK_VERIFY, H_WALK_STATUS or H_WALK_DUMP, returns TRUE if the heap is valid, FALSE otherwise.
HeapWalk(H_WALK_SYM) executes this block of code after verifying the heap. The example "List variables and folders" works on any AMS version, unlike HeapWalk(H_WALK_SYM):

// Sends the list of all variables and folders through the link port.
// This program does what HeapWalk(H_WALK_SYM); does on AMS 2.04 and
// later, but also works on any AMS version.

#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 NO_CALC_DETECT
#define ENABLE_ERROR_RETURN
#define MIN_AMS 100           // Compile for AMS 1.00 or higher

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

void _main(void)
{
SYM_ENTRY *symptr;
unsigned char buffer[256];
#ifdef SAVE_SYMPG // Saving the SymPG isn't necessary in _main, nobody else does it.
SymPG_S save;
TRY
  memcpy(&save, pSymPG, sizeof(SymPG_S));
#endif
  if ((symptr = SymFindFirst(NULL,2)) != NULL)
  {
    strcpy(buffer, "\r\nName/Flags/hVal (dec)\r\n");
    LIO_SendData(buffer, strlen((char*)buffer));
    do
    {
      short flags = symptr->flags.flags_n;
      if ((flags&SF_FOLDER))
        sprintf((char *)buffer, "FOLDER: %-8s   %04X  %hd\r\n", symptr->name,
        flags, symptr->handle);
      else
        sprintf((char *)buffer, "%8s\\%-8s %04X  %hd\r\n", SymFindFolderName(),
        symptr->name, flags, symptr->handle);
      LIO_SendData(buffer, strlen((char *)buffer));
      symptr = SymFindNext();
    } while (symptr != NULL);
  }
#ifdef SAVE_SYMPG // See above.
FINALLY
  memcpy(pSymPG, &save, sizeof(SymPG_S));
ENDFINAL
#endif
}

Uses: ER_catch, LIO_SendData, memcpy, sprintf, strlen, pSymPG, SymFindFirst, SymFindFolderName, SymFindNext

See also: HeapShuffle, vat.h, SymFindFolderName, pSymPG, SymPG_S


HLock

HLock Function (ROM Call 0x99)
alloc.h

void *HLock (HANDLE Handle);

Locks and dereferences a handle.

HLock locks a block referenced by Handle so that it will not move on the next heap compression, and returns a pointer to the actual memory block. Returns NULL in a case of error.

Note: Locking memory may cause the system to run out of usable memory sooner than if memory is kept unlocked.

Uses: HeapLock
Used by: realloc, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_toolbar, cmd_twovar, display_statements, NG_tokenize, Parse1DExpr, HomeExecute, fopen, fputc, TE_handleEvent, CustomBegin, SP_Define


hStrAppend

hStrAppend Function (ROM Call 0x45F*)
AMS 1.01 or higher alloc.h

void hStrAppend (HANDLE h, unsigned char *str);

Appends a string to a handle that contains a string.

h is the handle to string to be lengthened.
str is the string to append to the handle h.
This routine may cause heap compression, and it throws "Error: memory" if there is not enough memory to expand the handle h.

This routine provides a way to store in the clipboard something you can't paste with DIAMOND+PASTE !
But: you need to take great care when you use this routine: use it only on handles your program allocated, because writing garbage into system handles usually crashes the calculator !

hStrAppend is normally a ROM_CALL (ROM_CALL 45F) available on AMS 2.xx only, but a wrapper makes the use of this function possible on any AMS version (take great care with very old AMS 1.00 for 92+, though).

hStrAppend is implemented as follows:

void hStrAppend (HANDLE h, unsigned char *str)
{
  unsigned char* str1;
  unsigned long lstr1, lstr, lbuf;
  str1 = HeapDeref(h);
  lstr1 = strlen((char *)str1);                 /* length of string in handle */
  lstr = strlen((char *)str);                   /* length of string to append */
  lbuf = lstr1 + lstr + 1;                      /* new space requirement */
  if (!HeapRealloc(h, lbuf))                    /* try to get new space */
    ER_throw(670);
  str1 = (unsigned char *)HeapDeref(h) + lstr1; /* point to end of original string */
  memcpy(str1, str, lstr+1);                    /* append new string */
}

Uses: HeapRealloc, memcpy, strlen
Used by: SP_Define, cmd_sinreg, ROM Call 0x45B


malloc_throw

malloc_throw Function* (tigcc.a)
alloc.h

void *malloc_throw (unsigned long Size);

Performs malloc, and throws an error if not successful.

malloc_throw calls malloc and throws a memory error if there is not enough memory. Otherwise, it returns a pointer to the allocated block.

Uses: malloc


malloc

malloc Function (ROM Call 0xA2)
alloc.h, stdlib.h

void *malloc (unsigned long Size);

Allocates a memory block.

malloc allocates a block of Size bytes from the memory heap. It allows a program to allocate memory explicitly as it's needed, and in the exact amounts needed. The heap is used for dynamic allocation of variable-sized blocks of memory. Many data structures, such as trees and lists, naturally employ heap memory allocation. On success, malloc returns a pointer to the newly allocated block of memory. If not enough space exists for the new block, it returns NULL. The contents of the block are left unchanged. If the argument Size is zero malloc also returns NULL. malloc is in fact an ANSI C alias for a TIOS routine originally called HeapAllocPtr (see description of it for more system info).

Note: As the TIOS memory manager assigns a handle to each allocated block, and as the total number of handles is limited, malloc is not good for algorithms where you need to allocate a large number of small blocks (as in implementations of linked lists which are usually seen in various C language books and tutorials). The same is true for all other TIOS memory management routines.

Uses: HeapAllocHigh, NeedStack
Used by: malloc_throw

See also: realloc, calloc, free, malloc_throw


PtrToHandle

PtrToHandle Function* (tigcc.a)
alloc.h

HANDLE PtrToHandle (void *Ptr);

Determines the handle associated with a block.

PtrToHandle returns the handle associated to the block pointed to by Ptr (or H_NULL if Ptr does not point within a block).
This routine will return meaningful results only if the block of memory was not moved (e.g. by heap compression) since the pointer was originally obtained.
The following program shows the difference between HeapPtrToHandle and PtrToHandle:

// Return the EStack handle.

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

#define RETURN_VALUE          // Return Pushed Expression
#define MIN_AMS 101           // Compile for AMS 1.01 or higher

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

// Main Function
void _main(void)
{
  push_END_TAG ();
  push_END_TAG ();
  // Outside all allocated blocks.
  push_shortint (HeapPtrToHandle((void *)1));
  // Strictly inside a block.
  push_shortint (HeapPtrToHandle((void *)estack_max_index));
  // Strictly inside a block, must be the same handle as estack_max_index.
  push_shortint (HeapPtrToHandle((void *)top_estack));
  // Beginning of a block.
  push_shortint (PtrToHandle(HeapDeref(1)));
  push_LIST_TAG ();
  push_END_TAG ();
  // Outside all allocated blocks.
  push_shortint (PtrToHandle((void *)1));
  // Strictly inside a block.
  push_shortint (PtrToHandle((void *)estack_max_index));
  // Strictly inside a block, must be the same handle as estack_max_index.
  push_shortint (PtrToHandle((void *)top_estack));
  // Beginning of a block.
  push_shortint (PtrToHandle(HeapDeref(1)));
  push_LIST_TAG ();
  push_LIST_TAG ();
}

Uses: HeapDeref, HeapSize

See also: HeapPtrToHandle


realloc_throw

realloc_throw Function* (tigcc.a)
alloc.h

void *realloc_throw (void *Ptr, unsigned long NewSize);

Performs realloc, and throws an error if not successful.

realloc_throw calls realloc and throws a memory error if there is not enough memory. Otherwise, it returns a pointer to the allocated block.

Uses: realloc


realloc

realloc Function* (tigcc.a)
alloc.h, stdlib.h

void *realloc (void *Ptr, unsigned long NewSize);

Reallocates allocated memory.

realloc attempts to shrink or expand the previously allocated block to NewSize bytes. The Ptr argument points to a memory block previously obtained by calling malloc, calloc, or realloc. It may also be NULL; in this case the function simply calls malloc.

realloc adjusts the size of the allocated block to NewSize, copying the contents to a new location if necessary (note that the block will not stay in high memory after the reallocation, but it will still remain locked; see other functions from this header file for more info). realloc returns the address of the reallocated block, which can be different than the address of the original block. If the block cannot be reallocated, realloc returns NULL.

Usually realloc keeps the current contents of the block intact; only the portion of the block which is newly allocated is not initialized and contains random content. However, unlike HeapRealloc, the function frees the block pointed to by Ptr if there was an error, so you cannot assume that the data pointed to by Ptr is still valid. This is done because there is no way to guarantee that Ptr is still valid after the heap compression which HeapRealloc tries to perform (this function uses HeapRealloc internally).

Note: realloc is introduced to increase compatibility with ANSI C. It is better to use the official TIOS function HeapRealloc, which uses a system of handles to memory blocks.

Uses: HeapAllocPtr, HeapFree, HeapRealloc, HeapUnlock, HLock
Used by: realloc_throw, atexit

See also: malloc, calloc, free, realloc_throw


H_NULL

H_NULL Constant
alloc.h, cert.h, dialogs.h, estack.h, menus.h, homescr.h, vat.h

#define H_NULL 0

A null-handle value.

H_NULL is a null-handle defined as a constant with value 0.


NULL

NULL Constant
alloc.h, args.h, cert.h, dialogs.h, events.h, flash.h, kbd.h, link.h, mem.h, menus.h, stddef.h, stdio.h, stdlib.h, string.h, vat.h, wingraph.h

#define NULL ((void *) 0)

A null-pointer value.

NULL is a null-pointer value, defined as a pointer to the address 0.


Bool

Bool Type (Enumeration)
alloc.h, args.h, cert.h, dialogs.h, error.h, estack.h, events.h, flash.h, graph.h, gray.h, intr.h, homescr.h, kbd.h, link.h, math.h, menus.h, statline.h, system.h, textedit.h, timath.h, vat.h, unknown.h, wingraph.h

enum Bool {FALSE, TRUE};

An enumeration to describe true or false values.

The enum Bool represents a boolean value, that is, either 'true' or 'false'. The constant FALSE equals 0; TRUE equals 1.


HANDLE

HANDLE Type (Scalar)
alloc.h, cert.h, dialogs.h, estack.h, events.h, flash.h, menus.h, homescr.h, system.h, textedit.h, vat.h, wingraph.h, unknown.h

typedef unsigned short HANDLE;

Represents a handle associated with an allocated memory block.

The HANDLE type is mainly used to manage dynamically allocated memory using functions from alloc.h, but a lot of functions from other header files take instances of this type as parameters.

A handle points to a word-aligned block of memory, whose current address can be retrieved using HeapDeref.

See also: HeapAlloc, HeapFree, HLock, HeapUnlock, HeapDeref


HeapWalkCmds

HeapWalkCmds Type (Enumeration)
AMS 2.00 or higher alloc.h

enum HeapWalkCmds {H_WALK_VERIFY = 0, H_WALK_STATUS = 1, H_WALK_DUMP = 2, H_WALK_SYM = 3};

An enumeration describing the valid parameters for HeapWalk.


size_t

size_t Type (Scalar)
alloc.h, cert.h, flash.h, link.h, mem.h, stddef.h, stdio.h, stdlib.h, string.h, textedit.h

typedef unsigned long size_t;

A type to define sizes of strings and memory blocks.

size_t is a type proposed by ANSI C for defining sizes of strings and memory blocks.


args.h

args.h Header File
Header File Index

Routines for retrieving arguments passed to the program

Functions
ArgCount
Returns the number of arguments passed to the program.
EX_getArg
Returns a pointer to the nth argument.
EX_getBCD
Gets the nth floating point argument.
GetArgType
Returns the type of the current argument.
GetFloatArg
Returns the current argument of floating point type.
GetIntArg
Returns the current argument of integer type.
GetLongLongArg
Returns the current argument of double-long integer type.
GetStrnArg
Returns the current argument of string type.
GetSymstrArg
Returns a pointer to the terminating zero byte of the current argument of string type.
InitArgPtr
Initializes a pointer to the first argument passed to the program.
RemainingArgCnt
Returns the remaining number of arguments passed to the program.
SkipArg
Skips the current argument.
Global Variables
top_estack
Points to the top of the expression stack.
Constants
NULL
A null-pointer value.
Predefined Types
bcd
Represents the internal organization of floating point numbers in the format recognized by the TIOS.
Bool
An enumeration to describe true or false values.
CESI
Represents a pointer to a constant expression.
ESI
Represents an index of a value on the TIOS expression stack.
ESQ
Represents a quantum within an expression.
EStackIndex
Represents an index of a value on the TIOS expression stack.
Quantum
Represents a quantum within an expression.
SYM_STR
Represents a pointer to the terminating zero byte of a string.
Tags
An enumeration to describe types of entries on the expression stack.
ti_float
An alias for the standard ANSI float type.

Note: The header file estack.h contains a much more powerful set of functions to manipulate the expression stack.


ArgCount

ArgCount Function (Macro)
args.h

unsigned short ArgCount (void);

Returns the number of arguments passed to the program.

ArgCount returns the number of arguments passed to the called program. It is a simple macro which calls TIOS function RemainingArgCnt.

Uses: RemainingArgCnt, top_estack

See also: RemainingArgCnt


EX_getArg

EX_getArg Function (ROM Call 0xBE)
args.h

ESI EX_getArg (short n);

Returns a pointer to the nth argument.

EX_getArg is TIOS function which may be useful if you want to access arguments in non_sequential order. EX_getArg returns a pointer to the argument which ordinal number is n (which may be later processed using GetIntArg etc.). Arguments are numbered from zero (i.e. 0, 1, 2, ... N-1 where N is the total number of arguments). Note that when n = N, EX_getArg returns NULL, and when n > N, EX_getArg throws an error, so it is good idea to check in advance the total number of arguments using ArgCount.

Uses: next_expression_index, top_estack
Used by: EX_getBCD


EX_getBCD

EX_getBCD Function (ROM Call 0xBF)
args.h

short EX_getBCD (short n, float *dest);

Gets the nth floating point argument.

EX_getBCD is a somewhat limited TIOS function. It first calls EX_getArg passing n to it. Then, if the argument pointed to by the result of EX_getArg is not a floating point number, EX_getBCD returns FALSE, otherwise it stores the floating point value to the variable pointed to by dest and returns TRUE.

Uses: EX_getArg, estack_to_float


GetArgType

GetArgType Function (Macro)
args.h

unsigned char GetArgType (CESI ap);

Returns the type of the current argument.

GetArgType returns a one-byte value which determines the type of the current argument (pointed to by ap). There are many types of arguments: strings, integers (positive or negative), fractions, floats, symbols, various algebraic expressions, lists, matrices, etc. The enum Tags defines a lot of constants: the most commonly used in argument lists are STR_TAG, POSINT_TAG, NEGINT_TAG, FLOAT_TAG, POSFRAC_TAG, ENDFRAC_TAG, COMPLEX_TAG, LIST_TAG and END_TAG. They represent respectively a string, a positive integer, a negative integer, a floating point value, a positive fraction, a negative fraction, a complex number, a beginning of the list structure and an end-of-list marker (which also has meaning "no more arguments"). Any values except these need to be regarded as "an expression": you need to handle them "by hand" (of course, if you know how). See InitArgPtr for an example of usage.

Note: You can use SkipArg to bypass the argument which you don't know how to handle (or, which you don't want to handle for any reason).


GetFloatArg

GetFloatArg Function (Macro)
args.h

float GetFloatArg (CESI &ap);

Returns the current argument of floating point type.

GetFloatArg is a macro which returns the current floating point argument (pointed to by ap) and modifies ap to point to the next argument in the argument list. So, each successive time GetFloatArg is used, it returns the next argument in the argument list. Note that GetFloatArg assumes that the current argument is a floating point value (not an integer). This may be checked using GetArgType. If this is not true, the result of GetFloatArg is unpredictable.

Uses: memcpy

See also: estack_number_to_Float


GetIntArg

GetIntArg Function (Macro)
args.h

unsigned long GetIntArg (CESI &ap);

Returns the current argument of integer type.

GetIntArg is a macro which returns the current integer argument (pointed to by ap) and modifies ap to point to the next argument in the argument list. So, each successive time GetIntArg is used, it returns the next argument in the argument list. If the argument is a negative number (check the sign using GetArgType), GetIntArg returns its absolute value. See InitArgPtr for an example of usage. Note that GetIntArg assumes that the current argument IS an integer, either positive or negative (this may be checked using GetArgType). If this is not true, the result of GetIntArg is unpredictable.

If the current argument type is a fraction, do the following to pick it:

numerator = GetIntArg (ap);
ap++;
denominator = GetIntArg (ap);
i.e. pick two integers, with increasing argument pointer between two picks.

Note: It is not recommended to do something like
a = GetIntArg (top_estack);
It works fine sometimes, but not always. GetIntArg is a function-looking macro, with changes the value of its actual argument. So, if you write the statement mentioned above, you will also change the value of TIOS system variable top_estack, which is not always a good idea. So, I strictly recommend using an auxiliary variable, like in the following example:
ESI argptr = top_estack;
...
a = GetIntArg (argptr);
Using this method, you will avoid unexpected changes of top_estack.

See also: GetLongLongArg


GetLongLongArg

GetLongLongArg Function (Macro)
args.h

unsigned long long GetLongLongArg (CESI &ap);

Returns the current argument of double-long integer type.

GetLongLongArg works like GetIntArg, but returns a double-long integer.

See also: GetIntArg


GetStrnArg

GetStrnArg Function (Macro)
args.h

const char *GetStrnArg (CESI &ap);

Returns the current argument of string type.

GetStrnArg is a macro which returns the current string argument (pointed to by ap) and modifies ap to point to the next argument in the argument list. So, each successive time GetStrnArg is used, it returns the next argument in the argument list. See InitArgPtr for an example of usage. Note that GetStrnArg assumes that the current argument IS a string (this may be checked using GetArgType). If this is not true, the effect of GetStrnArg is unpredictable.


GetSymstrArg

GetSymstrArg Function (Macro)
args.h

SYM_STR GetSymstrArg (CESI &ap);

Returns a pointer to the terminating zero byte of the current argument of string type.

GetSymstrArg does the same task as GetStrnArg but returns a pointer to the terminating zero byte of the string, instead of a pointer to the first byte of the string. This function is implemented because nearly all functions for TIOS VAT handling need just the pointer to the terminating byte of the string. As the arguments are stored in memory as strings which are bounded with zero bytes from both sides, the result of GetSymstrArg may be directly passed to TIOS VAT routines. See vat.h for more info.


InitArgPtr

InitArgPtr Function (Macro)
args.h

void InitArgPtr (CESI &ap);

Initializes a pointer to the first argument passed to the program.

InitArgPtr is a macro which initializes ap (which is a pointer of type ESI) to point to the first argument passed to the assembly program. Principally, calling

InitArgPtr (argptr);
is equal to doing
argptr = top_estack;
See top_estack for more info.

InitArgPtr must be used before the first call to GetStrnArg etc. Here is an example of a program which reads string or integer arguments passed to it, and displays them on the screen, one by one (called "Argument Test"):
// An example of passing arguments to C program
// Try this program calling argtest(arg1,arg2,...)

#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#define MIN_AMS 100

#include <graph.h>
#include <printf.h>
#include <kbd.h>
#include <args.h>

void _main(void)
{
  ESI argptr;
  int argtype;
  long num;
  InitArgPtr (argptr);
  while ((argtype = GetArgType (argptr)) != END_TAG)
    {
      DrawStr (0, 30, "                          ", A_REPLACE);
      if (argtype == STR_TAG)
        DrawStr (0, 30, GetStrnArg (argptr), A_REPLACE);
      else if (argtype == POSINT_TAG || argtype == NEGINT_TAG)
        {
          num = GetIntArg (argptr);
          if (argtype == NEGINT_TAG)
            num = -num;
          printf_xy (0, 30, "%ld", num);
        }
      else
        {
          DrawStr (0, 30, "Wrong arg type!", A_REPLACE);
          ngetchx ();
          break;
        }
      ngetchx ();
    }
}
If the name of this program is example.89z, try to call it on the calculator using
example ("strarg1", 123, -12, "strarg2")
to see how it works in practice.

Note: I used notation "&ap" in the prototype description, although passing by reference does not exist in ordinary C (only in C++). However, this macro is implemented in such a way that it simulates "passing by reference".

Uses: top_estack


RemainingArgCnt

RemainingArgCnt Function (ROM Call 0x3C3)
AMS 1.01 or higher args.h

unsigned short RemainingArgCnt (CESI ap);

Returns the remaining number of arguments passed to the program.

RemainingArgCnt returns the number of remaining arguments passed to the called program, i.e. the number of arguments which are not yet picked up. It is a simple alias for the TIOS function remaining_element_count.

Uses: remaining_element_count
Used by: ArgCount

See also: ArgCount


SkipArg

SkipArg Function (Macro)
args.h

void SkipArg (CESI &ap);

Skips the current argument.

SkipArg is a macro which modifies ap to point to the next argument in the argument list, regardless of its type. Note that this function must not be called if GetArgType returns END_TAG, i.e. if there is no more arguments. Else, an error will be thrown.

Note: SkipArg is implemented by calling TIOS function next_expression_index.

Uses: next_expression_index


top_estack

top_estack Variable (ROM Call 0x109)
args.h, estack.h

ESI top_estack;

Points to the top of the expression stack.

The global variable top_estack points to the top (i.e. the last byte) of the expression stack. Strictly speaking, in "nostub" mode it is not a real variable but smart macro, although it works like it is a variable. The expression stack is the place in the memory where TI keeps expressions during evaluation. All statements are tokenized before being executed (interpreted). Instructions are reduced to (byte sized) quanta and parsed into Reverse Polish Notation (RPN). This is a common technique in interpreted languages. Expressions, functions, etc. are all stored in RPN form, to allow for efficient operation of the expressions stack. See below for more details about organization of the expression stack.

The actual processing of all expressions is done via the expression stack. The position in the stack is given by top_estack. Pushing a value appends it to the expression stack and increments top_estack. When a expression is interpreted, expressions are reduced, and executed as far as possible. Whatever remains on the stack is the result, this may then be stored or processed later.

When a file is interpreted the end of the variable is found and it is processed as a separate expression stack. It is then processed recursively, producing a simplified version on the real expression stack. Expressions are therefore interpreted from the top (high memory) recursively.

As an artefact of expressions processing mechanism, the arguments of the called program are kept also on the expression stack. It grows upwards, and the last argument is stored first. After the assembly program is called, the image of the expression stack is as follows:

  • The first byte (i.e. the byte with the lowest address) on the stack is END_TAG (0xE5).
  • Then, a argument list follows, starting from the last argument up to the first argument. So, top_estack points to the last byte of the first argument.
Each string entry on the expression stack is stored as follows (from lower to higher addresses):
  • One zero byte (starting tag);
  • Content of the string;
  • Terminating zero byte;
  • Byte STR_TAG (0x2D).
Each integer entry is stored as follows:
  • Bytes of the number in little endian format (i.e. the lowest byte is stored first); the number of bytes varies depending of the size of the number;
  • A byte which represents the number of the bytes which made the number (note that zero has zero-byte length);
  • Byte POSINT_TAG (0x1F) or NEGINT_TAG (0x20), depending whether the number is positive or negative (for negative numbers, previous bytes contain the absolute value).
Each fraction entry is stored as follows:
  • Bytes of the denominator in little endian format (i.e. the lowest byte is stored first); the number of bytes varies depending of the size of the number;
  • A byte which represents the number of the bytes which made the denominator;
  • Bytes of the numerator in little endian format;
  • A byte which represents the number of the bytes which made the numerator;
  • Byte POSFRAC_TAG (0x21) or NEGFRAC_TAG (0x22), depending whether the fraction is positive or negative (for negative fractions, previous bytes contain absolute values).
Each floating point entry is stored as follows:
  • Only first 9 bytes of the content of the floating point value are stored (instead of 10), because TIOS always rounds floating point values up to 14 significant digits before pushing them on expression stack (see bcd structure for more information about the internal organization of floating point values);
  • The last byte is FLOAT_TAG (0x23).
If the entry is complex number, real part is stored first (which can be integer, float, fraction, etc.), then imaginary part. COMPLEX_TAG (0x9D) is stored after them, so if the current argument type is complex, decrease the argument pointer by one, then first read imaginary part, then real part separately.

If the entry is composite (i.e. if it is a list or a matrix), the first byte is end_of_list marker (byte END_TAG or 0xE5), then follow each element of the list in reverse order (starting from the last element), and the last byte is LIST_TAG (0xD9). Now, you surely have an idea how you can pick up elements from the list. Note that a matrix is a "list of lists".

Signed zeros (POSITIVE_ZERO and NEGATIVE_ZERO) are represented as fractions +0/1 and -0/1.

Variable names are stored exactly like strings without terminating STR_TAG (i.e. it is a sequence of letters bounded with two zero bytes), so "variable" tag is just a zero byte. There is an exception: one-letter variables have unique one-byte tags (see Tags for more info. Also, note that variable names are always stored with lowercase letters. Variables whose names ends with an underscore are assumed to be complex, and variables whose names starts with an underscore are assumed to represent physical units.

Expressions are stored in RPN (Reverse Polish Notation) form (also known as postfix form). So, function calls like func(arg1,arg2,...argn) are stored as sequence

argn ... arg2 arg1 func_tag

and terms like arg1 operator arg2 are stored as arg1 arg2 operator_tag or arg2 arg1 operator_tag, depending on the concrete operator. The situation is analogous for unary operators. Note that a "pointer to an expression" is a pointer to the last byte of the expression! When a function (or operator) has variable number of arguments, END_TAG is used to indicate "no more arguments". See Tags for complete list of various tags. This will be illustrated with some examples:

Algebraic form: | integrate (e^(x^2), x, 1, 2)
RPN form: | 2 1 x 2 x ^ e ^ integrate
Sequence of bytes: | [02 01 1F] [01 01 1F] [08] [02 01 1F] [08] [93] [25] [93] [C4]

Algebraic form: | sum (sqrt (1 + x), x, 0, a) (where sum is actually the capital sigma)
RPN form: | a 0 x x 1 + sqrt sum
Sequence of bytes: | [0B] [00 1F] [08] [08] [01 01 1F] [8B] [51] [BA]

Algebraic form: | a + b + a - b + (a + b) * (a - b) -> a
RPN form: | a b + a + b - a b + a b - * + a ->
Sequence of bytes: | [0B] [0C] [8B] [0B] [8B] [0C] [8D] [0B] [0C] [8B] [0B] [0C] [8D] [8F] [8B] [0B] [80]

Algebraic form: | {{1, 2}, {3, 4}}
RPN form: | END_TAG END_TAG 4 3 LIST_TAG END_TAG 2 1 LIST_TAG LIST_TAG
Sequence of bytes: | [E5] [E5] [04 01 1F] [03 01 1F] [D9] [E5] [02 01 1F] [01 01 1F] [D9] [D9]

Algebraic form: | my_func (a, b, c)
RPN form: | END_TAG c b a my_func USERFUNC_TAG
Sequence of bytes: | [E5] [0D] [0C] [0B] [00 6D 79 5F 66 75 6E 63 00] [DA]

To perform some algebraic transformations on more unique way, expressions should be transformed into an equivalent form called "internal canonic form". In such form, for example, all constants are always in front of variables, e.g. 'x*3' and 'x+3' becomes '3*x' and '3+x' (although the second example will be printed as 'x+3'). Also, expressions like 'x/y' or 'x-y' in internal canonic form do not contain subtractions and divisions. As the parameter list (when the program is called from TI-Basic) is always in internal canonic form, such expressions will never be observed as-is in parameter lists etc. because they will be converted before passing them to the program. A lot of functions for algebraic manipulations automatically convert the expression in the internal canonic form, but when this is not true, you can always force the conversion using explicit call to push_internal_simplify function. Note that the reverse conversion (i.e. back from the canonic form into a regular form) is performed anytime when you try to print out the expression. Here is the list of the most common transformations which appears during the transformation into the internal canonic form:

Expression | Standard canonic form
-x | (-1)*x
x-y | x+y*(-1)
x/y | x*y^(-1)
e^x | exp(x)
x^y exp(ln(x)*y)
[ except when "y" is an integer or a fraction ]
e | exp(1)
sqrt(x) | x^(1/2)
log(x) | ln(x)*(ln(10)^(-1))
sin(x) trig(x,0)
[ assuming "radian" mode; for "trig" function, see SINCOS_TAG ]
cos(x) | trig(x,1)
tan(x) | trig(x,0)*trig(x,1)^(-1)
sinh(x) | exp(x)*(1/2)+exp(x)^(-1)*(-1/2)
cosh(x) | exp(x)*(1/2)+exp(x)^(-1)*(1/2)
tanh(x) | (exp(x)^2+1)^(-1)*(exp(x)^2+(-1))
x xor y | (not x and y) or (x and not y)

Mode dependent calculations are performed by converting expressions to a specific format, i.e. for trigonometric functions all values are converted to radians before passing them to radian trigonometric functions.

A variable may consist of multiple expressions, these are separated by several special quanta: NEXTEXPR_TAG and NEWLINE_TAG. The last expression is marked with ENDSTACK_TAG. See MULTI_EXPR.

If everything mentioned above is not so clear for you, compile and run the following example (called "Print EStack"):
// Print bottom_estack and top_estack

#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

// Main Function
void _main(void)
{
  ClrScr ();
  printf_xy (0, 40, "Bottom = 0x%lp", bottom_estack);
  printf_xy (0, 50, "Top = 0x%lp", top_estack);
  ngetchx ();
}
Run this program in VTI and pass to it parameters as you want. top_estack will be shown on the screen. During waiting for a keypress, enter the debugger and look at the addresses shown, to see how parameters are stored.

Used by: can_be_approxed, check_estack_size, compare_complex_magnitudes, delete_between, deleted_between, did_push_cnvrt_Float_to_integer, index_below_display_expression_aux, is_antisymmetric, is_symmetric, map_tail, map_tail_Int, next_expression_index, NG_graphESI, Parse2DExpr, Parse2DMultiExpr, push_between, push_expr_quantum, push_expr2_quantum, push_Float, push_Float_to_nonneg_int, push_Float_to_rat, push_internal_simplify, push_offset_array, push_parse_text, push_quantum, push_quantum_pair, push_round_Float, push_transpose_aux, push_ushort_to_integer, reset_estack_size, should_and_did_push_approx_arg2, TokenizeSymName, HeapAllocESTACK, ArgCount, EX_getArg, InitArgPtr, cmd_blddata, cmd_circle, cmd_custom, cmd_dialog, cmd_disp, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_endfor, cmd_endwhile, cmd_fill, cmd_for, cmd_get, cmd_if, cmd_ifthen, cmd_input, cmd_inputstr, cmd_linetan, cmd_local, cmd_newdata, cmd_newplot, cmd_output, cmd_passerr, cmd_pause, cmd_popup, cmd_prompt, cmd_randseed, cmd_request, cmd_shade, cmd_sinreg, cmd_slpline, cmd_sorta, cmd_sortd, cmd_toolbar, cmd_try, cmd_while, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_coldim, push_colnorm, push_comb, push_comdenom, push_conj, push_cosh, push_cross_product, push_csolve, push_cumsum, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_diag, push_dimension, push_dotproduct, push_eigvc, push_eigvl, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_im, push_integer_lcm, push_integer_part, push_integer_quotient, push_integer_remainder, push_is_prime, push_left, push_lim, push_list_to_mat, push_ln, push_log10, push_matnorm, push_max, push_max1, push_max2, push_mean, push_median, push_mid, push_min, push_min1, push_min2, push_mod, push_mrowadd, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_part, push_perm, push_phase, push_pttest, push_pxltest, push_r_cis, push_rand, push_randmat, push_randnorm, push_randpoly, push_re, push_rec_to_angle, push_red_row_ech, push_right, push_rotate, push_round, push_row_echelon, push_rowadd, push_rowdim, push_rownorm, push_rowswap, push_sequence, push_shift, push_sign, push_simult, push_sin2, push_sinh, push_solve, push_stddev, push_str_to_expr, push_string, push_submat, push_summation, push_switch, push_tan, push_tanh, push_unitv, push_variance, push_when, push_zeros, did_push_to_polar, push_and, push_assignment, push_degrees, push_dot_exponentiate, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_indir_name, push_less_than, push_less_than_or_equals, push_list_plus, push_list_times, push_matrix_product, push_negate, push_not, push_not_equals, push_or, push_product, push_radians, push_ratio, push_substitute_no_simplify, push_substitute_simplify, push_substitute_using_such_that, push_sum, push_to_cylin, push_to_sphere, push_xor, VarNew, VarOpen, VarSaveAs, EV_defaultHandler, handleRclKey, handleVarLinkKey, GR3_paint3d, GR3_xyToWindow, HomeExecute, HomePushEStack, HS_popEStack, getcalc, OSLinkCmd, sendcalc, atof, add_to_top, and_onto_top, are_units_consistent, compare_numbers, cpt_gr_fun, cpt_gr_param, cpt_gr_polar, de_initRes, de_loop, did_map_aggregate_arg, did_push_approx_inflection_point, did_push_divide_units, did_push_lincf, divide_top, dv_create_graph_titles, EQU_getNameInfo, ForceFloat, get_lb, get_list_indices, get_matrix_indices, get_ub, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_ck_solvergraph, gr_execute_de, gr_execute_seq, GR_Pan, GR3_addContours, GraphOrTableCmd, GT_CalcDepVals, GT_PrintCursor, has_different_variable, index_if_pushed_binomial_info, index_if_pushed_qquad_info, InitDEMem, InitTimeSeq, is_equivalent_to, is_negative, is_never0, is_nonnegative, is_nonpositive, is_positive, is_real, is_term_improper, or_onto_top, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_div_dif_1f, push_float_qr_fact, push_format, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_minus_recip_of_quantum, push_mrow_aux, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_pi_on_quantum, push_poly_deg_in_var_or_kernel, push_poly_qr, push_quantum_as_nonnegative_int, push_quantum_pair_as_pos_frac, push_reciprocal, push_reciprocal_of_quantum, push_simplify, push_simplify_statements, push_sq_matrix_to_whole_number, push_standardize, push_symbolic_qr_fact, push_trig, push_user_func, push_var, push_zero_partial_column, raise_to_top, Regraph, replace_top_with_post_simplified, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, run_one_seq, seqWebInit, setup_unit_system, SP_Define, spike_geo_titles, spike_in_editor, spike_optionD, spike_titles_in_editor, store_func_def, store_to_subscripted_element, subtract_from_top, time_loop, times_top, tokenize_if_TI_92_or_text, TokenizeName, VarStoreLink, FolderDel, FolderRename, HSymDel, SymFindFolderName, VarRecall, ROM Call 0x45B, ROM Call 0x468, ROM Call 0x46F, ROM Call 0x47F, ROM Call 0x480, cmd_lu_fact, cmd_qr_fact, ROM Call 0x48D, ROM Call 0x494, ROM Call 0x495, push_spher_vector, push_to_dd, push_to_dms, push_subscripted_element, ROM Call 0x4E6, push_exact0, push_exact_minus1, push_exact1, DateAndTime_SetDlg, ROM Call 0x606

See also: bottom_estack, estack_max_index


bcd

bcd Type (Structure)
args.h, estack.h, math.h, timath.h, values.h

typedef struct {
unsigned short exponent;
unsigned long long mantissa;
} bcd __attribute__((__may_alias__));

Represents the internal organization of floating point numbers in the format recognized by the TIOS.

The bcd type represents the internal organization of floating point numbers in the format recognized by the TIOS (the so-called SMAP II BCD format). Note that long long is not a typing error: it is a GNU C extension for representing very long integers (8-byte integers in this implementation).

Here will be given the exact internal organization of floating point numbers. Magnitude of every real number (except zero) can be represented as m*10^e, where e (so-called exponent) is an integer, and m (so-called mantissa) is a real number which satisfies condition 1 <= m < 10 (this is somewhat different convention than used in frexp10 function which is derived from ANSI standard). e is stored in the exponent field, and m in mantissa field of the bcd structure. Details of storing format are given below. You don't need to know these details, but they are given here for anybody who needs to know more about floats on TI.

Field exponent of the bcd structure contains e+0x4000 if the number is positive, or e+0xC000 if the number is negative. So, the most significant bit of exponent is the sign of the number, but the format is not 2-complement code (more precise, it is sign_and_magnitude_0x4000_biased code). The exponent is NOT bcd-coded (unlike the mantissa). Legal range for the e is from -16383 to +16382 (values -16384 and +16383 are reserved for some special values), although many math functions are not very happy with extremely small or extremely big exponents. Keep your exponents in the range from -999 to +999.

The mantissa is stored in BCD code. As the mantissa satisfies the condition 1 <= m < 10, it can be represented as m1.m2m3m4... where m1, m2 etc. are digits (0-9). TIOS first truncates the mantissa up to 16 digits, or adds trailing zeros on the end of the mantissa up to 16 digits if it is shorter than 16 digits. Then, it stores the integer number m1m2m3...m16 in mantissa field of the bcd structure using packed BCD code (each digit in 4 bits).

Everything will be more clear on a concrete example. Look the number 379.25. It can be written as 3.7925*10^2. So, e is 2, and m is 3.7925. As the number is positive, exponent will contain 0x4000+2 = 0x4002. As the mantissa has less than 16 digits, it must be padded to 3.792500000000000. So, mantissa will contain the integer 3792500000000000, i.e. it will contain 0x3792500000000000 (note the strong correspodence between hex numbers and bcd coded numbers: they have the same digits). So, to assign the value 379.25 to the variable a of type bcd, you can use a.exponent = 0x4002 and a.mantissa = 0x3792500000000000. Standard ANSI types float, double and long double (all of them are the same in TIGCC) are internally organized exactly at the same way in TIGCC, except that from the aspect of the compiler, they are scalars, and bcd is a structure, so you cannot simply cast float to bcd and vice versa. For this purpose, use functions (more precise macros) float_to_bcd, bcd_to_float and bcd_var.

Note that due to the condition 1 <= m < 10, the mantissa must be normalized (which means that the first digit of the mantissa must not be zero). The consequence is that mantissa field must always be greater or equal to 0x1000000000000000. You can construct (artifically) structures in which this condition is not satisfied. Some functions will work well with such (unnormalized) numbers, but many of them will not work correctly. So, avoid creating of such illegal values: any unnormalized number may be represented in normalized format. Anyway, don't worry about it: all numbers written using "normal" methods are always normalized: you can create unnormalized numbers only intentionally by direct accessing to mantissa part of a bcd structure.


CESI

CESI Type (Pointer)
args.h, bascmd.h, basfunc.h, basop.h, estack.h, link.h, vat.h, unknown.h

typedef const ESQ *CESI;

Represents a pointer to a constant expression.

The type CESI acts like ESI, but the value pointed to by it may have to be constant. For example, it may be a SYM_STR whose contents are stored at a fixed place in the program.


ESI

ESI Type (Pointer)
args.h, bascmd.h, basfunc.h, basop.h, estack.h, graphing.h, link.h, vat.h, unknown.h

typedef ESQ *ESI;

Represents an index of a value on the TIOS expression stack.

The type ESI is an "expression stack index", which is, in fact, a pointer to a tag byte on the TIOS expression stack.

See top_estack and Tags for more info about the expression stack.


ESQ

ESQ Type (Scalar)
args.h, bascmd.h, basfunc.h, basop.h, estack.h, dialogs.h, homescr.h, link.h, vat.h, unknown.h

typedef unsigned char ESQ;

Represents a quantum within an expression.

ESQ represents a quantum (the smallest meaningful unit) of an expression. It can be a tag from the Tags enum, or any other byte value.


EStackIndex

EStackIndex Type (Pointer)
args.h, bascmd.h, basfunc.h, basop.h, estack.h

#define EStackIndex ESI

Represents an index of a value on the TIOS expression stack.

EStackIndex is a synonym for ESI.


Quantum

Quantum Type (Scalar)
args.h, bascmd.h, basfunc.h, basop.h, estack.h

#define Quantum ESQ

Represents a quantum within an expression.

Quantum is a synonym for ESQ.


SYM_STR

SYM_STR Type (Pointer)
args.h, bascmd.h, basfunc.h, basop.h, estack.h, link.h, vat.h, unknown.h

typedef CESI SYM_STR;

Represents a pointer to the terminating zero byte of a string.

The type SYM_STR is in fact the same as CESI. It represents a string created with the SYMSTR macro. This type of string is usually used in expressions on the expression stack, or in functions from vat.h or bascmd.h.


Tags

Tags Type (Enumeration)
args.h, estack.h

enum Tags {...};

An enumeration to describe types of entries on the expression stack.

This enum is very large, as there are a lot of various entries. See top_estack for more info about how entries on the expression stack are organized. Here is a complete list of tags with their values in hexadecimal notation, along with their meaning written in RPN:

00 | VAR_NAME_TAG | variable name (with more than one letter): '\0' var_name '\0'
01 | _VAR_Q_TAG | variable q (but not used - 1B is used normally)
02 | VAR_R_TAG | variable r
03 | VAR_S_TAG | variable s
04 | VAR_T_TAG | variable t
05 | VAR_U_TAG | variable u
06 | VAR_V_TAG | variable v
07 | VAR_W_TAG | variable w
08 | VAR_X_TAG | variable x
09 | VAR_Y_TAG | variable y
0A | VAR_Z_TAG | variable z
0B | VAR_A_TAG | variable a
0C | VAR_B_TAG | variable b
0D | VAR_C_TAG | variable c
0E | VAR_D_TAG | variable d
0F | VAR_E_TAG | variable e
10 | VAR_F_TAG | variable f
11 | VAR_G_TAG | variable g
12 | VAR_H_TAG | variable h
13 | VAR_I_TAG | variable i
14 | VAR_J_TAG | variable j
15 | VAR_K_TAG | variable k
16 | VAR_L_TAG | variable l
17 | VAR_M_TAG | variable m
18 | VAR_N_TAG | variable n
19 | VAR_O_TAG | variable o
1A | VAR_P_TAG | variable p
1B | VAR_Q_TAG | variable q
1C | EXT_SYSTEM_TAG | system token (a byte before the tag identifies a system variable, see SysvarTags)
1D | ARB_REAL_TAG | arbitrary real number @xxx (byte before the tag determines xxx)
1E | ARB_INT_TAG | arbitrary integer number @nxxx (byte before the tag determines xxx)
1F | POSINT_TAG | positive integer tag
20 | NEGINT_TAG | negative integer tag
21 | POSFRAC_TAG | positive fraction tag
22 | NEGFRAC_TAG | negative fraction tag
23 | FLOAT_TAG | floating point tag
23 | BCD_TAG | floating point tag (alias tag name)
24 | PI_TAG | constant p
25 | EXP_TAG | constant e
26 | IM_TAG | constant i
27 | NEGINFINITY_TAG | -¥
28 | INFINITY_TAG | ¥
29 | PN_INFINITY_TAG | +/- ¥
2A | UNDEF_TAG | undef
2B | FALSE_TAG | false
2C | TRUE_TAG | true
2D | STR_TAG | string tag: '\0' string '\0' STR_TAG
2E | NOTHING_TAG | allows missing terms in expressions
2F | ACOSH_TAG | expr acosh
30 | ASINH_TAG | expr asinh
31 | ATANH_TAG | expr atanh
32 | ASECH_TAG | expr asech (AMS 2.08 or higher)
33 | ACSCH_TAG | expr acsch (AMS 2.08 or higher)
34 | ACOTH_TAG | expr acoth (AMS 2.08 or higher)
35 | COSH_TAG | expr cosh
36 | SINH_TAG | expr sinh
37 | TANH_TAG | expr tanh
38 | SECH_TAG | expr sech (AMS 2.08 or higher)
39 | CSCH_TAG | expr csch (AMS 2.08 or higher)
3A | COTH_TAG | expr coth (AMS 2.08 or higher)
3B | ACOS_TAG | expr acos
3C | ASIN_TAG | expr asin
3D | ATAN_TAG | expr atan
3E | ASEC_TAG | expr asec (AMS 2.08 or higher)
3F | ACSC_TAG | expr acsc (AMS 2.08 or higher)
40 | ACOT_TAG | expr acot (AMS 2.08 or higher)
41 | RACOS_TAG | expr arcos (used only internally)
42 | RASIN_TAG | expr arsin (used only internally)
43 | RATAN_TAG | expr artan (used only internally)
44 | COS_TAG | expr cos
45 | SIN_TAG | expr sin
46 | TAN_TAG | expr tan
47 | SEC_TAG | expr sec (AMS 2.08 or higher)
48 | CSC_TAG | expr csc (AMS 2.08 or higher)
49 | COT_TAG | expr cot (AMS 2.08 or higher)
4A | ITAN_TAG | expr tan (used only internally)
4B | ABS_TAG | expr abs
4C | ANGLE_TAG | expr angle
4D | CEILING_TAG | expr ceiling
4E | FLOOR_TAG | expr floor
4F | INT_TAG | expr int
50 | SIGN_TAG | expr sign
51 | SQRT_TAG | expr Ö
52 | EXPF_TAG | expr e^
53 | LN_TAG | expr ln
54 | LOG_TAG | expr log
55 | FPART_TAG | expr fPart
56 | IPART_TAG | expr iPart
57 | CONJ_TAG | expr conj
58 | IMAG_TAG | expr imag
59 | REAL_TAG | expr real
5A | APPROX_TAG | expr approx
5B | TEXPAND_TAG | expr tExpand
5C | TCOLLECT_TAG | expr tCollect
5D | GETDENOM_TAG | expr getDenom
5E | GETNUM_TAG | expr getNum
5F | ERROR_TAG | expr _ERROR_ (used only internally)
60 | CUMSUM_TAG | list cumSum
61 | DET_TAG | mat det
62 | COLNORM_TAG | mat colNorm
63 | ROWNORM_TAG | mat rowNorm
64 | NORM_TAG | mat norm
65 | MEAN_TAG | list mean
66 | MEDIAN_TAG | list median
67 | PRODUCT_TAG | list product
68 | STDDEV_TAG | list stdDev
69 | SUM_TAG | list sum
6A | VARIANCE_TAG | list variance
6B | UNITV_TAG | vec unitV
6C | DIM_TAG | mat dim
6D | MAT2LIST_TAG | mat mat>list
6E | NEWLIST_TAG | no_of_elements newList
6F | RREF_TAG | mat rref
70 | REF_TAG | mat ref
71 | IDENTITY_TAG | integer identity
72 | DIAG_TAG | mat diag
73 | COLDIM_TAG | mat colDim
74 | ROWDIM_TAG | mat rowDim
75 | TRANSPOSE_TAG | mat T
76 | FACTORIAL_TAG | expr !
77 | PERCENT_TAG | expr %
78 | RADIANS_TAG | expr r
79 | NOT_TAG | expr not
7A | MINUS_TAG | expr _negative_
7B | VEC_POLAR_TAG | mat _polar_vector_ (mat is assumed to be [[r,q]])
7C | VEC_CYLIND_TAG | mat _cylind_vector_ (mat is assumed to be [[r,q,z]])
7D | VEC_SPHERE_TAG | mat _sphere_vector_ (mat is assumed to be [[r,q,F]])
7E | START_TAG | ( (used only internally, don't use it)
7F | ISTORE_TAG | expr var -> (internal version: don't use)
80 | STORE_TAG | expr var ->
81 | WITH_TAG | condition expr |
82 | XOR_TAG | expr2 expr1 xor
83 | OR_TAG | expr2 expr1 or
84 | AND_TAG | expr2 expr1 and
85 | LT_TAG | expr2 expr1 <
86 | LE_TAG | expr2 expr1 <=
87 | EQ_TAG | expr2 expr1 =
88 | GE_TAG | expr2 expr1 >=
89 | GT_TAG | expr2 expr1 >
8A | NE_TAG | expr2 expr1 /=
8B | ADD_TAG | expr1 expr2 +
8C | ADDELT_TAG | expr1 expr2 .+
8D | SUB_TAG | expr1 expr2 -
8E | SUBELT_TAG | expr1 expr2 .-
8F | MUL_TAG | expr1 expr2 *
90 | MULELT_TAG | expr1 expr2 .*
91 | DIV_TAG | expr1 expr2 /
92 | DIVELT_TAG | expr1 expr2 ./
93 | POW_TAG | expr2 expr1 ^
94 | POWELT_TAG | expr2 expr1 .^
95 | SINCOS_TAG | int expr trig (where trig(expr,int)=cos(expr+(int-1)*pi/2))
96 | SOLVE_TAG | var equation solve
97 | CSOLVE_TAG | var equation cSolve
98 | NSOLVE_TAG | var equation nSolve
99 | ZEROS_TAG | var expr_in_var zeros
9A | CZEROS_TAG | var expr_in_var cZeros
9B | FMIN_TAG | var expr_in_var fMin
9C | FMAX_TAG | var expr_in_var fMax
9D | COMPLEX_TAG | complex number
9E | POLYEVAL_TAG | expr list polyEval
9F | RANDPOLY_TAG | order var randPoly
A0 | CROSSP_TAG | vec2 vec1 crossP
A1 | DOTP_TAG | vec2 vec1 dotP
A2 | GCD_TAG | expr2 expr1 gcd
A3 | LCM_TAG | expr2 expr1 lcm
A4 | MOD_TAG | expr2 expr1 mod
A5 | INTDIV_TAG | expr2 expr1 intDiv
A6 | REMAIN_TAG | expr2 expr1 remain
A7 | NCR_TAG | expr2 expr1 nCr
A8 | NPR_TAG | expr2 expr1 nPr
A9 | P2RX_TAG | q_expr r_expr P>Rx
AA | P2RY_TAG | q_expr r_expr P>Ry
AB | P2PTHETA_TAG | y_expr x_expr R>Pq
AC | P2PR_TAG | y_expr x_expr R>Pr
AD | AUGMENT_TAG | mat2 mat1 augment
AE | NEWMAT_TAG | num_columns num_rows newMat
AF | RANDMAT_TAG | num_columns num_rows randMat
B0 | SIMULT_TAG | vec mat simult
B1 | PART_TAG | [#] expr part
B2 | EXP2LIST_TAG | var list exp>list
B3 | RANDNORM_TAG | sd mean randNorm
B4 | MROW_TAG | [] index mat expr mRow
B5 | ROWADD_TAG | [] index2 index1 mat rowAdd
B6 | ROWSWAP_TAG | [] index2 index1 mat rowSwap
B7 | ARCLEN_TAG | [] end start var expr arcLen
B8 | NINT_TAG | [] up low var expr nInt
B9 | PI_PRODUCT_TAG | [] high low var expr Õ
BA | SIGMA_SUM_TAG | [] high low var expr å
BB | MROWADD_TAG | [] index2 index1 mat expr mRowAdd
BC | ANS_TAG | [int] ans
BD | ENTRY_TAG | [int] entry
BE | EXACT_TAG | [tol] expr exact
BF | LOGB_TAG | expr2 expr1 logb (where logb(expr1,expr2)=ln(expr1)/ln(expr2))
C0 | COMDENOM_TAG | [var] expr comDenom
C1 | EXPAND_TAG | [var] expr expand
C2 | FACTOR_TAG | [var] expr factor
C3 | CFACTOR_TAG | [var] expr cFactor
C4 | INTEGRATE_TAG | [up low] var expr ò
C5 | DIFFERENTIATE_TAG | [order] var expr ¶
C6 | AVGRC_TAG | [h] var expr avgRC
C7 | NDERIV_TAG | [h] var expr nDeriv
C8 | TAYLOR_TAG | [point] order var expr taylor
C9 | LIMIT_TAG | [direction] point var expr limit
CA | PROPFRAC_TAG | [var] expr propFrac
CB | WHEN_TAG | [[undef_val] false_val] true_val condition when
CC | ROUND_TAG | [digits] expr round
CD | DMS_TAG | [[ss] mm] dd _DMSNUMBER_
CE | LEFT_TAG | [num] string left
CF | RIGHT_TAG | [num] string right
D0 | MID_TAG | [count] start string mid
D1 | SHIFT_TAG | [int] list shift
D2 | SEQ_TAG | [step] high low var expr seq
D3 | LIST2MAT_TAG | [elements_per_row] list list->mat
D4 | SUBMAT_TAG | [[[[col2] row2] col1] row1] mat subMat
D5 | SUBSCRIPT_TAG | [col] row var _subscript_ (i.e. var[row] or var[row,col])
D6 | RAND_TAG | [int] rand
D7 | MIN_TAG | [expr2] list|expr1 min
D8 | MAX_TAG | [expr2] list|expr1 max
D9 | LIST_TAG | list tag, or matrix represented as "list of list"
DA | USERFUNC_TAG | user defined function/program call: [[...] arg1] '\0' fnc_name '\0' USERFUNC_TAG
DB | MATRIX_TAG | matrix tag (only in data editor)
DC | FUNC_TAG | program/function tag (not used in expressions)
DD | DATA_TAG | data tag (not used in expressions)
DE | GDB_TAG | GDB tag (not used in expressions)
DF | PIC_TAG | picture tag (not used in expressions)
E0 | TEXT_TAG | text tag (not used in expressions)
E1 | FIG_TAG | figure tag (not used in expressions)
E2 | MAC_TAG | macro tag (not used in expressions)
E3 | EXT_TAG | extra TI-Basic function token (see ExtTags)
E4 | EXT_INSTR_TAG | TI-Basic command token (not used in expressions, see InstructionTags)
E5 | END_TAG | end of the expression or the list
E6 | COMMENT_TAG | comment (not used in expressions): '\0' string '\0' indentation COMMENT_TAG, where indentation is a single byte indicating the number of spaces between © and the first comment character
E7 | NEXTEXPR_TAG | ":" between tokens on same line in the program (not used in expressions): indentation NEXTEXPR_TAG, where indentation is a single byte indicating the number of spaces between : and the first character of the next logical line
E8 | NEWLINE_TAG | marks end of line in TI-Basic (not used in expressions): indentation NEWLINE_TAG, where indentation is a single byte indicating the number of spaces in front of the first character of the next line
E9 | ENDSTACK_TAG | end of TI-Basic program (not used in expressions), or end of the expression stack
EA | PN1_TAG | expr +/-
EB | PN2_TAG | expr1 expr2 +/-
EC | ERROR_MSG_TAG | name error_message
ED | EIGVC_TAG | mat eigVc
EE | EIGVL_TAG | mat eigVl
EF | DASH_TAG | expr ' (prime, i.e. expr')
F0 | LOCALVAR_TAG | var _local_ (parameter/local variable reference)
F1 | DESOLVE_TAG | [] depend_var indep_var equation deSolve
F2 | FDASH_TAG | func_params func_name ' (prime, i.e. func_name'(func_params)
F3 | ASM_TAG | ASM program tag (not used in expressions)
F4 | ISPRIME_TAG | int isPrime
F8 | OTH_TAG | Other file tag, for custom file types (not used in expressions)
F9 | ROTATE_TAG | [count] list|int|string rotate

Note: An empty list [] of optional arguments means the function does not take any optional arguments, but an END_TAG is needed nonetheless.

Note: For compatibility with TI's compiler, their tag names are also supported.


ti_float

ti_float Type (Scalar)
args.h, estack.h, timath.h, values.h

typedef float ti_float;

An alias for the standard ANSI float type.

ti_float is an alias for the standard ANSI float type, introduced to keep backwards compatibility with antediluvian releases of TIGCC, which didn't support standard ANSI floats. See bcd for more info about the internal organization of floating point values.


asmtypes.h

asmtypes.h Header File
Header File Index

Common type definitions known to ASM programmers

This header file contains a set of predefined types which are common in assembly programs.

Predefined Types
BOOL
Boolean type.
BYTE
One-byte type.
DWORD
Four-byte type.
SBYTE
Signed one-byte type.
SCHAR
Signed character type.
SDWORD
Signed four-byte type.
SINT
Signed integer type.
SLONG
Signed long integer type.
SSHORT
Signed short integer type.
SWORD
Signed two-byte type.
UBYTE
Unsigned one-byte type.
UCHAR
Unsigned character type.
UDWORD
Unsigned four-byte type.
UINT
Unsigned integer type.
ULONG
Unsigned long integer type.
USHORT
Unsigned short integer type.
UWORD
Unsigned two-byte type.
WORD
Two-byte type.


BOOL

BOOL Type (Scalar)
asmtypes.h

typedef unsigned short BOOL;

Boolean type.

A type for storing 0 or 1.


BYTE

BYTE Type (Scalar)
asmtypes.h

typedef unsigned char BYTE;

One-byte type.


DWORD

DWORD Type (Scalar)
asmtypes.h

typedef unsigned long DWORD;

Four-byte type.


SBYTE

SBYTE Type (Scalar)
asmtypes.h

typedef signed char SBYTE;

Signed one-byte type.


SCHAR

SCHAR Type (Scalar)
asmtypes.h

typedef signed char SCHAR;

Signed character type.


SDWORD

SDWORD Type (Scalar)
asmtypes.h

typedef signed long SDWORD;

Signed four-byte type.


SINT

SINT Type (Scalar)
asmtypes.h

typedef signed int SINT;

Signed integer type.


SLONG

SLONG Type (Scalar)
asmtypes.h

typedef signed long SLONG;

Signed long integer type.


SSHORT

SSHORT Type (Scalar)
asmtypes.h

typedef signed short SSHORT;

Signed short integer type.


SWORD

SWORD Type (Scalar)
asmtypes.h

typedef signed short SWORD;

Signed two-byte type.


UBYTE

UBYTE Type (Scalar)
asmtypes.h

typedef unsigned char UBYTE;

Unsigned one-byte type.


UCHAR

UCHAR Type (Scalar)
asmtypes.h

typedef unsigned char UCHAR;

Unsigned character type.


UDWORD

UDWORD Type (Scalar)
asmtypes.h

typedef unsigned long UDWORD;

Unsigned four-byte type.


UINT

UINT Type (Scalar)
asmtypes.h

typedef unsigned int UINT;

Unsigned integer type.


ULONG

ULONG Type (Scalar)
asmtypes.h

typedef unsigned long ULONG;

Unsigned long integer type.


USHORT

USHORT Type (Scalar)
asmtypes.h

typedef unsigned short USHORT;

Unsigned short integer type.


UWORD

UWORD Type (Scalar)
asmtypes.h

typedef unsigned short UWORD;

Unsigned two-byte type.


WORD

WORD Type (Scalar)
asmtypes.h

typedef unsigned short WORD;

Two-byte type.


assert.h

assert.h Header File
Header File Index

Assert routine for debugging purposes

Functions
assert
Tests a condition and possibly aborts.


assert

assert Function (Macro)
assert.h

void assert (short condition);

Tests a condition and possibly aborts.

assert is a macro for debugging purposes that expands to an if statement. If condition evaluates to zero, assert opens an error message box, waits for a keypress, then abort the program. Here is a HTMLized "picture" which shows principally how such message box looks like:

ASSERTION FAILED

Condition: condition_written_as_text

File: filename Line: linenum

Enter=OK

The filename and linenum listed in the message box are the source file name and line number where the assert macro appears. assert expands to relatively big code, so if you have many assert statements in the program, it may become quite long relatively fast. But, if you place the directive
#define NDEBUG
("no debugging") in the source code before the
#include <assert.h>
directive, the assert statement will be ignored.

It might be hard to use this function if you are compiling your program with the IDE (it is possible to get wrong line numbers). In any case, turning off file splitting may be useful.

Uses: ScrRect, ngetchx, DrawStaticButton, MakeWinRect, WinClose, WinFont, WinOpen, WinStr, sprintf


bascmd.h

bascmd.h Header File
Header File Index

Routines for executing TI-Basic commands

Functions
cmd_andpic
Executes TI-Basic 'AndPic' command.
cmd_archive
Executes TI-Basic 'Archive' command.
cmd_blddata
Executes TI-Basic 'BldData' command.
cmd_circle
Executes TI-Basic 'Circle' command.
cmd_clrdraw
Executes TI-Basic 'ClrDraw' command.
cmd_clrerr
Executes TI-Basic 'ClrErr' command.
cmd_clrgraph
Executes TI-Basic 'ClrGraph' command.
cmd_clrhome
Executes TI-Basic 'ClrHome' command.
cmd_clrio
Executes TI-Basic 'ClrIO' command.
cmd_clrtable
Executes TI-Basic 'ClrTable' command.
cmd_copyvar
Executes TI-Basic 'CopyVar' command.
cmd_cubicreg
Executes TI-Basic 'CubicReg' command.
cmd_custmoff
Executes TI-Basic 'CustmOff' command.
cmd_custmon
Executes TI-Basic 'CustmOn' command.
cmd_custom
Executes TI-Basic 'Custom' command.
cmd_cycle
Executes TI-Basic 'Cycle' command.
cmd_cyclepic
Executes TI-Basic 'CyclePic' command.
cmd_delfold
Executes TI-Basic 'DelFold' command.
cmd_delvar
Executes TI-Basic 'DelVar' command.
cmd_dialog
Executes TI-Basic 'Dialog' command.
cmd_disp
Executes TI-Basic 'Disp' command.
cmd_dispg
Executes TI-Basic 'DispG' command.
cmd_disphome
Executes TI-Basic 'DispHome' command.
cmd_disptbl
Executes TI-Basic 'DispTbl' command.
cmd_drawfunc
Executes TI-Basic 'DrawFunc' command.
cmd_drawinv
Executes TI-Basic 'DrawInv' command.
cmd_drawparm
Executes TI-Basic 'DrawParm' command.
cmd_drawpol
Executes TI-Basic 'DrawPol' command.
cmd_else
Executes TI-Basic 'Else' command.
cmd_endfor
Executes TI-Basic 'EndFor' command.
cmd_endloop
Executes TI-Basic 'EndLoop' command.
cmd_endtry
Executes TI-Basic 'EndTry' command.
cmd_endwhile
Executes TI-Basic 'EndWhile' command.
cmd_exit
Executes TI-Basic 'Exit' command.
cmd_expreg
Executes TI-Basic 'ExpReg' command.
cmd_fill
Executes TI-Basic 'Fill' command.
cmd_fnoff
Executes TI-Basic 'FnOff' command.
cmd_fnon
Executes TI-Basic 'FnOn' command.
cmd_for
Executes TI-Basic 'For' command.
cmd_get
Executes TI-Basic 'Get' command.
cmd_getcalc
Executes TI-Basic 'GetCalc' command.
cmd_goto
Executes TI-Basic 'Goto' command.
cmd_graph
Executes TI-Basic 'Graph' command.
cmd_if
Executes TI-Basic 'If' command.
cmd_ifthen
Executes TI-Basic 'If'...'Then' command.
cmd_input
Executes TI-Basic 'Input' command.
cmd_inputstr
Executes TI-Basic 'InputStr' command.
cmd_line
Executes TI-Basic 'Line' command.
cmd_linehorz
Executes TI-Basic 'LineHorz' command.
cmd_linetan
Executes TI-Basic 'LineTan' command.
cmd_linevert
Executes TI-Basic 'LineVert' command.
cmd_linreg
Executes TI-Basic 'LinReg' command.
cmd_lnreg
Executes TI-Basic 'LnReg' command.
cmd_local
Executes TI-Basic 'Local' command.
cmd_lock
Executes TI-Basic 'Lock' command.
cmd_logistic
Executes TI-Basic 'Logistic' command.
cmd_lu_fact
Executes TI-Basic 'LU' command.
cmd_medmed
Executes TI-Basic 'MedMed' command.
cmd_movevar
Executes TI-Basic 'MoveVar' command.
cmd_newdata
Executes TI-Basic 'NewData' command.
cmd_newfold
Executes TI-Basic 'NewFold' command.
cmd_newpic
Executes TI-Basic 'NewPic' command.
cmd_newplot
Executes TI-Basic 'NewPlot' command.
cmd_newprob
Executes TI-Basic 'NewProb' command.
cmd_onevar
Executes TI-Basic 'OneVar' command.
cmd_output
Executes TI-Basic 'Output' command.
cmd_passerr
Executes TI-Basic 'PassErr' command.
cmd_pause
Executes TI-Basic 'Pause' command.
cmd_plotsoff
Executes TI-Basic 'PlotsOff' command.
cmd_plotson
Executes TI-Basic 'PlotsOn' command.
cmd_popup
Executes TI-Basic 'Popup' command.
cmd_powerreg
Executes TI-Basic 'PowerReg' command.
cmd_printobj
Executes TI-Basic 'PrintObj' command.
cmd_prompt
Executes TI-Basic 'Prompt' command.
cmd_ptchg
Executes TI-Basic 'PtChg' command.
cmd_ptoff
Executes TI-Basic 'PtOff' command.
cmd_pton
Executes TI-Basic 'PtOn' command.
cmd_pttext
Executes TI-Basic 'PtText' command.
cmd_pxlchg
Executes TI-Basic 'PxlChg' command.
cmd_pxlcircle
Executes TI-Basic 'PxlCircle' command.
cmd_pxlhorz
Executes TI-Basic 'PxlHorz' command.
cmd_pxlline
Executes TI-Basic 'PxlLine' command.
cmd_pxloff
Executes TI-Basic 'PxlOff' command.
cmd_pxlon
Executes TI-Basic 'PxlOn' command.
cmd_pxltext
Executes TI-Basic 'PxlText' command.
cmd_pxlvert
Executes TI-Basic 'PxlVert' command.
cmd_qr_fact
Executes TI-Basic 'QR' command.
cmd_quadreg
Executes TI-Basic 'QuadReg' command.
cmd_quartreg
Executes TI-Basic 'QuartReg' command.
cmd_randseed
Executes TI-Basic 'RandSeed' command.
cmd_rclgdb
Executes TI-Basic 'RclGDB' command.
cmd_rclpic
Executes TI-Basic 'RclPic' command.
cmd_rename
Executes TI-Basic 'Rename' command.
cmd_request
Executes TI-Basic 'Request' command.
cmd_return
Executes TI-Basic 'Return' command.
cmd_rplcpic
Executes TI-Basic 'RplcPic' command.
cmd_send
Executes TI-Basic 'Send' command.
cmd_sendcalc
Executes TI-Basic 'SendCalc' command.
cmd_sendchat
Executes TI-Basic 'SendChat' command.
cmd_shade
Executes TI-Basic 'Shade' command.
cmd_showstat
Executes TI-Basic 'ShowStat' command.
cmd_sinreg
Executes TI-Basic 'SinReg' command.
cmd_slpline
Executes TI-Basic 'SlpLine' command.
cmd_sorta
Executes TI-Basic 'SortA' command.
cmd_sortd
Executes TI-Basic 'SortD' command.
cmd_stogdb
Executes TI-Basic 'StoGDB' command.
cmd_stopic
Executes TI-Basic 'StoPic' command.
cmd_style
Executes TI-Basic 'Style' command.
cmd_table
Executes TI-Basic 'Table' command.
cmd_text
Executes TI-Basic 'Text' command.
cmd_toolbar
Executes TI-Basic 'Toolbar' command.
cmd_trace
Executes TI-Basic 'Trace' command.
cmd_try
Executes TI-Basic 'Try' command.
cmd_twovar
Executes TI-Basic 'TwoVar' command.
cmd_unarchiv
Executes TI-Basic 'UnArchiv' command.
cmd_unlock
Executes TI-Basic 'Unlock' command.
cmd_while
Executes TI-Basic 'While' command.
cmd_xorpic
Executes TI-Basic 'XorPic' command.
cmd_zoombox
Executes TI-Basic 'ZoomBox' command.
cmd_zoomdata
Executes TI-Basic 'ZoomData' command.
cmd_zoomdec
Executes TI-Basic 'ZoomDec' command.
cmd_zoomfit
Executes TI-Basic 'ZoomFit' command.
cmd_zoomin
Executes TI-Basic 'ZoomMin' command.
cmd_zoomint
Executes TI-Basic 'ZoomInt' command.
cmd_zoomout
Executes TI-Basic 'ZoomOut' command.
cmd_zoomprev
Executes TI-Basic 'ZoomPrev' command.
cmd_zoomrcl
Executes TI-Basic 'ZoomRcl' command.
cmd_zoomsqr
Executes TI-Basic 'ZoomSqr' command.
cmd_zoomstd
Executes TI-Basic 'ZoomStd' command.
cmd_zoomsto
Executes TI-Basic 'ZoomSto' command.
cmd_zoomtrig
Executes TI-Basic 'ZoomTrig' command.
Global Variables
primary_tag_list
Array of structures containing information on Tags.
Predefined Types
CESI
Represents a pointer to a constant expression.
ESI
Represents an index of a value on the TIOS expression stack.
ESQ
Represents a quantum within an expression.
EStackIndex
Represents an index of a value on the TIOS expression stack.
Quantum
Represents a quantum within an expression.
SYM_STR
Represents a pointer to the terminating zero byte of a string.
tag_info
Structure containing information about AMS EStack tags (Tags, ExtTags).

Note: All functions from this header file get parameters from the expression stack, so this header file must be used in conjunction with estack.h. You need to learn about the usage of the expression stack before using any function from this header file. All functions defined here execute particular TI-Basic commands. They sometimes may be useful to perform some operations which cannot be implemented in C easily. But note that if you use functions from this header file too much, this will decrease the performance of your program significantly. In an extreme case, it will in fact decrease to that of a TI-Basic program! So use functions from this header file only if it is really necessary. Also note that these functions act exactly like the appropriate TI-Basic commands (including throwing errors if something is wrong), so the use of an error tracking mechanism from the error.h header file is highly recommended.

See also: basfunc.h, basop.h


cmd_andpic

cmd_andpic Function (ROM Call 0x32A)
AMS 1.01 or higher bascmd.h

void cmd_andpic (SYM_STR SymName, CESI y, CESI x);

Executes TI-Basic 'AndPic' command.

cmd_andpic displays the Graph Screen and logically ANDs the picture stored in the TI-Basic variable pointed to by SymName (a VAT variable string, see SYMSTR) into the current graph screen at the pixel coordinates determined by the values pointed to by y and x, respectively. Both x and y should point to integer items. SymName should be the name of a PIC variable.

See BitmapPut for much faster low-level manipulations with bitmap pictures, independently of the Graph Screen.

Uses: GetValue, HToESI, gr_active, GraphActivate, DerefSym, VarRecall, WinBitmapPut

See also: cmd_rclpic, cmd_xorpic, cmd_rplcpic, cmd_stopic, BitmapPut


cmd_archive

cmd_archive Function (ROM Call 0x448)
AMS 2.00 or higher bascmd.h

void cmd_archive (CESI VarNameList);

Executes TI-Basic 'Archive' command.

cmd_archive archives one or more TI-Basic variables (i.e. VAT symbols). For details about VarNameList, see cmd_lock.

Uses: HToESI, next_expression_index, CheckSysFunc, DerefSym, EM_moveSymToExtMem, SymDelTwin, VarRecall, ROM Call 0x5CA
Used by: OSLinkCmd, EM_moveSymToExtMem

See also: cmd_unarchiv, cmd_lock, cmd_unlock


cmd_blddata

cmd_blddata Function (ROM Call 0x32B)
AMS 1.01 or higher bascmd.h

void cmd_blddata (ESI SymName);

Executes TI-Basic 'BldData' command.

cmd_blddata creates a TI-Basic data variable based on the information used to plot the current graph. It is valid in all graphing modes. See the TI-Basic BldData command in the TI-Basic manual for more details.

SymName should point to the variable tag of the wanted data variable name, which may be a string of type SYM_STR. However, it must be on the expression stack, so you cannot pass a result of the SYMSTR macro to cmd_blddata. Instead, if you want to create the data variable named "foo", for example, you should do:

push_expression (SYMSTR ("foo"));
cmd_blddata (top_estack);
Alternatively, SymName may point to END_TAG. In this case, the system variable "sysData" is used.

Uses: cmd_newdata, HeapAllocThrow, HeapFreeIndir, HeapLock, HeapRealloc, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, push_expression, push_Float, push_quantum, push_quantum_pair, top_estack, CptDeltax, gr_active, gr_flags, StepCk, memcpy, memmove, fabs, is_transfinite, round12_err, sqrt, cleanup_de_mem, cleanup_seq_mem, CountGrFunc, cpt_gr_fun, cpt_gr_param, cpt_gr_polar, CptIndep, CptLastIndepDE, de_loop, deStepCk, estack_to_float, FindFunc, FindGrFunc, FirstSeqPlot, gr_CptIndepInc, gr_del_locals, gr_del_vars_in_folder, gr_find_de_result, gr_find_el, gr_xres_pixel, grFuncName, InitDEAxesRng, InitDEMem, InitTimeSeq, seqStepCk, setup_more_graph_fun, time_loop, TIOS_abs, unlock_more_graph_fun, DerefSym, FindSymInFolder, FolderAdd, FolderDel, FolderFind, HSymDel, SymAdd, SymFind, SymFindMain, VarStore, _bcd_math, NG_setup_graph_fun, NG_cleanup_graph_fun


cmd_circle

cmd_circle Function (ROM Call 0x32C)
AMS 1.01 or higher bascmd.h

void cmd_circle (CESI x, CESI y, CESI radius, CESI drawmode);

Executes TI-Basic 'Circle' command.

cmd_circle displays the Graph Screen and draws, erases, or inverts a circle on it. The parameters x, y, radius, and drawmode should point to four items on the expression stack, which represent respectively the coordinates of the center of the circle, the radius, and the drawing mode. All coordinates and the radius are integer or floating point values which are relative to the current window settings (you can change them using the "Window Editor" application, or directly by storing values in system variables like "xmin", using the VarStore function). drawmode should point to one of the following values:

1 | Draws the circle.
0 | Erases the circle.
-1 | Inverts pixels along the circle.

See also cmd_pxlcircle, which uses pixel coordinates instead of window-relative ones, and DrawClipEllipse for much faster low-level circle/ellipse drawing (independently of the Graph Screen).

Uses: ER_catch, ER_success, ER_throwVar, GetValue, push_expression, push_Float, push_quantum, top_estack, gr_active, OSCheckBreak, is_transfinite, ForceFloat, GraphActivate, GrLineFlt, QSkipGraphErr, XCvtFtoP, XCvtPtoF, YCvtFtoP, YCvtFtoWin, MakeWinRect, WinAttr, WinEllipse, WinLine, _bcd_math

See also: cmd_pxlcircle, DrawClipEllipse


cmd_clrdraw

cmd_clrdraw Function (ROM Call 0x32D)
AMS 1.01 or higher bascmd.h

void cmd_clrdraw (void);

Executes TI-Basic 'ClrDraw' command.

cmd_clrdraw clears the Graph Screen window and resets the Smart Graph feature, so that the next time the Graph Screen is displayed, the graph will be redrawn.

Uses: gr_active
Used by: cmd_newprob


cmd_clrerr

cmd_clrerr Function (ROM Call 0x32E)
AMS 1.01 or higher bascmd.h

void cmd_clrerr (void);

Executes TI-Basic 'ClrErr' command.

cmd_clrerr sets the TI-Basic system variable "errornum" to zero and clears the internal error context variables.

Note: See TRY, ONERR, and ENDTRY to learn how to take control over errors while executing a C program.

Uses: clear_error_context, Float0Index, VarStore
Used by: cmd_newprob

See also: cmd_try, cmd_passerr


cmd_clrgraph

cmd_clrgraph Function (ROM Call 0x32F)
AMS 1.01 or higher bascmd.h

void cmd_clrgraph (void);

Executes TI-Basic 'ClrGraph' command.

cmd_clrgraph clears all functions or expressions that were graphed with the TI-Basic Graph command (or cmd_graph from this header file), or were created with the TI-Basic Table command (or cmd_table from this header file). All previously selected functions in the Y= Editor application will be graphed the next time that the graph is displayed.

Uses: gr_active, gr_DelFolder
Used by: cmd_newprob

See also: cmd_graph, cmd_table


cmd_clrhome

cmd_clrhome Function (ROM Call 0x330)
AMS 1.01 or higher bascmd.h

void cmd_clrhome (void);

Executes TI-Basic 'ClrHome' command.

cmd_clrhome clears all items stored in the Home Screen history area and clears the Home Screen window. It also resets the suffixes of arbitrary constants or integers (like @1, @n2, etc.) to 1.

Uses: ARb_int_count, ARb_real_count, HS_freeAll, WinClr
Used by: cmd_newprob

See also: HS_freeAll, ARb_real_count, ARb_int_count


cmd_clrio

cmd_clrio Function (ROM Call 0x331)
AMS 1.01 or higher bascmd.h

void cmd_clrio (void);

Executes TI-Basic 'ClrIO' command.

cmd_clrio clears the TI-Basic Program I/O Screen window (without displaying it to the screen), and sets the Program I/O Screen window cursor position to the upper left corner.

Uses: WinClr
Used by: cmd_newprob


cmd_clrtable

cmd_clrtable Function (ROM Call 0x332)
AMS 1.01 or higher bascmd.h

void cmd_clrtable (void);

Executes TI-Basic 'ClrTable' command.

cmd_clrtable clears all table values. This applies only to the ASK setting on the Table Setup dialog box. See the TI-Basic manual for more info.

Uses: HeapFree, Dialog, gr_active, CreateEmptyList
Used by: cmd_newprob


cmd_copyvar

cmd_copyvar Function (ROM Call 0x333)
AMS 1.01 or higher bascmd.h

void cmd_copyvar (SYM_STR SrcName, SYM_STR DestName);

Executes TI-Basic 'CopyVar' command.

cmd_copyvar copies the contents of one TI-Basic variable to another one. The parameters SrcName and DestName should point to the variable tags of the source and the destination variable, respectively. If the destination variable does not exist, cmd_copyvar creates it. This function may be used instead of low-level routines from vat.h.

Uses: ROM Call 0x438

See also: cmd_movevar, cmd_rename


cmd_cubicreg

cmd_cubicreg Function (ROM Call 0x334)
AMS 1.01 or higher bascmd.h

void cmd_cubicreg (ESI RegData);

Executes TI-Basic 'CubicReg' command.

cmd_cubicreg calculates a cubic polynomial regression and updates all statistics variables (see TI-Basic manual for more info). The RegData parameter must point to a structure on the expression stack which describes where the actual data is stored. See cmd_linreg for more info.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_linreg, cmd_quadreg, cmd_quartreg, cmd_powerreg, cmd_expreg, cmd_lnreg, cmd_sinreg, cmd_onevar, cmd_twovar, cmd_medmed, cmd_logistic


cmd_custmoff

cmd_custmoff Function (ROM Call 0x335)
AMS 1.01 or higher bascmd.h

void cmd_custmoff (void);

Executes TI-Basic 'CustmOff' command.

cmd_custmoff removes the custom toolbar menu in the current application. The custom toolbar is removed automatically when you change the application.

Uses: CustomEnd


cmd_custmon

cmd_custmon Function (ROM Call 0x336)
AMS 1.01 or higher bascmd.h

void cmd_custmon (void);

Executes TI-Basic 'CustmOn' command.

cmd_custmon activates a custom toolbar menu in the current application.

Uses: CustomBegin

See also: cmd_toolbar, menus.h


cmd_custom

cmd_custom Function (ROM Call 0x337)
AMS 1.01 or higher bascmd.h

void cmd_custom (void);

Executes TI-Basic 'Custom' command.

cmd_custom is an internal subroutine used by the TI-Basic interpreter for defining custom menus using 'Custom'...'EndCustm' blocks. As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: Look at the functions from menus.h if you want to make menus inside a C program.

Uses: HeapAllocThrow, HeapFreeIndir, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, top_estack, MenuAddIcon, MenuAddText, MenuNew, strlen, NeedStack, CustomFree, push_simplify, ReallocExprStruct, DerefSym, VarRecall, ROM Call 0x5C8

See also: cmd_toolbar, menus.h


cmd_cycle

cmd_cycle Function (ROM Call 0x338)
AMS 1.01 or higher bascmd.h

void cmd_cycle (void);

Executes TI-Basic 'Cycle' command.

cmd_cycle is an internal subroutine used by the TI-Basic interpreter for executing the Cycle command (performs searching for a matching For/EndFor instruction, etc.). As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: If you want to achieve a similar effect in the C language like using the Cycle command in TI-Basic, you should use the continue keyword.

Uses: next_expression_index, index_after_match_endtag, ROM Call 0x5C8


cmd_cyclepic

cmd_cyclepic Function (ROM Call 0x339)
AMS 1.01 or higher bascmd.h

void cmd_cyclepic (CESI PicNamePrefix, CESI n, CESI wait, CESI cycles, CESI direction);

Executes TI-Basic 'CyclePic' command.

cmd_cyclepic implements the TI-Basic CyclePic command, which displays the Graph Screen and then displays a series of pictures (a slide show) on it in a cycle. The PicNamePrefix parameter should point to a string item on the expression stack (more precise, to its STR_TAG), and n should point to an integer item which determines the total number of pictures.

The names of the TI-Basic PIC variables which contain the picture data will be derived from PicNamePrefix and n. For example, if PicNamePrefix points to "pic" and n points to 5, the picture data will be picked from TI-Basic PIC variables called "pic1", "pic2", "pic3", "pic4" and "pic5".

The wait parameter should point to an integer or floating point item which determines the time between pictures. cycles should point to an integer item which determines the number of times to cycle through the pictures. direction should point to an integer item containing 1 or -1. If it is 1, the pictures will be displayed in a normal loop, and if it is -1, the loop will run in both directions.

Note: The TI-Basic command CyclePic is implemented to allow making simple animations in the TI-Basic. Although this function principally may be used in C to accomplish the same task, the usage of it is tedious and there are much better ways for doing this in C which are also independent of the Graph Screen. Take a look at the functions from graph.h, wingraph.h, and sprites.h.

Uses: GetValue, HToESI, next_expression_index, gr_active, memset, sprintf, strlen, idle, OSCheckBreak, OSFreeTimer, OSRegisterTimer, OSTimerExpired, ForceFloat, GraphActivate, DerefSym, FindSymInFolder, TempFolderName, ValidateSymName, VarRecall, WinBitmapPut, _bcd_math


cmd_delfold

cmd_delfold Function (ROM Call 0x33A)
AMS 1.01 or higher bascmd.h

void cmd_delfold (CESI FolderNameList);

Executes TI-Basic 'DelFold' command.

cmd_delfold deletes one or more empty folders. It expects the following layout on the expression stack:

END_TAG symname_n ... symname_2 symname_1

symname_1, symname_2, etc. are VAT symbol names (see SYMSTR and Tags for more info) of folders which are supposed to be deleted. The FolderNameList parameter should point to the tag of the last item. This function may be used as a high-level alternative for the low-level function FolderDel from the vat.h header file.

Uses: next_expression_index, ST_folder, DerefSym, HSymDel, SymFindHome

See also: cmd_newfold, FolderDel


cmd_delvar

cmd_delvar Function (ROM Call 0x33B)
AMS 1.01 or higher bascmd.h

void cmd_delvar (CESI VarNameList);

Executes TI-Basic 'DelVar' command.

This function deletes one or more TI-Basic variables. It expects the following layout on the expression stack:

END_TAG symname_n ... symname_2 symname_1

symname_1, symname_2, etc. are VAT symbol names (see SYMSTR and Tags for more info) of variables which are supposed to be deleted. The VarNameList parameter should point to the tag of the last item. This function may be used as a high-level alternative for the low-level function SymDel from the vat.h header file.

Uses: HeapFree, next_expression_index, DerefSym, HSymDel, VarRecall, sysvar_tag_list

See also: SymDel


cmd_dialog

cmd_dialog Function (ROM Call 0x33C)
AMS 1.01 or higher bascmd.h

void cmd_dialog (void);

Executes TI-Basic 'Dialog' command.

cmd_dialog is an internal subroutine used by the TI-Basic interpreter for defining dialogs using 'Dialog'...'EndDlog' blocks. As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See functions from the dialogs.h header file if you want to make dialogs inside a C program.

Uses: HeapFree, HeapFreeIndir, HeapLock, HeapRealloc, HeapUnlock, DialogAdd, DialogDo, DialogNew, ER_catch, ER_success, ER_throwVar, GetValue, HToESI, next_expression_index, push_internal_simplify, push_quantum, push_quantum_pair, push_zstr, top_estack, DrawStrWidth, memset, PopupAddText, PopupNew, strcat, strlen, strncpy, NeedStack, is0, primary_tag_list, push_simplify, DerefSym, SetOK, VarRecall, VarStore, ROM Call 0x480, ROM Call 0x5C8

See also: cmd_text, cmd_request, dialogs.h


cmd_disp

cmd_disp Function (ROM Call 0x33D)
AMS 1.01 or higher bascmd.h

void cmd_disp (CESI ExprList);

Executes TI-Basic 'Disp' command.

cmd_disp first displays the current contents of the TI-Basic Program I/O Screen window. If ExprList points to END_TAG, cmd_disp does nothing more. Else, the expression (or string, if ExprList points to STR_TAG) pointed to by ExprList is displayed on the TI-Basic Program I/O Screen window. This task is repeated for all expressions on the expression stack below ExprList, until END_TAG is reached. Each expression (or character string) is displayed on a separate line in the TI-Basic Program I/O Screen window. If "Pretty Print" in the current mode settings is turned on, expressions are displayed in mathematical notation.

Uses: HeapFree, ER_catch, ER_success, ER_throwVar, next_expression_index, Parms2D, Parse1DExpr, Parse2DExpr, Print2DExpr, top_estack, EV_setFKeyState, EV_startApp, ScrToHome, ScrToWin, TE_unfocus, EV_currentApp, EV_quit, WinActivate, WinAttr, WinBackupToScr, WinClr, WinDeactivate, WinHeight, WinHide, WinScrollV, WinStrXY, ROM Call 0x457, ROM Call 0x471


cmd_dispg

cmd_dispg Function (ROM Call 0x33E)
AMS 1.01 or higher bascmd.h

void cmd_dispg (void);

Executes TI-Basic 'DispG' command.

cmd_dispg displays the current contents of the Graph Screen window by switching to the "Graph" application (see the events.h header file for more information about switching applications).

Uses: GraphActivate


cmd_disphome

cmd_disphome Function (ROM Call 0x33F)
AMS 1.01 or higher bascmd.h

void cmd_disphome (void);

Executes TI-Basic 'DispHome' command.

cmd_disphome displays the current content of the Home Screen window. More precise, it starts the Home application if it is not already running, and makes sure the Home Screen window is being displayed switching from the Program I/O window if necessary. The OS will deactivate or terminate the current application to activate the Home Screen.

Note: If you used any function from this header file which displays various windows which are different than Home Screen window (for example, TI-Basic Program I/O Screen window), use cmd_disphome before returning from your program to activate the Home Screen again!

Uses: HeapFreeIndir, bottom_estack, EV_setCmdState, EV_setFKeyState, EV_startApp, HS_countFIFO, ST_stack, TE_focus, EV_currentApp, EV_quit, WinActivate, WinDeactivate, WinFill, WinHide, ROM Call 0x471, HS_MaxExpressions


cmd_disptbl

cmd_disptbl Function (ROM Call 0x340)
AMS 1.01 or higher bascmd.h

void cmd_disptbl (void);

Executes TI-Basic 'DispTbl' command.

cmd_disptbl displays the current contents of the Table Screen window by switching to the "Table" application (see the events.h header file for more information about switching applications). It interrupts the execution of the program and accepts all keypress events of the "Table" application, until the 'ENTER' key is pressed.

Uses: ER_catch, ER_success, ER_throwVar, ERD_process, EV_paintWindows, EV_sendEvent, EV_startApp, gr_active, kbhit, ngetchx, pushkey, ST_busy, idle, off, OSTimerExpired, OSTimerRestart, WordInList, ROM Call 0x46E


cmd_drawfunc

cmd_drawfunc Function (ROM Call 0x341)
AMS 1.01 or higher bascmd.h

void cmd_drawfunc (CESI expr);

Executes TI-Basic 'DrawFunc' command.

cmd_drawfunc displays the Graph Screen and draws the expression pointed to by expr on the screen as a function, using "x" as the independent variable. For example, to draw the graph of the sine function, you can do:

push_parse_text ("sin(x)");
cmd_drawfunc (top_estack);
Note that the drawn graph is not part of the smart graph feature (see the TI-Basic manual for more info), and that regraphing will erase all drawn items.

Uses: ER_catch, ER_success, ER_throwVar, push_expression, push_Float, push_quantum, top_estack, gr_active, OSCheckBreak, is_transfinite, ForceFloat, GraphActivate, GrLineFlt, QSkipGraphErr, XCvtPtoF, YCvtPtoF

See also: cmd_graph, cmd_drawinv, cmd_drawparm, cmd_drawpol


cmd_drawinv

cmd_drawinv Function (ROM Call 0x342)
AMS 1.01 or higher bascmd.h

void cmd_drawinv (CESI expr);

Executes TI-Basic 'DrawInv' command.

cmd_drawinv displays the Graph Screen and draws the inverse of the expression pointed to by expr on the screen by plotting x values on the y axis and y values on the x axis. "x" is used as the independent variable.

Uses: ER_catch, ER_success, ER_throwVar, push_expression, push_Float, push_quantum, top_estack, CkValidDelta, CptDeltay, gr_active, OSCheckBreak, is_transfinite, ForceFloat, GraphActivate, GrLineFlt, QSkipGraphErr, XCvtPtoF, YCvtPtoF

See also: cmd_drawfunc


cmd_drawparm

cmd_drawparm Function (ROM Call 0x343)
AMS 1.01 or higher bascmd.h

void cmd_drawparm (CESI ExprList);

Executes TI-Basic 'DrawParm' command.

cmd_drawparm displays the Graph Screen and draws a parametric graph, using "t" as the independent variable. This function expects one of the following eight layouts on the expression stack:

END_TAG tstep tmax tmin y_expr x_expr
END_TAG tmax tmin y_expr x_expr
END_TAG tstep NOTHING_TAG tmin y_expr x_expr
END_TAG tstep tmax NOTHING_TAG y_expr x_expr
END_TAG tmin y_expr x_expr
END_TAG tmax NOTHING_TAG y_expr x_expr
END_TAG tstep NOTHING_TAG NOTHING_TAG y_expr x_expr
END_TAG y_expr x_expr

The parameter ExprList should point to the tag of the last item. x_expr and y_expr are the expressions for "x(t)" and "y(t)", which define the curve. tmin, tmax and tstep are floating point items which determine the starting value, the ending value, and the increment of the independent variable "t" which will be used for drawing. For example, to draw the curve defined by x=cos(t) and y=sin(t) where t varies from 0 to 2*pi in steps of 0.1, you can use the following code fragment:

push_Float (0.1);
push_Float (2. * PI);
push_Float (0);
push_parse_text ("cos(t)");
push_parse_text ("sin(t)");
cmd_drawparm (top_estack);
If the current graphing mode is not parametric, only the first layout is valid. Otherwise, the omitted expressions will be picked from the current settings of the "tmin", "tmax", and "tstep" system variables, which can be set using the "Window Editor" application.

Uses: ER_catch, ER_success, ER_throwVar, next_expression_index, push_expression, push_Float, push_quantum, top_estack, gr_active, StepCk, OSCheckBreak, is_transfinite, CptIndep, ForceFloat, GraphActivate, GrLineFlt, QSkipGraphErr

See also: cmd_drawpol, cmd_drawfunc


cmd_drawpol

cmd_drawpol Function (ROM Call 0x344)
AMS 1.01 or higher bascmd.h

void cmd_drawpol (CESI ExprList);

Executes TI-Basic 'DrawPol' command.

cmd_drawpol displays the Graph Screen and draws a polar graph, using the Greek letter "theta" as the independent variable. This function expects one of the following eight layouts on the expression stack:

END_TAG thstep thmax thmin expr
END_TAG thmax thmin expr
END_TAG thstep NOTHING_TAG thmin expr
END_TAG thstep thmax NOTHING_TAG expr
END_TAG thmin expr
END_TAG thmax NOTHING_TAG expr
END_TAG thstep NOTHING_TAG NOTHING_TAG expr
END_TAG expr

The parameter ExprList should point to the tag of the last item. expr is the expression which defines the polar graph. thmin, thmax and thstep are floating point items which determine the starting value, the ending value, and the increment of the independent variable "theta" which will be used for drawing.

If the current graphing mode is not polar, only the first layout is valid. Otherwise, the omitted expressions will be picked from the current settings of the "thetamin", "thetamax" and "thetastep" system variables in the "Window Editor" application (note that "theta" means a Greek letter theta, not an actual string "theta").

Uses: ER_catch, ER_success, ER_throwVar, next_expression_index, push_expression, push_Float, push_quantum, top_estack, gr_active, StepCk, OSCheckBreak, is_transfinite, round14, sincos, CptIndep, ForceFloat, GraphActivate, GrLineFlt, QSkipGraphErr, _bcd_math

See also: cmd_drawparm, cmd_drawfunc


cmd_else

cmd_else Function (ROM Call 0x345)
AMS 1.01 or higher bascmd.h

void cmd_else (void);

Executes TI-Basic 'Else' command.

This is an internal subroutine used by TI-Basic interpreter for finding the matching EndIf instruction when the Else instruction is encountered. As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See the if and else keywords to learn how to implement conditional execution in the C language.

Uses: index_after_match_endtag, ROM Call 0x5C8

See also: cmd_ifthen


cmd_endfor

cmd_endfor Function (ROM Call 0x346)
AMS 1.01 or higher bascmd.h

void cmd_endfor (void);

Executes TI-Basic 'EndFor' command.

cmd_endfor is an internal subroutine used by the TI-Basic interpreter for terminating the 'For'...'EndFor' loop (searches for a matching 'For' instruction and transfers the control there if necessary). As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See the for keyword to learn how to use loops in C language which are similar to For...EndFor loops in TI-Basic.

Uses: push_difference, push_sum, is_narrowly_independent_of, next_expression_index, push_internal_simplify, top_estack, assign_between, divide_top, Integer1Index, is_negative, is0, primary_tag_list, ROM Call 0x480, ROM Call 0x5C8

See also: cmd_for


cmd_endloop

cmd_endloop Function (ROM Call 0x347)
AMS 1.01 or higher bascmd.h

void cmd_endloop (void);

Executes TI-Basic 'EndLoop' command.

This is an internal subroutine used by the TI-Basic interpreter for terminating the 'Loop'...'EndLoop' loop (searches for a matching 'Loop' instruction and transfers the control there). As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See the while keyword to learn how to use loops in the C language which are similar to Loop...EndLoop loops in TI-Basic.

Uses: ROM Call 0x5C8

See also: cmd_while


cmd_endtry

cmd_endtry Function (ROM Call 0x348)
AMS 1.01 or higher bascmd.h

void cmd_endtry (void);

Executes TI-Basic 'EndTry' command.

cmd_endtry is an internal subroutine used by the TI-Basic interpreter for terminating an error-protected block ('Try'...'EndTry'). Principally, this function performs cmd_clrerr and signals that further TI-Basic instructions are not error-protected anymore. It is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See TRY, ONERR, and ENDTRY to learn how to take control over errors while executing a C program.

Uses: clear_error_context, Float0Index, VarStore

See also: cmd_try


cmd_endwhile

cmd_endwhile Function (ROM Call 0x349)
AMS 1.01 or higher bascmd.h

void cmd_endwhile (void);

Executes TI-Basic 'EndWhile' command.

cmd_endwhile is an internal subroutine used by TI-Basic interpreter for terminating the 'While'...'EndWhile' loop (searches for a matching 'While' instruction and transfers the control there). As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See the while keyword to learn how to use loops in the C language which are similar to While...EndWhile loops in TI-Basic.

Uses: next_expression_index, push_internal_simplify, top_estack, NG_control, ROM Call 0x5C8

See also: cmd_while


cmd_exit

cmd_exit Function (ROM Call 0x34A)
AMS 1.01 or higher bascmd.h

void cmd_exit (void);

Executes TI-Basic 'Exit' command.

cmd_exit is an internal subroutine used by the TI-Basic interpreter for executing the Exit command (performs searching for a matching EndFor instruction, etc.). As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: If you want to achieve the similar effect in the C language like using the Exit command in TI-Basic, you should use the break keyword.

Uses: next_expression_index, index_after_match_endtag, ROM Call 0x5C8


cmd_expreg

cmd_expreg Function (ROM Call 0x34B)
AMS 1.01 or higher bascmd.h

void cmd_expreg (ESI RegData);

Executes TI-Basic 'ExpReg' command.

cmd_expreg calculates an exponential regression and updates all statistics variables (see TI-Basic manual for more info). The RegData parameter must point to a structure on the expression stack which describes where the actual data is stored. See cmd_linreg for more info.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_linreg, cmd_quadreg, cmd_cubicreg, cmd_quartreg, cmd_powerreg, cmd_lnreg, cmd_sinreg, cmd_onevar, cmd_twovar, cmd_medmed, cmd_logistic


cmd_fill

cmd_fill Function (ROM Call 0x34C)
AMS 1.01 or higher bascmd.h

void cmd_fill (CESI expr, SYM_STR SymName);

Executes TI-Basic 'Fill' command.

cmd_fill replaces each element in the TI-Basic matrix variable whose name is pointed to by SymName (see SYMSTR) with the expression pointed to by expr. The variable must already exist, else an error is thrown.

Uses: remaining_element_count, delete_between, HToESI, push_expression, push_quantum, top_estack, DerefSym, QSysProtected, VarRecall, VarStore

See also: VarStore


cmd_fnoff

cmd_fnoff Function (ROM Call 0x34D)
AMS 1.01 or higher bascmd.h

void cmd_fnoff (CESI IntList);

Executes TI-Basic 'FnOff' command.

If IntList points to END_TAG, cmd_fnoff deselects all 'Y=' functions for the current graphing mode (note that in split-screen two-graph mode, cmd_fnoff only applies to the active graph). If IntList points to an integer item in the range from 1 to 99, cmd_fnoff deselects the specified 'Y=' function for the current graph mode, and repeats this task for all expressions on the expression stack below IntList, until END_TAG is reached.

Uses: next_expression_index, gr_active, EQU_select
Used by: cmd_newprob

See also: cmd_fnon


cmd_fnon

cmd_fnon Function (ROM Call 0x34E)
AMS 1.01 or higher bascmd.h

void cmd_fnon (CESI IntList);

Executes TI-Basic 'FnOn' command.

If IntList points to END_TAG, cmd_fnon selects all 'Y=' functions that are defined for the current graphing mode (note that in split-screen two-graph mode, cmd_fnon only applies to the active graph). If IntList points to an integer item in the range from 1 to 99, cmd_fnon selects the specified 'Y=' function for the current graph mode, and repeats this task for all expressions on the expression stack below IntList, until END_TAG is reached. In 3D graphing mode, only one function at a time can be selected.

Uses: next_expression_index, gr_active, EQU_select, FindGrFunc

See also: cmd_fnoff


cmd_for

cmd_for Function (ROM Call 0x34F)
AMS 1.01 or higher bascmd.h

void cmd_for (SYM_STR VarName, CESI start, CESI end, CESI step);

Executes TI-Basic 'For' command.

This is an internal subroutine used by TI-Basic interpreter for initializing a counter variable used in a 'For'...'EndFor' loop. As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See the for keyword to learn how to use loops in C language which are similar to For...EndFor loops in TI-Basic.

Uses: push_difference, is_narrowly_independent_of, next_expression_index, top_estack, assign_between, divide_top, index_after_match_endtag, is_negative, is0, primary_tag_list, ROM Call 0x5C8

See also: cmd_endfor


cmd_get

cmd_get Function (ROM Call 0x350)
AMS 1.01 or higher bascmd.h

void cmd_get (SYM_STR SymName);

Executes TI-Basic 'Get' command.

cmd_get receives a CBL (Calculator-Based Laboratory) value from the link port and stores it in a variable whose name is pointed to by SymName (a VAT variable name, see SYMSTR).

Uses: HeapAllocThrow, HeapFree, HeapLock, HeapUnlock, push_assignment, push_indir_name, ER_catch, ER_success, ER_throwVar, HToESI, push_expression, push_Float, top_estack, LIO_Get, memcpy, round14, primary_tag_list, store_to_subscripted_element, DerefSym, VarRecall, VarStore, _du16u16, strtod

See also: cmd_send, cmd_getcalc


cmd_getcalc

cmd_getcalc Function (ROM Call 0x351)
AMS 1.01 or higher bascmd.h

void cmd_getcalc (SYM_STR SymName);

Executes TI-Basic 'GetCalc' command.

cmd_getcalc receives a variable (or program) whose name is pointed to by SymName (a VAT variable name, see SYMSTR) from the link interface. This function does nothing more than to call the function getcalc from the link.h header file.

Uses: getcalc

See also: cmd_sendcalc, cmd_sendchat, cmd_get, getcalc


cmd_goto

cmd_goto Function (ROM Call 0x352)
AMS 1.01 or higher bascmd.h

void cmd_goto (SYM_STR LabelName);

Executes TI-Basic 'Goto' command.

cmd_goto is the main subroutine for executing the TI-Basic Goto statement. It searches the current TI-Basic program for the label whose name is pointed to by LabelName (see SYMSTR. cmd_goto throws an error if it is not found, otherwise it tells the TI-Basic interpreter where it is found (by storing its address in an internal variable). It is not likely that this function may be useful inside a C program for anything.

Uses: are_expressions_identical, next_expression_index, ROM Call 0x5C7, ROM Call 0x5C8
Used by: cmd_toolbar


cmd_graph

cmd_graph Function (ROM Call 0x353)
AMS 1.01 or higher bascmd.h

void cmd_graph (CESI ExprEtc);

Executes TI-Basic 'Graph' command.

cmd_graph graphs the requested expressions or functions using the current graph mode. This function uses the Smart Graph feature (see the TI-Basic manual). It expects the following layout of the expression stack before calling (ExprEtc should point to the last item):

Graph mode | Requested layout on the expression stack
Function graphing | END_TAG var_name expression
Parametric graphing | END_TAG var_name y_expression x_expression
Polar graphing | END_TAG var_name expression
3D graphing | END_TAG y_var_name x_var_name expression

Graphing sequences and differential equations is not possible using this command. Variable names are optional, i.e. they may be omitted. In such cases, default variable names are used ("x" for function graphing, "t" for parametric graphing, "q" for polar graphing, and "x" and "y" for 3D graphing). For example, to graph the expression sin(t)+sin(2t) with respect to t (assuming that the current graph mode is set accordingly), you should do (example "Graph Function"):

// Graph a given function using the current graph settings

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

#define MIN_AMS 101           // Compile for AMS 1.01 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// Main Function
void _main(void)
{
  TRY
    push_quantum (VAR_T_TAG);
    push_parse_text ("sin(t)+sin(2t)");
    cmd_graph (top_estack);
    ngetchx ();
    cmd_disphome ();
  ONERR
  ENDTRY
}
Or, you can avoid push_parse_text by transforming the expression into RPN manually (which is very easy):

static ESQ rpn[] = {END_TAG, VAR_T_TAG, VAR_T_TAG, SIN_TAG,
  VAR_T_TAG, 2, 1, POSINT_TAG, MUL_TAG, SIN_TAG, ADD_TAG};
cmd_graph (rpn + sizeof(rpn) - 1);
All expressions entered using cmd_graph or cmd_table are remembered and assigned increasing function numbers starting with 1. The currently selected 'Y=' functions are deselected. Use cmd_clrgraph to clear the functions graphed with this command (they will also be cleared after you go to the Y= Editor application to re-enable the system 'Y=' functions).

Uses: GraphActivate, GraphOrTableCmd

See also: cmd_table, cmd_drawfunc, cmd_clrgraph


cmd_if

cmd_if Function (ROM Call 0x354)
AMS 1.01 or higher bascmd.h

void cmd_if (CESI condition);

Executes TI-Basic 'If' command.

This is an internal subroutine used by TI-Basic interpreter for executing simple If instructions (skips the next expression or tokenized TI-Basic statement if the condition is not true). As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See the if and else keywords to learn how to implement conditional execution in the C language.

Uses: next_expression_index, push_internal_simplify, top_estack, NG_control, ROM Call 0x5C8

See also: cmd_ifthen


cmd_ifthen

cmd_ifthen Function (ROM Call 0x355)
AMS 1.01 or higher bascmd.h

void cmd_ifthen (CESI condition);

Executes TI-Basic 'If'...'Then' command.

cmd_ifthen is an internal subroutine used by TI-Basic interpreter for executing 'If'...'EndIf' and 'If'...'Else'...'EndIf' blocks (searches for a matching 'Else', 'ElseIf' or 'EndIf' instruction and transfers the control there if the condition is not true). As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See the if and else keywords to learn how to implement conditional execution in the C language.

Uses: next_expression_index, push_internal_simplify, top_estack, index_after_match_endtag, NG_control, ROM Call 0x5C8

See also: cmd_else, cmd_if


cmd_input

cmd_input Function (ROM Call 0x356)
AMS 1.01 or higher bascmd.h

void cmd_input (CESI PromptAndVar);

Executes TI-Basic 'Input' command.

If PromptAndVar points to END_TAG, cmd_input pauses the program, performs cmd_dispg, and lets the user update the system coordinates "xc" and "yc" (as well as "rc" and "theta_c" for polar coordinate mode) by positioning the graph cursor.

If PromptAndVar points to a string item or to a variable tag, cmd_input works exactly like cmd_inputstr, but it treats the user response as an expression instead of a string (cmd_inputstr always stores the response as a string).

Uses: ER_catch, ER_success, ER_throwVar, ERD_dialog, next_expression_index, NG_tokenize, push_quantum, top_estack, EV_captureEvents, EV_eventLoop, EV_paintWindows, EV_setFKeyState, EV_startApp, ScrToHome, ScrToWin, strlen, TE_close, TE_focus, TE_isBlank, TE_open, TE_reopen, TE_select, TE_shrinkWrap, TE_unfocus, EV_currentApp, EV_quit, NG_control, push_simplify, VarStore, WinActivate, WinBackupToScr, WinChar, WinClr, WinDeactivate, WinFill, WinHide, WinScrollV, WinStrXY, WinWidth, _ds16u16, _du32u32, ROM Call 0x455, ROM Call 0x471, ROM Call 0x5CA


cmd_inputstr

cmd_inputstr Function (ROM Call 0x357)
AMS 1.01 or higher bascmd.h

void cmd_inputstr (ESI PromptAndVar);

Executes TI-Basic 'InputStr' command.

If PromptAndVar points to a string item (more precise, to its STR_TAG), cmd_inputstr first displays the current contents of the TI-Basic Program I/O Screen window, pauses the program, displays the prompt string pointed to by PromptAndVar on the Program I/O Screen, waits for the user to enter a response, and stores the response in a TI-Basic variable whose name is given on the expression stack just below the expression pointed to by PromptAndVar. This is illustated in the following example, which stores the user's name in a TI-Basic variable named "x":

push_quantum (VAR_X_TAG);
push_zstr ("Enter your name:");
cmd_inputstr (top_estack);
If PromptAndVar points directly to a variable tag, "?" is displayed as a prompt.

Note: cmd_inputstr is not the recommended way for inputing data from the keyboard into the program. It is limited to the TI-Basic Program I/O Screen window, and it stores the result in TI-Basic variables, which is not so useful in C programs (i.e. you need to import the value of a TI-Basic variable into the program, which is not so straightforward). See the keyboard input section of the FAQ list for explanation of much better ways to enter data from the keyboard.

Uses: ER_catch, ER_success, ER_throwVar, ERD_dialog, next_expression_index, NG_tokenize, push_quantum, top_estack, EV_captureEvents, EV_eventLoop, EV_paintWindows, EV_setFKeyState, EV_startApp, ScrToHome, ScrToWin, strlen, TE_close, TE_focus, TE_isBlank, TE_open, TE_reopen, TE_select, TE_shrinkWrap, TE_unfocus, EV_currentApp, EV_quit, NG_control, push_simplify, VarStore, WinActivate, WinBackupToScr, WinChar, WinClr, WinDeactivate, WinFill, WinHide, WinScrollV, WinStrXY, WinWidth, _ds16u16, _du32u32, ROM Call 0x455, ROM Call 0x471, ROM Call 0x5CA


cmd_line

cmd_line Function (ROM Call 0x358)
AMS 1.01 or higher bascmd.h

void cmd_line (CESI x1, CESI y1, CESI x2, CESI y2, CESI drawmode);

Executes TI-Basic 'Line' command.

cmd_line displays the Graph Screen and draws, erases, or inverts a line segment on it. The parameters x1, y1, x2, y2, and drawmode should point to five items on the expression stack, which represent respectively the coordinates of the starting point, the ending point, and the drawing mode. All coordinates are integer or floating point values which are relative to the current window settings (you can change them using the "Window Editor" application, or directly by storing values in system variables "xmin" etc., using the VarStore function). The parameter drawmode should point to one of the following values:

1 | Draws the line.
0 | Erases the line.
-1 | Inverts pixels along the line.

See also cmd_pxlline, which uses pixel coordinates instead of window-relative ones, and DrawLine (or DrawClipLine) for much faster low-level line drawing (independently of the Graph Screen).

Uses: GetValue, gr_active, ForceFloat, GraphActivate, GrClipLine, XCvtFtoP, YCvtFtoP, MakeWinRect, WinAttr, WinLine

See also: cmd_pxlline, DrawLine, DrawClipLine, cmd_circle, cmd_linehorz, cmd_linevert, cmd_pton, cmd_ptoff, cmd_ptchg


cmd_linehorz

cmd_linehorz Function (ROM Call 0x359)
AMS 1.01 or higher bascmd.h

void cmd_linehorz (CESI y, CESI drawmode);

Executes TI-Basic 'LineHorz' command.

cmd_linehorz displays the Graph Screen and draws, erases, or inverts a horizontal line on it. The parameters y and drawmode should point to two items on the expression stack, which represent respectively the y coordinate of the line and the drawing mode. The y coordinate is an integer or floating point value which is relative to the current window settings (you can change them using the "Window Editor" application, or directly by storing values in system variables "xmin" etc., using the VarStore function). The parameter drawmode should point to one of the following values:

1 | Draws the line.
0 | Erases the line.
-1 | Inverts pixels along the line.

See also cmd_pxlhorz, which uses pixel coordinates instead of window-relative ones, and DrawLine (or DrawClipLine) for much faster low-level line drawing (independently of the Graph Screen).

Uses: GetValue, gr_active, ForceFloat, GraphActivate, YCvtFtoP, MakeWinRect, WinAttr, WinLine

See also: cmd_pxlhorz, DrawLine, DrawClipLine, cmd_linevert, cmd_line


cmd_linetan

cmd_linetan Function (ROM Call 0x35A)
AMS 1.01 or higher bascmd.h

void cmd_linetan (CESI expr, CESI x);

Executes TI-Basic 'LineTan' command.

cmd_linetan displays the Graph Screen and draws a tangent line to the expression pointed to by expr (the expression is assumed to be a function which uses x as the independent variable) at the point specified by the floating point item pointed to by x.

Uses: ER_catch, ER_success, ER_throwVar, NG_approxESI, push_expression, push_Float, push_quantum, push_quantum_pair, top_estack, gr_active, OSCheckBreak, is_transfinite, ForceFloat, GraphActivate, GrLineFlt, QSkipGraphErr, XCvtPtoF, YCvtPtoF

See also: cmd_slpline, cmd_line, cmd_drawfunc


cmd_linevert

cmd_linevert Function (ROM Call 0x35B)
AMS 1.01 or higher bascmd.h

void cmd_linevert (CESI x, CESI drawmode);

Executes TI-Basic 'LineVert' command.

cmd_linehorz displays the Graph Screen and draws, erases, or inverts a vertical line on it. The parameters x and drawmode should point to two items on the expression stack, which represent respectively the x coordinate of the line and the drawing mode. The x coordinate is an integer or floating point value which is relative to the current window settings (you can change them using the "Window Editor" application, or directly by storing values in system variables "xmin" etc., using the VarStore function). The parameter drawmode should point to one of the following values:

1 | Draws the line.
0 | Erases the line.
-1 | Inverts pixels along the line.

See also cmd_pxlvert, which uses pixel coordinates instead of window-relative ones, and DrawLine (or DrawClipLine) for much faster low-level line drawing (independently of the Graph Screen).

Uses: GetValue, gr_active, ForceFloat, GraphActivate, XCvtFtoP, MakeWinRect, WinAttr, WinLine

See also: cmd_pxlvert, DrawLine, DrawClipLine, cmd_linehorz, cmd_line


cmd_linreg

cmd_linreg Function (ROM Call 0x35C)
AMS 1.01 or higher bascmd.h

void cmd_linreg (ESI RegData);

Executes TI-Basic 'LinReg' command.

cmd_linreg calculates a linear regression and updates all statistics variables (see TI-Basic manual for more info). The RegData parameter must point to a structure on the expression stack which describes where the actual data is stored. This structure may have one of the following four layouts (RegData should point to the last item):

NOTHING_TAG NOTHING_TAG NOTHING_TAG y_list_name x_list_name
NOTHING_TAG NOTHING_TAG freqs_name y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name NOTHING_TAG y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name freqs_name y_list_name x_list_name

x_list_name is the VAT symbol name (see SYMSTR and Tags for more info) of a TI-Basic list variable which contains the x values. y_list_name is the VAT symbol name of a TI-Basic list variable which contains the y values. freqs_name (if present) is the VAT symbol name of a TI-Basic list variable which contains the frequencies (all frequencies are assumed to be 1 if freqs_name is not present). categories_name (if present) is the VAT symbol name of a TI-Basic list which contains the category code for each item. categories_list represents a list of integer items which determine which categories will be included (this makes sense only when categories_name is used).

For example, assuming that two TI-Basic list variables "xdata" and "ydata" contain the x and y values, you can calculate a simple regression using the following code fragment:

push_quantum (NOTHING_TAG);
push_quantum (NOTHING_TAG);
push_quantum (NOTHING_TAG);
push_expression (SYMSTR ("ydata"));
push_expression (SYMSTR ("xdata"));
cmd_linreg (top_estack);
After this, you can retrieve the calculated regression data by accessing TI-Basic system variables like "regCoef" directly (using VarRecall, for example), or you can display the calculated data using cmd_showstat.

The symbol names x_list_name, y_list_name, freqs_name, and categories_name may also be "c1".."c99". In this case, they represent columns in the last data variable shown in the Data/Matrix editor. In all cases, the lists represented by x_list_name, y_list_name, freqs_name, and categories_name must have the same dimension.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_quadreg, cmd_cubicreg, cmd_quartreg, cmd_powerreg, cmd_expreg, cmd_lnreg, cmd_sinreg, cmd_onevar, cmd_twovar, cmd_medmed, cmd_logistic


cmd_lnreg

cmd_lnreg Function (ROM Call 0x35D)
AMS 1.01 or higher bascmd.h

void cmd_lnreg (ESI RegData);

Executes TI-Basic 'LnReg' command.

cmd_lnreg calculates a logarithmic regression and updates all statistics variables (see TI-Basic manual for more info). RegData must point to a structure on the expression stack which describes where the actual data is stored. See cmd_linreg for more info.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_linreg, cmd_quadreg, cmd_cubicreg, cmd_quartreg, cmd_powerreg, cmd_expreg, cmd_sinreg, cmd_onevar, cmd_twovar, cmd_medmed, cmd_logistic


cmd_local

cmd_local Function (ROM Call 0x35E)
AMS 1.01 or higher bascmd.h

void cmd_local (CESI VarNameList);

Executes TI-Basic 'Local' command.

cmd_local creates a temporary folder (see TempFolderName for more info about temporary folders), then creates one or more VAT entries in it. This function expects the following layout on the expression stack:

END_TAG symname_n ... symname_2 symname_1

symname_1, symname_2, etc. are VAT symbol names (see SYMSTR and Tags for more info) of variables which will be created in the temporary folder. The parameter VarNameList should point to the tag of the last item. This function is used by the TI-Basic interpreter for declaring TI-Basic variables as local ones (they are kept in temporary folders).

Uses: next_expression_index, push_expression, top_estack, is_pathname, AddSymToFolder, CheckReservedName, DerefSym, FindSymInFolder, TempFolderName, ROM Call 0x5C8


cmd_lock

cmd_lock Function (ROM Call 0x35F)
AMS 1.01 or higher bascmd.h

void cmd_lock (CESI VarNameList);

Executes TI-Basic 'Lock' command.

cmd_lock locks one or more TI-Basic variables (i.e. VAT symbols). It expects the following layout on the expression stack:

END_TAG symname_n ... symname_2 symname_1

symname_1, symname_2, etc. are VAT symbol names (see SYMSTR and Tags for more info) of variables which should be locked. The parameter VarNameList should point to the tag of the last item.

Uses: next_expression_index, CheckSysFunc, DerefSym, VarRecall

See also: cmd_unlock, cmd_archive, cmd_unarchiv


cmd_logistic

cmd_logistic Function (ROM Call 0x360)
AMS 1.01 or higher bascmd.h

void cmd_logistic (ESI RegData);

Executes TI-Basic 'Logistic' command.

cmd_logistic calculates a logistic regression and updates all statistics variables (see TI-Basic manual for more info). The RegData parameter must point to a structure on the expression stack which describes where the actual data is stored. This structure may have one of the following eight layouts (RegData should point to the last item):

NOTHING_TAG NOTHING_TAG NOTHING_TAG NOTHING_TAG y_list_name x_list_name
NOTHING_TAG NOTHING_TAG NOTHING_TAG iterations y_list_name x_list_name
NOTHING_TAG NOTHING_TAG freqs_name NOTHING_TAG y_list_name x_list_name
NOTHING_TAG NOTHING_TAG freqs_name iterations y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name NOTHING_TAG iterations y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name freqs_name iterations y_list_name x_list_name

x_list_name is the VAT symbol name (see SYMSTR and Tags for more info) of a TI-Basic list variable which contains the x values. y_list_name is the VAT symbol name of a TI-Basic list variable which contains the y values. iterations is an integer expression; if it is omitted, 64 is assumed. It specifies the maximum number of iterations in which a solution will be attempted (larger values result in better accuracy but longer execution times, and vice versa). freqs_name (if present) is the VAT symbol name of a TI-Basic list variable which contains the frequencies (all frequencies are assumed to be 1 if freqs_name is not present). categories_name (if present) is the VAT symbol name of a TI-Basic list which contains the category of each item. categories_list represents a list of integer items determining which categories will be included (this makes sense only when categories_name is used).

See cmd_linreg for more information.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_linreg, cmd_quadreg, cmd_cubicreg, cmd_quartreg, cmd_powerreg, cmd_expreg, cmd_lnreg, cmd_sinreg, cmd_onevar, cmd_twovar, cmd_medmed


cmd_lu_fact

cmd_lu_fact Function (ROM Call 0x484)
AMS 2.00 or higher bascmd.h

void cmd_lu_fact (ESI mat, ESI lSymName, ESI uSymName, ESI pSymName, ESI tol);

Executes TI-Basic 'LU' command.

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, get_matrix_indices, is_constant, NG_control, push_lu_fact, push0, push1, replace_top2_with_prod, push_dimension, push_max1, push_rownorm, push_assignment, is_free_of_tag, is_matrix, push_expression, push_offset_array, push_quantum, top_estack, _bcd_math

See also: cmd_qr_fact


cmd_medmed

cmd_medmed Function (ROM Call 0x361)
AMS 1.01 or higher bascmd.h

void cmd_medmed (ESI RegData);

Executes TI-Basic 'MedMed' command.

cmd_medmed calculates the median-median line and updates all statistics variables (see TI-Basic manual for more info). The RegData parameter must point to a structure on the expression stack which describes where the actual data is stored. See cmd_linreg for more info.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_linreg, cmd_quadreg, cmd_cubicreg, cmd_quartreg, cmd_powerreg, cmd_expreg, cmd_lnreg, cmd_sinreg, cmd_onevar, cmd_twovar, cmd_logistic


cmd_movevar

cmd_movevar Function (ROM Call 0x362)
AMS 1.01 or higher bascmd.h

void cmd_movevar (SYM_STR SymName, SYM_STR SrcFolder, SYM_STR DestFolder);

Executes TI-Basic 'MoveVar' command.

cmd_movevar moves a TI-Basic variable from one folder to another. The parameter SymName should point to the variable tag of the symbol which will be moved (see SYMSTR). SrcFolder and DestFolder should point to the variable tags of the source and the destination folders, respectively. If the destination folder does not exist, cmd_movevar creates it. This function may be used instead of the low-level function SymMove from the vat.h header file.

This function may cause heap compression.

Uses: ER_throwVar, strcat, strcmp, strlen, ParseSymName, CheckSysFunc, DerefSym, FolderAdd, FolderFind, SymMove, SymSysVar, VarRecall

See also: cmd_copyvar, cmd_rename, SymMove


cmd_newdata

cmd_newdata Function (ROM Call 0x363)
AMS 1.01 or higher bascmd.h

void cmd_newdata (CESI Data);

Executes TI-Basic 'NewData' command.

cmd_newdata creates a TI-Basic data variable. This function expects the following layout on the expression stack:

END_TAG listexpr_n ... listexpr_2 listexpr_1 symname

listexpr_1, listexpr_2, etc. are list expressions (they may be symbol names of TI-Basic list variables as well), and symname is the VAT symbol name (see SYMSTR and Tags for more info) of the TI-Basic data variable which will be created. The parameter Data should point to the tag of the last item on the expression stack. The data variable will be built up from these list expressions; each list will become one column of the data variable. There must be at least one list. This function also makes the new variable the current one in the Data/Matrix editor. See the TI-Basic manual for more info.

Uses: HeapAlloc, HeapFree, HeapFreeIndir, HeapLock, HeapRealloc, HeapUnlock, remaining_element_count, ER_catch, ER_success, ER_throwVar, check_estack_size, HToESI, next_expression_index, top_estack, memcpy, memset, sprintf, CheckGraphRef, estack_max_index, gen_version, primary_tag_list, statFree, AddSymToFolder, checkCurrent, DerefSym, HSymDel, HSYMtoName, SymFind, VarStore, _bcd_math, ROM Call 0x459, ROM Call 0x45A
Used by: cmd_blddata, spike_geo_titles, spike_optionD


cmd_newfold

cmd_newfold Function (ROM Call 0x364)
AMS 1.01 or higher bascmd.h

void cmd_newfold (SYM_STR FolderName);

Executes TI-Basic 'NewFold' command.

cmd_newfold creates a new folder, then sets the current folder to that folder. The parameter FolderName should point to the variable tag of the name of the folder to be created (see SYMSTR). This function may be used as a high-level alternative for the low-level functions FolderAdd and FolderCur from the vat.h header file.

Uses: ER_throwVar, ST_folder, ParseSymName, CheckSysFunc, FolderAdd, FolderCur, IsMainFolderStr

See also: cmd_delfold, FolderAdd, FolderCur


cmd_newpic

cmd_newpic Function (ROM Call 0x365)
AMS 1.01 or higher bascmd.h

void cmd_newpic (ESI Matrix, SYM_STR PicName, ESI MaxRow, ESI MaxCol);

Executes TI-Basic 'NewPic' command.

cmd_newpic creates a new TI-Basic PIC variable based on data from a matrix on the expression stack (see TI-Basic manual for more info). The parameter Matrix should point to the tag of an n x 2 matrix on the expression stack (its elements must be integer items). Each row in the matrix represents a pixel. Pixel coordinates starts at (0,0). PicName should point to the variable tag of the symbol (i.e. TI-Basic variable) which will be created (see SYMSTR). If the symbol already exists, cmd_newpic replaces it. The parameters MaxRow and MaxCol should point to two integer items which determine the height and the width of the created PIC variable, i.e. the maximum boundary limits for it. Optionally, either MaxRow or MaxCol may point to END_TAG. In this case, default values will be used, which are determined from the minimum area required for the matrix values.

This function may cause heap compression.

Uses: ER_catch, ER_success, ER_throwVar, GetValue, next_expression_index, DerefSym, VarStore, MakeWinRect, WinBitmapGet, WinBitmapSize, WinOpen, WinPixSet, WinRemove


cmd_newplot

cmd_newplot Function (ROM Call 0x366)
AMS 1.01 or higher bascmd.h

void cmd_newplot (ESI PlotData);

Executes TI-Basic 'NewPlot' command.

cmd_newplot creates a new statistical plot definition (see TI-Basic manual for more info).The PlotData parameter must point to a structure on the expression stack which describes where the actual data is stored (more precisely, it must point to the last item of it). It is possible to create five types of statistical plots: scatter plot, X-Y line plot, box plot, histogram and modified box plot. There is an item called type_id on the expression stack, which determines the type of the plot. It must be an integer item, with one of the following values:

1 | Scatter plot
2 | X-Y line plot
3 | Box plot
4 | Histogram
5 | Modified box plot

The actual expected layout of the structure on the expression stack depends on the type of the statistical plot. For scatter and X-Y line plots, this structure may have one of the following four layouts:

END_TAG y_list_name x_list_name type_id plot_no
END_TAG mark_id NOTHING_TAG NOTHING_TAG NOTHING_TAG y_list_name x_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name NOTHING_TAG y_list_name x_list_name type_id plot_no
END_TAG mark_id END_TAG categories_list LIST_TAG categories_name NOTHING_TAG y_list_name x_list_name type_id plot_no

plot_id is an integer item (which must belong to the range from 1 to 9) which represents the identification number of the plot (this number is used in cmd_plotson and cmd_plotsoff). x_list_name is the VAT symbol name (see SYMSTR and Tags for more info) of a TI-Basic list variable which contains the x values. y_list_name is the VAT symbol name of a TI-Basic list variable which contains the y values. categories_name (if present) is the VAT symbol name of a TI-Basic list variable which contains the category code for each item. categories_list represents a list of integer items which determine which categories will be included (this makes sense only if categories_name is used).

In scatter plots, the data points from the lists of x and y items are simply plotted as unconnected coordinate pairs. In X-Y line plots, the data points are plotted and connected in the order in which they appear in x and y lists. The plotted points are shown with the symbol determined by the mark_id item. It must be an integer item, containing one of the following values (a default value of 1 is used if it is omitted):

1 | box (a small empty square)
2 | cross (x)
3 | plus (+)
4 | square (a small filled square)
5 | dot

For box plots, the structure on the expressions stack may have one of the following four layouts:

END_TAG data_list_name type_id plot_no
END_TAG freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG data_list_name type_id plot_no

data_list_name is the VAT symbol name of a TI-Basic list variable which contains the data values. freqs_name (if present) is the VAT symbol name of a TI-Basic list variable which contains the frequencies (all frequencies are assumed to be 1 if freqs_name is not present). Other items have the same meaning as for scatter and X-Y line plots.

Box plots plot the data with respect to the minimum and maximum data points (minX and maxX) in the set. A drawn box is defined by its first quartile (Q1), median (Med) and third quartile (Q3). Whiskers extend from minX to Q1 and from Q3 to maxX.

For modified box plots, the structure on the expressions stack may have one of the following eight layouts:

END_TAG data_list_name type_id plot_no
END_TAG mark_id NOTHING_TAG NOTHING_TAG NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG mark_id NOTHING_TAG NOTHING_TAG freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG mark_id END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG mark_id END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG data_list_name type_id plot_no

A modified box plot is very similar to an ordinary box plot, but it excludes all points outside the interval [Q1-X, Q3+X] where X is defined as 3*(Q3-Q1)/2. These points, called outliers, are plotted individually beyond the box plot's whiskers, using the mark determined by mark_id (default of 1 is used if omitted). The possible values of mark_id are the same as with scatter and X-Y line plots.

For histograms, the structure on the expressions stack may have one of the following eight layouts:

END_TAG data_list_name type_id plot_no
END_TAG freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG bck_width NOTHING_TAG NOTHING_TAG NOTHING_TAG NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG bck_width NOTHING_TAG NOTHING_TAG NOTHING_TAG freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG data_list_name type_id plot_no
END_TAG bck_width NOTHING_TAG END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG data_list_name type_id plot_no
END_TAG bck_width NOTHING_TAG END_TAG categories_list LIST_TAG categories_name freqs_name NOTHING_TAG data_list_name type_id plot_no

The meaning of all items (except bck_width) is the same as for box and modified box plots. bck_width is an integer item which determines the width of each bar. In histograms, the x axis is divided into equal widths called buckets or bars. The height of each bar indicates how many data points fall within the bar's range. See the TI-Basic manual for more info.

If everything written above seems too complicated for you, here is a simple example. Assuming that two TI-Basic list variables "xdata" and "ydata" contain the x and y values, and assuming that the Graph window variables are set accordingly, the following code fragment will create and display the X-Y line diagram of the given data using cross marks:

push_longint (4);
push_quantum (NOTHING_TAG);
push_quantum (NOTHING_TAG);
push_quantum (NOTHING_TAG);
push_expression (SYMSTR ("ydata"));
push_expression (SYMSTR ("xdata"));
push_shortint (1);
push_shortint (1);
cmd_newplot (top_estack);
cmd_dispg ();
Note that cmd_newplot only creates a plot. To actually display it, you must activate the Graph screen (using cmd_dispg, for example).

The symbol names x_list_name, y_list_name, data_list_name, freqs_name, and categories_name may also be "c1".."c99". In this case, they represent columns in the last data variable shown in the Data/Matrix editor. In all cases, the lists represented by x_list_name, y_list_name, data_list_name, freqs_name, and categories_name must have the same dimension.

Uses: GetValue, next_expression_index, TokenizeSymName, top_estack, gr_active, memset, ParseSymName, PlotGet, PlotPut, push1

See also: cmd_plotson, cmd_plotsoff


cmd_newprob

cmd_newprob Function (ROM Call 0x367)
AMS 1.01 or higher bascmd.h

void cmd_newprob (void);

Executes TI-Basic 'NewProb' command.

cmd_newprob performs a variety of operations that let you begin a new problem from a cleared state without resetting the memory. It clears all single-character (a-z) TI-Basic variables in the current folder (unless the variables are locked or archived), turns off all functions and stat plots in the current graph mode, clears the error flag, and performs cmd_clrdraw, cmd_clrgraph, cmd_clrhome, cmd_clrio and cmd_clrtable.

Uses: cmd_clrdraw, cmd_clrerr, cmd_clrgraph, cmd_clrhome, cmd_clrio, cmd_clrtable, cmd_fnoff, cmd_plotsoff, ER_catch, ER_success, DerefSym, HSymDel, SymFind


cmd_onevar

cmd_onevar Function (ROM Call 0x368)
AMS 1.01 or higher bascmd.h

void cmd_onevar (ESI StatData);

Executes TI-Basic 'OneVar' command.

cmd_onevar calculates one-variable statistics and updates all statistics variables (see TI-Basic manual for more info). The StatData parameter must point to a structure on the expression stack which describes where the actual data is stored. This structure may have one of the following four layouts (StatData should point to the last item):

NOTHING_TAG NOTHING_TAG NOTHING_TAG list_name
NOTHING_TAG NOTHING_TAG freqs_name list_name
END_TAG categories_list LIST_TAG categories_name NOTHING_TAG list_name
END_TAG categories_list LIST_TAG categories_name freqs_name list_name

list_name is the VAT symbol name (see SYMSTR and Tags for more info) of a TI-Basic list variable which contains the values. freqs_name (if present) is the VAT symbol name of a TI-Basic list variable which contains the frequencies (all frequencies are assumed to be 1 if freqs_name is not present). categories_name (if present) is the VAT symbol name of a TI-Basic list which contains the category code for each item. categories_list represents a list of integer items which determine which categories will be included (this makes sense only when categories_name is used).

For example, assuming that the TI-Basic list variable "dataval" contains statistical data, you can calculate simple one-variable statistics using the following code fragment:

push_quantum (NOTHING_TAG);
push_quantum (NOTHING_TAG);
push_quantum (NOTHING_TAG);
push_expression (SYMSTR ("datavals"));
cmd_onevar (top_estack);
After this, you can retrieve the calculated regression data by accessing TI-Basic system variables like "minX" directly (using VarRecall, for example), or you can display the calculated data using cmd_showstat.

The symbol names list_name, freqs_name, and categories_name may also be "c1".."c99". In this case, they represent columns in the last data variable shown in the Data/Matrix editor. In all cases, the lists represented by list_name, freqs_name, and categories_name must have the same dimension.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_twovar, cmd_linreg, cmd_quadreg, cmd_cubicreg, cmd_quartreg, cmd_powerreg, cmd_expreg, cmd_lnreg, cmd_sinreg, cmd_medmed, cmd_logistic


cmd_output

cmd_output Function (ROM Call 0x369)
AMS 1.01 or higher bascmd.h

void cmd_output (CESI Row, CESI Column, CESI Expr);

Executes TI-Basic 'Output' command.

cmd_output first displays the current contents of the TI-Basic Program I/O Screen window. Then, the expression (or string, if Expr points to a STR_TAG) pointed to by Expr is displayed on the TI-Basic Program I/O Screen window at the TI-Basic text coordinates determined by expressions (usually numbers) pointed to by Row and Column. If "Pretty Print" in current calculator mode settings is turned on, expressions are displayed in mathematical notation.

Uses: HeapFree, ER_catch, ER_success, ER_throwVar, estack_to_short, Parms2D, Parse1DExpr, Parse2DExpr, Print2DExpr, top_estack, EV_setFKeyState, EV_startApp, ScrToHome, ScrToWin, TE_unfocus, EV_currentApp, EV_quit, WinActivate, WinAttr, WinBackupToScr, WinClr, WinDeactivate, WinHeight, WinHide, WinScrollV, WinStrXY, ROM Call 0x457, ROM Call 0x471


cmd_passerr

cmd_passerr Function (ROM Call 0x36A)
AMS 1.01 or higher bascmd.h

void cmd_passerr (void);

Executes TI-Basic 'PassErr' command.

cmd_passerr does nothing if the TI-Basic system variable 'errornum' is equal to zero, else it throws an error (using the ER_throwVar function) whose number is equal to the value of the system variable "errornum".

Note: See TRY, ONERR, and ENDTRY to learn how to take control over errors while executing a C program.

Uses: ER_throwVar, top_estack, does_push_fetch, estack_to_float, is0, DerefSym, VarRecall, _bcd_math

See also: cmd_try, cmd_clrerr, cmd_exit, cmd_return


cmd_pause

cmd_pause Function (ROM Call 0x36B)
AMS 1.01 or higher bascmd.h

void cmd_pause (CESI Expr);

Executes TI-Basic 'Pause' command.

cmd_pause suspends the program execution until 'ENTER' is pressed. If Expr points to END_TAG, cmd_output does nothing more. But, if Expr points to an expression, it displays the current contents of the TI-Basic Program I/O Screen window and displays the expression pointed to by Expr at the current TI-Basic text coordinates. If "Pretty Print" in current calculator mode settings is turned on, expressions are displayed in mathematical notation. If the result of the expression is too big to fit on the screen, you can use the cursor pad to scroll the display.

Uses: HeapFreeIndir, ER_catch, ER_success, ER_throwVar, Parms2D, Parse1DExpr, Parse2DExpr, Print2DExpr, top_estack, EV_paintWindows, EV_setFKeyState, EV_startApp, ScrToHome, ScrToWin, kbhit, ngetchx, ST_busy, strlen, idle, off, OSTimerExpired, OSTimerRestart, XR_stringPtr, TE_unfocus, EV_currentApp, EV_quit, WinActivate, WinAttr, WinBackground, WinBackupToScr, WinCharXY, WinClr, WinDeactivate, WinFill, WinHeight, WinHide, WinScrollH, WinScrollV, WinStrXY, WinWidth, ROM Call 0x457, ROM Call 0x46E, ROM Call 0x471


cmd_plotsoff

cmd_plotsoff Function (ROM Call 0x36C)
AMS 1.01 or higher bascmd.h

void cmd_plotsoff (CESI IntList);

Executes TI-Basic 'PlotsOff' command.

If IntList points to END_TAG, cmd_plotson turns off all statistical plots for graphing (note that in split-screen two-graph mode, cmd_plotson only applies to the active graph). If IntList points to an integer item in the range from 1 to 99, cmd_plotson turns off the specified statistical plot, and repeats this task for all expressions on the expression stack below IntList, until END_TAG is reached.

Uses: GetValue, next_expression_index, gr_active, PlotLookup
Used by: cmd_newprob

See also: cmd_plotson, cmd_newplot


cmd_plotson

cmd_plotson Function (ROM Call 0x36D)
AMS 1.01 or higher bascmd.h

void cmd_plotson (CESI IntList);

Executes TI-Basic 'PlotsOn' command.

If IntList points to END_TAG, cmd_plotson turns on all statistical plots for graphing (note that in split-screen two-graph mode, cmd_plotson only applies to the active graph). If IntList points to an integer item in the range from 1 to 99, cmd_plotson turns on the specified statistical plot, and repeats this task for all expressions on the expression stack below IntList, until END_TAG is reached.

Uses: GetValue, next_expression_index, gr_active, PlotLookup

See also: cmd_plotsoff, cmd_newplot


cmd_popup

cmd_popup Function (ROM Call 0x36E)
AMS 1.01 or higher bascmd.h

void cmd_popup (ESI ItemList, ESI SymName);

Executes TI-Basic 'Popup' command.

cmd_popup displays a popup menu containing character strings from the list of strings pointed to by ItemList (it should point to the tag of the list, i.e. to the LIST_TAG), waits for the user to select an item, and stores the index of the selection in the TI-Basic variable determined by the SymName parameter (see SYMSTR). If the variable does not exist, it will be created. Each item in the list expression must be a string. Also, both the ItemList and SymName entries must be on the expression stack, and the SymName entry must be exactly below the ItemList entry on the expression stack (the ItemList entry is usually on the top of the expression stack). As this function serves mainly as an internal subroutine for executing the TI-Basic Popup command, such a limitation is not so unusual.

Note: See PopupNew, PopupDo, and other functions from menus.h, for much more flexible methods to create popup menus in a C program.

Uses: HeapFree, HeapFreeIndir, ER_catch, ER_success, ER_throwVar, GetValue, HToESI, next_expression_index, push_quantum, push_quantum_pair, top_estack, PopupAddText, PopupDo, PopupNew, strlen, primary_tag_list, push_simplify, DerefSym, VarRecall, VarStore, ROM Call 0x480

See also: cmd_toolbar, menus.h


cmd_powerreg

cmd_powerreg Function (ROM Call 0x36F)
AMS 1.01 or higher bascmd.h

void cmd_powerreg (ESI RegData);

Executes TI-Basic 'PowerReg' command.

cmd_powerreg calculates a power regression and updates all statistics variables (see TI-Basic manual for more info). The RegData parameter must point to a structure on the expression stack which describes where the actual data is stored. See cmd_linreg for more info.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_linreg, cmd_quadreg, cmd_cubicreg, cmd_quartreg, cmd_expreg, cmd_lnreg, cmd_sinreg, cmd_onevar, cmd_twovar, cmd_medmed, cmd_logistic


cmd_printobj

cmd_printobj Function (ROM Call 0x370)
AMS 1.01 or higher bascmd.h

void cmd_printobj (SYM_STR SymName);

Executes TI-Basic 'PrintObj' command.

cmd_printobj sends the variable whose name is pointed to by SymName (a VAT string, see SYMSTR) as a "Print Object" through the link interface. See the TI-Basic manual (chapter "Creating a Lab Report") for more info about Print Objects.

Uses: push_expression, push_quantum


cmd_prompt

cmd_prompt Function (ROM Call 0x371)
AMS 1.01 or higher bascmd.h

void cmd_prompt (CESI VarList);

Executes TI-Basic 'Prompt' command.

cmd_prompt assumes that VarList points to a variable tag. It displays the current contents of the TI-Basic Program I/O Screen window, then displays a prompt on the Program I/O Screen for the variable pointed to by VarList, using its own name as the prompt (with a question mark appended after the name). Then, it waits for a user response, and stores the entered expression in the corresponding variable. This task is repeated for all entries on the expression stack below VarList, until END_TAG is reached.

Uses: HeapFree, ER_catch, ER_success, ER_throwVar, ERD_dialog, next_expression_index, NG_tokenize, Parse1DExpr, push_quantum, top_estack, EV_captureEvents, EV_eventLoop, EV_paintWindows, EV_setFKeyState, EV_startApp, ScrToHome, ScrToWin, strcat, strlen, TE_close, TE_focus, TE_isBlank, TE_open, TE_reopen, TE_select, TE_shrinkWrap, TE_unfocus, EV_currentApp, EV_quit, NG_control, push_simplify, VarStore, WinActivate, WinBackupToScr, WinChar, WinClr, WinDeactivate, WinFill, WinHide, WinScrollV, WinStrXY, WinWidth, _ds16u16, _du32u32, ROM Call 0x471, ROM Call 0x5CA


cmd_ptchg

cmd_ptchg Function (ROM Call 0x372)
AMS 1.01 or higher bascmd.h

void cmd_ptchg (CESI xValOrList, CESI yValOrList);

Executes TI-Basic 'PtChg' command.

cmd_ptchg acts like cmd_pton, but inverts the state of the pixel instead of turning it on unconditionally.

Uses: GetValue, next_expression_index, gr_active, ForceFloat, GraphActivate, XCvtFtoP, YCvtFtoP, WinAttr, WinDupStat, WinPixSet, _bcd_math

See also: cmd_pton, cmd_ptoff, cmd_pxlchg


cmd_ptoff

cmd_ptoff Function (ROM Call 0x373)
AMS 1.01 or higher bascmd.h

void cmd_ptoff (CESI xValOrList, CESI yValOrList);

Executes TI-Basic 'PtOff' command.

cmd_ptoff acts like cmd_pton, but turns off the pixel instead of turning it on.

Uses: GetValue, next_expression_index, gr_active, ForceFloat, GraphActivate, XCvtFtoP, YCvtFtoP, WinAttr, WinDupStat, WinPixSet, _bcd_math

See also: cmd_pton, cmd_ptchg, cmd_pxloff


cmd_pton

cmd_pton Function (ROM Call 0x374)
AMS 1.01 or higher bascmd.h

void cmd_pton (CESI xValOrList, CESI yValOrList);

Executes TI-Basic 'PtOn' command.

cmd_pton displays the Graph Screen and turns on the screen pixel nearest to the window coordinates (x,y) which are relative to the current window settings (you can change them using the "Window Editor" application, or directly by storing values in system variables like "xmin", using the VarStore function). The parameters xValOrList and yValOrList should either point to integer or floating point items on the expression stack, or to lists of integer or floating point items which contain x and y coordinates respectively (both lists must have an equal number of elements). In the second case, a set of corresponding pixels will be turned on, instead of just one pixel.

See also cmd_pxlon, which uses pixel coordinates instead of window relative ones, and DrawPix for much faster low-level pixel drawing (independently of the Graph Screen).

Uses: GetValue, next_expression_index, gr_active, ForceFloat, GraphActivate, XCvtFtoP, YCvtFtoP, WinAttr, WinDupStat, WinPixSet, _bcd_math

See also: cmd_ptoff, cmd_ptchg, cmd_pxlon, cmd_line, cmd_circle, DrawPix


cmd_pttext

cmd_pttext Function (ROM Call 0x375)
AMS 1.01 or higher bascmd.h

void cmd_pttext (CESI string, CESI x, CESI y);

Executes TI-Basic 'PtText' command.

cmd_pttext displays the Graph Screen and places a character string on the screen at the pixel nearest to the window coordinates (x,y), which are relative to the current window settings (you can change them using the "Window Editor" application, or directly by storing values in system variables like "xmin", using the VarStore function). The parameters x and y should point to integer or floating point items which determine the coordinates, and the parameter string should point to the tag of a string expression to be displayed.

See also cmd_pxltext, which uses pixel coordinates instead of window-relative ones, and DrawStr for much faster low-level string drawing (independently of the Graph Screen).

Uses: GetValue, gr_active, ForceFloat, GraphActivate, XCvtFtoP, YCvtFtoP, WinAttr, WinStrXY

See also: cmd_pxltext, DrawStr


cmd_pxlchg

cmd_pxlchg Function (ROM Call 0x376)
AMS 1.01 or higher bascmd.h

void cmd_pxlchg (CESI yValOrList, CESI xValOrList);

Executes TI-Basic 'PxlChg' command.

cmd_pxlchg acts like cmd_pxlon, but inverts the state of the pixel instead of turning it on unconditionally.

Uses: GetValue, next_expression_index, gr_active, ForceFloat, GraphActivate, XCvtFtoP, YCvtFtoP, WinAttr, WinDupStat, WinPixSet, _bcd_math

See also: cmd_pxlon, cmd_pxloff, cmd_ptchg


cmd_pxlcircle

cmd_pxlcircle Function (ROM Call 0x377)
AMS 1.01 or higher bascmd.h

void cmd_pxlcircle (CESI y, CESI x, CESI radius, CESI drawmode);

Executes TI-Basic 'PxlCircle' command.

cmd_pxlcircle displays the Graph Screen and draws, erases, or inverts a circle on it. The parameters y, x, radius and drawmode should point to four integer items on the expression stack, which represent respectively the coordinates of the center of the circle (note that the order of x and y is swapped), the radius, and the drawing mode. The coordinates are absolute pixel coordinates (independent of the current window settings), where (0,0) is the top left corner of the Graph Screen, excluding the menu area. The radius is also measured in pixels. The parameter drawmode should point to one of the following values:

1 | Draws the circle.
0 | Erases the circle.
-1 | Inverts pixels along the circle.

See also cmd_circle, which uses window-relative coordinates, and DrawClipEllipse for much faster low-level circle/ellipse drawing (independently of the Graph Screen).

Uses: GetValue, gr_active, GraphActivate, WinAttr, WinEllipse

See also: cmd_circle, DrawClipEllipse


cmd_pxlhorz

cmd_pxlhorz Function (ROM Call 0x378)
AMS 1.01 or higher bascmd.h

void cmd_pxlhorz (CESI y, CESI drawmode);

Executes TI-Basic 'PxlHorz' command.

cmd_pxlhorz displays the Graph Screen and draws, erases, or inverts a horizontal line on it. The parameters y and drawmode should point to two integer items on the expression stack, which represent respectively the y coordinate of the line and the drawing mode. The y coordinate is an absolute pixel coordinate (independent of the current window settings), where 0 is the top border of the Graph Screen, excluding the menu area. The parameter drawmode should point to one of the following values:

1 | Draws the line.
0 | Erases the line.
-1 | Inverts pixels along the line.

See also cmd_linehorz, which uses window-relative coordinates, and DrawLine (or DrawClipLine) for much faster low-level line drawing (independently of the Graph Screen).

Uses: GetValue, gr_active, GraphActivate, MakeWinRect, WinAttr, WinLine

See also: cmd_linehorz, DrawLine, DrawClipLine, cmd_pxlvert, cmd_pxlline


cmd_pxlline

cmd_pxlline Function (ROM Call 0x379)
AMS 1.01 or higher bascmd.h

void cmd_pxlline (CESI y1, CESI x1, CESI y2, CESI x2, CESI drawmode);

Executes TI-Basic 'PxlLine' command.

cmd_pxlline displays the Graph Screen and draws, erases, or inverts a line segment on it. The parameters y1, x1, y2, x2, and drawmode should point to five integer items on the expression stack, which represent respectively the coordinates of the starting point (note that the order of x and y coordinates is swapped), the ending point, and the drawing mode. The coordinates are absolute pixel coordinates (independent of the current window settings), where (0,0) is the top left corner of the Graph Screen, excluding the menu area. The parameter drawmode should point to one of the following values:

1 | Draws the line.
0 | Erases the line.
-1 | Inverts pixels along the line.

See also cmd_line, which uses window-relative coordinates, and DrawLine (or DrawClipLine) for much faster low-level line drawing (independently of the Graph Screen). Graph Screen).

Uses: GetValue, gr_active, GraphActivate, MakeWinRect, WinAttr, WinLine

See also: cmd_line, DrawLine, DrawClipLine, cmd_pxlcircle, cmd_pxlhorz, cmd_pxlvert, cmd_pxlon, cmd_pxloff, cmd_pxlchg


cmd_pxloff

cmd_pxloff Function (ROM Call 0x37A)
AMS 1.01 or higher bascmd.h

void cmd_pxloff (CESI yValOrList, CESI xValOrList);

Executes TI-Basic 'PxlOff' command.

cmd_pxloff acts like cmd_pxlon, but turns off the pixel instead of turning it on.

Uses: GetValue, next_expression_index, gr_active, ForceFloat, GraphActivate, XCvtFtoP, YCvtFtoP, WinAttr, WinDupStat, WinPixSet, _bcd_math

See also: cmd_pxlon, cmd_pxlchg, cmd_ptoff


cmd_pxlon

cmd_pxlon Function (ROM Call 0x37B)
AMS 1.01 or higher bascmd.h

void cmd_pxlon (CESI yValOrList, CESI xValOrList);

Executes TI-Basic 'PxlOn' command.

cmd_pxlon displays the Graph Screen and turns on the screen pixel at the screen coordinates (x,y). The coordinates are absolute pixel coordinates (independent of the current window settings), where (0,0) is the top left corner of the Graph Screen, excluding the menu area. The parameters yValOrList and xValOrList should either point to two integer items on the expression stack, or to list of integer items which contain y and x coordinates respectively (both lists must have an equal number of elements). In the second case, a set of corresponding pixels will be turned on instead of just one pixel.

See also cmd_pton, which uses window-relative coordinates, and DrawPix for much faster low-level pixel drawing (independently of the Graph Screen).

Uses: GetValue, next_expression_index, gr_active, ForceFloat, GraphActivate, XCvtFtoP, YCvtFtoP, WinAttr, WinDupStat, WinPixSet, _bcd_math

See also: cmd_pxloff, cmd_pxlchg, cmd_pton, cmd_pxlline, cmd_pxlcircle, DrawPix


cmd_pxltext

cmd_pxltext Function (ROM Call 0x37C)
AMS 1.01 or higher bascmd.h

void cmd_pxltext (CESI string, CESI y, CESI x);

Executes TI-Basic 'PxlText' command.

cmd_pxltext displays the Graph Screen and places a character string on the screen at the pixel (x,y). The coordinates are absolute pixel coordinates (independent of the current window settings), where (0,0) is the top left corner of the Graph Screen, excluding the menu area. The parameters y and x should point to integer items on the expression stack which determine the coordinates (note that the order of x and y coordinates is swapped), and the parameter string should point to the tag of a string expression to be displayed.

See also cmd_pttext, which uses window-relative coordinates, and DrawStr for much faster low-level string drawing (independently of the Graph Screen).

Uses: GetValue, gr_active, ForceFloat, GraphActivate, XCvtFtoP, YCvtFtoP, WinAttr, WinStrXY

See also: cmd_pttext, DrawStr


cmd_pxlvert

cmd_pxlvert Function (ROM Call 0x37D)
AMS 1.01 or higher bascmd.h

void cmd_pxlvert (CESI x, CESI drawmode);

Executes TI-Basic 'PxlVert' command.

cmd_pxlvert displays the Graph Screen and draws, erases, or inverts a vertical line on it. The parameters x and drawmode should point to two integer items on the expression stack, which represent respectively the x coordinate of the line and the drawing mode. The x coordinate is an absolute pixel coordinate (independent of the current window settings), where 0 is the left border of the Graph Screen. The parameter drawmode should point to one of the following values:

1 | Draws the line.
0 | Erases the line.
-1 | Inverts pixels along the line.

See also cmd_linehorz, which uses window-relative coordinates, and DrawLine (or DrawClipLine) for much faster low-level line drawing (independently of the Graph Screen).

Uses: GetValue, gr_active, GraphActivate, MakeWinRect, WinAttr, WinLine

See also: cmd_linevert, DrawLine, DrawClipLine, cmd_pxlhorz, cmd_pxlline


cmd_qr_fact

cmd_qr_fact Function (ROM Call 0x485)
AMS 2.00 or higher bascmd.h

void cmd_qr_fact (ESI mat, ESI qSymName, ESI rSymName, ESI tol);

Executes TI-Basic 'QR' command.

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, is_constant, NG_control, replace_top2_with_prod, push_dimension, push_float_qr_fact, push_symbolic_qr_fact, push_max1, push_rownorm, is_free_of_tag, is_matrix, top_estack, _bcd_math

See also: cmd_lu_fact


cmd_quadreg

cmd_quadreg Function (ROM Call 0x37E)
AMS 1.01 or higher bascmd.h

void cmd_quadreg (ESI RegData);

Executes TI-Basic 'QuadReg' command.

cmd_quadreg calculates a quadratic polynomial regression and updates all statistics variables (see TI-Basic manual for more info). The RegData parameter must point to a structure on the expression stack which describes where the actual data is stored. See cmd_linreg for more info.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_linreg, cmd_cubicreg, cmd_quartreg, cmd_powerreg, cmd_expreg, cmd_lnreg, cmd_sinreg, cmd_onevar, cmd_twovar, cmd_medmed, cmd_logistic


cmd_quartreg

cmd_quartreg Function (ROM Call 0x37F)
AMS 1.01 or higher bascmd.h

void cmd_quartreg (ESI RegData);

Executes TI-Basic 'QuartReg' command.

cmd_quartreg calculates a quartic polynomial regression and updates all statistics variables (see TI-Basic manual for more info). The RegData parameter must point to a structure on the expression stack which describes where the actual data is stored. See cmd_linreg for more info.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_linreg, cmd_quadreg, cmd_cubicreg, cmd_powerreg, cmd_expreg, cmd_lnreg, cmd_sinreg, cmd_onevar, cmd_twovar, cmd_medmed, cmd_logistic


cmd_randseed

cmd_randseed Function (ROM Call 0x380)
AMS 1.01 or higher bascmd.h

void cmd_randseed (CESI seed);

Executes TI-Basic 'RandSeed' command.

cmd_randseed sets the seeds for the TI-Basic random number generator. seed should point to an integer item. If it is zero, then the seeds are set to the factory defaults for the random number generator, else the value is used to calculate two seeds, which are stored in the TI-Basic system variables "seed1" and "seed2".

Note: This function controls only the TI-Basic random number generator, so it has nothing to do with the random number generator from stdlib.h (i.e. with srand). You can use the function push_rand to call the TI-Basic random number generator, but note that it is much slower than the random number generator implemented in stdlib.h.

Uses: next_expression_index, NG_approxESI, top_estack, memcpy, fpisanint, is_transfinite, estack_to_float, _bcd_math

See also: push_rand


cmd_rclgdb

cmd_rclgdb Function (ROM Call 0x381)
AMS 1.01 or higher bascmd.h

void cmd_rclgdb (SYM_STR SymName);

Executes TI-Basic 'RclGDB' command.

cmd_rclgdb restores all settings to the settings stored in the Graph database variable whose name is pointed to by SymName (a VAT string, see SYMSTR). See cmd_stogdb for more info.

Uses: gdb_recall, VarRecall

See also: cmd_stogdb


cmd_rclpic

cmd_rclpic Function (ROM Call 0x382)
AMS 1.01 or higher bascmd.h

void cmd_rclpic (SYM_STR SymName, CESI y, CESI x);

Executes TI-Basic 'RclPic' command.

cmd_rclpic displays the Graph Screen and logically ORs the picture stored in the TI-Basic variable pointed to by SymName (a VAT variable string, see SYMSTR) into the current graph screen at the pixel coordinates determined by the values pointed to by y and x, respectively. Both x and y should point to integer items. SymName should be the name of a PIC variable.

See BitmapPut for much faster low-level manipulations with bitmap pictures, independently of the Graph Screen.

Uses: GetValue, HToESI, gr_active, GraphActivate, DerefSym, VarRecall, WinBitmapPut

See also: cmd_andpic, cmd_xorpic, cmd_rplcpic, cmd_stopic, BitmapPut


cmd_rename

cmd_rename Function (ROM Call 0x383)
AMS 1.01 or higher bascmd.h

void cmd_rename (SYM_STR OldName, SYM_STR NewName);

Executes TI-Basic 'Rename' command.

cmd_rename renames a TI-Basic variable. The parameters OldName and NewName should point to the variable tags of the old name and the new name, respectively (see SYMSTR). This function may be used as a high-level alternative to the low-level function SymMove from the vat.h header file.

This function may cause heap compression.

Uses: ROM Call 0x437

See also: cmd_copyvar, cmd_movevar, SymMove


cmd_request

cmd_request Function (ROM Call 0x384)
AMS 1.01 or higher bascmd.h

void cmd_request (CESI PromptStr, SYM_STR SymName);

Executes TI-Basic 'Request' command.

cmd_request displays a dialog box without a title which contains only a request box (i.e. an input line box) and two buttons ("OK" and "Cancel"). The parameter PromptStr should point to the tag of a string item which describes a prompt of at most 20 characters which will appear in front of the request box, and SymName should point to the variable tag of the name of a TI-Basic variable (see SYMSTR). If this variable exists and contains a string value, this value will be displayed and highlighted in the input box as the default choice, else the input box will be empty. Either way, if the user presses 'ENTER', the value from the input box will be stored in this variable as a string value (it will be created if it does not exist, except if the user presses the 'ESC' key).

Note: See the dialogs.h header file for much more flexible methods to create dialog boxes.

Uses: HeapFree, HeapFreeIndir, HeapLock, HeapRealloc, DialogAdd, DialogDo, DialogNew, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, push_zstr, top_estack, memset, strcat, strlen, strncpy, NeedStack, primary_tag_list, push_simplify, DerefSym, SetOK, VarRecall, VarStore, ROM Call 0x480

See also: cmd_text, cmd_dialog, dialogs.h


cmd_return

cmd_return Function (ROM Call 0x385)
AMS 1.01 or higher bascmd.h

void cmd_return (CESI retval);

Executes TI-Basic 'Return' command.

cmd_return is an internal subroutine used by the TI-Basic interpreter for executing the Return statement (searches for a matching EndFunc or EndPrgm instruction, transfers the control there and eventually returns the expression pointed to by retval). As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See section How to make a program returning a value to learn about returning values to TI-Basic from a C program.

Uses: next_expression_index, push_internal_simplify, ROM Call 0x5C7, ROM Call 0x5C8

See also: cmd_exit, cmd_passerr


cmd_rplcpic

cmd_rplcpic Function (ROM Call 0x386)
AMS 1.01 or higher bascmd.h

void cmd_rplcpic (SYM_STR SymName, CESI y, CESI x);

Executes TI-Basic 'RplcPic' command.

cmd_rplcpic displays the Graph Screen and draws the picture stored in the TI-Basic variable pointed to by SymName (a VAT variable string, see SYMSTR) into the current graph screen at the pixel coordinates determined by the values pointed to by y and x, respectively. Both x and y should point to integer items. SymName should be the name of a PIC variable.

See BitmapPut for much faster low-level manipulations with bitmap pictures, independently of the Graph Screen.

Uses: GetValue, HToESI, gr_active, GraphActivate, DerefSym, VarRecall, WinBitmapPut

See also: cmd_rclpic, cmd_andpic, cmd_xorpic, cmd_stopic, BitmapPut


cmd_send

cmd_send Function (ROM Call 0x387)
AMS 1.01 or higher bascmd.h

void cmd_send (CESI List);

Executes TI-Basic 'Send' command.

cmd_send expects that List points to LIST_TAG. It sends the list pointed to by List to the link port to be accepted by a CBL (Calculator-Based Laboratory) device.

Uses: HeapAllocThrow, HeapFree, HeapLock, remaining_element_count, ER_catch, ER_success, ER_throwVar, LIO_Send, fabs, estack_to_float, _bcd_math

See also: cmd_get, cmd_sendcalc, cmd_sendchat


cmd_sendcalc

cmd_sendcalc Function (ROM Call 0x388)
AMS 1.01 or higher bascmd.h

void cmd_sendcalc (SYM_STR SymName);

Executes TI-Basic 'SendCalc' command.

cmd_sendcalc sends a variable (or program) pointed to by SymName (a VAT string, see SYMSTR) to the link interface, where another unit linked to the link port can receive the variable value. This function calls sendcalc from the link.h header file. If you send a variable from a TI-89 or TI-92 Plus to a TI-92, an error occurs if the TI-92 executes the GetCalc command from TI-Basic. In this case, the sending unit must use cmd_sendchat instead.

Uses: ER_catch, ER_success, ER_throwVar, OSLinkClose, OSLinkOpen, OSLinkReset, sendcalc, idle, OSFreeTimer, OSRegisterTimer, OSTimerExpired, clear_error_context

See also: cmd_sendchat, cmd_getcalc, cmd_send, sendcalc


cmd_sendchat

cmd_sendchat Function (ROM Call 0x389)
AMS 1.01 or higher bascmd.h

void cmd_sendchat (SYM_STR Var);

Executes TI-Basic 'SendChat' command.

cmd_sendchat is a generic alternative to cmd_sendcalc, which is useful if the receiving unit is a TI-92 (or for making a generic "chat" program that allows any device to be used). See cmd_sendcalc for more info. This function calls sendcalc from the link.h header file.

cmd_sendchat sends a variable only if that variable is compatible with the TI-92, which is typically true in "chat" programs. However, cmd_sendchat will not send an archived variable, a TI-89 graph data base, etc.

Uses: ER_catch, ER_success, ER_throwVar, OSLinkClose, OSLinkOpen, OSLinkReset, sendcalc, idle, OSFreeTimer, OSRegisterTimer, OSTimerExpired, clear_error_context

See also: cmd_sendcalc, cmd_getcalc, cmd_send, sendcalc


cmd_shade

cmd_shade Function (ROM Call 0x38A)
AMS 1.01 or higher bascmd.h

void cmd_shade (ESI Args);

Executes TI-Basic 'Shade' command.

cmd_shade displays the Graph Screen, graphs two expressions on the screen as functions using "x" as the independent variable, and shades the areas in which the first expression is less than the second one (see TI-Basic manual for more info). This function expects one of the following layouts on the expression stack:

END_TAG expression_2 expression_1
END_TAG x_low expression_2 expression_1
END_TAG x_high x_low expression_2 expression_1
END_TAG pattern x_high x_low expression_2 expression_1
END_TAG pat_res pattern x_high x_low expression_2 expression_1

Additionally, each of the entries x_low, x_high, pattern, and pat_res may be omitted and replaced with NOTHING_TAG. The parameter Args should point to the tag of the last item (i.e. expression_1).

x_low and x_high, if included, must be floating point or integer items. They specify the left and right boundaries for the shading process. Valid values are all real values between the values of TI-Basic system variables "xmin" and "xmax". Also, "xmin" and "xmax" are defaults for x_low and x_high if they are omitted.

pattern and pat_res, if included, must be integer items. pattern specifies one of the following four shading patterns:

1 | Vertical shading [DEFAULT]
2 | Horizontal shading
3 | Negative-slope (45 degree) shading
4 | Positive-slope (45 degree) shading

pat_res specifies the resolution of the shading patterns:

1 | Solid shading
2 | 1 pixel spacing [DEFAULT]
3 | 2 pixel spacing
4 | 3 pixel spacing
5 | 4 pixel spacing
6 | 5 pixel spacing
7 | 6 pixel spacing
8 | 7 pixel spacing
9 | 8 pixel spacing
10 | 9 pixel spacing

Note that the drawn graph is not part of the smart graph feature (see the TI-Basic manual for more info), and that regraphing will erase all drawn items.

Uses: ER_catch, ER_success, ER_throwVar, GetValue, next_expression_index, push_expression, push_Float, push_quantum, top_estack, gr_active, OSCheckBreak, is_transfinite, ForceFloat, GraphActivate, GrLineFlt, QSkipGraphErr, XCvtPtoF, YCvtFtoWin, MakeWinRect, WinAttr, WinLine, _bcd_math

See also: cmd_drawfunc, cmd_drawparm, cmd_drawpol


cmd_showstat

cmd_showstat Function (ROM Call 0x38B)
AMS 1.01 or higher bascmd.h

void cmd_showstat (void);

Executes TI-Basic 'ShowStat' command.

cmd_showstat displays a dialog box containing the last computed statistics results if they are still valid (they are cleared automatically if the data to compute them has changed). This function may be used after a statistics or regression calculation using cmd_onevar, cmd_linreg, or something similar.

Uses: DlgMessage, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, GKeyIn, sprintf, XR_stringPtr, is_transfinite, ForceFloat, GetTagStr, RM_Type, DerefSym, SetOK, VarRecall, DrawStaticButton, MakeWinRect, WinActivate, WinClose, WinClr, WinFont, WinOpen, WinStrXY, sysvar_tag_list

See also: cmd_onevar, cmd_twovar, cmd_linreg, cmd_quadreg, cmd_cubicreg, cmd_quartreg, cmd_powerreg, cmd_expreg, cmd_lnreg, cmd_sinreg, cmd_medmed, cmd_logistic


cmd_sinreg

cmd_sinreg Function (ROM Call 0x38C)
AMS 1.01 or higher bascmd.h

void cmd_sinreg (ESI RegData);

Executes TI-Basic 'SinReg' command.

cmd_sinreg calculates a sine regression and updates all the statistics variables (see TI-Basic manual for more info). The RegData parameter must point to a structure on the expression stack which describes where the actual data is stored. This structure may have one of the following eight layouts (RegData should point to the last item):

NOTHING_TAG NOTHING_TAG NOTHING_TAG NOTHING_TAG y_list_name x_list_name
NOTHING_TAG NOTHING_TAG NOTHING_TAG iterations y_list_name x_list_name
NOTHING_TAG NOTHING_TAG period NOTHING_TAG y_list_name x_list_name
NOTHING_TAG NOTHING_TAG period iterations y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name NOTHING_TAG NOTHING_TAG y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name NOTHING_TAG iterations y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name period NOTHING_TAG y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name period iterations y_list_name x_list_name

x_list_name is the VAT symbol name (see SYMSTR and Tags for more info) of a TI-Basic list variable which contains the x values. y_list_name is the VAT symbol name of a TI-Basic list variable which contains the y values. iterations is an integer item in the range 1-16 (8 is assumed if it is ommited). It specifies the maximum number of iterations in which a solution will be attempted (larger values result in better accuracy but longer execution times, and vice versa). period is an integer or floating point item which specifies an estimated period. If omitted, the difference between values in the list which contains x values should be equal, and the values should be in sequential order, otherwise the differences between x values may vary. categories_name (if present) is the VAT symbol name of a TI-Basic list which contains the category for each item. categories_list represents a list of integer items determining which categories will be included (this makes sense only if categories_name is used).

Uses: HeapAllocHighThrow, HeapAllocThrow, HeapFree, HeapFreeIndir, HeapLock, HeapUnlock, HLock, remaining_element_count, push_approx, push_red_row_ech, ER_catch, ER_success, ER_throwVar, delete_expression, estack_to_ushort, HToESI, next_expression_index, NG_approxESI, NG_tokenize, push_Float, push_internal_simplify, push_quantum, push_quantum_pair, top_estack, sprintf, strcat, XR_stringPtr, atan2, cos, fabs, is_transfinite, sin, sqrt, ck_valid_float, estack_to_float, hStrAppend, is_cFloat_agg, PlotInit, PlotPut, RM_Type, statFree, statStart, DerefSym, SymFindMain, VarRecall, VarStore, _bcd_math, ROM Call 0x4CB

See also: cmd_linreg, cmd_quadreg, cmd_cubicreg, cmd_quartreg, cmd_powerreg, cmd_expreg, cmd_lnreg, cmd_onevar, cmd_twovar, cmd_medmed, cmd_logistic


cmd_slpline

cmd_slpline Function (ROM Call 0x38D)
AMS 1.01 or higher bascmd.h

void cmd_slpline (CESI y0, CESI x0, CESI slope);

Executes TI-Basic 'SlpLine' command.

cmd_slpline displays the Graph Screen and draws a line on it as a graph of the equation y-y0=slope*(x-x0), where x and y are the independent and dependent variables, respectively. The parameters x0, y0, and slope should point to integer or floating point items on the expression stack. See the TI-Basic manual for more info.

Uses: ER_catch, ER_success, ER_throwVar, push_expression, push_Float, push_quantum, top_estack, gr_active, OSCheckBreak, is_transfinite, ForceFloat, GraphActivate, GrLineFlt, QSkipGraphErr, XCvtPtoF, YCvtPtoF

See also: cmd_linetan, cmd_line


cmd_sorta

cmd_sorta Function (ROM Call 0x38E)
AMS 1.01 or higher bascmd.h

void cmd_sorta (ESI SymName);

Executes TI-Basic 'SortA' command.

cmd_sorta sorts elements in a TI-Basic list variable in ascending order and stores the result back in the same list. The parameter SymName should point to the terminating zero byte or variable tag of the list variable name. It must be on the expression stack, so you cannot pass a result of the SYMSTR macro directly to cmd_sorta. Instead, if you want to sort the list variable named "foo", for example, you should do:

push_expression (SYMSTR ("foo"));
cmd_sorta (top_estack);
This function may cause heap compression and expansion of the expression stack.

Uses: HeapAllocHighThrow, HeapAllocThrow, HeapFree, HeapFreeIndir, HeapLock, HeapUnlock, HLock, remaining_element_count, push_mat_to_list, push_string, ER_catch, ER_success, ER_throwVar, compare_expressions, delete_expression, HToESI, next_expression_index, push_expression, push_quantum, top_estack, compare_numbers, primary_tag_list, push_simplify, DerefSym, QSysProtected, VarRecall, VarStore

See also: cmd_sortd


cmd_sortd

cmd_sortd Function (ROM Call 0x38F)
AMS 1.01 or higher bascmd.h

void cmd_sortd (ESI SymName);

Executes TI-Basic 'SortD' command.

cmd_sortd sorts elements in a TI-Basic list variable in descending order and stores the result back in the same list. The parameter SymName should point to the terminating zero byte or variable tag of the list variable name. It must be on the expression stack, so you cannot pass a result of the SYMSTR macro directly to cmd_sortd. Instead, if you want to sort the list variable named "foo", for example, you should do:

push_expression (SYMSTR ("foo"));
cmd_sortd (top_estack);
This function may cause heap compression and expansion of the expression stack.

Uses: HeapAllocHighThrow, HeapAllocThrow, HeapFree, HeapFreeIndir, HeapLock, HeapUnlock, HLock, remaining_element_count, push_mat_to_list, push_string, ER_catch, ER_success, ER_throwVar, compare_expressions, delete_expression, HToESI, next_expression_index, push_expression, push_quantum, top_estack, compare_numbers, primary_tag_list, push_simplify, DerefSym, QSysProtected, VarRecall, VarStore

See also: cmd_sorta


cmd_stogdb

cmd_stogdb Function (ROM Call 0x390)
AMS 1.01 or higher bascmd.h

void cmd_stogdb (SYM_STR SymName);

Executes TI-Basic 'StoGDB' command.

cmd_stogdb creates a Graph database (GDB) variable whose name is pointed to by SymName (a VAT string, see SYMSTR), containing the current graphing mode, 'Y=' functions, Window variables, Graph format settings, 1 or 2 Graph setting (split screen and ratio settings if 2-Graph mode), Angle mode, Real/complex mode, Initial conditions for Sequence and Diff Equations mode, Table flags, tblStart, Delta_tbl and tblInput system variables. These items are saved for both graphs in 2-Graph mode. You can use cmd_rclgdb to restore the graph environment later.

Uses: HeapAlloc, HeapFreeIndir, gdb_len, gdb_store, DerefSym, SymDel, VarStore

See also: cmd_rclgdb


cmd_stopic

cmd_stopic Function (ROM Call 0x391)
AMS 1.01 or higher bascmd.h

void cmd_stopic (ESI Args);

Executes TI-Basic 'StoPic' command.

cmd_stopic displays the Graph Screen and stores a part of it in a TI-Basic PIC variable. This function expects one of the following layouts on the expression stack:

END_TAG symname
END_TAG y symname
END_TAG x y symname
END_TAG width x y symname
END_TAG height width x y symname

Additionally, each of the entries x, y and width may be omitted and replaced with NOTHING_TAG. The parameter Args should point to the tag of the last item (i.e. symname). x, y, width and height should be integer items. x and y represent the upper left corner of the area to copy. Both default to 0 if they are omitted. width and height specify the dimensions in pixels. They default to the width and height of the whole graph screen. The symname entry is the VAT symbol name of a TI-Basic variable in which the graph data will be stored (it will be created if it does not exist).

See BitmapGet for a much faster low-level way of getting bitmapped data, independently of the Graph Screen.

Uses: GetValue, next_expression_index, gr_active, gr_stopic, GraphActivate

See also: cmd_rclpic, cmd_rplcpic, cmd_andpic, cmd_xorpic, BitmapGet


cmd_style

cmd_style Function (ROM Call 0x392)
AMS 1.01 or higher bascmd.h

void cmd_style (CESI EqnNum, CESI StyleString);

Executes TI-Basic 'Style' command.

cmd_style sets the system graphing function determined by EqnNum in the current graph mode to use the graphing property determined by StyleString. EqnNum must point to an integer item in the range from 1 to 99, and the corresponding graph function must already exist. StyleString must point to a string item containing one of the following strings: "LINE", "DOT", "THICK", "ANIMATE", "PATH", "ABOVE", "BELOW", "SQUARE". Note that some settings are not valid in various graph modes. The following table shows valid style names for particular graph modes:

Graph mode | Valid styles
Function | LINE, DOT, THICK, ANIMATE, PATH, ABOVE, BELOW, SQUARE
Parametric/Polar | LINE, DOT, THICK, ANIMATE, PATH, SQUARE
Sequence | LINE, DOT, THICK, SQUARE
3D | none
Diff Equations | LINE, DOT, THICK, ANIMATE, PATH, SQUARE

Uses: estack_to_ushort, gr_active, stricmp, EQU_setStyle


cmd_table

cmd_table Function (ROM Call 0x393)
AMS 1.01 or higher bascmd.h

void cmd_table (ESI ExprEtc);

Executes TI-Basic 'Table' command.

cmd_table builds a table for the specified expression/function and displays it on the screen by activating the Table application. This function expects the following layout on the expression stack before calling, depending on the current graph mode (ExprEtc should point to the last item):

Graph mode | Requested layout on the expression stack
Function graphing | END_TAG var_name expression
Parametric graphing | END_TAG var_name y_expression x_expression
Polar graphing | END_TAG var_name expression

Sequences, 3D functions and differential equations cannot be tabulated using this function. Variable names are optional, i.e. they may be omitted. In such cases, default variable names for current graph mode are used ("x" for function graphing, "t" for parametric graphing, and "q" for polar graphing). For example, to graph the function sin(t)+sin(2t) with respect to t (assuming that the current graph mode is "Function" or "Polar"), you should do:

push_quantum (VAR_T_TAG);
push_parse_text ("sin(t)+sin(2t)");
cmd_table (top_estack);
Or, you can avoid push_parse_text by transforming the expression into RPN manually (which is very easy):
static ESQ rpn[] = {END_TAG, VAR_T_TAG, VAR_T_TAG, SIN_TAG,
  VAR_T_TAG, 2, 1, POSINT_TAG, MUL_TAG, SIN_TAG, ADD_TAG};
cmd_table (rpn + sizeof(rpn) - 1);
All expressions entered using cmd_table and cmd_graph are remembered and assigned increasing function numbers starting with 1. The currently selected 'Y=' functions are ignored. Use cmd_clrgraph to clear these functions (they will also be cleared after you go to the Y= Editor application to re-enable the system 'Y=' functions). See the TI-Basic manual for more info.

You can use cmd_blddata as an alternative to this function.

Uses: EV_sendEvent, EV_startApp, gr_active, GraphOrTableCmd

See also: cmd_blddata, cmd_graph, cmd_clrgraph


cmd_text

cmd_text Function (ROM Call 0x394)
AMS 1.01 or higher bascmd.h

void cmd_text (CESI string);

Executes TI-Basic 'Text' command.

cmd_text displays the dialog box without a title which contains only s static text message and the 'OK' button. The parameter string should point to the tag of a string item which describes the text to be displayed.

Uses: DlgMessage, next_expression_index, DrawStrWidth

See also: cmd_request, cmd_dialog, dialogs.h, DlgMessage


cmd_toolbar

cmd_toolbar Function (ROM Call 0x395)
AMS 1.01 or higher bascmd.h

void cmd_toolbar (void);

Executes TI-Basic 'Toolbar' command.

cmd_toolbar is an internal subroutine used by the TI-Basic interpreter for defining toolbar menus using 'ToolBar'...'EndTBar' blocks. As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See functions from menus.h if you want to make toolbar menus inside a C program.

Uses: cmd_goto, HeapAllocThrow, HeapFreeIndir, HLock, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, top_estack, GKeyIn, FKeyI_H, MenuAddIcon, MenuAddText, MenuBegin, MenuEnd, MenuKey, MenuNew, MenuUpdate, strlen, NeedStack, CustomFree, push_simplify, ReallocExprStruct, DerefSym, VarRecall, ROM Call 0x5C8

See also: cmd_custom, cmd_custmon, cmd_popup, menus.h


cmd_trace

cmd_trace Function (ROM Call 0x396)
AMS 1.01 or higher bascmd.h

void cmd_trace (void);

Executes TI-Basic 'Trace' command.

cmd_trace displays the Graph Screen, draws a Smart Graph on it (see TI-Basic manual for more info about the Smart Graph feature), places the trace cursor on the first defined 'Y=' function at the previously defined cursor position (or at the default position if regraphing was necessary), then allows tracing the graph using the cursor keys.

Note: Press 'ENTER' to resume execution after this function.

Uses: ROM Call 0x455


cmd_try

cmd_try Function (ROM Call 0x397)
AMS 1.01 or higher bascmd.h

void cmd_try (void);

Executes TI-Basic 'Try' command.

cmd_try is an internal subroutine used by the TI-Basic interpreter for initializing an error-protected block ('Try'...'EndTry'). As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See TRY, ONERR, and ENDTRY to learn how to take control over errors while executing a C program.

Uses: ER_catch, ER_success, ER_throwVar, bottom_estack, next_expression_index, push_Float, reset_estack_size, top_estack, index_after_match_endtag, push_simplify_statements, VarStore, _bcd_math, ROM Call 0x5C5, ROM Call 0x5C7, ROM Call 0x5C8

See also: cmd_endtry, cmd_clrerr, cmd_passerr, error.h


cmd_twovar

cmd_twovar Function (ROM Call 0x398)
AMS 1.01 or higher bascmd.h

void cmd_twovar (ESI StatData);

Executes TI-Basic 'TwoVar' command.

cmd_twovar calculates two-variable statistics and updates all statistics variables (see TI-Basic manual for more info). The StatData parameter must point to a structure on the expression stack which describes where the actual data is stored. This structure may have one of the following four layouts (StatData should point to the last item):

NOTHING_TAG NOTHING_TAG NOTHING_TAG y_list_name x_list_name
NOTHING_TAG NOTHING_TAG freqs_name y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name NOTHING_TAG y_list_name x_list_name
END_TAG categories_list LIST_TAG categories_name freqs_name y_list_name x_list_name

x_list_name is the VAT symbol name (see SYMSTR and Tags for more info) of a TI-Basic list variable which contains the x values. y_list_name is the VAT symbol name of a TI-Basic list variable which contains the y values. freqs_name (if present) is the VAT symbol name of a TI-Basic list variable which contains the frequencies (all frequencies are assumed to be 1 if freqs_name is not present). categories_name (if present) is the VAT symbol name of a TI-Basic list which contains the category code for each item. categories_list represents a list of integer items which determine which categories will be included (this makes sense only when categories_name is used).

For example, assuming that two TI-Basic list variables "xdata" and "ydata" contain the x and y values, you can calculate simple two-variable statistics using the following code fragment:

push_quantum (NOTHING_TAG);
push_quantum (NOTHING_TAG);
push_quantum (NOTHING_TAG);
push_expression (SYMSTR ("ydata"));
push_expression (SYMSTR ("xdata"));
cmd_twovar (top_estack);
After this, you can retrieve the calculated regression data by accessing TI-Basic system variables like "minX" directly (using VarRecall, for example), or you can display the calculated data using cmd_showstat.

The symbol names x_list_name, y_list_name, freqs_name, and categories_name may also be "c1".."c99". In this case, they represent columns in the last data variable shown in the Data/Matrix editor. In all cases, the lists represented by x_list_name, y_list_name, freqs_name, and categories_name must have the same dimension.

Uses: HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapRealloc, HLock, ER_catch, ER_success, ER_throwVar, estack_to_ushort, next_expression_index, ST_helpMsg, XR_stringPtr, ceil, fabs, floor, sqrt, ck_valid_float, estack_to_float, is_cFloat_agg, OO_GetAppAttr, PlotInit, PlotPut, RM_Type, statFree, statStart, MakeWinRect, WinFill, WinFillTriangle, WinLine, WinRect, WinStrXY, _bcd_math, sysvar_tag_list, ROM Call 0x4CB

See also: cmd_onevar, cmd_linreg, cmd_quadreg, cmd_cubicreg, cmd_quartreg, cmd_powerreg, cmd_expreg, cmd_lnreg, cmd_sinreg, cmd_medmed, cmd_logistic


cmd_unarchiv

cmd_unarchiv Function (ROM Call 0x449)
AMS 2.00 or higher bascmd.h

void cmd_unarchiv (CESI VarNameList);

Executes TI-Basic 'UnArchiv' command.

cmd_unarchiv unarchives one or more TI-Basic variables (i.e. VAT symbols). For details about VarNameList, see cmd_lock.

Uses: HToESI, next_expression_index, CheckSysFunc, DerefSym, EM_moveSymToExtMem, SymDelTwin, VarRecall, ROM Call 0x5CA

See also: cmd_archive, cmd_unlock, cmd_lock


cmd_unlock

cmd_unlock Function (ROM Call 0x399)
AMS 1.01 or higher bascmd.h

void cmd_unlock (CESI VarNameList);

Executes TI-Basic 'Unlock' command.

cmd_unlock unlocks one or more TI-Basic variables (i.e. VAT symbols). For details about VarNameList, see cmd_lock.

Uses: next_expression_index, CheckSysFunc, DerefSym, VarRecall

See also: cmd_lock, cmd_unarchiv, cmd_archive


cmd_while

cmd_while Function (ROM Call 0x39A)
AMS 1.01 or higher bascmd.h

void cmd_while (CESI condition);

Executes TI-Basic 'While' command.

cmd_while is an internal subroutine used by the TI-Basic interpreter for executing 'While'...'EndWhile' loops (searches for a matching 'EndWhile' instruction and transfers the control there if the condition is not true). As this function depends heavily on some system state variables of the TI-Basic intepreter which are not set correctly while executing an ASM program, it is extremely unlikely that this function may be used inside a C program for anything useful.

Note: See the while keyword to learn how to use loops in the C language which are similar to While...EndWhile loops in TI-Basic.

Uses: next_expression_index, push_internal_simplify, top_estack, index_after_match_endtag, NG_control, ROM Call 0x5C8

See also: cmd_endwhile, cmd_endloop


cmd_xorpic

cmd_xorpic Function (ROM Call 0x39B)
AMS 1.01 or higher bascmd.h

void cmd_xorpic (SYM_STR SymName, CESI y, CESI x);

Executes TI-Basic 'XorPic' command.

cmd_xorpic displays the Graph Screen and logically XORs the picture stored in the TI-Basic variable pointed to by SymName (a VAT variable string, see SYMSTR) into the current graph screen at the pixel coordinates determined by the values pointed to by y and x, respectively. Both x and y should point to integer items. SymName should be the name of a PIC variable.

See BitmapPut for much faster low-level manipulations with bitmap pictures, independently of the Graph Screen.

Uses: GetValue, HToESI, gr_active, GraphActivate, DerefSym, VarRecall, WinBitmapPut

See also: cmd_rclpic, cmd_andpic, cmd_rplcpic, cmd_stopic, BitmapPut


cmd_zoombox

cmd_zoombox Function (ROM Call 0x39C)
AMS 1.01 or higher bascmd.h

void cmd_zoombox (void);

Executes TI-Basic 'ZoomBox' command.

cmd_zoombox displays the Graph Screen, lets user draw a box that defines a new viewing window, and updates the viewing window. See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomstd


cmd_zoomdata

cmd_zoomdata Function (ROM Call 0x39D)
AMS 1.01 or higher bascmd.h

void cmd_zoomdata (void);

Executes TI-Basic 'ZoomData' command.

cmd_zoomdata adjusts the viewing window settings based on the currently defined statistical plots (and data) so that all statistical data points will be sampled, and displays the Graph Screen. The adjustment is performed by updating the viewing window system variables ("xmin", etc.). This function does not adjust "ymin" and "ymax" for histograms. See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomstd


cmd_zoomdec

cmd_zoomdec Function (ROM Call 0x39E)
AMS 1.01 or higher bascmd.h

void cmd_zoomdec (void);

Executes TI-Basic 'ZoomDec' command.

cmd_zoomdec adjusts the viewing window settings so that the increments for x and y are both 0.1, and displays the Graph Screen with the origin centered on the screen. The adjustment is performed by updating the viewing window system variables ("xmin", etc.). See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomstd


cmd_zoomfit

cmd_zoomfit Function (ROM Call 0x39F)
AMS 1.01 or higher bascmd.h

void cmd_zoomfit (void);

Executes TI-Basic 'ZoomFit' command.

cmd_zoomfit displays the Graph Screen, adjusts the viewing window system variables for the dependent variables ("ymin", etc.) to view all the picture for the current independent variable settings, and updates the viewing window. See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomstd


cmd_zoomin

cmd_zoomin Function (ROM Call 0x3A0)
AMS 1.01 or higher bascmd.h

void cmd_zoomin (void);

Executes TI-Basic 'ZoomMin' command.

cmd_zoomin displays the Graph Screen, lets the user set a center point for a zoom in, and updates the viewing window. The magnitude of the zoom depends on the TI-Basic system variables "xFact" and "yFact", which determine the zoom factors. In 3D Graph mode, the magnitude depends on the system variables "xFact", "yFact", and "zFact". See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomout, cmd_zoomstd


cmd_zoomint

cmd_zoomint Function (ROM Call 0x3A1)
AMS 1.01 or higher bascmd.h

void cmd_zoomint (void);

Executes TI-Basic 'ZoomInt' command.

cmd_zoomint displays the Graph Screen, lets the user set a center point for the zoom, and adjusts the viewing window settings so that each pixel has an integer coordinate in all directions. The adjustment is performed by updating the viewing window system variables ("xmin", etc.). See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomstd


cmd_zoomout

cmd_zoomout Function (ROM Call 0x3A2)
AMS 1.01 or higher bascmd.h

void cmd_zoomout (void);

Executes TI-Basic 'ZoomOut' command.

cmd_zoomout displays the Graph Screen, lets the user set a center point for a zoom out, and updates the viewing window. The magnitude of the zoom depends on the TI-Basic system variables "xFact" and "yFact", which determine the zoom factors. In 3D Graph mode, the magnitude depends on the system variables "xFact", "yFact" and "zFact". See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomin, cmd_zoomstd


cmd_zoomprev

cmd_zoomprev Function (ROM Call 0x3A3)
AMS 1.01 or higher bascmd.h

void cmd_zoomprev (void);

Executes TI-Basic 'ZoomPrev' command.

cmd_zoomprev displays the Graph Screen and updates the viewing window with the settings in use before the last zoom. See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomstd


cmd_zoomrcl

cmd_zoomrcl Function (ROM Call 0x3A4)
AMS 1.01 or higher bascmd.h

void cmd_zoomrcl (void);

Executes TI-Basic 'ZoomRcl' command.

cmd_zoomrcl displays the Graph Screen and updates the viewing window using the settings stored with the cmd_zoomsto function. See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomsto, cmd_zoomstd


cmd_zoomsqr

cmd_zoomsqr Function (ROM Call 0x3A5)
AMS 1.01 or higher bascmd.h

void cmd_zoomsqr (void);

Executes TI-Basic 'ZoomSqr' command.

cmd_zoomsqr displays the Graph screen, adjusts the x or y viewing window settings so that each pixel represents an equal width and height in the coordinate system, and updates the viewing window. See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomstd


cmd_zoomstd

cmd_zoomstd Function (ROM Call 0x3A6)
AMS 1.01 or higher bascmd.h

void cmd_zoomstd (void);

Executes TI-Basic 'ZoomStd' command.

cmd_zoomstd sets the viewing window system variables ("xmin", etc.) to the following default values (depending on the graphing mode), and then updates the viewing window:

Function | xmin=-10 xmax=10 xscl=1 ymin=-10 ymax=10 yscl=1 xres=2
Parametric | tmin=0 tmax=2*pi tstep=pi/24 xmin=-10 xmax=10 xscl=1 ymin=-10 ymax=10 yscl=1
Polar | qmin=0 qmax=2*pi qstep=pi/24 xmin=-10 xmax=10 xscl=1 ymin=-10 ymax=10 yscl=1
Sequence | nmin=1 nmax=10 plotStrt=1 plotStep=1 xmin=-10 xmax=10 xscl=1 ymin=-10 ymax=10 yscl=1
3D | eyeq=20 eyeF=70 eyey=0 xmin=-10 xmax=10 xscl=14 ymin=-10 ymax=10 yscl=14 zmin=-10 zmax=10 ncontour=5
Differential Equations | t0=0 tmax=10 tstep=0.1 tplot=0 xmin=-1 xmax=10 xscl=1 ymin=-10 ymax=10 yscl=1 ncurves=0 Estep=1 diftol=0.001 fldres=14 dtime=0

See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoombox, cmd_zoomdata, cmd_zoomdec, cmd_zoomfit, cmd_zoomint, cmd_zoomout, cmd_zoomprev, cmd_zoomrcl, cmd_zoomsqr, cmd_zoomsto, cmd_zoomtrig, cmd_zoomin


cmd_zoomsto

cmd_zoomsto Function (ROM Call 0x3A7)
AMS 1.01 or higher bascmd.h

void cmd_zoomsto (void);

Executes TI-Basic 'ZoomSto' command.

cmd_zoomsto stores the current viewing window system variables ("xmin", etc.) in a specially reserved block of memory ("Zoom" memory). You can use cmd_zoomrcl to restore the settings. See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomrcl, cmd_zoomstd


cmd_zoomtrig

cmd_zoomtrig Function (ROM Call 0x3A8)
AMS 1.01 or higher bascmd.h

void cmd_zoomtrig (void);

Executes TI-Basic 'ZoomTrig' command.

cmd_zoomtrig displays the Graph Screen, sets the TI-Basic viewing window system variables "Delta_x" to pi/24 and "xscl" to pi/2, centers the origin, sets the y settings for "ymin", "ymax" and "yscl" to -4, 4, and 5, respectively, and updates the viewing window. See the TI-Basic manual for more info.

Uses: ROM Call 0x455

See also: cmd_zoomstd


primary_tag_list

primary_tag_list Variable (ROM Call 0x467)
bascmd.h, basfunc.h, basop.h, estack.h

const tag_info *const primary_tag_list;

Array of structures containing information on Tags.

Used by: add_to_top, are_units_consistent, compare_numbers, convert_to_TI_92, did_push_approx_inflection_point, did_push_lincf, did_push_var_val, divide_top, does_push_fetch, EQU_getNameInfo, gen_version, get_ub, GM_Intersect, GM_Math1, has_different_variable, has_unit_base, index_if_pushed_binomial_info, index_if_pushed_qquad_info, index_reductum_with_tag_base, index_rmng_factor, index_rmng_fctrs_start_base, integer_non_unknown, is_constant, is_equivalent_to, is_executable, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_positive, is_real, is_term_improper, is_variable, is_whole_number, is0, linear_degree, ParseSymName, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_poly_deg_in_var_or_kernel, push_poly_qr, push_reciprocal, push_simplify, push_sq_matrix_to_whole_number, push_standardize, push_user_func, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, store_func_def, store_to_subscripted_element, times_top, tokenize_if_TI_92_or_text, cmd_dialog, cmd_endfor, cmd_for, cmd_get, cmd_newdata, cmd_popup, cmd_request, cmd_sorta, cmd_sortd, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_char, push_comb, push_comdenom, push_conj, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_gettype, push_im, push_integer_gcd, push_integer_lcm, push_integer_quotient, push_is_prime, push_left, push_lim, push_ln, push_max, push_median, push_mid, push_min, push_mod, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_part, push_perm, push_phase, push_rand, push_randpoly, push_re, push_rec_to_angle, push_red_row_ech, push_right, push_rotate, push_row_echelon, push_sequence, push_shift, push_sign, push_simult, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_and, push_assignment, push_difference, push_dot_exponentiate, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_indir_name, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_or, push_product, push_ratio, push_substitute_no_simplify, push_substitute_using_such_that, push_sum, push_to_cylin, push_to_sphere, push_xor, are_expressions_identical, can_be_approxed, compare_complex_magnitudes, compare_expressions, GetValue, index_below_display_expression_aux, index_main_var, index_numeric_term, is_advanced_tag, is_complex_number, is_free_of_tag, is_independent_of, is_independent_of_de_seq_vars, is_monomial_in_kernel, is_narrowly_independent_of, likely_approx_to_number, next_expression_index, NG_graphESI, numeric_factor_index, Parse2DExpr, Parse2DMultiExpr, push_internal_simplify, push_parse_text, should_and_did_push_approx_arg2, TokToStrN, VarStore, ROM Call 0x468, ROM Call 0x47F, ROM Call 0x480, ROM Call 0x48D, push_to_dms, push_subscripted_element, ROM Call 0x4E6


tag_info

tag_info Type (Structure)
bascmd.h, basfunc.h, basop.h, estack.h

typedef struct {
unsigned char tag_order;
unsigned char tag_version;
unsigned char min_max_args; /* 4 MSB for minimal number of arguments, 4 LSB for maximal number of arguments */
unsigned char proc_args;
void (*CALLBACK tag_proc) (); /* routine that handles the tag */
unsigned long tag_str; /* Pointer to string data on AMS 1.xx, string ID suitable for XR_stringPtr on later AMS versions */
} tag_info;

Structure containing information about AMS EStack tags (Tags, ExtTags).


basfunc.h

basfunc.h Header File
Header File Index

Routines for executing TI-Basic functions

Very few of the functions from this header file are documented as of now. Of course, the ones which are undocumented have not been tested, either. It is very likely that there are errors in this file, so use it with care.

However, we thought it might be a good idea to provide a header file for all of the built-in TI-Basic functions which have a documented entry in the jump table. This way, you can easily search for particular symbolic math functions if you need them. If you use a function from this header file, please document it, too.

Many functions from this header file require their arguments to have some specific format. They usually have to be internally simplified, which can be achieved with the push_internal_simplify function from estack.h, and the result is an internally simplified expression as well. For optional arguments, you can usually pass NULL_INDEX.

If you do not want to accept the AMS dependency of these functions, you can usually construct an expression using their appropriate tags, and then call push_internal_simplify.

Functions
did_push_anti_deriv
Executes TI-Basic 'ò' function.
did_push_series
Executes TI-Basic 'taylor' function.
push_1st_derivative
Executes TI-Basic '¶' function.
push_abs
Executes TI-Basic 'abs' function.
push_acos
Executes TI-Basic 'cos-1' function.
push_acosh
Executes TI-Basic 'cosh-1' function.
push_acot
Executes TI-Basic 'cot-1' function.
push_acoth
Executes TI-Basic 'coth-1' function.
push_acsc
Executes TI-Basic 'csc-1' function.
push_acsch
Executes TI-Basic 'csch-1' function.
push_approx
Executes TI-Basic 'approx' function.
push_arclen
Executes TI-Basic 'arcLen' function.
push_asec
Executes TI-Basic 'sec-1' function.
push_asech
Executes TI-Basic 'sech-1' function.
push_asin
Executes TI-Basic 'sin-1' function.
push_asinh
Executes TI-Basic 'sinh-1' function.
push_atan
Executes TI-Basic 'tan-1' function.
push_atanh
Executes TI-Basic 'tanh-1' function.
push_augment
Executes TI-Basic 'augment' function.
push_ceiling
Executes TI-Basic 'ceiling' function.
push_char
Executes TI-Basic 'char' function.
push_coldim
Executes TI-Basic 'colDim' function.
push_colnorm
Executes TI-Basic 'colNorm' function.
push_comb
Executes TI-Basic 'nCr' function.
push_comdenom
Executes TI-Basic 'comDenom' function.
push_conj
Executes TI-Basic 'conj' function.
push_cos
Executes TI-Basic 'cos' function.
push_cosh
Executes TI-Basic 'cosh' function.
push_cot
Executes TI-Basic 'cot' function.
push_coth
Executes TI-Basic 'coth' function.
push_cross_product
Executes TI-Basic 'crossP' function.
push_csc
Executes TI-Basic 'csc' function.
push_csch
Executes TI-Basic 'csch' function.
push_csolve
Executes TI-Basic 'cSolve' function.
push_cumsum
Executes TI-Basic 'cumSum' function.
push_cylin_vector
Executes the simplification of a vector written under cylindrical form.
push_czeros
Executes TI-Basic 'cZeros' function.
push_def_int
Executes TI-Basic 'ò' function.
push_denominator
Executes TI-Basic 'getDenom' function.
push_dense_poly_eval
Executes TI-Basic 'polyEval(' function.
push_desolve
Executes TI-Basic 'deSolve' function.
push_determinant
Executes TI-Basic 'det' function.
push_diag
Executes TI-Basic 'diag' function.
push_dimension
Executes TI-Basic 'dim' function.
push_div_dif_1c
Executes TI-Basic 'nDeriv(' function.
push_div_dif_1f
Executes TI-Basic 'avgRC(' function.
push_dotproduct
Executes TI-Basic 'dotP' function.
push_eigvc
Executes TI-Basic 'eigVc' function.
push_eigvl
Executes TI-Basic 'eigVl' function.
push_exp
Executes TI-Basic 'e^' function.
push_expand
Executes TI-Basic 'expand' function.
push_extended_prod
Executes TI-Basic 'Õ' function.
push_factor
Executes TI-Basic 'factor' function.
push_floor
Executes TI-Basic 'floor' function.
push_format
Executes TI-Basic 'format' function.
push_fractional_part
Executes TI-Basic 'fPart' function.
push_gcd_numbers
Executes TI-Basic 'gcd' function.
push_getfold
Executes TI-Basic 'getFold' function.
push_getkey
Executes TI-Basic 'getKey' function.
push_getmode
Executes TI-Basic 'getMode' function.
push_gettype
Executes TI-Basic 'getType' function.
push_identity_mat
Executes TI-Basic 'identity' function.
push_im
Executes TI-Basic 'imag' function.
push_instring
Executes TI-Basic 'inString' function.
push_integer_gcd
Executes TI-Basic 'gcd' function.
push_integer_lcm
Executes TI-Basic 'lcm' function.
push_integer_part
Executes TI-Basic 'iPart' function.
push_integer_quotient
Executes TI-Basic 'intDiv' function.
push_integer_remainder
Executes TI-Basic 'remain' function.
push_is_prime
Executes TI-Basic 'isPrime' function.
push_left
Executes TI-Basic 'left' function.
push_lim
Executes TI-Basic 'limit' function.
push_list_to_mat
Executes TI-Basic 'list>mat' function.
push_ln
Executes TI-Basic 'ln' function.
push_log10
Executes TI-Basic 'log' function.
push_mat_to_list
Executes TI-Basic 'mat>list' function.
push_matnorm
Executes TI-Basic 'matNorm' function.
push_max1
Executes TI-Basic 'max' function for a single matrix.
push_max2
Executes TI-Basic 'max' function.
push_max
Executes TI-Basic 'fMax' function.
push_mean
Executes TI-Basic 'mean' function.
push_median
Executes TI-Basic 'median' function.
push_mid
Executes TI-Basic 'mid' function.
push_min1
Executes TI-Basic 'min' function for a single matrix.
push_min2
Executes TI-Basic 'min' function.
push_min
Executes TI-Basic 'fMin' function.
push_mod
Executes TI-Basic 'mod' function.
push_mrow
Executes TI-Basic 'mRow' function.
push_mrowadd
Executes TI-Basic 'mRowAdd' function.
push_newlist
Executes TI-Basic 'newList' function.
push_newmat
Executes TI-Basic 'newMat' function.
push_nint
Executes TI-Basic 'nInt' function.
push_nsolve
Executes TI-Basic 'nSolve' function.
push_nth_derivative
Executes TI-Basic '¶' function.
push_numerator
Executes TI-Basic 'getNum' function.
push_ord
Executes TI-Basic 'ord' function.
push_part
Executes TI-Basic 'part' function.
push_perm
Executes TI-Basic 'nPr' function.
push_phase
Executes TI-Basic 'R>Pq' function for a complex number (?).
push_polar_vector
Executes the simplification of a vector written under polar form.
push_prodlist
Executes TI-Basic 'product' function.
push_propfrac
Executes TI-Basic 'propFrac' function.
push_pttest
Executes TI-Basic 'ptTest' function.
push_pxltest
Executes TI-Basic 'pxlTest' function.
push_r_cis
Executes TI-Basic 'R>Pq' function (?).
push_rand
Executes TI-Basic 'rand' function.
push_randmat
Executes TI-Basic 'randMat' function.
push_randnorm
Executes TI-Basic 'randNorm' function.
push_randpoly
Executes TI-Basic 'randPoly' function.
push_re
Executes TI-Basic 'real' function.
push_rec_to_angle
Executes TI-Basic 'R>Pq' function.
push_red_row_ech
Executes TI-Basic 'rref' function.
push_right
Executes TI-Basic 'right' function.
push_rotate
Executes TI-Basic 'rotate' function.
push_round
Executes TI-Basic 'round' function.
push_row_echelon
Executes TI-Basic 'ref' function.
push_rowadd
Executes TI-Basic 'rowAdd' function.
push_rowdim
Executes TI-Basic 'rowDim' function.
push_rownorm
Executes TI-Basic 'rowNorm' function.
push_rowswap
Executes TI-Basic 'rowSwap' function.
push_sec
Executes TI-Basic 'sec' function.
push_sech
Executes TI-Basic 'sech' function.
push_sequence
Executes TI-Basic 'seq' function.
push_setfold
Executes TI-Basic 'setFold' function.
push_setgraph
Executes TI-Basic 'setGraph' function.
push_setmode
Executes TI-Basic 'setMode' function.
push_settable
Executes TI-Basic 'setTable' function.
push_shift
Executes TI-Basic 'shift' function.
push_sign
Executes TI-Basic 'sign' function.
push_simult
Executes TI-Basic 'simult' function.
push_sin2
Executes TI-Basic 'sin' and 'cos' functions.
push_sin
Executes TI-Basic 'sin' function.
push_sinh
Executes TI-Basic 'sinh' function.
push_solve
Executes TI-Basic 'solve' function.
push_spher_vector
Executes the simplification of a vector written under spherical form.
push_sqrt
Executes TI-Basic 'Ö' function.
push_stddev
Executes TI-Basic 'stdDev' function.
push_str_to_expr
Executes TI-Basic 'expr' function.
push_string
Executes TI-Basic 'string' function.
push_submat
Executes TI-Basic 'subMat' function.
push_sumlist
Executes TI-Basic 'sum' function.
push_summation
Executes TI-Basic 'S' function.
push_switch
Executes TI-Basic 'switch' function.
push_tan
Executes TI-Basic 'tan' function.
push_tanh
Executes TI-Basic 'tanh' function.
push_trig_collect
Executes TI-Basic 'tCollect' function.
push_trig_expand
Executes TI-Basic 'tExpand' function.
push_unitv
Executes TI-Basic 'unitV' function.
push_variance
Executes TI-Basic 'variance' function.
push_when
Executes TI-Basic 'when' function.
push_zeros
Executes TI-Basic 'zeros' function.
Global Variables
primary_tag_list
Array of structures containing information on Tags.
Constants
NULL_INDEX
Describes an empty expression stack index.
Predefined Types
CESI
Represents a pointer to a constant expression.
ESI
Represents an index of a value on the TIOS expression stack.
ESQ
Represents a quantum within an expression.
EStackIndex
Represents an index of a value on the TIOS expression stack.
Quantum
Represents a quantum within an expression.
SYM_STR
Represents a pointer to the terminating zero byte of a string.
tag_info
Structure containing information about AMS EStack tags (Tags, ExtTags).

Note: All functions from this header file get parameters from the expression stack, so this header file must be used in conjunction with estack.h. You need to learn about the usage of the expression stack before using any function from this header file. All functions defined here execute particular TI-Basic functions. They sometimes may be useful to perform some operations which cannot be implemented in C easily. But note that if you use functions from this header file too much, this will decrease the performance of your program significantly. In an extreme case, it will in fact decrease to that of a TI-Basic program! So use functions from this header file only if it is really necessary. Also note that these functions act exactly like the appropriate TI-Basic commands (including throwing errors if something is wrong), so the use of an error tracking mechanism from the error.h header file is highly recommended.

See also: bascmd.h, basop.h


did_push_anti_deriv

did_push_anti_deriv Function (ROM Call 0x5B1)
AMS 2.02 or higher basfunc.h

short did_push_anti_deriv(CESI expr, CESI var, short closed_form_only_flag);

Executes TI-Basic 'ò' function.

did_push_anti_deriv integrates 'expr' with respect to variable 'var'. If the closed-form-only flag is TRUE, it pushes a result to the estack only if it can find a closed form integral. It returns TRUE if it pushed a result to the estack, FALSE otherwise.

Uses: did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_lim, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_summation, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, floor, fmod, is_inf, is_nan, log, modf, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, did_push_lincf, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_if_pushed_binomial_info, index_if_pushed_qquad_info, index_rmng_factor, index_rmng_fctrs_start_base, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E2, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_minus_half, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E7, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606
Used by: push_1st_derivative, push_def_int, push_desolve, push_nth_derivative


did_push_series

did_push_series Function (ROM Call 0x588)
AMS 2.02 or higher basfunc.h

short did_push_series(CESI expr, CESI var, CESI exporder, CESI exppt, short push_only_first_nonzero_term_flag);

Executes TI-Basic 'taylor' function.

did_push_series does a Taylor series expansion of 'expr' with respect to variable 'var' about the point 'exppt' to order 'exporder'. If push_only_first_nonzero_term_flag is TRUE, it pushes only the first nonzero term. It returns TRUE if it pushed a result (not containing a SERIES_TAG) to the estack, FALSE otherwise.

Uses: push_1st_derivative, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_lim, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_sum, all_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, is_free_of_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push0, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_1st_derivative

push_1st_derivative Function (ROM Call 0x5AE)
AMS 2.02 or higher basfunc.h

void push_1st_derivative (CESI, CESI);

Executes TI-Basic '¶' function.

This identifier has not been documented yet. Please help us out.

Uses: did_push_anti_deriv, did_push_series, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_def_int, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_lim, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_summation, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_narrowly_independent_of, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4E9, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E7, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606
Used by: did_push_anti_deriv, did_push_series, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_nth_derivative, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, did_push_approx_inflection_point, get_ub


push_abs

push_abs Function (ROM Call 0x543)
AMS 2.02 or higher basfunc.h

void push_abs (CESI);

Executes TI-Basic 'abs' function.

This identifier has not been documented yet. Please help us out.

Uses: push_gcd_numbers, push_sqrt, push_negate, push_square, are_expressions_identical, check_estack_size, compare_expressions, delete_between, is_free_of_tag, lead_base_index, lead_exponent_index, lead_term_index, map_tail, map_unary_over_comparison, next_expression_index, numeric_factor_index, push_expr_quantum, push_expression, push_Float, push_internal_simplify, push_quantum, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, is_inf, is_nan, sqrt, did_map_aggregate_arg, estack_to_float, Float1Index, Integer1Index, is_nonnegative, is_nonpositive, is_real, is_whole_number, is1, NG_control, primary_tag_list, push_standardize, push1, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, _bcd_math, ROM Call 0x4DF
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_colnorm, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_integer_lcm, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_red_row_ech, push_row_echelon, push_rownorm, push_sign, push_simult, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, compare_complex_magnitudes, add_to_top, are_units_consistent, did_push_approx_inflection_point, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


push_acos

push_acos Function (ROM Call 0x537)
AMS 2.02 or higher basfunc.h

void push_acos (CESI);

Executes TI-Basic 'cos-1' function.

This identifier has not been documented yet. Please help us out.

Uses: push_asin, next_expression_index, push_expr_quantum, push_Float, push_quantum, top_estack, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, estack_to_float, primary_tag_list, push_pi_on_quantum, replace_top2_with_difference, _bcd_math
Used by: push_to_sphere


push_acosh

push_acosh Function (ROM Call 0x53E)
AMS 2.02 or higher basfunc.h

void push_acosh (CESI);

Executes TI-Basic 'cosh-1' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_diag, push_eigvc, push_eigvl, push_gcd_numbers, push_ln, push_re, push_sin2, push_sqrt, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_product, ER_catch, ER_success, ER_throwVar, are_expressions_identical, compare_expressions, delete_between, deleted_between, is_free_of_tag, is_square_matrix, lead_base_index, lead_exponent_index, lead_term_index, likely_approx_to_number, map_tail, map_unary_over_comparison, next_expression_index, numeric_factor_index, push_expr_quantum, push_expression, push_Float, push_quantum, remaining_factors_index, top_estack, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, estack_to_float, Float1Index, get_lb, get_ub, Integer1Index, Integer2Index, IntegerMinus1Index, is_nonnegative, is_nonpositive, is_positive, is_units_term, is_variable, is_whole_number, is1, primary_tag_list, push_pi_on_quantum, push_reciprocal_of_quantum, push_sq_matrix_to_whole_number, push_standardize, replace_top2_with_prod, replace_top2_with_sum, times_top, _bcd_math, ROM Call 0x4DF, push_exact0
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_acot

push_acot Function (Macro)
AMS 2.08 or higher basfunc.h

void push_acot (CESI);

Executes TI-Basic 'cot-1' function.

This identifier has not been documented yet. Please help us out.


push_acoth

push_acoth Function (Macro)
AMS 2.08 or higher basfunc.h

void push_acoth (CESI);

Executes TI-Basic 'coth-1' function.

This identifier has not been documented yet. Please help us out.


push_acsc

push_acsc Function (Macro)
AMS 2.08 or higher basfunc.h

void push_acsc (CESI);

Executes TI-Basic 'csc-1' function.

This identifier has not been documented yet. Please help us out.


push_acsch

push_acsch Function (Macro)
AMS 2.08 or higher basfunc.h

void push_acsch (CESI);

Executes TI-Basic 'csch-1' function.

This identifier has not been documented yet. Please help us out.


push_approx

push_approx Function (ROM Call 0x4F7)
AMS 2.00 or higher basfunc.h

void push_approx (CESI);

Executes TI-Basic 'approx' function.

This identifier has not been documented yet. Please help us out.

Uses: push_internal_simplify, NG_control
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_atanh, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_eigvc, push_eigvl, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_median, push_min, push_mod, push_nint, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_red_row_ech, push_row_echelon, push_rownorm, push_sequence, push_sign, push_simult, push_sin2, push_solve, push_summation, push_switch, push_zeros, cmd_sinreg, did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, can_be_approxed, should_and_did_push_approx_arg2, add_to_top, are_units_consistent, did_push_approx_inflection_point, get_ub, index_if_pushed_qquad_info, is_negative, is_never0, is_nonnegative, is_nonpositive, is_positive, is_real, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_float_qr_fact, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x606


push_arclen

push_arclen Function (Macro)
basfunc.h

void push_arclen (CESI, CESI, CESI, CESI);

Executes TI-Basic 'arcLen' function.

This identifier has not been documented yet. Please help us out.


push_asec

push_asec Function (Macro)
AMS 2.08 or higher basfunc.h

void push_asec (CESI);

Executes TI-Basic 'sec-1' function.

This identifier has not been documented yet. Please help us out.


push_asech

push_asech Function (Macro)
AMS 2.08 or higher basfunc.h

void push_asech (CESI);

Executes TI-Basic 'sech-1' function.

This identifier has not been documented yet. Please help us out.


push_asin

push_asin Function (ROM Call 0x536)
AMS 2.02 or higher basfunc.h

void push_asin (CESI);

Executes TI-Basic 'sin-1' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_asinh, push_atan, push_diag, push_eigvc, push_eigvl, push_gcd_numbers, push_ln, push_re, push_sign, push_sin2, push_sqrt, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_product, push_square, push_sum, ER_catch, ER_success, ER_throwVar, are_expressions_identical, compare_expressions, compare_Floats, delete_between, deleted_between, factor_exponent_index, is_free_of_tag, is_square_matrix, lead_base_index, lead_exponent_index, lead_term_index, likely_approx_to_number, map_tail, map_unary_over_comparison, next_expression_index, numeric_factor_index, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_quantum, remaining_factors_index, top_estack, asin, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, add_to_top, add1_to_top, estack_to_float, Float1Index, get_lb, get_ub, Integer0Index, Integer1Index, IntegerMinus1Index, is_minus1, is_neg_lead_numr_coef_re_part, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_units_term, is_variable, is_whole_number, is0, is1, negate_top, primary_tag_list, push_but_factor, push_minus_recip_of_quantum, push_pi_on_quantum, push_quantum_as_nonnegative_int, push_reciprocal_of_quantum, push_sq_matrix_to_whole_number, push_standardize, push0, push1, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, ROM Call 0x4DF, push_half, push_minus1
Used by: did_push_anti_deriv, push_1st_derivative, push_acos, push_asinh, push_atan, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_to_sphere, get_ub


push_asinh

push_asinh Function (ROM Call 0x53D)
AMS 2.02 or higher basfunc.h

void push_asinh (CESI);

Executes TI-Basic 'sinh-1' function.

This identifier has not been documented yet. Please help us out.

Uses: push_asin, push_diag, push_eigvc, push_eigvl, push_gcd_numbers, push_re, push_sign, push_sin2, push_exponentiate, push_negate, push_product, push_ratio, ER_catch, ER_success, ER_throwVar, are_expressions_identical, compare_expressions, delete_between, deleted_between, is_free_of_tag, is_square_matrix, lead_base_index, lead_exponent_index, lead_term_index, map_tail, map_unary_over_comparison, next_expression_index, numeric_factor_index, push_expr_quantum, push_expression, push_Float, push_quantum, remaining_factors_index, top_estack, asinh, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, estack_to_float, Float1Index, Integer1Index, IntegerMinus1Index, is_neg_lead_numr_coef_re_part, is_real, is_units_term, is_whole_number, is0, is1, negate_top, primary_tag_list, push_but_factor, push_sq_matrix_to_whole_number, push_standardize, push0, push1, replace_top2_with_prod, times_top, _bcd_math, ROM Call 0x4DF
Used by: did_push_anti_deriv, push_1st_derivative, push_asin, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_atan

push_atan Function (ROM Call 0x538)
AMS 2.02 or higher basfunc.h

void push_atan (CESI);

Executes TI-Basic 'tan-1' function.

This identifier has not been documented yet. Please help us out.

Uses: push_asin, push_atanh, push_diag, push_eigvc, push_eigvl, push_gcd_numbers, push_ln, push_mod, push_re, push_rec_to_angle, push_sign, push_sin2, push_sqrt, push_difference, push_exponentiate, push_negate, push_product, push_ratio, push_square, push_sum, ER_catch, ER_success, ER_throwVar, are_expressions_identical, compare_expressions, delete_between, delete_expression, deleted_between, factor_base_index, factor_exponent_index, is_free_of_tag, is_square_matrix, lead_base_index, lead_exponent_index, lead_term_index, map_tail, map_unary_over_comparison, moved_between_to_top, next_expression_index, numeric_factor_index, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, atan, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, add_to_top, estack_to_float, Float1Index, Integer0Index, Integer1Index, IntegerMinus1Index, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_nonnegative, is_pos_int_and_eq_quantum, is_real, is_reciprocal_of_quantum, is_units_term, is_whole_number, is0, is1, negate_top, primary_tag_list, push_but_factor, push_minus_recip_of_quantum, push_pi_on_quantum, push_quantum_as_nonnegative_int, push_reciprocal, push_reciprocal_of_quantum, push_sq_matrix_to_whole_number, push_standardize, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, ROM Call 0x4DF, push_exact0
Used by: did_push_anti_deriv, push_1st_derivative, push_asin, push_atanh, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_rec_to_angle, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_to_sphere, get_ub


push_atanh

push_atanh Function (ROM Call 0x53F)
AMS 2.02 or higher basfunc.h

void push_atanh (CESI);

Executes TI-Basic 'tanh-1' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_atan, push_diag, push_eigvc, push_eigvl, push_gcd_numbers, push_ln, push_re, push_rec_to_angle, push_sign, push_sin2, push_difference, push_exponentiate, push_negate, push_product, push_square, push_sum, ER_catch, ER_success, ER_throwVar, are_expressions_identical, compare_expressions, delete_between, delete_expression, deleted_between, is_free_of_tag, is_square_matrix, lead_base_index, lead_exponent_index, lead_term_index, likely_approx_to_number, map_tail, map_unary_over_comparison, next_expression_index, numeric_factor_index, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, estack_to_float, Float0Index, Float1Index, get_lb, get_ub, Integer0Index, Integer1Index, IntegerMinus1Index, is_minus1, is_neg_lead_numr_coef_re_part, is_positive, is_real, is_units_term, is_variable, is_whole_number, is0, is1, negate_top, primary_tag_list, push_but_factor, push_minus_recip_of_quantum, push_pi_on_quantum, push_reciprocal, push_reciprocal_of_quantum, push_sq_matrix_to_whole_number, push_standardize, push0, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, ROM Call 0x4DF, push_half, push_exact0
Used by: did_push_anti_deriv, push_1st_derivative, push_atan, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_augment

push_augment Function (ROM Call 0x496)
AMS 2.00 or higher basfunc.h

void push_augment (CESI, CESI);

Executes TI-Basic 'augment' function.

This identifier has not been documented yet. Please help us out.

Uses: remaining_element_count, next_expression_index, push_between, push_quantum
Used by: push_desolve, push_determinant, push_red_row_ech, push_row_echelon, push_simult, push_sq_matrix_to_whole_number


push_ceiling

push_ceiling Function (ROM Call 0x54B)
AMS 2.02 or higher basfunc.h

void push_ceiling (CESI);

Executes TI-Basic 'ceiling' function.

This identifier has not been documented yet. Please help us out.

Uses: push_floor, push_negate, delete_between, top_estack, negate_top
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_integer_part, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


push_char

push_char Function (ROM Call 0x497)
AMS 2.00 or higher basfunc.h

void push_char (CESI);

Executes TI-Basic 'char' function.

This identifier has not been documented yet. Please help us out.

Uses: estack_to_ushort, map_tail, push_quantum, push_quantum_pair, is_whole_number, primary_tag_list


push_coldim

push_coldim Function (ROM Call 0x498)
AMS 2.00 or higher basfunc.h

void push_coldim (CESI);

Executes TI-Basic 'colDim' function.

This identifier has not been documented yet. Please help us out.

Uses: remaining_element_count, delete_expression, is_matrix, push_Float, push_Float_to_rat, top_estack, _bcd_math


push_colnorm

push_colnorm Function (ROM Call 0x499)
AMS 2.00 or higher basfunc.h

void push_colnorm (CESI);

Executes TI-Basic 'colNorm' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_max1, can_be_approxed, delete_between, is_matrix, next_expression_index, top_estack, push0, replace_top2_with_sum


push_comb

push_comb Function (ROM Call 0x542)
AMS 2.02 or higher basfunc.h

void push_comb (CESI, CESI);

Executes TI-Basic 'nCr' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_perm, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_factorial, push_product, push_ratio, check_estack_size, delete_between, deleted_between, estack_number_to_Float, likely_approx_to_number, push_between, push_expression, push_Float, push_quantum, top_estack, ST_helpMsg, XR_stringPtr, add1_to_top, compare_numbers, did_map_aggregate_arg, estack_to_float, get_lb, get_ub, integer_non_unknown, IntegerMinus1Index, is_equivalent_to, is_negative, is_nonnegative, is_positive, is_real, is_units_term, is_variable, is_whole_number, is0, is1, primary_tag_list, replace_top2_with_prod, subtract1_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4E9, ROM Call 0x4EA, push_half, push_exact0, push_exact1


push_comdenom

push_comdenom Function (ROM Call 0x59B)
AMS 2.02 or higher basfunc.h

void push_comdenom (CESI, CESI);

Executes TI-Basic 'comDenom' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_expand, push_gcd_numbers, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, ER_catch, ER_success, ER_throwVar, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, add_to_top, compare_numbers, estack_to_float, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, ROM Call 0x4EF, push_exact1
Used by: push_desolve


push_conj

push_conj Function (ROM Call 0x547)
AMS 2.02 or higher basfunc.h

void push_conj (CESI);

Executes TI-Basic 'conj' function.

This identifier has not been documented yet. Please help us out.

Uses: push_ln, push_sin2, push_negate, delete_between, delete_expression, map_tail, map_unary_over_comparison, next_expression_index, push_expr_quantum, push_expression, push_internal_simplify, push_quantum, top_estack, is_real, is_whole_number, negate_top, primary_tag_list, push_reciprocal, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_dotproduct, push_lim, push_matnorm, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_transpose_aux, get_ub, push_reciprocal, push_symbolic_qr_fact


push_cos

push_cos Function (ROM Call 0x533)
AMS 2.02 or higher basfunc.h

void push_cos (CESI);

Executes TI-Basic 'cos' function.

This identifier has not been documented yet. Please help us out.

Uses: push_sin2, next_expression_index, push_Float, push_quantum, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, estack_to_float, Integer1Index, _bcd_math
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_perm, push_phase, push_r_cis, push_re, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, push_trig, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, push_spher_vector, push_polar_to_rect_x


push_cosh

push_cosh Function (ROM Call 0x53B)
AMS 2.02 or higher basfunc.h

void push_cosh (CESI);

Executes TI-Basic 'cosh' function.

This identifier has not been documented yet. Please help us out.

Uses: push_cos, push_diag, push_eigvc, push_eigvl, push_exp, push_re, push_sin, push_sin2, push_sinh, push_exponentiate, push_negate, push_product, ER_catch, ER_success, ER_throwVar, delete_between, deleted_between, is_free_of_tag, is_square_matrix, lead_base_index, lead_exponent_index, map_tail, map_unary_over_comparison, next_expression_index, push_expr_quantum, push_expression, push_Float, push_overflow_to_infinity, push_quantum, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, ccos, ccosh, cexp, cosh, csin, csinh, ctan, ctanh, fabs, log, estack_to_float, IntegerMinus1Index, is_neg_lead_numr_coef_re_part, is_real, is0, is1, primary_tag_list, push_but_factor, push_sq_matrix_to_whole_number, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_sum, times_top, _bcd_math, push_half, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_sin2, push_sinh, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_sum, get_ub, replace_top_with_post_simplified


push_cot

push_cot Function (Macro)
AMS 2.08 or higher basfunc.h

void push_cot (CESI);

Executes TI-Basic 'cot' function.

This identifier has not been documented yet. Please help us out.


push_coth

push_coth Function (Macro)
AMS 2.08 or higher basfunc.h

void push_coth (CESI);

Executes TI-Basic 'coth' function.

This identifier has not been documented yet. Please help us out.


push_cross_product

push_cross_product Function (ROM Call 0x4CE)
AMS 2.00 or higher basfunc.h

void push_cross_product (CESI, CESI);

Executes TI-Basic 'crossP' function.

This identifier has not been documented yet. Please help us out.

Uses: push_dimension, push_list_to_mat, remaining_element_count, push_product, delete_between, delete_expression, push_quantum, top_estack, get_matrix_indices, negate_top, push0, replace_top2_with_sum


push_csc

push_csc Function (Macro)
AMS 2.08 or higher basfunc.h

void push_csc (CESI);

Executes TI-Basic 'csc' function.

This identifier has not been documented yet. Please help us out.


push_csch

push_csch Function (Macro)
AMS 2.08 or higher basfunc.h

void push_csch (CESI);

Executes TI-Basic 'csch' function.

This identifier has not been documented yet. Please help us out.


push_csolve

push_csolve Function (ROM Call 0x585)
AMS 2.02 or higher basfunc.h

void push_csolve (CESI, CESI);

Executes TI-Basic 'cSolve' function.

Please see push_czeros entry for an important note for all solver ROM calls.

Uses: did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_indir_name, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_no_simplify, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, map_tail_Int, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, did_push_var_val, divide_top, does_push_fetch, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, DerefSym, VarRecall, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E6, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x5ED, ROM Call 0x606


push_cumsum

push_cumsum Function (ROM Call 0x49A)
AMS 2.00 or higher basfunc.h

void push_cumsum (CESI);

Executes TI-Basic 'cumSum' function.

This identifier has not been documented yet. Please help us out.

Uses: push_sum, delete_between, next_expression_index, push_expression, push_quantum, push_reversed_tail, top_estack, push0


push_cylin_vector

push_cylin_vector Function (ROM Call 0x49B)
AMS 2.00 or higher basfunc.h

void push_cylin_vector(ESI mat);

Executes the simplification of a vector written under cylindrical form.

The matrix pointed to by mat must be a one-line, three-column matrix, and the third element of the matrix must be free of tag LIST_TAG.

Uses: is_free_of_tag, next_expression_index, push_expression, push_quantum_pair, push_polar_to_rect_x, push_polar_to_rect_y

See also: push_polar_vector, push_spher_vector


push_czeros

push_czeros Function (ROM Call 0x587)
AMS 2.02 or higher basfunc.h

void push_czeros (CESI, CESI);

Executes TI-Basic 'cZeros' function.

Important note for all solver ROM calls:

When czeros( ) is executed on the command line, the OS provides special treatment for the specified "variable of interest". Part of the "special treatment" is temporarily to promote the "variable of interest" to the top of the ordering. Directly calling push_czeros( ) bypasses this special treatment. This affects solver ROM calls such as push_zeros, push_solve, push_czeros, push_csolve, push_min, push_max, and push_desolve.

For example, the following code for attempting to find an inverse of sqrt(x/(1-x)) gives no solutions:

 push_quantum(X_VAR_TAG);
 var = top_estack;
 push_difference(Integer1Index,var);
 expr = top_estack;
 push_quantum(X_VAR_TAG);
 divide_top(expr);
 push_sqrt(top_estack);	//sqrt(x/(1-x))
 push_zstr("solveaux"); top_estack--;
 solvevar = top_estack;	//Auxiliary solve variable
 push_substitute_simplify(expr,var,solvevar);
 push_difference(top_estack,var);    //(expr|x=solveaux)-x
 push_czeros(top_estack,solvevar);

The simplest and most reliable way around this is to do:
 push_expression(var);
 push_expression(expr);
 push_quantum(CZEROS_TAG);
 push_simplify(top_estack);

The above information was obtained from TI.

Uses: did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_indir_name, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_no_simplify, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, map_tail_Int, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, did_push_var_val, divide_top, does_push_fetch, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, DerefSym, VarRecall, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E6, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x5ED, ROM Call 0x606


push_def_int

push_def_int Function (ROM Call 0x5B2)
AMS 2.02 or higher basfunc.h

void push_def_int (CESI, CESI, CESI, CESI);

Executes TI-Basic 'ò' function.

This identifier has not been documented yet. Please help us out.

Uses: did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_lim, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, did_push_lincf, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606
Used by: push_1st_derivative, push_desolve


push_denominator

push_denominator Function (ROM Call 0x55B)
AMS 2.02 or higher basfunc.h

void push_denominator (CESI);

Executes TI-Basic 'getDenom' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_ceiling, push_cos, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


push_dense_poly_eval

push_dense_poly_eval Function (ROM Call 0x49C)
AMS 2.00 or higher basfunc.h

void push_dense_poly_eval (ESI coeflist, ESI expr);

Executes TI-Basic 'polyEval(' function.

The list 'coeflist' represents the coefficients of a polynomial in descending order. push_dense_poly_eval pushes the polynomial evaluated at 'expr'. 'expr' need not be a number, or even a variable.

Uses: add_to_top, is_constant, next_expression_index, push_expression, push_quantum, push0, times_top


push_desolve

push_desolve Function (ROM Call 0x58B)
AMS 2.02 or higher basfunc.h

void push_desolve (CESI);

Executes TI-Basic 'deSolve' function.

Please see push_czeros entry for an important note for all solver ROM calls.

Uses: did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_augment, push_ceiling, push_comdenom, push_conj, push_cos, push_cosh, push_def_int, push_denominator, push_determinant, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_lim, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_red_row_ech, push_row_echelon, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, last_element_index, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, did_push_lincf, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_if_pushed_qquad_info, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_totally_polynomial, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_reciprocal_of_quantum, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E7, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606


push_determinant

push_determinant Function (ROM Call 0x49D)
AMS 2.00 or higher basfunc.h

void push_determinant (CESI, CESI);

Executes TI-Basic 'det' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_augment, push_dimension, push_identity_mat, push_max1, push_mrowadd, push_rownorm, push_rowswap, HeapAllocHighThrow, HeapFree, HeapLock, remaining_element_count, push_difference, push_negate, push_product, push_ratio, ER_catch, ER_success, ER_throwVar, delete_between, delete_expression, is_free_of_tag, is_matrix, likely_approx_to_number, next_expression_index, push_expression, push_Float, push_ulong_to_integer, top_estack, memcpy, OSCheckBreak, estack_to_float, get_lb, get_ub, Integer1Index, is_constant, is_nonnegative, is_variable, is0, NG_control, primary_tag_list, push_mrow_aux, push0, push1, replace_top2_with_prod, _bcd_math
Used by: push_desolve


push_diag

push_diag Function (ROM Call 0x49E)
AMS 2.00 or higher basfunc.h

void push_diag (CESI);

Executes TI-Basic 'diag' function.

This identifier has not been documented yet. Please help us out.

Uses: delete_between, push_expr_quantum, push_expression, push_quantum, push_quantum_pair, top_estack, get_matrix_indices, push0
Used by: push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cosh, push_exp, push_ln, push_log10, push_sin2, push_sinh, push_tan, push_tanh, push_exponentiate


push_dimension

push_dimension Function (ROM Call 0x49F)
AMS 2.00 or higher basfunc.h

void push_dimension (CESI);

Executes TI-Basic 'dim' function.

This identifier has not been documented yet. Please help us out.

Uses: remaining_element_count, delete_expression, next_expression_index, push_Float, push_Float_to_rat, push_quantum, top_estack, _bcd_math
Used by: push_cross_product, push_determinant, push_red_row_ech, push_row_echelon, push_simult, push_sq_matrix_to_whole_number, cmd_lu_fact, cmd_qr_fact


push_div_dif_1c

push_div_dif_1c Function (ROM Call 0x58D)
AMS 2.02 or higher basfunc.h

void push_div_dif_1c (ESI expr, ESI var, ESI h);

Executes TI-Basic 'nDeriv(' function.

push_div_dif_1c pushes to the estack the 1st-order centered or symmetric difference of 'expr' with respect to variable 'var' with stepsize 'h'. You can obtain higher-order differences by repeated application, just as you can with derivatives.

Uses: push_difference, push_product, push_ratio, push_substitute_simplify, push_sum, check_estack_size, delete_between, estack_number_to_Float, push_between, push_expression, push_Float, push_quantum, subtract_from_top, top_estack, ST_helpMsg, XR_stringPtr, fabs, _bcd_math, _du16u16, _ds32s32, _ms32s32, push_exact0, Integer2Index, primary_tag_list

See also: push_div_dif_1f


push_div_dif_1f

push_div_dif_1f Function (ROM Call 0x58C)
AMS 2.02 or higher basfunc.h

void push_div_dif_1f (ESI expr, ESI var, ESI h);

Executes TI-Basic 'avgRC(' function.

push_div_dif_1f pushes to the estack the 1st-order forward difference of 'expr' with respect to variable 'var' with stepsize 'h'. You can obtain higher-order differences by repeated application, just as you can with derivatives.

Uses: push_ratio, push_substitute_simplify, add_to_top, delete_between, push_expression, subtract_from_top, top_estack

See also: push_div_dif_1c


push_dotproduct

push_dotproduct Function (ROM Call 0x4A3)
AMS 2.00 or higher basfunc.h

void push_dotproduct (CESI, CESI);

Executes TI-Basic 'dotP' function.

This identifier has not been documented yet. Please help us out.

Uses: push_conj, remaining_element_count, push_product, delete_between, next_expression_index, push_offset_array, push_quantum, top_estack, push0, replace_top2_with_sum


push_eigvc

push_eigvc Function (ROM Call 0x4CF)
AMS 2.00 or higher basfunc.h

void push_eigvc (CESI);

Executes TI-Basic 'eigVc' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, delete_between, is_square_matrix, top_estack, is_cFloat_agg, ROM Call 0x494
Used by: push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cosh, push_exp, push_ln, push_log10, push_sin2, push_sinh, push_tan, push_tanh, push_exponentiate


push_eigvl

push_eigvl Function (ROM Call 0x4D0)
AMS 2.00 or higher basfunc.h

void push_eigvl (CESI);

Executes TI-Basic 'eigVl' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, delete_between, is_square_matrix, top_estack, is_cFloat_agg, ROM Call 0x495
Used by: push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cosh, push_exp, push_ln, push_log10, push_sin2, push_sinh, push_tan, push_tanh, push_exponentiate


push_exp

push_exp Function (ROM Call 0x52E)
AMS 2.02 or higher basfunc.h

void push_exp (CESI);

Executes TI-Basic 'e^' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_cos, push_diag, push_eigvc, push_eigvl, push_expand, push_re, push_sin, push_sin2, push_difference, push_exponentiate, push_product, ER_catch, ER_success, ER_throwVar, delete_between, deleted_between, estack_number_to_Float, index_numeric_term, is_free_of_tag, is_square_matrix, lead_base_index, lead_exponent_index, likely_approx_to_number, main_gen_var_index, map_tail, map_unary_over_comparison, next_expression_index, numeric_factor_index, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_overflow_to_infinity, push_quantum, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, exp, fabs, log, estack_to_float, get_lb, get_ub, Integer1Index, IntegerMinus1Index, is_nonnegative, is_positive, is_real, is_units_term, is_variable, is0, is1, primary_tag_list, push_but_factor, push_nonnumeric_factors, push_sq_matrix_to_whole_number, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, times_top, _bcd_math, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_sin2, push_sinh, push_solve, push_summation, push_tanh, push_zeros, push_dot_exponentiate, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, get_ub, push_reciprocal, replace_top_with_post_simplified


push_expand

push_expand Function (ROM Call 0x59A)
AMS 2.02 or higher basfunc.h

void push_expand (CESI, CESI, short);

Executes TI-Basic 'expand' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_factor, push_gcd_numbers, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_ratio, push_square, push_sum, ER_catch, ER_success, ER_throwVar, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, index_main_var, is_advanced_tag, is_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, add_to_top, compare_numbers, estack_to_float, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_term_improper, is_variable, is_whole_number, is0, is1, negate_top, NG_control, primary_tag_list, push_but_factor, push_dependent_factors, push_gcd_then_cofactors, push_independent_factors, push_make_proper, push_negate_quantum_as_negint, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push0, push1, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_exp, push_extended_prod, push_floor, push_lim, push_max, push_min, push_nsolve, push_sin2, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_extended_prod

push_extended_prod Function (ROM Call 0x5B5)
AMS 2.02 or higher basfunc.h

void push_extended_prod (CESI, CESI, CESI, CESI);

Executes TI-Basic 'Õ' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_cos, push_exp, push_expand, push_factor, push_floor, push_lim, push_ln, push_summation, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_factorial, push_negate, push_product, push_ratio, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, are_expressions_identical, check_estack_size, delete_between, delete_expression, deleted_between, did_push_cnvrt_Float_to_integer, factor_base_index, factor_exponent_index, is_free_of_tag, is_independent_of, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_offset_array, push_quantum, push_ulong_to_integer, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, floor, fmod, add_to_top, add1_to_top, and_onto_top, did_push_lincf, divide_top, estack_to_float, FloatExp1Index, FloatPiIndex, get_lb, get_ub, index_rmng_fctrs_start_base, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, is_undefined, is_variable, is_whole_number, is0, is1, negate_top, NG_control, NG_such_that_index, primary_tag_list, push_but_factor, push_dependent_factors, push_independent_factors, push_pi, push_quantum_pair_as_pos_frac, push1, raise_to_top, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, subtract1_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4E2, ROM Call 0x4E9, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_exact1


push_factor

push_factor Function (ROM Call 0x59C)
AMS 2.02 or higher basfunc.h

void push_factor (CESI, CESI, short);

Executes TI-Basic 'factor' function.

This identifier has not been documented yet. Please help us out.

Uses: push_1st_derivative, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_gcd_numbers, push_ln, push_mod, push_numerator, push_sin, remaining_element_count, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, index_main_var, is_advanced_tag, is_free_of_tag, is_independent_of, is_monomial, is_narrowly_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_internal_simplify, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_ushort_to_integer, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, floor, sqrt, add_to_top, compare_numbers, divide_top, estack_to_float, Float0Index, Float1Index, FloatHalfIndex, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, index_if_pushed_qquad_info, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_nonnegative, is_nonpositive, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, primary_tag_list, push_but_factor, push_constant_factors, push_gcd_then_cofactors, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonnumeric_factors, push_poly_deg_in_var_or_kernel, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_reciprocal_of_quantum, push_standardize, push_var_kern_tail, push1, raise_to_top, remaining_conjuncts_index, replace_top_with_reciprocal, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4E0, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5C4, ROM Call 0x5E4
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_extended_prod, push_lim, push_ln, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_floor

push_floor Function (ROM Call 0x54A)
AMS 2.02 or higher basfunc.h

void push_floor (CESI);

Executes TI-Basic 'floor' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_expand, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, ER_catch, ER_success, ER_throwVar, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, floor, sqrt, add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_ceiling, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_integer_part, push_lim, push_max, push_min, push_mod, push_nsolve, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_format

push_format Function (ROM Call 0x315)
AMS 1.01 or higher basfunc.h

void push_format (ESI, ESI);

Executes TI-Basic 'format' function.

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable, push_string, ER_catch, ER_success, ER_throwVar, delete_between, next_expression_index, NG_approxESI, push_internal_simplify, push_quantum, top_estack, _ms32s32


push_fractional_part

push_fractional_part Function (ROM Call 0x54E)
AMS 2.02 or higher basfunc.h

void push_fractional_part (CESI);

Executes TI-Basic 'fPart' function.

This identifier has not been documented yet. Please help us out.

Uses: check_estack_size, delete_between, map_tail, next_expression_index, push_between, push_expr_quantum, push_expression, push_Float, push_quantum, push_quantum_pair, top_estack, fmod, estack_to_float, primary_tag_list, push_negate_quantum_as_negint, replace_top2_with_imre, _du16u16, _ds32s32, _ms32s32, push_exact0
Used by: push_product, push_to_dms


push_gcd_numbers

push_gcd_numbers Function (ROM Call 0x514)
AMS 2.02 or higher basfunc.h

void push_gcd_numbers (CESI, CESI);

Executes TI-Basic 'gcd' function.

This identifier has not been documented yet. Please help us out.

Uses: check_estack_size, delete_between, gcd_exact_whole_Floats, is_Float_exact_whole_number, push_between, push_expression, push_Float, push_Float_to_nonneg_int, push_quantum, top_estack, fabs, estack_to_float, Float1Index, primary_tag_list, _du16u16, _ds32s32, _ms32s32, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_factor, push_integer_gcd, push_integer_lcm, push_lim, push_max, push_min, push_nsolve, push_sign, push_solve, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, get_ub, index_if_pushed_binomial_info, push_gcd_then_cofactors, push_make_proper, push_reciprocal, push_standardize, replace_top_with_post_simplified


push_getfold

push_getfold Function (ROM Call 0x317)
AMS 1.01 or higher basfunc.h

void push_getfold (void);

Executes TI-Basic 'getFold' function.

This identifier has not been documented yet. Please help us out.

Uses: push_zstr


push_getkey

push_getkey Function (ROM Call 0x316)
AMS 1.01 or higher basfunc.h

void push_getkey (void);

Executes TI-Basic 'getKey' function.

push_getkey pushes tke key code of a pressed key to the expression stack. It pushes 0 if no key is pressed. The pushed value is exactly the same as a value returned from the TI-Basic getKey function (it is mainly the same value as returned from ngetchx, but not always: for example, codes for arrow keys are different).

Uses: push_ulong_to_integer, kbhit, ngetchx, off, OSTimerExpired, OSTimerRestart


push_getmode

push_getmode Function (ROM Call 0x318)
AMS 1.01 or higher basfunc.h

void push_getmode (CESI ModeNameString);

Executes TI-Basic 'getMode' function.

push_getmode assumes that ModeNameString points to the tag of a string expression (usually STR_TAG). If it points to a specific mode name string, it pushes a new string containing the current setting for that mode to the expressions stack. See push_setmode for a list of legal mode name strings.

If the mode name string is "ALL", push_getmode pushes a list of string pairs containing the settings of all the modes to the expression stack. So, you can restore all mode settings later at once using push_setmode.


push_gettype

push_gettype Function (ROM Call 0x319)
AMS 1.01 or higher basfunc.h

void push_gettype (CESI);

Executes TI-Basic 'getType' function.

This identifier has not been documented yet. Please help us out.

Uses: HToESI, push_zstr, XR_stringPtr, primary_tag_list, DerefSym, GetDataType, SmapTypeStrings, VarRecall


push_identity_mat

push_identity_mat Function (ROM Call 0x4A4)
AMS 2.00 or higher basfunc.h

void push_identity_mat (CESI);

Executes TI-Basic 'identity' function.

This identifier has not been documented yet. Please help us out.

Uses: GetValue, push_quantum, push0, push1
Used by: push_determinant, push_red_row_ech, push_row_echelon, push_simult, push_list_plus, push_sq_matrix_to_whole_number


push_im

push_im Function (ROM Call 0x546)
AMS 2.02 or higher basfunc.h

void push_im (CESI);

Executes TI-Basic 'imag' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_phase, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, map_tail, map_unary_over_comparison, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_internal_simplify, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, NG_control, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push0, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_instring

push_instring Function (ROM Call 0x31A)
AMS 1.01 or higher basfunc.h

void push_instring (CESI, CESI, CESI);

Executes TI-Basic 'inString' function.

This identifier has not been documented yet. Please help us out.

Uses: estack_to_ushort, push_expression, push_quantum, push_quantum_pair, push_ulong_to_integer, Integer1Index, push0


push_integer_gcd

push_integer_gcd Function (ROM Call 0x551)
AMS 2.02 or higher basfunc.h

void push_integer_gcd (CESI, CESI);

Executes TI-Basic 'gcd' function.

This identifier has not been documented yet. Please help us out.

Uses: push_gcd_numbers, push_expr2_quantum, did_map_aggregate_arg, primary_tag_list


push_integer_lcm

push_integer_lcm Function (ROM Call 0x552)
AMS 2.02 or higher basfunc.h

void push_integer_lcm (CESI, CESI);

Executes TI-Basic 'lcm' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_gcd_numbers, push_ratio, check_estack_size, delete_between, estack_number_to_Float, push_between, push_expr2_quantum, push_expression, push_Float, push_quantum, top_estack, ST_helpMsg, XR_stringPtr, did_map_aggregate_arg, is0, primary_tag_list, _bcd_math, _du16u16, _ds32s32, _ms32s32, push_exact0
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_integer_part

push_integer_part Function (ROM Call 0x54D)
AMS 2.02 or higher basfunc.h

void push_integer_part (CESI);

Executes TI-Basic 'iPart' function.

This identifier has not been documented yet. Please help us out.

Uses: push_ceiling, push_floor, push_negate, delete_between, map_tail, next_expression_index, push_expr_quantum, push_expression, push_quantum, top_estack, integer_non_unknown, is_neg_lead_numr_coef_re_part, is_nonnegative, is_nonpositive, negate_top, push_quantum_as_nonnegative_int, replace_top2_with_imre
Used by: push_integer_quotient, push_integer_remainder, push_product, push_to_dms


push_integer_quotient

push_integer_quotient Function (ROM Call 0x54F)
AMS 2.02 or higher basfunc.h

void push_integer_quotient (CESI, CESI);

Executes TI-Basic 'intDiv' function.

This identifier has not been documented yet. Please help us out.

Uses: push_integer_part, push_ratio, check_estack_size, delete_between, push_between, top_estack, did_map_aggregate_arg, is0, primary_tag_list, _du16u16, _ds32s32, _ms32s32
Used by: push_product


push_integer_remainder

push_integer_remainder Function (ROM Call 0x550)
AMS 2.02 or higher basfunc.h

void push_integer_remainder (CESI, CESI);

Executes TI-Basic 'remain' function.

This identifier has not been documented yet. Please help us out.

Uses: push_integer_part, push_ratio, delete_between, push_expression, top_estack, fabs, add_to_top, did_map_aggregate_arg, estack_to_float, is0, negate_top, times_top, _bcd_math
Used by: push_product


push_is_prime

push_is_prime Function (ROM Call 0x515)
AMS 2.02 or higher basfunc.h

void push_is_prime (CESI);

Executes TI-Basic 'isPrime' function.

This identifier has not been documented yet. Please help us out.

Uses: push_mod, push_difference, push_square, push_sum, check_estack_size, delete_between, deleted_between, estack_number_to_Float, push_between, push_expression, push_Float, push_quantum, push_quantum_pair, top_estack, ST_helpMsg, XR_stringPtr, add_to_top, estack_to_float, Integer2Index, IntegerMinus1Index, is0, primary_tag_list, push_quantum_as_nonnegative_int, _bcd_math, _du16u16, _ds32s32, _ms32s32, push_exact0, push_exact1


push_left

push_left Function (ROM Call 0x4A5)
AMS 2.00 or higher basfunc.h

void push_left (CESI, CESI);

Executes TI-Basic 'left' function.

This identifier has not been documented yet. Please help us out.

Uses: remaining_element_count, delete_between, estack_to_ushort, next_expression_index, push_expression, push_quantum, push_quantum_pair, top_estack, is_constant, primary_tag_list


push_lim

push_lim Function (ROM Call 0x5AD)
AMS 2.02 or higher basfunc.h

void push_lim (CESI, CESI, CESI, CESI);

Executes TI-Basic 'limit' function.

This identifier has not been documented yet. Please help us out.

Uses: did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_def_int, push_desolve, push_extended_prod, push_max, push_min, push_summation, did_push_approx_inflection_point, index_if_pushed_binomial_info


push_list_to_mat

push_list_to_mat Function (ROM Call 0x4A6)
AMS 2.00 or higher basfunc.h

void push_list_to_mat (CESI, CESI);

Executes TI-Basic 'list>mat' function.

This identifier has not been documented yet. Please help us out.

Uses: remaining_element_count, delete_between, GetValue, push_expression, push_quantum, top_estack, get_list_indices, push0, _du16u16, _mu16u16
Used by: did_push_anti_deriv, push_1st_derivative, push_cross_product, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_ln

push_ln Function (ROM Call 0x52F)
AMS 2.02 or higher basfunc.h

void push_ln (CESI);

Executes TI-Basic 'ln' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_diag, push_eigvc, push_eigvl, push_factor, push_re, push_rec_to_angle, push_sign, push_sin2, push_difference, push_exponentiate, push_negate, push_product, push_square, ER_catch, ER_success, ER_throwVar, delete_between, delete_expression, deleted_between, is_free_of_tag, is_square_matrix, lead_base_index, lead_factor_index, likely_approx_to_number, map_tail, map_unary_over_comparison, next_expression_index, push_expr_quantum, push_expression, push_Float, push_quantum, push_quantum_pair, remaining_factors_index, signum_Float, top_estack, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, log, add1_to_top, estack_to_float, FloatPiIndex, get_lb, get_ub, index_rmng_fctrs_start_fctr_tag, Integer1Index, IntegerMinus1Index, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, is_units_term, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_sq_matrix_to_whole_number, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_sum, times_top, _bcd_math, push_half, push_exact0
Used by: did_push_anti_deriv, push_1st_derivative, push_acosh, push_asin, push_atan, push_atanh, push_conj, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_lim, push_log10, push_max, push_min, push_nsolve, push_re, push_solve, push_summation, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_sum, get_ub, replace_top_with_post_simplified


push_log10

push_log10 Function (ROM Call 0x530)
AMS 2.02 or higher basfunc.h

void push_log10 (CESI);

Executes TI-Basic 'log' function.

This identifier has not been documented yet. Please help us out.

Uses: push_diag, push_eigvc, push_eigvl, push_ln, push_re, push_sin2, push_exponentiate, push_product, ER_catch, ER_success, ER_throwVar, delete_between, deleted_between, is_free_of_tag, is_square_matrix, map_tail, next_expression_index, push_Float, push_quantum, signum_Float, top_estack, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, log10, estack_to_float, IntegerMinus1Index, push_quantum_as_nonnegative_int, push_sq_matrix_to_whole_number, replace_top2_with_ratio, times_top, _bcd_math


push_mat_to_list

push_mat_to_list Function (ROM Call 0x4A8)
AMS 2.00 or higher basfunc.h

void push_mat_to_list (CESI);

Executes TI-Basic 'mat>list' function.

This identifier has not been documented yet. Please help us out.

Uses: is_matrix, next_expression_index, push_between, push_quantum
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, cmd_sorta, cmd_sortd, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_matnorm

push_matnorm Function (ROM Call 0x4A7)
AMS 2.00 or higher basfunc.h

void push_matnorm (CESI);

Executes TI-Basic 'matNorm' function.

This identifier has not been documented yet. Please help us out.

Uses: push_conj, push_sqrt, delete_between, is_matrix, top_estack, get_matrix_indices, push0, replace_top2_with_sum, times_top
Used by: push_unitv


push_max1

push_max1 Function (ROM Call 0x554)
AMS 2.02 or higher basfunc.h

void push_max1 (CESI);

Executes TI-Basic 'max' function for a single matrix.

This identifier has not been documented yet. Please help us out.

Uses: push_max2, delete_between, next_expression_index, push_expression, push_quantum, top_estack
Used by: push_colnorm, push_determinant, push_max2, push_red_row_ech, push_row_echelon, push_simult, push_sq_matrix_to_whole_number, cmd_lu_fact, cmd_qr_fact


push_max2

push_max2 Function (ROM Call 0x599)
AMS 2.02 or higher basfunc.h

void push_max2 (CESI, CESI);

Executes TI-Basic 'max' function.

This identifier has not been documented yet. Please help us out.

Uses: push_max1, push_difference, compare_expressions, is_free_of_tag, push_expression, push_quantum, top_estack, did_map_aggregate_arg, is_nonnegative, is_nonpositive
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_max1, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_max

push_max Function (ROM Call 0x58A)
AMS 2.02 or higher basfunc.h

void push_max (CESI, CESI);

Executes TI-Basic 'fMax' function.

Please see push_czeros entry for an important note for all solver ROM calls.

Uses: did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_lim, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_equals, push_exponentiate, push_indir_name, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_no_simplify, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, map_tail_Int, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, did_push_var_val, divide_top, does_push_fetch, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, DerefSym, VarRecall, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E2, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x5ED, ROM Call 0x606


push_mean

push_mean Function (ROM Call 0x4A9)
AMS 2.00 or higher basfunc.h

void push_mean (CESI);

Executes TI-Basic 'mean' function.

This identifier has not been documented yet. Please help us out.

Uses: push_sumlist, remaining_element_count, push_ulong_to_integer, top_estack, replace_top2_with_ratio
Used by: push_stddev, push_variance


push_median

push_median Function (ROM Call 0x4AA)
AMS 2.00 or higher basfunc.h

void push_median (CESI);

Executes TI-Basic 'median' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_string, push_sum, check_estack_size, compare_expressions, delete_between, is_matrix, push_expression, push_quantum, push_quantum_pair, top_estack, compare_numbers, divide_top, get_list_indices, get_matrix_indices, init_list_indices, Integer2Index, primary_tag_list


push_mid

push_mid Function (ROM Call 0x4AB)
AMS 2.00 or higher basfunc.h

void push_mid (CESI, CESI, CESI);

Executes TI-Basic 'mid' function.

This identifier has not been documented yet. Please help us out.

Uses: remaining_element_count, delete_between, estack_to_ushort, next_expression_index, push_expression, push_quantum, push_quantum_pair, top_estack, is_constant, primary_tag_list


push_min1

push_min1 Function (ROM Call 0x553)
AMS 2.02 or higher basfunc.h

void push_min1 (CESI);

Executes TI-Basic 'min' function for a single matrix.

This identifier has not been documented yet. Please help us out.

Uses: push_min2, delete_between, next_expression_index, push_expression, push_quantum, top_estack
Used by: push_min2


push_min2

push_min2 Function (ROM Call 0x598)
AMS 2.02 or higher basfunc.h

void push_min2 (CESI, CESI);

Executes TI-Basic 'min' function.

This identifier has not been documented yet. Please help us out.

Uses: push_min1, push_difference, compare_expressions, is_free_of_tag, push_expression, push_quantum, top_estack, did_map_aggregate_arg, is_nonnegative, is_nonpositive
Used by: push_min1, push_and


push_min

push_min Function (ROM Call 0x589)
AMS 2.02 or higher basfunc.h

void push_min (CESI, CESI);

Executes TI-Basic 'fMin' function.

Please see push_czeros entry for an important note for all solver ROM calls.

Uses: did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_lim, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_equals, push_exponentiate, push_indir_name, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_no_simplify, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, map_tail_Int, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, did_push_var_val, divide_top, does_push_fetch, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, DerefSym, VarRecall, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E2, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x5ED, ROM Call 0x606


push_mod

push_mod Function (ROM Call 0x54C)
AMS 2.02 or higher basfunc.h

void push_mod (CESI, CESI);

Executes TI-Basic 'mod' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_floor, push_difference, push_product, check_estack_size, delete_between, estack_number_to_Float, likely_approx_to_number, push_between, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_quantum, top_estack, fabs, floor, add_to_top, did_map_aggregate_arg, estack_to_float, Float0Index, get_lb, get_ub, is_negative, is_nonnegative, is_positive, is_real, is_variable, is0, is1, negate_top, primary_tag_list, push_gcd_then_cofactors, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, push_exact1
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_atan, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_is_prime, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


push_mrow

push_mrow Function (ROM Call 0x4AC)
AMS 2.00 or higher basfunc.h

void push_mrow (CESI, CESI, CESI);

Executes TI-Basic 'mRow' function.

This identifier has not been documented yet. Please help us out.

Uses: GetValue, is_matrix, push_mrow_aux


push_mrowadd

push_mrowadd Function (ROM Call 0x4AD)
AMS 2.00 or higher basfunc.h

void push_mrowadd (CESI, CESI, CESI, CESI);

Executes TI-Basic 'mRowAdd' function.

This identifier has not been documented yet. Please help us out.

Uses: push_product, push_sum, delete_between, GetValue, is_matrix, push_expression, push_quantum, top_estack, add_to_top, get_list_indices
Used by: push_determinant, push_red_row_ech, push_row_echelon, push_simult, push_sq_matrix_to_whole_number


push_newlist

push_newlist Function (ROM Call 0x4AE)
AMS 2.00 or higher basfunc.h

void push_newlist (CESI);

Executes TI-Basic 'newList' function.

This identifier has not been documented yet. Please help us out.

Uses: GetValue, push_quantum, push0


push_newmat

push_newmat Function (ROM Call 0x4AF)
AMS 2.00 or higher basfunc.h

void push_newmat (CESI, CESI);

Executes TI-Basic 'newMat' function.

This identifier has not been documented yet. Please help us out.

Uses: GetValue, push_quantum, push0


push_nint

push_nint Function (ROM Call 0x5B3)
AMS 2.02 or higher basfunc.h

void push_nint (CESI, CESI, CESI, CESI);

Executes TI-Basic 'nInt' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_difference, push_substitute_simplify, are_expressions_identical, delete_between, likely_approx_to_number, next_expression_index, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_internal_simplify, push_next_internal_var, push_offset_array, push_quantum, top_estack, fabs, estack_to_float, Float0Index, get_lb, get_ub, is_nonnegative, is_variable, NG_control, primary_tag_list, push_negate_quantum_as_negint, replace_top2_with_imre, replace_top2_with_prod, times_top, _bcd_math, push_exact_minus1


push_nsolve

push_nsolve Function (ROM Call 0x583)
AMS 2.02 or higher basfunc.h

void push_nsolve (CESI, CESI);

Executes TI-Basic 'nSolve' function.

This identifier has not been documented yet. Please help us out.

Uses: did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_indir_name, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_no_simplify, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, map_tail_Int, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, did_push_var_val, divide_top, does_push_fetch, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, DerefSym, VarRecall, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x5ED, ROM Call 0x606


push_nth_derivative

push_nth_derivative Function (ROM Call 0x5AF)
AMS 2.02 or higher basfunc.h

void push_nth_derivative (CESI, CESI, CESI);

Executes TI-Basic '¶' function.

This identifier has not been documented yet. Please help us out.

Uses: did_push_anti_deriv, push_1st_derivative, check_estack_size, delete_between, deleted_between, estack_number_to_Float, is_independent_of, next_expression_index, push_between, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_quantum, top_estack, ST_helpMsg, XR_stringPtr, fabs, integer_non_unknown, Integer1Index, IntegerMinus1Index, is_variable, is0, primary_tag_list, _bcd_math, _du16u16, _ds32s32, _ms32s32, push_exact0, ROM Call 0x5E7
Used by: did_push_approx_inflection_point


push_numerator

push_numerator Function (ROM Call 0x55A)
AMS 2.02 or higher basfunc.h

void push_numerator (CESI);

Executes TI-Basic 'getNum' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_phase, push_re, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


push_ord

push_ord Function (ROM Call 0x4B0)
AMS 2.00 or higher basfunc.h

void push_ord (CESI);

Executes TI-Basic 'ord' function.

This identifier has not been documented yet. Please help us out.

Uses: map_tail, next_expression_index, push_quantum, push_quantum_as_nonnegative_int


push_part

push_part Function (ROM Call 0x31C)
AMS 1.01 or higher basfunc.h

void push_part ();

Executes TI-Basic 'part' function.

This identifier has not been documented yet. Please help us out.

Uses: push_string, delete_between, get_key_ptr, GetValue, next_expression_index, push_expr_quantum, push_expression, push_internal_simplify, push_quantum_pair, push_ulong_to_integer, push_zstr, top_estack, primary_tag_list, push_simplify


push_perm

push_perm Function (ROM Call 0x541)
AMS 2.02 or higher basfunc.h

void push_perm (CESI, CESI);

Executes TI-Basic 'nPr' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_cos, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_factorial, push_product, push_ratio, delete_between, deleted_between, likely_approx_to_number, push_expression, push_Float, top_estack, modf, did_map_aggregate_arg, estack_to_float, get_lb, get_ub, IntegerMinus1Index, is_nonnegative, is_variable, is_whole_number, primary_tag_list, push_pi, push_reciprocal, push0, push1, replace_top2_with_imre, replace_top2_with_prod, times_top, _bcd_math, ROM Call 0x4DF, ROM Call 0x4E2
Used by: push_comb, push_factorial


push_phase

push_phase Function (ROM Call 0x548)
AMS 2.02 or higher basfunc.h

void push_phase (CESI);

Executes TI-Basic 'R>Pq' function for a complex number (?).

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_rec_to_angle, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, map_tail, map_unary_over_comparison, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_internal_simplify, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_negative, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, NG_control, primary_tag_list, push_but_factor, push_negate_quantum_as_negint, push_pi, push_quantum_as_nonnegative_int, push_reciprocal, push0, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_im, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, replace_top_with_post_simplified


push_polar_vector

push_polar_vector Function (ROM Call 0x4B1)
AMS 2.00 or higher basfunc.h

void push_polar_vector(ESI mat);

Executes the simplification of a vector written under polar form.

The matrix pointed to by mat must be a one-line, two-column matrix.

Uses: next_expression_index, push_quantum_pair, push_polar_to_rect_x, push_polar_to_rect_y

See also: push_cylin_vector, push_spher_vector


push_prodlist

push_prodlist Function (ROM Call 0x4B2)
AMS 2.00 or higher basfunc.h

void push_prodlist (CESI);

Executes TI-Basic 'product' function.

This identifier has not been documented yet. Please help us out.

Uses: next_expression_index, push_expression, push_quantum, is_constant, push1, times_top


push_propfrac

push_propfrac Function (Macro)
basfunc.h

void push_propfrac (CESI, CESI);

Executes TI-Basic 'propFrac' function.

This identifier has not been documented yet. Please help us out.


push_pttest

push_pttest Function (ROM Call 0x31D)
AMS 1.01 or higher basfunc.h

void push_pttest (CESI, CESI);

Executes TI-Basic 'ptTest' function.

This identifier has not been documented yet. Please help us out.

Uses: delete_between, GetValue, next_expression_index, push_quantum, top_estack, gr_active, ForceFloat, XCvtFtoP, YCvtFtoP, WinDupStat, WinPixGet


push_pxltest

push_pxltest Function (ROM Call 0x31E)
AMS 1.01 or higher basfunc.h

void push_pxltest (CESI, CESI);

Executes TI-Basic 'pxlTest' function.

This identifier has not been documented yet. Please help us out.

Uses: delete_between, GetValue, next_expression_index, push_quantum, top_estack, gr_active, ForceFloat, XCvtFtoP, YCvtFtoP, WinDupStat, WinPixGet


push_r_cis

push_r_cis Function (ROM Call 0x549)
AMS 2.02 or higher basfunc.h

void push_r_cis (CESI, CESI);

Executes TI-Basic 'R>Pq' function (?).

This identifier has not been documented yet. Please help us out.

Uses: push_cos, push_sin, top_estack, replace_top2_with_imre, times_top
Used by: push_sin2


push_rand

push_rand Function (ROM Call 0x31F)
AMS 1.01 or higher basfunc.h

void push_rand (CESI Range);

Executes TI-Basic 'rand' function.

push_rand pushes a random number on the expression stack. Range should point either to END_TAG, or to an integer expression. If Range points to END_TAG, push_rand pushes a floating point number between 0 and 1. If Range points to an integer value n, push_rand pushes an integer number between 1 and n if n is positive, or between -n and -1 if n is negative.

Note: This function calls the TI-Basic random number generator, so it has nothing to do with the random number generator from stdlib.h (i.e. with the functions rand, random, randomize, and srand). You can use the function cmd_randseed (instead of srand) to set the seed for the TI-Basic random number generator. Note also that push_rand is much slower than the random number generator implemented in stdlib.h.

Uses: delete_between, estack_number_to_Float, push_expression, push_Float, push_Float_to_rat, push_quantum, top_estack, memcpy, fabs, fpisanint, is_transfinite, estack_to_float, is_whole_number, is0, NG_control, primary_tag_list, _bcd_math

See also: cmd_randseed, rand, random


push_randmat

push_randmat Function (ROM Call 0x4B4)
AMS 2.00 or higher basfunc.h

void push_randmat (CESI, CESI);

Executes TI-Basic 'randMat' function.

This identifier has not been documented yet. Please help us out.

Uses: delete_expression, GetValue, push_Float, push_Float_to_rat, push_quantum, top_estack, memcpy, fpisanint, is_transfinite, _bcd_math


push_randnorm

push_randnorm Function (ROM Call 0x4B5)
AMS 2.00 or higher basfunc.h

void push_randnorm (CESI, CESI);

Executes TI-Basic 'randNorm' function.

This identifier has not been documented yet. Please help us out.

Uses: next_expression_index, NG_approxESI, push_Float, top_estack, memcpy, fpisanint, is_transfinite, log, sqrt, estack_to_float, _bcd_math


push_randpoly

push_randpoly Function (ROM Call 0x320)
AMS 1.01 or higher basfunc.h

void push_randpoly (CESI, CESI);

Executes TI-Basic 'randPoly' function.

This identifier has not been documented yet. Please help us out.

Uses: delete_between, delete_expression, estack_to_ushort, next_expression_index, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_quantum, top_estack, memcpy, fpisanint, is_transfinite, is0, primary_tag_list, push_quantum_as_nonnegative_int, DerefSym, VarRecall, _bcd_math


push_re

push_re Function (ROM Call 0x545)
AMS 2.02 or higher basfunc.h

void push_re (CESI);

Executes TI-Basic 'real' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_ln, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, map_tail, map_unary_over_comparison, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_internal_simplify, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, NG_control, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_exp, push_lim, push_ln, push_log10, push_max, push_min, push_nsolve, push_sin2, push_sinh, push_solve, push_tan, push_tanh, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_rec_to_angle

push_rec_to_angle Function (ROM Call 0x539)
AMS 2.02 or higher basfunc.h

void push_rec_to_angle (CESI, CESI);

Executes TI-Basic 'R>Pq' function.

This identifier has not been documented yet. Please help us out.

Uses: push_atan, push_sign, push_difference, push_ratio, push_sum, all_tail, delete_between, is_free_of_tag, next_expression_index, push_expr2_quantum, push_expression, push_Float, push_quantum, top_estack, atan2, add1_to_top, did_map_aggregate_arg, estack_to_float, FloatPiIndex, Integer0Index, Integer1Index, is_nonnegative, is0, negate_top, primary_tag_list, push_minus_recip_of_quantum, push_pi, push_pi_on_quantum, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract1_from_top, push_half, push_exact0
Used by: did_push_anti_deriv, push_1st_derivative, push_atan, push_atanh, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_ln, push_max, push_min, push_nsolve, push_phase, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_sum, push_to_cylin, push_to_sphere, get_ub


push_red_row_ech

push_red_row_ech Function (ROM Call 0x4B6)
AMS 2.00 or higher basfunc.h

void push_red_row_ech (CESI, CESI);

Executes TI-Basic 'rref' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_augment, push_dimension, push_identity_mat, push_max1, push_mrowadd, push_rownorm, push_rowswap, HeapAllocHighThrow, HeapFree, HeapLock, remaining_element_count, push_difference, push_negate, push_product, push_ratio, ER_catch, ER_success, ER_throwVar, delete_between, delete_expression, is_free_of_tag, is_matrix, likely_approx_to_number, next_expression_index, push_expression, push_Float, push_ulong_to_integer, top_estack, memcpy, OSCheckBreak, estack_to_float, get_lb, get_ub, Integer1Index, is_constant, is_nonnegative, is_variable, is0, NG_control, primary_tag_list, push_mrow_aux, push0, push1, replace_top2_with_prod, _bcd_math
Used by: push_desolve, cmd_sinreg


push_right

push_right Function (ROM Call 0x4B7)
AMS 2.00 or higher basfunc.h

void push_right (CESI, CESI);

Executes TI-Basic 'right' function.

This identifier has not been documented yet. Please help us out.

Uses: remaining_element_count, delete_between, estack_to_ushort, next_expression_index, push_expression, push_quantum, top_estack, is_constant, primary_tag_list


push_rotate

push_rotate Function (ROM Call 0x4B8)
AMS 2.00 or higher basfunc.h

void push_rotate (CESI, CESI);

Executes TI-Basic 'rotate' function.

This identifier has not been documented yet. Please help us out.

Uses: remaining_element_count, push_negate, check_estack_size, delete_between, estack_to_ushort, next_expression_index, push_between, push_expression, push_long_to_integer, push_quantum, push_quantum_pair, top_estack, ST_helpMsg, XR_stringPtr, IntegerMinus1Index, is_negative, primary_tag_list, _du16u16, _mu16u16, _ds32s32, _ms32s32


push_round

push_round Function (ROM Call 0x4B9)
AMS 2.00 or higher basfunc.h

void push_round (CESI, CESI);

Executes TI-Basic 'round' function.

This identifier has not been documented yet. Please help us out.

Uses: delete_between, delete_expression, next_expression_index, NG_approxESI, push_expr_quantum, push_expression, push_Float, push_Float_to_rat, push_offset_array, push_quantum, top_estack, memcpy, fpisanint, round12, estack_to_float, _bcd_math


push_row_echelon

push_row_echelon Function (ROM Call 0x4BE)
AMS 2.00 or higher basfunc.h

void push_row_echelon (CESI, CESI);

Executes TI-Basic 'ref' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_augment, push_dimension, push_identity_mat, push_max1, push_mrowadd, push_rownorm, push_rowswap, HeapAllocHighThrow, HeapFree, HeapLock, remaining_element_count, push_difference, push_negate, push_product, push_ratio, ER_catch, ER_success, ER_throwVar, delete_between, delete_expression, is_free_of_tag, is_matrix, likely_approx_to_number, next_expression_index, push_expression, push_Float, push_ulong_to_integer, top_estack, memcpy, OSCheckBreak, estack_to_float, get_lb, get_ub, Integer1Index, is_constant, is_nonnegative, is_variable, is0, NG_control, primary_tag_list, push_mrow_aux, push0, push1, replace_top2_with_prod, _bcd_math
Used by: push_desolve


push_rowadd

push_rowadd Function (ROM Call 0x4BA)
AMS 2.00 or higher basfunc.h

void push_rowadd (CESI, CESI, CESI);

Executes TI-Basic 'rowAdd' function.

This identifier has not been documented yet. Please help us out.

Uses: push_product, push_sum, delete_between, GetValue, is_matrix, push_expression, push_quantum, top_estack, add_to_top, get_list_indices


push_rowdim

push_rowdim Function (ROM Call 0x4BB)
AMS 2.00 or higher basfunc.h

void push_rowdim (CESI);

Executes TI-Basic 'rowDim' function.

This identifier has not been documented yet. Please help us out.

Uses: remaining_element_count, push_product, push_sum, delete_between, delete_expression, GetValue, is_matrix, push_expression, push_Float, push_Float_to_rat, push_quantum, top_estack, add_to_top, get_list_indices, _bcd_math


push_rownorm

push_rownorm Function (ROM Call 0x4BC)
AMS 2.00 or higher basfunc.h

void push_rownorm (CESI);

Executes TI-Basic 'rowNorm' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_difference, can_be_approxed, delete_between, is_matrix, likely_approx_to_number, top_estack, estack_to_float, get_lb, get_matrix_indices, get_ub, is_positive, is_variable, push0, replace_top2_with_sum, _bcd_math
Used by: push_determinant, push_red_row_ech, push_row_echelon, push_simult, push_sq_matrix_to_whole_number, cmd_lu_fact, cmd_qr_fact


push_rowswap

push_rowswap Function (ROM Call 0x4BD)
AMS 2.00 or higher basfunc.h

void push_rowswap (CESI, CESI, CESI);

Executes TI-Basic 'rowSwap' function.

This identifier has not been documented yet. Please help us out.

Uses: delete_between, GetValue, is_matrix, push_expression, push_quantum, top_estack, get_list_indices
Used by: push_determinant, push_red_row_ech, push_row_echelon, push_simult, push_sq_matrix_to_whole_number


push_sec

push_sec Function (Macro)
AMS 2.08 or higher basfunc.h

void push_sec (CESI);

Executes TI-Basic 'sec' function.

This identifier has not been documented yet. Please help us out.


push_sech

push_sech Function (Macro)
AMS 2.08 or higher basfunc.h

void push_sech (CESI);

Executes TI-Basic 'sech' function.

This identifier has not been documented yet. Please help us out.


push_sequence

push_sequence Function (ROM Call 0x4BF)
AMS 2.00 or higher basfunc.h

void push_sequence (CESI, CESI, CESI, CESI, CESI);

Executes TI-Basic 'seq' function.

This identifier has not been documented yet. Please help us out.

Uses: push_approx, push_difference, push_substitute_using_such_that, push_sum, check_estack_size, delete_between, delete_expression, is_matrix, push_between, push_expression, push_Float, push_Float_to_nonneg_int, push_quantum, push_quantum_pair, push_reversed_tail, top_estack, floor, add1_to_top, divide_top, estack_to_float, Integer1Index, is_negative, is0, primary_tag_list, _du16u16, _ds32s32, _ms32s32


push_setfold

push_setfold Function (ROM Call 0x321)
AMS 1.01 or higher basfunc.h

void push_setfold (CESI);

Executes TI-Basic 'setFold' function.

This identifier has not been documented yet. Please help us out.

Uses: push_zstr, ST_folder, ParseSymName, FolderCur, FolderGetCur, ValidateSymName


push_setgraph

push_setgraph Function (ROM Call 0x322)
AMS 1.01 or higher basfunc.h

void push_setgraph (CESI ModeNameString, CESI SettingString);

Executes TI-Basic 'setGraph' function.

push_setgraph assumes that ModeNameString points to the tag of a string expression (usually STR_TAG). It sets the appropriate Graph mode to the new string pointed to by SettingString (it should also point to the string tag), and pushes the previous setting string of that mode to the expression stack. Possible mode strings and settings strings are listed in the table below:

Mode name | Possible settings
"Coordinates" | "RECT", "POLAR", "OFF"
"Graph Order" | "SEQ", "SIMUL" (not available in SEQUENCE, 3D or DIFF EQUATIONS graph mode)
"Grid" | "OFF", "ON" (not available in 3D graph mode)
"Axes" | "OFF", "ON" (not 3D graph mode) "OFF", "AXES", "BOX" (3D graph mode)
"Leading Cursor" | "OFF", "ON" (not available in 3D graph mode)
"Labels" | "OFF", "ON"
"Style" | "WIRE FRAME", "HIDDEN SURFACE", "CONTOUR LEVELS", "WIRE AND CONTOUR", "IMPLICIT PLOT" (applies only to 3D graph mode)
"Seq Axes" | "TIME", "WEB", "U1-VS-U2" (applies only to SEQUENCE graph mode)
"DE Axes" | "TIME", "T-VS-Y'", "Y-VS-Y'", "Y1-VS-Y2", "Y1-VS-Y2'", "Y1'-VS-Y2'" (applies only to DIFF EQUATIONS graph mode)
"Solution Method" | "RK", "EULER" (applies only to DIFF EQUATIONS graph mode)
"Fields" | "SLPFLD", "DIRFLD", "FLDOFF" (applies only to DIFF EQUATIONS graph mode)

Uses: gr_active


push_setmode

push_setmode Function (ROM Call 0x323)
AMS 1.01 or higher basfunc.h

void push_setmode (CESI ModeNameStringOrList, CESI SettingString);

Executes TI-Basic 'setMode' function.

push_setmode assumes that ModeNameStringOrList points to the tag of a string expression (usually to STR_TAG), or to a list expression (usually to LIST_TAG). If it points to a string, push_setmode sets the appropriate mode to the new string pointed to by SettingString (it should also point to the string tag), and pushes the previous setting string of that mode to the expression stack. Possible mode strings and settings strings are listed in the table below:

Mode name | Possible settings
"Graph" | "FUNCTION", "PARAMETRIC", "POLAR", "SEQUENCE", "3D", "DIFF EQUATIONS"
"Display Digits" | "FIX 0", "FIX 1", ..., "FIX 12", "FLOAT 1", "FLOAT 2", ..., "FLOAT 12"
"Angle" | "RADIAN", "DEGREE"
"Exponential Format" | "NORMAL", "SCIENTIFIC", "ENGINEERING"
"Complex Format" | "REAL", "RECTANGULAR", "POLAR"
"Vector Format" | "RECTANGULAR", "CYLINDRICAL", "SPHERICAL"
"Pretty Print" | "OFF", "ON"
"Split Screen" | "FULL", "TOP-BOTTOM", "LEFT-RIGHT"
"Split 1 App" | "Home", "Y=Editor", "Window Editor", "Graph", "Table", "Data/Matrix Editor", "Program Editor", "Text Editor", "Numeric Solver"
"Split 2 App" | "Home", "Y=Editor", "Window Editor", "Graph", "Table", "Data/Matrix Editor", "Program Editor", "Text Editor", "Numeric Solver"
"Number of Graphs" | "1", "2"
"Graph2" | "FUNCTION", "PARAMETRIC", "POLAR", "SEQUENCE", "3D", "DIFF EQUATIONS"
"Exact/Approx" | "AUTO", "EXACT", "APPROXIMATE"
"Base" | "DEC", "HEX", "BIN"

If ModeNameStringOrList points to a list, this list is assumed to contain pairs of keyword strings. push_setmode will then set them all at once (SettingString is ignored in this case). This is recommended for multiple mode changes.

Note: push_setmode may cause switching of the current application. See the events.h header file for more info.

Uses: push_END_TAG, push_LIST_TAG, push_zstr, MO_currentOptions, MO_digestOptions


push_settable

push_settable Function (ROM Call 0x324)
AMS 1.01 or higher basfunc.h

void push_settable (CESI ModeNameString, CESI SettingString);

Executes TI-Basic 'setTable' function.

push_settable assumes that ModeNameString points to the tag of a string expression (usually STR_TAG). It sets the appropriate table parameter to the new string pointed to by SettingString (it should also point to the string tag), and pushes the previous setting string of that parameter to the expression stack. Possible parameter name strings and settings strings are listed in the table below:

Parameter name | Possible settings
"Graph <-> Table" | "OFF", "ON"
"Independent" | "AUTO", "ASK"


push_shift

push_shift Function (ROM Call 0x4C0)
AMS 2.00 or higher basfunc.h

void push_shift (CESI, CESI);

Executes TI-Basic 'shift' function.

This identifier has not been documented yet. Please help us out.

Uses: remaining_element_count, push_negate, check_estack_size, delete_between, estack_to_ushort, move_between_to_top, next_expression_index, push_between, push_expression, push_long_to_integer, push_quantum, push_quantum_pair, push_reversed_tail, top_estack, ST_helpMsg, XR_stringPtr, IntegerMinus1Index, is_negative, primary_tag_list, _du16u16, _ds32s32, _ms32s32


push_sign

push_sign Function (ROM Call 0x544)
AMS 2.02 or higher basfunc.h

void push_sign (CESI);

Executes TI-Basic 'sign' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_gcd_numbers, push_arg_minus_1, push_difference, push_product, are_expressions_identical, compare_expressions, delete_between, lead_base_index, lead_exponent_index, lead_term_index, likely_approx_to_number, map_tail, map_unary_over_comparison, next_expression_index, numeric_factor_index, push_expr_quantum, push_expression, push_Float, push_internal_simplify, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, is_pzero, is_uinf_or_nan, is_uzero, estack_to_float, Float1Index, get_lb, get_ub, Integer0Index, Integer1Index, IntegerMinus1Index, is_nonnegative, is_nonpositive, is_real, is_variable, is_whole_number, is1, NG_control, primary_tag_list, push_standardize, push1, replace_top2_with_pow, replace_top2_with_prod, times_top, _bcd_math, ROM Call 0x4DF, push_exact0, push_exact_minus1, push_minus1, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_asin, push_asinh, push_atan, push_atanh, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_ln, push_max, push_min, push_nsolve, push_rec_to_angle, push_sinh, push_solve, push_tanh, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, get_ub


push_simult

push_simult Function (ROM Call 0x4C1)
AMS 2.00 or higher basfunc.h

void push_simult (CESI, CESI, CESI);

Executes TI-Basic 'simult' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_augment, push_dimension, push_identity_mat, push_max1, push_mrowadd, push_rownorm, push_rowswap, HeapAllocHighThrow, HeapFree, HeapLock, remaining_element_count, push_difference, push_negate, push_product, push_ratio, ER_catch, ER_success, ER_throwVar, delete_between, delete_expression, is_free_of_tag, is_matrix, likely_approx_to_number, next_expression_index, push_expression, push_Float, push_ulong_to_integer, top_estack, memcpy, OSCheckBreak, estack_to_float, get_lb, get_ub, Integer1Index, is_constant, is_nonnegative, is_variable, is0, NG_control, primary_tag_list, push_mrow_aux, push0, push1, replace_top2_with_prod, _bcd_math
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_sin2

push_sin2 Function (ROM Call 0x531)
AMS 2.02 or higher basfunc.h

void push_sin2 (CESI, CESI);

Executes TI-Basic 'sin' and 'cos' functions.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_ceiling, push_cos, push_cosh, push_denominator, push_diag, push_eigvc, push_eigvl, push_exp, push_expand, push_mod, push_numerator, push_r_cis, push_re, push_sin, push_sinh, push_sqrt, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_ratio, push_square, push_sum, ER_catch, ER_success, ER_throwVar, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, did_push_cnvrt_Float_to_integer, estack_number_to_Float, factor_base_index, factor_exponent_index, index_numeric_term, is_advanced_tag, is_free_of_tag, is_square_matrix, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, floor, fmod, sin, sqrt, add_to_top, add1_to_top, compare_numbers, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, index_rmng_fctrs_start_fctr_tag, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_units_term, is_variable, is_whole_number, is0, is1, negate_top, primary_tag_list, push_but_factor, push_but_term, push_minus_recip_of_quantum, push_nonnumeric_factors, push_pi, push_quantum_as_nonnegative_int, push_quantum_pair_as_pos_frac, push_reciprocal, push_reciprocal_of_quantum, push_sq_matrix_to_whole_number, push0, raise_to_top, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_conj, push_cos, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_exp, push_lim, push_ln, push_log10, push_max, push_min, push_nsolve, push_sin, push_sinh, push_solve, push_tan, push_tanh, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum, get_ub


push_sin

push_sin Function (ROM Call 0x532)
AMS 2.02 or higher basfunc.h

void push_sin (CESI);

Executes TI-Basic 'sin' function.

This identifier has not been documented yet. Please help us out.

Uses: push_sin2, next_expression_index, push_Float, push_quantum, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, estack_to_float, Integer0Index, _bcd_math
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_perm, push_phase, push_r_cis, push_re, push_sin2, push_sinh, push_solve, push_tan, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, push_trig, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, push_spher_vector, push_polar_to_rect_y


push_sinh

push_sinh Function (ROM Call 0x53A)
AMS 2.02 or higher basfunc.h

void push_sinh (CESI);

Executes TI-Basic 'sinh' function.

This identifier has not been documented yet. Please help us out.

Uses: push_cos, push_cosh, push_diag, push_eigvc, push_eigvl, push_exp, push_re, push_sign, push_sin, push_sin2, push_exponentiate, push_negate, push_product, ER_catch, ER_success, ER_throwVar, delete_between, deleted_between, is_free_of_tag, is_square_matrix, lead_base_index, lead_exponent_index, map_tail, map_unary_over_comparison, next_expression_index, push_expr_quantum, push_expression, push_Float, push_overflow_to_infinity, push_quantum, remaining_factors_index, top_estack, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, log, sinh, estack_to_float, IntegerMinus1Index, is_neg_lead_numr_coef_re_part, is_real, is0, is1, negate_top, primary_tag_list, push_but_factor, push_sq_matrix_to_whole_number, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_sum, times_top, _bcd_math, push_half
Used by: did_push_anti_deriv, push_1st_derivative, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_sin2, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_sum, get_ub, replace_top_with_post_simplified


push_solve

push_solve Function (ROM Call 0x584)
AMS 2.02 or higher basfunc.h

void push_solve (CESI, CESI);

Executes TI-Basic 'solve' function.

Please see push_czeros entry for an important note for all solver ROM calls.

Uses: did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_indir_name, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_no_simplify, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, map_tail_Int, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, did_push_var_val, divide_top, does_push_fetch, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, DerefSym, VarRecall, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x5ED, ROM Call 0x606


push_spher_vector

push_spher_vector Function (ROM Call 0x4C2)
AMS 2.00 or higher basfunc.h

void push_spher_vector(ESI mat);

Executes the simplification of a vector written under spherical form.

The matrix pointed to by mat must be a one-line, three-column matrix, and all three elements of the matrix must be free of tag LIST_TAG.

Uses: push_trig, replace_top2_with_prod, times_top, push_cos, push_sin, is_free_of_tag, move_between_to_top, next_expression_index, push_expression, push_quantum_pair, top_estack

See also: push_cylin_vector, push_polar_vector


push_sqrt

push_sqrt Function (ROM Call 0x52B)
AMS 2.02 or higher basfunc.h

void push_sqrt (CESI);

Executes TI-Basic 'Ö' function.

This identifier has not been documented yet. Please help us out.

Uses: next_expression_index, push_Float, push_quantum, ccos, ccosh, cexp, csin, csinh, csqrt, ctan, ctanh, fabs, estack_to_float, push_reciprocal_of_quantum, raise_to_top, _bcd_math
Used by: did_push_anti_deriv, push_1st_derivative, push_abs, push_acosh, push_asin, push_atan, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_matnorm, push_max, push_min, push_nsolve, push_sin2, push_solve, push_stddev, push_variance, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_sum, push_to_cylin, push_to_sphere, get_ub, push_symbolic_qr_fact


push_stddev

push_stddev Function (ROM Call 0x4C3)
AMS 2.00 or higher basfunc.h

void push_stddev (CESI);

Executes TI-Basic 'stdDev' function.

This identifier has not been documented yet. Please help us out.

Uses: push_mean, push_sqrt, push_sumlist, remaining_element_count, push_product, push_ratio, push_sum, delete_between, delete_expression, map_tail, push_quantum, push_ulong_to_integer, top_estack, get_list_indices, negate_top


push_str_to_expr

push_str_to_expr Function (ROM Call 0x325)
AMS 1.01 or higher basfunc.h

void push_str_to_expr (CESI);

Executes TI-Basic 'expr' function.

This identifier has not been documented yet. Please help us out.

Uses: ER_catch, ER_success, ER_throwVar, delete_between, next_expression_index, push_parse_text, push_quantum, top_estack, NG_control, push_simplify_statements, ROM Call 0x5C5, ROM Call 0x5C7, ROM Call 0x5C8
Used by: push_simplify_statements

See also: push_string, push_parse_text


push_string

push_string Function (ROM Call 0x326)
AMS 1.01 or higher basfunc.h

void push_string (CESI expr);

Executes TI-Basic 'string' function.

push_string converts the expression pointed to by expr to a string and pushes this string on the expression stack. For example, after executing the code

push_shortint (100);
push_quantum_pair (VAR_X_TAG, ADD_TAG);
push_string (top_estack);
the string "x+100" will be pushed on the expression stack. See top_estack and Tags for more info about this example.

Of course, expr may point to a string containing a variable name, but it must not point to an ordinary string. Otherwise the string is truncated at the first space (but not after the 8th character). If you only want to push a string (not an expression converted to a string), a method which always works would be:
push_expr_quantum (expr, STR_TAG);

Uses: HeapFree, check_estack_size, Parse1DExpr, push_quantum, push_quantum_pair, top_estack, memmove, strlen
Used by: push_median, push_part, cmd_sorta, cmd_sortd, push_format

See also: push_str_to_expr, push_zstr, display_statements


push_submat

push_submat Function (ROM Call 0x4C4)
AMS 2.00 or higher basfunc.h

void push_submat (CESI, CESI, CESI, CESI, CESI);

Executes TI-Basic 'subMat' function.

This identifier has not been documented yet. Please help us out.

Uses: delete_between, GetValue, is_matrix, push_expression, push_quantum, top_estack, get_matrix_indices
Used by: push_symbolic_qr_fact


push_sumlist

push_sumlist Function (ROM Call 0x4C5)
AMS 2.00 or higher basfunc.h

void push_sumlist (CESI);

Executes TI-Basic 'sum' function.

This identifier has not been documented yet. Please help us out.

Uses: next_expression_index, push_expression, push_quantum, add_to_top, is_constant, push0
Used by: push_mean, push_stddev, push_variance, push_symbolic_qr_fact


push_summation

push_summation Function (ROM Call 0x5B4)
AMS 2.02 or higher basfunc.h

void push_summation (CESI, CESI, CESI, CESI);

Executes TI-Basic 'S' function.

This identifier has not been documented yet. Please help us out.

Uses: push_abs, push_approx, push_cos, push_exp, push_expand, push_factor, push_floor, push_lim, push_ln, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_factorial, push_negate, push_product, push_ratio, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, are_expressions_identical, check_estack_size, delete_between, delete_expression, deleted_between, did_push_cnvrt_Float_to_integer, factor_base_index, factor_exponent_index, is_free_of_tag, is_independent_of, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_offset_array, push_quantum, push_ulong_to_integer, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, floor, fmod, add_to_top, add1_to_top, and_onto_top, did_push_lincf, divide_top, estack_to_float, FloatExp1Index, FloatPiIndex, get_lb, get_ub, index_rmng_fctrs_start_base, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, is_undefined, is_variable, is_whole_number, is0, is1, negate_top, NG_control, NG_such_that_index, primary_tag_list, push_but_factor, push_dependent_factors, push_independent_factors, push_pi, push_quantum_pair_as_pos_frac, push1, raise_to_top, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, subtract1_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4E2, ROM Call 0x4E9, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_extended_prod


push_switch

push_switch Function (ROM Call 0x327)
AMS 1.01 or higher basfunc.h

void push_switch (CESI WinNum);

Executes TI-Basic 'switch' function.

push_switch expects that WinNum points to an integer expression. If this integer is 0, push_switch pushes the active window number (1 for left or top window, 2 for right or bottom window) to the expression stack. If this integer is 1 or 2, push_switch activates window 1 or 2 and pushes the previously active window number to the expressions stack. If WinNum points to END_TAG, push_switch switches windows and pushes the previously active window number to the expression stack. Of course, window switching is ignored if the calculator is not displaying a split screen.

Uses: push_approx, push_ulong_to_integer, top_estack, EV_switch, estack_to_float, EV_appSide, _bcd_math


push_tan

push_tan Function (ROM Call 0x534)
AMS 2.02 or higher basfunc.h

void push_tan (CESI);

Executes TI-Basic 'tan' function.

This identifier has not been documented yet. Please help us out.

Uses: push_cos, push_diag, push_eigvc, push_eigvl, push_re, push_sin, push_sin2, push_tanh, push_exponentiate, push_negate, push_product, ER_catch, ER_success, ER_throwVar, check_estack_size, delete_between, deleted_between, estack_number_to_Float, is_free_of_tag, is_square_matrix, map_tail, map_unary_over_comparison, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_quantum, top_estack, ST_helpMsg, XR_stringPtr, fabs, floor, add1_to_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, Integer1Index, IntegerMinus1Index, is_neg_lead_numr_coef_re_part, is_reciprocal_of_quantum, is0, negate_top, primary_tag_list, push_quantum_as_nonnegative_int, push_sq_matrix_to_whole_number, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, push_exact0, push_exact_minus1, push_exact1
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_tanh, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, push_trig, replace_top_with_post_simplified


push_tanh

push_tanh Function (ROM Call 0x53C)
AMS 2.02 or higher basfunc.h

void push_tanh (CESI);

Executes TI-Basic 'tanh' function.

This identifier has not been documented yet. Please help us out.

Uses: push_diag, push_eigvc, push_eigvl, push_exp, push_re, push_sign, push_sin2, push_tan, push_exponentiate, push_negate, push_product, ER_catch, ER_success, ER_throwVar, delete_between, deleted_between, is_free_of_tag, is_square_matrix, lead_base_index, lead_exponent_index, map_tail, map_unary_over_comparison, next_expression_index, push_expr_quantum, push_expression, push_Float, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ccos, ccosh, cexp, csin, csinh, ctan, ctanh, fabs, tanh, add_to_top, estack_to_float, IntegerMinus1Index, is_neg_lead_numr_coef_re_part, is_real, is0, is1, negate_top, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_sq_matrix_to_whole_number, push1, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, times_top, _bcd_math, push_exact0, push_exact_minus1, push_minus1
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_tan, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, replace_top_with_post_simplified


push_trig_collect

push_trig_collect Function (Macro)
basfunc.h

void push_trig_collect (CESI);

Executes TI-Basic 'tCollect' function.

This identifier has not been documented yet. Please help us out.


push_trig_expand

push_trig_expand Function (Macro)
basfunc.h

void push_trig_expand (CESI);

Executes TI-Basic 'tExpand' function.

This identifier has not been documented yet. Please help us out.


push_unitv

push_unitv Function (ROM Call 0x4C8)
AMS 2.00 or higher basfunc.h

void push_unitv (CESI);

Executes TI-Basic 'unitV' function.

This identifier has not been documented yet. Please help us out.

Uses: push_matnorm, remaining_element_count, push_ratio, delete_expression, is_matrix, top_estack


push_variance

push_variance Function (ROM Call 0x4C9)
AMS 2.00 or higher basfunc.h

void push_variance (CESI);

Executes TI-Basic 'variance' function.

This identifier has not been documented yet. Please help us out.

Uses: push_mean, push_sqrt, push_sumlist, remaining_element_count, push_product, push_ratio, push_sum, delete_between, delete_expression, map_tail, push_quantum, push_ulong_to_integer, top_estack, get_list_indices, negate_top


push_when

push_when Function (ROM Call 0x57D)
AMS 2.02 or higher basfunc.h

void push_when (CESI);

Executes TI-Basic 'when' function.

This identifier has not been documented yet. Please help us out.

Uses: push_and, push_not, next_expression_index, push_expression, push_internal_simplify, push_quantum, top_estack, NG_control, NG_such_that_index, or_onto_top, ROM Call 0x5ED


push_zeros

push_zeros Function (ROM Call 0x586)
AMS 2.02 or higher basfunc.h

void push_zeros (CESI, CESI);

Executes TI-Basic 'zeros' function.

Please see push_czeros entry for an important note for all solver ROM calls.

Uses: did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, remaining_element_count, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_indir_name, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_no_simplify, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, map_tail_Int, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, did_push_var_val, divide_top, does_push_fetch, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, DerefSym, VarRecall, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x5ED, ROM Call 0x606


NULL_INDEX

NULL_INDEX Constant
basfunc.h, estack.h

#define NULL_INDEX ((CESI) 0)

Describes an empty expression stack index.

NULL_INDEX is an expression stack index (ESI) equivalent to NULL. It can be used as a function argument in cases where the argument is optional.


basop.h

basop.h Header File
Header File Index

Routines for executing TI-Basic operators

Very few of the functions from this header file are documented as of now. Of course, the ones which are undocumented have not been tested, either. It is very likely that there are errors in this file, so use it with care.

However, we thought it might be a good idea to provide a header file for all of the built-in TI-Basic operators which have a documented entry in the jump table. This way, you can easily search for particular operators if you need them. If you use a function from this header file, please document it, too.

Many functions from this header file require their arguments to have some specific format. They usually have to be internally simplified, which can be achieved with the push_internal_simplify function from estack.h, and the result is an internally simplified expression as well.

If you do not want to accept the AMS dependency of these functions, you can usually construct an expression using their appropriate tags, and then call push_internal_simplify.

Functions
did_push_to_polar
Executes TI-Basic '>Polar' operator.
push_and
Executes TI-Basic 'and' operator.
push_arg_minus_1
Executes TI-Basic '-' operator with constant 1.
push_arg_plus_1
Executes TI-Basic '+' operator with constant 1.
push_assignment
Executes TI-Basic '->' operator or 'Define' command.
push_degrees
Executes TI-Basic '°' operator.
push_difference
Executes TI-Basic '-' operator.
push_dot_add
Executes TI-Basic '.+' operator.
push_dot_div
Executes TI-Basic './' operator.
push_dot_exponentiate
Executes TI-Basic '.^' operator.
push_dot_mult
Executes TI-Basic '.*' operator.
push_dot_sub
Executes TI-Basic '.-' operator.
push_equals
Executes TI-Basic '=' operator.
push_exponentiate
Executes TI-Basic '^' operator.
push_factorial
Executes TI-Basic '!' operator.
push_greater_than_or_equals
Executes TI-Basic '>=' operator.
push_greater_than
Executes TI-Basic '>' operator.
push_indir_name
Executes TI-Basic '#' operator.
push_less_than_or_equals
Executes TI-Basic '<=' operator.
push_less_than
Executes TI-Basic '<' operator.
push_list_plus
Executes TI-Basic '.+' operator.
push_list_times
Executes TI-Basic '.*' operator.
push_matrix_product
Executes TI-Basic '*' operator for matrices.
push_negate
Executes TI-Basic '-' (negation) operator.
push_not_equals
Executes TI-Basic '/=' operator.
push_not
Executes TI-Basic 'not' operator.
push_or
Executes TI-Basic 'or' operator.
push_percent
Executes TI-Basic '%' operator.
push_polar_to_rect_x
Executes TI-Basic 'P>Rx(' operator.
push_polar_to_rect_y
Executes TI-Basic 'P>Ry(' operator.
push_pow
Executes TI-Basic '^' operator for floats.
push_product
Executes TI-Basic '*' operator.
push_radians
Executes TI-Basic 'r' operator.
push_ratio
Executes TI-Basic '/' operator.
push_square
Executes TI-Basic '^' operator with exponent 2.
push_subscripted_element
Executes TI-Basic '[]' operator.
push_substitute_no_simplify
Executes TI-Basic '|' operator (unsimplified).
push_substitute_simplify
Executes TI-Basic '|' operator (simplified).
push_substitute_using_such_that
Executes TI-Basic '|' operator.
push_sum
Executes TI-Basic '+' operator.
push_to_cylin
Executes TI-Basic '>Cylind' operator.
push_to_dd
Executes TI-Basic '>DD' operator.
push_to_dms
Executes TI-Basic '>DMS' operator.
push_to_sphere
Executes TI-Basic '>Sphere' operator.
push_transpose
Executes TI-Basic 'T' operator.
push_xor
Executes TI-Basic 'xor' operator.
Global Variables
primary_tag_list
Array of structures containing information on Tags.
Predefined Types
CESI
Represents a pointer to a constant expression.
ESI
Represents an index of a value on the TIOS expression stack.
ESQ
Represents a quantum within an expression.
EStackIndex
Represents an index of a value on the TIOS expression stack.
Quantum
Represents a quantum within an expression.
SYM_STR
Represents a pointer to the terminating zero byte of a string.
tag_info
Structure containing information about AMS EStack tags (Tags, ExtTags).

Note: All functions from this header file get parameters from the expression stack, so this header file must be used in conjunction with estack.h. You need to learn about the usage of the expression stack before using any function from this header file. All functions defined here execute particular TI-Basic operators. They sometimes may be useful to perform some operations which cannot be implemented in C easily. But note that if you use functions from this header file too much, this will decrease the performance of your program significantly. In an extreme case, it will in fact decrease to that of a TI-Basic program! So use functions from this header file only if it is really necessary. Also note that these functions act exactly like the appropriate TI-Basic commands (including throwing errors if something is wrong), so the use of an error tracking mechanism from the error.h header file is highly recommended.

See also: bascmd.h, basfunc.h


did_push_to_polar

did_push_to_polar Function (ROM Call 0x313)
AMS 1.01 or higher basop.h

short did_push_to_polar ();

Executes TI-Basic '>Polar' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_rec_to_angle, push_sin, push_sqrt, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, is_free_of_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, is_inf, is_nan, sqrt, add_to_top, compare_numbers, did_map_aggregate_arg, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, NG_control, primary_tag_list, push_but_factor, push_negate_quantum_as_negint, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: replace_top_with_post_simplified


push_and

push_and Function (ROM Call 0x5AB)
AMS 2.02 or higher basop.h

void push_and (CESI, CESI);

Executes TI-Basic 'and' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_substitute_simplify, push_min2, are_expressions_identical, check_estack_size, compare_expressions, delete_between, deleted_between, is_independent_of, next_expression_index, push_between, push_expr_quantum, push_expression, push_long_to_integer, push_offset_array, push_quantum, top_estack, ST_helpMsg, XR_stringPtr, and_onto_top, is_variable, lead_conjunct_factor_index, NG_control, primary_tag_list, push_but_conjunct_factor, remaining_conjuncts_index, replace_top2_with_and, replace_top2_with_or, _du16u16, _ds32s32, _ms32s32
Used by: push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_when, push_zeros, and_onto_top, get_ub, replace_top2_with_and


push_arg_minus_1

push_arg_minus_1 Function (ROM Call 0x520)
AMS 2.02 or higher basop.h

void push_arg_minus_1 (CESI);

Executes TI-Basic '-' operator with constant 1.

This identifier has not been documented yet. Please help us out.

Uses: push_sum, FloatMinus1Index, IntegerMinus1Index
Used by: did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_sign, push_sin2, push_solve, push_summation, push_zeros, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, is_never0, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


push_arg_plus_1

push_arg_plus_1 Function (ROM Call 0x51F)
AMS 2.02 or higher basop.h

void push_arg_plus_1 (CESI);

Executes TI-Basic '+' operator with constant 1.

This identifier has not been documented yet. Please help us out.

Uses: push_sum, Float1Index, Integer1Index
Used by: did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_sin2, push_solve, push_summation, push_zeros, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


push_assignment

push_assignment Function (ROM Call 0x4DD)
AMS 2.00 or higher basop.h

void push_assignment (CESI);

Executes TI-Basic '->' operator or 'Define' command.

This identifier has not been documented yet. Please help us out.

Uses: push_indir_name, is_narrowly_independent_of, next_expression_index, push_expression, top_estack, assign_between, primary_tag_list, push_simplify, store_func_def, store_to_subscripted_element
Used by: cmd_get, GraphOrTableCmd, push_simplify_statements, cmd_lu_fact


push_degrees

push_degrees Function (ROM Call 0x314)
AMS 1.01 or higher basop.h

void push_degrees (CESI, CESI, CESI);

Executes TI-Basic '°' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_product, can_be_approxed, top_estack, add_to_top, is_negative, negate_top, push_pi_on_quantum, push_reciprocal_of_quantum, replace_top2_with_prod


push_difference

push_difference Function (ROM Call 0x51A)
AMS 2.02 or higher basop.h

void push_difference (CESI, CESI);

Executes TI-Basic '-' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_negate, add_to_top, primary_tag_list
Used by: did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, cmd_endfor, cmd_for, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_atan, push_atanh, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_is_prime, push_lim, push_ln, push_max, push_max2, push_min, push_min2, push_mod, push_nint, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_rec_to_angle, push_red_row_ech, push_row_echelon, push_rownorm, push_sequence, push_sign, push_simult, push_sin2, push_solve, push_summation, push_zeros, add_to_top, are_units_consistent, did_push_approx_inflection_point, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, is_equivalent_to, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, push_symbolic_qr_fact, raise_to_top, replace_top_with_post_simplified, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x606


push_dot_add

push_dot_add Function (ROM Call 0x4A0)
AMS 2.00 or higher basop.h

void push_dot_add (CESI, CESI);

Executes TI-Basic '.+' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_sum, did_map_aggregate_arg


push_dot_div

push_dot_div Function (ROM Call 0x4CD)
AMS 2.00 or higher basop.h

void push_dot_div (CESI, CESI);

Executes TI-Basic './' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_ratio, did_map_aggregate_arg
Used by: push_ratio, divide_top, replace_top2_with_ratio


push_dot_exponentiate

push_dot_exponentiate Function (ROM Call 0x596)
AMS 2.02 or higher basop.h

void push_dot_exponentiate (CESI, CESI);

Executes TI-Basic '.^' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_exponentiate, push_exp, ER_catch, ER_success, compare_Floats, delete_between, is_free_of_tag, next_expression_index, push_Float_to_rat, push_internal_simplify, push_quantum, top_estack, did_map_aggregate_arg, estack_to_float, FloatExp1Index, is_constant, is_nonnegative, is_real, is_whole_number, is1, NG_control, primary_tag_list, RAtionalize_tol, replace_top2_with_prod, _bcd_math, ROM Call 0x4DF


push_dot_mult

push_dot_mult Function (ROM Call 0x4A1)
AMS 2.00 or higher basop.h

void push_dot_mult (CESI, CESI);

Executes TI-Basic '.*' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_product, did_map_aggregate_arg


push_dot_sub

push_dot_sub Function (ROM Call 0x4A2)
AMS 2.00 or higher basop.h

void push_dot_sub (CESI, CESI);

Executes TI-Basic '.-' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_negate, add_to_top, did_map_aggregate_arg


push_equals

push_equals Function (ROM Call 0x5A3)
AMS 2.02 or higher basop.h

void push_equals (CESI, CESI);

Executes TI-Basic '=' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, remaining_element_count, did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606
Used by: push_max, push_min


push_exponentiate

push_exponentiate Function (ROM Call 0x595)
AMS 2.02 or higher basop.h

void push_exponentiate (CESI, CESI);

Executes TI-Basic '^' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_arg_minus_1, push_arg_plus_1, push_difference, push_negate, push_pow, push_product, push_square, push_sum, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_diag, push_eigvc, push_eigvl, push_exp, push_factor, push_gcd_numbers, push_ln, push_mod, push_numerator, push_re, push_rec_to_angle, push_sign, push_sin, push_sin2, push_sqrt, ER_catch, ER_success, ER_throwVar, all_tail, are_expressions_identical, can_be_approxed, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, index_numeric_term, is_advanced_tag, is_free_of_tag, is_independent_of, is_square_matrix, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_cnvrt_integer_if_whole_nmb, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, ST_helpMsg, XR_stringPtr, cexp, cln, fabs, floor, is_inf, is_nan, sqrt, add_to_top, add1_to_top, compare_numbers, did_map_aggregate_arg, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_negative, is_never0, is_nonnegative, is_nonpositive, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, negate_top, NG_control, primary_tag_list, push_but_factor, push_but_term, push_negate_quantum_as_negint, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_reciprocal_of_quantum, push_sq_matrix_to_whole_number, push_standardize, push0, push1, raise_to_top, replace_top_with_reciprocal, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4E0, ROM Call 0x4E2, ROM Call 0x4EA, push_half, push_exact0, push_minus1, ROM Call 0x4EF, push_exact1
Used by: did_push_to_polar, push_dot_exponentiate, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_square, push_sum, push_to_cylin, push_to_sphere, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_log10, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


push_factorial

push_factorial Function (ROM Call 0x540)
AMS 2.02 or higher basop.h

void push_factorial (CESI);

Executes TI-Basic '!' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_arg_plus_1, push_difference, push_product, push_approx, push_perm, delete_between, deleted_between, index_numeric_term, likely_approx_to_number, map_tail, map_unary_over_comparison, push_expr_quantum, push_expression, push_Float, push_overflow_to_infinity, push_quantum, top_estack, ST_helpMsg, XR_stringPtr, compare_numbers, estack_to_float, get_lb, get_ub, Integer2Index, is_nonnegative, is_units_term, is_variable, is_whole_number, is0, primary_tag_list, push_but_term, replace_top2_with_prod, replace_top2_with_ratio, _bcd_math, ROM Call 0x4DF, ROM Call 0x4EA
Used by: push_comb, push_extended_prod, push_perm, push_summation


push_greater_than_or_equals

push_greater_than_or_equals Function (ROM Call 0x5A7)
AMS 2.02 or higher basop.h

void push_greater_than_or_equals (CESI, CESI);

Executes TI-Basic '>=' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, remaining_element_count, did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606


push_greater_than

push_greater_than Function (ROM Call 0x5A5)
AMS 2.02 or higher basop.h

void push_greater_than (CESI, CESI);

Executes TI-Basic '>' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, remaining_element_count, did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606


push_indir_name

push_indir_name Function (ROM Call 0x2B2)
AMS 1.01 or higher basop.h

void push_indir_name (CESI);

Executes TI-Basic '#' operator.

This identifier has not been documented yet. Please help us out.

Uses: delete_between, next_expression_index, push_expression, push_internal_simplify, push_quantum, top_estack, next_token, primary_tag_list, push_var, DerefSym, FindSymInFolder, TempFolderName
Used by: push_assignment, cmd_get, push_csolve, push_czeros, push_max, push_min, push_nsolve, push_solve, push_zeros, push_internal_simplify, getcalc, sendcalc, push_simplify, push_user_func, store_func_def, store_to_subscripted_element, ROM Call 0x468, ROM Call 0x47F, ROM Call 0x480, push_subscripted_element


push_less_than_or_equals

push_less_than_or_equals Function (ROM Call 0x5A8)
AMS 2.02 or higher basop.h

void push_less_than_or_equals (CESI, CESI);

Executes TI-Basic '<=' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, remaining_element_count, did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606


push_less_than

push_less_than Function (ROM Call 0x5A6)
AMS 2.02 or higher basop.h

void push_less_than (CESI, CESI);

Executes TI-Basic '<' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, remaining_element_count, did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606


push_list_plus

push_list_plus Function (ROM Call 0x3BD)
AMS 1.01 or higher basop.h

void push_list_plus (CESI ptr1, CESI ptr2);

Executes TI-Basic '.+' operator.

Assuming that ptr1 and ptr2 point to tags of two lists (or matrices, which are "lists of lists"), push_list_plus pushes the element-by-element sum of these two lists to the expression stack. If the lists are not equal in size, an error will be thrown. If ptr1 or ptr2 doesn't point to a list tag, the behavior is unpredictable.

Uses: push_sum, remaining_element_count, push_identity_mat, delete_between, is_square_matrix, push_offset_array, push_quantum, push_ulong_to_integer, top_estack, add_to_top, times_top
Used by: push_sum


push_list_times

push_list_times Function (ROM Call 0x3BE)
AMS 1.01 or higher basop.h

void push_list_times (CESI ptr1, CESI ptr2);

Executes TI-Basic '.*' operator.

Assuming that ptr1 and ptr2 point to tags of two lists (or matrices, which are "lists of lists"), push_list_times pushes an element-by-element product of these two lists to the expression stack. If the lists are not equal in size, an error will be thrown. If ptr1 or ptr2 doesn't point to a list tag, the behavior is unpredictable.

Uses: push_matrix_product, push_product, delete_between, push_offset_array, push_quantum, top_estack
Used by: push_product


push_matrix_product

push_matrix_product Function (ROM Call 0x3C5)
AMS 1.01 or higher basop.h

void push_matrix_product (CESI ptr1, CESI ptr2);

Executes TI-Basic '*' operator for matrices.

Assuming that ptr1 and ptr2 point to tags of two matrices (which are, in fact, lists of equally sized lists), push_matrix_product pushes the matrix product of these two matrices to the expression stack. As the matrix product is not comutative, the matrix pointed to by ptr1 is assumed to be the first factor. If the matrices are not compatible for multiplying, an error will be thrown. If ptr1 or ptr2 don't point to matrices, the behavior is unpredictable.

Uses: push_product, delete_between, push_quantum, top_estack, get_matrix_indices, push0, replace_top2_with_sum
Used by: push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_list_times, push_not_equals, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, get_ub, push_sq_matrix_to_whole_number


push_negate

push_negate Function (ROM Call 0x524)
AMS 2.02 or higher basop.h

void push_negate (CESI);

Executes TI-Basic '-' (negation) operator.

This identifier has not been documented yet. Please help us out.

Uses: push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_pow, push_product, push_square, push_sum, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_gcd_numbers, push_mod, push_numerator, push_sin, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, add_to_top, compare_numbers, estack_to_float, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_to_polar, push_difference, push_dot_sub, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_comdenom, push_conj, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_integer_part, push_lim, push_ln, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_red_row_ech, push_rotate, push_row_echelon, push_shift, push_simult, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, is_antisymmetric, is_symmetric, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, is_negative, is_nonnegative, is_nonpositive, is_positive, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, subtract_from_top


push_not_equals

push_not_equals Function (ROM Call 0x5A4)
AMS 2.02 or higher basop.h

void push_not_equals (CESI, CESI);

Executes TI-Basic '/=' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, remaining_element_count, did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606


push_not

push_not Function (ROM Call 0x5AA)
AMS 2.02 or higher basop.h

void push_not (CESI);

Executes TI-Basic 'not' operator.

This identifier has not been documented yet. Please help us out.

Uses: check_estack_size, delete_between, map_tail, next_expression_index, push_between, push_expr_quantum, push_expression, push_long_to_integer, push_quantum, top_estack, ST_helpMsg, XR_stringPtr, is_variable, replace_top2_with_and, replace_top2_with_or, _du16u16, _ds32s32, _ms32s32
Used by: push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_xor, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_when, push_zeros, get_ub


push_or

push_or Function (ROM Call 0x5AC)
AMS 2.02 or higher basop.h

void push_or (CESI, CESI);

Executes TI-Basic 'or' operator.

This identifier has not been documented yet. Please help us out.

Uses: are_expressions_identical, check_estack_size, compare_expressions, delete_between, next_expression_index, push_between, push_expr_quantum, push_expression, push_long_to_integer, push_offset_array, push_quantum, top_estack, ST_helpMsg, XR_stringPtr, lead_conjunct_factor_index, lead_disjunct_term_index, or_onto_top, primary_tag_list, remaining_conjuncts_index, remaining_disjuncts_index, _du16u16, _ds32s32, _ms32s32
Used by: or_onto_top, replace_top2_with_or


push_percent

push_percent Function (ROM Call 0x555)
AMS 2.02 or higher basop.h

void push_percent (CESI);

Executes TI-Basic '%' operator.

This identifier has not been documented yet. Please help us out.

Uses: is_units_term, push_reciprocal_of_quantum, times_top


push_polar_to_rect_x

push_polar_to_rect_x Function (ROM Call 0x4F9)
AMS 2.00 or higher basop.h

void push_polar_to_rect_x(CESI rexpr, CESI thetaexpr);

Executes TI-Basic 'P>Rx(' operator.

This identifier has not been documented yet. Please help us out.

Uses: did_map_aggregate_arg, push_trig, times_top, push_cos, is_free_of_tag
Used by: push_cylin_vector, push_polar_vector


push_polar_to_rect_y

push_polar_to_rect_y Function (ROM Call 0x4FA)
AMS 2.00 or higher basop.h

void push_polar_to_rect_y(CESI rexpr, CESI thetaexpr);

Executes TI-Basic 'P>Ry(' operator.

This identifier has not been documented yet. Please help us out.

Uses: did_map_aggregate_arg, push_trig, times_top, push_sin, is_free_of_tag
Used by: push_cylin_vector, push_polar_vector


push_pow

push_pow Function (ROM Call 0x30F)
AMS 1.01 or higher basop.h

void push_pow (CESI base_ptr, CESI exp_ptr);

Executes TI-Basic '^' operator for floats.

Assuming that base_ptr and exp_ptr point to tags of two floating point numbers (called x and y for example), push_pow calculates x ^ y and pushes the result to the expression stack. If this assumption is not true, garbage will be pushed instead.

Uses: push_Float, pow, estack_to_float
Used by: did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_zeros, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


push_product

push_product Function (ROM Call 0x521)
AMS 2.02 or higher basop.h

void push_product (CESI, CESI);

Executes TI-Basic '*' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_list_times, push_negate, push_pow, push_ratio, push_square, push_sum, push_abs, push_approx, push_ceiling, push_conj, push_cos, push_denominator, push_exp, push_fractional_part, push_gcd_numbers, push_integer_part, push_integer_quotient, push_integer_remainder, push_mod, push_numerator, push_sign, push_sin, push_sin2, ER_catch, ER_success, ER_throwVar, all_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, is_free_of_tag, is_monomial, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, add_to_top, compare_numbers, divide_top, estack_to_float, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, index_reductum_with_tag_base, index_rmng_fctrs_start_base, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_positive, is_real, is_reciprocal_of_quantum, is_units_term, is_variable, is_whole_number, is0, is1, negate_top, NG_control, primary_tag_list, push_but_factor, push_gcd_then_cofactors, push_negate_quantum_as_negint, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, raise_to_top, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, is_temperature_unit, ROM Call 0x4DF, ROM Call 0x4E0, ROM Call 0x4E9, ROM Call 0x4EA, push_half, push_exact0, push_minus1, ROM Call 0x4EF, push_exact1
Used by: did_push_to_polar, push_degrees, push_dot_mult, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_list_times, push_matrix_product, push_negate, push_not_equals, push_sum, push_to_cylin, push_to_sphere, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_cosh, push_cross_product, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_dotproduct, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_log10, push_max, push_min, push_mod, push_mrowadd, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_red_row_ech, push_row_echelon, push_rowadd, push_rowdim, push_sign, push_simult, push_sin2, push_sinh, push_solve, push_stddev, push_summation, push_tan, push_tanh, push_variance, push_zeros, add_to_top, are_units_consistent, did_push_approx_inflection_point, get_ub, index_if_pushed_qquad_info, is_term_improper, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_mrow_aux, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, push_symbolic_qr_fact, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, times_top, push_to_dms


push_radians

push_radians Function (ROM Call 0x4B3)
AMS 2.00 or higher basop.h

void push_radians (CESI);

Executes TI-Basic 'r' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_ratio, delete_expression, is_free_of_tag, next_expression_index, push_expression, top_estack, push_pi_on_quantum


push_ratio

push_ratio Function (ROM Call 0x526)
AMS 2.02 or higher basop.h

void push_ratio (CESI, CESI);

Executes TI-Basic '/' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_dot_div, estack_number_to_Float, is_complex_number, next_expression_index, push_expression, push_Float, top_estack, Float0Index, is_complex_Float, primary_tag_list, push_reciprocal, replace_top2_with_imre, times_top, _bcd_math
Used by: push_dot_div, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_radians, push_sum, push_to_sphere, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asinh, push_atan, push_comb, push_csolve, push_czeros, push_def_int, push_desolve, push_determinant, push_expand, push_extended_prod, push_factor, push_integer_lcm, push_integer_quotient, push_integer_remainder, push_lim, push_max, push_min, push_nsolve, push_perm, push_rec_to_angle, push_red_row_ech, push_row_echelon, push_simult, push_sin2, push_solve, push_stddev, push_summation, push_unitv, push_variance, push_zeros, EV_defaultHandler, HomeExecute, are_units_consistent, did_push_divide_units, get_ub, push_div_dif_1c, push_div_dif_1f, push_gcd_then_cofactors, push_lu_fact, push_poly_qr, push_sq_matrix_to_whole_number, push_symbolic_qr_fact, replace_top_with_post_simplified


push_square

push_square Function (ROM Call 0x52C)
AMS 2.02 or higher basop.h

void push_square (CESI);

Executes TI-Basic '^' operator with exponent 2.

This identifier has not been documented yet. Please help us out.

Uses: push_exponentiate, Integer2Index
Used by: did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_asin, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_is_prime, push_lim, push_ln, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_zeros, compare_complex_magnitudes, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


push_subscripted_element

push_subscripted_element Function (ROM Call 0x4D1)
AMS 2.00 or higher basop.h

void push_subscripted_element (CESI);

Executes TI-Basic '[]' operator.

This identifier has not been documented yet. Please help us out.

Uses: dv_findColumn, is_negative, primary_tag_list, push_indir_name, all_tail, delete_between, estack_to_ushort, HToESI, map_tail, next_expression_index, push_expression, push_internal_simplify, push_quantum, top_estack, DerefSym, VarRecall, ROM Call 0x450
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_substitute_no_simplify

push_substitute_no_simplify Function (ROM Call 0x489)
AMS 2.00 or higher basop.h

void push_substitute_no_simplify (CESI, CESI, CESI);

Executes TI-Basic '|' operator (unsimplified).

This identifier has not been documented yet. Please help us out.

Uses: are_expressions_identical, delete_between, next_expression_index, push_expression, push_offset_array, push_quantum, top_estack, primary_tag_list, secondary_tag_list
Used by: push_csolve, push_czeros, push_max, push_min, push_nsolve, push_solve, push_zeros


push_substitute_simplify

push_substitute_simplify Function (ROM Call 0x5B9)
AMS 2.04 or higher basop.h

void push_substitute_simplify (CESI, CESI, CESI);

Executes TI-Basic '|' operator (simplified).

This identifier has not been documented yet. Please help us out.

Uses: ER_catch, ER_success, ER_throwVar, delete_between, push_expression, push_internal_simplify, push_quantum, top_estack, ROM Call 0x5E4
Used by: push_and, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, did_push_anti_deriv, did_push_series, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_lim, push_max, push_min, push_nint, push_nsolve, push_solve, push_summation, push_zeros, is_antisymmetric, is_symmetric, did_push_approx_inflection_point, get_ub, index_if_pushed_binomial_info, push_div_dif_1c, push_div_dif_1f


push_substitute_using_such_that

push_substitute_using_such_that Function (ROM Call 0x5BE)
AMS 2.04 or higher basop.h

void push_substitute_using_such_that (CESI expr, CESI var, CESI replacement);

Executes TI-Basic '|' operator.

This identifier has not been documented yet. Please help us out.

Uses: ER_catch, ER_success, ER_throwVar, delete_between, is_independent_of, is_independent_of_elements, push_expr2_quantum, push_expression, push_internal_simplify, top_estack, and_onto_top, lead_conjunct_factor_index, NG_such_that_index, primary_tag_list, remaining_conjuncts_index
Used by: push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_sequence, push_solve, push_summation, push_zeros, did_push_approx_inflection_point, get_ub, GM_Intersect, GM_Math1


push_sum

push_sum Function (ROM Call 0x594)
AMS 2.02 or higher basop.h

void push_sum (CESI, CESI);

Executes TI-Basic '+' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_list_plus, push_negate, push_pow, push_product, push_ratio, push_square, push_abs, push_approx, push_ceiling, push_cos, push_cosh, push_denominator, push_gcd_numbers, push_ln, push_mod, push_numerator, push_rec_to_angle, push_sin, push_sin2, push_sinh, push_sqrt, ER_catch, ER_success, ER_throwVar, all_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, index_of_lead_base_of_lead_term, is_advanced_tag, is_monomial, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, ST_helpMsg, XR_stringPtr, fabs, float_class, sqrt, add_to_top, compare_numbers, divide_top, estack_to_float, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, index_reductum_with_tag_base, index_rmng_fctrs_start_base, index_rmng_fctrs_start_fctr_tag, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_equivalent_to, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_term_improper, is_variable, is_whole_number, is0, is1, negate_top, NG_control, primary_tag_list, push_but_factor, push_but_term, push_gcd_then_cofactors, push_make_proper, push_negate_quantum_as_negint, push_nonnumeric_factors, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, raise_to_top, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_to_polar, push_arg_minus_1, push_arg_plus_1, push_dot_add, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_list_plus, push_negate, push_not_equals, push_product, push_to_cylin, push_to_sphere, cmd_endfor, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_atan, push_atanh, push_comdenom, push_csolve, push_cumsum, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_is_prime, push_lim, push_max, push_median, push_min, push_mrowadd, push_nsolve, push_numerator, push_phase, push_re, push_rec_to_angle, push_rowadd, push_rowdim, push_sequence, push_sin2, push_solve, push_stddev, push_summation, push_variance, push_zeros, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, is_term_improper, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_sum


push_to_cylin

push_to_cylin Function (ROM Call 0x328)
AMS 1.01 or higher basop.h

void push_to_cylin ();

Executes TI-Basic '>Cylind' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_rec_to_angle, push_sin, push_sqrt, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, is_free_of_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, is_inf, is_nan, sqrt, add_to_top, compare_numbers, did_map_aggregate_arg, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, NG_control, primary_tag_list, push_but_factor, push_negate_quantum_as_negint, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: replace_top_with_post_simplified


push_to_dd

push_to_dd Function (ROM Call 0x4C6)
AMS 2.00 or higher basop.h

void push_to_dd(CESI expr);

Executes TI-Basic '>DD' operator.

This identifier has not been documented yet. Please help us out.

Uses: is_negative, negate_top, push_negate_quantum_as_negint, push_quantum_as_nonnegative_int, times_top, is_free_of_tag, map_tail, push_expression, push_quantum, top_estack


push_to_dms

push_to_dms Function (ROM Call 0x4C7)
AMS 2.00 or higher basop.h

void push_to_dms(CESI expr);

Executes TI-Basic '>DMS' operator.

This identifier has not been documented yet. Please help us out.

Uses: is_negative, is0, negate_top, primary_tag_list, push_negate_quantum_as_negint, push_quantum_as_nonnegative_int, times_top, push_fractional_part, push_integer_part, push_product, delete_between, delete_expression, is_free_of_tag, map_tail, next_expression_index, push_expression, push_Float_to_rat, push_quantum, push_reversed_tail, top_estack


push_to_sphere

push_to_sphere Function (ROM Call 0x329)
AMS 1.01 or higher basop.h

void push_to_sphere ();

Executes TI-Basic '>Sphere' operator.

This identifier has not been documented yet. Please help us out.

Uses: push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_ratio, push_square, push_sum, push_abs, push_acos, push_approx, push_asin, push_atan, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_rec_to_angle, push_sin, push_sqrt, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, is_free_of_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, itrig, sqrt, add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, NG_control, primary_tag_list, push_but_factor, push_negate_quantum_as_negint, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: replace_top_with_post_simplified


push_transpose

push_transpose Function (ROM Call 0x4D2)
AMS 2.00 or higher basop.h

void push_transpose(CESI mat);

Executes TI-Basic 'T' operator.

This routine calls push_transpose_aux with parameter ConjFlag=1.

Uses: is_matrix, push_transpose_aux
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_xor

push_xor Function (Macro)
basop.h

void push_xor (CESI, CESI);

Executes TI-Basic 'xor' operator.

This identifier has not been documented yet. Please help us out.

Uses: top_estack, primary_tag_list, push_long_to_integer, push_quantum, delete_between, memmove, push_not, check_estack_size, map_tail, next_expression_index, push_between, push_expr_quantum, push_expression, ST_helpMsg, XR_stringPtr, is_variable, replace_top2_with_and, replace_top2_with_or, _du16u16, _ds32s32, _ms32s32, and_onto_top, push_and, are_expressions_identical, delete_expression, push_or
Used by: primary_tag_list


cert.h

cert.h Header File
Header File Index

Routines for accessing certificates and other memory-mapped files

Functions
ceof
Returns end-of-file status of the context.
cfindfield
Finds a matching field from a context.
cgetc
Gets a character from a context.
cgetcertrevno
Gets a certificate revision number.
cgetflen
Gets the length of a field.
cgetfnl
Gets a non-aligned long integer from a field.
cgetnl
Gets a non-aligned long integer from a context.
cgetns
Gets a non-aligned short integer from a context.
cgetsn
Gets the calculator serial number from the Flash ROM certificate.
copen
Opens a certificate file context.
copensub
Opens a subcontext.
cputhdr
Puts a field header to a context.
cputnl
Puts a non-aligned long integer to a context.
cputns
Puts a non-aligned short integer to a context.
cread
Reads a field from a context.
ctell
Returns the current position relative to the start of a context.
cwrite
Puts a field to a context.
freeIdList
Releases and deletes the RAM copy of the ID list, if it exists.
Global Variables
CertificateMemory
A pointer to the certificate memory.
Constants
H_NULL
A null-handle value.
NULL
A null-pointer value.
Predefined Types
Bool
An enumeration to describe true or false values.
CERT_FIELD
A structure describing the records of certificate files.
CFILE
A structure representing the context of a memory-mapped file.
HANDLE
Represents a handle associated with an allocated memory block.
size_t
A type to define sizes of strings and memory blocks.

Note: The functions caddcert, cgetcert, cgetvernum and cfindcertfield, which were present in the AMS 1.xx TIOS jump table, don't exist in the AMS 2.xx TIOS jump table any more. Fortunately, all of them are only internal routines; you need to use FL_addCert, FL_getCert and FL_getVerNum from flash.h instead.

In AMS 2.xx, the function replacing ROM_CALL 12C (cgetcert in AMS 1.xx), is HeapWalk.


ceof

ceof Function (ROM Call 0x128)
cert.h

short ceof (CFILE *context);

Returns end-of-file status of the context.

ceof returns TRUE if the end-of-file indicator of the file associated with the file context pointed to by context is set, otherwise it returns FALSE.

Used by: cread


cfindfield

cfindfield Function (ROM Call 0x12A)
cert.h

short cfindfield (CFILE *context, unsigned short FieldID, CERT_FIELD *dest);

Finds a matching field from a context.

cfindfield searches a file associated with the file context pointed to by context for a field which has field ID number equal to FieldID (length bits should be set to 0). If such field is found, cfindfield fills the field descriptor structure pointed to by dest and returns TRUE, else returns FALSE.

cfindfield is used often in TIOS to access particular data in a certificate file. Usually, function copensub is called immediately after cfindfield to get access to the content of the field. If the field contains subfields, this procedure may be repeated several times if necessary.

As an illustration of layout of certificate files, the layout of certificate files used in TIOS is given below. First, the field ID number is shown, then the short description of the field follows. Indentation shows that a particular field is a subfield of the field with smaller indentation.

  • Layout of AMS header (AMS is part of TIOS which may be replaced, unlike Boot Code); it starts at address ROM_base+0x12000, i.e. 0x212000 on TI-89 and V200, 0x412000 on TI-92 Plus and 0x812000 on TI-89T.

    0x8000 AMS header (organized as a certificate file, although it is not
                   read-protected like "real" certificates)

0x8010  First part of Product ID
0x8020  Third part of Product ID
0x8030  Fourth part of Product ID
0x80A0  Second part of Product ID
0x8040  Product Name: "Advanced Mathematics Software"
0x0320  Product code (6 bytes)
0x0200  Signature - encrypted MD5 (see rsa.h) of 0x320 field
        (including header)
0x8070  Actual AMS code

0x0200 Signature of entire AMS
    Fields with ID numbers 0x0320 and 0x0200 contains an authenticated number. More precisely, field with ID number 0x0320 contains a 4-byte field with ID 0x0900, itself containing a 32-bit timestamp: number of seconds elapsed since January 1st 1997, 00:00 in some timezone (GMT ?), and the time the OS image was signed. Field with ID 0x0200 is the encrypted digital signature of it.
    Product ID is formed by applying format string "%02lX-%lX-%lx-%lX" to the content of fields with ID numbers 0x8010, 0x80A0, 0x8020 and 0x8030.

  • Layout of Flash ROM certificate (stored in the part of the Flash ROM which is read-protected when the Protection is enabled); it starts at address ROM_base+0x10004, i.e. 0x210004 on TI-89 and V200, 0x410004 on TI-92 Plus and 0x810004 on TI-89T:

    0x0330 Flash ROM certificate

0xA10 Five-byte Serial Number (used as "pass phrase")
0xA20 Certificate Key
    Serial number has layout #sssss sssss cccc (all digits are in hex). First ten digits are picked up from the field with ID number 0xA10. Then, the Certificate Key is used to decrypt the MD5 (see rsa.h for more info about RSA encryption) of the Serial Number to get cccc. In fact, decrypting the Serial Number in this way creates a 40 byte number. Only first two bytes (in little endian) are taken for cccc. This method ensures that only TI can create valid Serial Numbers, as both the Serial Number and Key are unique for each machine.

  • Layout of .cer files, which are attached to the start of Flash applications:

    0x0300 Flash application certificate

0x0100 Certificate Revision Number
0x0400 Five-byte Serial Number
0x0500 Optional field in .cer files

0x0510 Author name

0x0320 Product code - same construction and meaning as the field in AMS itself, see above
0x0200 Product code signature - see above
0x0700 Unknown certificate data

0x0710 Unknown byte data
0x0730 Signature
0x0710 Unknown word data
0x0730 Signature
0x0710 Unknown word data
0x0730 Signature

0x0200 Signature of all certificate data
    Of course, such data are present in the certificate memory only if you have installed additional Flash applications. Function FL_addCert is used to add such data to the certificate memory (this routine performs very strong checking of what may be written there and under what conditions, so it is not possible to write a garbage in this area by calling this routine).
As it is not possible to access the certificate part of Flash ROM directly, because this area of Flash is read-protected when the Protection is enabled, the usual method (there's an unusual method that doesn't even require disabling the Protection from the client program) for reading certificates is to call FL_getCert first. This function will copy all data from the certificate area which may be shown to the public into the RAM, so that the certificate can be read later from the RAM. For example, if you need to access the certificate data which shows the name of the author of an Flash application (assuming that such data is present in the certificate), the usual procedure is:
HANDLE handle;
unsigned long size;
CFILE context;
CERT_FIELD field;
...
FL_getCert (&handle, &size, FALSE);
copen (&context, HeapDeref (handle), size);
cfindfield (&context, 0x300, &field);
copensub (&context, &field);
cfindfield (&context, 0x500, &field);
copensub (&context, &field);
cfindfield (&context, 0x510, &field);
copensub (&context, &field);
After this, context.Pos will point to the author name. Alternatively, you can pick the name character-by-character using cgetc. If any of calls to cfindfield functions fail (i.e. return FALSE), then such data are not present in the certificate area.

Uses: cread
Used by: AB_prodid, AB_prodname, ROM Call 0x504


cgetc

cgetc Function (ROM Call 0x12B)
cert.h

unsigned char cgetc (CFILE *context);

Gets a character from a context.

cgetc gets a character from the file associated with the file context pointed to by context, and moves the file pointer to the next character. This function is functionally equal to

*(char*) context->Pos++;

Used by: cgetflen, cgetnl, cgetns


cgetcertrevno

cgetcertrevno Function (ROM Call 0x2A0)
cert.h

short cgetcertrevno (long *dest);

Gets a certificate revision number.

cgetcertrevno fills the variable pointed to by dest with the certificate revision number. Returns TRUE if the operation was successful, otherwise it returns FALSE.

Used by: ABT_dialog


cgetflen

cgetflen Function (ROM Call 0x12D)
cert.h

unsigned long cgetflen (CFILE *context, unsigned short FieldIDWord);

Gets the length of a field.

cgetflen returns length of the field which has ID word (see cread) equal to FieldIDWord. This information is present in lower 4 bits of FieldIDWord if these bits are smaller or equal to 0xC. If not, necessary information needed to calculate the length are read from the context pointed to by context. cgetflen returns 0 if the end of the file is reached.

Uses: cgetc, cgetnl, cgetns
Used by: cread


cgetfnl

cgetfnl Function (ROM Call 0x12E)
cert.h

long cgetfnl (CERT_FIELD *field);

Gets a non-aligned long integer from a field.

cgetfnl gets a long integer (which does not necessarily need to be aligned on an even address) from the field described by the structure pointed to by field. The field need not to be exactly four bytes long; it can be of any length, and cgetfnl gets as many bytes as are available, up to the size of a long.

Used by: AB_prodid, ROM Call 0x58E


cgetnl

cgetnl Function (ROM Call 0x12F)
cert.h

long cgetnl (CFILE *context);

Gets a non-aligned long integer from a context.

cgetnl gets a long integer (which does not necessarily need to be aligned on an even address) from the file associated with the file context pointed to by context, and moves the file pointer forward by four characters. In fact, it calls cgetc four times, and combines four returned bytes into one doubleword.

Uses: cgetc
Used by: cgetflen


cgetns

cgetns Function (ROM Call 0x130)
cert.h

short cgetns (CFILE *context);

Gets a non-aligned short integer from a context.

cgetns gets a short integer (which does not necessarily need to be aligned on an even address) from the file associated with the file context pointed to by context, and moves the file pointer forward by two characters. In fact, it calls cgetc twice, and combines two returned bytes into one word.

Uses: cgetc
Used by: cgetflen, cread


cgetsn

cgetsn Function (ROM Call 0x2A1)
cert.h

void cgetsn (char *dest);

Gets the calculator serial number from the Flash ROM certificate.

cgetsn fills the buffer pointed to by dest with the calculator serial number picked from the Flash ROM certificate. It has the form "pphnnnnnnn", where "pp" is the platform number (01 for TI-92 Plus, 03 for TI-89, 08 for V200, 09 for TI-89T), "h" is hardware revision level, and "nnnnnnn" is an ID number which is unique to each calculator. All the above fields consist of hexadecimal digits. buffer must be at least 17 bytes long to accept the serial number.

Used by: LIO_Receive, AB_serno, LIO_SendIdList


copen

copen Function (ROM Call 0x132)
cert.h

void copen (CFILE *context, char *data, unsigned long size);

Opens a certificate file context.

copen opens a memory mapped file which starts at address data, and which is size bytes long. It also initializes file context (this is a file control structure of type CFILE) pointed to by context. It does not reserve any memory. In fact, copen does nothing more than

context->Start = context->Pos = data;
context->End = data + size;
context->EOF = FALSE;
Note: All functions from this header file are used in TIOS exclusively for accessing certificate files, which are stored in the protected area of Flash ROM, and which contain certificate data. However, these functions are not limited to such files. They may be used with any memory mapped file (i.e. a "headerless" file which does not have an entry in the VAT table), which does not need to be a file which really contains certificate data.

Used by: copensub, AB_prodid, AB_prodname, ROM Call 0x44B, OO_GetFlashAppSize, OO_GetFirstFlashAppSectorAddress


copensub

copensub Function (ROM Call 0x133)
cert.h

void copensub (CFILE *context, CERT_FIELD *subfield);

Opens a subcontext.

As the certificate file is usually consist of various field, this function is used for initializing the context pointed to by context to point to the actual content of the field described in the structure pointed to by subfield. This function is equal to

copen (context, subfield->Data, subfield->Len);
copen is used mainly to reset the file pointer to the start of a group of items. See cfindfield for more info.

Uses: copen
Used by: AB_prodid, AB_prodname, ROM Call 0x504


cputhdr

cputhdr Function (ROM Call 0x134)
cert.h

short cputhdr (CFILE *context, unsigned short FieldID, unsigned short len);

Puts a field header to a context.

cputhdr puts a field header to the file associated with the file context pointed to by context and moves the file pointer accordingly. The field header includes ID word (i.e. field ID number and four length bits), and up to four length bytes if necessary (see cread for more info about fields). Required data for forming the header are taken from parameters FieldID and len. cputhdr returns TRUE if the operation was successful, otherwise it returns FALSE.

Uses: cputnl, cputns
Used by: cwrite


cputnl

cputnl Function (ROM Call 0x135)
cert.h

void cputnl (CFILE *context, long l);

Puts a non-aligned long integer to a context.

cputnl puts a long integer l to the file associated with the file context pointed to by context, and moves the file pointer forward by four characters. The stored integer will not always be aligned on an even address.

Used by: cputhdr


cputns

cputns Function (ROM Call 0x136)
cert.h

void cputns (CFILE *context, short s);

Puts a non-aligned short integer to a context.

cputns puts a short integer s to the file associated with the file context pointed to by context, and moves the file pointer forward by two characters. The stored integer will not always be aligned on an even address.

Used by: cputhdr


cread

cread Function (ROM Call 0x137)
cert.h

short cread (CFILE *context, CERT_FIELD *dest);

Reads a field from a context.

Certificate files in TIOS (which packages up all the data required to perform authentification) are well-organized as files of variable-length records called "fields". So, the different components are split up into various fields, which can be accessed fairly easily. Each field begins with ID word. High 12 bits of ID are used as field ID number, and lower 4 bits are used to encode size of the field (as the length of the field can be a variable size). If these bits are smaller or equal to 0xC, this value is just the length of the field. If these bits are 0xD, 0xE or 0xF, then the following byte, word or doubleword contains the actual length of the field. Fields in the file are stored sequentially. They may contain various data, including other fields (i.e. "subfields"), which are usually opened with copensub.

cread reads a field from the file associated with the file context pointed to by context and collects necessary information (field ID number, length of the field, and the pointer to the actual content of the field) into the CERT_FIELD structure pointed to by dest. It also moves the field pointer to the next field, and sets the EOF indicator in the context if the end of the file is reached. cread returns TRUE if the operation was successful, otherwise it returns FALSE (this usually means end-of-file error).

Uses: ceof, cgetflen, cgetns
Used by: cfindfield, OO_GetEndOfAllFlashApps, ROM Call 0x44B, OO_GetFlashAppSize, OO_GetFirstFlashAppSectorAddress


ctell

ctell Function (ROM Call 0x138)
cert.h

unsigned long ctell (CFILE *context);

Returns the current position relative to the start of a context.

ctell returns the current position of the file pointer associated with the file context pointed to by context, measured from the start address of the file.


cwrite

cwrite Function (ROM Call 0x139)
cert.h

short cwrite (CFILE *context, CERT_FIELD *source);

Puts a field to a context.

cwrite writes a field described with CERT_FIELD structure pointed to by source to the file associated with the file context pointed to by context. cwrite is the reverse of cread. Returns TRUE if the operation was successful, otherwise it returns FALSE.

Uses: cputhdr


freeIdList

freeIdList Function (ROM Call 0x4D6)
AMS 2.00 or higher cert.h

void freeIdList (void);

Releases and deletes the RAM copy of the ID list, if it exists.

Uses: HeapFree
Used by: LIO_SendIdList

See also: LIO_SendIdList


CertificateMemory

CertificateMemory Variable (ROM Call 0x43E)
AMS 2.00 or higher cert.h

unsigned char *const CertificateMemory;

A pointer to the certificate memory.

This variable contains a pointer to the first byte of the certificate memory. Note that it always has a value of (unsigned char *const) (ROM_base + 0x10000).


CERT_FIELD

CERT_FIELD Type (Structure)
cert.h

typedef struct {
unsigned short Field; /* Field ID number (without the length) */
unsigned short HdrLen; /* Size of the header (ID word &
optional length bytes: 0, 1, 2 or 4) */
unsigned long Len; /* Total length of the field */
void *Data; /* Pointer to an actual data */
} CERT_FIELD;

A structure describing the records of certificate files.

CERT_FIELD is a structure which describes the variable-length records (usually called "fields") of certificate files. Each field has its ID number, and some ID numbers have predefined meanings in the TIOS (see cfindfield).


CFILE

CFILE Type (Structure)
cert.h, flashapp.h

typedef struct {
void *Start, *Pos, *End; /* Start, current and end position of the file pointer */
short EOFVal; /* Boolean value indicating end of file */
} CFILE;

A structure representing the context of a memory-mapped file.

CFILE is a structure which represents the context of a memory-mapped file (usually a certificate file).


compat.h

compat.h Header File
Header File Index

Various calc-dependent and AMS-dependent pseudo-constants

This header file contains a set of various pseudo-constants (i.e. macros defined to look and work like constants), dedicated to increase compatibility between the TI-89 and TI-92 Plus and between AMS versions. These "constants" have different values on the TI-89 and TI-92 Plus (or on AMS 1.xx and AMS 2.xx). Using these pseudo-constants, you can, for example, perform keyboard reading and graphic calculations in a more sophisticated way, check the AMS version and perform some AMS-dependent actions (although this is not recommended if not really necessary), etc.

The following table shows all defined pseudo-constants. A lot of them are known from DoorsOS, but they are defined here to work in both "nostub" and "Doors" mode.

Functions
PSEUDO_CONST_CALC
A macro to construct a pseudo-constant from calculator-based values.
PSEUDO_CONST_KBD
A macro to construct a pseudo-constant from keyboard-based values.
PSEUDO_CONST_SCREEN
A macro to construct a pseudo-constant from screen-based values.
Constants
AMS_1xx
TRUE on AMS 1.xx, FALSE on AMS 2.xx and AMS 3.xx.
AMS_2xx
TRUE on AMS 2.xx, FALSE on AMS 1.xx and AMS 3.xx.
AMS_3xx
TRUE on AMS 3.xx, FALSE on AMS 1.xx and AMS 2.xx.
CALCULATOR
Describes the calculator model.
HW_VERSION
Describes the hardware version.
KEY_DIAMOND
The number added to the key code if the Diamond key is pressed with it (see ngetchx).
KEY_DOWN
Key code for the down arrow key (see ngetchx).
KEY_DOWNLEFT
Key code for simultaneous pressing of the down and left arrow keys (see ngetchx).
KEY_LEFT
Key code for the left arrow key (see ngetchx).
KEY_OFF2
The key code for Diamond+ON (see ngetchx).
KEY_RIGHT
Key code for the right arrow key (see ngetchx).
KEY_SHIFT
The number added to the key code if the Shift key is pressed with it (see ngetchx).
KEY_UP
Key code for the up arrow key (see ngetchx).
KEY_UPRIGHT
Key code for simultaneous pressing on up and right arrow keys (see ngetchx).
LCD_HEIGHT
Height of the screen in pixels.
LCD_LINE_BYTES
Number of bytes in the visible part of a screen line.
LCD_WIDTH
Width of the screen in pixels.
ROM_base
Base address of the ROM (0x200000 on TI-89 or V200, 0x400000 on TI-92 Plus, 0x800000 on TI-89 Titanium).
RR_0
A pseudo-constant pair for the '0' key.
RR_1
A pseudo-constant pair for the '1' key.
RR_2
A pseudo-constant pair for the '2' key.
RR_3
A pseudo-constant pair for the '3' key.
RR_4
A pseudo-constant pair for the '4' key.
RR_5
A pseudo-constant pair for the '5' key.
RR_6
A pseudo-constant pair for the '6' key.
RR_7
A pseudo-constant pair for the '7' key.
RR_8
A pseudo-constant pair for the '8' key.
RR_9
A pseudo-constant pair for the '9' key.
RR_2ND
A pseudo-constant pair for the '2nd' key.
RR_A
A pseudo-constant pair for the 'A' key.
RR_ALPHA
A pseudo-constant pair for the Alpha key.
RR_APPS
A pseudo-constant pair for the 'APPS' key.
RR_B
A pseudo-constant pair for the 'B' key.
RR_BCKSPC
A pseudo-constant pair for the backspace key.
RR_C
A pseudo-constant pair for the 'C' key.
RR_CATALOG
A pseudo-constant pair for the 'CATALOG' key.
RR_CLEAR
A pseudo-constant pair for the 'CLEAR' key.
RR_COMMA
A pseudo-constant pair for the ',' key.
RR_COS
A pseudo-constant pair for the 'COS' key.
RR_D
A pseudo-constant pair for the 'D' key.
RR_DIAMOND
A pseudo-constant pair for the Diamond key.
RR_DIVIDE
A pseudo-constant pair for the '/' key.
RR_DOT
A pseudo-constant pair for the '.' key.
RR_DOWN
A pseudo-constant pair for the down arrow key.
RR_E
A pseudo-constant pair for the 'E' key.
RR_EE
A pseudo-constant pair for the 'EE' key.
RR_ENTER1
A pseudo-constant pair for the first 'ENTER' key.
RR_ENTER2
A pseudo-constant pair for the second 'ENTER' key.
RR_ENTER
A pseudo-constant pair for the 'ENTER' key.
RR_EQUALS
A pseudo-constant pair for the '=' key.
RR_ESC
A pseudo-constant pair for the 'ESC' key.
RR_F1
A pseudo-constant pair for the 'F1' key.
RR_F2
A pseudo-constant pair for the 'F2' key.
RR_F3
A pseudo-constant pair for the 'F3' key.
RR_F4
A pseudo-constant pair for the 'F4' key.
RR_F5
A pseudo-constant pair for the 'F5' key.
RR_F6
A pseudo-constant pair for the 'F6' key.
RR_F7
A pseudo-constant pair for the 'F7' key.
RR_F8
A pseudo-constant pair for the 'F8' key.
RR_F
A pseudo-constant pair for the 'F' key.
RR_G
A pseudo-constant pair for the 'G' key.
RR_H
A pseudo-constant pair for the 'H' key.
RR_HAND
A pseudo-constant pair for the Hand key.
RR_HOME
A pseudo-constant pair for the 'HOME' key.
RR_I
A pseudo-constant pair for the 'I' key.
RR_J
A pseudo-constant pair for the 'J' key.
RR_K
A pseudo-constant pair for the 'K' key.
RR_L
A pseudo-constant pair for the 'L' key.
RR_LEFT
A pseudo-constant pair for the left arrow key.
RR_LN
A pseudo-constant pair for the 'LN' key.
RR_M
A pseudo-constant pair for the 'M' key.
RR_MINUS
A pseudo-constant pair for the '-' key.
RR_MODE
A pseudo-constant pair for the 'MODE' key.
RR_MULTIPLY
A pseudo-constant pair for the '*' key.
RR_N
A pseudo-constant pair for the 'N' key.
RR_NEGATE
A pseudo-constant pair for the negation key.
RR_NO_KEY
A constant which means that a specific key does not exist.
RR_O
A pseudo-constant pair for the 'O' key.
RR_P
A pseudo-constant pair for the 'P' key.
RR_PAREN_CLOSE
A pseudo-constant pair for the ')' key.
RR_PAREN_OPEN
A pseudo-constant pair for the '(' key.
RR_PLUS
A pseudo-constant pair for the '+' key.
RR_POWER
A pseudo-constant pair for the '^' key.
RR_Q
A pseudo-constant pair for the 'Q' key.
RR_R
A pseudo-constant pair for the 'R' key.
RR_RIGHT
A pseudo-constant pair for the right arrow key.
RR_S
A pseudo-constant pair for the 'S' key.
RR_SHIFT
A pseudo-constant pair for the Shift key.
RR_SIN
A pseudo-constant pair for the 'SIN' key.
RR_SPACE
A pseudo-constant pair for the space key.
RR_STORE
A pseudo-constant pair for the Store key.
RR_T
A pseudo-constant pair for the 'T' key.
RR_TAN
A pseudo-constant pair for the 'TAN' key.
RR_THETA
A pseudo-constant pair for the 'q' key.
RR_U
A pseudo-constant pair for the 'U' key.
RR_UP
A pseudo-constant pair for the up arrow key.
RR_V
A pseudo-constant pair for the 'V' key.
RR_W
A pseudo-constant pair for the 'W' key.
RR_WITH
A pseudo-constant pair for the '|' key.
RR_X
A pseudo-constant pair for the 'X' key.
RR_Y
A pseudo-constant pair for the 'Y' key.
RR_Z
A pseudo-constant pair for the 'Z' key.
TI89_CLASSIC
TRUE on a classic TI-89 (i.e. a TI-89 which is not a TI-89 Titanium), FALSE otherwise.
TI89_TITANIUM
TRUE on a TI-89 Titanium, FALSE otherwise.
TI89
TRUE on a TI-89, FALSE otherwise.
TI92PLUS
TRUE on TI-92 Plus, FALSE otherwise.
TIOS_entries
Number of entries in the TIOS jump table.
V200
TRUE on V200, FALSE otherwise.

Note: All of these pseudo-constants are in fact macros. Although they expand to relatively small code (in "Doors" mode they are mainly implemented as RAM calls and managed by kernel), it is recommended to store a pseudo-constant in an ordinary variable if you use it a lot of times in the program (especially in "nostub" mode), and to use this variable instead. For example, if you use the KEY_LEFT pseudo-constant too often, it is recommended to define

int key_left = KEY_LEFT;
somewhere at the beginning of the program, and to use
if (key == key_left) ...
instead of
if (key == KEY_LEFT) ...
Such indirection will save memory, but note that this is necessary only if you use the same pseudo-constant a lot in the program (say, more than 5 times).

There is yet another note. Pseudo-Constants work as constants in nearly all cases, but they are not really constants, so they cannot be used in case labels inside switch statements, i.e. the following is not legal:
switch (ngetchx ())
  {
    case KEY_LEFT:
      ...
    case KEY_RIGHT:
      ...
    ...
  }
Instead, use if...else constructions:
key = ngetchx ();
if (key == KEY_LEFT)
  {
    ...
  }
else if (key == KEY_RIGHT)
  {
    ...
  }
...
The pseudo-constants really become constants if you compile only for one calculator model. For example, if you define USE_TI89 and nothing else, CALCULATOR will have the value 0, and all other pseudo-constants will be optimized into single values. Or, if you define MIN_AMS to be 200, AMS_1xx will always be false.


PSEUDO_CONST_CALC

PSEUDO_CONST_CALC Function (Macro)
compat.h

#define PSEUDO_CONST_CALC(calc92,calc89,calc92plus,calcv200) (CALCULATOR ? ((CALCULATOR == 1) ? (calc92plus) : (calcv200)) : (calc89))

A macro to construct a pseudo-constant from calculator-based values.

PSEUDO_CONST_CALC is a macro used by PSEUDO_CONST_SCREEN and PSEUDO_CONST_KBD. Most of the time, you should not use it directly, but use these two macros instead.

It takes several values for the different calculators that GCC4TI can currently compile code for, and returns one of them based on the calculator that the program currently uses. The values must be plain positive integers up to 65535 (0xFFFF) in decimal or hexadecimal notation, otherwise this macro may fail in some cases.

Uses of this macro may be optimized by defining OPTIMIZE_CALC_CONSTS.

See also: PSEUDO_CONST_SCREEN, PSEUDO_CONST_KBD


PSEUDO_CONST_KBD

PSEUDO_CONST_KBD Function (Macro)
compat.h

#define PSEUDO_CONST_KBD(kbd89,kbd92) PSEUDO_CONST_CALC(kbd92, kbd89, kbd92, kbd92)

A macro to construct a pseudo-constant from keyboard-based values.

PSEUDO_CONST_KBD takes several values for different keyboard layouts, and returns one of them based on the keyboard that the program currently uses. The values must be plain positive integers up to 65535 (0xFFFF) in decimal or hexadecimal notation, otherwise this macro may fail in some cases.

Currently, there are two different keyboard layouts: The TI-89 keyboard, which looks like a normal calculator keyboard with extra keys, and the TI-92/TI-92+/V200 keyboard, which has a QWERTY layout. The two parameters specify the values to use whichever keyboard layout is encountered, which means that the number of parameters may increase as new hardware becomes available. If you want to use this macro in your application, you must decide for yourself whether this feature is desirable: On the one hand, it can prevent your code from being compiled in future releases of GCC4TI; on the other hand, you can easily port your programs to new hardware just by fixing all of the compile-time errors.

See also: PSEUDO_CONST_CALC, PSEUDO_CONST_SCREEN


PSEUDO_CONST_SCREEN

PSEUDO_CONST_SCREEN Function (Macro)
compat.h

#define PSEUDO_CONST_SCREEN(screen89,screen92) PSEUDO_CONST_CALC(screen92, screen89, screen92, screen92)

A macro to construct a pseudo-constant from screen-based values.

PSEUDO_CONST_SCREEN takes several values for different types of screens, and returns one of them based on the screen that the program currently uses. The values must be plain positive integers up to 65535 (0xFFFF) in decimal or hexadecimal notation, otherwise this macro may fail in some cases.

Currently, there are two types of screens: The TI-89 LCD with a size of 160x100 pixels, and the TI-92/TI-92+/V200 LCD with a size of 240x128 pixels. The two parameters specify the values to use whichever screen type is encountered, which means that the number of parameters may increase as new hardware becomes available. If you want to use this macro in your application, you must decide for yourself whether this feature is desirable: On the one hand, it can prevent your code from being compiled in future releases of GCC4TI; on the other hand, you can easily port your programs to new hardware just by fixing all of the compile-time errors.

See also: PSEUDO_CONST_CALC, PSEUDO_CONST_KBD


AMS_1xx

AMS_1xx Constant (Pseudo-Constant)
compat.h

TRUE on AMS 1.xx, FALSE on AMS 2.xx and AMS 3.xx.

This pseudo-constant is in fact defined globally, in default.h.


AMS_2xx

AMS_2xx Constant (Pseudo-Constant)
compat.h

TRUE on AMS 2.xx, FALSE on AMS 1.xx and AMS 3.xx.

This pseudo-constant is in fact defined globally, in default.h.


AMS_3xx

AMS_3xx Constant (Pseudo-Constant)
compat.h

TRUE on AMS 3.xx, FALSE on AMS 1.xx and AMS 2.xx.

This pseudo-constant is in fact defined globally, in default.h.


CALCULATOR

CALCULATOR Constant (Pseudo-Constant)
compat.h

Describes the calculator model.

This pseudo-constant is 0 on the TI-89, 1 on the TI-92 Plus, and 3 on the V200.


HW_VERSION

HW_VERSION Constant (Pseudo-Constant)
compat.h

Describes the hardware version.

This pseudo-constant is 1 on a HW1 calculator and 2 on a HW2 calculator. It reads the value of the gateArray field in the HARDWARE_PARM_BLOCK structure returned by FL_getHardwareParmBlock.


KEY_DIAMOND

KEY_DIAMOND Constant (Pseudo-Constant)
compat.h

#define KEY_DIAMOND (PSEUDO_CONST_KBD (16384, 8192))

The number added to the key code if the Diamond key is pressed with it (see ngetchx).


KEY_DOWN

KEY_DOWN Constant (Pseudo-Constant)
compat.h

#define KEY_DOWN (PSEUDO_CONST_KBD (340, 344))

Key code for the down arrow key (see ngetchx).


KEY_DOWNLEFT

KEY_DOWNLEFT Constant (Pseudo-Constant)
compat.h

#define KEY_DOWNLEFT (PSEUDO_CONST_KBD (342, 345))

Key code for simultaneous pressing of the down and left arrow keys (see ngetchx).


KEY_LEFT

KEY_LEFT Constant (Pseudo-Constant)
compat.h

#define KEY_LEFT (PSEUDO_CONST_KBD (338, 337))

Key code for the left arrow key (see ngetchx).


KEY_OFF2

KEY_OFF2 Constant (Pseudo-Constant)
compat.h

#define KEY_OFF2 (PSEUDO_CONST_KBD (16651, 8459))

The key code for Diamond+ON (see ngetchx).


KEY_RIGHT

KEY_RIGHT Constant (Pseudo-Constant)
compat.h

#define KEY_RIGHT (PSEUDO_CONST_KBD (344, 340))

Key code for the right arrow key (see ngetchx).


KEY_SHIFT

KEY_SHIFT Constant (Pseudo-Constant)
compat.h

#define KEY_SHIFT (PSEUDO_CONST_KBD (8192, 16384))

The number added to the key code if the Shift key is pressed with it (see ngetchx).


KEY_UP

KEY_UP Constant (Pseudo-Constant)
compat.h

#define KEY_UP (PSEUDO_CONST_KBD (337, 338))

Key code for the up arrow key (see ngetchx).


KEY_UPRIGHT

KEY_UPRIGHT Constant (Pseudo-Constant)
compat.h

#define KEY_UPRIGHT (PSEUDO_CONST_KBD (345, 342))

Key code for simultaneous pressing on up and right arrow keys (see ngetchx).


LCD_HEIGHT

LCD_HEIGHT Constant (Pseudo-Constant)
compat.h

#define LCD_HEIGHT (PSEUDO_CONST_SCREEN (100, 128))

Height of the screen in pixels.

This value is 100 on the TI-89, and 128 on the TI-92 Plus and V200.


LCD_LINE_BYTES

LCD_LINE_BYTES Constant (Pseudo-Constant)
compat.h

#define LCD_LINE_BYTES (PSEUDO_CONST_SCREEN (20, 30))

Number of bytes in the visible part of a screen line.

This value is 20 on the TI-89, and 30 on the TI-92 Plus and V200.


LCD_WIDTH

LCD_WIDTH Constant (Pseudo-Constant)
compat.h

#define LCD_WIDTH (PSEUDO_CONST_SCREEN (160, 240))

Width of the screen in pixels.

This value is 160 on the TI-89, and 240 on the TI-92 Plus and V200.


ROM_base

ROM_base Constant (Pseudo-Constant)
compat.h

Base address of the ROM (0x200000 on TI-89 or V200, 0x400000 on TI-92 Plus, 0x800000 on TI-89 Titanium).


RR_0

RR_0 Constant (Pseudo-Constant Pair)
compat.h

#define RR_0 (PSEUDO_CONST_KBD (4, 9)), (PSEUDO_CONST_KBD (0, 5))

A pseudo-constant pair for the '0' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_1

RR_1 Constant (Pseudo-Constant Pair)
compat.h

#define RR_1 (PSEUDO_CONST_KBD (4, 1)), (PSEUDO_CONST_KBD (1, 5))

A pseudo-constant pair for the '1' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_2

RR_2 Constant (Pseudo-Constant Pair)
compat.h

#define RR_2 (PSEUDO_CONST_KBD (3, 1)), (PSEUDO_CONST_KBD (1, 6))

A pseudo-constant pair for the '2' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_3

RR_3 Constant (Pseudo-Constant Pair)
compat.h

#define RR_3 (PSEUDO_CONST_KBD (2, 1)), (PSEUDO_CONST_KBD (1, 7))

A pseudo-constant pair for the '3' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_4

RR_4 Constant (Pseudo-Constant Pair)
compat.h

#define RR_4 (PSEUDO_CONST_KBD (4, 2)), (PSEUDO_CONST_KBD (2, 5))

A pseudo-constant pair for the '4' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_5

RR_5 Constant (Pseudo-Constant Pair)
compat.h

#define RR_5 (PSEUDO_CONST_KBD (3, 2)), (PSEUDO_CONST_KBD (2, 6))

A pseudo-constant pair for the '5' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_6

RR_6 Constant (Pseudo-Constant Pair)
compat.h

#define RR_6 2, (PSEUDO_CONST_KBD (2, 7))

A pseudo-constant pair for the '6' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_7

RR_7 Constant (Pseudo-Constant Pair)
compat.h

#define RR_7 (PSEUDO_CONST_KBD (4, 3)), (PSEUDO_CONST_KBD (3, 5))

A pseudo-constant pair for the '7' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_8

RR_8 Constant (Pseudo-Constant Pair)
compat.h

#define RR_8 3, (PSEUDO_CONST_KBD (3, 6))

A pseudo-constant pair for the '8' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_9

RR_9 Constant (Pseudo-Constant Pair)
compat.h

#define RR_9 (PSEUDO_CONST_KBD (2, 3)), (PSEUDO_CONST_KBD (3, 7))

A pseudo-constant pair for the '9' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_2ND

RR_2ND Constant (Pseudo-Constant Pair)
compat.h

#define RR_2ND 0, (PSEUDO_CONST_KBD (4, 0))

A pseudo-constant pair for the '2nd' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_A

RR_A Constant (Pseudo-Constant Pair)
compat.h

#define RR_A (PSEUDO_CONST_KBD (RR_NO_KEY, 9)), (PSEUDO_CONST_KBD (RR_NO_KEY, 2))

A pseudo-constant pair for the 'A' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_ALPHA

RR_ALPHA Constant (Pseudo-Constant Pair)
compat.h

#define RR_ALPHA (PSEUDO_CONST_KBD (0, RR_NO_KEY)), (PSEUDO_CONST_KBD (7, RR_NO_KEY))

A pseudo-constant pair for the Alpha key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_APPS

RR_APPS Constant (Pseudo-Constant Pair)
compat.h

#define RR_APPS (PSEUDO_CONST_KBD (5, 7)), (PSEUDO_CONST_KBD (0, 6))

A pseudo-constant pair for the 'APPS' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_B

RR_B Constant (Pseudo-Constant Pair)
compat.h

#define RR_B (PSEUDO_CONST_KBD (RR_NO_KEY, 5)), (PSEUDO_CONST_KBD (RR_NO_KEY, 1))

A pseudo-constant pair for the 'B' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_BCKSPC

RR_BCKSPC Constant (Pseudo-Constant Pair)
compat.h

#define RR_BCKSPC (PSEUDO_CONST_KBD (2, 8)), (PSEUDO_CONST_KBD (6, 0))

A pseudo-constant pair for the backspace key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_C

RR_C Constant (Pseudo-Constant Pair)
compat.h

#define RR_C (PSEUDO_CONST_KBD (RR_NO_KEY, 3)), (PSEUDO_CONST_KBD (RR_NO_KEY, 1))

A pseudo-constant pair for the 'C' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_CATALOG

RR_CATALOG Constant (Pseudo-Constant Pair)
compat.h

#define RR_CATALOG (PSEUDO_CONST_KBD (3, RR_NO_KEY)), (PSEUDO_CONST_KBD (6, RR_NO_KEY))

A pseudo-constant pair for the 'CATALOG' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_CLEAR

RR_CLEAR Constant (Pseudo-Constant Pair)
compat.h

#define RR_CLEAR (PSEUDO_CONST_KBD (1, 7)), (PSEUDO_CONST_KBD (6, 5))

A pseudo-constant pair for the 'CLEAR' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_COMMA

RR_COMMA Constant (Pseudo-Constant Pair)
compat.h

#define RR_COMMA (PSEUDO_CONST_KBD (2, 4)), (PSEUDO_CONST_KBD (4, 7))

A pseudo-constant pair for the ',' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_COS

RR_COS Constant (Pseudo-Constant Pair)
compat.h

#define RR_COS (PSEUDO_CONST_KBD (RR_NO_KEY, 5)), (PSEUDO_CONST_KBD (RR_NO_KEY, 6))

A pseudo-constant pair for the 'COS' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_D

RR_D Constant (Pseudo-Constant Pair)
compat.h

#define RR_D (PSEUDO_CONST_KBD (RR_NO_KEY, 2)), (PSEUDO_CONST_KBD (RR_NO_KEY, 2))

A pseudo-constant pair for the 'D' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_DIAMOND

RR_DIAMOND Constant (Pseudo-Constant Pair)
compat.h

#define RR_DIAMOND 0, (PSEUDO_CONST_KBD (6, 1))

A pseudo-constant pair for the Diamond key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_DIVIDE

RR_DIVIDE Constant (Pseudo-Constant Pair)
compat.h

#define RR_DIVIDE (PSEUDO_CONST_KBD (1, 5)), (PSEUDO_CONST_KBD (4, 0))

A pseudo-constant pair for the '/' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_DOT

RR_DOT Constant (Pseudo-Constant Pair)
compat.h

#define RR_DOT (PSEUDO_CONST_KBD (3, 9)), (PSEUDO_CONST_KBD (0, 6))

A pseudo-constant pair for the '.' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_DOWN

RR_DOWN Constant (Pseudo-Constant Pair)
compat.h

#define RR_DOWN 0, (PSEUDO_CONST_KBD (2, 7))

A pseudo-constant pair for the down arrow key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_E

RR_E Constant (Pseudo-Constant Pair)
compat.h

#define RR_E (PSEUDO_CONST_KBD (RR_NO_KEY, 2)), (PSEUDO_CONST_KBD (RR_NO_KEY, 3))

A pseudo-constant pair for the 'E' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_EE

RR_EE Constant (Pseudo-Constant Pair)
compat.h

#define RR_EE (PSEUDO_CONST_KBD (5, RR_NO_KEY)), (PSEUDO_CONST_KBD (2, RR_NO_KEY))

A pseudo-constant pair for the 'EE' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_ENTER1

RR_ENTER1 Constant (Pseudo-Constant Pair)
compat.h

#define RR_ENTER1 (PSEUDO_CONST_KBD (1, 9)), (PSEUDO_CONST_KBD (0, 1))

A pseudo-constant pair for the first 'ENTER' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_ENTER2

RR_ENTER2 Constant (Pseudo-Constant Pair)
compat.h

#define RR_ENTER2 (PSEUDO_CONST_KBD (1, 6)), (PSEUDO_CONST_KBD (0, 6))

A pseudo-constant pair for the second 'ENTER' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_ENTER

RR_ENTER Constant (Pseudo-Constant Pair)
compat.h

#define RR_ENTER RR_ENTER1

A pseudo-constant pair for the 'ENTER' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_EQUALS

RR_EQUALS Constant (Pseudo-Constant Pair)
compat.h

#define RR_EQUALS (PSEUDO_CONST_KBD (5, 7)), (PSEUDO_CONST_KBD (4, 0))

A pseudo-constant pair for the '=' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_ESC

RR_ESC Constant (Pseudo-Constant Pair)
compat.h

#define RR_ESC (PSEUDO_CONST_KBD (6, 8)), (PSEUDO_CONST_KBD (0, 6))

A pseudo-constant pair for the 'ESC' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_F1

RR_F1 Constant (Pseudo-Constant Pair)
compat.h

#define RR_F1 (PSEUDO_CONST_KBD (5, 6)), (PSEUDO_CONST_KBD (7, 4))

A pseudo-constant pair for the 'F1' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_F2

RR_F2 Constant (Pseudo-Constant Pair)
compat.h

#define RR_F2 4, (PSEUDO_CONST_KBD (7, 4))

A pseudo-constant pair for the 'F2' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_F3

RR_F3 Constant (Pseudo-Constant Pair)
compat.h

#define RR_F3 (PSEUDO_CONST_KBD (3, 2)), (PSEUDO_CONST_KBD (7, 4))

A pseudo-constant pair for the 'F3' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_F4

RR_F4 Constant (Pseudo-Constant Pair)
compat.h

#define RR_F4 (PSEUDO_CONST_KBD (2, 9)), (PSEUDO_CONST_KBD (7, 4))

A pseudo-constant pair for the 'F4' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_F5

RR_F5 Constant (Pseudo-Constant Pair)
compat.h

#define RR_F5 (PSEUDO_CONST_KBD (1, 7)), (PSEUDO_CONST_KBD (7, 4))

A pseudo-constant pair for the 'F5' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_F6

RR_F6 Constant (Pseudo-Constant Pair)
compat.h

#define RR_F6 (PSEUDO_CONST_KBD (RR_NO_KEY, 5)), (PSEUDO_CONST_KBD (RR_NO_KEY, 4))

A pseudo-constant pair for the 'F6' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_F7

RR_F7 Constant (Pseudo-Constant Pair)
compat.h

#define RR_F7 (PSEUDO_CONST_KBD (RR_NO_KEY, 3)), (PSEUDO_CONST_KBD (RR_NO_KEY, 4))

A pseudo-constant pair for the 'F7' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_F8

RR_F8 Constant (Pseudo-Constant Pair)
compat.h

#define RR_F8 (PSEUDO_CONST_KBD (RR_NO_KEY, 1)), (PSEUDO_CONST_KBD (RR_NO_KEY, 4))

A pseudo-constant pair for the 'F8' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_F

RR_F Constant (Pseudo-Constant Pair)
compat.h

#define RR_F (PSEUDO_CONST_KBD (RR_NO_KEY, 3)), (PSEUDO_CONST_KBD (RR_NO_KEY, 2))

A pseudo-constant pair for the 'F' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_G

RR_G Constant (Pseudo-Constant Pair)
compat.h

#define RR_G (PSEUDO_CONST_KBD (RR_NO_KEY, 4)), (PSEUDO_CONST_KBD (RR_NO_KEY, 2))

A pseudo-constant pair for the 'G' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_H

RR_H Constant (Pseudo-Constant Pair)
compat.h

#define RR_H (PSEUDO_CONST_KBD (RR_NO_KEY, 5)), (PSEUDO_CONST_KBD (RR_NO_KEY, 2))

A pseudo-constant pair for the 'H' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_HAND

RR_HAND Constant (Pseudo-Constant Pair)
compat.h

#define RR_HAND (PSEUDO_CONST_KBD (RR_NO_KEY, 0)), (PSEUDO_CONST_KBD (RR_NO_KEY, 3))

A pseudo-constant pair for the Hand key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_HOME

RR_HOME Constant (Pseudo-Constant Pair)
compat.h

#define RR_HOME (PSEUDO_CONST_KBD (5, RR_NO_KEY)), (PSEUDO_CONST_KBD (6, RR_NO_KEY))

A pseudo-constant pair for the 'HOME' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_I

RR_I Constant (Pseudo-Constant Pair)
compat.h

#define RR_I (PSEUDO_CONST_KBD (RR_NO_KEY, 7)), (PSEUDO_CONST_KBD (RR_NO_KEY, 3))

A pseudo-constant pair for the 'I' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_J

RR_J Constant (Pseudo-Constant Pair)
compat.h

#define RR_J (PSEUDO_CONST_KBD (RR_NO_KEY, 6)), (PSEUDO_CONST_KBD (RR_NO_KEY, 2))

A pseudo-constant pair for the 'J' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_K

RR_K Constant (Pseudo-Constant Pair)
compat.h

#define RR_K (PSEUDO_CONST_KBD (RR_NO_KEY, 7)), (PSEUDO_CONST_KBD (RR_NO_KEY, 2))

A pseudo-constant pair for the 'K' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_L

RR_L Constant (Pseudo-Constant Pair)
compat.h

#define RR_L (PSEUDO_CONST_KBD (RR_NO_KEY, 8)), (PSEUDO_CONST_KBD (RR_NO_KEY, 2))

A pseudo-constant pair for the 'L' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_LEFT

RR_LEFT Constant (Pseudo-Constant Pair)
compat.h

#define RR_LEFT 0, (PSEUDO_CONST_KBD (1, 4))

A pseudo-constant pair for the left arrow key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_LN

RR_LN Constant (Pseudo-Constant Pair)
compat.h

#define RR_LN (PSEUDO_CONST_KBD (RR_NO_KEY, 6)), (PSEUDO_CONST_KBD (RR_NO_KEY, 5))

A pseudo-constant pair for the 'LN' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_M

RR_M Constant (Pseudo-Constant Pair)
compat.h

#define RR_M (PSEUDO_CONST_KBD (RR_NO_KEY, 7)), (PSEUDO_CONST_KBD (RR_NO_KEY, 1))

A pseudo-constant pair for the 'M' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_MINUS

RR_MINUS Constant (Pseudo-Constant Pair)
compat.h

#define RR_MINUS (PSEUDO_CONST_KBD (1, 9)), (PSEUDO_CONST_KBD (2, 0))

A pseudo-constant pair for the '-' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_MODE

RR_MODE Constant (Pseudo-Constant Pair)
compat.h

#define RR_MODE (PSEUDO_CONST_KBD (4, 8)), (PSEUDO_CONST_KBD (6, 5))

A pseudo-constant pair for the 'MODE' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_MULTIPLY

RR_MULTIPLY Constant (Pseudo-Constant Pair)
compat.h

#define RR_MULTIPLY (PSEUDO_CONST_KBD (1, 7)), (PSEUDO_CONST_KBD (3, 7))

A pseudo-constant pair for the '*' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_N

RR_N Constant (Pseudo-Constant Pair)
compat.h

#define RR_N (PSEUDO_CONST_KBD (RR_NO_KEY, 6)), (PSEUDO_CONST_KBD (RR_NO_KEY, 1))

A pseudo-constant pair for the 'N' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_NEGATE

RR_NEGATE Constant (Pseudo-Constant Pair)
compat.h

#define RR_NEGATE (PSEUDO_CONST_KBD (2, 9)), (PSEUDO_CONST_KBD (0, 7))

A pseudo-constant pair for the negation key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_NO_KEY

RR_NO_KEY Constant
compat.h

#define RR_NO_KEY 0xF

A constant which means that a specific key does not exist.

This constant is used whenever a specific key only exists on one calculator.


RR_O

RR_O Constant (Pseudo-Constant Pair)
compat.h

#define RR_O (PSEUDO_CONST_KBD (RR_NO_KEY, 8)), (PSEUDO_CONST_KBD (RR_NO_KEY, 3))

A pseudo-constant pair for the 'O' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_P

RR_P Constant (Pseudo-Constant Pair)
compat.h

#define RR_P (PSEUDO_CONST_KBD (RR_NO_KEY, 6)), (PSEUDO_CONST_KBD (RR_NO_KEY, 7))

A pseudo-constant pair for the 'P' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_PAREN_CLOSE

RR_PAREN_CLOSE Constant (Pseudo-Constant Pair)
compat.h

#define RR_PAREN_CLOSE (PSEUDO_CONST_KBD (3, 4)), (PSEUDO_CONST_KBD (4, 6))

A pseudo-constant pair for the ')' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_PAREN_OPEN

RR_PAREN_OPEN Constant (Pseudo-Constant Pair)
compat.h

#define RR_PAREN_OPEN 4, (PSEUDO_CONST_KBD (4, 5))

A pseudo-constant pair for the '(' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_PLUS

RR_PLUS Constant (Pseudo-Constant Pair)
compat.h

#define RR_PLUS (PSEUDO_CONST_KBD (1, 8)), (PSEUDO_CONST_KBD (1, 4))

A pseudo-constant pair for the '+' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_POWER

RR_POWER Constant (Pseudo-Constant Pair)
compat.h

#define RR_POWER (PSEUDO_CONST_KBD (1, 6)), (PSEUDO_CONST_KBD (5, 0))

A pseudo-constant pair for the '^' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_Q

RR_Q Constant (Pseudo-Constant Pair)
compat.h

#define RR_Q (PSEUDO_CONST_KBD (RR_NO_KEY, 9)), (PSEUDO_CONST_KBD (RR_NO_KEY, 3))

A pseudo-constant pair for the 'Q' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_R

RR_R Constant (Pseudo-Constant Pair)
compat.h

#define RR_R (PSEUDO_CONST_KBD (RR_NO_KEY, 3)), (PSEUDO_CONST_KBD (RR_NO_KEY, 3))

A pseudo-constant pair for the 'R' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_RIGHT

RR_RIGHT Constant (Pseudo-Constant Pair)
compat.h

#define RR_RIGHT 0, (PSEUDO_CONST_KBD (3, 6))

A pseudo-constant pair for the right arrow key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_S

RR_S Constant (Pseudo-Constant Pair)
compat.h

#define RR_S (PSEUDO_CONST_KBD (RR_NO_KEY, 1)), (PSEUDO_CONST_KBD (RR_NO_KEY, 2))

A pseudo-constant pair for the 'S' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_SHIFT

RR_SHIFT Constant (Pseudo-Constant Pair)
compat.h

#define RR_SHIFT 0, (PSEUDO_CONST_KBD (5, 2))

A pseudo-constant pair for the Shift key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_SIN

RR_SIN Constant (Pseudo-Constant Pair)
compat.h

#define RR_SIN (PSEUDO_CONST_KBD (RR_NO_KEY, 5)), (PSEUDO_CONST_KBD (RR_NO_KEY, 5))

A pseudo-constant pair for the 'SIN' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_SPACE

RR_SPACE Constant (Pseudo-Constant Pair)
compat.h

#define RR_SPACE (PSEUDO_CONST_KBD (RR_NO_KEY, 4)), (PSEUDO_CONST_KBD (RR_NO_KEY, 0))

A pseudo-constant pair for the space key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_STORE

RR_STORE Constant (Pseudo-Constant Pair)
compat.h

#define RR_STORE (PSEUDO_CONST_KBD (5, 3)), (PSEUDO_CONST_KBD (1, 0))

A pseudo-constant pair for the Store key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_T

RR_T Constant (Pseudo-Constant Pair)
compat.h

#define RR_T (PSEUDO_CONST_KBD (2, 4)), (PSEUDO_CONST_KBD (5, 3))

A pseudo-constant pair for the 'T' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_TAN

RR_TAN Constant (Pseudo-Constant Pair)
compat.h

#define RR_TAN (PSEUDO_CONST_KBD (RR_NO_KEY, 5)), (PSEUDO_CONST_KBD (RR_NO_KEY, 7))

A pseudo-constant pair for the 'TAN' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_THETA

RR_THETA Constant (Pseudo-Constant Pair)
compat.h

#define RR_THETA (PSEUDO_CONST_KBD (RR_NO_KEY, 8)), (PSEUDO_CONST_KBD (RR_NO_KEY, 1))

A pseudo-constant pair for the 'q' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_U

RR_U Constant (Pseudo-Constant Pair)
compat.h

#define RR_U (PSEUDO_CONST_KBD (RR_NO_KEY, 6)), (PSEUDO_CONST_KBD (RR_NO_KEY, 3))

A pseudo-constant pair for the 'U' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_UP

RR_UP Constant (Pseudo-Constant Pair)
compat.h

#define RR_UP 0, (PSEUDO_CONST_KBD (0, 5))

A pseudo-constant pair for the up arrow key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_V

RR_V Constant (Pseudo-Constant Pair)
compat.h

#define RR_V (PSEUDO_CONST_KBD (RR_NO_KEY, 4)), (PSEUDO_CONST_KBD (RR_NO_KEY, 1))

A pseudo-constant pair for the 'V' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_W

RR_W Constant (Pseudo-Constant Pair)
compat.h

#define RR_W (PSEUDO_CONST_KBD (RR_NO_KEY, 1)), (PSEUDO_CONST_KBD (RR_NO_KEY, 3))

A pseudo-constant pair for the 'W' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_WITH

RR_WITH Constant (Pseudo-Constant Pair)
compat.h

#define RR_WITH (PSEUDO_CONST_KBD (5, RR_NO_KEY)), (PSEUDO_CONST_KBD (3, RR_NO_KEY))

A pseudo-constant pair for the '|' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_X

RR_X Constant (Pseudo-Constant Pair)
compat.h

#define RR_X (PSEUDO_CONST_KBD (5, 2)), (PSEUDO_CONST_KBD (5, 1))

A pseudo-constant pair for the 'X' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_Y

RR_Y Constant (Pseudo-Constant Pair)
compat.h

#define RR_Y (PSEUDO_CONST_KBD (4, 5)), (PSEUDO_CONST_KBD (5, 3))

A pseudo-constant pair for the 'Y' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


RR_Z

RR_Z Constant (Pseudo-Constant Pair)
compat.h

#define RR_Z (PSEUDO_CONST_KBD (3, 1)), (PSEUDO_CONST_KBD (5, 1))

A pseudo-constant pair for the 'Z' key.

This pseudo-constant pair defines the location of a specific key in the keyboard matrix used in _keytest.


TI89_CLASSIC

TI89_CLASSIC Constant (Pseudo-Constant)
compat.h

#define TI89_CLASSIC (TI89 && HW_VERSION<3)

TRUE on a classic TI-89 (i.e. a TI-89 which is not a TI-89 Titanium), FALSE otherwise.

See also: TI89


TI89_TITANIUM

TI89_TITANIUM Constant (Pseudo-Constant)
compat.h

#define TI89_TITANIUM (TI89 && HW_VERSION>=3)

TRUE on a TI-89 Titanium, FALSE otherwise.

See also: TI89


TI89

TI89 Constant (Pseudo-Constant)
compat.h

#define TI89 (CALCULATOR == 0)

TRUE on a TI-89, FALSE otherwise.

See also: TI89_CLASSIC, TI89_TITANIUM


TI92PLUS

TI92PLUS Constant (Pseudo-Constant)
compat.h

#define TI92PLUS (CALCULATOR == 1)

TRUE on TI-92 Plus, FALSE otherwise.


TIOS_entries

TIOS_entries Constant (Pseudo-Constant)
compat.h

Number of entries in the TIOS jump table.

This pseudo-constant may also be used to determine the AMS version:

684 | 0x2AC | AMS 1.00 (TI-92 Plus only)
972 | 0x3CC | AMS 1.01 (or 1.00 for TI-89), AMS 1.05
1288 | 0x508 | AMS 2.01
1463 | 0x5B7 | AMS 2.02, AMS 2.03
1506 | 0x5E2 | AMS 2.04
1519 | 0x5EF | AMS 2.05
1543 | 0x607 | AMS 2.06 (internal beta), 2.07, 2.08, 2.09
1544 | 0x608 | AMS 3.00, 3.01

It is, in fact, defined globally, in default.h.

You can precisely determine the AMS version using ReleaseVersion.


V200

V200 Constant (Pseudo-Constant)
compat.h

#define V200 (CALCULATOR == 3)

TRUE on V200, FALSE otherwise.


ctype.h

ctype.h Header File
Header File Index

Routines for checking and changing character types

Functions
_tolower
Translates uppercase characters to lowercase.
_toupper
Translates uppercase characters to lowercase.
isalnum
Checks whether a character is an alphanumeric.
isalpha
Checks whether a character is a letter.
isascii
Checks whether a character is an ASCII character.
iscntrl
Checks whether a character is a control character.
isdigit
Checks whether a character is a digit.
isextalnum
Checks whether a character is an extended alphanumeric.
isextlower
Checks whether a character is a lowercase, including foreign ones.
isextpunct
Checks whether a character is an extended punctuation character.
isextupper
Checks whether a character is an uppercase, including foreign ones.
isfrgn
Checks whether a character is a foreign letter.
isfrgnalnum
Checks whether a character is a foreign letter which is valid in a variable name.
isfrgnlower
Checks whether a character is a foreign lowercase.
isfrgnupper
Checks whether a character is a foreign uppercase.
isgraph
Checks whether a character is a graph character.
isGreek
Checks whether a character is a Greek letter.
islower
Checks whether a character is a lowercase.
isprint
Checks whether a character is a printing character.
ispunct
Checks whether a character is a punctuation character.
isspace
Checks whether a character is a white space.
isupper
Checks whether a character is an uppercase.
isxdigit
Checks whether a character is a hex digit.
toascii
Translates characters to ASCII format.
toextlower
Translates characters to lowercase, including foreign ones.
toextupper
Translates characters to uppercase, including foreign ones.
tolower
Translates characters to lowercase.
toupper
Translates characters to uppercase.

Note: All of these functions are inline functions which are implemented using GNU C smart macros (except the simplest ones, which are ordinary macros). Some of them expand to relatively large code, so if you call any of them more than twice in a program, it will be a good idea to define an ordinary function which calls this macro. For example, if you want to call isxdigit more than twice, define the following to save memory:

int _isxdigit(int c)
{
  return isxdigit (c);
}
Then call _isxdigit instead.


_tolower

_tolower Function (Macro)
ctype.h

short _tolower (short c);

Translates uppercase characters to lowercase.

_tolower does the same conversion as tolower or toextlower, except that it should be used only when c is known to be uppercase (either ordinary or foreign). It is faster, and generates much shorter code than tolower. _tolower returns the converted value of c if it is uppercase; otherwise, the result is undefined. _tolower is a simple macro.


_toupper

_toupper Function (Macro)
ctype.h

short _toupper (short c);

Translates uppercase characters to lowercase.

_toupper does the same conversion as toupper or toextupper, except that it should be used only when c is known to be lowercase (either ordinary or foreign). It is faster, and generates much shorter code than toupper. _toupper returns the converted value of c if it is lowercase; otherwise, the result is undefined. _toupper is a simple macro.


isalnum

isalnum Function (Macro)
ctype.h

short isalnum (short c);

Checks whether a character is an alphanumeric.

isalnum returns nonzero if c is a letter ('A' to 'Z' or 'a' to 'z') or a digit ('0' to '9'), otherwise it returns zero. It is an inline function which is implemented using GNU C smart macros, which expands to a medium-sized code.


isalpha

isalpha Function (Macro)
ctype.h

short isalpha (short c);

Checks whether a character is a letter.

isalpha returns nonzero if c is a letter ('A' to 'Z' or 'a' to 'z'), otherwise it returns zero. It is an inline function which is implemented using GNU C smart macros, which expands to a relatively small code.


isascii

isascii Function (Macro)
ctype.h

short isascii (short c);

Checks whether a character is an ASCII character.

isascii returns nonzero if c is in the range 0 to 127 (0x00-0x7F), otherwise it returns zero. It is a simple macro.


iscntrl

iscntrl Function (Macro)
ctype.h

short iscntrl (short c);

Checks whether a character is a control character.

iscntrl returns nonzero if c is a TIOS control character, otherwise it returns zero. Note that in TIOS control characters are reduced to the range from 0x00 to 0x0D. iscntrl is a simple macro.


isdigit

isdigit Function (Macro)
ctype.h

short isdigit (short c);

Checks whether a character is a digit.

isdigit returns nonzero if c is a digit ('0' to '9'), otherwise it returns zero. It is a small inline function which is implemented using GNU C smart macros.


isextalnum

isextalnum Function (Macro)
ctype.h

short isextalnum (short c);

Checks whether a character is an extended alphanumeric.

isextalnum returns nonzero if c is a symbol which may be used in variable names, including ordinary alphanumerics (see isalnum), underscore ('_') and foreign alphanumerics (see isfrgnalnum), otherwise it returns zero. It is an inline function which is implemented using GNU C smart macros and a library variable. The first call of isextalnum expands to a large code, but any next call of it expands to a relatively small code.


isextlower

isextlower Function (Macro)
ctype.h

short isextlower (short c);

Checks whether a character is a lowercase, including foreign ones.

isextlower returns nonzero if c is a lowercase letter, either ordinary ('a' to 'z') or foreign one (see isfrgnlower), otherwise it returns zero. It is an inline function which is implemented using GNU C smart macros, which expands to a medium-sized code.


isextpunct

isextpunct Function (Macro)
ctype.h

short isextpunct (short c);

Checks whether a character is an extended punctuation character.

isextpunct returns nonzero if c is a character which is printable (see isprint but which is not an extended alphanumeric (see isextalnum), otherwise it returns zero. Extended punctuation characters include ordinary punctuation characters (see ispunct) and some extra ones. isextpunct is an inline function which is implemented using GNU C smart macros. The first call of it expands to a large code, but any next call of it expands to a relatively small code.


isextupper

isextupper Function (Macro)
ctype.h

short isextupper (short c);

Checks whether a character is an uppercase, including foreign ones.

isextupper returns nonzero if c is an uppercase letter, either ordinary ('A' to 'Z') or foreign one (see isfrgnupper), otherwise it returns zero. It is an inline function which is implemented using GNU C smart macros, which expands to a medium-sized code.


isfrgn

isfrgn Function (Macro)
ctype.h

short isfrgn (short c);

Checks whether a character is a foreign letter.

isfrgn returns nonzero if c is a foreign letter (including Greek ones), either uppercase or lowercase (see isGreek, isfrgnupper and isfrgnlower), otherwise it returns zero. It is an inline function which is implemented using GNU C smart macros, which expands to a relatively large code.


isfrgnalnum

isfrgnalnum Function (Macro)
ctype.h

short isfrgnalnum (short c);

Checks whether a character is a foreign letter which is valid in a variable name.

isfrgnalnum is the same as isfrgn, except small Greek "pi" is excluded, because it is the reserved symbol and it is not valid in a variable name. isfrgnalnum is an inline function which is implemented using GNU C smart macros, which expands to a relatively large code.


isfrgnlower

isfrgnlower Function (Macro)
ctype.h

short isfrgnlower (short c);

Checks whether a character is a foreign lowercase.

isfrgnlower returns nonzero if c is a non-Greek foreign lowercase letter (0xE0 to 0xFE except 0xF7), otherwise it returns zero. It is a relatively small inline function which is implemented using GNU C smart macros.


isfrgnupper

isfrgnupper Function (Macro)
ctype.h

short isfrgnupper (short c);

Checks whether a character is a foreign uppercase.

isfrgnupper returns nonzero if c is a non-Greek foreign uppercase letter (0xC0 to 0xDE except 0xD7), otherwise it returns zero. It is a relatively small inline function which is implemented using GNU C smart macros.


isgraph

isgraph Function (Macro)
ctype.h

short isgraph (short c);

Checks whether a character is a graph character.

isgraph returns nonzero if c is printing character, like isprint, except that a space character is excluded; otherwise it returns zero. It is an inline function which is implemented using GNU C smart macros, which expands to a relatively small code.


isGreek

isGreek Function (Macro)
ctype.h

short isGreek (short c);

Checks whether a character is a Greek letter.

isGreek returns nonzero if c is a Greek letter (0x80 to 0x94 and 0xB5), otherwise it returns zero. It is a relatively small inline function which is implemented using GNU C smart macros.


islower

islower Function (Macro)
ctype.h

short islower (short c);

Checks whether a character is a lowercase.

islower returns nonzero if c is a lowercase letter ('a' to 'z'), otherwise it returns zero. It is a small inline function which is implemented using GNU C smart macros.


isprint

isprint Function (Macro)
ctype.h

short isprint (short c);

Checks whether a character is a printing character.

isprint returns nonzero if c is a printing character, otherwise it returns zero. In TIOS, all characters in a range 0x0E to 0xFF and 0x0B are marked as "printable". isprint is a relatively small inline function which is implemented using GNU C smart macros.


ispunct

ispunct Function (Macro)
ctype.h

short ispunct (short c);

Checks whether a character is a punctuation character.

ispunct returns nonzero if c is a punctuation character, otherwise it returns zero. Punctuation characters are all characters in standard ASCII graph range (0x21 to 0x7F), which are not alphanumeric character (see isalnum). ispunct is an inline function which is implemented using GNU C smart macros, which expands to a relatively large code.


isspace

isspace Function (Macro)
ctype.h

short isspace (short c);

Checks whether a character is a white space.

isspace returns nonzero if c is a space, tab, carriage return, new line, vertical tab, or formfeed (0x09 to 0x0D and 0x20), otherwise it returns zero. It is a relatively small inline function which is implemented using GNU C smart macros.


isupper

isupper Function (Macro)
ctype.h

short isupper (short c);

Checks whether a character is an uppercase.

isupper returns nonzero if c is an uppercase letter ('A' to 'Z'), otherwise it returns zero. It is a small inline function which is implemented using GNU C smart macros.


isxdigit

isxdigit Function (Macro)
ctype.h

short isxdigit (short c);

Checks whether a character is a hex digit.

isxdigit returns nonzero if c is a hexadecimal digit ('0' to '9', 'A' to 'F' or 'a' to 'f'), otherwise it returns zero. It is an inline function which is implemented using GNU C smart macros, which expands to a medium-sized code.


toascii

toascii Function (Macro)
ctype.h

short toascii (short c);

Translates characters to ASCII format.

toascii converts the integer c to ASCII by clearing all but the lower 7 bits. This gives a value in the range 0 to 127. Returns the converted value of c. toascii is a simple macro.


toextlower

toextlower Function (Macro)
ctype.h

short toextlower (short c);

Translates characters to lowercase, including foreign ones.

toextlower works like tolower, but it also converts foreign uppercase characters (see isfrgnupper). toextupper is an inline function which is implemented using GNU C smart macros, which expands to a medium-sized code.


toextupper

toextupper Function (Macro)
ctype.h

short toextupper (short c);

Translates characters to uppercase, including foreign ones.

toextupper works like toupper, but it also converts foreign lowercase characters (see isfrgnlower). toextupper is an inline function which is implemented using GNU C smart macros, which expands to a medium-sized code.


tolower

tolower Function (Macro)
ctype.h

short tolower (short c);

Translates characters to lowercase.

tolower is a function that converts an integer c to its lowercase value ('a' to 'z') if it was uppercase ('A' to 'Z'). All others are left unchanged. Returns the converted value of c. tolower is a relatively small inline function which is implemented using GNU C smart macros.


toupper

toupper Function (Macro)
ctype.h

short toupper (short c);

Translates characters to uppercase.

toupper is a function that converts an integer c to its uppercase value ('A' to 'Z') if it was lowercase ('a' to 'z'). All others are left unchanged. Returns the converted value of c. toupper is a relatively small inline function which is implemented using GNU C smart macros.


default.h

default.h Header File
Header File Index

Default header file which is always included

default.h is always included at the top of every other header file.

In addition to defining the following macros, this header file handles basic symbols such as USE_TI89 and related ones, or MIN_AMS. See the info section How to make a TIGCC/GCC4TI program.

Functions
_rom_call_addr_concat
Returns a void pointer to a TIOS ROM call (internal).
_rom_call_addr_hack_concat
Returns a void pointer for a TIOS ROM call, using an address hack if needed (internal).
_rom_call_addr_hack
Returns a void pointer for a TIOS ROM call, using an address hack if needed.
_rom_call_addr
Returns a void pointer to a TIOS ROM call.
_rom_call_attr
Constructs a function definition with attributes for a TIOS ROM call.
_rom_call_concat
Constructs a function definition for a TIOS ROM call (internal).
_rom_call_hack_attr_concat
Constructs a function definition with an address hack and attributes for a TIOS ROM call (internal).
_rom_call_hack_attr
Constructs a function definition with an address hack and attributes for a TIOS ROM call.
_rom_call_hack
Constructs a function definition with an address hack for a TIOS ROM call.
_rom_call
Constructs a function definition for a TIOS ROM call.
import_binary
Imports a binary file as an arbitrary symbol.
Global Variables
__jmp_tbl
A variable which points to the TIOS jump table of ROM calls.
Constants
MIN_AMS_MAJOR
The major part of MIN_AMS.
MIN_AMS_MINOR
The minor part of MIN_AMS.

See also: nostub.h, doors.h


_rom_call_addr_concat

_rom_call_addr_concat Function (Macro)
default.h

#define _rom_call_addr_concat(intindex,romindex) (__jmp_tbl [intindex])

Returns a void pointer to a TIOS ROM call (internal).

_rom_call_addr_concat is an internal macro which is used by _rom_call_addr and _rom_call.

intindex contains the index of the ROM call as a numeric constant. It is used in this definition, as an array subscript for __jmp_tbl, a pointer to the table of ROM calls. romindex contains a symbol in the form _ROM_CALL_xxx, where xxx is the index in hexadecimal form without the '0x' prefix.

Other header files override this definition to use romind instead. In particular, doors.h includes a romsymb.h header file which defines a list of external variables for all ROM call symbols which may appear in romindex, and changes the definition to:

#define _rom_call_addr_concat(intindex,romindex) (&romindex)
You probably wonder why _rom_call_addr_concat exists at all, since other header files might as well override _rom_call_addr, which could be used directly by _rom_call. The reason is that all arguments which are not concatenated are scanned for macros that have to be expanded. If _rom_call was using _rom_call_addr, passing index to it, then the index parameter would be scanned. This turns out to be fatal if the user defines a macro such as A1, and uses the ROM call with the index 0xA1.

Therefore, both _rom_call_addr and _rom_call have to use concatenation on their index parameter. Then they pass the resulting symbols to _rom_call_addr_concat.


_rom_call_addr_hack_concat

_rom_call_addr_hack_concat Function (Macro Constructor)
default.h

#define _rom_call_addr_hack_concat(intindex,romindex,addr,minams,minindex) (MIN_AMS >= (minams) || TIOS_entries >
(minindex) ? _rom_call_addr_concat (intindex, romindex) : ({
asm (".xdef __ref_all___reject_unofficial_os");
(void *) (addr);
}))

Returns a void pointer for a TIOS ROM call, using an address hack if needed (internal).

_rom_call_addr_hack_concat is a macro used internally by _rom_call_addr_hack. Its only purpose is to prevent prescan of the ROM call index (see _rom_call_addr_concat for more information).

See also: _rom_call_addr_hack


_rom_call_addr_hack

_rom_call_addr_hack Function (Macro Constructor)
default.h

#define _rom_call_addr_hack(index,addr,minams) (_rom_call_addr_hack_concat (0x##index, _ROM_CALL_##index, (addr), (minams), 0x##index))

Returns a void pointer for a TIOS ROM call, using an address hack if needed.

_rom_call_addr_hack works exactly like _rom_call_addr, except that it takes an additional parameter addr specifying an alternative way to get the address of the ROM call. If the TIOS jump table contains the ROM call specified by index, the address from the jump table is used. Otherwise _rom_call_addr_hack computes the address specified by addr (which can be any pointer type), and returns it.

minams specifies the AMS version which first exports the ROM call identified by index. If the value of MIN_AMS is greater or equal to the value of minams, the ROM call is used unconditionally. When using this macro directly, you need to make sure that this value is correct; otherwise you will get crashes only if a specific value for MIN_AMS has been chosen and an unsupported AMS version is used.

See also: _rom_call_addr, _rom_call_hack, Manually Obtaining the Address of a ROM Function


_rom_call_addr

_rom_call_addr Function (Macro)
default.h

#define _rom_call_addr(index) (_rom_call_addr_concat (0x##index, _ROM_CALL_##index))

Returns a void pointer to a TIOS ROM call.

_rom_call_addr returns a void pointer to a TIOS ROM call, which you can cast to any other pointer type. After this cast, you can dereference it and handle it like any other variable.

Note that index is the index of the ROM Call in hexadecimal form, but without the '0x' prefix. The reason for this unusual convention is that kernel programs use ROM calls by referring to _ROM_CALL_xxx, where xxx is the hexadecimal index of the ROM call.

See _rom_call_addr_concat for info about the reason why _rom_call_addr_concat is used.


_rom_call_attr

_rom_call_attr Function (Macro Constructor)
default.h

#define _rom_call_attr(type,args,attr,index) (*({
typedef __ATTR_TIOS__ attr type (*__temp__type__) args;
(__temp__type__) (__rom_call_addr_concat (0x##index, _ROM_CALL_##index));
}))

Constructs a function definition with attributes for a TIOS ROM call.

_rom_call_attr works exactly like _rom_call, except that it takes an additional parameter attr to specify attributes for the function.

See also: _rom_call


_rom_call_concat

_rom_call_concat Function (Macro Constructor)
default.h

#define _rom_call_concat(type,args,intindex,romindex) (*((type (* __ATTR_TIOS__) args) (__rom_call_addr_concat (intindex, romindex))))

Constructs a function definition for a TIOS ROM call (internal).

_rom_call_concat is a macro used internally by _rom_call and other macros. Its only purpose is to prevent prescan of the ROM call index (see _rom_call_addr_concat for more information).

See also: _rom_call


_rom_call_hack_attr_concat

_rom_call_hack_attr_concat Function (Macro Constructor)
default.h

#define _rom_call_hack_attr_concat(type,args,attr,intindex,romindex,addr,minams,minindex) (*({
typedef __ATTR_TIOS__ attr type (*__temp__type__hack__) args;
(__temp__type__hack__) (MIN_AMS >= (minams) || TIOS_entries >
(minindex) ? (const void *) (&(_rom_call_concat (void, (void), (intindex), (romindex)))) : ({
asm (".xdef __ref_all___reject_unofficial_os");
(const void *) (addr);
}));
}))

Constructs a function definition with an address hack and attributes for a TIOS ROM call (internal).

_rom_call_hack_attr_concat is a macro used internally by _rom_call_hack and _rom_call_hack_attr. Its only purpose is to prevent prescan of the ROM call index (see _rom_call_addr_concat for more information).

See also: _rom_call_hack_attr, _rom_call_hack, _rom_call


_rom_call_hack_attr

_rom_call_hack_attr Function (Macro Constructor)
default.h

#define _rom_call_hack_attr(type,args,attr,index,addr,minams) (_rom_call_hack_attr_concat (type, args, attr, 0x##index, _ROM_CALL_##index, (addr), (minams), 0x##index))

Constructs a function definition with an address hack and attributes for a TIOS ROM call.

_rom_call_hack_attr works exactly like _rom_call_hack, except that it takes an additional parameter attr to specify attributes for the function.

See also: _rom_call_hack, _rom_call_addr_hack, _rom_call_attr, _rom_call


_rom_call_hack

_rom_call_hack Function (Macro Constructor)
default.h

#define _rom_call_hack(type,args,index,addr,minams) (_rom_call_hack_attr_concat (type, args, , 0x##index, _ROM_CALL_##index, (addr), (minams), 0x##index))

Constructs a function definition with an address hack for a TIOS ROM call.

_rom_call_hack works exactly like _rom_call, except that it takes an additional parameter addr specifying an alternative way to get the address of the ROM call. If the TIOS jump table contains the ROM call specified by index, the address from the jump table is used. Otherwise _rom_call_hack computes the address specified by addr (which can be any pointer type), and uses it as the address of the ROM call.

minams specifies the AMS version which first exports the ROM call identified by index. If the value of MIN_AMS is greater or equal to the value of minams, the ROM call is used unconditionally. When using this macro directly, you need to make sure that this value is correct; otherwise you will get crashes only if a specific value for MIN_AMS has been chosen and an unsupported AMS version is used.

See also: _rom_call, _rom_call_hack_attr, _rom_call_addr_hack, Manually Obtaining the Address of a ROM Function


_rom_call

_rom_call Function (Macro Constructor)
default.h

#define _rom_call(type,args,index) (_rom_call_concat (type, args, 0x##index, _ROM_CALL_##index))

Constructs a function definition for a TIOS ROM call.

_rom_call uses _rom_call_addr to get a void pointer to the location in memory where the function is stored, and then casts this pointer to a temporarily defined "pointer to function" type.

To avoid argument prescan of index, _rom_call_addr cannot be used directly, but instead another macro has to be used, which has been called _rom_call_addr_concat.

See also: _rom_call_attr, _rom_call_hack, _rom_call_addr


import_binary

import_binary Function (Macro Constructor)
default.h

#define import_binary(filename,symname) asm(".globl "#symname"\n"#symname":\n\t.incbin \""filename"\"")

Imports a binary file as an arbitrary symbol.

import_binary imports a binary file at the current position using the .incbin assembler directive. The parameter filename specifies the file name in quotes; symname specifies the symbol name to assign to the contents. You can give the symbol any type using an external definition; for example:

extern unsigned char myarray[];
import_binary ("myfile.bin", myarray);
It is not recommended to use import_binary at any place other than the top level, as binary contents placed inside functions will generally be interpreted as code.


__jmp_tbl

__jmp_tbl Variable
default.h

#define __jmp_tbl (*(void***)0xC8)

A variable which points to the TIOS jump table of ROM calls.

__jmp_tbl is a global variable, which is implemented here as a macro. Defining OPTIMIZE_ROM_CALLS causes this definition to be overridden; in this case, __jmp_tbl will be a real variable stored in the register a5.

__jmp_tbl is always a pointer to a void pointer, so you can treat it as an array of void pointers. Its size can be determined using the TIOS_entries pseudo-constant.

Most of the entries in the jump table point to functions, but some of them actually point to global variables of the operating system.

Usually, it is not desirable to use __jmp_tbl directly. The code may be optimized a little better if you use the _rom_call and _rom_call_addr macros instead.


MIN_AMS_MAJOR

MIN_AMS_MAJOR Constant
default.h

#define MIN_AMS_MAJOR (MIN_AMS / 100)

The major part of MIN_AMS.

MIN_AMS_MAJOR contains the major version number of the defined minimum AMS version. It may be used in header files which are supplied to a lot of users to test the availability of certain features, in addition to MIN_AMS itself.


MIN_AMS_MINOR

MIN_AMS_MINOR Constant
default.h

#define MIN_AMS_MINOR (MIN_AMS % 100)

The minor part of MIN_AMS.

MIN_AMS_MINOR contains the minor version number of the defined minimum AMS version. It may be used in header files which are supplied to a lot of users to test the availability of certain features, in addition to MIN_AMS itself.


dialogs.h

dialogs.h Header File
Header File Index

Routines for creating dialogs

Functions
Dialog
Shows and activates a dialog box given a pointer to a dialog structure.
DialogAdd
Adds an item into a dialog box.
DialogAddDynamicPulldown
Adds a dynamic pulldown menu into a dialog box.
DialogAddDynamicRequest
Adds a request/edit box with a dynamic buffer into a dialog box.
DialogAddMenu
Adds a menu into a dialog box.
DialogAddPulldown
Adds a pulldown/popup menu into a dialog box.
DialogAddPulldownEx
Adds a pulldown/popup menu into a dialog box. Extended version.
DialogAddRequest
Adds a request/edit box into a dialog box.
DialogAddRequestEx
Adds a request/edit box into a dialog box. Extended version.
DialogAddScrollRegion
Adds a rectangular item-scrolling region to a dialog box.
DialogAddStaticPulldown
Adds a static pulldown/popup menu into a dialog box.
DialogAddText
Adds a text into a dialog box.
DialogAddTextEx
Adds a text, an image, or a custom item into a dialog box.
DialogAddTitle
Adds a title bar and up to two buttons into a dialog box.
DialogAddTitleEx
Adds a title/header bar and up to two buttons into a dialog box. Extended version.
DialogAddXFlags
Adds extended dialog properties into a dialog box.
DialogDo
Activates and shows a dialog box.
DialogNew
Creates a new dialog box which can interact with the user program.
DialogNewSimple
Creates a new dialog box.
DlgMessage
Displays a message dialog box.
HI_WORD
Returns the high word from a long value.
LO_WORD
Returns the low word from a long value.
NoCallBack
Dummy callback function doing nothing.
VarNew
Displays the standard "New" dialog.
VarOpen
Displays the standard "Open" dialog.
VarSaveAs
Displays the standard "Save Copy As" dialog.
Constants
CENTER
A constant to describe a centered position for dialogs.
DialogMessages
An enumeration to describe messages used by a Dialog's Callback.
H_NULL
A null-handle value.
NULL
A null-pointer value.
Predefined Types
Bool
An enumeration to describe true or false values.
Buttons
An enumeration to describe possible button types.
Dialog_Callback_t
Callback function type for dialogs.
Dialog_GetHandle_t
Callback function type returning a handle for a dialog item.
DIALOG_ITEM
A scructure for defining dialog items.
DIALOG
A scructure for defining dialogs.
DialogFlags
An enumeration to describe possible item flags in a dialog box.
DialogTypes
An enumeration to describe possible item types in a dialog box.
DialogXFlags
An enumeration to describe possible XFlags in a dialog box.
ESQ
Represents a quantum within an expression.
HANDLE
Represents a handle associated with an allocated memory block.
HSym
A structure representing a symbol reference.
OWNER_DRAW_STRUCT
A scructure for defining an owner draw item.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
WINDOW
The main window-describing structure.
Other Identifiers
SIZED_DIALOG
A macro to help defining dialogs, it is nearly the same as DIALOG.

Note: If your program uses functions from this header file, you probably have to define SET_FILE_IN_USE_BIT.


Dialog

Dialog Function (ROM Call 0x30)
dialogs.h

short Dialog (DIALOG *DialogPtr, short x, short y, char *RequestBuffer, short *PopupBuffer);

Shows and activates a dialog box given a pointer to a dialog structure.

Dialog works exactly like DialogDo, except instead of the handle, a pointer to the dialog structure is given as the parameter. DialogDo internally calls HeapDeref, then passes the returned pointer to the Dialog function. This function is mainly used internally in TIOS. Its advantage compared to DialogDo is the fact that the complete dialog structure may be given as a static pre-filled array of bytes, and you can give a pointer to such a structure to the Dialog function. It will save a lot of memory, because you do not need to call DialogNew and a lot of functions like DialogAddText etc.

If DialogPtr points to a dynamically created dialog box (i.e a dialog created with DialogNew or DialogAdd), the heap block that stores the dialog box must be locked because this routine may cause heap compression.

Dialog may return:

  • KEY_ENTER if the user pressed ENTER to close the dialog box.
  • KEY_ESC if the user pressed ESC to close the dialog box.
  • -1 if there is not enough memory to open the menu for the dialog box.

Uses: HeapGetLock, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, ERD_dialog, EV_captureEvents, EV_eventLoop, EV_paintWindows, EV_restorePainting, EV_suspendPainting, DrawStrWidth, DrawStrWidthP, FontCharWidth, FontGetSys, FontSetSys, alphaLockOff, alphaLockOn, GKeyIn, restoreAlphaLock, OSWriteLinkBlock, memset, MenuEnd, MenuOn, MenuPopup, MenuUpdate, ST_eraseHelp, strlen, CU_restore, CU_stop, OSSetSR, OSTimerRestart, XR_stringPtr, TE_close, TE_focus, TE_open, TE_openFixed, TE_select, TE_shrinkWrap, TE_unfocus, clear_error_context, sf_width, RectWinToScr, WinActivate, WinAttr, WinCharXY, WinClose, WinFill, WinFont, WinOpen, WinRect, WinStrXY, _du16u16, ROM Call 0x41C, ROM Call 0x41D, ROM Call 0x41E, ROM Call 0x471, ROM Call 0x4D7, ROM Call 0x5C6
Used by: DialogDo, cmd_clrtable, EV_defaultHandler, handleRclKey, MO_modeDialog, HomeExecute, LIO_Receive, TE_handleEvent, GT_DE_Init_Conds, GT_Format, GZ_SetFactors, SP_Define, ROM Call 0x45E, DateAndTime_SetDlg

See also: DialogDo


DialogAdd

DialogAdd Function (ROM Call 0x33)
dialogs.h

HANDLE DialogAdd (HANDLE Handle, short flags, short x, short y, short ItemType, ...);

Adds an item into a dialog box.

DialogAdd is a universal item-adding function. It is a very complicated function which accepts 6 to 12 parameters depending on the type of the item which will be added. This type is determined by the ItemType parameter. In fact, all other functions whose names begin with "DialogAdd..." (such as DialogAddTextEx, DialogAddTitleEx, DialogAddRequestEx, DialogAddPulldownEx, etc.) are implemented as macros which call DialogAdd with appropriate parameters (for easier usage), so you can mainly avoid this function. You can read the dialogs.h header file to see how exactly these macros are implemented.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

DialogAdd returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

ItemType can be filled with one of the following commands, defined in the DialogTypes enum:

ItemType | Appearance | Additional Parameters | Macro
D_HEADER | Title bar, up to two buttons | const char *title, unsigned short LeftButton, unsigned short RightButton | DialogAddTitleEx
D_TEXT | Text or personalized item | const char *text | DialogAddTextEx
D_EDIT_FIELD | Request (edit) box | const char *label, unsigned short offset, unsigned short MaxLen, unsigned short width | DialogAddRequestEx
D_HEDIT | Request (edit) box | const char *label, unsigned short width | DialogAddDynamicRequest
D_POPUP | Pulldown menu | const char *label, void *Popup, unsigned short buffer | DialogAddStaticPulldown
D_DYNPOPUP | AMS 2.00 or higher: Pulldown menu | const char *label, Dialog_GetHandle_t GetPopup, unsigned short index | DialogAddDynamicPulldown
D_HPOPUP | Pulldown menu | const char *label, HANDLE MenuHandle, unsigned short index | DialogAddPulldownEx
D_MENU | AMS 2.00 or higher: Main menu | void *Menu, unsigned short MaxMenuWidth | DialogAddMenu
D_SCROLL_REGION | Scroll region | unsigned short x1, unsigned short y1, unsigned short FirstItem, unsigned short LastItem, unsigned short NumDspItems, unsigned short TotNumItems, unsigned short ItemHeight | DialogAddScrollRegion
D_XFLAGS | AMS 2.00 or higher: Extended dialog properties | unsigned short xFlags1, unsigned short xFlags2, unsigned short xFlags3, unsigned short xFlags4 | DialogAddXFlags

The parameter flags depends on the type of element you are creating and can be a combination of the following flags, defined in the DialogFlags enum:

Flag | Item Type | Description
DF_SCREEN_SAVE | (any) | When applied to the first item in the dialog, the dialog code saves the area underneath the dialog box when it is started. DialogAdd returns DB_MEMFULL if there is not enough memory to do this.
DF_SKIP | (any) | This item is skipped when browsing through items with the arrow keys. For example, all text items should have this flag set.
DF_SCROLLABLE | (any) | Set this flag if you want this item to be scrollable in a scroll region.
DF_TAB_ELLIPSES | Request box, pulldown menu | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. It is the default on AMS 1.xx.
DF_TAB_SPACES | Request box, pulldown menu | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots.
DF_OWNER_DRAW | Text | AMS 2.00 or higher: The callback function (see DialogNew for more information) is responsible for drawing this item (which can be text, an image, or anything else). This can only be done if the dialog was created with DialogNew and not DialogNewSimple.
DF_POPUP_RADIO | Pulldown menu | AMS 2.00 or higher: If this flag is set, the item looks like a normal pulldown menu that you can select, but when you press the right arrow key, it does not pop up as usual, but returns control to the dialog callback function. This enables the programmer to do whatever he/she wants. For example, in the 'MODE' dialog, setting custom units pops up another dialog instead of a pulldown menu.
DF_MAX_MENU_WIDTH | Main menu | AMS 2.00 or higher: Passes MBF_MAX_MENU_WIDTH to MenuBegin when the menu is drawn.
DF_CLR_ON_REDRAW | Scroll region | Clears the entire visible scroll region when redrawn. If you do not set this flag, the scroll region will not be cleared before being redrawn, and you might still see the previously drawn items underneath the new ones.

Note: If you want your program to work in AMS 1.xx, you cannot pass D_MENU, D_DYNPOPUP, and D_XFLAGS to this function. Nevertheless, you can initialize a DIALOG structure with these items, and the program will still work on AMS 1.xx.

Uses: HeapRealloc, HeapSize, memcpy, memmove, memset, strlen
Used by: DialogAddPulldown, DialogAddRequest, DialogAddText, DialogAddTitle, DialogAddDynamicPulldown, DialogAddDynamicRequest, DialogAddMenu, DialogAddPulldownEx, DialogAddRequestEx, DialogAddScrollRegion, DialogAddStaticPulldown, DialogAddTextEx, DialogAddTitleEx, DialogAddXFlags, DlgMessage, VarNew, VarOpen, VarSaveAs, cmd_dialog, cmd_request, EV_defaultHandler, HomeExecute, VarSaveTitle

See also: DialogDo, DialogNew, DIALOG


DialogAddDynamicPulldown

DialogAddDynamicPulldown Function (Macro)
AMS 2.00 or higher dialogs.h

HANDLE DialogAddDynamicPulldown (HANDLE Handle, short flags, short x, short y, const char *label, Dialog_GetHandle_t GetPopup, unsigned short index);

Adds a dynamic pulldown menu into a dialog box.

DialogAddDynamicPulldown adds a pulldown item to the dialog box associated with the handle Handle at the position (x,y), where the coordinates are relative to the top-left corner of the dialog box.

When the pulldown is opened, the function passed to the GetPopup parameter is called (with the identification number of the newly created item as the value of the ID parameter), and it must return the handle of the actual popup menu (usually created using PopupNew). See menus.h for more information about creating popups.

An optional label label will appear in front of the request box; an empty string is used to indicate that no label should be drawn. The parameter index determines where the result value of executing the pulldown menu will be stored, and also indicates what the initially selected option will be. See DialogDo for information on how and where the result values are actually stored.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

The parameter flags can be a combination of the following, defined in the DialogFlags enumeration:
DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region.
DF_SKIP | This item is skipped when browsing through items with the arrow keys.
DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box.
DF_TAB_ELLIPSES | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. It is the default on AMS 1.xx.
DF_TAB_SPACES | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots.
DF_POPUP_RADIO | AMS 2.00 or higher: If this flag is set, the item looks like a normal pulldown menu that you can select, but when you press the right arrow key, it does not pop up as usual, but returns control to the dialog callback function. This enables the programmer to do whatever he/she wants. For example, in the 'MODE' dialog, setting custom units pops up another dialog instead of a pulldown menu.

DialogAddDynamicPulldown returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddDynamicPulldown is in fact a macro created for your convenience. It calls DialogAdd with D_DYNPOPUP as the ItemType parameter.

Uses: DialogAdd


DialogAddDynamicRequest

DialogAddDynamicRequest Function (Macro)
dialogs.h

HANDLE DialogAddDynamicRequest (HANDLE Handle, short flags, short x, short y, const char *label, unsigned short width);

Adds a request/edit box with a dynamic buffer into a dialog box.

DialogAddDynamicRequest adds a request box (i.e. an input line edit box) with a dynamic buffer to the dialog structure associated with the handle Handle at the position (x,y), where the coordinates are relative to the top-left corner of the dialog box. An optional label label will appear in front of the request box. An empty string, "", is used to indicate no label.

Items created with DialogAddDynamicRequest doesn't use the RequestBuffer array passed to the Dialog function, so they do not need the offset and MaxLen values like normal edit items as described in DialogAddRequestEx. Instead, the callback function (see DialogNew for more information) is called with the first parameter equal to DB_GET_EDIT_HANDLE and the second parameter equal to the item's identification number. The callback should then return the handle of an edit buffer of at least width bytes long. width determines the actual width of the request box (This is very useful when you need to prevent the user from overstepping a special size such as file names). It will be such that the widest string made of width characters may fit into the box. So, the real width of box in pixels will be width*6, because the widest character 'M' is 6 pixels wide. If you try to enter a string with more than width characters, the system will prevent you from doing so. If width is wider than the actually available width of the dialog box, the request box will be truncated at the edge of the dialog box.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

The parameter flags can be a combination of the following, defined in the DialogFlags enumeration:
DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region.
DF_SKIP | This item is skipped when browsing through items with the arrow keys.
DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box.
DF_TAB_ELLIPSES | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. (It is the default on AMS 1.xx. See the note below for more information.)
DF_TAB_SPACES | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots.

Note: On AMS 1.xx, all request boxes in one dialog box will be aligned according to the request box which has the longest label, except when the label string finishes with a '`' character (code 96). In such case, the request box will start immediately after the label string ('`' is a special character, which will not be displayed). When the label doesn't end with '`', it can be padded with '.' characters up to the length of the longest label, except if the label finishes with ':': In that case, the label will be padded with space characters (':' will also be displayed).

DialogAddDynamicRequest returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddDynamicRequest is in fact a macro created for your convenience. It calls DialogAdd with D_HEDIT as the ItemType parameter.

Uses: DialogAdd


DialogAddMenu

DialogAddMenu Function (Macro)
AMS 2.00 or higher dialogs.h

HANDLE DialogAddMenu (HANDLE Handle, short flags, short x, short y, void *Menu, unsigned short MaxMenuWidth);

Adds a menu into a dialog box.

DialogAddMenu adds the menu Menu, with a maximum width of MaxMenuWidth (or zero to automatically calculate the width) at the position (x,y) to the dialog structure associated with the handle Handle, where the coordinates are relative to the top-left corner of the dialog box.

A menu item is defined by a pointer Menu to a toolbar menu structure created statically (i.e. you must include a pre-filled static menu in your source code) or dynamically with MenuNew (in this case the caller must ensure the structure remains locked while in use in the dialog box, i.e. use HLock in the same way as for MenuBegin). The menu is drawn by an internal call to MenuBegin. When a menu key is pressed, the callback's (see DialogNew for more information) Message value will be the item's identification number and Value will be passed the menu handle returned from MenuBegin in the high word and the key code in the low word. You can specify a maximum width for your menu in MaxMenuWidth or zero if you want it to be automatically calculated. Each dialog box can have at most one menu. The creation of menus is explained in the header file menus.h. Note that if you want a menu, you must write a callback function, else you will not be able to do anything but dispaying it!

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

The parameter flags can be a combination of the following, defined in the DialogFlags enumeration:
DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box.
DF_MAX_MENU_WIDTH | AMS 2.00 or higher: Passes MBF_MAX_MENU_WIDTH to MenuBegin when the menu is drawn.

DialogAddMenu returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddMenu is in fact a macro created for your convenience. It calls DialogAdd with D_MENU as the ItemType parameter.

Uses: DialogAdd


DialogAddPulldown

DialogAddPulldown Function (Macro)
dialogs.h

HANDLE DialogAddPulldown (HANDLE Handle, short x, short y, const char *prompt, HANDLE MenuHandle, unsigned short index);

Adds a pulldown/popup menu into a dialog box.

DialogAddPulldown works exactly as DialogAddPulldownEx, but doesn't have the flags parameter available. This routine is in fact a macro using DialogAdd with D_HPOPUP passed as a command and zero passed as the flags. All the parameters are explained in DialogAddPulldownEx.

Uses: DialogAdd


DialogAddPulldownEx

DialogAddPulldownEx Function (Macro)
dialogs.h

HANDLE DialogAddPulldownEx (HANDLE Handle, short flags, short x, short y, const char *label, HANDLE PopupMenu, unsigned short index);

Adds a pulldown/popup menu into a dialog box. Extended version.

DialogAddPulldownEx adds the pulldown menu PopupMenu to the dialog structure associated with the handle Handle at the position (x,y), where the coordinates are relative to the top-left corner of the dialog box.

label is the label which will appear in front of the popup menu (or "" if you don't want any name), and MenuHandle is the handle of the associated menu which needs to be created using the PopupNew function (the same functions are used for creating pulldown and popup menus). See menus.h for more info about creating popups. The text must fit into one line of the dialog box.

The parameter index determines where the result value of executing the pulldown menu will be stored, and also indicates what the initially selected option will be. See DialogDo for information on how and where the result values are actually stored.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

The parameter flags can be a combination of the following, defined in the DialogFlags enumeration:
DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region.
DF_SKIP | This item is skipped when browsing through items with the arrow keys.
DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box.
DF_TAB_ELLIPSES | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. It is the default on AMS 1.xx.
DF_TAB_SPACES | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots.
DF_POPUP_RADIO | AMS 2.00 or higher: If this flag is set, the item looks like a normal pulldown menu that you can select, but when you press the right arrow key, it does not pop up as usual, but returns control to the dialog callback function. This enables the programmer to do whatever he/she wants. For example, in the 'MODE' dialog, setting custom units pops up another dialog instead of a pulldown menu.

DialogAddPulldownEx returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddPulldownEx is in fact a macro created for your convenience. It calls DialogAdd with D_HPOPUP as the ItemType parameter. Note that DialogAddPulldownEx is the same macro as DialogAddPulldown except for the parameter flags which is always set to zero in DialogAddPulldown.

Uses: DialogAdd


DialogAddRequest

DialogAddRequest Function (Macro)
dialogs.h

HANDLE DialogAddRequest (HANDLE Handle, short x, short y, const char *prompt, unsigned short offset, short MaxLen, short width);

Adds a request/edit box into a dialog box.

DialogAddRequest works exactly as DialogAddRequestEx, but doesn't have the flags parameter available. This routine is in fact a macro using DialogAdd with D_EDIT_FIELD passed as a command and zero passed as the flags. All the parameters are explained in DialogAddRequestEx.

Uses: DialogAdd


DialogAddRequestEx

DialogAddRequestEx Function (Macro)
dialogs.h

HANDLE DialogAddRequestEx (HANDLE Handle, short flags, short x, short y, const char *label, unsigned short offset, short MaxLen, short width);

Adds a request/edit box into a dialog box. Extended version.

DialogAddRequestEx adds a request box (i.e. an input line edit box) to the dialog structure associated with the handle Handle at the position (x,y), where the coordinates are relative to the top-left corner of the dialog box. An optional label label will appear in front of the request box. An empty string, "", is used to indicate no label.

The maximal number of characters which may be entered is determined by the parameter MaxLen (MaxLen must at most have the size of the RequestBuffer given to DialogDo), and width determines the actual display width of the request box (MaxLen can be very usefull when you need to prevent the user from overstepping a special size such as file names). It will be such that the widest string made of width characters may fit into the box. So, the real display width of box in pixels will be width*6, because the widest character 'M' is 6 pixels wide. If you try to enter a string with more than width characters, the content of the request box will scroll, and if you try to have a string longer than MaxLen, the system will prevent you from doing so. If width is wider than the actually available width of the dialog box, the request box will be truncated at the edge of the dialog box.

The parameter offset determines what will be the initial content of the request box, and where the entered characters will be stored. See DialogDo for information on how and where the entered characters are actually stored.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

The parameter flags can be a combination of the following, defined in the DialogFlags enumeration:
DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region.
DF_SKIP | This item is skipped when browsing through items with the arrow keys.
DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box.
DF_TAB_ELLIPSES | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. (It is the default on AMS 1.xx. See the note below for more information.)
DF_TAB_SPACES | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots.

Note: On AMS 1.xx, all request boxes in one dialog box will be aligned according to the request box which has the longest label, except when the label string finishes with a '`' character (code 96). In such case, the request box will start immediately after the label string ('`' is a special character, which will not be displayed). When the label doesn't end with '`', it can be padded with '.' characters up to the length of the longest label, except if the label finishes with ':': In that case, the label will be padded with space characters (':' will also be displayed).

DialogAddRequestEx returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddRequestEx is in fact a macro created for your convenience. It calls DialogAdd with D_EDIT_FIELD as the ItemType parameter. Note that DialogAddRequestEx is the same macro as DialogAddRequest except for the parameter flags which is always set to zero in DialogAddRequest.

Uses: DialogAdd


DialogAddScrollRegion

DialogAddScrollRegion Function (Macro)
dialogs.h

HANDLE DialogAddScrollRegion (HANDLE Handle, short flags, short x, short y, unsigned short x1, unsigned short y1, unsigned short FirstItem, unsigned short LastItem, unsigned short NumDspItems, unsigned short TotNumItems, unsigned short ItemHeight);

Adds a rectangular item-scrolling region to a dialog box.

DialogAddScrollRegion adds a rectangular item-scrolling region to the dialog structure associated with the handle Handle from the (x, y) position to the (x1, y1) position, where all coordinates are relative to the top-left corner of the dialog box.

A scroll region defines a group of items that will scroll as the user moves through the items. The identification number of the first scrollable should be set in FirstItem and the last scrollable item in LastItem. NumDspItems defines the number of items that are displayed at one time. The total number of scrollable item should be set in TotNumItems and the height of each item in ItemHeight. Every scrollable item must be defined contiguously and have the DF_SCROLLABLE flag set and must not be of MENU, HEADER or XFLAGS type. The coordinates of the scrollable items are relative to the dialog box except that they may extend beyond the bottom coordinate of the dialog box. They are defined assuming a virtual scroll region.

It's very easy to cause display bugs using this function (of course, that won't crash your calculator, but the dialog can easily become ugly), so here is a method you can use to avoid those bugs: First, the standard item height is the height of the biggest item (often the EDIT item which is 10 pixel high), so the minimum value in ItemHeight should be 10 in most cases. Then, to avoid any display bugs, the y axis should be the y value of your first displayed item - 2 and y1 axis should be the y value of your last displayed item + 8. I.e. if you wish to scroll 8 items and only display items 3 by 3 (but please use the available screen space: don't just restrict the items displayed at a time to 3 just because everyone else does it), and the first scrollable item is item number 4 (the last displayed item at the beginning is therefore item 6), the calculation should be: y=(item 4 y axis)-2 and y1=(item 6 y axis)+8). The difference x1-x should also be greater than the width of the largest item (else it will result in display bugs). I don't really understand the utility of such a TotNumItems parameter as it should always be equal to LastItem-FirstItem+1. The flag DF_CLR_ON_REDRAW is very useful and should be set in most cases (see below).

Note: If you use a SCROLL_REGION, it must be the first item defined in the dialog box. A dialog box can therefore have at most one scroll region.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

The parameter flags can be a combination of the following, defined in the DialogFlags enumeration:
DF_SKIP | This item is skipped when browsing through items with the arrow keys.
DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box.
DF_CLR_ON_REDRAW | Clears the entire visible scroll region when redrawn. If you do not set this flag, the scroll region will not be cleared before being redrawn, and you might still see the previously drawn items underneath the new ones.

DialogAddScrollRegion returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddScrollRegion is in fact a macro created for your convenience. It calls DialogAdd with D_SCROLL_REGION as the ItemType parameter.

Uses: DialogAdd


DialogAddStaticPulldown

DialogAddStaticPulldown Function (Macro)
dialogs.h

HANDLE DialogAddStaticPulldown (HANDLE Handle, short flags, short x, short y, const char *label, void *Popup, unsigned short index);

Adds a static pulldown/popup menu into a dialog box.

DialogAddStaticPulldown uses the pointer Popup to a static pre-filled popup menu structure (popup menus and dialog pulldowns are in fact the same structure) and adds this pulldown menu to the dialog structure associated with the handle Handle at the position (x,y), where the coordinates are relative to the top-left corner of the dialog box.

label is the label which will appear in front of the popup menu (or "" if you don't want any name), and Popup is a prefilled static popup structure (i.e. you must write this popup in your source code; for dynamic pop-ups use DialogAddPulldownEx) of the associated menu. See menus.h for more info about creating static popups. The text must fit into one line of the dialog box.

The parameter index determines where the result value of executing the pulldown menu will be stored, and also indicates what the initially selected option will be. See DialogDo for information on how and where the result values are actually stored.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

DialogAddStaticPulldown works like DialogAddPulldownEx, but only accepts a static pre-filled dialog Popup instead of a handle.

The parameter flags can be a combination of the following, defined in the DialogFlags enumeration:
DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region.
DF_SKIP | This item is skipped when browsing through items with the arrow keys.
DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box.
DF_TAB_ELLIPSES | Lines the item up on the right side of the dialog, and draws '......' between the item and its label. This flag is used in the TIOS 'MODE' dialog, for example. It is the default on AMS 1.xx.
DF_TAB_SPACES | AMS 2.00 or higher: Like DF_TAB_ELLIPSES, but does not draw any dots.
DF_POPUP_RADIO | AMS 2.00 or higher: If this flag is set, the item looks like a normal pulldown menu that you can select, but when you press the right arrow key, it does not pop up as usual, but returns control to the dialog callback function. This enables the programmer to do whatever he/she wants. For example, in the 'MODE' dialog, setting custom units pops up another dialog instead of a pulldown menu.

DialogAddStaticPulldown returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddStaticPulldown is in fact a macro created for your convenience. It calls DialogAdd with D_POPUP as the ItemType parameter.

Uses: DialogAdd


DialogAddText

DialogAddText Function (Macro)
dialogs.h

HANDLE DialogAddText (HANDLE Handle, short x, short y, const char *text);

Adds a text into a dialog box.

DialogAddText works exactly as DialogAddTextEx, but doesn't have the flags parameter available. This routine is in fact a macro using DialogAdd with D_TEXT passed as a command and zero passed as the flags. All the parameters are explained in DialogAddTextEx.

Uses: DialogAdd


DialogAddTextEx

DialogAddTextEx Function (Macro)
dialogs.h

HANDLE DialogAddTextEx(HANDLE Handle, short flags, short x, short y, const char *text);

Adds a text, an image, or a custom item into a dialog box.

DialogAddTextEx gives two possibilities:

The first one (if, as is the case of DialogAddText, the flags parameter doesn't contain the DF_OWNER_DRAW flag) is to add the text text to the dialog structure associated with the handle Handle at the position (x, y), where the coordinates are relative to the top-left corner of the dialog box.

The second possibility (when the flags parameter contains the DF_OWNER_DRAW flag) is that DialogAddText can add any kind of item to the dialog structure associated with the handle Handle at the position (x, y), where the coordinates are relative to the top-left corner of the dialog box. (This position can later be ignored so owner draw items will not necessarily have to stick to this position.) You can create every kind of item you wish with this function (such as text, buttons, bitmaps...) as far as you create a callback function (see DialogNew for more details on the CallBack function). See the DF_OWNER_DRAW flag below for more information.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

The parameter flags can be a combination of the following, defined in the DialogFlags enumeration (DF_OWNER_DRAW is very important as it can increase the numbers of possible items in dialogs):
DF_SCROLLABLE | Set this flag if you want this item to be scrollable in a scroll region.
DF_SCREEN_SAVE | The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box.
DF_OWNER_DRAW | AMS 2.00 or higher: The callback function (see DialogNew for more information) is responsible for drawing this item (which can be text, an image, or anything else). The parameters text, x and y will in this case be ignored. This can only be done if the dialog was created with DialogNew and not DialogNewSimple. If the DF_OWNER_DRAW flag is set, then the callback is passed the item identification number and a pointer to an OWNER_DRAW_STRUCT structure. The first value Item in this structure is a direct pointer to the DIALOG_ITEM structure for the item to be drawn. The second value pW is a pointer to the WINDOW structure for the dialog box. Using this pointer, the callback can draw anything and anywhere to the dialog box (all clipped to the dialog box window).

Note: By default, the DF_SKIP flag is set whenever you try to create text or owner draw items so you will not be able to focus on them.

DialogAddTextEx returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddTextEx is in fact a macro created for your convenience. It calls DialogAdd with D_TEXT as the ItemType parameter. Note that DialogAddTextEx is the same macro as DialogAddText except for the parameter flags which is always set to zero in DialogAddText.

Uses: DialogAdd


DialogAddTitle

DialogAddTitle Function (Macro)
dialogs.h

HANDLE DialogAddTitle (HANDLE Handle, const char *title, short left_button, short right_button);

Adds a title bar and up to two buttons into a dialog box.

DialogAddTitle works exactly as DialogAddTitleEx, but doesn't have the flags parameter available. This routine is in fact a macro using DialogAdd with D_HEADER passed as a command and zero passed as the flags. All the parameters are explained in DialogAddTitleEx.

Uses: DialogAdd


DialogAddTitleEx

DialogAddTitleEx Function (Macro)
dialogs.h

HANDLE DialogAddTitleEx (HANDLE Handle, short flags, const char *title, short left_button, short right_button);

Adds a title/header bar and up to two buttons into a dialog box. Extended version.

DialogAddTitleEx adds a title/header bar with the text title and up to two buttons to the dialog structure associated with the handle Handle.

The parameters left_button and right_button determine the type of the left and right buttons which eventually will appear at the bottom of the dialog box (by giving BT_NONE as the parameter, you can skip adding a button). The set of possible buttons is very limited. See DlgMessage for information about possible types. If you wish to have buttons without having a title bar, then you must use an owner draw item (see DialogAddTextEx and the explanation on owner draw items given with DialogNew for more information).

The parameter flags can be zero or DF_SCREEN_SAVE if you wish the dialog code to save the area underneath the dialog box when it is started, DB_MEMFULL is returned if it cannot. Note that if you use this flag, the title item must be the first one to be created. These flags are defined in the DialogFlags enumeration.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

DialogAddTitleEx returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddTitleEx is in fact a macro created for your convenience. It calls DialogAdd with D_HEADER as the ItemType parameter. Note that DialogAddTitleEx is the same macro as DialogAddTitle except for the parameter flags which is always set to zero in DialogAddTitle. In both functions, zero is passed to the x and y parameters. (These parameters are ignored when you use D_HEADER as the ItemType.)

Uses: DialogAdd


DialogAddXFlags

DialogAddXFlags Function (Macro)
AMS 2.00 or higher dialogs.h

HANDLE DialogAddXFlags (HANDLE Handle, short flags, unsigned short xFlags1, unsigned short xFlags2, unsigned short xFlags3, unsigned short xFlags4);

Adds extended dialog properties into a dialog box.

DialogAddXFlags adds extended dialog properties to the dialog structure associated with the handle Handle.
The XFLAGS item defines an array of four extended unsigned short flags (i.e. xFlags1, xFlags2, xFlags3, xFlags4.) Currently only xFlags1 is used: the three remaining values should always be set to zero for future compatibility.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

The parameter xFlags1 may contain a combination of the following flags, defined in the DialogXFlags enumeration:
XF_ALLOW_VARLINK | Setting this extended xflag allows all EDIT (=request) items in the dialog box to allow the [VAR-LINK] key to be activated within the dialog box and to paste results to the edit item. If this xflag or XF_VARLINK_SELECT_ONLY is not set, then when [VAR-LINK] is pressed in a dialog box, the dialog will be closed and VAR-LINK will be activated.
XF_NO_ALPHA_LOCK | On the TI-89, Alpha-Lock is turned on for all dialog boxes with edit items. Setting this extended xflag disables this feature.
XF_VARLINK_SELECT_ONLY | This xflag is similar to XF_ALLOW_VARLINK except thet the user may not make any variable changes inside VAR-LINK (like deleting, copying, renaming, or locking variables).
XF_TE_REPAINT | This xflag is unknown for the moment. Do not use.

The parameter flags can be zero or DF_SCREEN_SAVE if you wish the dialog code to save the area underneath the dialog box when it is started and to return DB_MEMFULL if it cannot. Note that if you use this flag, the item must be the first one to be created. These flags are defined in the DialogFlags enumeration.

DialogAddXFlags returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddXFlags is in fact a macro created for your convenience. It calls DialogAdd with D_XFLAGS as the ItemType parameter and with zero passed to the x and y parameters. (These parameters are ignored when you use D_XFLAGS as the ItemType.)

Uses: DialogAdd


DialogDo

DialogDo Function (ROM Call 0x32)
dialogs.h

short DialogDo (HANDLE Handle, short x, short y, char *RequestBuffer, short *PulldownBuffer);

Activates and shows a dialog box.

DialogDo activates and shows on the screen the dialog associated with handle Handle. The top-left corner of the dialog will be at the position (x, y), where coordinates are absolute screen coordinates. x, y or both may also have a special value CENTER which means "center the dialog on the screen in x, y or both directions". DialogDo returns KEY_ENTER or KEY_ESC, depending on whether the user exits the dialog by pressing ENTER or ESC key (note that structures pointed to by RequestBuffer and PulldownBuffer will be modified regardless of whether the user exits the dialog by pressing ENTER or ESC). It also may return a negative number in a case of error (e.g. not enough memory to display the dialog box). After the execution is finished, the original content of the screen will be restored. This routine may cause heap compression.

Parameter RequestBuffer is the pointer to the buffer where character entered into request boxes will be stored. This buffer may store more than one string; the characters entered into a request box will be stored starting from address RequestBuffer + offset, where offset is the parameter given with the DialogAddRequest command which created this request box. Each stored string will be zero terminated. This buffer may be pre-filled with the initial content which will appear in request boxes. Namely, initial content of any request box will be a sequence of characters starting from address RequestBuffer + offset up to the first zero ('\0') character (where offset is the parameter given when the request box is created). If the dialog does not contain any request boxes, RequestBuffer may be NULL.

Parameter PulldownBuffer is the pointer to the buffer where return values of execution of pulldown menus will be stored. This buffer is, in fact, an array of integers; the return value of executing a pulldown menu will be stored in PulldownBuffer[index], where index is the parameter given with the DialogAddPulldown command which created this pulldown menu. This array may be pre-filled with the ordinal numbers of initial option in pulldown menus. Namely, initially selected option content of any pulldown menu will be an option with ordinal number PulldownBuffer[index] (where index is the parameter given when the pulldown menu was created). If the dialog does not contain any pulldown menus, PulldownBuffer may be NULL.

Here is a concrete example (called "Dialog Test"), which creates a dialog which asks the user for his name, then displays a message box with a greeting message in which the user's name is included, except if the user pressed the ESC key:

// Display a simple dialog box and let the user enter a name

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 100           // Compile for AMS 1.00 or higher

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

// Main Function
void _main(void)
{
  char buffer[27] = "Hello ";
    // 6 bytes "Hello ", max. 20 bytes name, 1 zero byte
  HANDLE handle = DialogNewSimple (140, 55);
  DialogAddTitle (handle, "EXAMPLE", BT_OK, BT_CANCEL);
  DialogAddText (handle, 3, 20, "Enter name (max. 20 chars)");
  DialogAddRequest (handle, 3, 30, "Your name", 6, 20, 14);
  if (DialogDo (handle, CENTER, CENTER, buffer, NULL) == KEY_ENTER)
    DlgMessage ("GREETINGS", buffer, BT_OK, BT_NONE);
  HeapFree (handle);
}

Uses: Dialog, HeapLock, HeapUnlock
Used by: DlgMessage, VarNew, VarOpen, VarSaveAs, cmd_dialog, cmd_request, EV_defaultHandler, HomeExecute


DialogNew

DialogNew Function (ROM Call 0x34)
dialogs.h

HANDLE DialogNew (short Width, short Height, Dialog_Callback_t Callback);

Creates a new dialog box which can interact with the user program.

DialogNew acts like DialogNewSimple, but accepts a pointer to a user callback function Callback as a third parameter (i.e. you must pass the pointer of a function you wrote in your source code which contains the parameter types defined by Dialog_Callback_t). This function is called more than once during the dialog's execution.

Such a user function allows for interaction between the dialog box and the user program, and permits the creation of dialog boxes which dynamically change their contents during execution. This is a kind of event-driven programming: When an event occurs in the dialog, the Callback function will be called with a specific Message parameter Message that should be processed so as to know what data the parameter Value contains. Events are only sent on a few occasions, which include:

  • when an item in the dialog box is created or recreated;
  • when an item receives the focus;
  • when the user acts on an item. The moment the callback function is called depends on the kind of item (some elements need to call the Callback function when they are activated, some others need to call this function when they return from activation). For example, the callback is called after the user pressed ENTER in a request box or after execution of any pulldown menu.
This function has to return a value, whose meaning also depends on the input Message parameter. However, in simple dialog boxes without any dynamic elements, you may always pass TRUE, which is the same as DB_CONTINUE, i.e. the standard return value. Note that if you do not want to take care of the Callback function at all (i.e. if you do not want to write such a function) you can use the already written NoCallBack function, which does nothing but return TRUE whatever the entering message is (but in that case, the best thing is to use DialogNewSimple, which in fact is a macro using both DialogNew and NoCallBack).

Note that if you choose not to create a CallBack function, some of the items (such as D_MENU) and the DF_OWNER_DRAW flag will not be very useful for you as they need to be handled in the callback function.

The following table shows what the Message value can be, when events occur and what you should return from Callback. The constants are defined in the enum DialogMessages:

A nonnegative value This occurs when the user pressed ENTER to activate an item, or to return from an activated item.
This nonnegative value is in fact the identification number of an item in a dialog. This identification number is created automatically when you use one of the creation functions DialogAdd, DialogAddText, DialogAddPulldown, and all other functions starting with "DialogAdd". A value of 0 represents the first item you created in the dialog box, 1 is the second one, 2 the third one, and so on.
The meaning of the Value parameter depends on the type of the item. See below for a list of possible meanings.
The return value should be a message from the enum DialogMessages:
DB_CONTINUE | Process the key pressed by the user, but do not redraw the dialog box.
DB_REDRAW | Redraw the dialog box and ignore the key pressed by the user.
DB_REDRAW_AND_CONTINUE | Redraw the dialog box, then process the key pressed by the user.
DB_EXIT | You can return this value if you want the dialog box to stop its execution immediately.
DB_QACTIVE Query the status of an item (enabled/disabled).
This occurs whenever an item in the dialog box is created, gets the focus, or whenever the dialog box needs to update the state of the item. In this case, the value passed through Value is the identification number of an item in the dialog (0 for the first one, 1 for the second one, and so on). You should return TRUE if the item is enabled and should not be grayed out, or FALSE if the item is disabled and must be grayed out). Note that static items such as D_TITLE and D_TEXT are not even drawn if they are disabled.
DB_GET_TITLE Query the title of a dynamic header.
This event occurs when a special title bar which may be added to the dialog using DialogAdd with ItemType set to D_DYNHEADER is created. The Value parameter will be zero, and the callback function must return the text for the title of the dialog box.
Note: as statically created dynamic titles are not known very well for the moment, in most cases you do not have to care about this value.
DB_GET_EDIT_HANDLE Query the text buffer of a dynamic edit field.
This event occurs when a special request box which may be added to the dialog using DialogAdd with ItemType set to D_HEDIT (or using DialogAddDynamicRequest) is created or gets the focus. The value contained in Value is the identification number of this edit box item in the dialog. The callback function must return a handle which points to a buffer from where this request box will get its initial value, and where the contents of the request box will be stored. You may need the HeapAlloc function to get a new handle and HeapDeref to access the associated buffer (see the example below).
Note: See DialogAddDynamicRequest for more details about this special feature.

The following table shows what the Value parameter is if Message is a nonnegative value, depending on the item type:

Pulldown | If the item identified by Message is a pulldown menu (i.e. if this item has been created using DialogAddPulldown or DialogAddPulldownEx, or DialogAdd with ItemType set to D_POPUP, D_HPOPUP or D_DYNPOPUP), the value contained in Value is the identification number of the item selected in the pulldown menu (not one of a dialog item). The event occurs only when the user selects an item and presses ENTER.
Request | If the item identified by Message is a request item (i.e. if this item has been created using DialogAddRequest or DialogAddRequestEx, or DialogAdd with ItemType set to D_HEDIT or D_EDIT_FIELD), the value contained in Value is a pointer pointing to the data the user just entered.
Menu If the item identified by Message is a menu (i.e. if this item has been added using DialogAddMenu or DialogAdd with ItemType set to D_MENU), the value contained in Value is in fact the composition of two values: the 16 most significant bits (the high word) of Value contain the execution handle of the menu (the dialog box code calls MenuBegin initially to get a handle for the menu) and the 16 least significant bits (the low word) contain the key pressed by the user to activate the menu (for your convenience, common key values are defined in the CommonKeys enum). The macros LO_WORD and HI_WORD have been created to get both values easily. The callback function may activate the menu or change anything in it if needed. See MenuKey for more details on activating a menu.
Note: The return value of a menu differs from that of any other element: Returning a positive value will select (focus on) the dialog item whose identification number is equal to the value you returned. (This feature is mainly used in the TIOS 'MODE' dialog where pressing F1, F2 or F3 changes the page displayed, which is achieved by changing the focus.) With AMS 2.xx the return value can also be one of DB_REDRAW, DB_REDRAW_AND_CONTINUE or DB_EXIT, but not DB_CONTINUE, since that value is positive.
Owner Draw Text | If the item identified by Message is an owner draw text/image (i.e. if this item has been created using DialogAdd with ItemType set to D_TEXT and Flags containing DF_OWNER_DRAW), the value contained in Value is a pointer to an OWNER_DRAW_STRUCT structure. The Item field in this structure is a direct pointer to the DIALOG_ITEM structure for the item to be drawn (this is not normally used). The pW field is a pointer to the WINDOW structure for the dialog box. Using this pointer, the callback function can draw anything anywhere to the dialog box (clipped to the window of the dialog box). For example, you can draw simple text using the WinStrXY function, or draw a standard button using DrawStaticButton, or a bitmap using WinBitmapPut, etc. In general, you will be able to use any of the functions from wingraph.h.

All other item types cannot be activated; Callback will not be called with their identification number as the Message parameter.

After pressing ENTER in a request box or after execution of a pulldown menu, the DB_QACTIVE message will be sent to all items in the dialog. This permits the user to create dialogs in which the selection of various options in pulldown menus enables or disables some other items.

Note: It might be useful for you to know that dereferencing the handle returned by DialogNew with HeapDeref or with HLock returns a pointer to the dialog's DIALOG structure.

Uses: HeapAlloc, memset
Used by: DialogNewSimple, DlgMessage, VarNew, VarOpen, VarSaveAs, cmd_dialog, cmd_request, EV_defaultHandler, HomeExecute

See also: DialogDo, Dialog, DialogAdd, DIALOG


DialogNewSimple

DialogNewSimple Function (Macro)
dialogs.h

HANDLE DialogNewSimple (short width, short height);

Creates a new dialog box.

DialogNewSimple allocates memory for a dialog box with dimensions width x height, initializes allocated block with necessary structures and returns a handle to it (or H_NULL in case of error). This routine may cause heap compression. DialogNewSimple in fact calls DialogNew with NoCallBack as third parameter.

Note: You can later free the memory by calling HeapFree.

Uses: DialogNew, NoCallBack


DlgMessage

DlgMessage Function (ROM Call 0x1B4)
dialogs.h

short DlgMessage (const char *title, const char *message, short left_button, short right_button);

Displays a message dialog box.

DlgMessage displays a message dialog box, where title is the title string (pass NULL for no title), and message is the content of the message. Both title and message must fit into one screen line, else the calculator will crash (however, on AMS 2.xx, a long message will simply be wrapped in the dialog box). Parameters left_button and right_button determine the type of the left and right buttons which will appear at the bottom of the dialog box. The set of possible buttons is very limited, and possible types are defined in enum Buttons (any other values will cause a crash). The meanings of these constants are:

BT_NONE | No button at all
BT_OK | Button "Enter=OK"
BT_SAVE | Button "Enter=SAVE"
BT_YES | Button "Enter=YES"
BT_CANCEL | Button "Esc=CANCEL"
BT_NO | Button "ESC=NO"
BT_GOTO | Button "Enter=GOTO"

DlgMessage returns KEY_ENTER or KEY_ESC, depending on whether the user exits the dialog by pressing the ENTER or ESC key. This routine may cause heap compression.

Uses: DialogAdd, DialogDo, DialogNew, HeapAlloc, HeapFree, HeapFreeIndir, GKeyIn, strcat, strncpy, ERD_dismissNotice, ERD_notice, ROM Call 0x4D5
Used by: cmd_showstat, cmd_text, EV_defaultHandler, handleVarLinkKey, TE_handleEvent, EV_quit, SymFindPtr


HI_WORD

HI_WORD Function (Macro)
dialogs.h

short HI_WORD(long);

Returns the high word from a long value.

This function returns the highest short value (the 16 most significant bits) of a long value. This macro function was created for DialogNew.


LO_WORD

LO_WORD Function (Macro)
dialogs.h

short LO_WORD (long);

Returns the low word from a long value.

This function returns the lowest short value (the 16 least significant bits) of a long value. This macro function was created for DialogNew.


NoCallBack

NoCallBack Function (tigcc.a)
dialogs.h

short NoCallBack (short Message, long Value);

Dummy callback function doing nothing.

NoCallBack is a dummy function which does nothing, and always returns 1 as result. The purpose of this function lies in the fact that it may be given as a third parameter to the function DialogNew, when there is no need for an interaction with the user program during the execution of the dialog (i.e. no "calling back"). DialogNewSimple does exactly this: it calls DialogNew with NoCallBack as a third parameter.

Note: This routine was in TIOS jump table up to AMS 1.xx. In AMS 2.xx it is not in the jump table! Here, NoCallBack is implemented on such whay that it can be used on any version of AMS.

Used by: DialogNewSimple


VarNew

VarNew Function (ROM Call 0x28E)
dialogs.h

HSym VarNew (const ESQ *FileTypes, ...);

Displays the standard "New" dialog.

VarNew implements the standard "New" dialog. The user may select a type to create as well as the folder to create the new variable in, and then may type in a variable name.

FileTypes is a pointer to a zero-terminated array of types that are supported (see VarOpen for more info). VarNew returns the HSym descriptor of the newly created symbol, or H_NULL if the user presses 'ESC' or in case of an error.

This function may cause heap compression.

Uses: DialogAdd, DialogDo, DialogNew, HeapFree, ER_catch, ER_success, ERD_dialog, TokenizeSymName, top_estack, memset, PopupAddText, PopupNew, PopupText, VarCreateFolderPopup, strcat, strlen, XR_stringPtr, DataTypeNames, FirstNonblank, VarOptList, VarSaveTitle, FindSymInFolder, StrToTokN, SymSysVar, VarStore

See also: VarOpen, VarSaveAs


VarOpen

VarOpen Function (ROM Call 0x28C)
dialogs.h

HSym VarOpen (const ESQ *FileTypes, ...);

Displays the standard "Open" dialog.

VarOpen implements the standard "Open" dialog. The user may select a type, the folder to look in, and finally a symbol in the selected folder which matches the selected type.

FileTypes is a pointer to a zero-terminated array of types that are supported. These types are, in fact, tags (see the Tags enum for more info). Supported tags are: EQ_TAG (expression), STR_TAG (string), LIST_TAG (list), MATRIX_TAG (matrix), PRGM_ITAG (program), FUNC_ITAG (function), DATA_TAG (data), GDB_TAG (Graph Database), PIC_TAG (picture), TEXT_TAG (text), FIG_TAG (geometry figure), MAC_TAG (geometry macro), ASM_TAG (assembly program), and OTH_TAG (custom-type file). Each value in the FileTypes list will be presented to the user in a pulldown menu, unless there is only one value in the list (then it will be a static field).

VarOpen returns the HSym descriptor of the selected symbol, or HS_NULL if the user pressed 'ESC' or in case of an error.

If the FileTypes list contains OTH_TAG items, an extra parameter of type char ** is required. This parameter is an array of strings (more precisely, of char pointers). There must be exactly one char pointer for each OTH_TAG item in the FileTypes list, and these pointers should point to the text to display in the pulldown menu for these custom types.

This function may cause heap compression.

Uses: DialogAdd, DialogDo, DialogNew, HeapFree, TokenizeSymName, top_estack, PopupAddText, PopupClear, PopupNew, PopupText, VarCreateFolderPopup, strcat, strchr, strcmp, strlen, XR_stringPtr, DataTypeNames, VarOptList, CheckSysFunc, FolderOp, GetFuncPrgmBodyPtr, StrToTokN, SymCpy0, SymFindFirst, SymFindNext, SymSysVar, VarRecall, ROM Call 0x3E8
Used by: GT_Open

See also: VarNew, VarSaveAs


VarSaveAs

VarSaveAs Function (ROM Call 0x28D)
dialogs.h

HSym VarSaveAs (const ESQ *FileTypes, const char *TitleSym, ...);

Displays the standard "Save Copy As" dialog.

VarSaveAs implements the standard "Save Copy As" dialog. The user may select a type as well as the folder to save the symbol in, and finally has to enter the symbol name.

FileTypes is a pointer to a zero-terminated array of types that are supported (see VarOpen for more info). TitleSym is a string that will be placed in the title of the dialog box (the title will have the form "SAVE COPY OF TitleSym AS"). Alternatively, TitleSym may be NULL if no such title is wanted.

VarSaveAs returns the HSym descriptor of the newly created symbol, or H_NULL if the user pressed 'ESC' or in case of an error. This function is essentially the same as VarNew, only the different dialog type is used.

This function may cause heap compression.

Uses: DialogAdd, DialogDo, DialogNew, HeapFree, ER_catch, ER_success, ERD_dialog, TokenizeSymName, top_estack, memset, PopupAddText, PopupNew, PopupText, VarCreateFolderPopup, strcat, strlen, XR_stringPtr, DataTypeNames, FirstNonblank, VarOptList, VarSaveTitle, FindSymInFolder, StrToTokN, SymSysVar, VarStore
Used by: GT_SaveAs

See also: VarNew, VarOpen


CENTER

CENTER Constant
dialogs.h, menus.h

#define CENTER (-1)

A constant to describe a centered position for dialogs.

When used in the DialogDo or PopupDo command as a parameter, CENTER means "center the dialog or popup menu on the screen in x, y or both directions," depending on which parameter CENTER is used as.


DialogMessages

DialogMessages Constant (Enumeration)
dialogs.h

enum DialogMessages {
DB_CONTINUE =1, DB_MEMFULL = -1, DB_QACTIVE = -2, DB_REDRAW = -3, DB_REDRAW_AND_CONTINUE = -4, DB_UNKNOWN = -5,DB_GET_EDIT_HANDLE = -6, DB_GET_TITLE = -7, DB_EXIT = -8
};

An enumeration to describe messages used by a Dialog's Callback.


Buttons

Buttons Type (Enumeration)
dialogs.h, wingraph.h

enum Buttons {BT_NONE = 0, BT_OK = 1, BT_SAVE = 2, BT_YES = 3, BT_CANCEL = 4, BT_NO = 5, BT_GOTO = 6};

An enumeration to describe possible button types.

Describes the button types used in DlgMessage.


Dialog_Callback_t

Dialog_Callback_t Type (Pointer)
dialogs.h

typedef CALLBACK short (*Dialog_Callback_t) (short Message, long Value);

Callback function type for dialogs.

Dialog_Callback_t is used in DialogNew and in the DIALOG structure to provide a callback mechanism for events in the dialog box.

Deprecated alias: DialogNew_t


Dialog_GetHandle_t

Dialog_GetHandle_t Type (Pointer)
dialogs.h

typedef CALLBACK HANDLE (*Dialog_GetHandle_t) (short ID);

Callback function type returning a handle for a dialog item.

Dialog_GetHandle_t is used in DialogAddDynamicPulldown to let the program generate the menu handle on demand.


DIALOG_ITEM

DIALOG_ITEM Type (Structure)
dialogs.h

typedef struct {
unsigned char Type;
unsigned char Flags;
unsigned char x0, y0;
union {
struct {
void *Menu;
unsigned char MaxMenuWidth;
} dMenu;
struct {
short oText;
void *PopUp;
unsigned short oIndex;
} dPopUp;
struct {
short oText;
HANDLE (*GetPopUp)(unsigned short);
unsigned short oIndex;
} dDynPopUp;
struct {
short oText;
HANDLE hPopUp;
unsigned short dummy;
unsigned short oIndex;
} dHPopUp;
struct DEditType {
short oText;
unsigned short bOffset;
unsigned short Flen;
unsigned char Dlen;
} dEdit;
struct {
short oText;
} dText;
struct {
short oText;
unsigned char lButton, rButton;
} dHeader;
struct {
short oIcon;
} dIcon;
struct {
unsigned char x1, y1;
unsigned char Index0, Index1;
unsigned char NumDspFields, TotNumFields;
unsigned char FieldHeight;
} dScrollR;
struct {
unsigned short xFlags[4];
} dFlags;
} f;
} DIALOG_ITEM;

A scructure for defining dialog items.

This is the structure that defines an item in a DIALOG structure.

Note: To declare an Item of type D_END, which is all zeros, you can write:

DIALOG_ITEM empty={.f={}};

Deprecated alias: DIALOG_ITEMS

See also: DIALOG, DialogAdd, SIZED_DIALOG, DialogTypes


DIALOG

DIALOG Type
dialogs.h

typedef struct {
unsigned short TextOffset;
unsigned short NumItems;
unsigned char Width, Height;
Dialog_Callback_t CallBack;
DIALOG_ITEM Fields[];
} DIALOG;

A scructure for defining dialogs.

DIALOG is the structure to define a pre-filled dialog box, to be used as the first argument to the Dialog function. It enables making a dialog without using DialogNew, DialogAddTitle, and all the other macros that use DialogAdd.

There is a constraint in this structure which cannot be described within a C data type: The last item in the Fields array must be an item of type D_END, and all other fields of this item must be filled with zero.

TextOffset is used to know where the strings that the dialog uses are. Most dialog fields (of type DIALOG_ITEM) have a member oText, which is of type unsigned short as well. For each item, both numbers will be added to the address of the DIALOG structure, and the result must be the address of the string. Offsets are shorts and therefore they cannot be greater than 65535, so having a DIALOG structure on the stack with strings on the heap or vice versa certainly will not work. Even if both the dialog structure and the strings are on the stack, you must be sure that the addresses of all strings are greater than the address of the DIALOG structure; for example because both the DIALOG structure and the strings are contained in a larger structure.

NumItem must be set to the number of items without the terminating D_END item. Width, Height and Callback are the same as the arguments for DialogNew.

For most of the DIALOG_ITEM structures, the structures' members are the same as the arguments used by the corresponding macro made with DialogAdd, just care about using offsets instead of pointers for strings, and add the flag DF_SKIP to ScrollRegions, Menus, Titles and text.

The order in wich you place the items is very important. Usually, the order should be the same as the visual order of the items, because it defines the order in which you move between items with the arrow keys. It also defines each item's identification number, which is passed to the callback function.

Note that this is not really a static structure, since the value of Callback depends on where the program is placed in memory, and the handles or pointers to each pulldown can vary at each execution. If you store this structure as a static structure or in a data file, think about changing the values of pointers and handles each time you execute your program. (The pointer to the callback can be relocated at load time by AMS though.) Also, DIALOG contains a variable-size array of items, and variable-size arrays cannot be initialized with non-constant values. However, a DIALOG instance is usually non-constant. See the SIZED_DIALOG macro, which was created to avoid this problem.

See also: Dialog, DialogAdd, DIALOG_ITEM, DialogNew, SIZED_DIALOG


DialogFlags

DialogFlags Type (Enumeration)
dialogs.h

enum DialogFlags {DF_TAB_ELLIPSES = 0x01, DF_MAX_MENU_WIDTH = 0x01, DF_SCROLLABLE = 0x02, DF_CLR_ON_REDRAW = 0x04, DF_TAB_SPACES = 0x04, DF_OWNER_DRAW = 0x08, DF_POPUP_RADIO = 0x20, DF_SCREEN_SAVE = 0x40, DF_SKIP = 0x80};

An enumeration to describe possible item flags in a dialog box.

This enumeration describes all the possible item flags in a dialog box. See DialogAdd for more informations.


DialogTypes

DialogTypes Type (Enumeration)
dialogs.h

enum DialogTypes {D_END = 0, D_MENU = 1, D_EDIT_FIELD = 2, D_SCROLL_REGION = 3, D_OPTION = 4, D_RADIO = 5, D_BUTTON = 6, D_TEXT = 7, D_HEADER = 8, D_POPUP = 10, D_DYNPOPUP = 11, D_HEDIT = 12, D_DYNHEADER = 13, D_HPOPUP = 14, D_XFLAGS = 15};

An enumeration to describe possible item types in a dialog box.

This enumeration describes all the possible item types in a dialog box. See DialogAdd for more informations.

See also: DialogAdd, DIALOG_ITEM


DialogXFlags

DialogXFlags Type (Enumeration)
AMS 2.00 or higher dialogs.h

enum DialogXFlags {
XF_ALLOW_VARLINK = 0x0001, XF_TE_REPAINT = 0x0002, XF_NO_ALPHA_LOCK = 0x0004, XF_VARLINK_SELECT_ONLY = 0x8001
};

An enumeration to describe possible XFlags in a dialog box.

This enumeration describes all the possible XFlags in a dialog box. See DialogAddXFlags for more informations.


HSym

HSym Type (Structure)
dialogs.h, files.h, graphing.h, vat.h, unknown.h

typedef struct {
HANDLE folder;
unsigned short offset;
} HSym;

A structure representing a symbol reference.

HSym is a structure which contains the handle of the variable table list belonging to the folder in which the symbol is located, and the offset from the beginning of the list to the actual VAT symbol entry of type SYM_ENTRY. These symbol references are used as a safe and efficient method to pass variable references around in the system, so that there are no probems after garbage collection (i.e. the heap compression). In other words, symbol references stay valid even after the heap compression. Note, however, that the references may become invalid whenever a symbol in the same folder is added, removed, or even renamed, since the actual offset of the SYM_ENTRY structure may change during this operation.

You can use the DerefSym function to get a pointer to the actual SYM_ENTRY structure.


OWNER_DRAW_STRUCT

OWNER_DRAW_STRUCT Type (Structure)
dialogs.h

typedef struct {
DIALOG_ITEM *Item;
WINDOW *pW;
} OWNER_DRAW_STRUCT;

A scructure for defining an owner draw item.

This structure defines an owner draw item. A pointer to this structure is given to the callback function when an owner draw item is (re)created. See DialogNew for more informations.


SCR_RECT

SCR_RECT Type (Structure)
dialogs.h, estack.h, events.h, graph.h, kbd.h, statline.h, textedit.h, wingraph.h, unknown.h

typedef union {
struct {
unsigned char x0, y0, x1, y1;
} xy;
unsigned long l;
} SCR_RECT;

A scructure for defining a rectangular area.

SCR_RECT is a structure (more precisely, an union) for defining a rectangular area using physical screen coordinates.

Instead of giving four coordinates x0, y0, x1 and y1, it is possible to give all together using a field l which is a packed long number.

Note: GCC4TI is derived from GNU C, so it allows cast constructors. That's why, constructions like

DrawClipEllipse (50, 50, 30, 20, &(SCR_RECT){{0, 0, 159, 99}}, A_NORMAL);
are legal. See DrawClipEllipse for info about this command.

See also: ScrRect


SCR_STATE

SCR_STATE Type (Structure)
dialogs.h, estack.h, events.h, graph.h, statline.h, textedit.h, wingraph.h, unknown.h

typedef struct {
void *ScrAddr;
unsigned char XMax, YMax;
short CurFont, CurAttr, CurX, CurY;
SCR_RECT CurClip;
} SCR_STATE;

A structure for saving the state of the graphics system.

SCR_STATE is a structure used for saving the state of the graphics system, used in the commands SaveScrState and RestoreScrState.


WINDOW

WINDOW Type (Structure)
dialogs.h, estack.h, events.h, graphing.h, statline.h, textedit.h, wingraph.h, unknown.h

typedef struct WindowStruct {
unsigned short Flags; /* Window flags */
unsigned char CurFont; /* Current font */
unsigned char CurAttr; /* Current attribute */
unsigned char Background; /* Current background attribute */
short TaskId; /* Task ID of owner */
short CurX, CurY; /* Current (x,y) position (relative coordinates) */
short CursorX, CursorY; /* Cursor (x,y) position */
SCR_RECT Client; /* Client region of the window (excludes border) */
SCR_RECT Window; /* Entire window region including border */
SCR_RECT Clip; /* Current clipping region */
SCR_RECT Port; /* Port region for duplicate screen */
unsigned short DupScr; /* Handle of the duplicated or saved screen area */
struct WindowStruct *Next; /* Pointer to the next window in the linked list */
char *Title; /* Pointer to the (optional) title */
SCR_STATE savedScrState; /* Saved state of the graphics system */
unsigned char Reserved[16]; /* Reserved, do not use */
} WINDOW;

The main window-describing structure.

WINDOW is the main window-describing structure which is used in all window-based TIOS functions.


SIZED_DIALOG

SIZED_DIALOG Macro
dialogs.h

#define SIZED_DIALOG(NumbItems,StrLen) struct {
unsigned short TextOffset;
unsigned short NumItems;
unsigned char Width, Height;
Dialog_Callback_t Callback;
DIALOG_ITEM Fields[(NumbItems)+1];
char String[StrLen];
}

A macro to help defining dialogs, it is nearly the same as DIALOG.

There are two main difficulties one encounters using the DIALOG structure:
First there is a variable size array, and variable size arrays can't be initialized with non constant value.
Secondly it doesn't include strings, which should better be placed just after the DIALOG in memory.
SIZED_DIALOG avoids both of these problems: It needs two argument : the number of Items NumbItems and the size of the all the strings together StrLen, and defines a struct from this, wich is the same as DIALOG but with some place for the strings: you can define a dilalog using SIZED_DIALOG(NumbItems,StrLen)={/*Dialog definition*/}. It is done in the given examples. If you use that macro, it will fill to the right number of Item, and If you forget to add an item with type D_END after the last used Item, it is automatically done.

Using SIZED_DIALOG also helps to get the offset of the strings. You can initialize it with offsetof(SIZED_DIALOG(ItemsNum,0),String)


dll.h

dll.h Header File
Header File Index

Declarations for creating and using nostub libraries

Language Extensions
DLL_EXPORTS
Exports symbols from the DLL.
DLL_ID
Defines the DLL identification number.
DLL_IMPLEMENTATION
Ends the DLL interface section.
DLL_INTERFACE
Starts the DLL interface section.
DLL_VERSION
Defines the DLL major and minor version numbers.
Functions
_DLL_call_attr
Constructs a function definition with attributes for a DLL call.
_DLL_call
Constructs a function definition for a DLL call.
_DLL_entry
Returns a pointer to a symbol exported from a DLL.
_DLL_glbvar
Returns a dereferenced pointer to a global variable in a DLL.
_DLL_reference
Returns a pointer to a global variable in a DLL.
LoadDLL
Loads a DLL into memory and prepares it for use.
LoadDLLThrow
Loads a DLL into memory, throwing an error if not successful.
UnloadDLL
Unloads a previously loaded DLL.
Predefined Types
DLL_ErrorCodes
An enumeration to describe possible errors when trying to load a DLL.

See also: How to use DLLs


DLL_EXPORTS

DLL_EXPORTS Language Extension
dll.h

Exports symbols from the DLL.

The DLL_EXPORTS macro is used for defining the list of symbols which will be exported from the DLL. Note that just putting a symbol declaration or a function prototype into the DLL interface section does not mean that this symbol or function will automatically be exported: you need to put the names of all objects which should be exported after the DLL_EXPORTS interface item.

DLL_EXPORTS must be followed by a list of symbols which should be exported from the DLL. It is possible to exports function names, array names, or addresses of global variables (i.e. names of global variables preceded by the address operator '&'). More precisely, all types of pointers may be exported; functions and arrays are always referenced automatically. For example, suppose that the interface section contains the following declarations:

int foofunc (int fooarg1, const char *fooarg2);
char foostring [] = "Foo";
int fooarray [5] = {1, 2, 3, 4, 5};
unsigned short fooglbvar;
Then, to export these symbols from the DLL, use:
DLL_EXPORTS foofunc, foostring, fooarray, &fooglbvar
Each item in the DLL_EXPORTS declaration is assigned an index number, which is important later for importing symbols from the DLL (see _DLL_call, _DLL_call_attr, _DLL_reference, and _DLL_glbvar for info about how to import symbols from the DLL). The first item gets the index number 0, the second gets the index number 1, etc. So, in the above example, foofunc, foostring, fooarray, and fooglbvar get the index numbers 0, 1, 2, and 3, respectively.

DLL_EXPORTS must appear at the very end of the DLL interface section, just after the DLL_VERSION entry, and just before the DLL_IMPLEMENTATION delimiter, which terminates the DLL interface section and starts the implementation section. See DLL_INTERFACE for a detailed layout of the DLL interface structure.

See also: DLL_INTERFACE, _DLL_entry


DLL_ID

DLL_ID Language Extension
dll.h

Defines the DLL identification number.

The DLL_ID macro is used for defining the DLL indentification number. It must be followed by a 32-bit constant unsigned integer, which will be embedded in the DLL image as a part of the internal signature. For example:

DLL_ID 372331723
Later, when a program wants to load the DLL, it passes the expected ID number as a parameter to the LoadDLL function. If the expected and embedded ID numbers are not the same, the DLL is simply ignored (skipped). As LoadDLL searches through all folders for a matching DLL, it is completely legal to have several DLLs with the same name (in different folders) which differ only in their ID numbers.

DLL_ID must appear at the end of the DLL interface section, after all prototypes and global declarations, and just before the DLL_VERSION entry. See DLL_INTERFACE for a detailed layout of the DLL interface structure.

See also: DLL_INTERFACE, LoadDLL


DLL_IMPLEMENTATION

DLL_IMPLEMENTATION Language Extension
dll.h

Ends the DLL interface section.

This macro ends the DLL interface section. Any symbol declared after it cannot be exported from the DLL. Usually, the implementation part contains the bodies of all exported functions, and possible some more (helping) functions. See DLL_INTERFACE for more information about the structure of the interface section.

See also: DLL_INTERFACE


DLL_INTERFACE

DLL_INTERFACE Language Extension
dll.h

Starts the DLL interface section.

The DLL_INTERFACE macro starts the DLL interface section and tells the linker that a DLL image should be produced instead of the standard executable image. The DLL interface section must have the following general layout:

DLL_INTERFACE

// Declarations of global symbols which should be exported,
// and prototypes of functions which should be exported.

DLL_ID identification_number
DLL_VERSION major_version_number, minor_version_number
DLL_EXPORTS list_of_exported_symbols

DLL_IMPLEMENTATION

// Now the implementation follows
In principle, in addition to function prototypes, it is legal to put function implementations in the DLL interface section as well, although this is not a good practice from the aspect of readability and good structuring. So, a well-designed interface should contain only prototypes.

Note that just putting a symbol declaration or a function prototype into the DLL interface section does not mean that this symbol or function will automatically be exported: you need to put the names of all objects which should be exported after the DLL_EXPORTS interface item. Also, note that DLL_IMPLEMENTATION ends the interface section, so any symbol declared after it cannot be exported from the DLL.

See also: DLL_ID, DLL_VERSION, DLL_EXPORTS, DLL_IMPLEMENTATION


DLL_VERSION

DLL_VERSION Language Extension
dll.h

Defines the DLL major and minor version numbers.

The DLL_VERSION macro is used for defining the DLL major and minor version numbers. It must be followed by two 16-bit constant unsigned integers, which represent the major and minor version numbers, respectively. For example:

DLL_VERSION 2,13
Later, when a program wants to load the DLL, it passes the expected major and minor version numbers as parameters to the LoadDLL function. If the expected and actual major version numbers are not the same, or if the expected minor version number is greater than actual minor version number, the DLL is simply ignored (skipped). As LoadDLL searches through all folders for a matching DLL, it is legal to have several DLLs with the same name (in different folders) and with the same ID numbers, but with different version numbers. LoadDLL will load the first DLL found (if any) with a matching name, ID number and major version number, and whose minor version number is greater or equal to the expected minor version number.

DLL_ID must appear at the end of the DLL interface section, just after the DLL_ID entry, and just before the DLL_EXPORTS entry. See DLL_INTERFACE for a detailed layout of the DLL interface structure.

See also: DLL_INTERFACE, LoadDLL


_DLL_call_attr

_DLL_call_attr Function (Macro Constructor)
dll.h

#define _DLL_call_attr(type,args,attr,index) (*(type (* attr) args) _DLL_entry (index))

Constructs a function definition with attributes for a DLL call.

_DLL_call_attr gets a void pointer to the location of the index-th exported symbol of the currently loaded DLL (using _DLL_entry), casts this pointer to a temporarily-defined pointer to a function which returns type, requires args as arguments, and has the attributes defined by attr, and then dereferences it. _DLL_call_attr is very similar to _DLL_call, but allows for defining function attributes, too. For example, suppose that the DLL contains the following declarations in the DLL interface section (see DLL_INTERFACE):

void foo (int, const char *) __attribute__((__regparm__(4)));
int bar (long) __ATTR_STD__;
...
DLL_EXPORTS foo, bar
Then, to 'import' foo and bar from the DLL (assuming that it has been loaded sucessfully using LoadDLL), you should use the following defines:
#define foo _DLL_call_attr (void, (int, const char *), 0, __attribute__((regparm(4))))
#define bar _DLL_call_attr (int, (long), 1, __ATTR_STD__)

See also: _DLL_call, _DLL_reference, _DLL_glbvar, Declaring Attributes of Functions


_DLL_call

_DLL_call Function (Macro Constructor)
dll.h

#define _DLL_call(type,args,index) (*(type(*)args) _DLL_entry (index))

Constructs a function definition for a DLL call.

_DLL_call gets a void pointer to the location of the index-th exported symbol of the currently loaded DLL (using _DLL_entry), casts this pointer to a pointer to a function which returns type and which requires args as arguments, and dereferences it. This macro is usually used for accessing functions exported from the DLL. For example, suppose that the DLL contains the following declarations in the DLL interface section (see DLL_INTERFACE):

void foo (int, const char *);
int bar (long);
...
DLL_EXPORTS foo, bar
Then foo will get the index number 0, and bar will get the index number 1. To call foo from the main program (assuming that the DLL has been loaded sucessfully using LoadDLL) with arguments 123 and "foostr", you can principally do
_DLL_call (void, (int, const char *), 0) (123, "foostr");
But this is awkward, of course. So, to 'import' foo and bar from the DLL, you should use the following defines:
#define foo _DLL_call (void, (int, const char*), 0)
#define bar _DLL_call (int, (long), 1)
Then you can use foo and bar just as normal functions defined in the main program. For example:
foo (123, "foostr");
Principally, _DLL_call is quite similar to _rom_call, which constructs TIOS function calls instead of DLL function calls. But note that index in _DLL_call is an ordinary integer, which is not true for _rom_call.

See also: _DLL_call_attr, _DLL_reference, _DLL_glbvar


_DLL_entry

_DLL_entry Function (Macro)
dll.h

void *_DLL_entry (int index);

Returns a pointer to a symbol exported from a DLL.

_DLL_entry returns a void pointer to the location of the index-th exported symbol of the currently loaded DLL (assuming that it has been loaded sucessfully using LoadDLL). Note that _DLL_entry returns garbage if the DLL is not loaded.

This function is used internally in _DLL_call, _DLL_call_attr, _DLL_reference, and _DLL_glbvar.


_DLL_glbvar

_DLL_glbvar Function (Macro Constructor)
dll.h

#define _DLL_glbvar(type,index) (*(_DLL_reference (type, index)))

Returns a dereferenced pointer to a global variable in a DLL.

_DLL_glbvar gets a void pointer to the location of the index-th exported symbol of the currently loaded DLL (using _DLL_entry), casts this pointer to a pointer of type type, and then dereferences it. As the constructed object is a dereferenced pointer, it is a valid lvalue, so it can be used as a global variable. This macro is usually used for accessing global variables exported by the DLL. For example, suppose that the DLL contains the following declarations in the DLL interface section (see DLL_INTERFACE):

unsigned short foo;
...
DLL_EXPORTS &foo
Then foo will get the index number 0. To 'import' this global variable from the DLL (assuming that the DLL is sucessfully loaded using LoadDLL), you should use the following definition:
#define foo _DLL_glbvar (unsigned short, 0)
Then you can use foo just like a normal global variable. For example:
printf ("%d", foo);
foo = 50;

See also: _DLL_call, _DLL_call_attr, _DLL_reference


_DLL_reference

_DLL_reference Function (Macro Constructor)
dll.h

#define _DLL_reference(type,index) ((type*const) _DLL_entry (index))

Returns a pointer to a global variable in a DLL.

_DLL_reference gets a void pointer to the location of the index-th exported symbol of the currently loaded DLL (using _DLL_entry), then casts this pointer to a constant pointer of type type. This macro is usually used for accessing arrays exported from the DLL. For example, suppose that the DLL contains the following declarations in the DLL interface section (see DLL_INTERFACE):

char foo[] = "FooString";
int bar[5] = {10, 20, 30, 40, 50};
...
DLL_EXPORTS foo, bar
Then foo will get the index number 0, and bar will get the index number 1. To 'import' these two arrays from the DLL (assuming that the DLL has been loaded sucessfully using LoadDLL), you should use the following defines:
#define foo _DLL_reference (const char, 0)
#define bar _DLL_reference (int, 1)
Then you can use foo and bar just like normal arrays defined in the main program. Note that the elements of foo cannot be changed due to the const qualifier in the definition of foo (at least writing to it will trigger a warning). However, you can access the elements of bar. For example:
printf ("%s %d", foo, bar[2]);
bar[2] = 100;
printf (" %d", bar[2]);

See also: _DLL_call, _DLL_call_attr, _DLL_glbvar


LoadDLL

LoadDLL Function (tigcc.a)
dll.h

short LoadDLL (const char *VarName, unsigned long ID, unsigned short Major, unsigned short Minor);

Loads a DLL into memory and prepares it for use.

LoadDLL tries to load a DLL into memory and to prepare it for use. It traverses the complete VAT to find a fitting version of the DLL (so it is not necessary for the DLL to be in the same directory as the main program). The DLLName parameter is the standard ANSI C name of the DLL file which is to be loaded. The ID parameter is a DLL identification number introduced for safety reasons: any file which does not have the extension 'DLL', a valid embedded signature and an embedded identification number which is equal to ID is ignored (the identification number in the DLL itself is set using the DLL_ID entry in the DLL interface section). The parameters Major and Minor are the expected major and minor version numbers of the DLL (the actual major and minor version numbers in the DLL itself are set using the DLL_VERSION macro in the DLL interface section). LoadDLL will refuse to load a DLL if the expected and actual version numbers are not the same, or if the expected minor version number is greater than the actual minor version number. As LoadDLL searches trough all folders for a matching DLL, it is completely legal to have several DLLs with the same name (in different folders), but which differ in their ID numbers or version numbers. LoadDLL will load the first DLL found (if any) with a matching name, ID number and major version number, and whose minor version number is greater or equal to the expected minor version number.

LoadDLL returns one of the following values:

DLL_OK | The DLL was loaded and initialized successfully.
DLL_NOTINGHOSTSPACE | The DLL could not be loaded because the program counter is not in the "ghost space" (the virtual address space where HW2 protections do not take effect). Note that exe-packed programs are always executed in the ghost space; if you do not want to compress your program, you need to define EXECUTE_IN_GHOST_SPACE.
DLL_NOTFOUND | The DLL is not found. This means that either a file with the name DLLName is not found in any folder, or such files exist, but none of them has the correct extension ('DLL'), the correct embedded signature, and the correct identification number (determined by the ID parameter).
DLL_LOCKFAILED | The attempt to lock the DLL in memory has failed due to some strange reason. This error code is very unlikely.
DLL_OUTOFMEM | There is not memory to load the DLL into RAM.
DLL_ALREADYLOADED | There is already another DLL loaded in the RAM. Due to efficiency reasons, only one DLL is allowed to be loaded at the same time. You need to unload the current DLL using UnloadDLL before loading another one. Anyway, using more than one DLL is strongly deprecated if you don't know exactly what you are doing and why you are doing so.
DLL_WRONGVERSION | There is at least one valid DLL file with the name DLLName and with the correct extension, signature, and identification number, but none of them has a major version number which is equal to the expected major number (determined by the Major parameter) and a minor version number which is greater or equal than the expected minor number (determined by the Minor parameter).

Only if LoadDLL returns DLL_OK, it is valid to proceed further and to use functions imported from the DLL. No further checking is done by the functions from the DLL, so your program will definitely crash if you try to call any function from the DLL if LoadDLL has not returned DLL_OK. Also, don't forget to call UnloadDLL when the DLL is not needed any more (usually at the end of the program). So, any program which uses DLLs must have the following code fragment:

if ((status = LoadDLL (DLLName, ID, Major, Minor)) != DLL_OK)
{
  // Perform some kind of error processing
  // and terminate the program in some way
}

// Proceed further

UnloadDLL ();
You may use LoadDLLThrow instead, which throws an error instead of returning an error code, but this means that you cannot determine what caused the problem. As another solution, you may use ER_throw from error.h to throw your own error if loading the DLL fails.

Typically, if you use functions which may throw errors, you can either catch these errors using TRY...ONERR...ENDTRY blocks, or, if you want to pass them on to the AMS, you can use a single TRY...FINALLY...ENDFINAL block:
if ((status = LoadDLL (DLLName, ID, Major, Minor)) != DLL_OK)
{
  // Perform some kind of error processing
  // and terminate the program in some way
}
TRY

  // Proceed further

FINALLY
  UnloadDLL ();
ENDFINAL
Or, using LoadDLLThrow:
LoadDLLThrow (DLLName, ID, Major, Minor);
TRY

  // Proceed further

FINALLY
  UnloadDLL ();
ENDFINAL

Uses: HeapAllocPtr, HeapDeref, HeapGetLock, HeapLock, HeapUnlock, memcmp, strcmp, EX_patch, SymFindFirst, SymFindNext
Used by: LoadDLLThrow

See also: UnloadDLL, LoadDLLThrow, _DLL_call, _DLL_call_attr, _DLL_reference, _DLL_glbvar


LoadDLLThrow

LoadDLLThrow Function (tigcc.a)
dll.h

void LoadDLLThrow (const char *VarName, unsigned long ID, unsigned short Major, unsigned short Minor);

Loads a DLL into memory, throwing an error if not successful.

LoadDLLThrow calls LoadDLL, and throws an error if the result is not DLL_OK. This is useful if you want to display an error message on the Home Screen.

Uses: LoadDLL

See also: LoadDLL, UnloadDLL, error.h


UnloadDLL

UnloadDLL Function (tigcc.a)
dll.h

void UnloadDLL (void);

Unloads a previously loaded DLL.

UnloadDLL unloads the previously loaded DLL and frees the memory used by it. It does nothing if the DLL was not previously loaded. Each program which uses DLLs must execute UnloadDLL at the end, else the memory used by the DLL will not be freed. After unloading the DLL, it is legal to load another DLL. It is even legal to load and unload the same DLL several times in the program (if you know exactly what you are doing and why you are doing so).

Uses: HeapFreePtr

See also: LoadDLL


DLL_ErrorCodes

DLL_ErrorCodes Type (Enumeration)
dll.h

enum DLL_ErrorCodes {DLL_OK, DLL_NOTINGHOSTSPACE, DLL_NOTFOUND, DLL_LOCKFAILED, DLL_OUTOFMEM, DLL_ALREADYLOADED, DLL_WRONGVERSION};

An enumeration to describe possible errors when trying to load a DLL.

This enumeration describes possible values returned from the LoadDLL function. The value DLL_OK means correct loading. All other values indicate that something is wrong. See LoadDLL for the meaning of these codes.


doors.h

doors.h Header File
Header File Index

Basic header file for kernel-mode programming

This header file will be included automatically by default.h if you define the global preprocessor symbol USE_KERNEL.

First, this header file defines a global symbol named DOORS which is used in other header files to indicate kernel mode. Next, it includes default.h to make sure that the basic macros which GCC4TI needs are defined. It also includes a header file called romsymb.h, which overrides some definitions from default.h by referring to external _ROM_CALL_xxx symbols which are converted by the linker.

It contains code for tigcc.a, to support RETURN_VALUE. Finally, it contains some rather complicated macros and asm statements to put data needed for RETURN_VALUE directly into the assembly file.

Functions
_ram_call_addr
Performs a kernel-mode RAM call.
_ram_call
Performs a kernel-mode RAM call with a cast.

See also: How to make a kernel-based program, default.h, nostub.h


_ram_call_addr

_ram_call_addr Function (Macro)
doors.h

#define _ram_call_addr(ind) (&_RAM_CALL_##ind)

Performs a kernel-mode RAM call.

_ram_call_addr returns a void pointer to the location in memory defined by the kernel as RAM call ind.


_ram_call

_ram_call Function (Macro Constructor)
doors.h

#define _ram_call(ind,type) ((type)(&_RAM_CALL_##ind))

Performs a kernel-mode RAM call with a cast.

_ram_call uses _ram_call_addr to get a void pointer to the location in memory defined by the kernel as RAM call ind, and then casts it to the type type. To avoid prescan of ind, _ram_call_addr is written out.


error.h

error.h Header File
Header File Index

Routines for error handling

Language Extensions
ENDFINAL
Terminates a TRY...FINALLY...ENDFINAL block.
ENDTRY
Terminates a TRY...ONERR...ENDTRY block.
FINALLY
Begins the termination handler in a TRY...FINALLY...ENDFINAL block.
ONERR
Begins the error handler in a TRY...ONERR...ENDTRY block.
PASS
Passes on unhandled errors to a higher level.
TRY
Starts a protected block of code.
Functions
ER_catch
Catches an error.
ER_success
Pops the state from the error stack.
ER_throw
Throws an error with a constant number.
ER_throwVar
Throws an error.
ERD_dialog
Displays an error dialog box.
ERD_dismissNotice
Removes the error notice displayed by a prior call to ERD_notice.
ERD_notice
Displays an error notice.
ERD_process
Processes an error.
find_error_message
Returns a TI-Basic error message string.
Global Variables
errCode
Contains the error number in a TRY...ONERR...ENDTRY block.
Predefined Types
Bool
An enumeration to describe true or false values.
ERROR_FRAME
A type designed for capturing a task state.
ErrorCodes
An enumeration containing all error codes.


ENDFINAL

ENDFINAL Language Extension
error.h

Terminates a TRY...FINALLY...ENDFINAL block.

The macro ENDFINAL terminates a TRY...FINALLY...ENDFINAL block. See TRY for more info.

Uses: errCode, PASS


ENDTRY

ENDTRY Language Extension
error.h

Terminates a TRY...ONERR...ENDTRY block.

The macro ENDTRY terminates a TRY...ONERR...ENDTRY block. See TRY for more info.


FINALLY

FINALLY Language Extension
error.h

Begins the termination handler in a TRY...FINALLY...ENDFINAL block.

The macro FINALLY ends the protected block and begins the handler for code which always has to be executed (see TRY for more info). The variable errCode is automatically created in the error handler, and it contains the error number to allow the program to check what caused the error, or 0 if there was no error. This variable is destroyed after the ENDFINAL statement.

Note: The macro FINALLY uses the ER_success function to end the protected block, and ENDFINAL uses PASS to throw the error signaled by errCode a second time.

Here is an example (called "Memory Error"), which demonstrates the use of this macro:

// Allocate memory as long as possible, then throw an error
// All allocated memory will be freed again!

#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 ENABLE_ERROR_RETURN   // Enable Returning Errors to TIOS

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

#define BLOCK_SIZE 1024

void AllocRecursively(void)
{
  void *ptr = malloc_throw (BLOCK_SIZE);
  TRY
    // Could do something with ptr here...
    AllocRecursively ();
    // Could still do something with ptr...
  FINALLY
    free (ptr);
  ENDFINAL
}

// Main Function
void _main(void)
{
  AllocRecursively ();
}

Uses: ER_success


ONERR

ONERR Language Extension
error.h

Begins the error handler in a TRY...ONERR...ENDTRY block.

The macro ONERR ends the protected block and begins the error handler (see TRY for more info). The variable errCode is automatically created in the error handler, and it contains the error number to allow the program to check what caused the error. This variable is destroyed after the ENDTRY statement.

Note: The macro ONERR uses the ER_success function to end the protected block.

Uses: ER_success


PASS

PASS Language Extension
error.h

Passes on unhandled errors to a higher level.

The macro PASS passes on any unhandled errors to a higher level error handler (see TRY for more info). In fact, it executes ER_throwVar with errCode as an argument.

Uses: ER_throwVar, errCode
Used by: ENDFINAL


TRY

TRY Language Extension
error.h

Starts a protected block of code.

TRY, ONERR, ENDTRY, FINALLY, ENDFINAL, and PASS are macros which extend the C language to implement an error handling mechanism which is almost identical to the commonly-used exception handling as well as error handling in TI-Basic.

TRY begins the protected block. It is a macro which is implemented using the ER_catch function. If an error occurs in the protected block, program execution transfers to the block after the ONERR or FINALLY statement.

However, ONERR and FINALLY are entirely different. The ONERR block will not be executed if there was no error, and it is assumed to either handle the error or call PASS. The error is cleared, so if PASS is not called, the execution continues normally after the ENDTRY statement.

FINALLY, on the other hand, is not implemented to handle errors, but instead to create a block of code which will always be executed, regardless of whether there was an error or not. It does not clear the error (or more precisely, ENDFINAL throws it again). This can be used in a function which allocates memory, destroys the contents of the screen, or does something else which always needs cleaning up. If the function throws an error in a protected block, the memory should always be freed again, the screen should be restored, etc. But the error should not be handled at the same time; instead, it must be handled on a higher level (often even in the calling function).

The usage of ONERR is illustrated in the following example:

TRY
  // <protected code>
ONERR
  if (errCode == some_specific_code)
    // <error handler>
  else
    // pass on any unhandled errors to a higher level
    PASS;
ENDTRY
The usage of FINALLY is illustrated in the following example:
TRY
  ...
  // <allocate memory>
  TRY
    // <protected code>
  FINALLY
    // <free the allocated memory>
  ENDFINAL
  ...
ONERR
  // <error handler>
ENDTRY
The variable errCode is automatically created in the error handler, and it contains the error number to allow the program to check what caused the error. This variable will be destroyed after the ENDTRY/ENDFINAL statement.

It is important to say that you must not exit the protected block using goto or return statements, else the error frame will not be removed, so the further behavior of the program will be unpredictable. If you really want to exit from the protected block before its natural end (i.e. before the ONERR or FINALLY statement), call ER_success explicitely to remove the error frame before exiting, i.e. do something like
TRY
  ...
  if (I_really_must_exit_from_here)
  {
    ER_success ();
    return;
  }
  ...
ONERR
  ...
ENDTRY
But in general this is a very bad practice and should be avoided even if it requires some extra code. For example, you can rewrite the code like this:
TRY
  ...
  if (!I_really_must_exit_from_here)
  {
    ...
  }
ONERR
  ...
ENDTRY
if (I_really_must_exit_from_here)
  return;
There is also another possible caveat related to error handling. The TRY macro (or ER_catch, more precisely) saves many of the registers on its execution context stack, since ER_catch needs to simulate a return identical to the return of any normal function. Consequently, when an error is thrown, all variables which reside in registers are reset to their contents before the TRY macro was called. If code in an ONERR or FINALLY block needs the value of a variable set in the TRY block, the code must arrange to make sure the C code optimizer does not put that variable in a register. This can be accomplished by declaring such variables to be volatile. So, remember this rule: Variables changed in a TRY block must be declared volatile if they are referenced in an ONERR or FINALLY block!

If you want to protect the whole program, passing all unhandled errors to the operating system, you can define ENABLE_ERROR_RETURN instead of using a TRY...ONERR...ENDTRY block. See the section Returning Errors for more information.

Uses: ER_catch, errCode


ER_catch

ER_catch Function (ROM Call 0x154)
error.h

short ER_catch (void *ErrorFrame);

Catches an error.

ER_catch sets up an error handler. It saves the task state in ErrorFrame, which is usually a buffer of type ERROR_FRAME, and returns 0. The state consists of the values of A2-A7, D3-D7, and PC. It also records a pointer to the previously saved state, which makes it a linked list/stack, and yet another two system pointers.

If ER_throwVar is called later on (note that some TIOS routines may perform ER_throwVar in a case of error), it simulates a return from the previously called ER_catch, and the error code passed into ER_throwVar will become the result of ER_catch. The processor must be in User mode for this to work properly.

Note: Usually you should not call this function explicitely. Use the TRY macro instead.

Uses: NG_control, NG_such_that_index
Used by: ERD_dialog, ERD_process, TRY, HeapAllocESTACK, HeapWalk, cmd_blddata, cmd_circle, cmd_cubicreg, cmd_custom, cmd_dialog, cmd_disp, cmd_disptbl, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_expreg, cmd_get, cmd_input, cmd_inputstr, cmd_linetan, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_newdata, cmd_newpic, cmd_newprob, cmd_onevar, cmd_output, cmd_pause, cmd_popup, cmd_powerreg, cmd_prompt, cmd_quadreg, cmd_quartreg, cmd_request, cmd_send, cmd_sendcalc, cmd_sendchat, cmd_shade, cmd_showstat, cmd_sinreg, cmd_slpline, cmd_sorta, cmd_sortd, cmd_toolbar, cmd_try, cmd_twovar, did_push_anti_deriv, push_1st_derivative, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_lim, push_ln, push_log10, push_max, push_min, push_nsolve, push_red_row_ech, push_row_echelon, push_simult, push_sin2, push_sinh, push_solve, push_str_to_expr, push_summation, push_tan, push_tanh, push_zeros, push_dot_exponentiate, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_substitute_simplify, push_substitute_using_such_that, push_sum, Dialog, VarNew, VarSaveAs, display_statements, NG_approxESI, NG_execute, NG_graphESI, NG_rationalESI, NG_RPNToText, NG_tokenize, Parse1DExpr, Parse2DExpr, Parse2DMultiExpr, push_internal_simplify, push_parse_text, TokenizeSymName, EV_centralDispatcher, EV_defaultHandler, EV_sendEventSide, handleRclKey, handleVarLinkKey, MO_modeDialog, FOpen, GD_Text, GR3_paint3d, GR3_xyToWindow, gdb_recall, HomeExecute, HomePushEStack, HomeStorePair, LIO_Receive, OSLinkCmd, CTypeTable, atof, are_units_consistent, de_initRes, de_loop, did_push_approx_inflection_point, did_push_var_val, does_push_fetch, dv_create_graph_titles, EV_quit, execute_graph_func, get_ub, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_Shade, GM_TanLine, gr_ck_solvergraph, gr_execute_de, gr_execute_seq, GR_Pan, GR3_addContours, GR3_handleEvent, GraphOrTableCmd, GT_CalcDepVals, GT_DE_Init_Conds, GT_DspTraceCoords, GT_Trace, GZ_Fit, index_if_pushed_qquad_info, InitTimeSeq, NG_setup_graph_fun, push_ans_entry, push_format, push_gcd_then_cofactors, push_make_proper, push_parse_prgm_or_func_text, push_simplify, push_sq_matrix_to_whole_number, push_user_func, recall_data_var, Regraph, replace_top_with_post_simplified, run_one_seq, seqWebInit, SP_Define, spike_in_editor, spike_optionD, spike_titles_in_editor, time_loop, tokenize_if_TI_92_or_text, VarStoreLink, FolderDel, FolderRename, HSymDel, SymFindFolderName, ROM Call 0x3CD, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x438, ROM Call 0x455, ROM Call 0x45B, ROM Call 0x45E, ROM Call 0x46F, ROM Call 0x486, ROM Call 0x494, ROM Call 0x495, ROM Call 0x4E6, DateAndTime_SetDlg

See also: TRY, ONERR, ENDTRY, FINALLY, ENDFINAL, ER_throwVar, ER_throw, ER_success


ER_success

ER_success Function (ROM Call 0x155)
error.h

void ER_success (void);

Pops the state from the error stack.

ER_success pops the state previously saved by ER_catch off the stack, i.e. removes the error frame from the linked list. You usually will not call this function explicitely: the macro ONERR will do this for you.

Used by: ERD_dialog, ERD_process, FINALLY, ONERR, HeapAllocESTACK, cmd_blddata, cmd_circle, cmd_cubicreg, cmd_custom, cmd_dialog, cmd_disp, cmd_disptbl, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_expreg, cmd_get, cmd_input, cmd_inputstr, cmd_linetan, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_newdata, cmd_newpic, cmd_newprob, cmd_onevar, cmd_output, cmd_pause, cmd_popup, cmd_powerreg, cmd_prompt, cmd_quadreg, cmd_quartreg, cmd_request, cmd_send, cmd_sendcalc, cmd_sendchat, cmd_shade, cmd_showstat, cmd_sinreg, cmd_slpline, cmd_sorta, cmd_sortd, cmd_toolbar, cmd_try, cmd_twovar, did_push_anti_deriv, push_1st_derivative, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_lim, push_ln, push_log10, push_max, push_min, push_nsolve, push_red_row_ech, push_row_echelon, push_simult, push_sin2, push_sinh, push_solve, push_str_to_expr, push_summation, push_tan, push_tanh, push_zeros, push_dot_exponentiate, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_substitute_simplify, push_substitute_using_such_that, push_sum, Dialog, VarNew, VarSaveAs, display_statements, NG_approxESI, NG_execute, NG_graphESI, NG_rationalESI, NG_RPNToText, NG_tokenize, Parse1DExpr, Parse2DExpr, Parse2DMultiExpr, push_internal_simplify, push_parse_text, TokenizeSymName, EV_defaultHandler, EV_sendEventSide, handleRclKey, handleVarLinkKey, MO_modeDialog, FOpen, GD_Text, GR3_paint3d, GR3_xyToWindow, gdb_recall, HomeExecute, HomePushEStack, HomeStorePair, LIO_Receive, OSLinkCmd, CTypeTable, atof, are_units_consistent, de_initRes, de_loop, did_push_approx_inflection_point, did_push_var_val, does_push_fetch, dv_create_graph_titles, EV_quit, execute_graph_func, get_ub, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_Shade, GM_TanLine, gr_ck_solvergraph, gr_execute_de, gr_execute_seq, GR_Pan, GR3_addContours, GR3_handleEvent, GraphOrTableCmd, GT_CalcDepVals, GT_DE_Init_Conds, GT_DspTraceCoords, GT_Trace, GZ_Fit, index_if_pushed_qquad_info, InitTimeSeq, NG_setup_graph_fun, push_ans_entry, push_format, push_gcd_then_cofactors, push_make_proper, push_parse_prgm_or_func_text, push_simplify, push_sq_matrix_to_whole_number, push_user_func, recall_data_var, Regraph, replace_top_with_post_simplified, run_one_seq, seqWebInit, SP_Define, spike_in_editor, spike_optionD, spike_titles_in_editor, time_loop, tokenize_if_TI_92_or_text, VarStoreLink, FolderDel, FolderRename, HSymDel, SymFindFolderName, ROM Call 0x3CD, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x438, ROM Call 0x455, ROM Call 0x45B, ROM Call 0x45E, ROM Call 0x46F, ROM Call 0x486, ROM Call 0x494, ROM Call 0x495, ROM Call 0x4E6, DateAndTime_SetDlg


ER_throw

ER_throw Function (Macro)
error.h

void ER_throw (short err_no);

Throws an error with a constant number.

ER_throw works like ER_throwVar, but it produces much shorter code (only 2 bytes). This is done through the Line 1010 (A-Line) emulator, which emulates an assembly opcode for each error number. As a consequence, err_no must be constant.

See also: ER_throwVar, ErrorCodes


ER_throwVar

ER_throwVar Function (ROM Call 0x153)
error.h

void ER_throwVar (short err_no);

Throws an error.

ER_throwVar restores the state previously saved by ER_catch. It then returns in such a way that ER_catch appears to have returned with the value err_no. See the TI-Basic manual for a meaning of the various error codes. ER_throwVar should not be called with a value 0 as err_no. Think of ER_throwVar as a long jump rather than a subroutine call. Execution does not return from the ER_throwVar call.

Note: If you want to use ER_throwVar to bail out to the TIOS from an arbitrary place, you need to define ENABLE_ERROR_RETURN. See the section Returning Errors for more information.

Uses: NG_control, NG_such_that_index
Used by: PASS, cmd_blddata, cmd_circle, cmd_cubicreg, cmd_custom, cmd_dialog, cmd_disp, cmd_disptbl, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_expreg, cmd_get, cmd_input, cmd_inputstr, cmd_linetan, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_movevar, cmd_newdata, cmd_newfold, cmd_newpic, cmd_onevar, cmd_output, cmd_passerr, cmd_pause, cmd_popup, cmd_powerreg, cmd_prompt, cmd_quadreg, cmd_quartreg, cmd_request, cmd_send, cmd_sendcalc, cmd_sendchat, cmd_shade, cmd_showstat, cmd_sinreg, cmd_slpline, cmd_sorta, cmd_sortd, cmd_toolbar, cmd_try, cmd_twovar, did_push_anti_deriv, push_1st_derivative, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_lim, push_ln, push_log10, push_max, push_min, push_nsolve, push_red_row_ech, push_row_echelon, push_simult, push_sin2, push_sinh, push_solve, push_str_to_expr, push_summation, push_tan, push_tanh, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_substitute_simplify, push_substitute_using_such_that, push_sum, Dialog, display_statements, NG_approxESI, NG_execute, NG_graphESI, NG_rationalESI, NG_RPNToText, Parse1DExpr, Parse2DExpr, Parse2DMultiExpr, push_internal_simplify, push_parse_text, TokenizeSymName, EV_defaultHandler, EV_sendEventSide, handleRclKey, handleVarLinkKey, GR3_paint3d, GR3_xyToWindow, gdb_recall, HomeExecute, HomePushEStack, HomeStorePair, getcalc, exp, log, log10, are_units_consistent, de_initRes, de_loop, did_push_approx_inflection_point, did_push_var_val, does_push_fetch, dv_create_graph_titles, EQU_getNameInfo, EV_quit, execute_graph_func, get_ub, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_Shade, GM_TanLine, gr_ck_solvergraph, gr_execute_de, gr_execute_seq, GR_Pan, GR3_addContours, GR3_handleEvent, GraphOrTableCmd, GT_CalcDepVals, GT_DE_Init_Conds, GT_Trace, GZ_Fit, index_if_pushed_qquad_info, InitTimeSeq, next_token, NG_setup_graph_fun, push_ans_entry, push_format, push_gcd_then_cofactors, push_make_proper, push_parse_prgm_or_func_text, push_simplify, push_sq_matrix_to_whole_number, push_user_func, recall_data_var, Regraph, replace_top_with_post_simplified, run_one_seq, seqWebInit, SP_Define, spike_in_editor, spike_optionD, spike_titles_in_editor, tokenize_if_TI_92_or_text, FolderDel, FolderRename, HSymDel, SymFindFolderName, VarStore, ROM Call 0x437, ROM Call 0x438, ROM Call 0x455, ROM Call 0x45B, ROM Call 0x46F, ROM Call 0x494, ROM Call 0x495, ROM Call 0x4E6

See also: ER_throw, ErrorCodes, PASS


ERD_dialog

ERD_dialog Function (ROM Call 0x151)
error.h

short ERD_dialog (short err_no, short prog_flag);

Displays an error dialog box.

ERD_dialog displays an error dialog box with a message corresponding to the error code err_no. See the TI manual for a meaning of the various error codes. ERD_dialog returns TRUE or FALSE, depending of whether the user exits the dialog box by pressing ENTER or ESC key. This routine may cause heap compression.

prog_flag is a flag which may be FALSE or TRUE. Normally, it needs to be FALSE, but when it is TRUE, in addition to the standard button whith message "Esc=CANCEL", another button with message "Enter=GOTO" will be added in the error dialog box. This is mostly useless, but error dialog boxes have this option (TIOS uses this when you break a BASIC program). Note, however, that pressing Enter will not perform the actual transfer to the program editor.

Uses: ER_catch, ER_success, find_error_message, HeapAlloc, HeapFreeIndir, EV_captureEvents, EV_clearPasteString, EV_eventLoop, EV_restorePainting, EV_suspendPainting, OSWriteLinkBlock, sprintf, off, OSSetSR, OSTimerRestart, XR_stringPtr, EV_errorCode, sf_width, ResetSymFlags, DrawStaticButton, WinActivate, WinAttr, WinClose, WinFont, WinOpen, WinStrXY, ROM Call 0x471
Used by: ERD_process, cmd_input, cmd_inputstr, cmd_prompt, Dialog, VarNew, VarSaveAs, EV_defaultHandler, EV_eventLoop, handleVarLinkKey, HomeExecute, TE_handleEvent, TE_pasteText, GT_Error, GT_Trace, SP_Define, ROM Call 0x45B, DateAndTime_SetDlg


ERD_dismissNotice

ERD_dismissNotice Function (ROM Call 0x476)
AMS 2.00 or higher error.h

void ERD_dismissNotice (void);

Removes the error notice displayed by a prior call to ERD_notice.

This function causes the screen to be repainted, because it calls WinClose.
CAUTION: calling this function without a prior call to ERD_notice, or calling ERD_dismissNotice twice, can leave the calculator in an unstable state !

Uses: WinClose
Used by: DlgMessage, EV_eventLoop


ERD_notice

ERD_notice Function (ROM Call 0x475)
AMS 2.00 or higher error.h

short ERD_notice (unsigned char const *title, unsigned char const *message);

Displays an error notice.

ERD_notice displays a dialog-looking window with title title, message message (word-wrapped if necessary), without buttons, that will stay on the screen until ERD_dismissNotice is called.
ERD_notice returns TRUE if the window was actually displayed, FALSE otherwise.
ERD_notice must be paired correctly with ERD_dismissNotice.

Uses: sf_width, strncpy, WinActivate, WinAttr, WinFont, WinOpen, WinStrXY
Used by: DlgMessage, EV_eventLoop


ERD_process

ERD_process Function (ROM Call 0x152)
error.h

void ERD_process (short err_no);

Processes an error.

ERD_process processes the error with error code err_no by calling ERD_dialog appropriately. Button "Enter=GOTO" will be displayed only if the routine concludes from some system flags that the routine is called from the TI-Basic interpreter (which will not be the case if you called it from a C or ASM program). Then, ERD_process responds by starting the appropriate application (for example the text editor if the TI-Basic interpreter was active and if the user pressed the button "Enter=GOTO"). Principally, there is no difference between ERD_process and ERD_dialog, except in event-driven applications (see the events.h header file).

Uses: ER_catch, ER_success, ERD_dialog, EV_startApp, sprintf, CheckSysFunc, DerefSym, SymFind, SymFindFirst, SymFindFolderName, SymFindNext, ROM Call 0x31, ROM Call 0x5C9, ROM Call 0x5CA, ROM Call 0x5CC
Used by: cmd_disptbl, EV_centralDispatcher, HomeExecute


find_error_message

find_error_message Function (ROM Call 0x2C1)
AMS 1.01 or higher error.h

const char *find_error_message (short err_no);

Returns a TI-Basic error message string.

find_error_message returns a pointer to the text of the TI-Basic error message string with the code err_no. See the TI-Basic manual for a list of various error codes. If err_no is not a valid error code, the routine returns a pointer to the string "Unknown ERROR code", or its localized version if a language localization is active (on AMS 2.xx).

find_error_message may return NULL.

Uses: XR_stringPtr, EV_runningApp, OO_CondGetAttr
Used by: ERD_dialog, HomeExecute


errCode

errCode Variable (Automatic)
error.h

unsigned short errCode;

Contains the error number in a TRY...ONERR...ENDTRY block.

errCode is an automatic (local) variable which is automatically created in the error handler, and it contains the error number to allow the program to check what caused the error. This variable is automatically destroyed after ENDTRY statement, i.e. after execution of the error handler. Variable errCode, because it is local to the ONERR block, cannot be referenced outside the ONERR block.

Used by: TRY, ENDFINAL, PASS

See also: ErrorCodes


ERROR_FRAME

ERROR_FRAME Type (Array)
error.h

typedef struct ErrorFrameStruct {
unsigned long A2, A3, A4, A5, A6, A7;
unsigned long D3, D4, D5, D6, D7;
unsigned long NG_control;
char *RetIndex;
unsigned long PC;
struct ErrorFrameStruct *Link;
} ERROR_FRAME [1];

A type designed for capturing a task state.

ERROR_FRAME is a type designed for capturing a task state needed for catching errors using the ER_catch command.


ErrorCodes

ErrorCodes Type (Enumeration)
error.h

enum ErrorCodes {ER_OK = 0, ER_OKAY = 0, ER_EXIT = 1, ER_STOP = 2, ER_OFF = 3, ER_PRGM_STOP = 4, ER_NO_MSG = 9, ER_FUNC_DID_NOT_RETURN_VALUE = 10, ER_TEST_NOT_TRUE_OR_FALSE = 20, ER_ARG_CANNOT_BE_FOLDER = 30, ER_ARGUMENT = 40, ER_ARG_MISMATCH = 50, ER_EXPECTED_BOOL_OR_AGG = 60, ER_ARG_MUST_BE_DECIMAL = 70, ER_ARG_MUST_BE_LABEL = 80, ER_ARGUMENT_MUST_BE_LIST = 90, ER_ARG_MUST_BE_MATRIX = 100, ER_ARG_MUST_BE_PIC = 110, ER_ARG_MUST_BE_PIC_OR_STR = 120, ER_ARG_MUST_BE_STRING = 130, ER_EXPECTED_VAR = 140, ER_ARG_MUST_BE_EMPTY_FOLDER = 150, ER_EXPECTED_ALGEBRAIC = 160, ER_ASAP_TOO_LONG = 161, ER_ATTRIBUTE_NOT_FOUND = 163, ER_BATT_LOW = 165, ER_BOUND = 170, ER_BREAK = 180, ER_CHECKSUM = 185, ER_CIRCULAR_DEFINITION = 190, ER_INVALID_SUCH_THAT = 200, ER_DATATYPE = 210, ER_DEPENDENT_LIMIT = 220, ER_DIFF_EQ_SETUP = 225, ER_DIMENSION = 230, ER_NOT_ENOUGH_ELEMENTS = 230, ER_NON_CONFORMING_LISTS = 240, ER_DIVBY0 = 250, ER_DOMAIN = 260, ER_DUPLICATE_VAR_NAME = 270, ER_ELSEIF_WITHOUT_IF = 280, ER_ELSE_WITHOUT_IF = 280, ER_ENDTRY_WITHOUT_ELSE = 290, ER_EXCESSIVE_ITERATION = 295, ER_EXPECTED_2OR3_ELEMENTS = 300, ER_EXPIRED = 305, ER_APP_EXT_NOT_FOUND = 307, ER_APP_NOT_FOUND = 308, ER_INVALID_NSOLVE_ARG1 = 310, ER_INVALID_SOLVE_ARG1 = 320, ER_FOLDER = 330, ER_FUNCS_IN_DIFF_EQ = 335, ER_INCONSISTENT_UNITS = 345, ER_INVALID_SUBSCRIPT = 350, ER_INVALID_INDIR_STRING = 360, ER_INDIR_STRING_NOT_VARNAME = 360, ER_INDIR_STRING_NOT_FUNNAME = 360, ER_INVALID_ANS = 380, ER_ILLEGAL_ASSIGNMENT = 390, ER_ILLEGAL_ASSIGNMENT_VALUE = 400, ER_INVALID_AXES = 405, ER_ILLEGAL_COMMAND = 410, ER_INVALID_FOLDER_NAME = 420, ER_GRAPH_MODE = 430, ER_INVALID_GUESS = 435, ER_INVALID_IMPLIED_MULT = 440, ER_ILLEGAL_IN_FUNC = 450, ER_ILLEGAL_IN_CUSTOM = 460, ER_ILLEGAL_IN_DIALOG = 470, ER_ILLEGAL_IN_TOOLBAR = 480, ER_CANNOT_EXIT_FROM_TRY = 490, ER_CANNOT_CYCLE_FROM_TRY = 490, ER_CANNOT_GOTO_FROM_TRY = 490, ER_CANNOT_GOTO_INTO_TRY = 490, ER_INVALID_LABEL = 500, ER_INVALID_LIST_OR_MATRIX = 510, ER_INVAL_OUTSIDE_TB_CM = 520, ER_INVAL_OUTSIDE_DG_TB_CM = 530, ER_INVALID_OUTSIDE_DIALOG = 540, ER_MUST_BE_IN_PRGM_OR_FUNC = 550, ER_CYCLE_NOT_IN_LOOP = 560, ER_EXIT_NOT_IN_LOOP = 560, ER_INVALID_PATHNAME = 570, ER_INVALID_POLAR_COMPLEX = 575, ER_ILLEGAL_PRGM_REF = 580, ER_INVALID_SYNTAX_BLOCK = 590, ER_INVALID_TABLE = 600, ER_INVALID_USE_OF_UNITS = 605, ER_INVALID_LOCAL_DECLARATION = 610, ER_EXPECTED_VAR_OR_FUNC = 620, ER_INVALID_VAR_REF = 630, ER_INVALID_VECTOR_SYNTAX = 640, ER_LINK_IO = 650, ER_MAT_NOT_DIAGONALIZABLE = 665, ER_MEMORY = 670, ER_MEMORY_EXHAUSTION = 670, ER_ESTACK_OVERFLOW = 670, ER_STACK_VIO = 673, ER_EXPECTED_LPAR = 680, ER_EXPECTED_RPAR = 690, ER_EXPECTED_DOUBLE_QUOTE = 700, ER_EXPECTED_RIGHT_BRACKET = 710, ER_EXPECTED_RIGHT_BRACE = 720, ER_INVALID_BLOCK_STRUCTURE = 730, ER_MISSING_THEN = 740, ER_NOT_FUNC_OR_PRGM = 750, ER_NO_FUNCS_SEL = 765, ER_NO_SOLUTION = 780, ER_NON_ALGEBRAIC_VARIABLE = 790, ER_UNREAL_RESULT = 800, ER_EXPECTED_REAL = 800, ER_MEMORY_DML = 810, ER_RATIONAL_NUMERIC_OVERFLOW = 830, ER_OVERFLOW = 830, ER_STAT_PLOT = 840, ER_PRGM_NOT_FOUND = 850, ER_RECURSION_TOO_DEEP = 860, ER_RESERVED = 870, ER_SYS_FUNC = 870, ER_ROM_ROUTINE_NOT_AVAILABLE = 875, ER_SEQUENCE_SETUP = 880, ER_SIGNATURE_ERR = 885, ER_SINGULARMAT = 890, ER_SLOPE_FIELD_FUNCS = 895, ER_WEIGHTS_SUM_NOT_POS = 900, ER_LISTS_CONTAIN_NEG = 900, ER_LISTS_NOT2DISCREET = 900, ER_EMPTY_GROUP_NOT_VALID = 900, ER_SYNTAX = 910, ER_UNEXPECTED_CHARACTER = 910, ER_EXPECTED_EQUAL = 910, ER_EXPECTED_FACTOR = 910, ER_TOO_FEW_ARGS = 930, ER_TOO_MANY_ARGS = 940, ER_TOO_MANY_SUBSCRIPTS = 950, ER_TOO_MANY_UNDEFINED = 955, ER_UNDEFINED_VAR = 960, ER_UNLICENSED = 965, ER_GRAPH_FUNC_IN_USE = 970, ER_PROG_OR_FUNC_IN_USE = 970, ER_VAR_IN_USE = 970, ER_LOCKED = 980, ER_PROTECTED = 980, ER_NAME_TOO_LONG = 990, ER_RANGE = 1000, ER_ZOOM = 1010, ER_ILLEGAL_TAG = 1020, ER_UNKNOWN_TAG = 1020, ER_DIVISION_BUG = 1020, ER_MEM_VIO = 1030, ER_FP_TEST_FAIL = 4094, EXPECTED_BOOL_OR_AGG_ERROR = 60, EXPECTED_VAR_ERROR = 140, EXPECTED_ALGEBRAIC_ERROR = 160, INVALID_SUCH_THAT_ERROR = 200, NON_CONFORMING_LISTS_ERROR = 240, EXPECTED_2OR3_ELEMENTS_ERROR = 300, INVALID_NSOLVE_ARG1_ERROR = 310, INVALID_SOLVE_ARG1_ERROR = 320, INVALID_PATHNAME_ERROR = 570, EXPECTED_VAR_OR_FUNC_ERROR = 620, MEMORY_EXHAUSTION_ERROR = 670, ESTACK_OVERFLOW_ERROR = 670, EXPECTED_LPAR_ERROR = 680, EXPECTED_RPAR_ERROR = 690, EXPECTED_DOUBLE_QUOTE_ERROR = 700, EXPECTED_RIGHT_BRACKET_ERROR = 710, EXPECTED_RIGHT_BRACE_ERROR = 720, UNREAL_RESULT_ERROR = 800, EXPECTED_REAL_ERROR = 800, RATIONAL_NUMERIC_OVERFLOW_ERROR = 830, RECURSION_TOO_DEEP_ERROR = 860, SYNTAX_ERROR = 910, UNEXPECTED_CHARACTER_ERROR = 910, EXPECTED_EQUAL_ERROR = 910, EXPECTED_FACTOR_ERROR = 910, TOO_FEW_ARGS_ERROR = 930, TOO_MANY_ARGS_ERROR = 940, TOO_MANY_SUBSCRIPTS_ERROR = 950, TOO_MANY_UNDEFINED_ERROR = 955, GRAPH_FUNC_IN_USE_ERROR = 970, NAME_TOO_LONG_ERROR = 990, ILLEGAL_TAG_ERROR = 1020, UNKNOWN_TAG_ERROR = 1020, DIVISION_BUG_ERROR = 1020};

An enumeration containing all error codes.

This enumeration contains all error codes used by the TIOS. Error names not starting with 'ER_' are deprecated and introduced only for compatibility. All of these errors can be passed on to the operating system. You can use your own numbers for errors which you handle in your program, if you want to use the error-handling system to write more stable programs.

See also: ER_throw, ER_throwVar, errCode


estack.h

estack.h Header File
Header File Index

Routines for symbolic manipulation and expression handling

Functions
add_to_top
Adds a value to the expression on the top of the EStack.
add1_to_top
Adds 1 to the top of the EStack.
all_tail
Checks whether all elements in the list have some property.
and_onto_top
Logical ANDs an expression onto the EStack.
any_tail
Checks whether any element in the list has some property.
are_expressions_identical
Checks whether two expressions are identical.
can_be_approxed
Checks whether an expression can be approximated to a number.
check_estack_size
Checks if there is enough room on the expression stack.
compare_complex_magnitudes
Compares magnitudes of two complex number entries on the expression stack.
compare_expressions
Compares two expressions.
compare_Floats
Compares two floating point entries on the expression stack.
CreateEmptyList
Creates a MULTI_EXPR containing an empty list and returns its handle.
delete_between
Deletes a sequence of bytes from the expression stack.
delete_expression
Deletes an expression from the expression stack.
deleted_between
Deletes a sequence of bytes from the expression stack.
deleted_expression
Deletes an expression from the expression stack.
did_push_cnvrt_Float_to_integer
Pushes a floating point entry converted to an integer, but only if it is an exact whole number.
display_statements
Converts tokenized expressions or TI-Basic statements to the printable form.
divide_top
Divides the expression onto the EStack.
estack_number_to_Float
Converts entry on the expression stack to floating point number.
estack_to_short
Converts entry on the expression stack to signed short integer.
estack_to_ushort
Converts entry on the expression stack to unsigned short integer.
ESTACK
Reads the expression stack at a specific index.
factor_base_index
Gets the index of the base of an expression.
factor_exponent_index
Gets the index of the exponent of an expression.
gcd_exact_whole_Floats
Finds the greatest common divisor of two floating point entries.
get_key_ptr
Converts a tag code to a tag name.
GetValue
Converts entry on the expression stack to short integer and checks whether it is in a given range.
HS_popEStack
Pops the entire expression stack into memory.
HToESI
Converts a handle to an expression stack index.
im_index
Gets the index of the imaginary part of an expression.
index_below_display_expression_aux
Main routine for detokenizing.
index_main_var
Searches an expression for a first encountered variable.
index_numeric_term
Searches terms in the expression for a numeric term.
index_of_lead_base_of_lead_term
Gets the index of the base of the lead term of an expression.
init_list_indices
Computes and stores the indices of the elements of a list.
init_matrix_indices
Computes and stores the indices of the elements of a matrix.
integer_non_unknown
Tests if an expression is an integer.
is0
Tests if an expression is equal to 0.
is1
Tests if an expression is equal to 1.
is_advanced_tag
Checks whether a tag is an advanced tag.
is_antisymmetric
Checks for a antisymmetry.
is_complex0
Checks whether an expression is reducible to zero.
is_complex_number
Checks whether an expression is a number.
is_constant
Checks whether an expression is constant.
is_Float_exact_whole_number
Checks whether a floating point entry is an exact whole number.
is_free_of_tag
Checks whether an expression is free of a particular tag.
is_independent_of_de_seq_vars
Checks whether an expression is independent of differential equation and sequence variables.
is_independent_of_elements
Checks whether an expression is independent of the elements of a list.
is_independent_of_tail
Checks whether an expression is independent of a sequence of variables (or expressions).
is_independent_of
Checks whether an expression is independent of a variable (or expression).
is_matrix
Checks whether an expression is a matrix.
is_minus1
Tests if an expression is equal to -1.
is_monomial_in_kernel
Checks whether an expression is a monomial in kernel.
is_monomial
Checks whether an expression is a monomial.
is_narrowly_independent_of
Checks whether an expression is narrowly independent of a variable (???).
is_negative
Tests if an expression is less than 0.
is_never0
Tests if an expression is never 0.
is_nonnegative
Tests if an expression is >= 0.
is_nonpositive
Tests if an expression is <= 0.
is_polynomial_in_var_or_kern
Checks if an expression is a polynomial with respect to another expression.
is_pos_int_and_eq_quantum
Determines whether expr points to the tag of a positive integer equal to num.
is_positive
Tests if an expression is greater than 0.
is_reciprocal_of_quantum
Determines whether expr points to the tag of the reciprocal of ESQ num.
is_square_matrix
Checks whether an expression is a square matrix.
is_symmetric
Checks for symmetry.
is_tail_independent_of
Checks whether a sequence of expressions is independent of a variable (or expression).
is_temperature_unit
Checks for strings of temperature units.
is_totally_polynomial
Checks if an expression is polynomial in all variables.
is_valid_smap_aggregate
Checks whether an expression is a valid aggregate type.
is_variable
Checks if the expression is a variable.
is_whole_number
Tests if an expression is a whole number.
last_element_index
Searches for the last expression in the list.
lead_base_index
Gets the index of the base of the lead factor of an expression.
lead_exponent_index
Gets the index of the exponent of the lead factor of an expression.
lead_factor_index
Gets the index of the lead factor of an expression.
lead_term_index
Gets the index of the lead term of an expression.
likely_approx_to_complex_number
Checks if it is likely that an expression can be approxed to a complex number.
likely_approx_to_number
Checks is it likely that an expression can be approxed to a real number.
main_gen_var_index
Searches an expression for a generalized variable.
map_tail_Int
Applies an extended function to all elements in the list.
map_tail
Applies a function to all elements in the list.
map_unary_over_comparison
Calls callback function for both comparison terms and pushes the comparison tag.
min_quantum
Finds smaller of two tags.
move_between_to_top
Moves a sequence of bytes to the top of the expression stack.
moved_between_to_top
Moves a sequence of bytes to the top of the expression stack.
negate_top
Negates the top of the EStack.
next_expression_index
Finds the next entry on the expression stack.
NG_approxESI
Evaluates an expression in "APPROX" mode.
NG_execute
Executes TI-Basic statements.
NG_graphESI
Evaluates an expressions for graphing purposes.
NG_rationalESI
Evaluates an expression in "EXACT" mode.
NG_RPNToText
Detokenizes a tokenized structure associated with a handle.
NG_tokenize
Tokenizes text associated with a handle and pushes them to the expression stack.
norm1_complex_Float
Finds the 1-norm of a complex number entry.
numeric_factor_index
Searches factors in the expression for a numeric factor.
or_onto_top
Logical ORs an expression onto the estack.
Parms2D
Gets information about dimensions of block which will be "pretty printed".
Parse1DExpr
Parses a tokenized expression to be printed.
Parse2DExpr
Parses a tokenized expression to be pretty printed using Print2DExpr.
Parse2DMultiExpr
Parses a multi-statement expression associated with a handle to be pretty printed using Print2DExpr.
Print2DExpr
Performs "pretty printing" (or "2D printing") of an expression.
push0
Pushes a tagged integer or a tagged float 0, depending on the mode setting.
push1
Pushes a tagged integer or a tagged float 1, depending on the mode setting.
push_ANSI_string
Pushes a standard C string to the expression stack.
push_between
Pushes a sequence of bytes to the expression stack.
push_cnvrt_integer_if_whole_nmb
Pushes a floating point entry eventually converted to an integer.
push_e
Pushes e.
push_END_TAG
Pushes end-of-list marker to the expression stack.
push_exact0
Pushes a tagged integer 0.
push_exact1
Pushes a tagged integer 1.
push_exact_minus1
Pushes a tagged integer -1.
push_expr_quantum
Pushes an expression followed by a tag to the expression stack.
push_expr2_quantum
Pushes two expressions followed by a tag to the expression stack.
push_expression
Pushes an expression to the expression stack.
push_Float_to_nonneg_int
Rounds a floating point value to an integer, then pushes it to the expression stack.
push_Float_to_rat
Pushes a rational approximation of a floating point entry.
push_Float
Pushes a floating point value to the expression stack.
push_half
Pushes a tagged fraction +1/2 or a tagged float 0.5, depending on the mode setting.
push_i
Pushes i.
push_internal_simplify
Converts an expression into internal canonic form and pushes the result to the expression stack.
push_LIST_TAG
Pushes list tag to the expression stack.
push_long_to_integer
Pushes a signed long integer to the expression stack.
push_longint
Pushes a long integer to the expression stack.
push_longlongint
Pushes a double-long integer to the expression stack.
push_minus1
Pushes a tagged integer or a tagged float -1, depending on the mode setting.
push_minus_half
Pushes a tagged fraction -1/2 or a tagged float -0.5, depending on the mode setting.
push_minus_recip_of_quantum
Pushes on the EStack minus the reciprocal of the argument as a tagged negative fraction.
push_negate_quantum_as_negint
Pushes on the EStack the argument as a tagged negative integer.
push_next_arb_int
Pushes a next "arbitrary integer" symbol to the expression stack.
push_next_arb_real
Pushes a next "arbitrary real" symbol to the expression stack.
push_next_internal_var
Pushes an internal variable to the expression stack.
push_no_solution_found_string
Pushes "No solution found", or its localized version if a language localization is active (on AMS 2.xx), on the EStack.
push_offset_array
Pushes an array of offsets to the list items.
push_overflow_to_infinity
Displays a warning, and pushes a tag to the expression stack.
push_parse_text
Parses an expression given in a string and pushes tokenized expression to the expression stack.
push_pi_on_quantum
Pushes on the EStack the quotient of PI (numerator) and of the argument (denominator), in a way depending on the mode setting.
push_pi
Pushes on the EStack a tagged float PI if the mode setting is APPROX, otherwise pushes a PI_TAG.
push_quantum_as_nonnegative_int
Pushes on the EStack the argument as a tagged positive integer.
push_quantum_pair_as_pos_frac
Pushes on the EStack the quotient of the first argument (numerator) and the second argument (denominator).
push_quantum_pair
Pushes two bytes (tags) to the expression stack.
push_quantum
Pushes a byte (tag) to the expression stack.
push_reciprocal_of_quantum
Pushes on the EStack the reciprocal of the argument as a tagged positive fraction.
push_reversed_tail
Pushes elements of the list up to tail onto the stack in reversed order.
push_round_Float
Pushes an approximation of a floating point entry.
push_shortint
Pushes a short integer to the expression stack.
push_simplify
Simplifies the argument and pushes onto the estack.
push_transpose_aux
Pushes transposed matrix to the expression stack.
push_ulong_to_integer
Pushes an unsigned long integer to the expression stack.
push_ushort_to_integer
Pushes an unsigned short integer to the expression stack.
push_zstr
Pushes a standard C string to the expression stack.
raise_to_top
Raises a value to the power given by the expression on the top of the EStack.
re_index
Gets the index of the real part of an expression.
reductum_index
Gets the index of remaining terms of an expression.
remaining_element_count
Returns number of elements remaining.
remaining_factors_index
Gets the index of remaining factors of an expression.
replace_top_with_post_simplified
Replaces the expression on top of the EStack, in internal form, with the external (printing) form.
replace_top_with_reciprocal
Replaces the expression on top of the EStack by its reciprocal.
replace_top2_with_and
Replace the two top-most expressions on the EStack by their logical AND.
replace_top2_with_difference
Replace the two top-most expressions on the EStack by their difference.
replace_top2_with_imre
Replace the two top-most expressions on the EStack by a complex number.
replace_top2_with_or
Replace the two top-most expressions on the EStack by their logical OR.
replace_top2_with_pow
Replace the two top-most expressions on the EStack by a power.
replace_top2_with_prod
Replace the two top-most expressions on the EStack by their product.
replace_top2_with_ratio
Replace the two top-most expressions on the EStack by their ratio.
replace_top2_with_sum
Replace the two top-most expressions on the EStack by their sum.
reset_control_flags
Resets the control flags for operations with the expression stack.
reset_estack_size
Reallocates the expression stack.
should_and_did_push_approx_arg2
Pushes a second floating point argument, if possible.
signum_Float
Finds the signum of a floating point entry.
subtract_from_top
Subtracts a value from the top of the EStack.
subtract1_from_top
Subtracts 1 from the top of the EStack.
times_top
Multiplies the expression onto the EStack.
TokenizeSymName
Tokenizes a C string into a symbol name.
Global Variables
ARb_int_count
Represents the number of times arbitrary-integer variables were already used by some calculus.
ARb_real_count
Represents the number of times arbitrary variables were already used by some calculus.
bottom_estack
Points to the bottom of the expression stack.
command_tag_list
Array of structures containing information on InstructionTags.
estack_max_index
Points to the end of the expression stack.
Float0Index
Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value 0.0.
Float1Index
Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value 1.0.
FloatExp1Index
Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value e.
FloatHalfIndex
Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value 0.5.
FloatMinus1Index
Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value -1.0.
FloatPiIndex
Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value pi.
FLOATTAB
A pointer to an array of more or less commonly used untagged floats.
index_false
Pointer on a FALSE_TAG (0x2B) stored in the Flash.
index_true
Pointer on a TRUE_TAG (0x2C) stored in the Flash.
Integer0Index
Pointer to the end tag (POSINT_TAG) of an integer value 0.
Integer1Index
Pointer to the end tag (POSINT_TAG) of an integer value 1.
Integer2Index
Pointer to the end tag (POSINT_TAG) of an integer value 2.
IntegerMinus1Index
Pointer to the end tag (NEGINT_TAG) of an integer value -1.
primary_tag_list
Array of structures containing information on Tags.
secondary_tag_list
Array of structures containing information on ExtTags.
sysvar_tag_list
Array of structures containing information on SysvarTags.
top_estack
Points to the top of the expression stack.
Constants
H_NULL
A null-handle value.
NULL_INDEX
Describes an empty expression stack index.
Predefined Types
bcd
Represents the internal organization of floating point numbers in the format recognized by the TIOS.
Bool
An enumeration to describe true or false values.
CESI_Callback_t
Represents a pointer to a CESI callback function.
CESI
Represents a pointer to a constant expression.
cmd_info
Structure containing information about AMS EStack command tags (InstructionTags).
ESI_Callback_Int_t
Represents a pointer to an ESI callback function with integer extensions.
ESI_Callback_t
Represents a pointer to an ESI callback function.
ESI
Represents an index of a value on the TIOS expression stack.
ESQ
Represents a quantum within an expression.
EStackDisplacement
Type used for representing difference of two ESI pointers.
EStackIndex
Represents an index of a value on the TIOS expression stack.
ExtTags
An enumeration to describe extra types of entries on the expression stack.
FLOATTABIndexes
An enumeration for describing the valid indexes for FLOATTAB.
HANDLE
Represents a handle associated with an allocated memory block.
InstructionTags
An enumeration to describe types of instructions on the expression stack.
MULTI_EXPR
Describes a multi-expression, which is processed as a separate expression stack.
Quantum
Represents a quantum within an expression.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
SYM_STR
Represents a pointer to the terminating zero byte of a string.
sysvar_info
Structure containing information about AMS EStack tags (SysvarTags).
SysvarTags
An enumeration to describe types of system variable entries on the expression stack.
tag_info
Structure containing information about AMS EStack tags (Tags, ExtTags).
Tags
An enumeration to describe types of entries on the expression stack.
ti_float
An alias for the standard ANSI float type.
TokenizeSymNameFlags
Contains flags specifying how a symbol name is tokenized.
WINDOW
The main window-describing structure.

See also: args.h


add_to_top

add_to_top Function (ROM Call 0x518)
AMS 2.02 or higher estack.h

void add_to_top (CESI ptr);

Adds a value to the expression on the top of the EStack.

add_to_top adds the expression pointed to by ptr to the expression currently at the top of the EStack and stores the result to the top of the EStack, in place of the expression that was added to.

Uses: are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, integer_non_unknown, is_advanced_tag, is_constant, is_minus1, is_nonnegative, is_positive, is_variable, is_whole_number, is0, is1, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_real, is_reciprocal_of_quantum, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: add1_to_top, is_antisymmetric, is_negative, is_nonnegative, is_nonpositive, is_positive, subtract1_from_top, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_atan, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_integer_remainder, push_is_prime, push_lim, push_max, push_min, push_mod, push_mrowadd, push_nsolve, push_numerator, push_phase, push_re, push_rowadd, push_rowdim, push_sin2, push_solve, push_sumlist, push_summation, push_tanh, push_zeros, did_push_to_polar, push_degrees, push_difference, push_dot_sub, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_list_plus, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1f, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, push_dense_poly_eval

See also: subtract_from_top, negate_top, add1_to_top, subtract1_from_top


add1_to_top

add1_to_top Function (ROM Call 0x51D)
AMS 2.02 or higher estack.h

void add1_to_top (void);

Adds 1 to the top of the EStack.

add1_to_top adds 1 (or 1.0) to the value on the top of the EStack. This routine basically calls add_to_top with "1" as the pointed-to value.

Uses: add_to_top, Float1Index, Integer1Index
Used by: did_push_anti_deriv, push_1st_derivative, push_asin, push_comb, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_lim, push_ln, push_max, push_min, push_nsolve, push_rec_to_angle, push_sequence, push_sin2, push_solve, push_summation, push_tan, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub

See also: add_to_top, subtract1_from_top


all_tail

all_tail Function (ROM Call 0x3B5)
AMS 1.01 or higher estack.h

short all_tail (CESI_Callback_t f, ESI start_ptr);

Checks whether all elements in the list have some property.

all_tail is similar to map_tail, but callback function f is not void. It needs to return a Boolean value (TRUE or FALSE). If f returns FALSE, any further processing of the list tail will be stopped, even if END_TAG is not reached yet. The result of all_tail is the last value returned from f. In other words, it returns TRUE if and only if the callback function f returns TRUE for each expression in the tail of expressions indexed by element_ptr.

all_tail is very useful to check whether all elements of a list possess some property. Suppose that you defined the following function which checks whether an entry on the expression stack is a positive integer:

short is_positive_integer (ESI ptr)
{
  return (*ptr == POSINT_TAG);
}
and suppose that start_ptr points to the first element of the list (one byte below LIST_TAG). Then, you can use the following call to check whether all elements of the lists are positive integers:
are_all_positive_integers = all_tail (is_positive_integer, start_ptr);

Uses: next_expression_index
Used by: NG_graphESI, did_push_anti_deriv, did_push_series, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_lim, push_max, push_min, push_nsolve, push_rec_to_angle, push_solve, push_summation, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum, get_ub, is_cFloat_agg, is_constant, push_reciprocal, push_user_func, push_subscripted_element


and_onto_top

and_onto_top Function (ROM Call 0x579)
AMS 2.02 or higher estack.h

void and_onto_top (CESI ptr);

Logical ANDs an expression onto the EStack.

and_onto_top replaces the top expression on the EStack with the logical AND of itself and the expression pointed to by ptr.

Uses: push_and, are_expressions_identical, delete_expression, next_expression_index, push_expression, top_estack
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_and, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_substitute_using_such_that, push_xor, get_ub, push_but_conjunct_factor, push_user_func, ROM Call 0x4E6

See also: or_onto_top


any_tail

any_tail Function (ROM Call 0x3B6)
AMS 1.01 or higher estack.h

short any_tail (CESI_Callback_t f, ESI start_ptr);

Checks whether any element in the list has some property.

any_tail is similar like all_tail, except further processing of the list will be stopped if f returns TRUE instead of FALSE. In other words, it returns TRUE if and only if the callback function f returns TRUE for at least one expression in the tail of expressions indexed by element_ptr. any_tail is very useful to check whether any element of a list possesses some property. Assuming the same assumptions as in the example given with all_tail, the following call will check whether any element of the list is a positive integer:

is_any_positive_integer = any_tail (is_positive_integer, start_ptr);

Uses: next_expression_index
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


are_expressions_identical

are_expressions_identical Function (ROM Call 0x2BF)
AMS 1.01 or higher estack.h

short are_expressions_identical (CESI ptr1, CESI ptr2);

Checks whether two expressions are identical.

are_expressions_identical returns TRUE if expressions pointed to by ptr1 and ptr2 are syntactically identical, else returns FALSE. At the moment, I am not exactly sure what is the criteria for equivalence. I only know that a+b and b+a are not identical for example. And, floats are never identical to rational numbers. So far, I only know that this function surely returns TRUE when two expressions are absolutely identical. But, if this is the only case of equivalence, this routine should be very simple. But it is not. It is very complicated and recursive, so I am really not sure which pairs of expressions may be treated as "identical". Any additional info is welcomed.

Uses: next_expression_index, memcmp, primary_tag_list
Used by: is_independent_of, is_monomial_in_kernel, is_narrowly_independent_of, push_internal_simplify, push_parse_text, cmd_goto, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_lim, push_max, push_min, push_nint, push_nsolve, push_phase, push_sign, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_or, push_product, push_substitute_no_simplify, push_sum, push_to_cylin, push_to_sphere, ST_eraseHelp, ST_modKey, add_to_top, and_onto_top, are_units_consistent, did_push_lincf, EQU_getNameInfo, get_lb, get_ub, has_different_variable, index_if_pushed_binomial_info, index_rmng_factor, index_rmng_fctrs_start_base, is_equivalent_to, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_positive, is_term_improper, linear_degree, or_onto_top, push_but_term, push_constant_terms, push_dependent_terms, push_gcd_then_cofactors, push_independent_terms, push_make_proper, push_nonconstant_terms, push_parse_prgm_or_func_text, push_poly_deg_in_var_or_kernel, push_poly_qr, push_reciprocal, push_standardize, replace_top_with_post_simplified, replace_top2_with_sum, is_temperature_unit, ROM Call 0x48D, ROM Call 0x4E6


can_be_approxed

can_be_approxed Function (ROM Call 0x2F5)
AMS 1.01 or higher estack.h

short can_be_approxed (CESI ptr, short Complex);

Checks whether an expression can be approximated to a number.

can_be_approxed returns TRUE if the expression pointed to by ptr can be approximated to a number (including transfinite ones) or a list of numbers (such expression are for example 'ln(2+sin(1))/5', '1/0' or 'x^2+1-x*x'), else returns FALSE. Complex is a Boolean parameter: if it is TRUE, complex results will be allowed, but if it is FALSE, complex results will be treated as "cannot be approxed".

Note: can_be_approxed performs much detailed investigation than functions likely_approx_to_number and likely_approx_to_complex_number.

Uses: next_expression_index, top_estack, push_approx, primary_tag_list
Used by: push_colnorm, push_rownorm, push_degrees, push_exponentiate


check_estack_size

check_estack_size Function (ROM Call 0x2C2)
AMS 1.01 or higher estack.h

void check_estack_size (unsigned short Size);

Checks if there is enough room on the expression stack.

check_estack_size checks if there is enough room to push Size bytes to the expression stack. If there is not enough space, it tries to enlarge the stack (using HeapRealloc) to make additional space. It throws an error if the requirement cannot be satisfied. Note that all "push_..." functions call this routine, so all of them may throw an error if there is not enough memory.

Uses: top_estack, HeapRealloc, estack_max_index
Used by: compare_complex_magnitudes, index_below_display_expression_aux, Parse2DExpr, Parse2DMultiExpr, push_between, push_Float, push_Float_to_nonneg_int, push_offset_array, push_parse_text, push_quantum, push_quantum_pair, cmd_newdata, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_im, push_integer_lcm, push_integer_quotient, push_is_prime, push_lim, push_max, push_median, push_min, push_mod, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_rotate, push_sequence, push_shift, push_sin2, push_solve, push_string, push_summation, push_tan, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_or, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, compare_numbers, does_push_fetch, EQU_getNameInfo, get_list_indices, get_matrix_indices, get_ub, GraphOrTableCmd, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_float_qr_fact, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_poly_qr, push_reciprocal, push_standardize, push_symbolic_qr_fact, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, times_top, push_exact0, push_exact_minus1, push_exact1


compare_complex_magnitudes

compare_complex_magnitudes Function (ROM Call 0x2F6)
AMS 1.01 or higher estack.h

short compare_complex_magnitudes (CESI ptr1, CESI ptr2);

Compares magnitudes of two complex number entries on the expression stack.

compare_complex_magnitudes compares two complex number entries (which may be real also) on the expression stack pointed to by ptr1 and ptr2, and returns a value which is

  • < 0 if the magnitude of the number pointed to by ptr1 is less than the magnitude of the number pointed to by ptr2
  • == 0 if the magnitude of the number pointed to by ptr1 is the same as the magnitude of the number pointed to by ptr2
  • > 0 if the magnitude of the number pointed to by ptr1 is greater than the magnitude of the number pointed to by ptr2

Uses: check_estack_size, delete_between, estack_number_to_Float, next_expression_index, push_between, push_expression, push_Float, push_quantum, top_estack, push_abs, push_square, ST_helpMsg, XR_stringPtr, compare_numbers, primary_tag_list, replace_top2_with_sum, _bcd_math, _du16u16, _ds32s32, _ms32s32, push_exact0


compare_expressions

compare_expressions Function (ROM Call 0x2C0)
AMS 1.01 or higher estack.h

short compare_expressions (CESI ptr1, CESI ptr2);

Compares two expressions.

compare_expressions returns 0 if two expressions pointed to by ptr1 and ptr2 are equal in the sense that they have the same structure, variables, function names, and numbers that compare equal. A float and a rational number compare equal if converting the rational number to a float produces an identical number. If the expressions are not, it returns a non-zero value which may be positive or negative (more precise, 1 or -1). Positive result means that the expression pointed to by ptr1 is "more main" that the expression pointed to by ptr2, and negative result means "less main". Principally, variables are more main than symbolic constants such as pi, which are more main than numbers. In expressions such as 'expand(...,var)' or 'Integral(...,var)', a variable var is "most main". Otherwise, the 26 Roman one-letter variables order r>>s>>...>>z>>a>>b>>...>>q ('>>' means "more main"), which order more main than all other variables, which order alphabetically. Functions and operators are typically ordered by recursively comparing their first arguments, with ties broken by comparing their second arguments, etc. then finally comparing the operators or functions, if necessary. For example:

  • -2.0 and -2 are equal;
  • -2.0 is less main than -1;
  • pi is more main than 4;
  • x is more main than 4;
  • x is less main than r;
  • x is more main than ln(y);
  • x is less main than ln(x).
Note: Both expressions should be in internal canonic form (see push_internal_simplify), else this function may not work as expected.

Uses: lead_base_index, next_expression_index, cmpstri, strcmp, compare_numbers, Integer1Index, primary_tag_list, ROM Call 0x5E2
Used by: cmd_sorta, cmd_sortd, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_max2, push_median, push_min, push_min2, push_nsolve, push_numerator, push_phase, push_re, push_sign, push_sin2, push_solve, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_or, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, did_push_divide_units, get_ub, GM_Intersect, index_if_pushed_binomial_info, index_if_pushed_qquad_info, next_var_or_kernel_index, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_deg_in_var_or_kernel, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x48D


compare_Floats

compare_Floats Function (ROM Call 0x2F7)
AMS 1.01 or higher estack.h

long compare_Floats (CESI ptr1, CESI ptr2);

Compares two floating point entries on the expression stack.

compare_Floats compares two floating point entries on the expression stack pointed to by ptr1 and ptr2, and returns a value which is

  • < 0 if the number pointed to by ptr1 is less than the number pointed to by ptr2
  • == 0 if the number pointed to by ptr1 is the same as the number pointed to by ptr2
  • > 0 if the number pointed to by ptr1 is greater than the number pointed to by ptr2
So, this function is similar like fcmp, except the arguments are different (fcmp uses floating point arguments, and compare_Floats uses pointers to floating point entries on the expression stack).

Uses: estack_to_float, _bcd_math
Used by: push_asin, push_dot_exponentiate, GetStatValue


CreateEmptyList

CreateEmptyList Function (ROM Call 0x1E6)
estack.h

HANDLE CreateEmptyList (void);

Creates a MULTI_EXPR containing an empty list and returns its handle.

This function throws an error if there is not enough memory to allocate the handle.

Uses: HeapAllocThrow
Used by: cmd_clrtable, gdb_recall


delete_between

delete_between Function (ROM Call 0x2C3)
AMS 1.01 or higher estack.h

void delete_between (ESI ptr1, ESI ptr2);

Deletes a sequence of bytes from the expression stack.

delete_between deletes a sequence of bytes between ptr1 and ptr2 (more precise, starting at ptr1+1 and ending at ptr2) from the expression stack. It does this by moving the memory from ptr2+1 to top_estack downwards (using memmove) and adjusting top_estack. This routine assumes that ptr1 and ptr2 really point to parts of the expression stack and that ptr2 is above ptr1, otherwise the result is unpredictable.

Uses: top_estack, memmove
Used by: compare_complex_magnitudes, delete_expression, did_push_cnvrt_Float_to_integer, index_below_display_expression_aux, map_tail, map_tail_Int, move_between_to_top, NG_graphESI, Parse2DExpr, Parse2DMultiExpr, push_Float_to_nonneg_int, push_internal_simplify, push_parse_text, push_round_Float, push_transpose_aux, cmd_fill, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_colnorm, push_comb, push_comdenom, push_conj, push_cosh, push_cross_product, push_csolve, push_cumsum, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_diag, push_dotproduct, push_eigvc, push_eigvl, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_im, push_integer_lcm, push_integer_part, push_integer_quotient, push_integer_remainder, push_is_prime, push_left, push_lim, push_list_to_mat, push_ln, push_log10, push_matnorm, push_max, push_max1, push_median, push_mid, push_min, push_min1, push_mod, push_mrowadd, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_part, push_perm, push_phase, push_pttest, push_pxltest, push_rand, push_randpoly, push_re, push_rec_to_angle, push_red_row_ech, push_right, push_rotate, push_round, push_row_echelon, push_rowadd, push_rowdim, push_rownorm, push_rowswap, push_sequence, push_shift, push_sign, push_simult, push_sin2, push_sinh, push_solve, push_stddev, push_str_to_expr, push_submat, push_summation, push_tan, push_tanh, push_variance, push_zeros, did_push_to_polar, push_and, push_dot_exponentiate, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_indir_name, push_less_than, push_less_than_or_equals, push_list_plus, push_list_times, push_matrix_product, push_negate, push_not, push_not_equals, push_or, push_product, push_substitute_no_simplify, push_substitute_simplify, push_substitute_using_such_that, push_sum, push_to_cylin, push_to_sphere, push_xor, add_to_top, are_units_consistent, compare_numbers, de_loop, did_map_aggregate_arg, did_push_approx_inflection_point, EQU_getNameInfo, get_ub, GM_Intersect, GM_Math1, index_if_pushed_binomial_info, index_if_pushed_qquad_info, is_term_improper, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_div_dif_1f, push_float_qr_fact, push_format, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_mrow_aux, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_poly_deg_in_var_or_kernel, push_poly_qr, push_reciprocal, push_simplify, push_simplify_statements, push_sq_matrix_to_whole_number, push_standardize, push_symbolic_qr_fact, push_trig, push_user_func, push_zero_partial_column, raise_to_top, replace_top_with_post_simplified, replace_top2_with_and, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, tokenize_if_TI_92_or_text, ROM Call 0x468, ROM Call 0x48D, push_to_dms, push_subscripted_element, ROM Call 0x4E6


delete_expression

delete_expression Function (ROM Call 0x2C5)
AMS 1.01 or higher estack.h

void delete_expression (ESI ptr);

Deletes an expression from the expression stack.

delete_expression deletes an entry on the expression stack pointed to by ptr (it needs to point to the entry tag) from the stack. The entry need not be a simple entity; it may be a complex symbolic expression too. This is achieved by calling next_expression_index and delete_between.

Uses: delete_between, next_expression_index
Used by: push_parse_text, cmd_sinreg, cmd_sorta, cmd_sortd, did_push_anti_deriv, did_push_series, push_1st_derivative, push_atan, push_atanh, push_coldim, push_comdenom, push_conj, push_cross_product, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_dimension, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_nsolve, push_numerator, push_phase, push_randmat, push_randpoly, push_re, push_red_row_ech, push_round, push_row_echelon, push_rowdim, push_sequence, push_simult, push_sin2, push_solve, push_stddev, push_summation, push_unitv, push_variance, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_radians, push_sum, push_to_cylin, push_to_sphere, add_to_top, and_onto_top, are_units_consistent, divide_top, EQU_getNameInfo, get_ub, index_if_pushed_qquad_info, or_onto_top, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top_with_reciprocal, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, times_top, ROM Call 0x468, push_to_dms


deleted_between

deleted_between Function (ROM Call 0x2C4)
AMS 1.01 or higher estack.h

unsigned short deleted_between (ESI ptr1, ESI ptr2);

Deletes a sequence of bytes from the expression stack.

deleted_between acts like delete_between, but it also returns a number of deleted bytes. Note that delete_between calls memmove for moving memory after ptr2, but deleted_between uses an embedded loop sequence for the same task. I don't know why these two routines use different methods: as I can see, the final effect is the same. Maybe I am wrong?

Uses: top_estack
Used by: deleted_expression, moved_between_to_top, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_is_prime, push_lim, push_ln, push_log10, push_max, push_min, push_nsolve, push_nth_derivative, push_numerator, push_perm, push_phase, push_re, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_float_qr_fact, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, push_symbolic_qr_fact, raise_to_top, replace_top_with_post_simplified, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_sum


deleted_expression

deleted_expression Function (ROM Call 0x2C6)
AMS 1.01 or higher estack.h

unsigned short deleted_expression (ESI ptr);

Deletes an expression from the expression stack.

deleted_expression acts like delete_expression, but it also returns a number of deleted bytes. It calls deleted_between instead of delete_between.

Uses: deleted_between, next_expression_index
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


did_push_cnvrt_Float_to_integer

did_push_cnvrt_Float_to_integer Function (ROM Call 0x2F8)
AMS 1.01 or higher estack.h

short did_push_cnvrt_Float_to_integer (CESI ptr);

Pushes a floating point entry converted to an integer, but only if it is an exact whole number.

did_push_cnvrt_Float_to_integer is a subroutine used in push_cnvrt_integer_if_whole_nmb. It assumes that ptr points to a floating point entry. If it is a whole number (including big numbers too), did_push_cnvrt_Float_to_integer pushes the number converted to a tagged integer to the expression stack, and returns TRUE, otherwise it does nothing and returns FALSE.

Uses: delete_between, push_expression, push_Float, push_Float_to_nonneg_int, top_estack, fabs, fmod, estack_to_float, _bcd_math
Used by: push_cnvrt_integer_if_whole_nmb, push_extended_prod, push_sin2, push_summation


display_statements

display_statements Function (ROM Call 0x4E)
estack.h

HANDLE display_statements (CESI ptr, unsigned short Newlines, unsigned short FullPrec);

Converts tokenized expressions or TI-Basic statements to the printable form.

display_statements converts the expression (or a group of tokenized TI-Basic statements) pointed to by ptr from RPN form to the standard printable ("algebraic") form, and returns a handle to the memory block where the converted string is stored (you don't need to allocate anything by yourself, this function will do it instead; note that this routine may cause heap compression). It will return H_NULL if memory is full. Newline is a Boolean flag: when it is nonzero, all newline characters will be replaced with ':', otherwise they will remain intact. FullPrec is also a Boolean flag: when it is non-zero, all floating point values will be converted using the maximal precision (14 digits), else current precision settings (from TI-Basic MODE dialog) will be used. Here is an illustrative example for usage of this command (take a look at the "Integrate" example as well):

push_parse_text ("expand((x+1)(x+2)(x+3))");
NG_rationalESI (top_estack);
handle = display_statements (top_estack, 1, 1);
printf_xy (0, 40, "%s", HeapDeref (handle));
HeapFree (handle);
See push_parse_text, NG_rationalESI, HeapDeref and HeapFree to understand how this example works.

Note: Handles returned by display_statements aren't locked so any heap compression will move the block associated with the handle. Therefore it is safer to lock them using HLock and HeapUnlock than to just dereference them using HeapDeref.

display_statements will always convert expressions into the "canonic printing (external) form". For example, both x*3 and 3*x will be displayed as 3*x, x*y^(-1) will be displayed as x/y etc.

Note: Although display_statements is very similar to Parse1DExpr and both of them may usually be used for the same purposes, display_statements is used in TIOS for printing TI-Basic statements (from programs) and for the detokenization (in NG_RPNToText), and Parse1DExpr is used for printing expressions.

Uses: index_below_display_expression_aux, HeapAlloc, HeapFree, HeapLock, HeapRealloc, HeapUnlock, HLock, ER_catch, ER_success, ER_throwVar, OSDisableBreak, OSEnableBreak, ROM Call 0x5CB
Used by: NG_RPNToText, handleRclKey, TE_handleEvent, tokenize_if_TI_92_or_text


divide_top

divide_top Function (ROM Call 0x527)
AMS 2.02 or higher estack.h

void divide_top (CESI ptr);

Divides the expression onto the EStack.

divide_top divides the expression currently at the top of the EStack by the expression pointed to by ptr, and stores the result to the top of the EStack, in place of the expression that was divided by.

Uses: Float0Index, is_complex_Float, primary_tag_list, push_reciprocal, replace_top2_with_imre, replace_top2_with_prod, push_dot_div, delete_expression, estack_number_to_Float, is_complex_number, next_expression_index, push_expression, push_Float, top_estack, _bcd_math
Used by: get_ub, push_reciprocal, push_standardize, push_symbolic_qr_fact, cmd_endfor, cmd_for, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_lim, push_max, push_median, push_min, push_nsolve, push_sequence, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum

See also: times_top


estack_number_to_Float

estack_number_to_Float Function (ROM Call 0x2F9*)
AMS 1.01 or higher estack.h

float estack_number_to_Float (CESI ptr);

Converts entry on the expression stack to floating point number.

estack_number_to_Float converts an entry on the expression stack pointed to by ptr (it needs to point to the entry tag) to a floating point value and returns the result. Note that the entry need not be represented by FLOAT_TAG: it also may be represented by an integer, or by a fraction. This function does not remove the entry from the stack.

Note: estack_number_to_Float will throw an error if the entry on the stack is not a floating point number, a fraction or an integer, so you will need to use ER_catch to catch eventual errors.

Uses: min_quantum, round14, estack_to_float, _bcd_math
Used by: compare_complex_magnitudes, push_round_Float, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_factor, push_floor, push_im, push_integer_lcm, push_is_prime, push_lim, push_max, push_min, push_mod, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_rand, push_re, push_sin2, push_solve, push_tan, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_ratio, push_sum, push_to_cylin, push_to_sphere, atof, add_to_top, are_units_consistent, compare_numbers, divide_top, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top


estack_to_short

estack_to_short Function (ROM Call 0x2C7)
AMS 1.01 or higher estack.h

short estack_to_short (CESI ptr, short *value_ptr);

Converts entry on the expression stack to signed short integer.

estack_to_short converts an entry on the expression stack pointed to by ptr (it needs to point to the entry tag) to a signed short integer and stores the result in the location pointed to by value_ptr. Note that the entry need not be represented by POSINT_TAG or NEGINT_TAG: it also may be represented by FLOAT_TAG for example, but the value itself needs to be a whole number. This function does not remove the entry from the stack.

estack_to_short returns 1 if the conversion was successful, 0 in the case of overflow (in this case the stored result will be -32768 or 32767 depending of the direction of the overflow), and -1 if the entry cannot be represented as a whole number (in this case the result is undefined).

Uses: estack_to_float, is_whole_number, is0, _bcd_math
Used by: GetValue, cmd_output, push_ans_entry, push_sq_matrix_to_whole_number


estack_to_ushort

estack_to_ushort Function (ROM Call 0x2C8)
AMS 1.01 or higher estack.h

short estack_to_ushort (CESI ptr, unsigned short *value_ptr);

Converts entry on the expression stack to unsigned short integer.

estack_to_ushort converts an entry on the expression stack pointed to by ptr (it needs to point to the entry tag) to a unsigned short integer and stores the result in the location pointed to by value_ptr. Note that the entry need not be represented by POSINT_TAG or NEGINT_TAG: it also may be represented by FLOAT_TAG for example, but the value itself needs to be a whole number. This function does not remove the entry from the stack.

estack_to_short returns 1 if the conversion was successful, 0 in the case of overflow (in this case the stored result will be 0 or 65535 depending of the direction of the overflow), and -1 if the entry cannot be represented as a whole number (in this case the result is undefined).

Uses: estack_to_float, is_whole_number, is0, _bcd_math, ROM Call 0x4E2
Used by: GetValue, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_sinreg, cmd_style, cmd_twovar, push_char, push_instring, push_left, push_mid, push_randpoly, push_right, push_rotate, push_shift, store_to_subscripted_element, push_subscripted_element, DateAndTime_SetDlg


ESTACK

ESTACK Function (Macro)
estack.h

#define ESTACK(idx) (*(idx))

Reads the expression stack at a specific index.

The ESTACK macro can be used to read the expression stack at the index idx. It simply dereferences idx, since the ESI and CESI types are in fact pointers to quantums of type ESQ.


factor_base_index

factor_base_index Function (ROM Call 0x2C9)
AMS 1.01 or higher estack.h

ESI factor_base_index (CESI ptr);

Gets the index of the base of an expression.

If ptr points to the POW_TAG, which is a case when it points to an expression of form base ^ exponent factor_base_index returns the pointer to base. If ptr does not point to the POW_TAG, factor_base_index returns ptr (i.e. the pointer to the expression itself).

Used by: is_monomial_in_kernel, lead_base_index, did_push_anti_deriv, did_push_series, push_1st_derivative, push_atan, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, is_units_term, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


factor_exponent_index

factor_exponent_index Function (ROM Call 0x2CA)
AMS 1.01 or higher estack.h

ESI factor_exponent_index (CESI ptr);

Gets the index of the exponent of an expression.

If ptr points to the POW_TAG, which is a case when it points to an expression of form base ^ exponent factor_exponent_index returns the pointer to exponent. If ptr does not point to the POW_TAG, factor_exponent_index returns a pointer to a simple expression which consists only of the number 1 (floating point or integer, depending on whether the approximation mode is active or not).

Uses: next_expression_index, Integer1Index
Used by: lead_exponent_index, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_atan, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, is_term_improper, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


gcd_exact_whole_Floats

gcd_exact_whole_Floats Function (ROM Call 0x2FC*)
AMS 1.01 or higher estack.h

float gcd_exact_whole_Floats (CESI ptr1, CESI ptr2);

Finds the greatest common divisor of two floating point entries.

gcd_exact_whole_Floats finds the greatest common divisor of two floating point entries pointed to by ptr1 and ptr2 and returns the result (the result is a garbage if ptr1 or ptr2 doesn't point to floating point entries).

Note: Although the name of the function suggests that both entries need to be whole numbers, this is not true. This function, in fact, returns "generalized" GCD of two numbers x and y which is defined as the greatest number z which has a property that both x/z and y/z are whole numbers.

Uses: fabs, fmod, estack_to_float, _bcd_math
Used by: push_gcd_numbers


get_key_ptr

get_key_ptr Function (ROM Call 0x2B7)
AMS 1.01 or higher estack.h

char *get_key_ptr (ESQ Tag1, ESQ Tag2);

Converts a tag code to a tag name.

get_key_ptr returns a static pointer to the string which represents the name of the tag Tag1. Tag2 is used only if Tag1 is an extended tag (i.e. EXT_TAG, EXT_INSTR_TAG or EXT_SYSTEM_TAG) which can't be fully represented using only one byte.

If the tag corresponds to a function, AMS 1.xx does not append '(' at the end of the string, but AMS 2.xx does. Thus, anyone who intends to use this function for function tokens should use extra code to handle both cases.

Uses: XR_stringPtr
Used by: index_below_display_expression_aux, push_part


GetValue

GetValue Function (ROM Call 0x2CB)
AMS 1.01 or higher estack.h

long GetValue (CESI ptr, long low, long high);

Converts entry on the expression stack to short integer and checks whether it is in a given range.

GetValue converts an entry on the expression stack pointed to by ptr (it needs to point on the entry tag) to a short integer value using estack_to_short or estack_to_ushort, depending on the sign of low. Then, a "Domain Error" is thrown if the value is smaller than low or greater than high, otherwise the value will be returned as the result of the function. It will also throw a "Data type" error if the entry cannot be represented as an integer.

Uses: estack_to_short, estack_to_ushort, primary_tag_list
Used by: cmd_andpic, cmd_circle, cmd_cyclepic, cmd_dialog, cmd_line, cmd_linehorz, cmd_linevert, cmd_newpic, cmd_newplot, cmd_plotsoff, cmd_plotson, cmd_popup, cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pttext, cmd_pxlchg, cmd_pxlcircle, cmd_pxlhorz, cmd_pxlline, cmd_pxloff, cmd_pxlon, cmd_pxltext, cmd_pxlvert, cmd_rclpic, cmd_rplcpic, cmd_shade, cmd_stopic, cmd_xorpic, push_identity_mat, push_list_to_mat, push_mrow, push_mrowadd, push_newlist, push_newmat, push_part, push_pttest, push_pxltest, push_randmat, push_rowadd, push_rowdim, push_rowswap, push_submat


HS_popEStack

HS_popEStack Function (ROM Call 0x244)
homescr.h, estack.h

HANDLE HS_popEStack (void);

Pops the entire expression stack into memory.

HS_popEStack allocates a block in memory, pops the entire expression stack into the allocated block, and returns a handle which points to it. More precisely, it creates a MULTI_EXPR structure holding the expression stack. If there is not enough memory, it throws an error. See NG_execute for an example of usage. The returned handle is allocated with HeapAllocHigh, and is therefore intended to be temporary. However, it is unlocked.

This function copies everything from bottom_estack to top_estack (including both bottom_estack and top_estack), and resets top_estack to bottom_estack. This means that the size of the allocated block is top_estack - bottom_estack + 3 (because the MULTI_EXPR structure reserves two bytes for the size). By changing bottom_estack temporarily, it is theoretically possible to set the block which is to be popped off manually. However, you need to take care of the requirement that bottom_estack has to point to an ENDSTACK_TAG quantum.

This function is intended to copy an expression into memory so that it can be pushed to the Home Screen using HS_pushFIFONode or one of its wrapper functions.

Uses: HeapAllocHigh, HeapUnlock, bottom_estack, top_estack, memcpy
Used by: HomeExecute


HToESI

HToESI Function (ROM Call 0x247)
estack.h

ESI HToESI (HANDLE Handle);

Converts a handle to an expression stack index.

HToESI is a simple but very useful routine. It returns a pointer to the last byte of the MULTI_EXPR structure referenced by Handle. Therefore it allows for the use of TIOS variables as input data in expression stack routines. Assuming that Handle is a handle of a TIOS variable which contains an expression, HToESI will return a pointer to the tag of the expression contained in the variable. Such a pointer may be used in any routine which needs an argument of type CESI, like NG_approxESI, etc. (except in functions which manipulate the actual memory space on the expression stack, like delete_between). In fact, HToESI simply dereferences Handle and adds the size plus 1 to the address. It also may be used to determine the type of a TIOS variable, because after execution the result points to the data type tag of the variable data.

Note: If the handle is not locked, HToESI must be called again after a heap compression since the block of memory associated with the handle may have moved.

Used by: NG_execute, NG_RPNToText, cmd_andpic, cmd_archive, cmd_blddata, cmd_custom, cmd_cyclepic, cmd_dialog, cmd_fill, cmd_get, cmd_newdata, cmd_popup, cmd_rclpic, cmd_request, cmd_rplcpic, cmd_showstat, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_toolbar, cmd_unarchiv, cmd_xorpic, push_gettype, EV_defaultHandler, EV_eventLoop, handleRclKey, handleVarLinkKey, FFindFirst, FFindNext, FOpen, FType, GR3_paint3d, gdb_recall, HomeExecute, HomePushEStack, HS_getAns, LIO_Receive, OSLinkCmd, sendcalc, TE_handleEvent, de_initRes, de_loop, dv_create_graph_titles, EQU_select, EQU_setStyle, FindGrFunc, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_ck_solvergraph, gr_de_value, gr_execute_seq, gr_find_el, gr_seq_value, InitTimeSeq, push_ans_entry, push_user_func, recall_data_var, Regraph, seqWebInit, setup_more_graph_fun, spike_geo_titles, spike_optionD, time_loop, tokenize_if_TI_92_or_text, unlock_more_graph_fun, VarStoreLink, checkCurrent, CheckLinkLockFlag, ClearUserDef, EM_moveSymToExtMem, VarRecall, VarStore, NG_setup_graph_fun, NG_cleanup_graph_fun, ROM Call 0x438, push_subscripted_element


im_index

im_index Function (ROM Call 0x2CC)
AMS 1.01 or higher estack.h

ESI im_index (CESI ptr);

Gets the index of the imaginary part of an expression.

If ptr points to the COMPLEX_TAG (i.e. if the expression is complex), im_index returns the pointer to the imaginary part of the expression. If ptr does not point to the COMPLEX_TAG (i.e. if the expression is real), im_index returns a pointer to a simple zero expression, i.e. expression which consists only of the number 0 (floating point or integer, depending on whether the approximation mode is active or not).

Note: The expression should be in internal canonic form (see push_internal_simplify), else this function is not reliable.

Uses: Float0Index, Integer0Index
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


index_below_display_expression_aux

index_below_display_expression_aux Function (ROM Call 0x2B6)
AMS 1.01 or higher estack.h

ESI index_below_display_expression_aux (CESI ptr);

Main routine for detokenizing.

index_below_display_expression_aux is main (recursive) routine for detokenizing. As it is just an auxiliary routine used in display_statements and Parse1DExpr, it shouldn't need to be used directly.

Uses: check_estack_size, delete_between, get_key_ptr, next_expression_index, push_between, top_estack, HeapLock, HeapRealloc, HeapUnlock, sprintf, strchr, strlen, XR_stringPtr, estack_max_index, estack_to_float, primary_tag_list, _ds32s32, _ms32s32, ROM Call 0x457, ROM Call 0x4DF, command_tag_list, ROM Call 0x5EF, ROM Call 0x5F0
Used by: display_statements, Parse1DExpr


index_main_var

index_main_var Function (ROM Call 0x2CF)
AMS 1.01 or higher estack.h

ESI index_main_var (CESI ptr);

Searches an expression for a first encountered variable.

index_main_var returns the index of the first encountered variable in the expression pointed to by ptr. More precise, it repeatedly decreases value of ptr by one until the tag of a variable, a number or a symbolic constant (like pi) is reached. As expressions are usually organized in "internal canonic" form (see notes given with description of numeric_factor_index) in which all constants are always "below" variables on the stack, a variable will always be reached before any constant, except if there are not any variables in the expression (in this case, a pointer to a constant is returned). Obviously, this function is not reliable if the expression is not in the internal canonic form (see push_internal_simplify).

Uses: primary_tag_list
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, replace_top_with_post_simplified


index_numeric_term

index_numeric_term Function (ROM Call 0x2CD)
AMS 1.01 or higher estack.h

ESI index_numeric_term (CESI ptr);

Searches terms in the expression for a numeric term.

If ptr points to the ADD_TAG, which is a case when it points to an expression of form term1 + term2 + ... (i.e. if the expression is a sum of simpler terms), index_numeric_term returns the pointer to the eventual numeric term in the expression. If the expression is a number, index_numeric_term returns ptr (i.e. the pointer to the expression itself). If ptr does not point to the ADD_TAG (i.e. if the expression is not a sum of simpler terms), or if there are not any numeric terms in the expression, index_numeric_factor returns a pointer to a simple expression which consists only of the number 0 (floating point or integer, depending on whether the approximation mode is active or not).

Note: This function is not implemented to be very universal. TIOS always "reorganizes" expressions on such way that numeric terms are at the beginning of the expression (for example, x+3 will be reorganized into 3+x, although it will be displayed just reversed, i.e. as x+3), and this function assumes that the expression is organized on such way. In other words, it must be in internal canonic form (such expressions always have at most one term with a numeric tag, in which case it is the deepest term). Fortunately, all expressions in argument are always in internal canonic form. However, this is not true after push_parse_text function, nor after an evaluation using NG_rationalESI or NG_approxESI. In other words, results of these commands are not always "correctly" organized. To force converting an expression to the internal canonic form, always call push_internal_simplify after usage of any of the functions mentioned above.

Uses: next_expression_index, Float0Index, Integer0Index, primary_tag_list
Used by: push_exp, push_sin2, push_exponentiate, push_factorial


index_of_lead_base_of_lead_term

index_of_lead_base_of_lead_term Function (ROM Call 0x2CE)
AMS 1.01 or higher estack.h

ESI index_of_lead_base_of_lead_term (CESI ptr);

Gets the index of the base of the lead term of an expression.

index_of_lead_base_of_lead_term first calls lead_term_index, then apply lead_base_index on the result. So, it returns the pointer to the base of the lead factor of the first term of the expression pointed to by ptr.

Uses: lead_base_index, lead_term_index
Used by: push_sum


init_list_indices

init_list_indices Function (ROM Call 0x2BA)
AMS 1.01 or higher estack.h

ESI *init_list_indices (ESI *indices, CESI expr);

Computes and stores the indices of the elements of a list.

init_list_indices stores the index of the first element to indices, then it repeatedly calls next_expression_index and stores the result to indices until END_TAG is reached.
expr is assumed to point to a LIST_TAG. init_list_indices returns indices.

Here is an example (called "List elements") which displays the list elements as returned by init_list_indices:

// Shows how the init_list_indices function works.

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

#define MIN_AMS 101           // Compile for AMS 1.01 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// The {1, 0, -1} list.
static const ESQ list_1_0_minus1[10] = {END_TAG, 0x01, 0x01, NEGINT_TAG, 0x00, POSINT_TAG, 0x01, 0x01, POSINT_TAG, LIST_TAG};

// Main Function
void _main(void)
{
  ESI elements[3];
  HANDLE h;

  TRY
    ClrScr();
    DrawStr (0, 0, "The elements of list", A_NORMAL);
    DrawStr (0, 20, "are", A_NORMAL);
    // Print whole expression.
    h = Parse1DExpr (list_1_0_minus1 + 9, FALSE, 0);
    DrawStr(0, 10, HeapDeref(h), A_NORMAL);
    HeapFree(h);

    // Get the individual constituents of the expression and print them.
    init_list_indices(elements, list_1_0_minus1 + 9);
    h = Parse1DExpr (elements[0], FALSE, 0);
    DrawStr(0, 30, HeapDeref(h), A_NORMAL);
    HeapFree(h);
    h = Parse1DExpr (elements[1], FALSE, 0);
    DrawStr(0, 40, HeapDeref(h), A_NORMAL);
    HeapFree(h);
    h = Parse1DExpr (elements[2], FALSE, 0);
    DrawStr(0, 50, HeapDeref(h), A_NORMAL);
    HeapFree(h);
  ONERR
    DrawStr (0, 70, "Error!", A_NORMAL);
  ENDTRY
  GKeyIn (NULL, 0);
}

Uses: next_expression_index
Used by: get_list_indices, push_symbolic_qr_fact, push_median


init_matrix_indices

init_matrix_indices Function (ROM Call 0x2BB)
AMS 1.01 or higher estack.h

ESI *init_matrix_indices (ESI *indices, CESI expr);

Computes and stores the indices of the elements of a matrix.

init_matrix_indices stores the index of the first element of the first row to indices, then it repeatedly calls next_expression_index and stores the result to indices until the END_TAG for the whole matrix is reached.
expr is assumed to point to a double LIST_TAG. init_matrix_indices returns indices.

Here is an example (called "Matrix elements") which displays the matrix elements as returned by init_matrix_indices:

// Shows how the init_matrix_indices function works.

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

#define MIN_AMS 101           // Compile for AMS 1.01 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// The [1, 0; 0, 1] matrix.
static const ESQ matrix_identity_2[16] = {END_TAG, END_TAG, 0x01, 0x01, POSINT_TAG, 0x00, POSINT_TAG, LIST_TAG, END_TAG, 0x00, POSINT_TAG, 0x01, 0x01, POSINT_TAG, LIST_TAG, LIST_TAG};

// Main Function
void _main(void)
{
  ESI elements[4];
  HANDLE h;

  TRY
    ClrScr();
    DrawStr (0, 0, "The elements of matrix", A_NORMAL);
    DrawStr (0, 20, "are", A_NORMAL);
    // Print whole expression.
    h = Parse1DExpr (matrix_identity_2 + 15, FALSE, 0);
    DrawStr(0, 10, HeapDeref(h), A_NORMAL);
    HeapFree(h);

    // Get the individual constituents of the expression and print them.
    init_matrix_indices(elements, matrix_identity_2 + 15);
    h = Parse1DExpr (elements[0], FALSE, 0);
    DrawStr(0, 30, HeapDeref(h), A_NORMAL);
    HeapFree(h);
    h = Parse1DExpr (elements[1], FALSE, 0);
    DrawStr(0, 40, HeapDeref(h), A_NORMAL);
    HeapFree(h);
    h = Parse1DExpr (elements[2], FALSE, 0);
    DrawStr(0, 50, HeapDeref(h), A_NORMAL);
    HeapFree(h);
    h = Parse1DExpr (elements[3], FALSE, 0);
    DrawStr(0, 60, HeapDeref(h), A_NORMAL);
    HeapFree(h);
  ONERR
    DrawStr (0, 70, "Error!", A_NORMAL);
  ENDTRY
  GKeyIn (NULL, 0);
}

Uses: next_expression_index
Used by: get_matrix_indices, push_lu_fact, push_symbolic_qr_fact


integer_non_unknown

integer_non_unknown Function (ROM Call 0x50C)
AMS 2.02 or higher estack.h

short integer_non_unknown (CESI ptr);

Tests if an expression is an integer.

Returns 1 if the expression pointed to by ptr is an integer or floating-point value; returns -1 for constants like p or e. Returns 0 for everything else - this includes expressions like ln(2), 2p, or Ö(2).

Uses: is_nonnegative, is_whole_number, next_expression_index, is_real, primary_tag_list
Used by: is_never0, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_integer_part, push_lim, push_max, push_min, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


is0

is0 Function (ROM Call 0x269)
AMS 2.00 or higher estack.h

short is0 (CESI ptr);

Tests if an expression is equal to 0.

Returns TRUE if the expression pointed to by ptr is equal to zero (integer or floating point).

Uses: estack_to_float, primary_tag_list, _bcd_math
Used by: estack_to_short, estack_to_ushort, is_antisymmetric, is_complex0, is_never0, is_nonnegative, is_nonpositive, is_symmetric, cmd_dialog, cmd_endfor, cmd_for, cmd_passerr, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_integer_lcm, push_integer_quotient, push_integer_remainder, push_is_prime, push_lim, push_ln, push_max, push_min, push_mod, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_rand, push_randpoly, push_re, push_rec_to_angle, push_red_row_ech, push_row_echelon, push_sequence, push_simult, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, ST_eraseHelp, ST_modKey, add_to_top, are_units_consistent, did_push_approx_inflection_point, did_push_divide_units, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, push_symbolic_qr_fact, raise_to_top, replace_top_with_post_simplified, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, times_top, push_to_dms

See also: is1, is_minus1, is_never0


is1

is1 Function (ROM Call 0x2FD)
AMS 2.00 or higher estack.h

short is1 (CESI ptr);

Tests if an expression is equal to 1.

Returns TRUE if the expression pointed to by ptr is equal to one (integer or floating point).

Uses: estack_to_float, _bcd_math
Used by: is_never0, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_mod, push_nsolve, push_numerator, push_phase, push_re, push_sign, push_sin2, push_sinh, push_solve, push_summation, push_tanh, push_zeros, did_push_to_polar, push_dot_exponentiate, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, index_reductum_with_tag_base, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum

See also: is0, is_minus1


is_advanced_tag

is_advanced_tag Function (ROM Call 0x2D0)
AMS 1.01 or higher estack.h

short is_advanced_tag (ESQ Tag);

Checks whether a tag is an advanced tag.

is_advanced_tag returns TRUE if a byte Tag is an advanced tag, otherwise it returns FALSE. Advanced tags are all tags which do not represent a variable, a number (integer, fraction or float) or an expression which consists only of simple operations "+", "-", "*", "/" and "^" (including element-by-element versions "+.", "-.", "*.", "/." and "^.").

Uses: primary_tag_list
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_factor, push_floor, push_lim, push_max, push_min, push_nsolve, push_phase, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, get_ub, push_but_term, push_constant_terms, push_dependent_terms, push_gcd_then_cofactors, push_independent_terms, push_make_proper, push_nonconstant_terms, push_poly_qr, push_standardize, replace_top_with_post_simplified, replace_top2_with_sum


is_antisymmetric

is_antisymmetric Function (ROM Call 0x2D1)
AMS 1.01 or higher estack.h

short is_antisymmetric (CESI expr_ptr, CESI var_ptr);

Checks for a antisymmetry.

is_antisymmetric returns TRUE if the expression pointed to by expr_ptr is such that it changes the sign but keeps the same magnitude when the variable pointed to by var_ptr changes it sign, otherwise it returns FALSE.

Uses: top_estack, push_negate, push_substitute_simplify, add_to_top, is0
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


is_complex0

is_complex0 Function (ROM Call 0x2D3)
AMS 1.01 or higher estack.h

short is_complex0 (CESI ptr);

Checks whether an expression is reducible to zero.

is_complex0 returns TRUE if the expression pointed to by ptr is a zero (signed, unsigned, or even complex), otherwise it returns FALSE.

Note: The information about this routine in releases of TIGCCLIB before 2.3 was wrong.

Uses: next_expression_index, is0
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, is_equivalent_to


is_complex_number

is_complex_number Function (ROM Call 0x2D2)
AMS 1.01 or higher estack.h

short is_complex_number (CESI ptr);

Checks whether an expression is a number.

is_complex_number returns TRUE if the expression (in RPN form, of course) pointed to by ptr is a "number" (integer, rational, floating point, or complex, but not irrational), otherwise it returns FALSE. Note that 'sqrt(2)' is not a "number" in this convention. A complex number is a "number" if both real and imaginary parts are "numbers" in a sense of the convention given above.

Note: The information about this routine in releases of TIGCCLIB before 2.3 was wrong.

Uses: next_expression_index, primary_tag_list
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_ratio, divide_top, get_ub, replace_top2_with_ratio

See also: likely_approx_to_number


is_constant

is_constant Function (ROM Call 0x593)
AMS 2.02 or higher estack.h

short is_constant (CESI ptr);

Checks whether an expression is constant.

is_constant returns TRUE if the expression pointed to by ptr does not rely on any variables (initialized, built-in, but not constants like p), otherwise it returns FALSE.

Uses: all_tail, next_expression_index, primary_tag_list
Used by: is_totally_polynomial, did_push_anti_deriv, did_push_series, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_determinant, push_expand, push_extended_prod, push_factor, push_floor, push_left, push_lim, push_max, push_mid, push_min, push_nsolve, push_phase, push_prodlist, push_red_row_ech, push_right, push_row_echelon, push_simult, push_sin2, push_solve, push_sumlist, push_summation, push_zeros, did_push_to_polar, push_dot_exponentiate, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, push_internal_simplify, add_to_top, did_push_approx_inflection_point, get_ub, GM_Intersect, GM_Math1, push_but_term, push_constant_factors, push_constant_terms, push_dependent_terms, push_gcd_then_cofactors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_poly_qr, push_simplify, push_sq_matrix_to_whole_number, push_standardize, push_user_func, replace_top_with_post_simplified, replace_top2_with_sum, cmd_lu_fact, cmd_qr_fact, ROM Call 0x48D, push_dense_poly_eval


is_Float_exact_whole_number

is_Float_exact_whole_number Function (ROM Call 0x2FE)
AMS 1.01 or higher estack.h

short is_Float_exact_whole_number (CESI ptr);

Checks whether a floating point entry is an exact whole number.

is_Float_exact_whole_number returns TRUE if the floating point entry pointed to by ptr is an exact whole number whose magnitude is less than the smallest whole number that is not represented exactly (1e15), otherwise it returns FALSE.

Uses: fabs, fmod, estack_to_float, _bcd_math
Used by: push_gcd_numbers


is_free_of_tag

is_free_of_tag Function (ROM Call 0x2D4)
AMS 1.01 or higher estack.h

short is_free_of_tag (CESI ptr, ESQ Tag);

Checks whether an expression is free of a particular tag.

is_free_of_tag is a recursive function which returns TRUE if the expression structure pointed to by ptr is free of tag Tag, otherwise it returns FALSE.

Uses: next_expression_index, primary_tag_list
Used by: push_internal_simplify, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_determinant, push_exp, push_extended_prod, push_factor, push_lim, push_ln, push_log10, push_max, push_max2, push_min, push_min2, push_nsolve, push_rec_to_angle, push_red_row_ech, push_row_echelon, push_simult, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_dot_exponentiate, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_radians, push_to_cylin, push_to_sphere, did_push_approx_inflection_point, get_ub, GM_Intersect, GM_Math1, push_float_qr_fact, push_lu_fact, push_simplify, push_sq_matrix_to_whole_number, push_trig, push_user_func, cmd_lu_fact, cmd_qr_fact, push_cylin_vector, push_spher_vector, push_to_dd, push_to_dms, push_polar_to_rect_x, push_polar_to_rect_y


is_independent_of_de_seq_vars

is_independent_of_de_seq_vars Function (ROM Call 0x2D6)
AMS 1.01 or higher estack.h

short is_independent_of_de_seq_vars (CESI ptr);

Checks whether an expression is independent of differential equation and sequence variables.

is_independent_of_de_seq_vars returns TRUE if the expression pointed to by expr_ptr is independent of system variables which are used for differential equation and sequence graphing (i.e. variables u1-u99 and y1'-y99'), otherwise it returns FALSE.

Uses: next_expression_index, CTypeTable, primary_tag_list


is_independent_of_elements

is_independent_of_elements Function (ROM Call 0x2D8)
AMS 1.01 or higher estack.h

short is_independent_of_elements (CESI expr_ptr, CESI varlist_ptr);

Checks whether an expression is independent of the elements of a list.

is_independent_of_elements is very similar to is_independent_of_tail. Assuming that varlist_ptr points to the list of variables or expressions (more precise, to the LIST_TAG of such list), is_independent_of_elements returns TRUE if the expression pointed to by expr_ptr is independent of all variables from the list pointed to by varlist_ptr, otherwise it returns FALSE. More precisely,

is_independent_of_elements (expr_ptr, varlist_ptr)
is the same as
is_independent_of_tail (expr_ptr, varlist_ptr - 1)

Uses: is_independent_of_tail
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_substitute_using_such_that, get_ub


is_independent_of_tail

is_independent_of_tail Function (ROM Call 0x2D7)
AMS 1.01 or higher estack.h

short is_independent_of_tail (CESI expr_ptr, CESI start_ptr);

Checks whether an expression is independent of a sequence of variables (or expressions).

is_independent_of_tail returns TRUE if the expression pointed to by expr_ptr is independent of all entries on the expression stack stored below start_ptr up to END_TAG tag, otherwise it returns FALSE.

Uses: is_independent_of, next_expression_index
Used by: is_independent_of_elements, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, ROM Call 0x4E6

See also: is_independent_of, is_independent_of_elements, map_tail, all_tail


is_independent_of

is_independent_of Function (ROM Call 0x2D5)
AMS 1.01 or higher estack.h

short is_independent_of (CESI expr_ptr, CESI var_ptr);

Checks whether an expression is independent of a variable (or expression).

is_independent_of returns TRUE if the expression pointed to by expr_ptr is independent of the variable pointed to by var_ptr, else returns FALSE. Although var_ptr may point to something which is not a variable, the independence of the "expression" is not well defined, so avoid such situations until more information about what such "independence" means (TI says that this means "syntactical independence", but this is not well defined either).

Note: This routine (and all other "independence" routines also) is not reliable if expressions are not in internal canonic form (see push_internal_simplify).

Uses: are_expressions_identical, is_tail_independent_of, next_expression_index, primary_tag_list
Used by: is_independent_of_tail, is_monomial_in_kernel, is_tail_independent_of, push_internal_simplify, did_push_anti_deriv, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_extended_prod, push_factor, push_lim, push_max, push_min, push_nsolve, push_nth_derivative, push_solve, push_summation, push_zeros, push_and, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_substitute_using_such_that, are_units_consistent, did_push_lincf, get_ub, is_polynomial_in_var_or_kern, push_dependent_factors, push_dependent_terms, push_independent_factors, push_independent_terms, push_simplify, ROM Call 0x468, ROM Call 0x4E6


is_matrix

is_matrix Function (ROM Call 0x3B7)
AMS 1.01 or higher estack.h

short is_matrix (CESI ptr);

Checks whether an expression is a matrix.

is_matrix returns TRUE if the expression pointed to by ptr is a matrix (i.e. a list which consists of equally sized lists), otherwise it returns FALSE.

Uses: next_expression_index, remaining_element_count
Used by: is_square_matrix, push_coldim, push_colnorm, push_determinant, push_mat_to_list, push_matnorm, push_median, push_mrow, push_mrowadd, push_red_row_ech, push_row_echelon, push_rowadd, push_rowdim, push_rownorm, push_rowswap, push_sequence, push_simult, push_submat, push_unitv, cmd_lu_fact, cmd_qr_fact, push_transpose


is_minus1

is_minus1 Function (ROM Call 0x508)
AMS 2.02 or higher estack.h

short is_minus1 (CESI ptr);

Tests if an expression is equal to -1.

Returns TRUE if the expression pointed to by ptr is equal to negative one (integer or floating point).

Uses: estack_to_float, _bcd_math
Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere

See also: is0, is1


is_monomial_in_kernel

is_monomial_in_kernel Function (ROM Call 0x2DA)
AMS 1.01 or higher estack.h

short is_monomial_in_kernel (CESI ptr);

Checks whether an expression is a monomial in kernel.

is_monomial_in_kernel returns TRUE if the expression pointed to by ptr is a monomial in kernel, i.e. if it is a monomial function of kernels, where "kernel" means any irrational subexpression, else returns FALSE. For example, 'sin(x)*ln(y)' is not monomial (in respect to 'x' and 'y'), but it is monomial in kernel (in respect to 'sin(x)' and 'ln(y)').

Uses: are_expressions_identical, factor_base_index, is_independent_of, lead_factor_index, remaining_factors_index, primary_tag_list
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


is_monomial

is_monomial Function (ROM Call 0x2D9)
AMS 1.01 or higher estack.h

short is_monomial (CESI ptr);

Checks whether an expression is a monomial.

is_monomial returns TRUE if the expression pointed to by ptr is a monomial expression, otherwise it returns FALSE. For example, the expression 'x*y^3' is a monomial, and x+y*z' or 'ln(x)' are not.

Uses: lead_base_index, remaining_factors_index
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum, get_ub, push_gcd_then_cofactors, push_make_proper


is_narrowly_independent_of

is_narrowly_independent_of Function (ROM Call 0x2DB)
AMS 1.01 or higher estack.h

short is_narrowly_independent_of (CESI expr_ptr, CESI var_ptr);

Checks whether an expression is narrowly independent of a variable (???).

is_narrowly_independent_of returns TRUE if the expression pointed to by expr_ptr is narrowly independent of the variable pointed to by var_ptr, otherwise it returns FALSE. I am not sure what "narrowly independent" really means, and what the difference between this function and is_independent_of is.

Uses: are_expressions_identical, next_expression_index, primary_tag_list
Used by: cmd_endfor, cmd_for, push_1st_derivative, push_factor, push_assignment, index_if_pushed_qquad_info, linear_degree


is_negative

is_negative Function (ROM Call 0x575)
AMS 2.02 or higher estack.h

short is_negative (CESI ptr);

Tests if an expression is less than 0.

Returns TRUE if the expression pointed to by ptr is known to be negative, FALSE otherwise.

Uses: are_expressions_identical, is_never0, is_nonnegative, is_nonpositive, is_positive, lead_factor_index, likely_approx_to_number, next_expression_index, push_internal_simplify, push_quantum, remaining_factors_index, top_estack, push_approx, push_difference, push_negate, add_to_top, estack_to_float, get_lb, get_ub, Integer1Index, IntegerMinus1Index, is_variable, lead_conjunct_factor_index, NG_control, NG_such_that_index, primary_tag_list, push_but_factor, push_pi_on_quantum, remaining_conjuncts_index, times_top, _bcd_math, ROM Call 0x4DF, push_exact_minus1
Used by: is_never0, is_positive, cmd_endfor, cmd_for, did_push_anti_deriv, push_1st_derivative, push_atan, push_comb, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_lim, push_ln, push_max, push_min, push_mod, push_nsolve, push_phase, push_rotate, push_sequence, push_shift, push_sin2, push_solve, push_summation, push_zeros, push_degrees, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, get_ub, push_reciprocal, ROM Call 0x48D, push_to_dd, push_to_dms, push_subscripted_element, ROM Call 0x606

See also: is_nonnegative, is_positive, is_nonpositive


is_never0

is_never0 Function (ROM Call 0x577)
AMS 2.02 or higher estack.h

short is_never0 (CESI ptr);

Tests if an expression is never 0.

Returns TRUE if the expression pointed to by ptr cannot be equal to zero.

Uses: are_expressions_identical, integer_non_unknown, is_negative, is_nonnegative, is_nonpositive, is_positive, is0, is1, likely_approx_to_number, next_expression_index, top_estack, push_approx, push_arg_minus_1, is_variable, lead_conjunct_factor_index, NG_such_that_index, primary_tag_list, remaining_conjuncts_index, ROM Call 0x4DF, ROM Call 0x4E2
Used by: is_negative, is_positive, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, get_ub

See also: is0


is_nonnegative

is_nonnegative Function (ROM Call 0x574)
AMS 2.02 or higher estack.h

short is_nonnegative (CESI ptr);

Tests if an expression is >= 0.

Returns TRUE if the expression pointed to by ptr is known to be positive or zero, FALSE otherwise.

Uses: are_expressions_identical, is_nonpositive, is_positive, is0, lead_factor_index, likely_approx_to_number, next_expression_index, push_internal_simplify, push_quantum, remaining_factors_index, top_estack, push_approx, push_difference, push_negate, add_to_top, estack_to_float, get_lb, get_ub, Integer1Index, IntegerMinus1Index, is_real, is_variable, lead_conjunct_factor_index, NG_control, NG_such_that_index, primary_tag_list, push_but_factor, push_pi_on_quantum, remaining_conjuncts_index, times_top, _bcd_math, ROM Call 0x4DF
Used by: integer_non_unknown, is_negative, is_never0, is_nonpositive, is_positive, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_atan, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_integer_part, push_lim, push_ln, push_max, push_max2, push_min, push_min2, push_mod, push_nint, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_rec_to_angle, push_red_row_ech, push_row_echelon, push_sign, push_simult, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_dot_exponentiate, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, is_real, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x606

See also: is_negative, is_positive, is_nonpositive


is_nonpositive

is_nonpositive Function (ROM Call 0x576)
AMS 2.02 or higher estack.h

short is_nonpositive (CESI ptr);

Tests if an expression is <= 0.

Returns TRUE if the expression pointed to by ptr is known to be negative or zero, FALSE otherwise.

Uses: are_expressions_identical, is0, is_nonnegative, lead_factor_index, likely_approx_to_number, next_expression_index, push_internal_simplify, push_quantum, remaining_factors_index, top_estack, push_approx, push_difference, push_negate, add_to_top, estack_to_float, get_lb, get_ub, Integer1Index, IntegerMinus1Index, is_variable, lead_conjunct_factor_index, NG_control, NG_such_that_index, primary_tag_list, push_but_factor, push_pi_on_quantum, remaining_conjuncts_index, times_top, _bcd_math, ROM Call 0x4E1, push_exact_minus1
Used by: is_negative, is_never0, is_nonnegative, did_push_anti_deriv, push_1st_derivative, push_abs, push_acosh, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_integer_part, push_lim, push_ln, push_max, push_max2, push_min, push_min2, push_nsolve, push_sign, push_solve, push_summation, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, get_ub, push_reciprocal

See also: is_positive, is_negative, is_nonnegative


is_polynomial_in_var_or_kern

is_polynomial_in_var_or_kern Function (ROM Call 0x56B)
AMS 2.02 or higher estack.h

short is_polynomial_in_var_or_kern (CESI test, CESI var_or_kern);

Checks if an expression is a polynomial with respect to another expression.

is_polynomial_in_var_or_kern returns TRUE if the expression pointed to by test is a polynomial with respect to the expression var_or_kern, otherwise it returns FALSE. The definition of "polynomial with respect to" is more complicated when dealing with expressions in var_or_kern. For example, "x+sin(x)" is polynomial with respect to "sin(x)" but not to "x". Interestingly, when testing with respect to "sin(x)", "x" seems to be treated like a constant.

Uses: are_expressions_identical, is_independent_of, is_whole_number, next_expression_index, primary_tag_list, ROM Call 0x4E2
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, index_if_pushed_binomial_info


is_pos_int_and_eq_quantum

is_pos_int_and_eq_quantum Function (ROM Call 0x509)
AMS 2.02 or higher estack.h

short is_pos_int_and_eq_quantum (CESI expr, ESQ num);

Determines whether expr points to the tag of a positive integer equal to num.

Returns TRUE if expr points to the tag of a positive integer equal to num, FALSE otherwise.
This function assumes that num is nonzero.

Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_atan, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


is_positive

is_positive Function (ROM Call 0x573)
AMS 2.02 or higher estack.h

short is_positive (CESI ptr);

Tests if an expression is greater than 0.

Returns TRUE if the expression pointed to by ptr is known to be positive (not zero), FALSE otherwise.

Uses: are_expressions_identical, is_negative, is_never0, is_nonnegative, lead_factor_index, likely_approx_to_number, next_expression_index, push_internal_simplify, push_quantum, remaining_factors_index, top_estack, add_to_top, estack_to_float, push_approx, push_difference, push_negate, get_lb, get_ub, Integer1Index, IntegerMinus1Index, is_real, is_variable, lead_conjunct_factor_index, NG_control, NG_such_that_index, primary_tag_list, push_but_factor, push_pi_on_quantum, remaining_conjuncts_index, times_top, _bcd_math, ROM Call 0x4E2
Used by: is_negative, is_never0, is_nonnegative, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_atanh, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_mod, push_nsolve, push_numerator, push_phase, push_re, push_rownorm, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, did_push_approx_inflection_point, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x48D, ROM Call 0x606

See also: is_nonpositive, is_negative, is_nonnegative


is_reciprocal_of_quantum

is_reciprocal_of_quantum Function (ROM Call 0x50A)
AMS 2.02 or higher estack.h

short is_reciprocal_of_quantum (CESI, ESQ);

Determines whether expr points to the tag of the reciprocal of ESQ num.

Returns TRUE if expr points to the tag of the fraction that is the reciprocal of ESQ num, FALSE otherwise.
This function assumes that num is nonzero.

Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_atan, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_tan, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere


is_square_matrix

is_square_matrix Function (ROM Call 0x3B8)
AMS 1.01 or higher estack.h

short is_square_matrix (CESI ptr);

Checks whether an expression is a square matrix.

is_square_matrix returns TRUE if the expression pointed to by ptr is a square matrix, otherwise it returns FALSE.

Uses: is_matrix, remaining_element_count
Used by: push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cosh, push_eigvc, push_eigvl, push_exp, push_ln, push_log10, push_sin2, push_sinh, push_tan, push_tanh, push_exponentiate, push_list_plus


is_symmetric

is_symmetric Function (ROM Call 0x2DC)
AMS 1.01 or higher estack.h

short is_symmetric (CESI expr_ptr, CESI var_ptr);

Checks for symmetry.

is_symmetric returns TRUE if the expression pointed to by expr_ptr is such that it remains the same when the variable pointed to by var_ptr changes its sign, otherwise it returns FALSE.

Uses: top_estack, push_negate, push_substitute_simplify, is0, subtract_from_top
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


is_tail_independent_of

is_tail_independent_of Function (ROM Call 0x2DD)
AMS 1.01 or higher estack.h

short is_tail_independent_of (CESI start_ptr, CESI var_ptr);

Checks whether a sequence of expressions is independent of a variable (or expression).

is_tail_independent_of returns TRUE if all expressions on the expression stack which are stored below start_ptr up to END_TAG are independent of the variable pointed to by var_ptr, otherwise it returns FALSE.

Uses: is_independent_of, next_expression_index
Used by: is_independent_of, next_expression_index, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, ROM Call 0x468, ROM Call 0x4E6

See also: is_independent_of, map_tail, all_tail


is_temperature_unit

is_temperature_unit Function (ROM Call 0x410)
AMS 2.00 or higher estack.h

short is_temperature_unit(CESI ptr);

Checks for strings of temperature units.

Checks if ptr points to the end of AMS strings (zero-padded at both sides) SYMSTR("_°C"), SYMSTR("_°K"), SYMSTR("_°F") and SYMSTR("_°R"), i.e. strings of temperature units.

Uses: are_expressions_identical
Used by: are_units_consistent, push_product


is_totally_polynomial

is_totally_polynomial Function (ROM Call 0x56C)
AMS 2.02 or higher estack.h

short is_totally_polynomial (CESI ptr);

Checks if an expression is polynomial in all variables.

is_totally_polynomial returns TRUE if the expression pointed to by ptr is polynomial with respect to all variables - that is, consists only of variables raised to positive constant powers (with coefficients) and multiplied or added together. Otherwise it returns FALSE.

Uses: is_constant, is_variable, next_expression_index
Used by: push_desolve


is_valid_smap_aggregate

is_valid_smap_aggregate Function (ROM Call 0x3B9)
AMS 1.01 or higher estack.h

short is_valid_smap_aggregate (CESI ptr);

Checks whether an expression is a valid aggregate type.

is_valid_smap_aggregate returns TRUE if the expression pointed to by ptr is a valid aggregate type (i.e. list or valid matrix), otherwise it returns FALSE. This is not a simple check whether a tag pointed to by ptr is LIST_TAG. For example, list which consists of lists which are not equally sized (like {{1,2,3},{4,5}}) are not valid. Also, matrices whose elements are list or matrices are also not valid aggregate types.

Uses: next_expression_index, remaining_element_count
Used by: push_parse_text, EQU_getNameInfo, push_parse_prgm_or_func_text


is_variable

is_variable Function (ROM Call 0x488)
AMS 2.00 or higher estack.h

short is_variable (CESI ptr);

Checks if the expression is a variable.

is_variable returns TRUE if the expression is a variable and FALSE if it is not.

Uses: primary_tag_list
Used by: is_negative, is_never0, is_nonnegative, is_nonpositive, is_positive, is_totally_polynomial, push_internal_simplify, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_atanh, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_mod, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_perm, push_phase, push_re, push_red_row_ech, push_row_echelon, push_rownorm, push_sign, push_simult, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, did_push_approx_inflection_point, did_push_lincf, get_ub, has_different_variable, index_if_pushed_qquad_info, is_real, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_simplify, push_sq_matrix_to_whole_number, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, times_top, ROM Call 0x4E6, ROM Call 0x606


is_whole_number

is_whole_number Function (ROM Call 0x50B)
AMS 2.02 or higher estack.h

short is_whole_number (CESI ptr);

Tests if an expression is a whole number.

Returns TRUE if the expression pointed to by ptr is a whole number (it can be a floating-point value).

Uses: fmod, estack_to_float, primary_tag_list, _bcd_math
Used by: estack_to_short, estack_to_ushort, integer_non_unknown, main_gen_var_index, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_char, push_comb, push_comdenom, push_conj, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_nsolve, push_numerator, push_perm, push_phase, push_rand, push_re, push_sign, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_dot_exponentiate, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, is_polynomial_in_var_or_kern, is_real, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


last_element_index

last_element_index Function (ROM Call 0x3BA)
AMS 1.01 or higher estack.h

ESI last_element_index (CESI ptr);

Searches for the last expression in the list.

last_element_index calls next_expression_index in a loop starting from ptr until END_TAG is reached, then returns the pointer to the last encountered expression before END_TAG. So, assuming that ptr points to a member of the list (including argument lists too), last_element_index will return the pointer to the last element of the list.

Uses: next_expression_index
Used by: push_desolve


lead_base_index

lead_base_index Function (ROM Call 0x2DE)
AMS 1.01 or higher estack.h

ESI lead_base_index (CESI ptr);

Gets the index of the base of the lead factor of an expression.

lead_base_index first calls lead_factor_index, then applies factor_base_index to the result. So, it returns the pointer to the base of the lead factor (i.e. the lead base) of the expression pointed to by ptr.

Uses: factor_base_index, lead_factor_index
Used by: compare_expressions, index_of_lead_base_of_lead_term, is_monomial, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sign, push_sin2, push_sinh, push_solve, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, did_push_divide_units, get_ub, has_unit_base, index_if_pushed_binomial_info, index_if_pushed_qquad_info, index_reductum_with_tag_base, index_rmng_fctrs_start_base, index_rmng_fctrs_start_base_tag, is_term_improper, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x48D


lead_exponent_index

lead_exponent_index Function (ROM Call 0x2DF)
AMS 1.01 or higher estack.h

ESI lead_exponent_index (CESI ptr);

Gets the index of the exponent of the lead factor of an expression.

lead_exponent_index first calls lead_factor_index, then applies factor_exponent_index to the result. So, it returns the pointer to the exponent of the lead factor (i.e. the lead exponent) of the expression pointed to by ptr.

Uses: factor_exponent_index, lead_factor_index
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sign, push_sin2, push_sinh, push_solve, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, did_push_divide_units, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, index_reductum_with_tag_base, is_term_improper, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x48D


lead_factor_index

lead_factor_index Function (ROM Call 0x2E0)
AMS 1.01 or higher estack.h

ESI lead_factor_index (CESI ptr);

Gets the index of the lead factor of an expression.

If ptr points to the MUL_TAG, which is the case when it points to an expression of form factor1 * factor2 * ... (i.e. if the expression is a product of simpler factors), lead_factor_index returns the pointer to factor1 (i.e. to the lead factor). If ptr does not point to the MUL_TAG (i.e. if the expression is not a product of simpler factors), lead_factor_index returns ptr (i.e. the pointer to the expression itself).

Note: Expressions in internal canonic form have the most main factor shallowest, with less main factors deeper (see compare_expressions for more info about "main" ordering). Also, the lead factor of an internally-simplified product is never a product. For example, lead factor of '(3*x^2)*y' converted into canonic form is 'x^2'. Internally-simplified numeric denominator factors are combined with numeric numerator factors into a fractional numeric factor. Non-numeric denominator factors are internally simplified to be merged with numerator factors as negative powers. For example, the lead factor of '2/x' converted into canonic form is 'x^-1'. A factor having a sum as its base orders shallower than a factor having the sum’s main variable as its base. For example, the lead factor of '(x+1)^-2*x^3' converted into canonic form is '(x+1)^-2'. See push_internal_simplify for more info about how to convert an expression into the internal canonic form.

Used by: is_monomial_in_kernel, lead_base_index, lead_exponent_index, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, index_rmng_factor, index_rmng_fctrs_start_fctr_tag, is_negative, is_nonnegative, is_nonpositive, is_positive, is_term_improper, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x48D


lead_term_index

lead_term_index Function (ROM Call 0x2E1)
AMS 1.01 or higher estack.h

ESI lead_term_index (CESI ptr);

Gets the index of the lead term of an expression.

If ptr points to the ADD_TAG, which is a case when it points to an expression of form term1 + term2 + ... (i.e. if the expression is a sum of simpler terms), lead_term_index returns the pointer to term1 (i.e. to the lead term). If ptr does not point to the ADD_TAG (i.e. if the expression is not a sum of simpler terms), lead_term_index returns ptr (i.e. the pointer to the expression itself).

Note: Expressions in internal canonic form have the most main term shallowest, with less main terms deeper (see compare_expressions about more info about "main" ordering). Also, the lead term of an internally-simplified sum is never a sum. For example, the lead term of '(2+x)+y' converted to canonic form is 'x'. By default, similar powers of the main variable are collected in internal canonic forms. For example, the lead term of 'x^2*y+x^2+5' converted to canonic form is 'x^2*(y+1)'. See push_internal_simplify for more info about how to convert an expression into the internal canonic form.

Used by: index_of_lead_base_of_lead_term, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_lim, push_max, push_min, push_nsolve, push_phase, push_sign, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, get_ub, index_if_pushed_binomial_info, index_reductum_with_tag_base, push_but_term, push_constant_terms, push_dependent_terms, push_gcd_then_cofactors, push_independent_terms, push_make_proper, push_nonconstant_terms, push_poly_qr, push_reciprocal, push_standardize, replace_top_with_post_simplified, replace_top2_with_sum


likely_approx_to_complex_number

likely_approx_to_complex_number Function (ROM Call 0x307)
AMS 1.01 or higher estack.h

short likely_approx_to_complex_number (CESI ptr);

Checks if it is likely that an expression can be approxed to a complex number.

likely_approx_to_complex_number is very similar to likely_approx_to_number, except that it checks for the possibility of approximation to numbers which need not be real numbers.

Uses: likely_approx_to_number, next_expression_index
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


likely_approx_to_number

likely_approx_to_number Function (ROM Call 0x308)
AMS 1.01 or higher estack.h

short likely_approx_to_number (CESI ptr);

Checks is it likely that an expression can be approxed to a real number.

If likely_approx_to_number returned TRUE, it is sure that the expression pointed to by ptr can be approxed to a real number, but returning FALSE does not mean that the approximation is not possible: it only means that the approximation to a number is not obvious. For example, it is obvious that expression 'ln(2+sin(1))/5' can be approxed to a number, but this is not so obvious for expression 'x^2+1-x*x', because it contains a symbolic variable name. See can_be_approxed for a more detailed investigation of possibility of approximation.

Uses: next_expression_index, primary_tag_list
Used by: likely_approx_to_complex_number, should_and_did_push_approx_arg2, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_atanh, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_mod, push_nint, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_red_row_ech, push_row_echelon, push_rownorm, push_sign, push_simult, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, did_push_approx_inflection_point, get_ub, index_if_pushed_qquad_info, is_negative, is_never0, is_nonnegative, is_nonpositive, is_positive, is_real, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x606


main_gen_var_index

main_gen_var_index Function (ROM Call 0x2E2)
AMS 1.01 or higher estack.h

ESI main_gen_var_index (CESI ptr);

Searches an expression for a generalized variable.

main_gen_var_index is a variant of index_main_var, but it searches for a "generalized variable", which may also be a subexpression. For example, if the expression is 'sin(x)+y', index_main_var will return a pointer to 'x', but main_gen_var_index will return a pointer to 'sin(x)'. Generalized variable can be an ordinary variable, the base of a noninteger power, or a kernel (like 'sin(x)'), meaning any other irrational subexpression.

More precise, main_gen_var_index skips all ADD_TAG, MUL_TAG and POW_TAG tags, then stops at the first tag which is not equal to some of them. In addition to this, if the tag is POW_TAG, function next_expression_index will be called, to get access to the base of the power (note that "powers" cannot be "reorganized" on such way that constants are always in front of variables, because '2^x' and 'x^2' are not the same expression). This implies that "main generalized variable" of a sum, a product or an integer power is equal to the main generalized variable of a lead term, a lead factor or a base respectively. Otherwise, main generalized variable is the expression itself. For example, main "generalized variables" of expressions 'sin(x)^2*y+ln(z)', '3^(1/5)+2' and '(x+y)^(1/2)+x' are 'sin(x)', '3' and 'x+y' respectively.

Uses: next_expression_index, is_whole_number
Used by: did_push_anti_deriv, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_lim, push_max, push_min, push_nsolve, push_phase, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, get_ub, is_term_improper, push_gcd_then_cofactors, push_make_proper, push_poly_qr, push_standardize, push_var_kern_tail


map_tail_Int

map_tail_Int Function (ROM Call 0x3BC)
AMS 1.01 or higher estack.h

short map_tail_Int (ESI_Callback_Int_t f, ESI start_ptr, short n);

Applies an extended function to all elements in the list.

map_tail_Int is very similar to map_tail, except callback function f has one additional parameter n. Each time f is called, the parameter n passed to map_tail_Int is passed to f. Also, the callback function is not void but returns a Boolean value (TRUE or FALSE). The result of map_tail_Int is the logical OR of all the values returned by f.

Uses: delete_between, push_offset_array, push_quantum, top_estack
Used by: push_csolve, push_czeros, push_max, push_min, push_nsolve, push_solve, push_zeros, replace_top_with_post_simplified


map_tail

map_tail Function (ROM Call 0x3BB)
AMS 1.01 or higher estack.h

void map_tail (ESI_Callback_t f, ESI start_ptr);

Applies a function to all elements in the list.

map_tail first pushes END_TAG on the expression stack, then calls callback function f for every expression on the expression stack (in reversed order), starting from the expression pointed to by start_ptr until END_TAG is reached. Each time f is called, a pointer to the actual expression is passed to it. This function is very useful if you want to apply some operation on all elements of the list (then start_ptr need to point to the first element of the list). If the callback function does not push anything on the stack, the END_TAG pushed by map_tail should probably be deleted.

Note: map_tail calls next_expression_index to step from one expression to another.

Uses: delete_between, push_offset_array, push_quantum, top_estack
Used by: push_parse_text, did_push_anti_deriv, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_char, push_conj, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_exp, push_floor, push_fractional_part, push_im, push_integer_part, push_lim, push_ln, push_log10, push_max, push_min, push_nsolve, push_ord, push_phase, push_re, push_sign, push_sinh, push_solve, push_stddev, push_tan, push_tanh, push_variance, push_zeros, push_equals, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not, push_not_equals, get_ub, push_parse_prgm_or_func_text, push_reciprocal, push_trig, push_user_func, ROM Call 0x450, ROM Call 0x48D, push_to_dd, push_to_dms, push_subscripted_element, ROM Call 0x4DC


map_unary_over_comparison

map_unary_over_comparison Function (ROM Call 0x2E3)
AMS 1.01 or higher estack.h

void map_unary_over_comparison (ESI_Callback_t f, ESI cmptag_ptr);

Calls callback function for both comparison terms and pushes the comparison tag.

map_unary_over_comparison assumes that cmptag_ptr points to a comparison tag. It calls the callback function f twice, passing to it pointers to both comparison terms, i.e. the two expressions below the comparison tag (the callback function should push something to the expression stack). The callback function is applied first to the deeper argument on the stack, then to the shallower argument. Finally, map_unary_over_comparison will push the tag pointed to by cmptag_ptr (one byte) to the expression stack. This function is useful to perform some transformations on both sides of a comparison (e.g. to transform 'n<5' into 'n!<120'). Beware that squaring of both sides of an inequality can cause loss of solutions, and squaring both sides of an equation may introduce spurious solutions!

Uses: next_expression_index, push_quantum
Used by: push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_conj, push_cosh, push_exp, push_im, push_ln, push_phase, push_re, push_sign, push_sinh, push_tan, push_tanh, push_factorial


min_quantum

min_quantum Function (ROM Call 0x2E4)
AMS 1.01 or higher estack.h

ESQ min_quantum (ESQ Tag1, ESQ Tag2);

Finds smaller of two tags.

min_quantum returns Tag1 if it is smaller than Tag2, else returns Tag2.

Used by: estack_number_to_Float


move_between_to_top

move_between_to_top Function (ROM Call 0x2E5)
AMS 1.01 or higher estack.h

void move_between_to_top (ESI ptr1, ESI ptr2);

Moves a sequence of bytes to the top of the expression stack.

move_between_to_top moves a sequence of bytes between ptr1 and ptr2 (more precise, starting at ptr1+1 and ending at ptr2) to the top of the expression stack. It acts like a combination of push_between and delete_between (in fact, it is). This routine assumes that ptr1 and ptr2 really point to parts of the expression stack and that ptr2 is above ptr1, otherwise the result is unpredictable.

Uses: delete_between, push_between
Used by: push_parse_text, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_shift, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, EQU_getNameInfo, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_poly_qr, push_reciprocal, push_standardize, push_user_func, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x48D, push_spher_vector


moved_between_to_top

moved_between_to_top Function (ROM Call 0x2E6)
AMS 1.01 or higher estack.h

unsigned short moved_between_to_top (ESI ptr1, ESI ptr2);

Moves a sequence of bytes to the top of the expression stack.

moved_between_to_top acts like move_between_to_top, but it also returns a number of moved bytes. It calls deleted_between instead of delete_between.

Uses: deleted_between, push_between
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_atan, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum


negate_top

negate_top Function (ROM Call 0x525)
AMS 2.02 or higher estack.h

void negate_top (void);

Negates the top of the EStack.

negate_top changes the sign of the expression on the top of the EStack.

Uses: FloatMinus1Index, IntegerMinus1Index, times_top
Used by: did_push_anti_deriv, push_1st_derivative, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cross_product, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_extended_prod, push_factor, push_integer_part, push_integer_remainder, push_lim, push_max, push_min, push_mod, push_nsolve, push_rec_to_angle, push_sin2, push_sinh, push_solve, push_stddev, push_summation, push_tan, push_tanh, push_variance, push_zeros, push_degrees, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum, get_ub, push_gcd_then_cofactors, push_lu_fact, push_poly_qr, push_reciprocal, push_standardize, push_symbolic_qr_fact, replace_top_with_post_simplified, replace_top2_with_difference, push_to_dd, push_to_dms

See also: add_to_top, subtract_from_top, and_onto_top


next_expression_index

next_expression_index Function (ROM Call 0x10A)
estack.h

ESI next_expression_index (CESI ptr);

Finds the next entry on the expression stack.

Assuming that ptr points to an expression entry on the expression stack, next_expression_index returns the pointer which points to an expression which is located just below the expression pointed to by ptr. So, by successive calls to next_expression_index starting from top_estack, you can locate all expressions on the stack. This command will throw an error if ptr points to the END_TAG, so be careful.

Note: next_expression_index calls index_after_match_endtag for TI-Basic functions and program tags, so that inline functions are counted as entire expressions rather than of their components.

Uses: is_tail_independent_of, push_expression, push_quantum, top_estack, index_after_match_endtag, primary_tag_list, command_tag_list
Used by: all_tail, any_tail, are_expressions_identical, can_be_approxed, compare_complex_magnitudes, compare_expressions, delete_expression, deleted_expression, factor_exponent_index, index_below_display_expression_aux, index_numeric_term, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_de_seq_vars, is_independent_of_tail, is_matrix, is_narrowly_independent_of, is_tail_independent_of, is_valid_smap_aggregate, last_element_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_unary_over_comparison, NG_graphESI, norm1_complex_Float, numeric_factor_index, Parse2DExpr, Parse2DMultiExpr, push_expression, push_internal_simplify, push_offset_array, push_parse_text, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, TokenizeSymName, EX_getArg, SkipArg, cmd_archive, cmd_blddata, cmd_cubicreg, cmd_custom, cmd_cycle, cmd_cyclepic, cmd_delfold, cmd_delvar, cmd_dialog, cmd_disp, cmd_drawparm, cmd_drawpol, cmd_endfor, cmd_endwhile, cmd_exit, cmd_expreg, cmd_fnoff, cmd_fnon, cmd_for, cmd_goto, cmd_if, cmd_ifthen, cmd_input, cmd_inputstr, cmd_linreg, cmd_lnreg, cmd_local, cmd_lock, cmd_logistic, cmd_medmed, cmd_newdata, cmd_newpic, cmd_newplot, cmd_onevar, cmd_plotsoff, cmd_plotson, cmd_popup, cmd_powerreg, cmd_prompt, cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pxlchg, cmd_pxloff, cmd_pxlon, cmd_quadreg, cmd_quartreg, cmd_randseed, cmd_request, cmd_return, cmd_shade, cmd_showstat, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_stopic, cmd_text, cmd_toolbar, cmd_try, cmd_twovar, cmd_unarchiv, cmd_unlock, cmd_while, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_augment, push_colnorm, push_comdenom, push_conj, push_cos, push_cosh, push_csolve, push_cumsum, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_dimension, push_dotproduct, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_im, push_integer_part, push_left, push_lim, push_ln, push_log10, push_mat_to_list, push_max, push_max1, push_mid, push_min, push_min1, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_ord, push_part, push_phase, push_prodlist, push_pttest, push_pxltest, push_randnorm, push_randpoly, push_re, push_rec_to_angle, push_red_row_ech, push_right, push_rotate, push_round, push_row_echelon, push_shift, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_solve, push_sqrt, push_str_to_expr, push_sumlist, push_summation, push_tan, push_tanh, push_when, push_zeros, did_push_to_polar, push_and, push_assignment, push_dot_exponentiate, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_indir_name, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_or, push_product, push_radians, push_ratio, push_substitute_no_simplify, push_sum, push_to_cylin, push_to_sphere, remaining_element_count, handleVarLinkKey, MO_digestOptions, HomePushEStack, ST_eraseHelp, ST_modKey, add_to_top, and_onto_top, are_units_consistent, convert_to_TI_92, cpt_gr_fun, cpt_gr_param, cpt_gr_polar, CustomMenuItem, de_initRes, de_loop, delete_list_element, did_push_approx_inflection_point, did_push_divide_units, did_push_lincf, did_push_var_val, divide_top, dv_create_graph_titles, EQU_getNameInfo, fix_loop_displacements, gen_version, get_lb, get_ub, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_ck_solvergraph, gr_execute_seq, gr_find_el, GraphOrTableCmd, has_different_variable, has_unit_base, index_after_match_endtag, index_if_pushed_binomial_info, index_if_pushed_qquad_info, init_list_indices, init_matrix_indices, init_unit_system, InitDEMem, InitTimeSeq, integer_non_unknown, is_cFloat_agg, is_constant, is_equivalent_to, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_positive, is_real, is_totally_polynomial, is_undefined, is_units_term, linear_degree, next_var_or_kernel_index, NG_setup_graph_fun, or_onto_top, PlotDup, PlotGet, PlotPut, PlotSize, push_ans_entry, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_float_qr_fact, push_format, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_poly_deg_in_var_or_kernel, push_poly_qr, push_reciprocal, push_simplify, push_simplify_statements, push_sq_matrix_to_whole_number, push_standardize, push_symbolic_qr_fact, push_user_func, push_var, raise_to_top, ReallocExprStruct, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_post_simplified, replace_top2_with_and, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, setup_more_graph_fun, setup_unit_system, spike_geo_titles, spike_in_editor, spike_optionD, spike_titles_in_editor, store_func_def, store_to_subscripted_element, times_top, tokenize_if_TI_92_or_text, VarStoreLink, FolderDel, FolderRename, GetFuncPrgmBodyPtr, HSymDel, SymFindFolderName, VarRecall, VarStore, ROM Call 0x468, ROM Call 0x48C, ROM Call 0x48D, ROM Call 0x494, ROM Call 0x495, push_cylin_vector, push_dense_poly_eval, push_polar_vector, push_spher_vector, push_to_dms, ROM Call 0x4CA, push_subscripted_element, ROM Call 0x4E6, DateAndTime_SetDlg


NG_approxESI

NG_approxESI Function (ROM Call 0x25C)
estack.h

void NG_approxESI (CESI ptr);

Evaluates an expression in "APPROX" mode.

NG_approxESI executes the entry on the expression stack pointed to by ptr (it needs to point to the entry tag) in "APPROX" mode, then pushes the result (i.e. a new expression) on the top of the expression stack. The pushed result is NOT in internal canonic form (if necessary, do push_internal_simplify to force conversion to the internal canonic form). The following example illustrates this very powerful command:

push_parse_text ("sin(1.3)+log(2)/7");
NG_approxESI (top_estack);
printf_xy (0, 50, "%f", estack_number_to_Float (top_estack));
See push_parse_text and estack_number_to_Float to understand how this example works.

Note: The expression must not contain TI-Basic statements. For executing TI-Basic statements, use NG_execute. Also, this command may cause expansion of the expression stack or heap compression, and may throw various errors is something is wrong.

Uses: ER_catch, ER_success, ER_throwVar, NG_control, push_simplify, ROM Call 0x5C7
Used by: cmd_linetan, cmd_randseed, cmd_sinreg, push_randnorm, push_round, de_initRes, dv_create_graph_titles, ForceFloat, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_execute_de, gr_execute_seq, InitTimeSeq, push_format, seqWebInit, ROM Call 0x46F


NG_execute

NG_execute Function (ROM Call 0x25D)
estack.h

void NG_execute (HANDLE Handle, short approx_flag);

Executes TI-Basic statements.

NG_execute executes a sequence of TI-Basic statements in tokenized form, which are located in a memory block pointed to by handle Handle. It is a handle to a MULTI_EXPR structure. To create such a block, the functions push_parse_text and HS_popEStack may be very useful, like in the following example:

push_parse_text ("ClrGraph:Graph sin(x)");
handle = HS_popEStack ();
NG_execute (handle, FALSE);
HeapFree (handle);
If approx_flag is non-zero, the sequence will be executed in "approx" mode (like running with [DIAMOND]+[ENTER]). Otherwise, the current mode settings will be used. This routine is called after NG_RPNToText from the home screen.

NG_execute can also evaluate expressions. In this case, the result of the evaluation is pushed on the top of the expression stack.

Note: This routine always clears the error context, resets control flags, may cause estack expansion or heap compression. It may throw various errors if something is wrong.

Uses: HToESI, reset_control_flags, HeapLock, HeapMoveHigh, HeapUnlock, ER_catch, ER_success, ER_throwVar, clear_error_context, NG_control, push_simplify_statements, ROM Call 0x5C5, ROM Call 0x5C6, ROM Call 0x5C7, ROM Call 0x5C8, ROM Call 0x5CB, ROM Call 0x5CC
Used by: HomeExecute


NG_graphESI

NG_graphESI Function (ROM Call 0x25E)
estack.h

void NG_graphESI (CESI ptr, HANDLE Handle);

Evaluates an expressions for graphing purposes.

NG_graphESI is the function used in TIOS during drawing function graphs. It evaluates the entry on the expression stack pointed to by ptr in "APPROX" mode then pushes the result on the top of the expression stack, similar to what NG_approxESI does, but NG_graphESI requires that all variables in the expression must be defined, i.e. the expression must evaluate to a number (else "Undefined variable" error will be thrown). Handle is the handle of the function in which the expression is defined. I don't know exactly when and why this function needs this handle (probably to check which variables are parameters of the function, which variables are local etc.). When I tried to pass H_NULL to this function, nothing bad happened. However, in the absence of more info, avoid this function.

Uses: all_tail, delete_between, next_expression_index, top_estack, ER_catch, ER_success, ER_throwVar, NG_control, primary_tag_list, push_simplify, push_simplify_statements, ROM Call 0x5C5, ROM Call 0x5C6, ROM Call 0x5C7, ROM Call 0x5C8, ROM Call 0x5CB, ROM Call 0x5CC
Used by: GR3_paint3d, GR3_xyToWindow, de_loop, execute_graph_func, GR3_addContours, run_one_seq


NG_rationalESI

NG_rationalESI Function (ROM Call 0x25F)
estack.h

void NG_rationalESI (CESI ptr);

Evaluates an expression in "EXACT" mode.

NG_rationalESI executes the entry on the expression stack pointed to by ptr (it needs to point to the entry tag) in "EXACT" mode, then pushes the result (i.e. a new expression) on the top of the expression stack. See the example of usage given with display_statements. The same notes given with NG_approxESI are true with this command too.

Note: The expression must not contain TI-Basic statements. For executing TI-Basic statements, use NG_execute. Also, this command may cause expansion of the expression stack or heap compression, and may throw various errors is something is wrong.

Uses: ER_catch, ER_success, ER_throwVar, NG_control, push_simplify, ROM Call 0x5C7


NG_RPNToText

NG_RPNToText Function (ROM Call 0x25B)
estack.h

HANDLE NG_RPNToText (HANDLE hRPN, unsigned short NewLines, unsigned short FullPrec);

Detokenizes a tokenized structure associated with a handle.

NG_RPNToText detokenizes a tokenized structure (an expression, TI-Basic statement or a group of statements) associated with handle hRPN and returns a handle to the memory block where detokenized string is stored (you don't need to allocate anything by yourself, this function will do it instead). The first word of the data associated with hRPN should be the length of the data which is used to find the first tag of the tokenized data. It throws an error if the detokenization fails. This function is mainly identical to display_statements except NG_RPNToText requires a handle instead of the pointer to the structure which needs to be detokenized. See display_statements for more info.

Uses: display_statements, HToESI, HeapGetLock, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar
Used by: HomeExecute, HomePushEStack


NG_tokenize

NG_tokenize Function (ROM Call 0x260)
estack.h

short NG_tokenize (HANDLE hTEXT, unsigned short *ErrCode, unsigned short *ErrOffset);

Tokenizes text associated with a handle and pushes them to the expression stack.

NG_tokenize is more powerful variant of push_parse_text. It tokenizes the text associated with the handle hTEXT, and pushes the converted text to the expression stack. Returns TRUE if the operation was successful, otherwise it returns FALSE. If there was an error, then the variable pointed to by ErrCode contains the error code, and the variable pointed to by ErrOffset contains the offset in the text where the error occurred. If there were not any errors, then the variable pointed to by ErrCode contains multi state (this is the result returned from push_parse_text) and ErrOffset is undefined. This routine may expand the expression stack, may cause the heap compression, or even may throw an error if something goes really wrong (not enough memory, for example).

Uses: push_parse_text, HeapUnlock, HLock, ER_catch, ER_success
Used by: cmd_input, cmd_inputstr, cmd_prompt, cmd_sinreg, HomeExecute, SP_Define


norm1_complex_Float

norm1_complex_Float Function (ROM Call 0x309*)
AMS 1.01 or higher estack.h

float norm1_complex_Float (CESI ptr);

Finds the 1-norm of a complex number entry.

norm1_complex_Float finds the 1-norm (i.e. the sum of absolute values of real and imaginary part) of the complex number entry pointed to by ptr and returns the result. If the entry is not a complex or real floating point number, the result is garbage (in the case of a real number, norm1_complex_Float reduces to a simple absolute value).

Uses: next_expression_index, fabs, estack_to_float, _bcd_math
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


numeric_factor_index

numeric_factor_index Function (ROM Call 0x2E7)
AMS 1.01 or higher estack.h

ESI numeric_factor_index (CESI ptr);

Searches factors in the expression for a numeric factor.

If ptr points to the MUL_TAG, which is a case when it points to an expression of form factor1 * factor2 * ... (i.e. if the expression is a product of simpler factors), numeric_factor_index returns the pointer to the eventual numeric factor in the expression. If the expression is a number, numeric_factor_index returns ptr (i.e. the pointer to the expression itself). If ptr does not point to the MUL_TAG (i.e. if the expression is not a product of simpler factors), or if there is not any numeric factors in the expression, lead_factor_index returns a pointer to a simple expression which consists only of the number 1 (floating point or integer, depending of whether the approximation mode is active or not).

Note: This function is not implemented to be very universal. TIOS always "reorganizes" expressions on such way that numeric factors are at the beginning of the expression (i.e. x*3 will be reorganized into 3*x), and this function assumes that the expression is organized on such way. This is the so-called "internal canonic" form, and such expressions always have at most one factor with a numeric tag, in which case it is the deepest factor. So, '3*x^2*y' contains a numeric factor (3), but '2*x+3' does not. Also, numeric factors in numerators and denominators are always simplified into a single numeric factor in internal canonic forms (so, the numeric factor of '6*x/(4*y)' after conversion to canonic form is 3/2. Fortunately, all expressions in arguments are always in internal canonic form. However, this is not true after push_parse_text function, nor after an evaluation using NG_rationalESI or NG_approxESI. In other words, results of these commands are not always "correctly" organized. To force converting an expression to the internal canonic form, always call push_internal_simplify after usage any of functions mentioned above.

Uses: next_expression_index, Float1Index, Integer1Index, primary_tag_list
Used by: did_push_anti_deriv, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_exp, push_expand, push_factor, push_lim, push_max, push_min, push_nsolve, push_sign, push_sin2, push_solve, push_tan, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, get_ub, index_if_pushed_binomial_info, push_gcd_then_cofactors, push_make_proper, push_reciprocal, push_standardize, replace_top_with_post_simplified, ROM Call 0x48D


or_onto_top

or_onto_top Function (ROM Call 0x57B)
AMS 2.02 or higher estack.h

void or_onto_top (CESI ptr);

Logical ORs an expression onto the estack.

or_onto_top replaces the top expression on the estack with the logical OR of itself and the expression pointed to by ptr.

Uses: push_or, are_expressions_identical, delete_expression, next_expression_index, push_expression, top_estack
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_when, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_or

See also: and_onto_top


Parms2D

Parms2D Function (ROM Call 0x4D)
estack.h

void Parms2D (CESI ptr, short *Width, short *Bottom, short *Top);

Gets information about dimensions of block which will be "pretty printed".

Parms2D gets information about the screen space which will be occupied by displayed expression. It should be called after calling Parse2DExpr (or Parse2DMultiExpr), and ptr should be a result returned from it. Params2D stores the information in three variables pointed to by Width, Bottom and Top. Width is the width of the displayed block, and Top and Bottom are distances of top and bottom edge of the block measured from the wanted y position. More precise, if the expression is printed at (x, y) using Print2DExpr, the left corner of the occupied space will be at (x, y-*Top), and the right corner of the occupied space will be at (x+*Width, y+*Bottom). So, the 2D expression has an imaginary center line above which is the "Top", and below (counting this line too) is the "Bottom".

Used by: cmd_disp, cmd_output, cmd_pause, HomeExecute, HomePushEStack


Parse1DExpr

Parse1DExpr Function (ROM Call 0x4F)
estack.h

HANDLE Parse1DExpr (CESI ptr, unsigned short FullPrec, unsigned short width);

Parses a tokenized expression to be printed.

Parse1DExpr does a similar job as display_statements (i.e. converts a RPN expression to the TEXT and returns the handle to the text), but the parameters are somewhat different. Here, width is the maximum width of text result (0 indicates no width restriction). So, when necessary, symbolic expressions are truncated to width-1 characters and terminated with an ellipsis character ('...'). When ptr points to a tagged floating point number, the number is rounded to fit in width characters. When the number cannot be rounded to fit in width characters, an ellipsis character ('...') is returned. See display_statements for more info.

Uses: index_below_display_expression_aux, HeapAlloc, HeapFree, HeapLock, HeapRealloc, HeapUnlock, HLock, ER_catch, ER_success, ER_throwVar, sprintf, strchr, OSDisableBreak, OSEnableBreak, estack_to_float, TIOS_abs, ROM Call 0x457
Used by: cmd_disp, cmd_output, cmd_pause, cmd_prompt, push_string, handleRclKey, GT_PrintCursor, SP_Define, ROM Call 0x45B


Parse2DExpr

Parse2DExpr Function (ROM Call 0x4A)
estack.h

ESI Parse2DExpr (CESI ptr, unsigned short FullPrec);

Parses a tokenized expression to be pretty printed using Print2DExpr.

Parse2DExpr parses the expression pointed to by ptr, so it can be displayed with Print2DExpr. This function splits up expression into blocks with information about their relative position and size. This splitting is performed for efficiency reasons, so the expression may be displayed again without having to calculate the positions again. Parse2DExpr returns the pointer to a created structure (it needs to be passed to Print2DExpr). This pointer is in fact the new value of top_estack, because the created structure (known as "boxed RPN") is also pushed on the expression stack. FullPrec is a Boolean flag: when it is non-zero, all floating point values will be converted using the maximal precision (14 digits), else current precision settings (from TI-Basic MODE dialog) will be used. If there is not enough memory, a special symbol is pushed onto the expression stack to signify this. This routine may cause heap compression. See Print2DExpr for an example of usage.

Parse2DExpr will always convert expressions into the "canonic printing (external) form". For example, both x*3 and 3*x will be displayed as 3*x, x*y^(-1) will be displayed as x/y etc.

Note: Break key (ON) is checked during execution of this function, and pressing it will throw an error!

Uses: check_estack_size, delete_between, next_expression_index, push_between, push_END_TAG, push_expression, push_quantum, top_estack, ER_catch, ER_success, ER_throwVar, sprintf, strlen, NeedStack, XR_stringPtr, estack_max_index, estack_to_float, GetTagStr, primary_tag_list, _ds32s32, _ms32s32, ROM Call 0x457, ROM Call 0x4DF, command_tag_list
Used by: cmd_disp, cmd_output, cmd_pause


Parse2DMultiExpr

Parse2DMultiExpr Function (ROM Call 0x4B)
estack.h

ESI Parse2DMultiExpr (HANDLE Handle, unsigned short FullPrec);

Parses a multi-statement expression associated with a handle to be pretty printed using Print2DExpr.

Parse2DMultiExpr parses a multi-expression (see MULTI_EXPR) associated with Handle so that it can be displayed with Print2DExpr. Parameter FullPrec has the same meaning as in Parse2DExpr. The expression associated with Handle may contain multiple expressions separated with NEXTEXPR_TAG (in opposite to Parse2DExpr). I must admit that I don't understand this function very well, so avoid it except if you know about it more than I know...

Uses: check_estack_size, delete_between, next_expression_index, push_between, push_END_TAG, push_expression, push_quantum, top_estack, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, sprintf, strlen, NeedStack, OSDisableBreak, OSEnableBreak, XR_stringPtr, estack_max_index, estack_to_float, GetTagStr, primary_tag_list, _ds32s32, _ms32s32, ROM Call 0x4DF, command_tag_list
Used by: HomeExecute, HomePushEStack


Print2DExpr

Print2DExpr Function (ROM Call 0x4C)
estack.h

void Print2DExpr (CESI ptr, WINDOW *w, short x, short y);

Performs "pretty printing" (or "2D printing") of an expression.

Print2DExpr prints the expression in "pretty" or "2D" style. Before printing, the expression needs first to be "parsed" using Parse2DExpr, and argument ptr should be a result returned from Parse2DExpr (an error may be thrown if ptr points to something else). w is a pointer to the WINDOW structure which describes the window in which the expression will be displayed (see wingraph.h header file for more info about windows). If you didn't create your own windows in the program, you can pass DeskTop as the parameter (as in the example given below). x and y are coordinates (window-relative) where the expression will be printed. x determines the left edge of the expression, and the expression goes (in y direction) both above and below the value of y. See Parms2D for exact information about dimensions of displayed expression. If the displayed expression cannot fit into the given window, it will be simply clipped at edges of the window.

Here is an example (called "Pretty Print") which first calculates the integral of 1/((x-3)(x^2+4)), then "pretty prints" the result on the screen:

// Calculate an integral and pretty print it

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

#define MIN_AMS 101           // Compile for AMS 1.01 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// Main Function
void _main(void)
{
  TRY
    push_END_TAG ();
    push_quantum (VAR_X_TAG);
    push_parse_text ("1/((x-3)(x^2+4))");
    push_quantum (INTEGRATE_TAG);
    NG_rationalESI (top_estack);
    WinClr (DeskTop);
    Print2DExpr (Parse2DExpr (top_estack, FALSE), DeskTop, 0, 50);
  ONERR
    DrawStr (20, 20, "Error!", A_NORMAL);
  ENDTRY
  ngetchx ();
}
It is also possible to use
Parse2DExpr (top_estack, FALSE);
Print2DExpr (top_estack, DeskTop, 0, 50);
instead of
Print2DExpr (Parse2DExpr (top_estack, FALSE), DeskTop, 0, 50);
You can use Parms2D to get information about the height and the width of the printed expression without displaying it on the screen. This may be used to determine coordinates where the expression needs to be displayed.

Uses: WinFont
Used by: cmd_disp, cmd_output, cmd_pause, HomeExecute


push0

push0 Function (ROM Call 0x4E7)
AMS 2.00 or higher estack.h

void push0 (void);

Pushes a tagged integer or a tagged float 0, depending on the mode setting.

If the mode setting is APPROX, the tagged float 0.0 is pushed onto the EStack. Else, the tagged integer 0 is pushed by push_exact0.

Uses: Float0Index, push_expression, push_exact0
Used by: did_push_lincf, get_ub, push_constant_terms, push_dependent_terms, push_independent_terms, push_lu_fact, push_nonconstant_terms, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_symbolic_qr_fact, spike_in_editor, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_asinh, push_atanh, push_colnorm, push_cross_product, push_csolve, push_cumsum, push_czeros, push_def_int, push_desolve, push_determinant, push_diag, push_dotproduct, push_expand, push_identity_mat, push_im, push_instring, push_lim, push_list_to_mat, push_matnorm, push_max, push_min, push_newlist, push_newmat, push_nsolve, push_perm, push_phase, push_red_row_ech, push_row_echelon, push_rownorm, push_simult, push_sin2, push_solve, push_sumlist, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_matrix_product, push_not_equals, cmd_lu_fact, ROM Call 0x48D, push_dense_poly_eval

See also: push1, push_minus1, push_exact0, push_exact1, push_exact_minus1


push1

push1 Function (ROM Call 0x4E8)
AMS 2.00 or higher estack.h

void push1 (void);

Pushes a tagged integer or a tagged float 1, depending on the mode setting.

If the mode setting is APPROX, the tagged float 1.0 is pushed onto the EStack. Else, the tagged integer 1 is pushed by push_exact1.

Uses: Float1Index, push_expression, push_exact1
Used by: did_push_lincf, get_ub, push_auto_units_conversion, push_constant_factors, push_dependent_factors, push_gcd_then_cofactors, push_independent_factors, push_mrow_aux, push_nonconstant_factors, push_nonnumeric_factors, push_sq_matrix_to_whole_number, push_symbolic_qr_fact, replace_top_with_post_simplified, cmd_newplot, did_push_anti_deriv, push_1st_derivative, push_abs, push_asin, push_asinh, push_csolve, push_czeros, push_def_int, push_desolve, push_determinant, push_expand, push_extended_prod, push_factor, push_identity_mat, push_lim, push_max, push_min, push_nsolve, push_perm, push_prodlist, push_red_row_ech, push_row_echelon, push_sign, push_simult, push_solve, push_summation, push_tanh, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, cmd_lu_fact

See also: push0, push_minus1, push_exact0, push_exact1, push_exact_minus1


push_ANSI_string

push_ANSI_string Function (ROM Call 0x48A*)
AMS 1.01 or higher estack.h

void push_ANSI_string (const char *str);

Pushes a standard C string to the expression stack.

push_ANSI_string is an alias (known from early versions of TIGCCLIB) for the TIOS function push_zstr.


push_between

push_between Function (ROM Call 0x2E8)
AMS 1.01 or higher estack.h

void push_between (void *ptr1, void *ptr2);

Pushes a sequence of bytes to the expression stack.

push_between pushes a sequence of bytes starting at ptr1+1 and ending at ptr2 to the expression stack.

Note: The break key (ON) is checked during execution of this routine, and an error is thrown if it is pressed!

Uses: check_estack_size, top_estack, memcpy, OSCheckBreak
Used by: compare_complex_magnitudes, index_below_display_expression_aux, move_between_to_top, moved_between_to_top, Parse2DExpr, Parse2DMultiExpr, push_expression, push_Float_to_nonneg_int, push_parse_text, push_reversed_tail, did_push_anti_deriv, did_push_series, push_1st_derivative, push_augment, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_im, push_integer_lcm, push_integer_quotient, push_is_prime, push_lim, push_mat_to_list, push_max, push_min, push_mod, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_rotate, push_sequence, push_shift, push_sin2, push_solve, push_summation, push_tan, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_or, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, compare_numbers, did_push_var_val, does_push_fetch, EQU_getNameInfo, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, time_loop, times_top, ROM Call 0x48D


push_cnvrt_integer_if_whole_nmb

push_cnvrt_integer_if_whole_nmb Function (ROM Call 0x30D)
AMS 1.01 or higher estack.h

void push_cnvrt_integer_if_whole_nmb (CESI ptr);

Pushes a floating point entry eventually converted to an integer.

push_cnvrt_integer_if_whole_nmb checks the entry on the expression stack pointed to by ptr. If it is not a floating point value (represented by FLOAT_TAG), or if it is a floating point value which is not a whole number, yet another copy of the entry is pushed on the expression stack. If the entry is a floating point value which is a whole number, this number is pushed on the expression stack, but this time as an integer (i.e. with POSINT_TAG or NEGINT_TAG).

Uses: did_push_cnvrt_Float_to_integer, push_expression
Used by: push_exponentiate


push_e

push_e Function (Macro)
estack.h

void push_e (void);

Pushes e.

If the mode setting is APPROX, the tagged float e is pushed onto the EStack. Otherwise, e^1 is pushed.


push_END_TAG

push_END_TAG Function (ROM Call 0x263)
estack.h

void push_END_TAG (void);

Pushes end-of-list marker to the expression stack.

push_END_TAG pushes END_TAG to the expression stack. This is the same as push_quantum (END_TAG).

push_END_TAG may be useful when you want to push a list on the expressions stack: first push END_TAG, then all elements of the list in reverse order, and finally push LIST_TAG (using push_LIST_TAG).

Uses: push_quantum
Used by: Parse2DExpr, Parse2DMultiExpr, push_setmode, OSLinkCmd, de_initRes, de_loop, gr_ck_solvergraph, InitDEMem, InitTimeSeq

See also: push_quantum


push_exact0

push_exact0 Function (ROM Call 0x4EC)
AMS 2.00 or higher estack.h

void push_exact0 (void);

Pushes a tagged integer 0.

This routine is called by push0 if the mode setting is not APPROX.

Uses: check_estack_size, top_estack
Used by: add_to_top, are_units_consistent, compare_numbers, get_ub, index_if_pushed_qquad_info, is_term_improper, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_deg_in_var_or_kernel, push_poly_qr, push_reciprocal, push_standardize, push0, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, times_top, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_atan, push_atanh, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_im, push_integer_lcm, push_is_prime, push_lim, push_ln, push_max, push_min, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_sin2, push_solve, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, compare_complex_magnitudes, ROM Call 0x4E9

See also: push0, push1, push_minus1, push_exact1, push_exact_minus1


push_exact1

push_exact1 Function (ROM Call 0x4F2)
AMS 2.00 or higher estack.h

void push_exact1 (void);

Pushes a tagged integer 1.

This routine is called by push1 if the mode setting is not APPROX.

Uses: check_estack_size, top_estack
Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_deg_in_var_or_kernel, push_poly_qr, push_reciprocal, push_standardize, push1, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comb, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_gcd_numbers, push_im, push_is_prime, push_lim, push_max, push_min, push_mod, push_nsolve, push_numerator, push_phase, push_re, push_sign, push_sin2, push_solve, push_summation, push_tan, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, ROM Call 0x4EA

See also: push0, push1, push_minus1, push_exact0, push_exact_minus1


push_exact_minus1

push_exact_minus1 Function (ROM Call 0x4ED)
AMS 2.00 or higher estack.h

void push_exact_minus1 (void);

Pushes a tagged integer -1.

This routine is called by push_minus1 if the mode setting is not APPROX.

Uses: check_estack_size, top_estack
Used by: get_ub, is_negative, is_nonpositive, push_auto_units_conversion, push_reciprocal, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_lim, push_max, push_min, push_nint, push_nsolve, push_sign, push_solve, push_summation, push_tan, push_tanh, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_minus1, ROM Call 0x4EF

See also: push0, push1, push_minus1, push_exact0, push_exact1


push_expr_quantum

push_expr_quantum Function (ROM Call 0x2E9)
AMS 1.01 or higher estack.h

void push_expr_quantum (CESI ptr, ESQ Tag);

Pushes an expression followed by a tag to the expression stack.

push_expr_quantum pushes an entry (expression) pointed to by ptr (it needs to point to the entry tag) to the top of the expression stack, then pushes a byte Tag. The entry does not need to be a simple entity; it may be a complex symbolic expression, too. This is achieved by calling next_expression_index and push_between. This function is useful when you need to perform a unary operation on the expression.

Uses: push_expression, top_estack
Used by: push_internal_simplify, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_conj, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_diag, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_im, push_integer_part, push_lim, push_ln, push_max, push_min, push_nint, push_nsolve, push_numerator, push_part, push_phase, push_re, push_round, push_sign, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_or, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, did_push_approx_inflection_point, get_ub, GM_Intersect, GM_Math1, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_simplify, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, times_top, ROM Call 0x48D, ROM Call 0x4E6

See also: push_expression, push_expr2_quantum


push_expr2_quantum

push_expr2_quantum Function (ROM Call 0x2EA)
AMS 1.01 or higher estack.h

void push_expr2_quantum (CESI ptr1, CESI ptr2, ESQ Tag);

Pushes two expressions followed by a tag to the expression stack.

push_expr2_quantum pushes two entries (expressions) on the expression stack pointed to by ptr1 and ptr2 to the top of the stack, then pushes a byte Tag. This function is useful when you need to perform a binary operation on two expressions.

Uses: push_expression, top_estack
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_integer_gcd, push_integer_lcm, push_lim, push_max, push_min, push_mod, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_rec_to_angle, push_sin2, push_solve, push_summation, push_tan, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_substitute_using_such_that, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum

See also: push_expression, push_expr_quantum


push_expression

push_expression Function (ROM Call 0x44D*)
AMS 1.01 or higher estack.h

void push_expression (CESI ptr);

Pushes an expression to the expression stack.

push_expression pushes an entry (expression) pointed to by ptr (it needs to point to the entry tag) to the top of the expression stack. The entry does not need to be a simple entity; it may be a complex symbolic expression, too. This is achieved by calling next_expression_index and push_between.

Uses: next_expression_index, push_between
Used by: compare_complex_magnitudes, did_push_cnvrt_Float_to_integer, next_expression_index, Parse2DExpr, Parse2DMultiExpr, push_cnvrt_integer_if_whole_nmb, push_expr_quantum, push_expr2_quantum, push_internal_simplify, push_parse_text, push_transpose_aux, should_and_did_push_approx_arg2, cmd_blddata, cmd_circle, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_fill, cmd_get, cmd_linetan, cmd_local, cmd_printobj, cmd_shade, cmd_slpline, cmd_sorta, cmd_sortd, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_conj, push_cosh, push_csolve, push_cumsum, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_diag, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_im, push_instring, push_integer_lcm, push_integer_part, push_integer_remainder, push_is_prime, push_left, push_lim, push_list_to_mat, push_ln, push_max, push_max1, push_max2, push_median, push_mid, push_min, push_min1, push_min2, push_mod, push_mrowadd, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_part, push_perm, push_phase, push_prodlist, push_rand, push_randpoly, push_re, push_rec_to_angle, push_red_row_ech, push_right, push_rotate, push_round, push_row_echelon, push_rowadd, push_rowdim, push_rowswap, push_sequence, push_shift, push_sign, push_simult, push_sin2, push_sinh, push_solve, push_submat, push_sumlist, push_summation, push_tan, push_tanh, push_when, push_zeros, did_push_to_polar, push_and, push_assignment, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_indir_name, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_or, push_product, push_radians, push_ratio, push_substitute_no_simplify, push_substitute_simplify, push_substitute_using_such_that, push_sum, push_to_cylin, push_to_sphere, add_to_top, and_onto_top, are_units_consistent, compare_numbers, de_initRes, did_push_approx_inflection_point, did_push_divide_units, divide_top, dv_create_graph_titles, EQU_getNameInfo, get_ub, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_ck_solvergraph, GraphOrTableCmd, has_different_variable, index_if_pushed_binomial_info, index_if_pushed_qquad_info, InitDEMem, or_onto_top, push_ans_entry, push_auto_units_conversion, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_div_dif_1f, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_mrow_aux, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_pi, push_pi_on_quantum, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, push_symbolic_qr_fact, push_trig, push_user_func, push_var_kern_tail, push_zero_partial_column, push0, push1, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, SP_Define, store_func_def, times_top, tokenize_if_TI_92_or_text, VarRecall, ROM Call 0x45B, ROM Call 0x468, ROM Call 0x47F, ROM Call 0x480, cmd_lu_fact, ROM Call 0x48D, push_cylin_vector, push_dense_poly_eval, push_spher_vector, push_to_dd, push_to_dms, push_subscripted_element, ROM Call 0x4E6, ROM Call 0x4E9, ROM Call 0x4EA, push_minus1, ROM Call 0x4EF

See also: push_quantum, push_expr_quantum, push_expr2_quantum


push_Float_to_nonneg_int

push_Float_to_nonneg_int Function (ROM Call 0x30B)
AMS 1.01 or higher estack.h

void push_Float_to_nonneg_int (float value);

Rounds a floating point value to an integer, then pushes it to the expression stack.

push_Float_to_nonneg_int rounds value to the nearest integer, then pushes it to the expression stack, as a tagged integer value. The sign of value is ignored. This routine may throw an error if the truncated integer part of value is not representable as a big integer.

Uses: check_estack_size, delete_between, push_between, push_quantum, top_estack, _bcd_math
Used by: did_push_cnvrt_Float_to_integer, push_gcd_numbers, push_sequence


push_Float_to_rat

push_Float_to_rat Function (ROM Call 0x30C)
AMS 1.01 or higher estack.h

void push_Float_to_rat (CESI ptr);

Pushes a rational approximation of a floating point entry.

push_Float_to_rat finds a rational approximation of the floating point entry pointed to by ptr (of course, ptr points to the tag), and pushes it on the top of the expression stack. The relative error can be specified using the AMS global variable RAtionalize_tol. This routine works well even with transfinite floats (e.g. POSITIVE_INF will be pushed as INFINITY_TAG).

Uses: top_estack, float_class, estack_to_float
Used by: push_round_Float, did_push_anti_deriv, push_1st_derivative, push_coldim, push_csolve, push_czeros, push_def_int, push_desolve, push_dimension, push_floor, push_lim, push_max, push_min, push_mod, push_nsolve, push_nth_derivative, push_rand, push_randmat, push_randpoly, push_round, push_rowdim, push_sin2, push_solve, push_zeros, push_dot_exponentiate, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, are_units_consistent, get_ub, push_to_dms


push_Float

push_Float Function (ROM Call 0x30A)
AMS 1.01 or higher estack.h

void push_Float (float value);

Pushes a floating point value to the expression stack.

push_Float rounds value to the 14 significant digits (using round14), then pushes it to the expression stack. If value is not representable as a finite float, the most appropriate transfinite tag is pushed.

Uses: check_estack_size, push_overflow_to_infinity, push_quantum, top_estack, is_nan, is_transfinite, round14, _bcd_math
Used by: compare_complex_magnitudes, did_push_cnvrt_Float_to_integer, push_parse_text, push_round_Float, cmd_blddata, cmd_circle, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_get, cmd_linetan, cmd_shade, cmd_sinreg, cmd_slpline, cmd_try, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_coldim, push_comb, push_comdenom, push_cos, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_dimension, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_im, push_integer_lcm, push_is_prime, push_lim, push_ln, push_log10, push_max, push_min, push_mod, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_perm, push_phase, push_rand, push_randmat, push_randnorm, push_randpoly, push_re, push_rec_to_angle, push_red_row_ech, push_round, push_row_echelon, push_rowdim, push_sequence, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_solve, push_sqrt, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_pow, push_product, push_ratio, push_sum, push_to_cylin, push_to_sphere, EV_defaultHandler, add_to_top, are_units_consistent, compare_numbers, de_initRes, de_loop, did_push_approx_inflection_point, divide_top, dv_create_graph_titles, EQU_getNameInfo, get_ub, GM_Derivative, GM_DistArc, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_execute_de, gr_execute_seq, GT_IncXY, GT_PrintCursor, GT_Trace, index_if_pushed_qquad_info, InitDEMem, InitTimeSeq, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_float_qr_fact, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, push_trig, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, time_loop, times_top, VarRecall, ROM Call 0x494, ROM Call 0x495, push_half, push_minus_half


push_half

push_half Function (ROM Call 0x4EB)
AMS 2.00 or higher estack.h

void push_half (void);

Pushes a tagged fraction +1/2 or a tagged float 0.5, depending on the mode setting.

If the mode setting is APPROX, the tagged float 0.5 is pushed onto the EStack. Else, the tagged fraction +1/2 is pushed by calling push_reciprocal_of_quantum(2);

Uses: push_reciprocal_of_quantum, push_Float
Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_atanh, push_comb, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_rec_to_angle, push_sin2, push_sinh, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere

See also: push0, push1, push_minus1, push_minus_half, push_reciprocal_of_quantum


push_i

push_i Function (Macro)
estack.h

void push_i (void);

Pushes i.

The complex i is pushed onto the EStack, in float or integer form, depending on the APPROX mode setting.


push_internal_simplify

push_internal_simplify Function (ROM Call 0x4F8*)
AMS 1.01 or higher estack.h

void push_internal_simplify (CESI ptr);

Converts an expression into internal canonic form and pushes the result to the expression stack.

This extremely important low-level subroutine converts an expression pointed to by ptr to the internal canonic form (see top_estack for more info about the internal canonic form), and pushes the converted expression at the top of the expression stack. This routine accepts all valid (algebraic, calculus, relational, logical or Boolean) tokenized expressions. During the conversion, various simplifications may be performed as well. This routine may cause heap compression, stack expansion, and may throw an error if something goes wrong.

Uses: are_expressions_identical, bottom_estack, delete_between, is_free_of_tag, is_independent_of, next_expression_index, push_expr_quantum, push_expression, push_quantum, top_estack, push_indir_name, ER_catch, ER_success, ER_throwVar, did_push_var_val, does_push_fetch, is_constant, is_real, is_variable, NG_control, NG_such_that_index, primary_tag_list, replace_top2_with_and, DerefSym, VarRecall, ROM Call 0x5E4
Used by: cmd_dialog, cmd_endfor, cmd_endwhile, cmd_if, cmd_ifthen, cmd_return, cmd_sinreg, cmd_while, did_push_anti_deriv, push_1st_derivative, push_abs, push_approx, push_conj, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_im, push_lim, push_max, push_min, push_nint, push_nsolve, push_part, push_phase, push_randpoly, push_re, push_sign, push_solve, push_summation, push_when, push_zeros, push_dot_exponentiate, push_equals, push_greater_than, push_greater_than_or_equals, push_indir_name, push_less_than, push_less_than_or_equals, push_not_equals, push_substitute_simplify, push_substitute_using_such_that, EV_defaultHandler, HomeExecute, are_units_consistent, did_push_approx_inflection_point, get_lb, get_ub, index_if_pushed_qquad_info, is_negative, is_nonnegative, is_nonpositive, is_positive, push_format, push_simplify, push_simplify_statements, push_user_func, replace_top_with_post_simplified, ROM Call 0x450, push_subscripted_element, ROM Call 0x4E6


push_LIST_TAG

push_LIST_TAG Function (ROM Call 0x264)
estack.h

void push_LIST_TAG (void);

Pushes list tag to the expression stack.

push_LIST_TAG pushes LIST_TAG to the expression stack. This is the same as push_quantum (LIST_TAG).

push_LIST_TAG may be useful when you want to push a list on the expressions stack: first push END_TAG (using push_END_TAG), then all elements of the list in reverse order, and finally push LIST_TAG.

Uses: push_quantum
Used by: push_setmode, de_initRes, de_loop, InitDEMem

See also: push_quantum


push_long_to_integer

push_long_to_integer Function (ROM Call 0x4E3)
AMS 2.00 or higher estack.h

void push_long_to_integer (long value);

Pushes a signed long integer to the expression stack.

push_long_to_integer pushes the long integer value value to the expression stack. It is the same as push_longint, except that it is implemented in the operating system instead of by GCC4TI.

Uses: push_quantum
Used by: push_rotate, push_shift, push_and, push_not, push_or

See also: push_ulong_to_integer, push_ushort_to_integer, push_longint


push_longint

push_longint Function (tigcc.a)
AMS 1.01 or higher estack.h

void push_longint (long value);

Pushes a long integer to the expression stack.

push_longint pushes the long integer value value to the expression stack.

Note: push_longint is not a TIOS entry; it is implemented "by hand" using push_quantum. This means that either push_shortint or push_longint should be used in a program, but using both is usually not desirable.

Uses: push_quantum

See also: push_shortint, push_longlongint


push_longlongint

push_longlongint Function (tigcc.a)
AMS 1.01 or higher estack.h

void push_longlongint (long long value);

Pushes a double-long integer to the expression stack.

push_longlongint pushes the double-long integer value value to the expression stack.

Note: push_longlongint is not a TIOS entry; it is implemented "by hand" using push_quantum.

Uses: push_quantum

See also: push_shortint, push_longint


push_minus1

push_minus1 Function (ROM Call 0x4EE)
AMS 2.00 or higher estack.h

void push_minus1 (void);

Pushes a tagged integer or a tagged float -1, depending on the mode setting.

If the mode setting is APPROX, the tagged float -1.0 is pushed onto the EStack. Else, the tagged integer -1 is pushed by push_exact_minus1.

Uses: FloatMinus1Index, push_expression, push_exact_minus1
Used by: get_ub, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_asin, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_sign, push_solve, push_tanh, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product

See also: push0, push1, push_exact0, push_exact1, push_exact_minus1


push_minus_half

push_minus_half Function (ROM Call 0x4F0)
AMS 2.00 or higher estack.h

void push_minus_half (void);

Pushes a tagged fraction -1/2 or a tagged float -0.5, depending on the mode setting.

If the mode setting is APPROX, the tagged float -0.5 is pushed onto the EStack. Else, the tagged fraction -1/2 is pushed by calling push_minus_recip_of_quantum(2);

Uses: push_minus_recip_of_quantum, push_Float
Used by: did_push_anti_deriv

See also: push0, push1, push_minus1, push_half, push_minus_recip_of_quantum


push_minus_recip_of_quantum

push_minus_recip_of_quantum Function (ROM Call 0x510)
AMS 2.02 or higher estack.h

void push_minus_recip_of_quantum (ESQ q);

Pushes on the EStack minus the reciprocal of the argument as a tagged negative fraction.

This function assumes that its argument is strictly superior to 1.

Uses: push_quantum_pair, top_estack
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_asin, push_atan, push_atanh, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_rec_to_angle, push_sin2, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_minus_half

See also: push_reciprocal_of_quantum, push_quantum_as_nonnegative_int, push_negate_quantum_as_negint, push_quantum_pair_as_pos_frac


push_negate_quantum_as_negint

push_negate_quantum_as_negint Function (ROM Call 0x4F1)
AMS 2.00 or higher estack.h

void push_negate_quantum_as_negint (ESQ);

Pushes on the EStack the argument as a tagged negative integer.

This function assumes that its argument is strictly superior to 0.

Uses: push_quantum_pair, top_estack
Used by: get_ub, push_gcd_then_cofactors, push_make_proper, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_factor, push_fractional_part, push_lim, push_max, push_min, push_nint, push_nsolve, push_phase, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, push_to_dd, push_to_dms

See also: push_quantum_as_nonnegative_int, push_reciprocal_of_quantum, push_minus_recip_of_quantum, push_quantum_pair_as_pos_frac


push_next_arb_int

push_next_arb_int Function (ROM Call 0x2EB)
AMS 1.01 or higher estack.h

void push_next_arb_int (void);

Pushes a next "arbitrary integer" symbol to the expression stack.

push_next_arb_int pushes a next "arbitrary integer" symbol (i.e. symbol @n xxx) to the top of the expression stack. More precise, it increments an internal counter for arbitrary integers, pushes the counter on the stack, then pushes ARB_INT_TAG. The counter wraps to zero after 255 is reached.

Uses: ARb_int_count, push_quantum_pair
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_next_arb_real

push_next_arb_real Function (ROM Call 0x2EC)
AMS 1.01 or higher estack.h

void push_next_arb_real (void);

Pushes a next "arbitrary real" symbol to the expression stack.

push_next_arb_int pushes a next "arbitrary real" symbol (i.e. symbol @xxx) to the top of the expression stack. More precise, it increments an internal counter for arbitrary reals, pushes the counter on the stack, then pushes ARB_REAL_TAG. The counter wraps to zero after 255 is reached.

Uses: ARb_real_count, push_quantum_pair
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, ROM Call 0x4E6


push_next_internal_var

push_next_internal_var Function (ROM Call 0x2ED)
AMS 1.01 or higher estack.h

void push_next_internal_var (ESQ Tag);

Pushes an internal variable to the expression stack.

push_next_internal_var is an auxiliary function used in calculus operations. It pushes the sequence 0, Tag+1, count, 0 to the expression stack, where count is the internal counter of internal variables. Then, the counter is increased by one. TIOS usually passes 0 or 1 for Tag, so it manages a two independent sets of internal variables. You can see that internal variable names consist of two bytes (see VAR_NAME_TAG): one byte is "set number", and another byte is "number of a variable in the set".

Uses: push_quantum_pair, ROM Call 0x5C4
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nint, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


push_no_solution_found_string

push_no_solution_found_string Function (ROM Call 0x4CC)
AMS 2.00 or higher estack.h

void push_no_solution_found_string (void);

Pushes "No solution found", or its localized version if a language localization is active (on AMS 2.xx), on the EStack.

The string is pushed as an AMS string using push_zstr.

Uses: push_zstr, XR_stringPtr
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_offset_array

push_offset_array Function (ROM Call 0x3C4)
AMS 1.01 or higher estack.h

unsigned short push_offset_array (CESI elements_ptr, unsigned short **dest);

Pushes an array of offsets to the list items.

This function is not complicated, but it is a bit hard to explain. It first increments the pointer to the top of the expression stack to the nearest even address, then pushes a word array which contains the offsets to all entries on the expression stack below elements_ptr until END_TAG is reached. The offset is expressed relative to the elements_ptr. push_offset_array returns the size of pushed array in words (i.e. the number of elements), and stores in the pointer variable pointed to by dest the top address of pushed array. For example, if you execute the following sequence

unsigned int *offsets;
ESI esi;
unsigned int count;
...
esi=top_estack;
count=push_offset_array (esi, &offsets);

then esi-offsets[0], esi-offsets[-1], esi-offsets[-2], ..., esi-offsets[1-count] will point to entries on the expression stack. esi-offsets[0] will point to the further entry from the top of the expression stack, esi-offsets[-1] will point to the next one, and finally, esi-offsets[1-count] will point to the entry on the top of the expression stack (more precise, offsets[1-count] is always zero). This function is useful when you need a fast way to access to all entries on the expression stack many times.

Uses: check_estack_size, next_expression_index, top_estack, estack_max_index
Used by: map_tail, map_tail_Int, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_dotproduct, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nint, push_nsolve, push_numerator, push_phase, push_re, push_round, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_list_plus, push_list_times, push_negate, push_not_equals, push_or, push_product, push_substitute_no_simplify, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, did_map_aggregate_arg, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_mrow_aux, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, push_zero_partial_column, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, cmd_lu_fact


push_overflow_to_infinity

push_overflow_to_infinity Function (ROM Call 0x30E)
AMS 1.01 or higher estack.h

void push_overflow_to_infinity (ESQ inf_tag);

Displays a warning, and pushes a tag to the expression stack.

push_overflow_to_infinity displays the warning message "Warning: Overflow replaced by INF or -INF", then pushes byte inf_tag to the expression stack (it is usually INFINITY_TAG or NEGINFINITY_TAG).

Uses: push_quantum, ST_helpMsg, XR_stringPtr
Used by: push_Float, push_cosh, push_exp, push_sinh, push_factorial


push_parse_text

push_parse_text Function (ROM Call 0x3CA)
AMS 1.01 or higher estack.h

short push_parse_text (const char *str);

Parses an expression given in a string and pushes tokenized expression to the expression stack.

push_parse_text is an extremely powerful function: it parses the expression given in the string str, and pushes the expressions (in RPN form) to the expression stack. This function also can parse TI-Basic statements (after parsing, the tokenized form of these statements is pushed on the expression stack too). push_parse_text returns FALSE if the expression is a multi expression (i.e. if it contains ":" [separator], "->" [store] or TI-Basic statements), otherwise it returns TRUE. This routine may cause expansion of the expression stack or heap compression. GCC4TILIB internally uses this function (together with estack_number_to_Float) in the implementation of atof function. For more examples of usage of this function, see NG_approxESI, NG_rationalESI, NG_execute etc. The "inverse" function of push_parse_text is display_statements.

If you want to perform highly advanced symbolic operations with expressions, you should know that expressions created by push_parse_text are not always organized on a way which allows the most efficient symbolic processing (so-called internal canonic form). For example, TIOS always converts 'x*3' into '3*x' and converts 'x-y' into 'x+y*(-1)', although it will be printed as 'x-y'. However, expressions created by push_parse_text are always as-is, i.e. '3*x' will be just '3*x', not 'x*3'. Some routines (like numeric_factor_index for example) may be fooled if the expression is not "sorted" correctly. Also, some routines (like lead_term_index, lead_factor_index etc.) may also be fooled with expressions like 'x-y' and 'x/y', because operators '-' and '/' are usually never seen in expressions during symbolic processing (the processing is more unique if addition and subtraction are treated as the same operation; the same is true for '*' and '/'). So, if you planed to perform some advanced symbolic processing which is based on accessing various part of the expression, always call push_internal_simplify after calling push_parse_text. This function pushes on the expression stack the same expression but converted in internal canonic form.

Note: push_parse_text will throw an error if the string contains expression with wrong syntax, so you need to use TRY etc. to catch eventual errors. And, the string must be built using TI-Basic conventions (for example, you must use 0xAD ("small" minus) instead of '-' for unary minus, etc. See NG_tokenize for a more powerful function which doesn't throw any errors, and which can determine the exact location and type of the error.

Uses: are_expressions_identical, check_estack_size, delete_between, delete_expression, is_valid_smap_aggregate, map_tail, move_between_to_top, next_expression_index, push_between, push_expression, push_Float, push_quantum, push_quantum_pair, push_reversed_tail, top_estack, ER_catch, ER_success, ER_throwVar, OSCheckBreak, CTypeTable, fix_loop_displacements, is_pathname, next_token, nonblank, primary_tag_list, push_ans_entry, push_var, CheckReservedName, DerefSym, FindSymInFolder, TempFolderName, strtod, ROM Call 0x5C5, ROM Call 0x5EF, ROM Call 0x5F0
Used by: NG_tokenize, TokenizeSymName, push_str_to_expr, handleVarLinkKey, HomeExecute, atof, FolderDel, FolderRename, HSymDel, SymFindFolderName, ROM Call 0x46F, DateAndTime_SetDlg


push_pi_on_quantum

push_pi_on_quantum Function (ROM Call 0x513)
AMS 2.02 or higher estack.h

void push_pi_on_quantum (ESQ);

Pushes on the EStack the quotient of PI (numerator) and of the argument (denominator), in a way depending on the mode setting.

If the mode setting is APPROX, then a tagged float is pushed on the EStack. The sequence of bytes [reciprocal of argument] PI_TAG MUL_TAG is pushed otherwise.
This function assumes that its argument is strictly superior to 1.

Uses: FloatPiIndex, push_reciprocal_of_quantum, replace_top2_with_prod, push_expression, top_estack
Used by: get_ub, is_negative, is_nonnegative, is_nonpositive, is_positive, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_acos, push_acosh, push_asin, push_atan, push_atanh, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_rec_to_angle, push_solve, push_zeros, push_degrees, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_radians

See also: push_pi


push_pi

push_pi Function (ROM Call 0x512)
AMS 2.02 or higher estack.h

void push_pi (void);

Pushes on the EStack a tagged float PI if the mode setting is APPROX, otherwise pushes a PI_TAG.

This function assumes nothing.

Uses: FloatPiIndex, push_expression, push_quantum
Used by: get_ub, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_perm, push_phase, push_rec_to_angle, push_sin2, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals

See also: push_pi_on_quantum


push_quantum_as_nonnegative_int

push_quantum_as_nonnegative_int Function (ROM Call 0x50E)
AMS 2.02 or higher estack.h

void push_quantum_as_nonnegative_int (ESQ);

Pushes on the EStack the argument as a tagged positive integer.

This function assumes that its argument is strictly superior to 0.

Uses: push_quantum, top_estack
Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_atan, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_integer_part, push_is_prime, push_lim, push_log10, push_max, push_min, push_nsolve, push_numerator, push_ord, push_phase, push_randpoly, push_re, push_sin2, push_solve, push_tan, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, push_to_dd, push_to_dms

See also: push_negate_quantum_as_negint, push_reciprocal_of_quantum, push_minus_recip_of_quantum, push_quantum_pair_as_pos_frac


push_quantum_pair_as_pos_frac

push_quantum_pair_as_pos_frac Function (ROM Call 0x511)
AMS 2.02 or higher estack.h

void push_quantum_pair_as_pos_frac (ESQ, ESQ);

Pushes on the EStack the quotient of the first argument (numerator) and the second argument (denominator).

This function assumes:

  • that the numerator and the denominator are relatively prime;
  • that the numerator is strictly superior to 0;
  • that the denominator is strictly superior to 1.

Uses: push_quantum_pair, top_estack
Used by: push_extended_prod, push_sin2, push_summation

See also: push_quantum_as_nonnegative_int, push_negate_quantum_as_negint, push_reciprocal_of_quantum, push_minus_recip_of_quantum


push_quantum_pair

push_quantum_pair Function (ROM Call 0x2EF)
AMS 1.01 or higher estack.h

void push_quantum_pair (ESQ Tag1, ESQ Tag2);

Pushes two bytes (tags) to the expression stack.

push_quantum_pair pushes the bytes Tag1 and Tag2 to the expression stack. Basically, it acts like:

push_quantum (Tag1);
push_quantum (Tag2);
but it is a little more optimized.

Uses: check_estack_size, top_estack, estack_max_index
Used by: push_next_arb_int, push_next_arb_real, push_next_internal_var, push_parse_text, push_zstr, cmd_blddata, cmd_dialog, cmd_linetan, cmd_popup, cmd_sinreg, did_push_anti_deriv, did_push_series, push_1st_derivative, push_atan, push_atanh, push_char, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_diag, push_expand, push_factor, push_floor, push_fractional_part, push_im, push_instring, push_is_prime, push_left, push_lim, push_ln, push_max, push_median, push_mid, push_min, push_nsolve, push_numerator, push_part, push_phase, push_re, push_rotate, push_sequence, push_shift, push_sign, push_sin2, push_solve, push_string, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, EQU_getNameInfo, get_ub, GetStatValue, GT_IncXY, GT_Trace, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_poly_qr, push_quantum_pair_as_pos_frac, push_reciprocal, push_reciprocal_of_quantum, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, tokenize_if_TI_92_or_text, push_cylin_vector, push_polar_vector, push_spher_vector

See also: push_quantum


push_quantum

push_quantum Function (ROM Call 0x2EE*)
estack.h

void push_quantum (ESQ Tag);

Pushes a byte (tag) to the expression stack.

push_quantum is the basic function for manipulating the expression stack, and many other functions are based on it. It pushes a byte Tag to the expression stack. For example, you can push a complex value to the expression stack using the following construction:

push_Float (real_part);
push_Float (imaginary_part);
push_quantum (COMPLEX_TAG);
See push_Float, and info about top_estack and Tags for more info about this example.

Note: This routine (as well as all other "push_..." routines) may cause heap compression, and may throw an error if there is not enough space on the expression stack.

Uses: check_estack_size, top_estack, estack_max_index
Used by: compare_complex_magnitudes, map_tail, map_tail_Int, map_unary_over_comparison, next_expression_index, Parse2DExpr, Parse2DMultiExpr, push_END_TAG, push_Float, push_Float_to_nonneg_int, push_internal_simplify, push_LIST_TAG, push_long_to_integer, push_longint, push_longlongint, push_overflow_to_infinity, push_parse_text, push_reversed_tail, push_shortint, push_transpose_aux, push_ulong_to_integer, push_ushort_to_integer, push_zstr, cmd_blddata, cmd_circle, cmd_dialog, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_fill, cmd_input, cmd_inputstr, cmd_linetan, cmd_popup, cmd_printobj, cmd_prompt, cmd_shade, cmd_sinreg, cmd_slpline, cmd_sorta, cmd_sortd, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_augment, push_char, push_comb, push_comdenom, push_conj, push_cos, push_cosh, push_cross_product, push_csolve, push_cumsum, push_czeros, push_def_int, push_denominator, push_desolve, push_diag, push_dimension, push_dotproduct, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_identity_mat, push_im, push_instring, push_integer_lcm, push_integer_part, push_is_prime, push_left, push_lim, push_list_to_mat, push_ln, push_log10, push_mat_to_list, push_max, push_max1, push_max2, push_median, push_mid, push_min, push_min1, push_min2, push_mod, push_mrowadd, push_newlist, push_newmat, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_ord, push_phase, push_prodlist, push_pttest, push_pxltest, push_rand, push_randmat, push_randpoly, push_re, push_rec_to_angle, push_right, push_rotate, push_round, push_rowadd, push_rowdim, push_rowswap, push_sequence, push_shift, push_sign, push_sin, push_sin2, push_sinh, push_solve, push_sqrt, push_stddev, push_str_to_expr, push_string, push_submat, push_sumlist, push_summation, push_tan, push_tanh, push_variance, push_when, push_zeros, did_push_to_polar, push_and, push_dot_exponentiate, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_indir_name, push_less_than, push_less_than_or_equals, push_list_plus, push_list_times, push_matrix_product, push_negate, push_not, push_not_equals, push_or, push_product, push_substitute_no_simplify, push_substitute_simplify, push_sum, push_to_cylin, push_to_sphere, HomeExecute, OSLinkCmd, add_to_top, are_units_consistent, compare_numbers, did_map_aggregate_arg, did_push_approx_inflection_point, dv_create_graph_titles, EQU_getNameInfo, get_ub, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_ck_solvergraph, gr_execute_de, gr_execute_seq, GraphOrTableCmd, GT_IncXY, GT_Trace, has_different_variable, index_if_pushed_qquad_info, InitTimeSeq, is_negative, is_nonnegative, is_nonpositive, is_positive, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_float_qr_fact, push_format, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_mrow_aux, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_parse_prgm_or_func_text, push_pi, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_simplify, push_standardize, push_symbolic_qr_fact, push_trig, push_unit_system_list, push_user_func, push_var, push_var_kern_tail, push_zero_partial_column, raise_to_top, replace_top_with_post_simplified, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, run_one_seq, SP_Define, spike_in_editor, spike_optionD, store_func_def, times_top, tokenize_if_TI_92_or_text, VarRecall, ROM Call 0x468, cmd_lu_fact, ROM Call 0x48D, ROM Call 0x494, ROM Call 0x495, push_dense_poly_eval, push_to_dd, push_to_dms, push_subscripted_element, ROM Call 0x4E6

See also: push_quantum_pair, push_expression, push_expr_quantum


push_reciprocal_of_quantum

push_reciprocal_of_quantum Function (ROM Call 0x50F)
AMS 2.02 or higher estack.h

void push_reciprocal_of_quantum (ESQ q);

Pushes on the EStack the reciprocal of the argument as a tagged positive fraction.

This function assumes that its argument is strictly superior to 1.

Uses: push_quantum_pair, top_estack
Used by: push_pi_on_quantum, push_trig, replace_top_with_post_simplified, push_acosh, push_asin, push_atan, push_atanh, push_desolve, push_factor, push_sin2, push_sqrt, push_degrees, push_exponentiate, push_percent, push_half

See also: push_minus_recip_of_quantum, push_quantum_as_nonnegative_int, push_negate_quantum_as_negint, push_quantum_pair_as_pos_frac


push_reversed_tail

push_reversed_tail Function (ROM Call 0x3BF)
AMS 1.01 or higher estack.h

void push_reversed_tail (CESI ptr);

Pushes elements of the list up to tail onto the stack in reversed order.

push_reversed_tail first pushes END_TAG to the expression stack, then pushes all expressions starting from the expression pointed to by ptr one by one (by calling next_expression_index) until END_TAG is reached. So after calling this function, the expressions up to tail will be pushed onto the stack in reversed order. See other "tail" operations like map_tail.

Uses: next_expression_index, push_between, push_quantum
Used by: push_parse_text, did_push_anti_deriv, push_1st_derivative, push_csolve, push_cumsum, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_sequence, push_shift, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, EQU_getNameInfo, get_ub, push_parse_prgm_or_func_text, push_to_dms, ROM Call 0x4E6


push_round_Float

push_round_Float Function (ROM Call 0x310)
AMS 1.01 or higher estack.h

void push_round_Float (CESI ptr);

Pushes an approximation of a floating point entry.

push_round_Float first finds a rational approximation of the floating point entry pointed to by ptr using push_Float_to_rat, then converts this fraction back to the floating point number and pushes it on the top of the expressions stack. The summary effect is rounding float to the precision of about 1e-5.

Uses: delete_between, estack_number_to_Float, push_Float, push_Float_to_rat, top_estack, RAtionalize_tol
Used by: ROM Call 0x48C


push_shortint

push_shortint Function (tigcc.a)
AMS 1.01 or higher estack.h

void push_shortint (short value);

Pushes a short integer to the expression stack.

push_shortint pushes the short integer value value to the expression stack.

Note: push_shortint is not a TIOS entry; it is implemented "by hand" using push_quantum. This means that either push_shortint or push_longint should be used in a program, but using both is usually not desirable.

Uses: push_quantum

See also: push_longint, push_longlongint


push_simplify

push_simplify Function (ROM Call 0x44E)
AMS 2.00 or higher estack.h

void push_simplify (CESI ptr);

Simplifies the argument and pushes onto the estack.

push_simplify is like push_internal_simplify, but does not convert into internal canonic form.

Uses: delete_between, is_constant, is_free_of_tag, is_independent_of, is_variable, next_expression_index, push_expr_quantum, push_internal_simplify, push_quantum, top_estack, push_indir_name, ER_catch, ER_success, ER_throwVar, DerefSym, VarRecall, did_push_var_val, does_push_fetch, is_real, NG_control, NG_such_that_index, primary_tag_list, replace_top_with_post_simplified, replace_top2_with_and, ROM Call 0x5E2, ROM Call 0x5E5
Used by: NG_approxESI, NG_graphESI, NG_rationalESI, cmd_custom, cmd_dialog, cmd_input, cmd_inputstr, cmd_popup, cmd_prompt, cmd_request, cmd_sorta, cmd_sortd, cmd_toolbar, push_part, push_assignment, push_simplify_statements, ROM Call 0x4DC


push_transpose_aux

push_transpose_aux Function (ROM Call 0x3C1)
AMS 1.01 or higher estack.h

void push_transpose_aux (CESI ptr, short ConjFlag);

Pushes transposed matrix to the expression stack.

Assuming that ptr points to the tag of a matrix (which is, in fact, a list of equally sized lists), push_transpose_aux pushes the transpose of the matrix to the expression stack. If ConjFlag is TRUE, a complex conjugate transpose will be produced, and if ConjFlag is FALSE, an ordinary transpose will be produced. For complex conjugate transposition, the matrix should be in canonic internal form (see push_internal_simplify). If ptr doesn't point to a matrix, the behavior is unpredictable.

Uses: delete_between, push_expression, push_quantum, top_estack, push_conj, get_matrix_indices
Used by: push_symbolic_qr_fact, push_transpose


push_ulong_to_integer

push_ulong_to_integer Function (ROM Call 0x4E4)
AMS 2.00 or higher estack.h

void push_ulong_to_integer (unsigned long value);

Pushes an unsigned long integer to the expression stack.

push_ulong_to_integer pushes the long integer value value to the expression stack. It is the same as push_long_to_integer, except that the value is interpreted as an unsigned value.

Uses: push_quantum
Used by: push_determinant, push_extended_prod, push_getkey, push_instring, push_mean, push_part, push_red_row_ech, push_row_echelon, push_simult, push_stddev, push_summation, push_switch, push_variance, push_list_plus, push_lu_fact, push_sq_matrix_to_whole_number, push_symbolic_qr_fact, strtod

See also: push_long_to_integer, push_ushort_to_integer, push_longint


push_ushort_to_integer

push_ushort_to_integer Function (ROM Call 0x4E5)
AMS 2.00 or higher estack.h

void push_ushort_to_integer (unsigned short value);

Pushes an unsigned short integer to the expression stack.

push_ushort_to_integer pushes the short integer value value to the expression stack. It is the same as push_shortint, except that the value is interpreted as an unsigned value, and that it is implemented in the operating system instead of by GCC4TI.

Uses: push_quantum, top_estack
Used by: push_factor

See also: push_long_to_integer, push_ulong_to_integer, push_shortint


push_zstr

push_zstr Function (ROM Call 0x48A*)
AMS 1.01 or higher estack.h

void push_zstr (const char *str);

Pushes a standard C string to the expression stack.

push_zstr pushes the string str to the expression stack. str is a standard ANSI (zero-terminated) string.

Uses: push_quantum, push_quantum_pair
Used by: cmd_dialog, cmd_request, push_getfold, push_gettype, push_part, push_setfold, push_setmode, push_auto_units_conversion, push_unit_system_list, push_no_solution_found_string


raise_to_top

raise_to_top Function (ROM Call 0x529)
AMS 2.02 or higher estack.h

void raise_to_top (CESI ptr);

Raises a value to the power given by the expression on the top of the EStack.

raise_to_top raises the expression pointed to by ptr to the power indicated by the expression currently at the top of the EStack, and stores the result to the top of the EStack, in place of the expression that was used as power.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_sqrt, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere


re_index

re_index Function (ROM Call 0x2F2)
AMS 1.01 or higher estack.h

ESI re_index (CESI ptr);

Gets the index of the real part of an expression.

If ptr points to the COMPLEX_TAG (i.e. if the expression is complex), re_index returns the pointer to the real part of the expression. If ptr does not point to the COMPLEX_TAG (i.e. if the expression is real), re_index returns ptr (i.e. the pointer to the expression itself).

Note: The expression should be in internal canonic form (see push_internal_simplify), else this function is not reliable.

Uses: next_expression_index
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, is_neg_lead_numr_coef_re_part


reductum_index

reductum_index Function (ROM Call 0x2F0)
AMS 1.01 or higher estack.h

ESI reductum_index (CESI ptr);

Gets the index of remaining terms of an expression.

If ptr points to the ADD_TAG, which is a case when it points to an expression of form term1 + term2 + ... (i.e. if the expression is a sum of simpler terms), reductum_index returns the pointer to the subexpression term2 + ... (which is a reductum subexpression of the given expression). If ptr does not point to the ADD_TAG (i.e. if the expression is not a sum of simpler terms), reductum_index returns a pointer to a simple zero expression, i.e. expression which consists only of number 0 (floating point or integer, depending of whether the approximation mode is active or not).

Note: Expressions in internal canonic form have the most main term shallowest (see lead_term_index. So, the reductum of '2+x+y' converted to canonic form is 'y+2'. By default, similar powers of the main variable are collected in internal canonic forms. For example, the reductum of 'x^2*y+x^2+5' converted to canonic form is '5'. See push_internal_simplify for more info about how to convert an expression into the internal canonic form.

Uses: next_expression_index, Float0Index, Integer0Index
Used by: did_push_anti_deriv, did_push_series, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_lim, push_max, push_min, push_nsolve, push_phase, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, get_ub, index_reductum_with_tag_base, push_but_term, push_constant_terms, push_dependent_terms, push_gcd_then_cofactors, push_independent_terms, push_make_proper, push_nonconstant_terms, push_poly_qr, push_standardize, replace_top_with_post_simplified, replace_top2_with_sum


remaining_element_count

remaining_element_count Function (ROM Call 0x3C3)
AMS 1.01 or higher estack.h

unsigned short remaining_element_count (CESI start_ptr);

Returns number of elements remaining.

remaining_element_count counts how many expressions are stored on the expressions stack below the expression pointed to by ptr (including this one). END_TAG is treated as the terminator, so eventual expressions below END_TAG are not counted. So, if ptr points to an element of the list, remaining_element_count returns the number of elements in the list starting from this element up to the end of the list.

remaining_element_count works using repeated calling next_expression_index and increasing a counter until END_TAG is reached.

Uses: next_expression_index
Used by: RemainingArgCnt, cmd_fill, cmd_newdata, cmd_send, cmd_sinreg, cmd_sorta, cmd_sortd, did_push_anti_deriv, push_1st_derivative, push_augment, push_coldim, push_cross_product, push_csolve, push_czeros, push_def_int, push_desolve, push_determinant, push_dimension, push_dotproduct, push_factor, push_left, push_lim, push_list_to_mat, push_max, push_mean, push_mid, push_min, push_nsolve, push_red_row_ech, push_right, push_rotate, push_row_echelon, push_rowdim, push_shift, push_simult, push_solve, push_stddev, push_unitv, push_variance, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_list_plus, push_not_equals, is_matrix, is_square_matrix, is_valid_smap_aggregate, get_list_indices, get_matrix_indices, get_ub, GetStatValue, push_float_qr_fact, push_lu_fact, push_sq_matrix_to_whole_number, push_symbolic_qr_fact, push_user_func, replace_top_with_post_simplified, spike_geo_titles, spike_optionD, VarRecall, ROM Call 0x494, ROM Call 0x495


remaining_factors_index

remaining_factors_index Function (ROM Call 0x2F1)
AMS 1.01 or higher estack.h

ESI remaining_factors_index (CESI ptr);

Gets the index of remaining factors of an expression.

If ptr points to the MUL_TAG, which is a case when it points to an expression of form factor1 * factor2 * ... (i.e. if the expression is a sum of simpler terms), remaining_factors_index returns the pointer to the subexpression term2 * ... (i.e. to the remaining factors of the expression). If ptr does not point to the MUL_TAG (i.e. if the expression is not a product of simpler factors), remaining_factors_index returns a pointer to a simple expression which consists only of number 1.

Note: Expressions in internal canonic form have the most main factor shallowest, with less main factors below that (see compare_expressions for more info about "main" ordering). Also, the lead factor of an internally-simplified product is never a product. For example, remaining factors of '(3*x^2)*y' converted into canonic form are '3*y'. By default, similar powers of the main variable are collected, so remaining factor of 'x^2*y+x^2' after conversion into canonic form is 'y+1'. Internally-simplified numeric denominator factors are combined with numeric numerator factors into a fractional numeric factor. Non-numeric denominator factors are internally simplified to be merged with numerator factors as negative powers. See push_internal_simplify for more info about how to convert an expression into the internal canonic form.

Uses: next_expression_index, Float1Index, Integer1Index
Used by: is_monomial, is_monomial_in_kernel, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sign, push_sin2, push_sinh, push_solve, push_summation, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, add_to_top, are_units_consistent, did_push_divide_units, get_ub, has_unit_base, index_if_pushed_binomial_info, index_if_pushed_qquad_info, index_reductum_with_tag_base, index_rmng_factor, index_rmng_fctrs_start_base, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, is_negative, is_nonnegative, is_nonpositive, is_positive, is_term_improper, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x48D


replace_top_with_post_simplified

replace_top_with_post_simplified Function (ROM Call 0x5B6)
AMS 2.02 or higher estack.h

void replace_top_with_post_simplified (ESI prev_top);

Replaces the expression on top of the EStack, in internal form, with the external (printing) form.

See display_statements and top_estack for more information about the external form.
prev_top should usually be next_expression_index(top_estack).

Uses: add_to_top, compare_numbers, did_map_aggregate_arg, did_push_divide_units, estack_to_float, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, index_reductum_with_tag_base, index_rmng_factor, index_rmng_fctrs_start_base, index_rmng_fctrs_start_fctr_tag, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_equivalent_to, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_units_term, is_variable, is_whole_number, is0, is1, negate_top, NG_control, NG_such_that_index, primary_tag_list, push_auto_units_conversion, push_but_factor, push_but_term, push_negate_quantum_as_negint, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_quantum_as_nonnegative_int, push_reciprocal, push_reciprocal_of_quantum, push1, raise_to_top, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, RemainingArgCnt, push_abs, push_approx, push_ceiling, push_cos, push_cosh, push_denominator, push_exp, push_gcd_numbers, push_ln, push_mod, push_numerator, push_phase, push_sin, push_sinh, push_tan, push_tanh, did_push_to_polar, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_ratio, push_square, push_sum, push_to_cylin, push_to_sphere, ER_catch, ER_success, ER_throwVar, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, index_main_var, is_advanced_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, map_tail_Int, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_internal_simplify, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, fmod, is_nan, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, command_tag_list, ROM Call 0x5E6, ROM Call 0x5EC
Used by: push_simplify, push_simplify_statements, push_user_func

See also: display_statements, top_estack, push_simplify, push_internal_simplify


replace_top_with_reciprocal

replace_top_with_reciprocal Function (ROM Call 0x52D)
AMS 2.02 or higher estack.h

void replace_top_with_reciprocal (void);

Replaces the expression on top of the EStack by its reciprocal.

replace_top_with_reciprocal computes the reciprocal of the expression currently at the top of the EStack, and stores the result in place of the expression.

Uses: push_reciprocal, delete_expression, top_estack
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


replace_top2_with_and

replace_top2_with_and Function (ROM Call 0x57A)
AMS 2.02 or higher estack.h

void replace_top2_with_and (ESI expr);

Replace the two top-most expressions on the EStack by their logical AND.

The following code:

push_quantum(TRUE_TAG);
ptr = top_estack;
push_quantum(FALSE_TAG);
replace_top2_with_and(ptr);
will leave the false expression on the EStack.
expr should usually be next_expression_index(top_estack).

Uses: push_and, delete_between, next_expression_index, top_estack
Used by: get_ub, push_simplify, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_and, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not, push_not_equals, push_internal_simplify

See also: replace_top2_with_or


replace_top2_with_difference

replace_top2_with_difference Function (ROM Call 0x51C)
AMS 2.02 or higher estack.h

void replace_top2_with_difference (ESI expr);

Replace the two top-most expressions on the EStack by their difference.

The following code:

push_quantum(VAR_A_TAG);
ptr = top_estack;
push_quantum(VAR_B_TAG);
replace_top2_with_difference(ptr);
will leave the a - b expression on the EStack.
expr should usually be next_expression_index(top_estack).

Uses: negate_top, replace_top2_with_sum
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_acos, push_atan, push_atanh, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals

See also: replace_top2_with_sum


replace_top2_with_imre

replace_top2_with_imre Function (ROM Call 0x559)
AMS 2.02 or higher estack.h

void replace_top2_with_imre (ESI expr);

Replace the two top-most expressions on the EStack by a complex number.

The following code:

push_quantum(VAR_A_TAG);
ptr = top_estack;
push_quantum(VAR_B_TAG);
replace_top2_with_imre(ptr);
will leave the a + b * i expression on the EStack.
expr should usually be next_expression_index(top_estack).

Uses: estack_to_float, IM_re_tol, Integer0Index, is0, push_difference, push_sum, delete_between, deleted_between, next_expression_index, push_between, push_quantum, should_and_did_push_approx_arg2, top_estack, fabs, _bcd_math
Used by: add_to_top, are_units_consistent, did_push_divide_units, did_push_lincf, divide_top, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_ratio, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_atan, push_atanh, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_im, push_integer_part, push_lim, push_ln, push_max, push_min, push_nint, push_nsolve, push_numerator, push_perm, push_phase, push_r_cis, push_re, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_ratio, push_sum, push_to_cylin, push_to_sphere


replace_top2_with_or

replace_top2_with_or Function (ROM Call 0x57C)
AMS 2.02 or higher estack.h

void replace_top2_with_or (ESI expr);

Replace the two top-most expressions on the EStack by their logical OR.

The following code:

push_quantum(TRUE_TAG);
ptr = top_estack;
push_quantum(FALSE_TAG);
replace_top2_with_or(ptr);
will leave the true expression on the EStack.
expr should usually be next_expression_index(top_estack).

Uses: push_or, delete_between, next_expression_index, top_estack
Used by: did_push_approx_inflection_point, get_ub, GM_Intersect, GM_Math1, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_and, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not, push_not_equals, push_xor

See also: replace_top2_with_and


replace_top2_with_pow

replace_top2_with_pow Function (ROM Call 0x52A)
AMS 2.02 or higher estack.h

void replace_top2_with_pow (ESI expr);

Replace the two top-most expressions on the EStack by a power.

The following code:

push_quantum(VAR_A_TAG);
ptr = top_estack;
push_quantum(VAR_B_TAG);
replace_top2_with_pow(ptr);
will leave the b ^ a expression on the EStack.
expr should usually be next_expression_index(top_estack).

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, push_reciprocal, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_abs, push_asin, push_conj, push_csolve, push_czeros, push_def_int, push_desolve, push_exp, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_sign, push_sin2, push_solve, push_summation, push_tan, push_tanh, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum, ROM Call 0x48D


replace_top2_with_prod

replace_top2_with_prod Function (ROM Call 0x523)
AMS 2.02 or higher estack.h

void replace_top2_with_prod (ESI expr);

Replace the two top-most expressions on the EStack by their product.

The following code:

push_quantum(VAR_A_TAG);
ptr = top_estack;
push_quantum(VAR_B_TAG);
replace_top2_with_prod(ptr);
will leave the a * b expression on the EStack.
expr should usually be next_expression_index(top_estack).

Uses: estack_to_float, is_variable, is0, primary_tag_list, push_product, check_estack_size, delete_between, delete_expression, estack_number_to_Float, next_expression_index, push_between, push_expression, push_Float, push_quantum, should_and_did_push_approx_arg2, top_estack, ST_helpMsg, XR_stringPtr, _bcd_math, _du16u16, _ds32s32, _ms32s32, push_exact0
Used by: add_to_top, are_units_consistent, did_push_approx_inflection_point, divide_top, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi_on_quantum, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_ratio, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_conj, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_nint, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_rec_to_angle, push_red_row_ech, push_row_echelon, push_sign, push_simult, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_degrees, push_dot_exponentiate, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, cmd_lu_fact, cmd_qr_fact, ROM Call 0x48D, push_spher_vector

See also: replace_top2_with_ratio


replace_top2_with_ratio

replace_top2_with_ratio Function (ROM Call 0x528)
AMS 2.02 or higher estack.h

void replace_top2_with_ratio (ESI expr);

Replace the two top-most expressions on the EStack by their ratio.

push_quantum(VAR_A_TAG);
ptr = top_estack;
push_quantum(VAR_B_TAG);
replace_top2_with_ratio(ptr);
will leave the a / b expression on the EStack.
expr should usually be next_expression_index(top_estack).

Uses: Float0Index, is_complex_Float, primary_tag_list, push_reciprocal, replace_top2_with_imre, replace_top2_with_prod, push_dot_div, delete_between, estack_number_to_Float, is_complex_number, next_expression_index, push_expression, push_Float, top_estack, _bcd_math
Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_log10, push_max, push_mean, push_min, push_nsolve, push_numerator, push_phase, push_re, push_rec_to_angle, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere

See also: replace_top2_with_prod


replace_top2_with_sum

replace_top2_with_sum Function (ROM Call 0x519)
AMS 2.02 or higher estack.h

void replace_top2_with_sum (ESI expr);

Replace the two top-most expressions on the EStack by their sum.

The following code:

push_quantum(VAR_A_TAG);
ptr = top_estack;
push_quantum(VAR_B_TAG);
replace_top2_with_sum(ptr);
will leave the a + b expression on the EStack.
expr should usually be next_expression_index(top_estack).

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: did_push_divide_units, did_push_lincf, get_ub, push_gcd_then_cofactors, push_make_proper, push_poly_deg_in_var_or_kernel, push_reciprocal, push_standardize, push_symbolic_qr_fact, replace_top_with_post_simplified, replace_top2_with_difference, subtract_from_top, did_push_anti_deriv, push_1st_derivative, push_abs, push_acosh, push_asin, push_atan, push_atanh, push_colnorm, push_conj, push_cosh, push_cross_product, push_csolve, push_czeros, push_def_int, push_desolve, push_dotproduct, push_expand, push_extended_prod, push_factor, push_im, push_lim, push_ln, push_matnorm, push_max, push_min, push_nsolve, push_re, push_rec_to_angle, push_rownorm, push_sin2, push_sinh, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_matrix_product, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, compare_complex_magnitudes

See also: replace_top2_with_difference


reset_control_flags

reset_control_flags Function (ROM Call 0x2F4)
AMS 1.01 or higher estack.h

void reset_control_flags (void);

Resets the control flags for operations with the expression stack.

reset_control_flags resets various control flags which control operations which use the expression stack. It is good idea to call this function before starting any calculation using the expression stack.

Uses: NG_control, ROM Call 0x5C4, ROM Call 0x5E2, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E6, ROM Call 0x5EC, ROM Call 0x5ED, ROM Call 0x5EF, ROM Call 0x5F0
Used by: NG_execute, EV_centralDispatcher, MO_notifyModeChange, HomeExecute


reset_estack_size

reset_estack_size Function (ROM Call 0x2F3)
AMS 1.01 or higher estack.h

void reset_estack_size (unsigned short NewSize);

Reallocates the expression stack.

reset_estack_size changes the size of the expression stack to NewSize. It throws an error if the requirement cannot be satisfied. If NewSize is smaller than the current amount of used space, then the expression stack is set to the current amount of used space instead of NewSize. Default size of the expression stack is 16384 bytes.

Uses: bottom_estack, top_estack, HeapRealloc, estack_max_index
Used by: HeapAllocESTACK, HeapFree, cmd_try, HomeExecute, OSLinkCmd, TE_checkSlack, push_simplify_statements, time_loop


should_and_did_push_approx_arg2

should_and_did_push_approx_arg2 Function (ROM Call 0x311)
AMS 1.01 or higher estack.h

short should_and_did_push_approx_arg2 (CESI arg1_ptr, CESI arg2_ptr);

Pushes a second floating point argument, if possible.

This function is combination of "push" and "check" operations. If the entry on the expressions stack pointed to by arg1_ptr is not a floating point number (i.e. if arg1_ptr does not point to FLOAT_TAG), this function does nothing and returns FALSE. Otherwise, it checks if it is likely that the entry on the expression stack pointed to by arg2_ptr can be approxed to a real number (using likely_approx_to_number). If it is, should_and_did_push_approx_arg2 pushes the approximated value to the expression stack and returns TRUE, otherwise it does nothing more and returns FALSE.

Uses: likely_approx_to_number, next_expression_index, push_expression, top_estack, push_approx, primary_tag_list
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum, add_to_top, get_ub, push_standardize, raise_to_top, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, times_top


signum_Float

signum_Float Function (ROM Call 0x312)
AMS 1.01 or higher estack.h

long signum_Float (CESI ptr);

Finds the signum of a floating point entry.

signum_Float finds the signum of the floating point entry pointed to by ptr (i.e. returns 1 if the entry is positive, -1 if it is negative, 0 if it is zero). If the entry is not a floating point number, the result is garbage.

Uses: estack_to_float, _bcd_math
Used by: push_ln, push_log10, compare_numbers, is_neg_lead_numr_coef_re_part, ROM Call 0x4DF, ROM Call 0x4E0, ROM Call 0x4E1, ROM Call 0x4E2


subtract_from_top

subtract_from_top Function (ROM Call 0x51B)
AMS 2.02 or higher estack.h

void subtract_from_top (CESI ptr);

Subtracts a value from the top of the EStack.

subtract_from_top subtracts the expression pointed to by ptr from the expression currently at the top of the EStack and stores the result to the top of the EStack, in place of the expression that was substracted from.

Uses: top_estack, push_negate, replace_top2_with_sum
Used by: is_symmetric, did_push_anti_deriv, push_1st_derivative, push_asin, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub, push_div_dif_1c, push_div_dif_1f, push_reciprocal

See also: add_to_top, negate_top, subtract1_from_top


subtract1_from_top

subtract1_from_top Function (ROM Call 0x51E)
AMS 2.02 or higher estack.h

void subtract1_from_top (void);

Subtracts 1 from the top of the EStack.

subtract1_from_top subtracts 1 (or 1.0) from the value on the top of the EStack. This routine basically calls add_to_top with "-1" as the pointed-to value.

Uses: add_to_top, FloatMinus1Index, IntegerMinus1Index
Used by: push_comb, push_extended_prod, push_rec_to_angle, push_summation

See also: subtract_from_top, add1_to_top


times_top

times_top Function (ROM Call 0x522)
AMS 2.02 or higher estack.h

void times_top (CESI ptr);

Multiplies the expression onto the EStack.

times_top multiplies the expression currently at the top of the EStack by the expression pointed to by ptr, and stores the result to the top of the estack, in place of the expression that was multiplied.

Uses: estack_to_float, is_variable, is0, primary_tag_list, push_product, check_estack_size, delete_between, delete_expression, estack_number_to_Float, next_expression_index, push_between, push_expr_quantum, push_expression, push_Float, push_quantum, should_and_did_push_approx_arg2, top_estack, ST_helpMsg, XR_stringPtr, _bcd_math, _du16u16, _ds32s32, _ms32s32, push_exact0
Used by: add_to_top, are_units_consistent, did_push_approx_inflection_point, did_push_lincf, get_ub, index_if_pushed_qquad_info, is_negative, is_nonnegative, is_nonpositive, is_positive, negate_top, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_deg_in_var_or_kernel, push_poly_qr, push_reciprocal, push_standardize, push_symbolic_qr_fact, push_trig, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_integer_remainder, push_lim, push_ln, push_log10, push_matnorm, push_max, push_min, push_mod, push_nint, push_nsolve, push_numerator, push_perm, push_phase, push_prodlist, push_r_cis, push_re, push_sign, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_list_plus, push_negate, push_not_equals, push_percent, push_product, push_ratio, push_sum, push_to_cylin, push_to_sphere, push_dense_poly_eval, push_spher_vector, push_to_dd, push_to_dms, push_polar_to_rect_x, push_polar_to_rect_y


TokenizeSymName

TokenizeSymName Function (ROM Call 0x80)
estack.h

ESI TokenizeSymName (const char *src, unsigned short Flags);

Tokenizes a C string into a symbol name.

TokenizeSymName converts a symbol name pointed to by src, which is an ordinary ANSI C string, into a tokenized form, and pushes the tokenized form on the expression stack. After pushing, the new value of top_estack points to the variable tag on the expression stack. TokenizeSymName returns the old value of top_estack (which you can use to restore top_estack), or NULL_INDEX if the symbol name was invalid.

The parameter Flags is a set of binary flags from TokenizeSymNameFlags with the following meaning:

TSF_FULLY_QUALIFIED | Add current default folder to the name if no folder specified in the name (do not use if tokenizing standalone folder names).
TSF_ALLOW_RESERVED | Allow reserved names to be tokenized (otherwise they cause throwing an error).
TSF_PASS_ERRORS | Throw errors instead of returning NULL_INDEX.

Note: This routine may cause heap compression.

Uses: next_expression_index, push_parse_text, top_estack, ER_catch, ER_success, ER_throwVar, strcat, strchr, strlen, OSDisableBreak, OSEnableBreak, FirstNonblank, IsMainFolderStr, SymSysVar
Used by: cmd_newplot, VarNew, VarOpen, VarSaveAs, handleRclKey, TokenizeName, VarStoreLink

See also: StrToTokN


ARb_int_count

ARb_int_count Variable (ROM Call 0x5C3)
AMS 2.04 or higher estack.h

ESQ ARb_int_count;

Represents the number of times arbitrary-integer variables were already used by some calculus.

Arbitrary-integer variables (of the form "@nx") are generated by TI-Basic function calls such as solve(sin(x)=0,x).

This variable is set to 0 every time the calculator is reset, or if cmd_clrhome is called. ARb_int_count wraps back to 0 after 255.

Used by: push_next_arb_int, cmd_clrhome, HomeExecute

See also: ARb_real_count, cmd_clrhome, cmd_newprob


ARb_real_count

ARb_real_count Variable (ROM Call 0x5C2)
AMS 2.04 or higher estack.h

ESQ ARb_real_count;

Represents the number of times arbitrary variables were already used by some calculus.

Arbitrary variables (of the form "@x") are generated by TI-Basic function calls such as zeros(0,x).

This variable is set to 0 every time the calculator is reset, or if cmd_clrhome is called. ARb_real_count wraps back to 0 after 255.

Used by: push_next_arb_real, cmd_clrhome, HomeExecute

See also: ARb_int_count, cmd_clrhome, cmd_newprob


bottom_estack

bottom_estack Variable (ROM Call 0x432)
estack.h

CESI bottom_estack;

Points to the bottom of the expression stack.

bottom_estack is a global variable which points to the bottom of the expression stack, i.e. the first byte used. The quantum at bottom_estack is always ENDSTACK_TAG. Usually, you should not change this pointer, although it seems that it is possible to change it temporarily. If you do this, however, you need to make sure that it is changed back in any case, even if an error occurs.

This variable can be used together with top_estack to determine the amount of memory on the expression stack which is currently used.

The following example (called "Print EStack") prints the values of bottom_estack and top_estack:

// Print bottom_estack and top_estack

#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

// Main Function
void _main(void)
{
  ClrScr ();
  printf_xy (0, 40, "Bottom = 0x%lp", bottom_estack);
  printf_xy (0, 50, "Top = 0x%lp", top_estack);
  ngetchx ();
}

Used by: push_internal_simplify, reset_estack_size, HeapAllocESTACK, cmd_disphome, cmd_try, HomeExecute, HS_popEStack, OSLinkCmd, push_user_func, store_func_def, time_loop

See also: top_estack, estack_max_index


command_tag_list

command_tag_list Variable (ROM Call 0x5D8)
estack.h

const cmd_info *const command_tag_list;

Array of structures containing information on InstructionTags.

Used by: replace_top_with_post_simplified, index_below_display_expression_aux, next_expression_index, Parse2DExpr, Parse2DMultiExpr


estack_max_index

estack_max_index Variable (ROM Call 0x5BF)
estack.h

CESI estack_max_index;

Points to the end of the expression stack.

This is the address of the highest usable byte of the expression stack.

Used by: cmd_newdata, check_estack_size, index_below_display_expression_aux, Parse2DExpr, Parse2DMultiExpr, push_offset_array, push_quantum, push_quantum_pair, reset_estack_size

See also: top_estack, bottom_estack


Float0Index

Float0Index Variable (ROM Call 0x5D0)
AMS 2.04 or higher estack.h

ESI Float0Index;

Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value 0.0.

This variable is meant to be used with functions dealing with the EStack, rather than with timath.h functions.

Used by: divide_top, get_ub, InitDEMem, push0, replace_top2_with_ratio, cmd_clrerr, cmd_endtry, did_push_anti_deriv, push_1st_derivative, push_atanh, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_mod, push_nint, push_nsolve, push_sin2, push_solve, push_tan, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_ratio, im_index, index_numeric_term, reductum_index, ROM Call 0x3F9, ROM Call 0x4E9


Float1Index

Float1Index Variable (ROM Call 0x5D1)
AMS 2.04 or higher estack.h

ESI Float1Index;

Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value 1.0.

This variable is meant to be used with functions dealing with the EStack, rather than with timath.h functions.

Used by: add1_to_top, did_push_approx_inflection_point, get_ub, index_if_pushed_binomial_info, push_gcd_then_cofactors, push_make_proper, push_reciprocal, push_standardize, push1, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_factor, push_gcd_numbers, push_lim, push_max, push_min, push_nsolve, push_sign, push_sin2, push_solve, push_tan, push_zeros, push_arg_plus_1, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, numeric_factor_index, remaining_factors_index, ROM Call 0x3F9, ROM Call 0x4EA


FloatExp1Index

FloatExp1Index Variable (ROM Call 0x5D4)
AMS 2.04 or higher estack.h

ESI FloatExp1Index;

Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value e.

This variable is meant to be used with functions dealing with the EStack, rather than with timath.h functions.

Used by: push_extended_prod, push_summation, push_dot_exponentiate, ROM Call 0x3F9


FloatHalfIndex

FloatHalfIndex Variable (ROM Call 0x5E0)
AMS 2.04 or higher estack.h

ESI FloatHalfIndex;

Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value 0.5.

This variable is meant to be used with functions dealing with the EStack, rather than with timath.h functions.

Used by: push_factor, ROM Call 0x3F9


FloatMinus1Index

FloatMinus1Index Variable (ROM Call 0x5D2)
AMS 2.04 or higher estack.h

ESI FloatMinus1Index;

Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value -1.0.

This variable is meant to be used with functions dealing with the EStack, rather than with timath.h functions.

Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, negate_top, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, subtract1_from_top, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_tan, push_zeros, did_push_to_polar, push_arg_minus_1, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, ROM Call 0x3F9, push_minus1, ROM Call 0x4EF


FloatPiIndex

FloatPiIndex Variable (ROM Call 0x5D3)
AMS 2.04 or higher estack.h

ESI FloatPiIndex;

Pointer to the end tag (FLOAT_TAG) of a 14-digit tagged floating-point value pi.

This variable is meant to be used with functions dealing with the EStack, rather than with timath.h functions.

Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_rec_to_angle, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, ROM Call 0x3F9


FLOATTAB

FLOATTAB Variable (ROM Call 0x464)
AMS 2.00 or higher estack.h

const float * const FLOATTAB;

A pointer to an array of more or less commonly used untagged floats.

Elements of this array are:
FPI_TWOPI | 2*pi
FPI_ONEPI | pi
FPI_PIDIV2 | pi/2
FPI_PIDIV4 | pi/4
FPI_360 | 360.0
FPI_180 | 180.0
FPI_90 | 90.0
FPI_45 | 45.0
FPI_180DIVPI | 180/pi
FPI_PIDIV180 | pi/180
FPI_0 | 0.0
FPI_PT001 | 0.001
FPI_PT1 | 0.1
FPI_PIDIV24 | pi/24
FPI_PT5 | 0.5
FPI_PT9 | 0.9
FPI_1 | 1.0
FPI_MINUS1 | -1.0
FPI_SQRT2 | sqrt(2)
FPI_2 | 2.0
FPI_3 | 3.0
FPI_2PI12 | 2*pi (12 digits precision)
FPI_10 | 10.0
FPI_MINUS10 | -10.0
FPI_12 | 12.0
FPI_14 | 14.0
FPI_20 | 20.0
FPI_70 | 70.0
FPI_BIGGEST | 10^1000
FPI_NEGBIGGEST | -10^1000
FPI_16000 | 16000.0
FPI_MINUS16000 | -16000.0
FPI_32767 | 32767.0
FPI_MINUS32768 | -32768.0
FPI_65535 | 65535.0
FPI_1E14 | 1.0e14
FPI_INVALID | NAN
FPI_LOGE | log(e)
FPI_POS0 | positive zero
FPI_NEG0 | negative zero
FPI_POSINF | +infinity
FPI_NEGINF | -infinity
FPI_UNSINF | infinity

The FPI_... constants are defined in enum FLOATTABIndexes.

Of course, not all these values may be stored anywhere without problems. For instance, VarStore can throw errors if you write invalid values to system variables.

See also: FLOATTABIndexes


index_false

index_false Variable (ROM Call 0x5D6)
AMS 2.04 or higher estack.h

ESI index_false;

Pointer on a FALSE_TAG (0x2B) stored in the Flash.

This variable is meant to be used with functions dealing with the EStack.

Used by: get_ub, remaining_disjuncts_index, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


index_true

index_true Variable (ROM Call 0x5D5)
AMS 2.04 or higher estack.h

ESI index_true;

Pointer on a TRUE_TAG (0x2C) stored in the Flash.

This variable is meant to be used with functions dealing with the EStack.

Used by: get_ub, remaining_conjuncts_index, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


Integer0Index

Integer0Index Variable (ROM Call 0x5CD)
AMS 2.04 or higher estack.h

ESI Integer0Index;

Pointer to the end tag (POSINT_TAG) of an integer value 0.

This variable is meant to be used with functions dealing with the EStack.

Used by: add_to_top, are_units_consistent, did_push_approx_inflection_point, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, push_symbolic_qr_fact, push_zero_partial_column, raise_to_top, replace_top_with_post_simplified, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_sin, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, im_index, index_numeric_term, reductum_index, SetOK


Integer1Index

Integer1Index Variable (ROM Call 0x5CE)
AMS 2.04 or higher estack.h

ESI Integer1Index;

Pointer to the end tag (POSINT_TAG) of an integer value 1.

This variable is meant to be used with functions dealing with the EStack.

Used by: add_to_top, add1_to_top, are_units_consistent, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, push_symbolic_qr_fact, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, cmd_endfor, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_cos, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_instring, push_lim, push_ln, push_max, push_min, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_rec_to_angle, push_red_row_ech, push_row_echelon, push_sequence, push_sign, push_simult, push_sin2, push_solve, push_summation, push_tan, push_zeros, did_push_to_polar, push_arg_plus_1, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, compare_expressions, factor_exponent_index, numeric_factor_index, remaining_factors_index, SetOK, ROM Call 0x606


Integer2Index

Integer2Index Variable (ROM Call 0x5E1)
AMS 2.04 or higher estack.h

ESI Integer2Index;

Pointer to the end tag (POSINT_TAG) of an integer value 2.

This variable is meant to be used with functions dealing with the EStack.

Used by: add_to_top, are_units_consistent, did_push_approx_inflection_point, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_is_prime, push_lim, push_max, push_median, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_square, push_sum, push_to_cylin, push_to_sphere


IntegerMinus1Index

IntegerMinus1Index Variable (ROM Call 0x5CF)
AMS 2.04 or higher estack.h

ESI IntegerMinus1Index;

Pointer to the end tag (NEGINT_TAG) of an integer value -1.

This variable is meant to be used with functions dealing with the EStack.

Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, negate_top, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, subtract1_from_top, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_is_prime, push_lim, push_ln, push_log10, push_max, push_min, push_nsolve, push_nth_derivative, push_numerator, push_perm, push_phase, push_re, push_rotate, push_shift, push_sign, push_sin2, push_sinh, push_solve, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_arg_minus_1, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, ROM Call 0x606


secondary_tag_list

secondary_tag_list Variable (ROM Call 0x5EE)
estack.h

const tag_info *const secondary_tag_list;

Array of structures containing information on ExtTags.

Used by: gen_version, push_substitute_no_simplify, ROM Call 0x468


sysvar_tag_list

sysvar_tag_list Variable (ROM Call 0x46B)
estack.h

const sysvar_info *const sysvar_tag_list;

Array of structures containing information on SysvarTags.

Used by: cmd_cubicreg, cmd_delvar, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_showstat, cmd_twovar, VarRecall, VarStore


CESI_Callback_t

CESI_Callback_t Type (Pointer)
estack.h

typedef CALLBACK unsigned short (*CESI_Callback_t) (CESI);

Represents a pointer to a CESI callback function.

CESI_Callback_t is a pointer to a function taking a CESI (expression stack index with constant data) as a parameter and returning an integer. It is used in all_tail and any_tail.


cmd_info

cmd_info Type (Structure)
estack.h

typedef struct {
unsigned char tag_version;
unsigned char min_max_args; /* 4 MSB for minimal number of arguments, 4 LSB for maximal number of arguments */
unsigned char proc_args;
void (* CALLBACK arg_simp) (ESI);
void (* CALLBACK cmd_proc)(); /* routine that handles the tag */
unsigned long tag_str; /* Pointer to string data on AMS 1.xx, string ID suitable for XR_stringPtr on later AMS versions */
} cmd_info;

Structure containing information about AMS EStack command tags (InstructionTags).


ESI_Callback_Int_t

ESI_Callback_Int_t Type (Pointer)
estack.h

typedef CALLBACK unsigned short (*ESI_Callback_Int_t) (ESI, unsigned short);

Represents a pointer to an ESI callback function with integer extensions.

ESI_Callback_Int_t is a pointer to a function taking an ESI (expression stack index) and an integer as a parameter and returning an integer. It is used in map_tail_Int.


ESI_Callback_t

ESI_Callback_t Type (Pointer)
estack.h, unknown.h

typedef CALLBACK void (*ESI_Callback_t) (ESI);

Represents a pointer to an ESI callback function.

ESI_Callback_t is a pointer to a function taking an ESI (expression stack index) as a parameter and returning nothing. It is used in map_tail and map_unary_over_comparison.


EStackDisplacement

EStackDisplacement Type (Scalar)
estack.h

typedef unsigned short EStackDisplacement;

Type used for representing difference of two ESI pointers.


ExtTags

ExtTags Type (Enumeration)
estack.h

enum ExtTags {...};

An enumeration to describe extra types of entries on the expression stack.

If the tag of an entry on the expression stack is EXT_TAG (0xE3), then the byte below it is the extra TI-Basic function tag. ExtTags is enumerated type for describing such extended entries (see top_estack for more info about how entries on the expression stack are organized). This enum is quite big, and here is a complete list of extended function tags defined in it (all values are in hex), with their meaning (used notation is RPN):

01 | INDIR_TAG | string_expr # (indirection)
02 | GETKEY_TAG | [] getKey
03 | GETFOLD_TAG | [] getFold
04 | SWITCH_TAG | [int] switch
05 | UNITCONV_TAG | unit1 unit2 > (unit conversion, unit1 |> unit2)
06 | ORD_TAG | string ord
07 | EXPR_TAG | string expr
08 | CHAR_TAG | int char
09 | STRING_TAG | expr string
0A | GETTYPE_TAG | var getType
0B | GETMODE_TAG | string getMode
0C | SETFOLD_TAG | var setFold
0D | PTTEST_TAG | y x ptTest
0E | PXLTEST_TAG | column row pxlTest
0F | SETGRAPH_TAG | string string setGraph
10 | SETTABLE_TAG | string string setTable
11 | SETMODE_TAG | string string setMode / list setMode
12 | FORMAT_TAG | [string] expr format
13 | INSTRING_TAG | [start] substring search-string inString
14 | APPEND_TAG | string1 string2 & (append)
15 | DD_TAG | dmsnumber >DD
16 | EXPR2DMS_TAG | expr >DMS
17 | VEC2RECT_TAG | vec >Rect
18 | VEC2POLAR_TAG | vec >Polar
19 | VEC2CYLIND_TAG | vec >Cylind
1A | VEC2SPHERE_TAG | vec >Sphere
1B | PARENTH_START_TAG | ( (used only internally for the parser, not in expressions)
1C | PARENTH_END_TAG | ) (used only internally for the parser, not in expressions)
1D | MAT_START_TAG | [ (used only internally for the parser, not in expressions)
1E | MAT_END_TAG | ] (used only internally for the parser, not in expressions)
1F | LIST_START_TAG | { (used only internally for the parser, not in expressions)
20 | LIST_END_TAG | } (used only internally for the parser, not in expressions)
21 | COMMA_TAG | , (used only internally for the parser, not in expressions)
22 | SEMICOLON_TAG | ; (used only internally for the parser, not in expressions)
23 | COMPLEX_ANGLE_TAG | /_ (used only internally for the parser, not in expressions)
24 | SINGLE_QUOTE_TAG | ' (used only internally for the parser, not in expressions)
25 | QUOTE_TAG | " (used only internally for the parser, not in expressions)
26 | POLCPLX_TAG | magnitude angle /_ (polar complex number)
27 | TMPCNV_TAG | expr2 expr1 tmpCnv
28 | DELTA_TMPCNV_TAG | expr2 expr1 DtmpCnv
29 | GETUNITS_TAG | [] getUnits
2A | SETUNITS_TAG | list setUnits
2B | BIN_TAG | int 0b (i.e. 0b int)
2C | HEX_TAG | expr 0h (i.e. 0h expr)
2D | INT2BIN_TAG | int >Bin
2E | INT2DEC_TAG | int >Dec
2F | INT2HEX_TAG | int >Hex
30 | DET_TOL_TAG | tol mat det
31 | REF_TOL_TAG | tol mat ref
32 | RREF_TOL_TAG | tol mat rref
33 | SIMULT_TOL_TAG | tol vec mat simult
34 | GETCONFG_TAG | [] getConfg
35 | V_AUGMENT_TAG | mat2 ; mat1 augment
36 | MEAN_TWOARG_TAG | list list mean (AMS 2.00 or higher)
37 | PRODUCT_TWOARG_TAG | [end] start list product (AMS 2.00 or higher)
38 | STDDEV_TWOARG_TAG | list list stdDev (AMS 2.00 or higher)
39 | SUM_TWOARG_TAG | [end] start list sum (AMS 2.00 or higher)
3A | VARIANCE_TWOARG_TAG | list list variance (AMS 2.00 or higher)
3B | DELTA_LIST_TAG | list Dlist (AMS 2.00 or higher)
46 | ISCLKON_TAG | [] isClkOn (AMS 2.07 or higher)
47 | GETDATE_TAG | [] getDate (AMS 2.07 or higher)
48 | GETTIME_TAG | [] getTime (AMS 2.07 or higher)
49 | GETTMZN_TAG | [] getTmZn (AMS 2.07 or higher)
4A | SETDATE_TAG | [] d mo y setDate (AMS 2.07 or higher)
4B | SETTIME_TAG | [] s min h setTime (AMS 2.07 or higher)
4C | SETTMZN_TAG | int setTmZn (AMS 2.07 or higher)
4D | DAYOFWK_TAG | [] d mo y dayOfWk (AMS 2.07 or higher)
4E | STARTTMR_TAG | [] startTmr (AMS 2.07 or higher)
4F | CHECKTMR_TAG | seconds checkTmr (AMS 2.07 or higher)
50 | TIMECNV_TAG | seconds timeCnv (AMS 2.07 or higher)
51 | GETDTFMT_TAG | [] getDtFmt (AMS 2.07 or higher)
52 | GETTMFMT_TAG | [] getTmFmt (AMS 2.07 or higher)
53 | GETDTSTR_TAG | [int] getDtStr (AMS 2.07 or higher)
54 | GETTMSTR_TAG | [int] getTmStr (AMS 2.07 or higher)
55 | SETDTFMT_TAG | [int] setDtFmt (AMS 2.07 or higher)
56 | SETTMFMT_TAG | [int] setTmFmt (AMS 2.07 or higher)
57 | ROOT_TAG | nthOrder expr root (AMS 3.10 or higher)
58 | EXPRIO_TAG | string exprIO (AMS 3.10 or higher)
59 | IMPDIF_TAG | [order] dependentVar independentVar equation impDif (AMS 3.10 or higher)
5A | STDEVPOP_TAG | [arg2] arg1 stDevPop (AMS 3.10 or higher)
5B | ISVAR_TAG | var isVar (AMS 3.10 or higher)
5C | ISLOCKED_TAG | var isLocked (AMS 3.10 or higher)
5D | ISARCHIV_TAG | var isArchiv (AMS 3.10 or higher)
5E | GRAD_TAG | expr G (AMS 3.10 or higher)
5F | TO_GRAD_TAG | expr >Grad (AMS 3.10 or higher)
60 | TO_RAD_TAG | expr >Rad (AMS 3.10 or higher)
61 | TO_LN_TAG | expr >ln (AMS 3.10 or higher)
62 | TO_LOGBASE_TAG | expr expr >logbase (AMS 3.10 or higher)

Note: An empty list [] of optional arguments means the function does not take any optional arguments, but an END_TAG is needed nonetheless.

Note: For compatibility with TI's compiler, their tag names are also supported.


FLOATTABIndexes

FLOATTABIndexes Type (Enumeration)
estack.h

enum FLOATTABIndexes {
FPI_TWOPI=0, FPI_ONEPI, FPI_PIDIV2, FPI_PIDIV4, FPI_360, FPI_180, FPI_90, FPI_45, FPI_180DIVPI, FPI_PIDIV180, FPI_0, FPI_PT001, FPI_PT1, FPI_PIDIV24, FPI_PT5, FPI_PT9, FPI_1, FPI_MINUS1, FPI_SQRRT2, FPI_2, FPI_3, FPI_2PI12, FPI_10, FPI_MINUS10, FPI_12, FPI_14, FPI_20, FPI_70, FPI_BIGGEST, FPI_NEGBIGGEST, FPI_16000, FPI_MINUS16000, FPI_32767, FPI_MINUS32768, FPI_65535, FPI_1E14, FPI_INVALID, FPI_LOGE, FPI_POS0, FPI_NEG0, FPI_POSINF, FPI_NEGINF, FPI_UNSINF
};

An enumeration for describing the valid indexes for FLOATTAB.

See also: FLOATTAB


InstructionTags

InstructionTags Type (Enumeration)
estack.h

enum InstructionTags {...};

An enumeration to describe types of instructions on the expression stack.

If the tag of an entry on the expression stack is EXT_INSTR_TAG (0xE4), then the byte below it is the tag of a TI-Basic command token. Although TI-Basic tokens are not interesting for programming, they are defined in enumerated type InstructionTags, due to completeness. This enum is quite big, and here is a complete list of TI-Basic instruction token tags defined in it (all values are in hex), with their meaning (used notation is RPN):

01 | CLRDRAW_ITAG | ClrDraw
02 | CLRGRAPH_ITAG | ClrGraph
03 | CLRHOME_ITAG | ClrHome
04 | CLRIO_ITAG | ClrIO
05 | CLRTABLE_ITAG | ClrTable
06 | CUSTOM_ITAG | Custom
07 | CYCLE_ITAG | displacement Cycle (displacement towards the instruction ending the loop)
08 | DIALOG_ITAG | Dialog
09 | DISPG_ITAG | DispG
0A | DISPTBL_ITAG | DispTbl
0B | ELSE_ITAG | Else (in If...EndIf statement)
0C | ENDCUSTM_ITAG | EndCustm
0D | ENDDLOG_ITAG | EndDlog
0E | ENDFOR_ITAG | displacement EndFor
0F | ENDFUNC_ITAG | EndFunc
10 | ENDIF_ITAG | EndIf
11 | ENDLOOP_ITAG | displacement EndLoop
12 | ENDPRGM_ITAG | EndPrgm
13 | ENDTBAR_ITAG | EndTBar
14 | ENDTRY_ITAG | EndTry
15 | ENDWHILE_ITAG | displacement EndWhile
16 | EXIT_ITAG | displacement Exit (displacement towards the end of the loop, i.e. the instruction following the loop ending instruction)
17 | FUNC_ITAG | Func
18 | LOOP_ITAG | Loop
19 | PRGM_ITAG | Prgm
1A | SHOWSTAT_ITAG | ShowStat
1B | STOP_ITAG | Stop
1C | THEN_ITAG | Then
1D | TOOLBAR_ITAG | Toolbar
1E | TRACE_ITAG | Trace
1F | TRY_ITAG | Try
20 | ZOOMBOX_ITAG | ZoomBox
21 | ZOOMDATA_ITAG | ZoomData
22 | ZOOMDEC_ITAG | ZoomDec
23 | ZOOMFIT_ITAG | ZoomFit
24 | ZOOMIN_ITAG | ZoomIn
25 | ZOOMINT_ITAG | ZoomInt
26 | ZOOMOUT_ITAG | ZoomOut
27 | ZOOMPREV_ITAG | ZoomPrev
28 | ZOOMRCL_ITAG | ZoomRcl
29 | ZOOMSQR_ITAG | ZoomSqr
2A | ZOOMSTD_ITAG | ZoomStd
2B | ZOOMSTO_ITAG | ZoomSto
2C | ZOOMTRIG_ITAG | ZoomTrig
2D | DRAWFUNC_ITAG | expr DrawFunc
2E | DRAWINV_ITAG | expr DrawInv
2F | GOTO_ITAG | expr Goto (Expr = LABEL)
30 | LBL_ITAG | expr Lbl (Expr = LABEL)
31 | GET_ITAG | var Get
32 | SEND_ITAG | list Send
33 | GETCALC_ITAG | var GetCalc
34 | SENDCALC_ITAG | var SendCalc
35 | NEWFOLD_ITAG | foldername NewFold
36 | PRINTOBJ_ITAG | var PrintObj
37 | RCLGDB_ITAG | var RclGDB
38 | STOGDB_ITAG | var StoGDB
39 | ELSEIF_ITAG | condition ElseIf
3A | IF_ITAG | condition If (simple variant)
3B | IFTHEN_ITAG | condition If...Then (If condition Then)
3C | RANDSEED_ITAG | expr RandSeed
3D | WHILE_ITAG | condition While
3E | LINETAN_ITAG | point expr LineTan
3F | COPYVAR_ITAG | var2 var1 CopyVar
40 | RENAME_ITAG | newname oldname Rename
41 | STYLE_ITAG | string expr Style
42 | FILL_ITAG | var expr Fill
43 | REQUEST_ITAG | var string Request
44 | POPUP_ITAG | var itemlist PopUp
45 | PTCHG_ITAG | y x PtChg
46 | PTOFF_ITAG | y x PtOff
47 | PTON_ITAG | y x PtOn
48 | PXLCHG_ITAG | column row PxlChg
49 | PXLOFF_ITAG | column row PxlOff
4A | PXLON_ITAG | column row PxlOn
4B | MOVEVAR_ITAG | newfolder oldfolder var MoveVar
4C | DROPDOWN_ITAG | var list title_string DropDown
4D | OUTPUT_ITAG | expr column row Output
4E | PTTEXT_ITAG | y x string PtText
4F | PXLTEXT_ITAG | column row string PxlText
50 | DRAWSLP_ITAG | slope y x DrawSlp
51 | PAUSE_ITAG | [expr] Pause
52 | RETURN_ITAG | [expr] Return
53 | INPUT_ITAG | [var [string]] Input
54 | PLOTSOFF_ITAG | [9] ... [2] [1] PlotsOff
55 | PLOTSON_ITAG | [9] ... [2] [1] PlotsOn
56 | TITLE_ITAG | [label] string Title
57 | ITEM_ITAG | [label] string Item
58 | INPUTSTR_ITAG | var [string] InputStr
59 | LINEHORZ_ITAG | [drawmode] y LineHorz
5A | LINEVERT_ITAG | [drawmode] x LineVert
5B | PXLHORZ_ITAG | [drawmode] row PxlHorz
5C | PXLVERT_ITAG | [drawmode] column PxlVert
5D | ANDPIC_ITAG | [pxlcol pxlrow] picvar AndPic
5E | RCLPIC_ITAG | [pxlcol pxlrow] picvar RclPic
5F | RPLCPIC_ITAG | [pxlcol pxlrow] picvar RplcPic
60 | XORPIC_ITAG | [pxlcol pxlrow] picvar XorPic
61 | DRAWPOL_ITAG | [q step] [q max] [q min] DrawPol
62 | TEXT_ITAG | [] string Text
63 | ONEVAR_ITAG | [L4] [L3] [L2] [L1] OneVar
64 | STOPIC_ITAG | [height width] [pxlcol pxlrow] var StoPic
65 | GRAPH_ITAG | [var2] [var1] [expr2] expr1 Graph
66 | TABLE_ITAG | [var] [expr2] expr1 Table
67 | NEWPIC_ITAG | [maxcol] [maxrow] picvar mat NewPic
68 | DRAWPARM_ITAG | [tstep] [tmax] [tmin] expr2 expr1 DrawParm
69 | CYCLEPIC_ITAG | [direction] [cycle] [wait] N picname_string CyclePic
6A | CUBICREG_ITAG | [[L5 L4] [L3]] L2 L1 CubicReg
6B | EXPREG_ITAG | [[L5 L4] [L3]] L2 L1 ExpReg
6C | LINREG_ITAG | [[L5 L4] [L3]] L2 L1 LinReg
6D | LNREG_ITAG | [[L5 L4] [L3]] L2 L1 LnReg
6E | MEDMED_ITAG | [[L5 L4] [L3]] L2 L1 MedMed
6F | POWERREG_ITAG | [[L5 L4] [L3]] L2 L1 PowerReg
70 | QUADREG_ITAG | [[L5 L4] [L3]] L2 L1 QuadReg
71 | QUARTREG_ITAG | [[L5 L4] [L3]] L2 L1 QuartReg
72 | TWOVAR_ITAG | [[L5 L4] [L3]] L2 L1 TwoVar
73 | SHADE_ITAG | [patres] [pat] [xhigh] [xlow] expr2 expr1 Shade
74 | FOR_ITAG | [step] high low var For
75 | CIRCLE_ITAG | [drawmode] r y x Circle
76 | PXLCRCL_ITAG | [drawmode] r col row PxlCrcl
77 | NEWPLOT_ITAG | [bucket] [mark] [inc] [cat] [frq] [ylist] xlist type N NewPlot
78 | LINE_ITAG | [drawmode] yend xend ystart xstart Line
79 | PXLLINE_ITAG | [drawmode] colend rowend colstart rowstart PxlLine
7A | DISP_ITAG | [[...] expr1] Disp
7B | FNOFF_ITAG | [99] ... [2] [1] FnOff
7C | FNON_ITAG | [99] ... [2] [1] FnOn
7D | LOCAL_ITAG | [...] var1 Local
7E | DELFOLD_ITAG | [...] var1 DelFold
7F | DELVAR_ITAG | [...] var1 DelVar
80 | LOCK_ITAG | [...] var1 Lock
81 | PROMPT_ITAG | [...] var1 Prompt
82 | SORTA_ITAG | [...] list1 SortA
83 | SORTD_ITAG | [...] list1 SortD
84 | UNLOCK_ITAG | [...] var1 UnLock
85 | NEWDATA_ITAG | [...] list1 datavar NewData
86 | DEFINE_ITAG | expr var|userfunc Define
87 | ELSE_TRY_ITAG | Else (in Try...EndTry statement)
88 | CLRERR_ITAG | ClrErr
89 | PASSERR_ITAG | PassErr
8A | DISPHOME_ITAG | DispHome
8B | EXEC_ITAG | [[...] expr] string Exec
8C | ARCHIVE_ITAG | [...] var1 Archive
8D | UNARCHIV_ITAG | [...] var1 Unarchiv
8E | LU_ITAG | [tol] pvar uvar lvar mat LU
8F | QR_ITAG | [tol] rvar qvar mat QR
90 | BLDDATA_ITAG | var|sysdata BldData
91 | DRWCTOUR_ITAG | expr DrwCtour
92 | NEWPROB_ITAG | NewProb
93 | SINREG_ITAG | [[L4 L3] [period] [iter]] L2 L1 SinReg
94 | LOGISTIC_ITAG | [[L4 L3] [period] [iter]] L2 L1 Logistic
95 | CUSTMON_ITAG | CustmOn
96 | CUSTMOFF_ITAG | CustmOff
97 | SENDCHAT_ITAG | var SendChat
99 | REQUEST_THREEARG_ITAG | [] alphalock var string Request (AMS 2.07 or higher)
9A | CLOCKON_ITAG | ClockOn (AMS 2.07 or higher)
9B | CLOCKOFF_ITAG | ClockOff (AMS 2.07 or higher)
9C | SENDCALC_TWOARG_ITAG | port var SendCalc (AMS 3.00 or higher)
9D | GETCALC_TWOARG_ITAG | port var GetCalc (AMS 3.00 or higher)
9E | DELTYPE_ITAG | varTypeStr DelType (AMS 3.10 or higher)
9F | DATA2MAT_ITAG | [col2] [row2] [col1] [row1] matVar dataVar Data>Mat (AMS 3.10 or higher)
A0 | MAT2DATA_ITAG | [col2] [row2] [col1] [row1] dataVar matVar Mat>Data (AMS 3.10 or higher)

Note: Displacements for jumps are 2 byte quantities in little endian format. Displacements in front of loop ending instructions are towards the beginning of the loop.

Note: An empty list [] of optional arguments means the instruction does not take any optional arguments, but an END_TAG is needed nonetheless.

Note: For compatibility with TI's compiler, their tag names are also supported.


MULTI_EXPR

MULTI_EXPR Type (Structure)
estack.h, homescr.h, vat.h

typedef struct {
unsigned short Size;
ESQ Expr[];
} MULTI_EXPR;

Describes a multi-expression, which is processed as a separate expression stack.

MULTI_EXPR is a structure describing a multi-expression. It can be applied to the contents of every VAT symbol, because all symbols contain size bytes at the beginning. It can also be used to describe a multi-expression passed to Parse2DMultiExpr, or used by the FIFO elements in homescr.h.

The Size field contains the size of the data in Expr, in bytes (but note that ESQ is one byte large). For real multi-expressions, Expr should start with ENDSTACK_TAG, followed by the actual expressions. These expressions are processed from the end to the beginning, as usual (using the Size field to find the end). So the last quantum needs to be a tag from the Tags enum.

Multiple expressions are separated with NEXTEXPR_TAG, or with NEWLINE_TAG (only in TI-Basic programs and functions).

If you have a handle to a MULTI_EXPR structure, you can use the HToESI function to get a pointer to the last quantum (i.e. the tag).

See also: top_estack, HToESI, Parse2DMultiExpr, homescr.h


sysvar_info

sysvar_info Type (Structure)
estack.h

typedef struct {
unsigned char tag_type_1;
unsigned char tag_type_2;
unsigned char tag_type_3;
unsigned char tag_type_4;
unsigned long tag_str; /* Pointer to string data on AMS 1.xx, string ID suitable for XR_stringPtr on later AMS versions */
} sysvar_info;

Structure containing information about AMS EStack tags (SysvarTags).


SysvarTags

SysvarTags Type (Enumeration)
estack.h

enum SysvarTags {...};

An enumeration to describe types of system variable entries on the expression stack.

If the tag of an entry on the expression stack is EXT_SYSTEM_TAG (0x1C), then the byte below it is the tag of a TI-Basic system variable. SysvarTags is enumerated type for describing such extended entries (see top_estack for more info about how entries on the expression stack are organized). This enum is quite big, and here is a complete list of system variables tags defined in it (all values are in hex), with their meaning:

01 | X_BAR_TAG | x mean
02 | Y_BAR_TAG | y mean
03 | SIGMA_X_TAG | Sx
04 | SIGMA_X2_TAG | Sx2
05 | SIGMA_Y_TAG | Sy
06 | SIGMA_Y2_TAG | Sy2
07 | SIGMA_XY_TAG | Sxy
08 | SX_TAG | Sx
09 | SY_TAG | Sy
0A | SMLSIGMA_X_TAG | sx
0B | SMLSIGMA_Y_TAG | sy
0C | NSTAT_TAG | nStat
0D | MINX_TAG | minX
0E | MINY_TAG | minY
0F | Q1_TAG | q1
10 | MEDSTAT_TAG | medStat
11 | Q3_TAG | q3
12 | MAXX_TAG | maxX
13 | MAXY_TAG | maxY
14 | CORR_TAG | corr
15 | R2_TAG | R2
16 | MEDX1_TAG | medx1
17 | MEDX2_TAG | medx2
18 | MEDX3_TAG | medx3
19 | MEDY1_TAG | medy1
1A | MEDY2_TAG | medy2
1B | MEDY3_TAG | medy3
1C | XC_TAG | xc
1D | YC_TAG | yc
1E | ZC_TAG | zc
1F | TC_TAG | tc
20 | RC_TAG | rc
21 | THETA_C_TAG | qc
22 | NC_TAG | nc
23 | XFACT_TAG | xfact
24 | YFACT_TAG | yfact
25 | ZFACT_TAG | zfact
26 | XMIN_TAG | xmin
27 | XMAX_TAG | xmax
28 | XSCL_TAG | xscl
29 | YMIN_TAG | ymin
2A | YMAX_TAG | ymax
2B | YSCL_TAG | yscl
2C | DELTA_X_TAG | Dx
2D | DELTA_Y_TAG | Dy
2E | XRES_TAG | xres
2F | XGRID_TAG | xgrid
30 | YGRID_TAG | ygrid
31 | ZMIN_TAG | zmin
32 | ZMAX_TAG | zmax
33 | ZSCL_TAG | zscl
34 | EYE_THETA_TAG | eyeq
35 | EYE_PHI_TAG | eyeF
36 | THETA_MIN_TAG | qmin
37 | THETA_MAX_TAG | qmax
38 | THETA_STEP_TAG | qstep
39 | TMIN_TAG | tmin
3A | TMAX_TAG | tmax
3B | TSTEP_TAG | tstep
3C | NMIN_TAG | nmin
3D | NMAX_TAG | nmax
3E | PLOTSTRT_TAG | plotStrt
3F | PLOTSTEP_TAG | plotStep
40 | ZXMIN_TAG | zxmin
41 | ZXMAX_TAG | zxmax
42 | ZXSCL_TAG | zxscl
43 | ZYMIN_TAG | zymin
44 | ZYMAX_TAG | zymax
45 | ZYSCL_TAG | zyscl
46 | ZXRES_TAG | zxres
47 | Z_THETA_MIN_TAG | zqmin
48 | Z_THETA_MAX_TAG | zqmax
49 | Z_THETA_STEP_TAG | zqstep
4A | ZTMIN_TAG | ztmin
4B | ZTMAX_TAG | ztmax
4C | ZTSTEP_TAG | ztstep
4D | ZXGRID_TAG | zxgrid
4E | ZYGRID_TAG | zygrid
4F | ZZMIN_TAG | zzmin
50 | ZZMAX_TAG | zzmax
51 | ZZSCL_TAG | zzscl
52 | ZEYE_THETA_TAG | zeyeq
53 | ZEYE_PHI_TAG | zeyeF
54 | ZNMIN_TAG | znmin
55 | ZNMAX_TAG | znmax
56 | ZPLTSTEP_TAG | zpltstep
57 | ZPLTSTRT_TAG | zpltstrt
58 | SEED1_TAG | seed1
59 | SEED2_TAG | seed2
5A | OK_TAG | ok
5B | ERRORNUM_TAG | errornum
5C | SYSMATH_TAG | sysMath
5D | SYSDATA_TAG | sysData
5E | REGEQ_TAG | regEq (Name = null)
5F | REGCOEF_TAG | regCoef
60 | TBLINPUT_TAG | tblInput
61 | TBLSTART_TAG | tblStart
62 | DELTA_TBL_TAG | Dtbl
63 | FLDPIC_TAG | fldpic (this tag is suspicious)
64 | EYE_PSI_TAG | eyeY
65 | TPLOT_TAG | tplot
66 | DIFTOL_TAG | diftol
67 | ZEYE_PSI_TAG | zeyeY
68 | T0_TAG | t0
69 | DTIME_TAG | dtime
6A | NCURVES_TAG | ncurves
6B | FLDRES_TAG | fldres
6C | ESTEP_TAG | Estep
6D | ZT0DE_TAG | zt0de
6E | ZTMAXDE_TAG | ztmaxde (Name = ztmax)
6F | ZTSTEPDE_TAG | ztstepde (Name = ztstep)
70 | ZTPLOTDE_TAG | ztplotde
71 | NCONTOUR_TAG | ncontour


TokenizeSymNameFlags

TokenizeSymNameFlags Type (Enumeration)
estack.h

enum TokenizeSymNameFlags {TSF_FULLY_QUALIFIED = 0x01, TSF_ALLOW_RESERVED = 0x02, TSF_PASS_ERRORS = 0x04};

Contains flags specifying how a symbol name is tokenized.

TokenizeSymNameFlags is an enumeration containing flags used by TokenizeSymName.


events.h

events.h Header File
Header File Index

Routines for event-driven programming and for mode settings

Functions
ABT_dialog
Starts "ABOUT" dialog "applet".
CAT_dialog
Starts "CATALOG" dialog "applet".
EV_captureEvents
Sets the event message handler (i.e. installs an event driven application).
EV_centralDispatcher
Enters the main controlling loop of the TIOS.
EV_clearPasteString
Clears the event paste buffer.
EV_defaultHandler
Processes an event message using the default handler.
EV_eventLoop
Enters the loop in which main event messages are collected and dispatched.
EV_getAppID
Finds a task ID number for an application.
EV_getc
Waits for the keypress, then fills an event structure with the keypress.
EV_getSplitRect
Gets the screen rectangle for a given side.
EV_notifySwitchGraph
Notify appropriate applications of graph switching.
EV_paintOneWindow
Repaints the topmost window.
EV_paintWindows
Repaints all windows.
EV_quit
Switches from the current application to the Home application.
EV_registerMenu
Attaches a menu to an application.
EV_restorePainting
Restores previous state of window painting.
EV_sendEvent
Sends an event message from the current side.
EV_sendEventSide
Sends an event message from the given side.
EV_sendString
Sends XR string to the running application.
EV_setCmdCheck
Checks/unchecks a menu item in the current application.
EV_setCmdState
Changes the status (active/inactive) of a menu command in the current application.
EV_setFKeyState
Changes the status (active/inactive) of a toolbox in the menu associated with current application.
EV_startApp
Starts an application from any state.
EV_startSide
Starts the given side.
EV_startTask
Starts a particular task in the running application.
EV_suspendPainting
Suspends window painting.
EV_switch
Performs switching of sides.
handleRclKey
Displays the standard "Recall Variable" dialog.
handleVarLinkKey
Displays the standard "Var-Link" dialog.
MO_currentOptions
Fills in options structure from current mode settings.
MO_defaults
Sets default mode settings.
MO_digestOptions
Updates system mode settings from options structure.
MO_isMultigraphTask
Checks whether a task is multigraph task.
MO_modeDialog
Executes "MODE" dialog.
MO_notifyModeChange
Sends mode change notify message to all applications.
MO_sendQuit
Quits an application on given side.
TIOS_EV_getAppID
Finds a task ID number for an application, AMS 2.xx only.
Global Variables
EV_flags
State information for the event manager.
EV_hook
A global variable pointing to the "hook" event handler.
Constants
MO_option
Contains a pointer to the global mode settings array.
ModeSettings
Contains a pointer to the global MO_OPTIONS structure.
NULL
A null-pointer value.
Predefined Types
Bool
An enumeration to describe true or false values.
EV_FLAGS
An enumeration for describing possible bits for EV_flags.
EVENT_HANDLER
A pointer to an event handler.
EVENT
A structure describing an event message.
EventIDs
An enumeration describing IDs of system messages.
HANDLE
Represents a handle associated with an allocated memory block.
MO_OPTIONS
A structure containing all system mode settings.
MoNotifyFlags
Enumerates notify messages for the MO_notifyModeChange function.
PaintFlags
An enumeration describing whether painting is suspended or enabled.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
ST_ACTIVITIES
Contains status bar activity flags.
StandardTaskIDs
An enumeration describing task ID constants.
StartTypes
A pseudo-enumeration describing start types for EV_startTask.
SystemDataTypes
Describes valid variable types in the "Var-Link" dialog, and for the GetDataType and SmapTypeStrings functions.
WIN_RECT
A structure for defining a rectangular area.
WINDOW
The main window-describing structure.
WinFlags
An enumeration for describing flags which control the window manager.

Note: Event-related functions are intended mainly for flash applications, although some of them may be useful even in user programs. Anyway, they are intended for serious programmers, not for beginners. Don't try to make an event-driven application if you don't understand this file really well!

If your program uses functions from this header file, you may have to define SET_FILE_IN_USE_BIT.


ABT_dialog

ABT_dialog Function (ROM Call 0x10D)
events.h

void ABT_dialog (void);

Starts "ABOUT" dialog "applet".

The "ABOUT" dialog is an event driven "applet", which works exactly like "CATALOG" dialog applet. See CAT_dialog for more info about event driven dialogs.

Note: If your program uses this function, you have to define SET_FILE_IN_USE_BIT.

Uses: EV_captureEvents, EV_restorePainting, EV_suspendPainting, cgetcertrevno, RestoreScrState, SaveScrState, sprintf, AB_getGateArrayVersion, AB_prodid, AB_prodname, AB_serno, LOC_localVersionDate, ReleaseVersion, XR_stringPtr, DrawWinBorder, WinActivate, WinAttr, WinClr, WinFont, WinOpen, WinStr, WinStrXY
Used by: EV_defaultHandler, EV_quit


CAT_dialog

CAT_dialog Function (ROM Call 0x125)
events.h

void CAT_dialog (void);

Starts "CATALOG" dialog "applet".

The "CATALOG" dialog is an event driven "applet". CAT_dialog draws the dialog on the screen, installs its own event handler, then exits (without stopping the caller program). It does not enter into a loop (like normal dialogs do) which ends only on pressing ENTER or ESC. Its event handler restores the previously installed handler after the user presses ENTER or ESC, but if the pressed key was the ENTER key, the selected command from the catalog is send as a CM_STRING message after restoring the user handler (which need to be captured via user event handler). That's why it is not so easy to use CAT_dialog in user programs, but this is also not very hard. Here is an example, which opens the "CATALOG" dialog, and displays in the help screen a message which tells what the user selected from the catalog (called "Catalog"):

// Display the catalog and let the user select something

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 100           // Compile for AMS 1.00 or higher

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

const char *ptr;
HANDLE handle;

CALLBACK void Handler(EVENT *ev)
{
  if (ev->Type == CM_STRING)
    ptr = ev->extra.pasteText;
  else if (ev->Type == CM_HSTRING)
    handle = ev->extra.hPasteText;
  ER_throw (1);
}

void _main(void)
{
  EVENT ev;
  char buffer[100];
  ptr = NULL;
  handle = H_NULL;
  EV_captureEvents (Handler);
  CAT_dialog ();
  TRY
    EV_eventLoop ();
  ONERR
    EV_captureEvents (NULL);
  ENDTRY
  if (handle != H_NULL)
    ptr = HLock (handle);
  if (ptr != NULL)
  {
    sprintf (buffer, "You selected \"%s\".", ptr);
    ST_helpMsg (buffer);
  }
  else ST_helpMsg ("You pressed ESC.");
  if (handle != H_NULL)
    HeapFree (handle);
  ev.Type = CM_UNFOCUS;               // This is more due to some
  EV_sendEvent (AP_CURRENT, &ev);     // aesthetical reasons
}
Note that it is important that EV_captureEvents must be called before calling CAT_dialog. This example is a good test whether you understand the principles of event handling or not.

Note: If your program uses this function, you have to define SET_FILE_IN_USE_BIT.

Used by: EV_defaultHandler


EV_captureEvents

EV_captureEvents Function (ROM Call 0xC6)
events.h

EVENT_HANDLER EV_captureEvents (EVENT_HANDLER NewHandler);

Sets the event message handler (i.e. installs an event driven application).

EV_captureEvents sets a new event message handler to the routine pointed to by NewHandler, overriding any current handler. NewHandler is the pointer of type EVENT_HANDLER, which is the pointer to a void function (i.e. procedure) which accepts one parameter of EVENT type. If NewHandler is NULL, EV_captureEvents restores the standard event handler (which depends on the current application like "Home Screen", "Graph", etc.). EV_captureEvents returns the pointer to the previous installed event handler.

Any event handler is, in fact, an event driven application. All built-in flash applications like "Home screen", "Graph", "Text editor", "Geometry" etc. and all add-in flash applications are event driven applications. Also, "About" and "Catalog" dialogs and "Error message" dialogs are also event driven applications (maybe the word "applets" is better for them). The whole idea of event driving is as follows: instead of having an application which has an internal "main loop" in which all processing are performed, an event driven application accepts a message (or event), checks the type of the event (a keypress is, for example, one type of the event), process it, then exits immediately after processing the event. So, the user needs to make a loop in which necessary events are collected and dispatched (using EV_sendEvent) to the application. The main advantage of such an approach is in the fact that the main loop is under the control of the user, even if the application itself may be written by somebody else. So, the user can decide in the loop what events will be sent to an application etc. This would not be possible if the "main loop" is the part of the application itself. For example, if the user makes a loop in which events are dispatched to two or more applications, it is easy to estabilish a kind of multitasking. Note that each modern operating system (for example Windows or UNIX) is based on such event dispatching/handling mechanism!

To understand more about event driven applications, you need to read about all other functions in this header file (especially EV_eventLoop, EV_sendEvent and EV_defaultHandler may be very useful in user programs). Probably the most frequent usage of these functions in user programs will be to access the text editor application (see textedit.h header file), which is event driven. In this header file, there is also a good example about using some event functions.

Note: If you want to "hook" on the existing event handler instead to complete overriding the current handler, it is better to use EV_hook.

Used by: ABT_dialog, EV_defaultHandler, cmd_input, cmd_inputstr, cmd_prompt, Dialog, ERD_dialog, GD_Text, fgetchar, gets, getsn, EV_quit, GT_Trace


EV_centralDispatcher

EV_centralDispatcher Function (ROM Call 0x156)
events.h

void EV_centralDispatcher (void);

Enters the main controlling loop of the TIOS.

As the name suggests this is the main controlling loop of the entire TIOS. This functions initializes all installed applications by sending CM_INIT event to them, starts the "Home screen" application, then calls EV_eventLoop under an error handler, so if any error appeared during execution of the event loop, it will be catched by the error handler, which will first dispatch the error code to ERD_process then restart the event loop.

Note: As far as I know, there is no any need to call this function from your program. This will enter the endless loop, which cannot be broken even by throwing an error from the event handler (the method used to exit from EV_eventLoop), because the event loop is now executed under the internal error handler (maybe the only method to exit from such loop is using longjmp from the event handler, but I don't believe that such a barbaric method would leave the system in a stable state).

Uses: EV_eventLoop, EV_hook, EV_sendEvent, EV_startTask, ER_catch, ERD_process, reset_control_flags, ST_busy, EV_appA, EV_appB, EV_appSide, EV_currentApp, EV_runningApp, OO_firstACB, OO_NextACB, ROM Call 0x428


EV_clearPasteString

EV_clearPasteString Function (ROM Call 0xC7)
events.h

void EV_clearPasteString (void);

Clears the event paste buffer.

EV_clearPasteString clears event paste buffer, i.e. clears the static pointer to the paste buffer (see default action for CM_STRING message in EV_defaultHandler), and eventually frees the memory occupied for dynamically pasted string (sent via CM_HSTRING message).

Uses: HeapFreeIndir
Used by: ERD_dialog


EV_defaultHandler

EV_defaultHandler Function (ROM Call 0x157)
events.h

void EV_defaultHandler (EVENT *event);

Processes an event message using the default handler.

EV_defaultHandler performs some default actions with most common messages (event is the pointer to the message which need to be processed). This function is very useful in user event handlers, and it is often called to process any unhandled messages in handlers. Not all messages are supported in EV_defaultHandler. This is a list of supported message types (unsupported types are simply ignored) together with the description of the action performed by EV_defaultHandler:

CM_ACTIVATE | Registers and starts the menu for the running application (see EV_registerMenu).
CM_DEACTIVATE | Ends custom and normal menus.
CM_KEY_PRESS | Handles tokens, system and mode keys. This is maybe the most useful action performed by EV_defaultHandler. If the keypress is a simple key (i.e. a single character), nothing will happen. If the keypress is a token (like "sin", "ln" etc.), the appropriate string is sent (as a CM_PASTE_STRING message) to the application. The summary effects will be that the application will receive token as a sequence of single keypresses. So, tokens are all sent via EV_sendString and do not have to be processed as single keypresses (note that this will not cause problems if called from user event handlers, although it may cause recursion; see textedit.h header file for an useful example). If the keypress is system or mode key (see QSysKey and QModeKey), the corresponding action associated with the key (for example, opening a menu or a dialog) will be performed (see the example below this table). The chosen menu item is then sent as a CM_PASTE_STRING message to the current application (note however that VAR-LINK uses a CM_PASTE_HANDLE message instead), except for toolbar menus, where an appropriate menu ID is send as a message. Command keypresses STO, RCL, SWITCH, MODE, APPS, MEM, INS, CUT, PASTE etc. and OFF key (code 4363) are also handled via this handler, and all of them cause usual actions (keypresses like CUT, PASTE etc. only send an appropriate message to the application).
CM_PASTE_STRING | Pastes the string in the event paste buffer. More precise, it sets an internal static pointer to points to event->extra.pasteText and does not nothing more. The event loop (see EV_eventLoop) will then send the string as individual keypresses to the current application. This means that the paste buffer is exported from the code, so this allows pasting large amounts of text.
CM_PASTE_HANDLE | Frees the memory associated with handle event->extra.hPasteText.
CM_STO | Sends CM_KEY_PRESS event filled with key code 22 (right arrow) to the current application.
CM_RCL | Performs usual actions for the RCL key (open Recall dialog, etc.). After execution of the Recall dialog, the content of the variable is sent to the current application as a CM_PASTE_STRING message.

Useful examples for this functions may be found in textedit.h header file. Here is another simple example which ilustrates how you can open the "CHAR" menu. This may be useful if you want to make your user input routine which allows inserting extra characters:

EVENT ev;
...
ev.Type = CM_KEY_PRESS;
ev.extra.Key.Code = KEY_CHAR;
EV_defaultHandler (&ev);
After execution of the menu, the selected character will be sent as the event to the current application (it may be captured through an user event handler).

Uses: ABT_dialog, CAT_dialog, EV_captureEvents, EV_eventLoop, EV_restorePainting, EV_sendEvent, EV_sendString, EV_startApp, EV_suspendPainting, EV_switch, handleRclKey, handleVarLinkKey, MO_currentOptions, MO_digestOptions, MO_modeDialog, MO_option, MO_sendQuit, HeapAlloc, HeapDeref, HeapFree, HeapFreeIndir, HeapLock, HeapUnlock, push_ratio, Dialog, DialogAdd, DialogDo, DialogNew, DlgMessage, ER_catch, ER_success, ER_throwVar, ERD_dialog, HToESI, push_Float, push_internal_simplify, top_estack, FontCharWidth, gr_active, memcmp, memcpy, memset, DynMenuAdd, MenuBegin, MenuEnd, MenuKey, PopupDo, PopupNew, PopupText, ST_modKey, ST_helpMsg, sprintf, strcat, AB_getGateArrayVersion, CU_cursorState, CU_restore, HelpKeys, off, OSClearBreak, XR_stringPtr, TE_focus, TE_openFixed, TE_select, fabs, fmod, CustomBegin, CustomEnd, CustomMenuItem, EV_appA, EV_appB, EV_appSide, EV_currentApp, EV_quit, EV_runningApp, has_unit_base, OO_firstACB, OO_GetAppAttr, OO_NextACB, OO_SetAppAttr, FolderOp, SymFindFirst, SymFindNext, VarStore, DrawStaticButton, MakeWinRect, WinActivate, WinAttr, WinBitmapPut, WinClr, WinFill, WinFillTriangle, WinFont, WinLine, WinOpen, WinRect, WinScrollV, WinStrXY, _bcd_math, ROM Call 0x3CD, ROM Call 0x46F, ROM Call 0x471, ROM Call 0x4FB, DateAndTime_SetDlg, DateAndTime_Get, IsClockOn, DateStr, TimeStr, WinBeginPaint
Used by: GD_Circle, GD_Eraser, GD_HVLine, GD_Line, GD_Pen, GD_Select, GD_Text, GZ_Box, HomeExecute, fgetchar, gets, getsn, EV_quit, GT_FreeTrace, GT_KeyIn, GT_Trace, DateAndTime_Get


EV_eventLoop

EV_eventLoop Function (ROM Call 0x158)
events.h

void EV_eventLoop (void);

Enters the loop in which main event messages are collected and dispatched.

EV_eventLoop enters the (endless) loop in which main events are collected and dispatched to the current application. In the normal operation of the calculator (i.e. when no user program is running), the TIOS is just in this loop. Calling this function in the user program makes sense (and may be very useful if you are happy with set of events which are processed in this function) only if the program installs a custom event handler using EV_captureEvents function, so the events may be trapped by the user program.

Here is the exact description what happens in the each iteration of this loop (not in exact order, but this is not important):

  • If there are no activities (keypresses etc.) for a long time, and if the timer APD_TIMER expires (see OSRegisterTimer), the calculator is turned off.
  • If a key is pressed, the event CM_KEYPRESS is send (using EV_sendEvent) to the current application. Note if the current application is "Home screen", this may cause evaluation of the input line (if the pressed key was ENTER key), including execution of user programs, etc. This may also cause changing of the current application (for example, if the user pressed APPS key).
  • If there is a string in the event paste buffer (see EV_sendString), the content of the buffer is processed exactly as if all codes in the buffer are typed from the keyboard (i.e. a sequence of CM_KEYPRESS events are send to the current application).
  • If there is no keypress, if the cursor is enabled (see CU_start) and if CURSOR_TIMER expires (see OSRegisterTimer), CM_BLINK event is send to the current application.
  • If a global variable which contains the error code is non-zero, an error dialog is displayed (using ERD_dialog).
  • If there are twin symbols (see SymAddTwin) in the VAT table, they are deleted. This performs cleaning up the RAM after executing of archived programs.
  • If painting is enabled (see EV_suspendPainting and EV_restorePainting), event CM_WPAINT is send using EV_paintOneWindow function.
  • If there are no other activities, CM_IDLE event is send to the current application, and the function idle is called.

Note that when an user ASM program is started, the current application is always "Home screen", until the user changes the current application using EV_startApp or installs thier own event driven "task" using EV_captureEvents. So, if you simply call EV_eventLoop in the your program, without previous usage of EV_captureEvents or EV_startApp, you will have an illusion that you are not in the your program but in the home screen, because all collected events will be dispatched to the "Home screen" application. Note that in this case, there is no way to exit this loop, and your program will stay "resident" and "locked" in the memory forever, although you will not be aware of the fact that your program is still "running" - you will be able to execute everything, including running other programs etc.

As EV_eventLoop enters the endless loop, the only method (and this is the proposed method in TIOS) to exit the loop is to throw an error from the user event handler installed using EV_captureEvents. This is possible because in the event loop there are no error handlers in place, so ER_throw passes control to the previous level of error handler. In terms of normal operation (i.e. while you are typing in the home screen) this is handled by EV_centralDispatcher, which restarts the event loop. However, in custom event handling it is used to return from the event loop to the calling code. To achieve this, you need to catch errors using ER_catch or using TRY ... ONERR ... ENDTRY construction. So, the typical usage of EV_eventLoop function in user programs is:
EV_captureEvents (UserHandler);
TRY
  EV_eventLoop ();                // The only way to exit from this is
ONERR                             // to throw an error from the event handler!
  EV_captureEvents (NULL);
ENDTRY
Of course, user handler must decide what to do with events dispatched by EV_eventLoop. Very nice example of usage of this methodology is given in textedit.h header file. Another example may be found with the description of CAT_dialog function. These principles are used often in the TIOS. For example, error dialogs are principally implemented as follows (although there are no obvious reasons why events are used in this example):
void ERD_EventHandler(EVENT *ev)
{
  if (ev->Type == CM_KEYPRESS)
    switch (ev->Key.Code)
      {
        case KEY_ENTER: ER_throw (1);
          // Exit from event loop: ENTER key pressed
        case KEY_ESC: ER_throw (2);
          // Another exit: ESC key pressed
        case KEY_OFF: EV_defaultHandler (ev);
          // OFF key pressed: allow the machine to be switched off
      }
}

short ERD_dialog(short err_no, short prog_flag)
{
  EV_captureEvents (ERD_EventHandler);
  // Display the dialog
  TRY
    EV_eventLoop();
  ONERR
    switch(errCode)
      {
        case 1: // Restore the screen and return KEY_ENTER code
        case 2: // Restore the screen and return KEY_ESC code
      }
  ENDTRY
}
To exit from EV_eventLoop, the best idea is to throw error codes less than 8, as they are never used as error codes in normal error handling.

Uses: EV_paintOneWindow, EV_sendEvent, EV_sendEventSide, ERD_dialog, HToESI, kbhit, ngetchx, ST_busy, CU_cursorState, idle, off, OSClearBreak, OSEnableBreak, OSTimerExpired, OSTimerRestart, XR_stringPtr, ERD_dismissNotice, ERD_notice, EV_currentApp, EV_errorCode, LoadSymFromFindHandle, OO_firstACB, SymDelTwin, SymFindFirst, SymFindNext, ROM Call 0x424, ROM Call 0x471
Used by: EV_centralDispatcher, EV_defaultHandler, cmd_input, cmd_inputstr, cmd_prompt, Dialog, ERD_dialog, EV_quit, GT_Trace


EV_getAppID

EV_getAppID Function* (tigcc.a)
events.h

short EV_getAppID (const char *TaskName);

Finds a task ID number for an application.

EV_getAppID returns a task ID number for the task/application whose internal name is TaskName, or returns -1 if the application is not found. Each application (including both built-in applications and external Flash applications) has a unique internal name (max. 8 characters). This function is introduced for compatibility with all AMS versions, because task ID numbers are inconsistent between AMS versions. On AMS 1.xx, built-in flash applications have fixed ID numbers attached to them, but on AMS 2.xx the task ID is simply the handle of the application control block (this is why it is quite hard to add flash applications on AMS 1.xx). So, always use EV_getAppID to determine the task ID number for an application. Internal names of built-in applications are given in the following table:

Application name | Internal name
Home screen | TIHOME
Y=Editor | TIEQUED
Window Editor | TIWINDED
Graph | TIGRAPH
Table | TITABLED
Data/Matrix Editor | TIDMED
Program Editor | TIPRGMED
Text Editor | TITEXTED
Numeric Solver | TIINSLVR
Self Test | TISLFTST

Note: Although this function was not officially introduced before AMS 2.xx, it is implemented here to work even on AMS 1.xx! However, there is one difference between this function, and the function with the same name in Flash Studio SDK. This implementation of EV_getAppID returns -1 if the application is not found, but EV_getAppID from Flash Studio SDK returns zero under the same conditions. The convention used in Flash Studio is not consistent with the fact that the "Home screen" application has the ID number 0 on AMS 1.xx. That's why the value for "not found" is slightly changed in this implementation.

Uses: strcmp, TIOS_EV_getAppID

See also: TIOS_EV_getAppID


EV_getc

EV_getc Function (ROM Call 0xC8)
events.h

unsigned short EV_getc (unsigned short busy, EVENT *event);

Waits for the keypress, then fills an event structure with the keypress.

EV_getc is a function similar like ngetchx. It waits for a keypress, and returns the keycode of the keypress. But, in addition to ngetchx, it also fills the structure pointed to by event with appropriate CM_KEYPRESS event. Parameter busy may be ACTIVITY_IDLE, ACTIVITY_BUSY, ACTIVITY_PAUSED or ACTIVITY_NORMAL (these constants are defined in enum ST_ACTIVITIES). This parameter determines the indicator in the status line which will be displayed (see ST_busy for more info).

If there is no keypress and the cursor timer expires (cca 0.5 seconds), the message CM_BLINK is stored in the event structure instead, and the function returns zero (no keypresses). Also, this routine puts the calculator into low power mode until a character is available, and it will automatically power down the calculator if a key has not been pressed after a few minutes.

Uses: kbhit, ngetchx, ST_busy, CU_cursorState, idle, off, OSTimerExpired, OSTimerRestart, ROM Call 0x471
Used by: GT_KeyIn, ROM Call 0x3EA


EV_getSplitRect

EV_getSplitRect Function (ROM Call 0xC9)
events.h

WIN_RECT *EV_getSplitRect (unsigned short Side);

Gets the screen rectangle for a given side.

EV_getSplitRect consults various calculator mode settings ("Split Screen": "FULL", "LEFT-RIGHT" or "TOP-BOTTOM" and "Split Aspect Ratio": "1:1", "1:2" or "2:1") to determine dimensions of the rectangular area in which the application will be executed. Parameter Side determines wanted side, and it needs to be 0 or 1 (0=left or top side, 1=right or bottom side). EV_getSplitRect returns the static pointer to the WIN_RECT structure which describes the determined rectangular area.

Used by: EV_startSide, EV_startTask


EV_notifySwitchGraph

EV_notifySwitchGraph Function (ROM Call 0xCA)
events.h

void EV_notifySwitchGraph (void);

Notify appropriate applications of graph switching.

EV_notifySwitchGraph does nothing if the calculator is not in "two-graph" mode, else sends CM_SWITCH_GRAPH message to "Graph", "Window Editor", "Table" and "Y= Editor" applications (these applications are the so-called "multigraph" applications).

Uses: EV_sendEvent
Used by: EV_startApp, EV_switch, MO_digestOptions


EV_paintOneWindow

EV_paintOneWindow Function (ROM Call 0xCB)
events.h

short EV_paintOneWindow (void);

Repaints the topmost window.

EV_paintOneWindows searches through a linked list of windows (see wingraph.h header file) for the first window which has WF_DIRTY flag set. If the found window is visible (i.e. if WF_VISIBLE flag is set), the CM_WPAINT message is sent to the application which is the owner of the window (note that WinOpen stores the task ID of the current application in TaskID field of the WINDOW structure). See also notes about EV_sendEvent. After sending this message, WF_DIRTY flag of the window is cleared, and this flag is set in all other windows in the linked list of windows which overlap with this window (because repainting of this window may cause trashing of another windows).

EV_paintOneWindow returns TRUE if the window was "painted" (more precise, if CM_WPAINT message is sent), otherwise it returns FALSE (i.e. if none to paint).

Here is an example which ilustrates that painting of all TIOS windows is "event driven". Suppose that you make very simplified loop which "simulates" normal behaviour of the calculator when it is in the home screen:

while (TRUE)
{
  EV_getc (ACTIVITY_NORMAL, &ev);
  EV_sendEvent (AP_CURRENT, &ev);
}
If you try this program, you will notice that although you can type in statements, execute user programs etc. from this loop, nothing happens on the screen when you type in 2 + 3 <ENTER> (i.e. result 5 is not displayed). This is because the "Home screen" application didn't receive a message which forces redrawing of the Home screen. You can see that everything will be correct if you make the following loop:
while (TRUE)
{
  EV_getc (ACTIVITY_NORMAL, &ev);
  EV_sendEvent (AP_CURRENT, &ev);
  EV_paintOneWindow ();
}

Uses: EV_sendEvent, QScrRectOverlap, FirstWindow
Used by: EV_eventLoop, EV_paintWindows, paint_all_except


EV_paintWindows

EV_paintWindows Function (ROM Call 0xCC)
events.h

void EV_paintWindows (void);

Repaints all windows.

If painting is enabled (see EV_suspendPainting), EV_paintWindows repeatedly calls EV_paintOneWindow until it returns FALSE (no more to paint). So, the effect will be "repainting" of all "dirty" windows.

Uses: EV_paintOneWindow
Used by: handleVarLinkKey, cmd_disptbl, cmd_input, cmd_inputstr, cmd_pause, cmd_prompt, Dialog, HomeExecute, TE_handleEvent, GraphActivate


EV_quit

EV_quit Function (ROM Call 0x48E)
AMS 2.00 or higher events.h, flashapp.h

void EV_quit (void);

Switches from the current application to the Home application.

Uses: EV_appA, EV_appB, EV_appSide, EV_currentApp, OO_GetAppAttr, HeapAlloc, HeapDeref, HeapFreeIndir, HeapLock, HeapUnlock, DlgMessage, ER_catch, ER_success, ER_throwVar, ABT_dialog, EV_captureEvents, EV_defaultHandler, EV_eventLoop, EV_restorePainting, EV_startApp, EV_suspendPainting, EV_switch, MO_currentOptions, MO_digestOptions, MO_sendQuit, FontCharWidth, memset, DynMenuAdd, PopupDo, PopupNew, ST_helpMsg, sprintf, strcat, AB_getGateArrayVersion, OSClearBreak, XR_stringPtr, TE_focus, TE_openFixed, TE_select, fabs, fmod, DrawStaticButton, MakeWinRect, WinActivate, WinAttr, WinBeginPaint, WinBitmapPut, WinClr, WinFill, WinFillTriangle, WinFont, WinLine, WinOpen, WinRect, WinScrollV, WinStrXY, _bcd_math, ROM Call 0x471, DateAndTime_SetDlg, DateAndTime_Get, IsClockOn, DateStr, TimeStr
Used by: SP_Define, cmd_disp, cmd_disphome, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, EV_defaultHandler, HomeExecute, ROM Call 0x45B


EV_registerMenu

EV_registerMenu Function (ROM Call 0x159)
events.h

void EV_registerMenu (void *MenuPtr);

Attaches a menu to an application.

Applications can register toolbar menus with the system event handler. EV_registerMenu registers the toolbar menu pointed to by MenuPtr with the current application. MenuPtr is exactly the same pointer as expected in MenuBegin function. Note that registering the menu will not automatically display nor activate the menu. The application will draw the menu (using MenuBegin) on receipt of CM_ACTIVATE message. So if you, for example, attach a new menu to the "Home screen" application, you need to send CM_ACTIVATE message to it too. Also, before calling EV_registerMenu, a CM_DEACTIVATE message should to be sent to the application.

When a menu is attached to the application, each keypress event (a CM_KEYPRESS message) which represents keys F1, F2 etc. activates the menu (more precise, it is dispatched to the MenuKey function). After execution of MenuKey, the value returned from it (this is the ID of the selected item, see MenuAddText) is sent as an event to the application. So, the ID value for each menu item must be carefully planned: if you want to have the "Cut" option in the menu, its ID needs to be 0x720 (CM_MENU_CUT). Options which represent tokens (as in "Algebra" and "Calc" submenus) have ID less than 0x500, because tokens are send as XR strings (see XR_stringPtr). If you plan to create a serious event driven application which has toolbar menus (a flash application for example), it must behave in the same way (i.e. its event handler must process F-key events as described), and it must respond on CM_ACTIVATE message as described above. Of course, how to put an application in Flash ROM without TI certificate and TI professional SDK is greater problem...

To restore the original menu after termination of the program, you need to get a pointer to the original menu first, and before termination, you have to call EV_registerMenu again passing this pointer to it. The pointer can be obtained by calling OO_GetAppAttr like this:

void *oldmenu = OO_GetAppAttr (EV_runningApp, OO_APP_DEFAULT_MENU);

Note: Sending NULL to EV_registerMenu unattaches the toolbar menu from the application. Here is a dirty example which first removes the menu from the "Home screen" application, then changes parameters of "Home screen" parent window to expand the "Home screen" stack area into the menu area (but note that only a reset would restore the original state after execution of this program):
EVENT ev;
ev.Type = CM_DEACTIVATE;
EV_sendEvent (AP_CURRENT, &ev);
EV_registerMenu (NULL);
ev.Type = CM_ACTIVATE;
EV_sendEvent (AP_CURRENT, &ev);
FirstWindow->Client.xy.y0 = 0;
FirstWindow->Window.xy.y0 = 0;
FirstWindow->Clip.xy.y0 = 0;

Uses: EV_runningApp, OO_SetAppAttr
Used by: ROM Call 0x45B


EV_restorePainting

EV_restorePainting Function (ROM Call 0xCD)
events.h

short EV_restorePainting (short blockPaint);

Restores previous state of window painting.

EV_restorePainting suspends or enables window painting, depending on whether blockPaint is PAINTING_ENABLED or PAINTING_SUSPENDED (these constants are defined in enum PaintFlags). The main purpose of this function is to restore previous state after usage of EV_suspendPainting function. EV_restorePainting also returns previous state of painting enable flag (PAINTING_ENABLED or PAINTING_SUSPENDED) before calling this function.

Uses: EV_flags
Used by: ABT_dialog, EV_defaultHandler, Dialog, ERD_dialog, EV_quit


EV_sendEvent

EV_sendEvent Function (ROM Call 0xCE)
events.h

void EV_sendEvent (short TaskID, EVENT *event);

Sends an event message from the current side.

EV_sendEvent sends the event message described in the structure pointed to by event to the task/application with ID number TaskID (see below for more info about task IDs). Note that the user needs to pre-fill only Type field of the event structure and eventually extra field (if the message has extra information attached). All other fields will be filled by EV_sendEvent function before sending the message.

The Type field of the event structure is interpreted as following:

  • If Type >=0x700, the message is an event command message (like CM_KEYPRESS, CM_WPAINT, etc. These codes are defined in enum EventIDs. These messages are the most common messages, and such messages are the most usable messages in user applications. See EventIDs for detailed description of the meaning of such messages.
  • If 0x500 <=Type < 0x700, the message is a custom command message. The interpretation of such messages is strictly task-dependent. The TIOS uses such messages in dialogs, etc.
  • If Type < 0x500, XR_string (see XR_stringPtr) is sent as the message. This is used for internal purposes in TIOS.
Here is the description what EV_sendEvent exactly does:
  • If EV_hook pointer is not NULL, then a routine pointed to by it is called, passing event to it.
  • If there is an user event handler installed (using EV_captureEvents), the user handler is called, and event is passed to it. In this case, parameter TaskID is ignored. The only exception is when the message is CM_WPAINT. In this case, the user handler is called only if TaskID is AP_NULL.
  • If there is no user event handler installed, the message event is sent to the default application-dependent event handler, which is determined by parameter TaskID. Note that default application-dependent event handler will not be called if there is an user event handler installed. The exception is when the message is CM_WPAINT. This message is always dispatched to the default application-dependent handler, except if TaskID is AP_NULL.
Note that task ID numbers are inconsistent between AMS versions, so always call EV_getAppID before to determine an appropriate task ID, or use special task IDs AP_CURRENT, AP_RUNNING and AP_NONE, which are AMS-independent.

If you want to send an event from the user event handler, you can enter into an infinite recursion. Here is an example how to avoid this. The following program will change the behaviour of the ENTER key to behave like pressing DIAMOND+ENTER. So, run the following program (called "Approximation Mode"). After this, the ENTER key will behave like DIAMOND+ENTER (note that the program is "resident": it is active for whole time, although you have feeling that you are in "Home screen" for example). The ENTER key will remain redefined until the user press DIAMOND+ENTER. After this, the original function of the ENTER key is restored, and the program finishes working.
// Run Home Screen in approximation mode

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

volatile EVENT_HANDLER Old_Handler;

CALLBACK void Handler(EVENT *ev)
{
  if (ev->Type == CM_KEYPRESS)
    {
      if (ev->extra.Key.Code == KEY_DIAMOND + KEY_ENTER)
        ER_throw (1);
      if (ev->extra.Key.Code == KEY_ENTER)
        ev->extra.Key.Code = KEY_DIAMOND + KEY_ENTER;
    }
  /* Send the event to the default application handler,
     but be careful to avoid infinite recursion! */
  EV_captureEvents (Old_Handler);
  EV_sendEvent (AP_CURRENT, ev);
  Old_Handler = EV_captureEvents (Handler);
}

void _main(void)
{
  Old_Handler = EV_captureEvents (Handler);
  TRY
    EV_eventLoop ();
  ONERR
    EV_captureEvents (Old_Handler);
  ENDTRY
}
Of course, this program is not extremely useful: the much easier method to achieve the same functionality is to set the calculator to "APPROX" mode. But, note that this is just an example, which should give you an idea how to redefine the keyboard.

Note: The destination application does not have to be started or active to receive messages. You should first start the application using EV_startApp if it is important that the application be on the screen before it receives an event.

Uses: EV_sendEventSide, EV_appSide
Used by: EV_centralDispatcher, EV_defaultHandler, EV_eventLoop, EV_notifySwitchGraph, EV_paintOneWindow, EV_sendString, EV_startApp, EV_startTask, EV_switch, handleRclKey, handleVarLinkKey, MO_notifyModeChange, cmd_disptbl, cmd_table, HomeExecute, CustomMenuItem, GraphActivate, ROM Call 0x424, ROM Call 0x428, ROM Call 0x455


EV_sendEventSide

EV_sendEventSide Function (ROM Call 0xCF)
events.h

void EV_sendEventSide (short TaskID, EVENT *event, unsigned short Side);

Sends an event message from the given side.

EV_sendEventSide is very similar to EV_sendEvent. The only difference is in the fact that EV_sendEventSide fills the field Side of the event structure with the value of parameter Side. EV_sendEvent fills this field with the current side number (0=left or top side, 1 = right or bottom side). This field allows the message handler to determine which side (of course, in split screen mode) the message is sent from, so it allows a primitive kind of multitasking.

Uses: EV_hook, ER_catch, ER_success, ER_throwVar, EV_currentApp, EV_runningApp, OO_GetAttr, ST_flags
Used by: EV_eventLoop, EV_sendEvent, EV_startSide, MO_digestOptions, MO_sendQuit


EV_sendString

EV_sendString Function (ROM Call 0xD0)
events.h

void EV_sendString (unsigned short XR_String);

Sends XR string to the running application.

EV_sendString is an internal function which sends the XR string (see XR_stringPtr) to the running application via a CM_STRING message. XR_String is the code of the XR string which will be sent.

Uses: EV_sendEvent, XR_stringPtr
Used by: EV_defaultHandler


EV_setCmdCheck

EV_setCmdCheck Function (ROM Call 0xD1)
events.h

void EV_setCmdCheck (unsigned short ID, short State);

Checks/unchecks a menu item in the current application.

This function sets or clears the check mark on a menu item in the current application. It is related to MenuCheck from the menus.h header file. EV_setCmdCheck checks or unchecks the item with the specified ID (see EV_registerMenu).

State should be one of the following values as defined in the MenuCheckCmds enum:
MC_CHECK | Display a check mark next to the menu item.
MC_UNCHECK | AMS 2.00 or higher: Remove the check mark.
MC_FLIP | Invert the status of the check mark.

Note: Unlike MenuCheck, you cannot use the MC_STATUS command to retrieve the status of the checkmark.

Uses: MenuCheck, ROM Call 0x3CD


EV_setCmdState

EV_setCmdState Function (ROM Call 0xD2)
events.h

void EV_setCmdState (unsigned short cmd, short State);

Changes the status (active/inactive) of a menu command in the current application.

EV_setCmdState is similar to EV_setFKeyState, but works with command pulldown menus associated with the main toolbar menu which belongs to the current application. EV_setCmdState changes the status of the command item which has its ret_val (see EV_registerMenu) equal to the cmd. For example, if you execute

EV_setCmdState (CM_MENU_CUT, FALSE);
in your program, you will see that the "Cut" command in the "Home screen" menu will be disabled (note that "Home screen" is the current application if you didn't use EV_startApp in your program). CM_MENU_CUT is, of course, the code of the "Cut" menu command.

Uses: MenuSubStat, ROM Call 0x3CD
Used by: cmd_disphome, HomeExecute, TE_indicateReadOnly

See also: MenuSubStat


EV_setFKeyState

EV_setFKeyState Function (ROM Call 0xD3)
events.h

void EV_setFKeyState (unsigned short Item, short State, short Redraw);

Changes the status (active/inactive) of a toolbox in the menu associated with current application.

EV_setFKeyState changes the status of the toolbox Item (0 = first, 1 = second etc.) which belongs to the menu associated with the current application (see also MenuTopStat). State is a Boolean value: when it is TRUE, the toolbox will be active, and when it is FALSE, the toolbox will be inactive (i.e. it will be dimmed, and it cannot be selected).

EV_setFKeyState can also force redrawing of the menu after changing state: to do this, set Boolean parameter Redraw to TRUE. Avoid menu redraw flicker when enabling/disabling several function keys by specifying FALSE for redraw in all but the last call to this routine.

Uses: MenuOn, MenuTopStat, CU_cursorState, CU_restore, ROM Call 0x3CD, ROM Call 0x4FB
Used by: cmd_disp, cmd_disphome, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, HomeExecute

See also: MenuTopStat


EV_startApp

EV_startApp Function (ROM Call 0xD4)
events.h

void EV_startApp (HANDLE TaskID, unsigned short StartType);

Starts an application from any state.

EV_startApp is dedicated to "start the application". It changes current application to TaskID and sends a sequence of messages to it (how they will be interpreted depends on the concrete application), so this command may be used for changing the current application.

It is not likely that following information will be very useful for you (except if you are an expert who wants to make a new high perfomance flash application), but anyway here is the pseudo-code which describes what exactly EV_startApp does:

if TaskID is equal to the current application
  if StartType is AP_START_CURRENT
    send CM_START_CURRENT to the current application
  else {change task}
    send CM_UNFOCUS, CM_DEACTIVATE and CM_ENDTASK to the current application
    call EV_startTask, passing StartTask to it
    send CM_ACTIVATE and CM_FOCUS to the current application
  endif
else {new application}
  send CM_UNFOCUS and CM_DEACTIVATE to the current application
  if TaskID is equal to the application on the other side
   and if the calculator is in "two-graph" mode
   or TaskID is not "Graph", "Window Editor", "Table" nor "Y= Editor"
    set current application to TaskID
    invert current side
    call EV_notifySwitchGraph
    if StartType is not AP_START_CURRENT
      send CM_ENDTASK to the new application
      call EV_startTask, passing StartTask to it
    endif
  else
    send CM_ENDTASK to the current application
    set current application to TaskID
    call EV_startTask, passing StartTask to it
  endif
  send CM_ACTIVATE and CM_FOCUS to the new application
endif
Under normal circumstances, you should start another application with StartType set to AP_START_CURRENT.

Note: Task ID numbers are inconsistent between AMS versions (see EV_getAppID for more info). So, if you, for example, want to start the "Numeric Solver" application, the AMS-independent way to do this is
EV_startApp (EV_getAppID ("TIINSLVR"), AP_START_CURRENT);
Also, some common applications (like "Graph", "Table" or "Home screen") may be started safely using some commands from bascmd.h header file.

Uses: EV_notifySwitchGraph, EV_sendEvent, EV_startTask, MO_isMultigraphTask, EV_appA, EV_appB, EV_appSide, EV_currentApp
Used by: EV_defaultHandler, EV_switch, cmd_disp, cmd_disphome, cmd_disptbl, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, cmd_table, ERD_process, HomeExecute, EV_quit, GraphActivate, ROM Call 0x455


EV_startSide

EV_startSide Function (ROM Call 0xD5)
events.h

void EV_startSide (short *saveTaskID, HANDLE TaskID, unsigned short Side);

Starts the given side.

EV_startSide first sends CM_STARTTASK message to the application with ID number TaskID. Field StartType of the event structure will be set to AP_START_CURRENT, and field r (in extra field) of the event structure will be filled from the result of executing EV_getSplitRect function (with Side given to it as the parameter). See EV_startTask. This is all if the current side is not equal to Side, else messages CM_ACTIVATE and CM_FOCUS will also be sent to the task TaskID and side Side (using EV_sendEventSide). EV_startSide also fills the variable pointed to by saveTaskID with TaskID (I don't know what the purpose of this is).

Uses: EV_getSplitRect, EV_sendEventSide, EV_appSide, EV_currentApp
Used by: MO_digestOptions

See also: EV_startApp


EV_startTask

EV_startTask Function (ROM Call 0xD6)
events.h

void EV_startTask (unsigned short StartType);

Starts a particular task in the running application.

EV_startTask sends CM_STARTTASK message to the running application. Field StartType of the event structure will be filled from StartType parameter of this function (this is the only message in which StartType field is significant). Field r (in extra field) of the event structure will be filled from the result of executing EV_getSplitRect function (with current side given to it as the parameter). How StartType will be interpreted depends on the concrete application. Usually, three types of "starting" are supported: AP_START_CURRENT, AP_START_NEW and AP_START_OPEN (these constants are defined in enum StartTypes. For example, Text and Data/Matrix editor may be started in three submodes: "Current", "Open" and "New". Under normal circumstances, you should start another task with AP_START_CURRENT.

Uses: EV_getSplitRect, EV_sendEvent, EV_appSide
Used by: EV_centralDispatcher, EV_startApp, MO_digestOptions


EV_suspendPainting

EV_suspendPainting Function (ROM Call 0xD7)
events.h

short EV_suspendPainting (void);

Suspends window painting.

EV_suspendPainting sets a flag which indicates that window painting is suspended (see EV_eventLoop and EV_paintWindows). Returns PAINTING_ENABLED or PAINTING_SUSPENDED depending on whether painting was enabled or disabled before calling this function (these constants are defined in enum PaintFlags), so the returned value may be later used in the EV_restorePainting function.

Uses: EV_flags
Used by: ABT_dialog, EV_defaultHandler, Dialog, ERD_dialog, EV_quit


EV_switch

EV_switch Function (ROM Call 0xD8)
events.h

void EV_switch (void);

Performs switching of sides.

EV_switch performs side switching. It does nothing if the current "Split Screen" mode is "FULL". Else, it sends CM_UNFOCUS and CM_DEACTIVATE messages, inverts current side, sets the current application to the application on the other side, calls EV_notifySwitchGraph, and finally, sends CM_ACTIVATE and CM_FOCUS messages to the new application.

Note: In AMS 2.xx, this function is extended to allow switching between the current application and the application which last ran before the current application.

Uses: EV_notifySwitchGraph, EV_sendEvent, EV_startApp, EV_appA, EV_appB, EV_appSide, EV_currentApp, OO_firstACB, OO_NextACB
Used by: EV_defaultHandler, push_switch, HomeExecute, EV_quit


handleRclKey

handleRclKey Function (ROM Call 0x14F)
events.h

void handleRclKey (short CRstatus);

Displays the standard "Recall Variable" dialog.

handleRclKey is the default handler for the 'RCL' key (called from EV_defaultHandler when processing a CM_RECALL message). A pop-up dialog box is displayed requesting the name of a variable. The contents of the variable are converted to text and pasted to the current application as a CM_HSTRING message. Nothing is pasted if the user pressed 'ESC' to cancel the dialog.

CRstatus is a boolean parameter. If it is TRUE, carriage returns are converted to colons after the contents of the variable have been converted to text. The variable itself is not changed. If it is FALSE, carriage returns remain unchanged.

Note: This function may cause heap compression and may throw errors.

Uses: EV_sendEvent, HeapAlloc, HeapFreeIndir, HeapGetLock, HeapLock, HeapUnlock, Dialog, ER_catch, ER_success, ER_throwVar, display_statements, HToESI, Parse1DExpr, TokenizeSymName, top_estack, memset, strchr, strlen, NeedStack, DerefSym, GetFuncPrgmBodyPtr, VarRecall
Used by: EV_defaultHandler

See also: handleVarLinkKey


handleVarLinkKey

handleVarLinkKey Function (ROM Call 0x129)
AMS 2.00 or higher events.h

void handleVarLinkKey (short type);

Displays the standard "Var-Link" dialog.

handleVarLinkKey shows the "Var-Link" screen and allows the user to select a variable of type type. Valid values for type are described in the enum SystemDataTypes. In addition to those, you can OR type with 0x8000 to forbid the user to change (i.e. delete, copy, rename, etc.) any variables. The name of any variable or folder selected is sent back to the currently active application as a CM_HSTRING message.

This routine may cause heap compression.

Uses: EV_paintWindows, EV_sendEvent, HeapAlloc, DlgMessage, ER_catch, ER_success, ER_throwVar, ERD_dialog, HToESI, next_expression_index, push_parse_text, top_estack, GKeyIn, LIO_RecvData, LIO_SendData, memset, MenuBegin, MenuEnd, MenuKey, MenuOn, MenuSubStat, MenuTopStat, MenuUpdate, ST_folder, ST_helpMsg, sprintf, strcat, strchr, strlen, strncpy, CU_restore, CU_stop, NeedStack, OSClearBreak, OSDisableBreak, OSEnableBreak, XR_stringPtr, trig, CTypeTable, OO_firstACB, OO_GetAppAttr, OO_NextACB, OO_PrevACB, DerefSym, FolderCount, FolderDel, FolderGetCur, GetDataType, IsMainFolderStr, SmapTypeStrings, StrToTokN, SymCmp, SymCpy, SymCpy0, SymDel, SymFindFirst, SymFindNext, SymFindPrev, SymSysVar, VarRecall, DrawWinBorder, MakeWinRect, WinActivate, WinAttr, WinCharXY, WinClose, WinClr, WinFill, WinOpen, WinStrXY, ROM Call 0x40E, ROM Call 0x424, OO_GetFlashAppSize, ROM Call 0x4FD
Used by: EV_defaultHandler

See also: handleRclKey, GetDataType, SmapTypeStrings


MO_currentOptions

MO_currentOptions Function (ROM Call 0xD9)
events.h

void MO_currentOptions (void);

Fills in options structure from current mode settings.

MO_currentOptions fills the structure pointed to by ModeSettings and MO_option from current mode settings. It should always be called before using MO_digestOptions.

Uses: MO_option, gr_active, gr_other, strcmp, XR_stringPtr, EV_appA, EV_appB, OO_AppNameToACB, ROM Call 0x471
Used by: EV_defaultHandler, MO_modeDialog, push_setmode, gdb_recall, gdb_store, OSLinkCmd, EV_quit, tokenize_if_TI_92_or_text


MO_defaults

MO_defaults Function (ROM Call 0xDA)
events.h

void MO_defaults (void);

Sets default mode settings.

MO_defaults resets options structure (i.e. fills the structure pointed to by ModeSettings and MO_option with default settings), then calls MO_digestOptions to dispatch these settings to applications.

Uses: MO_digestOptions, MO_option, OO_firstACB, OO_NextACB


MO_digestOptions

MO_digestOptions Function (ROM Call 0xDB)
events.h

void MO_digestOptions (short Folder);

Updates system mode settings from options structure.

MO_digestOptions "digests" options from the ModeSettings structure (in other words, the MO_option array) into the various TIOS system variables. It should be called after each change of the options structure to notify the calculator about changes. This routine may change the status line indicators. It also notifies all applications about eventual changes, if there was any essential changes (using MO_notifyModeChange). If new mode settings need a change of current application or side, it may also quit an application (see MO_sendQuit), switch sides, start a new applications/tasks etc. which in fact means sending a sequence of messages to applications (see EV_startApp etc.).

Parameter Folder is the index (ordinal number) of the current folder in the folder list. Under normal conditions, you should always pass zero to this parameter. The mode dialog box calls MO_digestOptions with non-zero argument to indicate which folder name is highlighted in the "Current Folder" popup menu.

Uses: EV_notifySwitchGraph, EV_sendEventSide, EV_startSide, EV_startTask, MO_isMultigraphTask, MO_notifyModeChange, MO_option, MO_sendQuit, next_expression_index, PopupText, ST_angle, ST_folder, ST_precision, cmpstri, strcmp, XR_stringPtr, CTypeTable, EV_appA, EV_appB, EV_appSide, EV_currentApp, init_unit_system, OO_firstACB, OO_GetAppAttr, OO_NextACB, FolderCur, StrToTokN, ROM Call 0x41C, ROM Call 0x41D, ROM Call 0x41E, ROM Call 0x471
Used by: EV_defaultHandler, MO_defaults, MO_modeDialog, push_setmode, gdb_recall, OSLinkCmd, EV_quit


MO_isMultigraphTask

MO_isMultigraphTask Function (ROM Call 0xDC)
events.h

short MO_isMultigraphTask (short TaskID);

Checks whether a task is multigraph task.

MO_isMultigraphTask returns TRUE if the task with ID number TaskID is "Y= Editor", "Window Editor", "Graph" or "Table" (these tasks are tasks which may be doubled in two different part of the screen), otherwise it returns FALSE.

Used by: EV_startApp, MO_digestOptions


MO_modeDialog

MO_modeDialog Function (ROM Call 0xDD)
events.h

void MO_modeDialog (void);

Executes "MODE" dialog.

MO_modeDialog opens the "MODE" dialog, and allows the user to set mode options. If the user pressed ENTER key, MO_digestOptions will be called to "digest" new settings to TIOS. If the user pressed ESC key, nothing will happen. In each case, the dialog will be removed from the screen after pressing ENTER or ESC.

Uses: MO_currentOptions, MO_digestOptions, MO_option, HeapDeref, HeapFree, HeapFreeIndir, Dialog, ER_catch, ER_success, memset, MenuAddText, PopupNew, VarCreateFolderPopup, strcat, EV_currentApp, EV_errorCode, OO_firstACB, OO_GetAppAttr, OO_NextACB, ROM Call 0x486
Used by: EV_defaultHandler


MO_notifyModeChange

MO_notifyModeChange Function (ROM Call 0xDE)
events.h

void MO_notifyModeChange (short Flags);

Sends mode change notify message to all applications.

MO_notifyModeChange sends a CM_MODE_CHANGE message to all applications (note that the "Graph" application will receive this message first). This function also has a parameter Flags, which contains a set of flags which describes what exactly was changed. This parameter is attached to message in the extra field of the message, so it gives more information to applications on what they need to check.

The flags can be one of the following as enumerated in MoNotifyFlags:
MO_NOTIFY_FOLDER | The current folder has changed.
MO_NOTIFY_GRAPH_COUNT | 2 graph mode or 1 graph mode.
MO_NOTIFY_GRAPH_TYPE_1 | Graph mode change.
MO_NOTIFY_GRAPH_TYPE_2 | Graph mode change for graph 2 if in 2 graph mode.
MO_NOTIFY_SPLIT | The screen size has changed.
MO_NOTIFY_ANGLE | The angle mode has changed.
MO_NOTIFY_PRECISION | The precision has changed between EXACT, APPROX and AUTO.
MO_NOTIFY_FIX | Fix digits or float precision change.
MO_NOTIFY_NUMBER_FORMAT | Exponential format: Normal, scientific or engineering.
MO_NOTIFY_VECTOR_FORMAT | Rectangular, cylindrical or spherical.
MO_NOTIFY_COMPLEX_FORMAT | Real, rectangular or polar.
MO_NOTIFY_PRETTY_PRINT | Pretty Print has been switched on or off.
MO_NOTIFY_UNIT_SYSTEM | SI, ENG/US or CUSTOM unit system.
MO_NOTIFY_BASE | DEC, HEX or BIN base.
MO_NOTIFY_LANGUAGE | AMS 2.00 or higher: The language mode has changed.
MO_NOTIFY_DESKTOP | AMS 2.07 or higher: The Apps Desktop has been switched on or off.

Uses: EV_sendEvent, reset_control_flags, MenuUpdate, ST_eraseHelp, ST_helpMsg, EV_appA, EV_appB, OO_firstACB, OO_NextACB, FirstWindow
Used by: MO_digestOptions, setup_unit_system


MO_sendQuit

MO_sendQuit Function (ROM Call 0xDF)
events.h

void MO_sendQuit (short TaskID, short Side);

Quits an application on given side.

MO_sendQuit quits an application on side Side (0=left/top, 1 = right/bottom). This is what pressing of the QUIT key does. More precise, if Side is equal to the current side, the side will receive CM_UNFOCUS and CM_DEACTIVATE messages. After this, the application will receive CM_ENDTASK message. Finally, the application on side Side will be set to CM_NULL. If the application on side Side is already CM_NULL, nothing will be performed.

Note: If you don't understand what "quitting" means, try MO_sendQuit(AP_CURRENT, 0) from your program to "quit" the "Home screen" application. You will notice that the menu will dissappear. Later, executing commands will not show results in the home screen, because "repainting" of the "Home screen" window will be suspended (the application is set to CM_NULL).

Uses: EV_sendEventSide, EV_appA, EV_appB, EV_appSide
Used by: EV_defaultHandler, MO_digestOptions, EV_quit


TIOS_EV_getAppID

TIOS_EV_getAppID Function (ROM Call 0x454)
AMS 2.00 or higher events.h

HANDLE TIOS_EV_getAppID (const unsigned char *TaskName);

Finds a task ID number for an application, AMS 2.xx only.

This the AMS routine called by EV_getAppID on AMS 2.xx.
Upon failure to find the application ID, this routine returns 0, while EV_getAppID returns -1.
If your program needs MIN_AMS >= 200 for another reason, you should use this function instead of using EV_getAppID: it will save space in your program.

Uses: OO_firstACB, strncmp
Used by: OO_InstallAppHookByName, OO_UninstallAppHookByName, EV_getAppID, LIO_Receive, ROM Call 0x478

See also: EV_getAppID


EV_flags

EV_flags Variable (ROM Call 0x5DF)
AMS 2.04 or higher events.h

EV_FLAGS EV_flags;

State information for the event manager.

Used by: EV_restorePainting, EV_suspendPainting


EV_hook

EV_hook Variable (ROM Call 0x2A3)
events.h

EVENT_HANDLER EV_hook;

A global variable pointing to the "hook" event handler.

EV_hook is a global pointer variable which points to the "hook" event handler (or NULL if there is no "hook" handler installed. Hook handler hooks events like EV_captureEvents, however, the application handler (either default application handler or user handler installed with EV_captureEvents) is still called afterwards (see EV_sendEvent for more info. This is probably meant for debugging purposes as it is never used in TIOS.

Using EV_hook you can capture all messages and process them as you like, without overriding current handlers. So, you can use it to change behaviour of some events, or add new functionalities. DoorsOS for example uses EV_hook to add SHIFT+ON feature. You also can hook the APPS key and display a different menu in which your application set will be listed (then you can start your own event driven application via EV_captureEvents). If you understand principles described in this header file, this is not so hard. If you didn't understand what is written here, don't try to play with this...

Used by: EV_centralDispatcher, EV_sendEventSide, HomeStore


MO_option

MO_option Constant (ROM Call 0x447)
events.h

unsigned short *const MO_option;

Contains a pointer to the global mode settings array.

MO_option is a constant pointer to an array of words (unsigned shorts) equivalent to the MO_OPTIONS structure pointed to by ModeSettings. In fact, the definition is almost exactly the same, only the pointer type differs for compatibility with TI's compiler.

Used by: EV_defaultHandler, MO_currentOptions, MO_defaults, MO_digestOptions, MO_modeDialog, HomeExecute

See also: ModeSettings


ModeSettings

ModeSettings Constant (ROM Call 0x447)
events.h

MO_OPTIONS *const ModeSettings;

Contains a pointer to the global MO_OPTIONS structure.

ModeSettings is the constant pointer to the MO_OPTIONS structure, which keeps all mode settings together. But note that this structure is "auxiliary": TIOS consults other variables to check various mode settings when necessary. So, values in this structure are correct only after calling MO_currentOptions, and after changing one or more values in this structure, you need to call MO_digestOptions to inform TIOS about any changes. So, if you want, for example, to change "Display Digits" settings to "FIX 4" and "Complex Format" to "POLAR", you should do:

MO_currentOptions ();
ModeSettings->Fix = 5;
ModeSettings->Complex = 3;
MO_digestOptions (0);

See also: MO_option


EV_FLAGS

EV_FLAGS Type (Enumeration)
AMS 2.04 or higher events.h

typedef enum {EV_OFF = 0x0001, EV_SUSPEND_PAINTING = 0x0002} EV_FLAGS;

An enumeration for describing possible bits for EV_flags.

EV_OFF: The default event handler sets this flag when the 2ND + OFF key is pressed. The EV_OFF flag will never be set when any events are sent to an application, you should never see this flag set.

EV_SUSPEND_PAINTING: This flag is set by EV_suspendPainting and restored by EV_restorePainting. The event manager quits sending CM_WPAINT messages when this flag is set, and resumes painting when this flag is clear.

See also: EV_flags


EVENT_HANDLER

EVENT_HANDLER Type (Pointer)
events.h

typedef void (* EVENT_HANDLER) (EVENT *) CALLBACK;

A pointer to an event handler.

EVENT_HANDLER is a pointer type, pointing to a void function which accepts one parameter which is a pointer to an EVENT. See EV_captureEvents and EV_hook for more info.


EVENT

EVENT Type (Structure)
events.h, textedit.h

typedef struct EventStruct {
unsigned short Type; /* ID code of the message, see EventIDs */
unsigned short RunningApp; /* Task ID of the sender of the message */
unsigned short Side; /* Side from which message is sent */
unsigned short StatusFlags; /* Status line flags */
union /* Message-dependent extra information: see EventIDs */ {
WINDOW *w;
WIN_RECT *r;
char *pasteText;
HANDLE hPasteText;
struct {
unsigned short Mod; /* Key modifiers (SHIFT, etc.) */
unsigned short Code; /* Key code */
} Key;
} extra;
unsigned char StartType; /* Used only in the CM_STARTTASK message */
} EVENT;

A structure describing an event message.

EVENT is a structure which describes an event message in an event-driven application.


EventIDs

EventIDs Type (Enumeration)
events.h

enum EventIDs {...};

An enumeration describing IDs of system messages.

EventIDs is enumerated type for describing ID numbers of system messages (they are stored in the Type field of the EVENT structure. All possible ID numbers (everything is in hex) are described in the following table. "Extra field" describes which subfield in extra union field of EVENT structure is used for storing extra information (if any). "(depr.)" after a name specifies that this name is deprecated.

Code | Message name | Description | Extra field
0x0 | CM_NOTHING |  |
0x1 - 0x4FF | CM_LAST_STRING_NUMBER | Built-in strings: Strings for the AMS are stored in a table for lanugage customization. EV_defaultHandler will turn these events into CM_PASTE_STRING events for the application to process. For compatibility with TI's Flash Studio, CM_LAST_STRING_NUMBER (0x4FF) is defined here. |
0x500 | CM_FIRST_APP_ID | Commands in the range 0x500 - 0x6FF are reserved for applications. Generally, these commands refer to Menu choices made by the user while running the application. |
0x700 | CM_FIRST_SYS_ID | Commands in the range 0x700 - 0x7BF are reserved for use by the AMS. |
0x700 | CM_NULL CM_IDLE (depr.) | Idle (idle is called after message sent). This message is sent to the active application when there are no other events to process. The application might use this event to take care of some background processing or update an animated display. This message is used for example in spinning of 3D graph. |
0x701 | CM_INIT | Init application. This message is sent from EV_centralDispatcher after a reset or when batteries are inserted. |
0x702 | CM_START CM_STARTTASK (depr.) | Start Task (in rect r). This message is sent to a task when it is being started. r is a rectangle with the requested window location and size chosen by the user from the mode screen settings. The application passes it to WinOpen to create its initial window. StartType field of the message is checked here (see EV_startTask), because some applications display a "Current/Open/New" submenu on the APPS menu, so this field is needed to tell the application which submenu command was selected by the user. | r
0x703 | CM_ACTIVATE | Activate. Applications usually respond to this message by highlighting their window border to make it apparent to the user which application is active, by setting menu command states, and by updating (or activating) registered menus (see EV_registerMenu. Calling EV_defaultHandler will register and start the default toolbar for the running application. |
0x704 | CM_FOCUS | Focus. Applications usually respond to this message by getting Mode options, and by giving the focus to the application editor (see TE_focus in textedit.h header file). This usually means making the cursor flashing. |
0x705 | CM_UNFOCUS | UnFocus. Usually used on switching sides. When used on the text editor, it means turning of the cursor flashing. |
0x706 | CM_DEACTIVATE | DeActivate. This message is sent to the active application to inform it that it no longer holds the interactive center of attention. Applications usually respond to this message by hiding menus and releasing the memory occupied by them. |
0x707 | CM_QUIT CM_ENDTASK (depr.) | End Task. Applications usually respond to this message by hiding windows and doing various cleanups. |
0x708 | CM_RESTART CM_START_CURRENT (depr.) | Start current. This message only notifies the current application that the user has chosen to start the same application again. Usually ignored. |
0x709 | CM_APD |  |
0x70A | CM_OFF |  |
0x70B | CM_ON | Sent to each application when the calculator is turned on after being turned off with ([2ND] [OFF]). This command is not sent if the calculator was turned off via APD (Auto Power Down). |
0x70C | CM_INSTALL | Sent to a FLASH application after it has been successfully installed on the calculator. This event will be sent when batteries are replaced, and after the FLASH app has been downloaded into the FLASH memory. |
0x70D | CM_UNINSTALL | Sent to a FLASH application before it is deleted from the FLASH memory. |
0x70E | CM_PACK | Tells a FLASH app that FLASH memory garbage collection is about to take place. All important settings should to be backed up using the application's public storage. |
0x70F | CM_UNPACK | Tells a FLASH app that FLASH memory garbage collection has finished. The application should restore any saved settings. |
0x710 | CM_KEY_PRESS CM_KEYPRESS (depr.) | Keypress. This is the most common event. Note that a lot of system and mode events (opening system menus, dialogs etc.) are also processed as keypresses. They all have correct keypresses attached to them (usually DIAMOND + ...). Tokens are usually send via EV_sendString and do not have to be processed as single keypresses. All special keypresses may be passed to EV_defaultHandler for further processing. | Key
0x720 | CM_CUT CM_MENU_CUT (depr.) | Menu command: Cut. Dedicated for cutting selected text to the clipboard. All similar (text editing) events should eventually be handled by TE_handleEvent (the default text editor handler). |
0x721 | CM_COPY CM_MENU_COPY (depr.) | Menu command: Copy. Dedicated for copying selected text to the clipboard. Should eventually be handled by the default text editor handler. |
0x722 | CM_PASTE CM_MENU_PASTE (depr.) | Menu command: Paste. Dedicated for pasting text from the clipboard to the edit buffer at the cursor position, replacing any eventually selected text. Should eventually be handled by the default text editor handler. |
0x723 | CM_PASTE_STRING CM_STRING (depr.) | Paste static (constant) text into the event paste buffer (in fact, it only sets a pointer to PasteText). See EV_eventLoop and EV_sendString. | PasteText
0x724 | CM_PASTE_HANDLE CM_HSTRING (depr.) | Paste dynamic text, associated with a handle. The handle is released back to the heap by the default text edit handler after the paste is complete. | hPasteText
0x725 | CM_DELETE CM_DEL (depr.) | DEL (backspace) keypress. Dedicated for deleting selected text, or one character to the left of the cursor if no text is selected. Should eventually be handled by the default text editor handler. |
0x726 | CM_CLEAR CM_CLR (depr.) | CLR keypress. Dedicated for clearing selected text (if no text is selected, clear from cursor to end of edit buffer, and if cursor is at end of edit buffer, clear all text from edit buffer). Should eventually be handled by the default text editor handler. |
0x727 | CM_CLEAR_ALL CM_MENU_CLEAR (depr.) | Menu command: Clear. The application should decide decides what it means. |
0x728 | CM_FIND CM_MENU_FIND (depr.) | Menu command: Find. The application should decide decides what it means. |
0x730 | CM_TOGGLE_INSERT CM_INSERT (depr.) | Insert key. Dedicated for switching between text insert mode and overstrike mode. Should eventually be handled by the default text editor handler. |
0x740 | CM_CURSOR_FLASH CM_BLINK (depr.) | Flash cursor (0.5 sec timer expired, see EV_eventLoop). |
0x750 | CM_STO CM_STORE (depr.) | "Store" keypress. The default handler convert this message to the right arrow character. |
0x751 | CM_RCL CM_RECALL (depr.) | "RCL" keypress. The default event handler displays a dialog box for the user to enter the name of a variable to recall. The chosen variable’s contents are pasted at the edit cursor. |
0x760 | CM_WPAINT | Paint window. Pointer to a window which need to be painted is attached. Applications should check to see if it belongs to the application and to redraw it if it is. See EV_paintWindows. These are not sent to the capturing hook, unless an application ID number is set to CM_NULL (force redraw). WinOpen stores the current application ID number in TaskId field of WINDOW structure. | w
0x770 | CM_OPEN CM_MENU_OPEN (depr.) | Menu command: Open... (the application should decide how to handle this and similar event messages; there are no default actions for them). |
0x771 | CM_SAVE_AS CM_MENU_SAVE (depr.) | Menu command: Save Copy As... |
0x772 | CM_NEW CM_MENU_NEW (depr.) | Menu command: New... |
0x773 | CM_FORMAT CM_MENU_FORMAT (depr.) | Menu command: Format... |
0x774 | CM_ABOUT CM_MENU_ABOUT (depr.) | Menu command: About... |
0x780 | CM_MODE_CHANGE | Notify Mode Change (see MO_notifyModeChange). |
0x781 | CM_SWITCH_GRAPH | Notify Switch Graph (this message is sent to "Graph", "Window Editor", "Table" and "Y=Editor" applications only). This event is used when the user switches between graphs in two-graph mode. |
0x782 | CM_DEFAULTS | This command is sent when Reset->RAM->Default is executed in the MEMORY screen. Applications should revert to default settings. |
0x790 | CM_BACKGROUND | This command is sent to applications which have a special flag set in their ACB (Application Control Block). It is a very low priority message and is generally used for background processing. |
0x7C0 | CM_OPEN_SYSDATA CM_GEOMETRY (depr.) | Geometry Open Data. |
0x7C0 - 0x7FF |  | Used especially by AMS 1.xx to communicate between applications. This command has been largely replaced by using application frames on AMS 2.xx |
0x800 | CM_FIRST_APP_STRING |  |
0x800 - 0xFFF |  | On AMS 2.xx, applications store pointers to their strings in a frame. Messages in the range from 0x800 - 0xFFF are reserved for the active application's strings. For more information, see XR_stringPtr. |


MO_OPTIONS

MO_OPTIONS Type (Structure)
events.h

typedef struct {
unsigned short CurrentFolder;
unsigned short SplitScreen;
unsigned short NumGraphs;
unsigned short Graph1; /* Graph mode for first application */
unsigned short Graph2; /* Graph mode for second application */
unsigned short Split1App;
unsigned short Split2App;
unsigned short SplitRatio;
unsigned short Angle;
unsigned short ExactApprox;
unsigned short Fix; /* Display Digits */
unsigned short Exp; /* Exponential Form */
unsigned short Vector;
unsigned short Complex;
unsigned short Pretty;
unsigned short Base;
unsigned short UnitSystem;
unsigned short CustomUnits;
} MO_OPTIONS;

A structure containing all system mode settings.

MO_OPTIONS is a structure which contains all system mode settings. All fields in this structure are in fact indices of appropriate menu options in the "MODE" dialog. The only exceptions are fields Split1App and Split2App: they contains task ID numbers of the appropriate applications.

See also: ModeSettings, MO_option, MO_currentOptions, MO_digestOptions


MoNotifyFlags

MoNotifyFlags Type (Enumeration)
events.h

typedef enum MoNotifyFlags {
MO_NOTIFY_FOLDER = 0x0001, MO_NOTIFY_GRAPH_COUNT = 0x0002, MO_NOTIFY_GRAPH_TYPE_1 = 0x0004, MO_NOTIFY_GRAPH_TYPE_2 = 0x0008, MO_NOTIFY_SPLIT = 0x0010, MO_NOTIFY_ANGLE = 0x0020, MO_NOTIFY_PRECISION = 0x0040, MO_NOTIFY_FIX = 0x0080, MO_NOTIFY_NUMBER_FORMAT = 0x0100, MO_NOTIFY_VECTOR_FORMAT = 0x0200, MO_NOTIFY_COMPLEX_FORMAT = 0x0400, MO_NOTIFY_PRETTY_PRINT = 0x0800, MO_NOTIFY_UNIT_SYSTEM = 0x1000, MO_NOTIFY_BASE = 0x2000, MO_NOTIFY_LANGUAGE = 0x4000, MO_NOTIFY_DESKTOP = 0x8000
} MoNotifyFlags;

Enumerates notify messages for the MO_notifyModeChange function.

Enumerates notify messages for the MO_notifyModeChange function. The meaning of these flags is given in MO_notifyModeChange.

See also: MO_notifyModeChange


PaintFlags

PaintFlags Type (Enumeration)
events.h

enum PaintFlags {PAINTING_ENABLED = 0, PAINTING_SUSPENDED = 2};

An enumeration describing whether painting is suspended or enabled.

PaintFlags is an enumeration which describes the constants used in the EV_suspendPainting and EV_restorePainting functions.


ST_ACTIVITIES

ST_ACTIVITIES Type (Enumeration)
events.h, statline.h

enum ST_ACTIVITIES {ACTIVITY_IDLE, ACTIVITY_BUSY, ACTIVITY_PAUSED, ACTIVITY_NORMAL};

Contains status bar activity flags.

ST_ACTIVITIES is enumerated type which contains some alias names known from DoorsOS.


StandardTaskIDs

StandardTaskIDs Type (Enumeration)
events.h

enum StandardTaskIDs {AP_NULL = -3, AP_RUNNING = -2, AP_CURRENT = -1};

An enumeration describing task ID constants.

StandardTaskIDs is an enumeration which describes standard task "magic" numbers which works independently of actual task ID numbers, so they are AMS-independent (see EV_sendEvent).

"Running" application is the application which has an attached and activated toolbar menu (this does not need to be equal to "Current" application). "Null" application is special value used for overriding CM_WPAINT block (see EV_sendEvent).

See also: MO_sendQuit


StartTypes

StartTypes Type (Enumeration)
events.h

enum StartTypes {...};

A pseudo-enumeration describing start types for EV_startTask.

StartTypes is a pseudo-enumeration which describes standard "start types" used in the EV_startTask command, on such way to be compatible with all AMS versions. It is defined using macros, but it behaves as it is defined as

enum StartTypes {AP_START_CURRENT = 0x00, AP_START_NEW = 0x10,
AP_START_OPEN = 0x20, AP_START_ERROR = 0x30};
on AMS 1.xx, and
enum StartTypes {AP_START_CURRENT = 0, AP_START_NEW = 1,
AP_START_OPEN = 2, AP_START_ERROR = 3};
on AMS 2.xx.


SystemDataTypes

SystemDataTypes Type (Enumeration)
events.h, vat.h

enum SystemDataTypes {SDT_EXPR = 0, SDT_LIST = 1, SDT_MAT = 2, SDT_FUNC = 3, SDT_PRGM = 4, SDT_PIC = 5, SDT_STR = 6, SDT_TEXT = 7, SDT_GDB = 8, SDT_DATA = 9, SDT_FIG = 10, SDT_MAC = 11, SDT_OTH = 12, SDT_SYS = 13, SDT_ALL = 14, SDT_ASM = 15};

Describes valid variable types in the "Var-Link" dialog, and for the GetDataType and SmapTypeStrings functions.

See also: GetDataType, SmapTypeStrings, handleVarLinkKey


WIN_RECT

WIN_RECT Type (Structure)
events.h, graph.h, statline.h, textedit.h, wingraph.h, unknown.h

typedef struct {
short x0, y0, x1, y1;
} WIN_RECT;

A structure for defining a rectangular area.

WIN_RECT is a scructure for defining a rectangular area using logical screen coordinates.

Note: GCC4TI is derived from GNU C, so it allows cast constructors. That's why constructions like

WinOpen (&w, &(WIN_RECT){30, 30, 130, 80}, WF_SAVE_SCR);
are legal. See WinOpen for info about this command.


WinFlags

WinFlags Type (Enumeration)
events.h, wingraph.h

enum WinFlags {WF_SYS_ALLOC = 0x0001, WF_STEAL_MEM = 0x0002, WF_DONT_REALLOC = 0x0004, WF_ROUNDEDBORDER = 0x0008, WF_SAVE_SCR = 0x0010, WF_DUP_SCR = 0x0020, WF_TTY = 0x0040, WF_ACTIVE = 0x0080, WF_NOBORDER = 0x0100, WF_NOBOLD = 0x0200, WF_DUP_ON = 0x0400, WF_VIRTUAL = 0x0800, WF_TITLE = 0x1000, WF_DIRTY = 0x2000, WF_TRY_SAVE_SCR = 0x4010, WF_VISIBLE = 0x8000};

An enumeration for describing flags which control the window manager.

These flags are used in the WinOpen command. Usage of some of them are still not very clear to me. See WinOpen to see what I know about them (any additional info is welcomed).

WF_DIRTY and WF_VISIBLE are used in event driven applications, see EV_paintOneWindow function.


files.h

files.h Header File
Header File Index

Routines for accessing files (needs AMS 2.00 or later)

This set of routines (available only in AMS 2.00 or later) gives the possibility of managing custom type files.

They give a 'higher' level way for managing custom type symbols in the Variable Allocation Table than the routines in vat.h.

They can in any case be used in conjunction with the vat.h routines.

However, files.h routines are different from the file routines contained in stdio.h. First of all, they do not use the same files structures. Moreover, stdio.h file functions are GCC4TI library functions working with any AMS versions while files.h functions are AMS (TIOS) functions which are only available under AMS 2.00 and later. They do have the advantage of not requiring extra code in your program, unlike stdio.h.

Therefore the following routines must never be used with stdio.h file routines for the same file stream at the same time.

Functions
FAccess
Check to see if a file can be opened for a given mode without modifying the file.
FClose
Close a file.
FCreate
Create an empty file.
FDelete
Deletes a file.
FEof
Returns TRUE if a file is at the end.
FFindFirst
Find the first file of a given type.
FFindNext
Find the next symbol as set up by a call to FFindFirst.
FGetC
Read a byte from an open file.
FGetPos
Return the current file position.
FGetSize
Return the number of bytes currently stored in an opened file.
FOpen
Open a file for a specific mode.
FPutC
Write a byte to a file opened in write mode.
FRead
Read a given number of bytes from an open file.
FSetBufSize
Set the buffer size of a file.
FSetPos
Set the position of the next read or write for an opened file.
FSetSize
Truncate the size of a file opened in write mode.
FSetVer
Change the version number of an opened file.
FStatus
Return the status of a file.
FType
Gives the type of a specified file.
FWrite
Write a specified number of bytes to a file.
Predefined Types
fileMode
An enumeration for describing possible file modes.
FILES
A structure for defining a file.
FileStatusEnum
An enumeration for describing possible file statuses.
FindOptions
Describes options for SymFindFirst and FFindFirst.
HSym
A structure representing a symbol reference.
SYM_ENTRY
A structure representing a VAT symbol entry.

See also: stdio.h, vat.h


FAccess

FAccess Function (ROM Call 0x3D4)
AMS 2.00 or higher files.h

unsigned short FAccess (const char *fileName, unsigned short mode, const char *typeName);

Check to see if a file can be opened for a given mode without modifying the file.

FAccess checks to see if the file fileName can be opened for the given mode mode without modifying the file first. The file, if it exists, must have the same type as typeName. fileName and typeName are normal zero-terminated C strings (i.e. you do not have to tokenize them).

mode is the given mode to be checked. This parameter can either be FM_READ_ACCESS or FM_WRITE_ACCESS.

typeName is a string which gives the type of the file to open. typeName is a normal-zero terminated C string which must contain one to four characters.

The value returned by FAccess is one of the following, as described in the FileStatusEnum enum:
FS_OK | The file can be opened in the given mode.
FS_ERROR | The file cannot be opened for the specified mode. (It may be locked or not of custom (OTH) data-type.)
FS_NOT_FOUND | fileName does not exist.
FS_BAD_NAME | fileName is invalid.

Uses: FOpen

See also: FOpen, FCreate


FClose

FClose Function (ROM Call 0x3D5)
AMS 2.00 or higher files.h

unsigned short FClose (FILES *fsPtr);

Close a file.

FClose closes the file fsPtr. This is required for files opened in WRITE mode. For files in READ mode, FClose just updates the fsPtr->fileMode and fsPtr->fileStatus fields in the FILES structure.

fsPtr is a pointer to a FILES structure that was previously opened with FOpen.

FClose returns FS_OK if the file was successfully closed. There is extra overhead required for a file that is always kept around by the file system and so closing a file will only return an error if the file or the heap has been damaged.

Uses: HeapRealloc, HeapSize, strlen, DerefSym
Used by: FCreate

See also: FAccess, FOpen, FStatus


FCreate

FCreate Function (ROM Call 0x3D6)
AMS 2.00 or higher files.h

unsigned short FCreate (const char *fileName, const char *typeName);

Create an empty file.

FCreate creates an empty file with the name fileName and the type typeName. It is normally only needed if multiple files must be simultaneously opened in write mode. Filename is not a tokenized variable name (as required by the symbol table code) but rather a normal zero-terminated C string of characters. It must not be a reserved name. If filename does not contain a folder name, the file will be stored in the current folder. Internally, files are stored as custom (third-party) data type files (i.e. they are defined with the OTH_TAG). They will show up to the user in the VAR-LINK screen as the type specified when the FILE was opened (up to four letters).

typeName must point to a normal zero-terminated C string of at most four characters which describes the file type (FS_ERROR is returned if it does not).

FCreate returns one of the following values, as described in the FileStatusEnum enum:
FS_OK | The file was opened for the specified mode.
FS_ERROR | The file cannot be opened for the specified mode. (It may be locked or not of custom (OTH) data-type.)
FS_BAD_NAME | fileName is invalid.
FS_MEMORY | Not enough memory.

Uses: FClose, FOpen

See also: FClose, FOpen


FDelete

FDelete Function (ROM Call 0x3D7)
AMS 2.00 or higher files.h

unsigned short FDelete (const char *fileName);

Deletes a file.

FDelete deletes the file fileName. fileName is a normal zero-terminated C string (i.e. it musn't be tokenized).
Note: FDelete may invalidate any current HSyms.

FDelete may return one of the following values as described in the FileStatusEnum enum:
FS_OK | File deleted.
FS_BAD_NAME | Bad filename.
FS_ERROR | File not deleted because it is locked, in use, a folder, in Flash, or it does not exist.

Uses: TokenizeName, DerefSym, HSymDel, VarRecall

See also: FCreate


FEof

FEof Function (ROM Call 0x3D8)
AMS 2.00 or higher files.h

short FEof (FILES *fsPtr);

Returns TRUE if a file is at the end.

FEof returns TRUE if the file fsPtr is at the end of File mark, and FALSE otherwise. fsPtr must be a pointer to a FILES structure opened with FOpen.

Note that this is not an error condition (as returned by FStatus) and can be changed not only by reading from a file but also by changing the current file position.

See also: FOpen, FSetPos, FGetPos


FFindFirst

FFindFirst Function (ROM Call 0x3D9)
AMS 2.00 or higher files.h

SYM_ENTRY *FFindFirst (unsigned short Options, const char *typeName, const char *folderName);

Find the first file of a given type.

FFindFirst finds the first file of the type typeName and returns a SYM_ENTRY pointer to it (or NULL if none found). typeName must point to a normal zero-terminated C string (i.e. not a tokenized form) of at most four characters which describes the file type. Use FFindNext to find subsequent entries, NULL will be returned after the last entry is found.

Options can be one of the following flags as described in the FindOptions enum:
FO_NONE | When this flag is set, folderName is a string pointer to the folder to search.
FO_RECURSE | When this flag is set, FFindFirst searches all folders (folderName is ignored).

FFindFirst returns a SYM_ENTRY pointer to the first file with a type matching typeName or NULL if none found. The Name field of the SYM_ENTRY contains the name of the file being searched for as an 8 character string. If using FO_RECURSE, then calling SymFindFolderName will return the folder of the symbol just found.

Note: SYM_ENTRY pointers are only valid until heap compression is done or another symbol is added to the symbol table.

Uses: FFindNext, HToESI, strcmp, strlen, ROM Call 0x3E8, StrToTokN, SymFindFirst

See also: FFindNext, SymFindFolderName


FFindNext

FFindNext Function (ROM Call 0x3DA)
AMS 2.00 or higher files.h

SYM_ENTRY *FFindNext (void);

Find the next symbol as set up by a call to FFindFirst.

FFindNext finds the next symbol as set up by a call to FFindFirst and returns a SYM_ENTRY pointer to it, or NULL if no more symbols can be found.
The pointer returned by FFindNext is a SYM_ENTRY pointer to a file with a type matching the one set up by a previous call to FFindFirst. If using FO_RECURSE, then calling SymFindFolderName will return the folder of the symbol just found.
Note that FFindFirst must have been called previously to find the first symbol.

Note: SYM_ENTRY pointers are only valid until heap compression is done or another symbol is added to the symbol table.

Uses: HToESI, strcmp, ROM Call 0x3E8, SymFindNext
Used by: FFindFirst

See also: FFindFirst, SymFindFolderName


FGetC

FGetC Function (ROM Call 0x3DB)
AMS 2.00 or higher files.h

unsigned short FGetC (FILES *fsPtr);

Read a byte from an open file.

FGetC reads a byte from the open file fsPtr (which may be opened in either READ or WRITE mode) at the current file position and returns the byte, or FS_EOF if the end of file was reached.
fsPtr is a pointer to a FILES structure previously opened with FOpen.

Note that the FILES structure pointed to by fsPtr must have been opened with FOpen.

FGetC returns the next byte in the file, or FS_EOF if the end of file has been reached.

Used by: FRead

See also: FOpen, FPutC, FRead, FSetPos


FGetPos

FGetPos Function (ROM Call 0x3DC)
AMS 2.00 or higher files.h

unsigned short FGetPos (FILES *fsPtr);

Return the current file position.

FGetPos returns the current file position (where the next read or write would occur) for the file pointed to by fsPtr.fsPtr is a pointer to a FILES structure previously opened with FOpen.

Note that the FILES structure pointed to by fsPtr must have been previously opened with FOpen.

FGetPos returns the current file position.

See also: FOpen, FSetPos, FEof


FGetSize

FGetSize Function (ROM Call 0x3DD)
AMS 2.00 or higher files.h

unsigned short FGetSize (FILES *fsPtr);

Return the number of bytes currently stored in an opened file.

FGetSize returns the number of bytes currently stored in the opened file fsPtr.

The FILES structure pointed to by fsPtr must have been previously opened with FOpen (either in read or in write mode).

See also: FOpen, FSetSize


FOpen

FOpen Function (ROM Call 0x3DE)
AMS 2.00 or higher files.h

unsigned short FOpen (const char *fileName, FILES *fsPtr, unsigned short mode, const char *typeName);

Open a file for a specific mode.

FOpen opens the file fileName for the mode mode. fileName is not a tokenized variable name (as required by the symbol table code), but rather a normal zero-terminated C string of characters. It must not be a reserved name. If fileName does not contain a folder name, the file will be stored in (or read from) the current folder. Internally, files are stored as custom (third-party) data-type files (OTH_TAG). They will show up to the user in the VAR-LINK screen as the type specified when the file was opened (up to four letters).

When a file is opened with FOpen in FM_WRITE or FM_APPEND mode, the associated variable is locked and inaccessible by any other routines in the system. It must be closed with FClose to return the variable to a not-in-use mode, to write the file type and the OTH_TAG, and to close the associated buffer. For files opened in FM_READ mode, the call to FClose will merely update the mode of the file in the FILES structure to closed and clear the associated error status.

There is no separate mode to open a file for both reading and writing. However, if a file is opened in FM_APPEND mode, the contents of the file are not erased and the file may be subsequently positioned to any location in the file (random access) and either read from or written to. For all access modes, the given name must not be a system variable. For FM_READ and FM_APPEND the name must correspond to an existing file of a custom data-type. For FM_WRITE the file must either not exist or correspond to a file of a custom data-type which is not locked or marked in-use.

Note that for files in read mode, FClose merely updates the fsPtr->fileMode field in the FILES structure to indicate it is closed. For write mode, it must be called to update information in the file needed by the system. While a file is in write mode, it is marked as in-use so that no other application, nor the system itself, will try to access it (it will not be visible in the VAR-LINK screen either). Files in write or append mode may be accessed randomly by using FSetPos.

Note: Any number of files may be simultaneously opened in read mode. If multiple files are opened simultaneously in write (or append) mode, all but the first file must already exist before they are opened. Use the FCreate routine if they need to be created as empty files before they are opened with FOpen.

typeName must point to a normal (non-tokenized) zero-terminated C string of at most four characters which describes the file type (FS_ERROR is returned if it does not). If there is an existing file with the same name as fileName, the types must match.

fsPtr is a pointer to a structure of type FILES.

The parameter mode can be one of the following commands, as described in the fileMode enum:
FM_READ | The file must exist and can only be read.
FM_WRITE | Open the file for writing and erase its contents. Create the file if it does not exist.
FM_APPEND | If the file exists, open it for writing at the end of the file. If it does not exist, then create it and open it for writing.

FOpen returns one of the following values as described in the FileStatusEnum enum:
FS_OK | The file was opened for the specified mode.
FS_ERROR | The file cannot be opened for the specified mode. (It may be locked or not of custom (OTH) data-type, or typeName may be invalid.)
FS_BAD_NAME | fileName is invalid.
FS_MEMORY | Not enough memory.

The return value is also stored in fsPtr->fileStatus in the FILES structure.
The FILES pointer fsPtr may then be used in subsequent file routines.

This routine may cause heap compression or invalidate any current HSyms.

Uses: ER_catch, ER_success, HToESI, memset, strcmp, strlen, ROM Call 0x3E8, TokenizeName, DerefSym, VarRecall, VarStore
Used by: FAccess, FCreate, FType

See also: FAccess, FClose, FRead, FGetC, FSetPos, FStatus, FWrite, FPutC


FPutC

FPutC Function (ROM Call 0x3DF)
AMS 2.00 or higher files.h

unsigned short FPutC (short byte, FILES *fsPtr);

Write a byte to a file opened in write mode.

FPutC writes the byte byte to the file fsPtr opened in write mode at the current file position. The FILES structure pointed to by fsPtr must have been opened with FOpen in write mode.

FPutC returns FS_OK if successful, FS_ERROR if the file is not opened for write mode or FS_MEMORY if the system is out of memory.

Note: Any error will cause the file status to be set to FS_ERROR so that multiple writes may be performed without checking the return status as long as an FStatus is done at the end to make sure all of the writes were successful.

This routine may cause heap compression.

Uses: HeapRealloc, HeapSize
Used by: FWrite

See also: FOpen, FGetC, FWrite, FSetPos, FStatus


FRead

FRead Function (ROM Call 0x3E0)
AMS 2.00 or higher files.h

unsigned short FRead (void *buffer, unsigned short bytesToRead, FILES *fsPtr);

Read a given number of bytes from an open file.

FRead reads bytesToRead bytes from the open file fsPtr (which may be opened in either read or write mode) into buffer. fsPtr must be a pointer to a FILES structure previously opened with FOpen. buffer must be a pointer to a buffer at least bytesToRead bytes long.

FRead returns FS_OK if the file read was successful or FS_EOF if it read past the end of the file.

Uses: FGetC

See also: FOpen, FWrite, FGetC, FSetPos


FSetBufSize

FSetBufSize Function (ROM Call 0x3E2)
AMS 2.00 or higher files.h

unsigned short FSetBufSize (FILES *fsPtr, unsigned short newBufSize);

Set the buffer size of a file.

FSetBufSize sets the buffer size of the file fsPtr to a new one: newBufSize. The buffer size determines how much memory is reallocated to the file every time a write needs more memory from the heap. The default size (128 bytes) is set when the file is opened and should be sufficient for most uses. Setting a larger value will make writes faster but at the cost of possibly prematurely running out of memory.

FSetBufSize returns the value stored in newBufSize.

See also: FOpen, FWrite


FSetPos

FSetPos Function (ROM Call 0x3E1)
AMS 2.00 or higher files.h

unsigned short FSetPos (FILES *fsPtr, unsigned short pos);

Set the position of the next read or write for an opened file.

FSetPos sets the position pos of the next read or write for the opened file fsPtr and returns the new position (which may be less than specified if the end of the file is exceeded). fsPtr must be a pointer to a FILES structure previously opened with FOpen.

pos is the file position (0 being the first byte in the file) to set.

See also: FOpen, FGetPos, FEof


FSetSize

FSetSize Function (ROM Call 0x3E3)
AMS 2.00 or higher files.h

unsigned short FSetSize (FILES *fsPtr, unsigned short fileSize);

Truncate the size of a file opened in write mode.

FSetSize truncates the size of the file opened in write mode to fileSize, which may not exceed the current file size. Return the new file size, but no more than the current size. Note that in read mode, the current file size is always returned without making any changes. fsPtr must be a pointer to a FILES structure previously opened with FOpen for writing.

See also: FOpen, FGetSize


FSetVer

FSetVer Function (ROM Call 0x3E4)
AMS 2.00 or higher files.h

unsigned char FSetVer (FILES *fsPtr, unsigned char newVer);

Change the version number of an opened file.

FSetVer changes the version number of the opened file fsPtr to the new one newVer and returns the old version number. Note that the file can be in read or write mode. fsPtr is a pointer to a FILES structure previously opened with FOpen in either read or write mode. The version number of a file is stored in the file’s symbol table entry. It is a byte and is used internally by TIOS to verify that a newer version of a symbol is not sent to an older TI-89, TI-92, or TI-92 Plus.

Uses: DerefSym

See also: FOpen


FStatus

FStatus Function (ROM Call 0x3E5)
AMS 2.00 or higher files.h

unsigned short FStatus (FILES *fsPtr);

Return the status of a file.

FStatus returns the status of the file fsPtr: FS_OK if no errors have occurred, or FS_ERROR if any errors have occurred. Note that errors accumulate so that multiple writes may be done on a file as long as the status is checked after the last write. The only way to clear the status is to close the file.

fsPtr must be a pointer to a FILES structure previously opened with FOpen.

See also: FOpen, FClose, FWrite, FPutC


FType

FType Function (ROM Call 0x3E6)
AMS 2.00 or higher files.h

unsigned short FType (const char *fileName, char *buf);

Gives the type of a specified file.

FType writes the type of the file fileName into the buffer buf as a zero-terminated string. The buffer should be a least 5 bytes long (four bytes + a zero terminating byte). fileName file must not be opened for write mode.

FType can return one of the following values as enumerated in the FileStatusEnum enum:
FS_OK | Ftype successfully wrote the type of the file into buf.
FS_ERROR | An error occured while opening the file, or the file was opened successfully, but the type field is invalid.
FS_BAD_NAME | fileName is invalid.

Note that FType will always fail if the given file is already opened for write mode.

Uses: FOpen, HToESI, ROM Call 0x3E8

See also: FOpen


FWrite

FWrite Function (ROM Call 0x3E7)
AMS 2.00 or higher files.h

unsigned short FWrite (const void *buffer, unsigned short bytesToWrite, FILES *fsPtr);

Write a specified number of bytes to a file.

FWrite writes bytesToWrite bytes of data from the buffer buffer to the output file associated with the FILES structure pointed to by fsPtr. The data written begins at the current file position. buffer is a pointer to any object.

FWrite returns one of the following values as enumerated in the FileStatusEnum enum:
FS_OK | The write was successful.
FS_ERROR | The file fsPtr is not opened in write mode.
FS_MEMORY | Out of memory.

Note: Any error will cause the file status to be set to FS_ERROR so that multiple writes may be performed without checking the return status as long as an FStatus is done at the end to make sure all of the writes were successful.

Uses: FPutC

See also: FOpen, FPutC, FRead, FClose


fileMode

fileMode Type (Enumeration)
files.h

enum fileMode {
FM_CLOSED=0, FM_READ=1, FM_WRITE=2, FM_APPEND=3, FM_READ_ACCESS=1, FM_WRITE_ACCESS=4
};

An enumeration for describing possible file modes.

These constants describe the file modes stored in the FILES structure and needed by nearly every files.h function.


FILES

FILES Type (Structure)
files.h

typedef struct fileStruct {
unsigned short dataLen;
unsigned short dataPos;
unsigned short bufSize;
HANDLE dataH;
unsigned char fileFlags, fileMode;
unsigned short fileStatus;
HSym hSym;
char type[5];
} FILES;

A structure for defining a file.

fileStruct is a structure for defining a file, used in commands like FOpen.


FileStatusEnum

FileStatusEnum Type (Enumeration)
files.h

enum FileStatusEnum {FS_OK = 0x0000, FS_EOF = 0xFFFF, FS_ERROR = 0xFFFE, FS_BAD_NAME = 0xFFFD, FS_MEMORY = 0xFFFC, FS_NOT_FOUND = 0xFFFB};

An enumeration for describing possible file statuses.

These constants describe the file status codes stored in the FILES structure and returned by nearly every files.h function.


FindOptions

FindOptions Type (Enumeration)
vat.h, files.h

enum FindOptions {FO_SINGLE_FOLDER = 0x01, FO_RECURSE = 0x02, FO_SKIP_TEMPS = 0x04, FO_NOTEMPS = 0x04, FO_RETURN_TWINS = 0x08, FO_CKTWINS = 0x08, FO_RETURN_FOLDER = 0x10, FO_SKIP_COLLAPSE = 0x20};

Describes options for SymFindFirst and FFindFirst.

FindOptions is an enumeration describing flags for SymFindFirst and FFindFirst. They can be combined with the '|' operator.


SYM_ENTRY

SYM_ENTRY Type (Structure)
vat.h, files.h, unknown.h

typedef struct {
char name[8];
unsigned short compat;
union {
unsigned short flags_n;
struct {
unsigned int busy : 1, local : 1, flag1_5 : 1, flag1_4 : 1, collapsed : 1, twin : 1, archived : 1, in_view : 1;
unsigned int folder : 1, overwritten : 1, checked : 1, hidden : 1, locked : 1, statvar : 1, graph_ref_1 : 1, graph_ref_0 : 1;
} bits;
} flags;
HANDLE handle;
} SYM_ENTRY;

A structure representing a VAT symbol entry.

Principally, SYM_ENTRY consists of the symbol name, the flags, and the handle associated with the symbol. The flags are defined as a union, so you can access to all flags together using the field flags_n (in such case, constants defined in the enum SymFlags may be useful for bit masking), or access to individual flags (which are defined as bit fields) using the field bits. Some flags are unused, and some flags have an unknown meaning. At the moment, the known flags are: locked (set for locked symbols), hidden (set for symbols which are hidden for the TI-Basic; in fact, "hidden" files are files which are currently opened, i.e. in-use files), checked (set for symbols which are checked in VAR-LINK dialog), folder (set for folder entries), collapsed (set for collapsed folders; this makes sense only on AMS 2.xx), archived (set for archived symbols), twin (set for twin symols, see SymAddTwin), and local (set for local symbols). For example, if "SymPtr" is the pointer to the VAT symbol entry, the following command makes this symbol invisible for TIOS:

SymPtr->flags.bits.hidden = 1;
Note that the twin bit may only be set if the symbol is really a twin symbol, i.e. an entry with the same name exists. Otherwise, the system will crash upon the next call to SymAdd.

The handle field always contains a handle to a MULTI_EXPR structure. It must contain valid data for the operating system to operate properly.

Each symbol has also associated compatibility flag (field compat). It determines how the symbol will behave during sending to unexpanded (non-Plus) TI-92. There are four possible values of the compatibility flag (these constants are defined in enum CompatFlags):

CF_NONE | Sends immediately
CF_CONVERT | Converts and sends
CF_ENHANCED | An enhanced token - may or may not work
CF_NEW | Will not be sent

A compatibilty number of CF_CONVERT or CF_NEW is determined from symbols context. CF_ENHANCED is related mainly for internal tokens, which does not appear in final results and programs.

Here is the list of token tags (see Tags) which belong to CF_CONVERT, CF_ENHANCED and CF_NEW categories:

Convert: | LOCALVAR_TAG
Enhanced: | _VAR_Q_TAG, PN_INFINITY_TAG, tag 0x5F (internal), START_TAG, ISTORE_TAG, ANS_TAG, ENTRY_TAG, MATRIX_TAG, ERROR_MSG_TAG, tags 0xF5, 0xF6 and 0xF7 (internal)
New: | PART_TAG, PN1_TAG, PN2_TAG, EIGVC_TAG, EIGVL_TAG, DASH_TAG, DESOLVE_TAG, FDASH_TAG, ASM_TAG, ISPRIME_TAG, OTH_TAG, ROTATE_TAG, PARENTH_START_TAG, PARENTH_END_TAG, MAT_START_TAG, MAT_END_TAG, LIST_START_TAG, LIST_END_TAG, COMMA_TAG, SEMICOLON_TAG, COMPLEX_ANGLE_TAG, SINGLE_QUOTE_TAG, QUOTE_TAG, POLCPLX_TAG, TMPCNV_TAG, DELTA_TMPCNV_TAG, GETUNITS_TAG, SETUNITS_TAG, BIN_TAG, HEX_TAG, INT2BIN_TAG, INT2DEC_TAG, INT2HEX_TAG, DET_TOL_TAG, REF_TOL_TAG, RREF_TOL_TAG, SIMULT_TOL_TAG, GETCONFG_TAG, V_AUGMENT_TAG, EYE_PSI_TAG, TPLOT_TAG, DIFTOL_TAG, ZEYE_PSI_TAG, T0_TAG, DTIME_TAG, NCURVES_TAG, FLDRES_TAG, ESTEP_TAG, ZT0DE_TAG, ZTMAXDE_TAG, ZTSTEPDE_TAG, ZTPLOTDE_TAG, NCONTOUR_TAG, DISPHOME_ITAG, EXEC_ITAG, ARCHIVE_ITAG, UNARCHIV_ITAG, LU_ITAG, QR_ITAG, BLDDATA_ITAG, DRWCTOUR_ITAG, NEWPROB_ITAG, SINREG_ITAG, LOGISTIC_ITAG, CUSTMON_ITAG, CUSTMOFF_ITAG, SENDCHAT_ITAG

Note: SYM_ENTRY structures are usually not locked, which means that pointers to them will become invalid if a heap compression occurs. Basically, this means that you can only operate on them for a short time in which you know that no heap compression can occur.


flash.h

flash.h Header File
Header File Index

Low-level routines for working with the Flash ROM

Functions
BatTooLowFlash
Checks if the battery level is (or ever was) too low to write to the Flash memory.
EM_abandon
Abandon an archive memory block.
EM_blockVerifyErase
Verifies if an archive block is erased.
EM_findEmptySlot
Finds an empty space in the archive memory of the given size.
EM_GC
Performs garbage collection in the archive memory.
EM_getArchiveMemoryBeginning
Returns a pointer to the first byte of the archive memory area.
EM_survey
Collects some useful information about the archive memory.
EM_write
Writes a block into the extended memory.
FL_addCert
Adds a certificate.
FL_download
Installs the product code.
FL_getCert
Gets a certificate.
FL_getHardwareParmBlock
Gets a pointer to the hardware parameter block.
FL_getVerNum
Gets a Flash ROM verification number.
FL_write
Writes a block into the Flash ROM.
Global Variables
CappedHW1ArchiveMemoryBeginning
The address where AMS 2.xx and 3.xx cap the beginning of the archive memory on HW1 calculators.
FlashMemoryEnd
A pointer to the first byte after the end of the archive memory.
Constants
FLASH_SECTOR_SIZE
Size of a Flash sector.
NULL
A null-pointer value.
Predefined Types
Bool
An enumeration to describe true or false values.
HANDLE
Represents a handle associated with an allocated memory block.
HARDWARE_PARM_BLOCK
Structure describing the calculator hardware.
size_t
A type to define sizes of strings and memory blocks.

Note: The functions EM_blockErase, EM_blockVerifyErase, EM_delete, EM_writeToExtMem, EM_open, and EM_put, which were present in the AMS 1.xx TIOS jump table, don't exist in the AMS 2.xx TIOS jump table any more. This is a pity; some of them were useful (especially the last three of them).
In AMS 2.xx: EM_blockErase is replaced by: OSFastArrows.
EM_delete is replaced by: AB_getGateArrayVersion.
EM_open is replaced by: SetAlphaStatus.
EM_put is replaced by: GetAlphaStatus.
It seems that EM_writeToExtMem was simply removed, and there is no function replacing it.

In addition to the functions defined here, three other functions which work with the archive memory are defined in the vat.h header file: EM_moveSymFromExtMem, EM_moveSymToExtMem and EM_twinSymFromExtMem. Maybe these functions are the most useful functions for working with the archive memory. They are defined in vat.h because they are related to other functions and data structures defined in that header file.


BatTooLowFlash

BatTooLowFlash Function (ROM Call 0x434)
AMS 2.00 or higher flash.h

short BatTooLowFlash (unsigned short delay);

Checks if the battery level is (or ever was) too low to write to the Flash memory.

BatTooLowFlash returns TRUE if the battery level is (or ever was) too low to write to the Flash memory, and FALSE otherwise. If delay is non-zero, and USER_TIMER is not already in use, a delay of delay will occur before any checking is done.

For information about USER_TIMER, see OSRegisterTimer.

Uses: OSFreeTimer, OSRegisterTimer, OSTimerExpired, ST_flags
Used by: LIO_Receive, OSLinkCmd


EM_abandon

EM_abandon Function (ROM Call 0x15B)
flash.h

void EM_abandon (HANDLE h);

Abandon an archive memory block.

EM_abandon abandons an archive memory block associated with handle h. More precise, it frees the handle by clearing the entry in the heap table, and precedes memory block with flag which indicate that the block is free.

Note: Functions like EM_blockErase are removed in AMS 2.xx to increase the life of the Flash ROM. Really, it is not necessary to erase a block psyhically. It is quite enough to mark it as "deleted", and it will be eventually simply be rewritten later.

Uses: EM_write, EM_getArchiveMemoryBeginning
Used by: LIO_Receive, OSLinkCmd, FolderDel


EM_blockVerifyErase

EM_blockVerifyErase Function (ROM Call 0x15D)
flash.h

short EM_blockVerifyErase (void *src);

Verifies if an archive block is erased.

EM_blockVerifyErase returns TRUE if an archive block of 64KB size is erased (i.e filled with 0xFFFFFFFF), and FALSE otherwise. It is used in the reset routine of AMS 2.xx.

Note: This function behaves differently on AMS 1.xx and AMS 2.xx:

  • On AMS 1.xx, src may be anything between 0 and 0x60000; it will be rounded down to the nearest multiple of 0x10000.
  • On AMS 2.xx, src can only be 0x340000, 0x350000, 0x360000, 0x370000, 0x380000, 0x390000, 0x3A0000, 0x3B0000, 0x3C0000, 0x3D0000, 0x3E0000, 0x3F0000. There is no rounding.


EM_findEmptySlot

EM_findEmptySlot Function (ROM Call 0x15F*)
flash.h

void *EM_findEmptySlot (unsigned long Size);

Finds an empty space in the archive memory of the given size.

EM_findEmptySlot returns a pointer to a place in the archive memory which is large enough to store a block which is Size bytes long. It returns NULL if the requirement cannot be satisfied. In such case, a garbage collection (see EM_GC) is recommended, and there is a chance that a next call of EM_findEmptySlot will be successful. If not, there is really not enough space in the archive memory for a block of the given size. Thanks to Johan Eilert for information how this function should be defined to work on both AMS 1.xx and AMS 2.xx.

Note: The pointer returned by EM_findEmptySlot points to the place where the actual block needs to be stored (see EM_write), not to the place where the header of the block should be stored. The header begins 4 bytes before returned value on AMS 1.xx and 22 bytes before returned value on AMS 2.xx. Note that you need to write a header for each stored block if you don't want problems. See EM_write for more info.

Uses: EM_write, EM_getArchiveMemoryBeginning, ROM Call 0x3D1
Used by: EM_moveSymToExtMem


EM_GC

EM_GC Function (ROM Call 0x160)
flash.h

short EM_GC (short allowDialog);

Performs garbage collection in the archive memory.

EM_GC performs garbage collection, i.e. rearranges blocks in the archive memory on such way that all used blocks become contiguous, without free blocks between them. If allowDialog is TRUE, a confirmation dialog will be displayed, and if it is FALSE, the garbage collection will be performed without asking user for the confirmation. EM_GC returns TRUE if garbage collection occured, otherwise it returns FALSE.

Used by: OSLinkCmd, EM_moveSymToExtMem


EM_getArchiveMemoryBeginning

EM_getArchiveMemoryBeginning Function (ROM Call 0x3CF)
AMS 2.00 or higher flash.h

unsigned char * EM_getArchiveMemoryBeginning(void);

Returns a pointer to the first byte of the archive memory area.

This ROM_CALL first calls OO_GetEndOfAllFlashApps and rounds the result up to the next Flash sector boundary (multiple of 64 KB). Then, it calls a subroutine which, on two hardware models, increases the address to artificially reduce the amount of usable archive memory (MaxMem, XPand and tiosmod+amspatch nullify this code):

  • on 89 HW1 and 92+ HW1 running AMS 2.xx, capping to ROM_base+0x190000 (see CappedHW1ArchiveMemoryBeginning) - this is the size hard-coded in AMS 1.xx;
  • on V200, capping to 0x500000 (ROM_base+0x300000).
Finally, it returns the result to the user.

The capping described above can be defeated on both hardware models. This ROM_CALL and OO_GetEndOfAllFlashApps can be used to detect whether the capping was defeated.

Uses: FL_getHardwareParmBlock, AB_getGateArrayVersion, OO_GetEndOfAllFlashApps, CappedHW1ArchiveMemoryBeginning
Used by: HeapShuffle, HeapUnlock, EM_abandon, EM_findEmptySlot, EM_survey, EM_write, ROM Call 0x3CE

See also: OO_GetFirstFlashAppSectorAddress, CappedHW1ArchiveMemoryBeginning


EM_survey

EM_survey Function (ROM Call 0x165)
flash.h

void EM_survey (unsigned long *inUse, unsigned long *freedByGC, unsigned long *free, unsigned long *unusedSectors, unsigned long *badSectors, unsigned long *allExceptBaseCode);

Collects some useful information about the archive memory.

EM_survey collects some useful information about the archive memory and stores them in six variables pointed to by arguments. *inUse is the number of used bytes. *freedByGC is the number of bytes which will be freed by performing garbage collection (see EM_GC). free is the number of free bytes (not counting bytes occupied by "deleted" blocks, which will become "free" only after the garbage collection). *unusedSectors is the number of bytes in "unused" sectors. I don't know why the archive memory contains usually one unused sector (i.e. sector which is never used for archiving purposes). The program called "MoreMem" just marks such unused sectors as "sectors in use" to get more archive memory (?). *badSectors is the number of bytes in bad sectors, but I am not so sure what "bad sectors" really means. *allExceptBaseCode is the number of all bytes in the Flash ROM which are not occupied by TIOS. This argument is new in AMS 2.xx, but you must use six arguments even on AMS 1.xx. If you don't need a particular information, you may pass NULL as the argument. TIOS will see it's a null pointer and will not save anything in it.

TIOS uses only freedByGC and free and always passes NULL to everything else. *freedByGC + *free is used to tell the user how much archive memory is available. Thanks to Johan Eilert for information how EM_survey should be used correctly on both AMS 1.xx and AMS 2.xx.

Uses: FlashMemoryEnd, EM_getArchiveMemoryBeginning, ROM Call 0x3D1, OO_GetFirstFlashAppSectorAddress


EM_write

EM_write Function (ROM Call 0x167)
flash.h

void EM_write (const void *src, void *dest, unsigned long size);

Writes a block into the extended memory.

EM_write is mostly identical as FL_write, except an error will be thrown if dest points out of the archive memory (i.e. user portion of the Flash ROM).

Note: For anybody who wants to write something into the archive memory, the following information may be useful:

  • Blocks in the archive memory are kept in the linked list, but the organization of the list is AMS-dependent (see compat.h header file to see how to check which AMS version is present on the machine). If you don't want problems, you should not write any data to the archive memory which are not organized as described below.
  • Archive memory is divided in sectors which are 64K long. The first word of each sector is the status word, and it cannot be used for storage purposes (-2 means "sector in use", -4 means "full sector", and -1 means "unused sector"). Each block must completely belong to one sector, i.e. it cannot cross over sector boundaries.
  • Before each block is a header. It starts with a flag which may be -4 for deleted blocks, -2 for used blocks and -1 for free blocks (AMS 2.xx uses -32 and -64 instead of -2 and -4, I don't know why; maybe old flags may be used for "noname" files, see below). So, if you need to keep some data in the archive memory for a longer time, it must be marked with -2 (or -32 on AMS 2.xx), otherwise it may be treated by TIOS as "free space".
  • After the flag word, on AMS 2.xx the name of the folder (8 bytes) and the name of the stored file (8 bytes) are stored (both of them are zero padded). After this, yet one word follows (usually set to zero), exact meaning is unknown to me. This extra information (18 bytes) is not present on AMS 1.xx.
  • After this, the next stored word is the size of the block in words increased by 1 and with the topmost bit set. This word is used as a link to the next block. This concludes the block header. Its size is 4 bytes on AMS 1.xx and 22 bytes on AMS 2.xx.
  • Finally, the actual content of the block follows. If a handle is associated with the block, the handle points just here, i.e. to the first byte of the actual content.
Function EM_findEmptySlot may be used for finding an empty space in the archive memory of a given size. Of course, if you are not an experienced programmer, avoid direct writing in the archive memory. Use safe high-level functions like EM_moveSymToExtMem instead.

Uses: FL_write, EM_getArchiveMemoryBeginning
Used by: EM_abandon, EM_findEmptySlot, EM_moveSymFromExtMem, EM_moveSymToExtMem


FL_addCert

FL_addCert Function (ROM Call 0x169)
flash.h

unsigned short FL_addCert (void *src, unsigned long size);

Adds a certificate.

FL_addCert adds size bytes long certificate pointed to by src to the Flash ROM (see cert.h for more info). Returns certificate error code (I don't know too much about its meaning). It is unlikely that this routine may be efficiently used without cooperation with TI.


FL_download

FL_download Function (ROM Call 0x16A)
flash.h

void FL_download (unsigned long dummy);

Installs the product code.

FL_download installs the product code (there is no exit from this routine). It calls startup boot code, reinstates vector table, then enters a receiving loop. It seems that parameter dummy is ignored.

Used by: LIO_Receive


FL_getCert

FL_getCert Function (ROM Call 0x16C)
flash.h

void FL_getCert (HANDLE *hDest, unsigned long *len, short decrypt);

Gets a certificate.

FL_getCert allocates a space in the RAM and stores in it all relevant information which can be collected from the certificate area of Flash ROM (which is read-protected). It stores a handle of allocated space to a variable pointed to by hDest, and stores the length of it in the variable pointed to by len. decrypt is a Boolean parameter, which determines whether the crypted part of the certificate will be stored or not (it will be decrypted before storing, so crypted parts of the certificate are always invisible). See cert.h header file for more info.


FL_getHardwareParmBlock

FL_getHardwareParmBlock Function (ROM Call 0x16B*)
flash.h

const void *FL_getHardwareParmBlock (void);

Gets a pointer to the hardware parameter block.

FL_getHardwareParmBlock returns a pointer to a HARDWARE_PARM_BLOCK structure describing the hardware. If the parameter block of the boot code is not found, it returns the address of the default parameter block.

Used by: OSInitBetweenKeyDelay, LIO_Receive, OSLinkCmd, AB_getGateArrayVersion, EM_getArchiveMemoryBeginning, ROM Call 0x473


FL_getVerNum

FL_getVerNum Function (ROM Call 0x16D)
flash.h

unsigned short FL_getVerNum (void);

Gets a Flash ROM verification number.

FL_getVerNum returns the encrypted Flash ROM verification number from the Flash ROM certificate.

Used by: LIO_Receive, AB_serno, LIO_SendIdList


FL_write

FL_write Function (ROM Call 0x171)
flash.h

void FL_write (const void *src, void *dest, unsigned long size);

Writes a block into the Flash ROM.

FL_write writes a size bytes long block which begins at address pointed to by src (RAM or Flash memory) into the Flash ROM at the address dest. Writing is allowed only to the user portion of the Flash ROM (also known as "archive memory"), which starts at an address depending on the hardware model and OS version.
The general rule on AMS 2.xx and 3.xx is that storage for FlashApps starts at the first sector boundary after the end of the OS, and that the archive memory starts at the first sector boundary after the end of the FlashApps. There is always at least one sector for FlashApps, even if it's empty. See EM_getArchiveMemoryBeginning for the exceptions to this general rule.
User portion of the Flash ROM ends at 0x400000 (TI-89), 0x600000 (TI-92 Plus, V200) or 0x800000 (TI-89T). Any attempt to write something out of this region will be ignored. Attempts to read the Flash memory (in Protection disabled mode) are, however, not filtered.

Used by: EM_write


CappedHW1ArchiveMemoryBeginning

CappedHW1ArchiveMemoryBeginning Variable (ROM Call 0x43C)
AMS 2.00 or higher flash.h

unsigned char *const CappedHW1ArchiveMemoryBeginning;

The address where AMS 2.xx and 3.xx cap the beginning of the archive memory on HW1 calculators.

This ROM call points to ROM_base+0x190000, i.e. the address where the archive memory starts on HW1 calculators running AMS 2.00+.
This is because AMS 2.00+ versions cap the beginning the archive memory, effectively decreasing the amount of archive memory available to users by 192 or 256 KB (depending on the AMS version).

There's a way around this limitation, see EM_getArchiveMemoryBeginning.

Used by: EM_getArchiveMemoryBeginning

See also: EM_getArchiveMemoryBeginning


FlashMemoryEnd

FlashMemoryEnd Variable (ROM Call 0x43D)
AMS 2.00 or higher flash.h

unsigned char *const FlashMemoryEnd;

A pointer to the first byte after the end of the archive memory.

FlashMemoryEnd can be used in a function reading the archive memory like this:

void ReadSomethingInArchive(unsigned char *start)
{
  unsigned char *end = FlashMemoryEnd;
  for (; start < end; start++)
    {
      // Read something here...
    }
}

Used by: EM_survey, AB_prodid, AB_prodname, ROM Call 0x3CE, OO_GetFirstFlashAppSectorAddress

See also: ROM_base


FLASH_SECTOR_SIZE

FLASH_SECTOR_SIZE Constant
flash.h

#define FLASH_SECTOR_SIZE (0x10000)

Size of a Flash sector.

On TI-68k calculators, a flash sector is 64 KB (65536 bytes).


HARDWARE_PARM_BLOCK

HARDWARE_PARM_BLOCK Type (Structure)
flash.h

typedef struct {
unsigned short len; /* length of parameter block */
unsigned long hardwareID; /* 1 = TI-92 Plus, 3 = TI-89, 8 = V200, 9 = TI-89T */
unsigned long hardwareRevision; /* hardware revision number */
unsigned long bootMajor; /* boot code version number */
unsigned long bootRevision; /* boot code revision number */
unsigned long bootBuild; /* boot code build number */
unsigned long gateArray; /* gate array version number */
unsigned long physDisplayBitsWide; /* display width */
unsigned long physDisplayBitsTall; /* display height */
unsigned long LCDBitsWide; /* visible display width */
unsigned long LCDBitsTall; /* visible display height */
} HARDWARE_PARM_BLOCK;

Structure describing the calculator hardware.

The hardware parameter block contains a description of the calculator hardware. This structure is mainly used with the FL_getHardwareParmBlock function.

Some fields of the HARDWARE_PARM_BLOCK structure are not available in earlier versions of the calculator. Only the len and hardwareID fields are available in all boot code versions. It is important to check the value of len before accessing any values after hardwareID. You can use offsetof to determine if a particular field is present.

The TI-89 / 89T and TI-92 Plus / V200 allocate the same amount of memory for the LCD. However, the TI-89 / 89T cannot display as much as the TI-92 Plus / V200. LCDBitsWide and LCDBitsTall reflect how much of the calculator's LCD memory the user can see.

If len is 24 or more, gateArray contains a hardware version number (currently 1 (HW1) or 2 (HW2) for 89, 92+ and V200; 3 (HW3) or 4 (HW4) for 89T). Otherwise, the calculator is certainly a HW1 calculator.

Here is an example (called "Hardware Parameters") which returns the complete hardware parameter block as a list:

// Return the hardware parameter block as a list

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

#define RETURN_VALUE          // Return Pushed Expression
#define MIN_AMS 100           // Compile for AMS 1.00 or higher

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

// Main Function
void _main(void)
{
  const HARDWARE_PARM_BLOCK *hpb = FL_getHardwareParmBlock ();
  const unsigned long *curptr;
  push_END_TAG ();
  for (curptr = (const unsigned long *) &(hpb->hardwareID) + hpb->len / 4 - 1; (unsigned long) curptr > (unsigned long) hpb; curptr--)
    {
      push_quantum (*curptr);
      push_quantum (1);
      push_quantum (POSINT_TAG);
    }
  push_quantum (hpb->len);
  push_quantum (1);
  push_quantum (POSINT_TAG);
  push_LIST_TAG ();
}

See also: FL_getHardwareParmBlock


flashapp.h

flashapp.h Header File
Header File Index

Routines, variables and structures related to FlashApps.

Functions
EV_quit
Switches from the current application to the Home application.
OO_GetEndOfAllFlashApps
Returns a pointer to the first word-aligned byte after the last FlashApp.
OO_GetFirstFlashAppSectorAddress
Fills given CFILE and returns a pointer to the first byte of the first sector reserved for FlashApps.
OO_GetFlashAppSize
Returns the size of a FlashApp given its task ID.
Predefined Types
CFILE
A structure representing the context of a memory-mapped file.

Note: this header is currently VERY incomplete.
On AMS 2.xx and 3.xx, FlashApps enable tighter integration to AMS than ASM programs enable: FlashApps can extend AMS, e.g. by exporting multiple TI-BASIC functions, and override various aspects of AMS (e.g. the language, or the font used by character drawing functions).

GCC4TI cannot currently generate FlashApps, but mixed mode operation with TIFS should be possible.


OO_GetEndOfAllFlashApps

OO_GetEndOfAllFlashApps Function (ROM Call 0x3D2)
AMS 2.00 or higher flashapp.h

unsigned char *OO_GetEndOfAllFlashApps(void);

Returns a pointer to the first word-aligned byte after the last FlashApp.

This function calls OO_GetFirstFlashAppSectorAddress, and then loops through the FlashApps, using the CFILE filled by OO_GetFirstFlashAppSectorAddress.
The first sector after the last sector reserved for FlashApps is the first archive memory sector.

Uses: cread, OO_GetFirstFlashAppSectorAddress
Used by: EM_getArchiveMemoryBeginning


OO_GetFirstFlashAppSectorAddress

OO_GetFirstFlashAppSectorAddress Function (ROM Call 0x4F3)
AMS 2.00 or higher flashapp.h

unsigned char *OO_GetFirstFlashAppSectorAddress(CFILE *certfile);

Fills given CFILE and returns a pointer to the first byte of the first sector reserved for FlashApps.

After execution of this ROM_CALL, certfile contains the following information:

  • certfile->Start = ROM_base+0x12000
  • certfile->Pos = end of AMS code, rounded up to the next multiple of 64 KB (= return value of the ROM_CALL).
  • certfile->End = FlashMemoryEnd
  • certfile->EOFVal = FALSE
At least one 64 KB sector is reserved for FlashApps in the Flash Memory. The first such sector is the first sector after the end of the AMS code.

Uses: copen, cread, FlashMemoryEnd
Used by: EM_survey, OO_GetEndOfAllFlashApps

See also: EM_getArchiveMemoryBeginning, OO_GetEndOfAllFlashApps


OO_GetFlashAppSize

OO_GetFlashAppSize Function (ROM Call 0x477)
AMS 2.00 or higher flashapp.h

unsigned long OO_GetFlashAppSize(short TaskID);

Returns the size of a FlashApp given its task ID.

On AMS 2.xx, the task ID of a FlashApp can be retrieved with EV_getAppID.

Uses: copen, cread
Used by: handleVarLinkKey

See also: EV_getAppID


float.h

float.h Header File
Header File Index

Various platform-dependent floating point constants proposed by ANSI

This header file contains a set of various platform-dependent constants related to floating point values. These constants are proposed by ANSI C. They allow making more portable programs.

Constants
DBL_DIG
Number of significant digits in a floating point number.
DBL_EPSILON
The smallest x for which 1.0+x != 1.0.
DBL_MANT_BITS
Number of bits used for the mantissa.
DBL_MANT_DIG
Number of FLT_RADIX digits in the mantissa.
DBL_MAX_10_EXP
The maximal exponent of a floating point value expressed in base 10 (see notes about FLT_MAX_EXP).
DBL_MAX_2_EXP
The maximal exponent of a floating point value expressed in base 2 (see notes about FLT_MAX_EXP).
DBL_MAX_EXP
The maximal exponent of a floating point value expressed in base FLT_RADIX; greater exponents are principally possible (up to 16383), but not supported in all math functions.
DBL_MAX
The maximal floating point value (see notes about FLT_MAX_EXP).
DBL_MIN_10_EXP
The minimal exponent of a floating point value expressed in base 10 (see notes about FLT_MIN_EXP).
DBL_MIN_2_EXP
The minimal exponent of a floating point value expressed in base 2 (see notes about FLT_MIN_EXP).
DBL_MIN_EXP
The maximal exponent of a floating point value expressed in base FLT_RADIX; smaller exponents are principally possible (up to -16383), but not supported in all math functions.
DBL_MIN
The minimal floating point value (see notes about FLT_MIN_EXP).
FLT_DIG
Number of significant digits in a floating point number.
FLT_EPSILON
The smallest x for which 1.0+x != 1.0.
FLT_MANT_BITS
Number of bits used for the mantissa.
FLT_MANT_DIG
Number of FLT_RADIX digits in the mantissa.
FLT_MAX_10_EXP
The maximal exponent of a floating point value expressed in base 10 (see notes about FLT_MAX_EXP).
FLT_MAX_2_EXP
The maximal exponent of a floating point value expressed in base 2 (see notes about FLT_MAX_EXP).
FLT_MAX_EXP
The maximal exponent of a floating point value expressed in base FLT_RADIX; greater exponents are principally possible (up to 16383), but not supported in all math functions.
FLT_MAX
The maximal floating point value (see notes about FLT_MAX_EXP).
FLT_MIN_10_EXP
The minimal exponent of a floating point value expressed in base 10 (see notes about FLT_MIN_EXP).
FLT_MIN_2_EXP
The minimal exponent of a floating point value expressed in base 2 (see notes about FLT_MIN_EXP).
FLT_MIN_EXP
The minimal exponent of a floating point value expressed in base FLT_RADIX; smaller exponents are principally possible (up to -16383), but not supported in all math functions.
FLT_MIN
The minimal floating point value (see notes about FLT_MIN_EXP).
FLT_NORMALIZE
Indicates that floating point numbers should always be normalized.
FLT_RADIX
The base used for representing the exponent.
FLT_ROUNDS
Option for rounding floating point numbers during the addition.
LDBL_DIG
Number of significant digits in a floating point number.
LDBL_EPSILON
The smallest x for which 1.0+x != 1.0.
LDBL_MANT_BITS
Number of bits used for the mantissa.
LDBL_MANT_DIG
Number of FLT_RADIX digits in the mantissa.
LDBL_MAX_10_EXP
The maximal exponent of a floating point value expressed in base 10 (see notes about FLT_MAX_EXP).
LDBL_MAX_2_EXP
The maximal exponent of a floating point value expressed in base 2 (see notes about FLT_MAX_EXP).
LDBL_MAX_EXP
The maximal exponent of a floating point value expressed in base FLT_RADIX; greater exponents are principally possible (up to 16383), but not supported in all math functions.
LDBL_MAX
The maximal floating point value (see notes about FLT_MAX_EXP).
LDBL_MIN_10_EXP
The minimal exponent of a floating point value expressed in base 10 (see notes about FLT_MIN_EXP).
LDBL_MIN_2_EXP
The minimal exponent of a floating point value expressed in base 2 (see notes about FLT_MIN_EXP).
LDBL_MIN_EXP
The maximal exponent of a floating point value expressed in base FLT_RADIX; smaller exponents are principally possible (up to -16383), but not supported in all math functions.
LDBL_MIN
The minimal floating point value (see notes about FLT_MIN_EXP).

See also: values.h


DBL_DIG

DBL_DIG Constant
float.h

#define DBL_DIG 16

Number of significant digits in a floating point number.


DBL_EPSILON

DBL_EPSILON Constant
float.h

#define DBL_EPSILON (1e-15)

The smallest x for which 1.0+x != 1.0.


DBL_MANT_BITS

DBL_MANT_BITS Constant
float.h

#define DBL_MANT_BITS 64

Number of bits used for the mantissa.


DBL_MANT_DIG

DBL_MANT_DIG Constant
float.h

#define DBL_MANT_DIG 16

Number of FLT_RADIX digits in the mantissa.


DBL_MAX_10_EXP

DBL_MAX_10_EXP Constant
float.h

#define DBL_MAX_10_EXP 999

The maximal exponent of a floating point value expressed in base 10 (see notes about FLT_MAX_EXP).


DBL_MAX_2_EXP

DBL_MAX_2_EXP Constant
float.h

#define DBL_MAX_2_EXP 3321

The maximal exponent of a floating point value expressed in base 2 (see notes about FLT_MAX_EXP).


DBL_MAX_EXP

DBL_MAX_EXP Constant
float.h

#define DBL_MAX_EXP 999

The maximal exponent of a floating point value expressed in base FLT_RADIX; greater exponents are principally possible (up to 16383), but not supported in all math functions.


DBL_MAX

DBL_MAX Constant
float.h

#define DBL_MAX (9.999999999999999e999)

The maximal floating point value (see notes about FLT_MAX_EXP).


DBL_MIN_10_EXP

DBL_MIN_10_EXP Constant
float.h

#define DBL_MIN_10_EXP (-999)

The minimal exponent of a floating point value expressed in base 10 (see notes about FLT_MIN_EXP).


DBL_MIN_2_EXP

DBL_MIN_2_EXP Constant
float.h

#define DBL_MIN_2_EXP (-3318)

The minimal exponent of a floating point value expressed in base 2 (see notes about FLT_MIN_EXP).


DBL_MIN_EXP

DBL_MIN_EXP Constant
float.h

#define DBL_MIN_EXP (-999)

The maximal exponent of a floating point value expressed in base FLT_RADIX; smaller exponents are principally possible (up to -16383), but not supported in all math functions.


DBL_MIN

DBL_MIN Constant
float.h

#define DBL_MIN (1e-999)

The minimal floating point value (see notes about FLT_MIN_EXP).


FLT_DIG

FLT_DIG Constant
float.h

#define FLT_DIG 16

Number of significant digits in a floating point number.


FLT_EPSILON

FLT_EPSILON Constant
float.h

#define FLT_EPSILON (1e-15)

The smallest x for which 1.0+x != 1.0.


FLT_MANT_BITS

FLT_MANT_BITS Constant
float.h

#define FLT_MANT_BITS 64

Number of bits used for the mantissa.


FLT_MANT_DIG

FLT_MANT_DIG Constant
float.h

#define FLT_MANT_DIG 16

Number of FLT_RADIX digits in the mantissa.


FLT_MAX_10_EXP

FLT_MAX_10_EXP Constant
float.h

#define FLT_MAX_10_EXP 999

The maximal exponent of a floating point value expressed in base 10 (see notes about FLT_MAX_EXP).


FLT_MAX_2_EXP

FLT_MAX_2_EXP Constant
float.h

#define FLT_MAX_2_EXP 3321

The maximal exponent of a floating point value expressed in base 2 (see notes about FLT_MAX_EXP).


FLT_MAX_EXP

FLT_MAX_EXP Constant
float.h

#define FLT_MAX_EXP 999

The maximal exponent of a floating point value expressed in base FLT_RADIX; greater exponents are principally possible (up to 16383), but not supported in all math functions.


FLT_MAX

FLT_MAX Constant
float.h

#define FLT_MAX (9.999999999999999e999)

The maximal floating point value (see notes about FLT_MAX_EXP).


FLT_MIN_10_EXP

FLT_MIN_10_EXP Constant
float.h

#define FLT_MIN_10_EXP (-999)

The minimal exponent of a floating point value expressed in base 10 (see notes about FLT_MIN_EXP).


FLT_MIN_2_EXP

FLT_MIN_2_EXP Constant
float.h

#define FLT_MIN_2_EXP (-3318)

The minimal exponent of a floating point value expressed in base 2 (see notes about FLT_MIN_EXP).


FLT_MIN_EXP

FLT_MIN_EXP Constant
float.h

#define FLT_MIN_EXP (-999)

The minimal exponent of a floating point value expressed in base FLT_RADIX; smaller exponents are principally possible (up to -16383), but not supported in all math functions.


FLT_MIN

FLT_MIN Constant
float.h

#define FLT_MIN (1e-999)

The minimal floating point value (see notes about FLT_MIN_EXP).


FLT_NORMALIZE

FLT_NORMALIZE Constant
float.h

#define FLT_NORMALIZE 1

Indicates that floating point numbers should always be normalized.


FLT_RADIX

FLT_RADIX Constant
float.h

#define FLT_RADIX 10

The base used for representing the exponent.


FLT_ROUNDS

FLT_ROUNDS Constant
float.h

#define FLT_ROUNDS 1

Option for rounding floating point numbers during the addition.


LDBL_DIG

LDBL_DIG Constant
float.h

#define LDBL_DIG 16

Number of significant digits in a floating point number.


LDBL_EPSILON

LDBL_EPSILON Constant
float.h

#define LDBL_EPSILON (1e-15)

The smallest x for which 1.0+x != 1.0.


LDBL_MANT_BITS

LDBL_MANT_BITS Constant
float.h

#define LDBL_MANT_BITS 64

Number of bits used for the mantissa.


LDBL_MANT_DIG

LDBL_MANT_DIG Constant
float.h

#define LDBL_MANT_DIG 16

Number of FLT_RADIX digits in the mantissa.


LDBL_MAX_10_EXP

LDBL_MAX_10_EXP Constant
float.h

#define LDBL_MAX_10_EXP 999

The maximal exponent of a floating point value expressed in base 10 (see notes about FLT_MAX_EXP).


LDBL_MAX_2_EXP

LDBL_MAX_2_EXP Constant
float.h

#define LDBL_MAX_2_EXP 3321

The maximal exponent of a floating point value expressed in base 2 (see notes about FLT_MAX_EXP).


LDBL_MAX_EXP

LDBL_MAX_EXP Constant
float.h

#define LDBL_MAX_EXP 999

The maximal exponent of a floating point value expressed in base FLT_RADIX; greater exponents are principally possible (up to 16383), but not supported in all math functions.


LDBL_MAX

LDBL_MAX Constant
float.h

#define LDBL_MAX (9.999999999999999e999)

The maximal floating point value (see notes about FLT_MAX_EXP).


LDBL_MIN_10_EXP

LDBL_MIN_10_EXP Constant
float.h

#define LDBL_MIN_10_EXP (-999)

The minimal exponent of a floating point value expressed in base 10 (see notes about FLT_MIN_EXP).


LDBL_MIN_2_EXP

LDBL_MIN_2_EXP Constant
float.h

#define LDBL_MIN_2_EXP (-3318)

The minimal exponent of a floating point value expressed in base 2 (see notes about FLT_MIN_EXP).


LDBL_MIN_EXP

LDBL_MIN_EXP Constant
float.h

#define LDBL_MIN_EXP (-999)

The maximal exponent of a floating point value expressed in base FLT_RADIX; smaller exponents are principally possible (up to -16383), but not supported in all math functions.


LDBL_MIN

LDBL_MIN Constant
float.h

#define LDBL_MIN (1e-999)

The minimal floating point value (see notes about FLT_MIN_EXP).


gdraw.h

gdraw.h Header File
Header File Index

Routines for graph screen drawing

Note: This header file is prepared for use, but not documented yet. These functions are still useless without support of some other functions which are not properly defined yet, so I didn't document this header file.

Functions
GD_Circle

GD_Contour

GD_Eraser

GD_HVLine

GD_Line

GD_Pen

GD_Select

GD_Text

GR3_paint3d
Draws the current 3D graph.
GR3_xyToWindow
Converts 3D coordinates to window coordinates.
GZ_Box
This function performs the Zoom Box command.
GZ_Center
Changes the zoom settings of the graph.
Predefined Types
GraphModes
Describes different graphing modes.


GD_Circle

GD_Circle Function (ROM Call 0x176)
gdraw.h

void GD_Circle (void);

This identifier has not been documented yet. Please help us out.

Uses: EV_defaultHandler, gr_active, ST_helpMsg, XR_stringPtr, sqrt, GT_CursorKey, GT_DspFreeTraceCoords, GT_DspMsg, GT_FreeTrace, GT_IncXY, GT_WinBound, GT_WinCursor, MakeWinRect, WinDupStat, WinEllipse, WinGetCursor, WinLine, WinLineTo, WinMoveTo, _bcd_math


GD_Contour

GD_Contour Function (ROM Call 0x17D)
gdraw.h

void GD_Contour (void);

This identifier has not been documented yet. Please help us out.

Uses: GR3_paint3d, gr_active, GR3_addContours, GT_Trace


GD_Eraser

GD_Eraser Function (ROM Call 0x17A)
gdraw.h

void GD_Eraser (void);

This identifier has not been documented yet. Please help us out.

Uses: EV_defaultHandler, gr_active, ST_helpMsg, XR_stringPtr, GT_CursorKey, GT_IncXY, GT_WinBound, WinBitmapPut, WinDupStat, WinGetCursor, WinMoveCursor


GD_HVLine

GD_HVLine Function (ROM Call 0x178)
gdraw.h

void GD_HVLine (short Orientation);

This identifier has not been documented yet. Please help us out.

Uses: EV_defaultHandler, gr_active, ST_helpMsg, XR_stringPtr, GT_CursorKey, GT_DspFreeTraceCoords, GT_IncXY, GT_ValidGraphRanges, GT_WinBound, GT_WinCursor, MakeWinRect, WinDupStat, WinGetCursor, WinHeight, WinLine, WinMoveCursor, WinWidth


GD_Line

GD_Line Function (ROM Call 0x177)
gdraw.h

void GD_Line (void);

This identifier has not been documented yet. Please help us out.

Uses: EV_defaultHandler, gr_active, ST_helpMsg, XR_stringPtr, GT_CursorKey, GT_DspFreeTraceCoords, GT_DspMsg, GT_FreeTrace, GT_IncXY, GT_WinBound, GT_WinCursor, MakeWinRect, WinDupStat, WinGetCursor, WinLine, WinLineTo, WinMoveTo


GD_Pen

GD_Pen Function (ROM Call 0x179)
gdraw.h

void GD_Pen (void);

This identifier has not been documented yet. Please help us out.

Uses: EV_defaultHandler, gr_active, ST_helpMsg, XR_stringPtr, GT_CursorKey, GT_DspFreeTraceCoords, GT_IncXY, GT_ValidGraphRanges, GT_WinBound, GT_WinCursor, WinAttr, WinDupStat, WinGetCursor, WinMoveCursor, WinPixGet, WinPixSet


GD_Select

GD_Select Function (ROM Call 0x17C)
gdraw.h

void GD_Select (void);

This identifier has not been documented yet. Please help us out.

Uses: EV_defaultHandler, gr_active, ST_helpMsg, XR_stringPtr, GT_CursorKey, GT_DspMsg, GT_IncXY, GT_SaveAs, GT_WinBound, GT_WinCursor, WinDupStat, WinRect


GD_Text

GD_Text Function (ROM Call 0x17B)
gdraw.h

void GD_Text (void);

This identifier has not been documented yet. Please help us out.

Uses: ER_catch, ER_success, EV_captureEvents, EV_defaultHandler, gr_active, ST_helpMsg, XR_stringPtr, CTypeTable, GT_CursorKey, GT_IncXY, GT_WinBound, GT_WinCursor, WinAttr, WinCharXY, WinDupStat, WinGetCursor, WinMoveCursor


GR3_paint3d

GR3_paint3d Function (ROM Call 0x1FF)
gdraw.h

void GR3_paint3d (void);

Draws the current 3D graph.

GR3_paint3d draws the currently active 3D graph using the current mode, format, and zoom settings. If the graph is not already calculated, it will display the calculation status.

Note: the graph application should be active when this function is executed. You can do this by executing:

EV_startApp (EV_getAppID ("TIGRAPH"), AP_START_CURRENT);

Uses: HeapAllocThrow, HeapDeref, HeapFreeIndir, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, HToESI, NG_graphESI, top_estack, RestoreScrState, SaveScrState, gr_active, gr_flags, memcpy, memmove, sprintf, XR_stringPtr, fmod, is_transfinite, round12, sincos, ck_valid_float, clear_error_context, estack_to_float, FindFunc, gr_del_locals, GR3_freeDB, QSkipGraphErr, FolderDelAllTemp, WinAttr, WinBackupToScr, WinCharXY, WinClr, WinFillTriangle, WinFont, WinLine, WinLineTo, WinMoveTo, WinStrXY, _bcd_math, NG_setup_graph_fun, NG_cleanup_graph_fun, _du32u32, ROM Call 0x46E
Used by: GD_Contour, GR3_handleEvent, Regraph, ROM Call 0x4CA


GR3_xyToWindow

GR3_xyToWindow Function (ROM Call 0x200)
gdraw.h

void GR3_xyToWindow (float xc, float yc, float* zc, short *WinX, short *WinY);

Converts 3D coordinates to window coordinates.

GR3_xyToWindow takes the 3D-graph point (xc,yc) and determines:

  1. the Z-coordinate (zc) at the point;
  2. the (WinX,WinY) pair of window coordinates for the location of this point on the 3D graph currently displayed.

Uses: HeapDeref, ER_catch, ER_success, ER_throwVar, NG_graphESI, top_estack, gr_active, memcpy, is_transfinite, clear_error_context, estack_to_float, FindFunc, QSkipGraphErr, _bcd_math, NG_setup_graph_fun, NG_cleanup_graph_fun
Used by: GT_Trace


GZ_Box

GZ_Box Function (ROM Call 0x22B)
gdraw.h

void GZ_Box (void);

This function performs the Zoom Box command.

This is the equivalent of the Zoom Box command. After a keypress, it will display the graph screen. If there is none (i.e. no function graphed), and there aren't any graphs selected, then you will be presented with a blank screen. If there is a function (or more) selected, then it will present you with a "dummy axis" (a smaller one).

Uses: GZ_Center, EV_defaultHandler, gr_active, ST_helpMsg, XR_stringPtr, GT_CursorKey, GT_DspFreeTraceCoords, GT_DspMsg, GT_FreeTrace, GT_IncXY, GT_Regraph, GT_SetGraphRange, GT_WinBound, GT_WinCursor, WinDupStat, WinGetCursor, WinRect


GZ_Center

GZ_Center Function (ROM Call 0x22C)
gdraw.h

void GZ_Center (void);

Changes the zoom settings of the graph.

This function basically changes the zoom settings of the graph. The first time the function is called, it changes the graph to the standard settings. The next time it is called, if there is a function selected, it increases xmin and xmax by 10, and increases ymin and ymax also. If there is no function selected, it remains at the standard. It seems that this function has some internal values for xmin and xmax, and any changes are ignored, meaning that, if you call it twice and change the values for xmin and xmax, and call this function a third time, the changes you made will be ignored.

Uses: gr_active, round12_err, GT_CenterGraphCursor, GT_Regraph, _bcd_math
Used by: GZ_Box, GZ_Decimal, GZ_Fit, GZ_InOut, GZ_Integer, GZ_Previous, GZ_Recall, GZ_Square, GZ_Standard, GZ_Stat, GZ_Store, GZ_Trig


GraphModes

GraphModes Type (Enumeration)
gdraw.h, graphing.h, unknown.h, vat.h

enum GraphModes {GR_FUNC = 1, GR_PAR = 2, GR_POL = 3, GR_SEQ = 4, GR_3D = 5, GR_DE = 6};

Describes different graphing modes.

This is an enumeration describing the modes of the Graph screen. It is currently used in CheckReservedName and CheckSysFunc from vat.h and also in GR_WIN_VARS from graphing.h.

The meaning of the different flags is given in the description of GR_WIN_VARS.

See also: GR_WIN_VARS, CheckReservedName, CheckSysFunc


graph.h

graph.h Header File
Header File Index

Common (non-windowed) graphic routines

Functions
BitmapGet
Gets a bitmap from the port graphical functions are writing to.
BitmapInit
Initializes a bitmap structure.
BitmapPut
Puts a bitmap to the screen.
BitmapSize
Determines a bitmap size in bytes.
CalcBitmapSize
Calculates the size of a bitmap.
ClientToScr
Converts a window-based rectangle to screen-based coordinates.
ClrScr
Clears the entire screen.
DisplayOff
Turns the display off.
DisplayOn
Turns the display on.
DrawChar
Draws a character.
DrawClipChar
Draws a clipped character.
DrawClipEllipse
Draws a clipped ellipse.
DrawClipLine
Draws a clipped line.
DrawClipPix
Draws a clipped pixel.
DrawClipRect
Draws a clipped rectangle.
DrawFkey
Draws a function key symbol.
DrawIcon
Draws an icon.
DrawLine
Draws a line between two specified points.
DrawMultiLines
Draws a set of lines in one turn.
DrawPix
Draws a pixel.
DrawStr
Draws a string.
DrawStrWidth
Determines the width of a string, in pixels.
DrawStrWidthP
Returns the width of the first len characters of a string.
FillLines2
Draws a filled area between two lines.
FillTriangle
Draws a filled triangle.
FontCharWidth
Determines the character width in pixels.
FontGetSys
Gets the current font number.
FontSetSys
Sets the current font.
GetPix
Gets the status of a specified pixel.
LCD_restore
Restores the saved content of the LCD screen.
LCD_save
Saves the content of the LCD screen.
LineTo
Draws a clipped line from the current pen position.
MakeScrRect
Puts four coordinates into a SCR_RECT and returns a pointer to it.
MakeWinRect
Builds a structure for representing rectangular area.
MoveTo
Sets the current pen position.
PortRestore
Cancels the virtual screen.
PortSet
Sets up the virtual screen.
QScrRectOverlap
Determines whether two rectangular areas overlap or not.
RestoreScrState
Restores a a saved state of the graphic system.
SaveScrState
Saves the state of the graphic system.
ScrRectFill
Draws a filled rectangle.
ScrRectOverlap
Finds an intersection of two rectangular areas.
ScrRectScroll
Scrols a rectangular area upwards or downwards.
ScrRectShift
Shifts a rectangular area left or right.
ScrToHome
Shifts structure of type SCR_RECT to the home position.
ScrToWin
Converts a structure of type SCR_RECT to type WIN_RECT.
SetCurAttr
Sets the default attribute.
SetCurClip
Sets the default clipping area.
sf_width
Returns the width in pixels of character character in the small font.
Global Variables
ScrRect
A global pointer to a SCR_RECT structure representing the whole screen.
Constants
BITMAP_HDR_SIZE
Defines the size of the header of the BITMAP structure.
LCD_MEM
A pointer to the area in memory where the contents of the LCD screen are stored.
LCD_SIZE
An integer constant which represents the size of the LCD screen in bytes.
Predefined Types
Attrs
An enumeration for describing legal attribute values.
BITMAP
A structure for defining a bitmap.
Bool
An enumeration to describe true or false values.
BoxAttrs
An enumeration for describing addittional box attribute values.
Fonts
An enumeration for describing legal font values.
ICON
A structure which describes an icon.
LCD_BUFFER
Describes a buffer to hold the screen contents.
MULTI_LINE
A structure for defining multiple lines for the DrawMultiLines command.
pICON
A pointer to the ICON scructure.
SCR_COORDS
An alias type for defining physical screen coordinates.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
WIN_COORDS
An alias type for defining logical screen coordinates.
WIN_RECT
A structure for defining a rectangular area.

For a lot of advanced drawing routines, we recommend you to download the ExtGraph library by the TI-Chess Team.

See also: wingraph.h, sprites.h, gray.h


BitmapGet

BitmapGet Function (ROM Call 0x185)
graph.h

void BitmapGet (const SCR_RECT *rect, void *BitMap);

Gets a bitmap from the port graphical functions are writing to.

BitmapGet stores a series of bytes (the size of which is defined by BitmapSize) defining a bitmap for a rectangular area (whose boundaries are given using the SCR_RECT structure rect) into a buffer pointed to by BitMap. The data is fetched in the port graphical functions are writing to (see PortSet). The first two words at the address BitMap will contain the height and the width (in pixels) of the rectangular area respectively, then the actual data follows. BitMap is usually a pointer to a BITMAP structure.

Here is a simple example (called "Bitmap Test"), which uses BitmapGet and BitmapPut to get the contents of the TI-89 screen and to restore it later:

// Retrieve and store a bitmap

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization

#define MIN_AMS 100           // Compile for AMS 1.00 or higher

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

// Main Function
void _main(void)
{
  SCR_RECT full_screen = {{0, 0, LCD_WIDTH - 1, LCD_HEIGHT - 1}};
  char buffer [BITMAP_HDR_SIZE + LCD_WIDTH*LCD_HEIGHT/8]; // or 2004 for a TI-89 and 3844 for a TI-92+/V200 if you like it more
  BitmapGet (&full_screen, buffer);          // store screen in buffer
  clrscr ();
  printf ("Press any key to\nrestore screen...");
  ngetchx ();
  BitmapPut (0, 0, buffer, &full_screen, A_REPLACE);
  ngetchx ();
}
Note that this is just an example: for saving/restoring the whole screen, functions LCD_save and LCD_restore are much more efficient! And, 'buffer' will probably be allocated using malloc in a more realistic example...

Uses: BitmapInit
Used by: ScrRectScroll, ScrRectShift, MenuKey, WinBitmapGet, WinOpen, ROM Call 0x421

See also: BitmapPut, BitmapSize, CalcBitmapSize


BitmapInit

BitmapInit Function (ROM Call 0x186)
graph.h

void BitmapInit (const SCR_RECT *rect, void *BitMap);

Initializes a bitmap structure.

BitmapInit is an auxilary command (used internally in BitmapGet, so it is not particularly useful). It initializes first two words at address BitMap to the height and the width (in pixels) of the rectangular area rect.

Used by: BitmapGet, WinOpen, WinReOpen


BitmapPut

BitmapPut Function (ROM Call 0x187)
graph.h

void BitmapPut (short x, short y, const void *BitMap, const SCR_RECT *clip, short Attr);

Puts a bitmap to the screen.

BitmapPut puts a bitmap BitMap (which was taken using BitmapGet) on the screen at position (x, y), using the attribute Attr. The drawn bitmap will be clipped at the boundaries of the area given by the clip parameter. See SetCurClip for more info about clipping areas. The following attributes are supported:

A_REPLACE | Replace the destination region with the source bitmap
A_REVERSE | Replace the destination region with the inverse of the source bitmap
A_NORMAL | OR the source bitmap into the destination region
A_XOR | Exculsive-OR the source bitmap into the destination region
A_OR | OR the source bitmap into the destination region
A_AND | AND the source bitmap into the destination region
A_SHADED | Mask the source bitmap so that every other pixel is turned off and replace the destination region with that result (the source region is left unchanged)

See SetCurAttr command for more general info about attributes.

It seems that the A_REVERSE attribute is broken in current implementations of this function: If the value of x is not a multiple of 8, a black vertical line will appear across the picture.

Note: The sprites.h header file supports much faster alternatives to the BitmapPut function for bitmap shapes which are not wider than 32 pixels (useful for games programming).

Uses: ScrRectOverlap, memcpy, TIOS_abs
Used by: ScrRectScroll, ScrRectShift, MenuKey, WinBackupToScr, WinBitmapPut, ROM Call 0x420, ROM Call 0x421, WinRemove

See also: BitmapGet, CalcBitmapSize


BitmapSize

BitmapSize Function (ROM Call 0x188)
graph.h

unsigned short BitmapSize (const SCR_RECT *rect);

Determines a bitmap size in bytes.

BitmapSize returns the size in bytes of a bitmap for a rectangular area given by parameter rect. This size includes the data for the bitmap and the header. See BitmapGet for more info about bitmaps.

Used by: MenuKey, WinBitmapSize, WinClr, WinOpen, WinReOpen, ROM Call 0x421

See also: BitmapGet


CalcBitmapSize

CalcBitmapSize Function (ROM Call 0x3EF)
AMS 2.00 or higher graph.h

unsigned short CalcBitmapSize (BITMAP *b);

Calculates the size of a bitmap.

CalcBitmapSize calculates the size of the bitmap pointed to by b. In fact, CalcBitmapSize has the following implementation:

unsigned short CalcBitmapSize(BITMAP *b)
{
  return ((((b->NumCols + 7) >> 3) * b->NumRows) + BITMAP_HDR_SIZE);
}
This means that you can create a bitmap with only NumRows and NumCols filled, and pass it to this function.

You can also define a macro for this purpose.

Used by: DynMenuAdd, DynMenuChange, MenuBegin, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, ROM Call 0x421

See also: BitmapGet, BitmapPut, BitmapSize


ClientToScr

ClientToScr Function (ROM Call 0x42C)
AMS 2.00 or higher graph.h

void ClientToScr (const SCR_RECT *WindowRect, const SCR_RECT *Rect, SCR_RECT *Result);

Converts a window-based rectangle to screen-based coordinates.

ClientToScr adds the values of x1 and y1 in WindowRect to all x and y values in Rect, and returns the result in Result. This is usually used to convert a window-based SCR_RECT to screen-based coordinates by passing it as the second parameter to this function. The first parameter is then a screen-based SCR_RECT of the window's client region. This routine is called in SetWinClip.

Used by: SetWinClip, WinBitmapGet, WinScrollH, WinScrollV

See also: ScrToWin


ClrScr

ClrScr Function (ROM Call 0x19E)
graph.h

void ClrScr (void);

Clears the entire screen.

ClrScr fills the entire screen (real or virtual) with zeros. To set up a virtual screen, use PortSet.

Uses: memset
Used by: clrscr

Deprecated alias: ClearScreen


DisplayOff

DisplayOff Function (Macro)
graph.h

void DisplayOff (void);

Turns the display off.

DisplayOff turns the display off. It does not really switch the LCD off, it just blanks the screen and keeps it blank. To turn the display back on, you must use DisplayOn.

See also: DisplayOn


DisplayOn

DisplayOn Function (Macro)
graph.h

void DisplayOn (void);

Turns the display on.

DisplayOn turns the display on. It is mostly used after you turned the display off using DisplayOff.

See also: DisplayOff


DrawChar

DrawChar Function (ROM Call 0x1A4)
graph.h

void DrawChar (short x, short y, char c, short Attr);

Draws a character.

DrawChar draws a character c at a specific (x, y) location. The following character attributes are supported (the region defined by a character is 8x10 for huge font, 6x8 for large font or nx5 for small font, depending on the current font set by FontSetSys command):

A_NORMAL | The character is ORed into the destination
A_REVERSE | The region created by inversing the character replaces the destination
A_REPLACE | The region defined by the character replaces the destination
A_XOR | The character is XORed into the destination
A_SHADED | The character is masked so that every other pixel is turned off then ORed into the destination

See SetCurAttr command for more general info about attributes.

Uses: EV_runningApp, OO_GetAppAttr, sf_width, TIOS_abs
Used by: DrawFkey, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, fputchar, ROM Call 0x412, ROM Call 0x421


DrawClipChar

DrawClipChar Function (ROM Call 0x191)
graph.h

void DrawClipChar (short x, short y, short c, const SCR_RECT *clip, short Attr);

Draws a clipped character.

DrawClipChar works exactly like DrawChar, except the character will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas.

Uses: EV_runningApp, OO_GetAppAttr, sf_width, TIOS_abs
Used by: fgetchar, ROM Call 0x412


DrawClipEllipse

DrawClipEllipse Function (ROM Call 0x192)
graph.h

void DrawClipEllipse (short x, short y, short a, short b, const SCR_RECT *clip, short Attr);

Draws a clipped ellipse.

DrawClipEllipse draws an ellipse with centre at (x, y), and with semiaxes a and b. The ellipse will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. The interior of the ellipse remains intact (no fill). The ellipse will be drawn using the attribute Attr. Supported attributes are:

A_NORMAL | Draw a elipse
A_REVERSE | Erase a ellipse
A_XOR | XORs a ellipse into the destination

See SetCurAttr for more general information about attributes.

Note: Set a== b to draw a circle.

Uses: DrawClipLine, DrawPix
Used by: WinEllipse


DrawClipLine

DrawClipLine Function (ROM Call 0x193)
graph.h

void DrawClipLine (const WIN_RECT *Line, const SCR_RECT *clip, short Attr);

Draws a clipped line.

DrawClipLine draws a line from (x0, y0) to (x1, y1) where coordinates (x0, y0) and (x1, y1) are given in a WIN_RECT structure Line, using the attribute Attr. The line will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. See DrawLine for a description of supported atributes.

Uses: DrawLine, SetCurClip, ROM Call 0x47E
Used by: DrawClipEllipse, FillLines2, LineTo, WinLine, WinLineTo


DrawClipPix

DrawClipPix Function (ROM Call 0x194)
graph.h

void DrawClipPix (short x, short y);

Draws a clipped pixel.

DrawClipPix works exactly like DrawPix, except the pixel will not be drawn if its coordinates are out of clipping zone given by SetCurClip command, and an attribute is not given as an explicite parameter (the attribute given with SetCurAttr command will be used instead).

Uses: DrawPix
Used by: DrawClipRect


DrawClipRect

DrawClipRect Function (ROM Call 0x195)
graph.h

void DrawClipRect (const WIN_RECT *rect, const SCR_RECT *clip, short Attr);

Draws a clipped rectangle.

DrawClipRect draws a rectangle with (x0, y0) and (x1, y1) as corners, where coordinates (x0, y0) and (x1, y1) are given in a WIN_RECT structure rect. The rectangle will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. The interior of the rectangle remains intact (no fill). The border lines of the rectangle will be drawn using the attribute Attr. See DrawLine for a description of supported line atributes. In addition, the attribute may be ORed with one or more following constants (which are defined in enum BoxAttrs:

B_NORMAL | Draw a normal rectangle
B_DOUBLE | Draw a double thick rectangle
B_ROUNDED | Draw a rectangle with rounded corners
B_CUT | Draw a rectangle with the upper corners cut (like in toolboxes)

Note: I cannot conclude what the difference is if you OR the attribute with B_NORMAL or if you do not do so. Maybe I am stupid.

Uses: DrawClipPix, LineTo, MoveTo, SetCurAttr, SetCurClip
Used by: MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, DrawWinBorder, WinRect, ROM Call 0x421


DrawFkey

DrawFkey Function (ROM Call 0x1A5)
graph.h

void DrawFkey (short x, short y, short fkey_no, short Attr);

Draws a function key symbol.

DrawFkey draws a string "F<fkey_no>" at (x, y), using the attribute Attr, and using small font, regardless of the current font setting. See DrawChar for a description of attribute Attr. fkey_no must be in a range 0-9.

Uses: DrawChar, FontSetSys
Used by: MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, ROM Call 0x421


DrawIcon

DrawIcon Function (ROM Call 0x1A6)
graph.h

void DrawIcon (short x, short y, const void *Icon, short Attr);

Draws an icon.

DrawIcon draws an icon (a 16x16 bitmap structure given as 16-word group of bits) pointed to by pointer Icon at location (x, y) using attribute Attr. Pointer Icon is usually of type pICON (pointer to the ICON structure). The following attributes are supported:

A_NORMAL | The icon is ORed into the destination
A_REVERSE | The inversed icon is ANDed into the destination
A_XOR | The icon is XORed into the destination
A_SHADED | The icon is masked so that every other pixel is turned off then ORed into the destination

See SetCurAttr command for more general info about attributes.

Note: In antediluvian releases of TIGCCLIB (before 2.0) the documentation said that A_REPLACE attribute is supported. Unfortunately, it seems that this is not true (Daniel Pineo informed me about this problem). Also, information about usage of A_REVERSE was incorrect.

Uses: DrawPix

See also: sprites.h


DrawLine

DrawLine Function (ROM Call 0x1A7)
graph.h

void DrawLine (short x0, short y0, short x1, short y1, short Attr);

Draws a line between two specified points.

DrawLine draws a line from (x0, y0) to (x1, y1) using the attribute Attr. The following attributes are supported:

A_NORMAL | Draw a normal line
A_REVERSE | Draw an inverse line (i.e. erase the line)
A_XOR | Draw a line using XORing with the destination
A_THICK1 | Draw a double thick line
A_SHADE_V | Draw the line using a vertical shading pattern
A_SHADE_H | Draw the line using a horizontal shading pattern
A_SHADE_NS | Draw the line using a negative slope diagonal shading pattern
A_SHADE_PS | Draw the line using a positive slope diagonal shading pattern

See SetCurAttr command for more general info about attributes. Note that although TI said nothing about it, attributes A_SHADE_V, A_SHADE_H, A_SHADE_NS and A_SHADE_PS work only for lines with slope more than 45 degree (i.e. for lines which are more "vertical" than "horizontal"). For "nearly horizontal" lines all of them act like A_NORMAL. I don't know whether it is a bug, or planned feature. So, if you want to draw shaded-fill rectangle using DrawLine in a loop, use vertical lines for drawing, not horizontal ones!

Using DrawLine (and all other graphic comands which does not do clipping) may be harmful if called using parameters which are out of legal range (i.e. out of the screen area).

Uses: TIOS_abs
Used by: DrawClipLine, FillTriangle, ScrRectFill, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, GT_BackupToScr, Regraph, DrawWinBorder, WinLineNC, ROM Call 0x421, ROM Call 0x47B


DrawMultiLines

DrawMultiLines Function (ROM Call 0x196)
graph.h

void DrawMultiLines (short x, short y, const void *multi_lines);

Draws a set of lines in one turn.

DrawMultiLines draws a whole set of lines using a single command. The parameter multi_lines is a pointer to the byte-area structure organized as follows:

  • The first byte is the total number of lines;
  • Then, each line is described using a 5-byte structure as follows:
    • The first byte is line attribute;
    • The next four bytes are x0, y0, x1 and y1 respective.
The line will be clipped at the current clipping area boundaries given with SetCurClip command. multi_lines is usually a pointer to the MULTI_LINE structure. See DrawLine for more info about line attributes.

Parameters x and y act as a translation shifters. They are added to all line coordinates before drawing (the structure itself remains intact), so by using the same multi_line with various x-s and y-s, it is possible to draw several instances of the same-shape objects on various places on the screen.

The following example will draw two stars on the screen:
static MULTI_LINE star_shape = {3, {{1, 30, 50, 70, 50},
                                    {1, 35, 35, 65, 65},
                                    {1, 35, 65, 65, 35}}};
...
DrawMultiLines (0, 0, &star_shape);
DrawMultiLines (80, 0, &star_shape);

Uses: LineTo, MoveTo, SetCurAttr
Used by: MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect


DrawPix

DrawPix Function (ROM Call 0x1A8)
graph.h

void DrawPix (short x, short y, short Attr);

Draws a pixel.

DrawPix draws a pixel at (x, y), using the attribute Attr. The following attributes are supported:

A_NORMAL | Draw a pixel
A_REVERSE | Erase a pixel
A_XOR | Invert a pixel

See SetCurAttr command for a more general info about attributes.

Used by: DrawClipEllipse, DrawClipPix, DrawIcon, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, WinPixSet, ROM Call 0x421


DrawStr

DrawStr Function (ROM Call 0x1A9)
graph.h

void DrawStr (short x, short y, const char *str, short Attr);

Draws a string.

DrawStr draws a string str at a specific (x, y) location. See DrawChar for a description of attribute Attr.

Note: Too many people ask me how to draw a content of an integer variable (for example) instead of a string. Although this question is answered in the Frequently Asked Question list, I received a suggestion that it would be better if explained here. Well. You need to use sprintf to convert a non-string variable to a string. For example:

int x, y;
char buffer[50];
...
sprintf (buffer, "%d + %d = %d", x, y, x + y);
DrawStr (0, 0, buffer, A_NORMAL);

Uses: EV_runningApp, OO_GetAppAttr, sf_width, TIOS_abs
Used by: MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, printf_xy, DrawWinBorder, ROM Call 0x421

Deprecated alias: DrawStrXY


DrawStrWidth

DrawStrWidth Function (ROM Call 0x197)
graph.h

short DrawStrWidth (const char *str, short Font);

Determines the width of a string, in pixels.

DrawStrWidth returns the actual width of the string str according to the font number given by parameter Font. For 8x10 and 6x8 fonts, this is just 8 or 6 times the length of the string, but the 4x6 font is proportional. See FontSetSys for more info on fonts.

Uses: strlen, sf_width
Used by: cmd_dialog, cmd_text, Dialog, MenuBegin, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, DrawWinBorder, ROM Call 0x421, ROM Call 0x4D7

See also: DrawStrWidthP


DrawStrWidthP

DrawStrWidthP Function (ROM Call 0x3EE)
AMS 2.00 or higher graph.h

unsigned short DrawStrWidthP (const char *str, short len, short Font);

Returns the width of the first len characters of a string.

DrawStrWidthP returns the length in pixels of the first len characters of the string str displayed with font Font. The difference between DrawStrWidthP and DrawStrWidth is that DrawStrWidth gives the length in pixels of the full string str displayed with font Font.
Be careful: len must be less or equal to strlen (str)!

This function is interesting only for the F_4x6 font; for the F_6x8 and F_8x10 fonts, DrawStrWidthP will return 6*len and 8*len, respectively. Also, using

DrawStrWidthP (str, strlen (str), font);
is slower than using
DrawStrWidth (str, font);
Example:
// This line is equivalent to:
// printf_xy (0, 0, "%hu", DrawStrWidth ("DEFGHIJK", F_4x6));
printf_xy (0, 0, "%hu",
  DrawStrWidthP ("ABCDEFGHIJKLMNOPQRSTUVWXYZ" + 3, 8, F_4x6));
On AMS versions lower than 2.00, you can emulate DrawStrWidthP with:
unsigned short DrawStrWidthP(const char *str, short len, short Font)
{
  char s[len+1];
  short i;
  // Calling memcpy is slower than copying the string by-hand...
  for (i = 0; i < len; i++)
    s[i] = str[i];
  s[len] = 0;
  return DrawStrWidth (s, font);
}
or the following assembly code provided by Lionel Debroux:
unsigned short DrawStrWidthP(register const char *str asm("a0"), register short len asm("d0"), register short Font asm("d2"));
asm("DrawStrWidthP:
    move.w   %d0,%d1
    beq.s    __end_DrawStrWidthP__
    btst     #0,%d0
    beq.s    __allocate_on_the_stack_DSWP__
    addq.w   #1,%d1
__allocate_on_the_stack_DSWP__:
    suba.w   %d1,%sp

    movea.l  %sp,%a1
    subq.w   #1,%d0
__loop_copy_DrawStrWidthP__:
    move.b   (%a0)+,(%a1)+
    dbf      %d0,__loop_copy_DrawStrWidthP__
    clr.b    (%a1)

    addq.w   #8,%d1
    move.w   %d1,-(%sp) | save d1 (DrawStrWidth can destroy it)...
    move.w   %d2,-(%sp)
    pea      4(%sp)
    movea.l  0xC8.w,%a0
    movea.l  0x197*4(%a0),%a0 | DrawStrWidth
    jsr      (%a0)

    adda.w   6(%sp),%sp
__end_DrawStrWidthP__:
    rts
");
The C function is about 1% slower than the original implementation. The assembly implementation is faster.

Uses: sf_width
Used by: Dialog, WinStrXYWrap

See also: DrawStrWidth


FillLines2

FillLines2 Function (ROM Call 0x199)
graph.h

void FillLines2 (const WIN_RECT *lower_line, const WIN_RECT *upper_line, const SCR_RECT *clip, short Attr);

Draws a filled area between two lines.

FillLines2 fills an area bounded with two lines which coordinates are given in two WIN_RECT structures lower_line (lower bound) and upper_line (upper bound). In fact, it draws a filled polygon whose vertices are (lower_line.x0, lower_line.y0), (lower_line.x1, lower_line.y1), (upper_line.x0, upper_line.y0) and (upper_line.x1, upper_line.y1) using the attribute Attr. Supported attributes are the same as in command FillTriangle. The drawn polygon will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. If lower_line is above upper_line, nothing will be drawn. To be more precise, "above" means "closer to the top of the screen".

Uses: DrawClipLine, TIOS_abs
Used by: WinFillLines2


FillTriangle

FillTriangle Function (ROM Call 0x198)
graph.h

void FillTriangle (short x0, short y0, short x1, short y1, short x2, short y2, const SCR_RECT *clip, short Attr);

Draws a filled triangle.

FillTriangle draws a filled triangle with vertices (x0, y0), (x1, y1) and (x2, y2) using the attribute Attr. The triangle will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. Supported attributes are:

A_NORMAL | Draws a solid fill triangle
A_REVERSE | Draws an empty triangle (i.e. erase a triangular area)
A_XOR | XORs a solid fill triangle into the destination
A_SHADE_V | Draws a triangle filled using a vertical shading pattern
A_SHADE_H | Draws a triangle filled using a horizontal shading pattern
A_SHADE_NS | Draws a triangle filled using a negative slope diagonal shading pattern
A_SHADE_PS | Draws a triangle filled using a positive slope diagonal shading pattern

See SetCurAttr command for more general info about attributes.

Uses: DrawLine, TIOS_abs
Used by: WinFillTriangle


FontCharWidth

FontCharWidth Function (ROM Call 0x190)
graph.h

short FontCharWidth (short c);

Determines the character width in pixels.

FontCharWidth returns the actual width of the character c according to current font settings.

Uses: sf_width
Used by: Dialog, EV_defaultHandler, fputchar, EV_quit, WinStrXYWrap

See also: DrawStrWidth


FontGetSys

FontGetSys Function (ROM Call 0x18E)
graph.h

unsigned char FontGetSys(void);

Gets the current font number.

FontGetSys returns the current font number. See FontSetSys for more info.

Used by: Dialog, fputchar, ROM Call 0x4D7


FontSetSys

FontSetSys Function (ROM Call 0x18F)
graph.h

unsigned char FontSetSys (short Font);

Sets the current font.

FontSetSys changes the current text font. All subsequent characters written to the screen will use this font. The supported values for Font are F_4x6, F_6x8, and F_8x10, and they are defined in enum Fonts. The 4x6 font is a proportional font while the 6x8 and 8x10 fonts are fixed-width. FontSetSys returns the previously active font number.

Used by: DrawFkey, RestoreScrState, Dialog, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, DrawWinBorder, WinActivate, WinBegin, WinBeginPaint, WinFont, WinRemove, ROM Call 0x421


GetPix

GetPix Function (ROM Call 0x19F)
graph.h

short GetPix (short x, short y);

Gets the status of a specified pixel.

GetPix gets the status of the pixel located at (x, y). Returns TRUE or FALSE depending on whether the corresponding pixel is set or reset.

Used by: WinPixGet


LCD_restore

LCD_restore Function (Macro)
graph.h

void LCD_restore (const void *buffer);

Restores the saved content of the LCD screen.

LCD_restore restores the contents of the screen (saved using LCD_save) from the buffer pointed to by buffer. buffer is usually of type LCD_BUFFER. LCD_restore is a small macro which calls the memcpy function.

Note: LCD_save and LCD_restore do not work in grayscale mode.

Uses: memcpy


LCD_save

LCD_save Function (Macro)
graph.h

void LCD_save (void *buffer);

Saves the content of the LCD screen.

LCD_save saves the complete contents of the screen into the 3840-bytes long buffer pointed to by buffer. buffer is usually of type LCD_BUFFER. LCD_save is a small macro which calls the memcpy function.

Note: LCD_save and LCD_restore do not work in grayscale mode.

Uses: memcpy


LineTo

LineTo Function (ROM Call 0x19C)
graph.h

void LineTo (short x, short y);

Draws a clipped line from the current pen position.

LineTo draws a line from the current pen position to the pixel (x, y) using the current attribute given with SetCurAttr command, then updates the pen position to those coordinates. The line will be clipped at the current clipping area boundaries given with SetCurClip command.

Uses: DrawClipLine
Used by: DrawClipRect, DrawMultiLines, DrawWinBorder

Deprecated alias: DrawTo


MakeScrRect

MakeScrRect Function (ROM Call 0x42D)
AMS 2.00 or higher graph.h

SCR_RECT *MakeScrRect (short x0, short y0, short x1, short y1, SCR_RECT *s);

Puts four coordinates into a SCR_RECT and returns a pointer to it.

MakeScrRect is used to create a SCR_RECT from four screen coordinates.

For example, it can be used to convert a WIN_RECT to a SCR_RECT like this (s is a SCR_RECT, and rect is a WIN_RECT):

MakeScrRect (rect.x0, rect.y0, rect.x1, rect.y1, &s);
In GNU C (like GCC4TI is), it is generally faster to use cast constructors instead of calling MakeScrRect:
s = (SCR_RECT){{x0, y0, x1, y1}};

See also: SetWinClip, MakeWinRect


MakeWinRect

MakeWinRect Function (ROM Call 0x2C)
graph.h, wingraph.h

WIN_RECT *MakeWinRect (short x0, short y0, short x1, short y1);

Builds a structure for representing rectangular area.

MakeWinRect accepts coordinates of two corners (x0, y0) and (x1, y1) of an rectangular area, and returns the pointer to the structure of type WIN_RECT in which these coordinates are embeded. This function may be useful in combination with a rich set of TIOS functions which expect a structure of type WIN_RECT as explicit argument, like WinOpen, WinLine, etc.

Note: This function returns a static pointer, which will be rewritten with each call. So, you must not use it inside functions which needs more than one parameter of type WIN_RECT like WinFillLines2 etc.

Used by: DrawStaticButton, assert, cmd_circle, cmd_cubicreg, cmd_expreg, cmd_line, cmd_linehorz, cmd_linevert, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_newpic, cmd_onevar, cmd_powerreg, cmd_pxlhorz, cmd_pxlline, cmd_pxlvert, cmd_quadreg, cmd_quartreg, cmd_shade, cmd_showstat, cmd_twovar, EV_defaultHandler, handleVarLinkKey, GD_Circle, GD_HVLine, GD_Line, HelpKeys, dv_create_graph_titles, EV_quit, FuncLineFlt, GM_Integrate, GM_Shade, GM_TanLine, gr_stopic, GrLineFlt, GT_SaveAs


MoveTo

MoveTo Function (ROM Call 0x19D)
graph.h

void MoveTo (short x, short y);

Sets the current pen position.

MoveTo sets the current pen position to (x, y).

Used by: DrawClipRect, DrawMultiLines, clrscr, fgetchar, fputchar, gets, getsn, DrawWinBorder


PortRestore

PortRestore Function (ROM Call 0x1A3)
graph.h

void PortRestore (void);

Cancels the virtual screen.

PortRestore restores factory defaults for address and dimensions of the video memory. PortRestore acts exactly like

PortSet ((void *) 0x4C00, 239, 127);

Used by: GrayOff, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, ST_eraseHelp, ST_helpMsg, ST_modKey, ST_precision, WinBeginPaint, WinBitmapGet, WinBitmapPut, WinChar, WinEllipse, WinFill, WinFillLines2, WinFillTriangle, WinLine, WinLineExt, WinLineNC, WinLineTo, WinPixGet, WinPixSet, WinRect, WinScrollH, WinScrollV, ROM Call 0x412, ROM Call 0x421


PortSet

PortSet Function (ROM Call 0x1A2)
graph.h

void PortSet (void *vm_addr, short x_max, short y_max);

Sets up the virtual screen.

PortSet allows drawing in a virtual screen. All graphic commands which are built-in into TIOS does not expect that the video memory must be at 0x4C00, and that the video memory is always 240 x 128 pixels. Using PortSet you can set up a virtual screen anywhere in a memory, and of any size. After using PortSet, all graphic commands will assume that the video memory starts at vm_addr, and that the dimensions of the video memory are (x_max+1) x (y_max+1) pixels. This allows to you to use graphic functions even when the actual LCD memory is relocated at any other address using I/O hardware ports, or to draw pictures into virtual screens (not visible on the real screen), then move them (using memcpy or some other function) to the real screen. This will enable the possibility of hiding the actual drawing process, and to display the drawn picture immediately.

Here is a code fragment which ilustrates the usage of virtual screens:

void *virtual=malloc (LCD_SIZE);  // Allocate the buffer
...
if (!virtual) ... // do some error handling - not enough memory!
PortSet (virtual, 239, 127); // redirect drawing routines to buffer
or, even simpler, a virtual screen may simply be in any local variable which is long enough:
char virtual[LCD_SIZE];
...
PortSet (virtual, 239, 127);
Note that, in this case, virtual screen memory will in fact be somewhere on the stack. There is nothing bad in this, but keep in mind that the total amount of the stack is 16K, so don't put too much data (like big arrays etc.) on the stack (i.e. in local variables). If you really need to handle a lot of data, use malloc instead.

After setting up the virtual screen, you can do any drawing you want - it will be redirected to the virtual screen. To copy this to the regular screen (i.e. to display it) do this:
memcpy (LCD_MEM, virtual, LCD_SIZE);
or even simpler (this is the same):
LCD_restore (virtual);
Note: Don't forget to do PortRestore before the end of the program, otherwise TIOS will be fooled after returning to TI-Basic!

Used by: GrayOn, GraySetAMSPlane, ROM Call 0x413


QScrRectOverlap

QScrRectOverlap Function (ROM Call 0x18D)
graph.h

short QScrRectOverlap (const SCR_RECT *r1, const SCR_RECT *r2);

Determines whether two rectangular areas overlap or not.

QScrRectOverlap returns TRUE or FALSE depending on whether two rectangular areas given in two SCR_RECT structures r1 and r2 overlap or not.

Used by: ScrRectOverlap, EV_paintOneWindow


RestoreScrState

RestoreScrState Function (ROM Call 0x1A1)
graph.h

void RestoreScrState (const void *buffer);

Restores a a saved state of the graphic system.

RestoreScrState restores a saved state of the graphic system (saved using SaveScrState command) from a structure pointed to by buffer.

Uses: FontSetSys, memcpy
Used by: ABT_dialog, GR3_paint3d, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, ST_eraseHelp, ST_helpMsg, ST_modKey, ST_precision, fopen, GR3_handleEvent, ROM Call 0x421, WinEndPaint


SaveScrState

SaveScrState Function (ROM Call 0x1A0)
graph.h

void SaveScrState (void *buffer);

Saves the state of the graphic system.

SaveStrState saves the current state of the graphic system (including the address and dimensions of the virtual screen, current font, attribute, clipping area and pen position) into a 18-byte structure pointed to by buffer. buffer is usually a pointer to a SCR_STATE structure.

Uses: memcpy
Used by: ABT_dialog, GR3_paint3d, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, ST_eraseHelp, ST_helpMsg, ST_modKey, ST_precision, fgetchar, fopen, fputchar, gets, getsn, GR3_handleEvent, ROM Call 0x421, WinBeginPaint


ScrRectFill

ScrRectFill Function (ROM Call 0x189)
graph.h

void ScrRectFill (const SCR_RECT *rect, const SCR_RECT *clip, short Attr);

Draws a filled rectangle.

ScrRectFill draws a filled rectangle given by SCR_RECT structure rect, using the attribute Attr. The rectangle will be clipped at the boundaries of the area given by parameter clip. See SetCurClip for more info about clipping areas. Supported attributes are:

A_NORMAL | Fill with black pixels
A_REVERSE | Fill with white pixels
A_XOR | All pixels in the rectangle will be reversed

FillLines2 is more complicated and slower function than ScrRectFill, but it supports many more attributes. See SetCurAttr for more info about attributes.

Note: TI said that attribute A_SHADED (set to a pattern of pixels on and off) is also supported, but it didn't work when I tried it; at least, it does not work on AMS 1.00.

Uses: DrawLine
Used by: ScrRectScroll, ScrRectShift, MenuEnd, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, UpdateWindows, DrawWinBorder, WinClr, WinFill, ROM Call 0x3EA, ROM Call 0x421


ScrRectOverlap

ScrRectOverlap Function (ROM Call 0x18A)
graph.h

short ScrRectOverlap (const SCR_RECT *r1, const SCR_RECT *r2, SCR_RECT *r);

Finds an intersection of two rectangular areas.

ScrRectOverlap finds an intersection of two rectangular areas given in two SCR_RECT structures r1 and r2, and stores coordinates of the intersection in r. ScrRectOverlap returns TRUE or FALSE depending on whether r1 and r2 overlap or not.

Uses: QScrRectOverlap
Used by: BitmapPut, ScrRectDivide, UpdateWindows, WinBitmapGet, WinBitmapSize, WinFill, WinRect, WinScrollH, WinScrollV


ScrRectScroll

ScrRectScroll Function (ROM Call 0x18B)
graph.h

void ScrRectScroll (const SCR_RECT *rect, const SCR_RECT *clip, short NumRows, short Attr);

Scrols a rectangular area upwards or downwards.

ScrRectScroll scrolls a rectangular area which is an intersection of two rectangular areas given using two SCR_RECT structures rect and clip upwards by NumRows pixels (or downwards if NumRows < 0). rect usually represents the actual area which need to be scrolled, and clip is the clipping area. See SetCurClip for more info about clipping areas. The attribute Attr determines what happens with pixels in a vacant space produced after scrolling:

A_NORMAL | Pixels in a vacant space are set
A_REVERSE | Pixels in a vacant space are reset
A_XOR | Pixels in a vacant space are inverted

See SetCurAttr command for more general info about attributes.

Note: This command is internally realized stupidly using BitmapGet and BitmapPut, so it is slow.

Uses: BitmapGet, BitmapPut, ScrRectFill, memcmp, memcpy, TIOS_abs
Used by: fputchar, WinChar, WinScrollV


ScrRectShift

ScrRectShift Function (ROM Call 0x18C)
graph.h

void ScrRectShift (const SCR_RECT *rect, const SCR_RECT *clip, short NumCols, short Attr);

Shifts a rectangular area left or right.

ScrRectShift shifts a rectangular area which is an intersection of two rectangular areas given using two SCR_RECT structures rect and clip left by NumRows pixels (or right if NumRows < 0). The attribute Attr determines what happens with pixels in a vacant space produced after shifting. For more info, see ScrRectScroll command.

Uses: BitmapGet, BitmapPut, ScrRectFill, memmove, TIOS_abs
Used by: WinScrollH


ScrToHome

ScrToHome Function (ROM Call 0x2E)
graph.h

SCR_RECT *ScrToHome (SCR_RECT *rect);

Shifts structure of type SCR_RECT to the home position.

ScrToHome modifies the structure pointed to by rect so that the modified structure will represent the same-shape rectangular area, but with topleft corner at position (0, 0). ScrToHome returns rect back (but note that the structure pointed to by it is modified).

Used by: cmd_disp, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, WinLineNC


ScrToWin

ScrToWin Function (ROM Call 0x2D)
graph.h

WIN_RECT *ScrToWin (const SCR_RECT *rect);

Converts a structure of type SCR_RECT to type WIN_RECT.

ScrToWin accepts a pointer rect to the structure of type SCR_RECT and returns a static pointer to a structure of type WIN_RECT which represents the same rectangular area. It is stored at a fixed place in memory, which means that you cannot write something like:

foo (ScrToWin (&r1), ScrToWin (&r2));

Used by: cmd_disp, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, DrawWinBorder, ROM Call 0x421


SetCurAttr

SetCurAttr Function (ROM Call 0x19A)
graph.h

short SetCurAttr (short Attr);

Sets the default attribute.

SetCurAttr sets the default attribute for all commands which haven't an attribute as an explicite parameter to Attr. The interpretation of the attribute depends of concrete graphic command. Some attributes are only valid for certain graphic operation. Legal attribute values are defined in enum Attrs. In a general, the following attributes are supported:

A_REVERSE | Destination pixels turned off
A_NORMAL | Destination pixels turned on
A_XOR | Source pixels XORed with destination pixels
A_SHADED | Destination pixels masked so that every other pixel turned off
A_REPLACE | Source pixels replace destination pixels
A_OR | Source pixels ORed with destination pixels

For lines the following additional attributes are supported:

A_THICK1 | Draw a double thick line
A_SHADE_V | Draw the line using a vertical shading pattern
A_SHADE_H | Draw the line using a horizontal shading pattern
A_SHADE_NS | Draw the line using a negative slope diagonal shading pattern
A_SHADE_PS | Draw the line using a positive slope diagonal shading pattern

SetCurAttr returns the previous current attribute.

Note: Although TI said nothing about it, attributes A_SHADE_V, A_SHADE_H, A_SHADE_NS and A_SHADE_PS work only for lines with slope more than 45 degree (i.e. for lines which are more "vertical" than "horizontal"). For "nearly horizontal" lines all of them act like A_NORMAL. I don't know whether it is a bug, or planned feature. So, if you want to draw shaded-fill rectangle using a line drawing command (for example, DrawLine) in a loop, use vertical lines for drawing, not horizontal ones! Note also that these additional attributes work fine with FillTriangle and FillLines2, but not with ScrRectFill!

Used by: DrawClipRect, DrawMultiLines, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, DrawWinBorder, ROM Call 0x421


SetCurClip

SetCurClip Function (ROM Call 0x19B)
graph.h

void SetCurClip (const SCR_RECT *clip);

Sets the default clipping area.

SetCurClip sets the default clipping area for commands which are sensitive to clipping, but which do not need a clipping area as an explicit parameter (such commands are LineTo and DrawClipPix). The clipping area is a rectangle with corners (x0, y0) and (x1, y1) which is given using a SCR_RECT structure clip. All clip-sensitive drawings will be clipped (truncated) at the current clipping area boundaries. Be warned: the default clipping area at the beginning of the program is not the full screen!

Note: GCC4TI is GNU C, so it allows cast constructors. That's why constructions like

SetCurClip (&(SCR_RECT){{0, 0, 159, 99}});
are legal.

Used by: DrawClipLine, DrawClipRect, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, DrawWinBorder, WinLineNC, ROM Call 0x421


sf_width

sf_width Function (ROM Call 0x4D3)
AMS 2.00 or higher graph.h

unsigned char sf_width(unsigned char character);

Returns the width in pixels of character character in the small font.

Uses: EV_runningApp, OO_GetAppAttr
Used by: ERD_notice, Dialog, ERD_dialog, DrawChar, DrawClipChar, DrawStr, DrawStrWidth, DrawStrWidthP, FontCharWidth, TE_focus, TE_handleEvent, TE_open, TE_openFixed, TE_pasteText, TE_select, TE_unfocus, WinChar, WinCharXY, WinStr, ROM Call 0x412

See also: DrawStrWidth, DrawStrWidthP, FontCharWidth


ScrRect

ScrRect Variable (ROM Call 0x2F)
graph.h

SCR_RECT *const ScrRect;

A global pointer to a SCR_RECT structure representing the whole screen.

ScrRect is a (constant) pointer to a SCR_RECT structure set by TIOS to point to a structure which represents the whole screen area without the status line. So, if you don't need drawing in the status line, you can set the default clipping area using the SetCurClip command like

SetCurClip (ScrRect);
or, you can use ScrRect in a command which needs clipping area parameter explicitely (such command is DrawClipEllipse, for example):
DrawClipEllipse (50, 50, 30, 20, ScrRect, A_NORMAL);
ScrRect may be used also to determine a calculator type. If
ScrRect->xy.x1 == 159
then the calculator is a TI-89 or TI-89 Titanium, else it is a TI-92 Plus or V200.

Note: ScrRect is a variable, so it may be changed (more precise, the structure on which it points may be changed). By changing it, it is possible to force some TIOS commands which normally cannot access to the status line area to get the access to this "forbidden" zone, or to force some commands to use only smaller part of the screen. Use this possibility with great care, and only if you know exactly what you are doing!

Used by: assert, MenuEnd, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, fputchar, paint_all_except, UpdateWindows, WinClr, WinRemove, ROM Call 0x3EA, ROM Call 0x421


BITMAP_HDR_SIZE

BITMAP_HDR_SIZE Constant
graph.h, wingraph.h

#define BITMAP_HDR_SIZE 4

Defines the size of the header of the BITMAP structure.


LCD_MEM

LCD_MEM Constant
graph.h

#define LCD_MEM ((void *) 0x4C00)

A pointer to the area in memory where the contents of the LCD screen are stored.

Used by: OSLinkCmd

See also: LCD_SIZE, LCD_BUFFER


LCD_SIZE

LCD_SIZE Constant
graph.h

#define LCD_SIZE 3840

An integer constant which represents the size of the LCD screen in bytes.

See also: LCD_MEM, LCD_BUFFER


Attrs

Attrs Type (Enumeration)
graph.h, graphing.h, unknown.h, wingraph.h

enum Attrs {A_REVERSE, A_NORMAL, A_XOR, A_SHADED, A_REPLACE, A_OR, A_AND, A_THICK1, A_SHADE_V, A_SHADE_H, A_SHADE_NS, A_SHADE_PS};

An enumeration for describing legal attribute values.

For more information about attributes, see the SetCurAttr command or the GR_WIN_VARS structure.

See also: SetCurAttr, GR_WIN_VARS, WinAttr, WinFillTriangle, ScrRectScroll, ScrRectFill, FillTriangle, DrawPix, DrawClipEllipse, DrawIcon, WinPixSet, DrawChar, WinBackground, WinEllipse, WinFill, BitmapPut, WinChar


BITMAP

BITMAP Type (Structure)
graph.h, wingraph.h, menus.h, unknown.h

typedef struct {
unsigned short NumRows, NumCols;
unsigned char Data[];
} BITMAP;

A structure for defining a bitmap.

BITMAP is a structure for defining a bitmap, used in commands like BitmapGet.

Note that Data[] is a GNU C extension for variable-length arrays (GCC4TI is GNU C).


BoxAttrs

BoxAttrs Type (Enumeration)
graph.h, wingraph.h

enum BoxAttrs {B_NORMAL = 0x10, B_ROUNDED = 0x20, B_DOUBLE = 0x40, B_CUT = 0x80};

An enumeration for describing addittional box attribute values.

For more info about box attributes, see the DrawClipRect command.


Fonts

Fonts Type (Enumeration)
graph.h, wingraph.h

enum Fonts {F_4x6, F_6x8, F_8x10};

An enumeration for describing legal font values.

For more info about fonts, see FontSetSys.


ICON

ICON Type (Structure)
graph.h, menus.h, wingraph.h

typedef struct {
unsigned short i[16];
} ICON;

A structure which describes an icon.

ICON is a structure which describes an icon (a 16x16 pixel area), which is used in the DrawIcon command.


LCD_BUFFER

LCD_BUFFER Type (Array)
graph.h

typedef char LCD_BUFFER[LCD_SIZE];

Describes a buffer to hold the screen contents.

LCD_BUFFER is a 3840-bytes long array type. Its main purpose is to declare a buffer for saving and restoring the contents of the LCD screen using the functions LCD_save and LCD_restore.

It is long enough to accept the content of the screen on both the TI-89 and the TI-92 Plus.

See also: LCD_MEM, LCD_SIZE


MULTI_LINE

MULTI_LINE Type (Structure)
graph.h

typedef struct {
unsigned char Count;
struct {
signed char Attr, x0, y0, x1, y1;
} Data[];
} MULTI_LINE;

A structure for defining multiple lines for the DrawMultiLines command.

Note that Data[] is a GNU C extension for variable-length arrays (GCC4TI is GNU C). Static variables of such types may be initialized with a variable-length constructor, for example:

static MULTI_LINE star_shape = {3, {{1, 30, 50, 70, 50},
                                    {1, 35, 35, 65, 65},
                                    {1, 35, 65, 65, 35}}};
Initialization with a variable-length constructor is not suitable for non-static (auto) variables, because the amount of stack storage will not be determined properly.


pICON

pICON Type (Pointer)
graph.h, menus.h, wingraph.h

typedef unsigned short *pICON;

A pointer to the ICON scructure.


SCR_COORDS

SCR_COORDS Type (Scalar)
graph.h, wingraph.h, unknown.h

typedef unsigned char SCR_COORDS;

An alias type for defining physical screen coordinates.


WIN_COORDS

WIN_COORDS Type (Scalar)
graph.h, wingraph.h, unknown.h

typedef short WIN_COORDS;

An alias type for defining logical screen coordinates.


graphing.h

graphing.h Header File
Header File Index

Routines, variables and structures related to graphing in general.

Functions
CkValidDelta
Checks the validity of a given delta.
CptDeltax
Computes the system variable Δx.
CptDeltay
Computes the system variable Δy.
gdb_len
Returns the length of the GDB in the current graph mode.
gdb_recall
Actual core of cmd_rclgdb.
gdb_store
Actual core of cmd_stogdb.
rngLen
Returns the size of the array pointed to by GR_WIN_VARS.rngp if the current graphing mode if GraphMode.
StepCk
Verifies that the input min, max, and step values are valid in parametric or polar mode.
Global Variables
gr_active
Pointer to the active GR_WIN_VARS struct.
gr_flags
Global flags used by the Graph application.
gr_other
Pointer to the second GR_WIN_VARS struct.
Predefined Types
Attrs
An enumeration for describing legal attribute values.
DB3
Structure for defining a 3D function spin database.
EQU_DS_AMS1
Structure for defining internal Y = Editor app data (AMS 1.xx version).
EQU_DS
Structure for defining internal Y = Editor app data.
ESI
Represents an index of a value on the TIOS expression stack.
FUNCID
Function identifier structure.
GR_FLAGS
A structure for defining global flags used by the Graph application.
GR_MODES
Structure for describing graph modes.
GR_WIN_VARS
Structure defining data for the graph related apps.
GraphModes
Describes different graphing modes.
GrFmtFlags2
Enumerates different Graph Format flags for the GR_MODES struct.
GrFmtFlags
Enumerates different Graph Format flags for the GR_MODES struct.
GrMode3dStyles
Enumerates different 3D Graph Style flags for the GR_MODES struct.
GrSides
Enumerates different Graph side flags for the GR_WIN_VARS struct.
GrWinFlags
Enumerates different Graph app flags for the GR_WIN_VARS struct.
HSym
A structure representing a symbol reference.
TABLE_WIN_VARS
Structure for defining Table app data.
TableFlags
Enumerates different Table app flags for the GR_WIN_VARS struct.
WINDOW_AMS1
The main window-describing structure (AMS 1.xx version).
WINDOW
The main window-describing structure.
WinVarEnum
Describes different Window variables.

Note: This header is currently very incomplete.


CkValidDelta

CkValidDelta Function (ROM Call 0x1C3)
graphing.h

unsigned char CkValidDelta (float maxrng, float minrng, float delta);

Checks the validity of a given delta.

CkValidDelta checks to see if the exponent of delta is too small relative to the exponents of maxrng and minrng so that all the significant digits of delta would be shifted out of the floating-point mantissa when performing arithmetic.

The parameter maxrng is the final value in the graph window variable sequence (e.g., xmax, ymax, tmax, etc.). The parameter minrng is the first value in the graph window variable sequence (e.g., xmin, ymin, tmin, etc.). The parameter delta is the increment value which will be used to compute the sequence from minrng to maxrng (e.g., Δx, Δy, tstep, etc.).

CkValidDelta returns 1 if delta is valid, 0 if the exponent of delta is too small.

Note: CkValidDelta assumes the sign of delta has already been verified as correct for computing a sequence from minrng to maxrng. It is valid for maxrng to be less than minrng if delta is negative.

Uses: _bcd_math
Used by: CptDeltax, StepCk, cmd_drawinv

See also: StepCk


CptDeltax

CptDeltax Function (ROM Call 0x1C1)
graphing.h

unsigned char CptDeltax (GR_WIN_VARS *);

Computes the system variable Δx.

Given a pointer to a GR_WIN_VARS structure (usually gr_active or gr_other), CptDeltax computes the system variable Δx.

This function calls ck_valid_float and CkValidDelta, among others.

Uses: CkValidDelta, ck_valid_float, _bcd_math
Used by: cmd_blddata, GT_ValidGraphRanges, GZ_Square, Regraph


CptDeltay

CptDeltay Function (ROM Call 0x1C2)
graphing.h

unsigned char CptDeltay (GR_WIN_VARS *);

Computes the system variable Δy.

Given a pointer to a GR_WIN_VARS structure (usually gr_active or gr_other), CptDeltay computes the system variable Δy.

This function calls ck_valid_float and CkValidDelta, among others.

Uses: ck_valid_float, _bcd_math
Used by: cmd_drawinv, GT_ValidGraphRanges, GZ_Square, Regraph


gdb_len

gdb_len Function (ROM Call 0x1E0)
graphing.h

unsigned long gdb_len (void);

Returns the length of the GDB in the current graph mode.

Used internally by cmd_stogdb, there's no point in using gdb_len directly.

Uses: gr_active, gr_other, rngLen, gr_initCondName, grFuncName, DerefSym, SymFindMain
Used by: GT_SaveAs, cmd_stogdb


gdb_recall

gdb_recall Function (ROM Call 0x1E2)
graphing.h

void gdb_recall (HSym var);

Actual core of cmd_rclgdb.

This is the routine which retrieves the current GDB from the variable described by var.
This routine is wrapped by cmd_rclgdb, which is basically a combination of VarRecall and gdb_recall, so there's no point in using gdb_recall directly.

Uses: gr_active, gr_other, rngLen, HeapAlloc, HeapAllocThrow, HeapFreeIndir, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, HToESI, MO_currentOptions, MO_digestOptions, memcpy, CreateEmptyList, FindGrFunc, gen_version, gr_DelFolder, gr_initCondName, grFuncName, DerefSym, HSymDel, SymFindMain, VarStore, WinClr, WinLineNC, WinPixSet
Used by: GT_Open, cmd_rclgdb


gdb_store

gdb_store Function (ROM Call 0x1E1)
graphing.h

void gdb_store (ESI dest);

Actual core of cmd_stogdb.

This is the routine which stores the current GDB at the memory location starting at dest.
This routine is wrapped by cmd_stogdb, so there's no point in using gdb_store directly.

Uses: gr_active, gr_other, rngLen, MO_currentOptions, memcpy, gr_initCondName, grFuncName, DerefSym, SymFindMain
Used by: cmd_stogdb, GT_SaveAs


rngLen

rngLen Function (ROM Call 0x1DF)
graphing.h

unsigned long rngLen (unsigned char GraphMode);

Returns the size of the array pointed to by GR_WIN_VARS.rngp if the current graphing mode if GraphMode.

This function is used by many ROM_CALLs related to graphing, through gdb_len, gdb_recall and gdb_store.

Valid values for GraphMode are described in GraphModes.

Used by: gdb_len, gdb_recall, gdb_store

See also: GR_WIN_VARS, GraphModes


StepCk

StepCk Function (ROM Call 0x1DD)
graphing.h

void StepCk (float *indep);

Verifies that the input min, max, and step values are valid in parametric or polar mode.

StepCk verifies that the input min, max, and step values in the array pointed to by indep are valid values for the independent variable in parametric mode (tmin, tmax, and tstep) or polar mode (θmin, θmax, and θstep). The function will return to the calling routine if the values are valid, otherwise an error is thrown.

indep is a pointer to an array of floating-point values where indep[0] = min, indep[1] = max, and indep[2] = step.

An error is thrown if the input values are not valid for the independent variable in parametric mode or polar mode, such as the step value being negative when it should have been positive for the given min and max.

Uses: CkValidDelta, floor, _bcd_math
Used by: cmd_blddata, cmd_drawparm, cmd_drawpol, deStepCk, Regraph

See also: CkValidDelta, error.h


gr_active

gr_active Variable (ROM Call 0x10B)
graphing.h

GR_WIN_VARS *gr_active;

Pointer to the active GR_WIN_VARS struct.

gr_active is a pointer to a GR_WIN_VARS struct that contain most of the data used by the Graph application and other graph-related apps. gr_active points to the GR_WIN_VARS struct containing all the information for the active graph (whereas gr_other points to the information for the second graph in two-graph mode). As the calculator user switches between the two windows in two-graph mode, the pointers in gr_active and gr_other are swapped so that gr_active is always referring to the active graph. The members of a GR_WIN_VARS struct are given along with an explanation of the contents of each in the description of GR_WIN_VARS. None of the data should be changed directly by a program, but can be accessed for use. System routines may be called to change many items (for example, VarStore may be used to change the graph system variables), but some data is for internal use only and should only be changed by the appropriate system app.

Used by: gdb_len, gdb_recall, gdb_store, cmd_andpic, cmd_blddata, cmd_circle, cmd_clrdraw, cmd_clrgraph, cmd_clrtable, cmd_cyclepic, cmd_disptbl, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_fnoff, cmd_fnon, cmd_line, cmd_linehorz, cmd_linetan, cmd_linevert, cmd_newplot, cmd_plotsoff, cmd_plotson, cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pttext, cmd_pxlchg, cmd_pxlcircle, cmd_pxlhorz, cmd_pxlline, cmd_pxloff, cmd_pxlon, cmd_pxltext, cmd_pxlvert, cmd_rclpic, cmd_rplcpic, cmd_shade, cmd_slpline, cmd_stopic, cmd_style, cmd_table, cmd_xorpic, push_pttest, push_pxltest, push_setgraph, EV_defaultHandler, MO_currentOptions, GD_Circle, GD_Contour, GD_Eraser, GD_HVLine, GD_Line, GD_Pen, GD_Select, GD_Text, GR3_paint3d, GR3_xyToWindow, GZ_Box, GZ_Center, HomePushEStack, OSLinkCmd, ROM Call 0x455, ROM Call 0x4CA, CheckGraphRef, de_initRes, de_loop, de_rng_no_graph, dv_create_graph_titles, EQU_deStatus, EQU_select, FindFunc, FindGrFunc, FirstSeqPlot, FuncLineFlt, GetStatValue, GetSysGraphRef, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_Shade, GM_TanLine, GM_Value, gr_add_fldpic, gr_ck_solvergraph, gr_CptIndepInc, gr_de_value, gr_del_locals, gr_del_vars_in_folder, gr_DispLabels, gr_execute_de, gr_execute_seq, gr_find_de_result, GR_Pan, gr_seq_value, gr_stopic, gr_xres_pixel, GR3_addContours, GR3_handleEvent, GraphActivate, GraphOrTableCmd, grFuncName, GrLineFlt, GS_PlotAll, GS_PlotTrace, GT_BackupToScr, GT_CalcDepVals, GT_CenterGraphCursor, GT_CursorKey, GT_DE_Init_Conds, GT_DspFreeTraceCoords, GT_DspMsg, GT_DspTraceCoords, GT_Format, GT_FreeTrace, GT_IncXY, GT_KeyIn, GT_Open, GT_QFloatCursorsInRange, GT_Regraph, GT_Regraph_if_neccy, GT_SaveAs, GT_SelFunc, GT_Set_Graph_Format, GT_SetCursorXY, GT_SetGraphRange, GT_ShowMarkers, GT_Trace, GT_ValidGraphRanges, GT_WinBound, GT_WinCursor, GZ_Decimal, GZ_Fit, GZ_InOut, GZ_Integer, GZ_Previous, GZ_Recall, GZ_Square, GZ_Standard, GZ_Stat, GZ_Store, GZ_Trig, InitDEAxesRng, InitDEMem, InitTimeSeq, NG_setup_graph_fun, PlotDel, PlotPut, QActivePlots, QPlotActive, Regraph, seqStepCk, seqWebInit, SetGraphMode, setup_more_graph_fun, spike_chk_gr_dirty, spike_in_editor, statFree, time_loop, VarGraphRefBitsClear, YCvtFtoP, YCvtFtoWin, FolderCur, VarRecall, VarStore

See also: GR_WIN_VARS, gr_other


gr_flags

gr_flags Variable (ROM Call 0x463)
AMS 2.00 or higher graphing.h

GR_FLAGS gr_flags;

Global flags used by the Graph application.

gr_flags returns the Global flags used by the Graph application. Each flag is a separate member of the GR_FLAGS struct. The contents of these flags should not be changed by a program, but may be accessed for testing the value. The names of the flags and their purposes are given with the GR_FLAGS struct.

Used by: cmd_blddata, GR3_paint3d, de_loop, FindFunc, GetStatValue, gr_ck_solvergraph, gr_de_value, gr_execute_de, gr_execute_seq, GrLineFlt, GS_PlotAll, GT_Trace, GZ_Stat, InitDEAxesRng, InitDEMem, Regraph, VarRecall, VarStore

See also: GR_FLAGS


gr_other

gr_other Variable (ROM Call 0x10C)
graphing.h

GR_WIN_VARS *gr_other;

Pointer to the second GR_WIN_VARS struct.

gr_other is a pointer to a GR_WIN_VARS struct that contain most of the data used by the Graph application and other graph related apps. gr_other points to the GR_WIN_VARS struct containing all the information for the second graph in two-graph mode (whereas gr_active points to the information for the active graph). As the calculator user switches between the two windows in two-graph mode, the pointers in gr_other and gr_active are swapped so that gr_active is always referring to the active graph. The members of a GR_WIN_VARS struct are given along with an explanation of the contents of each in the description of GR_WIN_VARS. None of the data should be changed directly by a program, but can be accessed for use. System routines may be called to change many items (for example, VarStore may be used to change the graph system variables), but some data is for internal use only and should only be changed by the appropriate system app.

Used by: gdb_len, gdb_recall, gdb_store, MO_currentOptions, OSLinkCmd, CheckGraphRef, EQU_setStyle, GetSysGraphRef, gr_add_fldpic, PlotDel, SetGraphMode, statFree, FolderCur, VarStore

See also: GR_WIN_VARS, gr_active


DB3

DB3 Type (Structure)
graphing.h, unknown.h

typedef struct {
long cVertices;
HANDLE hVertices;
long cEdges;
HANDLE hEdges;
HANDLE hContours;
long ciVertices;
HANDLE hiVertices;
long ciEdges;
HANDLE hiEdges;
short DCM[3][3];
short DCM0[3][3];
short DCMhome[3][3];
short cDCMangle;
unsigned short nSpinDir;
unsigned char nSpinSpeed;
unsigned char bSpinning;
short calp, salp;
} DB3;

Structure for defining a 3D function spin database.

Structure for defining a 3D function spin database. This structure is only used in the GR_WIN_VARS structure. It is not very well known, so if you have more information, please help.

See also: GR_WIN_VARS


EQU_DS_AMS1

EQU_DS_AMS1 Type (Structure)
graphing.h, unknown.h

typedef struct SEquDS_AMS1 {
WINDOW_AMS1 wMain;
short focus;
short cFunc;
short yPos;
short xOffset;
short yBelow;
unsigned short bAltForm;
} EQU_DS_AMS1;

Structure for defining internal Y = Editor app data (AMS 1.xx version).

EQU_DS_AMS1 is the AMS 1.xx version of the EQU_DS structure. It uses the AMS 1.xx version of the WINDOW structure.

See also: EQU_DS


EQU_DS

EQU_DS Type (Structure)
graphing.h, unknown.h

typedef struct SEquDS {
WINDOW wMain;
short focus;
short cFunc;
short yPos;
short xOffset;
short yBelow;
unsigned short bAltForm;
} EQU_DS;

Structure for defining internal Y = Editor app data.

Structure for defining internal Y = Editor app data. This structure is not very well known for the moment, and it is open to anyone who knows more than I do.

Anyway, this structure is needed by the GR_WIN_VARS structure.

See also: GR_WIN_VARS, EQU_DS_AMS1


FUNCID

FUNCID Type (Structure)
graphing.h, unknown.h

typedef struct {
unsigned char FNum;
unsigned char FNum2;
unsigned short LNum;
unsigned short PlotIndex;
unsigned char PlotDir;
} FUNCID;

Function identifier structure.

Function identifier structure. This structure is not very well known for the moment, and it is open to anyone who knows more than I do.

Anyway, this structure is needed by the GR_WIN_VARS structure.


GR_FLAGS

GR_FLAGS Type (Structure)
AMS 2.00 or higher graphing.h

typedef struct {
int gr_in_progress: 1;
int gr_zoom_fit: 1;
int gr_cpt_seq_flag: 1;
int stat_in_progress: 1;
int gr_trace_seq: 1;
int de_init_conds: 1;
int gr_cpt_de_flag: 1;
int new_eqn: 1;
int de_error: 1;
} GR_FLAGS;

A structure for defining global flags used by the Graph application.

The GR_FLAGS structure is used for defining global flags used by the Graph application (this structure is pointed to by gr_flags). Each flag is a separate member of the structure (each member is in fact a boolean value). The contents of these flags should not be changed by a program, but may be accessed for testing the value.

The purposes of these flags are:
gr_in_progress | A graph is currently being plotted. Among other things, this flag alerts VarRecall to set the graph reference flag for every user variable accessed until this flag is reset to enable the Smart Graph feature to work.
gr_zoom_fit | ZoomFit is being executed. Every graph point is computed to determine the min and max Window variable values, but while this flag is set, nothing is plotted.
gr_cpt_seq_flag | A graph sequence mode function (u1 - u99) is being executed.
stat_in_progress | A statistics calculation is currently being performed. Among other things, this flag alerts VarRecall to set the stat reference flag for every user variable accessed until this flag is reset to enable the calculator to determine when the statistics results are no longer valid.
gr_trace_seq | A sequence function is being traced.
de_init_conds | A differential equation is being plotted with initial conditions selected interactively using the graph cursor.
gr_cpt_de_flag | A differential equation graphing mode function (y1' - y99') is being executed.
new_eqn | The Numeric Solver system variable eqn has changed. This alerts the solver graph to regraph.
de_error | An error has occurred while computing a differential equation graphing mode function.

See also: gr_flags


GR_MODES

GR_MODES Type (Structure)
graphing.h, unknown.h

typedef struct {
unsigned short gr_fmt_flags; /* Graph Format flags */
unsigned char gr_xaxis; /* X Axis for SEQUENCE or DIFF EQUATIONS CUSTOM Axes setting */
signed char gr_yaxis; /* Y Axis for SEQUENCE or DIFF EQUATIONS CUSTOM Axes setting */
unsigned short gr_fmt_flags2; /* Graph Format flags */
unsigned char gr_3dflags; /* 3D Graph Style */
unsigned char pad; /* Unused. */
} GR_MODES;

Structure for describing graph modes.

The members of the GR_MODES struct and their contents are as follows:

Contents of the gr_fmt_flags (Graph Format flags) member as given in the GrFmtFlags enum:
GR_SEQ_TIME SEQUENCE Axes settings:
  • GR_SEQ_TIME = 1 and GR_SEQ_WEB = 0: TIME
  • GR_SEQ_TIME = 0 and GR_SEQ_WEB = 1: WEB
  • GR_SEQ_TIME = 0 and GR_SEQ_WEB = 0: CUSTOM
GR_SEQ_WEB
GR_BUILD_WEB SEQUENCE WEB Build Web:
  • GR_BUILD_WEB = 0: TRACE
  • GR_BUILD_WEB = 1: AUTO
GR_3dEXPAND Set for 3D expanded view mode.
GR_COORDOFF Graph Coordinates:
  • GR_COORDOFF = 0 and GR_COORD_POLAR = 0: RECT
  • GR_COORDOFF = 0 and GR_COORD_POLAR = 1: POLAR
  • GR_COORDOFF = 1: OFF
GR_COORD_POLAR
GR_SIMUL Graph Order:
  • GR_SIMUL = 0: SEQ
  • GR_SIMUL = 1: SIMUL
GR_GRIDON Graph Grid:
  • GR_GRIDON = 0: OFF
  • GR_GRIDON = 1: ON
GR_AXESOFF Graph Axes:
  • GR_AXESOFF = 0: ON
  • GR_AXESOFF = 1: OFF
GR_AXESBOX 3D Axes:
  • GR_AXESOFF = 1: OFF
  • GR_AXESOFF = 0 and GR_AXESBOX = 0: AXES
  • GR_AXESOFF = 0 and GR_AXESBOX = 1: BOX
GR_LABELSON Graph Labels:
  • GR_LABELSON = 0: OFF
  • GR_LABELSON = 1: ON
GR_LEAD_CURSOR Graph Leading Cursor:
  • GR_LEAD_CURSOR = 0: OFF
  • GR_LEAD_CURSOR = 1: ON

Meaning of the gr_xaxis member, X Axis for SEQUENCE or DIFF EQUATIONS CUSTOM Axes setting:

  • SEQUENCE X Axis:
    gr_xaxis value: meaning:
    -1 | n
    0 | u
    1,2,...,99 | u1,u2,...,u99
  • DIFF EQUATIONS X Axis:
    gr_xaxis value: meaning:
    -100 | y'
    -1,-2,...,-99 | y1',y2',...,y99'
    0 | t
    1,2,...,99 | y1,y2,...,y99
    100 | y

Meaning of the gr_yaxis member, Y Axis for SEQUENCE or DIFF EQUATIONS CUSTOM Axes setting:
  • SEQUENCE Y Axis:
    gr_yaxis value: meaning:
    -1 | n
    0 | u
    1,2,...,99 | u1,u2,...,u99
  • DIFF EQUATIONS Y Axis:
    gr_yaxis value: meaning:
    -100 | y'
    -1,-2,...,-99 | y1',y2',...,y99'
    0 | t
    1,2,...,99 | y1,y2,...,y99
    100 | y

Contents of the gr_fmt_flags2 (Graph Format flags) member as given in the GrFmtFlags2 enum:
GR_DE_CUSTOM GR_DE_CUSTOM = 1: DIFF EQUATIONS Axes = CUSTOM
GR_DE_FIELDS DIFF EQUATIONS Fields:
  • GR_DE_FIELDS = 1: SLPFLD
  • GR_DE_FIELDS = 0 and GR_DIRFLD = 1: DIRFLD
  • GR_DE_FIELDS = 0 and GR_DIRFLD = 0: FLDOFF
GR_DIRFLD
GR_EULER DIFF EQUATIONS Solution Method:
  • GR_EULER = 0: RK
  • GR_EULER = 1: EULER

Contents of the gr_3dflags (3D Graph Style) member as given in the GrMode3dStyles enum:
GR_3D_WIRE_FRAME | Wire frame
GR_3D_HIDDEN_SURFACE | Hidden surface
GR_3D_CONTOUR | Contour levels
GR_3D_CONTOUR_WIRE | Wire and contour
GR_3D_IMPLICIT | Implicit plot

See also: GR_WIN_VARS


GR_WIN_VARS

GR_WIN_VARS Type (Structure)
graphing.h, unknown.h

typedef struct {
float flt_xcursor; /* Graph system variable xc */
float flt_ycursor; /* Graph system variable yc */
float flt_zcursor; /* Graph system variable zc */
float flt_tcursor; /* Graph system variable tc */
float flt_rcursor; /* Graph system variable rc */
float flt_thetacursor; /* Graph system variable θc */
float flt_ncursor; /* Graph system variable nc */
float recip_delx; /* 1/Δx rounded to 6 significant digits */
float recip_dely; /* 1/Δy rounded to 6 significant digits */
float orgxmin; /* Original xmin, before any panning has occurred */
float orgxmax; /* Original xmax, before any panning has occurred */
float panshift; /* Number of columns panned from orgxmin */
float orgtblst; /* Original tblStart, before any scrolling has occurred */
float tblshift; /* Number of lines scrolled in table */
float tblstart; /* Table system variable tblStart */
float deltatbl; /* Table system variable Δtbl */
float *rngp; /* Pointer to current Window variables array */
float PrevRange[12]; /* Current ZoomPrev values */
float UserRange[29]; /* Current ZoomSto values */
GR_MODES *gr_modep; /* Pointer to GR_MODES struct for current graph */
WINDOW *grwinp; /* Pointer to current Graph app WINDOW struct */
WINDOW *rngwinp; /* Pointer to current Window Editor app WINDOW struct */
WINDOW *tblwinp; /* Pointer to current Table app WINDOW struct */
TABLE_WIN_VARS *tableptr; /* Pointer to internal Table app data */
union {
struct {
EQU_DS_AMS1 equedDS; /* Internal Y= Editor app data */
unsigned short curinc; /* Graph iteration counter */
unsigned short curincy; /* 3D y trace mode iteration counter */
unsigned short tblindx; /* Index of tblInput element at top of Table */
short yaxispix; /* Pixel number of y axis for panning */
unsigned short TBL_WidthLimit; /* Format width for Table app */
HANDLE zval; /* Handle of the 3D z value array */
DB3 DB3z; /* 3D function spin database */
HANDLE htbinput; /* Handle of the table system variable tblInput */
HANDLE hfldpic; /* Handle of the graph system variable fldpic */
unsigned short gr_win_flags; /* Graph app flags */
unsigned char xmaxpix; /* Rightmost column used by graph in current window */
unsigned char ymaxpix; /* Bottom row used by graph in current window */
unsigned char gr_ref_mask; /* Graph reference flag mask for current graph */
unsigned char graph_mode; /* Graph mode of current graph */
unsigned char gr_side; /* Graph window location */
unsigned char gr_folder_cnt; /* Number of functions created by the TI-BASIC Graph and Table commands */
unsigned char gr_shade_pat; /* Shade pattern */
unsigned char rng_xpix; /* Maximum x pixel number on Window Editor screen */
unsigned char rng_ypix; /* Maximum y pixel number on Window Editor screen */
unsigned char tbl_flags; /* Table app flags */
unsigned char tbl_par_flags; /* Internal Table app flags */
unsigned char gr_top_flags; /* Internal Graph app flags */
unsigned char ValidCursBits; /* Internal Graph app flags */
signed char de_twopass; /* Internal Graph app flags */
FUNCID CurFunc; /* Data for currently selected function for tracing */
unsigned char PrevZoomMode; /* Graph mode of current ZoomPrev values */
} ams1;
struct {
EQU_DS equedDS; /* Internal Y= Editor app data */
unsigned short curinc; /* Graph iteration counter */
unsigned short curincy; /* 3D y trace mode iteration counter */
unsigned short tblindx; /* Index of tblInput element at top of Table */
short yaxispix; /* Pixel number of y axis for panning */
unsigned short TBL_WidthLimit; /* Format width for Table app */
HANDLE zval; /* Handle of the 3D z value array */
DB3 DB3z; /* 3D function spin database */
HANDLE htbinput; /* Handle of the table system variable tblInput */
HANDLE hfldpic; /* Handle of the graph system variable fldpic */
unsigned short gr_win_flags; /* Graph app flags */
unsigned char xmaxpix; /* Rightmost column used by graph in current window */
unsigned char ymaxpix; /* Bottom row used by graph in current window */
unsigned char gr_ref_mask; /* Graph reference flag mask for current graph */
unsigned char graph_mode; /* Graph mode of current graph */
unsigned char gr_side; /* Graph window location */
unsigned char gr_folder_cnt; /* Number of functions created by the TI-BASIC Graph and Table commands */
unsigned char gr_shade_pat; /* Shade pattern */
unsigned char rng_xpix; /* Maximum x pixel number on Window Editor screen */
unsigned char rng_ypix; /* Maximum y pixel number on Window Editor screen */
unsigned char tbl_flags; /* Table app flags */
unsigned char tbl_par_flags; /* Internal Table app flags */
unsigned char gr_top_flags; /* Internal Graph app flags */
unsigned char ValidCursBits; /* Internal Graph app flags */
signed char de_twopass; /* Internal Graph app flags */
FUNCID CurFunc; /* Data for currently selected function for tracing */
unsigned char PrevZoomMode; /* Graph mode of current ZoomPrev values */
} ams2;
};
} GR_WIN_VARS;

Structure defining data for the graph related apps.

GR_WIN_VARS is a structure which contains most of the data used by the Graph Application and other graph-related apps.

Caution: This structure is different on AMS 1.xx and AMS 2.xx (34 bytes bigger on AMS 2.xx, see WINDOW_AMS1 for a more detailed explanation)!

There are two main GR_WIN_VARS structures in the calculator which are pointed by gr_active and gr_other. In most cases, you will not have to create a GR_WIN_VARS structure, and therefore the GR_WIN_VARS will only be useful to access data pointed to by gr_active or gr_other.

None of the data contained in the GR_WIN_VARS struct should be changed directly, but it can be accessed for use. System routines may be called to change many items (for example, VarStore may be used to change the graph system variables), but some data is for internal use only and should only be changed by the appropriate system app.

Here is an explanation of all the special structure members:

The size of the rngp array and the meaning of the elements depend on the current graphing mode (see GraphModes and rngLen). It can point to one of the following sets of indices, as described in the WinVarEnum enum:

  • FUNCTION mode indices:
    GR_XMIN | System variable xmin.
    GR_XMAX | System variable xmax.
    GR_XSCL | System variable xscl.
    GR_YMIN | System variable ymin.
    GR_YMAX | System variable ymax.
    GR_YSCL | System variable yscl.
    GR_DELTAX | System variable Δx.
    GR_DELTAY | System variable Δy.
    GR_XRES | System variable xres.

  • PARAMETRIC mode indices:
    GR_XMIN | System variable xmin.
    GR_XMAX | System variable xmax.
    GR_XSCL | System variable xscl.
    GR_YMIN | System variable ymin.
    GR_YMAX | System variable ymax.
    GR_YSCL | System variable yscl.
    GR_DELTAX | System variable Δx.
    GR_DELTAY | System variable Δy.
    GR_TMIN | System variable tmin.
    GR_TMAX | System variable tmax.
    GR_TSTEP | System variable tstep.

  • POLAR mode indices:
    GR_XMIN | System variable xmin.
    GR_XMAX | System variable xmax.
    GR_XSCL | System variable xscl.
    GR_YMIN | System variable ymin.
    GR_YMAX | System variable ymax.
    GR_YSCL | System variable yscl.
    GR_DELTAX | System variable Δx.
    GR_DELTAY | System variable Δy.
    GR_THETMIN | System variable θmin.
    GR_THETMAX | System variable θmax.
    GR_THETSTEP | System variable θstep.

  • SEQUENCE mode indices:
    GR_XMIN | System variable xmin.
    GR_XMAX | System variable xmax.
    GR_XSCL | System variable xscl.
    GR_YMIN | System variable ymin.
    GR_YMAX | System variable ymax.
    GR_YSCL | System variable yscl.
    GR_DELTAX | System variable Δx.
    GR_DELTAY | System variable Δy.
    GR_NMIN | System variable nmin.
    GR_NMAX | System variable nmax.
    GR_NPLOT | System variable plotStrt.
    GR_NSTEP | System variable plotStep.

  • 3D mode indices:
    GR_XMIN | System variable xmin.
    GR_XMAX | System variable xmax.
    GR_XGRID | System variable xgrid.
    GR_YMIN | System variable ymin.
    GR_YMAX | System variable ymax.
    GR_YGRID | System variable ygrid.
    GR_DELTAX | Internal data.
    GR_DELTAY | Internal data.
    GR_ZMIN | System variable zmin.
    GR_ZMAX | System variable zmax.
    GR_ZSCL | System variable zscl. (Note that zscl is not used on the TI-89, TI-89 Titanium, TI-92 Plus or Voyage 200.)
    GR_EYE_THETA | System variable eyeθ.
    GR_EYE_PHI | System variable eyeΦ.
    GR_EYE_PSI | System variable eyeΨ.
    GR_NCONTOUR | System variable ncontour.
    GR_XSCALE | Internal data.
    GR_YSCALE | Internal data.
    GR_ZSCALE | Internal data.

  • DIFF EQUATIONS mode indices:
    GR_XMIN | System variable xmin.
    GR_XMAX | System variable xmax.
    GR_XSCL | System variable xscl.
    GR_YMIN | System variable ymin.
    GR_YMAX | System variable ymax.
    GR_YSCL | System variable yscl.
    GR_DELTAX | System variable Δx.
    GR_DELTAY | System variable Δy.
    GR_T0 | System variable t0.
    GR_TMAX | System variable tmax.
    GR_TSTEP | System variable tstep.
    GR_TPLOT | System variable tplot.
    GR_DIFTOL | System variable diftol.
    GR_ESTEP | System variable Estep.
    GR_FLDRES | System variable fldres.
    GR_NCURVES | System variable ncurves.
    GR_DTIME | System variable dtime.

The parameter gr_win_flags can be a combination of the following as described in the GrWinFlags enum:
GR_REDRAW | Redraw 3D graph without recomputing.
GR_DIRTY | The current graph needs to be recomputed.
TAB_DIRTY | The current table needs to be recomputed.
GR_ADD_TO | Add a function to the current graph without recomputing.
GR_OPEN | The current graph window is open.
GRAPH_FOLDER | The temporary folder for functions created by the Graph and Table commands exists.
EYE_DIRTY | The eye of the 3D graph has changed.
GR_SHADE_NO_PAN | The panning is not valid after shading.
FLDPIC_DIRTY | The system variable fldpic needs to be recomputed.

The parameter graph_mode can be one of the following as described in the GraphModes enum:
GR_FUNC | FUNCTION mode.
GR_PAR | PARAMETRIC mode.
GR_POL | POLAR mode.
GR_SEQ | SEQUENCE mode.
GR_3D | 3D mode.
GR_DE | DIFF EQUATIONS mode.

The parameter gr_side can be one of the following as described in the GrSides enum:
AP_SIDE_A | Top or left split.
AP_SIDE_B | Bottom or right split.
AP_SIDE_UNKNOWN | Unknown.

The parameter gr_shade_pat can be one of the following as described in the Attrs enum:
A_SHADE_V | Vertical shade pattern.
A_SHADE_H | Horizontal shade pattern.
A_SHADE_NS | Negative slope 45° shade pattern.
A_SHADE_PS | Positive slope 45° shade pattern.

The parameter tbl_flags can be one of the following as described in the TableFlags enum:
TBL_CONNECT_TRC | Set when Graph<->Table = ON.
TBL_INDEP_ASK | Set when Independent = ASK.
TBL_NO_MODE_CHANGE | Set when executing the DispTbl command.


GrFmtFlags2

GrFmtFlags2 Type (Enumeration)
graphing.h, unknown.h

enum GrFmtFlags2 {
GR_DE_CUSTOM = 0x0010, GR_DE_FIELDS = 0x0004, GR_DIRFLD = 0x0002, GR_EULER = 0x0001
};

Enumerates different Graph Format flags for the GR_MODES struct.

Enumerates different Graph Format flags. The meaning of these flags is given in the description of GR_MODES.

See also: GR_MODES, GR_WIN_VARS


GrFmtFlags

GrFmtFlags Type (Enumeration)
graphing.h, unknown.h

enum GrFmtFlags {
GR_SEQ_TIME = 0x8000, GR_SEQ_WEB = 0x4000, GR_BUILD_WEB = 0x2000, GR_3dEXPAND = 0x0800, GR_COORDOFF = 0x0080, GR_SIMUL = 0x0040, GR_GRIDON = 0x0020, GR_AXESOFF = 0x0010,GR_AXESBOX = 0x0008, GR_LABELSON = 0x0004,GR_LEAD_CURSOR = 0x0002, GR_COORD_POLAR = 0x0001
};

Enumerates different Graph Format flags for the GR_MODES struct.

Enumerates different Graph Format flags. The meaning of these flags is given in the description of GR_MODES.

See also: GR_MODES, GR_WIN_VARS


GrMode3dStyles

GrMode3dStyles Type (Enumeration)
graphing.h, unknown.h

enum GrMode3dStyles {GR_3D_WIRE_FRAME = 0, GR_3D_HIDDEN_SURFACE = 1, GR_3D_CONTOUR = 2, GR_3D_CONTOUR_WIRE = 3, GR_3D_IMPLICIT = 4};

Enumerates different 3D Graph Style flags for the GR_MODES struct.

Enumerates different 3D Graph Style flags. The meaning of these flags is given in the description of GR_MODES.

See also: GR_MODES, GR_WIN_VARS


GrSides

GrSides Type (Enumeration)
graphing.h, unknown.h

enum GrSides {AP_SIDE_A = 0, AP_SIDE_B = 1, AP_SIDE_UNKNOWN = 2};

Enumerates different Graph side flags for the GR_WIN_VARS struct.

Enumerates different Graph side flags used in the GR_WIN_VARS structure.

The meaning of these flags is given in the description of GR_WIN_VARS.

See also: GR_WIN_VARS


GrWinFlags

GrWinFlags Type (Enumeration)
graphing.h, unknown.h

enum GrWinFlags {
GR_REDRAW = 0x0100, GR_DIRTY = 0x0080, TAB_DIRTY = 0x0040, GR_ADD_TO = 0x0020, GR_OPEN = 0x0010, GRAPH_FOLDER = 0x0008, EYE_DIRTY = 0x0004, GR_SHADE_NO_PAN = 0x0002, FLDPIC_DIRTY = 0x0001
} ;

Enumerates different Graph app flags for the GR_WIN_VARS struct.

Enumerates different Graph app flags used in the GR_WIN_VARS structure.

The meaning of these flags is given in the description of GR_WIN_VARS.

See also: GR_WIN_VARS


TABLE_WIN_VARS

TABLE_WIN_VARS Type (Structure)
graphing.h, unknown.h

typedef struct {
short last_col;
short last_row;
unsigned short table_xpix;
unsigned short table_ypix;
unsigned char curtblinc;
unsigned char curtblincy;
unsigned char col_first;
unsigned char col_last;
short row_first;
short row_last;
unsigned char tbfn[10];
unsigned char gr_xpix;
float orgtblmax;
} TABLE_WIN_VARS;

Structure for defining Table app data.

TABLE_WIN_VARS Structure is used to define Table app data. It is only used in the GR_WIN_VARS structure and is not very well known for the moment. If you have any information about this structure, please help.

See also: GR_WIN_VARS


TableFlags

TableFlags Type (Enumeration)
graphing.h, unknown.h

enum TableFlags {TBL_CONNECT_TRC = 0x80, TBL_INDEP_ASK = 0x40, TBL_NO_MODE_CHANGE = 0x20};

Enumerates different Table app flags for the GR_WIN_VARS struct.

Enumerates different Table app flags used in the GR_WIN_VARS structure.

The meaning of these flags is given in the description of GR_WIN_VARS.

See also: GR_WIN_VARS


WINDOW_AMS1

WINDOW_AMS1 Type (Structure)
graphing.h, wingraph.h, unknown.h

typedef struct WindowStruct_AMS1 {
unsigned short Flags; /* Window flags */
unsigned char CurFont; /* Current font */
unsigned char CurAttr; /* Current attribute */
unsigned char Background; /* Current background attribute */
short TaskId; /* Task ID of owner */
short CurX, CurY; /* Current (x,y) position (relative coordinates) */
short CursorX, CursorY; /* Cursor (x,y) position */
SCR_RECT Client; /* Client region of the window (excludes border) */
SCR_RECT Window; /* Entire window region including border */
SCR_RECT Clip; /* Current clipping region */
SCR_RECT Port; /* Port region for duplicate screen */
unsigned short DupScr; /* Handle of the duplicated or saved screen area */
struct WindowStruct *Next; /* Pointer to the next window in the linked list */
char *Title; /* Pointer to the (optional) title */
} WINDOW_AMS1;

The main window-describing structure (AMS 1.xx version).

WINDOW_AMS1 is the AMS 1.xx version of the WINDOW structure. It is a little smaller, since the last two fields are missing. Usually, this is not important, but it is a problem if a window structure is included in other structures (like EQU_DS).

See also: WINDOW


WinVarEnum

WinVarEnum Type (Enumeration)
graphing.h, unknown.h

enum WinVarEnum {GR_XMIN = 0, GR_XMAX = 1, GR_XSCL = 2, GR_YMIN = 3, R_YMAX = 4, GR_YSCL = 5, GR_DELTAX = 6, GR_DELTAY = 7, GR_XRES = 8, GR_TMIN = 8, GR_T0 = 8, GR_TMAX = 9, GR_TSTEP = 10, GR_TPLOT = 11, GR_DIFTOL = 12, GR_ESTEP = 13, GR_FLDRES = 14, GR_NCURVES = 15, GR_DTIME = 16, GR_THETMIN = 8, GR_THETMAX = 9, GR_THETSTEP = 10, GR_XGRID = 2, GR_YGRID = 5, GR_ZMIN = 8, GR_ZMAX = 9, GR_ZSCL = 10, GR_EYE_THETA = 11, GR_EYE_PHI = 12, GR_EYE_PSI = 13, GR_NCONTOUR = 14, GR_XSCALE = 15, GR_YSCALE = 16, GR_ZSCALE = 17, GR_NMIN = 8, GR_NMAX = 9, GR_NPLOT = 10, GR_NSTEP = 11};

Describes different Window variables.

WinVarEnum describes different Window variables. They are mainly used in the GR_WIN_VARS structure.

The meaning of the flags is explained in the description of GR_WIN_VARS.

See also: GR_WIN_VARS


gray.h

gray.h Header File
Header File Index

Routines for grayscale graphics

Functions
GrayAdjust
Adjusts grayscale support to make it flickerless.
GrayCheckRunning
Checks whether grayscale mode is active.
GrayDBufCleanup
Uninitializes grayscale double-buffering.
GrayDBufGetActiveIdx
Returns the index of the currently visible double buffer.
GrayDBufGetActivePlane
Returns a pointer to a specific plane of the currently visible buffer.
GrayDBufGetHiddenIdx
Returns the index of the currently invisible double buffer.
GrayDBufGetHiddenPlane
Returns a pointer to a specific plane of the currently hidden buffer.
GrayDBufGetPlane
Returns a pointer to a specific plane of a specific buffer.
GrayDBufInit
Initializes grayscale double-buffering mode.
GrayDBufSetActiveAMSPlane
Forces graphics routines to use selected plane of visible buffer.
GrayDBufSetActiveIdx
Sets the currently visible double buffer.
GrayDBufSetActiveIdxSync
Synchronizes and sets the currently visible double buffer.
GrayDBufSetAMSPlane
Forces graphics routines to use selected plane of a specific buffer.
GrayDBufSetHiddenAMSPlane
Forces graphics routines to use selected plane of hidden buffer.
GrayDBufToggle
Toggles the currently visible double buffer.
GrayDBufToggleSync
Synchronizes and toggles the currently visible double buffer.
GrayGetInt1Handler
Returns the interrupt handler executed by the grayscale algorithm.
GrayGetPlane
Gets the address of a grayscale plane.
GrayGetSwitchCount
Returns the current plane switch counter.
GrayGetVersionString
Returns the embedded grayscale support version string.
GrayMode
This function has become obsolete.
GrayOff
Deactivates grayscale mode.
GrayOn
Activates grayscale mode with four shades of gray.
GrayOnThrow
Activates grayscale mode, throwing an error if unsuccessful.
GraySetAMSPlane
Forces graphics routines to use selected plane.
GraySetInt1Handler
Sets the interrupt handler executed by the grayscale algorithm.
GraySetSwitchCount
Sets the current plane switch counter to a given value.
GrayWaitNSwitches
Waits for a given number of plane switches.
Constants
GRAYDBUFFER_SIZE
Specifies the necessary size of a user-allocated double-buffer.
Predefined Types
Bool
An enumeration to describe true or false values.
GrayModes
An enumeration to describe legal grayscale modes.
GrayPlanes
An enumeration to describe legal grayscale planes.
INT_HANDLER
A pointer to an interrupt handler.

See also: graph.h, sprites.h


GrayAdjust

GrayAdjust Function (Macro)
gray.h

void GrayAdjust (short adjustment);

Adjusts grayscale support to make it flickerless.

Note: This function has become more or less obsolete since the effect is hardly visible with the new HW2 grayscale support.

This function is introduced to improve grayscale support on HW2 calculators, i.e. to make it more flickerless (it can be used on HW1 calculators too, but HW1 grayscale support is usually satisfactorily flickerless by default). Namely, if the plane switching frequency is not well synchronized with the LCD refresh frequency, the flickering may be too ugly. Unfortunately, it is not possible to use hardwired values because this frequency drifts with the battery strength, so a value which is good if the batteries are full is not good if the batteries are worn out, and vice versa. So the only solution is to make the frequency ratio adjustable. This trick was used in Universal OS by Julien Muchembled to produce quite flickerless grayscale support on HW2 calculators (many thanks to him for telling to me about this). His grayscale support allows adjusting the LCD refresh frequency (by changing the logical height of the display) using the keys DIAMOND+LEFT/RIGHT.

This solution was a bit unflexible to me, so I decided to use slightly modified variant of Julien's method. I introduced the function GrayAdjust for fine adjusting of the grayscale quality. This function does exactly the same as pressing DIAMOND+LEFT/RIGHT in Universal OS, i.e. it adjusts the LCD refresh frequency. The default value for adjustment is 0, which means "factory settings". Values less than 0 increases and values greater than 0 decreases the LCD refresh frequency. Legal values for adjustment range from -28 to 127 on TI-89 and from 0 to 127 on TI-92+ (although only slight variations around 0 are meaningful, for example from -10 to +10). Note that values less than 0 are not allowed on the TI-92+, else strange things would happen with the screen (use macros from compat.h to check the calculator model).

So how would one use this function? You can put an option into your program which displays a grayscale picture, and ask the user to adjust the quality. Here is a simplified example (called "Adjust Grayscale") of the program which displays the full screen filled with dark gray, then allows adjusting the quality using the '+' and '-' keys (use 'ESC' for exit):

// Adjust grayscale quality using + and - keys.

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

// Main Function
void _main(void)
{
  int key, value = 0;
  if (!GrayOn ())
    return;
  GrayAdjust (value);
  memset (GetPlane (DARK_PLANE), 255, LCD_SIZE);  // Fill the dark plane and
  memset (GetPlane (LIGHT_PLANE), 0, LCD_SIZE);   //  clear the light plane
  while ((key=ngetchx ()) != KEY_ESC)
    {
      if (key== '+' && value < 127)
        value++;
      if (key== '-' && value > (TI89 ? -28 : 0))
        value--;
      GrayAdjust(value);
    }
  GrayOff ();
}
This program does not have to be embedded in your program: as the LCD refresh frequency is kept in the hardware register, it will still be valid after exiting from the program, so this example may be used as a standalone adjusting program. However, the factory settings are restored each time the calculator is turned on. If you embed the adjustment code in your program, it is not a bad idea to use the same adjustment key as used in Universal OS (DIAMOND+LEFT/RIGHT), due to conformance. These keys may be checked easily using pseudoconstants from the compat.h header file, as in
if (key == KEY_DIAMOND + KEY_LEFT) ...
Note: Changing adjustment also has influence to the lightness of the display, but you always can change the contrast the usual way. Increasing adjustment makes the display lighter, and decreasing it makes the display darker. Anyway, do not use this function for adjusting the display lightness. Its purpose is just to estabilish precise synchronization.


GrayCheckRunning

GrayCheckRunning Function (Macro)
gray.h

short GrayCheckRunning (void);

Checks whether grayscale mode is active.

GrayCheckRunning returns TRUE if grayscale mode is active, else returns FALSE.

Deprecated alias: IsGrayMode


GrayDBufCleanup

GrayDBufCleanup Function (Macro)
gray.h

void GrayDBufCleanup (void);

Uninitializes grayscale double-buffering.

GrayDBufCleanup turns off double-buffering mode, which should have been previously turned on with GrayDBufInit. After calling this function, you can operate in grayscale just like before calling GrayDBufInit. You do not need to call this function explicitly before GrayOff, as GrayOff will perform the necessary uninitialization itself.

Note: GrayDBufCleanup does not free the buffer passed to GrayDBufInit. You need to do this yourself afterwards, i.e. after calling this function or GrayOff.

See also: GrayDBufInit, GrayOff


GrayDBufGetActiveIdx

GrayDBufGetActiveIdx Function (Macro)
gray.h

short GrayDBufGetActiveIdx (void);

Returns the index of the currently visible double buffer.

GrayDBufGetActiveIdx returns the index of the visible double buffer. This index will be either 0 or 1, and can be passed to GrayDBufSetActiveIdx or GrayDBufGetPlane. Usually, you do not need to call this function directly.

See also: GrayDBufGetHiddenIdx, GrayDBufSetActiveIdx, GrayDBufGetActivePlane, GrayDBufSetActiveAMSPlane


GrayDBufGetActivePlane

GrayDBufGetActivePlane Function (Macro)
gray.h

void *GrayDBufGetActivePlane (short plane);

Returns a pointer to a specific plane of the currently visible buffer.

GrayDBufGetActivePlane acts like GrayGetPlane for the currently visible buffer (it calls GrayDBufGetPlane with the index returned from GrayDBufGetActiveIdx). Drawing into this buffer has (almost) direct effect on the contents of the screen.

See also: GrayDBufGetHiddenPlane, GrayGetPlane, GrayDBufGetPlane, GrayDBufToggle


GrayDBufGetHiddenIdx

GrayDBufGetHiddenIdx Function (Macro)
gray.h

short GrayDBufGetHiddenIdx (void);

Returns the index of the currently invisible double buffer.

GrayDBufGetHiddenIdx returns the index of the visible double buffer. This index will be either 0 or 1, and can be passed to GrayDBufSetActiveIdx or GrayDBufGetPlane. Usually, you do not need to call this function directly.

See also: GrayDBufGetActiveIdx, GrayDBufSetActiveIdx, GrayDBufGetHiddenPlane, GrayDBufSetHiddenAMSPlane


GrayDBufGetHiddenPlane

GrayDBufGetHiddenPlane Function (Macro)
gray.h

void *GrayDBufGetHiddenPlane (short plane);

Returns a pointer to a specific plane of the currently hidden buffer.

GrayDBufGetHiddenPlane acts like GrayGetPlane for the currently hidden buffer (it calls GrayDBufGetPlane with the index returned from GrayDBufGetActiveIdx). Drawing into this buffer has no effect on the contents of the screen until GrayDBufSetActiveIdx or GrayDBufToggle is called.

See also: GrayDBufGetActivePlane, GrayGetPlane, GrayDBufGetPlane, GrayDBufToggle


GrayDBufGetPlane

GrayDBufGetPlane Function (Macro)
gray.h

void *GrayDBufGetPlane (short idx, short plane);

Returns a pointer to a specific plane of a specific buffer.

GrayDBufGetPlane acts like GrayGetPlane, but it has an additional parameter idx which contains the index of the buffer for which the plane pointer should be returned. idx should be 0 or 1; it is usually a value returned from GrayDBufGetActiveIdx or GrayDBufGetHiddenIdx. Usually, you do not need to call this function explicitly; call GrayDBufGetActivePlane or GrayDBufGetHiddenPlane instead.

Drawing into the currently visible buffer has (almost) direct effect on the contents of the screen. Drawing into the hidden buffer has no effect until GrayDBufSetActiveIdx or GrayDBufToggle is called.

See also: GrayGetPlane, GrayDBufGetActivePlane, GrayDBufGetHiddenPlane, GrayDBufGetActiveIdx, GrayDBufGetHiddenIdx, GrayDBufSetActiveIdx


GrayDBufInit

GrayDBufInit Function (Macro)
gray.h

void GrayDBufInit (void *buf);

Initializes grayscale double-buffering mode.

GrayDBufInit initializes double-buffering mode. In double-buffering mode, you can switch between two buffers (using GrayDBufToggle) very quickly; much more quickly than using memcpy to achieve double-buffering. This function assumes that GrayOn has been called and its result was successful. To have as little extra double-buffering code in the grayscale implementation as possible, you need to allocate your own buffer and pass it to this function. You can do this with malloc, for example, but be sure to check its result before proceeding. The necessary size of the buffer (in bytes) is specified by the constant GRAYDBUFFER_SIZE.

You do not explicitly need to call GrayDBufCleanup to deactivate double-buffering mode; GrayOff will do the necessary uninitialization. However, be sure to free the buffer after calling GrayDBufCleanup or GrayOff.

The contents of the current grayscale buffer become the new contents of the plane with index 0 (see GrayDBufGetActiveIdx). The plane with index 1 is initialized from the new buffer and is filled either with random contents or with zeroes, depending on the contents of buf. Do not attempt to change the contents of buf directly after calling GrayDBufInit.

Note: After calling this function, you should not use the standard grayscale functions GrayGetPlane and GraySetAMSPlane any more. Instead, use the double-buffering functions GrayDBufGetPlane and GrayDBufSetAMSPlane or related ones.

See also: GrayDBufCleanup, GrayDBufSetActiveIdx, GrayDBufToggle


GrayDBufSetActiveAMSPlane

GrayDBufSetActiveAMSPlane Function (Macro)
gray.h

void GrayDBufSetActiveAMSPlane (short plane);

Forces graphics routines to use selected plane of visible buffer.

GrayDBufSetActiveAMSPlane acts like GraySetAMSPlane for the currently visible buffer (it calls GrayDBufSetAMSPlane with the index returned from GrayDBufGetActiveIdx). Drawing into this buffer has (almost) direct effect on the contents of the screen.

See also: GrayDBufSetHiddenAMSPlane, GraySetAMSPlane, GrayDBufSetAMSPlane, GrayDBufToggle


GrayDBufSetActiveIdx

GrayDBufSetActiveIdx Function (Macro)
gray.h

void GrayDBufSetActiveIdx (short idx);

Sets the currently visible double buffer.

GrayDBufSetActiveIdx sets the currently visible buffer to the one indexed by idx, which should be either 0 or 1. Afterwards, GrayDBufGetActiveIdx will return idx, and GrayDBufGetHiddenIdx will return the opposite. As the switch may happen during the time a plane is copied to the screen, it may be desirable to use GrayDBufSetActiveIdxSync instead.

See also: GrayDBufSetActiveIdxSync, GrayDBufToggle, GrayDBufToggleSync, GrayDBufGetActiveIdx, GrayDBufGetHiddenIdx


GrayDBufSetActiveIdxSync

GrayDBufSetActiveIdxSync Function (Macro)
gray.h

void GrayDBufSetActiveIdxSync (short idx);

Synchronizes and sets the currently visible double buffer.

GrayDBufSetActiveIdxSync waits until the next plane switch occurs (using GrayWaitNSwitches), then calls GrayDBufSetActiveIdx. This way you can make sure that the switch is not performed during an update of the screen, which would cause unwanted distortion effects.

See also: GrayDBufSetActiveIdx, GrayDBufToggleSync, GrayDBufToggle, GrayDBufGetActiveIdx, GrayDBufGetHiddenIdx


GrayDBufSetAMSPlane

GrayDBufSetAMSPlane Function (Macro)
gray.h

void GrayDBufSetAMSPlane (short idx, short plane);

Forces graphics routines to use selected plane of a specific buffer.

GrayDBufSetAMSPlane acts like GraySetAMSPlane, but it has an additional parameter idx which contains the index of the buffer for which the plane pointer should be returned. idx should be 0 or 1; it is usually a value returned from GrayDBufGetActiveIdx or GrayDBufGetHiddenIdx. Usually, you do not need to call this function explicitly; call GrayDBufSetActiveAMSPlane or GrayDBufSetHiddenAMSPlane instead.

Drawing into the currently visible buffer has (almost) direct effect on the contents of the screen. Drawing into the hidden buffer has no effect until GrayDBufSetActiveIdx or GrayDBufToggle is called.

See also: GraySetAMSPlane, GrayDBufSetActiveAMSPlane, GrayDBufSetHiddenAMSPlane, GrayDBufGetActiveIdx, GrayDBufGetHiddenIdx, GrayDBufSetActiveIdx


GrayDBufSetHiddenAMSPlane

GrayDBufSetHiddenAMSPlane Function (Macro)
gray.h

void GrayDBufSetHiddenAMSPlane (short plane);

Forces graphics routines to use selected plane of hidden buffer.

GrayDBufSetHiddenAMSPlane acts like GraySetAMSPlane for the currently hidden buffer (it calls GrayDBufSetAMSPlane with the index returned from GrayDBufGetHiddenIdx). Drawing into this buffer has no effect on the contents of the screen until GrayDBufSetActiveIdx or GrayDBufToggle is called.

See also: GrayDBufSetActiveAMSPlane, GraySetAMSPlane, GrayDBufSetAMSPlane, GrayDBufToggle


GrayDBufToggle

GrayDBufToggle Function (Macro)
gray.h

void GrayDBufToggle (void);

Toggles the currently visible double buffer.

GrayDBufToggle sets the currently visible buffer to the one which was previously hidden. Afterwards, the return values of GrayDBufGetActiveIdx and GrayDBufGetHiddenIdx will be the exact opposite as before. As the switch may happen during the time a plane is copied to the screen, it may be desirable to use GrayDBufToggleSync instead.

See also: GrayDBufToggleSync, GrayDBufSetActiveIdx, GrayDBufSetActiveIdxSync


GrayDBufToggleSync

GrayDBufToggleSync Function (Macro)
gray.h

void GrayDBufToggleSync (void);

Synchronizes and toggles the currently visible double buffer.

GrayDBufToggleSync waits until the next plane switch occurs (using GrayWaitNSwitches) and calls GrayDBufToggle. Due to grayscale routine implementation differences, the order of the synchronizing and switching depends on the hardware version. On HW1, the toggles are effective only after a plane switch, so GrayDBufToggleSync toggles first and waits for synchronization afterwards so as to keep you from writing into the "hidden" planes before they are actually hidden. On HW2 and higher, GrayDBufToggleSync waits for synchronization before toggling. This way you can make sure that the switch is not performed during an update of the screen, which would cause unwanted distortion effects.

See also: GrayDBufToggle, GrayDBufSetActiveIdxSync, GrayDBufSetActiveIdx


GrayGetInt1Handler

GrayGetInt1Handler Function (Macro)
gray.h

INT_HANDLER GrayGetInt1Handler (void);

Returns the interrupt handler executed by the grayscale algorithm.

GrayGetInt1Handler returns the interrupt handler which is called internally by the grayscale support. Use this function to store the interrupt temporarily when you are using GraySetInt1Handler to change it.

The interrupt handler called by the grayscale routines looks something like this (pseudo-code):

DEFINE_INT_HANDLER (GrayInt1Handler)
{
  SwitchPlanes ();
  ExecuteHandler (OldInt1);
}
where OldInt1 is the previous AUTO_INT_1 handler. GrayGetInt1Handler returns the value of OldInt1. Note that this is just a C-style declaration of the AUTO_INT_1 handler for grayscale; the actual one is implemented in assembly.

Deprecated alias: GetGrayInt1Handler

See also: GraySetInt1Handler, intr.h


GrayGetPlane

GrayGetPlane Function (Macro)
gray.h

void *GrayGetPlane (short plane);

Gets the address of a grayscale plane.

GrayGetPlane returns a pointer to the grayscale plane plane. Valid values for plane are LIGHT_PLANE and DARK_PLANE. To draw in black, draw in both planes.

Note: Do not assume that any plane is on 0x4C00 when in grayscale mode, due to hardware version 2 support. Also do not assume that the 2 grayscale planes are consecutive, this is not the case on hardware version 1.

Deprecated alias: GetPlane


GrayGetSwitchCount

GrayGetSwitchCount Function (Macro)
gray.h

unsigned long GrayGetSwitchCount (void);

Returns the current plane switch counter.

Antediluvian versions of grayscale support were lacking a mechanism to synchronize to the internal switching of the grayscales planes, which is quite necessary for almost any kind of "high-speed" games where the grayscale graphics change a lot.

This is why Thomas Nussbaumer implemented a plane switch counter which is increased after every processed plane switch.

A complete grayscale frame consists of 2 plane switches. GrayOn resets the switch counter value to 0.

A program which wants to synchronize to the plane switching within a loop can do this like this, for example:

unsigned long cur_count = GrayGetSwitchCount ();
do {
  unsigned long wait_for = cur_count + 2;
  while ((cur_count = GrayGetSwitchCount ()) < wait_for);
  // We'll always come here after the same plane
  // (dark plane or light plane) was switched.

  // Do something here ...

} while (some_condition);

Deprecated alias: GetGraySwitchCount

See also: GraySetSwitchCount


GrayGetVersionString

GrayGetVersionString Function (Macro)
gray.h

const char *GrayGetVersionString (void);

Returns the embedded grayscale support version string.

GrayGetVersionString returns the current version of the grayscale support in human-readable form. The version string is embedded in the program only if this macro is used at least once.


GrayMode

GrayMode Function (Macro)
gray.h

#define GrayMode(x) ((x) ? GrayOn () : ({
GrayOff ();
(short) 1;
}))

This function has become obsolete.

This function has become obsolete. You should use GrayOn and GrayOff now. GrayMode is implemented as a macro which calls one of these two functions; if mode is a constant, the compiler will optimize the code into a single function call.

Uses: GrayOn, GrayOff


GrayOff

GrayOff Function (tigcc.a)
gray.h

void GrayOff (void);

Deactivates grayscale mode.

This function deactivates grayscale mode. If grayscale mode is not activated, this function does nothing.

Uses: HeapFree, PortRestore
Used by: GrayMode

See also: GrayOn


GrayOn

GrayOn Function (tigcc.a)
gray.h

short GrayOn (void);

Activates grayscale mode with four shades of gray.

GrayOn activates grayscale mode. This works on both hardware version 1 and 2 calculators because the calculator type is detected automatically. See GrayAdjust for information on how to reduce flickering on HW2 calculators as much as possible.

The GrayMode function as well as the constants defined in the enum GrayModes still exist to maintain backwards compatibility with very old programs. In fact, GrayMode is now defined as a macro which optimizes into a call to GrayOn or GrayOff if you call it with a constant value.

GrayOn returns FALSE if there was an error in switching to grayscale mode, otherwise it returns TRUE. Don't forget to switch off grayscale mode before your program terminates, or your TI will crash very soon!

Here is an example of a program for testing grayscale mode (called "Gray Test Project"), which displays 3 squares on the screen, each with a different level of gray (see other functions from this header file and from the graph.h header file for an explanation about how it works):

// Grayscale test program for TIGCC

#define USE_TI89
#define USE_TI92PLUS
#define USE_V200

#define MIN_AMS 100
#define SAVE_SCREEN

#include <tigcclib.h>

void _main(void)
{
  if (!GrayOn ())
    return;
  GraySetAMSPlane (LIGHT_PLANE);
  ClrScr ();
  ScrRectFill (&(SCR_RECT){{20,20,40,40}}, ScrRect, A_NORMAL);
  ScrRectFill (&(SCR_RECT){{80,20,100,40}}, ScrRect, A_NORMAL);
  GraySetAMSPlane (DARK_PLANE);
  ClrScr ();
  ScrRectFill (&(SCR_RECT){{50,20,70,40}}, ScrRect, A_NORMAL);
  ScrRectFill (&(SCR_RECT){{80,20,100,40}}, ScrRect, A_NORMAL);
  ngetchx ();
  GrayOff ();
}
Starting from release 2.2 of the library, it is safe to call GrayOn even if grayscale mode is already on, and to call GrayOff even if grayscale mode is already off.

Uses: HeapAllocHigh, HeapDeref, PortSet
Used by: GrayMode, GrayOnThrow

See also: GrayOff, GrayOnThrow


GrayOnThrow

GrayOnThrow Function (tigcc.a)
gray.h

void GrayOnThrow (void);

Activates grayscale mode, throwing an error if unsuccessful.

GrayOnThrow works like GrayOn, except that it throws an error if it could not turn on grayscale successfully.

Uses: GrayOn

See also: GrayOn, GrayOff, error.h


GraySetAMSPlane

GraySetAMSPlane Function (Macro)
gray.h

void GraySetAMSPlane (short plane);

Forces graphics routines to use selected plane.

GraySetAMSPlane forces all graphics routines (from graph.h) to draw into the grayscale plane plane (valid values are LIGHT_PLANE and DARK_PLANE). This way you can use standard routines for drawing lines, circles, etc. in grayscale mode as well. In fact, GraySetAMSPlane is a macro which calls GrayGetPlane and PortSet.

Uses: PortSet

Deprecated alias: SetPlane


GraySetInt1Handler

GraySetInt1Handler Function (Macro)
gray.h

void GraySetInt1Handler (INT_HANDLER handler);

Sets the interrupt handler executed by the grayscale algorithm.

GraySetInt1Handler sets the interrupt handler which is called internally by the grayscale support to handler. Using this function, you can redirect this interrupt even in grayscale mode.

The interrupt handler called by the grayscale routines looks something like this (pseudo-code):

DEFINE_INT_HANDLER (GrayInt1Handler)
{
  SwitchPlanes ();
  ExecuteHandler (OldInt1);
}
where OldInt1 is the previous AUTO_INT_1 handler. GraySetInt1Handler sets the value of OldInt1 to handler. Note that this is just a C-style declaration of the AUTO_INT_1 handler for grayscale; the actual one is implemented in assembly.

Note: Always reset the handler to the previous value (returned by GrayGetInt1Handler) before turning off grayscale, otherwise it will be installed as a permanent interrupt handler.

Deprecated alias: SetGrayInt1Handler

See also: GrayGetInt1Handler, intr.h


GraySetSwitchCount

GraySetSwitchCount Function (Macro)
gray.h

void GraySetSwitchCount (unsigned long val);

Sets the current plane switch counter to a given value.

See GrayGetSwitchCount for information on the switch counter.

Deprecated alias: SetGraySwitchCount

See also: GrayGetSwitchCount


GrayWaitNSwitches

GrayWaitNSwitches Function (Macro)
gray.h

void GrayWaitNSwitches (short wait);

Waits for a given number of plane switches.

GrayWaitNSwitches waits for wait plane switches to happen before returning. If wait is 1, the function waits until the next plane switch occurs, so you can synchronize your program to the grayscale plane switches. Since the switches happen periodically, you can be pretty sure that no switch will occur too soon after you call this function. Using GrayGetSwitchCount and GraySetSwitchCount, you can also choose exactly after which plane the function returns.

See also: GrayGetSwitchCount


GRAYDBUFFER_SIZE

GRAYDBUFFER_SIZE Constant
gray.h

#define GRAYDBUFFER_SIZE 7688

Specifies the necessary size of a user-allocated double-buffer.

As GrayDBufInit requires the user to pass a user-allocated buffer as a parameter, this constant has been introduced to specify the size of this buffer. Note that it is not exactly 2*LCD_SIZE.


GrayModes

GrayModes Type (Enumeration)
gray.h

enum GrayModes {GRAY_OFF = 0, GRAY_ON = 1, GRAY_HW1 = 1, GRAY_HW2 = 1};

An enumeration to describe legal grayscale modes.

This type has become obsolete upon the introduction of GrayOn and GrayOff.


GrayPlanes

GrayPlanes Type (Enumeration)
gray.h

enum GrayPlanes {LIGHT_PLANE = 0, DARK_PLANE = 1};

An enumeration to describe legal grayscale planes.


INT_HANDLER

INT_HANDLER Type (Pointer)
intr.h, gray.h

A pointer to an interrupt handler.

INT_HANDLER is a pointer type which represents the address of the interrupt handler. It might be logical that INT_HANDLER is defined as a pointer to a void function, i.e.

typedef void (*INT_HANDLER)(void);
But this is not true. Instead, INT_HANDLER is a pointer to a strange structure (its shape is completely irrelevant, as this structure is never used, neither explicitely nor implicitely). Such unusual behaviour is implemented due to safety reasons. First, with such implementation it is impossible to call an interrupt handler using a simple function call (which would be possible if INT_HANDLER is implemented as a pointer to a function). Second, as INT_HANDLER is a pointer to an unusual structure, the compiler can emit a warning if you try to pass anything which is not created using DEFINE_INT_HANDLER or returned from GetIntVec to the functions SetIntVec and ExecuteHandler. For example, you will be warned if you try to pass an ordinary void function instead of properly-defined interrupt handler to the SetIntVec.


homescr.h

homescr.h Header File
Header File Index

Home Screen manipulation routines

Functions
HomeAlone
Checks if the Home Screen is active in full-screen mode.
HomeExecute
Sends a command to the Home Screen.
HomePushEStack
Creates and draws a new history pair with given contents.
HomeStore
Creates a new history pair with contents from the expression stack.
HomeStorePair
Creates a new history pair with given contents.
HS_chopFIFO
Deletes all history items which exceed the limit.
HS_countFIFO
Returns the number of history pairs.
HS_deleteFIFONode
Deletes a history entry/answer pair.
HS_freeAll
Clears the Home Screen history.
HS_freeFIFONode
Frees a FIFO node.
HS_getAns
Returns the handle of a Home Screen answer.
HS_getEntry
Returns the handle of a Home Screen entry.
HS_getFIFONode
Returns the handle of a history pair.
HS_newFIFONode
Allocates memory for a new FIFO node.
HS_popEStack
Pops the entire expression stack into memory.
HS_pushEmptyFIFONode
Inserts a new almost-empty FIFO node into the history.
HS_pushFIFONode
Inserts a new filled FIFO node into the history.
Global Variables
HS_FirstFIFONodeHandle
The handle of the FIFO node related to the first entry of the Home Screen history.
HS_MaxExpressions
The maximum number of expressions allowed in the home screen.
Constants
H_NULL
A null-handle value.
Predefined Types
Bool
An enumeration to describe true or false values.
ESQ
Represents a quantum within an expression.
FIFO_ELEMENT
A structure describing a single entry or answer element in the history.
FIFO_NODE
Describes an entry/answer pair in the history.
HANDLE
Represents a handle associated with an allocated memory block.
MULTI_EXPR
Describes a multi-expression, which is processed as a separate expression stack.

Note: In most cases, this header file is used to store expressions in the Home Screen history. For this purpose, use the HomeStore and HomeStorePair functions. They are much less complicated than the other functions manipulating the history.


HomeAlone

HomeAlone Function (ROM Call 0x506)
AMS 2.00 or higher homescr.h

unsigned short HomeAlone (void);

Checks if the Home Screen is active in full-screen mode.

HomeAlone returns TRUE if the Home Screen is active on a full screen and events are not captured, and FALSE otherwise.

Uses: EV_currentApp
Used by: kbhit, ngetchx


HomeExecute

HomeExecute Function (ROM Call 0x10E)
homescr.h

void HomeExecute (const char *Command, unsigned short ComLen);

Sends a command to the Home Screen.

This function sends an ordinary ANSI C string pointed to by Command (which does not have to be zero-terminated) to the Home Screen application, which will execute it exactly as if the string was typed in from the keyboard into the Home Screen entry line. ComLen must be smaller or equal to the length of Command.

Uses: HS_chopFIFO, HS_countFIFO, HS_freeAll, HS_freeFIFONode, HS_getFIFONode, HS_newFIFONode, HS_popEStack, HS_pushFIFONode, HeapAlloc, HeapAllocThrow, HeapFree, HeapFreeIndir, HeapLock, HeapMoveHigh, HeapRealloc, HeapUnlock, HLock, push_ratio, Dialog, DialogAdd, DialogDo, DialogNew, ER_catch, ER_success, ER_throwVar, ERD_dialog, ERD_process, find_error_message, ARb_int_count, ARb_real_count, bottom_estack, HToESI, NG_execute, NG_RPNToText, NG_tokenize, Parms2D, Parse2DMultiExpr, Print2DExpr, push_internal_simplify, push_parse_text, push_quantum, reset_control_flags, reset_estack_size, top_estack, EV_defaultHandler, EV_paintWindows, EV_sendEvent, EV_setCmdState, EV_setFKeyState, EV_startApp, EV_switch, MO_option, OSWriteLinkBlock, memcpy, PopupNew, PopupText, ST_stack, sprintf, strlen, OSClearBreak, OSSetSR, XR_stringPtr, TE_focus, TE_handleEvent, TE_isBlank, TE_pasteText, TE_reopen, TE_reopenPlain, TE_select, TE_shrinkWrap, TE_unfocus, EV_currentApp, EV_errorCode, EV_quit, has_unit_base, push_simplify_statements, FolderOp, SymFindFirst, SymFindNext, DrawWinBorder, WinActivate, WinAttr, WinBackupToScr, WinBegin, WinCharXY, WinClr, WinDeactivate, WinFill, WinHeight, WinHide, WinStrXY, WinWidth, ROM Call 0x45E, ROM Call 0x471, ROM Call 0x502, ROM Call 0x5CA, ROM Call 0x5CC, HS_FirstFIFONodeHandle, HS_MaxExpressions


HomePushEStack

HomePushEStack Function (ROM Call 0x10F)
homescr.h

void HomePushEStack (void);

Creates and draws a new history pair with given contents.

HomePushEStack is a very powerful command which lets you store expressions straight to the history.

The expression (not a multi-expression) which you want to store to the history has to be placed at the top of the expression stack. This function will pop it off of the estack and into the history. It will be used as both entry and answer, but it will not be simplified.

The result of using this call is that memory is allocated, so garbage collection may occur. After your program exits, the allocated memory will remain allocated, which is perfectly normal. However, kernels like DoorsOS, TeOS, and PreOS (but not UniversalOS) have a feature that frees all handles left unfreed by kernel programs. This feature is smart and first checks if a handle is that of a variable, but older kernels do not check if it is a history item.

For kernel-based programs, DoorsOS and TeOS will free the handles for the newly stored item, and when your program exits, the calculator will crash! PreOs 0.62 or higher detects the history handles and handles them correctly.

HomePushEStack calls HS_newFIFONode and HS_pushEmptyFIFONode to create the new history item.

Note: HomePushEStack redraws the home screen if it is the active application, which it most likely is. To circumvent this, use HomeStore.

Uses: HS_countFIFO, HS_freeFIFONode, HS_newFIFONode, HS_pushEmptyFIFONode, HS_pushFIFONode, HeapAllocThrow, HeapFreeIndir, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, NG_RPNToText, Parms2D, Parse2DMultiExpr, top_estack, gr_active, memcpy, ST_helpMsg, ST_stack, strlen, XR_stringPtr, EV_currentApp, paint_all_except, WinHeight, WinWidth, ROM Call 0x471, HS_FirstFIFONodeHandle, HS_MaxExpressions
Used by: HomeStore, GT_IncXY, GT_Trace

See also: HomeStore, HomeStorePair, HS_popEStack


HomeStore

HomeStore Function (tigcc.a)
homescr.h

void HomeStore (void);

Creates a new history pair with contents from the expression stack.

HomeStore performs the same operation as HomePushEStack. However, the visuals for storing something to the history with HomePushEStack will be done immediately, over top of your program's visuals, if the home screen is the current application, which it most likely is. This function suppresses this.

However, HomeStore still displays a message in the status bar saying "DATA PLACED IN HOME SCREEN HISTORY," and turns on the busy indicator.

HomeStore is implemented in assembly, using the following code as a starting point:

CALLBACK void TempHook(EVENT *ev)
{
  ev->Type = CM_IDLE;
}

void HomeStore(void)
{
  EVENT_HANDLER temp = EV_hook;
  EV_hook = TempHook;
  HomePushEStack ();
  EV_hook = temp;
}

Uses: HomePushEStack, EV_hook

See also: HomePushEStack, HomeStorePair, HS_popEStack


HomeStorePair

HomeStorePair Function (tigcc.a)
homescr.h

void HomeStorePair (HANDLE Entry, HANDLE Ans);

Creates a new history pair with given contents.

HomeStorePair creates a new Home Screen history pair with a given entry and answer part. Entry and Ans have to point to multi-expressions (see MULTI_EXPR). They may be the same handles; in this case, the same expression will be used on both sides of the screen.

HomeStorePair first uses HS_newFIFONode to allocate memory for a new FIFO node, then fills the Expr fields of the entry and answer elements with Entry and Ans, and then calls HS_pushEmptyFIFONode. If HS_pushEmptyFIFONode throws an error, it calls HS_freeFIFONode to free all handles, even Entry and Ans.

In any case, the expressions pointed to by Entry and Ans should not be modified after calling this function. In fact, the two handles then belong to the operating system, and should not be used any more.

Note: It seems that the handles Entry and Ans should be allocated with HeapAlloc (or HeapAllocThrow), and should not be locked. Be sure to read the notes about HS_pushEmptyFIFONode as well.

Uses: HS_newFIFONode, HS_freeFIFONode, HS_pushEmptyFIFONode, HeapDeref, HeapFree, ER_catch, ER_success, ER_throwVar

See also: HomeStore, HS_pushEmptyFIFONode


HS_chopFIFO

HS_chopFIFO Function (ROM Call 0x23C)
homescr.h

void HS_chopFIFO (void);

Deletes all history items which exceed the limit.

HS_copyFIFO deletes all Home Screen history pairs which exceed the limit set by the user. It is called internally by HS_pushFIFONode, so usually you do not need to call it yourself.

Uses: HS_deleteFIFONode, HS_getFIFONode, HS_MaxExpressions
Used by: HomeExecute, HS_pushFIFONode


HS_countFIFO

HS_countFIFO Function (ROM Call 0x23D)
homescr.h

unsigned short HS_countFIFO (void);

Returns the number of history pairs.

HS_countFIFO returns the number of entry/answer pairs in the history.

Uses: HS_FirstFIFONodeHandle
Used by: HomeExecute, HomePushEStack, cmd_disphome


HS_deleteFIFONode

HS_deleteFIFONode Function (ROM Call 0x23E)
homescr.h

HANDLE HS_deleteFIFONode (HANDLE Node);

Deletes a history entry/answer pair.

HS_deleteFIFONode deletes the history pair associated with Node, and returns the handle of the next history item in the linked list of FIFO nodes. To do this, it removes the node from the linked list, and then calls HS_freeFIFONode.

Uses: HS_freeFIFONode, HS_FirstFIFONodeHandle
Used by: HS_chopFIFO

See also: HS_pushFIFONode


HS_freeAll

HS_freeAll Function (ROM Call 0x23F)
homescr.h

void HS_freeAll (void);

Clears the Home Screen history.

HS_freeAll clears the history, freeing all nodes. This function calls HS_freeFIFONode repeatedly.

Uses: HS_freeFIFONode, HS_FirstFIFONodeHandle
Used by: HomeExecute, cmd_clrhome

See also: cmd_clrhome


HS_freeFIFONode

HS_freeFIFONode Function (ROM Call 0x240)
homescr.h

void HS_freeFIFONode (HANDLE Node);

Frees a FIFO node.

HS_freeFIFONode frees the node pointed to by Node, including the expressions it contains. The node should have been allocated with HS_newFIFONode. This function takes into account that the handles for the entry and answer may be the same.

This function is called by HS_deleteFIFONode and HS_freeAll. You should call it yourself only if you want to free a node you have allocated yourself, but which you could not insert into the history using HS_pushFIFONode.

Uses: HeapFree, HeapFreeIndir
Used by: HomeExecute, HomePushEStack, HomeStorePair, HS_deleteFIFONode, HS_freeAll

See also: HS_newFIFONode, HS_deleteFIFONode


HS_getAns

HS_getAns Function (ROM Call 0x241)
homescr.h

HANDLE HS_getAns (unsigned short Index);

Returns the handle of a Home Screen answer.

HS_getAns returns a handle to the answer part of the Home Screen history pair with index Index, where Index is a value between 1 and 99 and has the same meaning as the parameter of the TI-Basic 'ans' pseudo-function. If the answer does not exist, HS_getAns returns H_NULL. This happens in three conditions

  • The entry/answer pair does not exist.
  • The answer is a message like "Done" that comes after an executed program.
  • The answer is an error message (i.e. ERROR_MSG_TAG is present in it).
The returned handle contains a "multi-expression"; see MULTI_EXPR and HS_getEntry for more info.

Uses: HS_getFIFONode, HToESI
Used by: push_ans_entry

See also: HS_getEntry, HS_getFIFONode


HS_getEntry

HS_getEntry Function (ROM Call 0x242)
homescr.h

HANDLE HS_getEntry (unsigned short Index);

Returns the handle of a Home Screen entry.

HS_getEntry returns a handle to the entry part of the Home Screen history pair with index Index, where Index is a value between 1 and 99 and has the same meaning as the parameter of the TI-Basic 'entry' pseudo-function. If the entry does not exist, HS_getEntry returns H_NULL.

The returned handle contains a "multi-expression". A multi-expression is an expression consisting of multiple expressions seperated by NEXTEXPR_TAG and ending in ENDSTACK_TAG. See MULTI_EXPR for more info.

Even if the multi-expression contains only one expression and therefore has no NEXTEXPR_TAGs in it, it will still have an ENDSTACK_TAG.

The handle returned by this funtion is valid input for HToESI and Parse2DMultiExpr.

Uses: HS_getFIFONode
Used by: TE_handleEvent, push_ans_entry

See also: HS_getAns, HS_getFIFONode


HS_getFIFONode

HS_getFIFONode Function (ROM Call 0x243)
homescr.h

HANDLE HS_getFIFONode (unsigned short Index);

Returns the handle of a history pair.

This function returns the handle of an entry/answer pair in the Home Screen history. Dereferencing this handle using HeapDeref or HLock returns a pointer to a FIFO_NODE structure containing the handles of the entry and answer and some additional information.

Uses: HS_FirstFIFONodeHandle
Used by: HomeExecute, HS_chopFIFO, HS_getAns, HS_getEntry

See also: HS_getEntry, HS_getAns


HS_newFIFONode

HS_newFIFONode Function (ROM Call 0x245)
homescr.h

HANDLE HS_newFIFONode (void);

Allocates memory for a new FIFO node.

HS_newFIFONode simpy allocates 56 bytes for a FIFO_NODE structure and sets them all to zero. It throws an error if there is not enough memory.

Uses: HeapAllocThrow, memset
Used by: HomeExecute, HomePushEStack, HomeStorePair


HS_pushEmptyFIFONode

HS_pushEmptyFIFONode Function (ROM Call*)
homescr.h

void HS_pushEmptyFIFONode (HANDLE Node);

Inserts a new almost-empty FIFO node into the history.

HS_pushEmptyFIFONode inserts the entry/answer pair identified by Node into the linked list of FIFO nodes. Node must contain a handle to a FIFO_NODE structure, but only the Expr fields of the entry and answer need to be filled. It should have been allocated using HS_newFIFONode.

This function first fills the structure pointed to by Node, then calls HS_pushFIFONode to insert the new node. Unfortunately, it also calls ST_stack from statline.h to redraw the history status line indicator of the Home Screen, which cannot be prevented using PortSet or the method used in HomeStore. In theory, it is possible to fill the structure by hand, but this is very tedious.

Note: The address of the HS_pushEmptyFIFONode function is not in the jump table of any AMS version up to 2.05, and probably will never be. Getting the address of this function is implemented using a very dirty hack. However, it is the main function for storing items in the Home Screen history, so you probably cannot avoid it unless you want to fill the FIFO_NODE structure yourself. An error is thrown if the address of this function could not be determined.

Uses: HS_pushFIFONode
Used by: HomePushEStack, HomeStorePair

See also: HS_pushFIFONode, HomeStorePair


HS_pushFIFONode

HS_pushFIFONode Function (ROM Call 0x246)
homescr.h

void HS_pushFIFONode (HANDLE Node);

Inserts a new filled FIFO node into the history.

HS_pushFIFONode inserts the entry/answer pair identified by Node into the linked list of FIFO nodes. Node must contain a handle to a FIFO_NODE structure, which needs to be filled completely except for the Prev and Next fields. It should have been allocated using HS_newFIFONode.

This function calls HS_chopFIFO to remove the last history pair if needed. It may throw an error if inserting the node was not possible.

Uses: HS_chopFIFO, HS_FirstFIFONodeHandle
Used by: HomeExecute, HomePushEStack, HS_pushEmptyFIFONode

See also: HS_pushEmptyFIFONode, HomeStorePair


HS_FirstFIFONodeHandle

HS_FirstFIFONodeHandle Variable (ROM Call 0x5DD)
AMS 2.04 or higher homescr.h

const HANDLE HS_FirstFIFONodeHandle;

The handle of the FIFO node related to the first entry of the Home Screen history.

Warning: performing inappropriate changes to HS_FirstFIFONodeHandle may cause strange things on your calculator...

Used by: HomeExecute, HomePushEStack, HS_countFIFO, HS_deleteFIFONode, HS_freeAll, HS_getFIFONode, HS_pushFIFONode

See also: FIFO_NODE


HS_MaxExpressions

HS_MaxExpressions Variable (ROM Call 0x5DE)
AMS 2.04 or higher homescr.h

const unsigned short HS_MaxExpressions;

The maximum number of expressions allowed in the home screen.

Warning: performing inappropriate changes to HS_MaxExpressions may cause strange things on your calculator...

Used by: cmd_disphome, HomeExecute, HomePushEStack, HS_chopFIFO


FIFO_ELEMENT

FIFO_ELEMENT Type (Structure)
homescr.h

typedef struct {
short ScreenLeft;
long ScreenBottom;
long XStart;
unsigned short Width;
unsigned short Height;
short Top;
HANDLE Expr;
short TooLong;
short PrettyPrint;
unsigned short Exp;
unsigned short Fix;
} FIFO_ELEMENT;

A structure describing a single entry or answer element in the history.

FIFO_ELEMENT is a structure used by the TIOS to describe a single entry or answer on the screen. It is included twice in the FIFO_NODE structure. In most cases, you do not need to access the individual fields of this structure directly.

Expr contains a handle to the actual expression (a multi-expression, see MULTI_EXPR). You can fill the Width and Height fields using the Parms2D function. You should also know that the values for the Fix and Exp fields need to be one less than the values in MO_OPTIONS.

FIFO elements are displayed using Parse2DMultiExpr, and then Print2DExpr if PrettyPrint is TRUE, or WinCharXY otherwise.

See also: FIFO_NODE


FIFO_NODE

FIFO_NODE Type (Structure)
homescr.h

typedef struct {
FIFO_ELEMENT Entry;
FIFO_ELEMENT Ans;
HANDLE Prev;
HANDLE Next;
} FIFO_NODE;

Describes an entry/answer pair in the history.

FIFO_NODE describes an entry/answer pair (a node) in the Home Screen history. Usually, you do not need to access the fields of this structure directly.

All nodes are kept in a bidirectionally linked list; the Prev and Next fields contain handles to the previous and next nodes, respectively.

The Expr fields of the Entry and Ans fields of this structure may contain the same handles.

See also: FIFO_ELEMENT


intr.h

intr.h Header File
Header File Index

Routines for creating interrupt handlers

Language Extensions
DEFINE_INT_HANDLER
Defines an interrupt handler function.
Functions
AUTO_INT
Gets an address of an interrupt vector.
DisablePRG
Disables the programmable rate generator.
DUMMY_HANDLER
A dummy interrupt handler doing nothing.
EnablePRG
Enables the programmable rate generator.
ExecuteHandler
Executes an interrupt handler.
GetIntVec
Gets an interrupt vector.
IsPRGEnabled
Determines whether the programmable rate generator is enabled.
PRG_getRate
Returns the speed at which the programmable rate generator is incremented.
PRG_getStart
Returns the starting value of the programmable rate generator variable.
PRG_getValue
Returns the current value stored in the programmable rate generator.
PRG_setRate
Sets the speed at which the programmable rate generator is incremented.
PRG_setStart
Specifies the starting value of the variable incremented by the programmable rate generator.
SetIntVec
Sets an interrupt vector.
TRAP
Gets an address of a trap vector.
Constants
AUTO_INT_COUNT
Returns the total number of Auto-Int vectors.
FIRST_AUTO_INT
Returns the index of the first Auto-Int vector.
FIRST_TRAP
Returns the index of the first Auto-Int vector.
LAST_AUTO_INT
Returns the index of the last Auto-Int vector.
LAST_TRAP
Returns the index of the last Auto-Int vector.
TRAP_COUNT
Returns the total number of Auto-Int vectors.
Predefined Types
Bool
An enumeration to describe true or false values.
INT_HANDLER
A pointer to an interrupt handler.
IntVecs
An enumeration describing interrupt vectors.


DEFINE_INT_HANDLER

DEFINE_INT_HANDLER Language Extension
intr.h

Defines an interrupt handler function.

DEFINE_INT_HANDLER is a language extension macro which is used for defining interrupt handlers. The syntax is similar to function definition:

DEFINE_INT_HANDLER (HandlerName)
{
  // The body of the handler...
}
Note, however, that DEFINE_INT_HANDLER does not define a standard function: it constructs an object named HandlerName of INT_HANDLER type, which is initialized to point to the handler body (implemented internally as a function, but unaccessable directly to the rest of the program). So, you cannot call the interrupt handler using a standard call construction like
HandlerName ();
Such behaviour is implemented due to safety reasons: interrupt handlers are not supposed to be executed directly. If you need to call the interrupt handler anyway, you can use ExecuteHandler function. Here is an example of the program which installs the new (user-defined) interrupt handler for auto interrupt 5 (the programable timer interrupt), in which the old (default) handler is called as well (called "Interrupt Handler"):
// Interrupt handler incrementing a counter

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

INT_HANDLER OldInt5 = NULL;
volatile int Counter = 0;

DEFINE_INT_HANDLER(MyInt5)
{
  Counter++;
  ExecuteHandler (OldInt5);
}

void _main(void)
{
  OldInt5 = GetIntVec (AUTO_INT_5);
  SetIntVec (AUTO_INT_5, MyInt5);
  while (!kbhit()) printf_xy (50, 50, "Counter = %d  ", Counter);
  SetIntVec (AUTO_INT_5, OldInt5);
  GKeyFlush ();
}
The only legal usage of INT_HANDLER objects is to be passed as arguments to the functions SetIntVec or ExecuteHandler.

Be aware that the variable Counter in above example is declared as volatile. In fact, any global variable which may be changed by the interrupt handler should be declared as volatile, especially if it is accessed from the other parts of the program (i.e. out of the interrupt handler). This is necessary to prevent various optimizations which may be fooled by the fact that the variable may be changed in a way which is completely unpredictable from the aspect of the normal program flow. For example, various optimizations may force keeping the variable content in a register, so if the variable is changed asynchronously, the compiler will not know anything about it. volatile will prevent keeping the variable in a register, so it will be reloaded from the memory on each access. The example given above will still work if you omit the volatile keyword, but more complicated programs will probably not work correctly without it.


AUTO_INT

AUTO_INT Function (Macro)
intr.h

#define AUTO_INT(IntNo) ((long) (IntNo) * 4 + 0x60)

Gets an address of an interrupt vector.

AUTO_INT returns the absolute address where the interrupt vector for Auto-Int IntNo is located.

You can use it together with FIRST_AUTO_INT, LAST_AUTO_INT, and AUTO_INT_COUNT to loop through all interrupts.


DisablePRG

DisablePRG Function (Macro)
intr.h

void DisablePRG (void);

Disables the programmable rate generator.

DisablePRG disables the programmable rate generator, which means that the value determined by PRG_getValue does not change and AUTO_INT_5 is not called any more.

Note: Auto interrupt 5 is used by the AMS, so the previous state (which can be determined using IsPRGEnabled) should be restored before the program terminates.

This macro does not work in VTI 2.5 Beta 5.

See also: EnablePRG, OSRegisterTimer


DUMMY_HANDLER

DUMMY_HANDLER Function (tigcc.a)
intr.h

INT_HANDLER DUMMY_HANDLER;

A dummy interrupt handler doing nothing.

DUMMY_HANDLER is an interrupt handler of type INT_HANDLER which consists only of 'rte'. The purpose of this handler is to redirect an interrupt vector to "nothing", in cases when disabling interrupts is not possible. For example, you cannot disable auto-int 1 in grayscale programs, because grayscale support is based on it. Grayscale support installs its own auto-int 1 handler, which executes the previously installed handler at the end. Suppose that you don't want it to call the default auto-int 1 handler, which trashes the status line by displaying keyboard status indicators. You can redirect auto-int 1 to the dummy handler before enabling grayscale, so after the grayscale interrupt, the dummy handler (i.e. nothing) will be called instead of the default auto-int 1 handler:

INT_HANDLER save_int_1;
...
save_int_1 = GetIntVec (AUTO_INT_1);
SetIntVec (AUTO_INT_1, DUMMY_HANDLER);   // redirect auto-int 1 to "nothing"
// enable grayscale
// do whatever you want in grayscale
// disable grayscale
SetIntVec (AUTO_INT_1, save_int_1);


EnablePRG

EnablePRG Function (Macro)
intr.h

void EnablePRG (void);

Enables the programmable rate generator.

The programmable rate generator is used by the AMS and is normally on. If it has been disabled using DisablePRG, EnablePRG re-enables it.

This macro does not work in VTI 2.5 Beta 5.

See also: DisablePRG, OSRegisterTimer


ExecuteHandler

ExecuteHandler Function (Macro)
intr.h

void ExecuteHandler (INT_HANDLER Handler);

Executes an interrupt handler.

ExecuteHandler executes the interrupt handler pointed to by Handler. The only purpose of this function is to allow calling the previous interrupt handler (usually the default one) from the user-defined interrupt handler. This function must not be executed from anywhere out of the user-defined interrupt handler (defined using DEFINE_INT_HANDLER). Otherwise, you will get the "Privilege Violation" crash, because all interrupt handlers expect to be executed in the supervisor CPU mode. Parameter Handler should be either the value returned from GetIntVec, or the address of a user-defined interrupt handler defined using DEFINE_INT_HANDLER. It must not be the address of an ordinary C function. See DEFINE_INT_HANDLER for an example of usage.


GetIntVec

GetIntVec Function (Macro)
intr.h

INT_HANDLER GetIntVec (long IntVec);

Gets an interrupt vector.

GetIntVec gets the content of the interrupt vector located at the absolute address IntVec (typical values of IntVec are defined in enum IntVecs). Typical usage of this function is to get the current content of the interrupt vector to be restored later. See DEFINE_INT_HANDLER for an example of usage.

See also: SetIntVec, IntVecs


IsPRGEnabled

IsPRGEnabled Function (Macro)
intr.h

short IsPRGEnabled (void);

Determines whether the programmable rate generator is enabled.

The programmable rate generator is used by the AMS and is normally on. However, if you enable or disable it in a program, first you should check whether it is currently enabled, which can be done with this macro.

See also: EnablePRG, DisablePRG


PRG_getRate

PRG_getRate Function (Macro)
intr.h

short PRG_getRate (void);

Returns the speed at which the programmable rate generator is incremented.

This function returns the current speed of the programmable rate generator. For more information, see PRG_setRate.

See also: PRG_setRate


PRG_getStart

PRG_getStart Function (tigcc.a)
intr.h

unsigned char PRG_getStart (void);

Returns the starting value of the programmable rate generator variable.

PRG_getStart returns the starting value of the variable incremented by the programmable rate generator. For more information about this variable, see PRG_getValue.

See also: PRG_setStart, PRG_getValue


PRG_getValue

PRG_getValue Function (Macro)
intr.h

unsigned char PRG_getValue (void);

Returns the current value stored in the programmable rate generator.

PRG_getValue returns the current value of the variable incremented by the programmable rate generator. When this value overflows from 0xFF to 0x00, auto interrupt 5 will be triggered (see PRG_setStart for more information about this value, and SetIntVec for more information about auto interrupts).

See also: PRG_setStart, PRG_setRate


PRG_setRate

PRG_setRate Function (Macro)
intr.h

void PRG_setRate (short rate);

Sets the speed at which the programmable rate generator is incremented.

The programmable rate generator's speed can be controlled by this function. Valid values for rate are as follows:

Value | Speed
0 | OSC2/2^5 (highest rate)
1 | OSC2/2^9 (default)
2 | OSC2/2^12
3 | OSC2/2^18 (lowest rate)

Note: Before exiting your program, it is good practice to restore the programmable rate generator to its previous value (determined by PRG_getRate) so that the AMS does not misbehave.

See also: PRG_getRate


PRG_setStart

PRG_setStart Function (Macro)
intr.h

void PRG_setStart (unsigned char val);

Specifies the starting value of the variable incremented by the programmable rate generator.

PRG_setStart sets the starting value of the variable incremented by the programmable rate generator. This variable is incremented by 1 every time the programmable rate generator is triggered (at a speed which can be set using PRG_setRate). When it overflows from 0xFF to 0x00, auto interrupt 5 is triggered, and it is reset to val. To conclude, the way the value of this variable changes is shown here:

..., val, val+1, ..., 0xFF, 0x00, (auto interrupt 5), val, val+1, ...

Note: If a program uses this function, it should restore the previous value before the end of the program, as determined by PRG_getStart.

See also: PRG_getStart, PRG_setRate


SetIntVec

SetIntVec Function (Macro)
intr.h

void SetIntVec (long IntVec, INT_HANDLER Handler);

Sets an interrupt vector.

SetIntVec sets the interrupt vector located at the absolute address IntVec to the interrupt handler pointed to by Handler. Handler should be either a value returned from GetIntVec, or the address of a user-defined interrupt handler defined using DEFINE_INT_HANDLER. Note that Handler may not be the address of an ordinary C function.

Typical values of IntVec are given in the following table as enumerated in the IntVecs enum:

Address | Associated Constant | Triggered On
0x04 | INT_VEC_RESET | Reset (contains pointer to OS entry point)
0x08 | INT_VEC_BUS_ERROR | Bus error
0x0C | INT_VEC_ADDRESS_ERROR | Address error (accessing a short or long at an odd address)
0x10 | INT_VEC_ILLEGAL_INSTRUCTION | Illegal instruction
0x14 | INT_VEC_ZERO_DIVIDE | Division by zero
0x18 | INT_VEC_CHK_INS | CHK instruction
0x1C | INT_VEC_TRAPV_INS | TRAPV instruction
0x20 | INT_VEC_PRIVILEGE_VIOLATION | Privilege violation
0x24 | INT_VEC_TRACE | Code Tracing
0x28 | INT_VEC_LINE_1010 | Special instructions generated by ER_throw (0xA???)
0x2C | INT_VEC_LINE_1111 | F-Line instructions (0xF???)
0x3C | INT_VEC_UNINITIALIZED_INT | Uninitialized interrupt vector
0x60 | INT_VEC_SPURIOUS_INT | Spurious interrupt
0x64 | AUTO_INT_1 | Main timer hardware interrupt running at approximately 350 Hz
0x68 | AUTO_INT_2 INT_VEC_KEY_PRESS | Key press (triggered periodically while key(s) other than 'ON' are held down; the rate depends both on battery strength and on which keys are being held down, and is usually in the ballpark of about 600 Hz)
0x6C | AUTO_INT_3 | On most calculators, triggers once per second if enabled using a certain instruction
0x70 | AUTO_INT_4 INT_VEC_LINK | Link port activity
0x74 | AUTO_INT_5 | System timer running at approximately 18 Hz (see PRG_setRate, PRG_setStart)
0x78 | AUTO_INT_6 INT_VEC_ON_KEY_PRESS | 'ON' key press
0x7C | AUTO_INT_7 INT_VEC_STACK_OVERFLOW | Stack overflow (actually results in Protected Memory Violation)

All traps may be triggered manually using the TRAP assembler instruction.

Address | Associated Constant | Default Behavior
0x80 | TRAP_0 | (unknown)
0x84 | TRAP_1 INT_VEC_INT_MASK | Change interrupt mask (bits 8-10 of %sr) to %d0.w, output old mask in %d0.l
0x88 | TRAP_2 INT_VEC_MANUAL_RESET | Reset calculator
0x8C | TRAP_3 | (unknown)
0x90 | TRAP_4 INT_VEC_OFF | Turn the calculator off and wait for 'ON' key press
0x94 | TRAP_5 | (unknown)
0x98 | TRAP_6 | (unknown)
0x9C | TRAP_7 | (unknown)
0xA0 | TRAP_8 | (unknown)
0xA4 | TRAP_9 | Access to various system routines
0xA8 | TRAP_10 INT_VEC_SELF_TEST | Enter self test
0xAC | TRAP_11 INT_VEC_ARCHIVE | Print "Trap 11" and freeze
0xB0 | TRAP_12 | Put the processor in supervisor mode; return the previous value of the status register in %d0:w
0xB4 | TRAP_13 | Print "Trap 13" and freeze
0xB8 | TRAP_14 | Print "Trap 14" and freeze
0xBC | TRAP_15 INT_VEC_ER_THROW | Print "ER_throw" and freeze

See DEFINE_INT_HANDLER for an example of usage.

See also: GetIntVec, IntVecs, DEFINE_INT_HANDLER


TRAP

TRAP Function (Macro)
intr.h

#define TRAP(TrapNo) ((long) (TrapNo) * 4 + 0x80)

Gets an address of a trap vector.

TRAP returns the absolute address where the interrupt vector for Trap TrapNo is located.

You can use it together with FIRST_TRAP, LAST_TRAP, and TRAP_COUNT to loop through all traps.


AUTO_INT_COUNT

AUTO_INT_COUNT Constant
intr.h

#define AUTO_INT_COUNT (LAST_AUTO_INT - FIRST_AUTO_INT + 1)

Returns the total number of Auto-Int vectors.

You can use it together with FIRST_AUTO_INT, LAST_AUTO_INT, and AUTO_INT to loop through all interrupts.


FIRST_AUTO_INT

FIRST_AUTO_INT Constant
intr.h

#define FIRST_AUTO_INT 1

Returns the index of the first Auto-Int vector.

You can use it together with LAST_AUTO_INT, AUTO_INT_COUNT, and AUTO_INT to loop through all interrupts.


FIRST_TRAP

FIRST_TRAP Constant
intr.h

#define FIRST_TRAP 0

Returns the index of the first Auto-Int vector.

You can use it together with LAST_TRAP, TRAP_COUNT, and TRAP to loop through all interrupts.


LAST_AUTO_INT

LAST_AUTO_INT Constant
intr.h

#define LAST_AUTO_INT 7

Returns the index of the last Auto-Int vector.

You can use this together with FIRST_AUTO_INT, AUTO_INT_COUNT, and AUTO_INT to loop through all interrupts.


LAST_TRAP

LAST_TRAP Constant
intr.h

#define LAST_TRAP 15

Returns the index of the last Auto-Int vector.

You can use this together with FIRST_TRAP, TRAP_COUNT, and TRAP to loop through all interrupts.


TRAP_COUNT

TRAP_COUNT Constant
intr.h

#define TRAP_COUNT (LAST_TRAP - FIRST_TRAP + 1)

Returns the total number of Auto-Int vectors.

You can use it together with FIRST_TRAP, LAST_TRAP, and TRAP to loop through all interrupts.


IntVecs

IntVecs Type (Enumeration)
intr.h

enum IntVecs {AUTO_INT_1 = 0x64, AUTO_INT_2 = 0x68, AUTO_INT_3 = 0x6C, AUTO_INT_4 = 0x70, AUTO_INT_5 = 0x74, AUTO_INT_6 = 0x78, AUTO_INT_7 = 0x7C, TRAP_0 = 0x80, TRAP_1 = 0x84, TRAP_2 = 0x88, TRAP_3 = 0x8C, TRAP_4 = 0x90, TRAP_5 = 0x94, TRAP_6 = 0x98, TRAP_7 = 0x9C, TRAP_8 = 0xA0, TRAP_9 = 0xA4, TRAP_10 = 0xA8, TRAP_11 = 0xAC, TRAP_12 = 0xB0, TRAP_13 = 0xB4, TRAP_14 = 0xB8, TRAP_15 = 0xBC, INT_VEC_RESET = 0x04, INT_VEC_BUS_ERROR = 0x08, INT_VEC_ADDRESS_ERROR = 0x0C, INT_VEC_ILLEGAL_INSTRUCTION = 0x10, INT_VEC_ZERO_DIVIDE = 0x14, INT_VEC_CHK_INS = 0x18, INT_VEC_TRAPV_INS = 0x1C, INT_VEC_PRIVILEGE_VIOLATION = 0x20, INT_VEC_TRACE = 0x24, INT_VEC_LINE_1010 = 0x28, INT_VEC_LINE_1111 = 0x2C, INT_VEC_UNINITIALIZED_INT = 0x3C, INT_VEC_SPURIOUS_INT = 0x60, INT_VEC_KEY_PRESS = 0x68, INT_VEC_LINK = 0x70, INT_VEC_ON_KEY_PRESS = 0x78, INT_VEC_STACK_OVERFLOW = 0x7C, INT_VEC_INT_MASK = 0x84, INT_VEC_MANUAL_RESET = 0x88, INT_VEC_OFF = 0x90, INT_VEC_SELF_TEST = 0xA8, INT_VEC_ARCHIVE = 0xAC, INT_VEC_ER_THROW = 0xBC};

An enumeration describing interrupt vectors.

IntVecs is an enumeration for easier access to the standard interrupt vectors. These include the usual auto-interrupts and traps as well as the other predefined interrupts, which are triggered in special cases.

Note that some traps have their own names. For example, TRAP_4 equals INT_VEC_OFF.

Deprecated alias: AutoInts

See also: SetIntVec, GetIntVec


inttypes.h

inttypes.h Header File
Header File Index

C99 standard header file containing string constants usable in format arguments to printf-type and scanf-type functions, for printing and scanning the portable integer types defined in stdint.h.

Constants
PRId8
Format specifier for printing an integer of type int8_t or uint8_t as a signed decimal integer.
PRId16
Format specifier for printing an integer of type int16_t or uint16_t as a signed decimal integer.
PRId32
Format specifier for printing an integer of type int32_t or uint32_t as a signed decimal integer.
PRIdFAST8
Format specifier for printing an integer of type int_fast8_t or uint_fast8_t as a signed decimal integer.
PRIdFAST16
Format specifier for printing an integer of type int_fast16_t or uint_fast16_t as a signed decimal integer.
PRIdFAST32
Format specifier for printing an integer of type int_fast32_t or uint_fast32_t as a signed decimal integer.
PRIdLEAST8
Format specifier for printing an integer of type int_least8_t or uint_least8_t as a signed decimal integer.
PRIdLEAST16
Format specifier for printing an integer of type int_least16_t or uint_least16_t as a signed decimal integer.
PRIdLEAST32
Format specifier for printing an integer of type int_least32_t or uint_least32_t as a signed decimal integer.
PRIdPTR
Format specifier for printing an integer of type intptr_t or uintptr_t as a signed decimal integer.
PRIi8
Format specifier for printing an integer of type int8_t or uint8_t as a signed decimal integer.
PRIi16
Format specifier for printing an integer of type int16_t or uint16_t as a signed decimal integer.
PRIi32
Format specifier for printing an integer of type int32_t or uint32_t as a signed decimal integer.
PRIiFAST8
Format specifier for printing an integer of type int_fast8_t or uint_fast8_t as a signed decimal integer.
PRIiFAST16
Format specifier for printing an integer of type int_fast16_t or uint_fast16_t as a signed decimal integer.
PRIiFAST32
Format specifier for printing an integer of type int_fast32_t or uint_fast32_t as a signed decimal integer.
PRIiLEAST8
Format specifier for printing an integer of type int_least8_t or uint_least8_t as a signed decimal integer.
PRIiLEAST16
Format specifier for printing an integer of type int_least16_t or uint_least16_t as a signed decimal integer.
PRIiLEAST32
Format specifier for printing an integer of type int_least32_t or uint_least32_t as a signed decimal integer.
PRIiPTR
Format specifier for printing an integer of type intptr_t or uintptr_t as a signed decimal integer.
PRIu8
Format specifier for printing an integer of type int8_t or uint8_t as an unsigned decimal integer.
PRIu16
Format specifier for printing an integer of type int16_t or uint16_t as an unsigned decimal integer.
PRIu32
Format specifier for printing an integer of type int32_t or uint32_t as an unsigned decimal integer.
PRIuFAST8
Format specifier for printing an integer of type int_fast8_t or uint_fast8_t as an unsigned decimal integer.
PRIuFAST16
Format specifier for printing an integer of type int_fast16_t or uint_fast16_t as an unsigned decimal integer.
PRIuFAST32
Format specifier for printing an integer of type int_fast32_t or uint_fast32_t as an unsigned decimal integer.
PRIuLEAST8
Format specifier for printing an integer of type int_least8_t or uint_least8_t as an unsigned decimal integer.
PRIuLEAST16
Format specifier for printing an integer of type int_least16_t or uint_least16_t as an unsigned decimal integer.
PRIuLEAST32
Format specifier for printing an integer of type int_least32_t or uint_least32_t as an unsigned decimal integer.
PRIuPTR
Format specifier for printing an integer of type intptr_t or uintptr_t as an unsigned decimal integer.
PRIx8
Format specifier for printing an integer of type int8_t or uint8_t as an unsigned hexadecimal (lowercase) integer.
PRIX8
Format specifier for printing an integer of type int8_t or uint8_t as an unsigned hexadecimal (uppercase) integer.
PRIx16
Format specifier for printing an integer of type int16_t or uint16_t as an unsigned hexadecimal (lowercase) integer.
PRIX16
Format specifier for printing an integer of type int16_t or uint16_t as an unsigned hexadecimal (uppercase) integer.
PRIx32
Format specifier for printing an integer of type int32_t or uint32_t as an unsigned hexadecimal (lowercase) integer.
PRIX32
Format specifier for printing an integer of type int32_t or uint32_t as an unsigned hexadecimal (uppercase) integer.
PRIxFAST8
Format specifier for printing an integer of type int_fast8_t or uint_fast8_t as an unsigned hexadecimal (lowercase) integer.
PRIXFAST8
Format specifier for printing an integer of type int_fast8_t or uint_fast8_t as an unsigned hexadecimal (uppercase) integer.
PRIxFAST16
Format specifier for printing an integer of type int_fast16_t or uint_fast16_t as an unsigned hexadecimal (lowercase) integer.
PRIXFAST16
Format specifier for printing an integer of type int_fast16_t or uint_fast16_t as an unsigned hexadecimal (uppercase) integer.
PRIxFAST32
Format specifier for printing an integer of type int_fast32_t or uint_fast32_t as an unsigned hexadecimal (lowercase) integer.
PRIXFAST32
Format specifier for printing an integer of type int_fast32_t or uint_fast32_t as an unsigned hexadecimal (uppercase) integer.
PRIxLEAST8
Format specifier for printing an integer of type int_least8_t or uint_least8_t as an unsigned hexadecimal (lowercase) integer.
PRIXLEAST8
Format specifier for printing an integer of type int_least8_t or uint_least8_t as an unsigned hexadecimal (uppercase) integer.
PRIxLEAST16
Format specifier for printing an integer of type int_least16_t or uint_least16_t as an unsigned hexadecimal (lowercase) integer.
PRIXLEAST16
Format specifier for printing an integer of type int_least16_t or uint_least16_t as an unsigned hexadecimal (uppercase) integer.
PRIxLEAST32
Format specifier for printing an integer of type int_least32_t or uint_least32_t as an unsigned hexadecimal (lowercase) integer.
PRIXLEAST32
Format specifier for printing an integer of type int_least32_t or uint_least32_t as an unsigned hexadecimal (uppercase) integer.
PRIxPTR
Format specifier for printing an integer of type intptr_t or uintptr_t as an unsigned hexadecimal (lowercase) integer.
PRIXPTR
Format specifier for printing an integer of type intptr_t or uintptr_t as an unsigned hexadecimal (uppercase) integer.
SCNd8
Format specifier for scanning an integer of type int8_t or uint8_t written as a signed decimal integer.
SCNd16
Format specifier for scanning an integer of type int16_t or uint16_t written as a signed decimal integer.
SCNd32
Format specifier for scanning an integer of type int32_t or uint32_t written as a signed decimal integer.
SCNdFAST8
Format specifier for scanning an integer of type int_fast8_t or uint_fast8_t written as a signed decimal integer.
SCNdFAST16
Format specifier for scanning an integer of type int_fast16_t or uint_fast16_t written as a signed decimal integer.
SCNdFAST32
Format specifier for scanning an integer of type int_fast32_t or uint_fast32_t written as a signed decimal integer.
SCNdLEAST8
Format specifier for scanning an integer of type int_least8_t or uint_least8_t written as a signed decimal integer.
SCNdLEAST16
Format specifier for scanning an integer of type int_least16_t or uint_least16_t written as a signed decimal integer.
SCNdLEAST32
Format specifier for scanning an integer of type int_least32_t or uint_least32_t written as a signed decimal integer.
SCNdPTR
Format specifier for scanning an integer of type intptr_t or uintptr_t written as a signed decimal integer.
SCNi8
Format specifier for scanning an integer of type int8_t or uint8_t written as a signed decimal integer.
SCNi16
Format specifier for scanning an integer of type int16_t or uint16_t written as a signed decimal integer.
SCNi32
Format specifier for scanning an integer of type int32_t or uint32_t written as a signed decimal integer.
SCNiFAST8
Format specifier for scanning an integer of type int_fast8_t or uint_fast8_t written as a signed decimal integer.
SCNiFAST16
Format specifier for scanning an integer of type int_fast16_t or uint_fast16_t written as a signed decimal integer.
SCNiFAST32
Format specifier for scanning an integer of type int_fast32_t or uint_fast32_t written as a signed decimal integer.
SCNiLEAST8
Format specifier for scanning an integer of type int_least8_t or uint_least8_t written as a signed decimal integer.
SCNiLEAST16
Format specifier for scanning an integer of type int_least16_t or uint_least16_t written as a signed decimal integer.
SCNiLEAST32
Format specifier for scanning an integer of type int_least32_t or uint_least32_t written as a signed decimal integer.
SCNiPTR
Format specifier for scanning an integer of type intptr_t or uintptr_t written as a signed decimal integer.
SCNu8
Format specifier for scanning an integer of type int8_t or uint8_t written as an unsigned decimal integer.
SCNu16
Format specifier for scanning an integer of type int16_t or uint16_t written as an unsigned decimal integer.
SCNu32
Format specifier for scanning an integer of type int32_t or uint32_t written as an unsigned decimal integer.
SCNuFAST8
Format specifier for scanning an integer of type int_fast8_t or uint_fast8_t written as an unsigned decimal integer.
SCNuFAST16
Format specifier for scanning an integer of type int_fast16_t or uint_fast16_t written as an unsigned decimal integer.
SCNuFAST32
Format specifier for scanning an integer of type int_fast32_t or uint_fast32_t written as an unsigned decimal integer.
SCNuLEAST8
Format specifier for scanning an integer of type int_least8_t or uint_least8_t written as an unsigned decimal integer.
SCNuLEAST16
Format specifier for scanning an integer of type int_least16_t or uint_least16_t written as an unsigned decimal integer.
SCNuLEAST32
Format specifier for scanning an integer of type int_least32_t or uint_least32_t written as an unsigned decimal integer.
SCNuPTR
Format specifier for scanning an integer of type intptr_t or uintptr_t written as an unsigned decimal integer.
SCNx8
Format specifier for scanning an integer of type int8_t or uint8_t written as an unsigned hexadecimal (lowercase) integer.
SCNx16
Format specifier for scanning an integer of type int16_t or uint16_t written as an unsigned hexadecimal (lowercase) integer.
SCNx32
Format specifier for scanning an integer of type int32_t or uint32_t written as an unsigned hexadecimal (lowercase) integer.
SCNxFAST8
Format specifier for scanning an integer of type int_fast8_t or uint_fast8_t written as an unsigned hexadecimal (lowercase) integer.
SCNxFAST16
Format specifier for scanning an integer of type int_fast16_t or uint_fast16_t written as an unsigned hexadecimal (lowercase) integer.
SCNxFAST32
Format specifier for scanning an integer of type int_fast32_t or uint_fast32_t written as an unsigned hexadecimal (lowercase) integer.
SCNxLEAST8
Format specifier for scanning an integer of type int_least8_t or uint_least8_t written as an unsigned hexadecimal (lowercase) integer.
SCNxLEAST16
Format specifier for scanning an integer of type int_least16_t or uint_least16_t written as an unsigned hexadecimal (lowercase) integer.
SCNxLEAST32
Format specifier for scanning an integer of type int_least32_t or uint_least32_t written as an unsigned hexadecimal (lowercase) integer.
SCNxPTR
Format specifier for scanning an integer of type intptr_t or uintptr_t written as an unsigned hexadecimal (lowercase) integer.

This header file contains some of the definitions mandated in Paragraph 7.8 of the ANSI/ISO C99 standard.
Since the long long type is unhandled by printf and scanf, the definitions corresponding to 64-bit types, including intmax_t and uintmax_t, are omitted from this header. The octal format specifiers are omitted as well.


PRId8

PRId8 Constant
inttypes.h

#define PRId8 "hd"

Format specifier for printing an integer of type int8_t or uint8_t as a signed decimal integer.

This definition is the same as PRIi8. Definition mandated by the C99 standard.


PRId16

PRId16 Constant
inttypes.h

#define PRId16 "hd"

Format specifier for printing an integer of type int16_t or uint16_t as a signed decimal integer.

This definition is the same as PRIi16. Definition mandated by the C99 standard.


PRId32

PRId32 Constant
inttypes.h

#define PRId32 "ld"

Format specifier for printing an integer of type int32_t or uint32_t as a signed decimal integer.

This definition is the same as PRIi32. Definition mandated by the C99 standard.


PRIdFAST8

PRIdFAST8 Constant
inttypes.h

#define PRIdFAST8 "hd"

Format specifier for printing an integer of type int_fast8_t or uint_fast8_t as a signed decimal integer.

This definition is the same as PRIiFAST8. Definition mandated by the C99 standard.


PRIdFAST16

PRIdFAST16 Constant
inttypes.h

#define PRIdFAST16 "hd"

Format specifier for printing an integer of type int_fast16_t or uint_fast16_t as a signed decimal integer.

This definition is the same as PRIiFAST16. Definition mandated by the C99 standard.


PRIdFAST32

PRIdFAST32 Constant
inttypes.h

#define PRIdFAST32 "ld"

Format specifier for printing an integer of type int_fast32_t or uint_fast32_t as a signed decimal integer.

This definition is the same as PRIiFAST32. Definition mandated by the C99 standard.


PRIdLEAST8

PRIdLEAST8 Constant
inttypes.h

#define PRIdLEAST8 "hd"

Format specifier for printing an integer of type int_least8_t or uint_least8_t as a signed decimal integer.

This definition is the same as PRIiLEAST8. Definition mandated by the C99 standard.


PRIdLEAST16

PRIdLEAST16 Constant
inttypes.h

#define PRIdLEAST16 "hd"

Format specifier for printing an integer of type int_least16_t or uint_least16_t as a signed decimal integer.

This definition is the same as PRIiLEAST16. Definition mandated by the C99 standard.


PRIdLEAST32

PRIdLEAST32 Constant
inttypes.h

#define PRIdLEAST32 "ld"

Format specifier for printing an integer of type int_least32_t or uint_least32_t as a signed decimal integer.

This definition is the same as PRIiLEAST32. Definition mandated by the C99 standard.


PRIdPTR

PRIdPTR Constant
inttypes.h

#define PRIdPTR "ld"

Format specifier for printing an integer of type intptr_t or uintptr_t as a signed decimal integer.

This definition is the same as PRIiPTR. Definition mandated by the C99 standard.


PRIi8

PRIi8 Constant
inttypes.h

#define PRIi8 "hi"

Format specifier for printing an integer of type int8_t or uint8_t as a signed decimal integer.

This definition is the same as PRId8. Definition mandated by the C99 standard.


PRIi16

PRIi16 Constant
inttypes.h

#define PRIi16 "hi"

Format specifier for printing an integer of type int16_t or uint16_t as a signed decimal integer.

This definition is the same as PRId16. Definition mandated by the C99 standard.


PRIi32

PRIi32 Constant
inttypes.h

#define PRIi32 "li"

Format specifier for printing an integer of type int32_t or uint32_t as a signed decimal integer.

This definition is the same as PRId32. Definition mandated by the C99 standard.


PRIiFAST8

PRIiFAST8 Constant
inttypes.h

#define PRIiFAST8 "hi"

Format specifier for printing an integer of type int_fast8_t or uint_fast8_t as a signed decimal integer.

This definition is the same as PRIdFAST8. Definition mandated by the C99 standard.


PRIiFAST16

PRIiFAST16 Constant
inttypes.h

#define PRIiFAST16 "hi"

Format specifier for printing an integer of type int_fast16_t or uint_fast16_t as a signed decimal integer.

This definition is the same as PRIdFAST16. Definition mandated by the C99 standard.


PRIiFAST32

PRIiFAST32 Constant
inttypes.h

#define PRIiFAST32 "li"

Format specifier for printing an integer of type int_fast32_t or uint_fast32_t as a signed decimal integer.

This definition is the same as PRIdFAST32. Definition mandated by the C99 standard.


PRIiLEAST8

PRIiLEAST8 Constant
inttypes.h

#define PRIiLEAST8 "hi"

Format specifier for printing an integer of type int_least8_t or uint_least8_t as a signed decimal integer.

This definition is the same as PRIdLEAST8. Definition mandated by the C99 standard.


PRIiLEAST16

PRIiLEAST16 Constant
inttypes.h

#define PRIiLEAST16 "hi"

Format specifier for printing an integer of type int_least16_t or uint_least16_t as a signed decimal integer.

This definition is the same as PRIdLEAST16. Definition mandated by the C99 standard.


PRIiLEAST32

PRIiLEAST32 Constant
inttypes.h

#define PRIiLEAST32 "li"

Format specifier for printing an integer of type int_least32_t or uint_least32_t as a signed decimal integer.

This definition is the same as PRIdLEAST32. Definition mandated by the C99 standard.


PRIiPTR

PRIiPTR Constant
inttypes.h

#define PRIiPTR "li"

Format specifier for printing an integer of type intptr_t or uintptr_t as a signed decimal integer.

This definition is the same as PRIdPTR. Definition mandated by the C99 standard.


PRIu8

PRIu8 Constant
inttypes.h

#define PRIu8 "hu"

Format specifier for printing an integer of type int8_t or uint8_t as an unsigned decimal integer.

Definition mandated by the C99 standard.


PRIu16

PRIu16 Constant
inttypes.h

#define PRIu16 "hu"

Format specifier for printing an integer of type int16_t or uint16_t as an unsigned decimal integer.

Definition mandated by the C99 standard.


PRIu32

PRIu32 Constant
inttypes.h

#define PRIu32 "lu"

Format specifier for printing an integer of type int32_t or uint32_t as an unsigned decimal integer.

Definition mandated by the C99 standard.


PRIuFAST8

PRIuFAST8 Constant
inttypes.h

#define PRIuFAST8 "hu"

Format specifier for printing an integer of type int_fast8_t or uint_fast8_t as an unsigned decimal integer.

Definition mandated by the C99 standard.


PRIuFAST16

PRIuFAST16 Constant
inttypes.h

#define PRIuFAST16 "hu"

Format specifier for printing an integer of type int_fast16_t or uint_fast16_t as an unsigned decimal integer.

Definition mandated by the C99 standard.


PRIuFAST32

PRIuFAST32 Constant
inttypes.h

#define PRIuFAST32 "lu"

Format specifier for printing an integer of type int_fast32_t or uint_fast32_t as an unsigned decimal integer.

Definition mandated by the C99 standard.


PRIuLEAST8

PRIuLEAST8 Constant
inttypes.h

#define PRIuLEAST8 "hu"

Format specifier for printing an integer of type int_least8_t or uint_least8_t as an unsigned decimal integer.

Definition mandated by the C99 standard.


PRIuLEAST16

PRIuLEAST16 Constant
inttypes.h

#define PRIuLEAST16 "hu"

Format specifier for printing an integer of type int_least16_t or uint_least16_t as an unsigned decimal integer.

Definition mandated by the C99 standard.


PRIuLEAST32

PRIuLEAST32 Constant
inttypes.h

#define PRIuLEAST32 "lu"

Format specifier for printing an integer of type int_least32_t or uint_least32_t as an unsigned decimal integer.

Definition mandated by the C99 standard.


PRIuPTR

PRIuPTR Constant
inttypes.h

#define PRIuPTR "lu"

Format specifier for printing an integer of type intptr_t or uintptr_t as an unsigned decimal integer.

Definition mandated by the C99 standard.


PRIx8

PRIx8 Constant
inttypes.h

#define PRIx8 "hx"

Format specifier for printing an integer of type int8_t or uint8_t as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


PRIX8

PRIX8 Constant
inttypes.h

#define PRIX8 "hX"

Format specifier for printing an integer of type int8_t or uint8_t as an unsigned hexadecimal (uppercase) integer.

Definition mandated by the C99 standard.


PRIx16

PRIx16 Constant
inttypes.h

#define PRIx16 "hx"

Format specifier for printing an integer of type int16_t or uint16_t as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


PRIX16

PRIX16 Constant
inttypes.h

#define PRIX16 "hX"

Format specifier for printing an integer of type int16_t or uint16_t as an unsigned hexadecimal (uppercase) integer.

Definition mandated by the C99 standard.


PRIx32

PRIx32 Constant
inttypes.h

#define PRIx32 "lx"

Format specifier for printing an integer of type int32_t or uint32_t as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


PRIX32

PRIX32 Constant
inttypes.h

#define PRIX32 "lX"

Format specifier for printing an integer of type int32_t or uint32_t as an unsigned hexadecimal (uppercase) integer.

Definition mandated by the C99 standard.


PRIxFAST8

PRIxFAST8 Constant
inttypes.h

#define PRIxFAST8 "hx"

Format specifier for printing an integer of type int_fast8_t or uint_fast8_t as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


PRIXFAST8

PRIXFAST8 Constant
inttypes.h

#define PRIXFAST8 "hX"

Format specifier for printing an integer of type int_fast8_t or uint_fast8_t as an unsigned hexadecimal (uppercase) integer.

Definition mandated by the C99 standard.


PRIxFAST16

PRIxFAST16 Constant
inttypes.h

#define PRIxFAST16 "hx"

Format specifier for printing an integer of type int_fast16_t or uint_fast16_t as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


PRIXFAST16

PRIXFAST16 Constant
inttypes.h

#define PRIXFAST16 "hX"

Format specifier for printing an integer of type int_fast16_t or uint_fast16_t as an unsigned hexadecimal (uppercase) integer.

Definition mandated by the C99 standard.


PRIxFAST32

PRIxFAST32 Constant
inttypes.h

#define PRIxFAST32 "lx"

Format specifier for printing an integer of type int_fast32_t or uint_fast32_t as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


PRIXFAST32

PRIXFAST32 Constant
inttypes.h

#define PRIXFAST32 "lX"

Format specifier for printing an integer of type int_fast32_t or uint_fast32_t as an unsigned hexadecimal (uppercase) integer.

Definition mandated by the C99 standard.


PRIxLEAST8

PRIxLEAST8 Constant
inttypes.h

#define PRIxLEAST8 "hx"

Format specifier for printing an integer of type int_least8_t or uint_least8_t as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


PRIXLEAST8

PRIXLEAST8 Constant
inttypes.h

#define PRIXLEAST8 "hX"

Format specifier for printing an integer of type int_least8_t or uint_least8_t as an unsigned hexadecimal (uppercase) integer.

Definition mandated by the C99 standard.


PRIxLEAST16

PRIxLEAST16 Constant
inttypes.h

#define PRIxLEAST16 "hx"

Format specifier for printing an integer of type int_least16_t or uint_least16_t as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


PRIXLEAST16

PRIXLEAST16 Constant
inttypes.h

#define PRIXLEAST16 "hX"

Format specifier for printing an integer of type int_least16_t or uint_least16_t as an unsigned hexadecimal (uppercase) integer.

Definition mandated by the C99 standard.


PRIxLEAST32

PRIxLEAST32 Constant
inttypes.h

#define PRIxLEAST32 "lx"

Format specifier for printing an integer of type int_least32_t or uint_least32_t as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


PRIXLEAST32

PRIXLEAST32 Constant
inttypes.h

#define PRIXLEAST32 "lX"

Format specifier for printing an integer of type int_least32_t or uint_least32_t as an unsigned hexadecimal (uppercase) integer.

Definition mandated by the C99 standard.


PRIxPTR

PRIxPTR Constant
inttypes.h

#define PRIxPTR "lx"

Format specifier for printing an integer of type intptr_t or uintptr_t as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


PRIXPTR

PRIXPTR Constant
inttypes.h

#define PRIXPTR "lX"

Format specifier for printing an integer of type intptr_t or uintptr_t as an unsigned hexadecimal (uppercase) integer.

Definition mandated by the C99 standard.


SCNd8

SCNd8 Constant
inttypes.h

#define SCNd8 "hd"

Format specifier for scanning an integer of type int8_t or uint8_t written as a signed decimal integer.

This definition is the same as SCNi8. Definition mandated by the C99 standard.


SCNd16

SCNd16 Constant
inttypes.h

#define SCNd16 "hd"

Format specifier for scanning an integer of type int16_t or uint16_t written as a signed decimal integer.

This definition is the same as SCNi16. Definition mandated by the C99 standard.


SCNd32

SCNd32 Constant
inttypes.h

#define SCNd32 "ld"

Format specifier for scanning an integer of type int32_t or uint32_t written as a signed decimal integer.

This definition is the same as SCNi32. Definition mandated by the C99 standard.


SCNdFAST8

SCNdFAST8 Constant
inttypes.h

#define SCNdFAST8 "hd"

Format specifier for scanning an integer of type int_fast8_t or uint_fast8_t written as a signed decimal integer.

This definition is the same as SCNiFAST8. Definition mandated by the C99 standard.


SCNdFAST16

SCNdFAST16 Constant
inttypes.h

#define SCNdFAST16 "hd"

Format specifier for scanning an integer of type int_fast16_t or uint_fast16_t written as a signed decimal integer.

This definition is the same as SCNiFAST16. Definition mandated by the C99 standard.


SCNdFAST32

SCNdFAST32 Constant
inttypes.h

#define SCNdFAST32 "ld"

Format specifier for scanning an integer of type int_fast32_t or uint_fast32_t written as a signed decimal integer.

This definition is the same as SCNiFAST32. Definition mandated by the C99 standard.


SCNdLEAST8

SCNdLEAST8 Constant
inttypes.h

#define SCNdLEAST8 "hd"

Format specifier for scanning an integer of type int_least8_t or uint_least8_t written as a signed decimal integer.

This definition is the same as SCNiLEAST8. Definition mandated by the C99 standard.


SCNdLEAST16

SCNdLEAST16 Constant
inttypes.h

#define SCNdLEAST16 "hd"

Format specifier for scanning an integer of type int_least16_t or uint_least16_t written as a signed decimal integer.

This definition is the same as SCNiLEAST16. Definition mandated by the C99 standard.


SCNdLEAST32

SCNdLEAST32 Constant
inttypes.h

#define SCNdLEAST32 "ld"

Format specifier for scanning an integer of type int_least32_t or uint_least32_t written as a signed decimal integer.

This definition is the same as SCNiLEAST32. Definition mandated by the C99 standard.


SCNdPTR

SCNdPTR Constant
inttypes.h

#define SCNdPTR "ld"

Format specifier for scanning an integer of type intptr_t or uintptr_t written as a signed decimal integer.

This definition is the same as SCNiPTR. Definition mandated by the C99 standard.


SCNi8

SCNi8 Constant
inttypes.h

#define SCNi8 "hi"

Format specifier for scanning an integer of type int8_t or uint8_t written as a signed decimal integer.

This definition is the same as SCNd8. Definition mandated by the C99 standard.


SCNi16

SCNi16 Constant
inttypes.h

#define SCNi16 "hi"

Format specifier for scanning an integer of type int16_t or uint16_t written as a signed decimal integer.

This definition is the same as SCNd16. Definition mandated by the C99 standard.


SCNi32

SCNi32 Constant
inttypes.h

#define SCNi32 "li"

Format specifier for scanning an integer of type int32_t or uint32_t written as a signed decimal integer.

This definition is the same as SCNd32. Definition mandated by the C99 standard.


SCNiFAST8

SCNiFAST8 Constant
inttypes.h

#define SCNiFAST8 "hi"

Format specifier for scanning an integer of type int_fast8_t or uint_fast8_t written as a signed decimal integer.

This definition is the same as SCNdFAST8. Definition mandated by the C99 standard.


SCNiFAST16

SCNiFAST16 Constant
inttypes.h

#define SCNiFAST16 "hi"

Format specifier for scanning an integer of type int_fast16_t or uint_fast16_t written as a signed decimal integer.

This definition is the same as SCNdFAST16. Definition mandated by the C99 standard.


SCNiFAST32

SCNiFAST32 Constant
inttypes.h

#define SCNiFAST32 "li"

Format specifier for scanning an integer of type int_fast32_t or uint_fast32_t written as a signed decimal integer.

This definition is the same as SCNdFAST32. Definition mandated by the C99 standard.


SCNiLEAST8

SCNiLEAST8 Constant
inttypes.h

#define SCNiLEAST8 "hi"

Format specifier for scanning an integer of type int_least8_t or uint_least8_t written as a signed decimal integer.

This definition is the same as SCNdLEAST8. Definition mandated by the C99 standard.


SCNiLEAST16

SCNiLEAST16 Constant
inttypes.h

#define SCNiLEAST16 "hi"

Format specifier for scanning an integer of type int_least16_t or uint_least16_t written as a signed decimal integer.

This definition is the same as SCNdLEAST16. Definition mandated by the C99 standard.


SCNiLEAST32

SCNiLEAST32 Constant
inttypes.h

#define SCNiLEAST32 "li"

Format specifier for scanning an integer of type int_least32_t or uint_least32_t written as a signed decimal integer.

This definition is the same as SCNdLEAST32. Definition mandated by the C99 standard.


SCNiPTR

SCNiPTR Constant
inttypes.h

#define SCNiPTR "li"

Format specifier for scanning an integer of type intptr_t or uintptr_t written as a signed decimal integer.

This definition is the same as SCNdPTR. Definition mandated by the C99 standard.


SCNu8

SCNu8 Constant
inttypes.h

#define SCNu8 "hu"

Format specifier for scanning an integer of type int8_t or uint8_t written as an unsigned decimal integer.

Definition mandated by the C99 standard.


SCNu16

SCNu16 Constant
inttypes.h

#define SCNu16 "hu"

Format specifier for scanning an integer of type int16_t or uint16_t written as an unsigned decimal integer.

Definition mandated by the C99 standard.


SCNu32

SCNu32 Constant
inttypes.h

#define SCNu32 "lu"

Format specifier for scanning an integer of type int32_t or uint32_t written as an unsigned decimal integer.

Definition mandated by the C99 standard.


SCNuFAST8

SCNuFAST8 Constant
inttypes.h

#define SCNuFAST8 "hu"

Format specifier for scanning an integer of type int_fast8_t or uint_fast8_t written as an unsigned decimal integer.

Definition mandated by the C99 standard.


SCNuFAST16

SCNuFAST16 Constant
inttypes.h

#define SCNuFAST16 "hu"

Format specifier for scanning an integer of type int_fast16_t or uint_fast16_t written as an unsigned decimal integer.

Definition mandated by the C99 standard.


SCNuFAST32

SCNuFAST32 Constant
inttypes.h

#define SCNuFAST32 "lu"

Format specifier for scanning an integer of type int_fast32_t or uint_fast32_t written as an unsigned decimal integer.

Definition mandated by the C99 standard.


SCNuLEAST8

SCNuLEAST8 Constant
inttypes.h

#define SCNuLEAST8 "hu"

Format specifier for scanning an integer of type int_least8_t or uint_least8_t written as an unsigned decimal integer.

Definition mandated by the C99 standard.


SCNuLEAST16

SCNuLEAST16 Constant
inttypes.h

#define SCNuLEAST16 "hu"

Format specifier for scanning an integer of type int_least16_t or uint_least16_t written as an unsigned decimal integer.

Definition mandated by the C99 standard.


SCNuLEAST32

SCNuLEAST32 Constant
inttypes.h

#define SCNuLEAST32 "lu"

Format specifier for scanning an integer of type int_least32_t or uint_least32_t written as an unsigned decimal integer.

Definition mandated by the C99 standard.


SCNuPTR

SCNuPTR Constant
inttypes.h

#define SCNuPTR "lu"

Format specifier for scanning an integer of type intptr_t or uintptr_t written as an unsigned decimal integer.

Definition mandated by the C99 standard.


SCNx8

SCNx8 Constant
inttypes.h

#define SCNx8 "hx"

Format specifier for scanning an integer of type int8_t or uint8_t written as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


SCNx16

SCNx16 Constant
inttypes.h

#define SCNx16 "hx"

Format specifier for scanning an integer of type int16_t or uint16_t written as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


SCNx32

SCNx32 Constant
inttypes.h

#define SCNx32 "lx"

Format specifier for scanning an integer of type int32_t or uint32_t written as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


SCNxFAST8

SCNxFAST8 Constant
inttypes.h

#define SCNxFAST8 "hx"

Format specifier for scanning an integer of type int_fast8_t or uint_fast8_t written as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


SCNxFAST16

SCNxFAST16 Constant
inttypes.h

#define SCNxFAST16 "hx"

Format specifier for scanning an integer of type int_fast16_t or uint_fast16_t written as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


SCNxFAST32

SCNxFAST32 Constant
inttypes.h

#define SCNxFAST32 "lx"

Format specifier for scanning an integer of type int_fast32_t or uint_fast32_t written as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


SCNxLEAST8

SCNxLEAST8 Constant
inttypes.h

#define SCNxLEAST8 "hx"

Format specifier for scanning an integer of type int_least8_t or uint_least8_t written as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


SCNxLEAST16

SCNxLEAST16 Constant
inttypes.h

#define SCNxLEAST16 "hx"

Format specifier for scanning an integer of type int_least16_t or uint_least16_t written as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


SCNxLEAST32

SCNxLEAST32 Constant
inttypes.h

#define SCNxLEAST32 "lx"

Format specifier for scanning an integer of type int_least32_t or uint_least32_t written as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


SCNxPTR

SCNxPTR Constant
inttypes.h

#define SCNxPTR "lx"

Format specifier for scanning an integer of type intptr_t or uintptr_t written as an unsigned hexadecimal (lowercase) integer.

Definition mandated by the C99 standard.


iso646.h

iso646.h Header File
Header File Index

ISO C99 definitions of alternative spellings for operators

Here are the macros, and their expansions, defined by the C99 standard in the iso646.h header:
and | &&
and_eq | &=
bitand | &
bitor | |
compl | ~
not | !
not_eq | !=
or | ||
or_eq | |=
xor | ^
xor_eq | ^=


kbd.h

kbd.h Header File
Header File Index

Keyboard handling routines

Language Extensions
BEGIN_KEYTEST
Starts a _keytest_optimized block.
END_KEYTEST
Ends a _keytest_optimized block.
Functions
_keytest_optimized
Optimized low-level keyboard reading for single keys.
_keytest
Low-level keyboard reading for single keys.
_rowread_internal
Low-level keyboard reading without inverting.
_rowread_inverted
Low-level keyboard reading with inverting.
_rowread
Low-level keyboard reading.
alphaLockOff
Turns the alpha-lock off on the TI-89.
alphaLockOn
Turns the alpha-lock on on the TI-89.
GetAlphaStatus
Returns the current alpha-lock status.
GKeyDown
Checks for currently-available keystrokes.
GKeyFlush
Flushes the keyboard queue.
GKeyIn
Gets character from the keyboard, with additional possibilities.
kbhit
Checks for unread keystrokes.
KeyYesOrNo
Checks if a key value represents a 'yes' or 'no' key.
ngetchx
Gets character from the keyboard, without echoing to the screen.
OSGetStatKeys
Checks whether an arrow key (TI-89) or status key (TI-92+) is pressed.
OSInitBetweenKeyDelay
Sets the rate at which a key autorepeats.
OSInitKeyInitDelay
Sets the initial autorepeat key delay.
pushkey
Replaces the keystroke in the keyboard queue with the given code.
restoreAlphaLock
Restores the alpha-lock status.
SetAlphaStatus
Sets the alpha-lock status on the TI-89.
Global Variables
OSFastArrows
A variable determining whether arrow keys are repeated slowly or quickly.
Constants
KB_AUTOREPEAT
A constant defining the "auto-repeat" bit.
NULL
A null-pointer value.
Predefined Types
Arrows
An enumeration for describing the four arrow keys.
Bool
An enumeration to describe true or false values.
CommonKeys
An enumeration for describing common key codes.
GKeyFlags
Enumerates different key options flags for the GKeyIn routine.
SCR_RECT
A scructure for defining a rectangular area.
StatKeys
An enumeration for describing modifier key values.


BEGIN_KEYTEST

BEGIN_KEYTEST Language Extension
kbd.h

Starts a _keytest_optimized block.

BEGIN_KEYTEST is used to start a block of key reading using _keytest_optimized.

See also: END_KEYTEST, _keytest_optimized


END_KEYTEST

END_KEYTEST Language Extension
kbd.h

Ends a _keytest_optimized block.

END_KEYTEST is used to end a block of key reading using _keytest_optimized.

See also: BEGIN_KEYTEST


_keytest_optimized

_keytest_optimized Function (Macro)
kbd.h

short _keytest_optimized (short row, short col);

Optimized low-level keyboard reading for single keys.

_keytest_optimized behaves like _keytest, but it produces better code if keys from the same row are read sequentially. You have to use it together with BEGIN_KEYTEST and END_KEYTEST.

An example probably best explains the usage of this function. The following piece of code waits until an arrow key is pressed. Since all arrows are in the same row, only one call to _rowread is necessary.

for (;;)
  {
    BEGIN_KEYTEST
      if (_keytest_optimized (RR_LEFT)
       || _keytest_optimized (RR_RIGHT)
       || _keytest_optimized (RR_UP)
       || _keytest_optimized (RR_DOWN))
        break;
    END_KEYTEST
  }

Uses: _rowread


_keytest

_keytest Function (Macro)
kbd.h

short _keytest (short row, short col);

Low-level keyboard reading for single keys.

_keytest uses _rowread to read the key in a specific row and column. If the parameters are constants, the argument for _rowread and the return mask are optimized into single values.

_keytest returns TRUE if the key is being held down, and FALSE otherwise.

Be sure to read the notes about _rowread.

compat.h defines constant pairs for all keys. Using these constant pairs, you can use _keytest in this way:

if (_keytest (RR_ESC))
  ...

Uses: _rowread

See also: _keytest_optimized


_rowread_internal

_rowread_internal Function (Macro)
kbd.h

#define _rowread_internal(row) (~(_rowread (row)))

Low-level keyboard reading without inverting.

_rowread_internal is a function which was previously used internally by _rowread. Unlike _rowread, it does not invert the return value.

Uses: _rowread


_rowread_inverted

_rowread_inverted Function (Macro)
kbd.h

#define _rowread_inverted(row) (_rowread (~((short)(row))))

Low-level keyboard reading with inverting.

_rowread_inverted is similar to _rowread, but it also inverts the row passed to it.

Uses: _rowread


_rowread

_rowread Function* (tigcc.a)
kbd.h

unsigned short _rowread (unsigned short row);

Low-level keyboard reading.

_rowread is a function for low-level keyboard reading. It is implemented for simultaneous reading of more than one key (useful in games), or for reading keys when interrupts are disabled (useful if you want to avoid displaying status line indicators, which are displayed from Auto-Int 1).

Setting a bit in row masks the corresponding row of the keyboard from being read, so if row is zero, all rows are read at the same time. Take a look at _rowread_inverted as well. In the result, all bits (cols) corresponding to keys which are being held down are set. See below for some examples.

Here is a table which describes how the keyboard matrix is organized on both the TI-89 and TI-92 Plus:

TI-89:
C o l u m n
R
o
w
 | Bit 7 | Bit 6 | Bit 5 | Bit 4 | Bit 3 | Bit 2 | Bit 1 | Bit 0
Bit 0 | alpha | Diamnd | Shift | 2nd | Right | Down | Left | Up
Bit 1 | F5 | CLEAR | ^ | / | * | - | + | ENTER
Bit 2 | F4 | BckSpc | T | , | 9 | 6 | 3 | (-)
Bit 3 | F3 | CATLG | Z | ) | 8 | 5 | 2 | .
Bit 4 | F2 | MODE | Y | ( | 7 | 4 | 1 | 0
Bit 5 | F1 | HOME | X | = | | | EE | STO | APPS
Bit 6 |  |  |  |  |  |  |  | ESC

TI-92 Plus:
C o l u m n
R
o
w
 | Bit 7 | Bit 6 | Bit 5 | Bit 4 | Bit 3 | Bit 2 | Bit 1 | Bit 0
Bit 0 | Down | Right | Up | Left | Hand | Shift | Diamnd | 2nd
Bit 1 | 3 | 2 | 1 | F8 | W | S | Z |
Bit 2 | 6 | 5 | 4 | F3 | E | D | X |
Bit 3 | 9 | 8 | 7 | F7 | R | F | C | STO
Bit 4 | , | ) | ( | F2 | T | G | V | Space
Bit 5 | TAN | COS | SIN | F6 | Y | H | B | /
Bit 6 | P | ENTER2 | LN | F1 | U | J | N | ^
Bit 7 | * | APPS | CLEAR | F5 | I | K | M | =
Bit 8 |  | ESC | MODE | + | O | L | q | BckSpc
Bit 9 | (-) | . | 0 | F4 | Q | A | ENTER1 | -

Note for TI-92+: ENTER1 is on the alphabetic and numeric keypads. ENTER2 is next to the cursor pad.

You can use binary numbers to mask out the rows you need. You can also make use of the fact that a value where only bit i is set equals 1<<i.
Use the bitwise NOT operator ('~') to invert the value.

These four expressions all check whether '9' on the TI-89 or 'E' on the TI-92+ is held down. In fact, they are all equal:

_rowread(~((short)(1<<2))) & (1<<3)
_rowread(~0b100) & 0b1000
_rowread(~0x4) & 0x8
_rowread(0xFFFB) & 0x8
But generally it is much easier to use the _keytest macro instead.

Because of the way the TI-89 and TI-92+'s keyboard is wired, if you hold down three keys that form the corners of a rectangle, the calculator will think you are also holding down the key at the fourth corner. The ON key is special. It is not part of the keyboard matrix and therefore cannot be read with _rowread. It triggers a special interrupt instead.

Note: It is recommended to redirect Auto-Int 1 and 5 while reading the keyboard using _rowread, because keyboard reading routines implemented in these two interrupts may interfere with _rowread if an interrupt occurs just while _rowread is executing. See DUMMY_HANDLER from intr.h for information on how to do this.

About the internal implementation: _rowread sends row to the I/O port 0x600018 (keyboard row mask), waits a while to allow the I/O to recover, then returns the byte read from 0x60001B (inverted for easier testing in C programs).

Used by: _keytest, _keytest_optimized, _rowread_internal, _rowread_inverted

See also: _rowread_internal, _rowread_inverted, _keytest


alphaLockOff

alphaLockOff Function (ROM Call 0x482)
AMS 2.00 or higher kbd.h

void alphaLockOff (unsigned char *Status);

Turns the alpha-lock off on the TI-89.

alphaLockOff first returns the current alpha-lock keyboard status in Status. Then it turns the alpha-lock off. This routine exists on both the TI-89 and TI-92+, but as there is no alpha-lock on the TI-92+, this function does nothing on the TI-92+.

Used by: Dialog, MenuKey, ROM Call 0x421

See also: alphaLockOn, restoreAlphaLock, SetAlphaStatus, GetAlphaStatus


alphaLockOn

alphaLockOn Function (ROM Call 0x481)
AMS 2.00 or higher kbd.h

void alphaLockOn (unsigned char *Status);

Turns the alpha-lock on on the TI-89.

alphaLockOn first returns the current alpha-lock keyboard status in Status. Then it turns the alpha-lock on. This routine exists on both the TI-89 and TI-92+, but as there is no alpha-lock on the TI-92+, this function does nothing on the TI-92+.

Used by: Dialog, MenuKey, ROM Call 0x421

See also: alphaLockOff, restoreAlphaLock, SetAlphaStatus, GetAlphaStatus


GetAlphaStatus

GetAlphaStatus Function (ROM Call 0x164)
AMS 2.00 or higher kbd.h

unsigned char GetAlphaStatus (void);

Returns the current alpha-lock status.

GetAlphaStatus returns TRUE if the alpha-lock is on, and FALSE otherwise.
On the TI-92+, the function will always return FALSE.

See also: SetAlphaStatus


GKeyDown

GKeyDown Function (ROM Call 0x17F)
kbd.h

short GKeyDown (void);

Checks for currently-available keystrokes.

Although GKeyDown is different entry in the TIOS jump table than kbhit, there is no difference between these two functions. GKeyDown just calls kbhit and does nothing more.

Uses: kbhit


GKeyFlush

GKeyFlush Function (ROM Call 0x180)
kbd.h

void GKeyFlush (void);

Flushes the keyboard queue.

GKeyFlush flushes the keyboard queue by repeatedly calling GKeyIn until the queue is empty.

Uses: GKeyIn, kbhit


GKeyIn

GKeyIn Function (ROM Call 0x17E)
kbd.h

short GKeyIn (SCR_RECT *cursor_shape, unsigned short Flags);

Gets character from the keyboard, with additional possibilities.

GKeyIn acts similarly to ngetchx, with following differences:

  • During waiting for a keypress, a flashing cursor may optionally be displayed. Parameter cursor_shape is a pointer to SCR_RECT structure which defines location and shape of the cursor (it is, in fact, a flashing rectangular area which is obtained by XORing a rectangle while waiting on a key). If cursor_shape is NULL, no cursor will be displayed.
  • The activity in the status line during waiting for a keypress is set to IDLE (in opposite to ngetchx which sets activity to BUSY). After a keystroke is ready, the activity will be switched to BUSY. See ST_busy for more info about status line activity indicator.
  • During waiting for a keypress, if the user waits too long, the calculator will be switched off (APD feature - Automatic Power Down). This will not happen with ngetchx. See system.h header file for more info about APD.
  • During waiting for a keypress, the calculator enters into "idle" state (see idle for more info).
  • GKeyIn bypasses the event manager’s handling of keys so this routine should be used with caution.
  • If Flags is different than zero, some special behaviour happens.
The parameter Flags can be a combination of the following, defined in the GKeyFlags enumeration:
GKF_NORMAL | No special key processing. This is the usual value to set. Note: GKF_NORMAL is actually 0 (i.e. no flags are set).
GKF_MODAL | If the pressed key is a modal key (see QModeKey for information on what is a "modal" key for the TIOS), GKeyIn will return KEY_ESC instead of the real keystroke code, and the keystroke will not be picked from the keyboard queue. If the pressed key is not a mode key, GKeyIn behaves as usual. Note that DIALOG boxes usually set GKF_MODAL and GKF_SYS so that if the user presses [VAR-LINK] in the dialog box, the dialog box is closed and then the [VAR-LINK] key is acted on (though there is a flag to allow [VAR-LINK] to be activated from inside a dialog box).
GKF_REPUSH_KEY | GKeyIn will not pick the keystroke from the keyboard queue, so the "keypress" flag will remain set. You must explicitely pick it using ngetchx or flush the queue using GKeyFlush.
GKF_ACCEPT | The purpose of this flag is unknown for the moment.
GKF_SYS | If the pressed key is a system key (see QSysKey for information on what is a "system" key for the TIOS), GKeyIn will return KEY_ESC instead of the real keystroke code, and the keystroke will not be picked from the keyboard queue. If the pressed key is not a system key, GKeyIn behaves as usual.
GKF_NO_EVS | Pressing the [CATALOG] key will be ignored.

Except in noted special cases, GKeyIn returns the same value as ngetchx. Menus and dialog boxes usually set GKF_MODAL and GKF_SYS, so that if a user presses say the VAR-LINK key in the dialog box, the dialog box is closed and then the VAR-LINK key is acted on.

Note: TI doesn't recommend to use GKeyIn as it bypasses the event manager’s handling of keys. Programs should use the event manager to process keys in most cases. GKeyIn should only be used in special cases where the event manager is not accessible. For games, you'll probably be better off using kbd_queue or _keytest.

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

Uses: ROM Call 0x3EA
Used by: GKeyFlush, cmd_showstat, cmd_toolbar, Dialog, DlgMessage, handleVarLinkKey, MenuKey, HelpKeys, GT_Trace

See also: ngetchx, kbhit, kbd_queue, OSFastArrows


kbhit

kbhit Function (ROM Call 0x52)
kbd.h

short kbhit (void);

Checks for unread keystrokes.

kbhit checks to see if a keystroke is currently available. Any available keystrokes can be retrieved with ngetchx. If a keystroke is available, kbhit returns a nonzero integer (in fact, it returns the exactly same value as ngetchx); if not, it returns 0. Note that kbhit does not pick a keystroke from the keyboard queue. So, kbhit will continue to return non-zero value until "keypress" flag is reset by calling ngetchx, GKeyFlush or GKeyIn.

Note: kbhit function is slow, because it also handles receiving eventual bytes from the link port (used mainly internally in TIOS when the calculator is in the Home screen). See kbd_queue for much faster way to check the keyboard state.

Uses: HomeAlone, OSCheckSilentLink, OSLinkCmd, OSqinquire, OSSetSR
Used by: GKeyDown, GKeyFlush, pushkey, cmd_disptbl, cmd_pause, push_getkey, EV_eventLoop, EV_getc, GS_PlotAll, GZ_Stat, Regraph

See also: ngetchx, GKeyIn, kbd_queue, OSFastArrows


KeyYesOrNo

KeyYesOrNo Function (ROM Call 0x3EB)
AMS 2.00 or higher kbd.h

short KeyYesOrNo (unsigned short key);

Checks if a key value represents a 'yes' or 'no' key.

KeyYesOrNo returns:

  • 1, if key is ENTER, or the first letter of 'yes' in the current language;
  • 0, if key is ESC, or the first letter of 'no' in the current language;
  • -1, if key is neither.
Here is an example (called "Key Yes or No"):
// Check whether typed keys represent "Yes" or "No"
// in current language

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 200           // Compile for AMS 2.00 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

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

// Main Function
void _main(void)
{
  short k, a;
  ClrScr ();
  while ((k = GKeyIn (NULL, 0)) != 32)
    // While the user doesn't type SPACE
  {
    a = KeyYesOrNo(k);
    if (a == 0)
      DrawStr (0, 0, "FALSE  ", A_REPLACE);
    else if (a == 1)
      DrawStr (0, 0, "TRUE   ", A_REPLACE);
    else
      DrawStr (0, 0, "NEITHER", A_REPLACE);
  }
  DrawStr (0, 0, "SPACE  ", A_REPLACE);
  GKeyIn (NULL, 0);
}

Uses: strchr, XR_stringPtr
Used by: GM_Shade


ngetchx

ngetchx Function (ROM Call 0x51)
kbd.h

short ngetchx (void);

Gets character from the keyboard, without echoing to the screen.

ngetchx reads a single character directly from the keyboard, without echoing to the screen. If the keyboard queue is empty, ngetchx will wait for the keypress, else the character will be picked from the keyboard queue.

ngetchx returns the code of the character read from the keyboard. This code is mainly the same as TI-Basic function GetKey returns. All keypresses which correspond to the ASCII character will return the ASCII code of it, for example pressing on '+' key will return the ASCII code of '+' (which is 43 in decimal), so you can write

if (ngetchx () == '+') ...
Codes for some other common keypresses which do not have an ASCII representation (ESC, ENTER, function keys, etc.) and which are the same on the TI-89 and TI-92 Plus are defined in the enum CommonKeys (for example, KEY_ESC, KEY_ENTER etc.).

Be aware that codes assigned to arrow keys is shuffled in comparation with TI-Basic. These codes are also different on TI-89 and TI-92 Plus. Note that the documentation of releases of TIGCCLIB prior to 2.0 has an error: it recommends usage of OSGetStatKeys as a calculator-independent method for reading arrow keys. This is simply not true. Here is a table of return codes for pressing arrow keys on TI-89 and TI-92 Plus:

TI-89:

Key | Normal | +Shift | +2nd | +Diamond | +alpha
Up | 337 | 8529 | 4433 | 16721 | 33105
Right | 344 | 8536 | 4440 | 16728 | 33112
Down | 340 | 8532 | 4436 | 16724 | 33108
Left | 338 | 8530 | 4434 | 16722 | 33106

TI-92+:

Key | Normal | +Shift | +2nd | +Diamond | +alpha
Up | 338 | 16722 | 4434 | 8530 | 33106
Right | 340 | 16724 | 4436 | 8532 | 33108
Down | 344 | 16728 | 4440 | 8536 | 33112
Left | 337 | 16721 | 4433 | 8529 | 33105

It is interesting that the ngetchx function is able to handle pressing to more than one arrow keys at the same moment. The returned value is then simply logical OR of values for a particular key.

To increase compatibility between TI-89 and TI-92 Plus, a header file compat.h is implemented. This file (among others) defines pseudo-constants (known from DoorsOS) like KEY_LEFT, KEY_RIGHT, KEY_UP and KEY_DOWN which represent return values for arrow keys. These "pseudo-constants" have different values on the TI-89 and TI-92 Plus, so if you use testing like
if (key == KEY_LEFT) ...
such test will work fine on both the TI-89 and TI-92 Plus. These pseudo-constants works in both "nostub" and "DoorsOS" mode. Pseudo-constants KEY_UPRIGHT and KEY_DOWNLEFT are also defined, with obvious meaning.

Codes of keystrokes like <Diamond> + <key> are also different in comparison with the TI-Basic GetKey function. I will not give a complete table here, because such keystrokes are rarely used in programs. If you are interested for a code of the concrete keystroke, you can easily find it by yourself. Principally, the code for a keystroke like <Diamond> + <key> is mainly equal to the code for <key> increased by KEY_DIAMOND. This is also a pseudo-constant with value 16384 on TI-89 and 8192 on TI-92 Plus. The same is true for keystrokes like <Shift> + <key>, and the appropriate pseudo-constant which need to be added is called KEY_SHIFT (8192 on TI-89 and 16384 on TI-92 Plus).

As a side effett, ngetchx also sets the activity in the status bar to BUSY, so the "BUSY" indicator will appear in the status bar. If you want later to remove the "BUSY" indicator, you must call ST_busy function to do this.

Note: ngetchx function is slow, because it also handles receiving eventual bytes from the link port. This is used in TIOS mainly when the calculator is in the Home screen, but principally, if the program is waiting for a keypress using ngetchx function, any valid data which come to the link port will be received and processed accordingly (for example, the program waiting for a keypress can accept another program via the link port during waiting). See kbd_queue for much faster way to gets characters from the keyboard.

Uses: OSFastArrows, HomeAlone, OSCheckSilentLink, OSLinkCmd, OSReadLinkBlock, OSWriteLinkBlock, OSdequeue, OSSetSR, OSTimerRestart, ROM Call 0x471
Used by: assert, cmd_disptbl, cmd_pause, push_getkey, EV_eventLoop, EV_getc, fgetchar, gets, getsn, GS_PlotAll, GZ_Stat, Regraph

See also: GKeyIn, kbhit, kbd_queue, OSFastArrows


OSGetStatKeys

OSGetStatKeys Function (ROM Call 0x299)
kbd.h

short OSGetStatKeys (void);

Checks whether an arrow key (TI-89) or status key (TI-92+) is pressed.

OSGetStatKeys is a strange function: it behaves differently on TI-89 and on TI-92 Plus. On TI-89 it returns ARROW_LEFT, ARROW_RIGHT, ARROW_UP or ARROW_DOWN if one of the corresponding arrow keys is pressed (these constants are defined in enum Arrows). On TI-92 Plus it returns STAT_2ND, STAT_DIAMOND, STAT_SHIFT of STAT_HAND if one of the corresponding status key is pressed (these constants are defined in enum StatKeys). If no arrow keys is pressed (TI-89) or if no status keys is pressed (TI-92 Plus), this function returns zero. OSGetStatKeys does not wait for a keypress. If more than one arrow/status key is pressed, OSGetStatKeys returns a garbage value.

Note: The information about this functions in releases of TIGCCLIB prior to 2.0 were incomplete: I didn't notice different behaviour on TI-89 and TI-92 Plus. So, avoid this function in portable programs.


OSInitBetweenKeyDelay

OSInitBetweenKeyDelay Function (ROM Call 0x249*)
kbd.h

short OSInitBetweenKeyDelay (short rate);

Sets the rate at which a key autorepeats.

OSInitBetweenKeyDelay sets the rate at which a key autorepeats to rate (note that only few keys have an autorepeat feature, namely arrow keys and backspace). The measuring unit for this function is 1/395 s (because Auto-Int 1 is triggered 395 times per second), and the default value for rate is 48. OSInitBetweenKeyDelay returns the previous autorepeat rate.

Greg Dietsche pointed out that on HW2 (precisely, if the gateArray field of the structure returned by FL_getHardwareParmBlock exists and is 2 or higher), TIOS immediately multiplies the value passed to it by 3/4. This is probably a bug, as this implies that there is no way to restore the rate to the value previously returned by OSInitBetweenKeyDelay. To work around this problem, OSInitBetweenKeyDelay is defined as a macro which detects this modification in a smart way, and tries to revert it for the return value.

Uses: FL_getHardwareParmBlock


OSInitKeyInitDelay

OSInitKeyInitDelay Function (ROM Call 0x248)
kbd.h

short OSInitKeyInitDelay (short delay);

Sets the initial autorepeat key delay.

OSInitKeyInitDelay sets the time that a key has to be held down before it starts to repeat to delay (note that only few keys have autorepeat feature, like arrow keys and backspace). Measuring unit for this function is 1/395 s (because Auto-Int 1 is triggered 395 times per second), and the default value for delay is 336 (slightly shorter than 1 second). OSInitKeyInitDelay returns previous autorepeat key delay.


pushkey

pushkey Function (ROM Call 0x50)
kbd.h

void pushkey (short code);

Replaces the keystroke in the keyboard queue with the given code.

If the keyboard queue is empty, pushkey pushes code in the keyboard queue, then sets the "keypressed" flag. If the keyboard queue is not empty, pushkey replaces the keystroke on the top of the keyboard queue with code. In each case, the next call of ngetchx will return code.

Uses: kbhit, OSdequeue, OSenqueue, OSSetSR
Used by: cmd_disptbl, GS_PlotAll, GT_FreeTrace, GT_KeyIn, GT_Trace, GZ_Stat, Regraph, ROM Call 0x3EA


restoreAlphaLock

restoreAlphaLock Function (ROM Call 0x483)
AMS 2.00 or higher kbd.h

void restoreAlphaLock (unsigned char *Status);

Restores the alpha-lock status.

restoreAlphaLock restores the alpha-lock status to the value saved in Flags, which is obtained through a call to alphaLockOn or alphaLockOff. It seems that these are the valid values for *Status:

0 | Alpha-lock is turned off.
1 | Alpha-lock is turned on.
2 | Uppercase alpha-lock is turned on. However, GetAlphaStatus will then return FALSE. This is the value which is used if the user presses SHIFT and then ALPHA.
3 | Uppercase alpha-lock is turned on. GetAlphaStatus will return TRUE.

On the TI-92+, the function does nothing.

Used by: Dialog, MenuKey, ROM Call 0x421

See also: alphaLockOn, alphaLockOff, SetAlphaStatus


SetAlphaStatus

SetAlphaStatus Function (ROM Call 0x163)
AMS 2.00 or higher kbd.h

void SetAlphaStatus (unsigned char Status);

Sets the alpha-lock status on the TI-89.

There are two valid values for Status: TRUE turns the alpha-lock on; FALSE turns it off.
On the TI-92+, the function does nothing.

See also: GetAlphaStatus


OSFastArrows

OSFastArrows Variable (ROM Call 0x15C)
kbd.h

unsigned char OSFastArrows;

A variable determining whether arrow keys are repeated slowly or quickly.

OSFastArrows tells ngetchx, GKeyIn, and OSdequeue how to handle the arrow keys.

Once a key value is pushed onto the key queue, the same key value is not pushed again until the key is released, unless that key is one of the following: any of the arrow keys, the contrast keys, delete, or backspace. These keys are allowed to "auto-repeat". If one of these keys is pressed and held, after an initial delay, the same key value will be pushed again. If the keypress continues to be active, the key value will continue to be pushed at a rate set by a delay which is slightly shorter than the initial delay. If a key is pushed as a result of this auto-repeat feature, the value KB_AUTOREPEAT is OR’d with the key value prior to pushing the key value onto the key queue.

It seems that the following values are allowed:

0 | Keys are repeated at normal speed. This is the default. In this case, ngetchx will clear the KB_AUTOREPEAT bit from the key value.
1 | Same as 0 for ngetchx, but in text editors like the home screen entry line, keys are not repeated at all.
2 | The key delay is ignored; ngetchx returns immediately if an arrow key is pressed. In text editors, the busy indicator is visible, but keys do not seem to be repeated.

Further information is welcome.

Used by: ngetchx, GT_Trace, ROM Call 0x473

See also: ngetchx, OSInitBetweenKeyDelay, OSInitKeyInitDelay


KB_AUTOREPEAT

KB_AUTOREPEAT Constant (Macro)
kbd.h, system.h

#define KB_AUTOREPEAT (1<<11)

A constant defining the "auto-repeat" bit.

KB_AUTOREPEAT is a constant defining the "auto-repeat" bit in key values, please see OSFastArrows for more informations.

See also: OSFastArrows


Arrows

Arrows Type (Enumeration)
kbd.h

enum Arrows {ARROW_UP = 1, ARROW_LEFT = 2, ARROW_DOWN = 3, ARROW_RIGHT = 4};

An enumeration for describing the four arrow keys.

Arrows is an enumeration for describing the return values of the function OSGetStatKeys, which is used for reading arrow keys (TI-89 only).


CommonKeys

CommonKeys Type (Enumeration)
kbd.h, menus.h

enum CommonKeys {KEY_F1 = 268, KEY_F2 = 269, KEY_F3 = 270, KEY_F4 = 271, KEY_F5 = 272, KEY_F6 = 273, KEY_F7 = 274, KEY_F8 = 275, KEY_ESC = 264, KEY_QUIT = 4360, KEY_APPS = 265, KEY_SWITCH = 4361, KEY_MODE = 266, KEY_BACKSPACE = 257, KEY_INS = 4353, KEY_CLEAR = 263, KEY_VARLNK = 4141, KEY_CHAR = 4139, KEY_ENTER = 13, KEY_ENTRY = 4109, KEY_STO = 258, KEY_RCL = 4354, KEY_SIGN = 173, KEY_MATH = 4149, KEY_MEM = 4150, KEY_ON = 267, KEY_OFF = 4363};

An enumeration for describing common key codes.

CommonKeys is enumerated type for decribing codes of various common keypresses, which usually does not ASCII representation, and which are the same on TI-89 and TI-92 Plus. Note that codes of keypresses like HOME, CATALOG etc. are not defined here, because they are not the same on TI-89 and TI-92 Plus. See compat.h for more info how to detect the calculator version.


GKeyFlags

GKeyFlags Type (Enumeration)
kbd.h

enum GKeyFlags {GKF_NORMAL=0, GKF_MODAL=1, GKF_REPUSH_KEY=2, GKF_ACCEPT=4, GKF_SYS=8, GKF_NO_EVS=16};

Enumerates different key options flags for the GKeyIn routine.

Enumerates different key options flags. The meanings of these flags are given in GKeyIn.

See also: GKeyIn


StatKeys

StatKeys Type (Enumeration)
kbd.h

enum StatKeys {STAT_2ND = 1, STAT_DIAMOND = 2, STAT_SHIFT = 3, STAT_HAND = 4};

An enumeration for describing modifier key values.

StatKeys is an enumerated type for describing the return values of the function OSGetStatKeys, which is used for reading the status keys (TI-92 Plus only).


limits.h

limits.h Header File
Header File Index

Various platform-dependent constants proposed by ANSI

Constants
CHAR_BIT
Length of a char variable in bits.
CHAR_MAX
Maximal value which can be stored in a char variable.
CHAR_MIN
Minimal value which can be stored in a char variable.
INT_MAX
Maximal value which can be stored in an int variable.
INT_MIN
Minimal value which can be stored in an int variable.
LONG_MAX
Maximal value which can be stored in a long int variable.
LONG_MIN
Minimal value which can be stored in a long int variable.
SCHAR_MAX
Maximal value which can be stored in a signed char variable.
SCHAR_MIN
Minimal value which can be stored in a signed char variable.
SHRT_MAX
Maximal value which can be stored in a short int variable.
SHRT_MIN
Minimal value which can be stored in a short int variable.
UCHAR_MAX
Maximal value which can be stored in an unsigned char variable.
UINT_MAX
Maximal value which can be stored in an unsigned int variable.
ULONG_MAX
Maximal value which can be stored in an unsigned long int variable.
USHRT_MAX
Maximal value which can be stored in an unsigned short variable.

Note: CHAR_MAX and CHAR_MIN may have different values depending on whether chars are signed or not. They are signed by default in GCC4TI, but this may be changed using a compiler command-line switch. Similarly, INT_MAX, INT_MIN, and UINT_MAX depend on whether short or long integers are used.

See also: values.h


CHAR_BIT

CHAR_BIT Constant
limits.h

#define CHAR_BIT 8

Length of a char variable in bits.


CHAR_MAX

CHAR_MAX Constant
limits.h

#define CHAR_MAX 127/255

Maximal value which can be stored in a char variable.


CHAR_MIN

CHAR_MIN Constant
limits.h

#define CHAR_MIN (-128)/0

Minimal value which can be stored in a char variable.


INT_MAX

INT_MAX Constant
limits.h

#define INT_MAX 0x7FFF/0x7FFFFFFF

Maximal value which can be stored in an int variable.


INT_MIN

INT_MIN Constant
limits.h

#define INT_MIN ((int) 0x8000/0x80000000)

Minimal value which can be stored in an int variable.


LONG_MAX

LONG_MAX Constant
limits.h

#define LONG_MAX 0x7FFFFFFFL

Maximal value which can be stored in a long int variable.


LONG_MIN

LONG_MIN Constant
limits.h

#define LONG_MIN ((long) 0x80000000L)

Minimal value which can be stored in a long int variable.


SCHAR_MAX

SCHAR_MAX Constant
limits.h

#define SCHAR_MAX 127

Maximal value which can be stored in a signed char variable.


SCHAR_MIN

SCHAR_MIN Constant
limits.h

#define SCHAR_MIN (-128)

Minimal value which can be stored in a signed char variable.


SHRT_MAX

SHRT_MAX Constant
limits.h

#define SHRT_MAX 0x7FFF

Maximal value which can be stored in a short int variable.


SHRT_MIN

SHRT_MIN Constant
limits.h

#define SHRT_MIN ((short) 0x8000)

Minimal value which can be stored in a short int variable.


UCHAR_MAX

UCHAR_MAX Constant
limits.h

#define UCHAR_MAX 255

Maximal value which can be stored in an unsigned char variable.


UINT_MAX

UINT_MAX Constant
limits.h

#define UINT_MAX 0xFFFFU/0xFFFFFFFFUL

Maximal value which can be stored in an unsigned int variable.


ULONG_MAX

ULONG_MAX Constant
limits.h

#define ULONG_MAX 0xFFFFFFFFUL

Maximal value which can be stored in an unsigned long int variable.


USHRT_MAX

USHRT_MAX Constant
limits.h

#define USHRT_MAX 0xFFFFU

Maximal value which can be stored in an unsigned short variable.


link.h

link.h Header File
Header File Index

Calc/calc and calc/computer link interface routines

Functions
getcalc
Receives a variable (or program) from the link interface.
LIO_Get
Gets a CBL file from the link interface.
LIO_GetMultiple
Gets a multiple (???) from the link interface.
LIO_Receive
Receives a file from the link interface.
LIO_RecvData
Receives data from the link interface.
LIO_Send
Sends a file through the link interface.
LIO_SendData
Sends data through the link interface.
LIO_SendIdList
Sends the ID list of the calculator through the link port.
LIO_SendProduct
Sends a product code through the link interface.
OSCheckLinkOpen
Checks if the link port is open.
OSCheckSilentLink
Checks the link state.
OSLinkClose
Closes a low-level link communication.
OSLinkCmd
Process the command received through the link port.
OSLinkOpen
Opens low-level link communication.
OSLinkReset
Resets the link interface.
OSLinkTxQueueActive
Determines whether the transmit queue is active.
OSLinkTxQueueInquire
Determines the number of free bytes in the transmit buffer.
OSReadLinkBlock
Reads bytes from the link receive buffer.
OSWriteLinkBlock
Inserts bytes into the link transmit buffer.
sendcalc
Sends a variable (or program) through the link interface.
Constants
NULL
A null-pointer value.
Predefined Types
Bool
An enumeration to describe true or false values.
CESI
Represents a pointer to a constant expression.
ESI
Represents an index of a value on the TIOS expression stack.
ESQ
Represents a quantum within an expression.
LIO_CTX
A file context structure used in some high-level link commands.
size_t
A type to define sizes of strings and memory blocks.
SYM_STR
Represents a pointer to the terminating zero byte of a string.

Note: Some functions from this header file are straightforward and quite simple to use, but some of them require good knowledge of TI's communication protocols (much better than my knowledge about it, so don't ask me about details; protocol information can be found at http://www.ticalc.org/pub/text/calcinfo/tixx_guide.zip).


getcalc

getcalc Function (ROM Call 0x54)
link.h

void getcalc (SYM_STR SymName);

Receives a variable (or program) from the link interface.

getcalc receives a variable (or program) from the link interface (this is exactly what the TI-Basic command GetCalc does). SymName is a pointer to the variable name. Note that SymName is not an ordinary C string. Instead, it is zero-started zero-terminated string, and SymName points to the terminating byte of it (many TIOS functions for manipulating with TIOS variables use such strings). See SYMSTR and other functions from the vat.h header file for more info about symbol names).

Note: getcalc enters a loop which will not end until the data is received. The only method to break out of this loop (if no data is received) is pressing the 'ON' key.

Uses: LIO_GetMultiple, LIO_Receive, OSLinkReset, push_indir_name, ER_throwVar, top_estack, NeedStack, ParseSymName, VarStoreLink, SymSysVar
Used by: cmd_getcalc

See also: sendcalc, cmd_getcalc


LIO_Get

LIO_Get Function (ROM Call 0x57)
link.h

unsigned short LIO_Get (LIO_CTX *file);

Gets a CBL file from the link interface.

LIO_Get is a high-level function which receives a CBL (Calculator-Based Laboratory) file through the link interface and fills LIO_CTX structure pointed to by file accordingly (note that I don't know much more about it). LIO_Get returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

Uses: LIO_RecvData, LIO_SendData, OSLinkClose, OSLinkOpen, OSLinkReset, HeapAlloc, HeapLock, HeapUnlock, strlen, strncpy, OSClearBreak
Used by: cmd_get


LIO_GetMultiple

LIO_GetMultiple Function (ROM Call 0x59)
link.h

short LIO_GetMultiple (LIO_CTX *file);

Gets a multiple (???) from the link interface.

Yet another unclear high-level link routine. It is called often as a subroutine in other high-level linking routines. In fact, it just performs

LIO_Receive (file, 0, 0);
but returns a different result. If LIO_Receive returns 0, LIO_GetMultiple returns -1. If LIO_Receive returns 0xFFFF, LIO_GetMultiple returns 0. Else, LIO_GetMultiple returns the same value returned from LIO_Receive. Don't ask me what it means. Any additional info is welcomed.

Uses: LIO_Receive, OSLinkReset
Used by: getcalc


LIO_Receive

LIO_Receive Function (ROM Call 0x58)
link.h

unsigned short LIO_Receive (LIO_CTX *file, unsigned short DevType, short skipmuch);

Receives a file from the link interface.

LIO_Receive is a high-level function which receives a file (a variable for example) through the link interface and fills the LIO_CTX structure pointed to by file accordingly. However, this function is not so easy for usage, because you need to interpret the file context structure pointed to by file manually after using this function, which is not a trivial task. If you want just to receive a variable through the link interface, function getcalc is much easier to use. The advantage of this routine is greater generality in comparing to getcalc (for example, it allows transfer even between incompatible TI models, if properly used; sorry, I don't know too much about it).

The parameter DevType determines the device type (see LIO_Send for the explanation about its meaning). It seems that it is possible to set DevType to zero (it probably means "receive from anything").

The parameter skipmuch is a boolean parameter (if it is non-zero, a lot of code in this function is skipped over). skipmuch has to do with the Silent Link mode (see OSCheckSilentLink). When receiving a file manually, the AMS calls LIO_Receive with a value of 0 for skipmuch; in Silent Link mode, LIO_Receive is called with a value of 1 once the header has been read, to transfer the file properly.

LIO_Receive returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

Uses: LIO_RecvData, LIO_SendData, OSLinkClose, OSLinkReset, OSLinkTxQueueActive, HeapAlloc, HeapFree, HeapLock, HeapRealloc, HeapUnlock, cgetsn, Dialog, ER_catch, ER_success, HToESI, BatTooLowFlash, EM_abandon, FL_download, FL_getHardwareParmBlock, FL_getVerNum, memcpy, memset, sprintf, strcat, strncpy, AB_getGateArrayVersion, OSClearBreak, XR_stringPtr, gen_version, is_executable, LoadSymFromFindHandle, OO_GetAppAttr, ST_flags, TIOS_EV_getAppID, ClearUserDef, FolderCount, FolderDel, StrToTokN, SymCpy0, SymDel, SymDelTwin, SymFindFirst, SymFindFolderName, SymFindNext, ROM Call 0x418, ROM Call 0x424, ROM Call 0x428, ROM Call 0x4FD, ROM Call 0x4FE
Used by: getcalc, LIO_GetMultiple, OSLinkCmd


LIO_RecvData

LIO_RecvData Function (ROM Call 0x5B)
link.h

unsigned short LIO_RecvData (void *dest, unsigned long size, unsigned long WaitDelay);

Receives data from the link interface.

LIO_RecvData reads size bytes through the link interface, and stores received bytes at the address dest. This functions calls repeatedly OSReadLinkBlock function as many times as necessary to receive wanted amount of data. Parameter WaitDelay is the maximal allowed waiting time: if no data is received during WaitDelay timer ticks (one timer tick is 1/20 seconds by default), the reading fails. When WaitDelay is set to zero, this means "waiting forever". Anyway, this operation may be interrupted by pressing ON key. LIO_RecvData returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

Note: This functions registers LIO_TIMER for measuring the time. See OSRegisterTimer for more info.

Uses: OSReadLinkBlock, OSLinkReset, off, OSClearBreak, OSFreeTimer, OSRegisterTimer, OSTimerExpired, OSTimerRestart, ROM Call 0x46E
Used by: LIO_Get, LIO_Receive, LIO_Send, LIO_SendProduct, OSCheckSilentLink, OSLinkCmd, handleVarLinkKey, LIO_SendIdList


LIO_Send

LIO_Send Function (ROM Call 0x56)
link.h

unsigned short LIO_Send (LIO_CTX *file, unsigned short DevType);

Sends a file through the link interface.

LIO_Send is a high-level function which sends a file (a variable, a screen dump file, etc.) described by the LIO_CTX structure pointed to by file through the link interface. However, this function is not so easy for usage, because you need to fill the file context structure pointed to by file manually before using this function. If you want just to send a variable through the link interface, function sendcalc is much easier to use. The advantage of this routine is greater generality in comparing to sendcalc (for example, it allows transfer even between incompatible TI models, if properly used; sorry, I don't know too much about it).

Parameter DevType determines the device type (this information is stored in the header of each packet during the communication). It is a collection of flags. Bit b7 is 0 during transfer from a computer to a calculator and 1 during transfer from a calculator to a computer or another calculator. Bits b6 and b5 are reserved (keep them to 0). Bit b4 is 1 if a device is a "special" device, whatever it means (so far, I know that this bit is set if a device is TI-89 or CBL). Bits b3-b0 determine the calculator type (so far, I know the following meanings: 0010 for TI-82, 0011 for TI83, 0101 for TI85, 1000 for TI-89 or TI-92 Plus, and 1001 for TI-92). So, DevType should to be 0x98 for sending from TI-89 or 0x88 for sending from TI-92 Plus.

LIO_Send returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

Uses: LIO_RecvData, LIO_SendData, OSLinkClose, OSLinkOpen, OSLinkReset, strlen, OSClearBreak, ROM Call 0x46E
Used by: sendcalc, cmd_send, LIO_SendIdList


LIO_SendData

LIO_SendData Function (ROM Call 0x5A)
link.h

unsigned short LIO_SendData (const void *src, unsigned long size);

Sends data through the link interface.

LIO_SendData sends size bytes from the address src through the link interface. This function calls repeatedly OSWriteLinkBlock function as many times as necessary to send all of data. Returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

Uses: OSLinkTxQueueInquire, OSWriteLinkBlock, OSFreeTimer
Used by: LIO_Get, LIO_Receive, LIO_Send, LIO_SendProduct, OSLinkCmd, HeapWalk, handleVarLinkKey, LIO_SendIdList


LIO_SendIdList

LIO_SendIdList Function (ROM Call 0x3D0)
AMS 2.00 or higher link.h

unsigned short LIO_SendIdList (unsigned short delete);

Sends the ID list of the calculator through the link port.

If the ID list does not exist, creates one using the calculator's ID. Otherwise, the calculator ID is appended. This list is then sent over the link port.
If delete is TRUE, the ID list is deleted from memory after it is sent.
The function returns non-zero if an error occurs, otherwise it returns zero.

Uses: freeIdList, HeapAlloc, cgetsn, FL_getVerNum, LIO_RecvData, LIO_Send, LIO_SendData, OSLinkReset, memcpy, sprintf

See also: freeIdList


LIO_SendProduct

LIO_SendProduct Function (ROM Call 0x253)
link.h

unsigned short LIO_SendProduct (LIO_CTX *file, unsigned short DevType);

Sends a product code through the link interface.

LIO_SendProduct is a high-level function which sends a Product Code through the link interface. What exactly will be sent is described in LIO_CTX structure pointed to by file. Parameter DevType determines the device type (see LIO_Send for the explanation about its meaning). This routine is called from the VAR_LINK menu. Returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values).

Uses: LIO_RecvData, LIO_SendData, OSLinkClose, OSLinkOpen, OSLinkReset, OSClearBreak


OSCheckLinkOpen

OSCheckLinkOpen Function (ROM Call 0x5E3*)
link.h

unsigned short OSCheckLinkOpen (void);

Checks if the link port is open.

This function returns TRUE if the link port is open, FALSE otherwise.

See also: OSLinkOpen


OSCheckSilentLink

OSCheckSilentLink Function (ROM Call 0x24A)
link.h

short OSCheckSilentLink (void);

Checks the link state.

OSCheckSilentLink returns an integer which determines the link state. The meaning of the returned value is:

0 | None (the link is silent)
1 | A variable header or extended header is received
2 | A direct command, a screen dump, a request with size or a request is in progress
3 | The link is ready

This function is called from high-level keyboard reading functions like kbhit and ngetchx, and if it returns non-zero, OSLinkCmd is called to process the received packet (as the link is interrupt-driven, a packet may be received asynchronously, without the request from the program itself). So, the TIOS can receive variables from the link whenever the program is waiting for a keypress (used mainly when the calculator is in the Home Screen).

Uses: LIO_RecvData, OSLinkClose, OSLinkReset
Used by: kbhit, ngetchx


OSLinkClose

OSLinkClose Function (ROM Call 0x24E)
link.h

void OSLinkClose (void);

Closes a low-level link communication.

OSLinkClose waits until eventual bytes waiting in transmit queue are sent out, then clears both transmit and receive queues, and clear a flag which tells that the communication is opened.

Uses: ROM Call 0x46E
Used by: LIO_Get, LIO_Receive, LIO_Send, LIO_SendProduct, OSCheckSilentLink, cmd_sendcalc, cmd_sendchat


OSLinkCmd

OSLinkCmd Function (ROM Call 0x24B)
link.h

void OSLinkCmd (short NormalState);

Process the command received through the link port.

OSLinkCmd should to be called after OSCheckSilentLink if the result returned from it is non-zero (this means that there is a packet received from the link port, which waits to be processed). This function handles link commands when the calculator is in the Home Screen for example (link commands are stored in packets). Parameter NormalState should to be set to TRUE if the calculator is in a "normal receiving state", i.e. if the current application is "Home Screen", if the screen is not splitted, and if there is no any event-driven "applets" installed using EV_captureEvents (see events.html for more info). This parameter helps TIOS to conclude which link commands should be processed, and which commands should be rejected (for example, the calculator cannot receive variables if it is not in a "normal receiving state").

Uses: LIO_Receive, LIO_RecvData, LIO_SendData, OSLinkReset, sendcalc, HeapFree, cmd_archive, ER_catch, ER_success, bottom_estack, HToESI, push_END_TAG, push_quantum, reset_estack_size, top_estack, MO_currentOptions, MO_digestOptions, BatTooLowFlash, EM_abandon, EM_GC, FL_getHardwareParmBlock, LCD_MEM, gr_active, gr_other, ST_eraseHelp, ST_folder, ST_helpMsg, strcat, strcmp, strlen, AB_getGateArrayVersion, OSenqueue, OSqclear, OSqinquire, XR_stringPtr, EV_appA, EV_appB, gr_delete_fldpic, gr_DelFolder, LoadSymFromFindHandle, ParseSymName, PlotInit, ST_flags, VarStoreLink, ClearUserDef, DerefSym, FolderCount, FolderDel, GetDataType, HSymDel, StrToTokN, SymCpy0, SymDel, SymDelTwin, SymFindFirst, SymFindFolderName, SymFindNext, SymSysVar, VarRecall, ROM Call 0x46E
Used by: kbhit, ngetchx


OSLinkOpen

OSLinkOpen Function (ROM Call 0x24D)
link.h

void OSLinkOpen (void);

Opens low-level link communication.

OSLinkOpen clears both transmit and receive queues, then set a flag which tells that the communication is opened.

Uses: off, OSFreeTimer, OSTimerExpired, OSTimerRestart, ROM Call 0x46E, ROM Call 0x4F4
Used by: LIO_Get, LIO_Send, LIO_SendProduct, cmd_sendcalc, cmd_sendchat

Deprecated alias: flush_link


OSLinkReset

OSLinkReset Function (ROM Call 0x24C)
link.h

void OSLinkReset (void);

Resets the link interface.

OSLinkReset resets the link interface. It also resets all link variables and performs OSLinkClose.

Used by: getcalc, LIO_Get, LIO_GetMultiple, LIO_Receive, LIO_RecvData, LIO_Send, LIO_SendProduct, OSCheckSilentLink, OSLinkCmd, cmd_sendcalc, cmd_sendchat, LIO_SendIdList

Deprecated alias: reset_link


OSLinkTxQueueActive

OSLinkTxQueueActive Function (ROM Call 0x252)
link.h

short OSLinkTxQueueActive (void);

Determines whether the transmit queue is active.

OSLinkTxQueueActive returns TRUE if the transmit queue is active, else returns FALSE. This function checks bit b1 in I/O port 0x60000C (interrupt on transmit buffer empty).

Used by: LIO_Receive


OSLinkTxQueueInquire

OSLinkTxQueueInquire Function (ROM Call 0x251)
link.h

unsigned short OSLinkTxQueueInquire (void);

Determines the number of free bytes in the transmit buffer.

OSLinkTxQueueInquire returns the number of free bytes in the link transmit buffer. Note that this number may change in a time without any obvious actions, because the link communication is interrupt driven.

Used by: LIO_SendData

Deprecated alias: tx_free


OSReadLinkBlock

OSReadLinkBlock Function (ROM Call 0x24F)
link.h

unsigned short OSReadLinkBlock (char *buffer, unsigned short num);

Reads bytes from the link receive buffer.

OSReadLinkBlock reads at most num bytes into buffer from the link receive buffer. Returns the number of bytes read.

Note: This function is a low-level function. See also LIO_RecvData for a higher-level variant of this function.

Used by: LIO_RecvData, ngetchx

Deprecated alias: receive

See also: LIO_RecvData


OSWriteLinkBlock

OSWriteLinkBlock Function (ROM Call 0x250)
link.h

short OSWriteLinkBlock (const char *buffer, unsigned short num);

Inserts bytes into the link transmit buffer.

OSWriteLinkBlock inserts num bytes from buffer into the link transmit buffer. Returns 0 if the operation was sucessful, else returns a non-zero value. num must be in the range 1-128. An error occurs if num is out of range or if there is not enough room in the transmit buffer to insert num bytes.

Note: This function is a low-level function. See also LIO_SendData for a higher-level variant of this function.

Used by: LIO_SendData, Dialog, ERD_dialog, HomeExecute, ngetchx, ROM Call 0x3EA

Deprecated alias: transmit

See also: LIO_SendData


sendcalc

sendcalc Function (ROM Call 0x55)
link.h

unsigned short sendcalc (SYM_STR SymName, short allowSysVars, unsigned short DevType, unsigned char *compat);

Sends a variable (or program) through the link interface.

sendcalc sends a variable (or program) through the link interface (this is exactly what the TI-Basic command SendCalc does). SymName is a pointer to the variable name. allowSysVars is a Boolean parameter. If it is TRUE, transfer of a system variable will be allowed, and if it is FALSE, such transfer will be rejected. DevType determines the device type (see LIO_Send for the explanation about its meaning). If Compat is not a NULL pointer, sendcalc also stores in a byte variable pointed to by compat compatibility information about the variable which will be transfered (see info about SYM_ENTRY structure in vat.h header file for more info about compatibility flags).

Note that SymName is not an ordinary C string. Instead, it is zero-started zero-terminated string, and SymName points to the terminating byte of it (many TIOS functions for manipulating with TIOS variables use such strings). See SYMSTR and other functions from the vat.h header file for more info about symbol names). For example, to send a variable called "example" from one TI-89 unit to another, use the following command:

sendcalc (SYMSTR ("example"), FALSE, 0x98, NULL);
Replace 0x98 with 0x89 to simulate TI-Basic SendChat command instead of SendCalc.

sendcalc returns zero if the operation was successful, else returns a non-zero value (this value describes the type of the error, but I am not sure about the concrete meaning of particular values). This function also may throw an error in a case of various fatal errors, so error trapping (using functions from the error.h header file) is recommended.

Uses: LIO_Send, push_indir_name, HToESI, top_estack, strcmp, convert_to_TI_92, ParseSymName, CheckLinkLockFlag, CheckSysFunc, DerefSym, GetDataType, SymSysVar, VarRecall
Used by: OSLinkCmd, cmd_sendcalc, cmd_sendchat

See also: getcalc, cmd_sendcalc, cmd_sendchat


LIO_CTX

LIO_CTX Type (Structure)
link.h

typedef struct {
unsigned short hVar; /* File handle (or 0 if no handles associated) */
union {
const void *pVar; /* Pointer to the file, used only if hVar is 0 */
struct {
unsigned short FindFlags;
unsigned short NameSym;
} DirVars; /* Used only if hVar is non-zero */
} extra;
const char *VarName; /* Pointer to the var name (ordinary C string) */
unsigned long VarSize; /* Size of the variable */
unsigned short Index; /* Only for CBL access - data sent as float array */
unsigned short Unknown; /* Sent after index */
unsigned char VarType; /* See below */
unsigned char VarCompat; /* See info about SYM_ENTRY in vat.h */
} LIO_CTX;

A file context structure used in some high-level link commands.

LIO_CTX is a file context structure used in some high-level link commands. Some fields of this structure are not so clear for me. However, in many applications not all fields need to be set properly, so limited use of this structure is possible.

The field VarType may contain the following values (I don't know much more than I wrote in this table, so don't ask me about details):

0 | Expression
4 | List
6 | Matrix
10 | Data
11 | Text
12 | String
13 | GDB variable
14 | Geometry figure
16 | Picture
17 | Picture (???)
18 | TI-Basic program
19 | TI-Basic function
20 | Geometry macro
21 | In link protocol, cause execution of assembly block
25 | Directory list (used recursively, unless VarType 26 follows)
26 | List the folder table entries
27 | List contents of a given folder (VarType 26 should follow)
28 | Other (OTH) file
29 | Backup file
31 | Folder entry symbol in group files
32 | Used for getting a certificate
33 | ASM program
34 | ID List
35 | Product code (AMS)
36 | FLASH application
37 | Certificate


math.h

math.h Header File
Header File Index

ANSI-compatible routines for floating point arithmetic

Functions
abs
Absolute value of a number.
acos
Floating point arc cosine.
acosh
Floating point hyperbolic area cosine.
asin
Floating point arc sine.
asinh
Floating point hyperbolic area sine.
atan2
Four-quadrant arc tangent of y/x (or argument of the complex number).
atan
Floating point arc tangent.
atanh
Floating point hyperbolic area tangent.
atof
Converts a string to a floating point.
cacos
Complex arc cosine.
cacosh
Complex hyperbolic area cosine.
casin
Complex arc sine.
casinh
Complex hyperbolic area sine.
catan
Complex arc tangent.
catanh
Complex hyperbolic area tangent.
ccos
Complex cosine.
ccosh
Complex hyperbolic cosine.
ceil
Rounds up the floating point number.
cexp
Complex exponential function.
cln
Complex natural logarithm (base e).
clog10
Complex logarithm, base 10.
cos
Floating point cosine.
cosh
Floating point hyperbolic cosine.
csin
Complex sine.
csinh
Complex hyperbolic sine.
csqrt
Complex square root.
ctan
Complex tangent.
ctanh
Complex hyperbolic tangent.
exp
Floating point exponential function.
fabs
Absolute value of a floating point number.
floor
Rounds down the floating point number.
fmod
Calculates x modulo y, i.e. the remainder of x/y.
frexp10
Splits floating point number into mantissa and exponent.
hypot
Calculates hypotenuse of right triangle.
is_inf
Checks whether the argument is an infinite number.
is_nan
Checks whether the argument is Not_a_Number.
is_nzero
Checks whether the argument is negative zero.
is_pzero
Checks whether the argument is positive zero.
is_sinf
Checks whether the argument is signed infinity.
is_transfinite
Checks whether the argument is a transfinite number.
is_uinf_or_nan
Checks whether the argument is unsigned infinity or Not_a_Number.
is_uzero
Checks whether the argument is unsigned zero.
labs
Absolute value of a long integer number.
ldexp10
Calculates x times 10 raised to exponent.
log
Floating point natural logarithm (base e).
log10
Floating point logarithm, base 10.
modf
Splits floating point value into integer and fraction part.
pow
Floating point power function.
sin
Floating point sine.
sinh
Floating point hyperbolic sine.
sqrt
Floating point square root.
tan
Floating point tangent.
tanh
Floating point hyperbolic tangent.
Constants
HALF_PI
A constant with value PI/2.
NAN
A constant defining an undefined value.
NEGATIVE_INF
Represents an infinitely large negative quantity.
NEGATIVE_ZERO
Represents an infinitely small quantity which is known to be always non-positive.
PI
An approximated value of pi.
POSITIVE_INF
Represents an infinitely large positive quantity.
POSITIVE_ZERO
Represents an infinitely small quantity which is known to be always non-negative.
UNSIGNED_INF
Represents an infinite quantity.
UNSIGNED_ZERO
Represents an infinitely small quantity with indeterminate sign.
ZERO
A deprecated constant.
Predefined Types
bcd
Represents the internal organization of floating point numbers in the format recognized by the TIOS.
Bool
An enumeration to describe true or false values.

Note: All functions which return a result of type float are implemented as macros, although many of them exist as TIOS entries. This is done because the GCC convention for returning floating point values as function results differs from the convention expected by the TIOS. This note is mainly unimportant from the user's point of view. Also note that the timath.h header file contains all functions from math.h, but in addition to this, it also contains some TIOS-specific low-level floating point functions.


abs

abs Function (Macro)
math.h, stdlib.h, timath.h

any_type abs (any_type x);

Absolute value of a number.

abs returns the absolute value of a numeric argument x, which may be either an integer or a floating point value. The returned value is of the same type as the argument.

Note: abs is a smart macro compiling to open code which depends on the type of the argument.

See also: labs, fabs


acos

acos Function (ROM Call 0xF5*)
math.h, timath.h

float acos (float x);

Floating point arc cosine.

acos returns the arc cosine of floating point argument x. The result is always in radians.

Note: If the argument is not in range from -1 to 1, acos will return NAN.

Uses: itrig
Used by: cacos, GR3_handleEvent


acosh

acosh Function (ROM Call 0x288*)
math.h, timath.h

float acosh (float x);

Floating point hyperbolic area cosine.

asinh returns the hyperbolic area cosine of floating point argument x, Hyperbolic area cosine is defined as log(x+sqrt(x*x-1)).

Note: acosh will return NAN if x is smaller than 1.

Uses: fabs, is_transfinite, sqrt, TIOS_abs, _bcd_math


asin

asin Function (ROM Call 0xF6*)
math.h, timath.h

float asin (float x);

Floating point arc sine.

asin returns the arc sine of floating point argument x. The result is always in radians.

Note: If the argument is not in range from -1 to 1, asin will return NAN.

Uses: itrig
Used by: casin, push_asin


asinh

asinh Function (ROM Call 0x287*)
math.h, timath.h

float asinh (float x);

Floating point hyperbolic area sine.

asinh returns the hyperbolic area sine of floating point argument x. Hyperbolic area sine is defined as log(x+sqrt(x*x+1)).

Uses: fabs, is_transfinite, sqrt, TIOS_abs, _bcd_math
Used by: push_asinh


atan2

atan2 Function (ROM Call 0xF8*)
math.h, timath.h

float atan2 (float y, float x);

Four-quadrant arc tangent of y/x (or argument of the complex number).

atan2 returns the four-quadrant arc tangent of y/x. More precise, it returns the argument of the complex number x + y i. So, the result is in the range -pi to pi.

Note: atan2 produces correct results even when the resulting angle is near pi/2 or -pi/2 (x near zero). If both x and y are zeros, atan2 returns NAN.

Uses: is_sinf, is_transfinite, is_uinf_or_nan, _bcd_math
Used by: catan, cln, cmd_sinreg, push_rec_to_angle, GR3_handleEvent


atan

atan Function (ROM Call 0xF7*)
math.h, timath.h

float atan (float x);

Floating point arc tangent.

asin returns the arc tangent of floating point argument x. The result is always in radians.

Uses: itrig
Used by: push_atan


atanh

atanh Function (ROM Call 0x289*)
math.h, timath.h

float atanh (float x);

Floating point hyperbolic area tangent.

atanh returns the hyperbolic area tangent of floating point argument x. The hyperbolic area tangent is defined as log((1+x)/(1-x))/2.

Note: atanh will return NAN if x is smaller than -1 or greater than 1. Also, it will return POSITIVE_INF if x is 1, and NEGATIVE_INF if x is -1.

Uses: fabs, is_transfinite, sqrt, TIOS_abs, _bcd_math
Used by: catan


atof

atof Function (tigcc.a)
AMS 1.01 or higher math.h, stdlib.h, timath.h

float atof (const char *s);

Converts a string to a floating point.

atof converts a string pointed to by s to floating point value. It recognizes the character representation of a floating point number, made up of the following:

  • an optional string of spaces;
  • an optional minus sign;
  • a string of digits and an optional decimal point (the digits can be on both sides of the decimal point);
  • an optional exponent followed by a (optionally signed) integer.
It is important to say that this implementation of atof requires that an optional minus sign and an optional exponent must be TI Basic characters for minus sign and exponent, (characters with codes 0xAD and 0x95 instead of ordinary '-' and 'e' or 'E' characters). This limitation is caused by using some TIOS calls which needs such number format. Anyway, it is very easy to "preprocess" any string to satisfy this convention before calling to atof by routine like the following (assuming that c is a char variable, and i is an integer variable):
for (i = 0; (c = s[i]); i++)
 // Yes, the second '=' is really '=', not '=='...
  {
    if (c == '-') s[i] = 0xAD;
    if ((c|32) == 'e') s[i] = 0x95;
  }
atof returns the converted value of the input string. It returns NAN if the input string cannot be converted (i.e. if it is not in a correct format). This is not the same as in ANSI C: atof in ANSI C returns 0 if the conversion was not successful. I decided to return NAN instead, so the user can check whether the conversion was successful (which is not possible with ANSI atof). See is_nan for a good method to check whether the result is NAN.

Note: This function is not part of TIOS, and it is implemented using the TIOS function push_parse_text.
Note: You should use strtod instead of atof, since it will take up less space in your program, and provide a more direct and finer error-checking.

Uses: ER_catch, ER_success, estack_number_to_Float, push_parse_text, top_estack

See also: strtod


cacos

cacos Function (ROM Call 0x13A)
math.h, timath.h

void cacos (float z_re, float z_im, float *w_re, float *w_im);

Complex arc cosine.

cacos calculates the arc cosine w = acos(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex arc cosine is defined by

acos(z) = -i ln (z + i sqrt (1 - z^2))

where ln and sqrt are complex natural logarithm and complex square root (see cln and csqrt).

Uses: acos, fabs, is_inf, is_nan, pow, sqrt, _bcd_math
Used by: cacosh


cacosh

cacosh Function (ROM Call 0x13D)
math.h, timath.h

void cacosh (float z_re, float z_im, float *w_re, float *w_im);

Complex hyperbolic area cosine.

cacosh calculates the hyperbolic area cosine w = acosh(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex hyperbolic area cosine is defined by

acosh(z) = ln (z + sqrt (z^2 - 1))

where ln and sqrt are complex natural logarithm and complex square root (see cln and csqrt).

Uses: cacos, fabs, _bcd_math


casin

casin Function (ROM Call 0x13B)
math.h, timath.h

void casin (float z_re, float z_im, float *w_re, float *w_im);

Complex arc sine.

casin calculates the arc sine w = asin(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex arc sine is defined by

asin(z) = -i ln (i z + sqrt (1 - z^2))

where ln and sqrt are complex natural logarithm and complex square root (see cln and csqrt).

Uses: asin, fabs, is_inf, is_nan, pow, sqrt, _bcd_math
Used by: casinh


casinh

casinh Function (ROM Call 0x13E)
math.h, timath.h

void casinh (float z_re, float z_im, float *w_re, float *w_im);

Complex hyperbolic area sine.

casinh calculates the hyperbolic area sine w = asinh(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex hyperbolic area sine is defined by

asinh(z) = ln (z + sqrt (z^2 + 1))

where ln and sqrt are complex natural logarithm and complex square root (see cln and csqrt).

Uses: casin, _bcd_math


catan

catan Function (ROM Call 0x13C)
math.h, timath.h

void catan (float z_re, float z_im, float *w_re, float *w_im);

Complex arc tangent.

catan calculates the arc tangent w = atan(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex arc tangent is defined by

atan(z) = -i ln ((1 + i z) / (1 - i z)) / 2

where ln is complex natural logarithm (see cln).

Uses: atan2, atanh, fabs, pow, _bcd_math
Used by: catanh


catanh

catanh Function (ROM Call 0x13F)
math.h, timath.h

void catanh (float z_re, float z_im, float *w_re, float *w_im);

Complex hyperbolic area tangent.

catanh calculates the hyperbolic area tangent w = atanh(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex hyperbolic area tangent is defined by

atanh(z) = ln ((1 + z) / (1 - z)) / 2

where ln is complex natural logarithm (see cln).

Uses: catan, _bcd_math


ccos

ccos Function (ROM Call 0x140)
math.h, timath.h

void ccos (float z_re, float z_im, float *w_re, float *w_im);

Complex cosine.

ccos calculates the cosine w = cos(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex cosine is defined by

cos(z) = (exp(i z) + exp(-i z)) / 2

where exp is complex exponential function (see cexp).

Uses: cos, cosh, sin, sinh, _bcd_math
Used by: ccosh, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cos, push_cosh, push_exp, push_ln, push_log10, push_sin, push_sinh, push_sqrt, push_tanh


ccosh

ccosh Function (ROM Call 0x143)
math.h, timath.h

void ccosh (float z_re, float z_im, float *w_re, float *w_im);

Complex hyperbolic cosine.

ccosh calculates the hyperbolic cosine w = cosh(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex hyperbolic cosine is defined by

cosh(z) = (exp(z) + exp(-z)) / 2

where exp is complex exponential function (see cexp).

Uses: ccos, _bcd_math
Used by: push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cos, push_cosh, push_exp, push_ln, push_log10, push_sin, push_sinh, push_sqrt, push_tanh


ceil

ceil Function (ROM Call 0x105*)
math.h, timath.h

float ceil (float x);

Rounds up the floating point number.

ceil finds the smallest integer not less than floating point argument x, and returns the integer found as a floating point value.

Uses: fpisanint, is_transfinite, _bcd_math
Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_twovar, GrAxes


cexp

cexp Function (ROM Call 0x149)
math.h, timath.h

void cexp (float z_re, float z_im, float *w_re, float *w_im);

Complex exponential function.

cexp calculates the complex exponential function w = exp(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex exponential function is defined by

exp(z) = exp(z_re) (cos(z_im) + i sin(z_im))

See exp, sin and cos.

Uses: cos, exp, sin, _bcd_math
Used by: push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cos, push_cosh, push_exp, push_ln, push_log10, push_sin, push_sinh, push_sqrt, push_tanh, push_exponentiate


cln

cln Function (ROM Call 0x147)
math.h, timath.h

void cln (float z_re, float z_im, float *w_re, float *w_im);

Complex natural logarithm (base e).

cln calculates the natural logarithm w = ln(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex logarithm is defined by

ln(z) = log(abs(z)) + i arg(z)

where abs(z) = sqrt(z_re^2+z_im^2), arg(z) = atan2(z_im, z_re) and log is the real natural logarithm. See also sqrt and atan2.

Uses: atan2, fabs, is_inf, is_nan, log, _bcd_math
Used by: clog10, push_exponentiate


clog10

clog10 Function (ROM Call 0x148)
math.h, timath.h

void clog10 (float z_re, float z_im, float *w_re, float *w_im);

Complex logarithm, base 10.

clog10 calculates the base 10 logarithm w = log10(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The base 10 complex logarithm is defined by

log10(z) = ln(z) / ln(10)

where ln is complex natural logarithm (see cln).

Uses: cln, _bcd_math


cos

cos Function (ROM Call 0xF9*)
math.h, timath.h

float cos (float x);

Floating point cosine.

cos returns the cosine of floating point argument x, which is assumed to be specified in radians.

Note: cos will return NAN if the argument is so big that reducing to the main period can't be performed without complete losing of significant digits (i.e. when the magnitude of x is greater than 1e13).

Uses: trig
Used by: ccos, cexp, csin, ctan, cmd_sinreg


cosh

cosh Function (ROM Call 0xFC*)
math.h, timath.h

float cosh (float x);

Floating point hyperbolic cosine.

sinh returns the hyperbolic cosine of floating point argument x. Hyperbolic cosine is defined as (exp(x)+exp(-x))/2.

Note: cosh will return POSITIVE_INF in a case of overflow.

Uses: is_nan, is_transfinite, _bcd_math
Used by: ccos, csin, ctan, push_cosh


csin

csin Function (ROM Call 0x141)
math.h, timath.h

void csin (float z_re, float z_im, float *w_re, float *w_im);

Complex sine.

csin calculates the sine w = sin(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex sine is defined by

sin(z) = (exp(i z) - exp(-i z)) / (2 i)

where exp is complex exponential function (see cexp).

Uses: cos, cosh, sin, sinh, _bcd_math
Used by: csinh, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cos, push_cosh, push_exp, push_ln, push_log10, push_sin, push_sinh, push_sqrt, push_tanh


csinh

csinh Function (ROM Call 0x144)
math.h, timath.h

void csinh (float z_re, float z_im, float *w_re, float *w_im);

Complex hyperbolic sine.

csinh calculates the hyperbolic sine w = sinh(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex hyperbolic sine is defined by

sinh(z) = (exp(z) - exp(-z)) / 2

where exp is complex exponential function (see cexp).

Uses: csin, _bcd_math
Used by: push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cos, push_cosh, push_exp, push_ln, push_log10, push_sin, push_sinh, push_sqrt, push_tanh


csqrt

csqrt Function (ROM Call 0x146)
math.h, timath.h

void csqrt (float z_re, float z_im, float *w_re, float *w_im);

Complex square root.

csqrt calculates the square root w = sqrt(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex square root is defined by

sqrt(z) = sqrt(abs(z)) (cos(arg(z)/2) + i sin(arg(z)/2))

where abs(z) = sqrt(z_re^2+z_im^2) and arg(z) = atan2(z_im, z_re). See sqrt, atan2, sin and cos.

Uses: _bcd_math
Used by: push_sqrt


ctan

ctan Function (ROM Call 0x142)
math.h, timath.h

void ctan (float z_re, float z_im, float *w_re, float *w_im);

Complex tangent.

ctan calculates the tangent w = tan(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex tangent is defined by

tan(z) = sin(z) / cos(z)

where sin and cos are complex sine and complex cosine (see csin and ccos).

Uses: cos, cosh, fabs, sin, sinh, _bcd_math
Used by: ctanh, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cos, push_cosh, push_exp, push_ln, push_log10, push_sin, push_sinh, push_sqrt, push_tanh


ctanh

ctanh Function (ROM Call 0x145)
math.h, timath.h

void ctanh (float z_re, float z_im, float *w_re, float *w_im);

Complex hyperbolic tangent.

ctanh calculates the hyperbolic tangent w = tanh(z) of the complex number which real and imaginary parts are z_re and z_im, and stores real and imaginary part of the result in floating point destinations pointed to by w_re and w_im. The complex hyperbolic tangent is defined by

tanh(z) = sinh(z) / cosh(z)

where sinh and cosh are complex hyperbolic sine and complex hyperbolic cosine (see csinh and ccosh).

Uses: ctan, _bcd_math
Used by: push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cos, push_cosh, push_exp, push_ln, push_log10, push_sin, push_sinh, push_sqrt, push_tanh


exp

exp Function (ROM Call 0xFF*)
math.h, timath.h

float exp (float x);

Floating point exponential function.

exp returns the exponential function of floating point argument x (i.e. calculates e to the x-th power).

Note: exp will return POSITIVE_INF in a case of overflow, and zero (unsigned, see ZERO; strange, I expected POSITIVE_ZERO) in a case of underflow.

Used by: cexp, push_exp


fabs

fabs Function (ROM Call 0x106*)
math.h, stdlib.h, timath.h

float fabs (float x);

Absolute value of a floating point number.

fabs returns the absolute value of floating point argument x.

Uses: is_uzero, _bcd_math
Used by: acosh, asinh, atanh, cacos, cacosh, casin, catan, cln, ctan, cmd_blddata, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_send, cmd_sinreg, cmd_twovar, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_cos, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_remainder, push_lim, push_ln, push_log10, push_max, push_min, push_mod, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_rand, push_re, push_sin, push_sin2, push_sinh, push_solve, push_sqrt, push_summation, push_tan, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, did_push_cnvrt_Float_to_integer, gcd_exact_whole_Floats, is_Float_exact_whole_number, norm1_complex_Float, EV_defaultHandler, add_to_top, are_units_consistent, compare_numbers, de_initRes, de_loop, de_rng_no_graph, did_push_approx_inflection_point, EV_quit, get_ub, GM_Intersect, GM_Math1, GR_Pan, GrAxes, GrClipLine, GZ_Stat, index_if_pushed_qquad_info, InitDEAxesRng, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, push_trig, raise_to_top, replace_top_with_post_simplified, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x48C, ROM Call 0x48D, ROM Call 0x494, ROM Call 0x495, DateAndTime_Get

See also: abs, labs


floor

floor Function (ROM Call 0x107*)
math.h, timath.h

float floor (float x);

Rounds down the floating point number.

floor finds the largest integer not greater than floating point argument x, and returns the integer found as a floating point value.

Uses: fpisanint, is_transfinite, _bcd_math
Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_twovar, did_push_anti_deriv, push_extended_prod, push_factor, push_floor, push_mod, push_sequence, push_sin2, push_summation, push_tan, push_exponentiate, StepCk, CptLastIndepDE, FirstSeqPlot, gr_CptIndepInc, gr_execute_seq, gr_xres_pixel, GT_Trace, GZ_Integer, seqStepCk


fmod

fmod Function (ROM Call 0x108*)
math.h, timath.h

float fmod (float x, float y);

Calculates x modulo y, i.e. the remainder of x/y.

fmod returns x modulo y, i.e. it returns the remainder f, where x = a * y + f for some integer a and 0 <= f < y. Where y = 0, fmod returns 0.

Uses: is_nan, is_transfinite, _bcd_math
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_fractional_part, push_lim, push_max, push_min, push_nsolve, push_sin2, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, did_push_cnvrt_Float_to_integer, gcd_exact_whole_Floats, is_Float_exact_whole_number, EV_defaultHandler, GR3_paint3d, EV_quit, get_ub, GR3_handleEvent, is_whole_number, replace_top_with_post_simplified, DateAndTime_SetDlg, DateAndTime_Set, DateAndTime_Get, DayOfTheWeek, TimeStr


frexp10

frexp10 Function (ROM Call 0x2FB*)
AMS 1.01 or higher math.h, timath.h

float frexp10 (float x, short *exponent);

Splits floating point number into mantissa and exponent.

frexp10 calculates the mantissa m (a floating point greater than or equal to 0.1 and less than 1) and the integer value n, such that x equals m*10^n. frexp stores n in the integer that exponent points to, and returns the mantissa m.

Note: This routine is analogous to frexp in ANSI C math library, except using base ten rather than base two.

Uses: is_transfinite, _bcd_math


hypot

hypot Function (Macro)
math.h, timath.h

float hypot (float x, float y);

Calculates hypotenuse of right triangle.

hypot returns the value z where z^2 = x^2 + y^2 and z >= 0. This is equivalent to the length of the hypotenuse of a right triangle, if the lengths of the two sides are x and y. Or, this is also equivalent to the absolute value of the complex number x + y i.

Note: hypot is implemented as macro which calls fmul (for squaring x and y), fadd and sqrt.

Uses: fadd, fmul, sqrt


is_inf

is_inf Function (ROM Call 0x2FF)
AMS 1.01 or higher math.h, timath.h

short is_inf (float x);

Checks whether the argument is an infinite number.

is_inf returns TRUE if x is an infinite number (i.e. UNSIGNED_INF, POSITIVE_INF or NEGATIVE_INF), else returns FALSE. Infinite values are produced when the result is unbounded (for example dividing by zero), or in case of overflow. This function is an alias for TIOS function originally called is_float_infinity.

Uses: _bcd_math
Used by: cacos, casin, cln, is_transfinite, itrig, did_push_anti_deriv, push_1st_derivative, push_abs, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_to_cylin, get_ub


is_nan

is_nan Function (ROM Call 0x306)
AMS 1.01 or higher math.h, timath.h

short is_nan (float x);

Checks whether the argument is Not_a_Number.

is_nan returns TRUE if x is NAN (Not_a_Number), else returns FALSE. Not_a_Number is a special value which is produced as a result of all operations when the result is undefined or non-real, for example dividing zero with zero, calculating the logarithm of a negative number, etc.

Uses: _bcd_math
Used by: cacos, casin, cln, cosh, float_class, fmod, is_transfinite, itrig, sinh, tanh, did_push_anti_deriv, push_1st_derivative, push_abs, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_to_cylin, push_Float, did_push_approx_inflection_point, get_ub, GM_Intersect, GM_Math1, GT_Trace, Regraph, replace_top_with_post_simplified


is_nzero

is_nzero Function (ROM Call 0x300)
AMS 1.01 or higher math.h, timath.h

short is_nzero (float x);

Checks whether the argument is negative zero.

is_nzero returns TRUE if x is a negative zero (i.e. infinitely small negative quantity, see NEGATIVE_ZERO), else returns FALSE. This function is an alias for TIOS function originally called is_float_negative_zero.


is_pzero

is_pzero Function (ROM Call 0x301)
AMS 1.01 or higher math.h, timath.h

short is_pzero (float x);

Checks whether the argument is positive zero.

is_pzero returns TRUE if x is a positive zero (i.e. infinitely small positive quantity, see POSITIVE_ZERO), else returns FALSE. This function is an alias for TIOS function originally called is_float_positive_zero.

Used by: push_sign


is_sinf

is_sinf Function (ROM Call 0x302)
AMS 1.01 or higher math.h, timath.h

short is_sinf (float x);

Checks whether the argument is signed infinity.

is_sinf returns TRUE if x is a signed infinity (i.e. POSITIVE_INF or NEGATIVE_INF), else returns FALSE. This function is an alias for TIOS function originally called is_float_signed_infinity.

Uses: _bcd_math
Used by: atan2, itrig


is_transfinite

is_transfinite Function (ROM Call 0x303)
AMS 1.01 or higher math.h, timath.h

short is_transfinite (float x);

Checks whether the argument is a transfinite number.

is_transfinite returns TRUE if x is a transfinite number, else returns FALSE. Transfinite numbers are all infinite numbers (UNSIGNED_INF, POSITIVE_INF and NEGATIVE_INF) and NAN. This function is an alias for TIOS function originally called is_float_transfinite.

Uses: is_inf, is_nan
Used by: acosh, asinh, atan2, atanh, ceil, cosh, floor, fmod, frexp10, itrig, sinh, tanh, trig, cmd_blddata, cmd_circle, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_linetan, cmd_randseed, cmd_shade, cmd_showstat, cmd_sinreg, cmd_slpline, push_rand, push_randmat, push_randnorm, push_randpoly, push_Float, GR3_paint3d, GR3_xyToWindow, sprintf, de_loop, dv_create_graph_titles, FuncLineFlt, GM_Derivative, GM_Integrate, GM_Shade, GM_TanLine, gr_execute_de, gr_execute_seq, GR3_addContours, GR3_handleEvent, GrLineFlt, GT_DspTraceCoords, GT_Trace, GZ_Fit, Regraph, VarRecall


is_uinf_or_nan

is_uinf_or_nan Function (ROM Call 0x304)
AMS 1.01 or higher math.h, timath.h

short is_uinf_or_nan (float x);

Checks whether the argument is unsigned infinity or Not_a_Number.

is_uinf_or_nan returns TRUE if x is UNSIGNED_INF or NAN, else returns FALSE. These two special numbers are treated very similarly in TIOS. This function is an alias for TIOS function originally called is_float_unsigned_inf_or_nan.

Uses: _bcd_math
Used by: atan2, itrig, push_sign


is_uzero

is_uzero Function (ROM Call 0x305)
AMS 1.01 or higher math.h, timath.h

short is_uzero (float x);

Checks whether the argument is unsigned zero.

is_uzero returns TRUE if x is an unsigned zero (i.e. infinitely small quantity with indeterminate sign, see UNSIGNED_ZERO), else returns FALSE. This function is an alias for TIOS function originally called is_float_unsigned_zero.

Used by: fabs, push_sign


labs

labs Function (Builtin)
math.h, stdlib.h, timath.h

long labs (long x);

Absolute value of a long integer number.

labs returns the absolute value of (long) integer argument x.

Note: labs is a built-in function in the GCC compiler itself, and it compiles to open code instead of a function call.

See also: abs, fabs


ldexp10

ldexp10 Function (Macro)
math.h, timath.h

float ldexp10 (float x, short exponent);

Calculates x times 10 raised to exponent.

ldexp10 calculates x times 10 raised to exponent, and returns the result, i.e. returns x*10^exponent. Strictly speaking, ldexp10 is a macro, not a function.

Note: This routine is analogous to ldexp in ANSI C math library, except using base ten rather than base two.


log

log Function (ROM Call 0x100*)
math.h, timath.h

float log (float x);

Floating point natural logarithm (base e).

log returns the natural logarithm of floating point argument x.

Note: log will return NEGATIVE_INF if the argument is zero, or NAN if the argument is negative.

Uses: ER_throwVar, _bcd_math
Used by: cln, did_push_anti_deriv, push_1st_derivative, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_exp, push_lim, push_ln, push_max, push_min, push_nsolve, push_randnorm, push_sinh, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


log10

log10 Function (ROM Call 0x101*)
math.h, timath.h

float log10 (float x);

Floating point logarithm, base 10.

log10 returns the base 10 logarithm of floating point argument x.

Note: log will return NEGATIVE_INF if the argument is zero, or NAN if the argument is negative.

Uses: ER_throwVar, _bcd_math
Used by: push_log10


modf

modf Function (ROM Call 0x102*)
math.h, timath.h

float modf (float x, float *ipart);

Splits floating point value into integer and fraction part.

modf breaks the floating point value x into two parts: the integer and the fraction, both having the same sign as x. It stores the integer in a floating point destination pointed to by ipart and returns the fractional part of x.

Uses: _bcd_math
Used by: did_push_anti_deriv, push_perm


pow

pow Function (ROM Call 0x103*)
math.h, timath.h

float pow (float x, float y);

Floating point power function.

pow returns x^y, x to the y (i.e. x raised to the y-th power).

Note: pow will return an infinite result (see POSITIVE_INF, NEGATIVE_INF, UNSIGNED_INF) in a case of overflow. If both x and y are zeros, pow will return 1. If x is negative, the correct result will be produced only if y can be represented as a whole number, or as a fraction with odd denominator; otherwise, pow will return a garbage (not NAN) which sometimes even not satisfy the floating point BCD format (digits greater than 9 etc.), so be careful in a case when x is negative!

Uses: _bcd_math
Used by: cacos, casin, catan, push_pow, de_loop


sin

sin Function (ROM Call 0xFA*)
math.h, timath.h

float sin (float x);

Floating point sine.

sin returns the sine of floating point argument x, which is assumed to be specified in radians.

Note: sin will return NAN if the argument is so big that reducing to the main period can't be performed without complete losing of significant digits (i.e. when the magnitude of x is greater than 1e13).

Uses: trig
Used by: ccos, cexp, csin, ctan, cmd_sinreg, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_sin2, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


sinh

sinh Function (ROM Call 0xFD*)
math.h, timath.h

float sinh (float x);

Floating point hyperbolic sine.

sinh returns the hyperbolic sine of floating point argument x. Hyperbolic sine is defined as (exp(x)-exp(-x))/2.

Note: sinh will return POSITIVE_INF or NEGATIVE_INF in a case of overflow.

Uses: is_nan, is_transfinite, _bcd_math
Used by: ccos, csin, ctan, push_sinh


sqrt

sqrt Function (ROM Call 0x104*)
math.h, timath.h

float sqrt (float x);

Floating point square root.

sqrt returns the positive square root of floating point argument x.

Note: If the argument is negative, there will be no error, but the result will be invalid.

Used by: acosh, asinh, atanh, cacos, casin, hypot, itrig, cmd_blddata, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_sinreg, cmd_twovar, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_randnorm, push_re, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, GD_Circle, add_to_top, are_units_consistent, get_ub, GM_DistArc, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_float_qr_fact, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, ROM Call 0x494, ROM Call 0x495


tan

tan Function (ROM Call 0xFB*)
math.h, timath.h

float tan (float x);

Floating point tangent.

tan returns the tangent of floating point argument x, which is assumed to be specified in radians.

Note: tan will return UNSIGNED_INF for all arguments for which the tangent is infinity. Also, it will return NAN if the argument is so big that reducing to the main period can't be performed without complete losing of significant digits (i.e. when the magnitude of x is greater than 1e13).

Uses: trig
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


tanh

tanh Function (ROM Call 0xFE*)
math.h, timath.h

float tanh (float x);

Floating point hyperbolic tangent.

sinh returns the hyperbolic cosine of floating point argument x. Hyperbolic tangent is defined as sinh(x)/cosh(x).

Uses: is_nan, is_transfinite, _bcd_math
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_tanh, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, get_ub


HALF_PI

HALF_PI Constant
math.h, timath.h

#define HALF_PI (1.570796326794897)

A constant with value PI/2.

HALF_PI is a predefined floating point constant which approximates PI/2 up to 16 significant digits, i.e. 1.570796326794897. Of course, it is the same as PI/2.0.


NAN

NAN Constant (Pseudo-constant)
math.h, timath.h

A constant defining an undefined value.

NAN is an acronyme of "Not a Number". TIOS generates NAN when nothing can be deduced about the magnitude of the result (for example, when dividing zero by zero, or when substracting two infinities of the same sign). Also, TIOS generates NAN when the argument of a function is out of legal range, excluding values of the argument which produces infinity results. For example, log will produce NAN when the argument is negative, but when the argument is zero, the result is NEGATIVE_INF.

NAN also belongs to the class of "transfinite" numbers (see is_transfinite). Use is_nan to check whether a value is NAN. This is a common method to check in run time whether the arguments of the called math functions was legal.

See also: UNSIGNED_INF


NEGATIVE_INF

NEGATIVE_INF Constant (Pseudo-constant)
math.h, timath.h

Represents an infinitely large negative quantity.

NEGATIVE_INF represents an infinitely large negative quantity. TIOS generates NEGATIVE_INF when the result is infinite in magnitude, but when it is known to be negative (for example, log returns NEGATIVE_INF when the argument is equal to zero). Other properties of NEGATIVE_INF are analogous like properties of POSITIVE_INF.

See also: POSITIVE_INF, UNSIGNED_INF, NEGATIVE_ZERO, is_transfinite


NEGATIVE_ZERO

NEGATIVE_ZERO Constant (Pseudo-constant)
math.h, timath.h

Represents an infinitely small quantity which is known to be always non-positive.

NEGATIVE_ZERO is similar to POSITIVE_ZERO, but it represents an infinitely small quantity which is known to be always non-positive. The properties of NEGATIVE_ZERO are analog to the properties of POSITIVE_ZERO. To check whether a value is a negative zero, use is_nzero.


PI

PI Constant
math.h, timath.h

#define PI (3.141592653589793)

An approximated value of pi.

PI is a predefined floating point constant which approximates pi up to 16 significant digits, i.e. 3.141592653589793.


POSITIVE_INF

POSITIVE_INF Constant (Pseudo-constant)
math.h, timath.h

Represents an infinitely large positive quantity.

POSITIVE_INF represents an infinitely large positive quantity. TIOS generates POSITIVE_INF when the result is infinite in magnitude, but when it is known to be positive (for example, atanh returns POSITIVE_INF when the argument is equal to 1). TIOS also generates POSITIVE_INF as the result of positive overflow (i.e. when the result is positive and too big to be represented in float type), and as the result of rounding extremely big positive numbers using round14 or round12_err.

TIOS allows much greater flexibility when working with "signed" infinities than with UNSIGNED_INF. To check whether a value is signed infinity, use is_sinf. POSITIVE_INF belongs to the class of "transfinite" numbers (see is_transfinite).

See also: NEGATIVE_INF, UNSIGNED_INF, POSITIVE_ZERO, is_transfinite


POSITIVE_ZERO

POSITIVE_ZERO Constant (Pseudo-constant)
math.h, timath.h

Represents an infinitely small quantity which is known to be always non-negative.

In opposite to UNSIGNED_ZERO, POSITIVE_ZERO is an infinitely small quantity which is known to be always non-negative. It can be imagined as "the smallest positive real number", altough something like this does not exist in reality. TIOS generates POSITIVE_ZERO in cases when the result is zero, but it is known that the result cannot be negative for any argument. For example, squaring of ZERO using pow function will return POSITIVE_ZERO, because the square is always non-negative. The same is true for acosh when the argument is equal to 1, etc.

TIOS also generates POSITIVE_ZERO as the result of positive underflow (i.e. when the result is positive, but too small to be represented in a float type), and as the result of rounding extremely small positive numbers using round14 or round12_err. To check whether a value is a positive zero, use is_pzero.

Dividing any finite strictly positive number by POSITIVE_INF will produce POSITIVE_ZERO as the result. Dividing any finite strictly positive number by POSITIVE_ZERO gives POSITIVE_INF, and dividing any finite strictly negative number by POSITIVE_ZERO gives NEGATIVE_INF.

Note: Try in TI Basic '1/0' and '1/0^2' to see that '0' and '0^2' are not strictly the same for TIOS. Clever, isn't it?


UNSIGNED_INF

UNSIGNED_INF Constant (Pseudo-constant)
math.h, timath.h

Represents an infinite quantity.

UNSIGNED_INF represents a quantity which is known to be infinite in magnitude, but when nothing can be deduced about its sign. For example, dividing of non-zero number with "standard" zero (i.e. with UNSIGNED_ZERO) or calculating tangent of pi/2 will produce such value. TIOS mathematical functions are much more limited in working with unsigned than with signed infinities (like POSITIVE_INF). For example, arc tangent of POSITIVE_INF is well defined and equals to pi/2, but arc tangent of UNSIGNED_INF is not unique determined.

Although UNSIGNED_INF is a much more "concrete" quantity than NAN, TIOS very often does not make any difference between these two quantities. To check whether a value is an unsigned infinity or NAN, use is_uinf_or_nan. If it is, then you can use is_nan for checking whether a value is NAN, and if it it not, it must be an unsigned infinity. UNSIGNED_INF belongs to the class of "transfinite" numbers (see is_transfinite).

See also: POSITIVE_INF, NEGATIVE_INF, NAN, is_transfinite


UNSIGNED_ZERO

UNSIGNED_ZERO Constant (Pseudo-constant)
math.h, timath.h

#define UNSIGNED_ZERO (0.)

Represents an infinitely small quantity with indeterminate sign.

TIOS makes a difference between three types of zeros. UNSIGNED_ZERO is "ordinary" zero, i.e. infinitely small quantity with indeterminate sign. It is identical to ZERO. Dividing any finite non-zero number by UNSIGNED_ZERO will produce UNSIGNED_INF.

All kind of zeros are equal when comparing using comparison operators or fcmp. To check whether a value is an unsigned zero, use is_uzero.


ZERO

ZERO Constant (Pseudo-constant)
math.h, timath.h

#define ZERO (0.)

A deprecated constant.

ZERO is a predefined floating point constant with value 0.0. ZERO is the same as UNSIGNED_ZERO.


mem.h

mem.h Header File
Header File Index

Routines for manipulation of memory blocks

Functions
_memset
Sets num bytes of buffer to byte c.
memchr
Searches the first len bytes of array str for character c.
memcmp
Compares two blocks of signed chars.
memcpy
Copies a block of len bytes from src to dest.
memmove
Copies a block of len bytes from src to dest, with possibility of overlaping of source and destination block.
memset
Sets num bytes of buffer to byte c.
memucmp
Compares two blocks of unsigned chars.
Constants
NULL
A null-pointer value.
Predefined Types
size_t
A type to define sizes of strings and memory blocks.

See also: alloc.h


_memset

_memset Function (ROM Call 0x27B)
mem.h, string.h

void *_memset (void *buffer, short c, unsigned long num);

Sets num bytes of buffer to byte c.

_memset is a slower (byte-by-byte) variant of memset.

Used by: ReleaseDate


memchr

memchr Function (ROM Call 0x273)
mem.h, string.h

void *memchr (const void *str, short c, unsigned long len);

Searches the first len bytes of array str for character c.

memchr searches the first len bytes of the block pointed to by str for character c. On success, memchr returns a pointer to the first occurrence of c in str. Otherwise, it returns NULL.


memcmp

memcmp Function (ROM Call 0x270)
mem.h, string.h

short memcmp (const void *s1, const void *s2, unsigned long len);

Compares two blocks of signed chars.

memcmp compares the first len bytes of the blocks s1 and s2 as signed chars. Since it compares bytes as signed chars, memcmp returns a value

  • < 0 if s1 is less than s2
  • =0 if s1 is the same as s2
  • > 0 if s1 is greater than s2
For example, memcmp("\xFF","\x7F",1) returns a value greater than 0. More precisely, the exact return value is the result of subtracting the first pair of values that differ in the two blocks being compared based on them being signed chars.

Note: This routine is declared as "short" although the ANSI standard proposes "long". This is important, because the TIOS memcmp routine puts garbage in the higher half of the d0 register.

Used by: LoadDLL, are_expressions_identical, EV_defaultHandler, ScrRectScroll, GraphOrTableCmd, ScrRectDivide

See also: memucmp


memcpy

memcpy Function (ROM Call 0x26A)
mem.h, string.h

void *memcpy (void *dest, const void *src, unsigned long len);

Copies a block of len bytes from src to dest.

memcpy copies a block of len bytes from src to dest. If src and dest overlap, the memcpy is ill-behaved (in such case, use memmove instead). memcpy returns dest.

Used by: HeapWalk, GetFloatArg, cmd_blddata, cmd_get, cmd_newdata, cmd_randseed, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_determinant, push_lim, push_max, push_min, push_nsolve, push_rand, push_randmat, push_randnorm, push_randpoly, push_red_row_ech, push_round, push_row_echelon, push_simult, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, DialogAdd, push_between, EV_defaultHandler, GR3_paint3d, GR3_xyToWindow, BitmapPut, LCD_restore, LCD_save, RestoreScrState, SaveScrState, ScrRectScroll, gdb_recall, gdb_store, HomeExecute, HomePushEStack, HS_popEStack, LIO_Receive, DynMenuAdd, DynMenuChange, MenuLoad, cdecrypt, MD5Update, AB_prodname, CB_replaceTEXT, de_initRes, de_loop, execute_graph_func, get_ub, GR3_addContours, GR3_handleEvent, hStrAppend, InitDEMem, InitTimeSeq, LIO_SendIdList, PlotDel, PlotDup, PlotGet, PlotPut, push_sq_matrix_to_whole_number, push_var, ReallocExprStruct, Regraph, run_one_seq, seqWebInit, SP_Define, spike_geo_titles, spike_in_editor, spike_optionD, store_data_var, tokenize_if_TI_92_or_text, TokenizeName, EM_moveSymFromExtMem, EM_moveSymToExtMem, EM_twinSymFromExtMem, EX_stoBCD, SYMSTR, VarRecall, VarStore, WinOpen, ROM Call 0x420, ROM Call 0x438, ROM Call 0x478


memmove

memmove Function (ROM Call 0x26B)
mem.h, string.h

void *memmove (void *dest, const void *src, unsigned long len);

Copies a block of len bytes from src to dest, with possibility of overlaping of source and destination block.

memmove copies a block of len bytes from src to dest. Even when the source and destination blocks overlap, bytes in the overlapping locations are copied correctly (in opposite to memcpy). memmove returns dest.

Used by: HeapCompress, HeapGetHandle, HeapMoveHigh, HeapRealloc, HeapShuffle, cmd_blddata, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_string, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, DialogAdd, delete_between, GR3_paint3d, ScrRectShift, DynMenuAdd, DynMenuChange, AB_serno, TE_handleEvent, TE_pasteText, convert_to_TI_92, delete_list_element, get_ub, OO_SetAttr, spike_geo_titles, spike_in_editor, spike_optionD, UpdateWindows, AddSymToFolder, FolderAdd, FolderDel, FolderRename, HSymDel, SymAddTwin, SymDel, SymDelTwin, VarStore, ROM Call 0x439


memset

memset Function (ROM Call 0x27C)
mem.h, string.h

void *memset (void *buffer, short c, unsigned long num);

Sets num bytes of buffer to byte c.

memset sets the first num bytes of the array buffer to the character c. memset is faster than _memset, because it sets a memory in a 4-byte chunks as long as possible. memset returns buffer.

Used by: calloc, HeapGetHandle, cmd_cyclepic, cmd_dialog, cmd_newdata, cmd_newplot, cmd_request, Dialog, DialogAdd, DialogNew, VarNew, VarSaveAs, EV_defaultHandler, handleRclKey, handleVarLinkKey, MO_modeDialog, FOpen, ClrScr, HS_newFIFONode, LIO_Receive, DynMenuAdd, MenuBegin, MenuKey, MenuNew, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, PopupBegin, PopupClear, PopupNew, EV_quit, GM_Shade, GR_Pan, GT_Trace, GZ_SetFactors, Regraph, SP_Define, spike_in_editor, spike_titles_in_editor, EM_moveSymToExtMem, WinClr, WinOpen, WinReOpen, ROM Call 0x3E8, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x40C, ROM Call 0x45B, ROM Call 0x486, DateAndTime_SetDlg, DateStr, TimeStr


memucmp

memucmp Function (ROM Call 0x3CC)
AMS 2.00 or higher mem.h, string.h

short memucmp (const void *s1, const void *s1, unsigned long len);

Compares two blocks of unsigned chars.

memucmp acts like memcmp, but treats s1 and s2 as pointers to unsigned chars.

Used by: ROM Call 0x168

See also: memcmp


menus.h

menus.h Header File
Header File Index

Routines for creating popup and toolbar menus

Functions
DynMenuAdd
Adds a new entry to a dynamic menu.
DynMenuChange
Changes an entry in a dynamic menu.
FKeyI_H
Returns the corresponding menu item for a function key.
MenuAddIcon
Adds a new icon item in a toolbar menu.
MenuAddText
Adds a new text item in a toolbar menu.
MenuBegin
Displays a toolbar menu and creates a new structure which is used for executing the menu.
MenuCheck
Checks/unchecks or returns the state of an item in a pulldown menu.
MenuEnd
Deallocates an executable menu structure and removes the menu from the screen.
MenuFlags
Return the flag word for a dynamic menu/popup structure.
MenuGetTopRedef
Gets the index of a toolbox icon.
MenuItemDef
Returns a pointer to the data of a menu item.
MenuKey
Activates a toolbar menu by processing a key press.
MenuLoad
Begins a dynamically created menu using a prefilled static menu as the starting point.
MenuNew
Creates a new toolbar menu.
MenuOff
Disables a toolbar menu.
MenuOn
Redraws a toolbar menu.
MenuPopup
Executes a popup menu given a pointer to a popup menu structure.
MenuSubStat
Changes the state (enabled/disabled) of an item in a pulldown menu.
MenuTopRedef
Redefines a toolbox icon.
MenuTopSelect
Emphasizes a toolbox.
MenuTopStat
Changes the state (enabled/disabled) of a toolbox.
MenuUpdate
Draws the default home screen menu.
PopupAddText
Adds a new text item in a popup menu.
PopupBegin
Creates a new popup menu with checkmarks features.
PopupBeginDo
Executes a dynamically allocated popup using a menu-draw handle.
PopupClear
Clears a popup or toolbar menu structure.
PopupDo
Executes a popup menu.
PopupNew
Creates a new popup menu.
PopupText
Returns a pointer to the text of a popup menu item.
QMenuTopSelect
Returns the currently selected top-level menu item.
VarCreateFolderPopup
Creates a popup menu containing a list of all folders.
Constants
CENTER
A constant to describe a centered position for dialogs.
H_NULL
A null-handle value.
NULL
A null-pointer value.
Predefined Types
BITMAP
A structure for defining a bitmap.
Bool
An enumeration to describe true or false values.
CommonKeys
An enumeration for describing common key codes.
DynMenuFlags
An enumeration for describing possible flags associated to dynamic menu entries.
HANDLE
Represents a handle associated with an allocated memory block.
ICON
A structure which describes an icon.
ItemTypes
An enumeration for describing item types in menus.
MenuBeginFlags
An enumeration for describing possible flags passed to MenuBegin.
MenuCheckCmds
An enumeration for describing possible commands for the MenuCheck function.
MenuFlagsEnum
An enumeration for describing possible flags contained in a dynamic menu.
MenuKeyValues
Contains predefined return values of MenuKey.
pICON
A pointer to the ICON scructure.
VCFPFlags
Describes possible flags for VarCreateFolderPopup.


DynMenuAdd

DynMenuAdd Function (ROM Call 0x3F1)
AMS 2.00 or higher menus.h

HANDLE DynMenuAdd (HANDLE Handle, short ParentID, const void *Data, short ID, unsigned short Flags);

Adds a new entry to a dynamic menu.

DynMenuAdd adds a new entry to the dynamic toolbar menu associated with the handle Handle, which must be a handle created by MenuNew or MenuLoad. The entry added first will be the first option in the menu, the entry added second will be the second option, and so on. Each new entry (pointed by Data) can either be a text, an ICON structure, or a BITMAP structure, depending on the parameter Flags.

This function is similar to MenuAddText and MenuAddIcon, except that it is available only in AMS 2.00 and later (i.e. you have to set MIN_AMS in GCC4TI to 200 or higher). This function also offers a new feature: the use of bitmaps in menus. In fact, TI says that MenuAddText and MenuAddIcon are just older ways to do the same things, so DynMenuAdd can fully replace those functions if you plan to run your program only on AMS 2.00 or later.

ID is the identification number of the item. It is used to identify the item in many other functions; for example it will later be returned by the MenuKey function if the user selects this menu item. You may also be able to change this new entry using the ID number and the function DynMenuChange. Moreover, this value can be used by a child entry to identify its parent. If ID equals 0, the TIOS will generate the ID automatically (1 for the first menu entry, 2 for the second entry, etc.). The legal range for ID is 1 to 4095. If ID is greater than 4095, it will be truncated (ANDed with 0x0FFF).

Note: If you are adding to a prefilled static menu (i.e. written in your source code and loaded using MenuLoad), do not use the range 0x0F00 to 0x0FFF (i.e. do not use an ID greater than 3839).

DynMenuAdd returns H_NULL in case of an error, otherwise it returns Handle. An error occurs if the system runs out of memory, or if there is an error in the parameters (ParentID not found, ParentID found but it was not a possible parent, or maximum number of items in a menu exceeded). If there is an error adding the new entry, the MF_ERROR flag in the menu structure is set (you can use MenuFlags to get this flag, but do not confuse menu structure flags such as MF_ERROR and the parameter Flags in MenuAddText which gives the type of entry). DynMenuAdd may cause heap compression.

The parameter ParentID must be set to 0 if this is a new top-level entry (i.e. if this entry has no parent), or to the ID of the parent entry if this entry is a child (i.e. this is an item in a pulldown menu). Note that if this entry is at top level, ParentID can also be set to -1, which means it has no child. (For some reason, this seems to be the only way to prevent any other entry to be a child of this one, as the DMF_TOP flag still allows child entries.)

The Flags parameter, defined in the enum DynMenuFlags, must contain one of the flags described in the first following table, bitwise ORed with one of the flags described in the second table:

DMF_TEXT | The parameter Data points to a text string.
DMF_ICON | The parameter Data points to an ICON structure.
DMF_BITMAP | The parameter Data points to a BITMAP structure.

DMF_TOP | New top-level entry that cannot be a parent. Note that this flag does not seem to prevent any other entry to be a child of this one (i.e. when this flag is set in an entry, that entry can still be a parent). To prevent this, please set -1 for the ParentID parameter as well as setting this flag.
DMF_TOP_SUB | New top-level entry that can have children.
DMF_CHILD | Child entry whose parent is the one specified by the parameter ParentID. This child entry cannot be the parent of another entry (i.e. no submenu available for this entry). Note: The parent specified by ParentID should have the DMF_TOP_SUB or the DMF_CHILD_SUB flag set.
DMF_CHILD_SUB | Child entry whose parent is the one specified by the parameter ParentID. This child entry can be the parent of another entry (i.e. submenus are available for this entry). With this option, you can create many sublevels of nesting. Note: The parent specified by ParentID should have the DMF_TOP_SUB or the DMF_CHILD_SUB flag set.

If you forget to give a DMF_TEXT, DMF_ICON or DMF_BITMAP flag, DynMenuAdd will automatically consider Data to point to a text string.

Here is an example for this function (called "Menu Example 2"):

// A simple menu example, with several submenus

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

#define RETURN_VALUE          // Return a Value
#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 200           // Compile for AMS 2.00 or higher

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

// Main Function
void _main(void)
{
  HANDLE menu_handle = MenuNew (2, 240, 18);
  DynMenuAdd (menu_handle, 0, "First", 1, DMF_TEXT | DMF_TOP_SUB);
  DynMenuAdd (menu_handle, 1, "Subitem 1.1", 5, DMF_TEXT | DMF_CHILD_SUB);
  DynMenuAdd (menu_handle, 5, "Subitem 1.1.1", 8, DMF_TEXT | DMF_CHILD_SUB);
  DynMenuAdd (menu_handle, 5, "Subitem 1.1.2", 9, DMF_TEXT | DMF_CHILD);
  DynMenuAdd (menu_handle, 8, "Subitem 1.1.1.1", 10, DMF_TEXT | DMF_CHILD);
  DynMenuAdd (menu_handle, 1, "Subitem 1.2", 6, DMF_TEXT | DMF_CHILD);
  DynMenuAdd (menu_handle, 0, "Second", 2, DMF_TEXT | DMF_TOP_SUB);
  DynMenuAdd (menu_handle, 2, "Subitem 2.1", 7, DMF_TEXT | DMF_CHILD);
  DynMenuAdd (menu_handle, -1, "Third", 3, DMF_TEXT | DMF_TOP);
  DynMenuAdd (menu_handle, -1, "Fourth", 4, DMF_TEXT | DMF_TOP);
  HANDLE exec_handle = MenuBegin (NULL, 0, 0, MBF_HMENU, menu_handle);
  short result;
  do {
    result = MenuKey (exec_handle, ngetchx ());
  } while (result == M_NOTMENUKEY);
  MenuEnd (exec_handle);
  MenuUpdate ();
  push_shortint (result);
}

Uses: HeapRealloc, CalcBitmapSize, memcpy, memmove, memset, strlen, strncpy
Used by: MenuAddIcon, MenuAddText, PopupAddText, EV_defaultHandler, EV_quit

See also: MenuNew, MenuLoad, DynMenuChange


DynMenuChange

DynMenuChange Function (ROM Call 0x3F0)
AMS 2.00 or higher menus.h

HANDLE DynMenuChange (HANDLE Handle, short ID, const void *NewData, unsigned short Flags);

Changes an entry in a dynamic menu.

DynMenuChange replaces an entry created with DynMenuAdd, MenuAddText, or MenuAddIcon in the dynamic toolbar menu associated with the handle Handle with a new entry (pointed to by NewData). Handle must be a handle created by MenuNew or MenuLoad. The new entry pointed by NewData can either be a text, an ICON structure, or a BITMAP structure, depending on the parameter Flags. ID is the identification number of the existing item you wish to change.

DynMenuChange returns H_NULL in case of an error, otherwise it returns Handle. An error occurs if the system runs out of memory or if there is an error in the parameters. If there is an error replacing the entry, the MF_ERROR flag in the menu structure is set (you can use MenuFlags to get this flag, but do not confuse menu structure flags such as MF_ERROR with the parameter Flags in DynMenuChange which gives the type of entry). DynMenuChange may cause heap compression.

The Flags parameter, defined in the enum DynMenuFlags, contains one of the flags given in the following array:

DMF_TEXT | The parameter NewData points to a text string.
DMF_ICON | The parameter NewData points to an ICON structure.
DMF_BITMAP | The parameter NewData points to a BITMAP structure.

Uses: HeapRealloc, CalcBitmapSize, memcpy, memmove, strlen, strncpy, ROM Call 0x41E

See also: MenuNew, MenuLoad, DynMenuAdd


FKeyI_H

FKeyI_H Function (ROM Call 0x592)
AMS 2.02 or higher menus.h

short FKeyI_H (HANDLE ExecHandle, short Key);

Returns the corresponding menu item for a function key.

FKeyI_H returns the corresponding index to the function key given in Key of the menu associated with the ExecHandle handle, or returns M_NOTMENUKEY for function keys not used in the given menu. The ExecHandle handle should have been returned from MenuBegin.

Key should be a function key (i.e. KEY_Fx) given in the enum CommonKeys. KEY_F1 will return 0 for the first top-level entry if it exists, KEY_F2 will return 1 for the second top-level entry if it exists, and so on.

FKeyI_H can be useful in combination with MenuKey.

Uses: HeapDeref
Used by: MenuKey, cmd_toolbar, ROM Call 0x421

See also: MenuBegin, MenuKey


MenuAddIcon

MenuAddIcon Function (ROM Call 0x42)
menus.h

HANDLE MenuAddIcon (HANDLE Handle, short ParentID, const void *Icon, short ID, short Flags);

Adds a new icon item in a toolbar menu.

MenuAddIcon is very similar to MenuAddText, except instead of a text, the added menu item will consist of an icon. The icon is a 16x16 bitmap structure given as a 16-word group of bits, and parameter Icon is the pointer to it. This pointer is usually of type pICON (pointer to the ICON structure). All other parameters are explained in the MenuAddText function.

Note: It seems that it is possible to add items with icons instead of text to popup menus, too (not only to toolbar menus).

Uses: DynMenuAdd
Used by: cmd_custom, cmd_toolbar

See also: MenuNew, MenuLoad, DynMenuAdd, DynMenuChange, MenuAddText


MenuAddText

MenuAddText Function (ROM Call 0x41)
menus.h

HANDLE MenuAddText (HANDLE Handle, short ParentID, const char *Text, short ID, short Flags);

Adds a new text item in a toolbar menu.

MenuAddText adds the text Text to the toolbar menu associated with the handle Handle. The text added first will be the first option in the menu, the text added second will be the second option, and so on.

ID is the identification number of the item. It is used to identify the item in many other functions; for example it will later be returned by the MenuKey function if the user selects this menu entry. Moreover, this value can be used by a child entry to identify its parent. If ID equals 0, the TIOS will generate the ID automatically (1 for the first menu entry, 2 for the second entry, etc.). The legal range for ID is 1 to 4095. If ID is greater than 4095, it will be truncated (ANDed with 0x0FFF).

Note: If you are adding to a prefilled static menu (i.e. written in your source code and loaded using MenuLoad), do not use the range 0x0F00 to 0x0FFF (i.e. do not use an ID greater than 3839).

The parameter ParentID must be set to 0 if this is a new top-level entry (i.e. if this entry has no parent), or to the ID of the parent entry if this entry is a child (i.e. this is an item in a pulldown menu). Note that if this entry is at top level, ParentID can also be set to -1, which means it has no child. (For some reason, this seems to be the only way to prevent any other entry to be a child of this one; as the DMF_TOP flag still allows child entries.)

MenuAddText returns H_NULL in case of an error, otherwise it returns Handle. If there is an error adding the new entry, the MF_ERROR flag in the menu structure is set (you can use MenuFlags to get this flag, but do not confuse menu structure flags such as MF_ERROR and the parameter Flags in MenuAddText which gives the type of entry). MenuAddText may cause heap compression.

Although the TIOS menu system allows for toolbar menus with associated pulldown menus which have their own submenus (i.e. more than one level of nesting), it is not possible to create such menus in AMS 1.xx using this command. If you really want more levels of nesting and need to stay compatible, you need to use pre-filled static structures and pass them directly to the MenuBegin function (see MenuPopup for more info). But, note that this is somewhat complicated.

The Flags parameter contains one of the following flags, defined in the enum DynMenuFlags:

DMF_TOP | New top-level entry that cannot be a parent. Note that this flag does not seem to prevent any other entry to be a child of this one (i.e. when this flag is set in an entry, that entry can still be a parent). To prevent this, please set -1 for the ParentID parameter as well as setting this flag.
DMF_TOP_SUB | New top-level entry that can have children.
DMF_CHILD | Child entry whose parent is the one specified by the parameter ParentID. This child entry cannot be the parent of another entry (i.e. no submenu available for this entry). Note: The parent specified by ParentID should have the DMF_TOP_SUB or the DMF_CHILD_SUB flag set.
DMF_CHILD_SUB | AMS 2.00 or higher: Child entry whose parent is the one specified by the parameter ParentID. This child entry can be the parent of another entry (i.e. submenus are available for this entry). With this option, you can create many sublevels of nesting. Note: The parent specified by ParentID should have the DMF_TOP_SUB or the DMF_CHILD_SUB flag set.

Here is an example for this function (called "Menu Example 1"):

// A simple menu example, with several submenus

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

#define RETURN_VALUE          // Return a Value
#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 200           // Compile for AMS 2.00 or higher

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

// Main Function
void _main(void)
{
  HANDLE menu_handle = MenuNew (2, 240, 18);
  MenuAddText (menu_handle, 0, "First", 1, DMF_TOP_SUB);
  MenuAddText (menu_handle, 1, "Subitem 1.1", 5, DMF_CHILD_SUB);
  MenuAddText (menu_handle, 5, "Subitem 1.1.1", 8, DMF_CHILD_SUB);
  MenuAddText (menu_handle, 5, "Subitem 1.1.2", 9, DMF_CHILD);
  MenuAddText (menu_handle, 8, "Subitem 1.1.1.1", 10, DMF_CHILD);
  MenuAddText (menu_handle, 1, "Subitem 1.2", 6, DMF_CHILD);
  MenuAddText (menu_handle, 0, "Second", 2, DMF_TOP_SUB);
  MenuAddText (menu_handle, 2, "Subitem 2.1", 7, DMF_CHILD);
  MenuAddText (menu_handle, -1, "Third", 3, DMF_TOP);
  MenuAddText (menu_handle, -1, "Fourth", 4, DMF_TOP);
  HANDLE exec_handle = MenuBegin (NULL, 0, 0, MBF_HMENU, menu_handle);
  short result;
  do {
    result = MenuKey (exec_handle, ngetchx ());
  } while (result == M_NOTMENUKEY);
  MenuEnd (exec_handle);
  MenuUpdate ();
  push_shortint (result);
}

Uses: DynMenuAdd
Used by: cmd_custom, cmd_toolbar, MO_modeDialog, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x486

See also: MenuNew, MenuLoad, DynMenuAdd, DynMenuChange, MenuAddIcon


MenuBegin

MenuBegin Function (ROM Call 0x36)
menus.h

HANDLE MenuBegin (const void *MenuPtr, short x, short y, unsigned short Flags, ...);

Displays a toolbar menu and creates a new structure which is used for executing the menu.

MenuBegin shows the toolbar menu pointed to by MenuPtr on the screen. The top-left corner of the menu will be at the position (x, y); the coordinates are absolute screen coordinates. x, y, or both may also have the special value CENTER, which tells MenuBegin to center the menu in a particular dimension.

Note that this function does not use a handle if called in a normal fashion. Instead, it needs a pointer to the actual menu structure. So you must use HLock to lock and dereference the handle before using this function (locking is highly recommended because heap compression may occur):

exec_handle = MenuBegin (HLock (handle), x, y, Flags);
A second way which is almost equal to the one above but only works on AMS 2.00 or higher is to pass NULL to MenuPtr and MBF_HMENU to Flags. Then the optional parameter after Flags will take the handle instead:
exec_handle = MenuBegin (NULL, x, y, Flags | MBF_HMENU, handle);
But note that in this case, the handle will be freed when MenuEnd is called.

Alternatively (but only if you are an expert), you can pass a pointer to a pre-filled static menu structure to MenuPtr (like the TIOS usually does). Using this approach you can save a lot of memory. See MenuPopup for more info about this.

MenuBegin does not activate the menu. Instead, it creates yet another structure which is necessary to execute the menu, and returns the handle to it (or H_NULL in case of an error, i.e. if there was not enough memory to allocate the new structure). To activate the menu, you must call MenuKey with this handle.

The Flags parameter contains a combination of the following flags, defined in the enum MenuBeginFlags:

MBF_WITHICON | Reserve extra space in memory in order to display menus with icons.
MBF_REDEF | Allow for the top-level items (special text/icon combination) to be redefined with the MenuTopRedef function. Note: The only way to create redefinable menu items is to use a pre-filled menu structure.
MBF_SYS_ALLOC | Unknown for the moment (do not use).
MBF_MAX_MENU_WIDTH | AMS 2.00 or higher: The parameter after Flags should be a short integer representing the maximum field width to use for the menu (by default it is the screen width). This maximum field width is only used if the menu width is calculated automatically (i.e. the width was set to 0). If you wish to use both MAX_MENU_WIDTH and MBF_HMENU at the same time, see below.
MBF_STRIKEOUT | AMS 2.00 or higher: Use strikeout (line drawn through text or icon fields) instead of grayed items to indicate disabled menu items.
MBF_HMENU | AMS 2.00 or higher: The parameter after Flags should be the handle of a dynamically created menu. If this flag is used, the parameter MenuPtr is ignored and should be set to NULL. The handle is locked and dereferenced and used instead of MenuPtr. The handle is saved internally, and calling MenuEnd on the handle returned by MenuBegin will free this handle. If you wish to use both MAX_MENU_WIDTH and MBF_HMENU at the same time, see below.
MBF_NO_DRAWTOP | AMS 2.00 or higher: Set up the menu-draw structure and return a handle to it, but do not draw the menu. You have to call MenuOn to draw it.

If both MAX_MENU_WIDTH and MBF_HMENU are set, the first parameter after Flags represents the maximum menu width, and the second parameter after Flags represents the handle to a dynamic menu.

This routine may cause heap compression.

Uses: MenuOn, HeapAlloc, HeapLock, CalcBitmapSize, DrawStrWidth, memset, ROM Call 0x41E
Used by: cmd_toolbar, EV_defaultHandler, handleVarLinkKey, CustomBegin


MenuCheck

MenuCheck Function (ROM Call 0x37)
menus.h

short MenuCheck (HANDLE ExecHandle, short ID, unsigned short Cmd);

Checks/unchecks or returns the state of an item in a pulldown menu.

MenuCheck checks/unchecks or returns the state of the check mark of the pulldown submenu item identified by ID (see MenuAddText for more details about item IDs). ExecHandle is a handle returned from the MenuBegin function, not from MenuNew.

If Cmd is set to MC_STATUS, MenuCheck returns the status of the check mark (zero: not checked, nonzero: checked). Otherwise it returns TRUE on success (i.e. item was found) and FALSE on failure.

The Cmd parameter must be one of the following values, defined in the enum MenuCheckCmds:

MC_CHECK | Display a check mark next to the menu item.
MC_UNCHECK | AMS 2.00 or higher: Remove the check mark.
MC_STATUS | Return the status of the check mark (zero: not checked, nonzero: checked).
MC_FLIP | Invert the status of the check mark.

Uses: ROM Call 0x422
Used by: EV_setCmdCheck

See also: MenuBegin


MenuEnd

MenuEnd Function (ROM Call 0x38)
menus.h

void MenuEnd (HANDLE ExecHandle);

Deallocates an executable menu structure and removes the menu from the screen.

MenuEnd deletes the structure needed for executing the toolbar menu (such a structure is created using MenuBegin), and removes the menu from the screen by filling the menu area with blank pixels (except if the MBF_NO_DRAWTOP flag was passed to MenuBegin). Note that it never restores the background which was present before the menu was drawn; you must do this manually. If the menu was drawn at the top of the screen (as usually), calling MenuUpdate may help. Also note that MenuEnd does not remove the structure created using MenuNew unless you used the MBF_HMENU flag; you must call HeapFree to remove it.

Uses: HeapFree, ScrRect, ScrRectFill
Used by: cmd_toolbar, Dialog, EV_defaultHandler, handleVarLinkKey, CustomEnd

See also: MenuBegin, MenuKey


MenuFlags

MenuFlags Function (ROM Call 0x3F4)
AMS 2.00 or higher menus.h

short MenuFlags (HANDLE Handle);

Return the flag word for a dynamic menu/popup structure.

MenuFlags returns the flags stored in a dynamic menu structure (see MenuPopup for more information on menu structures). For the moment, the only useful flag bit is MF_ERROR, which is cleared when the menu structure is created and set if adding or changing a menu entry causes a memory error. All menu flags are described in the enum MenuFlagsEnum.

See also: MenuBegin, MenuKey


MenuGetTopRedef

MenuGetTopRedef Function (ROM Call 0x40)
menus.h

short MenuGetTopRedef (HANDLE ExecHandle, short Item);

Gets the index of a toolbox icon.

MenuGetTopRedef returns the ID of the child item whose icon is used by the top-level parent Item as a redefinition icon which belongs to the menu associated with the handle ExecHandle. See MenuTopRedef for more info.

See also: MenuBegin, MenuTopRedef, MenuTopSelect


MenuItemDef

MenuItemDef Function (ROM Call 0x3F3)
AMS 2.00 or higher menus.h

void *MenuItemDef (HANDLE ExecHandle, short ID, unsigned short *Type);

Returns a pointer to the data of a menu item.

Given a menu item ID, MenuItemDef returns a pointer to the text, ICON, or BITMAP defining it (or NULL if ID was not found in the menu identified by ExecHandle) and returns its type in Type. ExecHandle is a handle returned from MenuBegin.

The value returned in Type can be one of the following types (or 0 if not found), as defined in the enum DynMenuFlags:

DMF_TEXT | The pointer returned points to a text string.
DMF_ICON | The pointer returned points to an ICON structure.
DMF_BITMAP | The pointer returned points to a BITMAP structure.

Uses: ROM Call 0x41E, ROM Call 0x422

See also: MenuBegin, DynMenuAdd, DynMenuChange


MenuKey

MenuKey Function (ROM Call 0x39)
menus.h

short MenuKey (HANDLE ExecHandle, short KeyCode);

Activates a toolbar menu by processing a key press.

MenuKey is the heart of all toolbar menus. It activates the menu associated with the handle ExecHandle, where ExecHandle is a handle returned from MenuBegin (not from MenuNew). The parameter KeyCode is the code of the key associated with the menu item (toolbox) which will be activated. If this toolbox has a pulldown menu assigned to it (DMF_TOP_SUB), it will be opened, and the user can navigate through the menu using the arrow keys. If the toolbox has no pulldown menu, MenuKey returns immediately. A typical method of calling MenuKey is to pass a result of the ngetchx function (which waits for a keypress and returns the key code) to the parameter KeyCode:

result = MenuKey (exec_handle, ngetchx ());
MenuKey returns the following values (as far as I know; maybe other return values also exist):
  • M_NOITEM, if the user pressed ESC while the menu was active, or if the code of a disabled toolbox (see MenuTopStat) was passed to MenuKey;
  • M_NOTMENUKEY, if a wrong key code was passed to it (i.e. a key code which is not associated with any menu item);
  • a positive value, if the user selects a menu item normally. In this case, the return value will be the identification number (ID) of the selected menu item (see MenuAddText).
Note that this approach is very flexible, because the actual reading of the keypress is done in the user program, so it allows various ways of "hooking" into the "heart" of the menu. Most importantly, the user program can decide which keys belong to the menu.

This routine may cause heap compression.

Here is an example of defining a menu and using MenuKey to activate it (called "Menu Example 1"):
// A simple menu example, with several submenus

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

#define RETURN_VALUE          // Return a Value
#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 200           // Compile for AMS 2.00 or higher

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

// Main Function
void _main(void)
{
  HANDLE menu_handle = MenuNew (2, 240, 18);
  MenuAddText (menu_handle, 0, "First", 1, DMF_TOP_SUB);
  MenuAddText (menu_handle, 1, "Subitem 1.1", 5, DMF_CHILD_SUB);
  MenuAddText (menu_handle, 5, "Subitem 1.1.1", 8, DMF_CHILD_SUB);
  MenuAddText (menu_handle, 5, "Subitem 1.1.2", 9, DMF_CHILD);
  MenuAddText (menu_handle, 8, "Subitem 1.1.1.1", 10, DMF_CHILD);
  MenuAddText (menu_handle, 1, "Subitem 1.2", 6, DMF_CHILD);
  MenuAddText (menu_handle, 0, "Second", 2, DMF_TOP_SUB);
  MenuAddText (menu_handle, 2, "Subitem 2.1", 7, DMF_CHILD);
  MenuAddText (menu_handle, -1, "Third", 3, DMF_TOP);
  MenuAddText (menu_handle, -1, "Fourth", 4, DMF_TOP);
  HANDLE exec_handle = MenuBegin (NULL, 0, 0, MBF_HMENU, menu_handle);
  short result;
  do {
    result = MenuKey (exec_handle, ngetchx ());
  } while (result == M_NOTMENUKEY);
  MenuEnd (exec_handle);
  MenuUpdate ();
  push_shortint (result);
}

Uses: FKeyI_H, HeapAllocESTACK, HeapFree, BitmapGet, BitmapPut, BitmapSize, CalcBitmapSize, DrawChar, DrawClipRect, DrawFkey, DrawLine, DrawMultiLines, DrawPix, DrawStr, DrawStrWidth, FontSetSys, PortRestore, RestoreScrState, SaveScrState, ScrRect, ScrRectFill, ScrToWin, SetCurAttr, SetCurClip, alphaLockOff, alphaLockOn, GKeyIn, restoreAlphaLock, memset, ST_eraseHelp, ST_helpMsg, strlen, CU_cursorState, CU_restore, CU_stop, XR_stringPtr, CTypeTable, ROM Call 0x3EA, ROM Call 0x41E, ROM Call 0x420, ROM Call 0x422
Used by: cmd_toolbar, EV_defaultHandler, handleVarLinkKey

See also: MenuBegin


MenuLoad

MenuLoad Function (ROM Call 0x3F2)
AMS 2.00 or higher menus.h

HANDLE MenuLoad (const void *BaseMenu, unsigned short Size);

Begins a dynamically created menu using a prefilled static menu as the starting point.

MenuLoad creates a dynamic menu, using the prefilled static menu structure BaseMenu with the size Size (in bytes) as the starting point. It copies the menu's items, flags, width, and height from the static structure. MenuLoad returns the handle of the new dynamically created menu which may be used in DynMenuAdd or DynMenuChange and then passed to MenuBegin to draw the menu, or returns H_NULL if there was not enough memory.

Note: Please see MenuPopup for more informations on menu structures, and take a look at the proposed method to execute menus as described in MenuNew.

Uses: HeapAlloc, memcpy

See also: MenuBegin, MenuNew, DynMenuAdd, DynMenuChange


MenuNew

MenuNew Function (ROM Call 0x43)
menus.h

HANDLE MenuNew (short Flags, short Width, short Height);

Creates a new toolbar menu.

MenuNew allocates memory for a new toolbar menu (i.e. a menu which looks like the main menu of the home screen), initializes the allocated block with the necessary structures, and returns a handle to it (or H_NULL in case of an error). You can later free the memory by calling HeapFree, but note that this is done automatically if you use the MBF_HMENU flag when calling the MenuBegin function. Width and Height are the width and the height of the menu in pixels. Passing 0 means that the width or height should be calculated automatically; however, AMS 1.xx simply uses the default values in this case. Values which are too large are converted to the largest possible values; for the height this is a value of 18. If the cumulated width of the items in the menu is greater than the available width of the menu, the menu items will scroll left or right if necessary.

This routine may cause heap compression.

The parameter Flags contains various flags defined in the enum MenuFlagsEnum. TI recommends passing 0, but the TIOS mainly passes MF_TOOLBOX when calling this routine. This parameter is copied to the Flags field of the menu structure (see MenuPopup for info about this structure).

The method for creating menus on AMS 2.00 or later which TI proposes is as follows:

  1. Create an empty, dynamic menu structure with MenuNew or MenuLoad.
  2. Build the menu with DynMenuAdd or DynMenuChange using the handle returned by MenuNew or MenuLoad (each of these routines returns H_NULL if not enough memory, or check MenuFlags when done with all of the additions/changes).
  3. Call MenuBegin setting the MBF_HMENU flag and passing the handle returned by MenuNew or MenuLoad as the argument after the Flags parameter (MenuBegin has a variable number of arguments). NULL can be passed as the pointer to the menu structure (since the dereferenced handle points to this structure). (If interested, see MenuPopup for more informations on menu structures.) This will lock the handle returned from MenuNew and save it.
  4. Using the handle returned from MenuBegin (this is a separate handle!), you may then call all of the normal menu functions (MenuCheck, MenuKey, MenuOn, MenuTopStat, MenuTopSelect, etc.).
  5. When done with the menu, call MenuEnd on the handle returned from MenuBegin. This will free the handle returned from MenuBegin as well as the handle returned from MenuNew.
Do not forget that once you call MenuBegin, you may not unlock the handle returned from MenuNew, nor call DynMenuAdd or DynMenuChange.

It might also be useful for you to have the following information:

 | TI-89 | TI-92
Maximum menu width (in pixels) | 160 | 240
Top-level font (as defined in the Fonts enum) | F_4x6 | F_6x8
Sub-level font (as defined in the Fonts enum) | F_6x8 | F_6x8

Uses: HeapAlloc, memset
Used by: cmd_custom, cmd_toolbar

See also: MenuBegin, MenuKey, MenuLoad, DynMenuAdd, DynMenuChange, MenuAddText, MenuAddIcon


MenuOff

MenuOff Function (ROM Call 0x419)
AMS 2.00 or higher menus.h

void MenuOff (HANDLE ExecHandle);

Disables a toolbar menu.

MenuOff grays-out (i.e. disables) the top-level menu defined by ExecHandle (a handle returned from MenuBegin). To re-enable it, call MenuOn.

Uses: CalcBitmapSize, DrawChar, DrawClipRect, DrawFkey, DrawLine, DrawMultiLines, DrawPix, DrawStr, DrawStrWidth, FontSetSys, PortRestore, RestoreScrState, SaveScrState, ScrRect, ScrRectFill, ScrToWin, SetCurAttr, SetCurClip, memset, ST_eraseHelp, CU_cursorState, CU_restore, CU_stop, ROM Call 0x41E, ROM Call 0x420

See also: MenuBegin, MenuOn


MenuOn

MenuOn Function (ROM Call 0x3A)
menus.h

void MenuOn (HANDLE ExecHandle);

Redraws a toolbar menu.

MenuOn redraws the menu associated with the handle ExecHandle, where ExecHandle is a handle returned from the MenuBegin function. This may be useful after executing functions like MenuTopSelect, or after calling MenuOff. Note that items that were disabled with MenuTopStat remain disabled and therefore shaded.

Uses: CalcBitmapSize, DrawChar, DrawClipRect, DrawFkey, DrawLine, DrawMultiLines, DrawPix, DrawStr, DrawStrWidth, FontSetSys, PortRestore, RestoreScrState, SaveScrState, ScrRect, ScrRectFill, ScrToWin, SetCurAttr, SetCurClip, memset, ST_eraseHelp, CU_cursorState, CU_restore, CU_stop, ROM Call 0x41E, ROM Call 0x420
Used by: MenuBegin, MenuUpdate, Dialog, EV_setFKeyState, handleVarLinkKey

See also: MenuBegin, MenuOff, MenuTopStat


MenuPopup

MenuPopup Function (ROM Call 0x3B)
menus.h

unsigned short MenuPopup (const void *MenuPtr, short x, short y, unsigned short start_option);

Executes a popup menu given a pointer to a popup menu structure.

MenuPopup works exactly like PopupDo, except instead of the handle, a pointer to the menu structure is given as the parameter. PopupDo internally calls HeapDeref, then passes the returned pointer to this function. This function is mainly used internally in the TIOS. Its advantage in comparison with PopupDo is the fact that the complete popup menu structure may be given as a static pre-filled array of bytes, and you can pass the pointer to such a structure to the MenuPopup function. This will save a lot of memory, because you do not need to call PopupNew and a lot of functions like PopupAddText. Moreover, MenuPopup allows executing menus with more than one level of submenus even in AMS 1.xx, which is not possible otherwise. But note that the menu structure is a quite complicated variable-shape structure, so if you do not know exactly what you are doing, avoid this function! As the menu structure has a variable length and shape, it cannot be strictly described as a C language type, but it will be described here using non-formal C-like syntax. Note that toolbar menus use the same structure:

packed struct MENU
  {
    unsigned short DisplayOffset;  // Contains offset to Display[0] from here
    unsigned short Flags;          // Various flags: see text below
    unsigned short TotalItems;     // Total number of items
    unsigned char Width;           // Menu width, 0 for popup menus
    unsigned char Height;          // Menu height
    unsigned short MainItems;      // Number of main items only
    unsigned short DynSize;        // Dynamic size (see text below)
    unsigned short RedefOffset;    // Offset to RedefIcons, 0 if RedefItems = 0
    unsigned short RedefItems;     // Number of redefinable icons
    long separator = -1;

    MENU_ENTRY main_entries [];    // for each main item
    long separator = -1;

    struct
      {
        MENU_ENTRY sub_entries []; // for each submenu item
        long separator = -1;
      } cascade [];                // for each submenu

    packed union
      {
        ICON Icon;          // Used in toolbars with icons instead of text
        char Text [];       // Text, zero terminated
      } Display [];         // for each menu item

    struct
      {
        unsigned short ID;  // ID number
        ICON Icon;          // Corresponding icon description
      } RedefIcons [];      // for each redefinable icon (if any)
  };
The Flags field contains various flags defined in the enum MenuFlagsEnum. The DynSize field for dynamically created menus (i.e. menus created with PopupNew) contains the total length of the MENU structure in bytes (this info is needed for the heap manager). For statically allocated menus, you can put zero in this field. Also, each element of the array Display should be aligned on a word boundary. This is not strictly necessary for text items, but it is necessary for icon items.

Each menu item is described using a variable-length (4 or 6 bytes) structure called MENU_ENTRY, which is described as:
struct MENU_ENTRY
  {
    unsigned short ID;                // Item type (see below) ORed with
                                      //   ID number for this item
    unsigned short Offset;            // Offset of icon/text (from Display[0])
                                      //   or XR_string, depending of item type
    packed union                      // If the item is cascaded (i.e if it has
      {                               //   a submenu), we have an extra offset
        unsigned short CascadeOffset; // Offset from the begining of menu
      } extras;                       //   structure to the begining of the
  };                                  //   description of the cascaded submenu
Possible item types are MT_TEXT (0x8000), MT_XREF (0x9000), and MT_ICON (0xA000). They may optionally be ORed with MT_CASCADE (0x4000) to signalize that the item is cascaded (i.e. that the item has a submenu). All these constants are defined in the enum ItemTypes. The CascadeOffset field exists only if ID & MT_CASCADE is non-zero (i.e. if bit b14 in ID is set). If the Offset field for an item of icon type is not defined, this is an item with redefinable icons (for example, the toolbar menu item in the Geometry application uses such menu items).

Note that the topmost (b15) bit of the ID field is always set, and the topmost bit of the Offset field is always 0. This is necessary because MENU_ENTRY is a variable length structure (4 or 6 bytes), depending on whether a cascade is defined. To correctly move up and down through menu items, the TIOS uses the following strategy: on pressing down, if MT_CASCADE is set, move down 6 bytes, otherwise move down 4 bytes. On pressing up, move back 4 bytes, then check bit b15. If it is 0, this is an Offset field, so move back another 2 bytes.

All of this will become clearer with a concrete example. A variable-sized variable-shape structure like MENU cannot be defined using standard C initializers, but it may be defined with the help of the built-in assembler. This example (called "Static Popup") defines exactly the same menu as the example given with PopupDo, but saves about 200 bytes:
// Display a predefined popup menu

#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

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

extern void menu;
asm ("menu:\n"
"        .word  title_text - menu\n"
"        .word  0xD5\n"
"        .word  9\n"
"        .byte  0, 40\n"
"        .word  5\n"
"        .word  0\n"
"        .word  0\n"
"        .word  0\n"
"        .long  -1\n"
"      main_entries:\n"
"        .word  MT_TEXT + 1                   /* | is a comment character, */\n"
"        .word  option_1_text - title_text    /* so use + instead */\n"
"        .word  MT_TEXT + 2\n"
"        .word  option_2_text - title_text\n"
"        .word  MT_TEXT + MT_CASCADE + 3\n"
"        .word  submenu_3_text - title_text\n"
"        .word  submenu_3_cascade - menu\n"
"        .word  MT_TEXT + MT_CASCADE + 4\n"
"        .word  submenu_4_text - title_text\n"
"        .word  submenu_4_cascade - menu\n"
"        .word  MT_TEXT + 5\n"
"        .word  option_5_text - title_text\n"
"        .long  -1\n"
"      submenu_3_cascade:\n"
"        .word  MT_TEXT + 6\n"
"        .word  suboption_3_1_text - title_text\n"
"        .word  MT_TEXT + 7\n"
"        .word  suboption_3_2_text - title_text\n"
"        .word  MT_TEXT + 8\n"
"        .word  suboption_3_3_text - title_text\n"
"        .long  -1\n"
"      submenu_4_cascade:\n"
"        .word  MT_TEXT + 9\n"
"        .word  suboption_4_1_text - title_text\n"
"        .long  -1\n"
"      title_text:\n"
"        .asciz \"EXAMPLE\"\n"
"      option_1_text:\n"
"        .asciz \"Option 1\"\n"
"      option_2_text:\n"
"        .asciz \"Option 2\"\n"
"      submenu_3_text:\n"
"        .asciz \"Submenu 3\"\n"
"      submenu_4_text:\n"
"        .asciz \"Submenu 4\"\n"
"      option_5_text:\n"
"        .asciz \"Option 5\"\n"
"      suboption_3_1_text:\n"
"        .asciz \"Suboption 3.1\"\n"
"      suboption_3_2_text:\n"
"        .asciz \"Suboption 3.2\"\n"
"      suboption_3_3_text:\n"
"        .asciz \"Suboption 3.3\"\n"
"      suboption_4_1_text:\n"
"        .asciz \"Suboption 4.1\"\n");

void _main(void)
{
  MenuPopup (&menu, CENTER, CENTER, 0);
}
There is an alternative method as well. Note that the field DynSize (the tenth and eleventh byte starting from zero) of the MENU structure contains the total length of the structure for dynamically created menus. So you can make a menu using commands like PopupNew, PopupAddText, etc., and then to use VTI and its debugger to pick up bytes from the menu structure knowing the length of it. After this, you may pass a pointer to the pre-filled sequence of bytes picked from VTI to this function. I used this approach in the following (cryptic) example which is functionally equivalent to the example given above:
static long menu[] = {0x4800D5, 0x90028, 0x500BA, 0, -1, 0x80010008,
  0x80020012, 0xC003001C, 0x30C004, 0X260040, 0X80050030, -1, 0x8006003A,
  0x80070048, 0x80080056, -1, 0X80090064, -1, 0x4558414D, 0x504C4500,
  0x4F707469, 0x6F6E2031, 0x4F4F70, 0x74696F6E, 0x20320053, 0x5375626D,
  0x656E7520, 0x33005375, 0x626D656E, 0x75203400, 0x4F707469, 0x6F6E2035,
  0x535375, 0x626F7074, 0x696F6E20, 0x332E3100, 0x5375626F, 0x7074696F,
  0x6E20332E, 0x32005375, 0x626F7074, 0x696F6E20, 0x332E3300, 0x5375626F,
  0x7074696F, 0x6E20342E, 0x31000000};
MenuPopup (&menu, CENTER, CENTER, 0);

Uses: ROM Call 0x421
Used by: PopupDo, Dialog

See also: PopupDo


MenuSubStat

MenuSubStat Function (ROM Call 0x3C)
menus.h

void MenuSubStat (HANDLE ExecHandle, short ID, short State);

Changes the state (enabled/disabled) of an item in a pulldown menu.

MenuSubStat is very similar to MenuTopStat, but works with items in associated pulldown menus. MenuSubStat changes status of the item with the given ID (see MenuAddText).

Uses: ROM Call 0x422
Used by: EV_setCmdState, handleVarLinkKey

See also: MenuTopStat


MenuTopRedef

MenuTopRedef Function (ROM Call 0x3F)
menus.h

void MenuTopRedef (HANDLE ExecHandle, short Item, short ID);

Redefines a toolbox icon.

MenuTopRedef redefines the icon in the toolbox Item (0 = first, 1 = second, etc.), which belongs to the menu associated with the handle ExecHandle, to the icon with index Index, i.e. to the icon associated with the submenu with the given ID. The menu must have been started using MenuBegin with the MBF_REDEF flag set. This is used mainly in the Geometry application which has a toolbar menu with redefinable icons. ExecHandle is a handle returned from the MenuBegin function, not one returned from MenuNew.

Note: Such menus cannot be created using commands like MenuNew, MenuAddIcon, etc. The only way to make a such menu is to create an appropriate pre-filled static menu structure, and to pass a pointer to such a structure to MenuBegin. See MenuPopup for more info about menu structures.

Uses: CalcBitmapSize, DrawChar, DrawClipRect, DrawFkey, DrawLine, DrawMultiLines, DrawPix, DrawStr, DrawStrWidth, FontSetSys, PortRestore, RestoreScrState, SaveScrState, ScrRect, ScrRectFill, ScrToWin, SetCurAttr, SetCurClip, memset, ST_eraseHelp, CU_cursorState, CU_restore, CU_stop, ROM Call 0x41E, ROM Call 0x420

See also: MenuBegin, MenuGetTopRedef, MenuTopSelect


MenuTopSelect

MenuTopSelect Function (ROM Call 0x3E)
menus.h

void MenuTopSelect (HANDLE ExecHandle, short Item);

Emphasizes a toolbox.

MenuTopSelect emphasizes (selects) the toolbox Item (0 = first, 1 = second, etc.) which belongs to the menu associated with the handle ExecHandle, by drawing a thick border arround the toolbox. The Geometry application uses this feature. This command also redraws the menu. Call this function with Item = -1 to cancel the selection. ExecHandle is a handle returned from the MenuBegin function, not one returned from MenuNew.

Uses: CalcBitmapSize, DrawChar, DrawClipRect, DrawFkey, DrawLine, DrawMultiLines, DrawPix, DrawStr, DrawStrWidth, FontSetSys, PortRestore, RestoreScrState, SaveScrState, ScrRect, ScrRectFill, ScrToWin, SetCurAttr, SetCurClip, memset, ST_eraseHelp, CU_cursorState, CU_restore, CU_stop, ROM Call 0x41E, ROM Call 0x420

See also: MenuBegin, QMenuTopSelect


MenuTopStat

MenuTopStat Function (ROM Call 0x3D)
menus.h

void MenuTopStat (HANDLE ExecHandle, short Item, short State);

Changes the state (enabled/disabled) of a toolbox.

MenuTopStat changes the state of the toolbox Item (0 = first, 1 = second, etc.) which belongs to the menu associated with the handle ExecHandle. ExecHandle is a handle returned from the MenuBegin function, not one returned from MenuNew. State is a boolean value: if it is TRUE, the toolbox will be enabled; if it is FALSE, the toolbox will be disabled (i.e. it will be dimmed and cannot be selected).

MenuTopStat does not redraw the menu according to the new state; this must be done manually by calling MenuOn.

Used by: EV_setFKeyState, handleVarLinkKey

See also: MenuSubStat


MenuUpdate

MenuUpdate Function (ROM Call 0x49)
menus.h

void MenuUpdate (void);

Draws the default home screen menu.

MenuUpdate redraws the default home screen menu, which is often useful. More precisely, it redraws the menu registered with the current application (for more info, see the EV_registerMenu function from events.h).

Uses: MenuOn, EV_currentApp, ROM Call 0x3CD, ROM Call 0x4FB
Used by: cmd_toolbar, Dialog, handleVarLinkKey, MO_notifyModeChange, CustomEnd, UpdateWindows


PopupAddText

PopupAddText Function (ROM Call 0x44)
menus.h

HANDLE PopupAddText (HANDLE Handle, short ParentID, const char *Text, short ID);

Adds a new text item in a popup menu.

PopupAddText adds the text Text to the popup menu associated with the handle Handle. The text added first will be the first option in the menu, the text added second will be the second option, etc. ID is the identification number which PopupDo will return later if the user selected this menu option, and which may be used as the ParentID parameter in another call. If ID is 0, the TIOS will generate the return value automatically (1 for the first menu option, 2 for the second option, etc.). The legal range for ID is 1 to 4095. If ID is greater than 4095, it will be truncated (ANDed with 0x0FFF). The parameter ParentID has the following meaning:

  • Use ParentID = -1 for menu items which have no submenu.
  • Use ParentID = 0 for menu items which have an associated submenu.
  • If ParentID > 0, this is a submenu item which belongs to the submenu associated to the menu item whose ID equals ParentID.
PopupAddText returns H_NULL in case of an error (i.e. out of memory, ParentID not found, ParentID found but it was not a possible parent, or maximum number of items in a menu exceeded), otherwise it returns Handle. If there is an error adding the new entry, the MF_ERROR bit in the menu structure is set (see MenuPopup for more information on menu structures). You can use MenuFlags to retrieve this flag from the structure.

Although the TIOS menu system allows for menus with more than one level of submenus, it is not possible to create such menus using this command. If you really want more levels of nesting, you can use DynMenuAdd, which supports more levels of nesting, but is only available in AMS 2.00 or later. Alternatively, you can use pre-filled static structures and the MenuPopup function. But note that this is somewhat complicated.

This routine may cause heap compression.

Note: If text is longer than 18 characters, it will be truncated by storing a zero byte into the string after the 18th character. You have to be especially careful because the text parameter is not constant in this case.

Uses: DynMenuAdd
Used by: VarCreateFolderPopup, cmd_dialog, cmd_popup, VarNew, VarOpen, VarSaveAs

See also: DynMenuAdd, DynMenuChange, PopupNew, MenuAddText


PopupBegin

PopupBegin Function (ROM Call 0x3F5)
AMS 2.00 or higher menus.h

HANDLE PopupBegin (HANDLE Handle, short Flags);

Creates a new popup menu with checkmarks features.

PopuBegin allocates a menu-draw structure for a dynamic popup associated with Handle, so that the popup items can use the enable/disable or check mark features of menus. PopupBegin returns a handle which must be passed to PopupBeginDo, not to PopupDo. The Flags parameter is currently not used and should be set to 0.

TI gives a strict method of using dynamic popups that use PopupBegin:

  1. Create an empty, dynamic popup structure with PopupNew.
  2. Build the menu with DynMenuAdd (or PopupAddText).
  3. Pass the handle returned by PopupNew to PopupBegin.
  4. The handle returned by PopupBegin can now be passed to MenuSubStat to enable/disable individual items or MenuCheck to turn on/off or test the status of checkmarks for individual items.
  5. Pass the handle returned from PopupBegin to PopupBeginDo to actually execute the pop-up.
  6. When done with the menu, call MenuEnd on the handle returned from PopupBegin. This will free that handle and the handle returned from PopupNew.
Do not forget that once you call PopupBegin, you may not unlock the handle returned from PopupNew, or call DynMenuAdd, DynMenuChange, or PopupAddText.

This routine may cause heap compression.

Here is an example of a scrolling popup menu with submenus (called "Dynamic Popup Example"):
// A simple popup menu example

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

#define RETURN_VALUE          // Return a Value
#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 200           // Compile for AMS 2.00 or higher

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

// Main Function
void _main(void)
{
  HANDLE handle = PopupNew ("EXAMPLE", 40);
  PopupAddText (handle, -1, "Option 1", 1);
  PopupAddText (handle, -1, "Option 2", 2);
  PopupAddText (handle, 0, "Submenu 3", 3);
  PopupAddText (handle, 0, "Submenu 4", 4);
  PopupAddText (handle, -1, "Option 5", 5);
  PopupAddText (handle, 3, "Suboption 3.1", 6);
  PopupAddText (handle, 3, "Suboption 3.2", 7);
  PopupAddText (handle, 3, "Suboption 3.3", 8);
  PopupAddText (handle, 4, "Suboption 4.1", 9);
  HANDLE exec_handle = PopupBegin (handle, 0);
  MenuCheck (exec_handle, 2, MC_CHECK);
  MenuCheck (exec_handle, 5, MC_FLIP);
  short result = PopupBeginDo (exec_handle, CENTER, CENTER, 0);
  push_longint (result);
  MenuEnd (exec_handle);
}

Uses: HeapAlloc, HeapLock, memset

See also: PopupNew, PopupBeginDo, MenuSubStat, MenuCheck, MenuEnd


PopupBeginDo

PopupBeginDo Function (ROM Call 0x3F6)
AMS 2.00 or higher menus.h

short PopupBeginDo (HANDLE ExecHandle, short x, short y, short StartID);

Executes a dynamically allocated popup using a menu-draw handle.

PopupBeginDo draws the popup menu associated with the handle ExecHandle on the screen. ExecHandle must be returned from PopupBegin and not directly from PopupNew; take care never to mix handles.

The top-left corner of the dialog will be the at the position (x, y); the coordinates are absolute screen coordinates. x, y, or both may also have a special value CENTER, which tells PopupBeginDo to center the menu in this dimension. After the execution, the original contents of the screen will be restored. PopupBeginDo returns the identification number (ID) of the selected menu item (see DynMenuAdd), or 0 if the user pressed ESC. StartID determines which option will be selected first when the menu is executed. It seems that StartID works correctly only for menus without submenus. Anyway, you can always pass 0 to StartID. It causes the function to select the first item.

This routine may cause heap compression.

Here is an example of a scrolling popup menu with submenus (called "Dynamic Popup Example"):

// A simple popup menu example

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

#define RETURN_VALUE          // Return a Value
#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 200           // Compile for AMS 2.00 or higher

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

// Main Function
void _main(void)
{
  HANDLE handle = PopupNew ("EXAMPLE", 40);
  PopupAddText (handle, -1, "Option 1", 1);
  PopupAddText (handle, -1, "Option 2", 2);
  PopupAddText (handle, 0, "Submenu 3", 3);
  PopupAddText (handle, 0, "Submenu 4", 4);
  PopupAddText (handle, -1, "Option 5", 5);
  PopupAddText (handle, 3, "Suboption 3.1", 6);
  PopupAddText (handle, 3, "Suboption 3.2", 7);
  PopupAddText (handle, 3, "Suboption 3.3", 8);
  PopupAddText (handle, 4, "Suboption 4.1", 9);
  HANDLE exec_handle = PopupBegin (handle, 0);
  MenuCheck (exec_handle, 2, MC_CHECK);
  MenuCheck (exec_handle, 5, MC_FLIP);
  short result = PopupBeginDo (exec_handle, CENTER, CENTER, 0);
  push_longint (result);
  MenuEnd (exec_handle);
}

Uses: HeapLock, HeapUnlock, ROM Call 0x421

See also: PopupBegin, MenuEnd, PopupDo


PopupClear

PopupClear Function (ROM Call 0x46)
menus.h

HANDLE PopupClear (HANDLE Handle);

Clears a popup or toolbar menu structure.

PopupClear erases all menu items from the popup menu associated with the handle Handle, without freeing the memory (the popup structure itself remains intact, only menu items are erased). PopupClear returns H_NULL in case of an error, otherwise it returns Handle.

Note: This function is very useful in menus which are parts of dialogs, if some changes in a dialog box may force menu items to be refilled (for example when the user selects a new folder in the "Open Variable" dialog). Since the dialog box code keeps the handle of the menu, a new one cannot be created. So the old popup menu is cleared and new entries are added to it.

It seems that this function can also be used for toolbar menus. As popups and toolbar menus just differ in some points, it should work just fine. Then Handle is a handle returned from the MenuNew function (not one returned from MenuBegin). Take care not to execute MenuBegin or functions which use the menu in any way just after this function without refilling the menu with new items using MenuAddText or MenuAddIcon, or this will result in a crash. Remember that using this function erases all the items; using a menu with no items inside is nonsense.

Also note that the memory allocated to the handle is not released until the next call to DynMenuAdd or PopupAddText.

Uses: HeapAlloc, memset, strlen, strncpy
Used by: VarOpen

See also: PopupNew, DynMenuAdd, DynMenuChange


PopupDo

PopupDo Function (ROM Call 0x47)
menus.h

short PopupDo (HANDLE Handle, short x, short y, short StartID);

Executes a popup menu.

PopupDo draws the popup menu associated with the handle Handle on the screen. Handle must be returned from PopupNew and not from PopupBegin; take care never to mix handles.

The top-left corner of the dialog will be the at the position (x, y); the coordinates are absolute screen coordinates. x, y, or both may also have a special value CENTER, which tells PopupDo to center the menu in this dimension. After the execution, the original contents of the screen will be restored. PopupDo returns the identification number (ID) of the selected menu item (see PopupAddText), or 0 if the user pressed ESC. StartID determines which option will be selected first when the menu is executed. It seems that StartID works correctly only for menus without submenus. Anyway, you can always pass 0 to StartID. It causes the function to select the first item.

This routine may cause heap compression.

Here is an example of a scrolling popup menu with submenus (called "Popup Menu Example"):

// A simple popup menu example

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

#define RETURN_VALUE          // Return a Value
#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 101           // Compile for AMS 1.01 or higher

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

// Main Function
void _main(void)
{
  HANDLE handle = PopupNew ("EXAMPLE", 40);
  PopupAddText (handle, -1, "Option 1", 1);
  PopupAddText (handle, -1, "Option 2", 2);
  PopupAddText (handle, 0, "Submenu 3", 3);
  PopupAddText (handle, 0, "Submenu 4", 4);
  PopupAddText (handle, -1, "Option 5", 5);
  PopupAddText (handle, 3, "Suboption 3.1", 6);
  PopupAddText (handle, 3, "Suboption 3.2", 7);
  PopupAddText (handle, 3, "Suboption 3.3", 8);
  PopupAddText (handle, 4, "Suboption 4.1", 9);
  short result = PopupDo (handle, CENTER, CENTER, 0);
  push_longint (result);
  HeapFree (handle);
}

Uses: MenuPopup, HeapLock, HeapUnlock
Used by: cmd_popup, EV_defaultHandler, EV_quit

See also: PopupNew, MenuPopup


PopupNew

PopupNew Function (ROM Call 0x45)
menus.h

HANDLE PopupNew (const char *Title, short Height);

Creates a new popup menu.

PopupNew allocates memory for a new popup menu, initializes the allocated block with the necessary structures and returns a handle to it (or H_NULL in case of an error). You can later free the memory by calling HeapFree. Title is the title of the menu (you can pass NULL if you do not want a title), and Height is the height of the menu box in pixels (you can pass 0 for autocalculating the height). If the cumulated height of the items in the menu is greater than the available height of the menu box, the contents of the menu will scroll up or down if necessary.

This empty popup structure can be modified with PopupAddText (or DynMenuAdd and DynMenuChange if you wish to use program only on AMS 2.00 or later). The popup can then be executed with PopupDo (or PopupBegin and PopupBeginDo on AMS 2.00 or later if specific menu features are needed).

Note: If Title is longer than 18 characters, it will be truncated by storing a zero byte into the string after the 18th character. You have to be especially careful because the Title parameter is not constant in this case.

Uses: HeapAlloc, memset, strlen, strncpy
Used by: VarCreateFolderPopup, cmd_dialog, cmd_popup, VarNew, VarOpen, VarSaveAs, EV_defaultHandler, MO_modeDialog, HomeExecute, EV_quit, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x486

See also: PopupDo, PopupBegin, PopupClear, DynMenuAdd, DynMenuChange, PopupAddText


PopupText

PopupText Function (ROM Call 0x48)
menus.h

const char *PopupText (HANDLE Handle, short ID);

Returns a pointer to the text of a popup menu item.

PopupText returns a pointer to the text of the popup menu item with the identification number ID (see PopupAddText). Handle is the handle associated with the menu. This function does not work with toolbar menus; you must use MenuItemDef, which does the same for toolbar menus on AMS 2.00 or later.

Uses: ROM Call 0x41E
Used by: VarNew, VarOpen, VarSaveAs, EV_defaultHandler, MO_digestOptions, HomeExecute

See also: PopupNew, PopupDo, PopupAddText


QMenuTopSelect

QMenuTopSelect Function (ROM Call 0x41A)
AMS 2.00 or higher menus.h

unsigned short QMenuTopSelect (HANDLE ExecHandle);

Returns the currently selected top-level menu item.

QMenuTopSelect returns the currently selected top-level menu item (0 = first, 1 = second, etc.) or -1 if none is selected. ExecHandle refers to a menu-draw handle returned from MenuBegin. MenuTopSelect is normally used with redefinable menus.

See also: MenuBegin, MenuTopSelect


VarCreateFolderPopup

VarCreateFolderPopup Function (ROM Call 0x28F)
menus.h

HANDLE VarCreateFolderPopup (unsigned short *CurIndex, unsigned short Flags);

Creates a popup menu containing a list of all folders.

VarCreateFolderPopup creates a dynamic popup (or pulldown) menu which contains a list of all folders in the VAT folder table, and returns a handle to it (or H_NULL in case of an error).

The parameter Flags is usually zero, but it may contain additional flags from the enum VCFPFlags:

VCFP_ALL | "All" is included as the first option in the list, like in the "View" dialog of the Var-Link window.
VCFP_SKIP_CURDIR | The currently active folder is not included in the list.

This function also stores the index of the currently active folder in the word pointed to by CurIndex.

Note: You need to free the returned handle later by calling HeapFree.

This routine may cause heap compression.

Uses: PopupAddText, PopupNew, HeapFree, XR_stringPtr, FolderOp, SymCpy0, SymFindFirst, SymFindNext
Used by: VarNew, VarOpen, VarSaveAs, MO_modeDialog


DynMenuFlags

DynMenuFlags Type (Enumeration)
menus.h

enum DynMenuFlags {DMF_TEXT = 0x0001, DMF_ICON = 0x0002, DMF_BITMAP = 0x0004, DMF_CHILD_SUB = 0x1000, DMF_CHILD = 0x2000, DMF_TOP_SUB = 0x4000, DMF_TOP = 0x8000};

An enumeration for describing possible flags associated to dynamic menu entries.

These constants are used as flags, please see the MenuAddText and MenuAddIcon functions for more information.


ItemTypes

ItemTypes Type (Enumeration)
menus.h

enum ItemTypes {MT_TEXT = 0x8000, MT_XREF = 0x9000, MT_ICON = 0xA000, MT_CASCADE = 0x4000};

An enumeration for describing item types in menus.

As these constants are used mainly in "asm" statements, they are defined using a special method, so they are visible for the built-in assembler (i.e. in "asm" statements). See the example given with the MenuPopup command.


MenuBeginFlags

MenuBeginFlags Type (Enumeration)
menus.h

enum MenuBeginFlags {MBF_WITHICON = 0x01, MBF_REDEF = 0x02, MBF_SYS_ALLOC = 0x04, MBF_MAX_MENU_WIDTH = 0x08, MBF_STRIKEOUT = 0x10, MBF_HMENU = 0x20, MBF_NO_DRAWTOP = 0x40};

An enumeration for describing possible flags passed to MenuBegin.

These constant are used as flags, please see the MenuBegin function for more information.


MenuCheckCmds

MenuCheckCmds Type (Enumeration)
menus.h

enum MenuCheckCmds {MC_CHECK = 0, MC_UNCHECK = 1, MC_STATUS = 2, MC_FLIP = 3};

An enumeration for describing possible commands for the MenuCheck function.

These constants are used as commands, meaning that exactly one of the constants must be specified. Please see the MenuCheck function for more information.


MenuFlagsEnum

MenuFlagsEnum Type (Enumeration)
menus.h

enum MenuFlagsEnum {MF_POPUP = 0x0001, MF_TOOLBOX = 0x0002, MF_NONSEQ = 0x0004, MF_ICON_TITLE = 0x0008, MF_TEXT_TITLE = 0x0010, MF_NO_NUMS = 0x0020, MF_NO_UNAMED = 0x0040, MF_DYN_POPUP = 0x0080, MF_ALT_ICONS = 0x0100, MF_BITMAP_TITLE = 0x0200, MF_ERROR = 0x0800, MF_ICONS_OVERLAP = 0x1000, MF_TITLE = 0x0218};

An enumeration for describing possible flags contained in a dynamic menu.

These constant are used as flags, please see the MenuFlags function for more information. Note that MF_TITLE is a combination of MF_TEXT_TITLE, MF_ICON_TITLE, and MF_BITMAP_TITLE.


MenuKeyValues

MenuKeyValues Type (Enumeration)
menus.h

enum MenuKeyValues {M_NOITEM = 0, M_NOTMENUKEY = -2};

Contains predefined return values of MenuKey.


VCFPFlags

VCFPFlags Type (Enumeration)
menus.h

enum VCFPFlags {VCFP_ALL = 0x01, VCFP_SKIP_CURDIR = 0x02};

Describes possible flags for VarCreateFolderPopup.

The constants in this enumeration are used as flags, meaning that you can combine them through bitwise OR.


nostub.h

nostub.h Header File
Header File Index

Basic header file for kernel-less programming

This header file will be included automatically by default.h, except if you define the global preprocessor symbol USE_KERNEL, or if you explicitly include the doors.h header file before including any other header file.

First, this header file defines a global symbol named NOSTUB which is used in other header files to indicate nostub mode. Next, it includes default.h to make sure that the basic macros which GCC4TI needs are defined.

It then handles nostub-specific directives such as OPTIMIZE_ROM_CALLS (which is useful only for nostub mode) and USE_FLINE_ROM_CALLS (which needs special support in nostub mode). If these symbols are defined, some of the definitions from default.h are overwritten.

It contains code for tigcc.a, to support SAVE_SCREEN and RETURN_VALUE. Finally, it contains some rather complicated macros and asm statements to put data needed for RETURN_VALUE directly into the assembly file.

See also: How to make a nostub program, default.h, doors.h


peekpoke.h

peekpoke.h Header File
Header File Index

Routines for easier access to the memory and to I/O ports

Functions
peek_bit
Fetches a bit from the memory.
peek_l
Fetches a double word from the memory.
peek_w
Fetches a word from the memory.
peek
Fetches a byte from the memory.
peekIO_bit
Reads a bit from an I/O port.
peekIO_w
Reads a word from an I/O port.
peekIO
Reads a byte from an I/O port.
poke_bchg
Inverts a bit at a memory address.
poke_bclr
Clears a bit at a memory address.
poke_bset
Sets a bit at a memory address.
poke_l
Stores a double word in memory.
poke_w
Stores a word in memory.
poke
Stores a byte in memory.
pokeIO_bchg
Inverts a bit in an I/O port.
pokeIO_bclr
Clears a bit in an I/O port.
pokeIO_bset
Sets a bit in an I/O port.
pokeIO_w
Sends a word to an I/O port.
pokeIO
Sends a byte to an I/O port.
speek_l
Fetches a signed double word from the memory.
speek_w
Fetches a signed word from the memory.
speek
Fetches a signed byte from the memory.


peek_bit

peek_bit Function (Macro)
peekpoke.h

short peek_bit (unsigned char *addr, short bit);

Fetches a bit from the memory.

peek_bit is a macro which fetches bit bit from the memory address addr. For example, to read the first bit from the video memory (the pixel in the upper left corner), do this:

byte = peek_bit (0x4C00, 7);
Note that it is better to use LCD_MEM in this case.

Note: Do not use peek_bit for reading I/O ports! Use peekIO_bit instead.


peek_l

peek_l Function (Macro)
peekpoke.h

#define peek_l(addr) (*((unsigned long*)(long)(addr)))

Fetches a double word from the memory.

peek_l is like peek, but fetches a double word from the memory instead of a byte.


peek_w

peek_w Function (Macro)
peekpoke.h

#define peek_w(addr) (*((unsigned short*)(long)(addr)))

Fetches a word from the memory.

peek_w is like peek, but fetches a word from the memory instead of a byte.

Note: Do not use peek_w for reading I/O ports! Use peekIO_w instead.


peek

peek Function (Macro)
peekpoke.h

#define peek(addr) (*((unsigned char*)(long)(addr)))

Fetches a byte from the memory.

peek is a macro which fetches a byte from the memory address addr, where addr does not necessarily need to be a pointer. Instead, it can be of any type (usually an integer) which may represent a memory address in a way which makes sense. This way it allows for fetching bytes from memory using the style which is common in most dialects of the BASIC language. For example, to read a first byte from the video memory, do this:

byte = peek (0x4C00);
Note that it is better to use LCD_MEM in this case.

Note: Do not use peek for reading I/O ports! Use peekIO instead.


peekIO_bit

peekIO_bit Function (Macro)
peekpoke.h

short peekIO_bit (unsigned char *port, short bit);

Reads a bit from an I/O port.

This macro exists because peek_bit is not reliable when reading data from memory-mapped I/O ports. See the notes about peekIO if you want to know why.


peekIO_w

peekIO_w Function (Macro)
peekpoke.h

#define peekIO_w(port) (*((volatile unsigned short*)(long)(port)))

Reads a word from an I/O port.

peekIO_w is like peekIO, but reads a word from the I/O port instead of a byte.


peekIO

peekIO Function (Macro)
peekpoke.h

#define peekIO(port) (*((volatile unsigned char*)(long)(port)))

Reads a byte from an I/O port.

peek is not reliable when reading data from memory-mapped I/O ports. For example, suppose that the user wants to wait until the programable timer on the TI-89 (its value may be read from the address 0x600017) reaches the value 255. The following construction seems quite good:

while (peek (0x600017) != 255);
However, it will cause an infinity loop. Namely, the compiler will notice that the same value is read in the loop. As a normal memory location cannot be changed without explicitely writing to it, and there is nothing in the loop which changes the data at the address 0x600017, the optimizer will move memory reading out of the loop to make the code more efficient. Such behaviour is correct for ordinary memory locations. But the compiler does not know anything about the fact that 0x600017 is not an ordinary memory location but an I/O port, which may be changed unpredictably (purely by the hardware, without any program control). To prevent such behaviour, use peekIO instead of peek, i.e. write
while (peekIO (0x600017) != 255);
Basically, peekIO works exactly like peek, but prevents any unwanted optimizations generated by the compiler. Always use peekIO for reading memory-mapped I/O ports, else you may have trouble (especially in short loops). For example, to read the keyboard column mask on TI-89, do
key_mask = peekIO (0x60001B);
peekIO may be used even for reading bytes in memory, but peek will generate better code when working with memory. However, use peekIO to read any memory location which may change in a way which is unpredictable from the aspect of a normal program flow (for example, a memory location which is changed in the body of the interrupt handler).


poke_bchg

poke_bchg Function (Macro)
peekpoke.h

void poke_bchg (unsigned char *addr, short bit);

Inverts a bit at a memory address.

This macro inverts bit bit at memory address addr. It is useful if you do not want to store a whole byte at this address, but only need to invert the state of a single bit. As usual, the rightmost bit of a value is numbered 0, and the leftmost bit is 7 in this case. For example, let's assume the address addr contains the value 0b10011010, and you call this macro like this:

poke_bchg (addr, 3);
Then the value will be 0b10010010 afterwards. Making the same call again will restore the previous value 0b10011010,

Note: Do not use poke_bchg for sending bits to I/O ports! Use pokeIO_bchg instead.


poke_bclr

poke_bclr Function (Macro)
peekpoke.h

void poke_bclr (unsigned char *addr, short bit);

Clears a bit at a memory address.

This macro clears bit bit at memory address addr. It is useful if you do not want to store a whole byte at this address, but only need to set a single bit to 0. As usual, the rightmost bit of a value is numbered 0, and the leftmost bit is 7 in this case. For example, let's assume the address addr contains the value 0b10011010, and you call this macro like this:

poke_bclr (addr, 3);
Then the value will be 0b10010010 afterwards.

Note: Do not use poke_bclr for sending bits to I/O ports! Use pokeIO_bclr instead.


poke_bset

poke_bset Function (Macro)
peekpoke.h

void poke_bset (unsigned char *addr, short bit);

Sets a bit at a memory address.

This macro sets bit bit at memory address addr, which can be any which which may be cast to unsigned char *. It is useful if you do not want to store a whole byte at this address, but only need to set a single bit to 1. As usual, the rightmost bit of a value is numbered 0, and the leftmost bit is 7 in this case. For example, let's assume the address addr contains the value 0b10010010, and you call this macro like this:

poke_bset (addr, 3);
Then the value will be 0b10011010 afterwards.

Note: Do not use poke_bset for sending bits to I/O ports! Use pokeIO_bset instead.


poke_l

poke_l Function (Macro)
peekpoke.h

#define poke_l(addr,val) (void)(*((unsigned long*)(long)(addr)) = (val))

Stores a double word in memory.

poke_l is like poke, but stores a double word in memory instead of a byte.


poke_w

poke_w Function (Macro)
peekpoke.h

#define poke_w(addr,val) (void)(*((unsigned short*)(long)(addr)) = (val))

Stores a word in memory.

poke_w is like poke, but stores a word in memory instead of a byte.


poke

poke Function (Macro)
peekpoke.h

#define poke(addr,val) (void)(*((unsigned char*)(long)(addr)) = (val))

Stores a byte in memory.

poke is a macro which stores a byte val at the memory address addr, where addr does not necessarily need to be a pointer. Instead, it can be of any type (usually an integer) which may represent a memory address in a way which makes sense. This way it allows for storing bytes in memory using the style which is common in most dialects of the BASIC language. For example, to store a byte 255 at the first byte of the video memory, do this:

poke (0x4C00, 255);
Note: Do not use poke for sending bytes to I/O ports! Use pokeIO instead.


pokeIO_bchg

pokeIO_bchg Function (Macro)
peekpoke.h

void pokeIO_bchg (unsigned char *port, short bit);

Inverts a bit in an I/O port.

This macro exists because poke_bchg is not reliable when sending data to memory-mapped I/O ports. See the notes about pokeIO if you want to know why.


pokeIO_bclr

pokeIO_bclr Function (Macro)
peekpoke.h

void pokeIO_bclr (unsigned char *port, short bit);

Clears a bit in an I/O port.

This macro exists because poke_bclr is not reliable when sending data to memory-mapped I/O ports. See the notes about pokeIO if you want to know why.


pokeIO_bset

pokeIO_bset Function (Macro)
peekpoke.h

void pokeIO_bset (unsigned char *port, short bit);

Sets a bit in an I/O port.

This macro exists because poke_bset is not reliable when sending data to memory-mapped I/O ports. See the notes about pokeIO if you want to know why.


pokeIO_w

pokeIO_w Function (Macro)
peekpoke.h

#define pokeIO_w(port,val) (void)(*((volatile unsigned short*)(long)(port)) = (val))

Sends a word to an I/O port.

pokeIO_w is like pokeIO, but sends a word to the I/O port instead of a byte.


pokeIO

pokeIO Function (Macro)
peekpoke.h

#define pokeIO(port,val) (void)(*((volatile unsigned char*)(long)(port)) = (val))

Sends a byte to an I/O port.

poke is not reliable when sending data to memory-mapped I/O ports. Suppose that you have a device mapped to the address port, and that this device requests sending a sequence ot bytes 127,0,255,0 to this address to be reset. If you simply try to do

poke (port, 127);
poke (port, 0);
poke (port, 255);
poke (port, 0);
the compiler will (incorrectly) conclude that sending a sequence of bytes to the same address is nonsense, because new values will overwrite previous ones (assuming that the address points to the memory), so the optimizer will ignore all stores but the last one. Such behavior is correct if port is a normal memory address, but it may be fatal if port is an address of a memory-mapped I/O port. To prevent such behaviour, use pokeIO instead of poke, i.e. write
pokeIO (port, 127);
pokeIO (port, 0);
pokeIO (port, 255);
pokeIO (port, 0);
Basically, pokeIO works exactly like poke, but prevents any unwanted optimizations generated by the compiler. It may be used even for storing bytes in memory, but poke will generate better code when working with memory.


speek_l

speek_l Function (Macro)
peekpoke.h

#define speek_l(addr) (*((signed long*)(long)(addr)))

Fetches a signed double word from the memory.

speek_l is like peek_l, but the result is interpreted as a signed double word.


speek_w

speek_w Function (Macro)
peekpoke.h

#define speek_w(addr) (*((signed short*)(long)(addr)))

Fetches a signed word from the memory.

speek_w is like peek_w, but the result is interpreted as a signed word.


speek

speek Function (Macro)
peekpoke.h

#define speek(addr) (*((signed char*)(long)(addr)))

Fetches a signed byte from the memory.

speek is like peek, but the result is interpreted as a signed byte.


printf.h

printf.h Header File
Header File Index

Printing routines (now deprecated, use stdio.h instead)

This header file is deprecated. It simply includes stdio.h. It still exists to achieve compatibility with some existing programs.


rsa.h

rsa.h Header File
Header File Index

Routines for large number arithmetic, message digesting and RSA encryption

Functions
BN_power17Mod
Raises a big integer to the 17-th power modulo n.
BN_powerMod
Raises a big integer to the e-th power modulo n.
BN_prodMod
Multiplies two big integers modulo n.
cdecrypt
Decrypt a message.
MD5Done
Produces a Message-Digest as a big integer.
MD5Final
Ends an MD5 operation and produces a Message-Digest.
MD5Init
Initializes Message-Diggest context for usage in MD5 algorithm.
MD5Update
Process a message block using MD5 algorithm.
Predefined Types
BN
A structure for describing very large integers (up to 2040 bits).
MD5_CTX
A structure for describing the context data used for implementing the MD5 Message-Digest Algorithm.


BN_power17Mod

BN_power17Mod Function (ROM Call 0x122)
rsa.h

void BN_power17Mod (BN *dest, const BN *x, const BN *n);

Raises a big integer to the 17-th power modulo n.

BN_power17Mod calculates Y = (X ^ 17) mod N where Y, X and N are big integers (up to 2040 bits) stored in BN structures pointed to by dest, x and n respectively.

This is main routine for RSA decryption used in cdecrypt (see BN for more info about how RSA works).

Uses: BN_prodMod
Used by: cdecrypt


BN_powerMod

BN_powerMod Function (ROM Call 0x123)
rsa.h

void BN_powerMod (BN *dest, const BN *x, const BN *e, const BN *n);

Raises a big integer to the e-th power modulo n.

BN_powerMod calculates Y = (X ^ E) mod N where Y, X, E and N are big integers (up to 2040 bits) stored in BN structures pointed to by dest, x, e and n respectively. This routine is used in TIOS for RSA encryption, but may be used for any other purposes too (see BN for more info about how RSA works).

Uses: BN_prodMod


BN_prodMod

BN_prodMod Function (ROM Call 0x124)
rsa.h

void BN_prodMod (BN *dest, const BN *b, const BN *n);

Multiplies two big integers modulo n.

BN_prodMod calculates Y = (Y * B) mod N where Y, B and N are big integers (up to 2040 bits) stored in BN structures pointed to by dest, b and n respectively. This routine is used in TIOS for RSA encryption, but may be used for any other purposes too (see BN for more info about how RSA works).

Here is an example of program (called "Big Numbers") which takes three (arbitrarily large) integers A, B and N, calculates (A * B) mod N and returns the result (assuming that A, B and N are really integers, i.e. no checking is implemented). This program also illustrates how you can get "big" integers from the expression stack, and push them to it:

// Perform big number arithmetic through BN_prodMod

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 101           // Compile for AMS 1.01 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents
#define RETURN_VALUE          // Return a Value

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

#define GetBignumArg(ap, bn) \
  ({unsigned char __n = *--(unsigned char*)(ap); \
  char *__p = (char*)(bn) + __n; \
  (bn)->Len = __n; \
  while (__n--) *__p-- = *--(ap); \
  (void)*(ap)--; })

void push_Bignum(BN *bn)
{
  unsigned m, n = bn->Len;
  char *p = (char*)bn;
  m = n;
  while (n--) push_quantum (*++p);
  push_quantum_pair (m, POSINT_TAG);
}

void _main(void)
{
  ESI argptr = top_estack;
  BN *a = malloc (256), *b = malloc (256), *c = malloc (256);
  GetBignumArg (argptr, a);
  GetBignumArg (argptr, b);
  GetBignumArg (argptr, c);
  while (GetArgType (top_estack) != END_TAG)  // Clean up arguments
    top_estack = next_expression_index (top_estack);
  top_estack--;
  BN_prodMod (a, b, c);
  push_Bignum (a);
  free (a); free (b); free (c);
}

Used by: BN_power17Mod, BN_powerMod


cdecrypt

cdecrypt Function (ROM Call 0x127)
rsa.h

void cdecrypt (BN *dest, char *src, unsigned long size, BN *public_key);

Decrypt a message.

cdecrypt decrypts the message pointed to by src which is size butes long using the public key pointed to by public_key, and stores decrypted message in BN structure pointed to by dest (see BN for more info about how RSA works). Note that the message must be short enough to be decrypted in the structure pointed to by dest, because BN structure is maximally 255 bytes long.

TIOS use decryption with public key (N,17) where N is a 512-bit (64-byte) key, given at the beginning of the certificate code, although others may (or may not) be used. That's why it uses BN_power17Mod. Generally, for usage in RSA, N must be equal to P * Q, where P and Q are large primes, and where (P-1) * (Q-1) is relatively prime to 17 (other part of the key).

Uses: BN_power17Mod, memcpy


MD5Done

MD5Done Function (ROM Call 0x257)
rsa.h

void MD5Done (BN *digest, MD5_CTX *context);

Produces a Message-Digest as a big integer.

MD5Done is very similar as MD5Final. It calls MD5Final, but stores the computed Message-Digest in BN structure pointed to by digest (i.e. stores the length byte in digest[0]). This function is the only extension to MD5 package invented by TI: all other functions is picked up from the original MD5 package, but optimized for 16-bit processors (instead of 32-bit).

Uses: MD5Final


MD5Final

MD5Final Function (ROM Call 0x256)
rsa.h

void MD5Final (unsigned char *digest, MD5_CTX *context);

Ends an MD5 operation and produces a Message-Digest.

MD5Final finalizes MD algorithm, i.e. ends an MD5 Message-Digest operation, writing the Message-Digest in the 16-byte buffer pointed to by digest in according to the information stored in context.

Uses: MD5Update
Used by: MD5Done

See also: MD5Init


MD5Init

MD5Init Function (ROM Call 0x254)
rsa.h

void MD5Init (MD5_CTX *context);

Initializes Message-Diggest context for usage in MD5 algorithm.

MD5Init begins a MD5 Message-Diggest Algorithm, i.e. fills the MD5_CTX structure pointed to by context with necessary data. MD5 is the algorithm which takes as input a message of arbitrary length and produces as output a 128-bit "fingerprint" or "message digest" of the input. It is conjectured that it is computationally infeasible to produce two messages having the same message digest, or to produce any message having a given prespecified target message digest. The MD5 algorithm is intended for digital signature applications, where a large file must be "compressed" in a secure manner before being encrypted with a private (secret) key under a public-key cryptosystem such as RSA (see BN for more info about how RSA works).


MD5Update

MD5Update Function (ROM Call 0x255)
rsa.h

void MD5Update (MD5_CTX *context, unsigned char *input, unsigned long InputLen);

Process a message block using MD5 algorithm.

MD5Update performs a MD5 block update operation. It continues an MD5 message-digest operation, by processing InputLen-byte length message block pointed to by input, and by updating the MD5 context pointed to by context. MD5Update may be called as many times as necessary, so the message may be processed in blocks.

Uses: memcpy
Used by: MD5Final

See also: MD5Init


BN

BN Type (Structure)
rsa.h

typedef struct {
unsigned char Len;
unsigned char Data[];
} BN;

A structure for describing very large integers (up to 2040 bits).

Note that Data contains the number in little endian format.

TIOS uses big integers for implementing RSA criptography algorithm to authenticate (digitally sign) ROM images (and flash applications), more precise, to protect actual ROM/Flash certificate data (see cert.h header file). The basic ideas of RSA are as follows: under certain conditions, function

Y = (X ^ A) mod N

has function

X = (Y ^ B) mod N

as its inverse function, where parameter B depends, of course, of A and N. But, computing B from A and N requires that the prime factors of N are known. Now, suppose that N = P * Q, where P and Q are large primes, such that nobody can factor N in a real time. Suppose also that somebody (person XXX for example) knows two large primes P and Q. Person XXX can compute N = P * Q. After this, he may insist (for security reasons) that anybody which wants to send the message to XXX must to encode the message using the formula Y = (X^A) mod N, where X is an original message, and Y is encoded message. Constants A and N may be published without any danger, and pair (N,A) is so-called public key. XXX may decrypt encoded message Y using the formula X = (Y^B) mod N because XXX can calculate B (he knows the prime factor of N). But note that nobody else can decrypt X, because nobody else knows prime factors of N a priori, and they cannot be computed in a real time. Pair (N,B) is so-called private key.

This is only a half of the story. Suppose that person XXX wants to send a message to person YYY. He will encrypt the message with the public key of person YYY. YYY will, of course, decrypt the message with his private key. But, suppose that XXX send together with encoded message another message (called "signature") which is encoded using formula Y = (X^B) mod N, i.e. using PRIVATE key of XXX. Then, if YYY tries to decode such message using PUBLIC key of XXX, he must get original message too (so, he will receive two identical copies of the message). But, after this, YYY can be sure that really XXX sent the message (not some third person), because nobody else can compute B from A, i.e. nobody else can produce a message which can be decrypted using the public key of XXX!

To summarize: the RSA algorithm uses two keys, one is public and one private. Data encrypted with one of these keys can only be decrypted with the other key. So given the procedure is secure, data encryped with the public key can only be decrypted with the private key, and valid data decrypted with the public key could only be produced by the private key.


MD5_CTX

MD5_CTX Type (Structure)
rsa.h

typedef struct {
unsigned long state[4]; /* state (ABCD) */
unsigned long count[2]; /* number of bits modulo 2^64 (lsb first) */
unsigned char buffer[64]; /* input buffer */
} MD5_CTX;

A structure for describing the context data used for implementing the MD5 Message-Digest Algorithm.

MD5 is the algorithm which takes as input a message of arbitrary length and produces as output a 128-bit "fingerprint" or "message digest" of the input. It is conjectured that it is computationally infeasible to produce two messages having the same message digest, or to produce any message having a given prespecified target message digest. The MD5 algorithm is intended for digital signature applications, where a large file must be "compressed" in a secure manner before being encrypted with a private (secret) key under a public-key cryptosystem such as RSA (see BN for more info about how RSA works). Summary, message digests create a unique number for given data. By sending a message digest encrypted with the private key, along with the original message, it is possible to check that the message came from the correct source. This is done by generating the message digest, and comparing it against the encrypted version sent along with the message (decrypted with the public key). If they match, then this "authenticates" the message.

TI implements the MD5 Message-Digest Algorithm optimised for 16 bit operation rather than 32 bit operation as in original algorithm. The code is based on "RSA Data Security, Inc. MD5 Message-Digest Algorithm". A good reference and source code for this algorithm can be found at [RFC1321].


setjmp.h

setjmp.h Header File
Header File Index

ANSI-compatible routines for non-local jumps

Functions
longjmp
Performs nonlocal goto.
setjmp
Sets up for nonlocal goto.
Predefined Types
JMP_BUF
A type for capturing a task state.


longjmp

longjmp Function (ROM Call 0x267)
setjmp.h

void longjmp (void *j_buf, short ret_val);

Performs nonlocal goto.

A call to longjmp restores the task state captured by the last call to setjmp with the argument j_buf. It then returns in such a way that setjmp appears to have returned with the value ret_val. j_buf is usually a buffer of type JMP_BUF. See setjmp for more info.

Note: longjmp should not be called with a value 0 as ret_val.


setjmp

setjmp Function (ROM Call 0x266)
setjmp.h

short setjmp (void *j_buf);

Sets up for nonlocal goto.

setjmp captures the complete task state in j_buf and returns 0. j_buf is usually a buffer of type JMP_BUF. A later call to longjmp with j_buf restores the captured task state and returns in such a way that setjmp appears to have returned with the value val. A task state consists of address registers A2-A7, data registers D2-D7, and the program counter.

setjmp must be called before longjmp. The routine that calls setjmp and sets up j_buf must still be active and cannot have returned before the longjmp is called. If it has returned, the results are unpredictable (and usually results with a crash). setjmp is useful for dealing with errors and exceptions encountered in a low-level subroutine of a program. setjmp returns 0 when it is initially called. If the return is from a call to longjmp, setjmp returns a nonzero value.

Note: The saved task state is not complete enough that setjmp can be used to implement coroutines (i.e. multitasking). Namely, registers A0, A1, D0, D1 and SR are not included into the task state.


JMP_BUF

JMP_BUF Type (Array)
setjmp.h

typedef struct {
unsigned long D2, D3, D4, D5, D6, D7;
unsigned long A2, A3, A4, A5, A6, A7;
unsigned long PC;
} JMP_BUF [1];

A type for capturing a task state.

JMP_BUF is a type designed for capturing a task state needed for the setjmp and longjmp commands.


sprites.h

sprites.h Header File
Header File Index

Simple sprite routines

Functions
ClipSprite8
Safely draws a sprite with a width of 8 pixels or less on the screen.
ClipSprite16
Safely draws a sprite with a width of 16 pixels or less on the screen.
ClipSprite32
Safely draws a sprite with a width of 32 pixels or less on the screen.
Sprite8
Draws a sprite with a width of 8 pixels or less on the screen.
Sprite16
Draws a sprite with a width of 16 pixels or less on the screen.
Sprite32
Draws a sprite with a width of 32 pixels or less on the screen.
Predefined Types
SprtModes
An enumeration to describe possible modes of sprite drawing.

For lots of advanced drawing routines, we recommend you to download either the ExtGraph static library by the TI-Chess Team or Genlib "kernel"-based dynamic library by the Time To Team.

See also: graph.h, gray.h


ClipSprite8

ClipSprite8 Function* (tigcc.a)
sprites.h

void ClipSprite8 (short x, short y, short height, const unsigned char *sprite, void *vm_addr, short mode);

Safely draws a sprite with a width of 8 pixels or less on the screen.

ClipSprite8 works exactly like Sprite8, but it doesn't draw out of the boundaries of a 240x128 screen, unlike Sprite8 if given x < 0, y < 0, x > 232 or y > 128 - height.

See Sprite8 for more info about sprites.

See also: Sprite8


ClipSprite16

ClipSprite16 Function* (tigcc.a)
sprites.h

void ClipSprite16 (short x, short y, short height, const unsigned short *sprite, void *vm_addr, short mode);

Safely draws a sprite with a width of 16 pixels or less on the screen.

ClipSprite16 works exactly like Sprite16, but it doesn't draw out of the boundaries of a 240x128 screen, unlike Sprite16 if given x < 0, y < 0, x > 224 or y > 128 - height.

See Sprite8 for more info about sprites.

See also: Sprite16


ClipSprite32

ClipSprite32 Function* (tigcc.a)
sprites.h

void ClipSprite32 (short x, short y, short height, const unsigned long *sprite, void *vm_addr, short mode);

Safely draws a sprite with a width of 32 pixels or less on the screen.

ClipSprite32 works exactly like Sprite32, but it doesn't draw out of the boundaries of a 240x128 screen, unlike Sprite32 if given x < 0, y < 0, x > 208 or y > 128 - height.

See Sprite8 for more info about sprites.

See also: Sprite32


Sprite8

Sprite8 Function* (tigcc.a)
sprites.h

void Sprite8 (short x, short y, short height, const unsigned char *sprite, void *vm_addr, short mode);

Draws a sprite with a width of 8 pixels or less on the screen.

Sprite8 draws a sprite with a width of 8 pixels or less on the screen. See ClipSprite8 for a version that handles out-of-screen sprites gracefully, and Sprite16, ClipSprite16, Sprite32 or ClipSprite32 for wider sprites. This routine is much faster than TIOS routines such as DrawIcon, BitmapPut, etc. x and y are the coordinates of the upper left corner of the sprite. height is the height of the sprite. sprite is a pointer to the array of unsigned characters which define the shape of the sprite (line by line). vm_addr is the pointer to the video plane; it should be LCD_MEM if you are not using grayscale or the PortSet function. mode is the drawing mode, and it may have one of the following values (these constants are defined in the enum SprtModes):

SPRT_XOR | XOR the sprite into a background. This is used only for non-masked sprites. XOR mode switches every pixel with a corresponding '1' bit in the sprite array from white to black and verse vica.
SPRT_OR | OR the sprite into a background. This is mainly used for masked sprites together with SPRT_AND. OR means that every pixel with a corresponding '1' bit in the sprite array will be set to black, but all other pixels stay the same. If you want to turn all other pixels to white instead, use SPRT_RPLC.
SPRT_AND | AND the sprite into a background. This is used for masked sprites together with SPRT_OR. AND turns off every pixel with a corresponding '0' bit in the sprite array, but all other pixels remain untouched. If you want to turn all other pixels to black instead, use SPRT_RPLC.
SPRT_RPLC | RePLaCe the sprite into a background. RPLC sets every pixel with a corresponding '1' bit to black and every pixel with a corresponding '0' bit to white. This is equivalent to calling Sprite8(x,y,h,sprite,plane,SPRT_AND); Sprite8(x,y,h,sprite,plane,SPRT_OR);.

In fact, you can use one of two techniques to draw sprites:

  • Non-masked sprites. Using this method, the sprites are simply XORed into the background. This technique was popular in many games on old 8-bit computers. To erase the sprite, it is enough to call the routine again on the same position.
  • Masked sprites. This is the more advanced method, which needs more programming practice, but produces much better results. Using this method, you first need to erase a part of the background which occupies a space where the sprite need to be displayed, then to draw the actual sprite shape. To do this, AND the inverse of the sprite mask to the background, then OR the sprite at the same location. However, it is not so easy to restore the background later. For solving this problem, a lot of advanced methods are developed (like "double-buffering", etc.). These methods are quite common in advanced ASM games, and they are explained in many ASM tutorials.
Here is a simple example (called "Masked Sprite"), which first draws a simple "background", then draws a "masked" sprite (which is a simple 8x8 square with solid edges and blank interior) at (30,30):
// Display a masked sprite over an arbitrary background

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

// Main Function
void _main(void)
{
  static const unsigned char sprite[] = {0xFF,0x81,0x81,0x81,0x81,0x81,0x81,0xFF};
  static const unsigned char imask[] = {(unsigned char)~0xFF,(unsigned char)~0xFF,
    (unsigned char)~0xFF,(unsigned char)~0xFF,(unsigned char)~0xFF,
    (unsigned char)~0xFF,(unsigned char)~0xFF,(unsigned char)~0xFF};
  int i;
  ClrScr ();
  for (i = 0; i <= LCD_WIDTH; i++)
    DrawLine (i, 0, i, LCD_HEIGHT, A_SHADE_NS);  // A simple background
  Sprite8 (30, 30, 8, imask, LCD_MEM, SPRT_AND);
  Sprite8 (30, 30, 8, sprite, LCD_MEM, SPRT_OR);
  ngetchx ();
}
Here the sprite mask is {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF}, but it needs to be inverted before passing it to the Sprite8 function. For this purpose, the operator '~' may be very useful. Note that '~' is "bitwise NOT". Of course, ~0xFF is the same as 0x00, but this notation makes the program more clear (and it does not increase the code size, because the inverting will be performed at compilation time). And if you want to use Sprite16, ClipSprite16, Sprite32 or ClipSprite32, the notation ~0xFF will still be valid in a short int array, or in a long int array if you add the 'L' suffix (see the respective info about Sprite32 and ClipSprite32). Without this notation, you must use 0x00 in Sprite8, but 0xFF00 in Sprite16/ClipSprite16, and 0xFFFFFF00 in Sprite32/ClipSprite32. This is why a notation like ~0xFF is more universal.

You can use binary numbers to define your sprites. On the one hand, it makes the program incompatible with some other C dialects. On the other hand, it makes designing a sprite much easier and also allows for editing the sprite at a later time without having to reconvert it. The binary representation of the sprite presented above would look like this:
static const unsigned char sprite[]={
0b11111111,
0b10000001,
0b10000001,
0b10000001,
0b10000001,
0b10000001,
0b10000001,
0b11111111};

See also: ClipSprite8


Sprite16

Sprite16 Function* (tigcc.a)
sprites.h

void Sprite16 (short x, short y, short height, const unsigned short *sprite, void *vm_addr, short mode);

Draws a sprite with a width of 16 pixels or less on the screen.

Sprite16 works exactly like Sprite8, but it takes sprites with a width of 16 pixels. sprite is now a pointer to the array of unsigned short integers which defines the sprite. So, to define a sprite (or sprite mask), use something like

static const unsigned short sprite[] = {...};
See Sprite8 for more info about sprites, and ClipSprite16 for a version that handles out-of-screen sprites gracefully.

See also: ClipSprite16


Sprite32

Sprite32 Function* (tigcc.a)
sprites.h

void Sprite32 (short x, short y, short height, const unsigned long *sprite, void *vm_addr, short mode);

Draws a sprite with a width of 32 pixels or less on the screen.

Sprite32 works exactly like Sprite8, but it takes sprites with a width of 32 pixels. sprite is now a pointer to the array of unsigned long integers which defines the sprite. So, to define a sprite (or sprite mask), use something like

static const unsigned long sprite[] = {...};
Note: If you define a sprite mask and invert it with the '~' operator, you need to take care of the possibility of the first two bytes being zero in one constant. In this case, the constant will be assumed to be a 16 bit value, so only 16 bits will be inverted. Then the constant is promoted to an unsigned long integer, and the first 16 bits are still zero as if they actually belonged to the mask. To take care of this problem, add the 'L' (long) suffix to the end of the value.

If you want to use sprites wider than 32 pixels (which is not very likely), one solution is to use a "kernel"-based program and graphlib::put_sprite (see Frequently Asked Questions for more info about how to do it). If you don't want to use kernel-based programs, the proposed method depends on what the use of the sprite will be:
  • If you don't need too fast action, the built-in TIOS function BitmapPut may be good enough.
  • If you need a very fast sprite routine for very large sprites, then you must write it yourself, or use prewritten ones in ExtGraph or Genlib.

See Sprite8 for more info about sprites, and ClipSprite32 for a version that handles out-of-screen sprites gracefully.

See also: ClipSprite32


SprtModes

SprtModes Type (Enumeration)
sprites.h

enum SprtModes {SPRT_XOR, SPRT_OR, SPRT_AND, SPRT_RPLC};

An enumeration to describe possible modes of sprite drawing.

This type is used by all sprite functions.


statline.h

statline.h Header File
Header File Index

Routines for manipulation of the status line

Functions
ST_angle
Sets the angle mode indicator in the status line.
ST_batt
Sets the battery low indicator in the status line.
ST_busy
Sets the BUSY indicator in the status line.
ST_eraseHelp
Redraws the status line.
ST_folder
Sets the folder name indicator in the status line.
ST_graph
Sets the graph mode indicator in the status line.
ST_helpMsg
Displays message in the status line.
ST_modKey
Sets the modifier key indicator in the status line.
ST_precision
Sets the precision mode indicator in the status line.
ST_progressBar
Creates a progress bar in the status line.
ST_progressDismiss
Removes a progress bar from the status line.
ST_progressIncrement
Increments the value of a progress bar.
ST_progressUpdate
Changes the value of a progress bar.
ST_readOnly
Sets the "read only" (or "locked") indicator in the status line.
ST_refDsp
Displays a system message in the status line.
ST_stack
Sets the history pairs indicator in the status line.
Predefined Types
Bool
An enumeration to describe true or false values.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
ST_ACTIVITIES
Contains status bar activity flags.
ST_FLAGS
An enumeration containing codes of status line indicators.
ST_PROGRESS_BAR
A structure describing a progress bar.
WIN_RECT
A structure for defining a rectangular area.
WINDOW
The main window-describing structure.


ST_angle

ST_angle Function (ROM Call 0xE0)
statline.h

void ST_angle (short mode);

Sets the angle mode indicator in the status line.

ST_angle sets the angle mode indicator to RAD or DEG, depending of whether mode is ST_RAD or ST_DEG (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line. Note that this command acts only to the displayed status; it would not change the actual current angle mode (use MO_digestOptions if you want to change angle mode).

Uses: ST_eraseHelp, ST_flags
Used by: MO_digestOptions


ST_batt

ST_batt Function (ROM Call 0xE1)
statline.h

void ST_batt (short mode);

Sets the battery low indicator in the status line.

ST_batt sets the battery low indicator to nothing, BATT with light background, or BATT with dark background, depending of whether mode is ST_BATT_OK, ST_BATT_LOW or ST_BATT_REPLACE (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line.

Uses: ST_eraseHelp, ST_flags


ST_busy

ST_busy Function (ROM Call 0xE2)
statline.h

void ST_busy (short mode);

Sets the BUSY indicator in the status line.

ST_busy sets the program status indicator to idle, busy or paused, depending of whether mode is ST_IDLE, ST_BUSY or ST_PAUSED (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line. In the idle mode, the number of entry/answer pairs in the history area would be displayed, else words "BUSY" or "PAUSE" would be displayed. If ST_busy is called with argument ST_NORMAL, the indicator would be erased. Note that the TIOS event handler always sets "BUSY" indicator before calling an event to an application, and clears it when the application returns from handling the event.

Note: Alternative mode names ACTIVITY_IDLE, ACTIVITY_BUSY and ACTIVITY_PAUSED known from DoorsOS will also be accepted, and these constants are defined in enum ST_ACTIVITIES.

Uses: ST_eraseHelp, ST_flags
Used by: cmd_disptbl, cmd_pause, EV_centralDispatcher, EV_eventLoop, EV_getc, GR3_handleEvent, GS_PlotAll, GZ_Stat, Regraph


ST_eraseHelp

ST_eraseHelp Function (ROM Call 0xE3)
statline.h

short ST_eraseHelp (void);

Redraws the status line.

If the status flags indicate that a help message is being displayed, this function redraws the status line, effectively removing the message. Returns TRUE or FALSE, depending of whether redrawing was performed or not.

Uses: are_expressions_identical, next_expression_index, PortRestore, RestoreScrState, SaveScrState, XR_stringPtr, is0, lead_conjunct_factor_index, remaining_conjuncts_index, ST_flags, WinAttr, WinFill, WinFont, WinStrXY
Used by: ST_angle, ST_batt, ST_busy, ST_folder, ST_graph, ST_modKey, ST_precision, ST_progressDismiss, ST_readOnly, Dialog, MO_notifyModeChange, OSLinkCmd, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, GT_FreeTrace, GT_Trace, ROM Call 0x421


ST_folder

ST_folder Function (ROM Call 0xE4)
statline.h

void ST_folder (const char *name);

Sets the folder name indicator in the status line.

ST_folder sets the folder name indicator to name, i.e. displays the given folder name (converted to uppercase letters) at the beginning of the status line. Note that this command acts only to the displayed status; it would not change the actual current folder (use routines for vat.h for changing the current folder).

Uses: ST_eraseHelp, strlen, CTypeTable
Used by: cmd_delfold, cmd_newfold, push_setfold, handleVarLinkKey, MO_digestOptions, OSLinkCmd, ROM Call 0x437


ST_graph

ST_graph Function (ROM Call 0xE5)
statline.h

void ST_graph (short mode);

Sets the graph mode indicator in the status line.

ST_angle sets the graph mode indicator to FUNC, PAR, POL, SEQ, 3D or DE, depending of whether mode is ST_FUNC, ST_PAR, ST_POL, ST_SQR, ST_3D or ST_DE (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line. Note that this command acts only to the displayed status; it would not change the actual current graph mode.

Uses: ST_eraseHelp, ST_flags


ST_helpMsg

ST_helpMsg Function (ROM Call 0xE6)
statline.h

void ST_helpMsg (const char *msg);

Displays message in the status line.

ST_helpMsg displays the message msg in the status line, also setting a status flag indicating that a message is being displayed.

Uses: PortRestore, RestoreScrState, SaveScrState, WinFill, WinFont, WinStrXY
Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_twovar, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_comb, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_integer_lcm, push_is_prime, push_lim, push_max, push_min, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_rotate, push_shift, push_sign, push_sin2, push_solve, push_summation, push_tan, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_or, push_product, push_sum, push_to_cylin, push_to_sphere, compare_complex_magnitudes, push_overflow_to_infinity, EV_defaultHandler, handleVarLinkKey, MO_notifyModeChange, GD_Circle, GD_Eraser, GD_HVLine, GD_Line, GD_Pen, GD_Select, GD_Text, GZ_Box, HomePushEStack, OSLinkCmd, MenuKey, abort, HelpKeys, add_to_top, are_units_consistent, compare_numbers, EQU_deStatus, EV_quit, get_ub, GT_DE_Init_Conds, GT_Trace, GZ_InOut, GZ_Integer, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, spike_optionD, times_top, ROM Call 0x421, ROM Call 0x4E6

Deprecated alias: ST_showHelp


ST_modKey

ST_modKey Function (ROM Call 0xE7)
statline.h

void ST_modKey (short flags);

Sets the modifier key indicator in the status line.

ST_modKey sets the modifier key indicator to nothing, 2nd, shift, diamond, alpha, shifted alpha lock or alpha lock, depending of whehter mode is ST_NONE, ST_2ND, ST_SHIFT, ST_DIAMOND, ST_ALPHA, ST_SH_A_LOCK or ST_A_LOCK (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line. This function has a very limited usage, because it is called very often from AutoInt 1, so if interrupts are enabled, the modifier key indicator will be changed very soon depending of actual state of the keyboard.

Uses: ST_eraseHelp, are_expressions_identical, next_expression_index, PortRestore, RestoreScrState, SaveScrState, is0, lead_conjunct_factor_index, remaining_conjuncts_index, ST_flags, WinAttr, WinFill, WinFont, WinStrXY
Used by: EV_defaultHandler, trunc, ROM Call 0x473


ST_precision

ST_precision Function (ROM Call 0xE8)
statline.h

void ST_precision (short mode);

Sets the precision mode indicator in the status line.

ST_precision sets the precision mode indicator to AUTO, EXACT or APPROX, depending of whether mode is ST_AUTO, ST_EXACT or ST_APPROX (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line. Note that this command acts only to the displayed status; it would not change the actual current precision mode.

Uses: ST_eraseHelp, PortRestore, RestoreScrState, SaveScrState, XR_stringPtr, ST_flags, WinFill, WinFont, WinStrXY
Used by: MO_digestOptions


ST_progressBar

ST_progressBar Function (ROM Call 0x4D8)
AMS 2.00 or higher statline.h

void ST_progressBar (ST_PROGRESS_BAR *pb, long low, long high);

Creates a progress bar in the status line.

ST_progressBar creates a progress bar in the status line (excluding the busy indicator), representing values ranging from low to high. The progress bar will be stored into pb. The function also redraws the line at the top of the status line.

As an alternative to this function, you can fill an ST_PROGRESS_BAR structure manually. This gives you the possibility to create a progress bar in any window.

Here is an example (called "Progress Bar"):

// Progress bar example for TIGCC

// Define this to display the progress bar in a (large) window
//#define USE_WINDOW_PB

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

#define MIN_AMS 200           // Compile for AMS 2.00 or higher

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

// Main Function
void _main(void)
{
  short j;

#ifdef USE_WINDOW_PB
  ST_PROGRESS_BAR spb = {NULL, {0, 0, 0, 0}, 0, 0, 100, 100, 0};
  WINDOW w;
  memcpy (&(spb.rect), ScrToWin (ScrRect), sizeof (WIN_RECT));
  spb.physwidth = spb.rect.x1 - spb.rect.x0 + 1;
  WinOpen (&w, &(spb.rect), WF_SAVE_SCR | WF_NOBORDER);
  spb.w = &w;
#else
  ST_PROGRESS_BAR spb;
  ST_progressBar (&spb, 0, 100); // Create the progress bar in spb. low=0, high=100.
                                 // It will be created in the status line.
#endif

  for (j = 0; j < 20; j++)
    {
      OSFreeTimer (USER_TIMER);
      OSRegisterTimer (USER_TIMER, 1);
      while (!OSTimerExpired (USER_TIMER)); // Wait a little...
      ST_progressIncrement (&spb, 1); // Increment the progress bar by 1/100.
    }
  ST_progressUpdate (&spb, 50); // Increment the progress bar up to 50/100.
  OSFreeTimer (USER_TIMER);
  OSRegisterTimer (USER_TIMER, 20);
  while (!OSTimerExpired (USER_TIMER)); // Wait for about 1 second...
  OSFreeTimer (USER_TIMER);
  ST_progressUpdate (&spb, 100); // Fill the progress bar entirely.

  GKeyIn (NULL, 0);
  ST_progressDismiss (&spb); // Remove the progress bar, redraw status line.
#ifdef USE_WINDOW_PB
  WinClose (&w);
#endif
}

Uses: WinFill, WinWidth

See also: ST_progressDismiss, ST_progressIncrement, ST_progressUpdate, ST_PROGRESS_BAR


ST_progressDismiss

ST_progressDismiss Function (ROM Call 0x4DB)
AMS 2.00 or higher statline.h

void ST_progressDismiss (ST_PROGRESS_BAR *pb);

Removes a progress bar from the status line.

ST_progressDismiss removes the progress bar pointed to by pb, and redraws the status line indicators. It is not necessary to call this function when you finish using a progress bar.

Uses: ST_eraseHelp

See also: ST_progressBar, ST_progressIncrement, ST_progressUpdate, ST_PROGRESS_BAR


ST_progressIncrement

ST_progressIncrement Function (ROM Call 0x4DA)
AMS 2.00 or higher statline.h

void ST_progressIncrement (ST_PROGRESS_BAR *pb, long amount);

Increments the value of a progress bar.

ST_progressIncrement increments the progress bar pointed to by pb, by the quantity given in amount. It also displays the busy indicator in the status line.

If the resulting progress value is greater than the field logwidth of *pb, the bar will be filled completely. If amount is zero, the progress bar will simply be redrawn.

This function is not equivalent to ST_progressUpdate.

Uses: ST_progressUpdate

See also: ST_progressBar, ST_progressDismiss, ST_progressUpdate, ST_PROGRESS_BAR


ST_progressUpdate

ST_progressUpdate Function (ROM Call 0x4D9)
AMS 2.00 or higher statline.h

void ST_progressUpdate (ST_PROGRESS_BAR *pb, long value);

Changes the value of a progress bar.

ST_progressUpdate updates the progress bar pointed to by pb, setting the progress to value. It also displays the busy indicator in the status line.

If value is greater than the logwidth field of *pb, the bar will be filled completely.

This function is not equivalent to ST_progressIncrement.

Uses: WinFill, _ds32s32
Used by: ST_progressIncrement

See also: ST_progressBar, ST_progressDismiss, ST_progressIncrement, ST_PROGRESS_BAR


ST_readOnly

ST_readOnly Function (ROM Call 0xE9)
statline.h

void ST_readOnly (short mode);

Sets the "read only" (or "locked") indicator in the status line.

ST_readOnly sets the "read only" ("locked") indicator in the status line if the mode is non-zero, else resets the indicator. But note that this indicator appears only when you open a variable in a text editor, and that this routine does not set or change the read-only state of the text currently being edited. This function is called from TE_indicateReadOnly.

Uses: ST_eraseHelp, ST_flags
Used by: TE_indicateReadOnly


ST_refDsp

ST_refDsp Function (ROM Call 0xEB)
statline.h

void ST_refDsp (short msg_no);

Displays a system message in the status line.

ST_refDsp displays various system messages (determined by msg_no) in the status line (this function calls ST_helpMsg). Here is the list of used messages:

1 | TYPE OR USE left right up down + [ENTER]=OK AND [ESC]=CANCEL
2 | USE up AND down TO OPEN CHOICES
3 | USE left right up down + [ENTER]=OK AND [ESC]=CANCEL
4 | TYPE + [ENTER]=OK AND [ESC]=CANCEL
5 | USE left right up down OR TYPE + [ESC]=CANCEL
6 | USE left right up down + [ENTER]=OK AND [ESC]=CANCEL, OR DRAG
7 | DATA PLACED IN VARIABLE SYSDATA
8 | DATA PLACED IN HOME SCREEN HISTORY
9 | [ENTER]=OK AND [ESC]=CANCEL
10 | empty
11 | USE left right + [ENTER]=OK AND [ESC]=CANCEL
12 | USE left right + [ENTER]=OK AND [ESC]=CANCEL
13 | USE [2ND] [KEYS] OR [ESC]=CANCEL


ST_stack

ST_stack Function (ROM Call 0xEA)
statline.h

void ST_stack (short index, short total);

Sets the history pairs indicator in the status line.

ST_stack sets the displayed number of entry/answer pairs in the history area to index/total. This indicator is displayed in the status line only if the current program activity status (set by ST_busy) is ST_IDLE. Note that this command acts only on the displayed status; it does not change the actual number of entries in the history area, nor the capacity of the history area.

Uses: ST_flags
Used by: cmd_disphome, HomeExecute, HomePushEStack


ST_FLAGS

ST_FLAGS Type (Enumeration)
statline.h

enum ST_FLAGS {ST_IDLE = 0, ST_BUSY = 1, ST_PAUSE = 2, ST_CLEAR = 3, ST_NORMAL = 3, ST_NOTHING = 0, ST_BATT = 1, ST_BATT_DARK = 2, ST_BATT_OK = 0, ST_BATT_LOW = 1, ST_BATT_REPLACE = 2, ST_RAD = 0, ST_DEG = 1, ST_FUNC = 0, ST_PAR = 2, ST_POL = 3, ST_SEQ = 4, ST_3D = 5, ST_DE = 6, ST_NONE = 0, ST_2ND = 1, ST_SHIFT = 2, ST_DIAMOND = 4, ST_ALPHA = 8, ST_SH_A_LOCK = 16, ST_A_LOCK = 32, ST_AUTO = 0, ST_EXACT = 1, ST_APPROX = 2};

An enumeration containing codes of status line indicators.

ST_FLAGS is an enumeration which contains codes of various modes which are possible to set into the status line using various functions defined in the statline.h header file.

Some of these values (like ST_BATT_DARK) are deprecated, and they are included only for backwards compatibility.


ST_PROGRESS_BAR

ST_PROGRESS_BAR Type (Structure)
AMS 2.00 or higher statline.h

typedef struct {
WINDOW *w; /* parent window */
WIN_RECT rect; /* scroll bar area */
long value; /* current progress */
long low, high; /* minimum and maximum values for progress */
long logwidth; /* equal to high-low */
short physwidth; /* equal to rect.x1-rect.x0+1 */
} ST_PROGRESS_BAR;

A structure describing a progress bar.

ST_PROGRESS_BAR describes a progress bar, which is used with the following functions: ST_progressBar, ST_progressDismiss, ST_progressIncrement, ST_progressUpdate.

You do not need to fill the structure by hand; this is done automatically by ST_progressBar. In addition to this, this function already draws the outline of the progress bar.
However, if you want to fill an ST_PROGRESS_BAR structure by hand, you can do it easily:

  • w is a pointer to the window in which you want to display the progress bar. This window has to be initialized with WinOpen before you use it. Of course, you can use DeskTop as well.
  • rect is the structure that represents the rectangle where the progress bar will be on the screen. Note that the coordinates have to be in the right order (i.e. xmin as rect.x0, xmax as rect.x1).
  • value represents the current progress of the task. It must be between low and high.
  • low is the minimum value for value. That is to say, if value is equal to low, the progress bar is empty.
  • high is the maximum value for value. If value is equal to high the progress bar is filled completely. Of course, high must always be greater than low.
  • logwidth must be equal to high - low.
  • physwidth is the length in pixels of the progress bar on the screen. It must be equal to rect.x1 - rect.x0 + 1.
Beware that the functions dealing with progress bars are very slow. They take more than 20 ms, that is to say half of the time between two timer ticks. You can go up to a bit less than 1 second when a progress bar taking the full screen of the 92+ is filled. Filling the screen pixel by pixel with a double loop using logical operations with masks, or better, bit operations, is up to about 10 times faster...

So it is not a good idea to use these functions if you want to clock the process whose progress is represented by the bar. Take a look at the "Progress Bar" example for an implementation demonstrating this pitfall:
// Progress bar example for TIGCC

// Define this to display the progress bar in a (large) window
//#define USE_WINDOW_PB

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

#define MIN_AMS 200           // Compile for AMS 2.00 or higher

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

// Main Function
void _main(void)
{
  short j;

#ifdef USE_WINDOW_PB
  ST_PROGRESS_BAR spb = {NULL, {0, 0, 0, 0}, 0, 0, 100, 100, 0};
  WINDOW w;
  memcpy (&(spb.rect), ScrToWin (ScrRect), sizeof (WIN_RECT));
  spb.physwidth = spb.rect.x1 - spb.rect.x0 + 1;
  WinOpen (&w, &(spb.rect), WF_SAVE_SCR | WF_NOBORDER);
  spb.w = &w;
#else
  ST_PROGRESS_BAR spb;
  ST_progressBar (&spb, 0, 100); // Create the progress bar in spb. low=0, high=100.
                                 // It will be created in the status line.
#endif

  for (j = 0; j < 20; j++)
    {
      OSFreeTimer (USER_TIMER);
      OSRegisterTimer (USER_TIMER, 1);
      while (!OSTimerExpired (USER_TIMER)); // Wait a little...
      ST_progressIncrement (&spb, 1); // Increment the progress bar by 1/100.
    }
  ST_progressUpdate (&spb, 50); // Increment the progress bar up to 50/100.
  OSFreeTimer (USER_TIMER);
  OSRegisterTimer (USER_TIMER, 20);
  while (!OSTimerExpired (USER_TIMER)); // Wait for about 1 second...
  OSFreeTimer (USER_TIMER);
  ST_progressUpdate (&spb, 100); // Fill the progress bar entirely.

  GKeyIn (NULL, 0);
  ST_progressDismiss (&spb); // Remove the progress bar, redraw status line.
#ifdef USE_WINDOW_PB
  WinClose (&w);
#endif
}


stats.h

stats.h Header File
Header File Index

Routines for working with statistics.

Functions
QstatRcl
Tells if VarRecall can be used to read the stat variables.
statEnd
Tells the system that the program is no more working on the stat variables.
statFree
Frees the stat variables (including regeq and regcoef) if they exist.
statStart
Creates stat vars and sets them to invalid values.
Global Variables
RM_Type
Global variable that specifies the type of the current stat operation.
Predefined Types
RegModelTypes
An enumeration for describing the different types of the current stat operation. [Explanation] This enum describes the correct values for RM_Type.


QstatRcl

QstatRcl Function (ROM Call 0x40B)
AMS 2.00 or higher stats.h

short QstatRcl (void);

Tells if VarRecall can be used to read the stat variables.

It returns TRUE if the stat variables are valid, FALSE otherwise.

See also: statEnd, statStart, statFree, VarRecall


statEnd

statEnd Function (ROM Call 0x409)
AMS 2.00 or higher stats.h

void statEnd (void);

Tells the system that the program is no more working on the stat variables.

This function must be called when the work on the stat variables is finished.


statFree

statFree Function (ROM Call 0x40A)
AMS 2.00 or higher stats.h

void statFree (void);

Frees the stat variables (including regeq and regcoef) if they exist.

This function may set the dirty flag for the graph (this will force a regraph when the grapher is activated).

Uses: CheckGraphRef, GetSysGraphRef, HeapFree, gr_active, gr_other, DerefSym, ResetSymFlags, SymFindMain
Used by: spike_geo_titles, spike_optionD, statStart, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_newdata, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_sinreg, cmd_twovar, FolderCur, FolderDel, HSymDel, SymDel, VarStore


statStart

statStart Function (ROM Call 0x408)
AMS 2.00 or higher stats.h

void statStart (void);

Creates stat vars and sets them to invalid values.

This function must be called prior to any modifications to the stat variables:

statStart(); // Creates and initializes the stat vars to invalid values.
RM_Type = ... // set to the type you want, see RM_Type
// do calculations
// store to stat vars with VarStore
statEnd(); // tell the system we are no more working on the stat variables...
statStart can throw 'Error: Memory'.

Uses: statFree, HeapAllocThrow
Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_sinreg, cmd_twovar


RM_Type

RM_Type Variable (ROM Call 0x5DC)
AMS 2.04 or higher stats.h

unsigned char RM_Type;

Global variable that specifies the type of the current stat operation.

Valid values for RM_Type are described in enum RegModelTypes.

Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_showstat, cmd_sinreg, cmd_twovar


RegModelTypes

RegModelTypes Type (Enumeration)
stats.h

enum RegModelTypes {
RM_NONE, RM_MEDMED, RM_LIN, RM_LN, RM_EXP, RM_POWER, RM_QUAD, RM_CUBIC, RM_QUART, RM_LOGISTIC, RM_SIN
};

An enumeration for describing the different types of the current stat operation.

This enum describes the correct values for RM_Type.


stdarg.h

stdarg.h Header File
Header File Index

ANSI routines for creating functions with variable numbers of arguments

Functions
va_arg
Returns the current argument in the list.
va_end
va_end helps the called function perform a normal return.
va_start
Initializes a pointer to a variable argument list.
Predefined Types
va_list
A void pointer which can be interpreted as an argument list.


va_arg

va_arg Function (Macro)
stdarg.h

type va_arg (va_list &ap, type);

Returns the current argument in the list.

This function (also implemented as a macro) expands to an expression that has the same type and value as the next argument being passed (one of the variable arguments). The variable ap to va_arg should be the same ap that va_start initialized. Because of default promotions, you can't use char or unsigned char types with va_arg.

The first time va_arg is used, it returns the first argument in the list. Each successive time va_arg is used, it returns the next argument in the list. It does this by first dereferencing ap, and then incrementing ap to point to the following item.

va_arg uses the parameter type (which must be an expected type name) to both perform the dereference and to locate the following item. Each successive time va_arg is invoked, it modifies ap to point to the next argument in the list.


va_end

va_end Function (Macro)
stdarg.h

void va_end (va_list &ap);

va_end helps the called function perform a normal return.

va_end might modify ap in such a way that it cannot be used unless va_start is recalled. va_end should be called after va_arg has read all the arguments.

Note: va_end is introduced here only to increase compatibility with ANSI C. In this implementation, va_end in fact does nothing.


va_start

va_start Function (Macro)
stdarg.h

void va_start (va_list &ap, &lastfix);

Initializes a pointer to a variable argument list.

Some C functions, such as sprintf have a variable number of arguments. This function, together with va_arg and va_end, provides a portable way to access these argument lists. They are used for stepping through a list of arguments when the called function does not know the number and types of the arguments being passed. Function va_start (implemented as a macro) sets ap to point to the first of the variable arguments being passed to the function. It must be used before the first call to va_arg or va_end.

va_start takes two parameters: ap and lastfix. ap is explained above, and lastfix is the name of the last fixed parameter being passed to the called function.

Note: I used notation "&ap" in the prototype description, although passing by reference does not exist in ordinary C (only in C++). However, this macro is implemented in such a way that it simulates "passing by reference".


va_list

va_list Type (Pointer)
stdarg.h, stdio.h

typedef void *va_list;

A void pointer which can be interpreted as an argument list.

va_list is the type of the void pointer passed to one of the functions that accepts a pointer to a list of arguments. This array holds information needed by va_arg and va_end.


stdbool.h

stdbool.h Header File
Header File Index

ISO C99 definitions of boolean type and values

This headers defines false (a macro expanding to integer value 0), true (a macro expanding to integer value 1) and bool (a macro expanding to the _Bool C keyword).


stddef.h

stddef.h Header File
Header File Index

ANSI definitions of default macros and types

Functions
offsetof
Returns the offset of a member in a structure.
Constants
NULL
A null-pointer value.
Predefined Types
ptrdiff_t
A type to define the result of subtracting two pointers. [Explanation] ptrdiff_t is a type proposed by ANSI C for defining the result of subtracting two pointers (e.g. the first address after the end of an array minus the beginning of the array).
size_t
A type to define sizes of strings and memory blocks.


offsetof

offsetof Function (Macro)
stddef.h

#define offsetof(type,member) ((unsigned long) &(((type*)0)->member))

Returns the offset of a member in a structure.

offsetof is a macro which returns the offset of a member in a structure type. The type can either be defined through typedef, or preceded by struct, as usual.

Deprecated alias: OFFSETOF

See also: sizeof, typeof


ptrdiff_t

ptrdiff_t Type (Scalar)
stddef.h

typedef long ptrdiff_t;

A type to define the result of subtracting two pointers.

ptrdiff_t is a type proposed by ANSI C for defining the result of subtracting two pointers (e.g. the first address after the end of an array minus the beginning of the array).


stdint.h

stdint.h Header File
Header File Index

C99-compatible integer types with a fixed size in bits

Functions
INT16_C
Appends the correct suffix to a 16-bit signed integer literal.
INT32_C
Appends the correct suffix to a 32-bit signed integer literal.
INT64_C
Appends the correct suffix to a 64-bit signed integer literal.
INT8_C
Appends the correct suffix to an 8-bit signed integer literal.
INTMAX_C
Appends the correct suffix to a maximally-sized signed integer literal.
UINT16_C
Appends the correct suffix to a 16-bit unsigned integer literal.
UINT32_C
Appends the correct suffix to a 32-bit unsigned integer literal.
UINT64_C
Appends the correct suffix to a 64-bit unsigned integer literal.
UINT8_C
Appends the correct suffix to an 8-bit unsigned integer literal.
UINTMAX_C
Appends the correct suffix to a maximally-sized unsigned integer literal.
Constants
INT_FAST16_MAX
Maximum value of our int_fast16_t type.
INT_FAST16_MIN
Minimum value of our int_fast16_t type.
INT_FAST32_MAX
Maximum value of our int_fast32_t type.
INT_FAST32_MIN
Minimum value of our int_fast32_t type.
INT_FAST64_MAX
Maximum value of our int_fast64_t type.
INT_FAST64_MIN
Minimum value of our int_fast64_t type.
INT_FAST8_MAX
Maximum value of our int_fast8_t type.
INT_FAST8_MIN
Minimum value of our int_fast8_t type.
INT_LEAST16_MAX
Maximum value of our int_least16_t type.
INT_LEAST16_MIN
Minimum value of our int_least16_t type.
INT_LEAST32_MAX
Maximum value of our int_least32_t type.
INT_LEAST32_MIN
Minimum value of our int_least32_t type.
INT_LEAST64_MAX
Maximum value of our int_least64_t type.
INT_LEAST64_MIN
Minimum value of our int_least64_t type.
INT_LEAST8_MAX
Maximum value of our int_least8_t type.
INT_LEAST8_MIN
Minimum value of our int_least8_t type.
INT16_MAX
Maximum value of a signed 16-bit integer.
INT16_MIN
Minimum value of a signed 16-bit integer.
INT32_MAX
Maximum value of a signed 32-bit integer.
INT32_MIN
Minimum value of a signed 32-bit integer.
INT64_MAX
Maximum value of a signed 64-bit integer.
INT64_MIN
Minimum value of a signed 64-bit integer.
INT8_MAX
Maximum value of a signed 8-bit integer.
INT8_MIN
Minimum value of a signed 8-bit integer.
INTMAX_MAX
Maximum value of our intmax_t type.
INTMAX_MIN
Minimum value of our intmax_t type.
INTPTR_MAX
Maximum value of our intptr_t type.
INTPTR_MIN
Minimum value of our intptr_t type.
PTRDIFF_MAX
Largest positive value of a ptrdiff_t integer.
PTRDIFF_MIN
Largest negative value of a ptrdiff_t integer.
SIZE_MAX
Maximum value of a size_t integer.
UINT_FAST16_MAX
Maximum value of our uint_fast16_t type.
UINT_FAST32_MAX
Maximum value of our uint_fast32_t type.
UINT_FAST64_MAX
Maximum value of our uint_fast64_t type.
UINT_FAST8_MAX
Maximum value of our uint_fast8_t type.
UINT_LEAST16_MAX
Maximum value of our uint_least16_t type.
UINT_LEAST32_MAX
Maximum value of our uint_least32_t type.
UINT_LEAST64_MAX
Maximum value of our uint_least64_t type.
UINT_LEAST8_MAX
Maximum value of our uint_least8_t type.
UINT16_MAX
Maximum value of an unsigned 16-bit integer.
UINT32_MAX
Maximum value of an unsigned 32-bit integer.
UINT64_MAX
Maximum value of an unsigned 64-bit integer.
UINT8_MAX
Maximum value of an unsigned 8-bit integer.
UINTMAX_MAX
Maximum value of our uintmax_t type.
UINTPTR_MAX
Maximum value of our uintptr_t type.
Predefined Types
int_fast16_t
The fastest signed type with at least 16 bits (specified by C99).
int_fast32_t
The fastest signed type with at least 32 bits (specified by C99).
int_fast64_t
The fastest signed type with at least 64 bits (specified by C99).
int_fast8_t
The fastest signed type with at least 8 bits (specified by C99).
int_least16_t
A signed type with at least 16 bits (specified by C99).
int_least32_t
A signed type with at least 32 bits (specified by C99).
int_least64_t
A signed type with at least 64 bits (specified by C99).
int_least8_t
A signed type with at least 8 bits (specified by C99).
int16_t
A 16-bit signed fixed-width type specified by C99.
int32_t
A 32-bit signed fixed-width type specified by C99.
int64_t
A 64-bit signed fixed-width type specified by C99.
int8_t
An 8-bit signed fixed-width type specified by C99.
intmax_t
The largest signed integer on this platform (specified by C99).
intptr_t
A signed integer large enough to hold a void* pointer (specified by C99).
uint_fast16_t
The fastest unsigned type with at least 16 bits (specified by C99).
uint_fast32_t
The fastest unsigned type with at least 32 bits (specified by C99).
uint_fast64_t
The fastest unsigned type with at least 64 bits (specified by C99).
uint_fast8_t
The fastest unsigned type with at least 8 bits (specified by C99).
uint_least16_t
An unsigned type with at least 16 bits (specified by C99).
uint_least32_t
An unsigned type with at least 32 bits (specified by C99).
uint_least64_t
An unsigned type with at least 64 bits (specified by C99).
uint_least8_t
An unsigned type with at least 8 bits (specified by C99).
uint16_t
A 16-bit type unsigned fixed-width type specified by C99.
uint32_t
A 32-bit type unsigned fixed-width type specified by C99.
uint64_t
A 64-bit type unsigned fixed-width type specified by C99.
uint8_t
An 8-bit type unsigned fixed-width type specified by C99.
uintmax_t
The largest unsigned integer on this platform (specified by C99).
uintptr_t
An unsigned integer large enough to hold a void* pointer (specified by C99).


INT16_C

INT16_C Function (Macro constructor)
stdint.h

#define INT16_C(c) c

Appends the correct suffix to a 16-bit signed integer literal.

This macro appends the correct suffix for a 16-bit signed integer literal to c.


INT32_C

INT32_C Function (Macro constructor)
stdint.h

#define INT32_C(c) c ## L

Appends the correct suffix to a 32-bit signed integer literal.

This macro appends the correct suffix for a 32-bit signed integer literal to c.


INT64_C

INT64_C Function (Macro constructor)
stdint.h

#define INT64_C(c) c ## LL

Appends the correct suffix to a 64-bit signed integer literal.

This macro appends the correct suffix for a 64-bit signed integer literal to c.


INT8_C

INT8_C Function (Macro constructor)
stdint.h

#define INT8_C(c) c

Appends the correct suffix to an 8-bit signed integer literal.

This macro appends the correct suffix for an 8-bit signed integer literal to c.


INTMAX_C

INTMAX_C Function (Macro constructor)
stdint.h

#define INTMAX_C(c) c ## LL

Appends the correct suffix to a maximally-sized signed integer literal.

This macro appends the correct suffix for a maximally-sized (on the GCC4TI platform) signed integer literal to c.


UINT16_C

UINT16_C Function (Macro constructor)
stdint.h

#define UINT16_C(c) c ## U

Appends the correct suffix to a 16-bit unsigned integer literal.

This macro appends the correct suffix for a 16-bit unsigned integer literal to c.


UINT32_C

UINT32_C Function (Macro constructor)
stdint.h

#define UINT32_C(c) c ## UL

Appends the correct suffix to a 32-bit unsigned integer literal.

This macro appends the correct suffix for a 32-bit unsigned integer literal to c.


UINT64_C

UINT64_C Function (Macro constructor)
stdint.h

#define UINT64_C(c) c ## ULL

Appends the correct suffix to a 64-bit unsigned integer literal.

This macro appends the correct suffix for a 64-bit unsigned integer literal to c.


UINT8_C

UINT8_C Function (Macro constructor)
stdint.h

#define UINT8_C(c) c

Appends the correct suffix to an 8-bit unsigned integer literal.

This macro appends the correct suffix for an 8-bit unsigned integer literal to c.


UINTMAX_C

UINTMAX_C Function (Macro constructor)
stdint.h

#define UINTMAX_C(c) c ## ULL

Appends the correct suffix to a maximally-sized unsigned integer literal.

This macro appends the correct suffix for a maximally-sized (on the GCC4TI platform) unsigned integer literal to c.


INT_FAST16_MAX

INT_FAST16_MAX Constant
stdint.h

#define INT_FAST16_MAX (32767)

Maximum value of our int_fast16_t type.

This is the maximum value that an int_fast16_t can contain on the GCC4TI platform.


INT_FAST16_MIN

INT_FAST16_MIN Constant
stdint.h

#define INT_FAST16_MIN (-32767-1)

Minimum value of our int_fast16_t type.

This is the minimum value that an int_fast16_t can contain on the GCC4TI platform.


INT_FAST32_MAX

INT_FAST32_MAX Constant
stdint.h

#define INT_FAST32_MAX (2147483647L)

Maximum value of our int_fast32_t type.

This is the maximum value that an int_fast32_t can contain on the GCC4TI platform.


INT_FAST32_MIN

INT_FAST32_MIN Constant
stdint.h

#define INT_FAST32_MIN (-2147483647L-1)

Minimum value of our int_fast32_t type.

This is the minimum value that an int_fast32_t can contain on the GCC4TI platform.


INT_FAST64_MAX

INT_FAST64_MAX Constant
stdint.h

#define INT_FAST64_MAX (9223372036854775807LL)

Maximum value of our int_fast64_t type.

This is the maximum value that an int_fast64_t can contain on the GCC4TI platform.


INT_FAST64_MIN

INT_FAST64_MIN Constant
stdint.h

#define INT_FAST64_MIN (-9223372036854775807LL-1)

Minimum value of our int_fast64_t type.

This is the minimum value that an int_fast64_t can contain on the GCC4TI platform.


INT_FAST8_MAX

INT_FAST8_MAX Constant
stdint.h

#define INT_FAST8_MAX (32767)

Maximum value of our int_fast8_t type.

This is the maximum value that an int_fast8_t can contain on the GCC4TI platform.


INT_FAST8_MIN

INT_FAST8_MIN Constant
stdint.h

#define INT_FAST8_MIN (-32767-1)

Minimum value of our int_fast8_t type.

This is the minimum value that an int_fast8_t can contain on the GCC4TI platform.


INT_LEAST16_MAX

INT_LEAST16_MAX Constant
stdint.h

#define INT_LEAST16_MAX (32767)

Maximum value of our int_least16_t type.

This is the maximum value that an int_least16_t can contain on the GCC4TI platform.


INT_LEAST16_MIN

INT_LEAST16_MIN Constant
stdint.h

#define INT_LEAST16_MIN (-32767-1)

Minimum value of our int_least16_t type.

This is the minimum value that an int_least16_t can contain on the GCC4TI platform.


INT_LEAST32_MAX

INT_LEAST32_MAX Constant
stdint.h

#define INT_LEAST32_MAX (2147483647L)

Maximum value of our int_least32_t type.

This is the maximum value that an int_least32_t can contain on the GCC4TI platform.


INT_LEAST32_MIN

INT_LEAST32_MIN Constant
stdint.h

#define INT_LEAST32_MIN (-2147483647L-1)

Minimum value of our int_least32_t type.

This is the minimum value that an int_least32_t can contain on the GCC4TI platform.


INT_LEAST64_MAX

INT_LEAST64_MAX Constant
stdint.h

#define INT_LEAST64_MAX (9223372036854775807LL)

Maximum value of our int_least64_t type.

This is the maximum value that an int_least64_t can contain on the GCC4TI platform.


INT_LEAST64_MIN

INT_LEAST64_MIN Constant
stdint.h

#define INT_LEAST64_MIN (-9223372036854775807LL-1)

Minimum value of our int_least64_t type.

This is the minimum value that an int_least64_t can contain on the GCC4TI platform.


INT_LEAST8_MAX

INT_LEAST8_MAX Constant
stdint.h

#define INT_LEAST8_MAX (127)

Maximum value of our int_least8_t type.

This is the maximum value that an int_least8_t can contain on the GCC4TI platform.


INT_LEAST8_MIN

INT_LEAST8_MIN Constant
stdint.h

#define INT_LEAST8_MIN (-128)

Minimum value of our int_least8_t type.

This is the minimum value that an int_least8_t can contain on the GCC4TI platform.


INT16_MAX

INT16_MAX Constant
stdint.h

#define INT16_MAX (32767)

Maximum value of a signed 16-bit integer.

This is the maximum value that a signed 16-bit integer can contain.


INT16_MIN

INT16_MIN Constant
stdint.h

#define INT16_MIN (-32767-1)

Minimum value of a signed 16-bit integer.

This is the minimum value that a signed 16-bit integer can contain.


INT32_MAX

INT32_MAX Constant
stdint.h

#define INT32_MAX (2147483647L)

Maximum value of a signed 32-bit integer.

This is the maximum value that a signed 32-bit integer can contain.


INT32_MIN

INT32_MIN Constant
stdint.h

#define INT32_MIN (-2147483647L-1)

Minimum value of a signed 32-bit integer.

This is the minimum value that a signed 32-bit integer can contain.


INT64_MAX

INT64_MAX Constant
stdint.h

#define INT64_MAX (9223372036854775807LL)

Maximum value of a signed 64-bit integer.

This is the maximum value that a signed 64-bit integer can contain.


INT64_MIN

INT64_MIN Constant
stdint.h

#define INT64_MIN (-9223372036854775807LL-1)

Minimum value of a signed 64-bit integer.

This is the minimum value that a signed 64-bit integer can contain.


INT8_MAX

INT8_MAX Constant
stdint.h

#define INT8_MAX (127)

Maximum value of a signed 8-bit integer.

This is the maximum value that a signed 8-bit integer can contain.


INT8_MIN

INT8_MIN Constant
stdint.h

#define INT8_MIN (-128)

Minimum value of a signed 8-bit integer.

This is the minimum value that a signed 8-bit integer can contain.


INTMAX_MAX

INTMAX_MAX Constant
stdint.h

#define INTMAX_MAX (9223372036854775807LL)

Maximum value of our intmax_t type.

This is the maximum value that the largest signed integer can contain on the GCC4TI platform.


INTMAX_MIN

INTMAX_MIN Constant
stdint.h

#define INTMAX_MIN (-9223372036854775807LL-1)

Minimum value of our intmax_t type.

This is the minimum value that the largest signed integer can contain on the GCC4TI platform.


INTPTR_MAX

INTPTR_MAX Constant
stdint.h

#define INTPTR_MAX (2147483647L)

Maximum value of our intptr_t type.

This is the maximum value that a signed integer large enough to hold a pointer can contain on the GCC4TI platform.


INTPTR_MIN

INTPTR_MIN Constant
stdint.h

#define INTPTR_MIN (-2147483647L-1)

Minimum value of our intptr_t type.

This is the minimum value that a signed integer large enough to hold a pointer can contain on the GCC4TI platform.


PTRDIFF_MAX

PTRDIFF_MAX Constant
stdint.h

#define PTRDIFF_MAX (16777215L)

Largest positive value of a ptrdiff_t integer.

This is the largest meaningful positive value that a variable of ptrdiff_t type can contain on the TI-68k platform, due to the 24-bit addressing space of the 68000.


PTRDIFF_MIN

PTRDIFF_MIN Constant
stdint.h

#define PTRDIFF_MIN (-16777215L)

Largest negative value of a ptrdiff_t integer.

This is the largest meaningful negative value that a variable of ptrdiff_t type can contain on the TI-68k platform, due to the 24-bit addressing space of the 68000.


SIZE_MAX

SIZE_MAX Constant
stdint.h

#define SIZE_MAX (16777215UL)

Maximum value of a size_t integer.

This is the largest meaningful value that a variable of size_t type can contain on the TI-68k platform, due to the 24-bit addressing space of the 68000.


UINT_FAST16_MAX

UINT_FAST16_MAX Constant
stdint.h

#define UINT_FAST16_MAX (65535U)

Maximum value of our uint_fast16_t type.

This is the maximum value that an uint_fast16_t can contain on the GCC4TI platform.


UINT_FAST32_MAX

UINT_FAST32_MAX Constant
stdint.h

#define UINT_FAST32_MAX (4294967295UL)

Maximum value of our uint_fast32_t type.

This is the maximum value that an uint_fast32_t can contain on the GCC4TI platform.


UINT_FAST64_MAX

UINT_FAST64_MAX Constant
stdint.h

#define UINT_FAST64_MAX (18446744073709551615ULL)

Maximum value of our uint_fast64_t type.

This is the maximum value that an uint_fast64_t can contain on the GCC4TI platform.


UINT_FAST8_MAX

UINT_FAST8_MAX Constant
stdint.h

#define UINT_FAST8_MAX (65535U)

Maximum value of our uint_fast8_t type.

This is the maximum value that an uint_fast8_t can contain on the GCC4TI platform.


UINT_LEAST16_MAX

UINT_LEAST16_MAX Constant
stdint.h

#define UINT_LEAST16_MAX (65535U)

Maximum value of our uint_least16_t type.

This is the maximum value that a uint_least16_t can contain on the GCC4TI platform.


UINT_LEAST32_MAX

UINT_LEAST32_MAX Constant
stdint.h

#define UINT_LEAST32_MAX (4294967295UL)

Maximum value of our uint_least32_t type.

This is the maximum value that a uint_least32_t can contain on the GCC4TI platform.


UINT_LEAST64_MAX

UINT_LEAST64_MAX Constant
stdint.h

#define UINT_LEAST64_MAX (18446744073709551615ULL)

Maximum value of our uint_least64_t type.

This is the maximum value that a uint_least64_t can contain on the GCC4TI platform.


UINT_LEAST8_MAX

UINT_LEAST8_MAX Constant
stdint.h

#define UINT_LEAST8_MAX (255)

Maximum value of our uint_least8_t type.

This is the maximum value that a uint_least8_t can contain on the GCC4TI platform.


UINT16_MAX

UINT16_MAX Constant
stdint.h

#define UINT16_MAX (65535U)

Maximum value of an unsigned 16-bit integer.

This is the maximum value that an unsigned 16-bit integer can contain.


UINT32_MAX

UINT32_MAX Constant
stdint.h

#define UINT32_MAX (4294967295UL)

Maximum value of an unsigned 32-bit integer.

This is the maximum value that an unsigned 32-bit integer can contain.


UINT64_MAX

UINT64_MAX Constant
stdint.h

#define UINT64_MAX (18446744073709551615ULL)

Maximum value of an unsigned 64-bit integer.

This is the maximum value that an unsigned 64-bit integer can contain.


UINT8_MAX

UINT8_MAX Constant
stdint.h

#define UINT8_MAX (255)

Maximum value of an unsigned 8-bit integer.

This is the maximum value that an unsigned 8-bit integer can contain.


UINTMAX_MAX

UINTMAX_MAX Constant
stdint.h

#define UINTMAX_MAX (18446744073709551615ULL)

Maximum value of our uintmax_t type.

This is the maximum value that the largest unsigned integer can contain on the GCC4TI platform.


UINTPTR_MAX

UINTPTR_MAX Constant
stdint.h

#define UINTPTR_MAX (4294967295UL)

Maximum value of our uintptr_t type.

This is the maximum value that an unsigned integer large enough to hold a pointer can contain on the GCC4TI platform.


int_fast16_t

int_fast16_t Type (Scalar)
stdint.h

typedef short int_fast16_t;

The fastest signed type with at least 16 bits (specified by C99).

This type can be used when at least 16 bits of signed data storage are wanted, and speed is more of a concern than size. In GCC4TI, its size is exactly 16 bits.


int_fast32_t

int_fast32_t Type (Scalar)
stdint.h

typedef long int_fast32_t;

The fastest signed type with at least 32 bits (specified by C99).

This type can be used when at least 32 bits of signed data storage are wanted, and speed is more of a concern than size. In GCC4TI, its size is exactly 32 bits.


int_fast64_t

int_fast64_t Type (Scalar)
stdint.h

typedef long long int_fast64_t;

The fastest signed type with at least 64 bits (specified by C99).

This type can be used when at least 64 bits of signed data storage are wanted, and speed is more of a concern than size. In GCC4TI, its size is exactly 64 bits.


int_fast8_t

int_fast8_t Type (Scalar)
stdint.h

typedef short int_fast8_t;

The fastest signed type with at least 8 bits (specified by C99).

This type can be used when at least 8 bits of signed data storage are wanted, and speed is more of a concern than size. In GCC4TI, its size is 16 bits.


int_least16_t

int_least16_t Type (Scalar)
stdint.h

typedef short int int_least16_t;

A signed type with at least 16 bits (specified by C99).

This type can be used when at least 16 bits of signed data storage are wanted. In GCC4TI, its size is exactly 16 bits.


int_least32_t

int_least32_t Type (Scalar)
stdint.h

typedef long int_least32_t;

A signed type with at least 32 bits (specified by C99).

This type can be used when at least 32 bits of signed data storage are wanted. In GCC4TI, its size is exactly 32 bits.


int_least64_t

int_least64_t Type (Scalar)
stdint.h

typedef long long int int_least64_t;

A signed type with at least 64 bits (specified by C99).

This type can be used when at least 64 bits of signed data storage are wanted. In GCC4TI, its size is exactly 64 bits.


int_least8_t

int_least8_t Type (Scalar)
stdint.h

typedef signed char int_least8_t;

A signed type with at least 8 bits (specified by C99).

This type can be used when at least 8 bits of signed data storage are wanted. In GCC4TI, its size is exactly 8 bits.


int16_t

int16_t Type (Scalar)
stdint.h

typedef short int16_t;

A 16-bit signed fixed-width type specified by C99.

This type can be used when exactly 16 bits of signed data storage are wanted.


int32_t

int32_t Type (Scalar)
stdint.h

typedef long int32_t;

A 32-bit signed fixed-width type specified by C99.

This type can be used when exactly 32 bits of signed data storage are wanted.


int64_t

int64_t Type (Scalar)
stdint.h

typedef long long int64_t;

A 64-bit signed fixed-width type specified by C99.

This type can be used when exactly 64 bits of signed data storage are wanted.


int8_t

int8_t Type (Scalar)
stdint.h

typedef signed char int8_t;

An 8-bit signed fixed-width type specified by C99.

This type can be used when exactly 8 bits of signed data storage are wanted.


intmax_t

intmax_t Type (Scalar)
stdint.h

typedef long long intmax_t;

The largest signed integer on this platform (specified by C99).

This type can be used when one wants the widest possible signed integer on the platform. In GCC4TI, this type is exactly 64 bits.


intptr_t

intptr_t Type (Scalar)
stdint.h

typedef long intptr_t;

A signed integer large enough to hold a void* pointer (specified by C99).

This type can be used when one wants to store a pointer value in a signed integer.


uint_fast16_t

uint_fast16_t Type (Scalar)
stdint.h

typedef unsigned short uint_fast16_t;

The fastest unsigned type with at least 16 bits (specified by C99).

This type can be used when at least 16 bits of unsigned data storage are wanted, and speed is more of a concern than size. In GCC4TI, its size is exactly 16 bits.


uint_fast32_t

uint_fast32_t Type (Scalar)
stdint.h

typedef unsigned long uint_fast32_t;

The fastest unsigned type with at least 32 bits (specified by C99).

This type can be used when at least 32 bits of unsigned data storage are wanted, and speed is more of a concern than size. In GCC4TI, its size is exactly 32 bits.


uint_fast64_t

uint_fast64_t Type (Scalar)
stdint.h

typedef unsigned long long uint_fast64_t;

The fastest unsigned type with at least 64 bits (specified by C99).

This type can be used when at least 64 bits of unsigned data storage are wanted, and speed is more of a concern than size. In GCC4TI, its size is exactly 64 bits.


uint_fast8_t

uint_fast8_t Type (Scalar)
stdint.h

typedef unsigned short uint_fast8_t;

The fastest unsigned type with at least 8 bits (specified by C99).

This type can be used when at least 8 bits of unsigned data storage are wanted, and speed is more of a concern than size. In GCC4TI, its size is 16 bits.


uint_least16_t

uint_least16_t Type (Scalar)
stdint.h

typedef unsigned short uint_least16_t;

An unsigned type with at least 16 bits (specified by C99).

This type can be used when at least 16 bits of unsigned data storage are wanted. In GCC4TI, its size is exactly 16 bits.


uint_least32_t

uint_least32_t Type (Scalar)
stdint.h

typedef unsigned long uint_least32_t;

An unsigned type with at least 32 bits (specified by C99).

This type can be used when at least 32 bits of unsigned data storage are wanted. In GCC4TI, its size is exactly 32 bits.


uint_least64_t

uint_least64_t Type (Scalar)
stdint.h

typedef unsigned long long uint_least64_t;

An unsigned type with at least 64 bits (specified by C99).

This type can be used when at least 64 bits of unsigned data storage are wanted. In GCC4TI, its size is exactly 64 bits.


uint_least8_t

uint_least8_t Type (Scalar)
stdint.h

typedef unsigned char uint_least8_t;

An unsigned type with at least 8 bits (specified by C99).

This type can be used when at least 8 bits of unsigned data storage are wanted. In GCC4TI, its size is exactly 8 bits.


uint16_t

uint16_t Type (Scalar)
stdint.h

typedef unsigned short uint16_t;

A 16-bit type unsigned fixed-width type specified by C99.

This type can be used when exactly 16 bits of unsigned data storage are wanted.


uint32_t

uint32_t Type (Scalar)
stdint.h

typedef unsigned long uint32_t;

A 32-bit type unsigned fixed-width type specified by C99.

This type can be used when exactly 32 bits of unsigned data storage are wanted.


uint64_t

uint64_t Type (Scalar)
stdint.h

typedef unsigned long long uint64_t;

A 64-bit type unsigned fixed-width type specified by C99.

This type can be used when exactly 64 bits of unsigned data storage are wanted.


uint8_t

uint8_t Type (Scalar)
stdint.h

typedef unsigned char uint8_t;

An 8-bit type unsigned fixed-width type specified by C99.

This type can be used when exactly 8 bits of unsigned data storage are wanted.


uintmax_t

uintmax_t Type (Scalar)
stdint.h

typedef unsigned long long uintmax_t;

The largest unsigned integer on this platform (specified by C99).

This type can be used when one wants the widest possible unsigned integer on the platform. In GCC4TI, this type is exactly 64 bits.


uintptr_t

uintptr_t Type (Scalar)
stdint.h

typedef unsigned long uintptr_t;

An unsigned integer large enough to hold a void* pointer (specified by C99).

This type can be used when one wants to store a pointer value in an unsigned integer.


stdio.h

stdio.h Header File
Header File Index

ANSI-compatible file and TTY input/output routines

Functions
cbprintf
Callback printing function.
cbscanf
Callback parsing function.
clearerr
Resets error indication.
clrscr
Clears the screen and resets the print position.
fclose
Closes a stream.
feof
Tests a stream for an end-of-file indicator.
ferror
Tests a stream for a read or write error.
fflush
Flushes a stream.
fgetc
Function version of fgetc.
fgetchar
Function version of getchar.
fgetpos
Gets the current file pointer position.
fgets
Gets a string from a stream.
fopen
Opens a stream.
fprintf
Sends formatted output to a stream.
fputc
Function version of fputc.
fputchar
Function version of putchar.
fputs
Outputs a string to a stream.
fread
Reads data from a stream.
freopen
Associates a new file with an open stream.
fscanf
File parsing function.
fseek
Repositions the file pointer of a stream.
fsetbufsize
Sets the buffer size of a file.
fsetpos
Positions the file pointer of a stream.
ftell
Returns the current file pointer.
fwrite
Writes data to a stream.
getc
Gets a character from a stream.
getchar
Gets a character from the keyboard (with echoing to the screen).
gets
Gets a string from the keyboard.
getsn
Gets a string from the keyboard avoiding buffer overflows.
printf_xy
Sends formatted output to the fixed place on the screen.
printf
Sends formatted output to the screen.
putc
Writes a character to a stream.
putchar
Outputs a character to the screen in TTY mode.
puts
Outputs a string to the screen in TTY mode.
remove
Macro that removes a file.
rename
Renames a file.
rewind
Repositions file pointer to stream's beginning.
scanf
Console input parsing function.
snprintf
Sends formatted output, up to a given length, to a string.
sprintf
Sends formatted output to a string.
sscanf
String parsing function.
strerror
Gives an error message string.
strputchar
Default vcbprintf callback function used in sprintf.
tmpnam
Produces a unique random file name.
ungetc
Pushes a character back into input stream.
unlink
Deletes a file.
vcbprintf
Virtual callback printing function.
vcbscanf
Virtual callback parsing function.
vfprintf
Sends formatted output to a stream using argument list.
vfscanf
File parsing function using argument list.
vprintf
Sends formatted output to the screen using argument list.
vscanf
Console input parsing function using argument list.
vsnprintf
Sends formatted output, up to a given length, to a string, using argument list.
vsprintf
Sends formatted output to a string using argument list.
vsscanf
String parsing function using argument list.
Constants
EOF
Indicates that the end of a file has been reached.
NULL
A null-pointer value.
TMP_MAX
Contains the maximum number of temporary file names.
Predefined Types
FILE
A structure describing an opened file.
FileFlags
An enumeration describing internal flags for file handling.
fpos_t
A type describing the current position in a file.
SeekModes
An enumeration for describing possible modes used in fseek.
size_t
A type to define sizes of strings and memory blocks.
va_list
A void pointer which can be interpreted as an argument list.
vcbprintf_Callback_t
Describes a callback function for vcbprintf.
vcbscanf_get_Callback_t
Describes the first callback function for vcbscanf.
vcbscanf_unget_Callback_t
Describes the second callback function for vcbscanf.

Note: This implementation of stdio.h is 90% compatible with the ANSI standard. I tried to make all functions to be as close to ANSI as possible, without introducing a too large overload in the generated code. The main difference is the fact that there are no terminal-associated file streams like stdin and stdout which may be redirected. However, functions from this header file are mostly not TIOS functions - they are completely written by us, so they are not embedded in the TIOS. That's why their use may cause your program to be larger than if you don't use functions from this header file. The typical increase in size is 300-2000 bytes, depending on which functions and how many different functions from this header file are used in the program. Functions from the scanf family are the worst offenders, using any of them takes about 1500 bytes. So, although functions from this header file are much more "standard" than TIOS-specific functions, it is better to avoid functions like fopen etc. Instead, use "non-standard" functions from the vat.h header file. Also avoid using scanf family functions if you don't really have to. Prefer getsn for input, and atoi family functions for parsing. Of course, functions from this header file may be very useful for porting a program from a "standard" computer to the TI. But I will repeat again: it is better to avoid them.


cbprintf

cbprintf Function (tigcc.a)
stdio.h

void cbprintf (vcbprintf_Callback_t callback, void **param, const char *format, ...);

Callback printing function.

cbprintf is an alternate entry point to the vcbprintf function. The difference is that the argument is passed directly through the stack instead of through an argument list pointer.

It is implemented here as an assembly wrapper which calls vcbprintf.

Uses: vcbprintf


cbscanf

cbscanf Function* (tigcc.a)
stdio.h

short cbscanf(vcbscanf_get_Callback_t getfun, vcbscanf_unget_Callback_t ungetfun, void *param, const char *format, ...);

Callback parsing function.

cbscanf is an alternate entry point to the vcbscanf function. The difference is that the argument is passed directly through the stack instead of through an argument list pointer.

Used by: fscanf, sscanf


clearerr

clearerr Function (Macro)
stdio.h

void clearerr (FILE *stream);

Resets error indication.

clearerr resets the error and end-of-file indicators of the stream associated to the structure pointed to by stream to 0. Once the error indicator is set, stream operations continue to return error status until a call is made to clearerr or rewind.


clrscr

clrscr Function (tigcc.a)
stdio.h

void clrscr (void);

Clears the screen and resets the print position.

Function clrscr is very similar to stantard TIOS function ClrScr (defined in graph.h header file). The difference is in fact that clrscr moves the current print/plot position to (0, 0), but with ClrScr the current print/plot position remains intact. More precise, clrscr calls ClrScr then MoveTo passing two zeros as arguments. Always use clrscr instead of ClrScr if you want to use TTY printing functions like puts, printf etc.

Uses: ClrScr, MoveTo


fclose

fclose Function (tigcc.a)
stdio.h

short fclose (FILE *stream);

Closes a stream.

fclose closes the stream associated to the structure pointed to by stream. In this implementation, fclose unlocks the file (which is locked during it is opened), and frees the file descriptor structure pointed to by stream. fclose returns 0 on success. It returns EOF if any errors were detected.

Uses: HeapRealloc, HeapUnlock
Used by: freopen


feof

feof Function (Macro)
stdio.h

short feof (FILE *stream);

Tests a stream for an end-of-file indicator.

feof is a macro that tests the stream associated to the structure pointed to by stream for an end-of-file indicator. Once the indicator is set, read operations on the file return the indicator until fseek, fsetpos or rewind is called, or until the stream is closed. feof returns nonzero if an end-of-file indicator was detected on the last (usually input) operation on the given stream. It returns 0 if end-of-file has not been reached.

Used by: fgetc, fputc


ferror

ferror Function (Macro)
stdio.h

short ferror (FILE *stream);

Tests a stream for a read or write error.

ferror is a macro that tests the stream associated to the structure pointed to by stream for a read or write error. It the stream's error indicator has been set, it remains set (and all file I/O operations will return error) until clearerr or rewind is called, or until the stream is closed. ferror returns nonzero if an error was detected on the named stream.


fflush

fflush Function (Macro)
stdio.h

short fflush (FILE *stream);

Flushes a stream.

fflush is supposed to flush the output buffer for stream to the associated file if the given stream has buffered output. As the TI file system is not buffered (of course), fflush has no effect, except for undoing the effect of the ungetc function. fflush returns 0 on success (which is always the case on the TI).


fgetc

fgetc Function (tigcc.a)
stdio.h

short fgetc (FILE *stream);

Function version of fgetc.

fgetc is usually equal to getc, except fgetc is implemented as a function, but getc is implemented as a macro.

Uses: feof
Used by: fgets, fread, fscanf, getc, vfscanf


fgetchar

fgetchar Function (tigcc.a)
stdio.h

short fgetchar (void);

Function version of getchar.

fgetchar is equal to getchar, except fgetchar is implemented as a function, but getchar is implemented as a macro.

Uses: fputchar, EV_captureEvents, EV_defaultHandler, DrawClipChar, MoveTo, SaveScrState, ngetchx
Used by: getchar


fgetpos

fgetpos Function (Macro)
stdio.h

short fgetpos (FILE *stream, fpos_t *pos);

Gets the current file pointer position.

fgetpos stores the position of the file pointer associated with the stream associated with the structure pointed to by stream in the location pointed to by pos The exact value is irrelevant. On success, fgetpos returns 0. On failure, it returns a nonzero value.

Note: fgetpos is implemented here as a macro which calls ftell.

Uses: ftell


fgets

fgets Function (tigcc.a)
stdio.h

char *fgets (char *s, short n, FILE *stream);

Gets a string from a stream.

fgets reads characters from stream associated to the structure pointed to by stream into the string s. It does this by calling fgetc repeatedly. The function stops reading when it reads either n - 1 characters or a '\r' (0x0D) character, whichever comes first. fgets retains the newline character at the end of s, eventually translated to '\n' character if the stream is opened in "text" mode (see fopen). A null byte is appended to s to mark the end of the string. On success, fgets returns the string pointed to by s. It returns NULL in a case of error.

Note: fgets is used mainly with files opened in "text" mode. As an example, this command may be useful for reading a text line from a TEXT variable.

Uses: fgetc


fopen

fopen Function (tigcc.a)
stdio.h

FILE *fopen (const char *filename, const char *mode);

Opens a stream.

fopen opens the file named by filename (this is a normal C string, which should be in lowercase) and associates a stream with it. fopen returns a pointer to be used to identify the stream in subsequent operations. The mode string used in calls to fopen is one of the following values:

Mode | Description
r | Open for reading only.
w | Create for writing. If a file by that name already exists, it will be overwritten.
a | Append; open for writing at end of file, or create for writing if the file does not exist.
r+ | Open an existing file for update (reading and writing).
w+ | Create a new file for update (reading and writing). If a file by that name already exists, it will be overwritten.
a+ | Open for append; open for update at the end of the file, or create if the file does not exist.

On successful completion, fopen returns a pointer to the newly opened stream. In the event of error, it returns NULL. Note that files on TI are in fact TIOS variables, so their maximal size is limited (as the size of the variable is limited). Maybe in the future I will try to implement files which are limited only by the amount of the free memory.
To specify that a given file is being opened or created in text mode, append a 't' to the mode string ("rt", "w+t", and so on). Similarly, to specify binary mode, append a 'b' to the mode string ("wb", "a+b", and so on). What "text" or "binary" exactly means will be explained a bit later. fopen also allows the t or b to be inserted between the letter and the '+' character in the mode string. For example, "rt+" is equivalent to "r+t". If a 't' or 'b' is not given in the mode string, 't' is assumed (this slightly differs from the ANSI convention: in ANSI C the mode in this case is governed by the global variable _fmode, which is not implemented here).

When a file is opened in "text" mode, it is assumed to be a TEXT variable. On creating, all necessary headers and tags for the TEXT variable will be created. On opening for reading, the file pointer will be set to the first character in the first text line (asuming that it IS a text variable). So, files created in "text" mode can be readed in the TI text editor, and you can read variables created in the text editor. All '\n' characters will be translated to '\r' 0x20 sequence during writting (to satisfy the format of the text in TEXT variables), and a character after '\r' will be swallowed during reading (to skip over the "command byte" at the begining of the each line). Here is an example:

FILE *f = fopen ("example", "w");
fputs ("First line\n", f);
fputs ("Second line\n", f);
fputs ("Third line\n", f);
fclose (f);
After this, you will have a TEXT variable called "example" which can be opened in text editor. You can read the content of a TEXT variable similarly.

When a file is opened in "binary" mode, nothing is assumed about the structure of the file. It can be a variable of any type. The user is responsible to create appropriate variable structure. There will no be any translation of characters, and after opening the file pointer will point to the first byte of the variable (after two "length" bytes), regardless of what the variable is supposed to be. For example, the string variable has the following structure: one zero byte, the content of the string, another zero byte, and finally, the string tag (STR_TAG or 0x2D byte). Here is an example of creating a file which represents a string variable:
FILE *f = fopen ("example", "wb");
fputc (0, f);
fputs ("This is a string", f);
fputc (0, f);
fputc (STR_TAG, f);
fclose (f);
When a file is opened for update (in both text or binary mode), both input and output can be done on the resulting stream. However, ANSI proposes that output cannot be followed directly by input without an intervening fseek or rewind, and that input cannot be directly followed by output without an intervening fseek, rewind, or an input that encounters end-of-file. I don't see any reason to implement such limitation here.

The filename pointed to by filename may also contain a path (i.e. a folder name may be given in front of the file name). If name of a folder which does not exist is given, and if fopen needs to create a new file, a dialog will appear which asks the user whether a new folder will be created. If the answer is "NO", fopen fails, returning NULL. If no folder name is given, the current folder is assumed.

Note: All functions which accept a parameter which is a pointer to a FILE structure assumes that the pointer is valid, i.e. created using fopen command. As I have no any efficient method to check whether the pointer is valid or not, no checking is implemented. So, if you pass an invalid pointer to any file handling function, the results are unpredictable.

Uses: HeapAlloc, HeapAllocPtr, HeapFreePtr, HeapSize, HLock, SaveScrState, RestoreScrState, strpbrk, DerefSym, SymAdd, SymDel, SymFind
Used by: freopen


fprintf

fprintf Function (tigcc.a)
stdio.h

short fprintf (FILE *stream, const char *format, ...);

Sends formatted output to a stream.

fprintf sends formatted output to a string. In fact, it does the following:

  • accepts a series of arguments;
  • applies to each argument a format specifier contained in the format string pointed to by format (see printf for details on format specifiers);
  • outputs the formatted data to the stream associated with the structure pointed to by stream
There must be the same number of format specifiers as arguments. fprintf returns the number of bytes output. In the event of error, it returns EOF.

Uses: fputc, vcbprintf


fputc

fputc Function (tigcc.a)
stdio.h

short fputc (short c, FILE *stream);

Function version of fputc.

fputc is usually equal to putc, except fputc is implemented as a function, but putc is implemented as a macro.

Uses: feof, HeapRealloc, HeapUnlock, HLock
Used by: fprintf, fputs, fwrite, putc, vfprintf


fputchar

fputchar Function (tigcc.a)
stdio.h

short fputchar (short c);

Function version of putchar.

fputchar is usually equal to putchar, except fputchar is implemented as a function, but putchar is implemented as a macro.

Uses: DrawChar, FontCharWidth, FontGetSys, MoveTo, SaveScrState, ScrRect, ScrRectScroll
Used by: fgetchar, gets, getsn, printf, putchar, puts, vprintf


fputs

fputs Function (tigcc.a)
stdio.h

short fputs (const char *s, FILE *stream);

Outputs a string to a stream.

fputs copies the null-terminated string s to the output stream associated to the structure pointed to by stream. It does this by calling putc repeatedly. It does not append a newline character, and the terminating null character is not copied. On successful completion, fputs returns the last character written. Otherwise, it returns a value of EOF.

Uses: fputc


fread

fread Function (tigcc.a)
stdio.h

unsigned short fread (void *ptr, unsigned short size, unsigned short n, FILE *stream);

Reads data from a stream.

fread reads n items of data, each of length size bytes, from the input stream associated with the structure pointed to by stream into a block pointed to by ptr. The total number of bytes read is n x size. fread fread returns the number of items (not bytes) actually read. If the operation was sucessful, the returned result should be equal to n. In a case of error, returned result will be smaller (possibly zero).

Note: fread is proposed to be used in "binary" mode (see fopen). Although this is not strictly necessary, it is is highly recommended opening stream in "binary" mode if you want to use this function. Anyway, there will not be any character translations during reading, even if the file is opened in "text" mode. This function was buggy in releases of TIGCCLIB prior to 2.2; this is now fixed.

Uses: fgetc


freopen

freopen Function (Macro)
stdio.h

FILE *freopen (const char *filename, const char *mode, FILE *stream);

Associates a new file with an open stream.

freopen substitutes the named file in place of the open stream. It closes stream, regardless of whether the open succeeds. In this implementation, freopen is implemented as macro which first calls fclose passing stream to it, then calls fopen passing filename and mode to it. Such implementation is not absolutely correct, because the address of the file descriptor structure may be changed after closing and reopening again (if a garbage collect occurs). This is not a problem in programs which uses freopen as in

f=freopen (name, mode, f);
but it might cause problems in programs which uses freopen as in
freopen (name, mode, f);
To solve this problem, freopen macro will always re-assign the variable f to a (eventually) new value, so both above examples will be correct (the only small problem is in fact that f must ultimately be an lvalue, i.e, a variable or something similar).

On successful completion, freopen returns the argument stream (possibly changed). In the event of error, it returns NULL.

Note: This function is usually used for redirecting terminal streams like stdout and stdin. This is not possible here, because terminal-associated streams are not implemented.

Uses: fclose, fopen


fscanf

fscanf Function (Macro)
stdio.h

short fscanf(FILE *file, const char *format, ...);

File parsing function.

Works like sscanf, but reads the input from the file file rather than from a buffer of type char *.

Uses: cbscanf, fgetc


fseek

fseek Function (tigcc.a)
stdio.h

short fseek (FILE *stream, long offset, short whence);

Repositions the file pointer of a stream.

fseek sets the file pointer associated with stream to a new position that is offset bytes from the file location given by whence. For text mode streams (see fopen), offset should be 0 or a value returned by ftell. whence must be one of the following values (defined in enum SeekModes):

whence | File location
SEEK_SET | File beginning
SEEK_CUR | Current file pointer position
SEEK_END | End-of-file

fseek discards any character pushed back using ungetc. fseek returns 0 if the pointer is successfully moved. It returns a nonzero value on failure.

Used by: fsetpos, rewind


fsetbufsize

fsetbufsize Function (tigcc.a)
stdio.h

void fsetbufsize (unsigned short newsize, FILE *f);

Sets the buffer size of a file.

fsetbufsize sets the buffer size of an open file. The buffer size determines how much memory is reallocated to the file every time a write needs more memory from the heap. The default size (128 bytes) is set when the file is opened and should be sufficient for most uses. Setting a larger value will make writes faster at the cost of possibly running out of memory prematurely. If newsize is zero or f is NULL, no changes will be made.


fsetpos

fsetpos Function (Macro)
stdio.h

short fsetpos (FILE *stream, const fpos_t *pos);

Positions the file pointer of a stream.

fsetpos sets the file pointer associated with stream to a new position (given in the variable pointed to by pos). The new position is the value obtained by a previous call to fgetpos on that stream. It also clears the end-of-file indicator on the file that stream points to and undoes any effects of ungetc on that file. On success, fsetpos returns 0. On failure, it returns a nonzero value.

Note: fgetpos is implemented here as a macro which calls fseek.

Uses: fseek


ftell

ftell Function (tigcc.a)
stdio.h

long ftell (const FILE *stream);

Returns the current file pointer.

ftell returns the current file pointer for the stream associated with the structure pointed to by stream. The offset is measured in bytes from the beginning of the file. The value returned by ftell can be used in a subsequent call to fseek. ftell returns the current file pointer position on success. It returns EOF on error.

Used by: fgetpos


fwrite

fwrite Function (tigcc.a)
stdio.h

unsigned short fwrite (const void *ptr, unsigned short size, unsigned short n, FILE *stream);

Writes data to a stream.

fwrite writes n items of data, each of length size bytes, to the output file associated with the structure pointed to by stream. The data written begins at ptr. The total number of bytes written is n x size. ptr in the declarations is a pointer to any object. fwrite returns the number of items (not bytes) actually written. If the operation was sucessful, the returned result should be equal to n. In a case of error, returned result will be smaller (possibly zero).

Note: fwrite is proposed to be used in "binary" mode (see fopen). Although this is not strictly necessary, it is is highly recommended opening stream in "binary" mode if you want to use this function. Anyway, there will not be any character translations during writing, even if the file is opened in "text" mode. This function was buggy in releases of TIGCCLIB prior to 2.2; this is now fixed.

Uses: fputc


getc

getc Function (Macro)
stdio.h

#define getc fgetc

Gets a character from a stream.

getc gets the next character on the given input stream (associated with the structure pointed to by stream), and increments the stream's file pointer to point to the next character. If the file is opened in "text" mode (see fopen), a character after '\r' will be swallowed during reading (to skip over the "command byte" at the begining of the each line in a TEXT variable).

On success, getc returns the character read, after converting it to an integer without sign extension. On error (usually end-of-file), it returns EOF.

Uses: fgetc


getchar

getchar Function (Macro)
stdio.h

#define getchar fgetchar

Gets a character from the keyboard (with echoing to the screen).

fgetchar returns the character read from the keyboard. It is similar to ngetchx except getchar shows a cursor (a simple underscore), echoes the character read on the screen and supports the CHAR menu. '\r' character (i.e. ENTER key) will be echoed as a "new line".

Note: In ANSI C, getchar(c) is equal to getc(c, stdin), so it can be redirected using freopen. This is not possible here, because stdin is not implemented as a file stream.

Uses: fgetchar


gets

gets Function* (tigcc.a)
stdio.h

char *gets (char *string);

Gets a string from the keyboard.

gets collects a string of characters terminated by a new line from the keyboard (by repeated calling to getchar) and puts it into string. The new line is replaced by a null character ('\0') in string. gets returns when it encounters a new line (i.e. when the ENTER key is pressed); everything up to the new line is copied into string. gets returns the string argument string (ANSI proposes returning of NULL in a case of error, but this never occurs on the TI). For editing, the backspace key is supported. Here is an example of usage:

char buffer[50];
int a, b;
clrscr ();
puts ("A = ");
a = atoi (gets (buffer));
puts ("B = ");
b = atoi (gets (buffer));
printf ("%d + %d = %d", a, b, a+b);
atoi is an ANSI C standard function from stdlib.h header file.

Important: gets does not check buffer bounds, so using getsn or a custom input routine is recommended instead.

Uses: fputchar, printf, EV_captureEvents, EV_defaultHandler, MoveTo, SaveScrState, ngetchx

See also: getsn, How can I get input from the keyboard?, textedit.h


getsn

getsn Function* (tigcc.a)
stdio.h

char *getsn (char *string, unsigned long maxlen);

Gets a string from the keyboard avoiding buffer overflows.

getsn works like gets, but with a maximum length specified. The maximum length (maxlen) is the total size of the buffer. In other words, the null-terminator is included in the maximum length. When the buffer is full (i.e. when the string length is maxlen - 1), getsn will not accept any more characters. Only backspace or ENTER are allowed in that situation. Here is an example of usage:

char buffer[50];
int a, b;
clrscr ();
puts ("A = ");
a = atoi (getsn (buffer, 50));
puts ("B = ");
b = atoi (getsn (buffer, 50));
printf ("%d + %d = %d", a, b, a+b);
atoi is an ANSI C standard function from stdlib.h header file.

Note: getsn is not an ANSI C standard function, but the equivalent of fgets (buffer, maxlen, stdin) in ANSI C. It is needed because terminal streams are not implemented in TIGCCLIB.

Uses: fputchar, printf, EV_captureEvents, EV_defaultHandler, MoveTo, SaveScrState, ngetchx
Used by: scanf, vscanf

See also: gets, fgets, How can I get input from the keyboard?, textedit.h


printf_xy

printf_xy Function (Macro)
stdio.h

void printf_xy (short x, short y, const char *format, ...);

Sends formatted output to the fixed place on the screen.

printf_xy is similar to the standard ANSI C printf function, except:

  • this function displays formatted output to the screen at the strictly specified position, more precise, starting from the point (x, y);
  • text printed with printf_xy will not wrap at the right end of the screen (if the text is longer, the result is unpredictable);
  • characters '\n' will not be translated to "new line";
  • this function will never cause screen scrolling;
  • current print/plot position remains intact after executing this function.
printf_xy is a GNU C macro which calls sprintf and DrawStr.

Uses: sprintf, DrawStr


printf

printf Function (tigcc.a)
stdio.h

void printf (const char *format, ...);

Sends formatted output to the screen.

printf is nearly full implementation of standard ANSI C printf function, which sends the formatted output to the screen in terminal (TTY) mode. In fact, it does the following:

  • accepts a series of arguments;
  • applies to each a format specifier contained in the format string pointed to by format;
  • outputs the formatted data to the screen.
The printed text will wrap on the right end of the screen. Characters '\n' will be translated to "next line" (and this is the only control code which has a special implementation). The screen will scroll upwards when necessary (i.e. after printing a text in the last screen line). Note that all TI fonts are supported. Of course, printf will update current "print position" to a new one after the text is printed.

printf applies the first format specifier to the first argument after format, the second to the second, and so on. The format string, controls how printf will convert and format its arguments. There must be enough arguments for the format; if there are not, the results will be unpredictable and likely disastrous. Excess arguments (more than required by the format) are merely ignored. The format string is a character string that contains two types of objects: plain characters and conversion specifications. Plain characters are simply copied verbatim to the output string. Conversion specifications fetch arguments from the argument list and apply formatting to them. printf format specifiers have the following form:

% [flags] [width] [.prec] [{h|l}] type

Here is a complete table of supported formatting options (see any book about C language for more info):

Flags | Meaning
none | Right align (pad spaces or zeros to left)
- | Left align (pad spaces to right)
+ | Always force sign (include prefix '+' before positive values)
z | Don't postfix padding (this option is non-ANSI, i.e. TI specific)
space | Insert space before positive values
# | Prefix octal values with 0 and hex values (>0) with '0x') Force '.' in float output (and prevent trunctation of trailing zeros)
^ | TI-Float format: special character for the exponent and for the minus sign, no '+' prefix in the exponent, 0. instead of 0, no leading zeros if the magnitude is smaller than 1 (this option is non-ANSI, i.e. TI specific)
| | Center the output in the field (this option is non-ANSI, i.e. TI specific)

Width | Meaning
num | Print at least num characters - padded the rest with blanks
0num | (Zero prefixed) Same as above but padded with '0'
* | The width is specified in the arguments list (before value being formatted)

Precision | Meaning
none | Default precision
num | num is number of chars, decimal places, or number of significant digits (num<=16) to display depending on type (see below)
-1 | Default = 6 digits (this option is non-ANSI, i.e. TI specific)
* | The precision is specified in the argument list (before value being formatted)

Size {h|l} | Meaning
h | Force short integer
l | Force long integer

Type | Meaning
d, i | Signed decimal integer
u | Unsigned decimal integer
x | Lowercase hexadecimal integer
X | Uppercase hexadecimal integer
e | Floating point, format [-]d.dddd e[sign]ddd (exponential format)
E | Like 'e' but with uppercase letter for the exponent
f | Floating point, format [-]dddd.dddd
g | Floating point: most compact float format available ('e' or 'f'); this is the most common option, used for most dialog floats
G | Like 'g' but with uppercase letter for the exponent
r | Floating point, engineering form (this option is non-ANSI, i.e. TI specific)
R | Like 'r' but with uppercase letter for the exponent
y | Floating point, mode specified float format (this option is non-ANSI, i.e. TI specific)
Y | Like 'y' but with uppercase letter for the exponent
c | Character
s | String
p | Pointer; principally the same as 'x' - do not use without 'l' modifier
% | None; the character '%' is printed instead

Here is a short demonstration of usage:
int i, j;
for (j = F_4x6; j <= F_8x10; j++)
  {
    clrscr ();
    FontSetSys (j);
    for (i = 1; i <= 1000; i++)
      printf ("%d ", i);
    ngetchx ();
  }
Note: In ANSI C, printf is an int function, and it returns the number of printed characters. Due to some practical reasons, this implementation of printf is a void function. This difference is usually not important.

Uses: fputchar, vcbprintf
Used by: gets, getsn


putc

putc Function (Macro)
stdio.h

#define putc fputc

Writes a character to a stream.

putc writes the character c to the stream given by stream. It will update the stream's file pointer, and expands the size of associated variable if necessary. If the file is opened in "text" mode (see fopen), all '\n' characters will be translated to '\r' 0x20 sequence during writting (to satisfy the format of the text in TEXT variables). On success, putc returns the character c. On error, it returns EOF.

Uses: fputc


putchar

putchar Function (Macro)
stdio.h

#define putchar fputchar

Outputs a character to the screen in TTY mode.

Outputs a character c to the screen in TTY mode. This means the following:

  • The current print position will be moved in the text line after printing the last character in the screen line;
  • after printing the last character in the last screen line, the screen will scroll upwards;
  • characters '\n' will be translated to "next line" (and this is the only control code which has a special implementation);
  • the current print position will be updated after the character is printed.
All TI fonts are supported.

putchar returns the character c (ANSI C proposes returning EOF in a case of error, but printing on TIOS cannot fail).

Note: In ANSI C, putchar(c) is equal as putc(c, stdout), so it can be redirected using freopen. This is not possible here, because stdout is not implemented as a file stream.

Uses: fputchar


puts

puts Function (tigcc.a)
stdio.h

void puts (const char *s);

Outputs a string to the screen in TTY mode.

puts outputs the null-terminated string s to the screen by repeated calling to putchar until the end of the string is reached.

Note: There are two minor differences between this implementation of puts and ANSI definition. First, ANSI puts is an int function which returns an undefined nonnegative value, except in a case of error (which never occurs on TI). For some practical reasons, puts is here a void function. Second, ANSI puts automatically appends a "new line" character after the last printed character. This implementation of puts does not append a newline automatically. My opinion is that such implementation is more flexible, and it is not problem to append a newline ('\n') explicitely if necessary.

Uses: fputchar


remove

remove Function (Macro)
stdio.h

#define remove unlink

Macro that removes a file.

remove deletes the file specified by filename. It is a macro that simply translates its call to a call to unlink (name known from UNIX). So, both remove and unlink are equal. Although ANSI C proposes rename, unlink is more common in UNIX programs.

Uses: unlink


rename

rename Function (tigcc.a)
stdio.h

short rename (const char *oldname, const char *newname);

Renames a file.

rename changes the name of a file from oldname to newname (both filenames are normal C strings, which should be in lowercase). Filenames may also contain folder names. Folder names in oldname and newname need not be the same, so rename can be used to move a file from one folder to another. On successfully renaming the file, rename returns 0. In the event of error, EOF is returned.

Note: Function SymMove from vat.h header file is very similar like rename, except the parameters and returned result are somewhat different. As rename is not a TIOS entry and SymMove is, the usage of SymMove is recommended instead of rename (although SymMove is not ANSI standard).

Uses: SymMove


rewind

rewind Function (Macro)
stdio.h

void rewind (FILE *stream);

Repositions file pointer to stream's beginning.

rewind (stream) is equivalent to

fseek (stream, 0, SEEK_SET)
except that rewind clears the end-of-file and error indicators, while fseek only clears the end-of-file indicator.

Uses: fseek


scanf

scanf Function (Macro)
stdio.h

short scanf (const char *format, ...);

Console input parsing function.

Works like sscanf, but reads the input from the keyboard using getsn rather than from a buffer of type char *. [ENTER] is interpreted as EOF.

The input is echoed on the screen. No newline will be output at the end of the input, no matter whether it resulted from the user pressing [ENTER] or from a format matching error.

The amount of possible user input is limited by available memory. scanf may also return 0 if there was no memory left at all to allocate the temporary buffer.

Uses: getsn, sscanf, HeapAllocPtr, HeapFreePtr, HeapMax


snprintf

snprintf Function (tigcc.a)
stdio.h

short snprintf (char *buffer, unsigned long maxlen, const char *format, ...);

Sends formatted output, up to a given length, to a string.

snprintf sends formatted output to a string. In fact, it does the following:

  • accepts a series of arguments;
  • applies to each a format specifier contained in the format string pointed to by format;
  • outputs the formatted data (up to maxlen characters, including the terminating null byte) to the string pointed to by buffer;
snprintf applies the first format specifier to the first argument, the second to the second, and so on. The format string, controls how snprintf will convert and format its arguments. See printf for more info about format specifiers.

snprintf returns the number of bytes output, not including the terminating null byte in the count.

Uses: vsnprintf

See also: sprintf, vsnprintf


sprintf

sprintf Function (ROM Call 0x53)
stdio.h, string.h

short sprintf (char *buffer, const char *format, ...);

Sends formatted output to a string.

sprintf sends formatted output to a string. In fact, it does the following:

  • accepts a series of arguments;
  • applies to each a format specifier contained in the format string pointed to by format;
  • outputs the formatted data to the string pointed to by buffer;
sprintf applies the first format specifier to the first argument, the second to the second, and so on. The format string, controls how sprintf will convert and format its arguments. See printf for more info about format specifiers.

sprintf returns the number of bytes output, not including the terminating null byte in the count.

Uses: strlen, XR_stringPtr, is_transfinite, CTypeTable, _bcd_math, _du32u32, _mu32u32
Used by: printf_xy, HeapWalk, assert, cmd_cyclepic, cmd_newdata, cmd_showstat, cmd_sinreg, ERD_dialog, ERD_process, index_below_display_expression_aux, Parse1DExpr, Parse2DExpr, Parse2DMultiExpr, ABT_dialog, EV_defaultHandler, handleVarLinkKey, GR3_paint3d, HomeExecute, LIO_Receive, AB_prodid, AB_serno, LOC_formatDate, EQU_getNameInfo, EV_quit, gr_de_axes_lbl, gr_DispLabels, GR3_addContours, GT_Trace, GZ_SetFactors, LIO_SendIdList, OO_GetAttr, SP_Define, spike_in_editor, spike_titles_in_editor, TempFolderName, ROM Call 0x45B, DateAndTime_SetDlg, DateStr, TimeStr

See also: snprintf, vsprintf


sscanf

sscanf Function (Macro)
stdio.h

short sscanf (const char *buffer, const char *format, ...);

String parsing function.

sscanf scans the string buffer for the formats in the format string format and assigns the input to pointers passed as varargs. Returns:

  • the number of pointers filled in (the number of matches done) if it is non-0
  • 0 if no pointers were filled in because of a format matching error
  • EOF (-1) if the input ended before any pointers were filled in

Formats accepted:
  • any non-whitespace character other than '%': matches a literal character, assigns nothing
  • whitespace characters: match any whitespace characters, even if they are a different kind of whitespace, assign nothing
  • '%%': matches a literal '%', assigns nothing
  • Any formats of the type '%' + flags + width + type (or '%' + width + flags + type, the order isn't actually checked, you can even put the flags in the middle of the width):

    Flags accepted:
    • '*': skip the matched data (don't assign it to a pointer, and don't count it)
    • 'h': if an integer type follows, it will be a short integer, otherwise the flag is ignored. (This is the default if neither 'h' nor 'l' are specified.)
    • 'l': if an integer type follows, it will be a long integer, otherwise the flag is ignored
    • Warning: "%h" or "%l" alone is not accepted. Always write "%li", "%ld", ... explicitely.

    Width: Maximum number of bytes to read in for data matching. The maximum is 65535. Any larger number will be truncated modulo 65536. If the width is 0 or omitted, the default width for the format is used.

Types accepted:
  • 'u': matches an unsigned decimal integer
    default width: 65536
    required pointer: 'unsigned short *' for '%hu', 'unsigned long *' for '%lu'
    automatically skips leading whitespace
  • 'd': matches a signed decimal integer (both [-] and [(-)] are accepted)
    default width: 65536
    required pointer: 'short *' for '%hd', 'long *' for '%ld'
    automatically skips leading whitespace
  • 'o': matches an unsigned octal integer
    default width: 65536
    required pointer: 'unsigned short *' for '%ho', 'unsigned long *' for '%lo'
    automatically skips leading whitespace
  • 'x' or 'X': matches an unsigned hexadecimal integer (0-9 and both a-f and A-F are accepted)
    default width: 65536
    required pointer: 'unsigned short *' for '%hx', '%hX', 'unsigned long *' for '%lx', '%lX'
    automatically skips leading whitespace
  • 'p': same as '%lx' (even if '%hp' or just '%p' is specified)
  • 'i': matches an integer in C syntax: may contain a negative sign ([-] or [(-)]), is hexadecimal if started with 0x, octal if started with 0, and decimal otherwise
    default width: 65536
    required pointer: 'short *' or 'unsigned short *' for '%hi', 'long *' or 'unsigned long *' for '%li'
    automatically skips leading whitespace
  • 'f', 'g', 'e' or 'E': matches a floating-point number. (This number will be parsed by push_parse_text (through atof), so it has to use the calculator '-' and 'E'.)
    default and maximum width: 29. This limitation is because we need to allocate a buffer for atof on the stack, and we didn't want to waste too much stack space.
    required pointer: 'float *'
    automatically skips leading whitespace
  • 's': matches a non-whitespace string, and null-terminates it when copying it to the buffer (so make sure you have a buffer of size width + 1)
    default width: 65536
    required pointer: 'char *'
    automatically skips leading whitespace
  • 'c': matches a fixed number of characters (the given width). Does NOT null-terminate the string when copying it to the buffer.
    default width: 1 (NOT the maximum width like for the other formats)
    required pointer: 'char *'
    does NOT skip leading whitespace (put a space before '%c' if you want to skip it)
  • '[': matches a regexp-style set of characters:
    • ']' terminates the set unless it immediately follows the leading '[' or the leading '[^'
    • if '^' is the first character, matches the characters which are NOT in the set
    • '-' specifies a range of characters (as in '0-9') unless it immediately precedes the terminating ']'
    • any other characters (including ']' right at the beginning or '-' right at the end): match the corresponding literal characters

    copies characters until either the input ends, or the specified width is reached, or a character which is not in the specified set (when using '^': which is in the specified set) is encountered
    null-terminates the copied string (so make sure you have a buffer of size width + 1)
    default width: 65536
    required pointer: 'char *'
    does not skip leading whitespace (put a space before '%[' if you want to skip it)
  • 'n': does not read anything from the input, but assigns the number of characters already read in to the given pointer
    default width: N/A (the width is ignored, and no characters are read in)
    required pointer: 'short *'
    does not skip any whitespace in the input

Uses: cbscanf
Used by: scanf


strerror

strerror Function (ROM Call 0x27D)
stdio.h, string.h

char *strerror (short err_no);

Gives an error message string.

strerror returns a pointer to string which contains text of the system error message err_no. Note that this is not a TI-Basic error message, but a low level error message. Here is a complete table of such messages:

0 | no error
1 | no such file entry
2 | I/O error
3 | not a serial device
4 | out of memory
5 | permission denied
6 | block device required
7 | no such device
8 | invalid argument
9 | file table is full
10 | device directory is full
11 | no space left on device
12 | no more allocation blocks
13 | no more data blocks on device
14 | file is open
15 | no RAM space configured
16 | no heap space configured
17 | seek can't extend read only file
18 | bad file descriptor - file not open
19 | invalid signal number
20 | argument out of range
21 | result out of range

Other values of err_no will generate "undefined errno value" message.

Note: antediluvian releases of TIGCCLIB report wrongly that err_no is a TI-Basic error code, which is not true. To get a pointer to TI-Basic error message, use find_error_message function.


strputchar

strputchar Function (tigcc.a)
stdio.h

void strputchar (char c, void **ptr);

Default vcbprintf callback function used in sprintf.

strputchar is callback function (passed to vcbprintf which is used internally for implementation of sprintf (in TIOS) and vsprintf functions. It does nothing more than

*((*(char**)ptr)++) = ch;

Used by: vsprintf


tmpnam

tmpnam Function (tigcc.a)
stdio.h

char *tmpnam (char *s);

Produces a unique random file name.

tmpnam returns a random file name of 8 characters which does not exist on the calculator. If s is NULL, tmpnam returns a pointer to a static buffer, otherwise it fills s and returns a pointer to it. When passing NULL to tmpnam, it is best to treat the pointer returned as if it were pointing to constant data. It is assumed that the buffer pointed to by s is at least 9 bytes long.

tmpnam is capable of returning TMP_MAX or 25^8 combinations. When nearing TMP_MAX, performance decreases significantly, and eventually, the function will run into an infinite loop. These factors, however, should not pose any problems for the currently supported calculator platforms. You will run into the maximum number of handles a lot sooner.

Note: tmpnam does not actually create any files. If you call it twice without creating a file whose name equals the first result, it may, in theory, return the same name again.

Uses: rand


ungetc

ungetc Function (Macro)
stdio.h

short ungetc (short c, FILE *stream);

Pushes a character back into input stream.

ungetc pushes the character c back onto the stream associated with the structure pointed to by stream. This character will be returned on the next call to getc (or related functions like fread) for that stream. A second call to ungetc without a call to getc will force the previous character to be forgotten. A call to fflush, fseek, fsetpos, or rewind erases all memory of any pushed-back characters. ungetc returns the character pushed back. ANSI C proposes that it need to return EOF if the operation fails, but in this implementation it cannot fail. It is implemented as a very simple macro.

Note: ungetc is used in some programs to push back a character to the stream associated with the keyboard using ungetc(c, stdin). This is not possible on TI, because terminal-associated streams are not supported. Use pushkey instead to achieve the same effect.


unlink

unlink Function (tigcc.a)
stdio.h

short unlink (const char *filename);

Deletes a file.

unlink deletes the file specified by filename (it is a normal C string, which should be in lowercase). If your file is open, be sure to close it before removing it. The string pointed to by filename may include a folder name too. On successful completion, unlink returns 0. On error, it returns EOF.

Note: Function SymDel from vat.h header file is very similar like unlink (or remove), except the parameter and returned result are somewhat different. As unlink is not a TIOS entry and SymDel is, the usage of SymDel is recommended instead of unlink (although SymDel is not ANSI standard).

Uses: SymDel
Used by: remove


vcbprintf

vcbprintf Function (ROM Call*)
stdio.h

void vcbprintf (vcbprintf_Callback_t callback, void **param, const char *format, va_list arglist);

Virtual callback printing function.

vcbprintf is an auxiliary function which is the heart of all v...printf functions. arglist is a pointer to the list of arguments (see stdarg.h for more info about argument lists), and format is the format string, as usually. vcbprintf applies to each argument a format specifier contained in the format string. After this, the formatted data is sent character by character to the callback function callback passing the actual characters as the parameter c to it. Also, the parameter param of vcbprint is passed as the second parameter to the callback function. This allows for much more flexibility, because a callback function usually needs more info than a simple character to be processed. The callback function for example can push characters to a stream, so in this case param would probably be a pointer to the stream structure. More precisely,

vfprintf (stream, format, arglist);
is exactly the same as
vcbprintf ((vcbprintf_callback_t)fputc, (void**)stream, format, arglist);
See also TE_pasteText for an ununsual but powerful example of usage of vcbprintf.

param is declared as a "double pointer" because it is often used as a pointer to a pointer variable (in vsprintf for example), so the callback function is able to change the content of the actual pointer variable (see strputchar).

Used by: cbprintf, fprintf, printf, vfprintf, vprintf, vsprintf


vcbscanf

vcbscanf Function* (tigcc.a)
stdio.h

short vcbscanf (vcbscanf_get_Callback_t getfun, vcbscanf_unget_Callback_t ungetfun, void *param, const char *format, va_list arglist);

Virtual callback parsing function.

vcbscanf is an auxiliary function which is the heart of all scanf family functions. arglist is a pointer to the list of arguments (see stdarg.h for more info about argument lists), and format is the format string, as usually (see sscanf). vcbscanf gets its characters using the getfun callback. If it reads a character it can't handle, it ungets it using the ungetfun callback. Also, the parameter param of vcbscanf is passed as the second parameter to the callback function. This allows for much more flexibility, because a callback function usually needs more info than a simple character to be processed. The callback function for example can get characters from to a stream, so in this case param would probably be a pointer to the stream structure. The formatted data is parsed according to the format string, as described for sscanf.

Used by: vfscanf, vsscanf


vfprintf

vfprintf Function (Macro)
stdio.h

short vfprintf (FILE *stream, const char *format, va_list arglist);

Sends formatted output to a stream using argument list.

The vfprintf functions is known as an alternate entry point for the fprintf functions. It behaves exactly like fprintf, but it accepts a pointer to a list of arguments instead of an argument list (see stdarg.h header file for more info about argument lists). See printf for details on format specifiers.

vfprintf accepts arglist which is a pointer to a series of arguments, applies to each argument a format specifier contained in the format string pointed to by format, and outputs the formatted data to the stream associated with the structure pointed to by stream. There must be the same number of format specifiers as arguments.

vfprintf returns the number of bytes output. In the event of error, vfprintf returns EOF.

Uses: vcbprintf, fputc


vfscanf

vfscanf Function (Macro)
stdio.h

short vfscanf (FILE *file, const char *format, va_list arglist);

File parsing function using argument list.

The vfscanf function is known as an alternate entry point for the fscanf function. It behaves exactly like fscanf, but it accepts a pointer to a list of arguments instead of an argument list (see stdarg.h header file for more info about argument lists). See sscanf for details on format specifiers.

Uses: vcbscanf, fgetc


vprintf

vprintf Function (Macro)
stdio.h

void vprintf (const char *format, va_list arglist);

Sends formatted output to the screen using argument list.

The vprintf functions is known as an alternate entry point for the printf function. It behaves exactly like printf, but it accepts a pointer to a list of arguments instead of an argument list (see stdarg.h header file for more info about argument lists). See printf for details on format specifiers.

vprintf accepts arglist, which is a pointer to a series of arguments, applies to each a format specifier contained in the format string pointed to by format, and outputs the formatted data to the screen. There must be the same number of format specifiers as arguments.

Note: In ANSI C, function vprintf is an int function, and it returns the number of printed characters. Due to some practical reasons, this implementation of vprintf is a void function. This difference is usually not important.

Uses: vcbprintf, fputchar


vscanf

vscanf Function (Macro)
stdio.h

short vscanf (const char *format, va_list arglist);

Console input parsing function using argument list.

The vfscanf function is known as an alternate entry point for the fscanf function. It behaves exactly like scanf, but it accepts a pointer to a list of arguments instead of an argument list (see stdarg.h header file for more info about argument lists). See sscanf for details on format specifiers.

Uses: getsn, vsscanf, HeapAllocPtr, HeapFreePtr, HeapMax


vsnprintf

vsnprintf Function (tigcc.a)
stdio.h

short vsnprintf (char *buffer, unsigned long maxlen, const char *format, va_list arglist);

Sends formatted output, up to a given length, to a string, using argument list.

The vsprintf function is known as an alternate entry point for the snprintf function. It behaves exactly like snprintf, but it accepts a pointer to a list of arguments instead of an argument list (see stdarg.h header file for more info about argument lists). See printf for details on format specifiers.

vsprintf accepts arglist, which is a pointer to a series of arguments, applies to each a format specifier contained in the format string pointed to by format, and outputs the formatted data (up to maxlen characters) to the string pointed to by buffer. There must be the same number of format specifiers as arguments.

Uses: vcbprintf, setjmp, longjmp

See also: vsprintf


vsprintf

vsprintf Function (Macro)
stdio.h

short vsprintf (char *buffer, const char *format, va_list arglist);

Sends formatted output to a string using argument list.

The vsprintf function is known as an alternate entry point for the sprintf function. It behaves exactly like sprintf, but it accepts a pointer to a list of arguments instead of an argument list (see stdarg.h header file for more info about argument lists). See printf for details on format specifiers.

vsprintf accepts arglist, which is a pointer to a series of arguments, applies to each a format specifier contained in the format string pointed to by format, and outputs the formatted data to the string pointed to by buffer. There must be the same number of format specifiers as arguments.

Note: In ANSI C, function vsprintf is an int function, and it returns the number of characters stored in buffer. Due to some practical reasons, this implementation of vsprintf is a void function. This difference is usually not important.

Uses: vcbprintf, strputchar

See also: vsnprintf


vsscanf

vsscanf Function (Macro)
stdio.h

short vsscanf (const char *buffer, const char *format, va_list arglist);

String parsing function using argument list.

The vsscanf function is known as an alternate entry point for the sscanf function. It behaves exactly like sscanf, but it accepts a pointer to a list of arguments instead of an argument list (see stdarg.h header file for more info about argument lists). See sscanf for details on format specifiers.

Uses: vcbscanf
Used by: vscanf


EOF

EOF Constant
stdio.h

#define EOF (-1)

Indicates that the end of a file has been reached.

EOF is a constant which is usually returned as the result of file handling functions if an end-of-file is reached, or in a case of an error. The ANSI standard does not propose exact value of this constant, but it proposes that it must be negative.


TMP_MAX

TMP_MAX Constant
stdio.h

#define TMP_MAX 152587890625

Contains the maximum number of temporary file names.

TMP_MAX describes the maximum number of temporary file names the tmpnam function can return. This limit equals 25^8, i.e. the number of possibilities if you have 25 possible values for all 8 characters. You can never run into this limit; see tmpnam for more info.


FILE

FILE Type (Structure)
stdio.h

typedef struct {
char *fpos; /* Current position of file pointer (absolute address) */
void *base; /* Pointer to the base of the file */
unsigned short handle; /* File handle */
short flags; /* Flags (see FileFlags) */
short unget; /* 1-byte buffer for ungetc (b15=1 if non-empty) */
unsigned long alloc; /* Number of currently allocated bytes for the file */
unsigned short buffincrement; /* Number of bytes allocated at once */
} FILE;

A structure describing an opened file.

FILE is the main file control structure for streams. The exact structure of it is very platform-dependent, so ANSI C proposes that the exact structure of this structured type should not be known, and well-written programs do not need to access the internal fields of this structure.


FileFlags

FileFlags Type (Enumeration)
stdio.h

enum FileFlags {_F_READ = 0x0001, _F_WRIT = 0x0002, _F_RDWR = 0x0003, _F_ERR = 0x0010, _F_EOF = 0x0020, _F_BIN = 0x0040};

An enumeration describing internal flags for file handling.

These flags describes whether the file is opened in read or write mode, whether an end-of-file or a serious error occured, and whether the file is open in binary or text mode.

See also: FILE


fpos_t

fpos_t Type (Scalar)
stdio.h

typedef unsigned long fpos_t;

A type describing the current position in a file.

fpos_t is a scalar type used for saving the current file position using fgetpos and restoring it back using fsetpos.


SeekModes

SeekModes Type (Enumeration)
stdio.h

enum SeekModes {SEEK_SET, SEEK_CUR, SEEK_END};

An enumeration for describing possible modes used in fseek.


vcbprintf_Callback_t

vcbprintf_Callback_t Type (Pointer)
stdio.h

typedef CALLBACK void (*vcbprintf_Callback_t) (char c, void **param);

Describes a callback function for vcbprintf.


vcbscanf_get_Callback_t

vcbscanf_get_Callback_t Type (Pointer)
stdio.h

typedef CALLBACK short (*vcbscanf_get_Callback_t) (void *param);

Describes the first callback function for vcbscanf.


vcbscanf_unget_Callback_t

vcbscanf_unget_Callback_t Type (Pointer)
stdio.h

typedef CALLBACK short (*vcbscanf_unget_Callback_t) (void *param);

Describes the second callback function for vcbscanf.


stdlib.h

stdlib.h Header File
Header File Index

Some useful routines proposed by ANSI (sorting, searching, etc.)

Functions
abort
Abnormal termination of a process.
abs
Absolute value of a number.
alloca
Allocates memory on the local storage space.
atexit
Registers a termination function.
atof
Converts a string to a floating point.
atoi
Converts a string to a short integer.
atol
Converts a string to a long integer.
bsearch
Binary search.
calloc
Allocates a memory block for a given number and size of items.
div
Divides two short integers, and returns quotient and remainder.
exit
Forced termination of the program.
fabs
Absolute value of a floating point number.
free
Frees an allocated block.
labs
Absolute value of a long integer number.
ldiv
Divides two long integers, and returns quotient and remainder.
malloc
Allocates a memory block.
max
Maximum of two integer numbers.
min
Minimum of two integer values.
qsort
Sorts an area of items.
rand
Returns a pseudorandom number.
random
Generates a random integer in a given range.
randomize
Initializes random number generator with a random value.
realloc
Reallocates allocated memory.
srand
Initializes random number generator.
strtod
Converts a string to a floating point value, with optional error-checking.
strtol
Converts a string to a long integer using a given radix, with detection of overflows and errors.
strtoul
Converts a string to an unsigned long integer using a given radix, with detection of overflows and errors.
TIOS_strtod

Constants
EXIT_FAILURE
Failure exit code for exit.
EXIT_SUCCESS
Normal exit code for exit.
NULL
A null-pointer value.
RAND_MAX
Returns the largest number returned by rand.
Predefined Types
atexit_t
Describes an exit function passed to atexit.
compare_t
Describes a comparison function.
div_t
An integer division return type used in the div function.
ldiv_t
A long integer division return type used in the ldiv function.
size_t
A type to define sizes of strings and memory blocks.


abort

abort Function (Macro)
stdlib.h

void abort (void);

Abnormal termination of a process.

abort writes a termination message ("ABNORMAL PROGRAM TERMINATION") in the status line, then aborts the program by a call to exit (passing 0 to it).

Note that the status line text will not be visible if SAVE_SCREEN is defined.

Uses: exit, ST_helpMsg


atexit

atexit Function (tigcc.a)
stdlib.h

short atexit (atexit_t func);

Registers a termination function.

atexit registers the function pointed to by func as an exit function. Upon normal termination of the program (including termination using the exit function), func is called just before returning to the TIOS. Each call to atexit registers another exit function. The number of function which can be registered depends on the current number of free handles. All registered termination functions are executed on a last-in, first-out basis (the last function registered is the first to be executed). atexit returns 0 on success and nonzero on failure (no space left to register the function).

Note: Termination functions are not called on abnormal termination of the program (i.e. if an error is thrown from the program).

atexit does not work with enter_ghost_space. However, if a program is already executed in the ghost space (because of ExePack compression or because it has been called from a launcher), there should not be any problems.

Uses: HeapAllocPtr, HeapFreePtr, realloc


atoi

atoi Function (tigcc.a)
stdlib.h

short atoi (const char *str);

Converts a string to a short integer.

atoi converts the string pointed to by str to integer. atoi recognizes (in the following order):

  • an optional string of spaces [ws];
  • an optional sign ('+', '-', or special "small" minus used in TI-Basic) [sn];
  • a string of digits [ddd].
The characters must match this generic format:

[ws] [sn] [ddd]

In atoi, the first unrecognized character ends the conversion. There are no provisions for overflow in atoi (results are wrong in a case of overflow). atoi returns the converted value of the input string. If the string cannot be converted, the return value is 0. See strtol and strtoul for conversions which allow much greater flexibility.


atol

atol Function (tigcc.a)
stdlib.h

long atol (const char *str);

Converts a string to a long integer.

atol is similar to atoi, but converts the string to a long integer.


bsearch

bsearch Function* (tigcc.a)
stdlib.h

void *bsearch (const void *Key, const void *BasePtr, unsigned short NoOfElements, unsigned short Width, compare_t cmp_func);

Binary search.

bsearch searches a table (array) of NoOfElements elements in memory, and returns the address of the first entry in the table that matches the search key. Because this is a binary search, the first matching entry is not necessarily the first entry in the table. If no match is found, bsearch returns NULL. NoOfElements gives the number of elements in the table. Width specifies the number of bytes in each table entry. BasePtr points to the base (0-th element) of the table to be sorted. Key is a pointer to the search key. cmp_func, the comparison function, accepts two arguments, elem1 and elem2, each a pointer to an entry in the table. The comparison function compares each of the pointed-to items (*elem1 and *elem2), and returns a short integer based on the result of the comparison:

  • If *elem1 < *elem2, cmp_func should return an integer < 0.
  • If *elem1 == *elem2, cmp_func should return 0.
  • If *elem1 > *elem2, cmp_func should return an integer > 0.
Here is a complete example of usage (called "Binary Search"):
// Search integer values using a binary search.

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

#define OPTIMIZE_ROM_CALLS
#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

// Comparison Function
CALLBACK short int_comp(const void *a, const void *b)
{
  return (*(const short*)a) - (*(const short*)b);
}

// Main Function
void _main(void)
{
  short list[10] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
  short i;
  short font;
  void *p;

  font = FontGetSys();
  FontSetSys(F_4x6);
  clrscr ();
  for (i = -1; i < 11; i++) {
    p = bsearch (&i, list, sizeof(list)/sizeof(list[0]), sizeof (list[0]), int_comp);
    if (p == NULL) {
      printf ("%d not found\n", i);
    }
    else {
      printf ("%d is at index %lu\n", i, ((void *)p - (void *)list)/sizeof(list[0]));
    }
  }
  FontSetSys(font);
  ngetchx ();
}

Note: if speed matters, create a bsearch() routine in your program, and inline the comparison function and element copy/swap codes. Your routine will be significantly faster and smaller that way.

See also: qsort


div

div Function (Macro)
stdlib.h

div_t div (short numer, short denom);

Divides two short integers, and returns quotient and remainder.

div divides two integers and returns both the quotient and the remainder as a div_t type. numer and denom are the numerator and the denominator, respectively. div returns a structure whose elements are quot (the quotient) and rem (the remainder).

Note: div is an inline function, implemented using GNU C smart macros.


exit

exit Function (Macro)
stdlib.h

void exit (short code);

Forced termination of the program.

exit terminates the program (it may be called from any nesting level). Before termination, any registered "exit functions" (posted with atexit) are called. ANSI proposes that exit also closes all open files. Such behaviour is not implemented here, you need to do it manually if necessary.

code is the exit status. Value of 0 (EXIT_SUCCESS) is used to indicate a normal exit. If code is nonzero (e.g. EXIT_FAILURE), an error message dialog which corresponds with code code will be displayed before exiting. Note that this is not the same as throwing error code using ER_throwVar. Throwing an error is much more a "barbaric" method for exiting from the program. Among others, by throwing an error, no registered "exit functions" will be called.

Used by: abort


ldiv

ldiv Function (Macro)
stdlib.h

ldiv_t ldiv (long n, long d);

Divides two long integers, and returns quotient and remainder.

ldiv divides two long integers and returns both the quotient and the remainder as a ldiv_t type. numer and denom are the numerator and the denominator, respectively. div returns a structure whose elements are quot (the quotient) and rem (the remainder).

Note: ldiv is an inline function, implemented using GNU C smart macros.


max

max Function (Macro)
stdlib.h

any_type max (any_type a, anytype b);

Maximum of two integer numbers.

max is an inline function (implemented using GNU C smart macros) which returns the greater of a and b. They may be any numeric values, either integer or floating point numbers, and they also may be pointers to the same base type. The result has the type of the argument which has greater range of possible values (e.g. if one is float and second one is long int, the result is of float type).

See also: min


min

min Function (Macro)
stdlib.h

any_type min (any_type a, anytype b);

Minimum of two integer values.

min is an inline function (implemented using GNU C smart macros) which returns the smaller of a and b. They may be any numeric values, either integer or floating point numbers, and they also may be pointers to the same base type. The result has the type of the argument which has greater range of possible values (e.g. if one is float and second one is long int, the result is of float type).

See also: max


qsort

qsort Function* (tigcc.a)
stdlib.h

void qsort (void *BasePtr, unsigned short NoOfElements, unsigned short Width, compare_t cmp_func);

Sorts an area of items.

qsort sorts the entries in a table by repeatedly calling the user-defined comparison function pointed to by cmp_func. BasePtr points to the base (0-th element) of the table to be sorted. NoOfElement is the number of entries in the table. Width is the size of each entry in the table, in bytes. cmp_func, the comparison function, accepts two arguments, elem1 and elem2, each a pointer to an entry in the table. The comparison function compares each of the pointed-to items (*elem1 and *elem2), and returns a short integer based on the result of the comparison:

  • If *elem1 < *elem2, cmp_func should return an integer < 0.
  • If *elem1 == *elem2, cmp_func should return 0.
  • If *elem1 > *elem2, cmp_func should return an integer > 0.
In the comparison, the less-than symbol (<) means the left element should appear before the right element in the final, sorted sequence. Similarly, the greater-than symbol (>) means the left element should appear after the right element in the final, sorted sequence.

The ANSI standard proposes that the comparison function has to return a long integer. However, strcmp, which is frequently used as a comparison function, returns a short integer.

Note: if speed matters, create a qsort() routine in your program, and inline the comparison function and element copy/swap codes. Your routine will be significantly faster and smaller that way.

Here is a complete example of usage (called "Sort Integers"):
// Sort a list of integer values

#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

// Comparison Function
CALLBACK short int_comp(const void *a, const void *b)
{
  return (*(const short*)a) - (*(const short*)b);
}

// Main Function
void _main(void)
{
  short list[10] = {2, 9, 3, 6, 4, 2, 3, 3, 1, 5};
  int i;
  clrscr ();
  qsort (list, 10, sizeof (short), int_comp);
  for (i = 0; i < 10; i++)
    printf ("%d ", list[i]);
  ngetchx ();
}
Note that the function strcmp is ideal for string comparisons. However, its parameters are not void pointers. This may be solved using a typecast like
qsort (StringArray, NoOfStrings, LenOfEachString, (compare_t) strcmp);

See also: bsearch


rand

rand Function (tigcc.a)
stdlib.h

short rand (void);

Returns a pseudorandom number.

rand uses a linear congruential random number generator to return successive pseudorandom numbers in the range from 0 to RAND_MAX (i.e. from 0 to 32767). It returns the generated pseudorandom number.

Used by: random, tmpnam

See also: srand, randomize, random


random

random Function (Macro)
stdlib.h

short random (short num);

Generates a random integer in a given range.

random is a macro which uses rand to return a random number between 0 and (num-1).

Uses: rand

See also: rand, srand, randomize


randomize

randomize Function (Macro)
stdlib.h

void randomize (void);

Initializes random number generator with a random value.

randomize initializes the random number generator with a random value (picked from the timer).

Uses: srand

See also: rand, random, srand


srand

srand Function (Macro)
stdlib.h

void srand (unsigned long seed);

Initializes random number generator.

The random number generator is reinitialized by calling srand with an argument value of 1. It can be set to a new starting point by calling srand with a given seed number (if an argument is set to seed).

Used by: randomize

See also: rand, random, randomize


strtod

strtod Function (tigcc.a)
AMS 2.00 or higher stdlib.h

double strtod(const char *str, char **endptr);

Converts a string to a floating point value, with optional error-checking.

strtod converts a string pointed to by s to a floating point value. It recognizes the following character representation of a floating point number:

  • an optional string of spaces;
  • an optional minus sign (0xAD character, instead of ordinary '-');
  • a string of digits and an optional decimal point (the digits can be on both sides of the decimal point);
  • an optional exponent followed by a (optionally signed) integer. The exponent character needs to be 0x95, instead of ordinary 'e' or 'E'.
It is easy to "preprocess" any string to satisfy this convention before calling strtod, by code such as the following snippet (assuming that c is a char variable, and i is an integer variable):
for (i = 0; (c = s[i]); i++)
 // Yes, the second '=' is really '=', not '=='...
  {
    if (c == '-') s[i] = 0xAD;
    if ((c|32) == 'e') s[i] = 0x95;
  }
strtod returns the converted value (BCD floating-point number). If endptr is not NULL, the char pointer pointed to by it is assigned the address of the first character of the string following the converted floating-point number. If the conversion fails, 0.0 is returned and *endptr is assigned the value str.
If the result of the conversion would cause overflow, strtod sets errno to ERANGE and returns 9.9999999999999e+999. If the result of the conversion would cause underflow, strtod sets errno to ERANGE and returns 0.

Note: This function is part of AMS, but it is wrapped in the library to prevent a crash when end_ptr == NULL on early AMS 2.xx versions. In fact, atof ends up calling strtod, and using atof takes up more space into your program than strtod does, while not providing the endptr argument, which helps for error checking.

Uses: CTypeTable, errno, push_ulong_to_integer, _bcd_math
Used by: EQU_getNameInfo, push_parse_prgm_or_func_text, cmd_get, push_parse_text

See also: atof, TIOS_strtod


strtol

strtol Function (tigcc.a)
stdlib.h

long strtol (const char *str, char **endptr, short radix);

Converts a string to a long integer using a given radix, with detection of overflows and errors.

strtol converts a character string str to a long integer value. str is a sequence of characters that can be interpreted as a long value. The characters must match this generic format:

[ws] [sn] [0] [x] [ddd]

where

  • [ws] is an optional string of spaces;
  • [sn] is an optional sign ('+', '-', or special "small" minus used in TI-Basic);
  • [0] is an optional zero (0);
  • [x] is an optional 'x' or 'X';
  • [ddd] is an optional string of digits.
strtol stops reading the string at the first character it doesn't recognize.
  • If radix is between 2 and 36, the long integer is expressed in base radix.
  • If radix is 0, the first few characters of str determine the base of the value being converted.

    First character Second character String interpreted as
    0
    0
    1 - 9     		1 - 7
    x or X     		Octal
    Hexadecimal
    Decimal

  • If radix is 1, less than 0 or greater than 36, it is considered to be an invalid value.
The characters are interpreted according to the following table:

Value in str meant to be interpreted as | Resulting Character Recognition
Octal | Any character other than 0 to 7 will be unrecognized.
Decimal | Any character other than 0 to 9 will be unrecognized.
A number in any other base | Only the numerals and letters used to represent numbers in that base will be recognized (for example, if radix equals 5, only 0 to 4 will be recognized; if radix equals 20, only 0 to 9 and A to J will be recognized).

If endptr is not NULL, strtol sets the pointer variable pointed to by endptr to point to the character that stopped the scan (i.e. *endptr = &stopper). strtol returns the value of the converted string, or 0 on error. In a case of overflow, strtol returns LONG_MAX or LONG_MIN, depending of the sign.

Note: strtol is much more flexible than atol (or atoi), but as it is not built-in in the TIOS, usage of it makes the total size of the program much greater.

Uses: _du32u32, _mu32u32


strtoul

strtoul Function (tigcc.a)
stdlib.h

unsigned long strtoul (const char *str, char **endptr, short radix);

Converts a string to an unsigned long integer using a given radix, with detection of overflows and errors.

strtoul operates the same way as strtol, except that it converts a string str to an unsigned long value (where strtol converts to a long). See strtol for more information. In a case of overflow, strtoul returns ULONG_MAX.

Uses: _du32u32, _mu32u32


TIOS_strtod

TIOS_strtod Function (ROM Call 0x4D4*)
AMS 2.00 or higher stdlib.h

double TIOS_strtod(const char *str, char **endptr);

You really should use strtod, 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 strtod. But if you use it on AMS 1.00-2.03, never pass NULL as endptr, otherwise the routine will trigger a crash !

Uses: CTypeTable, errno, push_ulong_to_integer, _bcd_math
Used by: EQU_getNameInfo, push_parse_prgm_or_func_text, cmd_get, push_parse_text

See also: strtod


EXIT_FAILURE

EXIT_FAILURE Constant
stdlib.h

#define EXIT_FAILURE 1

Failure exit code for exit.

EXIT_FAILURE is a constant (here with value 1) which is usually defined in stdlib.h. Its meaning is "the exit code upon failure for exit".


EXIT_SUCCESS

EXIT_SUCCESS Constant
stdlib.h

#define EXIT_SUCCESS 0

Normal exit code for exit.

EXIT_SUCCESS is a constant (here with value 0) which is usually defined in stdlib.h. Its meaning is "the exit code upon success for exit".


RAND_MAX

RAND_MAX Constant
stdlib.h

#define RAND_MAX 32767

Returns the largest number returned by rand.

RAND_MAX is a constant (here with value 32767) which is usually defined in stdlib.h. Its meaning is "the largest number returned by rand".


atexit_t

atexit_t Type (Pointer)
stdlib.h

typedef CALLBACK void (*atexit_t) (void);

Describes an exit function passed to atexit.

atexit_t is a type proposed in ANSI C for defining the type of an exit function passed to atexit.


compare_t

compare_t Type (Pointer)
stdlib.h

typedef CALLBACK short (*compare_t) (const void *elem1, const void *elem2);

Describes a comparison function.

compare_t is a type for defining the type of a comparison function passed to bsearch or qsort.

Note that this type is not ANSI-compliant: It should have a 'long' return value. The reason it does not is that the strcmp function, frequently cast to this type, returns a 'short' value.


div_t

div_t Type (Structure)
stdlib.h, unknown.h

typedef struct {
short quot, rem;
} div_t;

An integer division return type used in the div function.


ldiv_t

ldiv_t Type (Structure)
stdlib.h, unknown.h

typedef struct {
long quot, rem;
} ldiv_t;

A long integer division return type used in the ldiv function.


string.h

string.h Header File
Header File Index

ANSI-compatible string manipulation routines

Functions
_memset
Sets num bytes of buffer to byte c.
CharNumber
Writes an unsigned char in base 10 at given offset from the beginning of a string, and null-terminates the string.
cmpstri
Performs case-insensitive string comparison.
FirstNonblank
Returns a pointer to the first nonblank character in given string.
memchr
Searches the first len bytes of array str for character c.
memcmp
Compares two blocks of signed chars.
memcpy
Copies a block of len bytes from src to dest.
memmove
Copies a block of len bytes from src to dest, with possibility of overlaping of source and destination block.
memset
Sets num bytes of buffer to byte c.
memucmp
Compares two blocks of unsigned chars.
sprintf
Sends formatted output to a string.
strcat
Appends src to dest.
strchr
Finds c in str.
strcmp
Compares one string to another.
strcpy
Copies string src to dest.
strcspn
Scans a string.
strerror
Gives an error message string.
stricmp
Performs case-insensitive string comparison.
strlen
Calculates length of a string.
strncat
Appends at most maxlen characters of src to dest.
strncmp
Compares at most maxlen characters of one string to another.
strncpy
Copies at most maxlen characters of src to dest.
strpbrk
Scans one string for the first occurrence of any character that's in a second string.
strrchr
Finds the last occurrence of c in str.
strspn
Scans a string for a segment that is a subset of a set of characters.
strstr
Finds the first occurrence of a substring in another string.
strtok
Scans s1 for the first token not contained in s2.
Constants
NULL
A null-pointer value.
Predefined Types
size_t
A type to define sizes of strings and memory blocks.


CharNumber

CharNumber Function (ROM Call 0x113)
string.h

unsigned char CharNumber (unsigned char num, unsigned char pos, unsigned char *string);

Writes an unsigned char in base 10 at given offset from the beginning of a string, and null-terminates the string.

CharNumber writes number num as a string, in base 10, at string[pos], and null-terminates string after the number has been printed.
It returns the offset of the terminating null character from the beginning of string.
Of course, CharNumber may be useful only if the number you want to write is in the range of values an unsigned char can represent.

Used by: de_initRes, de_loop, GetStatValue, gr_find_de_result, gr_initCondName, grFuncName, recall_data_var, store_data_var, partial_len


cmpstri

cmpstri Function (ROM Call 0x16F)
string.h

short cmpstri (const unsigned char *s1, const unsigned char *s2);

Performs case-insensitive string comparison.

cmpstri acts like strcmp, but the comparison is case-insensitive. More precisely, it internally converts all uppercase characters to lowercase (unlike stricmp, which converts all lowercase characters to uppercase).

Uses: CTypeTable
Used by: compare_expressions, MO_digestOptions, init_unit_system, setup_unit_system

See also: stricmp, strcmp


FirstNonblank

FirstNonblank Function (ROM Call 0x4DE)
AMS 2.00 or higher string.h

unsigned char *FirstNonblank (unsigned char *s);

Returns a pointer to the first nonblank character in given string.

This function is very limited: it simply searches the string s for blank characters (space, code 0x20), and returns when it finds a character different from 0x20.

Used by: SP_Define, VarNew, VarSaveAs, TokenizeSymName


strcat

strcat Function (ROM Call 0x26E)
string.h

char *strcat (char *dest, const char *src);

Appends src to dest.

strcat appends a copy of src to the end of dest, overwriting the null character terminating the string pointed to by dest. The length of the resulting string is strlen(dest) + strlen(src). strcat returns a pointer to the concatenated strings (this is dest, in fact).

Note: This routine assumes that dest points to a buffer large enough to hold the concatenated string.

Used by: cmd_dialog, cmd_movevar, cmd_prompt, cmd_request, cmd_sinreg, DlgMessage, VarNew, VarOpen, VarSaveAs, TokenizeSymName, EV_defaultHandler, handleVarLinkKey, MO_modeDialog, LIO_Receive, OSLinkCmd, EV_quit, VarSaveTitle, FolderDel, FolderRename, HSymDel, HSYMtoName, SymFindFolderName, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x486, DayOfTheWeek, DateStr, TimeStr


strchr

strchr Function (ROM Call 0x274)
string.h

char *strchr (const char *str, short c);

Finds c in str.

strchr scans a string in the forward direction, looking for a specific character. strchr finds the first occurrence of the character c in the string str. The null-terminator is considered to be part of the string, so that, for example,

strchr (s, 0)
returns a pointer to the terminating null character of the string s. Returns a pointer to the first occurrence of the character c in str. If c does not occur in str, strchr returns NULL.

Used by: VarOpen, index_below_display_expression_aux, Parse1DExpr, TokenizeSymName, handleRclKey, handleVarLinkKey, KeyYesOrNo, push_user_func, EM_moveSymToExtMem, FolderDel, FolderRename, HSymDel, SymFindFolderName


strcmp

strcmp Function (ROM Call 0x271)
string.h

short strcmp (const unsigned char *s1, const unsigned char *s2);

Compares one string to another.

strcmp performs an unsigned comparison of s1 to s2. It starts with the first character in each string and continues with subsequent characters until the corresponding characters differ or until the end of the strings is reached. strcmp returns a value that is

  • < 0 if s1 is less than s2
  • == 0 if s1 is the same as s2
  • > 0 if s1 is greater than s2
More precisely, if the strings differ, the value of the first nonmatching character in s2 subtracted from the corresponding character in s1 is returned.

Note: This routine is declared as "short" although the ANSI standard proposes "long". This is important, because TIOS the strncmp routine puts garbage in the higher half of the d0 register.

Used by: cmd_movevar, VarOpen, LoadDLL, compare_expressions, EV_getAppID, MO_currentOptions, MO_digestOptions, FFindFirst, FFindNext, FOpen, OSLinkCmd, sendcalc, GraphOrTableCmd, OO_AppNameToACB, tokenize_if_TI_92_or_text, FolderCur, FolderOp, IsMainFolderStr, SymFindFirst, SymSysVar, VarRecall, VarStore, ROM Call 0x131

See also: strncmp, cmpstri, stricmp


strcpy

strcpy Function (ROM Call 0x26C)
string.h

char *strcpy (char *dest, const char *src);

Copies string src to dest.

strcpy copies string src to dest, stopping after the terminating null character has been moved. Returns dest.

Note: If the objects pointed to by src and dest overlap in memory, the behavior is undefined. strcpy assumes that src points to a buffer large enough to hold dest.


strcspn

strcspn Function (ROM Call 0x275)
string.h

unsigned long strcspn (const char *s1, const char *s2);

Scans a string.

strcspn returns the length of the initial segment of string s1 that consists entirely of characters not from string s2. If string s1 contains no characters from string s2, strcspn returns the length of string s1.


stricmp

stricmp Function (ROM Call 0x407)
AMS 2.00 or higher string.h

short stricmp (const unsigned char *s1, const unsigned char *s1);

Performs case-insensitive string comparison.

stricmp acts like strcmp, but the comparison is case-insensitive. More precisely, it internally converts all lowercase characters to uppercase (unlike cmpstri, which converts all uppercase characters to lowercase).

Note: This function is buggy in the AMS versions 2.00 through 2.03: If s1 contains characters above 127 (i.e. extended/international characters), and these characters are really needed for the comparison, it always returns a negative value. So, if you really need to use this function, make sure that you never call it with such characters in s1.

Uses: CTypeTable
Used by: cmd_style, OO_AppNameToACB, ROM Call 0x131, ROM Call 0x4F6

See also: cmpstri, strcmp


strlen

strlen Function (ROM Call 0x27E)
string.h

unsigned long strlen (const char *str);

Calculates length of a string.

strlen calculates the length of str. Returns the number of characters in str, not counting the terminating null character.

Used by: HeapWalk, cmd_custom, cmd_cyclepic, cmd_dialog, cmd_input, cmd_inputstr, cmd_movevar, cmd_pause, cmd_popup, cmd_prompt, cmd_request, cmd_toolbar, push_string, Dialog, DialogAdd, VarNew, VarOpen, VarSaveAs, index_below_display_expression_aux, Parse2DExpr, Parse2DMultiExpr, TokenizeSymName, handleRclKey, handleVarLinkKey, FClose, FFindFirst, FOpen, DrawStrWidth, HomeExecute, HomePushEStack, LIO_Get, LIO_Send, OSLinkCmd, DynMenuAdd, DynMenuChange, MenuKey, PopupClear, PopupNew, ST_folder, sprintf, AB_serno, TE_handleEvent, TE_open, TE_openFixed, GetTagStr, gr_de_axes_lbl, gr_DispLabels, hStrAppend, push_var, SP_Define, tokenize_if_TI_92_or_text, VarSaveTitle, SmapTypeStrings, StrToTokN, SYMSTR, ROM Call 0x40E, ROM Call 0x421, ROM Call 0x502


strncat

strncat Function (ROM Call 0x26F)
string.h

char *strncat (char *dest, const char *src, unsigned long maxlen);

Appends at most maxlen characters of src to dest.

strncat copies at most maxlen characters of src to the end of dest and then appends a null character. The null character terminating src is overwritten by the first character in dest. The maximum length of the resulting string is strlen(dest) + maxlen. strncat returns dest.

Note: This routine assumes that src points to a buffer large enough to hold the concatenated string. Since strncat appends a null character to the result, it may add maxlen+1 characters to the string.


strncmp

strncmp Function (ROM Call 0x272)
string.h

short strncmp (const unsigned char *s1, const unsigned char *s2, unsigned long maxlen);

Compares at most maxlen characters of one string to another.

strncmp makes the same unsigned comparison as strcmp, but looks at no more than maxlen characters. It starts with the first character in each string and continues with subsequent characters until the corresponding characters differ or until it has examined maxlen characters. strncmp returns an int value based on the result of comparing s1 (or part of it) to s2 (or part of it):

  • < 0 if s1 is less than s2
  • == 0 if s1 is the same as s2
  • > 0 if s1 is greater than s2
More precisely, if the strings differ, the value of the first nonmatching character in s2 subtracted from the corresponding character in s1 is returned. The subtraction casts the input strings to unsigned chars so that the characters in the range 128..255 are considered above the characters in the range 0..127.

Note: This routine is declared as "short" although the ANSI standard proposes "long". This is important, because TIOS the strncmp routine puts garbage in the higher half of the d0 register.

Used by: TIOS_EV_getAppID

See also: strcmp


strncpy

strncpy Function (ROM Call 0x26D)
string.h

char *strncpy (char *dest, const char *src, unsigned long maxlen);

Copies at most maxlen characters of src to dest.

strncpy copies up to maxlen characters from src into dest, truncating or null-padding dest. The target string, dest, might not be null-terminated if the length of src is maxlen or more. Returns dest.

Note: If the objects pointed to by src and dest overlap in memory, the behavior is undefined. strcpy assumes that src points to a buffer large enough to hold maxlen characters.

Used by: cmd_dialog, cmd_request, DlgMessage, handleVarLinkKey, LIO_Get, LIO_Receive, DynMenuAdd, DynMenuChange, PopupClear, PopupNew, ERD_notice, OO_GetAttr, EM_moveSymToExtMem, TokToStrN


strpbrk

strpbrk Function (ROM Call 0x276)
string.h

char *strpbrk (const char *s1, const char *s2);

Scans one string for the first occurrence of any character that's in a second string.

strpbrk scans a string, s1, for the first occurrence of any character appearing in s2. strpbrk returns a pointer to the first occurrence of any of the characters in s2. If none of the s2 characters occurs in s1, it returns NULL.

Used by: fopen


strrchr

strrchr Function (ROM Call 0x277)
string.h

char *strrchr (const char *str, short c);

Finds the last occurrence of c in str.

strrchr scans a string in the reverse direction, looking for a specific character. strrchr finds the last occurrence of the character c in the string str. The null-terminator is considered to be part of the string. strrchr returns a pointer to the last occurrence of the character c. If c does not occur in str, strrchr returns NULL.


strspn

strspn Function (ROM Call 0x278)
string.h

unsigned long strspn (const char *s1, const char *s2);

Scans a string for a segment that is a subset of a set of characters.

strspn finds the initial segment of string s1 that consists entirely of characters from string s2. Returns the length of the initial segment of s1 that consists of characters entirely from s2. If s1 contains no characters from s2, NULL is returned.


strstr

strstr Function (ROM Call 0x279)
string.h

char *strstr (const char *str, const char *substr);

Finds the first occurrence of a substring in another string.

strstr scans str for the first occurrence of the substring substr. strstr returns a pointer to the element in str where substr begins (points to substr in str). If substr does not occur in str, strstr returns NULL.


strtok

strtok Function (ROM Call 0x27A)
string.h

char *strtok (char *s1, const char *s2);

Scans s1 for the first token not contained in s2.

strtok considers the string s1 to consist of a sequence of zero or more text tokens, separated by spans of one or more characters from the separator string s2. The first call to strtok returns a pointer to the first character of the first token in s1 and writes a null character into s1 immediately following the returned token. Subsequent calls with NULL for the first argument will work through the string s1 in this way, until no tokens remain. The separator string, s2, can be different from call to call. strtok returns a pointer to the token found in s1. A null pointer is returned when there are no more tokens.


system.h

system.h Header File
Header File Index

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.
TIOS_OSVFreeTimer
Frees an event (vectored) timer.
TIOS_OSVRegisterTimer
Registers an event (vectored) timer.
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

AB_getGateArrayVersion Function (ROM Call 0x15E)
AMS 2.00 or higher system.h

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.

Uses: FL_getHardwareParmBlock
Used by: OSContrastDn, OSContrastUp, ABT_dialog, EV_defaultHandler, LIO_Receive, OSLinkCmd, EV_quit, EM_getArchiveMemoryBeginning, DateAndTime_SetDlg, ClockOn

See also: FL_getHardwareParmBlock


AB_prodid

AB_prodid Function (ROM Call 0x29D)
system.h

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.

Uses: cfindfield, cgetfnl, copen, copensub, FlashMemoryEnd, sprintf
Used by: ABT_dialog


AB_prodname

AB_prodname Function (ROM Call 0x29E)
system.h

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.

Uses: cfindfield, copen, copensub, FlashMemoryEnd, memcpy
Used by: ABT_dialog


AB_serno

AB_serno Function (ROM Call 0x29F)
system.h

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.

Uses: cgetsn, FL_getVerNum, memmove, sprintf, strlen
Used by: ABT_dialog


ASM_call

ASM_call Function (Macro)
system.h

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.

Uses: ASM_fastcall


ASM_fastcall

ASM_fastcall Function (Macro)
system.h

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!

Used by: ASM_call


CB_fetchTEXT

CB_fetchTEXT Function (ROM Call 0xC2)
system.h

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.

Used by: TE_handleEvent

See also: CB_replaceTEXT


CB_replaceTEXT

CB_replaceTEXT Function (ROM Call 0xC1)
system.h

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.

Uses: HeapRealloc, memcpy
Used by: TE_handleEvent

See also: CB_fetchTEXT


CU_restore

CU_restore Function (ROM Call 0xC3)
system.h

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.

Uses: CU_cursorState, OSTimerRestart
Used by: Dialog, EV_defaultHandler, EV_setFKeyState, handleVarLinkKey, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, GT_KeyIn, ROM Call 0x3EA, ROM Call 0x421


CU_start

CU_start Function (ROM Call 0xC4)
system.h

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.

Uses: CU_cursorState, OSTimerRestart
Used by: TE_focus, TE_handleEvent, TE_pasteText, GT_KeyIn, ROM Call 0x3EA


CU_stop

CU_stop Function (ROM Call 0xC5)
system.h

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.

Uses: CU_cursorState
Used by: Dialog, handleVarLinkKey, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, TE_handleEvent, TE_pasteText, TE_unfocus, GT_KeyIn, ROM Call 0x421


enter_ghost_space

enter_ghost_space Function (tigcc.a)
system.h

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.


EX_getBasecodeParmBlock

EX_getBasecodeParmBlock Function (ROM Call 0x5DA)
AMS 2.04 or higher system.h

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

EX_patch Function (ROM Call 0x15A)
system.h

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!

Used by: LoadDLL, push_user_func

See also: enter_ghost_space, EXECUTE_IN_GHOST_SPACE


HelpKeys

HelpKeys Function (ROM Call 0x181)
system.h

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.

Uses: XR_stringPtr, GKeyIn, ST_helpMsg, MakeWinRect, WinActivate, WinCharXY, WinClose, WinClr, WinFont, WinOpen, WinRect, WinStrXY
Used by: EV_defaultHandler


idle

idle Function (ROM Call 0x29B)
system.h

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.

Used by: cmd_cyclepic, cmd_disptbl, cmd_pause, cmd_sendcalc, cmd_sendchat, EV_eventLoop, EV_getc, GS_PlotAll, GT_Trace, GZ_Stat, Regraph


kbd_queue

kbd_queue Function (tigcc.a)
system.h

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

LOC_formatDate Function (ROM Call 0x590)
AMS 2.02 or higher system.h

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.

Uses: sprintf
Used by: LOC_localVersionDate

See also: LOC_getLocalDateFormat, LOC_localVersionDate


LOC_getLocalDateFormat

LOC_getLocalDateFormat Function (ROM Call 0x58F)
AMS 2.02 or higher system.h

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);

Used by: LOC_localVersionDate

See also: LOC_formatDate, LOC_localVersionDate


LOC_localVersionDate

LOC_localVersionDate Function (ROM Call 0x591)
AMS 2.02 or higher system.h

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);

Uses: LOC_formatDate, LOC_getLocalDateFormat
Used by: ABT_dialog

See also: LOC_formatDate, LOC_getLocalDateFormat


NeedStack

NeedStack Function (ROM Call 0xA4)
system.h

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.

Used by: HeapAlloc, HeapAllocESTACK, HeapAllocHigh, HeapAllocPtr, HeapCompress, HeapFree, HeapMoveHigh, HeapRealloc, malloc, cmd_custom, cmd_dialog, cmd_request, cmd_toolbar, Parse2DExpr, Parse2DMultiExpr, handleRclKey, handleVarLinkKey, getcalc, GraphActivate, VarStore, ROM Call 0x438


off

off Function (ROM Call 0x29A)
system.h

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.

Used by: cmd_disptbl, cmd_pause, push_getkey, ERD_dialog, EV_defaultHandler, EV_eventLoop, EV_getc, LIO_RecvData, OSLinkOpen, GS_PlotAll, GZ_Stat, Regraph, ROM Call 0x3EA


OSCheckBreak

OSCheckBreak Function (ROM Call 0xEC)
system.h

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.

Used by: cmd_circle, cmd_cyclepic, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_linetan, cmd_shade, cmd_slpline, push_determinant, push_red_row_ech, push_row_echelon, push_simult, push_between, push_parse_text, dv_create_graph_titles, EQU_getNameInfo, GM_TanLine, push_parse_prgm_or_func_text, push_simplify_statements, push_sq_matrix_to_whole_number


OSClearBreak

OSClearBreak Function (ROM Call 0xED)
system.h

void OSClearBreak (void);

Clears "BREAK key pressed" flag.

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

Used by: EV_defaultHandler, EV_eventLoop, handleVarLinkKey, HomeExecute, LIO_Get, LIO_Receive, LIO_RecvData, LIO_Send, LIO_SendProduct, EV_quit, GR3_handleEvent, GT_Trace, DateAndTime_SetDlg


OSContrastAddress

OSContrastAddress Function (Macro)
system.h

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

OSContrastDn Function (ROM Call 0x297*)
system.h

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.

Uses: AB_getGateArrayVersion

See also: OSContrastUp, OSContrastAddress, OSContrastValue


OSContrastUp

OSContrastUp Function (ROM Call 0x296*)
system.h

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.

Uses: AB_getGateArrayVersion

See also: OSContrastDn, OSContrastAddress, OSContrastValue


OSdequeue

OSdequeue Function (ROM Call 0x3AA)
AMS 1.01 or higher system.h

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.

Used by: ngetchx, pushkey

See also: OSenqueue, kbd_queue


OSDisableBreak

OSDisableBreak Function (ROM Call 0xEF)
system.h

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.

Used by: display_statements, Parse1DExpr, Parse2DMultiExpr, TokenizeSymName, handleVarLinkKey, tokenize_if_TI_92_or_text, FolderDel, FolderRename, HSymDel, SymFindFolderName

See also: OSEnableBreak


OSEnableBreak

OSEnableBreak Function (ROM Call 0xEE)
system.h

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.

Used by: display_statements, Parse1DExpr, Parse2DMultiExpr, TokenizeSymName, EV_eventLoop, handleVarLinkKey, tokenize_if_TI_92_or_text, FolderDel, FolderRename, HSymDel, SymFindFolderName

See also: OSDisableBreak


OSenqueue

OSenqueue Function (ROM Call 0x3A9)
AMS 1.01 or higher system.h

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.

Used by: pushkey, OSLinkCmd

See also: OSdequeue


OSFreeTimer

OSFreeTimer Function (ROM Call 0xF1)
system.h

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.

Used by: cmd_cyclepic, cmd_sendcalc, cmd_sendchat, BatTooLowFlash, LIO_RecvData, LIO_SendData, OSLinkOpen, GT_Trace, Regraph


OSqclear

OSqclear Function (ROM Call 0x3AD)
AMS 1.01 or higher system.h

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}.

Used by: OSLinkCmd, ROM Call 0x473

See also: OSenqueue


OSqhead

OSqhead Function (ROM Call 0x3AC)
AMS 1.01 or higher system.h

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

OSqinquire Function (ROM Call 0x3AB)
AMS 1.01 or higher system.h

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.

Used by: kbhit, OSLinkCmd

See also: OSenqueue


OSRegisterTimer

OSRegisterTimer Function (ROM Call 0xF0)
system.h

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:

  • 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.

Used by: cmd_cyclepic, cmd_sendcalc, cmd_sendchat, BatTooLowFlash, LIO_RecvData, GT_Trace, Regraph

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


OSReset

OSReset Function (ROM Call 0x294)
system.h

void OSReset (void);

Resets the calculator.

OSReset resets the calculator without any warnings.


OSSetSR

OSSetSR Function (ROM Call 0x29C)
system.h

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.

Used by: Dialog, ERD_dialog, HomeExecute, kbhit, ngetchx, pushkey, ROM Call 0x3EA


OSTimerCurVal

OSTimerCurVal Function (ROM Call 0xF2)
system.h

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

OSTimerExpired Function (ROM Call 0xF3)
system.h

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.

Used by: cmd_cyclepic, cmd_disptbl, cmd_pause, cmd_sendcalc, cmd_sendchat, push_getkey, EV_eventLoop, EV_getc, BatTooLowFlash, LIO_RecvData, OSLinkOpen, GS_PlotAll, GT_Trace, GZ_Stat, Regraph


OSTimerRestart

OSTimerRestart Function (ROM Call 0xF4)
system.h

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.

Used by: CU_restore, CU_start, cmd_disptbl, cmd_pause, push_getkey, Dialog, ERD_dialog, EV_eventLoop, EV_getc, ngetchx, LIO_RecvData, OSLinkOpen, GS_PlotAll, GZ_Stat, Regraph


OSVFreeTimer

OSVFreeTimer Function* (tigcc.a)
system.h

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


OSVRegisterTimer

OSVRegisterTimer Function* (tigcc.a)
system.h

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


QModeKey

QModeKey Function (ROM Call 0x182)
system.h

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.

Uses: WordInList
Used by: GT_KeyIn, ROM Call 0x3EA


QSysKey

QSysKey Function (ROM Call 0x183)
system.h

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).

Uses: WordInList
Used by: ROM Call 0x3EA


SumStoChkMem

SumStoChkMem Function (ROM Call 0x295)
system.h

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).

Uses: ROM Call 0x441


TIOS_OSVFreeTimer

TIOS_OSVFreeTimer Function (ROM Call 0x285)
system.h

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


TIOS_OSVRegisterTimer

TIOS_OSVRegisterTimer Function (ROM Call 0x284)
system.h

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


WordInList

WordInList Function (ROM Call 0x184)
system.h

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.

Used by: QModeKey, QSysKey, cmd_disptbl


XR_stringPtr

XR_stringPtr Function (ROM Call 0x293*)
system.h

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.

Uses: EV_runningApp, OO_CondGetAttr
Used by: HelpKeys, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_pause, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_showstat, cmd_sinreg, cmd_twovar, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_comb, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_gettype, push_im, push_integer_lcm, push_is_prime, push_lim, push_max, push_min, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_rotate, push_shift, push_sign, push_sin2, push_solve, push_summation, push_tan, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_or, push_product, push_sum, push_to_cylin, push_to_sphere, Dialog, VarNew, VarOpen, VarSaveAs, ERD_dialog, find_error_message, compare_complex_magnitudes, get_key_ptr, index_below_display_expression_aux, Parse2DExpr, Parse2DMultiExpr, push_overflow_to_infinity, ABT_dialog, EV_defaultHandler, EV_eventLoop, EV_sendString, handleVarLinkKey, MO_currentOptions, MO_digestOptions, GD_Circle, GD_Eraser, GD_HVLine, GD_Line, GD_Pen, GD_Select, GD_Text, GR3_paint3d, GZ_Box, HomeExecute, HomePushEStack, KeyYesOrNo, LIO_Receive, OSLinkCmd, MenuKey, VarCreateFolderPopup, ST_eraseHelp, ST_precision, sprintf, TE_handleEvent, add_to_top, are_units_consistent, compare_numbers, DataTypeNames, EQU_deStatus, EQU_getNameInfo, EV_quit, get_ub, GetTagStr, GM_Shade, GR3_addContours, GT_DE_Init_Conds, GT_FreeTrace, GT_Trace, GZ_InOut, GZ_Integer, index_if_pushed_qquad_info, init_unit_system, next_token, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, push_unit_system_list, push_var, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, setup_unit_system, SP_Define, spike_optionD, times_top, tokenize_if_TI_92_or_text, VarSaveTitle, SmapTypeStrings, SymFindPtr, VarRecall, VarStore, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x40C, ROM Call 0x41E, ROM Call 0x41F, ROM Call 0x421, ROM Call 0x486, push_no_solution_found_string, ROM Call 0x4D5, ROM Call 0x4E6, ROM Call 0x502, TimeStr


CTypeTable

CTypeTable Variable (Macro)
system.h

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.

Used by: EQU_getNameInfo, GetStatValue, gr_del_locals, GT_Trace, init_unit_system, next_token, nonblank, ParseSymName, push_format, push_parse_prgm_or_func_text, push_user_func, push_var, setup_unit_system, is_independent_of_de_seq_vars, push_parse_text, handleVarLinkKey, MO_digestOptions, GD_Text, MenuKey, ST_folder, sprintf, cmpstri, stricmp, TE_handleEvent, CheckSysFunc, FolderCurTemp, StrToTokN, ValidateSymName, VarRecall, VarStore, ROM Call 0x421, strtod


CU_cursorState

CU_cursorState Variable (ROM Call 0x503)
AMS 2.00 or higher system.h

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.

Used by: CU_restore, CU_start, CU_stop, EV_defaultHandler, EV_eventLoop, EV_getc, EV_setFKeyState, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, ROM Call 0x3EA, ROM Call 0x421

See also: CU_restore, CU_start, CU_stop


FiftyMsecTick

FiftyMsecTick Variable (ROM Call 0x4FC)
AMS 2.00 or higher system.h

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

OSContrastValue Variable (Macro)
system.h

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

OSOnBreak Variable (ROM Call 0x46E)
AMS 2.00 or higher system.h

unsigned char OSOnBreak;

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

Used by: GR3_addContours, GS_PlotAll, GZ_Stat, Regraph, cmd_disptbl, cmd_pause, GR3_paint3d, LIO_RecvData, LIO_Send, OSLinkClose, OSLinkCmd, OSLinkOpen, ROM Call 0x473

See also: OSCheckBreak, OSClearBreak


ReleaseDate

ReleaseDate Variable (ROM Call 0x43F)
system.h

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).

Uses: _memset
Used by: ReleaseVersion

See also: ReleaseVersion


ReleaseVersion

ReleaseVersion Variable (ROM Call 0x440)
system.h

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.

Uses: ReleaseDate
Used by: ABT_dialog

See also: ReleaseDate


BASECODE_PARM_BLOCK

BASECODE_PARM_BLOCK Type (Structure)
AMS 2.04 or higher system.h

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

DEF_QUEUE Type (Structure)
system.h

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 (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.


QUEUE

QUEUE Type (Structure constructor)
system.h

#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

Timer_Callback_t Type (Pointer)
system.h

typedef CALLBACK void (*Timer_Callback_t) (void);

Describes a timer callback function.

Timer_Callback_t describes a timer callback function for OSVRegisterTimer.


Timers

Timers Type (Enumeration)
system.h

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.


textedit.h

textedit.h Header File
Header File Index

Routines to access the text editor

Functions
TE_checkSlack
Reallocates the text editor buffer if there is not much space left in it.
TE_close
Closes the text editor.
TE_empty
Empties the text editor buffer.
TE_focus
Highlightes the selected text in the editor, and gives the focus to it.
TE_handleEvent
Dispatches an event to the text editor to be processed by it.
TE_indicateReadOnly
Indicates read-only mode of the editor.
TE_isBlank
Check whether the editor buffer is empty.
TE_open
Initializes the text editor.
TE_openFixed
Initializes the text editor, with fixed buffer.
TE_pasteText
Pastes a text into the editor.
TE_reopen
Re-opens the text editor.
TE_reopenPlain
Re-opens the text editor (plain).
TE_select
Selects a block of text in the editor, or positions the cursor.
TE_shrinkWrap
Shrinks the text editor buffer.
TE_unfocus
Removes the focus from the selected text in the editor.
TE_updateCommand
Updates the command byte in the current line of the text.
Constants
TE_FAR_RIGHT
A constant defining the last cursor position in TE_open.
Predefined Types
Bool
An enumeration to describe true or false values.
ETE_FLAGS
Enumerates optional features for the TE_open function.
EVENT
A structure describing an event message.
HANDLE
Represents a handle associated with an allocated memory block.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
size_t
A type to define sizes of strings and memory blocks.
TEXT_EDIT
A structure used to coordinate all text editor operations.
WIN_RECT
A structure for defining a rectangular area.
WINDOW
The main window-describing structure.


TE_checkSlack

TE_checkSlack Function (ROM Call 0xA6)
textedit.h

void TE_checkSlack (TEXT_EDIT *te);

Reallocates the text editor buffer if there is not much space left in it.

TE_checkSlack checks how much free space is present in the text editor buffer (associated with the structure pointed to by te). If there is not much space left, then the buffer is reallocated (expanded). Note that the editor will expand buffer if necessary during normal processing of keypresses using TE_handleEvent, so the user need not to call this function, except if it is necessary to check and eventually expand the buffer independently of event dispatching procedure. Of course, the editor must not be opened with TE_openFixed if you want to use this function.

Uses: HeapRealloc, reset_estack_size
Used by: TE_empty, TE_handleEvent, TE_open, TE_pasteText, TE_reopen, TE_reopenPlain


TE_close

TE_close Function (ROM Call 0xA5)
textedit.h

void TE_close (TEXT_EDIT *te);

Closes the text editor.

TE_close closes the text editor structure pointed to by te. I am not sure whether calling this routine is necessary: it performs mainly some irrelevant operations (like calling TE_unfocus). I also know that TE_close tries to free the memory occupied by the buffer (by calling HeapFreeIndir) if the editor was opened using TE_openFixed, and if the buffer was allocated dinamically. So, it seems that it tries to close out a text edit record and to release its memory automatically. It seems better to me to release the memory manually (it is more safe anyway).

Uses: TE_unfocus, HeapFreeIndir
Used by: cmd_input, cmd_inputstr, cmd_prompt, Dialog, GT_Trace


TE_empty

TE_empty Function (ROM Call 0xA7)
textedit.h

void TE_empty (TEXT_EDIT *te);

Empties the text editor buffer.

TE_empty empties the text editor buffer (associated with the structure pointed to by te). Note that this routine turns off cursor blink before emptying the edit buffer, but does not repaint the edit region. It only makes its parent window dirty (i.e. clears its WF_DIRTY bit) so, the edit region will be eventually updated when the next paint message arrives.

Uses: TE_checkSlack, TE_unfocus


TE_focus

TE_focus Function (ROM Call 0xA8)
textedit.h

short TE_focus (TEXT_EDIT *te);

Highlightes the selected text in the editor, and gives the focus to it.

TE_focus is usually called after TE_select. It highlightes the selected text in the editor (associated with the structure pointed to by te), and gives the focus to it, so the selected text will become active (after this, any keypress will replace selected text with the newly pressed key). Returns TRUE if focusing was performed, and returns FALSE if not (for example, if the text was already focused).

Note: TE_focus also enables the cursor using CU_start if it was disabled. So, it is sometimes used after calling TE_select with Low == High, just to display the cursor.

Uses: CU_start, sf_width, WinBegin, WinFill, ROM Call 0x471
Used by: TE_handleEvent, TE_reopen, TE_reopenPlain, TE_select, cmd_disphome, cmd_input, cmd_inputstr, cmd_prompt, Dialog, EV_defaultHandler, HomeExecute, EV_quit, GT_Trace


TE_handleEvent

TE_handleEvent Function (ROM Call 0xA9)
textedit.h

short TE_handleEvent (TEXT_EDIT *te, EVENT *event);

Dispatches an event to the text editor to be processed by it.

The text editor is an event driven application (see events.h for more info about events). It does not have a "main loop" in which keypresses are collected and processed. Instead, the user need to collect keypresses, and to dispatch them to the editor using TE_handleEvent. The editor will then process the keypress (for example, it will insert a new character, delete a character, scroll the editor area upwards/downwards etc. depending of the concrete keypress). In other words, the "main loop" is part of the user program. This approach is much more flexible, because the user may decide which keys will be processed and which will not be, and the user may program a lot of special actions which are not pre-programmed in the editor. For example, the user can redefine keys, forbid all keys except uppercase letters, etc. TE_handleEvent returns TRUE if the event was sucessfully processed by the editor, else returns FALSE.

TE_handleEvent needs a pointer to the editor control structure te, and a pointer to the EVENT structure event which represents the event to be processed. Basically, after calling TE_open, the program should enter a loop which does keyboard reading, and sending (wanted) keypress events to the editor using TE_handleEvent. The keyboard may be read using ngetchx, but this requires manual converting of integer keycode to an event structure. It is better idea to use EV_getc which is similar to ngetchx but in addition to the returned keycode, it also fills as an event structure. So, the text editor operations should be programmed as follows:

EVENT ev;
TEXT_EDIT te;
HANDLE h = HeapAlloc (200);                     // initial buffer size
memset (HeapDeref (h), 0, 200);

TE_open (&te, DeskTop, MakeWinRect (30, 30, 130, 70), h, 0, 0, 3);

CU_start ();                                    // Enable the cursor

while (EV_getc (ACTIVITY_BUSY, &ev) != KEY_ESC) // Get keypress and translate it to
  {                                             //   the event (until ESC pressed)
    TE_handleEvent (&te, &ev);                  // Send the event to the editor
  }                                             //   to be processed
In this example, all keypresses are passed to the editor. This need not to be always true; in fact, the main loop may contain whatever the user wants. The editor can handle a lot of special keypresses, like marking with shift+arrows, cut, copy and paste operations etc, not only inserting, deleting and scrolling (note that you can later access the clipboard using CB_fetchTEXT and CB_replaceTEXT if necessary). However, TE_handleEvent cannot handle keypresses which represents tokens (like "sin" etc.) nor system keypresses which open menus like "CHAR" etc. Fortunately, this problem can be solved easily (see the next example).

The example given above is not a typical example of event driven program. All events in this example are restricted to simple keypresses. Typical event driven program uses EV_eventLoop function, which is an endless loop in which all timers, I/O ports etc. are checked for every possible event, and when an event appears, it is dispatched to the active application. The program need to install an event handler using EV_captureEvents function, which will capture all events, and which need to decide what to do with every particular event. This approach is used in the following example, which is written in typical "event driven" maneer. In this example (extracted from the "Text Editor" example), all events are dispatched to the text editor, except pressing the ESC key (this event will exit the event loop), and all events which were not processed sucessfully by the editor are dispatched to the default event handler (see EV_defaultHandler) which for example split tokens to single characters, open menus, etc:
TEXT_EDIT te;

CALLBACK void EventHandler(EVENT *ev)
{
  if (ev->Type == CM_KEYPRESS && ev->extra.Key.Code == KEY_ESC)
    ER_throw (1);
  if (!TE_handleEvent (&te, ev))
    EV_defaultHandler (ev);
}

void _main(void)
{
  HANDLE h = HeapAlloc (200);
  ...
  memset (HeapDeref (h), 0, 200);
  TE_open (&te, DeskTop, MakeWinRect (30, 30, 130, 70), h, 0, 0, 3);
  CU_start ();
  EV_captureEvents (EventHandler);
  TRY
    EV_eventLoop ();           // The only way to exit from "EV_eventLoop" is
  ONERR                        //   to throw an error from the event handler
    EV_captureEvents (NULL);
  ENDTRY
  ...
}
So, event driven programs using the text edit manager typically process events in three phases. First, the application event handler examines the event for action it needs to take. Either the application handler handles the event and returns to the event manager or it proceeds further. Second, the application event handler calls TE_handleEvent to allow the text edit manager to process the event. Either TE_handleEvent handles the event and returns TRUE, or it does not understand the event and returns FALSE. If TE_handleEvent does not handle the event, the application proceeds further. Third, the application calls EV_defaultHandler to let the event manager have one last try at handling the event. System-wide default behavior is implemented in EV_defaultHandler. Programs may drive the text editor by calling TE_handleEvent with their own created event messages (as in previous example), but in practice, the application just forwards events it received from the event manager (i.e. from the EV_eventLoop loop). Also note that calling TE_handleEvent may cause the heap compression.

Beware that EV_eventLoop is an endless loop, so the only way to exit from it is to throw an error from the event handler. This error will be captured later by a TRY ... ONERR ... ENDTRY construction.

Note: For the most of applications, you need not to use any text editor functions except TE_open (or TE_openFixed) and TE_handleEvent, because TE_handleEvent can do even relatively complicated operations like cut/copy/paste, etc. Other text editor functions are needed only if the user wants to program some special actions.

Uses: TE_checkSlack, TE_focus, TE_pasteText, TE_select, TE_unfocus, HeapFree, HeapLock, HeapMoveHigh, HeapRealloc, HeapUnlock, HLock, Dialog, DlgMessage, ERD_dialog, display_statements, HToESI, EV_paintWindows, HS_getEntry, memmove, strlen, CB_fetchTEXT, CB_replaceTEXT, CU_start, CU_stop, XR_stringPtr, CTypeTable, EV_errorCode, sf_width, WinBegin, WinChar, WinFill, WinScrollV, _du16u16, _mu16u16, ROM Call 0x412, ROM Call 0x471
Used by: HomeExecute


TE_indicateReadOnly

TE_indicateReadOnly Function (ROM Call 0xAA)
textedit.h

void TE_indicateReadOnly (TEXT_EDIT *te);

Indicates read-only mode of the editor.

TE_indicateReadOnly indicates read-only mode of the editor (associated with the structure pointed to by te) by disabling commands "Cut", "Paste", "Clear" and "Del" in all menus registred with the current applications (see EV_registerMenu), and setting the status line (using ST_readOnly). Note that this command works only if the editor is opened in read-only mode (i.e. if TE_READ_ONLY is set in the parameter Flags of the TE_open function). Also note that you need to call ST_readOnly manually later, when you decide to remove the read-only indicator from the status line.

Uses: EV_setCmdState, ST_readOnly


TE_isBlank

TE_isBlank Function (ROM Call 0xAB)
textedit.h

short TE_isBlank (TEXT_EDIT *te);

Check whether the editor buffer is empty.

TE_isBlank returns TRUE if the text editor buffer (associated with the structure pointed to by te) is empty, else returns FALSE. Note that the content of the editor is regarded as "blank" if there is no characters in it, or if all characters in it are blanks (spaces).

Used by: cmd_input, cmd_inputstr, cmd_prompt, HomeExecute


TE_open

TE_open Function (ROM Call 0xAC)
textedit.h

short TE_open (TEXT_EDIT *te, WINDOW *w, WIN_RECT *rect, HANDLE BufHandle, unsigned short cur_offset, unsigned short ReadOnly, unsigned short Flags);

Initializes the text editor.

TE_open initializes the text editor and displays the initial contents of the editor. All text editor operations are controled using a structure of type TEXT_EDIT. TE_open will initialize such a structure pointed to by the parameter te, which later needs to be passed to all text editor operations (i.e. te must be allocated statically to maintain state between calls to the text edit routines). It returns TRUE if the edit buffer could be allocated, or FALSE if there is insufficient memory to allocate the edit buffer. This routine always returns TRUE if BufHandle is passed in with the handle to a text buffer.

Note: The window w must already be open. The handle BufHandle must not be locked.

This routine may cause heap compression.

w is a pointer to the parent window of the editor: you can create a new window to be the parent using WinOpen, or you can pass DeskTop as the parameter, if you are happy with its settings (which is usually the case). rect is a pointer to the WIN_RECT structure which describes the actual dimensions of the rectangular text editor area (You can pass NULL to use entire client rectangle of the window w for the edit region). Note that if you use your own window as a parent window, this window must not be "dirty" (i.e. it must not have the WF_DIRTY flag set). Windows created by WinOpen are "dirty" by default, so you need to clear the "dirty" flag manually before calling TE_open. For example, you can do

w->Flags &= ~WF_DIRTY;
BufHandle is the handle of the text editor buffer, which may be pre-filled with the text (if you want to edit existing text), or filled with zeros (if you want to create a new text). BufHandle may be, for example, the result of a HeapAlloc operation. BufHandle can also be H_NULL, in this case TE_open will allocate a new handle and initialize it with no text. Note that contrary to what I said in the documentation of TIGCCLIB releases prior to 2.2, it cannot be a handle of a text variable, because text variables contain additional system data on the begining, and the editor expect raw data (see the Frequently Asked Questions to learn how you can pass a text variable to the editor though).

The contents of the text buffer are a standard zero-terminated string, in which lines of text are separated with '\r' characters (0xD). The size of the buffer is managed automatically by the editor: it will be expanded if necessary to add more text, so you need not to worry about the allocated size.

The parameter cur_offset is the initial position of the cursor (counted from the begining of the buffer). Position 0 is to the left of the first character. If the contents of the text edit buffer are too long to display entirely in the edit region, the text is scrolled to make sure the cursor is visible. Set cur_offset to TE_FAR_RIGHT to place the edit cursor after the last character in the edit buffer.

The parameter ReadOnly is the count of characters at the begining of the buffer which can't be modified (i.e. which are read-only). ReadOnly is usually set to zero, except in some special applications. The ReadOnly characters are considered to be part of a prompt (or of command characters as in the text editor) so the user cannot change the text of the ReadOnly characters nor move the edit cursor into them.

Flags is a set of binary flags which controls the editor. Each bit specifies optional features of the text editor. Some of these flags are changed automatically during the operation of the editor. The flags are defined in the ETE_FLAGS enumeration and have the following meanings:

TE_WRAP | Set this flag for multiline edit regions. Reset it for single-line edit regions: the editor will operate in "compact" mode, in which the editor is only one character high, and where the contents of the editor will scroll left/right when necessary (such a mode is used in request boxes in dialogs). In "compact" mode, the contents of the editor buffer must not contain '\r' characters, else the editor will be fooled. In multiline edit regions, text can wrap around the end of the line to the beginning of the next line. The program editor is an example of a multiline edit region. The Home screen entry line is an example of a single-line edit region.
TE_COLON | When set, each line of the editor will be preceded with a colon (":"), like in the "Text editor" or the "Program editor". When TE_COLON is reset, there will not be a preceding colon. The program editor uses this flag to mark the beginning of each line of the program.
TE_COMMANDS | When set, the first character of each line will be regarded as "command character", and it will be displayed before the colon. The "Text editor" application uses this mode to store editor commands (like "P" = "PrintObj" etc.). Note that when this flag is set, the parameter cur_offset must not be zero (it is usually set to 1 in this case). Note: This flag includes the TE_COLON flag (as needed by the AMS).
TE_MORE_ARROWS | Set this flag to display arrows at the left and right ends of a single-line edit region to indicate when more text is to the left or right of the edit region.
TE_MORE_ELLIPSES | Set this flag to display ellipses (...) at the left and right ends of a single-line edit region to indicate when more text is to the left or right of the edit region. Note: This flag includes the TE_MORE_ARROWS flag (as needed by the AMS).
TE_SELECT | This flag is an internal flag. It is set if there currently is a selection in the text editor. It is clear if nothing is selected. Do not set this flag.
TE_CURSOR | This flag is an internal flag. It represents the current blinking state of the cursor: it is set if the blinking cursor is currently visible. Do not set this flag.
TE_FIXED_LENGTH | This flag is an internal flag. It is set for text editors opened with TE_openFixed. Do not set this flag.
TE_CHANGED | This flag is an internal flag. It is a status flag which, if 1, indicates the contents of the edit buffer have changed. Do not set this flag.
TE_FOCUSED | This flag is an internal flag. It is set if the text editor currently has the focus, i.e. if the cursor is currently in the text editor. See TE_focus and TE_unfocus. Do not set this flag.
TE_AUTO_ANS | Set this flag to 1 to cause "ans(1)" to be inserted automatically when the edit buffer is empty and an arithmetic operation is typed.
TE_READ_ONLY | When set, the editor enters read-only mode. In this mode, the editor displays text and allows arrow keys to navigate through the edit buffer, but it does not allow changing the text, i.e. you can't insert, delete or change any characters.

Note: TE_open just initializes the editor, displays the intial content of it and exits. It does not enter the editor loop in which keypresses are processed. In fact, there is no such loop: you need to get keypresses manually (using ngetchx or, even better, using EV_getc, or using the default event loop EV_eventLoop) and to pass them to TE_handleEvent which will process them. Such an approach gives much more flexibility. See TE_handleEvent for an example of usage.

Uses: TE_checkSlack, HeapAlloc, strlen, sf_width, WinAttr, WinBegin, WinChar, WinFill, _du16u16, _mu16u16, ROM Call 0x412
Used by: cmd_input, cmd_inputstr, cmd_prompt, Dialog

See also: TE_openFixed


TE_openFixed

TE_openFixed Function (ROM Call 0xAD)
textedit.h

short TE_openFixed (TEXT_EDIT *te, WINDOW *w, WIN_RECT *rect, char *buffer, unsigned short maxlen, unsigned short Flags);

Initializes the text editor, with fixed buffer.

TE_openFixed is very similar to TE_open, except it uses a fixed allocated buffer pointed to by buffer instead of dinamically created buffer associated with handle. So, the text buffer cannot expand automatically when necessary. The parameter maxlen determines the length of the buffer (the editor will not accept more characters than specified). That's why functions TE_checkSlack and TE_shrinkWrap cannot be applied to text editors opened with TE_openFixed.

Note: After opening text editor using TE_openFixed, it is recommended to manually set position of the cursor using TE_select (TE_openFixed has not a parameter for initial cursor position in opposite to TE_open), else strange things may happen.

Uses: strlen, sf_width, WinAttr, WinBegin, WinChar, WinFill, _du16u16, _mu16u16, ROM Call 0x412
Used by: Dialog, EV_defaultHandler, EV_quit, GT_Trace


TE_pasteText

TE_pasteText Function (ROM Call 0xAE)
textedit.h

void TE_pasteText (TEXT_EDIT *te, const char *text, unsigned long len);

Pastes a text into the editor.

TE_pasteText inserts len bytes of the text pointed to by text into the text editor buffer (associated with the structure pointed to by te) at the current cursor position. These functions may be used together with CB_fetchTEXT and CB_replaceTEXT if necessary. Also, this function may be used for implementing various (very useful) functions like TE_printf which works like printf but "prints" the formatted output into the text editor. Among various ways of implementing such functions, I suggested the following one (which uses the unusual but powerful function vcbprintf):

CALLBACK void TE_pasteChar(char c, TEXT_EDIT *te)
{
  char str[2] = {c, 0};
  TE_pasteText (te, str, 1);
}

void TE_printf(TEXT_EDIT *te, char *format, ...)
{
  va_list arglist;
  va_start (arglist, format);
  vcbprintf ((vcbprintf_callback_t)TE_pasteChar, (void**)te, format, arglist);
  va_end (arglist);
}
This example is not so simple, so you need to be familiar with (standard) C to understand it.

Uses: TE_checkSlack, HeapRealloc, ERD_dialog, memmove, CU_start, CU_stop, sf_width, WinBegin, WinChar, WinFill, _du16u16, _mu16u16, ROM Call 0x412, ROM Call 0x471
Used by: TE_handleEvent, HomeExecute


TE_reopen

TE_reopen Function (ROM Call 0xAF)
textedit.h

void TE_reopen (TEXT_EDIT *te, unsigned short Focus);

Re-opens the text editor.

TE_reopen first checks free space in the text editor buffer (associated with the structure pointed to by te) by calling TE_checkSlack, selects all characters in the editor buffer using TE_select, and eventually gives the focus to them if Focus is TRUE (Focus is Boolean parameter). This function is a good method to re-open previously edited text on such way that all text is selected and focused, so the eventual keypress will replace the selected text. It is usually used to reopen a text edit record which has been closed by TE_shrinkWrap.

Uses: TE_checkSlack, TE_focus, TE_select
Used by: cmd_input, cmd_inputstr, cmd_prompt, HomeExecute


TE_reopenPlain

TE_reopenPlain Function (ROM Call 0xB0)
textedit.h

void TE_reopenPlain (TEXT_EDIT *te, unsigned short Focus);

Re-opens the text editor (plain).

TE_reopenPlain is similar like TE_reopen, but it doesn't call TE_select funciton. I am not very sure about usage of this function.

Uses: TE_checkSlack, TE_focus
Used by: HomeExecute


TE_select

TE_select Function (ROM Call 0xB1)
textedit.h

void TE_select (TEXT_EDIT *te, unsigned short Low, unsigned short High);

Selects a block of text in the editor, or positions the cursor.

If Low != High, then TE_select selects all character in the text editor described by structure pointed to by te, starting from the character with offset Low up to character with offset High (counted from the begining of the text buffer). This is the operation which editor usually performs when the user uses shift + arrows. Note that you don't need to call TE_select often; usually TE_handleEvent will perform wanted job. This is only needed if you want to select a block of text in the editor independently of pressing of shift + arrows. Note that selected text will not automatically get a focus: you need to call TE_focus to achieve this.

If Low is equal to High, then TE_select positions the cursor to the position Low (counted from the begining of the text buffer).

Uses: TE_focus, TE_unfocus, sf_width, WinBegin, WinChar, WinFill, _du16u16, _mu16u16, ROM Call 0x412
Used by: TE_handleEvent, TE_reopen, cmd_input, cmd_inputstr, cmd_prompt, Dialog, EV_defaultHandler, HomeExecute, EV_quit, GT_Trace


TE_shrinkWrap

TE_shrinkWrap Function (ROM Call 0xB2)
textedit.h

HANDLE TE_shrinkWrap (TEXT_EDIT *te);

Shrinks the text editor buffer.

TE_shrinkWrap shrinks the text editor buffer (associated with the structure pointed to by te) to the minimal possible size. After calling this function, the size of the buffer will be equal to the actual number of characters in the buffer. This function must not be applied to text buffers opened with the TE_openFixed function. TE_shrinkWrap returns the handle of the text editor buffer as the result. In addition, this function cancels selection highlight and turns off the cursor. The edit buffer memory is not freed. Use this routine to prepare the edit buffer for further processing or to be stored as a variable.

If NULL is passed as an argument, TE_shrinkWrap creates a new handle for the text editor buffer.

Uses: TE_unfocus, HeapRealloc
Used by: cmd_input, cmd_inputstr, cmd_prompt, Dialog, HomeExecute


TE_unfocus

TE_unfocus Function (ROM Call 0xB3)
textedit.h

short TE_unfocus (TEXT_EDIT *te);

Removes the focus from the selected text in the editor.

TE_unfocus cancels the effect of TE_focus. Returns TRUE if unfocusing was performed, and returns FALSE if not (for example, if the text was already unfocused).

Uses: CU_stop, sf_width, WinBegin, WinFill, ROM Call 0x471
Used by: TE_close, TE_empty, TE_handleEvent, TE_select, TE_shrinkWrap, cmd_disp, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, Dialog, HomeExecute


TE_updateCommand

TE_updateCommand Function (ROM Call 0xB4)
textedit.h

void TE_updateCommand (TEXT_EDIT *te, unsigned char cmd);

Updates the command byte in the current line of the text.

TE_updateCommand sets the first byte of the current line (i.e. the line in which the cursor is located) of the text editor associated to the structure pointed to by te to cmd, i.e. sets the "command byte". This function works correctly only if the editor is opened in "command byte" mode, i.e. if if b2 = 1 in parameter Flags of the TE_open function).


TE_FAR_RIGHT

TE_FAR_RIGHT Constant (Macro)
textedit.h

#define TE_FAR_RIGHT (0xFFFF)

A constant defining the last cursor position in TE_open.

Set the parameter cur_offset in TE_open to TE_FAR_RIGHT will place the edit cursor after the last character in the edit buffer.

See also: TE_open


ETE_FLAGS

ETE_FLAGS Type (Enumeration)
textedit.h

typedef enum ETE_FLAGS {TE_WRAP = 0x0001, TE_COLON = 0x0002, TE_COMMANDS = 0x0006, TE_MORE_ARROWS = 0x0008, TE_MORE_ELLIPSES = 0x0018, TE_SELECT = 0x0020, TE_CURSOR = 0x0040, TE_FIXED_LENGTH = 0x0080, TE_CHANGED = 0x0100, TE_FOCUSED = 0x0200, TE_AUTO_ANS = 0x0400, TE_READ_ONLY = 0x0800} TE_FLAGS;

Enumerates optional features for the TE_open function.

Enumerates optional features for the TE_open function. The meaning of these flags is given in TE_open.

See also: TE_open


TEXT_EDIT

TEXT_EDIT Type (Structure)
textedit.h

typedef struct TextEditStruct {
WINDOW *Parent; /* Pointer to the parent window */
unsigned short ReadOnly; /* Number of bytes at start that are read only */
WIN_RECT Rect; /* Editor area descriptor */
unsigned short BufSize; /* Number of currently allocated bytes */
unsigned short CurSize; /* Current number of characters in the editor */
unsigned short CursorOffset; /* Offset of the cursor */
unsigned short StartOffset; /* ScrollX, position at which text is displayed */
union {
unsigned short SelStart; /* Position of the start of the selection, if any */
unsigned short PreChars; /* Deprecated old name of SelStart */
};
unsigned short CharWidth; /* Width in characters */
unsigned short CharHeight; /* Height in characters */
unsigned short LineNum; /* Line number: cursor is on 0..CharHeight-1 */
unsigned short CursorX; /* Horizontal char position */
unsigned short Flags; /* Editor flags */
union {
HANDLE h; /* Handle of the editor buffer, if opened with TE_open */
const char *p; /* Ptr to the editor buffer, if opened with TE_openFixed */
} Text;
} TEXT_EDIT;

A structure used to coordinate all text editor operations.

Note: StartOffset is the first shown character of the entry line, but it may be covered by an arrow or ellipsis if the corresponding flag is set. SelStart is the position of the non-extensible end of the selection. This may be either the beginning or the end of the selection, depending on whether it expands to the right or to the left. Its value is undefined if there is no selection. CursorX is the horizontal character position in the line, or position relative to StartOffset.


tigcclib.h

tigcclib.h Header File
Header File Index

Includes all other header files

This header file simply includes all other header files. It is equivalent to a header file called all.h.


timath.h

timath.h Header File
Header File Index

Routines for floating point arithmetic

Functions
abs
Absolute value of a number.
acos
Floating point arc cosine.
acosh
Floating point hyperbolic area cosine.
asin
Floating point arc sine.
asinh
Floating point hyperbolic area sine.
atan2
Four-quadrant arc tangent of y/x (or argument of the complex number).
atan
Floating point arc tangent.
atanh
Floating point hyperbolic area tangent.
atof
Converts a string to a floating point.
bcd_to_float
Converts BCD to float.
bcd_var
Converts reference to float object to reference to BCD object.
bcdadd
BCD addition.
bcdbcd
Converts integer to BCD.
bcdcmp
BCD comparation.
bcddiv
BCD division.
bcdlong
Converts BCD to integer.
bcdmul
BCD multiplication.
bcdneg
BCD negation.
bcdsub
BCD substraction.
cacos
Complex arc cosine.
cacosh
Complex hyperbolic area cosine.
casin
Complex arc sine.
casinh
Complex hyperbolic area sine.
catan
Complex arc tangent.
catanh
Complex hyperbolic area tangent.
ccos
Complex cosine.
ccosh
Complex hyperbolic cosine.
ceil
Rounds up the floating point number.
cexp
Complex exponential function.
ck_valid_float
Checks if the float pointed to by ptr is valid.
cln
Complex natural logarithm (base e).
clog10
Complex logarithm, base 10.
cos
Floating point cosine.
cosh
Floating point hyperbolic cosine.
csin
Complex sine.
csinh
Complex hyperbolic sine.
csqrt
Complex square root.
ctan
Complex tangent.
ctanh
Complex hyperbolic tangent.
exp
Floating point exponential function.
fabs
Absolute value of a floating point number.
fadd
Floating point addition.
fcmp
Floating point comparation.
fdiv
Floating point division.
FEXP_NEG
A deprecated macro used to define floating point numbers.
FEXP
A deprecated macro used to define floating point numbers.
float_class
Determines the class of the floating point number.
float_to_bcd
Converts float to BCD.
floor
Rounds down the floating point number.
FLT_NEG
A deprecated macro used to define floating point numbers.
flt
Converts integer to floating point.
FLT
A deprecated macro used to define floating point numbers.
fmod
Calculates x modulo y, i.e. the remainder of x/y.
fmul
Floating point multiplication.
fneg
Floating point negation.
fpisanint
Checks whether the floating point number is reducable to an integer.
fpisodd
Checks whether the integer part of a floating point number is an odd number.
frexp10
Splits floating point number into mantissa and exponent.
fsub
Floating point substraction.
hypot
Calculates hypotenuse of right triangle.
init_float
Initializes the floating point emulator.
is_float_infinity
Checks whether the argument is an infinite number.
is_float_negative_zero
Checks whether the argument is negative zero.
is_float_positive_zero
Checks whether the argument is positive zero.
is_float_signed_infinity
Checks whether the argument is signed infinity.
is_float_transfinite
Checks whether the argument is a transfinite number.
is_float_unsigned_inf_or_nan
Checks whether the argument is unsigned infinity or Not_a_Number.
is_float_unsigned_zero
Checks whether the argument is unsigned zero.
is_inf
Checks whether the argument is an infinite number.
is_nan
Checks whether the argument is Not_a_Number.
is_nzero
Checks whether the argument is negative zero.
is_pzero
Checks whether the argument is positive zero.
is_sinf
Checks whether the argument is signed infinity.
is_transfinite
Checks whether the argument is a transfinite number.
is_uinf_or_nan
Checks whether the argument is unsigned infinity or Not_a_Number.
is_uzero
Checks whether the argument is unsigned zero.
itrig
Generic subroutine for calculating inverse trigonometric functions.
labs
Absolute value of a long integer number.
ldexp10
Calculates x times 10 raised to exponent.
log
Floating point natural logarithm (base e).
log10
Floating point logarithm, base 10.
modf
Splits floating point value into integer and fraction part.
pow
Floating point power function.
round12_err
Rounds the floating point number to 12 significant digits, throwing an error if unsuccessful.
round12
Rounds the floating point number to 12 significant digits.
round14
Rounds the floating point number to 14 significant digits.
sin
Floating point sine.
sincos
Calculates both sine and cosine in one turn.
sinh
Floating point hyperbolic sine.
sqrt
Floating point square root.
tan
Floating point tangent.
tanh
Floating point hyperbolic tangent.
trig
Generic subroutine for calculating trigonometric functions.
trunc
Converts floating point to integer.
Constants
FIVE
A deprecated constant.
FOUR
A deprecated constant.
HALF_PI
A constant with value PI/2.
HALF
A deprecated constant.
MINUS_ONE
A deprecated constant.
NAN
A constant defining an undefined value.
NEGATIVE_INF
Represents an infinitely large negative quantity.
NEGATIVE_ZERO
Represents an infinitely small quantity which is known to be always non-positive.
ONE
A deprecated constant.
PI
An approximated value of pi.
POSITIVE_INF
Represents an infinitely large positive quantity.
POSITIVE_ZERO
Represents an infinitely small quantity which is known to be always non-negative.
TEN
A deprecated constant.
THREE
A deprecated constant.
TWO
A deprecated constant.
UNSIGNED_INF
Represents an infinite quantity.
UNSIGNED_ZERO
Represents an infinitely small quantity with indeterminate sign.
ZERO
A deprecated constant.
Predefined Types
bcd
Represents the internal organization of floating point numbers in the format recognized by the TIOS.
Bool
An enumeration to describe true or false values.
ti_float
An alias for the standard ANSI float type.

Note: All functions which return a result of type float are implemented as macros, although many of them exist as TIOS entries. This is done because the GCC convention for returning floating point values as function results differs from the convention expected by the TIOS. This note is mainly unimportant from the user's point of view.

See also: math.h


bcd_to_float

bcd_to_float Function (Macro)
timath.h

float bcd_to_float (bcd x);

Converts BCD to float.

bcd_to_float converts BCD structure x into an ordinary floating point value. In fact, this function returns the same value as the argument, but with different interpretation. This function, in a way, performs typecasting from a bcd type to an ordinary float type.


bcd_var

bcd_var Function (Macro)
timath.h

#define bcd_var(a) (*(bcd*)&(a))

Converts reference to float object to reference to BCD object.

bcd_var converts the reference to a floating point object x (which must be an lvalue, for example a floating point variable) to the reference to the same object, but interpreted as a bcd structure. bcd_var is similar as float_to_bcd, but returned object is an lvalue, so it may be used in assignments like

float a;
...
bcd_var(a).exponent = 0x4002;
The drawback of bcd_var (compared with float_to_bcd) is the fact that its argument must be an lvalue, so it cannot be a floating point constant or any non-lvalue expression (for example, a result of a function).

Note: I used notation "&bcd_var" and "&x" in the prototype description, although passing by reference and returning results by reference does not exist in ordinary C (only in C++). However, this bcd_var is macro which is implemented on such way that it simulates "passing and returning by reference".


bcdadd

bcdadd Function (Macro)
timath.h

bcd bcdadd (bcd x, bcd y);

BCD addition.

bcdadd is principally the same as fadd, but instead of ordinary floats, its arguments and return value are bcd structures (which represent internal organization of floating point values in TIOS). At the fundamental level, bcdadd and fadd are the same routine.

Uses: fadd


bcdbcd

bcdbcd Function
timath.h

bcd bcdbcd (long x);

Converts integer to BCD.

bcdbcd is principally the same as flt, but instead of ordinary float, its return value is a bcd structure (which represent internal organization of floating point values in TIOS). At the fundamental level, bcdbcd and flt are the same routine.


bcdcmp

bcdcmp Function (Macro)
timath.h

long bcdcmp (bcd x, bcd y);

BCD comparation.

bcdcmp is principally the same as fcmp, but instead of ordinary floats, its arguments are bcd structures (which represent internal organization of floating point values in TIOS). At the fundamental level, bcdcmp and fcmp are the same routine.

Uses: fcmp


bcddiv

bcddiv Function (Macro)
timath.h

bcd bcddiv (bcd x, bcd y);

BCD division.

bcddiv is principally the same as fdiv, but instead of ordinary floats, its arguments and return value are bcd structures (which represent internal organization of floating point values in TIOS). At the fundamental level, bcddiv and fdiv are the same routine.

Uses: fdiv


bcdlong

bcdlong Function (Macro)
timath.h

long bcdlong (bcd x);

Converts BCD to integer.

bcdlong is principally the same as trunc, but instead of ordinary float, its argument is a bcd structure (which represent internal organization of floating point values in TIOS). At the fundamental level, bcdlong and trunc are the same routine.

Uses: trunc


bcdmul

bcdmul Function (Macro)
timath.h

bcd bcdmul (bcd x, bcd y);

BCD multiplication.

bcdmul is principally the same as fmul, but instead of ordinary floats, its arguments and return value are bcd structures (which represent internal organization of floating point values in TIOS). At the fundamental level, bcdmul and fmul are the same routine.

Uses: fmul


bcdneg

bcdneg Function (Macro)
timath.h

bcd bcdneg (bcd x);

BCD negation.

bcdneg is principally the same as fneg, but instead of ordinary floats, its argument and return value are bcd structures (which represent internal organization of floating point values in TIOS). At the fundamental level, bcdneg and fneg are the same routine.

Uses: fneg


bcdsub

bcdsub Function (Macro)
timath.h

bcd bcdsub (bcd x, bcd y);

BCD substraction.

bcdsub is principally the same as fsub, but instead of ordinary floats, its arguments and return value are bcd structures (which represent internal organization of floating point values in TIOS). At the fundamental level, bcdsub and fsub are the same routine.

Uses: fsub


ck_valid_float

ck_valid_float Function (ROM Call 0x1E5)
timath.h

short ck_valid_float (float *ptr);

Checks if the float pointed to by ptr is valid.

This function first rounds *ptr to 14 significant digits and underflows it to 0 if the exponent is less than -999 (it returns TRUE in that case). If the float pointed to by ptr is transfinite (see is_float_transfinite) or its exponent is greater than +999, *ptr is set to NAN and FALSE is returned. Else, TRUE is returned.

Uses: round14, _bcd_math
Used by: cpt_gr_polar, CptIndep, de_loop, FirstSeqPlot, GT_DspTraceCoords, GT_Trace, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_sinreg, cmd_twovar, GR3_paint3d, CptDeltax, CptDeltay, VarStore


fadd

fadd Function (ROM Call 0xB6*)
timath.h

float fadd (float x, float y);

Floating point addition.

fadd returns the sum of floating point arguments x and y. This routine performs the same operation as the C '+' operator applied to floating point operands, but it is kept here for backwards compatibility. At the fundamental level, fadd is exactly the same routine as bcdadd.

Uses: _bcd_math
Used by: bcdadd, hypot


fcmp

fcmp Function (ROM Call 0xBB)
timath.h

long fcmp (float x, float y);

Floating point comparation.

fcmp compares floating point arguments x and y, and returns a value which is

  • < 0 if x is less than y
  • == 0 if x is the same as y
  • > 0 if x is greater than y
This function may be useful as a comparison function for qsort function from stdlib.html. All relation operators applied to floating point types are implemented through implicite calls of this function. At the fundamental level, fcmp is exactly the same routine as bcdcmp.

Note: All kind of zeros are equal from the aspect of comparation. Transfinite values are incomparable, and the result of fcmp is unpredictable (usually 1, but this is not guarantee) if any argument is transfinite. See ZERO, UNSIGNED_ZERO, POSITIVE_ZERO, NEGATIVE_ZERO, UNSIGNED_INF, POSITIVE_INF, NEGATIVE_INF and NAN for more details.

Uses: _bcd_math
Used by: bcdcmp


fdiv

fdiv Function (ROM Call 0xB9*)
timath.h

float fdiv (float x, float y);

Floating point division.

fdiv returns the quotient of floating point arguments x and y. This routine performs the same operation as the C '/' operator applied to floating point operands, but it is kept here for backwards compatibility. At the fundamental level, fdiv is exactly the same routine as bcddiv.

Note: fdiv returns infinite result if the argument is zero (signed or unsigned), or in a case of overflow. Also, it returns NAN if both arguments are zeros or infinities. See ZERO, UNSIGNED_ZERO, POSITIVE_ZERO, NEGATIVE_ZERO, UNSIGNED_INF, POSITIVE_INF and NEGATIVE_INF for more details.

Uses: _bcd_math
Used by: bcddiv


FEXP_NEG

FEXP_NEG Function (Macro constructor)
timath.h

A deprecated macro used to define floating point numbers.

FEXP_NEG (also deprecated) works exactly like FEXP, except it constructs negative values instead of positive ones.


FEXP

FEXP Function (Macro constructor)
timath.h

A deprecated macro used to define floating point numbers.

Yet one deprecated macro. FEXP(m,e) constructs a number m*10^e where m is a sequence of digits (without decimal point) which is assumed to represent decimal number m.mmmm..., e.g. FEXP(2514,5) represents number 2.514*10^5 (251400 or 2.514e5 using conventional exponential notation), and FEXP(42,-3) represents number 4.2*10^-3 (0.0042 or 4.2e-3). FEXP(1,3) is 1*10^3 (1000 or 1e3). mantissa must be the constant sequence of digits, without leading zeros, but the way on which FEXP is implemented allows that exponent may be a variable or an expression, like FEXP(314,a), when even mantissa is not a constant, you can use function ldexp10. Anyway, you don't need to use FEXP any more: simply use conventional exponential notation. E.g. simply use 4.2e3 instead of FEXP(42,3) etc.

Note that a = FEXP(m,e) is not the same as bcd_var(a).exponent = e+0x4000 and bcd_var(a).mantissa = m. The first part is true; the second is not. More precise, FEXP shifts m to the left enough number of times to produce correct normalized mantissa (see bcd for more info). So, when you type a = FEXP(352,3) it works like bcd_var(a).exponent = 0x4003 and bcd_var(a).mantissa = 0x3520000000000000. For more description about internal format of floating point numbers, see bcd.

See also: float_to_bcd, bcd_to_float, bcd_var


float_class

float_class Function (ROM Call 0x2FA)
AMS 1.01 or higher timath.h

short float_class (float x);

Determines the class of the floating point number.

float_class checks the floating point argument x and returns an integer result which determines the subtype of the argument, in according to the following table:

1 | Not_a_Number (NAN)
2 | Negative infinity (NEGATIVE_INF)
3 | Negative real number
5 | Negative zero (NEGATIVE_ZERO)
6 | Unsigned zero (ZERO)
7 | Positive zero (POSITIVE_ZERO)
9 | Positive real number
10 | Positive infinity (POSITIVE_INF)
11 | Unsigned infinity (UNSIGNED_INF)

Note: This table was wrong in the documentation of TIGCCLIB release 1.5: negative and unsigned infinity was swapped due a to typing error.

Uses: is_nan, _bcd_math
Used by: did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_sum, push_Float_to_rat, get_ub, push_gcd_then_cofactors, push_standardize


float_to_bcd

float_to_bcd Function (Macro)
timath.h

bcd float_to_bcd (float x);

Converts float to BCD.

bcd_to_float converts BCD structure x into an ordinary floating point value. In fact, this function returns the same value as the argument, but with different interpretation. This function, in a way, performs typecasting from an ordinary float type to a bcd type. Beware that returned value is not an lvalue (ordinary C functions never return lvalues, by the way), so you cannot do something like

float a;
...
float_to_bcd(a).exponent = 0x4002;
To perform such assignments, use bcd_var macro.


FLT_NEG

FLT_NEG Function (Macro constructor)
timath.h

A deprecated macro used to define floating point numbers.

FLT_NEG is another deprecated macro which works exactly as FLT, except it construct negative values instead of positive ones. More precise, FLT_NEG(x,y) will simply be translated to -x.y and FLT_NEG(x) will be translated to -x.0. Anyway, you don't need to use the FLT_NEG macro any more.


flt

flt Function (ROM Call 0xBD*)
timath.h

float flt (long x);

Converts integer to floating point.

flt converts the (long) integer argument x to the floating point representation of the same value. This routine performs the same operation as casting a long integer value to float type using the '(float)' typecast operator, but it is kept here for backwards compatibility. This function is automatically called when any floating point function is called with a long integer argument, to force a promotion of an integer to a floating point type. In other words, integer values will be automatically promoted to the floating point type when necessary. So, you can do assignment like b = a; when a is an integer variable (or expression) and b is a standard floating point variable (float or double). Also, you can calculate sin(a) where a is an integer. In both cases, flt will be called automatically to perform the promotion. At the fundamental level, flt is exactly the same routine as bcdbcd.

Uses: _bcd_math


FLT

FLT Function (Macro constructor)
timath.h

A deprecated macro used to define floating point numbers.

FLT is a now deprecated macro which is kept here only to retain compatibility with programs which are written with older releases of TIGCC (before 0.9), which didn't support standard floating point numbers. Now, FLT(x,y) will simply be translated to x.y and FLT(x) will be translated to x.0, e.g. FLT(342,15) will be translated to 342.15, FLT(0,0001) will be translated to 0.0001, and FLT(4) will be translated to 4.0. Anyway, you don't need to use the FLT macro any more.


fmul

fmul Function (ROM Call 0xB8*)
timath.h

float fmul (float x, float y);

Floating point multiplication.

fmul returns the product of floating point arguments x and y. This routine performs the same operation as the C '*' operator applied to floating point operands, but it is kept here for backwards compatibility. At the fundamental level, fmul is exactly the same routine as bcdmul.

Note: fmul returns infinite result in a case of overflow. See UNSIGNED_INF, POSITIVE_INF and NEGATIVE_INF for more details.

Uses: _bcd_math
Used by: bcdmul, hypot


fneg

fneg Function (ROM Call 0xBA*)
timath.h

float fneg (float x);

Floating point negation.

fneg returns negated value of floating point argument x. This routine performs the same operation as the C '-' unary minus operator applied to a floating point operand, but it is kept here for backwards compatibility. At the fundamental level, fneg is exactly the same routine as bcdneg.

Uses: _bcd_math
Used by: bcdneg


fpisanint

fpisanint Function (ROM Call 0x172)
timath.h

short fpisanint (unsigned long long *mantissa, unsigned short exponent);

Checks whether the floating point number is reducable to an integer.

fpisanint is an internal TIOS subroutine used in pow. It checks whether the floating point with the exponent exponent and the mantissa pointed to by mantissa is reducable to an integer. Returns TRUE or FALSE, depending on the test.

Note: long long is not a typing error: it is a GNU C extension for representing very long integers (8-byte integers in this implementation).

Used by: ceil, floor, cmd_randseed, push_rand, push_randmat, push_randnorm, push_randpoly, push_round, GR3_handleEvent


fpisodd

fpisodd Function (ROM Call 0x173)
timath.h

short fpisodd (const unsigned long long *mantissa, unsigned short exponent);

Checks whether the integer part of a floating point number is an odd number.

fpisodd is an internal TIOS subroutine used in pow. It checks whether the integer part of the floating point with the exponent exponent and the mantissa pointed to by mantissa is an odd number. Returns TRUE or FALSE, depending on the test. Also returns TRUE if the integer part is zero, although zero is not an odd number.

Note: long long is not a typing error: it is a GNU C extension for representing very long integers (8-byte integers in this implementation).


fsub

fsub Function (ROM Call 0xB7*)
timath.h

float fsub (float x, float y);

Floating point substraction.

fsub returns the difference of floating point arguments x and y. This routine performs the same operation as the C '-' operator applied to floating point operands, but it is kept here for backwards compatibility. At the fundamental level, fsub is exactly the same routine as bcdsub.

Uses: _bcd_math
Used by: bcdsub


init_float

init_float Function (Macro)
timath.h

void init_float (void);

Initializes the floating point emulator.

init_float initializes the TIOS floating point emulator. However, as far as I know, you need not to call this function explicitely anywhere in your program, because TIOS does it in the boot code. As this function is removed from AMS 2.xx, it is redefined in this release of TIGCCLIB to do nothing (it is kept in this header file only for compatibility with previous releases).

Note: TIOS fp emulator is, in fact, located in TIOS routine called _bcd_math. This routine performs a set of arithmetic operations on binary coded decimal floating point values. A two-byte emulator opcode word is needed after the call to _bcd_math to instruct the emulator which operation will be performed, where are its operands, etc. Operands may be in MC68000 registers, in the memory, or in "floating point registers" (they are, in fact, memory locations on the stack frame from the aspect of the emulator). If the "instruction" has immediate operand, there will be more than one extra inline word after the call to _bcd_math. Anyway, function _bcd_math is unusable in C programs (except in asm statements), due to non-C calling convention. Fortunately, nearly all operations supported by _bcd_math have also a built-in interface in TIOS which is adapted to C calling convention. That's why I completely bypassed _bcd_math function in this header file. It may give additional flexibility for ASM programmers (sometimes the argument may be in the register, sometimes in the memory, etc.). But in C, the arguments are always on the stack, so this flexibility is not necessary.


is_float_infinity

is_float_infinity Function (ROM Call 0x2FF)
AMS 1.01 or higher timath.h

short is_float_infinity (float x);

Checks whether the argument is an infinite number.

is_float_infinity is original TIOS name for the function which is aliased here as is_inf.


is_float_negative_zero

is_float_negative_zero Function (ROM Call 0x300)
AMS 1.01 or higher timath.h

short is_float_negative_zero (float x);

Checks whether the argument is negative zero.

is_float_negative_zero is original TIOS name for the function which is aliased here as is_nzero.


is_float_positive_zero

is_float_positive_zero Function (ROM Call 0x301)
AMS 1.01 or higher timath.h

short is_float_positive_zero (float x);

Checks whether the argument is positive zero.

is_float_positive_zero is original TIOS name for the function which is aliased here as is_pzero.


is_float_signed_infinity

is_float_signed_infinity Function (ROM Call 0x302)
AMS 1.01 or higher timath.h

short is_float_signed_infinity (float x);

Checks whether the argument is signed infinity.

is_float_signed_infinity is original TIOS name for the function which is aliased here as is_sinf.


is_float_transfinite

is_float_transfinite Function (ROM Call 0x303)
AMS 1.01 or higher timath.h

short is_float_transfinite (float x);

Checks whether the argument is a transfinite number.

is_float_transfinite is original TIOS name for the function which is aliased here as is_transfinite.


is_float_unsigned_inf_or_nan

is_float_unsigned_inf_or_nan Function (ROM Call 0x304)
AMS 1.01 or higher timath.h

short is_float_unsigned_inf_or_nan (float x);

Checks whether the argument is unsigned infinity or Not_a_Number.

is_float_unsigned_inf_or_nan is original TIOS name for the function which is aliased here as is_uinf_or_nan.


is_float_unsigned_zero

is_float_unsigned_zero Function (ROM Call 0x305)
AMS 1.01 or higher timath.h

short is_float_unsigned_zero (float x);

Checks whether the argument is unsigned zero.

is_float_unsigned_zero is original TIOS name for the function which is aliased here as is_uzero.


itrig

itrig Function (ROM Call 0x28A)
timath.h

void itrig (short option, short deg_flag, float *xptr, float *result);

Generic subroutine for calculating inverse trigonometric functions.

itrig is a TIOS subroutine which is used internally for calculating inverse trigonometric functions, i.e. in TIOS functions asin, acos and atan. It calculates the arc sine, the arc cosine or the arc tangent of the floating point value pointed to by xptr, and stores the result in the floating point destination pointed to by result. The result will be in radians if deg_flag is 0, or in degrees if deg_flag is 1 (it seems that these two values are only legal values for deg_flag). Parameter option determines which inverse trigonometric function will be calculated: the arc sine if option = 1, the arc cosine if option = 2 and the arc tangent if option = 4. I don't know whether these values are the only legal values for option, but I believe so.

Note: The parameter xptr is not a pointer to const value. This means that the value pointed to by it may be changed. In normal cases this would not appear, but this need not to be true if the structure pointed to by xptr contains wrong values (for example, arguments out of the function domain, unnormalized values, etc.).

Uses: is_inf, is_nan, is_sinf, is_transfinite, is_uinf_or_nan, sqrt, _bcd_math
Used by: acos, asin, atan, push_to_sphere


round12_err

round12_err Function (ROM Call 0x227*)
timath.h

float round12_err (float x, short error_code);

Rounds the floating point number to 12 significant digits, throwing an error if unsuccessful.

round12_err is identical as round12, except it throws an error with code error_code if the absolute value of the argument is greater or equal than 10^1000, or if the argument is a transfinite number (see is_transfinite), and it rounds arguments whose absolute values are smaller than 10^-1000 to UNSIGNED_ZERO.

Uses: round12, _bcd_math
Used by: cmd_blddata, GZ_Center, CptFuncX, CptLastIndepDE, de_initRes, de_loop, dv_create_graph_titles, GM_Derivative, GM_DistArc, GM_TanLine, GZ_Decimal, GZ_Fit, GZ_InOut, GZ_Integer, GZ_Square, GZ_Trig, YCvtPtoF, VarStore


round12

round12 Function (ROM Call 0x174*)
timath.h

float round12 (float x);

Rounds the floating point number to 12 significant digits.

round12 returns the value of the floating point argument x rounded to 12 significant digits. TIOS sometimes does such rounding, for example when TIOS updates coordinate values (xc, yc, etc.), during printing approximate results, or when TIOS stores a value to system variables like xmin, xmax etc. (strictly speaking, TIOS calls round12_err instead of round12 in such cases).

Used by: round12_err, push_round, GR3_paint3d, CptIndep, CptLastIndepDE, FuncLineFlt, GR3_addContours, GrAxes, GrClipLine, GrLineFlt, GT_Trace, GZ_Stat, InitDEAxesRng


round14

round14 Function (ROM Call 0x175*)
timath.h

float round14 (float x);

Rounds the floating point number to 14 significant digits.

round14 returns the value of the floating point argument x rounded to 14 significant digits. Also, arguments whose absolute values are greater or equal than 10^8192 are rounded to POSITIVE_INF or NEGATIVE_INF, and arguments whose absolute values are smaller than 10^-8192 are rounded to POSITIVE_ZERO or NEGATIVE_ZERO. TIOS always does such rounding before storing a floating point value to a variable.

Used by: cmd_drawpol, cmd_get, estack_number_to_Float, push_Float, ck_valid_float, dv_create_graph_titles, ForceFloat, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, GT_Trace, GZ_Trig, VarRecall


sincos

sincos Function (ROM Call 0x286)
timath.h

void sincos (float x, short deg_flag, float *sine, float *cosine);

Calculates both sine and cosine in one turn.

sincos calculates both the sine and the cosine of floating point argument x, and stores the results in floating point destinationss pointed to by sine and cosine. The argument x is assumed to be specified in radians if deg_flag is 0, or in degrees if deg_flag is 1 (it seems that these two values are only legal values for deg_flag). See also notes related to sin and cos.

Uses: trig
Used by: cmd_drawpol, GR3_paint3d, cpt_gr_polar, dv_create_graph_titles, GM_Derivative, GM_TanLine, GR3_handleEvent

See also: sin, cos


trig

trig Function (ROM Call 0x28B)
timath.h

void trig (short option, short deg_flag, const float *xptr, float *sine, float *cosine, float *tangent);

Generic subroutine for calculating trigonometric functions.

trig is a TIOS subroutine which is used internally for calculating trigonometric functions, i.e. in TIOS functions sin, cos, sincos and tan. It calculates simultaneously the sine, the cosine and the tangent of the floating point value pointed to by xptr, and stores the results in floating point destinations pointed to by sine, cosine and tangent. The argument pointed to by xptr is assumed to be specified in radians if deg_flag is 0, or in degrees if deg_flag is 1 (it seems that these two values are only legal values for deg_flag). Parameter option is not very clear to me: TIOS uses option = 1 in sin and sincos, option = 2 in cos, and option = 4 in tan. I don't know what is the difference between option = 1 and option = 2, because both the sine and the cosine are calculated regardless of the value of option. I only noticed that the tangent will not be calculated if option is not equal to 4.

Note: I included the description of this routine here only due to completeness: it is more preferable to call particular trigonometric function instead.

Uses: is_transfinite, _bcd_math
Used by: cos, sin, sincos, tan, handleVarLinkKey, push_trig, ROM Call 0x446


trunc

trunc Function (ROM Call 0xBC)
timath.h

long trunc (float x);

Converts floating point to integer.

trunc truncates floating point argument x to the long integer result. Returns zero in a case of overflow. This routine performs the same operation as casting a floating point value to an int type using '(int)', '(unsigned int)' and '(long)' typecast operators, but it is kept here for backwards compatibility. This function is automatically called when any function which needs an integer is called with a floating point arguments, to force a truncation of a floating point value to an integer. Also, you can do assignments like b = a; when a is a floating point variable (or expression) and b is an integer variable. In both cases, trunc will be called automatically to perform the truncation. At the fundamental level, trunc is exactly the same routine as bcdlong.

Uses: ST_modKey, _bcd_math
Used by: bcdlong


FIVE

FIVE Constant
timath.h

#define FIVE (5.)

A deprecated constant.

FIVE is a predefined floating point constant with value 5.0, defined to keep backwards compatibility.


FOUR

FOUR Constant
timath.h

#define FOUR (4.)

A deprecated constant.

FOUR is a predefined floating point constant with value 4.0, defined to keep backwards compatibility.


HALF

HALF Constant
timath.h

#define HALF (0.5)

A deprecated constant.

HALF is a predefined floating point constant with value 0.5, defined to keep backwards compatibility.


MINUS_ONE

MINUS_ONE Constant
timath.h

#define MINUS_ONE (-1.)

A deprecated constant.

MINUS_ONE is a predefined floating point constant with value -1.0, defined to keep backwards compatibility.


ONE

ONE Constant
timath.h

#define ONE (1.)

A deprecated constant.

ONE is a predefined floating point constant with value 1.0, defined to keep backwards compatibility.


TEN

TEN Constant
timath.h

#define TEN (10.)

A deprecated constant.

TEN is a predefined floating point constant with value 10.0, defined to keep backwards compatibility.


THREE

THREE Constant
timath.h

#define THREE (3.)

A deprecated constant.

THREE is a predefined floating point constant with value 3.0, defined to keep backwards compatibility.


TWO

TWO Constant
timath.h

#define TWO (2.)

A deprecated constant.

TWO is a predefined floating point constant with value 2.0, defined to keep backwards compatibility.


unknown.h

unknown.h Header File
Header File Index

Unknown routines

This header file defines all TIOS jump table entries which are not defined in any other header file. Some of these entries are absolutely unknown for us, and other entries are still not clear enough to us to be documented. The totally unknown entries are assumed to be functions which return short, and which accept any number of arguments.

Our intention is that the number of functions this header file contains be as small as possible. Please help us with this task.

Functions
_bcd_math

_ds16u16

_ds32s32

_du16u16

_du32u32

_ms16u16

_ms32s32

_mu16u16

_mu32u32

are_units_consistent

assign_between

CheckGraphRef

cleanup_de_mem

cleanup_seq_mem

clear_error_context

ClockOff

ClockOn

compare_numbers

convert_to_TI_92

CountGrFunc

cpt_gr_fun

cpt_gr_param

cpt_gr_polar

CptFuncX

CptIndep

CptLastIndepDE

CustomBegin

CustomEnd

CustomFree

CustomMenuItem

DateAndTime_Get

DateAndTime_Set

DateAndTime_SetDlg

DateFormat_Get

DateFormat_Set

DateStr

DayOfTheWeek

de_initRes

de_loop

de_rng_no_graph

delete_list_element

deStepCk

did_map_aggregate_arg

did_push_approx_inflection_point

did_push_divide_units

did_push_lincf

did_push_var_val

does_push_fetch

dv_create_graph_titles

dv_findColumn

EQU_deStatus

EQU_getNameInfo

EQU_select

EQU_setStyle

ER_throwFrame

estack_to_float

execute_graph_func

FindFunc

FindGrFunc

FirstSeqPlot

fix_loop_displacements

ForceFloat

FuncLineFlt

gen_version

get_lb

get_list_indices

get_matrix_indices

get_ub

GetStatValue

GetSysGraphRef

GM_Derivative

GM_DistArc

GM_Inflection

GM_Integrate

GM_Intersect

GM_Math1

GM_Shade

GM_TanLine

GM_Value

gr_add_fldpic

gr_ck_solvergraph

gr_CptIndepInc

gr_de_axes_lbl

gr_de_value

gr_del_locals

gr_del_vars_in_folder

gr_delete_fldpic

gr_DelFolder

gr_DispLabels

gr_execute_de

gr_execute_seq

gr_find_de_result

gr_find_el

gr_find_func_index

gr_initCondName

gr_openFolder

GR_Pan

gr_remove_fldpic

gr_seq_value

gr_stopic

gr_xres_pixel

GR3_addContours

GR3_freeDB

GR3_handleEvent

GraphActivate

GraphOrTableCmd

GrAxes

GrClipLine

grFuncName

GrLineFlt

GS_PlotAll

GS_PlotTrace

GT_BackupToScr

GT_CalcDepVals

GT_CenterGraphCursor

GT_CursorKey

GT_DE_Init_Conds

GT_DspFreeTraceCoords

GT_DspMsg
Displays msg according to pos.
GT_DspTraceCoords

GT_Error

GT_Format

GT_FreeTrace

GT_IncXY

GT_KeyIn

GT_Open

GT_PrintCursor

GT_QFloatCursorsInRange

GT_Regraph_if_neccy

GT_Regraph

GT_SaveAs

GT_SelFunc

GT_Set_Graph_Format

GT_SetCursorXY

GT_SetGraphRange

GT_ShowMarkers

GT_Trace

GT_ValidGraphRanges

GT_WinBound

GT_WinCursor

GXcoord

GYcoord

GZ_Decimal

GZ_Fit

GZ_InOut

GZ_Integer

GZ_Previous

GZ_Recall

GZ_SetFactors

GZ_Square

GZ_Standard

GZ_Stat

GZ_Store

GZ_Trig

has_different_variable

has_unit_base

index_after_match_endtag

index_if_pushed_binomial_info

index_if_pushed_qquad_info

index_reductum_with_tag_base

index_rmng_factor

index_rmng_fctrs_start_base_tag

index_rmng_fctrs_start_base

index_rmng_fctrs_start_fctr_tag

init_unit_system

InitDEAxesRng

InitDEMem

InitTimeSeq

is_cFloat_agg

is_complex_Float

is_equivalent_to

is_executable

is_neg_lead_numr_coef_re_part

is_real

is_term_improper

is_undefined

is_units_term

IsClockOn

lead_conjunct_factor_index

lead_disjunct_term_index

linear_degree

LoadSymFromFindHandle

next_token

next_var_or_kernel_index

NG_cleanup_graph_fun

NG_setup_graph_fun

nonblank

OO_appGetPublicStorage

OO_appIsMarkedDelete

OO_appMarkDelete

OO_AppNameToACB

OO_appSetPublicStorage

OO_CondGetAttr

OO_Deref

OO_Destroy

OO_DestroyAll

OO_GetAppAttr

OO_GetAttr

OO_HasAttr

OO_InstallAppHook

OO_InstallAppHookByName

OO_InstallSystemHook

OO_New

OO_NextACB

OO_PrevACB

OO_SetAppAttr

OO_SetAttr

OO_UninstallAppHook

OO_UninstallAppHookByName

OO_UninstallSystemHook

OSKeyScan

paint_all_except

ParseSymName

PlotDel

PlotDup

PlotGet

PlotInit

PlotLookup

PlotPut

PlotSize

push_ans_entry

push_auto_units_conversion

push_but_conjunct_factor

push_but_factor

push_but_term

push_constant_factors

push_constant_terms

push_dependent_factors

push_dependent_terms

push_float_qr_fact

push_gcd_then_cofactors

push_independent_factors

push_independent_terms

push_lu_fact

push_make_proper

push_mrow_aux

push_nonconstant_factors

push_nonconstant_terms

push_nonnumeric_factors

push_parse_prgm_or_func_text

push_poly_deg_in_var_or_kernel

push_poly_qr

push_reciprocal

push_simplify_statements

push_sq_matrix_to_whole_number

push_standardize

push_symbolic_qr_fact

push_trig

push_unit_system_list

push_user_func

push_var_kern_tail

push_var

push_zero_partial_column

QActivePlots

QPlotActive

QSkipGraphErr

readHandshake
Deprecated high-level linking protocol.
ReallocExprStruct

recall_data_var

Regraph

remaining_conjuncts_index

remaining_disjuncts_index

run_one_seq

ScrRectDivide

SearchExprStruct

seqStepCk

seqWebInit

SetGraphMode

setup_more_graph_fun

setup_unit_system

SP_Define

spike_chk_gr_dirty

spike_geo_titles

spike_in_editor

spike_optionD

spike_titles_in_editor

startBPTimer
Starts timer number 8 with a very high initial value.
stopBPTimer
Stops timer number 8.
store_data_var

store_func_def

store_to_subscripted_element

time_loop

TimeFormat_Get

TimeFormat_Set

Timer_Start

Timer_Value

TimeStr

TimeZone_Get

TimeZone_Set

TIOS_abs

TIOS_div

TIOS_labs

TIOS_ldiv

TIOS_strtol

tokenize_if_TI_92_or_text

TokenizeName

unlock_more_graph_fun

UpdateWindows

ValidateStore

VarGraphRefBitsClear

VarSaveTitle

VarStoreLink

writeHandshake
Deprecated high-level linking protocol.
XCvtFtoP

XCvtPtoF

YCvtFtoP

YCvtFtoWin

YCvtPtoF

Global Variables
errno

EV_appA

EV_appB

EV_appSide

EV_currentApp

EV_errorCode

EV_runningApp

IM_re_tol

NG_control

NG_such_that_index

OO_firstACB

OO_SuperFrame

OSModKeyStatus

pSymPG

RAtionalize_tol

ST_flags

VarOptList

Constants
SYM_LEN
Maximum length of the name of a folder or file.
Predefined Types
Attrs
An enumeration for describing legal attribute values.
BITMAP
A structure for defining a bitmap.
Bool
An enumeration to describe true or false values.
CESI
Represents a pointer to a constant expression.
DB3
Structure for defining a 3D function spin database.
div_t
An integer division return type used in the div function.
EQU_DS_AMS1
Structure for defining internal Y = Editor app data (AMS 1.xx version).
EQU_DS
Structure for defining internal Y = Editor app data.
EQU_SELECT

ESI_Callback_t
Represents a pointer to an ESI callback function.
ESI
Represents an index of a value on the TIOS expression stack.
ESQ
Represents a quantum within an expression.
FOLDER_TYPE
A union of three pointers, pointing either to a handle, a SYM_ENTRY or a file in memory.
FUNCID
Function identifier structure.
GR_MODES
Structure for describing graph modes.
GR_WIN_VARS
Structure defining data for the graph related apps.
GraphModes
Describes different graphing modes.
GrFmtFlags2
Enumerates different Graph Format flags for the GR_MODES struct.
GrFmtFlags
Enumerates different Graph Format flags for the GR_MODES struct.
GrMode3dStyles
Enumerates different 3D Graph Style flags for the GR_MODES struct.
GrSides
Enumerates different Graph side flags for the GR_WIN_VARS struct.
GrWinFlags
Enumerates different Graph app flags for the GR_WIN_VARS struct.
HANDLE
Represents a handle associated with an allocated memory block.
HSym
A structure representing a symbol reference.
ldiv_t
A long integer division return type used in the ldiv function.
OO_Indices

pFrame

SCR_COORDS
An alias type for defining physical screen coordinates.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
SYM_ENTRY
A structure representing a VAT symbol entry.
SYM_STR
Represents a pointer to the terminating zero byte of a string.
SymPG_S
A structure describing a "symbol table private global structure".
TABLE_WIN_VARS
Structure for defining Table app data.
TableFlags
Enumerates different Table app flags for the GR_WIN_VARS struct.
Two_ESI_Callback_t

unknown_retval
Type for unknown return values.
WIN_COORDS
An alias type for defining logical screen coordinates.
WIN_RECT
A structure for defining a rectangular area.
WINDOW_AMS1
The main window-describing structure (AMS 1.xx version).
WINDOW
The main window-describing structure.
WinVarEnum
Describes different Window variables.


_bcd_math

_bcd_math Function (ROM Call 0xB5)

This identifier has not been documented yet. Please help us out.

Used by: are_units_consistent, ck_valid_float, compare_numbers, cpt_gr_polar, CptFuncX, CptIndep, CptLastIndepDE, de_initRes, de_loop, de_rng_no_graph, deStepCk, did_push_approx_inflection_point, divide_top, dv_create_graph_titles, EV_quit, FirstSeqPlot, FuncLineFlt, get_lb, get_ub, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_Shade, GM_TanLine, gr_CptIndepInc, gr_execute_seq, GR_Pan, gr_xres_pixel, GR3_addContours, GR3_handleEvent, GrAxes, GrClipLine, GrLineFlt, GT_DspTraceCoords, GT_QFloatCursorsInRange, GT_Regraph_if_neccy, GT_SelFunc, GT_SetCursorXY, GT_Trace, GZ_Decimal, GZ_InOut, GZ_Integer, GZ_SetFactors, GZ_Square, GZ_Stat, GZ_Trig, index_if_pushed_binomial_info, index_if_pushed_qquad_info, InitDEAxesRng, InitTimeSeq, is_minus1, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, is_whole_number, is0, is1, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_float_qr_fact, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, push_trig, raise_to_top, Regraph, replace_top_with_post_simplified, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, seqStepCk, spike_in_editor, spike_titles_in_editor, time_loop, times_top, XCvtFtoP, XCvtPtoF, YCvtFtoP, YCvtFtoWin, YCvtPtoF, cmd_blddata, cmd_circle, cmd_cubicreg, cmd_cyclepic, cmd_drawpol, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_newdata, cmd_onevar, cmd_passerr, cmd_powerreg, cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pxlchg, cmd_pxloff, cmd_pxlon, cmd_quadreg, cmd_quartreg, cmd_randseed, cmd_send, cmd_shade, cmd_sinreg, cmd_try, cmd_twovar, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_coldim, push_comb, push_comdenom, push_cos, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_dimension, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_integer_lcm, push_integer_remainder, push_is_prime, push_lim, push_ln, push_log10, push_max, push_min, push_mod, push_nint, push_nsolve, push_nth_derivative, push_numerator, push_perm, push_phase, push_rand, push_randmat, push_randnorm, push_randpoly, push_re, push_red_row_ech, push_round, push_row_echelon, push_rowdim, push_rownorm, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_solve, push_sqrt, push_summation, push_switch, push_tan, push_tanh, push_zeros, did_push_to_polar, push_dot_exponentiate, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_ratio, push_sum, push_to_cylin, push_to_sphere, add_to_top, compare_complex_magnitudes, compare_Floats, did_push_cnvrt_Float_to_integer, estack_number_to_Float, estack_to_short, estack_to_ushort, gcd_exact_whole_Floats, is_Float_exact_whole_number, norm1_complex_Float, push_Float, push_Float_to_nonneg_int, signum_Float, EV_defaultHandler, GD_Circle, GR3_paint3d, GR3_xyToWindow, GZ_Center, CkValidDelta, CptDeltax, CptDeltay, StepCk, sprintf, acosh, asinh, atan2, atanh, cacos, cacosh, casin, casinh, catan, catanh, ccos, ccosh, ceil, cexp, cln, clog10, cosh, csin, csinh, csqrt, ctan, ctanh, fabs, fadd, fcmp, fdiv, float_class, floor, flt, fmod, fmul, fneg, frexp10, fsub, is_inf, is_nan, is_sinf, is_uinf_or_nan, itrig, log, log10, modf, pow, round12_err, sinh, tanh, trig, trunc, VarStore, cmd_lu_fact, cmd_qr_fact, ROM Call 0x48C, ROM Call 0x48D, ROM Call 0x494, ROM Call 0x495, ROM Call 0x4CA, strtod, DateAndTime_SetDlg, DateAndTime_Set, DateAndTime_Get, DayOfTheWeek, TimeStr, ROM Call 0x606


_ds16u16

_ds16u16 Function (ROM Call 0x2A4)

This identifier has not been documented yet. Please help us out.

Used by: cmd_input, cmd_inputstr, cmd_prompt


_ds32s32

_ds32s32 Function (ROM Call 0x2A8)

This identifier has not been documented yet. Please help us out.

Used by: add_to_top, are_units_consistent, compare_numbers, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, times_top, TIOS_strtol, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_im, push_integer_lcm, push_integer_quotient, push_is_prime, push_lim, push_max, push_min, push_mod, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_rotate, push_sequence, push_shift, push_sin2, push_solve, push_summation, push_tan, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_or, push_product, push_sum, push_to_cylin, push_to_sphere, compare_complex_magnitudes, index_below_display_expression_aux, Parse2DExpr, Parse2DMultiExpr, ST_progressUpdate, AddSymToFolder, FolderAdd, FolderDel, FolderRename, HSymDel, SymAddTwin, SymDel, SymDelTwin, ROM Call 0x439, ROM Call 0x47E


_du16u16

_du16u16 Function (ROM Call 0x2A6)

This identifier has not been documented yet. Please help us out.

Used by: add_to_top, are_units_consistent, compare_numbers, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, times_top, cmd_get, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_im, push_integer_lcm, push_integer_quotient, push_is_prime, push_lim, push_list_to_mat, push_max, push_min, push_mod, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_rotate, push_sequence, push_shift, push_sin2, push_solve, push_summation, push_tan, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_or, push_product, push_sum, push_to_cylin, push_to_sphere, Dialog, compare_complex_magnitudes, TE_handleEvent, TE_open, TE_openFixed, TE_pasteText, TE_select


_du32u32

_du32u32 Function (ROM Call 0x2AA)

This identifier has not been documented yet. Please help us out.

Used by: GR3_addContours, cmd_input, cmd_inputstr, cmd_prompt, GR3_paint3d, sprintf, strtol, strtoul, ROM Call 0x58E


_ms16u16

_ms16u16 Function (ROM Call 0x2A5)

This identifier has not been documented yet. Please help us out.


_ms32s32

_ms32s32 Function (ROM Call 0x2A9)

This identifier has not been documented yet. Please help us out.

Used by: add_to_top, are_units_consistent, compare_numbers, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_div_dif_1c, push_format, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, times_top, TIOS_strtol, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_im, push_integer_lcm, push_integer_quotient, push_is_prime, push_lim, push_max, push_min, push_mod, push_nsolve, push_nth_derivative, push_numerator, push_phase, push_re, push_rotate, push_sequence, push_shift, push_sin2, push_solve, push_summation, push_tan, push_zeros, did_push_to_polar, push_and, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not, push_not_equals, push_or, push_product, push_sum, push_to_cylin, push_to_sphere, compare_complex_magnitudes, index_below_display_expression_aux, Parse2DExpr, Parse2DMultiExpr


_mu16u16

_mu16u16 Function (ROM Call 0x2A7)

This identifier has not been documented yet. Please help us out.

Used by: push_list_to_mat, push_rotate, TE_handleEvent, TE_open, TE_openFixed, TE_pasteText, TE_select, FindSymInFolder, FolderAdd, FolderCur, FolderCurTemp, FolderDel, FolderFind, FolderOp, FolderRename, SymFindFirst, SymFindHome, SymFindPtr, ROM Call 0x494, ROM Call 0x495


_mu32u32

_mu32u32 Function (ROM Call 0x2AB)

This identifier has not been documented yet. Please help us out.

Used by: sprintf, strtol, strtoul, ROM Call 0x58E


are_units_consistent

are_units_consistent Function (ROM Call 0x40F)
AMS 2.00 or higher unknown.h

short are_units_consistent (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, did_map_aggregate_arg, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_ratio, push_square, push_sum, ER_catch, ER_success, ER_throwVar, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, is_temperature_unit, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4


assign_between

assign_between Function (ROM Call 0x2AC)
AMS 1.01 or higher unknown.h

short assign_between (ESI var, ESI low, ESI high);

This identifier has not been documented yet. Please help us out.

Uses: VarStore
Used by: cmd_endfor, cmd_for, push_assignment


CheckGraphRef

CheckGraphRef Function (ROM Call 0x7D)
unknown.h

short CheckGraphRef (const SYM_ENTRY *SymEntry);

This identifier has not been documented yet. Please help us out.

Uses: gr_active, gr_other
Used by: spike_geo_titles, spike_optionD, statFree, cmd_newdata, FolderDel, HSymDel, SymDel, SymMove


cleanup_de_mem

cleanup_de_mem Function (ROM Call 0x1EC)
unknown.h

unknown_retval cleanup_de_mem ();

This identifier has not been documented yet. Please help us out.

Uses: unlock_more_graph_fun, HeapFreeIndir, NG_cleanup_graph_fun
Used by: gr_execute_de, GT_Trace, Regraph, cmd_blddata


cleanup_seq_mem

cleanup_seq_mem Function (ROM Call 0x1D7)
unknown.h

unknown_retval cleanup_seq_mem ();

This identifier has not been documented yet. Please help us out.

Uses: unlock_more_graph_fun, HeapFree, HeapFreeIndir, NG_cleanup_graph_fun
Used by: gr_execute_seq, GT_Trace, Regraph, cmd_blddata


clear_error_context

clear_error_context Function (ROM Call 0x44C)
AMS 2.00 or higher unknown.h

void clear_error_context (void);

This identifier has not been documented yet. Please help us out.

Uses: ROM Call 0x5C9, ROM Call 0x5CA, ROM Call 0x5CB, ROM Call 0x5CC
Used by: de_loop, dv_create_graph_titles, execute_graph_func, GM_TanLine, GR_Pan, GR3_addContours, GT_Error, GT_Trace, Regraph, run_one_seq, cmd_clrerr, cmd_endtry, cmd_sendcalc, cmd_sendchat, Dialog, NG_execute, GR3_paint3d, GR3_xyToWindow


ClockOff

ClockOff Function (ROM Call 0x5F6)
AMS 2.07 or higher unknown.h

void ClockOff (void);

This identifier has not been documented yet. Please help us out.

Used by: DateAndTime_SetDlg


ClockOn

ClockOn Function (ROM Call 0x5F5)
AMS 2.07 or higher unknown.h

void ClockOn (void);

This identifier has not been documented yet. Please help us out.

Uses: AB_getGateArrayVersion
Used by: DateAndTime_SetDlg


compare_numbers

compare_numbers Function (ROM Call 0x50D)
AMS 2.02 or higher unknown.h

short compare_numbers (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, primary_tag_list, TIOS_abs, check_estack_size, delete_between, estack_number_to_Float, push_between, push_expression, push_Float, push_quantum, signum_Float, top_estack, ST_helpMsg, XR_stringPtr, fabs, _bcd_math, _du16u16, _ds32s32, _ms32s32, push_exact0
Used by: add_to_top, are_units_consistent, did_push_divide_units, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, cmd_sorta, cmd_sortd, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_median, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, compare_complex_magnitudes, compare_expressions


convert_to_TI_92

convert_to_TI_92 Function (ROM Call 0x258)
unknown.h

void convert_to_TI_92 (HANDLE h);

This identifier has not been documented yet. Please help us out.

Uses: fix_loop_displacements, primary_tag_list, HeapRealloc, next_expression_index, memmove
Used by: sendcalc


CountGrFunc

CountGrFunc Function (ROM Call 0x1D5)
unknown.h

unknown_retval CountGrFunc ();

This identifier has not been documented yet. Please help us out.

Uses: FindGrFunc
Used by: gr_execute_de, gr_execute_seq, GT_DE_Init_Conds, GT_SelFunc, GT_Trace, Regraph, cmd_blddata


cpt_gr_fun

cpt_gr_fun Function (ROM Call 0x1D1)
unknown.h

unknown_retval cpt_gr_fun ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, execute_graph_func, next_expression_index, top_estack
Used by: GT_CalcDepVals, Regraph, cmd_blddata


cpt_gr_param

cpt_gr_param Function (ROM Call 0x1D2)
unknown.h

unknown_retval cpt_gr_param ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, execute_graph_func, gr_del_locals, next_expression_index, top_estack
Used by: GT_CalcDepVals, Regraph, cmd_blddata


cpt_gr_polar

cpt_gr_polar Function (ROM Call 0x1D3)
unknown.h

unknown_retval cpt_gr_polar ();

This identifier has not been documented yet. Please help us out.

Uses: ck_valid_float, estack_to_float, execute_graph_func, next_expression_index, top_estack, sincos, _bcd_math
Used by: GT_CalcDepVals, Regraph, cmd_blddata


CptFuncX

CptFuncX Function (ROM Call 0x1B9*)
unknown.h

float CptFuncX (float, GR_WIN_VARS *);

This identifier has not been documented yet. Please help us out.

Uses: round12_err, _bcd_math
Used by: XCvtPtoF


CptIndep

CptIndep Function (ROM Call 0x1C9)
unknown.h

unsigned char CptIndep (float *, float *, unsigned short);

This identifier has not been documented yet. Please help us out.

Uses: ck_valid_float, round12, _bcd_math
Used by: de_loop, Regraph, cmd_blddata, cmd_drawparm, cmd_drawpol


CptLastIndepDE

CptLastIndepDE Function (ROM Call 0x1EF)
unknown.h

unknown_retval CptLastIndepDE ();

This identifier has not been documented yet. Please help us out.

Uses: floor, round12, round12_err, _bcd_math
Used by: de_initRes, de_rng_no_graph, gr_CptIndepInc, GT_Trace, InitDEAxesRng, Regraph, cmd_blddata


CustomBegin

CustomBegin Function (ROM Call 0x14A)
unknown.h

void CustomBegin (void);

This identifier has not been documented yet. Please help us out.

Uses: CustomFree, HeapMoveHigh, HeapUnlock, HLock, MenuBegin, ROM Call 0x4FB
Used by: cmd_custmon, EV_defaultHandler


CustomEnd

CustomEnd Function (ROM Call 0x14C)
unknown.h

void CustomEnd (void);

This identifier has not been documented yet. Please help us out.

Uses: HeapUnlock, MenuEnd, MenuUpdate, ROM Call 0x4FB
Used by: CustomFree, cmd_custmoff, EV_defaultHandler


CustomFree

CustomFree Function (ROM Call 0x150)
unknown.h

void CustomFree (void);

This identifier has not been documented yet. Please help us out.

Uses: CustomEnd, HeapFreeIndir
Used by: CustomBegin, cmd_custom, cmd_toolbar


CustomMenuItem

CustomMenuItem Function (ROM Call 0x14B)
unknown.h

short CustomMenuItem (unsigned short id);

This identifier has not been documented yet. Please help us out.

Uses: SearchExprStruct, next_expression_index, EV_sendEvent
Used by: EV_defaultHandler


DateAndTime_Get

DateAndTime_Get Function (ROM Call 0x5F3)
AMS 2.07 or higher unknown.h

void DateAndTime_Get (unsigned short *year, unsigned short *month, unsigned short *day, unsigned short *hour, unsigned short *minute, unsigned short *second);

This identifier has not been documented yet. Please help us out.

Uses: EV_defaultHandler, fabs, fmod, _bcd_math, TimeZone_Get
Used by: EV_quit, EV_defaultHandler, DateAndTime_SetDlg


DateAndTime_Set

DateAndTime_Set Function (ROM Call 0x5F2)
AMS 2.07 or higher unknown.h

void DateAndTime_Set (unsigned short year, unsigned short month, unsigned short day, unsigned short hour, unsigned short minute, unsigned short second);

This identifier has not been documented yet. Please help us out.

Uses: fmod, _bcd_math, TimeZone_Get
Used by: DateAndTime_SetDlg


DateAndTime_SetDlg

DateAndTime_SetDlg Function (ROM Call 0x5F1)
AMS 2.07 or higher unknown.h

void DateAndTime_SetDlg (void);

This identifier has not been documented yet. Please help us out.

Uses: Dialog, ER_catch, ER_success, ERD_dialog, estack_to_ushort, next_expression_index, push_parse_text, top_estack, memset, sprintf, AB_getGateArrayVersion, OSClearBreak, fmod, _bcd_math, DateAndTime_Set, DateAndTime_Get, ClockOn, ClockOff, IsClockOn
Used by: EV_quit, EV_defaultHandler


DateFormat_Get

DateFormat_Get Function (ROM Call 0x5FC)
AMS 2.07 or higher unknown.h

unsigned char DateFormat_Get (void);

This identifier has not been documented yet. Please help us out.


DateFormat_Set

DateFormat_Set Function (ROM Call 0x5FD)
AMS 2.07 or higher unknown.h

void DateFormat_Set (unsigned char NewDateFormat);

This identifier has not been documented yet. Please help us out.


DateStr

DateStr Function (ROM Call 0x5FE)
AMS 2.07 or higher unknown.h

void DateStr (unsigned short year, unsigned short month, unsigned short day, unsigned char DateFormat, char* str);

This identifier has not been documented yet. Please help us out.

Uses: memset, sprintf, strcat
Used by: EV_quit, EV_defaultHandler


DayOfTheWeek

DayOfTheWeek Function (ROM Call 0x5F4)
AMS 2.07 or higher unknown.h

unsigned short DayOfTheWeek (unsigned short year, unsigned short month, unsigned short day);

This identifier has not been documented yet. Please help us out.

Uses: strcat, fmod, _bcd_math


de_initRes

de_initRes Function (ROM Call 0x1F0)
unknown.h

unknown_retval de_initRes ();

This identifier has not been documented yet. Please help us out.

Uses: CharNumber, CptLastIndepDE, gen_version, gr_find_de_result, gr_find_el, gr_initCondName, gr_openFolder, HeapAllocThrow, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, NG_approxESI, push_END_TAG, push_expression, push_Float, push_LIST_TAG, top_estack, gr_active, memcpy, fabs, round12_err, AddSymToFolder, DerefSym, FindSymInFolder, FolderDelAllTemp, HSymDel, SymFind, SymFindMain, TempFolderName, VarStore, _bcd_math
Used by: GT_Trace, InitDEMem, Regraph


de_loop

de_loop Function (ROM Call 0x1EB)
unknown.h

unknown_retval de_loop ();

This identifier has not been documented yet. Please help us out.

Uses: CharNumber, ck_valid_float, clear_error_context, CptIndep, estack_to_float, gen_version, gr_CptIndepInc, gr_del_locals, gr_find_el, gr_openFolder, QSkipGraphErr, HeapAllocThrow, HeapDeref, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, delete_between, HToESI, next_expression_index, NG_graphESI, push_END_TAG, push_Float, push_LIST_TAG, top_estack, gr_active, gr_flags, memcpy, fabs, is_transfinite, pow, round12_err, AddSymToFolder, DerefSym, FolderDelAllTemp, HSymDel, ResetSymFlags, SymFind, TempFolderName, VarStore, _bcd_math
Used by: gr_execute_de, GT_Trace, Regraph, cmd_blddata


de_rng_no_graph

de_rng_no_graph Function (ROM Call 0x2A2)
unknown.h

unknown_retval de_rng_no_graph ();

This identifier has not been documented yet. Please help us out.

Uses: CptLastIndepDE, deStepCk, gr_active, fabs, _bcd_math
Used by: gr_execute_de


delete_list_element

delete_list_element Function (ROM Call 0x2AF)
AMS 1.01 or higher unknown.h

short delete_list_element (CESI var, unsigned short element);

This identifier has not been documented yet. Please help us out.

Uses: HeapRealloc, next_expression_index, memmove, DerefSym, VarRecall, VarStore


deStepCk

deStepCk Function (ROM Call 0x1F9)
unknown.h

unknown_retval deStepCk ();

This identifier has not been documented yet. Please help us out.

Uses: StepCk, _bcd_math
Used by: de_rng_no_graph, Regraph, cmd_blddata


did_map_aggregate_arg

did_map_aggregate_arg Function (ROM Call 0x5B8)
AMS 2.04 or higher unknown.h

short did_map_aggregate_arg (Two_ESI_Callback_t, ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: delete_between, push_offset_array, push_quantum, top_estack
Used by: are_units_consistent, get_ub, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_abs, push_comb, push_csolve, push_czeros, push_def_int, push_desolve, push_integer_gcd, push_integer_lcm, push_integer_quotient, push_integer_remainder, push_lim, push_max, push_max2, push_min, push_min2, push_mod, push_nsolve, push_perm, push_rec_to_angle, push_solve, push_zeros, did_push_to_polar, push_dot_add, push_dot_div, push_dot_exponentiate, push_dot_mult, push_dot_sub, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_to_cylin, push_polar_to_rect_x, push_polar_to_rect_y


did_push_approx_inflection_point

did_push_approx_inflection_point Function (ROM Call 0x5B0)
AMS 2.02 or higher unknown.h

short did_push_approx_inflection_point (ESI, ESI, float, float);

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, Float1Index, get_lb, get_ub, Integer0Index, Integer2Index, is_constant, is_positive, is_undefined, is_variable, is0, NG_control, primary_tag_list, replace_top2_with_or, replace_top2_with_prod, times_top, push_1st_derivative, push_abs, push_approx, push_lim, push_nth_derivative, push_difference, push_product, push_substitute_simplify, push_substitute_using_such_that, ER_catch, ER_success, ER_throwVar, delete_between, is_free_of_tag, likely_approx_to_number, next_expression_index, push_expr_quantum, push_expression, push_Float, push_internal_simplify, push_quantum, top_estack, fabs, is_nan, DerefSym, VarRecall, _bcd_math, ROM Call 0x460, ROM Call 0x461, ROM Call 0x5E5, ROM Call 0x5EB
Used by: GM_Inflection


did_push_divide_units

did_push_divide_units Function (ROM Call 0x3AE)
AMS 1.01 or higher unknown.h

unknown_retval did_push_divide_units ();

This identifier has not been documented yet. Please help us out.

Uses: compare_numbers, has_unit_base, is0, replace_top2_with_imre, replace_top2_with_sum, push_ratio, compare_expressions, lead_base_index, lead_exponent_index, next_expression_index, push_expression, remaining_factors_index, top_estack, ROM Call 0x4DF, ROM Call 0x4E2
Used by: push_auto_units_conversion, replace_top_with_post_simplified


did_push_lincf

did_push_lincf Function (ROM Call 0x572)
AMS 2.02 or higher unknown.h

short did_push_lincf (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: is_variable, primary_tag_list, push0, push1, replace_top2_with_imre, replace_top2_with_sum, times_top, are_expressions_identical, is_independent_of, next_expression_index, top_estack
Used by: did_push_anti_deriv, push_def_int, push_desolve, push_extended_prod, push_summation


did_push_var_val

did_push_var_val Function (ROM Call 0x2AD)
AMS 1.01 or higher unknown.h

short did_push_var_val (ESI var);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, next_expression_index, push_between, DerefSym, VarRecall
Used by: push_simplify, push_csolve, push_czeros, push_max, push_min, push_nsolve, push_solve, push_zeros, push_internal_simplify


does_push_fetch

does_push_fetch Function (ROM Call 0x2AE)
AMS 1.01 or higher unknown.h

short does_push_fetch (ESI var);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, check_estack_size, push_between, DerefSym, VarRecall
Used by: push_simplify, cmd_passerr, push_csolve, push_czeros, push_max, push_min, push_nsolve, push_solve, push_zeros, push_internal_simplify, ROM Call 0x468


dv_create_graph_titles

dv_create_graph_titles Function (ROM Call 0x117)
unknown.h

unknown_retval dv_create_graph_titles ();

This identifier has not been documented yet. Please help us out.

Uses: clear_error_context, estack_to_float, ForceFloat, grFuncName, GrLineFlt, QSkipGraphErr, ST_flags, XCvtFtoP, XCvtPtoF, YCvtPtoF, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, NG_approxESI, push_expression, push_Float, push_quantum, top_estack, gr_active, OSCheckBreak, is_transfinite, round12_err, round14, sincos, DerefSym, SymFindMain, MakeWinRect, WinLine, _bcd_math
Used by: spike_in_editor, spike_optionD


dv_findColumn

dv_findColumn Function (ROM Call 0x119)
unknown.h

unknown_retval dv_findColumn ();

This identifier has not been documented yet. Please help us out.

Used by: GetStatValue, push_subscripted_element


EQU_deStatus

EQU_deStatus Function (ROM Call 0x16E)
unknown.h

unknown_retval EQU_deStatus ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active, ST_helpMsg, XR_stringPtr


EQU_getNameInfo

EQU_getNameInfo Function (ROM Call 0x120)
unknown.h

unknown_retval EQU_getNameInfo ();

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable, is_pathname, next_token, primary_tag_list, push_ans_entry, push_var, ER_throwVar, are_expressions_identical, check_estack_size, delete_between, delete_expression, is_valid_smap_aggregate, move_between_to_top, next_expression_index, push_between, push_expression, push_Float, push_quantum, push_quantum_pair, push_reversed_tail, top_estack, sprintf, OSCheckBreak, XR_stringPtr, CheckReservedName, DerefSym, FindSymInFolder, TempFolderName, strtod, ROM Call 0x5C5, ROM Call 0x5EF, ROM Call 0x5F0
Used by: EQU_select, EQU_setStyle


EQU_select

EQU_select Function (ROM Call 0x11E)
unknown.h

short EQU_select (short, EQU_SELECT);

This identifier has not been documented yet. Please help us out.

Uses: EQU_getNameInfo, HToESI, gr_active, DerefSym, SymFindMain
Used by: cmd_fnoff, cmd_fnon


EQU_setStyle

EQU_setStyle Function (ROM Call 0x11F)
unknown.h

void EQU_setStyle (GR_WIN_VARS *, short, unsigned short, short, short);

This identifier has not been documented yet. Please help us out.

Uses: EQU_getNameInfo, HToESI, gr_other, DerefSym, SymFindMain
Used by: cmd_style


ER_throwFrame

ER_throwFrame Function (ROM Call 0x507)
AMS 2.00 or higher unknown.h

void ER_throwFrame (short, pFrame);

This identifier has not been documented yet. Please help us out.

Uses: NG_control, NG_such_that_index


estack_to_float

estack_to_float Function (ROM Call 0x469*)
AMS 2.00 or higher unknown.h

float estack_to_float (CESI);

This identifier has not been documented yet. Please help us out.

Used by: add_to_top, are_units_consistent, compare_numbers, cpt_gr_fun, cpt_gr_param, cpt_gr_polar, de_loop, did_push_approx_inflection_point, dv_create_graph_titles, ForceFloat, get_lb, get_ub, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_de_value, gr_execute_de, gr_execute_seq, gr_seq_value, GR3_addContours, GT_CalcDepVals, index_if_pushed_binomial_info, index_if_pushed_qquad_info, is_minus1, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, is_whole_number, is0, is1, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, push_trig, raise_to_top, Regraph, replace_top_with_post_simplified, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_sum, seqWebInit, time_loop, times_top, EX_getBCD, cmd_blddata, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_passerr, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_randseed, cmd_send, cmd_sinreg, cmd_twovar, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acos, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_cos, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_fractional_part, push_gcd_numbers, push_im, push_integer_remainder, push_is_prime, push_lim, push_ln, push_log10, push_max, push_min, push_mod, push_nint, push_nsolve, push_numerator, push_perm, push_phase, push_rand, push_randnorm, push_re, push_rec_to_angle, push_red_row_ech, push_round, push_row_echelon, push_rownorm, push_sequence, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_solve, push_sqrt, push_summation, push_switch, push_tan, push_tanh, push_zeros, did_push_to_polar, push_dot_exponentiate, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_pow, push_product, push_sum, push_to_cylin, push_to_sphere, compare_Floats, did_push_cnvrt_Float_to_integer, estack_number_to_Float, estack_to_short, estack_to_ushort, gcd_exact_whole_Floats, index_below_display_expression_aux, is_Float_exact_whole_number, norm1_complex_Float, Parse1DExpr, Parse2DExpr, Parse2DMultiExpr, push_Float_to_rat, signum_Float, GR3_paint3d, GR3_xyToWindow, ROM Call 0x46F, cmd_lu_fact, cmd_qr_fact, ROM Call 0x48C, ROM Call 0x48D, ROM Call 0x494, ROM Call 0x495, ROM Call 0x4CA, ROM Call 0x606


execute_graph_func

execute_graph_func Function (ROM Call 0x1D0)
unknown.h

unknown_retval execute_graph_func ();

This identifier has not been documented yet. Please help us out.

Uses: clear_error_context, QSkipGraphErr, HeapDeref, ER_catch, ER_success, ER_throwVar, NG_graphESI, memcpy, FolderDelAllTemp, ResetSymFlags
Used by: cpt_gr_fun, cpt_gr_param, cpt_gr_polar


FindFunc

FindFunc Function (ROM Call 0x1C5)
unknown.h

HSym FindFunc (unsigned char, unsigned char name[], HSym *);

This identifier has not been documented yet. Please help us out.

Uses: FindGrFunc, gr_active, gr_flags
Used by: GM_Shade, GR3_addContours, GT_CalcDepVals, GT_SelFunc, GT_Trace, Regraph, cmd_blddata, GR3_paint3d, GR3_xyToWindow


FindGrFunc

FindGrFunc Function (ROM Call 0x1C6)
unknown.h

SYM_ENTRY *FindGrFunc (unsigned char, HSym *, ESI *, unsigned char name[], unsigned char);

This identifier has not been documented yet. Please help us out.

Uses: grFuncName, HToESI, gr_active, DerefSym, SymFindMain
Used by: CountGrFunc, FindFunc, GT_DE_Init_Conds, InitDEMem, InitTimeSeq, Regraph, cmd_blddata, cmd_fnon, gdb_recall


FirstSeqPlot

FirstSeqPlot Function (ROM Call 0x1D6)
unknown.h

unknown_retval FirstSeqPlot ();

This identifier has not been documented yet. Please help us out.

Uses: ck_valid_float, gr_active, floor, _bcd_math
Used by: gr_CptIndepInc, GT_Trace, Regraph, cmd_blddata


fix_loop_displacements

fix_loop_displacements Function (ROM Call 0x170)
unknown.h

void fix_loop_displacements (ESI esi);

This identifier has not been documented yet. Please help us out.

Uses: index_after_match_endtag, next_expression_index
Used by: convert_to_TI_92, push_parse_prgm_or_func_text, push_parse_text


ForceFloat

ForceFloat Function (ROM Call 0x47D*)
AMS 2.00 or higher unknown.h

float ForceFloat (ESI);

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, NG_approxESI, top_estack, round14
Used by: dv_create_graph_titles, GM_TanLine, GS_PlotTrace, cmd_circle, cmd_cyclepic, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_line, cmd_linehorz, cmd_linetan, cmd_linevert, cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pttext, cmd_pxlchg, cmd_pxloff, cmd_pxlon, cmd_pxltext, cmd_shade, cmd_showstat, cmd_slpline, push_pttest, push_pxltest, VarStore


FuncLineFlt

FuncLineFlt Function (ROM Call 0x1BF)
unknown.h

unknown_retval FuncLineFlt ();

This identifier has not been documented yet. Please help us out.

Uses: GrClipLine, GT_WinCursor, XCvtFtoP, YCvtFtoP, gr_active, is_transfinite, round12, MakeWinRect, WinAttr, WinFillLines2, WinLineNC, WinPixSet, _bcd_math
Used by: Regraph


gen_version

gen_version Function (ROM Call 0x259)
unknown.h

unsigned char gen_version (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, next_expression_index, secondary_tag_list
Used by: de_initRes, de_loop, InitDEMem, tokenize_if_TI_92_or_text, cmd_newdata, gdb_recall, LIO_Receive, VarStore


get_lb

get_lb Function (ROM Call 0x516*)
AMS 2.02 or higher unknown.h

float get_lb (ESI);

This function is used when solving an equation in the solver app (TIINSLVR). "lb" is short for "lower bound".

Uses: estack_to_float, lead_conjunct_factor_index, NG_control, NG_such_that_index, remaining_conjuncts_index, are_expressions_identical, next_expression_index, push_internal_simplify, top_estack, _bcd_math
Used by: add_to_top, are_units_consistent, did_push_approx_inflection_point, get_ub, index_if_pushed_qquad_info, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_atanh, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_mod, push_nint, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_red_row_ech, push_row_echelon, push_rownorm, push_sign, push_simult, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, ROM Call 0x606


get_list_indices

get_list_indices Function (ROM Call 0x2B8)
AMS 1.01 or higher unknown.h

unknown_retval get_list_indices ();

This identifier has not been documented yet. Please help us out.

Uses: init_list_indices, RemainingArgCnt, check_estack_size, top_estack
Used by: push_list_to_mat, push_median, push_mrowadd, push_rowadd, push_rowdim, push_rowswap, push_stddev, push_variance


get_matrix_indices

get_matrix_indices Function (ROM Call 0x2B9)
AMS 1.01 or higher unknown.h

unknown_retval get_matrix_indices ();

This identifier has not been documented yet. Please help us out.

Uses: init_matrix_indices, RemainingArgCnt, check_estack_size, top_estack
Used by: push_cross_product, push_diag, push_matnorm, push_median, push_rownorm, push_submat, push_matrix_product, push_transpose_aux, cmd_lu_fact


get_ub

get_ub Function (ROM Call 0x517*)
AMS 2.02 or higher unknown.h

float get_ub (ESI);

This function is used when solving an equation in the solver app (TIINSLVR). "ub" is short for "upper bound".

Uses: add_to_top, add1_to_top, and_onto_top, compare_numbers, did_map_aggregate_arg, divide_top, estack_to_float, Float0Index, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, has_different_variable, index_false, index_rmng_factor, index_rmng_fctrs_start_base_tag, index_rmng_fctrs_start_fctr_tag, index_true, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_complex_Float, is_constant, is_equivalent_to, is_minus1, is_neg_lead_numr_coef_re_part, is_negative, is_never0, is_nonnegative, is_nonpositive, is_polynomial_in_var_or_kern, is_pos_int_and_eq_quantum, is_positive, is_real, is_reciprocal_of_quantum, is_undefined, is_variable, is_whole_number, is0, is1, lead_conjunct_factor_index, lead_disjunct_term_index, linear_degree, negate_top, next_var_or_kernel_index, NG_control, NG_such_that_index, or_onto_top, primary_tag_list, push_but_conjunct_factor, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_minus_recip_of_quantum, push_negate_quantum_as_negint, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_pi, push_pi_on_quantum, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push_var_kern_tail, push0, push1, raise_to_top, RAtionalize_tol, remaining_conjuncts_index, remaining_disjuncts_index, replace_top_with_reciprocal, replace_top2_with_and, replace_top2_with_difference, replace_top2_with_imre, replace_top2_with_or, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, RemainingArgCnt, did_push_series, push_1st_derivative, push_abs, push_acosh, push_approx, push_asin, push_asinh, push_atan, push_atanh, push_ceiling, push_conj, push_cos, push_cosh, push_denominator, push_exp, push_expand, push_factor, push_floor, push_gcd_numbers, push_im, push_integer_lcm, push_list_to_mat, push_ln, push_mat_to_list, push_max2, push_mod, push_numerator, push_phase, push_re, push_rec_to_angle, push_sign, push_simult, push_sin, push_sin2, push_sinh, push_sqrt, push_tan, push_tanh, push_and, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_matrix_product, push_negate, push_not, push_pow, push_product, push_ratio, push_square, push_substitute_simplify, push_substitute_using_such_that, push_sum, ER_catch, ER_success, ER_throwVar, all_tail, any_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, im_index, index_main_var, is_advanced_tag, is_antisymmetric, is_complex_number, is_complex0, is_free_of_tag, is_independent_of, is_independent_of_elements, is_independent_of_tail, is_monomial, is_monomial_in_kernel, is_symmetric, is_tail_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_complex_number, likely_approx_to_number, main_gen_var_index, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, norm1_complex_Float, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_Float_to_rat, push_internal_simplify, push_next_arb_int, push_next_arb_real, push_next_internal_var, push_offset_array, push_quantum, push_quantum_pair, push_reversed_tail, re_index, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, fabs, float_class, fmod, is_inf, is_nan, log, sin, sqrt, tan, tanh, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x460, ROM Call 0x461, ROM Call 0x462, ROM Call 0x48C, push_no_solution_found_string, push_subscripted_element, push_transpose, ROM Call 0x4DF, ROM Call 0x4E6, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, push_minus1, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4, ROM Call 0x5E5, ROM Call 0x5E8, ROM Call 0x5EB, ROM Call 0x606
Used by: add_to_top, are_units_consistent, did_push_approx_inflection_point, index_if_pushed_qquad_info, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_lu_fact, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_sq_matrix_to_whole_number, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_acosh, push_asin, push_atanh, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_determinant, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_mod, push_nint, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_red_row_ech, push_row_echelon, push_rownorm, push_sign, push_simult, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, ROM Call 0x606


GetStatValue

GetStatValue Function (ROM Call 0x11B)
unknown.h

unknown_retval GetStatValue ();

This identifier has not been documented yet. Please help us out.

Uses: CharNumber, CTypeTable, dv_findColumn, estack_to_float, PlotGet, HeapLock, HeapUnlock, RemainingArgCnt, ER_catch, ER_success, ER_throwVar, compare_Floats, HToESI, next_expression_index, NG_approxESI, push_quantum, push_quantum_pair, top_estack, gr_active, gr_flags, checkCurrent, DerefSym, FindSymInFolder, SymCmp, VarRecall, _bcd_math, ROM Call 0x45A
Used by: GS_PlotAll, GS_PlotTrace, GZ_Stat, ROM Call 0x4CB


GetSysGraphRef

GetSysGraphRef Function (ROM Call 0x8A)
unknown.h

unsigned short GetSysGraphRef (unsigned short num);

This identifier has not been documented yet. Please help us out.

Uses: gr_active, gr_other
Used by: spike_chk_gr_dirty, statFree, VarStore


GM_Derivative

GM_Derivative Function (ROM Call 0x1B0)
unknown.h

unknown_retval GM_Derivative ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, grFuncName, GT_SelFunc, GT_Trace, ST_flags, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, NG_approxESI, push_expression, push_Float, push_quantum, top_estack, gr_active, is_transfinite, round12_err, round14, sincos, DerefSym, SymFindMain, _bcd_math


GM_DistArc

GM_DistArc Function (ROM Call 0x1B1)
unknown.h

unknown_retval GM_DistArc ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, grFuncName, GT_SelFunc, GT_ShowMarkers, GT_Trace, ST_flags, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, NG_approxESI, push_expression, push_Float, push_quantum, top_estack, gr_active, round12_err, round14, sqrt, DerefSym, SymFindMain, _bcd_math


GM_Inflection

GM_Inflection Function (ROM Call 0x1AD)
unknown.h

unknown_retval GM_Inflection ();

This identifier has not been documented yet. Please help us out.

Uses: did_push_approx_inflection_point, estack_to_float, grFuncName, GT_SelFunc, GT_Trace, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, NG_approxESI, push_expression, push_quantum, top_estack, gr_active, round14, DerefSym, SymFindMain, _bcd_math


GM_Integrate

GM_Integrate Function (ROM Call 0x1AC)
unknown.h

unknown_retval GM_Integrate ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, grFuncName, GT_CalcDepVals, GT_SelFunc, GT_Trace, XCvtFtoP, XCvtPtoF, YCvtFtoWin, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, NG_approxESI, push_expression, push_Float, push_quantum, top_estack, gr_active, is_transfinite, round14, DerefSym, SymFindMain, MakeWinRect, WinAttr, WinLine, _bcd_math


GM_Intersect

GM_Intersect Function (ROM Call 0x1AB)
unknown.h

unknown_retval GM_Intersect ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, grFuncName, GT_SelFunc, GT_Trace, NG_control, primary_tag_list, replace_top2_with_or, push_substitute_using_such_that, ER_catch, ER_success, ER_throwVar, compare_expressions, delete_between, HToESI, is_constant, is_free_of_tag, next_expression_index, NG_approxESI, push_expr_quantum, push_expression, push_Float, push_quantum, top_estack, gr_active, fabs, is_nan, round14, DerefSym, SymFindMain, _bcd_math, ROM Call 0x460, ROM Call 0x461, ROM Call 0x5E5, ROM Call 0x5EB


GM_Math1

GM_Math1 Function (ROM Call 0x1AF)
unknown.h

unknown_retval GM_Math1 ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, grFuncName, GT_SelFunc, GT_Trace, NG_control, primary_tag_list, replace_top2_with_or, push_substitute_using_such_that, ER_catch, ER_success, ER_throwVar, delete_between, HToESI, is_constant, is_free_of_tag, next_expression_index, NG_approxESI, push_expr_quantum, push_expression, push_Float, push_quantum, top_estack, gr_active, fabs, is_nan, round14, DerefSym, SymFindMain, _bcd_math, ROM Call 0x460, ROM Call 0x461, ROM Call 0x5E5, ROM Call 0x5EB


GM_Shade

GM_Shade Function (ROM Call 0x1B2)
unknown.h

unknown_retval GM_Shade ();

This identifier has not been documented yet. Please help us out.

Uses: FindFunc, gr_xres_pixel, GT_CalcDepVals, GT_CursorKey, GT_DspMsg, GT_SelFunc, GT_Trace, XCvtFtoP, XCvtPtoF, YCvtFtoWin, ER_catch, ER_success, ER_throwVar, gr_active, KeyYesOrNo, memset, XR_stringPtr, is_transfinite, MakeWinRect, WinAttr, WinFillLines2, WinLine, _bcd_math


GM_TanLine

GM_TanLine Function (ROM Call 0x1AE)
unknown.h

unknown_retval GM_TanLine ();

This identifier has not been documented yet. Please help us out.

Uses: clear_error_context, estack_to_float, ForceFloat, grFuncName, GrLineFlt, GT_SelFunc, GT_Trace, QSkipGraphErr, ST_flags, XCvtFtoP, XCvtPtoF, YCvtPtoF, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, NG_approxESI, push_expression, push_Float, push_quantum, top_estack, gr_active, OSCheckBreak, is_transfinite, round12_err, round14, sincos, DerefSym, SymFindMain, MakeWinRect, WinLine, _bcd_math


GM_Value

GM_Value Function (ROM Call 0x1AA)
unknown.h

unknown_retval GM_Value ();

This identifier has not been documented yet. Please help us out.

Uses: GT_SelFunc, GT_Trace, gr_active


gr_add_fldpic

gr_add_fldpic Function (ROM Call 0x1F6)
unknown.h

void gr_add_fldpic (void);

This identifier has not been documented yet. Please help us out.

Uses: gr_remove_fldpic, gr_active, gr_other, DerefSym, SymAddMain, SymFindMain


gr_ck_solvergraph

gr_ck_solvergraph Function (ROM Call 0x1FA)
unknown.h

void gr_ck_solvergraph (GR_WIN_VARS *gv);

This identifier has not been documented yet. Please help us out.

Uses: GraphOrTableCmd, grFuncName, PlotLookup, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, push_END_TAG, push_expression, push_quantum, top_estack, gr_active, gr_flags, DerefSym, HSymDel, SymFindMain, ROM Call 0x46A


gr_CptIndepInc

gr_CptIndepInc Function (ROM Call 0x1CA)
unknown.h

unsigned char gr_CptIndepInc (float, float *, unsigned short *);

This identifier has not been documented yet. Please help us out.

Uses: CptLastIndepDE, FirstSeqPlot, gr_active, floor, _bcd_math
Used by: de_loop, GT_Trace, Regraph, cmd_blddata


gr_de_axes_lbl

gr_de_axes_lbl Function (ROM Call 0x1F2)
unknown.h

unknown_retval gr_de_axes_lbl ();

This identifier has not been documented yet. Please help us out.

Uses: TIOS_abs, sprintf, strlen
Used by: gr_DispLabels, GT_DspTraceCoords, GT_Trace


gr_de_value

gr_de_value Function (ROM Call 0x1ED)
unknown.h

unknown_retval gr_de_value ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, gr_find_de_result, gr_find_el, gr_find_func_index, TIOS_abs, HToESI, gr_active, gr_flags, DerefSym, SymFind
Used by: gr_execute_de, GT_Trace, Regraph


gr_del_locals

gr_del_locals Function (ROM Call 0x1CB)
unknown.h

unknown_retval gr_del_locals ();

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable, gr_active, SymDel, SymFindFirst, SymFindNext, TempFolderName
Used by: cpt_gr_param, de_loop, GT_CalcDepVals, Regraph, run_one_seq, cmd_blddata, GR3_paint3d


gr_del_vars_in_folder

gr_del_vars_in_folder Function (ROM Call 0x1F1)
unknown.h

unknown_retval gr_del_vars_in_folder ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active, FolderDel
Used by: gr_execute_de, GT_Trace, Regraph, cmd_blddata


gr_delete_fldpic

gr_delete_fldpic Function (ROM Call 0x1F4)
unknown.h

void gr_delete_fldpic (GR_WIN_VARS *);

This identifier has not been documented yet. Please help us out.

Uses: gr_remove_fldpic, HeapFreeIndir
Used by: Regraph, SetGraphMode, OSLinkCmd


gr_DelFolder

gr_DelFolder Function (ROM Call 0x1CC)
unknown.h

void gr_DelFolder (GR_WIN_VARS *gv);

This identifier has not been documented yet. Please help us out.

Uses: FolderDel
Used by: SetGraphMode, cmd_clrgraph, gdb_recall, OSLinkCmd


gr_DispLabels

gr_DispLabels Function (ROM Call 0x1E3)
unknown.h

void gr_DispLabels (GR_WIN_VARS *);

This identifier has not been documented yet. Please help us out.

Uses: gr_de_axes_lbl, GXcoord, GYcoord, gr_active, sprintf, strlen, WinAttr, WinDupStat, WinStrXY
Used by: GR_Pan, GT_BackupToScr, Regraph


gr_execute_de

gr_execute_de Function (ROM Call 0x1F3)
unknown.h

unknown_retval gr_execute_de ();

This identifier has not been documented yet. Please help us out.

Uses: cleanup_de_mem, CountGrFunc, de_loop, de_rng_no_graph, estack_to_float, gr_de_value, gr_del_vars_in_folder, InitDEMem, HeapAllocThrow, ER_catch, ER_success, ER_throwVar, NG_approxESI, push_Float, push_quantum, top_estack, gr_active, gr_flags, is_transfinite, FolderDelAllTemp
Used by: push_user_func


gr_execute_seq

gr_execute_seq Function (ROM Call 0x1D4)
unknown.h

unknown_retval gr_execute_seq ();

This identifier has not been documented yet. Please help us out.

Uses: cleanup_seq_mem, CountGrFunc, estack_to_float, InitTimeSeq, seqStepCk, time_loop, HeapAllocThrow, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, NG_approxESI, push_Float, push_quantum, top_estack, gr_active, gr_flags, floor, is_transfinite, DerefSym, FolderDelAllTemp, SymFind, _bcd_math
Used by: push_user_func


gr_find_de_result

gr_find_de_result Function (ROM Call 0x1E8)
unknown.h

unknown_retval gr_find_de_result ();

This identifier has not been documented yet. Please help us out.

Uses: CharNumber, gr_active, FindSymInFolder
Used by: de_initRes, gr_de_value, cmd_blddata, VarRecall


gr_find_el

gr_find_el Function (ROM Call 0x1F8)
unknown.h

unknown_retval gr_find_el ();

This identifier has not been documented yet. Please help us out.

Uses: HToESI, next_expression_index
Used by: de_initRes, de_loop, gr_de_value, Regraph, cmd_blddata


gr_find_func_index

gr_find_func_index Function (ROM Call 0x1EE)
unknown.h

unknown_retval gr_find_func_index ();

This identifier has not been documented yet. Please help us out.

Used by: gr_de_value, VarRecall


gr_initCondName

gr_initCondName Function (ROM Call 0x1C8)
unknown.h

unknown_retval gr_initCondName ();

This identifier has not been documented yet. Please help us out.

Uses: CharNumber
Used by: gdb_len, gdb_recall, gdb_store, de_initRes, GT_SelFunc, GT_Trace, InitDEMem, seqWebInit


gr_openFolder

gr_openFolder Function (ROM Call 0x1CD)
unknown.h

void gr_openFolder (GR_WIN_VARS *gv);

This identifier has not been documented yet. Please help us out.

Uses: FolderAdd
Used by: de_initRes, de_loop, GraphOrTableCmd, InitDEMem


GR_Pan

GR_Pan Function (ROM Call 0x1C4)
unknown.h

unknown_retval GR_Pan ();

This identifier has not been documented yet. Please help us out.

Uses: clear_error_context, gr_DispLabels, GT_BackupToScr, ER_catch, ER_throwVar, top_estack, gr_active, memset, fabs, ResetSymFlags, _bcd_math
Used by: GT_Trace


gr_remove_fldpic

gr_remove_fldpic Function (ROM Call 0x1F5)
unknown.h

void gr_remove_fldpic (GR_WIN_VARS *gv);

This identifier has not been documented yet. Please help us out.

Uses: DerefSym, HSymDel, SymFindMain
Used by: gr_add_fldpic, gr_delete_fldpic


gr_seq_value

gr_seq_value Function (ROM Call 0x1DC)
unknown.h

unknown_retval gr_seq_value ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, HToESI, gr_active, DerefSym, SymFind
Used by: GT_Trace, Regraph


gr_stopic

gr_stopic Function (ROM Call 0x1F7)
unknown.h

unknown_retval gr_stopic ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active, DerefSym, VarStore, MakeWinRect, WinBitmapGet, WinBitmapSize, WinDupStat
Used by: Regraph, cmd_stopic


gr_xres_pixel

gr_xres_pixel Function (ROM Call 0x1B8)
unknown.h

unsigned short gr_xres_pixel (unsigned short, unsigned char);

This identifier has not been documented yet. Please help us out.

Uses: gr_active, floor, _bcd_math
Used by: GM_Shade, GT_Trace, Regraph, cmd_blddata


GR3_addContours

GR3_addContours Function (ROM Call 0x1FB)
unknown.h

unknown_retval GR3_addContours ();

This identifier has not been documented yet. Please help us out.

Uses: clear_error_context, estack_to_float, FindFunc, QSkipGraphErr, HeapAllocThrow, HeapDeref, HeapFreeIndir, ER_catch, ER_success, ER_throwVar, NG_graphESI, top_estack, gr_active, memcpy, sprintf, XR_stringPtr, is_transfinite, round12, WinAttr, WinClr, WinFont, WinStrXY, _bcd_math, NG_setup_graph_fun, NG_cleanup_graph_fun, _du32u32, ROM Call 0x46E
Used by: GD_Contour, ROM Call 0x4CA


GR3_freeDB

GR3_freeDB Function (ROM Call 0x1FD)
unknown.h

unknown_retval GR3_freeDB ();

This identifier has not been documented yet. Please help us out.

Uses: HeapFree, HeapFreeIndir
Used by: SetGraphMode, GR3_paint3d


GR3_handleEvent

GR3_handleEvent Function (ROM Call 0x1FE)
unknown.h

unknown_retval GR3_handleEvent ();

This identifier has not been documented yet. Please help us out.

Uses: TIOS_abs, ER_catch, ER_success, ER_throwVar, GR3_paint3d, RestoreScrState, SaveScrState, gr_active, memcpy, ST_busy, OSClearBreak, acos, atan2, fmod, fpisanint, is_transfinite, sincos, WinAttr, WinBackupToScr, WinCharXY, WinClr, WinFillTriangle, WinFont, WinLine, WinLineTo, WinMoveTo, _bcd_math


GraphActivate

GraphActivate Function (ROM Call 0x1FC)
unknown.h

short GraphActivate (short);

This identifier has not been documented yet. Please help us out.

Uses: EV_paintWindows, EV_sendEvent, EV_startApp, gr_active, NeedStack
Used by: GZ_SetFactors, cmd_andpic, cmd_circle, cmd_cyclepic, cmd_dispg, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_graph, cmd_line, cmd_linehorz, cmd_linetan, cmd_linevert, cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pttext, cmd_pxlchg, cmd_pxlcircle, cmd_pxlhorz, cmd_pxlline, cmd_pxloff, cmd_pxlon, cmd_pxltext, cmd_pxlvert, cmd_rclpic, cmd_rplcpic, cmd_shade, cmd_slpline, cmd_stopic, cmd_xorpic, ROM Call 0x455, ROM Call 0x4CA


GraphOrTableCmd

GraphOrTableCmd Function (ROM Call 0x1E4)
unknown.h

void GraphOrTableCmd (ESI expr, short liberal);

This identifier has not been documented yet. Please help us out.

Uses: gr_openFolder, grFuncName, push_assignment, ER_catch, ER_success, ER_throwVar, check_estack_size, next_expression_index, push_expression, push_quantum, top_estack, gr_active, memcmp, strcmp, CheckReservedName, SymDel, SymFindPtr, TokToStrN, ROM Call 0x480
Used by: gr_ck_solvergraph, cmd_graph, cmd_table


GrAxes

GrAxes Function (ROM Call 0x1B7)
unknown.h

void GrAxes (short, GR_WIN_VARS *);

This identifier has not been documented yet. Please help us out.

Uses: TIOS_abs, XCvtFtoP, XCvtPtoF, ceil, fabs, round12, WinLineNC, WinPixSet, _bcd_math
Used by: Regraph


GrClipLine

GrClipLine Function (ROM Call 0x1C0)
unknown.h

unsigned char GrClipLine (float, float, float, float, float *, float *, float *, float *, GR_WIN_VARS *);

This identifier has not been documented yet. Please help us out.

Uses: fabs, round12, _bcd_math
Used by: FuncLineFlt, GrLineFlt, Regraph, cmd_line


grFuncName

grFuncName Function (ROM Call 0x1C7)
unknown.h

unknown_retval grFuncName ();

This identifier has not been documented yet. Please help us out.

Uses: CharNumber, gr_active
Used by: dv_create_graph_titles, FindGrFunc, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_ck_solvergraph, GraphOrTableCmd, NG_setup_graph_fun, setup_more_graph_fun, cmd_blddata, gdb_len, gdb_recall, gdb_store


GrLineFlt

GrLineFlt Function (ROM Call 0x1BE)
unknown.h

void GrLineFlt (float, float, float, float, GR_WIN_VARS *, short pixcur[], unsigned char, unsigned char);

This identifier has not been documented yet. Please help us out.

Uses: GrClipLine, GT_WinCursor, XCvtFtoP, YCvtFtoP, gr_active, gr_flags, is_transfinite, round12, MakeWinRect, WinAttr, WinFillLines2, WinLineNC, WinPixSet, _bcd_math
Used by: dv_create_graph_titles, GM_TanLine, GS_PlotAll, GT_Trace, Regraph, cmd_circle, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_linetan, cmd_shade, cmd_slpline


GS_PlotAll

GS_PlotAll Function (ROM Call 0x202)
unknown.h

unknown_retval GS_PlotAll ();

This identifier has not been documented yet. Please help us out.

Uses: GetStatValue, GrLineFlt, PlotGet, QPlotActive, XCvtFtoP, YCvtFtoP, gr_active, gr_flags, kbhit, ngetchx, pushkey, ST_busy, idle, off, OSTimerExpired, OSTimerRestart, WinBitmapPut, ROM Call 0x46E
Used by: Regraph


GS_PlotTrace

GS_PlotTrace Function (ROM Call 0x201)
unknown.h

unknown_retval GS_PlotTrace ();

This identifier has not been documented yet. Please help us out.

Uses: ForceFloat, GetStatValue, gr_active, GT_DspTraceCoords, PlotGet
Used by: GT_Trace


GT_BackupToScr

GT_BackupToScr Function (ROM Call 0x20C)
unknown.h

unknown_retval GT_BackupToScr ();

This identifier has not been documented yet. Please help us out.

Uses: gr_DispLabels, GT_DspTraceCoords, GT_PrintCursor, GXcoord, GYcoord, DrawLine, gr_active, WinAttr, WinBackupToScr, WinDupStat, WinStrXY
Used by: GR_Pan, GT_CursorKey, GT_Trace, GZ_Previous, GZ_Store, Regraph


GT_CalcDepVals

GT_CalcDepVals Function (ROM Call 0x20D)
unknown.h

unknown_retval GT_CalcDepVals ();

This identifier has not been documented yet. Please help us out.

Uses: cpt_gr_fun, cpt_gr_param, cpt_gr_polar, estack_to_float, FindFunc, gr_del_locals, NG_setup_graph_fun, NG_cleanup_graph_fun, run_one_seq, setup_more_graph_fun, unlock_more_graph_fun, ER_catch, ER_success, ER_throwVar, top_estack, gr_active
Used by: GM_Integrate, GM_Shade, GT_Trace


GT_CenterGraphCursor

GT_CenterGraphCursor Function (ROM Call 0x20E)
unknown.h

unknown_retval GT_CenterGraphCursor ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active
Used by: GZ_InOut, GZ_Integer, GZ_Square, GZ_Center


GT_CursorKey

GT_CursorKey Function (ROM Call 0x20F)
unknown.h

unknown_retval GT_CursorKey ();

This identifier has not been documented yet. Please help us out.

Uses: GT_BackupToScr, GT_KeyIn, gr_active, WinDupStat, WinMoveTo
Used by: GM_Shade, GT_FreeTrace, GD_Circle, GD_Eraser, GD_HVLine, GD_Line, GD_Pen, GD_Select, GD_Text, GZ_Box


GT_DE_Init_Conds

GT_DE_Init_Conds Function (ROM Call 0x22A)
unknown.h

unknown_retval GT_DE_Init_Conds ();

This identifier has not been documented yet. Please help us out.

Uses: CountGrFunc, FindGrFunc, GT_FreeTrace, GT_Regraph_if_neccy, InitDEAxesRng, Regraph, TIOS_abs, Dialog, ER_catch, ER_success, ER_throwVar, gr_active, ST_helpMsg, XR_stringPtr


GT_DspFreeTraceCoords

GT_DspFreeTraceCoords Function (ROM Call 0x210)
unknown.h

unknown_retval GT_DspFreeTraceCoords ();

This identifier has not been documented yet. Please help us out.

Uses: GT_DspTraceCoords, XCvtPtoF, YCvtPtoF, gr_active
Used by: GT_FreeTrace, GD_Circle, GD_HVLine, GD_Line, GD_Pen, GZ_Box


GT_DspMsg

GT_DspMsg Function (ROM Call 0x212)
unknown.h

void GT_DspMsg (const char* msg, short pos);

Displays msg according to pos.

This function displays msg at a place determined by pos. It seems that the rules determining which place pos corresponds to are somewhat random.

Uses: GXcoord, GYcoord, gr_active, WinAttr, WinDupStat, WinStrXY
Used by: GM_Shade, GT_FreeTrace, GT_Trace, GD_Circle, GD_Line, GD_Select, GZ_Box


GT_DspTraceCoords

GT_DspTraceCoords Function (ROM Call 0x211)
unknown.h

unknown_retval GT_DspTraceCoords ();

This identifier has not been documented yet. Please help us out.

Uses: ck_valid_float, gr_de_axes_lbl, GT_PrintCursor, GXcoord, GYcoord, TIOS_abs, ER_catch, ER_success, gr_active, is_transfinite, WinAttr, WinDupStat, WinStrXY, _bcd_math
Used by: GS_PlotTrace, GT_BackupToScr, GT_DspFreeTraceCoords, GT_Trace, YCvtFtoP


GT_Error

GT_Error Function (ROM Call 0x213)
unknown.h

unknown_retval GT_Error ();

This identifier has not been documented yet. Please help us out.

Uses: clear_error_context, ERD_dialog


GT_Format

GT_Format Function (ROM Call 0x214)
unknown.h

unknown_retval GT_Format ();

This identifier has not been documented yet. Please help us out.

Uses: GT_Set_Graph_Format, Dialog, gr_active


GT_FreeTrace

GT_FreeTrace Function (ROM Call 0x215)
unknown.h

unknown_retval GT_FreeTrace ();

This identifier has not been documented yet. Please help us out.

Uses: GT_CursorKey, GT_DspFreeTraceCoords, GT_DspMsg, GT_IncXY, GT_Trace, GT_ValidGraphRanges, GT_WinBound, GT_WinCursor, XCvtPtoF, YCvtPtoF, EV_defaultHandler, gr_active, pushkey, ST_eraseHelp, XR_stringPtr, WinDupStat, WinGetCursor, WinMoveCursor
Used by: GT_DE_Init_Conds, GZ_InOut, GZ_Integer, GD_Circle, GD_Line, GZ_Box


GT_IncXY

GT_IncXY Function (ROM Call 0x216)
unknown.h

unknown_retval GT_IncXY ();

This identifier has not been documented yet. Please help us out.

Uses: spike_optionD, XCvtPtoF, YCvtPtoF, push_Float, push_quantum, push_quantum_pair, gr_active, HomePushEStack
Used by: GT_FreeTrace, GD_Circle, GD_Eraser, GD_HVLine, GD_Line, GD_Pen, GD_Select, GD_Text, GZ_Box


GT_KeyIn

GT_KeyIn Function (ROM Call 0x217)
unknown.h

unknown_retval GT_KeyIn ();

This identifier has not been documented yet. Please help us out.

Uses: GT_WinCursor, EV_defaultHandler, EV_getc, gr_active, pushkey, CU_restore, CU_start, CU_stop, QModeKey, WinAttr, ROM Call 0x4FB
Used by: GT_CursorKey, GT_Trace


GT_Open

GT_Open Function (ROM Call 0x21B)
unknown.h

unknown_retval GT_Open ();

This identifier has not been documented yet. Please help us out.

Uses: EV_currentApp, VarOptList, VarOpen, gdb_recall, gr_active, DerefSym, WinBitmapPut


GT_PrintCursor

GT_PrintCursor Function (ROM Call 0x229)
unknown.h

unknown_retval GT_PrintCursor ();

This identifier has not been documented yet. Please help us out.

Uses: HeapFree, Parse1DExpr, push_Float, top_estack
Used by: GT_BackupToScr, GT_DspTraceCoords, GT_Trace, YCvtFtoP


GT_QFloatCursorsInRange

GT_QFloatCursorsInRange Function (ROM Call 0x218)
unknown.h

unknown_retval GT_QFloatCursorsInRange ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active, _bcd_math


GT_Regraph_if_neccy

GT_Regraph_if_neccy Function (ROM Call 0x21A)
unknown.h

void GT_Regraph_if_neccy (void);

This identifier has not been documented yet. Please help us out.

Uses: GT_SelFunc, Regraph, gr_active, _bcd_math
Used by: GT_DE_Init_Conds, GT_Regraph, GT_Trace, GZ_Store


GT_Regraph

GT_Regraph Function (ROM Call 0x219)
unknown.h

void GT_Regraph (void);

This identifier has not been documented yet. Please help us out.

Uses: GT_Regraph_if_neccy, gr_active
Used by: GZ_Decimal, GZ_Fit, GZ_InOut, GZ_Integer, GZ_Previous, GZ_Recall, GZ_Square, GZ_Standard, GZ_Stat, GZ_Trig, GZ_Box, GZ_Center


GT_SaveAs

GT_SaveAs Function (ROM Call 0x21C)
unknown.h

unknown_retval GT_SaveAs ();

This identifier has not been documented yet. Please help us out.

Uses: EV_currentApp, VarOptList, HeapAlloc, HeapFree, VarSaveAs, gdb_len, gdb_store, gr_active, DerefSym, SymDel, MakeWinRect, WinBitmapGet, WinBitmapSize, WinDupStat
Used by: GD_Select


GT_SelFunc

GT_SelFunc Function (ROM Call 0x21D)
unknown.h

unknown_retval GT_SelFunc ();

This identifier has not been documented yet. Please help us out.

Uses: CountGrFunc, FindFunc, gr_initCondName, PlotGet, QPlotActive, TIOS_abs, gr_active, SymFindMain, _bcd_math
Used by: GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_Shade, GM_TanLine, GM_Value, GT_Regraph_if_neccy, GT_Trace


GT_Set_Graph_Format

GT_Set_Graph_Format Function (ROM Call 0x228)
unknown.h

unknown_retval GT_Set_Graph_Format ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active
Used by: GT_Format


GT_SetCursorXY

GT_SetCursorXY Function (ROM Call 0x21F)
unknown.h

unknown_retval GT_SetCursorXY ();

This identifier has not been documented yet. Please help us out.

Uses: XCvtFtoP, YCvtFtoP, gr_active, _bcd_math
Used by: GT_Trace


GT_SetGraphRange

GT_SetGraphRange Function (ROM Call 0x21E)
unknown.h

unknown_retval GT_SetGraphRange ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active, XCvtPtoF, YCvtPtoF
Used by: GZ_Box


GT_ShowMarkers

GT_ShowMarkers Function (ROM Call 0x220)
unknown.h

unknown_retval GT_ShowMarkers ();

This identifier has not been documented yet. Please help us out.

Uses: GT_WinCursor, gr_active, WinAttr, WinDupStat, WinLineTo, WinMoveTo
Used by: GM_DistArc, GT_Trace


GT_Trace

GT_Trace Function (ROM Call 0x221)
unknown.h

short GT_Trace (unsigned short PromptId, float * Retval, unsigned short Flags);

This identifier has not been documented yet. Please help us out.

Uses: ck_valid_float, cleanup_de_mem, cleanup_seq_mem, clear_error_context, CountGrFunc, CptLastIndepDE, CTypeTable, de_initRes, de_loop, FindFunc, FirstSeqPlot, gr_CptIndepInc, gr_de_axes_lbl, gr_de_value, gr_del_vars_in_folder, gr_initCondName, GR_Pan, gr_seq_value, gr_xres_pixel, GrLineFlt, GS_PlotTrace, GT_BackupToScr, GT_CalcDepVals, GT_DspMsg, GT_DspTraceCoords, GT_KeyIn, GT_PrintCursor, GT_Regraph_if_neccy, GT_SelFunc, GT_SetCursorXY, GT_ShowMarkers, GT_WinCursor, GXcoord, GYcoord, InitDEAxesRng, InitDEMem, InitTimeSeq, PlotGet, QActivePlots, QPlotActive, seqWebInit, spike_optionD, time_loop, TIOS_abs, XCvtFtoP, XCvtPtoF, YCvtFtoP, HeapAllocThrow, HeapFreeIndir, ER_catch, ER_success, ER_throwVar, ERD_dialog, push_Float, push_quantum, push_quantum_pair, EV_captureEvents, EV_defaultHandler, EV_eventLoop, GR3_xyToWindow, gr_active, gr_flags, HomePushEStack, GKeyIn, OSFastArrows, pushkey, memset, ST_eraseHelp, ST_helpMsg, sprintf, idle, OSClearBreak, OSFreeTimer, OSRegisterTimer, OSTimerExpired, XR_stringPtr, TE_close, TE_focus, TE_openFixed, TE_select, floor, is_nan, is_transfinite, round12, round14, SymFindMain, WinAttr, WinDupStat, WinStrXY, _bcd_math, ROM Call 0x46F
Used by: GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_Shade, GM_TanLine, GM_Value, GT_FreeTrace, GZ_InOut, GD_Contour

See also: GT_Regraph_if_neccy


GT_ValidGraphRanges

GT_ValidGraphRanges Function (ROM Call 0x222)
unknown.h

unknown_retval GT_ValidGraphRanges ();

This identifier has not been documented yet. Please help us out.

Uses: CptDeltax, CptDeltay, gr_active
Used by: GT_FreeTrace, GD_HVLine, GD_Pen


GT_WinBound

GT_WinBound Function (ROM Call 0x223)
unknown.h

unknown_retval GT_WinBound ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active, WinHeight, WinWidth
Used by: GT_FreeTrace, GD_Circle, GD_Eraser, GD_HVLine, GD_Line, GD_Pen, GD_Select, GD_Text, GZ_Box


GT_WinCursor

GT_WinCursor Function (ROM Call 0x224)
unknown.h

unknown_retval GT_WinCursor ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active, WinBitmapPut
Used by: FuncLineFlt, GrLineFlt, GT_FreeTrace, GT_KeyIn, GT_ShowMarkers, GT_Trace, Regraph, GD_Circle, GD_HVLine, GD_Line, GD_Pen, GD_Select, GD_Text, GZ_Box


GXcoord

GXcoord Function (ROM Call 0x226)
unknown.h

unknown_retval GXcoord ();

This identifier has not been documented yet. Please help us out.

Used by: gr_DispLabels, GT_BackupToScr, GT_DspMsg, GT_DspTraceCoords, GT_Trace, YCvtFtoP


GYcoord

GYcoord Function (ROM Call 0x225)
unknown.h

unknown_retval GYcoord ();

This identifier has not been documented yet. Please help us out.

Used by: gr_DispLabels, GT_BackupToScr, GT_DspMsg, GT_DspTraceCoords, GT_Trace, YCvtFtoP


GZ_Decimal

GZ_Decimal Function (ROM Call 0x22D)
unknown.h

unknown_retval GZ_Decimal ();

This identifier has not been documented yet. Please help us out.

Uses: GT_Regraph, GZ_Center, gr_active, round12_err, _bcd_math


GZ_Fit

GZ_Fit Function (ROM Call 0x22E)
unknown.h

unknown_retval GZ_Fit ();

This identifier has not been documented yet. Please help us out.

Uses: GT_Regraph, GZ_Square, Regraph, ER_catch, ER_success, ER_throwVar, GZ_Center, gr_active, is_transfinite, round12_err


GZ_InOut

GZ_InOut Function (ROM Call 0x22F)
unknown.h

unknown_retval GZ_InOut ();

This identifier has not been documented yet. Please help us out.

Uses: GT_CenterGraphCursor, GT_FreeTrace, GT_Regraph, GT_Trace, GZ_Center, gr_active, ST_helpMsg, XR_stringPtr, round12_err, _bcd_math


GZ_Integer

GZ_Integer Function (ROM Call 0x230)
unknown.h

unknown_retval GZ_Integer ();

This identifier has not been documented yet. Please help us out.

Uses: GT_CenterGraphCursor, GT_FreeTrace, GT_Regraph, XCvtPtoF, YCvtPtoF, GZ_Center, gr_active, ST_helpMsg, XR_stringPtr, floor, round12_err, _bcd_math


GZ_Previous

GZ_Previous Function (ROM Call 0x231)
unknown.h

unknown_retval GZ_Previous ();

This identifier has not been documented yet. Please help us out.

Uses: GT_BackupToScr, GT_Regraph, GZ_Center, gr_active


GZ_Recall

GZ_Recall Function (ROM Call 0x232)
unknown.h

unknown_retval GZ_Recall ();

This identifier has not been documented yet. Please help us out.

Uses: GT_Regraph, GZ_Center, gr_active


GZ_SetFactors

GZ_SetFactors Function (ROM Call 0x233)
unknown.h

unknown_retval GZ_SetFactors ();

This identifier has not been documented yet. Please help us out.

Uses: GraphActivate, Dialog, memset, sprintf, _bcd_math, ROM Call 0x46F


GZ_Square

GZ_Square Function (ROM Call 0x234)
unknown.h

unknown_retval GZ_Square ();

This identifier has not been documented yet. Please help us out.

Uses: GT_CenterGraphCursor, GT_Regraph, GZ_Center, CptDeltax, CptDeltay, gr_active, round12_err, _bcd_math
Used by: GZ_Fit


GZ_Standard

GZ_Standard Function (ROM Call 0x235)
unknown.h

unknown_retval GZ_Standard ();

This identifier has not been documented yet. Please help us out.

Uses: GT_Regraph, GZ_Center, gr_active


GZ_Stat

GZ_Stat Function (ROM Call 0x236)
unknown.h

unknown_retval GZ_Stat ();

This identifier has not been documented yet. Please help us out.

Uses: GetStatValue, GT_Regraph, PlotGet, QPlotActive, GZ_Center, gr_active, gr_flags, kbhit, ngetchx, pushkey, ST_busy, idle, off, OSTimerExpired, OSTimerRestart, fabs, round12, _bcd_math, ROM Call 0x46E


GZ_Store

GZ_Store Function (ROM Call 0x237)
unknown.h

unknown_retval GZ_Store ();

This identifier has not been documented yet. Please help us out.

Uses: GT_BackupToScr, GT_Regraph_if_neccy, GZ_Center, gr_active


GZ_Trig

GZ_Trig Function (ROM Call 0x238)
unknown.h

void GZ_Trig (void);

This identifier has not been documented yet. Please help us out.

Uses: GT_Regraph, GZ_Center, gr_active, round12_err, round14, _bcd_math


has_different_variable

has_different_variable Function (ROM Call 0x5A0)
AMS 2.02 or higher unknown.h

short has_different_variable (ESI, ESI, short);

This identifier has not been documented yet. Please help us out.

Uses: is_variable, primary_tag_list, are_expressions_identical, next_expression_index, push_expression, push_quantum, top_estack
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


has_unit_base

has_unit_base Function (ROM Call 0x3AF)
AMS 1.01 or higher unknown.h

short has_unit_base (ESI);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, lead_base_index, next_expression_index, remaining_factors_index
Used by: did_push_divide_units, push_auto_units_conversion, EV_defaultHandler, HomeExecute


index_after_match_endtag

index_after_match_endtag Function (ROM Call 0x2B1)
AMS 1.01 or higher unknown.h

ESI index_after_match_endtag (ESI esi, unsigned char endtag);

This identifier has not been documented yet. Please help us out.

Uses: next_expression_index
Used by: fix_loop_displacements, store_func_def, cmd_cycle, cmd_else, cmd_exit, cmd_for, cmd_ifthen, cmd_try, cmd_while, next_expression_index


index_if_pushed_binomial_info

index_if_pushed_binomial_info Function (ROM Call 0x5A1)
AMS 2.02 or higher unknown.h

ESI index_if_pushed_binomial_info (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, Float1Index, Integer0Index, Integer1Index, IntegerMinus1Index, is_polynomial_in_var_or_kern, is_whole_number, is1, primary_tag_list, push_dependent_factors, push_independent_factors, push_standardize, push_gcd_numbers, push_lim, push_difference, push_substitute_simplify, are_expressions_identical, compare_expressions, delete_between, deleted_between, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_term_index, next_expression_index, numeric_factor_index, push_expression, remaining_factors_index, top_estack, _bcd_math, ROM Call 0x4DF
Used by: did_push_anti_deriv


index_if_pushed_qquad_info

index_if_pushed_qquad_info Function (ROM Call 0x5A2)
AMS 2.02 or higher unknown.h

ESI index_if_pushed_qquad_info (ESI, ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, ER_catch, ER_success, ER_throwVar, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_narrowly_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_internal_simplify, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1, ROM Call 0x5E4
Used by: did_push_anti_deriv, push_desolve, push_factor


index_reductum_with_tag_base

index_reductum_with_tag_base Function (ROM Call 0x59F)
AMS 2.02 or higher unknown.h

ESI index_reductum_with_tag_base (ESI, ESQ, short);

This identifier has not been documented yet. Please help us out.

Uses: is1, primary_tag_list, lead_base_index, lead_exponent_index, lead_term_index, reductum_index, remaining_factors_index
Used by: replace_top_with_post_simplified, push_product, push_sum


index_rmng_factor

index_rmng_factor Function (ROM Call 0x565)
AMS 2.02 or higher unknown.h

ESI index_rmng_factor (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, are_expressions_identical, lead_factor_index, remaining_factors_index
Used by: get_ub, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


index_rmng_fctrs_start_base_tag

index_rmng_fctrs_start_base_tag Function (ROM Call 0x563)
AMS 2.02 or higher unknown.h

ESI index_rmng_fctrs_start_base_tag (ESI, ESQ);

This identifier has not been documented yet. Please help us out.

Uses: is1, lead_base_index, remaining_factors_index
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product


index_rmng_fctrs_start_base

index_rmng_fctrs_start_base Function (ROM Call 0x564)
AMS 2.02 or higher unknown.h

ESI index_rmng_fctrs_start_base (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, are_expressions_identical, lead_base_index, remaining_factors_index
Used by: replace_top_with_post_simplified, did_push_anti_deriv, push_extended_prod, push_summation, push_product, push_sum


index_rmng_fctrs_start_fctr_tag

index_rmng_fctrs_start_fctr_tag Function (ROM Call 0x562)
AMS 2.02 or higher unknown.h

ESI index_rmng_fctrs_start_fctr_tag (ESI, ESQ);

This identifier has not been documented yet. Please help us out.

Uses: is1, lead_factor_index, remaining_factors_index
Used by: get_ub, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_ln, push_max, push_min, push_nsolve, push_sin2, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum


init_unit_system

init_unit_system Function (ROM Call 0x3B0)
AMS 1.01 or higher unknown.h

unknown_retval init_unit_system ();

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable, next_expression_index, cmpstri, XR_stringPtr, ROM Call 0x41C, ROM Call 0x41D, ROM Call 0x41E
Used by: setup_unit_system, MO_digestOptions


InitDEAxesRng

InitDEAxesRng Function (ROM Call 0x1E9)
unknown.h

unknown_retval InitDEAxesRng ();

This identifier has not been documented yet. Please help us out.

Uses: CptLastIndepDE, gr_active, gr_flags, fabs, round12, _bcd_math
Used by: GT_DE_Init_Conds, GT_Trace, Regraph, cmd_blddata


InitDEMem

InitDEMem Function (ROM Call 0x1EA)
unknown.h

unknown_retval InitDEMem ();

This identifier has not been documented yet. Please help us out.

Uses: de_initRes, EV_currentApp, FindGrFunc, Float0Index, gen_version, gr_initCondName, gr_openFolder, NG_setup_graph_fun, setup_more_graph_fun, TIOS_abs, HeapAllocThrow, HeapDeref, next_expression_index, push_END_TAG, push_expression, push_Float, push_LIST_TAG, top_estack, gr_active, gr_flags, memcpy, AddSymToFolder, DerefSym, TempFolderName, VarStore
Used by: gr_execute_de, GT_Trace, Regraph, cmd_blddata


InitTimeSeq

InitTimeSeq Function (ROM Call 0x1D9)
unknown.h

unknown_retval InitTimeSeq ();

This identifier has not been documented yet. Please help us out.

Uses: EV_currentApp, FindGrFunc, NG_setup_graph_fun, setup_more_graph_fun, HeapDeref, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, NG_approxESI, push_END_TAG, push_Float, push_quantum, top_estack, gr_active, memcpy, AddSymToFolder, DerefSym, FolderDelAllTemp, SymFindMain, TempFolderName, VarStore, _bcd_math
Used by: gr_execute_seq, GT_Trace, Regraph, cmd_blddata


is_cFloat_agg

is_cFloat_agg Function (ROM Call 0x465)
AMS 2.00 or higher unknown.h

short is_cFloat_agg (ESI);

This identifier has not been documented yet. Please help us out.

Uses: is_complex_Float, all_tail, next_expression_index
Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_sinreg, cmd_twovar, push_eigvc, push_eigvl


is_complex_Float

is_complex_Float Function (ROM Call 0x48B)
AMS 2.00 or higher unknown.h

short is_complex_Float (CESI);

This identifier has not been documented yet. Please help us out.

Used by: divide_top, get_ub, is_cFloat_agg, replace_top2_with_ratio, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_ratio


is_equivalent_to

is_equivalent_to Function (ROM Call 0x578)
AMS 2.02 or higher unknown.h

short is_equivalent_to (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, push_difference, are_expressions_identical, is_complex0, next_expression_index, top_estack
Used by: get_ub, push_gcd_then_cofactors, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_atan, push_comb, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_sum


is_executable

is_executable Function (ROM Call 0x25A)
unknown.h

short is_executable (CESI);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list
Used by: LIO_Receive


is_neg_lead_numr_coef_re_part

is_neg_lead_numr_coef_re_part Function (ROM Call 0x56D)
AMS 2.02 or higher unknown.h

short is_neg_lead_numr_coef_re_part (ESI);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, next_expression_index, re_index, signum_Float
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_asin, push_asinh, push_atan, push_atanh, push_cosh, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_integer_part, push_lim, push_max, push_min, push_nsolve, push_sin2, push_sinh, push_solve, push_tan, push_tanh, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product


is_real

is_real Function (ROM Call 0x5A9)
AMS 2.02 or higher unknown.h

short is_real (ESI);

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, get_lb, get_ub, Integer1Index, IntegerMinus1Index, is_nonnegative, is_variable, is_whole_number, primary_tag_list, push_approx, push_difference, likely_approx_to_number, next_expression_index, top_estack, _bcd_math
Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, integer_non_unknown, is_nonnegative, is_positive, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_simplify, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_comdenom, push_conj, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_mod, push_nsolve, push_numerator, push_phase, push_re, push_sign, push_sin2, push_sinh, push_solve, push_summation, push_tanh, push_zeros, did_push_to_polar, push_dot_exponentiate, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, push_internal_simplify, ROM Call 0x4E6, ROM Call 0x606


is_term_improper

is_term_improper Function (ROM Call 0x556)
AMS 2.02 or higher unknown.h

short is_term_improper (ESI);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, push_product, push_sum, are_expressions_identical, delete_between, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, main_gen_var_index, remaining_factors_index, top_estack, ROM Call 0x4DF, ROM Call 0x4E0, push_exact0
Used by: push_expand, push_sum


is_undefined

is_undefined Function (ROM Call 0x5B7)
AMS 2.04 or higher unknown.h

short is_undefined (ESI);

This identifier has not been documented yet. Please help us out.

Uses: next_expression_index
Used by: did_push_approx_inflection_point, get_ub, did_push_anti_deriv, did_push_series, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


is_units_term

is_units_term Function (ROM Call 0x3B1)
AMS 1.01 or higher unknown.h

short is_units_term (CESI);

This identifier has not been documented yet. Please help us out.

Uses: factor_base_index, next_expression_index
Used by: push_trig, replace_top_with_post_simplified, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comb, push_exp, push_ln, push_sin2, push_factorial, push_percent, push_product


IsClockOn

IsClockOn Function (ROM Call 0x5F7)
AMS 2.07 or higher unknown.h

unsigned short IsClockOn (void);

This identifier has not been documented yet. Please help us out.

Used by: EV_quit, EV_defaultHandler, DateAndTime_SetDlg


lead_conjunct_factor_index

lead_conjunct_factor_index Function (ROM Call 0x580)
AMS 2.02 or higher unknown.h

ESI lead_conjunct_factor_index (ESI);

This identifier has not been documented yet. Please help us out.

Used by: get_lb, get_ub, is_negative, is_never0, is_nonnegative, is_nonpositive, is_positive, push_but_conjunct_factor, push_user_func, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_and, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_or, push_substitute_using_such_that, ST_eraseHelp, ST_modKey, ROM Call 0x4E6


lead_disjunct_term_index

lead_disjunct_term_index Function (ROM Call 0x57E)
AMS 2.02 or higher unknown.h

ESI lead_disjunct_term_index (ESI);

This identifier has not been documented yet. Please help us out.

Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_or, ROM Call 0x4E6


linear_degree

linear_degree Function (ROM Call 0x571)
AMS 2.02 or higher unknown.h

short linear_degree (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, are_expressions_identical, is_narrowly_independent_of, next_expression_index
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


LoadSymFromFindHandle

LoadSymFromFindHandle Function (ROM Call 0x281)
unknown.h

void LoadSymFromFindHandle (void);

This identifier has not been documented yet. Please help us out.

Used by: EV_eventLoop, LIO_Receive, OSLinkCmd


next_token

next_token Function (ROM Call 0x3C7)
AMS 1.01 or higher unknown.h

short next_token (short errorthrow);

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable, nonblank, ER_throwVar, XR_stringPtr
Used by: EQU_getNameInfo, push_parse_prgm_or_func_text, push_indir_name, push_parse_text


next_var_or_kernel_index

next_var_or_kernel_index Function (ROM Call 0x56E)
AMS 2.02 or higher unknown.h

ESI next_var_or_kernel_index (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: compare_expressions, next_expression_index
Used by: get_ub, push_var_kern_tail, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


NG_cleanup_graph_fun

NG_cleanup_graph_fun Function (ROM Call 0x262)
unknown.h

unknown_retval NG_cleanup_graph_fun ();

This identifier has not been documented yet. Please help us out.

Uses: HeapUnlock, HToESI, FolderDelTemp
Used by: cleanup_de_mem, cleanup_seq_mem, GR3_addContours, GT_CalcDepVals, Regraph, cmd_blddata, GR3_paint3d, GR3_xyToWindow


NG_setup_graph_fun

NG_setup_graph_fun Function (ROM Call 0x261)
unknown.h

unknown_retval NG_setup_graph_fun ();

This identifier has not been documented yet. Please help us out.

Uses: grFuncName, tokenize_if_TI_92_or_text, HeapAllocThrow, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, gr_active, AddSymToFolder, DerefSym, FolderAddTemp, FolderDelTemp
Used by: GR3_addContours, GT_CalcDepVals, InitDEMem, InitTimeSeq, Regraph, cmd_blddata, GR3_paint3d, GR3_xyToWindow


nonblank

nonblank Function (ROM Call 0x3C8)
AMS 1.01 or higher unknown.h

void nonblank (void);

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable
Used by: next_token, push_parse_prgm_or_func_text, push_parse_text


OO_appGetPublicStorage

OO_appGetPublicStorage Function (ROM Call 0x425)
AMS 2.00 or higher unknown.h

unsigned long OO_appGetPublicStorage (void);

This identifier has not been documented yet. Please help us out.

Uses: EV_runningApp


OO_appIsMarkedDelete

OO_appIsMarkedDelete Function (ROM Call 0x426)
AMS 2.00 or higher unknown.h

short OO_appIsMarkedDelete (short TaskID);

This identifier has not been documented yet. Please help us out.


OO_appMarkDelete

OO_appMarkDelete Function (ROM Call 0x427)
AMS 2.00 or higher unknown.h

void OO_appMarkDelete (short TaskID);

This identifier has not been documented yet. Please help us out.

Used by: ROM Call 0x4FD


OO_AppNameToACB

OO_AppNameToACB Function (ROM Call 0x406)
AMS 2.00 or higher unknown.h

short OO_AppNameToACB (unsigned char const *, short);

This identifier has not been documented yet. Please help us out.

Uses: OO_CondGetAttr, OO_firstACB, OO_GetAppAttr, OO_NextACB, OO_SuperFrame, strcmp, stricmp
Used by: MO_currentOptions


OO_appSetPublicStorage

OO_appSetPublicStorage Function (ROM Call 0x429)
AMS 2.00 or higher unknown.h

void OO_appSetPublicStorage (unsigned long);

This identifier has not been documented yet. Please help us out.

Uses: EV_runningApp


OO_CondGetAttr

OO_CondGetAttr Function (ROM Call 0x3FA)
AMS 2.00 or higher unknown.h

short OO_CondGetAttr (pFrame, unsigned long, void **);

This identifier has not been documented yet. Please help us out.

Uses: OO_Deref, OO_SuperFrame
Used by: OO_AppNameToACB, OO_GetAttr, OO_HasAttr, find_error_message, XR_stringPtr


OO_Deref

OO_Deref Function (ROM Call 0x3FB)
AMS 2.00 or higher unknown.h

void *OO_Deref (pFrame);

This identifier has not been documented yet. Please help us out.

Used by: OO_CondGetAttr, OO_Destroy, OO_DestroyAll, OO_InstallAppHook, OO_InstallSystemHook, OO_New, OO_SetAppAttr, OO_SetAttr, OO_UninstallAppHook, OO_UninstallSystemHook


OO_Destroy

OO_Destroy Function (ROM Call 0x423)
AMS 2.00 or higher unknown.h

pFrame OO_Destroy (pFrame);

This identifier has not been documented yet. Please help us out.

Uses: OO_Deref, HeapFree
Used by: OO_DestroyAll, OO_UninstallAppHook, OO_UninstallSystemHook


OO_DestroyAll

OO_DestroyAll Function (ROM Call 0x4F5)
AMS 2.00 or higher unknown.h

pFrame OO_DestroyAll (pFrame);

This identifier has not been documented yet. Please help us out.

Uses: OO_Deref, OO_Destroy
Used by: ROM Call 0x424


OO_GetAppAttr

OO_GetAppAttr Function (ROM Call 0x3FC)
AMS 2.00 or higher unknown.h

void *OO_GetAppAttr (short TaskID, unsigned long);

This identifier has not been documented yet. Please help us out.

Uses: OO_GetAttr
Used by: EV_quit, OO_AppNameToACB, push_user_func, sf_width, tokenize_if_TI_92_or_text, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_twovar, EV_defaultHandler, handleVarLinkKey, MO_digestOptions, MO_modeDialog, DrawChar, DrawClipChar, DrawStr, LIO_Receive, VarStore, ROM Call 0x131, ROM Call 0x3CD, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x428, ROM Call 0x486, ROM Call 0x4F6, ROM Call 0x4FE


OO_GetAttr

OO_GetAttr Function (ROM Call 0x3FD)
AMS 2.00 or higher unknown.h

void *OO_GetAttr (pFrame, unsigned long);

This identifier has not been documented yet. Please help us out.

Uses: OO_CondGetAttr, OO_SuperFrame, sprintf, strncpy, ROM Call 0x505
Used by: OO_GetAppAttr, EV_sendEventSide


OO_HasAttr

OO_HasAttr Function (ROM Call 0x3FE)
AMS 2.00 or higher unknown.h

short OO_HasAttr (pFrame, unsigned long);

This identifier has not been documented yet. Please help us out.

Uses: OO_CondGetAttr


OO_InstallAppHook

OO_InstallAppHook Function (ROM Call 0x490)
AMS 2.00 or higher unknown.h

short OO_InstallAppHook (short TaskID, pFrame, pFrame *);

This identifier has not been documented yet. Please help us out.

Uses: OO_Deref, OO_New
Used by: OO_InstallAppHookByName


OO_InstallAppHookByName

OO_InstallAppHookByName Function (ROM Call 0x492)
AMS 2.00 or higher unknown.h

short OO_InstallAppHookByName (unsigned char const *, pFrame, pFrame *);

This identifier has not been documented yet. Please help us out.

Uses: OO_firstACB, OO_InstallAppHook, TIOS_EV_getAppID, ROM Call 0x4F6


OO_InstallSystemHook

OO_InstallSystemHook Function (ROM Call 0x404)
AMS 2.00 or higher unknown.h

short OO_InstallSystemHook (pFrame, pFrame *);

This identifier has not been documented yet. Please help us out.

Uses: OO_Deref, OO_New


OO_New

OO_New Function (ROM Call 0x3FF)
AMS 2.00 or higher unknown.h

pFrame OO_New (pFrame);

This identifier has not been documented yet. Please help us out.

Uses: OO_Deref, HeapAlloc
Used by: OO_InstallAppHook, OO_InstallSystemHook, OO_SetAppAttr


OO_NextACB

OO_NextACB Function (ROM Call 0x402)
AMS 2.00 or higher unknown.h

short OO_NextACB (short TaskID);

This identifier has not been documented yet. Please help us out.

Used by: OO_AppNameToACB, push_user_func, tokenize_if_TI_92_or_text, EV_centralDispatcher, EV_defaultHandler, EV_switch, handleVarLinkKey, MO_defaults, MO_digestOptions, MO_modeDialog, MO_notifyModeChange, ROM Call 0x131, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x424, ROM Call 0x428, ROM Call 0x42B, ROM Call 0x486, ROM Call 0x4F6, ROM Call 0x4FE


OO_PrevACB

OO_PrevACB Function (ROM Call 0x403)
AMS 2.00 or higher unknown.h

short OO_PrevACB (short TaskID);

This identifier has not been documented yet. Please help us out.

Used by: handleVarLinkKey


OO_SetAppAttr

OO_SetAppAttr Function (ROM Call 0x400)
AMS 2.00 or higher unknown.h

short OO_SetAppAttr (short TaskID, unsigned long, void *);

This identifier has not been documented yet. Please help us out.

Uses: OO_Deref, OO_New, OO_SetAttr
Used by: EV_defaultHandler, EV_registerMenu


OO_SetAttr

OO_SetAttr Function (ROM Call 0x401)
AMS 2.00 or higher unknown.h

short OO_SetAttr (pFrame, unsigned long, void *);

This identifier has not been documented yet. Please help us out.

Uses: OO_Deref, HeapRealloc, memmove, ROM Call 0x505
Used by: OO_SetAppAttr


OO_UninstallAppHook

OO_UninstallAppHook Function (ROM Call 0x491)
AMS 2.00 or higher unknown.h

short OO_UninstallAppHook (short TaskID, pFrame);

This identifier has not been documented yet. Please help us out.

Uses: OO_Deref, OO_Destroy
Used by: OO_UninstallAppHookByName


OO_UninstallAppHookByName

OO_UninstallAppHookByName Function (ROM Call 0x493)
AMS 2.00 or higher unknown.h

short OO_UninstallAppHookByName (unsigned char const *, pFrame);

This identifier has not been documented yet. Please help us out.

Uses: OO_firstACB, OO_UninstallAppHook, TIOS_EV_getAppID, ROM Call 0x4F6


OO_UninstallSystemHook

OO_UninstallSystemHook Function (ROM Call 0x405)
AMS 2.00 or higher unknown.h

short OO_UninstallSystemHook (pFrame);

This identifier has not been documented yet. Please help us out.

Uses: OO_Deref, OO_Destroy


OSKeyScan

OSKeyScan Function (ROM Call 0x298)
unknown.h

short OSKeyScan (void);

This identifier has not been documented yet. Please help us out.


paint_all_except

paint_all_except Function (ROM Call 0x11D)
unknown.h

unknown_retval paint_all_except ();

This identifier has not been documented yet. Please help us out.

Uses: EV_currentApp, EV_paintOneWindow, ScrRect, DrawWinBorder
Used by: spike_in_editor, HomePushEStack


ParseSymName

ParseSymName Function (ROM Call 0x78)
unknown.h

short ParseSymName (CESI SymName);

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable, primary_tag_list, IsMainFolderStr
Used by: cmd_movevar, cmd_newfold, cmd_newplot, push_setfold, getcalc, OSLinkCmd, sendcalc, FindSymInFolder, SymFindHome, SymFindPtr, VarRecall, VarStore, ROM Call 0x437


PlotDel

PlotDel Function (ROM Call 0x203)
unknown.h

unknown_retval PlotDel ();

This identifier has not been documented yet. Please help us out.

Uses: HeapRealloc, gr_active, gr_other, memcpy
Used by: PlotPut


PlotDup

PlotDup Function (ROM Call 0x207)
unknown.h

unknown_retval PlotDup ();

This identifier has not been documented yet. Please help us out.

Uses: PlotSize, HeapAlloc, HeapLock, HeapUnlock, next_expression_index, memcpy


PlotGet

PlotGet Function (ROM Call 0x205)
unknown.h

unknown_retval PlotGet ();

This identifier has not been documented yet. Please help us out.

Uses: next_expression_index, memcpy
Used by: GetStatValue, GS_PlotAll, GS_PlotTrace, GT_SelFunc, GT_Trace, GZ_Stat, QActivePlots, SP_Define, cmd_newplot


PlotInit

PlotInit Function (ROM Call 0x206)
unknown.h

unknown_retval PlotInit ();

This identifier has not been documented yet. Please help us out.

Uses: HeapAlloc, HeapFree
Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_sinreg, cmd_twovar, OSLinkCmd


PlotLookup

PlotLookup Function (ROM Call 0x209)
unknown.h

unknown_retval PlotLookup ();

This identifier has not been documented yet. Please help us out.

Used by: gr_ck_solvergraph, cmd_plotsoff, cmd_plotson


PlotPut

PlotPut Function (ROM Call 0x204)
unknown.h

unknown_retval PlotPut ();

This identifier has not been documented yet. Please help us out.

Uses: PlotDel, PlotSize, HeapRealloc, next_expression_index, gr_active, memcpy
Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_newplot, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_sinreg, cmd_twovar


PlotSize

PlotSize Function (ROM Call 0x208)
unknown.h

unknown_retval PlotSize ();

This identifier has not been documented yet. Please help us out.

Uses: next_expression_index
Used by: PlotDup, PlotPut


push_ans_entry

push_ans_entry Function (ROM Call 0x2B0)
AMS 1.01 or higher unknown.h

HANDLE push_ans_entry (CESI);

This identifier has not been documented yet. Please help us out.

Uses: TIOS_abs, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, estack_to_short, HToESI, next_expression_index, push_expression, HS_getAns, HS_getEntry
Used by: EQU_getNameInfo, push_parse_prgm_or_func_text, push_parse_text


push_auto_units_conversion

push_auto_units_conversion Function (ROM Call 0x3B2)
AMS 1.01 or higher unknown.h

unknown_retval push_auto_units_conversion ();

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, did_push_divide_units, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, has_unit_base, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push1, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, push_zstr, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, ROM Call 0x4EF, push_exact1
Used by: replace_top_with_post_simplified


push_but_conjunct_factor

push_but_conjunct_factor Function (ROM Call 0x582)
AMS 2.02 or higher unknown.h

void push_but_conjunct_factor (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: and_onto_top, lead_conjunct_factor_index, remaining_conjuncts_index, push_expression
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_and, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, ROM Call 0x4E6


push_but_factor

push_but_factor Function (ROM Call 0x561)
AMS 2.02 or higher unknown.h

void push_but_factor (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, is_negative, is_nonnegative, is_nonpositive, is_positive, push_auto_units_conversion, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_cosh, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_exp, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_ln, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_sinh, push_solve, push_summation, push_tanh, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere


push_but_term

push_but_term Function (ROM Call 0x56A)
AMS 2.02 or higher unknown.h

void push_but_term (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_sin2, push_solve, push_zeros, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_sum


push_constant_factors

push_constant_factors Function (ROM Call 0x55D)
AMS 2.02 or higher unknown.h

void push_constant_factors (ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push1, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_constant_terms

push_constant_terms Function (ROM Call 0x566)
AMS 2.02 or higher unknown.h

void push_constant_terms (ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push0, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_dependent_factors

push_dependent_factors Function (ROM Call 0x55F)
AMS 2.02 or higher unknown.h

void push_dependent_factors (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push1, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, index_if_pushed_binomial_info, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_dependent_terms

push_dependent_terms Function (ROM Call 0x568)
AMS 2.02 or higher unknown.h

void push_dependent_terms (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push0, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, is_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_float_qr_fact

push_float_qr_fact Function (ROM Call 0x2BC)
AMS 1.01 or higher unknown.h

ESI push_float_qr_fact (ESI, float);

This identifier has not been documented yet. Please help us out.

Uses: RemainingArgCnt, push_approx, check_estack_size, delete_between, deleted_between, is_free_of_tag, next_expression_index, push_Float, push_quantum, top_estack, sqrt, _bcd_math
Used by: cmd_qr_fact


push_gcd_then_cofactors

push_gcd_then_cofactors Function (ROM Call 0x59E)
AMS 2.02 or higher unknown.h

ESI push_gcd_then_cofactors (ESI, ESI, ESI *);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_equivalent_to, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, negate_top, NG_control, primary_tag_list, push_but_factor, push_negate_quantum_as_negint, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, push1, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_gcd_numbers, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_ratio, push_square, push_sum, ER_catch, ER_success, ER_throwVar, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, is_monomial, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, float_class, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x48D, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, push_make_proper, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_factor, push_lim, push_max, push_min, push_mod, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum


push_independent_factors

push_independent_factors Function (ROM Call 0x560)
AMS 2.02 or higher unknown.h

void push_independent_factors (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push1, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, index_if_pushed_binomial_info, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_extended_prod, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_independent_terms

push_independent_terms Function (ROM Call 0x569)
AMS 2.02 or higher unknown.h

void push_independent_terms (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push0, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, is_independent_of, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_lu_fact

push_lu_fact Function (ROM Call 0x2BD)
AMS 1.01 or higher unknown.h

ESI push_lu_fact (ESI, float);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, estack_to_float, get_lb, get_ub, init_matrix_indices, is_constant, is_nonnegative, is_variable, is0, negate_top, primary_tag_list, push0, RemainingArgCnt, push_abs, push_approx, push_difference, push_product, push_ratio, check_estack_size, delete_between, delete_expression, is_free_of_tag, likely_approx_to_number, move_between_to_top, next_expression_index, push_expression, push_Float, push_quantum, push_ulong_to_integer, top_estack, _bcd_math
Used by: cmd_lu_fact


push_make_proper

push_make_proper Function (ROM Call 0x557)
AMS 2.02 or higher unknown.h

void push_make_proper (ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, NG_control, primary_tag_list, push_but_factor, push_gcd_then_cofactors, push_negate_quantum_as_negint, push_poly_qr, push_quantum_as_nonnegative_int, push_reciprocal, push_standardize, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_gcd_numbers, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, ER_catch, ER_success, ER_throwVar, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, is_monomial, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: push_expand, push_sum


push_mrow_aux

push_mrow_aux Function (ROM Call 0x31B)
AMS 1.01 or higher unknown.h

void push_mrow_aux (ESI, ESI, short, short);

This identifier has not been documented yet. Please help us out.

Uses: push1, push_product, delete_between, push_expression, push_offset_array, push_quantum, top_estack
Used by: push_sq_matrix_to_whole_number, push_determinant, push_mrow, push_red_row_ech, push_row_echelon, push_simult


push_nonconstant_factors

push_nonconstant_factors Function (ROM Call 0x55E)
AMS 2.02 or higher unknown.h

void push_nonconstant_factors (ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push1, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_nonconstant_terms

push_nonconstant_terms Function (ROM Call 0x567)
AMS 2.02 or higher unknown.h

void push_nonconstant_terms (ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push0, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_nonnumeric_factors

push_nonnumeric_factors Function (ROM Call 0x55C)
AMS 2.02 or higher unknown.h

void push_nonnumeric_factors (ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push1, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, likely_approx_to_number, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_exp, push_factor, push_lim, push_max, push_min, push_nsolve, push_sin2, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_sum


push_parse_prgm_or_func_text

push_parse_prgm_or_func_text Function (ROM Call 0x3C9)
AMS 1.01 or higher unknown.h

void push_parse_prgm_or_func_text (const char *text, ESI esi, short cmp);

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable, fix_loop_displacements, is_pathname, next_token, nonblank, primary_tag_list, push_ans_entry, push_var, ER_catch, ER_success, ER_throwVar, are_expressions_identical, check_estack_size, delete_between, delete_expression, is_valid_smap_aggregate, map_tail, move_between_to_top, next_expression_index, push_between, push_expression, push_Float, push_quantum, push_quantum_pair, push_reversed_tail, top_estack, OSCheckBreak, CheckReservedName, DerefSym, FindSymInFolder, TempFolderName, strtod, ROM Call 0x5C5, ROM Call 0x5EF, ROM Call 0x5F0
Used by: tokenize_if_TI_92_or_text


push_poly_deg_in_var_or_kernel

push_poly_deg_in_var_or_kernel Function (ROM Call 0x570)
AMS 2.02 or higher unknown.h

void push_poly_deg_in_var_or_kernel (ESI, ESI);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, replace_top2_with_sum, times_top, are_expressions_identical, compare_expressions, delete_between, next_expression_index, top_estack, push_exact0, push_exact1
Used by: push_factor


push_poly_qr

push_poly_qr Function (ROM Call 0x59D)
AMS 2.02 or higher unknown.h

ESI push_poly_qr (ESI, ESI, ESI, short);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, estack_to_float, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, negate_top, NG_control, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, push0, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_ratio, push_square, push_sum, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x48D, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, push_gcd_then_cofactors, push_make_proper, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_reciprocal

push_reciprocal Function (ROM Call 0x597)
AMS 2.02 or higher unknown.h

void push_reciprocal (ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, divide_top, estack_to_float, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_minus1, is_negative, is_nonnegative, is_nonpositive, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, negate_top, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_standardize, push0, raise_to_top, replace_top2_with_imre, replace_top2_with_pow, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, subtract_from_top, times_top, push_abs, push_approx, push_ceiling, push_conj, push_cos, push_denominator, push_exp, push_gcd_numbers, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, all_tail, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, map_tail, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, remaining_factors_index, top_estack, ST_helpMsg, XR_stringPtr, fabs, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4E9, ROM Call 0x4EA, push_half, push_exact0, push_exact_minus1, ROM Call 0x4EF, push_exact1
Used by: add_to_top, are_units_consistent, divide_top, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top_with_reciprocal, replace_top2_with_pow, replace_top2_with_ratio, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_atan, push_atanh, push_comdenom, push_conj, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_ratio, push_sum, push_to_cylin, push_to_sphere


push_simplify_statements

push_simplify_statements Function (ROM Call 0x44F)
AMS 2.00 or higher unknown.h

void push_simplify_statements (ESI);

This identifier has not been documented yet. Please help us out.

Uses: NG_control, push_simplify, push_user_func, replace_top_with_post_simplified, push_str_to_expr, push_assignment, delete_between, next_expression_index, push_internal_simplify, reset_estack_size, top_estack, OSCheckBreak, ROM Call 0x5C5, ROM Call 0x5C8, ROM Call 0x5E7, ROM Call 0x5E8, ROM Call 0x5EF, ROM Call 0x5F0
Used by: push_user_func, SP_Define, cmd_try, push_str_to_expr, NG_execute, NG_graphESI, HomeExecute


push_sq_matrix_to_whole_number

push_sq_matrix_to_whole_number Function (ROM Call 0x3C0)
AMS 1.01 or higher unknown.h

unknown_retval push_sq_matrix_to_whole_number ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, get_lb, get_ub, Integer1Index, is_constant, is_nonnegative, is_variable, is0, NG_control, primary_tag_list, push_mrow_aux, push0, push1, replace_top2_with_prod, HeapAllocHighThrow, HeapFree, HeapLock, RemainingArgCnt, push_abs, push_approx, push_augment, push_dimension, push_identity_mat, push_max1, push_mrowadd, push_rownorm, push_rowswap, push_difference, push_matrix_product, push_negate, push_product, push_ratio, ER_catch, ER_success, ER_throwVar, delete_between, delete_expression, estack_to_short, is_free_of_tag, likely_approx_to_number, next_expression_index, push_expression, push_Float, push_ulong_to_integer, top_estack, memcpy, OSCheckBreak, _bcd_math
Used by: push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_cosh, push_exp, push_ln, push_log10, push_sin2, push_sinh, push_tan, push_tanh, push_exponentiate


push_standardize

push_standardize Function (ROM Call 0x558)
AMS 2.02 or higher unknown.h

void push_standardize (ESI);

This identifier has not been documented yet. Please help us out.

Uses: add_to_top, compare_numbers, divide_top, estack_to_float, Float1Index, FloatMinus1Index, FloatPiIndex, get_lb, get_ub, integer_non_unknown, Integer0Index, Integer1Index, Integer2Index, IntegerMinus1Index, is_constant, is_minus1, is_nonnegative, is_positive, is_real, is_reciprocal_of_quantum, is_variable, is_whole_number, is0, is1, negate_top, NG_control, primary_tag_list, push_but_factor, push_quantum_as_nonnegative_int, push_reciprocal, raise_to_top, replace_top2_with_imre, replace_top2_with_prod, replace_top2_with_ratio, replace_top2_with_sum, times_top, push_abs, push_approx, push_ceiling, push_cos, push_denominator, push_gcd_numbers, push_mod, push_numerator, push_sin, push_arg_minus_1, push_arg_plus_1, push_difference, push_exponentiate, push_negate, push_pow, push_product, push_square, push_sum, are_expressions_identical, check_estack_size, compare_expressions, delete_between, delete_expression, deleted_between, deleted_expression, estack_number_to_Float, factor_base_index, factor_exponent_index, is_advanced_tag, lead_base_index, lead_exponent_index, lead_factor_index, lead_term_index, likely_approx_to_number, main_gen_var_index, move_between_to_top, moved_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expr2_quantum, push_expression, push_Float, push_offset_array, push_quantum, push_quantum_pair, reductum_index, remaining_factors_index, should_and_did_push_approx_arg2, top_estack, ST_helpMsg, XR_stringPtr, fabs, float_class, sqrt, _bcd_math, _du16u16, _ds32s32, _ms32s32, ROM Call 0x4DF, ROM Call 0x4EA, push_half, push_exact0, ROM Call 0x4EF, push_exact1
Used by: get_ub, index_if_pushed_binomial_info, push_gcd_then_cofactors, push_make_proper, push_reciprocal, did_push_anti_deriv, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_desolve, push_expand, push_factor, push_lim, push_max, push_min, push_nsolve, push_sign, push_solve, push_zeros, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum


push_symbolic_qr_fact

push_symbolic_qr_fact Function (ROM Call 0x2BE)
AMS 1.01 or higher unknown.h

ESI push_symbolic_qr_fact (ESI);

This identifier has not been documented yet. Please help us out.

Uses: divide_top, init_list_indices, init_matrix_indices, Integer0Index, Integer1Index, is0, negate_top, push0, push1, replace_top2_with_sum, times_top, RemainingArgCnt, push_conj, push_sqrt, push_submat, push_sumlist, push_difference, push_product, push_ratio, check_estack_size, delete_between, deleted_between, next_expression_index, push_expression, push_quantum, push_transpose_aux, push_ulong_to_integer, top_estack
Used by: cmd_qr_fact


push_trig

push_trig Function (ROM Call 0x535)
AMS 2.02 or higher unknown.h

void push_trig (ESI_Callback_t, ESI);

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, is_units_term, push_reciprocal_of_quantum, times_top, push_cos, push_sin, push_tan, delete_between, is_free_of_tag, map_tail, push_expression, push_Float, push_quantum, top_estack, fabs, trig, _bcd_math
Used by: push_spher_vector, push_polar_to_rect_x, push_polar_to_rect_y


push_unit_system_list

push_unit_system_list Function (ROM Call 0x3B3)
AMS 1.01 or higher unknown.h

unknown_retval push_unit_system_list ();

This identifier has not been documented yet. Please help us out.

Uses: push_quantum, push_zstr, XR_stringPtr


push_user_func

push_user_func Function (ROM Call 0x2B3)
AMS 1.01 or higher unknown.h

void push_user_func (ESI, short);

This identifier has not been documented yet. Please help us out.

Uses: and_onto_top, CTypeTable, EV_currentApp, gr_execute_de, gr_execute_seq, is_constant, lead_conjunct_factor_index, NG_control, NG_such_that_index, OO_firstACB, OO_GetAppAttr, OO_NextACB, primary_tag_list, push_simplify_statements, remaining_conjuncts_index, replace_top_with_post_simplified, tokenize_if_TI_92_or_text, HeapGetLock, HeapLock, HeapMoveHigh, HeapUnlock, RemainingArgCnt, push_indir_name, ER_catch, ER_success, ER_throwVar, all_tail, bottom_estack, delete_between, HToESI, is_free_of_tag, map_tail, move_between_to_top, next_expression_index, push_expression, push_internal_simplify, push_quantum, top_estack, strchr, EX_patch, AddSymToFolder, DerefSym, EM_twinSymFromExtMem, FolderAddTemp, FolderDelTemp, VarRecall, VarStore, ROM Call 0x131, ROM Call 0x450, ROM Call 0x5C5, ROM Call 0x5C6, ROM Call 0x5C7, ROM Call 0x5C8, ROM Call 0x5CB, ROM Call 0x5CC, ROM Call 0x5E4, ROM Call 0x5ED
Used by: push_simplify_statements


push_var_kern_tail

push_var_kern_tail Function (ROM Call 0x56F)
AMS 2.02 or higher unknown.h

void push_var_kern_tail (ESI);

This identifier has not been documented yet. Please help us out.

Uses: next_var_or_kernel_index, main_gen_var_index, push_expression, push_quantum
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


push_var

push_var Function (ROM Call 0x3CB)
AMS 1.01 or higher unknown.h

void push_var (const char *start, const char *end);

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable, next_expression_index, push_quantum, top_estack, memcpy, strlen, XR_stringPtr
Used by: EQU_getNameInfo, push_parse_prgm_or_func_text, push_indir_name, push_parse_text


push_zero_partial_column

push_zero_partial_column Function (ROM Call 0x3C2)
AMS 1.01 or higher unknown.h

void push_zero_partial_column (CESI mat, short row, short col);

This identifier has not been documented yet. Please help us out.

Uses: Integer0Index, delete_between, push_expression, push_offset_array, push_quantum, top_estack


QActivePlots

QActivePlots Function (ROM Call 0x20A)
unknown.h

unknown_retval QActivePlots ();

This identifier has not been documented yet. Please help us out.

Uses: PlotGet, QPlotActive, gr_active
Used by: GT_Trace


QPlotActive

QPlotActive Function (ROM Call 0x20B)
unknown.h

unknown_retval QPlotActive ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active
Used by: GS_PlotAll, GT_SelFunc, GT_Trace, GZ_Stat, QActivePlots


QSkipGraphErr

QSkipGraphErr Function (ROM Call 0x1E7)
unknown.h

unknown_retval QSkipGraphErr ();

This identifier has not been documented yet. Please help us out.

Uses: ROM Call 0x487
Used by: de_loop, dv_create_graph_titles, execute_graph_func, GM_TanLine, GR3_addContours, run_one_seq, cmd_circle, cmd_drawfunc, cmd_drawinv, cmd_drawparm, cmd_drawpol, cmd_linetan, cmd_shade, cmd_slpline, GR3_paint3d, GR3_xyToWindow


readHandshake

readHandshake Function (ROM Call 0x602)
AMS 2.07 or higher unknown.h

unsigned char readHandshake (unsigned short DummyErrArg, void *DataBuffer, unsigned short MaxDataLen, unsigned short *DataLen, unsigned char *ThreadID, unsigned char* SenderID, unsigned short MaxWaitingTime);

Deprecated high-level linking protocol.

This function is available only in AMS 2.07-2.09.


ReallocExprStruct

ReallocExprStruct Function (ROM Call 0x14D)
unknown.h

short ReallocExprStruct (HANDLE struct, unsigned short, ESI);

This identifier has not been documented yet. Please help us out.

Uses: HeapRealloc, next_expression_index, memcpy
Used by: cmd_custom, cmd_toolbar


recall_data_var

recall_data_var Function (ROM Call 0x112)
unknown.h

unknown_retval recall_data_var ();

This identifier has not been documented yet. Please help us out.

Uses: CharNumber, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, HToESI, AddSymToFolder, DerefSym, FolderCurTemp, TempFolderName, VarStore


Regraph

Regraph Function (ROM Call 0x1B6)
unknown.h

unknown_retval Regraph ();

This identifier has not been documented yet. Please help us out.

Uses: cleanup_de_mem, cleanup_seq_mem, clear_error_context, CountGrFunc, cpt_gr_fun, cpt_gr_param, cpt_gr_polar, CptIndep, CptLastIndepDE, de_initRes, de_loop, deStepCk, estack_to_float, FindFunc, FindGrFunc, FirstSeqPlot, FuncLineFlt, gr_CptIndepInc, gr_de_value, gr_del_locals, gr_del_vars_in_folder, gr_delete_fldpic, gr_DispLabels, gr_find_el, gr_seq_value, gr_stopic, gr_xres_pixel, GrAxes, GrClipLine, GrLineFlt, GS_PlotAll, GT_BackupToScr, GT_WinCursor, InitDEAxesRng, InitDEMem, InitTimeSeq, run_one_seq, seqStepCk, seqWebInit, setup_more_graph_fun, time_loop, TIOS_abs, unlock_more_graph_fun, VarGraphRefBitsClear, XCvtFtoP, XCvtPtoF, YCvtFtoP, HeapAllocThrow, HeapDeref, HeapFree, HeapFreeIndir, ER_catch, ER_success, ER_throwVar, HToESI, top_estack, GR3_paint3d, DrawLine, CptDeltax, CptDeltay, gr_active, gr_flags, StepCk, kbhit, ngetchx, pushkey, memcpy, memset, ST_busy, idle, off, OSFreeTimer, OSRegisterTimer, OSTimerExpired, OSTimerRestart, is_nan, is_transfinite, ResetSymFlags, SymFind, SymFindFirst, TempFolderName, WinAttr, WinBitmapPut, WinClr, WinDupStat, WinLineNC, _bcd_math, NG_setup_graph_fun, NG_cleanup_graph_fun, ROM Call 0x46E
Used by: GT_DE_Init_Conds, GT_Regraph_if_neccy, GZ_Fit


remaining_conjuncts_index

remaining_conjuncts_index Function (ROM Call 0x581)
AMS 2.02 or higher unknown.h

ESI remaining_conjuncts_index (ESI);

This identifier has not been documented yet. Please help us out.

Uses: index_true, next_expression_index
Used by: get_lb, get_ub, is_negative, is_never0, is_nonnegative, is_nonpositive, is_positive, push_but_conjunct_factor, push_user_func, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_and, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_or, push_substitute_using_such_that, ST_eraseHelp, ST_modKey, ROM Call 0x4E6


remaining_disjuncts_index

remaining_disjuncts_index Function (ROM Call 0x57F)
AMS 2.02 or higher unknown.h

ESI remaining_disjuncts_index (ESI);

This identifier has not been documented yet. Please help us out.

Uses: index_false, next_expression_index
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_or, ROM Call 0x4E6


run_one_seq

run_one_seq Function (ROM Call 0x1DB)
unknown.h

unknown_retval run_one_seq ();

This identifier has not been documented yet. Please help us out.

Uses: clear_error_context, gr_del_locals, QSkipGraphErr, HeapDeref, ER_catch, ER_success, ER_throwVar, NG_graphESI, push_quantum, top_estack, memcpy, FolderDelAllTemp, ResetSymFlags
Used by: GT_CalcDepVals, Regraph


ScrRectDivide

ScrRectDivide Function (ROM Call 0x28)
unknown.h

SCR_RECT *ScrRectDivide (const SCR_RECT *r, const SCR_RECT *, short *);

This identifier has not been documented yet. Please help us out.

Uses: ScrRectOverlap, memcmp
Used by: UpdateWindows


SearchExprStruct

SearchExprStruct Function (ROM Call 0x14E)
unknown.h

char *SearchExprStruct (HANDLE struct, unsigned short id);

This identifier has not been documented yet. Please help us out.

Used by: CustomMenuItem


seqStepCk

seqStepCk Function (ROM Call 0x1DE)
unknown.h

unknown_retval seqStepCk ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active, floor, _bcd_math
Used by: gr_execute_seq, Regraph, cmd_blddata


seqWebInit

seqWebInit Function (ROM Call 0x1DA)
unknown.h

unknown_retval seqWebInit ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, gr_initCondName, HeapAllocThrow, HeapLock, HeapUnlock, ER_catch, ER_success, ER_throwVar, HToESI, NG_approxESI, top_estack, gr_active, memcpy, AddSymToFolder, DerefSym, FolderDelAllTemp, FolderDelTemp, SymFindMain
Used by: GT_Trace, Regraph


SetGraphMode

SetGraphMode Function (ROM Call 0x1B5)
unknown.h

void SetGraphMode (unsigned char GraphMode);

This identifier has not been documented yet. Please help us out.

Uses: gr_delete_fldpic, gr_DelFolder, GR3_freeDB, HeapFreeIndir, gr_active, gr_other


setup_more_graph_fun

setup_more_graph_fun Function (ROM Call 0x1CE)
unknown.h

unknown_retval setup_more_graph_fun ();

This identifier has not been documented yet. Please help us out.

Uses: grFuncName, tokenize_if_TI_92_or_text, HeapLock, HToESI, next_expression_index, gr_active, DerefSym
Used by: GT_CalcDepVals, InitDEMem, InitTimeSeq, Regraph, cmd_blddata


setup_unit_system

setup_unit_system Function (ROM Call 0x3B4)
AMS 1.01 or higher unknown.h

unknown_retval setup_unit_system ();

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable, init_unit_system, next_expression_index, top_estack, MO_notifyModeChange, cmpstri, XR_stringPtr, ROM Call 0x41C, ROM Call 0x41D, ROM Call 0x41E


SP_Define

SP_Define Function (ROM Call 0x110)
unknown.h

unknown_retval SP_Define ();

This identifier has not been documented yet. Please help us out.

Uses: EV_quit, FirstNonblank, hStrAppend, PlotGet, push_simplify_statements, HeapAlloc, HeapAllocThrow, HeapFreeIndir, HeapLock, HeapUnlock, HLock, Dialog, ER_catch, ER_success, ER_throwVar, ERD_dialog, NG_tokenize, Parse1DExpr, push_expression, push_quantum, top_estack, memcpy, memset, sprintf, strlen, XR_stringPtr


spike_chk_gr_dirty

spike_chk_gr_dirty Function (ROM Call 0x11A)
unknown.h

unknown_retval spike_chk_gr_dirty ();

This identifier has not been documented yet. Please help us out.

Uses: GetSysGraphRef, gr_active
Used by: spike_in_editor, spike_optionD


spike_geo_titles

spike_geo_titles Function (ROM Call 0x115)
unknown.h

unknown_retval spike_geo_titles ();

This identifier has not been documented yet. Please help us out.

Uses: CheckGraphRef, spike_titles_in_editor, statFree, HeapRealloc, RemainingArgCnt, cmd_newdata, HToESI, next_expression_index, top_estack, memcpy, memmove, DerefSym, SymFindMain
Used by: spike_in_editor, spike_optionD


spike_in_editor

spike_in_editor Function (ROM Call 0x116)
unknown.h

unknown_retval spike_in_editor ();

This identifier has not been documented yet. Please help us out.

Uses: dv_create_graph_titles, paint_all_except, push0, spike_chk_gr_dirty, spike_geo_titles, HeapRealloc, ER_catch, ER_success, ER_throwVar, next_expression_index, push_quantum, top_estack, gr_active, memcpy, memmove, memset, sprintf, AddSymToFolder, DerefSym, FindSymInFolder, HSymDel, VarStore, _bcd_math
Used by: spike_optionD


spike_optionD

spike_optionD Function (ROM Call 0x114)
unknown.h

unknown_retval spike_optionD ();

This identifier has not been documented yet. Please help us out.

Uses: CheckGraphRef, dv_create_graph_titles, spike_chk_gr_dirty, spike_geo_titles, spike_in_editor, statFree, HeapRealloc, RemainingArgCnt, cmd_newdata, ER_catch, ER_success, ER_throwVar, HToESI, next_expression_index, push_quantum, top_estack, memcpy, memmove, ST_helpMsg, XR_stringPtr, DerefSym, SymFindMain
Used by: GT_IncXY, GT_Trace


spike_titles_in_editor

spike_titles_in_editor Function (ROM Call 0x118)
unknown.h

unknown_retval spike_titles_in_editor ();

This identifier has not been documented yet. Please help us out.

Uses: ER_catch, ER_success, ER_throwVar, next_expression_index, top_estack, memset, sprintf, AddSymToFolder, FindSymInFolder, HSymDel, VarStore, _bcd_math
Used by: spike_geo_titles


startBPTimer

startBPTimer Function (ROM Call 0x604)
AMS 2.07 or higher unknown.h

unsigned short startBPTimer (void);

Starts timer number 8 with a very high initial value.

This function is available only in AMS 2.07-2.09. It must be called before using readHandshake or writeHandshake.


stopBPTimer

stopBPTimer Function (ROM Call 0x605)
AMS 2.07 or higher unknown.h

unsigned short stopBPTimer (void);

Stops timer number 8.

This function is available only in AMS 2.07-2.09.


store_data_var

store_data_var Function (ROM Call 0x111)
unknown.h

void store_data_var (ESI name, unsigned char bSetFlags);

This identifier has not been documented yet. Please help us out.

Uses: CharNumber, HeapAlloc, HeapFree, memcpy, DerefSym, FindSymInFolder, partial_len, VarStore


store_func_def

store_func_def Function (ROM Call 0x2B4)
AMS 1.01 or higher unknown.h

void store_func_def (ESI esi);

This identifier has not been documented yet. Please help us out.

Uses: index_after_match_endtag, primary_tag_list, push_indir_name, bottom_estack, next_expression_index, push_expression, push_quantum, top_estack, FindSymInFolder, TempFolderName, VarStore, ROM Call 0x5C7, ROM Call 0x5C8
Used by: push_assignment


store_to_subscripted_element

store_to_subscripted_element Function (ROM Call 0x2B5)
AMS 1.01 or higher unknown.h

void store_to_subscripted_element (CESI esi, CESI data);

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, push_indir_name, estack_to_ushort, next_expression_index, top_estack, VarStore, ROM Call 0x450
Used by: cmd_get, push_assignment


time_loop

time_loop Function (ROM Call 0x1D8)
unknown.h

unknown_retval time_loop ();

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, HeapAlloc, HeapCompress, HeapGetHandle, ER_catch, ER_success, bottom_estack, HToESI, push_between, push_Float, reset_estack_size, top_estack, gr_active, SymFind, _bcd_math, ROM Call 0x5C6
Used by: gr_execute_seq, GT_Trace, Regraph, cmd_blddata


TimeFormat_Get

TimeFormat_Get Function (ROM Call 0x5FF)
AMS 2.07 or higher unknown.h

unsigned char TimeFormat_Get (void);

This identifier has not been documented yet. Please help us out.

Uses: memset, sprintf, strcat
Used by: EV_quit, EV_defaultHandler


TimeFormat_Set

TimeFormat_Set Function (ROM Call 0x600)
AMS 2.07 or higher unknown.h

void TimeFormat_Set (unsigned char NewTimeFormat);

This identifier has not been documented yet. Please help us out.


Timer_Start

Timer_Start Function (ROM Call 0x5F8)
AMS 2.07 or higher unknown.h

unsigned long Timer_Start (void);

This identifier has not been documented yet. Please help us out.

Uses: IsClockOn


Timer_Value

Timer_Value Function (ROM Call 0x5F9)
AMS 2.07 or higher unknown.h

unsigned long Timer_Value (unsigned long TimerStartingValue);

This identifier has not been documented yet. Please help us out.

Uses: IsClockOn


TimeStr

TimeStr Function (ROM Call 0x601)
AMS 2.07 or higher unknown.h

void TimeStr (unsigned short hour, unsigned short minute, unsigned short second, unsigned short PrintSecond, unsigned char TimeFormat, char* str);

This identifier has not been documented yet. Please help us out.

Uses: memset, sprintf, strcat, XR_stringPtr, fmod, _bcd_math
Used by: EV_quit, EV_defaultHandler


TimeZone_Get

TimeZone_Get Function (ROM Call 0x5FA)
AMS 2.07 or higher unknown.h

signed short TimeZone_Get (void);

This identifier has not been documented yet. Please help us out.

Used by: DateAndTime_Set, DateAndTime_Get


TimeZone_Set

TimeZone_Set Function (ROM Call 0x5FB)
AMS 2.07 or higher unknown.h

void TimeZone_Set (signed short NewTimeZone);

This identifier has not been documented yet. Please help us out.


TIOS_abs

TIOS_abs Function (ROM Call 0x5BA)
AMS 2.04 or higher unknown.h

short TIOS_abs (short);

This identifier has not been documented yet. Please help us out.

Used by: compare_numbers, gr_de_axes_lbl, gr_de_value, GR3_handleEvent, GrAxes, GT_DE_Init_Conds, GT_DspTraceCoords, GT_SelFunc, GT_Trace, InitDEMem, push_ans_entry, Regraph, cmd_blddata, Parse1DExpr, BitmapPut, DrawChar, DrawClipChar, DrawLine, DrawStr, FillLines2, FillTriangle, ScrRectScroll, ScrRectShift, acosh, asinh, atanh, ROM Call 0x3EC, ROM Call 0x47B


TIOS_div

TIOS_div Function (ROM Call 0x5BB)
AMS 2.04 or higher unknown.h

div_t TIOS_div (short, short);

This identifier has not been documented yet. Please help us out.


TIOS_labs

TIOS_labs Function (ROM Call 0x5BC)
AMS 2.04 or higher unknown.h

long TIOS_labs (long);

This identifier has not been documented yet. Please help us out.


TIOS_ldiv

TIOS_ldiv Function (ROM Call 0x5BD)
AMS 2.04 or higher unknown.h

ldiv_t TIOS_ldiv (long, long);

This identifier has not been documented yet. Please help us out.


TIOS_strtol

TIOS_strtol Function (ROM Call 0x4FF)
AMS 2.00 or higher unknown.h

long TIOS_strtol (const char *, char **, short);

This identifier has not been documented yet. Please help us out.

Uses: errno, _ds32s32, _ms32s32
Used by: ROM Call 0x502


tokenize_if_TI_92_or_text

tokenize_if_TI_92_or_text Function (ROM Call 0x265)
unknown.h

unknown_retval tokenize_if_TI_92_or_text ();

This identifier has not been documented yet. Please help us out.

Uses: gen_version, NG_control, OO_firstACB, OO_GetAppAttr, OO_NextACB, primary_tag_list, push_parse_prgm_or_func_text, HeapFree, HeapLock, HeapRealloc, HeapUnlock, ER_catch, ER_success, ER_throwVar, delete_between, display_statements, HToESI, next_expression_index, push_expression, push_quantum, push_quantum_pair, top_estack, MO_currentOptions, memcpy, strcmp, strlen, OSDisableBreak, OSEnableBreak, XR_stringPtr, CheckReservedName, DerefSym, ROM Call 0x5C8, ROM Call 0x5C9, ROM Call 0x5CA, ROM Call 0x5CB, ROM Call 0x5CC
Used by: push_user_func, setup_more_graph_fun, NG_setup_graph_fun


TokenizeName

TokenizeName Function (ROM Call 0x3E9)
AMS 2.00 or higher unknown.h

unsigned short TokenizeName (const char *, unsigned char *);

This identifier has not been documented yet. Please help us out.

Uses: TokenizeSymName, top_estack, memcpy
Used by: FDelete, FOpen


unlock_more_graph_fun

unlock_more_graph_fun Function (ROM Call 0x1CF)
unknown.h

unknown_retval unlock_more_graph_fun ();

This identifier has not been documented yet. Please help us out.

Uses: HeapUnlock, HToESI
Used by: cleanup_de_mem, cleanup_seq_mem, GT_CalcDepVals, Regraph, cmd_blddata


UpdateWindows

UpdateWindows Function (ROM Call 0x2B)
unknown.h

short UpdateWindows (SCR_RECT *);

This identifier has not been documented yet. Please help us out.

Uses: ScrRectDivide, ScrRect, ScrRectFill, ScrRectOverlap, memmove, MenuUpdate, DrawWinBorder, FirstWindow, WinClr
Used by: WinRemove, WinActivate, WinHide, WinReOpen


ValidateStore

ValidateStore Function (ROM Call 0x8D)
unknown.h

HSym ValidateStore (HSym Var, unsigned char Flags);

This identifier has not been documented yet. Please help us out.

Uses: HSYMtoName, VarStore


VarGraphRefBitsClear

VarGraphRefBitsClear Function (ROM Call 0x268)
unknown.h

void VarGraphRefBitsClear (void);

This identifier has not been documented yet. Please help us out.

Uses: gr_active
Used by: Regraph, ROM Call 0x40C


VarSaveTitle

VarSaveTitle Function (ROM Call 0x290)
unknown.h

short VarSaveTitle (HANDLE Dialog, const char *TitleSym, char *dest);

This identifier has not been documented yet. Please help us out.

Uses: DialogAdd, strcat, strlen, XR_stringPtr, TokToStrN
Used by: VarNew, VarSaveAs


VarStoreLink

VarStoreLink Function (ROM Call 0x87)
unknown.h

HSym VarStoreLink (ESI esi, HANDLE *DestVar, unsigned short *Status);

This identifier has not been documented yet. Please help us out.

Uses: HeapFree, HeapFreeIndir, HeapLock, HeapUnlock, ER_catch, ER_success, HToESI, next_expression_index, TokenizeSymName, top_estack, CheckReservedName, ClearUserDef, DerefSym, QSysProtected, VarStore
Used by: getcalc, OSLinkCmd


writeHandshake

writeHandshake Function (ROM Call 0x603)
AMS 2.07 or higher unknown.h

unsigned char writeHandshake (unsigned short DummyErrArg, void *Data, unsigned short DataLen, unsigned char ThreadID, unsigned char SenderID);

Deprecated high-level linking protocol.

This function is available only in AMS 2.07-2.09.


XCvtFtoP

XCvtFtoP Function (ROM Call 0x1BD)
unknown.h

short XCvtFtoP (float, GR_WIN_VARS *);

This identifier has not been documented yet. Please help us out.

Uses: _bcd_math
Used by: dv_create_graph_titles, FuncLineFlt, GM_Integrate, GM_Shade, GM_TanLine, GrAxes, GrLineFlt, GS_PlotAll, GT_SetCursorXY, GT_Trace, Regraph, cmd_circle, cmd_line, cmd_linevert, cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pttext, cmd_pxlchg, cmd_pxloff, cmd_pxlon, cmd_pxltext, push_pttest, push_pxltest


XCvtPtoF

XCvtPtoF Function (ROM Call 0x1BA*)
unknown.h

float XCvtPtoF (short, GR_WIN_VARS *);

This identifier has not been documented yet. Please help us out.

Uses: CptFuncX, _bcd_math
Used by: dv_create_graph_titles, GM_Integrate, GM_Shade, GM_TanLine, GrAxes, GT_DspFreeTraceCoords, GT_FreeTrace, GT_IncXY, GT_SetGraphRange, GT_Trace, GZ_Integer, Regraph, cmd_circle, cmd_drawfunc, cmd_drawinv, cmd_linetan, cmd_shade, cmd_slpline


YCvtFtoP

YCvtFtoP Function (ROM Call 0x1BC)
unknown.h

short YCvtFtoP (float, GR_WIN_VARS *);

This identifier has not been documented yet. Please help us out.

Uses: GT_DspTraceCoords, GT_PrintCursor, GXcoord, GYcoord, gr_active, WinAttr, WinDupStat, WinStrXY, _bcd_math
Used by: FuncLineFlt, GrLineFlt, GS_PlotAll, GT_SetCursorXY, GT_Trace, Regraph, cmd_circle, cmd_line, cmd_linehorz, cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pttext, cmd_pxlchg, cmd_pxloff, cmd_pxlon, cmd_pxltext, push_pttest, push_pxltest


YCvtFtoWin

YCvtFtoWin Function (ROM Call 0x1B3)
unknown.h

unknown_retval YCvtFtoWin ();

This identifier has not been documented yet. Please help us out.

Uses: gr_active, _bcd_math
Used by: GM_Integrate, GM_Shade, cmd_circle, cmd_shade


YCvtPtoF

YCvtPtoF Function (ROM Call 0x1BB*)
unknown.h

float YCvtPtoF (short, GR_WIN_VARS *);

This identifier has not been documented yet. Please help us out.

Uses: round12_err, _bcd_math
Used by: dv_create_graph_titles, GM_TanLine, GT_DspFreeTraceCoords, GT_FreeTrace, GT_IncXY, GT_SetGraphRange, GZ_Integer, cmd_drawfunc, cmd_drawinv, cmd_linetan, cmd_slpline


errno

errno Variable (ROM Call 0x5D9)
AMS 2.04 or higher unknown.h

short errno;

This identifier has not been documented yet. Please help us out.

Used by: TIOS_strtol, strtod


EV_appA

EV_appA Variable (ROM Call 0x452)
unknown.h

short EV_appA;

This identifier has not been documented yet. Please help us out.

Used by: EV_quit, EV_centralDispatcher, EV_defaultHandler, EV_startApp, EV_switch, MO_currentOptions, MO_digestOptions, MO_notifyModeChange, MO_sendQuit, OSLinkCmd, ROM Call 0x4FE


EV_appB

EV_appB Variable (ROM Call 0x453)
unknown.h

short EV_appB;

This identifier has not been documented yet. Please help us out.

Used by: EV_quit, EV_centralDispatcher, EV_defaultHandler, EV_startApp, EV_switch, MO_currentOptions, MO_digestOptions, MO_notifyModeChange, MO_sendQuit, OSLinkCmd, ROM Call 0x4FE


EV_appSide

EV_appSide Variable (ROM Call 0x458)
unknown.h

unsigned short EV_appSide;

This identifier has not been documented yet. Please help us out.

Used by: EV_quit, push_switch, EV_centralDispatcher, EV_defaultHandler, EV_sendEvent, EV_startApp, EV_startSide, EV_startTask, EV_switch, MO_digestOptions, MO_sendQuit


EV_currentApp

EV_currentApp Variable (ROM Call 0x45C)
AMS 2.00 or higher unknown.h

short EV_currentApp;

This identifier has not been documented yet. Please help us out.

Used by: EV_quit, GT_Open, GT_SaveAs, InitDEMem, InitTimeSeq, paint_all_except, push_user_func, cmd_disp, cmd_disphome, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, EV_centralDispatcher, EV_defaultHandler, EV_eventLoop, EV_sendEventSide, EV_startApp, EV_startSide, EV_switch, MO_digestOptions, MO_modeDialog, HomeAlone, HomeExecute, HomePushEStack, MenuUpdate, VarRecall, VarStore, ROM Call 0x3CD


EV_errorCode

EV_errorCode Variable (ROM Call 0x46D)
AMS 2.00 or higher unknown.h

short EV_errorCode;

This identifier has not been documented yet. Please help us out.

Used by: ERD_dialog, EV_eventLoop, MO_modeDialog, HomeExecute, TE_handleEvent


EV_runningApp

EV_runningApp Variable (ROM Call 0x45D)
AMS 2.00 or higher unknown.h

short EV_runningApp;

This identifier has not been documented yet. Please help us out.

Used by: OO_appGetPublicStorage, OO_appSetPublicStorage, sf_width, find_error_message, EV_centralDispatcher, EV_defaultHandler, EV_registerMenu, EV_sendEventSide, DrawChar, DrawClipChar, DrawStr, XR_stringPtr, WinOpen


IM_re_tol

IM_re_tol Variable (ROM Call 0x5C1)
AMS 2.04 or higher unknown.h

float IM_re_tol;

This identifier has not been documented yet. Please help us out.

Used by: replace_top2_with_imre, ROM Call 0x48C


NG_control

NG_control Variable (ROM Call 0x466)
AMS 2.00 or higher unknown.h

unsigned long NG_control;

This identifier has not been documented yet. Please help us out.

Used by: did_push_approx_inflection_point, ER_throwFrame, get_lb, get_ub, GM_Intersect, GM_Math1, is_negative, is_nonnegative, is_nonpositive, is_positive, push_gcd_then_cofactors, push_make_proper, push_poly_qr, push_simplify, push_simplify_statements, push_sq_matrix_to_whole_number, push_standardize, push_user_func, replace_top_with_post_simplified, tokenize_if_TI_92_or_text, cmd_endwhile, cmd_if, cmd_ifthen, cmd_input, cmd_inputstr, cmd_prompt, cmd_while, did_push_anti_deriv, push_1st_derivative, push_abs, push_approx, push_csolve, push_czeros, push_def_int, push_desolve, push_determinant, push_expand, push_extended_prod, push_factor, push_im, push_lim, push_max, push_min, push_nint, push_nsolve, push_phase, push_rand, push_re, push_red_row_ech, push_row_echelon, push_sign, push_simult, push_solve, push_str_to_expr, push_summation, push_when, push_zeros, did_push_to_polar, push_and, push_dot_exponentiate, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, ER_catch, ER_throwVar, NG_approxESI, NG_execute, NG_graphESI, NG_rationalESI, push_internal_simplify, reset_control_flags, ROM Call 0x46F, cmd_lu_fact, cmd_qr_fact, ROM Call 0x4E9, ROM Call 0x4EA, ROM Call 0x4EF


NG_such_that_index

NG_such_that_index Variable (ROM Call 0x5D7)
AMS 2.04 or higher unknown.h

ESI NG_such_that_index;

This identifier has not been documented yet. Please help us out.

Used by: ER_throwFrame, get_lb, get_ub, is_negative, is_never0, is_nonnegative, is_nonpositive, is_positive, push_simplify, push_user_func, replace_top_with_post_simplified, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_extended_prod, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_summation, push_when, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_substitute_using_such_that, ER_catch, ER_throwVar, push_internal_simplify


OO_firstACB

OO_firstACB Variable (ROM Call 0x451)
AMS 2.00 or higher unknown.h

short OO_firstACB;

This identifier has not been documented yet. Please help us out.

Used by: OO_AppNameToACB, OO_InstallAppHookByName, OO_UninstallAppHookByName, push_user_func, TIOS_EV_getAppID, tokenize_if_TI_92_or_text, EV_centralDispatcher, EV_defaultHandler, EV_eventLoop, EV_switch, handleVarLinkKey, MO_defaults, MO_digestOptions, MO_modeDialog, MO_notifyModeChange, ROM Call 0x131, ROM Call 0x3F7, ROM Call 0x3F8, ROM Call 0x424, ROM Call 0x428, ROM Call 0x42B, ROM Call 0x486, ROM Call 0x4F6, ROM Call 0x4FE


OO_SuperFrame

OO_SuperFrame Variable (ROM Call 0x48F)
AMS 2.00 or higher unknown.h

pFrame OO_SuperFrame;

This identifier has not been documented yet. Please help us out.

Used by: OO_AppNameToACB, OO_CondGetAttr, OO_GetAttr


OSModKeyStatus

OSModKeyStatus Variable (ROM Call 0x431)
AMS 2.00 or higher unknown.h

unsigned short OSModKeyStatus;

This identifier has not been documented yet. Please help us out.


pSymPG

pSymPG Variable (ROM Call 0x430)
AMS 2.00 or higher unknown.h

SymPG_S *const pSymPG;

This identifier has not been documented yet. Please help us out.

Used by: HeapWalk


RAtionalize_tol

RAtionalize_tol Variable (ROM Call 0x5C0)
AMS 2.04 or higher unknown.h

float RAtionalize_tol;

This identifier has not been documented yet. Please help us out.

Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_dot_exponentiate, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_round_Float


ST_flags

ST_flags Variable (ROM Call 0x443)
AMS 2.00 or higher unknown.h

unsigned long ST_flags;

This identifier has not been documented yet. Please help us out.

Used by: dv_create_graph_titles, GM_Derivative, GM_DistArc, GM_TanLine, EV_sendEventSide, BatTooLowFlash, LIO_Receive, OSLinkCmd, ST_angle, ST_batt, ST_busy, ST_eraseHelp, ST_graph, ST_modKey, ST_precision, ST_readOnly, ST_stack


VarOptList

VarOptList Variable (ROM Call 0x444)
AMS 2.00 or higher unknown.h

unsigned short *const VarOptList;

This identifier has not been documented yet. Please help us out.

Used by: GT_Open, GT_SaveAs, VarNew, VarOpen, VarSaveAs


SYM_LEN

SYM_LEN Constant (Constant)
unknown.h

#define SYM_LEN 8

Maximum length of the name of a folder or file.


EQU_SELECT

EQU_SELECT Type (Enumeration)
unknown.h

typedef enum {SELECT_ON, SELECT_OFF, SELECT_TOGGLE} EQU_SELECT;

This identifier has not been documented yet. Please help us out.


FOLDER_TYPE

FOLDER_TYPE Type (Union)
AMS 2.00 or higher unknown.h

typedef union {
unsigned short *pW;
SYM_ENTRY *pS;
unsigned char *pB;
} FOLDER_TYPE;

A union of three pointers, pointing either to a handle, a SYM_ENTRY or a file in memory.

This union is used by SymPG_S. Any information is welcome.


OO_Indices

OO_Indices Type (Enumeration)
AMS 2.00 or higher unknown.h

enum OO_Indices {OO_APP_FLAGS = 0x1, OO_APP_NAME = 0x2, OO_APP_TOK_NAME = 0x3, OO_APP_PROCESS_EVENT = 0x4, OO_APP_DEFAULT_MENU = 0x5, OO_APP_DEFAULT_MENU_HANDLE = 0x6, OO_APP_EXT_COUNT = 0x7, OO_APP_EXTENSIONS = 0x8, OO_APP_EXT_ENTRIES = 0x9, OO_APP_LOCALIZE = 0xA, OO_APP_UNLOCALIZE = 0xB, OO_APP_CAN_DELETE = 0xC, OO_APP_CAN_MOVE = 0xD, OO_APP_VIEWER = 0xE, OO_APP_ICON = 0xF, OO_APP_EXT_HELP = 0x10, OO_APP_NOTICE_INSTALL = 0x11, OO_APP_ABOUT = 0x12, OO_SFONT = 0x300, OO_LFONT = 0x301, OO_HFONT = 0x302, OO_APP_SFONT = 0x300, OO_APP_LFONT = 0x301, OO_APP_HFONT = 0x301, OO_LANGUAGE = 0x310, OO_DATE_FORMAT = 0x311, OO_BUILTIN_HELP = 0x312, OO_KTLIST = 0x320, OO_CAT_TABLE = 0x321, OO_CAT_INDEX = 0x322, OO_CAT_COUNT = 0x323, OO_CHAR_MENU = 0x330, OO_CHAR_HANDLER = 0x331, OO_APPS_HANDLER = 0x332, OO_FLASH_APPS_HANDLER = 0x333, OO_MATH_HANDLER = 0x334, OO_MEM_HANDLER = 0x335, OO_STO_HANDLER = 0x336, OO_QUIT_HANDLER = 0x337};

This identifier has not been documented yet. Please help us out.


pFrame

pFrame Type (Scalar)
unknown.h

typedef unsigned long pFrame;

This identifier has not been documented yet. Please help us out.


SymPG_S

SymPG_S Type (Structure)
AMS 2.00 or higher unknown.h

typedef struct SymPrivateGlobals {
unsigned char SPG_Ver;
unsigned short SymTempFolCount;
unsigned char *SymFolder,*SymName;
HANDLE SymHandle, HomeHandle, MainHandle, DefTempHandle, DefFolderHandle;
unsigned short SymErrCode;
unsigned short CallStatFree;
HANDLE FindHandle;
unsigned short DefFolderName[SYM_LEN+1];
struct {
FOLDER_TYPE Low, High, Cur;
unsigned short CurOffset;
} Find, Prev;
} SymPG_S;

A structure describing a "symbol table private global structure".

There is only one reason for using such a structure: saving the global variables pointed to by pSymPG.

Note: replacing the structure pointed to by pSymPG by an invalid structure may leave the system in an unstable state.

Any information is welcome.


Two_ESI_Callback_t

Two_ESI_Callback_t Type (Pointer)
unknown.h

typedef CALLBACK void (*Two_ESI_Callback_t) (ESI, ESI);

This identifier has not been documented yet. Please help us out.


unknown_retval

unknown_retval Type (Scalar)
unknown.h

typedef unsigned short unknown_retval;

Type for unknown return values.

unknown_retval is a type which represents an unknown return value type. Since most functions return their values in the same register, it is logical to use this type, so you can test unknown functions with the least possible restrictions.


values.h

values.h Header File
Header File Index

Various platform-dependent constants

Constants
_DEXPLEN
Number of exponent bits for double precision.
_EXPBASE
Exponent base used for floating point representation.
_FEXPLEN
Number of exponent bits for single precision.
_IEEE
Boolean flag: tells that TI floats are not compatible with IEEE standard.
BITSPERBYTE
Number of bits per one byte.
DMAXEXP
Maximal floating point exponent for double precision; greater exponents are principally possible (up to 16383), but not supported in all math functions.
DMAXPOWTWO
Maximal power of two in double precision.
DMINEXP
Minimal floating point exponent for double precision; smaller exponents are principally possible (up to -16383), but not supported in all math functions.
DSIGNIF
Number of mantissa bits for double precision.
FMAXEXP
Maximal floating point exponent for single precision.
FMAXPOWTWO
Maximal power of two in single precision.
FMINEXP
Minimal floating point exponent for single precision.
FSIGNIF
Number of mantissa bits for single precision.
HIBITI
The most significant bit mask for the int type.
HIBITL
The most significant bit mask for the long int type.
HIBITS
The most significant bit mask for the short int type.
LN_MAXDOUBLE
Natural logarithm of MAXDOUBLE.
LN_MINDOUBLE
Natural logarithm of MINDOUBLE.
MAXDOUBLE
Maximum floating point number for double precision (see notes about DMAXEXP).
MAXFLOAT
Maximum floating point number for single precision.
MAXINT
Maximum value which can be stored in an int variable.
MAXLONG
Maximum value which can be stored in a long int variable.
MAXSHORT
Maximum value which can be stored in a short int variable.
MINDOUBLE
Minimum floating point number for single precision (see notes about DMINEXP).
MINFLOAT
Minimum floating point number for single precision.
Predefined Types
bcd
Represents the internal organization of floating point numbers in the format recognized by the TIOS.
ti_float
An alias for the standard ANSI float type.

See also: limits.h, float.h


_DEXPLEN

_DEXPLEN Constant
values.h

#define _DEXPLEN 15

Number of exponent bits for double precision.


_EXPBASE

_EXPBASE Constant
values.h

#define _EXPBASE 10

Exponent base used for floating point representation.


_FEXPLEN

_FEXPLEN Constant
values.h

#define _FEXPLEN 15

Number of exponent bits for single precision.


_IEEE

_IEEE Constant
values.h

#define _IEEE 0

Boolean flag: tells that TI floats are not compatible with IEEE standard.


BITSPERBYTE

BITSPERBYTE Constant
values.h

#define BITSPERBYTE 8

Number of bits per one byte.


DMAXEXP

DMAXEXP Constant
values.h

#define DMAXEXP 999

Maximal floating point exponent for double precision; greater exponents are principally possible (up to 16383), but not supported in all math functions.


DMAXPOWTWO

DMAXPOWTWO Constant
values.h

#define DMAXPOWTWO 3321

Maximal power of two in double precision.


DMINEXP

DMINEXP Constant
values.h

#define DMINEXP (-999)

Minimal floating point exponent for double precision; smaller exponents are principally possible (up to -16383), but not supported in all math functions.


DSIGNIF

DSIGNIF Constant
values.h

#define DSIGNIF 64

Number of mantissa bits for double precision.


FMAXEXP

FMAXEXP Constant
values.h

#define FMAXEXP 999

Maximal floating point exponent for single precision.


FMAXPOWTWO

FMAXPOWTWO Constant
values.h

#define FMAXPOWTWO 3321

Maximal power of two in single precision.


FMINEXP

FMINEXP Constant
values.h

#define FMINEXP (-999)

Minimal floating point exponent for single precision.


FSIGNIF

FSIGNIF Constant
values.h

#define FSIGNIF 56

Number of mantissa bits for single precision.


HIBITI

HIBITI Constant
values.h

#define HIBITI 0x8000/0x80000000

The most significant bit mask for the int type.


HIBITL

HIBITL Constant
values.h

#define HIBITL 0x80000000L

The most significant bit mask for the long int type.


HIBITS

HIBITS Constant
values.h

#define HIBITS 0x8000

The most significant bit mask for the short int type.


LN_MAXDOUBLE

LN_MAXDOUBLE Constant
values.h

#define LN_MAXDOUBLE (2303.58509299)

Natural logarithm of MAXDOUBLE.


LN_MINDOUBLE

LN_MINDOUBLE Constant
values.h

#define LN_MINDOUBLE (-2300.2825079)

Natural logarithm of MINDOUBLE.


MAXDOUBLE

MAXDOUBLE Constant
values.h

#define MAXDOUBLE (9.999999999999999e999)

Maximum floating point number for double precision (see notes about DMAXEXP).


MAXFLOAT

MAXFLOAT Constant
values.h

#define MAXFLOAT (9.999999999999999e999)

Maximum floating point number for single precision.


MAXINT

MAXINT Constant
values.h

#define MAXINT 0x7FFF/0x7FFFFFFF

Maximum value which can be stored in an int variable.


MAXLONG

MAXLONG Constant
values.h

#define MAXLONG 0x7FFFFFFFL

Maximum value which can be stored in a long int variable.


MAXSHORT

MAXSHORT Constant
values.h

#define MAXSHORT 0x7FFF

Maximum value which can be stored in a short int variable.


MINDOUBLE

MINDOUBLE Constant
values.h

#define MINDOUBLE (1e-999)

Minimum floating point number for single precision (see notes about DMINEXP).


MINFLOAT

MINFLOAT Constant
values.h

#define MINFLOAT (1e-999)

Minimum floating point number for single precision.


vat.h

vat.h Header File
Header File Index

Routines for accessing the variable allocation table

Functions
$
Defines a constant VAT string.
AddSymToFolder
Adds a symbol in a given folder.
checkCurrent
Check for the existence of a symbol.
CheckLinkLockFlag
Prevents a variable to be overwritten through link transfer if this is not allowed.
CheckReservedName
Checks for graph functions and other special variable names.
CheckSysFunc
Checks for graph functions and other special variable names.
ClearUserDef
Clears TI-Basic program/function status flags.
DataTypeNames
Returns a pointer to a static string representing the type of the tag passed.
DerefSym
Dereferences a symbol.
EM_moveSymFromExtMem
Moves a symbol from the archive memory to the RAM.
EM_moveSymToExtMem
Moves a symbol from the RAM to the archive memory.
EM_twinSymFromExtMem
Creates a twin symbol, then copies a symbol from the archive memory to it.
EX_stoBCD
Stores a floating point value into a variable.
FindProgramVar
Finds the running program's variable.
FindSymInFolder
Finds a symbol in a given folder.
FolderAdd
Creates a folder.
FolderAddTemp
Creates a temporary folder.
FolderClear
Deletes all files in the folder.
FolderCount
Determines a number of symbols in a folder.
FolderCur
Sets the currently active folder.
FolderCurTemp
Sets the current temporary folder for storing local symbols.
FolderDel
Deletes a folder, including all files in it.
FolderDelAllTemp
Deletes a block of temporary folders.
FolderDelTemp
Deletes a temporary folder.
FolderFind
Checks whether a folder exists.
FolderGetCur
Determines the current active folder.
FolderOp
Locks or unlocks a folder table.
FolderRename
Renames a folder.
GetDataType
Returns the data type for a given tag pointed to by tagptr.
GetFuncPrgmBodyPtr
Returns a pointer to a TI-Basic function/program body.
GetTagStr
Returns the address of the string representing the special tag pointed to by tag.
HSymDel
Deletes a symbol pointed to by HSym.
HSYMtoName
Determines a full path of a symbol.
is_pathname
Checks if argument points to a pathname.
IsMainFolderStr
Checks whether a name is the name of the main folder.
MakeHSym
Makes a HSym structure.
partial_len
Queries information about the Data Editor.
QSysProtected
Checks if a given tag represents a system-protected variable type.
ResetSymFlags
Clears all VAT symbols flags.
SetOK
Changes the system variable 'OK'.
SmapTypeStrings
Returns the 3-4 character description of a variable type.
StrToTokN
Converts a C string to a token.
SymAdd
Adds a symbol.
SymAddMain
Adds a symbol in the main folder.
SymAddTwin
Creates a twin symbol.
SymCmp
Compares two symbol names.
SymCpy0
Copies a symbol name with putting zero byte at the end.
SymCpy
Copies a symbol name.
SymDel
Deletes a symbol.
SymDelTwin
Deletes a twin symbol.
SymFind
Finds a symbol.
SymFindFirst
Begins looping through the VAT.
SymFindFolderName
Returns an actual folder name during browsing through the VAT table.
SymFindHome
Finds a folder.
SymFindMain
Finds a symbol in the main folder.
SymFindNext
Finds the next entry in the VAT table.
SymFindPrev
Finds the previous entry in the VAT table.
SymFindPtr
Finds a symbol and returns a pointer to the VAT entry.
SymMove
Moves a symbol.
SYMSTR
Defines a VAT string.
SymSysVar
Checks for a system-reserved variable name.
TempFolderName
Creates a temporary folder name.
TokToStrN
Converts a token to a C string.
ValidateSymName
Checks for a valid VAT name symbol.
VarRecall
A higher-level variant of SymFind.
VarStore
High-level function to store values into variables.
Constants
H_NULL
A null-handle value.
HS_NULL
A null symbol constant.
NULL
A null-pointer value.
Predefined Types
Bool
An enumeration to describe true or false values.
CESI
Represents a pointer to a constant expression.
CompatFlags
An enumeration for describing possible compatibility flags in the SYM_ENTRY structure.
ESI
Represents an index of a value on the TIOS expression stack.
ESQ
Represents a quantum within an expression.
ExtendedSysTypes
Describes system variable types.
FindOptions
Describes options for SymFindFirst and FFindFirst.
FolderOpFlags
An enumeration for describing possible options for the FolderOp function.
FolderStats
An enumeration for describing possible results of the FolderFind function.
GraphModes
Describes different graphing modes.
HANDLE
Represents a handle associated with an allocated memory block.
HSym
A structure representing a symbol reference.
HSYM
An alias for HSym.
MULTI_EXPR
Describes a multi-expression, which is processed as a separate expression stack.
SYM_ENTRY
A structure representing a VAT symbol entry.
SYM_STR
Represents a pointer to the terminating zero byte of a string.
SymFlags
An enumeration for easy access to flags in VAT symbol entries.
SystemDataTypes
Describes valid variable types in the "Var-Link" dialog, and for the GetDataType and SmapTypeStrings functions.
VarRecallFlags
A collection of flags used in VarRecall.
VarStoreFlags
Describes possible flags for VarStore.


$

$ Function (Macro Constructor)
vat.h

#define $(s) (SYMSTR (#s))

Defines a constant VAT string.

This macro constructor has been superseded by the function-like macro SYMSTR.


AddSymToFolder

AddSymToFolder Function (ROM Call 0x70)
vat.h

HSym AddSymToFolder (SYM_STR SymName, SYM_STR FolderName);

Adds a symbol in a given folder.

AddSymToFolder acts like SymAdd, but adds the VAT entry in the folder given by FolderName. See SymAdd and SYMSTR for more info and rules about SymName and FolderName.

Note: This routine is a bit buggy: if the folder FolderName does not exist, the behavior of this routine is very uncertain, and may result with a crash.

Uses: DerefSym, FindSymInFolder, MakeHSym, SymCpy, HeapFree, HeapRealloc, memmove, _ds32s32
Used by: cmd_local, cmd_newdata, de_initRes, de_loop, InitDEMem, InitTimeSeq, push_user_func, recall_data_var, seqWebInit, spike_in_editor, spike_titles_in_editor, NG_setup_graph_fun


checkCurrent

checkCurrent Function (ROM Call 0x121)
vat.h

HSym checkCurrent (SYM_STR SymName, ESQ Type);

Check for the existence of a symbol.

checkCurrent makes sure the given symbol exists and matches the requested tag Type. SymName is the symbol name (see SYMSTR for rules about SymName), and Type is the requested tag type (see VarNew for a list of valid tags). checkCurrent returns the HSym of the VAT entry if it exists and matches the requested tag type, otherwise it returns HS_NULL. For example, the text editor uses checkCurrent when it is told to edit the current text variable, to make sure the previous name entered by the user still exists and is a text variable. If it is not then it executes the code to prompt the user for a new text variable to edit.

Uses: DerefSym, SymCmp, SymFind, SymFindMain, HToESI, ROM Call 0x45A
Used by: cmd_newdata, GetStatValue


CheckLinkLockFlag

CheckLinkLockFlag Function (ROM Call 0x7F)
vat.h

void CheckLinkLockFlag (const SYM_ENTRY *FuncSymEntry);

Prevents a variable to be overwritten through link transfer if this is not allowed.

If FuncSymEntry is a pointer to the VAT entry of TI-Basic program or function variable, then this function sets or clears the link lock flag which is embedded in the program or function variable itself, according to the 'archived' and 'locked' bits in the VAT entry. This prevents the variable to be overwritten through link transfer if this is not permitted. Otherwise this function does nothing.

Uses: HToESI
Used by: sendcalc


CheckReservedName

CheckReservedName Function (ROM Call 0x8B)
vat.h

short CheckReservedName (SYM_STR SymName);

Checks for graph functions and other special variable names.

CheckReservedName checks whether SymName is a graph function or another special variable name. It returns zero if this is not the case, otherwise it returns the type of the variable. This routine works in the same way as CheckSysFunc; the only differences are that SymName is a tokenized name, and that the function may also return R_SYSVAR.

Precisely, this function returns values from either GraphModes or ExtendedSysTypes, in addition to zero:

GR_FUNC | "y1".."y99"
GR_PAR | "xt1".."xt99", "yt1".."yt99"
GR_POL | "r1".."r99"
GR_SEQ | "u1".."u99"
GR_3D | "z1".."z99"
GR_DE | "y'1".."y'99"
SEQ_INITC | "ui1".."ui99"
DE_INITC | "yi1".."yi99"
DR_FLDPIC | "FldPic"
SOLVER_SYS_VARS | "Exp", "Eqn"
UNIT_VAR | name with a leading underscore
C_COL | "c1".."c99"
R_REGEQ | "RegEq"
R_SYSVAR | another system variable (see EXT_SYSTEM_TAG)

This function calls TokToStrN and CheckSysFunc.

Uses: CheckSysFunc, TokToStrN
Used by: cmd_local, push_parse_text, EQU_getNameInfo, GraphOrTableCmd, push_parse_prgm_or_func_text, tokenize_if_TI_92_or_text, VarStoreLink, ROM Call 0x437

See also: CheckSysFunc, SymSysVar


CheckSysFunc

CheckSysFunc Function (ROM Call 0x89)
vat.h

short CheckSysFunc (const char *VarName, unsigned short *Index);

Checks for graph functions and other special variable names.

CheckSysFunc checks whether VarName (an ordinary C string) is a graph function or another special variable name. It returns zero if this is not the case, otherwise it returns the type of the variable.

Precisely, this function returns values from either GraphModes or ExtendedSysTypes, in addition to zero:

GR_FUNC | "y1".."y99"
GR_PAR | "xt1".."xt99", "yt1".."yt99"
GR_POL | "r1".."r99"
GR_SEQ | "u1".."u99"
GR_3D | "z1".."z99"
GR_DE | "y'1".."y'99"
SEQ_INITC | "ui1".."ui99"
DE_INITC | "yi1".."yi99"
DR_FLDPIC | "FldPic"
SOLVER_SYS_VARS | "Exp", "Eqn"
UNIT_VAR | name with a leading underscore
C_COL | "c1".."c99"
R_REGEQ | "RegEq"

Note that ExtendedSysTypes also contains R_SYSVAR, which may be returned only by CheckReservedName. In fact, this function cannot check for system variable names like "xmin".

Also, if VarName is a valid graph function name or column name ("y1", "c1", etc.), CheckSysFunc stores the function/column index at the word pointed to by Index.

Uses: CTypeTable
Used by: CheckReservedName, FolderCur, SymFindPtr, SymSysVar, VarRecall, VarStore, cmd_archive, cmd_lock, cmd_movevar, cmd_newfold, cmd_unarchiv, cmd_unlock, VarOpen, ERD_process, sendcalc, ROM Call 0x437

See also: SymSysVar, CheckReservedName


ClearUserDef

ClearUserDef Function (ROM Call 0x7E)
vat.h

void ClearUserDef (HANDLE hFuncVar);

Clears TI-Basic program/function status flags.

This function assumes that hFuncVar is the handle of a TI-Basic program or function variable (otherwise the behavior is unpredicted). It clears various status flags which are embedded in the program or function variable itself, which include the link lock flag (see CheckLinkLockFlag), the entry counter (which counts the depth of recursive calls of a function or program), and some flags used in the "Graph" application.

Uses: HToESI
Used by: LIO_Receive, OSLinkCmd, VarStoreLink, ROM Call 0x438


DataTypeNames

DataTypeNames Function (ROM Call 0x43B)
AMS 2.00 or higher vat.h

unsigned char *DataTypeNames (unsigned char);

Returns a pointer to a static string representing the type of the tag passed.

On AMS 2.xx, the string is localized for the current language; on AMS 1.xx, the string is in English, because no language localizations are available.
Valid values for tag are a subset of Tags and InstructionTags:

EXT_SYSTEM_TAG (0x1C)
STR_TAG        (0x2D)
EQ_TAG         (0x87)
DATA_TAG       (0xDD)
GDB_TAG        (0xDE)
PIC_TAG        (0xDF)
TEXT_TAG       (0xE0)
FIG_TAG        (0xE1)
MAC_TAG        (0xE2)
ASM_TAG        (0xF3)
OTH_TAG        (0xF8)
FUNC_ITAG      (0x17)
PRGM_ITAG      (0x19)
If the tag is not allowed, the address of the string containing "?" is returned.

Uses: XR_stringPtr
Used by: VarNew, VarOpen, VarSaveAs


DerefSym

DerefSym Function (ROM Call 0x79)
vat.h

SYM_ENTRY *DerefSym (HSym Sym);

Dereferences a symbol.

DerefSym dereferences the symbol by converting Sym (which is return value from many TIOS VAT functions) into the actual VAT entry. DerefSym returns a pointer to the entry, which is a pointer to the structure of type SYM_ENTRY, which represents a VAT entry. Returns NULL in a case of error. Beware that VAT entries may moved during the heap compression, so SYM_ENTRY pointers may become invalid after the heap compession.

DerefSym may be simulated using HeapDeref. For example, the statement

SymPtr = DerefSym (hsym);
is equal to the statement
SymPtr = (SYM_ENTRY*)((char*)HeapDeref(hsym.folder) + hsym.offset);
I don't know what the best way to find the handle of the main folder is, but one method which is certainly legal is the following:
MainHandle = DerefSym(SymFindHome(SYMSTR("main")))->handle;
Note: SYM_ENTRY structures are usually not locked, which means that pointers to them will become invalid if a heap compression occurs. Basically, this means that you can only operate on them for a short time in which you know that no heap compression can occur.

Used by: AddSymToFolder, checkCurrent, EM_moveSymFromExtMem, EM_moveSymToExtMem, EM_twinSymFromExtMem, HSymDel, HSYMtoName, partial_len, VarRecall, VarStore, cmd_andpic, cmd_archive, cmd_blddata, cmd_custom, cmd_cyclepic, cmd_delfold, cmd_delvar, cmd_dialog, cmd_fill, cmd_get, cmd_local, cmd_lock, cmd_movevar, cmd_newdata, cmd_newpic, cmd_newprob, cmd_passerr, cmd_popup, cmd_rclpic, cmd_request, cmd_rplcpic, cmd_showstat, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_stogdb, cmd_toolbar, cmd_unarchiv, cmd_unlock, cmd_xorpic, push_csolve, push_czeros, push_gettype, push_max, push_min, push_nsolve, push_randpoly, push_solve, push_zeros, push_indir_name, ERD_process, push_internal_simplify, push_parse_text, handleRclKey, handleVarLinkKey, FClose, FDelete, FOpen, FSetVer, gdb_len, gdb_recall, gdb_store, OSLinkCmd, sendcalc, fopen, de_initRes, de_loop, delete_list_element, did_push_approx_inflection_point, did_push_var_val, does_push_fetch, dv_create_graph_titles, EQU_getNameInfo, EQU_select, EQU_setStyle, FindGrFunc, GetStatValue, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_add_fldpic, gr_ck_solvergraph, gr_de_value, gr_execute_seq, gr_remove_fldpic, gr_seq_value, gr_stopic, GT_Open, GT_SaveAs, InitDEMem, InitTimeSeq, NG_setup_graph_fun, push_parse_prgm_or_func_text, push_simplify, push_user_func, recall_data_var, seqWebInit, setup_more_graph_fun, spike_geo_titles, spike_in_editor, spike_optionD, statFree, store_data_var, tokenize_if_TI_92_or_text, VarStoreLink, ROM Call 0x437, ROM Call 0x438, ROM Call 0x45E, ROM Call 0x468, push_subscripted_element


EM_moveSymFromExtMem

EM_moveSymFromExtMem Function (ROM Call 0x161)
vat.h

short EM_moveSymFromExtMem (SYM_STR SymName, HSym Sym);

Moves a symbol from the archive memory to the RAM.

EM_moveSymFromExtMem unarchives an archived symbol. The symbol may be described either by symbol name SymName (in this case, parameter Sym should be set to HS_NULL) or by HSym structure Sym (in this case, SymName must be NULL). See SYMSTR for rules about SymName. EM_moveSymFromExtMem returns TRUE if the operation was successful, else returns FALSE.

Uses: DerefSym, SymFind, HeapAlloc, HeapSize, EM_write, memcpy


EM_moveSymToExtMem

EM_moveSymToExtMem Function (ROM Call 0x162)
vat.h

short EM_moveSymToExtMem (SYM_STR SymName, HSym Sym);

Moves a symbol from the RAM to the archive memory.

EM_moveSymToExtMem archives a symbol. The symbol may be described either by symbol name SymName (in this case, parameter Sym should be set to HS_NULL) or by HSym structure Sym (in this case, SymName must be NULL). See SYMSTR for rules about SymName. EM_moveSymToExtMem returns TRUE if the operation was successful, else returns FALSE.

Uses: DerefSym, HSYMtoName, SymFind, HeapFree, HeapSize, cmd_archive, HToESI, EM_findEmptySlot, EM_GC, EM_write, memcpy, memset, strchr, strncpy
Used by: cmd_archive, cmd_unarchiv


EM_twinSymFromExtMem

EM_twinSymFromExtMem Function (ROM Call 0x166)
vat.h

HSym EM_twinSymFromExtMem (SYM_STR SymName, HSym Sym);

Creates a twin symbol, then copies a symbol from the archive memory to it.

EM_twinSymFromExtMem first calls SymAddTwin to create a twin symbol, then copies the archived symbol to it. The symbol may be described either by symbol name SymName (in this case, parameter Sym should be set to HS_NULL) or by Hsym structure Sym (in this case, SymName must be NULL). See SYMSTR for rules about SymName. TIOS uses EM_twinSymFromExtMem when it need to execute archived program. EM_twinSymFromExtMem returns a HSym structure which represents a newly created symbol (or HS_NULL in a case of error). EM_twinSymFromExtMem returns Sym itself if the symbol is not archived.

Uses: DerefSym, HSYMtoName, SymAddTwin, SymFind, HeapAlloc, HeapFree, HeapSize, memcpy
Used by: push_user_func


EX_stoBCD

EX_stoBCD Function (ROM Call 0xC0)
vat.h

void EX_stoBCD (unsigned char *VarName, float *Src);

Stores a floating point value into a variable.

EX_stoBCD stores the floating point value pointed to by src into the TI-Basic variable whose name is pointed to by VarName (an ordinary C string).

Uses: StrToTokN, VarStore, memcpy


FindProgramVar

FindProgramVar Function (tigcc.a)
vat.h

SYM_ENTRY *FindProgramVar (void);

Finds the running program's variable.

FindProgramVar returns a pointer to the SYM_ENTRY structure of the running program, or NULL in case it is not found (e.g. if the program was compressed).

Note: Do not call anything which may cause a heap compression between when this function is called and when the pointer to it is used. Otherwise, the pointer may become invalid, causing a crash or other random, unexpected behavior. You can also use FolderOp to avoid this problem.

Uses: SymFindFirst, SymFindNext, HeapDeref, HeapSize


FindSymInFolder

FindSymInFolder Function (ROM Call 0x71)
vat.h

HSym FindSymInFolder (SYM_STR SymName, const char *FolderName);

Finds a symbol in a given folder.

FindSymInFolder acts like SymFind, but searches for a symbol in the folder given by FolderName. See SYMSTR for more info and rules about SymName and FolderName. As far as I know, the statement

hsym = FindSymInFolder (SYMSTR ("tetris"), SYMSTR ("games"));
acts exactly the same as the statement
hsym = SymFind (SYMSTR ("games\\tetris"));

Uses: IsMainFolderStr, MakeHSym, SymCmp, TokToStrN, ParseSymName, _mu16u16
Used by: AddSymToFolder, partial_len, VarRecall, cmd_blddata, cmd_cyclepic, cmd_local, push_indir_name, VarNew, VarSaveAs, push_parse_text, de_initRes, EQU_getNameInfo, GetStatValue, gr_find_de_result, push_parse_prgm_or_func_text, spike_in_editor, spike_titles_in_editor, store_data_var, store_func_def


FolderAdd

FolderAdd Function (ROM Call 0x64)
vat.h

HANDLE FolderAdd (SYM_STR SymName);

Creates a folder.

FolderAdd creates a new folder with name SymName. See SYMSTR for rules about SymName. FolderAdd returns a handle to the created folder (more precise, to the VAT variable list which belongs to the created folder). Returns H_NULL in a case of error (for example, the folder already exists, or there is not enough memory). Note that reserved names are not valid folder names and that this routine does not check for reserved names. It is up to the caller to validate the folder name before calling this routine. This routine may cause heap compression.

This routine also can be used to create temporary folders (see also FolderAddTemp) whose names begin with a number and are not displayed in VAR-LINK dialog. Temporary folder numbers '0001'...'8192' are reserved for keeping TI-BASIC local symbols, folder number '9998' is used in Data/Matrix Editor, and folder number '9999' is reserved for various temporary storage.

Uses: SymCmp, SymCpy, TokToStrN, HeapAlloc, HeapFree, HeapRealloc, memmove, _mu16u16, _ds32s32
Used by: FolderAddTemp, SymFindPtr, cmd_blddata, cmd_movevar, cmd_newfold, gr_openFolder

See also: FolderAddTemp, SymAdd


FolderAddTemp

FolderAddTemp Function (ROM Call 0x73)
vat.h

SYM_STR FolderAddTemp (void);

Creates a temporary folder.

FolderAddTemp creates a temporary folder whose name will consist of four digits (see TempFolderName). The first call of FolderAddTemp will create a folder named "0001", the next call will create a folder named "0002", etc. FolderAddTemp returns the name of the created folder, with the same convention as used in function TempFolderName. The created folder will be marked as the "current temporary folder" (see FolderCurTemp). FolderAddTemp throws a "Memory" error if there is not enough space for a new folder.

Uses: FolderAdd, FolderCurTemp, TempFolderName
Used by: push_user_func, NG_setup_graph_fun


FolderClear

FolderClear Function (ROM Call 0x66*)
vat.h

short FolderClear (SYM_STR SymName);

Deletes all files in the folder.

FolderClear deletes all files in the folder SymName, but does not remove the folder itself. Returns TRUE if the operation was successful, else returns FALSE (e.g. if the folder is not found). See SYMSTR for rules about SymName. Beware that this routine will delete all symbols in the folder even if they are locked, in use, or archived!

Note: This function calls original TIOS entry called "FolderDel", but passes an extra Boolean parameter set to TRUE. See also note given with FolderDel function.

See also: FolderDel


FolderCount

FolderCount Function (ROM Call 0x6B)
vat.h

unsigned short FolderCount (const SYM_ENTRY *SymPtr);

Determines a number of symbols in a folder.

FolderCount returns the number of symbols in the folder whose VAT entry is SymPtr. For example, to determine the number of symbols in the "main" folder, do the following:

number = FolderCount (DerefSym (SymFindHome (SYMSTR ("main"))));
See SYMSTR, SymFindHome, and DerefSym for more info.

Used by: FolderRename, handleVarLinkKey, LIO_Receive, OSLinkCmd


FolderCur

FolderCur Function (ROM Call 0x65)
vat.h

short FolderCur (SYM_STR SymName, short nonSys);

Sets the currently active folder.

FolderCur sets the currently active folder to SymName (see SYMSTR for rules about SymName). It returns TRUE if the operation was successful, else returns FALSE (e.g. if the folder name is invalid).

nonSys is a boolean flag which normally needs to be TRUE. If it is set to TRUE, FolderCur calls SymFindNext repeatedly until the first non-system variable in this folder is reached. This is necessary, else the current graph may become invalid. In particular, if the graph references a variable defined in a folder which previously was the current folder, it is not redrawn if nonSys is set to FALSE.

Note: The folder name in the status line will not be changed automatically using this command. You must change it manually using the function ST_folder from statline.h.

This routine may cause heap compression.

Uses: CheckSysFunc, SymCmp, SymCpy, SymCpy0, SymFindFirst, SymFindNext, TokToStrN, gr_active, gr_other, strcmp, statFree, _mu16u16
Used by: cmd_newfold, push_setfold, MO_digestOptions

See also: FolderGetCur, FolderCurTemp


FolderCurTemp

FolderCurTemp Function (ROM Call 0x72)
vat.h

short FolderCurTemp (SYM_STR SymName);

Sets the current temporary folder for storing local symbols.

FolderCurTemp sets the current temporary folder for storing local symbols to SymName. SymName must be a "numeric" symbol name as functions like TempFolderName or FolderAddTemp returns. FolderCurTemp returns TRUE if the operation was successful, else returns FALSE.

Uses: SymCmp, TokToStrN, CTypeTable, _mu16u16
Used by: FolderAddTemp, FolderDelTemp, recall_data_var

See also: FolderCur


FolderDel

FolderDel Function (ROM Call 0x66*)
vat.h

short FolderDel (SYM_STR SymName);

Deletes a folder, including all files in it.

FolderDel deletes the folder SymName including all files in it, and returns TRUE if the operation was successful, else returns FALSE (e.g. if the folder is not found). See SYMSTR for rules about SymName. If the folder SymName is the current folder, the new current folder after deleting will become the "main" folder. If the folder SymName is "main", then all symbols from it will be deleted, but the folder itself will remain intact. Beware that this routine will delete all symbols in the folder even if they are locked, in use, or archived!

Note: This function was buggy in TIGCCLIB releases prior to 2.3. I didn't know that the original TIOS entry called "FolderDel" requires in fact two parameters: another one is a Boolean flag. As this parameter was not passed before, the behaviour of this routine was random (see also FolderClear). Now, to keep the compatibility with already written programs, I modified FolderDel to always pass FALSE as an extra parameter (in this case, FolderDel behaves as described above; when it is TRUE, FolderDel behaves as FolderClear).

Uses: IsMainFolderStr, SymCmp, TokToStrN, HeapFree, HeapRealloc, ER_catch, ER_success, ER_throwVar, next_expression_index, push_parse_text, top_estack, EM_abandon, memmove, strcat, strchr, OSDisableBreak, OSEnableBreak, CheckGraphRef, statFree, _mu16u16, _ds32s32
Used by: FolderDelAllTemp, FolderDelTemp, cmd_blddata, handleVarLinkKey, LIO_Receive, OSLinkCmd, gr_del_vars_in_folder, gr_DelFolder

See also: FolderClear


FolderDelAllTemp

FolderDelAllTemp Function (ROM Call 0x75)
vat.h

void FolderDelAllTemp (short StartTempNum);

Deletes a block of temporary folders.

FolderDelAllTemp deletes all temporary folders whose names are series of consequent numbers starting from StartTempNum up to the first unused number, like in following algorithm:

current=StartTempNum;

while (FolderFind ((name = TempFolderName (current++))) == 3)
FolderDel (name);
The intention of this routine was very probably to delete all temporary folders when called with StartTempNum equals to 1. But, there is a problem. This routine does not reset the system variable which tells which is last used temporary folder number (I think that this is a bug in TIOS). So, a next call of FolderAddTemp will not start again from folder named "0001". This may cause various problems later. That's why I strongly recommend avoiding this routine, and using repeated call to FolderDelTemp instead.

Uses: FolderDel, TempFolderName
Used by: GR3_paint3d, de_initRes, de_loop, execute_graph_func, gr_execute_de, gr_execute_seq, InitTimeSeq, run_one_seq, seqWebInit


FolderDelTemp

FolderDelTemp Function (ROM Call 0x74)
vat.h

void FolderDelTemp (void);

Deletes a temporary folder.

FolderDelTemp deletes the last created temporary folder and selects the previous temporary folder as current temporary folder (see FolderCurTemp). Nothing bad will happen if the temporary folder does not exist, or in case of any eventual error.

Uses: FolderCurTemp, FolderDel, TempFolderName
Used by: push_user_func, seqWebInit, NG_setup_graph_fun, NG_cleanup_graph_fun


FolderFind

FolderFind Function (ROM Call 0x67)
vat.h

short FolderFind (SYM_STR SymName);

Checks whether a folder exists.

FolderFind searches for a folder SymName through the folder table in the VAT, and returns the following result:

  • MAIN_FOLDER, if SymName is the "main" folder;
  • FOLDER_TABLE, if a folder with name SymName exists;
  • NOT_FOUND, if a folder with name SymName does not exists;
  • BAD_FOLDER, if a symbol with name SymName is really present in the folder table, but does not represents a folder (i.e. folder bit is not set); this return value probably represents an invalid entry.
These constants are defined in enum FolderStats. See SYM_ENTRY for more info about structure of VAT entry, and SYMSTR for rules about SymName.

Uses: IsMainFolderStr, SymCmp, TokToStrN, _mu16u16
Used by: cmd_blddata, cmd_movevar, ROM Call 0x437


FolderGetCur

FolderGetCur Function (ROM Call 0x68)
vat.h

void FolderGetCur (char *buffer);

Determines the current active folder.

FolderGetCur fills buffer with a name of the current active folder. The buffer must be at least 9 bytes long, and it will be filled with a standard C zero-terminated string.

Uses: SymCpy0
Used by: push_setfold, handleVarLinkKey

See also: FolderCur


FolderOp

FolderOp Function (ROM Call 0x69)
vat.h

short FolderOp (SYM_STR SymName, short Flags);

Locks or unlocks a folder table.

FolderOp locks or unlocks a folder table which name is determined by SymName. Returns TRUE if the operation was successful, else returns FALSE. Parameter Flags may have following values (these constants are defined in enum FolderOpFlags):

FOP_UNLOCK | Unlocks a folder table
FOP_LOCK | Locks a folder table
FOP_ALL_FOLDERS | Locks/unlocks all folder tables (SymName is ignored); this value should be ORed with one of FOP_UNLOCK or FOP_LOCK

By locking the folder table, you may be sure that a dereferenced pointer to the table will remain valid even after a lot of heap memory allocations (i.e. a garbage collection will not move the table through memory).

Note: To lock the "home" folder (this is a pseudo-folder which contains all other folders in itself, i.e. this is the table of folders), you need to know that its name consists only of the character with code 0x7F (diamond). So, you can use

FolderOp (SYMSTR ("\x7F"), FOP_LOCK);
to do this.

Uses: SymCmp, TokToStrN, HeapLock, HeapUnlock, strcmp, _mu16u16
Used by: VarOpen, EV_defaultHandler, HomeExecute, VarCreateFolderPopup


FolderRename

FolderRename Function (ROM Call 0x6A)
vat.h

short FolderRename (const char *SrcName, const char *DestName);

Renames a folder.

FolderRename renames the folder SrcName to the name DestName. Returns TRUE if the operation was successful (SrcName must exist and must be a folder, and DestName must not exist), else returns FALSE. See SYMSTR for rules about folder names. Note that this routine does not check for reserved names, and may throw an error if renaming to or from a reserved name (e.g. "main"), or if any variable in the given folder is in-use.

Uses: FolderCount, IsMainFolderStr, SymCmp, SymCpy, TokToStrN, HeapRealloc, ER_catch, ER_success, ER_throwVar, next_expression_index, push_parse_text, top_estack, memmove, strcat, strchr, OSDisableBreak, OSEnableBreak, _mu16u16, _ds32s32
Used by: ROM Call 0x437


GetDataType

GetDataType Function (ROM Call 0x435*)
AMS 1.01 or higher vat.h

short GetDataType (CESI tagptr);

Returns the data type for a given tag pointed to by tagptr.

Valid values for the tag pointed to by tagptr are defined in the enum SystemDataTypes.

Uses: GetFuncPrgmBodyPtr
Used by: push_gettype, handleVarLinkKey, OSLinkCmd, sendcalc

See also: SmapTypeStrings, handleVarLinkKey


GetFuncPrgmBodyPtr

GetFuncPrgmBodyPtr Function (ROM Call 0x43A*)
vat.h

ESI GetFuncPrgmBodyPtr (ESI ptr);

Returns a pointer to a TI-Basic function/program body.

GetFuncPrgmBodyPtr returns the pointer to the function or program body of the TI-Basic function or program pointed to by ptr. ptr must point to the FUNC_TAG quantum, i.e. to the last byte of the variable. The parameters and flags are skipped. See Tags for more info on tags.

Uses: next_expression_index
Used by: GetDataType, VarOpen, handleRclKey


GetTagStr

GetTagStr Function (ROM Call 0x46C)
AMS 2.00 or higher vat.h

char *GetTagStr (ESI tag, char * buf);

Returns the address of the string representing the special tag pointed to by tag.

tag needs to point to one of EXT_SYSTEM_TAG (0x1C), EXT_TAG (0xE3) or EXT_INSTR_TAG (0xE4), otherwise garbage is returned.
Also, if you pass GetTagStr a tag unrecognized by the AMS version, it returns a pointer to 'ERROR'.

Example: The TI-BASIC command ShowStat prints the string name for each statistical variable it finds using GetTagStr to print the name of the variable as shown in this example.

unsigned char tag[2];
char buf[24];
char buf2[11];
tag[0] = X_BAR_TAG; // in fact, any tag defined in SysvarTags.
tag[1] = EXT_SYSTEM_TAG; // Defined in Tags
sprintf(buf,"%-7s",GetTagStr(tag+1,buf2));
You can use HToESI to get a pointer to the tag stored in tag.

Uses: strlen, XR_stringPtr
Used by: cmd_showstat, Parse2DExpr, Parse2DMultiExpr


HSymDel

HSymDel Function (ROM Call 0x5F)
vat.h

short HSymDel (HSym Sym);

Deletes a symbol pointed to by HSym.

HSymDel acts exactly like SymDel, except it takes a structure of type HSym as an input parameter instead of the symbol name (see SYMSTR).

Note: This routine assumes that Sym is valid; if it is not, it may throw an error (for example, if Sym represents a reserved symbol like "main", or if the referenced symbol is in-use). If HSymDel is called to delete a folder than that folder must be empty! Also do not use HSymDel to delete twin or archived variables. This routine modifies the VAT table, so it invalidates any other existing HSyms. The caller must be sure that the VAT table has not been changed since Sym was obtained.

Uses: DerefSym, IsMainFolderStr, HeapFree, HeapRealloc, ER_catch, ER_success, ER_throwVar, next_expression_index, push_parse_text, top_estack, memmove, strcat, strchr, OSDisableBreak, OSEnableBreak, CheckGraphRef, statFree, _ds32s32
Used by: cmd_blddata, cmd_delfold, cmd_delvar, cmd_newdata, cmd_newprob, FDelete, gdb_recall, OSLinkCmd, de_initRes, de_loop, gr_ck_solvergraph, gr_remove_fldpic, spike_in_editor, spike_titles_in_editor, ROM Call 0x438, ROM Call 0x45E

See also: SymFind


HSYMtoName

HSYMtoName Function (ROM Call 0x7A)
vat.h

short HSYMtoName (HSym Sym, char *buffer);

Determines a full path of a symbol.

HSYMtoName fills buffer with a full-path name (i.e. "folder\name") of the symbol given by HSym structure Sym. See SYMSTR for more info about HSym names. The buffer must be at least 18 bytes long, and it will be filled with a standard C zero-terminated string. HSYMtoName returns TRUE if the operation was successful, else returns FALSE.

Uses: DerefSym, SymCpy, SymCpy0, SymSysVar, strcat
Used by: EM_moveSymToExtMem, EM_twinSymFromExtMem, cmd_newdata, ValidateStore


is_pathname

is_pathname Function (ROM Call 0x3C6)
AMS 1.01 or higher vat.h

short is_pathname (CESI name);

Checks if argument points to a pathname.

name must be a valid SYM_STR constructed with SYMSTR or equivalent.
This function first checks if name is pointing to the last byte of a SYM_STR (it must be 0x00), and searches backwards for character 0x5C ('\'). If is_pathname finds one such character, it immediately retuns TRUE. If name doesn't point to a 0x00, or there is no '\' in the string, it returns FALSE.
Note: this function is flawed, as it doesn't check if there is only one '\'. Indeed, a string such as SYMSTR("main\foo\bar"), while it is a pathname (it contains '\'), is NOT a valid pathname...

Used by: EQU_getNameInfo, push_parse_prgm_or_func_text, cmd_local, push_parse_text, ROM Call 0x468


IsMainFolderStr

IsMainFolderStr Function (ROM Call 0x77)
vat.h

short IsMainFolderStr (const char *Name);

Checks whether a name is the name of the main folder.

IsMainFolderStr returns TRUE if Name is the string "main", else returns FALSE.

Uses: strcmp
Used by: FindSymInFolder, FolderDel, FolderFind, FolderRename, HSymDel, SymFindFolderName, VarRecall, VarStore, cmd_newfold, TokenizeSymName, handleVarLinkKey, ParseSymName


MakeHSym

MakeHSym Function (ROM Call 0x282)
vat.h

HSym MakeHSym (HANDLE FldHandle, const SYM_ENTRY *SymPtr);

Makes a HSym structure.

MakeHSym is an internal function, used very often in other TIOS routines. It converts the VAT symbol entry pointed to by SymPtr which belongs to the folder associated with handle FldHandle to the HSym structure. As HSym-s are basically a combination of the folder’s handle and the offset of a symbol into that folder, they are valid until a symbol is added or removed from the folder they belong to. Dereferencing them with DerefSym produces a direct pointer to the symbol entry, but such pointer are not valid after a heap compression is done. The main usage of MakeHSym is when you need to preserve a pointer to the symbol entry after a heap compression, like in following example:

hsym = MakeHsym (FldHandle, SymPtr);
// Something that may cause heap compression...
SymPtr = DerefSym (hsym);
In this example, an eventual heap compression would cause the pointer to be invalid since it is a direct pointer into memory. So the SymPtr is converted to a HSym structure with MakeHsym (along with the handle of the folder that the symbol belongs to). After the code that may cause heap compression is executed, the HSym is converted back into a SYM_ENTRY pointer with DerefSym.

Used by: AddSymToFolder, FindSymInFolder, SymAdd, SymAddMain, SymAddTwin, SymFind, SymFindHome, SymFindMain, VarRecall, VarStore

Deprecated alias: MakeHsym


partial_len

partial_len Function (ROM Call 0x11C)
vat.h

unsigned long partial_len (const char *VarName, unsigned char *MaxList);

Queries information about the Data Editor.

partial_len is used to query information about the temporary folder of the Data Editor ("9998", see FolderAdd), which contains three variables for each column:

"tc1".."tc99" | A STR variable containing the title for the column.
"hc1".."hc99" | An EXPR variable containing the formula for the column.
"c1".."c99" | A LIST variable containing the (fixed or calculated) cell values.

VarName must be "tc", "hc", or "c", and partial_len returns the size of all files matching VarName. It stores the last column which is used into the byte pointed to by MaxList.

Uses: DerefSym, FindSymInFolder, CharNumber
Used by: store_data_var


QSysProtected

QSysProtected Function (ROM Call 0x88)
vat.h

short QSysProtected (ESQ Tag);

Checks if a given tag represents a system-protected variable type.

QSysProtected returns TRUE if the given tag (see Tags for more info) is the tag of a system protected data type, i.e. a program/function (FUNC_TAG), assembly program (ASM_TAG), text file (TEXT_TAG), graph database (GDB_TAG), picture (PIC_TAG), data variable (DATA_TAG), or custom file (OTH_TAG). Otherwise, QSysProtected returns FALSE.

Used by: VarStore, cmd_fill, cmd_sorta, cmd_sortd, VarStoreLink, ROM Call 0x438

See also: VarStore


ResetSymFlags

ResetSymFlags Function (ROM Call 0x8E)
vat.h

void ResetSymFlags (unsigned short Flags);

Clears all VAT symbols flags.

Clears all VAT symbol flags (i.e. flags defined in the enum SymFlags) which are set in the Flags parameter, for all entries in the VAT table (i.e. in all folders).

Uses: SymFindFirst, SymFindNext
Used by: ERD_dialog, de_loop, execute_graph_func, GR_Pan, Regraph, run_one_seq, statFree


SetOK

SetOK Function (ROM Call 0x456*)
vat.h

void SetOK (short value);

Changes the system variable 'OK'.

If value is TRUE, 'OK' is set to 1; if it is FALSE, 'OK' is set to 0.

Uses: VarStore, Integer0Index, Integer1Index
Used by: cmd_dialog, cmd_request, cmd_showstat


SmapTypeStrings

SmapTypeStrings Function (ROM Call 0x436)
AMS 2.00 or higher vat.h

const char *SmapTypeStrings (short type);

Returns the 3-4 character description of a variable type.

SmapTypeStrings returns a string of three characters for the variable type represented by type. Valid values for type are defined in the enum SystemDataTypes; you can use GetDataType to convert a tag to such a type value.
NULL is returned if type is incorrect.

The value returned is the string displayed in the VAR-LINK dialog. This string is localized for the current language and can be up to four characters long. Note that files of type SDT_OTH will return a pointer to the string "OTH", and not to the true extension of the file.

Uses: strlen, XR_stringPtr
Used by: push_gettype, handleVarLinkKey

See also: GetDataType, handleVarLinkKey


StrToTokN

StrToTokN Function (ROM Call 0x7B)
vat.h

ESI StrToTokN (const char *src, unsigned char *dest);

Converts a C string to a token.

StrToTokN converts a symbol name pointed to by src, which is an ordinary ANSI C string, into a tokenized symbol name. See SYMSTR for more info about symbol names. dest must point to a buffer of 20 bytes (which is the maximum length of the expanded file name). The tokenized name is stored there starting at the end of the buffer. StrToTokN returns a pointer to the terminating zero byte of the converted name, exactly as expected in most routines from vat.h.

Note: This routine merely converts a name into tokenized format; it does not handle reserved names or check for the validity of the name passed to it. For this reason, TokenizeSymName should be used in general to tokenize symbol names.

Uses: strlen, CTypeTable
Used by: EX_stoBCD, VarNew, VarOpen, VarSaveAs, handleVarLinkKey, MO_digestOptions, FFindFirst, LIO_Receive, OSLinkCmd

See also: TokToStrN, SYMSTR


SymAdd

SymAdd Function (ROM Call 0x5C)
vat.h

HSym SymAdd (SYM_STR SymName);

Adds a symbol.

SymAdd creates a new entry in the variable allocation table (VAT) for a symbol called SymName, and returns the same type of result as the SymFind function. If the symbol SymName already exists, SymAdd deletes the old symbol before creating a new one (except if SymName is a folder name; this case is considered an error). In case of an error, SymAdd returns HS_NULL. This function may throw an error if the symbol already exists and it is locked. See SymFind and DerefSym for more info.

SymName may also contain a folder name together with the symbol name (separated by "\"). In this case, the symbol will be added in the given folder. If the given folder does not exist, a dialog will appear which asks the user whether a new folder will be created. If the answer is "NO", a "Folder" error will be thrown (beware that opening a dialog may change the system font, so the use of SaveScrState and RestoreScrState is highly recommended in all cases when you expect that a folder creation dialog might appear). If SymName does not contain a folder name, the symbol entry will be created in the current active folder. This routine does not check for reserved symbol names, so caution must be used when using this routine.

Note that SymAdd adds only an entry in the VAT with an empty handle; it does not allocate any space for the actual variable. To actually create a variable named "example", do the following (assuming that there were no errors in intermediate steps):

HSym hsym = SymAdd (SYMSTR ("example"));
// HeapAlloc must be executed before DerefSym
// because of possible garbage collection.
HANDLE handle = HeapAlloc (100);
SYM_ENTRY *SymPtr = (DerefSym (hsym));
MULTI_EXPR *VarPtr = HeapDeref (SymPtr->handle = handle);
Now, 100 bytes of space for the variable (together with the valid handle in the VAT entry) is created, and VarPtr points to it (see HeapAlloc and HeapDeref for more info). It does not mean that the actual length of the variable must be 100 bytes: it is only the allocated amount of memory. To create a concrete variable, you must fill the space pointed to by VarPtr with valid data which depends on the wanted type of the variable. The format of some variable types (STR, PIC, TEXT etc.) may be found on doors.ticalc.org. For example, to create a one-character long string variable with content "A", do the following:
VarPtr->Size = 4;            // length of the variable data
VarPtr->Expr[0] = 0;         // zero marks the beginning of the actual variable data
VarPtr->Expr[1] = 'A';       // actual data
VarPtr->Expr[2] = 0;         // end-of-string marker
VarPtr->Expr[3] = STR_TAG;   // the last byte is the type (see STR_TAG)
Note: It is very dangerous to add a new entry in the VAT without allocating a memory space, and without assigning the handle in the entry. I didn't check whether a real TI-89 crashes after this, but the debugger in VTI crashes!? Rusty, this is a bug...

Uses: MakeHSym, ROM Call 0x439
Used by: cmd_blddata, fopen

See also: SymAddMain, FolderAdd, MULTI_EXPR


SymAddMain

SymAddMain Function (ROM Call 0x5D)
vat.h

HSym SymAddMain (SYM_STR SymName);

Adds a symbol in the main folder.

SymAddMain acts like SymAdd, but adds the VAT entry in the main folder list, regardless of the current active folder, even if SymName contains the folder name together with the symbol name. See SymAdd for more info.

Uses: MakeHSym, ROM Call 0x439
Used by: VarStore, gr_add_fldpic

See also: SymAdd


SymAddTwin

SymAddTwin Function (ROM Call 0x27F)
vat.h

HSym SymAddTwin (SYM_STR SymName);

Creates a twin symbol.

SymAddTwin creates a twin entry in the variable allocation table (VAT) for an existing symbol SymName. A twin symbol is, in fact, another entry in the VAT with the same variable name, but with a different handle. The TIOS creates twin symbols during execution of archived programs, just in front of the normal symbol in the VAT table (see EM_twinSymFromExtMem). A twin symbol is "stronger" that a normal symbol, i.e. existence of a twin symbol temporary hides the symbol with the same name, until the twin symbol is deleted. Twin symbols have the "twin" bit set in the VAT entry (see SYM_ENTRY for the structure of a VAT entry), but in the VAR-LINK menu, it is shown as "archived". SymAddTwin returns the same result as SymAdd (HS_NULL in case of an error). If the symbol SymName does not exist, this is also an error.

Uses: MakeHSym, SymCpy, SymFindPtr, HeapRealloc, memmove, _ds32s32
Used by: EM_twinSymFromExtMem


SymCmp

SymCmp Function (ROM Call 0x81)
vat.h

short SymCmp (const char *s1, const char *s2);

Compares two symbol names.

SymCmp compares two symbol names by comparing at most 8 characters starting from addresses pointed to by s1 and s2. It returns the same result as strcmp. It seems that calling this function is equal to

strncmp (s1, s2, 8);
See strncmp for more info.

Used by: checkCurrent, FindSymInFolder, FolderAdd, FolderCur, FolderCurTemp, FolderDel, FolderFind, FolderOp, FolderRename, SymFindFirst, SymFindHome, SymFindPtr, handleVarLinkKey, GetStatValue


SymCpy0

SymCpy0 Function (ROM Call 0x83)
vat.h

void SymCpy0 (char *dest, const char *src);

Copies a symbol name with putting zero byte at the end.

SymCpy0 first performs SymCpy, then puts the zero byte in ninth byte of the string pointed to by dest (i.e. in dest[8]). So, dest must be at least 9 bytes long.

Uses: SymCpy
Used by: FolderCur, FolderGetCur, HSYMtoName, TokToStrN, VarOpen, handleVarLinkKey, LIO_Receive, OSLinkCmd, VarCreateFolderPopup, ROM Call 0x40E


SymCpy

SymCpy Function (ROM Call 0x82)
vat.h

void SymCpy (char *dest, const char *src);

Copies a symbol name.

SymCpy copies at most 8 characters from string src to dest, then fills rest of the dest up to 8 bytes, so dest must be at least 8 bytes long. It seems that calling this function is equal to

strncpy (dest, src, 8);
except in the fact that function SymCpy is void. See strncpy for more info.

Used by: AddSymToFolder, FolderAdd, FolderCur, FolderRename, HSYMtoName, SymAddTwin, SymCpy0, handleVarLinkKey, ROM Call 0x439


SymDel

SymDel Function (ROM Call 0x5E)
vat.h

short SymDel (SYM_STR SymName);

Deletes a symbol.

SymDel deletes the symbol SymName and returns TRUE if the operation was successful, else returns FALSE. See SYMSTR for rules about SymName. Note that this routine will delete symbols even if they are locked or in use! Do not call SymDel to delete a folder, or twin or archived symbols (for these purposes, see FolderDel and SymDelTwin).

Note: Do not call SymDel to delete twin symbols. Instead, use the SymDelTwin function.

Uses: SymFindPtr, HeapFree, HeapRealloc, memmove, CheckGraphRef, statFree, _ds32s32
Used by: SymMove, VarStore, cmd_stogdb, handleVarLinkKey, LIO_Receive, OSLinkCmd, fopen, unlink, gr_del_locals, GraphOrTableCmd, GT_SaveAs, ROM Call 0x438


SymDelTwin

SymDelTwin Function (ROM Call 0x280)
vat.h

short SymDelTwin (SYM_ENTRY *SymPtr);

Deletes a twin symbol.

SymDelTwin deletes a twin symbol (see SymAddTwin for more info about twin symbols) whose VAT entry is SymPtr. Returns TRUE if the operation was successful, else returns FALSE.

When the TIOS deletes a twin symbol, the current value of the flags SF_GREF1, SF_GREF2, and SF_STATVAR are copied from the twin symbol to the original symbol.

Note: Since the TIOS is not able to get the folder handle with only the SYM_ENTRY structure, it reads the folder address, the number of files in this folder, and the maximum number of files in the folder from the global variables used by SymFindFirst and related functions. If the program changes these variables (for example by simply using SymFindFirst) or if it adds or deletes a symbol in the VAT by itself without using SymAdd and SymDel, SymDelTwin will cause severe data corruption.

The solution is simple: Always call SymFindPtr with the complete name of the twin symbol before calling SymDelTwin; passing 0 to its Flags parameter. Samuel Stearley says that calling LoadSymFromFindHandle after finding the symbol with SymFindFirst and SymFindNext works as well. (However, do not call SymDel to delete twin symbols.)

Uses: HeapFree, HeapRealloc, memmove, _ds32s32, ROM Call 0x5CA
Used by: cmd_archive, cmd_unarchiv, EV_eventLoop, LIO_Receive, OSLinkCmd


SymFind

SymFind Function (ROM Call 0x60)
vat.h

HSym SymFind (SYM_STR SymName);

Finds a symbol.

SymFind searches the variable allocation table (VAT) for a symbol (i.e. variable) SymName. SymName may also contain a folder name together with the symbol name (separated by "\"), else only the currently active folder will be searched. SymFind returns a structure of type HSym, which contains the handle of the variable table list belonging to the folder (current, or folder given in the name), and the offset from the beginning of the list to the actual VAT symbol entry. Use DerefSym to get a pointer to the actual VAT symbol entry instead. In case of an error (for example, if the symbol does not exist), SymFind returns HS_NULL. Note that most reserved symbols (i.e. system variables) are not stored in the VAT table, so you cannot locate them using SymFind.

Note: SymName is not an ordinary C string. Instead, this is a sequence of characters which starts with the zero character ('\0') and terminates with the zero character as well, and all TIOS routines for VAT handling need a pointer to the terminating zero byte as the input argument, which is a little twisty. So, to search for a symbol named "tetris", instead of

hsym = SymFind ("tetris");
you must do the following:
hsym = SymFind ("\0tetris"+7);
To make this job easier, the macro SYMSTR is implemented, so you may simply do
hsym = SymFind (SYMSTR ("tetris"));
You may use the older $ macro constructor as well.

Note also that all legal TIOS symbol names must be in lowercase!

Uses: MakeHSym, SymFindPtr
Used by: checkCurrent, EM_moveSymFromExtMem, EM_moveSymToExtMem, EM_twinSymFromExtMem, cmd_blddata, cmd_newdata, cmd_newprob, ERD_process, fopen, de_initRes, de_loop, gr_de_value, gr_execute_seq, gr_seq_value, Regraph, time_loop, ROM Call 0x45E

See also: SymFindMain, SymFindHome, SymFindPtr


SymFindFirst

SymFindFirst Function (ROM Call 0x6C)
vat.h

SYM_ENTRY *SymFindFirst (SYM_STR SymName, unsigned short Flags);

Begins looping through the VAT.

SymFindFirst searches for the first symbol entry in the variable allocation table which satisfies the requirements given by the parameters Flags and SymName (see SYMSTR for information about symbol names), and sets some internal pointers so that SymFindNext and SymFindPrev may be called to traverse the VAT. SymName is required only for some values of Flags (you can set it to NULL otherwise). Flags is a collection of binary flags defined in the enum FindOptions. These flags also determine how subsequent calls of SymFindNext and SymFindPrev will be interpreted.

If Flags is 0 (i.e. no flags are given), SymFindFirst and subsequent calls to SymFindNext and SymFindPrev loop only through the list of folders. In this case, SymName is ignored.

The following flags are defined:

FO_RECURSE | Loop through all folders including their symbols. Naturally, SymName is still ignored. Subsequent calls to SymFindNext will continue searching through the whole variable allocation table, including both the folder table and the variable tables associated with each folder. More precisely, after each folder, the complete variable table for this folder will be browsed before the next folder is reached. This flag can be used together with all other flags except FO_SINGLE_FOLDER and FO_RETURN_FOLDER.
FO_SKIP_TEMPS | Skip temporary folders when looping through the folder table. See FolderAddTemp for more information about temporary folders. This flag cannot be used together with FO_SINGLE_FOLDER, obviously.
FO_SKIP_COLLAPSE | Skip variables in collapsed folders. Folders can be collapsed only since AMS 2.00; therefore this flag has no effect if the AMS version is lower than 2.00 (but it is still defined). This flag can only be used if FO_RECURSE is set as well.
FO_RETURN_TWINS | Return the temporarily hidden equivalents of twin entries in the archive as well, which is normally not the case. See SymAddTwin for more information about twin entries. Of course, this does not have any effect if neither FO_RECURSE nor FO_SINGLE_FOLDER are included in Flags (i.e. if only folder names are returned).
FO_SINGLE_FOLDER | Loop through all symbols in the folder identified by SymName, but do not return the folder name itself. This flag may be used together with FO_RETURN_FOLDER and FO_RETURN_TWINS, but not with any other flag.
FO_RETURN_FOLDER | This flag can only be set if FO_SINGLE_FOLDER is set as well. It slightly alters the meaning of FO_SINGLE_FOLDER so that SymFindFirst returns the SYM_ENTRY structure of the folder identified by SymName, and subsequent calls to SymFindNext will return all symbols in that folder.

SymFindFirst returns the pointer to the symbol entry in the VAT, or NULL if there are no symbols which satisfy the given requirements. Here is an example how to (legally) create a list of all variable names in the main folder:

counter = 0;
SymPtr = SymFindFirst (SYMSTR ("main"), FO_SINGLE_FOLDER);
while (SymPtr)
{
  strcpy (names[counter++], SymPtr->name);
  SymPtr = SymFindNext ();
}
If you want to create a list of all folder names, simply change
SymPtr = SymFindFirst (SYMSTR ("main"), FO_SINGLE_FOLDER);
in the previous example to
SymPtr = SymFindFirst (NULL, 0);
Note: Since this routine and subsequent calls to SymFindNext and SymFindPrev return direct pointers to the symbol table, heap compression will cause subsequent results to be invalid or may crash the system. In other words, heap compression will invalidate all pointers returned necessitating another call to SymFindFirst. Therefore locking the folder table (using FolderOp) during the complete operation is highly recommended.

Uses: SymCmp, TokToStrN, strcmp, _mu16u16
Used by: FindProgramVar, FolderCur, ResetSymFlags, HeapWalk, VarOpen, LoadDLL, ERD_process, EV_defaultHandler, EV_eventLoop, handleVarLinkKey, FFindFirst, HomeExecute, LIO_Receive, OSLinkCmd, VarCreateFolderPopup, gr_del_locals, Regraph, ROM Call 0x40D

See also: SymFindNext, SymFindPrev, SymFindFolderName


SymFindFolderName

SymFindFolderName Function (ROM Call 0x6F)
vat.h

char *SymFindFolderName (void);

Returns an actual folder name during browsing through the VAT table.

This routine is used only when you search the complete VAT table using functions SymFindFirst, SymFindNext and SymFindPrev with FO_RECURSE in Flags set. Each time when a folder is encountered in the VAT table, the TIOS stores its name in an internal buffer. Later, when you go through the variable part of the VAT table, you can call this routine to retrieve the stored folder name, i.e. to get the name of the folder for the symbol just returned. Under any other conditions, SymFindFolderName just returns a pointer to the string "main".

See HeapWalk for an example using this function.

Uses: IsMainFolderStr, ER_catch, ER_success, ER_throwVar, next_expression_index, push_parse_text, top_estack, strcat, strchr, OSDisableBreak, OSEnableBreak
Used by: HeapWalk, ERD_process, LIO_Receive, OSLinkCmd

Deprecated alias: SymFindFoldername


SymFindHome

SymFindHome Function (ROM Call 0x62)
vat.h

HSym SymFindHome (SYM_STR SymName);

Finds a folder.

SymFindHome searches the folder table part of variable allocation table (VAT) for a folder named SymName (in fact, it searches through a pseudo-folder called "home", which contains all other folders). SymFindHome returns a structure of type HSym, which contains the handle of the folder table list of the VAT, and the offset from the beginning of the list to the actual VAT symbol entry. Use DerefSym to get a pointer to the actual VAT symbol entry instead. In case of an error (for example, if the folder does not exist), SymFindHome returns HS_NULL.

Note: I don't know what kernels do to find the handle of the folder list, but as far as I know, the only legal method is the following:

FolderListHandle = SymFindHome(SYMSTR("main")).folder;

Uses: MakeHSym, SymCmp, ParseSymName, _mu16u16
Used by: cmd_delfold

See also: SymFind


SymFindMain

SymFindMain Function (ROM Call 0x61)
vat.h

HSym SymFindMain (SYM_STR SymName);

Finds a symbol in the main folder.

SymFindMain acts like SymFind, but searches only the main folder, regardless of the currently active folder, even if SymName contains a folder name together with the symbol name. See SymFind for more info. It is useful for searching some symbols such as the system reserved equations ("Y1"..."Y99", "RegEq", etc.) which are always stored in the "main" folder and cannot be moved to a different folder.

Uses: MakeHSym, SymFindPtr
Used by: checkCurrent, VarStore, cmd_blddata, cmd_sinreg, gdb_len, gdb_recall, gdb_store, de_initRes, dv_create_graph_titles, EQU_select, EQU_setStyle, FindGrFunc, GM_Derivative, GM_DistArc, GM_Inflection, GM_Integrate, GM_Intersect, GM_Math1, GM_TanLine, gr_add_fldpic, gr_ck_solvergraph, gr_remove_fldpic, GT_SelFunc, GT_Trace, InitTimeSeq, seqWebInit, spike_geo_titles, spike_optionD, statFree

See also: SymFind


SymFindNext

SymFindNext Function (ROM Call 0x6D)
vat.h

SYM_ENTRY *SymFindNext (void);

Finds the next entry in the VAT table.

SymFindNext searches for the next symbol entry in the VAT table after calling SymFindFirst. The exact behavior of SymFindNext depends on the parameters passed to SymFindFirst. See the description of SymFindFirst for more information and examples of usage.

SymFindNext returns a pointer to the symbol entry in the VAT, or NULL if there are no more entries in the VAT which satisfy the given requirements.

Used by: FindProgramVar, FolderCur, ResetSymFlags, HeapWalk, VarOpen, LoadDLL, ERD_process, EV_defaultHandler, EV_eventLoop, handleVarLinkKey, FFindNext, HomeExecute, LIO_Receive, OSLinkCmd, VarCreateFolderPopup, gr_del_locals, ROM Call 0x40D

See also: SymFindFirst, SymFindPrev


SymFindPrev

SymFindPrev Function (ROM Call 0x6E)
vat.h

SYM_ENTRY *SymFindPrev (void);

Finds the previous entry in the VAT table.

SymFindPrev is very similar to SymFindNext, but instead of the next entry in the VAT, SymFindPrev searches for the previous entry in the VAT.

Normally the only routine used with SymFindFirst is SymFindNext, but this routine allows a program to traverse the symbol table in both directions. For example, the VAR-LINK dialog uses this routine to present a scrollable list of all symbols without having to maintain a separate list in memory.

Used by: handleVarLinkKey

See also: SymFindFirst, SymFindNext


SymFindPtr

SymFindPtr Function (ROM Call 0x283)
vat.h

SYM_ENTRY *SymFindPtr (SYM_STR SymName, unsigned short Flags);

Finds a symbol and returns a pointer to the VAT entry.

SymFindPtr acts like SymFind and related functions, but instead of a HSym structure, it returns a pointer to the actual VAT entry. SymFindPtr returns NULL in case of an error. So, it acts somewhat as a combination of SymFind and DerefSym.

Flags is an additional argument which determines the searching method. It is a set of binary flags. The exact meaning of these flags are still unknown for me, but at the moment, I know the following for sure:

  • If Flags = 0, the search is performed like using the SymFind function (i.e. through current or given folder);
  • If Flags = 4, the search is performed like using the SymFindMain function (i.e. through main folder only).
What I also know is that if b15 in Flags is set, the search is somewhat related to the folder list, and it is possible to search for folders as well. But I still can't conclude the exact meaning of these flags. So, instead of giving uncertain information, I will stop here. Everything about this function presented so far is certainly true. Fortunately, the TIOS set of VAT functions is rich enough so that eventual additional possibilities of this function may be simulated using other known functions. Any additional information will be welcomed, if someone knows more than me.

As an example of usage, this is a legal method how to lock a variable named "tetris":
SymFindPtr(SYMSTR("tetris"),0)->flags.bits.locked = 1;
See SYMSTR for info about symbol names.

Uses: CheckSysFunc, FolderAdd, SymCmp, DlgMessage, XR_stringPtr, ParseSymName, _mu16u16
Used by: SymAddTwin, SymDel, SymFind, SymFindMain, SymMove, VarRecall, VarStore, GraphOrTableCmd, ROM Call 0x439

See also: SymFind, SymFindMain, SymFindHome


SymMove

SymMove Function (ROM Call 0x63)
vat.h

short SymMove (SYM_STR SrcName, SYM_STR DestName);

Moves a symbol.

SymMove moves the symbol SrcName to the symbol DestName (see SymFind for rules about SrcName and DestName). Both SrcName and DestName may also contain a folder name together with the symbol name (separated by "\"). If none of the names does not contain a folder name, moving will be simply reduced to renaming. If the destination folder does not exist, a dialog will appear which asks the user whether a new folder will be created. If the answer is "NO", a "Folder" error will be thrown. Destination symbol will be deleted before moving, if such symbol exists. SymMove returns TRUE if the operation was successful, else returns FALSE. This function will even move and rename locked and archived files; however, upon a reset, they will return to the original name and/or folder.

Note: Check whether SrcName exists before applying this command, because the destination symbol DestName (if exists) will be deleted even in a case of an error!

Uses: SymDel, SymFindPtr, CheckGraphRef, ROM Call 0x439
Used by: cmd_movevar, rename, ROM Call 0x437


SYMSTR

SYMSTR Function (Macro)
vat.h

SYM_STR SYMSTR (const char *s);

Defines a VAT string.

Most of the TIOS functions which take symbol names as parameters do not accept ordinary C strings. Instead, the symbol name is either a variable tag or a sequence of characters which starts with the zero character ('\0') and terminates with the zero character as well, and the TIOS routines for VAT handling need a pointer to the terminating zero byte as the input argument, which is a little twisty. For example, to search for a symbol named "tetris", instead of

hsym = SymFind ("tetris");
you have to do the following:
hsym = SymFind ("\0tetris"+7);
To make this job easier, the SYMSTR macro is implemented, so you may simply do
hsym = SymFind (SYMSTR ("tetris"));
If the argument passed to SYMSTR is a string literal as in this case, SYMSTR simply expands to the sequence in the second example. This is an optimization done by the preprocessor. In all other cases, space for a temporary string is allocated on the stack using alloca, and the string is copied to this location on the stack. Strictly speaking, SYMSTR does not return a pointer of type SYM_STR in this case, but rather a pointer to non-constant data. This means that you may write to it if you wish.

Note that this macro doesn't check whether s is valid or not. If you need to tokenize a variable string and want to be sure that s is valid, you can use the TokenizeSymName routine.

Note: You cannot create tokens for system variables using this macro. See EXT_SYSTEM_TAG for more information. And if you want to use a single-character variable name, you can usually use one of the variable tags from the enum Tags. Note also that all legal TIOS symbol names must be in lowercase.

Uses: alloca, memcpy, strlen

See also: TokenizeSymName


SymSysVar

SymSysVar Function (ROM Call 0x8C)
vat.h

short SymSysVar (const char *VarName);

Checks for a system-reserved variable name.

SymSysVar checks if a variable pointed to by VarName (an ordinary C string) is a system-reserved variable stored in the symbol table (in the main folder). It returns the same values as CheckSysFunc. Additionally, it returns R_SYSVAR if the variable name is "SysData" or "RegCoef". In fact, this function calls CheckSysFunc with additional checks for "SysData" and "RegCoef".

Uses: CheckSysFunc, strcmp
Used by: HSYMtoName, cmd_movevar, VarNew, VarOpen, VarSaveAs, TokenizeSymName, handleVarLinkKey, getcalc, OSLinkCmd, sendcalc

See also: CheckSysFunc, CheckReservedName


TempFolderName

TempFolderName Function (ROM Call 0x76)
vat.h

SYM_STR TempFolderName (unsigned short TempNum);

Creates a temporary folder name.

TempFolderName converts the number TempNum in a four-digit string which corresponds to the given number (i.e. 12 will be converted into "0012"). This string will begin with '\0' character, and TempFolderName will return a pointer to the terminating '\0' character, as expected by many TIOS VAT routines (see SymAdd for more info about symbol names). TIOS will accept such "numeric" folder names, but they are invisible for the TI-Basic system, VAR-LINK menu, etc. TIOS creates and uses such folders for storing local variables during execution of TI-Basic programs.

Uses: sprintf
Used by: FolderAddTemp, FolderDelAllTemp, FolderDelTemp, VarRecall, cmd_cyclepic, cmd_local, push_indir_name, push_parse_text, de_initRes, de_loop, EQU_getNameInfo, gr_del_locals, InitDEMem, InitTimeSeq, push_parse_prgm_or_func_text, recall_data_var, Regraph, store_func_def


TokToStrN

TokToStrN Function (ROM Call 0x7C)
vat.h

short TokToStrN (unsigned char *dest, SYM_STR src);

Converts a token to a C string.

TokToStrN converts the VAT symbol name pointed to by src into an ordinary ANSI C string. See SYMSTR for more info about symbol names. src should point to the terminating zero byte of the name (or to a one-letter variable tag), and the result will be stored in the buffer pointed to by dest. The buffer has to be at least 20 bytes long. TokToStrN returns TRUE if the symbol could be converted, and FALSE if src does not point to a tag that represents a variable or is a reserved variable name.

Uses: SymCpy0, strncpy, primary_tag_list
Used by: CheckReservedName, FindSymInFolder, FolderAdd, FolderCur, FolderCurTemp, FolderDel, FolderFind, FolderOp, FolderRename, SymFindFirst, GraphOrTableCmd, VarSaveTitle

See also: StrToTokN


ValidateSymName

ValidateSymName Function (ROM Call 0x84)
vat.h

short ValidateSymName (const char *VarName);

Checks for a valid VAT name symbol.

Checks whether the ANSI C string pointed to by VarName may be a valid name of a VAT symbol (i.e. a TI-Basic variable), and returns TRUE if it can, or FALSE otherwise. This function checks for valid characters, and for a maximum length of eight characters.

Uses: CTypeTable
Used by: cmd_cyclepic, push_setfold


VarRecall

VarRecall Function (ROM Call 0x85)
vat.h

HSym VarRecall (SYM_STR SymName, unsigned short Flags);

A higher-level variant of SymFind.

VarRecall works like SymFind, but it is able to handle system variables which do not have an entry in the variable allocation table. SymName is a pointer to the terminating zero byte of the VAT variable name (see SYMSTR for more info about symbol names). Flags is a collection of flags defined in the enum VarRecallFlags:

VR_NO_SYS_VARS | Do not return system variables.
VR_FUNC_NAME | Accept strings terminating with an opening parenthesis (like "y1(") for SymName.
VR_LINK | Used only internally by the link code.

Note that you cannot create the necessary token for system variables with the SYMSTR or $ macro. Instead, system variables have their own tags. For example, to recall the system variable called "xmin", you have to use the following code:

hsym = VarRecall ((const ESQ []){XMIN_TAG, EXT_SYSTEM_TAG} + 1, 0);
You may use the TokenizeSymName function if you need a generic way to access variables, like this:
TokenizeSymName ("xmin", TSF_ALLOW_RESERVED);
hsym = VarRecall (top_estack, 0);
To make the handling of system variables consistent with normal variables even though system variables do not have an entry in the variable allocation table, VarRecall returns a reference to a dummy SYM_ENTRY if a system variable is requested. It actually copies the contents of the system variable into an internal buffer and adds the appropriate tag. Since one dummy entry is used for many system variables, you have to store the contents of each variable in your program if you need to access more than one value at a time.

In other words, a dummy HSym descriptor which is created for system variabes is shared by all variables not in the VAT. Thus the next call to VarRecall for such a variable will return the same descriptor, but with a different value (and the previous descriptor will be invalid). So if VarRecall is used for system variables, it is best to keep a copy of the value pointed to by the HSym if it is needed.

It might be useful to know (but it is not reliable) that internally, the folder field of the returned HSym contains a handle to the following type of structure:
struct SysVarSym {
  unsigned short DataSize;
  ESQ Data[60];
  SYM_ENTRY sysVar;
  SYM_ENTRY tblInput;
  SYM_ENTRY unit;
};
The offset field is then either 62 for system variables (offset to the sysVar field), 76 for the "tblInput" variable (offset to the tblInput field), or 90 for units (offset to the unit field). The reason that three different SYM_ENTRY type fields are used is that they contain different flags and handles. sysVar and unit both contain the same handle as the folder field of the HSym, whereas tblInput contains a handle to an external memory location. The compatibility flag is CF_NONE for system variables (including "tblInput"), but CF_NEW for units. All three fields contain the SF_LOCKED flag.

If the SYM_ENTRY structures use the same handle as the folder field of the HSym returned by VarRecall, they use in fact the first 62 bytes of this internal structure. This saves a handle in the operating system.

When dealing with system variables and units, it is not reliable to use the name field of the SYM_ENTRY structure whose address is obtained with DerefSym (which is, of course, one of the three structures mentioned above). It is blank for all system variables and units except "tblInput".

Note: This function may throw different errors. Especially, most system variables cannot be used in a function that is being graphed, either because they change too often or because they are used by the graph routines themselves (for example, "xmin" or "xc"). If these variables are accessed while graphing, VarRecall throws an error. However, locked variables may be looked up with VarRecall.

Uses: CheckSysFunc, DerefSym, FindSymInFolder, IsMainFolderStr, MakeHSym, SymFindPtr, TempFolderName, RemainingArgCnt, HToESI, next_expression_index, push_expression, push_Float, push_quantum, top_estack, gr_active, gr_flags, memcpy, strcmp, XR_stringPtr, is_transfinite, round14, CTypeTable, EV_currentApp, gr_find_de_result, gr_find_func_index, ParseSymName, sysvar_tag_list
Used by: cmd_andpic, cmd_archive, cmd_custom, cmd_cyclepic, cmd_delvar, cmd_dialog, cmd_fill, cmd_get, cmd_lock, cmd_movevar, cmd_passerr, cmd_popup, cmd_rclgdb, cmd_rclpic, cmd_request, cmd_rplcpic, cmd_showstat, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_toolbar, cmd_unarchiv, cmd_unlock, cmd_xorpic, push_csolve, push_czeros, push_gettype, push_max, push_min, push_nsolve, push_randpoly, push_solve, push_zeros, VarOpen, push_internal_simplify, handleRclKey, handleVarLinkKey, FDelete, FOpen, OSLinkCmd, sendcalc, delete_list_element, did_push_approx_inflection_point, did_push_var_val, does_push_fetch, GetStatValue, push_simplify, push_user_func, ROM Call 0x437, ROM Call 0x438, ROM Call 0x468, push_subscripted_element


VarStore

VarStore Function (ROM Call 0x86)
vat.h

HSym VarStore (SYM_STR SymName, unsigned short Flags, unsigned short Size, ...);

High-level function to store values into variables.

VarStore performs many storing operations, from basic file saving to list/matrix element access. Although some of its operations appear to be quite trivial, it provides a consistent interface to all storing operations, even for system variables. So, this is the general system routine for storing to TI-Basic variables.

VarStore can perform different types of operations. It can store values into TI-Basic variables (it will create a new VAT entry if needed), prepare variables to be stored to, or store individual values to elements of a list or matrix. The data type and domain of system variables are verified to be correct.

SymName is the symbol name of the variable in which the value will be stored (see SYMSTR for more info about symbol names). VarStore returns the HSym descriptor of the TI-Basic variable, or HS_NULL if the variable is a system variable (which is not stored in the VAT).

Note that you cannot create the necessary token for system variables with the SYMSTR or $ macro. Instead, system variables have their own tags. For example, to store something in the system variable xmin, you have to use the following code:

VarStore ((const ESQ []){XMIN_TAG, EXT_SYSTEM_TAG} + 1, ...);
You may use the TokenizeSymName function if you need a generic way to access variables.

The parameter Flags determines the meaning of the remaining parameters:

STOF_ESI | An extra parameter of type ESI is needed, which points to an expression which will be stored into the variable. Basically, this parameter may point to an arbitrary locked block of memory, not necessarily on the expression stack. On a side note, this variant is used internally if RETURN_VALUE <variable> is defined.
STOF_HESI | Like STOF_ESI, but the extra parameter has the type HANDLE. It must be a handle to a block of memory containing the data to be stored. The handle will be locked during the operation.
STOF_ELEMENT | Three extra parameters are needed. The first extra parameter has the type ESI; it should point to an expression which will be stored into an element of a list or matrix variable determined by the SymName parameter. The second and third parameters have the type unsigned short. For matrices, they determine the column and the row of the element, respectively. For lists, the second extra parameter is the index and the third parameter must be zero. Indices for both matrices and lists start at one.
STOF_NONE | Nothing is assumed about the source, so no copying is done (it is left to the caller). Only the VAT entry will be created. The name and flags and other conditions will be verified.

Additionally, the parameter Flags may contain some tag values (see Tags for more info). The allowed tags are USERFUNC_TAG (in this case an extra parameter of type ESI should point to the user function which will be stored; note that this is not FUNC_TAG), TEXT_TAG (for text variables), GDB_TAG (for Graph Database variables), PIC_TAG (for picture variables), DATA_TAG (for data variables), and OTH_TAG (for custom type variables). In all of these cases except USERFUNC_TAG, the destination is verified to have the same type as the source, but the copy operation is not done. There are more possible values for Flags, but they are used only for internal purposes in the TIOS.

The parameter Size is the size of the source data including the tag but not the size word stored in the heap. If Size is zero, then the size of the expression pointed to by the first extra parameter will be used (this is allowed if Flags is STOF_ESI, STOF_HESI, or STOF_ELEMENT). Otherwise, the new variable is not allocated, but the folder field in the returned HSym descriptor may still not be H_NULL if previous data existed in that variable).

Note: VarStore may throw various errors, and may cause heap compression (garbage collection). For example, some VAT variables are system protected (see QSysProtected). These include programs and functions (TI-Basic or ASM), data variables, graph databases, custom type files, pictures, and text variables. Only variables of the same type can be copied to a system-protected variable. If the variable name already exists, the lock flag is checked (a variable that is locked or archived cannot be overwritten; VarStore throws an error in this case). System variables cannot be locked and some system variables cannot be changed by the user. VarStore also checks the SF_HIDDEN flag in the VAT entry (see the SYM_ENTRY structure for more info), which is actually an "in-use" flag. Any variable being used by an application cannot be overwritten except by that application (it cannot be deleted, renamed, or linked, either). The in-use count is verified to be 0 for functions and programs.

If the variable is not a system variable, locked, system protected, or in use, a value can be stored to it no matter what it contained before. However, there are type restrictions on individual elements of lists or matrices. Usually, VarStore makes sure there is enough memory left to store the new contents to the variable before deleting the current contents of the variable. When storing to an existing variable, both graph reference flags are tested (SF_GREF1 and SF_GREF2). If one or both is set, the corresponding dirty graph and dirty table flag(s) are set to indicate the graph and table are no longer valid. Storing to an individual element or submatrix of a matrix or list does the same checks as for an existing variable, and updates the length. In addition, the data type of the element needs to be correct (expression, relation, string).

Only functions with the correct function arguments can be stored in the variables reserved as system functions. These are y1(x)...y99(x), xt1(t)...xt99(t), yt1(t)...yt99(t), r1(q)...r99(q), u1(n)...u99(n), y1'(t)...y99'(t), and z1(x,y)...z99(x,y). They can be single-line or multi-line functions, but an error is returned if the user tries to create any other data type with those names or if the number of arguments is incorrect. Since they are system functions, they cannot be locked and must be in the main folder. Empty functions are not valid and should not be added to the symbol table. This is true for user functions as well.

Uses: CheckSysFunc, DerefSym, IsMainFolderStr, MakeHSym, QSysProtected, SymAddMain, SymDel, SymFindMain, SymFindPtr, HeapAlloc, HeapFree, HeapLock, HeapRealloc, ER_throwVar, HToESI, next_expression_index, gr_active, gr_flags, gr_other, memcpy, memmove, strcmp, NeedStack, XR_stringPtr, round12_err, ck_valid_float, CTypeTable, EV_currentApp, ForceFloat, gen_version, GetSysGraphRef, OO_GetAppAttr, ParseSymName, primary_tag_list, statFree, _bcd_math, ROM Call 0x3E8, ROM Call 0x439, sysvar_tag_list, ROM Call 0x5C5
Used by: EX_stoBCD, SetOK, cmd_blddata, cmd_clrerr, cmd_dialog, cmd_endtry, cmd_fill, cmd_get, cmd_input, cmd_inputstr, cmd_newdata, cmd_newpic, cmd_popup, cmd_prompt, cmd_request, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_stogdb, cmd_try, VarNew, VarSaveAs, EV_defaultHandler, FOpen, gdb_recall, assign_between, de_initRes, de_loop, delete_list_element, gr_stopic, InitDEMem, InitTimeSeq, push_user_func, recall_data_var, spike_in_editor, spike_titles_in_editor, store_data_var, store_func_def, store_to_subscripted_element, ValidateStore, VarStoreLink, ROM Call 0x438


HS_NULL

HS_NULL Constant
vat.h

#define HS_NULL ((HSym) {0, 0})

A null symbol constant.

HS_NULL is a null symbol. Many TIOS functions returns such a symbol in case of an error. Note that you can't check whether a some variable is HS_NULL using the "==" operator because HS_NULL is not scalar, i.e. you can't write something like

if (hs == HS_NULL) ...
Instead, check the folder field of HSym structure: if it is zero, the whole structure is HS_NULL, because TIOS never creates HSym structures in which the folder field is zero and the offset field is nonzero.


CompatFlags

CompatFlags Type (Enumeration)
vat.h

enum CompatFlags {CF_NONE = 0, CF_CONVERT = 1, CF_ENHANCED = 2, CF_NEW = 3};

An enumeration for describing possible compatibility flags in the SYM_ENTRY structure.


ExtendedSysTypes

ExtendedSysTypes Type (Enumeration)
vat.h

enum ExtendedSysTypes {SEQ_INITC = 7, DE_INITC = 8, DE_FLDPIC = 9, SOLVER_SYS_VARS = 10, UNIT_VAR = 11, C_COL = 12, R_REGEQ = 13, R_SYSVAR = 14};

Describes system variable types.

This is an enumeration describing system variables which are not included in the types described in GraphModes from gdraw.h. It is currently used only in CheckReservedName.


FolderOpFlags

FolderOpFlags Type (Enumeration)
vat.h

enum FolderOpFlags {FOP_UNLOCK = 0, FOP_LOCK = 1, FOP_ALL_FOLDERS = 0x80};

An enumeration for describing possible options for the FolderOp function.


FolderStats

FolderStats Type (Enumeration)
vat.h

enum FolderStats {MAIN_FOLDER = 2, FOLDER_TABLE = 3, NOT_FOUND = 4, BAD_FOLDER = 5};

An enumeration for describing possible results of the FolderFind function.


HSYM

HSYM Type (Structure)
vat.h

#define HSYM HSym

An alias for HSym.

HSYM is an alias for HSym, to achieve compatibility between different programs.


SymFlags

SymFlags Type (Enumeration)
vat.h

enum SymFlags {SF_GREF1 = 0x0001, SF_GREF2 = 0x0002, SF_STATVAR = 0x0004, SF_LOCKED = 0x0008, SF_HIDDEN = 0x0010, SF_OPEN = 0x0010, SF_CHECKED = 0x0020, SF_OVERWRITTEN = 0x0040, SF_FOLDER = 0x0080, SF_INVIEW = 0x0100, SF_ARCHIVED = 0x0200, SF_TWIN = 0x0400, SF_COLLAPSED = 0x0800, SF_LOCAL = 0x4000, SF_BUSY = 0x8000};

An enumeration for easy access to flags in VAT symbol entries.

SymFlags is an enumeration for easy access to flags in VAT symbol entries represented by the SYM_ENTRY structure.

See SYM_ENTRY for more info.


VarRecallFlags

VarRecallFlags Type (Enumeration)
vat.h

enum VarRecallFlags {VR_NO_SYS_VARS = 0x01, VR_FUNC_NAME = 0x02, VR_LINK = 0x04};

A collection of flags used in VarRecall.

VarRecallFlags is an enumeration describing possible flags used in the VarRecall function.


VarStoreFlags

VarStoreFlags Type (Enumeration)
vat.h

enum VarStoreFlags {STOF_ESI = 0x4000, STOF_ELEMENT = 0x4001, STOF_NONE = 0x4002, STOF_HESI = 0x4003};

Describes possible flags for VarStore.

VarStoreFlags is an enumeration describing flags used in the VarStore function. Only one of these flags may be used at a time.


version.h

version.h Header File
Header File Index

Constants describing the version number of GCC4TI

Constants
__TIGCC__
The GCC4TI major version number, like __GNUC__.
__TIGCC_BETA__
The GCC4TI beta version number; 0 in the official release.
__TIGCC_MINOR__
The GCC4TI minor version number, represented by a two-digit decimal number.
__TIGCC_SP__
The GCC4TI service pack number; 0 in most cases.
__TIGCC_VERSION__
The full GCC4TI version number, as an integer value concatenating __TIGCC__ and __TIGCC_MINOR__.
__TIGCC_VERSION_STRING__
A string constant describing the GCC4TI version number in a unified format.
__TIGCCLIB__
The GCC4TI Library major version number.
__TIGCCLIB_MINOR__
The GCC4TI Library minor version number, represented by a two-digit decimal number.
__TIGCCLIB_SP__
The GCC4TI Library service pack number; 0 in most cases.
__TIGCCLIB_VERSION__
The full GCC4TI library version number, as an integer value concatenating __TIGCCLIB__ and __TIGCCLIB_MINOR__.
__TIGCCLIB_VERSION_STRING__
A string constant describing the GCC4TI Library version number in a unified format.

You can embed the version strings into your program by defining the preprocessor symbol EMBED_VERSION_STRINGS before including this header file or tigcclib.h.

If you want to check whether a program is compiled with TIGCC/GCC4TI, you cannot use the __TIGCC__ macro, since this header file does not exist in other libraries. For this reason, there is a global preprocessor symbol __TIGCC_ENV__.


__TIGCC__

__TIGCC__ Constant
version.h

The GCC4TI major version number, like __GNUC__.


__TIGCC_BETA__

__TIGCC_BETA__ Constant
version.h

The GCC4TI beta version number; 0 in the official release.


__TIGCC_MINOR__

__TIGCC_MINOR__ Constant
version.h

The GCC4TI minor version number, represented by a two-digit decimal number.


__TIGCC_SP__

__TIGCC_SP__ Constant
version.h

The GCC4TI service pack number; 0 in most cases.


__TIGCC_VERSION__

__TIGCC_VERSION__ Constant
version.h

The full GCC4TI version number, as an integer value concatenating __TIGCC__ and __TIGCC_MINOR__.


__TIGCC_VERSION_STRING__

__TIGCC_VERSION_STRING__ Constant
version.h

A string constant describing the GCC4TI version number in a unified format.


__TIGCCLIB__

__TIGCCLIB__ Constant
version.h

The GCC4TI Library major version number.


__TIGCCLIB_MINOR__

__TIGCCLIB_MINOR__ Constant
version.h

The GCC4TI Library minor version number, represented by a two-digit decimal number.


__TIGCCLIB_SP__

__TIGCCLIB_SP__ Constant
version.h

The GCC4TI Library service pack number; 0 in most cases.


__TIGCCLIB_VERSION__

__TIGCCLIB_VERSION__ Constant
version.h

The full GCC4TI library version number, as an integer value concatenating __TIGCCLIB__ and __TIGCCLIB_MINOR__.


__TIGCCLIB_VERSION_STRING__

__TIGCCLIB_VERSION_STRING__ Constant
version.h

A string constant describing the GCC4TI Library version number in a unified format.


wingraph.h

wingraph.h Header File
Header File Index

Routines for windowed graphics

Functions
BitmapSizeExt

DrawStaticButton
Draws a button in a window.
DrawWinBorder
Draws a border of a window.
MakeWinRect
Builds a structure for representing rectangular area.
RectWinToScr
Converts relative to absolute coordinates then clips them to a window.
RectWinToScrExt
Converts relative to absolute coordinates then clips them to a window, taking into account negative coordinates.
RectWinToWin
Converts relative window coordinates to absolute coordinates.
SetWinClip
Changes the clipping area of a window.
WinActivate
Activates a window.
WinAttr
Sets the default window attribute.
WinBackground
Sets the default window background.
WinBackupToScr
Shows a current backup screen.
WinBegin
Setup a window for writing to without activating the window.
WinBeginPaint
Saves the current screen state of given window, and prepares the settings for drawing in the LCD memory.
WinBitmapGet
Gets a bitmap from a window.
WinBitmapPut
Puts a bitmap to a window.
WinBitmapSize
Determines a size of a bitmap (eventually clipped) in bytes.
WinBitmapSizeExt
Determines a size of a bitmap (eventually clipped) in bytes, taking into account negative coordinates.
WinChar
Draws a character to a window.
WinCharXY
Draws a series of characters to a window at the specific location.
WinClose
Closes a window.
WinClr
Clears a window.
WinDeactivate
Deactivates a window.
WinDupStat
Turns the duplicate status on or off.
WinEllipse
Draws an ellipse to a window.
WinEnd
Ends writing to a non-active window.
WinEndPaint
Restores the screen state saved with WinBeginPaint in given window.
WinFill
Draws a filled rectangle to a window.
WinFillLines2
Draws a filled area between two lines to a window.
WinFillTriangle
Draws a filled triangle to a window.
WinFont
Sets the current window font.
WinGetCursor
Returns the cursor location for a window.
WinHeight
Height of a window.
WinHide
Hides a window.
WinHome
Moves the pen location for a window to the home position.
WinLine
Draws a line to a window.
WinLineExt
Draws a line to a window, more accurately than WinLine when clipping.
WinLineNC
Draws a line to a window, without range checking.
WinLineRel
Draws a line to a window from the current pen position, using relative displacements.
WinLineTo
Draws a line to a window from the current pen position.
WinMoveCursor
Moves the pen position (???).
WinMoveRel
Sets the current window pen position relative to the previous position.
WinMoveTo
Sets the current window pen position.
WinOpen
Opens a new window.
WinPixGet
Gets the status of a pixel in a window.
WinPixSet
Sets a pixel in a window.
WinRect
Draws a rectangle to a window.
WinRemove
Closes the window pointed to by w, and frees the memory assigned to that window.
WinReOpen
Reopens an existing window.
WinScrollH
Shifts a region of a window left or right.
WinScrollV
Scrolls a region of a window upwards or downwards.
WinSetCursor
Moves the cursor (???).
WinShow
Makes a window visible for the repainting routine.
WinStr
Draws a string to a window.
WinStrXY
Draws a string to a window at a specific location.
WinStrXYWrap
Draws a word-wrapped string to a window at position x, y (window-based), and returns the height in pixels of the text drawn.
WinToScr
Converts a WIN_RECT into a SCR_RECT, clipping the coordinates if necessary.
WinWidth
Width of a window.
Global Variables
DeskTop
A pointer to the desktop window.
FirstWindow
A pointer to the head of the list of all windows.
Constants
BITMAP_HDR_SIZE
Defines the size of the header of the BITMAP structure.
NULL
A null-pointer value.
Predefined Types
Attrs
An enumeration for describing legal attribute values.
BITMAP
A structure for defining a bitmap.
Bool
An enumeration to describe true or false values.
BoxAttrs
An enumeration for describing addittional box attribute values.
Buttons
An enumeration to describe possible button types.
Fonts
An enumeration for describing legal font values.
HANDLE
Represents a handle associated with an allocated memory block.
ICON
A structure which describes an icon.
pICON
A pointer to the ICON scructure.
SCR_COORDS
An alias type for defining physical screen coordinates.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
WIN_COORDS
An alias type for defining logical screen coordinates.
WIN_RECT
A structure for defining a rectangular area.
WINDOW_AMS1
The main window-describing structure (AMS 1.xx version).
WINDOW
The main window-describing structure.
WinFlags
An enumeration for describing flags which control the window manager.
winWriteFlags
Enumeration for parameter flags to WinStrXYWrap.

See also: graph.h


BitmapSizeExt

BitmapSizeExt Function (ROM Call 0x3ED)
AMS 2.00 or higher wingraph.h

unsigned short BitmapSizeExt (const WIN_RECT *WinRect);

This identifier has not been documented yet. Please help us out.

Used by: WinBitmapSizeExt

See also: CalcBitmapSize


DrawStaticButton

DrawStaticButton Function (ROM Call 0x35)
wingraph.h

void DrawStaticButton (WINDOW *w, short ButtonType, short x);

Draws a button in a window.

DrawStaticButton draws a button at the bottom of the window pointed to by w, where x is distance (in pixels) from the left edge of the window to the left edge of the button. Parameter ButtonType determines the type of the button. The set of possible types is very limited, and they are defined in enum Buttons (any other values will cause a crash). The meanings of these constants are:

BT_OK | Button "Enter=OK"
BT_SAVE | Button "Enter=SAVE"
BT_YES | Button "Enter=YES"
BT_CANCEL | Button "Esc=CANCEL"
BT_NO | Button "ESC=NO"
BT_GOTO | Button "Enter=GOTO"

Note: The current font (set using WinFont) must be F_4x6 for this function to work correctly.

Uses: MakeWinRect, WinRect, WinStrXY, ROM Call 0x4D5
Used by: assert, cmd_showstat, ERD_dialog, EV_defaultHandler, EV_quit


DrawWinBorder

DrawWinBorder Function (ROM Call 0x27)
wingraph.h

void DrawWinBorder (WINDOW *w, SCR_RECT *rect);

Draws a border of a window.

DrawWinBorder is an internal function which draws a border of the window, and optionally a title bar. The actual dimensions of the border are given in the SCR_RECT structure rect, but all other parameters (border shape, etc.) will be picked from the structure pointed to by w. Not very useful as a standalone function, although may be sometimes used in combination with WinBackupToScr. Note that you can pass &w.Window as the rect parameter.

Uses: DrawClipRect, DrawLine, DrawStr, DrawStrWidth, FontSetSys, LineTo, MoveTo, ScrRectFill, ScrToWin, SetCurAttr, SetCurClip
Used by: WinActivate, WinClr, WinDeactivate, WinRemove, ABT_dialog, handleVarLinkKey, HomeExecute, paint_all_except, UpdateWindows


RectWinToScr

RectWinToScr Function (ROM Call 0x2A)
wingraph.h

SCR_RECT *RectWinToScr (const SCR_RECT *win_area, const WIN_RECT *rect, SCR_RECT *result_area);

Converts relative to absolute coordinates then clips them to a window.

RectWinToScr first converts coordinates in the structure rect (which are assumed to be relative to the topleft corner of the structure win_area) to the absolute screen coordinates. Converted rectangular area is then clipped at the boundaries of the rectangular area win_area, and coordinates of resulting rectangular area are stored to the structure pointed to by result_area. RectWinToScr returns result_area. If converted rectangular area does not overlap with win_area, result_area will be undefined, and RectWinToScr returns NULL.

Used by: WinFill, Dialog


RectWinToScrExt

RectWinToScrExt Function (ROM Call 0x415)
AMS 2.00 or higher wingraph.h

SCR_RECT *RectWinToScrExt (const SCR_RECT *win_area, const WIN_RECT *rect, SCR_RECT *result_area);

Converts relative to absolute coordinates then clips them to a window, taking into account negative coordinates.

Used by: WinBitmapSizeExt, WinBitmapGet

See also: RectWinToScr


RectWinToWin

RectWinToWin Function (ROM Call 0x29)
wingraph.h

WIN_RECT *RectWinToWin (const SCR_RECT *win_area, WIN_RECT *rect);

Converts relative window coordinates to absolute coordinates.

RectWinToWin converts coordinates in the structure rect (which are assumed to be relative to the topleft corner of the structure win_area) to the absolute screen coordinates. The converted coordinates are stored again in structure pointed to by rect. RectWinToWin returns rect back (but note that the structure pointed to by it is modified).

Used by: WinFillLines2, WinLine, WinLineNC, WinLineTo, WinRect, WinLineExt


SetWinClip

SetWinClip Function (ROM Call 0x42E)
AMS 2.00 or higher wingraph.h

void SetWinClip (WINDOW *w, SCR_RECT *s);

Changes the clipping area of a window.

SetWinClip changes the clipping area of the window pointed to by w, to the SCR_RECT pointed to by s, and changes the contents of s from window-based to screen-based coordinates.

The original coordinates in s must be window-based, i.e (0,0) is the upper left corner of the window.

Uses: ClientToScr


WinActivate

WinActivate Function (ROM Call 0x1)
wingraph.h

void WinActivate (WINDOW *w);

Activates a window.

WinActivate makes the window pointed to by w the current active window. This will cause the following events:

  • The currently active window will be deactivated (its border will be changed to a single-line border);
  • The border for the window will switch to a double-line border (except in single-border mode, in rounded-border mode or if the window is a full-screen window);
  • The graphics system will be reset to the current windows defaults (draw attributes, current (x, y) location, etc.).
  • The window will be marked as visible (see WinHide).
See WinOpen for more info.

Note: Because of memory requirements, only the active window may be drawn to. Once a window becomes the active window, it may use any of the window drawing routines. If you try to draw in a non-active window, a garbage may appear on the screen. If no other window overlaps a window (even if there are multiple windows on the screen), then you may write to a non-active window by using WinBegin and WinEnd to bracket the writes.

Uses: DrawWinBorder, FirstWindow, WinClr, WinDeactivate, FontSetSys, UpdateWindows
Used by: cmd_disp, cmd_disphome, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, cmd_showstat, Dialog, ERD_dialog, ABT_dialog, EV_defaultHandler, handleVarLinkKey, HomeExecute, HelpKeys, ERD_notice, EV_quit


WinAttr

WinAttr Function (ROM Call 0x2)
wingraph.h

short WinAttr (WINDOW *w, short Attr);

Sets the default window attribute.

WinAttr sets the attribute for the next write (or draw) to the window pointed to by w to Attr. This attribute will be used in all drawing commands which have not an attribute as explicite parameter. The interpretation of the attribute depends of concrete graphic command. Some attributes are only valid for certain graphic operation. Legal attribute values are defined in enum Attrs. In a general, the following attributes are supported:

A_REVERSE | Destination pixels turned off
A_NORMAL | Destination pixels turned on
A_XOR | Source pixels XORed with destination pixels
A_SHADED | Destination pixels masked so that every other pixel turned off
A_REPLACE | Source pixels replace destination pixels
A_OR | Source pixels ORed with destination pixels

For lines the following additional attributes are supported:

A_THICK1 | Draw a double thick line
A_SHADE_V | Draw the line using a vertical shading pattern
A_SHADE_H | Draw the line using a horizontal shading pattern
A_SHADE_NS | Draw the line using a negative slope diagonal shading pattern
A_SHADE_PS | Draw the line using a positive slope diagonal shading pattern

WinAttr returns the previous current attribute.

Note: Although TI said nothing about it, attributes A_SHADE_V, A_SHADE_H, A_SHADE_NS and A_SHADE_PS work only for lines with slope more than 45 degree (i.e. for lines which are more "vertical" than "horizontal"). For "nearly horizontal" lines all of them act like A_NORMAL. I don't know whether it is a bug, or planned feature. So, if you want to draw shaded-fill rectangle using a line drawing command (for example, WinLine) in a loop, use vertical lines for drawing, not horizontal ones! Note also that these additional attributes work fine with WinFillTriangle and WinFillLines2, but not with WinFill!

Used by: cmd_circle, cmd_disp, cmd_line, cmd_linehorz, cmd_linevert, cmd_output, cmd_pause, cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pttext, cmd_pxlchg, cmd_pxlcircle, cmd_pxlhorz, cmd_pxlline, cmd_pxloff, cmd_pxlon, cmd_pxltext, cmd_pxlvert, cmd_shade, Dialog, ERD_dialog, ABT_dialog, EV_defaultHandler, handleVarLinkKey, GD_Pen, GD_Text, GR3_paint3d, HomeExecute, ST_eraseHelp, ST_modKey, TE_open, TE_openFixed, ERD_notice, EV_quit, FuncLineFlt, GM_Integrate, GM_Shade, gr_DispLabels, GR3_addContours, GR3_handleEvent, GrLineFlt, GT_BackupToScr, GT_DspMsg, GT_DspTraceCoords, GT_KeyIn, GT_ShowMarkers, GT_Trace, Regraph, YCvtFtoP, ROM Call 0x45B


WinBackground

WinBackground Function (ROM Call 0x4)
wingraph.h

void WinBackground (WINDOW *w, short Attr);

Sets the default window background.

WinBackground changes the current default attribute for the background of a window pointed to by w (used to clear the window using WinClr). Note that the background attribute is also used to fill up a newly created area when a window content is scrolled in any direction. Valid values for Attr are:

A_NORMAL | Black background
A_REVERSE | White background
A_XOR | All pixels will be reversed during clearing

See WinAttr for more info about attributes.

Note: TI said that attribute A_SHADED (set to a pattern of pixels on and off) is also supported, but it didn't work when I tried it; at least, it does not work on AMS 1.00.

Used by: cmd_pause


WinBackupToScr

WinBackupToScr Function (ROM Call 0x3)
wingraph.h

void WinBackupToScr (WINDOW *w);

Shows a current backup screen.

If the window pointed to by w is active, WinBackupToScreen copies the current backup screen (duplicate screen) to the real screen (more precise, to the client area of the window), else does nothing. This routine assumes that a window is opened with the WF_DUP_SCR flag (see WinOpen). Then, all output to that window is saved in a backup screen image (allocated in the heap). So, this routine copies the contents of that image to the real screen.

Uses: BitmapPut
Used by: cmd_disp, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, GR3_paint3d, HomeExecute, GR3_handleEvent, GT_BackupToScr

See also: DrawWinBorder


WinBegin

WinBegin Function (ROM Call 0x5)
wingraph.h

void WinBegin (WINDOW *w);

Setup a window for writing to without activating the window.

WinBegin setup the window pointed to by w for writing to it without activating it. When writing to the window is done, call WinEnd. See WinActivate for more info.

Uses: FontSetSys
Used by: HomeExecute, TE_focus, TE_handleEvent, TE_open, TE_openFixed, TE_pasteText, TE_select, TE_unfocus


WinBeginPaint

WinBeginPaint Function (ROM Call 0x500)
AMS 2.00 or higher wingraph.h

void WinBeginPaint (WINDOW *w);

Saves the current screen state of given window, and prepares the settings for drawing in the LCD memory.

WinBeginPaint just saves the current screen state in w->savedScrState, executes PortRestore and sets the current font to w->CurFont. So, emulating it on AMS 1.xx is easy.
WinBeginPaint is always paired with WinEndPaint which restores the screen state.
WinBeginPaint is commonly used to respond a CM_ACTIVATE message.

Uses: FontSetSys, PortRestore, SaveScrState
Used by: EV_quit, EV_defaultHandler

See also: WinEndPaint


WinBitmapGet

WinBitmapGet Function (ROM Call 0x6)
wingraph.h

short WinBitmapGet (WINDOW *w, const WIN_RECT *rect, void *BitMap);

Gets a bitmap from a window.

WinBitmapGet stores a series of bytes (the size of which is defined by WinBitmapSize) defining a bitmap for a rectangular area (whose boundaries are given using WIN_RECT structure rect) into a buffer pointed to by BitMap. All coordinates are relative to the topleft corner of the window pointed to by w. Actual stored bitmap may be smaller than area defined by rect due to clipping on the boundaries of the clipping area of the window.

The first two words at address BitMap will contain the height and the width (in pixels) of the rectangular area respectively (after eventual clipping), then actual data follows. BitMap is usually a pointer to a BITMAP structure. WinBitmapGet returns FALSE if the region defined by rect is outside of the window, and returns TRUE if it is partially or entirely inside the window.

Uses: WinBitmapSizeExt, WinToScr, BitmapGet, ClientToScr, PortRestore, ScrRectOverlap, ROM Call 0x3EC, ROM Call 0x413
Used by: cmd_newpic, gr_stopic, GT_SaveAs


WinBitmapPut

WinBitmapPut Function (ROM Call 0x7)
wingraph.h

void WinBitmapPut (WINDOW *w, short x, short y, void *BitMap, short Attr);

Puts a bitmap to a window.

WinBitmapPut puts a bitmap BitMap (which was taken using WinBitmapGet) to the window pointed to by w at the position (x, y), using the attribute Attr. The coordinates are relative to the topleft corner of the window pointed to by w. The drawn bitmap will be clipped at the boundaries of the clipping area of the window. The following attributes are supported:

A_REPLACE | Replace the destination region with the source bitmap
A_REVERSE | Replace the destination region with the inverse of the source bitmap
A_XOR | Exculsive-OR the source bitmap into the destination region
A_OR | OR the source bitmap into the destination region
A_AND | AND the source bitmap into the destination region
A_SHADED | Mask the source bitmap so that every other pixel is turned off and replace the destination region with that result (the source region is left unchanged)

See WinAttr command for a more general info about attributes.

Uses: BitmapPut, PortRestore, ROM Call 0x413
Used by: cmd_andpic, cmd_cyclepic, cmd_rclpic, cmd_rplcpic, cmd_xorpic, EV_defaultHandler, GD_Eraser, EV_quit, GS_PlotAll, GT_Open, GT_WinCursor, Regraph, ROM Call 0x45B


WinBitmapSize

WinBitmapSize Function (ROM Call 0x8)
wingraph.h

unsigned short WinBitmapSize (WINDOW *w, const WIN_RECT *rect);

Determines a size of a bitmap (eventually clipped) in bytes.

WinBitmapSize returns the size in bytes of a bitmap for a part of rectangular area given by parameter rect which belongs to the window pointed to by w (may be smaller than the size of this area due to clipping). This size includes the data for the bitmap and the header. All coordinates in rect are relative to the topleft corner of the window. See WinBitmapGet for more info about bitmaps.

Note: WinBitmapSize will clip any negative coordinates to zero.

Uses: WinToScr, BitmapSize, ScrRectOverlap
Used by: cmd_newpic, gr_stopic, GT_SaveAs

See also: WinBitmapSizeExt


WinBitmapSizeExt

WinBitmapSizeExt Function (ROM Call 0x411)
AMS 2.00 or higher wingraph.h

unsigned short WinBitmapSizeExt (WINDOW *w, const WIN_RECT *WinRect);

Determines a size of a bitmap (eventually clipped) in bytes, taking into account negative coordinates.

The difference between WinBitmapSize and WinBitmapSizeExt is that WinBitmapSizeExt takes into account negative coordinates. So, use WinBitmapSize if negative coordinates have to be clipped to zero.

Uses: BitmapSizeExt, RectWinToScrExt

See also: CalcBitmapSize, WinBitmapGet, WinBitmapPut, WinBitmapSize


WinChar

WinChar Function (ROM Call 0xA)
wingraph.h

void WinChar (WINDOW *w, char c);

Draws a character to a window.

DrawChar writes a character c at the current (x, y) location of the window pointed to by w, using the current window attribute (set using WinAttr). The character will be clipped at the boundaries of the window clipping area. The following character attributes are supported (the region defined by a character is 8x10 for huge font, 6x8 for large font or nx5 for small font, depending on the current font set by WinFont command):

A_NORMAL | The character is ORed into the destination
A_REVERSE | The region created by inversing the character replaces the destination
A_REPLACE | The region defined by the character replaces the destination
A_XOR | The character is XORed into the destination
A_SHADED | The character masked so that every other pixel is turned off then ORed into the destination

See WinAttr command for a more general info about attributes.

Note: If the window is opened in TTY mode (see WinOpen), the current printing location will be updated, and newline ('\n' or '\r') and formfeed ('\f') characters will be handled correctly.

Note: On all AMS versions, WinChar calls most of the time a subroutine which is exported in the jump table on AMS 2.xx as ROM_CALL_412. It doesn't call it if the window is opened in TTY mode and the character is '\n', '\r' or '\f'. As a consequence, that subroutine is not of much use, as the same effect (showing these characters as symbols) can be obtained by unsetting the WF_TTY flag. It is mentioned here only for completeness.

Uses: WinClr, PortRestore, ScrRectScroll, sf_width, ROM Call 0x412, ROM Call 0x413
Used by: WinCharXY, WinStr, cmd_input, cmd_inputstr, cmd_prompt, TE_handleEvent, TE_open, TE_openFixed, TE_pasteText, TE_select


WinCharXY

WinCharXY Function (ROM Call 0x9)
wingraph.h

void WinCharXY (WINDOW *w, short x, short y, char c, short Count);

Draws a series of characters to a window at the specific location.

DrawCharXY writes a Count number of character c to a window pointed to by w at a specific (x, y) location (the coordinates are relative to the topleft corner of the window). The current (x, y) location is updated it the wintow is in TTY mode (see WinOpen for more description about window modes). See WinChar for more info about drawing characters.

Uses: WinChar, WinMoveTo, sf_width, ROM Call 0x412
Used by: cmd_pause, Dialog, handleVarLinkKey, GD_Text, GR3_paint3d, HomeExecute, HelpKeys, GR3_handleEvent, WinStrXYWrap


WinClose

WinClose Function (ROM Call 0xB)
wingraph.h

void WinClose (WINDOW *w);

Closes a window.

WinClose closes a window pointed to by w, releasing any memory assigned to it and activating the next window in the window-list. This may mean redrawing portions of the screen in order to keep it up-to-date.

Uses: WinRemove
Used by: assert, cmd_showstat, Dialog, ERD_dialog, handleVarLinkKey, HelpKeys, ERD_dismissNotice


WinClr

WinClr Function (ROM Call 0xC)
wingraph.h

void WinClr (WINDOW *w);

Clears a window.

WinClr clears the client area (i.e. area without the border and without the optional title bar) of the window pointed to by w (using the current clip region), and resets the current (x, y) position to the home of the client region. The current background pattern (set using WinBackground) is used to fill the client area.

Uses: DrawWinBorder, WinHome, BitmapSize, ScrRect, ScrRectFill, memset
Used by: WinActivate, WinChar, WinOpen, WinRemove, cmd_clrhome, cmd_clrio, cmd_disp, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, cmd_showstat, ABT_dialog, EV_defaultHandler, handleVarLinkKey, GR3_paint3d, gdb_recall, HomeExecute, HelpKeys, EV_quit, GR3_addContours, GR3_handleEvent, Regraph, UpdateWindows


WinDeactivate

WinDeactivate Function (ROM Call 0xD)
wingraph.h

void WinDeactivate (WINDOW *w);

Deactivates a window.

WinDeactivate deactivates a window pointed to by w. In fact, it only changes its border to the single-line border, without giving a focus to any other window. It is really only needed if an application has multiple windows. The purpose is to provide a visual clue to the user that a particular window has lost the current focus and that another window (which will be activated with WinActivate) has received the focus. When WinActivate is called, the window with the current focus (the last one to do an activating) is automatically deactivated with WinDeactivate and so it is not necessary to explicitly call WinDeactivate.

Uses: DrawWinBorder
Used by: WinActivate, WinRemove, cmd_disp, cmd_disphome, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, HomeExecute


WinDupStat

WinDupStat Function (ROM Call 0xE)
wingraph.h

short WinDupStat (WINDOW *w, short Stat);

Turns the duplicate status on or off.

WinDupStat turn the duplicate status of the window pointed to by w on (Stat = TRUE) or off (Stat = FALSE). When the duplicate status is turned off, all writes to a window go only to the screen. When turned on, all writes go to both the screen and the backup window. This only applies to windows created with the WF_DUP_SCR flag set. See WinOpen for more info. Beware that duplicate writes slow down all writes to windows with WF_DUP_SCR flag set. WinDupStat also returns the previous duplicate writing status.

Note: This is an official information from TI. I must admit that many things about window management (especially about overlapping windows) is still very obscure to me.

Used by: cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pxlchg, cmd_pxloff, cmd_pxlon, push_pttest, push_pxltest, GD_Circle, GD_Eraser, GD_HVLine, GD_Line, GD_Pen, GD_Select, GD_Text, GZ_Box, gr_DispLabels, gr_stopic, GT_BackupToScr, GT_CursorKey, GT_DspMsg, GT_DspTraceCoords, GT_FreeTrace, GT_SaveAs, GT_ShowMarkers, GT_Trace, Regraph, YCvtFtoP


WinEllipse

WinEllipse Function (ROM Call 0xF)
wingraph.h

void WinEllipse (WINDOW *w, short x, short y, short a, short b);

Draws an ellipse to a window.

WinEllipse draws an ellipse with centre at (x, y) and with semiaxes a and b to the window pointed to by w. The coordinates are relative to the topleft corner of the window. The ellipse will be clipped at the boundaries of the clipping area of the window. The interior of the ellipse remains intact (no fill). The ellipse will be drawn using the current window attribute (set using WinFill). Supported attributes are:

A_NORMAL | Draw a elipse
A_REVERSE | Erase a ellipse
A_XOR | XORs a ellipse into the destination

Note: Set a=b to draw a circle.

Uses: DrawClipEllipse, PortRestore, ROM Call 0x413
Used by: cmd_circle, cmd_pxlcircle, GD_Circle


WinEnd

WinEnd Function (Macro)
wingraph.h

void WinEnd (WINDOW *w);

Ends writing to a non-active window.

If you write to a non-active window, then bracket the writes with WinBegin and WinEnd. See WinActivate for more info.


WinEndPaint

WinEndPaint Function (ROM Call 0x501)
AMS 2.00 or higher wingraph.h

void WinEndPaint (WINDOW *w);

Restores the screen state saved with WinBeginPaint in given window.

WinEndPaint(&w); does nothing more than RestoreScrState(&(w.savedScrState));
WinEndPaint is always paired with WinBeginPaint, and it is commonly used to respond a CM_DEACTIVATE message.

Uses: RestoreScrState

See also: WinBeginPaint


WinFill

WinFill Function (ROM Call 0x10)
wingraph.h

void WinFill (WINDOW *w, const WIN_RECT *rect, short Attr);

Draws a filled rectangle to a window.

WinFill draws a filled rectangle (i.e. fills a rectangular region of a window) given by WIN_RECT structure rect to the window pointed to by w, using the attribute Attr. All coordinates are relative to the topleft corner of the window. The rectangle will be clipped at the boundaries of the clipping area of the window. Supported attributes are:

A_NORMAL | Fill with black pixels
A_REVERSE | Fill with white pixels
A_XOR | All pixels in the rectangle will be reversed

WinFillLines2 is more complicated and slower function than WinFill, but it supports much more attributes. See WinAttr for more info about attributes.

Note: TI said that attribute A_SHADED (set to a pattern of pixels on and off) is also supported, but it didn't work when I tried it; at least, it does not work on AMS 1.00.

Uses: RectWinToScr, WinToScr, PortRestore, ScrRectFill, ScrRectOverlap, ROM Call 0x413
Used by: cmd_cubicreg, cmd_disphome, cmd_expreg, cmd_input, cmd_inputstr, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_pause, cmd_powerreg, cmd_prompt, cmd_quadreg, cmd_quartreg, cmd_twovar, Dialog, EV_defaultHandler, handleVarLinkKey, HomeExecute, ST_eraseHelp, ST_modKey, ST_precision, ST_progressBar, ST_progressUpdate, ST_helpMsg, TE_focus, TE_handleEvent, TE_open, TE_openFixed, TE_pasteText, TE_select, TE_unfocus, EV_quit


WinFillLines2

WinFillLines2 Function (ROM Call 0x11)
wingraph.h

void WinFillLines2 (WINDOW *w, const WIN_RECT *lower_line, const WIN_RECT *upper_line, short Attr);

Draws a filled area between two lines to a window.

WinFillLines2 fills an area bounded with two lines which coordinates are given in two WIN_RECT structures lower_line (lower bound) and upper_line (upper bound) to the window pointed to by w. In fact, it draws a filled polygon whose vertices are (lower_line.x0, lower_line.y0), (lower_line.x1, lower_line.y1), (upper_line.x0, upper_line.y0) and (upper_line.x1, upper_line.y1) using the attribute Attr. All coordinates are relative to the topleft corner of the window. Supported attributes are the same as in command WinFillTriangle. The drawn polygon will be clipped at the boundaries of the clipping area of the window. If lower_line is above upper_line, nothing will be drawn. To be more precise, "above" means "closer to the top of the screen".

Uses: RectWinToWin, FillLines2, PortRestore, ROM Call 0x413
Used by: FuncLineFlt, GM_Shade, GrLineFlt


WinFillTriangle

WinFillTriangle Function (ROM Call 0x12)
wingraph.h

void WinFillTriangle (WINDOW *w, short x0, short y0, short x1, short y1, short x2, short y2, short Attr);

Draws a filled triangle to a window.

FillTriangle draws a filled triangle with vertices (x0, y0), (x1, y1) and (x2, y2) to the window pointed to by w, using the attribute Attr. All coordinates are relative to the topleft corner of the window. The triangle will be clipped at the boundaries of the clipping area of the window. Supported attributes are:

A_NORMAL | Draws a solid fill triangle
A_REVERSE | Draws an empty triangle (i.e. erase a triangular area)
A_XOR | XORs a solid fill triangle into the destination
A_SHADE_V | Draws a triangle filled using a vertical shading pattern
A_SHADE_H | Draws a triangle filled using a horizontal shading pattern
A_SHADE_NS | Draws a triangle filled using a negative slope diagonal shading pattern
A_SHADE_PS | Draws a triangle filled using a positive slope diagonal shading pattern

See WinAttr command for a more general info about attributes.

Note: The 3D grapher in HIDDEN SURFACE mode uses this routine to shade the graph using A_REVERSE if the surface is visible and A_NORMAL if it is hidden (by splitting the graph into 6-sided polygons and splitting those into triangles).

Uses: FillTriangle, PortRestore, ROM Call 0x413
Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_twovar, EV_defaultHandler, GR3_paint3d, EV_quit, GR3_handleEvent


WinFont

WinFont Function (ROM Call 0x13)
wingraph.h

void WinFont (WINDOW *w, short Font);

Sets the current window font.

WinFont changes the current text font for the window pointed to by w. All subsequent characters written to the window will use this font. The supported values for Font are F_4x6, F_6x8, and F_8x10, and they are defined in enum Fonts. The 4x6 font is a proportional font while the 6x8 and 8x10 fonts are fixed-width.

Uses: FontSetSys
Used by: assert, cmd_showstat, Dialog, ERD_dialog, Print2DExpr, ABT_dialog, EV_defaultHandler, GR3_paint3d, ST_eraseHelp, ST_helpMsg, ST_modKey, ST_precision, HelpKeys, ERD_notice, EV_quit, GR3_addContours, GR3_handleEvent, ROM Call 0x45B


WinGetCursor

WinGetCursor Function (ROM Call 0x14)
wingraph.h

void WinGetCursor (WINDOW *w, short *x, short *y);

Returns the cursor location for a window.

WinGetCursor returns the cursor location for the window pointed to by w into x and y. But, I am not quite sure what the "cursor" is. See notes about WinMoveCursor.

Used by: GD_Circle, GD_Eraser, GD_HVLine, GD_Line, GD_Pen, GD_Text, GZ_Box, GT_FreeTrace


WinHeight

WinHeight Function (ROM Call 0x292)
wingraph.h

short WinHeight (WINDOW *w);

Height of a window.

WinHeight returns the height of the client (drawable) area of the window pointed to by w. The window region is the region that was defined when the window was created with WinOpen. If the window is full screen (not counting the status bar which may not be overlapped), then the client region is equal to the window region. The client region is reduced by adding borders or a title to a window.

Used by: cmd_disp, cmd_output, cmd_pause, GD_HVLine, HomeExecute, HomePushEStack, GT_WinBound


WinHide

WinHide Function (ROM Call 0x15)
wingraph.h

void WinHide (WINDOW *w);

Hides a window.

WinHide hides a window pointed to by w (mark it as not-visible so that it is never activated by the system) and updates the screen. When a window is activated (see WinActivate) or when it is opened (unless the WF_VIRTUAL flag is passed to WinOpen), it is marked as visible. All windows in the system are kept in a linked list. When a window in the system is closed, the next visible window in the system is activated and becomes the currently active window. Since virtual windows are never displayed on the screen they are never considered visible. An application's main window is always visible since that is the only view the user has of the application. From the other side, an application may open other windows that it does not want to ever be activated. In that case, use WinHide so that they will never be activated by the system. Although the given window will not be activated by the system, writes to it still go to the screen (unless it is a virtual window).

Uses: UpdateWindows
Used by: cmd_disp, cmd_disphome, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, HomeExecute, ROM Call 0x45B


WinHome

WinHome Function (ROM Call 0x16)
wingraph.h

void WinHome (WINDOW *w);

Moves the pen location for a window to the home position.

WinHome moves the pen location for the window pointed to by w to the home position. Note that in TTY mode this is (1 1) otherwise it is (0, 0). See WinOpen for more info about window modes.

Used by: WinClr, WinOpen, WinReOpen


WinLine

WinLine Function (ROM Call 0x17)
wingraph.h

void WinLine (WINDOW *w, const WIN_RECT *Line);

Draws a line to a window.

WinLine draws a line from (x0, y0) to (x1, y1) to the window pointed to by w where coordinates (x0, y0) and (x1, y1) are given in a WIN_RECT structure Line, using the current attribute. The line will be clipped at the boundaries of the window clipping area. See WinLineTo for a description of supported atributes.

Uses: RectWinToWin, DrawClipLine, PortRestore, ROM Call 0x413
Used by: cmd_circle, cmd_cubicreg, cmd_expreg, cmd_line, cmd_linehorz, cmd_linevert, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_pxlhorz, cmd_pxlline, cmd_pxlvert, cmd_quadreg, cmd_quartreg, cmd_shade, cmd_twovar, EV_defaultHandler, GD_Circle, GD_HVLine, GD_Line, GR3_paint3d, dv_create_graph_titles, EV_quit, GM_Integrate, GM_Shade, GM_TanLine, GR3_handleEvent


WinLineExt

WinLineExt Function (ROM Call 0x47C)
AMS 2.00 or higher wingraph.h

void WinLineExt (WINDOW *w, const WIN_RECT *Line);

Draws a line to a window, more accurately than WinLine when clipping.

WinLineExt acts like WinLine, except that clipping is done more smoothly and drawing is sometimes more accurate: instead of just clipping the coordinates to the window clipping area, as WinLine does, WinLineExt draws the line between the endpoints, drawing only the pixels that are in the window clipping area.
This can lead to little differences between a line drawn by WinLine and the same line drawn by WinLineExt.

The drawback is that WinLineExt is slower than WinLine.

Uses: PortRestore, RectWinToWin, ROM Call 0x413, ROM Call 0x47B, ROM Call 0x47E

See also: WinAttr, WinLine, WinLineRel, WinLineTo


WinLineNC

WinLineNC Function (ROM Call 0x18)
wingraph.h

void WinLineNC (WINDOW *w, const WIN_RECT *Line);

Draws a line to a window, without range checking.

WinLineNC works like WinLine except no range checking is done on the line drawn. Use it with extreme caution as invalid lines could trash the system.

Uses: RectWinToWin, DrawLine, PortRestore, ScrToHome, SetCurClip, ROM Call 0x413
Used by: gdb_recall, FuncLineFlt, GrAxes, GrLineFlt, Regraph


WinLineRel

WinLineRel Function (ROM Call 0x1A)
wingraph.h

void WinLineRel (WINDOW *w, short dx, short dy);

Draws a line to a window from the current pen position, using relative displacements.

WinLineRel acts like WinLine, but dx and dy are relative to the current pen position.

Uses: WinLineTo


WinLineTo

WinLineTo Function (ROM Call 0x19)
wingraph.h

void WinLineTo (WINDOW *w, short x, short y);

Draws a line to a window from the current pen position.

WinLineTo draws a line to the window pointed to by w from the current pen position to the pixel (x, y) using the current attribute given with WinAttr command, then updates the pen position to those coordinates. The current pen position can be initialized with WinMoveTo. Note that the coordinates are relative to the topleft corner of the window. The line will be clipped at the boundaries of the window clipping area. Here is a list of the supported attributes:

A_NORMAL | Draw a normal line
A_REVERSE | Draw an inverse line (i.e. erase the line)
A_XOR | Draw a line using XORing with the destination
A_THICK1 | Draw a double thick line
A_SHADE_V | Draw the line using a vertical shading pattern
A_SHADE_H | Draw the line using a horizontal shading pattern
A_SHADE_NS | Draw the line using a negative slope diagonal shading pattern
A_SHADE_PS | Draw the line using a positive slope diagonal shading pattern

See WinAttr command for a more general info about attributes. Note that although TI said nothing about it, attributes A_SHADE_V, A_SHADE_H, A_SHADE_NS and A_SHADE_PS work only for lines with slope more than 45 degree (i.e. for lines which are more "vertical" than "horizontal"). For "nearly horizontal" lines all of them act like A_NORMAL. I don't know whether it is a bug, or planned feature. So, if you want to draw shaded-fill rectangle using WinLine in a loop, use vertical lines for drawing, not horizontal ones!

Uses: RectWinToWin, WinMoveTo, DrawClipLine, PortRestore, ROM Call 0x413
Used by: WinLineRel, GD_Circle, GD_Line, GR3_paint3d, GR3_handleEvent, GT_ShowMarkers


WinMoveCursor

WinMoveCursor Function (ROM Call 0x1B)
wingraph.h

void WinMoveCursor (WINDOW *w, short x, short y);

Moves the pen position (???).

On the Texas Instruments site, TI comments related to this function are (cite): use WinMoveTo to move pen position, use WinSetCursor to move cursor. Obviously, I am too stupid to conclude what is the difference between the pen position and the cursor. To be more precise, I don't know what "cursor" means to them. I don't see any difference between this command and WinMoveTo. Any info is welcomed. If this fact may help, WinMoveTo changes CurX and CurY fields of the WINDOW structure, WinMoveCursor changes both CurX, CurY and CursorX, CursorY pairs, and WinSetCursor changes only CursorX and CursorY field. Please help!!!

Used by: GD_Eraser, GD_HVLine, GD_Pen, GD_Text, GT_FreeTrace


WinMoveRel

WinMoveRel Function (ROM Call 0x1D)
wingraph.h

void WinMoveRel (WINDOW *w, short dx, short dy);

Sets the current window pen position relative to the previous position.

WinMoveRel acts like WinMoveTo, but dx and dy are relative to the current pen position.


WinMoveTo

WinMoveTo Function (ROM Call 0x1C)
wingraph.h

void WinMoveTo (WINDOW *w, short x, short y);

Sets the current window pen position.

WinMoveTo sets the current pen position for the window pointed to by w to (x, y). The coordinates are relative to the topleft corner of the window. WinMoveTo affects where WinChar and WinStr draw characters and strings as well as the line position for WinLineRel and WinLineTo.

Used by: WinCharXY, WinLineTo, WinStrXY, GD_Circle, GD_Line, GR3_paint3d, GR3_handleEvent, GT_CursorKey, GT_ShowMarkers


WinOpen

WinOpen Function (ROM Call 0x1E)
wingraph.h

short WinOpen (WINDOW *w, const WIN_RECT *rect, unsigned short Flags, ...);

Opens a new window.

WinOpen opens a new window, initializing all fields of the WINDOW structure pointed to by w, and then links this window into the current list of windows as the topmost window. rect is the pointer to the rectangular structure of type WIN_RECT which defines the window area. The flags defined in Flags may be set as one or more of the following constants defined in the enum WinFlags (they have to be ORed; note that WF_SAVE_SCR and WF_DUP_SCR are mutually exclusive):

WF_SAVE_SCR | Save the screen region underneath the window (restore it when the window is closed).
WF_DUP_SCR | Keep a duplicate copy of all data written to the window; when the window needs to be updated, the application will not receive a CM_WPAINT message, instead the system will update the window (see EV_paintOneWindow for more info).
WF_TTY | Write characters in TTY mode (translate '\n' and '\r' to a newline, '\f' to clear screen, and wrap at end of lines).
WF_NOBOLD | When window is activated, do not make the window's border bold.
WF_NOBORDER | Do not draw a border around the window.
WF_ROUNDEDBORDER | Draw a rounded border instead of rectangular border (this option implies WF_NOBOLD as well).
WF_TITLE | Draw a title bar; in this case the Flags parameter must be followed by a text string which will be used as the window title (according to my experience, it seems that only windows with rounded borders may have title bars).
WF_VIRTUAL | Set this flag for virtual windows which are just allocated bitmaps in memory and which are not limited to the size of the screen; no writes to actual LCD are done, only writes to a duplicate screen area (so WF_DUP_SCR must also be set).

WinOpen returns FALSE if there is not enough memory to allocate the save buffer, else returns TRUE. Here is an example (called "Window 4") which displays "hello everyone" in a window (assuming that there were no errors):

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

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#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

// Main Function
void _main(void)
{
  WINDOW *wind = HeapAllocPtr (sizeof (WINDOW));
  WinOpen (wind, MakeWinRect (20, 20, 80, 50), WF_SAVE_SCR | WF_TTY);
  WinActivate (wind);
  WinFont (wind, F_6x8);
  WinStr (wind, "hello everyone");
  ngetchx ();
  WinClose (wind);
  HeapFreePtr (wind);
}
Like any other function which allocates a memory block, WinOpen may cause heap compression.

Note: You must call WinActivate to display a window on the screen, although TI said that you do not need to do so. Also, don't forget to close all windows (using WinClose or WinRemove) before the end of the program, else the TI will crash later, when the TIOS window manager tries to refresh a window in the list which ceased to exist after terminating the program!

Uses: FirstWindow, WinClr, WinHome, HeapAlloc, BitmapGet, BitmapInit, BitmapSize, memcpy, memset, EV_runningApp
Used by: WinReOpen, assert, cmd_newpic, cmd_showstat, Dialog, ERD_dialog, ABT_dialog, EV_defaultHandler, handleVarLinkKey, HelpKeys, ERD_notice, EV_quit, ROM Call 0x45B


WinPixGet

WinPixGet Function (ROM Call 0x1F)
wingraph.h

short WinPixGet (WINDOW *w, short x, short y);

Gets the status of a pixel in a window.

WinPixGet gets the status of the pixel located at (x, y), where coordinates are relative to the topleft corner of the window. Returns TRUE or FALSE depending of whether corresponding pixel is set or reset. Also returns FALSE if coordinates are outside current window.

Uses: GetPix, PortRestore, ROM Call 0x413
Used by: push_pttest, push_pxltest, GD_Pen


WinPixSet

WinPixSet Function (ROM Call 0x20)
wingraph.h

void WinPixSet (WINDOW *w, short x, short y);

Sets a pixel in a window.

WinPixSet set a pixel at (x, y) in the window pointed to by w using the current window attribute (set using WinAttr). The coordinates are relative to the topleft corner of the window (the pixel will not be drawn if the coordinates are out of the window). The following attributes are supported:

A_NORMAL | Draw a pixel
A_REVERSE | Erase a pixel
A_XOR | Invert a pixel

Uses: DrawPix, PortRestore, ROM Call 0x413
Used by: cmd_newpic, cmd_ptchg, cmd_ptoff, cmd_pton, cmd_pxlchg, cmd_pxloff, cmd_pxlon, GD_Pen, gdb_recall, FuncLineFlt, GrAxes, GrLineFlt


WinRect

WinRect Function (ROM Call 0x21)
wingraph.h

void WinRect (WINDOW *w, const WIN_RECT *rect, short Attr);

Draws a rectangle to a window.

WinRect draws a rectangle with (x0, y0) and (x1, y1) as corners to the window pointed to by w, where coordinates (x0, y0) and (x1, y1) are given in a WIN_RECT structure rect. All coordinates are relative to the topleft corner of the window. The rectangle will be clipped at the boundaries of the clipping area of the window. The interior of the rectangle remains intact (no fill). The border lines of the rectangle will be drawn using the attribute Attr. See WinLineTo for a description of supported line atributes. In addition, the attribute may be ORed with one or more following constants (which are defined in enum BoxAttrs:

B_NORMAL | Draw a normal rectangle
B_DOUBLE | Draw a double thick rectangle
B_ROUNDED | Draw a rectangle with rounded corners
B_CUT | Draw a rectangle with the upper corners cut (like in toolboxes)

Note: I cannot conclude which is the difference if you OR the attribute with B_NORMAL or if you do not so. Maybe I am stupid.

Uses: RectWinToWin, WinToScr, DrawClipRect, PortRestore, ScrRectOverlap, ROM Call 0x413
Used by: DrawStaticButton, cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_twovar, Dialog, EV_defaultHandler, GD_Select, GZ_Box, HelpKeys, EV_quit


WinRemove

WinRemove Function (ROM Call 0x414*)
wingraph.h

void WinRemove (WINDOW *w, short UpdateScreen);

Closes the window pointed to by w, and frees the memory assigned to that window.

If UpdateScreen is TRUE, the next window in the linked list of windows is activated and the screen is updated.
If UpdateScreen is FALSE, no window is activated and the screen is not updated.
In fact, WinClose calls WinRemove with UpdateScreen = TRUE on all AMS versions.
Virtual windows (the ones with WF_VIRTUAL flag set) should be closed with:

WinRemove(&w,FALSE);

Uses: UpdateWindows, HeapFree, BitmapPut, FontSetSys, ScrRect, DrawWinBorder, FirstWindow, WinClr, WinDeactivate
Used by: cmd_newpic, WinClose, WinReOpen

See also: WinClose, WinOpen


WinReOpen

WinReOpen Function (ROM Call 0x22)
wingraph.h

short WinReOpen (WINDOW *w, const WIN_RECT *rect, unsigned short Flags, ...);

Reopens an existing window.

WinReOpen acts like WinOpen, but reopens an existing window. Not valid for windows created in WF_SAVE_SCR mode (unless using just to call WinOpen). If the window is not in the "list of windows" then just calls WinOpen. Otherwise, it updates the Client, Window, Clip, and Port regions of the window. If the new window is of the same size as the old one, then the Port region (DUP_SCR) is not cleared. Returns TRUE if the window re-opened OK, and returns FALSE if not (bad window or not enough memory to enlarge DUP_SCR).

Note: This is the official information by Texas Instruments. I am not sure that I fully understood what they want to say. It seems that you can reopen a window on a new place (keeping the same size), then redraw the window on a new position using WinBackupToScr.

Uses: FirstWindow, WinHome, WinOpen, WinRemove, HeapRealloc, BitmapInit, BitmapSize, memset, UpdateWindows


WinScrollH

WinScrollH Function (ROM Call 0x23)
wingraph.h

void WinScrollH (WINDOW *w, const WIN_RECT *rect, short NumCols);

Shifts a region of a window left or right.

WinScrollH shifts the rectangular area determined by rect of the window pointed to by w left by NumRows pixels (or right if NumRows < 0). The coordinates in rect are relative to the topleft corner od the window. Blank areas (i.e. the vacant space produced after scrolling) are filled with current background for the window (see WinBackground).

Note: This command is not very fast because it is realized using WinBitmapGet and WinBitmapPut. If the region to be scrolled starts on a byte boundary (left-most pixel), then the region will scroll much faster.

Uses: WinToScr, ClientToScr, PortRestore, ScrRectOverlap, ScrRectShift, ROM Call 0x413
Used by: cmd_pause


WinScrollV

WinScrollV Function (ROM Call 0x24)
wingraph.h

void WinScrollV (WINDOW *w, const WIN_RECT *rect, short NumRows);

Scrolls a region of a window upwards or downwards.

WinScrollV scrolls the rectangular area determined by rect of the window pointed to by w upwards by NumRows pixels (or downwards if NumRows < 0). The coordinates in rect are relative to the topleft corner od the window. Blank areas (i.e. the vacant space produced after scrolling) are filled with current background for the window (see WinBackground).

Note: This command is not very fast because it is realized using WinBitmapGet and WinBitmapPut.

Uses: WinToScr, ClientToScr, PortRestore, ScrRectOverlap, ScrRectScroll, ROM Call 0x413
Used by: cmd_disp, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, EV_defaultHandler, TE_handleEvent, EV_quit


WinSetCursor

WinSetCursor Function (Macro)
wingraph.h

void WinSetCursor (WINDOW *w, short x, short y);

Moves the cursor (???).

See the note under WinMoveCursor. WinSetCursor really does not produce any visible effect for me. It is a macro defined by TI which changes CursorX and CursorY fields of the WINDOW structure.


WinShow

WinShow Function (Macro)
wingraph.h

void WinShow (WINDOW *w);

Makes a window visible for the repainting routine.

This is a simple macro defined by Texas Instruments. It sets WF_VISIBLE flag of the window pointed to by w, making the window "visible" for event-driven repainting routine. This flag is used only in event driven applications (see event.h header file, especially EV_paintOneWindow function).


WinStr

WinStr Function (ROM Call 0x25)
wingraph.h

void WinStr (WINDOW *w, const char *str);

Draws a string to a window.

WinStr draws the string str to the window pointed to by w at the current pen location. The current pen location is updated to point to the end of where the string was written if the window is in TTY mode (see WinOpen for more description about window modes). See WinChar routine for a description of character attributes and fonts.

Uses: WinChar, sf_width, ROM Call 0x412
Used by: WinStrXY, assert, ABT_dialog


WinStrXY

WinStrXY Function (ROM Call 0x26)
wingraph.h

void WinStrXY (WINDOW *w, short x, short y, const char *str);

Draws a string to a window at a specific location.

WinStrXY draws the string str to a window pointed to by w at the specific (x, y) location (the coordinates are relative to the topleft corner of the window). See WinStr for more info.

Uses: WinMoveTo, WinStr
Used by: DrawStaticButton, cmd_cubicreg, cmd_disp, cmd_expreg, cmd_input, cmd_inputstr, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_output, cmd_pause, cmd_powerreg, cmd_prompt, cmd_pttext, cmd_pxltext, cmd_quadreg, cmd_quartreg, cmd_showstat, cmd_twovar, Dialog, ERD_dialog, ABT_dialog, EV_defaultHandler, handleVarLinkKey, GR3_paint3d, HomeExecute, ST_eraseHelp, ST_modKey, ST_precision, ST_helpMsg, HelpKeys, ERD_notice, EV_quit, gr_DispLabels, GR3_addContours, GT_BackupToScr, GT_DspMsg, GT_DspTraceCoords, GT_Trace, YCvtFtoP, ROM Call 0x45B


WinStrXYWrap

WinStrXYWrap Function (ROM Call 0x5DB)
AMS 2.04 or higher wingraph.h

short WinStrXYWrap (WINDOW *w, WIN_COORDS x, WIN_COORDS y, const char *s, unsigned short flags);

Draws a word-wrapped string to a window at position x, y (window-based), and returns the height in pixels of the text drawn.

w is the pointer to a window.
x and y is the place where to draw the string, x is also the left margin to wrap on.
s is the pointer to the string to write.
flags: correct values are described in winWriteFlags.

This function is available in the jump table only on AMS 2.04 and later, and the parameter WWF_WRAP_BACK_TO_ZERO is taken into account only on AMS 2.07 and later.

Uses: DrawStrWidthP, FontCharWidth, WinCharXY, WinWidth

See also: winWriteFlags


WinToScr

WinToScr Function (ROM Call 0x42F)
AMS 2.00 or higher wingraph.h

SCR_RECT *WinToScr (const WIN_RECT *win_rect, SCR_RECT *dest_rect);

Converts a WIN_RECT into a SCR_RECT, clipping the coordinates if necessary.

WinToScr converts coordinates (shorts) in the structure win_rect to the same coordinates (unsigned char), storing the result in the structure pointed to by dest_rect, except that the coordinates that are negative are clipped to 0, and the coordinates greater than 0xFF are clipped to 0xFF. WinToScr returns dest_rect back (but the structure pointed to by it is modified).

If you want a WinToScr that works on all AMS versions, you can use:

#undef WinToScr
SCR_RECT *WinToScr (const WIN_RECT *win_rect, SCR_RECT *dest_rect);
asm("
WinToScr:
move.l   4(%sp),%a1
move.l   8(%sp),%a0
moveq    #4-1,%d1
_loop_WTS_:
move.w   (%a1)+,%d0
bge.s    _not_negative_WTS_
moveq    #0,%d0 | clr.w %d0 or eor.w %d0,%d0 are enough and just as fast.
bra.s    _store_WTS_
_not_negative_WTS_:
cmpi.w   #0xFF,%d0
bls.s    _store_WTS_
moveq    #-1,%d0
_store_WTS_:
move.b   %d0,(%a0)+
dbf      %d1,_loop_WTS_
subq.l   #4,%a0
rts
");


WinWidth

WinWidth Function (ROM Call 0x291)
wingraph.h

short WinWidth (WINDOW *w);

Width of a window.

WinWidth returns the width of the client (drawable) area of the window pointed to by w. The window region is the region that was defined when the window was created with WinOpen. If the window is full screen (not counting the status bar which may not be overlapped), then the client region is equal to the window region. The client region is reduced by adding borders or a title to a window.

Used by: WinStrXYWrap, cmd_input, cmd_inputstr, cmd_pause, cmd_prompt, GD_HVLine, HomeExecute, HomePushEStack, ST_progressBar, GT_WinBound


DeskTop

DeskTop Variable
wingraph.h

WINDOW *const DeskTop;

A pointer to the desktop window.

DeskTop is a constant static pointer (i.e. it can't be changed, but the structure pointed to by it may be changed) which points to the desktop window. This is a window without a border which occupies the whole screen area except the status line, but the clipping area of this window is set to exclude the area occupied by the toolbar menu, so you cannot draw over the menu area if you use this window as a parameter to any window drawing function (except if you changed Clip field of the structure pointed to by DeskTop manually). Usually, if you want to use a function which expects a parameter which is a pointer to a window structure, but if you don't want to create your own window, you can pass DeskTop as the parameter to it (of course, if you don't need to draw something in the menu or status line area).


FirstWindow

FirstWindow Variable (ROM Call 0x0)
wingraph.h

WINDOW *FirstWindow;

A pointer to the head of the list of all windows.

FirstWindow is a pointer to the first window in the linked list of all created windows. By starting from FirstWindow and tracking the Next field of a WINDOW structure pointed to by it, it is possible to access to all created windows (the last one is the window which Next field is equal to NULL).

Note: Under normal conditions, FirstWindow points to the Home screen window, which is defined as a window without a border, which occupies the space between the toolbar menu and the command input line. When this is just a window which you want to use in your program, you can pass FirstWindow as a parameter to any window routine (although DeskTop is probably a better choice). And, by changing a structure pointed to by FirstWindow, it is possible to make Home screen "larger" or "smaller", or to perform similar "dirty" tricks. See EV_registerMenu for a dirty example.

Used by: WinActivate, WinOpen, WinRemove, WinReOpen, EV_paintOneWindow, MO_notifyModeChange, UpdateWindows


winWriteFlags

winWriteFlags Type (Enumeration)
AMS 2.04 or higher wingraph.h

enum winWriteFlags {
WWF_DRAW = 1, WWF_WRAP_ON_COMMAS = 2, WWF_WRAP_BACK_TO_ZERO = 4
};

Enumeration for parameter flags to WinStrXYWrap.

WWF_DRAW means that the function will draw the string. If it is not set in the flags, the height of the text drawn is returned and nothing else is done.
WWF_WRAP_ON_COMMAS means that the function will also wrap on commas, not only on spaces (\x20) and carriage returns (\x0A).
WWF_WRAP_BACK_TO_ZERO means that the function will go back to the first column of the window after the first line. This option is available only on AMS 2.07 and more.

See also: WinStrXYWrap


GNU General Public License

GNU General Public License
Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software -- to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it (some other Free Software Foundation software is covered by the GNU Library General Public License instead). You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING,
DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language (hereinafter, translation is included without limitation in the term "modification"). Each licensee is addressed as "you".

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
NO WARRANTY
  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

<one line to give the program's name and a brief idea of what it does.>
Copyright (C) 19yy <name of author>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type 'show c' for details.

The hypothetical commands 'show w' and 'show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than 'show w' and 'show c'; they could even be mouse-clicks or menu items -- whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program
'Gnomovision' (which makes passes at compilers) written by James Hacker.

<signature of Ty Coon>, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.
  • GNU Free Documentation License
  • Funding Free Software


Funding Free Software
Previous GNU General Public License

If you want to have more free software a few years from now, it makes sense for you to help encourage people to contribute funds for its development. The most effective approach known is to encourage commercial redistributors to donate.

Users of free software systems can boost the pace of development by encouraging for-a-fee distributors to donate part of their selling price to free software developers - the Free Software Foundation, and others.

The way to convince distributors to do this is to demand it and expect it from them. So when you compare distributors, judge them partly by how much they give to free software development. Show distributors they must compete to be the one who gives the most.

To make this approach work, you must insist on numbers that you can compare, such as, "We will donate ten dollars to the Frobnitz project for each disk sold." Don't be satisfied with a vague promise, such as "A portion of the profits are donated," since it doesn't give a basis for comparison.

Even a precise fraction "of the profits from this disk" is not very meaningful, since creative accounting and unrelated business decisions can greatly alter what fraction of the sales price counts as profit. If the price you pay is $50, ten percent of the profit is probably less than a dollar; it might be a few cents, or nothing at all.

Some redistributors do development work themselves. This is useful too; but to keep everyone honest, you need to inquire how much they do, and what kind. Some kinds of development make much more long-term difference than others. For example, maintaining a separate version of a program contributes very little; maintaining the standard version of a program for the whole community contributes much. Easy new ports contribute little, since someone else would surely do them; difficult ports such as adding a new CPU to the GNU Compiler Collection contribute more; major new features or packages contribute the most.

By establishing the idea that supporting further development is "the proper thing to do" when distributing free software for a fee, we can assure a steady flow of resources into making more free software.

Copyright © 1994 Free Software Foundation, Inc.
Verbatim copying and redistribution of this section is permitted without royalty; alteration is not permitted.


GNU Free Documentation License
GNU General Public License Next

GNU Free Documentation License
Version 1.1, March 2000

Copyright (c) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

    A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

    The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

    A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

    The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).

    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.

    4. Preserve all the copyright notices of the Document.

    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

    8. Include an unaltered copy of this License.

    9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

    11. In any section entitled "Acknowledgments" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgments and/or dedications given therein.

    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

    13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.

    14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties - for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgments", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled "GNU
  Free Documentation License".
If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.


Function (ROM Call 0x3CD)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: EV_currentApp, OO_GetAppAttr, ER_catch, ER_success
Used by: EV_defaultHandler, EV_setCmdCheck, EV_setCmdState, EV_setFKeyState, MenuUpdate


Function (ROM Call 0x3CE)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: FlashMemoryEnd, EM_getArchiveMemoryBeginning


Function (ROM Call 0x3D1)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: EM_findEmptySlot, EM_survey


Function (ROM Call 0x3E8)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: memset
Used by: VarOpen, FFindFirst, FFindNext, FOpen, FType, VarStore


Function (ROM Call 0x3EA)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: EV_getc, ScrRect, ScrRectFill, pushkey, OSWriteLinkBlock, CU_cursorState, CU_restore, CU_start, off, OSSetSR, QModeKey, QSysKey, ROM Call 0x471
Used by: GKeyIn, MenuKey, ROM Call 0x421


Function (ROM Call 0x3EC)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: TIOS_abs
Used by: WinBitmapGet


Function (ROM Call 0x3F7)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: OO_firstACB, OO_GetAppAttr, OO_NextACB, HeapFreeIndir, ER_catch, ER_success, memset, MenuAddText, PopupNew, strcat, XR_stringPtr


Function (ROM Call 0x3F8)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: OO_firstACB, OO_GetAppAttr, OO_NextACB, HeapFreeIndir, ER_catch, ER_success, memset, MenuAddText, PopupNew, strcat, XR_stringPtr


Function (ROM Call 0x3F9)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: Float0Index, Float1Index, FloatExp1Index, FloatHalfIndex, FloatMinus1Index, FloatPiIndex, ROM Call 0x5E9, ROM Call 0x5EA


Function (ROM Call 0x4CA)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, GR3_addContours, GraphActivate, next_expression_index, GR3_paint3d, gr_active, _bcd_math


Function (ROM Call 0x4CB)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: GetStatValue, HeapAllocThrow, HeapRealloc
Used by: cmd_cubicreg, cmd_expreg, cmd_linreg, cmd_lnreg, cmd_logistic, cmd_medmed, cmd_onevar, cmd_powerreg, cmd_quadreg, cmd_quartreg, cmd_sinreg, cmd_twovar


Function (ROM Call 0x4D5)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: XR_stringPtr
Used by: DlgMessage, DrawStaticButton


Function (ROM Call 0x4D7)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: DrawStrWidth, FontGetSys, ROM Call 0x41E
Used by: Dialog


Function (ROM Call 0x4DC)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: push_simplify, map_tail


Function (ROM Call 0x4DF)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: signum_Float
Used by: add_to_top, are_units_consistent, did_push_divide_units, get_ub, index_if_pushed_binomial_info, index_if_pushed_qquad_info, is_negative, is_never0, is_nonnegative, is_term_improper, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_abs, push_acosh, push_asin, push_asinh, push_atan, push_atanh, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_perm, push_phase, push_re, push_sign, push_sin2, push_solve, push_zeros, did_push_to_polar, push_dot_exponentiate, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere, index_below_display_expression_aux, Parse2DExpr, Parse2DMultiExpr


Function (ROM Call 0x4E0)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: signum_Float
Used by: is_term_improper, push_factor, push_exponentiate, push_product


Function (ROM Call 0x4E1)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: signum_Float
Used by: is_nonpositive


Function (ROM Call 0x4E2)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: signum_Float
Used by: did_push_divide_units, is_never0, is_polynomial_in_var_or_kern, is_positive, did_push_anti_deriv, push_extended_prod, push_max, push_min, push_perm, push_summation, push_exponentiate, estack_to_ushort


Function (ROM Call 0x4E6)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: and_onto_top, is_real, is_variable, lead_conjunct_factor_index, lead_disjunct_term_index, primary_tag_list, push_but_conjunct_factor, remaining_conjuncts_index, remaining_disjuncts_index, ER_catch, ER_success, ER_throwVar, are_expressions_identical, delete_between, is_independent_of, is_independent_of_tail, is_tail_independent_of, next_expression_index, push_expr_quantum, push_expression, push_internal_simplify, push_next_arb_real, push_quantum, push_reversed_tail, top_estack, ST_helpMsg, XR_stringPtr, ROM Call 0x5E4
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


Function (ROM Call 0x4E9)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: Float0Index, NG_control, push_expression, push_exact0
Used by: push_reciprocal, push_1st_derivative, push_comb, push_extended_prod, push_summation, push_product


Function (ROM Call 0x4EA)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: Float1Index, NG_control, push_expression, push_exact1
Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comb, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_extended_prod, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_summation, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_factorial, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere


Function (ROM Call 0x4EF)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: FloatMinus1Index, NG_control, push_expression, push_exact_minus1
Used by: add_to_top, are_units_consistent, get_ub, index_if_pushed_qquad_info, push_auto_units_conversion, push_but_factor, push_but_term, push_constant_factors, push_constant_terms, push_dependent_factors, push_dependent_terms, push_gcd_then_cofactors, push_independent_factors, push_independent_terms, push_make_proper, push_nonconstant_factors, push_nonconstant_terms, push_nonnumeric_factors, push_poly_qr, push_reciprocal, push_standardize, raise_to_top, replace_top_with_post_simplified, replace_top2_with_pow, replace_top2_with_sum, did_push_anti_deriv, did_push_series, push_1st_derivative, push_comdenom, push_csolve, push_czeros, push_def_int, push_denominator, push_desolve, push_expand, push_factor, push_floor, push_im, push_lim, push_max, push_min, push_nsolve, push_numerator, push_phase, push_re, push_sin2, push_solve, push_zeros, did_push_to_polar, push_equals, push_exponentiate, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_negate, push_not_equals, push_product, push_sum, push_to_cylin, push_to_sphere


Function (ROM Call 0x4F4)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: OSLinkOpen


Function (ROM Call 0x4F6)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: OO_firstACB, OO_GetAppAttr, OO_NextACB, stricmp
Used by: OO_InstallAppHookByName, OO_UninstallAppHookByName


Function (ROM Call 0x4FB)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: CustomBegin, CustomEnd, GT_KeyIn, EV_defaultHandler, EV_setFKeyState, MenuUpdate


Function (ROM Call 0x4FD)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: OO_appMarkDelete, ROM Call 0x4FE
Used by: handleVarLinkKey, LIO_Receive, ROM Call 0x478


Function (ROM Call 0x4FE)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: EV_appA, EV_appB, OO_firstACB, OO_GetAppAttr, OO_NextACB
Used by: LIO_Receive, ROM Call 0x4FD


Function (ROM Call 0x5C4)
AMS 2.04 or higher

This identifier has not been documented yet. Please help us out.

Used by: push_factor, push_next_internal_var, reset_control_flags


Function (ROM Call 0x5C5)
AMS 2.04 or higher

This identifier has not been documented yet. Please help us out.

Used by: EQU_getNameInfo, push_parse_prgm_or_func_text, push_simplify_statements, push_user_func, cmd_try, push_str_to_expr, NG_execute, NG_graphESI, push_parse_text, VarStore


Function (ROM Call 0x5C6)
AMS 2.04 or higher

This identifier has not been documented yet. Please help us out.

Used by: push_user_func, time_loop, HeapAllocESTACK, Dialog, NG_execute, NG_graphESI


Function (ROM Call 0x5C7)
AMS 2.04 or higher

This identifier has not been documented yet. Please help us out.

Used by: push_user_func, store_func_def, cmd_goto, cmd_return, cmd_try, push_str_to_expr, NG_approxESI, NG_execute, NG_graphESI, NG_rationalESI


Function (ROM Call 0x5C8)
AMS 2.04 or higher

This identifier has not been documented yet. Please help us out.

Used by: push_simplify_statements, push_user_func, store_func_def, tokenize_if_TI_92_or_text, cmd_custom, cmd_cycle, cmd_dialog, cmd_else, cmd_endfor, cmd_endloop, cmd_endwhile, cmd_exit, cmd_for, cmd_goto, cmd_if, cmd_ifthen, cmd_local, cmd_return, cmd_toolbar, cmd_try, cmd_while, push_str_to_expr, NG_execute, NG_graphESI


Function (ROM Call 0x5C9)
AMS 2.04 or higher

This identifier has not been documented yet. Please help us out.

Used by: clear_error_context, tokenize_if_TI_92_or_text, ERD_process


Function (ROM Call 0x5CA)
AMS 2.04 or higher

This identifier has not been documented yet. Please help us out.

Used by: clear_error_context, tokenize_if_TI_92_or_text, cmd_archive, cmd_input, cmd_inputstr, cmd_prompt, cmd_unarchiv, ERD_process, HomeExecute, SymDelTwin


Function (ROM Call 0x5CB)
AMS 2.04 or higher

This identifier has not been documented yet. Please help us out.

Used by: clear_error_context, push_user_func, tokenize_if_TI_92_or_text, display_statements, NG_execute, NG_graphESI


Function (ROM Call 0x5CC)
AMS 2.04 or higher

This identifier has not been documented yet. Please help us out.

Used by: clear_error_context, push_user_func, tokenize_if_TI_92_or_text, ERD_process, NG_execute, NG_graphESI, HomeExecute


Function (ROM Call 0x5E2)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: push_simplify, compare_expressions, reset_control_flags


Function (ROM Call 0x5E4)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: are_units_consistent, get_ub, index_if_pushed_qquad_info, push_user_func, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_factor, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, push_substitute_simplify, push_internal_simplify, reset_control_flags, ROM Call 0x4E6


Function (ROM Call 0x5E5)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: did_push_approx_inflection_point, get_ub, GM_Intersect, GM_Math1, push_simplify, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals, reset_control_flags


Function (ROM Call 0x5E6)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: replace_top_with_post_simplified, push_csolve, push_czeros, reset_control_flags


Function (ROM Call 0x5E7)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: push_simplify_statements, did_push_anti_deriv, push_1st_derivative, push_desolve, push_nth_derivative


Function (ROM Call 0x5E8)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: get_ub, push_simplify_statements, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


Function (ROM Call 0x5E9)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: ROM Call 0x3F9


Function (ROM Call 0x5EA)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: ROM Call 0x3F9


Function (ROM Call 0x5EB)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: did_push_approx_inflection_point, get_ub, GM_Intersect, GM_Math1, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


Function (ROM Call 0x5EC)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: replace_top_with_post_simplified, reset_control_flags


Function (ROM Call 0x5ED)
AMS 2.05 or higher

This identifier has not been documented yet. Please help us out.

Used by: push_user_func, push_csolve, push_czeros, push_max, push_min, push_nsolve, push_solve, push_when, push_zeros, reset_control_flags


Function (ROM Call 0x5EF)
AMS 2.08 or higher

This identifier has not been documented yet. Please help us out.

Used by: EQU_getNameInfo, push_parse_prgm_or_func_text, push_simplify_statements, index_below_display_expression_aux, push_parse_text, reset_control_flags


Function (ROM Call 0x5F0)
AMS 2.08 or higher

This identifier has not been documented yet. Please help us out.

Used by: EQU_getNameInfo, push_parse_prgm_or_func_text, push_simplify_statements, index_below_display_expression_aux, push_parse_text, reset_control_flags


Function (ROM Call 0x31)

This identifier has not been documented yet. Please help us out.

Used by: ERD_process


Function (ROM Call 0x40C)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: VarGraphRefBitsClear, HeapAlloc, memset, XR_stringPtr


Function (ROM Call 0x40D)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: SymFindFirst, SymFindNext


Function (ROM Call 0x40E)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: strlen, SymCpy0
Used by: handleVarLinkKey


Function (ROM Call 0x41C)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: ROM Call 0x422
Used by: init_unit_system, setup_unit_system, Dialog, MO_digestOptions, ROM Call 0x421


Function (ROM Call 0x41D)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: init_unit_system, setup_unit_system, Dialog, MO_digestOptions


Function (ROM Call 0x41E)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: XR_stringPtr
Used by: init_unit_system, setup_unit_system, Dialog, MO_digestOptions, DynMenuChange, MenuBegin, MenuItemDef, MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, PopupText, ROM Call 0x421, ROM Call 0x4D7


Function (ROM Call 0x41F)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: XR_stringPtr
Used by: ROM Call 0x421


Function (ROM Call 0x42B)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: OO_firstACB, OO_NextACB


Function (ROM Call 0x44B)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: copen, cread


Function (ROM Call 0x45A)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: GetStatValue, cmd_newdata, checkCurrent, ROM Call 0x45B


Function (ROM Call 0x45B)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: EV_quit, hStrAppend, HeapAllocThrow, HeapFreeIndir, ER_catch, ER_success, ER_throwVar, ERD_dialog, Parse1DExpr, push_expression, top_estack, EV_registerMenu, memset, sprintf, WinAttr, WinBitmapPut, WinFont, WinHide, WinOpen, WinStrXY, ROM Call 0x45A


Function (ROM Call 0x45E)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: Dialog, ER_catch, ER_success, DerefSym, HSymDel, SymFind
Used by: HomeExecute


Function (ROM Call 0x46A)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: gr_ck_solvergraph


Function (ROM Call 0x46E)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: GR3_addContours, GS_PlotAll, GZ_Stat, Regraph, cmd_disptbl, cmd_pause, GR3_paint3d, LIO_RecvData, LIO_Send, OSLinkClose, OSLinkCmd, OSLinkOpen, ROM Call 0x473


Function (ROM Call 0x46F)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, NG_control, ER_catch, ER_success, ER_throwVar, NG_approxESI, push_parse_text, top_estack
Used by: GT_Trace, GZ_SetFactors, EV_defaultHandler


Function (ROM Call 0x47A)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: ROM Call 0x473


Function (ROM Call 0x47B)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: TIOS_abs, DrawLine
Used by: WinLineExt


Function (ROM Call 0x47E)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: _ds32s32
Used by: DrawClipLine, WinLineExt


Function (ROM Call 0x47F)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, push_indir_name, push_expression, top_estack


Function (ROM Call 0x48C)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, IM_re_tol, next_expression_index, push_round_Float, fabs, _bcd_math
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


Function (ROM Call 0x48D)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, is_constant, is_negative, is_positive, primary_tag_list, push0, replace_top2_with_pow, replace_top2_with_prod, are_expressions_identical, compare_expressions, delete_between, lead_base_index, lead_exponent_index, lead_factor_index, map_tail, move_between_to_top, next_expression_index, numeric_factor_index, push_between, push_expr_quantum, push_expression, push_quantum, remaining_factors_index, top_estack, fabs, _bcd_math
Used by: push_gcd_then_cofactors, push_poly_qr


Function (ROM Call 0x58E)
AMS 2.02 or higher

This identifier has not been documented yet. Please help us out.

Uses: cgetfnl, _du32u32, _mu32u32


Function (ROM Call 0x131)

This identifier has not been documented yet. Please help us out.

Uses: OO_firstACB, OO_GetAppAttr, OO_NextACB, strcmp, stricmp
Used by: push_user_func


Function (ROM Call 0x168)

This identifier has not been documented yet. Please help us out.

Uses: memucmp


Function (ROM Call 0x412)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: sf_width, DrawChar, DrawClipChar, PortRestore, ROM Call 0x413
Used by: TE_handleEvent, TE_open, TE_openFixed, TE_pasteText, TE_select, WinChar, WinCharXY, WinStr


Function (ROM Call 0x413)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: PortSet
Used by: WinLineExt, WinBitmapGet, WinBitmapPut, WinChar, WinEllipse, WinFill, WinFillLines2, WinFillTriangle, WinLine, WinLineNC, WinLineTo, WinPixGet, WinPixSet, WinRect, WinScrollH, WinScrollV, ROM Call 0x412


Function (ROM Call 0x417)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: ROM Call 0x424


Function (ROM Call 0x418)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: LIO_Receive


Function (ROM Call 0x420)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: BitmapPut, memcpy
Used by: MenuKey, MenuOff, MenuOn, MenuTopRedef, MenuTopSelect, ROM Call 0x421


Function (ROM Call 0x421)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: CTypeTable, HeapAllocESTACK, HeapFree, BitmapGet, BitmapPut, BitmapSize, CalcBitmapSize, DrawChar, DrawClipRect, DrawFkey, DrawLine, DrawPix, DrawStr, DrawStrWidth, FontSetSys, PortRestore, RestoreScrState, SaveScrState, ScrRect, ScrRectFill, ScrToWin, SetCurAttr, SetCurClip, alphaLockOff, alphaLockOn, restoreAlphaLock, FKeyI_H, ST_eraseHelp, ST_helpMsg, strlen, CU_cursorState, CU_restore, CU_stop, XR_stringPtr, ROM Call 0x3EA, ROM Call 0x41C, ROM Call 0x41E, ROM Call 0x41F, ROM Call 0x420, ROM Call 0x422
Used by: MenuPopup, PopupBeginDo


Function (ROM Call 0x422)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: MenuCheck, MenuItemDef, MenuKey, MenuSubStat, ROM Call 0x41C, ROM Call 0x421


Function (ROM Call 0x424)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: OO_DestroyAll, OO_firstACB, OO_NextACB, HeapAlloc, HeapDeref, HeapFreeIndir, EV_sendEvent, ROM Call 0x417
Used by: EV_eventLoop, handleVarLinkKey, LIO_Receive, ROM Call 0x478


Function (ROM Call 0x428)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: OO_firstACB, OO_GetAppAttr, OO_NextACB, EV_sendEvent
Used by: EV_centralDispatcher, LIO_Receive


Function (ROM Call 0x437)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: ParseSymName, ER_throwVar, ST_folder, CheckReservedName, CheckSysFunc, DerefSym, FolderFind, FolderRename, SymMove, VarRecall
Used by: cmd_rename


Function (ROM Call 0x438)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: HeapAllocThrow, HeapFree, HeapFreeIndir, HeapGetLock, HeapLock, HeapSize, HeapUnlock, ER_catch, ER_success, ER_throwVar, HToESI, memcpy, NeedStack, ClearUserDef, DerefSym, HSymDel, QSysProtected, SymDel, VarRecall, VarStore, ROM Call 0x487
Used by: cmd_copyvar


Function (ROM Call 0x439)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: HeapFree, HeapRealloc, memmove, SymCpy, SymFindPtr, _ds32s32
Used by: SymAdd, SymAddMain, SymMove, VarStore


Function (ROM Call 0x441)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: SumStoChkMem


Function (ROM Call 0x446)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: trig


Function (ROM Call 0x450)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: map_tail, push_internal_simplify
Used by: push_user_func, store_to_subscripted_element, push_subscripted_element


Function (ROM Call 0x455)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: GraphActivate, ER_catch, ER_success, ER_throwVar, EV_sendEvent, EV_startApp, gr_active
Used by: cmd_input, cmd_inputstr, cmd_trace, cmd_zoombox, cmd_zoomdata, cmd_zoomdec, cmd_zoomfit, cmd_zoomin, cmd_zoomint, cmd_zoomout, cmd_zoomprev, cmd_zoomrcl, cmd_zoomsqr, cmd_zoomstd, cmd_zoomsto, cmd_zoomtrig


Function (ROM Call 0x457)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: cmd_disp, cmd_output, cmd_pause, index_below_display_expression_aux, Parse1DExpr, Parse2DExpr


Function (ROM Call 0x459)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: cmd_newdata


Function (ROM Call 0x460)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: did_push_approx_inflection_point, get_ub, GM_Intersect, GM_Math1, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


Function (ROM Call 0x461)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: did_push_approx_inflection_point, get_ub, GM_Intersect, GM_Math1, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


Function (ROM Call 0x462)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals


Function (ROM Call 0x468)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: does_push_fetch, is_pathname, primary_tag_list, push_indir_name, delete_between, delete_expression, is_independent_of, is_tail_independent_of, next_expression_index, push_expression, push_quantum, top_estack, DerefSym, VarRecall, secondary_tag_list


Function (ROM Call 0x471)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: EV_quit, cmd_disp, cmd_disphome, cmd_input, cmd_inputstr, cmd_output, cmd_pause, cmd_prompt, Dialog, ERD_dialog, EV_defaultHandler, EV_eventLoop, EV_getc, MO_currentOptions, MO_digestOptions, HomeExecute, HomePushEStack, ngetchx, TE_focus, TE_handleEvent, TE_pasteText, TE_unfocus, ROM Call 0x3EA


Function (ROM Call 0x473)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: FL_getHardwareParmBlock, OSFastArrows, ST_modKey, OSqclear, ROM Call 0x46E, ROM Call 0x47A


Function (ROM Call 0x478)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: TIOS_EV_getAppID, memcpy, ROM Call 0x424, ROM Call 0x4FD


Function (ROM Call 0x480)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: primary_tag_list, push_indir_name, push_expression, top_estack
Used by: GraphOrTableCmd, cmd_dialog, cmd_endfor, cmd_popup, cmd_request


Function (ROM Call 0x486)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: OO_firstACB, OO_GetAppAttr, OO_NextACB, HeapFreeIndir, ER_catch, ER_success, memset, MenuAddText, PopupNew, strcat, XR_stringPtr
Used by: MO_modeDialog


Function (ROM Call 0x487)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: QSkipGraphErr, ROM Call 0x438


Function (ROM Call 0x494)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, HeapAllocHighThrow, HeapAllocThrow, HeapFreeIndir, HeapLock, RemainingArgCnt, ER_catch, ER_success, ER_throwVar, next_expression_index, push_Float, push_quantum, top_estack, fabs, sqrt, _bcd_math, _mu16u16
Used by: push_eigvc


Function (ROM Call 0x495)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, HeapAllocHighThrow, HeapAllocThrow, HeapFreeIndir, HeapLock, RemainingArgCnt, ER_catch, ER_success, ER_throwVar, next_expression_index, push_Float, push_quantum, top_estack, fabs, sqrt, _bcd_math, _mu16u16
Used by: push_eigvl


Function (ROM Call 0x502)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: TIOS_strtol, strlen, XR_stringPtr
Used by: HomeExecute


Function (ROM Call 0x504)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Uses: cfindfield, copensub


Function (ROM Call 0x505)
AMS 2.00 or higher

This identifier has not been documented yet. Please help us out.

Used by: OO_GetAttr, OO_SetAttr


Function (ROM Call 0x606)
AMS 2.08 or higher

This identifier has not been documented yet. Please help us out.

Uses: estack_to_float, get_lb, get_ub, Integer1Index, IntegerMinus1Index, is_negative, is_nonnegative, is_positive, is_real, is_variable, push_approx, push_difference, likely_approx_to_number, top_estack, _bcd_math
Used by: get_ub, did_push_anti_deriv, push_1st_derivative, push_csolve, push_czeros, push_def_int, push_desolve, push_lim, push_max, push_min, push_nsolve, push_solve, push_zeros, push_equals, push_greater_than, push_greater_than_or_equals, push_less_than, push_less_than_or_equals, push_not_equals