Fundamentals of FOSSIL implementation and use

                        Version 5,  February 11,  1988

                       Rick Moore,  Solar Wind Computing
                          FidoNet Address:  1:115/333





                 FidoNet Standards Committee index:  FSC-0015

                 This document supersedes/obsoletes: FSC-0008



















 Copyright (C) 1987, VEP Software, Naugatuck, CT 06770. All rights reserved.
 Copyright (C) 1988, Rick Moore,  Homewood,  IL, 60430. All rights reserved.

 This document may be freely used or copied by anyone interested in the data
 contained herein. No fees may be charged for distribution of this document.
 You will be held  accountable for all such charges,  and expected to either
 reimburse those persons or organizations so charged,  or to make a donation
 in the exact amount of those fees to the International FidoNet Association,
 to  assist  them in their  efforts to  advance the  technology of  personal
 computer telecommunications.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Introduction                                                          Page 2



 A. Objectives of this document

    This document is directed at implementors or intellectuals.  It is meant
    for use in implementing applications that can use FOSSIL drivers, or for
    details needed to implement a new FOSSIL. As such it won't always go out
    of its way to explain itself to the neophyte.

    This document will have served its purpose to you if you are able to use
    the data contained within to perform either of the above tasks.   If you
    feel  that necessary  data has  been omitted  please contact  Rick Moore
    at the above listed address so that the  appropriate changes can be made.
    Any lines changed in the current version are marked with "|" in the left
    margin.


 B. Historical perspective

    For those people who were not lucky enough to have an IBM PC or a system
    nearly completely compatible, the world has not been very friendly. With
    his implementation of the Generic Fido(tm) driver,  Tom Jennings made it
    possible for systems that had nothing in common with an IBM PC except an
    808x-class processor, and the ability to run MS-DOS Version 2 and above,
    to run his Fido(tm) software. That was a lot to ask, and a lot of people
    thought it was enough.

    But not everyone.  While Thom Henderson was debugging Version 4.0 of his
    SEAdog(tm) mail package,  an "extended" Generic driver was designed  (in
    cooperation with Bob Hartman)   as a quick kludge to help him get past a
    problem with certain UART chips.The new hook was quickly pounced upon by
    Vince Perriello,  who, with almost DAILY prodding (ouch! it still hurts)
    by Ken Kaplan,had been working with Henderson to get DEC Rainbow support
    into SEAdog. Vince then coded a driver to use this hook and - Voila! -
    SEAdog 4.0 started working like a champ on the Rainbow.

    At the same time something was rotten in the state of Texas. Wynn Wagner
    started  encountering some serious  difficulties in his Opus development
    effort. Specifically, he couldn't force the Greenleaf(tm) Communications
    Libraries to behave in exactly the way he felt Opus required.  Enter Bob
    Hartman.Having already enjoyed success in the effort with Thom Henderson,
    he suggested to Wynn that with very few extensions,  any driver that was
    already  SEAdog(tm) 4.0 compatible could drive Opus as well.  About that
    time, Vince called Wynn to discuss porting Opus to the DEC Rainbow. Wynn
    called Bob, Bob called Vince, and the FOSSIL driver came into existence.

    FOSSIL is an acronym for "Fido/Opus/SEAdog Standard Interface Layer". To
    say that the concept has gained wide acceptance in the FidoNet community
    would be an understatement. Henk Wevers' DUTCHIE package uses the FOSSIL
    communications services.   Ron Bemis' OUTER package uses FOSSIL services
    for everything it does and as a result it is completely generic.   There
    are already FOSSIL implementations for the Tandy 2000, Heath/Zenith 100,
    Sanyo 555 and other "non-IBM" architectures. With each new 'port' of the
    spec, the potential of a properly coded FOSSIL application grows!


