QDOS Low-Level Documentation
INTRODUCTION
This document is a collection of different documents from different
sources dealing with low-level details of the QL and QDOS.
TABLE OF CONTENTS
QL Device Names & Related Conventions
QDOS Errors
QDOS Basic Memory Areas
QDOS Memory Map
QDOS Register conventions
CHANNEL- & SCR_-DEFINITION BLOCKS
QDOS Device Driver Headers
QDOS Job Control Headers
QDOS Vectored Calls
Summary of QDOS Traps
CREDITS
Kit Lester ( Most QDOS summeries), Simon Goodwin ( QDOS Traps )
QL Device names & related conventions
-------------------------------------
CON_wXhAxXy_k or
CON_ - default con_448x180a32x16_128
CTLn - see concepts/"joystick"
DEVn 93- GC/p iii n=1 to 8: logical devices attacable to
physical devices or directories
FLPn_*D2h 93- GC/p ix for direct sector access to a HD disk
FLPn_*D4e 93- GC/p ix for direct sector access to an ED disk:
4 means 2048-byte sectors
FLPn_*Dsd 86 Trumpcard see keywords/OPEN
FLPn_name * 86 Trumpcard see keywords/FORMAT
MDVn_name - see concepts/"Microdrives"
NET - see concepts/"network"
NETd_s - see concepts/"devices"
NETI_0 84 TK1/tk2 device to receive broadcast, with
2.4,22 buffer size 2kb less than memory
NETI_0_buffersize 84 TK1/tk2 as NETI_0, with given buffer size in kb
2.4,22
device for input from the given
NETI_station 84 TK1/tk2 station: if station=this machine, input
2.4,22
from any station
NETO_0 84 TK1/tk2 device for broadcast to all stations
2.4,22
NETO_station 84 TK1/tk2 device for output to the given station
2.4,22
Nn_dev_ 84 TK1/tk2 dev_ on network node n
2.4,22
PAR 95 SGC/p II Parallel port
PAR 95 SGC/p VI Parallel port connector details
PARF 95 SGC/p II Parallel port with FF at CLOSE
PIPE_ - input pipe whose channel is in D3
(assembler)
PIPE_n - output pipe with a n-byte buffer
RAMn 86 TK2 ramdisk
ROM1_ 98 RomDisq RomDisq (Flash-disk, from Firshman)
SCR_wXhAxXy or SCR_ - default ser_448x180a32x16
SERnphz - default ser1r
WINn 93- GC/p vii ...
QDOS Errors
-----------
Returned in D0 from TRAPs, Vectored Calls, and Basic extensions
-1 ERR_NC Operation not complete
-2 ERR_NJ Not a (valid) job
-3 ERR_OM Out of memory
-4 ERR_OR Out of range
-5 ERR_BO Buffer overflow
-6 ERR_NO Channel not open
-7 ERR_NF File or device not found
-8 ERR_EX File already exists
-9 ERR_IU File or device already in use
-10 ERR_EF End of file
-11 ERR_DF Drive full
-12 ERR_BN Bad device
-13 ERR_TE Transmission error
-14 ERR_FF Format failed
-15 ERR_BP Bad parameter
-16 ERR_FE File error
-17 ERR_EX Expression error
-18 ERR_OV Arithmetic overflow
-19 ERR_NI Not implemented (yet)
-20 ERR_RO Read only
-21 ERR_BL Bad line of Basic
QDOS Basic Memory Areas
-----------------------
There are 12 distinct areas:
LOW ADDRESS
job header -- Same layout as any other JB area. $68 bytes.
SV_BASIC points to the base of this area.
-- Interpreter work variables. fixed length:
includes pointers to other areas, which may be
SuperBASIC work area moved around. During interpretation, A6 points
to the base of this area: the BV values are the
offsets: the whole area can be moved (hence A6
is changed to new base address). See below.
-- For access to SuperBasic variables and
name table parameters. A table of 8-byte entries: see
below.
-- For access to SuperBasic variables and
namelist parameters. Each entry is a BYTE character
count, then the characters of the name [ALL
OTHER STRINGS USE*WORD* -LENGTH COUNTS].
-- For access to SuperBasic variables and
variable values area parameters. A heap in which the values of the
variables are cstored: see below for the formats
of the entries.
channel table -- For SuperBASIC channels. See below.
-- Convenient for reserving space in added
arithmetic (RI) stack routines: and for passing parameters from
SuperBASIC to routines. See above.
token list -- Not described in TechRefMan
line number table -- Not described in TechRefMan
program file -- Not described in TechRefMan
return list -- Not described in TechRefMan
buffer -- Not described in TechRefMan
HIGH ADDRESS
1 SuperBASIC work area
$00 BC_START Relative to SV_BASIC
- - *** START OF POINTERS ***
$00.L BV_BFBAS Buffer base
$04.L BV_BFP Buffer running pointer
$08.L BV_TKBAS Token list
$0C.L BV_TKP ?
$10.L BV_PFBAS Program file
$14.L BV_PFP ?
$18.L BV_NBAS Name table
$1C.L BV_NTP ?
$20.L BV_NLBAS Name list
$24.L BV_NLP ?
$28.L BV_VVBAS Variable values
$2C.L BV_VVP ?
$30.L BV_CHBAS Channel name
$34.L BV_CHP ?
$38.L BV_RTBAS Return table
$3C.L BV_RTP ?
$40.L BV_LNBAS Line number table
$44.L BV_LNP ?
- - *** CHANGE OF DIRECTION ***
$48.L BV_BTP Backtrack stack during parsing
$4C.L BV_BTBAS ?
$50.L BV_TGP Temporary graph stack during parsing
$54.L BV_TGBAS ?
$58.L BV_RIP Arithmetic stack
$5C.L BV_RIBAS ?
$60.L BV_SSP System stack
$64.L BV_SSBAS ?
- - *** END OF POINTERS ***
$68.W BV_LINUM Current line number
$6A.W BV_LENGTH Current length
$6C.B BV_STMNT Current statement on line
$6D.B BV_CONT Continue ($80) or stop (0) processing
$6E.B BV_INLIN Processing in-line clause (loop=1, other=$FF) or
not (=0)
$6F.B BV_SING Single line execution ON ($FF) or OFF (0)
$70.W BV_INDEX Name tab row of last inline loop index read
$72.L BV_VVFREE First free space in variable value table
$76.L BV_SSSAV Saved sp for out/mem to back to
$7C.? BV_UPROC MINERVA: Set address of use trace routine [p
ASM.5-]
$80.L BV_RAND Random number
$84.L BV_COMCH Command channel
$88.W BV_NXLIN Which line number to start after
$8A.B BV_NXSTM Which statement to start after
$8B.B BV_COMLN Command line saved ($FF) or not (0)
$8C.W BV_STOPN Which stop number set
$8E.B BV_EDIT Program has been edited ($FF) or not (0)
$8F.B BV_BRK There has been a break (0) or not ($80)
$90.B BV_UNRVL Need to unravel ($FF) or not (0)
$91.B BV_CNSTM Statement to CONTINUE from
$92.W BV_CNLND Line to CONTINUE from
$94.W BV_DALNO Current DATA line number
$96.B BV_DASTM Current DATA statement number
$97.B BV_DAITM Next DATA item to read
$98.W BV_CNIND Inline loop index to CONTINUE with
$9A.B BV_CNINL Inline loop flag for CONTINUE
$9B.B BV_LSANY Whether checking list ($FF) or not (0
$9C.W BV_LSBEF Invisible top line
$9E.W BV_LSBAS Bottom line in window
$A0.W BV_LSAFT Invisible bottom line
$A2.W BV_LENLN Length of window line
$A4.W BV_MAXLN Max. number of window lines
$A6.W BV_TOTLN Number of window line so far
$AA.B BV_AUTO Whether AUTO/EDIT is on ($FF) or off (0)
$AB.B BV_PRINT Print from prtok ($FF) or leave in buffer (0)
$AC.W BV_EDLIN Line number to edit next
$AE.W BV_EDINC Increment on edit range
$B0 to $100 - See p163 of the Tech Ref Man
Basic channel definitions: (1) see later (2) p164 Tech Ref Man
2 NAME TABLE ENTRIES
The entries can be of the following kinds:
bytes 7-4 bytes 3-2 byte 1 byte 0 [1] Kind
value pointer name pointer $00 $01/02/03 Unset typed value
ptr to RI stack -1 $01 $01/02/03 Typed expression [2]
value pointer name pointer $02 $01/02/03 Typed value
value pointer -1 $03 $00 Substring [2]
value pointer name pointer $03 $01/02/03 Typed array
line # in msw name pointer $04 $00 SuperBASIC procedure
line # in msw name pointer $05 $01/02/03 SuperBASIC typed
function
value pointer name pointer $06 $02 REPeat loop index
value pointer name pointer $07 $02 FOR loop index
abs address name pointer $08 $00 Machine code procedure
abs address name pointer $09 $00 Machine code function
* A positive name pointer is to an entry in the name list: -1 is a
nameless item: other -ve name pointers are to another entry in the name
table of which this entry is a copy.
* A positive value pointer is to an entry in the variable values area: -1
is for an undefined value.
* Because the areas are movable, the pointers are offsets: for the RI
stack the offsets are from the high-address base; for other areas it is
from the low-address base.
[1] Byte 0 has bitwise format h sss tttt where
sss separator after the parameter
0 none/not param
1 comma
2 semi-colon
3 backslash
4 exclamation mark
5 'TO' keyword
h # before the parameter
0
no/not param
1
yes
tttt type of entry
0 null
1 string
2 f p
3 integer
(Only tttt is shown in the main table)
[2] Not normally reccomended for use by added routines.
3 VARIABLE VALUES AREA
A heap in which the values are stored. The item entries are:
--integer - 16-bit two's complement word.
- 2-byte exponent, then 4-byte mantissa. Ms 4 bits of exponent
are 0, LS 12 bits are offset -$800.
Mantissa is 2's complement with bit 31 -1, bit 30 +1/2,
normalized so that bit31 /= bit30 (unless the whole number is
--f p exactly zero, in which case all 6 bytes are 0). So value is
-- mantissa*2^(exponent-$800)
if the mantissa is taken as fraction or
-- mantissa*2^(exponent-$81F)
if the mantissa is taken as .L integer.
- 2 byte character count, then that number of characters, then
-- string (if the count was odd) an ignored byte to make the whole an even
# of bytes
- header of format
* .L offset from base of variable values area to the array
values
* .W number of dimensions
* .W max index of the dimension
-- array * .W index multiplier for the dimension
[The last pair of items are repeated once for each dimension.]
STRING ARRAY: is an array of characters, except zeroth element
of the final demension is .W containing the string length; Final
dimension defines the maximum string length, +1 if odd.
SUBSTRING: result of a slicing: an array of characters, except
that the base of indexing is one rather than zero.
4 THE BASIC CHANNEL TABLE
A channel number #n indexes the SuperBASIC channel table. Each entry in the
table is of length CH_LENCH ($28) bytes. The base of the table is at
BV(CHBAS(A6) and the top at BV_CHP(A6). So the base for entry #n is at (
BV_CHBAS(A6) + CH_LENCH*n ) (A6)
Each entry is of format:
$00.L The channel ID
$04.F Current graphics cursor x
$0A.F Current graphics cursor y
$10.F Turtle angle (degrees)
$16.B Pen status
$20.W Character position on line for PRINT and INPUT
$22.W WIDTH of page
The table has as many entries as the number of the current highest-numbered
channel: an un-opened channel either has a number greater than that, OR has
a negative channel ID.
QDOS MEMORY MAP
---------------
Hardware map
$FFFFF +--------------------------+
| Add-on ROM (up to 128kb) |
$E0000 +--------------------------+
| 8x16kb device slots |
$C0000 +--------------------------+
| Up to 512kb add-on RAM | } See } Top actual
$40000 +--------------------------+ } next } address goes
| 96kb on-board user RAM | } diagram } in SV_RAMT
$28000 +--------------------------+
| 32KB screen RAM |
$20000 +--------------------------+
| On-board IO (partially | $1806?3 = master chip status reg: bit 0=1 blanks display:
| decoded) | bit 0=0 enables display. ALSO??!! POKE 98403,2 to blank
$10000 +--------------------------+ screen, POKE..,2 to restore monitor mode.
| 16kb plug-in ROM |
$0C000 +--------------------------+
| 48kb on-board ROM |
$00000 +--------------------------+
Ram map
SV_RAMT +----------------+
SV_RESPR | Resident proc- | When not jobs present, QDOS can allocate &
| edure area | totally-deallocate space: no other QDOS ops.
+vvvvvvvvvvvvvvvv+
SV_TRNSP | Transient | Code/data/stack area per relocatable job.
| program area | Not normally re-entrant, but can be made so.
+vvvvvvvvvvvvvvvv+
SV_BASIC | SuperBASIC | Basic program, variables, its IO channels.
| area | See BV_ definitions: all pointers A6-relative.
+vvvvvvvvvvvvvvvv+ [Top regions grow down.]
SV_FREE | Free memory | Used by the filing
| area | system for slave blocks.
+^^^^^^^^^^^^^^^^+ [Common heap grows up]
SV_HEAP | Common heap | Channel definitions, workstore for IO & programs.
| area | MT_ALCHP & _RECHP. Auto RECHP at end of job.
+----------------+
| System manage- | Various. Info for joblist, etc. Also the
| ment tables | Supervisor Stack.
+----------------+
| System |
| variables SV_ |
$28000* +----------------+ Base of system variables. $28000 or MT_INF: see below
| Display RAM |
$20000 +----------------+ Base of RAM
* System variables start at $28000 in ROMs up to JS: in Minerva (up to 1.92
at least) running in two-screen mode they start at $30000 because of the
second screen's-worth of display ram. IN ANY ROM it is prudent to use MT_INF
to locate the base of the SVs.
NB: $28000 = 163840
$20000 = 196608
Allocation and release
Allocate Release
Res. procedure areaMT_ALRES MT_RERES [total release
only]
Trans. program area~MT_CJOB ~MT_FRJOB
[for heap
--------"-------- MM_ALLOC MM_LINKFR allocation within
the jobs own data
area.]
SuperBASIC area MT_ALBAS MT_REBAS [for interpreter
only]
------"------ BV_CHRIX automatic [space in RI stack]
[in other
------"------ [see "BASIC SuperBASIC
interpreter"]
areas]
Free memory area [not directly used
by normal jobs]
- also released
Common heap area MT_ALCHP MT_RECHP when owner job is
deleted
[from dev.drivers]
------"------ MM_ALCHP MM_RECHP - also released
when owner job is
deleted
QDOS Register conventions
-------------------------
EXEC and MT_CJOB
Each EXEC/MT_CJOB transient program area is activated in the state:
(A6,A5.L) +-------------------+
high | Command string | } If A6+A5>A7, parameters from
address+-------------------+ }
| .L Channel ID | } the jobs parent job.
| ... | }
| .L Channel ID | }
+-------------------+ } (EXEC/EXEC_W leave A6+A5=A7.)
| .? Number of | }
(A7) i.e.USP| Channel IDs | }
+-------------------+
| Stack area/ | The jobs stack is the top
(A6,A4.L) | Data area |
+-=-=-=-=-=-=-=-=-=-+ part of the data area.
| Code area |
Even address+-------------------+
| .Bs Job Name | If the job name has an odd number
| .W #chars in j.n. |
| .W $4AFB | of characters, it's followed by
low | JMP.L start |
(A6) address+-------------------+ an (ignored) 'pad' character.
The stack usually runs from the top of the data area downwards, except that
the various ways of loading can imply differing numbers of zeros already on
the stack when the program is started.
TALENT WORKBENCH does not appear to implement the A4 and A5 conventions.
The A6 convention is of great use to circumvent the problem that
instructions that store to memory may not have PC-related addresses, i.e.
may not have addresses of either of the forms:
* d16(PC) or
* d8(PC,R)
Instead, one can use d16(A6) and d8(A6,R) - provided that one does not
change A6, of course!
Basic extensions
Defining extra routines
Call BP_INIT (qv) to link in the new routine(s).
1. The SuperBASIC program area can be moved at any time, so all references
in the area must be A6- or A7-relative: don't save A6 or A7 except in
arithmetic or address calculations: don't alter them (except A7 by
PUSHes and POPs). [But can use TRAP#0 to go into supervisor mode to
make following code uninteruptable - this is not a normal practice.]
2. Don't use more than 128 bytes of user stack.
3. D0.L must be returned as an error code.
4. D1-5 and A0-5 can be spoilt: DO NOT SPOIL D6 D7 A6 or A7.
PARAMETER PASSING
...is by substitution:
1. The interpreter evaluates any expression parameters;
2. Each actual is then given a new entry at the top of the name table - if
the routine is written in SuperBASIC, any missing actual gets a null
entry;
3. The interpreter then swaps the new name table entries with the old
entries for the actuals;
4. If the routine is written in machine code, it is CALLed with A3->NTE of
first parameter in the list, and A5->[?just after] the NTE of the last
parameter. [So there will be (A5-A3)/8 parameters.]
5. If a LOCal statement is found, the NTE is copied to the top of the name
table, and the original NTE is replaced by an empty entry.
6. At the end of SuperBASIC routine, the parameter enties are copied back
and local entries removed. The parameter NTEs and any temporary storage
in the variable value area are then removed for all routines.
GETTING SCALAR ACTUALS BY VALUE
Use CA_GTINT (.W integer) CA_GTFP (f p) CA_GTSTR (string) CA_GTLIN (f p
converted to .L integer). Each needs A3 to base of & A5 to end of the NTEs
of the parameters, assumes the parameters are of the same type, and returns
the # of parameters fetched, with their values on the RI stack. Separator
flags are spoilt.
For unquoted strings (i.e. SuperBASIC names to be used literally - e.g. as
file names) the caller of CA_GTSTR must do as follows:
1. Inspect the name to see if it is a valid set string variable.
2. If so, fetch it with CA_GTSTR;
3. otherwise, fetch the parameter's name itself from the name list,
converting to string form by changing the word count from byte to word,
and realigning the string if necessary.
RETURNED VALUES ON THE ARITHMETIC (RI) STACK
Entries on the stack must be word-aligned. So for a string
1. the character count must be on a word boundary; and
2. odd-length strings have a final padding byte, whose value is ignored.
GENERAL
TOS is usually pointed to by A1. Space can be allocated by BV_CHRIX. The
vectored routines for getting results to RI stack do their own
space-allocation. RI stack is automatically tidied after procedures and
after errors in functions.
On return from a function the returned value should be the topmost (i.e.
lowest address) with nothing below it, and both (A6,A1.L) and BV_RIP(A6)
pointing to it. The result type should be in D4 (1=string, 2=fp, 3=.W
integer, with .L integers converted to f p before the RETurn).
Results can be passed back in parameters by pointing A3 to the NTE and
calling BP_LET. If the actual was an expression, BP_LET doesn't give an
error, and the result value is lost. The type of the result is given by the
NTE, and the value on the RI stack must be in the correct form for that
type.
CHANNEL- & SCR_-DEFINITION BLOCKS
---------------------------------
SV_CHBAS thru SV_CHMAX point to a table of longwords: each of those
longwords points to a CHANNEL DEFINITION BLOCK in the following offsets
format.
ALL CHANNELS:
$00.LCH__LEN Length of channel definition block
$04.LCH__DRIVR Address of driver
$08.LCH__OWNER Owner Job
$0C.LCH__RFLAG Address to be set when space released
$10.WCH__TAG Channel ID (channel tag)
Status:
* = 0 OK
$12.BCH__STAT * = -1 (A1)
* = $80 (A1,A6.L)
* = -ve waiting
$13.BCH__ACTIN Stored action for waiting Job
$14.LCH__JOBWT ID of Job waiting on IO
$18 CH__END -- here on differs depending on the kind of channel --
EXTENDED CHANNEL DEFINITION FOR PLAIN SERIAL QUEUES:
$18.LCH__QIN pointer to input Q (or 0)
$1C.LCH__QOUT pointer to output Q (or 0)
$20 CH__QEND -- end --
EXTENDED CHANNEL DEFINITION FOR SCREEN DRIVER:
$18.WSD__XMIN Window top lefthand side
$1A.WSD__YMIN
$1C.WSD__XSIZE Window size
$1E.WSD__YSIZE
$20.WSD__BORWD Border width
$22.WSD__XPOS Cursor position
$24.WSD__YPOS
$26.WSD__XINC Cursor increment
$28.WSD__YINC
$2A.LSD__FONT Font address
$2E.L- Second font address
$32.LSD__SCRB Base address of screen ($20000 on QLs, differs on THOR)
$36.LSD__PMASK Paper colour mask
$3A.LSD__SMASK Strip colour mask
$3E.LSD__IMASK Ink colour mask
Character attributes:
* bit 0 - Underline bit
* bit 1 - Flash bit
* bit 2 - Transparent background
$42.BSD__CATTR * bit 3 - XOR characters/graphics
* bit 4 - Double height
* bit 5 - Extended width
* bit 6 - Double width
* bit 7 - Graphics positioned characters
$43.BSD__CURF Cursor flag, 0=suppressed, >0=visible
$44.BSD__PCOLR Paper colour byte
$45.BSD__SCOLR Strip colour byte
$46.BSD__ICOLR Ink colour byte
$47.BSD__BCOLR Border colour byte
$48.BSD__NLSTA New line status ( >0 implicit, <0 explict)
$49.BSD__FMOD Fill mode (0=OFF, 1=ON)
$4A.FSD__YORG Graphics window x origin (6 bytes)
$50.FSD__XORG Graphics window y origin (6 bytes)
$56.FSD__SCAL Graphics scale factor (6 bytes)
$5C.LSD__FBUF Pointer to fill buffer
$60.LSD__FUSE Pointer to user defined fill vectors
$64.WSD__LINEL Line length in bytes
$68 SD__END -- end --
I've used ".F" to mean "6-byte floating point". -- KL
QDOS Device Driver Headers
--------------------------
$00.L CH_NEXT Pointer to next driver
$04.L CH_INOUT Entry for input and output
$08.L CH_OPEN Entry for OPEN
$0C.L CH_CLOSE Entry for CLOSE
EXTENDED DEVICE HEADER FOR DIRECTORY DEVICES:
$10.L CH_SLAVE Entry for slaving blocks
$14.L CH_RENAM Entry for RENAME
$1C.L CH_FORMAT Entry for FORMAT
$20.L CH_DFLEN Length of physical definition block
$24 CH_DRNAM 2+n bytes drive name
QDOS Job Control Headers
------------------------
Base of the table is pointed to by SV_JBBAS: top by SV_JBTOP. Each entry in
the table is .L & points to $69 bytes as follows:
$00.LJB__LEN Total length of job control + Job area
$04.LJB__START Start address on activation
$08.LJB__OWNER Job ID of this Job's owner
$0C.LJB__HOLD Pointer to a byte which will be cleared when the scheduler
releases the job.
$10.WJB__TAG Tag for Job as allocated by MT.CJOB
Current accumulated priority: incremented when a job is
$12.BJB__PRIOR active but not executing. It is set to zero when the job is
executing. The scheduler allows the Job with the highest
accumulated priority to execute.
$13.BJB__PRINC This priority increment is the initial priority of the Job.
($20=>default: 0=>inactive)
Job status:
* =0 is not suspended
$14.WJB__STAT * >0 is number of frames before release
* -1 is suspended (IO or MT.SUSJB)
* -2 is waiting for another job to finish
$16.BJB__RELA6 MSB is set if next trap #2 or #3 has addressing relative to
A6 (as set by Trap #4)
$17.BJB__WFLAG Set if a job is waiting for this one
$18.LJB__WJOB ID of Job waiting for this to finish
$1C.LJB__TRAPV Pointer to trap redirection vectors
$20.LJB__D0 Saved value of D0
$24.LJB__D1 Saved value of D1
$28.LJB__D2 Saved value of D2
$2C.LJB__D3 Saved value of D3
$30.LJB__D4 Saved value of D4
$34.LJB__D5 Saved value of D5
$38.LJB__D6 Saved value of D6
$3C.LJB__D7 Saved value of D7
$40.LJB__A0 Saved value of A0
$44.LJB__A1 Saved value of A1
$48.LJB__A2 Saved value of A2
$4C.LJB__A3 Saved value of A3
$50.LJB__A4 Saved value of A4
$54.LJB__A5 Saved value of A5
$58.LJB__A6 Saved value of A6
$5C.LJB__A7 Saved value of A7
$60.WJB__SR Saved value of Status register
$62.LJB__PC Saved value of Program counter
$68 JB__END
QDOS Vectored Calls
--------------------
D1.L space
required. Returns
D1.L space actually
$0C0 MM_ALCHP Allocate on allocated, A0->base
common heap of area allocated.
Spoils D2-3 A1-3.
Error code ERR_OM
if out of memory.
Called in
supervisor modes,
A6->base of system
varaibles, A0->base
$0C2 MM_RECHP Release on of area to release,
common heap
& not from a task
that services an
interrupt. Spoils
D1-3 A0-3.
$0C4 UT_WINDW SET WINDOW
BY NAME
$0C6 UT_CON SET UP CON_
WINDOW
$0C8 UT_SCR SET UP SCR_
WINDOW
- - - Last 3: see OPIE
$0CA UT_ERR0 ERROR TO #0
$0CC UT_ERR ERROR TO #n
$0CE UT_MINT INT TO ISO
ON #n
$0D0 UT_MTEXT TEXT TO #n
- - - Last 4: see OPIE
A0->base of item
(with 4 bytes at
$0D2 UT_LINK Link item start for the
into a list
link), A1->prior
item.
A1 updated, others
$0D4 UT_UNLNK Unlink item preserved. To link
from a list to a new list, use
A1=0.
Allocate an
$0D8 MM_ALLOC area in a See TecRefMan 4.1
heap and p148.
MM_LINKFR
Link freeSee
$0DA space TecRefMan
back into4.1 and
heap p148.
} D1.L=queue length
$0DC IO_QSET Set up a or data, (A6,A2.L)
queue ->queue. Error code
in D0=ERR.NC (q
} full QIN; empty
QOUT,QTEST) ERR_EF
$0DE IO_QTEST Test status (end of file
of a queue
QOUT,QTEST).
Changes
Put a byte } D1 to data, ?D2
$0E0 IO_QIN into a becomes free space
queue if changed, A3
spoilt by QIN,QOUT,
Extract a
$0E2 IO_QOUT byte from a } QTEST,QSET. Data
q length<32767.
Put EOF
$0E4 IO_QEOF marker into
a q
$0E6 UT_CSTR COMPARE TWO
STRINGS
- - - : see OPIE
Direct } For IOSS
$0E8 IO_SERQ queue activities only.
handling See the
$0EA IO_SERIO General IO } Technical
handling Reference Manual.
} D1.L=internal
date/time,
$0EC CN_DATE GET (A1,A6)->tos.
DATE/TIME
Changes A1: puts
string of date or
} time onto stack.
$0EE CN_DAY GET DAY OF CN_Date needs 23
WEEK bytes of stack,
CN_DAY needs 7.
- - - Both: see OPIE
$0F0 CN_FTOD F.P. TO ISO } Convert value on
(A1,A6)->tos to
$0F2 CN_ITOD WORD INT TO } characters in
ISO (A0,A6)->buffer.
$0F4 CN_ITOBB BYTE TO ISO } Spoil D1-D3 A2
A3, change A0 A1.
$0F6 CN_ITOBW WORD TO ISO
$0F8 CN_ITOBL LONG TO ISO
$0FA CN_ITOHB BYTE TO
HEX-ISO
$0FC CN_ITOHW WORD TO
HEX-ISO
$0FE CN_ITOHL LONG TO
HEX-ISO
- - - All: see OPIE
} Convert
(A0,A6)->ISO chars
$100 CN_DTOF ISO TO F.P. in buffer to value
on (A1,A6)->tos. D7
is 0 or
(D7,A6)-> end of
$102 CN_DTOI ISO TO INT buffer. FP result
is 6-byte, others
4-byte, A1 left
-> last of
the result
$104 CN_BTOIB ISO BINARY % bytes. Error
TO BYTE code in D0.
Spoil D1 D2
D3 A1 A2,
change A0 A1
(unless
$106 CN_BTOIW ISO BINARY % error) to
TO WORD point after
consumed
characters,
and to new
tos. Use
$108 CN_BTOIL ISO BINARY % approx 30
TO LONG bytes of
stack. Those
marked '%'
are not in
$10A CN_HTOIB HEX-ISO TO % QDOS 1.03 or
BYTE
earlier.
$10C CN_HTOIW HEX-ISO TO %
WORD
$10E CN_HTOIL HEX-ISO TO %
LONG
- - - All: see OPIE
(A1,A6)->table -
add m/c see below. Spoils
$110 BP_INIT routines to A1, D2. Uses <
SuperBASIC 49bytes of
stack
(A3,A6)->nametable
Get .W entry of 1st param
$112 CA_GTINT ints->RI of list,
stack (A5,A6)->NTE of
last. Spoils
D1 D2 D4 D6 A0 A2 &
$114 CA_GTFP Get f p separator flags in
numbers NTEs. Error code to
D0 & CC.
Leaves D3 lsw =
#params fetched,
$116 CA_GTSTR Get strings params left on
arith stack with
1st
$118 CA_GTLIN Get long param top (ie
integers lowest addr). *
D0.L=#bytes to
reserve: reserves
space on arith
stack (A1,A6).
Reserve Spoils D1 D2 D3.
$11A BV_CHRIX space on RI Error code to D0.
stack May move whole
program, so save
arith stack pointer
in BV_RIP(A6),
retreive it after.
EXECUTE
$11C RI_EXEC SINGLE RIs
ARITH OP
EXECUTE
$11E RI_EXECB LIST OF
AR.OPS
- - : see OPIE
(A3,A6)->nte,
(A1,A6)->value to
assign: A3 & A1
even. Nte
$120 BP_LET Assign TOS determines type of
to variable
value, hence also
length. Spoils D1
D2 D3 A0 A1 A2.
Error code to D0. *
(A0)->device name
in STRING format *,
decoded result,
(A6)->base of
system variables:
device description
starts 6 bytes
after the call -
see below for
format and
examples. For each
numeric value in
the description,
the value given in
the device name is
returned, or the
$122 IO_NAME Decode a default; for each
device name
list of codes, the
position of the
code in the list is
returned, or zero.
Spoils D1-3 A1 A2,
preserves A0 A3,
error code in D0 =
ERR_NF (not
recognised) or
ERR_BN (recognized
but bad
parameters). If OK,
returns +4: if
ERR_BN, returns +2:
if ERR_NF, returns
+0.
$124 MD_READ Read a } A1->start of
sector buffer, A3=$18020.
$126 MD_WRITE Write a } Error ret WRITE
sector READ/VER SECTR
$128 MD_VERIN Verify a } +0 OK failed bad
sector medium
OK
File#->D1,
Block#->D2
(read/verify);
Sector#->D7
(read sec
head); Point to
end of $4000(An)
buffer->A1 [$18020 is
(all). All mdv control
Read a bad other registers register.]
$12A MD_SECTR sector } +2 OK sec +4 spoilt. Before All 4
header head MD_WRITE, A7 should be
must be to a called with
word with the interrupts
file number in off.
MSB and block
number in LSB.
All should be
called
-- MOVE.W
MD_xxxx,An
-- JSR
* value format - same as in the SuperBASIC variable values area.
$110 BP_INIT Table of form:
.W, approx # of procedures
.W, entry address - this address ) for
.B, length of name of procedure ) each
.. that number of bytes ) proc
.W, zero
.W, approx # of functions
.W, entry address - this address ) for
.B, length of name of function ) each
.. that number of bytes ) func
.W, zero
"approx#" is the number of procs/funcs, unless the average length of the
names is >7, in which case the approx# is (total number of characters+number
of funcs or procs+7)/8 $122 IO_NAME The device name is formed of 4 kinds of
element:
Name - ISO characters, usually letters, case ignored;
Separator - Single ISO character, case ignored.
Number - Decimal number > -1 and < 32768.
Code - One of a list of ISO characters.
The device description block has format:
.W #chars in dev name to check for
.Ws the chars
.W #params to check for
description per params
The format of each parameter description is
byte space, byte separator, word default value (numeric with separator);
word negative number, word default value (numeric with no separator);
word positive number of possible codes, bytes for the ISO char codes.
In the description block, letters must be upper case.
Example description blocks:
DC.W 3,'CON'
DC.W 5 parameters
DC.W '_',448 x-size | CON yeilds 0, 0, 128
448, 180,
DC.W 'X',180 y-size | CON_256 yeilds 0, 0, 128
256, 180,
DC.W 'A',32 x-origin | CON__60 yeilds 0, 0, 60
448, 180,
DC.W 'X',16 y-origin | CONa0x12 yeilds 0, 12,
448, 180, 128
DC.W '_',128 kb q length
DC.W 3,'SER'
DC.W 4
parameters
| SER
yeilds 1, 0, 0, 0
DC.W -1,1
port(dflt 1)
| SERe
yeilds 1, 1, 0, 0
DC.W 4,'OEMS'
parity
| SER2miz
yeilds 2, 3, 1, 2
DC.W 2,'IH'
h/shake
DC.W 3,RZC
raw/ctrlZ/CR
SUMMARY OF QDOS TRAPS and their parameters
Extended, revised and adapted from notes on Qdos supplied with the Public
Domain QDOS Emulator for the Commodore Amiga computer, supplied on disk by
Softville Ltd. (0705) 266509.
Supervisor TRAP #0
This is only mentioned for the sake of completeness, as it cannot be called
from SuperBasic - and should not, or problems are likely. The interpreter
is designed and expects to run in User Mode.
TRAP #0 enters Supervisor mode. This stops the job scheduler running, so
SuperBasic will not move until you return to user mode with the 68008
instruction AND #$D8FF,SR. While you are in Supervisor mode A7 points to
a fixed stack, not the user stack of the task (which can move, if the task
is SuperBasic). You are not expected to use more than 64 bytes on this SSP.
Manager TRAP #1
These calls are used to control or manage machine resources. The effect of
TRAP #1 depends on the value in register D0 at the time of the call. Some
parameters are passed in registers A0 to A3, D1, D2 and D3, depending on
the operation to be performed. Error codes are returned in D0; the operation
went wrong unless D0=0 on return (i.e. DATAREG=0). The table shows error
codes by two-letter mnemonics, e.g. OM = OUT OF MEMORY, OR = OUT OF RANGE,
NJ = No such Job (or no room in Job Table!), NC = NOT COMPLETE etc.
Register names marked .W expect or return 16 bit integer values in the 'low
word' of the register. .L marks a 32 bit long integer, or SuperBasic float.
Byte values 0 to 255 are indicated by .B. If a value is specified as a byte
or word the state of other bits in the register does not alter the effect.
MTRAP 0 MT.INF Provide current job and system information
No Call parameters Return parameters
D1 D1.L current Job ID
D2 D2.L ASCII version, e.g. "1.10"
D3 D3 preserved
A0 A0 pointer to system variables
A1 A1 preserved
A2 A2 preserved
A3 A3 preserved
No errors possible so no need to check DATAREG
MTRAP 1 MT.CJOB Create a job in the transient program area
Call parameters Return parameters
D1.L owner's Job ID D1.L ID of new Job
D2.L length of code(bytes) D2 preserved
D3.L length of data space D3 preserved
A0 A0 Start of memory for task code
A1 start address or 0 A1 preserved
A2 A2 preserved
A3 A3 preserved
Errors : OM, NJ
MTRAP 2 MT.JINF Provide information on a job
Call Return
D1.L Job ID D1.L next Job in tree
D2.L Job at top of tree D2.L owner of Job
D3 D3 MSB<0 if suspended, LSB=priority
A0 A0 base address of job
A1 A1 undefined
A2 A2 preserved
A3 A3 preserved
Errors : NJ
MTRAP 3 illegal system trap, original purpose unknown.
4 MT.RJOB Remove job from transient program area
Call Return
D1.L Job ID D1 undefined
D2 D2 undefined
D3.L Error code D3 undefined
A0 A0 undefined
A1 A1 undefined
A2 A2 undefined
A3 A3 undefined
Errors : NJ,NC
5 MT.FRJOB force remove job from transient program area
Call Return
D1.L Job ID D1 undefined
D2 D2 undefined
D3.L Error code D3 undefined
A0 A0 undefined
A1 A1 undefined
A2 A2 undefined
A3 A3 undefined
Errors : NJ
6 MT.FREE finds the maximum space free for a task
Call Return
D1 D1.L length of space
D2 D2 undefined
D3 D3 undefined
A0 A0 undefined
A1 A1 undefined
A2 A2 undefined
A3 A3 undefined
7 MT.TRAPV sets pointer to trap vectors for this job
Call Return
D1.L Job ID D1.L Job ID
D2 D2 preserved
D3 D3 preserved
A0 A0 base of job
A1 pointer to table A1 undefined
A2 A2 preserved
A3 A3 preserved
8 MT.SUSJB suspend a job
Call Return
D1.L Job ID D1.L Job ID
D2 D2 preserved
D3.W Timeout D3 preserved
A0 A0 base of job control area
A1 address of flag byte A1 preserved
A2 A2 preserved
A3 A3 preserved
Errors : NJ
9 MT.RELJB Release a job
Call Return
D1.L Job ID D1.L Job ID
D2 D2 preserved
D3 D3 preserved
A0 A0 base of job control area
A1 A1 preserved
A2 A2 preserved
A3 A3 preserved
Errors : NJ
10 MT.ACTIV activate a job
Call Return
D1.L Job ID D1.L Job ID
D2.B priority (0-127) D2 preserved
D3.W Timeout (-1,0) D3 preserved
A0 A0 base of job control area
A1 A1 preserved
A2 A2 preserved
A3 A3 preserved
Errors : NJ,NC
11 MT.PRIOR change a job's priority
Call Return
D1.L Job ID D1.L Job ID
D2.B priority (0-127) D2 preserved
D3 D3 preserved
A0 A0 base of job control area
A1 A1 preserved
A2 A2 preserved
A3 A3 preserved
Errors : NJ
12 MT.ALLOC allocate an area in a user heap
Call Return
D1.L required length D1.L allocated length
D2 D2 undefined
D3 D3 undefined
A0 pointer to pointer A0 base of area allocated
to free space
A1 A1 undefined
A2 A2 undefined
A3 A3 undefined
A6 base address A6 preserved
Errors : OM
13 MT.LNKFR link free space back into a user heap
Call Return
D1.L length to link in D1 undefined
D2 D2 undefined
D3 D3 undefined
A0 base of new space A0 undefined
A1 pointer to pointer A1 undefined
to free space
A2 A2 undefined
A3 A3 undefined
A6 base address A6 preserved
14 MT.ALRES allocate resident procedure area
Call Return
D1.L num of bytes required D1 undefined
D2 D2 undefined
D3 D3 undefined
A0 A0 base address of area
A1 A1 undefined
A2 A2 undefined
A3 A3 undefined
Errors : OM,NC
15 MT.RERES release resident procedure area
Call Return
D1 D1 undefined
D2 D2 undefined
D3 D3 undefined
A0 A0 undefined
A1 A1 undefined
A2 A2 undefined
A3 A3 undefined
Errors : NC
N.B. This only works on Minerva, and even then it is dangerous!
16 MT.DMODE Sets or reads the display mode
Call Return
D1.B -1 read mode D1.B display mode
0 : 512 * 256 (MODE 4)
8 : 256 * 256 (MODE 8)
12 : 256 * 256 (MODE 12)
D2.B -1 read display D2.B display type
0 : monitor
1 : TV
D3 D3 preserved
A0 A0 preserved
A1 A1 preserved
A2 A2 preserved
A3 A3 undefined
Mode 12 is only available on CST Thor XVI at the time of writing.
Minerva accepts extra DMODE parameters - see the manual for details.
17 MT.IPCOM Sends a command to the IPC
Call Return
D1 D1.B IPC return parameter
D2 D2 preserved
D3 D3 preserved
D5 D5 undefined
D7 D7 undefined
A0 A0 preserved
A1 A1 preserved
A2 A2 preserved
A3.L pointer to command A3 preserved
14 MT.BAUD sets the RS-232 baud rate
Call Return
D1.W baud rate D1 undefined
D2 D2 preserved
D3 D3 preserved
A0 A0 preserved
A1 A1 preserved
A2 A2 preserved
A3 A3 preserved
SMS-2 documentation calls this SMS.COMM.
19 MT.RCLCK reads the clock
Call Return
D1 D1.L time in seconds since 1961
D2 D2 undefined
D3 D3 preserved
A0 A0 undefined
A1 A1 preserved
A2 A2 preserved
A3 A3 preserved
20 MT.SCLCK sets the clock
Call Return
D1.L time in seconds D1.L time in seconds
D2 D2 undefined
D3 D3 undefined
A0 A0 undefined
A1 A1 preserved
A2 A2 preserved
A3 A3 preserved
21 MT.ACLCK adjust the clock
Call Return
D1.L adjustment in seconds D1.L time in seconds
D2 D2 undefined
D3 D3 undefined
A0 A0 undefined
A1 A1 preserved
A2 A2 preserved
A3 A3 preserved
22 MT.ALBAS allocate Basic program area
Call Return
D1.L num of bytes required D1.L number of bytes allocated
D2 D2 undefined
D3 D3 undefined
A0 A0 undefined
A1 A1 undefined
A2 A2 undefined
A3 A3 undefined
A6 base address A6 new base address
A7 User Stack Pointer A7 new USP (maybe!)
Errors : OM
SMS-2 documentation calls this MT.ALMPA (Movable program area).
23 MT.REBAS release Basic program area
Call Return
D1.L num of bytes D1.L number of bytes released
D2 D2 undefined
D3 D3 undefined
A0 A0 undefined
A1 A1 undefined
A2 A2 undefined
A3 A3 undefined
A6 base address A6 new base address
A7 USP A7 new USP
24 MT.ALCHP allocate common heap area
Call Return
D1.L num of bytes required D1.L number of bytes allocated
D2.L owner Job ID D2 undefined
D3 D3 undefined
A0 A0 base address of area
A1 A1 undefined
A2 A2 undefined
A3 A3 undefined
Errors : OM, NJ
25 MT.RECHP release common heap area
Call Return
D1 D1 undefined
D2 D2 undefined
D3 D3 undefined
A0.L base of area to free A0 undefined
A1 A1 undefined
A2 A2 undefined
A3 A3 undefined
26 MT.LXINT link in an external interrupt service routine
Call Return
D1 D1 preserved
D2 D2 preserved
D3 D3 preserved
A0.L address of link A0 preserved
A1.L entry address, 4(A0) A1 undefined
A2 A2 preserved
A3 A3 preserved
27 MT.RXINT remove external interrupt routine from list
Call Return
D1 D1 preserved
D2 D2 preserved
D3 D3 preserved
A0.L address of link A0 preserved
A1 A1 undefined
A2 A2 preserved
A3 A3 preserved
28 MT.LPOLL link in 50/60 Hz poll routine
Call Return
D1 D1 preserved
D2 D2 preserved
D3 D3 preserved
A0.L address of link A0 preserved
A1.L entry address A1 undefined
A2 A2 preserved
A3 A3 preserved
29 MT.RPOLL remove 50/60 Hz routine from list
Call Return
D1 D1 preserved
D2 D2 preserved
D3 D3 preserved
A0.L address of link A0 preserved
A1 A1 undefined
A2 A2 preserved
A3 A3 preserved
30 MT.LSCHD links in a scheduler loop task
Call Return
D1 D1 preserved
D2 D2 preserved
D3 D3 preserved
A0.L address of link A0 preserved
A1.L entry address A1 undefined
A2 A2 preserved
A3 A3 preserved
31 MT.RSCHD remove scheduler loop task from list
Call Return
D1 D1 preserved
D2 D2 preserved
D3 D3 preserved
A0.L address of link A0 preserved
A1 A1 undefined
A2 A2 preserved
A3 A3 preserved
32 MT.LIOD links in I/O device driver
Call Return
D1 D1 preserved
D2 D2 preserved
D3 D3 preserved
A0.L address of link A0 preserved
A1.L entry address A1 undefined
A2 A2 preserved
A3 A3 preserved
33 MT.RIOD remove I/O device driver from list
Call Return
D1 D1 preserved
D2 D2 preserved
D3 D3 preserved
A0.L address of link A0 preserved
A1 A1 undefined
A2 A2 preserved
A3 A3 preserved
34 MT.LDD links in directory device driver
Call Return
D1 D1 preserved
D2 D2 preserved
D3 D3 preserved
A0.L address of link A0 preserved
A1.L entry address A1 undefined
A1 -> 4(A0)
A2 A2 preserved
A3 A3 preserved
35 MT.RDD remove directory device driver from list
Call Return
D1 D1 preserved
D2 D2 preserved
D3 D3 preserved
A0.L address of link A0 preserved
A1 A1 undefined
A2 A2 preserved
A3 A3 preserved
36 MT.TRA Set up Translate Tables (use TRA instead!)
I/O Allocation TRAP #2
This is only mentioned here for the sake of completeness, as it cannot be
called with DIY Toolkit QTRAP calls.
TRAP #2 calls have parameters in D0 between 1 and 4. They should be accessed
through normal OPEN, CLOSE. FORMAT and DELETE commands, or Toolkit variants.
I/O utilisation TRAP #3
Like TRAP #1 calls, these expect an operation code in D0. They also use
a channel ID (returned by OPEN, or read with BPEEK_L or CHANNEL_ID) in A0,
generated by QTRAP and BTRAP from a SuperBasic Channel number.
Use QTRAP by default; use BTRAP only when the buffer or data addressed by
A1 is inside the SuperBasic task memory area.
Register values that are 'undefined' after a call may have interesting
values in them, but you should not expect these to be consistent between
ROM versions. It is best only to use results that are explicitly documented
here; they should not change as Qdos develops.
The type of the channel determines the operations that may be performed.
If an operation is not defined for a particular device, all these routines
can return ERR.BP (Bad parameter, DATAREG = -15 after the call). The code
in DATAREG after a call depends entirely on the parameters and the channel
or device in use; new devices could potentially return ANY error code.
QTRAP 0 IO.PEND Checks for pending input
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,EF
Beware: this is not reliable if used to check for console
input on early Qdos versions (such as "JM" or "AH" ROMs).
QTRAP 1 IO.FBYTE Fetch a byte
Parameters Results
D1 D1.B byte fetched
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,EF
2 IO.FLINE Fetch a line of characters
Parameters Results
D1 D1.W number of bytes (inc. LF)
D2.W length of buffer D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1.L base of buffer A1 updated pointer to buffer
A2 A2 preserved
Errors : NC,NO,EF,BO
3 IO.FSTRG Fetches a string of bytes
Parameters Results
D1 D1.W number of bytes fetched
D2.W length of buffer D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1.L base of buffer A1 updated pointer to buffer
A2 A2 preserved
Errors : NC,NO,EF
4 IO.EDLIN edit a line of characters
Parameters Results
D1.H cursor position D1.W Line length
D1.W current length (including terminator)
D2.W length of buffer D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1.L pointer to EOL A1 pointer to end of line
A2 A2 preserved
Errors : NC,NO,BO
5 IO.SBYTE sends a byte
Parameters Results
D1.B byte to be sent D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,DF,OR
6 Unused System call (IO.SLINE, redundant; ERR.BP)
7 IO.SSTRG sends a string of bytes
Parameters Results
D1 D1.W number of bytes sent
D2.W number of bytes D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1.L base of buffer A1 updated pointer to buffer
A2 A2 preserved
Errors : NC,NO,DF
8 Unknown unimplemented System call, reports Bad parameter
9 IO.EXTOP invoke extra code as part of SCR/CON/MEM driver
Parameters Results
D1 Passed to extension D1 Passed back by extension
D2 Passed to extension D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 Passed to extension A1 Passed back by extension
A2 Start of extension A2 preserved
Errors : NC,NO,BP or potentially ANYTHING returned by code at A2!
10 SD.PXENQ Results window size and cursor position in pixels
Parameters Results
D1 D1 preserved
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1.L base of buffer A1 undefined
A2 A2 preserved
Errors : NC,NO
PXENQ and CHENQ store four words in a buffer addressed by parameter A1:
0(A1) = X-dimension of window
2(A1) = Y-dimension of window
4(A1) = X-position of cursor
6(A1) = Y-position of cursor
11 SD.CHENQ Find window size and cursor position in characters
Parameters Results
D1 D1 preserved
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1.L base of buffer A1 undefined
A2 A2 preserved
Errors : NC,NO
12 SD.BORDR sets the border width and colour
Parameters Results
D1.B colour D1 undefined
D2.W width D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 preserved
A2 A2 preserved
Errors : NC,NO
13 SD.WDEF redefines a window's position & border
Parameters Results
D1.B border colour D1 undefined
D2.W border width D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1.L base of buffer A1 undefined
A2 A2 preserved
Errors : NC,NO,OR
WDEF expects parameters in a buffer of 8 bytes addressed by A1:
0(A1) = X-dimension of window
2(A1) = Y-dimension of window
4(A1) = X-origin
6(A1) = Y-origin
14 SD.CURE Enable the cursor
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
15 SD.CURS Turn off the cursor
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
16 SD.POS Position cursor at character row & column
Parameters Results
D1.W column number D1 undefined
D2.W row number D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,OR
17 SD.TAB Position cursor at column
Parameters Results
D1.W column number D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,OR
18 SD.NL Position cursor on new line
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,OR
19 SD.PCOL Position cursor on previous column
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,OR
20 SD.NCOL Position cursor on next column
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,OR
21 SD.PROW Position cursor on previous row
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,OR
22 SD.NROW Position cursor on next row
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,OR
23 SD.PIXP Position cursor using pixel coordinates
Parameters Results
D1.W X-coordinate D1 undefined
D2.W Y-coordinate D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,OR
24 SD.SCROL Scroll entire window
Parameters Results
D1.W distance to scroll D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
25 SD.SCRTP Scroll the top of a window
Parameters Results
D1.W pixels to scroll D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
26 SD.SCRBT Scroll the bottom of a window
Parameters Results
D1.W distance to scroll D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
27 SD.PAN Pans all of a window
Parameters Results
D1.W distance to pan D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
28 SD.PANTOP, unimplemented system call
29, SD.PANBOT, unimplemented system call
30 SD.PANLN pans cursor line
Parameters Results
D1.W distance to pan D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
31 SD.PANRT pans right side of cursor line
Parameters Results
D1.W distance to pan D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
32 SD.CLEAR clears all of a window
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
33 SD.CLRTP clears the top of a window
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
34 SD.CLRBT clears the bottom of a window
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
35 SD.CLRLN clears the cursor line
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
36 SD.CLRRT clears the right side of the cursor line
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
37 SD.FOUNT sets or resets the character founts
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 base of fount 0 A1 undefined
A2 base of fount 1 A2 preserved
Errors : NC, NO
38 SD.RECOL recolours a window
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 ptr to colour list A1 undefined
A2 A2 preserved
Errors : NC,NO
The colour list consists of 8 bytes which contain the new colour for
each old colour, in order from 0 to 7, or 16 bytes for Argos MODE 12.
39 SD.SETPA sets the Paper colour
Parameters Results
D1.W colour D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
The SuperBasic PAPER command sets both PAPER and STRIP, but this call
sets only the PAPER colour used beneath characters printed with OVER 0.
Thor XVI MODE 12 intensity is controlled by bits 14 & 15 of D1.W
40 SD.SETST sets the Strip colour
Parameters Results
D1.W colour D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
41 SD.SETIN sets the ink colour
Parameters Results
D1.W colour D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
42 SD.SETFL sets MODE 8 flashing on or off
Parameters Results
D1.B flash flag (0 or 1) D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
43 SD.SETUL sets Underlining on or off
Parameters Results
D1.B UNDER flag, 0 or 1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
44 SD.SETMD sets text and graphics OVER mode
Parameters Results
D1.W OVER flag 0, 1 or -1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
45 SD.SETSZ set character size and spacing
Parameters Results
D1.W text width, 0-3 D1 undefined
D2.W text height, 0 or 1 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
46 SD.FILL fills a rectangular block within a window
Parameters Results
D1.W colour D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 ptr to block def A1 undefined
A2 A2 preserved
Errors : NC,NO
Thor XVI MODE 12 intensity is controlled by bits 14 & 15 of D1.W.
A1 points to four word parameters in a buffer:
0(A1) = width in pixels
2(A1) = height in pixel
4(A1) = X origin (relative to window)
6(A1) = Y origin
47 SD.DONL Perform a pending newline, if any
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
48 SD.POINT plots a graphics point
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 arithmetic stack ptr A1 undefined
A2 A2 preserved
Errors : NC,NO
This expects two floating point parameters, passed on the maths stack:
0(A1) = Y coordinate
6(A1) = X coordinate
49 SD.LINE plots a graphics line
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 arithmetic stack ptr A1 undefined
A2 A2 preserved
Errors : NC,NO
This expects four floating point parameters, passed on the maths stack:
0(A1) = Y coordinate end of line
6(A1) = X coordinate end of line
12(A1) = Y start
18(A1) = X start
50 SD.ARC plots a graphics arc
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 arithmetic stack ptr A1 undefined
A2 A2 preserved
Errors : NC,NO
This expects five floating point parameters, passed on the maths stack:
0(A1) = angle subtended, in radians
6(A1) = Y end
12(A1) = X end
18(A1) = Y start
24(A1) = X start
51 SD.ELLIPS plots an ellipse
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 arithmetic stack ptr A1 undefined
A2 A2 preserved
Errors : NC,NO
This expects five floating point parameters, passed on the maths stack:
0(A1) = orientation in radians
6(A1) = radius
12(A1) = eccentricity
18(A1) = Y centre
24(A1) = X centre
52 SD.SCALE sets window scale
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 arithmetic stack ptr A1 undefined
A2 A2 preserved
Errors : NC,NO
This expects three floating point parameters, passed on the maths stack:
0(A1) = Y coordinate of the bottom line
6(A1) = Leftmost pixel X coordinate
12(A1) = length of Y axis in your units
53 SD.FLOOD turns area filling on and off
Parameters Results
D1.L Flag, 0/1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
54 SD.GCUR sets graphics cursor position
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 arithmetic stack ptr A1 undefined
A2 A2 preserved
Errors : NC,NO
This expects four floating point parameters, passed on the maths stack:
0(A1) = graphics X coordinate
6(A1) = graphics Y coordinate
C(A1) = pixel offset to the right
12(A1) = pixel offset downwards
55, 56, 57 unimplemented/unknown system calls
58 SD.TOPW Moves a Thor window to top of the pile
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
This Thor windowing TRAP also directs keyboard input to the window.
59, 60, 61, 62, 63 unimplemented/unknown system calls
64 FS.CHECK checks all pending operations on a file
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
65 FS.FLUSH flushes buffer for file
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO
66 FS.POSAB Move file pointer to absolute position
Parameters Results
D1.L position in file D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,EF
67 FS.POSRE position file pointer relative
Parameters Results
D1.L offset to file ptr D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,EF
68 Unimplemented system call, once reserved for RENAME
69 FS.MDINF Gets information about storage medium
Parameters Results
D1 D1.H Unused sectors
D1.W Usable sectors
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 10 byte name buffer A1 past end of medium name
A2 A2 preserved
Errors : NC,NO
70 FS.HEADS sets start of a file header
Parameters Results
D1 D1 length of header set
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 base of header block A1 end of header definition
A2 A2 preserved
Errors : NC,NO
Please see DIY Toolkit volume F for further details of file headers.
71 FS.HEADR reads a 64 byte file header
Parameters Results
D1 D1 undefined
D2.W buffer length D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 ptr to read buffer A1 undefined
A2 A2 preserved
Errors : NC,NO,BO
72 FS.LOAD loads a file into memory
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout (use -1) D3 preserved
A0.L Channel ID A0 preserved
A1 EVEN load address A1 top address after load
A2 A2 preserved
Errors : NO
Some books say D2 is 'length of file' but existing drivers load the
entire file regardless of the parameter value, unfortunately.
73 FS.SAVE saves a file from memory
Parameters Results
D1 D1 undefined
D2.L length of file D2 preserved
D3.W Timeout (-1) D3 preserved
A0.L Channel ID A0 preserved
A1 EVEN address of data A1 Just past end of data
A2 A2 preserved
Errors : DF,NO
This is the end of the calls implemented on standard QL systems.
Others need Toolkit 2, CST Thors, Minerva or hard disks to work.
74 FS.RENAM Changes the name of a file
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 address of new name A1 undefined
A2 A2 preserved
Errors : NC,NO,NF,EX,IU,DF,BN,RO
75 FS.TRUNC Truncate file to current position
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,NO,RO
76 FS.DATE Set or read file dates
Parameters Results
D1.L Date/-1=READ/0=SET D1 undefined
D2.W 0-2 Update/Ref/Backup D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NO,NC
77 FS.MKDIR Makes a file into a sub-directory
Parameters Results
D1 D1 undefined
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NC,IU,BN,RO,DF,NO
78 FS.WATER Read CST Thor watermark
Parameters Results
D1.W Field 0 or 1 D1 Length of field read
D2 Buffer length D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 Base of buffer A1 Top of buffer
A2 A2 preserved
Errors : NO,NC,BO,OR
78 FS.VERS Set or read Miracle file version number
Parameters Results
D1.W Number/0=Read/-1=Bump D1 Version number, 1-65535
D2 D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 A1 undefined
A2 A2 preserved
Errors : NO,NC
79 FS.XINF Interrogate the file system
Parameters Results
D1.W Flag: 0 = everything D1 undefined
D2 Buffer length D2 preserved
D3.W Timeout D3 preserved
A0.L Channel ID A0 preserved
A1 Ptr to result buffer A1 undefined
A2 A2 preserved
Errors : NC,IU,BN,RO,DF,NO
D1=0 to read all the information. Set bits in D1 request specific fields
e.g. D1=7 for a 32 bit MDINF equivalent, D1=57344 for the full name, etc.
The exact contents of the buffer may vary, depending on the system you are
using and its age; CST (Argos 6.37), Miracle and Rebel implement FS.XINF.
SuperBasic A6 relative TRAP #4
This makes the next TRAP #2 or TRAP #3 call relative to A6, for SuperBASIC.
Use BTRAP instead of QTRAP to get the effect of calling TRAP #4 directly.