Header File Contents

These are the pre-written ASMLIB functions. They are written for some basic functionality in BASIC ASM, they also here to make it easier to comunicate with the TI-OS. At this time there are only a few functions available. However, you have three options which will help you program really powerfull in BASIC ASM.


The ASMLIB functions are sorted by their include file. If you put

#include <asmlib.h>

on top of your source file, there will be a lot of files included from that file.
(You can see this if you run BZC with the -v option.)

Each file declares a lot of functions which, all together, represent the ASMLIB Library. All those functions are listed here.

There is sometimes trouble about what to write in uppercase, and what in lowercase. All the build-in commands must be written in UPPERCASE. All the functions on this page (and everything else in BASIC ASM) can be written how you like it the most (case unsensitive). These function are written in lowercase by default, but if you choose to write it in an other way, it is also possible.

Now, let's start!.


tios.h

tios.h internally calls romcalls.h and sysvars.h, which declare all the TI-OS romcalls, and (almost) all TI-OS sysvars and consts. Besides this, tios.h has no real function.


math.h

math.h has a few mathematical functions, which allow the compiler to multiply, divide and find the remainder while dividing. When you use the *, / or % operators while programming, the compiler calls those functions internally.


time.h

time.h has only one function, the functions sleep.

sleep

Syntax:

 

sleep <number>

sleep is a so called "slowdown-routine". It's only purpose is slowing down the executions of your program at one point. It accepts a number which indicates how long the pause must be.
If you use 1, you almost can't see any result, if you use 4, you see a little pause and if you use 255 (or $ff), which is the maximum, you think your calculator has stopt working.


io.h

io.h has a collection of functions which are for text input and output.

cls

Syntax:

 

cls

cls is one of the easiest functions available. It clears the screen, clears the text-buffer and locate the cursor at the upperleft of the screen.

locate

Syntax:

 

locate <row> <column>

locate sets the cursor position to a specified location. Since your calculator has a text screen of 8x16, you may only use 0 to 7 as <row> and 0 to 15 as <column>.

You can use the special value NumRight as <column>. This has the result that, if you display a numerical value, this is right-aligned in your screen.

locnum

Syntax:

 

locnum

locnum sets the column of the cursor postition to the special value NumRight, without changing the current row.

putc

Syntax:

 

putc <character>

putc displays a single character on the current cursor position and advances this position. <character> is the numerical value of a character, which can be stored in a variable of the BYTE type. You can also use the function get, which is discussed later.

puts

Syntax:

 

puts <string>

puts displays a character string on the current cursor position and advances this position. <string> is an string constant, or a pointer (stored in a variable of the type INT) to a zero-terminated character string.

dispnum

Syntax:

 

dispnum <number>

dispnum displays a number in a field of 5 character on the cursor position, and advances this position. <number> may be a BYTE, an INT a calculation or a pointer-address (which is internally also handled as an INT).

printnum

Syntax:

 

printnum <number>

printnum displays a number (again in a field of 5 character) right-aligned on the current row, and scrolls to the next line. <number> may be a BYTE, an INT a calculation or a pointer-address (which is internally also handled as an INT).

printf

Syntax:

 

printf <format_id> <data>

printf is probably the most complicated function of this file. It displays a number, character or character-string (given by <data>) and scrolls to the next line. Information about what to display is given by the <format_id>, which can be one of the folowing special values: num, str or char.

This function is called by the buildin command PRINTF. If you want to display a single variable, you better use this function, which auto-detects, what to display. However, if you want to display the result of a calculation or a function-returned value, you only can use this native function printf. When you want to display a single character, you also need to use printf char ..., because PRINTF would detect is as a number (since it has been declared as BYTE).


string.h

string.h has a collection of functions for character string manipulation. You can compare it with the string.h header file for C.

strlen

Syntax:

 

<variable> = strlen <string>

strlen returns the length of a character string, including the terminating zero.

strcpy

Syntax:

 

strcpy <target> <source>

strcpy copies an entire string (including the terminating zero) from <source> to the memory location <target>. You must only think about one thing: You have to declare enough memory space with the MEM command, or there is a big chance your calculator will sooner or later crash.

strncpy

Syntax:

 

strncpy <target> <source> <max_chars>

