When calling the OSWORD routine from machine code you will need to use the absolute address &40F1. However, when CALLing this routine from BBC BASIC it is recommended that you use the BBC Micro-compatible address &FFF1.
The OSWORD routines operate in a similar manner to the OSBYTE routines except that instead of parameters being passed in via registers they are stored in a parameter block in RAM, the address of which is passed via the HL register pair.
The routine number is loaded into the Z80's accumulator register A. When CALLing the routine from BBC BASIC you will need to set A% to the routine number.
Parameters for the routine are stored in RAM. You will need to set the Z80 register pair HL to the address of this parameter block, which in BBC BASIC can be accomplished via the H% and L% static variables.
OSWORD &01 - Read system clock
This routine reads the relative system clock (used for the BASIC TIME function). It outputs a five-byte integer to the address in HL.
10 OSWORD=&FFF1 20 DIM time 4 30 H%=time/256:L%=time 40 A%=&01 50 CALL OSWORD 60 PRINT !time
OSWORD &02 - Write system clock
This routine sets the system clock to the five-byte integer value pointed to by HL.
OSWORD &09 - Read pixel value
This routine returns the colour of a pixel at a specified point on the screen in the same manner as thePOINT function.
The inputs are as follows:
- (HL+0) LSB of the X coordinate.
- (HL+1) MSB of the X coordinate.
- (HL+2) LSB of the Y coordinate.
- (HL+3) MSB of the Y coordinate.
- (HL+4) contains the colour (0-127) at the specified point or 255 (-1) if the specified point was off screen.
OSWORD &0D - Read last two graphics cursor positions
The host interface keeps track of the last two visited graphics cursor positions (triangle and parallelogram filling require three points; two remembered and one passed with the PLOT command). You can use this routine to retrieve these recorded positions. HL needs to point to eight bytes of memory to receive the following values:
- (HL+0) LSB of the previous X coordinate.
- (HL+1) MSB of the previous X coordinate.
- (HL+2) LSB of the previous Y coordinate.
- (HL+3) MSB of the previous Y coordinate.
- (HL+4) LSB of the current X coordinate.
- (HL+5) MSB of the current X coordinate.
- (HL+6) LSB of the current Y coordinate.
- (HL+7) MSB of the current Y coordinate.
The values returned are all absolute coordinates in relation to the top-left hand corner of the screen.
An example of the usage of this routine is shown below. It is an assembly program that can be used to retrieve the current graphics origin (set with VDU 29 command). It works by moving the graphics cursor to (0,0) then reading back the current cursor position.
10 REM OS call routine constants 20 OSWRCH=&40EE 30 OSWORD=&40F1 40 : 50 DIM GetOrigin 90 60 FOR pass%=0 TO 1 70 P%=GetOrigin 80 [ 90 OPT pass%*2 100 ; 110 ; Check there are 2 arguments 120 LD A,(IX+0) : CP 2 : RET NZ 130 ; 140 ; Check they are both integers 150 LD A,(IX+1) : CP 4 : RET NZ 160 LD A,(IX+4) : CP 4 : RET NZ 170 ; 180 ; MOVE to the origin by invoking VDU 25,5,0;0; 190 LD A,25 : CALL OSWRCH 200 LD A,5 : CALL OSWRCH 210 ; Output 4 zeroes to move to (0,0). 220 LD B,4 230 .lp XOR A : CALL OSWRCH : DJNZ lp 240 ; 250 ; Invoke OSWORD &0D to read last two cursor positions 260 LD HL,PrevX 270 LD A,&0D : CALL OSWORD 280 ; 290 ; Now we know the origin we need to output it. 300 LD L,(IX+2) : LD H,(IX+3) 310 LD DE,(CurrX) : CALL OutputCoord 320 LD L,(IX+5) : LD H,(IX+6) 330 LD DE,(CurrY) : CALL OutputCoord 340 RET 350 ; 360 ; 8 bytes of storage for cursor positions 370 .PrevX : DEFW 0 : .PrevY : DEFW 0 380 .CurrX : DEFW 0 : .CurrY : DEFW 0 390 ; 400 ; Outputs 16-bit value DE to 32-bit variable at HL 410 .OutputCoord 420 LD (HL),E : INC HL 430 LD (HL),D : INC HL 440 SLA D 450 SBC A,A 460 LD (HL),A : INC HL 470 LD (HL),A : RET 480 ] 490 NEXT pass%
The routine can now be CALLed to retrieve the current graphics origin:
VDU 29,48;-32; CALL GetOrigin,x%,y% PRINT "Origin = (";x%;",";y%;")"