                         
                                           
                                
                                         
                            
  (c) by Andreas Ess, Sam Davies, Jimmy Mrdell, Austin Butler and Mel Tsai

This document describes the ton of function Usgard provides for the programmer.
For each function, Input, Output and Traps and an example are written down here.
If you've got further questions, contact:
 ess.andreas@computerhaus.at
 sdavies@mail.trilogy.net
 mja@algonet.se
 corndog@flash.net
 tsaimelv@pilot.msu.edu

Information listed here is (c) by Andreas Ess, Sam Davies, Jimmy Mrdell,
Austin Butler and Mel Tsai. This is a reference about all calls in USGARD.H,
except the ZShell support calls (check out ZSFNLIB.DOC for those). Note that
all these calls are made by a simple 'call' instruction.

In the function list, you'll find the following acronyms:

 CF = Carry Flag set        ZF = Zero Flag set
 NC = Carry Flag cleared    NZ = Zero Flag cleared

[- FUNCTION INDEX --------------------------------------------------------]

   1. Usgard interrupt functions
      * INT_INSTALL   ; Installs an interrupt located at HL
      * INT_REMOVE    ; Remove last installed interrupt
      * INT_CLEAN     ; Clears all installed interrupts

   2. Usgard variable functions
      * VAR_NEW       ; Creates a new variable
      * VAR_DELETE    ; Deletes a variable (std only)
      * VAR_EXEC      ; Executes a variable
      * VAR_GET       ; Gets the memory location of a variable
      * VAR_RESIZE    ; Resizes a variable (std only)

   3. Usgard append functions
      * APPEND        ; Appends source to Usgard (std only)
      * UNAPPEND      ; Removes the last appended source (std only)
      * CHECK_APPEND  ; Compare source with appended source (std only)

   4. Usgard ROM calls
      * READ_KEYPAD   ; Reads the keypad through ports
      * RANDOM        ; Generates random numbers
      * VAR_LENGTH    ; Returns actual length of a variable
      * ASCIIZ_LEN    ; Returns the length of a Zero terminated string
      * NEG_BC        ; Negates the number in BC
      * MUL_HL        ; Multiplies H with L (H<>0)
      * FREEMEM       ; Returns free memory on TI

   5. Other Usgard functions
      * OTH_PAUSE     ; Pause until enter is pressed
      * OTH_CLEAR     ; Clears an area in the memory
      * OTH_EXIT      ; Exit the current program (no need for pops)
      * OTH_ARROW     ; Read arrowkey, 2nd, Exit & More status (multikey)
      * OTH_SHUTDOWN  ; Shutdown the calc
      * UPDATE_APD    ; Updates APD to 3,5 minutes
      * SEARCH_VAT    ; Scans the VAT for variables of type A
      * DM_HL_DECI    ; Display HL in menu style, right justified

(std only = works only in the STANDARD Usgard installation, not the LITE one)

[- USGARD INTERRUPT FUNCTIONS --------------------------------------------]

*** INT_INSTALL   - installs an interrupt handler

Input:     HL = pointer to interrupt handler that will be installed
Output:    If CF, then the installation failed (already 5 interrupts installed)
           If NC, the installation succeeded, and Interupt Mode 2 is set
Registers: AF, BC, DE, HL destroyed
Traps:     If you use IX/IY in an interrupt handler, don't forget to save them
           before leaving the interrupt handler.
Example:

 ld hl,&ScreenCapt
 call INT_INSTALL

ScreenCapt:
 ld a,%11011111   ; Mask out all keys except GRAPH
 out (1),a
 in a,(1)
 bit 6, a         ; GRAPH pressed?
 ret nz
 ld hl,VIDEO_MEM  ; Copy the VIDEO_MEM to the GRAPH_MEM
 ld de,GRAPH_MEM
 ld bc,1024
 ldir
 ret


*** INT_REMOVE   - removes the last installed interrupt handler

Input:     -
Output:    If CF, no interrupts was installed
           If ZF, the interrupt removed was the last one
Registers: AF, BC, DE, HL destroyed
Traps:     -
Example:

 call INT_REMOVE


*** INT_CLEAN   - removes all interrupt handlers installed with INT_INSTALL

Input:     -
Output:    Interupt Mode=1
Registers: AF, BC, DE, HL destroyed
Traps:     This will disable all TSR programs installed, but they will
           still be a part of the Usgard string, ie waste memory.
Example:

 call INT_CLEAN


[- USGARD VARIABLE FUNCTIONS ---------------------------------------------]

*** VAR_NEW   - generates a new variable

