

                  MACROs FOR TOS CALLS (GEMDOS, BIOS & XBIOS)
                      Compiled by Peter Hibbs for ICTARI

                      For use with MACRO file TOSMACRO.S

    Version 1. 15-10-1993.

    Note that registers d0-d2 and  a0-a2   may   be  corrupted by all these
    MACROs and should  be  saved   if   necessary  before  using any MACRO.
    Register d0 is normally used  to   return   information from a TOS call
    and is tested with the   tst.w   instruction immediately before exiting
    each MACRO. If the function requires to  test  d0 for a value after the
    call, a branch instruction can be  executed  without having to test the
    register again. For  example  the   f_close   MACRO  returns a negative
    value in d0.w if the call  failed   so   the main program can branch on
    return from the MACRO as follows :-

                   f_close         try to close a file
                   bmi     error   branch if negative value in d0.w

    Note, however,  that  if  the   value    is   returned   in   the whole
    register (longword), it should be  tested  again  after returning  from
    the MACRO. See ATARI documentation for  more  information  on  the  TOS
    calls  and   file  MACROTUT.TXT  for   information   on   how   to  use
    MACROs. The MACRO names used  in  this  file  are  the  same  as  those
    used  in the back of the  DevPac   assembler manual  (except for mfpint
    which  appears twice, XBIOS 31 has  been  changed to xbtimer)  and  the
    parameters are used in the same order.

        ------------------------ GEMDOS (TRAP #1) ---------------------

      0 ($0)       Terminate process (old form)
           p_term0

      1 ($1)       Read character from keyboard
           c_conin
           Result- d0.l=key code

      2 ($2)       Write character to screen
           c_conout        char

      3 ($3)       Read character from serial port
           c_auxin
           Result- d0.b=character read

      4 ($4)       Write character to serial port
           c_auxout        char

      5 ($5)       Write character to printer
           c_prnout        char
           Result- d0.w=0 if failed, =-1 if OK

      6 ($6)       Raw I/O to standard I/O
           Input-  char=character to output or =$00FF to read
           c_rawio         char
           Result- d0.w if $00FF passed

      7 ($7)       Raw input from keyboard
           c_rawcin
           Result- d0.l=character read

      8 ($8)       Read character from keyboard, no echo
           c_necin
           Result- d0.l=character read

      9 ($9)       Write string to screen
           c_conws         buffer_addr.l

      10 ($A)      Read edited string from keyboard
           c_conrs         buffer_addr.l

      11 ($B)      Check status of keyboard
           c_conis
           Result- d0.l=-1 if character available, =0 if none

      12 ($C)      Set default drive
           d_setdrv        drive_No
           Result- d0.l=bit map of drives on system

      16 ($10)     Check status of standard output
           c_conos
           Result- d0.l=-1 if console ready, =0 if not ready

      17 ($11)     Check status of printer
           c_prnos
           Result- d0.l=-1 if ready, =0 if not ready

      18 ($12)     Check status of serial port input
           c_auxis
           Result- d0.l=-1 if character waiting, =0 if not

      19 ($13)     Check status of serial port output
           c_auxos
           Result- d0.l=-1 if ready, =0 if not ready

      20 ($14)     Informs GEMDOS of alternative memory (GEMDOS V0.25)
           m_addalt        size.l,address.l
           Result- d0.w=0 if OK, =error code if not OK

      25 ($19)     Get default drive
           d_getdrv
           Result- d0.w=drive number

      26 ($1A)     Set disk transfer address
           f_setdta        buffer_address.l

      32 ($20)     Set Supervisor/User mode
           super
           Result- d0.l=old stack pointer (save for use with 'user' macro)

           user            old_stack.l

      42 ($2A)     Get date
           t_getdate
           Result- d0.w=date value

      43 ($2B)     Set date
           t_setdate       date
           Result- d0.w=0 if OK =error code if not

      44 ($2C)     Get time
           t_gettime
           Result- d0.w=time value

      45 ($2D)     Set time
           t_settime       time

      47 ($2F)     Get disk transfer address
           f_getdta
           Result- d0.l=pointer to disk transfer address

      48 ($30)     Get version number
           s_version
           Result- d0.w=GEMDOS version number

      49 ($31)     Terminate and stay resident
           p_termres       ret_code,bytes.l

      54 ($36)     Get drive free space
           d_free          drive,buffer.l

      57 ($39)     Create a sub-directory
           d_create        address.l
           Result- d0.w=0 if OK =error code if not

      58 ($3A)     Delete a sub-directory
           d_delete        address.l
           Result- d0.w=0 if OK, =error code if not

      59 ($3B)     Set current directory
           d_setpath       address.l
           Result- d0.w=0 if OK, =error code if not

      60 ($3C)     Create a file
           f_create        attribute,filename.l
           Result- d0.w=file handle if OK, d0.l=error code if not

      61 ($3D)     Open a file
           f_open          attribute,filename.l
           Result- d0.w=file handle if OK, d0.l=error code if not

      62 ($3E)     Close a file
           f_close         fhandle
           Result- d0.w=0 if OK, =error code if not

      63 ($3F)     Read a file
           f_read          buffer.l,count.l,fhandle
           Result- d0.l=number of bytes read or error code

      64 ($40)     Write a file
           f_write         buffer.l,count.l,fhandle
           Result- d0.l=number of bytes written or error code

      65 ($41)     Delete a file
           f_delete        filename.l
           Result- d0.w=0 if OK, =error code if not

      66 ($42)     Seek file pointer
           f_seek          mode,fhandle,offset.l
           Result-d0.l=absolute position in file after seek

      67 ($43)     Get/set file attributes
           f_attrib        attribute,get/set,address.l
           Result- d0.w=new attributes or error code

      69 ($45)     Duplicate file handle
           f_dup           standard_handle
           Result- d0.w=new handle or error code

      70 ($46)     Force file handle
           f_force         nstdh,stdh
           Result- d0.w=0 if OK, =error code if not OK

      71 ($47)     Get current directory
           d_getpath       drive,address
           Result- d0.w=0 if OK, =error code if not

      72 ($48)     Allocate memory
           m_alloc         size.l
           Result- d0.l=start address of allocated memory or 0 if error

      73 ($49)     Free allocated memory
           m_free          address.l
           Result- d0.w=0 if OK, =error code if not

      74 ($4A)     Shrink allocated memory
           m_shrink        newsize.l,block.l
           Result- d0.w=0 if OK, =error code if not

      75 ($4B)     Load or execute a program
           p_exec          environ.l,command.l,filename.l,mode
           Result- d0.l depends on mode

      76 ($4C)     Terminate program
           The macro on its own returns a value of zero to calling program
           If a value follows the macro, that value is returned.

           p_term          return_code or nothing

      78 ($4E)     Search for first
           f_sfirst        attribute,filespec.l
           Result- d0.w=0 if found, =-33 if not found

      79 ($4F)     Search for next occurrence
           f_snext
           Result- d0.w=0 if found, =-33 if not found

      86 ($56)     Rename file
           f_rename        newname.l,oldname.l
           Result- d0.w=0 if OK, =error code if not

      87 ($57)     Get/Set file Date & Time stamp
           f_datime        mode,fhandle,buffer.l


        ------------------------BIOS (TRAP #13) -------------------------

      0 ($0)       Get memory parameter block
           getmpb          pointer.l

      1 ($1)       Return device input status
           bconstat        device
           Result- d0.w=0 no characters, =-1 at least one character ready

      2 ($2)       Read a character from a device
           bconin          device
           Result- d0.l=character found

      3 ($3)       Write a character to a device
           bconout         character,device
           Result- d0.w=0 if OK, =error code if not OK

      4 ($4)       Read/Write logical sectors on a device
           rwabs           drive,recno,count,buffer.l,mode
           Result- d0.w=0 if OK, =error code if not OK

      5 ($5)       Set exception vector
           setexc          vecaddress.l,vecnum
           Result- d0.l=old vector entry

      6 ($6)       Get system timer tick interval
           tickcal
           Result- d0.l=timer calibration in milliseconds

      7 ($7)       Get BIOS parameter block for a device
           getbpb          deviceno
           Result- d0.l=pointer to the BPB for this device, =0 if error

      8 ($8)       Return device output status
           bcostat         deviceno
           Result- d0.w=0 if device not ready

      9 ($9)       Return media change status
           mediach         deviceno
           Result- d0.w=0 media definitely NOT changed
                   d0.w=1 media may have been changed
                   d0.w=2 media definitely HAS changed

      10 ($A)      Return bitmap of mounted drives
           drvmap
           Result- d0.l=bitmap of mounted drives (bit 0=drive A)

      11 ($B)      Find state of keyboard 'shift' keys
           kbshift         mode
           Result- d0.w=bitmap of state before call

         -------------------- Extended BIOS (TRAP #14) ----------------

      0 ($0)       Set mouse mode and packet handler
           initmous        mode,parameter.l,vector.l

      2 ($2)       Get physical screen address
           physbase
           Result- d0.l=start of physical screen address

      3 ($3)       Get logical screen address
           logbase
           Result- d0.l=start of logical screen address

      4 ($4)       Get screen resolution
           getrez
           Result- d0.w=screen resolution (0-7)

      5 ($5)       Set screen address & mode
           setscreen       mode,physaddress.l,logaddress.l

      6 ($6)       Set display palette
           setpalette      pointer.l

      7 ($7)       Set display palette
           setcolor        color,colnumber

      8 ($8)       Read sectors from floppy disk
           floprd          count,sideno,trackno,sectno,driveno,buffer.l
           Result- d0.w=0 if OK, =error code if not

      9 ($9)       Write sectors to floppy disk
           flopwr          count,sideno,trackno,sectno,driveno,buffer.l
           Result- d0.w=0 if OK, =error code if not

      10 ($A)      Format a track on a floppy disk
           flopfmt         newdata,magic.l,interlv,sideno,trackno,sector,
                           driveno,buffer.l
           Result- d0.w=0 if OK, =error code if not

      12 ($C)      Write string to MIDI port
           midiws          pointer.l,count

      13 ($D)      Set the MFP interrupt handler
           mfpint          address.l,number

      14 ($E)      Find serial device I/O structure
           iorec           device
           Result- d0.l=pointer to I/O record

      15 ($F)      Configure RS232 port
           rsconf          scr,tsr,rsr,ucr,ctrl,baud
           Result- d0.l=old 68901 configuration

      16 ($10)     Get/Set keyboard translation table
           keytbl          caps.l,shift.l,unshift.l
           Result- d0.l=pointer to structure

      17 ($11)     Get random number
           random
           Result- d0.l=random number

      18 ($12)     Build prototype boot sector
           protobt         execflag,disktype,serialno.l,buffer.l

      19 ($13)     Verify sectors from a floppy disk
           flopver         count,sideno,trackno,sectno,driveNo,buffer.l
           Result- d0.w=0 if OK, =error code if not OK

      20 ($14)     Copy screen to printer
           scrdmp

      21 ($15)     Configure VT52 cursor
           cursconf        flash,function
           Result- d0.w=old flash rate (if function 5)

      22 ($16)     Set IKBD time
           settime         time

      23 ($17)     Get IKBD time
           gettime
           Result- d0.l=time/date

      24 ($18)     Reset keyboard translation tables
           bioskeys

      25 ($19)     Write string to keyboard processor
           ikbdws          pointer.l,number

      26 ($1A)     Disable 68901 interrupt
           jdisint         number

      27 ($1B)     Enable 68901 interrupt
           jenabint        number

      28 ($1C)     Read/Write sound chip registers
           giaccess        register,data
           Result- d0.w=value of register

      29 ($1D)     Reset bit on port A of sound chip
           offgbit         bit_mask

      30 ($1E)     Set bit on port A of sound chip
           ongibit         bit_mask

      31 ($1F)     Configure MFP timer
           xbtimer         vector.l,data,cntrl,timer

      32 ($20)     Initialise sound daemon
           dosound         pointer.l

      33 ($21)     Set/Get printer configuration
           setprt          config
           Result- d0.w=old configuration

      34 ($22)     Get system ACIA dispatch handler
           kbdvbase
           Result- d0.l=pointer to structure

      35 ($23)     Get/Set keyboard repeat & delay
           kbrate          repeat,delay
           Result- d0.w=old delay rate & old repeat rate

      36 ($24)     Print bitmap
           prtblk          pointer.l
           Result- d0.w=error status

      37 ($25)     Wait for vertical sync to occur
           vsync

      38 ($26)     Call supervisor routine
           supexec         where.l

      39 ($27)     Discard AES
           puntaes

    -----------------------------------------------------------------------
    List of MACRO definitions grouped in functions

    Input/output.

           c_conin
           c_conout        char
           c_auxin
           c_auxout        char
           c_prnout        char
           c_rawio         char
           c_rawcin
           c_necin
           c_conws         buffer_addr.l
           c_conrs         buffer_addr.l
           c_conis
           c_conos
           c_prnos
           c_auxis
           c_auxos
           bconstat        device
           bconin          device
           bconout         character,device
           getbpb          deviceno
           bcostat         deviceno
           kbshift         mode
           midiws          pointer.l,count
           iorec           device
           rsconf          scr,tsr,rsr,ucr,ctrl,baud
           keytbl          caps.l,shift.l,unshift.l
           bioskeys
           ikbdws          pointer.l,number
           setprt          config

    Program termination.

           p_term0
           p_termres       ret_code,bytes.l
           p_term          return_code or nothing

    Disk Handling.

           d_setdrv        drive_No
           d_getdrv
           f_setdta        buffer_address.l
           f_getdta
           d_free          drive,buffer.l
           d_create        address.l
           d_delete        address.l
           d_setpath       address.l
           f_create        attribute,filename.l
           f_open          attribute,filename.l
           f_close         fhandle
           f_read          buffer.l,count.l,fhandle
           f_write         buffer.l,count.l,fhandle
           f_delete        filename.l
           f_seek          mode,fhandle,offset.l
           f_attrib        attribute,get/set,address.l
           f_dup           standard_handle
           f_force         nstdh,stdh
           d_getpath       drive,address
           f_sfirst        attribute,filespec.l
           f_snext
           f_rename        newname.l,oldname.l
           f_datime        mode,fhandle,buffer.l
           rwabs           drive,recno,count,buffer.l,mode
           mediach         deviceno
           drvmap
           floprd          count,sideno,trackno,sectno,driveno,buffer.l
           flopwr          count,sideno,trackno,sectno,driveno,buffer.l
           flopfmt         newdata,magic.l,interlv,sideno,trackno,sector,
                           driveno,buffer.l
           protobt         execflag,disktype,serialno.l,buffer.l
           flopver         count,sideno,trackno,sectno,driveNo,buffer.l

    Time and timer functions.

           t_getdate
           t_setdate       date
           t_gettime
           t_settime       time
           tickcal
           settime         time
           gettime
           xbtimer         vector.l,data,cntrl,timer
           vsync

    Interrupt and exception vector control.

           setexc          vecaddress.l,vecnum
           mfpint          address.l,number
           jdisint         number
           jenabint        number

    Screen and palette control.

           physbase
           logbase
           getrez
           setscreen       mode,physaddress.l,logaddress.l
           setpalette      pointer.l
           setcolor        color,colnumber

    Memory control.

           m_addalt        size.l,address.l
           m_alloc         size.l
           m_free          address.l
           m_shrink        newsize.l,block.l
           getmpb          pointer.l

    Miscellaneous.

           super
           user            old_stack.l
           s_version
           p_exec          environ.l,command.l,filename.l,mode
           initmous        mode,parameter.l,vector.l
           random
           scrdmp
           cursconf        flash,function
           giaccess        register,data
           offgbit         bit_mask
           ongibit         bit_mask
           dosound         pointer.l
           kbdvbase
           kbrate          repeat,delay
           prtblk          pointer.l
           supexec         where.l
           puntaes