Fundamentals of FOSSIL implementation and use                       FSC-0015
Basic conventions and calling method                                  Page 3



 C. Basic principles of a FOSSIL driver

    1)  Interrupt 14h.

    The one basic rule that the driver depends upon,  is the ability for ANY
    target machine to allow the vector for INT 14h (usually pointing to BIOS
    comm functions) to be "stolen" by the driver.  In a system where the INT
    14h vector is used already, it must be possible to replace the "builtin"
    functionality with that of a FOSSIL,  when an application that wants the
    use of a FOSSIL is to be run on the target machine.


    2)  How to install a FOSSIL driver in a system

    There's no hard and fast way to do this. The FOSSIL might be implemented
    as part of a device driver (like Ray Gwinn's X00.SYS) and therefore gets
    loaded using a line in CONFIG.SYS at bootup time.  It might be done as a
    TSR (terminate and stay resident) program, in which event you install it
    by running the program  (DECcomm by Vince Perriello and Opus!Comm by Bob
    Hartman work this way, for example).


    3)  How an application can detect the presence of a FOSSIL

    The driver has a "signature" that can be used to determine whether it is
    present in memory. At offset 6 in the INT 14h service routine is a word,
    1954h,  followed  by a  byte that  specifies the maximum function number
    supported by the driver. This is to make it possible to determine when a
    driver is present and what level of functionality it provides. Also, the
    Init call (see below)  returns a 1954h  in AX.  SEAdog(tm)  looks at the
    signature and Opus just goes for the Init. Fido doesn't do either.


    4)  How to call a FOSSIL function

    The FOSSIL driver  is entered  by issuing  a software Interrupt 14h from
    the application  program. The code corresponding to the desired function
    should be in 8-bit register AH. For calls that relate to communications,
    the port number will be passed from the application in register DX. When
    DX contains a zero (0) it signifies use of COM1, or whatever the "first"
    serial port on your machine is called. A one (1) in DX points the driver
    at COM2, and so on.  A value of 00FFh in DX is considered a special case
    where the driver  should do no actual processing but return SUCCESS.  In
    the specific case of Init/Uninit with DX=00FFh,the FOSSIL should perform
    all non-communications  processing  necessary  with such calls.  In some
    machines  (H/Z-100 for example),  the FOSSIL must  assume control of the
    keyboard in order to service the keyboard functions.

    FOR ALL FUNCTIONS,  ALL REGISTERS NOT SPECIFICALLY CONTAINING A FUNCTION
    RETURN VALUE MUST BE PRESERVED ACROSS THE CALL.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                              Page 4


D. Functions currently defined for FOSSILs


    AH = 00h    Set baud rate

            Parameters:
                Entry:  AL = Baud rate code
                        DX = Port number
|               Exit:   AX = Port status (see function 03h)

    This works the same as the  equivalent IBM PC BIOS call,  except that it
    ONLY selects a baud rate.  This is passed in the high order 3 bits of AL
    as follows:

                010 =   300 baud
                011 =   600  ''
                100 =  1200  ''
                101 =  2400  ''
                110 =  4800  ''
                111 =  9600  ''
                000 = 19200  '' (Replaces old 110 baud mask)
                001 = 38400  '' (Replaces old 150 baud mask)

    The low order 5 bits can be implemented or not by the FOSSIL, but in all
    cases, if the low order bits of AL are 00011,  the result should be that
    the communications device should be set to eight data bits, one stop bit
    and no parity. This setting is a  MINIMUM REQUIREMENT  of Fido, Opus and
    SEAdog.  For purposes of completeness,  here are the IBM PC "compatible"
    bit settings:

    Bits 4-3 define parity:     0 0       no parity
                                1 0       no parity
                                0 1      odd parity
                                1 1     even parity

    Bit 2 defines stop bits:      0        1 stop bit;
                                  1      1.5 bits for 5-bit char;
                                           2 for others

    Bits 1-0 character length:  0 0        5 bits
                                0 1        6 bits
                                1 0        7 bits
                                1 1        8 bits


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                              Page 5


    AH = 01h    Transmit character with wait

            Parameters:
                Entry:  AL = Character
                        DX = Port number
                Exit:   AX = Port status (see function 03h)

    AL contains the character to be sent.   If there is room in the transmit
    buffer the return will be immediate,  otherwise it will wait until there
    is room to store the character in the transmit buffer.  On return, AX is
    set as in a status request (see function 03h).


    AH = 02h    Receive character with wait

            Parameters:
                Entry:  DX = Port number
                Exit:   AH = 00h
                        AL = Input character

    If there is a character  available in the  receive buffer,  returns with
    the next character in AL.  It will wait until a character is received if
    none is available.


    AH = 03h    Request status

            Parameters:
                Entry:  DX = Port number
                Exit:   AX = Status bit mask (see below)

    Returns with the line and modem status in AX.  Status bits returned are:

            In AH:
                Bit 0 = RDA  - input data is available in buffer
