back : next : content =

5.2.3 ** I/O Trap #3


iob.test IO.PEND 3 / 0  
Test for pending Input
  IN:   OUT:  
A1 A1 smashed
ERR.EF -10

iob.fbyt IO.Fbyte 1 / 3  
Fetch a byte
  IN:   OUT:  
D1 fetched byte
A1 smashed
ERR.EF -10
D1 (mostly) remains unchanged after an error.

iob.flin IO.FLINE 3 / 2  
fetches a line of characters delimited by <NL> to a buffer
  IN:   OUT:  
D1.W count of received characters
D2.W length of buffer
A1 address of buffer A1 Ptr beyond last character
ERR.EF -10
Timeout valid until completion of the entire process - re IO.EDLIN.
With CON channels the characters will be echoed to screen and can be editted.
A delimiting <NL> which lead to termination is included in the D1 count word.
D1 remains unchanged if an error occurred, or returns with the until then fetched number of characters being accumulated (ERR.NC).

iob.fmul IO.FSTRG 3 / 3  
 fetches a String
  IN:   OUT:  
D1 (s. IO.FLINE) D1.W Anzahl received character 
D2.W length of buffer
A1 address of buffer A1 Ptr beyond last character
ERR.EF -10

iob.elin IO.EDLIN 3 / 4  
editting a line (CON_ only) 
  IN:    OUT:  
D1 Cursor.W | line length.W D1 Cursor.W | line length.W
D2.W length of buffer
A1 Ptr to line end A1 Ptr to line end
The string may not contain any <NL> characters.
<CTRL/J>, <ENTER>, Cursor up or Cursor down are the input delimiting or output terminating characters.
MINERVA 1.97+ enable wrapped multiple lines editting, where only <ENTER> or <CTR/J> will terminate.
D1.hi.w refers to where the string display shall beginn;
the delimiting character does not count for the string length.
The timeout if non zero and not endless spans the entire editting process, i.e. the call will terminate after timing out regardless of the string actually being editted.

iob.sbyt IO.Sbyte 3 / 5  
Send a byte
  IN:   OUT:  
D1.B byte to send D1 smashed
A1 A1 smashed
ERR.DF -11
error messages do not include data buffering (slaving, etc).

iob.suml IOB.SUML 3 / 6 SQ only 
Send a group character, always un-TRAnslated
iob.smul IO.SSTRG 3 / 7  
Send a group of characters 
  IN:   OUT:  
D1.W count of chars sent
D2.W no. of characters D2
A1 start of buffer A1 new pointer to buffer
ERR.DF -11
IOB.SUML is available only with the SQ systems, data sent with this trap call will not be modified by the TRA settings.
The same feature, in an improved manner, can be assigned to any QDOS compliant system (JM+ tested) by the SIMSER extension. JM or any predecessors, anyway, would need some extension code to enable the output character TRAnslation.

iow.xtop SD.EXTOP 3 / 9  
screen handler extending Operation 
  IN:   OUT:  
D0 error code
D1 parameter D1 return parameter
D2 dto.
A1 dto. A1 return parameter
A2 Ptr to handler routine
Executes the subroutine where A2 points to as if it were part of the screen handler,
with the register settings:
  IN:   OUT:  
D0 error code
D1 input data D1 return data
D2 input data
A0 Base of channel parameters
A1 input data A1 return data
A3 handler base address (CH.LXINT)
A6 base adress of system variables
A0 points to 24 bytes "below" the 1st standard CON/SCR channel parameter, SD.XMIN, regardless whether the PIF (or any other extension) installed or not.
ERR.xx   freely (within reasonable limits) selectable

ow.pixq SD.PXENQ 3 / 10  
fetch pixel raster window sizes and cursor position
iow.chrq SD.CHENQ 3 / 11  
fetch character raster window sizes and cursor position 
  IN:   OUT:  
A1 Ptr to buffer A1 smashed
return data in buffer
0(A1) width of window
2(A1) height
4(A1) horizontal cursor posn w.r.t. top left origin
6(A1) vertical

iow.defb SD.BORDR 3 / 12  
set border width and colour
  IN:   OUT:  
D1.B colour D1 smashed
D2.W width
Cursor set to the top left origin.
D1 = 128 = $80 preserves old colour, which after width D2 = 0 will be set to black.

iow.defw SD.WDEF 3 / 13  
re-defining a window
  IN:   OUT:  
D1.B border colour D1 smashed
D2.W border width
A1 Ptr to data block A1 smashed
Screen content unmodified, cursor set to top left origin.
Data block with
0(A1) width
2(A1) height
4(A1) left origin
6(A1) top origin