strncpy is very similar to strcpy, with the only difference that is copies maximal <max_chars> of characters and puts a terminating zero after it. If the number of characters in your source string is lower or equel to <max_chars>, this function is similar to strcpy.

strcat and strncat

Syntax:

 

strcat <target> <source>
strncat <target> <source> <max_chars>

strcat and strncat copy the source string <source> after the target string <target>. Again, strncat will maximal copy <max_chars> characters.

pointer.h

pointer.h has a collection of functions basic pointer management. It makes it possible to work with pointers, altough it doesn't work very optimal.

get

Syntax:

 

<variable> = get <mem_loc>

get returnes a BYTE value which is currently stored at the memory location <mem_loc>. <mem_loc> should be a variable of the INT-type, or a STRING. You can assign the location of a STRING or MEM-pointer to a variable using to normal = command:

MEM 3 memptr
STRING str1 = "Hello"
INT pointer

pointer = memptr
pointer = str1

or assign the address of an BYTE or INT using the special operator &:

BYTE bt
INT number
INT pointer

pointer = &number
pointer = &bt

Note: when you use the special operator &, you should NOT put any space or tab between the operator and the variable.

getint

Syntax:

 

<variable> = getint <mem_loc>

getint is the older brother of get, with the only difference getint reads and returns a two-byte-length INT value instead of a one-byte-length BYTE value.

put and putint

Syntax:

 

put <location> <byte>
putint <location> <int>

put and putint write a value to a memory location <location>. Again: put writes a BYTE-value and putint an INT-value. This also means that is you use putint, you write to two bytes in the memory, you should remeber this and declare enough bytes when you use this function.

menu.h

menu.h is a special programmers toy, it has a prewritten menu routine, which let you easily create and use a menu (up to 255 menu options!) in your programs. In the next releases we expect to have more of these header files, which also should have functions for dialogs and other GUI elements.

menuoption and menu
 
Syntax:
 

// Declarations

MEM <menu_name> <length: (1 + # of menu options) * 2>

menuoption <menu_name> 0 <string_menutitle>

menuoption <menu_name> <option_number> <string_name>

menuoption <menu_name> <option_number> <string_name>

...

// Call the menu

<variable> = menu <menu_name> <# of menu options>

A menu first must have space allocated to it to store the locations of the various strings it uses. Those strings must be declared prior to their use in declaring menu options. A title is specified with <option_number> = 0; the first menu option is <option_number> = 1, and so forth.

The routine returns the chosen option number, or (if CLEAR was pressed, $ffff or, in decimal: 65535).

See the example file menu.bzc for an exapmle of using menus.

Alternatives for the ASMLIB functions.

Using the TI-OS Romcalls

The people who wrote the TI-OS created a lot of so called Romcalls. All of these romcalls can be used by programmers. Most of them require so called registers as argument. An example of this is the romcall _DispHL, which displays the register HL on the screen. The ASMLIB function dispnum (and also several others, even a part of printf) is based on this romcall. You can call it in the following way:

HL = <variable>
_DispHL

There are a lot of these romcalls and they are all declared for you to use in the ASMLIB headers. However, because there are soo many of them, and it has not much to do with this compiler, I am not going to give you a list in this manual. But there are many people who have done this, google and a little time should help wonderfull.

Write your own functions

After a while you find out that there are some things you do many times. In that case it is a great help to put a set of instructions in a special routine, in other words: write your own functions. For information about writing your own functions, please look at the small tutorial which comes with this manual. You can also choose the put romcalls in your function. Here you see the official ASMLIB dispnum function as example:

FUNCTION dispnum ARG 1

FSTART dispnum HL
_DispHL
FEND

Because we directly put the given argument in HL we safe a lot of CPU cycles, and program space. There are only a few conditions you mus keep in mind:

Ofcourse you can also use the ASM...ENDASM command in functions.

if you have many functions of your own, you can also put them in an include file of yourself. The only thing to do is create a file with the extension .h, and put all your functions in it. After you did this, you can use it by putting it in your source directory (folder), or you can put it in the special BZC Include File Folder, which can be at two places:

If you think you made something which can also be helpfull for other programmers, please send it to: ideas@hofhom.nl If we also think it is helpfull, we include it in the ASMLIB Library, and... your name shall be put on the credits list ofcourse.