|               Bit 1 = OVRN - the input buffer has been overrun.  All
|                              characters received after the buffer is
|                              full should be discarded.
                Bit 5 = THRE - room is available in output buffer
                Bit 6 = TSRE - output buffer is empty

            In AL:
|               Bit 3 = Always 1 (always return with this bit set to 1)
                Bit 7 = DCD  - carrier detect

    This can be used by the application to determine  whether carrier detect
    (CD) is set,  signifying the presence/absence of a remote connection, as
    well as monitoring both the input and output buffer status.  Bit 3 of AL
    is always returned set to enable programs to use it as a carrier detect
    bit on hardwired (null modem) links.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                              Page 6


    AH = 04h    Initialize driver

            Parameters:
                Entry:  DX = port number
                      ( BX = 4F50h
|                       ES:CX = ^C flag address --- optional )
                Exit:   AX = 1954h if successful
|                       BL = maximum function number supported
|                            (not counting functions 7Eh and above)
|                       BH = rev of FOSSIL doc supported

    This is used to tell the driver to begin  operations,  and to check that
    the driver is installed. This function should be called before any other
    communications calls are made.  At this point all interrupts involved in
    supporting the comm port (specified in DX) should be set up for handling
    by  the  FOSSIL, then  enabled.  If BX contains 4F50h,  then the address
    specified in ES:CX is that of a ^C flag byte in the application program,
    to be incremented when  ^C is detected in the keyboard service routines.
    This is an optional service and only need be supported on machines where
    the keyboard service can't (or won't) perform an INT 1Bh or INT 23h when