iow.ecur SD.CURE 3 / 14  
activate cursor 
iow.dcur SD.CURS 3 / 15  
 disable cursor
  IN:   OUT:  
D1 smashed
A1 smashed

iow.scur SD.POS 3 / 16  
 Set cursor to character position
  IN:   OUT:  
D1.W column D1 smashed
D2.W line
A1 smashed
ERR.OR -4 Position out of window
Position unchanged if an error occurs.

iow.scol SD.TAB 3 / 17  
Set cursor to column on current line.
  IN:   OUT:  
D1.W  column D1 smashed
A1 smashed
ERR.OR -4 Position out of window
Releases pending <NL>s.

iow.newl SD.NL 3 / 18  
Cursor to new line - sequence CR LF
iow.pcol SD.PCOL 3 / 19  
Cursor one character back
iow.ncol SD.NCOL 3 / 20  
Cursor to next column
iow.prow SD.PROW 3 / 21  
Cursor one line up
iow.nrow SD.NROW 3 / 22  
Cursor one line down
  IN:   OUT:  
D1 smashed
A1 smashed
ERR.OR -4 Position out of window (not for SD.NL)

iow.spix SD.PIXP 3 / 23  
Set cursor to pixel position
  IN:   OUT:  
D1.W X co-ordinate D1 smashed
D2.W Y co-ordinate
A1 smashed
ERR.OR -4 Position out of window
Releases pending <NL>s.

iow.scra SD.SCROL 3 / 24  
Scroll entire window
iow.scrt SD.SCRTP 3 / 25  
Scroll part of window on top of cursor line
iow.sceb SD.SCRBT 3 / 26  
Scrollt part of window below cursor line
  IN:   OUT:  
D1.W no. of horizontal pixel lines D1 smashed
A1 smashed
D1 +ve to scroll upwards (top lines disappearing).
Cursor position remains unchanged.

iow.pana SD.PAN 3 / 27  
shift window contents
iow.panl  SD.PANLN 3 / 30  
shift content of cursor row
iow.panr SD.PANRT 3 / 31  
shift row content to right of cursor
  IN:   OUT:  
D1.W  no. of vertical pixel lines D1 smashed
A1 smashed
D1 +ve shifting to the right.

iow.clra SD.CLEAR 3 / 32  
Clear window content
iow.clrt SD.CLRTP 3 / 33  
Clear window on top of cursor row
iow.clrb SD.CLRBT 3 / 34  
Clear window below cursor row
iow.clrl  SD.CLRLN 3 / 35  
Clear cursor line
iow.clrr SD.CLRRT 3 / 36
Clear cursor line to the right of cursor
  IN:   OUT:  
D1 smashed
A1 smashed
 ERR.NC -1

iow.font SD.FOUNT 3 / 37  
Pass ptr(s) to a windows character fount
  IN:   OUT:  
D1 smashed 
A1 Ptr to 1st character fount  A1 smashed 
A2 Ptr to 2nd character fount
A1 and/or A2 := 0 to restore predefined ROM founts.

iow.rclr SD.RECOL 3 / 38  
recolour window appearance
  IN:   OUT:  
D1 smashed
A1 ptr to table of new colours A1 smashed
The new colours will be expected in the table where A1 points to, at positions corresponding to the QDOS colour numbers, one byte for the eight colours, each.

iow.spap SD.SETPA 3 / 39  
colour for PAPER 
iow.sstr SD.SETST 3 / 40  
colour for STRIP 
iow.sink  SD.SETIN 3 / 41  
colour for INK 
  IN:   OUT:  
D1.B colour
D2 SQ: smashed
A1 smashed

iow.sfla SD.SETFL 3 / 42  
 Set blink mode (MODE 8 only)
  IN:   OUT:  
D1.B  =/=0 bink D1 smashed
A1 smashed

iow.sula SD.SEUFL 3 / 43  
 Set understrike mode.
  IN:   OUT:  
D1.B  =/=0 understrike D1 smashed
A1 smashed

iow.sova SD.SETMD 3 / 44  
 Set character display mode 
  IN:   OUT:  
D1.W type -1, 0 or 1 D1 smashed
(as SBasic: OVER) A1 smashed

iow.ssiz SD.SETSZ 3 / 45  
 character sizes einstellen
  IN:   OUT:  
D1.W character width D1 smashed
D2.W character height
A1 smashed
Width and height as with the SBasic command CSIZE.

iow.blok SD.FILL 3 / 46  
draw a coloured rectangle
  IN:   OUT:  
