




                                       
                                       
                                       
                                       
                                       
                                       
                                       
                                       
                                       
                                       
                                       
                                       
                                       
                                       
				   FossComm
                                       
                                 version 0.04
                                       
                                       
                                August 22, 1988
                                       
                                       
                             Program Documentation
                                       
                                       
                                       
                                       
                                       
                    Copyright (C) 1988  Daan van der Weide
                              All rights reserved
                                       









































         

           FosComm is an  interface between a  compiled BASIC  program
         and a so-called FOSSIL  driver. It enables  the user to  take
         advantage of all  the functions  regarding the  communication
         ports, from a BASIC  program. In this way  it is possible  to
         avoid the problems/shortcomings  of the BASIC  communications
         handler.

           FossComm is based on  the document 'Fundamentals of  FOSSIL
         implementation and use, draft  version 5, February 11,  1988'
         by Rick Moor. Please make sure that your fossil driver  meets
         this draft.


           FossComm can be used with any of the following compilers :

                MicroSoft Quickbasic 1.00, 2.00, 3.00 and 4.00, 6.00
                IBM BasCom           1.00, 2.00


         LICENSE AND REGISTRATION
         ------------------------

           FossComm is distributed  as a  'shareware' program.  Please
         help me get it known by giving away unmodified copies of  the
         program and documentation to other people, either by  copying
         the disk  or making  it available  for downloading  on a  BBS
         system.

           FossComm is copyright (C) 1988 by Daan van der Weide. It is
         not public domain or free software. Non-registered users  are
         granted a limited license  to use FossComm  on a trial  basis
         for determining  whether  or not  it  is suitable  for  their
         needs. Registration allows  the use of  FossComm in  programs
         for sale and/or distribution.

           The registration fee is 50 guilders (25 US$). Users who pay
         the registration  fee will  be sent  a disk  woth the  latest
         version and documentation ans some example programs.

           It  is  also  possible  to  obtain  the  source  codes  for
         FossComm. In that case the  registration fee is 100  guilders
         (50 US$).

           Register your usage of FossComm by sending the registration
         fee to :

                        Daan van der Weide
                        Kastelenstraat 229-3
                        1082 EG  Amsterdam
                        the Netherlands

                        telephone : (0)20 463647

           Your  comments  regarding  the  FossComm  program  or   any
         suggestions you  have for  extensions or  for other  programs
         that would be useful to you are welcome.

         ------------------------------------------------------------
         FossComm                   page 2                    FossComm
         










           Daan van der Weide makes no warranties whatsoever regarding
         the FossComm computer program or the documentation.


         USING FOSSCOMM IN YOUR PROGRAMS
         -------------------------------

           The FossComm  module contains  a number  of functions  that
         handle the access of  RS232 communication boards as  provided
         by a driver conform the FOSSIL standard.

           Below follows a  list of  the functions  supported and  the
         parameters that should be specified, as well as the  eventual
         return values. To incorporate the module within your compiled
         program specify  the  name  FOSSCOMM.OBJ  when  linking  your
         program. Example :

           LINK MYPROG+FOSSCOMM,MYPROG;


         CREDITS
         -------

           I would like to mention a few people who have supported and
         still are supporting the development :

           Ronald Koridon who adapted RBBS 16.1a to run using FossComm
         and who is my primary 'guinea-pig'; Arjen Lentz, John Janssen
         sysops that are using the RBBS 16.1a FOSSIL version as  well.
         the RBBS version as well  to run. (they've probably  upgraded
         by now ...)


         FEEDBACK
         --------

           As you  may know,  any software  developer depends  on  his
         users to  modify, adjust  and extend  his product.  Therefore
         I'm very  interested  in  all  comments,  notes  and  critics
         towards the  FossComm product.  I can  be reached  either  by
         telephone or, better, at the RBBS system listed below.  Thank
         you very much !

                              RBBS Gaasperdam (4 lines)
                              sysop Ronald Koridon
                              Amsterdam, the Netherlands

                              31  (0)20 978493  node 1
                                        913890  node 2
                                        974420  node 3
                                        972763  node 4








         ------------------------------------------------------------
         FossComm                   page 3                    FossComm
         










         
         Revision                                              history
         ----------------

         v0.01

                This is the first alpha-test version only released  to
         people involved in testing.


         v0.02

                Extended FOSSIL calls  implemented to access  keyboard
         and to do video I/O etc. Not released.


         v0.03

                Adaptions according  to  draft 5  are  made.  FOSSPEED
         changed, so that parity, databits and the number of  stopbits
         may be specified as well. The documentation is extended,  and
         a number of functions was added.

         v0.04

                I think  the product  is solid  enough to  release  it
         generally, especially because there's 'official' RBBS support
         for FossComm. A number of BBS  systems are running for a  few
         months now without any problems.






























         ------------------------------------------------------------
         FossComm                   page 4                    FossComm
         










         
         -------------------------------------------------------------
         FOSINIT
         -------------------------------------------------------------

         PURPOSE :

           Initializes the  FOSSIL  driver,  and  checks  whether  the
         FOSSIL driver is  installed. This function  should be  called
         before any other FOS  calls are made. DTR  is raised by  this
         call. The baudrate is NOT set by this call.


         FORMAT  :

           FOSINIT(port%, result%)


         RETURNS :

           0    no error, driver initialized
          -1    error initializing driver


         EXAMPLE :

           100 PORT% = 1
           110 CALL FOSINIT(PORT%,RESULT%)
           120 IF RESULT% = -1 THEN PRINT "ERROR INITIALIZING FOSSIL"


         REMARKS :

           The number of the comport  that may be initialized  depends
         on the particular  FOSSIL driver you're  using. Refer to  the
         documentations of your driver for the values.

           Should a second call to  this function occur, all  buffers,
         flow-contol parameters etc. are reset to their initial  state
         and no error is returned.


         -------------------------------------------------------------
         FOSEXIT
         -------------------------------------------------------------

         PURPOSE :

           This function should be called whenever the  communications
         port in  no longer  needed. No  FOS calls  to the  particular
         comport can be made anymore once this call has been made. DTR
         is not affected by this call.


         FORMAT  :

           FOSEXIT(COMPORT%)


         ------------------------------------------------------------
         FossComm                   page 5                    FossComm
         










         -------------------------------------------------------------
         FOSSPEED
         -------------------------------------------------------------

         PURPOSE :

           Sets  the  baudrate   and  the   additional  line   control
         parameters for  the communication  port. If  a  non-supported
         baudrate is specified,  the baudrate variable  is set to  -1,
         and no call to the FOSSIL drive is made.


         FORMAT  :

           FOSSPEED(comport%, speed%, parity%, databits%, stopbits%)

           where speed% can be one of the following :

           300,600,1200,2400,4800,9600,19200,38400

           parity% can be :

           0  for    no parity
           1  for   odd parity
           2  for    no parity
           3  for  even parity

           databits% can be :

           0  for     5 databits
           1  for     6 databits
           2  for     7 databits
           3  for     8 databits

           stopbits% can be :

           0  for     1 stopbit
           1  for    1 stopbit if databits% = 0 i.e. 5 bits or
                      2 stopbits for all other values for databits%.


         RETURNS :

           speed% is set to -1  if an illegal baudrate was  specified,
         otherwise speed% is not affected.














         ------------------------------------------------------------
         FossComm                   page 6                    FossComm
         










         -------------------------------------------------------------
         FOSTXCHAR
         -------------------------------------------------------------

         PURPOSE :

           Transmits a character using the specified port. If  there's
         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.


         FORMAT  :

           FOSTXCHAR(comport%, char%, result%)


         REMARKS :

           For the values  of the result%  parameter, please refer  to
         the description of the FOSSTATUS function.


         -------------------------------------------------------------
         FOSRXCHAR
         -------------------------------------------------------------

         PURPOSE :

           If there's a character available in the receive buffer, the
         character will be returned.  When no character is  available,
         it will wait until one becomes available.


         FORMAT  :

           FOSRXCHAR(comport%, char%, result%)


         REMARKS :

           For the values  of the result%  parameter, please refer  to
         the description of the FOSSTATUS function.
















         ------------------------------------------------------------
         FossComm                   page 7                    FossComm
         










         -------------------------------------------------------------
         FOSSTATUS
         -------------------------------------------------------------

         PURPOSE :

           Requests status information about the state of the comport.


         FORMAT  :

           FOSSTATUS(comport%, status%)

           status bits returned are :

           15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00      mask
           -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
              XX XX          XX XX XX          XX
               |  |           |  |  |           |
               |  |           |  |  |           |
               |  |           |  |  |           + bit is always set
               |  |           |  |  |
               |  |           |  |  +----- Carrier Detect       &H0080
               |  |           |  |
               |  |           |  +-------- Input data available &H0100
               |  |           |
               |  |           +----------- RX buffer overrun    &H0200
               |  |
               |  +----------------------- Room available       &H2000
               |
               +-------------------------- Output buffer empty  &H4000


         -------------------------------------------------------------
         FOSDTR
         -------------------------------------------------------------

         PURPOSE :

           Raises or lowers the DTR signal on the specified comport.


         FORMAT  :

           FOSDTR(comport%, state%)

           state% can be :

           0  to indicate that DTR should be lowered
           1  to indicate that DTR should be raised









         ------------------------------------------------------------
         FossComm                   page 8                    FossComm
         










         -------------------------------------------------------------
         FOSTXFLUSH
         -------------------------------------------------------------

         PURPOSE :

           Forces the transmission  of all  characters that  currently
         are in  the transmit  buffer. The  function does  not  return
         until all characters are transmitted !!!


         FORMAT  :

           FOSTXFLUSH(comport%)


         -------------------------------------------------------------
         FOSTXPURGE
         -------------------------------------------------------------

         PURPOSE :

           This function purges all pending characters in the transmit
         buffer. Any characters not transmitted are discarded.


         FORMAT  :

           FOSTXPURGE(comport%)


         -------------------------------------------------------------
         FOSRXPURGE
         -------------------------------------------------------------

         PURPOSE :

           Purges the receive  buffer. Any input  data in the  receive
         buffer is discarded.


         FORMAT  :

           FOSRXPURGE(comport%)















         ------------------------------------------------------------
         FossComm                   page 9                    FossComm
         










         -------------------------------------------------------------
         FOSTXCHARNW
         -------------------------------------------------------------

         PURPOSE :

           This function is similar to the FOSTXCHAR function,  except
         that if  the  driver is  unable  to buffer  the  character  -
         because the  transmit  buffer  is full  -  the  call  returns
         immediately indicating the success of the call in the result%
         parameter.


         FORMAT  :

           FOSTXCHARNW(comport%, char%, result%)

           result% can be :

           0  if the character could *NOT* be transmitted
           1  if the character was transmitted


         -------------------------------------------------------------
         FOSREADAHEAD
         -------------------------------------------------------------

         PURPOSE :

           Peeks into  the receive  buffer and  returns the  character
         that will  be  returned  upon the  next  FOSRXCHAR  call,  or
         returns -1 if the receive buffer is empty.


         FORMAT  :

           FOSREADAHEAD(comport%, char%)

           char% is -1  if the receive buffer is empty




















         ------------------------------------------------------------
         FossComm                   page 10                   FossComm
         










         -------------------------------------------------------------
         FOSFLOWCTL
         -------------------------------------------------------------

         PURPOSE :

           Enables or disables the  flow control on the  transmission.
         Two kinds of flow control are supported :

           15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
           -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
                                   XX XX XX XX XX XX XX XX
                                   FORCED HIGH  |  |  |  |
                                                |  |  |  |
                                                |  |  |  +-- Xon/Xoff
                                                |  |  |      on
                                                |  |  |      transmit
                                                |  |  |
                                                |  |  +----- CTS/RTS
                                                |  |
                                                |  +-------- DSR/DTR
                                                |
                                                +----------- Xon/Xoff
                                                             on
                                                             receive

           When the  corresponding  bit  is set,  that  type  of  flow
         control is enabled.  Applications should set  the upper  four
         bits in the lower nibble as well, i.e. bits 4, 5, 6 and 7.

           When the  bit is  cleared,  that type  of flow  control  is
         disabled.

           Enabling Xon/Xoff on transmission will suspend transmission
         upon receiving  an Xoff  character.  The FOSSIL  drives  will
         resume transmission as soon as an Xon character is received.

           Enabling CTS/RTS,  will suspend  transmission when  CTS  is
         lowered. As soon as CTS  is raised, transmission is  resumed.
         The FOSSIL driver will drop RTS whenever a certain amount  of
         the receive buffer is filled.  As soon as the receive  buffer
         contains less characters  than the predetermined  percentage,
         RTS is raised again.

           Enabling DSR/DTR,  will suspend  transmission when  DSR  is
         lowered. As soon as DSR  is raised, transmission is  resumed.
         The FOSSIL driver will drop DTR whenever a certain amount  of
         the receive buffer is filled.  As soon as the receive  buffer
         contains less characters  than the predetermined  percentage,
         RTS is raised again.

           Enabling Xon/Xoff on receive, will cause the FOSSIL  driver
         to send an Xoff  character whenever a  certain amount of  the
         receive buffer is filled. An  Xon character will be sent,  as
         soon as the receive buffer contains less characters than  the
         predetermined percentage.



         ------------------------------------------------------------
         FossComm                   page 11                   FossComm
         










         FORMAT  :

           FOSFLOWCTL(comport%, state%)


         EXAMPLES :

           state% is :

           &H00F0 to disable all flow control types
           &H00F1 to enable Xon/Xoff on transmission
           &H00F2 to enable CTS/RTS
           &H00F4 to enable DSR/DTR
           &H00F8 to enable Xon/Xoff on reception


         -------------------------------------------------------------
         FOSCTRLCK
         -------------------------------------------------------------

         PURPOSE :

           Enables/disables extended  Ctrl-C/Ctrl-K  checking,  and/or
         enables/disables the transmitter.


           15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
           -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
                                                     XX XX
                                                      |  |
                                                      |  +--- CtrlCK
                                                      |
                                                      +------ TX

           Bit 0 controls whether the extended Ctrl-K/Ctrl-C  checking
         is enabled  (bit  set)  or  disabled (bit  not  set).  Bit  1
         controls whether the  transmitter is  active or  not, in  the
         same way Xon/Xoff characters do affect the transmitter.

           If the  extended  Ctrl-C/Ctrl-K checking  is  enabled,  any
         subsequent call to this this routine will return an  internal
         flag maintained by the FOSSIL driver, that indicates  whether
         Ctrl-C/Ctrl-K has  been  pressed.  When  enabled,  the  Ctrl-
         C/Ctrl-K character does *NOT* appear in the receive buffer.


         FORMAT  :

           FOSCTRLCK(comport%, state%)


         EXAMPLES :

           COMPORT% = 1
           STATE% = &H0001
           FOSCTRLCK(COMPORT%, STATE%)
           IF STATE% AND &H0001 THEN PRINT "CTRL-C/CTRL-K RECEIVED"


         ------------------------------------------------------------
         FossComm                   page 12                   FossComm
         










         -------------------------------------------------------------
         FOSWDOG
         -------------------------------------------------------------

         PURPOSE :

           Enables or disables 'watchdog' processing. When watchdog is
         enabled, the state of  the carrier detect  (DCD) line on  the
         particular comport is constantly monitored, and whenever  the
         signal drops, i.e. the connection is terminated the system is
         rebooted. This option is  typically used in combination  with
         external  programs   shelled  from   a  main   program.   The
         FOSINIT/FOSEXIT calls do *NOT* affect this monitoring.

         FORMAT  :

           FOSWDOG(comport%, state%)

           state% = 1 to enable the watchdog process
           state% = 0 to disable the watchdog process


         -------------------------------------------------------------
         FOSBOOT
         -------------------------------------------------------------

         PURPOSE :

           Boots the  system.  This  function  enables  a  program  to
         perform either a soft- or a warmboot.


         FORMAT  :

           FOSBOOT(type%)

           type% = 0  for a 'cold'start (incl. POST & memory tests)
           type% = 1  for a 'warm'start (only DOS reboots)





















         ------------------------------------------------------------
         FossComm                   page 13                   FossComm
         










         -------------------------------------------------------------
         FOSREAD
         -------------------------------------------------------------

         PURPOSE :

           Read a block of data from the receive buffer. The number of
         characters  actually  transferred  is  put  into  the  BYTES%
         variable after the call.


         FORMAT  :

           FOSREAD(comport%, bytes%, buffer$)


         EXAMPLE :

           '
           'create a 32 byte buffer
           '
           BUF$="12345678901234567890123456789012"
           '
           PORT%  = 1
           BYTES% = 32
           '
           CALL FOSREAD(PORT%, BYTES%, BUF$)
           '
           PRINT "BYTES READ : ";BYTES%
           PRINT "DATA READ  : ";LEFT$(BUF$,BYTES%)





























         ------------------------------------------------------------
         FossComm                   page 14                   FossComm
         










         -------------------------------------------------------------
         FOSWRITE
         -------------------------------------------------------------

         PURPOSE :

           Write a block of data to the transmit buffer. The number of
         characters  actually  transferred  is  put  into  the  BYTES%
         variable after the call.


         FORMAT  :

           FOSWRITE(comport%, bytes%, buffer$)


         EXAMPLES :

           '
           'create some string
           '
           BUF$="Welcome to MailPro !"+CHR$(10)+CHR$(13)
           '
           PORT%  = 1
           BYTES% = LEN(BUF$)
           '
           CALL FOSWRITE(PORT%, BYTES%, BUF$)
           '
           PRINT "BYTES WRITTEN : ";BYTES%


         -------------------------------------------------------------
         FOSBREAK
         -------------------------------------------------------------

         PURPOSE :

           Starts or ends the transmission of a break state.


         FORMAT  :

           FOSBREAK(comport%, state%)

           state% = 1 to start a break
           state% = 0 to end a break













         ------------------------------------------------------------
         FossComm                   page 15                   FossComm
         










         -------------------------------------------------------------
         FOSTIMERTICK
         -------------------------------------------------------------

         PURPOSE :

           This function returns information  about the current  timer
         interrupt. It returns the interrupt number the timer is  tied
         to, the  number  of  ticks  per second,  and  the  number  of
         milliseconds per tick.


         FORMAT  :

           FOSTIMERTICK(Intno%, Ticks%, Msecs%)


         -------------------------------------------------------------
         FOSSCANKEY
         -------------------------------------------------------------

         PURPOSE :

           Scans the keyboard  and returns the  next character in  the
         keyboard buffer. If no characters are available a value of -1
         will be returned.

           The values returned will match the IBM-style of keycoding.


         FORMAT  :

           FOSSCANKEY(Key%)


         -------------------------------------------------------------
         FOSGETKEY
         -------------------------------------------------------------

         PURPOSE :

           Returns the next  character in the  keyboard buffer. If  no
         characters are available, the functions waits until a key  is
         pressed.


         FORMAT  :

           FOSGETKEY(Key%)










         ------------------------------------------------------------
         FossComm                   page 16                   FossComm
         










         -------------------------------------------------------------
         FOSLOCATE
         -------------------------------------------------------------

         PURPOSE :

           Locates the cursor on the screen. The screen is treated  to
         have cordinates as follows :

         ( 0, 0)
                +---------------------------------------------+
                |                                             |
		|  Hello World, this is supposed to be a      |
		|  picture of a screen...		      |
                |                                             |
                |                                             |
                |                                             |
                |                                             |
                |                                             |
                +---------------------------------------------+
                                                               (24,79)

         FORMAT  :

           FOSLOCATE(Row%, Col%)


         -------------------------------------------------------------
         FOSGETLOC
         -------------------------------------------------------------

         PURPOSE :

           Returns the current position of the cursor.


         FORMAT  :

           FOSGETLOC(Row%, Col%)




















         ------------------------------------------------------------
         FossComm                   page 17                   FossComm
         










         -------------------------------------------------------------
         FOSDISPANSI
         -------------------------------------------------------------

         PURPOSE :

           Displays a character and  allows ANSI screen processing  to
         occur (if available). On DOS  machines the FOSSIL routine  to
         perform this function probably will call a DOS function to do
         the ANSI processing. Keep in  mind that DOS function are  not
         re-entrant. In such cases, this routine may not be assumed to
         be re-entrant either.


         FORMAT  :

           FOSDISPANSI(Char%)


         -------------------------------------------------------------
         FOSDISPBIOS
         -------------------------------------------------------------

         PURPOSE :

           Displays a charactes using the system BIOS. This means that
         DOS output redirection does not  work when this call is  used
         to produce screen output.


         FORMAT  :

           FOSDISPBIOS(Char%)


























         ------------------------------------------------------------
         FossComm                   page 18                   FossComm
         