|   a Control-C is entered.  DTR is raised by this call.  The baud rate must
|   NOT be changed by this call.

    NOTE: Should an additional call to this service occur  (2 Inits or Init,
    Read,Init, etc.) the driver should reset all buffers, flow control, etc.
    to the INIT state and return SUCCESS.


    AH = 05h    Deinitialize driver

            Parameters:
                Entry:  DX = Port number
                Exit:   None

    This is used to tell the driver that comm port operations are ended. The
    function should be called  when no more comm port functions will be used
    on the port specified in DX.  DTR is NOT affected by this call.


    AH = 06h    Raise/lower DTR

            Parameters:
                Entry:  DX = Port number
                        AL = DTR state to be set (01h = Raise, 00h = Lower)
                Exit:   None

    This function is used to control the DTR line to the modem. AL = 00h means
    lower DTR (disable the modem), and AL = 01h means to raise DTR (enable the
    modem).  No other function (except Init) should alter DTR.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                              Page 7


    AH = 07h    Return timer tick parameters

            Parameters:
                Entry:  None
                Exit:   AL = Timer tick interrupt number
                        AH = Ticks per second on interrupt number in AL
                        DX = Approximate number of milliseconds per tick

    This is used to  determine the parameters of the timer tick on any given
    machine.  Three numbers are returned:

        AL =   Timer tick interrupt number
        AH =   Ticks per second on interrupt number shown in AL
        DX =   Milliseconds per tick (approximate)

    Applications can use this for critical timing  (granularity of less than
    one second) or to set up code  (such as a watchdog)  that is executed on
    every timer tick. See function 16h (add/delete function from timer tick)
    for the preferred way of actually installing such code.


    AH = 08h    Flush output buffer

            Parameters:
                Entry:  DX = Port number
                Exit:   None

    This is used to force any pending output.   It does not return until all
    pending output has been sent.  You should use this call with care.  Flow
    control  (documented below)  can make your system hang on this call in a
    tight uninterruptible loop under the right circumstances.


    AH = 09h    Purge output buffer

            Parameters:
                Entry:  DX = Port number
                Exit:   None

    This is used to purge any pending output.   Any output data remaining in
    the output buffer (not transmitted yet) is discarded.


    AH = 0Ah    Purge input buffer

            Parameters:
                Entry:  DX = Port number
                Exit:   None

    This is used to purge any pending input.   Any input data which is still
    in the buffer is discarded.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                              Page 8


    AH = 0Bh    Transmit no wait

            Parameters:
                Entry:  DX = Port number
                Exit:   AX = 0001h - Character was accepted
                           = 0000h - Character was not accepted

    This is exactly the same as the "regular"  transmit call, except that if
    the driver is  unable to  buffer the character  (the buffer is full),  a
    value of 0000h is returned in AX. If the driver accepts the character
    (room is available),  0001h is returned in AX.


    AH = 0Ch    Non-destructive read-ahead

            Parameters:
                Entry:  DX = Port number
                Exit:   AH = 00h           - Character is
                        AL = Next character    available
                        AX = FFFFh         - Character is not available

    Return in AL the next character in the receive buffer.  If the receive
    buffer is empty,  return  FFFFh.  The  character  returned  remains in
    the receive buffer. Some applications call this "peek".


    AH = 0Dh    Keyboard read without wait

            Parameters:
                Entry:  None
                Exit:   AX = IBM-style scan code (Character available)
                           = FFFFh               (Character not available)

    Return in  AX the  next character  (non-destructive read ahead)  from the
    keyboard; if nothing is currently in the keyboard buffer, return FFFFh in
    AX.   Use IBM-style  function  key mapping  in the high order byte.  Scan
    codes for non-"function" keys  are not specifically required,  but may be
    included. Function keys return 00h in AL and the "scan code" in AH.


    AH = 0Eh    Keyboard read with wait

            Parameters:
                Entry:  None
                Exit:   AX = IBM-style scan code

    Return in AX the next character from the keyboard;  wait if no character
    is available. Keyboard mapping should be the same as function 0Dh.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                              Page 9


    AH = 0Fh    Enable or disable flow control

            Parameters:
                Entry:  AL = Bit mask describing requested flow control
                        DX = Port number
                Exit:   None

    TRANSMIT flow control allows the "other end" to restrain the transmitter
    when you are  over-running it.  RECEIVE flow control tells the FOSSIL to
    attempt to do just that if it is being overwhelmed.

    Two kinds of basic flow control are supported:

                Bit 0 = 1       Xon/Xoff on transmit
                Bit 1 = 1       CTS/RTS (CTS on transmit, RTS on receive)
                Bit 2           Reserved
|               Bit 3 = 1       Xon/Xoff on Receive

    Flow control is enabled, or disabled, by setting the appropriate bits in
    AL  for the types of flow control we want to ENABLE (value = 1),  and/or
    DISABLE  (value = 0),  and calling this function.  Bit 2 is reserved for
    DSR/DTR,  but is not currently supported in any implementation.

    Enabling  transmit  Xon/Xoff will cause the FOSSIL  to stop transmitting
    upon receiving an Xoff.  The FOSSIL will resume transmitting when an Xon
    is received.

    Enabling CTS/RTS will cause the FOSSIL to cease transmitting when CTS is
    lowered.  Transmission will resume  when CTS is raised.  The FOSSIL will
    drop RTS when the receive buffer reaches a predetermined percentage full
    The FOSSIL will  raise RTS  when the  receive buffer  empties below  the
    predetermined  percentage full.  The  point(s)  at which  this occurs is
    left to the individual FOSSIL implementor.