D1.W colour D1 smashed
A1 Ptr to Block definition A1 smashed
block definition:
0(A1) block width in Pixel.
2(A1) height 
4(A1) left origin of block w.r.t. to window origin
6(A1) top origin SD.POINT 3 / 48  
Draw a point in the scaled graphics system 
  IN:   OUT:  
D1 smashed
A1 arithmetik stack A1 smashed
The required parameters of the scaled graphics traps are expected as floating point numbers in a stack area of at least 40 items, pointed to by A1.

Stacked parameters:

00(A1) Y co-ordinate
06(A1) X

iog.line SD.LINE 3 / 49  
Draw a line in the scaled graphics system
Parameters as SD.POINT
 00(A1) Y end co-ordinate 
 06(A1) X 
$0C(A1) Y start co-ordinate
$12(A1) X

iog.arc  SD.ARC 3 / 50  
Draw an arc (circle segment) in the scaled graphics system
Parameters as SD.POINT
$00(A1) angle that the arc spans, w.r.t. to virtual circle centre
$06(A1) Y end co-ordinate
$0C(A1) X
$12(A1) Y start co-ordinate
$18(A1) X

iog.elip SD.ELIPS 3 / 51  
Draw an ellipse (circle) in the scaled graphics system
Parameters as SD.POINT
$00(A1) angle of main achsle w.r.t. to horizontal
$06(A1) length of secondary achsle
$0C(A1) relation of main : secondary achsle
$12(A1) Y centre co-ordinate
$18(A1) X

iog.scal SD.SCALE 3 / 52  
Set scale and origin of the scaled graphic co-ordinates 
Parameters as SD.POINT
$00(A1) Y co-ordinate graphics origin displacement w.r.t. bottom left
$06(A1) X
$0C(A1) window's scaled height measure

iog.fill SD.FLOOD 3 / 53  
Enable filling of concave closed areae
  IN:   OUT:  
D1.L flag D1 smashed
A1 smashed
D1 = 0 disables, D1 = 1 (re-)enables.
The area will be filled with the colour as set for INK.
D1 is also supposed to pass the address of an alternative filling routine - which is not always implemented reliably (ROM dependent)!

iow.sgcr SD.GCUR 3 / 54  
Relate graphic cursor to the pixel raster
Parameters as SD.POINT
$00(A1) graphic X co-ordinate
$06(A1) Y
$0C(A1) pixel displacement to the right
$12(A1) bottom disp.

  SD.ROP 3 / 61  
  SD.DOT 3 / 62  
  SD.LIN 3 / 63  
Names reserved, though no documented usage {4}.

iof.chek FS.CHECK 3 / 64  
check a file channel for pending processing
  IN:   OUT:  
D1 smashed
A1 smashed
ERR.NC -1 if work on file and/or slave blocks not (yet) finished.

iof.flsh FS.FLUSH 3 / 65  
Send all slave blocks of a file, discard slave blocks
  IN:   OUT:  
D1 smashed
A1 smashed
Recommended operation to safely terminate any files transfer.
Might be unsafe with certain LV2/TK2 versions.

iof.posa FS.POSAB 3 / 66  
Set file access pointer
iof.posr FS.POSRE 3 / 67  
Advance file access pointer
  IN:   OUT:  
D1 (signed) new position D1 actual file position
A1 smashed
ERR.NC -1 
ERR.EF -10
If D1 points beyond either limit the pointer will be set to the nearest bound.
file pointer advanced by signed D1 value, in either direction.
D1:=0 can be used to just read the file access pointer.
Relative positioning should be done in integer increments, only, if any MDV files might be involved.

iof.minf FS.MDINF 3 / 69  
fetch information about data storage medium
  IN:   OUT:  
D1.hi.w Free Sectors
D1.lo.w good Sectors
A1 Ptr to 10 bytes A1 Ptr beyond name
name buffer A2 smashed
A3 smashed
SQ {15}: A2/A3 preserved

iof.shdr FS.HEADS 3 / 70  
(Re-)Set file header - may be unsafe with certain TK2 versions
  IN:   OUT:  
D1.W length set
A1 Ptr to header data A1 ptr to after header data
The trap call will (re-)set the leading 14 bytes of the file header concerned.
Re {3.5.1} for file header structure.

Serial channels will receive an additional leading byte $FF.
For modification of the file date re FS.DATE.

iof.rhdr FS.HEADR 3 / 71  
Read file header read.
  IN:   OUT:  