Input:     HL = pointer to name of variable to be created (Zero terminated)
           A = variable type ($0C=string)
           BC = size
Output:    If CF, then there was to little memory left.
Registers: AF, BC, DE, HL destroyed
Traps:     You MUST check that the variable doesn't exist, because else
           you will create two variables with the same name :-/ The calc
           won't crash (you'll have to delete the same variable twice) though.
Example:

 ld hl,&VarName
 call VAR_NEW
 jr c,Failed

VarName:
 .db "testvar",0


*** VAR_DELETE (std only)   - deletes a variable

Input:     HL = pointer to name of variable to be deleted (Zero terminated)
Output:    If CF, variable not found OR user uses Usgard LITE
           If NC, variable destroyed
Registers: AF, BC, DE, HL destroyed
Traps:     If this function call is made from a subroutine in a program,
           the routine must have been called to using RCALL_() else the
           subroutine may return to the wrong address (due memory update)
Example:

 ld hl,&VarName
 call VAR_DELETE
 jr c,VarNotFound

VarName:
 .db "testvar",0


*** VAR_EXEC   - executes a variable

Input:     HL = pointer to name of variable to be executed
Output:    If CF the variable wasn't found, else the var got executed
Registers: All registers destroyed
Traps:     If the function is called from a subroutine, that subroutine
           should be called to with RCALL_() (in std version only)
           USG_BITS gets cleared
Example:

 ld hl,&VarName
 call VAR_EXEC
 jr c,Failed

VarName:
 .db "runme",0


*** VAR_GET   - gets the location of a variable (data and VAT location)

Input:     HL = pointer to name of variable to be found
Output:    HL = pointer to variable data (length of variable skipped)
           DE = pointer to VAT entry
           If CF, the variable was not found
Registers: AF, DE, HL destroyed
Traps:     -
Example:

 ld hl,&VarName
 call VAR_GET
 jr c,NotFound

VarName:
 .db "findme",0


*** VAR_RESIZE (std only)   - changes the size of a variable

Input:     HL = pointer to name of variable to be found
           BC = new size
Output:    If CF, variable not found OR user runs LITE version OR out of mem
           If NC, the variable was resized successfully.
Registers: AF, BC, DE, HL destroyed
Traps:     Resizing a REAL or a CPLX doesn't affect them. Resizing a MATRX
           or a VECTR crashes the calc for some reason. Resizing a list could
           crash the calc later (when viewing) if the list contains illegal
           values.
Example:

 ld hl,&VarName
 ld bc,1000
 call VAR_RESIZE
 jr c,Failed

VarName:
 .db "savegame",0


[- USGARD APPEND FUNCTIONS -----------------------------------------------]

*** APPEND (std only)   - appends code to the end of the Usgard string

Input:     HL = pointer to source to be attached
           BC = length of code to be attached
           DE = pointer to description
Output:    If CF, failed (too little memory left OR user runs LITE version)
           HL = pointer to source in the Usgard string.
Registers: AF, BC, DE, HL destroyed
Traps:     -

Example:

 ld hl,&Source
 ld bc,SourceEnd-Source
 ld de,(PROGRAM_ADDR)  ; Program name as description
 call APPEND

Source:
 ld hl,$FC00
 .
 .
 ret
SourceEnd:


*** UNAPPEND (std only)   - removes the last appended code

Input:     -
Output:    If CF, no code to unappend or user runs LITE version
Registers: AF, BC, DE, HL destroyed
Traps:     Use CHECK_APPEND to be sure it's really your code you unappend.

Example:

 call UNAPPEND


*** CHECK_APPEND (std only)   - checks if the last appended code is your code

Input:     HL = pointer to description
Output:    If ZF, the program is not resident
           If CF, the program is the latest resident program installed
           If neither, program is installed, but not the latest program
           If NZ, HL = pointer to code in Usgard string
Registers: AF, BC, DE, HL destroyed
Traps:     -

Example:

 ld hl,(PROGRAM_ADDR)
 call CHECK_APPEND
 jr z,InstallRoutine
 jr c,RemoveRoutine


[- USGARD ROM CALLS ------------------------------------------------------]

*** READ_KEYPAD   - reads the keypad trough ports

Input:     A = keygroup
Output:    A = B = keydata
Registers: AF, B destroyed
Traps:     -
Example:

 ld a,$BF
 call READ_KEYPAD
 bit 5,a
 jr z,SecondPressed


*** RANDOM   - creates random numbers

Input:     -
Output:    AF, BC, DE, HL = random numbers
Registers: AF, BC, DE, HL destroyed
Traps:     -
Example:

 call RANDOM