|   Enabling receive  Xon/Xoff will cause the FOSSIL to send a Xoff when the
|   receive buffer reaches a pre-determined percentage full.  An Xon will be
|   sent when the receive buffer empties below the pre-determined percentage
|   full. The point(s) at which this occurs is left to the individual FOSSIL
|   implementor.

    Applications  using this  function  should set all bits  ON  in the high
    nibble of AL as well.  There is a compatible  (but not identical) FOSSIL
    driver implementation that uses the  high nibble as a control mask.   If
    your application sets the high nibble to all ones,  it will always work,
    regardless of the method used by any given driver.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                             Page 10


    AH = 10h    Extended Control-C / Control-K checking and transmit on/off

            Parameters:
                Entry:  AL = Bit mask (see below)
                        DX = Port number
                Exit:   AX = 0001h - Control-C/K has been received
                           = 0000h - Control-C/K has not been received

    This is used for BBS  operation,  primarily.  A bit mask is passed in AL
    with the following flags:

                Bit 0   Enable/disable Control-C / Control-K checking
                Bit 1   Disable/enable the transmitter

    The Enable (bit 0 = 1) and Disable (Bit 0 = 0) Control-C/Control-K check
    function is meant primarily for BBS use. When the checking is enabled, a
    Control-C or Control-K received  from the communications port will set a
    flag internal to the FOSSIL driver,  but will not be stored in the input
    buffer. The next use of this function will return the value of this flag
    in register AX then clear the flag for the next occurrence. The returned
    value is used by the BBS  software to determine whether output should be
    halted or not.

    The Disable (Bit 1 = 1) and Enable (Bit 1 = 0) Transmitter function lets
    the application restrain the asynchronous driver from output in much the
    same way as XON/XOFF would.


    AH = 11h    Set current cursor location.

            Parameters:
                Entry:  DH = Row (line)
                        DL = Column
                Exit:   None

    This function looks exactly like like INT 10h, subfunction 2, on the IBM
    PC. The cursor location is passed in DX: row in DH and column in DL. The
    function treats the screen as a coordinate  system whose origin (0,0) is
    the upper left hand corner of the screen.


    AH = 12h    Read current cursor location.

            Parameters:
                Entry:  None
                Exit:   DH = Row (line)
                        DL = Column

    Looks exactly like INT 10h,  subfunction 3,  on the IBM PC.  The current
    cursor location  (using the same coordinate  system as  function 16h) is
    passed back in DX.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                             Page 11


    AH = 13h    Single character ANSI write to screen.

            Parameters:
                Entry:  AL = Character to display
                Exit:   None

    The character in AL is sent to the screen by the fastest method possible
    that allows ANSI processing to occur (if available). This routine should
    not be used in such a way that DOS output  (which is not re-entrant) can
    not be employed by some FOSSIL driver to perform the function  (in fact,
    on the IBM PC that is likely to be how it's done).  On some systems such
    as the DEC Rainbow this will be a very fast method of screen writing.


    AH = 14h    Enable or disable watchdog processing

            Parameters:
                Entry:  AL = 01h - Enable watchdog
                           = 00h - Disable watchdog
                        DX = Port number
                Exit:   None

    When watchdog is enabled,   the state of the carrier detect (CD) line on
    the comm port specified in DX should be constantly monitored. Should the
    state of that line become FALSE (carrier lost), the system should be re-
    booted, to enable the BBS (or other application) to start up again. This
    monitor is not affected by Init/Uninit etc.


    AH = 15h    Write character to screen using BIOS support routines

            Parameters:
                Entry:  AL = Character to display
                Exit:   None

    The character in AL is sent to the screen using  BIOS-level Input/Output
    routines. This differs from function 13h in that DOS I/O CAN NOT be used,
    as this function might be called from driver level.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                             Page 12


    AH = 16h    Insert or delete a function from the timer tick chain

            Parameter:
                Entry:  AL = 01h - Add a function
                           = 00h - Delete a function
|                       ES = Segment of function
                        DX = Offset of function
                Exit:   AX = 0000h - Operation successful
                           = FFFFh - Operation unsuccessful

    This function is used to allow a  central authority  to manage the timer
    interrupts, so that as code is loaded and unloaded, the integrity of the
    "chain" is not compromised.  Rather than using the traditional method of
    saving the old contents of the timer vector, storing the address of your
    routine there,  and executing a far call to the "old" routine when yours
    is done, instead you call this function. It manages a list of such entry
    points and calls them on a timer tick (interrupt) using a FAR call.  All
    the usual cautions about making DOS calls apply (that is, DON'T!).

    This makes it possible for a program to get in and out of the tick chain
    without having to know whether another program has also done so since it
    first insinuated itself.   At least 4 entries should be available in the
    driver's table (including one to be used by Watchdog if implemented that
    way).


    AH = 17h    Reboot system

            Parameters:
                Entry:  AL = 00h - "Cold boot"
                           = 01h - "Warm boot"

    Perform the old 3-finger salute.  Used in extreme emergency by code that
    can't seem to find a "clean" way out of the trouble it has gotten itself
    into.  Hopefully it won't happen while you're computing something in the
    other half of a DoubleDOS system. If your machine can make a distinction
    between a "cold" (power-up, self-test and boot) and a "warm" (just boot)
    bootstrap,  your FOSSIL should support the flag in AL. Otherwise just do
    whatever bootstrap is possible.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                             Page 13


|   AH = 18h    Read block (transfer from FOSSIL to user buffer)

|           Parameters:
|               Entry:  CX = Maximum number of characters to transfer
|                       DX = Port number
|                       ES = Segment of user buffer
|                       DI = Offset into ES of user buffer
|               Exit:   AX = Number of characters actually transferred

|   A "no-wait"  block read of 0 to FFFFh characters from the FOSSIL inbound
|   ring buffer to the calling routine's buffer. ES:DI are left unchanged by
|   the call; the count of bytes actually transferred will be returned in AX.


|   AH = 19h    Write block (transfer from user buffer to FOSSIL)

|           Parameters:
|               Entry:  CX = Maximum number of characters to transfer
|                       DX = Port number
|                       ES = Segment of user buffer
|                       DI = Offset into ES of user buffer
|               Exit:   AX = Number of characters actually transferred


|   A  "no-wait"  block  move of 0  to FFFFh  characters  from  the  calling
|   program's  buffer into  the  FOSSIL outbound ring buffer. ES:DI are left
|   unchanged by the call;  the count of bytes actually transferred  will be
|   returned in AX.


|   AH = 1Ah    Break begin or end

|           Parameters:
|               Entry:  AL = 01h - Start sending 'break'
                           = 00h - Stop sending 'break'
|                       DX = port number
|               Exit:   None

|   Send a break signal to the modem. If AL=01h the driver will commence the
|   transmission of a break.  If AL=00h the driver will end the break.  This
|   is useful for communications with devices that can only go into 'command
|   mode' when a BREAK is received. Note: the application is responsible for
|   the timing of the BREAK.  Also,  if the FOSSIL has been restrained by an
|   Xoff received from the modem, the flag will be cleared.   An Init or Un-
|   Init will stop an in-progress BREAK.


Fundamentals of FOSSIL implementation and use                       FSC-0015
Communications functions                                             Page 14


|   AH = 1Bh    Return information about the driver

|           Parameters:
|               Entry:  CX = Size of user info buffer in bytes
|                       DX = Port number
|                       ES = Segment of user info buffer
|                       DI = Offset into ES of user info buffer
|               Exit:   AX = Number of bytes actually transferred

|   Transfer information about the driver and its current status to the user
|   for use in determining,  at the application level, limits of the driver.
|   Designed to assist  "generic" applications  to adjust to "foreign" gear.

|   The data structure currently returned by the driver is as follows (sorry
|   but you'll have to live with assembly syntax):

|       info    equ     $               ; define begin of structure
|       strsiz  dw      info_size       ; size of the structure in bytes
|       majver  db      curr_fossil     ; FOSSIL spec driver conforms to
|       minver  db      curr_rev        ; rev level of this specific driver
|       ident   dd      id_string       ; "FAR" pointer to ASCII ID string
|       ibufr   dw      ibsize          ; size of the input buffer (bytes)
|       ifree   dw      ?               ; number of bytes left in buffer
|       obufr   dw      obsize          ; size of the output buffer (bytes)
|       ofree   dw      ?               ; number of bytes left in the buffer
|       swidth  db      screen_width    ; width of screen on this adapter
|       sheight db      screen_height   ; height of screen    "     "
|       baud    db      ?               ; ACTUAL baud rate, computer to modem
|       info_size equ $-info

|   The ident string should be  null-terminated,  and NOT contain a newline.
|   The baud rate byte contains the bits that  Function 00h would use to set
|   the port to that speed.

|   The fields related to a particular port (buffer size,  space left in the
|   buffer,  baud rate) will be undefined if port FFh  or an invalid port is
|   contained in DX.

|   Additional information will always be passed after these,  so that,  for
|   example, offset "sheight" will never change with FOSSIL revision changes.


Fundamentals of FOSSIL implementation and use                       FSC-0015
"Layered Application" services                                       Page 15 



|   The functions below are not necessarily FOSSIL related. However, because
|   dispatchers  that support them are hooked on Interrupt 14H,  it behooves
|   the FOSSIL developer to support them as well to avoid fragmenting memory
|   with several dispatchers.



|   AH = 7Eh    Install an "external application" function

|           Parameters:
|               Entry:  AL = Code assigned to external application
|                       DX = Offset of application entry point
|                       ES = Segment of application entry point
|               Exit:   AX = 1954h
|                       BL = Code assigned to application (same as input AL)
|                       BH = 01h - Installation was successful
|                          = 00h - Installation failed

|   This call is used by external application code  (special screen drivers,
|   modem code, database code, etc) to link into the INT 14h service for use
|   by multiple applications. The "error return" (BH=0 with AX=1954h) should
|   mean that  another application layer has  already been installed at that
|   particular code. Codes 80h through BFh should be supported.

|   External application codes 80h-83h are  reserved by FOSSIL developers for
|   re-organizing FOSSIL services by type (comm, screen, keyboard, system).

|   Installed application code will be entered, via a FAR call, from the INT
|   14H dispatcher whenever it is entered with AH=(application code).

|   If the value returned in AX from this function is not 1954h, the service
|   code that is trying to be installed should bring up its own INT 14h code
|   that can service INT 14h functions 7h-BFh (80h-BFh are "applications").


|   AH = 7Fh    Remove an "external application" function

|           Parameters:
|               Entry:  AL = Code assigned to external application
|                       DX = Offset of application entry point
|                       ES = Segment of application entry point
|               Exit:   AX = 1954h
|                       BL = Code assigned to application (same as input AL)
|                       BH = 01h - Removal was successful
|                          = 00h - Removal failed

|   Removes an application's entry into the table.  Usually so it can remove
|   itself from memory. Error return means ES:DX did not match or that there
|   is no entry at the slot described by AL.

|   An application that wants to remove itself from memory can issue the  7F
|   function to remove itself from the table, then, if it is successful, get
|   out of memory. If it had to install itself with an INT 14h dispatcher it
|   may back itself out, provided no other applications  have been installed
|   on top of it (using its dispatcher).


Fundamentals of FOSSIL implementation and use                       FSC-0015
                                                                     Page 16



E.  Validation Suite.

    Well, there is one, but it's involved.   Here is a list of software that
    is known to use FOSSIL calls,  and the range of calls used by that
    software:

        Software package                        Fossil calls used

    Fido,  V11w,  generic version                  00h - 07h
    SEAdog,  V4.1b                                 00h - 0Eh
    Opus,  V1.03a                                  00h - 17h
    BinkleyTerm,  V1.30                            00h - 1Bh

    While  there is  certainly no  guarantee that your FOSSIL is bug-free if
    all the above software runs  with it,  you  have probably  done as  much
    as you  can in  a test environment if your FOSSIL is tested with each of
    these packages.



 F. Technical Discussion.

    A FOSSIL echomail conference exists,  for the purpose of exchanging info
    and implementation details for FOSSIL drivers.  It is coordinated by Ray
    Gwinn at FidoNet node 1:109/639.  Contact him for details on how to join.
    Keep in mind though,  that this conference is intended  SPECIFICALLY for
    implementors of FOSSIL  software and not as a general Q&A conference for
    people who think FOSSILs have something to do with paleontology.



G. Distribution Of This Document.

   This document may be distribute freely as long as it is  not  modified in
   any  way.  Please  list  all  changes  and  deviations  in a given FOSSIL
   implementation in an addendum contained in a  separate file added  to the
   FOSSIL archive.   Also,  please  do  not distribute this document without
   the accompanying version of FOSSIL.CHT.   This will help avoid confusion,
   among both FOSSIL implementors and application developers.