The Programmer's Guide to TRSDOS Version 6 - Tim Mann's Home ...

ENTRY JR BEGIN ;Branch around linkage
STUFHI DW $-$ ;To contain last byte used
DB MODDCB-BEGIN-5 ;Calculate length of 'NAME'
DB 'MODNAME' ;Name of this module
MODDCB DW $-$ ;To contain DCB pointer for module
DW 0 ;Reserved by the DOS
BEGIN EQU $
;*=*=*
; Actual module code start
;*=*=*
JR C,WASGET ;Go if @GET request
JR Z,WASPUT ;Go if @PUT request
JR WASCTL ;Was @CTL request
At the entry of the driver, an absolute relative jump instruction executes which causes a
branch around some data. Ignore, for a moment, the header data which is discussed in the
Chapter 8, appendix. At the label "BEGIN", a test is made on the CARRY FLAG. If the CARRY
was set, then it must have been the result of an input request (@GET). Thus, an input
request could be directed to that part of the module which handles character INPUT.
If the request was not from the @GET primitive, the CARRY will not be set. The next test
is if the ZERO FLAG is set. The ZERO condition prevailed when an @PUT primitive was the
initial request. Thus the jump to WASPUT can transfer to that part of the module that
deals specifically with character OUTPUT.
If neither the ZERO nor CARRY flags are set, the routine falls through to the next
instruction, a jump to WASCTL - that part of the module that would handle @CTL requests.
Obviously, the module code that handles @CTL requests could be placed immediately after
the first two tests thereby obviating the need for the "JR WASCTL". Some modules are
written to assume that @CTL requests are to be handled exactly like @PUT requests
although this is not recommended. The processing of @CTL requests is entirely up to the
function of the driver and the author thereof with the exception that the author should
not deviate from the functions identified in the @CTL INTERFACING section. When a device
has been routed to a disk file, the DOS will ignore @CTL requests. That is, the @CTL
codes will not be written to the disk file. The functions of @CTL requests are covered as
a separate topic later in this chapter.
3.5.3 Device Driver/Filter Return Codes
One last topic needs to be discussed relating to drivers - the subject of register
handshaking conventions. On @GET requests, the character input should be placed in the
accumulator. On output requests (either @PUT or @CTL), the character is obtained from
register C. It is extremely important for drivers and filters to observe return codes.
Specifically, if the request is @GET and no byte is available, the driver returns an NZ
condition with the accumulator containing a zero (i.e. OR 1 : LD A,0 : RET). If a byte is
available, the byte is placed in the accumulator and the Z-flag is set (i.e. LD A,CHAR :
CP A : RET). If there is an input error, the error code is returned in the accumulator
and the Z-flag is reset (i.e. LD A,ERRNUM : OR A : RET). On output requests, the Z-flag
is set if no output error occurred. The accumulator may be loaded with the character that
was output; however, applications invoking an @PUT cannot depend on the accumulator
containing the output character on return from the SVC - the character will, however,
still be contained in the C register! In the case of an output error, the accumulator
must be loaded with the error code and the Z-flag reset as shown above.
3.5.4 Filter Interfacing
A filter module is inserted between the DCB and driver routine (or between the DCB and
the current filter when applied to a DCB already filtered). The application of insertion
is performed by the DOS FILTER command once the filter module is resident and associated
3-11