THE SYSTEM LIBRARIES -------------------- Access to the Amiga's underlying operating system is through a variety of run-time libraries, which contain in total about 400 different routines. To find out how to use them you will have to refer to the ROM Kernel Manual, or similar Amiga documentation. The AmigaTools drawer contains support files for accessing the Amiga's run-time libraries from within your True BASIC programs. These files were generated for you from the version 2.04 .fd files supplied by Commodore. In addition, the AmigaTools drawer contain the amiga* library, which makes possible access to all the others. To make a particular run-time library available to your True BASIC programs, you must first either LOAD it, along with amiga*, into your workspace, or refer to it in a LIBRARY statement, like this: LIBRARY "{AmigaTools}graphics*", "{AmigaTools}amiga*" The above instruction makes the Amiga's "graphics.library" available to your program. Note that the amiga* library must always be mentioned last. All system routines on the Amiga are functions, just as in C, so you will have to declare them before using them. True BASIC requires that all functions be declared before they are used. For example, the following instruction declares the popular Text function of the Amiga's "graphics.library": DECLARE FUNCTION Text All arguments for the Amiga's system routines are integers, and they usually represent the addresses of data needed by the particular function being invoked. In the case of the dos*, exec*, intuition*, and graphics*, the calling sequences are exactly the same as the C versions documented in the ROM Kernel Manual. For example, the following instruction invokes the Amiga's Text routine from the graphics* library: LET Success = Text(RastPort, StringAddress, Count) Note that the first two arguments represent addresses and are obtained by invoking the Addr function of the amiga* library, as explained below. In the case of all other libraries, you must explicitely open the system library by using exec*'s OpenLibrary() function, then invoke the particular function you want by using the address of the library as its last argument. Thus your calls in True BASIC will contain one extra argument compared to the ones in the ROM Kernel Manual. Certain system routines require blocks of data as arguments, which are usually built up as structures in C. To build them up in True BASIC you can use the PackB() routine. You must be careful however. True BASIC uses a sophisticated storage management scheme which allows it to keep only one copy of a certain piece of data, even though it may represent the contents of several variables. This never causes problems as long as you stick with True BASIC, but the system calls don't know about True BASIC's scheme, and won't cooperate with it. To avoid problems, use the ZeroString subroutine from the amiga* library to create strings with private blocks of data. Many of the strings used by the system routines are supposed to be null-terminated. True BASIC strings are not. So, you should use the Nullt$ and UnNullt$ functions of the amiga* library as necessary. Be careful when calling the Amiga's system routines. If invoked incorrectly they may crash your system. THE LOW LEVEL UTILITIES, amiga* ------------------------------- This library of low level utilities contains routines used by most of the system libraries. This library must be mentioned last in the LIBRARY statement if you use any of the AmigaTools libraries. Some of the routines in amiga* may be useful on their own. Nullt$ ........ Converts from True BASIC to null-terminated string. UnNullt$ ...... Converts from null-terminated to True BASIC string. ZeroString .... Create a unique, zeroed-out string. Addr .......... Returns the address of a string. CurrentWindow . Returns a pointer to the current Intuition Window. CurrentRPort .. Returns a pointer to the current RastPort. PackL ......... Packs 32 bits into a string. PokeB ......... Packs a byte. PeekB ......... Peeks a signed byte. UPeekB ........ Peeks an unsigned byte. PokeW ......... Pokes a word. PeekW ......... Peeks a signed word. UPeekW ........ Peeks an unsigned word. PokeL ......... Pokes a longword. PeekL ......... Peeks a signed longword. UPeekL ........ Peeks an unsigned longword. S_Call ........ Calls a system routine. ToString ...... Copies data to a string. FUNCTION Nullt$(string$) Nullt$ appends a CHR$(0), or NULL, to a string$ and returns the result. This is useful for making a True BAISC string into the kind required by many of the Amiga's system routines. EXCEPTIONS: None. FUNCTION UnNullt$(string$) UnNullt$ truncates its argument string$ just before the first NULL, if any. This is useful for converting from system-type strings to True BASIC strings. EXCEPTIONS: None. SUB ZeroString(string$,length) ZeroSting makes its argument, sting$, a unique string of length bytes. Each byte contains a zeros, or NULL. EXCEPTIONS: None. FUNCTION Addr(string$) Addr returns the hardware address of the first byte of a string. Since all True BASIC strings are longword-aligned, this number will be 0 mod 4. EXCEPTIONS: None. FUNCTION CurrentWindow CurrentWindow returns the hardware address of True BASIC's Intuition Window structure. This is either the smaller, resizeable OUTPUT window, or a full-screen output window. The address is valid until the program stops, or until it executes a SET MODE instruction. EXCEPTIONS: None. FUNCTION CurrentRPort CurrentRPort returns the hardware address of True BASIC's RastPort. This is the RastPort that True BASIC would currently draw into. The address is valid until the program stops, or until it executes a SET MODE instruction. EXCEPTION: None. SUB PackL(data, string$) PackL performs the equivalent of CAll PACKB(string$,1,32,data) except that it allows data to be unsigned, that is, greater than 2^31-1. EXCEPTIONS: None. SUB PokeB(Addr, data) FUNCTION PeekB(addr) FUNCTION UPeekB(addr) SUB PokeW(addr, data) FUNCTION PeekW(addr) FUNCTION UPeekW(addr) SUB PokeL(addr, data) FUNCTION PeekL(addr) FUNCTION UPeekL(addr) These routines are used to peek and poke data in byte, word, and longword sizes. The word and longword varieties actually use MOVE.W and MOVE.L instructions, so they're suitable for tinkering with the custom hardware's registers. However, this also means that they must be used on even addresses only. The byte varieties can be used on any address. The unsigned peeks treat the data as unsigned. The normal peeks will return a negative number if the high-order bit of the datum is set. EXCEPTIONS: None. SUB S_CALL(offset, flags, s$) S_CALL is used to make Amiga system calls from True BASIC. You don't normally invoke this routine yourself, it's done for you by the various AmigaTools libraries, like exec*, intuition*, graphics*, ... etc. Offset is the offset from the library pointer for the system call. Flags is the register list mask for the control-mode MOVEM instruction. S$ is the register block for the MOVEM. If the flag for register A6 is not set in flags, the first longword of this block is the offset into the user vector for the library pointer. Otherwise, the library pointer is loaded into A6 from the register block. After the system routine returns, register D0 is stored in the first longword of s$. This means that S_CALL cannot be used to call system routines that return double-word quantities, like the IEEE, double-precision floating point math routines. EXCEPTIONS: None. SUB ToString(a, p$, d$) This routine fills the string d$ with data from memory. The length of d$ is not changed. The address from which data are fetched is determined by p$ and a. If p$ is the NULL string, a is an offset in the user vector. Otherwise, p$ is a four-byte string containing a pointer, and a is an offset from that pointer. EXCEPTIONS: None.