This document should be read in conjunction with :
1. Checking that COMMS LINK is installed 2. Opening and closing the RS232 port 3. RS232 Control signals 4. Examples using handshaking lines 5. Programming considerations
First check that the COMMS LINK software has been loaded - i.e. COMMS is in the top-level menu. If COMMS LINK is not installed, any program which calls the machine code interface routines provided by COMMS LINK will crash.
This check can be performed in OPL as follows :
commsin%: rem return true if COMMS LINK installed onerr iserr:: xfeof: :rem try a harmless COMMS LINK function iserr:: return err<>203 : rem not installed if "missing proc" error
or in machine code :
bsr check_present bcs not_present bra is_present check_present: bsr 1$ ; PC relative LDX #XFEOF .ascic "XFEOF" ; leading count byte string 1$: pulx ; PC = address of "XFEOF" os dv$lkup ; if XFEOF not there, no COMMS LINK rts ; see tech. ref. manual
Before accessing the RS232 port, the program must first call the COMMS LINK machine code interface routine RS$OPEN. This indicates that the RS232 port is now in use.
Example :
clrb ; Open for reading and writing jsr rst_entry_point .byte rs$open bcs error ; Deal with error ... ; Now free to access the port
RS$CLOSE should be called when the RS232 port is no longer needed.
; bit masks for rs$close turn_off_immed= 1 ; switch off immediately after close, else leave port on fail_if_busy= 2 ; fail with carry set if paused by XOFF, else ignore XOFF state, and close immediately
Example where port not closed while XOFF handshake:
close_type = fail_if_busy; don't close if busy handshaking, leave port switched on wait_busy: ldab,#close_type jsr rst_entry_point .byte rs$close bcs wait_busy; wait until XON
Straight close:
close_type = 0; ignore XOFF state, leave port switched on ldab,#close_type jsr rst_entry_point .byte rs$close
The COMMS LINK hardware provides the following RS232 control signals on the port POB_PORT2 (address $0003) :-
| Name | Top slot pin | Direction | PORT2 bit no | Set if: |
|---|---|---|---|---|
| RTS | 5 | input | 2 | correspondent busy |
| CTS | 6 | output | 0 | ORGANISER II busy |
| DSR | 4 | input | 1 | correspondent busy |
| DTR | - | linked to DSR | - | DSR set |
Note that DTR (normally an output) is merely linked to DSR and can not be driven by a program.
All bits are readable. See technical reference manual for details for POB_PORT2.
; Bit masks cts= 1 dsr= 2 rts= 4 ;Set CTS to indicate ORGANISER II busy oim #cts,POB_PORT2:
Example:
;Clear CTS to indicate ORGANISER II ready for input aim #^C cts,POB_PORT2: ; note (1) = $FE
Example:
;Wait on both RTS and DSR wait: tim #rts!dsr,POB_PORT2: bne wait
Example: OPL/Machine code for controlling the RTS line directly:
global rtshigh%(2),rtslow%(2),a% rtshigh%(1)=$71fe rtshigh%(2)=$0339 rtslow%(1)=$7201 rtslow%(2)=$0339 rem to assert (raise) the rts line a%=usr%(addr(rtshigh%()),0) rem to de-assert (lower) the rts line a%=usr%(addr(rtslow%()),0)
In between a call to RS$OPEN and a call to RS$CLOSE, programmers should look out for the following operating system routines :-
Routines which access packs :
These turn off the RS232 port, until the next call to COMMS LINK. This is normally no problem, unless a program tries to access POB_PORT2 after a call to one of the above routines but before another COMMS LINK call. The RS232 port should then be turned on by calling RS$OPEN again, as follows :
Example : no problem here
os FL$OPEN ...; RS232 now off jsr rst_entry_point .byte rs$getchar; or similar COMMS LINK function ... tim #cts,POB_PORT2; test the cts line
Example: this is a BUG
os PK$SETP ... ; RS232 now off tim #cts,POB_PORT2; test the cts line
Example: corrected version of above
os PK$SETP ;Re-open the RS232 port, to switch it on ldab,#opened_with ; use value originally supplied to RS$OPEN andb,#^XFE ; but with bit 0 clear to indicate that jsr rst_entry_point ; the handshaking state is not to be reset .byte rs$open ... tim #cts,POB_PORT2 ; now ok to access port
Other routines whose behaviour is altered while the RS232 port open:
DO NOT CALL :
The keyboard interrupt service routine is altered so that interrupts remain enabled while the keyboard is being scanned. This gives RS232 interrupts a higher priority than keyboard interrupts.