D1.W  length received
D2.W buffer length
A1 Ptr to buffer A1 Ptr beyond data
Fetches up to 64 bytes (plus a leading byte $ff for serial channels) to the buffer, the maximum of which depends on the device structure concerned.
Some QDOS systems will also set the file pointer to Zero.

iof.load FS.LOAD 3 / 72  
Fetch any amount of consecutive data to memory FS.SAVE 3 / 73  
  Send any amount of consecutive data from memory
  IN:   OUT:  
D1 smashed
D2 file length
A1 Ptr to data area A1 end address after loading/saving
D3 should be set to -1, for safe operation.
A1 should be an even address, and D2 an even length value.
This trap, despite rarely being an efficient choice, is usually badly implemented, in most systems (SQ inclusive!) and thus should only be used to load/save an entire file. The returned pointer is not always safe!.


With Toolkit II or MINERVA:

iof.rnam FS.RENAME 3 / 74  
File rename - TK, MINERVA
  IN:   OUT:  
D1 smashed
A1 Ptr to new Name  A1 smashed
Only MINERVA will leave the file update entry unchanged.
Newly opened files cannot be renamed.

iof.trnc FS.TRUNC 3 / 75  
Truncate file at current access pointer position.
  IN:   OUT:  


Additional calls with Level 2 device handler (TK, GoldCard, SQ):
  FS.DATE 3 / 76  
read/enter update or backup date
  IN:   OUT:  
D1 -1: read D1 date set
  0: current date
number: date in seconds 
D2.B   0: Update
  2: Backup
Re CDISK for an example using the QDOS clock, instead.

iof.mkdr FS.MKDR 3 / 77  
Modify empty(!) file to type "directory" 
  IN:   OUT:  
D1 0
D3.W -1

iof.vers FS.VERS 3 / 78  
read/enter 6-bit number file version
  IN:   OUT:  
D1 0 read, D1 current access count
>0 new count
-1 read and increment by one
A newly entered access count will remain unchanged until FLUSH and CLOSE.

This trap is also the Thor computers "watermark" (whatever that might be) {SNG}.

iof.xinf FS.XINF 3 / 79  
Fetch extended media information
  IN:   OUT:  
A1 Ptr 64 bytes data buffer A1 unchanged
Media data im buffer:  
IOI.NAME 00 .w count.w 
02 .b 20 *  Name of data storage medium
IOI.DNAM 22 $16 .w   count.w
24 $18 .b   4 * up to 4 characters device name
IOI.DNUM 28 $1c .b drive number
IOI.RDON 29 $1d .b =/= 0 write protected (not QXL)
IOI.ALLC 30 $1e .w size of one allocation unit
IOI.TOTL 32 $20 number of allocation units
IOI.FREE 36 $24 number of free allocation units
IOI.HDRL 40 $28 length of (physiscal) file header
IOI.xxxx 44 $2c .b 20 * bytes $ff filling up to length = 64
extended data block {15}:
IOI.FTYP 44 $2c .b format type 1:QDOS, 2:PC-DOS
IOI.STYP 45 $2d .b format version
IOI.DENS 46 $2e .b density 
IOI.MTYP 47 $2f .b Medium 0:RAM 1:FLP 2:HD 3:CD
IOI.REMV 48 $30 .b =/= 0 for removable media
IOI.xxxx 49 $31 .b 15 * $ff filling bytes

{15} says:
"The error free executable FS.XINF call grants for the Level-02 handler presence...

(some old versions) TK2 bug:
The trap might fetch 100 bytes to the buffer!

IOI.RDON related settings and system reactions on attempts to writing to a write protected medium are not reliable, at all. Files "saved" can even appear in the directory.

With "SYSTEM" {Schiemann} only:

iof.attr IOF.ATTR 3 / 80  
Set/Clear File-Attribute(s), "SYSTEM" 
  IN:   OUT:  
D1.W toggle D1 smashed
D2.B attribute(s) D2 smashed
D1=0 clear attribute
D1=/= 0 set attribute
Attributes in D2.B:
  Bit set
7 write protection
6 filename visibility
0-5 user number
111111 with D1:=0 for user 0
Files set to attribute 0 can be used as standard (this is the file headers "access" byte),
those with user-no. 0 can always be read and written to, any other files are accessible according to the attributes only if the currently set system user is the same as noted in the attribute/access byte.
The "super user" only, requiring an additional password, can re-define the current system user number.

SYSTEM by and for SQ was rendered useless because of the undocumented use of a system variable which previously was announced to and, according to JS, accepted by the SQ maintainers as being required for "system". - On sufficient demand (only!) this could be fixed in a fairly Tebby-proof manner, pse, give me a notice..


  top : back : next : content