*** VAR_LENGTH   - Returns actual length of a variable

Input:     A = type of var
           HL = pointer to data space
Output:    DE = length in bytes
Registers: A destroyed
Traps:     -
Example:

 ld hl,&varName
 call VAR_GET
 dec hl
 dec hl  ; Dec HL with 2 to make it point at the data space
 call VAR_LENGTH


*** ASCIIZ_LEN   - Returns the length of a Zero terminated string

Input:     HL = pointer to string
Output:    BC = length of string
Registers: BC destroyed
Traps:     -
Example:

 ld hl,&textstring
 call ASCIIZ_LEN

textstring:
 .db "Hello world!",0


*** NEG_BC   - Negates the number in BC

Input:     BC = number
Output:    HL = BC = -BC
Registers: A=0, BC, HL destroyed
Traps:     -
Example:

 ld bc,-50
 call NEG_BC


*** MUL_HL   - Multiplies H with L, answered stored in HL

Input:     H = factor, L = factor
Output:    HL = H*L
Registers: B, DE, HL destroyed
Traps:     If H=0, then HL = 256*L
           If L=0, then HL = H*0 = 0
Example:

 ld hl,$0508
 call MUL_HL  ; HL = 40


*** FREEMEM   - Returns free memory on TI

Input:     -
Output:    HL = free memory
Registers: BC, HL destroyed
Traps:     -
Example:

  call FREEMEM
  call D_HL_DECI ; Show free memory


[- OTHER USGARD FUNCTIONS ------------------------------------------------]

*** OTH_PAUSE   - waits until ENTER is pressed

Input:     -
Output:    A=K_ENTER
Registers: AF destroyed
Traps:     -

Example:

 call OTH_PAUSE


*** OTH_EXIT   - Exit the program. No need for pops!

Input:     -
Output:    -
Registers: Registers destroyed when returning to previous program
Traps:     -
Example:

 call OTH_EXIT


*** OTH_CLEAR   - Clears memory

Input:     HL = pointer to area to zero
           BC = size-1 to zero
Output:    Area cleared
Registers: BC, DE, HL destroyed
Traps:     -
Example:

 ld hl,GRAPHMEM
 ld bc,1024-1
 call OTH_CLEAR


*** OTH_ARROW   - Scans for arrowkeys, 2nd, Exit and More (multikey)

Input:     -
Output:    A=key byte
Registers: AF destroyed
Traps:     -
Example:

 call OTH_ARROW
 bit 6,a
 call z,OTH_EXIT

After the call, the following information can be read from the A register:

  bit 0 = 0 = down arrow pressed
  bit 1 = 0 = left arrow pressed
  bit 2 = 0 = right arrow pressed
  bit 3 = 0 = up arrow pressed
  bit 5 = 0 = 2nd pressed
  bit 6 = 0 = Exit pressed
  bit 7 = 0 = More pressed


*** OTH_SHUTDOWN   - shutdown the calc

Input:     -
Output:    -
Registers  AF destroyed
Traps:     -
Example:

 call OTH_SHUTDOWN


*** UPDATE_APD   - update the APD to 3,5 minutes

Input:     -
Output:    -
Registers: HL destroyed
Traps:     -
Example:

 call UPDATE_APD
 ld (iy+8),$8C  ; Enable APD


*** SEARCH_VAT   - scans the VAT after a certain variable type

Input:     HL = pointer to start location of scanning in VAT
           A = variable type to find
Output:    HL = pointer to next VAT location
           DE = pointer to variable data area
           VATname = name of found variable
           If CF, no variable of type A was found
Registers: AF, BC, DE, HL destroyed
Traps:     -
Example:

 ld hl,VAT_Start-10   ; Skip the first entry, the Usgard string itself
SearchPrgm:
 ld a,$12             ; $12 = program
 call SEARCH_VAT
 jr c,TypeNotFound
 push hl
 .
 .
 pop hl
 jr SearchPrgm
TypeNotFound:


*** DM_HL_DECI   - display HL decimal, menu style, right justified

Input:     HL = number to display
           ($8333) = display location
Output:    HL gets displayed
Registers: AF, DE, HL destroyed
Traps:     -
Example:

 ld hl,0
 ld ($8333),hl
 ld hl,1234
 call DM_HL_DECI



THAT'S ALL FOLKS!

No part of Usgard may be disassembled, remove  or altered without prior
written permission by the authors. In no way can Andreas Ess, Sam Davies,
Jimmy Mrdell, Austin Butler & Mel Tsai be held liable resulting through the
use or misuse of this product.
